@gurulu/node 0.1.1 → 1.0.0

package/dist/client.js

@@ -1,307 +0,0 @@
-"use strict";
-/**
- * @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
- */
-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;
-const DEFAULT_BATCH_SIZE = 50;
-const DEFAULT_TIMEOUT = 10000;
-const RETRY_DELAYS_MS = [200, 600, 1800];
-/**
- * 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.
- */
-function createIdempotencyKey(event, siteId) {
-    const parts = [
-        siteId,
-        event.event_name ?? '',
-        event.timestamp ?? '',
-        event.user_id ?? '',
-    ];
-    return (0, crypto_1.createHash)('sha256').update(parts.join('|')).digest('hex');
-}
-class Gurulu {
-    siteId;
-    apiKey;
-    endpoint;
-    flushInterval;
-    batchSize;
-    timeout;
-    onError;
-    onDeadLetter;
-    fetchImpl;
-    debug;
-    queue = [];
-    flushTimer = null;
-    inFlight = null;
-    shutdownHandlers = [];
-    constructor(config) {
-        if (!config.siteId)
-            throw new Error('siteId is required');
-        if (!config.apiKey)
-            throw new Error('apiKey is required');
-        this.siteId = config.siteId;
-        this.apiKey = config.apiKey;
-        this.endpoint = config.endpoint || DEFAULT_ENDPOINT;
-        this.flushInterval = config.flushInterval ?? DEFAULT_FLUSH_INTERVAL;
-        this.batchSize = config.batchSize ?? DEFAULT_BATCH_SIZE;
-        this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
-        this.onError = config.onError;
-        this.onDeadLetter = config.onDeadLetter;
-        this.debug = config.debug ?? false;
-        const injected = config.fetchImpl;
-        if (injected) {
-            this.fetchImpl = injected;
-        }
-        else {
-            const g = globalThis;
-            if (typeof g.fetch !== 'function') {
-                throw new Error('global fetch is not available; pass fetchImpl in config (Node 18+ required)');
-            }
-            this.fetchImpl = g.fetch.bind(globalThis);
-        }
-        if (this.flushInterval > 0) {
-            this.flushTimer = setInterval(() => {
-                // Fire and forget; errors surface via onError.
-                void this.flush();
-            }, this.flushInterval);
-            // Let the process exit even if the timer is pending.
-            const t = this.flushTimer;
-            if (typeof t.unref === 'function')
-                t.unref();
-        }
-        if (!config.disableAutoShutdown && typeof process !== 'undefined' && typeof process.on === 'function') {
-            const beforeExit = () => {
-                void this.flush();
-            };
-            const onSigterm = () => {
-                void this.shutdown();
-            };
-            process.on('beforeExit', beforeExit);
-            process.on('SIGTERM', onSigterm);
-            this.shutdownHandlers.push(() => {
-                process.off('beforeExit', beforeExit);
-                process.off('SIGTERM', onSigterm);
-            });
-        }
-    }
-    get queueSize() {
-        return this.queue.length;
-    }
-    /**
-     * 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) {
-        if (!event || !event.event_name) {
-            if (this.debug)
-                console.warn('[gurulu] event_name is required');
-            return;
-        }
-        if (!event.user_id) {
-            if (this.debug)
-                console.warn('[gurulu] user_id is required for server events');
-            return;
-        }
-        const stamped = {
-            ...event,
-            timestamp: event.timestamp ?? new Date().toISOString(),
-        };
-        this.queue.push(stamped);
-        if (this.debug) {
-            console.log(`[gurulu] queued: ${stamped.event_name} (${this.queue.length}/${this.batchSize})`);
-        }
-        if (this.queue.length >= this.batchSize) {
-            void this.flush();
-        }
-    }
-    /**
-     * 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.
-     */
-    async flush() {
-        // Serialize concurrent flushes so retries don't interleave.
-        if (this.inFlight) {
-            await this.inFlight;
-        }
-        if (this.queue.length === 0)
-            return;
-        const batch = this.queue.splice(0, this.queue.length);
-        const run = this.sendBatch(batch);
-        this.inFlight = run.finally(() => {
-            this.inFlight = null;
-        });
-        await this.inFlight;
-    }
-    async sendBatch(batch) {
-        // Idempotency key for the whole batch — hashed over individual event keys.
-        const perEventKeys = batch.map((e) => createIdempotencyKey(e, this.siteId));
-        const batchKey = (0, crypto_1.createHash)('sha256').update(perEventKeys.join('|')).digest('hex');
-        const body = JSON.stringify({
-            site_id: this.siteId,
-            events: batch,
-        });
-        const headers = {
-            'Content-Type': 'application/json',
-            Authorization: `Bearer ${this.apiKey}`,
-            'Idempotency-Key': batchKey,
-        };
-        let lastError = null;
-        for (let attempt = 0; attempt < RETRY_DELAYS_MS.length; attempt++) {
-            try {
-                const res = await this.fetchImpl(this.endpoint, {
-                    method: 'POST',
-                    headers,
-                    body,
-                });
-                if (res.ok) {
-                    if (this.debug)
-                        console.log(`[gurulu] flushed ${batch.length} events`);
-                    return;
-                }
-                if (res.status >= 400 && res.status < 500) {
-                    // Client error — don't retry. Drop + dead-letter.
-                    const text = await safeText(res);
-                    const err = new Error(`client_error ${res.status}: ${text}`);
-                    if (this.debug)
-                        console.error(`[gurulu] ${err.message}`);
-                    this.onError?.(err);
-                    this.onDeadLetter?.(batch, {
-                        kind: 'client_error',
-                        status: res.status,
-                        message: text,
-                    });
-                    return;
-                }
-                lastError = new Error(`server_error ${res.status}`);
-                this.onError?.(lastError);
-            }
-            catch (err) {
-                lastError = err instanceof Error ? err : new Error(String(err));
-                this.onError?.(lastError);
-            }
-            // Not the last attempt — sleep with the fixed exponential schedule.
-            if (attempt < RETRY_DELAYS_MS.length - 1) {
-                await sleep(RETRY_DELAYS_MS[attempt + 1 - 1]);
-                // ^ Index arithmetic: attempt=0 -> use RETRY_DELAYS_MS[0]=200, etc.
-            }
-        }
-        // All 3 attempts failed.
-        if (this.debug) {
-            console.error(`[gurulu] dropping batch of ${batch.length} after retries: ${lastError?.message}`);
-        }
-        if (this.onDeadLetter) {
-            this.onDeadLetter(batch, {
-                kind: lastError?.message.startsWith('server_error') ? 'server_error' : 'network_error',
-                message: lastError?.message ?? 'unknown error',
-            });
-        }
-        else if (this.debug) {
-            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.
-     */
-    async shutdown() {
-        if (this.flushTimer) {
-            clearInterval(this.flushTimer);
-            this.flushTimer = null;
-        }
-        for (const detach of this.shutdownHandlers.splice(0)) {
-            try {
-                detach();
-            }
-            catch { /* best-effort */ }
-        }
-        await this.flush();
-    }
-}
-exports.Gurulu = Gurulu;
-async function safeText(res) {
-    try {
-        return await res.text();
-    }
-    catch {
-        return '';
-    }
-}
-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/types.js

@@ -1,30 +0,0 @@
-"use strict";
-/**
- * Node SDK public types.
- *
- * Canonical event shapes (Envelope, ServerEvent, EventTier, EventSource,
- * ConsentLevel, createEnvelope, normalizeLegacy, parseEnvelope) are re-exported
- * from @gurulu/shared-core — single source of truth per W1.2.
- *
- * The only node-sdk-specific addition is the transport config
- * (GuruluClientConfig) which wraps the shared ServerEvent with the knobs
- * needed to actually ship events to the ingest endpoint.
- *
- * Related docs: PHASE-10-ROADMAP.md §W1.2, §W4.2
- */
-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("@gurulu/shared-core"), exports);