@switchlabs/verify-ai-react-native 1.1.2 → 2.3.0

package/README.md

@@ -4,18 +4,20 @@ React Native SDK for Verify AI photo verification.
 
 ## Install
 
-Expo-managed apps:
+Core SDK (client, hooks, types):
 
 ```bash
-npx expo install @switchlabs/verify-ai-react-native expo-camera expo-image-manipulator @react-native-async-storage/async-storage
+npm install @switchlabs/verify-ai-react-native
 ```
 
-React Native CLI:
+With built-in camera scanner:
 
 ```bash
-npm install @switchlabs/verify-ai-react-native expo-camera expo-image-manipulator @react-native-async-storage/async-storage
+npm install @switchlabs/verify-ai-react-native expo-camera expo-image-manipulator
 ```
 
+For offline queue support, also install `@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.
@@ -44,18 +46,18 @@ function ParkingScreen() {
 
 ## Scanner Component
 
+The scanner is exported from a separate subpath to avoid pulling in `expo-camera` for consumers that only need the client.
+
 ```tsx
-import { useVerifyAI, VerifyAIScanner } from '@switchlabs/verify-ai-react-native';
+import { useVerifyAI } from '@switchlabs/verify-ai-react-native';
+import { VerifyAIScanner } from '@switchlabs/verify-ai-react-native/scanner';
 
 function ScannerScreen() {
-  const { verifyMultipart } = useVerifyAI({
-    apiKey: 'vai_your_api_key',
-    enableOnDeviceML: true,
-  });
+  const { verify } = useVerifyAI({ apiKey: 'vai_your_api_key' });
   return (
     <VerifyAIScanner
-      onCapture={(imageUri) =>
-        verifyMultipart({ imageUri, policy: 'scooter_parking' })
+      onCapture={(base64) =>
+        verify({ image: base64, policy: 'scooter_parking' })
       }
       onResult={(result) => console.log(result.is_compliant ? 'PASS' : 'FAIL')}
     />
@@ -63,12 +65,10 @@ function ScannerScreen() {
 }
 ```
 
-`verifyMultipart()` is the recommended path for live camera captures. The
-built-in offline queue currently replays base64 `verify()` requests only; raw
-multipart uploads are not persisted automatically.
-
 ## Offline Mode
 
+Requires `@react-native-async-storage/async-storage` to be installed.
+
 Set `offlineMode: true` to queue transient failures (network, timeout, 429, 5xx) and retry later.
 
 ```tsx

package/lib/client/index.d.ts

@@ -38,9 +38,6 @@ export declare class VerifyAIClient {
      * 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

package/lib/client/index.js

@@ -1,6 +1,24 @@
 import { TelemetryReporter } from '../telemetry/TelemetryReporter';
+import { SDK_VERSION } from '../version';
 const DEFAULT_BASE_URL = 'https://verify.switchlabs.dev/api/v1';
 const DEFAULT_TIMEOUT = 30000;
+const VEHICLE_TYPE_LABELS = {
+    scooter: 'Scooter',
+    'e-bike': 'E-Bike',
+    ebike: 'E-Bike',
+    bike: 'Bike',
+    moped: 'Moped',
+    car: 'Car',
+};
+/** Auto-inject sdkVersion and vehicleTypeLabel into metadata. */
+function enrichMetadata(metadata) {
+    const enriched = { ...metadata, sdkVersion: SDK_VERSION };
+    const vehicleType = enriched.vehicleType;
+    if (typeof vehicleType === 'string' && !enriched.vehicleTypeLabel) {
+        enriched.vehicleTypeLabel = VEHICLE_TYPE_LABELS[vehicleType.toLowerCase()] || vehicleType;
+    }
+    return enriched;
+}
 export class VerifyAIClient {
     constructor(config) {
         if (!config.apiKey) {
@@ -142,19 +160,17 @@ export class VerifyAIClient {
         if (options?.idempotencyKey) {
             headers['Idempotency-Key'] = options.idempotencyKey;
         }
+        const enrichedRequest = { ...request, metadata: enrichMetadata(request.metadata) };
         return this.request('/verify', {
             method: 'POST',
             headers,
-            body: JSON.stringify(request),
+            body: JSON.stringify(enrichedRequest),
         });
     }
     /**
      * 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
@@ -168,9 +184,7 @@ export class VerifyAIClient {
             name: 'photo.jpg',
         });
         formData.append('policy', request.policy);
-        if (request.metadata) {
-            formData.append('metadata', JSON.stringify(request.metadata));
-        }
+        formData.append('metadata', JSON.stringify(enrichMetadata(request.metadata)));
         if (request.provider) {
             formData.append('provider', request.provider);
         }
@@ -181,11 +195,37 @@ export class VerifyAIClient {
         if (options?.idempotencyKey) {
             headers['Idempotency-Key'] = options.idempotencyKey;
         }
-        return this.executeRequest('/verify', {
-            method: 'POST',
-            headers,
-            body: formData,
-        });
+        try {
+            return await this.executeRequest('/verify', {
+                method: 'POST',
+                headers,
+                body: formData,
+            });
+        }
+        catch (error) {
+            // Blank 500 means the server crashed during multipart parsing (e.g.
+            // Vercel function crash). Retry as JSON/base64 with a fresh request
+            // — the crashed request may have partially recorded the idempotency key.
+            if (error instanceof VerifyAIRequestError && error.status >= 500 && error.isServerError) {
+                try {
+                    const { Buffer } = await import('buffer');
+                    const fileResponse = await fetch(request.imageUri);
+                    const arrayBuffer = await fileResponse.arrayBuffer();
+                    const base64 = Buffer.from(arrayBuffer).toString('base64');
+                    return this.verify({
+                        image: base64,
+                        policy: request.policy,
+                        metadata: request.metadata,
+                        provider: request.provider,
+                    });
+                }
+                catch {
+                    // If the retry itself fails, throw the original error
+                    throw error;
+                }
+            }
+            throw error;
+        }
     }
     /**
      * List past verifications with optional filters.

package/lib/components/VerifyAIScanner.js

@@ -312,12 +312,12 @@ 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", 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 }
-                                    : 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] })] }) })), 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: [
+    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 && (_jsxs(View, { style: styles.guideContainer, children: [_jsxs(View, { style: [
+                                    styles.guideFrame,
+                                    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: [
                                                     styles.resultIconCircle,
                                                     result.is_compliant ? styles.resultIconPass : styles.resultIconFail,
                                                 ], children: _jsx(Text, { style: styles.resultIcon, children: result.is_compliant ? '\u2713' : '\u2717' }) }), _jsx(Text, { style: [
@@ -334,9 +334,16 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
                                 }
                                 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));
+                                    errorTitle = overlay?.failureMessage || 'Not Verified';
+                                    if (overlay?.retryMessage) {
+                                        errorMessage = overlay.retryMessage.replace('{remaining}', String(remaining));
+                                    }
+                                    else {
+                                        // Show actual API feedback with retry count (matches Flutter)
+                                        const feedback = result.feedback?.trim();
+                                        const retryInfo = `${remaining} attempt${remaining === 1 ? '' : 's'} remaining.`;
+                                        errorMessage = feedback ? `${feedback}\n\n${retryInfo}` : `Please try again. ${retryInfo}`;
+                                    }
                                 }
                                 else {
                                     const display = getErrorDisplay(lastError, overlay?.showTechnicalErrorDetails);
@@ -382,6 +389,14 @@ const styles = StyleSheet.create({
         alignItems: 'center',
         paddingHorizontal: 40,
     },
+    guideCaptionText: {
+        color: 'rgba(255,255,255,0.8)',
+        fontSize: 13,
+        fontWeight: '500',
+        textAlign: 'center',
+        marginTop: 12,
+        lineHeight: 18,
+    },
     guideFrame: {
         width: '100%',
         aspectRatio: 4 / 3,

package/lib/index.d.ts

@@ -1,8 +1,6 @@
 export { VerifyAIClient, VerifyAIRequestError } from './client';
 export { useVerifyAI } from './hooks/useVerifyAI';
 export type { UseVerifyAIReturn, UseVerifyAIConfig } from './hooks/useVerifyAI';
-export { VerifyAIScanner } from './components/VerifyAIScanner';
-export type { VerifyAIScannerProps } from './components/VerifyAIScanner';
 export { TelemetryReporter } from './telemetry/TelemetryReporter';
 export { TelemetryContext } from './telemetry/TelemetryContext';
 export { OfflineQueue } from './storage/offlineQueue';

package/lib/index.js

@@ -2,8 +2,6 @@
 export { VerifyAIClient, VerifyAIRequestError } from './client';
 // Hooks
 export { useVerifyAI } from './hooks/useVerifyAI';
-// Components
-export { VerifyAIScanner } from './components/VerifyAIScanner';
 // Telemetry
 export { TelemetryReporter } from './telemetry/TelemetryReporter';
 export { TelemetryContext } from './telemetry/TelemetryContext';

package/lib/scanner.d.ts

@@ -0,0 +1,2 @@
+export { VerifyAIScanner } from './components/VerifyAIScanner';
+export type { VerifyAIScannerProps } from './components/VerifyAIScanner';

package/lib/scanner.js

@@ -0,0 +1 @@
+export { VerifyAIScanner } from './components/VerifyAIScanner';

package/lib/storage/offlineQueue.js

@@ -1,5 +1,12 @@
-import AsyncStorage from '@react-native-async-storage/async-storage';
 import { VerifyAIRequestError } from '../client';
+let _storage = null;
+async function getStorage() {
+    if (!_storage) {
+        const mod = await import('@react-native-async-storage/async-storage');
+        _storage = mod.default;
+    }
+    return _storage;
+}
 const MANIFEST_KEY = '@verifyai/queue_manifest';
 const ITEM_PREFIX = '@verifyai/queue_item_';
 const LEGACY_KEY = '@verifyai/offline_queue';
@@ -17,13 +24,13 @@ export class OfflineQueue {
         if (this.migrated)
             return;
         this.migrated = true;
-        const legacy = await AsyncStorage.getItem(LEGACY_KEY);
+        const legacy = await (await getStorage()).getItem(LEGACY_KEY);
         if (!legacy)
             return;
         try {
             const items = JSON.parse(legacy);
             if (!Array.isArray(items) || items.length === 0) {
-                await AsyncStorage.removeItem(LEGACY_KEY);
+                await (await getStorage()).removeItem(LEGACY_KEY);
                 return;
             }
             const ids = [];
@@ -32,24 +39,25 @@ export class OfflineQueue {
                 ids.push(item.id);
                 pairs.push([`${ITEM_PREFIX}${item.id}`, JSON.stringify(item)]);
             }
-            await AsyncStorage.multiSet([
+            const storage = await getStorage();
+            await storage.multiSet([
                 [MANIFEST_KEY, JSON.stringify(ids)],
                 ...pairs,
             ]);
-            await AsyncStorage.removeItem(LEGACY_KEY);
+            await storage.removeItem(LEGACY_KEY);
         }
         catch {
             // If migration fails, remove corrupt legacy data
-            await AsyncStorage.removeItem(LEGACY_KEY);
+            await (await getStorage()).removeItem(LEGACY_KEY);
         }
     }
     async getManifest() {
         await this.migrateIfNeeded();
-        const raw = await AsyncStorage.getItem(MANIFEST_KEY);
+        const raw = await (await getStorage()).getItem(MANIFEST_KEY);
         return raw ? JSON.parse(raw) : [];
     }
     async setManifest(ids) {
-        await AsyncStorage.setItem(MANIFEST_KEY, JSON.stringify(ids));
+        await (await getStorage()).setItem(MANIFEST_KEY, JSON.stringify(ids));
     }
     /**
      * Add a verification request to the offline queue.
@@ -64,7 +72,7 @@ export class OfflineQueue {
         };
         const ids = await this.getManifest();
         ids.push(item.id);
-        await AsyncStorage.setItem(`${ITEM_PREFIX}${item.id}`, JSON.stringify(item));
+        await (await getStorage()).setItem(`${ITEM_PREFIX}${item.id}`, JSON.stringify(item));
         await this.setManifest(ids);
         return item.id;
     }
@@ -76,7 +84,7 @@ export class OfflineQueue {
         if (ids.length === 0)
             return [];
         const keys = ids.map((id) => `${ITEM_PREFIX}${id}`);
-        const pairs = await AsyncStorage.multiGet(keys);
+        const pairs = await (await getStorage()).multiGet(keys);
         const items = [];
         for (const [, value] of pairs) {
             if (value) {
@@ -104,7 +112,7 @@ export class OfflineQueue {
         const ids = await this.getManifest();
         const filtered = ids.filter((i) => i !== id);
         await this.setManifest(filtered);
-        await AsyncStorage.removeItem(`${ITEM_PREFIX}${id}`);
+        await (await getStorage()).removeItem(`${ITEM_PREFIX}${id}`);
     }
     /**
      * Clear all items from the queue.
@@ -113,10 +121,10 @@ export class OfflineQueue {
         const ids = await this.getManifest();
         if (ids.length > 0) {
             const keys = ids.map((id) => `${ITEM_PREFIX}${id}`);
-            await AsyncStorage.multiRemove([MANIFEST_KEY, ...keys]);
+            await (await getStorage()).multiRemove([MANIFEST_KEY, ...keys]);
         }
         else {
-            await AsyncStorage.removeItem(MANIFEST_KEY);
+            await (await getStorage()).removeItem(MANIFEST_KEY);
         }
     }
     /**
@@ -140,7 +148,7 @@ export class OfflineQueue {
         try {
             const ids = await this.getManifest();
             for (const id of ids) {
-                const raw = await AsyncStorage.getItem(`${ITEM_PREFIX}${id}`);
+                const raw = await (await getStorage()).getItem(`${ITEM_PREFIX}${id}`);
                 if (!raw)
                     continue;
                 let item;
@@ -149,13 +157,13 @@ export class OfflineQueue {
                 }
                 catch {
                     // Remove corrupt item
-                    await AsyncStorage.removeItem(`${ITEM_PREFIX}${id}`);
+                    await (await getStorage()).removeItem(`${ITEM_PREFIX}${id}`);
                     continue;
                 }
                 try {
                     const result = await this.client.verify(item.request, { idempotencyKey: item.id });
                     processed++;
-                    await AsyncStorage.removeItem(`${ITEM_PREFIX}${id}`);
+                    await (await getStorage()).removeItem(`${ITEM_PREFIX}${id}`);
                     onResult?.(item.id, result);
                 }
                 catch (err) {
@@ -163,12 +171,12 @@ export class OfflineQueue {
                     const shouldRetry = !requestError || requestError.isRetryable;
                     item.retryCount++;
                     if (shouldRetry && item.retryCount < maxRetries) {
-                        await AsyncStorage.setItem(`${ITEM_PREFIX}${id}`, JSON.stringify(item));
+                        await (await getStorage()).setItem(`${ITEM_PREFIX}${id}`, JSON.stringify(item));
                         remainingIds.push(id);
                     }
                     else {
                         failed++;
-                        await AsyncStorage.removeItem(`${ITEM_PREFIX}${id}`);
+                        await (await getStorage()).removeItem(`${ITEM_PREFIX}${id}`);
                     }
                 }
             }

package/lib/types/index.d.ts

@@ -30,6 +30,8 @@ export interface VerificationResult {
     feedback: string;
     metadata: Record<string, unknown>;
     image_url: string | null;
+    /** Classification category (e.g. good_parking, no_vehicle, poor_photo). */
+    category?: string;
 }
 export interface VerificationListResponse {
     data: VerificationResult[];
@@ -87,6 +89,8 @@ export interface ScannerOverlayConfig {
     guideOverlayContent?: React.ReactNode;
     /** Opacity of the guideOverlayContent (0–1). Default: 0.3. */
     guideOverlayOpacity?: number;
+    /** Caption text shown directly below the guide frame. */
+    guideCaption?: string;
     processingMessage?: string;
     successMessage?: string;
     failureMessage?: string;

package/lib/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "1.1.1";
+export declare const SDK_VERSION = "2.3.0";

package/lib/version.js

@@ -1 +1 @@
-export const SDK_VERSION = '1.1.1';
+export const SDK_VERSION = '2.3.0';

package/package.json

@@ -1,9 +1,19 @@
 {
   "name": "@switchlabs/verify-ai-react-native",
-  "version": "1.1.2",
+  "version": "2.3.0",
   "description": "React Native SDK for Verify AI - photo verification with AI vision processing",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./scanner": {
+      "types": "./lib/scanner.d.ts",
+      "default": "./lib/scanner.js"
+    }
+  },
   "files": [
     "src",
     "lib"

package/src/client/index.ts

@@ -10,10 +10,30 @@ import type {
   PolicyConfigResponse,
 } from '../types';
 import { TelemetryReporter } from '../telemetry/TelemetryReporter';
+import { SDK_VERSION } from '../version';
 
 const DEFAULT_BASE_URL = 'https://verify.switchlabs.dev/api/v1';
 const DEFAULT_TIMEOUT = 30000;
 
+const VEHICLE_TYPE_LABELS: Record<string, string> = {
+  scooter: 'Scooter',
+  'e-bike': 'E-Bike',
+  ebike: 'E-Bike',
+  bike: 'Bike',
+  moped: 'Moped',
+  car: 'Car',
+};
+
+/** Auto-inject sdkVersion and vehicleTypeLabel into metadata. */
+function enrichMetadata(metadata?: Record<string, unknown>): Record<string, unknown> {
+  const enriched: Record<string, unknown> = { ...metadata, sdkVersion: SDK_VERSION };
+  const vehicleType = enriched.vehicleType;
+  if (typeof vehicleType === 'string' && !enriched.vehicleTypeLabel) {
+    enriched.vehicleTypeLabel = VEHICLE_TYPE_LABELS[vehicleType.toLowerCase()] || vehicleType;
+  }
+  return enriched;
+}
+
 interface RequestContext {
   path: string;
   url: string;
@@ -204,10 +224,11 @@ export class VerifyAIClient {
     if (options?.idempotencyKey) {
       headers['Idempotency-Key'] = options.idempotencyKey;
     }
+    const enrichedRequest = { ...request, metadata: enrichMetadata(request.metadata) };
     return this.request<VerificationResult>('/verify', {
       method: 'POST',
       headers,
-      body: JSON.stringify(request),
+      body: JSON.stringify(enrichedRequest),
     });
   }
 
@@ -215,9 +236,6 @@ export class VerifyAIClient {
    * 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
@@ -231,9 +249,7 @@ export class VerifyAIClient {
       name: 'photo.jpg',
     } as unknown as Blob);
     formData.append('policy', request.policy);
-    if (request.metadata) {
-      formData.append('metadata', JSON.stringify(request.metadata));
-    }
+    formData.append('metadata', JSON.stringify(enrichMetadata(request.metadata)));
     if (request.provider) {
       formData.append('provider', request.provider);
     }
@@ -246,11 +262,35 @@ export class VerifyAIClient {
       headers['Idempotency-Key'] = options.idempotencyKey;
     }
 
-    return this.executeRequest<VerificationResult>('/verify', {
-      method: 'POST',
-      headers,
-      body: formData,
-    });
+    try {
+      return await this.executeRequest<VerificationResult>('/verify', {
+        method: 'POST',
+        headers,
+        body: formData,
+      });
+    } catch (error) {
+      // Blank 500 means the server crashed during multipart parsing (e.g.
+      // Vercel function crash). Retry as JSON/base64 with a fresh request
+      // — the crashed request may have partially recorded the idempotency key.
+      if (error instanceof VerifyAIRequestError && error.status >= 500 && error.isServerError) {
+        try {
+          const { Buffer } = await import('buffer');
+          const fileResponse = await fetch(request.imageUri);
+          const arrayBuffer = await fileResponse.arrayBuffer();
+          const base64 = Buffer.from(arrayBuffer).toString('base64');
+          return this.verify({
+            image: base64,
+            policy: request.policy,
+            metadata: request.metadata,
+            provider: request.provider,
+          });
+        } catch {
+          // If the retry itself fails, throw the original error
+          throw error;
+        }
+      }
+      throw error;
+    }
   }
 
   /**

package/src/components/VerifyAIScanner.tsx

@@ -450,6 +450,9 @@ export function VerifyAIScanner({
                 <View style={[styles.corner, styles.cornerBottomLeft]} />
                 <View style={[styles.corner, styles.cornerBottomRight]} />
               </View>
+              {overlay.guideCaption && (
+                <Text style={styles.guideCaptionText}>{overlay.guideCaption}</Text>
+              )}
             </View>
           )}
 
@@ -505,9 +508,15 @@ export function VerifyAIScanner({
                 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));
+                errorTitle = overlay?.failureMessage || 'Not Verified';
+                if (overlay?.retryMessage) {
+                  errorMessage = overlay.retryMessage.replace('{remaining}', String(remaining));
+                } else {
+                  // Show actual API feedback with retry count (matches Flutter)
+                  const feedback = result.feedback?.trim();
+                  const retryInfo = `${remaining} attempt${remaining === 1 ? '' : 's'} remaining.`;
+                  errorMessage = feedback ? `${feedback}\n\n${retryInfo}` : `Please try again. ${retryInfo}`;
+                }
               } else {
                 const display = getErrorDisplay(lastError, overlay?.showTechnicalErrorDetails);
                 errorTitle = display.title;
@@ -595,6 +604,14 @@ const styles = StyleSheet.create({
     alignItems: 'center',
     paddingHorizontal: 40,
   },
+  guideCaptionText: {
+    color: 'rgba(255,255,255,0.8)',
+    fontSize: 13,
+    fontWeight: '500',
+    textAlign: 'center' as const,
+    marginTop: 12,
+    lineHeight: 18,
+  },
   guideFrame: {
     width: '100%',
     aspectRatio: 4 / 3,

package/src/index.ts

@@ -5,10 +5,6 @@ export { VerifyAIClient, VerifyAIRequestError } from './client';
 export { useVerifyAI } from './hooks/useVerifyAI';
 export type { UseVerifyAIReturn, UseVerifyAIConfig } from './hooks/useVerifyAI';
 
-// Components
-export { VerifyAIScanner } from './components/VerifyAIScanner';
-export type { VerifyAIScannerProps } from './components/VerifyAIScanner';
-
 // Telemetry
 export { TelemetryReporter } from './telemetry/TelemetryReporter';
 export { TelemetryContext } from './telemetry/TelemetryContext';

package/src/scanner.ts

@@ -0,0 +1,2 @@
+export { VerifyAIScanner } from './components/VerifyAIScanner';
+export type { VerifyAIScannerProps } from './components/VerifyAIScanner';

package/src/storage/offlineQueue.ts

@@ -1,7 +1,15 @@
-import AsyncStorage from '@react-native-async-storage/async-storage';
 import type { VerificationRequest, VerificationResult, QueueItem } from '../types';
 import { VerifyAIClient, VerifyAIRequestError } from '../client';
 
+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 MANIFEST_KEY = '@verifyai/queue_manifest';
 const ITEM_PREFIX = '@verifyai/queue_item_';
 const LEGACY_KEY = '@verifyai/offline_queue';
@@ -23,13 +31,13 @@ export class OfflineQueue {
     if (this.migrated) return;
     this.migrated = true;
 
-    const legacy = await AsyncStorage.getItem(LEGACY_KEY);
+    const legacy = await (await getStorage()).getItem(LEGACY_KEY);
     if (!legacy) return;
 
     try {
       const items: QueueItem[] = JSON.parse(legacy);
       if (!Array.isArray(items) || items.length === 0) {
-        await AsyncStorage.removeItem(LEGACY_KEY);
+        await (await getStorage()).removeItem(LEGACY_KEY);
         return;
       }
 
@@ -40,25 +48,26 @@ export class OfflineQueue {
         pairs.push([`${ITEM_PREFIX}${item.id}`, JSON.stringify(item)]);
       }
 
-      await AsyncStorage.multiSet([
+      const storage = await getStorage();
+      await storage.multiSet([
         [MANIFEST_KEY, JSON.stringify(ids)],
         ...pairs,
       ]);
-      await AsyncStorage.removeItem(LEGACY_KEY);
+      await storage.removeItem(LEGACY_KEY);
     } catch {
       // If migration fails, remove corrupt legacy data
-      await AsyncStorage.removeItem(LEGACY_KEY);
+      await (await getStorage()).removeItem(LEGACY_KEY);
     }
   }
 
   private async getManifest(): Promise<string[]> {
     await this.migrateIfNeeded();
-    const raw = await AsyncStorage.getItem(MANIFEST_KEY);
+    const raw = await (await getStorage()).getItem(MANIFEST_KEY);
     return raw ? JSON.parse(raw) : [];
   }
 
   private async setManifest(ids: string[]): Promise<void> {
-    await AsyncStorage.setItem(MANIFEST_KEY, JSON.stringify(ids));
+    await (await getStorage()).setItem(MANIFEST_KEY, JSON.stringify(ids));
   }
 
   /**
@@ -76,7 +85,7 @@ export class OfflineQueue {
     const ids = await this.getManifest();
     ids.push(item.id);
 
-    await AsyncStorage.setItem(`${ITEM_PREFIX}${item.id}`, JSON.stringify(item));
+    await (await getStorage()).setItem(`${ITEM_PREFIX}${item.id}`, JSON.stringify(item));
     await this.setManifest(ids);
     return item.id;
   }
@@ -89,7 +98,7 @@ export class OfflineQueue {
     if (ids.length === 0) return [];
 
     const keys = ids.map((id) => `${ITEM_PREFIX}${id}`);
-    const pairs = await AsyncStorage.multiGet(keys);
+    const pairs = await (await getStorage()).multiGet(keys);
 
     const items: QueueItem[] = [];
     for (const [, value] of pairs) {
@@ -119,7 +128,7 @@ export class OfflineQueue {
     const ids = await this.getManifest();
     const filtered = ids.filter((i) => i !== id);
     await this.setManifest(filtered);
-    await AsyncStorage.removeItem(`${ITEM_PREFIX}${id}`);
+    await (await getStorage()).removeItem(`${ITEM_PREFIX}${id}`);
   }
 
   /**
@@ -129,9 +138,9 @@ export class OfflineQueue {
     const ids = await this.getManifest();
     if (ids.length > 0) {
       const keys = ids.map((id) => `${ITEM_PREFIX}${id}`);
-      await AsyncStorage.multiRemove([MANIFEST_KEY, ...keys]);
+      await (await getStorage()).multiRemove([MANIFEST_KEY, ...keys]);
     } else {
-      await AsyncStorage.removeItem(MANIFEST_KEY);
+      await (await getStorage()).removeItem(MANIFEST_KEY);
     }
   }
 
@@ -162,7 +171,7 @@ export class OfflineQueue {
       const ids = await this.getManifest();
 
       for (const id of ids) {
-        const raw = await AsyncStorage.getItem(`${ITEM_PREFIX}${id}`);
+        const raw = await (await getStorage()).getItem(`${ITEM_PREFIX}${id}`);
         if (!raw) continue;
 
         let item: QueueItem;
@@ -170,14 +179,14 @@ export class OfflineQueue {
           item = JSON.parse(raw);
         } catch {
           // Remove corrupt item
-          await AsyncStorage.removeItem(`${ITEM_PREFIX}${id}`);
+          await (await getStorage()).removeItem(`${ITEM_PREFIX}${id}`);
           continue;
         }
 
         try {
           const result = await this.client.verify(item.request, { idempotencyKey: item.id });
           processed++;
-          await AsyncStorage.removeItem(`${ITEM_PREFIX}${id}`);
+          await (await getStorage()).removeItem(`${ITEM_PREFIX}${id}`);
           onResult?.(item.id, result);
         } catch (err) {
           const requestError = err instanceof VerifyAIRequestError ? err : null;
@@ -185,11 +194,11 @@ export class OfflineQueue {
 
           item.retryCount++;
           if (shouldRetry && item.retryCount < maxRetries) {
-            await AsyncStorage.setItem(`${ITEM_PREFIX}${id}`, JSON.stringify(item));
+            await (await getStorage()).setItem(`${ITEM_PREFIX}${id}`, JSON.stringify(item));
             remainingIds.push(id);
           } else {
             failed++;
-            await AsyncStorage.removeItem(`${ITEM_PREFIX}${id}`);
+            await (await getStorage()).removeItem(`${ITEM_PREFIX}${id}`);
           }
         }
       }

package/src/types/index.ts

@@ -34,6 +34,8 @@ export interface VerificationResult {
   feedback: string;
   metadata: Record<string, unknown>;
   image_url: string | null;
+  /** Classification category (e.g. good_parking, no_vehicle, poor_photo). */
+  category?: string;
 }
 
 export interface VerificationListResponse {
@@ -98,6 +100,8 @@ export interface ScannerOverlayConfig {
   guideOverlayContent?: React.ReactNode;
   /** Opacity of the guideOverlayContent (0–1). Default: 0.3. */
   guideOverlayOpacity?: number;
+  /** Caption text shown directly below the guide frame. */
+  guideCaption?: string;
   processingMessage?: string;
   successMessage?: string;
   failureMessage?: string;

package/src/version.ts

@@ -1 +1 @@
-export const SDK_VERSION = '1.1.1';
+export const SDK_VERSION = '2.3.0';