{"_id":"@autra-io/biometrics-sdk-web","name":"@autra-io/biometrics-sdk-web","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@autra-io/biometrics-sdk-web","version":"0.1.0","description":"Web SDK for Autra's hosted biometric selfie capture with liveness proof.","license":"Apache-2.0","type":"module","repository":{"type":"git","url":"git+https://github.com/autratech/autra-biometrics-sdk-web.git"},"homepage":"https://autra.io","keywords":["biometrics","selfie","liveness","kyc","autra","hosted-page","postmessage"],"publishConfig":{"access":"public"},"main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"sideEffects":false,"engines":{"node":">=20"},"scripts":{"clean":"rm -rf dist coverage .tsbuildinfo","lint":"eslint .","lint:fix":"eslint . --fix","format:check":"prettier --check .","format:write":"prettier --write .","typecheck":"tsc --noEmit","test":"vitest run","test:coverage":"vitest run --coverage","build":"tsup","size":"bash scripts/check-bundle-size.sh","pack:dry-run":"npm pack --dry-run","verify:install":"bash scripts/verify-pack-install.sh","ci":"npm run format:check && npm run lint && npm run typecheck && npm run test:coverage && npm run build && npm run size && npm run pack:dry-run","prepublishOnly":"npm run ci"},"devDependencies":{"@eslint/js":"^9.15.0","@types/node":"^20.11.0","@vitest/coverage-v8":"^2.1.8","esbuild":"^0.24.0","eslint":"^9.15.0","eslint-config-prettier":"^9.1.0","jsdom":"^25.0.1","prettier":"^3.3.3","semantic-release":"25.0.5","tsup":"^8.3.5","typescript":"^5.6.3","typescript-eslint":"^8.16.0","vitest":"^2.1.8"},"_id":"@autra-io/biometrics-sdk-web@0.1.0","gitHead":"a7aea17bfeaf578da33c7ffa0a74e1612088f205","bugs":{"url":"https://github.com/autratech/autra-biometrics-sdk-web/issues"},"_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-fRMhHOQKIrtb2n/x/7Mvd4piDNyp2hNJSS9BItOYiaBnsGPNwCTibVZc+NH9GHl3pRei++nLZhiyb0AVmL8ctQ==","shasum":"740b5e704832864cad7da9d7c9eb70c9dd7fb4fa","tarball":"https://registry.npmjs.org/@autra-io/biometrics-sdk-web/-/biometrics-sdk-web-0.1.0.tgz","fileCount":12,"unpackedSize":279665,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCFF10h0TkKeZREuTBoA1EPLNKgfVCNln4WTmCUU8Q+4QIhALFqyQeG9KoUz/SyyHleX5OlAztysqLABxfZIt95XuPa"}]},"_npmUser":{"name":"ximenis-weaura","email":"victor.ximenis@weaura.tech"},"directories":{},"maintainers":[{"name":"magnoaura","email":"magno@weaura.tech"},{"name":"adminautra","email":"it@autra.io"},{"name":"ximenis-weaura","email":"victor.ximenis@weaura.tech"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/biometrics-sdk-web_0.1.0_1787494762564_0.3400360148861046"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-23T14:19:22.368Z","0.1.0":"2026-08-23T14:19:22.694Z","modified":"2026-08-23T14:19:23.064Z"},"maintainers":[{"name":"magnoaura","email":"magno@weaura.tech"},{"name":"adminautra","email":"it@autra.io"},{"name":"ximenis-weaura","email":"victor.ximenis@weaura.tech"}],"description":"Web SDK for Autra's hosted biometric selfie capture with liveness proof.","homepage":"https://autra.io","keywords":["biometrics","selfie","liveness","kyc","autra","hosted-page","postmessage"],"repository":{"type":"git","url":"git+https://github.com/autratech/autra-biometrics-sdk-web.git"},"bugs":{"url":"https://github.com/autratech/autra-biometrics-sdk-web/issues"},"license":"Apache-2.0","readme":"# @autra-io/biometrics-sdk-web\n\nSDK web da Autra para captura biométrica de selfie com prova de vida\nhospedada. Seu backend cria uma sessão com as credenciais OAuth2 que você já\ntem; sua aplicação web abre a Hosted Page da Autra através deste SDK e\nrecebe de volta o JWT assinado pela Unico — a prova de que a captura veio de\numa selfie legítima com liveness. A Autra nunca vê, verifica ou armazena o\ndado biométrico.\n\n[Read in English](./README.md)\n\n## Sumário\n\n- [Recursos](#recursos)\n- [Requisitos](#requisitos)\n- [Instalação](#instalação)\n- [Como funciona](#como-funciona)\n- [Início rápido](#início-rápido)\n- [Referência de API](#referência-de-api)\n- [Segurança](#segurança)\n- [Solução de problemas](#solução-de-problemas)\n- [Licença](#licença)\n\n## Recursos\n\n- API pública tipada: ESM + CJS + `.d.ts`, tree-shakeable (`sideEffects: false`)\n- Agnóstico de framework: sem React, sem dependência de runtime\n- Modal (iframe) como modo primário de abertura, com um modo redirect para\n contextos em que a página hospedeira não pode embutir a Hosted Page\n- Canal `postMessage` endurecido: `targetOrigin` sempre exato, validação de\n `event.origin` **e** `event.source`, envelope versionado, terminal guard\n- API híbrida: `Promise` para o resultado terminal, eventos para os estados\n intermediários (`ready`, `mode_selected`, `camera_requested`,\n `capture_started`, `capture_retry`, `closed`)\n- Taxonomia de erro tipada com 17 códigos (`AutraBiometricsError`)\n- Bundle ESM sempre ≤ 15 KB minificado+gzip (verificado no CI)\n\n## Requisitos\n\n- Node.js >= 20 para construir/testar este pacote\n- Um navegador moderno (desktop ou mobile) em tempo de execução\n- Um backend capaz de chamar `POST /v1/biometrics/sessions` com suas\n credenciais OAuth2 existentes — este SDK nunca recebe uma credencial da\n API da Autra\n\n## Instalação\n\n```bash\nnpm install @autra-io/biometrics-sdk-web\n```\n\n## Como funciona\n\n```text\nSeu backend Sua app web + SDK Hosted Page da Autra\n | | |\n |--- sessionToken ------>| |\n | |--- open() monta o iframe -->|\n | |<---------- ready -----------|\n | |<---- camera_requested -------|\n | |<---- capture_started --------|\n | |<----------- jwt -------------|\n |<---------------------- jwt (POST /api/kyc) -----------|\n```\n\nO SDK nunca conversa diretamente com a Unico e nunca persiste nada. A imagem\nda selfie nunca sai da Hosted Page.\n\n## Início rápido\n\n### Passo 1 — Backend: crie uma sessão\n\n```http\nPOST /v1/biometrics/sessions\nAuthorization: Bearer \nContent-Type: application/json\n\n{ \"referenceId\": \"customer-42\", \"flow\": \"selfie\", \"environment\": \"production\" }\n```\n\nA resposta traz `sessionId`, `sessionToken` (exibido uma única vez) e\n`hostedPageUrl`. Repasse `sessionId`, `sessionToken` e `hostedPageUrl` para\nsua aplicação web — nunca registre `sessionToken` em log.\n\n### Passo 2 — App: abra a captura\n\n```typescript\nimport { AutraBiometrics, AutraBiometricsError } from '@autra-io/biometrics-sdk-web';\n\nconst biometrics = AutraBiometrics.create({\n environment: 'production', // ou \"sandbox\"\n locale: 'pt-BR', // opcional\n debug: false, // opcional — nunca loga sessionToken nem jwt\n});\n\nconst session = biometrics.createSession({\n sessionId,\n sessionToken, // veio do SEU backend, nunca um segredo gerado por você\n hostedPageUrl,\n preferredMode: 'auto', // \"auto\" | \"modal\" | \"redirect\"\n timeoutMs: 300_000,\n});\n\nsession.on('ready', () => {});\nsession.on('mode_selected', ({ mode }) => {});\nsession.on('camera_requested', () => {});\nsession.on('capture_started', ({ attempt }) => {});\nsession.on('capture_retry', ({ attempt, code }) => {});\n\ntry {\n const result = await session.open();\n // { sessionId, jwt, attempts, capturedAt }\n await fetch('/api/kyc', { method: 'POST', body: JSON.stringify({ jwt: result.jwt }) });\n} catch (err) {\n if (err instanceof AutraBiometricsError && err.code === 'cancelled_by_user') return;\n showError(err instanceof AutraBiometricsError ? err.code : 'unknown_error');\n} finally {\n session.destroy();\n}\n```\n\n## Referência de API\n\n### `AutraBiometrics.create(options)`\n\n| Opção | Tipo | Obrigatório | Notas |\n| ------------- | --------------------------- | ----------- | ------------------------------------------------------------ |\n| `environment` | `\"production\" \\| \"sandbox\"` | sim | |\n| `locale` | `string` | não | |\n| `debug` | `boolean` | não | Loga apenas transições de estado, nunca `sessionToken`/`jwt` |\n\nNão faz nenhuma chamada de rede.\n\n### `biometrics.createSession(options)`\n\n| Opção | Tipo | Obrigatório | Notas |\n| --------------- | ------------------------------------------ | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `sessionId` | `string` | sim | Vindo do seu backend |\n| `sessionToken` | `string` | sim | Vindo do seu backend; nunca logado, nunca persistido |\n| `hostedPageUrl` | `string` | sim | Deve ser HTTPS ou `createSession` lança erro |\n| `preferredMode` | `\"auto\" \\| \"modal\" \\| \"redirect\"` | não | Padrão `\"auto\"` |\n| `returnUrl` | `string` | obrigatório se `preferredMode` resolver para `\"redirect\"` | Deve ser HTTPS |\n| `timeoutMs` | `number` | não | Teto local de UI; padrão 300000 |\n| `embedModes` | `Array<\"modal\" \\| \"iframe\" \\| \"redirect\">` | não | Vindo do `embedModes` do seu backend (fail-closed por origem — sem `\"modal\"` na lista, o SDK nunca tenta o modal). Omita para tentar todos os modos que a sequência resolvida incluiria. A API ainda devolve `\"popup\"` para algumas origens; o SDK aceita na lista e ignora (`window.open()` é bloqueado por padrão fora de um gesto direto do usuário). |\n\nNão faz nenhuma chamada de rede. Lança um `AutraBiometricsError` tipado\n(código `configuration_error`) de forma síncrona para entrada inválida.\n\n### `session.open()`\n\nResolve o modo de abertura, monta a UI e retorna\n`Promise`:\n\n```typescript\ntype AutraBiometricsResult = {\n sessionId: string;\n jwt: string; // trate como credencial — envie ao seu backend imediatamente, nunca persista, nunca logue\n attempts: number;\n capturedAt: string;\n};\n```\n\nChamar `open()` duas vezes na mesma sessão rejeita a segunda chamada com\n`invalid_session`.\n\n### `session.close()` / `session.destroy()`\n\n`close()` fecha a UI ativa; o `open()` pendente rejeita com\n`cancelled_by_host`. `destroy()` remove listeners, o iframe/overlay e os\ntimers — idempotente, seguro para chamar múltiplas vezes.\n\n### `AutraBiometricsError`\n\n```typescript\nclass AutraBiometricsError extends Error {\n readonly code: AutraBiometricsErrorCode;\n readonly sessionId?: string;\n readonly retryable: boolean;\n}\n```\n\n`AutraBiometricsErrorCode` é um de: `configuration_error`,\n`invalid_session`, `session_expired`, `session_already_used`,\n`origin_not_allowed`, `feature_disabled`, `camera_permission_denied`,\n`camera_unavailable`, `browser_unsupported`, `capture_failed`,\n`attempts_exhausted`, `cancelled_by_user`, `cancelled_by_host`, `timeout`,\n`network_error`, `message_origin_rejected`, `message_invalid`.\n\n### `AUTRA_BIOMETRICS_SDK_VERSION`\n\nA versão publicada do pacote, injetada em tempo de build.\n\n## Segurança\n\nVeja [`SECURITY.md`](SECURITY.md) para a política completa. Em resumo:\n\n- O SDK nunca recebe uma credencial da API da Autra — apenas o\n `sessionToken` de vida curta emitido pelo seu backend.\n- `hostedPageUrl` deve ser HTTPS; o SDK compõe o fragmento `#token=…` por\n conta própria — seu backend nunca coloca o token em uma URL que ele possa\n logar.\n- Todo `postMessage` usa a origem de destino exata, nunca `'*'`, e valida\n tanto `event.origin` quanto `event.source` no recebimento.\n- `jwt` é uma credencial de TTL curto: envie ao seu backend imediatamente,\n nunca persista, nunca logue.\n\n## Solução de problemas\n\n| Sintoma | Causa provável |\n| ------------------------------------------ | ------------------------------------------------------------------------------------------------- |\n| `configuration_error` em `createSession()` | `hostedPageUrl`/`returnUrl` não é HTTPS, ou falta um campo obrigatório |\n| `open()` nunca se resolve no modo redirect | Esperado — a aba navega para outra página; trate o resultado na sua `returnUrl` |\n| `browser_unsupported` | Chamado fora de um navegador (SSR), ou as APIs de DOM que o modo precisa não existem |\n| `message_origin_rejected` no console | Uma mensagem `postMessage` chegou de uma origem/janela inesperada — nunca da Hosted Page legítima |\n\n## Licença\n\nApache-2.0 — veja [`LICENSE`](LICENSE) e [`NOTICE`](NOTICE).\n","readmeFilename":"README.pt-BR.md","_rev":"1-a88e3efab65190ff9add99d94eda35a8"}