@scanid-africa/mrz-scanner 1.0.0

package/README.md

@@ -0,0 +1,166 @@
+# @scanid/mrz-scanner
+
+Scanner MRZ automatique pour React Native (Expo) et React web, propulsé par [ScanID Africa](https://scanid.africa).
+
+Scan automatique déclenché par frames — aucun bouton. Dès qu'une MRZ valide est détectée, `onSuccess` est appelé.
+
+---
+
+## Installation
+
+```bash
+# npm
+npm install @scanid/mrz-scanner
+
+# Expo (peer deps)
+npx expo install expo-camera expo-image-manipulator expo-haptics
+```
+
+---
+
+## Usage rapide
+
+### React Native / Expo
+
+```tsx
+import { MrzScannerNative } from '@scanid/mrz-scanner'
+
+<MrzScannerNative
+  api={{ mode: 'selfhosted', apiUrl: 'http://192.168.1.10:3000' }}
+  onSuccess={(result) => console.log(result.fields)}
+  onClose={() => navigation.goBack()}
+/>
+```
+
+### React web / Next.js
+
+```tsx
+// Next.js App Router — import dynamique obligatoire (SSR incompatible getUserMedia)
+import dynamic from 'next/dynamic'
+
+const MrzScannerWeb = dynamic(
+  () => import('@scanid/mrz-scanner').then(m => m.MrzScannerWeb),
+  { ssr: false }
+)
+
+<MrzScannerWeb
+  api={{ mode: 'cloud', apiKey: 'sk_live_...', region: 'west-africa' }}
+  onSuccess={(result) => console.log(result.fields)}
+  width="100%"
+  height="480px"
+/>
+```
+
+---
+
+## Configuration API
+
+### Self-hosted (votre instance mrz-nest)
+
+```ts
+api={{ mode: 'selfhosted', apiUrl: 'https://your-api.com' }}
+```
+
+### ScanID Africa Cloud
+
+```ts
+api={{ mode: 'cloud', apiKey: 'sk_live_xxx', region: 'west-africa' }}
+// regions: 'west-africa' | 'north-africa' | 'auto'
+```
+
+---
+
+## Props
+
+### Communes (native + web)
+
+| Prop | Type | Défaut | Description |
+|---|---|---|---|
+| `api` | `ApiConfig` | requis | Config API (self-hosted ou cloud) |
+| `onSuccess` | `(result: MrzResult) => void` | requis | Appelé quand une MRZ est détectée |
+| `onError` | `(error: Error) => void` | — | Appelé si maxAttempts est atteint |
+| `onClose` | `() => void` | — | Bouton fermer |
+| `maxAttempts` | `number` | `10` | Tentatives avant abandon |
+| `scanIntervalMs` | `number` | `1500` | Intervalle entre deux captures (ms) |
+
+### React Native uniquement
+
+| Prop | Défaut | Description |
+|---|---|---|
+| `hint` | `"Alignez la zone MRZ dans le cadre"` | Texte sous le cadre |
+| `frameColor` | `"#FFFFFF"` | Couleur du cadre |
+| `successColor` | `"#34d399"` | Couleur du cadre en succès |
+
+### React web uniquement
+
+| Prop | Défaut | Description |
+|---|---|---|
+| `width` | `"100%"` | Largeur du composant |
+| `height` | `"480px"` | Hauteur du composant |
+| `className` | — | Classe CSS additionnelle |
+
+---
+
+## Type MrzResult
+
+```ts
+interface MrzResult {
+  documentType: 'TD1' | 'TD2' | 'TD3' | 'DL'
+  documentLabel: string        // "Passeport", "Carte d'identité nationale"…
+  corrected: boolean           // true si mrz-fast a corrigé des erreurs OCR
+  fields: {
+    surname: string | null
+    givenNames: string | null
+    nationality: string | null
+    issuingState: string | null
+    dateOfBirth: string | null      // YYMMDD
+    sex: 'male' | 'female' | 'unspecified' | null
+    expirationDate: string | null   // YYMMDD
+    documentNumber: string | null
+    personalNumber: string | null
+  }
+}
+```
+
+---
+
+## Architecture
+
+```
+src/
+├── shared/
+│   ├── types.ts         # Types TypeScript partagés
+│   ├── api-client.ts    # Client fetch (self-hosted + cloud)
+│   └── useScanner.ts    # Hook — boucle de scan automatique
+├── native/
+│   └── MrzScannerNative.tsx  # Composant Expo (expo-camera)
+└── web/
+    └── MrzScannerWeb.tsx     # Composant React web (getUserMedia)
+```
+
+Le hook `useScanner` est partagé entre les deux plateformes. La seule
+différence est `captureFrame` (expo-camera vs canvas) et `sendToApi`
+(URI vs Blob).
+
+---
+
+## Flux de scan automatique
+
+```
+onCameraReady
+    ↓
+setInterval(1500ms)
+    ↓
+captureFrame() → recadrage 38% bas (zone MRZ)
+    ↓
+sendToApi() → POST /mrz/scan
+    ↓
+✅ valid  → onSuccess() + stop scan
+❌ invalid → attempts++ → retry | onError()
+```
+
+---
+
+## Licence
+
+MIT © ScanID Africa

package/dist/index.js

@@ -0,0 +1,7 @@
+// ─── Composants ──────────────────────────────────────────────────────────────
+export { MrzScannerNative } from './native/MrzScannerNative';
+export { MrzScannerWeb } from './web/MrzScannerWeb';
+// ─── Hook bas niveau (pour usage custom) ─────────────────────────────────────
+export { useScanner } from './shared/useScanner';
+// ─── Client API (pour usage standalone) ──────────────────────────────────────
+export { sendImageToApi, sendUriToApi } from './shared/api-client';

package/dist/native/MrzScannerNative.js

@@ -0,0 +1,220 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useRef, } from 'react';
+import { ActivityIndicator, Animated, Easing, Platform, Pressable, StyleSheet, Text, View, } from 'react-native';
+import { CameraView, useCameraPermissions } from 'expo-camera';
+import { manipulateAsync, SaveFormat } from 'expo-image-manipulator';
+import { useScanner } from '../shared/useScanner';
+import { sendUriToApi } from '../shared/api-client';
+// Tentative d'import haptics — optionnel
+let Haptics = null;
+try {
+    Haptics = require('expo-haptics');
+}
+catch (_a) { }
+// ─── Labels d'état ────────────────────────────────────────────────────────────
+function getStatusLabel(state, attempts, maxAttempts, hint) {
+    switch (state) {
+        case 'idle':
+            return 'Initialisation…';
+        case 'scanning':
+            return hint;
+        case 'analyzing':
+            return 'Lecture en cours…';
+        case 'success':
+            return '✓ Document reconnu !';
+        case 'failed':
+            return `Scan échoué après ${attempts}/${maxAttempts} tentatives`;
+    }
+}
+// ─── Composant principal ──────────────────────────────────────────────────────
+/**
+ * MrzScannerNative
+ *
+ * Composant React Native (Expo) de scan MRZ automatique.
+ * Démarre dès que la caméra est prête — aucun bouton requis.
+ *
+ * Usage:
+ * ```tsx
+ * <MrzScannerNative
+ *   api={{ mode: 'selfhosted', apiUrl: 'http://192.168.1.10:3000' }}
+ *   onSuccess={(result) => console.log(result.fields)}
+ *   onClose={() => navigation.goBack()}
+ * />
+ * ```
+ */
+export function MrzScannerNative({ api, onSuccess, onError, onClose, maxAttempts = 10, scanIntervalMs = 1500, hint = 'Alignez la zone MRZ dans le cadre', frameColor = '#FFFFFF', successColor = '#34d399', }) {
+    const [permission, requestPermission] = useCameraPermissions();
+    const cameraRef = useRef(null);
+    // Animations
+    const pulseAnim = useRef(new Animated.Value(1)).current;
+    const colorAnim = useRef(new Animated.Value(0)).current;
+    const pulseLoop = useRef(null);
+    function startPulse() {
+        pulseLoop.current = Animated.loop(Animated.sequence([
+            Animated.timing(pulseAnim, {
+                toValue: 1.025,
+                duration: 700,
+                easing: Easing.inOut(Easing.ease),
+                useNativeDriver: true,
+            }),
+            Animated.timing(pulseAnim, {
+                toValue: 1,
+                duration: 700,
+                easing: Easing.inOut(Easing.ease),
+                useNativeDriver: true,
+            }),
+        ]));
+        pulseLoop.current.start();
+    }
+    function flashSuccess() {
+        var _a;
+        (_a = pulseLoop.current) === null || _a === void 0 ? void 0 : _a.stop();
+        Animated.timing(colorAnim, {
+            toValue: 1,
+            duration: 300,
+            useNativeDriver: false,
+        }).start();
+    }
+    // Capture + recadrage sur les 38% bas (zone MRZ)
+    const captureFrame = useCallback(async () => {
+        if (!cameraRef.current)
+            return null;
+        try {
+            const photo = await cameraRef.current.takePictureAsync({
+                quality: 0.85,
+                skipProcessing: true,
+            });
+            if (!photo)
+                return null;
+            const cropped = await manipulateAsync(photo.uri, [
+                {
+                    crop: {
+                        originX: 0,
+                        originY: Math.floor(photo.height * 0.62),
+                        width: photo.width,
+                        height: Math.floor(photo.height * 0.38),
+                    },
+                },
+            ], { compress: 0.85, format: SaveFormat.JPEG });
+            return { uri: cropped.uri };
+        }
+        catch (_a) {
+            return null;
+        }
+    }, []);
+    const handleSuccess = useCallback((result) => {
+        flashSuccess();
+        Haptics === null || Haptics === void 0 ? void 0 : Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success);
+        // Petit délai pour laisser voir le feedback visuel avant de fermer
+        setTimeout(() => onSuccess(result), 500);
+    }, [onSuccess]);
+    const { scanState, attempts, start, reset } = useScanner({
+        api,
+        maxAttempts,
+        scanIntervalMs,
+        onSuccess: handleSuccess,
+        onError,
+        captureFrame,
+        sendToApi: async (cfg, payload) => sendUriToApi(cfg, payload),
+    });
+    // Démarrer quand la caméra est prête
+    function onCameraReady() {
+        startPulse();
+        start();
+    }
+    const borderColor = colorAnim.interpolate({
+        inputRange: [0, 1],
+        outputRange: [frameColor, successColor],
+    });
+    if (!permission)
+        return _jsx(View, { style: styles.container });
+    if (!permission.granted) {
+        return (_jsxs(View, { style: styles.permContainer, children: [_jsx(Text, { style: styles.permText, children: "Acc\u00E8s \u00E0 la cam\u00E9ra requis pour scanner le document." }), _jsx(Pressable, { style: styles.permBtn, onPress: requestPermission, children: _jsx(Text, { style: styles.permBtnText, children: "Autoriser la cam\u00E9ra" }) })] }));
+    }
+    return (_jsxs(View, { style: styles.container, children: [_jsx(CameraView, { ref: cameraRef, style: StyleSheet.absoluteFill, facing: "back", onCameraReady: onCameraReady }), _jsxs(View, { style: styles.overlay, pointerEvents: "none", children: [_jsx(View, { style: styles.topMask }), _jsxs(View, { style: styles.middleRow, children: [_jsx(View, { style: styles.sideMask }), _jsxs(Animated.View, { style: [
+                                    styles.frame,
+                                    {
+                                        borderColor,
+                                        transform: [{ scale: pulseAnim }],
+                                    },
+                                ], children: [scanState === 'analyzing' && (_jsx(ActivityIndicator, { size: "small", color: "rgba(255,255,255,0.8)", style: styles.spinner })), scanState === 'success' && (_jsx(Text, { style: [styles.successIcon, { color: successColor }], children: "\u2713" }))] }), _jsx(View, { style: styles.sideMask })] }), _jsx(View, { style: styles.bottomMask })] }), _jsx(View, { style: styles.statusBar, pointerEvents: "none", children: _jsx(Text, { style: styles.statusText, children: getStatusLabel(scanState, attempts, maxAttempts, hint) }) }), scanState === 'failed' && (_jsx(View, { style: styles.retryRow, children: _jsx(Pressable, { style: styles.retryBtn, onPress: () => {
+                        reset();
+                        setTimeout(start, 100);
+                    }, children: _jsx(Text, { style: styles.retryText, children: "R\u00E9essayer" }) }) })), onClose && (_jsx(Pressable, { style: styles.closeBtn, onPress: onClose, hitSlop: 12, children: _jsx(Text, { style: styles.closeTxt, children: "\u2715" }) }))] }));
+}
+// ─── Styles ───────────────────────────────────────────────────────────────────
+const FRAME_H = 100;
+const styles = StyleSheet.create({
+    container: { flex: 1, backgroundColor: '#000' },
+    permContainer: {
+        flex: 1,
+        justifyContent: 'center',
+        alignItems: 'center',
+        backgroundColor: '#000',
+        padding: 32,
+    },
+    permText: {
+        color: '#fff',
+        fontSize: 16,
+        textAlign: 'center',
+        marginBottom: 20,
+    },
+    permBtn: {
+        backgroundColor: '#c8ff00',
+        borderRadius: 8,
+        paddingHorizontal: 24,
+        paddingVertical: 12,
+    },
+    permBtnText: { color: '#000', fontWeight: '700', fontSize: 15 },
+    overlay: Object.assign({}, StyleSheet.absoluteFill),
+    topMask: { flex: 3, backgroundColor: 'rgba(0,0,0,0.55)' },
+    middleRow: { flexDirection: 'row', height: FRAME_H },
+    sideMask: { flex: 1, backgroundColor: 'rgba(0,0,0,0.55)' },
+    bottomMask: { flex: 2, backgroundColor: 'rgba(0,0,0,0.55)' },
+    frame: {
+        flex: 5,
+        borderWidth: 2,
+        borderRadius: 6,
+        justifyContent: 'center',
+        alignItems: 'center',
+    },
+    spinner: { position: 'absolute', top: 8, right: 8 },
+    successIcon: { fontSize: 28, fontWeight: '700' },
+    statusBar: {
+        position: 'absolute',
+        bottom: 100,
+        left: 0,
+        right: 0,
+        alignItems: 'center',
+        paddingHorizontal: 32,
+    },
+    statusText: {
+        color: '#fff',
+        fontSize: 14,
+        textAlign: 'center',
+        textShadowColor: 'rgba(0,0,0,0.8)',
+        textShadowOffset: { width: 0, height: 1 },
+        textShadowRadius: 4,
+    },
+    retryRow: {
+        position: 'absolute',
+        bottom: 50,
+        left: 0,
+        right: 0,
+        alignItems: 'center',
+    },
+    retryBtn: {
+        backgroundColor: '#c8ff00',
+        borderRadius: 8,
+        paddingHorizontal: 28,
+        paddingVertical: 12,
+    },
+    retryText: { color: '#000', fontWeight: '700', fontSize: 15 },
+    closeBtn: {
+        position: 'absolute',
+        top: Platform.OS === 'ios' ? 56 : 20,
+        right: 20,
+        padding: 10,
+    },
+    closeTxt: { color: '#fff', fontSize: 22 },
+});

