@neofaceid/web-sdk 1.36.1 → 1.37.0

package/dist/index.d.ts

@@ -88,7 +88,12 @@ export declare interface AuthorizeOptions {
     amount?: number;
     onChallengeStart?: (gesture: ChallengeGesture, index: number, total: number) => void;
     onChallengeComplete?: (gesture: ChallengeGesture, index: number, total: number) => void;
-    onSuccess?: (result: LivenessChallengeResult) => void;
+    /**
+     * NEO-427: agora recebe o resultado da COLETA (sessionId + challenge + gestures
+     * capturadas). O SDK não decide aprovação — envie os frames via seu próprio
+     * pipeline de recognition (ex.: `POST /auth/recognition/face/`).
+     */
+    onSuccess?: (result: RunLivenessChallengeCollectResult) => void;
     onError?: (error: NeoFaceError) => void;
     onCancel?: () => void;
     /**
@@ -329,6 +334,11 @@ export declare interface CaptureSession {
 export declare interface ChallengeGesture {
     index: number;
     gesture_key: GestureKey | string;
+    /**
+     * Instrução pronta pelo backend (v1.4.x, respeita `Accept-Language`).
+     * Nos payloads legados vinha via `instruction_i18n`.
+     */
+    instruction?: string;
     instruction_i18n?: Record<string, string>;
 }
 
@@ -411,6 +421,24 @@ export declare function confirmPasswordReset(token: string, new_password: string
     message: string;
 }>;
 
