@transfergratis/react-native-sdk 0.1.10 → 0.1.12

package/README.md

@@ -1,29 +1,36 @@
 # TransferGratis KYC SDK
 
-A comprehensive KYC (Know Your Customer) SDK built with React Native and Expo, featuring advanced camera capabilities powered by react-native-vision-camera.
+A comprehensive React Native SDK for identity verification (KYC - Know Your Customer) with Expo support, featuring advanced camera capabilities powered by react-native-vision-camera.
 
 ## 🚀 Features
 
 ✅ **Advanced Camera Integration** with react-native-vision-camera  
-✅ **Selfie Capture** with face detection overlay  
+✅ **Selfie Capture** with face detection and overlay  
 ✅ **Document Capture** with auto-focus and quality controls  
 ✅ **Orientation Video Processing** for liveness detection  
 ✅ **File Upload** with validation  
 ✅ **Custom Overlays** and instructions  
 ✅ **Permission Management** with graceful fallbacks  
-✅ **Multi-Platform Support** (iOS, Android)  
+✅ **Multi-Platform Support** (iOS, Android, Web)  
 ✅ **TypeScript Support** with full type definitions  
 ✅ **Expo Config Plugin** for easy setup  
+✅ **JSON Template System** for configurable KYC flows  
+✅ **Multilingual Support** (French, English)  
+✅ **GPS Location Capture**  
+✅ **Country Selection** with region mapping  
+✅ **Reusable UI Components**
 
-## 📦 Installation (Essentiel)
+## 📦 Installation
+
+### Installing Dependencies
 
 ```bash
-npm install @transfergratis/react-native-sdk react-native-vision-camera expo-location react-native-svg
+npm install @transfergratis/react-native-sdk react-native-vision-camera expo-location expo-image-manipulator react-native-svg
 ```
 
-### Configuration Expo (app.json / app.config.js)
+### Expo Configuration (app.json / app.config.js)
 
-Ajoutez le plugin à `app.json` (ou `app.config.js`) en vous basant sur l’exemple fourni. Le plugin applique les permissions caméra/micro et la localisation.
+Add the plugin to your Expo configuration file:
 
 ```json
 {
@@ -32,21 +39,21 @@ Ajoutez le plugin à `app.json` (ou `app.config.js`) en vous basant sur l’exem
       [
         "react-native-vision-camera",
         {
-          "cameraPermissionText": "Cette application utilise la caméra pour la vérification d'identité KYC.",
+          "cameraPermissionText": "This app uses the camera for KYC identity verification.",
           "enableMicrophonePermission": true,
-          "microphonePermissionText": "Cette application utilise le microphone pour l'enregistrement vidéo."
+          "microphonePermissionText": "This app uses the microphone for video recording."
         }
       ],
       [
         "@transfergratis/react-native-sdk/plugin",
         {
           "visionCamera": {
-            "cameraPermissionText": "Cette application utilise la caméra pour la vérification d'identité KYC.",
-            "microphonePermissionText": "Cette application utilise le microphone pour l'enregistrement vidéo."
+            "cameraPermissionText": "This app uses the camera for KYC identity verification.",
+            "microphonePermissionText": "This app uses the microphone for video recording."
           },
           "location": {
-            "locationPermissionText": "Cette application utilise la localisation pour vérifier votre identité et votre emplacement.",
-            "locationWhenInUsePermissionText": "Cette application utilise la localisation pour vérifier votre identité et votre emplacement.",
+            "locationPermissionText": "This app uses location to verify your identity and location.",
+            "locationWhenInUsePermissionText": "This app uses location to verify your identity and location.",
             "enableBackgroundLocation": false
           }
         }
@@ -58,31 +65,190 @@ Ajoutez le plugin à `app.json` (ou `app.config.js`) en vous basant sur l’exem
 
 ### Android Setup
 
-The config plugin will handle Android permissions automatically. No additional setup required.
+The config plugin automatically handles Android permissions. No additional setup required.
+
+### iOS Setup
+
+iOS permissions are also automatically handled by the Expo plugin.
 
 ## 🎯 Quick Start
 
-### Basic KYC Flow
+### Using JSON Templates (Recommended)
+
+The recommended approach is to use the JSON template system to configure your KYC flow:
 
 ```tsx
 import React from 'react';
