@switchlabs/verify-ai-react-native 2.3.2 → 2.4.1

package/lib/client/index.js

@@ -118,9 +118,12 @@ export class VerifyAIClient {
                                 : normalized.status >= 400 && normalized.status < 500
                                     ? 'request_error'
                                     : 'server_error';
+                const telemetryError = eventType === 'request_timeout'
+                    ? `${normalized.message} [${context.method} ${context.path}; timeout=${this.timeout}ms]`
+                    : normalized;
                 this.telemetry.track(eventType, {
                     component: 'client',
-                    error: normalized,
+                    error: telemetryError,
                     errorCode,
                 });
             }
@@ -188,6 +191,9 @@ export class VerifyAIClient {
         if (request.provider) {
             formData.append('provider', request.provider);
         }
+        if (request.include_image_data) {
+            formData.append('include_image_data', 'true');
+        }
         const headers = {
             'X-API-Key': this.apiKey,
             // Do NOT set Content-Type — fetch auto-sets multipart boundary
@@ -217,6 +223,7 @@ export class VerifyAIClient {
                         policy: request.policy,
                         metadata: request.metadata,
                         provider: request.provider,
+                        include_image_data: request.include_image_data,
                     });
                 }
                 catch {

package/lib/components/VerifyAIScanner.js

@@ -1,14 +1,14 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useRef, useState, useCallback, useEffect } from 'react';
-import { View, Text, TouchableOpacity, StyleSheet, ActivityIndicator, } from 'react-native';
+import { View, Text, TouchableOpacity, StyleSheet, ActivityIndicator, AppState, useWindowDimensions, } from 'react-native';
 import { CameraView, useCameraPermissions, } from 'expo-camera';
 import { useTelemetry } from '../telemetry/TelemetryContext';
 /** Quality used when expo-image-manipulator is not available (lower = smaller). */
-const FALLBACK_QUALITY = 0.5;
+const FALLBACK_QUALITY = 0.65;
 /** Quality used when expo-image-manipulator IS available (resize handles size). */
-const MANIPULATOR_QUALITY = 0.7;
+const MANIPULATOR_QUALITY = 0.8;
 /** Max dimension (px) on longest side when resize is available. */
