santoid-sdk 7.0.0 → 9.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/CHANGELOG.md +25 -4
  2. package/README.md +123 -237
  3. package/api/AbstractService.js +9 -3
  4. package/api/ApiLivenessSessionService.d.ts +14 -1
  5. package/api/ApiLivenessSessionService.js +20 -11
  6. package/browser/index.js +1 -1
  7. package/browser/liveness-capture.js +2 -0
  8. package/browser/liveness-capture.js.LICENSE.txt +350 -0
  9. package/client/age/index.d.ts +18 -0
  10. package/client/age/index.js +40 -0
  11. package/client/index.d.ts +4 -2
  12. package/client/index.js +4 -2
  13. package/client/liveness/index.d.ts +2 -2
  14. package/client/liveness/index.js +3 -3
  15. package/client/liveness/methods/livenessSession/Service.d.ts +10 -3
  16. package/client/liveness/methods/livenessSession/Service.js +14 -6
  17. package/client/liveness/methods/livenessSession/index.d.ts +13 -9
  18. package/client/liveness/methods/livenessSession/index.js +12 -9
  19. package/client/liveness/methods/livenessSession/isLivenessApproved.d.ts +6 -0
  20. package/client/liveness/methods/livenessSession/isLivenessApproved.js +13 -0
  21. package/client/liveness/methods/uploadIdentificationDocument/Service.d.ts +8 -29
  22. package/client/liveness/methods/uploadIdentificationDocument/Service.js +25 -66
  23. package/client/liveness/methods/uploadIdentificationDocument/index.d.ts +4 -18
  24. package/client/liveness/methods/uploadIdentificationDocument/index.js +4 -8
  25. package/client/liveness-capture/LivenessCapture.d.ts +13 -0
  26. package/client/liveness-capture/LivenessCapture.js +23 -0
  27. package/client/liveness-capture/displayText.d.ts +54 -0
  28. package/client/liveness-capture/displayText.js +57 -0
  29. package/client/liveness-capture/index.d.ts +36 -0
  30. package/client/liveness-capture/index.js +2 -0
  31. package/client/liveness-capture/index.js.LICENSE.txt +350 -0
  32. package/package.json +11 -4
  33. package/server/index.d.ts +0 -2
  34. package/server/index.js +0 -2
  35. package/server/liveness/index.d.ts +1 -2
  36. package/server/liveness/index.js +1 -3
  37. package/server/liveness/methods/uploadIdentificationDocument/Service.d.ts +3 -3
  38. package/server/liveness/methods/uploadIdentificationDocument/Service.js +2 -2
  39. package/server/liveness/methods/uploadIdentificationDocument/index.d.ts +7 -21
  40. package/server/liveness/methods/uploadIdentificationDocument/index.js +4 -10
  41. package/tsconfig.json +3 -0
  42. package/tsconfig.prod.json +3 -0
  43. package/utils/constants.d.ts +1 -2
  44. package/utils/constants.js +4 -3
  45. package/utils/error.d.ts +6 -5
  46. package/utils/error.js +7 -6
  47. package/utils/index.d.ts +2 -0
  48. package/utils/index.js +12 -1
  49. package/utils/types.d.ts +8 -39
  50. package/webpack.config.cjs +45 -2
  51. package/client/liveness/methods/livenessDetection/Service.d.ts +0 -28
  52. package/client/liveness/methods/livenessDetection/Service.js +0 -138
  53. package/client/liveness/methods/livenessDetection/index.d.ts +0 -23
  54. package/client/liveness/methods/livenessDetection/index.js +0 -58
  55. package/server/liveness/methods/livenessDetection/Service.d.ts +0 -6
  56. package/server/liveness/methods/livenessDetection/Service.js +0 -20
  57. package/server/liveness/methods/livenessDetection/index.d.ts +0 -13
  58. package/server/liveness/methods/livenessDetection/index.js +0 -50
  59. package/utils/websocket.d.ts +0 -18
  60. package/utils/websocket.js +0 -62
package/CHANGELOG.md CHANGED
@@ -1,11 +1,32 @@
1
1
  # Changelog
2
2
 
