datakeen-session-react 1.1.194 → 1.1.195-dev.10

package/docs/GITLAB_BADGES_SETUP.md

@@ -1,317 +0,0 @@
-# GitLab Badges Setup Guide — SDK Datakeen Session React
-
-This guide explains what is already automated by CI/CD and what requires a one-time manual action on GitLab.
-
----
-
-## Overview
-
-| Badge              | Source                      | Automated? | Manual action required?                |
-|--------------------|-----------------------------|------------|----------------------------------------|
-| Pipeline status    | GitLab CI built-in          | ✅ Yes     | Optional (add to project badges panel) |
-| Test coverage      | GitLab CI `coverage:` regex | ✅ Yes     | Optional (add to project badges panel) |
-| NPM version `main` → `@latest` | shields.io → npm registry | ✅ Yes | ❌ None — updates on every `publish:main` |
-| NPM version `staging` → `@rc`  | shields.io → npm registry | ✅ Yes | ❌ None — updates on every `publish:staging` |
-| NPM version `dev` → `@dev`     | shields.io → npm registry | ✅ Yes | ❌ None — updates on every `publish:dev` |
-
----
-
-## Part 1 — What CI/CD does automatically
-
-### 1.1 Test coverage badge
-
-The `test` job in `.gitlab-ci.yml` includes this directive:
-
-```yaml
-coverage: '/All files[^|]*\|[^|]*\s+([\d\.]+)/'
-```
-
-GitLab parses the Jest output for this regex and **automatically extracts the coverage percentage**. After the first successful pipeline run on a protected branch (`main`, `staging`, `dev`), the coverage badge URL becomes active:
-
-```
-https://gitlab.com/datakeenteam/teamfullstack/client-sessions-react-sdk/badges/{branch}/coverage.svg
-```
-
-No additional setup is needed — it works as soon as the pipeline runs successfully.
-
-### 1.2 Pipeline status badge
-
-GitLab generates these automatically for every branch:
-
-```
-https://gitlab.com/datakeenteam/teamfullstack/client-sessions-react-sdk/badges/{branch}/pipeline.svg
-```
-
-### 1.3 NPM version badges (per branch/tag)
-
-The SDK is published to npm with **three distinct tags** matching the three branches. Shields.io reads from the npm registry in real time — no setup required.
-
-| Branch    | npm tag   | Badge URL |
-|-----------|-----------|-----------|
-| `main`    | `@latest` | `https://img.shields.io/npm/v/datakeen-session-react/latest?label=npm%40latest&color=blue` |
-| `staging` | `@rc`     | `https://img.shields.io/npm/v/datakeen-session-react/rc?label=npm%40rc&color=orange` |
-| `dev`     | `@dev`    | `https://img.shields.io/npm/v/datakeen-session-react/dev?label=npm%40dev&color=yellow` |
-
-**How the version updates:**
-- A merge on `dev` → `publish:dev` runs → bumps `1.x.x-dev.N` → badge updates to the new `@dev` version
-- A merge on `staging` → `publish:staging` runs → bumps `1.x.x-rc.N` → badge updates to the new `@rc` version
-- A merge on `main` → `publish:main` runs → bumps `1.x.x` (patch) → badge updates to the new `@latest` version
-
----
-
-## Part 2 — One-time manual action on GitLab (optional but recommended)
-
-GitLab has a **Project Badges** panel in Settings that displays badges as a horizontal strip on the project overview page.
-
-> **Tip — order matters:** GitLab displays badges in the order they were added. Add them in the order below so they appear grouped by branch left-to-right: `main` → `staging` → `dev`.
-
-### Step-by-step: Add badges to GitLab project panel
-
-1. Go to your project: `https://gitlab.com/datakeenteam/teamfullstack/client-sessions-react-sdk`
-2. Navigate to **Settings → General → Badges**
-3. Add the 9 badges below **in order**
-
----
-
-### 🔵 main — pipeline · coverage · version
-
-#### Badge 1
-
-| Field               | Value |
-|---------------------|-------|
-| **Name**            | `main · pipeline` |
-| **Link**            | `https://gitlab.com/datakeenteam/teamfullstack/client-sessions-react-sdk/-/pipelines?ref=main` |
-| **Badge image URL** | `https://gitlab.com/datakeenteam/teamfullstack/client-sessions-react-sdk/badges/main/pipeline.svg` |
-
-#### Badge 2
-
-| Field               | Value |
-|---------------------|-------|
-| **Name**            | `main · coverage` |
-| **Link**            | `https://gitlab.com/datakeenteam/teamfullstack/client-sessions-react-sdk/-/commits/main` |
-| **Badge image URL** | `https://gitlab.com/datakeenteam/teamfullstack/client-sessions-react-sdk/badges/main/coverage.svg` |
-
-#### Badge 3
-
-| Field               | Value |
-|---------------------|-------|
-| **Name**            | `main · npm @latest` |
-| **Link**            | `https://www.npmjs.com/package/datakeen-session-react` |
-| **Badge image URL** | `https://img.shields.io/npm/v/datakeen-session-react/latest?label=%40latest&color=blue&style=flat-square&logo=npm` |
-
----
-
-### 🟠 staging — pipeline · coverage · version
-
-#### Badge 4
-
-| Field               | Value |
-|---------------------|-------|
-| **Name**            | `staging · pipeline` |
-| **Link**            | `https://gitlab.com/datakeenteam/teamfullstack/client-sessions-react-sdk/-/pipelines?ref=staging` |
-| **Badge image URL** | `https://gitlab.com/datakeenteam/teamfullstack/client-sessions-react-sdk/badges/staging/pipeline.svg` |
-
-#### Badge 5
-
-| Field               | Value |
-|---------------------|-------|
-| **Name**            | `staging · coverage` |
-| **Link**            | `https://gitlab.com/datakeenteam/teamfullstack/client-sessions-react-sdk/-/commits/staging` |
-| **Badge image URL** | `https://gitlab.com/datakeenteam/teamfullstack/client-sessions-react-sdk/badges/staging/coverage.svg` |
-
-#### Badge 6
-
-| Field               | Value |
-|---------------------|-------|
-| **Name**            | `staging · npm @rc` |
-| **Link**            | `https://www.npmjs.com/package/datakeen-session-react?activeTab=versions` |
-| **Badge image URL** | `https://img.shields.io/npm/v/datakeen-session-react/rc?label=%40rc&color=orange&style=flat-square&logo=npm` |
-
----
-
-### 🟡 dev — pipeline · coverage · version
-
-#### Badge 7
-
-| Field               | Value |
-|---------------------|-------|
-| **Name**            | `dev · pipeline` |
-| **Link**            | `https://gitlab.com/datakeenteam/teamfullstack/client-sessions-react-sdk/-/pipelines?ref=dev` |
-| **Badge image URL** | `https://gitlab.com/datakeenteam/teamfullstack/client-sessions-react-sdk/badges/dev/pipeline.svg` |
-
-#### Badge 8
-
-| Field               | Value |
-|---------------------|-------|
-| **Name**            | `dev · coverage` |
-| **Link**            | `https://gitlab.com/datakeenteam/teamfullstack/client-sessions-react-sdk/-/commits/dev` |
-| **Badge image URL** | `https://gitlab.com/datakeenteam/teamfullstack/client-sessions-react-sdk/badges/dev/coverage.svg` |
-
-#### Badge 9
-
-| Field               | Value |
-|---------------------|-------|
-| **Name**            | `dev · npm @dev` |
-| **Link**            | `https://www.npmjs.com/package/datakeen-session-react?activeTab=versions` |
-| **Badge image URL** | `https://img.shields.io/npm/v/datakeen-session-react/dev?label=%40dev&color=yellow&style=flat-square&logo=npm` |
-
----
-
-## Part 3 — GitLab CI variables required
-
-The publish jobs already use these CI/CD variables. Verify they are set under **Settings → CI/CD → Variables**:
-
-| Variable         | Description                                      | Protected | Masked |
-|------------------|--------------------------------------------------|-----------|--------|
-| `CI_PUSH_USER`   | GitLab username for pushing version bump commits | ✅ Yes    | ❌     |
-| `CI_PUSH_TOKEN`  | GitLab personal/project access token             | ✅ Yes    | ✅ Yes |
-
----
-
-## Part 4 — Expected coverage regex match
-
-Jest outputs a coverage table like this:
-
-```
-------------|---------|----------|---------|---------|-------------------
-File        | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
-------------|---------|----------|---------|---------|-------------------
-All files   |   82.45 |    71.23 |   78.90 |   82.10 |
-```
-
-The regex `/All files[^|]*\|[^|]*\s+([\d\.]+)/` captures `82.45` (Statements %).
-
-GitLab then colours the badge:
-- 🟢 Green: ≥ 95%
-- 🟡 Yellow: 75–95%
-- 🔴 Red: < 75%
-
-You can customize thresholds in **Settings → CI/CD → General pipelines → Test coverage parsing**.
-
-
----
-
-## Part 1 — What CI/CD does automatically
-
-### 1.1 Test coverage badge
-
-The `test` job in `.gitlab-ci.yml` includes this directive:
-
-```yaml
-coverage: '/All files[^|]*\|[^|]*\s+([\d\.]+)/'
-```
-
-GitLab parses the Jest output for this regex and **automatically extracts the coverage percentage**. After the first successful pipeline run on a protected branch (`main`, `staging`, `dev`), the coverage badge URL becomes active:
-
-```
-https://gitlab.com/datakeenteam/teamfullstack/client-sessions-react-sdk/badges/{branch}/coverage.svg
-```
-
-No additional setup is needed — it works as soon as the pipeline runs successfully.
-
-### 1.2 Pipeline status badge
-
-GitLab generates these automatically for every branch:
-
-```
-https://gitlab.com/datakeenteam/teamfullstack/client-sessions-react-sdk/badges/{branch}/pipeline.svg
-```
-
-### 1.3 NPM version badge
-
-Powered by shields.io pointing to the npm registry. As soon as the `publish:*` jobs run, the badges reflect the latest published version for each tag (`latest`, `@rc`, `@dev`).
-
----
-
-## Part 2 — One-time manual action on GitLab (optional but recommended)
-
-GitLab has a **Project Badges** panel in Settings that displays badges on the project overview page (not just the README). This is optional but gives more visibility.
-
-### Step-by-step: Add badges to GitLab project panel
-
-1. Go to your project: `https://gitlab.com/datakeenteam/teamfullstack/client-sessions-react-sdk`
-2. Navigate to **Settings → General → Badges**
-3. Click **Add badge** for each badge below
-
----
-
-#### Badge 1 — Pipeline status `main`
-
-| Field      | Value                                                                                                                             |
-|------------|-----------------------------------------------------------------------------------------------------------------------------------|
-| **Name**   | `Pipeline main`                                                                                                                   |
-| **Link**   | `https://gitlab.com/datakeenteam/teamfullstack/client-sessions-react-sdk/-/pipelines?ref=main`                                   |
-| **Badge image URL** | `https://gitlab.com/datakeenteam/teamfullstack/client-sessions-react-sdk/badges/main/pipeline.svg?key_text=dev&key_width=50`                     |
-
----
-
-#### Badge 2 — Pipeline status `staging`
-
-| Field      | Value                                                                                                                              |
-|------------|------------------------------------------------------------------------------------------------------------------------------------|
-| **Name**   | `Pipeline staging`                                                                                                                 |
-| **Link**   | `https://gitlab.com/datakeenteam/teamfullstack/client-sessions-react-sdk/-/pipelines?ref=staging`                                 |
-| **Badge image URL** | `https://gitlab.com/datakeenteam/teamfullstack/client-sessions-react-sdk/badges/staging/pipeline.svg?key_text=staging&key_width=50`               |
-
----
-
-#### Badge 3 — Pipeline status `dev`
-
-| Field      | Value                                                                                                                             |
-|------------|-----------------------------------------------------------------------------------------------------------------------------------|
-| **Name**   | `Pipeline dev`                                                                                                                    |
-| **Link**   | `https://gitlab.com/datakeenteam/teamfullstack/client-sessions-react-sdk/-/pipelines?ref=dev`                                    |
-| **Badge image URL** | `https://gitlab.com/datakeenteam/teamfullstack/client-sessions-react-sdk/badges/dev/pipeline.svg?key_text=dev&key_width=50`                     |
-
----
-
-#### Badge 4 — Test coverage `main`
-
-| Field      | Value                                                                                                                             |
-|------------|-----------------------------------------------------------------------------------------------------------------------------------|
-| **Name**   | `Coverage main`                                                                                                                   |
-| **Link**   | `https://gitlab.com/datakeenteam/teamfullstack/client-sessions-react-sdk/-/commits/main`                                         |
-| **Badge image URL** | `https://gitlab.com/datakeenteam/teamfullstack/client-sessions-react-sdk/badges/main/coverage.svg`                    |
-
----
-
-#### Badge 5 — NPM version (latest/stable)
-
-| Field      | Value                                                                                           |
-|------------|-------------------------------------------------------------------------------------------------|
-| **Name**   | `npm version`                                                                                   |
-| **Link**   | `https://www.npmjs.com/package/datakeen-session-react`                                          |
-| **Badge image URL** | `https://img.shields.io/npm/v/datakeen-session-react/latest?label=npm%40latest&color=blue` |
-
----
-
-## Part 3 — Gitlab CI variables required
-
-The publish jobs already use these CI/CD variables. Verify they are set under **Settings → CI/CD → Variables**:
-
-| Variable         | Description                                      | Protected | Masked |
-|------------------|--------------------------------------------------|-----------|--------|
-| `CI_PUSH_USER`   | GitLab username for pushing version bump commits | ✅ Yes    | ❌     |
-| `CI_PUSH_TOKEN`  | GitLab personal/project access token             | ✅ Yes    | ✅ Yes |
-
----
-
-## Part 4 — Expected coverage regex match
-
-Jest outputs a coverage table like this:
-
-```
-------------|---------|----------|---------|---------|-------------------
-File        | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
-------------|---------|----------|---------|---------|-------------------
-All files   |   82.45 |    71.23 |   78.90 |   82.10 |
-```
-
-The regex `/All files[^|]*\|[^|]*\s+([\d\.]+)/` captures `82.45` (Statements %).
-
-GitLab then colours the badge:
-- 🟢 Green: ≥ 95%
-- 🟡 Yellow: 75–95%
-- 🔴 Red: < 75%
-
-You can customize thresholds in **Settings → CI/CD → General pipelines → Test coverage parsing**.

