@fixback/sdk 0.4.0 → 0.6.0

package/dist/invite.d.ts

@@ -1,104 +0,0 @@
-/**
- * Invite redemption & reporter identity (spec §F).
- *
- * The zero-integration path for an invited tester: detect an invite token on the
- * page (`?fixback_invite=<token>`) or an explicit `redeem()` call, read the
- * Invite's public status, and — on confirmation — redeem it into a persisted
- * `reporterId` the SDK thereafter presents as an identity input.
- *
- * This module is the wire + storage half (pure enough to unit-test directly): the
- * two invite endpoints, the localStorage persistence scoped by publishable key,
- * and the URL token detection / one-time consumption. The onboarding modal is
- * `onboarding.ts`; `init` wires the two together.
- *
- * Like `boot.ts`, the wire types are a **vendored** slice of the server contract
- * (`apps/api/src/invites/invite-redemption.controller.ts`) — the SDK never imports
- * the private server package. Keep them in lock-step with that controller.
- */
-import type { ReporterTier } from "./boot";
-/** The Invite's shape. Mirrors the server's `InviteKind`. */
-export type InviteKind = "targeted" | "shared";
-/** The dead/unknown states a status or redeem read can resolve to. */
-export type InviteDeadStatus = "revoked" | "expired" | "exhausted" | "not_found";
-/**
- * The public status of an Invite (`GET /api/invites/:token`). A live (`pending`)
- * Invite reveals the minimal facts the onboarding modal needs — the Project, the
- * Invite's shape, and the **server-derived** tier the redemption would grant; a
- * dead or unknown token reveals only its state.
- */
-export type InviteStatusAnswer = {
-    readonly status: "pending";
-    readonly projectId: string;
-    readonly kind: InviteKind;
-    readonly tier: ReporterTier;
-} | {
-    readonly status: InviteDeadStatus;
-};
-/**
- * The result of redeeming an Invite (`POST /api/invites/:token/redeem`): the
- * minted Reporter (its handle + server-derived tier + Project), or why it was
- * refused.
- */
-export type RedeemAnswer = {
-    readonly status: "redeemed";
-    readonly reporterId: string;
-    readonly tier: ReporterTier;
-    readonly projectId: string;
-} | {
-    readonly status: InviteDeadStatus;
-};
-/**
- * The self-provided display fields captured in the onboarding modal. They ride
- * along as a Reporter's chosen name / email — **never** a trust signal (the tier
- * is always server-derived, spec §F).
- */
-export interface ReporterDisplay {
-    readonly name?: string;
-    readonly email?: string;
-}
-/** A persisted redeemed Reporter: the server handle plus the display fields. */
-export interface StoredReporter extends ReporterDisplay {
-    readonly reporterId: string;
-}
-/** The URL query parameter that carries an invite token. */
-export declare const INVITE_QUERY_PARAM = "fixback_invite";
-/**
- * Read the invite token from a page URL's `?fixback_invite=` param. Returns the
- * token, or `null` when absent, empty, or the URL cannot be parsed — never throws.
- */
-export declare function readInviteToken(href: string): string | null;
-/**
- * Strip the invite token from the address bar (one-time consumption, spec §F) via
- * `history.replaceState`, so a reload or a shared link cannot re-trigger — or
- * re-consume — an already-redeemed Invite. Other params, the path, and the hash
- * are preserved. Best-effort: it never throws into the host page.
- */
-export declare function stripInviteToken(win: Window): void;
-/**
- * Persist a redeemed Reporter for `key`. The `reporterId` is the identity the SDK
- * presents on later boots; the display name / email ride along as chosen fields.
- * Best-effort — storage being unavailable (private mode) is never fatal.
- */
-export declare function persistReporter(key: string, reporter: StoredReporter, store?: Storage | null): void;
-/**
- * Read the redeemed Reporter persisted for `key`, or `null` when none is stored,
- * the record is malformed, or it carries no `reporterId`. Never throws.
- */
-export declare function readStoredReporter(key: string, store?: Storage | null): StoredReporter | null;
-/** Join an API base URL with the invite status path, tolerating a trailing slash. */
-export declare function inviteStatusEndpoint(apiUrl: string, token: string): string;
-/** Join an API base URL with the redeem path for a token. */
-export declare function redeemEndpoint(apiUrl: string, token: string): string;
-/**
- * Read an Invite's public status. Resolves to the answer, or `null` when Fixback
- * could not be reached or the body was not a recognised answer. The endpoint
- * answers 200 for a live or dead Invite and 404 (with a JSON body) for an unknown
- * token, so the body — not the HTTP status — is what the caller narrows on. Never
- * throws: an outage stays invisible to the host page.
- */
-export declare function fetchInviteStatus(apiUrl: string, token: string, fetchImpl?: typeof fetch): Promise<InviteStatusAnswer | null>;
-/**
- * Redeem an Invite by token, minting and returning a Reporter. Resolves to the
- * answer, or `null` on an unreachable API or an unrecognised body. Never throws.
- */
-export declare function redeemInviteToken(apiUrl: string, token: string, fetchImpl?: typeof fetch): Promise<RedeemAnswer | null>;

