@drivemetadata-ai/sdk 0.1.1-beta.1

package/docs/node-server-integration.md

@@ -0,0 +1,138 @@
+# Node Server Integration
+
+Use `@drivemetadata/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
+```
+
+## Create Client
+
+```ts
+import { createDmdServerClient } from '@drivemetadata/sdk/node';
+
+const dmd = createDmdServerClient({
+  writeKey: process.env.DMD_SERVER_WRITE_KEY!,
+  endpoint: 'https://sdk.drivemetadata.com/v2/data-collector',
+  timeoutMs: 5000,
+  retry: {
+    attempts: 3,
+    minDelayMs: 250,
+    maxDelayMs: 2000
+  }
+});
+```
+
+## Track Event
+
+```ts
+await dmd.track({
+  userId: 'user_123',
+  event: 'Invoice Paid',
+  messageId: 'evt_123',
+  idempotencyKey: 'invoice_123',
+  properties: {
+    amount: 500,
+    currency: 'USD'
+  }
+});
+```
+
+## Idempotency
+
+Pass `messageId` when you already have a unique event ID and `idempotencyKey` when retrying business events such as orders, invoices, or subscriptions.
+
+```ts
+await dmd.track({
+  userId: 'user_123',
+  event: 'Order Completed',
+  messageId: 'evt_123',
+  idempotencyKey: 'order_123'
+});
+```
+
+## Batch
+
+```ts
+await dmd.batch([
+  { type: 'track', payload: { userId: 'user_123', event: 'Order Completed' } },
+  { type: 'identify', payload: { userId: 'user_123', traits: { plan: 'pro' } } }
+]);
+```
+
+## Identify User
+
+```ts
+await dmd.identify({
+  userId: 'user_123',
+  traits: {
+    plan: 'enterprise',
+    seats: 25
+  }
+});
+```
+
+## Page Event
+
+```ts
+await dmd.page({
+  userId: 'user_123',
+  name: 'Billing Settings',
+  properties: {
+    source: 'server_render'
+  }
+});
+```
+
+## Alias User
+
+```ts
+await dmd.alias({
+  previousId: 'anonymous_123',
+  userId: 'user_123'
+});
+```
+
+## Group User
+
+```ts
+await dmd.group({
+  userId: 'user_123',
+  groupId: 'account_456',
+  traits: {
+    companyName: 'Acme Inc'
+  }
+});
+```
+
+## Runtime Requirements
+
+The Node SDK requires Node.js 18+ because it uses global `fetch`. For older runtimes, pass a custom fetch implementation:
+
+```ts
+const dmd = createDmdServerClient({
+  writeKey: process.env.DMD_SERVER_WRITE_KEY!,
+  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.
+
+Store server keys in backend-only environment variables:
+
+```ts
+const dmd = createDmdServerClient({
+  writeKey: process.env.DMD_SERVER_WRITE_KEY!,
+  timeoutMs: 3000
+});
+```
+
+## Reliability
+
+Use `timeoutMs` to cap request time and `retry` to retry transient failures such as `408`, `429`, and `5xx` responses. Timeout timers are cleaned up after each request settles.

package/docs/npm-browser-sdk.md

@@ -0,0 +1,143 @@
+# Browser NPM SDK
+
+Install:
+
+```bash
+npm install @drivemetadata/sdk
+```
+
+Import:
+
+```ts
+import {
+  alias,
+  consent,
+  flush,
+  getDmdHealth,
+  group,
+  identify,
+  initDmdSDK,
+  page,
+  reset,
+  track
+} from '@drivemetadata/sdk/browser';
+```
+
+Initialize in browser runtime:
+
+```ts
+initDmdSDK({
+  clientId: 'client_xxx',
+  workspaceId: 'workspace_xxx',
+  appId: 'app_xxx',
+  writeKey: 'public_write_key',
+  consent: {
+    analytics: 'granted',
+    advertising: 'denied',
+    personalization: 'denied',
+    functional: 'granted',
+    saleOfData: 'denied'
+  }
+});
+```
+
+If `consent` is omitted, analytics defaults to `pending` and events are dropped until consent is granted.
+
+Track event:
+
+```ts
+track('Product Viewed', {
+  productId: 'sku_123'
+});
+```
+
+Identify user:
+
+```ts
+identify('user_123', {
+  plan: 'enterprise'
+});
+```
+
+Track page view:
+
+```ts
+page();
+```
+
+Group account:
+
+```ts
+group('account_123', {
+  tier: 'enterprise'
+});
+```
+
+Alias anonymous to known user:
+
+```ts
+alias('anonymous_123', 'user_123');
+```
+
+Update consent:
+
+```ts
+consent.update({
+  analytics: 'denied',
+  advertising: 'denied'
+});
+```
+
+Reset identity on logout:
+
+```ts
+reset();
+```
+
+Inspect health:
+
+```ts
+console.log(getDmdHealth());
+```
+
+Flush queued events:
+
+```ts
+await flush();
+```
+
+SSR note:
+
+The browser package can be imported during SSR, but `initDmdSDK` must run only in the browser. For Next.js, call it inside a client component or use the React/Next adapter from a later SDK phase.
+
+Diagnostics:
+
+`getDmdHealth()` reports initialized state, consent state, queue size, offline state, dropped-event count, last error, and last dropped-event reason.
+
+## Delivery Troubleshooting
+
+Use `getDmdHealth()` to inspect queue size, offline state, last error, and dropped delivery records.
+
+```ts
+import { flush, getDmdHealth } from '@drivemetadata/sdk/browser';
+
+console.log(getDmdHealth());
+await flush();
+```
+
+Common drop reasons:
+
+| Reason | Meaning | Fix |
+|---|---|---|
+| `consent_denied` | Analytics consent is not granted | Call `setConsent({ analytics: 'granted' })` after user consent |
+| `payload_too_large` | Event exceeds configured payload size | Reduce properties or increase `delivery.maxPayloadBytes` |
+| `queue_limit_exceeded` | Offline queue is full | Increase `delivery.maxQueueSize` or flush more often |
+| `queue_ttl_expired` | Event stayed offline past TTL | Increase `delivery.queueTtlMs` if appropriate |
+
+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

@@ -0,0 +1,168 @@
+# React and Next.js Integration
+
+## Install
+
+```bash
+npm install @drivemetadata/sdk
+```
+
+## React
+
+Wrap your application once:
+
+```tsx
+import { DmdProvider } from '@drivemetadata/sdk/react';
+
+export function App() {
+  return (
+    <DmdProvider
+      config={{
+        clientId: 'client_xxx',
+        workspaceId: 'workspace_xxx',
+        appId: 'app_xxx',
+        writeKey: 'public_write_key',
+        consent: { analytics: 'granted', advertising: 'denied' }
+      }}
+    >
+      <Routes />
+    </DmdProvider>
+  );
+}
+```
+
+Track events:
+
+```tsx
+import { useTrackEvent } from '@drivemetadata/sdk/react';
+
+export function CTAButton() {
+  const track = useTrackEvent();
+
+  return (
+    <button onClick={() => track('CTA Clicked', { location: 'pricing' })}>
+      Start
+    </button>
+  );
+}
+```
+
+Use the complete browser client surface from hooks:
+
+```tsx
+import {
+  useAlias,
+  useDmdFlush,
+  useGroup,
+  useIdentify,
+  usePage,
+  useReset,
+  useTrackEvent
+} from '@drivemetadata/sdk/react';
+
+export function AnalyticsActions() {
+  const track = useTrackEvent();
+  const page = usePage();
+  const identify = useIdentify();
+  const group = useGroup();
+  const alias = useAlias();
+  const flush = useDmdFlush();
+  const reset = useReset();
+
+  async function onCheckout() {
+    identify('user_123', { plan: 'enterprise' });
+    group('account_123', { tier: 'enterprise' });
+    alias('anonymous_123', 'user_123');
+    page('Checkout');
+    track('Checkout Started', { source: 'cart' });
+    await flush();
+  }
+
+  return (
+    <>
+      <button onClick={onCheckout}>Track checkout</button>
+      <button onClick={reset}>Reset</button>
+    </>
+  );
+}
+```
+
+## Next.js App Router
+
+Create a client provider:
+
+```tsx
+'use client';
+
+import { DmdProvider, useDmdAppRouterPageTracking } from '@drivemetadata/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(), {
+    name: 'Route Viewed'
+  });
+
+  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!,
+        writeKey: process.env.NEXT_PUBLIC_DMD_WRITE_KEY!,
+        consent: { analytics: 'granted', advertising: 'denied' }
+      }}
+    >
+      {children}
+    </DmdProvider>
+  );
+}
+```
+
+Use it in `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
+
+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';
+
+function AnalyticsPageTracking() {
+  const router = useRouter();
+  useDmdPagesRouterPageTracking(router);
+  return null;
+}
+
+export default function App({ Component, pageProps }: AppProps) {
+  return (
+    <DmdProvider config={config}>
+      <AnalyticsPageTracking />
+      <Component {...pageProps} />
+    </DmdProvider>
+  );
+}
+```
+
+## 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'`.
+
+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

