@fixback/sdk-core 0.2.0

package/src/index.ts

@@ -0,0 +1,63 @@
+/**
+ * `@fixback/sdk-core` — the runtime-agnostic core shared by the Fixback capture
+ * SDKs (ADR-0028). Pure fingerprinting, scrubbing, and backoff logic plus the
+ * shared ingest wire shapes — no DOM, no Node built-ins, no rrweb.
+ */
+
+// Fingerprint (ADR-0027) — the cross-surface grouping key.
+export { computeFingerprint, extractTopFrames, hashString, normalize } from "./fingerprint";
+
+// Scrub choke point (spec 0003 §C).
+export {
+  applyDefaultScrub,
+  type BeforeSend,
+  type BeforeSendOptions,
+  redactPii,
+  runBeforeSend,
+  scrubUrl,
+} from "./scrub";
+
+// Backoff (spec 0003 §E/§H) — honouring ingest's 429 / Retry-After.
+export {
+  AutoReportBackoff,
+  type Clock,
+  DEFAULT_RETRY_AFTER_SECONDS,
+  parseRetryAfter,
+} from "./backoff";
+
+// Ingest wire shapes.
+export type {
+  CaptureEnvironment,
+  CapturedFrame,
+  FeedbackSource,
+  Platform,
+  ReportContent,
+} from "./wire";
+
+// Annotation wire types (spec 0003 §D).
+export type {
+  Annotation,
+  ArrowMark,
+  BoxMark,
+  DrawTool,
+  ElementRect,
+  Mark,
+  PenMark,
+  Point,
+  Rect,
+  SelectedElement,
+  TextMark,
+} from "./annotation";
+
+// Breadcrumb / trace wire types (spec #122).
+export type {
+  Breadcrumb,
+  BreadcrumbCategory,
+  BreadcrumbData,
+  BreadcrumbLevel,
+  ConsoleArg,
+  ConsoleArgType,
+  NetworkApi,
+  NetworkOutcome,
+  SourceLocation,
+} from "./breadcrumb";

package/src/scrub.test.ts

