@41devs/naya-id-js 0.1.0

package/LICENSE

@@ -0,0 +1,5 @@
+© 2026 41devs. Tous droits réservés.
+
+Ce logiciel est distribué pour l'intégration des services Naya ID.
+Toute reproduction ou utilisation en dehors de ce cadre nécessite
+l'accord écrit de 41devs.

package/README.md

@@ -0,0 +1,272 @@
+# Naya ID — SDK JavaScript
+
+SDK JavaScript officiel de **Naya ID**, la vérification d'identité (eKYC) clé en
+main pour l'Afrique de l'Ouest (zone CEDEAO). **Aucun framework, aucune étape de
+build côté client** : vous ajoutez une balise `<script>`, vous appelez **une
+seule méthode**, l'interface Naya s'ouvre en plein écran, prend en charge la
+capture du document, la détection de vivacité et la décision, puis vous rend le
+résultat et rend la main à votre page.
+
+C'est le pendant « vanilla » des SDK [Flutter](https://pub.dev/packages/naya_id)
+et [Angular](https://www.npmjs.com/package/@41devs/naya-id-angular) : même
+parcours, mêmes écrans, même contrat d'API.
+
+- **npm** : [`@41devs/naya-id-js`](https://www.npmjs.com/package/@41devs/naya-id-js)
+- **Site** : https://naya.41devs.com
+
+---
+
+## Installation
+
+### Par balise `<script>` (le plus simple)
+
+Aucune installation. Chargez le SDK depuis un CDN — il expose un objet global
+`NayaId` :
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@41devs/naya-id-js@0/dist/naya-id.min.js"></script>
+<script>
+  document.getElementById('verifier').addEventListener('click', async () => {
+    const result = await NayaId.startVerification({
+      apiKey: 'naya_live_xxx',
+      config: { country: 'BJ' },
+    });
+    console.log(result.status, result.verificationId, result.ocrData);
+  });
+</script>
+```
+
+> Épinglez une version majeure (`@0`) ou exacte (`@0.1.0`) en production. `unpkg`
+> fonctionne de la même façon : `https://unpkg.com/@41devs/naya-id-js`.
+
+### Par npm (bundlers : Vite, webpack, Rollup…)
+
+```bash
+npm install @41devs/naya-id-js
+```
+
+```ts
+import { startVerification } from '@41devs/naya-id-js';
+
+const result = await startVerification({
+  apiKey: 'naya_live_xxx',
+  config: { country: 'BJ' },
+});
+```
+
+Le SDK est livré en **ESM**, **CommonJS** et **IIFE**, avec les **types
+TypeScript**. Il n'a **aucune dépendance npm** : la détection de vivacité
+(MediaPipe) est chargée à la demande depuis un CDN au moment du selfie.
+
+---
+
+## Prérequis
+
+| Élément | Détail |
+|---|---|
+| **Clé API Naya** | Une clé `naya_live_…` ou `naya_test_…` (créée dans le dashboard Naya). |
+| **Entreprise vérifiée (KYB)** | La société propriétaire de la clé doit être **KYB-vérifiée**, sinon l'API renvoie `403`. |
+| **HTTPS** | La caméra (`getUserMedia`) exige un **contexte sécurisé** : `https://` en production, ou `http://localhost` en développement. Sur `http://` distant, la caméra ne démarre pas. |
+| **CORS** | L'origine de votre page doit être autorisée côté API Naya (liste `ALLOWED_ORIGINS`). |
+
+---
+
+## Démarrage rapide
+
+`startVerification` retourne une promesse qui se résout quand l'utilisateur
+ressort du parcours, avec le résultat.
+
+```js
+const result = await NayaId.startVerification({
+  apiKey: 'naya_live_xxx',
+  config: {
+    country: 'BJ',                                    // pré-sélectionne le pays
+    callbackUrl: 'https://votre-backend.com/naya/hook', // notification serveur (optionnel)
+  },
+});
+
+switch (result.status) {
+  case 'approved':  // Identité vérifiée. result.ocrData contient les champs extraits.
+    break;
+  case 'review':    // Revue manuelle : décision finale notifiée plus tard via callbackUrl.
+    break;
+  case 'rejected':  // Refus (result.note explique pourquoi).
+    break;
+  case 'cancelled': // L'utilisateur a fermé le parcours avant la fin.
+    break;
+  case 'error':     // Problème technique : result.errorMessage.
+    console.error(result.errorMessage);
+    break;
+}
+```
+
+`startVerification` **ne rejette jamais** : une erreur réseau ou une annulation
+revient toujours sous forme de `NayaResult` (`status: 'error'` ou `'cancelled'`).
+
+---
+
+## Le parcours vu par l'utilisateur
+
+Une fois `startVerification` appelée, l'interface Naya enchaîne seule :
+
+1. **Bienvenue** — écran d'accueil.
+2. **Sélection** — pays et type de document (sautée si `country` + un seul `documentTypes`).
+3. **Capture du document** — recto, puis verso pour la CNI (bande MRZ). Cadre vert quand l'image est nette ; l'utilisateur déclenche.
+4. **Vivacité** — selfie avec défi actif : regarder droit → cligner → tourner la tête.
+5. **Traitement** — OCR, biométrie, décision côté serveur.
+6. **Résultat** — approuvé / en revue / rejeté, puis retour à votre page.
+
+L'interface est montée dans un **Shadow DOM** : ni le CSS de votre page
+n'affecte le SDK, ni l'inverse.
+
+---
+
+## API
+
+### `NayaId.startVerification(params)`
+
+| Champ | Type | Rôle |
+|---|---|---|
+| `apiKey` | `string` | Clé d'application, transmise depuis le navigateur. |
+| `sessionToken` | `string` | Jeton de session éphémère obtenu par votre backend (à privilégier). |
+| `auth` | `{ apiKey?, sessionToken? }` | Alternative aux deux champs ci-dessus, en objet. |
+| `config` | `NayaConfig` | Configuration optionnelle (voir ci-dessous). |
+
+### Configuration (`config`)
+
+Tous les champs sont optionnels — le SDK a des défauts raisonnables (tous pays,
+tous documents, français).
+
+| Champ | Type | Défaut | Rôle |
+|---|---|---|---|
+| `country` | `'BJ'\|'CI'\|'SN'\|'ML'\|'BF'\|'TG'` | — | Pré-sélectionne le pays ; l'utilisateur ne le choisit plus. |
+| `documentTypes` | `('cni'\|'passeport'\|'permis')[]` | les trois | Types proposés. Un seul + `country` défini ⇒ écran de sélection sauté. |
+| `countries` | `NayaCountryCode[]` | les six | Pays proposés quand `country` n'est pas fixé. |
+| `locale` | `'fr' \| 'en'` | `'fr'` | Langue de l'interface. |
+| `callbackUrl` | `string` | — | URL HTTPS notifiée par le serveur Naya à chaque décision. |
+| `maxAttempts` | `number` | `2` | Nombre d'essais autorisés après un rejet (bouton « Réessayer »). |
+| `theme` | `{ primaryColor?, accentColor? }` | navy / ambre | Surcharge des couleurs de marque. |
+| `clientLogoUrl` | `string` | — | Logo affiché à côté de « Propulsé par Naya ID ». |
+| `livenessAssets` | `{ esmUrl?, wasmBaseUrl?, modelUrl? }` | CDN public | Auto-hébergement MediaPipe (CSP stricte — voir plus bas). |
+| `baseUrl` | `string` | API de prod | À ne changer que pour un environnement de test. |
+
+### Résultat (`NayaResult`)
+
+| Champ | Type | Présent quand |
+|---|---|---|
+| `status` | `'approved'\|'review'\|'rejected'\|'cancelled'\|'error'` | toujours |
+| `verificationId` | `string` | dès qu'une session a été créée — à conserver pour rapprocher notifications et dashboard |
+| `riskScore` | `number` (0-100) | après traitement — score de confiance agrégé |
+| `matchScore` | `number` (0-100) | concordance visage document ↔ selfie |
+| `authenticityScore` | `number` (0-100) | intégrité du document |
+| `livenessScore` | `number` (0-100) | vivacité |
+| `ocrConfidence` | `number` (0-100) | confiance de l'OCR |
+| `ocrData` | `NayaOcrData` | champs extraits (nom, prénoms, date de naissance, n° document, NPI…) |
+| `note` | `string` | note d'analyse du pipeline |
+| `errorMessage` | `string` | uniquement si `status === 'error'` |
+
+---
+
+## Authentification
+
+Un seul des deux champs est à renseigner :
+
+| Mode | Usage |
+|---|---|
+| `apiKey` | Simple, mais la clé est **lisible dans le navigateur** (outils de dev). À réserver aux démos et aux intégrations où le front est maîtrisé. |
+| `sessionToken` | Jeton éphémère obtenu par **votre backend**, limité à une vérification. **À privilégier en production** : la clé ne quitte jamais votre serveur. |
+
+```js
+// Production : votre backend échange sa clé contre un jeton de session.
+await NayaId.startVerification({
+  sessionToken: jetonObtenuDeVotreBackend,
+  config: { country: 'BJ' },
+});
+```
+
+Passer de l'un à l'autre ne change rien au reste de l'intégration.
+
+---
+
+## Notifications serveur (`callbackUrl`)
+
+En passant `callbackUrl`, votre backend est notifié à chaque décision, sans
+interroger l'API. Deux événements possibles par session :
+`verification.completed` (décision automatique) puis, le cas échéant,
+`verification.reviewed` (après revue d'un analyste). Les envois sont signés
+(`X-Naya-Signature`, HMAC-SHA256). Détails côté documentation de l'API.
+
+---
+
+## Détection de vivacité
+
+La vivacité s'exécute **sur l'appareil** via [MediaPipe Face Landmarker]. Le
+module et le modèle sont chargés depuis un CDN public **au moment du selfie**
+seulement — aucune configuration requise, et rien n'alourdit le chargement
+initial de votre page. L'analyse est **locale** : la photo n'est transmise qu'à
+la fin du défi.
+
+Pour une page à **CSP stricte** (hôtes externes bloqués), auto-hébergez ces
+ressources et indiquez leurs URL :
+
+```js
+config: {
+  country: 'BJ',
+  livenessAssets: {
+    esmUrl: '/assets/naya/vision_bundle.mjs',       // module @mediapipe/tasks-vision
+    wasmBaseUrl: '/assets/naya/wasm',                // dossier wasm/ du paquet
+    modelUrl: '/assets/naya/face_landmarker.task',   // modèle MediaPipe
+  },
+}
+```
+
+Copiez `vision_bundle.mjs`, le dossier `wasm/` et le modèle
+`face_landmarker.task` de `@mediapipe/tasks-vision@1.0.1`.
+
+[MediaPipe Face Landmarker]: https://ai.google.dev/edge/mediapipe/solutions/vision/face_landmarker
+
+---
+
+## Contraintes navigateur
+
+- **Contexte sécurisé obligatoire** pour la caméra : `https://` ou `http://localhost`.
+- Testé sur Chrome et Safari (desktop et iOS). Les webviews in-app (Instagram,
+  Facebook…) restreignent souvent `getUserMedia` — orientez l'utilisateur vers
+  le navigateur système si la caméra ne démarre pas.
+- L'interface s'ouvre en superposition plein écran (Shadow DOM) et fige le
+  défilement de la page tant que le parcours est ouvert.
+
+---
+
+## Dépannage
+
+| Symptôme | Cause probable |
+|---|---|
+| `status: 'error'`, « clé API invalide » (401) | Clé absente/révoquée, ou coquille. |
+| `status: 'error'`, « KYB… » (403) | La société de la clé n'est pas KYB-vérifiée. |
+| `status: 'error'`, « CORS » | L'origine de votre page n'est pas dans `ALLOWED_ORIGINS` côté API. |
+| La caméra ne démarre pas | Page servie en `http://` distant (contexte non sécurisé), permission refusée, ou webview in-app. |
+| Score de vivacité anormalement bas | Selfie de mauvaise qualité (contre-jour, reflets d'écran) — l'anti-fraude serveur le pénalise. |
+
+---
+
+## Développement (ce dépôt)
+
+```bash
+npm install          # Node 18+ (22 recommandé)
+npm run build        # produit dist/ (iife .min.js, esm .mjs, cjs .cjs, types .d.ts)
+npm run typecheck    # vérification TypeScript
+```
+
+Démo locale : après `npm run build`, servez la racine et ouvrez
+`example/index.html` sur `http://localhost` (contexte sécurisé requis) :
+
+```bash
+npm run serve        # puis http://localhost:3000/example/
+```
+
+---
+
+## Licence
+
+Propriété de 41Devs. Voir le fichier `LICENSE`.