@switchlabs/verify-ai-react-native 2.5.3 → 2.5.5

package/lib/components/VerifyAIScanner.js

@@ -8,6 +8,7 @@ import { SDK_VERSION } from '../version';
 import { BikeOverlay } from './BikeOverlay';
 import { ScooterOverlay } from './ScooterOverlay';
 import { ANDROID_ACCELEROMETER_AXIS_DOMINANCE_THRESHOLD, classifyAndroidAccelerometerOrientation, getOverlayRotationDeg, } from './scannerOrientation';
+import { CAMERA_CAPTURE_RETRY_DELAY_MS, getCameraCaptureRetryPlan, } from './cameraCaptureRetry';
 /** Quality used when expo-image-manipulator is not available (lower = smaller). */
 const FALLBACK_QUALITY = 0.65;
 /** Quality used when expo-image-manipulator IS available (resize handles size). */
@@ -19,10 +20,6 @@ const CAMERA_NOT_READY_ERROR_CODE = 'ERR_CAMERA_NOT_READY';
 const CAMERA_INIT_ERROR_CODE = 'ERR_CAMERA_INIT_FAILED';
 const DEFAULT_TERMINAL_RESULT_DISPLAY_MS = 3000;
 const TRANSIENT_ERROR_DISPLAY_MS = 3000;
-const CAMERA_CAPTURE_RETRY_DELAY_MS = 350;
-const CAMERA_CAPTURE_RETRY_TORCH_SETTLE_MS = 800;
-const IOS_CAMERA_CAPTURE_RETRY_READY_TIMEOUT_MS = 3000;
-const ANDROID_CAMERA_CAPTURE_RETRY_READY_TIMEOUT_MS = 10000;
 // iOS AVCaptureSession cold start can legitimately exceed 8s on first launch (permission
 // prompt, first-ever session spin-up, thermal/low-power throttling). An 8s watchdog tore
 // down sessions that were seconds from ready and restarted from scratch, which made slow
@@ -297,6 +294,7 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
         device_os_version: String(Platform.Version),
         route_name: telemetryContext?.routeName,
         is_portrait_locked: telemetryContext?.isPortraitLocked,
+        host_reference_id: telemetryContext?.hostReferenceId,
         window_width: windowWidth,
         window_height: windowHeight,
         interface_orientation: isLandscape ? 'landscape' : 'portrait',
@@ -917,15 +915,20 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                             : exhausted
                                 ? 'exhausted'
                                 : null;
-        telemetry?.track('camera_capture_request', {
-            component: 'scanner',
-            error: blockedReason == null ? 'capture_requested' : 'capture_ignored',
-            metadata: buildScannerTelemetryMetadata({
-                capture_attempt_id: captureAttemptId,
-                capture_sequence: captureSequence,
-                capture_blocked_reason: blockedReason,
-            }),
-        });
+        if (telemetry) {
+            // Do not begin native capture until the user's shutter intent is on disk.
+            // If the process is force-closed during capture or delivery, the next SDK
+            // initialization recovers and sends this exact capture_attempt_id.
+            await telemetry.trackDurably('camera_capture_request', {
+                component: 'scanner',
+                error: blockedReason == null ? 'capture_requested' : 'capture_ignored',
+                metadata: buildScannerTelemetryMetadata({
+                    capture_attempt_id: captureAttemptId,
+                    capture_sequence: captureSequence,
+                    capture_blocked_reason: blockedReason,
+                }),
+            });
+        }
         if (blockedReason && blockedReason !== 'camera_not_ready')
             return;
         if (blockedReason === 'camera_not_ready') {
@@ -958,6 +961,7 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
         let captureRetryTorchSuppressed = false;
         let captureRetrySettleDelayMs = CAMERA_CAPTURE_RETRY_DELAY_MS;
         let captureRetryRemountBackoffMs = 0;
+        let captureRetryReadyTimeoutMs = 0;
         let lastNativeCaptureErrorMessage = null;
         try {
             const capturePhysicalOrientation = physicalOrientation;
@@ -1025,13 +1029,11 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                         lastNativeCaptureErrorMessage = normalized.message;
                         if (attempt === 1 && isNativeCameraCaptureError(normalized) && !terminated) {
                             captureRetryAttempted = true;
-                            captureRetryTorchSuppressed = !!enableTorch;
-                            captureRetrySettleDelayMs = captureRetryTorchSuppressed
-                                ? CAMERA_CAPTURE_RETRY_TORCH_SETTLE_MS
-                                : CAMERA_CAPTURE_RETRY_DELAY_MS;
-                            captureRetryRemountBackoffMs = captureRetryTorchSuppressed
-                                ? CAMERA_CAPTURE_RETRY_DELAY_MS
-                                : 0;
+                            const retryPlan = getCameraCaptureRetryPlan(Platform.OS, !!enableTorch);
+                            captureRetryTorchSuppressed = retryPlan.suppressTorch;
+                            captureRetrySettleDelayMs = retryPlan.settleDelayMs;
+                            captureRetryRemountBackoffMs = retryPlan.remountBackoffMs;
+                            captureRetryReadyTimeoutMs = retryPlan.readyTimeoutMs;
                             const retryAt = new Date().toISOString();
                             lastCaptureRetryAtRef.current = retryAt;
                             cameraRemountCountRef.current++;
@@ -1042,9 +1044,6 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                                 ? { backoffMs: captureRetryRemountBackoffMs }
                                 : undefined);
                             await sleep(captureRetrySettleDelayMs);
-                            const captureRetryReadyTimeoutMs = Platform.OS === 'android'
-                                ? ANDROID_CAMERA_CAPTURE_RETRY_READY_TIMEOUT_MS
-                                : IOS_CAMERA_CAPTURE_RETRY_READY_TIMEOUT_MS;
                             captureRetryReady = await waitForCameraReady(captureRetryReadyTimeoutMs);
                             telemetry?.track('camera_capture_retry', {
                                 component: 'scanner',
@@ -1142,6 +1141,7 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                     capture_retry_torch_suppressed: captureRetryTorchSuppressed,
                     capture_retry_settle_delay_ms: captureRetrySettleDelayMs,
                     capture_retry_remount_backoff_ms: captureRetryRemountBackoffMs,
+                    capture_retry_ready_timeout_ms: captureRetryReadyTimeoutMs,
                     recovered_native_capture_failure: captureRetryAttempted ? 1 : 0,
                     last_native_capture_error: lastNativeCaptureErrorMessage,
                 }),
@@ -1218,6 +1218,7 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                         capture_retry_torch_suppressed: captureRetryTorchSuppressed,
                         capture_retry_settle_delay_ms: captureRetrySettleDelayMs,
                         capture_retry_remount_backoff_ms: captureRetryRemountBackoffMs,
+                        capture_retry_ready_timeout_ms: captureRetryReadyTimeoutMs,
                         is_native_camera_capture_error: isNativeCameraCaptureError(error),
                         last_native_capture_error: lastNativeCaptureErrorMessage,
                     }),

