@sanctum-key/react-native-sdk 1.0.0

package/src/types/env.types.ts

@@ -0,0 +1,13 @@
+/**
+ * KYC Environment types
+ * PRODUCTION: Full verification with AI checks
+ * SANDBOX: Skip AI verification, only save data to backend
+ */
+export type KycEnvironment = 'PRODUCTION' | 'SANDBOX';
+
+/**
+ * Backend Environment types
+ * PRODUCTION: Production backend
+ * TEST: Test backend
+ */
+export type BackendEnvironment = 'PRODUCTION' | 'TEST';

package/src/utils/cropByObb.ts

@@ -0,0 +1,254 @@
+import { Image as RNImage, Platform } from 'react-native';
+import * as ImageManipulator from "expo-image-manipulator";
+import { truncateFields } from '../modules/api/KYCService';
+import { logger } from './logger';
+
+type Point = [number, number];
+
+/** OBB confidence below this = card not fully in frame; don't crop, give user feedback. */
+export const OBB_CONFIDENCE_THRESHOLD = 0.85;
+
+/**
+ * card_obb format from API:
+ * - Legacy: [ [ [p1,p2,p3,p4], confidence ] ]
+ * - New:    [ { obb: [p1,p2,p3,p4], confidence, card_in_frame?, cropped_sides? } ]
+ * Returns confidence in [0,1] or null if not present.
+ */
+export function getObbConfidence(cardObb: any): number | null {
+  if (!cardObb || !Array.isArray(cardObb) || cardObb.length === 0) return null;
+  const first = cardObb[0];
+
+  // New format: first is an object with a confidence field
+  if (first && typeof first === 'object' && 'confidence' in first) {
+    const score = (first as any).confidence;
+    return typeof score === 'number' ? score : null;
+  }
+
+  // Legacy format: [ [points], score ]
+  if (!Array.isArray(first) || first.length < 2) return null;
+  const score = first[1];
+  return typeof score === 'number' ? score : null;
+}
+
+/**
+ * Extracts the card_in_frame flag from card_obb when present.
+ * Returns:
+ * - true  => card fully in frame
+ * - false => card not fully in frame
+ * - null  => field not present (backward compatibility)
+ */
+/**
+ * Extracts the framing data from card_obb.
+ * STRICT CHECK: Returns true ONLY if card_in_frame is true AND cropped_sides is empty.
+ * Returns:
+ * - true  => card fully in frame (no sides cropped)
+ * - false => card not fully in frame OR edges are cropped
+ * - null  => field not present (backward compatibility)
+ */
+export function getCardInFrame(cardObb: any): boolean | null {
+  if (!cardObb) return null;
+
+  // card_obb can be an array of objects or a single object
+  const first = Array.isArray(cardObb) ? cardObb[0] : cardObb;
+
+  if (first && typeof first === 'object' && 'card_in_frame' in first) {
+    const isCardInFrame = first.card_in_frame === true;
+    const hasCroppedSides = Array.isArray(first.cropped_sides) && first.cropped_sides.length > 0;
+
+    // If the API explicitly says it's not in frame, OR if it lists cropped edges, reject it.
+    if (!isCardInFrame || hasCroppedSides) {
+      if (hasCroppedSides) {
+        console.warn(`Card is cropped on sides: ${first.cropped_sides.join(', ')}`);
+      }
+      return false; 
+    }
+
+    // If we made it here, card_in_frame is true AND cropped_sides is empty.
+    return true; 
+  }
+
+  // Backward compatibility check
+  if (cardObb && typeof cardObb === 'object' && 'card_in_frame' in cardObb) {
+    const value = (cardObb as any).card_in_frame;
+    return typeof value === 'boolean' ? value : null;
+  }
+
+  return null;
+}
+
+// Compute axis-aligned bounding box from oriented quadrilateral
+function computeAabb(points: Point[]) {
+  const xs = points.map(p => p[0]);
+  const ys = points.map(p => p[1]);
+  const minX = Math.min(...xs);
+  const minY = Math.min(...ys);
+  const maxX = Math.max(...xs);
+  const maxY = Math.max(...ys);
+  return { minX, minY, maxX, maxY, width: maxX - minX, height: maxY - minY };
+}
+
+// Web-only crop using Canvas; returns dataURL (base64)
+async function cropWeb(uri: string, points: Point[]): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    img.crossOrigin = 'anonymous';
+    img.onload = () => {
+      const { minX, minY, width, height } = computeAabb(points);
+      const canvas = document.createElement('canvas');
+      canvas.width = Math.max(1, Math.round(width));
+      canvas.height = Math.max(1, Math.round(height));
+      const ctx = canvas.getContext('2d');
+      if (!ctx) return reject(new Error('Canvas context not available'));
+      ctx.drawImage(
+        img,
+        minX, // sx
+        minY, // sy
+        width, // sw
+        height, // sh
+        0,
+        0,
+        canvas.width,
+        canvas.height
+      );
+      resolve(canvas.toDataURL('image/jpeg', 0.92));
+    };
+    img.onerror = (e) => reject(e);
+    img.src = uri;
+  });
+}
+
+// Fallback: return original for native (no dependency added); caller can still use bbox to draw overlay
+export async function cropByObb(uri: string, cardObb: any): Promise<{ base64?: string; bbox?: { minX: number; minY: number; width: number; height: number } }> {
+  try {
+    // card_obb format: [ [ [p1,p2,p3,p4], score ] ] — if confidence too low, don't crop (send full image)
+    const confidence = getObbConfidence(cardObb);
+    if (confidence !== null && confidence < OBB_CONFIDENCE_THRESHOLD) {
+      return {};
+    }
+    const first = Array.isArray(cardObb) ? cardObb[0] : null;
+    const points = Array.isArray(first?.[0]) ? (first[0] as Point[]) : null;
+    if (!points || points.length !== 4) return {};
+
+    const { minX, minY, width, height } = computeAabb(points);
+
+    if (Platform.OS === 'web') {
+      const base64 = await cropWeb(uri, points);
+      return { base64, bbox: { minX, minY, width, height } };
+    }
+    // Native: return bbox only; keep base64 undefined
+    return { bbox: { minX, minY, width, height } };
+  } catch (e) {
+    return {};
+  }
+}
+
+
+
+
+// exemple d'appel :
+export async function cropImageWithBBox(uri: string, bbox: any) {
+  // 1️⃣ Récupère la taille originale de l'image
+  await RNImage.getSize(uri, (width, height) => {
+    console.log("Image originale:", width, height);
+  });
+
+  // // 2️⃣ Suppose que ton bbox vient d'une image affichée dans `displayedSize`
+  // const scaleX = originalWidth / displayedSize.width;
+  // const scaleY = originalHeight / displayedSize.height;
+
+  // 3️⃣ Convertir le bbox à la taille réelle scale 0.10 = 10%
+  const crop = {
+    originX: bbox.minX,
+    originY: bbox.minY,
+    width: bbox.width,
+    height: bbox.height,
+  };
+
+  // 4️⃣ Appliquer le crop
+  // @ts-ignore - manipulateAsync is deprecated but still functional, new API (useImageManipulator) is a React hook and not suitable for utility functions
+  const result = await ImageManipulator.manipulateAsync(
+    uri,
+    [{ crop }],
+    { compress: 1, format: ImageManipulator.SaveFormat.PNG }
+  );
+
+  console.log("Image recadrée:", result.uri);
+  return result.uri;
+}
+
+// Fonction pour rogner avec une tolérance de 10% autour du bbox
+export async function cropImageWithBBoxWithTolerance(uri: string, bbox: any, tolerance: number = 0.1): Promise<string> {
+  console.log("cropImageWithBBoxWithTolerance", JSON.stringify(truncateFields({ uri, bbox, tolerance }), null, 2));
+  
+  return new Promise<string>((resolve, reject) => {
+    let isResolved = false;
+    
+    // Timeout de sécurité (15 secondes)
+    const timeout = setTimeout(() => {
+      if (!isResolved) {
+        isResolved = true;
+        console.warn("Timeout lors du rognage avec tolérance, utilisation de l'image originale");
+        resolve(uri); // Retourner l'URI original en cas de timeout
+      }
+    }, 15000);
+
+    // 1️⃣ Récupère la taille originale de l'image
+    RNImage.getSize(uri, (imageWidth, imageHeight) => {
+      if (isResolved) return;
+      
+      // 2️⃣ Calculer la tolérance en pixels (10% de chaque côté)
+      const toleranceX = bbox.width * tolerance;
+      const toleranceY = bbox.height * tolerance;
+
+      // 3️⃣ Ajuster le bbox avec la tolérance
+      // Calculer les nouvelles coordonnées avec tolérance
+      const newMinX = Math.max(0, bbox.minX - toleranceX);
+      const newMinY = Math.max(0, bbox.minY - toleranceY);
+      const newMaxX = Math.min(imageWidth, bbox.minX + bbox.width + toleranceX);
+      const newMaxY = Math.min(imageHeight, bbox.minY + bbox.height + toleranceY);
+
+      // Calculer la largeur et hauteur finales
+      const finalWidth = newMaxX - newMinX;
+      const finalHeight = newMaxY - newMinY;
+
+      const crop = {
+        originX: newMinX,
+        originY: newMinY,
+        width: finalWidth,
+        height: finalHeight,
+      };
+
+      logger.log("cropImageWithBBoxWithTolerance - crop params", JSON.stringify(truncateFields({ uri, crop, tolerance, imageWidth, imageHeight }), null, 2));
+
+      // 4️⃣ Appliquer le crop avec tolérance
+      // @ts-ignore - manipulateAsync is deprecated but still functional, new API (useImageManipulator) is a React hook and not suitable for utility functions
+      ImageManipulator.manipulateAsync(
+        uri,
+        [{ crop }],
+        { compress: 0.95, format: ImageManipulator.SaveFormat.JPEG }
+      )
+        .then((result) => {
+          if (isResolved) return;
+          isResolved = true;
+          clearTimeout(timeout);
+          console.log("Image recadrée avec tolérance:", result.uri);
+          resolve(result.uri);
+        })
+        .catch((error) => {
+          if (isResolved) return;
+          isResolved = true;
+          clearTimeout(timeout);
+          console.error("Erreur lors du rognage avec tolérance:", error);
+          // En cas d'erreur, retourner l'URI original au lieu de rejeter
+          resolve(uri);
+        });
+    }, (error) => {
+      if (isResolved) return;
+      isResolved = true;
+      clearTimeout(timeout);
+      console.error("Erreur lors de la récupération de la taille de l'image:", error);
+      // En cas d'erreur, retourner l'URI original au lieu de rejeter
+      resolve(uri);
+    });
+  });
+}

