@fixback/node 0.2.0

package/dist/wire.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The `@fixback/node` **transport contract** — the value shapes this SDK sends to
+ * the secret-key server-error ingest endpoint, and the {@link FixbackErrorEvent} the
+ * `beforeSend` hook sees before a capture leaves the process.
+ *
+ * `@fixback/node` **vendors** this contract (the ticket #47 convention, reaffirmed by
+ * ADR-0028: the shared core carries pure logic and value shapes, not the ingest
+ * envelope). It is kept in lock-step with the server endpoint that parses it —
+ * `POST /api/errors` (`apps/api/src/errors/errors.controller.ts`, ADR-0026/0027).
+ * `CapturedFrame` (the structured stack-frame shape) is the one type reused from the
+ * shared core, so the browser and node SDKs describe a frame identically.
+ */
+import type { CapturedFrame } from "@fixback/sdk-core";
+/** A severity for {@link FixbackErrorEvent} messages — Sentry's level vocabulary. */
+export type Severity = "fatal" | "error" | "warning" | "info" | "debug";
+/**
+ * The **server context** captured for a backend error (ADR-0025, spec #224).
+ * Private-by-default: the route **pattern** (never the concrete path with values),
+ * the HTTP method, the resolved status, a correlation id, and an **app-supplied**
+ * user ref only. Never request/response bodies, never `Authorization`/`Cookie`
+ * headers, never env vars, never query-string values.
+ */
+export interface ServerContext {
+    /** The HTTP method (`GET`, `POST`, …). */
+    readonly method?: string;
+    /** The route **pattern** (`/users/:id`) — never the concrete path with values. */
+    readonly route?: string;
+    /** The resolved HTTP status of the failed request. */
+    readonly statusCode?: number;
+    /** A per-request correlation id (from `x-request-id` when present, else generated). */
+    readonly requestId?: string;
+    /** An **app-supplied** user reference (via `setUser`) — never scraped from the request. */
+    readonly user?: string;
+}
+/**
+ * The assembled event a capture produces, handed to the project's optional
+ * `beforeSend` hook (spec §C) before transport. The hook may mutate it (to redact)
+ * or return `null` to drop the event entirely.
+ *
+ * `type` and `value` (the error class and message) are here for the hook to inspect
+ * and for the fingerprint, but are **not** put on the wire — the ingest contract has
+ * no slot for them (the fingerprint already encodes them, and error text is treated
+ * as untrusted-derived, ADR-0016). `level` likewise rides only on the event.
+ */
+export interface FixbackErrorEvent {
+    /** The cross-surface fingerprint (shared-core signature, ADR-0028) — the fold key. */
+    errorSignature: string;
+    /** The error class / name (`TypeError`), or `"Message"` for a `captureMessage`. */
+    type: string;
+    /** The error message (or the message text for a `captureMessage`). */
+    value: string;
+    /** `false` = an uncaught process crash, `true` = a caught/manual capture (ADR-0025). */
+    handled?: boolean;
+    /** The severity of a `captureMessage` (event-only; unset for a `captureException`). */
+    level?: Severity;
+    /** The deploy environment (`production` / `staging` / …). */
+    environment?: string;
+    /** The host app's Release — the build the stack symbolicates against. */
+    release?: string;
+    /** The running occurrence count coalesced for this fingerprint in the flush window. */
+    occurrences?: number;
+    /** The parsed stack frames, top of stack first, scrubbed and capped. */
+    errorFrames?: CapturedFrame[];
+    /** The in-flight request's server context, when captured inside a request. */
+    server?: ServerContext;
+}
+/**
+ * The project's optional capture hook (spec §C, story 24), run at the scrub choke
+ * point **after** the built-in scrubbers. Mutate the event to redact, or return
+ * `null` to drop it entirely. Synchronous and network-free by contract; a hook that
+ * throws is treated as a no-op (the already-scrubbed event is kept).
+ */
+export type BeforeSend = (event: FixbackErrorEvent) => FixbackErrorEvent | null;
+/**
+ * One captured backend error **on the wire** — the payload item the SDK posts.
+ * `errorSignature` is required (the ADR-0027 fold key); everything else is optional.
+ * Mirrors the server's `errorItemBody`. `server` rides along for forward
+ * compatibility — the current endpoint strips unknown keys, so it is harmless today
+ * and ready for when the server persists it.
+ */
+export interface ServerErrorPayload {
+    readonly errorSignature: string;
+    readonly handled?: boolean;
+    readonly environment?: string;
+    readonly release?: string;
+    readonly occurrences?: number;
+    readonly errorFrames?: readonly CapturedFrame[];
+    readonly server?: ServerContext;
+}
+/** The JSON batch envelope `POST`ed to `/api/errors` — a non-empty array of errors. */
+export interface ServerErrorBatch {
+    readonly errors: readonly ServerErrorPayload[];
+}
+/** The per-item accept/reject result the endpoint returns (ADR-0026 partial-failure). */
+export type ServerErrorItemResult = {
+    readonly accepted: true;
+    readonly issueId: string;
+    readonly folded: boolean;
+    readonly feedbackId?: string;
+} | {
+    readonly accepted: false;
+    readonly reason: string;
+};
+/** The endpoint's response body — `results` on `201`, or a `message` on a shed `429`. */
+export interface ServerErrorResponse {
+    readonly results?: readonly ServerErrorItemResult[];
+    readonly message?: string;
+}

