@gurulu/node 0.1.2 → 1.0.0

package/dist/client.js

@@ -1,442 +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;
-exports.addBreadcrumb = addBreadcrumb;
-const crypto_1 = require("crypto");
-const DEFAULT_ENDPOINT = 'https://app.gurulu.io/api/ingest/v1/server';
-const SDK_VERSION = 'node@0.1.0';
-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;
-    release;
-    queue = [];
-    breadcrumbs = [];
-    maxBreadcrumbs = 50;
-    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;
-        this.release = config.release || process.env.GURULU_RELEASE || '';
-        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;
-    }
-    static REVENUE_EVENTS = new Set([
-        'purchase', '$purchase', 'order_placed', '$order_placed',
-        'subscription_started', '$subscription_started', 'subscription_created', '$subscription_created',
-        'refund', '$refund', 'order_refunded', '$order_refunded',
-        'payment_succeeded', '$payment_succeeded', 'checkout_completed', '$checkout_completed',
-        'deposit_completed', '$deposit_completed', 'bet_placed', '$bet_placed',
-        'subscribe', '$subscribe',
-    ]);
-    /**
-     * 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;
-        }
-        // Warn when a known revenue event is missing value/amount or currency
-        const eName = event.event_name;
-        if (Gurulu.REVENUE_EVENTS.has(eName) ||
-            Gurulu.REVENUE_EVENTS.has(eName.replace(/^\$/, ''))) {
-            const props = event.properties;
-            const hasValue = props?.value !== undefined || props?.amount !== undefined;
-            if (!hasValue) {
-                console.warn(`[gurulu] Revenue event "${eName}" is missing "value"/"amount" property. Revenue tracking will be incomplete.`);
-            }
-            if (!props?.currency) {
-                console.warn(`[gurulu] Revenue event "${eName}" is missing "currency" property (expected ISO 4217 code like "USD", "EUR").`);
-            }
-        }
-        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();
-        }
-    }
-    /**
-     * Identify a user — links an anonymous session to a known user ID and
-     * persists traits on the identity profile. Sends immediately to the
-     * dedicated `/api/ingest/v1/identify` endpoint (not batched with track
-     * events) because identity resolution is latency-sensitive and returns
-     * the canonical_id synchronously.
-     *
-     * Retries with the same exponential-backoff strategy as batch flushes.
-     */
-    async identify(params) {
-        if (!params.userId)
-            throw new Error('userId is required for identify()');
-        if (!params.anonymousId)
-            throw new Error('anonymousId is required for identify()');
-        const identifyEndpoint = this.endpoint.replace(/\/server\/?$/, '/identify');
-        const body = JSON.stringify({
-            site_id: this.siteId,
-            anonymous_id: params.anonymousId,
-            user_id: params.userId,
-            traits: params.traits,
-            ...(params.deviceId ? { device_id: params.deviceId } : {}),
-            ...(params.oauthProvider ? { oauth_provider: params.oauthProvider } : {}),
-            ...(params.oauthId ? { oauth_id: params.oauthId } : {}),
-            ...(params.consentLevel ? { consent_level: params.consentLevel } : {}),
-        });
-        const headers = {
-            'Content-Type': 'application/json',
-            Authorization: `Bearer ${this.apiKey}`,
-        };
-        let lastError = null;
-        for (let attempt = 0; attempt < RETRY_DELAYS_MS.length; attempt++) {
-            try {
-                const res = await this.fetchImpl(identifyEndpoint, {
-                    method: 'POST',
-                    headers,
-                    body,
-                });
-                if (res.ok) {
-                    const data = (await res.json());
-                    if (this.debug)
-                        console.log(`[gurulu] identify success: canonical_id=${data.canonical_id}`);
-                    return data;
-                }
-                if (res.status >= 400 && res.status < 500) {
-                    const text = await safeText(res);
-                    const err = new Error(`identify client_error ${res.status}: ${text}`);
-                    this.onError?.(err);
-                    throw err;
-                }
-                lastError = new Error(`identify server_error ${res.status}`);
-                this.onError?.(lastError);
-            }
-            catch (err) {
-                if (err instanceof Error && err.message.startsWith('identify client_error')) {
-                    throw err;
-                }
-                lastError = err instanceof Error ? err : new Error(String(err));
-                this.onError?.(lastError);
-            }
-            if (attempt < RETRY_DELAYS_MS.length - 1) {
-                await sleep(RETRY_DELAYS_MS[attempt]);
-            }
-        }
-        throw lastError ?? new Error('identify failed after retries');
-    }
-    /**
-     * 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++) {
-            const controller = new AbortController();
-            const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-            try {
-                const res = await this.fetchImpl(this.endpoint, {
-                    method: 'POST',
-                    headers,
-                    body,
-                    signal: controller.signal,
-                });
-                clearTimeout(timeoutId);
-                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) {
-                clearTimeout(timeoutId);
-                // Treat AbortError (timeout) as retryable network error
-                if (err instanceof Error && err.name === 'AbortError') {
-                    lastError = new Error(`timeout after ${this.timeout}ms`);
-                    this.onError?.(lastError);
-                }
-                else {
-                    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');
-        }
-    }
-    /**
-     * Add a custom breadcrumb to the trail. Breadcrumbs are sent with error
-     * events to provide context about what happened before the error occurred.
-     */
-    addBreadcrumb(category, message, data) {
-        this.breadcrumbs.push({
-            timestamp: new Date().toISOString(),
-            category,
-            message,
-            data,
-        });
-        if (this.breadcrumbs.length > this.maxBreadcrumbs) {
-            this.breadcrumbs = this.breadcrumbs.slice(-this.maxBreadcrumbs);
-        }
-    }
-    /**
-     * Capture an exception and send it as an error event.
-     * Includes any accumulated breadcrumbs for debugging context.
-     */
-    captureException(error, context) {
-        const breadcrumbSnapshot = [...this.breadcrumbs];
-        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',
-                breadcrumbs: breadcrumbSnapshot,
-                release: this.release,
-                sdk_version: SDK_VERSION,
-                event_source: 'server_sdk',
-                ...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);
-}
-/**
- * Convenience function — adds a breadcrumb via the default instance.
- * Call `setDefaultInstance()` first (or create a Gurulu client).
- */
-function addBreadcrumb(category, message, data) {
-    if (!defaultInstance) {
-        throw new Error('No default Gurulu instance. Call setDefaultInstance() first.');
-    }
-    defaultInstance.addBreadcrumb(category, message, data);
-}

