@fixback/sdk 0.5.0 → 0.6.0

package/dist/overlay.d.ts

@@ -1,28 +1,40 @@
-import { type BeforeSend } from "@fixback/sdk-core";
-import type { IdentityInputs, ProjectGate, ReporterTier } from "./boot";
-import type { Breadcrumb } from "./breadcrumbs";
-import type { ReporterDisplay } from "./invite";
-import { type ElementPicker, type ElementPickerOptions } from "./element-picker";
+/**
+ * The report **overlay** — the on-page panel a Reporter files a report from, built
+ * to the frozen Signal Reporter prototype (`docs/design/Fixback Reporter.dc.html`).
+ *
+ * This module is the wiring: it mounts the view lazily inside its own Shadow DOM
+ * (isolated from the host page, and marked so the replay recorder and
+ * element-picker skip it), opens on the launcher's `fixback:launch` seam, and joins
+ * the three parts that do the work:
+ *
+ * - `./overlay/view` builds the markup and hands back typed refs;
+ * - `./overlay/marking` runs the three composable marking layers (element-pick,
+ *   region-capture, draw) and owns what has been marked;
+ * - `./overlay/send` assembles, scrubs, and submits.
+ *
+ * What is left here is the panel's own state: open/closed, the compose → sending →
+ * sent phase, the status line, and the confirmation's auto-close. The marks are
+ * viewport-space vectors composited at view time (spec §D), never baked into an
+ * image; the still they annotate is a frame of the buffered rrweb window
+ * (reconstructed downstream since ADR-0027), so the SDK rasterises nothing.
+ */
+import type { BeforeSend, IdentityInputs, ProjectGate, ReporterIdentity } from "@fixback/sdk-core";
+import { type StartPickerFn } from "./overlay/marking";
+import { type BreadcrumbSource, type SubmitReportFn } from "./overlay/send";
 import type { ReplaySource } from "./replay";
-import { type SubmitInput, type SubmitResult } from "./submit";
-/** Marks the overlay's host element in the light DOM (skipped by capture/picker). */
-export declare const OVERLAY_ATTRIBUTE = "data-fixback-overlay";
-type SubmitReportFn = (apiUrl: string, input: SubmitInput, fetchImpl?: typeof fetch) => Promise<SubmitResult>;
-type StartPickerFn = (options: ElementPickerOptions) => ElementPicker;
+export { OVERLAY_ATTRIBUTE } from "./overlay/dom";
+export type { BreadcrumbSource } from "./overlay/send";
 /** Injectable collaborators, defaulted to the real implementations. */
 export interface OverlayDeps {
     readonly submitReport: SubmitReportFn;
     readonly startElementPicker: StartPickerFn;
 }
