@drivemetadata-ai/sdk 0.1.1-beta.4 → 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
 

package/dist/angular/index.cjs

@@ -264,6 +264,15 @@ var sensitiveKeys = /* @__PURE__ */ new Set([
   "session",
   "cookie"
 ]);
+function redactUrl(url, allowQueryKeys = ["utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content"]) {
+  const parsed = new URL(url, "https://placeholder.local");
+  for (const key of Array.from(parsed.searchParams.keys())) {
+    if (!allowQueryKeys.includes(key)) {
+      parsed.searchParams.set(key, "[REDACTED]");
+    }
+  }
+  return url.startsWith("http") ? parsed.toString() : `${parsed.pathname}${parsed.search}`;
+}
 function sanitizeValue(value, allow, path = []) {
   if (Array.isArray(value)) {
     return value.map((item) => sanitizeValue(item, allow, path));
@@ -285,6 +294,127 @@ function sanitizeProperties(input, allowRawKeys = []) {
   return sanitizeValue(input, allow);
 }
 
+// src/browser/core/attribute-persistence.ts
+var DMD_ATTRIBUTES_STORAGE_KEY = "dmd_attributes";
+var SESSION_STORAGE_KEY = "sessionData";
+var SESSION_ID_KEY = "sessionId";
+var SESSION_TIMESTAMP_KEY = "timestamp";
+function isBlankValue(value) {
+  return value === null || value === void 0 || typeof value === "string" && value.trim() === "";
+}
+function readAttributes(base) {
+  const raw = base.getItem(DMD_ATTRIBUTES_STORAGE_KEY);
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    base.removeItem(DMD_ATTRIBUTES_STORAGE_KEY);
+    return {};
+  }
+}
+function sanitizeAttributes(attributes) {
+  return Object.fromEntries(Object.entries(attributes).filter(([, value]) => !isBlankValue(value)));
+}
+function writeAttributes(base, attributes) {
+  const sanitized = sanitizeAttributes(attributes);
+  if (Object.keys(sanitized).length === 0) {
+    base.removeItem(DMD_ATTRIBUTES_STORAGE_KEY);
+    return;
+  }
+  base.setItem(DMD_ATTRIBUTES_STORAGE_KEY, JSON.stringify(sanitized));
+}
+function parseSessionData(value) {
+  try {
+    const parsed = JSON.parse(value);
+    const sessionData = {};
+    const sessionId = typeof parsed.sessionId === "string" && parsed.sessionId.trim() !== "" ? parsed.sessionId : void 0;
+    const timestamp = typeof parsed.timestamp === "number" ? parsed.timestamp : void 0;
+    if (sessionId !== void 0) sessionData.sessionId = sessionId;
+    if (timestamp !== void 0) sessionData.timestamp = timestamp;
+    return sessionData;
+  } catch {
+    return {};
+  }
+}
+function getAggregateValue(attributes, key) {
+  if (key === SESSION_STORAGE_KEY) {
+    const sessionId = attributes[SESSION_ID_KEY];
+    const timestamp = attributes[SESSION_TIMESTAMP_KEY];
+    if (typeof sessionId === "string" && !isBlankValue(sessionId) && typeof timestamp === "number") {
+      return JSON.stringify({ sessionId, timestamp });
+    }
+    return null;
+  }
+  const value = attributes[key];
+  if (isBlankValue(value)) return null;
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
+function setAggregateValue(attributes, key, value) {
+  if (key === SESSION_STORAGE_KEY) {
+    const sessionData = parseSessionData(value);
+    if (sessionData.sessionId === void 0 || sessionData.timestamp === void 0) {
+      delete attributes[SESSION_ID_KEY];
+      delete attributes[SESSION_TIMESTAMP_KEY];
+      return;
+    }
+    attributes[SESSION_ID_KEY] = sessionData.sessionId;
+    attributes[SESSION_TIMESTAMP_KEY] = sessionData.timestamp;
+    return;
+  }
+  attributes[key] = value;
+}
+function removeAggregateValue(attributes, key) {
+  if (key === SESSION_STORAGE_KEY) {
+    delete attributes[SESSION_ID_KEY];
+    delete attributes[SESSION_TIMESTAMP_KEY];
+    return;
+  }
+  delete attributes[key];
+}
+function createDmdAttributesPersistence(base) {
+  return {
+    getItem(key) {
+      if (key === DMD_ATTRIBUTES_STORAGE_KEY) return base.getItem(key);
+      const attributes = readAttributes(base);
+      const aggregateValue = getAggregateValue(attributes, key);
+      if (aggregateValue !== null) return aggregateValue;
+      const legacyValue = base.getItem(key);
+      if (isBlankValue(legacyValue)) return null;
+      setAggregateValue(attributes, key, String(legacyValue));
+      writeAttributes(base, attributes);
+      return legacyValue;
+    },
+    setItem(key, value) {
+      if (key === DMD_ATTRIBUTES_STORAGE_KEY) return base.setItem(key, value);
+      const attributes = readAttributes(base);
+      if (isBlankValue(value)) {
+        removeAggregateValue(attributes, key);
+        writeAttributes(base, attributes);
+        base.removeItem(key);
+        return true;
+      }
+      setAggregateValue(attributes, key, value);
+      writeAttributes(base, attributes);
+      base.setItem(key, value);
+      return true;
+    },
+    removeItem(key) {
+      if (key === DMD_ATTRIBUTES_STORAGE_KEY) {
+        base.removeItem(key);
+        return;
+      }
+      const attributes = readAttributes(base);
+      removeAggregateValue(attributes, key);
+      writeAttributes(base, attributes);
+      base.removeItem(key);
+    },
+    getHealth() {
+      return base.getHealth();
+    }
+  };
+}
+
 // src/core/attribution.ts
 var dmdUtmKeys = [
   "utm_source",
@@ -321,6 +451,10 @@ function mergeAttributionRecords(explicitProperties, stored) {
 }
 
 // src/browser/core/attribution.ts
+var DMD_CLICK_ID_QUERY_KEY = "click_id";
+var DMD_CLICK_ID_LEGACY_QUERY_KEY = "dmd_click_id";
+var DMD_CLICK_ID_STORAGE_KEY = "dmd_click_id";
+var DMD_CLICK_ID_ATTRIBUTE_KEY = "click_id";
 function getCurrentUrl() {
   return getBrowserWindow()?.location?.href;
 }
@@ -339,6 +473,9 @@ function setIfPresent(persistence, key, value) {
     persistence.setItem(key, value);
   }
 }
+function getClickIdParam(params) {
+  return params.get(DMD_CLICK_ID_LEGACY_QUERY_KEY) || params.get(DMD_CLICK_ID_QUERY_KEY);
+}
 function getStoredString(persistence, key) {
   const value = persistence.getItem(key);
   return value === null || value === "" ? void 0 : value;
@@ -358,6 +495,9 @@ function captureAttributionFromUrl(persistence, url = getCurrentUrl()) {
   for (const key of dmdCampaignKeys) {
     setIfPresent(persistence, key, params.get(key));
   }
+  const clickId = getClickIdParam(params);
+  setIfPresent(persistence, DMD_CLICK_ID_ATTRIBUTE_KEY, clickId);
+  setIfPresent(persistence, DMD_CLICK_ID_STORAGE_KEY, clickId);
   for (const [param, sdkPubId] of dmdClickIdSources) {
     const value = params.get(param);
     if (value) {
@@ -373,7 +513,8 @@ function getStoredAttributionData(persistence) {
     fbc: getStoredString(persistence, "fbc") ?? getCookie("_fbc"),
     fbp: getStoredString(persistence, "fbp") ?? getCookie("_fbp"),
     campaign_id: getStoredString(persistence, "campaign_id"),
-    ad_id: getStoredString(persistence, "ad_id")
+    ad_id: getStoredString(persistence, "ad_id"),
+    click_id: getStoredString(persistence, DMD_CLICK_ID_STORAGE_KEY) ?? getStoredString(persistence, DMD_CLICK_ID_ATTRIBUTE_KEY)
   });
 }
 function getStoredUtmParameter(persistence) {
@@ -892,6 +1033,24 @@ function resetAnonymousId(persistence) {
   return anonymousId;
 }
 
+// src/browser/core/page-context.ts
+function redactSearch(search) {
+  const redacted = redactUrl(search);
+  return redacted.startsWith("/?") ? redacted.slice(1) : redacted;
+}
+function getBrowserPageContext() {
+  const browserWindow = getBrowserWindow();
+  const documentRef = browserWindow?.document ?? globalThis.document;
+  const location = browserWindow?.location;
+  const page2 = {};
+  if (location?.href) page2.url = location.href;
+  if (location?.pathname) page2.path = location.pathname;
+  if (location?.search) page2.search = redactSearch(location.search);
+  if (documentRef?.title) page2.title = documentRef.title;
+  if (documentRef?.referrer) page2.referrer = redactUrl(documentRef.referrer);
+  return page2;
+}
+
 // src/browser/core/persistence.ts
 function createPersistenceHealth(requested) {
   return {
@@ -1058,7 +1217,7 @@ function createBrowserPersistence(mode = "localStorage+cookie") {
 }
 
 // src/browser/core/session.ts
-var SESSION_STORAGE_KEY = "sessionData";
+var SESSION_STORAGE_KEY2 = "sessionData";
 function getUrlParam2(name) {
   const href = getBrowserWindow()?.location?.href;
   if (!href) return null;
@@ -1069,7 +1228,7 @@ function getUrlParam2(name) {
   }
 }
 function readStoredSession(persistence) {
-  const rawSession = persistence.getItem(SESSION_STORAGE_KEY);
+  const rawSession = persistence.getItem(SESSION_STORAGE_KEY2);
   if (!rawSession) return void 0;
   try {
     const parsed = JSON.parse(rawSession);
@@ -1080,12 +1239,12 @@ function readStoredSession(persistence) {
       };
     }
   } catch {
-    persistence.removeItem(SESSION_STORAGE_KEY);
+    persistence.removeItem(SESSION_STORAGE_KEY2);
   }
   return void 0;
 }
 function writeStoredSession(persistence, sessionId, timestamp) {
-  persistence.setItem(SESSION_STORAGE_KEY, JSON.stringify({ sessionId, timestamp }));
+  persistence.setItem(SESSION_STORAGE_KEY2, JSON.stringify({ sessionId, timestamp }));
 }
 function createSessionManager(persistence, idleTimeoutSeconds = 30 * 60) {
   function resolveSessionId() {
@@ -1139,11 +1298,12 @@ var DriveMetaDataSDK = class {
     requireConfigString(config.writeKey || config.token, "writeKey or token");
     this.config = config;
     this.endpoint = endpointFromConfig(config);
-    this.persistence = createBrowserPersistence(config.persistence);
+    const storagePersistence = createBrowserPersistence(config.persistence);
+    this.persistence = createDmdAttributesPersistence(storagePersistence);
     this.session = createSessionManager(this.persistence, config.sessionIdleTimeoutSeconds);
     const deliveryConfig = {
       endpoint: this.endpoint,
-      storage: this.persistence
+      storage: storagePersistence
     };
     if (config.delivery?.maxQueueSize !== void 0) deliveryConfig.maxQueueSize = config.delivery.maxQueueSize;
     if (config.delivery?.queueTtlMs !== void 0) deliveryConfig.queueTtlMs = config.delivery.queueTtlMs;
@@ -1388,6 +1548,7 @@ var DriveMetaDataSDK = class {
   }
   toCollectorPayload(prepared) {
     const browserWindow = getBrowserWindow();
+    const pageContext = getBrowserPageContext();
     return createBackendCollectorPayload({
       requestId: prepared.messageId,
       timestamp: prepared.timestamp,
@@ -1399,9 +1560,13 @@ var DriveMetaDataSDK = class {
       sessionId: prepared.sessionId,
       ua: browserWindow?.navigator?.userAgent,
       appId: prepared.appId,
-      pageUrl: browserWindow?.location?.href,
+      pageUrl: pageContext.url ?? browserWindow?.location?.href,
       eventData: mergeStoredAttribution({
         ...prepared.properties,
+        page: {
+          ...pageContext,
+          ...prepared.properties.page && typeof prepared.properties.page === "object" ? prepared.properties.page : {}
+        },
         anonymousId: prepared.anonymousId,
         sessionId: prepared.sessionId,
         timestamp: prepared.timestamp,