@fixback/sdk 0.4.0 → 0.5.0

package/dist/init.d.ts

@@ -1,7 +1,7 @@
+import type { BeforeSend } from "@fixback/sdk-core";
 import { type IdentityInputs } from "./boot";
 import { type BeforeBreadcrumb, type BreadcrumbLevel, type TraceStream } from "./breadcrumbs";
 import { type ReplayOptions } from "./replay";
-import type { BeforeSend } from "./scrub";
 /**
  * The hosted Fixback API origin the SDK talks to by default. A self-hosted or
  * local deployment overrides it with `apiUrl` (the dashboard's install snippet
@@ -92,7 +92,7 @@ export interface InitOptions extends IdentityInputs {
     };
     /**
      * Automatic error capture — the SDK files uncaught exceptions / unhandled
-     * rejections as `source: auto` Feedback with no prompt (spec §E, ADR-0011).
+     * rejections as `source: error` Feedback with no prompt (spec §E, ADR-0011).
      * **Default-on across all Gates**; set `false` for the per-project toggle that
      * turns it off. It is gated by boot's `canSubmit` either way, so an auto-error is
      * never filed where a manual report would be refused.

package/dist/overlay.d.ts

@@ -1,19 +1,16 @@
+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";
 import type { ReplaySource } from "./replay";
-import { type BeforeSend } from "./scrub";
-import { type Capture, type CaptureOptions } from "./screenshot";
 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 CaptureViewFn = (options?: CaptureOptions) => Promise<Capture | null>;
 type SubmitReportFn = (apiUrl: string, input: SubmitInput, fetchImpl?: typeof fetch) => Promise<SubmitResult>;
 type StartPickerFn = (options: ElementPickerOptions) => ElementPicker;
 /** Injectable collaborators, defaulted to the real implementations. */
 export interface OverlayDeps {
-    readonly captureView: CaptureViewFn;
     readonly submitReport: SubmitReportFn;
     readonly startElementPicker: StartPickerFn;
 }
@@ -73,14 +70,15 @@ export interface OverlayController {
  * 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 screenshot and element-picker skip it), opens on the launcher's
+ * 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 one full masked screenshot (spec §B): **element-pick**, **region-capture**
- * (drag), and **draw** (arrow / box / pen / text, with undo / cancel / attach). On
- * Send it captures the masked screenshot, assembles the structured Annotation
- * (`{ element?, region?, marks? }`, spec §D — marks stay vector, never baked into
- * the PNG), and submits to ingest — showing a confirmation on success and failing
- * quietly otherwise.
+ * 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.
  */
 export declare function createOverlay(config: OverlayConfig): OverlayController;
 export {};

package/dist/report.d.ts