package/docs/JOURNEY_NODE_BUILDER.md

@@ -1,198 +0,0 @@
-# JOURNEY NODE BUILDER - Client Sessions React SDK (Onboarding)
-
-## Objectif
-
-Cette documentation aide un nouveau développeur à:
-- comprendre comment le SDK exécute un journey côté client,
-- identifier où la navigation est gérée (steps, templateIndex, persistance),
-- ajouter un nouveau type de nœud sans oublier les points bloquants.
-
-## Fichiers à connaître
-
-Orchestration session:
-- `client-sessions-react-sdk/src/components/DatakeenSession.tsx`
-- `client-sessions-react-sdk/src/hooks/useSessionData.ts`
-- `client-sessions-react-sdk/src/hooks/useStepNavigation.ts`
-- `client-sessions-react-sdk/src/hooks/useTemplateLoader.ts`
-- `client-sessions-react-sdk/src/components/session/SessionContent.tsx`
-
-Rendu et exécution des nœuds:
-- `client-sessions-react-sdk/src/components/template/TemplateNodeRenderer.tsx`
-- `client-sessions-react-sdk/src/components/template/ConditionNodeHandler.tsx`
-- `client-sessions-react-sdk/src/components/session/UserInputForm.tsx`
-- `client-sessions-react-sdk/src/components/session/DocumentCheck.tsx`
-- `client-sessions-react-sdk/src/components/document-collection/DocumentCollection.tsx`
-
-Services et modèle:
-- `client-sessions-react-sdk/src/services/sessionService.ts`
-- `client-sessions-react-sdk/src/services/retryService.ts`
-- `client-sessions-react-sdk/src/types/session.ts`
-- `client-sessions-react-sdk/src/utils/conditionEvaluator.ts`
-
-Styles et i18n:
-- `client-sessions-react-sdk/src/hooks/useStepCSS.ts`
-- `client-sessions-react-sdk/src/utils/cssLoader.ts`
-- `client-sessions-react-sdk/src/i18n/fr.json`
-- `client-sessions-react-sdk/src/i18n/en.json`
-
-## Vue d'ensemble du flux
-
-1. `DatakeenSession` charge la session (`fetchSessionById`) via `useSessionData`.
-2. La navigation est pilotée par `useStepNavigation`:
-- `step=0`: écran de démarrage,
-- `step=0.5`: écran QR desktop/mobile (si configuré),
-- `step>=1`: exécution des nœuds du template.
-3. `SessionContent` délègue le rendu des nœuds à `TemplateNodeRenderer` avec `templateIndex = step - 1`.
-4. `TemplateNodeRenderer` récupère les nœuds ordonnés via `getOrderedJourneySteps(template)`:
-- filtre `start`,
-- conserve `end`,
-- tri par `order`.
-5. Selon `node.type`, le SDK rend le composant correspondant (document, selfie, information-input, condition, etc.).
-6. `stepObject.setStep(...)` fait 2 actions:
-- met à jour le step en local,
-- persiste `currentStep` côté backend (`PATCH /session/sdk/:id`).
-
-## Règles runtime importantes
-
-### Ordre de lecture des nœuds
-- Le SDK ne suit pas les `edges` pour le flux nominal.
-- Il suit l’ordre `order` des `nodes` (sauf `start`).
-- Le branchement par `edges` est surtout utilisé pour `condition`.
-
-### Session terminée
-- Si `session.status === "ended"`, le SDK affiche directement `EndFlow`, quel que soit le `step`.
-
-### Condition node
-- `ConditionNodeHandler` recharge la session pour récupérer les analyses les plus fraîches.
-- Évalue `conditionTokens` (ou `conditionExpression`) avec `conditionEvaluator`.
-- Cherche l’edge sortante via:
-  - `sourceHandle === "true" | "false"`,
-  - sinon `conditionValue === "true" | "false"`,
-  - sinon fallback sur la première edge sortante.
-- Redirige ensuite vers le `target` via son index dans la liste ordonnée des nœuds.
-
-### Retry documentaires
-- `DocumentCheck` et `DocumentCollection` utilisent `retryCounts` (clé: `nodeId`) via `retryService`.
-- `allowResubmission` et `maxResubmissionAttempts` contrôlent les retries.
-- Sur succès d’analyse, ces composants poussent `currentStep` côté backend immédiatement pour éviter une double analyse après refresh.
-
-### Callback URL de fin
-- `useSessionData` normalise `callbackURL` en priorisant le `callbackURL` présent sur le nœud `end` si défini.
-
-## Types de nœuds gérés actuellement
-
-Dans `TemplateNodeRenderer`, les principaux types gérés sont:
-- `information-input`
-- `document-selection`
-- `controle-jdi`
-- `document-collection`
-- `selfie-capture`
-- `biometric-capture`
-- `video-capture`
-- `condition`
-- `end`
-- `custom` (fallback d’extension)
-
-Si un type est inconnu, le SDK affiche un écran "Étape non supportée" et permet de continuer.
-
-## Ajouter un nouveau nœud (checklist)
-
-1. Étendre le contrat de données
-- Ajouter les champs nécessaires dans `SessionTemplateNode` (`src/types/session.ts`).
-- Si le nœud utilise de nouveaux handles/edges, vérifier `SessionTemplateEdge`.
-
-2. Créer le composant runtime
-- Implémenter le composant dédié (ex: `src/components/session/MyNewNode.tsx`).
-- Prévoir les callbacks de navigation (`stepObject.setStep`) et le comportement mobile/desktop.
-
-3. Brancher le rendu
-- Ajouter le `case` dans le `switch(node.type)` de `TemplateNodeRenderer`.
-- Valider le comportement d’erreur si la config du nœud est incomplète.
-
-4. Gérer la navigation et la persistance
-- Si le nœud avance simplement: `stepObject.setStep(step + 1)`.
-- Si le nœud branche: implémenter la résolution des `edges` (à la manière de `condition`).
-- Si le nœud lance un process long (analyse/upload), persister `currentStep` au bon moment.
-
-5. Gérer styles et traductions
-- Ajouter les clés i18n dans `src/i18n/fr.json` et `src/i18n/en.json`.
-- Si le nœud a des styles dédiés, charger son CSS via `useStepCSS` / `cssLoader`.
-
-6. Vérifier les dépendances de session
-- Si le nœud stocke des données locales, intégrer la synchro dans `useSessionData` ou un hook dédié.
-- Si le nœud a de la logique retry, utiliser `retryService` avec `node.id`.
-
-7. Ajouter les tests
-- Tests de rendu/comportement du nouveau composant.
-- Test de navigation (step suivant, branch, fallback).
-- Test des cas d’erreur de configuration.
-
-## Champs verrouillés depuis l'API — nœud `information-input`
-
-Le nœud `information-input` supporte des champs marqués `lockedFromApi: true` dans la configuration du journey. Ces champs sont pré-remplis par le partenaire à la création de session et **ne doivent jamais apparaître** dans le formulaire présenté au Mandataire.
-
-### Comportement dans le SDK
-
-Dans `CustomFormFields.tsx`, les champs verrouillés sont filtrés **avant** le rendu :
-
-```tsx
-const visibleFields = customFields.filter((f) => !f.lockedFromApi);
-```
-
-Le champ n'est pas rendu du tout (pas de `disabled`, pas de `readOnly`) — il est complètement absent du DOM.
-
-### Types concernés
-
-Dans `src/types/session.ts`, l'interface `CustomField` expose :
-
-| Propriété | Type | Description |
-|---|---|---|
-| `lockedFromApi` | `boolean \| undefined` | Si `true`, le champ est exclu du formulaire |
-| `userInputKey` | `string \| undefined` | Clé correspondante dans `session.userInput` côté backend |
-
-### Important
-
-Le filtre côté SDK est une couche d'UX uniquement. La protection réelle est assurée côté backend via `stripLockedFields()` dans `session.service.ts` — qui réinjecte la valeur verrouillée sur chaque soumission SDK, même si un client malveillant tente de la modifier.
-
-## Écran post-signature — nœud `signature-electronic`
-
-L'écran de consultation du document signé accepte trois textes optionnels portés par le nœud :
-
-| Propriété | Type | Contenu |
-|---|---|---|
-| `signedScreenTitle` | `string \| undefined` | Titre de la page |
-| `signedScreenDescription` | `string \| undefined` | Message de remerciement |
-| `signedScreenDownloadHint` | `string \| undefined` | Phrase invitant à conserver ou télécharger le document |
-
-Une propriété absente, vide ou composée uniquement d'espaces utilise le texte standard traduit du SDK. Ces propriétés ne modifient pas les messages techniques des états `error`, `declined` et `expired`.
-
----
-
-## Point d'attention condition
-
-La logique détaillée du nœud condition est documentée dans:
-- `client-sessions-react-sdk/docs/condition-node.md`
-
-## Vérification manuelle minimale
-
-1. Exécuter une session avec le nouveau nœud en environnement local.
-2. Vérifier progression du `step` (y compris refresh page).
-3. Vérifier la persistance backend de `currentStep`.
-4. Vérifier les cas erreur (config incomplète, API indisponible, fallback UI).
-5. Vérifier les traductions FR/EN et le rendu mobile/desktop.
-
-## Vérifications utiles
-
-- `pnpm -C client-sessions-react-sdk lint`
-- `pnpm -C client-sessions-react-sdk test -- --runInBand`
-- `pnpm -C client-sessions-react-sdk build`
-
-
-## Métadonnée de sensibilité des champs personnalisés (1.2)
-
-`CustomField.containsPersonalData?: boolean` est un ajout déclaratif optionnel.
-Le SDK ne le lit pas : rendu, validation et stockage restent identiques.
-L’absence signifie donnée personnelle côté backoffice/backend. Seul `false`
-permet un affichage restreint des champs métier ; une liste est classée en bloc.
-La version mineure `1.2.0-dev.0` est préparée localement, sans publication.
-Le backend doit conserver exactement la conversion `labelToKey` du SDK.