@dynamicore/jumio-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DynamiCore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,272 @@
+# @dynamicore/jumio-sdk
+
+> SDK modular, tipado y agnóstico para la validación de identidad e identificación oficial (INE) mediante Jumio en el ecosistema DynamiCore.
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-blue.svg)](https://www.typescriptlang.org/)
+[![React](https://img.shields.io/badge/React-18%20%7C%2019-61dafb.svg)](https://react.dev/)
+[![Dual ESM/CJS](https://img.shields.io/badge/Module-ESM%20%26%20CJS-green.svg)](#)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 🌟 Características
+
+- **Agnóstico y Universal**: Funciona en cualquier entorno JavaScript/TypeScript (Next.js App/Pages router, React, React Native, Vite, Node.js, Express, Fastify).
+- **Manejo Flexible de Imágenes**: Acepta `File`, `Blob`, `ArrayBuffer`, `Uint8Array`, strings en `Base64`, URLs públicas, URLs prefirmadas de S3 o rutas S3 con firmador personalizado.
+- **Soporte de Flujos Asíncrono y Síncrono**:
+  - *No bloqueante* (`awaitFinalStatus: false`): Inicia la validación, responde de inmediato para no detener al usuario y ejecuta el sondeo (polling) en segundo plano notificando mediante callbacks.
+  - *Bloqueante* (`awaitFinalStatus: true`): Aguarda activamente hasta que Jumio resuelva la validación (`APPROVED_VERIFIED`, `REJECTED`, etc.).
+- **Tolerancia a Fallos y Reintentos Automáticos**: Backoff exponencial configurable ante timeouts o caídas transitorias de red.
+- **React Hook de Primera Clase**: `useJumioVerification` provee estados reactivos (`isLoading`, `isSubmitting`, `isPolling`, `progress`, `stage`, `result`, `error`) y cancelación con `AbortController`.
+- **Tipado Estricto y Errores Específicos**: Jerarquía clara de errores (`JumioTimeoutError`, `JumioValidationError`, `JumioImageProcessingError`, etc.).
+- **Bundle Dual Optimizado**: Salida ESM (`.js`) y CommonJS (`.cjs`) con source maps y definiciones TypeScript (`.d.ts`).
+
+---
+
+## 📦 Instalación
+
+### Desde npm / registro privado:
+```bash
+npm install @dynamicore/jumio-sdk axios
+# o con pnpm:
+pnpm add @dynamicore/jumio-sdk axios
+# o con yarn:
+yarn add @dynamicore/jumio-sdk axios
+```
+
+### O en proyectos locales (Monorepo o Enlace local):
+```bash
+npm install file:../jumio-sdk
+```
+
+---
+
+## 🚀 Guía de Uso
+
+### 1. Uso con React / Next.js (`useJumioVerification`)
+
+```tsx
+import React, { useState } from "react";
+import { useJumioVerification } from "@dynamicore/jumio-sdk/react";
+
+export function IneVerificationStep({ clientId, onNext }: { clientId: string; onNext: () => void }) {
+  const [frontFile, setFrontFile] = useState<File | null>(null);
+  const [backFile, setBackFile] = useState<File | null>(null);
+
+  const {
+    verify,
+    isSubmitting,
+    isPolling,
+    isLoading,
+    stage,
+    progress,
+    result,
+    error,
+    reset,
+  } = useJumioVerification({
+    baseUrl: process.env.NEXT_PUBLIC_API_URL || "https://front.dynamicore.io",
+    context: process.env.NEXT_PUBLIC_DYNAMICORE_MORAL_CONTEXT,
+    // Callback cuando el sondeo en segundo plano resuelve el resultado final:
+    onStatusResolved: (res) => {
+      if (res.valid) {
+        alert("¡Tu INE ha sido validada exitosamente!");
+      } else {
+        alert(`No se pudo validar el INE: ${res.errorMessage || "Documento no legible"}`);
+      }
+    },
+    onStatusError: (err) => {
+      console.error("Error en validación en segundo plano:", err);
+    },
+  });
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!frontFile || !backFile) return;
+
+    try {
+      // awaitFinalStatus: false permite avanzar en el flujo sin esperar 2 minutos
+      const res = await verify({
+        clientId,
+        frontImage: frontFile,
+        backImage: backFile,
+        awaitFinalStatus: false,
+      });
+
+      if (res.valid) {
+        onNext(); // Avanzar al siguiente paso del onboarding
+      }
+    } catch (err) {
+      console.error("Error al iniciar verificación:", err);
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit} className="space-y-4">
+      <div>
+        <label>Frente de INE:</label>
+        <input
+          type="file"
+          accept="image/*"
+          onChange={(e) => setFrontFile(e.target.files?.[0] || null)}
+        />
+      </div>
+
+      <div>
+        <label>Reverso de INE:</label>
+        <input
+          type="file"
+          accept="image/*"
+          onChange={(e) => setBackFile(e.target.files?.[0] || null)}
+        />
+      </div>
+
+      {isLoading && (
+        <div>
+          <p>Estado: {stage} ({progress}%)</p>
+          {isSubmitting && <p>Subiendo y procesando imágenes...</p>}
+          {isPolling && <p>Verificando autenticidad en segundo plano...</p>}
+        </div>
+      )}
+
+      {error && <p className="text-red-500">{error.message}</p>}
+
+      <button type="submit" disabled={isLoading || !frontFile || !backFile}>
+        {isLoading ? "Validando..." : "Continuar"}
+      </button>
+    </form>
+  );
+}
+```
+
+---
+
+### 2. Uso con TypeScript / Node.js / Core (`JumioClient`)
+
+```typescript
+import { JumioClient, isJumioError } from "@dynamicore/jumio-sdk";
+
+const jumio = new JumioClient({
+  baseUrl: "https://front.dynamicore.io",
+  context: "MI_CONTEXTO_NEGOCIO", // Contexto/tenant de tu aplicación en DynamiCore
+  authToken: () => getAuthTokenFromSession(), // Token estático o función async
+  // Opcional: Función para firmar URLs privadas de S3
+  s3Signer: async (path, expires) => {
+    return await myS3SignerService(path, expires);
+  },
+});
+
+async function runVerification() {
+  try {
+    const result = await jumio.verifyIne({
+      clientId: "usr_987654",
+      frontImage: "https://my-bucket.s3.amazonaws.com/uploads/ine_front.jpg",
+      backImage: "https://my-bucket.s3.amazonaws.com/uploads/ine_back.jpg",
+      awaitFinalStatus: true, // Espera resolución completa
+    });
+
+    if (result.valid) {
+      console.log("Validación completada con éxito:", result.data);
+    } else {
+      console.warn("Documento rechazado:", result.errorMessage);
+    }
+  } catch (error) {
+    if (isJumioError(error)) {
+      console.error(`Error Jumio [${error.code}]:`, error.message);
+      console.error("Detalle crudo:", error.rawData);
+    } else {
+      console.error("Error inesperado:", error);
+    }
+  }
+}
+```
+
+---
+
+## 🛠️ Opciones de Configuración (`JumioClientConfig`)
+
+| Parámetro | Tipo | Por defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `baseUrl` | `string` | `"https://front.dynamicore.io"` | URL base de la API de DynamiCore. |
+| `endpoint` | `string` | `"/marketplace/apps/jumio"` | Ruta del endpoint de verificación. |
+| `context` | `string` | `undefined` | Contexto moral / de aplicación en header `context`. |
+| `authToken` | `string \| (() => string \| Promise<string>)` | `undefined` | Token Bearer o proveedor dinámico. |
+| `requestTimeout` | `number` | `180000` (3 min) | Timeout para el POST inicial de imágenes. |
+| `statusTimeout` | `number` | `120000` (2 min) | Timeout para cada consulta de estatus. |
+| `maxRetries` | `number` | `3` | Número de reintentos ante caídas transitorias. |
+| `retryDelayMs` | `number` | `800` | Delay base de backoff para reintentos. |
+| `pollingIntervalMs` | `number` | `10000` (10s) | Intervalo entre consultas sucesivas de estado. |
+| `maxPollingAttempts` | `number` | `20` | Cantidad máxima de consultas antes de timeout. |
+| `s3Signer` | `S3SignerFunction` | `undefined` | Función para firmar rutas privadas de S3. |
+| `customHeaders` | `Record<string, string>` | `{}` | Headers HTTP personalizados. |
+| `axiosInstance` | `AxiosInstance` | `undefined` | Instancia personalizada de Axios. |
+
+---
+
+## 🖼️ Formatos de Imagen Soportados
+
+La librería detecta y convierte automáticamente cualquier formato a Base64 puro sin encabezados `data:image/...`:
+
+1. **`File` o `Blob`**: Obtenidos desde `<input type="file" />` o drag & drop.
+2. **`Base64` / `Data URL`**: Strings directos como `"data:image/jpeg;base64,..."` o Base64 crudo.
+3. **`URL Remota`**: URLs `https://...` públicas o con token de firma.
+4. **`Ruta S3`**: Rutas relativas como `"company/123/docs/ine.png"` (utiliza `s3Signer` para resolver la URL firmada).
+5. **`ArrayBuffer` / `Uint8Array`**: Datos binarios en memoria.
+
+---
+
+## 🚦 Estados y Veredicto (`valid` / `decision`)
+
+> **Regla de oro:** el veredicto real de la verificación está en los campos `valid` y `decision`, **no** en `workflowStatus`. `workflowStatus: "PROCESSED"` solo significa que el workflow terminó de procesar; un `PROCESSED` + `decision: "NOT_EXECUTED"` es un **rechazo**, no una aprobación.
+
+### Estados del workflow (`JumioWorkflowStatus`)
+
+- `PENDING` / `INITIATED`: En proceso de análisis por los motores de Jumio.
+- `PROCESSED`: El workflow terminó de procesar. **No implica aprobación**: el veredicto se determina con `valid` / `decision`.
+- `APPROVED_VERIFIED` / `DONE` / `COMPLETED`: Estados inequívocamente aprobados (fallback conservador).
+- `REJECTED` / `FAILED` / `DENIED` / `EXPIRED` / `ABANDONED` / `NOT_READABLE` / `FRAUD` / `UNSUPPORTED_ID_TYPE`: Estados finales no válidos.
+
+### Precedencia del veredicto
+
+El SDK resuelve la validez del resultado priorizando los campos explícitos:
+
+1. **`valid` booleano** (fuente de verdad de la gateway): `true` = aprobado, `false` = rechazado.
+2. **`decision`** presente: `PASSED` = aprobado; cualquier otro valor (`NOT_EXECUTED`, `REJECTED`, `FAILED`, etc.) = rechazado.
+3. **Fallback conservador** por `workflowStatus` (fail-closed): solo `APPROVED_VERIFIED` / `DONE` / `COMPLETED` cuentan como aprobados; si no hay `valid` ni `decision`, un `PROCESSED` se considera rechazado.
+
+> Siempre lee `result.valid` en lugar de interpretar el payload crudo de Jumio.
+
+---
+
+## 🔄 Flujo No Bloqueante y Ciclo de Vida del Polling
+
+Con `awaitFinalStatus: false` el SDK retorna de inmediato para no detener al usuario y ejecuta el sondeo (`polling`) en segundo plano consultando el estado del workflow hasta obtener un veredicto final:
+
+- El polling en segundo plano está **desacoplado del `signal`** del llamador: continúa aunque el componente que lo inició se desmonte o se aborte la señal original (navegación, cierre de pantalla). El `signal` / `AbortController` solo aplica a la fase inicial síncrona (upload y consulta de arranque).
+- El veredicto final llega a `onStatusResolved` (o a `isSuccess` / `isError` del hook); en caso de agotarse los `maxPollingAttempts` se invoca `onStatusError` con un `JumioPollingTimeoutError`.
+- Si la respuesta inicial ya trae un veredicto definitivo (p. ej. `valid: false` + `workflowStatus: "PROCESSED"`), el SDK lo resuelve de inmediato sin requerir los identificadores de seguimiento.
+
+---
+
+## 🧪 Pruebas y Construcción
+
+Para compilar y ejecutar la suite de pruebas del paquete:
+
+```bash
+# Instalar dependencias
+npm install
+
+# Ejecutar pruebas unitarias
+npm test
+
+# Compilar para producción (ESM, CJS y .d.ts)
+npm run build
+
+# Verificación de tipos TypeScript
+npm run typecheck
+```
+
+---
+
+## 📄 Licencia
+
+MIT © DynamiCore

package/dist/client-BR1xIZ0X.d.mts

@@ -0,0 +1,252 @@
+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;
+}
+/**
+ * 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>;
+}
+/**
+ * Fábrica para crear una nueva instancia de `JumioClient`.
+ */
+declare function createJumioClient(config?: JumioClientConfig): JumioClient;
+
+export { type AuthTokenProvider as A, type ImageSource as I, JumioClient as J, type PollStatusOptions as P, type S3SignerFunction as S, type VerifyIneInput as V, 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 VerifyIneResult as i, createJumioClient as j };