@switchlabs/verify-ai-react-native 1.0.0 → 1.1.1

package/README.md

@@ -16,6 +16,10 @@ React Native CLI:
 npm install @switchlabs/verify-ai-react-native expo-camera @react-native-async-storage/async-storage
 ```
 
+If you want on-device inference, also install `expo-file-system`,
+`react-native-fast-tflite`, and configure `react-native-fast-tflite` for the
+delegates you plan to use.
+
 ## Quick Start
 
 ```tsx
@@ -44,10 +48,15 @@ function ParkingScreen() {
 import { useVerifyAI, VerifyAIScanner } from '@switchlabs/verify-ai-react-native';
 
 function ScannerScreen() {
-  const { verify } = useVerifyAI({ apiKey: 'vai_your_api_key' });
+  const { verifyMultipart } = useVerifyAI({
+    apiKey: 'vai_your_api_key',
+    enableOnDeviceML: true,
+  });
   return (
     <VerifyAIScanner
-      onCapture={(base64) => verify({ image: base64, policy: 'scooter_parking' })}
+      onCapture={(imageUri) =>
+        verifyMultipart({ imageUri, policy: 'scooter_parking' })
+      }
       onResult={(result) => console.log(result.is_compliant ? 'PASS' : 'FAIL')}
     />
   );

package/lib/client/index.d.ts

@@ -1,9 +1,15 @@
-import type { VerifyAIConfig, VerificationRequest, VerificationResult, VerificationListResponse, VerificationListParams, VerifyAIError, PolicyConfigResponse } from '../types';
+import type { VerifyAIConfig, VerificationRequest, MultipartVerificationRequest, VerificationResult, VerificationListResponse, VerificationListParams, VerifyAIError, VerifyOptions, PolicyConfigResponse } from '../types';
+import { TelemetryReporter } from '../telemetry/TelemetryReporter';
 export declare class VerifyAIClient {
     private apiKey;
     private baseUrl;
     private timeout;
+    readonly telemetry: TelemetryReporter | null;
     constructor(config: VerifyAIConfig);
+    private parseResponseBody;
+    private buildRequestError;
+    private normalizeRequestError;
+    private executeRequest;
     private request;
     /**
      * Submit a photo for AI verification.
@@ -27,7 +33,19 @@ export declare class VerifyAIClient {
      * }
      * ```
      */
-    verify(request: VerificationRequest): Promise<VerificationResult>;
+    verify(request: VerificationRequest, options?: VerifyOptions): Promise<VerificationResult>;
+    /**
+     * Submit a photo for AI verification using multipart/form-data.
+     * Streams the image directly from disk — avoids base64 encoding overhead.
+     *
+     * **Breaking change:** `onCapture` prop on `VerifyAIScanner` now receives
+     * an image URI instead of a base64 string.
+     *
+     * @param request - Multipart request with file URI and policy
+     * @param options - Optional verify options (e.g. idempotency key)
+     * @returns The verification result with compliance status and feedback
+     */
+    verifyMultipart(request: MultipartVerificationRequest, options?: VerifyOptions): Promise<VerificationResult>;
     /**
      * List past verifications with optional filters.
      *
@@ -84,4 +102,6 @@ export declare class VerifyAIRequestError extends Error {
     get isServerError(): boolean;
     get isRetryable(): boolean;
     get upgradeUrl(): string | undefined;
+    get requestId(): string | undefined;
+    get code(): string | undefined;
 }

package/lib/client/index.js

@@ -1,3 +1,4 @@
+import { TelemetryReporter } from '../telemetry/TelemetryReporter';
 const DEFAULT_BASE_URL = 'https://verify.switchlabs.dev/api/v1';
 const DEFAULT_TIMEOUT = 30000;
 export class VerifyAIClient {
@@ -8,12 +9,54 @@ export class VerifyAIClient {
         this.apiKey = config.apiKey;
         this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, '');
         this.timeout = config.timeout || DEFAULT_TIMEOUT;
+        this.telemetry = config.telemetry !== false
+            ? new TelemetryReporter(this.apiKey, this.baseUrl)
+            : null;
     }
-    async request(path, options = {}) {
+    parseResponseBody(rawBody) {
+        if (!rawBody) {
+            return null;
+        }
+        try {
+            return JSON.parse(rawBody);
+        }
+        catch {
+            return { error: rawBody };
+        }
+    }
+    buildRequestError(message, status, context, body = {}) {
+        const error = {
+            error: message,
+            status,
+            code: status === 408 ? 'timeout' : status === 0 ? 'network_error' : 'request_error',
+            path: context.path,
+            url: context.url,
+            method: context.method,
+            ...body,
+        };
+        return new VerifyAIRequestError(message, status, error);
+    }
+    normalizeRequestError(error, context) {
+        if (error instanceof VerifyAIRequestError) {
+            return error;
+        }
+        if (error instanceof Error && error.name === 'AbortError') {
+            return this.buildRequestError('Verification request timed out', 408, context, { code: 'timeout' });
+        }
+        if (error instanceof TypeError) {
+            return this.buildRequestError('Network request failed', 0, context, { code: 'network_error' });
+        }
+        const message = error instanceof Error ? error.message : 'VerifyAI request failed';
+        return this.buildRequestError(message, 0, context);
+    }
+    async executeRequest(path, options = {}) {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), this.timeout);
+        const method = (options.method || 'GET').toUpperCase();
+        const url = `${this.baseUrl}${path}`;
+        const context = { path, url, method };
         try {
-            const response = await fetch(`${this.baseUrl}${path}`, {
+            const response = await fetch(url, {
                 ...options,
                 signal: controller.signal,
                 headers: {
@@ -22,35 +65,56 @@ export class VerifyAIClient {
                 },
             });
             const rawBody = await response.text();
-            let body = null;
-            if (rawBody) {
-                try {
-                    body = JSON.parse(rawBody);
-                }
-                catch {
-                    body = { error: rawBody };
-                }
-            }
+            const body = this.parseResponseBody(rawBody);
             if (!response.ok) {
                 const errorBody = (body && typeof body === 'object' ? body : null);
-                const error = {
-                    error: errorBody?.error || `Request failed with status ${response.status}`,
-                    status: response.status,
+                throw this.buildRequestError(errorBody?.error || `Request failed with status ${response.status}`, response.status, context, {
                     current_usage: errorBody?.current_usage,
                     limit: errorBody?.limit,
                     upgrade_url: errorBody?.upgrade_url,
-                };
-                throw new VerifyAIRequestError(error.error, response.status, error);
+                    request_id: errorBody?.request_id || response.headers.get('X-Request-Id') || undefined,
+                    code: errorBody?.code || 'http_error',
+                });
             }
             if (!body || typeof body !== 'object') {
-                throw new Error('VerifyAI: Invalid response payload');
+                throw this.buildRequestError('VerifyAI: Invalid response payload', 0, context, {
+                    code: 'invalid_response',
+                    request_id: response.headers.get('X-Request-Id') || undefined,
+                });
             }
             return body;
         }
+        catch (error) {
+            const normalized = this.normalizeRequestError(error, context);
+            // Track network/timeout/server errors
+            if (this.telemetry) {
+                const errorCode = normalized.code || (normalized.status >= 500 ? 'server_error' : undefined);
+                const eventType = normalized.status === 408 || normalized.code === 'timeout'
+                    ? 'request_timeout'
+                    : normalized.status === 0 || normalized.code === 'network_error'
+                        ? 'network_error'
+                        : normalized.status === 401 || normalized.status === 403
+                            ? 'auth_error'
+                            : normalized.status === 429
+                                ? 'rate_limited'
+                                : normalized.status >= 400 && normalized.status < 500
+                                    ? 'request_error'
+                                    : 'server_error';
+                this.telemetry.track(eventType, {
+                    component: 'client',
+                    error: normalized,
+                    errorCode,
+                });
+            }
+            throw normalized;
+        }
         finally {
             clearTimeout(timer);
         }
     }
+    async request(path, options = {}) {
+        return this.executeRequest(path, options);
+    }
     /**
      * Submit a photo for AI verification.
      *
@@ -73,13 +137,56 @@ export class VerifyAIClient {
      * }
      * ```
      */
-    async verify(request) {
+    async verify(request, options) {
+        const headers = { 'Content-Type': 'application/json' };
+        if (options?.idempotencyKey) {
+            headers['Idempotency-Key'] = options.idempotencyKey;
+        }
         return this.request('/verify', {
             method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
+            headers,
             body: JSON.stringify(request),
         });
     }
+    /**
+     * Submit a photo for AI verification using multipart/form-data.
+     * Streams the image directly from disk — avoids base64 encoding overhead.
+     *
+     * **Breaking change:** `onCapture` prop on `VerifyAIScanner` now receives
+     * an image URI instead of a base64 string.
+     *
+     * @param request - Multipart request with file URI and policy
+     * @param options - Optional verify options (e.g. idempotency key)
+     * @returns The verification result with compliance status and feedback
+     */
+    async verifyMultipart(request, options) {
+        const formData = new FormData();
+        // React Native FormData accepts { uri, type, name } objects for file fields
+        formData.append('image', {
+            uri: request.imageUri,
+            type: 'image/jpeg',
+            name: 'photo.jpg',
+        });
+        formData.append('policy', request.policy);
+        if (request.metadata) {
+            formData.append('metadata', JSON.stringify(request.metadata));
+        }
+        if (request.provider) {
+            formData.append('provider', request.provider);
+        }
+        const headers = {
+            'X-API-Key': this.apiKey,
+            // Do NOT set Content-Type — fetch auto-sets multipart boundary
+        };
+        if (options?.idempotencyKey) {
+            headers['Idempotency-Key'] = options.idempotencyKey;
+        }
+        return this.executeRequest('/verify', {
+            method: 'POST',
+            headers,
+            body: formData,
+        });
+    }
     /**
      * List past verifications with optional filters.
      *
@@ -171,4 +278,10 @@ export class VerifyAIRequestError extends Error {
     get upgradeUrl() {
         return this.body.upgrade_url;
     }
+    get requestId() {
+        return this.body.request_id;
+    }
+    get code() {
+        return this.body.code;
+    }
 }

package/lib/components/VerifyAIScanner.d.ts

@@ -1,10 +1,11 @@
 import React from 'react';
 import { type ViewStyle } from 'react-native';
 import type { VerificationResult, ScannerOverlayConfig } from '../types';
+import type { TelemetryReporter } from '../telemetry/TelemetryReporter';
 export interface VerifyAIScannerProps {
-    /** Called with the base64 image data when the user captures a photo. */
-    onCapture: (base64Image: string) => Promise<VerificationResult | null>;
-    /** Called when verification completes successfully. */
+    /** Called with the image URI when the user captures a photo. */
+    onCapture: (imageUri: string) => Promise<VerificationResult | null>;
+    /** Called when a terminal verification result is reached. */
     onResult?: (result: VerificationResult) => void;
     /** Called when an error occurs. */
     onError?: (error: Error) => void;
@@ -16,6 +17,10 @@ export interface VerifyAIScannerProps {
     showCaptureButton?: boolean;
     /** Ref to imperatively trigger capture from parent. */
     captureRef?: React.MutableRefObject<(() => void) | null>;
+    /** Whether to enable the camera torch/flashlight. */
+    enableTorch?: boolean;
+    /** Optional telemetry reporter (falls back to TelemetryContext). */
+    telemetry?: TelemetryReporter | null;
 }
 /**
  * Camera scanner component for capturing verification photos.
@@ -23,10 +28,13 @@ export interface VerifyAIScannerProps {
  *
  * @example
  * ```tsx
- * const { verify } = useVerifyAI({ apiKey: 'vai_...' });
+ * const { verifyMultipart } = useVerifyAI({
+ *   apiKey: 'vai_...',
+ *   enableOnDeviceML: true,
+ * });
  *
  * <VerifyAIScanner
- *   onCapture={(base64) => verify({ image: base64, policy: 'scooter_parking' })}
+ *   onCapture={(imageUri) => verifyMultipart({ imageUri, policy: 'scooter_parking' })}
  *   onResult={(result) => {
  *     if (result.is_compliant) navigation.navigate('Success');
  *   }}
@@ -38,4 +46,4 @@ export interface VerifyAIScannerProps {
  * />
  * ```
  */
-export declare function VerifyAIScanner({ onCapture, onResult, onError, overlay, style, showCaptureButton, captureRef, }: VerifyAIScannerProps): import("react/jsx-runtime").JSX.Element;
+export declare function VerifyAIScanner({ onCapture, onResult, onError, overlay, style, showCaptureButton, captureRef, enableTorch, telemetry: telemetryProp, }: VerifyAIScannerProps): import("react/jsx-runtime").JSX.Element;

package/lib/components/VerifyAIScanner.js

@@ -1,17 +1,62 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { useRef, useState, useCallback } from 'react';
+import { useRef, useState, useCallback, useEffect } from 'react';
 import { View, Text, TouchableOpacity, StyleSheet, ActivityIndicator, } from 'react-native';
 import { CameraView, useCameraPermissions, } from 'expo-camera';
+import * as ImageManipulator from 'expo-image-manipulator';
+import { useTelemetry } from '../telemetry/TelemetryContext';
+function getErrorDisplay(error, showTechnicalDetails) {
+    if (!error) {
+        return {
+            title: 'Something went wrong',
+            message: "We couldn't process your photo. Please try again.",
+        };
+    }
+    const status = error.status ?? error.body?.status;
+    const code = error.code ?? error.body?.code;
+    const requestId = error.requestId ?? error.body?.request_id;
+    let message = error.message?.trim() || "We couldn't process your photo. Please try again.";
+    if (code === 'timeout' || status === 408 || error.name === 'AbortError') {
+        message = 'Verification timed out. Please try again.';
+    }
+    else if (code === 'network_error' || status === 0) {
+        message = 'Network request failed. Check your connection and try again.';
+    }
+    else if (status === 401) {
+        message = 'Verification is not configured correctly.';
+    }
+    else if (status === 429) {
+        message = 'Verification is temporarily unavailable. Please try again.';
+    }
+    else if (status !== undefined && status >= 500) {
+        message = 'Verify AI is unavailable right now. Please try again.';
+    }
+    if (showTechnicalDetails) {
+        const details = [
+            status != null ? `status ${status}` : null,
+            requestId ? `request ${requestId}` : null,
+        ].filter(Boolean).join(' · ');
+        if (details) {
+            message = `${message}\n\n${details}`;
+        }
+    }
+    return {
+        title: 'Verification failed',
+        message,
+    };
+}
 /**
  * Camera scanner component for capturing verification photos.
  * Uses expo-camera for the camera view and provides a simple capture UI.
  *
  * @example
  * ```tsx
- * const { verify } = useVerifyAI({ apiKey: 'vai_...' });
+ * const { verifyMultipart } = useVerifyAI({
+ *   apiKey: 'vai_...',
+ *   enableOnDeviceML: true,
+ * });
  *
  * <VerifyAIScanner
- *   onCapture={(base64) => verify({ image: base64, policy: 'scooter_parking' })}
+ *   onCapture={(imageUri) => verifyMultipart({ imageUri, policy: 'scooter_parking' })}
  *   onResult={(result) => {
  *     if (result.is_compliant) navigation.navigate('Success');
  *   }}
@@ -23,29 +68,108 @@ import { CameraView, useCameraPermissions, } from 'expo-camera';
  * />
  * ```
  */
-export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style, showCaptureButton = true, captureRef, }) {
+export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style, showCaptureButton = true, captureRef, enableTorch, telemetry: telemetryProp, }) {
+    const contextTelemetry = useTelemetry();
+    const telemetry = telemetryProp ?? contextTelemetry;
     const cameraRef = useRef(null);
     const [status, setStatus] = useState('idle');
     const [result, setResult] = useState(null);
+    const [lastError, setLastError] = useState(null);
     const [permission, requestPermission] = useCameraPermissions();
     const attemptCountRef = useRef(0);
     const [exhausted, setExhausted] = useState(false);
+    const [terminated, setTerminated] = useState(false);
+    const [cameraReady, setCameraReady] = useState(false);
+    const cameraReadyRef = useRef(false);
+    const cameraInitFailedRef = useRef(false);
+    const permissionDeniedTrackedRef = useRef(false);
+    // Release camera (and torch) when a terminal result is reached or on unmount.
+    const releaseCamera = useCallback(() => {
+        setTerminated(true);
+        cameraRef.current?.pausePreview?.().catch(() => { });
+    }, []);
+    useEffect(() => {
+        return () => {
+            cameraRef.current?.pausePreview?.().catch(() => { });
+        };
+    }, []);
+    // Camera init callbacks
+    const onCameraReady = useCallback(() => {
+        setCameraReady(true);
+        cameraReadyRef.current = true;
+        cameraInitFailedRef.current = false;
+    }, []);
+    const onMountError = useCallback((event) => {
+        const error = new Error(event.message || 'Camera mount error');
+        setResult(null);
+        setLastError(error);
+        setStatus('error');
+        setCameraReady(false);
+        cameraReadyRef.current = false;
+        cameraInitFailedRef.current = true;
+        onError?.(error);
+        telemetry?.track('camera_init_failure', {
+            component: 'scanner',
+            error,
+        });
+    }, [onError, telemetry]);
+    // Startup watchdog — if camera hasn't fired onCameraReady within 5s, report timeout
+    useEffect(() => {
+        if (!permission?.granted || terminated)
+            return;
+        const timer = setTimeout(() => {
+            if (!cameraReadyRef.current && !cameraInitFailedRef.current) {
+                telemetry?.track('camera_preview_timeout', {
+                    component: 'scanner',
+                    error: 'Camera did not initialize within 5 seconds',
+                });
+            }
+        }, 5000);
+        return () => clearTimeout(timer);
+    }, [permission?.granted, terminated, telemetry]);
+    // Track permission denied
+    useEffect(() => {
+        if (permission &&
+            !permission.granted &&
+            permission.canAskAgain === false &&
+            !permissionDeniedTrackedRef.current) {
+            permissionDeniedTrackedRef.current = true;
+            telemetry?.track('camera_permission_denied', { component: 'scanner' });
+        }
+    }, [permission, telemetry]);
     const handleCapture = useCallback(async () => {
         if (!cameraRef.current || status === 'capturing' || status === 'processing' || exhausted)
             return;
+        if (!cameraReadyRef.current) {
+            const error = new Error('Camera is not ready yet. Please wait a moment and try again.');
+            setResult(null);
+            setLastError(error);
+            setStatus('error');
+            onError?.(error);
+            telemetry?.track('camera_not_ready', {
+                component: 'scanner',
+                error,
+            });
+            setTimeout(() => setStatus('idle'), 2000);
+            return;
+        }
         setStatus('capturing');
         setResult(null);
+        setLastError(null);
         try {
             const photo = await cameraRef.current.takePictureAsync({
-                base64: true,
                 quality: 0.8,
                 exif: false,
             });
-            if (!photo?.base64) {
+            if (!photo?.uri) {
                 throw new Error('Failed to capture photo');
             }
+            // Normalize EXIF orientation into actual pixels so the server
+            // receives an upright image (Gemini and other vision APIs ignore EXIF).
+            // An empty actions array makes ImageManipulator apply EXIF rotation only.
+            const normalized = await ImageManipulator.manipulateAsync(photo.uri, [], { compress: 0.8, format: ImageManipulator.SaveFormat.JPEG });
             setStatus('processing');
-            const verificationResult = await onCapture(photo.base64);
+            const verificationResult = await onCapture(normalized.uri);
             attemptCountRef.current++;
             if (verificationResult) {
                 const maxAttempts = overlay?.maxAttempts;
@@ -55,6 +179,7 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
                     maxAttempts != null &&
                     attemptCountRef.current >= maxAttempts) {
                     setExhausted(true);
+                    releaseCamera();
                     if (autoApprove) {
                         const approvedResult = { ...verificationResult, is_compliant: true };
                         setResult(approvedResult);
@@ -64,13 +189,22 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
                     else {
                         setResult(verificationResult);
                         setStatus('error');
+                        onResult?.(verificationResult);
                     }
                     return;
                 }
+                if (!verificationResult.is_compliant &&
+                    maxAttempts != null &&
+                    attemptCountRef.current < maxAttempts) {
+                    setResult(verificationResult);
+                    setStatus('error');
+                    setTimeout(() => setStatus('idle'), 3000);
+                    return;
+                }
+                releaseCamera();
                 setResult(verificationResult);
                 setStatus('success');
                 onResult?.(verificationResult);
-                setTimeout(() => setStatus('idle'), 3000);
             }
             else {
                 // null result means queued for offline
@@ -78,13 +212,20 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
             }
         }
         catch (err) {
-            const error = err instanceof Error ? err : new Error(String(err));
+            const error = (err instanceof Error ? err : new Error(String(err)));
+            setLastError(error);
             setStatus('error');
             onError?.(error);
+            // Track the error
+            const isCaptureFail = error.message?.includes('capture') || error.message?.includes('photo');
+            const isImageFail = error.message?.includes('manipulate') || error.message?.includes('image');
+            telemetry?.track(isCaptureFail ? 'capture_failure'
+                : isImageFail ? 'image_manipulation_failure'
+                    : 'unknown_error', { component: 'scanner', error });
             // Reset after a brief pause
             setTimeout(() => setStatus('idle'), 2000);
         }
-    }, [status, exhausted, onCapture, onResult, onError, overlay?.maxAttempts, overlay?.autoApproveOnExhaust]);
+    }, [status, exhausted, onCapture, onResult, onError, overlay?.maxAttempts, overlay?.autoApproveOnExhaust, releaseCamera, telemetry]);
     // Expose capture to parent via ref
     if (captureRef) {
         captureRef.current = handleCapture;
@@ -96,7 +237,7 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
         return (_jsxs(View, { style: [styles.container, styles.permissionContainer, style], children: [_jsx(Text, { style: styles.permissionText, children: "Camera access is required for photo verification" }), _jsx(TouchableOpacity, { style: styles.permissionButton, onPress: requestPermission, children: _jsx(Text, { style: styles.permissionButtonText, children: "Grant Camera Access" }) })] }));
     }
     const showBottomCard = status === 'success' || status === 'error';
-    return (_jsx(View, { style: [styles.container, style], children: _jsx(CameraView, { ref: cameraRef, style: styles.camera, facing: "back", children: _jsxs(View, { style: styles.overlay, children: [overlay?.title && (_jsx(View, { style: styles.topBar, children: _jsx(Text, { style: styles.titleText, children: overlay.title }) })), overlay?.showGuideFrame && (_jsx(View, { style: styles.guideContainer, children: _jsxs(View, { style: [
+    return (_jsx(View, { style: [styles.container, style], children: _jsx(CameraView, { ref: cameraRef, style: styles.camera, facing: "back", enableTorch: !terminated && enableTorch, onCameraReady: onCameraReady, onMountError: onMountError, children: _jsxs(View, { style: styles.overlay, children: [overlay?.title && (_jsx(View, { style: styles.topBar, children: _jsx(Text, { style: styles.titleText, children: overlay.title }) })), overlay?.showGuideFrame && (_jsx(View, { style: styles.guideContainer, children: _jsxs(View, { style: [
                                 styles.guideFrame,
                                 overlay.guideFrameAspectRatio
                                     ? { aspectRatio: overlay.guideFrameAspectRatio }
@@ -123,15 +264,16 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
                                     errorMessage = template.replace('{remaining}', String(remaining));
                                 }
                                 else {
-                                    errorTitle = 'Something went wrong';
-                                    errorMessage = "We couldn't process your photo. Please try again.";
+                                    const display = getErrorDisplay(lastError, overlay?.showTechnicalErrorDetails);
+                                    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 })] }));
                             })(), !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,
-                                                (status === 'capturing' || status === 'processing') &&
+                                                (!cameraReady || status === 'capturing' || status === 'processing') &&
                                                     styles.captureButtonDisabled,
-                                            ], onPress: handleCapture, disabled: status === 'capturing' || status === 'processing', activeOpacity: 0.7, children: _jsx(View, { style: styles.captureButtonInner }) }) }))] }))] })] }) }) }));
+                                            ], onPress: handleCapture, disabled: !cameraReady || status === 'capturing' || status === 'processing', activeOpacity: 0.7, children: _jsx(View, { style: styles.captureButtonInner }) }) }))] }))] })] }) }) }));
 }
 const CORNER_SIZE = 30;
 const CORNER_THICKNESS = 3;

