@edraj/sauron-node 1.0.0

package/dist/dsn.js

@@ -0,0 +1,55 @@
+/**
+ * DSN parsing.
+ *
+ * A DSN looks like `https://<public_key>@<host>/<project_id>`. The public key
+ * is a non-secret, write-only credential.
+ */
+export class DsnError extends Error {
+    constructor(message) {
+        super(`[sauron] invalid DSN: ${message}`);
+        this.name = 'DsnError';
+    }
+}
+/** Parse and validate a DSN, deriving the transport URL. */
+export function parseDsn(dsn) {
+    if (typeof dsn !== 'string' || dsn.length === 0) {
+        throw new DsnError('DSN must be a non-empty string');
+    }
+    let url;
+    try {
+        url = new URL(dsn);
+    }
+    catch {
+        throw new DsnError(`could not parse "${dsn}"`);
+    }
+    const protocol = url.protocol.replace(/:$/, '');
+    if (protocol !== 'http' && protocol !== 'https') {
+        throw new DsnError(`unsupported protocol "${protocol}"`);
+    }
+    const publicKey = url.username;
+    if (!publicKey) {
+        throw new DsnError('missing public key (the "user" part of the URL)');
+    }
+    if (url.password) {
+        throw new DsnError('DSN must not contain a secret (password component)');
+    }
+    const host = url.host; // includes port when present
+    const hostname = url.hostname;
+    if (!host) {
+        throw new DsnError('missing host');
+    }
+    const projectId = url.pathname.replace(/^\/+/, '').replace(/\/+$/, '');
+    if (!projectId) {
+        throw new DsnError('missing project id (the path segment)');
+    }
+    const envelopeUrl = `${protocol}://${host}/api/${projectId}/envelope`;
+    return {
+        raw: dsn,
+        publicKey,
+        host,
+        hostname,
+        protocol,
+        projectId,
+        envelopeUrl,
+    };
+}

package/dist/gzip.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Optional gzip of the request body.
+ *
+ * The ingest accepts `Content-Encoding: gzip` (see the module docs in
+ * `sauron-core/src/envelope.rs`). We only pay the CPU cost when the payload is
+ * large enough to matter — bodies at or below `threshold` bytes go out
+ * uncompressed. Node >= 18 ships `zlib`, so this adds no runtime dependency.
+ */
+/** The (possibly compressed) body plus the headers to merge into the request. */
+export interface MaybeGzipResult {
+    body: Buffer | string;
+    headers: Record<string, string>;
+}
+/**
+ * Gzip `body` when its byte length exceeds `threshold`; otherwise pass it
+ * through untouched. Returns the encoding header only when compression happened.
+ * A negative threshold disables compression entirely.
+ */
+export declare function maybeGzip(body: string, threshold: number): MaybeGzipResult;

package/dist/gzip.js

