From c368b59723d7585c6b85a3a71133586b7d94c9d6 Mon Sep 17 00:00:00 2001 From: christianmat Date: Fri, 25 Oct 2024 16:30:45 -0700 Subject: [PATCH] docs: refactor docs structure --- apps/docs/api-reference/events-create.mdx | 1 + apps/docs/api-reference/events-get.mdx | 2 + apps/docs/api-reference/overview.mdx | 9 ++- apps/docs/api-reference/queries-execute.mdx | 2 + apps/docs/api-reference/webhooks-create.mdx | 2 + apps/docs/api-reference/webhooks-delete.mdx | 2 + apps/docs/api-reference/webhooks-get.mdx | 2 + apps/docs/client.mdx | 11 ++- apps/docs/cloud-quickstart.mdx | 89 +++++++++++++++++++++ apps/docs/mint.json | 24 ++++-- apps/docs/quickstart.mdx | 4 +- apps/docs/self-host.mdx | 59 -------------- 12 files changed, 136 insertions(+), 71 deletions(-) create mode 100644 apps/docs/cloud-quickstart.mdx delete mode 100644 apps/docs/self-host.mdx diff --git a/apps/docs/api-reference/events-create.mdx b/apps/docs/api-reference/events-create.mdx index b054669..754acbb 100644 --- a/apps/docs/api-reference/events-create.mdx +++ b/apps/docs/api-reference/events-create.mdx @@ -4,6 +4,7 @@ description: Use `track`, `identify`, and `group` to send events to Trench. openapi: post /events --- +This endpoint requires your [public API key](/api-reference/overview#authentication). Trench is fully compatible with the [Segment Spec](https://segment.com/docs/spec/) schema. You can use the `track`, `identify`, and `group` methods to send events to Trench via the `/events` endpoint. diff --git a/apps/docs/api-reference/events-get.mdx b/apps/docs/api-reference/events-get.mdx index 71edbe4..cc30483 100644 --- a/apps/docs/api-reference/events-get.mdx +++ b/apps/docs/api-reference/events-get.mdx @@ -3,3 +3,5 @@ title: Get Events description: Get events based on a query openapi: get /events --- + +This endpoint requires your [private API key](/api-reference/overview#authentication). diff --git a/apps/docs/api-reference/overview.mdx b/apps/docs/api-reference/overview.mdx index 8a797e0..f21e3f2 100644 --- a/apps/docs/api-reference/overview.mdx +++ b/apps/docs/api-reference/overview.mdx @@ -1,5 +1,5 @@ --- -title: Overview +title: API Overview description: Overview of the Trench API --- @@ -25,6 +25,11 @@ The Trench API also supports webhooks, which allow you to receive real-time noti ### Authentication -The Trench API uses bearer token authentication to secure access to its endpoints. You will be issued a public api key and a private api key to use when making requests. The public key is used only in the [Events](./events-create) endpoint to send data to Trench. It is safe to expose this key to the public internet. +The Trench API uses bearer token authentication to secure access to its endpoints. You will be issued a **public api key** and a **private api key** to use when making requests. The public key is used only in the [Events](./events-create) endpoint to send data to Trench. It is safe to expose this key to the public internet. The private key is used on all other endpoints and should be kept secret. + + + **Note:** Do not use your private API key on public endpoints. Always use your public API key to + avoid unauthorized access and misuse. + diff --git a/apps/docs/api-reference/queries-execute.mdx b/apps/docs/api-reference/queries-execute.mdx index 016fd1d..aec2163 100644 --- a/apps/docs/api-reference/queries-execute.mdx +++ b/apps/docs/api-reference/queries-execute.mdx @@ -3,3 +3,5 @@ title: Execute Queries description: Overview of the Trench API openapi: post /queries --- + +This endpoint requires your [private API key](/api-reference/overview#authentication). diff --git a/apps/docs/api-reference/webhooks-create.mdx b/apps/docs/api-reference/webhooks-create.mdx index 9e32357..ce5e126 100644 --- a/apps/docs/api-reference/webhooks-create.mdx +++ b/apps/docs/api-reference/webhooks-create.mdx @@ -4,6 +4,8 @@ description: Create a new webhook. openapi: post /webhooks --- +This endpoint requires your [private API key](/api-reference/overview#authentication). + Once a webhook is created, events will be sent to it based on the criteria specified in the webhook. The data sent follows the [Event schema](/api-reference/events-get) and is sent as a JSON array in the POST request in the `data` field. Below is an example request body: diff --git a/apps/docs/api-reference/webhooks-delete.mdx b/apps/docs/api-reference/webhooks-delete.mdx index 5eb5924..a49f601 100644 --- a/apps/docs/api-reference/webhooks-delete.mdx +++ b/apps/docs/api-reference/webhooks-delete.mdx @@ -3,3 +3,5 @@ title: Delete Webhook description: Delete a webhook. openapi: delete /webhooks/{uuid} --- + +This endpoint requires your [private API key](/api-reference/overview#authentication). diff --git a/apps/docs/api-reference/webhooks-get.mdx b/apps/docs/api-reference/webhooks-get.mdx index 5262b5c..009c38f 100644 --- a/apps/docs/api-reference/webhooks-get.mdx +++ b/apps/docs/api-reference/webhooks-get.mdx @@ -3,3 +3,5 @@ title: Get Webhooks description: Get all webhooks under your account. openapi: get /webhooks --- + +This endpoint requires your [private API key](/api-reference/overview#authentication). diff --git a/apps/docs/client.mdx b/apps/docs/client.mdx index 02656f3..f25ea4b 100644 --- a/apps/docs/client.mdx +++ b/apps/docs/client.mdx @@ -1,4 +1,7 @@ -# Trench-JS Client Documentation +--- +title: JavaScript Client +description: Documentation for the Trench JavaScript client +--- ## Overview @@ -40,3 +43,9 @@ trench.track('test-event', { test: 'test-value', }) ``` + +Or to record a page view: + +```ts +trench.page() +``` diff --git a/apps/docs/cloud-quickstart.mdx b/apps/docs/cloud-quickstart.mdx new file mode 100644 index 0000000..ce09694 --- /dev/null +++ b/apps/docs/cloud-quickstart.mdx @@ -0,0 +1,89 @@ +--- +title: Cloud Quickstart +sidebarTitle: Cloud Quickstart +description: Send your first event to Trench Cloud +--- + +In this guide, we'll walk you through the process of sending your first event and reading it back using the Trench Cloud API. +The example uses the [Trench JavaScript client](https://github.com/trench-dev/trench-js), but the same can be achieved by calling the [Events API](https://docs.trench.dev/api-reference/events-create) directly. + + + + To get started with Trench Cloud, you need to request access from our [website](https://trench.dev?utm_campaign=cloud-quickstart). Once you have access, you will receive your API keys and other necessary credentials. + + + + First, you need to install the Trench JavaScript client using your favorite package manager: + + ```bash + npm install trench-js + ``` + + Alternatively, you can use the CDN version: + + ```html + + ``` + + + + + After installing the client, you need to initialize it with your API key. Replace `YOUR_API_KEY` and `YOUR_SERVER_URL` with the actual API key and server URL you received: + + ```javascript + const Trench = require('trench-js'); + + const trench = new Trench({ + publicApiKey: 'YOUR_PUBLIC_API_KEY', + serverUrl: 'YOUR_SERVER_URL' + }); + ``` + + + + + Now you can send a sample event to Trench Cloud. Here is an example of how to send an event: + + ```javascript + trench.track({ + userId: '550e8400-e29b-41d4-a716-446655440000', + event: 'ConnectedAccount', + properties: { + totalAccounts: 4, + country: 'Denmark' + } + }).then(response => { + console.log('Event sent successfully:', response); + }).catch(error => { + console.error('Error sending event:', error); + }); + ``` + + + + + You can verify that the event was received by querying the events endpoint. Use your private API key for this: + + ```bash + curl -i -X GET \ + -H "Authorization: Bearer private-YOUR_PRIVATE_API_KEY" \ + 'YOUR_SERVER_URL/events?event=ConnectedAccount' + ``` + + This will return a JSON response with the event that was just sent. + + + + +## Going Further + +Now that you've sent your first event, you can learn more about the many things you can do with Trench. + +## Related Resources + + + + + + + diff --git a/apps/docs/mint.json b/apps/docs/mint.json index 3121dd2..a000d43 100644 --- a/apps/docs/mint.json +++ b/apps/docs/mint.json @@ -45,19 +45,29 @@ "navigation": [ { "group": "Getting Started", - "pages": ["introduction", "quickstart", "client", "self-host"] + "pages": [ + "introduction", + "quickstart", + "cloud-quickstart", + "client", + "api-reference/overview" + ] + }, + { + "group": "Events API", + "pages": ["api-reference/events-create", "api-reference/events-get"] }, { - "group": "API", + "group": "Webhooks API", "pages": [ - "api-reference/overview", - "api-reference/events-create", - "api-reference/events-get", "api-reference/webhooks-get", "api-reference/webhooks-create", - "api-reference/webhooks-delete", - "api-reference/queries-execute" + "api-reference/webhooks-delete" ] + }, + { + "group": "Query API", + "pages": ["api-reference/queries-execute"] } ], "footerSocials": { diff --git a/apps/docs/quickstart.mdx b/apps/docs/quickstart.mdx index fa96def..d1086ed 100644 --- a/apps/docs/quickstart.mdx +++ b/apps/docs/quickstart.mdx @@ -1,6 +1,6 @@ --- -title: Quickstart Guide -sidebarTitle: Quickstart +title: Self-host Quickstart +sidebarTitle: Self-host Quickstart description: Get set up with Trench in less than 5 minutes --- diff --git a/apps/docs/self-host.mdx b/apps/docs/self-host.mdx deleted file mode 100644 index bf2a910..0000000 --- a/apps/docs/self-host.mdx +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Self-host Trench -sidebarTitle: Self-host -description: Host Trench on your own infrastructure ---- - -## Self-Hosting Trench - -Trench can be self-hosted on your own infrastructure using a single Docker image. The image comes bundled with both Clickhouse and Kafka and requires no additional dependencies. - -### Prerequisites - -To run the Trench Docker image, we recommend a system with the following specifications: - -- At least 4 CPU cores -- At least 8GB of RAM - -These specifications ensure optimal performance for your Trench instance. - -### Getting Started - -To start the server, first clone the Trench repository, navigate to the `apps/trench` directory. - -```bash -git clone https://github.com/frigadehq/trench -cd apps/trench -``` - -Next, create a `.env` file. You can use the example below as a template, but make sure to replace the placeholder values with your own: - -```bash -NODE_ENV=production -API_PORT=80 -API_HTTPS=false -CLICKHOUSE_USER=user -CLICKHOUSE_PASSWORD=password -CLICKHOUSE_DATABASE=default -CLICKHOUSE_HOST=clickhouse -CLICKHOUSE_PORT=8123 -KAFKA_BROKERS=kafka:9092 -KAFKA_TOPIC=trench_events -KAFKA_PARTITIONS=1 -PUBLIC_API_KEYS=my-public-api-key -PRIVATE_API_KEYS=my-private-api-key -``` - -You can now start the server in production mode with the following command. It may take a few minutes to start up: - -```bash -docker-compose up --build --force-recreate --renew-anon-volumes -d -``` - -Once the server is running, you can open up a browser and navigate to `http://localhost:80`. You should see the following message: - -``` -Trench server is running -``` - -You can now test out the system end to end by following the [Quickstart](/quickstart) guide.