@fixback/sdk 0.2.0 → 0.3.0

package/dist/init.d.ts

@@ -1,5 +1,5 @@
 import { type IdentityInputs } from "./boot";
-import { type BeforeBreadcrumb, type BreadcrumbLevel } from "./breadcrumbs";
+import { type BeforeBreadcrumb, type BreadcrumbLevel, type TraceStream } from "./breadcrumbs";
 import type { BeforeSend } from "./scrub";
 /**
  * The hosted Fixback API origin the SDK talks to by default. A self-hosted or
@@ -8,17 +8,39 @@ import type { BeforeSend } from "./scrub";
  */
 export declare const DEFAULT_API_URL = "https://api.fixback.dev";
 /**
- * Trace buffer tuning (spec §C). These are configurable **starting points** from
- * research (N ≈ 30, `warn`/`error`/`assert`, optional ~60 s age cap) — never
- * frozen magic numbers. Pass `false` for {@link InitOptions.trace} to disable
+ * Does `url` address one of the SDK's **own** API endpoints? Every request the SDK
+ * issues lives under two namespaces beneath the API origin: `/api/ingest/*` — boot
+ * (`bootEndpoint`, boot.ts) and feedback (`feedbackEndpoint`, submit.ts) — and
+ * `/api/invites/*` (`inviteStatusEndpoint` / `redeemEndpoint`, invite.ts).
+ *
+ * The trace's network capture ignores **only** these, never the whole origin. That
+ * distinction matters when the instrumented app and the Fixback API share an origin — a
+ * self-hosted deployment, or Fixback running its own SDK on its own dashboard — where
+ * ignoring the origin wholesale would swallow all of the app's own requests and leave the
+ * Network tab empty. When the app and the API sit on different origins (the common case)
+ * this matches nothing extra, since the app's origin is never `apiUrl`. `url` is the raw
+ * request URL — absolute for every call the SDK makes — so a prefix test over the
+ * normalised origin is exact.
+ */
+export declare function isFixbackApiRequest(apiUrl: string, url: string): boolean;
+/**
+ * Trace buffer tuning (spec #122 §A). These are configurable **starting points**
+ * from the grill — three per-stream ring budgets (network ≈ 100 / console ≈ 80 /
+ * breadcrumbs ≈ 40), a shared age cap (~3 min, on), and **all** console levels
+ * captured (eviction priority, not capture, keeps warn/error above the chatter) —
+ * never frozen magic numbers. Pass `false` for {@link InitOptions.trace} to disable
  * capture entirely.
  */
 export interface TraceOptions {
-    /** Keep at most this many crumbs (oldest drop). Defaults to 30. */
-    readonly maxBreadcrumbs?: number;
-    /** Optional age cap in ms (e.g. `60000`); off by default. */
+    /**
+     * Per-stream ring budgets (network / console / breadcrumbs); each stream evicts
+     * independently, so a chatty stream can't drop another's lead-up. Any stream
+     * omitted uses its default.
+     */
+    readonly budgets?: Partial<Record<TraceStream, number>>;
+    /** Shared age cap in ms. Defaults to ~3 min (on); pass `0` to disable age pruning. */
     readonly maxAgeMs?: number;
-    /** Console levels captured. Defaults to `warn`/`error`/`assert`. */
+    /** Console levels captured. Defaults to **all** levels (log/info/warn/error/assert/debug). */
     readonly consoleLevels?: readonly BreadcrumbLevel[];
     /** Per-crumb filter: mute a category, edit a crumb, or drop it (`null`). */
     readonly beforeBreadcrumb?: BeforeBreadcrumb;
@@ -47,6 +69,18 @@ export interface InitOptions extends IdentityInputs {
     readonly scrub?: boolean;
     /** Trace buffer tuning, or `false` to turn the buffer off entirely. */
     readonly trace?: TraceOptions | false;
+    /**
+     * The dev-side override of the Project's server-served capture config (spec #122
+     * §L; ticket #138). Capture is **default-on** and normally governed per-project
+     * from the dashboard, surfaced on the boot answer; set a stream here to override
+     * what the server serves for it — `{ network: false }` turns network capture off
+     * even where the Project leaves it on, and a stream left unset follows the served
+     * config. Independent of {@link trace} `false`, which turns the whole buffer off.
+     */
+    readonly capture?: {
+        readonly console?: boolean;
+        readonly network?: boolean;
+    };
     /**
      * Automatic error capture — the SDK files uncaught exceptions / unhandled
      * rejections as `source: auto` Feedback with no prompt (spec §E, ADR-0011).

package/dist/screenshot.d.ts

@@ -1,15 +1,24 @@
 /**
- * Client-side masked screenshot capture (spec MVP §E; ticket #54).
+ * 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 removed 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
- * approach is dependency-free — the cloned, masked DOM is serialised into an SVG
- * `<foreignObject>` and drawn onto a `<canvas>` — honouring the SDK's "no runtime
- * dependencies / no host-page disturbance" constraints. The raster step 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 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";
@@ -29,12 +38,19 @@ export interface Capture {
 }
 /** The screenshot filename extension for a {@link Capture}'s content type (defaults to `png`). */
 export declare function extensionFor(type: string): string;
-/** Turns a serialised SVG of the view into image bytes (injectable for tests). */
-export type Rasterize = (svg: string, meta: {
+/** 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;
-}) => Promise<Blob | null>;
+} & CaptureHooks) => Promise<Blob | null>;
 /** Options for {@link captureView}. */
 export interface CaptureOptions {
     /** The element to capture. Defaults to the document element (the full view). */
@@ -43,12 +59,15 @@ export interface CaptureOptions {
     readonly win?: Window;
     /** Output content type. Defaults to `image/png`. */
     readonly type?: string;
-    /** Override the raster step (the default draws via an SVG + `<canvas>`). */
-    readonly rasterize?: Rasterize;
+    /** Override the raster backend (the default is `modern-screenshot`). */
+    readonly capture?: CaptureBackend;
 }
 /**
- * Capture the current view as a masked screenshot. Clones the target, removes the
- * SDK's own UI, masks input values — **all before** serialising and rasterising —
- * then returns the image bytes, or `null` if capture wasn't possible.
+ * 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

@@ -35,10 +35,11 @@ export interface BeforeSendOptions {
 export declare function redactPii(text: string): string;
 /**
  * Strip the sensitive parts of a URL: userinfo credentials
- * (`scheme://user:pass@host`), the entire query string, and a token-bearing
- * fragment (one that carries `key=value`). Plain hash routes (`#/checkout`) are
- * kept. Works on absolute and relative URLs alike, with no dependency and no
- * throw.
+ * (`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;
 /**

package/dist/version.d.ts

@@ -1,7 +1,13 @@
 /**
  * The SDK's own version string, reported to ingest as `environment.sdkVersion`
- * (spec MVP §B/§E). Kept as a hand-maintained constant rather than imported from
- * `package.json`, so the bundle stays a single self-contained file with no JSON
- * import — keep it in step with `package.json` and the Changesets bump.
+ * (spec MVP §B/§E). Kept as an inlined constant rather than a runtime `package.json`
+ * import, so the published bundle stays a single self-contained file.
+ *
+ * It must equal `package.json`'s `version`. Two things keep it there: the Changesets
+ * `version` step syncs it automatically (`scripts/sync-sdk-version.mjs`, wired into
+ * `version-packages`), and `version.test.ts` fails the build if the two ever drift —
+ * so a stale dogfood version (the SDK reporting an old number on our own dashboard)
+ * 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.1.0";
+export declare const SDK_VERSION = "0.3.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fixback/sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The Fixback capture SDK — a boot-gated, self-isolating on-page feedback launcher.",
   "license": "MIT",
   "type": "module",
@@ -40,6 +40,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "modern-screenshot": "^4.7.0"
+  },
   "devDependencies": {
     "jsdom": "^30.0.1",
     "typescript": "5.9.3",