@ssddo/ecf-sdk 0.1.0 → 0.2.0

package/README.md

@@ -144,36 +144,103 @@ const result = await client.sendEcf(ecf, {
 
 ## Arquitectura Backend / Frontend
 
-En la mayoría de aplicaciones, el backend maneja la lógica de negocio (validación, almacenamiento, conversión) y envía el ECF. El frontend obtiene un token de solo lectura para consultar el estado directamente:
+```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
+```
+
+### Flujo detallado
+
+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`
+
+### Ejemplo: Backend
 
 ```typescript
-// Backend: tu endpoint de facturas
+import { EcfClient } from '@ssddo/ecf-sdk';
+
 const ecfClient = new EcfClient({
   apiKey: process.env.ECF_BACKEND_TOKEN,
   environment: 'prod',
 });
 
+// Endpoint de facturación
 app.post('/api/v1/invoices', async (req, res) => {
-  // 1. Validar y guardar tu factura interna
   const invoice = await validateAndSave(req.body);
-  // 2. Convertir a formato ECF
   const ecf = convertToEcf(invoice);
-  // 3. Enviar a ECF SSD
   const { data } = await ecfClient.raw.POST('/ecf/31', { body: ecf });
   await updateInvoice(invoice.id, { messageId: data.messageId });
   res.json({ id: invoice.id, messageId: data.messageId });
 });
 
-// Endpoint separado: generar token de solo lectura para el frontend
+// Generar token de solo lectura para el cliente
 app.get('/api/v1/ecf-token', async (req, res) => {
   const { data } = await ecfClient.createApiKey({ rnc: tenant.rnc });
-  res.json({ token: data.token });
+  res.json({ apiKey: data.token });
 });
 ```
 
-El frontend almacena el token de forma segura, lo renueva ante `401 Unauthorized` o expiración, y consulta ECF SSD directamente. Consulta el [README principal](../README.md#arquitectura-backend--frontend) para el diagrama completo y ejemplo con React.
+### Ejemplo: Frontend (con `EcfFrontendClient`)
+
+```typescript
+import { createFrontendClient } from '@ssddo/ecf-sdk';
 
-> **`sendEcf`** envuelve envío + polling en una sola llamada. Ideal para scripts o backends simples sin frontend.
+// 1. Enviar la factura al backend
+const invoiceRes = await fetch('/api/v1/invoices', {
+  method: 'POST',
+  body: JSON.stringify(invoiceData),
+});
+const { messageId, rnc, encf } = await invoiceRes.json();
+// El cliente no espera — puede continuar con otras operaciones
+
+// 2. Crear cliente de solo lectura (getToken se llama automáticamente)
+const frontend = createFrontendClient({
+  getToken: async () => {
+    const res = await fetch('/api/v1/ecf-token');
+    const { apiKey } = await res.json();
+    return apiKey;
+  },
+  environment: 'prod',
+  // cacheToken y getCachedToken usan localStorage por defecto
+});
+
+// 3. Consultar el estado del ECF
+const { data } = await frontend.queryEcf(rnc, encf);
+const { data: ecfs } = await frontend.searchEcfs(rnc);
+```
 
 ## Acceso directo al cliente
 

package/dist/index.cjs

@@ -412,10 +412,32 @@ var EcfFrontendClient = class {
   raw;
   constructor(config) {
     const baseUrl = config.baseUrl ?? ENVIRONMENT_URLS[config.environment ?? "test"];
+    const getToken = config.getToken;
+    const cacheToken = config.cacheToken ?? (async (token) => {
+      localStorage.setItem("ecf-token", token);
+    });
+    const getCachedToken = config.getCachedToken ?? (async () => {
+      return localStorage.getItem("ecf-token");
+    });
     const authMiddleware = {
       async onRequest({ request }) {
-        request.headers.set("Authorization", `Bearer ${config.apiKey}`);
+        let token = await getCachedToken();
+        if (!token) {
+          token = await getToken();
+          await cacheToken(token);
+        }
+        request.headers.set("Authorization", `Bearer ${token}`);
         return request;
+      },
+      async onResponse({ request, response }) {
+        if (response.status === 401) {
+          const token = await getToken();
+          await cacheToken(token);
+          const newRequest = request.clone();
+          newRequest.headers.set("Authorization", `Bearer ${token}`);
+          return fetch(newRequest);
+        }
+        return response;
       }
     };
     this.raw = (0, import_openapi_fetch.default)({ baseUrl });

package/dist/index.d.cts

@@ -6851,6 +6851,18 @@ interface EcfClientConfig {
     /** Target environment. Defaults to 'test'. */
     environment?: Environment;
 }
+interface EcfFrontendClientConfig {
+    /** Function that fetches a fresh token (e.g. calls your backend's GET /ecf-token). */
+    getToken: () => Promise<string>;
+    /** Function to cache the token. Defaults to localStorage.setItem('ecf-token', token). */
+    cacheToken?: (token: string) => Promise<void>;
+    /** Function to retrieve a cached token. Defaults to localStorage.getItem('ecf-token'). */
+    getCachedToken?: () => Promise<string | null>;
+    /** Base URL override. Takes precedence over `environment`. */
+    baseUrl?: string;
+    /** Target environment. Defaults to 'test'. */
+    environment?: Environment;
+}
 interface PollingOptions {
     /** Initial delay between polls in ms. Default: 1000 */
     initialDelay?: number;
@@ -8860,11 +8872,15 @@ declare class EcfClient {
  * A restricted, read-only client that only exposes GET endpoints.
  * Suitable for use in frontend / browser code where write operations
  * should not be available.
+ *
+ * Token lifecycle is handled automatically:
+ * - On each request, checks `getCachedToken()`. If null, calls `getToken()` then `cacheToken(token)`.
+ * - On 401 responses, calls `getToken()` again, updates the cache, and retries the request.
  */
 declare class EcfFrontendClient {
     /** The underlying openapi-fetch client for direct endpoint access. */
     private readonly raw;
-    constructor(config: EcfClientConfig);
+    constructor(config: EcfFrontendClientConfig);
     /** Query ECFs by RNC and eNCF. */
     queryEcf(rnc: string, encf: string): Promise<openapi_fetch.FetchResponse<{
         parameters: {
@@ -9296,7 +9312,7 @@ declare class EcfFrontendClient {
  * Factory that creates a restricted read-only client suitable for frontend use.
  * Only GET endpoints are exposed.
  */
-declare function createFrontendClient(config: EcfClientConfig): EcfFrontendClient;
+declare function createFrontendClient(config: EcfFrontendClientConfig): EcfFrontendClient;
 
 declare class PollingTimeoutError extends Error {
     constructor(message?: string);
@@ -9314,4 +9330,4 @@ declare class PollingMaxRetriesError extends Error {
  */
 declare function pollUntilComplete<T>(fn: () => Promise<T>, isComplete: (result: T) => boolean, options?: PollingOptions): Promise<T>;
 
-export { EcfClient, type EcfClientConfig, EcfError, EcfFrontendClient, type Environment, PollingMaxRetriesError, type PollingOptions, PollingTimeoutError, type components, createFrontendClient, type operations, type paths, pollUntilComplete };
+export { EcfClient, type EcfClientConfig, EcfError, EcfFrontendClient, type EcfFrontendClientConfig, type Environment, PollingMaxRetriesError, type PollingOptions, PollingTimeoutError, type components, createFrontendClient, type operations, type paths, pollUntilComplete };

package/dist/index.d.ts

@@ -6851,6 +6851,18 @@ interface EcfClientConfig {
     /** Target environment. Defaults to 'test'. */
     environment?: Environment;
 }
+interface EcfFrontendClientConfig {
+    /** Function that fetches a fresh token (e.g. calls your backend's GET /ecf-token). */
+    getToken: () => Promise<string>;
+    /** Function to cache the token. Defaults to localStorage.setItem('ecf-token', token). */
+    cacheToken?: (token: string) => Promise<void>;
+    /** Function to retrieve a cached token. Defaults to localStorage.getItem('ecf-token'). */
+    getCachedToken?: () => Promise<string | null>;
+    /** Base URL override. Takes precedence over `environment`. */
+    baseUrl?: string;
+    /** Target environment. Defaults to 'test'. */
+    environment?: Environment;
+}
 interface PollingOptions {
     /** Initial delay between polls in ms. Default: 1000 */
     initialDelay?: number;
@@ -8860,11 +8872,15 @@ declare class EcfClient {
  * A restricted, read-only client that only exposes GET endpoints.
  * Suitable for use in frontend / browser code where write operations
  * should not be available.
+ *
+ * Token lifecycle is handled automatically:
+ * - On each request, checks `getCachedToken()`. If null, calls `getToken()` then `cacheToken(token)`.
+ * - On 401 responses, calls `getToken()` again, updates the cache, and retries the request.
  */
 declare class EcfFrontendClient {
     /** The underlying openapi-fetch client for direct endpoint access. */
     private readonly raw;
-    constructor(config: EcfClientConfig);
+    constructor(config: EcfFrontendClientConfig);
     /** Query ECFs by RNC and eNCF. */
     queryEcf(rnc: string, encf: string): Promise<openapi_fetch.FetchResponse<{
         parameters: {
@@ -9296,7 +9312,7 @@ declare class EcfFrontendClient {
  * Factory that creates a restricted read-only client suitable for frontend use.
  * Only GET endpoints are exposed.
  */
-declare function createFrontendClient(config: EcfClientConfig): EcfFrontendClient;
+declare function createFrontendClient(config: EcfFrontendClientConfig): EcfFrontendClient;
 
 declare class PollingTimeoutError extends Error {
     constructor(message?: string);
@@ -9314,4 +9330,4 @@ declare class PollingMaxRetriesError extends Error {
  */
 declare function pollUntilComplete<T>(fn: () => Promise<T>, isComplete: (result: T) => boolean, options?: PollingOptions): Promise<T>;
 
-export { EcfClient, type EcfClientConfig, EcfError, EcfFrontendClient, type Environment, PollingMaxRetriesError, type PollingOptions, PollingTimeoutError, type components, createFrontendClient, type operations, type paths, pollUntilComplete };
+export { EcfClient, type EcfClientConfig, EcfError, EcfFrontendClient, type EcfFrontendClientConfig, type Environment, PollingMaxRetriesError, type PollingOptions, PollingTimeoutError, type components, createFrontendClient, type operations, type paths, pollUntilComplete };

package/dist/index.js

@@ -370,10 +370,32 @@ var EcfFrontendClient = class {
   raw;
   constructor(config) {
     const baseUrl = config.baseUrl ?? ENVIRONMENT_URLS[config.environment ?? "test"];
+    const getToken = config.getToken;
+    const cacheToken = config.cacheToken ?? (async (token) => {
+      localStorage.setItem("ecf-token", token);
+    });
+    const getCachedToken = config.getCachedToken ?? (async () => {
+      return localStorage.getItem("ecf-token");
+    });
     const authMiddleware = {
       async onRequest({ request }) {
-        request.headers.set("Authorization", `Bearer ${config.apiKey}`);
+        let token = await getCachedToken();
+        if (!token) {
+          token = await getToken();
+          await cacheToken(token);
+        }
+        request.headers.set("Authorization", `Bearer ${token}`);
         return request;
+      },
+      async onResponse({ request, response }) {
+        if (response.status === 401) {
+          const token = await getToken();
+          await cacheToken(token);
+          const newRequest = request.clone();
+          newRequest.headers.set("Authorization", `Bearer ${token}`);
+          return fetch(newRequest);
+        }
+        return response;
       }
     };
     this.raw = createClient({ baseUrl });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssddo/ecf-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "SDK de TypeScript para la API de ECF DGII (comprobantes fiscales electrónicos de República Dominicana)",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -21,6 +21,11 @@
   "files": [
     "dist"
   ],
+  "scripts": {
+    "generate": "openapi-typescript ../ecf_dgii/src/Apis/ECF_DGII.EcfApi/wwwroot/openapi/v1.json -o src/generated/v1.d.ts",
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
   "dependencies": {
     "openapi-fetch": "^0.13.0"
   },
@@ -56,9 +61,5 @@
     "openapi",
     "ssd"
   ],
-  "license": "MIT",
-  "scripts": {
-    "generate": "openapi-typescript ../ecf_dgii/src/Apis/ECF_DGII.EcfApi/wwwroot/openapi/v1.json -o src/generated/v1.d.ts",
-    "build": "tsup"
-  }
-}
+  "license": "MIT"
+}