package/lib/hooks/useVerifyAI.d.ts

@@ -1,9 +1,19 @@
+import React from 'react';
 import { VerifyAIClient } from '../client';
 import { OfflineQueue } from '../storage/offlineQueue';
-import type { VerifyAIConfig, VerificationRequest, VerificationResult, VerificationListParams, VerificationListResponse } from '../types';
+import type { TelemetryReporter } from '../telemetry/TelemetryReporter';
+import type { VerifyAIConfig, VerificationRequest, MultipartVerificationRequest, VerificationResult, VerificationListParams, VerificationListResponse, VerifyOptions } from '../types';
+export interface UseVerifyAIConfig extends VerifyAIConfig {
+    /** Enable on-device ML inference for faster, offline-capable verification. */
+    enableOnDeviceML?: boolean;
+    /** Minimum confidence threshold for on-device results. Below this, falls back to cloud. Default: 0.7 */
+    onDeviceConfidenceThreshold?: number;
+}
 export interface UseVerifyAIReturn {
-    /** Submit a verification. Uses offline queue if offlineMode is enabled and request fails. */
-    verify: (request: VerificationRequest) => Promise<VerificationResult | null>;
+    /** Submit a verification. Uses on-device ML if enabled and model is cached. */
+    verify: (request: VerificationRequest, options?: VerifyOptions) => Promise<VerificationResult | null>;
+    /** Submit a multipart verification. Uses on-device ML if enabled and model is cached. */
+    verifyMultipart: (request: MultipartVerificationRequest, options?: VerifyOptions) => Promise<VerificationResult | null>;
     /** List past verifications. */
     listVerifications: (params?: VerificationListParams) => Promise<VerificationListResponse>;
     /** Get a single verification by ID. */
@@ -22,27 +32,39 @@ export interface UseVerifyAIReturn {
     client: VerifyAIClient;
     /** The offline queue instance (null if offlineMode is disabled). */
     offlineQueue: OfflineQueue | null;
+    /** Whether an on-device model is loaded and ready. */
+    mlModelReady: boolean;
+    /** Initialize or update the on-device ML model for a policy. */
+    initializeMLModel: (policyId: string) => Promise<void>;
+    /** Telemetry reporter instance (null if telemetry is disabled). */
+    telemetry: TelemetryReporter | null;
+    /** TelemetryProvider component — wrap your scanner tree with this. */
+    TelemetryProvider: React.FC<{
+        children: React.ReactNode;
+    }>;
 }
 /**
- * React hook for Verify AI. Provides verification methods,
- * loading/error state, and optional offline queue management.
+ * React hook for Verify AI with optional on-device ML inference.
  *
  * @example
  * ```tsx
- * const { verify, loading, lastResult, error } = useVerifyAI({
+ * const { verify, loading, lastResult, mlModelReady, initializeMLModel } = useVerifyAI({
  *   apiKey: 'vai_your_api_key',
  *   offlineMode: true,
+ *   enableOnDeviceML: true,
  * });
  *
+ * // Initialize ML model on mount
+ * useEffect(() => {
+ *   initializeMLModel('scooter_parking');
+ * }, []);
+ *
  * const handleCapture = async (base64Image: string) => {
  *   const result = await verify({
  *     image: base64Image,
  *     policy: 'scooter_parking',
  *   });
- *   if (result?.is_compliant) {
- *     // Success
- *   }
  * };
  * ```
  */
-export declare function useVerifyAI(config: VerifyAIConfig): UseVerifyAIReturn;
+export declare function useVerifyAI(config: UseVerifyAIConfig): UseVerifyAIReturn;