@fixback/sdk-core 0.2.0 → 0.3.0

package/{src/backoff.ts → dist/backoff.d.ts}

@@ -12,13 +12,10 @@
  * 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 const DEFAULT_RETRY_AFTER_SECONDS = 60;
-
+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
@@ -26,58 +23,26 @@ export const DEFAULT_RETRY_AFTER_SECONDS = 60;
  * the header is absent, blank, or unparseable. Ingest sends the delta-seconds form;
  * the date form is handled for spec-completeness.
  */
-export function parseRetryAfter(
-  header: string | null | undefined,
-  now: number,
-): number {
-  if (header == null) return DEFAULT_RETRY_AFTER_SECONDS;
-  const value = header.trim();
-  if (value === "") return DEFAULT_RETRY_AFTER_SECONDS;
-
-  if (/^\d+$/.test(value)) {
-    return Number(value);
-  }
-
-  const when = Date.parse(value);
-  if (!Number.isNaN(when)) {
-    return Math.max(0, Math.ceil((when - now) / 1000));
-  }
-
-  return DEFAULT_RETRY_AFTER_SECONDS;
-}
-
+export declare function parseRetryAfter(header: string | null | undefined, now: number): number;
 /**
  * A single pause window for automatic (`source: error`) reports. `hold` opens (or
  * extends) it from a `429`'s `Retry-After`; `isPaused` reports whether it is still
  * open. The default instance in the SDK's transport is shared across a page's
  * reports so the hold persists across successive automatic submissions.
  */