package/dist/shared/api-client.js

@@ -0,0 +1,72 @@
+const CLOUD_BASE_URL = 'https://api.scanid.africa';
+/**
+ * Résout l'URL de l'endpoint scan selon la config (self-hosted ou cloud).
+ */
+function resolveEndpoint(api) {
+    var _a;
+    if (api.mode === 'selfhosted') {
+        return `${api.apiUrl.replace(/\/$/, '')}/mrz/scan`;
+    }
+    // Cloud : routing régional optionnel
+    const region = (_a = api.region) !== null && _a !== void 0 ? _a : 'auto';
+    const base = region === 'west-africa'
+        ? 'https://wa.api.scanid.africa'
+        : region === 'north-africa'
+            ? 'https://na.api.scanid.africa'
+            : CLOUD_BASE_URL;
+    return `${base}/mrz/scan`;
+}
+/**
+ * Construit les headers selon le mode.
+ * Self-hosted : pas d'auth par défaut.
+ * Cloud : Bearer token depuis la clé API.
+ */
+function buildHeaders(api) {
+    if (api.mode === 'cloud') {
+        return { Authorization: `Bearer ${api.apiKey}` };
+    }
+    return {};
+}
+/**
+ * Envoie un blob/File image à l'API MRZ et retourne le résultat parsé.
+ * Utilisable depuis React Native (uri → FormData) et depuis le web (File/Blob).
+ */
+export async function sendImageToApi(api, imageBlob, filename = 'mrz.jpg') {
+    var _a, _b;
+    const formData = new FormData();
+    formData.append('image', imageBlob, filename);
+    const response = await fetch(resolveEndpoint(api), {
+        method: 'POST',
+        headers: buildHeaders(api),
+        body: formData,
+    });
+    const json = await response.json();
+    if (!response.ok) {
+        throw new Error((_b = (_a = json === null || json === void 0 ? void 0 : json.message) !== null && _a !== void 0 ? _a : json === null || json === void 0 ? void 0 : json.error) !== null && _b !== void 0 ? _b : `Erreur API (${response.status})`);
+    }
+    return json.data;
+}
+/**
+ * Variante React Native : construit un FormData compatible RN
+ * à partir d'un URI local (retourné par expo-camera).
+ */
+export async function sendUriToApi(api, uri) {
+    var _a, _b;
+    const formData = new FormData();
+    // React Native accepte un objet { uri, name, type } dans FormData
+    formData.append('image', {
+        uri,
+        name: 'mrz.jpg',
+        type: 'image/jpeg',
+    });
+    const response = await fetch(resolveEndpoint(api), {
+        method: 'POST',
+        headers: buildHeaders(api),
+        body: formData,
+    });
+    const json = await response.json();
+    if (!response.ok) {
+        throw new Error((_b = (_a = json === null || json === void 0 ? void 0 : json.message) !== null && _a !== void 0 ? _a : json === null || json === void 0 ? void 0 : json.error) !== null && _b !== void 0 ? _b : `Erreur API (${response.status})`);
+    }
+    return json.data;
+}