3
- ## Versão 5.5.0
3
+ ## Versão 9.0.0
4
+
5
+ ### Novidades
6
+ - **mountLiveness** (`santoid-sdk/client/liveness-capture`): a captura da prova de vida pela câmera, em JavaScript puro. Monta dentro de um elemento da página, cria a sessão, busca o resultado e entrega com `approved` já calculado. Funciona com qualquer framework, ou nenhum, e não exige configuração além da chave. Na CDN, fica em `browser/liveness-capture.js` (global `SantoiDLivenessCapture`).
7
+ - **estimateAge** (`santoid-sdk/client/age`): estima a faixa etária a partir da foto de uma prova de vida aprovada, sem upload.
8
+ - **isLivenessApproved(result, threshold = 80)**: `Status: 'SUCCEEDED'` só indica que a sessão terminou; a aprovação depende da confiança.
9
+ - **livenessSession** ganhou `getSessionConfig()`, com a configuração que o componente de captura precisa.
10
+
11
+ ### Mudanças que quebram compatibilidade
12
+ - Removida a função **livenessDetection** (prova de vida v1), no client e no server, junto com a opção `customWebSocketUrl` e os tipos da v1 (`ISDKOptions`, `ILivenessResults`, `TPositions`, tipos de WebSocket). O serviço da v1 foi desativado. Use `mountLiveness` ou `livenessSession`.
13
+ - **uploadIdentificationDocument** não faz mais prova de vida: saem `startLivenessDetection`, a opção `livenessDetectionOptions` e o campo `liveness` dos resultados. `startFaceComparison(selfie)` e `startAll(documento, selfie?)` passam a receber a selfie explicitamente — por exemplo, a foto de referência da prova de vida. O `onSuccess` dispara quando a análise do documento termina sem comparação em andamento.
14
+ - Removido o código de erro `upload-identification-document/liveness-detection-error` e o enum `ELivenessDetectionErrorCodes`.
15
+ - Removida a dependência `ws`.
16
+
17
+ ## Versão 7.1.0
18
+
19
+ ### Mudanças
20
+ - A **livenessSession** passou a falar com o **API Gateway** (`api.santoid.com.br`), como o restante do SDK, em vez do domínio próprio do serviço. Para chamar o Cloud Run direto, passe `customApiUrl`.
21
+ - Adicionado suporte a **chave de API**. Informe-a em `apiKey` e ela é enviada em `x-api-key`. Uma chave passada em `token` também é reconhecida pelo prefixo (`st_`, `AIza`) — nesse caso o SDK a envia no header correto sozinho, em vez de tentar tratá-la como JWT.
22
+ - O campo `token` passou a ser opcional na **livenessSession** quando `apiKey` for informada.
23
+
24
+ ## Versão 7.0.0
4
25
 
5
26
  ### Mudanças
6
- - Adicionada a função **livenessSession**, a prova de vida v2, sobre o **AWS Rekognition Face Liveness**. Ela cobre o ciclo de sessão (`createSession` e `getResults`), incluindo a espera pelo resultado enquanto o Rekognition ainda avalia. A captura em si — câmera, oval e desafio — é feita pelo `<FaceLivenessDetector>` da AWS, um componente React, e por isso não faz parte deste pacote.
7
- - A função **livenessDetection** foi marcada como **deprecada**. Ela é a prova de vida v1, baseada no detector in-house (WebSocket com o desafio de cinco posições). Continua funcionando e será mantida até a migração dos clientes, mas não recebe mais evolução — código novo deve usar **livenessSession**.
8
- - A URL padrão do WebSocket da v1 deixou de apontar para o endereço gerado do Cloud Run e passou a usar o domínio próprio `liveness.santoid.com.br`.
27
+ - Adicionada a função **livenessSession**, a prova de vida v2. Ela cobre o ciclo de sessão (`createSession` e `getResults`), incluindo a espera pelo resultado enquanto a análise termina.
28
+ - A função **livenessDetection** foi marcada como **deprecada** (prova de vida v1, via WebSocket com o desafio de cinco posições).
29
+ - A URL padrão do WebSocket da v1 passou a usar o domínio próprio `liveness.santoid.com.br`.
9
30
 
10
31
  ## Versão 5.4.0
11
32
  - Foram adicionadas as funções de callback **onCameraStart** e **onCameraStop** para as funcionalidades de **Tipificação**, **OCR** e **Face Match**.
package/README.md CHANGED
@@ -68,7 +68,7 @@ Ao importar a biblioteca via tag script, todas as funções do SDK ficarão disp
68
68
  ```html
69
69
  <body>
70
70
  <button onclick="startTypification()">Iniciar tipificação</button>
71
- <button onclick="startLiveness()">Iniciar liveness</button>
71
+ <button onclick="checkResult()">Conferir prova de vida</button>
72
72
 
73
73
  <!-- ... -->
74
74
 
@@ -84,13 +84,8 @@ Ao importar a biblioteca via tag script, todas as funções do SDK ficarão disp
84
84
  })
85
85
  }
86
86
 
87
- function startLiveness () {
88
- SantoiDSDK.livenessDetection({
89
- track: 'string',
90
- token: 'string',
91
-
92
- // ...
93
- })
87
+ function checkResult () {
88
+ SantoiDSDK.isLivenessApproved({ Status: 'SUCCEEDED', Confidence: 92 })
94
89
  }
95
90
 
96
91
  // ...
@@ -98,6 +93,8 @@ Ao importar a biblioteca via tag script, todas as funções do SDK ficarão disp
98
93
  </body>
99
94
  ```
100
95
 
96
+ A captura da prova de vida (`mountLiveness`) tem arquivo próprio na CDN, para o bundle principal continuar leve — veja a seção **Prova de Vida**.
97
+
101
98
  ## Funcionalidades disponíveis
102
99
 
103
100
  ### Tipificação
@@ -363,197 +360,158 @@ A utilização da função de Face Match em Node.js é idêntica à utilização
363
360
  Os resultados podem ser obtidos por meio da função de callback **onSuccess** por meio dos parâmetros. Sua estrutura é baseada na interface **IFaceMatchResult**, a qual pode ser consultada mais abaixo na seção de **Tipos comuns**.
364
361
 
365
362
  ### Prova de Vida