-/** A read-only view of the trace buffer the overlay attaches to a report. */
-export interface BreadcrumbSource {
-    snapshot(): readonly Breadcrumb[];
-}
 /** Configuration for {@link createOverlay}. */
 export interface OverlayConfig {
     readonly apiUrl: string;
     readonly key: string;
-    readonly identity?: IdentityInputs;
+    /** Identity evidence, read **live** at send time (ADR-0032) — see {@link MountContext}. */
+    readonly getIdentity?: () => IdentityInputs;
     /**
      * The Project's Gate, forwarded verbatim from the boot answer. Reserved for
      * Gate-aware launcher / redemption behaviour (spec §A/§F); the overlay itself
@@ -30,21 +42,20 @@ export interface OverlayConfig {
      */
     readonly gate?: ProjectGate;
     /**
-     * The Reporter's **server-derived** trust tier from the boot answer, or `null`
-     * when a presented identity was refused. Rendered as a **display-only** chip in
-     * the overlay header (spec §G) — never a trust signal, never read for a decision,
-     * and never sent back to the server. When `null`/absent no tier is asserted.
+     * The current Reporter identity — anonymous, or a connected Account with its
+     * server-derived tier — rendered in the header's identity chip (ADR-0032). Updated in
+     * place via {@link OverlayController.setIdentity} after a Connect or sign-out.
      */
-    readonly tier?: ReporterTier | null;
+    readonly reporterIdentity: ReporterIdentity;
+    /** Start a Connect from the chip's **Sign in** (ADR-0032). */
+    readonly onSignIn: () => void;
+    /** Clear the Reporter session from the chip's **Sign out** (ADR-0032). */
+    readonly onSignOut: () => void;
     readonly sdkVersion?: string;
     /** The host app's Release (#117, ADR-0024), validated by `init`; rides in the environment. */
     readonly release?: string;
-    /**
-     * The Reporter's self-provided display name / email (spec §F), when the SDK holds
-     * them (from a redemption in this session or a prior one). They ride along with the
-     * report so a Member sees who filed it — display only, never a trust signal.
-     */
-    readonly display?: ReporterDisplay;
+    /** The deploy environment (`production` / `staging` / …), stamped on every report. */
+    readonly deployEnvironment?: string;
     /** Where to mount the overlay host. Defaults to `document.body`. */
     readonly target?: HTMLElement;
     readonly doc?: Document;
@@ -64,21 +75,9 @@ export interface OverlayController {
     open(): void;
     close(): void;
     destroy(): void;
+    /** Update the identity chip in place after a Connect or sign-out (ADR-0032). */
+    setIdentity(identity: ReporterIdentity): void;
     readonly isOpen: boolean;
 }
-/**
- * Create the report overlay — the on-page panel a Reporter files a report from,
- * built to the frozen Signal Reporter prototype (`docs/design/Fixback Reporter.dc.html`).
- * It mounts lazily inside its own Shadow DOM (isolated from the host page, and
- * marked so the replay recorder and element-picker skip it), opens on the launcher's
- * `fixback:launch` seam, and offers three **composable, optional** marking layers
- * over the current view (spec §B): **element-pick**, **region-capture** (drag), and
- * **draw** (arrow / box / pen / text, with undo / cancel / attach). The marks are
- * viewport-space vectors composited at view time (spec §D), never baked into an
- * image; the still they annotate is a frame of the buffered rrweb window
- * (reconstructed downstream since ADR-0027), so the SDK rasterises nothing. On Send
- * it assembles the structured Annotation (`{ element?, region?, marks? }`) and
- * submits to ingest — showing a confirmation on success and failing quietly otherwise.
- */
+/** Create the report overlay. See the module doc. */
 export declare function createOverlay(config: OverlayConfig): OverlayController;
-export {};

package/dist/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/report.d.ts

@@ -11,18 +11,10 @@
  * `payload` accepted by `POST /api/ingest/feedback`
  * (`apps/api/src/ingest/ingest.controller.ts`).
  */
-import { type CaptureEnvironment, type CapturedFrame, type ElementRect, type FeedbackSource, type ReportContent, type SelectedElement } from "@fixback/sdk-core";
+import { type Breadcrumb, type CaptureEnvironment, type CapturedFrame, type ElementRect, type FeedbackSource, normaliseRelease, type ReportContent, type SelectedElement } from "@fixback/sdk-core";
 import { type Mark, type Rect } from "./annotation";
-import type { Breadcrumb } from "./breadcrumbs";
 export type { CaptureEnvironment, CapturedFrame, ElementRect, FeedbackSource, ReportContent, SelectedElement, };
-/**
- * Validate + trim a builder-supplied release (#117, ADR-0024), mirroring the
- * server's rules by value: 1–100 visible characters, no whitespace, control
- * characters, or path separators, and not a reserved name. Returns `undefined`
- * for an invalid value — the SDK drops it (with a warning at `init`) rather than
- * shipping a value the server would discard.
- */
-export declare function normaliseRelease(value: string): string | undefined;
+export { normaliseRelease };
 /**
  * What the overlay hands to {@link assembleContent} when the Reporter sends. The
  * three marking layers arrive flat (`element` / `region` / `marks`); `assembleContent`
@@ -36,9 +28,13 @@ export interface ReportDraft {
     readonly url?: string;
     readonly environment?: CaptureEnvironment;
     readonly trace?: readonly Breadcrumb[];
-    /** The Reporter's self-provided display name / email (spec §F), if the SDK holds them. */
-    readonly reporterName?: string;
-    readonly reporterEmail?: string;
+    /**
+     * The deploy **Environment** the SDK was configured with (ADR-0025) —
+     * `production` / `staging` / … — distinct from the build `release` in
+     * {@link CaptureEnvironment}. Named apart from `environment` (the capture bag)
+     * to avoid the collision, exactly as the wire does.
+     */
+    readonly deployEnvironment?: string;
 }
 /**
  * Read the capture environment off a window: the viewport size, the browser's

package/dist/reporter-session-store.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The browser's **Reporter session** store (ADR-0032) — the storage binding only.
+ *
+ * After a Connect the SDK holds a compact signed token per origin and forwards it on
+ * every boot; the boot answer hands back a refreshed one (30-day sliding). The token
+ * lives in `localStorage` under a key **scoped by publishable key** (so two Projects on
+ * one origin keep separate sessions), the key format shared with every SDK
+ * (`@fixback/sdk-core`). Persistence is best-effort: a blocked or absent `localStorage`
+ * (private mode) simply means no stored session — the SDK falls back to anonymous
+ * rather than throwing, so it never disturbs the host page.
+ */
+/** Read the stored Reporter session token for this Project, or `null`. */
+export declare function readReporterSession(publishableKey: string): string | null;
+/** Persist a Reporter session token for this Project. Best-effort. */
+export declare function writeReporterSession(publishableKey: string, token: string): void;
+/** Clear the stored Reporter session token for this Project (sign out). Best-effort. */
+export declare function clearReporterSession(publishableKey: string): void;

