@fixback/node 0.2.0

package/dist/context.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRequestStore = getRequestStore;
+exports.runWithRequestStore = runWithRequestStore;
+exports.setRequestUser = setRequestUser;
+exports.deriveServerContext = deriveServerContext;
+exports.currentServerContext = currentServerContext;
+exports.createRequestContextMiddleware = createRequestContextMiddleware;
+const node_async_hooks_1 = require("node:async_hooks");
+const node_crypto_1 = require("node:crypto");
+const http_1 = require("./http");
+const storage = new node_async_hooks_1.AsyncLocalStorage();
+/** The active request store, or `undefined` outside a request scope. */
+function getRequestStore() {
+    return storage.getStore();
+}
+/** Run `fn` (and everything it awaits) with `store` as the active request store. */
+function runWithRequestStore(store, fn) {
+    return storage.run(store, fn);
+}
+/**
+ * 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.
+ */
+function setRequestUser(user) {
+    const store = storage.getStore();
+    if (store && typeof user === "string" && user.length > 0)
+        store.user = user;
+}
+/**
+ * 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.
+ */
+function deriveServerContext(store) {
+    if (!store)
+        return undefined;
+    const ctx = {};
+    const method = store.req.method;
+    if (typeof method === "string" && method.length > 0)
+        ctx.method = method;
+    const route = (0, http_1.routePatternOf)(store.req);
+    if (route)
+        ctx.route = route;
+    const status = store.res?.statusCode;
+    if (typeof status === "number" && status > 0)
+        ctx.statusCode = status;
+    if (store.requestId)
+        ctx.requestId = store.requestId;
+    if (store.user)
+        ctx.user = store.user;
+    return Object.keys(ctx).length > 0 ? ctx : undefined;
+}
+/** The {@link ServerContext} for the active request, or `undefined` outside one. */
+function currentServerContext() {
+    return deriveServerContext(storage.getStore());
+}
+/** Read a correlation id from the configured header, taking the first if repeated. */
+function readRequestId(req, header) {
+    const raw = req.headers?.[header];
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+/**
+ * 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.
+ */
+function createRequestContextMiddleware(options = {}) {
+    const header = (options.requestIdHeader ?? "x-request-id").toLowerCase();
+    return function fixbackRequestContext(req, res, next) {
+        const store = {
+            req,
+            res,
+            requestId: readRequestId(req, header) ?? (0, node_crypto_1.randomUUID)(),
+        };
+        runWithRequestStore(store, () => next());
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;AAqBH,0CAEC;AAGD,kDAEC;AAOD,wCAGC;AAQD,kDAuBC;AAGD,oDAEC;AAuBD,wEAgBC;AA/GD,uDAAqD;AACrD,6CAAyC;AAEzC,iCAAwG;AAaxG,MAAM,OAAO,GAAG,IAAI,oCAAiB,EAAgB,CAAC;AAEtD,wEAAwE;AACxE,SAAgB,eAAe;IAC7B,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;AAC5B,CAAC;AAED,oFAAoF;AACpF,SAAgB,mBAAmB,CAAI,KAAmB,EAAE,EAAW;IACrE,OAAO,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AAChC,CAAC;AAED;;;;GAIG;AACH,SAAgB,cAAc,CAAC,IAAY;IACzC,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IACjC,IAAI,KAAK,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;AAC9E,CAAC;AAED;;;;;GAKG;AACH,SAAgB,mBAAmB,CAAC,KAA+B;IACjE,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,MAAM,GAAG,GAML,EAAE,CAAC;IAEP,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC;IAChC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC;IAEzE,MAAM,KAAK,GAAG,IAAA,qBAAc,EAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACxC,IAAI,KAAK;QAAE,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC;IAE7B,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,EAAE,UAAU,CAAC;IACrC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,GAAG,CAAC;QAAE,GAAG,CAAC,UAAU,GAAG,MAAM,CAAC;IAEtE,IAAI,KAAK,CAAC,SAAS;QAAE,GAAG,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;IACrD,IAAI,KAAK,CAAC,IAAI;QAAE,GAAG,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;IAEtC,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC;AAED,oFAAoF;AACpF,SAAgB,oBAAoB;IAClC,OAAO,mBAAmB,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;AACjD,CAAC;AAED,sFAAsF;AACtF,SAAS,aAAa,CAAC,GAAoB,EAAE,MAAc;IACzD,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC;IAClC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAChD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AAClD,CAAC;AAQD;;;;;GAKG;AACH,SAAgB,8BAA8B,CAC5C,UAAiC,EAAE;IAEnC,MAAM,MAAM,GAAG,CAAC,OAAO,CAAC,eAAe,IAAI,cAAc,CAAC,CAAC,WAAW,EAAE,CAAC;IACzE,OAAO,SAAS,qBAAqB,CACnC,GAAoB,EACpB,GAAqB,EACrB,IAAkB;QAElB,MAAM,KAAK,GAAiB;YAC1B,GAAG;YACH,GAAG;YACH,SAAS,EAAE,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,IAAA,wBAAU,GAAE;SACtD,CAAC;QACF,mBAAmB,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;IAC3C,CAAC,CAAC;AACJ,CAAC"}

package/dist/express.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The **Express** adapter (`@fixback/node/express`, story 3) — two middlewares:
+ *
+ * - {@link fixbackRequestContext}: mount **before** your routes. It opens the
+ *   per-request AsyncLocalStorage scope (correlation id + request/response refs) so a
+ *   captured error carries the request without manual threading.
+ * - {@link fixbackErrorHandler}: mount **after** your routes (Express recognises a
+ *   4-arg middleware as an error handler). It captures an error that reaches
+ *   `next(err)` with the request's server context (`handled: true`), then **calls
+ *   `next(err)`** so your own error handling still runs — Fixback never swallows the
+ *   error and never breaks the request.
+ *
+ * Uses only structural request/response types, so the SDK needs no `express`
+ * dependency; the real Express objects satisfy them.
+ */
+import { type CaptureClient } from "./client";
+import { type HttpRequestLike, type HttpResponseLike, type NextFunction } from "./http";
+/** An Express request-processing middleware (`(req, res, next)`). */
+export type ExpressMiddleware = (req: HttpRequestLike, res: HttpResponseLike, next: NextFunction) => void;
+/** An Express error-handling middleware (`(err, req, res, next)`). */
+export type ExpressErrorMiddleware = (error: unknown, req: HttpRequestLike, res: HttpResponseLike, next: NextFunction) => void;
+/** Options for {@link fixbackRequestContext}. */
+export interface RequestContextOptions {
+    /** The header a correlation id is read from. Defaults to the client's config, then `x-request-id`. */
+    readonly requestIdHeader?: string;
+}
+/** Options for {@link fixbackErrorHandler}. */
+export interface ErrorHandlerOptions {
+    /** The client to file through. Defaults to the active module client (`init`). */
+    readonly client?: CaptureClient;
+}
+/**
+ * Build the request-context middleware. Mount it before your routes:
+ * `app.use(fixbackRequestContext())`.
+ */
+export declare function fixbackRequestContext(options?: RequestContextOptions): ExpressMiddleware;
+/**
+ * Build the error-handling middleware. Mount it after your routes:
+ * `app.use(fixbackErrorHandler())`. Captures the error (with the request's server
+ * context, `handled: true`) and always forwards it via `next(err)`.
+ */
+export declare function fixbackErrorHandler(options?: ErrorHandlerOptions): ExpressErrorMiddleware;

package/dist/express.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * The **Express** adapter (`@fixback/node/express`, story 3) — two middlewares:
+ *
+ * - {@link fixbackRequestContext}: mount **before** your routes. It opens the
+ *   per-request AsyncLocalStorage scope (correlation id + request/response refs) so a
+ *   captured error carries the request without manual threading.
+ * - {@link fixbackErrorHandler}: mount **after** your routes (Express recognises a
+ *   4-arg middleware as an error handler). It captures an error that reaches
+ *   `next(err)` with the request's server context (`handled: true`), then **calls
+ *   `next(err)`** so your own error handling still runs — Fixback never swallows the
+ *   error and never breaks the request.
+ *
+ * Uses only structural request/response types, so the SDK needs no `express`
+ * dependency; the real Express objects satisfy them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fixbackRequestContext = fixbackRequestContext;
+exports.fixbackErrorHandler = fixbackErrorHandler;
+const client_1 = require("./client");
+const context_1 = require("./context");
+const http_1 = require("./http");
+/**
+ * Build the request-context middleware. Mount it before your routes:
+ * `app.use(fixbackRequestContext())`.
+ */
+function fixbackRequestContext(options = {}) {
+    const header = options.requestIdHeader ?? (0, client_1.getClient)()?.requestIdHeader;
+    return (0, context_1.createRequestContextMiddleware)(header ? { requestIdHeader: header } : {});
+}
+/**
+ * Build the error-handling middleware. Mount it after your routes:
+ * `app.use(fixbackErrorHandler())`. Captures the error (with the request's server
+ * context, `handled: true`) and always forwards it via `next(err)`.
+ */
+function fixbackErrorHandler(options = {}) {
+    const client = options.client ?? {
+        captureException: (error, context) => (0, client_1.captureException)(error, context),
+    };
+    return function fixbackErrorHandlerMiddleware(error, req, res, next) {
+        try {
+            const server = { ...(0, http_1.serverContextFromRequest)(req), statusCode: (0, http_1.errorStatus)(error, res) };
+            client.captureException(error, { handled: true, server });
+        }
+        catch {
+            // Capture must never break the request pipeline — always forward the error.
+        }
+        next(error);
+    };
+}
+//# sourceMappingURL=express.js.map

package/dist/express.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.js","sourceRoot":"","sources":["../src/express.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;AA+CH,sDAGC;AAOD,kDAaC;AApED,qCAIkB;AAClB,uCAA2D;AAC3D,iCAMgB;AA6BhB;;;GAGG;AACH,SAAgB,qBAAqB,CAAC,UAAiC,EAAE;IACvE,MAAM,MAAM,GAAG,OAAO,CAAC,eAAe,IAAI,IAAA,kBAAS,GAAE,EAAE,eAAe,CAAC;IACvE,OAAO,IAAA,wCAA8B,EAAC,MAAM,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AACnF,CAAC;AAED;;;;GAIG;AACH,SAAgB,mBAAmB,CAAC,UAA+B,EAAE;IACnE,MAAM,MAAM,GAAkB,OAAO,CAAC,MAAM,IAAI;QAC9C,gBAAgB,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,IAAA,yBAAsB,EAAC,KAAK,EAAE,OAAO,CAAC;KAC7E,CAAC;IACF,OAAO,SAAS,6BAA6B,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI;QACjE,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,EAAE,GAAG,IAAA,+BAAwB,EAAC,GAAG,CAAC,EAAE,UAAU,EAAE,IAAA,kBAAW,EAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC;YACzF,MAAM,CAAC,gBAAgB,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QAC5D,CAAC;QAAC,MAAM,CAAC;YACP,4EAA4E;QAC9E,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,CAAC;IACd,CAAC,CAAC;AACJ,CAAC"}

package/dist/http.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Minimal **structural** types for the HTTP surface the adapters touch, plus
+ * {@link routePatternOf}.
+ *
+ * Described structurally (the same posture as `packages/expo/src/http.ts`) so the
+ * SDK needs no `@types/express` dependency: Express and NestJS (on Express) both pass
+ * requests/responses that satisfy these shapes, and tests pass plain objects. Only
+ * the private-by-default fields are read here — never bodies, headers beyond the
+ * correlation id, query values, or env.
+ */
+/** The request slice the adapters read — never its body, headers (bar the id), or query. */
+export interface HttpRequestLike {
+    readonly method?: string;
+    readonly baseUrl?: string;
+    readonly path?: string;
+    /** Populated by the router once a route matches — its `path` is the **pattern**. */
+    readonly route?: {
+        readonly path?: string | RegExp;
+    } | undefined;
+    readonly headers?: Readonly<Record<string, string | string[] | undefined>>;
+}
+/** The response slice the adapters read — only the resolved status. */
+export interface HttpResponseLike {
+    readonly statusCode?: number;
+}
+/** The Express/Nest `next` callback — `next(err)` forwards to the error pipeline. */
+export type NextFunction = (err?: unknown) => void;
+/**
+ * The route **pattern** for a request (`/api/users/:id`), joining a mounted router's
+ * `baseUrl` with the matched `route.path`. Returns `undefined` when no route has
+ * matched — deliberately **never** falling back to the concrete `path`, which would
+ * leak the in-URL values the PII boundary forbids (spec §D12).
+ */
+export declare function routePatternOf(req: HttpRequestLike): string | undefined;
+/**
+ * The private-by-default server-context fields derivable from a request alone — the
+ * HTTP method and the route **pattern**. The single place that decides what an adapter
+ * reads off a request (never a body, header, query value, or the concrete path), so the
+ * Express and NestJS adapters can never drift on the privacy posture. The status is
+ * added by the caller (it differs: an Express error's own status vs a Nest
+ * `HttpException`'s).
+ */
+export declare function serverContextFromRequest(req: HttpRequestLike): {
+    method?: string;
+    route?: string;
+};
+/** Read an http-errors-style numeric status off a thrown value (`err.status`/`.statusCode`). */
+export declare function numericStatus(error: unknown): number | undefined;
+/**
+ * A sensible status for a captured request error: the error's own status when set,
+ * else a 4xx/5xx already on the response, else `500`.
+ */
+export declare function errorStatus(error: unknown, res: HttpResponseLike): number;

package/dist/http.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * Minimal **structural** types for the HTTP surface the adapters touch, plus
+ * {@link routePatternOf}.
+ *
+ * Described structurally (the same posture as `packages/expo/src/http.ts`) so the
+ * SDK needs no `@types/express` dependency: Express and NestJS (on Express) both pass
+ * requests/responses that satisfy these shapes, and tests pass plain objects. Only
+ * the private-by-default fields are read here — never bodies, headers beyond the
+ * correlation id, query values, or env.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.routePatternOf = routePatternOf;
+exports.serverContextFromRequest = serverContextFromRequest;
+exports.numericStatus = numericStatus;
+exports.errorStatus = errorStatus;
+/**
+ * The route **pattern** for a request (`/api/users/:id`), joining a mounted router's
+ * `baseUrl` with the matched `route.path`. Returns `undefined` when no route has
+ * matched — deliberately **never** falling back to the concrete `path`, which would
+ * leak the in-URL values the PII boundary forbids (spec §D12).
+ */
+function routePatternOf(req) {
+    const routePath = req.route?.path;
+    if (routePath === undefined || routePath === null)
+        return undefined;
+    const pattern = typeof routePath === "string" ? routePath : (routePath.source ?? String(routePath));
+    const base = typeof req.baseUrl === "string" ? req.baseUrl : "";
+    if (pattern.length === 0)
+        return base.length > 0 ? base : undefined;
+    if (base.length === 0)
+        return pattern;
+    return `${base}${pattern.startsWith("/") ? pattern : `/${pattern}`}`;
+}
+/**
+ * The private-by-default server-context fields derivable from a request alone — the
+ * HTTP method and the route **pattern**. The single place that decides what an adapter
+ * reads off a request (never a body, header, query value, or the concrete path), so the
+ * Express and NestJS adapters can never drift on the privacy posture. The status is
+ * added by the caller (it differs: an Express error's own status vs a Nest
+ * `HttpException`'s).
+ */
+function serverContextFromRequest(req) {
+    const out = {};
+    if (typeof req.method === "string" && req.method.length > 0)
+        out.method = req.method;
+    const route = routePatternOf(req);
+    if (route)
+        out.route = route;
+    return out;
+}
+/** Read an http-errors-style numeric status off a thrown value (`err.status`/`.statusCode`). */
+function numericStatus(error) {
+    if (error && typeof error === "object") {
+        const e = error;
+        const raw = typeof e.status === "number" ? e.status : e.statusCode;
+        if (typeof raw === "number" && Number.isFinite(raw))
+            return raw;
+    }
+    return undefined;
+}
+/**
+ * A sensible status for a captured request error: the error's own status when set,
+ * else a 4xx/5xx already on the response, else `500`.
+ */
+function errorStatus(error, res) {
+    const fromError = numericStatus(error);
+    if (fromError && fromError >= 400)
+        return fromError;
+    const fromResponse = res.statusCode;
+    if (typeof fromResponse === "number" && fromResponse >= 400)
+        return fromResponse;
+    return 500;
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;AA0BH,wCASC;AAUD,4DAMC;AAGD,sCAOC;AAMD,kCAMC;AArDD;;;;;GAKG;AACH,SAAgB,cAAc,CAAC,GAAoB;IACjD,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC;IAClC,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACpE,MAAM,OAAO,GACX,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,IAAI,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;IACtF,MAAM,IAAI,GAAG,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IAChE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IACpE,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IACtC,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,EAAE,CAAC;AACvE,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,wBAAwB,CAAC,GAAoB;IAC3D,MAAM,GAAG,GAAwC,EAAE,CAAC;IACpD,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;IACrF,MAAM,KAAK,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,KAAK;QAAE,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC;IAC7B,OAAO,GAAG,CAAC;AACb,CAAC;AAED,gGAAgG;AAChG,SAAgB,aAAa,CAAC,KAAc;IAC1C,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,CAAC,GAAG,KAAmD,CAAC;QAC9D,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;QACnE,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,OAAO,GAAG,CAAC;IAClE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,SAAgB,WAAW,CAAC,KAAc,EAAE,GAAqB;IAC/D,MAAM,SAAS,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IACvC,IAAI,SAAS,IAAI,SAAS,IAAI,GAAG;QAAE,OAAO,SAAS,CAAC;IACpD,MAAM,YAAY,GAAG,GAAG,CAAC,UAAU,CAAC;IACpC,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,IAAI,GAAG;QAAE,OAAO,YAAY,CAAC;IACjF,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `@fixback/node` — the Fixback backend error SDK for Node servers.
+ *
+ * `init({ secretKey })` wires a batched secret-key transport, the polite
+ * process-crash handlers, and the manual capture API below. Framework adapters are
+ * separate entry points so a plain install never pulls a framework in:
+ *
+ * - `@fixback/node/express` — {@link https://expressjs.com Express} middlewares.
+ * - `@fixback/node/nestjs` — a NestJS module + exception filter.
+ *
+ * The root entry is framework-free: import from here for `init`, manual capture,
+ * `setUser`, and the shared types.
+ */
+export { captureException, captureMessage, close, FixbackClient, flush, getClient, init, } from "./client";
+export type { CaptureClient, CaptureContext, ClientDeps } from "./client";
+export { currentServerContext, getRequestStore, setRequestUser, setRequestUser as setUser } from "./context";
+export type { RequestStore } from "./context";
+export { DEFAULT_API_URL } from "./config";
+export type { InitOptions } from "./config";
+export type { CaptureTransport } from "./transport";
+export type { BeforeSend, FixbackErrorEvent, ServerContext, ServerErrorPayload, Severity, } from "./wire";
+export type { CapturedFrame } from "@fixback/sdk-core";
+export { NODE_SDK_VERSION } from "./version";

package/dist/index.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * `@fixback/node` — the Fixback backend error SDK for Node servers.
+ *
+ * `init({ secretKey })` wires a batched secret-key transport, the polite
+ * process-crash handlers, and the manual capture API below. Framework adapters are
+ * separate entry points so a plain install never pulls a framework in:
+ *
+ * - `@fixback/node/express` — {@link https://expressjs.com Express} middlewares.
+ * - `@fixback/node/nestjs` — a NestJS module + exception filter.
+ *
+ * The root entry is framework-free: import from here for `init`, manual capture,
+ * `setUser`, and the shared types.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NODE_SDK_VERSION = exports.DEFAULT_API_URL = exports.setUser = exports.setRequestUser = exports.getRequestStore = exports.currentServerContext = exports.init = exports.getClient = exports.flush = exports.FixbackClient = exports.close = exports.captureMessage = exports.captureException = void 0;
+// Capture surface + lifecycle.
+var client_1 = require("./client");
+Object.defineProperty(exports, "captureException", { enumerable: true, get: function () { return client_1.captureException; } });
+Object.defineProperty(exports, "captureMessage", { enumerable: true, get: function () { return client_1.captureMessage; } });
+Object.defineProperty(exports, "close", { enumerable: true, get: function () { return client_1.close; } });
+Object.defineProperty(exports, "FixbackClient", { enumerable: true, get: function () { return client_1.FixbackClient; } });
+Object.defineProperty(exports, "flush", { enumerable: true, get: function () { return client_1.flush; } });
+Object.defineProperty(exports, "getClient", { enumerable: true, get: function () { return client_1.getClient; } });
+Object.defineProperty(exports, "init", { enumerable: true, get: function () { return client_1.init; } });
+// Per-request context (AsyncLocalStorage) — attach a user, or read the active context.
+var context_1 = require("./context");
+Object.defineProperty(exports, "currentServerContext", { enumerable: true, get: function () { return context_1.currentServerContext; } });
+Object.defineProperty(exports, "getRequestStore", { enumerable: true, get: function () { return context_1.getRequestStore; } });
+Object.defineProperty(exports, "setRequestUser", { enumerable: true, get: function () { return context_1.setRequestUser; } });
+Object.defineProperty(exports, "setUser", { enumerable: true, get: function () { return context_1.setRequestUser; } });
+// Configuration.
+var config_1 = require("./config");
+Object.defineProperty(exports, "DEFAULT_API_URL", { enumerable: true, get: function () { return config_1.DEFAULT_API_URL; } });
+// The SDK's own version, reported as the capture `sdkVersion`.
+var version_1 = require("./version");
+Object.defineProperty(exports, "NODE_SDK_VERSION", { enumerable: true, get: function () { return version_1.NODE_SDK_VERSION; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAEH,+BAA+B;AAC/B,mCAQkB;AAPhB,0GAAA,gBAAgB,OAAA;AAChB,wGAAA,cAAc,OAAA;AACd,+FAAA,KAAK,OAAA;AACL,uGAAA,aAAa,OAAA;AACb,+FAAA,KAAK,OAAA;AACL,mGAAA,SAAS,OAAA;AACT,8FAAA,IAAI,OAAA;AAIN,uFAAuF;AACvF,qCAA6G;AAApG,+GAAA,oBAAoB,OAAA;AAAE,0GAAA,eAAe,OAAA;AAAE,yGAAA,cAAc,OAAA;AAAE,kGAAA,cAAc,OAAW;AAGzF,iBAAiB;AACjB,mCAA2C;AAAlC,yGAAA,eAAe,OAAA;AAkBxB,+DAA+D;AAC/D,qCAA6C;AAApC,2GAAA,gBAAgB,OAAA"}

package/dist/nestjs.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The **NestJS** adapter (`@fixback/node/nestjs`, story 2) — a module + exception
+ * filter that capture thrown request errors with server context, **without changing
+ * the app's behaviour**.
+ *
+ * - {@link FixbackExceptionFilter} extends Nest's `BaseExceptionFilter`: it captures
+ *   the exception (`handled: true`, with the request's route pattern / method /
+ *   status) and then delegates to `super.catch`, so Nest still produces the exact
+ *   HTTP response it would have. Registered globally via `APP_FILTER`.
+ * - {@link FixbackModule} wires that filter and applies the request-context
+ *   middleware (AsyncLocalStorage correlation) to every route. Register it with
+ *   `FixbackModule.forRoot()`.
+ *
+ * `@nestjs/common` and `@nestjs/core` are **optional peer dependencies** — this module
+ * is only loaded when you import `@fixback/node/nestjs`, so an Express-only or
+ * manual-capture install never pulls Nest in.
+ */
+import "reflect-metadata";
+import { type ArgumentsHost, type DynamicModule, type MiddlewareConsumer, type NestModule } from "@nestjs/common";
+import { BaseExceptionFilter } from "@nestjs/core";
+import { type CaptureClient } from "./client";
+/**
+ * Capture a Nest exception with the request's server context (`handled: true`).
+ * Exported so it can be unit-tested against a fake `ArgumentsHost`; the filter uses
+ * it. Never throws — a capture failure must not break the request pipeline.
+ */
+export declare function captureNestException(exception: unknown, host: ArgumentsHost, client?: CaptureClient): void;
+/**
+ * A global exception filter that captures every thrown request error and then hands
+ * off to Nest's `BaseExceptionFilter`, so the HTTP response is exactly what Nest
+ * would have produced (no behaviour change).
+ */
+export declare class FixbackExceptionFilter extends BaseExceptionFilter {
+    catch(exception: unknown, host: ArgumentsHost): void;
+}
+/**
+ * The Fixback NestJS module. Register with `imports: [FixbackModule.forRoot()]`; it
+ * installs the global {@link FixbackExceptionFilter} and applies the request-context
+ * middleware to every route.
+ */
+export declare class FixbackModule implements NestModule {
+    static forRoot(): DynamicModule;
+    configure(consumer: MiddlewareConsumer): void;
+}

package/dist/nestjs.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * The **NestJS** adapter (`@fixback/node/nestjs`, story 2) — a module + exception
+ * filter that capture thrown request errors with server context, **without changing
+ * the app's behaviour**.
+ *
+ * - {@link FixbackExceptionFilter} extends Nest's `BaseExceptionFilter`: it captures
+ *   the exception (`handled: true`, with the request's route pattern / method /
+ *   status) and then delegates to `super.catch`, so Nest still produces the exact
+ *   HTTP response it would have. Registered globally via `APP_FILTER`.
+ * - {@link FixbackModule} wires that filter and applies the request-context
+ *   middleware (AsyncLocalStorage correlation) to every route. Register it with
+ *   `FixbackModule.forRoot()`.
+ *
+ * `@nestjs/common` and `@nestjs/core` are **optional peer dependencies** — this module
+ * is only loaded when you import `@fixback/node/nestjs`, so an Express-only or
+ * manual-capture install never pulls Nest in.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var FixbackModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FixbackModule = exports.FixbackExceptionFilter = void 0;
+exports.captureNestException = captureNestException;
+require("reflect-metadata");
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const client_1 = require("./client");
+const context_1 = require("./context");
+const http_1 = require("./http");
+/** Files through the active module client by default. */
+const defaultClient = {
+    captureException: (error, context) => (0, client_1.captureException)(error, context),
+};
+/** Resolve the status: an `HttpException`'s own status, else the shared heuristic. */
+function nestStatus(exception, res) {
+    if (exception instanceof common_1.HttpException) {
+        const status = exception.getStatus();
+        if (typeof status === "number")
+            return status;
+    }
+    return (0, http_1.errorStatus)(exception, res);
+}
+/**
+ * Capture a Nest exception with the request's server context (`handled: true`).
+ * Exported so it can be unit-tested against a fake `ArgumentsHost`; the filter uses
+ * it. Never throws — a capture failure must not break the request pipeline.
+ */
+function captureNestException(exception, host, client = defaultClient) {
+    try {
+        const isHttp = typeof host.getType === "function" ? host.getType() === "http" : true;
+        if (!isHttp) {
+            client.captureException(exception, { handled: true });
+            return;
+        }
+        const http = host.switchToHttp();
+        const req = http.getRequest();
+        const res = (http.getResponse() ?? {});
+        const base = req ? (0, http_1.serverContextFromRequest)(req) : {};
+        const server = { ...base, statusCode: nestStatus(exception, res) };
+        client.captureException(exception, { handled: true, server });
+    }
+    catch {
+        try {
+            client.captureException(exception, { handled: true });
+        }
+        catch {
+            /* capture must never break the pipeline */
+        }
+    }
+}
+/**
+ * A global exception filter that captures every thrown request error and then hands
+ * off to Nest's `BaseExceptionFilter`, so the HTTP response is exactly what Nest
+ * would have produced (no behaviour change).
+ */
+let FixbackExceptionFilter = class FixbackExceptionFilter extends core_1.BaseExceptionFilter {
+    catch(exception, host) {
+        captureNestException(exception, host);
+        super.catch(exception, host);
+    }
+};
+exports.FixbackExceptionFilter = FixbackExceptionFilter;
+exports.FixbackExceptionFilter = FixbackExceptionFilter = __decorate([
+    (0, common_1.Catch)()
+], FixbackExceptionFilter);
+/**
+ * The Fixback NestJS module. Register with `imports: [FixbackModule.forRoot()]`; it
+ * installs the global {@link FixbackExceptionFilter} and applies the request-context
+ * middleware to every route.
+ */
+let FixbackModule = FixbackModule_1 = class FixbackModule {
+    static forRoot() {
+        return {
+            module: FixbackModule_1,
+            providers: [{ provide: core_1.APP_FILTER, useClass: FixbackExceptionFilter }],
+        };
+    }
+    configure(consumer) {
+        const requestIdHeader = (0, client_1.getClient)()?.requestIdHeader;
+        consumer
+            .apply((0, context_1.createRequestContextMiddleware)(requestIdHeader ? { requestIdHeader } : {}))
+            .forRoutes("*");
+    }
+};
+exports.FixbackModule = FixbackModule;
+exports.FixbackModule = FixbackModule = FixbackModule_1 = __decorate([
+    (0, common_1.Module)({})
+], FixbackModule);
+//# sourceMappingURL=nestjs.js.map

package/dist/nestjs.js.map

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

package/dist/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/process.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Process-level capture (spec §D9, stories 4 & 5) — the *polite* `uncaughtException`
+ * and `unhandledRejection` handlers that **never change the app's exit behaviour**.
+ *
+ * The subtlety: merely *adding* an `uncaughtException` listener suppresses Node's
+ * default crash. So to stay polite:
+ *
+ * - **uncaughtException:** capture (`handled: false`), then — only when we are the
+ *   *sole* listener (the app installed none of its own) — best-effort flush and hand
+ *   off to `onFatalError`, which preserves Node's default (log + non-zero exit). When
+ *   the app has its own handler, we do nothing further: the app owns the exit.
+ * - **unhandledRejection:** capture (`handled: false`) and stop. We never escalate a
+ *   rejection to a process exit — exactly the "never turn a logged rejection into an
+ *   exit" guarantee (story 5).
+ *
+ * Everything is wrapped so a capture failure can never break the handler.
+ */
+/** The `process` slice these handlers touch — injectable so tests never touch the real one. */
+export interface ProcessLike {
+    on(event: string, listener: (...args: unknown[]) => void): unknown;
+    removeListener(event: string, listener: (...args: unknown[]) => void): unknown;
+    listeners(event: string): Array<(...args: unknown[]) => void>;
+}
+/** What a captured process error is filed through — the {@link FixbackClient} satisfies it. */
+export interface CaptureSink {
+    captureException(error: unknown, context?: {
+        handled?: boolean;
+    }): void;
+    flush(): Promise<void>;
+}
+/** Which process handlers to install. */
+export interface ProcessHandlerOptions {
+    readonly captureUncaughtException: boolean;
+    readonly captureUnhandledRejection: boolean;
+    /** How long a fatal-path flush may take before the process exits anyway. */
+    readonly flushTimeoutMs?: number;
+}
+/** Injectable collaborators for {@link installProcessHandlers}. */
+export interface ProcessHandlerDeps {
+    readonly process?: ProcessLike;
+    /**
+     * Preserve Node's default fatal behaviour after a sole-listener uncaught exception.
+     * Defaults to logging the error and exiting non-zero (exactly what Node would do).
+     */
+    readonly onFatalError?: (error: unknown) => void;
+}
+/**
+ * Install the polite process handlers for `sink`, returning an uninstall function.
+ * A no-op (and a no-op uninstall) when no `process` is available or when both gates
+ * are off.
+ */
+export declare function installProcessHandlers(sink: CaptureSink, options: ProcessHandlerOptions, deps?: ProcessHandlerDeps): () => void;