+/**
+ * Dados de consentimento LGPD informados pelo integrador.
+ * Usados pelo SDK para registrar a base legal da coleta biométrica.
+ */
+export declare interface Consent {
+    /** Finalidade da coleta (ex: 'authentication', 'onboarding'). */
+    purpose: string;
+    /**
+     * Base legal. Legítimo interesse não é permitido para dado sensível (LGPD art. 11).
+     * Valores: 'consent' | 'legal_obligation' | 'fraud_prevention'.
+     */
+    legalBasis: 'consent' | 'legal_obligation' | 'fraud_prevention';
+    /** URL da política de privacidade apresentada ao titular. */
+    privacyPolicyUrl: string;
+    /** Prazo de retenção em dias (0 = indefinido/não informado). */
+    retentionDays: number;
+}
+
 declare type ConsentFlow = 'verification' | 'registration';
 
 export declare interface ConsentInfo {
@@ -637,7 +665,12 @@ export declare class ForgotPasswordModal {
     private addStyles;
 }
 
-export declare type GestureKey = 'turn_left' | 'turn_right' | 'turn_up' | 'turn_down' | 'blink' | 'smile' | 'open_mouth';
+/**
+ * Chaves de gesto reconhecidas pelo backend real (case-insensitive; SDK
+ * normaliza para maiúsculo). Novos gestos podem aparecer sem impacto no SDK
+ * — o campo é `string` na runtime.
+ */
+export declare type GestureKey = 'LOOK_LEFT' | 'LOOK_RIGHT' | 'LOOK_UP' | 'LOOK_DOWN' | 'BLINK' | 'SMILE' | 'OPEN_MOUTH' | 'turn_left' | 'turn_right' | 'look_up' | 'look_down' | 'blink' | 'smile' | 'open_mouth';
 
 export declare interface GestureResponse {
     gesture_key: string;
@@ -669,6 +702,9 @@ export declare function getCachedCaptureSession(): CaptureSession | null;
  */
 export declare function getConfig(): Readonly<SDKConfig>;
 
+/** Retorna os dados de consentimento configurados (ou os defaults conservadores). */
+export declare function getConsent(): Consent;
+
 /**
  * Retorna o ambiente atual configurado.
  */
@@ -769,9 +805,18 @@ export declare function isAdvancedDetectionAvailable(): boolean;
 export declare function isInitialized(): boolean;
 
 export declare interface LivenessChallenge {
-    challenge_id: string;
+    /**
+     * ID do desafio. **Opcional no contrato v1.4.x** — o backend real rastreia
+     * o desafio pelo `session_id` e não devolve `challenge_id` no payload.
+     * Mantido opcional para consumidores que ainda dependem do valor.
+     */
+    challenge_id?: string;
     gestures: ChallengeGesture[];
+    /** Data ISO derivada de `expires_in` (segundos) ou legado `expires_at`. */
     expires_at?: string;
+    /** Segundos até expirar (contrato v1.4.x). */
+    expires_in?: number;
+    language?: string;
 }
 
 export declare interface LivenessChallengeResult {
@@ -1310,7 +1355,7 @@ export declare const registerPersonWithoutFace: (personData: {
 /**
  * Data de lançamento da versão atual
  */
-export declare const RELEASE_DATE = "2026-09-03";
+export declare const RELEASE_DATE = "2026-09-05";
 
 declare interface RequestChallengeWithSessionParams {
     applicationToken: string;
@@ -1367,16 +1412,33 @@ declare interface ResolvedTheme {
 }
 
 /**
- * Orquestra o fluxo completo:
+ * Orquestra:
  * 1. Abre `capture/session`
- * 2. Pede `liveness/challenge` (sequência sorteada pelo servidor)
+ * 2. Pede `liveness/challenge` (backend sorteia)
  * 3. Delega a coleta de frames ao consumidor gesto a gesto
- * 4. Submete a resposta para o servidor validar
+ * 4. **Retorna a coleta** para o consumidor submeter no pipeline dele.
  *
- * Retry: em 410 no submit, reabre a sessão + refaz o desafio + reenvia UMA vez.
- * Segunda falha propaga.
+ * Retry: em 410 ao abrir sessão/pedir desafio, reabre + refaz 1x. Segunda falha propaga.
+ *
+ * Nota: até 1.36.1 esta função chamava `submitLivenessChallenge` no fim, mas o
+ * endpoint não existe no backend real. NEO-427 removeu essa chamada. Quando
+ * NEO-428 identificar o endpoint real de submit, o consumidor pode usá-lo, ou
+ * uma variante `runLivenessChallengeAndSubmit` pode ser reintroduzida.
+ */
+export declare function runLivenessChallenge({ applicationToken, purpose, collectFramesForGesture, retryOnSessionExpired, }: RunLivenessChallengeParams): Promise<RunLivenessChallengeCollectResult>;
+
+/**
+ * Resultado da coleta orquestrada. NEO-427: NÃO submete os frames automaticamente
+ * (o endpoint de submit `/challenge/{id}/submit/` não existe no backend v1.4.x —
+ * devolve 404). O consumidor recebe as gestures coletadas e envia via seu próprio
+ * pipeline (ex.: `POST /auth/recognition/face/` com `challenge_response` no body).
  */
-export declare function runLivenessChallenge({ applicationToken, purpose, collectFramesForGesture, retryOnSessionExpired, }: RunLivenessChallengeParams): Promise<LivenessChallengeResult>;
+export declare interface RunLivenessChallengeCollectResult {
+    sessionId: string;
+    challenge: LivenessChallenge;
+    /** Frames coletados por gesto, na ordem sorteada pelo servidor. */
+    capturedGestures: GestureResponse[];
+}
 
 export declare interface RunLivenessChallengeParams {
     applicationToken: string;
@@ -1384,10 +1446,10 @@ export declare interface RunLivenessChallengeParams {
     /**
      * 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.
+     * cumprido — só coleta; 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. */
+    /** Se true, quando o servidor devolver 410 na abertura do desafio, reabre sessão + refaz 1x. */
     retryOnSessionExpired?: boolean;
 }
 
@@ -1405,6 +1467,7 @@ declare interface SDKConfig {
     theme: SDKTheme;
     locale: string;
     resolvedTheme: ResolvedTheme | null;
+    consent: Consent;
 }
 
 /**
@@ -1456,6 +1519,11 @@ export declare interface SDKInitOptions {
      * Locale da UI. Padrão `pt-BR`.
      */
     locale?: string;
+    /**
+     * Dados de consentimento LGPD. Se omitido, o SDK usa defaults conservadores
+     * e emite `console.warn` uma única vez.
+     */
+    consent?: Consent;
 }
 
 export declare type SDKRadius = 8 | 16 | 24;
@@ -1583,14 +1651,18 @@ export declare interface StartOnboardingOptions {
 }
 
 /**
- * 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.
+ * @deprecated NEO-427: o endpoint `POST /liveness/challenge/{id}/submit/` NÃO
+ * EXISTE no backend v1.4.x — devolve 404. `runLivenessChallenge` não chama mais
+ * esta função. Mantida apenas para consumidores que ainda dependem do símbolo;
+ * será removida quando o endpoint real de submit for identificado (NEO-428).
+ *
+ * Continua tentando o path histórico e propaga o erro do servidor.
  */
 export declare function submitLivenessChallenge({ challengeId, sessionId, applicationToken, gestures, }: SubmitLivenessChallengeParams): Promise<LivenessChallengeResult>;
 
 export declare interface SubmitLivenessChallengeParams {
-    challengeId: string;
+    /** Opcional no v1.4.x — backend rastreia via session_id. */
+    challengeId?: string;
     sessionId: string;
     applicationToken: string;
     gestures: GestureResponse[];
@@ -1650,7 +1722,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.36.1";
+export declare const VERSION = "1.37.0";
 
 /**
  * Executa `fn(sessionId)`. Se o servidor devolver 410 (sessão consumida/expirada),

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

@@ -4534,6 +4534,12 @@ function injectScopedStyles(id, css) {
   document.head.appendChild(style);
 }
 const __vite_import_meta_env__ = {};
+const DEFAULT_CONSENT = {
+  purpose: "authentication",
+  legalBasis: "fraud_prevention",
+  privacyPolicyUrl: "",
+  retentionDays: 0
+};
 const ENVIRONMENT_URLS = {
   development: "http://localhost:8000",
   sandbox: "https://sandbox-core.neofaceid.com",
@@ -4554,12 +4560,25 @@ function makeDefaultConfig() {
     radius: DEFAULT_RADIUS,
     theme: DEFAULT_THEME,
     locale: DEFAULT_LOCALE,
-    resolvedTheme: null
+    resolvedTheme: null,
+    consent: { ...DEFAULT_CONSENT }
   };
 }
 let globalConfig = makeDefaultConfig();
+let consentWarningShown = false;
 function init(options = {}) {
-  const { environment, baseUrl, applicationToken, appName, accent, radius, theme, locale } = options;
+  const { environment, baseUrl, applicationToken, appName, accent, radius, theme, locale, consent } = options;
+  if (consent) {
+    globalConfig.consent = consent;
+  } else {
+    globalConfig.consent = { ...DEFAULT_CONSENT };
+    if (!consentWarningShown) {
+      console.warn(
+        "[NeoFaceID SDK] Consentimento não configurado em init(). Usando valores padrão (fraud_prevention). Configure consent: { purpose, legalBasis, privacyPolicyUrl, retentionDays }."
+      );
+      consentWarningShown = true;
+    }
+  }
   if (baseUrl) {
     globalConfig.baseUrl = baseUrl;
     globalConfig.environment = "custom";
@@ -4659,6 +4678,9 @@ function getResolvedThemeMode() {
 function getLocale() {
   return globalConfig.locale;
 }
+function getConsent() {
+  return { ...globalConfig.consent };
+}
 const getApiBaseUrl = () => getBaseUrl();
 const REQUEST_TIMEOUT = 1e4;
 const ensureSecureContext = () => {
@@ -11177,8 +11199,8 @@ const biometricDetection = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.
   initializeBiometricDetection,
   isAdvancedDetectionAvailable
 }, Symbol.toStringTag, { value: "Module" }));
-const VERSION = "1.36.1";
-const RELEASE_DATE = "2026-09-03";
+const VERSION = "1.37.0";
+const RELEASE_DATE = "2026-09-05";
 let cachedSession = null;
 function getCachedCaptureSession() {
   return cachedSession;
@@ -11305,18 +11327,33 @@ async function requestLivenessChallenge({
   }
   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) {
+  const rawSteps = payload == null ? void 0 : payload.steps;
+  const rawGestures = payload == null ? void 0 : payload.gestures;
+  const source = Array.isArray(rawSteps) ? rawSteps : Array.isArray(rawGestures) ? rawGestures : void 0;
+  if (!source || source.length === 0) {
     throw new NeoFaceError(
-      "Resposta inválida ao solicitar desafio (campos ausentes)",
+      "Resposta inválida ao solicitar desafio (steps/gestures ausentes)",
       ErrorType.API_ERROR
     );
   }
+  const gestures = source.map((s, i) => {
+    const item = s;
+    const gestureRaw = item.gesture ?? item.gesture_key;
+    return {
+      index: typeof item.order === "number" ? item.order : typeof item.index === "number" ? item.index : i + 1,
+      gesture_key: gestureRaw ?? "",
+      instruction: typeof item.instruction === "string" ? item.instruction : void 0,
+      instruction_i18n: item.instruction_i18n && typeof item.instruction_i18n === "object" ? item.instruction_i18n : void 0
+    };
+  });
+  const expiresIn = typeof (payload == null ? void 0 : payload.expires_in) === "number" ? payload.expires_in : void 0;
+  const expiresAt = typeof (payload == null ? void 0 : payload.expires_at) === "string" && payload.expires_at.length > 0 ? payload.expires_at : expiresIn !== void 0 ? new Date(Date.now() + expiresIn * 1e3).toISOString() : void 0;
   return {
-    challenge_id: challengeId,
+    challenge_id: typeof (payload == null ? void 0 : payload.challenge_id) === "string" ? payload.challenge_id : void 0,
     gestures,
-    expires_at: payload == null ? void 0 : payload.expires_at
+    expires_at: expiresAt,
+    expires_in: expiresIn,
+    language: typeof (payload == null ? void 0 : payload.language) === "string" ? payload.language : void 0
   };
 }
 async function requestLivenessChallengeWithSession({
@@ -11342,22 +11379,26 @@ async function submitLivenessChallenge({
   applicationToken,
   gestures
 }) {
+  console.warn(
+    "[NeoFaceID SDK] submitLivenessChallenge está deprecated (NEO-427): o endpoint /liveness/challenge/{id}/submit/ não existe no backend v1.4.x. Coleta os frames via runLivenessChallenge e envie via seu próprio pipeline até que NEO-428 defina o endpoint real."
+  );
   if (!applicationToken) {
     throw new NeoFaceError(
       "applicationToken é obrigatório para submeter desafio",
       ErrorType.INVALID_TOKEN
     );
   }
-  if (!challengeId || !sessionId) {
+  if (!sessionId) {
     throw new NeoFaceError(
-      "challenge_id e session_id são obrigatórios para submeter desafio",
+      "session_id é obrigatório 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/`;
+  const idSuffix = challengeId ? `${encodeURIComponent(challengeId)}/submit/` : "submit/";
+  const url = `${getBaseUrl()}/api/v1/auth/liveness/challenge/${idSuffix}`;
   let response;
   try {
     response = await fetch(url, {
@@ -11408,18 +11449,13 @@ async function runLivenessChallenge({
       sessionId: session.session_id,
       applicationToken
     });
-    const gestures = [];
+    const capturedGestures = [];
     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 });
+      capturedGestures.push({ gesture_key: String(g.gesture_key), images });
     }
-    return submitLivenessChallenge({
-      challengeId: challenge.challenge_id,
-      sessionId: session.session_id,
-      applicationToken,
-      gestures
-    });
+    return { sessionId: session.session_id, challenge, capturedGestures };
   };
   try {
     return await attempt();
@@ -12924,12 +12960,6 @@ function AuthorizeModalComponent({
         });
         if (stream) stream.getTracks().forEach((t) => t.stop());
         stream = null;
-        if (result.success === false || result.liveness_passed === false) {
-          setFailureCode("LIVENESS_LOW");
-          setFailureAt(/* @__PURE__ */ new Date());
-          setPhase("failure");
-          return;
-        }
         setPhase("success");
         if (onSuccess) onSuccess(result);
       } catch (err) {
@@ -14283,6 +14313,7 @@ export {
   getBaseUrl,
   getCachedCaptureSession,
   getConfig,
+  getConsent,
   getEnvironment,
   getLocale,
   getRadius,