santoid-sdk 8.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 (57) hide show
  1. package/CHANGELOG.md +17 -3
  2. package/README.md +123 -244
  3. package/api/ApiLivenessSessionService.d.ts +14 -0
  4. package/api/ApiLivenessSessionService.js +4 -0
  5. package/browser/index.js +1 -1
  6. package/browser/liveness-capture.js +2 -0
  7. package/browser/liveness-capture.js.LICENSE.txt +350 -0
  8. package/client/age/index.d.ts +18 -0
  9. package/client/age/index.js +40 -0
  10. package/client/index.d.ts +4 -2
  11. package/client/index.js +4 -2
  12. package/client/liveness/index.d.ts +2 -2
  13. package/client/liveness/index.js +3 -3
  14. package/client/liveness/methods/livenessSession/Service.d.ts +7 -2
  15. package/client/liveness/methods/livenessSession/Service.js +14 -6
  16. package/client/liveness/methods/livenessSession/index.d.ts +13 -9
  17. package/client/liveness/methods/livenessSession/index.js +12 -9
  18. package/client/liveness/methods/livenessSession/isLivenessApproved.d.ts +6 -0
  19. package/client/liveness/methods/livenessSession/isLivenessApproved.js +13 -0
  20. package/client/liveness/methods/uploadIdentificationDocument/Service.d.ts +8 -29
  21. package/client/liveness/methods/uploadIdentificationDocument/Service.js +25 -66
  22. package/client/liveness/methods/uploadIdentificationDocument/index.d.ts +4 -18
  23. package/client/liveness/methods/uploadIdentificationDocument/index.js +4 -8
  24. package/client/liveness-capture/LivenessCapture.d.ts +13 -0
  25. package/client/liveness-capture/LivenessCapture.js +23 -0
  26. package/client/liveness-capture/displayText.d.ts +54 -0
  27. package/client/liveness-capture/displayText.js +57 -0
  28. package/client/liveness-capture/index.d.ts +36 -0
  29. package/client/liveness-capture/index.js +2 -0
  30. package/client/liveness-capture/index.js.LICENSE.txt +350 -0
  31. package/package.json +11 -4
  32. package/server/index.d.ts +0 -2
  33. package/server/index.js +0 -2
  34. package/server/liveness/index.d.ts +1 -2
  35. package/server/liveness/index.js +1 -3
  36. package/server/liveness/methods/uploadIdentificationDocument/Service.d.ts +3 -3
  37. package/server/liveness/methods/uploadIdentificationDocument/Service.js +2 -2
  38. package/server/liveness/methods/uploadIdentificationDocument/index.d.ts +7 -21
  39. package/server/liveness/methods/uploadIdentificationDocument/index.js +4 -10
  40. package/tsconfig.json +3 -0
  41. package/tsconfig.prod.json +3 -0
  42. package/utils/constants.d.ts +1 -2
  43. package/utils/constants.js +4 -3
  44. package/utils/error.d.ts +6 -5
  45. package/utils/error.js +7 -6
  46. package/utils/types.d.ts +0 -39
  47. package/webpack.config.cjs +45 -2
  48. package/client/liveness/methods/livenessDetection/Service.d.ts +0 -28
  49. package/client/liveness/methods/livenessDetection/Service.js +0 -138
  50. package/client/liveness/methods/livenessDetection/index.d.ts +0 -23
  51. package/client/liveness/methods/livenessDetection/index.js +0 -58
  52. package/server/liveness/methods/livenessDetection/Service.d.ts +0 -6
  53. package/server/liveness/methods/livenessDetection/Service.js +0 -20
  54. package/server/liveness/methods/livenessDetection/index.d.ts +0 -13
  55. package/server/liveness/methods/livenessDetection/index.js +0 -50
  56. package/utils/websocket.d.ts +0 -18
  57. package/utils/websocket.js +0 -62
package/CHANGELOG.md CHANGED
@@ -1,5 +1,19 @@
1
1
  # Changelog
2
2
 
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
+
3
17
  ## Versão 7.1.0
4
18
 
