datakeen-session-react 1.1.140-dev.71 → 1.1.140-dev.73

package/CLAUDE.md

@@ -0,0 +1,227 @@
+# CLAUDE.md — Client Sessions React SDK
+
+## Vue d'ensemble
+
+Librairie React TypeScript servant d'orchestrateur côté client pour les parcours d'onboarding Datakeen (journeys). Publiée sur npm sous `datakeen-session-react`. Elle gère la navigation entre nœuds, la collecte de données (formulaires, documents, biométrique), le polling asynchrone des analyses et l'historique de navigation.
+
+**Stack :** React 18 (peer dep), TypeScript, Axios, i18next, Radix UI, TensorFlow (ML documents), Rollup (build ESM + CJS).
+
+**Tests :** Jest + React Testing Library.
+
+**Point d'entrée :** `src/components/DatakeenSession.tsx`
+
+---
+
+## Structure du projet
+
+```
+client-sessions-react-sdk/
+├── src/
+│   ├── components/
+│   │   ├── session/            # Orchestration session (SessionContent, UserInputForm)
+│   │   ├── template/           # Rendu nœuds (TemplateNodeRenderer, ConditionNodeHandler)
+│   │   ├── document-collection/
+│   │   ├── selfie/, id-check/, jdi/, signature-electronic/
+│   │   ├── start-flow/, end-flow/
+│   │   └── ui/                 # Composants réutilisables internes
+│   ├── hooks/
+│   │   ├── useStepNavigation.ts # Historique + navigation (CRITIQUE)
+│   │   ├── useSessionData.ts    # Chargement et synchro données
+│   │   ├── useTemplateLoader.ts # Résolution template
+│   │   └── useStepCSS.ts        # Styles dynamiques par nœud
+│   ├── services/
+│   │   ├── sessionService.ts    # API session + getOrderedJourneySteps
+│   │   ├── pollingService.ts    # Polling analyses documentaires
+│   │   ├── retryService.ts      # Gestion retryCounts
+│   │   └── ...
+│   ├── context/
+│   │   ├── SessionContext.tsx   # État session global
+│   │   ├── ConfigContext.tsx
+│   │   └── DocumentContext.tsx
+│   ├── types/
+│   │   ├── session.ts           # SessionTemplateNode, SessionTemplateEdge, CustomField
+│   │   └── ...
+│   ├── utils/
+│   │   ├── conditionEvaluator.ts # Évaluation conditions
+│   │   ├── cssLoader.ts          # Injection CSS dynamique
+│   │   └── documentLabels.ts
+│   └── i18n/
+│       ├── fr.json, en.json
+│       └── country/, documents/
+├── docs/                         # Documentation — LIRE EN PREMIER
+├── rollup.config.js              # Build production (ESM + CJS)
+└── dist/                         # Artefacts buildés (ne pas modifier)
+```
+
+---
+
+## Règles impératives
+
+### Avant de coder
+
+**Lire `docs/`** en premier :
+- `POLLING_SYSTEM.md` — spec complète polling v2.0.0
+- `navigation-history.md` — pièges navigation
+- `multi-runs.md` — convention `_list`
+- `JOURNEY_NODE_BUILDER.md` — checklist ajout nœud
+- `sdk_integration_guide.md` — intégration consommateur
+
+### Navigation entre nœuds
+
+Le fichier central est `src/hooks/useStepNavigation.ts`. Respecter strictement l'API :
+
+```typescript
+// ✅ Avancer vers le prochain nœud (résout via les edges du graphe)
+goToNextStep(nodeId, template, handle?)
+
+// ✅ Revenir en arrière (dépile l'historique)
+goBack()
+
+// ✅ Naviguer directement (cas spéciaux uniquement)
+setStep(n, skipHistory?)
+
+// ❌ Ne jamais faire ça
+setStep(step - 1) // arithmétique manuelle = bugs de navigation
+```
+
+**Index de navigation :**
+- `step=0` : écran de démarrage
+- `step=0.5` : QR code (si configuré)
+- `step≥1` : nœuds du template (1-indexed, triés par `order`)
+
+### Types de nœuds
+
+| Type | Description | Sorties |
+|------|-------------|---------|
+| `information-input` | Formulaires avec champs optionnellement verrouillés | 1 |
+| `document-selection` | Choix de document | 1 |
+| `document-collection` | Upload document + polling | 1 |
+| `controle-jdi` | Analyse JDI avec polling | 1 |
+| `selfie-capture` / `biometric-capture` | Biométrie | 1 |
+| `condition` | Branchement conditionnel (évalue `conditionTokens`) | 2 : `true` / `false` |
+| `end` | Fin de session | 0 |
+
+Le dispatcher est `src/components/template/TemplateNodeRenderer.tsx`.
+
+**Checklist ajout d'un nœud :**
+1. Ajouter le type dans `src/types/session.ts`
+2. Créer le composant dans `src/components/`
+3. Ajouter le case dans `TemplateNodeRenderer.tsx`
+4. Ajouter les traductions FR/EN dans `src/i18n/`
+5. Gérer `goToNextStep` à la complétion du nœud
+6. Gérer `goBack()` si le nœud a un bouton retour
+7. Tester avec les cas : nœud auto-exécutant → doit être sauté par `goBack()`
+
+### Système de polling
+
+Codes de résultat d'une analyse documentaire :
+
+| Code | Signification | Action |
+|------|---------------|--------|
+| `1.0` | Approuvé | `goToNextStep` |
+| `2.0` | Rejeté | Retry possible |
+| `3.0` | Erreur | Retry possible |
+| `4.0` | En vérification manuelle | Attendre |
+
+```typescript
+// Pattern polling
+pollingService.poll(analysisId, {
+  onProgress: (pct) => setProgress(pct), // 50% → analysisId absent, 100% → résultat
+  onComplete: (code, message) => handleResult(code),
+  interval: 2000,
+});
+```
+
+### Champs verrouillés (`lockedFromApi`)
+
+Définis dans `CustomField.lockedFromApi`. Le SDK **ne doit pas les afficher** à l'utilisateur :
+
+```typescript
+// Dans CustomFormFields.tsx — filtrer avant rendu
+const visibleFields = fields.filter(f => !f.lockedFromApi);
+```
+
+Le backend réinjecte la valeur originale via `stripLockedFields()` (protection côté serveur contre la manipulation). Ne jamais contourner ce mécanisme.
+
+### Multi-runs (convention `_list`)
+
+Cas : session avec plusieurs bénéficiaires passés à la création.
+
+```json
+{
+  "userInput": {
+    "_list": [
+      { "firstName": "Alice", "lastName": "Dupont" },
+      { "firstName": "Bob", "lastName": "Martin" }
+    ]
+  }
+}
+```
+
+- `session.retryCounts[nodeId]` = index du run courant (0-indexed)
+- Incrémenté automatiquement par `ConditionNodeHandler` en mode boucle
+- SDK sélectionne `_list[runIndex]` pour pré-remplir les formulaires
+- Si hors borne → formulaire vide (comportement attendu)
+
+### Historique de navigation (reconstruction)
+
+Au rechargement, l'historique est reconstruit depuis `initialStep` via `reconstructHistoryToStep()` dans `sessionService.ts`. La reconstruction suit la **première edge sortante** de chaque nœud — elle **ne reconnaît pas** les branches conditionnelles complexes. C'est une limitation connue et documentée.
+
+### Internationalisation
+
+- Toutes les chaînes visibles dans `src/i18n/fr.json` et `en.json`.
+- Ne jamais hardcoder de texte affiché à l'utilisateur.
+
+### Styles dynamiques
+
+- CSS chargé via `cssLoader.ts` selon `node.styles` (injection dynamique).
+- Fallback sur Tailwind pour les composants par défaut.
+- Ne pas utiliser de style inline.
+
+---
+
+## Build et publication
+
+```bash
+# Build de la librairie (ESM + CJS)
+npm run build   # ou pnpm build
+
+# Tests
+npm test
+
+# Développement avec watch
+npm run dev
+```
+
+Rollup génère deux artifacts dans `dist/` :
+- `dist/esm/index.js` — pour les bundlers modernes (import)
+- `dist/cjs/index.js` — pour CommonJS (require)
+- `dist/types/index.d.ts` — typages TypeScript
+
+**Ne jamais modifier `dist/` manuellement** — régénéré à chaque build.
+
+---
+
+## Fichiers critiques
+
+| Fichier | Rôle |
+|---------|------|
+| `src/components/DatakeenSession.tsx` | Point d'entrée public de la librairie |
+| `src/hooks/useStepNavigation.ts` | Navigation + historique (NE PAS casser l'API) |
+| `src/hooks/useSessionData.ts` | Chargement et synchro état session |
+| `src/components/template/TemplateNodeRenderer.tsx` | Dispatcher de rendu par type de nœud |
+| `src/services/sessionService.ts` | API session + `getOrderedJourneySteps` + `reconstructHistoryToStep` |
+| `src/services/pollingService.ts` | Polling analyses (voir `docs/POLLING_SYSTEM.md`) |
+| `src/utils/conditionEvaluator.ts` | Évaluation des conditions de branchement |
+| `src/types/session.ts` | Contrats de données principaux |
+
+---
+
+## À ne jamais faire
+
+- Utiliser `setStep(step - 1)` pour le retour — utiliser `goBack()`.
+- Appeler `setStep` directement pour avancer — utiliser `goToNextStep`.
+- Afficher un champ avec `lockedFromApi: true`.
+- Modifier les fichiers dans `dist/` — ils sont générés.
+- Introduire une dépendance directe vers le backend ou le frontend Datakeen — le SDK est agnostique.
+- Ajouter des dépendances `dependencies` qui devraient être en `peerDependencies` (React, Axios).

package/README.md

@@ -90,7 +90,7 @@ const VerificationPage = () => {
   const { SessionComponent } = useSession(
     "votre-session-id",
     { selfie: false, requireMobile: false }, // optionnel
-    "https://app-v3.datakeen.co/backend"     // optionnel
+    "https://app.datakeen.co/backend"     // optionnel
   );
 
   return <div>{SessionComponent}</div>;
@@ -106,7 +106,7 @@ const VerificationPage = () => (
   <DatakeenSession
     sessionId="votre-session-id"
     sessionConfig={{ selfie: false, requireMobile: false }}
-    apiBaseUrl="https://app-v3.datakeen.co/backend"
+    apiBaseUrl="https://app.datakeen.co/backend"
   />
 );
 ```
@@ -117,7 +117,7 @@ const VerificationPage = () => (
 import { DatakeenSession, ConfigProvider } from "datakeen-session-react";
 
 const App = () => (
-  <ConfigProvider apiBaseUrl="https://app-v3.datakeen.co/backend">
+  <ConfigProvider apiBaseUrl="https://app.datakeen.co/backend">
     <DatakeenSession sessionId="votre-session-id" />
   </ConfigProvider>
 );
@@ -164,7 +164,7 @@ import { DatakeenSession } from "datakeen-session-react";
 <DatakeenSession
   sessionId="votre-session-id"
   sessionConfig={{ selfie: true }}
-  apiBaseUrl="https://app-v3.datakeen.co/backend"
+  apiBaseUrl="https://app.datakeen.co/backend"
 />
 ```
 
@@ -177,7 +177,7 @@ Gère automatiquement : loading/erreur/expiration, layouts mobile/desktop, coule
 ```tsx
 import { ConfigProvider } from "datakeen-session-react";
 
-<ConfigProvider apiBaseUrl="https://app-v3.datakeen.co/backend">
+<ConfigProvider apiBaseUrl="https://app.datakeen.co/backend">
   {/* Tous les DatakeenSession enfants utilisent cette URL */}
   <DatakeenSession sessionId="session-1" />
 </ConfigProvider>
@@ -191,7 +191,7 @@ import { ConfigProvider } from "datakeen-session-react";
 import { configureApiBaseURL } from "datakeen-session-react";
 
 // À appeler une fois au démarrage de l'application
-configureApiBaseURL("https://app-v3.datakeen.co/backend");
+configureApiBaseURL("https://app.datakeen.co/backend");
 ```
 
 ---
@@ -322,7 +322,7 @@ Le SDK résout l'URL API dans cet ordre de priorité :
 import { configureApiBaseURL } from "datakeen-session-react";
 
 const urls = {
-  production: "https://app-v3.datakeen.co/backend",
+  production: "https://app.datakeen.co/backend",
   staging:    "https://app.staging.datakeen.co/backend",
   development:"https://app.dev.datakeen.co/backend",
 };
@@ -333,7 +333,7 @@ configureApiBaseURL(urls[process.env.NODE_ENV] ?? urls.development);
 ### Via `.env` (Vite)
 
 ```env
-VITE_API_BASE_URL=https://app-v3.datakeen.co/backend
+VITE_API_BASE_URL=https://app.datakeen.co/backend
 ```
 
 Commande de setup rapide :

package/examples/sdk-configuration.ts

@@ -16,7 +16,7 @@ export const configureSDKForEnvironment = () => {
 
   switch (environment) {
     case "production":
-      apiBaseURL = "https://app-v3.datakeen.co/backend";
+      apiBaseURL = "https://app.datakeen.co/backend";
       break;
 
     case "staging":
@@ -64,9 +64,9 @@ export const configureSDKDynamically = () => {
 
   let apiBaseURL: string;
 
-  if (hostname.includes("app-v3.datakeen.co")) {
+  if (hostname.includes("app.datakeen.co")) {
     // Production
-    apiBaseURL = "https://app-v3.datakeen.co/backend";
+    apiBaseURL = "https://app.datakeen.co/backend";
   } else if (hostname.includes("app.staging.datakeen.co")) {
     // Staging
     apiBaseURL = "https://app.staging.datakeen.co/backend";
@@ -115,7 +115,7 @@ export const configureSDKAdvanced = (options: {
   if (!apiBaseURL && environment) {
     switch (environment) {
       case "production":
-        apiBaseURL = "https://app-v3.datakeen.co/backend";
+        apiBaseURL = "https://app.datakeen.co/backend";
         break;
       case "staging":
         apiBaseURL = "https://app.staging.datakeen.co/backend";

package/examples/test-updated-urls.ts

@@ -13,7 +13,7 @@ import {
 
 // URLs attendues pour chaque environnement
 const EXPECTED_URLS = {
-  production: "https://app-v3.datakeen.co/backend/session",
+  production: "https://app.datakeen.co/backend/session",
   staging: "https://app.staging.datakeen.co/backend/session",
   development: "https://app.dev.datakeen.co/backend/session",
   localhost: "http://localhost:8888/backend/session",
@@ -63,7 +63,7 @@ const testDynamicConfiguration = () => {
   const originalLocation = window.location;
 
   const testCases = [
-    { hostname: "app-v3.datakeen.co", expected: EXPECTED_URLS.production },
+    { hostname: "app.datakeen.co", expected: EXPECTED_URLS.production },
     { hostname: "app.staging.datakeen.co", expected: EXPECTED_URLS.staging },
     { hostname: "app.dev.datakeen.co", expected: EXPECTED_URLS.development },
     { hostname: "localhost", expected: EXPECTED_URLS.localhost },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "datakeen-session-react",
-  "version": "1.1.140-dev.71",
+  "version": "1.1.140-dev.73",
   "description": "React SDK component to manage and render Datakeen session experiences easily.",
   "publishConfig": {
     "access": "public",