arca-sdk 0.4.0 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,142 @@
+# Changelog
+
+Todos los cambios notables de este proyecto se documentan en este archivo.
+
+---
+
+## [1.0.0] — 2026-02-23
+
+### 🔴 Breaking Changes
+
+Esta versión establece la API pública definitiva. **Requiere actualizar todos los imports** si venís de v0.x.
+
+#### Métodos renombrados en WsfeService
+| v0.x | v1.0.0 |
+|-------|--------|
+| `emitirTicketCSimple()` | `issueSimpleReceipt()` |
+| `emitirTicketC()` | `issueReceipt()` |
+| `emitirFacturaC()` | `issueInvoiceC()` |
+| `emitirFacturaB()` | `issueInvoiceB()` |
+| `emitirFacturaA()` | `issueInvoiceA()` |
+| `emitirComprobante()` | *(privado — ya no accesible)* |
+
+#### Método renombrado en PadronService
+| v0.x | v1.0.0 |
+|-------|--------|
+| `getPersona(cuit)` | `getTaxpayer(cuit)` |
+
+#### Configuración de WsfeService
+| v0.x | v1.0.0 |
+|-------|--------|
+| `puntoVenta: 4` | `pointOfSale: 4` |
+
+#### Tipos renombrados
+| v0.x | v1.0.0 |
+|-------|--------|
+| `TipoComprobante` | `InvoiceType` |
+| `TipoDocumento` | `TaxIdType` |
+| `Concepto` | `BillingConcept` |
+| `FacturaItem` | `InvoiceItem` |
+| `Comprador` | `Buyer` |
+| `EmitirFacturaRequest` | `IssueInvoiceRequest` |
+| `Persona` | `Taxpayer` |
+| `Domicilio` | `Address` |
+| `Actividad` | `Activity` |
+| `Impuesto` | `TaxRecord` |
+| `PadronResponse` | `TaxpayerResponse` |
+| `PadronConfig` | `TaxpayerServiceConfig` |
+
+#### Fields renombrados en tipos
+| Tipo | v0.x | v1.0.0 |
+|------|-------|--------|
+| `InvoiceItem` | `descripcion` | `description` |
+| `InvoiceItem` | `cantidad` | `quantity` |
+| `InvoiceItem` | `precioUnitario` | `unitPrice` |
+| `InvoiceItem` | `alicuotaIva` | `vatRate` |
+| `Buyer` | `tipoDocumento` | `docType` |
+| `Buyer` | `nroDocumento` | `docNumber` |
+| `CAEResponse` | `tipoComprobante` | `invoiceType` |
+| `CAEResponse` | `puntoVenta` | `pointOfSale` |
+| `CAEResponse` | `nroComprobante` | `invoiceNumber` |
+| `CAEResponse` | `fecha` | `date` |
+| `CAEResponse` | `vencimientoCae` | `caeExpiry` |
+| `CAEResponse` | `resultado` | `result` |
+| `CAEResponse` | `observaciones` | `observations` |
+| `CAEResponse` | `iva` | `vat` |
+| `CAEResponse` | `urlQr` | `qrUrl` |
+| `ServiceStatus` | `AppServer` | `appServer` |
+| `ServiceStatus` | `DbServer` | `dbServer` |
+| `ServiceStatus` | `AuthServer` | `authServer` |
+| `Taxpayer` | `idPersona` | `taxId` |
+| `Taxpayer` | `tipoPersona` | `personType` |
+| `Taxpayer` | `nombre` | `firstName` |
+| `Taxpayer` | `apellido` | `lastName` |
+| `Taxpayer` | `razonSocial` | `companyName` |
+| `Taxpayer` | `estadoClave` | `status` |
+| `Taxpayer` | `domicilio` | `addresses` |
+| `Taxpayer` | `actividad` | `activities` |
+| `Taxpayer` | `impuesto` | `taxes` |
+| `Taxpayer` | `descripcionActividadPrincipal` | `mainActivity` |
+| `Taxpayer` | `esInscriptoIVA` | `isVATRegistered` |
+| `Taxpayer` | `esMonotributista` | `isMonotax` |
+| `Taxpayer` | `esExento` | `isVATExempt` |
+| `Address` | `direccion` | `street` |
+| `Address` | `localidad` | `city` |
+| `Address` | `codPostal` | `postalCode` |
+| `Address` | `idProvincia` | `provinceId` |
+| `Address` | `descripcionProvincia` | `province` |
+| `Address` | `tipoDomicilio` | `type` |
+
+#### Función renombrada en utils
+| v0.x | v1.0.0 |
+|-------|--------|
+| `generarUrlQR()` | `generateQRUrl()` |
+
+#### Enums — valores constantes renombrados
+| Enum | v0.x | v1.0.0 |
+|------|-------|--------|
+| `TaxIdType` | `CONSUMIDOR_FINAL` | `FINAL_CONSUMER` |
+| `TaxIdType` | `CI_EXTRANJERA` | `FOREIGN_ID` |
+| `TaxIdType` | `CI_BUENOS_AIRES` | `BUENOS_AIRES_ID` |
+| `TaxIdType` | `CI_POLICIA_FEDERAL` | `NATIONAL_POLICE_ID` |
+| `BillingConcept` | `PRODUCTOS` | `PRODUCTS` |
+| `BillingConcept` | `SERVICIOS` | `SERVICES` |
+| `BillingConcept` | `PRODUCTOS_Y_SERVICIOS` | `PRODUCTS_AND_SERVICES` |
+
+---
+
+### ✅ Nuevas funcionalidades
+
+- **`WsfeService.getInvoice(type, number)`**: Consulta un comprobante ya emitido (FECompConsultar).
+- **`WsfeService.getPointsOfSale()`**: Lista los puntos de venta habilitados (FEParamGetPtosVenta).
+- **`ArcaNetworkError`**: Ahora exportado públicamente para manejo de errores de red.
+- **`InvoiceDetails`**: Nuevo tipo para la respuesta de `getInvoice()`.
+- **`PointOfSale`**: Nuevo tipo para la respuesta de `getPointsOfSale()`.
+
+### 🐛 Fixes
+
+- `ServiceStatus` ahora tiene campos `camelCase` (`appServer`, `dbServer`, `authServer`) en lugar de `PascalCase`.
+- `emitirComprobante` (ahora `issueDocument`) se volvió privado — ya no es accesible desde fuera del servicio.
+- Diccionario de hints de errores (`ARCA_ERROR_HINTS`) expandido a 15+ códigos documentados.
+- Eliminado `WsaaResponse` (tipo sin uso).
+- Tipado explícito en `PadronService`: eliminados todos los `any` en métodos privados.
+
+### 🧪 Tests
+
+- Nuevo suite de tests para `WsfeService` (`wsfe.test.ts`).
+- Tests existentes actualizados a la nueva API.
+
+---
+
+## [0.5.0] — 2026-02-22
+
+- Agregado Padrón A13 service (`PadronService`)
+- `ArcaError` con campo `hint` para guiar al desarrollador
+- `checkStatus()` con default seguro en `homologacion`
+
+## [0.4.0] — 2026-02-21
+
+- Primera versión pública del SDK
+- `WsaaService` con cache en memoria + persistencia opcional
+- `WsfeService` con Ticket C, Factura A, B, C
+- Generador de QR oficial de ARCA

