feat: sdks and docs (#239)

* init

* fix

* update docs

* bump: all sdks

* rename types test

Author: lindesvard

apps/public/content/articles/cookieless-analytics.mdx

@@ -88,9 +88,7 @@ We built OpenPanel from the ground up with privacy at its heart—and with featu
 
 ```html
 <script>
-  window.op = window.op || function(...args) {
-    (window.op.q = window.op.q || []).push(args);
-  };
+  window.op=window.op||function(){var n=[],o=new Proxy((function(){arguments.length>0&&n.push(Array.prototype.slice.call(arguments))}),{get:function(o,t){return"q"===t?n:function(){n.push([t].concat(Array.prototype.slice.call(arguments)))}}});return o}();
   window.op('init', {
     clientId: 'YOUR_CLIENT_ID',
     trackScreenViews: true,

apps/public/content/docs/(tracking)/adblockers.mdx

@@ -0,0 +1,104 @@
+---
+title: Avoid adblockers with proxy
+description: Learn why adblockers block analytics and how to avoid it by proxying events.
+---
+
+In this article we need to talk about adblockers, why they exist, how they work, and how to avoid them.
+
+Adblockers' main purpose was initially to block ads, but they have since started to block tracking scripts as well. This is primarily for privacy reasons, and while we respect that, there are legitimate use cases for understanding your visitors. OpenPanel is designed to be a privacy-friendly, cookieless analytics tool that doesn't track users across sites, but generic blocklists often catch all analytics tools indiscriminately.
+
+The best way to avoid adblockers is to proxy events via your own domain name. Adblockers generally cannot block requests to your own domain (first-party requests) without breaking the functionality of the site itself.
+
+## Built-in Support
+
+Today, our Next.js SDK and WordPress plugin have built-in support for proxying:
+- **WordPress**: Does it automatically.
+- **Next.js**: Easy to setup with a route handler.
+
+## Implementing Proxying for Any Framework
+
+If you are not using Next.js or WordPress, you can implement proxying in any backend framework. The key is to set up an API endpoint on your domain (e.g., `api.domain.com` or `domain.com/api`) that forwards requests to OpenPanel.
+
+Below is an example of how to set up a proxy using a [Hono](https://hono.dev/) server. This implementation mimics the logic used in our Next.js SDK.
+
+> You can always see how our Next.js implementation looks like in our [repository](https://github.com/Openpanel-dev/openpanel/blob/main/packages/sdks/nextjs/createNextRouteHandler.ts).
+
+### Hono Example
+
+```typescript
+import { Hono } from 'hono'
+
+const app = new Hono()
+
+// 1. Proxy the script file
+app.get('/op1.js', async (c) => {
+  const scriptUrl = 'https://openpanel.dev/op1.js'
+  try {
+    const res = await fetch(scriptUrl)
+    const text = await res.text()
+    
+    c.header('Content-Type', 'text/javascript')
+    // Optional caching for 24 hours
+    c.header('Cache-Control', 'public, max-age=86400, stale-while-revalidate=86400')
+    return c.body(text)
+  } catch (e) {
+     return c.json({ error: 'Failed to fetch script' }, 500)
+  }
+})
+
+// 2. Proxy the track event
+app.post('/track', async (c) => {
+  const body = await c.req.json()
+  
+  // Forward the client's IP address (be sure to pick correct IP based on your infra)
+  const ip = c.req.header('cf-connecting-ip') ?? 
+             c.req.header('x-forwarded-for')?.split(',')[0]
+
+  const headers = new Headers()
+  headers.set('Content-Type', 'application/json')
+  headers.set('Origin', c.req.header('origin') ?? '')
+  headers.set('User-Agent', c.req.header('user-agent') ?? '')
+  headers.set('openpanel-client-id', c.req.header('openpanel-client-id') ?? '')
+  
+  if (ip) {
+    headers.set('openpanel-client-ip', ip)
+  }
+
+  try {
+    const res = await fetch('https://api.openpanel.dev/track', {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+    })
+    return c.json(await res.text(), res.status)
+  } catch (e) {
+    return c.json(e, 500)
+  }
+})
+
+export default app
+```
+
+This script sets up two endpoints:
+1. `GET /op1.js`: Fetches the OpenPanel script and serves it from your domain.
+2. `POST /track`: Receives events from the frontend, adds necessary headers (User-Agent, Origin, Content-Type, openpanel-client-id, openpanel-client-ip), and forwards them to OpenPanel's API.
+
+## Frontend Configuration
+
+Once your proxy is running, you need to configure the OpenPanel script on your frontend to use your proxy endpoints instead of the default ones.
+
+```html
+<script>
+  window.op=window.op||function(){var n=[],o=new Proxy((function(){arguments.length>0&&n.push(Array.prototype.slice.call(arguments))}),{get:function(o,t){return"q"===t?n:function(){n.push([t].concat(Array.prototype.slice.call(arguments)))}}});return o}();
+  window.op('init', {
+    apiUrl: 'https://api.domain.com'
+    clientId: 'YOUR_CLIENT_ID',
+    trackScreenViews: true,
+    trackOutgoingLinks: true,
+    trackAttributes: true,
+  });
+</script>
+<script src="https://api.domain.com/op1.js" defer async></script>
+```
+
+By doing this, all requests are sent to your domain first, bypassing adblockers that look for third-party tracking domains.

apps/public/content/docs/(tracking)/how-it-works.mdx

@@ -0,0 +1,190 @@
+---
+title: How it works
+description: Understanding device IDs, session IDs, profile IDs, and event tracking
+---
+
+## Device ID
+
+A **device ID** is a unique identifier generated for each device/browser combination. It's calculated using a hash function that combines:
+
+- **User Agent** (browser/client information)
+- **IP Address**
+- **Origin** (project ID)
+- **Salt** (a rotating secret key)
+
+```typescript:packages/common/server/profileId.ts
+export function generateDeviceId({
+  salt,
+  ua,
+  ip,
+  origin,
+}: GenerateDeviceIdOptions) {
+  return createHash(`${ua}:${ip}:${origin}:${salt}`, 16);
+}
+```
+
+### Salt Rotation
+
+The salt used for device ID generation rotates **daily at midnight** (UTC). This means:
+
+- Device IDs remain consistent throughout a single day
+- Device IDs reset each day for privacy purposes
+- The system maintains both the current and previous day's salt to handle events that may arrive slightly after midnight
+
+```typescript:apps/worker/src/jobs/cron.salt.ts
+// Salt rotation happens daily at midnight (pattern: '0 0 * * *')
+```
+
+When the salt rotates, all device IDs change, effectively anonymizing tracking data on a daily basis while still allowing session continuity within a 24-hour period.
+
+## Session ID
+
+A **session** represents a continuous period of user activity. Sessions are used to group related events together and understand user behavior patterns.
+
+### Session Duration
+
+Sessions have a **30-minute timeout**. If no events are received for 30 minutes, the session automatically ends. Each new event resets this 30-minute timer.
+
+```typescript:apps/worker/src/utils/session-handler.ts
+export const SESSION_TIMEOUT = 1000 * 60 * 30; // 30 minutes
+```
+
+### Session Creation Rules
+
+Sessions are **only created for client events**, not server events. This means:
+
+- Events sent from browsers, mobile apps, or client-side SDKs will create sessions
+- Events sent from backend servers, scripts, or server-side SDKs will **not** create sessions
+- If you only track events from your backend, no sessions will be created
+
+Additionally, sessions are **not created for events older than 15 minutes**. This prevents historical data imports from creating artificial sessions.
+
+```typescript:apps/worker/src/jobs/events.incoming-event.ts
+// Sessions are not created if:
+// 1. The event is from a server (uaInfo.isServer === true)
+// 2. The timestamp is from the past (isTimestampFromThePast === true)
+if (uaInfo.isServer || isTimestampFromThePast) {
+  // Event is attached to existing session or no session
+}
+```
+
+## Profile ID
+
+A **profile ID** is a persistent identifier for a user across multiple devices and sessions. It allows you to track the same user across different browsers, devices, and time periods.
+
+### Profile ID Assignment
+
+If a `profileId` is provided when tracking an event, it will be used to identify the user. However, **if no `profileId` is provided, it defaults to the `deviceId`**.
+
+This means:
+- Anonymous users (without a profile ID) are tracked by their device ID
+- Once you identify a user (by providing a profile ID), all their events will be associated with that profile
+- The same user can be tracked across multiple devices by using the same profile ID
+
+```typescript:packages/db/src/services/event.service.ts
+// If no profileId is provided, it defaults to deviceId
+if (!payload.profileId && payload.deviceId) {
+  payload.profileId = payload.deviceId;
+}
+```
+
+## Client Events vs Server Events
+
+OpenPanel distinguishes between **client events** and **server events** based on the User-Agent header.
+
+### Client Events
+
+Client events are sent from:
+- Web browsers (Chrome, Firefox, Safari, etc.)
+- Mobile apps using client-side SDKs
+- Any client that sends a browser-like User-Agent
+
+Client events:
+- Create sessions
+- Generate device IDs
+- Support full session tracking
+
+### Server Events
+
+Server events are detected when the User-Agent matches server patterns, such as:
+- `Go-http-client/1.0`
+- `node-fetch/1.0`
+- Other single-name/version patterns (e.g., `LibraryName/1.0`)
+
+Server events:
+- Do **not** create sessions
+- Are attached to existing sessions if available
+- Are useful for backend tracking without session management
+
+```typescript:packages/common/server/parser-user-agent.ts
+// Server events are detected by patterns like "Go-http-client/1.0"
+function isServer(res: UAParser.IResult) {
+  if (SINGLE_NAME_VERSION_REGEX.test(res.ua)) {
+    return true;
+  }
+  // ... additional checks
+}
+```
+
+The distinction is made in the event processing pipeline:
+
+```typescript:apps/worker/src/jobs/events.incoming-event.ts
+const uaInfo = parseUserAgent(userAgent, properties);
+
+// Only client events create sessions
+if (uaInfo.isServer || isTimestampFromThePast) {
+  // Server events or old events don't create new sessions
+}
+```
+
+## Timestamps
+
+Events can include custom timestamps to track when events actually occurred, rather than when they were received by the server.
+
+### Setting Custom Timestamps
+
+You can provide a custom timestamp using the `__timestamp` property in your event properties:
+
+```javascript
+track('page_view', {
+  __timestamp: '2024-01-15T10:30:00Z'
+});
+```
+
+### Timestamp Validation
+
+The system validates timestamps to prevent abuse and ensure data quality:
+
+1. **Future timestamps**: If a timestamp is more than **1 minute in the future**, the server timestamp is used instead
+2. **Past timestamps**: If a timestamp is older than **15 minutes**, it's marked as `isTimestampFromThePast: true`
+
+```typescript:apps/api/src/controllers/track.controller.ts
+// Timestamp validation logic
+const ONE_MINUTE_MS = 60 * 1000;
+const FIFTEEN_MINUTES_MS = 15 * ONE_MINUTE_MS;
+
+// Future check: more than 1 minute ahead
+if (clientTimestampNumber > safeTimestamp + ONE_MINUTE_MS) {
+  return { timestamp: safeTimestamp, isTimestampFromThePast: false };
+}
+
+// Past check: older than 15 minutes
+const isTimestampFromThePast =
+  clientTimestampNumber < safeTimestamp - FIFTEEN_MINUTES_MS;
+```
+
+### Timestamp Impact on Sessions
+
+**Important**: Events with timestamps older than 15 minutes (`isTimestampFromThePast: true`) will **not create new sessions**. This prevents historical data imports from creating artificial sessions in your analytics.
+
+```typescript:apps/worker/src/jobs/events.incoming-event.ts
+// Events from the past don't create sessions
+if (uaInfo.isServer || isTimestampFromThePast) {
+  // Attach to existing session or track without session
+}
+```
+
+This ensures that:
+- Real-time tracking creates proper sessions
+- Historical data imports don't interfere with session analytics
+- Backdated events are still tracked but don't affect session metrics

apps/public/content/docs/(tracking)/meta.json

@@ -0,0 +1,3 @@
+{
+  "pages": ["sdks", "how-it-works", "..."]
+}