@drivemetadata-ai/sdk 0.1.0

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

@@ -0,0 +1,18 @@
+# DriveMetaData SDK Documentation
+
+## Start Here
+
+- [Complete Integration Guide](./integration.md)
+
+## Integration Guides
+
+- [Browser NPM SDK](./npm-browser-sdk.md)
+- [React and Next.js](./react-next-integration.md)
+- [Angular](./angular-integration.md)
+- [Node Server](./node-server-integration.md)
+
+## Enterprise Readiness
+
+- [Architecture](./architecture.md)
+- [Security and Privacy](./security-privacy.md)
+- [Release Checklist](./release-checklist.md)

package/docs/integration.md

@@ -0,0 +1,520 @@
+# DriveMetaData SDK Integration Guide
+
+This guide covers the npm package integration path for browser apps, React, Next.js, Angular, and Node.js.
+
+## Package
+
+```bash
+npm install @drivemetadata-ai/sdk
+```
+
+Runtime entry points:
+
+| 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` | Client-safe React helpers plus route tracking hooks |
+| Angular | `@drivemetadata-ai/sdk/angular` | Angular provider and injectable service |
+| Node.js | `@drivemetadata-ai/sdk/node` | Backend/server events only |
+
+Do not import the Node entry point from browser bundles. Do not initialize the browser SDK during server rendering.
+
+## Required Keys
+
+Browser and framework integrations use public browser tokens:
+
+```ts
+const browserConfig = {
+  clientId: 'client_xxx',
+  workspaceId: 'workspace_xxx',
+  appId: 'app_xxx',
+  token: 'public_token'
+};
+```
+
+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.
+
+```ts
+consent: {
+  analytics: 'pending',
+  advertising: 'denied',
+  personalization: 'denied',
+  functional: 'granted',
+  saleOfData: 'denied'
+}
+```
+
+If consent is omitted, analytics defaults to `pending` and events are dropped until consent is granted.
+
+## Browser Integration
+
+```ts
+import {
+  consent,
+  flush,
+  getDmdHealth,
+  identify,
+  initDmdSDK,
+  page,
+  track
+} from '@drivemetadata-ai/sdk/browser';
+
+const dmd = initDmdSDK({
+  clientId: 'client_xxx',
+  workspaceId: 'workspace_xxx',
+  appId: 'app_xxx',
+  token: 'public_token',
+  consent: {
+    analytics: 'pending',
+    advertising: 'denied',
+    personalization: 'denied',
+    functional: 'granted',
+    saleOfData: 'denied'
+  }
+});
+
+consent.update({ analytics: 'granted' });
+
+identify('user_123', { plan: 'enterprise' });
+page('Product Page');
+track('Product Viewed', { productId: 'sku_123' });
+
+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:
+
+```tsx
+import { DmdProvider } from '@drivemetadata-ai/sdk/react';
+
+export function App() {
+  return (
+    <DmdProvider
+      config={{
+        clientId: 'client_xxx',
+        workspaceId: 'workspace_xxx',
+        appId: 'app_xxx',
+        token: 'public_token',
+        consent: { analytics: 'pending', advertising: 'denied' }
+      }}
+    >
+      <Routes />
+    </DmdProvider>
+  );
+}
+```
+
+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
+import { useDmdConsent, useDmdFlush, useIdentify, useTrackEvent } from '@drivemetadata-ai/sdk/react';
+
+export function CheckoutButton() {
+  const track = useTrackEvent();
+  const identify = useIdentify();
+  const flush = useDmdFlush();
+  const consent = useDmdConsent();
+
+  async function onClick() {
+    consent({ analytics: 'granted' });
+    identify('user_123', { plan: 'enterprise' });
+    track('Checkout Started', { source: 'cart' });
+    await flush();
+  }
+
+  return <button onClick={onClick}>Checkout</button>;
+}
+```
+
+## Next.js App Router
+
+Create a client provider:
+
+```tsx
+'use client';
+
+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>
+  );
+}
+```
+
+Use it from `app/layout.tsx`:
+
+```tsx
+import { AnalyticsProvider } from './AnalyticsProvider';
+import type { ReactNode } from 'react';
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <AnalyticsProvider>{children}</AnalyticsProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+## Next.js Pages Router
+
+```tsx
+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);
+  return null;
+}
+
+export default function App({ Component, pageProps }: AppProps) {
+  return (
+    <DmdProvider config={config}>
+      <PageTracking />
+      <Component {...pageProps} />
+    </DmdProvider>
+  );
+}
+```
+
+## Angular Integration
+
+Register the provider:
+
+```ts
+import { ApplicationConfig } from '@angular/core';
+import { provideDmdAnalytics } from '@drivemetadata-ai/sdk/angular';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideDmdAnalytics({
+      clientId: 'client_xxx',
+      workspaceId: 'workspace_xxx',
+      appId: 'app_xxx',
+      token: 'public_token',
+      consent: { analytics: 'pending', advertising: 'denied' }
+    })
+  ]
+};
+```
+
+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 { isPlatformBrowser } from '@angular/common';
+import { Component, Inject, OnInit, PLATFORM_ID } from '@angular/core';
+import { DmdAnalyticsService } from '@drivemetadata-ai/sdk/angular';
+
+@Component({
+  selector: 'app-root',
+  template: '<router-outlet />'
+})
+export class AppComponent implements OnInit {
+  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');
+  }
+}
+```
+
+For Angular Universal, call `this.dmd.init()` only when `isPlatformBrowser(platformId)` is true.
+
+## Node Server Integration
+
+```ts
+import { createDmdServerClient } from '@drivemetadata-ai/sdk/node';
+
+const dmd = createDmdServerClient({
+  clientId: 'client_xxx',
+  workspaceId: 'workspace_xxx',
+  appId: 'app_xxx',
+  token: process.env.DMD_SERVER_TOKEN!,
+  timeoutMs: 5000,
+  retry: {
+    attempts: 3,
+    minDelayMs: 250,
+    maxDelayMs: 2000
+  }
+});
+
+await dmd.track({
+  userId: 'user_123',
+  event: 'Order Completed',
+  messageId: 'evt_123',
+  idempotencyKey: 'order_123',
+  properties: {
+    amount: 500,
+    currency: 'USD'
+  }
+});
+```
+
+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:
+
+```ts
+import { flush, getDmdHealth } from '@drivemetadata-ai/sdk/browser';
+
+console.log(getDmdHealth());
+await flush();
+```
+
+Common drop reasons:
+
+| Reason | Meaning | Fix |
+|---|---|---|
+| `consent_denied` | Analytics consent is not granted | Grant consent after the consent manager resolves |
+| `payload_too_large` | Event exceeds configured payload size | Reduce event properties |
+| `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.
+- Use `@drivemetadata-ai/sdk/node` only on the server with backend-only environment variables.
+- Start analytics consent as `pending` or `denied` until your consent manager grants it.
+- Call `flush()` before important navigation or checkout completion boundaries when needed.
+- Check `getDmdHealth()` during integration testing.
+- Verify SSR builds do not initialize browser analytics on the server.
+
+## More Guides
+
+- Browser SDK: [npm-browser-sdk.md](./npm-browser-sdk.md)
+- React and Next.js: [react-next-integration.md](./react-next-integration.md)
+- Angular: [angular-integration.md](./angular-integration.md)
+- Node server: [node-server-integration.md](./node-server-integration.md)
+- Security and privacy: [security-privacy.md](./security-privacy.md)