package/dist/shared/types.js

@@ -0,0 +1,2 @@
+// ─── Résultat MRZ ─────────────────────────────────────────────────────────────
+export {};

package/dist/shared/useScanner.js

@@ -0,0 +1,95 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+const DEFAULT_INTERVAL = 1500;
+const DEFAULT_MAX_ATTEMPTS = 10;
+/**
+ * Hook central du SDK.
+ * Gère la boucle de scan automatique :
+ *   captureFrame → sendToApi → onSuccess | retry | onError
+ *
+ * Utilisé à la fois par MrzScannerNative et MrzScannerWeb,
+ * la seule différence étant captureFrame et sendToApi.
+ */
+export function useScanner({ api, maxAttempts = DEFAULT_MAX_ATTEMPTS, scanIntervalMs = DEFAULT_INTERVAL, onSuccess, onError, captureFrame, sendToApi, }) {
+    const [scanState, setScanState] = useState('idle');
+    const [attempts, setAttempts] = useState(0);
+    // Refs pour éviter les closures obsolètes dans setInterval
+    const intervalRef = useRef(null);
+    const isAnalyzingRef = useRef(false); // verrou — évite les appels concurrents
+    const isMountedRef = useRef(true);
+    const attemptsRef = useRef(0);
+    useEffect(() => {
+        isMountedRef.current = true;
+        return () => {
+            isMountedRef.current = false;
+            stopInterval();
+        };
+    }, []);
+    function stopInterval() {
+        if (intervalRef.current) {
+            clearInterval(intervalRef.current);
+            intervalRef.current = null;
+        }
+    }
+    const analyze = useCallback(async () => {
+        // Verrou : on ne lance pas un nouvel appel si le précédent tourne encore
+        if (isAnalyzingRef.current || !isMountedRef.current)
+            return;
+        isAnalyzingRef.current = true;
+        try {
+            const frame = await captureFrame();
+            if (!frame || !isMountedRef.current)
+                return;
+            if (isMountedRef.current)
+                setScanState('analyzing');
+            // frame est soit { uri: string } (native) soit un Blob (web)
+            const payload = 'uri' in frame ? frame.uri : frame;
+            const result = await sendToApi(api, payload);
+            if (!isMountedRef.current)
+                return;
+            // ✅ Succès
+            stopInterval();
+            setScanState('success');
+            onSuccess(result);
+        }
+        catch (_a) {
+            if (!isMountedRef.current)
+                return;
+            // Retry ou abandon
+            attemptsRef.current += 1;
+            setAttempts(attemptsRef.current);
+            if (attemptsRef.current >= maxAttempts) {
+                stopInterval();
+                setScanState('failed');
+                onError === null || onError === void 0 ? void 0 : onError(new Error(`Scan échoué après ${maxAttempts} tentatives.`));
+            }
+            else {
+                setScanState('scanning');
+            }
+        }
+        finally {
+            isAnalyzingRef.current = false;
+        }
+    }, [api, captureFrame, sendToApi, onSuccess, onError, maxAttempts]);
+    function start() {
+        if (intervalRef.current)
+            return;
+        attemptsRef.current = 0;
+        setAttempts(0);
+        setScanState('scanning');
+        // Première tentative immédiate puis intervalle
+        analyze();
+        intervalRef.current = setInterval(analyze, scanIntervalMs);
+    }
+    function stop() {
+        stopInterval();
+        setScanState('idle');
+    }
+    function reset() {
+        stopInterval();
+        isAnalyzingRef.current = false;
+        attemptsRef.current = 0;
+        setAttempts(0);
+        setScanState('idle');
+    }
+    return { scanState, attempts, start, stop, reset };
+}

