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

package/README.md

@@ -0,0 +1,73 @@
+# @switchlabs/verify-ai-react-native
+
+React Native SDK for Verify AI photo verification.
+
+## Install
+
+Expo-managed apps:
+
+```bash
+npx expo install @switchlabs/verify-ai-react-native expo-camera @react-native-async-storage/async-storage
+```
+
+React Native CLI:
+
+```bash
+npm install @switchlabs/verify-ai-react-native expo-camera @react-native-async-storage/async-storage
+```
+
+## Quick Start
+
+```tsx
+import { useVerifyAI } from '@switchlabs/verify-ai-react-native';
+
+function ParkingScreen() {
+  const { verify } = useVerifyAI({ apiKey: 'vai_your_api_key' });
+
+  const onPhoto = async (base64: string) => {
+    const result = await verify({
+      image: base64,
+      policy: 'scooter_parking',
+    });
+    if (result?.is_compliant) {
+      console.log('PASS');
+    }
+  };
+
+  return null;
+}
+```
+
+## Scanner Component
+
+```tsx
+import { useVerifyAI, VerifyAIScanner } from '@switchlabs/verify-ai-react-native';
+
+function ScannerScreen() {
+  const { verify } = useVerifyAI({ apiKey: 'vai_your_api_key' });
+  return (
+    <VerifyAIScanner
+      onCapture={(base64) => verify({ image: base64, policy: 'scooter_parking' })}
+      onResult={(result) => console.log(result.is_compliant ? 'PASS' : 'FAIL')}
+    />
+  );
+}
+```
+
+## Offline Mode
+
+Set `offlineMode: true` to queue transient failures (network, timeout, 429, 5xx) and retry later.
+
+```tsx
+const { verify, queueSize, processQueue } = useVerifyAI({
+  apiKey: 'vai_your_api_key',
+  offlineMode: true,
+});
+
+const result = await verify({ image: base64, policy: 'scooter_parking' });
+await processQueue();
+```
+
+## API Docs
+
+Full API docs: https://verify.switchlabs.dev/docs

package/lib/client/index.d.ts

@@ -1,4 +1,4 @@
-import type { VerifyAIConfig, VerificationRequest, VerificationResult, VerificationListResponse, VerificationListParams, VerifyAIError } from '../types';
+import type { VerifyAIConfig, VerificationRequest, VerificationResult, VerificationListResponse, VerificationListParams, VerifyAIError, PolicyConfigResponse } from '../types';
 export declare class VerifyAIClient {
     private apiKey;
     private baseUrl;
@@ -51,6 +51,29 @@ export declare class VerifyAIClient {
      * @returns The full verification result with a fresh signed image URL
      */
     getVerification(id: string): Promise<VerificationResult>;
+    /**
+     * Fetch the policy configuration (categories, attempt limits, UI copy).
+     *
+     * Use this to configure the scanner overlay with server-driven settings
+     * so you can update behavior without shipping a new app version.
+     *
+     * @param policyId - The policy ID (e.g., "pol_abc123")
+     * @returns Policy config with maxAttempts, autoApproveOnExhaust, uiCopy, categories
+     *
+     * @example
+     * ```typescript
+     * const config = await client.fetchPolicyConfig('pol_abc123');
+     * // Use config to set scanner overlay props
+     * <VerifyAIScanner
+     *   overlay={{
+     *     maxAttempts: config.maxAttempts,
+     *     autoApproveOnExhaust: config.autoApproveOnExhaust,
+     *     processingMessage: config.uiCopy.processingMessage,
+     *   }}
+     * />
+     * ```
+     */
+    fetchPolicyConfig(policyId: string): Promise<PolicyConfigResponse>;
 }
 export declare class VerifyAIRequestError extends Error {
     status: number;
@@ -58,5 +81,7 @@ export declare class VerifyAIRequestError extends Error {
     constructor(message: string, status: number, body: VerifyAIError);
     get isRateLimited(): boolean;
     get isUnauthorized(): boolean;
+    get isServerError(): boolean;
+    get isRetryable(): boolean;
     get upgradeUrl(): string | undefined;
 }

package/lib/client/index.js

@@ -21,10 +21,29 @@ export class VerifyAIClient {
                     ...options.headers,
                 },
             });
