@neofaceid/web-sdk 2.1.2 → 2.1.3

package/README.md

@@ -63,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.
@@ -158,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 */
@@ -165,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/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.2";
+export declare const VERSION = "2.1.3";
 
 /**
  * Executa `fn(sessionId)`. Se o servidor devolver 410 (sessão consumida/expirada),

package/dist/neoface-id-sdk.es.js

@@ -2614,6 +2614,11 @@ class NeoFaceError extends Error {
   constructor(message, type) {
     super(message);
     __publicField(this, "type");
+    /**
+     * 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.
+     */
+    __publicField(this, "retryAfterMs");
     this.name = type;
     this.type = type;
   }
@@ -2645,6 +2650,7 @@ class NeoFaceError extends Error {
       case "GestureNotDetectedError":
         return "Não detectamos o polegar para cima. Mostre o gesto claramente para a câmera e tente novamente.";
       case "ApiError":
+        if (this.retryAfterMs !== void 0) return this.message;
         if (this.message.includes("400")) return "Requisição inválida. Tente novamente.";
         if (this.message.includes("500"))
           return "Ocorreu um erro interno no sistema. Tente mais tarde.";
@@ -7595,6 +7601,28 @@ const loginWithBiometric = async (image, applicationToken) => {
       if (response.status === 401 || response.status === 403) {
         throw new NeoFaceError("Invalid application token", ErrorType.INVALID_TOKEN);
       }
+      if (response.status === 429) {
+        const raw = response.headers.get("Retry-After");
+        let retryAfterMs = 6e4;
+        if (raw) {
+          const seconds = Number(raw);
+          if (Number.isFinite(seconds) && seconds > 0) {
+            retryAfterMs = seconds * 1e3;
+          } else {
+            const date2 = Date.parse(raw);
+            if (Number.isFinite(date2)) {
+              const delta = date2 - Date.now();
+              if (delta > 0) retryAfterMs = delta;
+            }
+          }
+        }
+        const err = new NeoFaceError(
+          `Muitas tentativas. Aguarde ${Math.ceil(retryAfterMs / 1e3)} segundo(s) antes de tentar novamente.`,
+          ErrorType.API_ERROR
+        );
+        err.retryAfterMs = retryAfterMs;
+        throw err;
+      }
       if (response.status >= 500) {
         throw new NeoFaceError(`Server Error ${response.status}`, ErrorType.API_ERROR);
       }
@@ -11483,7 +11511,7 @@ function BiometricRegistrationModal({
     /* @__PURE__ */ jsx("canvas", { ref: canvasRef })
   ] });
 }
-const VERSION = "2.1.2";
+const VERSION = "2.1.3";
 const RELEASE_DATE = "2026-09-23";
 const CONSENT_TRAIL_STORAGE_KEY = "neoface_consent_trail_v1";
 const CONSENT_TRAIL_MAX_LIMIT = 100;
@@ -11919,7 +11947,7 @@ function requestConsent(info = {}) {
   const appName = info.appName ?? globalAppName ?? DEFAULT_APP_NAME;
   if (!info.appName && !globalAppName) {
     console.warn(
-      '[NeoFaceID SDK] requestConsent sem appName — usando fallback "sua aplicação". Passe via NeoFaceSDK.init({ appName }) ou opts do caller.'
+      '[NeoFaceID SDK] requestConsent sem appName — usando fallback "sua aplicação". Passe via init({ appName }) ou opts do caller.'
     );
   }
   const flow = info.flow ?? "verification";
@@ -13544,6 +13572,7 @@ class BiometricStatusOverlay {
     }
   }
 }
