@fixback/expo 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,174 @@
+/**
+ * The headless Fixback client — everything the Expo SDK does except render.
+ *
+ * `createFixbackClient` owns the lifecycle the web SDK's `init` owns (spec 0003
+ * §G ported to mobile, spec 0004): establish identity → boot → arm capture
+ * (trace instrumentation + automatic error capture) only when boot allows
+ * submission → assemble/scrub/submit reports. The React layer
+ * (`FixbackProvider`) is a thin shell over this: it feeds accelerometer
+ * samples, listens for `present` events, and renders the composer.
+ *
+ * Every platform touchpoint is an injected adapter (`FixbackAdapters`), so the
+ * whole orchestration is unit-tested without React Native. Every path is
+ * defensive: a Fixback problem leaves the host app untouched — `start` resolves
+ * to a `disabled` client instead of throwing.
+ */
+import { type BootAnswer } from "./boot";
+import { type BeforeBreadcrumb, type ConsoleLike, type XhrConstructor } from "./breadcrumbs";
+import { type AppStateLike, type ErrorUtilsLike } from "./error-capture";
+import type { FetchLike, FormDataFactory } from "./http";
+import { type StorageLike } from "./identity";
+import { type EnvironmentInputs } from "./report";
+import { type BeforeSend } from "./scrub";
+import { type ShakeTuning } from "./shake";
+import { type ScreenshotFile, type SubmitResult } from "./submit";
+/** Where reports go when no `apiUrl` is configured (mirrors the web SDK). */
+export declare const DEFAULT_API_URL = "https://api.fixback.dev";
+/** How often the accelerometer reports while the gesture is armed. */
+export declare const DEFAULT_SHAKE_SAMPLE_INTERVAL_MS = 80;
+/** The shake gesture's init options: the tuning plus an off switch. */
+export interface ShakeOptions extends Partial<ShakeTuning> {
+    /** Arm the shake gesture. Defaults to `true`. */
+    readonly enabled?: boolean;
+    /**
+     * The accelerometer update interval to request, in ms. Defaults to
+     * {@link DEFAULT_SHAKE_SAMPLE_INTERVAL_MS}. The interval is global to the
+     * sensor in `expo-sensors` — the SDK only sets it when no other listener is
+     * registered, and apps that drive the accelerometer themselves should align
+     * this with their own setting.
+     */
+    readonly sampleIntervalMs?: number;
+}
+/** Everything `FixbackProvider` / `createFixbackClient` accepts. */
+export interface FixbackOptions {
+    /** The Project's publishable key. Required. */
+    readonly key: string;
+    /**
+     * The origin this app reports as, sent as the `Origin` header on every
+     * request (spec 0004 §A). Must be an `https://` origin allowlisted on the
+     * Project — e.g. `https://com.acme.myapp` or the product's web origin.
+     */
+    readonly origin: string;
+    /** The Fixback API base URL. Defaults to {@link DEFAULT_API_URL}. */
+    readonly apiUrl?: string;
+    /** A customer-server-minted signed identity (spec 0003 §F). */
+    readonly signedIdentity?: string;
+    /** A persisted Reporter handle, when the host app manages one. */
+    readonly reporterId?: string;
+    /** Override the SDK-managed anonymous id. */
+    readonly anonymousId?: string;
+    /** Display-only Reporter name/email riding on every submission. */
+    readonly reporterName?: string;
+    readonly reporterEmail?: string;
+    /** Per-stream capture toggles; unset streams follow the boot answer. */
+    readonly capture?: {
+        readonly console?: boolean;
+        readonly network?: boolean;
+    };
+    /** Automatic error capture. Defaults to `true` (ADR-0011). */
+    readonly autoCapture?: boolean;
+    /** Capture a screenshot when the composer opens. Defaults to `true`. */
+    readonly screenshots?: boolean;
+    /** The per-project client scrub hook (spec 0003 §C). */
+    readonly beforeSend?: BeforeSend;
+    /** Run the built-in default scrubbers. Defaults to `true`. */
+    readonly scrub?: boolean;
+    /** A per-crumb filter for the trace buffer. */
+    readonly beforeBreadcrumb?: BeforeBreadcrumb | null;
+    /** Shake gesture tuning / off switch. */
+    readonly shake?: ShakeOptions;
+}
+/**
+ * The platform touchpoints, as injectable seams. `createNativeAdapters()`
+ * builds the real React Native set; tests pass fakes.
+ */
+export interface FixbackAdapters {
+    /** Anonymous-id persistence (AsyncStorage). Absent ⇒ ephemeral ids. */
+    readonly storage?: StorageLike | null;
+    /** Reads the device environment (window size, OS description). */
+    readonly environment?: () => EnvironmentInputs;
+    /** Captures the current screen as a file reference; `null` on failure. */
+    readonly captureScreenshot?: () => Promise<ScreenshotFile | null>;
+    /** Releases a captured screenshot's tmpfile (best-effort, repeat-safe). */
+    readonly releaseScreenshot?: (uri: string) => void;
+    /** The `console` to wrap for the trace. `null` ⇒ skip. */
+    readonly consoleObj?: ConsoleLike | null;
+    /** The `XMLHttpRequest` to patch for the trace. `null` ⇒ skip. */
+    readonly xhr?: XhrConstructor | null;
+    /** The `ErrorUtils` seam for automatic error capture. `null` ⇒ skip. */
+    readonly errorUtils?: ErrorUtilsLike | null;
+    /** The `AppState` seam for occurrence flushes. */
+    readonly appState?: AppStateLike | null;
+    /** The transport seams. */
+    readonly fetchImpl?: FetchLike;
+    readonly formData?: FormDataFactory;
+    /** A development-only warning sink (silent in production builds). */
+    readonly warn?: (message: string) => void;
+    /** Clock source, injectable for tests. */
+    readonly now?: () => number;
+}
+/** The client's lifecycle state. */
+export type FixbackStatus = "idle" | "starting" | "ready" | "disabled";
+/** What a `present` listener receives — the composer's opening context. */
+export interface ComposerContext {
+    readonly screenshot: ScreenshotFile | null;
+}
+/** What the composer hands back when the Reporter sends. */
+export interface ComposerDraft {
+    readonly comment?: string;
+    /** The screenshot to attach (the presented one, unless removed). */
+    readonly screenshot?: ScreenshotFile | null;
+}
+/** The resolved shake configuration the provider arms the gesture with. */
+export interface ResolvedShakeConfig extends ShakeTuning {
+    readonly enabled: boolean;
+    readonly sampleIntervalMs: number;
+}
+/** The headless client `FixbackProvider` drives. */
+export interface FixbackClient {
+    /** Boot and arm capture. Idempotent; never throws. */
+    start(): Promise<void>;
+    getStatus(): FixbackStatus;
+    /** The boot answer, once one arrived (for display; trust stays server-side). */
+    getBoot(): BootAnswer | null;
+    /** Whether a submission would be accepted right now. */
+    canSubmit(): boolean;
+    /** Subscribe to status changes. Returns an unsubscribe. */
+    onStatus(listener: (status: FixbackStatus) => void): () => void;
+    /**
+     * Open the composer: capture a screenshot (unless disabled) and notify
+     * `onPresent` listeners. A no-op while the client cannot submit.
+     */
+    present(): Promise<void>;
+    /** Subscribe to composer-open requests. Returns an unsubscribe. */
+    onPresent(listener: (context: ComposerContext) => void): () => void;
+    /**
+     * Record a screen change: a `navigation` trace crumb, and the screen the
+     * next report's `url` names (spec 0004 §D).
+     */
+    trackScreen(name: string): void;
+    /** Assemble, scrub, and submit a manual report. Never throws. */
+    submit(draft: ComposerDraft): Promise<SubmitResult>;
+    /** Release a captured screenshot's tmpfile (best-effort, repeat-safe). */
+    discardScreenshot(screenshot: ScreenshotFile | null | undefined): void;
+    /** The resolved shake tuning for the provider to arm. */
+    shakeConfig(): ResolvedShakeConfig;
+    /** Tear down every hook. Safe to call repeatedly. */
+    destroy(): void;
+}
+/**
+ * Canonicalize the configured origin exactly as the server's `normalizeOrigin`
+ * does when an allowlist entry is stored (`apps/api/src/projects/origin.ts`):
+ * lowercase the scheme and host, elide default ports, and drop any userinfo,
+ * path, query, or fragment. The server compares the `Origin` header by exact
+ * string equality against those canonical rows — on the web the browser
+ * serializes the header, but here the SDK is the serializer, so without this a
+ * pasted `https://com.acme.MyApp` (bundle ids legally carry uppercase) would
+ * silently never match its own allowlist entry. Implemented without `URL`
+ * (React Native's polyfill is partial); a value that doesn't parse as an
+ * http(s) origin is kept trimmed — boot will simply refuse it. IDN hosts are
+ * not punycoded (the one divergence from the server; use the encoded form).
+ */
+export declare function canonicalizeOrigin(value: string): string;
+/** Create the headless client. See the module doc. */
+export declare function createFixbackClient(options: FixbackOptions, adapters?: FixbackAdapters): FixbackClient;