@@ -0,0 +1,215 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type { Breadcrumb } from "./breadcrumb";
+import type { ReportContent } from "./wire";
+import { applyDefaultScrub, redactPii, runBeforeSend, scrubUrl } from "./scrub";
+
+describe("scrubUrl", () => {
+  it("strips the query string entirely", () => {
+    expect(scrubUrl("https://acme.app/checkout?token=abc123&next=/pay")).toBe(
+      "https://acme.app/checkout",
+    );
+  });
+
+  it("strips userinfo credentials", () => {
+    expect(scrubUrl("https://user:s3cret@acme.app/data")).toBe(
+      "https://acme.app/data",
+    );
+  });
+
+  it("drops a token-bearing fragment but keeps a plain hash route", () => {
+    expect(scrubUrl("https://acme.app/#access_token=xyz&type=bearer")).toBe(
+      "https://acme.app/",
+    );
+    expect(scrubUrl("https://acme.app/dashboard#/checkout")).toBe(
+      "https://acme.app/dashboard#/checkout",
+    );
+  });
+
+  it("leaves a clean URL and relative paths untouched", () => {
+    expect(scrubUrl("https://acme.app/checkout")).toBe(
+      "https://acme.app/checkout",
+    );
+    expect(scrubUrl("/orders/42")).toBe("/orders/42");
+    expect(scrubUrl("/search?q=shoes")).toBe("/search");
+  });
+
+  it("redacts an email in a path segment (#139)", () => {
+    expect(scrubUrl("https://acme.app/users/jane.doe@acme.app/orders")).toBe(
+      "https://acme.app/users/[redacted-email]/orders",
+    );
+    // Relative paths are swept too.
+    expect(scrubUrl("/u/jane@acme.app")).toBe("/u/[redacted-email]");
+  });
+
+  it("redacts a long digit run in a path segment but keeps short ids (#139)", () => {
+    expect(scrubUrl("https://acme.app/card/4111111111111111/pay")).toBe(
+      "https://acme.app/card/[redacted-number]/pay",
+    );
+    // A short id (a page number, a small resource id) is left alone.
+    expect(scrubUrl("https://acme.app/orders/42")).toBe(
+      "https://acme.app/orders/42",
+    );
+  });
+
+  it("never redacts the authority — a host or port with digits is preserved (#139)", () => {
+    expect(scrubUrl("https://api2.acme.app/data")).toBe(
+      "https://api2.acme.app/data",
+    );
+    // A host that is itself a long digit run is authority, not a path segment.
+    expect(scrubUrl("https://12345678.acme.app/data")).toBe(
+      "https://12345678.acme.app/data",
+    );
+    expect(scrubUrl("https://acme.app:8080/orders/99999999")).toBe(
+      "https://acme.app:8080/orders/[redacted-number]",
+    );
+  });
+
+  it("scrubs both the query string and path PII together (#139)", () => {
+    expect(
+      scrubUrl("https://acme.app/users/jane@acme.app/44444444?token=abc"),
+    ).toBe("https://acme.app/users/[redacted-email]/[redacted-number]");
+  });
+});
+
+describe("redactPii", () => {
+  it("redacts email addresses", () => {
+    expect(redactPii("contact jane.doe@acme.app about it")).toBe(
+      "contact [redacted-email] about it",
+    );
+  });
+
+  it("redacts long digit runs but keeps short ones", () => {
+    expect(redactPii("card 4111111111111111 failed")).toBe(
+      "card [redacted-number] failed",
+    );
+    // A short run (an HTTP status, a small count) is left alone.
+    expect(redactPii("returned 404 in 12ms")).toBe("returned 404 in 12ms");
+  });
+
+  it("redacts bearer / token secrets", () => {
+    expect(redactPii("Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6")).toBe(
+      "Authorization: Bearer [redacted]",
+    );
+  });
+});
+
+const CRUMB_WITH_TOKENS: Breadcrumb = {
+  category: "fetch",
+  message: "GET https://acme.app/me?token=secret sent to jane@acme.app",
+  timestamp: 10,
+  data: { method: "GET", url: "https://acme.app/me?token=secret", status: 200 },
+};
+
+describe("applyDefaultScrub", () => {
+  it("strips the page URL and scrubs crumb URLs + PII, but keeps the comment", () => {
+    const draft: ReportContent = {
+      comment: "email me at jane@acme.app — 4111111111111111",
+      url: "https://acme.app/checkout?token=abc",
+      trace: [CRUMB_WITH_TOKENS],
+    };
+
+    const scrubbed = applyDefaultScrub(draft);
+
+    expect(scrubbed.url).toBe("https://acme.app/checkout");
+    expect(scrubbed.trace?.[0]?.data?.url).toBe("https://acme.app/me");
+    expect(scrubbed.trace?.[0]?.message).toBe(
+      "GET https://acme.app/me sent to [redacted-email]",
+    );
+    // The Reporter's own comment is authored on purpose — never scrubbed.
+    expect(scrubbed.comment).toBe("email me at jane@acme.app — 4111111111111111");
+  });
+
+  it("does not mutate the input draft", () => {
+    const draft: ReportContent = {
+      url: "https://acme.app/x?token=abc",
+      trace: [CRUMB_WITH_TOKENS],
+    };
+    applyDefaultScrub(draft);
+    expect(draft.url).toBe("https://acme.app/x?token=abc");
+    expect(draft.trace?.[0]?.data?.url).toBe("https://acme.app/me?token=secret");
+  });
+});
+
+describe("applyDefaultScrub — structured console args (#122)", () => {
+  const CONSOLE_WITH_PII: Breadcrumb = {
+    category: "console",
+    level: "error",
+    message: "checkout failed",
+    timestamp: 20,
+    args: [
+      { t: "string", v: "user jane@acme.app card 4111111111111111" },
+      {
+        t: "json",
+        v: { note: "call 5551234567", ref: { url: "https://acme.app/x?token=zzz" } },
+      },
+      {
+        t: "error",
+        v: {
+          name: "TypeError",
+          message: "failed for jane@acme.app",
+          stack: "at pay (https://acme.app/pay.js?token=q:4:2)",
+        },
+      },
+    ],
+  };
+
+  it("redacts PII and strips URL query strings inside a console entry's args", () => {
+    const scrubbed = applyDefaultScrub({ trace: [CONSOLE_WITH_PII] });
+    const serialized = JSON.stringify(scrubbed.trace);
+    // Every free-text carrier inside the args is swept — string, json leaves, error.
+    expect(serialized).not.toContain("jane@acme.app");
+    expect(serialized).not.toContain("4111111111111111");
+    expect(serialized).not.toContain("5551234567");
+    expect(serialized).not.toContain("token=zzz");
+    expect(serialized).not.toContain("token=q");
+    expect(serialized).toContain("[redacted-email]");
+  });
+
+  it("does not mutate the input args", () => {
+    const draft = { trace: [CONSOLE_WITH_PII] } as ReportContent;
+    applyDefaultScrub(draft);
+    expect((draft.trace?.[0]?.args?.[0] as { v: string }).v).toContain(
+      "jane@acme.app",
+    );
+  });
+});
+
+describe("runBeforeSend", () => {
+  const draft: ReportContent = {
+    url: "https://acme.app/x?token=abc",
+    trace: [CRUMB_WITH_TOKENS],
+  };
+
+  it("applies the default scrubbers by default", () => {
+    const out = runBeforeSend(draft);
+    expect(out?.url).toBe("https://acme.app/x");
+    expect(out?.trace?.[0]?.data?.url).toBe("https://acme.app/me");
+  });
+
+  it("relaxes the default scrubbers when scrub is false", () => {
+    const out = runBeforeSend(draft, { scrub: false });
+    expect(out?.url).toBe("https://acme.app/x?token=abc");
+  });
+
+  it("lets a hook mutate the (already scrubbed) draft", () => {
+    const hook = vi.fn((d: ReportContent) => ({ ...d, comment: "added" }));
+    const out = runBeforeSend(draft, { hook });
+    // The hook sees the scrubbed draft, and its mutation survives.
+    expect(hook.mock.calls[0]?.[0].url).toBe("https://acme.app/x");
+    expect(out?.comment).toBe("added");
+  });
+
+  it("drops the whole report when the hook returns null", () => {
+    expect(runBeforeSend(draft, { hook: () => null })).toBeNull();
+  });
+
+  it("treats a throwing hook as a no-op, keeping the scrubbed draft", () => {
+    const out = runBeforeSend(draft, {
+      hook: () => {
+        throw new Error("boom");
+      },
+    });
+    expect(out?.url).toBe("https://acme.app/x");
+  });
+});

