@fixback/node 0.2.0 → 0.3.0

package/src/transport.ts

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

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

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

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