@@ -1,65 +1,20 @@
 /**
- * The ingest **feedback** content wire-contract, vendored, plus the helpers that
- * assemble it from what a Reporter composed in the overlay.
+ * Assembling the ingest **feedback** content from what a Reporter composed in the
+ * overlay, plus the browser-side environment capture and Release validation.
  *
- * Like `boot.ts`, the SDK does not import `@fixback/shared`; the slice of the
- * submission shape it needs is copied here. Keep it in lock-step with the server:
- * the JSON `payload` part accepted by `POST /api/ingest/feedback`
- * (`apps/api/src/ingest/ingest.controller.ts` — `feedbackContentBody`) and the
- * `SubmissionContent` it parses (`apps/api/src/ingest/reporter-identity.ts`).
- */
-import { type Annotation, type Mark, type Rect } from "./annotation";
+ * The shared wire shapes it produces — `ReportContent`, `CaptureEnvironment`,
+ * `CapturedFrame`, `SelectedElement`, `ElementRect`, `FeedbackSource` — live in
+ * `@fixback/sdk-core` (ADR-0028), so the browser and backend SDKs speak the same
+ * shape; this module re-exports them for the SDK's public surface and holds only
+ * the browser-specific assembly (`assembleContent`, `collectEnvironment`) and the
+ * `release` validation. Keep the shapes in lock-step with the server: the JSON
+ * `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 Mark, type Rect } from "./annotation";
 import type { Breadcrumb } from "./breadcrumbs";
-/**
- * Where a Feedback came from — a human in the overlay (`reporter`, the default) or
- * the SDK's automatic error capture (`auto`). Mirrors the server's `FEEDBACK_SOURCES`;
- * the server derives trust independently and ignores anything else the client claims.
- */
-export type FeedbackSource = "reporter" | "auto";
-/** The picked element's viewport rectangle, as the server's annotation `rect`. */
-export interface ElementRect {
-    readonly x: number;
-    readonly y: number;
-    readonly width: number;
-    readonly height: number;
-}
-/**
- * The picked element — the `element` layer of an {@link Annotation}: a stable CSS
- * selector, a readable DOM path, the tag, and the bounding rect. Exactly the
- * server's annotation `element` object shape.
- */
-export interface SelectedElement {
-    readonly selector: string;
-    readonly domPath: string;
-    readonly tag: string;
-    readonly rect: ElementRect;
-}
-/** 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 (mirrors `@fixback/shared`'s
- * `CapturedStackFrame` by value, per this file's vendoring rule). `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;
-}
+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
@@ -68,46 +23,6 @@ export interface CapturedFrame {
  * shipping a value the server would discard.
  */
 export declare function normaliseRelease(value: string): string | undefined;
-/**
- * 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 `auto` by the SDK's error capture.
-     */
-    readonly source?: FeedbackSource;
-    /** For `source: auto` only — the SDK's per-session error fingerprint (spec §E). */
-    readonly errorSignature?: string;
-    /** For `source: auto` only — the running occurrence count within the session (spec §E). */
-    readonly occurrences?: number;
-    /**
-     * For `source: auto` 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[];
-}
 /**
  * What the overlay hands to {@link assembleContent} when the Reporter sends. The
  * three marking layers arrive flat (`element` / `region` / `marks`); `assembleContent`

package/dist/submit.d.ts

@@ -1,4 +1,4 @@
-import { AutoReportBackoff } from "./auto-report-backoff";
+import { AutoReportBackoff } from "@fixback/sdk-core";
 import type { IdentityInputs, ReporterTier } from "./boot";
 import type { ReportContent } from "./report";
 /** What ingest returns for an accepted submission (vendored server shape). */
@@ -8,11 +8,6 @@ export interface RecordedFeedback {
     readonly reporterId: string;
     readonly tier: ReporterTier;
 }
-/** The captured screenshot to attach, if any. */
-export interface SubmitScreenshot {
-    readonly blob: Blob;
-    readonly filename?: string;
-}
 /**
  * The buffered replay window to attach, if any — the rrweb events a
  * `ReplaySnapshot` holds (replay.ts). Serialized into its own binary part.
@@ -25,7 +20,6 @@ export interface SubmitInput {
     readonly key: string;
     readonly identity?: IdentityInputs;
     readonly content: ReportContent;
-    readonly screenshot?: SubmitScreenshot | null;
     readonly replay?: SubmitReplay | null;
 }
 /** The outcome of a submission — never an exception. */
@@ -38,7 +32,7 @@ export type SubmitResult = {
     readonly status?: number;
 } | {
     /**
-     * A `source: auto` report shed under ingest backpressure (spec §E/§H) — either
+     * A `source: error` report shed under ingest backpressure (spec §E/§H) — either
      * held locally because the window is still open, or answered `429` by ingest,
      * which opened/extended the window. Carries the seconds left to wait. Manual
      * reports never produce this.
@@ -51,11 +45,11 @@ export type SubmitResult = {
 export declare function feedbackEndpoint(apiUrl: string): string;
 /**
  * Submit a report to ingest. Assembles the `payload` JSON (key + identity +
- * content, with an explicit `source` stamped) and the optional full masked
- * `screenshot` file into a `FormData`, posts it, and resolves to the recorded
- * Feedback on success or a named failure otherwise.
+ * content, with an explicit `source` stamped) and the optional `replay` window
+ * into a `FormData`, posts it, and resolves to the recorded Feedback on success
+ * or a named failure otherwise.
  *
- * A `source: auto` report first consults the shared backpressure window: while it
+ * A `source: error` report first consults the shared backpressure window: while it
  * 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

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.4.0";
+export declare const SDK_VERSION = "0.5.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fixback/sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The Fixback capture SDK — a boot-gated, self-isolating on-page feedback launcher.",
   "license": "MIT",
   "type": "module",
@@ -43,7 +43,7 @@
   "dependencies": {
     "@rrweb/record": "^2.1.1",
     "@rrweb/types": "^2.1.1",
-    "modern-screenshot": "^4.7.0"
+    "@fixback/sdk-core": "0.2.0"
   },
   "devDependencies": {
     "jsdom": "^30.0.1",

package/dist/auto-report-backoff.d.ts

@@ -1,47 +0,0 @@
-/**
- * Client-side backpressure for **automatic** error reports (spec 0003 §E/§H,
- * ticket #89). When ingest sheds `source: auto` load it answers `429` with a
- * `Retry-After`; the SDK honours it by holding a pause window during which further
- * `source: auto` reports are dropped without touching the network. **Manual**
- * reports — a human clicking Send — never consult this gate.
- *
- * This is the transport's counterpart to the server's per-Project token bucket
- * (`apps/api/src/ingest/auto-report-rate-limiter.ts`): one shared window per page,
- * so a 429 from one auto-report shed applies to the auto-reports that follow it.
- * The clock is injectable so the window is unit-tested deterministically, never on
- * wall time — mirroring the server limiter's `Clock`.
- */
-/** A source of the current time in epoch milliseconds — injectable for tests. */
-export type Clock = () => number;
-/** The hold window applied when a `429` carries no usable `Retry-After` (spec §E). */
-export declare const DEFAULT_RETRY_AFTER_SECONDS = 60;
-/**
- * Parse a `Retry-After` header into whole seconds to hold for. Handles both HTTP
- * forms — a delta-seconds integer and an HTTP-date (measured from `now`, rounded up
- * and clamped at zero) — and falls back to {@link DEFAULT_RETRY_AFTER_SECONDS} when
- * the header is absent, blank, or unparseable. Ingest sends the delta-seconds form;
- * the date form is handled for spec-completeness.
- */
-export declare function parseRetryAfter(header: string | null | undefined, now: number): number;
-/**
- * A single pause window for `source: auto` reports. `hold` opens (or extends) it
- * from a `429`'s `Retry-After`; `isPaused` reports whether it is still open. The
- * default instance in `submit.ts` is shared across a page's reports so the hold
- * persists across successive auto submissions.
- */
-export declare class AutoReportBackoff {
-    private readonly now;
-    /** Epoch ms until which `source: auto` reports are held; `0` when clear. */
-    private pausedUntil;
-    constructor(now?: Clock);
-    /** Is the `source: auto` pause window currently open? */
-    isPaused(): boolean;
-    /** Whole seconds remaining in the pause window (`0` when clear). */
-    retryAfterSeconds(): number;
-    /**
-     * Open (or extend) the window from a `429`'s `Retry-After` value, returning the
-     * seconds it will hold for. The window only ever grows — a shorter later hold
-     * never clips a longer one already in effect.
-     */
-    hold(retryAfterHeader: string | null | undefined): number;
-}

package/dist/screenshot.d.ts

@@ -1,73 +0,0 @@
-/**
- * Client-side masked screenshot capture (spec MVP §E; ticket #54; ADR-0014).
- *
- * The capture is **private-by-default**: input values are masked and the SDK's own
- * UI is excluded from a *clone* of the view **before** anything is rasterised, so no
- * unmasked text and none of Fixback's chrome ever reaches the image.
- *
- * The rasterisation itself is delegated to `modern-screenshot` (ADR-0014): it clones
- * the target, inlines the page's real styles **and** its fonts and images as data
- * URIs, then draws the result through an SVG `<foreignObject>` onto a `<canvas>`.
- * That closes the fidelity gap a hand-rolled `<foreignObject>` left open — external
- * stylesheets, web fonts, and same-origin images now render — so the shot matches
- * what the Reporter saw and lines up with the annotation's viewport-space marks.
- *
- * We keep the privacy guarantee by driving it through two of its hooks: `filter`
- * drops Fixback's own host elements, and `onCloneNode` masks the clone's inputs —
- * both run on the library's internal clone, before it embeds or serialises anything,
- * so the live page is never touched and no real value reaches the raster. The backend
- * is injectable so the pipeline (and the masking-before-capture guarantee) is testable
- * without a real canvas, and it fails quietly: any problem resolves to `null` and the
- * report is simply sent without a screenshot.
- */
-/** The character private input content is replaced with. */
-export declare const MASK_CHAR = "\u2022";
-/**
- * Mask the private, user-entered content in a subtree: text `input` values,
- * `textarea` content, and `contenteditable` text. Developer-authored text
- * (placeholders, button labels, non-text controls) is left untouched. Operates in
- * place — call it on a *clone* of the view, never the live page.
- */
-export declare function maskInputs(root: ParentNode): void;
-/** A captured screenshot: the image bytes plus its dimensions and content type. */
-export interface Capture {
-    readonly blob: Blob;
-    readonly width: number;
-    readonly height: number;
-    readonly type: string;
-}
-/** The screenshot filename extension for a {@link Capture}'s content type (defaults to `png`). */
-export declare function extensionFor(type: string): string;
-/** How the SDK prepares a capture: exclude Fixback's UI, mask the clone's inputs. */
-interface CaptureHooks {
-    /** Keep a node in the shot? Returns `false` for Fixback's own host elements. */
-    readonly filter: (node: Node) => boolean;
-    /** Mask private input content on the library's internal clone, pre-raster. */
-    readonly onCloneNode: (clone: Node) => void;
-}
-/** Turns a DOM subtree into image bytes at a given size (injectable for tests). */
-export type CaptureBackend = (target: Element, meta: {
-    width: number;
-    height: number;
-    type: string;
-} & CaptureHooks) => Promise<Blob | null>;
-/** Options for {@link captureView}. */
-export interface CaptureOptions {
-    /** The element to capture. Defaults to the document element (the full view). */
-    readonly target?: Element;
-    readonly doc?: Document;
-    readonly win?: Window;
-    /** Output content type. Defaults to `image/png`. */
-    readonly type?: string;
-    /** Override the raster backend (the default is `modern-screenshot`). */
-    readonly capture?: CaptureBackend;
-}
-/**
- * Capture the current view as a masked screenshot. Delegates the raster to the
- * backend ({@link captureViaModernScreenshot} by default), which excludes the SDK's
- * own UI and masks input values on its internal clone — **before** it embeds or
- * serialises anything — then returns the image bytes, or `null` if capture wasn't
- * possible.
- */
-export declare function captureView(options?: CaptureOptions): Promise<Capture | null>;
-export {};

package/dist/scrub.d.ts

@@ -1,61 +0,0 @@
-/**
- * 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.
- *
- * Masking is the SDK's job, done in the browser before anything leaves the page.
- * 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 { ReportContent } from "./report";
-/** 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;
-}
-/**
- * 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 declare function redactPii(text: string): string;
-/**
- * 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 declare function scrubUrl(url: string): string;
-/**
- * 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 declare function applyDefaultScrub(draft: ReportContent): ReportContent;
-/**
- * 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 declare function runBeforeSend(draft: ReportContent, options?: BeforeSendOptions): ReportContent | null;