package/dist/onboarding-styles.d.ts

@@ -1,8 +0,0 @@
-/**
- * Styles for the invite onboarding modal (spec §F) — the Signal look of the
- * frozen Reporter prototype (`docs/design/Fixback Reporter.dc.html`), scoped to
- * the modal's own Shadow DOM so the host page is never touched and never touches
- * it. Tokens mirror `overlay-styles.ts` so launcher, overlay, and modal read as
- * one system.
- */
-export declare const ONBOARDING_STYLES = "\n:host {\n  --fb-color-accent: #2f6fed;\n  --fb-color-accent-hover: #245fd0;\n  --fb-color-on-emphasis: #ffffff;\n  --fb-color-ink: #0f1720;\n  --fb-color-text: #1a2530;\n  --fb-color-muted: #5a6875;\n  --fb-color-faint: #9aa7b2;\n  --fb-color-hint: #b7c1cb;\n  --fb-color-border: #dce3ea;\n  --fb-color-border-soft: #e6ebf0;\n  --fb-color-surface: #ffffff;\n  --fb-color-card: #f6f8fa;\n  --fb-color-accent-bg: #eaf1fe;\n  --fb-color-success: #2f9e5b;\n  --fb-font-sans: \"IBM Plex Sans\", system-ui, -apple-system, \"Segoe UI\", Roboto,\n    Helvetica, Arial, sans-serif;\n  --fb-font-mono: \"IBM Plex Mono\", ui-monospace, \"SFMono-Regular\", Menlo, Consolas,\n    monospace;\n  all: initial;\n}\n\n*, *::before, *::after { box-sizing: border-box; }\n\n.fb-ob-backdrop {\n  position: fixed;\n  inset: 0;\n  z-index: 2147483010;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  padding: 24px;\n  background: rgba(15, 23, 32, 0.55);\n  backdrop-filter: blur(3px);\n  font-family: var(--fb-font-sans);\n  color: var(--fb-color-text);\n  animation: fb-ob-fade 0.25s ease both;\n}\n\n.fb-ob-panel {\n  width: 400px;\n  max-width: 100%;\n  background: var(--fb-color-surface);\n  border-radius: 16px;\n  box-shadow: 0 30px 70px rgba(15, 40, 70, 0.4);\n  overflow: hidden;\n  animation: fb-ob-pop 0.32s cubic-bezier(0.2, 0.8, 0.3, 1) both;\n}\n\n.fb-ob-head {\n  padding: 22px 24px 0;\n  display: flex;\n  align-items: center;\n  gap: 10px;\n}\n.fb-ob-mark {\n  width: 22px;\n  height: 22px;\n  border-radius: 6px;\n  background: var(--fb-color-accent);\n  flex: none;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n}\n.fb-ob-mark::after {\n  content: \"\";\n  width: 7px;\n  height: 7px;\n  border-radius: 2px;\n  background: #fff;\n}\n.fb-ob-brand { font-size: 15px; font-weight: 600; color: var(--fb-color-ink); }\n.fb-ob-chip {\n  margin-left: auto;\n  font-family: var(--fb-font-mono);\n  font-size: 10px;\n  color: #8a97a3;\n  border: 1px solid var(--fb-color-border-soft);\n  border-radius: 6px;\n  padding: 2px 7px;\n}\n\n.fb-ob-body { padding: 16px 24px 8px; }\n.fb-ob-title {\n  font-size: 19px;\n  font-weight: 700;\n  color: var(--fb-color-ink);\n  letter-spacing: -0.01em;\n}\n.fb-ob-lede {\n  font-size: 13.5px;\n  color: var(--fb-color-muted);\n  line-height: 1.5;\n  margin: 7px 0 0;\n}\n.fb-ob-lede strong { color: var(--fb-color-text); }\n\n.fb-ob-card {\n  margin: 16px 0;\n  padding: 13px 14px;\n  background: var(--fb-color-card);\n  border: 1px solid var(--fb-color-border-soft);\n  border-radius: 10px;\n  display: flex;\n  flex-direction: column;\n  gap: 10px;\n}\n.fb-ob-row { display: flex; align-items: center; gap: 10px; }\n.fb-ob-row + .fb-ob-row {\n  border-top: 1px solid #eef2f6;\n  padding-top: 10px;\n}\n.fb-ob-rowlabel {\n  font-family: var(--fb-font-mono);\n  font-size: 10px;\n  color: var(--fb-color-faint);\n  width: 70px;\n  flex: none;\n}\n.fb-ob-site { font-size: 13px; color: var(--fb-color-text); font-weight: 500; }\n.fb-ob-tier {\n  font-size: 11px;\n  font-weight: 600;\n  color: var(--fb-color-accent);\n  background: var(--fb-color-accent-bg);\n  padding: 3px 9px;\n  border-radius: 6px;\n}\n.fb-ob-tiernote { font-size: 11.5px; color: #8a97a3; }\n\n.fb-ob-fieldlabel {\n  display: block;\n  font-family: var(--fb-font-mono);\n  font-size: 10px;\n  letter-spacing: 0.05em;\n  text-transform: uppercase;\n  color: var(--fb-color-faint);\n  margin-bottom: 6px;\n}\n.fb-ob-fields { display: flex; gap: 8px; }\n.fb-ob-input {\n  height: 38px;\n  padding: 0 12px;\n  border: 1px solid var(--fb-color-border);\n  border-radius: 9px;\n  font-family: inherit;\n  font-size: 13px;\n  color: var(--fb-color-text);\n  outline: none;\n  min-width: 0;\n}\n.fb-ob-input:focus { border-color: var(--fb-color-accent); }\n.fb-ob-name { flex: 1; }\n.fb-ob-email { flex: 1.3; font-family: var(--fb-font-mono); font-size: 12.5px; color: var(--fb-color-muted); }\n\n.fb-ob-privacy {\n  display: flex;\n  align-items: flex-start;\n  gap: 8px;\n  margin-top: 14px;\n  font-size: 11.5px;\n  color: #8a97a3;\n  line-height: 1.5;\n}\n.fb-ob-privacy svg { flex: none; margin-top: 1px; }\n.fb-ob-privacy strong { color: var(--fb-color-muted); }\n\n.fb-ob-foot { padding: 16px 24px 22px; }\n.fb-ob-confirm {\n  width: 100%;\n  height: 44px;\n  border: 0;\n  border-radius: 11px;\n  background: var(--fb-color-accent);\n  color: var(--fb-color-on-emphasis);\n  font-family: inherit;\n  font-size: 14px;\n  font-weight: 600;\n  cursor: pointer;\n}\n.fb-ob-confirm:hover { background: var(--fb-color-accent-hover); }\n.fb-ob-confirm:disabled { opacity: 0.6; cursor: default; }\n\n@keyframes fb-ob-fade { from { opacity: 0; } to { opacity: 1; } }\n@keyframes fb-ob-pop {\n  from { opacity: 0; transform: translateY(8px) scale(0.98); }\n  to { opacity: 1; transform: none; }\n}\n\n@media (prefers-reduced-motion: reduce) {\n  .fb-ob-backdrop, .fb-ob-panel { animation: none; }\n}\n";

