@fixback/node 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fixback
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# @fixback/node
+
+The Fixback **backend error SDK** for Node servers. Capture unhandled crashes and
+manually-reported errors and file them into the same Fixback pipeline your frontend
+uses — one queue for your whole product (ADR-0026/0027/0028, spec #224).
+
+Backend errors authenticate with the Project **secret key**, so they arrive
+**Internal** tier and tagged `platform: node`. Fleet-wide crash-loops collapse into a
+single Issue with a rising occurrence count instead of flooding your queue.
+
+## Install
+
+```bash
+npm install @fixback/node
+```
+
+The Express and NestJS adapters are optional — install the framework you use.
+
+## Quick start
+
+Call `init` as early as possible in your process (before your app boots), so the
+process handlers are installed before anything can throw:
+
+```ts
+// instrument.ts — imported first in your entry file
+import { init } from "@fixback/node";
+
+init({
+  secretKey: process.env.FIXBACK_SECRET_KEY!, // sk_… (never your publishable key)
+  environment: process.env.NODE_ENV,          // "production" | "staging" | …
+  release: process.env.GIT_SHA,               // symbolicated against your uploaded sourcemaps
+  enabled: process.env.NODE_ENV === "production", // gate auto-capture off in local dev
+});
+```
+
+That single call wires:
+
+- a **batched** secret-key transport that backs off on `429` (honouring `Retry-After`);
+- process-level `uncaughtException` / `unhandledRejection` capture that **never changes
+  your process's exit behaviour**;
+- and the manual capture API below.
+
+### Manual capture
+
+```ts
+import { captureException, captureMessage } from "@fixback/node";
+
+try {
+  await risky();
+} catch (err) {
+  captureException(err);           // handled: true
+}
+
+captureMessage("cache miss storm", "warning");
+```
+
+### Express
+
+```ts
+import express from "express";
+import { fixbackRequestContext, fixbackErrorHandler } from "@fixback/node/express";
+
+const app = express();
+app.use(fixbackRequestContext()); // opens per-request context (before your routes)
+// … your routes …
+app.use(fixbackErrorHandler());   // captures errors that reach next(err) (after your routes)
+```
+
+### NestJS
+
+```ts
+import { Module } from "@nestjs/common";
+import { FixbackModule } from "@fixback/node/nestjs";
+
+@Module({ imports: [FixbackModule.forRoot()] })
+export class AppModule {}
+```
+
+`FixbackModule.forRoot()` registers the request-context middleware and a global
+exception filter that captures thrown request errors and re-throws them, so your own
+error handling is unchanged.
+
+### Attaching a user
+
+The SDK never scrapes user identity. Attach an **app-supplied** reference from inside a
+request and it rides along with any error captured during that request:
+
+```ts
+import { setUser } from "@fixback/node";
+
+setUser(currentUser.id); // an opaque ref you choose — not a name/email unless you send one
+```
+
+## Privacy
+
+Private-by-default. The SDK captures the route **pattern** (never the concrete path
+with values), method, status, a correlation id, and the app-supplied user ref only. It
+**never** sends request/response bodies, `Authorization`/`Cookie` headers, environment
+variables, or query-string values. A `beforeSend(event)` hook lets you redact further
+or drop an event entirely (return `null`).
+
+## Fails quiet
+
+If Fixback is unreachable or misconfigured, your server keeps running normally —
+observability never becomes an outage.

package/dist/client.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The `FixbackClient` and the module-level singleton API (`init`, `captureException`,
+ * `captureMessage`, `flush`, `close`) — the SDK's capture surface.
+ *
+ * A capture distils the error, fingerprints it with the **shared core**
+ * (`@fixback/sdk-core`, so the key matches the browser SDK — ADR-0028), attaches the
+ * in-flight request's {@link ServerContext} from AsyncLocalStorage, runs the scrub
+ * choke point and the project's `beforeSend`, then hands a {@link ServerErrorPayload}
+ * to the batched transport. Every step is wrapped so a capture **never throws into
+ * the host** (story 34): a misbehaving hook, an unserialisable error, or a transport
+ * hiccup is swallowed, and the server keeps running.
+ */
+import { type InitOptions, type ResolvedConfig } from "./config";
+import { type ProcessLike } from "./process";
+import { type CaptureTransport } from "./transport";
+import type { ServerContext, Severity } from "./wire";
+export type { BeforeSend, FixbackErrorEvent, ServerContext, Severity } from "./wire";
+export type { InitOptions } from "./config";
+export type { CaptureTransport } from "./transport";
+/** Optional per-capture context — override `handled` or add/override server context. */
+export interface CaptureContext {
+    /** Override the handled flag (defaults to `true` for a manual/caught capture). */
+    readonly handled?: boolean;
+    /** Server context to merge over what the request scope provides (e.g. a filter's status). */
+    readonly server?: ServerContext;
+}
+/** The minimal capture surface the framework adapters file through (satisfied by {@link FixbackClient}). */
+export interface CaptureClient {
+    captureException(error: unknown, context?: CaptureContext): void;
+}
+/** Advanced/testing seam: supply a custom {@link CaptureTransport} or process. */
+export interface ClientDeps {
+    readonly transport?: CaptureTransport;
+    /** The process to attach handlers to (defaults to the real `process`). */
+    readonly process?: ProcessLike;
+    /** Override Node's default fatal behaviour after a sole-listener uncaught exception. */
+    readonly onFatalError?: (error: unknown) => void;
+}
+export declare class FixbackClient {
+    private readonly config;
+    private readonly transport;
+    constructor(config: ResolvedConfig, deps?: ClientDeps);
+    /** Whether this client will capture (its secret key resolved and the gate is on). */
+    get enabled(): boolean;
+    /** The header the request-context middleware reads a correlation id from. */
+    get requestIdHeader(): string;
+    /**
+     * Report a caught or manually-observed error. `handled` defaults to `true`; the
+     * process handlers pass `handled: false` for an uncaught crash.
+     */
+    captureException(error: unknown, context?: CaptureContext): void;
+    /** Report a noteworthy non-error condition, grouped by its message text. */
+    captureMessage(message: string, level?: Severity, context?: CaptureContext): void;
+    /** Flush the transport's buffer now. Resolves even when the SDK is disabled. */
+    flush(): Promise<void>;
+    /** Stop the transport (its timer) and drain what remains. */
+    close(): Promise<void>;
+    /** Assemble, scrub, run `beforeSend`, and enqueue — swallowing any failure. */
+    private dispatch;
+    /** Run the project hook after the default scrubbers; a throwing hook is a no-op. */
+    private runBeforeSend;
+}
+/**
+ * Initialise the SDK: resolve the config, replace any previous client (closing it and
+ * removing its process handlers), install the polite process handlers, and return the
+ * active {@link FixbackClient}. Fail-quiet — a missing secret key yields an inert
+ * client (no handlers, no transport) rather than throwing.
+ */
+export declare function init(options: InitOptions, deps?: ClientDeps): FixbackClient;
+/** The active client set by {@link init}, or `null` before the first `init`. */
+export declare function getClient(): FixbackClient | null;
+/** Report a caught/manual error through the active client (no-op before `init`). */
+export declare function captureException(error: unknown, context?: CaptureContext): void;
+/** Report a message through the active client (no-op before `init`). */
+export declare function captureMessage(message: string, level?: Severity, context?: CaptureContext): void;
+/** Flush the active client's buffer (no-op before `init`). */
+export declare function flush(): Promise<void>;
+/** Close and clear the active client, removing its process handlers (no-op before `init`). */
+export declare function close(): Promise<void>;

package/dist/client.js

@@ -0,0 +1,220 @@
+"use strict";
+/**
+ * The `FixbackClient` and the module-level singleton API (`init`, `captureException`,
+ * `captureMessage`, `flush`, `close`) — the SDK's capture surface.
+ *
+ * A capture distils the error, fingerprints it with the **shared core**
+ * (`@fixback/sdk-core`, so the key matches the browser SDK — ADR-0028), attaches the
+ * in-flight request's {@link ServerContext} from AsyncLocalStorage, runs the scrub
+ * choke point and the project's `beforeSend`, then hands a {@link ServerErrorPayload}
+ * to the batched transport. Every step is wrapped so a capture **never throws into
+ * the host** (story 34): a misbehaving hook, an unserialisable error, or a transport
+ * hiccup is swallowed, and the server keeps running.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FixbackClient = void 0;
+exports.init = init;
+exports.getClient = getClient;
+exports.captureException = captureException;
+exports.captureMessage = captureMessage;
+exports.flush = flush;
+exports.close = close;
+const sdk_core_1 = require("@fixback/sdk-core");
+const config_1 = require("./config");
+const context_1 = require("./context");
+const process_1 = require("./process");
+const stack_1 = require("./stack");
+const transport_1 = require("./transport");
+/** Merge two server contexts, the override winning; `undefined` when both are empty. */
+function mergeServerContext(base, override) {
+    if (!base && !override)
+        return undefined;
+    const merged = { ...(base ?? {}), ...(override ?? {}) };
+    for (const key of Object.keys(merged)) {
+        if (merged[key] === undefined)
+            delete merged[key];
+    }
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+class FixbackClient {
+    config;
+    transport;
+    constructor(config, deps = {}) {
+        this.config = config;
+        this.transport =
+            deps.transport ??
+                (config.enabled
+                    ? new transport_1.Transport({
+                        endpoint: config.errorsEndpoint,
+                        secretKey: config.secretKey,
+                        maxBatchSize: config.maxBatchSize,
+                        maxQueueSize: config.maxQueueSize,
+                        flushIntervalMs: config.flushIntervalMs,
+                        timeoutMs: config.timeoutMs,
+                    })
+                    : null);
+    }
+    /** Whether this client will capture (its secret key resolved and the gate is on). */
+    get enabled() {
+        return this.config.enabled;
+    }
+    /** The header the request-context middleware reads a correlation id from. */
+    get requestIdHeader() {
+        return this.config.requestIdHeader;
+    }
+    /**
+     * Report a caught or manually-observed error. `handled` defaults to `true`; the
+     * process handlers pass `handled: false` for an uncaught crash.
+     */
+    captureException(error, context = {}) {
+        const { type, value, stack } = (0, stack_1.extractError)(error);
+        const frames = (0, stack_1.extractStructuredFrames)(stack);
+        this.dispatch({
+            errorSignature: (0, sdk_core_1.computeFingerprint)(type, value, stack),
+            type,
+            value,
+            handled: context.handled ?? true,
+            errorFrames: frames.length > 0 ? frames : undefined,
+        }, context);
+    }
+    /** Report a noteworthy non-error condition, grouped by its message text. */
+    captureMessage(message, level = "info", context = {}) {
+        const value = typeof message === "string" ? message : String(message);
+        this.dispatch({
+            errorSignature: (0, sdk_core_1.computeFingerprint)("Message", value),
+            type: "Message",
+            value,
+            level,
+            handled: context.handled ?? true,
+        }, context);
+    }
+    /** Flush the transport's buffer now. Resolves even when the SDK is disabled. */
+    flush() {
+        return this.transport?.flush() ?? Promise.resolve();
+    }
+    /** Stop the transport (its timer) and drain what remains. */
+    close() {
+        return this.transport?.close() ?? Promise.resolve();
+    }
+    /** Assemble, scrub, run `beforeSend`, and enqueue — swallowing any failure. */
+    dispatch(partial, context) {
+        if (!this.config.enabled || !this.transport)
+            return;
+        try {
+            const event = {
+                errorSignature: partial.errorSignature,
+                type: partial.type,
+                value: partial.value,
+                handled: partial.handled,
+                level: partial.level,
+                environment: this.config.environment,
+                release: this.config.release,
+                errorFrames: partial.errorFrames,
+                server: mergeServerContext((0, context_1.currentServerContext)(), context.server),
+            };
+            if (this.config.scrub)
+                applyDefaultScrub(event);
+            const finalised = this.runBeforeSend(event);
+            if (!finalised)
+                return; // dropped at the choke point — no transport
+            this.transport.enqueue(toPayload(finalised));
+        }
+        catch {
+            // Capture must never throw into the host (story 34).
+        }
+    }
+    /** Run the project hook after the default scrubbers; a throwing hook is a no-op. */
+    runBeforeSend(event) {
+        const hook = this.config.beforeSend;
+        if (!hook)
+            return event;
+        try {
+            return hook(event) ?? null;
+        }
+        catch {
+            return event; // a buggy hook never breaks the report path nor leaks unscrubbed data
+        }
+    }
+}
+exports.FixbackClient = FixbackClient;
+/** The built-in default scrub: re-sweep frame URLs through the shared-core scrubber. */
+function applyDefaultScrub(event) {
+    if (event.errorFrames && event.errorFrames.length > 0) {
+        event.errorFrames = event.errorFrames.map((frame) => ({
+            ...frame,
+            file: (0, sdk_core_1.scrubUrl)(frame.file),
+        }));
+    }
+}
+/** Project the event onto the wire payload, dropping the event-only fields. */
+function toPayload(event) {
+    const payload = { errorSignature: event.errorSignature };
+    if (event.handled !== undefined)
+        payload.handled = event.handled;
+    if (event.environment !== undefined)
+        payload.environment = event.environment;
+    if (event.release !== undefined)
+        payload.release = event.release;
+    if (event.occurrences !== undefined)
+        payload.occurrences = event.occurrences;
+    if (event.errorFrames && event.errorFrames.length > 0)
+        payload.errorFrames = event.errorFrames;
+    if (event.server)
+        payload.server = event.server;
+    return payload;
+}
+// --- Module-level singleton API ----------------------------------------------
+let activeClient = null;
+let activeUninstall = null;
+/**
+ * Initialise the SDK: resolve the config, replace any previous client (closing it and
+ * removing its process handlers), install the polite process handlers, and return the
+ * active {@link FixbackClient}. Fail-quiet — a missing secret key yields an inert
+ * client (no handlers, no transport) rather than throwing.
+ */
+function init(options, deps) {
+    const previousClient = activeClient;
+    const previousUninstall = activeUninstall;
+    if (previousUninstall)
+        previousUninstall();
+    if (previousClient)
+        void previousClient.close();
+    const config = (0, config_1.resolveConfig)(options);
+    const client = new FixbackClient(config, deps);
+    activeClient = client;
+    activeUninstall =
+        config.enabled && (config.captureUncaughtException || config.captureUnhandledRejection)
+            ? (0, process_1.installProcessHandlers)(client, {
+                captureUncaughtException: config.captureUncaughtException,
+                captureUnhandledRejection: config.captureUnhandledRejection,
+            }, { process: deps?.process, onFatalError: deps?.onFatalError })
+            : null;
+    return client;
+}
+/** The active client set by {@link init}, or `null` before the first `init`. */
+function getClient() {
+    return activeClient;
+}
+/** Report a caught/manual error through the active client (no-op before `init`). */
+function captureException(error, context) {
+    activeClient?.captureException(error, context);
+}
+/** Report a message through the active client (no-op before `init`). */
+function captureMessage(message, level, context) {
+    activeClient?.captureMessage(message, level, context);
+}
+/** Flush the active client's buffer (no-op before `init`). */
+function flush() {
+    return activeClient?.flush() ?? Promise.resolve();
+}
+/** Close and clear the active client, removing its process handlers (no-op before `init`). */
+function close() {
+    const current = activeClient;
+    const uninstall = activeUninstall;
+    activeClient = null;
+    activeUninstall = null;
+    if (uninstall)
+        uninstall();
+    return current?.close() ?? Promise.resolve();
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The `init` options and their resolution into a validated {@link ResolvedConfig}.
+ *
+ * Resolution is **fail-quiet** (spec #224, story 34): it never throws. A missing
+ * secret key or an explicit `enabled: false` leaves the SDK inert (`enabled: false`)
+ * rather than raising — a Fixback misconfiguration must never break the host server.
+ * Numeric knobs are clamped to safe bounds (the batch to the server's 500-item cap)
+ * instead of rejected.
+ */
+import type { BeforeSend } from "./wire";
+/** The default Fixback ingest origin, shared with the browser and Expo SDKs. */
+export declare const DEFAULT_API_URL = "https://api.fixback.dev";
+/** Options for {@link init} — the one call that wires backend capture. */
+export interface InitOptions {
+    /**
+     * The Project **secret key** (`sk_…`) the backend authenticates with — the same
+     * key `npx fixback sourcemaps upload` uses (never the publishable key). Without it
+     * the SDK stays inert.
+     */
+    readonly secretKey: string;
+    /** The Fixback ingest origin. Defaults to {@link DEFAULT_API_URL}. */
+    readonly apiUrl?: string;
+    /** The deploy environment (`production` / `staging` / …) stamped on every error. */
+    readonly environment?: string;
+    /** The build **Release** the captured stacks symbolicate against. */
+    readonly release?: string;
+    /** A hook to redact or drop an event before it leaves the process (return `null` to drop). */
+    readonly beforeSend?: BeforeSend;
+    /** Run the built-in default scrubbers before `beforeSend`. Defaults to `true`. */
+    readonly scrub?: boolean;
+    /** Master gate — set `false` to disable all capture (e.g. in local dev). Defaults to `true`. */
+    readonly enabled?: boolean;
+    /** Install the polite `uncaughtException` handler. Defaults to `true`. */
+    readonly captureUncaughtException?: boolean;
+    /** Install the polite `unhandledRejection` handler. Defaults to `true`. */
+    readonly captureUnhandledRejection?: boolean;
+    /** Flush the buffer once it reaches this many errors. Defaults to `100`; capped at `500`. */
+    readonly maxBatchSize?: number;
+    /** Flush a non-empty buffer at least this often, in ms. Defaults to `5000`. */
+    readonly flushIntervalMs?: number;
+    /** Cap the in-memory buffer so a flood can't grow it without bound. Defaults to `1024`. */
+    readonly maxQueueSize?: number;
+    /** Overall per-request transport timeout in ms; `0` disables. Defaults to `30000`. */
+    readonly timeoutMs?: number;
+    /** The header a correlation id is read from. Defaults to `x-request-id`. */
+    readonly requestIdHeader?: string;
+}
+/** The validated, defaulted configuration a {@link FixbackClient} runs on. */
+export interface ResolvedConfig {
+    readonly enabled: boolean;
+    readonly secretKey: string;
+    readonly apiUrl: string;
+    readonly errorsEndpoint: string;
+    readonly environment?: string;
+    readonly release?: string;
+    readonly beforeSend?: BeforeSend;
+    readonly scrub: boolean;
+    readonly captureUncaughtException: boolean;
+    readonly captureUnhandledRejection: boolean;
+    readonly maxBatchSize: number;
+    readonly flushIntervalMs: number;
+    readonly maxQueueSize: number;
+    readonly timeoutMs: number;
+    readonly requestIdHeader: string;
+}
+/**
+ * Resolve raw {@link InitOptions} into a validated {@link ResolvedConfig}. Never
+ * throws: without a usable secret key (or with `enabled: false`) the result is
+ * inert (`enabled: false`), so an inert client can no-op every capture.
+ */
+export declare function resolveConfig(options: InitOptions): ResolvedConfig;

package/dist/config.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * The `init` options and their resolution into a validated {@link ResolvedConfig}.
+ *
+ * Resolution is **fail-quiet** (spec #224, story 34): it never throws. A missing
+ * secret key or an explicit `enabled: false` leaves the SDK inert (`enabled: false`)
+ * rather than raising — a Fixback misconfiguration must never break the host server.
+ * Numeric knobs are clamped to safe bounds (the batch to the server's 500-item cap)
+ * instead of rejected.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_API_URL = void 0;
+exports.resolveConfig = resolveConfig;
+/** The default Fixback ingest origin, shared with the browser and Expo SDKs. */
+exports.DEFAULT_API_URL = "https://api.fixback.dev";
+/** The largest batch the server-error endpoint accepts (`MAX_SERVER_ERROR_BATCH`). */
+const SERVER_MAX_BATCH = 500;
+const DEFAULT_MAX_BATCH_SIZE = 100;
+const DEFAULT_FLUSH_INTERVAL_MS = 5_000;
+const DEFAULT_MAX_QUEUE_SIZE = 1_024;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_REQUEST_ID_HEADER = "x-request-id";
+/** Trim a string option, returning `undefined` for a blank or non-string value. */
+function trimmed(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const out = value.trim();
+    return out.length > 0 ? out : undefined;
+}
+/** Normalise an api base URL: trim and strip trailing slashes. */
+function normalizeApiUrl(value) {
+    const base = trimmed(value) ?? exports.DEFAULT_API_URL;
+    return base.replace(/\/+$/, "") || exports.DEFAULT_API_URL;
+}
+/** Clamp a positive-integer option to `[min, max]`, falling back to `fallback`. */
+function clampInt(value, fallback, min, max) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return fallback;
+    return Math.min(max, Math.max(min, Math.floor(value)));
+}
+/**
+ * Resolve raw {@link InitOptions} into a validated {@link ResolvedConfig}. Never
+ * throws: without a usable secret key (or with `enabled: false`) the result is
+ * inert (`enabled: false`), so an inert client can no-op every capture.
+ */
+function resolveConfig(options) {
+    const secretKey = trimmed(options.secretKey) ?? "";
+    const apiUrl = normalizeApiUrl(options.apiUrl);
+    const enabled = options.enabled !== false && secretKey.length > 0;
+    return {
+        enabled,
+        secretKey,
+        apiUrl,
+        errorsEndpoint: `${apiUrl}/api/errors`,
+        environment: trimmed(options.environment),
+        release: trimmed(options.release),
+        beforeSend: typeof options.beforeSend === "function" ? options.beforeSend : undefined,
+        scrub: options.scrub !== false,
+        captureUncaughtException: options.captureUncaughtException !== false,
+        captureUnhandledRejection: options.captureUnhandledRejection !== false,
+        maxBatchSize: clampInt(options.maxBatchSize, DEFAULT_MAX_BATCH_SIZE, 1, SERVER_MAX_BATCH),
+        flushIntervalMs: clampInt(options.flushIntervalMs, DEFAULT_FLUSH_INTERVAL_MS, 0, Number.MAX_SAFE_INTEGER),
+        maxQueueSize: clampInt(options.maxQueueSize, DEFAULT_MAX_QUEUE_SIZE, 1, Number.MAX_SAFE_INTEGER),
+        timeoutMs: clampInt(options.timeoutMs, DEFAULT_TIMEOUT_MS, 0, Number.MAX_SAFE_INTEGER),
+        requestIdHeader: (trimmed(options.requestIdHeader) ?? DEFAULT_REQUEST_ID_HEADER).toLowerCase(),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/context.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Per-request correlation via Node **AsyncLocalStorage** (spec §D9, ADR-0025) — so a
+ * captured error carries the in-flight request's context without the developer
+ * threading a context object through every call.
+ *
+ * The request-context middleware opens a store holding the request/response refs and
+ * a correlation id; the transport reads {@link currentServerContext} at capture time,
+ * so the route pattern and status are read *late* (once the router has matched and the
+ * status is set), not at request start. `setRequestUser` lets the app attach its own
+ * user ref — the SDK never scrapes identity from the request itself.
+ */
+import { type HttpRequestLike, type HttpResponseLike, type NextFunction } from "./http";
+import type { ServerContext } from "./wire";
+/** What the ALS store carries for one in-flight request. */
+export interface RequestStore {
+    readonly req: HttpRequestLike;
+    readonly res?: HttpResponseLike;
+    /** The correlation id (inbound header when present, else generated). */
+    readonly requestId?: string;
+    /** The app-supplied user ref, written by {@link setRequestUser}. Never scraped. */
+    user?: string;
+}
+/** The active request store, or `undefined` outside a request scope. */
+export declare function getRequestStore(): RequestStore | undefined;
+/** Run `fn` (and everything it awaits) with `store` as the active request store. */
+export declare function runWithRequestStore<T>(store: RequestStore, fn: () => T): T;
+/**
+ * Attach an **app-supplied** user reference to the current request, so any error
+ * captured during it carries the user. A no-op outside a request scope (never
+ * throws). The SDK never derives identity from the request — only what you pass here.
+ */
+export declare function setRequestUser(user: string): void;
+/**
+ * Derive the private-by-default {@link ServerContext} from a request store: the HTTP
+ * method, the route **pattern**, the resolved status, the correlation id, and the
+ * app-supplied user ref. Returns `undefined` when there is no store or nothing
+ * resolvable — never the concrete path, a body, a header, or a query value.
+ */
+export declare function deriveServerContext(store: RequestStore | undefined): ServerContext | undefined;
+/** The {@link ServerContext} for the active request, or `undefined` outside one. */
+export declare function currentServerContext(): ServerContext | undefined;
+/** Options for {@link createRequestContextMiddleware}. */
+export interface RequestContextOptions {
+    /** The header a correlation id is read from. Defaults to `x-request-id`. */
+    readonly requestIdHeader?: string;
+}
+/**
+ * Build the Express-style request-context middleware: it opens an ALS store for the
+ * request (adopting an inbound correlation id, or minting one) and runs the rest of
+ * the request within it. Shared by the Express adapter and the NestJS module so both
+ * frameworks get per-request correlation the same way.
+ */
+export declare function createRequestContextMiddleware(options?: RequestContextOptions): (req: HttpRequestLike, res: HttpResponseLike, next: NextFunction) => void;