-const MAX_DIMENSION = 2048;
+const MAX_DIMENSION = 1600;
 function getErrorDisplay(error, showTechnicalDetails) {
     if (!error) {
         return {
@@ -89,16 +89,46 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
     const cameraReadyRef = useRef(false);
     const cameraInitFailedRef = useRef(false);
     const permissionDeniedTrackedRef = useRef(false);
+    // Track dimensions to detect orientation changes and remount camera
+    const { width: windowWidth, height: windowHeight } = useWindowDimensions();
+    const prevDimensionsRef = useRef({ width: windowWidth, height: windowHeight });
+    useEffect(() => {
+        const prev = prevDimensionsRef.current;
+        const orientationChanged = (prev.width > prev.height) !== (windowWidth > windowHeight);
+        prevDimensionsRef.current = { width: windowWidth, height: windowHeight };
+        if (orientationChanged && !terminated) {
+            // Force camera remount to fix preview distortion on iOS
+            setCameraReady(false);
+            cameraReadyRef.current = false;
+            setCameraKey((k) => k + 1);
+        }
+    }, [windowWidth, windowHeight, terminated]);
+    // Resume camera when app returns from background/inactive (e.g. notification bar)
+    useEffect(() => {
+        if (terminated)
+            return;
+        const subscription = AppState.addEventListener('change', (nextState) => {
+            if (nextState === 'active') {
+                // Force camera remount — on iOS, AVCaptureSession often fails to resume
+                // its preview layer after returning from the notification bar or control center.
+                setCameraReady(false);
+                cameraReadyRef.current = false;
+                setCameraKey((k) => k + 1);
+            }
+        });
+        return () => subscription.remove();
+    }, [terminated]);
+    const pausePreview = useCallback(() => {
+        cameraRef.current?.pausePreview?.().catch(() => { });
+    }, []);
     // Release camera (and torch) when a terminal result is reached or on unmount.
     const releaseCamera = useCallback(() => {
         setTerminated(true);
-        cameraRef.current?.pausePreview?.().catch(() => { });
-    }, []);
+        pausePreview();
+    }, [pausePreview]);
     useEffect(() => {
-        return () => {
-            cameraRef.current?.pausePreview?.().catch(() => { });
-        };
-    }, []);
+        return pausePreview;
+    }, [pausePreview]);
     // Camera init callbacks
     const onCameraReady = useCallback(() => {
         setCameraReady(true);
@@ -325,12 +355,16 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
                                     overlay.guideFrameAspectRatio
                                         ? { aspectRatio: overlay.guideFrameAspectRatio }
                                         : undefined,
-                                ], children: [overlay.guideOverlayContent && (_jsx(View, { style: [StyleSheet.absoluteFill, { opacity: overlay.guideOverlayOpacity ?? 0.3 }], children: overlay.guideOverlayContent })), _jsx(View, { style: [styles.corner, styles.cornerTopLeft] }), _jsx(View, { style: [styles.corner, styles.cornerTopRight] }), _jsx(View, { style: [styles.corner, styles.cornerBottomLeft] }), _jsx(View, { style: [styles.corner, styles.cornerBottomRight] })] }), overlay.guideCaption && (_jsx(Text, { style: styles.guideCaptionText, children: overlay.guideCaption }))] })), status === 'processing' && (_jsxs(View, { style: styles.processingOverlay, children: [_jsx(ActivityIndicator, { size: "large", color: "#fff" }), _jsx(Text, { style: styles.statusText, children: overlay?.processingMessage || 'Analyzing photo...' })] })), showBottomCard && _jsx(View, { style: styles.cardBackdrop }), _jsxs(View, { style: styles.bottomArea, children: [status === 'success' && result && (_jsxs(View, { style: styles.resultCard, children: [_jsxs(View, { style: styles.resultCardHeader, children: [_jsx(View, { style: [
+                                ], children: [overlay.guideOverlayContent && (_jsx(View, { style: [StyleSheet.absoluteFill, { opacity: overlay.guideOverlayOpacity ?? 0.3 }], children: overlay.guideOverlayContent })), _jsx(View, { style: [styles.corner, styles.cornerTopLeft, overlay.theme?.cornerColor ? { borderColor: overlay.theme.cornerColor } : undefined] }), _jsx(View, { style: [styles.corner, styles.cornerTopRight, overlay.theme?.cornerColor ? { borderColor: overlay.theme.cornerColor } : undefined] }), _jsx(View, { style: [styles.corner, styles.cornerBottomLeft, overlay.theme?.cornerColor ? { borderColor: overlay.theme.cornerColor } : undefined] }), _jsx(View, { style: [styles.corner, styles.cornerBottomRight, overlay.theme?.cornerColor ? { borderColor: overlay.theme.cornerColor } : undefined] })] }), overlay.guideCaption && (_jsx(Text, { style: styles.guideCaptionText, children: overlay.guideCaption }))] })), status === 'processing' && (_jsxs(View, { style: styles.processingOverlay, children: [_jsx(ActivityIndicator, { size: "large", color: "#fff" }), _jsx(Text, { style: styles.statusText, children: overlay?.processingMessage || 'Analyzing photo...' })] })), showBottomCard && _jsx(View, { style: styles.cardBackdrop }), _jsxs(View, { style: styles.bottomArea, children: [status === 'success' && result && (_jsxs(View, { style: styles.resultCard, children: [_jsxs(View, { style: styles.resultCardHeader, children: [_jsx(View, { style: [
                                                     styles.resultIconCircle,
                                                     result.is_compliant ? styles.resultIconPass : styles.resultIconFail,
+                                                    result.is_compliant && overlay?.theme?.successColor ? { backgroundColor: overlay.theme.successColor } : undefined,
+                                                    !result.is_compliant && overlay?.theme?.failureColor ? { backgroundColor: overlay.theme.failureColor } : undefined,
                                                 ], children: _jsx(Text, { style: styles.resultIcon, children: result.is_compliant ? '\u2713' : '\u2717' }) }), _jsx(Text, { style: [
                                                     styles.resultLabel,
                                                     result.is_compliant ? styles.resultLabelPass : styles.resultLabelFail,
+                                                    result.is_compliant && overlay?.theme?.successColor ? { color: overlay.theme.successColor } : undefined,
+                                                    !result.is_compliant && overlay?.theme?.failureColor ? { color: overlay.theme.failureColor } : undefined,
                                                 ], children: result.is_compliant
                                                     ? (overlay?.successMessage || 'Verified')
                                                     : (overlay?.failureMessage || 'Not Verified') })] }), _jsx(Text, { style: styles.feedbackText, children: result.feedback })] })), status === 'error' && (() => {
@@ -358,12 +392,13 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
                                     errorTitle = display.title;
                                     errorMessage = display.message;
                                 }
-                                return (_jsxs(View, { style: styles.resultCard, children: [_jsxs(View, { style: styles.resultCardHeader, children: [_jsx(View, { style: [styles.resultIconCircle, styles.resultIconError], children: _jsx(Text, { style: styles.resultIcon, children: "!" }) }), _jsx(Text, { style: [styles.resultLabel, styles.resultLabelError], children: errorTitle })] }), _jsx(Text, { style: styles.feedbackText, children: errorMessage })] }));
+                                return (_jsxs(View, { style: styles.resultCard, children: [_jsxs(View, { style: styles.resultCardHeader, children: [_jsx(View, { style: [styles.resultIconCircle, styles.resultIconError, overlay?.theme?.failureColor ? { backgroundColor: overlay.theme.failureColor } : undefined], children: _jsx(Text, { style: styles.resultIcon, children: "!" }) }), _jsx(Text, { style: [styles.resultLabel, styles.resultLabelError, overlay?.theme?.failureColor ? { color: overlay.theme.failureColor } : undefined], children: errorTitle })] }), _jsx(Text, { style: styles.feedbackText, children: errorMessage })] }));
                             })(), !showBottomCard && (_jsxs(_Fragment, { children: [overlay?.instructions && status === 'idle' && (_jsx(Text, { style: styles.instructionsText, children: overlay.instructions })), showCaptureButton && (_jsx(View, { style: styles.captureButtonRow, children: _jsx(TouchableOpacity, { style: [
                                                 styles.captureButton,
+                                                overlay?.theme?.captureButtonColor ? { borderColor: overlay.theme.captureButtonColor } : undefined,
                                                 (!cameraReady || status === 'capturing' || status === 'processing') &&
                                                     styles.captureButtonDisabled,
-                                            ], onPress: handleCapture, disabled: !cameraReady || status === 'capturing' || status === 'processing', activeOpacity: 0.7, children: _jsx(View, { style: styles.captureButtonInner }) }) }))] }))] })] }) }, cameraKey) }));
+                                            ], onPress: handleCapture, disabled: !cameraReady || status === 'capturing' || status === 'processing', activeOpacity: 0.7, children: _jsx(View, { style: [styles.captureButtonInner, overlay?.theme?.captureButtonColor ? { backgroundColor: overlay.theme.captureButtonColor } : undefined] }) }) }))] }))] })] }) }, cameraKey) }));
 }
 const CORNER_SIZE = 30;
 const CORNER_THICKNESS = 3;

