@ssddo/ecf-react 0.2.0 → 0.3.0

package/README.md

@@ -207,72 +207,109 @@ Crea un cliente tipado de React Query para la API de ECF DGII.
 
 ### `createEcfFrontendReactClient(config)`
 
-Crea un cliente de solo lectura restringido a endpoints GET. No expone `useMutation`. Diseñado para el frontend donde solo se consultan ECFs con un token de solo lectura.
+Crea un cliente de solo lectura restringido a endpoints GET. No expone `useMutation`. Diseñado para el cliente donde solo se consultan ECFs con un token de solo lectura. Maneja automáticamente el caching de tokens y refresh en caso de 401.
 
-**Opciones de configuración:** mismas que `createEcfReactClient`.
+**Opciones de configuración:**
+
+| Opción | Tipo | Requerido | Descripción |
+|--------|------|-----------|-------------|
+| `getToken` | `() => Promise<string>` | Sí | Callback para obtener un token fresco (ej. fetch a tu backend) |
+| `cacheToken` | `(token: string) => Promise<void>` | No | Callback para almacenar el token (por defecto: `localStorage`) |
+| `getCachedToken` | `() => Promise<string \| null>` | No | Callback para leer el token del cache (por defecto: `localStorage`) |
+| `environment` | `'test' \| 'cert' \| 'prod'` | No | Entorno destino (por defecto: `'test'`) |
+| `baseUrl` | `string` | No | URL base personalizada (sobreescribe `environment`) |
 
 **Retorna:** `{ $api, fetchClient }`
 
 - `$api` - Cliente con solo `useQuery`, `useSuspenseQuery`, y `queryOptions` (sin `useMutation`)
 - `fetchClient` - El cliente openapi-fetch subyacente (restringido a paths GET)
 
-```tsx
-import { createEcfFrontendReactClient } from '@ssddo/ecf-react';
-
-const { $api } = createEcfFrontendReactClient({
-  apiKey: token,
-  environment: 'prod',
-});
-
-// ✅ Funciona — endpoint GET
-$api.useQuery('get', '/ecf/{rnc}/{encf}', { params: { path: { rnc, encf } } });
+## Arquitectura Backend / Frontend
 
-// ❌ Error de tipo — useMutation no está disponible
-// $api.useMutation('post', '/ecf/31');
+```mermaid
+sequenceDiagram
+    participant C as Cliente (Browser/App)
+    participant BE as Backend
+    participant ECF as ECF API
+
+    C->>BE: POST /invoice (datos de factura)
+    Note over BE: Valida, guarda y convierte a formato ECF
+
+    BE->>ECF: POST /ecf/{tipo} (enviar ECF)
+    ECF-->>BE: { messageId }
+    BE-->>C: { messageId }
+
+    Note over C: No espera — puede continuar
+
+    alt Token en cache
+        C->>C: Usar token existente
+    else Sin token o expirado
+        C->>BE: GET /ecf-token
+        BE->>ECF: POST /apikey (solo lectura, scoped a RNC)
+        ECF-->>BE: { apiKey }
+        BE-->>C: { apiKey }
+        C->>C: Almacenar token en cache
+    end
+
+    loop Polling hasta completar
+        C->>ECF: GET /ecf/{rnc}/{encf} (token solo lectura)
+        ECF-->>C: { progress, codSec, ... }
+    end
 ```
 
-## Arquitectura Backend / Frontend
-
-El SDK de React está diseñado para el lado del **frontend** de la arquitectura recomendada:
+### Flujo detallado
 
-1. Tu **backend** valida, guarda y convierte tu factura interna al formato ECF, luego la envía a ECF SSD usando su token principal
-2. Tu **backend** expone un endpoint (ej. `GET /api/v1/ecf-token`) que genera un **API key de solo lectura** con alcance al tenant/RNC a través del endpoint `/apikey` de ECF SSD
-3. Tu **frontend** almacena este token de forma segura, lo renueva ante `401` o expiración, y lo usa con `@ssddo/ecf-react` para consultar el estado de los ECF directamente
+1. El **cliente** (browser/app) envía los datos de la factura al **backend** (`POST /invoice`, `/order`, `/sale`)
+2. El **backend** valida, guarda y convierte la factura interna al formato ECF
+3. El **backend** envía el ECF a la API de ECF SSD (`POST /ecf/{tipo}`) y recibe un `messageId`
+4. El **backend** retorna el `messageId` al cliente — **el cliente no espera**, puede continuar
+5. Cuando el cliente necesita consultar el estado del ECF, usa `EcfFrontendClient` que internamente:
+   - Verifica si hay un **token de solo lectura** en cache
+   - Si **no existe o expiró**: llama a `getToken()` (que el consumidor provee — típicamente un `fetch('/ecf-token')` a su backend), luego llama a `cacheToken(token)` para almacenarlo
+   - Si la API retorna **401**: automáticamente llama a `getToken()` de nuevo, actualiza el cache, y reintenta
+6. El cliente hace **polling** directamente contra la API de ECF SSD (`GET /ecf/{rnc}/{encf}`) hasta que `progress` sea `Finished`
 
 ```tsx