-            const body = await response.json();
+            const rawBody = await response.text();
+            let body = null;
+            if (rawBody) {
+                try {
+                    body = JSON.parse(rawBody);
+                }
+                catch {
+                    body = { error: rawBody };
+                }
+            }
             if (!response.ok) {
-                const error = body;
-                throw new VerifyAIRequestError(error.error || `Request failed with status ${response.status}`, response.status, error);
+                const errorBody = (body && typeof body === 'object' ? body : null);
+                const error = {
+                    error: errorBody?.error || `Request failed with status ${response.status}`,
+                    status: response.status,
+                    current_usage: errorBody?.current_usage,
+                    limit: errorBody?.limit,
+                    upgrade_url: errorBody?.upgrade_url,
+                };
+                throw new VerifyAIRequestError(error.error, response.status, error);
+            }
+            if (!body || typeof body !== 'object') {
+                throw new Error('VerifyAI: Invalid response payload');
             }
             return body;
         }
@@ -104,6 +123,31 @@ export class VerifyAIClient {
     async getVerification(id) {
         return this.request(`/verifications/${id}`);
     }
+    /**
+     * Fetch the policy configuration (categories, attempt limits, UI copy).
+     *
+     * Use this to configure the scanner overlay with server-driven settings
+     * so you can update behavior without shipping a new app version.
+     *
+     * @param policyId - The policy ID (e.g., "pol_abc123")
+     * @returns Policy config with maxAttempts, autoApproveOnExhaust, uiCopy, categories
+     *
+     * @example
+     * ```typescript
+     * const config = await client.fetchPolicyConfig('pol_abc123');
+     * // Use config to set scanner overlay props
+     * <VerifyAIScanner
+     *   overlay={{
+     *     maxAttempts: config.maxAttempts,
+     *     autoApproveOnExhaust: config.autoApproveOnExhaust,
+     *     processingMessage: config.uiCopy.processingMessage,
+     *   }}
+     * />
+     * ```
+     */
+    async fetchPolicyConfig(policyId) {
+        return this.request(`/policies/${policyId}/config`);
+    }
 }
 export class VerifyAIRequestError extends Error {
     constructor(message, status, body) {
@@ -118,6 +162,12 @@ export class VerifyAIRequestError extends Error {
     get isUnauthorized() {
         return this.status === 401;
     }
+    get isServerError() {
+        return this.status >= 500;
+    }
+    get isRetryable() {
+        return this.status === 408 || this.status === 429 || this.status >= 500;
+    }
     get upgradeUrl() {
         return this.body.upgrade_url;
     }

package/lib/components/VerifyAIScanner.js

@@ -28,8 +28,10 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
     const [status, setStatus] = useState('idle');
     const [result, setResult] = useState(null);
     const [permission, requestPermission] = useCameraPermissions();
+    const attemptCountRef = useRef(0);
+    const [exhausted, setExhausted] = useState(false);
     const handleCapture = useCallback(async () => {
-        if (!cameraRef.current || status === 'capturing' || status === 'processing')
+        if (!cameraRef.current || status === 'capturing' || status === 'processing' || exhausted)
             return;
         setStatus('capturing');
         setResult(null);
@@ -44,7 +46,27 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
             }
             setStatus('processing');
             const verificationResult = await onCapture(photo.base64);
+            attemptCountRef.current++;
             if (verificationResult) {
+                const maxAttempts = overlay?.maxAttempts;
+                const autoApprove = overlay?.autoApproveOnExhaust ?? false;
+                // Check attempt exhaustion for non-compliant results
+                if (!verificationResult.is_compliant &&
+                    maxAttempts != null &&
+                    attemptCountRef.current >= maxAttempts) {
+                    setExhausted(true);
+                    if (autoApprove) {
+                        const approvedResult = { ...verificationResult, is_compliant: true };
+                        setResult(approvedResult);
+                        setStatus('success');
+                        onResult?.(approvedResult);
+                    }
+                    else {
+                        setResult(verificationResult);
+                        setStatus('error');
+                    }
+                    return;
+                }
                 setResult(verificationResult);
                 setStatus('success');
                 onResult?.(verificationResult);
@@ -62,7 +84,7 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
             // Reset after a brief pause
             setTimeout(() => setStatus('idle'), 2000);
         }
-    }, [status, onCapture, onResult, onError]);
+    }, [status, exhausted, onCapture, onResult, onError, overlay?.maxAttempts, overlay?.autoApproveOnExhaust]);
     // Expose capture to parent via ref
     if (captureRef) {
         captureRef.current = handleCapture;
@@ -79,13 +101,33 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
                                 overlay.guideFrameAspectRatio
                                     ? { aspectRatio: overlay.guideFrameAspectRatio }
                                     : undefined,
-                            ], children: [_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] })] }) })), status === 'processing' && (_jsxs(View, { style: styles.processingOverlay, children: [_jsx(ActivityIndicator, { size: "large", color: "#fff" }), _jsx(Text, { style: styles.statusText, children: "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] }), _jsx(View, { style: [styles.corner, styles.cornerTopRight] }), _jsx(View, { style: [styles.corner, styles.cornerBottomLeft] }), _jsx(View, { style: [styles.corner, styles.cornerBottomRight] })] }) })), 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,
                                                 ], children: _jsx(Text, { style: styles.resultIcon, children: result.is_compliant ? '\u2713' : '\u2717' }) }), _jsx(Text, { style: [
                                                     styles.resultLabel,
                                                     result.is_compliant ? styles.resultLabelPass : styles.resultLabelFail,
-                                                ], children: result.is_compliant ? 'Verified' : 'Not Verified' })] }), _jsx(Text, { style: styles.feedbackText, children: result.feedback })] })), status === 'error' && (_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: "Something went wrong" })] }), _jsx(Text, { style: styles.feedbackText, children: "We couldn't process your photo. Please try again." })] })), !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: [
+                                                ], children: result.is_compliant
+                                                    ? (overlay?.successMessage || 'Verified')
+                                                    : (overlay?.failureMessage || 'Not Verified') })] }), _jsx(Text, { style: styles.feedbackText, children: result.feedback })] })), status === 'error' && (() => {
+                                let errorTitle;
+                                let errorMessage;
+                                if (exhausted) {
+                                    errorTitle = 'Attempts Exhausted';
+                                    errorMessage = overlay?.exhaustedMessage || 'Maximum attempts reached.';
+                                }
+                                else if (overlay?.maxAttempts != null && attemptCountRef.current < overlay.maxAttempts && result && !result.is_compliant) {
+                                    const remaining = overlay.maxAttempts - attemptCountRef.current;
+                                    errorTitle = 'Not Verified';
+                                    const template = overlay?.retryMessage || 'Please try again. {remaining} attempts left.';
+                                    errorMessage = template.replace('{remaining}', String(remaining));
+                                }
+                                else {
+                                    errorTitle = 'Something went wrong';
+                                    errorMessage = "We couldn't process your photo. Please try again.";
+                                }
+                                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') &&
                                                     styles.captureButtonDisabled,

package/lib/hooks/useVerifyAI.js

@@ -1,7 +1,20 @@
 import { useMemo, useCallback, useState, useEffect } from 'react';
 import { AppState } from 'react-native';
-import { VerifyAIClient } from '../client';
+import { VerifyAIClient, VerifyAIRequestError } from '../client';
 import { OfflineQueue } from '../storage/offlineQueue';
+function isQueueableError(error) {
+    if (error instanceof VerifyAIRequestError) {
+        return error.isRetryable;
+    }
+    if (error.name === 'AbortError') {
+        return true;
+    }
+    const message = error.message.toLowerCase();
+    return (message.includes('network') ||
+        message.includes('timeout') ||
+        message.includes('timed out') ||
+        message.includes('failed to fetch'));
+}
 /**
  * React hook for Verify AI. Provides verification methods,
  * loading/error state, and optional offline queue management.
@@ -62,8 +75,8 @@ export function useVerifyAI(config) {
         catch (err) {
             const error = err instanceof Error ? err : new Error(String(err));
             setError(error);
-            // If offline mode, queue the request
-            if (offlineQueue) {
+            // Queue only transient failures so invalid requests are surfaced immediately.
+            if (offlineQueue && isQueueableError(error)) {
                 await offlineQueue.enqueue(request);
                 await refreshQueueSize();
                 return null;

package/lib/index.d.ts

@@ -4,4 +4,4 @@ export type { UseVerifyAIReturn } from './hooks/useVerifyAI';
 export { VerifyAIScanner } from './components/VerifyAIScanner';
 export type { VerifyAIScannerProps } from './components/VerifyAIScanner';
 export { OfflineQueue } from './storage/offlineQueue';
-export type { VerifyAIConfig, VerificationRequest, VerificationResult, VerificationListResponse, VerificationListParams, QueueItem, VerifyAIError, ScannerStatus, ScannerOverlayConfig, } from './types';
+export type { VerifyAIConfig, VerificationRequest, VerificationResult, VerificationListResponse, VerificationListParams, QueueItem, VerifyAIError, ScannerStatus, ScannerOverlayConfig, PolicyConfigResponse, } from './types';

package/lib/storage/offlineQueue.js

@@ -1,4 +1,5 @@
 import AsyncStorage from '@react-native-async-storage/async-storage';
+import { VerifyAIRequestError } from '../client';
 const MANIFEST_KEY = '@verifyai/queue_manifest';
 const ITEM_PREFIX = '@verifyai/queue_item_';
 const LEGACY_KEY = '@verifyai/offline_queue';
@@ -157,9 +158,11 @@ export class OfflineQueue {
                     await AsyncStorage.removeItem(`${ITEM_PREFIX}${id}`);
                     onResult?.(item.id, result);
                 }
-                catch {
+                catch (err) {
+                    const requestError = err instanceof VerifyAIRequestError ? err : null;
+                    const shouldRetry = !requestError || requestError.isRetryable;
                     item.retryCount++;
-                    if (item.retryCount < maxRetries) {
+                    if (shouldRetry && item.retryCount < maxRetries) {
                         await AsyncStorage.setItem(`${ITEM_PREFIX}${id}`, JSON.stringify(item));
                         remainingIds.push(id);
                     }

package/lib/types/index.d.ts

@@ -1,3 +1,4 @@
+import type React from 'react';
 export interface VerifyAIConfig {
     apiKey: string;
     baseUrl?: string;
@@ -44,7 +45,7 @@ export interface QueueItem {
 }
 export interface VerifyAIError {
     error: string;
-    status: number;
+    status?: number;
     current_usage?: number;
     limit?: number;
     upgrade_url?: string;
@@ -55,4 +56,37 @@ export interface ScannerOverlayConfig {
     instructions?: string;
     showGuideFrame?: boolean;
     guideFrameAspectRatio?: number;
+    /**
+     * Optional React element rendered inside the guide frame as a semi-transparent
+     * overlay (e.g. a silhouette image to guide photo composition).
+     *
+     * The element is absolutely positioned to fill the guide frame.
+     *
+     * @example
+     * ```tsx
+     * guideOverlayContent: <Image source={require('./bike_silhouette.png')} style={{ width: '100%', height: '100%' }} resizeMode="contain" />
+     * ```
+     */
+    guideOverlayContent?: React.ReactNode;
+    /** Opacity of the guideOverlayContent (0–1). Default: 0.3. */
+    guideOverlayOpacity?: number;
+    processingMessage?: string;
+    successMessage?: string;
+    failureMessage?: string;
+    retryMessage?: string;
+    exhaustedMessage?: string;
+    maxAttempts?: number;
+    autoApproveOnExhaust?: boolean;
+}
+export interface PolicyConfigResponse {
+    maxAttempts: number;
+    autoApproveOnExhaust: boolean;
+    uiCopy: Record<string, string | undefined>;
+    categories: Array<{
+        id: string;
+        label: string;
+        color: string;
+        isCompliant: boolean;
+        description?: string;
+    }>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@switchlabs/verify-ai-react-native",
-  "version": "0.1.5",
+  "version": "1.0.0",
   "description": "React Native SDK for Verify AI - photo verification with AI vision processing",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",

package/src/client/index.ts

@@ -5,6 +5,7 @@ import type {
   VerificationListResponse,
   VerificationListParams,
   VerifyAIError,
+  PolicyConfigResponse,
 } from '../types';
 
 const DEFAULT_BASE_URL = 'https://verify.switchlabs.dev/api/v1';
@@ -41,17 +42,38 @@ export class VerifyAIClient {
         },
       });
 