package/src/scrub.ts

@@ -0,0 +1,226 @@
+/**
+ * The single client-side **scrub choke point** every report passes through
+ * before transport (spec 0003 §C; research `sentry-error-capture-findings.md`
+ * §7.4) — the SDK's `beforeSend` equivalent, shared runtime-agnostically across
+ * surfaces (ADR-0028).
+ *
+ * Masking is the SDK's job, done before anything leaves the process. The
+ * screenshot is masked at capture, and breadcrumbs never record a value or a
+ * body at the source; `runBeforeSend` is the **last** gate over the assembled
+ * report. Its default scrubbers are **on**: they strip credentials, query
+ * strings, and bearer tokens from URLs, and redact obvious PII (emails, long
+ * digit runs, bearer tokens) from crumb and error text. The result is then handed
+ * to an optional per-project hook that can mutate it further or drop the whole
+ * report by returning `null`.
+ *
+ * The hook is **synchronous and network-free** by contract, and both manual
+ * (overlay) and automatic (error-capture) reports run through the very same
+ * choke point. A project relaxes the defaults with `scrub: false`, or reshapes
+ * the draft in its own hook — never a silent raw send.
+ */
+
+import type { Breadcrumb, BreadcrumbData, ConsoleArg } from "./breadcrumb";
+import type { ReportContent } from "./wire";
+
+/** The per-project client scrub hook. Return `null` to drop the whole report. */
+export type BeforeSend = (draft: ReportContent) => ReportContent | null;
+
+/** Options for {@link runBeforeSend}. */
+export interface BeforeSendOptions {
+  /** The per-project hook, run **after** the default scrubbers. */
+  readonly hook?: BeforeSend | null;
+  /** Run the built-in default scrubbers first. Defaults to `true`. */
+  readonly scrub?: boolean;
+}
+
+/** A digit run at least this long is treated as sensitive (phone, card, id). */
+const MIN_DIGIT_RUN = 7;
+const EMAIL_RE = /[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi;
+const DIGIT_RUN_RE = new RegExp(`\\d{${MIN_DIGIT_RUN},}`, "g");
+const BEARER_RE = /\b(bearer|token)\s+[\w.\-~+/]+=*/gi;
+/** An http(s) URL embedded in free text (e.g. a console log line). */
+const URL_IN_TEXT_RE = /\bhttps?:\/\/[^\s"'<>]+/gi;
+
+/**
+ * Redact obvious PII from free text: email addresses, `Bearer <token>` /
+ * `token <value>` pairs, and long digit runs. Conservative by design — it keeps
+ * the shape of the message readable while removing the sensitive spans.
+ */
+export function redactPii(text: string): string {
+  if (typeof text !== "string" || text.length === 0) return text;
+  return text
+    .replace(EMAIL_RE, "[redacted-email]")
+    .replace(BEARER_RE, (_match, keyword: string) => `${keyword} [redacted]`)
+    .replace(DIGIT_RUN_RE, "[redacted-number]");
+}
+
+/**
+ * Redact PII from the **path** portion of a URL (spec #122 §E, ticket #139):
+ * emails and long digit runs in path (or fragment-route) segments — a network
+ * list shows URLs prominently, so an identifier baked into a path
+ * (`/users/jane@acme.app`, `/card/4111111111111111`) must not leak. Deliberately
+ * narrower than {@link redactPii}: no bearer/token rule (URL credentials are
+ * already stripped by {@link scrubUrl}) and it is only ever applied to the
+ * post-authority remainder, so a host or port with digits is never touched.
+ */
+function redactPathPii(pathAndBeyond: string): string {
+  return pathAndBeyond
+    .replace(EMAIL_RE, "[redacted-email]")
+    .replace(DIGIT_RUN_RE, "[redacted-number]");
+}
+
+/**
+ * Strip the sensitive parts of a URL: userinfo credentials
+ * (`scheme://user:pass@host`), the entire query string, a token-bearing
+ * fragment (one that carries `key=value`), and PII (emails, long digit runs) in
+ * the **path segments** (#139). Plain hash routes (`#/checkout`) are kept. Works
+ * on absolute and relative URLs alike, with no dependency and no throw. The host
+ * (authority) is never redacted — only the path and any surviving fragment route.
+ */
+export function scrubUrl(url: string): string {
+  if (typeof url !== "string" || url.length === 0) return url;
+  let out = url;
+  // Drop userinfo credentials: scheme://user:pass@host → scheme://host
+  out = out.replace(/(^[a-z][a-z0-9+.-]*:\/\/)[^/@?#]*@/i, "$1");
+  // Drop the query string entirely (everything from '?' up to a '#').
+  out = out.replace(/\?[^#]*/, "");
+  // Drop a token-bearing fragment (it carries '='); keep plain hash routes.
+  out = out.replace(/#.*$/, (fragment) =>
+    fragment.includes("=") ? "" : fragment,
+  );
+  // Redact PII in the path (and any kept fragment route), never in the authority.
+  // Split off `scheme://authority` (or a protocol-relative `//authority`) so a
+  // host/port that contains digits is preserved; the remainder is the path onward.
+  const absolute = out.match(/^([a-z][a-z0-9+.-]*:\/\/[^/?#]*)([\s\S]*)$/i);
+  if (absolute) return absolute[1] + redactPathPii(absolute[2] ?? "");
+  const protocolRelative = out.match(/^(\/\/[^/?#]*)([\s\S]*)$/);
+  if (protocolRelative) {
+    return protocolRelative[1] + redactPathPii(protocolRelative[2] ?? "");
+  }
+  // A relative URL is all path — redact the whole thing.
+  return redactPathPii(out);
+}
+
+type MutableBreadcrumbData = { -readonly [K in keyof BreadcrumbData]: BreadcrumbData[K] };
+type MutableBreadcrumb = { -readonly [K in keyof Breadcrumb]: Breadcrumb[K] };
+type MutableContent = { -readonly [K in keyof ReportContent]: ReportContent[K] };
+
+function scrubCrumbData(data: BreadcrumbData): BreadcrumbData {
+  const next: MutableBreadcrumbData = { ...data };
+  if (typeof next.url === "string") next.url = scrubUrl(next.url);
+  if (typeof next.from === "string") next.from = scrubUrl(next.from);
+  if (typeof next.to === "string") next.to = scrubUrl(next.to);
+  return next;
+}
+
+/** Scrub a crumb's free-text message: strip URL query strings, then redact PII. */
+function scrubMessage(message: string): string {
+  return redactPii(message.replace(URL_IN_TEXT_RE, (url) => scrubUrl(url)));
+}
+
+/**
+ * Scrub the string leaves of a structured console-arg value (spec #122 §C/§E) — the
+ * value a `json` arg carries. Walks arrays and plain objects, applying the same
+ * URL-strip + PII redaction as a crumb message to every nested string, so a value
+ * logged through `console.*` is swept just like the flattened preview.
+ */
+function scrubArgValue(value: unknown): unknown {
+  if (typeof value === "string") return scrubMessage(value);
+  if (Array.isArray(value)) return value.map(scrubArgValue);
+  if (value && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [key, v] of Object.entries(value as Record<string, unknown>)) {
+      out[key] = scrubArgValue(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Scrub one structured console argument (spec #122 §C): redact PII / strip URL query
+ * strings from a `string` value, from every string leaf of a `json` value, and from an
+ * `error` value's `message` and `stack`. Other tags (`number`/`bool`/`null`) carry no
+ * free text and pass through unchanged.
+ */
+function scrubConsoleArg(arg: ConsoleArg): ConsoleArg {
+  switch (arg.t) {
+    case "string":
+      return typeof arg.v === "string" ? { t: "string", v: scrubMessage(arg.v) } : arg;
+    case "json":
+      return { t: "json", v: scrubArgValue(arg.v) };
+    case "error": {
+      if (!arg.v || typeof arg.v !== "object") return arg;
+      const v = arg.v as { message?: unknown; stack?: unknown };
+      const next: Record<string, unknown> = { ...v };
+      if (typeof next.message === "string") next.message = scrubMessage(next.message);
+      if (typeof next.stack === "string") next.stack = scrubMessage(next.stack);
+      return { t: "error", v: next };
+    }
+    default:
+      return arg;
+  }
+}
+
+function scrubCrumb(crumb: Breadcrumb): Breadcrumb {
+  const next: MutableBreadcrumb = { ...crumb };
+  if (typeof next.message === "string") next.message = scrubMessage(next.message);
+  if (next.data) next.data = scrubCrumbData(next.data);
+  // A rich network crumb (#139) carries its scrubbed URL at the top level — sweep it
+  // again here (idempotent) so the choke point holds whether the URL rode in `data`
+  // (a legacy thin crumb) or top-level, and path-PII redaction is never skipped.
+  if (typeof next.url === "string") next.url = scrubUrl(next.url);
+  // A console crumb's structured args carry the same free text as its preview — sweep
+  // them too, so PII redaction holds whether a value is read from `message` or `args`.
+  if (Array.isArray(next.args)) next.args = next.args.map(scrubConsoleArg);
+  return next;
+}
+
+/**
+ * Apply the built-in default scrubbers to a report draft: strip the page URL,
+ * and scrub every crumb's URLs and redact PII from its text. The Reporter's own
+ * `comment` is intentionally left untouched — it is authored on purpose, not
+ * scraped. The screenshot and input values are masked elsewhere (at capture and
+ * at crumb creation); this is the final URL/PII sweep.
+ */
+export function applyDefaultScrub(draft: ReportContent): ReportContent {
+  const next: MutableContent = { ...draft };
+  if (typeof next.url === "string") next.url = scrubUrl(next.url);
+  if (next.trace && next.trace.length > 0) {
+    next.trace = next.trace.map(scrubCrumb);
+  }
+  // The structured stack frames (#117) carry script URLs — sweep them again here
+  // (idempotent, like the crumb URLs) so the choke point holds regardless of
+  // where the frames were parsed.
+  if (next.errorFrames && next.errorFrames.length > 0) {
+    next.errorFrames = next.errorFrames.map((frame) => ({
+      ...frame,
+      file: scrubUrl(frame.file),
+    }));
+  }
+  return next;
+}
+
+/**
+ * Run the report draft through the client scrub choke point: the default
+ * scrubbers first (unless `scrub` is `false`), then the optional per-project
+ * hook. Returns the scrubbed (and possibly hook-mutated) draft, or `null` when
+ * the hook drops the report. A hook that throws is treated as a no-op — the
+ * already-scrubbed draft is kept, so a buggy hook never breaks the report path
+ * nor leaks unscrubbed data.
+ */
+export function runBeforeSend(
+  draft: ReportContent,
+  options: BeforeSendOptions = {},
+): ReportContent | null {
+  const current =
+    options.scrub === false ? draft : applyDefaultScrub(draft);
+  const hook = options.hook;
+  if (!hook) return current;
+  try {
+    const result = hook(current);
+    return result ?? null;
+  } catch {
+    return current;
+  }
+}

package/src/wire.ts

@@ -0,0 +1,116 @@
+/**
+ * The shared **ingest wire shapes** (ADR-0028) — the value contract a captured
+ * report carries to `POST /api/ingest/feedback`, shared by every Fixback capture
+ * SDK so they all speak the same shape.
+ *
+ * Like the rest of the core these are runtime-agnostic value types: the browser
+ * and (future) backend SDKs both assemble a {@link ReportContent} from what they
+ * captured. Keep them in lock-step with the server: the JSON `payload` part the
+ * ingest controller parses (`apps/api/src/ingest/ingest.controller.ts`) and the
+ * `SubmissionContent` it maps to (`apps/api/src/ingest/reporter-identity.ts`).
+ * Each SDK keeps vendoring its own transport envelope (ticket #47) — the core
+ * carries the pure content shape, not the multipart envelope.
+ */
+
+import type { Annotation } from "./annotation";
+import type { Breadcrumb } from "./breadcrumb";
+
+/**
+ * Where a Feedback came from — a human in the overlay (`reporter`, the default) or
+ * a runtime error the SDK captured (`error`, ADR-0025: covers both an uncaught
+ * crash and a manual capture, on any runtime). Mirrors the server's
+ * `FEEDBACK_SOURCES`; the server derives trust independently and ignores anything
+ * else the client claims.
+ */
+export type FeedbackSource = "reporter" | "error";
+
+/**
+ * The **Platform** a Feedback was captured on (ADR-0025): `browser` (the web SDK),
+ * `node` (the backend SDK), or `expo` (the mobile SDK). Additive — future runtimes
+ * become new values. Mirrors the server's `PLATFORMS` (`@fixback/shared`) by value;
+ * the server stamps it from the ingest route, so it is **not** carried on
+ * {@link ReportContent} (the client never declares its own platform).
+ */
+export type Platform = "browser" | "node" | "expo";
+
+/** The capture environment recorded alongside a report. */
+export interface CaptureEnvironment {
+  readonly viewportWidth?: number;
+  readonly viewportHeight?: number;
+  readonly browser?: string;
+  readonly sdkVersion?: string;
+  /**
+   * The host app's **Release** — the build identifier the builder configured at
+   * `init` (#117, ADR-0024). Uploaded sourcemaps are keyed by it, so the server
+   * can symbolicate this session's stack traces against the exact build that
+   * produced them. Omitted when the Project doesn't set one.
+   */
+  readonly release?: string;
+}
+
+/**
+ * One structured frame of a captured stack trace (#117, ADR-0024), top of stack
+ * first — the server's `errorFrames` wire shape. `file` is the scrubbed script
+ * URL; `line`/`column` are 1-based as browsers report them.
+ */
+export interface CapturedFrame {
+  readonly file: string;
+  readonly line: number;
+  readonly column: number | null;
+  readonly function: string | null;
+}
+
+/**
+ * The JSON content of a feedback submission — the object serialised into the
+ * multipart `payload` part next to the `key` and identity evidence. Every field
+ * is optional: none of it feeds the server's trust decision, so a submission may
+ * carry any subset. `annotation` is the structured `{ element?, region?, marks? }`
+ * (spec §D); the screenshot is a separate binary part, never part of this JSON.
+ */
+export interface ReportContent {
+  readonly comment?: string;
+  /**
+   * The Reporter's self-provided display **name / email** (spec §F), captured in the
+   * invite onboarding step and riding along with every submission so a Member sees
+   * who reported an Issue. **Display only, never a trust signal** — the server derives
+   * the tier from identity evidence alone and ignores these. Omitted when the Reporter
+   * gave none (a Public/anonymous visitor).
+   */
+  readonly reporterName?: string;
+  readonly reporterEmail?: string;
+  readonly url?: string;
+  readonly environment?: CaptureEnvironment;
+  readonly annotation?: Annotation;
+  /** The masked breadcrumb trace buffer that rode on this report (spec §C). */
+  readonly trace?: readonly Breadcrumb[];
+  /**
+   * Provenance (spec §D/§E). Omitted for a manual report — the transport stamps the
+   * `reporter` default on the wire; set to `error` by the SDK's error capture.
+   */
+  readonly source?: FeedbackSource;
+  /**
+   * For `source: error` only — whether the error was **handled** (ADR-0025):
+   * `false` = an uncaught crash, `true` = a manual capture. Set by the backend SDK
+   * (`@fixback/node`), which distinguishes the two; the browser SDK captures only
+   * uncaught errors and leaves it unset.
+   */
+  readonly handled?: boolean;
+  /**
+   * The deploy **Environment** the SDK was configured with (ADR-0025) —
+   * `production` / `staging` / … — distinct from {@link CaptureEnvironment.release}
+   * (a build version). Named apart from `environment` (the capture bag above) to
+   * avoid the collision. Set by the backend SDK; unset by the browser SDK for now.
+   */
+  readonly deployEnvironment?: string;
+  /** For `source: error` only — the SDK's per-session error fingerprint (spec §E). */
+  readonly errorSignature?: string;
+  /** For `source: error` only — the running occurrence count within the session (spec §E). */
+  readonly occurrences?: number;
+  /**
+   * For `source: error` only — the captured error's parsed stack frames (#117,
+   * ADR-0024), top of stack first, capped client-side. The analysis worker
+   * matches them against the release's uploaded sourcemaps to write the Issue's
+   * Code-area pointer.
+   */
+  readonly errorFrames?: readonly CapturedFrame[];
+}