@neofaceid/web-sdk 1.26.1 → 1.28.0

package/dist/index.d.ts

@@ -33,6 +33,8 @@ export declare interface AuthorizationOptions {
     onProgress?: (step: number, totalSteps: number, instruction: string) => void;
     onPhotoTaken?: (photoNumber: number, blob: Blob) => void;
     captureDelay?: number;
+    /** Nome do integrador exibido no topo do modal de consentimento (US14.2). */
+    appName?: string;
 }
 
 export declare interface AuthorizationResult {
@@ -141,6 +143,11 @@ export declare function biometricLogin(applicationToken: string, mode?: 'face' |
 
 export declare interface BiometricLoginOptions {
     applicationToken: string;
+    /**
+     * Nome do integrador exibido no topo do modal de consentimento (US14.2).
+     * Ausência gera console.warn e cai para o fallback "sua aplicação".
+     */
+    appName?: string;
     onSuccess: (result: BiometricLoginResult) => void;
     onError: (error: NeoFaceError) => void;
     onCancel?: () => void;
@@ -258,6 +265,19 @@ export declare interface CaptureFaceFramesOptions {
     livenessCheck: boolean;
 }
 
+export declare type CapturePurpose = 'login' | 'onboarding' | 'authorization' | 'identification' | 'liveness';
+
+export declare interface CaptureSession {
+    session_id: string;
+    expires_at: string;
+}
+
+export declare interface ChallengeGesture {
+    index: number;
+    gesture_key: GestureKey | string;
+    instruction_i18n?: Record<string, string>;
+}
+
 /**
  * Check if a user exists by email or CPF
  * @param params Object with email or cpf to check (only one at a time)
@@ -337,16 +357,15 @@ export declare function confirmPasswordReset(token: string, new_password: string
     message: string;
 }>;
 
+declare type ConsentFlow = 'verification' | 'registration';
+
 export declare interface ConsentInfo {
-    purpose: string;
-    legalBasis: string;
-    privacyPolicyUrl: string;
-    retentionDays: number;
+    appName?: string;
+    flow?: ConsentFlow;
+    privacyPolicyUrl?: string;
+    retentionDays?: number;
 }
 
-/**
- * Gerencia o ciclo de vida (montagem/desmontagem) do modal de consentimento.
- */
 export declare class ConsentModal {
     private container;
     private root;
@@ -354,21 +373,18 @@ export declare class ConsentModal {
     close(): void;
 }
 
-/**
- * Props do modal de consentimento LGPD exibido antes de qualquer captura de câmera.
- */
 export declare interface ConsentModalProps {
-    purpose: string;
-    legalBasis: string;
-    privacyPolicyUrl: string;
-    retentionDays: number;
+    appName: string;
+    flow: ConsentFlow;
+    privacyPolicyUrl?: string;
+    retentionDays?: number;
     onAccept: () => void;
     onDecline: () => void;
 }
 
 /**
- * Defaults conservadores usados enquanto `SDKInitOptions` não expõe `consent` (US7.2).
- * Quando essa opção existir, este helper passa a ler `getConfig().consent`.
+ * Compatibilidade com callers antigos que passavam `{ purpose, legalBasis }`.
+ * Deprecated — remover quando US14.4 unificar tokens.
  */
 export declare const DEFAULT_CONSENT_INFO: ConsentInfo;
 
@@ -431,6 +447,9 @@ export declare interface DocumentCaptureOptions {
     useBackCamera?: boolean;
     onCancel?: () => void;
     preSelectedDocument?: DocumentType_2;
+    /** Nome do integrador exibido no topo do modal de consentimento (US14.2). */
+    appName?: string;
+    /* Excluded from this release type: skipConsent */
 }
 
 export declare interface DocumentCaptureResult {
@@ -557,6 +576,14 @@ export declare class ForgotPasswordModal {
     private addStyles;
 }
 
+export declare type GestureKey = 'turn_left' | 'turn_right' | 'turn_up' | 'turn_down' | 'blink' | 'smile' | 'open_mouth';
+
+export declare interface GestureResponse {
+    gesture_key: string;
+    /** Frames capturados como data URL ou base64. SDK só empacota — servidor valida. */
+    images: string[];
+}
+
 /**
  * Retorna o token de aplicação configurado, se houver.
  */
@@ -568,6 +595,8 @@ export declare function getApplicationToken(): string | null;
  */
 export declare function getBaseUrl(): string;
 
+export declare function getCachedCaptureSession(): CaptureSession | null;
+
 /**
  * Retorna toda a configuração atual (para debug).
  */
@@ -656,6 +685,19 @@ export declare function isAdvancedDetectionAvailable(): boolean;
  */
 export declare function isInitialized(): boolean;
 
+export declare interface LivenessChallenge {
+    challenge_id: string;
+    gestures: ChallengeGesture[];
+    expires_at?: string;
+}
+
+export declare interface LivenessChallengeResult {
+    success: boolean;
+    liveness_passed?: boolean;
+    score?: number;
+    raw: unknown;
+}
+
 /**
  * Options for login recognition
  */
@@ -942,6 +984,19 @@ export declare interface OnboardingPersonData {
     email?: string;
 }
 
+/**
+ * Abre uma sessão de captura no servidor. Server-decides: o `session_id`
+ * vem do backend, nunca é inventado no cliente.
+ *
+ * @throws NeoFaceError em 4xx/5xx ou payload inválido.
+ */
+export declare function openCaptureSession({ applicationToken, purpose, }: OpenCaptureSessionParams): Promise<CaptureSession>;
+
+export declare interface OpenCaptureSessionParams {
+    applicationToken: string;
+    purpose: CapturePurpose;
+}
+
 export declare type OverlayStatus = 'preparing' | 'detecting' | 'waiting-for-face' | 'capturing' | 'verifying' | 'success' | 'error';
 
 /**
@@ -1174,11 +1229,39 @@ export declare const registerPersonWithoutFace: (personData: {
  */
 export declare const RELEASE_DATE = "2026-09-01";
 
+declare interface RequestChallengeWithSessionParams {
+    applicationToken: string;
+    purpose: CapturePurpose;
+    sessionId?: string;
+}
+
 /**
  * Exibe o modal de consentimento e resolve `true` se o titular aceitou,
  * `false` se recusou. Deve ser chamado antes de qualquer `getUserMedia()`.
+ *
+ * `appName` é obrigatório na prática — omitir gera console.warn e fallback.
+ * `flow` decide a copy da terceira linha: 'verification' (padrão) descarta a
+ * imagem; 'registration' informa que o vetor biométrico é armazenado.
  */
-export declare function requestConsent(info?: Partial<ConsentInfo>): Promise<boolean>;
+export declare function requestConsent(info?: ConsentInfo): Promise<boolean>;
+
+/**
+ * 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
+ * exclusiva do servidor (regra "client collects, server decides").
+ */
+export declare function requestLivenessChallenge({ sessionId, applicationToken, }: RequestLivenessChallengeParams): Promise<LivenessChallenge>;
+
+export declare interface RequestLivenessChallengeParams {
+    sessionId: string;
+    applicationToken: string;
+}
+
+/**
+ * Garante uma sessão válida e retorna o desafio.
+ * Em 410 (sessão expirada), reabre 1x e reenvia. Segunda falha propaga.
+ */
+export declare function requestLivenessChallengeWithSession({ applicationToken, purpose, sessionId, }: RequestChallengeWithSessionParams): Promise<LivenessChallenge>;
 
 /**
  * Request a password reset for a user account
@@ -1189,6 +1272,33 @@ export declare function requestPasswordReset(email: string, applicationToken: st
     message: string;
 }>;
 
+export declare function resetCaptureSession(): void;
+
+/**
+ * Orquestra o fluxo completo:
+ * 1. Abre `capture/session`
+ * 2. Pede `liveness/challenge` (sequência sorteada pelo servidor)
+ * 3. Delega a coleta de frames ao consumidor gesto a gesto
+ * 4. Submete a resposta para o servidor validar
+ *
+ * Retry: em 410 no submit, reabre a sessão + refaz o desafio + reenvia UMA vez.
+ * Segunda falha propaga.
+ */
+export declare function runLivenessChallenge({ applicationToken, purpose, collectFramesForGesture, retryOnSessionExpired, }: RunLivenessChallengeParams): Promise<LivenessChallengeResult>;
+
+export declare interface RunLivenessChallengeParams {
+    applicationToken: string;
+    purpose: CapturePurpose;
+    /**
+     * Callback fornecido pelo consumidor: para cada gesto na sequência sorteada
+     * pelo servidor, retorna os frames coletados. SDK NÃO decide se o gesto foi
+     * cumprido — só coleta e envia; validação é 100% servidor.
+     */
+    collectFramesForGesture: (gesture: ChallengeGesture, index: number, total: number) => Promise<string[]>;
+    /** Se true, quando o servidor devolver 410 no submit, reabre sessão + refaz o desafio 1x. */
+    retryOnSessionExpired?: boolean;
+}
+
 /**
  * Configuração interna do SDK
  */
@@ -1249,7 +1359,9 @@ export declare const simpleIdentification: (documentType: string, documentNumber
     };
 }>;
 
-export declare function start(applicationToken: string, callbacks: Callbacks): void;
+export declare function start(applicationToken: string, callbacks: Callbacks, options?: {
+    appName?: string;
+}): void;
 
 /**
  * Inicia o processo de login com detecção automática do tipo biométrico
@@ -1271,6 +1383,7 @@ export declare function startBiometricRegistration(personData: {
     password: string;
 }, applicationToken: string, callbacks: BiometricRegistrationCallbacks, options?: {
     useRealApi?: boolean;
+    appName?: string;
 }): void;
 
 /**
@@ -1300,6 +1413,8 @@ export declare function startLivenessCapture(applicationToken: string, callbacks
     onSuccess(photos: Blob[]): void;
     onError(code: string, message: string): void;
     onCancel?(): void;
+}, options?: {
+    appName?: string;
 }): void;
 
 /**
@@ -1314,6 +1429,8 @@ export declare interface StartOnboardingOptions {
     countdown?: number;
     title?: string;
     subtitle?: string;
+    /** Nome do integrador exibido no topo do modal de consentimento (US14.2). */
+    appName?: string;
     onSuccess: (result: {
         success: boolean;
         message: string;
@@ -1327,6 +1444,20 @@ export declare interface StartOnboardingOptions {
     onCancel?: () => void;
 }
 
+/**
+ * Envia os frames coletados para o servidor validar o desafio de liveness.
+ * Endpoint: `POST /api/v1/auth/liveness/challenge/{challenge_id}/submit/`
+ * O SDK apenas empacota e envia — nenhuma decisão de aprovar/reprovar aqui.
+ */
+export declare function submitLivenessChallenge({ challengeId, sessionId, applicationToken, gestures, }: SubmitLivenessChallengeParams): Promise<LivenessChallengeResult>;
+
+export declare interface SubmitLivenessChallengeParams {
+    challengeId: string;
+    sessionId: string;
+    applicationToken: string;
+    gestures: GestureResponse[];
+}
+
 /**
  * Result of user existence check
  */
@@ -1363,6 +1494,21 @@ 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.26.1";
+export declare const VERSION = "1.28.0";
+
+/**
+ * Executa `fn(sessionId)`. Se o servidor devolver 410 (sessão consumida/expirada),
+ * reabre a sessão automaticamente 1x e reexecuta. Segunda falha propaga.
+ */
+export declare function withCaptureSession<T>(params: OpenCaptureSessionParams, fn: (sessionId: string) => Promise<T>): Promise<T>;
+
+/**
+ * Injeta `session_id` cacheado no payload. Se não houver sessão aberta,
+ * retorna o payload original inalterado — a decisão de exigir sessão
+ * fica no servidor.
+ */
+export declare function withSessionId<T extends Record<string, unknown>>(payload: T): T & {
+    session_id?: string;
+};
 
 export { }