@neofaceid/web-sdk 1.41.1 → 1.42.1

package/dist/index.d.ts

@@ -30,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;
@@ -107,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;
@@ -202,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;
@@ -280,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;
@@ -495,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.
@@ -518,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;
@@ -731,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.
@@ -1227,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: {
@@ -1310,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
  *
@@ -1414,7 +1595,7 @@ export declare const registerPersonWithoutFace: (personData: {
 /**
  * Data de lançamento da versão atual
  */
-export declare const RELEASE_DATE = "2026-09-10";
+export declare const RELEASE_DATE = "2026-09-13";
 
 declare interface RequestChallengeWithSessionParams {
     applicationToken: string;
@@ -1432,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
@@ -1527,6 +1723,7 @@ declare interface SDKConfig {
     locale: string;
     resolvedTheme: ResolvedTheme | null;
     consent: Consent;
+    autoFallback: Required<AutoFallbackOptions>;
 }
 
 /**
@@ -1583,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;
@@ -1618,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. */
@@ -1781,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.41.1";
+export declare const VERSION = "1.42.1";
 
 /**
  * Executa `fn(sessionId)`. Se o servidor devolver 410 (sessão consumida/expirada),