@neofaceid/web-sdk 1.40.3 → 1.42.0

package/README.md

@@ -192,7 +192,7 @@ startBiometricRegistration(
   'seu-token-de-aplicacao',
   {
     onSuccess: result => console.log('Cadastro concluído:', result.person_id),
-    onError: (code, message) => console.error(code, message),
+    onError: err => console.error(err.type, err.message),
   },
   { appName: 'Minha Aplicação' }
 );
@@ -210,7 +210,7 @@ startLivenessCapture(
   'seu-token-de-aplicacao',
   {
     onSuccess: (photos: Blob[]) => console.log(`${photos.length} fotos capturadas`),
-    onError: (code, message) => console.error(code, message),
+    onError: err => console.error(err.type, err.message),
     onCancel: () => console.log('Usuário fechou o modal'),
   },
   { appName: 'Minha Aplicação' }
@@ -347,14 +347,14 @@ function onError(err: NeoFaceError) {
 }
 ```
 
-> Os fluxos legados `start`, `startBiometricRegistration` e
-> `startLivenessCapture` ainda usam `onError(code: string, message: string)`
-> em vez de `onError(err: NeoFaceError)` — consulte o `CHANGELOG.md` antes de
-> migrar código que dependa dessa assinatura.
+> Desde a 1.41.0, `start`, `startBiometricRegistration` e
+> `startLivenessCapture` também usam `onError(err: NeoFaceError)` — antes
+> usavam `onError(code: string, message: string)`. Veja o `CHANGELOG.md`
+> (breaking change) se seu código ainda depende da assinatura antiga.
 
 | `ErrorType`             | Quando ocorre                                                  |
 | ----------------------- | --------------------------------------------------------------- |
-| `NETWORK`               | Erro de conexão com o servidor (alias `@deprecated`: `NETWORK_ERROR`) |
+| `NETWORK`               | Erro de conexão com o servidor                                  |
 | `INVALID_TOKEN`         | `applicationToken` inválido ou expirado                         |
 | `RECOGNITION_FAILED`    | Falha no reconhecimento facial                                  |
 | `LOGIN_FAILED`          | Falha no login biométrico                                       |

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { default as default_2 } from 'react';
 import { JSX as JSX_2 } from 'react/jsx-runtime';
 import { z } from 'zod';
 
@@ -29,6 +30,20 @@ export declare interface ApplicationRegistrationResult {
     message: string;
 }
 
+export declare type AuthMethod = z.infer<typeof AuthMethodSchema>;
+
+/**
+ * Por qual caminho a pessoa se autenticou.
+ *
+ * O console trata `password` como caminho degradado — entra, mas não executa
+ * operação de risco alto. Sem este campo o host não tem como distinguir, já que
+ * o resultado dos dois caminhos tem exatamente a mesma forma.
+ */
+declare const AuthMethodSchema: z.ZodEnum<{
+    face: "face";
+    password: "password";
+}>;
+
 export declare interface AuthorizationOptions {
     onProgress?: (step: number, totalSteps: number, instruction: string) => void;
     onPhotoTaken?: (photoNumber: number, blob: Blob) => void;
@@ -106,6 +121,76 @@ export declare interface AuthorizeOptions {
     autoLighting?: boolean;
 }
 
+/** Ver {@link SDKInitOptions.autoFallback}. */
+export declare interface AutoFallbackOptions {
+    /**
+     * Nível 1 — oferecer confirmação no celular quando o dispositivo atual não
+     * dá conta (sem câmera, permissão negada) ou quando o purpose exige.
+     *
+     * Default `false`. Quem decide se há aparelho é o core, na resposta: o SDK
+     * não consegue (e não deve) descobrir isso sozinho — um endpoint que
+     * respondesse "esta pessoa tem aparelho?" autenticado por `X-App-Token`,
+     * que é público por desenho, seria um oráculo de enumeração.
+     */
+    toPhone?: boolean;
+    /**
+     * Nível 2 — abrir o modal de e-mail e senha.
+     *
+     * Default `true`, que é o comportamento histórico de `startFaceLogin`
+     * quando `onFallbackRequest` não é passado. Mudá-lo para `false` por padrão
+     * quebraria todo integrador publicado, então a mudança fica explícita.
+     */
+    toPassword?: boolean;
+}
+
+/**
+ * Abre a tela "Confirme no seu celular" e aguarda a decisão pelo SSE do core.
+ *
+ * Este primitivo é avulso de propósito. Desde a NEO-427 o `authorize()` só
+ * **coleta** — quem submete ao core é o host, então é o host que recebe a
+ * resposta "exige confirmação no celular" e chama esta função com o
+ * `requestId` que veio de lá.
+ *
+ * O SDK nunca fala com a plataforma Push: o canal é sempre o core.
+ *
+ * @example
+ * ```ts
+ * const r = await meuBackend.submeter(frames);
+ * if (r.requires_push) {
+ *   const outcome = await awaitPushApproval({
+ *     requestId: r.request_id,
+ *     applicationToken: TOKEN,
+ *     expiresIn: r.expires_in,
+ *     numericCode: r.numeric_code,
+ *   });
+ *   if (outcome.status === 'approved') continuar();
+ *   else if (outcome.status === 'expired') caiParaSenha();
+ *   // 'denied' é terminal — não oferece caminho alternativo.
+ * }
+ * ```
+ */
+export declare function awaitPushApproval(options: AwaitPushApprovalOptions): Promise<PushApprovalOutcome>;
+
+export declare interface AwaitPushApprovalOptions {
+    /**
+     * Identificador da solicitação, devolvido pelo core na resposta que exigiu
+     * confirmação no celular.
+     */
+    requestId: string;
+    applicationToken: string;
+    /** Prazo informado pelo core, em segundos. */
+    expiresIn: number;
+    /**
+     * Código de correspondência numérica de 2 dígitos, quando a política exigir.
+     * O SDK apenas **exibe**; conferir é papel do celular contra o servidor.
+     */
+    numericCode?: string;
+    /** Nome do integrador (fallback: `init({ appName })`). */
+    appName?: string;
+    /** Oferece "entrar de outro jeito" na tela de expiração. */
+    onFallback?: () => void;
+}
+
 export declare class BiometricCaptureModal {
     private modal;
     private video;
@@ -201,6 +286,11 @@ export declare type BiometricLoginResult = z.infer<typeof BiometricLoginResultSc
 declare const BiometricLoginResultSchema: z.ZodObject<{
     success: z.ZodBoolean;
     accessToken: z.ZodOptional<z.ZodString>;
+    refreshToken: z.ZodOptional<z.ZodString>;
+    method: z.ZodOptional<z.ZodEnum<{
+        face: "face";
+        password: "password";
+    }>>;
     alias: z.ZodOptional<z.ZodString>;
     user: z.ZodOptional<z.ZodObject<{
         id: z.ZodString;
@@ -223,7 +313,7 @@ declare const BiometricLoginResultSchema: z.ZodObject<{
 
 declare interface BiometricRegistrationCallbacks {
     onSuccess(result: BiometricRegistrationResult): void;
-    onError(code: string, message: string): void;
+    onError(err: NeoFaceError): void;
 }
 
 export declare function BiometricRegistrationModal({ personData, applicationToken, onClose, onSuccess, onPhotosCaptured, onError, onCannotGesture, autoLighting, }: BiometricRegistrationModalProps): JSX_2.Element;
@@ -279,6 +369,7 @@ declare interface BiometricRegistrationResult_2 {
 /**
  * Overlay minimalista estilo FaceID para login biométrico
  * Implementação vanilla JS (sem React) para evitar conflitos de versão
+ * @deprecated Utilize o componente CameraOvalGuide (showCameraOvalGuideModal) para preview de câmera com guia oval.
  */
 export declare class BiometricStatusOverlay {
     private container;
@@ -297,7 +388,40 @@ declare interface Callbacks {
         email: string;
         documentId: string;
     }): void;
-    onError(code: string, message: string): void;
+    onError(err: NeoFaceError): void;
+}
+
+/**
+ * Componente de guia oval para captura facial.
+ *
+ * Renderiza o preview da câmera com um oval SVG sobreposto e um halo colorido
+ * que indica o estado de posicionamento do rosto em tempo real.
+ *
+ * @example
+ * ```tsx
+ * <CameraOvalGuide
+ *   stream={mediaStream}
+ *   faceState="centered"
+ *   instruction="Mantenha o rosto no oval"
+ * />
+ * ```
+ */
+export declare function CameraOvalGuide({ stream, faceState, instruction, className, style, }: CameraOvalGuideProps): JSX_2.Element;
+
+/**
+ * Props do componente CameraOvalGuide.
+ */
+export declare interface CameraOvalGuideProps {
+    /** Stream de vídeo da câmera. Null enquanto aguarda permissão. */
+    stream: MediaStream | null;
+    /** Estado de posicionamento do rosto — controla a cor do halo. */
+    faceState: FaceState;
+    /** Instrução textual exibida abaixo do oval (ex: "Aproxime o rosto"). */
+    instruction: string;
+    /** Classe CSS adicional aplicada ao container externo. */
+    className?: string;
+    /** Estilos inline adicionais aplicados ao container externo. */
+    style?: default_2.CSSProperties;
 }
 
 /**
@@ -461,6 +585,43 @@ export declare interface ConsentRecord {
     sdkVersion: string;
 }
 
+export declare interface ConsumeSseOptions<T> {
+    /**
+     * Pede um ticket ao core. Chamado na abertura **e a cada reconexão** — o
+     * ticket é de uso único e expira em 60 s (`core/sse_access.py`), então
+     * reconectar com o mesmo valor sempre falharia na autenticação.
+     */
+    requestTicket: () => Promise<string>;
+    /** Monta a URL do EventSource a partir de um ticket recém-emitido. */
+    buildUrl: (ticket: string) => string;
+    /** Decide, frame a frame, se o fluxo terminou. */
+    classify: (frame: SseFrame) => SseVerdict<T>;
+    /** Teto absoluto do fluxo. Default 310 s (o core faz timeout em 300 s). */
+    timeoutMs?: number;
+    /** Máximo de reconexões antes de desistir. Default 5. */
+    maxReconnects?: number;
+    /** Cancela o fluxo de fora (ex.: usuário fechou o modal). */
+    signal?: AbortSignal;
+    /** Injeção para teste. Default: `globalThis.EventSource`. */
+    eventSourceFactory?: (url: string) => EventSource;
+    /** Notifica cada frame não-terminal (ex.: atualizar UI). */
+    onProgress?: (frame: SseFrame) => void;
+}
+
+/**
+ * Consome um stream SSE do core até um veredito terminal.
+ *
+ * Diferenças em relação ao consumidor antigo (`loginWithBiometricSSE`, que era
+ * código morto e nunca funcionou):
+ *
+ * 1. escuta o evento default `message`, que é o que o core de fato emite;
+ * 2. reconecta pedindo **ticket novo**, em vez de rejeitar no primeiro soluço
+ *    de rede — o comentário em `api.ts` prometia isso e o código não fazia;
+ * 3. distingue o fechamento normal do servidor (que acontece logo após um
+ *    status terminal) de uma queda de conexão de verdade.
+ */
+export declare function consumeSseStream<T>(options: ConsumeSseOptions<T>): Promise<T>;
+
 /**
  * Compatibilidade com callers antigos que passavam `{ purpose, legalBasis }`.
  * Deprecated — remover quando US14.4 unificar tokens.
@@ -484,6 +645,15 @@ export declare interface DetectionResult {
     details?: any;
 }
 
+/** Token de inscrição de aparelho, devolvido por {@link requestDeviceEnrollmentToken}. */
+export declare interface DeviceEnrollmentToken {
+    /** JWT RS256 de uso único. Vira o conteúdo do QR. */
+    token: string;
+    /** Validade em segundos (o core emite 300). */
+    expiresIn: number;
+    purpose: string;
+}
+
 export declare class DocumentCaptureModal {
     private overlay;
     private video;
@@ -593,8 +763,6 @@ export declare const ENVIRONMENT_URLS: Record<Environment, string>;
  */
 export declare enum ErrorType {
     NETWORK = "NetworkError",
-    /** @deprecated Use `ErrorType.NETWORK`. Mantido para compatibilidade com consumidores existentes do SDK. */
-    NETWORK_ERROR = "NetworkError",
     INVALID_TOKEN = "InvalidTokenError",
     RECOGNITION_FAILED = "RecognitionFailedError",
     LOGIN_FAILED = "LoginFailedError",
@@ -629,6 +797,16 @@ declare interface FaceCaptureModalProps {
     autoLighting?: boolean;
 }
 
+/**
+ * Estado de posicionamento do rosto detectado.
+ * - `searching` — nenhum rosto detectado ainda
+ * - `too-far` — rosto muito distante da câmera
+ * - `too-close` — rosto muito próximo da câmera
+ * - `off-center` — rosto fora do centro do oval
+ * - `centered` — rosto corretamente posicionado
+ */
+export declare type FaceState = 'searching' | 'too-far' | 'too-close' | 'off-center' | 'centered';
+
 /**
  * Classe para gerenciar o prompt de fallback
  */
@@ -689,6 +867,9 @@ export declare function getApplicationToken(): string | null;
 /** Retorna o nome do integrador configurado, se houver. */
 export declare function getAppName(): string | null;
 
+/** Retorna a política de quedas automáticas de canal. Ver {@link AutoFallbackOptions}. */
+export declare function getAutoFallback(): Required<AutoFallbackOptions>;
+
 /**
  * Retorna a URL base configurada para a API.
  * Se o SDK não foi inicializado, retorna o fallback para sandbox.
@@ -1185,6 +1366,25 @@ export declare interface ProofOfLifeResult {
     error?: string;
 }
 
+/**
+ * Desfecho da confirmação no celular.
+ *
+ * `denied` e `expired` são desfechos, não exceções — quem chama precisa
+ * distinguir os dois para dirigir a cascata de fallback: expirar pode cair
+ * para senha, recusar **não pode**.
+ */
+export declare type PushApprovalOutcome = {
+    status: 'approved';
+    data: Record<string, unknown>;
+} | {
+    status: 'denied';
+    reason?: string;
+} | {
+    status: 'expired';
+} | {
+    status: 'cancelled';
+};
+
 declare interface RecognitionResult {
     success: boolean;
     data: {
@@ -1268,6 +1468,29 @@ export declare function recordConsent(customConsent?: Partial<{
     legalBasis: string;
 }>): Promise<ConsentRecord | null>;
 
+/** Par de tokens devolvido por {@link refreshSession}. */
+export declare interface RefreshedSession {
+    accessToken: string;
+    refreshToken: string;
+}
+
+/**
+ * Renova a sessão a partir de um refresh token.
+ *
+ * O core **rotaciona**: o refresh antigo entra na blacklist e um novo é
+ * emitido junto do access. Guarde sempre o par devolvido — reenviar o refresh
+ * anterior passa a dar 401.
+ *
+ * Existe para sessões que duram mais que a validade do access token (o console
+ * administrativo é o caso motivador). Fluxos curtos não precisam chamar.
+ *
+ * @param refreshToken Refresh token vigente, vindo de um login anterior.
+ * @param applicationToken Token da aplicação.
+ * @throws NeoFaceError `INVALID_TOKEN` se o refresh expirou, já foi usado ou
+ *         foi revogado — nesse caso o caminho é refazer o login.
+ */
+export declare const refreshSession: (refreshToken: string, applicationToken: string) => Promise<RefreshedSession>;
+
 /**
  * NEO-101: Register biometric data for an existing person
  *
@@ -1390,6 +1613,21 @@ declare interface RequestChallengeWithSessionParams {
  */
 export declare function requestConsent(info?: ConsentInfo): Promise<boolean>;
 
+/**
+ * Pede ao core um token de inscrição de aparelho.
+ *
+ * Exige **as duas** credenciais ao mesmo tempo: `X-App-Token` da aplicação e o
+ * Bearer de um usuário DONOR autenticado (permission `IsDonorOfApplicationConsumer`
+ * no core). Por isso a inscrição só existe no autosserviço, com a pessoa logada.
+ *
+ * O valor devolvido **não é segredo de longa duração**: é um JWT de 5 minutos,
+ * de uso único. Não guarde, não reaproveite e não exiba duas vezes.
+ *
+ * @param userAccessToken Access token do DONOR autenticado.
+ * @param applicationToken Token da aplicação.
+ */
+export declare const requestDeviceEnrollmentToken: (userAccessToken: string, applicationToken: string) => Promise<DeviceEnrollmentToken>;
+
 /**
  * Pede ao servidor a sequência de gestos do desafio de liveness.
  * O SDK apenas exibe e coleta — validação de gesto/yaw/pitch é responsabilidade
@@ -1485,6 +1723,7 @@ declare interface SDKConfig {
     locale: string;
     resolvedTheme: ResolvedTheme | null;
     consent: Consent;
+    autoFallback: Required<AutoFallbackOptions>;
 }
 
 /**
@@ -1541,6 +1780,31 @@ export declare interface SDKInitOptions {
      * e emite `console.warn` uma única vez.
      */
     consent?: Consent;
+    /**
+     * Quedas automáticas de canal, em dois níveis independentes.
+     *
+     * O canal mudar é informação de segurança: cair sozinho esconde do usuário
+     * que a verificação passou a acontecer em outro lugar. Por isso o nível 1
+     * nasce desligado e precisa ser pedido.
+     *
+     * ```
+     * nível 0  rosto no dispositivo atual
+     *          ├─ purpose exige push, ou câmera ausente/negada → nível 1
+     *          └─ ok → fim
+     *
+     * nível 1  confirmar no celular            (toPhone, default false)
+     *          ├─ core diz que não há aparelho → nível 2
+     *          ├─ prazo expirou                → nível 2
+     *          └─ RECUSADO no celular          → falha terminal, não cascateia
+     *
+     * nível 2  e-mail + senha                  (toPassword, default true)
+     * ```
+     *
+     * A recusa não cai para senha de propósito: se caísse, quem disparou o
+     * pedido e levou "não" entraria pelo outro caminho, e o controle não valeria
+     * nada. Só expiração e ausência de aparelho cascateiam.
+     */
+    autoFallback?: AutoFallbackOptions;
 }
 
 export declare type SDKRadius = 8 | 16 | 24;
@@ -1576,6 +1840,35 @@ export declare const simpleIdentification: (documentType: string, documentNumber
     };
 }>;
 
+/**
+ * Frame SSE do core.
+ *
+ * O core emite `data: {json}\n\n` **sem linha `event:`**
+ * (`core/sse_notification_service.py:_format_sse_message`). Pela spec SSE, um
+ * frame sem `event:` é despachado como o tipo default `message` — então
+ * `addEventListener('success', …)` nunca dispara. Quem discrimina é o campo
+ * `status` do payload.
+ */
+export declare interface SseFrame {
+    task_id?: string;
+    status?: string;
+    timestamp?: number;
+    data?: Record<string, unknown>;
+    message?: string;
+    error?: string;
+}
+
+/** Veredito do classificador para cada frame recebido. */
+export declare type SseVerdict<T> = {
+    kind: 'pending';
+} | {
+    kind: 'resolve';
+    value: T;
+} | {
+    kind: 'reject';
+    error: NeoFaceError;
+};
+
 export declare function start(applicationToken: string, callbacks: Callbacks, options?: {
     appName?: string;
     /** NEO-410 · US14.3 — botão "Não consigo fazer esse movimento" visível desde o 1º desafio. */
@@ -1632,7 +1925,7 @@ export declare function startHandLogin(options: BiometricLoginOptions): Promise<
  */
 export declare function startLivenessCapture(applicationToken: string, callbacks: {
     onSuccess(photos: Blob[]): void;
-    onError(code: string, message: string): void;
+    onError(err: NeoFaceError): void;
     onCancel?(): void;
 }, options?: {
     appName?: string;
@@ -1739,7 +2032,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 = "1.40.3";
+export declare const VERSION = "1.42.0";
 
 /**
  * Executa `fn(sessionId)`. Se o servidor devolver 410 (sessão consumida/expirada),