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

package/src/ml/policyEngine.ts

@@ -0,0 +1,201 @@
+/**
+ * Deterministic policy engine for React Native SDK.
+ * MUST produce identical output to the server TypeScript and Dart implementations.
+ *
+ * This file shares the same logic as lib/verify-ai/ml/policy-engine.ts
+ * but is self-contained for the SDK package.
+ */
+
+import type {
+  FeatureVector,
+  PolicyAST,
+  PolicyResult,
+  RuleResult,
+  Rule,
+  Condition,
+  CategoryPredicate,
+  ComparisonOperator,
+} from './types';
+
+// ─── Field Resolution ───
+
+function resolveField(features: FeatureVector, field: string): unknown {
+  const parts = field.split('.');
+  let current: unknown = features;
+
+  for (const part of parts) {
+    if (current === null || current === undefined) return undefined;
+    if (typeof current !== 'object') return undefined;
+    current = (current as Record<string, unknown>)[part];
+  }
+
+  return current;
+}
+
+// ─── Condition Evaluation ───
+
+function applyOperator(fieldValue: unknown, operator: ComparisonOperator, value: unknown): boolean {
+  switch (operator) {
+    case 'exists':
+      return fieldValue !== null && fieldValue !== undefined;
+    case 'not_exists':
+      return fieldValue === null || fieldValue === undefined;
+    case 'eq':
+      return fieldValue === value;
+    case 'neq':
+      return fieldValue !== value;
+    case 'gt':
+      return typeof fieldValue === 'number' && typeof value === 'number' && fieldValue > value;
+    case 'gte':
+      return typeof fieldValue === 'number' && typeof value === 'number' && fieldValue >= value;
+    case 'lt':
+      return typeof fieldValue === 'number' && typeof value === 'number' && fieldValue < value;
+    case 'lte':
+      return typeof fieldValue === 'number' && typeof value === 'number' && fieldValue <= value;
+    case 'contains':
+      if (Array.isArray(fieldValue)) return fieldValue.includes(value);
+      if (typeof fieldValue === 'string' && typeof value === 'string') return fieldValue.includes(value);
+      return false;
+    case 'not_contains':
+      if (Array.isArray(fieldValue)) return !fieldValue.includes(value);
+      if (typeof fieldValue === 'string' && typeof value === 'string') return !fieldValue.includes(value);
+      return true;
+    case 'in':
+      if (Array.isArray(value)) return value.includes(fieldValue);
+      return false;
+    case 'not_in':
+      if (Array.isArray(value)) return !value.includes(fieldValue);
+      return true;
+    case 'overlaps':
+      if (Array.isArray(fieldValue) && Array.isArray(value)) {
+        return fieldValue.some((v) => value.includes(v));
+      }
+      return false;
+    default:
+      return false;
+  }
+}
+
+function evaluateCondition(features: FeatureVector, condition: Condition): boolean {
+  const fieldValue = resolveField(features, condition.field);
+  return applyOperator(fieldValue, condition.operator, condition.value);
+}
+
+function evaluateRule(features: FeatureVector, rule: Rule): RuleResult {
+  const passed = rule.conditions.every((c) => evaluateCondition(features, c));
+  return {
+    rule_id: rule.id,
+    passed,
+    severity: rule.severity,
+    required: rule.required,
+  };
+}
+
+function resolveCategory(
+  features: FeatureVector,
+  categories: CategoryPredicate[],
+  ruleResults: RuleResult[],
+): { category_id: string; category_label: string; is_compliant: boolean } {
+  const failedCritical = ruleResults.some(
+    (r) => !r.passed && r.required && r.severity === 'critical',
+  );
+
+  for (const cat of categories) {
+    const matches = cat.conditions.every((c) => {
+      if (c.field === '_has_critical_failure') {
+        return applyOperator(failedCritical, c.operator, c.value);
+      }
+      if (c.field === '_failed_rule_count') {
+        const failedCount = ruleResults.filter((r) => !r.passed && r.required).length;
+        return applyOperator(failedCount, c.operator, c.value);
+      }
+      if (c.field === '_warning_count') {
+        const warnCount = ruleResults.filter((r) => !r.passed && r.severity === 'warning').length;
+        return applyOperator(warnCount, c.operator, c.value);
+      }
+      return evaluateCondition(features, c);
+    });
+
+    if (matches) {
+      return {
+        category_id: cat.category_id,
+        category_label: cat.label,
+        is_compliant: cat.is_compliant,
+      };
+    }
+  }
+
+  // Fallback
+  if (failedCritical) {
+    return { category_id: 'unsafe', category_label: 'Unsafe', is_compliant: false };
+  }
+  const hasFailedRequired = ruleResults.some((r) => !r.passed && r.required);
+  if (hasFailedRequired) {
+    return { category_id: 'improvable', category_label: 'Improvable', is_compliant: false };
+  }
+  return { category_id: 'compliant', category_label: 'Compliant', is_compliant: true };
+}
+
+function generateFeedback(
+  isCompliant: boolean,
+  violationReasons: string[],
+  ruleResults: RuleResult[],
+): string {
+  if (isCompliant) {
+    const warnings = ruleResults.filter((r) => !r.passed && r.severity === 'warning');
+    if (warnings.length > 0) {
+      return `Parking is compliant with ${warnings.length} minor suggestion(s).`;
+    }
+    return 'Parking meets all requirements.';
+  }
+
+  if (violationReasons.length === 0) {
+    return 'Unable to determine compliance.';
+  }
+
+  if (violationReasons.length === 1) {
+    return `Issue detected: ${violationReasons[0]}.`;
+  }
+
+  return `${violationReasons.length} issues detected: ${violationReasons.join(', ')}.`;
+}
+
+// ─── Main Evaluator ───
+
+/**
+ * Evaluate a PolicyAST against a FeatureVector.
+ * Pure function — no side effects.
+ * Must produce identical output to server TS and Dart implementations.
+ */
+export function evaluatePolicy(ast: PolicyAST, features: FeatureVector): PolicyResult {
+  const ruleResults = ast.rules.map((rule) => evaluateRule(features, rule));
+
+  const { category_id, category_label, is_compliant } = resolveCategory(
+    features,
+    ast.categories,
+    ruleResults,
+  );
+
+  const violationReasons: string[] = [];
+  for (let i = 0; i < ast.rules.length; i++) {
+    if (!ruleResults[i].passed && ast.rules[i].required) {
+      violationReasons.push(ast.rules[i].label);
+    }
+  }
+
+  const totalRules = ruleResults.length;
+  const passedRules = ruleResults.filter((r) => r.passed).length;
+  const confidence = totalRules > 0 ? passedRules / totalRules : 0;
+
+  const feedback = generateFeedback(is_compliant, violationReasons, ruleResults);
+
+  return {
+    category_id,
+    category_label,
+    is_compliant,
+    confidence: Math.round(confidence * 100) / 100,
+    violation_reasons: violationReasons,
+    rule_results: ruleResults,
+    feedback,
+  };
+}