package/src/utils/deviceDetection.ts

@@ -0,0 +1,11 @@
+/**
+ * Checks if the current environment is a mobile web browser based on User Agent.
+ * This can be used to distinguish between desktop web and mobile web.
+ */
+export const isMobileWeb = (): boolean => {
+    if (typeof window === 'undefined' || !window.navigator) {
+        return false;
+    }
+    const userAgent = window.navigator.userAgent;
+    return /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(userAgent);
+};

package/src/utils/get-document-type-info.ts

@@ -0,0 +1,62 @@
+import { GovernmentDocumentType } from "../types/KYC.types";
+
+export const getDocumentTypeInfo = (docType: GovernmentDocumentType) => {
+    switch (docType) {
+        case 'identity_card':
+            return {
+                name: { en: 'ID Card', fr: 'Carte d\'identité' },
+                icon: '🆔',
+                instructions: { en: 'Position your ID card within the frame', fr: 'Positionnez votre carte d\'identité dans le cadre' }
+            };
+        case 'passport':
+            return {
+                name: { en: 'Passport', fr: 'Passeport' },
+                icon: '📘',
+                instructions: { en: 'Position your passport within the frame', fr: 'Positionnez votre passeport dans le cadre' }
+            };
+        case 'drivers_licence':
+            return {
+                name: { en: 'Driver\'s License', fr: 'Permis de conduire' },
+                icon: '🚗',
+                instructions: { en: 'Position your driver\'s license within the frame', fr: 'Positionnez votre permis de conduire dans le cadre' }
+            };
+        case 'permanent_residence':
+            return {
+                name: { en: 'Residence Permit', fr: 'Permis de séjour' },
+                icon: '🏠',
+                instructions: { en: 'Position your residence permit within the frame', fr: 'Positionnez votre permis de séjour dans le cadre' }
+            };
+        case 'national_id':
+            return {
+                name: { en: 'National ID', fr: 'Carte nationale d\'identité' },
+                icon: '🏛️',
+                instructions: { en: 'Position your national ID within the frame', fr: 'Positionnez votre carte nationale d\'identité dans le cadre' }
+            };
+        case 'health_insurance_card':
+            return {
+                name: { en: 'Health Insurance Card', fr: 'Carte d\'assurance santé' },
+                icon: '🗳️',
+                instructions: { en: 'Position your health insurance card within the frame', fr: 'Positionnez votre carte d\'assurance santé dans le cadre' }
+            };
+        case 'work_permit':
+            return {
+                name: { en: 'Work Permit', fr: 'Permis de travail' },
+                icon: '🎖️',
+                instructions: { en: 'Position your work permit within the frame', fr: 'Positionnez votre permis de travail dans le cadre' }
+            };
+
+        case 'passport':
+            return {
+                name: { en: 'Passport', fr: 'Passeport' },
+                icon: '💼',
+                instructions: { en: 'Position your passport within the frame', fr: 'Positionnez votre passeport dans le cadre' }
+            };
+
+        default:
+            return {
+                name: { en: 'Government Document', fr: 'Document gouvernemental' },
+                icon: '📄',
+                instructions: { en: 'Position your document within the frame', fr: 'Positionnez votre document dans le cadre' }
+            };
+    }
+};

