@dynamicore/jumio-sdk 1.0.1 → 1.0.2

package/README.md

@@ -1,6 +1,6 @@
 # @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.
+> SDK modular, tipado y agnóstico para la validación de identidad mediante **Jumio** en el ecosistema DynamiCore. Soporta tanto el flujo de **Hosted Webflow (Redirección Web)** como el de **Carga Directa de Documentos (INE API)**.
 
 [![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/)
@@ -12,17 +12,15 @@
 
 ---
 
-## 🌟 Características
+## 🌟 Modalidades de Verificación Soportadas
 
-- **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`).
+| Característica | 🌐 1. Hosted Webflow (Redirección) | 📄 2. Carga Directa (INE API) |
+| :--- | :--- | :--- |
+| **Experiencia de Usuario** | El usuario es redirigido a la interfaz alojada oficial de Jumio para captura biométrica y de documentos. | El usuario permanece en tu app; tu interfaz captura/sube las imágenes de la INE. |
+| **Casos de Uso** | Panel web, onboarding sin cámara nativa, verificación biométrica completa + Liveness. | Formularios web/móviles integrados con controles de archivo personalizados. |
+| **Entrada Requerida** | `clientId`, `successUrl`, `errorUrl` | `clientId`, `frontImage`, `backImage` |
+| **Hooks de React** | `useJumioWebflow` | `useJumioVerification` |
+| **Métodos de Core** | `startWebflow`, `getWebflowStatus`, `pollWebflowStatus`, `parseWebflowReturnParams`, `buildRedirectUrl` | `startIneVerification`, `getIneStatus`, `verifyIne`, `pollIneStatus` |
 
 ---
 
@@ -31,110 +29,229 @@
 ### Desde npm / registro privado:
 ```bash
 npm install @dynamicore/jumio-sdk axios
-# o con pnpm:
+# o con pnpm / yarn:
 pnpm add @dynamicore/jumio-sdk axios
-# o con yarn:
-yarn add @dynamicore/jumio-sdk axios
 ```
 
-### O en proyectos locales (Monorepo o Enlace local):
+### En proyectos locales (Monorepo o enlace local):
 ```bash
 npm install file:../jumio-sdk
 ```
 
 ---
 
-## 🚀 Guía de Uso
+## 🚀 Guías y Ejemplos de Uso
 
-### 1. Uso con React / Next.js (`useJumioVerification`)
+---
 
-```tsx
-import React, { useState } from "react";
-import { useJumioVerification } from "@dynamicore/jumio-sdk/react";
+### 🌐 Servicio 1: Hosted Webflow (Redirección Web)
+
+En este flujo, la app solicita una sesión webflow, redirige al cliente a Jumio (`href`) y consulta el veredicto al regresar.
+
+> [!NOTE]
+> Llegar a `successUrl` solo significa que el usuario **completó los pasos en Jumio**, no que fue aprobado. Llegar a `errorUrl` significa que **abandonó o falló el flujo**. El veredicto real (`PASSED` / `WARNING` / `REJECTED` + `extraction`) solo se obtiene consultando el estado con `accountId` + `workflowId` (`getWebflowStatus` una vez, o `pollWebflowStatus` con sondeo). Por eso ambos suelen apuntar a la misma ruta `/verify/return`.
 
-export function IneVerificationStep({ clientId, onNext }: { clientId: string; onNext: () => void }) {
-  const [frontFile, setFrontFile] = useState<File | null>(null);
-  const [backFile, setBackFile] = useState<File | null>(null);
+#### A. Ejemplo con React / Next.js (`useJumioWebflow`)
+
+**Paso 1: Iniciar la verificación (Pantalla de Inicio)**
 
-  const {
-    verify,
-    isSubmitting,
-    isPolling,
-    isLoading,
-    stage,
-    progress,
-    result,
-    error,
-    reset,
-  } = useJumioVerification({
+```tsx
+import React from "react";
+import { useJumioWebflow } from "@dynamicore/jumio-sdk/react";
+
+export function StartIdentityVerification({ clientId }: { clientId: string }) {
+  const { startWebflow, isStarting, error } = useJumioWebflow({
     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);
-    },
+    context: process.env.NEXT_PUBLIC_DYNAMICORE_CONTEXT,
+    // Opcional: URL base para proxy de redirección
+    redirectProxyUrl: "https://inllhuznm2.execute-api.us-west-2.amazonaws.com/prod/jumio/redirect/",
   });
 
-  const handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault();
-    if (!frontFile || !backFile) return;
-
+  const handleStart = async () => {
     try {
-      // awaitFinalStatus: false permite avanzar en el flujo sin esperar 2 minutos
-      const res = await verify({
+      const baseUrl = window.location.origin;
+      await startWebflow({
         clientId,
-        frontImage: frontFile,
-        backImage: backFile,
-        awaitFinalStatus: false,
+        successUrl: `${baseUrl}/verify/return`,
+        errorUrl: `${baseUrl}/verify/return`,
+        useRedirectProxy: true, // Codifica las URLs en Base64 URL-safe con proxy
+        openInNewTab: true,     // Abre Jumio en una nueva pestaña (window.open) sin salir de la app
+        // autoRedirect: true,  // O redirige en la misma pestaña (window.location.href)
       });
 
-      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>
+      <h3>Verificación de Identidad</h3>
+      {error && <p style={{ color: "red" }}>{error.message}</p>}
+      <button onClick={handleStart} disabled={isStarting}>
+        {isStarting ? "Cargando..." : "Iniciar Verificación con Jumio"}
+      </button>
+    </div>
+  );
+}
+```
+
+**Paso 2: Procesar el retorno (Pantalla `/verify/return`)**
+
+```tsx
+import React, { useEffect } from "react";
+import { useJumioWebflow } from "@dynamicore/jumio-sdk/react";
+
+export function IdentityReturnPage({ clientId }: { clientId: string }) {
+  const { parseReturnParams, checkResult, isChecking, result, isValid, isRejected, error } =
+    useJumioWebflow({
+      baseUrl: process.env.NEXT_PUBLIC_API_URL,
+      context: process.env.NEXT_PUBLIC_DYNAMICORE_CONTEXT,
+      onResult: (res) => {
+        if (res.valid) {
+          console.log("¡Verificación aprobada!", res.extraction);
+        }
+      },
+    });
+
+  useEffect(() => {
+    // 1. Extraer accountId y workflowId de los query params de la URL
+    const { accountId, workflowId } = parseReturnParams();
+
+    if (accountId && workflowId) {
+      // 2. Sondear el resultado final (acepta { maxAttempts, pollingIntervalMs, signal })
+      // Para una sola consulta sin sondeo: await client.getWebflowStatus({ accountId, workflowId, clientId })
+      // Retorna null si aún está pendiente.
+      checkResult({ accountId, workflowId, clientId });
+    }
+    return () => cancel(); // Limpia el sondeo si el componente se desmonta (abort resetea isChecking)
+  }, []);
+
+  if (isChecking) {
+    return <p>Verificando identidad, por favor espera un momento...</p>;
+  }
+
+  if (isValid) {
+    return (
       <div>
-        <label>Frente de INE:</label>
-        <input
-          type="file"
-          accept="image/*"
-          onChange={(e) => setFrontFile(e.target.files?.[0] || null)}
-        />
+        <h2>✅ Verificación Completada</h2>
+        <p>CURP Extraída: {String(result?.extraction?.curp || "N/A")}</p>
       </div>
+    );
+  }
 
+  if (isRejected || error) {
+    return (
       <div>
-        <label>Reverso de INE:</label>
-        <input
-          type="file"
-          accept="image/*"
-          onChange={(e) => setBackFile(e.target.files?.[0] || null)}
-        />
+        <h2>❌ Verificación No Aprobada</h2>
+        <p>{error?.message || "El documento fue rechazado."}</p>
       </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>
-      )}
+  return <p>Cargando información de la sesión...</p>;
+}
+```
+
+---
+
+#### B. Ejemplo con TypeScript / Node.js (`JumioClient`)
+
+```typescript
+import { JumioClient } from "@dynamicore/jumio-sdk";
+
+const jumio = new JumioClient({
+  baseUrl: "https://front.dynamicore.io",
+  context: "MI_CONTEXTO_NEGOCIO",
+  authToken: () => getAuthTokenFromSession(),
+  redirectProxyUrl: "https://inllhuznm2.execute-api.us-west-2.amazonaws.com/prod/jumio/redirect/",
+});
+
+// 1. Solicitar la URL de verificación
+async function initVerificationSession(clientId: string) {
+  const { href, accountId, workflowId } = await jumio.startWebflow({
+    clientId,
+    successUrl: "https://myapp.com/identity/callback",
+    errorUrl: "https://myapp.com/identity/callback",
+    useRedirectProxy: true,
+  });
+
+  console.log("Redirigir cliente a:", href);
+  return { href, accountId, workflowId };
+}
+
+// 2. Consultar o sonder el resultado al regresar
+async function verifyReturnStatus(returnUrl: string, clientId: string) {
+  const { accountId, workflowId } = jumio.parseWebflowReturnParams(returnUrl);
+
+  if (!accountId || !workflowId) {
+    throw new Error("No se encontraron parámetros de seguimiento en la URL.");
+  }
+
+  const result = await jumio.pollWebflowStatus(
+    { accountId, workflowId, clientId },
+    { maxAttempts: 15, pollingIntervalMs: 5000 }
+  );
+
+  if (result.valid) {
+    console.log("Veredicto APROBADO:", result.extraction);
+  } else {
+    console.warn("Veredicto RECHAZADO:", result.errorMessage);
+  }
+
+  return result;
+}
+```
+
+---
 
-      {error && <p className="text-red-500">{error.message}</p>}
+### 📄 Servicio 2: Carga Directa de INE (INE API)
+
+En este flujo, la app captura las imágenes de la INE (frente y reverso) en su propia interfaz y las envía directamente al backend.
+
+#### A. Ejemplo con React / Next.js (`useJumioVerification`)
+
+```tsx
+import React, { useState } from "react";
+import { useJumioVerification } from "@dynamicore/jumio-sdk/react";
+
+export function DirectIneVerificationStep({ 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, error } =
+    useJumioVerification({
+      baseUrl: process.env.NEXT_PUBLIC_API_URL,
+      context: process.env.NEXT_PUBLIC_DYNAMICORE_CONTEXT,
+      onStatusResolved: (res) => {
+        if (res.valid) {
+          onNext();
+        }
+      },
+    });
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!frontFile || !backFile) return;
+
+    await verify({
+      clientId,
+      frontImage: frontFile,
+      backImage: backFile,
+      awaitFinalStatus: false, // Sondeo en 2do plano sin bloquear la UI
+    });
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input type="file" accept="image/*" onChange={(e) => setFrontFile(e.target.files?.[0] || null)} />
+      <input type="file" accept="image/*" onChange={(e) => setBackFile(e.target.files?.[0] || null)} />
+
+      {isLoading && <p>Estado: {stage} ({progress}%)</p>}
+      {error && <p style={{ color: "red" }}>{error.message}</p>}
 
       <button type="submit" disabled={isLoading || !frontFile || !backFile}>
-        {isLoading ? "Validando..." : "Continuar"}
+        Continuar
       </button>
     </form>
   );
@@ -143,41 +260,34 @@ export function IneVerificationStep({ clientId, onNext }: { clientId: string; on
 
 ---
 
-### 2. Uso con TypeScript / Node.js / Core (`JumioClient`)
+#### B. Ejemplo con TypeScript / Node.js (`JumioClient.verifyIne`)
 
 ```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);
-  },
+  context: "MI_CONTEXTO_NEGOCIO",
+  authToken: () => getAuthTokenFromSession(),
 });
 