-      const body = await response.json();
+      const rawBody = await response.text();
+      let body: unknown = null;
+
+      if (rawBody) {
+        try {
+          body = JSON.parse(rawBody);
+        } catch {
+          body = { error: rawBody };
+        }
+      }
 
       if (!response.ok) {
-        const error = body as VerifyAIError;
+        const errorBody = (body && typeof body === 'object' ? body : null) as VerifyAIError | null;
+        const error: VerifyAIError = {
+          error: errorBody?.error || `Request failed with status ${response.status}`,
+          status: response.status,
+          current_usage: errorBody?.current_usage,
+          limit: errorBody?.limit,
+          upgrade_url: errorBody?.upgrade_url,
+        };
+
         throw new VerifyAIRequestError(
-          error.error || `Request failed with status ${response.status}`,
+          error.error,
           response.status,
           error
         );
       }
 
+      if (!body || typeof body !== 'object') {
+        throw new Error('VerifyAI: Invalid response payload');
+      }
+
       return body as T;
     } finally {
       clearTimeout(timer);
@@ -131,6 +153,32 @@ export class VerifyAIClient {
   async getVerification(id: string): Promise<VerificationResult> {
     return this.request<VerificationResult>(`/verifications/${id}`);
   }
+
+  /**
+   * Fetch the policy configuration (categories, attempt limits, UI copy).
+   *
+   * Use this to configure the scanner overlay with server-driven settings
+   * so you can update behavior without shipping a new app version.
+   *
+   * @param policyId - The policy ID (e.g., "pol_abc123")
+   * @returns Policy config with maxAttempts, autoApproveOnExhaust, uiCopy, categories
+   *
+   * @example
+   * ```typescript
+   * const config = await client.fetchPolicyConfig('pol_abc123');
+   * // Use config to set scanner overlay props
+   * <VerifyAIScanner
+   *   overlay={{
+   *     maxAttempts: config.maxAttempts,
+   *     autoApproveOnExhaust: config.autoApproveOnExhaust,
+   *     processingMessage: config.uiCopy.processingMessage,
+   *   }}
+   * />
+   * ```
+   */
+  async fetchPolicyConfig(policyId: string): Promise<PolicyConfigResponse> {
+    return this.request<PolicyConfigResponse>(`/policies/${policyId}/config`);
+  }
 }
 
 export class VerifyAIRequestError extends Error {
@@ -152,6 +200,14 @@ export class VerifyAIRequestError extends Error {
     return this.status === 401;
   }
 
+  get isServerError(): boolean {
+    return this.status >= 500;
+  }
+
+  get isRetryable(): boolean {
+    return this.status === 408 || this.status === 429 || this.status >= 500;
+  }
+
   get upgradeUrl(): string | undefined {
     return this.body.upgrade_url;
   }

package/src/components/VerifyAIScanner.tsx

@@ -69,9 +69,11 @@ export function VerifyAIScanner({
   const [status, setStatus] = useState<ScannerStatus>('idle');
   const [result, setResult] = useState<VerificationResult | null>(null);
   const [permission, requestPermission] = useCameraPermissions();
+  const attemptCountRef = useRef(0);
+  const [exhausted, setExhausted] = useState(false);
 
   const handleCapture = useCallback(async () => {
-    if (!cameraRef.current || status === 'capturing' || status === 'processing') return;
+    if (!cameraRef.current || status === 'capturing' || status === 'processing' || exhausted) return;
 
     setStatus('capturing');
     setResult(null);
@@ -90,7 +92,29 @@ export function VerifyAIScanner({
       setStatus('processing');
       const verificationResult = await onCapture(photo.base64);
 
+      attemptCountRef.current++;
+
       if (verificationResult) {
+        const maxAttempts = overlay?.maxAttempts;
+        const autoApprove = overlay?.autoApproveOnExhaust ?? false;
+
+        // Check attempt exhaustion for non-compliant results
+        if (!verificationResult.is_compliant &&
+            maxAttempts != null &&
+            attemptCountRef.current >= maxAttempts) {
+          setExhausted(true);
+          if (autoApprove) {
+            const approvedResult: VerificationResult = { ...verificationResult, is_compliant: true };
+            setResult(approvedResult);
+            setStatus('success');
+            onResult?.(approvedResult);
+          } else {
+            setResult(verificationResult);
+            setStatus('error');
+          }
+          return;
+        }
+
         setResult(verificationResult);
         setStatus('success');
         onResult?.(verificationResult);
@@ -106,7 +130,7 @@ export function VerifyAIScanner({
       // Reset after a brief pause
       setTimeout(() => setStatus('idle'), 2000);
     }
-  }, [status, onCapture, onResult, onError]);
+  }, [status, exhausted, onCapture, onResult, onError, overlay?.maxAttempts, overlay?.autoApproveOnExhaust]);
 
   // Expose capture to parent via ref
   if (captureRef) {
@@ -151,6 +175,12 @@ export function VerifyAIScanner({
                     : undefined,
                 ]}
               >
+                {/* Guide overlay (e.g. bike silhouette) — rendered behind corners */}
+                {overlay.guideOverlayContent && (
+                  <View style={[StyleSheet.absoluteFill, { opacity: overlay.guideOverlayOpacity ?? 0.3 }]}>
+                    {overlay.guideOverlayContent}
+                  </View>
+                )}
                 {/* Corner brackets */}
                 <View style={[styles.corner, styles.cornerTopLeft]} />
                 <View style={[styles.corner, styles.cornerTopRight]} />
@@ -164,7 +194,9 @@ export function VerifyAIScanner({
           {status === 'processing' && (
             <View style={styles.processingOverlay}>
               <ActivityIndicator size="large" color="#fff" />
-              <Text style={styles.statusText}>Analyzing photo...</Text>
+              <Text style={styles.statusText}>
+                {overlay?.processingMessage || 'Analyzing photo...'}
+              </Text>
             </View>
           )}
 
@@ -192,28 +224,48 @@ export function VerifyAIScanner({
                       result.is_compliant ? styles.resultLabelPass : styles.resultLabelFail,
                     ]}
                   >
-                    {result.is_compliant ? 'Verified' : 'Not Verified'}
+                    {result.is_compliant
+                      ? (overlay?.successMessage || 'Verified')
+                      : (overlay?.failureMessage || 'Not Verified')}
                   </Text>
                 </View>
                 <Text style={styles.feedbackText}>{result.feedback}</Text>
               </View>
             )}
 
-            {status === 'error' && (
-              <View style={styles.resultCard}>
-                <View style={styles.resultCardHeader}>
-                  <View style={[styles.resultIconCircle, styles.resultIconError]}>
-                    <Text style={styles.resultIcon}>!</Text>
+            {status === 'error' && (() => {
+              let errorTitle: string;
+              let errorMessage: string;
+
+              if (exhausted) {
+                errorTitle = 'Attempts Exhausted';
+                errorMessage = overlay?.exhaustedMessage || 'Maximum attempts reached.';
+              } else if (overlay?.maxAttempts != null && attemptCountRef.current < overlay.maxAttempts && result && !result.is_compliant) {
+                const remaining = overlay.maxAttempts - attemptCountRef.current;
+                errorTitle = 'Not Verified';
+                const template = overlay?.retryMessage || 'Please try again. {remaining} attempts left.';
+                errorMessage = template.replace('{remaining}', String(remaining));
+              } else {
+                errorTitle = 'Something went wrong';
+                errorMessage = "We couldn't process your photo. Please try again.";
+              }
+
+              return (
+                <View style={styles.resultCard}>
+                  <View style={styles.resultCardHeader}>
+                    <View style={[styles.resultIconCircle, styles.resultIconError]}>
+                      <Text style={styles.resultIcon}>!</Text>
+                    </View>
+                    <Text style={[styles.resultLabel, styles.resultLabelError]}>
+                      {errorTitle}
+                    </Text>
                   </View>
-                  <Text style={[styles.resultLabel, styles.resultLabelError]}>
-                    Something went wrong
+                  <Text style={styles.feedbackText}>
+                    {errorMessage}
                   </Text>
                 </View>
-                <Text style={styles.feedbackText}>
-                  We couldn't process your photo. Please try again.
-                </Text>
-              </View>
-            )}
+              );
+            })()}
 
             {!showBottomCard && (
               <>

package/src/hooks/useVerifyAI.ts

@@ -1,6 +1,6 @@
-import { useRef, useMemo, useCallback, useState, useEffect } from 'react';
+import { useMemo, useCallback, useState, useEffect } from 'react';
 import { AppState, type AppStateStatus } from 'react-native';
-import { VerifyAIClient } from '../client';
+import { VerifyAIClient, VerifyAIRequestError } from '../client';
 import { OfflineQueue } from '../storage/offlineQueue';
 import type {
   VerifyAIConfig,
@@ -10,6 +10,24 @@ import type {
   VerificationListResponse,
 } from '../types';
 
+function isQueueableError(error: Error): boolean {
+  if (error instanceof VerifyAIRequestError) {
+    return error.isRetryable;
+  }
+
+  if (error.name === 'AbortError') {
+    return true;
+  }
+
+  const message = error.message.toLowerCase();
+  return (
+    message.includes('network') ||
+    message.includes('timeout') ||
+    message.includes('timed out') ||
+    message.includes('failed to fetch')
+  );
+}
+
 export interface UseVerifyAIReturn {
   /** Submit a verification. Uses offline queue if offlineMode is enabled and request fails. */
   verify: (request: VerificationRequest) => Promise<VerificationResult | null>;
@@ -104,8 +122,8 @@ export function useVerifyAI(config: VerifyAIConfig): UseVerifyAIReturn {
         const error = err instanceof Error ? err : new Error(String(err));
         setError(error);
 
-        // If offline mode, queue the request
-        if (offlineQueue) {
+        // Queue only transient failures so invalid requests are surfaced immediately.
+        if (offlineQueue && isQueueableError(error)) {
           await offlineQueue.enqueue(request);
           await refreshQueueSize();
           return null;

package/src/index.ts

@@ -23,4 +23,5 @@ export type {
   VerifyAIError,
   ScannerStatus,
   ScannerOverlayConfig,
+  PolicyConfigResponse,
 } from './types';

package/src/storage/offlineQueue.ts

@@ -1,6 +1,6 @@
 import AsyncStorage from '@react-native-async-storage/async-storage';
 import type { VerificationRequest, VerificationResult, QueueItem } from '../types';
-import { VerifyAIClient } from '../client';
+import { VerifyAIClient, VerifyAIRequestError } from '../client';
 
 const MANIFEST_KEY = '@verifyai/queue_manifest';
 const ITEM_PREFIX = '@verifyai/queue_item_';
@@ -179,9 +179,12 @@ export class OfflineQueue {
           processed++;
           await AsyncStorage.removeItem(`${ITEM_PREFIX}${id}`);
           onResult?.(item.id, result);
-        } catch {
+        } catch (err) {
+          const requestError = err instanceof VerifyAIRequestError ? err : null;
+          const shouldRetry = !requestError || requestError.isRetryable;
+
           item.retryCount++;
-          if (item.retryCount < maxRetries) {
+          if (shouldRetry && item.retryCount < maxRetries) {
             await AsyncStorage.setItem(`${ITEM_PREFIX}${id}`, JSON.stringify(item));
             remainingIds.push(id);
           } else {

package/src/types/index.ts

@@ -1,3 +1,5 @@
+import type React from 'react';
+
 export interface VerifyAIConfig {
   apiKey: string;
   baseUrl?: string;
@@ -50,7 +52,7 @@ export interface QueueItem {
 
 export interface VerifyAIError {
   error: string;
-  status: number;
+  status?: number;
   current_usage?: number;
   limit?: number;
   upgrade_url?: string;
@@ -63,4 +65,38 @@ export interface ScannerOverlayConfig {
   instructions?: string;
   showGuideFrame?: boolean;
   guideFrameAspectRatio?: number;
+  /**
+   * Optional React element rendered inside the guide frame as a semi-transparent
+   * overlay (e.g. a silhouette image to guide photo composition).
+   *
+   * The element is absolutely positioned to fill the guide frame.
+   *
+   * @example
+   * ```tsx
+   * guideOverlayContent: <Image source={require('./bike_silhouette.png')} style={{ width: '100%', height: '100%' }} resizeMode="contain" />
+   * ```
+   */
+  guideOverlayContent?: React.ReactNode;
+  /** Opacity of the guideOverlayContent (0–1). Default: 0.3. */
+  guideOverlayOpacity?: number;
+  processingMessage?: string;
+  successMessage?: string;
+  failureMessage?: string;
+  retryMessage?: string; // supports {remaining} placeholder
+  exhaustedMessage?: string;
+  maxAttempts?: number;
+  autoApproveOnExhaust?: boolean;
+}
+
+export interface PolicyConfigResponse {
+  maxAttempts: number;
+  autoApproveOnExhaust: boolean;
+  uiCopy: Record<string, string | undefined>;
+  categories: Array<{
+    id: string;
+    label: string;
+    color: string;
+    isCompliant: boolean;
+    description?: string;
+  }>;
 }