@sanctum-key/react-native-sdk 1.0.0

package/src/hooks/useTemplateKYCFlow.tsx

@@ -0,0 +1,1051 @@
+import React, { useState, useCallback, useMemo, createContext, useContext, ReactNode, useEffect } from 'react';
+import { KYCTemplate, TemplateState, TemplateActions, UseTemplateReturn, TemplateComponent, GovernmentDocumentType, VerificationState } from '../types/KYC.types';
+import { KycEnvironment } from '../types/env.types';
+import kycService, { authentification, truncateFields } from '../modules/api/KYCService';
+import useI18n from './useI18n';
+import { logger } from '../utils/logger';
+import { countryMapping } from '../config/region_mapping';
+import { countryData } from '../config/countriesData';
+
+// Context pour le provider
+interface TemplateKYCFlowContextType {
+  state: TemplateState;
+  actions: TemplateActions;
+  currentComponent: any;
+  progress: number;
+  canGoNext: boolean;
+  canGoPrevious: boolean;
+  isComplete: boolean;
+  getLocalizedText: (text: { en: string; fr: string;[key: string]: string }) => string;
+  initializeSession: () => Promise<void>;
+  env: KycEnvironment;
+  apiKey?: string;
+}
+
+const TemplateKYCFlowContext = createContext<TemplateKYCFlowContextType | undefined>(undefined);
+
+// Provider component
+interface TemplateKYCFlowProviderProps {
+  children: ReactNode;
+  template: KYCTemplate;
+  onComplete?: (data: VerificationState) => void;
+  onError?: (error: string) => void;
+  onCancel?: () => void;
+  initialLanguage?: string;
+  apiKey?: string;
+  env?: KycEnvironment;
+  existingSessionId?: string;
+  /** Index in template.components where to resume (0-based). Simple to store in template table. */
+  initialComponentIndex?: number;
+  /** Pays / type de document depuis l'URL de reprise — évite de dépendre du backend pour afficher les pays. */
+  initialCountryResume?: { code: string; documentType: string; region?: string };
+}
+
+export const TemplateKYCFlowProvider: React.FC<TemplateKYCFlowProviderProps> = ({
+  children,
+  template,
+  onComplete,
+  onError,
+  onCancel,
+  initialLanguage = 'en',
+  apiKey,
+  env = 'PRODUCTION',
+  existingSessionId,
+  initialComponentIndex,
+  initialCountryResume,
+}) => {
+  const hookResult = useTemplateKYCFlow(template, onComplete, onError, onCancel, initialLanguage, apiKey, env, existingSessionId, initialComponentIndex, initialCountryResume);
+
+  return (
+    <TemplateKYCFlowContext.Provider value={hookResult}>
+      {children}
+    </TemplateKYCFlowContext.Provider>
+  );
+};
+
+// Hook pour utiliser le context
+export const useTemplateKYCFlowContext = (): TemplateKYCFlowContextType => {
+  const context = useContext(TemplateKYCFlowContext);
+  if (!context) {
+    throw new Error('useTemplateKYCFlowContext must be used within a TemplateKYCFlowProvider');
+  }
+  return context;
+};
+
+export const useTemplateKYCFlow = (
+  template: KYCTemplate,
+  onComplete?: (data: VerificationState) => void,
+  onError?: (error: string) => void,
+  onCancel?: () => void,
+  initialLanguage: string = 'en',
+  apiKey?: string,
+  env: KycEnvironment = 'PRODUCTION',
+  existingSessionId?: string,
+  initialComponentIndex?: number,
+  initialCountryResume?: { code: string; documentType: string; region?: string },
+): UseTemplateReturn => {
+
+  const { setLocale } = useI18n();
+
+  useEffect(() => {
+    setLocale(initialLanguage);
+  }, [initialLanguage, apiKey]);
+
+  // Helpers to align SDK steps with backend actions/templates
+  const isUiOnlyStep = useCallback((type: TemplateComponent['type']) => {
+    return type === 'verification_progress';
+  }, [apiKey]);
+
+
+
+  const ensureReviewSubmitStep = useCallback((tpl: KYCTemplate): KYCTemplate => {
+    const hasReview = tpl.components.some(c => c.type === 'review_submit');
+    if (hasReview) return tpl;
+
+    const lastOrder = tpl.components.reduce((acc, c) => Math.max(acc, c.order ?? 0), 0);
+    const lastId = tpl.components.reduce((acc, c) => Math.max(acc, c.id), 0);
+
+    const reviewComponent: TemplateComponent = {
+      id: lastId + 1,
+      type: 'review_submit',
+      order: lastOrder + 1,
+      labels: { en: 'Review & Submit', fr: 'Revoir & Soumettre' },
+      instructions: { en: 'Confirm and submit', fr: 'Confirmer et soumettre' },
+      ui: { buttonText: { en: 'Complete Verification', fr: 'Terminer la vérification' } },
+      // @ts-ignore - config unused for review component
+      config: {},
+    } as TemplateComponent;
+
+    return {
+      ...tpl,
+      components: [...tpl.components, reviewComponent],
+    };
+  }, [apiKey]);
+
+  const ensureVerificationProgressStep = useCallback((tpl: KYCTemplate): KYCTemplate => {
+    const hasVerification = tpl.components.some(c => c.type === 'verification_progress');
+    if (hasVerification) return tpl;
+
+    const lastOrder = tpl.components.reduce((acc, c) => Math.max(acc, c.order ?? 0), 0);
+    const lastId = tpl.components.reduce((acc, c) => Math.max(acc, c.id), 0);
+
+    const verificationComponent: TemplateComponent = {
+      id: lastId + 2,
+      type: 'verification_progress',
+      order: lastOrder + 2,
+      labels: { en: 'Verification', fr: 'Vérification' },
+      instructions: { en: 'We\'re reviewing your documents', fr: 'Nous analysons vos documents' },
+      ui: { buttonText: { en: '', fr: '' } },
+      // @ts-ignore - config unused for progress component
+      config: {},
+    } as TemplateComponent;
+
+    return {
+      ...tpl,
+      components: [...tpl.components, verificationComponent],
+    };
+  }, [apiKey]);
+
+  const templateWithReview = useMemo(() => ensureReviewSubmitStep(template), [template, ensureReviewSubmitStep, apiKey]);
+  const templateWithReviewAndVerification = useMemo(() => ensureVerificationProgressStep(templateWithReview), [templateWithReview, ensureVerificationProgressStep, apiKey]);
+
+  // État initial du flux (initialComponentIndex = index dans template.components pour reprendre au bon composant)
+  const buildInitialState = (): TemplateState => {
+    let resumeAtIndex = 0;
+    let completedComponents: number[] = [];
+    let initialComponentData: Record<number, unknown> = {};
+
+    logger.log('buildInitialState called', { initialComponentIndex, existingSessionId, initialCountryResume });
+
+    if (initialComponentIndex !== undefined && initialComponentIndex >= 0) {
+      const maxIndex = templateWithReviewAndVerification.components.length - 1;
+      const requestedIndex = Math.min(initialComponentIndex, maxIndex);
+      const requestedComponent = templateWithReviewAndVerification.components[requestedIndex];
+
+      logger.log('Processing initialComponentIndex (component in template)', {
+        initialComponentIndex,
+        requestedIndex,
+        maxIndex,
+        componentType: requestedComponent?.type,
+        componentId: requestedComponent?.id,
+      });
+
+      // Reprendre au composant en cours (id_card, selfie, etc.)
+      if (requestedComponent?.type === 'id_card') {
+        if (existingSessionId) {
+          logger.log('id_card with existing session - staying at id_card');
+          resumeAtIndex = requestedIndex;
+          if (resumeAtIndex > 0) {
+            completedComponents = templateWithReviewAndVerification.components
+              .slice(0, resumeAtIndex)
+              .map(component => component.id);
+          }
+        } else {
+          const countrySelectionIndex = templateWithReviewAndVerification.components.findIndex(
+            c => c.type === 'country_selection'
+          );
+          logger.log('id_card without session - going back to country_selection', { countrySelectionIndex });
+          if (countrySelectionIndex >= 0) {
+            resumeAtIndex = countrySelectionIndex;
+            if (countrySelectionIndex > 0) {
+              completedComponents = templateWithReviewAndVerification.components
+                .slice(0, countrySelectionIndex)
+                .map(component => component.id);
+            }
+          } else {
+            resumeAtIndex = 0;
+          }
+        }
+      } else if (requestedComponent?.type === 'review_submit') {
+        resumeAtIndex = requestedIndex;
+        completedComponents = [];
+      } else {
+        resumeAtIndex = requestedIndex;
+        if (resumeAtIndex > 0) {
+          completedComponents = templateWithReviewAndVerification.components
+            .slice(0, resumeAtIndex)
+            .map(component => component.id);
+        }
+      }
+
+      logger.log('Final initial state (resume at component index)', {
+        resumeAtIndex,
+        completedComponentsCount: completedComponents.length,
+        componentAtResume: templateWithReviewAndVerification.components[resumeAtIndex]?.type,
+      });
+    }
+
+    if (initialCountryResume?.code && initialCountryResume?.documentType) {
+      const countrySel = templateWithReviewAndVerification.components.find(c => c.type === 'country_selection');
+      if (countrySel && countryData[initialCountryResume.code]) {
+        initialComponentData[countrySel.id] = {
+          code: initialCountryResume.code,
+          documentType: initialCountryResume.documentType,
+          region: initialCountryResume.region || 'root',
+          ...countryData[initialCountryResume.code],
+        };
+        logger.log('Prefilled country_selection from URL', { code: initialCountryResume.code, documentType: initialCountryResume.documentType });
+      }
+    }
+
+    return {
+      template: templateWithReviewAndVerification,
+      currentComponentIndex: resumeAtIndex,
+      completedComponents: completedComponents,
+      componentData: initialComponentData,
+      errors: {},
+      isProcessing: false,
+      currentLanguage: initialLanguage,
+      showCustomStepper: true,
+      session: {
+        session_id: existingSessionId || '',
+        token: '',
+        isInitialized: false,
+        isProcessing: false,
+        error: null,
+        sessionDataRestored: !existingSessionId || Boolean(initialCountryResume?.code && initialCountryResume?.documentType),
+      },
+      verification: {
+        status: 'idle',
+      },
+    };
+  };
+
+  // État du flux
+  const [state, setState] = useState<TemplateState>(() => buildInitialState());
+  
+  // Fonction utilitaire pour convertir base64 en data URI pour l'affichage
+  const base64ToDataUri = useCallback((base64: string, mimeType: string = 'image/jpeg'): string => {
+    // Si c'est déjà une data URI, retourner tel quel
+    if (base64.startsWith('data:')) {
+      return base64;
+    }
+    // Sinon, créer une data URI
+    return `data:${mimeType};base64,${base64}`;
+  }, []);
+
+  // Charger les données de session si on reprend une session existante
+  useEffect(() => {
+    const loadSessionData = async () => {
+      // Ne charger que si on a une session existante
+      if (!existingSessionId) {
+        logger.log('No existingSessionId, skipping data load');
+        return;
+      }
+
+      // Si initialComponentIndex n'est pas défini ou est 0, on ne charge pas (début de session)
+      if (initialComponentIndex === undefined || initialComponentIndex === 0) {
+        logger.log('initialComponentIndex is 0 or undefined, skipping data load');
+        return;
+      }
+
+      // Attendre que la session soit initialisée
+      if (!state.session.isInitialized || !state.session.session_id) {
+        logger.log('Session not initialized yet, waiting...', {
+          isInitialized: state.session.isInitialized,
+          sessionId: state.session.session_id
+        });
+        return;
+      }
+
+      try {
+        logger.log('Loading session data for resume:', { sessionId: existingSessionId, componentIndex: initialComponentIndex });
+        const result = await kycService.getVerificationResult(state.session.session_id);
+        const sessionData = result[state.session.session_id]?.data;
+
+        if (sessionData) {
+          // Restaurer les données des composants depuis la session
+          // Utiliser 'as any' car VerificationResult peut avoir des propriétés dynamiques
+          const data: any = sessionData;
+          const restoredComponentData: Record<number, any> = {};
+
+          // Parcourir les composants jusqu'au composant de reprise (inclu) pour restaurer leurs données
+          templateWithReviewAndVerification.components
+            .slice(0, initialComponentIndex + 1)
+            .forEach((component) => {
+              // Essayer de restaurer les données selon le type de composant
+              if (component.type === 'id_card' || component.type === 'file_upload') {
+                // Les documents peuvent être dans différentes structures
+                let documents: any = null;
+                
+                // Chercher dans différentes structures possibles
+                if (data.documents) {
+                  documents = data.documents;
+                } else if (data.user_data?.documents) {
+                  documents = data.user_data.documents;
+                } else if (data.document_images) {
+                  documents = data.document_images;
+                }
+
+                if (documents) {
+                  // Convertir les images base64 en format utilisable
+                  const restoredDocuments: Record<string, any> = {};
+                  
+                  Object.keys(documents).forEach((key) => {
+                    const doc = documents[key];
+                    if (typeof doc === 'object' && doc !== null) {
+                      // Si on a un fichier base64, créer une structure avec dir et file
+                      if (doc.file || doc.base64) {
+                        const base64Data = doc.file || doc.base64;
+                        restoredDocuments[key] = {
+                          dir: base64ToDataUri(base64Data), // Utiliser data URI pour l'affichage
+                          file: base64Data, // Garder le base64 pour l'envoi
+                          mrz: doc.mrz || '',
+                          templatePath: doc.templatePath || '',
+                        };
+                      } else {
+                        // Sinon, garder la structure originale
+                        restoredDocuments[key] = doc;
+                      }
+                    } else if (typeof doc === 'string') {
+                      // Si c'est directement une string base64
+                      restoredDocuments[key] = {
+                        dir: base64ToDataUri(doc),
+                        file: doc,
+                        mrz: '',
+                        templatePath: '',
+                      };
+                    }
+                  });
+
+                  if (Object.keys(restoredDocuments).length > 0) {
+                    restoredComponentData[component.id] = restoredDocuments;
+                  }
+                }
+              } else if (component.type === 'selfie') {
+                // Les selfies peuvent être dans sessionData.selfie_info
+                if (data.selfie_info) {
+                  const selfieData: Record<string, any> = {};
+                  const selfieInfo: any = data.selfie_info;
+                  
+                  // Si selfie_info contient une image
+                  if (selfieInfo.image) {
+                    const base64Image = selfieInfo.image;
+                    selfieData['front'] = {
+                      dir: base64ToDataUri(base64Image),
+                      file: base64Image,
+                    };
+                  }
+                  
+                  // Si on a plusieurs orientations
+                  if (selfieInfo.orientations) {
+                    Object.keys(selfieInfo.orientations).forEach((orientation) => {
+                      const img = selfieInfo.orientations[orientation];
+                      if (img) {
+                        selfieData[orientation] = {
+                          dir: base64ToDataUri(img),
+                          file: img,
+                        };
+                      }
+                    });
+                  }
+
+                  if (Object.keys(selfieData).length > 0) {
+                    restoredComponentData[component.id] = selfieData;
+                  }
+                }
+              } else if (component.type === 'country_selection') {
+                // Reconstruire country_selection au format attendu par IDCardCapture / CountrySelectionTemplate (code, documentType, region, regionMapping)
+                const meta = data.metadata || data.user_data || data;
+                const code = meta.country || meta.country_code || meta.code;
+                const documentType = meta.document_type || meta.documentType;
+                const region = meta.region;
+                if (code && documentType != null) {
+                  const country = countryData[code];
+                  const mapping = countryMapping[code as keyof typeof countryMapping];
+                  if (country) {
+                    restoredComponentData[component.id] = {
+                      code,
+                      ...country,
+                      documentType,
+                      region: region || undefined,
+                      regionMapping: mapping || undefined,
+                    };
+                    logger.log('Restored country_selection for resume', { code, documentType, region });
+                  } else {
+                    restoredComponentData[component.id] = { code, documentType, region: region || undefined, regionMapping: mapping || undefined };
+                  }
+                } else if (data.metadata || data.user_data) {
+                  restoredComponentData[component.id] = {
+                    ...(data.metadata || {}),
+                    ...(data.user_data || {}),
+                  };
+                }
+              } else if (component.type === 'location') {
+                // Les données de localisation peuvent être dans metadata
+                if (data.metadata?.location || data.user_data?.location) {
+                  restoredComponentData[component.id] = {
+                    ...(data.metadata?.location || {}),
+                    ...(data.user_data?.location || {}),
+                  };
+                }
+              }
+            });
+
+          // Fallback: si pas de country_selection restauré mais on a des documents avec templatePath, déduire code/documentType (ex. "templates/national_id_CM_front.jpg")
+          const countrySelectionComponent = templateWithReviewAndVerification.components.find(c => c.type === 'country_selection');
+          if (countrySelectionComponent && !restoredComponentData[countrySelectionComponent.id] && data.documents) {
+            const docs = data.documents as Record<string, { templatePath?: string }>;
+            const firstDoc = Object.values(docs).find(d => d?.templatePath);
+            const path = firstDoc?.templatePath || '';
+            const match = path.match(/([a-z_]+)_([A-Z]{2})(?:_|$)/i) || path.match(/([A-Z]{2})/);
+            const code = match ? (match[2] || match[1]).toUpperCase().slice(0, 2) : null;
+            const docTypeFromPath = path.match(/(national_id|identity_card|passport|passport_card)/i)?.[1]?.toLowerCase().replace('identity_card', 'national_id') || null;
+            if (code && countryData[code]) {
+              const documentType = docTypeFromPath || 'national_id';
+              const mapping = countryMapping[code as keyof typeof countryMapping];
+              const country = countryData[code];
+              restoredComponentData[countrySelectionComponent.id] = {
+                code,
+                ...country,
+                documentType,
+                region: undefined,
+                regionMapping: mapping || undefined,
+              };
+              logger.log('Restored country_selection from document templatePath', { code, documentType, path });
+            }
+          }
+
+          // Mettre à jour l'état avec les données restaurées
+          if (Object.keys(restoredComponentData).length > 0) {
+            logger.log('Session data restored - components:', Object.keys(restoredComponentData));
+            logger.log('Session data restored - sample data:', truncateFields(restoredComponentData));
+            setState(prev => ({
+              ...prev,
+              componentData: {
+                ...prev.componentData,
+                ...restoredComponentData,
+              },
+              session: { ...prev.session, sessionDataRestored: true },
+            }));
+            logger.log('Component data updated in state');
+          } else {
+            logger.log('No component data to restore from session');
+            setState(prev => ({ ...prev, session: { ...prev.session, sessionDataRestored: true } }));
+          }
+        } else {
+          setState(prev => ({ ...prev, session: { ...prev.session, sessionDataRestored: true } }));
+        }
+      } catch (error) {
+        logger.error('Error loading session data:', truncateFields(error));
+        setState(prev => ({ ...prev, session: { ...prev.session, sessionDataRestored: true } }));
+      }
+    };
+
+    loadSessionData();
+  }, [existingSessionId, initialComponentIndex, state.session.isInitialized, state.session.session_id, templateWithReviewAndVerification.components, base64ToDataUri]);
+
+  // Si l'index pointe vers Review alors que des étapes ne sont pas complétées, ramener à la première étape incomplète
+  useEffect(() => {
+    const comp = state.template.components[state.currentComponentIndex];
+    if (!comp || comp.type !== 'review_submit') return;
+    const nonReview = state.template.components.filter(
+      c => c.type !== 'review_submit' && c.type !== 'verification_progress'
+    );
+    if (nonReview.every(c => state.completedComponents.includes(c.id))) return;
+    const firstIncomplete = nonReview.find(c => !state.completedComponents.includes(c.id));
+    if (!firstIncomplete) return;
+    const targetIndex = state.template.components.findIndex(c => c.id === firstIncomplete.id);
+    if (targetIndex >= 0 && targetIndex !== state.currentComponentIndex) {
+      setState(prev => ({ ...prev, currentComponentIndex: targetIndex }));
+    }
+  }, [state.currentComponentIndex, state.completedComponents, state.template.components]);
+
+  const mapComponentTypeToAction = useCallback((type: TemplateComponent['type']): string | null => {
+    switch (type) {
+      case 'id_card':
+      case 'file_upload':
+        return 'document_upload';
+      case 'selfie':
+        return 'selfie_capture';
+      case 'location':
+        return 'location_permission';
+      case 'review_submit':
+        return 'final_submit';
+      case 'country_selection':
+        // No direct backend action; pack into metadata of next actionable step
+        return null;
+      case 'welcome':
+        // UI-only step, no backend action needed
+        return null;
+      case 'initialization':
+        return 'initialize_session';
+      case 'verification_progress':
+        return null; // UI-only
+      default:
+        return null;
+    }
+  }, []);
+
+  const chooseTemplateId = useCallback((tpl: KYCTemplate): string => {
+    const types = tpl.components.map(c => c.type);
+    const hasLocation = types.includes('location');
+    const hasSelfie = types.includes('selfie');
+    const hasIdDoc = types.includes('id_card') || types.includes('file_upload');
+    // Simple heuristic to map to backend examples
+    if (hasLocation && hasSelfie && hasIdDoc) return 'enhanced_id';
+    if (hasSelfie && hasIdDoc) return 'standard_passport';
+    return 'standard_passport';
+  }, [apiKey]);
+
+
+  const computeServerStepIndex = useCallback((tpl: KYCTemplate, upToIndex: number): number => {
+    // Count actionable steps before the current component (exclude UI-only and country_selection)
+    const actionable = tpl.components
+      .slice(0, upToIndex)
+      .filter(c => !isUiOnlyStep(c.type) && mapComponentTypeToAction(c.type) !== null);
+    return actionable.length; // 0-based
+  }, [isUiOnlyStep, mapComponentTypeToAction, apiKey]);
+
+  // Build backend-friendly payloads per action
+  const buildPayloadForComponent = useCallback((action: string | null, component: TemplateComponent, rawData: any, templateId: string, step: number) => {
+    console.log('apiKey in buildPayloadForComponent', apiKey);
+
+    const base = { template_id: templateId || null, templateId: templateId || null, step: component.order, permissionGranted: true } as any;
+    if (!action) {
+      return base;
+    }
+    // Document upload expects documents; include country_selection in metadata so resume can restore it
+    if (action === 'document_upload') {
+      const documents: Record<string, any> = {};
+      if (rawData && typeof rawData === 'object') {
+        Object.keys(rawData).forEach((key) => {
+          documents[key] = rawData[key];
+        });
+      }
+      const countryComp = state.template.components.find(c => c.type === 'country_selection');
+      const countryDataForPayload = countryComp ? state.componentData[countryComp.id] : null;
+      const metadata: Record<string, unknown> = {};
+      if (countryDataForPayload?.code) {
+        metadata.country = countryDataForPayload.code;
+        metadata.document_type = countryDataForPayload.documentType;
+        if (countryDataForPayload.region != null) metadata.region = countryDataForPayload.region;
+      }
+      return {
+        ...base,
+        documents,
+        ...(Object.keys(metadata).length > 0 ? { metadata } : {}),
+      };
+    }
+
+    if (action === 'selfie_capture') {
+      const documents: Record<string, any> = {};
+      if (rawData && typeof rawData === 'object') {
+
+        Object.keys(rawData).forEach((key) => {
+          documents[key] = rawData[key];
+        });
+      }
+      const idCardID = Object.keys(state.componentData).find((c: string) => c === "1");
+      if (idCardID) {
+        const _idCardData = state.componentData[idCardID];
+        const documentType = _idCardData?.documentType;
+        // Map national_id to identity_card for selfie capture
+        const mappedDocumentType = documentType === 'national_id' ? 'identity_card' : (documentType as GovernmentDocumentType || 'identity_card');
+        return { ...base, documents, country: _idCardData?.country || '', documentType: mappedDocumentType };
+      }
+      return { ...base, documents };
+    }
+
+    if (action === 'location_permission') {
+      return { ...base, ...({ metadata: rawData || {} }), ...({ permissionGranted: true, }) };
+    }
+
+    // Default: wrap as metadata
+    return { ...base, metadata: { ...(rawData || {}) } };
+  }, [state.componentData, apiKey]);
+  // Ensure the template contains a final review step
+
+  // console.log('apiKey in useTemplateKYCFlow', apiKey);
+
+
+  // Composant actuel (peut être redirigé si on pointe vers Review alors que le flux n'est pas terminé)
+  const currentComponent = useMemo(() => {
+    const comp = state.template.components[state.currentComponentIndex] || null;
+    if (!comp || comp.type !== 'review_submit') return comp;
+    const nonReview = state.template.components.filter(
+      c => c.type !== 'review_submit' && c.type !== 'verification_progress'
+    );
+    const allDone = nonReview.every(c => state.completedComponents.includes(c.id));
+    if (allDone) return comp;
+    const firstIncomplete = nonReview.find(c => !state.completedComponents.includes(c.id));
+    return firstIncomplete || comp;
+  }, [state.template.components, state.currentComponentIndex, state.completedComponents, apiKey]);
+
+  // Progression du flux (basée sur le composant effectivement affiché)
+  const progress = useMemo(() => {
+    const idx = currentComponent
+      ? state.template.components.findIndex(c => c.id === currentComponent.id)
+      : state.currentComponentIndex;
+    const i = idx >= 0 ? idx : state.currentComponentIndex;
+    return state.template.components.length > 0
+      ? ((i + 1) / state.template.components.length) * 100
+      : 0;
+  }, [currentComponent, state.template.components, state.currentComponentIndex, apiKey]);
+
+  // Vérifications de navigation
+  const canGoNext = useMemo(() => {
+    return state.currentComponentIndex < state.template.components.length - 1;
+  }, [state.currentComponentIndex, state.template.components.length, apiKey]);
+
+  const canGoPrevious = useMemo(() => {
+    return state.currentComponentIndex > 0;
+  }, [state.currentComponentIndex, apiKey]);
+
+  const isComplete = useMemo(() => {
+    const atReview = state.template.components[state.currentComponentIndex]?.type === 'review_submit';
+    const nonReviewCount = state.template.components.filter(c => c.type !== 'review_submit').length;
+    const completedNonReview = state.completedComponents.length >= nonReviewCount;
+    return atReview && completedNonReview;
+  }, [state.currentComponentIndex, state.completedComponents.length, state.template.components, apiKey]);
+
+  // Fonction pour obtenir le texte localisé
+  const getLocalizedText = useCallback((text: { en: string; fr: string;[key: string]: string }): string => {
+    return text[state.currentLanguage] || text.en || '';
+  }, [state.currentLanguage, apiKey]);
+
+  const initializeSession = useCallback(async () => {
+    try {
+      setState(prev => ({
+        ...prev,
+        session: {
+          ...prev.session,
+          isInitialized: false,
+          isProcessing: true,
+          error: null,
+        },
+      }));
+      logger.log('Initializing session');
+
+      const token = apiKey ? undefined : await authentification();
+      console.log('token in initializeSession', { token, apiKey },);
+
+      // Check if we already have a session ID from URL params (passed via state or prop)
+      let session;
+      const existingSessionId = state.session.session_id; // This might be set from initial props if we add logic for it
+
+      if (existingSessionId && existingSessionId.length > 0) {
+        logger.log('Resuming existing session:', existingSessionId);
+        // Verify existence/validity if needed, for now trust the ID and just fetch/use it
+        session = { session_id: existingSessionId };
+      } else {
+        session = await kycService.newSession({ token, apiKey });
+      }
+
+      // Align backend flow from step 0 with initialize_session
+      try {
+        const templateId = chooseTemplateId(templateWithReviewAndVerification);
+        await kycService.verificationSession({
+          session_id: session.session_id,
+          step: 0,
+          data: { template_id: templateId, metadata: { language: initialLanguage } },
+          templateId: templateId,
+          token: token,
+          action: 'initialize_session',
+          apiKey: apiKey,
+        });
+      } catch (e) {
+        logger.error('Error initializing session:', JSON.stringify(e, null, 2));
+        // Non-fatal: we will surface errors via state below if needed
+      }
+
+      setState(prev => ({
+        ...prev,
+        session: {
+          ...prev.session,
+          session_id: session.session_id,
+          token: token,
+          isInitialized: true,
+          isProcessing: false,
+          error: null,
+        }
+      }));
+    } catch (error) {
+
+      logger.error('Error initializing session:', JSON.stringify(error, null, 2));
+      setState(prev => ({
+        ...prev,
+        session: {
+          ...prev.session,
+          isInitialized: false,
+          isProcessing: false,
+          error: "Erreur lors de l'initialisation de la session",
+        },
+      }));
+    }
+  }, [apiKey]);
+
+  // When user switches device: resume with existingSessionId + initialStep — ensure session is initialized so loadSessionData runs
+  useEffect(() => {
+    if (!existingSessionId || state.session.isInitialized) return;
+    if (state.session.session_id !== existingSessionId) return;
+    logger.log('Resuming on new device: initializing session so data can load', { existingSessionId, initialComponentIndex });
+    initializeSession();
+  }, [existingSessionId, state.session.session_id, state.session.isInitialized, initializeSession]);
+
+  // Validation d'un composant (dataOverride permet de valider sans attendre la mise à jour du state)
+  const validateComponent = useCallback((componentId: number, dataOverride?: any): boolean => {
+    const component = state.template.components.find(c => c.id === componentId);
+    if (!component) return false;
+
+    const componentData = dataOverride !== undefined ? dataOverride : state.componentData[componentId];
+
+    switch (component.type) {
+      case 'id_card':
+        // Vérifier si au moins un côté a été capturé
+        return componentData && Object.keys(componentData).length > 0;
+
+      case 'selfie':
+        // Vérifier si toutes les orientations ont été capturées
+        const config = component.config as any;
+        const orientations = config.orientations || ['front'];
+        return componentData && orientations.every((orientation: string) => componentData[orientation]);
+
+      case 'file_upload':
+        // Vérifier si un fichier a été uploadé
+        return componentData && componentData.file;
+
+      case 'location':
+        // Vérifier si la localisation a été obtenue
+        return componentData && componentData.latitude && componentData.longitude;
+
+      case 'country_selection':
+        // Vérifier si un pays a été sélectionné
+        logger.log("componentData", truncateFields(componentData), componentId);
+
+        return componentData && componentData.code && componentData.regionMapping;
+
+      case 'welcome':
+        // Welcome is valid once user has given consent (componentData is set when they click Get Started)
+        return componentData && componentData.consentGiven !== false;
+
+      case 'email_verification':
+        return componentData && componentData.verified === true;
+
+      case 'phone_verification':
+        return componentData && componentData.verified === true;
+
+      case 'personal_information':
+        return componentData && Object.keys(componentData).length > 0;
+
+      case 'additional_documents':
+        // Optional by default in template config, but if required we should check based on config
+        // For now, return true or check length if present
+        return true;
+
+      case 'review_submit':
+        return true;
+      default:
+        return false;
+    }
+  }, [state.template.components, state.componentData, apiKey]);
+
+  // Actions du flux
+  const actions: TemplateActions = {
+    // Initialiser le template
+    initializeTemplate: useCallback((newTemplate: KYCTemplate) => {
+      const withReview = ensureReviewSubmitStep(newTemplate);
+      const withVerification = ensureVerificationProgressStep(withReview);
+      setState(prev => ({
+        ...prev,
+        template: withVerification,
+        currentComponentIndex: 0,
+        completedComponents: [],
+        componentData: {},
+        errors: {},
+        isProcessing: false,
+        verification: { status: 'idle', result: undefined },
+      }));
+    }, [ensureReviewSubmitStep, ensureVerificationProgressStep, apiKey]),
+
+    // Passer au composant suivant (overrideData = données du step courant si déjà connues, évite un double clic)
+    nextComponent: useCallback(async (overrideData?: any) => {
+      if (!canGoNext) return;
+
+      const currentComp = state.template.components[state.currentComponentIndex];
+      if (!currentComp) return;
+
+      // Prevent multiple simultaneous calls
+      setState(prev => {
+        if (prev.isProcessing) {
+          return prev;
+        }
+        return {
+          ...prev,
+          isProcessing: true,
+        };
+      });
+      // Valider avec override ou state
+      if (!validateComponent(currentComp.id, overrideData)) {
+        setState(prev => ({
+          ...prev,
+          isProcessing: false,
+          errors: {
+            ...prev.errors,
+            [currentComp.id]: state.currentLanguage === "en" ? "please complete this step before moving on" : " 'Veuillez compléter cette étape avant de continuer'"
+          }
+        }));
+        return;
+
+      }
+
+      try {
+        const component = state.template.components.find(c => c.id === currentComp.id);
+        if (!component) {
+          setState(prev => ({
+            ...prev,
+            isProcessing: false,
+          }));
+          return;
+        }
+
+        if (component.type === 'review_submit') {
+          setState(prev => ({
+            ...prev,
+            currentComponentIndex: prev.currentComponentIndex + 1,
+            completedComponents: [...prev.completedComponents, currentComp.id],
+            componentData: overrideData !== undefined ? { ...prev.componentData, [currentComp.id]: overrideData } : prev.componentData,
+            isProcessing: false,
+            verification: { status: 'in_progress' },
+            errors: { ...prev.errors, [currentComp.id]: '' }
+          }));
+          return;
+        }
+        // Determine backend action and step index
+        const action = mapComponentTypeToAction(component.type);
+        const templateId = chooseTemplateId(state.template);
+        const serverStep = computeServerStepIndex(state.template, state.currentComponentIndex);
+
+        // Optionally send initialize_session at step 0 before first actionable action
+        if (serverStep === 0) {
+          try {
+            // await kycService.verificationSession({
+            //   sessionId: state.session.session_id,
+            //   step: 0,
+            //   data: { template_id: templateId, metadata: { language: state.currentLanguage } },
+            //   templateId: templateId,
+            //   token: state.session.token,
+            //   action: 'initialize_session'
+            // });
+          } catch (e) {
+            // if init fails, surface error below in the main call handling
+          }
+        }
+
+        // Skip UI-only and data-only steps that have no backend action
+        if (!action) {
+          setState(prev => ({
+            ...prev,
+            currentComponentIndex: prev.currentComponentIndex + 1,
+            completedComponents: [...prev.completedComponents, currentComp.id],
+            componentData: overrideData !== undefined ? { ...prev.componentData, [currentComp.id]: overrideData } : prev.componentData,
+            isProcessing: false,
+            errors: { ...prev.errors, [currentComp.id]: '' }
+          }));
+          return;
+        }
+
+        const step = serverStep === 0 && action !== 'initialize_session' ? 1 : serverStep;
+        const currentStepData = overrideData !== undefined ? overrideData : state.componentData[currentComp.id];
+        const payloadData = buildPayloadForComponent(action, component, currentStepData, templateId, step);
+        console.log('payloadData', action, apiKey);
+
+        await kycService.verificationSession({
+          session_id: state.session.session_id,
+          step: step,
+          data: payloadData,
+          templateId: templateId,
+          token: state.session.token,
+          action: action,
+          apiKey: apiKey ?? "-",
+        });
+        logger.log("currentComp state", truncateFields(state));
+        setState(prev => ({
+          ...prev,
+          currentComponentIndex: prev.currentComponentIndex + 1,
+          completedComponents: [...prev.completedComponents, currentComp.id],
+          componentData: overrideData !== undefined ? { ...prev.componentData, [currentComp.id]: overrideData } : prev.componentData,
+          isProcessing: false,
+          ...(action === "location_permission" ? { permissionGranted: true } : {}),
+          errors: { ...prev.errors, [currentComp.id]: '' }
+        }));
+
+      } catch (error) {
+        logger.error('Error in nextComponent:', error);
+        setState(prev => ({
+          ...prev,
+          isProcessing: false,
+          errors: {
+            ...prev.errors,
+            [currentComp.id]: 'Erreur lors de la validation du composant'
+          }
+        }));
+      }
+
+    }, [canGoNext, state.currentComponentIndex, state.template.components, validateComponent, apiKey, state.session.session_id, state.session.token, buildPayloadForComponent, mapComponentTypeToAction, chooseTemplateId, state.currentLanguage]),
+
+    // Retourner au composant précédent
+    previousComponent: useCallback(() => {
+      if (!canGoPrevious) return;
+
+      setState(prev => ({
+        ...prev,
+        currentComponentIndex: prev.currentComponentIndex - 1,
+      }));
+    }, [canGoPrevious, apiKey]),
+
+    // Aller à un composant spécifique
+    goToComponent: useCallback((componentId: number) => {
+      const componentIndex = state.template.components.findIndex(c => c.id === componentId);
+      if (componentIndex !== -1) {
+        setState(prev => ({
+          ...prev,
+          currentComponentIndex: componentIndex,
+        }));
+      }
+    }, [state.template.components, apiKey]),
+
+    // Mettre à jour les données d'un composant
+    updateComponentData: useCallback((componentId: number, data: any) => {
+      logger.log("updateComponentData", componentId, JSON.stringify(truncateFields(data), null, 2));
+
+      setState(prev => ({
+        ...prev,
+        componentData: {
+          ...prev.componentData,
+          [componentId]: data
+        },
+        errors: {
+          ...prev.errors,
+          [componentId]: ''
+        }
+      }));
+
+    }, [apiKey]),
+
+    // Valider un composant
+    validateComponent: useCallback((componentId: number, dataOverride?: any) => {
+      return validateComponent(componentId, dataOverride);
+    }, [validateComponent, apiKey]),
+    // complet verification
+    submitVerification: useCallback(async () => {
+      setState(prev => ({ ...prev, isProcessing: true }));
+      try {
+        onComplete?.(state.verification);
+
+      } catch (error) {
+        setState(prev => ({ ...prev, isProcessing: false }));
+      }
+    }, [state.session.session_id, state.verification, onComplete, apiKey]),
+
+    // Soumettre le template complet
+    submitTemplate: useCallback(async () => {
+      // Allow submission when on the review step and all previous steps are valid
+      const atReview = state.template.components[state.currentComponentIndex]?.type === 'review_submit';
+      const allValid = state.template.components
+        .filter(c => c.type !== 'review_submit')
+        .every(comp => validateComponent(comp.id));
+      if (!(atReview && allValid)) {
+        onError?.('Le flux KYC n\'est pas encore terminé');
+        return;
+      }
+
+      setState(prev => ({ ...prev, isProcessing: true }));
+
+      try {
+        // Vérifier que tous les composants (hors review) sont validés
+        if (!allValid) throw new Error('Certaines étapes ne sont pas complètes');
+
+        // Appeler le callback de completion
+        // onComplete?.(state.componentData);
+
+        setState(prev => ({ ...prev, isProcessing: false }));
+      } catch (error) {
+        setState(prev => ({ ...prev, isProcessing: false }));
+        onError?.(error instanceof Error ? error.message : 'Erreur lors de la soumission');
+      }
+    }, [state.template.components, state.verification, state.currentComponentIndex, validateComponent, state.componentData, onComplete, onError, apiKey]),
+
+    // Réinitialiser le template
+    resetTemplate: useCallback(() => {
+      setState(buildInitialState());
+    }, [buildInitialState, apiKey]),
+
+    // Changer la langue
+    setLanguage: useCallback((language: string) => {
+      setState(prev => ({
+        ...prev,
+        currentLanguage: language,
+      }));
+    }, [apiKey]),
+
+    // Afficher le stepper personnalisé
+    showCustomStepper: useCallback((show: boolean) => {
+      setState(prev => ({
+        ...prev,
+        showCustomStepper: show,
+      }));
+    }, [apiKey]),
+
+    setVerificationState: useCallback((verificationState) => {
+      setState(prev => ({
+        ...prev,
+        verification: verificationState,
+      }));
+    }, [apiKey]),
+  };
+
+  return {
+    state,
+    actions,
+    currentComponent,
+    progress,
+    canGoNext,
+    canGoPrevious,
+    isComplete,
+    getLocalizedText,
+    initializeSession,
+    env,
+    apiKey,
+  } as UseTemplateReturn;
+};