@ramiidv/arca-fecred 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ramiidv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,351 @@
+# @ramiidv/arca-fecred
+
+[![npm](https://img.shields.io/npm/v/@ramiidv/arca-fecred)](https://www.npmjs.com/package/@ramiidv/arca-fecred)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+
+SDK en TypeScript para el web service **WSFECRED** de **ARCA** (ex AFIP) -- Factura de Credito Electronica MiPyME (Ley 27440).
+
+Gestiona el ciclo de vida completo de las FCE: consulta de obligados, cuentas corrientes, comprobantes, aceptacion, rechazo e informar cancelacion.
+
+## Instalacion
+
+```bash
+npm install @ramiidv/arca-fecred
+```
+
+## Requisitos
+
+- Node.js >= 18
+- Certificado digital X.509 y clave privada de ARCA
+  - **Testing**: generalo desde [WSASS Homologacion](https://wsass-homo.afip.gob.ar/wsass/portal/main.aspx)
+  - **Produccion**: generalo desde [Administracion de Certificados Digitales](https://www.afip.gob.ar/ws/documentacion/certificados.asp) (requiere clave fiscal en [arca.gob.ar](https://arca.gob.ar))
+
+## Uso rapido
+
+```typescript
+import { readFileSync } from 'fs';
+import { ArcaFecred, RolCtaCte, MotivoRechazo, FormaCancelacion } from '@ramiidv/arca-fecred';
+
+const fecred = new ArcaFecred({
+  cert: readFileSync('./cert.pem', 'utf-8'),
+  key: readFileSync('./key.pem', 'utf-8'),
+  cuit: '20123456789',
+  production: false, // true para produccion
+});
+
+// Verificar si una CUIT esta obligada a recibir FCE
+const obligado = await fecred.consultarMontoObligadoRecepcion('30712345678');
+console.log(obligado.obligado); // true/false
+
+// Consultar cuentas corrientes como receptor
+const cuentas = await fecred.consultarCtasCtes({
+  rol: RolCtaCte.RECEPTOR,
+  fechaDesde: '2026-01-01',
+  fechaHasta: '2026-03-31',
+});
+
+for (const cta of cuentas) {
+  console.log(`FCE #${cta.codCtaCte}: $${cta.importeTotal} - ${cta.estado}`);
+}
+
+// Aceptar una FCE
+const aceptar = await fecred.aceptarFECred(12345);
+console.log(aceptar.resultado);
+
+// Rechazar una FCE
+const rechazar = await fecred.rechazarFECred(12345, MotivoRechazo.CBU_INCORRECTO);
+console.log(rechazar.resultado);
+
+// Informar que una FCE aceptada fue pagada
+const cancelar = await fecred.informarFacturaAceptadaCancelada({
+  codCtaCte: 12345,
+  codFormaCancelacion: FormaCancelacion.TRANSFERENCIA,
+});
+console.log(cancelar.resultado);
+```
+
+## Configuracion
+
+```typescript
+const fecred = new ArcaFecred({
+  cert: '...',               // Certificado X.509 (PEM)
+  key: '...',                // Clave privada (PEM)
+  cuit: '20123456789',       // CUIT representada
+  production: false,          // Default: false (testing/homologacion)
+  timeout: 30_000,            // Default: 30000 (30 segundos)
+  retries: 1,                 // Default: 1 (reintentos en errores transitorios)
+  retryDelayMs: 1_000,        // Default: 1000 (backoff exponencial: 1s, 2s, ...)
+  onEvent: (e) => {           // Opcional: callback para logging/debugging
+    console.log(e.type, e);
+  },
+});
+```
+
+## Ejemplos
+
+### Verificar obligacion de recepcion FCE
+
+```typescript
+const resultado = await fecred.consultarMontoObligadoRecepcion('30712345678');
+
+if (resultado.obligado) {
+  console.log(`CUIT obligada a recibir FCE desde $${resultado.montoDesde}`);
+} else {
+  console.log('CUIT no obligada a recibir FCE');
+}
+```
+
+### Consultar cuentas corrientes
+
+```typescript
+// Como emisor (mis facturas FCE emitidas)
+const misEmitidas = await fecred.consultarCtasCtes({
+  rol: RolCtaCte.EMISOR,
+  fechaDesde: '2026-01-01',
+  fechaHasta: '2026-03-31',
+});
+
+// Como receptor (FCE que me enviaron)
+const recibidas = await fecred.consultarCtasCtes({
+  rol: RolCtaCte.RECEPTOR,
+  cuitEmisor: '30712345678', // opcional: filtrar por emisor
+  fechaDesde: '2026-01-01',
+  fechaHasta: '2026-03-31',
+});
+```
+
+### Consultar comprobantes FCE
+
+```typescript
+// Buscar por CUIT emisor
+const comprobantes = await fecred.consultarComprobantes({
+  cuitEmisor: '30712345678',
+  fechaDesde: '2026-01-01',
+  fechaHasta: '2026-03-31',
+});
+
+// Buscar un comprobante especifico por codigo de cuenta corriente
+const comprobante = await fecred.consultarComprobantes({
+  codCtaCte: 12345,
+});
+```
+
+### Aceptar y luego informar cancelacion
+
+```typescript
+import { FormaCancelacion } from '@ramiidv/arca-fecred';
+
+// 1. Aceptar la FCE
+await fecred.aceptarFECred(12345);
+
+// 2. Luego de pagar, informar la cancelacion
+await fecred.informarFacturaAceptadaCancelada({
+  codCtaCte: 12345,
+  codFormaCancelacion: FormaCancelacion.TRANSFERENCIA,
+  observaciones: 'Transferencia realizada el 2026-03-15',
+});
+```
+
+### Rechazar una FCE
+
+```typescript
+import { MotivoRechazo } from '@ramiidv/arca-fecred';
+
+await fecred.rechazarFECred(12345, MotivoRechazo.OTROS);
+```
+
+### Consultar parametros disponibles
+
+```typescript
+// Tipos de retencion
+const retenciones = await fecred.consultarTiposRetenciones();
+for (const r of retenciones) {
+  console.log(`${r.codTipoRetencion}: ${r.descTipoRetencion}`);
+}
+
+// Formas de cancelacion
+const formas = await fecred.consultarTiposFormasCancelacion();
+
+// Tipos de ajuste de operacion
+const ajustes = await fecred.consultarTiposAjustesOperacion();
+
+// Motivos de rechazo
+const motivos = await fecred.consultarTiposMotivoRechazo();
+```
+
+### Health check
+
+```typescript
+const status = await fecred.status();
+console.log(status.appserver); // "OK"
+console.log(status.dbserver);  // "OK"
+console.log(status.authserver); // "OK"
+```
+
+## Retry automatico
+
+El SDK reintenta automaticamente en errores transitorios (timeout, HTTP 5xx, errores de red). No reintenta en errores de negocio (4xx, errores de ARCA).
+
+- **Default**: 1 reintento con backoff exponencial (1s, 2s, ...)
+- **Configurable**: `retries: 0` para desactivar, `retries: 3` para mas intentos
+
+```typescript
+const fecred = new ArcaFecred({
+  ...config,
+  retries: 2,         // 2 reintentos (3 intentos totales)
+  retryDelayMs: 2000, // empezar con 2s -> 4s -> 8s
+});
+```
+
+## Eventos / Logging
+
+El SDK emite eventos para debugging y monitoreo sin forzar un logger especifico.
+
+```typescript
+const fecred = new ArcaFecred({
+  ...config,
+  onEvent: (e) => console.log(`[${e.type}]`, e),
+});
+```
+
+| Evento | Cuando | Datos |
+| --- | --- | --- |
+| `auth:login` | Nuevo token obtenido | `service`, `durationMs` |
+| `auth:cache-hit` | Token cacheado reutilizado | `service` |
+| `request:start` | Antes de una llamada SOAP | `method`, `endpoint` |
+| `request:end` | Llamada SOAP completada | `method`, `durationMs` |
+| `request:retry` | Reintentando tras error | `method`, `attempt`, `error` |
+| `request:error` | Llamada SOAP fallo | `method`, `error` |
+
+## Manejo de errores
+
+El SDK provee clases de error especificas para catch granular:
+
+```typescript
+import {
+  ArcaFecred,
+  ArcaAuthError,
+  ArcaServiceError,
+  ArcaSoapError,
+} from '@ramiidv/arca-fecred';
+
+try {
+  const resultado = await fecred.aceptarFECred(12345);
+} catch (e) {
+  if (e instanceof ArcaAuthError) {
+    // Error de autenticacion WSAA (certificado invalido, expirado, etc.)
+    console.error('Auth error:', e.message);
+    fecred.clearAuthCache(); // Limpiar cache e intentar de nuevo
+  }
+
+  if (e instanceof ArcaServiceError) {
+    // Error de negocio de WSFECRED (FCE no encontrada, estado invalido, etc.)
+    for (const err of e.errors) {
+      console.error(`[${err.code}] ${err.msg}`);
+    }
+  }
+
+  if (e instanceof ArcaSoapError) {
+    // Error HTTP/SOAP (timeout, servidor caido, etc.)
+    console.error('HTTP status:', e.statusCode);
+  }
+}
+```
+
+| Clase | Cuando se lanza |
+| --- | --- |
+| `ArcaAuthError` | Falla en login WSAA, respuesta inesperada, token/sign invalidos |
+| `ArcaServiceError` | Error devuelto por WSFECRED (FCE no encontrada, operacion invalida, etc.). Contiene `errors: { code, msg }[]` |
+| `ArcaSoapError` | Error HTTP, timeout, SOAP Fault. Contiene `statusCode?: number` |
+| `ArcaError` | Clase base para todos los errores del SDK |
+
+## API
+
+### `new ArcaFecred(config)`
+
+| Parametro | Tipo | Default | Descripcion |
+| --- | --- | --- | --- |
+| `cert` | `string` | -- | Contenido del certificado X.509 (PEM) |
+| `key` | `string` | -- | Contenido de la clave privada (PEM) |
+| `cuit` | `string` | -- | CUIT de la entidad representada |
+| `production` | `boolean` | `false` | Entorno de produccion |
+| `timeout` | `number` | `30000` | Timeout HTTP en milisegundos |
+| `retries` | `number` | `1` | Reintentos en errores transitorios |
+| `retryDelayMs` | `number` | `1000` | Delay inicial entre reintentos (exponencial) |
+| `onEvent` | `function` | -- | Callback para eventos del SDK |
+
+### Consultas de operaciones
+
+| Metodo | Descripcion |
+| --- | --- |
+| `consultarMontoObligadoRecepcion(cuit)` | Verifica si una CUIT esta obligada a recibir FCE |
+| `consultarCtasCtes(params)` | Consulta cuentas corrientes de actividad FCE |
+| `consultarComprobantes(params)` | Busca comprobantes FCE por filtros |
+
+### Acciones sobre FCE
+
+| Metodo | Descripcion |
+| --- | --- |
+| `aceptarFECred(codCtaCte)` | Acepta una FCE |
+| `rechazarFECred(codCtaCte, codMotivoRechazo)` | Rechaza una FCE con motivo |
+| `informarFacturaAceptadaCancelada(params)` | Informa que una FCE aceptada fue pagada/cancelada |
+
+### Consultas de parametros
+
+| Metodo | Descripcion |
+| --- | --- |
+| `consultarTiposRetenciones()` | Tipos de retenciones disponibles |
+| `consultarTiposFormasCancelacion()` | Formas de cancelacion disponibles |
+| `consultarTiposAjustesOperacion()` | Tipos de ajustes de operacion disponibles |
+| `consultarTiposMotivoRechazo()` | Motivos de rechazo disponibles |
+
+### Estado y utilidades
+
+| Metodo | Descripcion |
+| --- | --- |
+| `status()` | Health check del servicio WSFECRED (no requiere autenticacion) |
+| `clearAuthCache()` | Invalida el ticket de acceso cacheado |
+
+### Acceso a clientes de bajo nivel
+
+Para casos avanzados, se pueden usar los clientes individuales directamente:
+
+```typescript
+const fecred = new ArcaFecred({ /* ... */ });
+
+// Obtener ticket de acceso manualmente
+const ticket = await fecred.wsaa.getAccessTicket('wsfecred');
+
+const credenciales = {
+  Token: ticket.token,
+  Sign: ticket.sign,
+  Cuit: '20123456789',
+};
+
+// Llamar directamente al servicio
+const rawResult = await fecred.fecred.consultarMontoObligadoRecepcion(
+  credenciales,
+  '30712345678',
+);
+```
+
+## Enums disponibles
+
+- `RolCtaCte` -- Rol en la cuenta corriente (EMISOR, RECEPTOR)
+- `EstadoCtaCte` -- Estado de la cuenta corriente (PENDIENTE_ACEPTACION, ACEPTADA, RECHAZADA, CANCELADA, ANULADA)
+- `MotivoRechazo` -- Motivos de rechazo (NOTA_CREDITO_DEBITO, CUIT_INCORRECTO, FECHA_INCORRECTA, CBU_INCORRECTO, OTROS)
+- `FormaCancelacion` -- Formas de cancelacion (ACREDITACION_CUENTA, TRANSFERENCIA, CHEQUE, PAGO_ELECTRONICO, COMPENSACION, ENDOSO, OTRO)
+- `TipoAjusteOperacion` -- Tipos de ajuste (NOTA_CREDITO, NOTA_DEBITO)
+- `TipoRetencion` -- Tipos de retencion (GANANCIAS, IVA, SUSS, INGRESOS_BRUTOS, OTRAS)
+
+## Entornos
+
+| Entorno | WSAA | WSFECRED |
+| --- | --- | --- |
+| Testing | `wsaahomo.afip.gov.ar` | `fwshomo.afip.gob.ar` |
+| Produccion | `wsaa.afip.gov.ar` | `serviciosjava.afip.gob.ar` |
+
+## Licencia
+
+MIT

package/dist/arca-fecred.d.ts

@@ -0,0 +1,129 @@
+import { WsaaClient } from '@ramiidv/arca-common';
+import type { ServerStatus } from '@ramiidv/arca-common';
+import { FecredClient } from './fecred-client.js';
+import type { ArcaFecredConfig, MontoObligadoResult, CtaCte, ComprobanteFecred, ConsultarCtasCtesParams, ConsultarComprobantesParams, AceptarFecredResult, RechazarFecredResult, InformarCanceladaParams, InformarCanceladaResult, TipoRetencionItem, TipoFormaCancelacionItem, TipoAjusteOperacionItem, TipoMotivoRechazoItem } from './types.js';
+/**
+ * Main orchestrator class for ARCA WSFECRED (Factura de Credito Electronica MiPyME).
+ *
+ * Provides high-level methods that handle WSAA authentication automatically
+ * and expose results from the WSFECRED web service for managing FCE
+ * (Electronic Credit Invoices) under Law 27440.
+ *
+ * @example
+ * ```ts
+ * import { ArcaFecred } from '@ramiidv/arca-fecred';
+ * import { readFileSync } from 'fs';
+ *
+ * const fecred = new ArcaFecred({
+ *   cert: readFileSync('cert.pem', 'utf-8'),
+ *   key: readFileSync('key.pem', 'utf-8'),
+ *   cuit: '20123456789',
+ *   production: false,
+ * });
+ *
+ * // Check if a CUIT is obligated to receive FCE
+ * const obligado = await fecred.consultarMontoObligadoRecepcion('30712345678');
+ * console.log(obligado.obligado); // true/false
+ *
+ * // Query current accounts
+ * const cuentas = await fecred.consultarCtasCtes({
+ *   rol: 'Receptor',
+ *   fechaDesde: '2026-01-01',
+ *   fechaHasta: '2026-03-31',
+ * });
+ * ```
+ */
+export declare class ArcaFecred {
+    /** Low-level WSAA client for direct access */
+    readonly wsaa: WsaaClient;
+    /** Low-level WSFECRED client for direct access */
+    readonly fecred: FecredClient;
+    private readonly cuit;
+    private readonly onEvent?;
+    constructor(config: ArcaFecredConfig);
+    /**
+     * Health check for the WSFECRED service.
+     * Does not require authentication.
+     */
+    status(): Promise<ServerStatus>;
+    /**
+     * Check if a CUIT is obligated to receive FCE (Factura de Credito Electronica).
+     * Authenticates automatically via WSAA.
+     *
+     * @param cuitConsultada - CUIT to check
+     * @returns Result indicating if the CUIT is obligated and the threshold amount
+     */
+    consultarMontoObligadoRecepcion(cuitConsultada: string): Promise<MontoObligadoResult>;
+    /**
+     * Query current accounts from FCE activity.
+     * Authenticates automatically via WSAA.
+     *
+     * @param params - Query filters (role, CUITs, date range)
+     * @returns Array of current account records
+     */
+    consultarCtasCtes(params: ConsultarCtasCtesParams): Promise<CtaCte[]>;
+    /**
+     * Search FCE invoices by filters.
+     * Authenticates automatically via WSAA.
+     *
+     * @param params - Query filters
+     * @returns Array of FCE invoice records
+     */
+    consultarComprobantes(params: ConsultarComprobantesParams): Promise<ComprobanteFecred[]>;
+    /**
+     * Accept an FCE (Factura de Credito Electronica).
+     * Authenticates automatically via WSAA.
+     *
+     * @param codCtaCte - Current account code of the FCE to accept
+     * @returns Result of the acceptance operation
+     */
+    aceptarFECred(codCtaCte: number): Promise<AceptarFecredResult>;
+    /**
+     * Reject an FCE (Factura de Credito Electronica).
+     * Authenticates automatically via WSAA.
+     *
+     * @param codCtaCte - Current account code of the FCE to reject
+     * @param codMotivoRechazo - Rejection reason code (use MotivoRechazo enum)
+     * @returns Result of the rejection operation
+     */
+    rechazarFECred(codCtaCte: number, codMotivoRechazo: number): Promise<RechazarFecredResult>;
+    /**
+     * Inform that an accepted FCE was paid/cancelled.
+     * Authenticates automatically via WSAA.
+     *
+     * @param params - Cancellation details (account code, payment method, optional observations)
+     * @returns Result of the cancellation notification
+     */
+    informarFacturaAceptadaCancelada(params: InformarCanceladaParams): Promise<InformarCanceladaResult>;
+    /**
+     * Query available retention types.
+     * Authenticates automatically via WSAA.
+     */
+    consultarTiposRetenciones(): Promise<TipoRetencionItem[]>;
+    /**
+     * Query available payment method types for cancelling accepted FCE.
+     * Authenticates automatically via WSAA.
+     */
+    consultarTiposFormasCancelacion(): Promise<TipoFormaCancelacionItem[]>;
+    /**
+     * Query available operation adjustment types.
+     * Authenticates automatically via WSAA.
+     */
+    consultarTiposAjustesOperacion(): Promise<TipoAjusteOperacionItem[]>;
+    /**
+     * Query available rejection reason types.
+     * Authenticates automatically via WSAA.
+     */
+    consultarTiposMotivoRechazo(): Promise<TipoMotivoRechazoItem[]>;
+    /** Invalidate the cached WSAA access ticket for WSFECRED. */
+    clearAuthCache(): void;
+    private getAuth;
+    private parseCtaCte;
+    private parseComprobante;
+    /**
+     * Generic parser for parameter arrays from WSFECRED responses.
+     * Handles varying SOAP response structures (different key names, namespaces).
+     */
+    private parseParamArray;
+}
+//# sourceMappingURL=arca-fecred.d.ts.map

package/dist/arca-fecred.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arca-fecred.d.ts","sourceRoot":"","sources":["../src/arca-fecred.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAe,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EAA8B,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAErF,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,KAAK,EACV,gBAAgB,EAEhB,mBAAmB,EACnB,MAAM,EACN,iBAAiB,EACjB,uBAAuB,EACvB,2BAA2B,EAC3B,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,EACvB,uBAAuB,EACvB,iBAAiB,EACjB,wBAAwB,EACxB,uBAAuB,EACvB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,UAAU;IACrB,8CAA8C;IAC9C,SAAgB,IAAI,EAAE,UAAU,CAAC;IACjC,kDAAkD;IAClD,SAAgB,MAAM,EAAE,YAAY,CAAC;IAErC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAA6B;gBAE1C,MAAM,EAAE,gBAAgB;IAkCpC;;;OAGG;IACG,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAQrC;;;;;;OAMG;IACG,+BAA+B,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAe3F;;;;;;OAMG;IACG,iBAAiB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAsB3E;;;;;;OAMG;IACG,qBAAqB,CAAC,MAAM,EAAE,2BAA2B,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAyB9F;;;;;;OAMG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAYpE;;;;;;;OAOG;IACG,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAYhG;;;;;;OAMG;IACG,gCAAgC,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAoBzG;;;OAGG;IACG,yBAAyB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAc/D;;;OAGG;IACG,+BAA+B,IAAI,OAAO,CAAC,wBAAwB,EAAE,CAAC;IAc5E;;;OAGG;IACG,8BAA8B,IAAI,OAAO,CAAC,uBAAuB,EAAE,CAAC;IAc1E;;;OAGG;IACG,2BAA2B,IAAI,OAAO,CAAC,qBAAqB,EAAE,CAAC;IAkBrE,6DAA6D;IAC7D,cAAc,IAAI,IAAI;YAQR,OAAO;IASrB,OAAO,CAAC,WAAW;IAsBnB,OAAO,CAAC,gBAAgB;IA4CxB;;;OAGG;IACH,OAAO,CAAC,eAAe;CA6BxB"}