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

package/README.md

@@ -8,16 +8,50 @@ Enterprise-grade analytics, behavior intelligence, and customer data collection
 npm install @drivemetadata-ai/sdk
 ```
 
-## Browser
+For private beta installs, pin the beta tag:
+
+```bash
+npm install @drivemetadata-ai/sdk@beta
+```
+
+## Runtime Entries
+
+| Runtime | Import path | Use for |
+|---|---|---|
+| Browser | `@drivemetadata-ai/sdk/browser` | Plain JavaScript and browser applications |
+| React | `@drivemetadata-ai/sdk/react` | React provider and hooks |
+| Next.js | `@drivemetadata-ai/sdk/next` | App Router and Pages Router client helpers |
+| Angular | `@drivemetadata-ai/sdk/angular` | Angular provider and injectable service |
+| Node.js | `@drivemetadata-ai/sdk/node` | Backend/server events only |
+
+Do not import `@drivemetadata-ai/sdk/node` from frontend bundles. Browser, React, Next.js, and Angular integrations use public browser tokens. Node integrations use server tokens from backend-only environment variables.
+
+## Required Browser Config
+
+Use camelCase config keys in npm integrations:
 
 ```ts
-import { initDmdSDK } from '@drivemetadata-ai/sdk/browser';
+const config = {
+  clientId: 'client_xxx',
+  workspaceId: 'workspace_xxx',
+  appId: 'app_xxx',
+  token: 'public_browser_token',
+  consent: { analytics: 'pending', advertising: 'denied' }
+};
+```
+
+`token` is the public browser write key. It is sent to the backend as `metaData.token`.
+
+## Browser Quick Start
 
-const dmd = initDmdSDK({
+```ts
+import { consent, flush, getDmdHealth, identify, initDmdSDK, page, track } from '@drivemetadata-ai/sdk/browser';
+
+initDmdSDK({
   clientId: 'client_xxx',
   workspaceId: 'workspace_xxx',
   appId: 'app_xxx',
-  token: 'public_token',
+  token: 'public_browser_token',
   consent: {
     analytics: 'pending',
     advertising: 'denied',
@@ -27,26 +61,50 @@ const dmd = initDmdSDK({
   }
 });
 
-dmd.setConsent({ analytics: 'granted' });
-dmd.track('Product Viewed', {
-  productId: 'sku_123'
-});
-await dmd.flush();
+consent.update({ analytics: 'granted' });
+
+identify('user_123', { plan: 'enterprise' });
+page('Product Page');
+track('Product Viewed', { productId: 'sku_123' });
+
+await flush();
+console.log(getDmdHealth());
 ```
 
+Browser events automatically include backend `metaData` fields such as `requestId`, `anonymousId`, `sessionId`, timestamps, attribution/UTM enrichment, and page context.
+
 ## React
 
 ```tsx
-import { DmdProvider, useTrackEvent } from '@drivemetadata-ai/sdk/react';
+import { DmdProvider, useDmdConsent, useDmdFlush, useIdentify, useTrackEvent } from '@drivemetadata-ai/sdk/react';
 
 function ProductButton() {
   const track = useTrackEvent();
-  return <button onClick={() => track('Product Clicked')}>Track</button>;
+  const identify = useIdentify();
+  const flush = useDmdFlush();
+  const consent = useDmdConsent();
+
+  async function onClick() {
+    consent({ analytics: 'granted' });
+    identify('user_123', { plan: 'enterprise' });
+    track('Product Clicked', { productId: 'sku_123' });
+    await flush();
+  }
+
+  return <button onClick={onClick}>Track</button>;
 }
 
 export function App() {
   return (
-    <DmdProvider config={config}>
+    <DmdProvider
+      config={{
+        clientId: 'client_xxx',
+        workspaceId: 'workspace_xxx',
+        appId: 'app_xxx',
+        token: 'public_browser_token',
+        consent: { analytics: 'pending', advertising: 'denied' }
+      }}
+    >
       <ProductButton />
     </DmdProvider>
   );
@@ -60,15 +118,55 @@ Use `@drivemetadata-ai/sdk/next` from a client component.
 ```tsx
 'use client';
 
-import { DmdProvider } from '@drivemetadata-ai/sdk/next';
+import { DmdProvider, useDmdAppRouterPageTracking } from '@drivemetadata-ai/sdk/next';
+import { usePathname, useSearchParams } from 'next/navigation';
+import type { ReactNode } from 'react';
+
+function RouteTracking() {
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+  useDmdAppRouterPageTracking(pathname, searchParams.toString());
+  return null;
+}
+
+export function AnalyticsProvider({ children }: { children: ReactNode }) {
+  return (
+    <DmdProvider
+      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', advertising: 'denied' }
+      }}
+    >
+      <RouteTracking />
+      {children}
+    </DmdProvider>
+  );
+}
 ```
 
 ## Angular
 
 ```ts
 import { DmdAnalyticsService, provideDmdAnalytics } from '@drivemetadata-ai/sdk/angular';
+
+export const appConfig = {
+  providers: [
+    provideDmdAnalytics({
+      clientId: 'client_xxx',
+      workspaceId: 'workspace_xxx',
+      appId: 'app_xxx',
+      token: 'public_browser_token',
+      consent: { analytics: 'pending', advertising: 'denied' }
+    })
+  ]
+};
 ```
 
+Call `DmdAnalyticsService.init()` only in the browser when using Angular Universal/SSR.
+
 ## Node.js
 
 ```ts
@@ -78,23 +176,56 @@ const dmd = createDmdServerClient({
   clientId: 'client_xxx',
   workspaceId: 'workspace_xxx',
   appId: 'app_xxx',
-  token: process.env.DMD_SERVER_TOKEN!
+  token: process.env.DMD_SERVER_TOKEN!,
+  timeoutMs: 5000,
+  retry: {
+    attempts: 3,
+    minDelayMs: 250,
+    maxDelayMs: 2000
+  }
 });
 
 await dmd.track({
   userId: 'user_123',
   event: 'Order Completed',
-  idempotencyKey: 'order_123'
+  idempotencyKey: 'order_123',
+  properties: {
+    amount: 500,
+    currency: 'USD'
+  }
 });
 ```
 
-## Runtime Entries
+## Default Page Context
+
+Browser, React, Next.js, and Angular integrations automatically add 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"
+    }
+  }
+}
+```
+
+Query strings in `search` and `referrer` are redacted by default except common attribution parameters.
+
+## Diagnostics
+
+```ts
+import { flush, getDmdHealth } from '@drivemetadata-ai/sdk/browser';
+
+console.log(getDmdHealth());
+await flush();
+```
 
-- `@drivemetadata-ai/sdk/browser`
-- `@drivemetadata-ai/sdk/react`
-- `@drivemetadata-ai/sdk/next`
-- `@drivemetadata-ai/sdk/angular`
-- `@drivemetadata-ai/sdk/node`
+Useful drop reasons include `consent_denied`, `payload_too_large`, `queue_limit_exceeded`, and `queue_ttl_expired`.
 
 ## Documentation