-export class AutoReportBackoff {
-  /** Epoch ms until which automatic reports are held; `0` when clear. */
-  private pausedUntil = 0;
-
-  constructor(private readonly now: Clock = Date.now) {}
-
-  /** Is the automatic-report pause window currently open? */
-  isPaused(): boolean {
-    return this.now() < this.pausedUntil;
-  }
-
-  /** Whole seconds remaining in the pause window (`0` when clear). */
-  retryAfterSeconds(): number {
-    return Math.max(0, Math.ceil((this.pausedUntil - this.now()) / 1000));
-  }
-
-  /**
-   * 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 {
-    const now = this.now();
-    const seconds = parseRetryAfter(retryAfterHeader, now);
-    const until = now + seconds * 1000;
-    if (until > this.pausedUntil) this.pausedUntil = until;
-    return seconds;
-  }
+export declare class AutoReportBackoff {
+    private readonly now;
+    /** Epoch ms until which automatic reports are held; `0` when clear. */
+    private pausedUntil;
+    constructor(now?: Clock);
+    /** Is the automatic-report 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

@@ -0,0 +1,148 @@
+/**
+ * The ingest **boot + feedback wire contract** — the one copy every capture SDK
+ * speaks (ADR-0028).
+ *
+ * The SDKs deliberately do not import `@fixback/shared` — that package is private
+ * and server-shaped (ticket #47) — so the exact slice they need lives here, in the
+ * shared core, rather than being vendored once per SDK. 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`).
+ *
+ * One runtime difference is carried as an option, not a fork: a browser attaches
+ * the `Origin` header itself, while a native HTTP stack attaches none — so React
+ * Native passes its configured `origin` and the server reads it to decide
+ * `originAllowed` exactly as it does for a browser request (spec 0004 §A).
+ */
+import { type FetchLike } from "./http";
+/** 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 an 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 no SDK sends one.
+ */
+export interface IdentityInputs {
+    /** A Host identity token minted by the customer's server (the escape hatch). */
+    readonly hostIdentity?: string;
+    /**
+     * The **Reporter session** token the SDK holds after a Connect (ADR-0032). The
+     * server checks it against the live session row and re-derives the Account's tier;
+     * a revoked, expired, or forged token is treated as absent (the anonymous branch),
+     * never an error. Replaces the removed device-local `reporterId` branch.
+     */
+    readonly reporterSession?: string;
+    /** The anonymous first-party identifier for a Public Reporter on an Open Project. */
+    readonly anonymousId?: string;
+}
+/** The JSON body `POST /api/ingest/boot` accepts. */
+export interface BootRequest extends IdentityInputs {
+    readonly key: string;
+}
+/**
+ * The signed-in Account a valid Reporter session resolves to, as the boot answer and
+ * the Connect exchange report it for the identity chip (ADR-0032). Name and email
+ * come from the `user`, never from anything the client set. `null`/absent means the
+ * caller is anonymous.
+ */
+export interface ConnectedAccount {
+    readonly name: string;
+    readonly email: 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 an 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) — browser only.
+     * 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. An SDK
+ * shows its launcher (or arms its gesture) 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;
+    /**
+     * Where the SDK opens **Connect** (ADR-0032) — the platform's connect page, built
+     * by the server from its configured dashboard origin and carried on every boot so
+     * the SDK does not need to know the Fixback dashboard origin itself. Absent from an
+     * older server; the SDK then cannot offer Connect.
+     */
+    readonly connectUrl?: string;
+    /**
+     * The signed-in Account when a valid Reporter session was presented, else `null`.
+     * Lets the identity chip show the person's name on a page reload, when the SDK holds
+     * only the stored token.
+     */
+    readonly account?: ConnectedAccount | null;
+    /**
+     * A **refreshed** Reporter session token when the presented one was valid (30-day
+     * sliding lifetime; ADR-0032). The SDK swaps its stored token for this on every
+     * boot, so an actively-used session never lapses. Absent when no valid session was
+     * presented.
+     */
+    readonly reporterSession?: string;
+}
+/** Join an API base URL with the boot path, tolerating a trailing slash. */
+export declare function bootEndpoint(apiUrl: string): string;
+/** Join an API base URL with the feedback path, tolerating a trailing slash. */
+export declare function feedbackEndpoint(apiUrl: string): string;
+/** Narrow an unknown JSON body to a {@link BootAnswer} before an SDK trusts it. */
+export declare function isBootAnswer(value: unknown): value is BootAnswer;
+/** Drop `undefined` identity fields so a payload carries only what was given. */
+export declare function compactIdentity(identity: IdentityInputs | undefined): IdentityInputs;
+/**
+ * Does `url` address one of the SDK's **own** API endpoints? Every request a capture
+ * SDK issues lives under two namespaces beneath the API origin: `/api/ingest/*` —
+ * boot and feedback — and `/api/connect/*` — the Connect code exchange and sign-out
+ * (ADR-0032).
+ *
+ * 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 an SDK makes — so a prefix test over the
+ * normalised origin is exact.
+ */
+export declare function isFixbackApiRequest(apiUrl: string, url: string): boolean;
+/** Injectable collaborators for {@link requestBoot}. */
+export interface BootDeps {
+    /** The `fetch` to call. Defaults to the runtime's global. */
+    readonly fetch?: FetchLike;
+    /**
+     * The origin to declare explicitly, for a runtime that attaches no `Origin`
+     * header of its own (React Native). Omit in a browser — the user agent sets it,
+     * and a page may not override it.
+     */
+    readonly origin?: 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 "stay dormant", so a Fixback outage stays
+ * invisible to the host app (ticket #47: "fails quietly").
+ */
+export declare function requestBoot(apiUrl: string, request: BootRequest, deps?: BootDeps): Promise<BootAnswer | null>;

package/dist/boot.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * The ingest **boot + feedback wire contract** — the one copy every capture SDK
+ * speaks (ADR-0028).
+ *
+ * The SDKs deliberately do not import `@fixback/shared` — that package is private
+ * and server-shaped (ticket #47) — so the exact slice they need lives here, in the
+ * shared core, rather than being vendored once per SDK. 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`).
+ *
+ * One runtime difference is carried as an option, not a fork: a browser attaches
+ * the `Origin` header itself, while a native HTTP stack attaches none — so React
+ * Native passes its configured `origin` and the server reads it to decide
+ * `originAllowed` exactly as it does for a browser request (spec 0004 §A).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bootEndpoint = bootEndpoint;
+exports.feedbackEndpoint = feedbackEndpoint;
+exports.isBootAnswer = isBootAnswer;
+exports.compactIdentity = compactIdentity;
+exports.isFixbackApiRequest = isFixbackApiRequest;
+exports.requestBoot = requestBoot;
+const http_1 = require("./http");
+/** Join an API base URL with the boot path, tolerating a trailing slash. */
+function bootEndpoint(apiUrl) {
+    return `${apiUrl.replace(/\/+$/, "")}/api/ingest/boot`;
+}
+/** Join an API base URL with the feedback path, tolerating a trailing slash. */
+function feedbackEndpoint(apiUrl) {
+    return `${apiUrl.replace(/\/+$/, "")}/api/ingest/feedback`;
+}
+/** Narrow an unknown JSON body to a {@link BootAnswer} before an SDK trusts it. */
+function isBootAnswer(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v.originAllowed === "boolean" &&
+        typeof v.canSubmit === "boolean" &&
+        typeof v.gate === "string" &&
+        (v.tier === null || typeof v.tier === "string"));
+}
+/** Drop `undefined` identity fields so a payload carries only what was given. */
+function compactIdentity(identity) {
+    if (!identity)
+        return {};
+    const out = {};
+    if (identity.hostIdentity)
+        out.hostIdentity = identity.hostIdentity;
+    if (identity.reporterSession)
+        out.reporterSession = identity.reporterSession;
+    if (identity.anonymousId)
+        out.anonymousId = identity.anonymousId;
+    return out;
+}
+/**
+ * Does `url` address one of the SDK's **own** API endpoints? Every request a capture
+ * SDK issues lives under two namespaces beneath the API origin: `/api/ingest/*` —
+ * boot and feedback — and `/api/connect/*` — the Connect code exchange and sign-out
+ * (ADR-0032).
+ *
+ * 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 an SDK makes — so a prefix test over the
+ * normalised origin is exact.
+ */
+function isFixbackApiRequest(apiUrl, url) {
+    const apiBase = apiUrl.replace(/\/+$/, "");
+    return (url.startsWith(`${apiBase}/api/ingest/`) ||
+        url.startsWith(`${apiBase}/api/connect/`));
+}
+/**
+ * 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 "stay dormant", so a Fixback outage stays
+ * invisible to the host app (ticket #47: "fails quietly").
+ */
+async function requestBoot(apiUrl, request, deps = {}) {
+    const doFetch = deps.fetch ?? (0, http_1.resolveFetch)();
+    if (!doFetch)
+        return null;
+    let response;
+    try {
+        response = await doFetch(bootEndpoint(apiUrl), {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                ...(deps.origin ? { origin: deps.origin } : {}),
+            },
+            body: JSON.stringify(request),
+        });
+    }
+    catch {
+        return null; // network error / Fixback unreachable
+    }
+    if (!response.ok)
+        return null; // 401 unknown key, or any other refusal
+    let body;
+    try {
+        body = await response.json?.();
+    }
+    catch {
+        return null;
+    }
+    return isBootAnswer(body) ? body : null;
+}
+//# sourceMappingURL=boot.js.map

package/dist/boot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"boot.js","sourceRoot":"","sources":["../src/boot.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;AAoGH,oCAEC;AAGD,4CAEC;AAGD,oCASC;AAGD,0CAWC;AAiBD,kDAMC;AAqBD,kCAgCC;AA/MD,iCAA8E;AAiG9E,4EAA4E;AAC5E,SAAgB,YAAY,CAAC,MAAc;IACzC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,kBAAkB,CAAC;AACzD,CAAC;AAED,gFAAgF;AAChF,SAAgB,gBAAgB,CAAC,MAAc;IAC7C,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,sBAAsB,CAAC;AAC7D,CAAC;AAED,mFAAmF;AACnF,SAAgB,YAAY,CAAC,KAAc;IACzC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,OAAO,CACL,OAAO,CAAC,CAAC,aAAa,KAAK,SAAS;QACpC,OAAO,CAAC,CAAC,SAAS,KAAK,SAAS;QAChC,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ;QAC1B,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAChD,CAAC;AACJ,CAAC;AAED,iFAAiF;AACjF,SAAgB,eAAe,CAAC,QAAoC;IAClE,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,CAAC;IACzB,MAAM,GAAG,GAIL,EAAE,CAAC;IACP,IAAI,QAAQ,CAAC,YAAY;QAAE,GAAG,CAAC,YAAY,GAAG,QAAQ,CAAC,YAAY,CAAC;IACpE,IAAI,QAAQ,CAAC,eAAe;QAAE,GAAG,CAAC,eAAe,GAAG,QAAQ,CAAC,eAAe,CAAC;IAC7E,IAAI,QAAQ,CAAC,WAAW;QAAE,GAAG,CAAC,WAAW,GAAG,QAAQ,CAAC,WAAW,CAAC;IACjE,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,mBAAmB,CAAC,MAAc,EAAE,GAAW;IAC7D,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC3C,OAAO,CACL,GAAG,CAAC,UAAU,CAAC,GAAG,OAAO,cAAc,CAAC;QACxC,GAAG,CAAC,UAAU,CAAC,GAAG,OAAO,eAAe,CAAC,CAC1C,CAAC;AACJ,CAAC;AAcD;;;;;;GAMG;AACI,KAAK,UAAU,WAAW,CAC/B,MAAc,EACd,OAAoB,EACpB,OAAiB,EAAE;IAEnB,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,IAAI,IAAA,mBAAY,GAAE,CAAC;IAC7C,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAE1B,IAAI,QAA2B,CAAC;IAChC,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE;YAC7C,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAChD;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;SAC9B,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC,CAAC,sCAAsC;IACrD,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,EAAE;QAAE,OAAO,IAAI,CAAC,CAAC,wCAAwC;IAEvE,IAAI,IAAa,CAAC;IAClB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1C,CAAC"}

package/dist/breadcrumb.d.ts

@@ -0,0 +1,133 @@
+/**
+ * The trace **breadcrumb wire types** (spec 0003 §C, spec #122) — the shared,
+ * runtime-agnostic shapes for one entry of a captured trace stream (ADR-0028).
+ *
+ * A breadcrumb records recent activity — console, navigation, network metadata,
+ * masked user actions, and the failing error — that rides on a report as
+ * Evidence. This module carries only the value types; the SDK's ring buffer and
+ * DOM/Node instrumentation that produce them live in the consuming SDK.
+ * Everything private is kept out **at the source** by that instrumentation:
+ * `ui.input` records that an input changed, never its value; network crumbs carry
+ * method + URL + status only, never bodies.
+ */
+/** Console-style severity a `console` crumb records. */
+export type BreadcrumbLevel = "log" | "info" | "warn" | "error" | "assert" | "debug";
+/** The kind of activity a crumb records. */
+export type BreadcrumbCategory = "console" | "navigation" | "fetch" | "xhr" | "beacon" | "ui.click" | "ui.input" | "error";
+/**
+ * Which browser API issued a captured network request (spec #122 §D, ticket #139).
+ * Every network crumb's `category` is one of these too, so a stream router and the
+ * read model agree on what is a network entry.
+ */
+export type NetworkApi = "fetch" | "xhr" | "beacon";
+/**
+ * A network request's failure classification (spec #122 §D, ticket #139). `ok` and
+ * the HTTP status classes come from a settled response; `network-error` / `timeout`
+ * / `aborted` from how a request failed; `opaque-cors` from a cross-origin response
+ * whose status is unreadable. The Network tab flags every non-`ok` outcome.
+ */
+export type NetworkOutcome = "ok" | "http-4xx" | "http-5xx" | "network-error" | "timeout" | "aborted" | "opaque-cors";
+/**
+ * A crumb's structured detail. Deliberately narrow: there is **no** field for a
+ * request/response body or an input value, so those can never be recorded.
+ */
+export interface BreadcrumbData {
+    readonly url?: string;
+    readonly method?: string;
+    readonly status?: number;
+    /** A masked CSS selector for a `ui.*` target — never its text or value. */
+    readonly target?: string;
+    readonly from?: string;
+    readonly to?: string;
+    readonly errorType?: string;
+}
+/**
+ * The type tag on a structured console argument (spec #122 §C, decision D7). A
+ * console call's arguments are preserved **type-tagged** rather than flattened to a
+ * string, so an object/array argument can be inspected in the Console tab rather
+ * than read as `[object Object]`: `string`/`number`/`bool`/`null` carry the value
+ * directly, `json` a depth-/byte-capped JSON-safe clone, and `error` an Error's
+ * `{ name, message, stack }`.
+ */
+export type ConsoleArgType = "string" | "number" | "bool" | "null" | "json" | "error";
+/**
+ * One structured console argument (spec #122 §C): a type tag plus a JSON-safe value.
+ * `v` is always serializable — a `json` arg is depth-, breadth-, and string-capped at
+ * assembly, and exotic values (bigint, symbol, function, circular refs) are rendered
+ * to safe text — so a console crumb can never carry an unserializable or unbounded
+ * value onto the wire.
+ */
+export interface ConsoleArg {
+    readonly t: ConsoleArgType;
+    readonly v: unknown;
+}
+/** A `file:line` source location (spec #122 §C) — where a console call was made. */
+export interface SourceLocation {
+    readonly file: string;
+    readonly line: number;
+}
+/**
+ * One entry in a trace stream. Alongside its semantic fields every entry carries a
+ * stable {@link id} and a high-res monotonic {@link mono} timestamp — both stamped
+ * by the buffer on `add` — so entries from the three independent streams order and
+ * cross-link exactly (spec #122 §B, decision D9). `timestamp` stays epoch ms.
+ */
+export interface Breadcrumb {
+    readonly category: BreadcrumbCategory;
+    readonly message?: string;
+    readonly level?: BreadcrumbLevel;
+    /** Epoch milliseconds when the crumb was recorded. */
+    readonly timestamp: number;
+    /** A stable id, unique within the buffer — assigned on `add` when not already set. */
+    readonly id?: string;
+    /** A high-res monotonic timestamp (`performance.now()`) — assigned on `add`. */
+    readonly mono?: number;
+    readonly data?: BreadcrumbData;
+    /**
+     * For a `console` crumb (spec #122 §C): the call's arguments preserved as
+     * structured, type-tagged values (see {@link ConsoleArg}), so the Console tab can
+     * render each argument expandably instead of a flattened string. `message` stays
+     * the one-line preview. Absent on non-console crumbs.
+     */
+    readonly args?: readonly ConsoleArg[];
+    /**
+     * For a `console` crumb (spec #122 §C): the `file:line` the call was made from,
+     * parsed best-effort from the call stack. Captured only for the levels that keep a
+     * source — `warn`/`error`/`assert` — and only when the stack yields a usable
+     * location; a chatty app's `log`/`info`/`debug` omit it. Absent on non-console crumbs.
+     */
+    readonly source?: SourceLocation;
+    /**
+     * For an auto-captured `error` crumb only (spec #122 §F): the ids of the entries
+     * immediately preceding the throw — a causal pointer into the same trace, so a
+     * machine-filed crash names its lead-up. Absent on every other crumb.
+     */
+    readonly causedBy?: readonly string[];
+    /**
+     * For a network crumb (`fetch` / `xhr` / `beacon`) — spec #122 §D, ticket #139.
+     * The rich request metadata the Network tab renders, lifted to the top level (the
+     * console-enrichment precedent) so the read model shapes each into a
+     * `NetworkTraceEntry`. **No field carries a request/response body or an arbitrary
+     * header** — `respSize` derives from the `content-length` response header only and
+     * `contentType` from `content-type`; nothing else is read. Absent on every other crumb.
+     */
+    readonly api?: NetworkApi;
+    /** The request method (network crumb) — e.g. `GET`, `POST`. */
+    readonly method?: string;
+    /** The scrubbed request URL (network crumb) — query dropped, path PII redacted. */
+    readonly url?: string;
+    /** The final HTTP status (network crumb), when one was known; absent on a network error/beacon. */
+    readonly status?: number;
+    /** The HTTP status text (network crumb), when the response carried one. */
+    readonly statusText?: string;
+    /** Wall-clock duration of the request in ms (network crumb) — a `performance.now()` delta. */
+    readonly durationMs?: number;
+    /** Request body size in bytes (network crumb) — only when trivially known (string/Blob/ArrayBuffer), never by reading a stream. */
+    readonly reqSize?: number;
+    /** Response body size in bytes (network crumb) — from the `content-length` response header only. */
+    readonly respSize?: number;
+    /** Response content type (network crumb) — the `content-type` header's media type. */
+    readonly contentType?: string;
+    /** The request's failure classification (network crumb) — see {@link NetworkOutcome}. */
+    readonly outcome?: NetworkOutcome;
+}

package/dist/connect.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The **Connect** wire contract (ADR-0032, CONTEXT.md "Connect") — the one copy every
+ * capture SDK speaks, kept in the shared core beside the boot contract for the same
+ * reason (`@fixback/shared` is server-shaped and private, ticket #47).
+ *
+ * Connect is the round trip that binds an Account to a site: the SDK opens the
+ * platform's connect page ({@link BootAnswer.connectUrl}), the person signs in, the
+ * page hands back a **one-time code**, and the SDK exchanges it here for a **Reporter
+ * session** — a compact token it stores per origin and forwards on every boot. Keep
+ * this in lock-step with the server: `POST /api/connect/exchange` and
+ * `POST /api/connect/signout` (`apps/api/src/connect/*`).
+ */
+import type { ConnectedAccount, ReporterTier } from "./boot";
+import { type FetchLike } from "./http";
+/**
+ * The `postMessage` a connect page in a popup sends back to the opener. `source`
+ * pins it to Fixback so an unrelated message on the window is ignored; `code` is the
+ * one-time Connect code to exchange. Read with {@link parseConnectMessage}.
+ */
+export declare const CONNECT_MESSAGE_SOURCE = "fixback-connect";
+/**
+ * The query parameter a Fixback link — and the connect page's **redirect fallback** —
+ * carries the one-time code back on, when a popup could not be used (ADR-0032,
+ * "arriving with the `fixback` query parameter"). The SDK detects it on boot, exchanges
+ * it, and strips it from the URL.
+ */
+export declare const CONNECT_RETURN_PARAM = "fixback";
+/** The shape of the popup-to-opener message; `code` is the one-time Connect code. */
+export interface ConnectMessage {
+    readonly source: typeof CONNECT_MESSAGE_SOURCE;
+    readonly code: string;
+}
+/**
+ * The identity the SDK reports through `Fixback.identity()` and renders in the chip:
+ * anonymous, or a connected Account with its live tier. The tier is the server's, from
+ * the last boot — never self-declared.
+ */
+export type ReporterIdentity = {
+    readonly status: "anonymous";
+} | {
+    readonly status: "connected";
+    readonly name: string;
+    readonly email: string;
+    readonly tier: ReporterTier | null;
+};
+/** The JSON body `POST /api/connect/exchange` accepts. */
+export interface ConnectExchangeRequest {
+    /** The Project's publishable key — the exchange must be for the code's Project. */
+    readonly key: string;
+    /** The one-time Connect code from the popup message or the return query parameter. */
+    readonly code: string;
+    /**
+     * The browser's current anonymous id, if any — so the server can link the existing
+     * anonymous Reporter to the Account (one Reporter, prior Feedback attributed).
+     */
+    readonly anonymousId?: string;
+    /** The Platform the Connect happened on; defaults to `browser` server-side. */
+    readonly platform?: "browser" | "expo";
+}
+/** The JSON `POST /api/connect/exchange` returns on success. */
+export interface ConnectExchangeResponse {
+    /** The Reporter session token to store per origin and forward on every boot. */
+    readonly reporterSession: string;
+    /** The signed-in Account, for the identity chip. */
+    readonly account: ConnectedAccount;
+}
+/** Join an API base URL with the Connect exchange path, tolerating a trailing slash. */
+export declare function connectExchangeEndpoint(apiUrl: string): string;
+/** Join an API base URL with the Connect sign-out path, tolerating a trailing slash. */
+export declare function connectSignOutEndpoint(apiUrl: string): string;
+/**
+ * Build the connect-page URL the SDK opens (popup or redirect). `connectUrl` is the
+ * base the boot answer carried; `key` identifies the Project and `returnUrl` is where
+ * the person is sent back — validated server-side against the Project's allowed
+ * origins, so a hostile page cannot redirect the code anywhere else.
+ */
+export declare function buildConnectUrl(connectUrl: string, params: {
+    readonly key: string;
+    readonly returnUrl: string;
+}): string;
+/**
+ * The `localStorage` key a browser SDK stores its Reporter session token under,
+ * **scoped by publishable key** so two Fixback Projects on one origin keep separate
+ * sessions (ADR-0032). The storage binding is per-runtime; the key format is shared.
+ */
+export declare function reporterSessionStorageKey(publishableKey: string): string;
+/**
+ * Narrow an unknown `message.data` to the Connect code it carries, or `null`. Guards
+ * `source` so an unrelated `postMessage` — the web is noisy — is ignored.
+ */
+export declare function parseConnectMessage(data: unknown): string | null;
+/** Narrow an unknown JSON body to a {@link ConnectExchangeResponse}. */
+export declare function isConnectExchangeResponse(value: unknown): value is ConnectExchangeResponse;
+/** Injectable collaborators for the Connect fetch helpers. */
+export interface ConnectDeps {
+    readonly fetch?: FetchLike;
+}
+/**
+ * Exchange a one-time code for a Reporter session. Resolves to the response, or `null`
+ * when Fixback was unreachable, the code was refused, or the body was not a valid
+ * response — the caller stays anonymous rather than surfacing an error into the host
+ * page (ticket #47: "fails quietly").
+ */
+export declare function exchangeConnectCode(apiUrl: string, request: ConnectExchangeRequest, deps?: ConnectDeps): Promise<ConnectExchangeResponse | null>;
+/**
+ * Revoke a Reporter session server-side ("sign out"). Best-effort: a network failure
+ * still lets the SDK clear its stored token locally, and a revoked-anyway token is
+ * refused at the next boot regardless.
+ */
+export declare function revokeReporterSession(apiUrl: string, token: string, deps?: ConnectDeps): Promise<void>;