5
19
  ### Mudanças
@@ -10,9 +24,9 @@
10
24
  ## Versão 7.0.0
11
25
 
12
26
  ### Mudanças
13
- - 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.
14
- - 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**.
15
- - 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`.
16
30
 
17
31
  ## Versão 5.4.0
18
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,204 +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. |
374
-
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.
363
+ Verifica se há uma pessoa real diante da câmera, por meio de uma rápida análise facial.
377
364
 
378
- O fluxo é:
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.
379
366
 
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 do usuário, ou uma chave de API — o SDK reconhece a chave pelo
389
- // prefixo e a envia em x-api-key
390
- token: 'string',
372
+ const capture = mountLiveness(document.getElementById('captura'), {
373
+ // Chave de API (x-api-key) ou token do usuário
374
+ apiKey: 'st_...',
391
375
 
392
- // Alternativa explícita à chave de API. Com ela, token é opcional
393
- apiKey: 'string',
394
-
395
- // Opcional: sem track, a verificação não fica atrelada a um processo
376
+ // Opcionais
396
377
  track: 'string',
397
378
  customerRequestId: 'string',
379
+ language: 'pt', // 'pt' | 'en'
380
+ colorMode: 'light', // 'light' | 'dark'
381
+ threshold: 80, // confiança mínima para approved
398
382
 
399
- onSessionCreated: (sessionId) => {
400
- // Entregue este sessionId ao <FaceLivenessDetector>
383
+ onCaptureComplete () {
384
+ // a captura terminou; o resultado está sendo consultado
401
385
  },
402
386
 
403
- onResults: (results) => {
404
- // results.Status, results.Confidence, results.ReferenceImage, results.AuditImages
387
+ onResult (result) {
388
+ // result.approved, result.Confidence, result.Status, result.ReferenceImage...
405
389
  },
406
390
 
407
- onError: (error) => {
408
- // ...
391
+ onError (error) {
392
+ // error.code: liveness-capture/session-error | capture-error | result-error
409
393
  },
410
- })
411
394
 
412
- const sessionId = await session.createSession()
395
+ onCancel () {
396
+ // a pessoa desistiu da captura
397
+ },
398
+ })
413
399
 
414
- // Depois que o detector sinalizar o fim da captura:
415
- const results = await session.getResults()
400
+ // Ao sair da tela:
401
+ capture.unmount()
416
402
  ```
417
403
 
418
- As chamadas passam pelo API Gateway (`api.santoid.com.br`). Para falar direto com o serviço, sem o gateway, passe `customApiUrl: 'https://liveness.santoid.com.br'`.
419
-
420
- 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).
421
-
422
- #### Prova de Vida v1 (deprecada)
423
- > **Deprecada.** Use `livenessSession`. Esta seção descreve a versão anterior, mantida para os clientes que ainda não migraram.
424
-
425
- #### Utilização em JavaScript
426
- 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:
404
+ O elemento precisa ter altura: a captura ocupa o espaço que ele oferece.
427
405
 
428
- ```ts
429
- import { livenessDetection } from 'santoid-sdk/client/liveness'
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 |
430
418
 
431
- const livenessDetectionResponse = livenessDetection({
432
- token: 'string',
433
- track: 'string',
434
- customId: 'string',
419
+ `mountLiveness` devolve `{ getSessionId, unmount }`.
435
420
 
436
- getNextFrame: () => {
437
- // ...
438
- },
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`.
439
422
 
440
- // ...
441
- })
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:
442
424
 
443
- const { getVideoStream, stopLivenessDetection, resumeGettingFrames, pauseGettingFrames } = livenessDetectionResponse
425
+ ```ts
426
+ const { mountLiveness } = await import('santoid-sdk/client/liveness-capture')
444
427
  ```
445
428
 
446
- As propriedades disponíveis para utilização no objeto de opções estão listadas na tabela abaixo.
447
-
448
- #### Opções para a função livenessDetection (JavaScript)
429
+ #### Via CDN
449
430
 
