@fixback/expo 0.9.0 → 0.9.1

package/dist/client.d.ts

@@ -12,268 +12,25 @@
  * `resolveIdentity`, then `armCapture` — rather than one long procedure, so the
  * lifecycle reads as what it is and each step is testable on its own.
  *
+ * The client is a few pieces over one shared state object (`./client-state`, #661):
+ * boot and the capture it arms (`./client-boot`), mobile replay's arming
+ * (`./client-replay`), and Connect (`./client-connect`). What stays here is the
+ * lifecycle (`start`, `destroy`) and the composer-facing surface (`present`,
+ * `submit`, `trackScreen`). The public shapes live in `./options` and are
+ * re-exported from here.
+ *
  * 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, type CaptureToggles, type CommonCaptureInitOptions, DEFAULT_API_URL, type FetchLike, type IdentityInputs, type MaintenanceNotice, type ReporterIdentity } from "@fixback/sdk-core";
-import { type ConsoleLike, type XhrConstructor } from "./breadcrumbs";
-import { type DismissBrowser, type LinkingLike, type OpenAuthSession, type OpenBrowser } from "./connect";
-import { type SecureStorageLike } from "./reporter-session-store";
-import { type AppStateLike, type ErrorUtilsLike } from "./error-capture";
-import type { FormDataFactory } from "./http";
-import { type StorageLike } from "./identity";
+import { DEFAULT_API_URL } from "@fixback/sdk-core";
+import type { FixbackAdapters, FixbackClient, FixbackOptions } from "./options";
 import { canonicalizeOrigin } from "./origin";
-import { type EnvironmentInputs } from "./report";
-import { type MobileReplayOptions } from "./replay";
-import { type ReplayEncodeDeps } from "./replay-encode";
-import { type ResolvedShakeConfig, type ShakeOptions } from "./shake";
-import { type ScreenshotFile, type SubmitResult } from "./submit";
 export { DEFAULT_API_URL };
 export { canonicalizeOrigin };
 export { DEFAULT_SHAKE_SAMPLE_INTERVAL_MS, type ResolvedShakeConfig, type ShakeOptions, } from "./shake";
 export { DEFAULT_REPLAY_FPS, DEFAULT_REPLAY_MAX_EDGE, type MobileReplayOptions, REPLAY_BUCKET_MS, } from "./replay";