-import { LauchTransferGratisKYC } from '@transfergratis/react-native-sdk';
+import { TemplateKYCFlow, KYCTemplate, VerificationState } from '@transfergratis/react-native-sdk';
+
+const myKYCTemplate: KYCTemplate = {
+  id: 1,
+  name: {
+    en: "Identity Verification",
+    fr: "Vérification d'Identité"
+  },
+  description: {
+    en: "Complete identity verification flow",
+    fr: "Processus complet de vérification d'identité"
+  },
+  version: "1.0.0",
+  components: [
+    {
+      id: 6,
+      type: "country_selection",
+      order: 1,
+      labels: {
+        en: "Select your country",
+        fr: "Sélectionnez votre pays"
+      },
+      instructions: {
+        en: "Choose your country of residence.",
+        fr: "Choisissez votre pays de résidence."
+      },
+      ui: {
+        icon: "country-icon.png",
+        themeColor: "#2DBD60",
+        buttonText: { en: "Confirm", fr: "Confirmer" }
+      },
+      config: {
+        allowed_countries: ["CM", "NG", "CI", "KE", "GH"],
+        default_country: "CM",
+        required: true
+      }
+    },
+    {
+      id: 1,
+      type: "id_card",
+      order: 2,
+      templateId: 1,
+      labels: {
+        front: {
+          en: "Upload front of ID card",
+          fr: "Téléversez le recto de votre carte d'identité"
+        },
+        back: {
+          en: "Upload back of ID card",
+          fr: "Téléversez le verso de votre carte d'identité"
+        }
+      },
+      instructions: {
+        front: {
+          en: "Take a clear photo of the front of your ID.",
+          fr: "Prenez une photo nette du recto de votre pièce."
+        },
+        back: {
+          en: "Take a clear photo of the back of your ID.",
+          fr: "Prenez une photo nette du verso de votre pièce."
+        }
+      },
+      ui: {
+        front: {
+          themeColor: "#2DBD60",
+          buttonText: { en: "Next", fr: "Suivant" }
+        },
+        back: {
+          themeColor: "#2DBD60",
+          buttonText: { en: "Next", fr: "Suivant" }
+        }
+      },
+      config: {
+        sides: ["front", "back"],
+        allowed_formats: ["jpg", "png"],
+        max_size_mb: 5,
+        document_types: ["identity_card", "passport", "drivers_licence", "national_id"],
+        bbox_configs: {
+          identity_card: {
+            xMin: 20,
+            yMin: 140,
+            xMax: 370,
+            yMax: 340,
+            borderColor: "#2DBD60",
+            borderWidth: 4,
+            cornerRadius: 12
+          },
+          passport: {
+            xMin: 15,
+            yMin: 130,
+            xMax: 375,
+            yMax: 350,
+            borderColor: "#007AFF",
+            borderWidth: 4,
+            cornerRadius: 8
+          }
+        }
+      }
+    },
+    {
+      id: 3,
+      type: "selfie",
+      order: 3,
+      templateId: 1,
+      labels: {
+        en: "Take selfies from different angles",
+        fr: "Prenez des selfies sous différents angles"
+      },
+      instructions: {
+        en: "Take selfies from front, left, and right angles.",
+        fr: "Prenez des selfies de face, profil gauche et profil droit."
+      },
+      ui: {
+        icon: "selfie-icon.png",
+        themeColor: "#2DBD60",
+        buttonText: { en: "Next", fr: "Suivant" }
+      },
+      config: {
+        liveness_check: true,
+        max_attempts: 3,
+        orientations: ["center", "left", "right"]
+      }
+    }
+  ]
+};
 
 export default function App() {
+  const handleComplete = (result: VerificationState) => {
+    console.log('KYC completed:', result);
+    // Process verification result
+  };
+
+  const handleError = (error: string) => {
+    console.error('KYC error:', error);
+    // Handle error
+  };
+
+  const handleCancel = () => {
+    console.log('KYC cancelled');
+    // Handle cancellation
+  };
+
   return (
-    <LauchTransferGratisKYC
-      apiKey="your-api-key"
-      onComplete={(result) => {
-        console.log('KYC completed:', result);
-      }}
-      onError={(error) => {
-        console.error('KYC error:', error);
-      }}
+    <TemplateKYCFlow
+      template={myKYCTemplate}
+      onComplete={handleComplete}
+      onError={handleError}
+      onCancel={handleCancel}
+      language="en" // or "fr" for French
+      API_KEY="your-api-key-here"
     />
   );
 }
 ```
 
+### Basic Usage (Simple Component)
+
+For simple usage without templates:
+
+```tsx
+import React from 'react';
+import { LauchTransferGratisKYC } from '@transfergratis/react-native-sdk';
+
+export default function App() {
+  return (
+    <LauchTransferGratisKYC />
+  );
+}
+```
+
 ### Advanced Camera Usage
 
 ```tsx
