@fixback/node 0.2.0

package/src/context.ts

@@ -0,0 +1,124 @@
+/**
+ * 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 { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+
+import { type HttpRequestLike, type HttpResponseLike, type NextFunction, routePatternOf } 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;
+}
+
+const storage = new AsyncLocalStorage<RequestStore>();
+
+/** The active request store, or `undefined` outside a request scope. */
+export function getRequestStore(): RequestStore | undefined {
+  return storage.getStore();
+}
+
+/** Run `fn` (and everything it awaits) with `store` as the active request store. */
+export function runWithRequestStore<T>(store: RequestStore, fn: () => T): T {
+  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.
+ */
+export function setRequestUser(user: string): void {
+  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.
+ */
+export function deriveServerContext(store: RequestStore | undefined): ServerContext | undefined {
+  if (!store) return undefined;
+  const ctx: {
+    method?: string;
+    route?: string;
+    statusCode?: number;
+    requestId?: string;
+    user?: string;
+  } = {};
+
+  const method = store.req.method;
+  if (typeof method === "string" && method.length > 0) ctx.method = method;
+
+  const route = 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. */
+export function currentServerContext(): ServerContext | undefined {
+  return deriveServerContext(storage.getStore());
+}
+
+/** Read a correlation id from the configured header, taking the first if repeated. */
+function readRequestId(req: HttpRequestLike, header: string): string | undefined {
+  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;
+}
+
+/** 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 function createRequestContextMiddleware(
+  options: RequestContextOptions = {},
+): (req: HttpRequestLike, res: HttpResponseLike, next: NextFunction) => void {
+  const header = (options.requestIdHeader ?? "x-request-id").toLowerCase();
+  return function fixbackRequestContext(
+    req: HttpRequestLike,
+    res: HttpResponseLike,
+    next: NextFunction,
+  ): void {
+    const store: RequestStore = {
+      req,
+      res,
+      requestId: readRequestId(req, header) ?? randomUUID(),
+    };
+    runWithRequestStore(store, () => next());
+  };
+}

package/src/express.test.ts

@@ -0,0 +1,112 @@
+import { afterEach, describe, expect, it } from "vitest";
+
+import { close as moduleClose, FixbackClient, init } from "./client";
+import { resolveConfig } from "./config";
+import { fixbackErrorHandler, fixbackRequestContext } from "./express";
+import type { CaptureTransport } from "./transport";
+import type { ServerErrorPayload } from "./wire";
+
+function recorder(): { enqueued: ServerErrorPayload[]; transport: CaptureTransport } {
+  const enqueued: ServerErrorPayload[] = [];
+  return {
+    enqueued,
+    transport: {
+      enqueue: (payload) => enqueued.push(payload),
+      flush: async () => {},
+      close: async () => {},
+    },
+  };
+}
+
+const makeClient = (transport: CaptureTransport) =>
+  new FixbackClient(resolveConfig({ secretKey: "sk" }), { transport });
+
+describe("fixbackErrorHandler + fixbackRequestContext", () => {
+  it("captures a request error with server context (handled:true) and forwards it to next", () => {
+    const { enqueued, transport } = recorder();
+    const client = makeClient(transport);
+    const contextMiddleware = fixbackRequestContext();
+    const errorHandler = fixbackErrorHandler({ client });
+
+    const req = { method: "GET", route: { path: "/boom/:id" }, path: "/boom/1" };
+    const res = { statusCode: 200 };
+    const error = new Error("kaboom");
+    let forwarded: unknown;
+
+    contextMiddleware(req, res, () => {
+      // Simulate a route throwing and Express routing it to the error handler.
+      errorHandler(error, req, res, (e) => {
+        forwarded = e;
+      });
+    });
+
+    expect(forwarded).toBe(error); // never swallowed — the app's own handling still runs
+    expect(enqueued).toHaveLength(1);
+    expect(enqueued[0]!.handled).toBe(true);
+    expect(enqueued[0]!.server?.method).toBe("GET");
+    expect(enqueued[0]!.server?.route).toBe("/boom/:id");
+    // No err.status and res still 200 → a sensible 500 for an unhandled request error.
+    expect(enqueued[0]!.server?.statusCode).toBe(500);
+  });
+
+  it("carries the correlation id opened by the request-context middleware", () => {
+    const { enqueued, transport } = recorder();
+    const client = makeClient(transport);
+    const contextMiddleware = fixbackRequestContext();
+    const errorHandler = fixbackErrorHandler({ client });
+
+    const req = { method: "POST", route: { path: "/x" }, headers: { "x-request-id": "corr-77" } };
+    const res = { statusCode: 200 };
+    contextMiddleware(req, res, () => {
+      errorHandler(new Error("boom"), req, res, () => {});
+    });
+
+    expect(enqueued[0]!.server?.requestId).toBe("corr-77");
+  });
+
+  it("derives the status from an http-errors-style status on the error", () => {
+    const { enqueued, transport } = recorder();
+    const client = makeClient(transport);
+    const errorHandler = fixbackErrorHandler({ client });
+    const error = Object.assign(new Error("forbidden"), { statusCode: 403 });
+
+    let forwarded: unknown;
+    errorHandler(error, { method: "GET", route: { path: "/y" } }, { statusCode: 200 }, (e) => {
+      forwarded = e;
+    });
+
+    expect(forwarded).toBe(error);
+    expect(enqueued[0]!.server).toEqual({ method: "GET", route: "/y", statusCode: 403 });
+  });
+
+  it("still forwards the error when capture itself throws (never breaks the app)", () => {
+    const throwingClient = {
+      captureException() {
+        throw new Error("capture blew up");
+      },
+    };
+    const errorHandler = fixbackErrorHandler({ client: throwingClient });
+    const original = new Error("x");
+    let forwarded: unknown;
+    errorHandler(original, {}, {}, (e) => {
+      forwarded = e;
+    });
+    expect(forwarded).toBe(original);
+  });
+
+  it("uses the active module client when no explicit client is given", async () => {
+    const { enqueued, transport } = recorder();
+    init(
+      { secretKey: "sk", captureUncaughtException: false, captureUnhandledRejection: false },
+      { transport },
+    );
+    const errorHandler = fixbackErrorHandler();
+    errorHandler(new Error("via module"), { method: "GET", route: { path: "/z" } }, { statusCode: 500 }, () => {});
+    expect(enqueued).toHaveLength(1);
+    await moduleClose();
+  });
+
+  afterEach(async () => {
+    await moduleClose();
+  });
+});

package/src/express.ts

@@ -0,0 +1,85 @@
+/**
+ * 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,
+  captureException as moduleCaptureException,
+  getClient,
+} from "./client";
+import { createRequestContextMiddleware } from "./context";
+import {
+  errorStatus,
+  type HttpRequestLike,
+  type HttpResponseLike,
+  type NextFunction,
+  serverContextFromRequest,
+} 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 function fixbackRequestContext(options: RequestContextOptions = {}): ExpressMiddleware {
+  const header = options.requestIdHeader ?? getClient()?.requestIdHeader;
+  return 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)`.
+ */
+export function fixbackErrorHandler(options: ErrorHandlerOptions = {}): ExpressErrorMiddleware {
+  const client: CaptureClient = options.client ?? {
+    captureException: (error, context) => moduleCaptureException(error, context),
+  };
+  return function fixbackErrorHandlerMiddleware(error, req, res, next): void {
+    try {
+      const server = { ...serverContextFromRequest(req), statusCode: errorStatus(error, res) };
+      client.captureException(error, { handled: true, server });
+    } catch {
+      // Capture must never break the request pipeline — always forward the error.
+    }
+    next(error);
+  };
+}

package/src/fingerprint-parity.test.ts

@@ -0,0 +1,86 @@
+import { computeFingerprint } from "@fixback/sdk-core";
+import { describe, expect, it } from "vitest";
+
+import { FixbackClient } from "./client";
+import { resolveConfig } from "./config";
+import type { CaptureTransport } from "./transport";
+import type { ServerErrorPayload } from "./wire";
+
+/**
+ * Cross-surface fingerprint parity (ADR-0027/0028, spec #224 Seam 3): the browser and
+ * node SDKs must compute the **same** fingerprint for the same logical error, or a
+ * crash surfaced from both the frontend and the backend would not group together.
+ *
+ * Both SDKs key an error with the **shared core** `computeFingerprint(type, value,
+ * stack)`. `browserFingerprint` reproduces the browser SDK's distillation exactly
+ * (`packages/sdk/src/error-capture.ts`: `type = error.name || "Error"`,
+ * `value = error.message`, `stack = error.stack`, then `computeFingerprint(...)`), so
+ * it is the key the browser SDK would produce. `nodeFingerprint` drives the real
+ * `@fixback/node` capture pipeline and reads the fingerprint off the outgoing payload.
+ */
+
+/** The key the browser SDK computes for `error` (its distillation + the shared core). */
+function browserFingerprint(error: Error): string {
+  const type = error.name || "Error";
+  return computeFingerprint(type, error.message, error.stack);
+}
+
+/** The key the node SDK puts on the wire for `error` (the real capture pipeline). */
+function nodeFingerprint(error: unknown): string {
+  const enqueued: ServerErrorPayload[] = [];
+  const transport: CaptureTransport = {
+    enqueue: (payload) => enqueued.push(payload),
+    flush: async () => {},
+    close: async () => {},
+  };
+  const client = new FixbackClient(resolveConfig({ secretKey: "sk" }), { transport });
+  client.captureException(error);
+  return enqueued[0]!.errorSignature;
+}
+
+describe("cross-surface fingerprint parity (ADR-0028)", () => {
+  it("matches the browser's fingerprint for a typed error with a stack", () => {
+    const error = new TypeError("Cannot read properties of undefined (reading 'id')");
+    error.stack = [
+      "TypeError: Cannot read properties of undefined (reading 'id')",
+      "    at renderTotal (/srv/app/dist/checkout.js:88:12)",
+      "    at handle (/srv/app/dist/server.js:42:5)",
+    ].join("\n");
+    expect(nodeFingerprint(error)).toBe(browserFingerprint(error));
+  });
+
+  it("matches for a plain, stackless message-only error", () => {
+    const error = new Error("database connection refused");
+    error.stack = undefined;
+    expect(nodeFingerprint(error)).toBe(browserFingerprint(error));
+  });
+
+  it("matches for a custom error subclass (its name is the type on both surfaces)", () => {
+    class PaymentError extends Error {
+      constructor(message: string) {
+        super(message);
+        this.name = "PaymentError";
+      }
+    }
+    const error = new PaymentError("card declined");
+    expect(nodeFingerprint(error)).toBe(browserFingerprint(error));
+  });
+
+  it("is stable across instances — the same error from different install paths groups", () => {
+    // Two fleet instances throw the identical error; only the absolute path differs.
+    const onA = new Error("boom");
+    onA.stack = "Error: boom\n    at handler (/srv/app-a/dist/checkout.js:88:12)";
+    const onB = new Error("boom");
+    onB.stack = "Error: boom\n    at handler (/home/deploy/app-b/dist/checkout.js:88:12)";
+
+    // The node SDK folds them to one fingerprint, and it is the browser's fingerprint too.
+    expect(nodeFingerprint(onA)).toBe(nodeFingerprint(onB));
+    expect(nodeFingerprint(onA)).toBe(browserFingerprint(onA));
+  });
+
+  it("keeps genuinely distinct errors distinct", () => {
+    const a = new Error("first failure");
+    const b = new Error("second failure");
+    expect(nodeFingerprint(a)).not.toBe(nodeFingerprint(b));
+  });
+});

package/src/http.ts

@@ -0,0 +1,83 @@
+/**
+ * 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 function routePatternOf(req: HttpRequestLike): string | undefined {
+  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).
+ */
+export function serverContextFromRequest(req: HttpRequestLike): { method?: string; route?: string } {
+  const out: { method?: string; route?: string } = {};
+  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`). */
+export function numericStatus(error: unknown): number | undefined {
+  if (error && typeof error === "object") {
+    const e = error as { status?: unknown; statusCode?: unknown };
+    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`.
+ */
+export function errorStatus(error: unknown, res: HttpResponseLike): number {
+  const fromError = numericStatus(error);
+  if (fromError && fromError >= 400) return fromError;
+  const fromResponse = res.statusCode;
+  if (typeof fromResponse === "number" && fromResponse >= 400) return fromResponse;
+  return 500;
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+/**
+ * `@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.
+ */
+
+// Capture surface + lifecycle.
+export {
+  captureException,
+  captureMessage,
+  close,
+  FixbackClient,
+  flush,
+  getClient,
+  init,
+} from "./client";
+export type { CaptureClient, CaptureContext, ClientDeps } from "./client";
+
+// Per-request context (AsyncLocalStorage) — attach a user, or read the active context.
+export { currentServerContext, getRequestStore, setRequestUser, setRequestUser as setUser } from "./context";
+export type { RequestStore } from "./context";
+
+// Configuration.
+export { DEFAULT_API_URL } from "./config";
+export type { InitOptions } from "./config";
+
+// Transport contract (advanced — a custom transport).
+export type { CaptureTransport } from "./transport";
+
+// Wire / event value shapes.
+export type {
+  BeforeSend,
+  FixbackErrorEvent,
+  ServerContext,
+  ServerErrorPayload,
+  Severity,
+} from "./wire";
+
+// Re-exported from the shared core so callers can type stack frames in `beforeSend`.
+export type { CapturedFrame } from "@fixback/sdk-core";
+
+// The SDK's own version, reported as the capture `sdkVersion`.
+export { NODE_SDK_VERSION } from "./version";

package/src/nestjs.test.ts

@@ -0,0 +1,146 @@
+import "reflect-metadata";
+
+import type { ArgumentsHost } from "@nestjs/common";
+import { HttpException } from "@nestjs/common";
+import { APP_FILTER, BaseExceptionFilter } from "@nestjs/core";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { close as moduleClose, init } from "./client";
+import type { CaptureClient, CaptureContext } from "./client";
+import { captureNestException, FixbackExceptionFilter, FixbackModule } from "./nestjs";
+import type { CaptureTransport } from "./transport";
+import type { ServerErrorPayload } from "./wire";
+
+interface Captured {
+  error: unknown;
+  context?: CaptureContext;
+}
+
+function recordingClient(): { captures: Captured[]; client: CaptureClient } {
+  const captures: Captured[] = [];
+  return {
+    captures,
+    client: { captureException: (error, context) => captures.push({ error, context }) },
+  };
+}
+
+function recorder(): { enqueued: ServerErrorPayload[]; transport: CaptureTransport } {
+  const enqueued: ServerErrorPayload[] = [];
+  return {
+    enqueued,
+    transport: {
+      enqueue: (payload) => enqueued.push(payload),
+      flush: async () => {},
+      close: async () => {},
+    },
+  };
+}
+
+function fakeHost(req: unknown, res: unknown, type = "http"): ArgumentsHost {
+  const http = {
+    getRequest: <T>() => req as T,
+    getResponse: <T>() => res as T,
+    getNext: <T>() => undefined as T,
+  };
+  return {
+    switchToHttp: () => http,
+    getType: () => type,
+    getArgs: () => [],
+    getArgByIndex: () => undefined,
+    switchToRpc: () => ({}),
+    switchToWs: () => ({}),
+  } as unknown as ArgumentsHost;
+}
+
+afterEach(async () => {
+  await moduleClose();
+});
+
+describe("captureNestException", () => {
+  it("captures a thrown request error with server context (handled:true)", () => {
+    const { captures, client } = recordingClient();
+    captureNestException(
+      new Error("boom"),
+      fakeHost({ method: "GET", route: { path: "/orders/:id" } }, { statusCode: 200 }),
+      client,
+    );
+    expect(captures[0]!.context?.handled).toBe(true);
+    expect(captures[0]!.context?.server?.method).toBe("GET");
+    expect(captures[0]!.context?.server?.route).toBe("/orders/:id");
+    expect(captures[0]!.context?.server?.statusCode).toBe(500);
+  });
+
+  it("uses an HttpException's status code", () => {
+    const { captures, client } = recordingClient();
+    captureNestException(
+      new HttpException("forbidden", 403),
+      fakeHost({ method: "DELETE", route: { path: "/x" } }, { statusCode: 200 }),
+      client,
+    );
+    expect(captures[0]!.context?.server?.statusCode).toBe(403);
+  });
+
+  it("never throws even if capture fails", () => {
+    const client: CaptureClient = {
+      captureException() {
+        throw new Error("capture blew up");
+      },
+    };
+    expect(() =>
+      captureNestException(new Error("y"), fakeHost({ method: "GET" }, {}), client),
+    ).not.toThrow();
+  });
+});
+
+describe("FixbackExceptionFilter", () => {
+  it("captures the exception, then delegates to Nest's base filter (behaviour unchanged)", () => {
+    const { enqueued, transport } = recorder();
+    init(
+      { secretKey: "sk", captureUncaughtException: false, captureUnhandledRejection: false },
+      { transport },
+    );
+    const superCatch = vi
+      .spyOn(BaseExceptionFilter.prototype, "catch")
+      .mockImplementation(() => {});
+
+    const filter = new FixbackExceptionFilter();
+    const host = fakeHost({ method: "GET", route: { path: "/x" } }, { statusCode: 200 });
+    filter.catch(new Error("boom"), host);
+
+    expect(enqueued).toHaveLength(1);
+    expect(enqueued[0]!.handled).toBe(true);
+    expect(enqueued[0]!.server?.route).toBe("/x");
+    expect(superCatch).toHaveBeenCalledTimes(1);
+    superCatch.mockRestore();
+  });
+});
+
+describe("FixbackModule", () => {
+  it("configure() applies a request-context middleware to all routes", () => {
+    const applied: { middleware: unknown[]; routes: unknown[] } = { middleware: [], routes: [] };
+    const consumer = {
+      apply: (...mws: unknown[]) => {
+        applied.middleware = mws;
+        return {
+          forRoutes: (...routes: unknown[]) => {
+            applied.routes = routes;
+          },
+        };
+      },
+    };
+    new FixbackModule().configure(consumer as never);
+    expect(applied.middleware).toHaveLength(1);
+    expect(typeof applied.middleware[0]).toBe("function");
+    expect(applied.routes).toEqual(["*"]);
+  });
+
+  it("forRoot() registers the exception filter as a global APP_FILTER", () => {
+    const dynamic = FixbackModule.forRoot();
+    expect(dynamic.module).toBe(FixbackModule);
+    const providers = dynamic.providers ?? [];
+    const filterProvider = providers.find(
+      (p) => (p as { provide?: unknown }).provide === APP_FILTER,
+    ) as { useClass?: unknown } | undefined;
+    expect(filterProvider?.useClass).toBe(FixbackExceptionFilter);
+  });
+});