arca-sdk 0.4.0 → 0.5.0

package/README.md

@@ -5,8 +5,9 @@
 SDK en TypeScript para integración con servicios de ARCA:
 - ✅ **Type-safe**: TypeScript strict mode
 - ✅ **Simple**: No más XML manual
-- ✅ **Automático**: Cache de tokens, retry logic
-- ✅ **Fiscal**: Generador de QR oficial AFIP integrado
+- ✅ **Automático**: Cache de tokens, persistencia opcional (God Mode)
+- ✅ **Fiscal**: Generador de QR oficial ARCA/AFIP ultra-robusto
+- ✅ **Padrón**: Consulta de CUIT (A13) para autocompletado de datos
 - ✅ **Resiliente**: Maneja errores SSL ("dh key too small") y timeouts
 - ✅ **Moderno**: ESM + CJS nativo, Node.js 18+
 
@@ -23,283 +24,128 @@ bun add arca-sdk
 
 ## ⚡ Quick Start
 ```typescript
-import { WsaaService } from 'arca-sdk';
-import * as fs from 'node:fs';
-
-// 1. Crear servicio con tus certificados
-const wsaa = new WsaaService({
-  environment: 'homologacion',  // 'homologacion' o 'produccion'
-  cuit: '20123456789',
-  cert: fs.readFileSync('./cert.pem', 'utf-8'),
-  key: fs.readFileSync('./key.pem', 'utf-8'),
-  service: 'wsfe',
-});
-
-// 2. Obtener ticket (automático, con cache)
-const ticket = await wsaa.login();
-
-// 3. Usar token en otros servicios ARCA
-console.log('Token:', ticket.token);
-```
-
-**Eso es todo.** No XML. No SOAP. No pain.
-
----
-
-## 📖 Servicios Disponibles
-
-### WSAA - Autenticación
-```typescript
-import { WsaaService } from 'arca-sdk';
+import { WsaaService, WsfeService } from 'arca-sdk';
 
-const wsaa = new WsaaService({
+// 1. Configuración base
+const config = {
   environment: 'homologacion',
   cuit: '20123456789',
   cert: '...certificado PEM...',
   key: '...clave privada PEM...',
-  service: 'wsfe',  // o 'wsmtxca', etc
-});
-
-const ticket = await wsaa.login();
-// Ticket válido por ~12 horas
-// Se renueva automáticamente
-```
+};
 
-### WSFE - Facturación
-```typescript
+// 2. Emitir un Ticket C en dos líneas
 const wsfe = new WsfeService(config);
-const cae = await wsfe.emitirFacturaC({ items });
-console.log('CAE:', cae.cae);
-```
-
----
+const result = await wsfe.emitirTicketCSimple({ total: 1500 });
 
