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

package/docs/integration.md

@@ -0,0 +1,322 @@
+# 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'
+};
+```
+
+Node integrations use a server token stored only in backend environment variables:
+
+```bash
+DMD_SERVER_TOKEN=server_write_key
+```
+
+## 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());
+```
+
+## 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>
+  );
+}
+```
+
+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.update({ 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';
+
+export function AnalyticsProvider({ children }: { children: React.ReactNode }) {
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+
+  useDmdAppRouterPageTracking(pathname, searchParams.toString());
+
+  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' }
+      }}
+    >
+      {children}
+    </DmdProvider>
+  );
+}
+```
+
+Use it from `app/layout.tsx`:
+
+```tsx
+import { AnalyticsProvider } from './AnalyticsProvider';
+
+export default function RootLayout({ children }: { children: React.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';
+
+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' }
+    })
+  ]
+};
+```
+
+Initialize and track:
+
+```ts
+import { Component, OnInit } 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) {}
+
+  ngOnInit() {
+    this.dmd.init();
+    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.
+
+## 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 |
+
+## 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)

package/docs/node-server-integration.md

@@ -1,22 +1,25 @@
 # Node Server Integration
 
-Use `@drivemetadata/sdk/node` for backend events only.
+Use `@drivemetadata-ai/sdk/node` for backend events only.
 
 Do not use the browser SDK in server code. Browser analytics depends on DOM, cookies, localStorage, sessionStorage, page lifecycle, and session behavior.
 
 ## Install
 
 ```bash
-npm install @drivemetadata/sdk
+npm install @drivemetadata-ai/sdk
 ```
 
 ## Create Client
 
 ```ts