-/**
- * Everything `FixbackProvider` / `createFixbackClient` accepts: the shared init
- * vocabulary (`apiUrl`, `release`, `enabled`, `scrub`, `beforeSend`,
- * `beforeBreadcrumb`, `capture`) plus what only a React Native app has. There is no
- * `environment`: the `key` belongs to one Environment, and the server resolves the
- * Environment and its Gate from it (ADR 2026-09-24).
- */
-export interface FixbackOptions extends CommonCaptureInitOptions, IdentityInputs {
-    /** 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). **Optional** since ADR-0041: a native app attaches no `Origin`
-     * of its own, and ingest no longer demands one — a value the client invents proves
-     * nothing about who is calling, so requiring it only cost a setup step. Omit it and
-     * the app reports with no origin at all.
-     *
-     * Set one when you *want* mobile reports to carry an origin — it names the report's
-     * `url` as `<origin>/<screen>` and gives the queue something to filter by. Then it
-     * must be an `https://` origin allowlisted on the Project (convention: the app's
-     * reverse-DNS id as host, `https://com.acme.myapp`, or the product's web origin),
-     * because an origin that *is* presented is still checked.
-     */
-    readonly origin?: string;
-    /**
-     * Where the platform's connect page returns after a Connect **this app starts** —
-     * a scheme (`myapp://fixback-connect`) or universal link the app handles, declared
-     * once here and passed to the in-app auth session (ADR-0066; ticket #251). Its
-     * origin must be allowlisted on the Project (the server validates the return URL).
-     * Without it, `signIn` stays a no-op — a report still files anonymously where the
-     * Gate allows.
-     *
-     * It is **not** needed for an **invite**: that Connect is minted against the app
-     * link the Project allowlists and arrives as a deep link, which the SDK redeems
-     * whether or not this option is set (ADR-0046). Set it when you want to offer
-     * sign-in from inside the app; when it is set it also narrows which inbound links
-     * the SDK will read a code off.
-     */
-    readonly returnUrl?: string;
-    /**
-     * Automatic error capture — the SDK files uncaught JS errors as `source: error`
-     * Feedback with no prompt (spec 0004 §E, ADR-0011). Defaults to `true`; set
-     * `false` for the per-project toggle that turns it off. It is gated by boot's
-     * `canSubmit` either way, so an auto-error is never filed where a manual report
-     * would be refused.
-     */
-    readonly autoCapture?: boolean;
-    /**
-     * Per-stream capture toggles; unset streams follow the boot answer — **except
-     * `replay`**, which is off on mobile until this app asks for it (ADR-0044). A mobile
-     * replay is an unmasked recording of the device screen, so updating the SDK must
-     * never start one: set `capture: { replay: true }` (or pass a {@link replay} tuning
-     * object) to opt in, and the Project's own replay toggle still has the final say.
-     */
-    readonly capture?: CaptureToggles;
-    /**
-     * Mobile session-replay tuning (ADR-0044) — cadence, encoded size, frame quality.
-     * Passing it **also opts in**, exactly as `capture: { replay: true }` does; set
-     * `capture: { replay: false }` to tune without recording.
-     *
-     * The window is a buffered 30–60 s of device frames at 1 fps, encoded to one MP4 at
-     * report time. It is **not masked**: everything the app drew is in it, which is why
-     * it is off by default and why the Project must enable replay too.
-     */
-    readonly replay?: MobileReplayOptions;
-    /** Capture a screenshot when the composer opens. Defaults to `true`. */
-    readonly screenshots?: boolean;
-    /** Shake gesture tuning / off switch. */
-    readonly shake?: ShakeOptions;
-    /**
-     * The origins of **your own APIs** that should receive the **Correlation id** — a
-     * list of origins (`scheme://host[:port]`, e.g. `["https://api.example.com"]`).
-     *
-     * For a request to a listed origin the SDK sends a freshly minted W3C `traceparent`
-     * header and records its trace id on the request's network entry; `@fixback/node` on
-     * that backend adopts the same id for any error the request causes, so the app's
-     * Issue and the server Issue show one id. An app has no "same origin" to default to,
-     * so **nothing is sent unless its origin is listed** — a third-party API never sees a
-     * header it did not ask for. No wildcards and no paths: an entry that is not a bare
-     * origin is ignored with a warning. `fetch` is covered too — on React Native it runs
-     * on `XMLHttpRequest`, which is what the SDK instruments — and nothing is sent while
-     * network capture is off.
-     */
-    readonly propagateTo?: readonly string[];
-}
-/**
- * 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;
-    /**
-     * Secure persistence for the Reporter session token after a Connect (SecureStore).
-     * Absent ⇒ no persisted session (Connect still works for this launch).
-     */
-    readonly secureStore?: SecureStorageLike | null;
-    /**
-     * Opens the platform's connect page in an in-app auth session and resolves when it
-     * returns via the app's `returnUrl` (`expo-web-browser`). Absent ⇒ `signIn` is a
-     * no-op.
-     */
-    readonly openAuthSession?: OpenAuthSession | null;
-    /**
-     * Opens a URL in a plain in-app browser (`expo-web-browser`'s `openBrowserAsync`) —
-     * the **second** Connect door, for an app that declared no `returnUrl` (ADR-0052).
-     * There is no return for an auth session to recognise, so the connect page mints
-     * against the app links the Project lists and redirects to one; the code then
-     * arrives on `linking`, exactly as a claimed Invite's does. Absent ⇒ `signIn` falls
-     * back to the auth-session door alone.
-     */
-    readonly openBrowser?: OpenBrowser | null;
-    /**
-     * Closes the in-app browser this app opened (`expo-web-browser`'s `dismissBrowser`),
-     * called once the deep link has landed so the person is returned to the app rather
-     * than to the page they have finished with. Best-effort; absent ⇒ the browser is
-     * left for the OS (and the person) to dismiss.
-     */
-    readonly dismissBrowser?: DismissBrowser | null;
-    /**
-     * Reads the deep link the app was opened with, and reports later ones — React
-     * Native's `Linking`. It is how a Connect that started *outside* the app finishes
-     * inside it: an invite email lands on the Fixback claim page, the claim redirects to
-     * the app link the Project allowlists with a one-time code, and the app is launched
-     * from the outside with no auth session in flight (ADR-0046). Absent ⇒ an inbound
-     * Connect link is ignored and `signIn` remains the only way in — which on a gated
-     * Project means an invited tester can never be recognised.
-     */
-    readonly linking?: LinkingLike | 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;
-    /**
-     * Rasterises the screen to a replay frame file and resolves its URI (ADR-0044);
-     * `null` on failure. Absent ⇒ no replay, whatever the Project and init asked for.
-     */
-    readonly captureReplayFrame?: (quality: number) => Promise<string | null>;
-    /** Deletes a replay frame's (or encoded window's) file — best-effort, repeat-safe. */
-    readonly releaseReplayFrame?: (uri: string) => void;
-    /**
-     * Encodes a window of frame files into one H.264/MP4
-     * (`@fixback/expo-replay-encoder`). Absent, or resolving `null` — which is what a
-     * build with no native encoder linked does — means the report ships without replay.
-     */
-    readonly encodeReplaySegment?: ReplayEncodeDeps["encodeSegment"];
-    /** 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;
-    /**
-     * Whether the app is in the foreground. Replay capture pauses when it is not —
-     * a backgrounded app has nothing worth rasterising, and Android keeps JS timers
-     * running. Absent ⇒ capture never pauses.
-     */
-    readonly isAppActive?: () => boolean;
-    /** The transport seams. */
-    readonly fetch?: 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 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;
-    /**
-     * Drop the replay window frozen when the composer opened — call it when the Reporter
-     * dismisses the composer, so the buffered frames stop being retained (ADR-0044).
-     * A no-op when replay is off. Safe to call repeatedly.
-     */
-    discardReplay(): void;
-    /** The resolved shake tuning for the provider to arm. */
-    shakeConfig(): ResolvedShakeConfig;
-    /**
-     * Start a **Connect** (ADR-0066): open the platform's connect page in an in-app auth
-     * session, bind the signed-in Account to this app as a Reporter session (stored in
-     * SecureStore), and re-boot — so a gated Project's shake gesture arms once the Account
-     * is eligible. Resolves to the resulting identity. Never throws.
-     */
-    signIn(): Promise<ReporterIdentity>;
-    /** Clear the Reporter session — revoke it server-side, forget the token, re-boot. */
-    signOut(): Promise<void>;
-    /** The current Reporter identity — anonymous, or a connected Account with its tier. */
-    identity(): ReporterIdentity;
-    /** Subscribe to identity changes (boot, sign in, sign out). Returns an unsubscribe. */
-    onIdentity(listener: (identity: ReporterIdentity) => void): () => void;
-    /**
-     * **Maintenance mode**'s notice while Fixback is down for maintenance (the maintenance-mode
-     * ADR), else `null`. While it shows, the composer opens onto it with Send off; the client asks
-     * boot again every minute and clears it once maintenance ends.
-     */
-    maintenance(): MaintenanceNotice | null;
-    /** Subscribe to maintenance mode's notice coming and going. Returns an unsubscribe. */
-    onMaintenance(listener: (notice: MaintenanceNotice | null) => void): () => void;
-    /** Tear down every hook. Safe to call repeatedly. */
-    destroy(): void;
-}
+export type { ComposerContext, ComposerDraft, FixbackAdapters, FixbackClient, FixbackOptions, FixbackStatus, } from "./options";
 /** Create the headless client. See the module doc. */
 export declare function createFixbackClient(options: FixbackOptions, adapters?: FixbackAdapters): FixbackClient;