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

package/lib/telemetry/TelemetryReporter.d.ts

@@ -0,0 +1,24 @@
+export declare class TelemetryReporter {
+    private buffer;
+    private flushTimer;
+    private sessionId;
+    private baseUrl;
+    private apiKey;
+    private disposed;
+    private flushing;
+    constructor(apiKey: string, baseUrl: string);
+    /** Track an error event. Fire-and-forget — never throws. */
+    track(eventType: string, opts?: {
+        component?: string;
+        error?: unknown;
+        errorCode?: string;
+        metadata?: Record<string, string | number>;
+    }): void;
+    /** Flush all buffered events immediately. Returns a promise but never rejects. */
+    flush(): Promise<void>;
+    /** Dispose — flush remaining events and stop timers. */
+    dispose(): void;
+    private scheduleFlush;
+    private flushNow;
+    private clearFlushTimer;
+}

package/lib/telemetry/TelemetryReporter.js

@@ -0,0 +1,141 @@
+import { Platform } from 'react-native';
+import { SDK_VERSION } from '../version';
+/** Event types that flush immediately (critical init failures). */
+const CRITICAL_EVENTS = new Set([
+    'camera_init_failure',
+    'camera_preview_timeout',
+    'camera_permission_denied',
+]);
+export class TelemetryReporter {
+    constructor(apiKey, baseUrl) {
+        this.buffer = new Map();
+        this.flushTimer = null;
+        this.disposed = false;
+        this.flushing = false;
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+        this.sessionId = Math.random().toString(36).slice(2) + Date.now().toString(36);
+    }
+    /** Track an error event. Fire-and-forget — never throws. */
+    track(eventType, opts = {}) {
+        if (this.disposed)
+            return;
+        try {
+            const now = new Date().toISOString();
+            const errorObj = opts.error instanceof Error ? opts.error : null;
+            const errorMessage = errorObj?.message
+                ?? (typeof opts.error === 'string' ? opts.error : undefined);
+            const dedupKey = `${eventType}|${errorMessage ?? ''}|${opts.component ?? ''}`;
+            const existing = this.buffer.get(dedupKey);
+            if (existing) {
+                existing.event_count++;
+                existing.last_occurred_at = now;
+                // If the new occurrence is critical, flush immediately
+                if (CRITICAL_EVENTS.has(eventType)) {
+                    this.flushNow();
+                }
+                return;
+            }
+            const event = {
+                event_type: eventType,
+                component: opts.component,
+                error_message: errorMessage?.slice(0, 1000),
+                error_stack: errorObj?.stack?.slice(0, 2000),
+                error_code: opts.errorCode,
+                metadata: opts.metadata,
+                sdk_platform: Platform.OS,
+                sdk_version: SDK_VERSION,
+                os_name: Platform.OS,
+                os_version: String(Platform.Version),
+                session_id: this.sessionId,
+                event_count: 1,
+                first_occurred_at: now,
+                last_occurred_at: now,
+            };
+            this.buffer.set(dedupKey, event);
+            if (CRITICAL_EVENTS.has(eventType)) {
+                this.flushNow();
+            }
+            else {
+                this.scheduleFlush();
+            }
+        }
+        catch {
+            // Never throw from telemetry
+        }
+    }
+    /** Flush all buffered events immediately. Returns a promise but never rejects. */
+    async flush() {
+        if (this.buffer.size === 0 || this.flushing)
+            return;
+        this.flushing = true;
+        const bufferedEntries = Array.from(this.buffer.entries());
+        const events = bufferedEntries.map(([, event]) => event);
+        this.buffer.clear();
+        this.clearFlushTimer();
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 10000);
+        try {
+            const response = await fetch(`${this.baseUrl}/telemetry`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-API-Key': this.apiKey,
+                },
+                body: JSON.stringify({ events }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                throw new Error(`Telemetry request failed with status ${response.status}`);
+            }
+        }
+        catch {
+            for (const [dedupKey, event] of bufferedEntries) {
+                const existing = this.buffer.get(dedupKey);
+                if (existing) {
+                    existing.event_count += event.event_count;
+                    existing.first_occurred_at = existing.first_occurred_at < event.first_occurred_at
+                        ? existing.first_occurred_at
+                        : event.first_occurred_at;
+                    existing.last_occurred_at = existing.last_occurred_at > event.last_occurred_at
+                        ? existing.last_occurred_at
+                        : event.last_occurred_at;
+                }
+                else {
+                    this.buffer.set(dedupKey, event);
+                }
+            }
+        }
+        finally {
+            clearTimeout(timeout);
+            this.flushing = false;
+            if (this.buffer.size > 0 && !this.disposed) {
+                this.scheduleFlush();
+            }
+        }
+    }
+    /** Dispose — flush remaining events and stop timers. */
+    dispose() {
+        this.disposed = true;
+        this.clearFlushTimer();
+        this.flush();
+    }
+    scheduleFlush() {
+        if (this.flushTimer)
+            return;
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            this.flush();
+        }, 5000);
+    }
+    flushNow() {
+        this.clearFlushTimer();
+        this.flush();
+    }
+    clearFlushTimer() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+    }
+}