package/src/utils/logger.ts

@@ -0,0 +1,48 @@
+/**
+ * Logger utility that only logs in development mode
+ * In production, all logs are suppressed
+ */
+
+const isProduction = (): boolean => {
+  // Check for React Native __DEV__ flag
+  if (typeof __DEV__ !== 'undefined') {
+    return !__DEV__;
+  }
+  // Check for Node.js environment
+  if (typeof process !== 'undefined' && process.env) {
+    return process.env.NODE_ENV === 'production';
+  }
+  // Default to development mode if we can't determine
+  return false;
+};
+
+const shouldLog = !isProduction();
+
+export const logger = {
+  log: (...args: any[]) => {
+    if (shouldLog) {
+      console.log(...args);
+    }
+  },
+  error: (...args: any[]) => {
+    if (shouldLog) {
+      console.error(...args);
+    }
+  },
+  warn: (...args: any[]) => {
+    if (shouldLog) {
+      console.warn(...args);
+    }
+  },
+  info: (...args: any[]) => {
+    if (shouldLog) {
+      console.info(...args);
+    }
+  },
+  debug: (...args: any[]) => {
+    if (shouldLog) {
+      console.debug(...args);
+    }
+  },
+};
+

package/src/utils/pathToBase64.ts

@@ -0,0 +1,63 @@
+export async function pathToBase64(uri: string): Promise<string> {
+  if (!uri) throw new Error('pathToBase64: uri is required');
+
+  // If already a data URI, return the base64 part
+  if (uri.startsWith('data:')) {
+    const commaIndex = uri.indexOf(',');
+    return commaIndex !== -1 ? uri.substring(commaIndex + 1) : uri;
+  }
+
+  // Try Expo FileSystem if available (React Native + Expo)
+  try {
+    // Try legacy API from expo-file-system/legacy first (Expo SDK 54+)
+    // This is the recommended way to avoid deprecation warnings
+    try {
+      // @ts-ignore - legacy export might not be in types
+      const LegacyFileSystem = require('expo-file-system');
+      if (LegacyFileSystem?.readAsStringAsync) {
+        const base64 = await LegacyFileSystem.readAsStringAsync(uri, { encoding: LegacyFileSystem.EncodingType.Base64 });
+        if (base64) return base64;
+      }
+    } catch (legacyError) {
+      // Legacy not available (SDK 53 or earlier), try regular import
+      const errorMessage = legacyError instanceof Error ? legacyError.message : String(legacyError);
+      if (errorMessage.includes('Cannot find module') || errorMessage.includes('Module not found')) {
+        // SDK 53 or earlier - use regular import as fallback
+        // @ts-ignore
+        const FileSystem = require('expo-file-system');
+        if (FileSystem?.readAsStringAsync) {
+          const base64 = await FileSystem.readAsStringAsync(uri, { encoding: FileSystem.EncodingType.Base64 });
+          if (base64) return base64;
+        }
+      }
+      // If it's a different error, continue to other strategies
+    }
+  } catch (_) {
+    // All FileSystem APIs failed, fall back to other strategies (fetch + FileReader)
+  }
+
+  // Generic fetch + FileReader strategy (works on web; often works on RN for file:// URIs)
+  try {
+    const response = await fetch(uri);
+    const blob = await response.blob();
+    const dataUrl = await new Promise<string>((resolve, reject) => {
+      const reader = new FileReader();
+      reader.onloadend = () => {
+        if (typeof reader.result === 'string') resolve(reader.result);
+        else reject(new Error('Failed to convert blob to data URL'));
+      };
+      reader.onerror = reject;
+      reader.readAsDataURL(blob);
+    });
+    const commaIndex = dataUrl.indexOf(',');
+    return commaIndex !== -1 ? dataUrl.substring(commaIndex + 1) : dataUrl;
+  } catch (err) {
+    // continue to final error
+  }
+
+  throw new Error('pathToBase64: unable to convert uri to base64');
+}
+
+export default pathToBase64;
+
+

