@fixback/expo 0.1.0

package/dist/submit.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The multipart feedback submission — the transport half of the capture loop,
+ * kept file-parallel with `packages/sdk/src/submit.ts` (ADR-0021).
+ *
+ * `POST /api/ingest/feedback` is a multipart request: a single text part
+ * `payload` carrying the JSON (publishable key + identity evidence + content)
+ * and an optional binary part `screenshot`. Two mobile differences:
+ *
+ * - a native HTTP stack attaches no `Origin` header, so the configured origin
+ *   is sent explicitly (the server exact-matches it against the allowlist);
+ * - the screenshot is a `{ uri, name, type }` file reference (React Native's
+ *   `FormData` file-part shape), not a `Blob`.
+ *
+ * The content-type header is deliberately not set, so the runtime writes the
+ * `multipart/form-data` boundary itself. Like `requestBoot`, this never throws:
+ * an unreachable Fixback or a refusal is a quiet result, so a Fixback problem
+ * never breaks the host app. Automatic reports (`source: auto`) honour ingest's
+ * `429` + `Retry-After` backpressure; manual reports are never gated.
+ */
+import { AutoReportBackoff } from "./auto-report-backoff";
+import type { IdentityInputs, ReporterTier } from "./boot";
+import { type FetchLike, type FormDataFactory } from "./http";
+import type { ReportContent } from "./report";
+/** What ingest returns for an accepted submission (vendored server shape). */
+export interface RecordedFeedback {
+    readonly feedbackId: string;
+    readonly issueId: string;
+    readonly reporterId: string;
+    readonly tier: ReporterTier;
+}
+/**
+ * The captured screenshot to attach, if any — a React Native file reference.
+ * The server accepts png/jpeg/webp/gif up to 10 MiB; `react-native-view-shot`
+ * produces a png tmpfile by default.
+ */
+export interface ScreenshotFile {
+    readonly uri: string;
+    readonly name?: string;
+    readonly type?: string;
+}
+/** Everything a single feedback submission carries. */
+export interface SubmitInput {
+    readonly key: string;
+    /** The configured origin, sent as the `Origin` header (spec 0004 §A). */
+    readonly origin: string;
+    readonly identity?: IdentityInputs;
+    readonly content: ReportContent;
+    readonly screenshot?: ScreenshotFile | null;
+}
+/** The outcome of a submission — never an exception. */
+export type SubmitResult = {
+    readonly ok: true;
+    readonly feedback: RecordedFeedback | null;
+} | {
+    readonly ok: false;
+    readonly reason: "unreachable" | "refused";
+    readonly status?: number;
+} | {
+    /**
+     * A `source: auto` report shed under ingest backpressure — either held
+     * locally because the window is still open, or answered `429` by ingest,
+     * which opened/extended the window. Manual reports never produce this.
+     */
+    readonly ok: false;
+    readonly reason: "backpressure";
+    readonly retryAfterSeconds: number;
+};
+/**
+ * How long a submission may stay in flight before it is reported as
+ * `unreachable`. React Native's Android networking applies no default request
+ * timeout, so without this a stalled connection would hang a report forever.
+ * The abandoned request keeps running in the background harmlessly.
+ */
+export declare const DEFAULT_SUBMIT_TIMEOUT_MS = 30000;
+/** Injectable transport collaborators, defaulted to the real implementations. */
+export interface SubmitDeps {
+    readonly fetchImpl?: FetchLike;
+    readonly formData?: FormDataFactory;
+    readonly backoff?: AutoReportBackoff;
+    /** Overall request timeout in ms; `0` disables. Defaults to {@link DEFAULT_SUBMIT_TIMEOUT_MS}. */
+    readonly timeoutMs?: number;
+}
+/** Join an API base URL with the feedback path, tolerating a trailing slash. */
+export declare function feedbackEndpoint(apiUrl: string): string;
+/**
+ * Submit a report to ingest. Assembles the `payload` JSON (key + identity +
+ * content, with an explicit `source` stamped) and the optional screenshot file
+ * reference into a `FormData`, posts it with the configured `Origin` header,
+ * and resolves to the recorded Feedback on success or a named failure
+ * otherwise.
+ *
+ * A `source: auto` report first consults the shared backpressure window: while
+ * it is open the report is dropped without a request. Ingest's `429` +
+ * `Retry-After` opens/extends that window. Manual reports (`source: reporter`,
+ * the default) never consult the window and a non-2xx for them stays a plain
+ * refusal. The `deps` seams exist purely so the call is testable.
+ */
+export declare function submitReport(apiUrl: string, input: SubmitInput, deps?: SubmitDeps): Promise<SubmitResult>;