package/lib/components/cameraCaptureRetry.d.ts

@@ -0,0 +1,12 @@
+export declare const CAMERA_CAPTURE_RETRY_DELAY_MS = 350;
+export declare const CAMERA_CAPTURE_RETRY_TORCH_SETTLE_MS = 800;
+export declare const IOS_CAMERA_CAPTURE_RETRY_READY_TIMEOUT_MS = 3000;
+export declare const ANDROID_CAMERA_CAPTURE_RETRY_READY_TIMEOUT_MS = 10000;
+export type CameraCaptureRetryPlatform = 'ios' | 'android' | string;
+export interface CameraCaptureRetryPlan {
+    readyTimeoutMs: number;
+    remountBackoffMs: number;
+    settleDelayMs: number;
+    suppressTorch: boolean;
+}
+export declare function getCameraCaptureRetryPlan(platform: CameraCaptureRetryPlatform, torchRequested: boolean): CameraCaptureRetryPlan;

package/lib/components/cameraCaptureRetry.js

@@ -0,0 +1,23 @@
+export const CAMERA_CAPTURE_RETRY_DELAY_MS = 350;
+export const CAMERA_CAPTURE_RETRY_TORCH_SETTLE_MS = 800;
+export const IOS_CAMERA_CAPTURE_RETRY_READY_TIMEOUT_MS = 3000;
+export const ANDROID_CAMERA_CAPTURE_RETRY_READY_TIMEOUT_MS = 10000;
+export function getCameraCaptureRetryPlan(platform, torchRequested) {
+    const suppressTorch = torchRequested;
+    return {
+        readyTimeoutMs: platform === 'android'
+            ? ANDROID_CAMERA_CAPTURE_RETRY_READY_TIMEOUT_MS
+            : IOS_CAMERA_CAPTURE_RETRY_READY_TIMEOUT_MS,
+        // Flutter fully restarts its CameraController after native capture errors.
+        // On iOS/Expo Camera, a key-only remount can report ready too quickly while
+        // the native capture session is still unable to produce a photo, so force a
+        // brief unmount before the retry.
+        remountBackoffMs: platform === 'ios' || suppressTorch
+            ? CAMERA_CAPTURE_RETRY_DELAY_MS
+            : 0,
+        settleDelayMs: suppressTorch
+            ? CAMERA_CAPTURE_RETRY_TORCH_SETTLE_MS
+            : CAMERA_CAPTURE_RETRY_DELAY_MS,
+        suppressTorch,
+    };
+}

package/lib/telemetry/TelemetryReporter.d.ts