+const MIN_RETRY_COOLDOWN_MS = 3e3;
 function FallbackPromptComponent({
   error,
   onRetry,
@@ -13551,10 +13580,48 @@ function FallbackPromptComponent({
   onCancel,
   applicationToken
 }) {
+  const [cooldownSec, setCooldownSec] = useState(0);
+  const [retrying, setRetrying] = useState(false);
+  const cooldownIntervalRef = useRef(null);
+  const stopCooldown = useCallback(() => {
+    if (cooldownIntervalRef.current) {
+      clearInterval(cooldownIntervalRef.current);
+      cooldownIntervalRef.current = null;
+    }
+  }, []);
+  useEffect(() => stopCooldown, [stopCooldown]);
+  const handleRetry = useCallback(() => {
+    if (retrying) return;
+    setRetrying(true);
+    const waitMs = Math.max(
+      (error == null ? void 0 : error.retryAfterMs) ?? 0,
+      MIN_RETRY_COOLDOWN_MS
+    );
+    const totalSec = Math.ceil(waitMs / 1e3);
+    setCooldownSec(totalSec);
+    let remaining = totalSec;
+    cooldownIntervalRef.current = setInterval(() => {
+      remaining -= 1;
+      setCooldownSec(remaining);
+      if (remaining <= 0) {
+        stopCooldown();
+        setRetrying(false);
+        onRetry();
+      }
+    }, 1e3);
+  }, [retrying, error, onRetry, stopCooldown]);
   const handleForgotPassword = () => {
     const modal = new ForgotPasswordModal(applicationToken);
     modal.open();
   };
+  const handleCredentials = useCallback(() => {
+    stopCooldown();
+    onCredentials();
+  }, [stopCooldown, onCredentials]);
+  const handleCancel = useCallback(() => {
+    stopCooldown();
+    onCancel == null ? void 0 : onCancel();
+  }, [stopCooldown, onCancel]);
   return /* @__PURE__ */ jsxs(Fragment, { children: [
     /* @__PURE__ */ jsx("style", { children: `
         @keyframes slideUp {
@@ -13650,6 +13717,10 @@ function FallbackPromptComponent({
           outline: 2px solid var(--nfid-focus-ring);
           outline-offset: 2px;
         }
+        .neofaceid-fallback-button-primary:disabled {
+          opacity: 0.55;
+          cursor: not-allowed;
+        }
 
         .neofaceid-fallback-button-secondary {
           background: var(--nfid-surface-muted);
@@ -13709,8 +13780,10 @@ function FallbackPromptComponent({
           {
             type: "button",
             className: "neofaceid-fallback-button neofaceid-fallback-button-primary",
-            onClick: onRetry,
-            children: "Tentar Novamente"
+            onClick: handleRetry,
+            disabled: retrying,
+            "aria-disabled": retrying,
+            children: retrying ? `Aguarde ${cooldownSec}s...` : "Tentar Novamente"
           }
         ),
         /* @__PURE__ */ jsx(
@@ -13718,7 +13791,7 @@ function FallbackPromptComponent({
           {
             type: "button",
             className: "neofaceid-fallback-button neofaceid-fallback-button-secondary",
-            onClick: onCredentials,
+            onClick: handleCredentials,
             children: "Entrar com Email e Senha"
           }
         ),
@@ -13736,7 +13809,7 @@ function FallbackPromptComponent({
           {
             type: "button",
             className: "neofaceid-fallback-button neofaceid-fallback-button-ghost",
-            onClick: onCancel,
+            onClick: handleCancel,
             children: "Cancelar"
           }
         )
@@ -14120,7 +14193,10 @@ async function preloadFaceDetectionModels() {
       modelsLoaded = true;
       console.log("✅ Face detection models preloaded");
     } catch (error) {
-      console.warn("⚠️ Face-api.js models not loaded:", error);
+      console.error(
+        "[NeoFace ID SDK] Modelos de detecção facial não encontrados em /models/.\nCopie os 4 arquivos abaixo para public/models/ (ou equivalente do seu bundler):\n  - tiny_face_detector_model-weights_manifest.json\n  - tiny_face_detector_model-shard1\n  - face_landmark_68_model-weights_manifest.json\n  - face_landmark_68_model-shard1\nFonte: https://github.com/vladmandic/face-api/tree/master/model\nSem esses arquivos em /models, o fluxo de detecção facial falhará silenciosamente.",
+        error
+      );
     }
   })();
   return modelsLoading;
@@ -14487,6 +14563,7 @@ async function executeBiometricLoginFlow(options) {
     applicationToken,
     onSuccess,
     onError,
+    onAttemptError,
     onFallbackRequest,
     onCancel,
     fastMode = false
@@ -14508,6 +14585,9 @@ async function executeBiometricLoginFlow(options) {
         error instanceof Error ? error.message : "Erro desconhecido",
         ErrorType.UNKNOWN
       );
+      if (onAttemptError) {
+        onAttemptError(lastError, attempts);
+      }
       if (attempts < MAX_ATTEMPTS$1) {
         setTimeout(() => {
           tryLogin();
@@ -15179,6 +15259,7 @@ async function startFaceLogin(options) {
       applicationToken: options.applicationToken,
       onSuccess: options.onSuccess,
       onError: options.onError,
+      onAttemptError: options.onAttemptError,
       onFallbackRequest: options.onFallbackRequest || (() => openPasswordFallback(options)),
       onCancel: options.onCancel
     });