@gurulu/node 0.1.0 → 0.1.1

package/dist/{node-sdk/src/client.d.ts → client.d.ts}

@@ -23,6 +23,8 @@ export interface GuruluClient {
     track(event: ServerEvent): void;
     flush(): Promise<void>;
     shutdown(): Promise<void>;
+    captureException(error: Error, context?: Record<string, unknown>): void;
+    installGlobalHandlers(): void;
     /** Current queue length — exposed for tests and observability. */
     readonly queueSize: number;
 }
@@ -62,9 +64,27 @@ export declare class Gurulu implements GuruluClient {
      */
     flush(): Promise<void>;
     private sendBatch;
+    /**
+     * Capture an exception and send it as an error event.
+     */
+    captureException(error: Error, context?: Record<string, unknown>): void;
+    /**
+     * Install global error handlers for uncaught exceptions and unhandled rejections.
+     * Call once at app startup.
+     */
+    installGlobalHandlers(): void;
     /**
      * Stop the periodic flush timer, detach process listeners, and perform a
      * final flush. Safe to call multiple times.
      */
     shutdown(): Promise<void>;
 }
+/**
+ * Set the default Gurulu instance used by the convenience `captureException`.
+ */
+export declare function setDefaultInstance(instance: Gurulu): void;
+/**
+ * Convenience function — captures an exception via the default instance.
+ * Call `setDefaultInstance()` first (or create a Gurulu client).
+ */
+export declare function captureException(error: Error, context?: Record<string, unknown>): void;

package/dist/{node-sdk/src/client.js → client.js}

@@ -21,6 +21,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Gurulu = void 0;
 exports.createIdempotencyKey = createIdempotencyKey;
+exports.setDefaultInstance = setDefaultInstance;
+exports.captureException = captureException;
 const crypto_1 = require("crypto");
 const DEFAULT_ENDPOINT = 'https://app.gurulu.io/api/ingest/v1/server';
 const DEFAULT_FLUSH_INTERVAL = 5000;
@@ -223,6 +225,36 @@ class Gurulu {
             console.error('[gurulu] no dead-letter callback configured; events lost');
         }
     }
+    /**
+     * Capture an exception and send it as an error event.
+     */
+    captureException(error, context) {
+        this.track({
+            event_name: '$error',
+            user_id: context?.user_id || '__system__',
+            properties: {
+                error_message: error.message,
+                error_stack: error.stack || '',
+                error_type: error.name || 'Error',
+                ...context,
+            },
+        });
+    }
+    /**
+     * Install global error handlers for uncaught exceptions and unhandled rejections.
+     * Call once at app startup.
+     */
+    installGlobalHandlers() {
+        process.on('uncaughtException', (error) => {
+            this.captureException(error, { source: 'uncaughtException' });
+            // Flush before exit
+            this.flush().finally(() => process.exit(1));
+        });
+        process.on('unhandledRejection', (reason) => {
+            const error = reason instanceof Error ? reason : new Error(String(reason));
+            this.captureException(error, { source: 'unhandledRejection' });
+        });
+    }
     /**
      * Stop the periodic flush timer, detach process listeners, and perform a
      * final flush. Safe to call multiple times.
@@ -253,3 +285,23 @@ async function safeText(res) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/* ------------------------------------------------------------------ */
+/*  Singleton / default instance                                       */
+/* ------------------------------------------------------------------ */
+let defaultInstance = null;
+/**
+ * Set the default Gurulu instance used by the convenience `captureException`.
+ */
+function setDefaultInstance(instance) {
+    defaultInstance = instance;
+}
+/**
+ * Convenience function — captures an exception via the default instance.
+ * Call `setDefaultInstance()` first (or create a Gurulu client).
+ */
+function captureException(error, context) {
+    if (!defaultInstance) {
+        throw new Error('No default Gurulu instance. Call setDefaultInstance() first.');
+    }
+    defaultInstance.captureException(error, context);
+}

package/dist/{node-sdk/src/index.d.ts → index.d.ts}

@@ -4,7 +4,7 @@
  * Phase 10 W4.2: server SDK hardening adds batch+retry, deterministic
  * idempotency keys, dead-letter callbacks, and business event emitters.
  */
