@drivemetadata-ai/sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0
+
+- Added npm package foundation.
+- Added browser SDK facade.
+- Added React adapter.
+- Added Next.js adapter.
+- Added Angular adapter.
+- Added Node/server SDK.
+- Added diagnostics and release validation.
+- Preserved existing JavaScript/CDN SDK compatibility.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DriveMetaData
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,241 @@
+# DriveMetaData SDK
+
+Enterprise-grade analytics, behavior intelligence, and customer data collection SDK for browser apps, React, Next.js, Angular, and Node.js.
+
+## Install
+
+```bash
+npm install @drivemetadata-ai/sdk
+```
+
+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
+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
+
+```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_browser_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 events automatically include backend `metaData` fields such as `requestId`, `anonymousId`, `sessionId`, timestamps, attribution/UTM enrichment, and page context.
+
+## React
+
+```tsx
+import { DmdProvider, useDmdConsent, useDmdFlush, useIdentify, useTrackEvent } from '@drivemetadata-ai/sdk/react';
+
+function ProductButton() {
+  const track = useTrackEvent();
+  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={{
+        clientId: 'client_xxx',
+        workspaceId: 'workspace_xxx',
+        appId: 'app_xxx',
+        token: 'public_browser_token',
+        consent: { analytics: 'pending', advertising: 'denied' }
+      }}
+    >
+      <ProductButton />
+    </DmdProvider>
+  );
+}
+```
+
+## Next.js
+
+Use `@drivemetadata-ai/sdk/next` from a client component.
+
+```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>
+  );
+}
+```
+
+## 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
+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',
+  idempotencyKey: 'order_123',
+  properties: {
+    amount: 500,
+    currency: 'USD'
+  }
+});
+```
+
+## 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();
+```
+
+Useful drop reasons include `consent_denied`, `payload_too_large`, `queue_limit_exceeded`, and `queue_ttl_expired`.
+
+## Documentation
+
+- Complete integration guide: `docs/integration.md`
+- Browser npm SDK: `docs/npm-browser-sdk.md`
+- React and Next.js: `docs/react-next-integration.md`
+- Angular: `docs/angular-integration.md`
+- Node/server: `docs/node-server-integration.md`
+- Security and privacy: `docs/security-privacy.md`
+
+## License
+
+MIT