-// Gestión de token — tu hook personalizado
-// Llama al endpoint /api/v1/ecf-token de tu backend, almacena el token de forma segura,
-// y lo renueva automáticamente cuando expira o recibe un 401
-const ecfToken = useEcfToken();
+import { createEcfFrontendReactClient } from '@ssddo/ecf-react';
 
+// 1. Crear cliente de solo lectura (getToken se llama automáticamente)
 const { $api } = createEcfFrontendReactClient({
-  apiKey: ecfToken,  // solo lectura, con alcance al tenant/RNC
+  getToken: async () => {
+    const res = await fetch('/api/v1/ecf-token');
+    const { apiKey } = await res.json();
+    return apiKey;
+  },
   environment: 'prod',
 });
 
+// 2. El componente que envía la factura al backend
+function EnviarFactura() {
+  const handleSubmit = async (invoiceData) => {
+    // Enviar factura al backend — el cliente no espera por el procesamiento ECF
+    const res = await fetch('/api/v1/invoices', {
+      method: 'POST',
+      body: JSON.stringify(invoiceData),
+    });
+    const { messageId, rnc, encf } = await res.json();
+    // Navegar a la página de estado o mostrar el componente de polling
+    navigate(`/ecf-status/${rnc}/${encf}`);
+  };
+}
+
+// 3. El componente que consulta el estado del ECF (polling automático)
 function EstadoEcf({ rnc, encf }: { rnc: string; encf: string }) {
-  // Consulta ECF SSD directamente — no se necesita proxy en el backend
   const { data } = $api.useQuery('get', '/ecf/{rnc}/{encf}', {
     params: { path: { rnc, encf } },
     refetchInterval: 3000,
   });
 
   if (data?.progress === 'Finished') {
-    return (
-      <div>
-        <p>Comprobante aceptado</p>
-        <p>Código seguridad: {data.codSec}</p>
-        <QRCode value={data.impresionUrl} />
-      </div>
-    );
+    return <p>Comprobante aceptado — código: {data.codSec}</p>;
   }
-
   return <p>Procesando... ({data?.progress})</p>;
 }
 ```
 
-Este patrón descarga el polling de tu backend y permite que el frontend se comunique directamente con ECF SSD usando un token restringido. Consulta el [README principal](../README.md#arquitectura-backend--frontend) para el diagrama completo y ejemplo del backend.
-
 ## Uso fuera de React
 
 Para aplicaciones del lado del servidor o sin React, usa el SDK base de TypeScript: [`@ssddo/ecf-sdk`](https://www.npmjs.com/package/@ssddo/ecf-sdk).

package/dist/index.d.mts

@@ -6865,7 +6865,14 @@ type ReadOnlyPaths = {
         patch?: never;
     };
 };
-declare function createEcfFrontendReactClient(config: EcfReactClientConfig): {
+interface EcfFrontendReactClientConfig {
+    getToken: () => Promise<string>;
+    cacheToken?: (token: string) => Promise<void>;
+    getCachedToken?: () => Promise<string | null>;
+    baseUrl?: string;
+    environment?: Environment;
+}
+declare function createEcfFrontendReactClient(config: EcfFrontendReactClientConfig): {
     $api: {
         useQuery: openapi_react_query.UseQueryMethod<ReadOnlyPaths, `${string}/${string}`>;
         useSuspenseQuery: openapi_react_query.UseSuspenseQueryMethod<ReadOnlyPaths, `${string}/${string}`>;
@@ -6874,4 +6881,4 @@ declare function createEcfFrontendReactClient(config: EcfReactClientConfig): {
     fetchClient: openapi_fetch.Client<ReadOnlyPaths, `${string}/${string}`>;
 };
 
-export { type EcfReactClientConfig, type Environment, type components, createEcfFrontendReactClient, createEcfReactClient, type operations, type paths };
+export { type EcfFrontendReactClientConfig, type EcfReactClientConfig, type Environment, type components, createEcfFrontendReactClient, createEcfReactClient, type operations, type paths };

package/dist/index.d.ts

@@ -6865,7 +6865,14 @@ type ReadOnlyPaths = {
         patch?: never;
     };
 };
-declare function createEcfFrontendReactClient(config: EcfReactClientConfig): {
+interface EcfFrontendReactClientConfig {
+    getToken: () => Promise<string>;
+    cacheToken?: (token: string) => Promise<void>;
+    getCachedToken?: () => Promise<string | null>;
+    baseUrl?: string;
+    environment?: Environment;
+}
+declare function createEcfFrontendReactClient(config: EcfFrontendReactClientConfig): {
     $api: {
         useQuery: openapi_react_query.UseQueryMethod<ReadOnlyPaths, `${string}/${string}`>;
         useSuspenseQuery: openapi_react_query.UseSuspenseQueryMethod<ReadOnlyPaths, `${string}/${string}`>;
@@ -6874,4 +6881,4 @@ declare function createEcfFrontendReactClient(config: EcfReactClientConfig): {
     fetchClient: openapi_fetch.Client<ReadOnlyPaths, `${string}/${string}`>;
 };
 
-export { type EcfReactClientConfig, type Environment, type components, createEcfFrontendReactClient, createEcfReactClient, type operations, type paths };
+export { type EcfFrontendReactClientConfig, type EcfReactClientConfig, type Environment, type components, createEcfFrontendReactClient, createEcfReactClient, type operations, type paths };

package/dist/index.js

@@ -57,15 +57,38 @@ function createEcfReactClient(config) {
   const $api = (0, import_openapi_react_query.default)(fetchClient);
   return { $api, fetchClient };
 }
+var defaultCacheToken = async (token) => {
+  localStorage.setItem("ecf-token", token);
+};
+var defaultGetCachedToken = async () => {
+  return localStorage.getItem("ecf-token");
+};
 function createEcfFrontendReactClient(config) {
   const baseUrl = config.baseUrl ?? ENVIRONMENT_URLS[config.environment ?? "test"];
+  const cacheToken = config.cacheToken ?? defaultCacheToken;
+  const getCachedToken = config.getCachedToken ?? defaultGetCachedToken;
   const fetchClient = (0, import_openapi_fetch.default)({
     baseUrl
   });
   fetchClient.use({
     async onRequest({ request }) {
-      request.headers.set("Authorization", `Bearer ${config.apiKey}`);
+      let token = await getCachedToken();
+      if (!token) {
+        token = await config.getToken();
+        await cacheToken(token);
+      }
+      request.headers.set("Authorization", `Bearer ${token}`);
       return request;
+    },
+    async onResponse({ request, response }) {
+      if (response.status === 401) {
+        const token = await config.getToken();
+        await cacheToken(token);
+        const retryRequest = request.clone();
+        retryRequest.headers.set("Authorization", `Bearer ${token}`);
+        return fetch(retryRequest);
+      }
+      return response;
     }
   });
   const fullApi = (0, import_openapi_react_query.default)(fetchClient);

package/dist/index.mjs

@@ -20,15 +20,38 @@ function createEcfReactClient(config) {
   const $api = createClient(fetchClient);
   return { $api, fetchClient };
 }
+var defaultCacheToken = async (token) => {
+  localStorage.setItem("ecf-token", token);
+};
+var defaultGetCachedToken = async () => {
+  return localStorage.getItem("ecf-token");
+};
 function createEcfFrontendReactClient(config) {
   const baseUrl = config.baseUrl ?? ENVIRONMENT_URLS[config.environment ?? "test"];
+  const cacheToken = config.cacheToken ?? defaultCacheToken;
+  const getCachedToken = config.getCachedToken ?? defaultGetCachedToken;
   const fetchClient = createFetchClient({
     baseUrl
   });
   fetchClient.use({
     async onRequest({ request }) {
-      request.headers.set("Authorization", `Bearer ${config.apiKey}`);
+      let token = await getCachedToken();
+      if (!token) {
+        token = await config.getToken();
+        await cacheToken(token);
+      }
+      request.headers.set("Authorization", `Bearer ${token}`);
       return request;
+    },
+    async onResponse({ request, response }) {
+      if (response.status === 401) {
+        const token = await config.getToken();
+        await cacheToken(token);
+        const retryRequest = request.clone();
+        retryRequest.headers.set("Authorization", `Bearer ${token}`);
+        return fetch(retryRequest);
+      }
+      return response;
     }
   });
   const fullApi = createClient(fetchClient);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssddo/ecf-react",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Hooks de React Query para la API de ECF DGII (comprobantes fiscales electrónicos de República Dominicana)",
   "main": "dist/index.js",
   "module": "dist/index.mjs",