@@ -1,5 +1,12 @@
+interface TelemetryTrackOptions {
+    component?: string;
+    error?: unknown;
+    errorCode?: string;
+    metadata?: Record<string, string | number>;
+}
 export declare class TelemetryReporter {
     private buffer;
+    private inFlightBuffer;
     private flushTimer;
     private sessionId;
     private baseUrl;
@@ -8,6 +15,7 @@ export declare class TelemetryReporter {
     private flushing;
     private loadedPersisted;
     private loadPersistedPromise;
+    private persistenceChain;
     constructor(apiKey: string, baseUrl: string);
     /** Telemetry POST destination — exposed so the scanner can log an init banner
      * that helps field debugging confirm where events are being sent. */
@@ -16,12 +24,14 @@ export declare class TelemetryReporter {
     getApiKeyPrefix(): string;
     private logDeliveryFailure;
     /** Track an error event. Fire-and-forget — never throws. */
-    track(eventType: string, opts?: {
-        component?: string;
-        error?: unknown;
-        errorCode?: string;
-        metadata?: Record<string, string | number>;
-    }): void;
+    track(eventType: string, opts?: TelemetryTrackOptions): void;
+    /**
+     * Record an event and wait until it is durably stored before returning.
+     *
+     * Use this for user intent that must survive an immediate force-close. Network
+     * delivery starts after the local write, but callers do not wait on the network.
+     */
+    trackDurably(eventType: string, opts?: TelemetryTrackOptions): Promise<void>;
     /** Flush all buffered events immediately. Returns a promise but never rejects. */
     flush(): Promise<void>;
     /** Dispose — flush remaining events and stop timers. */
@@ -29,6 +39,8 @@ export declare class TelemetryReporter {
     private scheduleFlush;
     private flushNow;
     private clearFlushTimer;
+    private recordEvent;
+    private persistAfterRecovery;
     /**
      * Persist the current buffer to AsyncStorage so events survive abrupt app exits.
      * Fire-and-forget — never throws or blocks.
@@ -37,6 +49,7 @@ export declare class TelemetryReporter {
      * to avoid overwriting orphaned events from a previous session before recovery.
      */
     private persistBuffer;
+    private persistBufferAsync;
     /**
      * Load persisted events from a previous session and merge into current buffer.
      * Runs once per instance. If orphaned events are found, emits an
@@ -45,3 +58,4 @@ export declare class TelemetryReporter {
      */
     private loadPersistedBuffer;
 }
+export {};

package/lib/telemetry/TelemetryReporter.js

@@ -15,6 +15,7 @@ const CRITICAL_EVENTS = new Set([
     'camera_preview_timeout',
     'camera_startup_slow',
     'camera_permission_denied',
+    'camera_capture_request',
     'camera_scanner_mounted',
     'camera_scanner_disposed',
     'camera_android_native_orientation_started',
@@ -30,11 +31,13 @@ const CRITICAL_EVENTS = new Set([
 export class TelemetryReporter {
     constructor(apiKey, baseUrl) {
         this.buffer = new Map();
+        this.inFlightBuffer = new Map();
         this.flushTimer = null;
         this.disposed = false;
         this.flushing = false;
         this.loadedPersisted = false;
         this.loadPersistedPromise = null;
+        this.persistenceChain = Promise.resolve();
         this.apiKey = apiKey;
         this.baseUrl = baseUrl.replace(/\/$/, '');
         this.sessionId = Math.random().toString(36).slice(2) + Date.now().toString(36);
@@ -60,61 +63,42 @@ export class TelemetryReporter {
         if (this.disposed)
             return;
         try {
-            const now = new Date().toISOString();
-            const errorObj = opts.error instanceof Error ? opts.error : null;
-            const errorMessage = errorObj?.message
-                ?? (typeof opts.error === 'string' ? opts.error : undefined);
-            const dedupKey = `${eventType}|${errorMessage ?? ''}|${opts.component ?? ''}`;
-            const existing = this.buffer.get(dedupKey);
-            if (existing) {
-                existing.event_count++;
-                existing.last_occurred_at = now;
-                // If the new occurrence is critical, flush immediately
-                if (CRITICAL_EVENTS.has(eventType)) {
-                    this.flushNow();
-                }
-                return;
-            }
-            const event = {
-                event_type: eventType,
-                component: opts.component,
-                error_message: errorMessage?.slice(0, 1000),
-                error_stack: errorObj?.stack?.slice(0, 2000),
-                error_code: opts.errorCode,
-                metadata: opts.metadata,
-                sdk_platform: Platform.OS,
-                sdk_version: SDK_VERSION,
-                os_name: Platform.OS,
-                os_version: String(Platform.Version),
-                session_id: this.sessionId,
-                event_count: 1,
-                first_occurred_at: now,
-                last_occurred_at: now,
-            };
-            this.buffer.set(dedupKey, event);
+            this.recordEvent(eventType, opts);
             if (CRITICAL_EVENTS.has(eventType)) {
-                this.flushNow();
+                // Critical events are written locally before delivery starts. This keeps
+                // them recoverable if the process is killed while the POST is in flight.
+                void this.persistAfterRecovery().then(() => this.flushNow());
             }
             else {
                 this.scheduleFlush();
-            }
-            // Persist immediately once prior-session recovery has completed. If startup
-            // recovery is still in flight, write the merged buffer back afterwards.
-            if (this.loadedPersisted) {
-                this.persistBuffer();
-            }
-            else {
-                void this.loadPersistedBuffer().then(() => {
-                    if (!this.disposed && this.buffer.size > 0) {
-                        this.persistBuffer();
-                    }
-                });
+                void this.persistAfterRecovery();
             }
         }
         catch {
             // Never throw from telemetry
         }
     }
+    /**
+     * Record an event and wait until it is durably stored before returning.
+     *
+     * Use this for user intent that must survive an immediate force-close. Network
+     * delivery starts after the local write, but callers do not wait on the network.
+     */
+    async trackDurably(eventType, opts = {}) {
+        if (this.disposed)
+            return;
+        try {
+            await this.loadPersistedBuffer();
+            if (this.disposed)
+                return;
+            this.recordEvent(eventType, opts);
+            await this.persistBufferAsync();
+            this.flushNow();
+        }
+        catch {
+            // Never throw from telemetry or block the host capture flow.
+        }
+    }
     /** Flush all buffered events immediately. Returns a promise but never rejects. */
     async flush() {
         // Merge any persisted events from a previous session before flushing
@@ -125,6 +109,7 @@ export class TelemetryReporter {
         const bufferedEntries = Array.from(this.buffer.entries());
         const events = bufferedEntries.map(([, event]) => event);
         this.buffer.clear();
+        this.inFlightBuffer = new Map(bufferedEntries);
         this.clearFlushTimer();
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), 10000);
@@ -151,8 +136,10 @@ export class TelemetryReporter {
                 loggedDeliveryFailure = true;
                 throw new Error(`Telemetry request failed with status ${response.status}`);
             }
-            // Success — clear persisted buffer since events are now server-side
-            this.persistBuffer(); // buffer is empty at this point, so this clears the key
+            this.inFlightBuffer.clear();
+            // Success — persist the current buffer. Usually empty, but it may contain
+            // events recorded while this request was in flight.
+            await this.persistBufferAsync();
         }
         catch (error) {
             if (!loggedDeliveryFailure) {
@@ -175,6 +162,7 @@ export class TelemetryReporter {
                     this.buffer.set(dedupKey, event);
                 }
             }
+            this.inFlightBuffer.clear();
         }
         finally {
             clearTimeout(timeout);
@@ -208,6 +196,42 @@ export class TelemetryReporter {
             this.flushTimer = null;
         }
     }
+    recordEvent(eventType, opts) {
+        const now = new Date().toISOString();
+        const errorObj = opts.error instanceof Error ? opts.error : null;
+        const errorMessage = errorObj?.message
+            ?? (typeof opts.error === 'string' ? opts.error : undefined);
+        const occurrenceId = opts.metadata?.capture_attempt_id;
+        const dedupKey = `${eventType}|${errorMessage ?? ''}|${opts.component ?? ''}|${occurrenceId ?? ''}`;
+        const existing = this.buffer.get(dedupKey);
+        if (existing) {
+            existing.event_count++;
+            existing.last_occurred_at = now;
+            if (opts.metadata)
+                existing.metadata = opts.metadata;
+            return;
+        }
+        this.buffer.set(dedupKey, {
+            event_type: eventType,
+            component: opts.component,
+            error_message: errorMessage?.slice(0, 1000),
+            error_stack: errorObj?.stack?.slice(0, 2000),
+            error_code: opts.errorCode,
+            metadata: opts.metadata,
+            sdk_platform: Platform.OS,
+            sdk_version: SDK_VERSION,
+            os_name: Platform.OS,
+            os_version: String(Platform.Version),
+            session_id: this.sessionId,
+            event_count: 1,
+            first_occurred_at: now,
+            last_occurred_at: now,
+        });
+    }
+    async persistAfterRecovery() {
+        await this.loadPersistedBuffer();
+        await this.persistBufferAsync();
+    }
     /**
      * Persist the current buffer to AsyncStorage so events survive abrupt app exits.
      * Fire-and-forget — never throws or blocks.
@@ -216,24 +240,38 @@ export class TelemetryReporter {
      * to avoid overwriting orphaned events from a previous session before recovery.
      */
     persistBuffer() {
+        void this.persistBufferAsync();
+    }
+    persistBufferAsync() {
         if (!this.loadedPersisted)
-            return; // Don't overwrite orphaned prior-session data before it's loaded
+            return Promise.resolve();
         try {
             const entries = {};
+            for (const [key, event] of this.inFlightBuffer) {
+                entries[key] = event;
+            }
             for (const [key, event] of this.buffer) {
                 entries[key] = event;
             }
-            getStorage().then(s => {
+            // Serialize writes so an older fire-and-forget snapshot cannot overwrite a
+            // newer durable capture marker or resurrect an acknowledged event.
+            this.persistenceChain = this.persistenceChain
+                .catch(() => { })
+                .then(async () => {
+                const storage = await getStorage();
                 if (Object.keys(entries).length > 0) {
-                    s.setItem(TELEMETRY_PERSIST_KEY, JSON.stringify(entries));
+                    await storage.setItem(TELEMETRY_PERSIST_KEY, JSON.stringify(entries));
                 }
                 else {
-                    s.removeItem(TELEMETRY_PERSIST_KEY);
+                    await storage.removeItem(TELEMETRY_PERSIST_KEY);
                 }
-            }).catch(() => { });
+            })
+                .catch(() => { });
+            return this.persistenceChain;
         }
         catch {
             // Never throw from telemetry
+            return Promise.resolve();
         }
     }
     /**

package/lib/types/index.d.ts

@@ -33,6 +33,8 @@ export interface VerificationResult {
     policy: string;
     violation_reasons: string[];
     feedback: string;
+    warning_violation_reasons?: string[];
+    warning_feedback?: string | null;
     metadata: Record<string, unknown>;
     image_url: string | null;
     /** Base64-encoded image data URI. Only present when `include_image_data` is requested. */
@@ -85,6 +87,8 @@ export interface ScannerTelemetryContext {
     routeName?: string;
     /** Whether the host app keeps this screen portrait-locked. */
     isPortraitLocked?: boolean;
+    /** Host-owned identifier used to correlate scanner telemetry with its workflow. */
+    hostReferenceId?: string;
 }
 /**
  * Theme customization for the scanner overlay.

package/lib/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "2.5.2";
+export declare const SDK_VERSION = "2.5.5";

package/lib/version.js

@@ -1 +1 @@
-export const SDK_VERSION = '2.5.2';
+export const SDK_VERSION = '2.5.5';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@switchlabs/verify-ai-react-native",
-  "version": "2.5.3",
+  "version": "2.5.5",
   "description": "React Native SDK for Verify AI - photo verification with AI vision processing",
   "repository": {
     "type": "git",
@@ -25,6 +25,7 @@
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
+    "test": "vitest run",
     "build": "tsc",
     "prepublishOnly": "npm run build"
   },

package/src/components/VerifyAIScanner.tsx

@@ -32,6 +32,10 @@ import {
   getOverlayRotationDeg,
   type ScannerPhysicalOrientation,
 } from './scannerOrientation';
+import {
+  CAMERA_CAPTURE_RETRY_DELAY_MS,
+  getCameraCaptureRetryPlan,
+} from './cameraCaptureRetry';
 
 /** Quality used when expo-image-manipulator is not available (lower = smaller). */
 const FALLBACK_QUALITY = 0.65;
@@ -44,10 +48,6 @@ const CAMERA_NOT_READY_ERROR_CODE = 'ERR_CAMERA_NOT_READY';
 const CAMERA_INIT_ERROR_CODE = 'ERR_CAMERA_INIT_FAILED';
 const DEFAULT_TERMINAL_RESULT_DISPLAY_MS = 3000;
 const TRANSIENT_ERROR_DISPLAY_MS = 3000;
-const CAMERA_CAPTURE_RETRY_DELAY_MS = 350;
-const CAMERA_CAPTURE_RETRY_TORCH_SETTLE_MS = 800;
-const IOS_CAMERA_CAPTURE_RETRY_READY_TIMEOUT_MS = 3000;
-const ANDROID_CAMERA_CAPTURE_RETRY_READY_TIMEOUT_MS = 10000;
 // iOS AVCaptureSession cold start can legitimately exceed 8s on first launch (permission
 // prompt, first-ever session spin-up, thermal/low-power throttling). An 8s watchdog tore
 // down sessions that were seconds from ready and restarted from scratch, which made slow
@@ -409,6 +409,7 @@ export function VerifyAIScanner({
     device_os_version: String(Platform.Version),
     route_name: telemetryContext?.routeName,
     is_portrait_locked: telemetryContext?.isPortraitLocked,
+    host_reference_id: telemetryContext?.hostReferenceId,
     window_width: windowWidth,
     window_height: windowHeight,
     interface_orientation: isLandscape ? 'landscape' : 'portrait',
@@ -1125,15 +1126,20 @@ export function VerifyAIScanner({
                   ? 'exhausted'
                   : null;
 
-    telemetry?.track('camera_capture_request', {
-      component: 'scanner',
-      error: blockedReason == null ? 'capture_requested' : 'capture_ignored',
-      metadata: buildScannerTelemetryMetadata({
-        capture_attempt_id: captureAttemptId,
-        capture_sequence: captureSequence,
-        capture_blocked_reason: blockedReason,
-      }),
-    });
+    if (telemetry) {
+      // Do not begin native capture until the user's shutter intent is on disk.
+      // If the process is force-closed during capture or delivery, the next SDK
+      // initialization recovers and sends this exact capture_attempt_id.
+      await telemetry.trackDurably('camera_capture_request', {
+        component: 'scanner',
+        error: blockedReason == null ? 'capture_requested' : 'capture_ignored',
+        metadata: buildScannerTelemetryMetadata({
+          capture_attempt_id: captureAttemptId,
+          capture_sequence: captureSequence,
+          capture_blocked_reason: blockedReason,
+        }),
+      });
+    }
 
     if (blockedReason && blockedReason !== 'camera_not_ready') return;
     if (blockedReason === 'camera_not_ready') {
@@ -1172,6 +1178,7 @@ export function VerifyAIScanner({
     let captureRetryTorchSuppressed = false;
     let captureRetrySettleDelayMs = CAMERA_CAPTURE_RETRY_DELAY_MS;
     let captureRetryRemountBackoffMs = 0;
+    let captureRetryReadyTimeoutMs = 0;
     let lastNativeCaptureErrorMessage: string | null = null;
 
     try {
@@ -1251,13 +1258,11 @@ export function VerifyAIScanner({
 
             if (attempt === 1 && isNativeCameraCaptureError(normalized) && !terminated) {
               captureRetryAttempted = true;
-              captureRetryTorchSuppressed = !!enableTorch;
-              captureRetrySettleDelayMs = captureRetryTorchSuppressed
-                ? CAMERA_CAPTURE_RETRY_TORCH_SETTLE_MS
-                : CAMERA_CAPTURE_RETRY_DELAY_MS;
-              captureRetryRemountBackoffMs = captureRetryTorchSuppressed
-                ? CAMERA_CAPTURE_RETRY_DELAY_MS
-                : 0;
+              const retryPlan = getCameraCaptureRetryPlan(Platform.OS, !!enableTorch);
+              captureRetryTorchSuppressed = retryPlan.suppressTorch;
+              captureRetrySettleDelayMs = retryPlan.settleDelayMs;
+              captureRetryRemountBackoffMs = retryPlan.remountBackoffMs;
+              captureRetryReadyTimeoutMs = retryPlan.readyTimeoutMs;
               const retryAt = new Date().toISOString();
               lastCaptureRetryAtRef.current = retryAt;
               cameraRemountCountRef.current++;
@@ -1271,9 +1276,6 @@ export function VerifyAIScanner({
                   : undefined,
               );
               await sleep(captureRetrySettleDelayMs);
-              const captureRetryReadyTimeoutMs = Platform.OS === 'android'
-                ? ANDROID_CAMERA_CAPTURE_RETRY_READY_TIMEOUT_MS
-                : IOS_CAMERA_CAPTURE_RETRY_READY_TIMEOUT_MS;
               captureRetryReady = await waitForCameraReady(captureRetryReadyTimeoutMs);
               telemetry?.track('camera_capture_retry', {
                 component: 'scanner',
@@ -1397,6 +1399,7 @@ export function VerifyAIScanner({
           capture_retry_torch_suppressed: captureRetryTorchSuppressed,
           capture_retry_settle_delay_ms: captureRetrySettleDelayMs,
           capture_retry_remount_backoff_ms: captureRetryRemountBackoffMs,
+          capture_retry_ready_timeout_ms: captureRetryReadyTimeoutMs,
           recovered_native_capture_failure: captureRetryAttempted ? 1 : 0,
           last_native_capture_error: lastNativeCaptureErrorMessage,
         }),
@@ -1479,6 +1482,7 @@ export function VerifyAIScanner({
               capture_retry_torch_suppressed: captureRetryTorchSuppressed,
               capture_retry_settle_delay_ms: captureRetrySettleDelayMs,
               capture_retry_remount_backoff_ms: captureRetryRemountBackoffMs,
+              capture_retry_ready_timeout_ms: captureRetryReadyTimeoutMs,
               is_native_camera_capture_error: isNativeCameraCaptureError(error),
               last_native_capture_error: lastNativeCaptureErrorMessage,
             }),

package/src/components/cameraCaptureRetry.ts

@@ -0,0 +1,37 @@
+export const CAMERA_CAPTURE_RETRY_DELAY_MS = 350;
+export const CAMERA_CAPTURE_RETRY_TORCH_SETTLE_MS = 800;
+export const IOS_CAMERA_CAPTURE_RETRY_READY_TIMEOUT_MS = 3000;
+export const ANDROID_CAMERA_CAPTURE_RETRY_READY_TIMEOUT_MS = 10000;
+
+export type CameraCaptureRetryPlatform = 'ios' | 'android' | string;
+
+export interface CameraCaptureRetryPlan {
+  readyTimeoutMs: number;
+  remountBackoffMs: number;
+  settleDelayMs: number;
+  suppressTorch: boolean;
+}
+
+export function getCameraCaptureRetryPlan(
+  platform: CameraCaptureRetryPlatform,
+  torchRequested: boolean,
+): CameraCaptureRetryPlan {
+  const suppressTorch = torchRequested;
+
+  return {
+    readyTimeoutMs: platform === 'android'
+      ? ANDROID_CAMERA_CAPTURE_RETRY_READY_TIMEOUT_MS
+      : IOS_CAMERA_CAPTURE_RETRY_READY_TIMEOUT_MS,
+    // Flutter fully restarts its CameraController after native capture errors.
+    // On iOS/Expo Camera, a key-only remount can report ready too quickly while
+    // the native capture session is still unable to produce a photo, so force a
+    // brief unmount before the retry.
+    remountBackoffMs: platform === 'ios' || suppressTorch
+      ? CAMERA_CAPTURE_RETRY_DELAY_MS
+      : 0,
+    settleDelayMs: suppressTorch
+      ? CAMERA_CAPTURE_RETRY_TORCH_SETTLE_MS
+      : CAMERA_CAPTURE_RETRY_DELAY_MS,
+    suppressTorch,
+  };
+}

package/src/telemetry/TelemetryReporter.ts

@@ -34,12 +34,20 @@ interface BufferedEvent {
   dedupKey: string;
 }
 
+interface TelemetryTrackOptions {
+  component?: string;
+  error?: unknown;
+  errorCode?: string;
+  metadata?: Record<string, string | number>;
+}
+
 /** Event types that flush immediately (critical init failures). */
 const CRITICAL_EVENTS = new Set([
   'camera_init_failure',
   'camera_preview_timeout',
   'camera_startup_slow',
   'camera_permission_denied',
+  'camera_capture_request',
   'camera_scanner_mounted',
   'camera_scanner_disposed',
   'camera_android_native_orientation_started',
@@ -55,6 +63,7 @@ const CRITICAL_EVENTS = new Set([
 
 export class TelemetryReporter {
   private buffer: Map<string, TelemetryEvent> = new Map();
+  private inFlightBuffer: Map<string, TelemetryEvent> = new Map();
   private flushTimer: ReturnType<typeof setTimeout> | null = null;
   private sessionId: string;
   private baseUrl: string;
@@ -63,6 +72,7 @@ export class TelemetryReporter {
   private flushing = false;
   private loadedPersisted = false;
   private loadPersistedPromise: Promise<void> | null = null;
+  private persistenceChain: Promise<void> = Promise.resolve();
 
   constructor(apiKey: string, baseUrl: string) {
     this.apiKey = apiKey;
@@ -94,75 +104,49 @@ export class TelemetryReporter {
   /** Track an error event. Fire-and-forget — never throws. */
   track(
     eventType: string,
-    opts: {
-      component?: string;
-      error?: unknown;
-      errorCode?: string;
-      metadata?: Record<string, string | number>;
-    } = {},
+    opts: TelemetryTrackOptions = {},
   ): void {
     if (this.disposed) return;
 
     try {
-      const now = new Date().toISOString();
-      const errorObj = opts.error instanceof Error ? opts.error : null;
-      const errorMessage = errorObj?.message
-        ?? (typeof opts.error === 'string' ? opts.error : undefined);
-
-      const dedupKey = `${eventType}|${errorMessage ?? ''}|${opts.component ?? ''}`;
-
-      const existing = this.buffer.get(dedupKey);
-      if (existing) {
-        existing.event_count++;
-        existing.last_occurred_at = now;
-        // If the new occurrence is critical, flush immediately
-        if (CRITICAL_EVENTS.has(eventType)) {
-          this.flushNow();
-        }
-        return;
-      }
-
-      const event: TelemetryEvent = {
-        event_type: eventType,
-        component: opts.component,
-        error_message: errorMessage?.slice(0, 1000),
-        error_stack: errorObj?.stack?.slice(0, 2000),
-        error_code: opts.errorCode,
-        metadata: opts.metadata,
-        sdk_platform: Platform.OS,
-        sdk_version: SDK_VERSION,
-        os_name: Platform.OS,
-        os_version: String(Platform.Version),
-        session_id: this.sessionId,
-        event_count: 1,
-        first_occurred_at: now,
-        last_occurred_at: now,
-      };
-
-      this.buffer.set(dedupKey, event);
+      this.recordEvent(eventType, opts);
 
       if (CRITICAL_EVENTS.has(eventType)) {
-        this.flushNow();
+        // Critical events are written locally before delivery starts. This keeps
+        // them recoverable if the process is killed while the POST is in flight.
+        void this.persistAfterRecovery().then(() => this.flushNow());
       } else {
         this.scheduleFlush();
-      }
-
-      // Persist immediately once prior-session recovery has completed. If startup
-      // recovery is still in flight, write the merged buffer back afterwards.
-      if (this.loadedPersisted) {
-        this.persistBuffer();
-      } else {
-        void this.loadPersistedBuffer().then(() => {
-          if (!this.disposed && this.buffer.size > 0) {
-            this.persistBuffer();
-          }
-        });
+        void this.persistAfterRecovery();
       }
     } catch {
       // Never throw from telemetry
     }
   }
 
+  /**
+   * Record an event and wait until it is durably stored before returning.
+   *
+   * Use this for user intent that must survive an immediate force-close. Network
+   * delivery starts after the local write, but callers do not wait on the network.
+   */
+  async trackDurably(
+    eventType: string,
+    opts: TelemetryTrackOptions = {},
+  ): Promise<void> {
+    if (this.disposed) return;
+
+    try {
+      await this.loadPersistedBuffer();
+      if (this.disposed) return;
+      this.recordEvent(eventType, opts);
+      await this.persistBufferAsync();
+      this.flushNow();
+    } catch {
+      // Never throw from telemetry or block the host capture flow.
+    }
+  }
+
   /** Flush all buffered events immediately. Returns a promise but never rejects. */
   async flush(): Promise<void> {
     // Merge any persisted events from a previous session before flushing
@@ -174,6 +158,7 @@ export class TelemetryReporter {
     const bufferedEntries = Array.from(this.buffer.entries());
     const events = bufferedEntries.map(([, event]) => event);
     this.buffer.clear();
+    this.inFlightBuffer = new Map(bufferedEntries);
     this.clearFlushTimer();
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), 10000);
@@ -202,8 +187,10 @@ export class TelemetryReporter {
         throw new Error(`Telemetry request failed with status ${response.status}`);
       }
 
-      // Success — clear persisted buffer since events are now server-side
-      this.persistBuffer(); // buffer is empty at this point, so this clears the key
+      this.inFlightBuffer.clear();
+      // Success — persist the current buffer. Usually empty, but it may contain
+      // events recorded while this request was in flight.
+      await this.persistBufferAsync();
     } catch (error) {
       if (!loggedDeliveryFailure) {
         const kind = error instanceof Error ? error.name : typeof error;
@@ -224,6 +211,7 @@ export class TelemetryReporter {
           this.buffer.set(dedupKey, event);
         }
       }
+      this.inFlightBuffer.clear();
     } finally {
       clearTimeout(timeout);
       this.flushing = false;
@@ -260,6 +248,45 @@ export class TelemetryReporter {
     }
   }
 
+  private recordEvent(eventType: string, opts: TelemetryTrackOptions): void {
+    const now = new Date().toISOString();
+    const errorObj = opts.error instanceof Error ? opts.error : null;
+    const errorMessage = errorObj?.message
+      ?? (typeof opts.error === 'string' ? opts.error : undefined);
+    const occurrenceId = opts.metadata?.capture_attempt_id;
+    const dedupKey = `${eventType}|${errorMessage ?? ''}|${opts.component ?? ''}|${occurrenceId ?? ''}`;
+
+    const existing = this.buffer.get(dedupKey);
+    if (existing) {
+      existing.event_count++;
+      existing.last_occurred_at = now;
+      if (opts.metadata) existing.metadata = opts.metadata;
+      return;
+    }
+
+    this.buffer.set(dedupKey, {
+      event_type: eventType,
+      component: opts.component,
+      error_message: errorMessage?.slice(0, 1000),
+      error_stack: errorObj?.stack?.slice(0, 2000),
+      error_code: opts.errorCode,
+      metadata: opts.metadata,
+      sdk_platform: Platform.OS,
+      sdk_version: SDK_VERSION,
+      os_name: Platform.OS,
+      os_version: String(Platform.Version),
+      session_id: this.sessionId,
+      event_count: 1,
+      first_occurred_at: now,
+      last_occurred_at: now,
+    });
+  }
+
+  private async persistAfterRecovery(): Promise<void> {
+    await this.loadPersistedBuffer();
+    await this.persistBufferAsync();
+  }
+
   /**
    * Persist the current buffer to AsyncStorage so events survive abrupt app exits.
    * Fire-and-forget — never throws or blocks.
@@ -268,21 +295,38 @@ export class TelemetryReporter {
    * to avoid overwriting orphaned events from a previous session before recovery.
    */
   private persistBuffer(): void {
-    if (!this.loadedPersisted) return; // Don't overwrite orphaned prior-session data before it's loaded
+    void this.persistBufferAsync();
+  }
+
+  private persistBufferAsync(): Promise<void> {
+    if (!this.loadedPersisted) return Promise.resolve();
+
     try {
       const entries: Record<string, TelemetryEvent> = {};
+      for (const [key, event] of this.inFlightBuffer) {
+        entries[key] = event;
+      }
       for (const [key, event] of this.buffer) {
         entries[key] = event;
       }
-      getStorage().then(s => {
-        if (Object.keys(entries).length > 0) {
-          s.setItem(TELEMETRY_PERSIST_KEY, JSON.stringify(entries));
-        } else {
-          s.removeItem(TELEMETRY_PERSIST_KEY);
-        }
-      }).catch(() => { /* never throw from telemetry */ });
+
+      // Serialize writes so an older fire-and-forget snapshot cannot overwrite a
+      // newer durable capture marker or resurrect an acknowledged event.
+      this.persistenceChain = this.persistenceChain
+        .catch(() => { /* keep the write queue alive */ })
+        .then(async () => {
+          const storage = await getStorage();
+          if (Object.keys(entries).length > 0) {
+            await storage.setItem(TELEMETRY_PERSIST_KEY, JSON.stringify(entries));
+          } else {
+            await storage.removeItem(TELEMETRY_PERSIST_KEY);
+          }
+        })
+        .catch(() => { /* never throw from telemetry */ });
+      return this.persistenceChain;
     } catch {
       // Never throw from telemetry
+      return Promise.resolve();
     }
   }
 

package/src/types/index.ts

@@ -37,6 +37,8 @@ export interface VerificationResult {
   policy: string;
   violation_reasons: string[];
   feedback: string;
+  warning_violation_reasons?: string[];
+  warning_feedback?: string | null;
   metadata: Record<string, unknown>;
   image_url: string | null;
   /** Base64-encoded image data URI. Only present when `include_image_data` is requested. */
@@ -96,6 +98,8 @@ export interface ScannerTelemetryContext {
   routeName?: string;
   /** Whether the host app keeps this screen portrait-locked. */
   isPortraitLocked?: boolean;
+  /** Host-owned identifier used to correlate scanner telemetry with its workflow. */
+  hostReferenceId?: string;
 }
 
 /**

package/src/version.ts

@@ -1 +1 @@
-export const SDK_VERSION = '2.5.2';
+export const SDK_VERSION = '2.5.5';