package/README.md

@@ -3,12 +3,13 @@
 **La SDK moderna de ARCA (ex-AFIP) que no te rompe las bolas.**
 
 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
+- ✅ **Type-safe**: TypeScript strict mode, 100% tipado
+- ✅ **Simple**: API en inglés, sin XML manual, sin magia negra
+- ✅ **Automático**: Cache de tokens + persistencia opcional (God Mode)
+- ✅ **Fiscal**: Generador de QR oficial de ARCA 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+
+- ✅ **Moderno**: ESM + CJS nativo, Node.js 18+, Bun compatible
 
 ---
 
@@ -23,283 +24,205 @@ bun add arca-sdk
 
 ## ⚡ Quick Start
 ```typescript
-import { WsaaService } from 'arca-sdk';
-import * as fs from 'node:fs';
+import { WsaaService, WsfeService } from 'arca-sdk';
+import * as fs from 'fs';
 
-// 1. Crear servicio con tus certificados
+// 1. Autenticar con WSAA
 const wsaa = new WsaaService({
-  environment: 'homologacion',  // 'homologacion' o 'produccion'
+  environment: 'homologacion',
   cuit: '20123456789',
-  cert: fs.readFileSync('./cert.pem', 'utf-8'),
-  key: fs.readFileSync('./key.pem', 'utf-8'),
+  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);
-```
+// 2. Crear servicio de facturación
+const wsfe = new WsfeService({
+  environment: 'homologacion',
+  cuit: '20123456789',
+  ticket,
+  pointOfSale: 4,
+});
+
+// 3. Emitir un Ticket C
+const result = await wsfe.issueSimpleReceipt({ total: 1500 });
 