package/dist/types/index.d.ts

@@ -0,0 +1,5 @@
+export { MrzScannerNative } from './native/MrzScannerNative';
+export { MrzScannerWeb } from './web/MrzScannerWeb';
+export { useScanner } from './shared/useScanner';
+export { sendImageToApi, sendUriToApi } from './shared/api-client';
+export type { MrzResult, MrzFields, DocumentType, ScanState, ApiConfig, ApiMode, SelfHostedConfig, CloudConfig, MrzScannerNativeProps, MrzScannerWebProps, MrzScannerBaseProps, } from './shared/types';

package/dist/types/native/MrzScannerNative.d.ts

@@ -0,0 +1,18 @@
+import { type ReactElement } from 'react';
+import type { MrzScannerNativeProps } from '../shared/types';
+/**
+ * MrzScannerNative
+ *
+ * Composant React Native (Expo) de scan MRZ automatique.
+ * Démarre dès que la caméra est prête — aucun bouton requis.
+ *
+ * Usage:
+ * ```tsx
+ * <MrzScannerNative
+ *   api={{ mode: 'selfhosted', apiUrl: 'http://192.168.1.10:3000' }}
+ *   onSuccess={(result) => console.log(result.fields)}
+ *   onClose={() => navigation.goBack()}
+ * />
+ * ```
+ */
+export declare function MrzScannerNative({ api, onSuccess, onError, onClose, maxAttempts, scanIntervalMs, hint, frameColor, successColor, }: MrzScannerNativeProps): ReactElement;

