@fixback/sdk 0.1.0 → 0.3.0

package/README.md

@@ -62,6 +62,9 @@ global:
 | `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. |
 
 None of the identity fields is a trust tier — Fixback derives trust on the
 server and never honours a self-declared tier.
@@ -72,6 +75,24 @@ const fixback = await init({ key: "pk_live_..." });
 fixback.destroy();
 ```
 
+## The launcher
+
+The launcher is a bottom-right **Feedback** pill, and it stays out of the way:
+
+- **Hover-peek & tuck-away** — the pill's caret tucks it off-screen behind a
+  small edge nub. Hovering the bottom-right corner (or the nub) peeks it back;
+  clicking the nub — or pressing Enter/Space on it — brings it fully back, which
+  also covers pointers that can't hover (touch, keyboard). A brief hint appears
+  the first time it's tucked, pointing at the corner.
+- **First-visit welcome** — a one-time toast greets a new visitor, drawing the
+  eye with a gentle pulse. It shows once per publishable key per browser.
+- **Reduce motion** — pass `reduceMotion: true` to still the pulse and the
+  slide/fade transitions. The launcher also honours the visitor's OS-level
+  `prefers-reduced-motion: reduce` on its own, with no configuration.
+
+All of this chrome lives inside the launcher's Shadow DOM, so it never adds a
+global style or touches the host page's markup.
+
 ## The launch event
 
 Activating the launcher opens the SDK's own report overlay. It also dispatches a
@@ -86,6 +107,57 @@ document.addEventListener(LAUNCH_EVENT, () => {
 });
 ```
 
+## Automatic error capture
+
+The SDK's signature capability: **errors report themselves, with no prompt.** Two
+capture-phase global handlers (`error` + `unhandledrejection`) turn uncaught
+exceptions and unhandled promise rejections into `source: auto`, `Kind = bug`
+Feedback for the current session's reporter — carrying the same masked screenshot
+and trace buffer a manual report does, plus a per-session fingerprint. It is
+**on by default across every Gate**; pass `autoCapture: false` to turn it off.
+
+- **Deduped & rate-limited.** The same error reported many times collapses to one
+  Feedback with a rising occurrence count. A token-bucket burst limiter and a
+  per-session cap keep a runaway error loop from flooding the queue; the excess is
+  dropped and kept only as a local count. On a `429` + `Retry-After` from ingest,
+  auto-reporting backs off until the window clears.
+- **Gated like a manual report.** Auto-capture only runs where a submission would
+  be accepted (boot's `canSubmit`), so a public visitor's crash is tracked at their
+  server-derived tier — never auto-shipped. `console.error` is **not** promoted to a
+  report; it stays breadcrumb-only Evidence.
+- **Private-by-default.** Every auto-report passes through the same client-side
+  `beforeSend` scrub choke point as a manual one — input values and request/response
+  bodies never leave the browser, and your hook can drop an auto-report entirely.
+
+## Invite redemption
+
+An invited tester needs no account and no setup. When a page loads with an invite
+token in its URL (`?fixback_invite=<token>`), `init` reads the invite's status and
+renders the SDK's own **onboarding modal** — the site you were invited to, the
+**access tier** the redemption grants (server-derived, never guessed on the
+client), a private-by-default note, and a "Continue as" name / email:
+
+```ts
+init({ key: "pk_live_..." }); // auto-detects ?fixback_invite= on the page
+```
+
+On confirm the SDK redeems the invite, persists the returned `reporterId` in
+`localStorage` (scoped to your publishable key), strips the token from the URL
+(one-time consumption), and mounts the launcher. On later visits `init` presents
+that stored `reporterId`, so a returning tester is recognised at their correct
+tier without re-onboarding — and on an **Invited** or **Internal** Gate the
+launcher appears only after redemption, while an **Open** Gate shows it to anyone.
+
+The name / email are **self-provided display fields** — never a trust signal; the
+tier is always the server's to derive. If the token reaches the page some way
+other than the URL, redeem it explicitly:
+
+```ts
+import { redeem } from "@fixback/sdk";
+
+redeem({ key: "pk_live_...", token: "the-invite-token" });
+```
+
 ## How the boot gate works
 
 On `init`, the SDK `POST`s to `${apiUrl}/api/ingest/boot` with your key (the

package/dist/annotation.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The Annotation & vector-marks model (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 Kind + comment is a valid Send).
+ */
+export interface Annotation {
+    readonly element?: SelectedElement;
+    readonly region?: Rect;
+    readonly marks?: ReadonlyArray<Mark>;
+}
+/**
+ * The default mark colour — Signal's danger red, matching the frozen Reporter
+ * prototype's draw layer (`docs/design/Fixback Reporter.dc.html`).
+ */
+export declare const MARK_COLOR = "#e5484d";
+/**
+ * Normalise a drag from a start to an end point into a positive-extent rect
+ * (top-left origin, non-negative width/height), rounded to whole pixels — the
+ * screenshot is a pixel raster, so sub-pixel extents carry no meaning. Shared by
+ * region-capture and the box mark.
+ */
+export declare function normalizeRect(x0: number, y0: number, x1: number, y1: number): Rect;
+/**
+ * The three points of an arrow's head, given its line `(x0,y0)→(x1,y1)` and a head
+ * length: the tip, then the two barbs splayed ±30° behind it. Pure geometry the
+ * draw surface renders as a filled triangle at the arrow's tip.
+ */
+export declare function arrowHeadPoints(x0: number, y0: number, x1: number, y1: number, size?: number): [Point, Point, Point];
+/**
+ * Assemble the structured Annotation from whatever a Reporter marked, dropping
+ * empty layers: no element, no region, and an empty marks list are omitted, so the
+ * result is `undefined` when nothing was marked. Marks are copied into a plain,
+ * independent array so the annotation is a serialisable snapshot decoupled from the
+ * live draw state.
+ */
+export declare function assembleAnnotation(parts: {
+    readonly element?: SelectedElement | null;
+    readonly region?: Rect | null;
+    readonly marks?: ReadonlyArray<Mark> | null;
+}): Annotation | undefined;
+export {};

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

@@ -0,0 +1,47 @@
+/**
+ * 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/boot.d.ts

@@ -26,17 +26,31 @@ export interface IdentityInputs {
 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 boot answer: whether this origin is allowlisted, the Project's Gate, the
- * caller's derived tier (`null` when a presented identity was refused), and
- * whether a submission would be accepted right now. The launcher shows only when
- * `canSubmit` is true.
+ * 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;