@@ -0,0 +1,20 @@
+/**
+ * Optional gzip of the request body.
+ *
+ * The ingest accepts `Content-Encoding: gzip` (see the module docs in
+ * `sauron-core/src/envelope.rs`). We only pay the CPU cost when the payload is
+ * large enough to matter — bodies at or below `threshold` bytes go out
+ * uncompressed. Node >= 18 ships `zlib`, so this adds no runtime dependency.
+ */
+import { gzipSync } from 'node:zlib';
+/**
+ * Gzip `body` when its byte length exceeds `threshold`; otherwise pass it
+ * through untouched. Returns the encoding header only when compression happened.
+ * A negative threshold disables compression entirely.
+ */
+export function maybeGzip(body, threshold) {
+    if (threshold < 0 || Buffer.byteLength(body) <= threshold) {
+        return { body, headers: {} };
+    }
+    return { body: gzipSync(body), headers: { 'Content-Encoding': 'gzip' } };
+}

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @edraj/sauron-node — server-side Node/TypeScript SDK.
+ *
+ * Dispatches product-analytics events and captured exceptions to the Sauron
+ * ingest gateway. No browser/DOM/auto-instrumentation — a buffered background
+ * HTTP transport over Node's global `fetch`.
+ */
+import { SauronClient } from './client.js';
+import type { BreadcrumbInput, CaptureExceptionOptions, InitOptions, Level, MetadataOptions, TransactionInput, User } from './types.js';
+export { SauronClient, describeError } from './client.js';
+export { parseDsn, DsnError } from './dsn.js';
+export type { Dsn } from './dsn.js';
+export { parseStackString, parseError, isInAppFrame } from './stacktrace.js';
+export { Transport } from './transport.js';
+export { Scope, getGlobalScope, getCurrentScope, withScope, runWithAsyncScope, configureScope, } from './scope.js';
+export { installAutoCapture, installShutdownHooks } from './autocapture.js';
+export type { AutoCaptureOptions } from './autocapture.js';
+export type * from './types.js';
+/**
+ * Initialize the global Sauron client. Returns the client for direct use.
+ * A clearly-invalid DSN throws a typed `DsnError`.
+ */
+export declare function init(options: InitOptions): SauronClient;
+/** The client created by the most recent {@link init}, if any. */
+export declare function getClient(): SauronClient | null;
+/** Capture a product-analytics event. No-op if the SDK is not initialized. */
+export declare function track(event: string, distinctId: string, properties?: Record<string, unknown>, options?: MetadataOptions): void;
+/** Capture a native `Error`. No-op if the SDK is not initialized. */
+export declare function captureException(error: unknown, options?: CaptureExceptionOptions): void;
+/** Capture a bare message. No-op if the SDK is not initialized. */
+export declare function captureMessage(message: string, level?: Level, options?: MetadataOptions): void;
+/** Associate traits with a distinct id. No-op if the SDK is not initialized. */
+export declare function identify(distinctId: string, traits?: Record<string, unknown>): void;
+/**
+ * Emit a performance transaction. No-op if the SDK is not initialized.
+ * `distinct_id` falls back to the scoped user's id when omitted.
+ */
+export declare function trackTransaction(input: TransactionInput): void;
+/**
+ * Add a breadcrumb to the active scope (runs `beforeBreadcrumb`). No-op if the
+ * SDK is not initialized.
+ */
+export declare function addBreadcrumb(crumb: BreadcrumbInput): void;
+/** Set the user on the active scope (the global scope outside a `withScope`). */
+export declare function setUser(user: User | null): void;
+/** Set a single tag on the active scope. */
+export declare function setTag(key: string, value: string): void;
+/** Merge several tags onto the active scope. */
+export declare function setTags(tags: Record<string, string>): void;
+/** Set a named free-form context block on the active scope. */
+export declare function setContext(key: string, context: Record<string, unknown> | unknown): void;
+/** Set a single free-form extra value on the active scope. */
+export declare function setExtra(key: string, value: unknown): void;
+/** Flush buffered items immediately. Resolves once sent (or if not init). */
+export declare function flush(): Promise<void>;
+/** Flush and stop the background timer, then clear the active client. */
+export declare function close(): Promise<void>;

package/dist/index.js

@@ -0,0 +1,90 @@
+/**
+ * @edraj/sauron-node — server-side Node/TypeScript SDK.
+ *
+ * Dispatches product-analytics events and captured exceptions to the Sauron
+ * ingest gateway. No browser/DOM/auto-instrumentation — a buffered background
+ * HTTP transport over Node's global `fetch`.
+ */
+import { SauronClient } from './client.js';
+import { getCurrentScope } from './scope.js';
+export { SauronClient, describeError } from './client.js';
+export { parseDsn, DsnError } from './dsn.js';
+export { parseStackString, parseError, isInAppFrame } from './stacktrace.js';
+export { Transport } from './transport.js';
+export { Scope, getGlobalScope, getCurrentScope, withScope, runWithAsyncScope, configureScope, } from './scope.js';
+export { installAutoCapture, installShutdownHooks } from './autocapture.js';
+let activeClient = null;
+/**
+ * Initialize the global Sauron client. Returns the client for direct use.
+ * A clearly-invalid DSN throws a typed `DsnError`.
+ */
+export function init(options) {
+    activeClient = new SauronClient(options);
+    return activeClient;
+}
+/** The client created by the most recent {@link init}, if any. */
+export function getClient() {
+    return activeClient;
+}
+/** Capture a product-analytics event. No-op if the SDK is not initialized. */
+export function track(event, distinctId, properties, options) {
+    activeClient?.track(event, distinctId, properties, options);
+}
+/** Capture a native `Error`. No-op if the SDK is not initialized. */
+export function captureException(error, options) {
+    activeClient?.captureException(error, options);
+}
+/** Capture a bare message. No-op if the SDK is not initialized. */
+export function captureMessage(message, level, options) {
+    activeClient?.captureMessage(message, level, options);
+}
+/** Associate traits with a distinct id. No-op if the SDK is not initialized. */
+export function identify(distinctId, traits) {
+    activeClient?.identify(distinctId, traits);
+}
+/**
+ * Emit a performance transaction. No-op if the SDK is not initialized.
+ * `distinct_id` falls back to the scoped user's id when omitted.
+ */
+export function trackTransaction(input) {
+    activeClient?.trackTransaction(input);
+}
+/**
+ * Add a breadcrumb to the active scope (runs `beforeBreadcrumb`). No-op if the
+ * SDK is not initialized.
+ */
+export function addBreadcrumb(crumb) {
+    activeClient?.addBreadcrumb(crumb);
+}
+/** Set the user on the active scope (the global scope outside a `withScope`). */
+export function setUser(user) {
+    getCurrentScope().setUser(user);
+}
+/** Set a single tag on the active scope. */
+export function setTag(key, value) {
+    getCurrentScope().setTag(key, value);
+}
+/** Merge several tags onto the active scope. */
+export function setTags(tags) {
+    getCurrentScope().setTags(tags);
+}
+/** Set a named free-form context block on the active scope. */
+export function setContext(key, context) {
+    getCurrentScope().setContext(key, context);
+}
+/** Set a single free-form extra value on the active scope. */
+export function setExtra(key, value) {
+    getCurrentScope().setExtra(key, value);
+}
+/** Flush buffered items immediately. Resolves once sent (or if not init). */
+export function flush() {
+    return activeClient ? activeClient.flush() : Promise.resolve();
+}
+/** Flush and stop the background timer, then clear the active client. */
+export async function close() {
+    if (!activeClient)
+        return;
+    const client = activeClient;
+    activeClient = null;
+    await client.close();
+}

