@fixback/node 0.2.0

package/src/transport.test.ts

@@ -0,0 +1,187 @@
+import { AutoReportBackoff } from "@fixback/sdk-core";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { Transport } from "./transport";
+import type { FetchLike } from "./transport";
+
+interface FakeResponse {
+  readonly ok?: boolean;
+  readonly status?: number;
+  readonly headers?: Record<string, string>;
+  readonly throw?: boolean;
+}
+
+interface RecordedCall {
+  url: string;
+  headers: Record<string, string>;
+  body: { errors: Array<Record<string, unknown>> };
+}
+
+function fakeFetch(responses: FakeResponse[]): { fetchImpl: FetchLike; calls: RecordedCall[] } {
+  const calls: RecordedCall[] = [];
+  const fetchImpl: FetchLike = async (url, init) => {
+    calls.push({
+      url,
+      headers: init.headers ?? {},
+      body: JSON.parse(String(init.body)) as RecordedCall["body"],
+    });
+    const next = responses.shift() ?? { ok: true, status: 201 };
+    if (next.throw) throw new Error("network down");
+    return {
+      ok: next.ok ?? true,
+      status: next.status ?? 201,
+      headers: { get: (name: string) => next.headers?.[name.toLowerCase()] ?? null },
+      json: async () => ({}),
+    };
+  };
+  return { fetchImpl, calls };
+}
+
+const baseConfig = {
+  endpoint: "https://api.test/api/errors",
+  secretKey: "sk_secret",
+  maxBatchSize: 100,
+  maxQueueSize: 1000,
+  flushIntervalMs: 0,
+  timeoutMs: 0,
+};
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe("Transport", () => {
+  it("posts a JSON batch to the errors endpoint with a Bearer secret-key header", async () => {
+    const { fetchImpl, calls } = fakeFetch([{ ok: true, status: 201 }]);
+    const transport = new Transport(baseConfig, { fetchImpl });
+
+    transport.enqueue({ errorSignature: "fp-1", handled: true });
+    transport.enqueue({ errorSignature: "fp-2", handled: false });
+    await transport.flush();
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]!.url).toBe("https://api.test/api/errors");
+    expect(calls[0]!.headers.authorization).toBe("Bearer sk_secret");
+    expect(calls[0]!.headers["content-type"]).toContain("application/json");
+    expect(calls[0]!.body.errors).toHaveLength(2);
+    expect(calls[0]!.body.errors.map((e) => e.errorSignature)).toEqual(["fp-1", "fp-2"]);
+  });
+
+  it("coalesces same-fingerprint errors into one item, summing occurrences", async () => {
+    const { fetchImpl, calls } = fakeFetch([{ ok: true, status: 201 }]);
+    const transport = new Transport(baseConfig, { fetchImpl });
+
+    transport.enqueue({ errorSignature: "loop" });
+    transport.enqueue({ errorSignature: "loop" });
+    transport.enqueue({ errorSignature: "loop", occurrences: 3 });
+    await transport.flush();
+
+    expect(calls[0]!.body.errors).toHaveLength(1);
+    expect(calls[0]!.body.errors[0]!.occurrences).toBe(5);
+  });
+
+  it("keeps the first occurrence's evidence when coalescing", async () => {
+    const { fetchImpl, calls } = fakeFetch([{ ok: true, status: 201 }]);
+    const transport = new Transport(baseConfig, { fetchImpl });
+    transport.enqueue({ errorSignature: "loop", handled: false, server: { route: "/a" } });
+    transport.enqueue({ errorSignature: "loop", handled: false, server: { route: "/b" } });
+    await transport.flush();
+    expect(calls[0]!.body.errors[0]!.server).toEqual({ route: "/a" });
+    expect(calls[0]!.body.errors[0]!.occurrences).toBe(2);
+  });
+
+  it("flushes nothing when the buffer is empty", async () => {
+    const { fetchImpl, calls } = fakeFetch([]);
+    const transport = new Transport(baseConfig, { fetchImpl });
+    await transport.flush();
+    expect(calls).toHaveLength(0);
+  });
+
+  it("opens a backoff window on 429 + Retry-After and sheds captures until it clears", async () => {
+    let nowMs = 0;
+    const backoff = new AutoReportBackoff(() => nowMs);
+    const { fetchImpl, calls } = fakeFetch([
+      { ok: false, status: 429, headers: { "retry-after": "30" } },
+      { ok: true, status: 201 },
+    ]);
+    const transport = new Transport(baseConfig, { fetchImpl, backoff });
+
+    transport.enqueue({ errorSignature: "flood" });
+    await transport.flush(); // 429 → window opens, this batch is shed
+    expect(calls).toHaveLength(1);
+
+    // While the window is open, further captures are dropped without a request.
+    transport.enqueue({ errorSignature: "flood-2" });
+    await transport.flush();
+    expect(calls).toHaveLength(1);
+
+    // Once the window clears, capture resumes.
+    nowMs = 31_000;
+    transport.enqueue({ errorSignature: "after" });
+    await transport.flush();
+    expect(calls).toHaveLength(2);
+    expect(calls[1]!.body.errors[0]!.errorSignature).toBe("after");
+  });
+
+  it("fails quiet when fetch throws — flush never rejects and never throws to the caller", async () => {
+    const { fetchImpl } = fakeFetch([{ throw: true }]);
+    const transport = new Transport(baseConfig, { fetchImpl });
+    transport.enqueue({ errorSignature: "x" });
+    await expect(transport.flush()).resolves.toBeUndefined();
+  });
+
+  it("fails quiet when the endpoint refuses (non-2xx that is not 429)", async () => {
+    const { fetchImpl, calls } = fakeFetch([{ ok: false, status: 500 }]);
+    const transport = new Transport(baseConfig, { fetchImpl });
+    transport.enqueue({ errorSignature: "x" });
+    await expect(transport.flush()).resolves.toBeUndefined();
+    expect(calls).toHaveLength(1);
+  });
+
+  it("auto-flushes once the buffer reaches maxBatchSize", async () => {
+    const { fetchImpl, calls } = fakeFetch([{ ok: true, status: 201 }]);
+    const transport = new Transport({ ...baseConfig, maxBatchSize: 2 }, { fetchImpl });
+    transport.enqueue({ errorSignature: "a" });
+    transport.enqueue({ errorSignature: "b" }); // reaches the cap → auto-flush fires
+    await transport.flush(); // await the in-flight drain
+    expect(calls).toHaveLength(1);
+    expect(calls[0]!.body.errors).toHaveLength(2);
+  });
+
+  it("bounds the buffer at maxQueueSize under a sustained flood", async () => {
+    const { fetchImpl, calls } = fakeFetch([{ ok: true, status: 201 }]);
+    // flushIntervalMs 0 so nothing auto-sends; maxBatchSize high so the cap, not the
+    // batch trigger, is what bounds the buffer.
+    const transport = new Transport(
+      { ...baseConfig, maxQueueSize: 3, maxBatchSize: 1000 },
+      { fetchImpl },
+    );
+    for (let i = 0; i < 50; i++) transport.enqueue({ errorSignature: `fp-${i}` });
+    await transport.flush();
+    // At most maxQueueSize distinct items were retained.
+    expect(calls[0]!.body.errors.length).toBeLessThanOrEqual(3);
+  });
+
+  it("auto-flushes on the flush interval, on an unref'd timer", async () => {
+    vi.useFakeTimers();
+    const { fetchImpl, calls } = fakeFetch([{ ok: true, status: 201 }]);
+    const transport = new Transport({ ...baseConfig, flushIntervalMs: 5000 }, { fetchImpl });
+    transport.enqueue({ errorSignature: "timed" });
+    expect(calls).toHaveLength(0);
+    await vi.advanceTimersByTimeAsync(5000);
+    expect(calls).toHaveLength(1);
+    await transport.close();
+  });
+
+  it("close() drains the remaining buffer and stops the timer", async () => {
+    vi.useFakeTimers();
+    const { fetchImpl, calls } = fakeFetch([{ ok: true, status: 201 }]);
+    const transport = new Transport({ ...baseConfig, flushIntervalMs: 5000 }, { fetchImpl });
+    transport.enqueue({ errorSignature: "z" });
+    await transport.close();
+    expect(calls).toHaveLength(1);
+    // After close the timer no longer fires.
+    await vi.advanceTimersByTimeAsync(20_000);
+    expect(calls).toHaveLength(1);
+  });
+});