package/dist/wire.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * The `@fixback/node` **transport contract** — the value shapes this SDK sends to
+ * the secret-key server-error ingest endpoint, and the {@link FixbackErrorEvent} the
+ * `beforeSend` hook sees before a capture leaves the process.
+ *
+ * `@fixback/node` **vendors** this contract (the ticket #47 convention, reaffirmed by
+ * ADR-0028: the shared core carries pure logic and value shapes, not the ingest
+ * envelope). It is kept in lock-step with the server endpoint that parses it —
+ * `POST /api/errors` (`apps/api/src/errors/errors.controller.ts`, ADR-0026/0027).
+ * `CapturedFrame` (the structured stack-frame shape) is the one type reused from the
+ * shared core, so the browser and node SDKs describe a frame identically.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=wire.js.map

package/dist/wire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.js","sourceRoot":"","sources":["../src/wire.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG"}

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@fixback/node",
+  "version": "0.2.0",
+  "description": "The Fixback backend error SDK for Node servers — one-call init, batched secret-key capture, process handlers, and Express + NestJS adapters.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    },
+    "./express": {
+      "types": "./dist/express.d.ts",
+      "import": "./dist/express.js",
+      "require": "./dist/express.js"
+    },
+    "./nestjs": {
+      "types": "./dist/nestjs.d.ts",
+      "import": "./dist/nestjs.js",
+      "require": "./dist/nestjs.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "fixback",
+    "feedback",
+    "error-tracking",
+    "node",
+    "express",
+    "nestjs",
+    "sdk"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wemuda/fixback.git",
+    "directory": "packages/node"
+  },
+  "homepage": "https://github.com/wemuda/fixback/tree/master/packages/node#readme",
+  "bugs": "https://github.com/wemuda/fixback/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@fixback/sdk-core": "0.2.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": ">=10.0.0",
+    "@nestjs/core": ">=10.0.0",
+    "express": ">=4.18.0",
+    "reflect-metadata": ">=0.1.13"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": true
+    },
+    "@nestjs/core": {
+      "optional": true
+    },
+    "express": {
+      "optional": true
+    },
+    "reflect-metadata": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.1.29",
+    "@nestjs/core": "^11.1.29",
+    "@types/node": "^22.20.1",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2",
+    "typescript": "5.9.3",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/finalize-cjs.mjs",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/client.test.ts

@@ -0,0 +1,272 @@
+import { computeFingerprint } from "@fixback/sdk-core";
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+  captureException as moduleCaptureException,
+  captureMessage as moduleCaptureMessage,
+  close as moduleClose,
+  FixbackClient,
+  getClient,
+  init,
+} from "./client";
+import { resolveConfig } from "./config";
+import { runWithRequestStore } from "./context";
+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 () => {},
+    },
+  };
+}
+
+function client(options: Parameters<typeof resolveConfig>[0], transport: CaptureTransport) {
+  return new FixbackClient(resolveConfig(options), { transport });
+}
+
+/** A tiny process stand-in so module tests never attach handlers to the real process. */
+function fakeProcess() {
+  const map = new Map<string, Array<(...args: unknown[]) => void>>();
+  return {
+    on(event: string, listener: (...args: unknown[]) => void) {
+      map.set(event, [...(map.get(event) ?? []), listener]);
+      return this;
+    },
+    removeListener(event: string, listener: (...args: unknown[]) => void) {
+      map.set(event, (map.get(event) ?? []).filter((l) => l !== listener));
+      return this;
+    },
+    listeners(event: string) {
+      return [...(map.get(event) ?? [])];
+    },
+  };
+}
+
+describe("FixbackClient.captureException", () => {
+  it("enqueues a payload with a fingerprint, handled:true, environment, release and frames", () => {
+    const { enqueued, transport } = recorder();
+    const c = client({ secretKey: "sk", environment: "production", release: "1.2.3" }, transport);
+
+    c.captureException(new TypeError("boom"));
+
+    expect(enqueued).toHaveLength(1);
+    const payload = enqueued[0]!;
+    expect(typeof payload.errorSignature).toBe("string");
+    expect(payload.errorSignature.length).toBeGreaterThan(0);
+    expect(payload.handled).toBe(true);
+    expect(payload.environment).toBe("production");
+    expect(payload.release).toBe("1.2.3");
+    expect(payload.errorFrames?.length ?? 0).toBeGreaterThan(0);
+    // The error class / message never travel on the wire (no server slot; untrusted).
+    const asRecord = payload as unknown as Record<string, unknown>;
+    expect(asRecord.type).toBeUndefined();
+    expect(asRecord.value).toBeUndefined();
+  });
+
+  it("fingerprints via the shared core — the same error yields a stable key", () => {
+    const { enqueued, transport } = recorder();
+    const c = client({ secretKey: "sk" }, transport);
+    const err = new Error("same");
+    err.stack = "Error: same\n    at fn (/srv/app/a.js:1:1)";
+    c.captureException(err);
+    c.captureException(err);
+    expect(enqueued[0]!.errorSignature).toBe(enqueued[1]!.errorSignature);
+    expect(enqueued[0]!.errorSignature).toBe(computeFingerprint("Error", "same", err.stack));
+  });
+
+  it("attaches the in-flight request's server context from AsyncLocalStorage", () => {
+    const { enqueued, transport } = recorder();
+    const c = client({ secretKey: "sk" }, transport);
+    runWithRequestStore(
+      {
+        req: { method: "POST", route: { path: "/pay/:id" }, path: "/pay/42" },
+        res: { statusCode: 500 },
+        requestId: "r-1",
+        user: "u-9",
+      },
+      () => c.captureException(new Error("x")),
+    );
+    expect(enqueued[0]!.server).toEqual({
+      method: "POST",
+      route: "/pay/:id",
+      statusCode: 500,
+      requestId: "r-1",
+      user: "u-9",
+    });
+  });
+
+  it("lets an explicit context override merge over the request context (Nest filter status)", () => {
+    const { enqueued, transport } = recorder();
+    const c = client({ secretKey: "sk" }, transport);
+    runWithRequestStore(
+      { req: { method: "GET", route: { path: "/x" } }, res: { statusCode: 200 } },
+      () => c.captureException(new Error("x"), { handled: true, server: { statusCode: 503 } }),
+    );
+    expect(enqueued[0]!.server?.statusCode).toBe(503);
+    expect(enqueued[0]!.server?.method).toBe("GET");
+  });
+
+  it("captures a non-Error throwable without throwing", () => {
+    const { enqueued, transport } = recorder();
+    const c = client({ secretKey: "sk" }, transport);
+    expect(() => c.captureException("string failure")).not.toThrow();
+    expect(enqueued[0]!.errorSignature.length).toBeGreaterThan(0);
+  });
+
+  it("scrubs credentials and query strings out of frame urls before transport", () => {
+    const { enqueued, transport } = recorder();
+    const c = client({ secretKey: "sk" }, transport);
+    const err = new Error("x");
+    err.stack = "Error: x\n    at h (https://user:pass@cdn.ex.com/a.js?token=abc123:1:1)";
+    c.captureException(err);
+    const file = enqueued[0]!.errorFrames?.[0]?.file ?? "";
+    expect(file).not.toContain("token=abc123");
+    expect(file).not.toContain("user:pass@");
+    expect(file).toContain("cdn.ex.com/a.js");
+  });
+
+  it("is private-by-default — never carries cookies, auth headers or the concrete path", () => {
+    const { enqueued, transport } = recorder();
+    const c = client({ secretKey: "sk" }, transport);
+    runWithRequestStore(
+      {
+        req: {
+          method: "GET",
+          route: { path: "/u/:id" },
+          path: "/u/42",
+          headers: { cookie: "session=secret-cookie", authorization: "Bearer sk_leak" },
+        },
+        res: { statusCode: 500 },
+      },
+      () => c.captureException(new Error("x")),
+    );
+    const json = JSON.stringify(enqueued[0]);
+    expect(json).not.toContain("secret-cookie");
+    expect(json).not.toContain("sk_leak");
+    expect(json).not.toContain("/u/42");
+    expect(json).toContain("/u/:id");
+  });
+
+  it("does nothing when the client is disabled (fail-quiet gate)", () => {
+    const { enqueued, transport } = recorder();
+    const c = client({ secretKey: "" }, transport); // no key → inert
+    c.captureException(new Error("x"));
+    expect(enqueued).toHaveLength(0);
+  });
+});
+
+describe("FixbackClient beforeSend", () => {
+  it("runs the hook so it can redact the event", () => {
+    const { enqueued, transport } = recorder();
+    const c = new FixbackClient(
+      resolveConfig({
+        secretKey: "sk",
+        beforeSend: (event) => {
+          event.server = { ...event.server, user: "[redacted]" };
+          return event;
+        },
+      }),
+      { transport },
+    );
+    runWithRequestStore(
+      { req: { method: "GET", route: { path: "/x" } }, user: "real-user" },
+      () => c.captureException(new Error("x")),
+    );
+    expect(enqueued[0]!.server?.user).toBe("[redacted]");
+  });
+
+  it("drops the event entirely when the hook returns null", () => {
+    const { enqueued, transport } = recorder();
+    const c = new FixbackClient(resolveConfig({ secretKey: "sk", beforeSend: () => null }), {
+      transport,
+    });
+    c.captureException(new Error("dropped"));
+    expect(enqueued).toHaveLength(0);
+  });
+
+  it("keeps the scrubbed event when the hook throws (a buggy hook never breaks capture)", () => {
+    const { enqueued, transport } = recorder();
+    const c = new FixbackClient(
+      resolveConfig({
+        secretKey: "sk",
+        beforeSend: () => {
+          throw new Error("hook bug");
+        },
+      }),
+      { transport },
+    );
+    expect(() => c.captureException(new Error("survives"))).not.toThrow();
+    expect(enqueued).toHaveLength(1);
+  });
+});
+
+describe("FixbackClient.captureMessage", () => {
+  it("files a handled message with no frames; groups by message text", () => {
+    const { enqueued, transport } = recorder();
+    const c = client({ secretKey: "sk" }, transport);
+    c.captureMessage("cache miss storm", "warning");
+    c.captureMessage("cache miss storm");
+    c.captureMessage("something else");
+    expect(enqueued[0]!.handled).toBe(true);
+    expect(enqueued[0]!.errorFrames).toBeUndefined();
+    expect(enqueued[1]!.errorSignature).toBe(enqueued[0]!.errorSignature);
+    expect(enqueued[2]!.errorSignature).not.toBe(enqueued[0]!.errorSignature);
+  });
+});
+
+describe("module singleton API", () => {
+  afterEach(async () => {
+    await moduleClose();
+  });
+
+  it("init sets the active client, installs process handlers, and delegates captures", () => {
+    const { enqueued, transport } = recorder();
+    const proc = fakeProcess();
+    const active = init({ secretKey: "sk" }, { transport, process: proc, onFatalError: () => {} });
+    expect(getClient()).toBe(active);
+    expect(proc.listeners("uncaughtException")).toHaveLength(1);
+    expect(proc.listeners("unhandledRejection")).toHaveLength(1);
+    moduleCaptureException(new Error("via module"));
+    moduleCaptureMessage("hello");
+    expect(enqueued).toHaveLength(2);
+  });
+
+  it("removes the process handlers and clears the client on close", async () => {
+    const proc = fakeProcess();
+    init({ secretKey: "sk" }, { transport: recorder().transport, process: proc, onFatalError: () => {} });
+    expect(proc.listeners("uncaughtException")).toHaveLength(1);
+    await moduleClose();
+    expect(proc.listeners("uncaughtException")).toHaveLength(0);
+    expect(getClient()).toBeNull();
+  });
+
+  it("closes the previous client and removes its handlers when init is called again", () => {
+    let closed = 0;
+    const first: CaptureTransport = {
+      enqueue: () => {},
+      flush: async () => {},
+      close: async () => {
+        closed += 1;
+      },
+    };
+    const proc1 = fakeProcess();
+    init({ secretKey: "sk" }, { transport: first, process: proc1, onFatalError: () => {} });
+    init({ secretKey: "sk" }, { transport: recorder().transport, process: fakeProcess(), onFatalError: () => {} });
+    expect(closed).toBe(1);
+    expect(proc1.listeners("uncaughtException")).toHaveLength(0);
+  });
+
+  it("no-ops (never throws) when disabled — no handlers, no capture", () => {
+    const proc = fakeProcess();
+    init({ secretKey: "" }, { transport: recorder().transport, process: proc, onFatalError: () => {} });
+    expect(proc.listeners("uncaughtException")).toHaveLength(0);
+    expect(() => moduleCaptureException(new Error("x"))).not.toThrow();
+    expect(() => moduleCaptureMessage("x")).not.toThrow();
+  });
+});