package/dist/middleware.d.ts

@@ -1,31 +0,0 @@
-/**
- * @gurulu/node — framework error-handler middleware.
- *
- * Provides drop-in error handlers for Express, Fastify, and Hono.
- * Each handler captures the exception via `client.captureException` and
- * then delegates to the framework's default error-handling flow.
- */
-import type { GuruluClient } from './client';
-/**
- * Express error-handling middleware.
- * Place AFTER all routes: app.use(guruluErrorHandler(gurulu))
- */
-export declare function expressErrorHandler(client: GuruluClient): (err: Error, req: any, res: any, next: any) => void;
-/**
- * Express request handler wrapper.
- * Wraps async handlers to catch thrown errors:
- *   app.get('/x', guruluHandler(gurulu, handler))
- */
-export declare function expressHandler(client: GuruluClient, handler: Function): (req: any, res: any, next: any) => Promise<void>;
-/**
- * Fastify error handler plugin.
- * Register: fastify.register(guruluFastifyPlugin, { client: gurulu })
- */
-export declare function guruluFastifyPlugin(fastify: any, opts: {
-    client: GuruluClient;
-}, done: Function): void;
-/**
- * Hono error handler middleware.
- * Usage: app.onError(guruluHonoErrorHandler(gurulu))
- */
-export declare function honoErrorHandler(client: GuruluClient): (err: Error, c: any) => any;

package/dist/middleware.js