366
- O SDK conta com a funcionalidade de **Prova de Vida**, que possibilita a verificação do usuário atual, avaliando se uma pessoa real está realizando as atividades online por meio de uma rápida análise facial.
367
-
368
- Existem duas versões:
369
-
370
- | Versão | Função | Situação |
371
- | --- | --- | --- |
372
- | v2 | `livenessSession` | **Recomendada.** Usa o AWS Rekognition Face Liveness. |
373
- | v1 | `livenessDetection` | **Deprecada.** Detector in-house, via WebSocket, com o desafio de cinco posições. Mantida até a migração dos clientes, sem receber evolução. |
363
+ Verifica se há uma pessoa real diante da câmera, por meio de uma rápida análise facial.
374
364
 
375
- #### Prova de Vida v2 (recomendada)
376
- A v2 é feita em duas partes. O SDK cuida do ciclo de sessão contra a API do SantoiD; a captura — câmera, oval e desafio — é feita pelo componente React `<FaceLivenessDetector>` da AWS, que transmite os frames direto para o Rekognition e por isso não faz parte deste pacote.
365
+ A forma mais simples é o `mountLiveness`: ele cria a sessão, abre a câmera dentro de um elemento da sua página, busca o resultado e entrega já dizendo se a pessoa foi aprovada. Funciona em qualquer página — React, Vue, Angular ou HTML puro —, porque a captura roda isolada dentro do elemento. Não há nada para configurar além da sua chave.
377
366
 
378
- O fluxo é:
379
-
380
- 1. `createSession()` — cria a sessão e devolve o `sessionId`
381
- 2. o `<FaceLivenessDetector>` recebe esse `sessionId` e conduz a captura
382
- 3. `getResults()` — quando o detector avisar que terminou
367
+ #### Captura com `mountLiveness`
383
368
 
384
369
  ```ts
385
- import { livenessSession } from 'santoid-sdk/client/liveness'
370
+ import { mountLiveness } from 'santoid-sdk/client/liveness-capture'
386
371
 
387
- const session = livenessSession({
388
- token: 'string',
372
+ const capture = mountLiveness(document.getElementById('captura'), {
373
+ // Chave de API (x-api-key) ou token do usuário
374
+ apiKey: 'st_...',
389
375
 
390
- // Opcional: sem track, a verificação não fica atrelada a um processo
376
+ // Opcionais
391
377
  track: 'string',
392
378
  customerRequestId: 'string',
379
+ language: 'pt', // 'pt' | 'en'
380
+ colorMode: 'light', // 'light' | 'dark'
381
+ threshold: 80, // confiança mínima para approved
393
382
 
394
- onSessionCreated: (sessionId) => {
395
- // Entregue este sessionId ao <FaceLivenessDetector>
383
+ onCaptureComplete () {
384
+ // a captura terminou; o resultado está sendo consultado
396
385
  },
397
386
 
398
- onResults: (results) => {
399
- // results.Status, results.Confidence, results.ReferenceImage, results.AuditImages
387
+ onResult (result) {
388
+ // result.approved, result.Confidence, result.Status, result.ReferenceImage...
400
389
  },
401
390
 
402
- onError: (error) => {
403
- // ...
391
+ onError (error) {
392
+ // error.code: liveness-capture/session-error | capture-error | result-error
404
393
  },
405
- })
406
394
 
407
- const sessionId = await session.createSession()
395
+ onCancel () {
396
+ // a pessoa desistiu da captura
397
+ },
398
+ })
408
399
 
409
- // Depois que o detector sinalizar o fim da captura:
410
- const results = await session.getResults()
400
+ // Ao sair da tela:
401
+ capture.unmount()
411
402
  ```
412
403
 
413
- O `getResults` já espera internamente enquanto o Rekognition ainda avalia — o status fica `CREATED` ou `IN_PROGRESS` por alguns instantes após a captura terminar, e a função só devolve quando sair desse estado (ou após esgotar as tentativas).
404
+ O elemento precisa ter altura: a captura ocupa o espaço que ele oferece.
414
405
 
415
- #### Prova de Vida v1 (deprecada)
416
- > **Deprecada.** Use `livenessSession`. Esta seção descreve a versão anterior, mantida para os clientes que ainda não migraram.
406
+ | Opção | Função | É obrigatório? |
407
+ | --- | --- | --- |
408
+ | apiKey / token | Chave de API ou token do usuário. | Um dos dois |
409
+ | track | Processo ao qual a verificação fica atrelada. | Não |
410
+ | customerRequestId | Identificador seu para a verificação. | Não |
411
+ | language | Idioma dos textos da captura: `pt` (padrão) ou `en`. | Não |
412
+ | colorMode | Tema da captura: `light` (padrão) ou `dark`. | Não |
413
+ | threshold | Confiança mínima (0–100) para `approved`. Padrão: 80. | Não |
414
+ | onCaptureComplete | Chamada quando a captura termina, enquanto o resultado é consultado. | Não |
415
+ | onResult | Recebe o resultado, com `approved` e `threshold`. | Não |
416
+ | onError | Recebe um `SDKError` quando a sessão, a captura ou o resultado falham. | Não |
417
+ | onCancel | Chamada quando a pessoa cancela a captura. | Não |
417
418
 