package/dist/types/shared/api-client.d.ts

@@ -0,0 +1,11 @@
+import type { ApiConfig, MrzResult } from './types';
+/**
+ * Envoie un blob/File image à l'API MRZ et retourne le résultat parsé.
+ * Utilisable depuis React Native (uri → FormData) et depuis le web (File/Blob).
+ */
+export declare function sendImageToApi(api: ApiConfig, imageBlob: Blob | File, filename?: string): Promise<MrzResult>;
+/**
+ * Variante React Native : construit un FormData compatible RN
+ * à partir d'un URI local (retourné par expo-camera).
+ */
+export declare function sendUriToApi(api: ApiConfig, uri: string): Promise<MrzResult>;

package/dist/types/shared/types.d.ts

@@ -0,0 +1,66 @@
+export type DocumentType = 'TD1' | 'TD2' | 'TD3' | 'DL';
+export interface MrzFields {
+    surname: string | null;
+    givenNames: string | null;
+    nationality: string | null;
+    issuingState: string | null;
+    /** Date de naissance au format YYMMDD */
+    dateOfBirth: string | null;
+    sex: 'male' | 'female' | 'unspecified' | null;
+    /** Date d'expiration au format YYMMDD */
+    expirationDate: string | null;
+    documentNumber: string | null;
+    personalNumber: string | null;
+}
+export interface MrzResult {
+    documentType: DocumentType;
+    documentLabel: string;
+    /** true si mrz-fast a auto-corrigé des erreurs OCR (O↔0, I↔1…) */
+    corrected: boolean;
+    fields: MrzFields;
+}
+export type ScanState = 'idle' | 'scanning' | 'analyzing' | 'success' | 'failed';
+export type ApiMode = 'selfhosted' | 'cloud';
+export interface SelfHostedConfig {
+    mode: 'selfhosted';
+    /** URL de votre instance mrz-nest, ex: "http://192.168.1.10:3000" */
+    apiUrl: string;
+}
+export interface CloudConfig {
+    mode: 'cloud';
+    /** Clé API obtenue sur scanid.africa */
+    apiKey: string;
+    /** Région optionnelle : "west-africa" | "north-africa" | "auto" */
+    region?: 'west-africa' | 'north-africa' | 'auto';
+}
+export type ApiConfig = SelfHostedConfig | CloudConfig;
+export interface MrzScannerBaseProps {
+    /** Configuration de connexion à l'API */
+    api: ApiConfig;
+    /** Appelé dès qu'une MRZ valide est détectée */
+    onSuccess: (result: MrzResult) => void;
+    /** Appelé si le scan échoue après MAX_ATTEMPTS tentatives */
+    onError?: (error: Error) => void;
+    /** Appelé à chaque fermeture du scanner */
+    onClose?: () => void;
+    /** Nombre max de tentatives avant d'abandonner (défaut: 10) */
+    maxAttempts?: number;
+    /** Intervalle entre deux captures en ms (défaut: 1500) */
+    scanIntervalMs?: number;
+}
+export interface MrzScannerNativeProps extends MrzScannerBaseProps {
+    /** Texte affiché sous le cadre (défaut: "Alignez la zone MRZ dans le cadre") */
+    hint?: string;
+    /** Couleur du cadre de scan (défaut: "#FFFFFF") */
+    frameColor?: string;
+    /** Couleur du cadre en cas de succès (défaut: "#34d399") */
+    successColor?: string;
+}
+export interface MrzScannerWebProps extends MrzScannerBaseProps {
+    /** Largeur du composant (défaut: "100%") */
+    width?: string | number;
+    /** Hauteur du composant (défaut: "480px") */
+    height?: string | number;
+    /** Classe CSS additionnelle sur le conteneur */
+    className?: string;
+}

