@neofaceid/web-sdk 1.42.3 → 1.44.0

package/dist/index.d.ts

@@ -645,9 +645,41 @@ export declare interface DetectionResult {
     details?: any;
 }
 
+/** Desfecho da inscrição de aparelho. */
+export declare type DeviceEnrollmentOutcome = {
+    status: 'enrolled';
+    deviceLabel: string | null;
+    enrolledAt?: string;
+} | {
+    status: 'expired';
+} | {
+    status: 'cancelled';
+};
+
 /** Token de inscrição de aparelho, devolvido por {@link requestDeviceEnrollmentToken}. */
 export declare interface DeviceEnrollmentToken {
-    /** JWT RS256 de uso único. Vira o conteúdo do QR. */
+    /**
+     * Identificador curto, no formato `XXXX-XXXX`, de um alfabeto sem os pares
+     * que se confundem (`0/O`, `1/I/L`, `U/V`).
+     *
+     * **É isto que o QR deve carregar**, não o {@link token}. O JWT inteiro vira
+     * uma grade densa que exige tela grande e câmera boa, e deixa o segredo
+     * óptico — exposto em qualquer foto da tela. O handle fotografado vale muito
+     * menos: não carrega `person_id`, `consumer_id` nem assinatura, e morre na
+     * primeira troca. Como é legível, também serve para ditar por telefone ou
+     * digitar à mão quando a câmera falha.
+     */
+    handle: string;
+    /**
+     * Identificador da solicitação. É a chave do canal SSE que avisa quando o
+     * aparelho for inscrito: `/api/v1/devices/enrollment/{jti}/events/`.
+     */
+    jti: string;
+    /**
+     * JWT RS256 de uso único. Continua vindo por compatibilidade, mas **não deve
+     * ir para o QR** — quem resolve o handle é o Push, contra o core, por canal
+     * interno.
+     */
     token: string;
     /** Validade em segundos (o core emite 300). */
     expiresIn: number;
@@ -1372,6 +1404,12 @@ export declare interface ProofOfLifeResult {
  * `denied` e `expired` são desfechos, não exceções — quem chama precisa
  * distinguir os dois para dirigir a cascata de fallback: expirar pode cair
  * para senha, recusar **não pode**.
+ *
+ * `cancelled` carrega `source` pelo mesmo motivo: a pessoa fechar o modal no
+ * navegador e a solicitação ser cancelada do outro lado são situações
+ * diferentes, e dizer "você cancelou" para quem não cancelou é afirmar algo
+ * falso. É o colapso que o core pediu para evitar entre `denied` e `expired`,
+ * um nível abaixo.
  */
 export declare type PushApprovalOutcome = {
     status: 'approved';
@@ -1383,6 +1421,8 @@ export declare type PushApprovalOutcome = {
     status: 'expired';
 } | {
     status: 'cancelled';
+    source: 'user' | 'server';
+    reason?: string;
 };
 
 declare interface RecognitionResult {
@@ -1595,7 +1635,7 @@ export declare const registerPersonWithoutFace: (personData: {
 /**
  * Data de lançamento da versão atual
  */
-export declare const RELEASE_DATE = "2026-09-14";
+export declare const RELEASE_DATE = "2026-09-16";
 
 declare interface RequestChallengeWithSessionParams {
     applicationToken: string;
@@ -1900,6 +1940,42 @@ export declare function startBiometricRegistration(personData: {
     onCannotGesture?: () => void;
 }): void;
 
+/**
+ * Abre o fluxo de inscrição de aparelho: mostra o código, aguarda o celular
+ * lê-lo e confirma o vínculo.
+ *
+ * Exige uma pessoa autenticada — o core pede o Bearer do DONOR junto do
+ * `X-App-Token`, e por isso a inscrição só existe no autosserviço.
+ *
+ * O QR carrega o **handle curto**, nunca o JWT: um código denso exige tela
+ * grande e câmera boa, e o token inteiro ficaria exposto em qualquer foto da
+ * tela. Quem resolve o handle é a plataforma Push, contra o core, por canal
+ * interno — o navegador não participa dessa troca.
+ *
+ * @example
+ * ```ts
+ * const r = await startDeviceEnrollment({
+ *   userAccessToken: sessao.accessToken,
+ *   applicationToken: TOKEN,
+ * });
+ * if (r.status === 'enrolled') {
+ *   // r.deviceLabel pode ser null enquanto o Push não envia o rótulo
+ * }
+ * ```
+ */
+export declare function startDeviceEnrollment(options: StartDeviceEnrollmentOptions): Promise<DeviceEnrollmentOutcome>;
+
+export declare interface StartDeviceEnrollmentOptions {
+    /**
+     * Access token do DONOR autenticado. A inscrição só existe no autosserviço,
+     * com a pessoa logada — o core exige este Bearer **junto** do `X-App-Token`.
+     */
+    userAccessToken: string;
+    applicationToken: string;
+    /** Nome do integrador (fallback: `init({ appName })`). */
+    appName?: string;
+}
+
 /**
  * Função auxiliar para iniciar a captura de documento
  */
@@ -2032,7 +2108,7 @@ export declare const validateToken: (applicationToken: string) => Promise<boolea
  * MINOR: Incrementado quando adicionamos funcionalidades mantendo compatibilidade
  * PATCH: Incrementado quando corrigimos bugs mantendo compatibilidade
  */
-export declare const VERSION = "1.42.3";
+export declare const VERSION = "1.44.0";
 
 /**
  * Executa `fn(sessionId)`. Se o servidor devolver 410 (sessão consumida/expirada),