418
- #### Utilização em JavaScript
419
- Para utilizar a funcionalidade de Prova de Vida, é necessário importar a função para iniciar a verificação e passar alguns valores dentro do objeto de opções, como no exemplo abaixo:
419
+ `mountLiveness` devolve `{ getSessionId, unmount }`.
420
420
 
421
- ```ts
422
- import { livenessDetection } from 'santoid-sdk/client/liveness'
421
+ **Aprovação:** `Status: 'SUCCEEDED'` só indica que a sessão terminou. Quem aprova é a confiança: abaixo do limiar, a pessoa foi reprovada. `approved` já faz essa conta; para os resultados obtidos por `getResults`, use `isLivenessApproved(result, threshold = 80)`, exportada por `santoid-sdk/client/liveness`.
423
422
 
424
- const livenessDetectionResponse = livenessDetection({
425
- token: 'string',
426
- track: 'string',
427
- customId: 'string',
423
+ **Tamanho:** a captura inclui o componente de câmera e seu próprio React (~720 KB com gzip). Por isso ela está em `santoid-sdk/client/liveness-capture`, separada do resto do SDK: quem não usa a captura não carrega nada disso. Em aplicações com divisão de código, prefira importá-la sob demanda:
428
424
 
429
- getNextFrame: () => {
430
- // ...
431
- },
432
-
433
- // ...
434
- })
435
-
436
- const { getVideoStream, stopLivenessDetection, resumeGettingFrames, pauseGettingFrames } = livenessDetectionResponse
425
+ ```ts
426
+ const { mountLiveness } = await import('santoid-sdk/client/liveness-capture')
437
427
  ```
438
428
 
439
- As propriedades disponíveis para utilização no objeto de opções estão listadas na tabela abaixo.
440
-
441
- #### Opções para a função livenessDetection (JavaScript)
442
-
443
- | Nome da propriedade | Função | É obrigatório? |
444
- | ------------------- | ------ | -------------- |
445
- | token | Token de acesso obtido por meio da autenticação. | Sim |
446
- | track | Identificador do processo que será utilizado. | Sim |
447
- | customId | Identificador customizado para auditoria. | Não |
448
- | useBillingAccounts | Booleano que controla a utilização das contas de faturamento customizadas | Não |
449
- | startGettingFrames | Função executada quando a obtenção de frames for iniciada. <br><br>Se retornar um valor do tipo MediaStream, ele será salvo e fornecido por meio da função **getVideoStream**. | Não |
450
- | getNextFrame | Função que deve retornar os frames no formato **File ou Blob**. <br><br>Será executada várias vezes e deve sempre devolver o próximo frame. | Não |
451
- | stopGettingFrames | Função executada quando a obtenção de frames for finalizada. | Não |
452
- | onStart | Função executada quando a verificação for iniciada. <br><br>Disponibiliza pelos parâmetros um objeto contendo a stream da transmissão (**videoStream**), caso disponível. | Não |
453
- | onNextStep | Função executada sempre que a validação muda para a próxima etapa. <br><br>Disponibiliza pelos parâmetros a etapa atual ('front', 'left', 'right', 'up' ou 'bottom'). | Não |
454
- | onFrontStep | Função executada quando a etapa 'front' é iniciada. | Não |
455
- | onLeftStep | Função executada quando a etapa 'left' é iniciada. | Não |
456
- | onRightStep | Função executada quando a etapa 'right' é iniciada. | Não |
457
- | onUpStep | Função executada quando a etapa 'up' é iniciada. | Não |
458
- | onBottomStep | Função executada quando a etapa 'bottom' é iniciada. | Não |
459
- | onError | Função executada quando ocorre um erro. <br><br>Disponibiliza pelos parâmetros a instância do erro, a qual contém um identificador (propriedade **code**). | Não |
460
- | onSuccess | Função executada quando a verificação é finalizada com sucesso. <br><br>Disponibiliza pelos parâmetros um objeto com os resultados, compostos pelo ID da solicitação (**livenessId**) e pelos frames de sucesso (**successFrames**). | Não |
461
- | onEnd | Função executada quando a verificação é finalizada, seja com erro ou com sucesso. | Não |
429
+ #### Via CDN
462
430
 
463
- <br>
464
- Caso a função seja executada em um navegador (ou ambiente semelhante), não é obrigatório fornecer uma função que retorne os frames para verificação (getNextFrame), pois o próprio SDK iniciará a câmera e realizará todo o processo caso a função não seja fornecida.
465
-
466
- #### Retorno da função livenessDetection (JavaScript)
467
- A função livenessDetection retorna alguns métodos que possibilitam um melhor controle da verificação.
431
+ ```html
432
+ <div id="captura" style="height: 600px"></div>
433
+
434
+ <script src="https://cdn.jsdelivr.net/npm/santoid-sdk@VERSION/browser/liveness-capture.js"></script>
435
+ <script>
436
+ SantoiDLivenessCapture.mountLiveness(document.getElementById('captura'), {
437
+ apiKey: 'st_...',
438
+ onResult (result) {
439
+ console.log(result.approved, result.Confidence)
440
+ },
441
+ })
442
+ </script>
443
+ ```
468
444
 
469
- | Nome da propriedade | Função |
470
- | ------------------- | ------ |
471
- | getVideoStream | Retorna a stream dos frames (MediaStream), caso ela esteja disponível. |
472
- | stopLivenessDetection | Para a verificação de prova de vida imediatamente e a finaliza completamente. |
473
- | pauseGettingFrames | Para a verificação temporariamente, a qual pode ser retomada posteriormente. |
474
- | resumeGettingFrames | Retoma a verificação, caso ela tenha sido pausada com a função pauseGettingFrames. |
475
-
476
- <br>
445
+ #### Ciclo da sessão com `livenessSession`
446
+ Para quem monta a própria captura. `mountLiveness` usa estas mesmas funções por dentro.
477
447
 
478
448
  ```ts
