@edraj/sauron-node 1.0.0

package/README.md

@@ -0,0 +1,138 @@
+# @edraj/sauron-node
+
+Server-side Node/TypeScript SDK for [Sauron](https://sauron.dev) — dispatch
+product-analytics events and captured exceptions from your Node backends.
+
+This is the **server-side** SDK (no browser/DOM/auto-instrumentation). For the
+browser, use `@edraj/sauron-browser` (`sdks/js`).
+
+## Install
+
+```bash
+npm install @edraj/sauron-node
+```
+
+Requires Node >= 18 (uses the global `fetch` and `zlib`).
+
+## Usage
+
+```ts
+import {
+  init,
+  track,
+  captureException,
+  captureMessage,
+  identify,
+  trackTransaction,
+  addBreadcrumb,
+  withScope,
+  setUser,
+  setTag,
+  flush,
+  close,
+} from '@edraj/sauron-node';
+
+init({
+  dsn: 'https://<public_key>@<host>/<project_id>',
+  environment: 'production',
+  release: '1.4.2',
+  // Opt-in (both default off):
+  autoCaptureUnhandled: true, // capture uncaughtException / unhandledRejection
+  autoShutdown: true, // flush on beforeExit / SIGTERM / SIGINT
+});
+
+// Product analytics — distinctId is required.
+track('order_completed', 'user-123', { total: 42.5, currency: 'USD' });
+
+// Exceptions
+try {
+  doWork();
+} catch (err) {
+  captureException(err, { user: { id: 'user-123' }, tags: { area: 'checkout' } });
+}
+
+captureMessage('cache warm-up finished', 'info');
+identify('user-123', { plan: 'pro' });
+
+// On shutdown
+await close(); // flushes then stops the background timer
+```
+
+### Per-request scope
+
+Isolate user/tags/breadcrumbs per request with `withScope` — backed by
+`AsyncLocalStorage`, so concurrent requests never leak state into each other:
+
+```ts
+app.use((req, res, next) => {
+  withScope(() => {
+    setUser({ id: req.userId });
+    setTag('route', req.route.path);
+    addBreadcrumb({ category: 'http', message: `${req.method} ${req.url}` });
+    next();
+  });
+});
+```
+
+`captureException` automatically attaches the active scope's user, tags and
+breadcrumb trail. An optional `fingerprint` override is honored verbatim by the
+backend.
+
+### Transactions
+
+```ts
+trackTransaction({
+  name: 'GET /api/users',
+  op: 'http',
+  duration_ms: 12.5,
+  http_method: 'GET',
+  http_status: 200,
+}); // distinct_id falls back to the scoped user's id when omitted
+```
+
+## API
+
+| Function | Description |
+| --- | --- |
+| `init(options)` | Create the global client. Throws `DsnError` on an invalid DSN. |
+| `track(event, distinctId, properties?)` | Capture an analytics event. |
+| `captureException(error, options?)` | Capture a native `Error` (attaches scope). |
+| `captureMessage(message, level?)` | Capture a bare message. |
+| `identify(distinctId, traits?)` | Associate traits with a user. |
+| `trackTransaction(input)` | Emit a performance transaction. |
+| `addBreadcrumb(crumb)` | Add a breadcrumb to the active scope (runs `beforeBreadcrumb`). |
+| `setUser / setTag / setTags / setContext / setExtra` | Mutate the active scope. |
+| `withScope(cb)` / `configureScope(cb)` | Run with an isolated child scope / mutate the current one. |
+| `installShutdownHooks(client)` | Wire `beforeExit`/`SIGTERM`/`SIGINT` to `close()`. |
+| `flush()` | Send buffered items immediately. |
+| `close()` | Flush, stop the timer, and remove any installed process hooks. |
+
+Every dispatch function is a no-op before `init` / when the SDK is disabled.
+
+### `init` options
+
+`environment`, `release`, `sampleRate`, `flushInterval`, `maxBatch`,
+`maxBreadcrumbs` (default 100), `gzipThresholdBytes` (default 1024),
+`maxQueueBytes` (default 1 MiB), `offlineDir` (opt-in FIFO disk persistence),
+`maxRetries` (default 3), `autoCaptureUnhandled` (default off),
+`autoShutdown` (default off), `beforeSend(item)`, `beforeBreadcrumb(crumb)`.
+
+## Transport
+
+Items buffer in a byte-bounded in-memory queue (drop-oldest past `maxQueueBytes`,
+optionally persisted to `offlineDir` for at-least-once delivery across restarts)
+and flush every `flushInterval` ms (default 5000) or once `maxBatch` items
+(default 30) accumulate. The flush timer is `unref`'d so it never keeps your
+process alive. Each flush POSTs one envelope to
+`{proto}://{host}/api/{project_id}/envelope` with an `X-Sauron-Key` header,
+gzipping the body once it crosses `gzipThresholdBytes` (`Content-Encoding: gzip`).
+Transient failures (408/413/429/5xx, network) retry with exponential backoff +
+jitter honoring `Retry-After`; 400/401/403/404 drop without retry.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```

package/dist/autocapture.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Opt-in process-level hooks: auto-capture of uncaught errors and graceful
+ * shutdown. Both are OFF by default (see {@link InitOptions.autoCaptureUnhandled}
+ * / {@link InitOptions.autoShutdown}) and only installed when the consumer opts
+ * in.
+ *
+ * Auto-capture never *swallows* a crash. An uncaught exception is captured with
+ * `mechanism.handled = false`, the batch is flushed, and Node's default
+ * behavior is preserved: if this SDK is the *sole* `uncaughtException` handler,
+ * the process still exits non-zero (as Node would with no handler at all);
+ * if another handler is registered, that handler decides the process's fate.
+ * Unhandled rejections are captured but never terminate the process on their
+ * own — Node's own `unhandledRejection` mode still governs that.
+ */
+import type { ProcessLike } from './types.js';
+import type { SauronClient } from './client.js';
+export interface AutoCaptureOptions {
+    /** Injected process (tests). Defaults to the real Node `process`. */
+    process?: ProcessLike;
+}
+type Uninstaller = () => void;
+/**
+ * Register `uncaughtException` + `unhandledRejection` handlers that capture with
+ * `mechanism.handled = false`. Idempotent per client; returns an uninstaller
+ * that removes the listeners.
+ */
+export declare function installAutoCapture(client: SauronClient, options?: AutoCaptureOptions): Uninstaller;
+/**
+ * Wire `beforeExit`/`SIGTERM`/`SIGINT` to `client.close()` for a graceful flush
+ * on shutdown. `beforeExit` (event loop drained) just closes; a terminating
+ * signal closes then exits with the conventional code so the SDK does not hang
+ * the process. Idempotent per client; returns an uninstaller.
+ */
+export declare function installShutdownHooks(client: SauronClient, options?: AutoCaptureOptions): Uninstaller;
+export {};

package/dist/autocapture.js

@@ -0,0 +1,115 @@
+/**
+ * Opt-in process-level hooks: auto-capture of uncaught errors and graceful
+ * shutdown. Both are OFF by default (see {@link InitOptions.autoCaptureUnhandled}
+ * / {@link InitOptions.autoShutdown}) and only installed when the consumer opts
+ * in.
+ *
+ * Auto-capture never *swallows* a crash. An uncaught exception is captured with
+ * `mechanism.handled = false`, the batch is flushed, and Node's default
+ * behavior is preserved: if this SDK is the *sole* `uncaughtException` handler,
+ * the process still exits non-zero (as Node would with no handler at all);
+ * if another handler is registered, that handler decides the process's fate.
+ * Unhandled rejections are captured but never terminate the process on their
+ * own — Node's own `unhandledRejection` mode still governs that.
+ */
+/** Conventional exit code for a terminating signal (`128 + signal number`). */
+const SIGNAL_EXIT_CODE = { SIGINT: 130, SIGTERM: 143 };
+const autoCaptureInstalled = new WeakMap();
+const shutdownInstalled = new WeakMap();
+function realProcess() {
+    return process;
+}
+/**
+ * Register `uncaughtException` + `unhandledRejection` handlers that capture with
+ * `mechanism.handled = false`. Idempotent per client; returns an uninstaller
+ * that removes the listeners.
+ */
+export function installAutoCapture(client, options = {}) {
+    const existing = autoCaptureInstalled.get(client);
+    if (existing)
+        return existing;
+    const proc = options.process ?? realProcess();
+    // Guard against a capture path itself throwing and re-entering the handler.
+    let capturing = false;
+    const onUncaught = (error) => {
+        if (capturing)
+            return;
+        capturing = true;
+        try {
+            client.captureException(error, { level: 'fatal', handled: false });
+        }
+        catch {
+            // Never let a capture failure mask the original crash.
+        }
+        capturing = false;
+        void client.flush().then(exitIfSole, exitIfSole);
+    };
+    const exitIfSole = () => {
+        const others = proc
+            .listeners('uncaughtException')
+            .filter((listener) => listener !== onUncaught);
+        if (others.length === 0)
+            proc.exit(1);
+    };
+    const onRejection = (reason) => {
+        if (capturing)
+            return;
+        capturing = true;
+        try {
+            client.captureException(reason, { level: 'error', handled: false });
+        }
+        catch {
+            // ignore — see above.
+        }
+        capturing = false;
+        void client.flush();
+    };
+    proc.on('uncaughtException', onUncaught);
+    proc.on('unhandledRejection', onRejection);
+    const uninstall = () => {
+        proc.removeListener('uncaughtException', onUncaught);
+        proc.removeListener('unhandledRejection', onRejection);
+        autoCaptureInstalled.delete(client);
+    };
+    autoCaptureInstalled.set(client, uninstall);
+    return uninstall;
+}
+/**
+ * Wire `beforeExit`/`SIGTERM`/`SIGINT` to `client.close()` for a graceful flush
+ * on shutdown. `beforeExit` (event loop drained) just closes; a terminating
+ * signal closes then exits with the conventional code so the SDK does not hang
+ * the process. Idempotent per client; returns an uninstaller.
+ */
+export function installShutdownHooks(client, options = {}) {
+    const existing = shutdownInstalled.get(client);
+    if (existing)
+        return existing;
+    const proc = options.process ?? realProcess();
+    let closing = false;
+    const onBeforeExit = () => {
+        if (closing)
+            return;
+        closing = true;
+        void client.close();
+    };
+    const makeSignalHandler = (signal) => () => {
+        if (closing)
+            return;
+        closing = true;
+        const code = SIGNAL_EXIT_CODE[signal] ?? 0;
+        void client.close().then(() => proc.exit(code), () => proc.exit(code));
+    };
+    const onSigterm = makeSignalHandler('SIGTERM');
+    const onSigint = makeSignalHandler('SIGINT');
+    proc.on('beforeExit', onBeforeExit);
+    proc.on('SIGTERM', onSigterm);
+    proc.on('SIGINT', onSigint);
+    const uninstall = () => {
+        proc.removeListener('beforeExit', onBeforeExit);
+        proc.removeListener('SIGTERM', onSigterm);
+        proc.removeListener('SIGINT', onSigint);
+        shutdownInstalled.delete(client);
+    };
+    shutdownInstalled.set(client, uninstall);
+    return uninstall;
+}

package/dist/client.d.ts

@@ -0,0 +1,42 @@
+import type { BreadcrumbInput, CaptureExceptionOptions, InitOptions, Level, MetadataOptions, TransactionInput } from './types.js';
+/**
+ * The Sauron server-side client. Buffers events/errors and dispatches them via
+ * a background transport. Constructed by {@link init}.
+ */
+export declare class SauronClient {
+    private readonly options;
+    private readonly transport;
+    /** Uninstallers for any opt-in process-level hooks, torn down on {@link close}. */
+    private readonly hookUninstallers;
+    constructor(options: InitOptions);
+    /**
+     * The single enqueue chokepoint. Runs `beforeSend` on every item; a `null`
+     * return drops it, a returned item replaces it, then it is handed to the
+     * transport.
+     */
+    private dispatch;
+    /**
+     * Add a breadcrumb to the active scope. Runs `beforeBreadcrumb` first; a
+     * `null` return drops the crumb.
+     */
+    addBreadcrumb(crumb: BreadcrumbInput): void;
+    /** Emit a performance transaction item. */
+    trackTransaction(input: TransactionInput): void;
+    /** Capture a product-analytics event. `distinctId` is required. */
+    track(event: string, distinctId: string, properties?: Record<string, unknown>, options?: MetadataOptions): void;
+    /** Capture a native `Error` (or error-like value) as an error item. */
+    captureException(error: unknown, options?: CaptureExceptionOptions): void;
+    /** Capture a bare message as an error item (no exception payload). */
+    captureMessage(message: string, level?: Level, options?: MetadataOptions): void;
+    /** Associate traits with a distinct id. */
+    identify(distinctId: string, traits?: Record<string, unknown>): void;
+    /** Send any buffered items immediately. */
+    flush(): Promise<void>;
+    /** Flush then stop the background timer, and remove any opt-in process hooks. */
+    close(): Promise<void>;
+}
+/** Derive `{type, value}` from an arbitrary thrown value. */
+export declare function describeError(error: unknown): {
+    type: string;
+    value: string | null;
+};

package/dist/client.js

@@ -0,0 +1,291 @@
+import os from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { parseDsn } from './dsn.js';
+import { Transport } from './transport.js';
+import { parseError } from './stacktrace.js';
+import { installAutoCapture, installShutdownHooks } from './autocapture.js';
+import { getCurrentScope, getGlobalScope, normalizeBreadcrumb, } from './scope.js';
+const DEFAULTS = {
+    environment: 'production',
+    release: null,
+    sampleRate: 1,
+    flushInterval: 5000,
+    maxBatch: 30,
+    maxBreadcrumbs: 100,
+    gzipThresholdBytes: 1024,
+    maxQueueBytes: 1_048_576,
+    maxRetries: 3,
+    debug: false,
+};
+function resolveOptions(options) {
+    if (!options || typeof options.dsn !== 'string') {
+        throw new Error('[sauron] init requires a { dsn } option');
+    }
+    const sampleRate = typeof options.sampleRate === 'number' ? options.sampleRate : DEFAULTS.sampleRate;
+    return {
+        dsn: options.dsn,
+        environment: options.environment ?? DEFAULTS.environment,
+        release: options.release ?? DEFAULTS.release,
+        tags: options.tags ?? {},
+        contexts: options.contexts ?? {},
+        extra: options.extra ?? {},
+        sampleRate: Math.min(1, Math.max(0, sampleRate)),
+        flushInterval: typeof options.flushInterval === 'number'
+            ? options.flushInterval
+            : DEFAULTS.flushInterval,
+        maxBatch: typeof options.maxBatch === 'number' ? options.maxBatch : DEFAULTS.maxBatch,
+        maxBreadcrumbs: typeof options.maxBreadcrumbs === 'number'
+            ? options.maxBreadcrumbs
+            : DEFAULTS.maxBreadcrumbs,
+        gzipThresholdBytes: typeof options.gzipThresholdBytes === 'number'
+            ? options.gzipThresholdBytes
+            : DEFAULTS.gzipThresholdBytes,
+        maxQueueBytes: typeof options.maxQueueBytes === 'number'
+            ? options.maxQueueBytes
+            : DEFAULTS.maxQueueBytes,
+        offlineDir: options.offlineDir ?? null,
+        maxRetries: typeof options.maxRetries === 'number' ? options.maxRetries : DEFAULTS.maxRetries,
+        autoCaptureUnhandled: options.autoCaptureUnhandled ?? false,
+        autoShutdown: options.autoShutdown ?? false,
+        beforeSend: options.beforeSend,
+        beforeBreadcrumb: options.beforeBreadcrumb,
+        fetchImpl: options.fetchImpl,
+        debug: options.debug ?? DEFAULTS.debug,
+    };
+}
+/** Minimal server-side context assembled once at init. */
+function buildContext() {
+    return {
+        device: { device_id: randomUUID() },
+        os: { name: process.platform || null, version: os.release() || null },
+        app: {},
+        runtime: { name: 'node', version: process.versions.node ?? null },
+        user: null,
+    };
+}
+function isoNow() {
+    return new Date().toISOString();
+}
+function normalizeUser(user) {
+    if (!user)
+        return null;
+    return {
+        id: user.id ?? null,
+        email: user.email ?? null,
+        username: user.username ?? null,
+    };
+}
+/**
+ * The Sauron server-side client. Buffers events/errors and dispatches them via
+ * a background transport. Constructed by {@link init}.
+ */
+export class SauronClient {
+    options;
+    transport;
+    /** Uninstallers for any opt-in process-level hooks, torn down on {@link close}. */
+    hookUninstallers = [];
+    constructor(options) {
+        this.options = resolveOptions(options);
+        const dsn = parseDsn(this.options.dsn);
+        const globalScope = getGlobalScope();
+        globalScope.setMaxBreadcrumbs(this.options.maxBreadcrumbs);
+        globalScope.setTags(this.options.tags);
+        for (const [name, block] of Object.entries(this.options.contexts)) {
+            globalScope.setContext(name, block);
+        }
+        for (const [key, value] of Object.entries(this.options.extra)) {
+            globalScope.setExtra(key, value);
+        }
+        this.transport = new Transport({
+            dsn,
+            environment: this.options.environment,
+            release: this.options.release,
+            context: buildContext(),
+            flushInterval: this.options.flushInterval,
+            maxBatch: this.options.maxBatch,
+            gzipThresholdBytes: this.options.gzipThresholdBytes,
+            maxQueueBytes: this.options.maxQueueBytes,
+            offlineDir: this.options.offlineDir,
+            maxRetries: this.options.maxRetries,
+            fetchImpl: this.options.fetchImpl,
+            debug: this.options.debug,
+        });
+        if (this.options.autoCaptureUnhandled) {
+            this.hookUninstallers.push(installAutoCapture(this));
+        }
+        if (this.options.autoShutdown) {
+            this.hookUninstallers.push(installShutdownHooks(this));
+        }
+    }
+    /**
+     * The single enqueue chokepoint. Runs `beforeSend` on every item; a `null`
+     * return drops it, a returned item replaces it, then it is handed to the
+     * transport.
+     */
+    dispatch(item) {
+        const beforeSend = this.options.beforeSend;
+        if (beforeSend) {
+            const result = beforeSend(item);
+            if (result == null)
+                return;
+            this.transport.enqueue(result);
+            return;
+        }
+        this.transport.enqueue(item);
+    }
+    /**
+     * Add a breadcrumb to the active scope. Runs `beforeBreadcrumb` first; a
+     * `null` return drops the crumb.
+     */
+    addBreadcrumb(crumb) {
+        const stamped = normalizeBreadcrumb(crumb);
+        const beforeBreadcrumb = this.options.beforeBreadcrumb;
+        if (beforeBreadcrumb) {
+            const result = beforeBreadcrumb(stamped);
+            if (result == null)
+                return;
+            getCurrentScope().addBreadcrumb(result);
+            return;
+        }
+        getCurrentScope().addBreadcrumb(stamped);
+    }
+    /** Emit a performance transaction item. */
+    trackTransaction(input) {
+        if (typeof input?.name !== 'string' || input.name.length === 0)
+            return;
+        const distinctId = input.distinct_id ?? getCurrentScope().data.user?.id ?? undefined;
+        const item = {
+            type: 'transaction',
+            name: input.name,
+            op: input.op ?? 'custom',
+            duration_ms: input.duration_ms,
+            timestamp: isoNow(),
+        };
+        if (input.status !== undefined)
+            item.status = input.status;
+        if (input.http_method !== undefined)
+            item.http_method = input.http_method;
+        if (input.http_status !== undefined)
+            item.http_status = input.http_status;
+        if (input.url !== undefined)
+            item.url = input.url;
+        if (distinctId != null)
+            item.distinct_id = distinctId;
+        this.dispatch(item);
+    }
+    /** Capture a product-analytics event. `distinctId` is required. */
+    track(event, distinctId, properties, options = {}) {
+        if (typeof event !== 'string' || event.length === 0)
+            return;
+        if (typeof distinctId !== 'string' || distinctId.length === 0)
+            return;
+        const item = {
+            type: 'event',
+            name: event,
+            distinct_id: distinctId,
+            properties: properties ?? {},
+            timestamp: isoNow(),
+            session_id: null,
+            screen: null,
+            ...getCurrentScope().mergeMetadata(options),
+        };
+        this.dispatch(item);
+    }
+    /** Capture a native `Error` (or error-like value) as an error item. */
+    captureException(error, options = {}) {
+        if (this.options.sampleRate < 1 && Math.random() >= this.options.sampleRate) {
+            return;
+        }
+        const { type, value } = describeError(error);
+        const item = {
+            type: 'error',
+            event_id: randomUUID(),
+            level: options.level ?? 'error',
+            timestamp: isoNow(),
+            exception: {
+                type,
+                value,
+                mechanism: { type: 'generic', handled: options.handled ?? true },
+                stacktrace: parseError(error),
+            },
+            message: null,
+            breadcrumbs: [],
+            tags: options.tags ?? {},
+            contexts: options.contexts ?? {},
+            extra: options.extra ?? {},
+            fingerprint: options.fingerprint ?? null,
+            user: normalizeUser(options.user),
+            session_id: null,
+            screen: null,
+        };
+        getCurrentScope().applyToErrorItem(item);
+        this.dispatch(item);
+    }
+    /** Capture a bare message as an error item (no exception payload). */
+    captureMessage(message, level = 'info', options = {}) {
+        const item = {
+            type: 'error',
+            event_id: randomUUID(),
+            level,
+            timestamp: isoNow(),
+            exception: {
+                type: 'Message',
+                value: message,
+                mechanism: { type: 'generic', handled: true },
+                stacktrace: [],
+            },
+            message,
+            breadcrumbs: [],
+            tags: options.tags ?? {},
+            contexts: options.contexts ?? {},
+            extra: options.extra ?? {},
+            fingerprint: null,
+            user: null,
+            session_id: null,
+            screen: null,
+        };
+        getCurrentScope().applyToErrorItem(item);
+        this.dispatch(item);
+    }
+    /** Associate traits with a distinct id. */
+    identify(distinctId, traits) {
+        if (typeof distinctId !== 'string' || distinctId.length === 0)
+            return;
+        const item = {
+            type: 'identify',
+            distinct_id: distinctId,
+            anonymous_id: null,
+            traits: traits ?? {},
+            timestamp: isoNow(),
+        };
+        this.dispatch(item);
+    }
+    /** Send any buffered items immediately. */
+    flush() {
+        return this.transport.flush();
+    }
+    /** Flush then stop the background timer, and remove any opt-in process hooks. */
+    close() {
+        for (const uninstall of this.hookUninstallers.splice(0))
+            uninstall();
+        return this.transport.close();
+    }
+}
+/** Derive `{type, value}` from an arbitrary thrown value. */
+export function describeError(error) {
+    if (error instanceof Error) {
+        return { type: error.name || 'Error', value: error.message || null };
+    }
+    if (typeof error === 'string') {
+        return { type: 'Error', value: error };
+    }
+    if (error && typeof error === 'object') {
+        const name = error.name;
+        const message = error.message;
+        return {
+            type: typeof name === 'string' && name ? name : 'Error',
+            value: typeof message === 'string' ? message : null,
+        };
+    }
+    return { type: 'Error', value: error === undefined ? null : String(error) };
+}

package/dist/dsn.d.ts

@@ -0,0 +1,25 @@
+/**
+ * DSN parsing.
+ *
+ * A DSN looks like `https://<public_key>@<host>/<project_id>`. The public key
+ * is a non-secret, write-only credential.
+ */
+export interface Dsn {
+    /** The raw DSN string (embedded verbatim into the envelope header). */
+    raw: string;
+    publicKey: string;
+    /** `host:port` — used to build the endpoint. */
+    host: string;
+    /** Hostname without port. */
+    hostname: string;
+    /** `https` or `http` (no trailing colon). */
+    protocol: string;
+    projectId: string;
+    /** `POST` target: `{protocol}://{host}/api/{project_id}/envelope`. */
+    envelopeUrl: string;
+}
+export declare class DsnError extends Error {
+    constructor(message: string);
+}
+/** Parse and validate a DSN, deriving the transport URL. */
+export declare function parseDsn(dsn: string): Dsn;