@neofaceid/web-sdk 1.43.0 → 2.0.0

package/dist/index.d.ts

@@ -191,80 +191,6 @@ export declare interface AwaitPushApprovalOptions {
     onFallback?: () => void;
 }
 
-export declare class BiometricCaptureModal {
-    private modal;
-    private video;
-    private canvas;
-    private stream;
-    private options;
-    private countdownInterval;
-    private isCapturing;
-    private flashController;
-    constructor(options: BiometricCaptureOptions);
-    /**
-     * Abre o modal de captura biométrica
-     */
-    open(): Promise<void>;
-    /**
-     * Fecha o modal e limpa recursos
-     */
-    close(): void;
-    /**
-     * Cria a estrutura HTML do modal
-     */
-    private createModal;
-    /**
-     * Inicializa a câmera
-     */
-    private initializeCamera;
-    /**
-     * NEO-413 · US14.6 (item 18) — a contagem "3, 2, 1" foi removida.
-     * Agora habilita direto o botão "Capturar" assim que a câmera fica pronta.
-     * Vivacidade fica com o desafio `runLivenessChallenge` (NEO-408), servidor decide.
-     */
-    private enableCaptureButton;
-    /**
-     * Captura a imagem da câmera
-     */
-    private captureImage;
-    /**
-     * Detecta o tipo biométrico na imagem (face ou mão)
-     */
-    private detectBiometricType;
-    /**
-     * Adiciona event listeners aos elementos do modal
-     */
-    private addEventListeners;
-    /**
-     * Limpa recursos (câmera, intervalos, etc.)
-     */
-    private cleanup;
-    /**
-     * Retorna o título padrão baseado no modo
-     */
-    private getDefaultTitle;
-    /**
-     * Retorna o subtítulo padrão baseado no modo
-     */
-    private getDefaultSubtitle;
-    /**
-     * Adiciona estilos CSS ao modal
-     */
-    private addStyles;
-}
-
-declare interface BiometricCaptureOptions {
-    mode: 'face' | 'hand' | 'auto';
-    onSuccess: (imageData: string, detectedType: 'face' | 'hand') => void;
-    onError: (error: NeoFaceError) => void;
-    onCancel?: () => void;
-    countdown?: number;
-    title?: string;
-    subtitle?: string;
-    /** NEO-425 · US14.11.a — screen flash assistivo em ambiente escuro. Default true. */
-    autoLighting?: boolean;
-}
-
 export declare interface BiometricLoginOptions {
     applicationToken: string;
     /**
@@ -425,10 +351,21 @@ export declare interface CameraOvalGuideProps {
 }
 
 /**
- * Options for capturing face frames
+ * Captura quadros do rosto sem abrir modal.
+ *
+ * Substitui `new NeoFaceID(...).captureFaceFrames(options)`, removido na 2.0.0.
+ * Não precisava da instância — só a mantinha por estar pendurado na classe.
  */
+export declare function captureFaceFrames(options: CaptureFaceFramesOptions): Promise<Blob[]>;
+
+/** Opções de {@link captureFaceFrames}. */
 export declare interface CaptureFaceFramesOptions {
+    /** Quantos quadros capturar, de 1 a 10. */
     numFrames: number;
+    /**
+     * Espaça as capturas em 300 ms. Uma foto estática produz quadros idênticos;
+     * um rosto presente, não.
+     */
     livenessCheck: boolean;
 }
 
@@ -628,26 +565,41 @@ export declare function consumeSseStream<T>(options: ConsumeSseOptions<T>): Prom
  */
 export declare const DEFAULT_CONSENT_INFO: ConsentInfo;
 
-/**
- * Detecta automaticamente o tipo biométrico na imagem
- * @param imageData Dados da imagem em base64
- * @returns Resultado da detecção com tipo e confiança
- */
-export declare function detectBiometricType(imageData: string): Promise<DetectionResult>;
-
-/**
- * Módulo de detecção automática de tipo biométrico
- * Utiliza face-api.js para detectar se a imagem contém face ou mão
- */
-export declare interface DetectionResult {
-    type: 'face' | 'hand' | 'unknown';
-    confidence: number;
-    details?: any;
-}
+/** Desfecho da inscrição de aparelho. */
+export declare type DeviceEnrollmentOutcome = {
+    status: 'enrolled';
+    deviceLabel: string | null;
+    enrolledAt?: string;
+} | {
+    status: 'expired';
+} | {
+    status: 'cancelled';
+};
 
 /** 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. */
+    /**
+     * Identificador curto, no formato `XXXX-XXXX`, de um alfabeto sem os pares
+     * que se confundem (`0/O`, `1/I/L`, `U/V`).
+     *
+     * **É isto que o QR deve carregar**, não o {@link token}. O JWT inteiro vira
+     * uma grade densa que exige tela grande e câmera boa, e deixa o segredo
+     * óptico — exposto em qualquer foto da tela. O handle fotografado vale muito
+     * menos: não carrega `person_id`, `consumer_id` nem assinatura, e morre na
+     * primeira troca. Como é legível, também serve para ditar por telefone ou
+     * digitar à mão quando a câmera falha.
+     */
+    handle: string;
+    /**
+     * Identificador da solicitação. É a chave do canal SSE que avisa quando o
+     * aparelho for inscrito: `/api/v1/devices/enrollment/{jti}/events/`.
+     */
+    jti: string;
+    /**
+     * JWT RS256 de uso único. Continua vindo por compatibilidade, mas **não deve
+     * ir para o QR** — quem resolve o handle é o Push, contra o core, por canal
+     * interno.
+     */
     token: string;
     /** Validade em segundos (o core emite 300). */
     expiresIn: number;
@@ -974,18 +926,6 @@ export declare const identifyPersonAsync: (image: Blob, applicationToken: string
  */
 export declare function init(options?: SDKInitOptions): void;
 
-/**
- * Inicializa o sistema de detecção biométrica
- * Carrega bibliotecas e modelos necessários
- */
-export declare function initializeBiometricDetection(): Promise<void>;
-
-/**
- * Verifica se o sistema de detecção está disponível
- * @returns true se a detecção avançada está disponível
- */
-export declare function isAdvancedDetectionAvailable(): boolean;
-
 /**
  * Verifica se o SDK foi inicializado.
  */
@@ -1013,30 +953,6 @@ export declare interface LivenessChallengeResult {
     raw: unknown;
 }
 
-/**
- * Options for login recognition
- */
-export declare interface LoginRecognitionOptions {
-    biometricData: Blob | Blob[];
-    typeOfIdentification: 'FACE' | 'HAND';
-    purpose: 'LOGIN' | 'PROOF_OF_LIFE' | 'AUTHORIZATION' | 'SIMPLE_IDENTIFICATION' | 'SIMPLIFIED_REGISTRATION';
-    confidenceThreshold?: number;
-}
-
-/**
- * Result of login recognition
- */
-export declare interface LoginRecognitionResult {
-    success: boolean;
-    personName: string;
-    email: string;
-    cpf: string;
-    signature?: string;
-    sessionId?: string;
-    confidenceScore?: number;
-    accessToken?: string;
-}
-
 /**
  * Performs biometric login using face recognition
  * @param image The image blob to process
@@ -1075,194 +991,6 @@ export declare class NeoFaceError extends Error {
     getFriendlyMessage(): string;
 }
 
-/**
- * NeoFaceID SDK class for biometric authentication
- *
- * This class provides a high-level API for biometric recognition,
- * supporting both internal use (without signature) and external integrations
- * (with signature and session data for systems like OpsPay).
- *
- * @example
- * ```typescript
- * // For external integrations (with signature)
- * const sdk = new NeoFaceID({
- *   appToken: 'your-application-token',
- *   baseUrl: 'https://core.neofaceid.com',
- *   signature: signatureFromBackend,
- *   sessionData: {
- *     email: 'user@example.com',
- *     cpf: '12345678901',
- *     sessionId: 'session-uuid-123'
- *   }
- * });
- *
- * // For internal use (without signature)
- * const sdk = new NeoFaceID({
- *   appToken: 'your-application-token'
- * });
- * ```
- */
-export declare class NeoFaceID {
-    private appToken;
-    private signature?;
-    private sessionData?;
-    /**
-     * Creates a new NeoFaceID instance
-     * @param config Configuration object
-     * @throws NeoFaceError if signature format is invalid
-     */
-    constructor(config: NeoFaceIDConfig);
-    /**
-     * Validates the format of a signature
-     * HMAC-SHA256 produces a 64-character hexadecimal string
-     * @param signature The signature to validate
-     * @returns true if valid, false otherwise
-     */
-    private validateSignatureFormat;
-    /**
-     * Captures multiple face frames for biometric recognition
-     * @param options Capture options
-     * @returns Promise that resolves to an array of image blobs
-     * @throws NeoFaceError if capture fails
-     */
-    captureFaceFrames(options: CaptureFaceFramesOptions): Promise<Blob[]>;
-    /**
-     * Performs login recognition using biometric data
-     *
-     * This method is designed for external integrations that require
-     * signature validation and session management.
-     *
-     * @param options Recognition options
-     * @returns Promise that resolves to recognition result
-     * @throws NeoFaceError if recognition fails
-     *
-     * @example
-     * ```typescript
-     * const result = await sdk.loginRecognition({
-     *   biometricData: await sdk.captureFaceFrames({
-     *     numFrames: 5,
-     *     livenessCheck: true
-     *   }),
-     *   typeOfIdentification: 'FACE',
-     *   purpose: 'LOGIN',
-     *   confidenceThreshold: 0.8
-     * });
-     *
-     * // Result includes signature and sessionId for callback validation
-     * console.log(result.signature, result.sessionId);
-     * ```
-     */
-    loginRecognition(options: LoginRecognitionOptions): Promise<LoginRecognitionResult>;
-    /**
-     * Register a new application for a consumer
-     *
-     * This method allows authenticated users to register new applications
-     * that will receive their own app_token for API access.
-     *
-     * @param jwtToken JWT authentication token from logged user
-     * @param consumerId Consumer ID (UUID) who will own the application
-     * @param applicationData Application registration data
-     * @returns Promise with registration result including app_token
-     * @throws NeoFaceError if registration fails
-     *
-     * @example
-     * ```typescript
-     * const sdk = new NeoFaceID({
-     *   appToken: 'your-application-token'
-     * });
-     *
-     * const result = await sdk.registerApplication(
-     *   userJwtToken,
-     *   consumerUuid,
-     *   {
-     *     applicationName: 'My New App',
-     *     domain: 'example.com',
-     *     acceptOnlyEmailWithSameDomain: true
-     *   }
-     * );
-     *
-     * // Use the generated app_token for the new application
-     * console.log('New App Token:', result.application.app_token);
-     * ```
-     */
-    registerApplication(jwtToken: string, consumerId: string, applicationData: ApplicationRegistrationData): Promise<ApplicationRegistrationResult>;
-    /**
-     * Performs Proof of Life verification
-     *
-     * This method records a video from the camera, sends it to the backend
-     * for liveness detection and face recognition, and returns the result
-     * with personal data filtered by purpose.
-     *
-     * The process is asynchronous:
-     * 1. Records video from the camera (default 3 seconds)
-     * 2. Converts video to base64 and sends to backend
-     * 3. Backend processes liveness detection and face recognition
-     * 4. Polls for task completion
-     * 5. Returns personal data of the identified person
-     *
-     * @param options Configuration options for the proof of life process
-     * @returns Promise that resolves to ProofOfLifeResult
-     * @throws NeoFaceError if verification fails
-     *
-     * @example
-     * ```typescript
-     * const sdk = new NeoFaceID({
-     *   appToken: 'your-application-token'
-     * });
-     *
-     * const result = await sdk.proofOfLife({
-     *   videoDurationMs: 3000, // 3 seconds
-     *   onRecordingProgress: (progress) => {
-     *     console.log(`Recording: ${progress}%`);
-     *   },
-     *   onTaskStatusChange: (status, progress) => {
-     *     console.log(`Status: ${status}, Progress: ${progress}%`);
-     *   }
-     * });
-     *
-     * if (result.success && result.isLive) {
-     *   console.log('Person verified:', result.personalData);
-     *   console.log('Liveness score:', result.livenessScore);
-     *   console.log('Face recognition score:', result.faceRecognitionScore);
-     * }
-     * ```
-     */
-    /**
-     * Registers document images for an already-registered donor person.
-     *
-     * Opens the document capture UI (front + optional back), then submits
-     * the images to the backend for extraction via DocExt.
-     * The backend processes this asynchronously — use the returned `taskId`
-     * to poll status if needed.
-     *
-     * @param personId UUID of the donor's person record
-     * @param jwtToken JWT Bearer token of the authenticated donor
-     * @param options Optional capture configuration
-     * @returns Promise with task_id and processing status
-     * @throws NeoFaceError if capture is cancelled, validation fails, or API call fails
-     *
-     * @example
-     * ```typescript
-     * const sdk = new NeoFaceID({ appToken: 'your-token' });
-     *
-     * const result = await sdk.registerDocumentByImage(personId, userJwtToken);
-     * console.log('Task ID:', result.taskId); // poll for completion
-     * ```
-     */
-    registerDocumentByImage(personId: string, jwtToken: string, options?: RegisterDocumentByImageOptions): Promise<RegisterDocumentResult>;
-    proofOfLife(options?: ProofOfLifeOptions): Promise<ProofOfLifeResult>;
-}
-
-/**
- * Configuration for NeoFaceID SDK initialization
- */
-export declare interface NeoFaceIDConfig {
-    appToken: string;
-    baseUrl?: string;
-    signature?: string;
-    sessionData?: SessionData;
-}
-
 declare interface OnboardingLinkDetails {
     id: string;
     token: string;
@@ -1333,18 +1061,42 @@ export declare interface PersonalDataItem {
 export declare function preloadFaceDetectionModels(): Promise<void>;
 
 /**
- * Options for Proof of Life verification
+ * Prova de vida: grava um vídeo curto da câmera, envia ao core e aguarda o
+ * resultado da detecção de vivacidade e do reconhecimento.
+ *
+ * Substitui `new NeoFaceID({ appToken }).proofOfLife(options)`, removido na
+ * 2.0.0. A migração é direta:
+ *
+ * ```ts
+ * // antes
+ * const sdk = new NeoFaceID({ appToken: TOKEN });
+ * const r = await sdk.proofOfLife({ videoDurationMs: 3000 });
+ *
+ * // depois
+ * const r = await proofOfLife({ applicationToken: TOKEN, videoDurationMs: 3000 });
+ * ```
+ *
+ * `success: false` com `isLive: false` é desfecho, não exceção — a pessoa pode
+ * simplesmente não ter passado na prova. Exceção fica para falha de câmera,
+ * rede ou credencial.
  */
+export declare function proofOfLife(options?: ProofOfLifeOptions): Promise<ProofOfLifeResult>;
+
+/** Opções de {@link proofOfLife}. */
 export declare interface ProofOfLifeOptions {
-    /** Duration of video recording in milliseconds (default: 3000) */
+    /**
+     * Token da aplicação. Se omitido, usa o informado em `init({ applicationToken })`.
+     */
+    applicationToken?: string;
+    /** Duração da gravação, em milissegundos. Default 3000. */
     videoDurationMs?: number;
-    /** Maximum polling attempts for task status (default: 60) */
+    /** Máximo de consultas ao status da task. Default 60. */
     maxPollingAttempts?: number;
-    /** Interval between polling attempts in ms (default: 1000) */
+    /** Intervalo entre consultas, em milissegundos. Default 1000. */
     pollingIntervalMs?: number;
-    /** Callback for recording progress (0-100) */
+    /** Progresso da gravação, de 0 a 100. */
     onRecordingProgress?: (progress: number) => void;
-    /** Callback for task status changes */
+    /** Mudança de estado da task no core. */
     onTaskStatusChange?: (status: string, progress?: number) => void;
 }
 
@@ -1499,6 +1251,30 @@ export declare interface RefreshedSession {
  */
 export declare const refreshSession: (refreshToken: string, applicationToken: string) => Promise<RefreshedSession>;
 
+/**
+ * Register a new application for a consumer
+ * @param jwtToken JWT authentication token from logged user
+ * @param consumerId Consumer ID (UUID) who will own the application
+ * @param applicationData Application registration data
+ * @returns Promise with registration result
+ * @throws NeoFaceError if registration fails
+ *
+ * @example
+ * ```typescript
+ * const result = await registerApplication(
+ *   'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
+ *   'consumer-uuid-123',
+ *   {
+ *     applicationName: 'My App',
+ *     domain: 'example.com',
+ *     acceptOnlyEmailWithSameDomain: true
+ *   }
+ * );
+ * console.log('App Token:', result.application.app_token);
+ * ```
+ */
+export declare const registerApplication: (jwtToken: string, consumerId: string, applicationData: ApplicationRegistrationData) => Promise<ApplicationRegistrationResult>;
+
 /**
  * NEO-101: Register biometric data for an existing person
  *
@@ -1522,12 +1298,24 @@ export declare const registerBiometric: (personId: string, faceImage: Blob, appl
 }>;
 
 /**
- * Options for registering a document by image capture
+ * Abre a captura de documento (frente e, opcionalmente, verso) e envia as
+ * imagens ao core para extração.
+ *
+ * Substitui `new NeoFaceID(...).registerDocumentByImage(...)`, removido na
+ * 2.0.0. Difere de `startDocumentCapture()`, que só captura: esta função
+ * também submete ao core. O processamento é assíncrono — use o `taskId`
+ * devolvido para acompanhar.
+ *
+ * @param personId UUID da pessoa (doador já cadastrado).
+ * @param jwtToken Bearer do doador autenticado.
  */
+export declare function registerDocumentByImage(personId: string, jwtToken: string, options?: RegisterDocumentByImageOptions): Promise<RegisterDocumentResult>;
+
+/** Opções de {@link registerDocumentByImage}. */
 export declare interface RegisterDocumentByImageOptions {
-    /** Pre-select document type, skipping the selection screen */
+    /** Pré-seleciona o tipo de documento, pulando a tela de escolha. */
     preSelectedDocument?: 'RG' | 'CNH' | 'CPF';
-    /** Use back camera for capture (default: true) */
+    /** Usa a câmera traseira. Default `true`. */
     useBackCamera?: boolean;
 }
 
@@ -1603,7 +1391,7 @@ export declare const registerPersonWithoutFace: (personData: {
 /**
  * Data de lançamento da versão atual
  */
-export declare const RELEASE_DATE = "2026-09-15";
+export declare const RELEASE_DATE = "2026-09-19";
 
 declare interface RequestChallengeWithSessionParams {
     applicationToken: string;
@@ -1908,6 +1696,42 @@ export declare function startBiometricRegistration(personData: {
     onCannotGesture?: () => void;
 }): void;
 
+/**
+ * Abre o fluxo de inscrição de aparelho: mostra o código, aguarda o celular
+ * lê-lo e confirma o vínculo.
+ *
+ * Exige uma pessoa autenticada — o core pede o Bearer do DONOR junto do
+ * `X-App-Token`, e por isso a inscrição só existe no autosserviço.
+ *
+ * O QR carrega o **handle curto**, nunca o JWT: um código denso exige tela
+ * grande e câmera boa, e o token inteiro ficaria exposto em qualquer foto da
+ * tela. Quem resolve o handle é a plataforma Push, contra o core, por canal
+ * interno — o navegador não participa dessa troca.
+ *
+ * @example
+ * ```ts
+ * const r = await startDeviceEnrollment({
+ *   userAccessToken: sessao.accessToken,
+ *   applicationToken: TOKEN,
+ * });
+ * if (r.status === 'enrolled') {
+ *   // r.deviceLabel pode ser null enquanto o Push não envia o rótulo
+ * }
+ * ```
+ */
+export declare function startDeviceEnrollment(options: StartDeviceEnrollmentOptions): Promise<DeviceEnrollmentOutcome>;
+
+export declare interface StartDeviceEnrollmentOptions {
+    /**
+     * Access token do DONOR autenticado. A inscrição só existe no autosserviço,
+     * com a pessoa logada — o core exige este Bearer **junto** do `X-App-Token`.
+     */
+    userAccessToken: string;
+    applicationToken: string;
+    /** Nome do integrador (fallback: `init({ appName })`). */
+    appName?: string;
+}
+
 /**
  * Função auxiliar para iniciar a captura de documento
  */
@@ -2040,7 +1864,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.43.0";
+export declare const VERSION = "2.0.0";
 
 /**
  * Executa `fn(sessionId)`. Se o servidor devolver 410 (sessão consumida/expirada),