package/lib/index.d.ts

@@ -5,4 +5,4 @@ export { TelemetryReporter } from './telemetry/TelemetryReporter';
 export { TelemetryContext } from './telemetry/TelemetryContext';
 export { OfflineQueue } from './storage/offlineQueue';
 export type { BundleManifest, ModelArtifact, FeatureVector, Detection as MLDetection, PolicyAST, PolicyResult, RuleResult, } from './ml/types';
-export type { VerifyAIConfig, VerificationRequest, MultipartVerificationRequest, VerificationResult, VerificationListResponse, VerificationListParams, QueueItem, VerifyAIError, ScannerStatus, ScannerOverlayConfig, PolicyConfigResponse, } from './types';
+export type { VerifyAIConfig, VerificationRequest, MultipartVerificationRequest, VerificationResult, VerificationListResponse, VerificationListParams, QueueItem, VerifyAIError, ScannerStatus, ScannerOverlayConfig, ScannerTheme, PolicyConfigResponse, } from './types';

package/lib/telemetry/TelemetryReporter.d.ts

@@ -6,6 +6,8 @@ export declare class TelemetryReporter {
     private apiKey;
     private disposed;
     private flushing;
+    private loadedPersisted;
+    private loadPersistedPromise;
     constructor(apiKey: string, baseUrl: string);
     /** Track an error event. Fire-and-forget — never throws. */
     track(eventType: string, opts?: {
@@ -21,4 +23,19 @@ export declare class TelemetryReporter {
     private scheduleFlush;
     private flushNow;
     private clearFlushTimer;
+    /**
+     * 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;
+    /**
+     * Load persisted events from a previous session and merge into current buffer.
+     * Runs once per instance. If orphaned events are found, emits an
+     * `sdk_session_recovered` event so monitoring can flag that the prior
+     * session ended without a clean telemetry flush.
+     */
+    private loadPersistedBuffer;
 }

package/lib/telemetry/TelemetryReporter.js

@@ -1,5 +1,14 @@
 import { Platform } from 'react-native';
 import { SDK_VERSION } from '../version';
+let _storage = null;
+async function getStorage() {
+    if (!_storage) {
+        const mod = await import('@react-native-async-storage/async-storage');
+        _storage = mod.default;
+    }
+    return _storage;
+}
+const TELEMETRY_PERSIST_KEY = '@verifyai/telemetry_buffer';
 /** Event types that flush immediately (critical init failures). */
 const CRITICAL_EVENTS = new Set([
     'camera_init_failure',
@@ -12,9 +21,13 @@ export class TelemetryReporter {
         this.flushTimer = null;
         this.disposed = false;
         this.flushing = false;
+        this.loadedPersisted = false;
+        this.loadPersistedPromise = null;
         this.apiKey = apiKey;
         this.baseUrl = baseUrl.replace(/\/$/, '');
         this.sessionId = Math.random().toString(36).slice(2) + Date.now().toString(36);
+        // Load any persisted events left behind by a previous session
+        this.loadPersistedBuffer();
     }
     /** Track an error event. Fire-and-forget — never throws. */
     track(eventType, opts = {}) {
@@ -59,6 +72,18 @@ export class TelemetryReporter {
             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();
+                    }
+                });
+            }
         }
         catch {
             // Never throw from telemetry
@@ -66,6 +91,8 @@ export class TelemetryReporter {
     }
     /** Flush all buffered events immediately. Returns a promise but never rejects. */
     async flush() {
+        // Merge any persisted events from a previous session before flushing
+        await this.loadPersistedBuffer();
         if (this.buffer.size === 0 || this.flushing)
             return;
         this.flushing = true;
@@ -88,6 +115,8 @@ export class TelemetryReporter {
             if (!response.ok) {
                 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
         }
         catch {
             for (const [dedupKey, event] of bufferedEntries) {
@@ -138,4 +167,111 @@ export class TelemetryReporter {
             this.flushTimer = null;
         }
     }
+    /**
+     * 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() {
+        if (!this.loadedPersisted)
+            return; // Don't overwrite orphaned prior-session data before it's loaded
+        try {
+            const entries = {};
+            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(() => { });
+        }
+        catch {
+            // Never throw from telemetry
+        }
+    }
+    /**
+     * Load persisted events from a previous session and merge into current buffer.
+     * Runs once per instance. If orphaned events are found, emits an
+     * `sdk_session_recovered` event so monitoring can flag that the prior
+     * session ended without a clean telemetry flush.
+     */
+    async loadPersistedBuffer() {
+        if (this.loadedPersisted)
+            return;
+        if (this.loadPersistedPromise) {
+            await this.loadPersistedPromise;
+            return;
+        }
+        this.loadPersistedPromise = (async () => {
+            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;
+                        }
+                    }
+                    else {
+                        this.buffer.set(key, event);
+                    }
+                }
+                // 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',
+                        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);
+                }
+                // 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
+            }
+            finally {
+                this.loadedPersisted = true;
+                this.loadPersistedPromise = null;
+                if (this.buffer.size > 0 && !this.disposed) {
+                    this.persistBuffer();
+                    this.scheduleFlush();
+                }
+            }
+        })();
+        await this.loadPersistedPromise;
+    }
 }