package/dist/submit.js

@@ -0,0 +1,154 @@
+/**
+ * The multipart feedback submission — the transport half of the capture loop,
+ * kept file-parallel with `packages/sdk/src/submit.ts` (ADR-0021).
+ *
+ * `POST /api/ingest/feedback` is a multipart request: a single text part
+ * `payload` carrying the JSON (publishable key + identity evidence + content)
+ * and an optional binary part `screenshot`. Two mobile differences:
+ *
+ * - a native HTTP stack attaches no `Origin` header, so the configured origin
+ *   is sent explicitly (the server exact-matches it against the allowlist);
+ * - the screenshot is a `{ uri, name, type }` file reference (React Native's
+ *   `FormData` file-part shape), not a `Blob`.
+ *
+ * The content-type header is deliberately not set, so the runtime writes the
+ * `multipart/form-data` boundary itself. Like `requestBoot`, this never throws:
+ * an unreachable Fixback or a refusal is a quiet result, so a Fixback problem
+ * never breaks the host app. Automatic reports (`source: auto`) honour ingest's
+ * `429` + `Retry-After` backpressure; manual reports are never gated.
+ */
+import { AutoReportBackoff } from "./auto-report-backoff";
+import { globalFetch, globalFormData, } from "./http";
+/** The multipart field the screenshot binary is sent under (mirrors the server). */
+const SCREENSHOT_FIELD = "screenshot";
+/**
+ * How long a submission may stay in flight before it is reported as
+ * `unreachable`. React Native's Android networking applies no default request
+ * timeout, so without this a stalled connection would hang a report forever.
+ * The abandoned request keeps running in the background harmlessly.
+ */
+export const DEFAULT_SUBMIT_TIMEOUT_MS = 30_000;
+/**
+ * The shared `source: auto` backpressure window for the app. One instance so a
+ * `429` from an auto-report holds the auto-reports that follow it.
+ */
+const defaultBackoff = new AutoReportBackoff();
+/** Join an API base URL with the feedback path, tolerating a trailing slash. */
+export function feedbackEndpoint(apiUrl) {
+    return `${apiUrl.replace(/\/+$/, "")}/api/ingest/feedback`;
+}
+/** Drop `undefined` identity fields so the payload carries only what was given. */
+function compactIdentity(identity) {
+    if (!identity)
+        return {};
+    const out = {};
+    if (identity.signedIdentity)
+        out.signedIdentity = identity.signedIdentity;
+    if (identity.reporterId)
+        out.reporterId = identity.reporterId;
+    if (identity.anonymousId)
+        out.anonymousId = identity.anonymousId;
+    return out;
+}
+/** Read one response header defensively — `null` when unavailable or on any throw. */
+function safeHeader(response, name) {
+    try {
+        return response.headers?.get?.(name) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Submit a report to ingest. Assembles the `payload` JSON (key + identity +
+ * content, with an explicit `source` stamped) and the optional screenshot file
+ * reference into a `FormData`, posts it with the configured `Origin` header,
+ * and resolves to the recorded Feedback on success or a named failure
+ * otherwise.
+ *
+ * A `source: auto` report first consults the shared backpressure window: while
+ * it is open the report is dropped without a request. Ingest's `429` +
+ * `Retry-After` opens/extends that window. Manual reports (`source: reporter`,
+ * the default) never consult the window and a non-2xx for them stays a plain
+ * refusal. The `deps` seams exist purely so the call is testable.
+ */
+export async function submitReport(apiUrl, input, deps = {}) {
+    const source = input.content.source ?? "reporter";
+    const isAuto = source === "auto";
+    const backoff = deps.backoff ?? defaultBackoff;
+    // Client-side backpressure: shed auto-reports while the hold window is open,
+    // without touching the network. Manual reports are never gated.
+    if (isAuto && backoff.isPaused()) {
+        return {
+            ok: false,
+            reason: "backpressure",
+            retryAfterSeconds: backoff.retryAfterSeconds(),
+        };
+    }
+    const doFetch = deps.fetchImpl ?? globalFetch();
+    const makeForm = deps.formData ?? globalFormData();
+    if (!doFetch || !makeForm)
+        return { ok: false, reason: "unreachable" };
+    const payload = {
+        key: input.key,
+        ...compactIdentity(input.identity),
+        ...input.content,
+        source,
+    };
+    const form = makeForm();
+    form.append("payload", JSON.stringify(payload));
+    if (input.screenshot?.uri) {
+        // React Native's FormData accepts a { uri, name, type } object as a file
+        // part; the explicit type matters — the server answers 415 without a
+        // recognised image content type.
+        form.append(SCREENSHOT_FIELD, {
+            uri: input.screenshot.uri,
+            name: input.screenshot.name ?? "screenshot.png",
+            type: input.screenshot.type ?? "image/png",
+        });
+    }
+    const timeoutMs = deps.timeoutMs ?? DEFAULT_SUBMIT_TIMEOUT_MS;
+    let timer;
+    let response;
+    try {
+        const request = doFetch(feedbackEndpoint(apiUrl), {
+            method: "POST",
+            headers: { origin: input.origin },
+            body: form,
+        });
+        response =
+            timeoutMs > 0
+                ? await Promise.race([
+                    request,
+                    new Promise((_, reject) => {
+                        timer = setTimeout(() => reject(new Error("fixback: submission timed out")), timeoutMs);
+                    }),
+                ])
+                : await request;
+    }
+    catch {
+        return { ok: false, reason: "unreachable" };
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+    if (!response.ok) {
+        // A `429` for an auto-report is backpressure, not a refusal: open/extend
+        // the hold window from `Retry-After` and report the wait. Manual reports
+        // never 429 here, so any non-2xx for them stays a plain refusal.
+        if (isAuto && response.status === 429) {
+            const retryAfterSeconds = backoff.hold(safeHeader(response, "Retry-After"));
+            return { ok: false, reason: "backpressure", retryAfterSeconds };
+        }
+        return { ok: false, reason: "refused", status: response.status };
+    }
+    try {
+        const feedback = (await response.json());
+        return { ok: true, feedback };
+    }
+    catch {
+        // Accepted, but the body wasn't the expected JSON — still a success.
+        return { ok: true, feedback: null };
+    }
+}

package/dist/tokens.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A vendored slice of the **Signal** design tokens for the mobile composer.
+ *
+ * React Native cannot consume CSS custom properties, so the semantic roles the
+ * composer needs are mirrored here as constants. Every value traces to
+ * `packages/ui/src/tokens.css` (the design source of truth) — change it there
+ * first, then keep this slice in step (ADR-0021 records the gap).
+ *
+ * IBM Plex is not loadable without the host app shipping fonts, so type falls
+ * back to the system stack; the mono accents use the platform's monospace face
+ * (the composer passes `Platform.select` for that — this module stays free of
+ * React Native imports so pure code can use it too).
+ */
+export declare const signal: {
+    readonly accent: "#2f6fed";
+    readonly accentTint: "#eaf1fe";
+    readonly accentBorder: "#cfe0fd";
+    readonly text: "#0f1720";
+    readonly textPanel: "#1a2530";
+    readonly textMuted: "#5a6875";
+    readonly textFaint: "#8a97a3";
+    readonly textSubtle: "#9aa7b2";
+    readonly textGhost: "#b3bdc7";
+    readonly surface: "#ffffff";
+    readonly canvas: "#f4f6f9";
+    readonly sunken: "#eef1f5";
+    readonly border: "#e6ebf0";
+    readonly borderControl: "#e0e6ec";
+    readonly borderStrong: "#dce3ea";
+    readonly danger: "#e5484d";
+    readonly dangerSurface: "#fdecec";
+    readonly dangerBorder: "#f7cfcf";
+    readonly success: "#2f9e5b";
+    readonly successSurface: "#e5f5eb";
+    readonly successBorder: "#bfe6cd";
+    readonly idea: "#8b5cf6";
+    readonly ideaSurface: "#f1ecfe";
+    readonly ideaBorder: "#e0d4fb";
+    readonly onEmphasis: "#ffffff";
+    readonly scrim: "rgba(15, 23, 32, 0.42)";
+};

package/dist/tokens.js

@@ -0,0 +1,46 @@
+/**
+ * A vendored slice of the **Signal** design tokens for the mobile composer.
+ *
+ * React Native cannot consume CSS custom properties, so the semantic roles the
+ * composer needs are mirrored here as constants. Every value traces to
+ * `packages/ui/src/tokens.css` (the design source of truth) — change it there
+ * first, then keep this slice in step (ADR-0021 records the gap).
+ *
+ * IBM Plex is not loadable without the host app shipping fonts, so type falls
+ * back to the system stack; the mono accents use the platform's monospace face
+ * (the composer passes `Platform.select` for that — this module stays free of
+ * React Native imports so pure code can use it too).
+ */
+export const signal = {
+    /* --fb-color-accent / tints */
+    accent: "#2f6fed",
+    accentTint: "#eaf1fe",
+    accentBorder: "#cfe0fd",
+    /* ink + muted text ramp */
+    text: "#0f1720",
+    textPanel: "#1a2530",
+    textMuted: "#5a6875",
+    textFaint: "#8a97a3",
+    textSubtle: "#9aa7b2",
+    textGhost: "#b3bdc7",
+    /* surfaces + borders */
+    surface: "#ffffff",
+    canvas: "#f4f6f9",
+    sunken: "#eef1f5",
+    border: "#e6ebf0",
+    borderControl: "#e0e6ec",
+    borderStrong: "#dce3ea",
+    /* status colors (danger doubles as the error tone; violet kept in the Signal palette) */
+    danger: "#e5484d",
+    dangerSurface: "#fdecec",
+    dangerBorder: "#f7cfcf",
+    success: "#2f9e5b",
+    successSurface: "#e5f5eb",
+    successBorder: "#bfe6cd",
+    idea: "#8b5cf6",
+    ideaSurface: "#f1ecfe",
+    ideaBorder: "#e0d4fb",
+    /* emphasis */
+    onEmphasis: "#ffffff",
+    scrim: "rgba(15, 23, 32, 0.42)",
+};

package/dist/version.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The Expo SDK's own version string, reported to ingest as
+ * `environment.sdkVersion`. Kept as an inlined constant rather than a runtime
+ * `package.json` import, so the published build stays self-contained (the same
+ * posture as `packages/sdk/src/version.ts`).
+ *
+ * It must equal `package.json`'s `version`. Two things keep it there: the
+ * Changesets `version` step syncs it automatically (`scripts/sync-sdk-version.mjs`,
+ * wired into `version-packages`), and `version.test.ts` fails the build if the two
+ * ever drift. Do not hand-edit this line to a value other than `package.json`'s
+ * version.
+ */
+export declare const EXPO_SDK_VERSION = "0.1.0";

package/dist/version.js

@@ -0,0 +1,13 @@
+/**
+ * The Expo SDK's own version string, reported to ingest as
+ * `environment.sdkVersion`. Kept as an inlined constant rather than a runtime
+ * `package.json` import, so the published build stays self-contained (the same
+ * posture as `packages/sdk/src/version.ts`).
+ *
+ * It must equal `package.json`'s `version`. Two things keep it there: the
+ * Changesets `version` step syncs it automatically (`scripts/sync-sdk-version.mjs`,
+ * wired into `version-packages`), and `version.test.ts` fails the build if the two
+ * ever drift. Do not hand-edit this line to a value other than `package.json`'s
+ * version.
+ */
+export const EXPO_SDK_VERSION = "0.1.0";

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@fixback/expo",
+  "version": "0.1.0",
+  "description": "The Fixback capture SDK for Expo / React Native apps — shake the device to report feedback with trace Evidence.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "fixback",
+    "feedback",
+    "bug-report",
+    "expo",
+    "react-native",
+    "shake",
+    "sdk"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wemuda/fixback.git",
+    "directory": "packages/expo"
+  },
+  "homepage": "https://github.com/wemuda/fixback/tree/master/packages/expo#readme",
+  "bugs": "https://github.com/wemuda/fixback/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@react-native-async-storage/async-storage": ">=1.23.0",
+    "expo-sensors": ">=13.0.0",
+    "react": ">=18.0.0",
+    "react-native": ">=0.74.0",
+    "react-native-view-shot": ">=3.8.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "react": "19.2.8",
+    "react-native": "^0.81.0",
+    "typescript": "5.9.3",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}