facturas 0.12.4 → 0.13.0

package/README.md

@@ -4,14 +4,16 @@
 [![CI](https://github.com/LaPyme/facturas/actions/workflows/ci.yml/badge.svg)](https://github.com/LaPyme/facturas/actions/workflows/ci.yml)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://github.com/LaPyme/facturas/blob/main/LICENSE)
 
-SDK de Node.js para ARCA / AFIP: facturas, notas de crédito y Padrón, con
-integración directa a WSFE y WSMTXCA.
+SDK de Node.js para facturación electrónica con ARCA / AFIP. Emití facturas,
+notas de crédito y notas de débito, y consultá el Padrón con una sola API.
 
 - **Solo ESM**, Node.js **>= 20**
 - **CLI incluido**: `npx facturas init` genera la clave y el CSR, y
   `npx facturas check` nombra la capa de ARCA que falla
 - **Integración directa con ARCA**, sin proxy ni dependencia alojada
-- **Login WSAA resuelto**: caché en memoria, stores de sesión durables,
+- **Una API de emisión**: el SDK deriva el pedido fiscal y mantiene los detalles
+  de cada servicio fuera del flujo normal
+- **Login WSAA resuelto**: caché en memoria, stores de sesión persistentes,
   deduplicación de logins en vuelo y recuperación de `coe.alreadyAuthenticated`
 - **API pública en TypeScript estricto**, con nombres al estilo JS mapeados a
   SOAP internamente
@@ -20,8 +22,8 @@ integración directa a WSFE y WSMTXCA.
 - **Ejemplos copiables**, escritos para que los lean personas y agentes de
   código
 
-La documentación está en castellano, en [docs/](./docs/README.md).
-[English summary](./docs/en/README.md).
+La documentación está en castellano, en el [sitio de documentación](https://facturas-sdk.dev)
+y en su [fuente Mintlify](./docs/index.mdx).
 
 ## Instalación
 
@@ -33,7 +35,7 @@ npm install facturas
 
 ## Emití tu primera factura
 
-Definí las [variables de entorno](./docs/configuracion.md#variables-de-entorno)
+Definí las [variables de entorno](./docs/reference/configuration.mdx#variables-de-entorno)
 con tu CUIT, certificado y clave. No hace falta nada más: ni base de datos, ni
 tabla, ni servicio externo.
 
@@ -52,22 +54,22 @@ const factura = await arca.issue({
 
 Tratá siempre los cuatro resultados:
 
-| Resultado | Significado y acción del llamador |
+| Resultado | Qué significa y qué hacer |
 | --- | --- |
-| `authorized` | Guardá el comprobante y el CAE. `recoveredByMatch: true` significa que el input guardado coincidió con la identidad consultada; prueba consistencia, no autoría. |
+| `authorized` | Guardá el comprobante y el CAE. `recoveredByMatch: true` significa que el input guardado coincidió con la identidad consultada. Esto prueba consistencia, no autoría. |
 | `rejected` | Revisá los `issues` de ARCA. Una clave queda ligada a su input incluso después de un rechazo. |
 | `indeterminate` | Conservá el número y la evidencia. Conciliá o repetí el input idéntico con su clave existente. |
 | `conflict` | Hay otro comprobante en el número reservado. Detené el flujo e investigá. |
 
-El paso a paso está en [Inicio rápido](./docs/inicio-rapido.md); el detalle, en
-[Facturas](./docs/facturas.md).
+El paso a paso está en [Inicio rápido](./docs/getting-started/quickstart.mdx).
+El detalle está en [Facturas](./docs/guides/invoices.mdx).
 
 ## Reintentos seguros
 
-Recomendado en toda aplicación real, opcional para empezar. Sin
-`idempotencyKey`, un reintento después de una caída puede emitir la factura dos
-veces. Con un `store` y el ID estable de la venta como clave, el reintento
-consulta el número reservado y nunca vuelve a emitir.
+ARCA no recibe una clave de idempotencia como Stripe. Si una respuesta se
+pierde, no puede distinguir un reintento de una emisión nueva. `facturas` te
+permite guardar cada intento en un `store` con el ID estable de tu venta. Al
+repetir esa clave, consulta el número reservado en vez de empezar otra emisión.
 
 ```ts
 import { createArcaClient, createPostgresStore } from "facturas";
@@ -81,12 +83,13 @@ const factura = await arca.issue(input, { idempotencyKey: venta.id });
 ```
 
 Hay adaptadores para Postgres, Redis, archivos y memoria, y podés escribir el
-tuyo; con ellos, dos emisiones simultáneas sobre el mismo punto de venta se
-serializan y cada una escribe su número. Ver [Stores](./docs/stores.md).
+tuyo. Con ellos, dos emisiones simultáneas sobre el mismo punto de venta se
+serializan y cada una escribe su número. Ver
+[Evitar comprobantes duplicados](./docs/guides/avoid-duplicates.mdx).
 
 ## Nota de crédito
 
-ARCA no anula comprobantes: una corrección es una nota de crédito y también es
+ARCA no anula comprobantes. Una corrección es una nota de crédito y también es
 un documento real que queda en los registros de ARCA. Lo habitual es la nota
 parcial, que acredita las líneas que elegís.
 
@@ -101,31 +104,34 @@ const nota = await arca.issueCreditNote(
 ```
 
 Con `all: true` acreditás el original completo. El modo es explícito y
-obligatorio. La misma fachada emite [notas de débito y por
-período](./docs/notas-de-credito.md), tributos, FCE, [detalle de ítems por
-WSMTXCA](./docs/wsmtxca.md) y `recover()`, que concilia sin emitir.
+obligatorio. También podés emitir [notas de débito y por
+período](./docs/guides/credit-notes.mdx), tributos y FCE. `recover()` concilia
+una reserva sin emitir.
 
 ## Documentación
 
-- [Inicio rápido](./docs/inicio-rapido.md): de cero a la primera factura y su
+- [Inicio rápido](./docs/getting-started/quickstart.mdx): de cero a la primera factura y su
   nota de crédito.
-- [Habilitación en ARCA](./docs/habilitacion-arca.md): CUIT, certificado, punto
+- [Habilitación en ARCA](./docs/getting-started/arca-setup.mdx): CUIT, certificado, punto
   de venta y referencias oficiales.
-- [CLI](./docs/cli.md): `init`, `check` e `issue`, con la tabla de diagnósticos.
-- [Facturas](./docs/facturas.md): `issue()`, `preview()`, datos de la factura y
-  contrato fiscal de la fachada.
-- [Notas de crédito](./docs/notas-de-credito.md): `issueCreditNote()`, modo
+- [CLI](./docs/getting-started/cli.mdx): `init`, `check` e `issue`, con la tabla de diagnósticos.
+- [Facturas](./docs/guides/invoices.mdx): `issue()`, `preview()`, datos de la factura y
+  contrato fiscal de emisión.
+- [Notas de crédito](./docs/guides/credit-notes.mdx): `issueCreditNote()`, modo
   parcial y modo total.
-- [Stores](./docs/stores.md): Postgres, Redis, archivos, memoria, store propio
-  y vida de los registros.
-- [Configuración](./docs/configuracion.md): variables de entorno, opciones del
-  cliente, sesiones WSAA, logging, reintentos y timeouts.
-- [Capa exacta](./docs/capa-exacta.md): builders, superficie de servicios,
-  emisión exacta y evidencia de recuperación.
-- [Errores](./docs/errores.md): clases de error y diagnóstico.
-- [Referencia](./docs/referencia.md): constantes, API pública con semver y
+- [Evitar comprobantes duplicados](./docs/guides/avoid-duplicates.mdx): claves para
+  reintentos, Postgres, Redis, archivos y memoria.
+- [WSMTXCA para casos requeridos](./docs/guides/wsmtxca.mdx): configuración
+  avanzada para contribuyentes o puntos de venta que operan con ese servicio.
+- [Configuración](./docs/reference/configuration.mdx): variables de entorno, opciones del
+  cliente, sesiones WSAA, logs, reintentos y límites de tiempo.
+- [Módulos de transporte](./docs/reference/arca-services.mdx): `client.wsfe`,
+  `client.wsmtxca` y `client.padron` para lecturas, catálogos, estado del
+  servicio y Padrón.
+- [Errores](./docs/reference/errors.mdx): clases de error y diagnóstico.
+- [Referencia](./docs/reference/public-api.mdx): constantes, API pública con semver y
   seguridad.
-- [Ejemplos](./docs/ejemplos.md): índice de [examples/](./examples).
+- [Ejemplos](./docs/reference/examples.mdx): índice de [examples/](./examples).
 
 ## Estado del proyecto
 

package/dist/{chunk-YYDSBHMO.mjs → chunk-BPBTQDCO.mjs}

@@ -1,6 +1,3 @@
-import {
-  ARCA_VAT_RATES
-} from "./chunk-GX5ERXT6.mjs";
 import {
   classifyArcaAuthenticationError,
   classifyArcaAuthenticationIssues,
@@ -23,14 +20,6 @@ var PERCENTAGE_SCALE = 100;
 var MAX_ARCA_AMOUNT_MINOR_UNITS = 999999999999999n;
 var MAX_ARCA_EXCHANGE_RATE_SCALED = 9999999999n;
 var MAX_ARCA_PERCENTAGE_HUNDREDTHS = 99999n;
-var VAT_RATE_BASIS_POINTS = {
-  0: 0n,
-  2.5: 250n,
-  5: 500n,
-  10.5: 1050n,
-  21: 2100n,
-  27: 2700n
-};
 function normalizeArcaAmountToMinorUnits(value, field) {
   return normalizeScaledNumber({
     value,
@@ -91,17 +80,6 @@ function arcaMinorUnitsToNumber(minorUnits, field) {
   }
   return Number(formatScaledInteger(minorUnits, 2));
 }
-function calculateVatMinorUnits(taxableMinorUnits, vatRate, field) {
-  const basisPoints = VAT_RATE_BASIS_POINTS[vatRate];
-  if (basisPoints === void 0) {
-    throw new ArcaInputError(`${field} is not a supported VAT rate.`, {
-      code: "ARCA_INPUT_INVALID_VALUE",
-      field,
-      expected: "one of 0, 2.5, 5, 10.5, 21, or 27"
-    });
-  }
-  return roundHalfEvenRatio(taxableMinorUnits * basisPoints, 10000n);
-}
 function roundHalfEvenRatio(numerator, denominator) {
   if (numerator < 0n || denominator <= 0n) {
     throw new RangeError(
@@ -226,13 +204,13 @@ function createWsfeService(options) {
     const auth = await options.auth.login("wsfe", {
       representedTaxId: input.representedTaxId,
       forceRefresh: input.forceRefresh,
-      signal: input.signal
+      abortSignal: input.abortSignal
     });
     const response = await options.soap.execute({
       service: "wsfe",
       operation,
       ...retries === void 0 ? {} : { retries },
-      signal: input.signal,
+      signal: input.abortSignal,
       body: {
         Auth: createWsfeAuth(
           input.representedTaxId ?? options.config.taxId,
@@ -255,7 +233,7 @@ function createWsfeService(options) {
           {
             representedTaxId: input.representedTaxId,
             forceRefresh,
-            signal: input.signal
+            abortSignal: input.abortSignal
           },
           body
         );
@@ -279,14 +257,14 @@ function createWsfeService(options) {
     salesPoint,
     voucherType,
     forceRefresh,
-    signal
+    abortSignal
   }) {
     const result = await executeWsfeAuthenticatedOperation(
       "FECompUltimoAutorizado",
       {
         representedTaxId,
         forceRefresh,
-        signal
+        abortSignal
       },
       {
         PtoVta: salesPoint,
@@ -307,7 +285,7 @@ function createWsfeService(options) {
     data,
     voucherNumber,
     forceRefresh,
-    signal
+    abortSignal
   }) {
     const normalizedInput = normalizeWsfeVoucherInput(data);
     return executeWsfeAuthorization({
@@ -315,7 +293,7 @@ function createWsfeService(options) {
       data: normalizedInput,
       voucherNumber,
       forceRefresh,
-      signal
+      abortSignal
     }).then(({ outcome }) => outcome);
   }
   async function executeWsfeAuthorization({
@@ -323,13 +301,13 @@ function createWsfeService(options) {
     data: normalizedInput,
     voucherNumber,
     forceRefresh,
-    signal
+    abortSignal
   }) {
     const requestData = mapWsfeVoucherInput(normalizedInput, voucherNumber);
     try {
       const result = await executeWsfeAuthenticatedRawOperation(
         "FECAESolicitar",
-        { representedTaxId, forceRefresh, signal },
+        { representedTaxId, forceRefresh, abortSignal },
         {
           FeCAEReq: {
             FeCabReq: {
@@ -360,7 +338,7 @@ function createWsfeService(options) {
     salesPoint,
     voucherType,
     forceRefresh,
-    signal
+    abortSignal
   }) {
     return executeWithAuthenticationRecovery({
       service: "wsfe",
@@ -372,7 +350,7 @@ function createWsfeService(options) {
         salesPoint,
         voucherType,
         forceRefresh: attemptForceRefresh,
-        signal
+        abortSignal
       })
     });
   }
@@ -382,12 +360,12 @@ function createWsfeService(options) {
     salesPoint,
     voucherType,
     forceRefresh,
-    signal
+    abortSignal
   }) {
     const operation = "FECompConsultar";
     const result = await executeWsfeAuthenticatedRawOperation(
       operation,
-      { representedTaxId, forceRefresh, signal },
+      { representedTaxId, forceRefresh, abortSignal },
       {
         FeCompConsReq: {
           CbteNro: number,
@@ -1462,150 +1440,15 @@ function getWsfeResultEntries(result, key) {
   );
 }
 
-// src/services/wsfe-amounts.ts
-var RATES = {
-  0: { id: ARCA_VAT_RATES.IVA_0, basisPoints: 0n },
-  2.5: { id: ARCA_VAT_RATES.IVA_2_5, basisPoints: 250n },
-  5: { id: ARCA_VAT_RATES.IVA_5, basisPoints: 500n },
-  10.5: { id: ARCA_VAT_RATES.IVA_10_5, basisPoints: 1050n },
-  21: { id: ARCA_VAT_RATES.IVA_21, basisPoints: 2100n },
-  27: { id: ARCA_VAT_RATES.IVA_27, basisPoints: 2700n }
-};
-function calculateWsfeAmounts(input) {
-  if (!Array.isArray(input.items) || input.items.length === 0) {
-    invalidItem("items", "a non-empty array of items");
-  }
-  const isVat = input.voucherClass === "A" || input.voucherClass === "B";
-  if (!(isVat || input.voucherClass === "C")) {
-    invalidItem("voucherClass", "A, B or C");
-  }
-  const totals = collectItems(input.items, isVat);
-  let net = totals.net;
-  let vat = 0n;
-  const { exempt, untaxed, groups } = totals;
-  const vatRates = [];
-  for (const [rate, group] of groups) {
-    const { id, basisPoints } = RATES[rate];
-    const netFromGross = roundHalfEvenRatio(
-      group.gross * 10000n,
-      10000n + basisPoints
-    );
-    const base = group.net + netFromGross;
-    const tax = roundHalfEvenRatio(group.net * basisPoints, 10000n) + group.gross - netFromGross;
-    if (base === 0n) {
-      continue;
-    }
-    net += base;
-    vat += tax;
-    vatRates.push({
-      id,
-      baseAmount: arcaMinorUnitsToNumber(base, "netAmount"),
-      amount: arcaMinorUnitsToNumber(tax, "vatAmount")
-    });
-  }
-  const computed = net + vat + exempt + untaxed;
-  arcaMinorUnitsToNumber(computed, "totalAmount");
-  const sent = input.total === void 0 ? computed : assertArcaMinorUnits(input.total, "total");
-  const adjustment = sent - computed;
-  const allowance = BigInt(vatRates.length);
-  if (adjustment < -allowance || adjustment > allowance || vat + adjustment < 0n) {
-    throw new ArcaInputError(
-      "total does not match the computed amount within the VAT allowance.",
-      {
-        code: "ARCA_INPUT_AMOUNT_MISMATCH",
-        field: "total",
-        expected: `${computed} minor units (at most ${allowance} minor units of VAT adjustment, with non-negative VAT)`
-      }
-    );
-  }
-  return {
-    data: {
-      totalAmount: arcaMinorUnitsToNumber(sent, "totalAmount"),
-      netAmount: arcaMinorUnitsToNumber(net, "netAmount"),
-      vatAmount: arcaMinorUnitsToNumber(vat + adjustment, "vatAmount"),
-      nonTaxableAmount: arcaMinorUnitsToNumber(untaxed, "nonTaxableAmount"),
-      exemptAmount: arcaMinorUnitsToNumber(exempt, "exemptAmount"),
-      taxAmount: 0,
-      ...isVat ? { vatRates } : {}
-    },
-    amounts: {
-      computedTotal: Number(computed),
-      sentTotal: Number(sent),
-      vatAdjustment: Number(adjustment)
-    }
-  };
-}
-function collectItems(items, isVat) {
-  let net = 0n;
-  let exempt = 0n;
-  let untaxed = 0n;
-  const groups = /* @__PURE__ */ new Map();
-  for (const [index, item] of items.entries()) {
-    const path = `items[${index}]`;
-    if (item === null || typeof item !== "object" || Array.isArray(item)) {
-      invalidItem(path, "an item object");
-    }
-    if (!isVat) {
-      net += classCAmount(item, path);
-      continue;
-    }
-    const { amount, field, rate } = vatItemAmount(item, path);
-    if (rate === "exempt") {
-      exempt += amount;
-      continue;
-    }
-    if (rate === "untaxed") {
-      untaxed += amount;
-      continue;
-    }
-    const group = groups.get(rate) ?? { net: 0n, gross: 0n };
-    group[field] += amount;
-    groups.set(rate, group);
-  }
-  return { net, exempt, untaxed, groups };
-}
-function classCAmount(item, path) {
-  if ("vat" in item || "net" in item || "gross" in item) {
-    invalidItem("items", "amount items for a class C voucher");
-  }
-  return assertArcaMinorUnits(item.amount, `${path}.amount`);
-}
-function vatItemAmount(item, path) {
-  if ("amount" in item || "net" in item === "gross" in item) {
-    invalidItem(
-      "items",
-      "exactly one of net or gross, and vat, for a class A or B voucher"
-    );
-  }
-  const field = "net" in item ? "net" : "gross";
-  const amount = assertArcaMinorUnits(
-    item[field],
-    `${path}.${field}`
-  );
-  const rate = item.vat;
-  if (rate !== "exempt" && rate !== "untaxed" && (typeof rate !== "number" || !Object.hasOwn(RATES, rate))) {
-    invalidItem(`${path}.vat`, "0, 2.5, 5, 10.5, 21, 27, exempt, or untaxed");
-  }
-  return { amount, field, rate };
-}
-function invalidItem(field, expected) {
-  throw new ArcaInputError(`${field} must be ${expected}.`, {
-    code: "ARCA_INPUT_INVALID_VALUE",
-    field,
-    expected
-  });
-}
-
 export {
   normalizeArcaAmountToMinorUnits,
   serializeArcaExchangeRate,
   assertArcaMinorUnits,
   arcaMinorUnitsToNumber,
-  calculateVatMinorUnits,
+  roundHalfEvenRatio,
   isWithinArcaTolerance,
   createWsfeService,
   normalizeWsfeVoucherInput,
-  normalizeWsfeDateInput,
-  calculateWsfeAmounts
+  normalizeWsfeDateInput
 };
-//# sourceMappingURL=chunk-YYDSBHMO.mjs.map
+//# sourceMappingURL=chunk-BPBTQDCO.mjs.map