package/dist/onboarding.d.ts

@@ -1,44 +0,0 @@
-/**
- * The invite onboarding modal (spec §F) — the SDK-rendered redemption screen an
- * invited tester sees when a page carries an invite token. It shows the site
- * they were invited to, the **server-derived** access tier the redemption grants,
- * a private-by-default note, and a "Continue as" name / email, then confirms.
- *
- * Built to the frozen Signal Reporter prototype
- * (`docs/design/Fixback Reporter.dc.html`). It mounts lazily inside its own open
- * Shadow DOM so the host page is fully isolated, and — like the launcher and
- * overlay — never throws into the host page. It renders only data the SDK
- * truthfully holds: the site's own origin and the server-derived tier. The name /
- * email are **self-provided display fields**, never a trust signal (§F).
- */
-import type { ReporterTier } from "./boot";
-import type { ReporterDisplay } from "./invite";
-/** Marks the modal's host element in the light DOM, so it is findable and unique. */
-export declare const ONBOARDING_ATTRIBUTE = "data-fixback-onboard";
-/** Configuration for {@link createOnboardingModal}. */
-export interface OnboardingConfig {
-    /** The site the tester was invited to — its origin (`window.location.host`). */
-    readonly origin: string;
-    /** The **server-derived** tier the redemption grants (from the invite status). */
-    readonly tier: ReporterTier;
-    /** Prefill the Continue-as fields from a previously stored display identity. */
-    readonly defaults?: ReporterDisplay;
-    /** Called with the self-provided display fields when the tester confirms. */
-    readonly onConfirm: (display: ReporterDisplay) => void;
-    /** Where to mount the modal host. Defaults to `document.body`. */
-    readonly target?: HTMLElement;
-    /** The document to build in. Defaults to the target's owner document. */
-    readonly doc?: Document;
-}
-/** A mounted onboarding modal. */
-export interface OnboardingModal {
-    destroy(): void;
-    readonly host: HTMLElement;
-}
-/**
- * Render the onboarding modal into `target` (default `document.body`) and return a
- * handle to remove it. Confirming reads the name / email, fires `onConfirm` once
- * (further clicks are ignored while the caller redeems), and leaves teardown to
- * the caller so it can strip the token and mount the launcher first.
- */
-export declare function createOnboardingModal(config: OnboardingConfig): OnboardingModal;

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;