package/dist/session.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The **session flow** behind `init` (ADR-0032): recognise the Reporter through the
+ * Reporter session token it holds, ask ingest what it may do, and mount only when a
+ * submission would be accepted — while exposing `signIn` / `signOut` / `identity`.
+ *
+ * On boot the SDK forwards its stored **Reporter session** token (from a prior Connect,
+ * scoped per publishable key) and swaps in the refreshed one boot hands back (30-day
+ * sliding). It also detects a one-time code arriving on the `?fixback=` query parameter
+ * — the connect page's redirect fallback, and Fixback-issued links (ticket #250) — and
+ * exchanges it for a session before booting.
+ *
+ * **Connect** binds an Account to the site: `signIn` opens the platform's connect page
+ * (popup, or a full redirect when it is blocked), exchanges the returned code, and
+ * re-boots — so an Open-gated visitor's launcher gains the Account, and a gated
+ * Project's launcher **mounts** once the Account is eligible. The launcher mounts only
+ * when boot returns `canSubmit`, so a gated Project shows nothing to a signed-out
+ * visitor. Everything is wrapped so a Fixback problem resolves to a no-op and never
+ * surfaces on the host page.
+ */
+import type { FixbackInstance, InitOptions } from "./init";
+/** A running SDK that mounted nothing — every failure path resolves to this. */
+export declare const NOOP_INSTANCE: FixbackInstance;
+/**
+ * Run one session: recognise the Reporter, boot, and mount when accepted — exchanging a
+ * `?fixback=` return code first, and exposing Connect (`signIn` / `signOut` / `identity`).
+ */
+export declare function runSession(options: InitOptions, apiUrl: string): Promise<FixbackInstance>;

package/dist/submit.d.ts