package/dist/queue.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Bounded in-memory send buffer with opt-in disk persistence.
+ *
+ * Items accumulate here between flushes. The buffer is byte-capped: when a push
+ * would exceed `maxBytes`, the oldest items are dropped first (drop-oldest ring)
+ * so a stalled ingest can never grow memory without bound.
+ *
+ * When `offlineDir` is set, every queued item is also written to a FIFO file so
+ * that a crash mid-outage doesn't lose it: a fresh instance reloads the pending
+ * files on construction (at-least-once across restarts). Files are deleted only
+ * once their batch is committed (delivered or intentionally dropped). Disk
+ * persistence is off by default — servers shouldn't be forced into filesystem
+ * assumptions (ephemeral containers).
+ *
+ * The flush cycle is: `push` (many) → `drain` (take a batch, moving it "in
+ * flight") → `commit` (delivered/dropped: forget it, delete its files) or
+ * `restore` (send failed: put it back at the head, keep its files).
+ */
+import type { EnvelopeItem } from './types.js';
+export interface BoundedQueueOptions {
+    /** Drop-oldest byte cap for the in-memory buffer. */
+    maxBytes: number;
+    /** When set, persist pending items here (FIFO) for at-least-once across restarts. */
+    offlineDir?: string | null;
+}
+export declare class BoundedQueue {
+    private entries;
+    /** The batch currently handed to the transport, awaiting commit/restore. */
+    private inflight;
+    private byteCount;
+    private seq;
+    private readonly maxBytes;
+    private readonly offlineDir;
+    constructor(options: BoundedQueueOptions);
+    /** Reload persisted items (FIFO by filename) from a previous run. */
+    private reload;
+    /** Enqueue an item; persists it when offline, then enforces the byte cap. */
+    push(item: EnvelopeItem): void;
+    /** Drop oldest entries until the byte cap is satisfied. */
+    private evict;
+    /**
+     * Take up to `maxItems` queued entries, moving them "in flight". The
+     * transport must later {@link commit} them (delivered/dropped) or
+     * {@link restore} them (failed).
+     *
+     * The cap matters. Draining everything put the whole queue in one envelope,
+     * so a backlog accumulated during an outage could exceed the server's
+     * per-envelope item limit and be rejected outright — and a non-retryable
+     * rejection commits, deleting every persisted file the backlog was made of.
+     */
+    drain(maxItems?: number): EnvelopeItem[];
+    /** Entries still queued, excluding anything currently in flight. */
+    get pending(): number;
+    /** Delivered (or intentionally dropped): forget the in-flight batch and delete its files. */
+    commit(): void;
+    /** Send failed: return the in-flight batch to the head of the queue, keeping its files. */
+    restore(): void;
+    private tryUnlink;
+    /** Bytes currently buffered (excludes the in-flight batch). */
+    get bytes(): number;
+    /** Number of queued items (excludes the in-flight batch). */
+    get size(): number;
+}

package/dist/queue.js

@@ -0,0 +1,150 @@
+/**
+ * Bounded in-memory send buffer with opt-in disk persistence.
+ *
+ * Items accumulate here between flushes. The buffer is byte-capped: when a push
+ * would exceed `maxBytes`, the oldest items are dropped first (drop-oldest ring)
+ * so a stalled ingest can never grow memory without bound.
+ *
+ * When `offlineDir` is set, every queued item is also written to a FIFO file so
+ * that a crash mid-outage doesn't lose it: a fresh instance reloads the pending
+ * files on construction (at-least-once across restarts). Files are deleted only
+ * once their batch is committed (delivered or intentionally dropped). Disk
+ * persistence is off by default — servers shouldn't be forced into filesystem
+ * assumptions (ephemeral containers).
+ *
+ * The flush cycle is: `push` (many) → `drain` (take a batch, moving it "in
+ * flight") → `commit` (delivered/dropped: forget it, delete its files) or
+ * `restore` (send failed: put it back at the head, keep its files).
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const FILE_SUFFIX = '.env.json';
+function pad(seq) {
+    return String(seq).padStart(16, '0');
+}
+export class BoundedQueue {
+    entries = [];
+    /** The batch currently handed to the transport, awaiting commit/restore. */
+    inflight = [];
+    byteCount = 0;
+    seq = 0;
+    maxBytes;
+    offlineDir;
+    constructor(options) {
+        this.maxBytes = Math.max(0, options.maxBytes);
+        this.offlineDir = options.offlineDir ?? null;
+        if (this.offlineDir) {
+            mkdirSync(this.offlineDir, { recursive: true });
+            this.reload();
+        }
+    }
+    /** Reload persisted items (FIFO by filename) from a previous run. */
+    reload() {
+        const dir = this.offlineDir;
+        if (!dir || !existsSync(dir))
+            return;
+        const files = readdirSync(dir)
+            .filter((f) => f.endsWith(FILE_SUFFIX))
+            .sort();
+        for (const name of files) {
+            const full = join(dir, name);
+            try {
+                const raw = readFileSync(full, 'utf8');
+                const item = JSON.parse(raw);
+                this.entries.push({ item, size: Buffer.byteLength(raw), file: full });
+                this.byteCount += Buffer.byteLength(raw);
+            }
+            catch {
+                // Corrupt/partial file — drop it so it can't wedge the queue.
+                this.tryUnlink(full);
+            }
+            const seqPart = Number.parseInt(name, 10);
+            if (Number.isFinite(seqPart) && seqPart >= this.seq)
+                this.seq = seqPart + 1;
+        }
+        this.evict();
+    }
+    /** Enqueue an item; persists it when offline, then enforces the byte cap. */
+    push(item) {
+        const raw = JSON.stringify(item);
+        const size = Buffer.byteLength(raw);
+        let file = null;
+        if (this.offlineDir) {
+            file = join(this.offlineDir, `${pad(this.seq++)}${FILE_SUFFIX}`);
+            try {
+                writeFileSync(file, raw);
+            }
+            catch {
+                file = null; // best-effort persistence; never block the send path
+            }
+        }
+        this.entries.push({ item, size, file });
+        this.byteCount += size;
+        this.evict();
+    }
+    /** Drop oldest entries until the byte cap is satisfied. */
+    evict() {
+        while (this.byteCount > this.maxBytes && this.entries.length > 0) {
+            const dropped = this.entries.shift();
+            this.byteCount -= dropped.size;
+            if (dropped.file)
+                this.tryUnlink(dropped.file);
+        }
+    }
+    /**
+     * Take up to `maxItems` queued entries, moving them "in flight". The
+     * transport must later {@link commit} them (delivered/dropped) or
+     * {@link restore} them (failed).
+     *
+     * The cap matters. Draining everything put the whole queue in one envelope,
+     * so a backlog accumulated during an outage could exceed the server's
+     * per-envelope item limit and be rejected outright — and a non-retryable
+     * rejection commits, deleting every persisted file the backlog was made of.
+     */
+    drain(maxItems) {
+        const limit = maxItems && maxItems > 0 ? maxItems : this.entries.length;
+        const batch = this.entries.splice(0, limit);
+        this.byteCount = this.entries.reduce((n, e) => n + e.size, 0);
+        if (batch.length > 0)
+            this.inflight.push(...batch);
+        return batch.map((e) => e.item);
+    }
+    /** Entries still queued, excluding anything currently in flight. */
+    get pending() {
+        return this.entries.length;
+    }
+    /** Delivered (or intentionally dropped): forget the in-flight batch and delete its files. */
+    commit() {
+        for (const e of this.inflight) {
+            if (e.file)
+                this.tryUnlink(e.file);
+        }
+        this.inflight = [];
+    }
+    /** Send failed: return the in-flight batch to the head of the queue, keeping its files. */
+    restore() {
+        if (this.inflight.length === 0)
+            return;
+        this.entries = [...this.inflight, ...this.entries];
+        for (const e of this.inflight)
+            this.byteCount += e.size;
+        this.inflight = [];
+        this.evict();
+    }
+    tryUnlink(file) {
+        try {
+            unlinkSync(file);
+        }
+        catch {
+            // Already gone / never written — ignore.
+        }
+    }
+    /** Bytes currently buffered (excludes the in-flight batch). */
+    get bytes() {
+        return this.byteCount;
+    }
+    /** Number of queued items (excludes the in-flight batch). */
+    get size() {
+        return this.entries.length;
+    }
+}