package/lib/types/index.d.ts

@@ -4,6 +4,8 @@ export interface VerifyAIConfig {
     baseUrl?: string;
     timeout?: number;
     offlineMode?: boolean;
+    /** Enable SDK telemetry reporting for client-side errors. Default: true. */
+    telemetry?: boolean;
 }
 export interface VerificationRequest {
     image: string;
@@ -11,6 +13,12 @@ export interface VerificationRequest {
     metadata?: Record<string, unknown>;
     provider?: 'openai' | 'anthropic' | 'gemini';
 }
+export interface MultipartVerificationRequest {
+    imageUri: string;
+    policy: string;
+    metadata?: Record<string, unknown>;
+    provider?: 'openai' | 'anthropic' | 'gemini';
+}
 export interface VerificationResult {
     id: string;
     created_at: string;
@@ -37,6 +45,10 @@ export interface VerificationListParams {
     start_date?: string;
     end_date?: string;
 }
+export interface VerifyOptions {
+    /** Idempotency key to prevent duplicate verifications on retry. */
+    idempotencyKey?: string;
+}
 export interface QueueItem {
     id: string;
     request: VerificationRequest;
@@ -49,6 +61,11 @@ export interface VerifyAIError {
     current_usage?: number;
     limit?: number;
     upgrade_url?: string;
+    request_id?: string;
+    code?: string;
+    path?: string;
+    url?: string;
+    method?: string;
 }
 export type ScannerStatus = 'idle' | 'capturing' | 'processing' | 'success' | 'error';
 export interface ScannerOverlayConfig {
@@ -77,6 +94,7 @@ export interface ScannerOverlayConfig {
     exhaustedMessage?: string;
     maxAttempts?: number;
     autoApproveOnExhaust?: boolean;
+    showTechnicalErrorDetails?: boolean;
 }
 export interface PolicyConfigResponse {
     maxAttempts: number;

package/lib/version.d.ts

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

package/lib/version.js

@@ -0,0 +1 @@
+export const SDK_VERSION = '1.1.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@switchlabs/verify-ai-react-native",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "React Native SDK for Verify AI - photo verification with AI vision processing",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -23,26 +23,47 @@
   ],
   "author": "Switch Labs",
   "license": "MIT",
+  "dependencies": {
+    "@noble/hashes": "^1.8.0",
+    "buffer": "^6.0.3",
+    "jpeg-js": "^0.4.4"
+  },
   "peerDependencies": {
     "react": ">=18.0.0",
     "react-native": ">=0.72.0",
     "expo-camera": ">=15.0.0",
-    "@react-native-async-storage/async-storage": ">=1.19.0"
+    "expo-image-manipulator": ">=12.0.0",
+    "@react-native-async-storage/async-storage": ">=1.19.0",
+    "react-native-fast-tflite": ">=1.0.0",
+    "expo-file-system": ">=17.0.0"
   },
   "peerDependenciesMeta": {
     "expo-camera": {
       "optional": true
     },
+    "expo-image-manipulator": {
+      "optional": true
+    },
     "@react-native-async-storage/async-storage": {
       "optional": true
+    },
+    "react-native-fast-tflite": {
+      "optional": true
+    },
+    "expo-file-system": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@types/jpeg-js": "^0.3.7",
     "@react-native-async-storage/async-storage": "^2.1.0",
     "@types/react": "^18.2.0",
     "expo-camera": "^16.0.0",
+    "expo-file-system": "^18.0.12",
+    "expo-image-manipulator": "^13.0.0",
     "react": "^18.2.0",
     "react-native": "^0.76.0",
+    "react-native-fast-tflite": "^1.6.1",
     "typescript": "^5.5.0"
   }
 }

package/src/client/index.ts

@@ -1,20 +1,30 @@
 import type {
   VerifyAIConfig,
   VerificationRequest,
+  MultipartVerificationRequest,
   VerificationResult,
   VerificationListResponse,
   VerificationListParams,
   VerifyAIError,
+  VerifyOptions,
   PolicyConfigResponse,
 } from '../types';
+import { TelemetryReporter } from '../telemetry/TelemetryReporter';
 
 const DEFAULT_BASE_URL = 'https://verify.switchlabs.dev/api/v1';
 const DEFAULT_TIMEOUT = 30000;
 
+interface RequestContext {
+  path: string;
+  url: string;
+  method: string;
+}
+
 export class VerifyAIClient {
   private apiKey: string;
   private baseUrl: string;
   private timeout: number;
+  readonly telemetry: TelemetryReporter | null;
 
   constructor(config: VerifyAIConfig) {
     if (!config.apiKey) {
@@ -23,17 +33,71 @@ 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;
   }
 
-  private async request<T>(
+  private parseResponseBody(rawBody: string): unknown {
+    if (!rawBody) {
+      return null;
+    }
+
+    try {
+      return JSON.parse(rawBody);
+    } catch {
+      return { error: rawBody };
+    }
+  }
+
+  private buildRequestError(
+    message: string,
+    status: number,
+    context: RequestContext,
+    body: Partial<VerifyAIError> = {}
+  ): VerifyAIRequestError {
+    const error: VerifyAIError = {
+      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);
+  }
+
+  private normalizeRequestError(error: unknown, context: RequestContext): VerifyAIRequestError {
+    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);
+  }
+
+  private async executeRequest<T>(
     path: string,
     options: RequestInit = {}
   ): Promise<T> {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.timeout);
+    const method = (options.method || 'GET').toUpperCase();
+    const url = `${this.baseUrl}${path}`;
+    const context: RequestContext = { path, url, method };
 
     try {
-      const response = await fetch(`${this.baseUrl}${path}`, {
+      const response = await fetch(url, {
         ...options,
         signal: controller.signal,
         headers: {
@@ -43,43 +107,76 @@ export class VerifyAIClient {
       });
 
       const rawBody = await response.text();
-      let body: unknown = 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) 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,
+        throw this.buildRequestError(
+          errorBody?.error || `Request failed with status ${response.status}`,
           response.status,
-          error
+          context,
+          {
+            current_usage: errorBody?.current_usage,
+            limit: errorBody?.limit,
+            upgrade_url: errorBody?.upgrade_url,
+            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 as T;
+    } 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);
     }
   }
 
+  private async request<T>(
+    path: string,
+    options: RequestInit = {}
+  ): Promise<T> {
+    return this.executeRequest<T>(path, options);
+  }
+
   /**
    * Submit a photo for AI verification.
    *
@@ -102,14 +199,60 @@ export class VerifyAIClient {
    * }
    * ```
    */
-  async verify(request: VerificationRequest): Promise<VerificationResult> {
+  async verify(request: VerificationRequest, options?: VerifyOptions): Promise<VerificationResult> {
+    const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+    if (options?.idempotencyKey) {
+      headers['Idempotency-Key'] = options.idempotencyKey;
+    }
     return this.request<VerificationResult>('/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: MultipartVerificationRequest, options?: VerifyOptions): Promise<VerificationResult> {
+    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',
+    } as unknown as Blob);
+    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: Record<string, string> = {
+      '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<VerificationResult>('/verify', {
+      method: 'POST',
+      headers,
+      body: formData,
+    });
+  }
+
   /**
    * List past verifications with optional filters.
    *
@@ -211,4 +354,12 @@ export class VerifyAIRequestError extends Error {
   get upgradeUrl(): string | undefined {
     return this.body.upgrade_url;
   }
+
+  get requestId(): string | undefined {
+    return this.body.request_id;
+  }
+
+  get code(): string | undefined {
+    return this.body.code;
+  }
 }