package/lib/types/index.d.ts

@@ -12,12 +12,16 @@ export interface VerificationRequest {
     policy: string;
     metadata?: Record<string, unknown>;
     provider?: 'openai' | 'anthropic' | 'gemini';
+    /** When true, the response includes the image as a base64 data URI in `image_data`. */
+    include_image_data?: boolean;
 }
 export interface MultipartVerificationRequest {
     imageUri: string;
     policy: string;
     metadata?: Record<string, unknown>;
     provider?: 'openai' | 'anthropic' | 'gemini';
+    /** When true, the response includes the image as a base64 data URI in `image_data`. */
+    include_image_data?: boolean;
 }
 export interface VerificationResult {
     id: string;
@@ -30,6 +34,8 @@ export interface VerificationResult {
     feedback: string;
     metadata: Record<string, unknown>;
     image_url: string | null;
+    /** Base64-encoded image data URI. Only present when `include_image_data` is requested. */
+    image_data?: string;
     /** Classification category (e.g. good_parking, no_vehicle, poor_photo). */
     category?: string;
 }
@@ -70,6 +76,23 @@ export interface VerifyAIError {
     method?: string;
 }
 export type ScannerStatus = 'idle' | 'capturing' | 'processing' | 'success' | 'error';
+/**
+ * Theme customization for the scanner overlay.
+ *
+ * All properties are optional — unset values fall back to built-in defaults.
+ * Pass a `ScannerTheme` to `ScannerOverlayConfig.theme` to match the scanner
+ * to your app's brand.
+ */
+export interface ScannerTheme {
+    /** Color for success states (checkmark circle, success card accent). Default: '#22C55E'. */
+    successColor?: string;
+    /** Color for failure/error states (warning icon, error card accent). Default: '#F59E0B'. */
+    failureColor?: string;
+    /** Color for the capture button circle. Default: '#FFFFFF'. */
+    captureButtonColor?: string;
+    /** Color for the guide frame corner brackets. Default: 'rgba(255, 255, 255, 0.7)'. */
+    cornerColor?: string;
+}
 export interface ScannerOverlayConfig {
     title?: string;
     instructions?: string;
@@ -99,6 +122,8 @@ export interface ScannerOverlayConfig {
     maxAttempts?: number;
     autoApproveOnExhaust?: boolean;
     showTechnicalErrorDetails?: boolean;
+    /** Custom theme for scanner colors. */
+    theme?: ScannerTheme;
 }
 export interface PolicyConfigResponse {
     maxAttempts: number;

package/lib/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "2.3.2";
+export declare const SDK_VERSION = "2.4.1";

package/lib/version.js

@@ -1 +1 @@
-export const SDK_VERSION = '2.3.2';
+export const SDK_VERSION = '2.4.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@switchlabs/verify-ai-react-native",
-  "version": "2.3.2",
+  "version": "2.4.1",
   "description": "React Native SDK for Verify AI - photo verification with AI vision processing",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -39,13 +39,13 @@
     "jpeg-js": "^0.4.4"
   },
   "peerDependencies": {
-    "react": ">=18.0.0",
-    "react-native": ">=0.72.0",
+    "@react-native-async-storage/async-storage": ">=1.19.0",
     "expo-camera": ">=15.0.0",
+    "expo-file-system": ">=17.0.0",
     "expo-image-manipulator": ">=12.0.0",
-    "@react-native-async-storage/async-storage": ">=1.19.0",
-    "react-native-fast-tflite": ">=1.0.0",
-    "expo-file-system": ">=17.0.0"
+    "react": ">=18.0.0",
+    "react-native": ">=0.72.0",
+    "react-native-fast-tflite": ">=1.0.0"
   },
   "peerDependenciesMeta": {
     "expo-camera": {
@@ -65,8 +65,8 @@
     }
   },
   "devDependencies": {
-    "@types/jpeg-js": "^0.3.7",
     "@react-native-async-storage/async-storage": "^2.1.0",
+    "@types/jpeg-js": "^0.3.7",
     "@types/react": "^18.2.0",
     "expo-camera": "^16.0.0",
     "expo-file-system": "^18.0.12",
@@ -74,6 +74,7 @@
     "react": "^18.2.0",
     "react-native": "^0.76.0",
     "react-native-fast-tflite": "^1.6.1",
-    "typescript": "^5.5.0"
+    "typescript": "^5.5.0",
+    "vitest": "^4.1.0"
   }
 }

package/src/client/index.ts

@@ -173,13 +173,16 @@ export class VerifyAIClient {
                 : normalized.status === 429
                   ? 'rate_limited'
                   : normalized.status >= 400 && normalized.status < 500
-                    ? 'request_error'
+                  ? 'request_error'
                     : 'server_error';
+        const telemetryError = eventType === 'request_timeout'
+          ? `${normalized.message} [${context.method} ${context.path}; timeout=${this.timeout}ms]`
+          : normalized;
         this.telemetry.track(
           eventType,
           {
             component: 'client',
-            error: normalized,
+            error: telemetryError,
             errorCode,
           },
         );
@@ -253,6 +256,9 @@ export class VerifyAIClient {
     if (request.provider) {
       formData.append('provider', request.provider);
     }
+    if (request.include_image_data) {
+      formData.append('include_image_data', 'true');
+    }
 
     const headers: Record<string, string> = {
       'X-API-Key': this.apiKey,
@@ -283,6 +289,7 @@ export class VerifyAIClient {
             policy: request.policy,
             metadata: request.metadata,
             provider: request.provider,
+            include_image_data: request.include_image_data,
           });
         } catch {
           // If the retry itself fails, throw the original error

package/src/components/VerifyAIScanner.tsx

@@ -5,6 +5,8 @@ import {
   TouchableOpacity,
   StyleSheet,
   ActivityIndicator,
+  AppState,
+  useWindowDimensions,
   type ViewStyle,
 } from 'react-native';
 import {
@@ -20,11 +22,11 @@ import { useTelemetry } from '../telemetry/TelemetryContext';
 import type { TelemetryReporter } from '../telemetry/TelemetryReporter';
 
 /** Quality used when expo-image-manipulator is not available (lower = smaller). */
-const FALLBACK_QUALITY = 0.5;
+const FALLBACK_QUALITY = 0.65;
 /** Quality used when expo-image-manipulator IS available (resize handles size). */
-const MANIPULATOR_QUALITY = 0.7;
+const MANIPULATOR_QUALITY = 0.8;
 /** Max dimension (px) on longest side when resize is available. */
-const MAX_DIMENSION = 2048;
+const MAX_DIMENSION = 1600;
 
 export interface VerifyAIScannerProps {
   /** Called with base64 image data when the user captures a photo. */
@@ -152,17 +154,54 @@ export function VerifyAIScanner({
   const cameraInitFailedRef = useRef(false);
   const permissionDeniedTrackedRef = useRef(false);
 
+  // Track dimensions to detect orientation changes and remount camera
+  const { width: windowWidth, height: windowHeight } = useWindowDimensions();
+  const prevDimensionsRef = useRef({ width: windowWidth, height: windowHeight });
+
+  useEffect(() => {
+    const prev = prevDimensionsRef.current;
+    const orientationChanged =
+      (prev.width > prev.height) !== (windowWidth > windowHeight);
+    prevDimensionsRef.current = { width: windowWidth, height: windowHeight };
+
+    if (orientationChanged && !terminated) {
+      // Force camera remount to fix preview distortion on iOS
+      setCameraReady(false);
+      cameraReadyRef.current = false;
+      setCameraKey((k) => k + 1);
+    }
+  }, [windowWidth, windowHeight, terminated]);
+
+  // Resume camera when app returns from background/inactive (e.g. notification bar)
+  useEffect(() => {
+    if (terminated) return;
+
+    const subscription = AppState.addEventListener('change', (nextState) => {
+      if (nextState === 'active') {
+        // Force camera remount — on iOS, AVCaptureSession often fails to resume
+        // its preview layer after returning from the notification bar or control center.
+        setCameraReady(false);
+        cameraReadyRef.current = false;
+        setCameraKey((k) => k + 1);
+      }
+    });
+
+    return () => subscription.remove();
+  }, [terminated]);
+
+  const pausePreview = useCallback(() => {
+    cameraRef.current?.pausePreview?.().catch(() => {});
+  }, []);
+
   // Release camera (and torch) when a terminal result is reached or on unmount.
   const releaseCamera = useCallback(() => {
     setTerminated(true);
-    cameraRef.current?.pausePreview?.().catch(() => {});
-  }, []);
+    pausePreview();
+  }, [pausePreview]);
 
   useEffect(() => {
-    return () => {
-      cameraRef.current?.pausePreview?.().catch(() => {});
-    };
-  }, []);
+    return pausePreview;
+  }, [pausePreview]);
 
   // Camera init callbacks
   const onCameraReady = useCallback(() => {
@@ -453,10 +492,10 @@ export function VerifyAIScanner({
                   </View>
                 )}
                 {/* Corner brackets */}
-                <View style={[styles.corner, styles.cornerTopLeft]} />
-                <View style={[styles.corner, styles.cornerTopRight]} />
-                <View style={[styles.corner, styles.cornerBottomLeft]} />
-                <View style={[styles.corner, styles.cornerBottomRight]} />
+                <View style={[styles.corner, styles.cornerTopLeft, overlay.theme?.cornerColor ? { borderColor: overlay.theme.cornerColor } : undefined]} />
+                <View style={[styles.corner, styles.cornerTopRight, overlay.theme?.cornerColor ? { borderColor: overlay.theme.cornerColor } : undefined]} />
+                <View style={[styles.corner, styles.cornerBottomLeft, overlay.theme?.cornerColor ? { borderColor: overlay.theme.cornerColor } : undefined]} />
+                <View style={[styles.corner, styles.cornerBottomRight, overlay.theme?.cornerColor ? { borderColor: overlay.theme.cornerColor } : undefined]} />
               </View>
               {overlay.guideCaption && (
                 <Text style={styles.guideCaptionText}>{overlay.guideCaption}</Text>
@@ -486,6 +525,8 @@ export function VerifyAIScanner({
                     style={[
                       styles.resultIconCircle,
                       result.is_compliant ? styles.resultIconPass : styles.resultIconFail,
+                      result.is_compliant && overlay?.theme?.successColor ? { backgroundColor: overlay.theme.successColor } : undefined,
+                      !result.is_compliant && overlay?.theme?.failureColor ? { backgroundColor: overlay.theme.failureColor } : undefined,
                     ]}
                   >
                     <Text style={styles.resultIcon}>
@@ -496,6 +537,8 @@ export function VerifyAIScanner({
                     style={[
                       styles.resultLabel,
                       result.is_compliant ? styles.resultLabelPass : styles.resultLabelFail,
+                      result.is_compliant && overlay?.theme?.successColor ? { color: overlay.theme.successColor } : undefined,
+                      !result.is_compliant && overlay?.theme?.failureColor ? { color: overlay.theme.failureColor } : undefined,
                     ]}
                   >
                     {result.is_compliant
@@ -534,10 +577,10 @@ export function VerifyAIScanner({
               return (
                 <View style={styles.resultCard}>
                   <View style={styles.resultCardHeader}>
-                    <View style={[styles.resultIconCircle, styles.resultIconError]}>
+                    <View style={[styles.resultIconCircle, styles.resultIconError, overlay?.theme?.failureColor ? { backgroundColor: overlay.theme.failureColor } : undefined]}>
                       <Text style={styles.resultIcon}>!</Text>
                     </View>
-                    <Text style={[styles.resultLabel, styles.resultLabelError]}>
+                    <Text style={[styles.resultLabel, styles.resultLabelError, overlay?.theme?.failureColor ? { color: overlay.theme.failureColor } : undefined]}>
                       {errorTitle}
                     </Text>
                   </View>
@@ -558,6 +601,7 @@ export function VerifyAIScanner({
                     <TouchableOpacity
                       style={[
                         styles.captureButton,
+                        overlay?.theme?.captureButtonColor ? { borderColor: overlay.theme.captureButtonColor } : undefined,
                         (!cameraReady || status === 'capturing' || status === 'processing') &&
                           styles.captureButtonDisabled,
                       ]}
@@ -565,7 +609,7 @@ export function VerifyAIScanner({
                       disabled={!cameraReady || status === 'capturing' || status === 'processing'}
                       activeOpacity={0.7}
                     >
-                      <View style={styles.captureButtonInner} />
+                      <View style={[styles.captureButtonInner, overlay?.theme?.captureButtonColor ? { backgroundColor: overlay.theme.captureButtonColor } : undefined]} />
                     </TouchableOpacity>
                   </View>
                 )}

package/src/index.ts

@@ -38,5 +38,6 @@ export type {
   VerifyAIError,
   ScannerStatus,
   ScannerOverlayConfig,
+  ScannerTheme,
   PolicyConfigResponse,
 } from './types';

package/src/telemetry/TelemetryReporter.ts

@@ -1,6 +1,17 @@
 import { Platform } from 'react-native';
 import { SDK_VERSION } from '../version';
 
+let _storage: typeof import('@react-native-async-storage/async-storage').default | null = null;
+async function getStorage() {
+  if (!_storage) {
+    const mod = await import('@react-native-async-storage/async-storage');
+    _storage = mod.default;
+  }
+  return _storage;
+}
+
+const TELEMETRY_PERSIST_KEY = '@verifyai/telemetry_buffer';
+
 interface TelemetryEvent {
   event_type: string;
   component?: string;
@@ -38,11 +49,15 @@ export class TelemetryReporter {
   private apiKey: string;
   private disposed = false;
   private flushing = false;
+  private loadedPersisted = false;
+  private loadPersistedPromise: Promise<void> | null = null;
 
   constructor(apiKey: string, baseUrl: string) {
     this.apiKey = apiKey;
     this.baseUrl = baseUrl.replace(/\/$/, '');
     this.sessionId = Math.random().toString(36).slice(2) + Date.now().toString(36);
+    // Load any persisted events left behind by a previous session
+    this.loadPersistedBuffer();
   }
 
   /** Track an error event. Fire-and-forget — never throws. */
@@ -100,6 +115,18 @@ export class TelemetryReporter {
       } 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();
+          }
+        });
+      }
     } catch {
       // Never throw from telemetry
     }
@@ -107,6 +134,9 @@ export class TelemetryReporter {
 
   /** 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
+    await this.loadPersistedBuffer();
+
     if (this.buffer.size === 0 || this.flushing) return;
 
     this.flushing = true;
@@ -131,6 +161,9 @@ export class TelemetryReporter {
       if (!response.ok) {
         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
     } catch {
       for (const [dedupKey, event] of bufferedEntries) {
         const existing = this.buffer.get(dedupKey);
@@ -181,4 +214,110 @@ export class TelemetryReporter {
       this.flushTimer = null;
     }
   }
+
+  /**
+   * 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 {
+    if (!this.loadedPersisted) return; // Don't overwrite orphaned prior-session data before it's loaded
+    try {
+      const entries: Record<string, TelemetryEvent> = {};
+      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 */ });
+    } catch {
+      // Never throw from telemetry
+    }
+  }
+
+  /**
+   * Load persisted events from a previous session and merge into current buffer.
+   * Runs once per instance. If orphaned events are found, emits an
+   * `sdk_session_recovered` event so monitoring can flag that the prior
+   * session ended without a clean telemetry flush.
+   */
+  private async loadPersistedBuffer(): Promise<void> {
+    if (this.loadedPersisted) return;
+    if (this.loadPersistedPromise) {
+      await this.loadPersistedPromise;
+      return;
+    }
+
+    this.loadPersistedPromise = (async () => {
+      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 {
+            this.buffer.set(key, event);
+          }
+        }
+
+        // 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',
+            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);
+        }
+
+        // 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
+      } finally {
+        this.loadedPersisted = true;
+        this.loadPersistedPromise = null;
+        if (this.buffer.size > 0 && !this.disposed) {
+          this.persistBuffer();
+          this.scheduleFlush();
+        }
+      }
+    })();
+
+    await this.loadPersistedPromise;
+  }
 }

package/src/types/index.ts

@@ -14,6 +14,8 @@ export interface VerificationRequest {
   policy: string;
   metadata?: Record<string, unknown>;
   provider?: 'openai' | 'anthropic' | 'gemini';
+  /** When true, the response includes the image as a base64 data URI in `image_data`. */
+  include_image_data?: boolean;
 }
 
 export interface MultipartVerificationRequest {
@@ -21,6 +23,8 @@ export interface MultipartVerificationRequest {
   policy: string;
   metadata?: Record<string, unknown>;
   provider?: 'openai' | 'anthropic' | 'gemini';
+  /** When true, the response includes the image as a base64 data URI in `image_data`. */
+  include_image_data?: boolean;
 }
 
 export interface VerificationResult {
@@ -34,6 +38,8 @@ export interface VerificationResult {
   feedback: string;
   metadata: Record<string, unknown>;
   image_url: string | null;
+  /** Base64-encoded image data URI. Only present when `include_image_data` is requested. */
+  image_data?: string;
   /** Classification category (e.g. good_parking, no_vehicle, poor_photo). */
   category?: string;
 }
@@ -81,6 +87,24 @@ export interface VerifyAIError {
 
 export type ScannerStatus = 'idle' | 'capturing' | 'processing' | 'success' | 'error';
 
+/**
+ * Theme customization for the scanner overlay.
+ *
+ * All properties are optional — unset values fall back to built-in defaults.
+ * Pass a `ScannerTheme` to `ScannerOverlayConfig.theme` to match the scanner
+ * to your app's brand.
+ */
+export interface ScannerTheme {
+  /** Color for success states (checkmark circle, success card accent). Default: '#22C55E'. */
+  successColor?: string;
+  /** Color for failure/error states (warning icon, error card accent). Default: '#F59E0B'. */
+  failureColor?: string;
+  /** Color for the capture button circle. Default: '#FFFFFF'. */
+  captureButtonColor?: string;
+  /** Color for the guide frame corner brackets. Default: 'rgba(255, 255, 255, 0.7)'. */
+  cornerColor?: string;
+}
+
 export interface ScannerOverlayConfig {
   title?: string;
   instructions?: string;
@@ -110,6 +134,8 @@ export interface ScannerOverlayConfig {
   maxAttempts?: number;
   autoApproveOnExhaust?: boolean;
   showTechnicalErrorDetails?: boolean;
+  /** Custom theme for scanner colors. */
+  theme?: ScannerTheme;
 }
 
 export interface PolicyConfigResponse {

package/src/version.ts

@@ -1 +1 @@
-export const SDK_VERSION = '2.3.2';
+export const SDK_VERSION = '2.4.1';