@gurulu/node 0.1.0 → 0.1.2

package/dist/{node-sdk/src/business-events.d.ts → 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/{node-sdk/src/business-events.js → 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

@@ -0,0 +1,150 @@
+/**
+ * @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 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;
+}
+/**
+ * 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 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
+     * fires the dead-letter callback. Concurrent flush calls are serialized.
+     */
+    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;
+    /**
+     * Install global error handlers for uncaught exceptions and unhandled rejections.
+     * Call once at app startup.
+     */
+    installGlobalHandlers(): void;
+    /**
+     * Stop the periodic flush timer, detach process listeners, and perform a
+     * final flush. Safe to call multiple times.
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * Set the default Gurulu instance used by the convenience `captureException`.
+ */
+export declare function setDefaultInstance(instance: Gurulu): void;
+/**
+ * Convenience function — captures an exception via the default instance.
+ * 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/{node-sdk/src/client.js → client.js}

@@ -21,8 +21,12 @@
 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;
@@ -52,7 +56,10 @@ class Gurulu {
     onDeadLetter;
     fetchImpl;
     debug;
+    release;
     queue = [];
+    breadcrumbs = [];
+    maxBreadcrumbs = 50;
     flushTimer = null;
     inFlight = null;
     shutdownHandlers = [];
@@ -70,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;
@@ -109,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
@@ -125,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(),
@@ -137,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
@@ -171,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`);
@@ -200,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) {
@@ -223,6 +329,57 @@ 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__',
+            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.
@@ -253,3 +410,33 @@ async function safeText(res) {
 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/{node-sdk/src/index.d.ts → 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 } 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/{node-sdk/src/index.js → index.js}

@@ -6,10 +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.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/{node-sdk/src/types.d.ts → 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.0",
+  "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"