@drivemetadata-ai/sdk 0.1.1-beta.4 → 0.1.1

package/docs/integration.md

@@ -33,12 +33,72 @@ const browserConfig = {
 };
 ```
 
+Use camelCase config keys in npm integrations. The backend payload still sends the backend-required `metaData` shape, but SDK configuration should use `clientId`, `workspaceId`, `appId`, `apiHost`, `capturePageview`, `capturePageleave`, `schemaValidation`, and `beforeSend`.
+
 Node integrations use a server token stored only in backend environment variables:
 
 ```bash
 DMD_SERVER_TOKEN=server_write_key
 ```
 
+### Environment Variables
+
+For React/Vite-style browser builds, expose only public browser values:
+
+```bash
+VITE_DMD_CLIENT_ID=client_xxx
+VITE_DMD_WORKSPACE_ID=workspace_xxx
+VITE_DMD_APP_ID=app_xxx
+VITE_DMD_TOKEN=public_token
+```
+
+For Next.js browser integrations, use `NEXT_PUBLIC_` only for public browser values:
+
+```bash
+NEXT_PUBLIC_DMD_CLIENT_ID=client_xxx
+NEXT_PUBLIC_DMD_WORKSPACE_ID=workspace_xxx
+NEXT_PUBLIC_DMD_APP_ID=app_xxx
+NEXT_PUBLIC_DMD_TOKEN=public_token
+```
+
+For Node/server integrations, do not use `NEXT_PUBLIC_`:
+
+```bash
+DMD_SERVER_TOKEN=server_write_key
+```
+
+## Common Browser Config
+
+```ts
+const config = {
+  clientId: 'client_xxx',
+  workspaceId: 'workspace_xxx',
+  appId: 'app_xxx',
+  token: 'public_token',
+  apiHost: 'https://sdk.drivemetadata.com/v2',
+  consent: { analytics: 'pending', advertising: 'denied' },
+  capturePageview: true,
+  capturePageleave: true,
+  schemaValidation: 'warn',
+  delivery: {
+    retryDelayMs: 1000,
+    maxRetryDelayMs: 30000,
+    maxQueueSize: 100,
+    useBeacon: true
+  }
+};
+```
+
+Recommended defaults:
+
+| Option | Recommended | Notes |
+|---|---|---|
+| `consent.analytics` | `pending` | Grant after consent manager resolves |
+| `capturePageview` | `true` | Sends automatic page views in browser runtimes |
+| `capturePageleave` | `true` | Sends lifecycle/page leave events |
+| `schemaValidation` | `warn` | Use `strict` in controlled integrations after testing |
+| `delivery.useBeacon` | `true` | Helps lifecycle delivery during navigation |
+
 ## Consent First Setup
 
 Enterprise integrations should start with analytics consent as `pending` or `denied`, then grant it after the consent manager resolves.
@@ -92,6 +152,20 @@ await flush();
 console.log(getDmdHealth());
 ```
 
+Browser API methods:
+
+| Method | Use for |
+|---|---|
+| `track(event, properties, options)` | custom events |
+| `page(name, properties, options)` | page views |
+| `identify(userId, traits, options)` | known users |
+| `group(groupId, traits, options)` | accounts/workspaces/organizations |
+| `alias(previousId, userId, options)` | identity merge |
+| `flush()` | force queued delivery |
+| `reset()` | reset identity/session state |
+| `setConsent(consent)` / `consent.update(consent)` | consent updates |
+| `getDmdHealth()` | diagnostics |
+
 ## Backend Timestamp Fields
 
 Every collector request sends these timestamp fields inside `metaData`:
@@ -104,6 +178,42 @@ Every collector request sends these timestamp fields inside `metaData`:
 
 If a caller provides an invalid timestamp string, the SDK normalizes it to the current UTC time instead of sending the invalid value to the backend.
 
+## Default Page Context
+
+Browser, React, Next.js, and Angular integrations automatically add browser page context to each collector payload.
+
+```json
+{
+  "metaData": {
+    "page": {
+      "url": "https://example.com/products/sku-123?utm_source=paid",
+      "path": "/products/sku-123",
+      "search": "?utm_source=paid",
+      "title": "Product Detail",
+      "referrer": "https://google.com/search?q=%5BREDACTED%5D"
+    }
+  }
+}
+```
+
+The SDK reads this from `window.location`, `document.title`, and `document.referrer`. Query strings in `search` and `referrer` are redacted by default except common attribution parameters such as `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, and `utm_content`.
+
+Node/server integrations do not automatically capture page context. Pass page details explicitly in server event properties if needed.
+
+## Default Identity, Session, Attribution
+
+Browser, React, Next.js, and Angular integrations also add these fields by default:
+
+| Field | Behavior |
+|---|---|
+| `requestId` | generated UUID for each event |
+| `anonymousId` | persisted anonymous browser visitor ID |
+| `sessionId` | persisted browser session ID with idle timeout |
+| `attributionData` | stored click IDs and `_fbc`/`_fbp` when available |
+| `utmParameter` | stored UTM values when available |
+
+The SDK stores anonymous/session/attribution state using the configured browser persistence mode and falls back safely when browser storage is blocked.
+
 ## React Integration
 
 Wrap the app once:
@@ -128,6 +238,18 @@ export function App() {
 }
 ```
 
+For Vite React apps, the provider config commonly comes from `import.meta.env`:
+
+```tsx
+const config = {
+  clientId: import.meta.env.VITE_DMD_CLIENT_ID,
+  workspaceId: import.meta.env.VITE_DMD_WORKSPACE_ID,
+  appId: import.meta.env.VITE_DMD_APP_ID,
+  token: import.meta.env.VITE_DMD_TOKEN,
+  consent: { analytics: 'pending' as const, advertising: 'denied' as const }
+};
+```
+
 Track from components:
 
 ```tsx
@@ -140,7 +262,7 @@ export function CheckoutButton() {
   const consent = useDmdConsent();
 
   async function onClick() {
-    consent.update({ analytics: 'granted' });
+    consent({ analytics: 'granted' });
     identify('user_123', { plan: 'enterprise' });
     track('Checkout Started', { source: 'cart' });
     await flush();
@@ -159,13 +281,18 @@ Create a client provider:
 
 import { DmdProvider, useDmdAppRouterPageTracking } from '@drivemetadata-ai/sdk/next';
 import { usePathname, useSearchParams } from 'next/navigation';
+import type { ReactNode } from 'react';
 
-export function AnalyticsProvider({ children }: { children: React.ReactNode }) {
+function RouteTracking() {
   const pathname = usePathname();
   const searchParams = useSearchParams();
 
   useDmdAppRouterPageTracking(pathname, searchParams.toString());
 
+  return null;
+}
+
+export function AnalyticsProvider({ children }: { children: ReactNode }) {
   return (
     <DmdProvider
       config={{
@@ -176,6 +303,7 @@ export function AnalyticsProvider({ children }: { children: React.ReactNode }) {
         consent: { analytics: 'pending', advertising: 'denied' }
       }}
     >
+      <RouteTracking />
       {children}
     </DmdProvider>
   );
@@ -186,8 +314,9 @@ Use it from `app/layout.tsx`:
 
 ```tsx
 import { AnalyticsProvider } from './AnalyticsProvider';
+import type { ReactNode } from 'react';
 
-export default function RootLayout({ children }: { children: React.ReactNode }) {
+export default function RootLayout({ children }: { children: ReactNode }) {
   return (
     <html lang="en">
       <body>
@@ -205,6 +334,14 @@ import type { AppProps } from 'next/app';
 import { useRouter } from 'next/router';
 import { DmdProvider, useDmdPagesRouterPageTracking } from '@drivemetadata-ai/sdk/next';
 
+const config = {
+  clientId: process.env.NEXT_PUBLIC_DMD_CLIENT_ID!,
+  workspaceId: process.env.NEXT_PUBLIC_DMD_WORKSPACE_ID!,
+  appId: process.env.NEXT_PUBLIC_DMD_APP_ID!,
+  token: process.env.NEXT_PUBLIC_DMD_TOKEN!,
+  consent: { analytics: 'pending' as const, advertising: 'denied' as const }
+};
+
 function PageTracking() {
   const router = useRouter();
   useDmdPagesRouterPageTracking(router);
@@ -242,10 +379,24 @@ export const appConfig: ApplicationConfig = {
 };
 ```
 
+For Angular environment files, keep only the public browser token in frontend config:
+
+```ts
+export const environment = {
+  dmd: {
+    clientId: 'client_xxx',
+    workspaceId: 'workspace_xxx',
+    appId: 'app_xxx',
+    token: 'public_token'
+  }
+};
+```
+
 Initialize and track:
 
 ```ts
-import { Component, OnInit } from '@angular/core';
+import { isPlatformBrowser } from '@angular/common';
+import { Component, Inject, OnInit, PLATFORM_ID } from '@angular/core';
 import { DmdAnalyticsService } from '@drivemetadata-ai/sdk/angular';
 
 @Component({
@@ -253,10 +404,16 @@ import { DmdAnalyticsService } from '@drivemetadata-ai/sdk/angular';
   template: '<router-outlet />'
 })
 export class AppComponent implements OnInit {
-  constructor(private readonly dmd: DmdAnalyticsService) {}
+  constructor(
+    private readonly dmd: DmdAnalyticsService,
+    @Inject(PLATFORM_ID) private readonly platformId: object
+  ) {}
 
   ngOnInit() {
+    if (!isPlatformBrowser(this.platformId)) return;
+
     this.dmd.init();
+    this.dmd.setConsent({ analytics: 'granted' });
     this.dmd.track('App Loaded');
   }
 }
@@ -296,6 +453,21 @@ await dmd.track({
 
 Use `messageId` for a unique event ID and `idempotencyKey` for business events that may retry, such as orders, invoices, subscriptions, and webhooks.
 
+Server-side page context is explicit:
+
+```ts
+await dmd.page({
+  userId: 'user_123',
+  properties: {
+    page: {
+      url: 'https://example.com/orders/123',
+      path: '/orders/123',
+      title: 'Order Detail'
+    }
+  }
+});
+```
+
 ## Diagnostics
 
 Use health diagnostics when events do not appear:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drivemetadata-ai/sdk",
-  "version": "0.1.1-beta.4",
+  "version": "0.1.1",
   "description": "DriveMetaData JavaScript and TypeScript SDK.",
   "license": "MIT",
   "type": "module",
@@ -59,6 +59,7 @@
     "test": "vitest run",
     "test:package": "npm run build && vitest run tests/package/package-contents.test.ts tests/package/package-install-smoke.test.ts",
     "pack:check": "npm run build && npm pack --dry-run",
+    "release:version": "node scripts/release-version.mjs",
     "release:check": "npm run ci && npm_config_cache=/tmp/npm-cache npm run pack:check",
     "ci": "npm run typecheck && npm run test && npm run build && npm run test:package",
     "ci:phase1": "npm run typecheck && npm run test && npm run build"