@@ -0,0 +1,128 @@
+# Security and Privacy
+
+## Public and Server Keys
+
+Use public write keys only in browser, React, Next.js, and Angular integrations.
+
+Use server write keys only with `@drivemetadata/sdk/node` in backend environments.
+
+Never expose server write keys 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';
+
+initDmdSDK({
+  clientId: 'client_xxx',
+  workspaceId: 'workspace_xxx',
+  appId: 'app_xxx',
+  writeKey: 'public_write_key',
+  consent: {
+    analytics: 'pending',
+    advertising: 'denied',
+    personalization: 'denied',
+    functional: 'granted',
+    saleOfData: 'denied'
+  }
+});
+
+consent.update({
+  analytics: 'granted',
+  advertising: 'denied'
+});
+```
+
+Supported consent states:
+
+- `pending`
+- `granted`
+- `denied`
+
+Supported purposes:
+
+- `analytics`
+- `advertising`
+- `personalization`
+- `functional`
+- `saleOfData`
+
+When analytics consent is denied, analytics events are dropped. When advertising consent is denied, advertising identifiers should not be collected or forwarded.
+
+## PII Controls
+
+Use SDK masking and denylist options to reduce accidental sensitive data collection:
+
+```ts
+initDmdSDK({
+  clientId: 'client_xxx',
+  workspaceId: 'workspace_xxx',
+  appId: 'app_xxx',
+  writeKey: 'public_write_key',
+  maskAllText: true,
+  maskAllElementAttributes: true,
+  propertyDenylist: ['password', 'token', 'secret']
+});
+```
+
+The npm browser core removes common raw PII fields such as `email`, `phone`, address fields, `token`, `secret`, and `password` from event properties by default. URL redaction should preserve UTM parameters while replacing sensitive query values.
+
+## Form Capture
+
+Sensitive form fields should be denied or masked. Passwords, payment data, tokens, authentication fields, and government identifiers should never be captured as plain text.
+
+## Shopify Privacy
+
+The Shopify pixel adapter reads Shopify `customerPrivacy` when available. If `analyticsProcessingAllowed()` returns `false`, checkout and other pixel events are blocked before calling the SDK. The adapter also subscribes to `visitorConsentCollected` so consent changes during the session update tracking behavior.
+
+Raw checkout PII is not sent by default. Checkout email, phone, name, and address values are removed from default pixel event payloads.
+
+## Regional Endpoints
+
+Use `apiHost` to route events to the correct regional collector endpoint when required by customer policy.
+
+```ts
+initDmdSDK({
+  clientId: 'client_xxx',
+  workspaceId: 'workspace_xxx',
+  appId: 'app_xxx',
+  writeKey: 'public_write_key',
+  apiHost: 'https://eu-sdk.drivemetadata.com/v2'
+});
+```
+
+## Diagnostics
+
+Use `getDmdHealth()` to inspect SDK state and dropped-event diagnostics during integration:
+
+```ts
+import { getDmdHealth } from '@drivemetadata/sdk/browser';
+
+console.log(getDmdHealth());
+```
+
+Browser delivery uses message IDs, idempotency keys, queue TTL diagnostics, and a cross-tab flush lease so multiple tabs do not own queue flushing at the same time.
+
+## Enterprise Privacy Checklist
+
+- 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.
+- PII masking is recursive for common direct identifiers.
+- Customers should configure retention, region, DPA, and subprocessor review before production.
+
+## Enterprise Review Topics
+
+Customers should complete these reviews before production:
+
+| Topic | SDK Support | Customer Action |
+|---|---|---|
+| 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 |
+| 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

@@ -0,0 +1,100 @@
+{
+  "name": "@drivemetadata-ai/sdk",
+  "version": "0.1.1-beta.1",
+  "description": "Enterprise-grade DriveMetaData browser SDK.",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "docs/index.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"
+  ],
+  "sideEffects": false,
+  "exports": {
+    "./browser": {
+      "types": "./dist/browser/index.d.ts",
+      "import": "./dist/browser/index.js",
+      "require": "./dist/browser/index.cjs"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "require": "./dist/react/index.cjs"
+    },
+    "./next": {
+      "types": "./dist/next/index.d.ts",
+      "import": "./dist/next/index.js",
+      "require": "./dist/next/index.cjs"
+    },
+    "./angular": {
+      "types": "./dist/angular/index.d.ts",
+      "import": "./dist/angular/index.js",
+      "require": "./dist/angular/index.cjs"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "import": "./dist/node/index.js",
+      "require": "./dist/node/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "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"
+  },
+  "peerDependencies": {
+    "@angular/core": ">=16 <21",
+    "next": ">=13 <16",
+    "react": ">=18 <20",
+    "react-dom": ">=18 <20"
+  },
+  "peerDependenciesMeta": {
+    "@angular/core": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@angular/core": "^20.0.0",
+    "@testing-library/react": "^16.0.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "jsdom": "^26.0.0",
+    "next": "^15.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  }
+}