@fixback/sdk 0.5.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/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: error` 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,71 +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 BeforeSend, type CapturedFrame, computeFingerprint, extractTopFrames, hashString, normalize } from "@fixback/sdk-core";
-import type { IdentityInputs } from "./boot";
-import { type BreadcrumbBuffer, type Teardown } from "./breadcrumbs";
-import type { ReporterDisplay } from "./invite";
+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 SubmitInput, type SubmitResult } from "./submit";
+import { type SubmitDeps, type SubmitInput, type SubmitResult } from "./submit";
 export type { Teardown };
-export { computeFingerprint, extractTopFrames, hashString, normalize };
-/** 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;
-/**
- * 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[];
-/** 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 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. */
@@ -95,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;
     /**
@@ -130,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;