@neofaceid/web-sdk 2.1.1 → 2.1.3

package/README.md

@@ -47,14 +47,15 @@ vai consumi-lo:
 1. **HTTPS.** O SDK acessa a câmera via `getUserMedia`, que exige contexto
    seguro. `localhost` funciona em desenvolvimento; produção precisa de
    HTTPS (recomendado configurar HSTS no servidor).
-2. **`face-api.js` já vem como dependência transitiva** do
-   `@neofaceid/web-sdk` (não precisa instalar de novo) — mas os **pesos do
+2. **O detector facial (`@vladmandic/face-api`, fork mantido do
+   `face-api.js`) já vem embutido** no `@neofaceid/web-sdk`, rodando sobre o
+   TF.js 4.x que o SDK instala como dependência (não precisa instalar nada) — mas os **pesos do
    modelo (weights) não são publicados no bundle** e precisam ser
    auto-hospedados pelo consumer. O SDK carrega os modelos em runtime via
    `faceapi.nets.<rede>.loadFromUri('/models')`, ou seja, relativos à própria
    origem do seu app. Baixe os arquivos abaixo do repositório oficial de
-   pesos do face-api.js e sirva-os em `public/models/` (ou equivalente do seu
-   bundler) para que fiquem acessíveis em `/models/*`:
+   pesos do face-api.js (o fork usa os mesmos arquivos) e sirva-os em
+   `public/models/` (ou equivalente do seu bundler) para que fiquem acessíveis em `/models/*`:
    - `tiny_face_detector_model-weights_manifest.json` +
      `tiny_face_detector_model-shard1`
    - `face_landmark_68_model-weights_manifest.json` +
@@ -62,7 +63,19 @@ vai consumi-lo:
 
    Sem esses arquivos em `/models`, qualquer fluxo que dependa de detecção
    facial local (blink detection do liveness, `biometricDetection`) falha ao
-   carregar o modelo.
+   carregar o modelo. Se o manifest não for encontrado (404), o console
+   mostra um `console.error` acionável, com os 4 arquivos e o destino:
+
+   ```
+   [NeoFace ID SDK] Modelos de detecção facial não encontrados em /models/.
+   Copie os 4 arquivos abaixo para public/models/ (ou equivalente do seu bundler):
+     - tiny_face_detector_model-weights_manifest.json
+     - tiny_face_detector_model-shard1
+     - face_landmark_68_model-weights_manifest.json
+     - face_landmark_68_model-shard1
+   Fonte: https://github.com/vladmandic/face-api/tree/master/model
+   Sem esses arquivos em /models, o fluxo de detecção facial falhará silenciosamente.
+   ```
 3. **Ícone/logo do SDK não precisa de asset externo.** Desde a 1.29.0 a marca
    é renderizada via SVG inline (`src/assets/brand.ts`) — não há mais PNG
    para hospedar.