@@ -123,11 +289,26 @@ export default function CameraExample() {
 
 ## 📚 API Reference
 
-### Components
+### Main Components
+
+#### `TemplateKYCFlow`
+
+The main component for JSON template-based KYC flows.
+
+```tsx
+interface TemplateKYCFlowProps {
+  template: KYCTemplate;
+  onComplete?: (data: VerificationState) => void;
+  onError?: (error: string) => void;
+  onCancel?: () => void;
+  language?: string; // 'fr' | 'en'
+  API_KEY?: string;
+}
+```
 
 #### `EnhancedCameraView`
 
-The main camera component with full Vision Camera integration.
+Advanced camera component with full Vision Camera integration.
 
 ```tsx
 interface EnhancedCameraViewProps {
@@ -144,12 +325,21 @@ interface EnhancedCameraViewProps {
   showCaptureButton?: boolean;
   showSwitchCamera?: boolean;
   overlayComponent?: React.ReactNode;
+  bbox?: IBbox;
+  canFlip?: boolean;
+  enableVideo?: boolean;
+  isRecording?: boolean;
+  onVideoRecordingStart?: () => void;
+  onVideoRecordingStop?: () => void;
+  videoDuration?: number;
+  onSilentCapture?: (result: ISilentCaptureResult) => void;
+  silentCaptureResult?: ISilentCaptureResult;
 }
 ```
 
 #### `VisionCameraView`
 
-A simpler camera component for basic use cases.
+Simplified camera component for basic use cases.
 
 ```tsx
 interface VisionCameraViewProps {
@@ -166,20 +356,122 @@ interface VisionCameraViewProps {
 }
 ```
 
-#### `SelfieCapture`
+#### Specialized KYC Components
+
+##### `IDCardCapture`
 
-Pre-configured component for selfie capture with KYC integration.
+Identity document capture with automatic validation.
 
 ```tsx
-// No props required - integrates with KYC store
-<SelfieCapture />
+interface IDCardCaptureProps {
+  component: TemplateComponent;
+  value?: Record<string, IIDCardPayload>;
+  onValueChange: (value: Record<string, IIDCardPayload | string>) => void;
+  error?: string;
+  language?: string;
+  currentSide?: string;
+}
+```
+
+##### `SelfieCaptureTemplate`
+
+Selfie capture with liveness detection.
+
+```tsx
+interface SelfieCaptureTemplateProps {
+  component: TemplateComponent;
+  value?: any;
+  onValueChange: (value: any) => void;
+  error?: string;
+  language?: string;
+}
+```
+
+##### `FileUploadTemplate`
+
+File upload with validation.
+
+```tsx
+interface FileUploadTemplateProps {
+  component: TemplateComponent;
+  value?: any;
+  onValueChange: (value: any) => void;
+  error?: string;
+  language?: string;
+}
+```
+
+##### `LocationCaptureTemplate`
+
+GPS location capture.
+
+```tsx
+interface LocationCaptureTemplateProps {
+  component: TemplateComponent;
+  value?: LocationData;
+  onValueChange: (value: LocationData) => void;
+  error?: string;
+  language?: string;
+}
+```
+
+##### `CountrySelectionTemplate`
+
+Country selection with region mapping.
+
+```tsx
+interface CountrySelectionTemplateProps {
+  component: TemplateComponent;
+  value?: Country;
+  onValueChange: (value: Country) => void;
+  error?: string;
+  language?: string;
+}
+```
+
+#### `OrientationVideoCapture`
+
+Component for liveness detection via orientation video.
+
+```tsx
+interface OrientationVideoCaptureProps {
+  config: OrientationVideoConfig;
+  onComplete: (result: OrientationVideoResult) => void;
+  onError: (error: string) => void;
+  kycService: KYCService;
+}
 ```
 
 ### Modules
 
+#### `KYCService`
+
+Main service for KYC API calls.
+
+```tsx
+import { KYCService } from '@transfergratis/react-native-sdk';
+
+const kycService = new KYCService('https://api.yourdomain.com', 'your-api-key');
+
+// Create a new session
+const session = await kycService.newSession(token);
+
+// Submit a verification step
+await kycService.verificationSession({
+  session_id: session.id,
+  step: 'id_card',
+  data: { /* step data */ },
+  templateId: 1,
+  action: 'submit'
+});
+
+// Get verification result
+const result = await kycService.getVerificationResult(session_id);
+```
+
 #### `VisionCameraModule`
 
-Core module for camera operations and permissions.
+Module for camera operations and permissions.
 
 ```tsx
 import { VisionCameraModule } from '@transfergratis/react-native-sdk';
@@ -187,6 +479,9 @@ import { VisionCameraModule } from '@transfergratis/react-native-sdk';
 // Request permissions
 const hasPermissions = await VisionCameraModule.requestAllPermissions();
 
+// Check permissions
+const hasAllPermissions = await VisionCameraModule.hasAllPermissions();
+
 // Get camera devices
 const frontCamera = await VisionCameraModule.getFrontCameraDevice();
 const backCamera = await VisionCameraModule.getBackCameraDevice();
@@ -195,6 +490,43 @@ const backCamera = await VisionCameraModule.getBackCameraDevice();
 const isAvailable = await VisionCameraModule.isCameraAvailable();
 ```
 
+### Hooks
+
+#### `useTemplateKYCFlow`
+
+Hook for managing template-based KYC flow.
+
+```tsx
+import { useTemplateKYCFlow, TemplateKYCFlowProvider } from '@transfergratis/react-native-sdk';
+
+// In your component
+const { state, actions, currentComponent, progress } = useTemplateKYCFlow();
+```
+
+#### `useOrientationVideo`
+
+Hook for orientation video capture.
+
+```tsx
+import { useOrientationVideo, KYCService } from '@transfergratis/react-native-sdk';
+
+const kycService = new KYCService('https://api.yourdomain.com', 'your-api-key');
+const { state, actions } = useOrientationVideo(kycService, {
+  duration: 10,
+  maxRetakes: 2,
+});
+```
+
+#### `useLocation`
+
+Hook for location capture.
+
+```tsx
+import { useLocation } from '@transfergratis/react-native-sdk';
+
+const { location, error, requestPermission, getCurrentLocation } = useLocation();
+```
+
 ## 🎨 Customization
 
 ### Custom Overlay Example
@@ -255,7 +587,7 @@ const styles = StyleSheet.create({
 
 ### Orientation Video Processing
 
-The SDK now includes advanced liveness detection through orientation video processing. This feature captures and analyzes short videos to verify that a real person is present during the KYC process.
+The SDK includes advanced liveness detection through orientation video processing. This feature captures and analyzes short videos to verify that a real person is present during the KYC process.
 
 #### Basic Usage
 
@@ -282,11 +614,9 @@ export default function LivenessDetection() {
       }}
       onComplete={(result) => {
         console.log('Liveness detection result:', result);
-        // Handle successful processing
       }}
       onError={(error) => {
         console.error('Liveness detection error:', error);
-        // Handle error
       }}
       kycService={kycService}
     />
@@ -294,7 +624,7 @@ export default function LivenessDetection() {
 }
 ```
 
-#### Using the Custom Hook
+#### Using the Hook
 
 ```tsx
 import React from 'react';
@@ -324,7 +654,7 @@ export default function LivenessDetectionHook() {
 
 #### API Response Format
 
-The orientation video processing returns detailed results for each face orientation:
+Orientation video processing returns detailed results for each face orientation:
 
 ```json
 {
@@ -343,9 +673,7 @@ The orientation video processing returns detailed results for each face orientat
 }
 ```
 
-For more detailed information, see the [Orientation Video Processing Guide](./ORIENTATION_VIDEO_GUIDE.md).
-
-## 🔧 Configuration Plugin
+## 🔧 Plugin Configuration
 
 The SDK includes an Expo config plugin for automatic setup of native permissions and dependencies.
 
@@ -357,6 +685,12 @@ interface VisionCameraPluginProps {
   microphonePermissionText?: string;
   enableFrameProcessors?: boolean;
 }
+
+interface LocationPluginProps {
+  locationPermissionText?: string;
+  locationWhenInUsePermissionText?: string;
+  enableBackgroundLocation?: boolean;
+}
 ```
 
 ### Manual Plugin Usage
@@ -389,16 +723,28 @@ npm install
 npm run ios # or npm run android
 ```
 
-## 🚀 Publication npm
+### Testing
+
+```bash
+npm test
+```
+
+### Linting
+
+```bash
+npm run lint
+```
+
+## 🚀 npm Publishing
 
-### Pré-requis
+### Prerequisites
 
-- Compte npm avec droits de publication sur le package
-- Node 18+ et npm 9+
+- npm account with publish rights for the `@transfergratis/react-native-sdk` package
+- Node 18+ and npm 9+
 
-### Étapes de release
+### Release Steps
 
-1) Installer et nettoyer
+1. **Install and clean**
 
 ```bash
 cd transfergratis-sdk
@@ -406,13 +752,13 @@ npm ci
 npm run clean
 ```
 
-2) Builder le SDK
+2. **Build the SDK**
 
 ```bash
 npm run build
 ```
 
-3) Vérifier le contenu qui sera publié
+3. **Verify content to be published**
 
 ```bash
 npm publish --dry-run
@@ -420,98 +766,85 @@ npm pack
 tar -tf transfergratis-react-native-sdk-*.tgz | cat
 ```
 