@@ -1,138 +0,0 @@
-"use strict";
-/**
- * @gurulu/node — framework error-handler middleware.
- *
- * Provides drop-in error handlers for Express, Fastify, and Hono.
- * Each handler captures the exception via `client.captureException` and
- * then delegates to the framework's default error-handling flow.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.expressErrorHandler = expressErrorHandler;
-exports.expressHandler = expressHandler;
-exports.guruluFastifyPlugin = guruluFastifyPlugin;
-exports.honoErrorHandler = honoErrorHandler;
-// ---------------------------------------------------------------------------
-// Express
-// ---------------------------------------------------------------------------
-/**
- * Express error-handling middleware.
- * Place AFTER all routes: app.use(guruluErrorHandler(gurulu))
- */
-function expressErrorHandler(client) {
-    return function guruluExpressErrorHandler(err, req, res, next) {
-        client.captureException(err, {
-            mechanism: 'express_middleware',
-            request: {
-                method: req.method,
-                url: req.originalUrl || req.url,
-                headers: sanitizeHeaders(req.headers),
-                query: req.query,
-                body: truncate(req.body),
-                ip: req.ip || req.connection?.remoteAddress,
-            },
-            user: req.user ? { id: req.user.id, email: req.user.email } : undefined,
-        });
-        next(err);
-    };
-}
-/**
- * Express request handler wrapper.
- * Wraps async handlers to catch thrown errors:
- *   app.get('/x', guruluHandler(gurulu, handler))
- */
-function expressHandler(client, handler) {
-    return async function guruluWrappedHandler(req, res, next) {
-        try {
-            await handler(req, res, next);
-        }
-        catch (err) {
-            client.captureException(err, {
-                mechanism: 'express_handler_wrapper',
-                request: {
-                    method: req.method,
-                    url: req.originalUrl || req.url,
-                    headers: sanitizeHeaders(req.headers),
-                },
-            });
-            next(err);
-        }
-    };
-}
-// ---------------------------------------------------------------------------
-// Fastify
-// ---------------------------------------------------------------------------
-/**
- * Fastify error handler plugin.
- * Register: fastify.register(guruluFastifyPlugin, { client: gurulu })
- */
-function guruluFastifyPlugin(fastify, opts, done) {
-    fastify.setErrorHandler(function guruluFastifyErrorHandler(error, request, reply) {
-        opts.client.captureException(error, {
-            mechanism: 'fastify_error_handler',
-            request: {
-                method: request.method,
-                url: request.url,
-                headers: sanitizeHeaders(request.headers),
-                query: request.query,
-                body: truncate(request.body),
-                ip: request.ip,
-            },
-            user: request.user
-                ? { id: request.user.id, email: request.user.email }
-                : undefined,
-        });
-        // Let Fastify's default handler send the response
-        reply.status(500).send({ error: 'Internal Server Error' });
-    });
-    done();
-}
-// ---------------------------------------------------------------------------
-// Hono
-// ---------------------------------------------------------------------------
-/**
- * Hono error handler middleware.
- * Usage: app.onError(guruluHonoErrorHandler(gurulu))
- */
-function honoErrorHandler(client) {
-    return function guruluHonoErrorHandler(err, c) {
-        client.captureException(err, {
-            mechanism: 'hono_error_handler',
-            request: {
-                method: c.req.method,
-                url: c.req.url,
-                headers: sanitizeHeaders(Object.fromEntries(c.req.raw.headers || [])),
-            },
-        });
-        return c.json({ error: 'Internal Server Error' }, 500);
-    };
-}
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-const SENSITIVE_HEADERS = new Set([
-    'authorization',
-    'cookie',
-    'set-cookie',
-    'x-api-key',
-    'x-auth-token',
-]);
-function sanitizeHeaders(headers) {
-    if (!headers || typeof headers !== 'object')
-        return {};
-    const sanitized = {};
-    for (const [key, value] of Object.entries(headers)) {
-        const lower = key.toLowerCase();
-        sanitized[lower] = SENSITIVE_HEADERS.has(lower)
-            ? '[Filtered]'
-            : String(value);
-    }
-    return sanitized;
-}
-function truncate(body, maxLen = 2048) {
-    if (body === undefined || body === null)
-        return undefined;
-    const str = typeof body === 'string' ? body : JSON.stringify(body);
-    if (!str)
-        return undefined;
-    return str.length > maxLen ? str.slice(0, maxLen) + '...' : str;
-}

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