-## 🔑 Certificados
-
-Necesitás certificados de ARCA en formato PEM:
-- `cert.pem`: Certificado X.509
-- `key.pem`: Clave privada
-
-**Homologación (testing):**
-1. Ir a [ARCA Homologación](https://www.afip.gob.ar/ws/documentacion/certificados.asp)
-2. Generar certificado de prueba
-3. Descargar cert + key
-
-**Producción:**
-1. Generar CSR con tu CUIT
-2. Subir a ARCA
-3. Descargar certificado firmado
-
----
-
-## 🛠️ Ejemplos
-
-Ver carpeta [`/examples`](./examples):
-- [`autenticacion.ts`](./examples/autenticacion.ts) - Obtener ticket WSAA
-- [`quick-start.ts`](./examples/quick-start.ts) - Inicio rápido
-
----
-
-## 🧪 Testing
-```bash
-# Tests unitarios
-bun test
-
-# Build
-bun run build
+console.log('CAE:', result.cae);
+console.log('QR URL:', result.urlQr); // ← Ya viene integrado!
 ```
 
 ---
 
-## 📝 TypeScript
-
-La SDK exporta todos los tipos:
-```typescript
-import type { 
-  LoginTicket, 
-  WsaaConfig, 
-  Environment 
-} from 'arca-sdk';
-```
-
-Autocomplete completo en tu IDE. ✨
-
----
+## 👑 God Mode: Persistencia Automática
+No manejes tickets manualmente. Pasale un `storage` al SDK y se encargará de guardar, recuperar y renovar el token solo cuando expire.
 
-## ⚠️ Manejo de Errores
 ```typescript
-import { ArcaAuthError, ArcaValidationError } from 'arca-sdk';
-
-try {
-  const ticket = await wsaa.login();
-} catch (error) {
-  if (error instanceof ArcaAuthError) {
-    console.error('Error de autenticación:', error.message);
-  }
-  
-  if (error instanceof ArcaValidationError) {
-    console.error('Configuración inválida:', error.message);
-  }
-}
-```
-
-Los errores incluyen contexto útil en `error.details`.
-
-#### Timeouts
-Por defecto, las peticiones tienen un timeout de **15 segundos**. Podés ajustarlo en la configuración:
-```typescript
-const wsfe = new WsfeService({
+const wsaa = new WsaaService({
   ...config,
-  timeout: 30000 // 30 segundos
+  service: 'wsfe',
+  storage: {
+    get: async (key) => await db.token.findUnique({ where: { key } }),
+    save: async (key, data) => await db.token.upsert({ ... }),
+  }
 });
+
+// El SDK chequea el storage antes de pedir un nuevo ticket a ARCA
+const ticket = await wsaa.login();
 ```
 
 ---
 
-### WSFE - Facturación Electrónica
+## 🔍 Consulta de Padrón (A13)
+Obtené los datos de un cliente (Nombre, Domicilio, IVA) solo con su CUIT. Ideal para POS.
 
-#### Ticket C Simple (solo total)
 ```typescript
-import { WsaaService, WsfeService } from 'arca-sdk';
+import { PadronService } from 'arca-sdk';
 
-// 1. Autenticar
-const wsaa = new WsaaService({ ... });
-const ticket = await wsaa.login();
+const padron = new PadronService(config);
+const { persona, error } = await padron.getPersona('30111111118');
 
-// 2. Crear servicio WSFE
-const wsfe = new WsfeService({
-  environment: 'homologacion',
-  cuit: '20123456789',
-  ticket,
-  puntoVenta: 4,
-});
-
-// 3. Emitir ticket (modo simple)
-const cae = await wsfe.emitirTicketCSimple({ 
-  total: 3500 
-});
-
-console.log('CAE:', cae.cae);
+if (persona) {
+  console.log('Razón Social:', persona.razonSocial || `${persona.nombre} ${persona.apellido}`);
+  console.log('Provincia:', persona.domicilio[0].descripcionProvincia);
+  console.log('¿Es Inscripto?:', persona.esInscriptoIVA);
+}
 ```
 
-#### Ticket C con Items
-```typescript
-// Modo completo: con detalle de items
-const cae = await wsfe.emitirTicketC({
-  items: [
-    { descripcion: 'Producto 1', cantidad: 2, precioUnitario: 500 },
-    { descripcion: 'Producto 2', cantidad: 1, precioUnitario: 1000 },
-  ],
-});
+---
 
-// Los items NO se envían a ARCA
-// Pero se retornan en la respuesta para que los guardes
-console.log('Items:', cae.items);
-```
+## 📱 Generador de QR Oficial
+AFIP exige que los comprobantes impresos tengan un código QR. El SDK lo genera cumpliendo estrictamente con el formato oficial (JSON ordenado, Base64 URL-safe, etc).
 
-#### Factura B (IVA discriminado)
 ```typescript
-import { TipoDocumento } from 'arca-sdk';
-
-const cae = await wsfe.emitirFacturaB({
-  items: [
-    { 
-      descripcion: 'Servicio', 
-      cantidad: 10, 
-      precioUnitario: 1000,
-      alicuotaIva: 21,  // ← OBLIGATORIO
-    },
-  ],
-  comprador: {
-    tipoDocumento: TipoDocumento.CUIT,
-    nroDocumento: '20987654321',
-  },
-});
+// 1. Integrado en WsfeService (Recomendado)
+const result = await wsfe.emitirTicketCSimple({ total: 1500 });
+console.log(result.urlQr); 
 
-console.log('CAE:', cae.cae);
-console.log('IVA:', cae.iva);
+// 2. O manual si lo necesitás por separado
+import { generarUrlQR } from 'arca-sdk';
+const urlQr = generarUrlQR(caeResponse, '20123456789', 1500);
 ```
 
-#### Factura A (RI a RI)
-```typescript
-const cae = await wsfe.emitirFacturaA({
-  items: [
-    { descripcion: 'Producto', cantidad: 5, precioUnitario: 2000, alicuotaIva: 21 },
-  ],
-  comprador: {
-    tipoDocumento: TipoDocumento.CUIT,
-    nroDocumento: '20111111119',
-  },
-});
-```
+---
 
-#### Precios con IVA Incluido
-Si tus precios ya tienen el IVA (típico en venta minorista/POS), podés usar el flag `incluyeIva`:
-```typescript
-const cae = await wsfe.emitirFacturaB({
-  incluyeIva: true, // ← El SDK calculará el neto y el IVA automáticamente
-  items: [
-    { descripcion: 'Producto', cantidad: 1, precioUnitario: 1210, alicuotaIva: 21 },
-  ],
-  // ... comprador
-});
-// Internamente enviará: Subtotal: 1000, IVA: 210, Total: 1210
-```
+## 🖨️ Generación de PDF
+Para mantener la SDK ligera, no incluimos generadores de PDF (como `jspdf`) en el core. 
+**Tip:** La URL del QR (`urlQr`) apunta a la vista oficial de ARCA que ya es 100% imprimible y legal. Si necesitás PDF local, podés usar los datos de `CAEResponse` con tu librería favorita.
 
 ---
 
-## 📱 Generador de QR Oficial
-AFIP exige que los comprobantes impresos tengan un código QR con los datos fiscales. La SDK lo genera por vos:
+## 🩺 Chequeo de Salud
+Verificá si los servidores de ARCA están online antes de intentar facturar.
 
 ```typescript
-import { generarUrlQR } from 'arca-sdk';
-
-// Usá la respuesta del CAE para generar la URL del QR
-const urlQr = generarUrlQR(cae);
-
-console.log('URL para QR:', urlQr);
-// Output: https://www.afip.gob.ar/fe/qr/?p=eyJ2ZXIiOjEsImZlY2hh...
+const status = await wsfe.checkStatus();
+console.log('AppServer:', status.appServer); // 'OK'
 ```
 
-Esta URL la podés pasar a cualquier librería de generación de imágenes QR.
-
----
-
 ---
 
-## 🎯 Tipos de Comprobante
+## 📝 Servicios y Comprobantes
 
-| Tipo | Uso | IVA Discriminado | Items requeridos |
-|------|-----|------------------|------------------|
-| **Ticket C** | Consumidor final | No | Opcional (solo local) |
-| **Factura C** | Consumidor final | No | Opcional |
-| **Factura B** | Monotributo → RI | Sí | **Obligatorio** |
-| **Factura A** | RI → RI | Sí | **Obligatorio** |
+| Clase | Servicio ARCA | Descripción |
+|-------|---------------|-------------|
+| `WsaaService` | `wsaa` | Autenticación y Autorización |
+| `WsfeService` | `wsfev1` | Facturación Electrónica (A, B, C) |
+| `PadronService` | `ws_sr_padron_a13` | Consulta de datos de contribuyentes |
 
-**Importante:** Factura B y A requieren `alicuotaIva` en cada item.
+### Comprobantes soportados en `WsfeService`:
+- `emitirTicketCSimple()`: Rápido para Consumidor Final.
+- `emitirTicketC()`: Con detalle de items.
+- `emitirFacturaB()`: Para Responsables Inscriptos o Facturas > $ limite.
+- `emitirFacturaA()`: Con discriminación de IVA.
 
 ---
 
-## 🤝 Contribuir
+## 🛠️ Desarrollo y Tests
+```bash
+# Correr tests con mocks de ARCA
+bun test
+
+# Verificar tipos
+bun run lint
 
-Contribuciones bienvenidas! Ver [CONTRIBUTING.md](./CONTRIBUTING.md)
+# Build para producción (CJS + ESM)
+bun run build
+```
 
 ---
 
 ## 📄 Licencia
-
 MIT © [Marcela Borgarello](https://github.com/marcelaborgarello)
 
 ---
 
-## 🔗 Links
-
-- [Documentación ARCA](https://www.afip.gob.ar/ws/)
-- [Issues](https://github.com/marcelaborgarello/arca-sdk/issues)
-- [NPM](https://www.npmjs.com/package/arca-sdk)
-
----
-
 **Hecho con ❤️ en Argentina 🇦🇷**
-
 *Porque integrar con ARCA no tiene por qué ser un infierno.*

package/dist/index.cjs

@@ -68,10 +68,11 @@ function getPadronEndpoint(environment) {
 
 // src/types/common.ts
 var ArcaError = class extends Error {
-  constructor(message, code, details) {
+  constructor(message, code, details, hint) {
     super(message);
     this.code = code;
     this.details = details;
+    this.hint = hint;
     this.name = "ArcaError";
   }
 };
@@ -549,6 +550,54 @@ function redondear(valor) {
   return Math.round(valor * 100) / 100;
 }
 
+// src/utils/qr.ts
+function generarUrlQR(caeResponse, cuitEmisor, total, comprador) {
+  const cleanCuit = cuitEmisor.replace(/\D/g, "");
+  const cleanCae = caeResponse.cae.replace(/\D/g, "");
+  const fDate = caeResponse.fecha;
+  const fechaFormat = fDate.length === 8 ? `${fDate.substring(0, 4)}-${fDate.substring(4, 6)}-${fDate.substring(6, 8)}` : fDate;
+  const docTipo = comprador?.tipoDocumento || 99 /* CONSUMIDOR_FINAL */;
+  const docNro = comprador?.nroDocumento ? comprador.nroDocumento.replace(/\D/g, "") : "0";
+  const qrObj = {
+    ver: 1,
+    fecha: fechaFormat,
+    cuit: Number(cleanCuit),
+    ptoVta: Number(caeResponse.puntoVenta),
+    tipoCmp: Number(caeResponse.tipoComprobante),
+    nroCmp: Number(caeResponse.nroComprobante),
+    importe: Number(parseFloat(total.toFixed(2))),
+    moneda: "PES",
+    ctz: 1
+  };
+  if (docTipo !== 99 /* CONSUMIDOR_FINAL */ || Number(docNro) > 0) {
+    qrObj.tipoDocRec = Number(docTipo);
+    qrObj.nroDocRec = Number(docNro);
+  }
+  qrObj.tipoCodAut = "E";
+  qrObj.codAut = Number(cleanCae);
+  const jsonString = JSON.stringify(qrObj);
+  let base64 = typeof Buffer !== "undefined" ? Buffer.from(jsonString).toString("base64") : btoa(jsonString);
+  return `https://www.afip.gob.ar/fe/qr/?p=${encodeURIComponent(base64)}`;
+}
+
+// src/constants/errors.ts
+var ARCA_ERROR_HINTS = {
+  // Generales / Auth
+  501: "Error de autenticaci\xF3n: El certificado puede haber expirado o la relaci\xF3n CUIT/Servicio no est\xE1 dada de alta en la web de AFIP.",
+  502: "Error de autenticaci\xF3n: El ticket de acceso (TA) ya no es v\xE1lido o est\xE1 mal formado.",
+  1e3: "El CUIT informado no es v\xE1lido o no corresponde al certificado usado.",
+  // WSFE (Facturación)
+  10015: "Factura B: El importe total es superior al l\xEDmite para consumidores finales an\xF3nimos. Identific\xE1 al comprador.",
+  10016: "Factura C: El CUIT informado como receptor no es v\xE1lido.",
+  10048: 'Punto de Venta inv\xE1lido: Asegurate de que el punto de venta est\xE9 dado de alta como "Factuweb" o "Webservice" en AFIP.',
+  600: "No se pudo autorizar el comprobante. Revis\xE1 las observaciones para m\xE1s detalle.",
+  // Padrón
+  "PADRON_ERROR": "El servicio de Padr\xF3n suele ser inestable en homologaci\xF3n. Reintent\xE1 en unos minutos."
+};
+function getArcaHint(code) {
+  return ARCA_ERROR_HINTS[code];
+}
+
 // src/services/wsfe.ts
 var WsfeService = class _WsfeService {
   config;
@@ -797,10 +846,17 @@ var WsfeService = class _WsfeService {
     }
     const responseXml = await response.text();
     const result = await this.parseCAEResponse(responseXml);
+    const urlQr = generarUrlQR(
+      result,
+      this.config.cuit,
+      total,
+      request.comprador
+    );
     return {
       ...result,
       items: request.items,
-      iva: request.ivaData
+      iva: request.ivaData,
+      urlQr
     };
   }
   /**
@@ -826,7 +882,13 @@ var WsfeService = class _WsfeService {
     const data = result?.Envelope?.Body?.FECompUltimoAutorizadoResponse?.FECompUltimoAutorizadoResult;
     if (data?.Errors) {
       const error = Array.isArray(data.Errors.Err) ? data.Errors.Err[0] : data.Errors.Err;
-      throw new ArcaError(`Error ARCA: ${error?.Msg || "Error desconocido"}`, "ARCA_ERROR", data.Errors);
+      const code = error?.Code || "UNKNOWN";
+      throw new ArcaError(
+        `Error ARCA: ${error?.Msg || "Error desconocido"}`,
+        "ARCA_ERROR",
+        data.Errors,
+        getArcaHint(code)
+      );
     }
     const nro = data?.CbteNro;
     return typeof nro === "number" ? nro + 1 : 1;
@@ -935,7 +997,13 @@ var WsfeService = class _WsfeService {
     }
     if (data.Errors) {
       const error = Array.isArray(data.Errors.Err) ? data.Errors.Err[0] : data.Errors.Err;
-      throw new ArcaError(`Error ARCA: ${error?.Msg || "Error desconocido"}`, "ARCA_ERROR", data.Errors);
+      const code = error?.Code || "UNKNOWN";
+      throw new ArcaError(
+        `Error ARCA: ${error?.Msg || "Error desconocido"}`,
+        "ARCA_ERROR",
+        data.Errors,
+        getArcaHint(code)
+      );
     }
     const cab = data.FeCabResp;
     const det = Array.isArray(data.FeDetResp.FECAEDetResponse) ? data.FeDetResp.FECAEDetResponse[0] : data.FeDetResp.FECAEDetResponse;
@@ -1034,7 +1102,7 @@ var PadronService = class {
     if (!response) {
       const fault = body.Fault;
       if (fault) {
-        return { error: fault.faultstring || "Error desconocido en AFIP" };
+        return { error: fault.faultstring || "Error desconocido en ARCA" };
       }
       return { error: "No se encontraron datos para el CUIT informado" };
     }
@@ -1053,6 +1121,8 @@ var PadronService = class {
       razonSocial: p.razonSocial,
       estadoClave: p.estadoClave,
       domicilio: this.mapDomicilios(p.domicilio),
+      actividad: this.mapActividades(p.actividad),
+      impuesto: this.mapImpuestos(p.impuesto),
       descripcionActividadPrincipal: p.descripcionActividadPrincipal,
       esInscriptoIVA: this.checkImpuesto(p, 30),
       // 30 = IVA
@@ -1065,7 +1135,7 @@ var PadronService = class {
   }
   mapDomicilios(d) {
     if (!d) return [];
-    const list = Array.isArray(d) ? d : [d];
+    const list = this.ensureArray(d);
     return list.map((item) => ({
       direccion: item.direccion,
       localidad: item.localidad,
@@ -1075,43 +1145,39 @@ var PadronService = class {
       tipoDomicilio: item.tipoDomicilio
     }));
   }
+  mapActividades(a) {
+    if (!a) return [];
+    const list = this.ensureArray(a);
+    return list.map((item) => ({
+      idActividad: Number(item.idActividad),
+      descripcion: item.descripcion,
+      orden: Number(item.orden),
+      periodo: Number(item.periodo)
+    }));
+  }
+  mapImpuestos(i) {
+    if (!i) return [];
+    const list = this.ensureArray(i);
+    return list.map((item) => ({
+      idImpuesto: Number(item.idImpuesto),
+      descripcion: item.descripcion,
+      periodo: Number(item.periodo)
+    }));
+  }
   checkImpuesto(p, id) {
     const impuestos = p.impuesto;
     if (!impuestos) return false;
-    const list = Array.isArray(impuestos) ? impuestos : [impuestos];
+    const list = this.ensureArray(impuestos);
     return list.some((i) => Number(i.idImpuesto) === id);
   }
-};
-
-// src/utils/qr.ts
-function generarUrlQR(caeResponse, cuitEmisor, total, comprador) {
-  const cleanCuit = cuitEmisor.replace(/\D/g, "");
-  const cleanCae = caeResponse.cae.replace(/\D/g, "");
-  const fDate = caeResponse.fecha;
-  const fechaFormat = fDate.length === 8 ? `${fDate.substring(0, 4)}-${fDate.substring(4, 6)}-${fDate.substring(6, 8)}` : fDate;
-  const docTipo = comprador?.tipoDocumento || 99 /* CONSUMIDOR_FINAL */;
-  const docNro = comprador?.nroDocumento ? comprador.nroDocumento.replace(/\D/g, "") : "0";
-  const qrObj = {
-    ver: 1,
-    fecha: fechaFormat,
-    cuit: Number(cleanCuit),
-    ptoVta: Number(caeResponse.puntoVenta),
-    tipoCmp: Number(caeResponse.tipoComprobante),
-    nroCmp: Number(caeResponse.nroComprobante),
-    importe: Number(parseFloat(total.toFixed(2))),
-    moneda: "PES",
-    ctz: 1
-  };
-  if (docTipo !== 99 /* CONSUMIDOR_FINAL */ || Number(docNro) > 0) {
-    qrObj.tipoDocRec = Number(docTipo);
-    qrObj.nroDocRec = Number(docNro);
+  /**
+   * Helper para normalizar la respuesta de XML que puede ser objeto único o array
+   */
+  ensureArray(data) {
+    if (data === void 0 || data === null) return [];
+    return Array.isArray(data) ? data : [data];
   }
-  qrObj.tipoCodAut = "E";
-  qrObj.codAut = Number(cleanCae);
-  const jsonString = JSON.stringify(qrObj);
-  let base64 = typeof Buffer !== "undefined" ? Buffer.from(jsonString).toString("base64") : btoa(jsonString);
-  return `https://www.afip.gob.ar/fe/qr/?p=${encodeURIComponent(base64)}`;
-}
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ArcaAuthError,