@41devs/naya-id-js 0.1.0 → 0.3.0

package/dist/naya-id.d.cts

@@ -1,11 +1,6 @@
 /**
- * Configuration du parcours de vérification Naya ID.
- *
- * Reprend, à l'identique, le modèle des SDK Flutter et Angular : tous les champs
- * sont optionnels et le SDK fonctionne avec des valeurs par défaut raisonnables
- * (tous pays, tous documents, français).
+ * Configuration publique du SDK et valeurs par défaut.
  */
-/** Pays supportés par Naya ID (zone CEDEAO). Code = ISO 3166-1 alpha-2. */
 declare const NAYA_COUNTRIES: readonly [{
     readonly code: "BJ";
     readonly label: "Bénin";
@@ -26,38 +21,47 @@ declare const NAYA_COUNTRIES: readonly [{
     readonly label: "Togo";
 }];
 type NayaCountryCode = (typeof NAYA_COUNTRIES)[number]['code'];
-/** Types de documents acceptés. La valeur est envoyée telle quelle à l'API. */
 type NayaDocumentType = 'cni' | 'passeport' | 'permis';
 declare const NAYA_DOCUMENT_TYPES: readonly NayaDocumentType[];
 /** Langues de l'interface du SDK. */
-type NayaLocale = 'fr' | 'en';
+type NayaLocale = 'fr' | 'en' | 'pt';
+declare const NAYA_LOCALES: readonly NayaLocale[];
+declare function countryLabel(code: NayaCountryCode): string;
+/** La CNI CEDEAO porte sa MRZ au verso ; les autres pièces n'en ont pas besoin. */
+declare function documentNeedsVerso(doc: NayaDocumentType): boolean;
 /**
- * Fournisseur d'authentification.
+ * Authentification.
  *
- * Deux modes, un seul à renseigner :
- *   • `apiKey`       — la clé d'application est transmise depuis le navigateur.
- *                      Simple, mais la clé est lisible côté client : à réserver
- *                      aux démos et aux intégrations où le front est maîtrisé.
- *   • `sessionToken` — jeton éphémère obtenu par le backend du client, limité à
- *                      une vérification. À privilégier en production.
+ *   • `apiKey` — la clé d'application est transmise depuis le navigateur ; le
+ *     SDK ouvre lui-même la session. Réservé aux démos et aux fronts maîtrisés :
+ *     une clé live doit déclarer ses origines dans le dashboard.
+ *   • `sessionToken` + `verificationId` — la session a été ouverte par le
+ *     backend du client ; le SDK la reprend et n'appelle jamais `/start`.
+ *     À privilégier en production.
  */
 interface NayaAuth {
     apiKey?: string;
     sessionToken?: string;
+    verificationId?: string;
 }
-/** Palette optionnelle : surcharge des couleurs de marque. */
 interface NayaThemeOverrides {
-    /** Couleur principale (défaut : navy Naya #1A3A5C). */
+    /** Couleur principale (défaut : encre Naya #172062). */
     primaryColor?: string;
-    /** Couleur d'accent des CTA (défaut : ambre Naya #F5A623). */
+    /** Couleur d'accent des CTA (défaut : flamme Naya #E6950A). */
     accentColor?: string;
+    /** Pile de polices ; défaut : police système. */
+    fontFamily?: string;
+    /** Rayons : `sharp` (4/8 px), `soft` (12/24 px, défaut), `round` (pilule). */
+    radius?: 'sharp' | 'soft' | 'round';
+    /** Thème clair, sombre, ou suivant les préférences du système (défaut). */
+    mode?: 'light' | 'dark' | 'auto';
 }
 /**
- * Emplacement des ressources de détection de vivacité (MediaPipe). Par défaut,
- * elles sont chargées depuis un CDN public. Les applications à CSP stricte
- * (qui bloquent les hôtes externes) doivent auto-héberger ces fichiers et
- * renseigner ici leurs URL.
+ * Ressources de détection de vivacité (MediaPipe). Par défaut, servies par le
+ * CDN Naya, avec repli automatique sur les CDN publics si celui-ci ne répond
+ * pas. Les applications à CSP stricte peuvent auto-héberger ces fichiers.
  */
+type NayaOcrConfirmMode = 'display' | 'edit';
 interface NayaLivenessAssets {
     /** URL du module ESM `@mediapipe/tasks-vision` (`vision_bundle.mjs`). */
     esmUrl?: string;
@@ -65,6 +69,52 @@ interface NayaLivenessAssets {
     wasmBaseUrl?: string;
     /** URL du modèle `.task` de Face Landmarker. */
     modelUrl?: string;
+    /** Empreinte SHA-256 attendue du modèle (hex) ; `null` désactive le contrôle. */
+    modelSha256?: string | null;
+    /** Replier sur jsDelivr / Google si l'hôte principal échoue (défaut : true). */
+    fallbackToPublicCdn?: boolean;
+}
+interface NayaConsentOptions {
+    /** Lien vers la politique de confidentialité affichée sur l'écran de consentement. */
+    policyUrl?: string;
+    /** Version du texte de consentement, transmise à l'API. */
+    version?: string;
+}
+interface NayaCaptureOptions {
+    /** Déclenchement automatique quand la qualité est stable (défaut : true). */
+    autoCapture?: boolean;
+    /** Côté max de l'image envoyée, en pixels (défaut : 1600 ; 1200 sur réseau lent). */
+    maxDimension?: number;
+    /**
+     * Import d'une photo depuis un fichier : `auto` (proposé quand aucune caméra
+     * arrière n'est disponible, typiquement sur ordinateur), `always`, `never`.
+     */
+    fileUpload?: 'auto' | 'always' | 'never';
+}
+interface NayaLivenessOptions {
+    /** Délai avant de proposer des conseils et un nouvel essai (défaut : 45 s). */
+    timeoutMs?: number;
+    /**
+     * Après un délai dépassé ou deux échecs, proposer le parcours sans défi
+     * (selfie seul, décision plafonnée à la revue). Défaut : true.
+     */
+    allowPassive?: boolean;
+    /** Précharger le modèle pendant la capture du document (défaut : true). */
+    preload?: boolean;
+}
+interface NayaHandoffOptions {
+    /** Proposer le relais vers un téléphone par QR code sur ordinateur (défaut : true). */
+    enabled?: boolean;
+    /** Page hébergée qui reprend la session ; défaut : celle configurée côté API. */
+    baseUrl?: string;
+}
+type NayaEventName = 'ready' | 'step' | 'session' | 'consent' | 'document_captured' | 'liveness_step' | 'liveness_done' | 'submitted' | 'result' | 'error' | 'cancelled' | 'handoff_shown';
+interface NayaEvent {
+    type: NayaEventName;
+    /** `performance.now()` au moment de l'événement. */
+    at: number;
+    step?: string;
+    data?: Record<string, unknown>;
 }
 interface NayaConfig {
     /** Pré-sélectionne le pays : l'utilisateur ne le choisit plus. */
@@ -76,16 +126,13 @@ interface NayaConfig {
     documentTypes?: readonly NayaDocumentType[];
     /** Pays proposés quand `country` n'est pas défini. */
     countries?: readonly NayaCountryCode[];
-    /** Langue de l'interface. */
+    /** Langue de l'interface ; défaut : celle du navigateur (fr, en, pt). */
     locale?: NayaLocale;
-    /**
-     * URL (HTTPS) notifiée par le serveur Naya à chaque décision sur cette
-     * session — décision automatique puis, le cas échéant, revue manuelle.
-     */
+    /** URL HTTPS notifiée par le serveur Naya à chaque décision (mode apiKey). */
     callbackUrl?: string;
     /** Nombre de parcours autorisés après un rejet (bouton « Réessayer »). */
     maxAttempts?: number;
-    /** Surcharge des couleurs de marque. */
+    /** Surcharge des couleurs, de la police, des rayons et du mode. */
     theme?: NayaThemeOverrides;
     /** URL d'un logo client, affiché à côté de « Propulsé par Naya ID ». */
     clientLogoUrl?: string;
@@ -93,6 +140,38 @@ interface NayaConfig {
     baseUrl?: string;
     /** Auto-hébergement des ressources MediaPipe (CSP stricte). */
     livenessAssets?: NayaLivenessAssets;
+    /** Monter le parcours dans cet élément au lieu d'un overlay plein écran. */
+    container?: HTMLElement | null;
+    /** Écran de consentement biométrique ; `false` si recueilli en amont par l'hôte. */
+    consent?: boolean | NayaConsentOptions;
+    /**
+     * Écran des données lues sur le document. `false` (défaut) : rien n'est
+     * montré ; `'display'` : lecture seule, l'utilisateur dit si c'est exact ;
+     * `'edit'` : il peut saisir des corrections. Dans tous les cas l'extraction
+     * (`ocrData`) reste intacte côté serveur : ce qui est saisi part à part
+     * (`declaredData`) et un écart plafonne la décision à la revue.
+     * `true` vaut `'edit'`.
+     */
+    confirmOcr?: boolean | NayaOcrConfirmMode;
+    capture?: NayaCaptureOptions;
+    liveness?: NayaLivenessOptions;
+    handoff?: boolean | NayaHandoffOptions;
+    /**
+     * Ouvrir la session dès le choix du document pour recouvrir la latence
+     * réseau. Attention : une session ouverte peut être facturée même si la
+     * capture est abandonnée. Défaut : false.
+     */
+    eagerSession?: boolean;
+    /** Télémétrie anonyme (entonnoir, erreurs, qualité). Défaut : true. */
+    telemetry?: boolean;
+    /** Journal détaillé dans la console (préfixe `[NayaId]`). */
+    debug?: boolean;
+    /** Retour haptique aux étapes clés sur mobile (défaut : true). */
+    haptics?: boolean;
+    /** Surcharge de libellés, par clé de chaîne. */
+    strings?: Partial<Record<string, string>>;
+    /** Hook d'événements pour l'analytique de l'hôte. */
+    onEvent?: (event: NayaEvent) => void;
 }
 /** Configuration effective : `NayaConfig` avec tous les défauts appliqués. */
 interface ResolvedNayaConfig {
@@ -106,20 +185,29 @@ interface ResolvedNayaConfig {
     clientLogoUrl?: string;
     baseUrl: string;
     livenessAssets: NayaLivenessAssets;
+    container: HTMLElement | null;
+    consent: false | Required<NayaConsentOptions>;
+    confirmOcr: false | NayaOcrConfirmMode;
+    capture: Required<NayaCaptureOptions>;
+    liveness: Required<NayaLivenessOptions>;
+    handoff: Required<NayaHandoffOptions>;
+    eagerSession: boolean;
+    telemetry: boolean;
+    debug: boolean;
+    haptics: boolean;
+    strings: Partial<Record<string, string>>;
+    onEvent?: (event: NayaEvent) => void;
 }
-declare const NAYA_DEFAULT_PRIMARY = "#1A3A5C";
-declare const NAYA_DEFAULT_ACCENT = "#F5A623";
+declare const NAYA_DEFAULT_PRIMARY = "#172062";
+declare const NAYA_DEFAULT_ACCENT = "#E6950A";
 declare const NAYA_DEFAULT_BASE_URL = "https://api.naya.41devs.com/v1";
+/** Langue du navigateur ramenée aux langues supportées. */
+declare function detectLocale(): NayaLocale;
 /** Applique les valeurs par défaut à une configuration partielle. */
 declare function resolveConfig(config?: NayaConfig): ResolvedNayaConfig;
-/** Libellé lisible d'un code pays. */
-declare function countryLabel(code: NayaCountryCode): string;
-/** La CNI CEDEAO porte sa MRZ au verso ; passeport et permis n'en ont pas besoin. */
-declare function documentNeedsVerso(doc: NayaDocumentType): boolean;
 
 /**
  * Résultat du parcours, rendu à l'application cliente à la fermeture du SDK.
- * Miroir fidèle des modèles Flutter et Angular.
  */
 /** Issue du parcours de vérification. */
 type NayaStatus = 
@@ -131,8 +219,14 @@ type NayaStatus =
  | 'rejected'
 /** L'utilisateur a quitté le parcours avant la fin. */
  | 'cancelled'
-/** Erreur technique (réseau, serveur…) ayant interrompu le parcours. */
+/** Erreur technique (réseau, serveur, caméra…) ayant interrompu le parcours. */
  | 'error';
+/**
+ * Code d'erreur stable, indépendant de la langue. `errorMessage` porte le
+ * détail lisible (souvent celui du serveur) et `requestId` la référence à
+ * communiquer au support.
+ */
+type NayaErrorCode = 'network' | 'timeout' | 'unauthorized' | 'origin_not_allowed' | 'session_expired' | 'session_closed' | 'quota' | 'kyb_pending' | 'rate_limited' | 'upload_limit' | 'bad_request' | 'server' | 'camera_denied' | 'camera_unavailable' | 'camera_busy' | 'liveness_assets' | 'unsupported_browser' | 'in_app_browser' | 'insecure_context' | 'invalid_params' | 'unknown';
 /**
  * Données d'identité extraites du document par l'OCR Naya, éventuellement
  * corrigées par l'utilisateur.
@@ -166,87 +260,145 @@ interface NayaResult {
      * les notifications `callbackUrl` et le dashboard.
      */
     verificationId?: string;
-    /** Score de risque agrégé 0-100 (plus haut = plus sûr). */
+    /** Motifs stables de la décision (DOC_EXPIRED, FACE_MISMATCH…). */
+    reasonCodes?: string[];
+    /** `active` (défi exécuté) ou `passive` (selfie seul). */
+    livenessMode?: 'active' | 'passive';
     riskScore?: number;
-    /** Concordance faciale document ↔ selfie, 0-100. */
     matchScore?: number;
-    /** Intégrité du document, 0-100. */
     authenticityScore?: number;
-    /** Score de vivacité, 0-100. */
     livenessScore?: number;
-    /** Confiance de l'extraction OCR, 0-100. */
     ocrConfidence?: number;
-    /** Données d'identité finales (OCR fusionné avec les corrections). */
+    /** Extraction brute du document, telle que lue par le serveur ; jamais altérée. */
     ocrData?: NayaOcrData;
-    /** Note d'analyse produite par le pipeline Naya. */
+    /** Ce que l'utilisateur a déclaré (mode `confirmOcr: 'edit'`), conservé à part. */
+    declaredData?: Record<string, string>;
+    /** Champs où `declaredData` diffère de `ocrData`. */
+    dataMismatches?: string[];
+    /** L'utilisateur a contesté les données lues (mode `'display'`). */
+    dataDisputed?: boolean;
+    /** Note d'analyse du serveur (rejet, revue). */
     note?: string;
-    /** Détail de l'erreur quand `status` vaut `'error'`. */
+    /** Renseignés quand `status === 'error'`. */
+    errorCode?: NayaErrorCode;
     errorMessage?: string;
+    /** Statut HTTP de l'erreur serveur, le cas échéant. */
+    statusCode?: number;
+    /** Référence de requête renvoyée par l'API, à transmettre au support. */
+    requestId?: string;
 }
 declare function cancelledResult(verificationId?: string): NayaResult;
-declare function errorResult(errorMessage: string, verificationId?: string): NayaResult;
+declare function errorResult(errorMessage: string, verificationId?: string, extra?: {
+    errorCode?: NayaErrorCode;
+    statusCode?: number;
+    requestId?: string;
+}): NayaResult;
 
 /**
- * Client HTTP du pipeline de vérification Naya.
- *
- * Bâti sur `fetch` natif, sans dépendance. Les délais sont dimensionnés pour les
- * étapes longues (OCR et décision côté serveur).
- *
- * Authentification via `NayaAuth` : `apiKey` (en-tête `X-API-Key`) ou
- * `sessionToken` (en-tête `Authorization: Bearer`). Le choix est transparent
- * pour le reste du SDK.
+ * Détection des capacités du navigateur, avant d'ouvrir l'interface : mieux
+ * vaut refuser proprement avec la raison que d'échouer au moment du selfie.
  */
-/** Erreur renvoyée par l'API Naya ou par le transport réseau. */
-declare class NayaApiError extends Error {
-    readonly statusCode?: number;
-    constructor(message: string, statusCode?: number);
+interface NayaSupport {
+    ok: boolean;
+    code?: NayaErrorCode;
+    reason?: string;
+    secureContext: boolean;
+    mediaDevices: boolean;
+    webAssembly: boolean;
+    webGL: boolean;
+    inAppBrowser: boolean;
+    inAppBrowserName: string | null;
+    mobile: boolean;
+    ios: boolean;
+    android: boolean;
+    /** Classe d'appareil rapportée à la télémétrie : `mobile` | `tablet` | `desktop`. */
+    deviceClass: 'mobile' | 'tablet' | 'desktop';
 }
 
 /**
- * SDK JavaScript officiel de Naya ID — vérification d'identité (eKYC) clé en
- * main pour l'Afrique de l'Ouest (zone CEDEAO), chargeable en une balise
- * `<script>`.
+ * Client HTTP du pipeline de vérification Naya.
  *
- * Pendant web « sans framework » des SDK Flutter et Angular : même parcours,
- * mêmes écrans, même contrat d'API.
+ * Bâti sur `fetch` natif, sans dépendance. Les délais sont dimensionnés pour
+ * les étapes longues (OCR et décision côté serveur). Les échecs transitoires
+ * (réseau, délai, 429, 502-504) sont retentés avec un délai croissant.
  *
- * ```html
- * <script src="https://cdn.jsdelivr.net/npm/@41devs/naya-id-js@0/dist/naya-id.min.js"></script>
- * <script>
- *   const result = await NayaId.startVerification({
- *     apiKey: 'naya_live_xxx',
- *     config: { country: 'BJ' },
- *   });
- *   // result.status → 'approved' | 'review' | 'rejected' | 'cancelled' | 'error'
- * </script>
- * ```
+ * Authentification : `apiKey` (en-tête `X-API-Key`) ou `sessionToken`
+ * (en-tête `Authorization: Bearer`).
  */
+/** Erreur typée renvoyée par l'API Naya ou par le transport réseau. */
+declare class NayaApiError extends Error {
+    readonly code: NayaErrorCode;
+    readonly statusCode?: number;
+    readonly requestId?: string;
+    readonly retryable: boolean;
+    constructor(message: string, code: NayaErrorCode, opts?: {
+        statusCode?: number;
+        requestId?: string;
+        retryable?: boolean;
+    });
+}
 
 interface StartVerificationParams {
     /** Clé d'application `naya_live_…` / `naya_test_…` (lisible côté navigateur). */
     apiKey?: string;
-    /** Jeton de session éphémère obtenu par votre backend (à privilégier). */
+    /**
+     * Jeton de session rendu par `POST /verifications/start`, obtenu par votre
+     * backend (à privilégier). Va toujours avec `verificationId` : le SDK reprend
+     * la vérification ouverte par le serveur au lieu d'en ouvrir une nouvelle.
+     */
     sessionToken?: string;
-    /** Alternative aux deux champs ci-dessus, forme objet. */
+    /** Identifiant de la vérification ouverte par votre backend (avec `sessionToken`). */
+    verificationId?: string;
+    /** Alternative aux champs ci-dessus, forme objet. */
     auth?: NayaAuth;
-    /** Configuration optionnelle (pays, documents, langue, callbackUrl, thème…). */
+    /** Configuration optionnelle (pays, documents, langue, thème, conteneur…). */
     config?: NayaConfig;
 }
 /**
  * Lance le parcours de vérification d'identité : l'interface Naya s'ouvre en
- * plein écran au-dessus de la page, prend en charge la capture du document, la
- * vivacité et la décision, puis résout un `NayaResult` et rend la main.
+ * plein écran au-dessus de la page (ou dans `config.container`), prend en
+ * charge le consentement, la capture du document, la vivacité, la
+ * confirmation des données et la décision, puis résout un `NayaResult`.
  *
- * **Ne rejette jamais** : une erreur réseau ou une annulation revient toujours
- * sous forme de `NayaResult` (`status: 'error'` ou `'cancelled'`).
+ * **Ne rejette jamais** : une erreur ou une annulation revient toujours sous
+ * forme de `NayaResult` (`status: 'error'` avec `errorCode`, ou `'cancelled'`).
  */
 declare function startVerification(params: StartVerificationParams): Promise<NayaResult>;
+/** Vérifie que le navigateur peut exécuter le parcours, avant de l'ouvrir. */
+declare function isSupported(): NayaSupport;
+interface NayaVerification {
+    /** Monte l'interface et résout à la fermeture. Un seul `open` à la fois. */
+    open(): Promise<NayaResult>;
+    /** Ferme le parcours (résultat `cancelled`). */
+    close(): void;
+    /** Abonne un écouteur ; rend la fonction de désabonnement. */
+    on(event: NayaEventName | 'result', cb: (payload: NayaEvent | NayaResult) => void): () => void;
+    /** Ferme et libère les écouteurs. */
+    destroy(): void;
+    readonly isOpen: boolean;
+}
+/**
+ * API programmatique : instance réutilisable avec `open`, `close`, `on`.
+ * Utile aux enveloppes de framework et à l'analytique de l'hôte.
+ */
+declare function create(params: StartVerificationParams): NayaVerification;
+/**
+ * `<naya-id-verification api-key="…" country="BJ" locale="fr" inline auto>`
+ * Attributs : `api-key`, `session-token`, `verification-id`, `locale`,
+ * `country`, `document-types` (liste séparée par des virgules), `callback-url`,
+ * `inline` (monte dans l'élément), `auto` (démarre à l'insertion), `theme-primary`,
+ * `theme-accent`, `theme-mode`. Événements : `naya-event`, `naya-result`.
+ */
+declare function defineElement(tag?: string): void;
 /** Version du SDK. */
-declare const version = "0.1.0";
+declare const version: string;
 
 declare const _default: {
     startVerification: typeof startVerification;
+    create: typeof create;
+    isSupported: typeof isSupported;
+    defineElement: typeof defineElement;
     version: string;
 };
 
-export { NAYA_COUNTRIES, NAYA_DEFAULT_ACCENT, NAYA_DEFAULT_BASE_URL, NAYA_DEFAULT_PRIMARY, NAYA_DOCUMENT_TYPES, NayaApiError, type NayaAuth, type NayaConfig, type NayaCountryCode, type NayaDocumentType, type NayaLivenessAssets, type NayaLocale, type NayaOcrData, type NayaResult, type NayaStatus, type NayaThemeOverrides, type ResolvedNayaConfig, type StartVerificationParams, cancelledResult, countryLabel, _default as default, documentNeedsVerso, errorResult, ocrToDeclaredData, parseOcrData, resolveConfig, startVerification, version };
+export { NAYA_COUNTRIES, NAYA_DEFAULT_ACCENT, NAYA_DEFAULT_BASE_URL, NAYA_DEFAULT_PRIMARY, NAYA_DOCUMENT_TYPES, NAYA_LOCALES, NayaApiError, type NayaAuth, type NayaCaptureOptions, type NayaConfig, type NayaConsentOptions, type NayaCountryCode, type NayaDocumentType, type NayaErrorCode, type NayaEvent, type NayaEventName, type NayaHandoffOptions, type NayaLivenessAssets, type NayaLivenessOptions, type NayaLocale, type NayaOcrData, type NayaResult, type NayaStatus, type NayaSupport, type NayaThemeOverrides, type NayaVerification, type ResolvedNayaConfig, type StartVerificationParams, cancelledResult, countryLabel, create, _default as default, defineElement, detectLocale, documentNeedsVerso, errorResult, isSupported, ocrToDeclaredData, parseOcrData, resolveConfig, startVerification, version };