-export { Gurulu, createIdempotencyKey } from './client';
+export { Gurulu, createIdempotencyKey, captureException, setDefaultInstance } from './client';
 export type { GuruluClient } from './client';
 export type { GuruluClientConfig, DeadLetterCallback, ErrorCallback, } from './types';
 export type { Envelope, ServerEvent, EventTier, EventSource, ConsentLevel, } from '@gurulu/shared-core';

package/dist/{node-sdk/src/index.js → index.js}

@@ -6,10 +6,12 @@
  * idempotency keys, dead-letter callbacks, and business event emitters.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.leadCaptured = exports.orderPlaced = exports.subscriptionStarted = exports.paymentSucceeded = exports.userCreated = exports.createIdempotencyKey = exports.Gurulu = void 0;
+exports.leadCaptured = exports.orderPlaced = exports.subscriptionStarted = exports.paymentSucceeded = exports.userCreated = exports.setDefaultInstance = exports.captureException = exports.createIdempotencyKey = exports.Gurulu = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "Gurulu", { enumerable: true, get: function () { return client_1.Gurulu; } });
 Object.defineProperty(exports, "createIdempotencyKey", { enumerable: true, get: function () { return client_1.createIdempotencyKey; } });
+Object.defineProperty(exports, "captureException", { enumerable: true, get: function () { return client_1.captureException; } });
+Object.defineProperty(exports, "setDefaultInstance", { enumerable: true, get: function () { return client_1.setDefaultInstance; } });
 // Business event emitters (W4.2).
 var business_events_1 = require("./business-events");
 Object.defineProperty(exports, "userCreated", { enumerable: true, get: function () { return business_events_1.userCreated; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gurulu/node",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Gurulu.io server-side analytics SDK for Node.js",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/dist/shared-core/src/canonical-events.d.ts

@@ -1,35 +0,0 @@
-/**
- * Canonical Event Catalog — standardised event names and typed property
- * schemas shared across all Gurulu SDKs (web, iOS, Android, server).
- *
- * Every SDK exposes typed convenience helpers that delegate to the generic
- * `track()` method using the `$`-prefixed event names defined here. Users
- * can still call `track('$purchase', { ... })` directly; the helpers are
- * purely ergonomic.
- *
- * Property names are **snake_case** on all platforms.
- */
-export interface EventPropertySchema {
-    name: string;
-    type: 'string' | 'number' | 'boolean' | 'array' | 'object';
-    required: boolean;
-    description: string;
-}
-export type EventCategory = 'core' | 'acquisition' | 'activation' | 'revenue' | 'engagement' | 'retention' | 'referral';
-export interface CanonicalEvent {
-    /** Dollar-prefixed canonical name, e.g. `$purchase`. */
-    name: string;
-    /** Human-readable label for dashboards. */
-    displayName: string;
-    /** AARRR pirate-metrics category. */
-    category: EventCategory;
-    description: string;
-    properties: EventPropertySchema[];
-}
-export declare const CANONICAL_EVENTS: CanonicalEvent[];
-/** Retrieve a canonical event definition by its `$`-prefixed name. */
-export declare function getCanonicalEvent(name: string): CanonicalEvent | undefined;
-/** All canonical event names as a typed union. */
-export type CanonicalEventName = (typeof CANONICAL_EVENTS)[number]['name'];
-/** Set of all canonical event names for quick membership checks. */
-export declare const CANONICAL_EVENT_NAMES: ReadonlySet<string>;

package/dist/shared-core/src/canonical-events.js

@@ -1,225 +0,0 @@
-"use strict";
-/**
- * Canonical Event Catalog — standardised event names and typed property
- * schemas shared across all Gurulu SDKs (web, iOS, Android, server).
- *
- * Every SDK exposes typed convenience helpers that delegate to the generic
- * `track()` method using the `$`-prefixed event names defined here. Users
- * can still call `track('$purchase', { ... })` directly; the helpers are
- * purely ergonomic.
- *
- * Property names are **snake_case** on all platforms.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CANONICAL_EVENT_NAMES = exports.CANONICAL_EVENTS = void 0;
-exports.getCanonicalEvent = getCanonicalEvent;
-// ── Helper to reduce boilerplate ────────────────────────────────────────────
-function prop(name, type, description, required = false) {
-    return { name, type, required, description };
-}
-// ── Catalog ─────────────────────────────────────────────────────────────────
-exports.CANONICAL_EVENTS = [
-    // ─── Core ───────────────────────────────────────────────────────────────
-    {
-        name: '$page_view',
-        displayName: 'Page View',
-        category: 'core',
-        description: 'Fired when a user views a page or screen.',
-        properties: [
-            prop('url', 'string', 'Full URL of the page', true),
-            prop('title', 'string', 'Document title'),
-            prop('referrer', 'string', 'Referring URL'),
-        ],
-    },
-    {
-        name: '$session_start',
-        displayName: 'Session Start',
-        category: 'core',
-        description: 'Marks the beginning of a new session.',
-        properties: [],
-    },
-    {
-        name: '$session_end',
-        displayName: 'Session End',
-        category: 'core',
-        description: 'Marks the end of a session.',
-        properties: [
-            prop('duration_sec', 'number', 'Total session duration in seconds'),
-        ],
-    },
-    // ─── Acquisition ────────────────────────────────────────────────────────
-    {
-        name: '$signup',
-        displayName: 'Sign Up',
-        category: 'acquisition',
-        description: 'User created a new account.',
-        properties: [
-            prop('method', 'string', 'Authentication method (email, google, apple, github)'),
-        ],
-    },
-    {
-        name: '$app_install',
-        displayName: 'App Install',
-        category: 'acquisition',
-        description: 'Native app was installed on the device.',
-        properties: [
-            prop('install_source', 'string', 'Attribution source (e.g. play_store, app_store, ad_network)'),
-            prop('referrer_url', 'string', 'Install referrer URL'),
-        ],
-    },
-    {
-        name: '$first_open',
-        displayName: 'First Open',
-        category: 'acquisition',
-        description: 'First time the app is opened after install.',
-        properties: [],
-    },
-    // ─── Activation ─────────────────────────────────────────────────────────
-    {
-        name: '$login',
-        displayName: 'Login',
-        category: 'activation',
-        description: 'User authenticated into an existing account.',
-        properties: [
-            prop('method', 'string', 'Authentication method (email, google, apple, github)'),
-        ],
-    },
-    {
-        name: '$onboarding_complete',
-        displayName: 'Onboarding Complete',
-        category: 'activation',
-        description: 'User finished the onboarding flow.',
-        properties: [],
-    },
-    // ─── Revenue ────────────────────────────────────────────────────────────
-    {
-        name: '$purchase',
-        displayName: 'Purchase',
-        category: 'revenue',
-        description: 'A completed purchase or transaction.',
-        properties: [
-            prop('value', 'number', 'Monetary value of the transaction', true),
-            prop('currency', 'string', 'ISO 4217 currency code', true),
-            prop('transaction_id', 'string', 'Unique transaction identifier'),
-            prop('items', 'array', 'Array of purchased item objects'),
-            prop('payment_method', 'string', 'Payment method (credit_card, paypal, etc.)'),
-        ],
-    },
-    {
-        name: '$add_to_cart',
-        displayName: 'Add to Cart',
-        category: 'revenue',
-        description: 'Item added to shopping cart.',
-        properties: [
-            prop('value', 'number', 'Monetary value of the item'),
-            prop('currency', 'string', 'ISO 4217 currency code'),
-            prop('item_id', 'string', 'Unique item identifier'),
-            prop('item_name', 'string', 'Human-readable item name'),
-        ],
-    },
-    {
-        name: '$remove_from_cart',
-        displayName: 'Remove from Cart',
-        category: 'revenue',
-        description: 'Item removed from shopping cart.',
-        properties: [
-            prop('value', 'number', 'Monetary value of the item'),
-            prop('item_id', 'string', 'Unique item identifier'),
-        ],
-    },
-    {
-        name: '$begin_checkout',
-        displayName: 'Begin Checkout',
-        category: 'revenue',
-        description: 'User started the checkout flow.',
-        properties: [
-            prop('value', 'number', 'Total cart value'),
-            prop('currency', 'string', 'ISO 4217 currency code'),
-            prop('item_count', 'number', 'Number of items in the cart'),
-        ],
-    },
-    {
-        name: '$subscribe',
-        displayName: 'Subscribe',
-        category: 'revenue',
-        description: 'User started a recurring subscription.',
-        properties: [
-            prop('value', 'number', 'Subscription price', true),
-            prop('currency', 'string', 'ISO 4217 currency code', true),
-            prop('plan_id', 'string', 'Plan or tier identifier'),
-            prop('interval', 'string', 'Billing interval (monthly, yearly)'),
-        ],
-    },
-    {
-        name: '$refund',
-        displayName: 'Refund',
-        category: 'revenue',
-        description: 'A refund was issued.',
-        properties: [
-            prop('value', 'number', 'Refund amount', true),
-            prop('currency', 'string', 'ISO 4217 currency code'),
-            prop('transaction_id', 'string', 'Original transaction identifier'),
-        ],
-    },
-    // ─── Engagement ─────────────────────────────────────────────────────────
-    {
-        name: '$search',
-        displayName: 'Search',
-        category: 'engagement',
-        description: 'User performed a search.',
-        properties: [
-            prop('query', 'string', 'Search query string', true),
-            prop('results_count', 'number', 'Number of results returned'),
-        ],
-    },
-    {
-        name: '$share',
-        displayName: 'Share',
-        category: 'engagement',
-        description: 'User shared content.',
-        properties: [
-            prop('method', 'string', 'Share method (copy_link, twitter, email, etc.)'),
-            prop('content_type', 'string', 'Type of content shared'),
-            prop('item_id', 'string', 'Identifier of the shared item'),
-        ],
-    },
-    {
-        name: '$rate',
-        displayName: 'Rate',
-        category: 'engagement',
-        description: 'User rated an item or experience.',
-        properties: [
-            prop('value', 'number', 'Rating value', true),
-            prop('item_id', 'string', 'Identifier of the rated item'),
-        ],
-    },
-    {
-        name: '$content_view',
-        displayName: 'Content View',
-        category: 'engagement',
-        description: 'User viewed a specific content item.',
-        properties: [
-            prop('content_type', 'string', 'Type of content (article, video, product, etc.)'),
-            prop('content_id', 'string', 'Unique content identifier'),
-            prop('content_name', 'string', 'Human-readable content name'),
-        ],
-    },
-    // ─── Retention ──────────────────────────────────────────────────────────
-    {
-        name: '$app_open',
-        displayName: 'App Open',
-        category: 'retention',
-        description: 'App was opened (not first open).',
-        properties: [],
-    },
-];
-// ── Lookup helpers ──────────────────────────────────────────────────────────
-const _byName = new Map();
-for (const ev of exports.CANONICAL_EVENTS)
-    _byName.set(ev.name, ev);
-/** Retrieve a canonical event definition by its `$`-prefixed name. */
-function getCanonicalEvent(name) {
-    return _byName.get(name);
-}
-/** Set of all canonical event names for quick membership checks. */
-exports.CANONICAL_EVENT_NAMES = new Set(exports.CANONICAL_EVENTS.map((e) => e.name));

package/dist/shared-core/src/envelope.d.ts

@@ -1,91 +0,0 @@
-/**
- * Canonical Event Envelope — Phase 10, W1.1
- *
- * Single source of truth for the event shape flowing through every ingest
- * lane (web SDK, server SDK, future app SDK). Pure module: no DB, no logging,
- * no side effects. Must run in Node (ingest routes) and be safe to bundle
- * into esbuild for the browser SDK.
- *
- * Related docs: PHASE-10-ROADMAP.md §W1.1
- */
-export type EventTier = 'raw' | 'inferred' | 'verified';
-export type EventSource = 'client_sdk' | 'server_sdk' | 'system_inferred' | 'user_confirmed';
-export type ConsentLevel = 'pending' | 'accepted' | 'rejected';
-/**
- * Granular consent level for the pseudonymized identity graph.
- * - none: anonymous aggregate analytics only, no identity processing
- * - analytics: session/pageview/events allowed, anonymous_id claim only
- * - marketing: marketing identifiers allowed (email, phone for campaigns)
- * - full: all processing including profiling, cross-device, recommendations
- */
-export type GranularConsentLevel = 'none' | 'analytics' | 'marketing' | 'full';
-export interface Envelope {
-    event_id: string;
-    timestamp: string;
-    site_id: string;
-    anonymous_id: string;
-    canonical_id?: string;
-    session_id: string;
-    event_type: string;
-    event_name: string;
-    event_tier: EventTier;
-    event_source: EventSource;
-    correlation_id?: string;
-    parent_event_id?: string;
-    consent_level: ConsentLevel;
-    granular_consent_level?: GranularConsentLevel;
-    sdk_version: string;
-    config_version?: string;
-    page_url: string;
-    page_title?: string;
-    referrer?: string;
-    utm_source?: string;
-    utm_medium?: string;
-    utm_campaign?: string;
-    utm_term?: string;
-    utm_content?: string;
-    device_type?: string;
-    browser?: string;
-    os?: string;
-    screen_width?: number;
-    screen_height?: number;
-    device_id?: string;
-    phone?: string;
-    event_source_platform?: 'web' | 'ios' | 'android' | 'react_native' | 'flutter' | 'server';
-    properties: Record<string, unknown>;
-}
-export type ParseSuccess = {
-    ok: true;
-    value: Envelope;
-};
-export type ParseError = {
-    ok: false;
-    errors: string[];
-};
-export type ParseResult = ParseSuccess | ParseError;
-/**
- * Strict parser. Accepts only already-canonical envelopes. Used on internal
- * pipeline boundaries where we know producers emit the full shape.
- *
- * Throws-in-return-value: never throws, returns ParseError on failure.
- */
-export declare function parseEnvelope(raw: unknown): ParseResult;
-/**
- * Accepts the loose JSON shape that the current `sdk/tracker.ts` sends and
- * promotes it to a canonical Envelope, filling defaults for fields the legacy
- * shape doesn't know about. Use this on ingest boundaries during the
- * migration window (Phase 10 Wave 1 → Wave 3).
- */
-export declare function normalizeLegacy(raw: unknown): ParseResult;
-export interface CreateEnvelopeInput extends Partial<Envelope> {
-    site_id: string;
-    event_name: string;
-    anonymous_id: string;
-    session_id: string;
-}
-/**
- * Server-side helper for constructing envelopes from partial input. Fills
- * event_id, timestamp, and all enum defaults. Not used on the client SDK hot
- * path.
- */
-export declare function createEnvelope(partial: CreateEnvelopeInput): Envelope;

package/dist/shared-core/src/envelope.js

@@ -1,341 +0,0 @@
-"use strict";
-/**
- * Canonical Event Envelope — Phase 10, W1.1
- *
- * Single source of truth for the event shape flowing through every ingest
- * lane (web SDK, server SDK, future app SDK). Pure module: no DB, no logging,
- * no side effects. Must run in Node (ingest routes) and be safe to bundle
- * into esbuild for the browser SDK.
- *
- * Related docs: PHASE-10-ROADMAP.md §W1.1
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseEnvelope = parseEnvelope;
-exports.normalizeLegacy = normalizeLegacy;
-exports.createEnvelope = createEnvelope;
-const EVENT_TIERS = ['raw', 'inferred', 'verified'];
-const EVENT_SOURCES = [
-    'client_sdk',
-    'server_sdk',
-    'system_inferred',
-    'user_confirmed',
-];
-const CONSENT_LEVELS = [
-    'pending',
-    'accepted',
-    'rejected',
-];
-const GRANULAR_CONSENT_LEVELS = [
-    'none',
-    'analytics',
-    'marketing',
-    'full',
-];
-// ── UUID helper (dependency-free, safe in browser and Node) ─────────────────
-function generateUuid() {
-    // Prefer crypto.randomUUID when available (Node 14.17+, modern browsers).
-    const g = globalThis.crypto;
-    if (g && typeof g.randomUUID === 'function') {
-        try {
-            return g.randomUUID();
-        }
-        catch {
-            // fall through
-        }
-    }
-    // RFC4122 v4 fallback using Math.random (non-cryptographic but deterministic-free).
-    const hex = '0123456789abcdef';
-    let out = '';
-    for (let i = 0; i < 36; i++) {
-        if (i === 8 || i === 13 || i === 18 || i === 23) {
-            out += '-';
-        }
-        else if (i === 14) {
-            out += '4';
-        }
-        else if (i === 19) {
-            out += hex[(Math.random() * 4) | 0 | 8];
-        }
-        else {
-            out += hex[(Math.random() * 16) | 0];
-        }
-    }
-    return out;
-}
-// ── Field helpers ────────────────────────────────────────────────────────────
-function isObject(v) {
-    return typeof v === 'object' && v !== null && !Array.isArray(v);
-}
-function asString(v) {
-    if (typeof v === 'string')
-        return v;
-    return undefined;
-}
-function asNumber(v) {
-    if (typeof v === 'number' && Number.isFinite(v))
-        return v;
-    return undefined;
-}
-function asProperties(v) {
-    return isObject(v) ? v : {};
-}
-function requireString(obj, key, errors) {
-    const v = obj[key];
-    if (typeof v !== 'string' || v.length === 0) {
-        errors.push(`missing or invalid '${key}' (expected non-empty string)`);
-        return '';
-    }
-    return v;
-}
-function validTimestamp(v, errors) {
-    if (typeof v === 'string') {
-        if (!Number.isNaN(Date.parse(v)))
-            return v;
-        errors.push(`invalid 'timestamp' (unparseable string)`);
-        return '';
-    }
-    if (typeof v === 'number' && Number.isFinite(v)) {
-        return new Date(v).toISOString();
-    }
-    errors.push(`missing or invalid 'timestamp' (expected ISO-8601 string or epoch ms)`);
-    return '';
-}
-function requireEnum(value, allowed, key, errors) {
-    if (typeof value === 'string' && allowed.includes(value)) {
-        return value;
-    }
-    errors.push(`invalid '${key}': expected one of [${allowed.join(', ')}], got ${JSON.stringify(value)}`);
-    return allowed[0];
-}
-// ── parseEnvelope — strict ──────────────────────────────────────────────────
-/**
- * Strict parser. Accepts only already-canonical envelopes. Used on internal
- * pipeline boundaries where we know producers emit the full shape.
- *
- * Throws-in-return-value: never throws, returns ParseError on failure.
- */
-function parseEnvelope(raw) {
-    const errors = [];
-    if (!isObject(raw)) {
-        return { ok: false, errors: ['envelope must be an object'] };
-    }
-    const event_id = requireString(raw, 'event_id', errors);
-    const timestamp = validTimestamp(raw.timestamp, errors);
-    const site_id = requireString(raw, 'site_id', errors);
-    const anonymous_id = requireString(raw, 'anonymous_id', errors);
-    const session_id = requireString(raw, 'session_id', errors);
-    const event_type = requireString(raw, 'event_type', errors);
-    const event_name = requireString(raw, 'event_name', errors);
-    const page_url = requireString(raw, 'page_url', errors);
-    const sdk_version = requireString(raw, 'sdk_version', errors);
-    const event_tier = requireEnum(raw.event_tier, EVENT_TIERS, 'event_tier', errors);
-    const event_source = requireEnum(raw.event_source, EVENT_SOURCES, 'event_source', errors);
-    const consent_level = requireEnum(raw.consent_level, CONSENT_LEVELS, 'consent_level', errors);
-    // Granular consent is optional — parse if present, skip if absent.
-    const rawGranular = asString(raw.granular_consent_level);
-    const granular_consent_level = rawGranular && GRANULAR_CONSENT_LEVELS.includes(rawGranular)
-        ? rawGranular
-        : undefined;
-    if (errors.length > 0) {
-        return { ok: false, errors };
-    }
-    const value = {
-        event_id,
-        timestamp,
-        site_id,
-        anonymous_id,
-        canonical_id: asString(raw.canonical_id),
-        session_id,
-        event_type,
-        event_name,
-        event_tier,
-        event_source,
-        correlation_id: asString(raw.correlation_id),
-        parent_event_id: asString(raw.parent_event_id),
-        consent_level,
-        granular_consent_level,
-        sdk_version,
-        config_version: asString(raw.config_version),
-        page_url,
-        page_title: asString(raw.page_title),
-        referrer: asString(raw.referrer),
-        utm_source: asString(raw.utm_source),
-        utm_medium: asString(raw.utm_medium),
-        utm_campaign: asString(raw.utm_campaign),
-        utm_term: asString(raw.utm_term),
-        utm_content: asString(raw.utm_content),
-        device_type: asString(raw.device_type),
-        browser: asString(raw.browser),
-        os: asString(raw.os),
-        screen_width: asNumber(raw.screen_width),
-        screen_height: asNumber(raw.screen_height),
-        device_id: asString(raw.device_id),
-        phone: asString(raw.phone),
-        event_source_platform: asString(raw.event_source_platform),
-        properties: asProperties(raw.properties),
-    };
-    return { ok: true, value };
-}
-// ── normalizeLegacy — accept current SDK shape ──────────────────────────────
-/**
- * Maps the legacy SDK consent values ('necessary' | 'analytics' | 'marketing'
- * | 'rejected') onto the canonical envelope consent vocabulary. Anything
- * non-rejected is treated as 'accepted'; missing values become 'pending'.
- */
-function mapLegacyConsent(v) {
-    if (typeof v !== 'string')
-        return 'pending';
-    if (v === 'rejected')
-        return 'rejected';
-    if (v === 'pending')
-        return 'pending';
-    if (v === 'accepted')
-        return 'accepted';
-    // 'necessary' | 'analytics' | 'marketing' all indicate affirmative consent.
-    if (v === 'necessary' || v === 'analytics' || v === 'marketing') {
-        return 'accepted';
-    }
-    return 'pending';
-}
-/**
- * Maps legacy SDK consent values to the 4-level granular consent system.
- * - 'rejected' / 'none' → 'none'
- * - 'necessary' / 'pending' → 'none' (privacy by default)
- * - 'analytics' → 'analytics'
- * - 'marketing' → 'marketing'
- * - 'accepted' / 'full' → 'full'
- * Also accepts an explicit granular_consent_level field if the SDK sends it.
- */
-function mapLegacyToGranularConsent(raw) {
-    // If the SDK already sends granular_consent_level, prefer it
-    const explicit = asString(raw.granular_consent_level);
-    if (explicit && GRANULAR_CONSENT_LEVELS.includes(explicit)) {
-        return explicit;
-    }
-    // Fall back to mapping the legacy consent_level
-    const v = asString(raw.consent_level);
-    if (!v)
-        return 'none';
-    switch (v) {
-        case 'rejected':
-        case 'none':
-        case 'necessary':
-        case 'pending':
-            return 'none';
-        case 'analytics':
-            return 'analytics';
-        case 'marketing':
-            return 'marketing';
-        case 'accepted':
-        case 'full':
-            return 'full';
-        default:
-            return 'none';
-    }
-}
-/**
- * Accepts the loose JSON shape that the current `sdk/tracker.ts` sends and
- * promotes it to a canonical Envelope, filling defaults for fields the legacy
- * shape doesn't know about. Use this on ingest boundaries during the
- * migration window (Phase 10 Wave 1 → Wave 3).
- */
-function normalizeLegacy(raw) {
-    const errors = [];
-    if (!isObject(raw)) {
-        return { ok: false, errors: ['legacy event must be an object'] };
-    }
-    // Required in the legacy shape
-    const anonymous_id = requireString(raw, 'anonymous_id', errors);
-    const session_id = requireString(raw, 'session_id', errors);
-    const event_type = requireString(raw, 'event_type', errors);
-    const event_name = requireString(raw, 'event_name', errors);
-    if (errors.length > 0) {
-        return { ok: false, errors };
-    }
-    const site_id = asString(raw.site_id) ?? ''; // collect route supplies site_id at the batch level
-    const event_id = asString(raw.event_id) ?? generateUuid();
-    const ts = raw.timestamp;
-    const timestamp = typeof ts === 'string' && !Number.isNaN(Date.parse(ts))
-        ? ts
-        : typeof ts === 'number' && Number.isFinite(ts)
-            ? new Date(ts).toISOString()
-            : new Date().toISOString();
-    const value = {
-        event_id,
-        timestamp,
-        site_id,
-        anonymous_id,
-        canonical_id: asString(raw.canonical_id),
-        session_id,
-        event_type,
-        event_name,
-        event_tier: 'raw',
-        event_source: 'client_sdk',
-        correlation_id: asString(raw.correlation_id),
-        parent_event_id: asString(raw.parent_event_id),
-        consent_level: mapLegacyConsent(raw.consent_level),
-        granular_consent_level: mapLegacyToGranularConsent(raw),
-        sdk_version: asString(raw.sdk_version) ?? 'web@legacy',
-        config_version: asString(raw.config_version),
-        page_url: asString(raw.page_url) ?? '',
-        page_title: asString(raw.page_title),
-        referrer: asString(raw.referrer),
-        utm_source: asString(raw.utm_source),
-        utm_medium: asString(raw.utm_medium),
-        utm_campaign: asString(raw.utm_campaign),
-        utm_term: asString(raw.utm_term),
-        utm_content: asString(raw.utm_content),
-        device_type: asString(raw.device_type),
-        browser: asString(raw.browser),
-        os: asString(raw.os),
-        screen_width: asNumber(raw.screen_width),
-        screen_height: asNumber(raw.screen_height),
-        device_id: asString(raw.device_id),
-        phone: asString(raw.phone),
-        event_source_platform: asString(raw.event_source_platform),
-        properties: asProperties(raw.properties),
-    };
-    return { ok: true, value };
-}
-/**
- * Server-side helper for constructing envelopes from partial input. Fills
- * event_id, timestamp, and all enum defaults. Not used on the client SDK hot
- * path.
- */
-function createEnvelope(partial) {
-    return {
-        event_id: partial.event_id ?? generateUuid(),
-        timestamp: partial.timestamp ?? new Date().toISOString(),
-        site_id: partial.site_id,
-        anonymous_id: partial.anonymous_id,
-        canonical_id: partial.canonical_id,
-        session_id: partial.session_id,
-        event_type: partial.event_type ?? 'custom',
-        event_name: partial.event_name,
-        event_tier: partial.event_tier ?? 'raw',
-        event_source: partial.event_source ?? 'client_sdk',
-        correlation_id: partial.correlation_id,
-        parent_event_id: partial.parent_event_id,
-        consent_level: partial.consent_level ?? 'pending',
-        granular_consent_level: partial.granular_consent_level ?? 'none',
-        sdk_version: partial.sdk_version ?? 'server@unknown',
-        config_version: partial.config_version,
-        page_url: partial.page_url ?? '',
-        page_title: partial.page_title,
-        referrer: partial.referrer,
-        utm_source: partial.utm_source,
-        utm_medium: partial.utm_medium,
-        utm_campaign: partial.utm_campaign,
-        utm_term: partial.utm_term,
-        utm_content: partial.utm_content,
-        device_type: partial.device_type,
-        browser: partial.browser,
-        os: partial.os,
-        screen_width: partial.screen_width,
-        screen_height: partial.screen_height,
-        device_id: partial.device_id,
-        phone: partial.phone,
-        event_source_platform: partial.event_source_platform,
-        properties: partial.properties ?? {},
-    };
-}

package/dist/shared-core/src/index.d.ts

@@ -1,6 +0,0 @@
-/**
- * @gurulu/shared-core — canonical contracts shared by every Gurulu SDK.
- */
-export * from './envelope';
-export * from './server-event';
-export * from './canonical-events';

package/dist/shared-core/src/index.js

@@ -1,22 +0,0 @@
-"use strict";
-/**
- * @gurulu/shared-core — canonical contracts shared by every Gurulu SDK.
- */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./envelope"), exports);
-__exportStar(require("./server-event"), exports);
-__exportStar(require("./canonical-events"), exports);

package/dist/shared-core/src/server-event.d.ts

@@ -1,37 +0,0 @@
-/**
- * Server SDK public types — lifted from packages/node-sdk so every lane
- * imports them from a single source of truth.
- */
-export interface GuruluConfig {
-    siteId: string;
-    apiKey: string;
-    endpoint?: string;
-    flushInterval?: number;
-    maxBatchSize?: number;
-    maxRetries?: number;
-    debug?: boolean;
-}
-export interface ServerEvent {
-    event_name: string;
-    user_id: string;
-    properties?: Record<string, unknown>;
-    timestamp?: string;
-    idempotency_key?: string;
-    correlation_id?: string;
-}
-export interface TrackOptions {
-    userId: string;
-    timestamp?: Date;
-    idempotencyKey?: string;
-    correlationId?: string;
-}
-export interface IngestResponse {
-    accepted: number;
-    rejected: number;
-    correlations: Array<{
-        server_event: string;
-        matched_client_event: string;
-        inferred_intent: string;
-        confidence: number;
-    }>;
-}

package/dist/shared-core/src/server-event.js

@@ -1,6 +0,0 @@
-"use strict";
-/**
- * Server SDK public types — lifted from packages/node-sdk so every lane
- * imports them from a single source of truth.
- */
-Object.defineProperty(exports, "__esModule", { value: true });