package/dist/scope.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Scope — global process-wide defaults plus per-request/per-task isolation.
+ *
+ * A single global {@link Scope} holds process-wide user/tags/context/breadcrumbs.
+ * {@link withScope} (or {@link runWithAsyncScope}) layers an isolated child scope
+ * over the current one for the duration of a callback, backed by
+ * {@link AsyncLocalStorage} so concurrent requests never leak state into each
+ * other. Reads merge child-over-parent because a child is a *snapshot* of its
+ * parent taken at entry.
+ */
+import type { Breadcrumb, BreadcrumbInput, ErrorUser, ScopeData, User } from './types.js';
+/** Stamp a breadcrumb, defaulting missing fields; preserves an existing timestamp. */
+export declare function normalizeBreadcrumb(input: BreadcrumbInput | Breadcrumb): Breadcrumb;
+/** The mutable per-scope state and the operations over it. */
+export declare class Scope {
+    readonly data: ScopeData;
+    private maxBreadcrumbs;
+    constructor(maxBreadcrumbs?: number);
+    setUser(user: User | null): this;
+    setTag(key: string, value: string): this;
+    setTags(tags: Record<string, string>): this;
+    setContext(key: string, context: Record<string, unknown> | unknown): this;
+    setExtra(key: string, value: unknown): this;
+    addBreadcrumb(crumb: BreadcrumbInput | Breadcrumb): this;
+    setMaxBreadcrumbs(max: number): void;
+    /** A deep-enough snapshot; children never share mutable containers with parents. */
+    clone(): Scope;
+    /**
+     * Layer this scope onto an error item: fill breadcrumbs from the trail, merge
+     * scope tags *under* any per-call tags, and set the user only when the item
+     * has none (per-call values win).
+     */
+    applyToErrorItem(item: {
+        tags?: Record<string, string>;
+        contexts?: Record<string, unknown>;
+        extra?: Record<string, unknown>;
+        user?: ErrorUser | null;
+        breadcrumbs?: Breadcrumb[];
+    }): void;
+    /**
+     * Merge this scope's metadata *under* per-call overrides for non-error items
+     * (analytics `track`). tags & extra merge by shallow key; contexts merge by
+     * block name (a per-call block replaces the same-named scope block). Empty
+     * maps are omitted from the result per the emit convention.
+     */
+    mergeMetadata(overrides?: {
+        tags?: Record<string, string>;
+        contexts?: Record<string, unknown>;
+        extra?: Record<string, unknown>;
+    }): {
+        tags?: Record<string, string>;
+        contexts?: Record<string, unknown>;
+        extra?: Record<string, unknown>;
+    };
+}
+/** The process-wide scope holding defaults set at/after init. */
+export declare function getGlobalScope(): Scope;
+/** The scope in effect right now: the async-local child if inside a scoped block, else global. */
+export declare function getCurrentScope(): Scope;
+/**
+ * Run `cb` with an isolated child scope (a snapshot of the current one). The
+ * child is passed to `cb` and is what {@link getCurrentScope} returns for the
+ * duration — including across `await`s inside `cb`. Returns whatever `cb`
+ * returns (awaitable if `cb` is async).
+ */
+export declare function withScope<T>(cb: (scope: Scope) => T): T;
+/** Like {@link withScope}, but the callback takes no scope argument. */
+export declare function runWithAsyncScope<T>(cb: () => T): T;
+/** Mutate the active scope (the global scope outside any {@link withScope}). */
+export declare function configureScope(cb: (scope: Scope) => void): void;