package/dist/types/shared/useScanner.d.ts

@@ -0,0 +1,40 @@
+import type { ApiConfig, MrzResult, ScanState } from './types';
+interface UseScannerOptions {
+    api: ApiConfig;
+    maxAttempts?: number;
+    scanIntervalMs?: number;
+    onSuccess: (result: MrzResult) => void;
+    onError?: (error: Error) => void;
+    /**
+     * Fonction fournie par le composant (native ou web) qui :
+     * 1. Capture une frame depuis la caméra
+     * 2. La recadre sur la zone MRZ si besoin
+     * 3. Retourne une URI (native) ou un Blob (web) prêt à envoyer
+     * Retourne null si la capture échoue (caméra pas prête, etc.)
+     */
+    captureFrame: () => Promise<{
+        uri: string;
+    } | Blob | null>;
+    /**
+     * Fonction d'envoi adaptée à la plateforme
+     * (sendUriToApi pour native, sendImageToApi pour web)
+     */
+    sendToApi: (api: ApiConfig, payload: string | Blob) => Promise<MrzResult>;
+}
+export interface ScannerControls {
+    scanState: ScanState;
+    attempts: number;
+    start: () => void;
+    stop: () => void;
+    reset: () => void;
+}
+/**
+ * Hook central du SDK.
+ * Gère la boucle de scan automatique :
+ *   captureFrame → sendToApi → onSuccess | retry | onError
+ *
+ * Utilisé à la fois par MrzScannerNative et MrzScannerWeb,
+ * la seule différence étant captureFrame et sendToApi.
+ */
+export declare function useScanner({ api, maxAttempts, scanIntervalMs, onSuccess, onError, captureFrame, sendToApi, }: UseScannerOptions): ScannerControls;
+export {};

package/dist/types/web/MrzScannerWeb.d.ts

@@ -0,0 +1,27 @@
+import { type ReactElement } from 'react';
+import type { MrzScannerWebProps } from '../shared/types';
+/**
+ * MrzScannerWeb
+ *
+ * Composant React web de scan MRZ automatique via getUserMedia.
+ * Compatible Next.js (App Router) avec 'use client', Vite, CRA, etc.
+ *
+ * Next.js : importer avec dynamic() + { ssr: false }
+ * ```ts
+ * const MrzScannerWeb = dynamic(
+ *   () => import('@scanid/mrz-scanner').then(m => m.MrzScannerWeb),
+ *   { ssr: false }
+ * )
+ * ```
+ *
+ * Usage standard :
+ * ```tsx
+ * <MrzScannerWeb
+ *   api={{ mode: 'cloud', apiKey: 'sk_...', region: 'west-africa' }}
+ *   onSuccess={(r) => console.log(r.fields)}
+ *   width="100%"
+ *   height="480px"
+ * />
+ * ```
+ */
+export declare function MrzScannerWeb({ api, onSuccess, onError, onClose, maxAttempts, scanIntervalMs, width, height, className, }: MrzScannerWebProps): ReactElement;

package/dist/web/MrzScannerWeb.js