@@ -1,6 +1,36 @@
-import { AutoReportBackoff } from "@fixback/sdk-core";
-import type { IdentityInputs, ReporterTier } from "./boot";
-import type { ReportContent } from "./report";
+/**
+ * The multipart feedback submission — the transport half of the capture loop.
+ *
+ * `POST /api/ingest/feedback` (spec MVP §C; tickets #50/#53) is a multipart
+ * request: a single text part `payload` carrying the JSON (publishable key +
+ * identity evidence + content) and an optional binary `replay` part — the buffered
+ * rrweb window (ADR-0024), from which the annotated still is reconstructed downstream
+ * (ADR-0027), so the browser SDK rasterises and sends no screenshot. The content-type
+ * header is deliberately not set, so the runtime writes the `multipart/form-data`
+ * boundary itself. Like `requestBoot`, this never throws: an unreachable Fixback or a
+ * refusal is a quiet result, so a Fixback problem never breaks the host page.
+ *
+ * The endpoint, the identity compaction, and the backpressure window are the shared
+ * core's (ADR-0028); what lives here is the browser envelope — a `FormData` with a
+ * `Blob` replay part.
+ *
+ * The `payload` carries the full report content — the structured `annotation`
+ * (element + region + marks, kept vector), the masked `trace` buffer, and the
+ * `source` provenance (spec §D). Automatic reports (`source: error`) additionally
+ * honour ingest's `429` + `Retry-After` backpressure: while the hold window is open
+ * they are dropped without touching the network. Manual reports are never gated
+ * (spec §E/§H).
+ */
+import { AutoReportBackoff, feedbackEndpoint, type FetchLike, type IdentityInputs, type ReportContent, type ReporterTier } from "@fixback/sdk-core";
+export { feedbackEndpoint };
+/**
+ * How long a submission may stay in flight before it is reported as
+ * `unreachable`. A hung connection — a captive portal, a proxy that never
+ * answers — would otherwise leave a report pending forever, and with it the
+ * overlay's "Sending…" state. The abandoned request keeps running in the
+ * background harmlessly. Matches `@fixback/expo`'s and `@fixback/node`'s window.
+ */
+export declare const DEFAULT_SUBMIT_TIMEOUT_MS = 30000;
 /** What ingest returns for an accepted submission (vendored server shape). */
 export interface RecordedFeedback {
     readonly feedbackId: string;
@@ -41,8 +71,21 @@ export type SubmitResult = {
     readonly reason: "backpressure";
     readonly retryAfterSeconds: number;
 };
-/** Join an API base URL with the feedback path, tolerating a trailing slash. */
-export declare function feedbackEndpoint(apiUrl: string): string;
+/**
+ * Injectable transport collaborators, defaulted to the real implementations — the
+ * same deps-object shape `requestBoot` and `@fixback/expo`'s `submitReport` take.
+ */
+export interface SubmitDeps {
+    /** The `fetch` to call. Defaults to the page's global. */
+    readonly fetch?: FetchLike;
+    /**
+     * The shared `source: error` backpressure window. Defaults to the page-wide
+     * instance; tests inject their own to isolate the clock.
+     */
+    readonly backoff?: AutoReportBackoff;
+    /** Overall request timeout in ms; `0` disables. Defaults to {@link DEFAULT_SUBMIT_TIMEOUT_MS}. */
+    readonly timeoutMs?: number;
+}
 /**
  * Submit a report to ingest. Assembles the `payload` JSON (key + identity +
  * content, with an explicit `source` stamped) and the optional `replay` window
@@ -53,7 +96,7 @@ export declare function feedbackEndpoint(apiUrl: string): string;
  * is open the report is dropped without a request (spec §E/§H). Ingest's `429` +
  * `Retry-After` opens/extends that window (default 60 s if the header is absent).
  * Manual reports (`source: reporter`, the default) never consult the window and a
- * non-2xx for them stays a plain refusal. The `fetchImpl` and `backoff` seams exist
- * purely so the call is testable.
+ * non-2xx for them stays a plain refusal. The `deps` seams exist purely so the call
+ * is testable.
  */
-export declare function submitReport(apiUrl: string, input: SubmitInput, fetchImpl?: typeof fetch, backoff?: AutoReportBackoff): Promise<SubmitResult>;
+export declare function submitReport(apiUrl: string, input: SubmitInput, deps?: SubmitDeps): Promise<SubmitResult>;

package/dist/trace/instrument/beacon.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The `navigator.sendBeacon` network hook (spec #122 §D, ticket #139).
+ *
+ * `sendBeacon` is fire-and-forget with a **synchronous boolean** return — `true`
+ * when the user agent queued the beacon, `false` when it declined — so wrapping
+ * must return that boolean unchanged: the original is called first and its result
+ * both classifies the crumb (`ok` / `network-error`) and is returned to the caller.
+ * Only the URL and the trivially-known request size are recorded (no response
+ * exists to read); capture failure is swallowed and the boolean still returned, and
+ * if the original itself throws we record best-effort and re-throw so the contract
+ * is preserved exactly.
+ */
+import { type BreadcrumbBuffer, type Teardown } from "@fixback/sdk-core";
+import { type InstrumentWindow } from "./window";
+/** Wrap `navigator.sendBeacon` to record a network crumb per beacon. See the module doc. */
+export declare function instrumentBeacon(buffer: BreadcrumbBuffer, win: InstrumentWindow, ignoreUrl: (url: string) => boolean, now: () => number): Teardown;

package/dist/trace/instrument/console.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The browser's binding for the shared **console** wrapper.
+ *
+ * `instrumentConsole` itself is `@fixback/sdk-core`'s (ADR-0028) — the browser and
+ * React Native wrap `console` identically, and the wrapper takes its target as an
+ * argument rather than reading a global. This module exists so `./trace/instrument`
+ * names every stream it installs, and so the page's `console` is resolved in one
+ * place.
+ */
+export { instrumentConsole, type ConsoleLike } from "@fixback/sdk-core";
+export { globalConsole } from "./window";

package/dist/trace/instrument/fetch.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The `fetch` network hook (spec #122 §D, ticket #139).
+ *
+ * Wraps the page's `fetch` to record a rich network crumb on settlement: method,
+ * scrubbed URL, status + statusText, a `performance.now()` duration, request size
+ * (only when the body is trivially sized), response size (from the
+ * `content-length` header only), content type, and a failure outcome. The
+ * **original** outcome is returned untouched — the response is passed through
+ * **without its body being read** (only two metadata headers are inspected), and a
+ * rejection is re-thrown so the caller's `unhandledrejection` semantics are
+ * preserved.
+ */
+import { type BreadcrumbBuffer, type Teardown } from "@fixback/sdk-core";
+import { type InstrumentWindow } from "./window";
+/** Wrap `fetch` to record a rich network crumb on settlement. See the module doc. */
+export declare function instrumentFetch(buffer: BreadcrumbBuffer, win: InstrumentWindow, ignoreUrl: (url: string) => boolean, now: () => number, mono?: () => number): Teardown;

package/dist/trace/instrument/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The browser SDK's **capture instrumentation** — one hook per stream, plus the
+ * composite that installs them all (spec 0003 §C; spec #122 §A/§D).
+ *
+ * Each hook lives in its own module and takes exactly the surface it patches, so
+ * none of them needs a whole `Window`: `console` (the shared core's wrapper),
+ * `fetch`, `XMLHttpRequest`, `sendBeacon`, `history` + hash navigation, and the
+ * masked `click`/`input` listeners.
+ *
+ * Everything private is kept out **at the source**: `ui.input` records that an
+ * input changed, never its value; network crumbs carry method + URL + status only,
+ * **never** bodies; URLs are scrubbed as the crumb is built. The `beforeSend` choke
+ * point is the final gate over the whole report.
+ *
+ * The SDK stays dependency-free and must never throw into the host page, so every
+ * hook is wrapped: a capture failure is swallowed and the original behaviour (the
+ * real `console`, `fetch`, navigation) always runs.
+ */
+import { type BreadcrumbBuffer, type BreadcrumbLevel, type ConsoleLike, type Teardown } from "@fixback/sdk-core";
+import { type InstrumentWindow } from "./window";
+export { instrumentBeacon } from "./beacon";
+export { instrumentConsole } from "./console";
+export { instrumentFetch } from "./fetch";
+export { instrumentNavigation } from "./navigation";
+export { clickCrumb, inputCrumb, instrumentUiEvents } from "./ui";
+export { instrumentXhr } from "./xhr";
+export { type BeaconNavigator, type FetchFn, globalConsole, globalDocument, globalWindow, type HistoryLike, type InstrumentWindow, type XhrConstructor, type XhrInstance, } from "./window";
+/** Options for {@link instrumentBreadcrumbs} and the individual installers. */
+export interface InstrumentOptions {
+    /** The window to instrument. Defaults to the page's, when there is one. */
+    readonly win?: InstrumentWindow;
+    /** The document whose masked UI events are listened for. Defaults to the page's. */
+    readonly doc?: Document;
+    /** The console to wrap. Defaults to the page's. */
+    readonly consoleObj?: ConsoleLike;
+    readonly consoleLevels?: readonly BreadcrumbLevel[];
+    /** Skip URLs (e.g. the SDK's own ingest calls) so they never become crumbs. */
+    readonly ignoreUrl?: (url: string) => boolean;
+    readonly now?: () => number;
+    /**
+     * High-res monotonic clock (spec #122 §D) — used to measure a request's duration as
+     * a delta around the wrapped call. Defaults to `performance.now`; injectable for tests.
+     */
+    readonly mono?: () => number;
+    /**
+     * Whether to instrument the **console** stream (spec #122 §L; ticket #138).
+     * Defaults to `true`; pass `false` and `console` is never wrapped, so no console
+     * entry is ever recorded — the per-project toggle stops the stream at its source.
+     */
+    readonly captureConsole?: boolean;
+    /**
+     * Whether to instrument the **network** stream — `fetch`, `XHR`, and `sendBeacon`
+     * (spec #122 §L; ticket #138). Defaults to `true`; pass `false` and none is
+     * wrapped, so no network entry is ever recorded. Navigation and masked UI events
+     * are unaffected.
+     */
+    readonly captureNetwork?: boolean;
+}
+/**
+ * Install every capture hook onto a window/document and return a single teardown
+ * that removes them all. Each hook is independent and defensive: a failure in one
+ * never blocks the others, and none can throw into the host page.
+ */
+export declare function instrumentBreadcrumbs(buffer: BreadcrumbBuffer, options?: InstrumentOptions): Teardown;

package/dist/trace/instrument/navigation.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The navigation hook (spec #122 §A): a `navigation` crumb on every SPA route
+ * change — `pushState`, `replaceState`, `popstate`, and `hashchange`.
+ *
+ * Both `history` methods are patched rather than listened for, because neither
+ * fires an event of its own; the original is always called first and its result
+ * returned, so the host page's routing is untouched.
+ */
+import { type BreadcrumbBuffer, type Teardown } from "@fixback/sdk-core";
+import { type InstrumentWindow } from "./window";
+/** Record a `navigation` crumb on `pushState`/`replaceState`/pop/hash changes. */
+export declare function instrumentNavigation(buffer: BreadcrumbBuffer, win: InstrumentWindow, now: () => number): Teardown;

package/dist/trace/instrument/ui.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The masked **user-action** hook (spec #122 §A) and its two crumb builders.
+ *
+ * These are the browser-only crumbs: they need an `Element` to derive a masked CSS
+ * selector from, which is why they stay here rather than in the shared core with
+ * the rest of the builders. The masking is at the source and structural — a
+ * `ui.input` crumb records **that** a field changed and which one, and the shape
+ * has no slot for a value, so the typed text can never be recorded.
+ *
+ * Listeners are capture-phase and passive observers: they never call
+ * `preventDefault` or `stopPropagation`, and the SDK's own chrome (launcher,
+ * overlay, and anything inside their shadow roots) is skipped.
+ */
+import type { Breadcrumb, BreadcrumbBuffer, Teardown } from "@fixback/sdk-core";
+/** A `ui.click` crumb: a masked target selector only — no text or value. */
+export declare function clickCrumb(target: Element, timestamp: number): Breadcrumb;
+/**
+ * A `ui.input` crumb: records **that** an input changed and which field, never
+ * the value typed into it. The `target` element's `.value` is never read.
+ */
+export declare function inputCrumb(target: Element, timestamp: number): Breadcrumb;
+/** Listen (capture-phase) for clicks and input changes as masked crumbs. */
+export declare function instrumentUiEvents(buffer: BreadcrumbBuffer, doc: Document, now: () => number): Teardown;

package/dist/trace/instrument/window.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The **structural browser surfaces** the trace instrumentation reaches into, and
+ * the resolvers that find them on the page.
+ *
+ * Everything the hooks touch is described as a narrow interface rather than taken
+ * from the DOM lib wholesale, so a test can build a plain object (`fakeWindow()`)
+ * instead of a whole `Window`. The shapes are deliberately written so the **real**
+ * `window` and `console` satisfy them by assignment — no `as unknown as` escape
+ * anywhere, in the SDK or in its tests.
+ */
+import type { ConsoleLike } from "@fixback/sdk-core";
+/** The `fetch` signature the network hook wraps. */
+export type FetchFn = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/** The `history` slice the navigation hook patches. */
+export interface HistoryLike {
+    pushState(data: unknown, unused: string, url?: string | URL | null): void;
+    replaceState(data: unknown, unused: string, url?: string | URL | null): void;
+}
+/** The XHR instance surface the network hook touches. */
+export interface XhrInstance {
+    status: number;
+    statusText?: string;
+    open(method: string, url: string | URL, ...rest: unknown[]): void;
+    send(body?: unknown): void;
+    getResponseHeader?(name: string): string | null;
+    addEventListener(type: string, listener: () => void): void;
+    removeEventListener(type: string, listener: () => void): void;
+}
+/** The XHR constructor whose prototype the network hook patches. */
+export interface XhrConstructor {
+    new (): XhrInstance;
+    prototype: XhrInstance;
+}
+/** The `navigator.sendBeacon` surface the beacon hook wraps. */
+export interface BeaconNavigator {
+    sendBeacon?: (url: string | URL, data?: BodyInit | null) => boolean;
+}
+/** The structural window surface the instrumentation reaches into. */
+export interface InstrumentWindow {
+    fetch?: FetchFn;
+    history?: HistoryLike;
+    location?: {
+        href: string;
+    };
+    XMLHttpRequest?: XhrConstructor;
+    navigator?: BeaconNavigator;
+    addEventListener(type: string, listener: (event: Event) => void, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener(type: string, listener: (event: Event) => void, options?: boolean | EventListenerOptions): void;
+}
+/** An installed hook's detacher — nothing installed is the no-op below. */
+export declare function noop(): void;
+/**
+ * The page's `window`, when there is one (a worker or an SSR pass has none).
+ * `Window` satisfies {@link InstrumentWindow} structurally, so this is a plain
+ * assignment rather than a cast.
+ */
+export declare function globalWindow(): InstrumentWindow | undefined;
+/** The page's `document`, when there is one. */
+export declare function globalDocument(): Document | undefined;
+/**
+ * The page's `console`, when there is one. A real `Console` satisfies
+ * {@link ConsoleLike} (its optional-method shape is bivariant in its parameters,
+ * which is what makes `console.assert`'s overloads fit), so this too is an
+ * assignment, not a cast.
+ */
+export declare function globalConsole(): ConsoleLike | undefined;

package/dist/trace/instrument/xhr.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The `XMLHttpRequest` network hook (spec #122 §D, ticket #139).
+ *
+ * Patches the prototype's `open`/`send` to record a rich network crumb when a
+ * request settles: method, scrubbed URL, status + statusText, a
+ * `performance.now()` duration, request size (only when the body is trivially
+ * sized), response size (from the `content-length` header only), content type, and
+ * a failure outcome distinguished by which terminal event fired (`error` /
+ * `timeout` / `abort` / `load`). The `send` body argument is **never read for
+ * content** — only its trivially-known size — so a body can never reach the buffer.
+ */
+import { type BreadcrumbBuffer, type Teardown } from "@fixback/sdk-core";
+import { type InstrumentWindow } from "./window";
+/** Patch `XMLHttpRequest` to record a rich network crumb on settlement. See the module doc. */
+export declare function instrumentXhr(buffer: BreadcrumbBuffer, win: InstrumentWindow, ignoreUrl: (url: string) => boolean, now: () => number, mono?: () => number): Teardown;

package/dist/version.d.ts

@@ -10,4 +10,4 @@
  * can't slip through. Do not hand-edit this line to a value other than
  * `package.json`'s version.
  */
-export declare const SDK_VERSION = "0.5.0";
+export declare const SDK_VERSION = "0.6.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fixback/sdk",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "The Fixback capture SDK — a boot-gated, self-isolating on-page feedback launcher.",
   "license": "MIT",
   "type": "module",
@@ -35,15 +35,15 @@
     "url": "git+https://github.com/wemuda/fixback.git",
     "directory": "packages/sdk"
   },
-  "homepage": "https://github.com/wemuda/fixback/tree/master/packages/sdk#readme",
-  "bugs": "https://github.com/wemuda/fixback/issues",
+  "homepage": "https://docs.fixback.dev/sdk/web",
+  "bugs": "https://docs.fixback.dev",
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
     "@rrweb/record": "^2.1.1",
     "@rrweb/types": "^2.1.1",
-    "@fixback/sdk-core": "0.2.0"
+    "@fixback/sdk-core": "0.3.0"
   },
   "devDependencies": {
     "jsdom": "^30.0.1",
@@ -51,8 +51,11 @@
     "vite": "^8.2.1",
     "vitest": "^4.1.10"
   },
+  "engines": {
+    "node": ">=20.12"
+  },
   "scripts": {
-    "build": "vite build && tsc -p tsconfig.build.json",
+    "build": "vite build && tsc -p tsconfig.build.json && node ../../scripts/finalize-cjs.mjs dist",
     "lint": "eslint .",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"

package/dist/boot.d.ts

@@ -1,74 +0,0 @@
-/**
- * The ingest **boot** wire-contract, vendored.
- *
- * The SDK deliberately does not import `@fixback/shared` — that package is
- * private and server-shaped (ticket #47). The boot request/response is small and
- * stable, so the exact slice the SDK needs is copied here. Keep it in lock-step
- * with the server: the request body accepted by `POST /api/ingest/boot`
- * (`apps/api/src/ingest/ingest.controller.ts`) and the `BootAnswer` returned by
- * `evaluateBoot` (`apps/api/src/ingest/reporter-identity.ts`).
- */
-/** A Project's Gate — who may submit. Mirrors the server's `ProjectGate`. */
-export type ProjectGate = "open" | "invited" | "internal";
-/** The trust tier a Reporter holds. Mirrors the server's `ReporterTier`. */
-export type ReporterTier = "public" | "invited" | "internal";
-/**
- * Optional identity evidence the SDK forwards to boot. None of it is a tier: the
- * server re-derives trust from this evidence and never honours a self-declared
- * tier, so the SDK does not send one.
- */
-export interface IdentityInputs {
-    readonly signedIdentity?: string;
-    readonly reporterId?: string;
-    readonly anonymousId?: string;
-}
-/** The JSON body `POST /api/ingest/boot` accepts. */
-export interface BootRequest extends IdentityInputs {
-    readonly key: string;
-}
-/**
- * The Project's effective console/network capture config, served on the boot answer
- * (spec #122 §L; ticket #138). Each flag is the per-project master toggle ANDed with
- * that stream's own toggle, so the SDK gates instrumentation on one boolean per
- * stream. Optional on the wire: an older server that does not send it (or a
- * malformed value) is treated as **capture on** — default-on, matching the server
- * default — and `init` options override whatever is served.
- */
-export interface CaptureConfig {
-    readonly console: boolean;
-    readonly network: boolean;
-    /**
-     * The Project's session-replay toggle (issue #189, ADR-0024). Optional on the
-     * wire: a server predating replay omits it, which — like the other streams —
-     * means **capture on**.
-     */
-    readonly replay?: boolean;
-}
-/**
- * The boot answer: whether this origin is allowlisted, the Project's Gate, the
- * caller's derived tier (`null` when a presented identity was refused), whether a
- * submission would be accepted right now, and the Project's capture config. The
- * launcher shows only when `canSubmit` is true.
- */
-export interface BootAnswer {
-    readonly originAllowed: boolean;
-    readonly gate: ProjectGate;
-    readonly tier: ReporterTier | null;
-    readonly canSubmit: boolean;
-    /** The Project's console/network capture config; absent ⇒ default-on (#138). */
-    readonly capture?: CaptureConfig;
-}
-/** Join an API base URL with the boot path, tolerating a trailing slash. */
-export declare function bootEndpoint(apiUrl: string): string;
-/**
- * Ask ingest whether a submission would be accepted for this key / origin / Gate.
- * Resolves to the boot answer, or `null` when Fixback could not be reached, the
- * key was refused, or the response was not a boot answer. It never throws: any
- * non-answer is treated by the caller as "do not show the launcher", so a Fixback
- * outage stays invisible to the host page (ticket #47: "fails quietly").
- *
- * The browser attaches the `Origin` header itself on this cross-origin request —
- * the server reads it to decide `originAllowed` — so the SDK neither sets nor
- * needs to set it. `fetchImpl` is injectable purely so the boot call is testable.
- */
-export declare function requestBoot(apiUrl: string, request: BootRequest, fetchImpl?: typeof fetch): Promise<BootAnswer | null>;