@gurulu/node 0.1.0 → 0.1.2

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 });