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

package/lib/components/VerifyAIScanner.js

@@ -272,6 +272,7 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
     const overlayRotationDeg = getOverlayRotationDeg(physicalOrientation);
     const scannerSessionIdRef = useRef(createScannerSessionId());
     const captureSequenceRef = useRef(0);
+    const captureIntentPendingRef = useRef(false);
     const torchRetrySuppressedRef = useRef(false);
     const [torchRetrySuppressed, setTorchRetrySuppressed] = useState(false);
     const buildScannerTelemetryMetadata = useCallback((extra = {}) => compactTelemetryMetadata({
@@ -351,6 +352,7 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
         policy,
         status,
         telemetryContext?.isPortraitLocked,
+        telemetryContext?.hostReferenceId,
         telemetryContext?.routeName,
         terminated,
         windowHeight,
@@ -438,6 +440,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,
             android_native_orientation_subscription_active: 0,
             android_native_orientation_event_count: 0,
             android_native_orientation_change_count: 0,
@@ -616,7 +619,13 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                 trackAndroidOrientationEvent('camera_android_accelerometer_stopped', 'android_accelerometer_tracking_stopped', { accelerometer_stop_reason: 'orientation_tracking_stopped' });
             }
         };
-    }, [policy, telemetry, telemetryContext?.isPortraitLocked, telemetryContext?.routeName]);
+    }, [
+        policy,
+        telemetry,
+        telemetryContext?.hostReferenceId,
+        telemetryContext?.isPortraitLocked,
+        telemetryContext?.routeName,
+    ]);
     // Detect orientation changes and remount camera after rotation settles.
     // On iOS, AVCaptureVideoPreviewLayer distorts if remounted during the rotation
     // animation — the native preview layer initializes with transitional bounds.
@@ -902,24 +911,28 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
         const captureSequence = captureSequenceRef.current + 1;
         captureSequenceRef.current = captureSequence;
         const captureAttemptId = `${scannerSessionIdRef.current}_cap_${captureSequence}`;
-        const blockedReason = !cameraRef.current
-            ? 'camera_ref_null'
-            : !cameraReadyRef.current
-                ? 'camera_not_ready'
-                : status === 'capturing'
-                    ? 'already_capturing'
-                    : status === 'processing'
-                        ? 'already_processing'
-                        : terminated
-                            ? 'terminated'
-                            : exhausted
-                                ? 'exhausted'
-                                : null;
+        const blockedReason = captureIntentPendingRef.current
+            ? 'capture_intent_pending'
+            : !cameraRef.current
+                ? 'camera_ref_null'
+                : !cameraReadyRef.current
+                    ? 'camera_not_ready'
+                    : status === 'capturing'
+                        ? 'already_capturing'
+                        : status === 'processing'
+                            ? 'already_processing'
+                            : terminated
+                                ? 'terminated'
+                                : exhausted
+                                    ? 'exhausted'
+                                    : null;
+        if (blockedReason == null)
+            captureIntentPendingRef.current = true;
         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', {
+            const persisted = await telemetry.trackDurably('camera_capture_request', {
                 component: 'scanner',
                 error: blockedReason == null ? 'capture_requested' : 'capture_ignored',
                 metadata: buildScannerTelemetryMetadata({
@@ -928,6 +941,16 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                     capture_blocked_reason: blockedReason,
                 }),
             });
+            if (!persisted) {
+                telemetry.track('telemetry_persist_failure', {
+                    component: 'scanner',
+                    error: 'capture_intent_persist_failed',
+                    metadata: buildScannerTelemetryMetadata({
+                        capture_attempt_id: captureAttemptId,
+                        capture_sequence: captureSequence,
+                    }),
+                });
+            }
         }
         if (blockedReason && blockedReason !== 'camera_not_ready')
             return;
@@ -1229,6 +1252,7 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
             }
         }
         finally {
+            captureIntentPendingRef.current = false;
             setTorchSuppressedForRetry(false);
         }
     }, [status, exhausted, onCapture, onError, overlay?.maxAttempts, overlay?.autoApproveOnExhaust, releaseCamera, scheduleTerminalResult, buildScannerTelemetryMetadata, requestCameraRemount, telemetry, terminated, physicalOrientation, overlayRotationDeg, enableTorch, setTorchSuppressedForRetry]);

package/lib/telemetry/TelemetryReporter.d.ts