-4) Monter la version (exemples)
+4. **Bump version**
 
 ```bash
 # patch | minor | major | prerelease
 npm version patch -m "release: %s"
 ```
 
-5) Connexion npm (si nécessaire)
+5. **npm login (if needed)**
 
 ```bash
 npm whoami || npm login
 ```
 
-6) Publier sur npm (public)
+6. **Publish to npm (public)**
 
 ```bash
 npm publish --access public
 ```
 
-- Avec 2FA:
+- With 2FA:
 
 ```bash
 npm publish --access public --otp=123456
 ```
 
-- Publier une préversion (tag beta):
+- Publish a pre-release (beta tag):
 
 ```bash
 npm publish --tag beta --access public
 ```
 
-7) Pousser les tags git
+7. **Push git tags**
 
 ```bash
 git push && git push --tags
 ```
 
-8) Vérifier la version publiée
+8. **Verify published version**
 
 ```bash
 npm info @transfergratis/react-native-sdk version
 ```
 
-## 📝 Migration from Legacy Camera
+## 📝 Supported Document Types
 
-If you're upgrading from the legacy native camera implementation:
+The SDK supports several government document types:
 
-### Component Changes
+- `identity_card` - Identity card
+- `passport` - Passport
+- `drivers_licence` - Driver's license
+- `health_insurance_card` - Health insurance card
+- `permanent_residence` - Permanent residence permit
+- `national_id` - National ID card
+- `work_permit` - Work permit
 
