@neofaceid/web-sdk 1.26.1 → 1.27.0

package/dist/index.d.ts

@@ -258,6 +258,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)
@@ -557,6 +570,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 +589,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 +679,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 +978,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,12 +1223,36 @@ 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()`.
  */
 export declare function requestConsent(info?: Partial<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
  * @param email User email address
@@ -1189,6 +1262,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
  */
@@ -1327,6 +1427,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 +1477,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.27.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 { }

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

@@ -10417,8 +10417,254 @@ const biometricDetection = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.
   initializeBiometricDetection,
   isAdvancedDetectionAvailable
 }, Symbol.toStringTag, { value: "Module" }));
-const VERSION = "1.26.1";
+const VERSION = "1.27.0";
 const RELEASE_DATE = "2026-09-01";
+let cachedSession = null;
+function getCachedCaptureSession() {
+  return cachedSession;
+}
+function resetCaptureSession() {
+  cachedSession = null;
+}
+async function openCaptureSession({
+  applicationToken,
+  purpose
+}) {
+  if (!applicationToken) {
+    throw new NeoFaceError(
+      "applicationToken é obrigatório para abrir sessão de captura",
+      ErrorType.INVALID_TOKEN
+    );
+  }
+  const url = `${getBaseUrl()}/api/v1/auth/capture/session/`;
+  let response;
+  try {
+    response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-App-Token": applicationToken
+      },
+      body: JSON.stringify({ purpose })
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Erro de rede";
+    throw new NeoFaceError(`Falha de rede ao abrir sessão: ${message}`, ErrorType.NETWORK);
+  }
+  if (response.status === 401 || response.status === 403) {
+    throw new NeoFaceError("Token de aplicação inválido ou expirado", ErrorType.INVALID_TOKEN);
+  }
+  if (!response.ok) {
+    throw new NeoFaceError(
+      `Falha ao abrir sessão de captura (${response.status})`,
+      ErrorType.API_ERROR
+    );
+  }
+  const raw = await response.json().catch(() => null);
+  const payload = (raw == null ? void 0 : raw.data) ?? raw;
+  const sessionId = payload == null ? void 0 : payload.session_id;
+  const expiresAt = payload == null ? void 0 : payload.expires_at;
+  if (!sessionId || !expiresAt) {
+    throw new NeoFaceError(
+      "Resposta inválida ao abrir sessão de captura (campos ausentes)",
+      ErrorType.API_ERROR
+    );
+  }
+  cachedSession = { session_id: sessionId, expires_at: expiresAt };
+  return cachedSession;
+}
+async function withCaptureSession(params, fn) {
+  const session = cachedSession ?? await openCaptureSession(params);
+  try {
+    return await fn(session.session_id);
+  } catch (err) {
+    if (err instanceof NeoFaceError && err.message.includes("410")) {
+      resetCaptureSession();
+      const fresh = await openCaptureSession(params);
+      return fn(fresh.session_id);
+    }
+    throw err;
+  }
+}
+function withSessionId(payload) {
+  const session = cachedSession;
+  if (!session) return payload;
+  return { ...payload, session_id: session.session_id };
+}
+async function requestLivenessChallenge({
+  sessionId,
+  applicationToken
+}) {
+  if (!applicationToken) {
+    throw new NeoFaceError(
+      "applicationToken é obrigatório para solicitar desafio de liveness",
+      ErrorType.INVALID_TOKEN
+    );
+  }
+  if (!sessionId) {
+    throw new NeoFaceError(
+      "session_id é obrigatório para solicitar desafio de liveness",
+      ErrorType.VALIDATION_ERROR
+    );
+  }
+  const url = `${getBaseUrl()}/api/v1/auth/liveness/challenge/`;
+  let response;
+  try {
+    response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-App-Token": applicationToken
+      },
+      body: JSON.stringify({ session_id: sessionId })
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Erro de rede";
+    throw new NeoFaceError(`Falha de rede ao solicitar desafio: ${message}`, ErrorType.NETWORK);
+  }
+  if (response.status === 401 || response.status === 403) {
+    throw new NeoFaceError("Token de aplicação inválido ou expirado", ErrorType.INVALID_TOKEN);
+  }
+  if (response.status === 410) {
+    throw new NeoFaceError(
+      "Sessão de captura expirada (410) — reabrir sessão",
+      ErrorType.API_ERROR
+    );
+  }
+  if (!response.ok) {
+    throw new NeoFaceError(
+      `Falha ao solicitar desafio de liveness (${response.status})`,
+      ErrorType.API_ERROR
+    );
+  }
+  const raw = await response.json().catch(() => null);
+  const payload = (raw == null ? void 0 : raw.data) ?? raw;
+  const challengeId = payload == null ? void 0 : payload.challenge_id;
+  const gestures = payload == null ? void 0 : payload.gestures;
+  if (!challengeId || !Array.isArray(gestures) || gestures.length === 0) {
+    throw new NeoFaceError(
+      "Resposta inválida ao solicitar desafio (campos ausentes)",
+      ErrorType.API_ERROR
+    );
+  }
+  return {
+    challenge_id: challengeId,
+    gestures,
+    expires_at: payload == null ? void 0 : payload.expires_at
+  };
+}
+async function requestLivenessChallengeWithSession({
+  applicationToken,
+  purpose,
+  sessionId
+}) {
+  let currentSessionId = sessionId ?? (await openCaptureSession({ applicationToken, purpose })).session_id;
+  try {
+    return await requestLivenessChallenge({ sessionId: currentSessionId, applicationToken });
+  } catch (err) {
+    if (err instanceof NeoFaceError && err.message.includes("410")) {
+      resetCaptureSession();
+      currentSessionId = (await openCaptureSession({ applicationToken, purpose })).session_id;
+      return requestLivenessChallenge({ sessionId: currentSessionId, applicationToken });
+    }
+    throw err;
+  }
+}
+async function submitLivenessChallenge({
+  challengeId,
+  sessionId,
+  applicationToken,
+  gestures
+}) {
+  if (!applicationToken) {
+    throw new NeoFaceError(
+      "applicationToken é obrigatório para submeter desafio",
+      ErrorType.INVALID_TOKEN
+    );
+  }
+  if (!challengeId || !sessionId) {
+    throw new NeoFaceError(
+      "challenge_id e session_id são obrigatórios para submeter desafio",
+      ErrorType.VALIDATION_ERROR
+    );
+  }
+  if (!Array.isArray(gestures) || gestures.length === 0) {
+    throw new NeoFaceError("gestures[] vazio — nada para submeter", ErrorType.VALIDATION_ERROR);
+  }
+  const url = `${getBaseUrl()}/api/v1/auth/liveness/challenge/${encodeURIComponent(challengeId)}/submit/`;
+  let response;
+  try {
+    response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-App-Token": applicationToken
+      },
+      body: JSON.stringify({ session_id: sessionId, gestures })
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Erro de rede";
+    throw new NeoFaceError(`Falha de rede ao submeter desafio: ${message}`, ErrorType.NETWORK);
+  }
+  if (response.status === 401 || response.status === 403) {
+    throw new NeoFaceError("Token de aplicação inválido ou expirado", ErrorType.INVALID_TOKEN);
+  }
+  if (response.status === 410) {
+    throw new NeoFaceError(
+      "Sessão ou desafio expirado (410) — reabrir sessão",
+      ErrorType.API_ERROR
+    );
+  }
+  if (!response.ok) {
+    throw new NeoFaceError(
+      `Falha ao submeter desafio de liveness (${response.status})`,
+      ErrorType.API_ERROR
+    );
+  }
+  const raw = await response.json().catch(() => null);
+  const payload = (raw == null ? void 0 : raw.data) ?? raw ?? {};
+  return {
+    success: (payload == null ? void 0 : payload.success) ?? true,
+    liveness_passed: payload == null ? void 0 : payload.liveness_passed,
+    score: payload == null ? void 0 : payload.score,
+    raw
+  };
+}
+async function runLivenessChallenge({
+  applicationToken,
+  purpose,
+  collectFramesForGesture,
+  retryOnSessionExpired = true
+}) {
+  const attempt = async () => {
+    const session = await openCaptureSession({ applicationToken, purpose });
+    const challenge = await requestLivenessChallenge({
+      sessionId: session.session_id,
+      applicationToken
+    });
+    const gestures = [];
+    for (let i = 0; i < challenge.gestures.length; i += 1) {
+      const g = challenge.gestures[i];
+      const images = await collectFramesForGesture(g, i, challenge.gestures.length);
+      gestures.push({ gesture_key: String(g.gesture_key), images });
+    }
+    return submitLivenessChallenge({
+      challengeId: challenge.challenge_id,
+      sessionId: session.session_id,
+      applicationToken,
+      gestures
+    });
+  };
+  try {
+    return await attempt();
+  } catch (err) {
+    if (retryOnSessionExpired && err instanceof NeoFaceError && err.message.includes("410")) {
+      resetCaptureSession();
+      return attempt();
+    }
+    throw err;
+  }
+}
 class OnboardingCaptureModal {
   constructor(options) {
     __publicField(this, "overlay", null);
@@ -12275,6 +12521,7 @@ export {
   detectBiometricType,
   getApplicationToken,
   getBaseUrl,
+  getCachedCaptureSession,
   getConfig,
   getEnvironment,
   identifyPerson,
@@ -12285,6 +12532,7 @@ export {
   isInitialized,
   loginWithBiometric,
   loginWithEmail,
+  openCaptureSession,
   preloadFaceDetectionModels,
   recognize,
   recognizeBiometric,
@@ -12293,7 +12541,11 @@ export {
   registerPersonWithBiometric,
   registerPersonWithoutFace,
   requestConsent,
+  requestLivenessChallenge,
+  requestLivenessChallengeWithSession,
   requestPasswordReset,
+  resetCaptureSession,
+  runLivenessChallenge,
   simpleIdentification,
   start,
   startAutoLogin,
@@ -12303,6 +12555,9 @@ export {
   startHandLogin,
   startLivenessCapture,
   startOnboarding,
+  submitLivenessChallenge,
   validateOnboardingToken,
-  validateToken
+  validateToken,
+  withCaptureSession,
+  withSessionId
 };