@fixback/node 0.2.0 → 0.3.0

package/src/fingerprint-parity.test.ts

@@ -1,86 +0,0 @@
-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

@@ -1,83 +0,0 @@
-/**
- * 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

@@ -1,51 +0,0 @@
-/**
- * `@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

@@ -1,146 +0,0 @@
-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);
-  });
-});

package/src/nestjs.ts

@@ -1,123 +0,0 @@
-/**
- * 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,
-  Catch,
-  type DynamicModule,
-  HttpException,
-  type MiddlewareConsumer,
-  Module,
-  type NestModule,
-} from "@nestjs/common";
-import { APP_FILTER, BaseExceptionFilter } from "@nestjs/core";
-
-import {
-  type CaptureClient,
-  captureException as moduleCaptureException,
-  getClient,
-} from "./client";
-import { createRequestContextMiddleware } from "./context";
-import {
-  errorStatus,
-  type HttpRequestLike,
-  type HttpResponseLike,
-  serverContextFromRequest,
-} from "./http";
-
-/** Files through the active module client by default. */
-const defaultClient: CaptureClient = {
-  captureException: (error, context) => moduleCaptureException(error, context),
-};
-
-/** Resolve the status: an `HttpException`'s own status, else the shared heuristic. */
-function nestStatus(exception: unknown, res: HttpResponseLike): number {
-  if (exception instanceof HttpException) {
-    const status = exception.getStatus();
-    if (typeof status === "number") return status;
-  }
-  return 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.
- */
-export function captureNestException(
-  exception: unknown,
-  host: ArgumentsHost,
-  client: CaptureClient = defaultClient,
-): void {
-  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<HttpRequestLike>();
-    const res = (http.getResponse<HttpResponseLike>() ?? {}) as HttpResponseLike;
-    const base = req ? 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).
- */
-@Catch()
-export class FixbackExceptionFilter extends BaseExceptionFilter {
-  catch(exception: unknown, host: ArgumentsHost): void {
-    captureNestException(exception, host);
-    super.catch(exception, host);
-  }
-}
-
-/**
- * The Fixback NestJS module. Register with `imports: [FixbackModule.forRoot()]`; it
- * installs the global {@link FixbackExceptionFilter} and applies the request-context
- * middleware to every route.
- */
-@Module({})
-export class FixbackModule implements NestModule {
-  static forRoot(): DynamicModule {
-    return {
-      module: FixbackModule,
-      providers: [{ provide: APP_FILTER, useClass: FixbackExceptionFilter }],
-    };
-  }
-
-  configure(consumer: MiddlewareConsumer): void {
-    const requestIdHeader = getClient()?.requestIdHeader;
-    consumer
-      .apply(createRequestContextMiddleware(requestIdHeader ? { requestIdHeader } : {}))
-      .forRoutes("*");
-  }
-}

package/src/process.test.ts

@@ -1,154 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-
-import { installProcessHandlers, type ProcessLike } from "./process";
-
-type Listener = (...args: unknown[]) => void;
-
-/** A tiny EventEmitter-shaped stand-in for `process` (never the real one, in tests). */
-class FakeProcess implements ProcessLike {
-  private readonly map = new Map<string, Listener[]>();
-  on(event: string, listener: Listener): this {
-    this.map.set(event, [...(this.map.get(event) ?? []), listener]);
-    return this;
-  }
-  removeListener(event: string, listener: Listener): this {
-    this.map.set(event, (this.map.get(event) ?? []).filter((l) => l !== listener));
-    return this;
-  }
-  listeners(event: string): Listener[] {
-    return [...(this.map.get(event) ?? [])];
-  }
-  emit(event: string, ...args: unknown[]): void {
-    for (const l of [...(this.map.get(event) ?? [])]) l(...args);
-  }
-}
-
-function fakeSink() {
-  const captures: Array<{ error: unknown; handled?: boolean }> = [];
-  let flushes = 0;
-  return {
-    captures,
-    get flushes() {
-      return flushes;
-    },
-    sink: {
-      captureException(error: unknown, context?: { handled?: boolean }) {
-        captures.push({ error, handled: context?.handled });
-      },
-      flush: async () => {
-        flushes += 1;
-      },
-    },
-  };
-}
-
-const tick = () => new Promise((resolve) => setTimeout(resolve, 0));
-
-describe("installProcessHandlers", () => {
-  it("adds an uncaughtException and unhandledRejection listener, and uninstall removes them", () => {
-    const proc = new FakeProcess();
-    const { sink } = fakeSink();
-    const uninstall = installProcessHandlers(
-      sink,
-      { captureUncaughtException: true, captureUnhandledRejection: true },
-      { process: proc, onFatalError: () => {} },
-    );
-    expect(proc.listeners("uncaughtException")).toHaveLength(1);
-    expect(proc.listeners("unhandledRejection")).toHaveLength(1);
-    uninstall();
-    expect(proc.listeners("uncaughtException")).toHaveLength(0);
-    expect(proc.listeners("unhandledRejection")).toHaveLength(0);
-  });
-
-  it("installs only the handlers the gates enable", () => {
-    const proc = new FakeProcess();
-    const { sink } = fakeSink();
-    installProcessHandlers(
-      sink,
-      { captureUncaughtException: false, captureUnhandledRejection: true },
-      { process: proc, onFatalError: () => {} },
-    );
-    expect(proc.listeners("uncaughtException")).toHaveLength(0);
-    expect(proc.listeners("unhandledRejection")).toHaveLength(1);
-  });
-
-  it("captures an uncaught exception as handled:false", () => {
-    const proc = new FakeProcess();
-    const { sink, captures } = fakeSink();
-    installProcessHandlers(
-      sink,
-      { captureUncaughtException: true, captureUnhandledRejection: false },
-      { process: proc, onFatalError: () => {} },
-    );
-    proc.emit("uncaughtException", new Error("crash"), "uncaughtException");
-    expect(captures).toHaveLength(1);
-    expect((captures[0]!.error as Error).message).toBe("crash");
-    expect(captures[0]!.handled).toBe(false);
-  });
-
-  it("preserves the default crash — flushes then calls onFatalError — when it is the only listener", async () => {
-    const proc = new FakeProcess();
-    const { sink } = fakeSink();
-    const onFatalError = vi.fn();
-    installProcessHandlers(
-      sink,
-      { captureUncaughtException: true, captureUnhandledRejection: false },
-      { process: proc, onFatalError },
-    );
-    const boom = new Error("boom");
-    proc.emit("uncaughtException", boom);
-    await tick();
-    expect(onFatalError).toHaveBeenCalledTimes(1);
-    expect(onFatalError).toHaveBeenCalledWith(boom);
-  });
-
-  it("does NOT change exit behaviour when the app has its own uncaughtException listener", async () => {
-    const proc = new FakeProcess();
-    const { sink, captures } = fakeSink();
-    const onFatalError = vi.fn();
-    installProcessHandlers(
-      sink,
-      { captureUncaughtException: true, captureUnhandledRejection: false },
-      { process: proc, onFatalError },
-    );
-    // The host installed its own handler — it owns the exit decision.
-    proc.on("uncaughtException", () => {});
-    proc.emit("uncaughtException", new Error("x"));
-    await tick();
-    expect(captures).toHaveLength(1); // still captured
-    expect(onFatalError).not.toHaveBeenCalled(); // but we never force an exit
-  });
-
-  it("captures an unhandled rejection as handled:false and never forces an exit (story 5)", async () => {
-    const proc = new FakeProcess();
-    const { sink, captures } = fakeSink();
-    const onFatalError = vi.fn();
-    installProcessHandlers(
-      sink,
-      { captureUncaughtException: false, captureUnhandledRejection: true },
-      { process: proc, onFatalError },
-    );
-    proc.emit("unhandledRejection", new Error("rejected"), Promise.resolve());
-    await tick();
-    expect(captures).toHaveLength(1);
-    expect((captures[0]!.error as Error).message).toBe("rejected");
-    expect(captures[0]!.handled).toBe(false);
-    expect(onFatalError).not.toHaveBeenCalled();
-  });
-
-  it("never throws out of the handler when capture itself fails", () => {
-    const proc = new FakeProcess();
-    const throwingSink = {
-      captureException() {
-        throw new Error("capture blew up");
-      },
-      flush: async () => {},
-    };
-    installProcessHandlers(
-      throwingSink,
-      { captureUncaughtException: true, captureUnhandledRejection: false },
-      { process: proc, onFatalError: () => {} },
-    );
-    expect(() => proc.emit("uncaughtException", new Error("x"))).not.toThrow();
-  });
-});