package/src/ml/types.ts

@@ -0,0 +1,104 @@
+/**
+ * On-device ML types for React Native SDK.
+ */
+
+export interface ModelArtifact {
+  role: 'detector' | 'segmenter' | 'classifier';
+  architecture: string;
+  version: number;
+  format: 'coreml' | 'tflite' | 'onnx';
+  storagePath: string;
+  sizeBytes: number;
+  sha256: string;
+  downloadUrl?: string;
+  localPath?: string;
+}
+
+export interface BundleManifest {
+  bundleVersion: number;
+  ontologyVersion: string;
+  schemaVersion: string;
+  policyId: string;
+  classIds: number[];
+  artifacts: ModelArtifact[];
+  policyAst: PolicyAST;
+}
+
+// ─── Feature Schema Types ───
+
+export interface Detection {
+  class_id: number;
+  class_name: string;
+  confidence: number;
+  bbox: [number, number, number, number];
+}
+
+export interface ImageQuality {
+  is_blurry: boolean;
+  is_dark: boolean;
+  has_vehicle: boolean;
+}
+
+export interface FeatureVector {
+  schema_version: string;
+  detections: Detection[];
+  primary_vehicle: Detection | null;
+  image_quality: ImageQuality;
+  vehicle_on_surface: string | null;
+  vehicle_near: string[];
+}
+
+// ─── Policy AST Types ───
+
+export type ComparisonOperator =
+  | 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte'
+  | 'contains' | 'not_contains'
+  | 'exists' | 'not_exists'
+  | 'in' | 'not_in' | 'overlaps';
+
+export interface Condition {
+  field: string;
+  operator: ComparisonOperator;
+  value?: unknown;
+}
+
+export interface Rule {
+  id: string;
+  label: string;
+  severity: 'critical' | 'warning' | 'info';
+  required: boolean;
+  conditions: Condition[];
+}
+
+export interface CategoryPredicate {
+  category_id: string;
+  label: string;
+  is_compliant: boolean;
+  conditions: Condition[];
+}
+
+export interface PolicyAST {
+  ast_version: string;
+  policy_id: string;
+  ontology_version: string;
+  schema_version: string;
+  rules: Rule[];
+  categories: CategoryPredicate[];
+}
+
+export interface RuleResult {
+  rule_id: string;
+  passed: boolean;
+  severity: 'critical' | 'warning' | 'info';
+  required: boolean;
+}
+
+export interface PolicyResult {
+  category_id: string;
+  category_label: string;
+  is_compliant: boolean;
+  confidence: number;
+  violation_reasons: string[];
+  rule_results: RuleResult[];
+  feedback: string;
+}

