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

package/docs/architecture.md

@@ -0,0 +1,109 @@
+# SDK Architecture
+
+This package separates shared SDK logic from runtime-specific integrations.
+
+## Runtime Entry Points
+
+| Entry point | Runtime | Responsibility |
+|---|---|---|
+| `@drivemetadata-ai/sdk/browser` | Browser | Client-side analytics, identity, consent, persistence, delivery, autocapture |
+| `@drivemetadata-ai/sdk/react` | React | Provider and hooks over the browser SDK |
+| `@drivemetadata-ai/sdk/next` | Next.js | Client-safe provider and route tracking helpers over the browser SDK |
+| `@drivemetadata-ai/sdk/angular` | Angular | Provider and injectable service over the browser SDK |
+| `@drivemetadata-ai/sdk/node` | Node.js | Server-side event delivery without browser APIs |
+
+## Source Layout
+
+```text
+src/core/
+  backend-payload.ts
+  backend-schema.ts
+  consent.ts
+  diagnostics.ts
+  environment.ts
+  event-schema.ts
+  types.ts
+  uuid.ts
+
+src/browser/
+  client.ts
+  core/
+    DriveMetaDataSDK.ts
+    attribution.ts
+    autocapture.ts
+    browser-config.ts
+    delivery.ts
+    identity.ts
+    persistence.ts
+    privacy.ts
+    session.ts
+    types.ts
+
+src/react/
+src/next/
+src/angular/
+src/node/
+```
+
+## What Belongs In `src/core`
+
+Use `src/core` for runtime-neutral code only:
+
+- Backend collector payload construction.
+- Backend payload validation.
+- Consent normalization and purpose checks.
+- Event envelope validation.
+- Shared diagnostics and public types.
+- UUID helpers.
+
+Code in `src/core` must not depend on `window`, `document`, browser storage, cookies, `navigator`, DOM events, framework APIs, or Node-only APIs.
+
+## What Belongs In `src/browser/core`
+
+Use `src/browser/core` for browser-specific behavior:
+
+- Browser identity and session persistence.
+- Cookie/localStorage/sessionStorage/memory persistence.
+- Attribution and UTM capture from URLs and cookies.
+- Autocapture, history listeners, page lifecycle, and page leave.
+- Browser delivery, Beacon/fetch transport, queueing, and retry.
+- Browser privacy redaction behavior.
+- Browser config normalization.
+
+## Framework Adapter Rule
+
+React, Next.js, and Angular adapters must stay thin. They should call the browser SDK and should not reimplement:
+
+- Consent logic.
+- Identity/session logic.
+- Delivery queues.
+- Payload construction.
+- Attribution extraction.
+- Privacy filtering.
+
+Expected flow:
+
+```text
+React / Next / Angular
+  -> src/browser/client.ts
+  -> src/browser/core/DriveMetaDataSDK.ts
+  -> src/browser/core/*
+  -> src/core/*
+```
+
+## Node Boundary Rule
+
+The Node entry point must remain server-only and must not import browser runtime modules. It can use `src/core` for payload construction, backend payload validation, UUIDs, and shared types.
+
+Expected flow:
+
+```text
+src/node/*
+  -> src/core/backend-payload.ts
+  -> src/core/backend-schema.ts
+  -> src/core/uuid.ts
+```
+
+## Release Rule
+
+Before publishing, runtime boundaries should be verified by package and SSR import tests. Browser-only modules must not be imported by the Node entry point.

package/docs/index.md

@@ -13,5 +13,6 @@
 
 ## Enterprise Readiness
 
+- [Architecture](./architecture.md)
 - [Security and Privacy](./security-privacy.md)
 - [Release Checklist](./release-checklist.md)

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,68 @@ 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`:
+
+| Field | Format | Notes |
+|---|---|---|
+| `timestamp` | `YYYY-MM-DD HH:mm:ss` | UTC, no milliseconds, no timezone suffix |
+| `requestSentAt` | `YYYY-MM-DD HH:mm:ss` | UTC, no milliseconds, no timezone suffix |
+| `requestReceivedAt` | `YYYY-MM-DD HH:mm:ss` | UTC, no milliseconds, no timezone suffix |
+
+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:
@@ -116,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
@@ -128,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();
@@ -147,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={{
@@ -164,6 +303,7 @@ export function AnalyticsProvider({ children }: { children: React.ReactNode }) {
         consent: { analytics: 'pending', advertising: 'denied' }
       }}
     >
+      <RouteTracking />
       {children}
     </DmdProvider>
   );
@@ -174,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>
@@ -193,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);
@@ -230,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({
@@ -241,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');
   }
 }
@@ -284,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:
@@ -304,6 +488,20 @@ Common drop reasons:
 | `queue_limit_exceeded` | Offline queue is full | Flush more often or increase queue size |
 | `queue_ttl_expired` | Event stayed offline past TTL | Increase TTL only if business requirements allow it |
 
+## Backend Payload IDs
+
+The SDK sends `requestId`, `anonymousId`, and `sessionId` as UUID strings in `metaData`.
+
+```json
+{
+  "metaData": {
+    "requestId": "019de75e-dd28-779b-8084-2b3091b6de32",
+    "anonymousId": "019c8fe4-1fc7-7898-8089-f951a8bbfefb",
+    "sessionId": "019de75e-db3f-75e2-8054-0167411aa4ba"
+  }
+}
+```
+
 ## Production Checklist
 
 - Use `@drivemetadata-ai/sdk/browser`, `/react`, `/next`, or `/angular` only for public browser tokens.

package/docs/npm-browser-sdk.md

@@ -137,3 +137,7 @@ Common drop reasons:
 Delivery behavior:
 
 The browser SDK adds message IDs and idempotency keys to delivery payloads. Queue diagnostics include expired records, and queue flushing uses a cross-tab lease to avoid duplicate ownership when multiple tabs are open.
+
+`metaData.requestId`, `metaData.anonymousId`, and `metaData.sessionId` are UUID strings.
+
+`metaData.timestamp`, `metaData.requestSentAt`, and `metaData.requestReceivedAt` use UTC `YYYY-MM-DD HH:mm:ss` format. Invalid timestamp strings are normalized to the current UTC time before sending.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@drivemetadata-ai/sdk",
-  "version": "0.1.1-beta.2",
-  "description": "Enterprise-grade DriveMetaData browser SDK.",
+  "version": "0.1.1",
+  "description": "DriveMetaData JavaScript and TypeScript SDK.",
   "license": "MIT",
   "type": "module",
   "publishConfig": {
@@ -10,6 +10,7 @@
   "files": [
     "dist",
     "docs/index.md",
+    "docs/architecture.md",
     "docs/integration.md",
     "docs/npm-browser-sdk.md",
     "docs/react-next-integration.md",
@@ -58,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"