479
- import { livenessDetection } from 'santoid-sdk/client/liveness'
449
+ import { livenessSession, isLivenessApproved } from 'santoid-sdk/client/liveness'
480
450
 
481
- const livenessDetectionResponse = livenessDetection({
451
+ const session = livenessSession({
452
+ // Token do usuário, ou uma chave de API — o SDK reconhece a chave pelo
453
+ // prefixo e a envia em x-api-key
482
454
  token: 'string',
483
- track: 'string',
484
-
485
- onStart ({ videoStream }) {
486
- const video = document.querySelector('video')
487
- video.srcObject = videoStream
488
- },
489
455
 
490
- onNextStep () {
491
- pauseGettingFrames()
456
+ // Alternativa explícita à chave de API. Com ela, token é opcional
457
+ apiKey: 'string',
492
458
 
493
- // Simulando intervalo de sucesso
494
- setTimeout(() => {
495
- resumeGettingFrames()
496
- }, 1000)
497
- },
459
+ // Opcional: sem track, a verificação não fica atrelada a um processo
460
+ track: 'string',
461
+ customerRequestId: 'string',
498
462
 
499
- // ...
463
+ onSessionCreated: (sessionId) => {},
464
+ onResults: (results) => {},
465
+ onError: (error) => {},
500
466
  })
501
467
 
502
- // Funções retornadas
503
- const { getVideoStream, stopLivenessDetection, pauseGettingFrames, resumeGettingFrames } = livenessDetectionResponse
504
-
505
- ```
506
- #### Utilização em Node.js
507
- Caso deseje executar a função da prova de vida no servidor (Node.js), **é obrigatório informar ao SDK a função de obtenção de frames** (getNextFrame), a qual deve retornar um valor no formato **string, ArrayBuffer, Buffer ou Buffer[]** contendo os dados da imagem do frame.
468
+ const sessionId = await session.createSession()
508
469
 
509
- Fique atento ao caminho de importação da função, que muda para o caso de execução no servidor (Node.js):
470
+ // Configuração que o componente de captura precisa: { region, identityPoolId }
471
+ const config = session.getSessionConfig()
510
472
 
511
- #### Opções para a função livenessDetection (Node.js)
512
- Para Node.js, as opções são quase as mesmas que as utilizadas em JavaScript, mudando apenas a obrigatoriedade de alguns valores. Abaixo estão listadas as propriedades que mudaram. As outras permanecem iguais às apresentadas anteriormente.
473
+ // Depois que a captura terminar:
474
+ const results = await session.getResults()
475
+ const approved = isLivenessApproved(results)
476
+ ```
513
477
 
514
- | Nome da propriedade | Função | É obrigatório? |
515
- | ------------------- | ------ | -------------- |
516
- | startGettingFrames | Função executada quando a obtenção de frames for iniciada. <br>Não precisa retornar nenhum valor. | Não |
517
- | getNextFrame | Função que deve retornar os frames no formato **string, ArrayBuffer, Buffer ou Buffer[]**. <br><br>Será executada várias vezes e deve sempre devolver o próximo frame. | Sim |
478
+ O `getResults` já espera enquanto a análise termina — o status fica `CREATED` ou `IN_PROGRESS` por alguns instantes após a captura, e a função só devolve quando sair desse estado (ou após esgotar as tentativas).
518
479
 
519
- <br>
480
+ As chamadas passam pelo API Gateway (`api.santoid.com.br`). Para falar direto com o serviço, passe `customApiUrl: 'https://liveness.santoid.com.br'`.
520
481
 
521
- #### Retorno da função livenessDetection (Node.js)
522
- Os itens retornados pela função livenessDetection para Node.js são semelhantes àos retornados pela função para JavaScript, com exceção da função **getVideoStream**, que não é retornada.
482
+ ### Estimativa de Idade
483
+ Estima a faixa etária da pessoa a partir da foto de uma prova de vida **aprovada**. Não há upload: a idade sai da foto capturada na própria sessão, então quem responde é a pessoa que passou pela câmera.
523
484
 
524
485
  ```ts
525
- import { livenessDetection } from 'santoid-sdk/server/liveness'
486
+ import { mountLiveness } from 'santoid-sdk/client/liveness-capture'
487
+ import { estimateAge } from 'santoid-sdk/client/age'
526
488
 
527
- function getNextFrame (): string | ArrayBuffer | Buffer | Buffer[] {
528
- // ...
529
- }
489
+ mountLiveness(element, {
490
+ apiKey: 'st_...',
491
+ async onResult (result) {
492
+ if (!result.approved) return
530
493
 
531
- const livenessDetectionResponse = livenessDetection({
532
- token: 'string',
533
- track: 'string',
534
-
535
- getNextFrame,
536
-
537
- // ...
494
+ const age = await estimateAge({ apiKey: 'st_...', sessionId: result.SessionId })
495
+ // age.AgeRange.Low, age.AgeRange.High, age.Confidence, age.BoundingBox,
496
+ // age.LivenessConfidence, age.ReferenceImage (JPEG em base64)
497
+ },
538
498
  })
539
-
540
- // Funções retornadas
541
- const { stopLivenessDetection, pauseGettingFrames, resumeGettingFrames } = livenessDetectionResponse
542
499
  ```
543
500
 
544
- ### Teste do Fluxo Completo
545
- Com a funcionalidade do teste do fluxo completo do Santo iD, é possível iniciar a análise de prova de vida juntamente com a análise de um documento de identificação enviado, realizando também a comparação da face encontrada na prova de vida com a do documento ao final do processo.
501
+ | Resposta | Quando |
502
+ | --- | --- |
503
+ | 409 | A prova de vida da sessão não foi concluída. |
504
+ | 422 | Prova de vida reprovada, sem foto de referência ou sem um único rosto na foto. |
546
505
 
547
- Ao chamar a função **uploadIdentificationDocument**, ela retorna um determinado conjunto de métodos, os quais possibilitam as análises.
506
+ Erros chegam como `SDKError`, com a resposta original em `error.details`.
548
507
 
549
- Com o método retornado **startAll** é possível iniciar todas as análises simultaneamente, porém também é possível iniciar uma de cada vez com os métodos **startDocumentUpload**, **startLivenessDetection** e **startFaceComparison**.
508
+ ### Teste do Fluxo Completo
509
+ Analisa um documento de identificação enviado e, opcionalmente, compara a face do documento com uma selfie — por exemplo, a foto de referência de uma prova de vida (`result.ReferenceImage`).
550
510
 
551
- Entretanto, o método **startFaceComparison** para a comparação entre as faces detectadas será chamado automaticamente quando as outras análises forem concluídas, sendo mais útil apenas para reiniciar a comparação em caso de erro. Caso o método seja acionado quando as faces ainda não estiverem disponíveis para análise, a função **onError** será chamada com uma instância de erro como parâmetro, caso tenha sido fornecida.
511
+ Ao chamar a função **uploadIdentificationDocument**, ela retorna um conjunto de métodos que possibilitam as análises. Com **startAll** o documento e a comparação correm juntos; também é possível chamá-los separadamente com **startDocumentUpload** e **startFaceComparison**. Se **startFaceComparison** for chamado sem documento enviado, a função **onError** recebe um erro `upload-identification-document/face-match-unavailable-faces-error`.
552
512
 
553
513
  #### Utilização em JavaScript
554
514
 
555
- As propriedades disponíveis para utilização no objeto de opções estão listadas na tabela abaixo.
556
-
557
515
  #### Opções para a função uploadIdentificationDocument (JavaScript)
558
516
 
559
517
  | Nome da propriedade | Função | É obrigatório? |
@@ -561,11 +519,10 @@ As propriedades disponíveis para utilização no objeto de opções estão list
561
519
  | token | Token de acesso obtido por meio da autenticação. | Sim |
562
520
  | track | Identificador do processo que será utilizado. | Sim |
563
521
  | useBillingAccounts | Booleano que controla a utilização das contas de faturamento customizadas | Não |
564
- | livenessDetectionOptions | Opções para a verificação de prova de vida. | Não |
565
- | onUpdate | Função executada toda vez que ocorre uma atualização no status geral (quando alguma operação é iniciada ou concluída, quando ocorre erro, etc.). <br><br>Disponibiliza pelos parâmetros um objeto contendo as informações sobre a situação de cada tipo de processamento realizado (envio de documento, prova de vida, etc.). | Não |
522
+ | onUpdate | Função executada toda vez que ocorre uma atualização no status geral (quando alguma operação é iniciada ou concluída, quando ocorre erro, etc.). <br><br>Disponibiliza pelos parâmetros um objeto contendo a situação de cada análise. | Não |
566
523
  | onError | Função executada quando ocorre erro em alguma das operações. | Não |
567
- | onSuccess | Função executada quando as verificações são finalizadas com sucesso. <br><br>Disponibiliza pelos parâmetros o mesmo objeto fornecido pela função onUpdate, porém com todos os resultados preenchidos. | Não |
568
- | onEnd | Função executada quando a verificação é finalizada, seja com erro ou com sucesso. | Não |
524
+ | onSuccess | Função executada quando a análise do documento termina e não há comparação em andamento. <br><br>Disponibiliza pelos parâmetros o mesmo objeto fornecido pela função onUpdate. | Não |
525
+ | onEnd | Função executada logo após o onSuccess. | Não |
569
526
  | onValidationRequested | Função executada quando o status do processamento é "validation". Retorna informações da requisição para que o usuário consiga fazer a validação manual da requisição | Não |
570
527
  | onClearInterval | Função executada após a implementação da função setInterval(), retorna a variável atribuída ao setInterval() permitindo que o usuário consiga utilizar a função clearInterval() para limpar o temporizador quando desejar | Não |
571
528
 
@@ -574,67 +531,33 @@ As propriedades disponíveis para utilização no objeto de opções estão list
574
531
  ```ts
575
532
  import { uploadIdentificationDocument } from 'santoid-sdk/client/liveness'
576
533
 
577
- const uploadIdentificationDocumentResponse = uploadIdentificationDocument({
534
+ const {
535
+ startAll,
536
+ startDocumentUpload,
537
+ startFaceComparison,
538
+ getResults,
539
+ } = uploadIdentificationDocument({
578
540
  token: 'string',
579
541
  track: 'string',
580
542
 
581
- onUpdate (results) => {
582
- // ...
583
- },
584
-
585
- onError (error) {
586
- // ...
587
- },
588
-
589
- onSuccess (results) {
590
- // ...
591
- },
592
-
593
- onEnd () {
594
- // ...
595
- },
596
-
597
- onValidationRequested (requestInformation) {
598
- // ..
599
- },
600
-
601
- onClearInterval (interval) {
602
- // ..
603
- },
604
-
605
- livenessDetectionOptions: {
606
- getNextFrame () {
607
- // ...
608
- },
609
-
610
- onSuccess () {
611
- // ...
612
- },
613
-
614
- // ...
615
- },
616
-
617
- // ...
543
+ onUpdate (results) {},
544
+ onError (error) {},
545
+ onSuccess (results) {},
546
+ onEnd () {},
547
+ onValidationRequested (requestInformation) {},
548
+ onClearInterval (interval) {},
618
549
  })
619
550
 
620
- const {
621
- startAll,
622
- startDocumentUpload,
623
- startLivenessDetection,
624
- startFaceComparison,
625
- getResults
626
- } = uploadIdentificationDocumentResponse
551
+ await startAll(documentFile, selfieFile)
627
552
  ```
628
553
 
629
554
  #### Retorno da função uploadIdentificationDocument (JavaScript)
630
- A função uploadIdentificationDocument retorna alguns métodos que podem ser utilizados para dar controlar as análises.
631
555
 
632
556
  | Nome da propriedade | Função |
633
557
  | ------------------- | ------ |
634
- | startAll | Inicia todas as análises simultaneamente e espera dois parâmetros: o arquivo do documento (no formato **Blob** ou **File**) e, opcionalmente, as configurações para a prova de vida (caso deseje sobrescrevê-las). |
635
- | startDocumentUpload | Inicia a etapa de upload/análise do documento que será enviado e espera receber um parâmetro com o arquivo. (no formato **Blob** ou **File**). |
636
- | startLivenessDetection | Inicia a verificação de prova de vida e aceita as mesmas opções que a função livenessDetection, caso deseje sobrescrevê-las. |
637
- | startFaceComparison | Inicia a comparação da face do documento com a face detectada na prova de vida. <br><br>Ela será iniciada automaticamente quando as outras análises forem concluídas, porém você pode usar essa função para fazer uma nova tentativa em caso de falha. |
558
+ | startAll | Recebe o arquivo do documento e, opcionalmente, a selfie (**Blob** ou **File**). Com selfie, a comparação corre junto com a análise do documento. |
559
+ | startDocumentUpload | Inicia o upload/análise do documento (**Blob** ou **File**). |
560
+ | startFaceComparison | Compara a face do documento já enviado com a selfie recebida (**Blob** ou **File**). |
638
561
  | getResults | Retorna os status atuais de cada análise, no formato apresentado abaixo. |
639
562
 
640
563
  <br>
@@ -649,12 +572,6 @@ interface IUploadIdentificationDocumentResults {
649
572
  loading: boolean
650
573
  error: SDKError | null
651
574
  }
652
- liveness: {
653
- status: TResultStatuses
654
- results: ILivenessResults<Blob | File | null | undefined> | null
655
- loading: boolean
656
- error: SDKError | null
657
- }
658
575
  faceMatch: {
659
576
  status: TResultStatuses
660
577
  results: IFaceMatchResult | null
@@ -662,48 +579,17 @@ interface IUploadIdentificationDocumentResults {
662
579
  error: SDKError | null
663
580
  }
664
581
  }
665
- ```
666
-
667
- Em que:
668
582
 
669
- ```typescript
670
583
  type TResultStatuses = 'success' | 'error' | null
671
-
672
- type TPositions = 'front' | 'right' | 'left' | 'up' | 'bottom'
673
-
674
- interface ILivenessResults {
675
- livenessId: string
676
- successFrames: Record<TPositions, Blob>
677
- }
678
584
  ```
679
585
 
680
586
  Os tipos **ITypificationResult** e **IFaceMatchResult** podem ser conferidos na seção de **Tipos comuns**, disponível mais a frente na documentação.
681
587
 
682
588
  #### Utilização em Node.js
683
- De forma semelhante à funcionalidade da Prova de Vida, para o Node.js o caminho da importação muda
684
- e a função **getNextFrame** passa a ser obrigatória e deve ser fornecida às opções para o livenessDetection.
685
-
686
- Outro detalhe é que no Node.js todos os tipos envolvendo **File** ou **Blob** passam a utilizar valores do tipo **string, ArrayBuffer, Buffer ou Buffer[]**.
687
-
688
- Todos as outras opções e retornos se mantém os mesmos da versão para JavaScript.
589
+ No Node.js o caminho da importação muda, e os tipos **File** ou **Blob** passam a ser **string, ArrayBuffer ou Buffer**. As demais opções e retornos são os mesmos.
689
590
 
690
591
  ```ts
691
592
  import { uploadIdentificationDocument } from 'santoid-sdk/server/liveness'
692
-
693
- const uploadIdentificationDocumentResponse = uploadIdentificationDocument({
694
- token: 'string',
695
- track: 'string',
696
-
697
- livenessDetectionOptions: {
698
- getNextFrame () {
699
- // ...
700
- },
701
-
702
- // ...
703
- },
704
-
705
- // ...
706
- })
707
593
  ```
708
594
 
709
595
  ## Tipos comuns
package/api/AbstractService.js CHANGED
@@ -6,22 +6,28 @@ Object.defineProperty(exports, "__esModule", { value: true });
6
6
  exports.AbstractService = void 0;
7
7
  const axios_1 = __importDefault(require("axios"));
8
8
  const constants_1 = require("../utils/constants");
9
+ const index_1 = require("../utils/index");
9
10
  class AbstractService {
10
11
  constructor(options, serviceOptions) {
11
12
  this.options = options;
12
13
  this.serviceOptions = serviceOptions;
13
14
  }
14
15
  request(_a) {
15
- var _b, _c;
16
+ var _b, _c, _d;
16
17
  var { contentType = 'application/json', authToken = this.options.token, baseUrl = (_b = this.options.customApiUrl) !== null && _b !== void 0 ? _b : constants_1.API_GATEWAY_URL, extraHeaders, } = _a === void 0 ? {} : _a;
18
+ // Chave de API vai em x-api-key, nunca em Authorization: ela nao e' um JWT,
19
+ // e o backend recusaria ao tentar decodificar. A deteccao pelo prefixo
20
+ // repete a do orchestrator (getUserData), para que quem so tem `token` nao
21
+ // precise saber em qual campo colocar.
22
+ const apiKey = (_c = this.options.apiKey) !== null && _c !== void 0 ? _c : ((0, index_1.looksLikeApiToken)(authToken) ? authToken : undefined);
17
23
  const axiosConfig = {
18
24
  baseURL: baseUrl,
19
- headers: Object.assign({ 'Content-Type': contentType, Authorization: `Bearer ${authToken}` }, extraHeaders),
25
+ headers: Object.assign(Object.assign({ 'Content-Type': contentType }, (apiKey ? { 'x-api-key': apiKey } : { Authorization: `Bearer ${authToken}` })), extraHeaders),
20
26
  };
21
27
  let domain = this.options.domain;
22
28
  if (!this.options.domain && this.options.token) {
23
29
  const decodedToken = this.serviceOptions.tryDecodeJwt(this.options.token);
24
- domain = (_c = decodedToken === null || decodedToken === void 0 ? void 0 : decodedToken.claims) === null || _c === void 0 ? void 0 : _c.domain;
30
+ domain = (_d = decodedToken === null || decodedToken === void 0 ? void 0 : decodedToken.claims) === null || _d === void 0 ? void 0 : _d.domain;
25
31
  }
26
32
  if (axiosConfig.headers) {
27
33
  if (domain) {
package/api/ApiLivenessSessionService.d.ts CHANGED
@@ -1,6 +1,8 @@
1
1
  import { AbstractService } from './AbstractService';
2
2
  export interface ILivenessSession {
3
3
  SessionId: string;
4
+ Region: string;
5
+ IdentityPoolId: string;
4
6
  }
5
7
  export interface ILivenessBoundingBox {
6
8
  Width?: number;
@@ -12,6 +14,17 @@ export interface ILivenessImage {
12
14
  Bytes?: string;
13
15
  BoundingBox?: ILivenessBoundingBox;
14
16
  }
17
+ export interface IAgeRange {
18
+ Low: number;
19
+ High: number;
20
+ }
21
+ export interface IAgeEstimate {
22
+ AgeRange: IAgeRange;
23
+ Confidence: number;
24
+ BoundingBox: ILivenessBoundingBox;
25
+ LivenessConfidence: number;
26
+ ReferenceImage: string;
27
+ }
15
28
  export interface ILivenessSessionResult {
16
29
  SessionId: string;
17
30
  Status: string;
@@ -20,8 +33,8 @@ export interface ILivenessSessionResult {
20
33
  AuditImages?: ILivenessImage[];
21
34
  }
22
35
  export declare class ApiLivenessSessionService extends AbstractService {
23
- get baseLivenessUrl(): string;
24
36
  private livenessRequest;
25
37
  createSession(customerRequestId?: string): Promise<ILivenessSession>;
26
38
  getSessionResults(sessionId: string): Promise<ILivenessSessionResult>;
39
+ estimateAge(sessionId: string, customerRequestId?: string): Promise<IAgeEstimate>;
27
40
  }