@meetreeve/capacitor-bridge 0.1.0

package/README.md

@@ -0,0 +1,134 @@
+# @meetreeve/capacitor-bridge
+
+Reeve.Mobile substrate — the Capacitor wrapper bridge every Reeve consumer mobile app imports. One package, six entrypoints, zero per-app reinvention.
+
+Tracked in [DEV-1387](https://linear.app/mindfortress/issue/DEV-1387) under the Reeve substrate roadmap [DEV-1376](https://linear.app/mindfortress/issue/DEV-1376).
+
+## What it gives you
+
+| Entrypoint | What |
+|---|---|
+| `@meetreeve/capacitor-bridge/core` | Platform detection (`isNativePlatform`, `isIOS`, …), safe-area inset reader, splash-screen dismiss. Framework-agnostic. |
+| `@meetreeve/capacitor-bridge/react` | `<CapacitorProvider>`, `useCapacitor()`, `useSafeArea()`. |
+| `@meetreeve/capacitor-bridge/paywall` | Native-aware paywall gate. Auto-routes to RevenueCat on iOS/Android and Stripe on web. Prevents Apple-review rejection from in-app Stripe Checkout. |
+| `@meetreeve/capacitor-bridge/deeplink` | App-URL listener + handler chain for custom-scheme callbacks (Auth0) and universal links (email/iMessage/push). |
+| `@meetreeve/capacitor-bridge/bugreport` | TestFlight bug-report submitter — POSTs payload + screenshot + environment to a consumer-configured endpoint. |
+| `@meetreeve/capacitor-bridge/compliance` | Apple Privacy Manifest template + canonical Info.plist usage-description catalog (Node-only — used by the scaffold). |
+
+## Install
+
+```bash
+npm install @meetreeve/capacitor-bridge
+```
+
+(Private package — pulled from the org's npm registry. Consumer apps in the MindFortressInc org get it via the standard `@meetreeve/` workspace path.)
+
+## Quick start (React)
+
+```tsx
+import { CapacitorProvider, useCapacitor } from "@meetreeve/capacitor-bridge/react";
+
+function App() {
+  return (
+    <CapacitorProvider>
+      <YourApp />
+    </CapacitorProvider>
+  );
+}
+
+function YourApp() {
+  const { platform, isIOS } = useCapacitor();
+  // …
+}
+```
+
+## Quick start (paywall gate)
+
+```ts
+import {
+  runPaywall,
+  registerNativePaywall,
+  registerWebPaywall,
+  shouldShowWebPaywall,
+} from "@meetreeve/capacitor-bridge/paywall";
+
+// At app boot — wire your platform-specific checkouts
+registerNativePaywall(async (product) => {
+  // Reeve.Commerce DEV-1388 wires RevenueCat here
+  return purchaseViaRevenueCat(product);
+});
+
+registerWebPaywall(async (product) => {
+  // Existing Stripe Checkout redirect
+  window.location.href = await getStripeCheckoutUrl(product.webPriceId!);
+  return { status: "purchased", sourceChannel: "web_stripe" };
+});
+
+// In your paywall UI
+if (shouldShowWebPaywall()) {
+  // render the Stripe button
+}
+const result = await runPaywall({ productId: "pro-monthly", webPriceId: "price_xxx" });
+```
+
+## Quick start (deep links)
+
+```ts
+import {
+  registerDeepLinkHandler,
+  startDeepLinkListener,
+} from "@meetreeve/capacitor-bridge/deeplink";
+
+registerDeepLinkHandler(async (link) => {
+  if (link.scheme.endsWith(".ios") && link.path === "/callback") {
+    await handleAuth0Callback(link.query);
+    return true;
+  }
+  return false;
+});
+
+startDeepLinkListener({
+  onUnhandled: (link) => router.push(link.path + (link.hash ? `#${link.hash}` : "")),
+});
+```
+
+## Quick start (bug report)
+
+```ts
+import { configureBugReport, submitBugReport } from "@meetreeve/capacitor-bridge/bugreport";
+
+configureBugReport({
+  endpoint: "https://api.meetfreya.com/me/bug-report",
+  headers: async () => ({ Authorization: `Bearer ${await getToken()}` }),
+  appVersion: "1.0.0",
+  buildNumber: "42",
+});
+
+await submitBugReport({ message: "Push notification opened wrong project", userIdentifier: "user-42" });
+```
+
+## Architecture notes
+
+- **Zero hard dependencies.** Peers React and `@capacitor/core` are optional — `core/` works in any browser-like environment, `react/` only loads if React is present, `paywall`/`deeplink`/`bugreport` similarly degrade.
+- **SSR-safe.** Every entrypoint guards on `typeof window === "undefined"` and returns sensible defaults (`platform: "web"`, zero insets, no-op dismiss).
+- **One-time install.** `<CapacitorProvider>` installs the safe-area CSS vars + `data-platform` attribute on mount. Idempotent.
+
+## Roadmap
+
+| Substrate PR | What | Where it lives |
+|---|---|---|
+| **PR 1 (this)** | core + react + paywall + deeplink + bugreport + compliance pack | This package |
+| PR 2 | `create-reeve-mobile-app` cookie-cutter | Sibling `packages/create-reeve-mobile-app/` |
+| PR 3 | `reeve-mobile-ci` reusable GH workflow | `.github/workflows/reusable-ios-testflight.yml` |
+| PR 4 | Universal-links Vercel edge fn template | Bridge `deeplink/` already covers the JS side; edge fn = separate folder |
+| PR 5 (this) | Bug-report widget + compliance pack consolidated here | This package |
+
+PR 1 and PR 5 actually land together in this single package — separating them into multiple commits inside one PR.
+
+## Consumers
+
+- Freya iOS ([DEV-1390](https://linear.app/mindfortress/issue/DEV-1390)) — first wedge
+- AgentPik mobile (planned, post-Freya validation)
+- Studio mobile (planned)
+- AskClara mobile (planned, requires HIPAA-mode defaults)
+- Reeve Platform v1 mobile (planned)

package/compliance/PrivacyInfo.xcprivacy.template

@@ -0,0 +1,155 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Apple Privacy Manifest template for Reeve consumer mobile apps.
+
+  Required by App Store review as of Spring 2024 onward. Consumer apps
+  copy this file to their iOS project's App/PrivacyInfo.xcprivacy and
+  customize the collected-data categories + API reason codes to match
+  what the specific app actually does.
+
+  Baseline assumptions (Reeve substrate defaults):
+    - Auth0 collects User ID (email, sub) — already mapped below.
+    - Sentry collects Crash Data + Other Diagnostic Data — already mapped.
+    - PostHog collects Product Interaction + Other Usage Data — already mapped.
+    - No tracking domains (NSPrivacyTracking = false). Reeve apps do not
+      cross-app track; PostHog stays first-party.
+
+  Consumer-specific additions (per app):
+    - Camera / microphone access → add NSPrivacyAccessedAPITypes entries
+      AND ensure the Info.plist has *UsageDescription strings (see
+      compliance/permission-strings.json).
+    - Health / financial data → add the relevant
+      NSPrivacyCollectedDataType entries.
+
+  See compliance/README.md for the full reasoning checklist.
+-->
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>NSPrivacyTracking</key>
+  <false/>
+  <key>NSPrivacyTrackingDomains</key>
+  <array/>
+  <key>NSPrivacyCollectedDataTypes</key>
+  <array>
+    <!-- Auth0 user identity -->
+    <dict>
+      <key>NSPrivacyCollectedDataType</key>
+      <string>NSPrivacyCollectedDataTypeUserID</string>
+      <key>NSPrivacyCollectedDataTypeLinked</key>
+      <true/>
+      <key>NSPrivacyCollectedDataTypeTracking</key>
+      <false/>
+      <key>NSPrivacyCollectedDataTypePurposes</key>
+      <array>
+        <string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
+        <string>NSPrivacyCollectedDataTypePurposeAuthentication</string>
+      </array>
+    </dict>
+    <dict>
+      <key>NSPrivacyCollectedDataType</key>
+      <string>NSPrivacyCollectedDataTypeEmailAddress</string>
+      <key>NSPrivacyCollectedDataTypeLinked</key>
+      <true/>
+      <key>NSPrivacyCollectedDataTypeTracking</key>
+      <false/>
+      <key>NSPrivacyCollectedDataTypePurposes</key>
+      <array>
+        <string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
+      </array>
+    </dict>
+    <!-- Sentry crash + diagnostic data -->
+    <dict>
+      <key>NSPrivacyCollectedDataType</key>
+      <string>NSPrivacyCollectedDataTypeCrashData</string>
+      <key>NSPrivacyCollectedDataTypeLinked</key>
+      <false/>
+      <key>NSPrivacyCollectedDataTypeTracking</key>
+      <false/>
+      <key>NSPrivacyCollectedDataTypePurposes</key>
+      <array>
+        <string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
+        <string>NSPrivacyCollectedDataTypePurposeAnalytics</string>
+      </array>
+    </dict>
+    <dict>
+      <key>NSPrivacyCollectedDataType</key>
+      <string>NSPrivacyCollectedDataTypeOtherDiagnosticData</string>
+      <key>NSPrivacyCollectedDataTypeLinked</key>
+      <false/>
+      <key>NSPrivacyCollectedDataTypeTracking</key>
+      <false/>
+      <key>NSPrivacyCollectedDataTypePurposes</key>
+      <array>
+        <string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
+        <string>NSPrivacyCollectedDataTypePurposeAnalytics</string>
+      </array>
+    </dict>
+    <!-- PostHog product analytics -->
+    <dict>
+      <key>NSPrivacyCollectedDataType</key>
+      <string>NSPrivacyCollectedDataTypeProductInteraction</string>
+      <key>NSPrivacyCollectedDataTypeLinked</key>
+      <true/>
+      <key>NSPrivacyCollectedDataTypeTracking</key>
+      <false/>
+      <key>NSPrivacyCollectedDataTypePurposes</key>
+      <array>
+        <string>NSPrivacyCollectedDataTypePurposeAnalytics</string>
+        <string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
+      </array>
+    </dict>
+    <dict>
+      <key>NSPrivacyCollectedDataType</key>
+      <string>NSPrivacyCollectedDataTypeOtherUsageData</string>
+      <key>NSPrivacyCollectedDataTypeLinked</key>
+      <true/>
+      <key>NSPrivacyCollectedDataTypeTracking</key>
+      <false/>
+      <key>NSPrivacyCollectedDataTypePurposes</key>
+      <array>
+        <string>NSPrivacyCollectedDataTypePurposeAnalytics</string>
+      </array>
+    </dict>
+  </array>
+  <key>NSPrivacyAccessedAPITypes</key>
+  <array>
+    <!-- UserDefaults — Capacitor uses for plugin storage -->
+    <dict>
+      <key>NSPrivacyAccessedAPIType</key>
+      <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
+      <key>NSPrivacyAccessedAPITypeReasons</key>
+      <array>
+        <string>CA92.1</string>
+      </array>
+    </dict>
+    <!-- File timestamp — bridged JS file APIs -->
+    <dict>
+      <key>NSPrivacyAccessedAPIType</key>
+      <string>NSPrivacyAccessedAPICategoryFileTimestamp</string>
+      <key>NSPrivacyAccessedAPITypeReasons</key>
+      <array>
+        <string>C617.1</string>
+      </array>
+    </dict>
+    <!-- System boot time — Sentry uses for crash correlation -->
+    <dict>
+      <key>NSPrivacyAccessedAPIType</key>
+      <string>NSPrivacyAccessedAPICategorySystemBootTime</string>
+      <key>NSPrivacyAccessedAPITypeReasons</key>
+      <array>
+        <string>35F9.1</string>
+      </array>
+    </dict>
+    <!-- Disk space — push notification payload pre-flight -->
+    <dict>
+      <key>NSPrivacyAccessedAPIType</key>
+      <string>NSPrivacyAccessedAPICategoryDiskSpace</string>
+      <key>NSPrivacyAccessedAPITypeReasons</key>
+      <array>
+        <string>E174.1</string>
+      </array>
+    </dict>
+  </array>
+</dict>
+</plist>

package/compliance/README.md

@@ -0,0 +1,42 @@
+# Apple compliance pack
+
+Templates + catalogs every Reeve consumer mobile app uses to satisfy App Store review. Owned by the Reeve.Mobile substrate ([DEV-1387](https://linear.app/mindfortress/issue/DEV-1387)).
+
+## What's in here
+
+| File | Purpose |
+|---|---|
+| `PrivacyInfo.xcprivacy.template` | Apple Privacy Manifest baseline. Mandatory since Spring 2024. Consumer apps copy + extend per their actual data use. |
+| `permission-strings.json` | Canonical Info.plist `*UsageDescription` strings. Specific copy passes review; vague copy gets flagged. Substitute `{{APP_NAME}}` per consumer. |
+| `index.js` | Node helpers — `renderPrivacyInfo()`, `renderPermissionStrings()`. Used by the create-reeve-mobile-app scaffold (PR 2). |
+
+## How consumer apps use this
+
+```js
+const { renderPrivacyInfo, renderPermissionStrings } = require("@meetreeve/capacitor-bridge/compliance");
+
+// Generate Freya's privacy manifest
+const xml = renderPrivacyInfo();
+fs.writeFileSync("ios/App/App/PrivacyInfo.xcprivacy", xml);
+
+// Generate Freya's usage-description strings
+const strings = renderPermissionStrings(
+  ["NSCameraUsageDescription", "NSMicrophoneUsageDescription", "NSFaceIDUsageDescription"],
+  "Freya"
+);
+// → merge into Info.plist
+```
+
+## Apple review checklist
+
+- [ ] `PrivacyInfo.xcprivacy` present at `ios/App/App/PrivacyInfo.xcprivacy`
+- [ ] Every native capability used has a corresponding `*UsageDescription` Info.plist key
+- [ ] `NSPrivacyTracking = false` unless a third-party SDK forces tracking (rare)
+- [ ] No collected data type marked `NSPrivacyCollectedDataTypeTracking = true`
+- [ ] No payment URLs (Stripe Checkout) reachable from inside the app — paywall gate routes to RevenueCat IAP via [DEV-1388](https://linear.app/mindfortress/issue/DEV-1388)
+- [ ] Sign-out option visible if a sign-in option exists (App Store guideline 5.1.1(v))
+- [ ] Account deletion path visible if accounts are supported (App Store guideline 5.1.1(v))
+
+## When to add a new data type
+
+If the consumer app collects a new category Apple recognizes (e.g. Health, Financial Info), open a PR adding it to `PrivacyInfo.xcprivacy.template` so the next consumer doesn't have to re-discover it.

package/compliance/index.cjs

@@ -0,0 +1,60 @@
+/**
+ * compliance/ helpers. CommonJS — small enough to ship without a TS build,
+ * and the cookie-cutter (create-reeve-mobile-app) consumes these in a Node
+ * scaffold script. Browsers never import this; it's tooling only.
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const TEMPLATE_PATH = path.join(__dirname, "PrivacyInfo.xcprivacy.template");
+const PERMISSION_STRINGS_PATH = path.join(__dirname, "permission-strings.json");
+
+/**
+ * Render the PrivacyInfo template — the template has no substitutions today
+ * but we may add them (e.g. extra collected-data types per consumer). For
+ * now it's a straight copy. Returns the xml string.
+ */
+function renderPrivacyInfo() {
+  return fs.readFileSync(TEMPLATE_PATH, "utf8");
+}
+
+/**
+ * Render Info.plist usage-description strings for the requested permission
+ * keys with the consumer's app name substituted in.
+ *
+ * @param {string[]} keys - e.g. ["NSCameraUsageDescription", "NSFaceIDUsageDescription"]
+ * @param {string} appName - the consumer app's display name (e.g. "Freya")
+ * @returns {Record<string, string>}
+ */
+function renderPermissionStrings(keys, appName) {
+  const catalog = JSON.parse(fs.readFileSync(PERMISSION_STRINGS_PATH, "utf8"));
+  const out = {};
+  for (const key of keys) {
+    const template = catalog[key];
+    if (!template) {
+      throw new Error(
+        `[reeve/capacitor-bridge/compliance] unknown permission key: ${key}. ` +
+          `See compliance/permission-strings.json for the catalog.`
+      );
+    }
+    out[key] = template.replaceAll("{{APP_NAME}}", appName);
+  }
+  return out;
+}
+
+/**
+ * List every permission key the catalog knows about.
+ */
+function listPermissionKeys() {
+  const catalog = JSON.parse(fs.readFileSync(PERMISSION_STRINGS_PATH, "utf8"));
+  return Object.keys(catalog).filter((k) => !k.startsWith("$"));
+}
+
+module.exports = {
+  renderPrivacyInfo,
+  renderPermissionStrings,
+  listPermissionKeys,
+  TEMPLATE_PATH,
+  PERMISSION_STRINGS_PATH,
+};

package/compliance/permission-strings.json

@@ -0,0 +1,14 @@
+{
+  "$comment": "Reeve.Mobile substrate — canonical Info.plist usage-description strings. Consumer apps include the keys for capabilities they actually use; Apple rejects builds that declare a capability but omit the matching string. Strings are intentionally specific about WHY we need the capability — vague descriptions also draw rejections.",
+  "NSCameraUsageDescription": "{{APP_NAME}} uses your camera so you can capture photos for your projects.",
+  "NSPhotoLibraryUsageDescription": "{{APP_NAME}} accesses your photo library so you can attach images to your work.",
+  "NSPhotoLibraryAddUsageDescription": "{{APP_NAME}} saves images you create to your photo library.",
+  "NSMicrophoneUsageDescription": "{{APP_NAME}} uses your microphone so you can dictate notes and ideas hands-free.",
+  "NSSpeechRecognitionUsageDescription": "{{APP_NAME}} processes the audio you record so dictation appears as text.",
+  "NSFaceIDUsageDescription": "{{APP_NAME}} uses Face ID to quickly and securely sign you back in.",
+  "NSLocationWhenInUseUsageDescription": "{{APP_NAME}} uses your location to personalize nearby suggestions while the app is open.",
+  "NSBluetoothAlwaysUsageDescription": "{{APP_NAME}} connects to nearby devices to support hardware integrations.",
+  "NSUserTrackingUsageDescription": "{{APP_NAME}} does not track you across other apps or websites — leave this off; we include this string only if a third-party SDK requires it.",
+  "NSContactsUsageDescription": "{{APP_NAME}} accesses your contacts only when you choose to share, so you can invite collaborators.",
+  "NSCalendarsUsageDescription": "{{APP_NAME}} reads your calendar to suggest times that work for you."
+}

package/dist/bugreport/index.cjs

@@ -0,0 +1,143 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/bugreport/index.ts
+var bugreport_exports = {};
+__export(bugreport_exports, {
+  __resetBugReportConfigForTests: () => __resetBugReportConfigForTests,
+  captureScreenshot: () => captureScreenshot,
+  configureBugReport: () => configureBugReport,
+  getBugReportEnvironment: () => getBugReportEnvironment,
+  resetBugReportConfig: () => resetBugReportConfig,
+  submitBugReport: () => submitBugReport
+});
+module.exports = __toCommonJS(bugreport_exports);
+
+// src/core/platform.ts
+function getCapacitor() {
+  if (typeof window === "undefined") return null;
+  const cap = window.Capacitor;
+  if (!cap || typeof cap.isNativePlatform !== "function") return null;
+  return cap;
+}
+function getPlatform() {
+  const cap = getCapacitor();
+  if (!cap) return "web";
+  const p = cap.getPlatform();
+  return p === "ios" ? "ios" : p === "android" ? "android" : "web";
+}
+
+// src/bugreport/index.ts
+var GLOBAL_KEY = /* @__PURE__ */ Symbol.for("@meetreeve/capacitor-bridge/bugreport@1");
+function getGlobalState() {
+  const g = globalThis;
+  if (!g[GLOBAL_KEY]) g[GLOBAL_KEY] = { config: null };
+  return g[GLOBAL_KEY];
+}
+function configureBugReport(c) {
+  const state = getGlobalState();
+  if (state.config && state.config.endpoint !== c.endpoint) {
+    throw new Error(
+      "[@meetreeve/capacitor-bridge/bugreport] configureBugReport has already been called with a different endpoint. Re-configuration is refused so a later-loaded script cannot redirect bug-report submissions. Call __resetBugReportConfigForTests() in tests."
+    );
+  }
+  state.config = Object.freeze({ ...c });
+}
+function __resetBugReportConfigForTests() {
+  getGlobalState().config = null;
+}
+function resetBugReportConfig() {
+  if (typeof console !== "undefined" && typeof console.warn === "function") {
+    console.warn(
+      "[@meetreeve/capacitor-bridge/bugreport] resetBugReportConfig is deprecated; use __resetBugReportConfigForTests."
+    );
+  }
+  __resetBugReportConfigForTests();
+}
+function getBugReportEnvironment() {
+  const config = getGlobalState().config;
+  if (typeof window === "undefined") {
+    return {
+      platform: getPlatform(),
+      userAgent: "",
+      currentUrl: "",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  return {
+    platform: getPlatform(),
+    userAgent: window.navigator?.userAgent ?? "",
+    appVersion: config?.appVersion,
+    buildNumber: config?.buildNumber,
+    currentUrl: window.location?.href ?? "",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+async function submitBugReport(payload) {
+  const config = getGlobalState().config;
+  if (!config) {
+    throw new Error(
+      "[@meetreeve/capacitor-bridge/bugreport] submitBugReport called without configureBugReport({endpoint})."
+    );
+  }
+  const submission = {
+    ...payload,
+    environment: getBugReportEnvironment()
+  };
+  const headers = {
+    "Content-Type": "application/json"
+  };
+  if (config.headers) {
+    const extraHeaders = await config.headers();
+    Object.assign(headers, extraHeaders);
+  }
+  const response = await fetch(config.endpoint, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(submission),
+    credentials: config.credentials ?? "omit"
+  });
+  if (!response.ok) {
+    throw new Error(
+      `[@meetreeve/capacitor-bridge/bugreport] bug-report submission failed: ${response.status} ${response.statusText}`
+    );
+  }
+}
+async function captureScreenshot() {
+  if (typeof window === "undefined") return null;
+  const cap = window.Capacitor;
+  const plugin = cap?.Plugins?.Screenshot;
+  if (plugin) {
+    try {
+      const { base64 } = await plugin.take();
+      return `data:image/png;base64,${base64}`;
+    } catch {
+    }
+  }
+  return null;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  __resetBugReportConfigForTests,
+  captureScreenshot,
+  configureBugReport,
+  getBugReportEnvironment,
+  resetBugReportConfig,
+  submitBugReport
+});

package/dist/bugreport/index.d.cts

@@ -0,0 +1,76 @@
+/**
+ * Bug-report widget.
+ *
+ * TestFlight beta users hit "Report a bug" → small modal → text + optional
+ * screenshot → POST to a consumer-configured endpoint (typically a thin
+ * Slack-relay route on the consumer's backend). Sentry user feedback works
+ * too but the social UX of a Slack channel + screenshot is what beta cohorts
+ * actually respond to.
+ *
+ * This module owns the submission contract + a tiny snapshot helper. The
+ * React widget itself ships in src/react/BugReportButton.tsx (next step) —
+ * consumer apps that don't use React can call submitBugReport() directly.
+ */
+interface BugReportPayload {
+    message: string;
+    /** Optional screenshot — data URL or remote URL — uploaded as part of report. */
+    screenshot?: string;
+    /** Consumer-supplied user identifier (subscriber_id, email — whatever's stable). */
+    userIdentifier?: string;
+    /** Free-form metadata; merged with platform info before send. */
+    extra?: Record<string, unknown>;
+}
+interface BugReportEnvironment {
+    platform: string;
+    userAgent: string;
+    appVersion?: string;
+    buildNumber?: string;
+    currentUrl: string;
+    timestamp: string;
+}
+interface BugReportSubmission extends BugReportPayload {
+    environment: BugReportEnvironment;
+}
+interface BugReportConfig {
+    endpoint: string;
+    /** Headers to attach (auth token, host-app key, etc.). */
+    headers?: () => Record<string, string> | Promise<Record<string, string>>;
+    /** Consumer-supplied version metadata. */
+    appVersion?: string;
+    buildNumber?: string;
+    /**
+     * fetch credentials mode. Defaults to `"omit"` because the Capacitor
+     * WebView origin (`capacitor://localhost`) differs from the consumer's API
+     * origin, so cookie-based auth wouldn't flow anyway, and `omit` avoids
+     * accidentally turning the bug-report endpoint into a CSRF target if the
+     * consumer enables permissive CORS. Set to `"include"` only when you
+     * understand the consequences for the consumer's endpoint.
+     */
+    credentials?: "omit" | "same-origin" | "include";
+}
+declare function configureBugReport(c: BugReportConfig): void;
+/** Internal — for tests only. */
+declare function __resetBugReportConfigForTests(): void;
+/** @deprecated use __resetBugReportConfigForTests; prod calls now warn. */
+declare function resetBugReportConfig(): void;
+declare function getBugReportEnvironment(): BugReportEnvironment;
+/**
+ * Submit a bug report to the configured endpoint. Throws if not configured.
+ *
+ * The post body always includes a top-level `environment` object — consumer
+ * backends can route on `environment.platform === "ios"` to tag with a
+ * Slack emoji, etc.
+ */
+declare function submitBugReport(payload: BugReportPayload): Promise<void>;
+/**
+ * Capture the current screen as a data URL using the Capacitor Screenshot
+ * plugin (if present) or a DOM-canvas fallback. Returns null if no capture
+ * method is available — the bug-report modal then submits without an image.
+ *
+ * Note: many WebView screenshot plugins can't capture native chrome (push
+ * banners, system alerts). For TestFlight QA that's fine — the bug message
+ * almost always describes the chrome anyway.
+ */
+declare function captureScreenshot(): Promise<string | null>;
+
+export { type BugReportEnvironment, type BugReportPayload, type BugReportSubmission, __resetBugReportConfigForTests, captureScreenshot, configureBugReport, getBugReportEnvironment, resetBugReportConfig, submitBugReport };