@gurulu/node 0.1.1 → 0.1.2

package/dist/business-events.d.ts

@@ -49,8 +49,8 @@ export declare function paymentSucceeded(args: PaymentSucceededArgs): BusinessEv
 export interface SubscriptionStartedArgs {
     userId: string;
     plan: string;
-    amount?: number;
-    currency?: string;
+    amount: number;
+    currency: string;
 }
 export declare function subscriptionStarted(args: SubscriptionStartedArgs): BusinessEvent;
 export interface OrderPlacedArgs {

package/dist/business-events.js

@@ -80,11 +80,9 @@ function paymentSucceeded(args) {
 function subscriptionStarted(args) {
     const props = {
         plan: args.plan,
+        amount: args.amount,
+        currency: args.currency,
     };
-    if (args.amount !== undefined)
-        props.amount = args.amount;
-    if (args.currency !== undefined)
-        props.currency = args.currency;
     const env = baseEnvelope('subscription_started', args.userId, props);
     return toBusinessEvent(env, args.userId);
 }

package/dist/client.d.ts

@@ -19,11 +19,46 @@
  */
 import type { ServerEvent } from '@gurulu/shared-core';
 import type { GuruluClientConfig } from './types';
+export interface IdentifyParams {
+    /** The known user ID (e.g. database ID, email, etc.) */
+    userId: string;
+    /** An anonymous/session ID to link with this user. Required by the identify endpoint. */
+    anonymousId: string;
+    /** User traits (email, name, plan, etc.) to persist on the identity profile. */
+    traits?: Record<string, unknown>;
+    /** Device ID for cross-device identity resolution. */
+    deviceId?: string;
+    /** OAuth provider name (e.g. 'google', 'github'). */
+    oauthProvider?: string;
+    /** OAuth user ID from the provider. */
+    oauthId?: string;
+    /** Consent level: 'none' | 'analytics' | 'marketing' | 'full'. */
+    consentLevel?: string;
+}
+export interface IdentifyResponse {
+    status: string;
+    canonical_id: string | null;
+    consent_skipped?: boolean;
+    merges?: Array<{
+        winner: string;
+        loser: string;
+        reason: string;
+        claim_types: string[];
+    }>;
+}
+export interface Breadcrumb {
+    timestamp: string;
+    category: string;
+    message: string;
+    data?: Record<string, unknown>;
+}
 export interface GuruluClient {
     track(event: ServerEvent): void;
+    identify(params: IdentifyParams): Promise<IdentifyResponse>;
     flush(): Promise<void>;
     shutdown(): Promise<void>;
     captureException(error: Error, context?: Record<string, unknown>): void;
+    addBreadcrumb(category: string, message: string, data?: Record<string, unknown>): void;
     installGlobalHandlers(): void;
     /** Current queue length — exposed for tests and observability. */
     readonly queueSize: number;
@@ -45,18 +80,32 @@ export declare class Gurulu implements GuruluClient {
     private readonly onDeadLetter?;
     private readonly fetchImpl;
     private readonly debug;
+    private readonly release;
     private queue;
+    private breadcrumbs;
+    private readonly maxBreadcrumbs;
     private flushTimer;
     private inFlight;
     private shutdownHandlers;
     constructor(config: GuruluClientConfig);
     get queueSize(): number;
+    private static readonly REVENUE_EVENTS;
     /**
      * 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;
+    /**
+     * 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.
+     */
+    identify(params: IdentifyParams): Promise<IdentifyResponse>;
     /**
      * POST all queued events in one batch. On 5xx / network error retries with
      * exponential backoff (200ms, 600ms, 1800ms). On 4xx drops the batch and
@@ -64,8 +113,14 @@ export declare class Gurulu implements GuruluClient {
      */
     flush(): Promise<void>;
     private sendBatch;
+    /**
+     * 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: string, message: string, data?: Record<string, unknown>): void;
     /**
      * Capture an exception and send it as an error event.
+     * Includes any accumulated breadcrumbs for debugging context.
      */
     captureException(error: Error, context?: Record<string, unknown>): void;
     /**
@@ -88,3 +143,8 @@ export declare function setDefaultInstance(instance: Gurulu): void;
  * Call `setDefaultInstance()` first (or create a Gurulu client).
  */
 export declare function captureException(error: Error, context?: Record<string, unknown>): void;
+/**
+ * Convenience function — adds a breadcrumb via the default instance.
+ * Call `setDefaultInstance()` first (or create a Gurulu client).
+ */
+export declare function addBreadcrumb(category: string, message: string, data?: Record<string, unknown>): void;

package/dist/client.js

@@ -23,8 +23,10 @@ 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;
@@ -54,7 +56,10 @@ class Gurulu {
     onDeadLetter;
     fetchImpl;
     debug;
+    release;
     queue = [];
+    breadcrumbs = [];
+    maxBreadcrumbs = 50;
     flushTimer = null;
     inFlight = null;
     shutdownHandlers = [];
@@ -72,6 +77,7 @@ class Gurulu {
         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;
@@ -111,6 +117,14 @@ class Gurulu {
     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
@@ -127,6 +141,19 @@ class Gurulu {
                 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(),
@@ -139,6 +166,71 @@ class Gurulu {
             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
@@ -173,12 +265,16 @@ class Gurulu {
         };
         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`);
@@ -202,8 +298,16 @@ class Gurulu {
                 this.onError?.(lastError);
             }
             catch (err) {
-                lastError = err instanceof Error ? err : new Error(String(err));
-                this.onError?.(lastError);
+                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) {
@@ -225,10 +329,27 @@ class Gurulu {
             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__',
@@ -236,6 +357,10 @@ class Gurulu {
                 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,
             },
         });
@@ -305,3 +430,13 @@ function captureException(error, context) {
     }
     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/index.d.ts

@@ -4,9 +4,10 @@
  * Phase 10 W4.2: server SDK hardening adds batch+retry, deterministic
  * idempotency keys, dead-letter callbacks, and business event emitters.
  */
-export { Gurulu, createIdempotencyKey, captureException, setDefaultInstance } from './client';
-export type { GuruluClient } from './client';
+export { Gurulu, createIdempotencyKey, captureException, addBreadcrumb, setDefaultInstance } from './client';
+export type { GuruluClient, IdentifyParams, IdentifyResponse, Breadcrumb } from './client';
 export type { GuruluClientConfig, DeadLetterCallback, ErrorCallback, } from './types';
 export type { Envelope, ServerEvent, EventTier, EventSource, ConsentLevel, } from '@gurulu/shared-core';
+export { expressErrorHandler, expressHandler, guruluFastifyPlugin, honoErrorHandler, } from './middleware';
 export { userCreated, paymentSucceeded, subscriptionStarted, orderPlaced, leadCaptured, } from './business-events';
 export type { BusinessEvent, UserCreatedArgs, PaymentSucceededArgs, SubscriptionStartedArgs, OrderPlacedArgs, LeadCapturedArgs, } from './business-events';

package/dist/index.js

@@ -6,12 +6,19 @@
  * 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.setDefaultInstance = exports.captureException = exports.createIdempotencyKey = exports.Gurulu = void 0;
+exports.leadCaptured = exports.orderPlaced = exports.subscriptionStarted = exports.paymentSucceeded = exports.userCreated = exports.honoErrorHandler = exports.guruluFastifyPlugin = exports.expressHandler = exports.expressErrorHandler = exports.setDefaultInstance = exports.addBreadcrumb = 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, "addBreadcrumb", { enumerable: true, get: function () { return client_1.addBreadcrumb; } });
 Object.defineProperty(exports, "setDefaultInstance", { enumerable: true, get: function () { return client_1.setDefaultInstance; } });
+// Framework error-handler middleware.
+var middleware_1 = require("./middleware");
+Object.defineProperty(exports, "expressErrorHandler", { enumerable: true, get: function () { return middleware_1.expressErrorHandler; } });
+Object.defineProperty(exports, "expressHandler", { enumerable: true, get: function () { return middleware_1.expressHandler; } });
+Object.defineProperty(exports, "guruluFastifyPlugin", { enumerable: true, get: function () { return middleware_1.guruluFastifyPlugin; } });
+Object.defineProperty(exports, "honoErrorHandler", { enumerable: true, get: function () { return middleware_1.honoErrorHandler; } });
 // 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/dist/middleware.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @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

@@ -0,0 +1,138 @@
+"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.d.ts

@@ -27,6 +27,8 @@ export type ErrorCallback = (err: Error) => void;
 export interface GuruluClientConfig {
     siteId: string;
     apiKey: string;
+    /** Release version or git SHA for source map resolution. Falls back to GURULU_RELEASE env var. */
+    release?: string;
     endpoint?: string;
     /** Periodic flush interval in ms. Default 5000. */
     flushInterval?: number;

package/package.json

@@ -1,10 +1,23 @@
 {
   "name": "@gurulu/node",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Gurulu.io server-side analytics SDK for Node.js",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": ["dist"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware.d.ts",
+      "import": "./dist/middleware.js",
+      "require": "./dist/middleware.js"
+    },
+    "./package.json": "./package.json"
+  },
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch"