@gurulu/node 0.1.0 → 0.1.2

package/dist/node-sdk/src/client.d.ts

@@ -1,70 +0,0 @@
-/**
- * @gurulu/node — server-side SDK client.
- *
- * Responsibilities (Phase 10 W4.2):
- *   - Queue + batch server events.
- *   - Auto-flush at batchSize boundary and on a periodic timer.
- *   - Exponential-backoff retry (200ms, 600ms, 1800ms — 3 attempts total) on
- *     5xx / network errors. No retry on 4xx.
- *   - Attach deterministic Idempotency-Key headers so the server can dedupe
- *     replayed batches across retries.
- *   - Dead-letter callback for batches that exhaust retries or are rejected
- *     with a client error.
- *   - Flush on process.beforeExit + SIGTERM.
- *
- * Event shapes are pulled from @gurulu/shared-core (W1.2). Only the transport
- * config (`GuruluClientConfig`) is local.
- *
- * Related docs: PHASE-10-ROADMAP.md §W4.2
- */
-import type { ServerEvent } from '@gurulu/shared-core';
-import type { GuruluClientConfig } from './types';
-export interface GuruluClient {
-    track(event: ServerEvent): void;
-    flush(): Promise<void>;
-    shutdown(): Promise<void>;
-    /** Current queue length — exposed for tests and observability. */
-    readonly queueSize: number;
-}
-/**
- * Deterministic idempotency key for a server event. Hashes the tuple
- * (site_id, event_name, timestamp, anonymous_id/user_id) so replayed events
- * across retries produce the same key and the server can dedupe.
- */
-export declare function createIdempotencyKey(event: ServerEvent, siteId: string): string;
-export declare class Gurulu implements GuruluClient {
-    private readonly siteId;
-    private readonly apiKey;
-    private readonly endpoint;
-    private readonly flushInterval;
-    private readonly batchSize;
-    private readonly timeout;
-    private readonly onError?;
-    private readonly onDeadLetter?;
-    private readonly fetchImpl;
-    private readonly debug;
-    private queue;
-    private flushTimer;
-    private inFlight;
-    private shutdownHandlers;
-    constructor(config: GuruluClientConfig);
-    get queueSize(): number;
-    /**
-     * Enqueue a server event. Auto-flushes synchronously when the queue reaches
-     * `batchSize`. Each event is stamped with a timestamp if missing so the
-     * idempotency key is stable across retries.
-     */
-    track(event: ServerEvent): void;
-    /**
-     * POST all queued events in one batch. On 5xx / network error retries with
-     * exponential backoff (200ms, 600ms, 1800ms). On 4xx drops the batch and
-     * fires the dead-letter callback. Concurrent flush calls are serialized.
-     */
-    flush(): Promise<void>;
-    private sendBatch;
-    /**
-     * Stop the periodic flush timer, detach process listeners, and perform a
-     * final flush. Safe to call multiple times.
-     */
-    shutdown(): Promise<void>;
-}

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;