@@ -7,15 +7,18 @@ interface TelemetryTrackOptions {
 export declare class TelemetryReporter {
     private buffer;
     private inFlightBuffer;
+    private dedupIndex;
     private flushTimer;
     private sessionId;
     private baseUrl;
     private apiKey;
+    private storagePrefix;
     private disposed;
     private flushing;
     private loadedPersisted;
     private loadPersistedPromise;
     private persistenceChain;
+    private eventSequence;
     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. */
@@ -31,7 +34,7 @@ export declare class TelemetryReporter {
      * 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>;
+    trackDurably(eventType: string, opts?: TelemetryTrackOptions): Promise<boolean>;
     /** Flush all buffered events immediately. Returns a promise but never rejects. */
     flush(): Promise<void>;
     /** Dispose — flush remaining events and stop timers. */
@@ -41,15 +44,10 @@ export declare class TelemetryReporter {
     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.
-     *
-     * IMPORTANT: skips persist if loadPersistedBuffer() hasn't completed yet,
-     * to avoid overwriting orphaned events from a previous session before recovery.
-     */
-    private persistBuffer;
+    private createJournalKey;
     private persistBufferAsync;
+    private removeJournalEntries;
+    private releaseClaims;
     /**
      * Load persisted events from a previous session and merge into current buffer.
      * Runs once per instance. If orphaned events are found, emits an

package/lib/telemetry/TelemetryReporter.js

@@ -8,7 +8,22 @@ async function getStorage() {
     }
     return _storage;
 }
-const TELEMETRY_PERSIST_KEY = '@verifyai/telemetry_buffer';
+const LEGACY_TELEMETRY_PERSIST_KEY = '@verifyai/telemetry_buffer';
+const TELEMETRY_EVENT_KEY_PREFIX = '@verifyai/telemetry_event/';
+const MAX_EVENTS_PER_REQUEST = 25;
+// Per-event journal keys avoid shared full-buffer replacement. Claims prevent
+// two reporters in the same process from recovering/sending the same event.
+const claimedEventKeys = new Set();
+let legacyBufferClaimed = false;
+function telemetryTargetId(apiKey, baseUrl) {
+    let hash = 2166136261;
+    const input = `${baseUrl}|${apiKey}`;
+    for (let index = 0; index < input.length; index++) {
+        hash ^= input.charCodeAt(index);
+        hash = Math.imul(hash, 16777619);
+    }
+    return (hash >>> 0).toString(36);
+}
 /** Event types that flush immediately (critical init failures). */
 const CRITICAL_EVENTS = new Set([
     'camera_init_failure',
@@ -16,6 +31,7 @@ const CRITICAL_EVENTS = new Set([
     'camera_startup_slow',
     'camera_permission_denied',
     'camera_capture_request',
+    'telemetry_persist_failure',
     'camera_scanner_mounted',
     'camera_scanner_disposed',
     'camera_android_native_orientation_started',
@@ -32,14 +48,17 @@ export class TelemetryReporter {
     constructor(apiKey, baseUrl) {
         this.buffer = new Map();
         this.inFlightBuffer = new Map();
+        this.dedupIndex = new Map();
         this.flushTimer = null;
         this.disposed = false;
         this.flushing = false;
         this.loadedPersisted = false;
         this.loadPersistedPromise = null;
         this.persistenceChain = Promise.resolve();
+        this.eventSequence = 0;
         this.apiKey = apiKey;
         this.baseUrl = baseUrl.replace(/\/$/, '');
+        this.storagePrefix = `${TELEMETRY_EVENT_KEY_PREFIX}${telemetryTargetId(apiKey, this.baseUrl)}/`;
         this.sessionId = Math.random().toString(36).slice(2) + Date.now().toString(36);
         // Load any persisted events left behind by a previous session
         this.loadPersistedBuffer();
@@ -86,17 +105,19 @@ export class TelemetryReporter {
      */
     async trackDurably(eventType, opts = {}) {
         if (this.disposed)
-            return;
+            return false;
         try {
             await this.loadPersistedBuffer();
             if (this.disposed)
-                return;
+                return false;
             this.recordEvent(eventType, opts);
-            await this.persistBufferAsync();
+            const persisted = await this.persistBufferAsync();
             this.flushNow();
+            return persisted;
         }
         catch {
             // Never throw from telemetry or block the host capture flow.
+            return false;
         }
     }
     /** Flush all buffered events immediately. Returns a promise but never rejects. */
@@ -106,14 +127,16 @@ export class TelemetryReporter {
         if (this.buffer.size === 0 || this.flushing)
             return;
         this.flushing = true;
-        const bufferedEntries = Array.from(this.buffer.entries());
+        const bufferedEntries = Array.from(this.buffer.entries()).slice(0, MAX_EVENTS_PER_REQUEST);
         const events = bufferedEntries.map(([, event]) => event);
-        this.buffer.clear();
+        for (const [key] of bufferedEntries)
+            this.buffer.delete(key);
         this.inFlightBuffer = new Map(bufferedEntries);
         this.clearFlushTimer();
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), 10000);
         let loggedDeliveryFailure = false;
+        let delivered = false;
         try {
             const response = await fetch(`${this.baseUrl}/telemetry`, {
                 method: 'POST',
@@ -136,10 +159,19 @@ export class TelemetryReporter {
                 loggedDeliveryFailure = true;
                 throw new Error(`Telemetry request failed with status ${response.status}`);
             }
+            const acknowledgedKeys = bufferedEntries.map(([key]) => key);
+            const acknowledgedKeySet = new Set(acknowledgedKeys);
+            const removed = await this.removeJournalEntries(acknowledgedKeys);
+            if (removed) {
+                for (const key of acknowledgedKeys)
+                    claimedEventKeys.delete(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();
+            for (const [dedupKey, journalKey] of this.dedupIndex) {
+                if (acknowledgedKeySet.has(journalKey))
+                    this.dedupIndex.delete(dedupKey);
+            }
+            delivered = true;
         }
         catch (error) {
             if (!loggedDeliveryFailure) {
@@ -171,12 +203,17 @@ export class TelemetryReporter {
                 this.scheduleFlush();
             }
         }
+        // Drain oversized recovered journals in API-sized chunks. A failed chunk is
+        // rebuffered and left for the normal retry timer instead of spinning.
+        if (delivered && this.buffer.size > 0 && !this.disposed) {
+            await this.flush();
+        }
     }
     /** Dispose — flush remaining events and stop timers. */
     dispose() {
         this.disposed = true;
         this.clearFlushTimer();
-        this.flush();
+        void this.flush().finally(() => this.releaseClaims());
     }
     scheduleFlush() {
         if (this.flushTimer)
@@ -203,21 +240,31 @@ export class TelemetryReporter {
             ?? (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);
+        const existingJournalKey = this.dedupIndex.get(dedupKey);
+        const existing = existingJournalKey
+            ? this.buffer.get(existingJournalKey)
+            : undefined;
         if (existing) {
             existing.event_count++;
             existing.last_occurred_at = now;
             if (opts.metadata)
-                existing.metadata = opts.metadata;
+                existing.metadata = { ...existing.metadata, ...opts.metadata };
             return;
         }
-        this.buffer.set(dedupKey, {
+        const journalKey = this.createJournalKey();
+        this.dedupIndex.set(dedupKey, journalKey);
+        claimedEventKeys.add(journalKey);
+        const eventMetadata = {
+            ...opts.metadata,
+            telemetry_event_id: journalKey.slice(this.storagePrefix.length),
+        };
+        this.buffer.set(journalKey, {
             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,
+            metadata: eventMetadata,
             sdk_platform: Platform.OS,
             sdk_version: SDK_VERSION,
             os_name: Platform.OS,
@@ -232,48 +279,59 @@ export class TelemetryReporter {
         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.
-     *
-     * IMPORTANT: skips persist if loadPersistedBuffer() hasn't completed yet,
-     * to avoid overwriting orphaned events from a previous session before recovery.
-     */
-    persistBuffer() {
-        void this.persistBufferAsync();
+    createJournalKey() {
+        this.eventSequence++;
+        return `${this.storagePrefix}${this.sessionId}:${this.eventSequence.toString(36)}`;
     }
-    persistBufferAsync() {
+    async persistBufferAsync() {
         if (!this.loadedPersisted)
-            return Promise.resolve();
+            return Promise.resolve(false);
         try {
-            const entries = {};
-            for (const [key, event] of this.inFlightBuffer) {
-                entries[key] = event;
-            }
-            for (const [key, event] of this.buffer) {
-                entries[key] = event;
-            }
-            // 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
+            const entries = [
+                ...this.inFlightBuffer.entries(),
+                ...this.buffer.entries(),
+            ];
+            const operation = this.persistenceChain
                 .catch(() => { })
                 .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);
+                if (entries.length > 0) {
+                    await storage.multiSet(entries.map(([key, event]) => [key, JSON.stringify(event)]));
                 }
-            })
-                .catch(() => { });
-            return this.persistenceChain;
+            });
+            this.persistenceChain = operation.catch(() => { });
+            await operation;
+            return true;
         }
         catch {
             // Never throw from telemetry
-            return Promise.resolve();
+            return false;
         }
     }
+    async removeJournalEntries(keys) {
+        if (keys.length === 0)
+            return true;
+        try {
+            const operation = this.persistenceChain
+                .catch(() => { })
+                .then(async () => {
+                const storage = await getStorage();
+                await storage.multiRemove(keys);
+            });
+            this.persistenceChain = operation.catch(() => { });
+            await operation;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    releaseClaims() {
+        for (const key of this.buffer.keys())
+            claimedEventKeys.delete(key);
+        for (const key of this.inFlightBuffer.keys())
+            claimedEventKeys.delete(key);
+    }
     /**
      * Load persisted events from a previous session and merge into current buffer.
      * Runs once per instance. If orphaned events are found, emits an
@@ -288,65 +346,89 @@ export class TelemetryReporter {
             return;
         }
         this.loadPersistedPromise = (async () => {
+            const claimedDuringRecovery = [];
             try {
                 const storage = await getStorage();
-                const raw = await storage.getItem(TELEMETRY_PERSIST_KEY);
-                if (!raw)
-                    return;
-                const entries = JSON.parse(raw);
                 let orphanedCount = 0;
                 const orphanedTypes = [];
-                for (const [key, event] of Object.entries(entries)) {
-                    if (event.session_id === this.sessionId)
-                        continue; // Same session, skip
-                    orphanedCount++;
-                    orphanedTypes.push(event.event_type);
-                    // Merge orphaned events into the current buffer
-                    const existing = this.buffer.get(key);
-                    if (existing) {
-                        existing.event_count += event.event_count;
-                        if (event.first_occurred_at < existing.first_occurred_at) {
-                            existing.first_occurred_at = event.first_occurred_at;
-                        }
-                        if (event.last_occurred_at > existing.last_occurred_at) {
-                            existing.last_occurred_at = event.last_occurred_at;
-                        }
+                const allKeys = await storage.getAllKeys();
+                const recoverableKeys = allKeys.filter((key) => {
+                    if (!key.startsWith(this.storagePrefix))
+                        return false;
+                    if (claimedEventKeys.has(key))
+                        return false;
+                    claimedEventKeys.add(key);
+                    claimedDuringRecovery.push(key);
+                    return true;
+                });
+                const recoveredPairs = recoverableKeys.length > 0
+                    ? await storage.multiGet(recoverableKeys)
+                    : [];
+                for (const [key, raw] of recoveredPairs) {
+                    if (!raw) {
+                        claimedEventKeys.delete(key);
+                        continue;
                     }
-                    else {
+                    try {
+                        const event = JSON.parse(raw);
+                        orphanedCount++;
+                        orphanedTypes.push(event.event_type);
                         this.buffer.set(key, event);
                     }
+                    catch {
+                        claimedEventKeys.delete(key);
+                    }
+                }
+                // Migrate the pre-2.5.6 shared snapshot without a remove/rewrite gap:
+                // write each event journal entry first, then delete the legacy key.
+                if (!legacyBufferClaimed && allKeys.includes(LEGACY_TELEMETRY_PERSIST_KEY)) {
+                    legacyBufferClaimed = true;
+                    let migrated = false;
+                    try {
+                        const legacyRaw = await storage.getItem(LEGACY_TELEMETRY_PERSIST_KEY);
+                        if (legacyRaw) {
+                            const legacyEntries = JSON.parse(legacyRaw);
+                            const migrationPairs = [];
+                            for (const event of Object.values(legacyEntries)) {
+                                const key = this.createJournalKey();
+                                claimedEventKeys.add(key);
+                                this.buffer.set(key, event);
+                                orphanedCount++;
+                                orphanedTypes.push(event.event_type);
+                                migrationPairs.push([key, JSON.stringify(event)]);
+                            }
+                            if (migrationPairs.length > 0)
+                                await storage.multiSet(migrationPairs);
+                        }
+                        await storage.removeItem(LEGACY_TELEMETRY_PERSIST_KEY);
+                        migrated = true;
+                    }
+                    finally {
+                        if (!migrated)
+                            legacyBufferClaimed = false;
+                    }
                 }
                 // Emit sdk_session_recovered if we recovered orphaned events from a previous session
                 if (orphanedCount > 0) {
-                    const now = new Date().toISOString();
                     const uniqueTypes = [...new Set(orphanedTypes)];
-                    const crashEvent = {
-                        event_type: 'sdk_session_recovered',
+                    this.recordEvent('sdk_session_recovered', {
                         component: 'TelemetryReporter',
-                        error_message: `Recovered ${orphanedCount} unflushed event(s) from a previous session that ended without a clean telemetry flush: ${uniqueTypes.join(', ')}`,
-                        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(`sdk_session_recovered|recovered|${this.sessionId}`, crashEvent);
+                        error: `Recovered ${orphanedCount} unflushed event(s) from a previous session that ended without a clean telemetry flush: ${uniqueTypes.join(', ')}`,
+                    });
                 }
-                // Clear persisted data now that it's loaded into memory. The merged
-                // buffer will be re-persisted below until a flush succeeds.
-                await storage.removeItem(TELEMETRY_PERSIST_KEY);
             }
             catch {
                 // Never throw from telemetry
+                for (const key of claimedDuringRecovery) {
+                    if (!this.buffer.has(key))
+                        claimedEventKeys.delete(key);
+                }
             }
             finally {
                 this.loadedPersisted = true;
                 this.loadPersistedPromise = null;
                 if (this.buffer.size > 0 && !this.disposed) {
-                    this.persistBuffer();
+                    await this.persistBufferAsync();
                     this.scheduleFlush();
                 }
             }

package/lib/version.d.ts

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

package/lib/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@switchlabs/verify-ai-react-native",
-  "version": "2.5.5",
+  "version": "2.5.6",
   "description": "React Native SDK for Verify AI - photo verification with AI vision processing",
   "repository": {
     "type": "git",

package/src/components/VerifyAIScanner.tsx

@@ -384,6 +384,7 @@ export function VerifyAIScanner({
   const overlayRotationDeg = getOverlayRotationDeg(physicalOrientation);
   const scannerSessionIdRef = useRef(createScannerSessionId());
   const captureSequenceRef = useRef(0);
+  const captureIntentPendingRef = useRef(false);
   const torchRetrySuppressedRef = useRef(false);
   const [torchRetrySuppressed, setTorchRetrySuppressed] = useState(false);
 
@@ -466,6 +467,7 @@ export function VerifyAIScanner({
     policy,
     status,
     telemetryContext?.isPortraitLocked,
+    telemetryContext?.hostReferenceId,
     telemetryContext?.routeName,
     terminated,
     windowHeight,
@@ -579,6 +581,7 @@ export function VerifyAIScanner({
       device_os_version: String(Platform.Version),
       route_name: telemetryContext?.routeName,
       is_portrait_locked: telemetryContext?.isPortraitLocked,
+      host_reference_id: telemetryContext?.hostReferenceId,
       android_native_orientation_subscription_active: 0,
       android_native_orientation_event_count: 0,
       android_native_orientation_change_count: 0,
@@ -787,7 +790,13 @@ export function VerifyAIScanner({
         );
       }
     };
-  }, [policy, telemetry, telemetryContext?.isPortraitLocked, telemetryContext?.routeName]);
+  }, [
+    policy,
+    telemetry,
+    telemetryContext?.hostReferenceId,
+    telemetryContext?.isPortraitLocked,
+    telemetryContext?.routeName,
+  ]);
 
   // Detect orientation changes and remount camera after rotation settles.
   // On iOS, AVCaptureVideoPreviewLayer distorts if remounted during the rotation
@@ -1112,7 +1121,9 @@ export function VerifyAIScanner({
     captureSequenceRef.current = captureSequence;
     const captureAttemptId = `${scannerSessionIdRef.current}_cap_${captureSequence}`;
     const blockedReason =
-      !cameraRef.current
+      captureIntentPendingRef.current
+        ? 'capture_intent_pending'
+        : !cameraRef.current
         ? 'camera_ref_null'
         : !cameraReadyRef.current
           ? 'camera_not_ready'
@@ -1126,11 +1137,13 @@ export function VerifyAIScanner({
                   ? 'exhausted'
                   : null;
 
+    if (blockedReason == null) captureIntentPendingRef.current = true;
+
     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', {
+      const persisted = await telemetry.trackDurably('camera_capture_request', {
         component: 'scanner',
         error: blockedReason == null ? 'capture_requested' : 'capture_ignored',
         metadata: buildScannerTelemetryMetadata({
@@ -1139,6 +1152,16 @@ export function VerifyAIScanner({
           capture_blocked_reason: blockedReason,
         }),
       });
+      if (!persisted) {
+        telemetry.track('telemetry_persist_failure', {
+          component: 'scanner',
+          error: 'capture_intent_persist_failed',
+          metadata: buildScannerTelemetryMetadata({
+            capture_attempt_id: captureAttemptId,
+            capture_sequence: captureSequence,
+          }),
+        });
+      }
     }
 
     if (blockedReason && blockedReason !== 'camera_not_ready') return;
@@ -1494,6 +1517,7 @@ export function VerifyAIScanner({
         setTimeout(() => setStatus('idle'), TRANSIENT_ERROR_DISPLAY_MS);
       }
     } finally {
+      captureIntentPendingRef.current = false;
       setTorchSuppressedForRetry(false);
     }
   }, [status, exhausted, onCapture, onError, overlay?.maxAttempts, overlay?.autoApproveOnExhaust, releaseCamera, scheduleTerminalResult, buildScannerTelemetryMetadata, requestCameraRemount, telemetry, terminated, physicalOrientation, overlayRotationDeg, enableTorch, setTorchSuppressedForRetry]);

package/src/telemetry/TelemetryReporter.ts

@@ -10,7 +10,24 @@ async function getStorage() {
   return _storage;
 }
 
-const TELEMETRY_PERSIST_KEY = '@verifyai/telemetry_buffer';
+const LEGACY_TELEMETRY_PERSIST_KEY = '@verifyai/telemetry_buffer';
+const TELEMETRY_EVENT_KEY_PREFIX = '@verifyai/telemetry_event/';
+const MAX_EVENTS_PER_REQUEST = 25;
+
+// Per-event journal keys avoid shared full-buffer replacement. Claims prevent
+// two reporters in the same process from recovering/sending the same event.
+const claimedEventKeys = new Set<string>();
+let legacyBufferClaimed = false;
+
+function telemetryTargetId(apiKey: string, baseUrl: string): string {
+  let hash = 2166136261;
+  const input = `${baseUrl}|${apiKey}`;
+  for (let index = 0; index < input.length; index++) {
+    hash ^= input.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(36);
+}
 
 interface TelemetryEvent {
   event_type: string;
@@ -29,11 +46,6 @@ interface TelemetryEvent {
   last_occurred_at: string;
 }
 
-interface BufferedEvent {
-  event: TelemetryEvent;
-  dedupKey: string;
-}
-
 interface TelemetryTrackOptions {
   component?: string;
   error?: unknown;
@@ -48,6 +60,7 @@ const CRITICAL_EVENTS = new Set([
   'camera_startup_slow',
   'camera_permission_denied',
   'camera_capture_request',
+  'telemetry_persist_failure',
   'camera_scanner_mounted',
   'camera_scanner_disposed',
   'camera_android_native_orientation_started',
@@ -64,19 +77,23 @@ const CRITICAL_EVENTS = new Set([
 export class TelemetryReporter {
   private buffer: Map<string, TelemetryEvent> = new Map();
   private inFlightBuffer: Map<string, TelemetryEvent> = new Map();
+  private dedupIndex: Map<string, string> = new Map();
   private flushTimer: ReturnType<typeof setTimeout> | null = null;
   private sessionId: string;
   private baseUrl: string;
   private apiKey: string;
+  private storagePrefix: string;
   private disposed = false;
   private flushing = false;
   private loadedPersisted = false;
   private loadPersistedPromise: Promise<void> | null = null;
   private persistenceChain: Promise<void> = Promise.resolve();
+  private eventSequence = 0;
 
   constructor(apiKey: string, baseUrl: string) {
     this.apiKey = apiKey;
     this.baseUrl = baseUrl.replace(/\/$/, '');
+    this.storagePrefix = `${TELEMETRY_EVENT_KEY_PREFIX}${telemetryTargetId(apiKey, this.baseUrl)}/`;
     this.sessionId = Math.random().toString(36).slice(2) + Date.now().toString(36);
     // Load any persisted events left behind by a previous session
     this.loadPersistedBuffer();
@@ -133,17 +150,19 @@ export class TelemetryReporter {
   async trackDurably(
     eventType: string,
     opts: TelemetryTrackOptions = {},
-  ): Promise<void> {
-    if (this.disposed) return;
+  ): Promise<boolean> {
+    if (this.disposed) return false;
 
     try {
       await this.loadPersistedBuffer();
-      if (this.disposed) return;
+      if (this.disposed) return false;
       this.recordEvent(eventType, opts);
-      await this.persistBufferAsync();
+      const persisted = await this.persistBufferAsync();
       this.flushNow();
+      return persisted;
     } catch {
       // Never throw from telemetry or block the host capture flow.
+      return false;
     }
   }
 
@@ -155,15 +174,16 @@ export class TelemetryReporter {
     if (this.buffer.size === 0 || this.flushing) return;
 
     this.flushing = true;
-    const bufferedEntries = Array.from(this.buffer.entries());
+    const bufferedEntries = Array.from(this.buffer.entries()).slice(0, MAX_EVENTS_PER_REQUEST);
     const events = bufferedEntries.map(([, event]) => event);
-    this.buffer.clear();
+    for (const [key] of bufferedEntries) this.buffer.delete(key);
     this.inFlightBuffer = new Map(bufferedEntries);
     this.clearFlushTimer();
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), 10000);
 
     let loggedDeliveryFailure = false;
+    let delivered = false;
     try {
       const response = await fetch(`${this.baseUrl}/telemetry`, {
         method: 'POST',
@@ -187,10 +207,17 @@ export class TelemetryReporter {
         throw new Error(`Telemetry request failed with status ${response.status}`);
       }
 
+      const acknowledgedKeys = bufferedEntries.map(([key]) => key);
+      const acknowledgedKeySet = new Set(acknowledgedKeys);
+      const removed = await this.removeJournalEntries(acknowledgedKeys);
+      if (removed) {
+        for (const key of acknowledgedKeys) claimedEventKeys.delete(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();
+      for (const [dedupKey, journalKey] of this.dedupIndex) {
+        if (acknowledgedKeySet.has(journalKey)) this.dedupIndex.delete(dedupKey);
+      }
+      delivered = true;
     } catch (error) {
       if (!loggedDeliveryFailure) {
         const kind = error instanceof Error ? error.name : typeof error;
@@ -219,13 +246,19 @@ export class TelemetryReporter {
         this.scheduleFlush();
       }
     }
+
+    // Drain oversized recovered journals in API-sized chunks. A failed chunk is
+    // rebuffered and left for the normal retry timer instead of spinning.
+    if (delivered && this.buffer.size > 0 && !this.disposed) {
+      await this.flush();
+    }
   }
 
   /** Dispose — flush remaining events and stop timers. */
   dispose(): void {
     this.disposed = true;
     this.clearFlushTimer();
-    this.flush();
+    void this.flush().finally(() => this.releaseClaims());
   }
 
   private scheduleFlush(): void {
@@ -256,21 +289,31 @@ export class TelemetryReporter {
     const occurrenceId = opts.metadata?.capture_attempt_id;
     const dedupKey = `${eventType}|${errorMessage ?? ''}|${opts.component ?? ''}|${occurrenceId ?? ''}`;
 
-    const existing = this.buffer.get(dedupKey);
+    const existingJournalKey = this.dedupIndex.get(dedupKey);
+    const existing = existingJournalKey
+      ? this.buffer.get(existingJournalKey)
+      : undefined;
     if (existing) {
       existing.event_count++;
       existing.last_occurred_at = now;
-      if (opts.metadata) existing.metadata = opts.metadata;
+      if (opts.metadata) existing.metadata = { ...existing.metadata, ...opts.metadata };
       return;
     }
 
-    this.buffer.set(dedupKey, {
+    const journalKey = this.createJournalKey();
+    this.dedupIndex.set(dedupKey, journalKey);
+    claimedEventKeys.add(journalKey);
+    const eventMetadata = {
+      ...opts.metadata,
+      telemetry_event_id: journalKey.slice(this.storagePrefix.length),
+    };
+    this.buffer.set(journalKey, {
       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,
+      metadata: eventMetadata,
       sdk_platform: Platform.OS,
       sdk_version: SDK_VERSION,
       os_name: Platform.OS,
@@ -287,49 +330,61 @@ export class TelemetryReporter {
     await this.persistBufferAsync();
   }
 
-  /**
-   * Persist the current buffer to AsyncStorage so events survive abrupt app exits.
-   * Fire-and-forget — never throws or blocks.
-   *
-   * IMPORTANT: skips persist if loadPersistedBuffer() hasn't completed yet,
-   * to avoid overwriting orphaned events from a previous session before recovery.
-   */
-  private persistBuffer(): void {
-    void this.persistBufferAsync();
+  private createJournalKey(): string {
+    this.eventSequence++;
+    return `${this.storagePrefix}${this.sessionId}:${this.eventSequence.toString(36)}`;
   }
 
-  private persistBufferAsync(): Promise<void> {
-    if (!this.loadedPersisted) return Promise.resolve();
+  private async persistBufferAsync(): Promise<boolean> {
+    if (!this.loadedPersisted) return Promise.resolve(false);
 
     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;
-      }
+      const entries = [
+        ...this.inFlightBuffer.entries(),
+        ...this.buffer.entries(),
+      ];
 
-      // 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
+      const operation = 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);
+          if (entries.length > 0) {
+            await storage.multiSet(
+              entries.map(([key, event]): [string, string] => [key, JSON.stringify(event)]),
+            );
           }
-        })
-        .catch(() => { /* never throw from telemetry */ });
-      return this.persistenceChain;
+        });
+      this.persistenceChain = operation.catch(() => { /* keep queue alive */ });
+      await operation;
+      return true;
     } catch {
       // Never throw from telemetry
-      return Promise.resolve();
+      return false;
     }
   }
 
+  private async removeJournalEntries(keys: string[]): Promise<boolean> {
+    if (keys.length === 0) return true;
+    try {
+      const operation = this.persistenceChain
+        .catch(() => { /* keep the write queue alive */ })
+        .then(async () => {
+          const storage = await getStorage();
+          await storage.multiRemove(keys);
+        });
+      this.persistenceChain = operation.catch(() => { /* keep queue alive */ });
+      await operation;
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private releaseClaims(): void {
+    for (const key of this.buffer.keys()) claimedEventKeys.delete(key);
+    for (const key of this.inFlightBuffer.keys()) claimedEventKeys.delete(key);
+  }
+
   /**
    * Load persisted events from a previous session and merge into current buffer.
    * Runs once per instance. If orphaned events are found, emits an
@@ -344,64 +399,84 @@ export class TelemetryReporter {
     }
 
     this.loadPersistedPromise = (async () => {
+      const claimedDuringRecovery: string[] = [];
       try {
         const storage = await getStorage();
-        const raw = await storage.getItem(TELEMETRY_PERSIST_KEY);
-        if (!raw) return;
-
-        const entries = JSON.parse(raw) as Record<string, TelemetryEvent>;
         let orphanedCount = 0;
         const orphanedTypes: string[] = [];
 
-        for (const [key, event] of Object.entries(entries)) {
-          if (event.session_id === this.sessionId) continue; // Same session, skip
-          orphanedCount++;
-          orphanedTypes.push(event.event_type);
-          // Merge orphaned events into the current buffer
-          const existing = this.buffer.get(key);
-          if (existing) {
-            existing.event_count += event.event_count;
-            if (event.first_occurred_at < existing.first_occurred_at) {
-              existing.first_occurred_at = event.first_occurred_at;
-            }
-            if (event.last_occurred_at > existing.last_occurred_at) {
-              existing.last_occurred_at = event.last_occurred_at;
-            }
-          } else {
+        const allKeys = await storage.getAllKeys();
+        const recoverableKeys = allKeys.filter((key) => {
+          if (!key.startsWith(this.storagePrefix)) return false;
+          if (claimedEventKeys.has(key)) return false;
+          claimedEventKeys.add(key);
+          claimedDuringRecovery.push(key);
+          return true;
+        });
+        const recoveredPairs = recoverableKeys.length > 0
+          ? await storage.multiGet(recoverableKeys)
+          : [];
+
+        for (const [key, raw] of recoveredPairs) {
+          if (!raw) {
+            claimedEventKeys.delete(key);
+            continue;
+          }
+          try {
+            const event = JSON.parse(raw) as TelemetryEvent;
+            orphanedCount++;
+            orphanedTypes.push(event.event_type);
             this.buffer.set(key, event);
+          } catch {
+            claimedEventKeys.delete(key);
+          }
+        }
+
+        // Migrate the pre-2.5.6 shared snapshot without a remove/rewrite gap:
+        // write each event journal entry first, then delete the legacy key.
+        if (!legacyBufferClaimed && allKeys.includes(LEGACY_TELEMETRY_PERSIST_KEY)) {
+          legacyBufferClaimed = true;
+          let migrated = false;
+          try {
+            const legacyRaw = await storage.getItem(LEGACY_TELEMETRY_PERSIST_KEY);
+            if (legacyRaw) {
+              const legacyEntries = JSON.parse(legacyRaw) as Record<string, TelemetryEvent>;
+              const migrationPairs: Array<[string, string]> = [];
+              for (const event of Object.values(legacyEntries)) {
+                const key = this.createJournalKey();
+                claimedEventKeys.add(key);
+                this.buffer.set(key, event);
+                orphanedCount++;
+                orphanedTypes.push(event.event_type);
+                migrationPairs.push([key, JSON.stringify(event)]);
+              }
+              if (migrationPairs.length > 0) await storage.multiSet(migrationPairs);
+            }
+            await storage.removeItem(LEGACY_TELEMETRY_PERSIST_KEY);
+            migrated = true;
+          } finally {
+            if (!migrated) legacyBufferClaimed = false;
           }
         }
 
         // Emit sdk_session_recovered if we recovered orphaned events from a previous session
         if (orphanedCount > 0) {
-          const now = new Date().toISOString();
           const uniqueTypes = [...new Set(orphanedTypes)];
-          const crashEvent: TelemetryEvent = {
-            event_type: 'sdk_session_recovered',
+          this.recordEvent('sdk_session_recovered', {
             component: 'TelemetryReporter',
-            error_message: `Recovered ${orphanedCount} unflushed event(s) from a previous session that ended without a clean telemetry flush: ${uniqueTypes.join(', ')}`,
-            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(`sdk_session_recovered|recovered|${this.sessionId}`, crashEvent);
+            error: `Recovered ${orphanedCount} unflushed event(s) from a previous session that ended without a clean telemetry flush: ${uniqueTypes.join(', ')}`,
+          });
         }
-
-        // Clear persisted data now that it's loaded into memory. The merged
-        // buffer will be re-persisted below until a flush succeeds.
-        await storage.removeItem(TELEMETRY_PERSIST_KEY);
       } catch {
         // Never throw from telemetry
+        for (const key of claimedDuringRecovery) {
+          if (!this.buffer.has(key)) claimedEventKeys.delete(key);
+        }
       } finally {
         this.loadedPersisted = true;
         this.loadPersistedPromise = null;
         if (this.buffer.size > 0 && !this.disposed) {
-          this.persistBuffer();
+          await this.persistBufferAsync();
           this.scheduleFlush();
         }
       }

package/src/version.ts

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