450
- | Nome da propriedade | Função | É obrigatório? |
451
- | ------------------- | ------ | -------------- |
452
- | token | Token de acesso obtido por meio da autenticação. | Sim |
453
- | track | Identificador do processo que será utilizado. | Sim |
454
- | customId | Identificador customizado para auditoria. | Não |
455
- | useBillingAccounts | Booleano que controla a utilização das contas de faturamento customizadas | Não |
456
- | 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 |
457
- | 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 |
458
- | stopGettingFrames | Função executada quando a obtenção de frames for finalizada. | Não |
459
- | 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 |
460
- | 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 |
461
- | onFrontStep | Função executada quando a etapa 'front' é iniciada. | Não |
462
- | onLeftStep | Função executada quando a etapa 'left' é iniciada. | Não |
463
- | onRightStep | Função executada quando a etapa 'right' é iniciada. | Não |
464
- | onUpStep | Função executada quando a etapa 'up' é iniciada. | Não |
465
- | onBottomStep | Função executada quando a etapa 'bottom' é iniciada. | Não |
466
- | 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 |
467
- | 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 |
468
- | onEnd | Função executada quando a verificação é finalizada, seja com erro ou com sucesso. | Não |
469
-
470
- <br>
471
- 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.
472
-
473
- #### Retorno da função livenessDetection (JavaScript)
474
- A função livenessDetection retorna alguns métodos que possibilitam um melhor controle da verificação.
475
-
476
- | Nome da propriedade | Função |
477
- | ------------------- | ------ |
478
- | getVideoStream | Retorna a stream dos frames (MediaStream), caso ela esteja disponível. |
479
- | stopLivenessDetection | Para a verificação de prova de vida imediatamente e a finaliza completamente. |
480
- | pauseGettingFrames | Para a verificação temporariamente, a qual pode ser retomada posteriormente. |
481
- | resumeGettingFrames | Retoma a verificação, caso ela tenha sido pausada com a função pauseGettingFrames. |
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
+ ```
482
444
 
483
- <br>
445
+ #### Ciclo da sessão com `livenessSession`
446
+ Para quem monta a própria captura. `mountLiveness` usa estas mesmas funções por dentro.
484
447
 
485
448
  ```ts
486
- import { livenessDetection } from 'santoid-sdk/client/liveness'
449
+ import { livenessSession, isLivenessApproved } from 'santoid-sdk/client/liveness'
487
450
 
488
- 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
489
454
  token: 'string',
490
- track: 'string',
491
-
492
- onStart ({ videoStream }) {
493
- const video = document.querySelector('video')
494
- video.srcObject = videoStream
495
- },
496
455
 
497
- onNextStep () {
498
- pauseGettingFrames()
456
+ // Alternativa explícita à chave de API. Com ela, token é opcional
457
+ apiKey: 'string',
499
458
 
500
- // Simulando intervalo de sucesso
501
- setTimeout(() => {
502
- resumeGettingFrames()
503
- }, 1000)
504
- },
459
+ // Opcional: sem track, a verificação não fica atrelada a um processo
460
+ track: 'string',
461
+ customerRequestId: 'string',
505
462
 
506
- // ...
463
+ onSessionCreated: (sessionId) => {},
464
+ onResults: (results) => {},
465
+ onError: (error) => {},
507
466
  })
508
467
 
509
- // Funções retornadas
510
- const { getVideoStream, stopLivenessDetection, pauseGettingFrames, resumeGettingFrames } = livenessDetectionResponse
511
-
512
- ```
513
- #### Utilização em Node.js
514
- 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()
515
469
 
516
- 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()
517
472
 
518
- #### Opções para a função livenessDetection (Node.js)
519
- 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
+ ```
520
477
 
521
- | Nome da propriedade | Função | É obrigatório? |
522
- | ------------------- | ------ | -------------- |
523
- | startGettingFrames | Função executada quando a obtenção de frames for iniciada. <br>Não precisa retornar nenhum valor. | Não |
524
- | 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).
525
479
 
526
- <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'`.
527
481
 
528
- #### Retorno da função livenessDetection (Node.js)
529
- 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.
530
484
 
