@dynamicore/jumio-sdk 1.0.1 → 1.0.2

package/dist/client-BwEiGMPy.d.mts

@@ -0,0 +1,515 @@
+import { AxiosInstance } from 'axios';
+
+/**
+ * Estados posibles del flujo de verificación en Jumio.
+ */
+type JumioWorkflowStatus = "PENDING" | "INITIATED" | "ACQUIRED" | "SUBMITTED" | "PROCESSED" | "APPROVED_VERIFIED" | "REJECTED" | "FAILED" | "ERROR" | "DENIED" | "EXPIRED" | "ABANDONED" | (string & {});
+/**
+ * Tipos de entrada soportados para las imágenes del documento.
+ */
+type ImageSource = string | Blob | File | ArrayBuffer | Uint8Array | {
+    url?: unknown;
+} | {
+    [key: string]: unknown;
+};
+/**
+ * Función personalizada para firmar URLs de S3 o descargar recursos privados.
+ */
+type S3SignerFunction = (pathOrUrl: string, expires?: number) => Promise<string | {
+    url?: unknown;
+} | unknown>;
+/**
+ * Función o valor para proveer el token de autenticación.
+ */
+type AuthTokenProvider = string | (() => string | undefined | null | Promise<string | undefined | null>);
+/**
+ * Opciones de configuración para instanciar el cliente JumioClient.
+ */
+interface JumioClientConfig {
+    /**
+     * URL base de la API de DynamiCore / Backend.
+     * @default "https://front.dynamicore.io"
+     */
+    baseUrl?: string;
+    /**
+     * Endpoint específico del servicio de verificación Jumio.
+     * @default "/marketplace/apps/jumio"
+     */
+    endpoint?: string;
+    /**
+     * Header de contexto moral / negocio enviado en las peticiones.
+     */
+    context?: string;
+    /**
+     * Token de autenticación o función que lo obtiene.
+     */
+    authToken?: AuthTokenProvider;
+    /**
+     * Prefijo para el header Authorization (por defecto vacío o "Bearer ").
+     * @default ""
+     */
+    authTokenPrefix?: string;
+    /**
+     * Timeout en milisegundos para las peticiones POST de verificación.
+     * @default 180000 (3 minutos)
+     */
+    requestTimeout?: number;
+    /**
+     * Timeout en milisegundos para las peticiones GET de status.
+     * @default 120000 (2 minutos)
+     */
+    statusTimeout?: number;
+    /**
+     * Número máximo de reintentos ante timeouts o fallas transitorias de red.
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Delay base en milisegundos para el backoff exponencial de reintentos.
+     * @default 800
+     */
+    retryDelayMs?: number;
+    /**
+     * Intervalo en milisegundos entre consultas sucesivas de sondeo (polling).
+     * @default 10000 (10 segundos)
+     */
+    pollingIntervalMs?: number;
+    /**
+     * Número máximo de intentos de sondeo antes de timeout.
+     * @default 20 (20 x 10s = aprox 200 segundos)
+     */
+    maxPollingAttempts?: number;
+    /**
+     * Función opcional para firmar rutas u URLs de Amazon S3.
+     */
+    s3Signer?: S3SignerFunction;
+    /**
+     * Headers HTTP adicionales para incluir en cada petición.
+     */
+    customHeaders?: Record<string, string>;
+    /**
+     * Instancia personalizada de Axios (opcional).
+     */
+    axiosInstance?: AxiosInstance;
+    /**
+     * URL base del proxy de redirección para el flujo Hosted Webflow.
+     * Se usa para construir las URLs de éxito/error con codificación Base64 URL-safe.
+     * Si no se especifica, la URL de retorno se usa directamente sin proxied.
+     * @example "https://my-api.example.com/prod/jumio/redirect/"
+     */
+    redirectProxyUrl?: string;
+}
+/**
+ * Parámetros de entrada para iniciar un flujo Hosted Webflow de Jumio.
+ * El backend genera una URL de verificación oficial de Jumio a la que se redirige al usuario.
+ */
+interface StartWebflowInput {
+    /**
+     * Identificador único del cliente a verificar.
+     */
+    clientId: string;
+    /**
+     * URL a la que Jumio redirigirá al usuario si la verificación es exitosa.
+     * Si `useRedirectProxy` es true, esta URL se codificará en Base64 y se añadirá al proxy.
+     */
+    successUrl: string;
+    /**
+     * URL a la que Jumio redirigirá al usuario si la verificación falla o es rechazada.
+     * Si `useRedirectProxy` es true, esta URL se codificará en Base64 y se añadirá al proxy.
+     */
+    errorUrl: string;
+    /**
+     * Si es `true`, codifica las URLs de retorno en Base64 URL-safe y las prepone al `redirectProxyUrl`.
+     * Útil cuando el backend o la gateway de Jumio requiere un proxy intermediario.
+     * @default false
+     */
+    useRedirectProxy?: boolean;
+    /**
+     * Si es `true`, redirige automáticamente el navegador a la URL de Jumio (`href`) al recibirla.
+     * Solo aplica en entornos de navegador (`window.location`).
+     * @default false
+     */
+    autoRedirect?: boolean;
+    /**
+     * Si es `true`, abre la URL de verificación de Jumio en una nueva pestaña del navegador (`window.open(href, '_blank')`)
+     * sin salir ni perder el estado de la pestaña actual.
+     * @default false
+     */
+    openInNewTab?: boolean;
+    /**
+     * Referencia opcional a una ventana o pestaña pre-abierta (`window.open`).
+     */
+    targetWindow?: Window | null;
+    /**
+     * Señal de cancelación para abortar la petición HTTP.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Resultado devuelto por `startWebflow`.
+ * Contiene la URL de Jumio (`href`) a la que debe redirigirse el usuario.
+ */
+interface StartWebflowResult {
+    /**
+     * URL de la página web alojada de Jumio. Redirigir al usuario a esta URL para iniciar la verificación.
+     */
+    href: string;
+    /**
+     * ID de cuenta en Jumio (puede estar disponible desde el inicio o sólo tras el retorno).
+     */
+    accountId?: string;
+    /**
+     * ID de workflow de Jumio (puede estar disponible desde el inicio o sólo tras el retorno).
+     */
+    workflowId?: string;
+    /**
+     * Payload completo devuelto por el backend.
+     */
+    data: unknown;
+}
+/**
+ * Parámetros extraídos de la URL de retorno luego de completar el flujo web de Jumio.
+ * Jumio añade estos parámetros como query params al redirigir de vuelta a la aplicación.
+ */
+interface WebflowReturnParams {
+    /**
+     * ID de cuenta de Jumio. Requerido para consultar el resultado.
+     */
+    accountId?: string;
+    /**
+     * ID de ejecución del workflow de Jumio. Requerido para consultar el resultado.
+     * Puede venir como `workflowExecutionId` o `workflowId` dependiendo de la configuración del backend.
+     */
+    workflowId?: string;
+    /**
+     * Valor crudo del parámetro `status` de la URL (puede contener sub-parámetros anidados).
+     */
+    rawStatus?: string;
+    /**
+     * Todos los parámetros de query de la URL de retorno, sin procesar.
+     */
+    allParams: Record<string, string>;
+}
+/**
+ * Parámetros de entrada para consultar el estado del flujo Hosted Webflow.
+ */
+interface GetWebflowStatusInput {
+    /**
+     * ID de cuenta de Jumio.
+     */
+    accountId: string;
+    /**
+     * ID de workflow de Jumio.
+     */
+    workflowId: string;
+    /**
+     * ID del cliente (requerido por algunos endpoints de DynamiCore).
+     */
+    clientId?: string;
+    /**
+     * Señal de cancelación.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Resultado de una verificación completada mediante Hosted Webflow.
+ */
+interface WebflowResult {
+    /**
+     * `true` si la verificación fue exitosa (PASSED/WARNING con extracción de datos).
+     * `false` si fue rechazada.
+     */
+    valid: boolean;
+    /**
+     * Tipo de decisión devuelta por Jumio: 'PASSED', 'WARNING', 'REJECTED', 'NOT_EXECUTED', etc.
+     */
+    decision?: string;
+    /**
+     * Estado final del workflow de Jumio.
+     */
+    status?: string;
+    /**
+     * Datos de extracción del documento (CURP, nombre, etc.) si están disponibles.
+     */
+    extraction?: Record<string, unknown>;
+    /**
+     * ID de cuenta de Jumio asociado a la verificación.
+     */
+    accountId?: string;
+    /**
+     * ID de workflow de Jumio asociado a la verificación.
+     */
+    workflowId?: string;
+    /**
+     * Payload completo de la respuesta del backend.
+     */
+    data: unknown;
+    /**
+     * Mensaje descriptivo en caso de que la verificación no sea válida.
+     */
+    errorMessage?: string;
+}
+/**
+ * Opciones para el sondeo del estado del flujo Hosted Webflow.
+ */
+interface PollWebflowOptions {
+    /**
+     * Intervalo en milisegundos entre consultas de estado.
+     * @default 10000
+     */
+    pollingIntervalMs?: number;
+    /**
+     * Número máximo de intentos de sondeo.
+     * @default 20
+     */
+    maxAttempts?: number;
+    /**
+     * Señal de cancelación.
+     */
+    signal?: AbortSignal;
+    /**
+     * Callback invocado en cada intento de sondeo.
+     */
+    onAttempt?: (attempt: number, maxAttempts: number, lastData: unknown) => void;
+}
+/**
+ * Payload enviado a la API de verificación de Jumio.
+ */
+interface JumioVerificationPayload {
+    client: string;
+    front_image_b64: string;
+    back_image_b64: string;
+    [key: string]: unknown;
+}
+/**
+ * Estructura de respuesta de datos de verificación.
+ */
+interface JumioVerificationData {
+    valid?: boolean;
+    status?: JumioWorkflowStatus;
+    workflowStatus?: JumioWorkflowStatus;
+    decision?: string;
+    accountId?: string;
+    workflowId?: string;
+    message?: string;
+    [key: string]: unknown;
+}
+/**
+ * Estructura inicial devuelta al iniciar el flujo de verificación.
+ */
+interface JumioIneStartData extends JumioVerificationData {
+    accountId?: string;
+    workflowId?: string;
+}
+/**
+ * Resultado estructurado retornado por el cliente tras una validación.
+ */
+interface VerifyIneResult {
+    /**
+     * Indica si la validación fue exitosa (true) o fallida/rechazada (false).
+     */
+    valid: boolean;
+    /**
+     * Estado actual o final del flujo de Jumio.
+     */
+    status?: JumioWorkflowStatus;
+    /**
+     * Identificador de cuenta en Jumio.
+     */
+    accountId?: string;
+    /**
+     * Identificador del workflow en Jumio.
+     */
+    workflowId?: string;
+    /**
+     * Datos completos devueltos por la API de Jumio/DynamiCore.
+     */
+    data: unknown;
+    /**
+     * Mensaje descriptivo o de error si la validación falló.
+     */
+    errorMessage?: string;
+}
+/**
+ * Callback ejecutado cuando el sondeo resuelve un estado final.
+ */
+type JumioStatusResolvedCallback = (result: VerifyIneResult) => void;
+/**
+ * Callback ejecutado si ocurre un error durante el sondeo o la petición.
+ */
+type JumioStatusErrorCallback = (error: Error) => void;
+/**
+ * Callback de progreso para reportar avances de conversión o polling.
+ */
+type JumioProgressCallback = (stage: string, percent?: number) => void;
+/**
+ * Parámetros de entrada para la función `verifyIne`.
+ */
+interface VerifyIneInput {
+    /**
+     * Identificador único del cliente (persona, usuario o ID externo).
+     */
+    clientId: string;
+    /**
+     * Imagen frontal del documento (INE): URL, ruta S3, File, Blob o Base64.
+     */
+    frontImage: ImageSource;
+    /**
+     * Imagen trasera/reverso del documento (INE): URL, ruta S3, File, Blob o Base64.
+     */
+    backImage: ImageSource;
+    /**
+     * Si es `true`, la promesa espera hasta que Jumio resuelva el resultado final (bloqueante).
+     * Si es `false` (por defecto), inicia la validación, retorna de inmediato y ejecuta el sondeo en 2do plano.
+     * @default false
+     */
+    awaitFinalStatus?: boolean;
+    /**
+     * Callback invocado cuando se completa el proceso de validación (síncrono o en segundo plano).
+     */
+    onStatusResolved?: JumioStatusResolvedCallback;
+    /**
+     * Callback invocado ante errores no recuperables durante la validación o sondeo.
+     */
+    onStatusError?: JumioStatusErrorCallback;
+    /**
+     * Callback opcional para reportar etapas del proceso.
+     */
+    onProgress?: JumioProgressCallback;
+    /**
+     * Señal de cancelación (AbortSignal) para abortar peticiones o sondeo activo.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Opciones para el método de polling de estado.
+ */
+interface PollStatusOptions {
+    pollingIntervalMs?: number;
+    maxAttempts?: number;
+    signal?: AbortSignal;
+    onAttempt?: (attempt: number, maxAttempts: number, lastData: unknown) => void;
+}
+
+/**
+ * Cliente principal para gestionar validaciones de identidad mediante Jumio.
+ */
+declare class JumioClient {
+    private readonly http;
+    private readonly config;
+    constructor(config?: JumioClientConfig);
+    /**
+     * Inicia el proceso de verificación convirtiendo las imágenes y enviando el payload inicial a Jumio.
+     */
+    startIneVerification(params: {
+        clientId: string;
+        frontImage: ImageSource;
+        backImage: ImageSource;
+        signal?: AbortSignal;
+        onProgress?: JumioProgressCallback;
+    }): Promise<JumioIneStartData>;
+    /**
+     * Consulta una única vez el estado actual de la validación.
+     */
+    getIneStatus(accountId: string, workflowId: string, signal?: AbortSignal): Promise<JumioVerificationData>;
+    /**
+     * Sondea periódicamente el estado hasta obtener un resultado definitivo.
+     */
+    pollIneStatus(accountId: string, workflowId: string, options?: PollStatusOptions): Promise<VerifyIneResult>;
+    /**
+     * Ejecuta el flujo completo de validación de INE.
+     *
+     * @param input Parámetros de validación y callbacks.
+     * @returns `VerifyIneResult` con el resultado inicial o definitivo según `awaitFinalStatus`.
+     */
+    verifyIne(input: VerifyIneInput): Promise<VerifyIneResult>;
+    /**
+     * Construye la URL de redirección de retorno para el flujo Hosted Webflow.
+     *
+     * Si el cliente está configurado con un `redirectProxyUrl` y `useProxy` es `true`,
+     * la URL de retorno se codifica en Base64 URL-safe y se adjunta al proxy.
+     *
+     * @param returnUrl URL de la aplicación a la que Jumio redirigirá tras la verificación.
+     * @param useProxy Si es `true` y hay `redirectProxyUrl` configurado, usa el proxy.
+     * @returns URL de redirección construida.
+     */
+    buildRedirectUrl(returnUrl: string, useProxy?: boolean): string;
+    /**
+     * Inicia el flujo Hosted Webflow solicitando al backend de DynamiCore la URL
+     * de verificación de Jumio (`href`).
+     *
+     * El usuario debe ser redirigido a esa URL para completar la verificación en la
+     * página oficial de Jumio. Al terminar, Jumio redirige de vuelta a la aplicación
+     * con `accountId` y `workflowExecutionId` como query params.
+     *
+     * @param input Parámetros del flujo: `clientId`, `successUrl`, `errorUrl`, opciones de proxy y redirección.
+     * @returns `StartWebflowResult` con la URL de Jumio (`href`) y datos adicionales.
+     *
+     * @example
+     * ```ts
+     * const { href } = await client.startWebflow({
+     *   clientId: "usr_123",
+     *   successUrl: "https://app.example.com/verify/success",
+     *   errorUrl: "https://app.example.com/verify/error",
+     * });
+     * window.location.href = href;
+     * ```
+     */
+    startWebflow(input: StartWebflowInput): Promise<StartWebflowResult>;
+    /**
+     * Extrae los parámetros de seguimiento de Jumio de la URL de retorno.
+     *
+     * Jumio añade `accountId` y `workflowExecutionId` (o `workflowId`) como query
+     * params al redirigir de vuelta a la aplicación tras la verificación.
+     *
+     * @param source URL completa, `URLSearchParams`, objeto con `search`/`href`, o nada para leer `window.location`.
+     * @returns `WebflowReturnParams` con `accountId`, `workflowId`, `rawStatus` y todos los params.
+     *
+     * @example En React, en el componente de retorno:
+     * ```ts
+     * const { accountId, workflowId } = client.parseWebflowReturnParams(window.location.href);
+     * ```
+     */
+    parseWebflowReturnParams(source?: string | URLSearchParams | {
+        search?: string;
+        href?: string;
+    }): WebflowReturnParams;
+    /**
+     * Consulta una única vez el estado actual de la verificación del flujo Hosted Webflow.
+     *
+     * @param input Parámetros de consulta: `accountId`, `workflowId`, y `clientId` opcional.
+     * @returns `WebflowResult | null` — `null` si la verificación aún está pendiente.
+     */
+    getWebflowStatus(input: GetWebflowStatusInput): Promise<WebflowResult | null>;
+    /**
+     * Sondea periódicamente el estado de verificación de un flujo Hosted Webflow de Jumio.
+     *
+     * Continúa consultando hasta obtener un resultado definitivo o agotar los intentos.
+     *
+     * @param params `accountId`, `workflowId` y `clientId` opcional.
+     * @param options Opciones de sondeo (`maxAttempts`, `pollingIntervalMs`, `signal`, `onAttempt`).
+     * @returns `WebflowResult` con el resultado definitivo.
+     *
+     * @example
+     * ```ts
+     * // En el componente de retorno, tras leer los params de la URL:
+     * const result = await client.pollWebflowStatus({ accountId, workflowId, clientId });
+     * if (result.valid) {
+     *   console.log("Verificación aprobada:", result.extraction);
+     * } else {
+     *   console.warn("Rechazado:", result.errorMessage);
+     * }
+     * ```
+     */
+    pollWebflowStatus(params: {
+        accountId: string;
+        workflowId: string;
+        clientId?: string;
+    }, options?: PollWebflowOptions): Promise<WebflowResult>;
+}
+/**
+ * Fábrica para crear una nueva instancia de `JumioClient`.
+ */
+declare function createJumioClient(config?: JumioClientConfig): JumioClient;
+
+export { type AuthTokenProvider as A, type GetWebflowStatusInput as G, type ImageSource as I, JumioClient as J, type PollStatusOptions as P, type S3SignerFunction as S, type VerifyIneInput as V, type WebflowResult as W, type JumioClientConfig as a, type JumioIneStartData as b, type JumioProgressCallback as c, type JumioStatusErrorCallback as d, type JumioStatusResolvedCallback as e, type JumioVerificationData as f, type JumioVerificationPayload as g, type JumioWorkflowStatus as h, type PollWebflowOptions as i, type StartWebflowInput as j, type StartWebflowResult as k, type VerifyIneResult as l, type WebflowReturnParams as m, createJumioClient as n };