-import { createDmdServerClient } from '@drivemetadata/sdk/node';
+import { createDmdServerClient } from '@drivemetadata-ai/sdk/node';
 
 const dmd = createDmdServerClient({
-  writeKey: process.env.DMD_SERVER_WRITE_KEY!,
+  clientId: 'client_xxx',
+  workspaceId: 'workspace_xxx',
+  appId: 'app_xxx',
+  token: process.env.DMD_SERVER_TOKEN!,
   endpoint: 'https://sdk.drivemetadata.com/v2/data-collector',
   timeoutMs: 5000,
   retry: {
@@ -115,20 +118,26 @@ The Node SDK requires Node.js 18+ because it uses global `fetch`. For older runt
 
 ```ts
 const dmd = createDmdServerClient({
-  writeKey: process.env.DMD_SERVER_WRITE_KEY!,
+  clientId: 'client_xxx',
+  workspaceId: 'workspace_xxx',
+  appId: 'app_xxx',
+  token: process.env.DMD_SERVER_TOKEN!,
   fetch: customFetch
 });
 ```
 
 ## Server Key Safety
 
-Use `@drivemetadata/sdk/node` only in server runtimes. Never import this entry point from browser bundles, React client components, Angular browser bundles, or Next.js client components.
+Use `@drivemetadata-ai/sdk/node` only in server runtimes. Never import this entry point from browser bundles, React client components, Angular browser bundles, or Next.js client components.
 
 Store server keys in backend-only environment variables:
 
 ```ts
 const dmd = createDmdServerClient({
-  writeKey: process.env.DMD_SERVER_WRITE_KEY!,
+  clientId: 'client_xxx',
+  workspaceId: 'workspace_xxx',
+  appId: 'app_xxx',
+  token: process.env.DMD_SERVER_TOKEN!,
   timeoutMs: 3000
 });
 ```

package/docs/npm-browser-sdk.md

@@ -3,7 +3,7 @@
 Install:
 
 ```bash
-npm install @drivemetadata/sdk
+npm install @drivemetadata-ai/sdk
 ```
 
 Import:
@@ -20,7 +20,7 @@ import {
   page,
   reset,
   track
-} from '@drivemetadata/sdk/browser';
+} from '@drivemetadata-ai/sdk/browser';
 ```
 
 Initialize in browser runtime:
@@ -30,7 +30,7 @@ initDmdSDK({
   clientId: 'client_xxx',
   workspaceId: 'workspace_xxx',
   appId: 'app_xxx',
-  writeKey: 'public_write_key',
+  token: 'public_token',
   consent: {
     analytics: 'granted',
     advertising: 'denied',
@@ -119,7 +119,7 @@ Diagnostics:
 Use `getDmdHealth()` to inspect queue size, offline state, last error, and dropped delivery records.
 
 ```ts
-import { flush, getDmdHealth } from '@drivemetadata/sdk/browser';
+import { flush, getDmdHealth } from '@drivemetadata-ai/sdk/browser';
 
 console.log(getDmdHealth());
 await flush();
@@ -137,7 +137,3 @@ 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.
-
-Legacy note:
-
-The current CDN script `javascript/dmdSDK_v3.js` remains supported. The npm browser entry now initializes without requiring the CDN global, while legacy script customers keep the global constructor path.

package/docs/react-next-integration.md

@@ -3,7 +3,7 @@
 ## Install
 
 ```bash
-npm install @drivemetadata/sdk
+npm install @drivemetadata-ai/sdk
 ```
 
 ## React
@@ -11,7 +11,7 @@ npm install @drivemetadata/sdk
 Wrap your application once:
 
 ```tsx
-import { DmdProvider } from '@drivemetadata/sdk/react';
+import { DmdProvider } from '@drivemetadata-ai/sdk/react';
 
 export function App() {
   return (
@@ -20,7 +20,7 @@ export function App() {
         clientId: 'client_xxx',
         workspaceId: 'workspace_xxx',
         appId: 'app_xxx',
-        writeKey: 'public_write_key',
+        token: 'public_token',
         consent: { analytics: 'granted', advertising: 'denied' }
       }}
     >
@@ -33,7 +33,7 @@ export function App() {
 Track events:
 
 ```tsx
-import { useTrackEvent } from '@drivemetadata/sdk/react';
+import { useTrackEvent } from '@drivemetadata-ai/sdk/react';
 
 export function CTAButton() {
   const track = useTrackEvent();
@@ -57,7 +57,7 @@ import {
   usePage,
   useReset,
   useTrackEvent
-} from '@drivemetadata/sdk/react';
+} from '@drivemetadata-ai/sdk/react';
 
 export function AnalyticsActions() {
   const track = useTrackEvent();
@@ -93,7 +93,7 @@ Create a client provider:
 ```tsx
 'use client';
 
-import { DmdProvider, useDmdAppRouterPageTracking } from '@drivemetadata/sdk/next';
+import { DmdProvider, useDmdAppRouterPageTracking } from '@drivemetadata-ai/sdk/next';
 import { usePathname, useSearchParams } from 'next/navigation';
 
 export function AnalyticsProvider({ children }: { children: React.ReactNode }) {
@@ -110,7 +110,7 @@ export function AnalyticsProvider({ children }: { children: React.ReactNode }) {
         clientId: process.env.NEXT_PUBLIC_DMD_CLIENT_ID!,
         workspaceId: process.env.NEXT_PUBLIC_DMD_WORKSPACE_ID!,
         appId: process.env.NEXT_PUBLIC_DMD_APP_ID!,
-        writeKey: process.env.NEXT_PUBLIC_DMD_WRITE_KEY!,
+        token: process.env.NEXT_PUBLIC_DMD_TOKEN!,
         consent: { analytics: 'granted', advertising: 'denied' }
       }}
     >
@@ -143,7 +143,7 @@ Use a provider in `_app.tsx`:
 ```tsx
 import type { AppProps } from 'next/app';
 import { useRouter } from 'next/router';
-import { DmdProvider, useDmdPagesRouterPageTracking } from '@drivemetadata/sdk/next';
+import { DmdProvider, useDmdPagesRouterPageTracking } from '@drivemetadata-ai/sdk/next';
 
 function AnalyticsPageTracking() {
   const router = useRouter();
@@ -163,6 +163,6 @@ export default function App({ Component, pageProps }: AppProps) {
 
 ## SSR Safety
 
-`@drivemetadata/sdk/react` and `@drivemetadata/sdk/next` can be imported during server rendering, but SDK initialization must run in the browser. In Next.js App Router, place `DmdProvider` inside a file that starts with `'use client'`.
+`@drivemetadata-ai/sdk/react` and `@drivemetadata-ai/sdk/next` can be imported during server rendering, but SDK initialization must run in the browser. In Next.js App Router, place `DmdProvider` inside a file that starts with `'use client'`.
 
 If consent is omitted, analytics defaults to `pending`; call `consent.update()` or pass an explicit consent object after your consent manager resolves.

package/docs/security-privacy.md

@@ -2,24 +2,24 @@
 
 ## Public and Server Keys
 
-Use public write keys only in browser, React, Next.js, and Angular integrations.
+Use public browser tokens only in browser, React, Next.js, and Angular integrations.
 
-Use server write keys only with `@drivemetadata/sdk/node` in backend environments.
+Use server tokens only with `@drivemetadata-ai/sdk/node` in backend environments.
 
-Never expose server write keys through `NEXT_PUBLIC_`, frontend build variables, script tags, or mobile clients.
+Never expose server tokens through `NEXT_PUBLIC_`, frontend build variables, script tags, or mobile clients.
 
 ## Consent
 
 Use consent controls before tracking users in regulated environments:
 
 ```ts
-import { consent, initDmdSDK } from '@drivemetadata/sdk/browser';
+import { consent, initDmdSDK } from '@drivemetadata-ai/sdk/browser';
 
 initDmdSDK({
   clientId: 'client_xxx',
   workspaceId: 'workspace_xxx',
   appId: 'app_xxx',
-  writeKey: 'public_write_key',
+  token: 'public_token',
   consent: {
     analytics: 'pending',
     advertising: 'denied',
@@ -60,7 +60,7 @@ initDmdSDK({
   clientId: 'client_xxx',
   workspaceId: 'workspace_xxx',
   appId: 'app_xxx',
-  writeKey: 'public_write_key',
+  token: 'public_token',
   maskAllText: true,
   maskAllElementAttributes: true,
   propertyDenylist: ['password', 'token', 'secret']
@@ -88,7 +88,7 @@ initDmdSDK({
   clientId: 'client_xxx',
   workspaceId: 'workspace_xxx',
   appId: 'app_xxx',
-  writeKey: 'public_write_key',
+  token: 'public_token',
   apiHost: 'https://eu-sdk.drivemetadata.com/v2'
 });
 ```
@@ -98,7 +98,7 @@ initDmdSDK({
 Use `getDmdHealth()` to inspect SDK state and dropped-event diagnostics during integration:
 
 ```ts
-import { getDmdHealth } from '@drivemetadata/sdk/browser';
+import { getDmdHealth } from '@drivemetadata-ai/sdk/browser';
 
 console.log(getDmdHealth());
 ```
@@ -109,8 +109,8 @@ Browser delivery uses message IDs, idempotency keys, queue TTL diagnostics, and
 
 - Default analytics consent is `pending`.
 - Advertising storage must remain denied until advertising consent is granted.
-- Browser examples must use public write keys only.
-- Server write keys must be used only from server runtimes.
+- Browser examples must use public browser tokens only.
+- Server tokens must be used only from server runtimes.
 - PII masking is recursive for common direct identifiers.
 - Customers should configure retention, region, DPA, and subprocessor review before production.
 
@@ -123,6 +123,6 @@ Customers should complete these reviews before production:
 | Legal basis | Consent states and purpose-level controls | Connect SDK consent to CMP |
 | Data retention | Event delivery includes timestamps and customer IDs | Confirm retention policy in backend/product |
 | Data residency | `apiHost` supports regional collectors | Use approved regional endpoint |
-| Server keys | Node entry keeps keys server-side | Store keys only in backend secrets |
+| Server tokens | Node entry keeps tokens server-side | Store tokens only in backend secrets |
 | Subprocessors | Not enforced in SDK code | Review company subprocessor list |
 | PII minimization | Recursive common PII redaction | Configure denylist and avoid sensitive properties |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drivemetadata-ai/sdk",
-  "version": "0.1.1-beta.1",
+  "version": "0.1.1-beta.2",
   "description": "Enterprise-grade DriveMetaData browser SDK.",
   "license": "MIT",
   "type": "module",
@@ -10,12 +10,12 @@
   "files": [
     "dist",
     "docs/index.md",
+    "docs/integration.md",
     "docs/npm-browser-sdk.md",
     "docs/react-next-integration.md",
     "docs/angular-integration.md",
     "docs/node-server-integration.md",
     "docs/security-privacy.md",
-    "docs/migration-cdn-to-npm.md",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -56,12 +56,11 @@
     "build": "tsup",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "test:legacy": "node tests/dmdSDK_v3.browser.test.js && node tests/dmdSDK_v3.consent.test.js && node tests/dmdSDK_v3.integration.test.js && node tests/dmdSDK_v3.payload.test.js && node tests/dmdSDK_v3.privacy.test.js && node tests/dmdSDK_v3.schema.unit.test.js && node tests/dmdSDK_v3.singleton.test.js && node tests/dmdSDK_v3.storage.test.js",
     "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:check": "npm run ci && npm_config_cache=/tmp/npm-cache npm run pack:check",
-    "ci": "npm run typecheck && npm run test && npm run test:legacy && npm run build && npm run test:package",
-    "ci:phase1": "npm run typecheck && npm run test && npm run test:legacy && npm run build"
+    "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"
   },
   "peerDependencies": {
     "@angular/core": ">=16 <21",