package/src/transport.ts

@@ -0,0 +1,227 @@
+/**
+ * The **batched secret-key transport** (ADR-0026): the SDK buffers captured errors
+ * and flushes them to `POST /api/errors` as a JSON batch authenticated with the
+ * Project secret key as an `Authorization: Bearer` token.
+ *
+ * - **Batched:** a server emits many errors, so they buffer and flush together
+ *   (on the batch cap, on an interval, on demand, and on `close`).
+ * - **Coalesced:** repeats of one fingerprint in a flush window fold into a single
+ *   item with a summed occurrence count — the client half of the crash-loop defence
+ *   (the server folds across flushes, ADR-0027).
+ * - **Backed off:** a `429` opens the shared-core {@link AutoReportBackoff} window
+ *   (honouring `Retry-After`); while it is open captures are shed without a request.
+ * - **Fail-quiet (story 34):** an unreachable, timing-out, or refusing endpoint never
+ *   throws to the host and never grows the buffer without bound (`maxQueueSize`).
+ */
+
+import { AutoReportBackoff, type CapturedFrame } from "@fixback/sdk-core";
+
+import type { ServerContext, ServerErrorPayload } from "./wire";
+
+/** The response slice the transport reads. Satisfied by the global `fetch` Response. */
+export interface FetchResponseLike {
+  readonly ok: boolean;
+  readonly status: number;
+  readonly headers?: { get(name: string): string | null } | null;
+}
+
+/** The request init the transport sends — a subset of the standard `RequestInit`. */
+export interface FetchRequestInit {
+  readonly method: string;
+  readonly headers?: Record<string, string>;
+  readonly body?: string;
+}
+
+/** A `fetch`-shaped function, injectable for tests. */
+export type FetchLike = (url: string, init: FetchRequestInit) => Promise<FetchResponseLike>;
+
+/**
+ * The narrow transport surface the client depends on — buffer one error, flush, and
+ * close. {@link Transport} is the real implementation; tests inject a fake recorder.
+ */
+export interface CaptureTransport {
+  enqueue(payload: ServerErrorPayload): void;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+}
+
+/** The transport's configuration (a slice of the resolved SDK config). */
+export interface TransportConfig {
+  readonly endpoint: string;
+  readonly secretKey: string;
+  readonly maxBatchSize: number;
+  readonly maxQueueSize: number;
+  readonly flushIntervalMs: number;
+  readonly timeoutMs: number;
+}
+
+/** Injectable collaborators, defaulted to the real implementations. */
+export interface TransportDeps {
+  readonly fetchImpl?: FetchLike;
+  readonly backoff?: AutoReportBackoff;
+}
+
+/** A buffered error with a mutable occurrence tally (bumped on coalesce). */
+interface BufferedError {
+  errorSignature: string;
+  handled?: boolean;
+  environment?: string;
+  release?: string;
+  occurrences?: number;
+  errorFrames?: readonly CapturedFrame[];
+  server?: ServerContext;
+}
+
+/** The global `fetch`, adapted to {@link FetchLike}, or `undefined` when unavailable. */
+function resolveFetch(): FetchLike | undefined {
+  const g = globalThis as unknown as {
+    fetch?: (input: string, init?: unknown) => Promise<unknown>;
+  };
+  if (typeof g.fetch !== "function") return undefined;
+  const bound = g.fetch.bind(globalThis);
+  return (url, init) => bound(url, init) as Promise<FetchResponseLike>;
+}
+
+/** Read a response header defensively — `null` when unavailable or on any throw. */
+function safeHeader(response: FetchResponseLike, name: string): string | null {
+  try {
+    return response.headers?.get?.(name) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export class Transport implements CaptureTransport {
+  private readonly config: TransportConfig;
+  private readonly fetchImpl: FetchLike | undefined;
+  private readonly backoff: AutoReportBackoff;
+  /** Insertion-ordered buffer keyed by fingerprint, so a coalesce is O(1). */
+  private readonly buffer = new Map<string, BufferedError>();
+  private timer: ReturnType<typeof setInterval> | undefined;
+  private inFlight: Promise<void> | null = null;
+  private closed = false;
+
+  constructor(config: TransportConfig, deps: TransportDeps = {}) {
+    this.config = config;
+    this.fetchImpl = deps.fetchImpl ?? resolveFetch();
+    this.backoff = deps.backoff ?? new AutoReportBackoff();
+    if (config.flushIntervalMs > 0) {
+      this.timer = setInterval(() => {
+        void this.flush();
+      }, config.flushIntervalMs);
+      // Never keep the process alive for the flush timer.
+      const handle = this.timer as { unref?: () => void };
+      if (typeof handle.unref === "function") handle.unref();
+    }
+  }
+
+  /**
+   * Buffer one captured error for the next flush. Coalesces onto an existing
+   * fingerprint (summing occurrences, keeping the first occurrence's evidence);
+   * drops the capture while the backoff window is open or the buffer is full; and
+   * triggers an immediate flush once the batch cap is reached.
+   */
+  enqueue(payload: ServerErrorPayload): void {
+    const signature = payload.errorSignature;
+    if (this.closed || typeof signature !== "string" || signature.length === 0) return;
+    // Shed while the 429 window is open — the client half of the flood defence.
+    if (this.backoff.isPaused()) return;
+
+    const existing = this.buffer.get(signature);
+    if (existing) {
+      existing.occurrences = (existing.occurrences ?? 1) + (payload.occurrences ?? 1);
+    } else {
+      if (this.buffer.size >= this.config.maxQueueSize) return; // bounded — drop the newest
+      this.buffer.set(signature, { ...payload });
+    }
+
+    if (this.buffer.size >= this.config.maxBatchSize) void this.flush();
+  }
+
+  /** Flush the buffer to ingest. Never rejects (fail-quiet). Coalesces concurrent calls. */
+  flush(): Promise<void> {
+    if (this.inFlight) return this.inFlight;
+    this.inFlight = this.drain().finally(() => {
+      this.inFlight = null;
+    });
+    return this.inFlight;
+  }
+
+  /** Stop the flush timer and drain what remains. Safe to call more than once. */
+  async close(): Promise<void> {
+    this.closed = true;
+    if (this.timer !== undefined) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+    await this.flush();
+  }
+
+  /** Send batches until the buffer drains, the window opens, or a send fails. */
+  private async drain(): Promise<void> {
+    while (this.buffer.size > 0) {
+      if (this.backoff.isPaused()) return;
+      const ok = await this.send(this.takeBatch());
+      if (!ok) return; // 429 (held) or unreachable/refused — stop; the rest waits or is dropped
+    }
+  }
+
+  /** Remove and return up to `maxBatchSize` buffered errors, oldest first. */
+  private takeBatch(): BufferedError[] {
+    const batch: BufferedError[] = [];
+    for (const [signature, entry] of this.buffer) {
+      batch.push(entry);
+      this.buffer.delete(signature);
+      if (batch.length >= this.config.maxBatchSize) break;
+    }
+    return batch;
+  }
+
+  /**
+   * POST one batch. Returns `true` on acceptance; on a `429` it opens the backoff
+   * window from `Retry-After` and returns `false`; any other failure (unreachable,
+   * timeout, refusal) returns `false` without throwing.
+   */
+  private async send(batch: readonly ServerErrorPayload[]): Promise<boolean> {
+    const doFetch = this.fetchImpl;
+    if (!doFetch || batch.length === 0) return false;
+
+    let response: FetchResponseLike;
+    try {
+      response = await this.withTimeout(
+        doFetch(this.config.endpoint, {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${this.config.secretKey}`,
+            "content-type": "application/json",
+          },
+          body: JSON.stringify({ errors: batch }),
+        }),
+      );
+    } catch {
+      return false; // unreachable or timed out — fail quiet
+    }
+
+    if (!response.ok) {
+      if (response.status === 429) {
+        this.backoff.hold(safeHeader(response, "retry-after"));
+        return false;
+      }
+      return false; // refused — fail quiet
+    }
+    return true;
+  }
+
+  /** Race a request against the configured timeout (`0` disables it). */
+  private withTimeout(request: Promise<FetchResponseLike>): Promise<FetchResponseLike> {
+    const ms = this.config.timeoutMs;
+    if (ms <= 0) return request;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const timeout = new Promise<never>((_, reject) => {
+      timer = setTimeout(() => reject(new Error("fixback: request timed out")), ms);
+    });
+    return Promise.race([request, timeout]).finally(() => {
+      if (timer !== undefined) clearTimeout(timer);
+    });
+  }
+}

package/src/version.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from "vitest";
+
+import pkg from "../package.json";
+import { NODE_SDK_VERSION } from "./version";
+
+describe("NODE_SDK_VERSION", () => {
+  it("matches package.json's version (synced by scripts/sync-sdk-version.mjs)", () => {
+    expect(NODE_SDK_VERSION).toBe(pkg.version);
+  });
+});

package/src/version.ts

@@ -0,0 +1,13 @@
+/**
+ * The backend SDK's own version string, reported to ingest as
+ * `environment.sdkVersion`. Kept as an inlined constant rather than a runtime
+ * `package.json` import so the published build stays self-contained (the same
+ * posture as `packages/sdk/src/version.ts` and `packages/expo/src/version.ts`).
+ *
+ * It must equal `package.json`'s `version`. Two things keep it there: the
+ * Changesets `version` step syncs it automatically (`scripts/sync-sdk-version.mjs`,
+ * wired into `version-packages`), and `version.test.ts` fails the build if the two
+ * ever drift. Do not hand-edit this line to a value other than `package.json`'s
+ * version.
+ */
+export const NODE_SDK_VERSION = "0.2.0";

package/src/wire.ts

@@ -0,0 +1,116 @@
+/**
+ * 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;
+}