package/src/utils/platformAlert.ts

@@ -0,0 +1,86 @@
+import { Platform, Alert } from 'react-native';
+
+export interface AlertButton {
+  text?: string;
+  onPress?: () => void;
+  style?: 'default' | 'cancel' | 'destructive';
+}
+
+/**
+ * Platform-aware alert helper that works on both native and web platforms
+ * On web, uses window.confirm/window.alert since Alert.alert is not supported
+ * On native, uses the standard Alert.alert
+ */
+export const showAlert = (
+  title: string,
+  message?: string,
+  buttons?: AlertButton[]
+): void => {
+  if (Platform.OS === 'web') {
+    // Web implementation using native browser dialogs
+    const fullMessage = message ? `${title}\n\n${message}` : title;
+
+    if (buttons && buttons.length > 1) {
+      
+      // Multiple buttons - use confirm dialog
+      const confirmed = window.confirm(fullMessage);
+      
+      if (confirmed) {
+        // Find and call the primary/positive button callback
+        const confirmButton = buttons.find(
+          btn => btn.style !== 'cancel' && btn.onPress
+        );
+        confirmButton?.onPress?.();
+      } else {
+        // Find and call the cancel button callback
+        const cancelButton = buttons.find(btn => btn.style === 'cancel');
+        cancelButton?.onPress?.();
+      }
+    } else if (buttons && buttons.length === 1) {
+      // Single button - use alert dialog
+      window.alert(fullMessage);
+      buttons[0]?.onPress?.();
+    } else {
+      // No buttons - just show alert
+      window.alert(fullMessage);
+    }
+  } else {
+    // Native implementation - use standard Alert.alert
+    Alert.alert(title, message, buttons);
+  }
+};
+
+/**
+ * Simplified confirm dialog for yes/no scenarios
+ */
+export const showConfirm = (
+  title: string,
+  message: string,
+  onConfirm: () => void,
+  onCancel?: () => void
+): void => {
+  showAlert(title, message, [
+    {
+      text: 'Cancel',
+      style: 'cancel',
+      onPress: onCancel,
+    },
+    {
+      text: 'OK',
+      onPress: onConfirm,
+    },
+  ]);
+};
+
+/**
+ * Simple alert with just an OK button
+ */
+export const showSimpleAlert = (title: string, message?: string, onPress?: () => void): void => {
+  showAlert(title, message, [
+    {
+      text: 'OK',
+      onPress,
+    },
+  ]);
+};
+

package/src/utils/remove-duplicate.ts

@@ -0,0 +1,3 @@
+export function removeDuplicates(arr: string[]): string[] {
+    return [...new Set(arr)];
+}