531
485
  ```ts
532
- import { livenessDetection } from 'santoid-sdk/server/liveness'
486
+ import { mountLiveness } from 'santoid-sdk/client/liveness-capture'
487
+ import { estimateAge } from 'santoid-sdk/client/age'
533
488
 
534
- function getNextFrame (): string | ArrayBuffer | Buffer | Buffer[] {
535
- // ...
536
- }
489
+ mountLiveness(element, {
490
+ apiKey: 'st_...',
491
+ async onResult (result) {
492
+ if (!result.approved) return
537
493
 
538
- const livenessDetectionResponse = livenessDetection({
539
- token: 'string',
540
- track: 'string',
541
-
542
- getNextFrame,
543
-
544
- // ...
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
+ },
545
498
  })
546
-
547
- // Funções retornadas
548
- const { stopLivenessDetection, pauseGettingFrames, resumeGettingFrames } = livenessDetectionResponse
549
499
  ```
550
500
 
551
- ### Teste do Fluxo Completo
552
- 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. |
553
505
 
554
- 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`.
555
507
 
556
- 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`).
557
510
 
558
- 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`.
559
512
 
560
513
  #### Utilização em JavaScript
561
514
 
562
- As propriedades disponíveis para utilização no objeto de opções estão listadas na tabela abaixo.
563
-
564
515
  #### Opções para a função uploadIdentificationDocument (JavaScript)
565
516
 
566
517
  | Nome da propriedade | Função | É obrigatório? |
@@ -568,11 +519,10 @@ As propriedades disponíveis para utilização no objeto de opções estão list
568
519
  | token | Token de acesso obtido por meio da autenticação. | Sim |
569
520
  | track | Identificador do processo que será utilizado. | Sim |
570
521
  | useBillingAccounts | Booleano que controla a utilização das contas de faturamento customizadas | Não |
571
- | livenessDetectionOptions | Opções para a verificação de prova de vida. | Não |
572
- | 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 |
573
523
  | onError | Função executada quando ocorre erro em alguma das operações. | Não |
574
- | 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 |
575
- | 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 |
576
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 |
577
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 |
578
528
 
@@ -581,67 +531,33 @@ As propriedades disponíveis para utilização no objeto de opções estão list
581
531
  ```ts
582
532
  import { uploadIdentificationDocument } from 'santoid-sdk/client/liveness'
583
533
 
