@fixback/sdk 0.4.0 → 0.6.0

package/README.md

@@ -2,6 +2,8 @@
 
 The Fixback capture SDK — a tiny, self-isolating on-page feedback widget.
 
+> 📖 **Full documentation: [docs.fixback.dev/sdk/web](https://docs.fixback.dev/sdk/web)** — guides, concepts, and the complete API reference.
+
 `init({ key })` asks Fixback whether a submission would be accepted for your
 publishable key, the visitor's origin, and the Project's Gate, and mounts a
 launcher **only when it would**. Nothing renders when the origin isn't
@@ -58,13 +60,21 @@ global:
 | ---------------- | ------------- | -------------------------- | ----------------------------------------------------------------------- |
 | `key`            | `string`      | —                          | Your Project's **publishable** key (an identifier, not a secret).       |
 | `apiUrl`         | `string`      | `https://api.fixback.dev`  | The Fixback API origin. Override for a self-hosted or local deployment. |
-| `signedIdentity` | `string`      | —                          | A Signed-identity token minted by your server, for trusted reporters.   |
+| `hostIdentity` | `string`      | —                          | A Host-identity token minted by your server, for trusted reporters.   |
 | `reporterId`     | `string`      | —                          | The handle returned when a reporter redeems an invite.                  |
 | `anonymousId`    | `string`      | a persisted per-browser id | A stable first-party id for an anonymous reporter.                      |
 | `target`         | `HTMLElement` | `document.body`            | Where to mount the launcher.                                            |
 | `reduceMotion`   | `boolean`     | `false`                    | Still the launcher's pulse and motion (see [The launcher](#the-launcher)). |
 | `autoCapture`    | `boolean`     | `true`                     | Automatic error capture — file uncaught errors with no prompt (see [Automatic error capture](#automatic-error-capture)). Set `false` to turn it off. |
-| `capture`        | `{ console?: boolean; network?: boolean }` | served per-project | Console / network Trace capture. **On by default** and normally governed per-project from the dashboard; set a stream here to override what the server serves (e.g. `{ network: false }`). A stream you leave unset follows the Project's setting. |
+| `capture`        | `{ console?: boolean; network?: boolean; replay?: boolean }` | served per-project | Console / network / session-replay capture. **On by default** and normally governed per-project from the dashboard; set a stream here to override what the server serves (e.g. `{ network: false }`). A stream you leave unset follows the Project's setting. |
+| `enabled`        | `boolean`     | `true`                     | Master gate. `false` keeps the SDK completely dormant — no boot call, nothing instrumented, nothing mounted. |
+| `release`        | `string`      | —                          | The build identifier captured errors symbolicate against; set it to the value `fixback sourcemaps upload --release` used. |
+| `environment`    | `string`      | —                          | The deploy environment (`production` / `staging` / …) stamped on every capture. |
+| `scrub`          | `boolean`     | `true`                     | The built-in URL / PII scrubbers, run before `beforeSend`. |
+| `beforeSend`     | `(draft) => draft \| null` | —             | The scrub choke point every report passes through. Mutate the draft, or return `null` to drop it. |
+| `beforeBreadcrumb` | `(crumb) => crumb \| null` | —           | Filter or edit each Trace entry at the source; return `null` to drop it. |
+| `trace`          | `{ budgets?, maxAgeMs?, consoleLevels? }` | tuned defaults | Trace buffer **tuning** only. Whether a stream is captured is `capture`'s job. |
+| `replay`         | `ReplayOptions` | masking on               | Session-replay tuning. To turn the recorder off, use `capture: { replay: false }`. |
 
 None of the identity fields is a trust tier — Fixback derives trust on the
 server and never honours a self-declared tier.

package/dist/annotation.d.ts

@@ -1,78 +1,16 @@
 /**
- * The Annotation & vector-marks model (spec 0003 §B/§D).
+ * The Annotation & vector-marks geometry (spec 0003 §B/§D).
  *
- * An Annotation is everything a Reporter marked on the page, as three
- * **composable, optional** layers over one full masked screenshot: the picked
- * `element` (from the element-picker), a drag-captured `region`, and vector
- * `marks` — arrow / box / pen / text. Marks live in the **screenshot's coordinate
- * space** (the full viewport the screenshot is rasterised at), never baked into
- * the PNG: the dashboard composites them at view time (#91).
- *
- * This module is the marks' single home — the pure types and geometry used by the
- * region-capture and draw controllers and by the overlay's Send assembly. Like the
- * rest of the SDK's wire types it is vendored (no `@fixback/shared` import); keep
- * `Annotation` in lock-step with the server's ingest contract (spec §D/§H).
- */
-import type { SelectedElement } from "./report";
-/** A point in screenshot (viewport) coordinate space. */
-export interface Point {
-    readonly x: number;
-    readonly y: number;
-}
-/** A rectangle in screenshot coordinates — the same shape as an element's rect. */
-export interface Rect {
-    readonly x: number;
-    readonly y: number;
-    readonly width: number;
-    readonly height: number;
-}
-/** The draw tools the overlay offers, in toolbar order (spec §B, prototype). */
-export type DrawTool = "arrow" | "box" | "pen" | "text";
-/** Fields shared by every vector mark. */
-interface MarkBase {
-    /** Stroke/fill colour, as a CSS colour string. */
-    readonly color: string;
-}
-/** A directional arrow from `(x0,y0)` to its tip at `(x1,y1)`. */
-export interface ArrowMark extends MarkBase {
-    readonly type: "arrow";
-    readonly x0: number;
-    readonly y0: number;
-    readonly x1: number;
-    readonly y1: number;
-}
-/** A rectangle spanning the drag from `(x0,y0)` to `(x1,y1)`. */
-export interface BoxMark extends MarkBase {
-    readonly type: "box";
-    readonly x0: number;
-    readonly y0: number;
-    readonly x1: number;
-    readonly y1: number;
-}
-/** A freehand polyline through `points` (in order). */
-export interface PenMark extends MarkBase {
-    readonly type: "pen";
-    readonly points: ReadonlyArray<Point>;
-}
-/** A text label anchored at `(x,y)` (its baseline-left, as SVG text). */
-export interface TextMark extends MarkBase {
-    readonly type: "text";
-    readonly x: number;
-    readonly y: number;
-    readonly text: string;
-}
-/** A single vector mark, in screenshot coordinates. */
-export type Mark = ArrowMark | BoxMark | PenMark | TextMark;
-/**
- * The structured Annotation carried on a report's content (spec §D): the three
- * optional layers. Every field is optional — a report may carry any subset or
- * none (a bare comment is a valid Send).
+ * The Annotation **wire types** (`Annotation`, `Mark` and friends, `Point`,
+ * `Rect`, `SelectedElement`) live in `@fixback/sdk-core` (ADR-0028) so every
+ * surface shares one shape; this module re-exports them and holds the browser's
+ * pure geometry and Send-assembly used by the region-capture and draw controllers
+ * and the overlay. Marks live in the **screenshot's coordinate space** (the full
+ * viewport the screenshot is rasterised at), never baked into the PNG: the
+ * dashboard composites them at view time (#91).
  */
-export interface Annotation {
-    readonly element?: SelectedElement;
-    readonly region?: Rect;
-    readonly marks?: ReadonlyArray<Mark>;
-}
+import { type Annotation, type ArrowMark, type BoxMark, type DrawTool, type Mark, type PenMark, type Point, type Rect, type SelectedElement, type TextMark } from "@fixback/sdk-core";
+export type { Annotation, ArrowMark, BoxMark, DrawTool, Mark, PenMark, Point, Rect, TextMark, };
 /**
  * The default mark colour — Signal's danger red, matching the frozen Reporter
  * prototype's draw layer (`docs/design/Fixback Reporter.dc.html`).
@@ -103,4 +41,3 @@ export declare function assembleAnnotation(parts: {
     readonly region?: Rect | null;
     readonly marks?: ReadonlyArray<Mark> | null;
 }): Annotation | undefined;
-export {};

package/dist/capture/extract-dom.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Distilling the browser's **two error events** into the shape the shared capture
+ * state machine keys on.
+ *
+ * These are the only genuinely DOM-shaped part of automatic error capture: an
+ * `ErrorEvent` and an `unhandledrejection` `PromiseRejectionEvent` carry the
+ * throwable in different places and deserve different default type names. Everything
+ * after — fingerprinting, dedup, the burst limiter, the session cap — is
+ * `@fixback/sdk-core`'s (ADR-0028) and shared with the React Native SDK.
+ *
+ * Both are defensive by construction: a value with no usable message returns `null`
+ * rather than filing a Feedback about nothing, which is exactly how a resource-load
+ * `error` event (an `<img>`/`<script>` that 404s — never an uncaught exception) is
+ * kept out.
+ */
+import { type ExtractedError } from "@fixback/sdk-core";
+/**
+ * Distil an uncaught `error` event into a fingerprint-able shape, or `null` when
+ * the event names no error at all (a resource-load failure).
+ */
+export declare function extractFromErrorEvent(event: Event): ExtractedError | null;
+/**
+ * Distil an `unhandledrejection` event into a fingerprint-able shape. A rejection
+ * with a non-Error reason still files — `Promise.reject("nope")` is a real bug —
+ * so unlike {@link extractFromErrorEvent} this never returns `null`.
+ */
+export declare function extractFromRejectionEvent(event: Event): ExtractedError;
+/**
+ * Distil whichever of the two global error events fired. The browser registers one
+ * listener per type, so the event's `type` is an exact discriminator — and the
+ * single `extract` the shared state machine is parameterised over.
+ */
+export declare function extractFromGlobalEvent(event: Event): ExtractedError | null;

package/dist/connect.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The browser **Connect** flow (ADR-0032) — the DOM half of the round trip whose pure
+ * pieces (URL building, message parsing, the code exchange) live in `@fixback/sdk-core`.
+ *
+ * Connect opens the platform's connect page in a **popup**; the page signs the person in
+ * and posts back a one-time code, which the SDK exchanges for a Reporter session. When a
+ * popup is blocked the SDK falls back to a **full-page redirect** to the same URL; the
+ * connect page then returns to the site with the code on the `?fixback=` query
+ * parameter, which the SDK reads on the next load ({@link readReturnCode}) and exchanges.
+ * A Fixback-issued link (e.g. an Invite claim, ticket #250) carries the same parameter,
+ * so arriving on it starts a Connect with no popup at all.
+ */
+/**
+ * The outcome of starting Connect: `code` when a popup handed one back, `redirected`
+ * when a blocked popup sent the page to a full redirect (the page is navigating away and
+ * the code will arrive via {@link readReturnCode} on reload), or `cancelled` when the
+ * person closed the popup without signing in.
+ */
+export type ConnectStart = {
+    readonly kind: "code";
+    readonly code: string;
+} | {
+    readonly kind: "redirected";
+} | {
+    readonly kind: "cancelled";
+};
+/**
+ * Start Connect: open the connect page in a popup and resolve to the one-time code it
+ * posts back, or fall back to a full-page redirect when the popup is blocked. `returnUrl`
+ * is where the person is sent back — validated server-side against the Project's allowed
+ * origins, so a hostile page cannot redirect the code elsewhere.
+ */
+export declare function startConnect(win: Window, params: {
+    connectUrl: string;
+    key: string;
+    returnUrl: string;
+}): Promise<ConnectStart>;
+/**
+ * Read a Connect return code off the current URL's `?fixback=` parameter, or `null`.
+ * The connect page's redirect fallback and Fixback-issued links carry it.
+ */
+export declare function readReturnCode(win: Window): string | null;
+/**
+ * Strip the `?fixback=` parameter from the current URL without a reload, so the
+ * one-time code is not left in the address bar, history, or a shared link.
+ */
+export declare function stripReturnCode(win: Window): void;

package/dist/dom.d.ts

@@ -1,30 +1,18 @@
 /**
- * Small DOM helpers shared across the SDK's report surfaces.
+ * Recognising the SDK's **own** UI in the host page's DOM.
  *
- * The SDK mounts its own host elements into the host page — the launcher and the
- * overlay panel — each tagged with a `data-fixback-*` marker attribute (the
- * element-picker's highlight lives inside the overlay's shadow, so it is covered
- * by the shadow-boundary walk below). These helpers let the picker skip the SDK's
- * own UI and let the screenshot exclude it, so a report never captures or targets
- * Fixback's chrome.
+ * The SDK mounts host elements into the page — the launcher and the overlay panel
+ * — each tagged with a `data-fixback-*` marker attribute (the element-picker's
+ * highlight lives inside the overlay's shadow, so it is covered by the
+ * shadow-boundary walk below). {@link isFixbackNode} is what lets the picker, the
+ * masked UI crumbs, and the replay recorder skip Fixback's own chrome, so a report
+ * never targets or records the tool that filed it.
  */
 /** Marker attributes on the SDK's own host elements in the light DOM. */
 export declare const FIXBACK_HOST_MARKERS: readonly ["data-fixback-root", "data-fixback-overlay"];
-/**
- * Is this node itself one of the SDK's own host elements (the launcher / overlay
- * roots)? A self-only check — the screenshot's clone walk excludes a node's whole
- * subtree once the host is matched, so catching the host is enough to keep all of
- * Fixback's chrome (light DOM and its shadow tree) out of a capture.
- */
-export declare function isFixbackHostElement(node: Node | null | undefined): boolean;
 /**
  * Is this node part of the SDK's own UI? Walks up parents and out through any
  * Shadow DOM boundary (via `getRootNode().host`), so a click inside the overlay's
  * shadow is recognised as Fixback's own — not a host-page element to pick.
  */
 export declare function isFixbackNode(node: EventTarget | null | undefined): boolean;
-/**
- * Remove the SDK's own host elements from a (cloned) subtree, so a captured
- * screenshot never contains the launcher, overlay, or picker highlight.
- */
-export declare function stripFixbackNodes(root: ParentNode): void;

package/dist/element-picker.d.ts

@@ -1,4 +1,4 @@
-import type { SelectedElement } from "./report";
+import type { SelectedElement } from "@fixback/sdk-core";
 /**
  * A stable CSS selector for `el`: its own id when it has one, otherwise a path of
  * tag (with `:nth-of-type` to disambiguate same-tag siblings) climbing until it

package/dist/error-capture.d.ts

@@ -5,13 +5,17 @@
  *
  * Exactly **two capture-phase listeners** (`window` `error` +
  * `unhandledrejection`) turn uncaught exceptions and unhandled rejections into
- * `source: auto` Feedback (stamped `Kind = bug` server-side, ADR-0023) for the current session's Reporter — no
- * native-API monkeypatching, no library. Each firing is deduped by a per-session
- * fingerprint, rate-limited by a token-bucket burst limiter and a per-session cap,
- * scrubbed through the same `beforeSend` choke point as manual reports (§C), and
- * shipped through the same transport (which honours ingest's `429` / `Retry-After`
- * backpressure, ticket #89). `console.error` is **not** promoted — it stays
- * breadcrumb-only Evidence.
+ * `source: error` Feedback (stamped `Kind = bug` server-side, ADR-0023) for the
+ * current session's Reporter — no native-API monkeypatching, no library.
+ * `console.error` is **not** promoted; it stays breadcrumb-only Evidence.
+ *
+ * This module is the **browser binding** over the shared state machine
+ * (`createAutoCapture`, `@fixback/sdk-core`, ADR-0028): it supplies the two
+ * listeners, the DOM event distillation (`./capture/extract-dom`), the browser
+ * report assembly, and the flush hooks (`pagehide` + `visibilitychange`).
+ * Everything between — the per-session fingerprint dedup, the token-bucket burst
+ * limiter, the session cap, the causal error crumb, and the `sentCount` rollback —
+ * is the core's, identical to the React Native SDK's.
  *
  * Per-firing order (research §7.1): **`canSubmit`/Gate → dedup → rate-limit/cap →
  * `beforeSend` scrub → enqueue Feedback**. The Gate is honoured by construction:
@@ -19,100 +23,24 @@
  * never filed where a manual report would be refused, and it inherits the session
  * Reporter's server-derived tier.
  *
- * The whole module is defensive — every handler is wrapped so a Fixback problem
- * (or an error thrown while capturing an error) never surfaces on the host page.
- * The fingerprint/`normalize` shape and the limiter numbers are **starting points**
- * from research (ticket #92), exposed as config — tunable, not frozen.
+ * The whole module is defensive — a Fixback problem (or an error thrown while
+ * capturing an error) never surfaces on the host page.
  */
-import type { IdentityInputs } from "./boot";
-import { type BreadcrumbBuffer, type Teardown } from "./breadcrumbs";
-import type { ReporterDisplay } from "./invite";
-import { type CapturedFrame } from "./report";
+import { type BeforeSend, type BreadcrumbBuffer, DEFAULT_BURST_CAPACITY, DEFAULT_BURST_REFILL_MS, DEFAULT_MAX_DISTINCT_AUTO, type IdentityInputs, type Teardown } from "@fixback/sdk-core";
 import type { ReplaySource } from "./replay";
-import { type BeforeSend } from "./scrub";
-import { type Capture, type CaptureOptions } from "./screenshot";
-import { type SubmitInput, type SubmitResult } from "./submit";
+import { type SubmitDeps, type SubmitInput, type SubmitResult } from "./submit";
 export type { Teardown };
-/** Burst limiter capacity — how many auto-reports may fire back-to-back (§E). */
-export declare const DEFAULT_BURST_CAPACITY = 5;
-/** Burst limiter refill — one token returns every this-many ms (§E). */
-export declare const DEFAULT_BURST_REFILL_MS = 2000;
-/** Per-session ceiling on distinct auto-Feedback; beyond it, only a dropped-count (§E). */
-export declare const DEFAULT_MAX_DISTINCT_AUTO = 20;
-/**
- * Collapse the volatile parts of an error message so a changing string doesn't
- * split one bug: UUIDs, URLs, `0x…` and long hex runs, and long digit runs are
- * replaced with stable placeholders. Short numbers and stable text are kept so
- * genuinely distinct bugs stay distinct. A small, dependency-free regex set —
- * tunable per ticket #92, never a frozen magic set.
- */
-export declare function normalize(value: string): string;
-/**
- * A dependency-free FNV-1a hash rendered in base-36. It only has to be stable and
- * well-distributed within one session (the client key is a flood guard; the server
- * does canonical cross-session clustering), so a non-cryptographic hash is right.
- */
-export declare function hashString(input: string): string;
-/**
- * Extract a compact, stable signature of the top in-app frames of a stack: up to
- * {@link FINGERPRINT_FRAME_LIMIT} frames as `function@basename:line:col`, origin
- * and cache-busting query stripped so a per-deploy asset hash doesn't matter within
- * a session. Returns `""` when there is no usable stack (message-only fallback).
- */
-export declare function extractTopFrames(stack: string | undefined, limit?: number): string;
-/**
- * Extract **structured** frames from a stack for the wire (#117, ADR-0024) —
- * unlike {@link extractTopFrames} (a compact fingerprint signature that drops the
- * origin), these keep the full script URL, because server-side symbolication
- * matches it against uploaded sourcemap paths. URLs are scrubbed (query dropped,
- * PII redacted) before they leave the page; unlocatable frames (`native`,
- * `<anonymous>`, eval) are skipped; the count is capped.
- */
-export declare function extractStructuredFrames(stack: string | undefined, limit?: number): CapturedFrame[];
-/**
- * The per-session fingerprint (research §7.2):
- * `hash(errorType + "|" + normalize(value) + "|" + topFrames)`. Stack frames
- * dominate when present; otherwise it falls back to type + normalized value.
- */
-export declare function computeFingerprint(type: string, value: string, stack?: string): string;
-/** Configuration for {@link TokenBucket}. */
-export interface TokenBucketOptions {
-    readonly capacity: number;
-    readonly refillIntervalMs: number;
-    /** Clock source, injectable for tests. Defaults to `Date.now`. */
-    readonly now?: () => number;
-}
-/**
- * A token bucket: starts full at `capacity`, refills one token every
- * `refillIntervalMs`, and refuses (`take() === false`) when empty. So a fast error
- * loop that dodges dedup with distinct fingerprints still can't machine-gun ingest.
- * The clock is injectable so the window is unit-tested deterministically.
- */
-export declare class TokenBucket {
-    private readonly options;
-    private tokens;
-    private last;
-    private readonly now;
-    constructor(options: TokenBucketOptions);
-    /** Consume a token if one is available (refilling first), else refuse. */
-    take(): boolean;
-}
+export { DEFAULT_BURST_CAPACITY, DEFAULT_BURST_REFILL_MS, DEFAULT_MAX_DISTINCT_AUTO };
 /** Injectable collaborators, defaulted to the real implementations. */
 export interface AutoCaptureDeps {
-    readonly captureView: (options?: CaptureOptions) => Promise<Capture | null>;
-    readonly submitReport: (apiUrl: string, input: SubmitInput, fetchImpl?: typeof fetch) => Promise<SubmitResult>;
+    readonly submitReport: (apiUrl: string, input: SubmitInput, deps?: SubmitDeps) => Promise<SubmitResult>;
 }
 /** Configuration for {@link installErrorCapture}. */
 export interface AutoCaptureConfig {
     readonly apiUrl: string;
     readonly key: string;
-    readonly identity?: IdentityInputs;
-    /**
-     * The Reporter's self-provided display name / email (spec §F). Carried on
-     * auto-captured Feedback too, so a machine-filed crash still names whose session it
-     * was — display only, never a trust signal.
-     */
-    readonly display?: ReporterDisplay;
+    /** Identity evidence, read **live** at capture time (ADR-0032) — the current session token. */
+    readonly getIdentity?: () => IdentityInputs;
     /** The window whose global handlers are installed. Defaults to `window`. */
     readonly win?: Window;
     /** The document used for capture + environment. Defaults to the window's. */
@@ -124,6 +52,8 @@ export interface AutoCaptureConfig {
      * server can symbolicate the captured frames against this build's sourcemaps.
      */
     readonly release?: string;
+    /** The deploy environment (`production` / `staging` / …), stamped on every report. */
+    readonly deployEnvironment?: string;
     /** The shared trace buffer; the failing error is added to it before filing. */
     readonly buffer?: BreadcrumbBuffer | null;
     /**
@@ -159,7 +89,5 @@ export interface AutoCaptureHandle {
 /**
  * Install automatic error capture on a window and return a handle whose `destroy`
  * removes every listener it added (the two global handlers plus the flush hooks).
- * The caller (`init`) installs this only after boot returned `canSubmit`, so the
- * Gate is respected and the auto-error inherits the session Reporter's tier.
  */
 export declare function installErrorCapture(config: AutoCaptureConfig): AutoCaptureHandle;