feature(public,docs): new public website and docs

2024-11-13 21:15:46 +01:00
parent fc2a019e1d
commit a022cb4831
234 changed files with 9341 additions and 6154 deletions
--- a/apps/public/content/docs/api/export.mdx
+++ b/apps/public/content/docs/api/export.mdx
@@ -0,0 +1,177 @@
+---
+title: Export
+description: The Export API allows you to retrieve event data and chart data from your OpenPanel projects.
+---
+
+## Authentication
+
+To authenticate with the Export API, you need to use your `clientId` and `clientSecret`. Make sure your client has `read` or `root` mode. The default client does not have access to the Export API.
+
+Include the following headers with your requests:
+- `openpanel-client-id`: Your OpenPanel client ID
+- `openpanel-client-secret`: Your OpenPanel client secret
+
+Example:
+
+```bash
+curl 'https://api.openpanel.dev/export/events' \
+  -H 'openpanel-client-id: YOUR_CLIENT_ID' \
+  -H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
+```
+
+## Events
+
+Get events from a specific project within a date range.
+
+Endpoint: `GET /export/events`
+
+Parameters:
+- project_id (required): The ID of the project
+- event (optional): Filter by event name(s). Can be a single event or an array of events.
+- start (optional): Start date (format: YYYY-MM-DD)
+- end (optional): End date (format: YYYY-MM-DD)
+- page (optional, default: 1): Page number for pagination
+- limit (optional, default: 50, max: 50): Number of events per page
+- includes (optional): Additional fields to include in the response
+
+Example:
+
+```bash
+curl 'https://api.openpanel.dev/export/events?project_id=abc&event=screen_view&start=2024-04-15&end=2024-04-18' \
+  -H 'openpanel-client-id: YOUR_CLIENT_ID' \
+  -H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
+```
+
+### Query Parameters
+
+| Parameter | Type | Description | Example |
+|-----------|------|-------------|---------|
+| projectId | string | The ID of the project to fetch events from | `abc123` |
+| event | string or string[] | Event name(s) to filter | `screen_view` or `["screen_view","button_click"]` |
+| start | string | Start date for the event range (ISO format) | `2024-04-15` |
+| end | string | End date for the event range (ISO format) | `2024-04-18` |
+| page | number | Page number for pagination (default: 1) | `2` |
+| limit | number | Number of events per page (default: 50, max: 50) | `25` |
+| includes | string or string[] | Additional fields to include in the response | `profile` or `["profile","meta"]` |
+
+### Example Request
+
+```bash
+curl 'https://api.openpanel.dev/export/events?project_id=abc123&event=screen_view&start=2024-04-15&end=2024-04-18&page=1&limit=50&includes=profile,meta' \
+  -H 'openpanel-client-id: YOUR_CLIENT_ID' \
+  -H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
+```
+
+### Response
+
+```json
+{
+  "meta": {
+    "count": number,
+    "totalCount": number,
+    "pages": number,
+    "current": number
+  },
+  "data": Array<Event>
+}
+```
+
+## Charts
+
+Retrieve chart data for a specific project.
+
+### Endpoint
+
+```
+GET /export/charts
+```
+
+### Query Parameters
+
+| Parameter | Type | Description | Example |
+|-----------|------|-------------|---------|
+| projectId | string | The ID of the project to fetch chart data from | `abc123` |
+| events | string[] | Array of event names to include in the chart | `["sign_up","purchase"]` |
+| breakdowns | object[] | Array of breakdown configurations | `[{"name":"country"}]` |
+| interval | string | Time interval for data points | `day` |
+| range | string | Predefined date range | `last_7_days` |
+| previous | boolean | Include data from the previous period | `true` |
+| startDate | string | Custom start date (ISO format) | `2024-04-01` |
+| endDate | string | Custom end date (ISO format) | `2024-04-30` |
+| chartType | string | Type of chart to generate | `linear` |
+| metric | string | Metric to use for calculations | `sum` |
+| limit | number | Limit the number of results | `10` |
+| offset | number | Offset for pagination | `0` |
+
+### Example Request
+
+```bash
+curl 'https://api.openpanel.dev/export/charts?projectId=abc123&events=["sign_up","purchase"]&interval=day&range=last_30_days&chartType=linear&metric=sum' \
+  -H 'openpanel-client-id: YOUR_CLIENT_ID' \
+  -H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
+```
+
+### Response
+
+The response will include chart data with series, metrics, and optional previous period comparisons based on the input parameters.
+
+## Funnel
+
+Retrieve funnel data for a specific project.
+
+### Endpoint
+
+```
+GET /export/funnel
+```
+
+### Query Parameters
+
+| Parameter | Type | Description | Example |
+|-----------|------|-------------|---------|
+| projectId | string | The ID of the project to fetch funnel data from | `abc123` |
+| events | object[] | Array of event configurations for the funnel steps | `[{"name":"sign_up","filters":[]}]` |
+| range | string | Predefined date range | `last_30_days` |
+| startDate | string | Custom start date (ISO format) | `2024-04-01` |
+| endDate | string | Custom end date (ISO format) | `2024-04-30` |
+
+### Example Request
+
+```bash
+curl 'https://api.openpanel.dev/export/funnel?projectId=abc123&events=[{"name":"sign_up"},{"name":"purchase"}]&range=last_30_days' \
+  -H 'openpanel-client-id: YOUR_CLIENT_ID' \
+  -H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
+```
+
+### Response
+
+The response will include funnel data with total sessions and step-by-step breakdown of the funnel progression.
+
+```json
+{
+  "totalSessions": number,
+  "steps": [
+    {
+      "event": {
+        "name": string,
+        "displayName": string
+      },
+      "count": number,
+      "percent": number,
+      "dropoffCount": number,
+      "dropoffPercent": number,
+      "previousCount": number
+    }
+  ]
+}
+```
+
+## Notes
+
+- All date parameters should be in ISO format (YYYY-MM-DD).
+- The `range` parameter accepts values like `today`, `yesterday`, `last_7_days`, `last_30_days`, `this_month`, `last_month`, `this_year`, `last_year`, `all_time`.
+- The `interval` parameter accepts values like `minute`, `hour`, `day`, `month`.
+- The `chartType` parameter can be `linear` or other supported chart types.
+- The `metric` parameter can be `sum`, `average`, `min`, or `max`.
+
+Remember to replace `YOUR_CLIENT_ID` and `YOUR_CLIENT_SECRET` with your actual OpenPanel API credentials.
--- a/apps/public/content/docs/api/meta.json
+++ b/apps/public/content/docs/api/meta.json
@@ -0,0 +1,4 @@
+{
+  "title": "API",
+  "pages": ["track", "export"]
+}
--- a/apps/public/content/docs/api/track.mdx
+++ b/apps/public/content/docs/api/track.mdx
@@ -0,0 +1,145 @@
+---
+title: Track
+description: This guide demonstrates how to interact with the OpenPanel API using cURL. These examples provide a low-level understanding of the API endpoints and can be useful for testing or for integrations where a full SDK isn't available.
+---
+
+## Good to know
+
+- If you want to track **geo location** you'll need to pass the `ip` property as a header `x-client-ip`
+- If you want to track **device information** you'll need to pass the `user-agent` property as a header `user-agent`
+
+## Authentication
+
+All requests to the OpenPanel API require authentication. You'll need to include your `clientId` and `clientSecret` in the headers of each request.
+
+```bash
+-H "openpanel-client-id: YOUR_CLIENT_ID" \
+-H "openpanel-client-secret: YOUR_CLIENT_SECRET"
+```
+
+## Usage
+
+### Base URL
+
+All API requests should be made to:
+
+```
+https://api.openpanel.dev
+```
+
+### Tracking Events
+
+To track an event:
+
+```bash
+curl -X POST https://api.openpanel.dev/track \
+-H "Content-Type: application/json" \
+-H "openpanel-client-id: YOUR_CLIENT_ID" \
+-H "openpanel-client-secret: YOUR_CLIENT_SECRET" \
+-d '{
+  "type": "track",
+  "payload": {
+    "name": "my_event",
+    "properties": {
+      "foo": "bar"
+    }
+  }
+}'
+```
+
+### Identifying Users
+
+To identify a user:
+
+```bash
+curl -X POST https://api.openpanel.dev/track \
+-H "Content-Type: application/json" \
+-H "openpanel-client-id: YOUR_CLIENT_ID" \
+-H "openpanel-client-secret: YOUR_CLIENT_SECRET" \
+-d '{
+  "type": "identify",
+  "payload": {
+    "profileId": "123",
+    "firstName": "Joe",
+    "lastName": "Doe",
+    "email": "joe@doe.com",
+    "properties": {
+      "tier": "premium"
+    }
+  }
+}'
+```
+
+### Creating Aliases
+To create an alias for a user:
+
+```bash
+curl -X POST https://api.openpanel.dev/track \
+-H "Content-Type: application/json" \
+-H "openpanel-client-id: YOUR_CLIENT_ID" \
+-H "openpanel-client-secret: YOUR_CLIENT_SECRET" \
+-d '{
+  "type": "alias",
+  "payload": {
+    "profileId": "1",
+    "alias": "a1"
+  }
+}'
+```
+
+### Incrementing Properties
+To increment a numeric property:
+
+```bash
+curl -X POST https://api.openpanel.dev/track \
+-H "Content-Type: application/json" \
+-H "openpanel-client-id: YOUR_CLIENT_ID" \
+-H "openpanel-client-secret: YOUR_CLIENT_SECRET" \
+-d '{
+  "type": "increment",
+  "payload": {
+    "profileId": "1",
+    "property": "visits",
+    "value": 1
+  }
+}'
+```
+
+### Decrementing Properties
+To decrement a numeric property:
+
+```bash
+curl -X POST https://api.openpanel.dev/track \
+-H "Content-Type: application/json" \
+-H "openpanel-client-id: YOUR_CLIENT_ID" \
+-H "openpanel-client-secret: YOUR_CLIENT_SECRET" \
+-d '{
+  "type": "decrement",
+  "payload": {
+    "profileId": "1",
+    "property": "visits",
+    "value": 1
+  }
+}'
+```
+
+### Error Handling
+The API uses standard HTTP response codes to indicate the success or failure of requests. In case of an error, the response body will contain more information about the error.
+Example error response:
+
+```json
+{
+  "error": "Invalid client credentials",
+  "status": 401
+}
+```
+
+### Rate Limiting
+
+The API implements rate limiting to prevent abuse. If you exceed the rate limit, you'll receive a 429 (Too Many Requests) response. The response will include headers indicating your rate limit status.
+
+Best Practices
+	1.	Always use HTTPS to ensure secure communication.
+	2.	Store your clientId and clientSecret securely and never expose them in client-side code.
+	3.	Implement proper error handling in your applications.
+	4.	Respect rate limits and implement exponential backoff for retries.