yaver-feedback-react-native 0.9.0 → 0.9.2

package/src/types.ts

@@ -1,3 +1,7 @@
+// Type-only: BlackBox.ts already imports from this module, so a value import
+// would close a cycle. `import type` is erased at compile time.
+import type { BlackBoxConfig } from './BlackBox';
+
 /**
  * Remote browser-style sign-in session for a coding-agent CLI on the
  * connected yaver host. Mirrors runnerBrowserAuthSession on the agent
@@ -122,9 +126,33 @@ export interface CapabilitySnapshot {
   targets: Record<string, CapabilityTargetReadiness>;
 }
 
+/**
+ * Opt-in config for the overlay's "App Store screenshots" action and the
+ * `capture_store_shots` remote command. When set, the SDK can walk the
+ * app's routes on-device, screenshot each, and upload them to the agent
+ * (which runs the App Store Connect backend).
+ */
+export interface StoreShotsConfig {
+  /** Ordered routes to visit + screenshot (e.g. ['/(tabs)/home', ...]). */
+  routes: string[];
+  /** Navigation handle: a react-navigation ref or expo-router `router`. */
+  navigationRef?: any;
+  /** Also set metadata + attempt submit-for-review after upload. */
+  submit?: boolean;
+  /** Optional per-route screenshot names (defaults to NN_<route>). */
+  screens?: string[];
+}
+
 export interface FeedbackConfig {
   /** URL of the Yaver agent (e.g. "http://192.168.1.10:18080"). If omitted, auto-discovery is used. */
   agentUrl?: string;
+  /**
+   * Enables the overlay's "App Store screenshots" action + the
+   * `capture_store_shots` remote command. The host supplies the route
+   * list (and a navigation ref) once; the SDK captures the real running
+   * app — no simulator needed.
+   */
+  storeShots?: StoreShotsConfig;
   /**
    * Auth token for the Yaver agent. Optional in 0.5+: if omitted, the SDK
    * will hydrate one from AsyncStorage or show its in-app login screen
@@ -164,6 +192,39 @@ export interface FeedbackConfig {
    * If omitted with convexUrl, connects to the first online device.
    */
   preferredDeviceId?: string;
+  /**
+   * Identity of the app this SDK instance reports for. Both fields are
+   * resolved automatically from expo-constants / native modules when
+   * omitted, so most apps never set them.
+   *
+   * Set them when the ambient answer would be wrong — above all when the
+   * app's JS is pushed into Yaver's container as a Hermes guest. There the
+   * runtime IS Yaver: `expo-constants` and `SettingsManager` describe the
+   * host (`Yaver` / `io.yaver.mobile`), not the guest, so auto-resolution
+   * would file every report against Yaver's own repo and the fix task would
+   * edit the SDK instead of the app. Declaring identity here is the only
+   * answer that holds in both a standalone build and a guest bundle.
+   *
+   * `bundleId` is the key that actually routes: the agent matches it against
+   * each project's pbxproj / build.gradle / app.json. `projectName` is a
+   * fallback for platforms with no bundle id.
+   */
+  projectName?: string;
+  bundleId?: string;
+  /** Primary Yaver product surface for this app/package. */
+  surface?: YaverSurface;
+  /** All product surfaces this app/package owns. */
+  surfaces?: YaverSurface[];
+  /** Canonical development stack labels, e.g. react-native-expo, yaver-xml. */
+  stack?: string;
+  stacks?: string[];
+  /** Yaver preview/runtime targets that can exercise this app. */
+  testSurfaces?: string[];
+  feedbackSdk?: string;
+  feedbackTransport?: string;
+  voiceCapabilities?: string[];
+  sttProvider?: string;
+  ttsProvider?: string;
   /** How feedback collection is triggered */
   trigger?: 'shake' | 'floating-button' | 'manual';
   /**
@@ -204,6 +265,22 @@ export interface FeedbackConfig {
    * Calling `BlackBox.start()` manually is still safe — it's idempotent.
    */
   autoStartBlackBox?: boolean;
+  /**
+   * Config handed to BlackBox when the SDK auto-starts it.
+   *
+   * Without this there was no way to configure the flight recorder at all.
+   * The obvious move — and the one the README's own snippet makes — is:
+   *
+   *     YaverFeedback.init({ trigger: 'shake' });
+   *     BlackBox.start({ appName: 'my-app' });
+   *
+   * but that start() early-returns, because a zero-config init has no
+   * agentUrl yet (discovery resolves it asynchronously). The auto-start then
+   * fires ~500ms later once the agent and token exist and calls `start()`
+   * with NO arguments — so the host's config is silently dropped and appName
+   * is ''. Pass it here instead and the auto-start will honour it.
+   */
+  blackBox?: BlackBoxConfig;
   /**
    * Small tap-to-open icon that floats above the app so the user
    * doesn't have to shake every time they want to open feedback.
@@ -289,6 +366,26 @@ export interface FeedbackConfig {
    * Bugsnag, or any other error tracking tool.
    */
   maxCapturedErrors?: number;
+  /**
+   * Crash-aware reporting/fixing. Defaults to disabled.
+   *
+   * - enabled: records fatal errors into the SDK error buffer and enables
+   *   explicit `YaverFeedback.reportCrash(error)`.
+   * - installGlobalHandler: opt-in only. Wraps React Native's global ErrorUtils
+   *   handler without suppressing the existing handler. Leave false when Sentry,
+   *   Crashlytics, Bugsnag, or another crash tool owns the global handler.
+   * - autoFix: after uploading a crash report, ask the connected Yaver agent to
+   *   create a fix task. The normal BlackBox command stream can then deliver a
+   *   reload/reload_bundle command after the agent rebuilds.
+   * - captureScreenshot: attach a best-effort screenshot to the crash report.
+   */
+  crashReporting?: {
+    enabled?: boolean;
+    installGlobalHandler?: boolean;
+    autoFix?: boolean;
+    captureScreenshot?: boolean;
+    metadata?: Record<string, unknown>;
+  };
   /**
    * Which platforms the Build button targets.
    * - 'ios' — build iOS only
@@ -404,9 +501,36 @@ export interface CapturedError {
 
 export interface FeedbackMetadata {
   timestamp: string;
-  device: DeviceInfo;
+  /**
+   * Wire key is `deviceInfo`, matching the Flutter + web SDKs and the
+   * agent's `FeedbackReport.DeviceInfo` (`json:"deviceInfo"`). This was
+   * `device` until 0.9.2 — a key the agent never read, so the whole block
+   * (platform, model, and the app name the fix router needs) was silently
+   * dropped on every React Native report. The agent still accepts the old
+   * key so builds already in the field keep working.
+   */
+  deviceInfo: DeviceInfo;
   app: AppInfo;
+  /**
+   * Which of the host's projects this report is about. The agent resolves
+   * a feedback→fix task's working directory from this; without it the task
+   * falls back to whatever directory the agent happens to be sitting in.
+   * Populated automatically by `resolveReportIdentity()`.
+   */
+  project?: FeedbackProjectRef;
   userNote?: string;
+  reportKind?: 'feedback' | 'auto-report' | 'crash';
+  crash?: {
+    message: string;
+    isFatal: boolean;
+    source: 'manual' | 'global-handler';
+    autoFixRequested?: boolean;
+  };
+  twin?: {
+    sessionId?: string;
+    surface?: string;
+    artifactDir?: string;
+  };
 }
 
 export interface DeviceInfo {
@@ -415,6 +539,8 @@ export interface DeviceInfo {
   model: string;
   screenWidth: number;
   screenHeight: number;
+  /** Host app name. First key the agent's fix router checks. */
+  appName?: string;
 }
 
 export interface AppInfo {
@@ -423,6 +549,43 @@ export interface AppInfo {
   buildNumber?: string;
 }
 
+/**
+ * Identifies the host project a report belongs to. Mirrors the web SDK's
+ * `FeedbackProjectRef` and the agent's `FeedbackProject`.
+ */
+export interface FeedbackProjectRef {
+  appName?: string;
+  projectName?: string;
+  /**
+   * Bundle identifier / applicationId. The only unambiguous key: an app's
+   * display name ("Talos") does not match the agent's registry name for it
+   * ("talos / mobile"), and one repo can hold several mobile projects that
+   * all share a name prefix. The agent matches this against the project's
+   * pbxproj, build.gradle, and app.json.
+   */
+  bundleId?: string;
+  /**
+   * Deliberately never set by this SDK. The agent ignores client-supplied
+   * paths for feedback reports (an untrusted guest could otherwise point the
+   * fix task's CWD at ~/.ssh) and resolves the path server-side. Present only
+   * so the type matches the wire format the agent parses.
+   */
+  projectPath?: string;
+  surface?: YaverSurface;
+  surfaces?: YaverSurface[];
+  stack?: string;
+  stacks?: string[];
+  testSurfaces?: string[];
+  feedbackSdk?: string;
+  feedbackTransport?: string;
+  voiceCapabilities?: string[];
+  sttProvider?: string;
+  ttsProvider?: string;
+  releaseChannel?: 'production' | 'candidate' | 'development';
+}
+
+export type YaverSurface = 'web' | 'mobile' | 'backend' | 'watch' | 'tv' | 'car' | 'vision' | 'desktop' | 'cli';
+
 export interface TimelineEvent {
   type: 'screenshot' | 'audio' | 'video';
   path: string;