-async function runVerification() {
+async function runDirectVerification() {
   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
+      awaitFinalStatus: true,
     });
 
     if (result.valid) {
-      console.log("Validación completada con éxito:", result.data);
+      console.log("INE validada con éxito:", result.data);
     } else {
-      console.warn("Documento rechazado:", result.errorMessage);
+      console.warn("INE rechazada:", 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);
     }
   }
 }
@@ -191,85 +301,50 @@ async function runVerification() {
 | :--- | :--- | :--- | :--- |
 | `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.
-
----
-
+| `context` | `string` | `undefined` | Header de contexto enviado en las peticiones. |
+| `authToken` | `string \| Provider` | `undefined` | Token Bearer o función proveedora dinámica. |
+| `authTokenPrefix` | `string` | `""` | Prefijo del header `Authorization` (ej. `"Bearer"`). |
+| `redirectProxyUrl` | `string` | `undefined` | URL base del proxy de redirección para Hosted Webflow. |
+| `requestTimeout` | `number` | `180000` (3 min) | Timeout para peticiones POST. |
+| `statusTimeout` | `number` | `120000` (2 min) | Timeout para peticiones GET de estado. |
+| `maxRetries` | `number` | `3` | Número de reintentos ante caídas de red. |
+| `retryDelayMs` | `number` | `800` | Delay base del backoff exponencial entre reintentos. |
+| `pollingIntervalMs` | `number` | `10000` (10s) | Intervalo entre consultas de sondeo. |
+| `maxPollingAttempts` | `number` | `20` | Máximo de consultas de sondeo antes de timeout. |
+| `s3Signer` | `S3SignerFunction` | `undefined` | Función para firmar rutas privadas de S3. |
+| `customHeaders` | `Record<string,string>` | `undefined` | Headers adicionales en cada petición. |
+| `axiosInstance` | `AxiosInstance` | `undefined` | Instancia propia de Axios (opcional). |
+
+---
+
+## 🧰 Helpers y notas del flujo Webflow
+
+- `client.buildRedirectUrl(returnUrl, useProxy)` / `buildRedirectUrl(url, proxy)` — construye la URL de retorno, con Base64 URL-safe si usas `redirectProxyUrl`.
+- `client.getWebflowStatus({ accountId, workflowId, clientId })` — una sola consulta `GET ?type=ine&accountId&workflowId&clientId`; retorna `WebflowResult | null` (`null` = pendiente).
+- `client.pollWebflowStatus(params, { maxAttempts, pollingIntervalMs, signal, onAttempt })` — sondeo hasta veredicto o `JumioPollingTimeoutError`.
+- Hooks exponen `cancel()` / `reset()`; un abort (desmontaje, `cancel`, StrictMode) baja `isChecking/isStarting/isLoading` sin marcar error.
+- El backend puede responder con envelope `{ data }` o `{ values }` y datos anidados; el SDK los desempaqueta. `parseWebflowReturnParams` acepta `workflowExecutionId` / `workflowId` y params anidados en `?status=`.
+
+---
+
 ## 🧪 Pruebas y Construcción
 
-Para compilar y ejecutar la suite de pruebas del paquete:
-
 ```bash
 # Instalar dependencias
 npm install
 
-# Ejecutar pruebas unitarias
+# Ejecutar suite completa de pruebas unitarias (59 tests)
 npm test
 
-# Compilar para producción (ESM, CJS y .d.ts)
-npm run build
-
 # Verificación de tipos TypeScript
 npm run typecheck
+
+# Compilar para producción (ESM, CJS y .d.ts)
+npm run build
 ```
 
 ---
 
 ## 📄 Licencia
 
-MIT © DynamiCore
+MIT © DynamiCore