@@ -157,6 +170,7 @@ await startFaceLogin({
   appName: 'Minha Aplicação',
   onSuccess: result => console.log('Login ok:', result),
   onError: err => console.error(err.type, err.getFriendlyMessage()),
+  onAttemptError: (err, attempt) => analytics.track('biometric_attempt_failed', { attempt, type: err.type }),
   onCancel: () => console.log('Usuário cancelou'),
   onFallbackRequest: () => {
     /* opcional — default já abre EmailPasswordModal */
@@ -164,6 +178,15 @@ await startFaceLogin({
 });
 ```
 
+> `onError` × `onAttemptError` (`BiometricLoginOptions`, NEO-563): `onError` é
+> chamado quando o fluxo guiado **termina** — usuário cancelou, escolheu
+> email/senha, ou erro fora do loop de tentativas (ex.: `CONSENT_DENIED`
+> antes da câmera abrir). Já `onAttemptError` (opcional) é chamado a cada
+> tentativa individual que falha **dentro** do loop (401, 429, rosto não
+> detectado, etc.), antes de o `FallbackPrompt` interno aparecer — útil para
+> registrar cada falha no seu próprio sistema de monitoramento sem esperar o
+> fluxo encerrar.
+
 ### Login por mão / automático (`startHandLogin`, `startAutoLogin`)
 
 Mesma assinatura de `startFaceLogin` (`BiometricLoginOptions`); `startAutoLogin`

package/dist/{biometricDetection-8utmtR25.js → biometricDetection-CR31mETT.js}

@@ -149,6 +149,20 @@ async function loadFaceApiModels() {
     console.warn("Não foi possível carregar modelos do face-api.js:", error);
   }
 }
+async function initializeBiometricDetection() {
+  try {
+    if (typeof window !== "undefined") {
+      await loadFaceApiModels();
+    }
+  } catch (error) {
+    console.warn("Inicialização da detecção biométrica com limitações:", error);
+  }
+}
+function isAdvancedDetectionAvailable() {
+  return typeof window !== "undefined" && window.faceapi && window.faceapi.nets.tinyFaceDetector.isLoaded;
+}
 export {
-  detectBiometricType
+  detectBiometricType,
+  initializeBiometricDetection,
+  isAdvancedDetectionAvailable
 };

package/dist/index.d.ts

@@ -63,7 +63,7 @@ export declare interface AuthorizationResult {
 }
 
 /**
- * NeoFaceSDK.authorize — autoriza uma operação por biometria, orquestrando
+ * authorize — autoriza uma operação por biometria, orquestrando
  * consent + captura + desafio de vivacidade (via runLivenessChallenge, NEO-408).
  *
  * O servidor sorteia a sequência de gestos, valida cada frame enviado e decide
@@ -199,7 +199,37 @@ export declare interface BiometricLoginOptions {
      */
     appName?: string;
     onSuccess: (result: BiometricLoginResult) => void;
+    /**
+     * Chamado quando o fluxo guiado **termina** — ou seja, quando o usuário
+     * cancela, escolhe entrar por email/senha, ou ocorre um erro fora do loop
+     * de tentativas (ex.: `CONSENT_DENIED` antes da câmera abrir).
+     *
+     * Nas falhas de reconhecimento que acontecem **dentro** do loop de
+     * tentativas (401, 429, rosto não detectado, etc.), o SDK exibe o
+     * `FallbackPrompt` internamente antes de propagar ao host. Use
+     * `onAttemptError` para ser notificado dessas falhas individuais.
+     */
     onError: (error: NeoFaceError) => void;
+    /**
+     * NEO-563 — Chamado a cada tentativa de login que falha, **antes** de o
+     * `FallbackPrompt` aparecer. Permite ao integrador registrar falhas
+     * individuais no próprio sistema de monitoramento.
+     *
+     * @param error  O erro da tentativa que falhou.
+     * @param attempt Número da tentativa (começa em 1).
+     *
+     * @example
+     * ```ts
+     * startFaceLogin({
+     *   applicationToken,
+     *   onSuccess: r => console.log('ok', r),
+     *   onError: err => console.error('fluxo encerrado', err),
+     *   onAttemptError: (err, attempt) =>
+     *     analytics.track('biometric_attempt_failed', { attempt, type: err.type }),
+     * });
+     * ```
+     */
+    onAttemptError?: (error: NeoFaceError, attempt: number) => void;
     onCancel?: () => void;
     onFallbackRequest?: () => void;
     countdown?: number;
@@ -981,6 +1011,11 @@ export declare const loginWithEmail: (email: string, password: string, applicati
  */
 export declare class NeoFaceError extends Error {
     type: ErrorType;
+    /**
+     * NEO-562 · Presente quando o erro veio de um HTTP 429 (rate limit) — tempo
+     * em ms sugerido pelo `Retry-After` da API antes de uma nova tentativa.
+     */
+    retryAfterMs?: number;
     /**
      * Constrói um erro do SDK com mensagem e tipo categórico.
      * @param message Mensagem descritiva do erro (pode ser técnica)
@@ -1058,7 +1093,13 @@ export declare interface PersonalDataItem {
 }
 
 /**
- * Pré-carrega modelos do face-api.js (chame no início da aplicação)
+ * Pré-carrega modelos de detecção facial (chame no início da aplicação para
+ * evitar o delay do primeiro `loadFromUri` durante a interação do usuário).
+ *
+ * Os modelos não são publicados no bundle do SDK — precisam ser auto-hospedados
+ * pelo consumer em `/models/` (relativo à origem do app). Se os arquivos não
+ * forem encontrados, um `console.error` acionável é emitido indicando o que
+ * copiar e para onde.
  */
 export declare function preloadFaceDetectionModels(): Promise<void>;
 
@@ -1866,7 +1907,7 @@ export declare const validateToken: (applicationToken: string) => Promise<boolea
  * MINOR: Incrementado quando adicionamos funcionalidades mantendo compatibilidade
  * PATCH: Incrementado quando corrigimos bugs mantendo compatibilidade
  */
-export declare const VERSION = "2.1.1";
+export declare const VERSION = "2.1.3";
 
 /**
  * Executa `fn(sessionId)`. Se o servidor devolver 410 (sessão consumida/expirada),