@fixback/expo 0.1.0

package/dist/error-capture.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Automatic error capture on React Native — ADR-0011's model with mobile
+ * triggers (spec 0004 §E), ported from `packages/sdk/src/error-capture.ts`.
+ *
+ * Uncaught JS errors arrive through `ErrorUtils.setGlobalHandler` — React
+ * Native's one global error seam — and become `source: auto`, `Kind = bug`
+ * Feedback for the current session's Reporter. The **previous handler is always
+ * chained afterwards**, so dev redboxes and other crash reporters keep working.
+ * Each firing is deduped by a per-session fingerprint, rate-limited by a
+ * token-bucket burst limiter and a per-session cap, scrubbed through the same
+ * `beforeSend` choke point as manual reports, and shipped through the same
+ * transport (which honours ingest's `429` / `Retry-After` backpressure).
+ *
+ * Per-firing order: **`canSubmit`/Gate → dedup → rate-limit/cap → `beforeSend`
+ * scrub → enqueue Feedback**. The Gate is honoured by construction: the client
+ * installs this only when boot returned `canSubmit`. Occurrence-count flushes
+ * ride `AppState` → `background`/`inactive` (the `pagehide` equivalent).
+ * Unhandled promise rejections have no stable public Hermes hook and are not
+ * captured (ADR-0021 "Revisit when").
+ *
+ * The whole module is defensive — a Fixback problem (or an error thrown while
+ * capturing an error) never surfaces in the host app.
+ */
+import type { IdentityInputs } from "./boot";
+import { type BreadcrumbBuffer, type Teardown } from "./breadcrumbs";
+import { type EnvironmentInputs } from "./report";
+import { type BeforeSend } from "./scrub";
+import { type SubmitDeps, type SubmitInput, type SubmitResult } from "./submit";
+export type { Teardown };
+/** Burst limiter capacity — how many auto-reports may fire back-to-back. */
+export declare const DEFAULT_BURST_CAPACITY = 5;
+/** Burst limiter refill — one token returns every this-many ms. */
+export declare const DEFAULT_BURST_REFILL_MS = 2000;
+/** Per-session ceiling on distinct auto-Feedback; beyond it, only a dropped-count. */
+export declare const DEFAULT_MAX_DISTINCT_AUTO = 20;
+/**
+ * Collapse the volatile parts of an error message so a changing string doesn't
+ * split one bug: UUIDs, URLs, `0x…` and long hex runs, and long digit runs are
+ * replaced with stable placeholders. Short numbers and stable text are kept so
+ * genuinely distinct bugs stay distinct.
+ */
+export declare function normalize(value: string): string;
+/**
+ * A dependency-free FNV-1a hash rendered in base-36. It only has to be stable
+ * and well-distributed within one session (the client key is a flood guard; the
+ * server does canonical cross-session clustering).
+ */
+export declare function hashString(input: string): string;
+/**
+ * Extract a compact, stable signature of the top frames of a stack: up to
+ * {@link FINGERPRINT_FRAME_LIMIT} frames as `function@basename:line:col`,
+ * origin and cache-busting query stripped. Returns `""` when there is no
+ * usable stack (message-only fallback).
+ */
+export declare function extractTopFrames(stack: string | undefined, limit?: number): string;
+/**
+ * The per-session fingerprint:
+ * `hash(errorType + "|" + normalize(value) + "|" + topFrames)`. Stack frames
+ * dominate when present; otherwise it falls back to type + normalized value.
+ */
+export declare function computeFingerprint(type: string, value: string, stack?: string): string;
+/** Configuration for {@link TokenBucket}. */
+export interface TokenBucketOptions {
+    readonly capacity: number;
+    readonly refillIntervalMs: number;
+    /** Clock source, injectable for tests. Defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+/**
+ * A token bucket: starts full at `capacity`, refills one token every
+ * `refillIntervalMs`, and refuses (`take() === false`) when empty. So a fast
+ * error loop that dodges dedup with distinct fingerprints still can't
+ * machine-gun ingest.
+ */
+export declare class TokenBucket {
+    private readonly options;
+    private tokens;
+    private last;
+    private readonly now;
+    constructor(options: TokenBucketOptions);
+    /** Consume a token if one is available (refilling first), else refuse. */
+    take(): boolean;
+}
+/** React Native's global error handler signature. */
+export type GlobalErrorHandler = (error: unknown, isFatal?: boolean) => void;
+/** The `ErrorUtils` surface the capture uses — injectable for tests. */
+export interface ErrorUtilsLike {
+    getGlobalHandler?: () => GlobalErrorHandler | null | undefined;
+    setGlobalHandler: (handler: GlobalErrorHandler | null) => void;
+}
+/** React Native's global `ErrorUtils`, when present. */
+export declare function globalErrorUtils(): ErrorUtilsLike | undefined;
+/** A removable native event subscription. */
+export interface AppStateSubscription {
+    remove(): void;
+}
+/** The `AppState` slice the flush hook uses — injectable for tests. */
+export interface AppStateLike {
+    addEventListener(type: "change", listener: (state: string) => void): AppStateSubscription;
+}
+/**
+ * Injectable collaborators, defaulted to the real implementations.
+ *
+ * Deliberately screenshot-free: a `source: auto` report on mobile never
+ * attaches a screenshot. The composer's compensating privacy controls —
+ * preview and removal by the Reporter — cannot exist on a machine-filed
+ * report, and there is no client-side masking on mobile, so an auto
+ * screenshot would ship whatever sensitive screen happened to be open
+ * (ADR-0021; spec 0004 §E).
+ */
+export interface AutoCaptureDeps {
+    readonly submitReport: (apiUrl: string, input: SubmitInput, deps?: SubmitDeps) => Promise<SubmitResult>;
+}
+/** The Reporter's self-provided display name / email — display only. */
+export interface ReporterDisplay {
+    readonly name?: string;
+    readonly email?: string;
+}
+/** Configuration for {@link installErrorCapture}. */
+export interface AutoCaptureConfig {
+    readonly apiUrl: string;
+    readonly key: string;
+    /** The configured origin, forwarded on every submission (spec 0004 §A). */
+    readonly origin: string;
+    readonly identity?: IdentityInputs;
+    /** Display-only name/email carried on auto-captured Feedback too. */
+    readonly display?: ReporterDisplay;
+    readonly sdkVersion?: string;
+    /** The shared trace buffer; the failing error is added to it before filing. */
+    readonly buffer?: BreadcrumbBuffer | null;
+    /** Per-project client scrub hook, run at the `beforeSend` choke point. */
+    readonly beforeSend?: BeforeSend;
+    /** Run the built-in default scrubbers. Defaults to `true`. */
+    readonly scrub?: boolean;
+    /** Reads the device environment at filing time. */
+    readonly environment?: () => EnvironmentInputs;
+    /** The report `url` at filing time (`<origin>/<screen>` or the origin). */
+    readonly currentUrl?: () => string | undefined;
+    /** The `ErrorUtils` seam. Defaults to the React Native global. */
+    readonly errorUtils?: ErrorUtilsLike | null;
+    /** The `AppState` seam for occurrence flushes. Optional. */
+    readonly appState?: AppStateLike | null;
+    readonly deps?: Partial<AutoCaptureDeps>;
+    /** Burst limiter capacity. Defaults to {@link DEFAULT_BURST_CAPACITY}. */
+    readonly burstCapacity?: number;
+    /** Burst limiter refill interval (ms). Defaults to {@link DEFAULT_BURST_REFILL_MS}. */
+    readonly burstRefillMs?: number;
+    /** Per-session distinct-Feedback cap. Defaults to {@link DEFAULT_MAX_DISTINCT_AUTO}. */
+    readonly maxDistinct?: number;
+    /** Clock source, injectable for tests. Defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+/** A running auto-capture: its teardown, plus the local dropped-count. */
+export interface AutoCaptureHandle {
+    /** Restore the previous handler and remove the flush hook. Safe to repeat. */
+    readonly destroy: Teardown;
+    /** Distinct auto-Feedback dropped by the burst limiter or the session cap. */
+    droppedCount(): number;
+}
+/**
+ * Install automatic error capture through `ErrorUtils` and return a handle
+ * whose `destroy` restores the previous global handler and removes the flush
+ * hook. The caller installs this only after boot returned `canSubmit`, so the
+ * Gate is respected and the auto-error inherits the session Reporter's tier.
+ * Without a usable `ErrorUtils` (no `getGlobalHandler` to restore from) nothing
+ * is installed — the SDK never replaces a handler it could not put back.
+ */
+export declare function installErrorCapture(config: AutoCaptureConfig): AutoCaptureHandle;

package/dist/error-capture.js

@@ -0,0 +1,395 @@
+/**
+ * Automatic error capture on React Native — ADR-0011's model with mobile
+ * triggers (spec 0004 §E), ported from `packages/sdk/src/error-capture.ts`.
+ *
+ * Uncaught JS errors arrive through `ErrorUtils.setGlobalHandler` — React
+ * Native's one global error seam — and become `source: auto`, `Kind = bug`
+ * Feedback for the current session's Reporter. The **previous handler is always
+ * chained afterwards**, so dev redboxes and other crash reporters keep working.
+ * Each firing is deduped by a per-session fingerprint, rate-limited by a
+ * token-bucket burst limiter and a per-session cap, scrubbed through the same
+ * `beforeSend` choke point as manual reports, and shipped through the same
+ * transport (which honours ingest's `429` / `Retry-After` backpressure).
+ *
+ * Per-firing order: **`canSubmit`/Gate → dedup → rate-limit/cap → `beforeSend`
+ * scrub → enqueue Feedback**. The Gate is honoured by construction: the client
+ * installs this only when boot returned `canSubmit`. Occurrence-count flushes
+ * ride `AppState` → `background`/`inactive` (the `pagehide` equivalent).
+ * Unhandled promise rejections have no stable public Hermes hook and are not
+ * captured (ADR-0021 "Revisit when").
+ *
+ * The whole module is defensive — a Fixback problem (or an error thrown while
+ * capturing an error) never surfaces in the host app.
+ */
+import { errorCrumb, } from "./breadcrumbs";
+import { assembleContent, collectEnvironment, } from "./report";
+import { runBeforeSend } from "./scrub";
+import { submitReport, } from "./submit";
+import { EXPO_SDK_VERSION } from "./version";
+/** Burst limiter capacity — how many auto-reports may fire back-to-back. */
+export const DEFAULT_BURST_CAPACITY = 5;
+/** Burst limiter refill — one token returns every this-many ms. */
+export const DEFAULT_BURST_REFILL_MS = 2_000;
+/** Per-session ceiling on distinct auto-Feedback; beyond it, only a dropped-count. */
+export const DEFAULT_MAX_DISTINCT_AUTO = 20;
+/** How many top stack frames feed the fingerprint. */
+const FINGERPRINT_FRAME_LIMIT = 5;
+/** How many preceding entries an auto-error's causal pointer names. */
+const CAUSED_BY_LIMIT = 5;
+/**
+ * The ids of up to the last {@link CAUSED_BY_LIMIT} entries preceding the
+ * throw, in time order — the causal pointer an auto-captured error carries so a
+ * machine-filed crash names its lead-up. Entries without an id are skipped.
+ */
+function precedingIds(entries) {
+    if (!entries || entries.length === 0)
+        return [];
+    const ids = [];
+    for (let i = entries.length - 1; i >= 0 && ids.length < CAUSED_BY_LIMIT; i -= 1) {
+        const id = entries[i]?.id;
+        if (typeof id === "string" && id.length > 0)
+            ids.unshift(id);
+    }
+    return ids;
+}
+// --- Fingerprint (per-session flood-guard key) --------------------------------
+const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi;
+const URL_RE = /\bhttps?:\/\/[^\s"')]+/gi;
+const HEX_0X_RE = /\b0x[0-9a-f]+\b/gi;
+const HEX_RUN_RE = /\b[0-9a-f]{8,}\b/gi;
+const DIGIT_RUN_RE = /\d{4,}/g;
+/**
+ * Collapse the volatile parts of an error message so a changing string doesn't
+ * split one bug: UUIDs, URLs, `0x…` and long hex runs, and long digit runs are
+ * replaced with stable placeholders. Short numbers and stable text are kept so
+ * genuinely distinct bugs stay distinct.
+ */
+export function normalize(value) {
+    if (typeof value !== "string" || value.length === 0)
+        return "";
+    return value
+        .replace(UUID_RE, "<uuid>")
+        .replace(URL_RE, "<url>")
+        .replace(HEX_0X_RE, "<hex>")
+        .replace(HEX_RUN_RE, "<hex>")
+        .replace(DIGIT_RUN_RE, "<n>")
+        .trim();
+}
+/**
+ * A dependency-free FNV-1a hash rendered in base-36. It only has to be stable
+ * and well-distributed within one session (the client key is a flood guard; the
+ * server does canonical cross-session clustering).
+ */
+export function hashString(input) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < input.length; i++) {
+        h ^= input.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(36);
+}
+/** Reduce a frame location to `basename:line:col`, dropping origin and query. */
+function compactLocation(location) {
+    const noQuery = location.replace(/\?[^:]*/, "");
+    const lastSlash = noQuery.lastIndexOf("/");
+    return lastSlash >= 0 ? noQuery.slice(lastSlash + 1) : noQuery;
+}
+/** Parse one stack line into a compact `function@basename:line:col` frame id. */
+function parseFrame(line) {
+    // V8 / Hermes: "at fn (loc)"  |  "at loc"
+    const v8Named = line.match(/^at\s+(.+?)\s+\((.+)\)$/);
+    if (v8Named)
+        return `${v8Named[1] ?? ""}@${compactLocation(v8Named[2] ?? "")}`;
+    const v8Bare = line.match(/^at\s+(.+)$/);
+    if (v8Bare)
+        return `@${compactLocation(v8Bare[1] ?? "")}`;
+    // JSC: "fn@loc"  |  "@loc"
+    const at = line.indexOf("@");
+    if (at >= 0) {
+        const fn = line.slice(0, at);
+        return `${fn}@${compactLocation(line.slice(at + 1))}`;
+    }
+    return null;
+}
+/**
+ * Extract a compact, stable signature of the top frames of a stack: up to
+ * {@link FINGERPRINT_FRAME_LIMIT} frames as `function@basename:line:col`,
+ * origin and cache-busting query stripped. Returns `""` when there is no
+ * usable stack (message-only fallback).
+ */
+export function extractTopFrames(stack, limit = FINGERPRINT_FRAME_LIMIT) {
+    if (typeof stack !== "string" || stack.length === 0)
+        return "";
+    const frames = [];
+    for (const raw of stack.split("\n")) {
+        const frame = parseFrame(raw.trim());
+        if (frame) {
+            frames.push(frame);
+            if (frames.length >= limit)
+                break;
+        }
+    }
+    return frames.join(" < ");
+}
+/**
+ * The per-session fingerprint:
+ * `hash(errorType + "|" + normalize(value) + "|" + topFrames)`. Stack frames
+ * dominate when present; otherwise it falls back to type + normalized value.
+ */
+export function computeFingerprint(type, value, stack) {
+    return hashString(`${type}|${normalize(value)}|${extractTopFrames(stack)}`);
+}
+/**
+ * A token bucket: starts full at `capacity`, refills one token every
+ * `refillIntervalMs`, and refuses (`take() === false`) when empty. So a fast
+ * error loop that dodges dedup with distinct fingerprints still can't
+ * machine-gun ingest.
+ */
+export class TokenBucket {
+    options;
+    tokens;
+    last;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? Date.now;
+        this.tokens = Math.max(0, options.capacity);
+        this.last = this.now();
+    }
+    /** Consume a token if one is available (refilling first), else refuse. */
+    take() {
+        const now = this.now();
+        const { capacity, refillIntervalMs } = this.options;
+        if (refillIntervalMs > 0 && now > this.last) {
+            const refill = Math.floor((now - this.last) / refillIntervalMs);
+            if (refill > 0) {
+                this.tokens = Math.min(capacity, this.tokens + refill);
+                this.last += refill * refillIntervalMs;
+            }
+        }
+        if (this.tokens >= 1) {
+            this.tokens -= 1;
+            return true;
+        }
+        return false;
+    }
+}
+function asString(value) {
+    if (typeof value === "string")
+        return value;
+    if (value == null)
+        return "";
+    try {
+        return String(value);
+    }
+    catch {
+        return "";
+    }
+}
+/** Distil whatever `ErrorUtils` handed us into a fingerprint-able shape. */
+function extractGlobalError(error) {
+    if (error && typeof error === "object") {
+        const err = error;
+        return {
+            type: asString(err.name) || "Error",
+            value: asString(err.message) || asString(error),
+            stack: typeof err.stack === "string" ? err.stack : undefined,
+            original: error,
+        };
+    }
+    const value = asString(error);
+    return { type: "Error", value, original: error ?? value };
+}
+/** React Native's global `ErrorUtils`, when present. */
+export function globalErrorUtils() {
+    const g = globalThis;
+    const utils = g.ErrorUtils;
+    return utils && typeof utils.setGlobalHandler === "function" ? utils : undefined;
+}
+const NOOP_HANDLE = { destroy: () => { }, droppedCount: () => 0 };
+/**
+ * Install automatic error capture through `ErrorUtils` and return a handle
+ * whose `destroy` restores the previous global handler and removes the flush
+ * hook. The caller installs this only after boot returned `canSubmit`, so the
+ * Gate is respected and the auto-error inherits the session Reporter's tier.
+ * Without a usable `ErrorUtils` (no `getGlobalHandler` to restore from) nothing
+ * is installed — the SDK never replaces a handler it could not put back.
+ */
+export function installErrorCapture(config) {
+    const errorUtils = config.errorUtils === null ? undefined : config.errorUtils ?? globalErrorUtils();
+    if (!errorUtils ||
+        typeof errorUtils.setGlobalHandler !== "function" ||
+        typeof errorUtils.getGlobalHandler !== "function") {
+        return NOOP_HANDLE;
+    }
+    const now = config.now ?? Date.now;
+    const sdkVersion = config.sdkVersion ?? EXPO_SDK_VERSION;
+    const maxDistinct = config.maxDistinct ?? DEFAULT_MAX_DISTINCT_AUTO;
+    const submitReportFn = config.deps?.submitReport ?? submitReport;
+    const readEnvironment = config.environment ?? (() => ({}));
+    const bucket = new TokenBucket({
+        capacity: config.burstCapacity ?? DEFAULT_BURST_CAPACITY,
+        refillIntervalMs: config.burstRefillMs ?? DEFAULT_BURST_REFILL_MS,
+        now,
+    });
+    const seen = new Map();
+    /** Distinct auto-Feedback dropped by the burst limiter or the session cap. */
+    let dropped = 0;
+    /** Build the `source: auto` content for a fingerprint at a given count. */
+    function buildContent(fp, occurrences, opts) {
+        let environment;
+        try {
+            environment = collectEnvironment(readEnvironment(), sdkVersion);
+        }
+        catch {
+            environment = collectEnvironment({}, sdkVersion);
+        }
+        // No Kind rides along (ADR-0023): the server stamps a `source: auto`
+        // Issue `bug` deterministically.
+        const base = assembleContent({
+            url: config.currentUrl?.(),
+            environment,
+            trace: opts.trace ? config.buffer?.snapshot() : undefined,
+            reporterName: config.display?.name,
+            reporterEmail: config.display?.email,
+        });
+        return { ...base, source: "auto", errorSignature: fp, occurrences };
+    }
+    /**
+     * Assemble, scrub, and ship one auto-Feedback (never a screenshot — see
+     * {@link AutoCaptureDeps}). Sets the entry's `sentCount` optimistically so a
+     * concurrent flush never double-sends, and rolls it back on a failed send so
+     * the flush can retry. A `beforeSend` that returns `null` drops the report
+     * without transport.
+     */
+    async function file(fp, occurrences, opts) {
+        const entry = seen.get(fp);
+        if (!entry)
+            return;
+        const previouslySent = entry.sentCount;
+        entry.sentCount = occurrences;
+        try {
+            const draft = buildContent(fp, occurrences, opts);
+            const content = runBeforeSend(draft, {
+                hook: config.beforeSend,
+                scrub: config.scrub,
+            });
+            if (!content)
+                return; // dropped at the client scrub choke point — no transport.
+            const result = await submitReportFn(config.apiUrl, {
+                key: config.key,
+                origin: config.origin,
+                identity: config.identity,
+                content,
+                screenshot: null,
+            });
+            if (!result.ok && entry.sentCount === occurrences) {
+                // Held under backpressure, refused, or unreachable — let a flush retry.
+                entry.sentCount = previouslySent;
+            }
+        }
+        catch {
+            if (entry.sentCount === occurrences)
+                entry.sentCount = previouslySent;
+            // The error path must never throw into the host app.
+        }
+    }
+    /** Handle one distilled error: dedup → burst limiter → session cap → file. */
+    function handle(extracted) {
+        const fp = computeFingerprint(extracted.type, extracted.value, extracted.stack);
+        const existing = seen.get(fp);
+        if (existing) {
+            // Dedup: one Feedback per fingerprint per session; count locally.
+            existing.count += 1;
+            existing.lastAt = now();
+            return;
+        }
+        if (!bucket.take()) {
+            dropped += 1; // burst limiter
+            return;
+        }
+        if (seen.size >= maxDistinct) {
+            dropped += 1; // per-session cap — keep only the local dropped-count
+            return;
+        }
+        const at = now();
+        seen.set(fp, { count: 1, firstAt: at, lastAt: at, sentCount: 0 });
+        // The failing error joins the trace so the lead-up and the failure both
+        // show, carrying a causal pointer to the entries preceding the throw.
+        try {
+            const causedBy = precedingIds(config.buffer?.snapshot());
+            config.buffer?.add(errorCrumb(extracted.original, at, causedBy));
+        }
+        catch {
+            /* capture must never throw into the host app */
+        }
+        void file(fp, 1, { trace: true });
+    }
+    const previous = errorUtils.getGlobalHandler() ?? null;
+    let destroyed = false;
+    const wrapper = (error, isFatal) => {
+        if (!destroyed) {
+            try {
+                handle(extractGlobalError(error));
+            }
+            catch {
+                /* never throw into the host app */
+            }
+        }
+        // Always chain the previous handler — redbox in dev, crash reporters, etc.
+        if (previous)
+            previous(error, isFatal);
+    };
+    errorUtils.setGlobalHandler(wrapper);
+    /** Flush the final occurrence count of every fingerprint that grew. */
+    const flush = () => {
+        try {
+            for (const [fp, entry] of seen) {
+                if (entry.count > entry.sentCount) {
+                    void file(fp, entry.count, { trace: false });
+                }
+            }
+        }
+        catch {
+            /* best-effort on backgrounding */
+        }
+    };
+    let appStateSub = null;
+    if (config.appState) {
+        try {
+            appStateSub = config.appState.addEventListener("change", (state) => {
+                if (state === "background" || state === "inactive")
+                    flush();
+            });
+        }
+        catch {
+            appStateSub = null;
+        }
+    }
+    return {
+        destroy: () => {
+            destroyed = true;
+            try {
+                // `setGlobalHandler` is a single mutable slot: restore the previous
+                // handler only while ours is still the installed one. If someone
+                // installed a later handler (chaining ours as their previous), swapping
+                // the snapshot back in would silently uninstall them — instead our
+                // wrapper stays in the chain, inert, and keeps forwarding.
+                if (errorUtils.getGlobalHandler?.() === wrapper) {
+                    errorUtils.setGlobalHandler(previous);
+                }
+            }
+            catch {
+                /* teardown is best-effort */
+            }
+            try {
+                appStateSub?.remove();
+            }
+            catch {
+                /* teardown is best-effort */
+            }
+            appStateSub = null;
+        },
+        droppedCount: () => dropped,
+    };
+}

package/dist/http.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Minimal structural types for the HTTP surface the SDK touches.
+ *
+ * The package typechecks without the DOM lib (React Native is not a browser), so
+ * rather than depending on ambient `fetch`/`FormData` declarations, the exact
+ * slices the transport uses are described here and the globals are read off
+ * `globalThis` defensively. React Native provides both at runtime; tests inject
+ * fakes through the same seams.
+ */
+/** The response slice `boot`/`submit` read: status, ok, headers, JSON body. */
+export interface FetchResponseLike {
+    readonly ok: boolean;
+    readonly status: number;
+    readonly headers?: {
+        get(name: string): string | null;
+    } | null;
+    json(): Promise<unknown>;
+}
+/** The request init the SDK sends — method, plain headers, and a body. */
+export interface FetchRequestInit {
+    readonly method: string;
+    readonly headers?: Record<string, string>;
+    readonly body?: unknown;
+}
+/** A `fetch`-shaped function, injectable for tests. */
+export type FetchLike = (url: string, init: FetchRequestInit) => Promise<FetchResponseLike>;
+/** React Native's global `fetch`, when present. Bound so `this` never matters. */
+export declare function globalFetch(): FetchLike | undefined;
+/**
+ * The `FormData` slice the submission uses. React Native's implementation
+ * accepts `{ uri, name, type }` objects as file parts — that is how the
+ * screenshot travels (there is no `Blob` screenshot on mobile).
+ */
+export interface FormDataLike {
+    append(name: string, value: unknown): void;
+}
+/** Creates a fresh multipart form; injectable for tests. */
+export type FormDataFactory = () => FormDataLike;
+/** React Native's global `FormData` constructor, when present. */
+export declare function globalFormData(): FormDataFactory | undefined;

package/dist/http.js

@@ -0,0 +1,20 @@
+/**
+ * Minimal structural types for the HTTP surface the SDK touches.
+ *
+ * The package typechecks without the DOM lib (React Native is not a browser), so
+ * rather than depending on ambient `fetch`/`FormData` declarations, the exact
+ * slices the transport uses are described here and the globals are read off
+ * `globalThis` defensively. React Native provides both at runtime; tests inject
+ * fakes through the same seams.
+ */
+/** React Native's global `fetch`, when present. Bound so `this` never matters. */
+export function globalFetch() {
+    const g = globalThis;
+    return typeof g.fetch === "function" ? g.fetch.bind(globalThis) : undefined;
+}
+/** React Native's global `FormData` constructor, when present. */
+export function globalFormData() {
+    const g = globalThis;
+    const ctor = g.FormData;
+    return typeof ctor === "function" ? () => new ctor() : undefined;
+}

package/dist/identity.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The Public Reporter's stable, first-party anonymous id — the mobile
+ * counterpart of `packages/sdk/src/identity.ts`.
+ *
+ * When the host app does not supply its own identity, the SDK establishes a
+ * per-device id and persists it (AsyncStorage on React Native), so repeated
+ * boots from the same device are one Reporter. Persistence is best-effort: if
+ * storage is unavailable or failing, we fall back to an ephemeral id rather
+ * than throw — the SDK must never disturb the host app. The storage key is the
+ * web SDK's, so the shape stays recognisable across clients.
+ */
+/** The async storage slice the SDK uses — AsyncStorage-shaped, injectable. */
+export interface StorageLike {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+}
+export declare const ANONYMOUS_ID_STORAGE_KEY = "fixback.anonymousId";
+/** A random id: a UUID where the platform offers one, else a compact fallback. */
+export declare function generateAnonymousId(): string;
+/**
+ * Return this device's anonymous id, creating and persisting one on first use.
+ * Any storage failure — absent module, quota, corrupted value — yields an
+ * ephemeral id for this session instead of an error.
+ */
+export declare function ensureAnonymousId(storage: StorageLike | null | undefined): Promise<string>;