-**Eso es todo.** No XML. No SOAP. No pain.
+console.log('CAE:', result.cae);
+console.log('QR URL:', result.qrUrl); // ← Ya viene integrado!
+```
 
 ---
 
-## 📖 Servicios Disponibles
+## 👑 God Mode: Persistencia Automática
+No manejes tokens manualmente. Pasale un `storage` al SDK y se encargará de guardar, recuperar y renovar el TA solo cuando expire.
 
-### WSAA - Autenticación
 ```typescript
-import { WsaaService } from 'arca-sdk';
-
 const wsaa = new WsaaService({
-  environment: 'homologacion',
-  cuit: '20123456789',
-  cert: '...certificado PEM...',
-  key: '...clave privada PEM...',
-  service: 'wsfe',  // o 'wsmtxca', etc
+  ...config,
+  service: 'wsfe',
+  storage: {
+    get: async (cuit, env) => await db.token.findUnique({ where: { cuit, env } }),
+    save: async (cuit, env, ticket) => await db.token.upsert({ ... }),
+  }
 });
 
+// El SDK chequea el storage antes de pedir un nuevo ticket a ARCA
 const ticket = await wsaa.login();
-// Ticket válido por ~12 horas
-// Se renueva automáticamente
-```
-
-### WSFE - Facturación
-```typescript
-const wsfe = new WsfeService(config);
-const cae = await wsfe.emitirFacturaC({ items });
-console.log('CAE:', cae.cae);
 ```
 
 ---
 
-## 🔑 Certificados
+## 🔍 Consulta de Padrón (A13)
+Obtené los datos de un contribuyente (nombre, domicilio, condición IVA) solo con su CUIT.
 
-Necesitás certificados de ARCA en formato PEM:
-- `cert.pem`: Certificado X.509
-- `key.pem`: Clave privada
+```typescript
+import { PadronService } from 'arca-sdk';
 
-**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
+const padron = new PadronService(config);
+const { taxpayer, error } = await padron.getTaxpayer('30111111118');
 
-**Producción:**
-1. Generar CSR con tu CUIT
-2. Subir a ARCA
-3. Descargar certificado firmado
+if (taxpayer) {
+  const name = taxpayer.companyName || `${taxpayer.firstName} ${taxpayer.lastName}`;
+  console.log('Nombre:', name);
+  console.log('Provincia:', taxpayer.addresses[0].province);
+  console.log('¿Inscripto IVA?:', taxpayer.isVATRegistered);
+  console.log('¿Monotributista?:', taxpayer.isMonotax);
+}
+```
 
 ---
 
-## 🛠️ Ejemplos
+## 📱 Comprobantes soportados
 
-Ver carpeta [`/examples`](./examples):
-- [`autenticacion.ts`](./examples/autenticacion.ts) - Obtener ticket WSAA
-- [`quick-start.ts`](./examples/quick-start.ts) - Inicio rápido
+```typescript
+// Ticket C — Consumidor Final (solo total)
+const cae = await wsfe.issueSimpleReceipt({ total: 1500 });
 
----
+// Ticket C — con detalle de items (los items se guardan localmente, no van a ARCA)
+const cae = await wsfe.issueReceipt({
+  items: [
+    { description: 'Café con leche', quantity: 2, unitPrice: 750 },
+    { description: 'Medialunas x3', quantity: 1, unitPrice: 500 },
+  ],
+});
 
-## 🧪 Testing
-```bash
-# Tests unitarios
-bun test
+// Factura C — Consumidor Final con items
+const cae = await wsfe.issueInvoiceC({ items: [...] });
 
-# Build
-bun run build
+// Factura B — con IVA discriminado (requiere vatRate en cada item)
+const cae = await wsfe.issueInvoiceB({
+  items: [
+    { description: 'Servicio de diseño', quantity: 10, unitPrice: 1000, vatRate: 21 },
+  ],
+  buyer: { docType: TaxIdType.CUIT, docNumber: '20987654321' },
+});
+
+// Factura A — entre Responsables Inscriptos
+const cae = await wsfe.issueInvoiceA({
+  items: [...],
+  buyer: { docType: TaxIdType.CUIT, docNumber: '30123456789' },
+});
 ```
 
 ---
 