584
- const uploadIdentificationDocumentResponse = uploadIdentificationDocument({
534
+ const {
535
+ startAll,
536
+ startDocumentUpload,
537
+ startFaceComparison,
538
+ getResults,
539
+ } = uploadIdentificationDocument({
585
540
  token: 'string',
586
541
  track: 'string',
587
542
 
588
- onUpdate (results) => {
589
- // ...
590
- },
591
-
592
- onError (error) {
593
- // ...
594
- },
595
-
596
- onSuccess (results) {
597
- // ...
598
- },
599
-
600
- onEnd () {
601
- // ...
602
- },
603
-
604
- onValidationRequested (requestInformation) {
605
- // ..
606
- },
607
-
608
- onClearInterval (interval) {
609
- // ..
610
- },
611
-
612
- livenessDetectionOptions: {
613
- getNextFrame () {
614
- // ...
615
- },
616
-
617
- onSuccess () {
618
- // ...
619
- },
620
-
621
- // ...
622
- },
623
-
624
- // ...
543
+ onUpdate (results) {},
544
+ onError (error) {},
545
+ onSuccess (results) {},
546
+ onEnd () {},
547
+ onValidationRequested (requestInformation) {},
548
+ onClearInterval (interval) {},
625
549
  })
626
550
 
627
- const {
628
- startAll,
629
- startDocumentUpload,
630
- startLivenessDetection,
631
- startFaceComparison,
632
- getResults
633
- } = uploadIdentificationDocumentResponse
551
+ await startAll(documentFile, selfieFile)
634
552
  ```
635
553
 
636
554
  #### Retorno da função uploadIdentificationDocument (JavaScript)
637
- A função uploadIdentificationDocument retorna alguns métodos que podem ser utilizados para dar controlar as análises.
638
555
 
639
556
  | Nome da propriedade | Função |
640
557
  | ------------------- | ------ |
641
- | 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). |
642
- | 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**). |
643
- | startLivenessDetection | Inicia a verificação de prova de vida e aceita as mesmas opções que a função livenessDetection, caso deseje sobrescrevê-las. |
644
- | 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**). |
645
561
  | getResults | Retorna os status atuais de cada análise, no formato apresentado abaixo. |
646
562
 
647
563
  <br>
@@ -656,12 +572,6 @@ interface IUploadIdentificationDocumentResults {
656
572
  loading: boolean
657
573
  error: SDKError | null
658
574
  }
659
- liveness: {
660
- status: TResultStatuses
661
- results: ILivenessResults<Blob | File | null | undefined> | null
662
- loading: boolean
663
- error: SDKError | null
664
- }
665
575
  faceMatch: {
666
576
  status: TResultStatuses
667
577
  results: IFaceMatchResult | null
@@ -669,48 +579,17 @@ interface IUploadIdentificationDocumentResults {
669
579
  error: SDKError | null
670
580
  }
671
581
  }
672
- ```
673
582
 
674
- Em que:
675
-
676
- ```typescript
677
583
  type TResultStatuses = 'success' | 'error' | null
678
-
679
- type TPositions = 'front' | 'right' | 'left' | 'up' | 'bottom'
680
-
681
- interface ILivenessResults {
682
- livenessId: string
683
- successFrames: Record<TPositions, Blob>
684
- }
685
584
  ```
686
585
 
687
586
  Os tipos **ITypificationResult** e **IFaceMatchResult** podem ser conferidos na seção de **Tipos comuns**, disponível mais a frente na documentação.
688
587
 
689
588
  #### Utilização em Node.js
690
- De forma semelhante à funcionalidade da Prova de Vida, para o Node.js o caminho da importação muda
691
- e a função **getNextFrame** passa a ser obrigatória e deve ser fornecida às opções para o livenessDetection.
692
-
693
- Outro detalhe é que no Node.js todos os tipos envolvendo **File** ou **Blob** passam a utilizar valores do tipo **string, ArrayBuffer, Buffer ou Buffer[]**.
694
-
695
- 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.
696
590
 
697
591
  ```ts
698
592
  import { uploadIdentificationDocument } from 'santoid-sdk/server/liveness'
699
-
700
- const uploadIdentificationDocumentResponse = uploadIdentificationDocument({
701
- token: 'string',
702
- track: 'string',
703
-
704
- livenessDetectionOptions: {
705
- getNextFrame () {
706
- // ...
707
- },
708
-
709
- // ...
710
- },
711
-
712
- // ...
713
- })
714
593
  ```
715
594
 
716
595
  ## Tipos comuns
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;
@@ -23,4 +36,5 @@ export declare class ApiLivenessSessionService extends AbstractService {
23
36
  private livenessRequest;
24
37
  createSession(customerRequestId?: string): Promise<ILivenessSession>;
25
38
  getSessionResults(sessionId: string): Promise<ILivenessSessionResult>;
39
+ estimateAge(sessionId: string, customerRequestId?: string): Promise<IAgeEstimate>;
26
40
  }
package/api/ApiLivenessSessionService.js CHANGED
@@ -31,5 +31,9 @@ class ApiLivenessSessionService extends AbstractService_1.AbstractService {
31
31
  const response = await this.livenessRequest().get(`/api/v2/liveness/session/${sessionId}`, { params: this.options.track ? { track: this.options.track } : undefined });
32
32
  return response.data;
33
33
  }
34
+ async estimateAge(sessionId, customerRequestId) {
35
+ const response = await this.livenessRequest().post('/api/v2/age/estimate', { sessionId, track: this.options.track, customerRequestId });
36
+ return response.data;
37
+ }
34
38
  }
35
39
  exports.ApiLivenessSessionService = ApiLivenessSessionService;