arca-sdk 0.5.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,13 +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, persistencia opcional (God Mode)
-- ✅ **Fiscal**: Generador de QR oficial ARCA/AFIP ultra-robusto
+- ✅ **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
 
 ---
 
@@ -25,35 +25,46 @@ bun add arca-sdk
 ## ⚡ Quick Start
 ```typescript
 import { WsaaService, WsfeService } from 'arca-sdk';
+import * as fs from 'fs';
 
-// 1. Configuración base
-const config = {
+// 1. Autenticar con WSAA
+const wsaa = new WsaaService({
+  environment: 'homologacion',
+  cuit: '20123456789',
+  cert: fs.readFileSync('cert.pem', 'utf-8'),
+  key: fs.readFileSync('key.pem', 'utf-8'),
+  service: 'wsfe',
+});
+
+const ticket = await wsaa.login();
+
+// 2. Crear servicio de facturación
+const wsfe = new WsfeService({
   environment: 'homologacion',
   cuit: '20123456789',
-  cert: '...certificado PEM...',
-  key: '...clave privada PEM...',
-};
+  ticket,
+  pointOfSale: 4,
+});
 
-// 2. Emitir un Ticket C en dos líneas
-const wsfe = new WsfeService(config);
-const result = await wsfe.emitirTicketCSimple({ total: 1500 });
+// 3. Emitir un Ticket C
+const result = await wsfe.issueSimpleReceipt({ total: 1500 });
 
 console.log('CAE:', result.cae);
-console.log('QR URL:', result.urlQr); // ← Ya viene integrado!
+console.log('QR URL:', result.qrUrl); // ← Ya viene integrado!
 ```
 
 ---
 
 ## 👑 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.
+No manejes tokens manualmente. Pasale un `storage` al SDK y se encargará de guardar, recuperar y renovar el TA solo cuando expire.
 
 ```typescript
 const wsaa = new WsaaService({
   ...config,
   service: 'wsfe',
   storage: {
-    get: async (key) => await db.token.findUnique({ where: { key } }),
-    save: async (key, data) => await db.token.upsert({ ... }),
+    get: async (cuit, env) => await db.token.findUnique({ where: { cuit, env } }),
+    save: async (cuit, env, ticket) => await db.token.upsert({ ... }),
   }
 });
 
@@ -64,55 +75,107 @@ const ticket = await wsaa.login();
 ---
 
 ## 🔍 Consulta de Padrón (A13)
-Obtené los datos de un cliente (Nombre, Domicilio, IVA) solo con su CUIT. Ideal para POS.
+Obtené los datos de un contribuyente (nombre, domicilio, condición IVA) solo con su CUIT.
 
 ```typescript
 import { PadronService } from 'arca-sdk';
 
 const padron = new PadronService(config);
-const { persona, error } = await padron.getPersona('30111111118');
-
-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);
+const { taxpayer, error } = await padron.getTaxpayer('30111111118');
+
+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);
 }
 ```
 
 ---
 
-## 📱 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).
+## 📱 Comprobantes soportados
 
 ```typescript
-// 1. Integrado en WsfeService (Recomendado)
-const result = await wsfe.emitirTicketCSimple({ total: 1500 });
-console.log(result.urlQr); 
+// 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 },
+  ],
+});
+
+// Factura C — Consumidor Final con items
+const cae = await wsfe.issueInvoiceC({ items: [...] });
 
-// 2. O manual si lo necesitás por separado
-import { generarUrlQR } from 'arca-sdk';
-const urlQr = generarUrlQR(caeResponse, '20123456789', 1500);
+// 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' },
+});
 ```
 
 ---
 
-## 🖨️ 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.
+## 🔎 Consultar un comprobante ya emitido
+
+```typescript
+const invoice = await wsfe.getInvoice(InvoiceType.TICKET_C, 42);
+console.log('Total:', invoice.total);
+console.log('CAE:', invoice.cae);
+```
 
 ---
 
-## 🩺 Chequeo de Salud
-Verificá si los servidores de ARCA están online antes de intentar facturar.
+## 🏪 Listar puntos de venta
 
 ```typescript
-const status = await wsfe.checkStatus();
-console.log('AppServer:', status.appServer); // 'OK'
+const points = await wsfe.getPointsOfSale();
+points.forEach(p => {
+  console.log(`PdV ${p.number}: ${p.type} — ${p.isBlocked ? '🔴 Bloqueado' : '✅ Activo'}`);
+});
 ```
 
 ---
 
-## 📝 Servicios y Comprobantes
+## 📱 QR Oficial de ARCA
+
+```typescript
+// 1. Integrado automáticamente en todos los métodos de emisión
+const result = await wsfe.issueSimpleReceipt({ total: 1500 });
+console.log(result.qrUrl);
+
+// 2. O generalo manualmente
+import { generateQRUrl } from 'arca-sdk';
+const url = generateQRUrl(caeResponse, '20123456789', 1500);
+```
+
+---
+
+## 🩺 Estado de los servidores
+
+```typescript
+// 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);
+```
+
+---
+
+## 📝 Referencia de Servicios
 
 | Clase | Servicio ARCA | Descripción |
 |-------|---------------|-------------|
@@ -120,23 +183,37 @@ console.log('AppServer:', status.appServer); // 'OK'
 | `WsfeService` | `wsfev1` | Facturación Electrónica (A, B, C) |
 | `PadronService` | `ws_sr_padron_a13` | Consulta de datos de contribuyentes |
 
-### 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.
+### Enums disponibles
+
+```typescript
+import { InvoiceType, BillingConcept, TaxIdType } from 'arca-sdk';
+
+InvoiceType.FACTURA_A    // 1
+InvoiceType.FACTURA_B    // 6
+InvoiceType.FACTURA_C    // 11
+InvoiceType.TICKET_C     // 83
+
+BillingConcept.PRODUCTS               // 1
+BillingConcept.SERVICES               // 2
+BillingConcept.PRODUCTS_AND_SERVICES  // 3
+
+TaxIdType.CUIT            // 80
+TaxIdType.DNI             // 96
+TaxIdType.FINAL_CONSUMER  // 99
+```
 
 ---
 
 ## 🛠️ Desarrollo y Tests
+
 ```bash
-# Correr tests con mocks de ARCA
+# Correr tests (unit + mocks de ARCA)
 bun test
 
-# Verificar tipos
+# Verificar tipos TypeScript
 bun run lint
 
-# Build para producción (CJS + ESM)
+# Build para producción (CJS + ESM + .d.ts)
 bun run build
 ```