@neofaceid/web-sdk 1.40.2 → 1.41.1

package/README.md

@@ -1,6 +1,34 @@
 # NeoFace ID SDK Web
 
-SDK para captura e reconhecimento facial em aplicações web.
+SDK JavaScript/TypeScript (React) para autenticação, cadastro e verificação
+facial em aplicações web, publicado no npm como
+[`@neofaceid/web-sdk`](https://www.npmjs.com/package/@neofaceid/web-sdk).
+
+Veja o [`CHANGELOG.md`](CHANGELOG.md) para o histórico de versões.
+
+## Índice
+
+- [Instalação](#instalação)
+- [Requisitos do consumer](#requisitos-do-consumer)
+- [Início rápido](#início-rápido)
+- [LGPD e consentimento](#lgpd-e-consentimento)
+- [Fluxos principais](#fluxos-principais)
+  - [Login facial (`startFaceLogin`)](#login-facial-startfacelogin)
+  - [Login por mão / automático](#login-por-mão--automático-starthandlogin-startautologin)
+  - [Cadastro biométrico (`startBiometricRegistration`)](#cadastro-biométrico-startbiometricregistration)
+  - [Captura de liveness (`startLivenessCapture`)](#captura-de-liveness-startlivenesscapture)
+  - [Onboarding completo (`startOnboarding`)](#onboarding-completo-startonboarding)
+  - [Captura de documento (`startDocumentCapture`)](#captura-de-documento-startdocumentcapture)
+  - [Autorização por biometria (`authorize` / `authorizeOperation`)](#autorização-por-biometria-authorize--authorizeoperation)
+  - [Classe `NeoFaceID` (`proofOfLife` e afins)](#classe-neofaceid-proofoflife-e-afins)
+- [Tratamento de erros](#tratamento-de-erros)
+- [Componentes React exportados](#componentes-react-exportados)
+- [Sessão de captura e desafio de liveness (baixo nível)](#sessão-de-captura-e-desafio-de-liveness-baixo-nível)
+- [Trilha de consentimento (auditoria LGPD)](#trilha-de-consentimento-auditoria-lgpd)
+- [API de baixo nível (`api.ts`)](#api-de-baixo-nível-apits)
+- [Versão do SDK](#versão-do-sdk)
+- [Compatibilidade](#compatibilidade)
+- [Licença](#licença)
 
 ## Instalação
 
@@ -8,318 +36,509 @@ SDK para captura e reconhecimento facial em aplicações web.
 npm install @neofaceid/web-sdk
 ```
 
-## Uso Básico
-
-```javascript
-import { start } from '@neofaceid/web-sdk';
-
-// Inicialize o SDK com seu token de aplicação
-start('seu-token-de-aplicacao', {
-  onSuccess: (user) => {
-    console.log('Usuário autenticado:', user);
-    // user contém: { name, email, documentId }
+`react` e `react-dom` são `peerDependencies` (`^18.0.0 || ^19.0.0`) — o
+projeto consumidor precisa já ter as duas instaladas.
+
+## Requisitos do consumer
+
+Antes de usar qualquer fluxo do SDK, confirme os itens abaixo no projeto que
+vai consumi-lo:
+
+1. **HTTPS.** O SDK acessa a câmera via `getUserMedia`, que exige contexto
+   seguro. `localhost` funciona em desenvolvimento; produção precisa de
+   HTTPS (recomendado configurar HSTS no servidor).
+2. **`face-api.js` já vem como dependência transitiva** do
+   `@neofaceid/web-sdk` (não precisa instalar de novo) — mas os **pesos do
+   modelo (weights) não são publicados no bundle** e precisam ser
+   auto-hospedados pelo consumer. O SDK carrega os modelos em runtime via
+   `faceapi.nets.<rede>.loadFromUri('/models')`, ou seja, relativos à própria
+   origem do seu app. Baixe os arquivos abaixo do repositório oficial de
+   pesos do face-api.js e sirva-os em `public/models/` (ou equivalente do seu
+   bundler) para que fiquem acessíveis em `/models/*`:
+   - `tiny_face_detector_model-weights_manifest.json` +
+     `tiny_face_detector_model-shard1`
+   - `face_landmark_68_model-weights_manifest.json` +
+     `face_landmark_68_model-shard1`
+
+   Sem esses arquivos em `/models`, qualquer fluxo que dependa de detecção
+   facial local (blink detection do liveness, `biometricDetection`) falha ao
+   carregar o modelo.
+3. **Ícone/logo do SDK não precisa de asset externo.** Desde a 1.29.0 a marca
+   é renderizada via SVG inline (`src/assets/brand.ts`) — não há mais PNG
+   para hospedar.
+4. **`applicationToken`** válido, obtido no painel administrativo do
+   NeoFace ID.
+5. **Ambiente correto configurado via `init`** — veja
+   [Início rápido](#início-rápido). O default (sem `init`) é `sandbox`.
+
+## Início rápido
+
+```ts
+import { init } from '@neofaceid/web-sdk';
+
+init({
+  environment: 'sandbox', // 'development' | 'sandbox' | 'production'
+  applicationToken: 'seu-token-de-aplicacao',
+  appName: 'Minha Aplicação', // exibido no topo dos modais
+  consent: {
+    purpose: 'authentication',
+    legalBasis: 'fraud_prevention', // 'consent' | 'legal_obligation' | 'fraud_prevention'
+    privacyPolicyUrl: 'https://minha-app.com/privacidade',
+    retentionDays: 0,
   },
-  onError: (code, message) => {
-    console.error('Erro:', code, message);
-  }
 });
 ```
 
-## Versão
+Mapeamento de `environment` → URL base ([`src/config.ts`](src/config.ts)):
 
-O SDK segue o padrão de versionamento semântico (SemVer):
+| `environment`  | URL base                             |
+| -------------- | ------------------------------------ |
+| `development`  | `http://localhost:8000`              |
+| `sandbox`      | `https://sandbox-core.neofaceid.com` |
+| `production`   | `https://core.neofaceid.com.br`      |
 
-```javascript
-import { VERSION, RELEASE_DATE } from '@neofaceid/web-sdk';
+Use `baseUrl` em vez de `environment` para apontar para uma URL customizada
+(tem precedência sobre `environment`). Outras opções de `init` — tema visual
+do integrador:
 
-console.log(`Usando NeoFace ID SDK versão ${VERSION} (lançada em ${RELEASE_DATE})`);
+```ts
+init({
+  accent: '#0059C4', // cor do botão primário; contraste < 4.5 vs branco = fallback + warn
+  radius: 16, // 8 | 16 | 24, fallback 16 se fora da lista
+  theme: 'auto', // 'light' | 'dark' | 'auto' (respeita prefers-color-scheme)
+  locale: 'pt-BR',
+});
 ```
 
-### Histórico de Versões
+Getters correspondentes: `getBaseUrl()`, `getEnvironment()`,
+`getApplicationToken()`, `getConsent()`, `isInitialized()`, `getConfig()`,
+`getAppName()`, `getAccent()`, `getRadius()`, `getTheme()`, `getLocale()`,
+`getResolvedThemeMode()`, e o mapa `ENVIRONMENT_URLS`.
+
+## LGPD e consentimento
+
+Todo fluxo que abre a câmera (`start`, `startBiometricRegistration`,
+`startLivenessCapture`, `startFaceLogin`, `startHandLogin`, `startAutoLogin`,
+`startOnboarding`, `startDocumentCapture`, `authorizeOperation`, `authorize`)
+chama internamente `requestConsent({ appName, flow })` **antes** de qualquer
+`getUserMedia()`. Se o titular recusar, o callback de erro recebe
+`NeoFaceError` com `ErrorType.CONSENT_DENIED` e a câmera nunca é aberta.
+
+Configure a base legal uma vez em `init({ consent })` (ver
+[Início rápido](#início-rápido)) — omitir gera `console.warn` e usa defaults
+conservadores (`fraud_prevention`, sem URL de política, retenção
+indefinida). Também é possível chamar `requestConsent` diretamente para UI
+customizada:
+
+```ts
+import { requestConsent, DEFAULT_CONSENT_INFO } from '@neofaceid/web-sdk';
+
+const accepted = await requestConsent({
+  ...DEFAULT_CONSENT_INFO,
+  appName: 'Minha Aplicação',
+  flow: 'registration', // 'verification' (imagem descartada) | 'registration' (guarda vetor matemático)
+});
+```
 
-| Versão | Data | Mudanças |
-|--------|------|----------|
-| 1.0.0 | 2023-06-15 | Lançamento inicial do SDK |
+Toda decisão de consentimento pode ser auditada — veja
+[Trilha de consentimento](#trilha-de-consentimento-auditoria-lgpd).
 
-## Parâmetros
+## Fluxos principais
 
-### applicationToken (string)
-Token de autenticação da sua aplicação. Obtenha este token no painel de administração do NeoFace ID.
+### Login facial (`startFaceLogin`)
 
-### callbacks (object)
+Overlay minimalista estilo Face ID (não mostra a câmera na tela).
 
-#### onSuccess (function)
-Chamado quando o reconhecimento facial é bem-sucedido.
-- Parâmetros: `user` (object) - Contém `name`, `email` e `documentId` do usuário reconhecido.
+```ts
+import { startFaceLogin } from '@neofaceid/web-sdk';
 
-#### onError (function)
-Chamado quando ocorre um erro durante o processo.
-- Parâmetros:
-  - `code` (string) - Código do erro
-  - `message` (string) - Mensagem descritiva do erro
+await startFaceLogin({
+  applicationToken: 'seu-token-de-aplicacao',
+  appName: 'Minha Aplicação',
+  onSuccess: result => console.log('Login ok:', result),
+  onError: err => console.error(err.type, err.getFriendlyMessage()),
+  onCancel: () => console.log('Usuário cancelou'),
+  onFallbackRequest: () => {
+    /* opcional — default já abre EmailPasswordModal */
+  },
+});
+```
 
-### Códigos de Erro
+### Login por mão / automático (`startHandLogin`, `startAutoLogin`)
 
-| Código | Descrição |
-|--------|-----------|
-| `TOKEN_VALIDATION_ERROR` | Token de aplicação inválido ou expirado |
-| `NO_CAMERA` | Câmera não disponível ou permissão negada |
-| `FACE_NOT_DETECTED` | Nenhum rosto detectado na imagem |
-| `MULTIPLE_FACES` | Múltiplos rostos detectados na imagem |
-| `FACE_NOT_CENTERED` | Rosto não está centralizado no frame |
-| `LIVENESS_CHECK_FAILED` | Verificação de vivacidade falhou |
-| `RECOGNITION_FAILED` | Falha no reconhecimento facial |
-| `NETWORK_ERROR` | Erro de conexão com o servidor |
-| `TIMEOUT` | Tempo limite excedido durante o processo |
+Mesma assinatura de `startFaceLogin` (`BiometricLoginOptions`); `startAutoLogin`
+detecta rosto ou mão automaticamente.
 
-## Customização
+```ts
+import { startHandLogin, startAutoLogin } from '@neofaceid/web-sdk';
 
-O modal de captura facial pode ser customizado através de CSS. Adicione as seguintes classes ao seu CSS:
+await startHandLogin({ applicationToken, onSuccess, onError });
+await startAutoLogin({ applicationToken, onSuccess, onError });
+```
 
-```css
-/* Container principal */
-#neoface-modal-container {
-  /* Estilos para o container */
-}
+### Cadastro biométrico (`startBiometricRegistration`)
 
-/* Modal */
-#neoface-modal-container .modal {
-  /* Estilos para o modal */
-}
+```ts
+import { startBiometricRegistration } from '@neofaceid/web-sdk';
 
-/* Botões */
-#neoface-modal-container .button {
-  /* Estilos para os botões */
-}
+startBiometricRegistration(
+  {
+    name: 'Maria Silva',
+    birth_date: '1990-05-20',
+    cpf: '12345678900',
+    email: 'maria@exemplo.com',
+    password: 'senha-forte',
+  },
+  'seu-token-de-aplicacao',
+  {
+    onSuccess: result => console.log('Cadastro concluído:', result.person_id),
+    onError: err => console.error(err.type, err.message),
+  },
+  { appName: 'Minha Aplicação' }
+);
+```
 
-/* Mensagens */
-#neoface-modal-container .message {
-  /* Estilos para as mensagens */
-}
+### Captura de liveness (`startLivenessCapture`)
 
-/* Guia de posicionamento */
-#neoface-modal-container .guide {
-  /* Estilos para o guia de posicionamento */
-}
+Só a captura de fotos com prova de vida, sem cadastro — útil quando o
+consumer já tem seu próprio pipeline de reconhecimento.
+
+```ts
+import { startLivenessCapture } from '@neofaceid/web-sdk';
+
+startLivenessCapture(
+  'seu-token-de-aplicacao',
+  {
+    onSuccess: (photos: Blob[]) => console.log(`${photos.length} fotos capturadas`),
+    onError: err => console.error(err.type, err.message),
+    onCancel: () => console.log('Usuário fechou o modal'),
+  },
+  { appName: 'Minha Aplicação' }
+);
 ```
 
-## Requisitos de Segurança
+### Onboarding completo (`startOnboarding`)
 
-### HTTPS
-O SDK requer uma conexão HTTPS para funcionar. Em ambiente de desenvolvimento, você pode usar `localhost`.
+Orquestra: validação do link → consentimento → captura de rosto e
+documento → conclusão no backend.
 
-### Permissões
-O SDK solicita permissão para acessar a câmera do dispositivo. Esta permissão é essencial para o funcionamento do reconhecimento facial.
+```ts
+import { startOnboarding } from '@neofaceid/web-sdk';
 
-### HSTS
-Recomendamos configurar HTTP Strict Transport Security (HSTS) no servidor para garantir que todas as conexões sejam feitas via HTTPS.
+await startOnboarding({
+  applicationToken: 'seu-token-de-aplicacao',
+  onboardingToken: 'token-do-link-de-onboarding',
+  appName: 'Minha Aplicação',
+  onSuccess: result => console.log('Onboarding concluído:', result.person_id),
+  onError: err => console.error(err.type, err.message),
+  onCancel: () => console.log('Usuário cancelou'),
+});
+```
 
-### Privacidade
-O SDK não armazena dados biométricos localmente. Todas as imagens são processadas em tempo real e descartadas após o reconhecimento.
+### Captura de documento (`startDocumentCapture`)
 
-## Notas de Performance
+```ts
+import { startDocumentCapture } from '@neofaceid/web-sdk';
 
-- **Resolução Adaptativa**: O SDK ajusta automaticamente a resolução da câmera com base nas capacidades do dispositivo.
-- **Compressão JPEG**: As imagens são comprimidas antes do envio para otimizar o uso de banda.
-- **Timeout**: O processo de reconhecimento tem um timeout de 10 segundos para evitar que o usuário fique aguardando indefinidamente.
+const result = await startDocumentCapture({
+  appName: 'Minha Aplicação',
+  preSelectedDocument: 'CNH', // 'RG' | 'CNH' | 'CPF' — pula a tela de seleção
+  useBackCamera: true,
+});
 
-## Compatibilidade
+if (result.success) {
+  console.log('Frente:', result.frontImage);
+  console.log('Verso:', result.backImage); // null se o documento não tem verso
+}
+```
 
-### Navegadores Suportados
-- Chrome 60+
-- Firefox 55+
-- Safari 11+
-- Edge 79+
+### Autorização por biometria (`authorize` / `authorizeOperation`)
 
-### Responsividade
-O SDK é totalmente responsivo e funciona em dispositivos desktop e mobile. Em dispositivos móveis, o modal ocupa a tela inteira para uma melhor experiência do usuário.
+`authorize` é a API atual (protocolo Focus Frame, orquestra
+`runLivenessChallenge` — o servidor decide a sequência de gestos e a
+aprovação final):
 
-## Integração com .NET Framework
+```ts
+import { authorize } from '@neofaceid/web-sdk';
 
-O NeoFace ID SDK Web pode ser facilmente integrado em aplicações web desenvolvidas com .NET Framework 4.8 ou superior. Siga os passos abaixo para implementar a autenticação facial em seu projeto ASP.NET:
+await authorize({
+  applicationToken: 'seu-token-de-aplicacao',
+  subject: '12345678900', // CPF, e-mail ou id opaco do titular
+  appName: 'Minha Aplicação',
+  amount: 1250, // exibido como "R$ 1.250,00"
+  challenges: 2, // 0-3, teto sugerido; servidor decide a sequência real
+  onChallengeStart: (gesture, index, total) => console.log(gesture, index, total),
+  onSuccess: collectResult => {
+    // envie collectResult.capturedGestures ao seu próprio endpoint de recognition
+  },
+  onError: err => console.error(err.type, err.message),
+  onCancel: () => console.log('Usuário cancelou'),
+});
+```
 
-### 1. Instalação via NuGet
+`authorizeOperation` é a variante legada, mais baixo nível (captura 4 fotos
+com gestos fixos e chama `recognizeByPurpose('AUTHORIZATION')` diretamente):
 
-Adicione o pacote ao seu projeto .NET:
+```ts
+import { authorizeOperation } from '@neofaceid/web-sdk';
 
-```powershell
-Install-Package NeoFaceId.WebSdk
+const result = await authorizeOperation('seu-token-de-aplicacao', '12345678900', {
+  appName: 'Minha Aplicação',
+  onProgress: (step, total, instruction) => console.log(instruction, step, total),
+  onPhotoTaken: (n, blob) => console.log('Foto', n, blob),
+});
 ```
 
-Ou adicione a referência ao seu arquivo `.csproj`:
+### Classe `NeoFaceID` (`proofOfLife` e afins)
 
-```xml
-<PackageReference Include="NeoFaceId.WebSdk" Version="1.0.2" />
-```
+`NeoFaceID` reúne operações que não têm (ainda) uma função `start*`
+dedicada: prova de vida com gravação de vídeo, captura de múltiplos frames,
+login com assinatura para integrações externas, registro de aplicação e
+registro de documento pós-cadastro.
+
+```ts
+import { NeoFaceID } from '@neofaceid/web-sdk';
+
+const sdk = new NeoFaceID({ appToken: 'seu-token-de-aplicacao' });
 
-### 2. Configuração no Web.config
+// Prova de vida: grava vídeo curto, envia para o backend, faz polling do resultado
+const proof = await sdk.proofOfLife({
+  videoDurationMs: 3000,
+  onRecordingProgress: progress => console.log(`Gravando: ${progress}%`),
+  onTaskStatusChange: (status, progress) => console.log(status, progress),
+});
+if (proof.success && proof.isLive) {
+  console.log('Liveness score:', proof.livenessScore);
+  console.log('Dados da pessoa:', proof.personalData);
+}
 
-Adicione a configuração do token no seu arquivo `Web.config`:
+// Login com assinatura (integrações externas — ex.: sistemas que já geram HMAC)
+const sdkExterno = new NeoFaceID({
+  appToken: 'seu-token-de-aplicacao',
+  signature: signatureFromBackend, // HMAC-SHA256 hex, mínimo 64 chars
+  sessionData: { email: 'user@exemplo.com', cpf: '12345678900', sessionId: 'session-uuid' },
+});
+const frames = await sdkExterno.captureFaceFrames({ numFrames: 5, livenessCheck: true });
+const login = await sdkExterno.loginRecognition({
+  biometricData: frames,
+  typeOfIdentification: 'FACE',
+  purpose: 'LOGIN',
+});
 
-```xml
-<configuration>
-  <appSettings>
-    <add key="NeoFaceId:ApplicationToken" value="seu-token-de-aplicacao" />
-  </appSettings>
-</configuration>
+// Registro de documento para pessoa já cadastrada
+const docResult = await sdk.registerDocumentByImage(personId, userJwtToken);
+console.log('Task ID:', docResult.taskId);
 ```
 
-### 3. Implementação no Código
-
-#### No Controller (C#)
-
-```csharp
-using System.Web.Mvc;
-using NeoFaceId.WebSdk;
-
-public class AuthenticationController : Controller
-{
-    private readonly string _applicationToken;
-
-    public AuthenticationController()
-    {
-        _applicationToken = System.Configuration.ConfigurationManager.AppSettings["NeoFaceId:ApplicationToken"];
-    }
-
-    public ActionResult Index()
-    {
-        return View();
-    }
-
-    [HttpPost]
-    public JsonResult AuthenticateUser(string name, string email, string documentId)
-    {
-        // Processar a autenticação do usuário
-        // Este método é chamado após o reconhecimento facial bem-sucedido
-        
-        // Exemplo: Criar sessão do usuário
-        Session["UserName"] = name;
-        Session["UserEmail"] = email;
-        Session["UserDocumentId"] = documentId;
-        
-        return Json(new { success = true });
-    }
+## Tratamento de erros
+
+Toda falha do SDK (nos fluxos novos) é uma instância de `NeoFaceError`, com
+`error.type` (`ErrorType`) e `error.getFriendlyMessage()` para exibir ao
+usuário final sem termos técnicos:
+
+```ts
+import { NeoFaceError, ErrorType } from '@neofaceid/web-sdk';
+
+function onError(err: NeoFaceError) {
+  if (err.type === ErrorType.CONSENT_DENIED) {
+    // usuário recusou o consentimento — não abriu câmera
+  }
+  alert(err.getFriendlyMessage());
 }
 ```
 
-#### Na View (Razor)
+> Desde a 1.41.0, `start`, `startBiometricRegistration` e
+> `startLivenessCapture` também usam `onError(err: NeoFaceError)` — antes
+> usavam `onError(code: string, message: string)`. Veja o `CHANGELOG.md`
+> (breaking change) se seu código ainda depende da assinatura antiga.
+
+| `ErrorType`             | Quando ocorre                                                  |
+| ----------------------- | --------------------------------------------------------------- |
+| `NETWORK`               | Erro de conexão com o servidor                                  |
+| `INVALID_TOKEN`         | `applicationToken` inválido ou expirado                         |
+| `RECOGNITION_FAILED`    | Falha no reconhecimento facial                                  |
+| `LOGIN_FAILED`          | Falha no login biométrico                                       |
+| `VALIDATION_ERROR`      | Dados inválidos ou rosto não detectado corretamente              |
+| `API_ERROR`             | Erro genérico de API (400/500)                                  |
+| `PERSON_NOT_FOUND`      | Pessoa não encontrada na base                                   |
+| `INITIALIZATION_ERROR`  | Falha ao inicializar um fluxo                                   |
+| `CAMERA_ERROR`          | Erro genérico de câmera                                          |
+| `NO_CAMERA`             | Câmera não disponível ou permissão negada                        |
+| `CAPTURE_ERROR`         | Falha durante a captura de imagem/vídeo                         |
+| `NOT_FOUND`             | Recurso não encontrado                                           |
+| `UNKNOWN`               | Erro não categorizado                                            |
+| `CONSENT_DENIED`        | Titular recusou o consentimento LGPD                             |
+| `LIVENESS_BLINK_MISSING`| Piscada real (EAR) não detectada na janela de liveness (3s)      |
+
+## Componentes React exportados
+
+Para quem prefere montar a própria árvore React em vez de usar as funções
+`start*` (que já cuidam de criar/desmontar o container):
+
+```tsx
+import {
+  FaceCaptureModal,
+  BiometricRegistrationModal,
+  ConsentModal,
+  EmailPasswordModal,
+  ForgotPasswordModal,
+  BiometricStatusOverlay,
+  FallbackPrompt,
+  DocumentCaptureModal,
+} from '@neofaceid/web-sdk';
+```
 
-```html
-@{
-    ViewBag.Title = "Autenticação Facial";
-}
+Todos recebem `accessToken`/`applicationToken`, `onSuccess`/`onError` e
+`onClose` conforme o fluxo — consulte a assinatura de cada `start*`
+correspondente acima para as props equivalentes.
 
-<div class="container">
-    <h2>Autenticação Facial</h2>
-    
-    <button id="startFaceAuth" class="btn btn-primary">Iniciar Autenticação Facial</button>
-    
-    <div id="authResult"></div>
-</div>
-
-@section Scripts {
-    <script src="~/Scripts/neoface-id-sdk.js"></script>
-    <script>
-        document.getElementById('startFaceAuth').addEventListener('click', function() {
-            // Inicializar o SDK com o token da aplicação
-            NeoFaceId.start('@System.Configuration.ConfigurationManager.AppSettings["NeoFaceId:ApplicationToken"]', {
-                onSuccess: function(user) {
-                    // Enviar dados do usuário para o servidor
-                    $.ajax({
-                        url: '@Url.Action("AuthenticateUser", "Authentication")',
-                        type: 'POST',
-                        data: {
-                            name: user.name,
-                            email: user.email,
-                            documentId: user.documentId
-                        },
-                        success: function(response) {
-                            if (response.success) {
-                                document.getElementById('authResult').innerHTML = 
-                                    '<div class="alert alert-success">Autenticação bem-sucedida!</div>';
-                                // Redirecionar para a página principal após autenticação
-                                setTimeout(function() {
-                                    window.location.href = '@Url.Action("Index", "Home")';
-                                }, 1500);
-                            }
-                        },
-                        error: function() {
-                            document.getElementById('authResult').innerHTML = 
-                                '<div class="alert alert-danger">Erro ao processar autenticação no servidor.</div>';
-                        }
-                    });
-                },
-                onError: function(code, message) {
-                    document.getElementById('authResult').innerHTML = 
-                        '<div class="alert alert-danger">Erro: ' + message + '</div>';
-                }
-            });
-        });
-    </script>
-}
+## Sessão de captura e desafio de liveness (baixo nível)
+
+Usado internamente por `authorize`/`authorizeOperation`, mas exportado para
+quem monta o próprio orquestrador de liveness:
+
+```ts
+import {
+  openCaptureSession,
+  requestLivenessChallenge,
+  runLivenessChallenge,
+} from '@neofaceid/web-sdk';
+
+const session = await openCaptureSession({
+  applicationToken: 'seu-token-de-aplicacao',
+  purpose: 'authorization', // 'login' | 'onboarding' | 'authorization' | 'identification' | 'liveness'
+});
+
+const challenge = await requestLivenessChallenge({
+  applicationToken: 'seu-token-de-aplicacao',
+  sessionId: session.session_id,
+});
+
+// Ou o fluxo completo (session → challenge → coleta via callback → retorno):
+const collected = await runLivenessChallenge({
+  applicationToken: 'seu-token-de-aplicacao',
+  purpose: 'login',
+  collectFramesForGesture: async (gesture, index, total) => {
+    // capture o(s) frame(s) correspondente(s) ao gesto e retorne os Blobs
+    return [] as Blob[];
+  },
+});
 ```
 
-### 4. Personalização do Modal
+## Trilha de consentimento (auditoria LGPD)
 
-Para personalizar a aparência do modal de captura facial, adicione os estilos CSS ao seu arquivo `Site.css` ou ao layout principal:
+```ts
+import { recordConsent, getConsentTrail, clearConsentTrail } from '@neofaceid/web-sdk';
 
-```css
-/* Estilos para o modal de captura facial */
-#neoface-modal-container .modal {
-    border-radius: 8px;
-    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
-}
+// Grava no localStorage apenas hash(userAgent+purpose+timestamp), timestamp,
+// finalidade, base legal e versão do SDK — zero PII. Usa por padrão o
+// `consent` configurado em `init()`; pode ser sobrescrito pontualmente:
+await recordConsent({ purpose: 'authentication', legalBasis: 'fraud_prevention' });
 
-#neoface-modal-container .button {
-    background-color: #007bff;
-    color: white;
-    border: none;
-    padding: 8px 16px;
-    border-radius: 4px;
-    cursor: pointer;
-}
+const trail = getConsentTrail(); // ConsentRecord[] — histórico local (máx. 100, FIFO)
+clearConsentTrail(); // limpa o histórico (ex.: logout)
+```
 
-#neoface-modal-container .button:hover {
-    background-color: #0069d9;
-}
+## API de baixo nível (`api.ts`)
+
+Funções que os fluxos `start*` já usam por baixo dos panos, expostas para
+integrações que precisam de controle fino sobre a chamada HTTP:
+
+```ts
+import {
+  validateToken,
+  validateOnboardingToken,
+  recognize,
+  recognizeBiometric,
+  simpleIdentification,
+  recognizeByPurpose,
+  loginWithBiometric,
+  loginWithEmail,
+  registerPersonWithoutFace,
+  registerPersonWithBiometric,
+  registerBiometric,
+  identifyPerson,
+  identifyPersonAsync,
+  checkUserExistence,
+  requestPasswordReset,
+  confirmPasswordReset,
+  completeOnboarding,
+  completeOnboardingWithData,
+} from '@neofaceid/web-sdk';
+
+await validateToken('seu-token-de-aplicacao'); // boolean
+await validateOnboardingToken('seu-token-de-aplicacao', 'token-do-onboarding'); // boolean
+
+await recognize(faceBlob, 'seu-token-de-aplicacao');
+await recognizeBiometric(faceBlob, 'seu-token-de-aplicacao', /* livenessCheck */ true, 0.8);
+await simpleIdentification('CPF', '12345678900', 'seu-token-de-aplicacao');
+await recognizeByPurpose(faceBlob, 'seu-token-de-aplicacao', 'LOGIN', 0.8);
+
+await loginWithBiometric(faceBlob, 'seu-token-de-aplicacao');
+await loginWithEmail('user@exemplo.com', 'senha', 'seu-token-de-aplicacao');
+
+await registerPersonWithoutFace(
+  { name: 'Maria Silva', birth_date: '1990-05-20', cpf: '12345678900', email: 'maria@exemplo.com', password: 'senha-forte' },
+  'seu-token-de-aplicacao'
+);
+await registerPersonWithBiometric(
+  { name: 'Maria Silva', birth_date: '1990-05-20', cpf: '12345678900', email: 'maria@exemplo.com', password: 'senha-forte' },
+  [faceBlob1, faceBlob2],
+  'seu-token-de-aplicacao'
+);
+await registerBiometric(personId, faceBlob, 'seu-token-de-aplicacao');
+
+await identifyPerson(faceBlob, 'seu-token-de-aplicacao');
+await identifyPersonAsync(faceBlob, 'seu-token-de-aplicacao', { maxRetries: 5, interval: 1000 });
+await checkUserExistence({ email: 'user@exemplo.com' }); // ou { cpf }
+
+await requestPasswordReset('user@exemplo.com', 'seu-token-de-aplicacao');
+await confirmPasswordReset('token-do-email', 'nova-senha');
+
+await completeOnboarding('seu-token-de-aplicacao', 'token-do-onboarding', faceBlob, documentBlob);
+await completeOnboardingWithData(
+  'seu-token-de-aplicacao',
+  'token-do-onboarding',
+  { name: 'Maria Silva', cpf: '12345678900' },
+  [faceBlob1, faceBlob2],
+  documentBlob
+);
 ```
 
-### 5. Considerações de Segurança
+Utilitário de performance para pré-carregar os modelos de detecção facial
+antes do primeiro uso (evita o delay do primeiro `loadFromUri` acontecer
+durante a interação do usuário):
+
+```ts
+import { preloadFaceDetectionModels } from '@neofaceid/web-sdk';
 
-- Sempre valide os dados recebidos do cliente no servidor
-- Utilize HTTPS para todas as comunicações
-- Armazene o token de aplicação de forma segura (nunca no código-fonte)
-- Considere implementar rate limiting para evitar abusos
-- Implemente logs de auditoria para rastrear tentativas de autenticação
+preloadFaceDetectionModels(); // dispara o carregamento de /models em background
+```
 
-## Deploy Automático
+## Versão do SDK
 
-O SDK é publicado automaticamente no NPM quando há push na branch `master`. O workflow:
+```ts
+import { VERSION, RELEASE_DATE } from '@neofaceid/web-sdk';
 
-1. **Valida** que está rodando na branch master
-2. **Verifica** se a versão atual já existe no NPM (idempotente)
-3. **Determina** o tipo de bump (patch/minor) baseado no commit message
-4. **Incrementa** a versão em todos os arquivos (package.json, package-lock.json, src/version.ts)
-5. **Commita** e faz push das mudanças com retry logic
-6. **Builda** o pacote
-7. **Publica** no NPM com retry automático em caso de falhas temporárias
+console.log(`NeoFace ID SDK ${VERSION} (${RELEASE_DATE})`);
+```
 
-### Convenções de Commit
+Histórico completo em [`CHANGELOG.md`](CHANGELOG.md).
 
-- `feat:` ou `feature:` → bump **minor** (1.0.0 → 1.1.0)
-- `fix:` ou `patch:` → bump **patch** (1.0.0 → 1.0.1)
-- Outros commits → bump **patch** por padrão
+## Compatibilidade
 
-### Idempotência
+### Navegadores suportados
 
-O workflow é idempotente: se a versão já existe no NPM, o deploy é pulado automaticamente sem erro.
+- Chrome 60+
+- Firefox 55+
+- Safari 11+
+- Edge 79+
 
-### Retry Logic
+### Responsividade
 
-- **Git sync**: 3 tentativas com backoff exponencial
-- **NPM publish**: 3 tentativas com backoff exponencial
-- **Erro 409**: Verifica se versão existe antes de falhar
+O SDK é totalmente responsivo. Em dispositivos móveis, os modais ocupam a
+tela inteira.
 
 ## Licença
 
-MIT  
+MIT