-## 📝 TypeScript
+## 🔎 Consultar un comprobante ya emitido
 
-La SDK exporta todos los tipos:
 ```typescript
-import type { 
-  LoginTicket, 
-  WsaaConfig, 
-  Environment 
-} from 'arca-sdk';
+const invoice = await wsfe.getInvoice(InvoiceType.TICKET_C, 42);
+console.log('Total:', invoice.total);
+console.log('CAE:', invoice.cae);
 ```
 
-Autocomplete completo en tu IDE. ✨
-
 ---
 
-## ⚠️ 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);
-  }
-}
-```
+## 🏪 Listar puntos de venta
 
-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({
-  ...config,
-  timeout: 30000 // 30 segundos
+const points = await wsfe.getPointsOfSale();
+points.forEach(p => {
+  console.log(`PdV ${p.number}: ${p.type} — ${p.isBlocked ? '🔴 Bloqueado' : '✅ Activo'}`);
 });
 ```
 
 ---
 
-### WSFE - Facturación Electrónica
+## 📱 QR Oficial de ARCA
 
-#### Ticket C Simple (solo total)
 ```typescript
-import { WsaaService, WsfeService } from 'arca-sdk';
-
-// 1. Autenticar
-const wsaa = new WsaaService({ ... });
-const ticket = await wsaa.login();
+// 1. Integrado automáticamente en todos los métodos de emisión
+const result = await wsfe.issueSimpleReceipt({ total: 1500 });
+console.log(result.qrUrl);
 
-// 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);
+// 2. O generalo manualmente
+import { generateQRUrl } from 'arca-sdk';
+const url = generateQRUrl(caeResponse, '20123456789', 1500);
 ```
 
-#### 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);
-```
+## 🩺 Estado de los servidores
 
-#### 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',
-  },
-});
-
-console.log('CAE:', cae.cae);
-console.log('IVA:', cae.iva);
+// Sin necesidad de autenticación
+const status = await WsfeService.checkStatus('produccion');
+console.log('AppServer:', status.appServer);  // 'OK'
+console.log('DbServer:', status.dbServer);
+console.log('AuthServer:', status.authServer);
 ```
 
-#### 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
-```
+## 📝 Referencia de Servicios
 
----
+| 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 |
 
-## 📱 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:
+### Enums disponibles
 
 ```typescript
-import { generarUrlQR } from 'arca-sdk';
-
-// Usá la respuesta del CAE para generar la URL del QR
-const urlQr = generarUrlQR(cae);
+import { InvoiceType, BillingConcept, TaxIdType } from 'arca-sdk';
 
-console.log('URL para QR:', urlQr);
-// Output: https://www.afip.gob.ar/fe/qr/?p=eyJ2ZXIiOjEsImZlY2hh...
-```
+InvoiceType.FACTURA_A    // 1
+InvoiceType.FACTURA_B    // 6
+InvoiceType.FACTURA_C    // 11
+InvoiceType.TICKET_C     // 83
 
-Esta URL la podés pasar a cualquier librería de generación de imágenes QR.
+BillingConcept.PRODUCTS               // 1
+BillingConcept.SERVICES               // 2
+BillingConcept.PRODUCTS_AND_SERVICES  // 3
 
----
+TaxIdType.CUIT            // 80
+TaxIdType.DNI             // 96
+TaxIdType.FINAL_CONSUMER  // 99
+```
 
 ---
 
-## 🎯 Tipos de Comprobante
-
-| 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** |
+## 🛠️ Desarrollo y Tests
 
-**Importante:** Factura B y A requieren `alicuotaIva` en cada item.
-
----
+```bash
+# Correr tests (unit + mocks de ARCA)
+bun test
 
-## 🤝 Contribuir
+# Verificar tipos TypeScript
+bun run lint
 
-Contribuciones bienvenidas! Ver [CONTRIBUTING.md](./CONTRIBUTING.md)
+# Build para producción (CJS + ESM + .d.ts)
+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.*