@ssddo/ecf-react 0.1.5 → 0.3.0

package/README.md

@@ -205,48 +205,111 @@ Crea un cliente tipado de React Query para la API de ECF DGII.
 - `$api` - El cliente openapi-react-query con `useQuery`, `useMutation`, `useSuspenseQuery`, etc.
 - `fetchClient` - El cliente openapi-fetch subyacente para uso fuera de React.
 
+### `createEcfFrontendReactClient(config)`
+
+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:**
+
+| 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)
+
 ## Arquitectura Backend / Frontend
 
-El SDK de React está diseñado para el lado del **frontend** de la arquitectura recomendada:
+```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
+```
 
-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
+### Flujo detallado
 
-```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();
+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`
 
-const { $api } = createEcfReactClient({
-  apiKey: ecfToken,  // solo lectura, con alcance al tenant/RNC
+```tsx
+import { createEcfFrontendReactClient } from '@ssddo/ecf-react';
+
+// 1. Crear cliente de solo lectura (getToken se llama automáticamente)
+const { $api } = createEcfFrontendReactClient({
+  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

@@ -6852,5 +6852,33 @@ declare function createEcfReactClient(config: EcfReactClientConfig): {
     $api: openapi_react_query.OpenapiQueryClient<paths, `${string}/${string}`>;
     fetchClient: openapi_fetch.Client<paths, `${string}/${string}`>;
 };
+type PathsWithGet = {
+    [K in keyof paths as paths[K] extends {
+        get: unknown;
+    } ? K : never]: paths[K];
+};
+type ReadOnlyPaths = {
+    [K in keyof PathsWithGet]: Pick<PathsWithGet[K], 'get' | 'parameters'> & {
+        put?: never;
+        post?: never;
+        delete?: never;
+        patch?: never;
+    };
+};
+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}`>;
+        queryOptions: openapi_react_query.QueryOptionsFunction<ReadOnlyPaths, `${string}/${string}`>;
+    };
+    fetchClient: openapi_fetch.Client<ReadOnlyPaths, `${string}/${string}`>;
+};
 
-export { type EcfReactClientConfig, type Environment, type components, 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

@@ -6852,5 +6852,33 @@ declare function createEcfReactClient(config: EcfReactClientConfig): {
     $api: openapi_react_query.OpenapiQueryClient<paths, `${string}/${string}`>;
     fetchClient: openapi_fetch.Client<paths, `${string}/${string}`>;
 };
+type PathsWithGet = {
+    [K in keyof paths as paths[K] extends {
+        get: unknown;
+    } ? K : never]: paths[K];
+};
+type ReadOnlyPaths = {
+    [K in keyof PathsWithGet]: Pick<PathsWithGet[K], 'get' | 'parameters'> & {
+        put?: never;
+        post?: never;
+        delete?: never;
+        patch?: never;
+    };
+};
+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}`>;
+        queryOptions: openapi_react_query.QueryOptionsFunction<ReadOnlyPaths, `${string}/${string}`>;
+    };
+    fetchClient: openapi_fetch.Client<ReadOnlyPaths, `${string}/${string}`>;
+};
 
-export { type EcfReactClientConfig, type Environment, type components, createEcfReactClient, type operations, type paths };
+export { type EcfFrontendReactClientConfig, type EcfReactClientConfig, type Environment, type components, createEcfFrontendReactClient, createEcfReactClient, type operations, type paths };

package/dist/index.js

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  createEcfFrontendReactClient: () => createEcfFrontendReactClient,
   createEcfReactClient: () => createEcfReactClient
 });
 module.exports = __toCommonJS(index_exports);
@@ -56,7 +57,50 @@ 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 }) {
+      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);
+  const $api = {
+    useQuery: fullApi.useQuery,
+    useSuspenseQuery: fullApi.useSuspenseQuery,
+    queryOptions: fullApi.queryOptions
+  };
+  return { $api, fetchClient };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  createEcfFrontendReactClient,
   createEcfReactClient
 });

package/dist/index.mjs

@@ -20,6 +20,49 @@ 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 }) {
+      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);
+  const $api = {
+    useQuery: fullApi.useQuery,
+    useSuspenseQuery: fullApi.useSuspenseQuery,
+    queryOptions: fullApi.queryOptions
+  };
+  return { $api, fetchClient };
+}
 export {
+  createEcfFrontendReactClient,
   createEcfReactClient
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssddo/ecf-react",
-  "version": "0.1.5",
+  "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",