package/dist/client.js

@@ -0,0 +1,351 @@
+/**
+ * The headless Fixback client — everything the Expo SDK does except render.
+ *
+ * `createFixbackClient` owns the lifecycle the web SDK's `init` owns (spec 0003
+ * §G ported to mobile, spec 0004): establish identity → boot → arm capture
+ * (trace instrumentation + automatic error capture) only when boot allows
+ * submission → assemble/scrub/submit reports. The React layer
+ * (`FixbackProvider`) is a thin shell over this: it feeds accelerometer
+ * samples, listens for `present` events, and renders the composer.
+ *
+ * Every platform touchpoint is an injected adapter (`FixbackAdapters`), so the
+ * whole orchestration is unit-tested without React Native. Every path is
+ * defensive: a Fixback problem leaves the host app untouched — `start` resolves
+ * to a `disabled` client instead of throwing.
+ */
+import { requestBoot } from "./boot";
+import { createBreadcrumbBuffer, instrumentBreadcrumbs, navigationCrumb, } from "./breadcrumbs";
+import { installErrorCapture, } from "./error-capture";
+import { ensureAnonymousId } from "./identity";
+import { assembleContent, collectEnvironment, } from "./report";
+import { runBeforeSend } from "./scrub";
+import { DEFAULT_SHAKE_TUNING } from "./shake";
+import { submitReport, } from "./submit";
+import { EXPO_SDK_VERSION } from "./version";
+/** Where reports go when no `apiUrl` is configured (mirrors the web SDK). */
+export const DEFAULT_API_URL = "https://api.fixback.dev";
+/** How often the accelerometer reports while the gesture is armed. */
+export const DEFAULT_SHAKE_SAMPLE_INTERVAL_MS = 80;
+/** Normalise a base URL: trim and drop trailing slashes. */
+function normalizeBase(value) {
+    return value.trim().replace(/\/+$/, "");
+}
+/**
+ * Canonicalize the configured origin exactly as the server's `normalizeOrigin`
+ * does when an allowlist entry is stored (`apps/api/src/projects/origin.ts`):
+ * lowercase the scheme and host, elide default ports, and drop any userinfo,
+ * path, query, or fragment. The server compares the `Origin` header by exact
+ * string equality against those canonical rows — on the web the browser
+ * serializes the header, but here the SDK is the serializer, so without this a
+ * pasted `https://com.acme.MyApp` (bundle ids legally carry uppercase) would
+ * silently never match its own allowlist entry. Implemented without `URL`
+ * (React Native's polyfill is partial); a value that doesn't parse as an
+ * http(s) origin is kept trimmed — boot will simply refuse it. IDN hosts are
+ * not punycoded (the one divergence from the server; use the encoded form).
+ */
+export function canonicalizeOrigin(value) {
+    const trimmed = value.trim();
+    const match = trimmed.match(/^(https?):\/\/([^/?#]+)(?:[/?#].*)?$/i);
+    if (!match)
+        return trimmed.replace(/\/+$/, "");
+    const scheme = match[1].toLowerCase();
+    let authority = match[2];
+    const at = authority.lastIndexOf("@");
+    if (at >= 0)
+        authority = authority.slice(at + 1);
+    let host = authority;
+    let port;
+    const portMatch = authority.match(/^(.+):(\d+)$/);
+    if (portMatch) {
+        host = portMatch[1];
+        port = portMatch[2];
+    }
+    host = host.toLowerCase();
+    const isDefaultPort = !port || (scheme === "https" && port === "443") || (scheme === "http" && port === "80");
+    return isDefaultPort ? `${scheme}://${host}` : `${scheme}://${host}:${port}`;
+}
+/** Turn a screen name into the path segment of the report `url`. */
+function screenPath(name) {
+    return name.trim().replace(/^\/+/, "");
+}
+/** Create the headless client. See the module doc. */
+export function createFixbackClient(options, adapters = {}) {
+    const key = typeof options.key === "string" ? options.key.trim() : "";
+    const origin = typeof options.origin === "string" ? canonicalizeOrigin(options.origin) : "";
+    const apiUrl = normalizeBase(options.apiUrl || DEFAULT_API_URL) || DEFAULT_API_URL;
+    const now = adapters.now ?? Date.now;
+    const readEnvironment = adapters.environment ?? (() => ({}));
+    const warn = adapters.warn ?? (() => { });
+    const buffer = createBreadcrumbBuffer({
+        beforeBreadcrumb: options.beforeBreadcrumb,
+        now,
+    });
+    let status = "idle";
+    let boot = null;
+    let currentScreen = null;
+    let teardownTrace = null;
+    let autoCapture = null;
+    let identity = {};
+    /**
+     * The lifecycle generation. Each `start()` claims a new generation and every
+     * await inside it re-checks that it is still current; `destroy()` bumps the
+     * generation so an in-flight start abandons itself. A destroyed client can be
+     * started again — React 18+ StrictMode (and Fast Refresh) replay the
+     * provider's effect as mount → cleanup → re-mount on the same client
+     * instance, so destroy must not be terminal.
+     */
+    let generation = 0;
+    /** Whether a start() has claimed the current generation. */
+    let running = false;
+    const statusListeners = new Set();
+    const presentListeners = new Set();
+    function setStatus(next) {
+        if (status === next)
+            return;
+        status = next;
+        for (const listener of statusListeners) {
+            try {
+                listener(next);
+            }
+            catch {
+                /* a listener must never break the client */
+            }
+        }
+    }
+    /** The `url` a report carries right now (spec 0004 §D). */
+    function currentUrl() {
+        if (!origin)
+            return undefined;
+        return currentScreen ? `${origin}/${screenPath(currentScreen)}` : origin;
+    }
+    /** Keep the SDK's own ingest traffic out of the trace. */
+    function isFixbackApiRequest(url) {
+        return url.startsWith(`${apiUrl}/api/ingest/`) || url.startsWith(`${apiUrl}/api/invites/`);
+    }
+    async function start() {
+        if (running)
+            return;
+        running = true;
+        const gen = ++generation;
+        setStatus("starting");
+        try {
+            if (!key || !origin) {
+                if (!key)
+                    warn("Fixback: init needs a publishable `key`; staying dormant.");
+                if (!origin) {
+                    warn("Fixback: init needs an `origin` (an https origin allowlisted on the Project) — a native app sends no Origin header of its own; staying dormant.");
+                }
+                setStatus("disabled");
+                return;
+            }
+            const anonymousId = options.anonymousId ?? (await ensureAnonymousId(adapters.storage));
+            if (gen !== generation)
+                return; // destroyed (or restarted) while resolving
+            identity = {
+                ...(options.signedIdentity ? { signedIdentity: options.signedIdentity } : {}),
+                ...(options.reporterId ? { reporterId: options.reporterId } : {}),
+                anonymousId,
+            };
+            const answer = await requestBoot(apiUrl, { key, ...identity }, origin, adapters.fetchImpl);
+            if (gen !== generation)
+                return; // destroyed (or restarted) while booting
+            boot = answer;
+            if (!answer || !answer.canSubmit) {
+                if (answer && !answer.originAllowed) {
+                    warn(`Fixback: the Project has not allowlisted "${origin}" — add it to the Project's allowed origins to enable feedback from this app.`);
+                }
+                setStatus("disabled");
+                return;
+            }
+            // Per-stream capture: an init option overrides the served config; an
+            // absent/malformed served value means ON (spec 0003 §C, ported).
+            const served = answer.capture;
+            const captureConsole = options.capture?.console ??
+                (typeof served?.console === "boolean" ? served.console : true);
+            const captureNetwork = options.capture?.network ??
+                (typeof served?.network === "boolean" ? served.network : true);
+            teardownTrace = instrumentBreadcrumbs(buffer, {
+                consoleObj: adapters.consoleObj,
+                xhr: adapters.xhr,
+                ignoreUrl: isFixbackApiRequest,
+                now,
+                captureConsole,
+                captureNetwork,
+            });
+            if (options.autoCapture !== false) {
+                autoCapture = installErrorCapture({
+                    apiUrl,
+                    key,
+                    origin,
+                    identity,
+                    display: {
+                        name: options.reporterName,
+                        email: options.reporterEmail,
+                    },
+                    sdkVersion: EXPO_SDK_VERSION,
+                    buffer,
+                    beforeSend: options.beforeSend,
+                    scrub: options.scrub,
+                    environment: readEnvironment,
+                    currentUrl,
+                    errorUtils: adapters.errorUtils,
+                    appState: adapters.appState,
+                    deps: {
+                        submitReport: (url, input) => submitReport(url, input, {
+                            fetchImpl: adapters.fetchImpl,
+                            formData: adapters.formData,
+                        }),
+                    },
+                    now,
+                });
+            }
+            setStatus("ready");
+        }
+        catch {
+            // A Fixback problem must never disturb the host app.
+            if (gen === generation)
+                setStatus("disabled");
+        }
+    }
+    async function present() {
+        if (status !== "ready")
+            return;
+        let screenshot = null;
+        if (options.screenshots !== false && adapters.captureScreenshot) {
+            try {
+                screenshot = await adapters.captureScreenshot();
+            }
+            catch {
+                screenshot = null;
+            }
+        }
+        const context = { screenshot };
+        for (const listener of presentListeners) {
+            try {
+                listener(context);
+            }
+            catch {
+                /* a listener must never break the client */
+            }
+        }
+    }
+    async function submit(draft) {
+        try {
+            const content = runBeforeSend(
+            // No Kind on the wire — analysis classifies the Issue server-side
+            // (ADR-0023).
+            assembleContent({
+                comment: draft.comment,
+                url: currentUrl(),
+                environment: collectEnvironment(readEnvironment(), EXPO_SDK_VERSION),
+                trace: buffer.snapshot(),
+                reporterName: options.reporterName,
+                reporterEmail: options.reporterEmail,
+            }), { hook: options.beforeSend, scrub: options.scrub });
+            // Dropped by the project's own beforeSend — an intentional non-send.
+            if (!content)
+                return { ok: true, feedback: null };
+            const result = await submitReport(apiUrl, {
+                key,
+                origin,
+                identity,
+                content,
+                screenshot: draft.screenshot ?? null,
+            }, { fetchImpl: adapters.fetchImpl, formData: adapters.formData });
+            // A delivered screenshot's tmpfile has served its purpose — release it.
+            // On a failure the file is kept: the composer holds the draft for retry.
+            if (result.ok)
+                discardScreenshot(draft.screenshot);
+            return result;
+        }
+        catch {
+            return { ok: false, reason: "unreachable" };
+        }
+    }
+    /**
+     * Release a captured screenshot's tmpfile (best-effort, repeat-safe). Called
+     * after a delivered submission, and by the UI when the Reporter removes the
+     * screenshot or discards the draft — an image the Reporter declined to send
+     * must not linger in the app's cache (spec 0004 §C).
+     */
+    function discardScreenshot(screenshot) {
+        if (!screenshot?.uri || !adapters.releaseScreenshot)
+            return;
+        try {
+            adapters.releaseScreenshot(screenshot.uri);
+        }
+        catch {
+            /* release is best-effort */
+        }
+    }
+    function trackScreen(name) {
+        try {
+            const trimmed = typeof name === "string" ? name.trim() : "";
+            if (!trimmed)
+                return;
+            const from = currentUrl();
+            currentScreen = trimmed;
+            const to = currentUrl();
+            if (from && to && from !== to) {
+                buffer.add(navigationCrumb(from, to, now()));
+            }
+        }
+        catch {
+            /* never throw into the host app */
+        }
+    }
+    function shakeConfig() {
+        const shake = options.shake ?? {};
+        return {
+            enabled: shake.enabled !== false,
+            sampleIntervalMs: shake.sampleIntervalMs ?? DEFAULT_SHAKE_SAMPLE_INTERVAL_MS,
+            thresholdG: shake.thresholdG ?? DEFAULT_SHAKE_TUNING.thresholdG,
+            minPeaks: shake.minPeaks ?? DEFAULT_SHAKE_TUNING.minPeaks,
+            windowMs: shake.windowMs ?? DEFAULT_SHAKE_TUNING.windowMs,
+            minGapMs: shake.minGapMs ?? DEFAULT_SHAKE_TUNING.minGapMs,
+            cooldownMs: shake.cooldownMs ?? DEFAULT_SHAKE_TUNING.cooldownMs,
+        };
+    }
+    return {
+        start,
+        getStatus: () => status,
+        getBoot: () => boot,
+        canSubmit: () => status === "ready" && boot?.canSubmit === true,
+        onStatus(listener) {
+            statusListeners.add(listener);
+            return () => statusListeners.delete(listener);
+        },
+        present,
+        onPresent(listener) {
+            presentListeners.add(listener);
+            return () => presentListeners.delete(listener);
+        },
+        trackScreen,
+        submit,
+        discardScreenshot,
+        shakeConfig,
+        destroy() {
+            // Abandon any in-flight start and allow a later start() to re-arm —
+            // React StrictMode replays the provider's effect on this same instance.
+            generation += 1;
+            running = false;
+            try {
+                teardownTrace?.();
+            }
+            catch {
+                /* teardown is best-effort */
+            }
+            teardownTrace = null;
+            try {
+                autoCapture?.destroy();
+            }
+            catch {
+                /* teardown is best-effort */
+            }
+            autoCapture = null;
+            statusListeners.clear();
+            presentListeners.clear();
+            setStatus("disabled");
+        },
+    };
+}