-```tsx
-// Old (Legacy)
-import { NativeCameraView } from 'transfergratis-sdk';
-
-<NativeCameraView
-  instructions="Take a photo"
-  showCamera={true}
-  onCapture={(event) => {
-    if (event.action === 'capture') {
-      console.log(event.imagePath);
-    }
-  }}
-/>
+## 🌍 Multilingual Support
 
-// New (Vision Camera)
-import { EnhancedCameraView } from 'transfergratis-sdk';
-
-<EnhancedCameraView
-  instructions="Take a photo"
-  showCamera={true}
-  onCapture={(result) => {
-    if (result.success) {
-      console.log(result.path);
-    }
-  }}
-/>
-```
-
-### Module Changes
+The SDK currently supports French and English. Texts can be customized via the JSON template system using `LocalizedText` objects:
 
 ```tsx
-// Old
-import { NativeCameraModule } from 'transfergratis-sdk';
-const hasPermission = await NativeCameraModule.requestCameraPermission();
-
-// New
-import { VisionCameraModule } from 'transfergratis-sdk';
-const hasPermissions = await VisionCameraModule.requestAllPermissions();
+{
+  labels: {
+    en: "Upload your ID card",
+    fr: "Téléversez votre carte d'identité"
+  }
+}
 ```
 
 ## 🚨 Breaking Changes
 
-### v2.0.0
+### v0.1.10
+
+- **JSON Template System**: New JSON-based configuration system
+- **Specialized KYC Components**: New components for each KYC flow step
+- **Web Support**: Added support for web applications
+- **Liveness Detection Improvements**: Enhanced orientation video processing
+- **Multilingual Support**: Improved support for multiple languages
+
+### v0.1.0
 
 - **Camera Implementation**: Switched from custom native views to react-native-vision-camera
 - **Permissions**: Now requires both camera and microphone permissions
@@ -534,6 +867,12 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 For support, email support@transfergratis.com or open an issue on GitHub.
 
+## 📚 Additional Resources
+
+- [Vision Camera Documentation](https://react-native-vision-camera.com/)
+- [Expo Documentation](https://docs.expo.dev/)
+- [GitHub Repository](https://github.com/TransfergratisOrg/KYC-User-Frontend)
+
 ---
 
 Built with ❤️ by the TransferGratis Team