@@ -0,0 +1,259 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState, } from 'react';
+import { useScanner } from '../shared/useScanner';
+import { sendImageToApi } from '../shared/api-client';
+// ─── Label d'état ─────────────────────────────────────────────────────────────
+function getLabel(state, attempts, max) {
+    switch (state) {
+        case 'idle': return 'Initialisation caméra…';
+        case 'scanning': return 'Placez le document dans le cadre — zone MRZ en bas';
+        case 'analyzing': return 'Analyse en cours…';
+        case 'success': return '✓ Document reconnu !';
+        case 'failed': return `Échec après ${attempts}/${max} tentatives`;
+    }
+}
+// ─── Composant ────────────────────────────────────────────────────────────────
+/**
+ * MrzScannerWeb
+ *
+ * Composant React web de scan MRZ automatique via getUserMedia.
+ * Compatible Next.js (App Router) avec 'use client', Vite, CRA, etc.
+ *
+ * Next.js : importer avec dynamic() + { ssr: false }
+ * ```ts
+ * const MrzScannerWeb = dynamic(
+ *   () => import('@scanid/mrz-scanner').then(m => m.MrzScannerWeb),
+ *   { ssr: false }
+ * )
+ * ```
+ *
+ * Usage standard :
+ * ```tsx
+ * <MrzScannerWeb
+ *   api={{ mode: 'cloud', apiKey: 'sk_...', region: 'west-africa' }}
+ *   onSuccess={(r) => console.log(r.fields)}
+ *   width="100%"
+ *   height="480px"
+ * />
+ * ```
+ */
+export function MrzScannerWeb({ api, onSuccess, onError, onClose, maxAttempts = 10, scanIntervalMs = 1500, width = '100%', height = '480px', className, }) {
+    const videoRef = useRef(null);
+    const canvasRef = useRef(null);
+    const streamRef = useRef(null);
+    const [camReady, setCamReady] = useState(false);
+    const [camError, setCamError] = useState(null);
+    // Démarrage de la caméra
+    useEffect(() => {
+        let active = true;
+        async function initCamera() {
+            try {
+                const stream = await navigator.mediaDevices.getUserMedia({
+                    video: {
+                        facingMode: { ideal: 'environment' }, // caméra arrière si dispo
+                        width: { ideal: 1920 },
+                        height: { ideal: 1080 },
+                    },
+                });
+                if (!active) {
+                    stream.getTracks().forEach(t => t.stop());
+                    return;
+                }
+                streamRef.current = stream;
+                if (videoRef.current) {
+                    videoRef.current.srcObject = stream;
+                    videoRef.current.onloadedmetadata = () => {
+                        var _a;
+                        (_a = videoRef.current) === null || _a === void 0 ? void 0 : _a.play();
+                        if (active)
+                            setCamReady(true);
+                    };
+                }
+            }
+            catch (err) {
+                if (active) {
+                    setCamError("Impossible d'accéder à la caméra. Vérifiez les permissions.");
+                    console.error('[MrzScannerWeb] Camera error:', err);
+                }
+            }
+        }
+        initCamera();
+        return () => {
+            var _a;
+            active = false;
+            (_a = streamRef.current) === null || _a === void 0 ? void 0 : _a.getTracks().forEach(t => t.stop());
+        };
+    }, []);
+    /**
+     * Capture une frame depuis le flux vidéo.
+     * Recadrage automatique sur les 38% bas (zone MRZ).
+     * Retourne un Blob JPEG prêt à envoyer à l'API.
+     */
+    const captureFrame = useCallback(async () => {
+        const video = videoRef.current;
+        const canvas = canvasRef.current;
+        if (!video || !canvas || !camReady)
+            return null;
+        const vw = video.videoWidth;
+        const vh = video.videoHeight;
+        if (!vw || !vh)
+            return null;
+        // Recadrage sur les 38% bas
+        const cropY = Math.floor(vh * 0.62);
+        const cropH = Math.floor(vh * 0.38);
+        canvas.width = vw;
+        canvas.height = cropH;
+        const ctx = canvas.getContext('2d');
+        if (!ctx)
+            return null;
+        ctx.drawImage(video, 0, cropY, vw, cropH, 0, 0, vw, cropH);
+        return new Promise((resolve) => {
+            canvas.toBlob(resolve, 'image/jpeg', 0.85);
+        });
+    }, [camReady]);
+    const handleSuccess = useCallback((result) => {
+        onSuccess(result);
+    }, [onSuccess]);
+    const { scanState, attempts, start, reset } = useScanner({
+        api,
+        maxAttempts,
+        scanIntervalMs,
+        onSuccess: handleSuccess,
+        onError,
+        captureFrame: async () => {
+            const blob = await captureFrame();
+            return blob; // useScanner accepte Blob directement
+        },
+        sendToApi: async (cfg, payload) => sendImageToApi(cfg, payload),
+    });
+    // Démarrer dès que la caméra est prête
+    useEffect(() => {
+        if (camReady)
+            start();
+    }, [camReady]);
+    // ─── Erreur caméra ──────────────────────────────────────────────────────────
+    if (camError) {
+        return (_jsx("div", { style: Object.assign(Object.assign({}, containerStyle), { width, height }), className: className, children: _jsxs("div", { style: errorStyle, children: [_jsx("p", { style: { color: '#fff', marginBottom: 16 }, children: camError }), onClose && (_jsx("button", { style: btnStyle, onClick: onClose, children: "Fermer" }))] }) }));
+    }
+    // ─── Frame principal ────────────────────────────────────────────────────────
+    const isSuccess = scanState === 'success';
+    const isFailed = scanState === 'failed';
+    return (_jsxs("div", { style: Object.assign(Object.assign({}, containerStyle), { width, height }), className: className, children: [_jsx("video", { ref: videoRef, muted: true, playsInline: true, style: videoStyle }), _jsx("canvas", { ref: canvasRef, style: { display: 'none' } }), _jsxs("div", { style: overlayStyle, children: [_jsx("div", { style: Object.assign(Object.assign({}, maskStyle), { flex: 3 }) }), _jsxs("div", { style: { display: 'flex', height: 90 }, children: [_jsx("div", { style: Object.assign(Object.assign({}, maskStyle), { flex: 1 }) }), _jsxs("div", { style: Object.assign(Object.assign({}, frameStyle), { borderColor: isSuccess ? '#34d399' : 'rgba(255,255,255,0.9)', boxShadow: isSuccess
+                                        ? '0 0 0 2px #34d399, 0 0 20px rgba(52,211,153,0.3)'
+                                        : camReady
+                                            ? '0 0 0 1px rgba(255,255,255,0.2)'
+                                            : 'none', transition: 'border-color 0.3s, box-shadow 0.3s', animation: scanState === 'scanning' ? 'pulse 1.4s ease-in-out infinite' : 'none' }), children: [_jsx("div", { style: Object.assign(Object.assign({}, cornerStyle), { top: 0, left: 0, borderRightWidth: 0, borderBottomWidth: 0 }) }), _jsx("div", { style: Object.assign(Object.assign({}, cornerStyle), { top: 0, right: 0, borderLeftWidth: 0, borderBottomWidth: 0 }) }), _jsx("div", { style: Object.assign(Object.assign({}, cornerStyle), { bottom: 0, left: 0, borderRightWidth: 0, borderTopWidth: 0 }) }), _jsx("div", { style: Object.assign(Object.assign({}, cornerStyle), { bottom: 0, right: 0, borderLeftWidth: 0, borderTopWidth: 0 }) }), scanState === 'analyzing' && (_jsx("div", { style: spinnerStyle })), isSuccess && (_jsx("span", { style: { color: '#34d399', fontSize: 28, fontWeight: 700 }, children: "\u2713" }))] }), _jsx("div", { style: Object.assign(Object.assign({}, maskStyle), { flex: 1 }) })] }), _jsx("div", { style: Object.assign(Object.assign({}, maskStyle), { flex: 2 }) })] }), _jsxs("div", { style: statusBarStyle, children: [_jsx("span", { style: statusTextStyle, children: getLabel(scanState, attempts, maxAttempts) }), isFailed && (_jsx("button", { style: Object.assign(Object.assign({}, btnStyle), { marginTop: 12 }), onClick: () => { reset(); setTimeout(start, 100); }, children: "R\u00E9essayer" }))] }), onClose && (_jsx("button", { style: closeBtnStyle, onClick: onClose, "aria-label": "Fermer le scanner", children: "\u2715" })), _jsx("style", { children: `
+        @keyframes pulse {
+          0%, 100% { transform: scale(1);     opacity: 1;    }
+          50%       { transform: scale(1.015); opacity: 0.85; }
+        }
+        @keyframes spin {
+          to { transform: rotate(360deg); }
+        }
+      ` })] }));
+}
+// ─── Styles inline ────────────────────────────────────────────────────────────
+const containerStyle = {
+    position: 'relative',
+    overflow: 'hidden',
+    background: '#000',
+    borderRadius: 12,
+};
+const videoStyle = {
+    position: 'absolute',
+    inset: 0,
+    width: '100%',
+    height: '100%',
+    objectFit: 'cover',
+};
+const overlayStyle = {
+    position: 'absolute',
+    inset: 0,
+    display: 'flex',
+    flexDirection: 'column',
+    pointerEvents: 'none',
+};
+const maskStyle = {
+    background: 'rgba(0,0,0,0.55)',
+};
+const frameStyle = {
+    flex: 5,
+    border: '2px solid rgba(255,255,255,0.9)',
+    borderRadius: 6,
+    position: 'relative',
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+};
+const cornerStyle = {
+    position: 'absolute',
+    width: 16,
+    height: 16,
+    borderStyle: 'solid',
+    borderColor: '#fff',
+    borderWidth: 2,
+};
+const spinnerStyle = {
+    position: 'absolute',
+    top: 8,
+    right: 8,
+    width: 16,
+    height: 16,
+    border: '2px solid rgba(255,255,255,0.3)',
+    borderTopColor: '#fff',
+    borderRadius: '50%',
+    animation: 'spin 0.8s linear infinite',
+};
+const statusBarStyle = {
+    position: 'absolute',
+    bottom: 40,
+    left: 0,
+    right: 0,
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'center',
+    padding: '0 24px',
+    pointerEvents: 'none',
+};
+const statusTextStyle = {
+    color: '#fff',
+    fontSize: 13,
+    textAlign: 'center',
+    textShadow: '0 1px 4px rgba(0,0,0,0.8)',
+};
+const closeBtnStyle = {
+    position: 'absolute',
+    top: 16,
+    right: 16,
+    background: 'rgba(0,0,0,0.4)',
+    border: 'none',
+    color: '#fff',
+    fontSize: 18,
+    width: 36,
+    height: 36,
+    borderRadius: '50%',
+    cursor: 'pointer',
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+};
+const btnStyle = {
+    background: '#c8ff00',
+    color: '#000',
+    border: 'none',
+    borderRadius: 8,
+    padding: '10px 24px',
+    fontWeight: 700,
+    fontSize: 14,
+    cursor: 'pointer',
+    pointerEvents: 'auto',
+};
+const errorStyle = {
+    position: 'absolute',
+    inset: 0,
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: 24,
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@scanid-africa/mrz-scanner",
+  "version": "1.0.0",
+  "description": "MRZ scanner for React Native (Expo) and React web — powered by ScanID Africa API",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/types/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mrz",
+    "ocr",
+    "passport",
+    "scanner",
+    "react-native",
+    "expo",
+    "africa"
+  ],
+  "author": "ScanID Africa",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MJdiop/mrz-scanner-sdk"
+  },
+  "peerDependencies": {
+    "expo-camera": ">=14.0.0",
+    "expo-image-manipulator": ">=11.0.0",
+    "expo-haptics": ">=12.0.0",
+    "react": ">=18.0.0",
+    "react-native": ">=0.73.0"
+  },
+  "peerDependenciesMeta": {
+    "expo-haptics": {
+      "optional": true
+    },
+    "react-native": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.1",
+    "typescript": "^5.0.0"
+  }
+}