package/src/storage/offlineQueue.ts

@@ -175,7 +175,7 @@ export class OfflineQueue {
         }
 
         try {
-          const result = await this.client.verify(item.request);
+          const result = await this.client.verify(item.request, { idempotencyKey: item.id });
           processed++;
           await AsyncStorage.removeItem(`${ITEM_PREFIX}${id}`);
           onResult?.(item.id, result);

package/src/telemetry/TelemetryContext.tsx

@@ -0,0 +1,8 @@
+import React, { createContext, useContext } from 'react';
+import type { TelemetryReporter } from './TelemetryReporter';
+
+export const TelemetryContext = createContext<TelemetryReporter | null>(null);
+
+export function useTelemetry(): TelemetryReporter | null {
+  return useContext(TelemetryContext);
+}

package/src/telemetry/TelemetryReporter.ts

@@ -0,0 +1,184 @@
+import { Platform } from 'react-native';
+import { SDK_VERSION } from '../version';
+
+interface TelemetryEvent {
+  event_type: string;
+  component?: string;
+  error_message?: string;
+  error_stack?: string;
+  error_code?: string;
+  metadata?: Record<string, string | number>;
+  sdk_platform: string;
+  sdk_version: string;
+  os_name: string;
+  os_version: string;
+  session_id: string;
+  event_count: number;
+  first_occurred_at: string;
+  last_occurred_at: string;
+}
+
+interface BufferedEvent {
+  event: TelemetryEvent;
+  dedupKey: string;
+}
+
+/** 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 {
+  private buffer: Map<string, TelemetryEvent> = new Map();
+  private flushTimer: ReturnType<typeof setTimeout> | null = null;
+  private sessionId: string;
+  private baseUrl: string;
+  private apiKey: string;
+  private disposed = false;
+  private flushing = false;
+
+  constructor(apiKey: string, baseUrl: string) {
+    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: string,
+    opts: {
+      component?: string;
+      error?: unknown;
+      errorCode?: string;
+      metadata?: Record<string, string | number>;
+    } = {},
+  ): void {
+    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: TelemetryEvent = {
+        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(): Promise<void> {
+    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(): void {
+    this.disposed = true;
+    this.clearFlushTimer();
+    this.flush();
+  }
+
+  private scheduleFlush(): void {
+    if (this.flushTimer) return;
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = null;
+      this.flush();
+    }, 5000);
+  }
+
+  private flushNow(): void {
+    this.clearFlushTimer();
+    this.flush();
+  }
+
+  private clearFlushTimer(): void {
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+  }
+}

package/src/types/index.ts

@@ -5,6 +5,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 {
@@ -14,6 +16,13 @@ export interface VerificationRequest {
   provider?: 'openai' | 'anthropic' | 'gemini';
 }
 
+export interface MultipartVerificationRequest {
+  imageUri: string; // file URI (e.g. file:///path/to/photo.jpg)
+  policy: string;
+  metadata?: Record<string, unknown>;
+  provider?: 'openai' | 'anthropic' | 'gemini';
+}
+
 export interface VerificationResult {
   id: string;
   created_at: string;
@@ -43,6 +52,11 @@ export interface VerificationListParams {
   end_date?: string;
 }
 
+export interface VerifyOptions {
+  /** Idempotency key to prevent duplicate verifications on retry. */
+  idempotencyKey?: string;
+}
+
 export interface QueueItem {
   id: string;
   request: VerificationRequest;
@@ -56,6 +70,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';
@@ -86,6 +105,7 @@ export interface ScannerOverlayConfig {
   exhaustedMessage?: string;
   maxAttempts?: number;
   autoApproveOnExhaust?: boolean;
+  showTechnicalErrorDetails?: boolean;
 }
 
 export interface PolicyConfigResponse {

package/src/version.ts

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