facturas 0.8.0 → 0.10.0

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import {
   createPadronService
-} from "./chunk-NUV5RZPZ.mjs";
+} from "./chunk-7LEKQ4P7.mjs";
 import {
   buildFacturaB,
   buildFacturaC,
@@ -10,7 +10,7 @@ import {
   normalizeWsfeDateInput,
   normalizeWsfeVoucherInput,
   serializeArcaExchangeRate
-} from "./chunk-TOVSOJ3G.mjs";
+} from "./chunk-QHHLHSBW.mjs";
 import {
   ARCA_CURRENCY_IDS,
   ARCA_DOCUMENT_TYPES,
@@ -22,8 +22,8 @@ import {
 } from "./chunk-76WU5BVI.mjs";
 import {
   createWsmtxcaService
-} from "./chunk-ZX4OOCML.mjs";
-import "./chunk-PPYGVNFA.mjs";
+} from "./chunk-ALH5IPSY.mjs";
+import "./chunk-UDX6HLAU.mjs";
 import {
   ArcaAuthenticationError,
   ArcaConfigurationError,
@@ -37,7 +37,7 @@ import {
   createSafeErrorDiagnostic,
   isArcaAuthenticationError,
   toArcaSafeErrorMetadata
-} from "./chunk-HUT3PFKF.mjs";
+} from "./chunk-ZOSNASXB.mjs";
 
 // src/config.ts
 var ARCA_ENVIRONMENTS = ["production", "test"];
@@ -88,17 +88,7 @@ function assertArcaClientConfig(config) {
       "Encrypted private keys are not supported. Provide an unencrypted PKCS#8 or RSA private key PEM."
     );
   }
-  if (!/^\d{11}$/.test(normalized.taxId)) {
-    invalidFields.push("taxId");
-  }
-  if (!normalized.certificatePem.startsWith("-----BEGIN CERTIFICATE-----")) {
-    invalidFields.push("certificatePem");
-  }
-  if (!PRIVATE_KEY_PEM_PREFIXES.some(
-    (prefix) => normalized.privateKeyPem.startsWith(prefix)
-  )) {
-    invalidFields.push("privateKeyPem");
-  }
+  invalidFields.push(...invalidCredentialFields(normalized));
   if (!ARCA_ENVIRONMENTS.includes(normalized.environment)) {
     invalidFields.push("environment");
   }
@@ -210,10 +200,11 @@ function normalizeArcaClientConfig(config) {
   const normalizedEnvironment = normalizeEnvironmentValue(String(config.environment)) ?? config.environment;
   const normalizedLoggerLevel = normalizeLogLevelValue(config.logger?.level);
   return {
-    taxId: config.taxId.trim(),
-    certificatePem: config.certificatePem.trim(),
-    privateKeyPem: config.privateKeyPem.trim(),
-    environment: normalizedEnvironment,
+    taxId: config.taxId?.trim() ?? "",
+    certificatePem: config.certificatePem?.trim() ?? "",
+    privateKeyPem: config.privateKeyPem?.trim() ?? "",
+    environment: normalizedEnvironment ?? "test",
+    ...config.store === void 0 ? {} : { store: config.store },
     timeout: config.timeout ?? DEFAULT_ARCA_TIMEOUT_MS,
     retries: config.retries ?? DEFAULT_ARCA_RETRIES,
     retryDelay: config.retryDelay ?? DEFAULT_ARCA_RETRY_DELAY_MS,
@@ -249,6 +240,40 @@ function normalizeLogLevelValue(value) {
   }
   return value;
 }
+function discoverArcaClientConfig(config) {
+  const environment = config.environment ?? readEnv(process.env, ARCA_ENV_VARIABLES.environment);
+  if (environment === void 0) {
+    throw new ArcaConfigurationError(
+      `environment is required: pass environment or set ${ARCA_ENV_VARIABLES.environment} to "test" or "production".`
+    );
+  }
+  return {
+    ...config,
+    taxId: config.taxId ?? readEnv(process.env, ARCA_ENV_VARIABLES.taxId) ?? "",
+    certificatePem: config.certificatePem ?? readEnv(process.env, ARCA_ENV_VARIABLES.certificatePem) ?? "",
+    privateKeyPem: config.privateKeyPem ?? readEnv(process.env, ARCA_ENV_VARIABLES.privateKeyPem) ?? "",
+    environment
+  };
+}
+function invalidCredentialFields(normalized) {
+  const invalidFields = [];
+  if (!/^\d{11}$/.test(normalized.taxId)) {
+    invalidFields.push(normalized.taxId ? "taxId" : "taxId (ARCA_TAX_ID)");
+  }
+  if (!normalized.certificatePem.startsWith("-----BEGIN CERTIFICATE-----")) {
+    invalidFields.push(
+      normalized.certificatePem ? "certificatePem" : "certificatePem (ARCA_CERTIFICATE_PEM)"
+    );
+  }
+  if (!PRIVATE_KEY_PEM_PREFIXES.some(
+    (prefix) => normalized.privateKeyPem.startsWith(prefix)
+  )) {
+    invalidFields.push(
+      normalized.privateKeyPem ? "privateKeyPem" : "privateKeyPem (ARCA_PRIVATE_KEY_PEM)"
+    );
+  }
+  return invalidFields;
+}
 
 // src/internal/logger.ts
 var ARCA_LOG_LEVELS = ["debug", "info", "warn", "error"];
@@ -301,6 +326,36 @@ function defaultArcaLog(level, message, ...args) {
   method(message, ...args);
 }
 
+// src/store/types.ts
+import { createHash } from "crypto";
+function attemptKey(environment, taxId, key) {
+  return `arca:v1:attempt:${environment}:${taxId}:${key}`;
+}
+function canonicalHash(input) {
+  return createHash("sha256").update(JSON.stringify(canonical(input))).digest("hex");
+}
+function canonical(value) {
+  if (Array.isArray(value)) {
+    return value.map(canonical);
+  }
+  if (value instanceof Date) {
+    return value.toJSON();
+  }
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).filter(([, item]) => item !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, item]) => [key, canonical(item)])
+    );
+  }
+  return value;
+}
+async function storeCall(fn) {
+  try {
+    return await fn();
+  } catch (cause) {
+    throw new ArcaConfigurationError("ARCA store operation failed.", { cause });
+  }
+}
+
 // src/services/wsfe-derive.ts
 var INVOICE_TYPES = {
   A: ARCA_VOUCHER_TYPES.FACTURA_A,
@@ -324,18 +379,15 @@ function deriveWsfeInvoice(input, now = /* @__PURE__ */ new Date()) {
     ],
     "input"
   );
-  if (typeof input.issuer !== "string" || !Object.hasOwn(ARCA_ISSUER_CONDITION_IDS, input.issuer)) {
-    invalid(
-      "issuer",
-      "responsable_inscripto, monotributo, exento, or no_alcanzado"
-    );
-  }
-  if (!Number.isSafeInteger(input.salesPoint) || input.salesPoint < 1 || input.salesPoint > 99999) {
-    invalid("salesPoint", "an integer from 1 through 99999");
-  }
+  assertIssuerCondition(input.issuer);
+  assertSalesPoint(input.salesPoint);
   const receiver = deriveReceiver(input.to);
-  const voucherClass = ARCA_INVOICE_CLASS_BY_ISSUER[input.issuer][input.to.condition];
-  const { data: amountsData, amounts } = calculateWsfeAmounts(input);
+  const voucherClass = resolveInvoiceClass(input.issuer, input.to.condition);
+  const { data: amountsData, amounts } = calculateWsfeAmounts({
+    voucherClass,
+    items: input.items,
+    total: input.total
+  });
   const currency = deriveCurrency(input);
   if (input.to.condition === "consumidor_final" && receiver.documentType === ARCA_DOCUMENT_TYPES.CONSUMIDOR_FINAL) {
     const [whole, fraction = ""] = currency.exchangeRate.split(".");
@@ -375,6 +427,22 @@ function deriveWsfeInvoice(input, now = /* @__PURE__ */ new Date()) {
   }
   return { data, voucherClass, amounts };
 }
+function assertIssuerCondition(issuer) {
+  if (typeof issuer !== "string" || !Object.hasOwn(ARCA_ISSUER_CONDITION_IDS, issuer)) {
+    invalid(
+      "issuer",
+      "responsable_inscripto, monotributo, exento, or no_alcanzado"
+    );
+  }
+}
+function assertSalesPoint(salesPoint) {
+  if (!Number.isSafeInteger(salesPoint) || salesPoint < 1 || salesPoint > 99999) {
+    invalid("salesPoint", "an integer from 1 through 99999");
+  }
+}
+function resolveInvoiceClass(issuer, condition) {
+  return ARCA_INVOICE_CLASS_BY_ISSUER[issuer][condition];
+}
 function deriveReceiver(to) {
   assertIssueObject(to, "to");
   assertIssueKeys(to, ["condition", "cuit", "dni"], "to");
@@ -489,18 +557,15 @@ function assertIssueObject(value, field) {
     invalid(field, "an object");
   }
 }
-function assertIssueKeys(value, keys, prefix) {
+function assertIssueKeys(value, keys, prefix, method = "issue()") {
   for (const key of Object.keys(value)) {
     if (!keys.includes(key)) {
       const field = prefix === "input" ? key : `${prefix}.${key}`;
-      throw new ArcaInputError(
-        `${field} is not supported by vouchers.issue().`,
-        {
-          code: "ARCA_INPUT_RESERVED_FIELD",
-          field,
-          expected: "a supported facade field; use the exact API for other fiscal fields"
-        }
-      );
+      throw new ArcaInputError(`${field} is not supported by ${method}.`, {
+        code: "ARCA_INPUT_RESERVED_FIELD",
+        field,
+        expected: "a supported facade field; use the exact API for other fiscal fields"
+      });
     }
   }
 }
@@ -512,6 +577,286 @@ function invalid(field, expected) {
   });
 }
 
+// src/services/wsfe-credit-note.ts
+var NOTES = {
+  1: { voucherType: 3, voucherClass: "A" },
+  6: { voucherType: 8, voucherClass: "B" },
+  11: { voucherType: 13, voucherClass: "C" }
+};
+function invalid2(reason) {
+  throw new ArcaInputError(
+    `issueCreditNote cannot proceed: ${reason}. Use wsfe.issue() for exact control.`,
+    { code: "ARCA_INPUT_INVALID_VALUE" }
+  );
+}
+function required(value, field) {
+  if (value === void 0 || value === null) {
+    invalid2(`original is missing ${field}`);
+  }
+  return value;
+}
+function deriveWsfeFullCreditNote(original, input, now = /* @__PURE__ */ new Date()) {
+  const { note, header } = prepareCreditNote(original, input, now);
+  const data = {
+    ...header,
+    totalAmount: required(original.totalAmount, "totalAmount"),
+    netAmount: required(original.netAmount, "netAmount"),
+    vatAmount: required(original.vatAmount, "vatAmount"),
+    exemptAmount: required(original.exemptAmount, "exemptAmount"),
+    nonTaxableAmount: required(original.nonTaxableAmount, "nonTaxableAmount"),
+    taxAmount: required(original.taxAmount, "taxAmount"),
+    ...original.vatRates === void 0 ? {} : { vatRates: original.vatRates.map((rate) => ({ ...rate })) }
+  };
+  normalizeWsfeVoucherInput(data);
+  const total = Number(
+    normalizeArcaAmountToMinorUnits(data.totalAmount, "totalAmount")
+  );
+  return {
+    data,
+    voucherClass: note.voucherClass,
+    amounts: { computedTotal: total, sentTotal: total, vatAdjustment: 0 }
+  };
+}
+function deriveWsfePartialCreditNote(original, input, now = /* @__PURE__ */ new Date()) {
+  if (input.items === void 0) {
+    invalid2("items is required to credit chosen lines");
+  }
+  const { note, header } = prepareCreditNote(original, input, now);
+  const { data: amountsData, amounts } = calculateWsfeAmounts({
+    voucherClass: note.voucherClass,
+    items: input.items,
+    total: input.total
+  });
+  const originalTotal = normalizeArcaAmountToMinorUnits(
+    required(original.totalAmount, "totalAmount"),
+    "totalAmount"
+  );
+  if (BigInt(amounts.sentTotal) > originalTotal) {
+    invalid2(
+      "the note total is greater than the original; the SDK does not track earlier notes against an original"
+    );
+  }
+  const data = { ...header, ...amountsData };
+  normalizeWsfeVoucherInput(data);
+  return { data, voucherClass: note.voucherClass, amounts };
+}
+function prepareCreditNote(original, input, now) {
+  const note = NOTES[original.voucherType ?? 0];
+  if (!note) {
+    invalid2("original must be an invoice of type 1, 6 or 11");
+  }
+  if (!(["A", "O"].includes(original.result ?? "") && original.cae?.trim() && original.caeExpiry?.trim())) {
+    invalid2("original is not authorized");
+  }
+  rejectExtensions(original);
+  if (original.currencyId !== "PES" && original.currencyId !== "DOL") {
+    invalid2("unsupported currency; only ARS and USD are supported");
+  }
+  const voucherDate = normalizeWsfeDateInput(
+    input.date ?? buenosAiresDate(now),
+    "date"
+  );
+  const originalDate = normalizeWsfeDateInput(
+    required(original.voucherDate, "voucherDate"),
+    "original.voucherDate"
+  );
+  if (originalDate > voucherDate && originalDate.slice(0, 6) !== voucherDate.slice(0, 6)) {
+    invalid2(
+      "original date is later than the note and outside its month (10210)"
+    );
+  }
+  const header = {
+    salesPoint: input.salesPoint ?? required(original.salesPoint, "salesPoint"),
+    voucherType: note.voucherType,
+    concept: required(original.concept, "concept"),
+    documentType: required(original.documentType, "documentType"),
+    documentNumber: Number(required(original.documentNumber, "documentNumber")),
+    receiverVatConditionId: required(
+      original.receiverVatConditionId,
+      "receiverVatConditionId"
+    ),
+    currencyId: original.currencyId,
+    exchangeRate: required(original.exchangeRate, "exchangeRate"),
+    voucherDate,
+    associatedVouchers: [
+      {
+        type: required(original.voucherType, "voucherType"),
+        salesPoint: required(original.salesPoint, "salesPoint"),
+        number: original.voucherNumber,
+        voucherDate: originalDate
+      }
+    ]
+  };
+  copyServiceDates(original, header);
+  return { note, header };
+}
+function rejectExtensions(original) {
+  for (const [field, rawField] of [
+    ["taxes", "Tributos"],
+    ["optionalFields", "Opcionales"],
+    ["buyers", "Compradores"],
+    ["activities", "Actividades"],
+    ["associatedPeriod", "PeriodoAsoc"]
+  ]) {
+    const value = original[field];
+    const raw = original.raw[rawField];
+    if (present(value) || present(raw)) {
+      invalid2(`unsupported original ${field}`);
+    }
+  }
+  if ((original.taxAmount ?? 0) !== 0) {
+    invalid2("unsupported original taxes");
+  }
+}
+function present(value) {
+  return value !== void 0 && value !== null && value !== "" && (!Array.isArray(value) || value.length > 0);
+}
+function copyServiceDates(original, header) {
+  if (header.concept !== 2 && header.concept !== 3) {
+    return;
+  }
+  header.serviceStartDate = required(
+    original.serviceStartDate,
+    "serviceStartDate"
+  );
+  header.serviceEndDate = required(
+    original.serviceEndDate,
+    "serviceEndDate"
+  );
+  const due = normalizeWsfeDateInput(
+    required(original.paymentDueDate, "paymentDueDate"),
+    "original.paymentDueDate"
+  );
+  header.paymentDueDate = due < header.voucherDate ? header.voucherDate : due;
+}
+var CREDIT_NOTE_KEYS = ["for", "salesPoint", "date", "items", "total", "all"];
+var TARGET_BOUNDS = [
+  ["salesPoint", 99999],
+  ["voucherType", 999],
+  ["number", 99999999]
+];
+function assertCreditNoteInput(input) {
+  assertIssueObject(input, "input");
+  if ("associatedPeriod" in input) {
+    throw new ArcaInputError(
+      "issueCreditNote does not support associatedPeriod; a note against a period is exact-layer work. Use wsfe.issue() for exact control.",
+      {
+        code: "ARCA_INPUT_RESERVED_FIELD",
+        field: "associatedPeriod",
+        expected: "an associated invoice through for"
+      }
+    );
+  }
+  assertIssueKeys(input, CREDIT_NOTE_KEYS, "input", "issueCreditNote()");
+  const target = assertCreditNoteTarget(input.for);
+  if (input.salesPoint !== void 0) {
+    assertCreditNoteBound(input.salesPoint, 99999, "salesPoint");
+  }
+  const date = input.date === void 0 ? void 0 : normalizeWsfeDateInput(input.date, "date");
+  const common = {
+    for: target,
+    ...input.salesPoint === void 0 ? {} : { salesPoint: input.salesPoint },
+    ...date === void 0 ? {} : { date }
+  };
+  if (input.items === void 0 === (input.all === void 0)) {
+    throw new ArcaInputError(
+      "issueCreditNote needs exactly one mode: items for the credited lines, or all: true for the whole original.",
+      {
+        code: "ARCA_INPUT_INVALID_VALUE",
+        field: input.items === void 0 ? "input.items" : "input.all",
+        expected: "either items or all: true, never both and never neither"
+      }
+    );
+  }
+  if (input.all !== void 0) {
+    if (input.all !== true) {
+      throw new ArcaInputError(
+        "issueCreditNote accepts only all: true; pass items to credit chosen lines.",
+        {
+          code: "ARCA_INPUT_INVALID_VALUE",
+          field: "input.all",
+          expected: "the literal true"
+        }
+      );
+    }
+    if (input.total !== void 0) {
+      throw new ArcaInputError(
+        "issueCreditNote takes total only with items; all: true credits the original's own total.",
+        {
+          code: "ARCA_INPUT_INVALID_VALUE",
+          field: "input.total",
+          expected: "no total when all is true"
+        }
+      );
+    }
+    return { ...common, all: true };
+  }
+  return {
+    ...common,
+    items: copyCreditNoteItems(input.items),
+    ...input.total === void 0 ? {} : { total: input.total }
+  };
+}
+function assertCreditNoteTarget(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new ArcaInputError(
+      "issueCreditNote requires for: the coordinates of the authorized invoice the note corrects.",
+      {
+        code: "ARCA_INPUT_MISSING_FIELD",
+        field: "input.for",
+        expected: "{ salesPoint, voucherType, number }"
+      }
+    );
+  }
+  assertIssueKeys(
+    value,
+    ["salesPoint", "voucherType", "number"],
+    "input.for",
+    "issueCreditNote()"
+  );
+  for (const [field, max] of TARGET_BOUNDS) {
+    assertCreditNoteBound(value[field], max, `for.${field}`);
+  }
+  if (![1, 6, 11].includes(value.voucherType)) {
+    throw new ArcaInputError(
+      "issueCreditNote requires an authorized invoice of type 1, 6 or 11 in for.voucherType. Use wsfe.issue() for exact control.",
+      {
+        code: "ARCA_INPUT_INVALID_VALUE",
+        field: "input.for.voucherType",
+        expected: "1, 6 or 11"
+      }
+    );
+  }
+  return {
+    salesPoint: value.salesPoint,
+    voucherType: value.voucherType,
+    number: value.number
+  };
+}
+function assertCreditNoteBound(value, max, path) {
+  if (!Number.isSafeInteger(value) || value < 1 || value > max) {
+    throw new ArcaInputError(
+      `issueCreditNote requires input.${path} to be an integer from 1 through ${max}.`,
+      { code: "ARCA_INPUT_INVALID_VALUE", field: `input.${path}` }
+    );
+  }
+}
+function copyCreditNoteItems(items) {
+  if (!Array.isArray(items)) {
+    throw new ArcaInputError(
+      "issueCreditNote requires items to be a non-empty array of items.",
+      {
+        code: "ARCA_INPUT_INVALID_VALUE",
+        field: "input.items",
+        expected: "a non-empty array of items"
+      }
+    );
+  }
+  return items.map(
+    (item) => item === null || typeof item !== "object" ? item : { ...item }
+  );
+}
+
 // src/services/wsfe-identity.ts
 function matchWsfeVoucherIdentity(sent, number, found) {
   let missing;
@@ -581,7 +926,7 @@ function matchWsfeVoucherIdentity(sent, number, found) {
       (value) => normalizeArcaAmountToMinorUnits(value, field)
     ]);
   }
-  if (sent.concept === 2) {
+  if (sent.concept === 2 || sent.concept === 3) {
     for (const field of [
       "serviceStartDate",
       "serviceEndDate",
@@ -608,6 +953,17 @@ function matchWsfeVoucherIdentity(sent, number, found) {
     }
     missing ??= rates.reason;
   }
+  if (sent.associatedVouchers?.length) {
+    if (!found.associatedVouchers) {
+      missing ??= "associatedVouchers";
+    } else if (associationIdentity(sent.associatedVouchers) !== associationIdentity(found.associatedVouchers)) {
+      return {
+        matches: false,
+        evidence: "conflict",
+        reason: "associatedVouchers differ from the sent input"
+      };
+    }
+  }
   missing ??= incompleteAuthorization(sent, found);
   return missing ? {
     matches: false,
@@ -617,12 +973,11 @@ function matchWsfeVoucherIdentity(sent, number, found) {
 }
 function incompleteAuthorization(sent, found) {
   let missing;
-  if (sent.concept !== 1 && sent.concept !== 2) {
+  if (sent.concept !== 1 && sent.concept !== 2 && sent.concept !== 3) {
     missing ??= "unsupported concept";
   }
   for (const field of [
     "taxes",
-    "associatedVouchers",
     "associatedPeriod",
     "optionalFields",
     "buyers",
@@ -738,55 +1093,201 @@ function toVoucherSummary(found) {
   }
   return summary;
 }
+function associationIdentity(vouchers) {
+  return JSON.stringify(
+    vouchers.map(({ type, salesPoint, number }) => `${type}:${salesPoint}:${number}`).sort()
+  );
+}
 
 // src/services/vouchers.ts
-var SERIALIZATION_NOTICE = "Serialize calls per (representedTaxId, salesPoint, voucherType). The SDK does not coordinate writers; uncoordinated calls collide on 10016. Servers and queues must persist attempts and use wsfe.authorizeVoucherOutcome().";
-function createVouchersService(wsfe) {
+function createVouchersService(wsfe, context) {
   return {
+    issueCreditNote: async (input, options) => {
+      const result = await issueCreditNote(
+        wsfe,
+        input,
+        options === void 0 ? {} : options,
+        context
+      );
+      return result;
+    },
     issue: async (input, options) => {
       const result = await issueInvoice(
         wsfe,
         input,
-        options === void 0 ? {} : options
+        options === void 0 ? {} : options,
+        context
       );
       return result;
-    }
+    },
+    preview: (input, options) => previewInvoice(input, options === void 0 ? {} : options)
   };
 }
-async function issueInvoice(wsfe, input, options) {
-  validateOptions(options);
+function previewInvoice(input, options) {
+  assertIssueObject(options, "options");
+  assertIssueKeys(options, ["representedTaxId"], "options");
+  if (options.representedTaxId !== void 0) {
+    issueDocumentNumber(
+      options.representedTaxId,
+      "options.representedTaxId",
+      11,
+      11
+    );
+  }
   const { data, voucherClass, amounts } = deriveWsfeInvoice(input);
-  const auth = {
-    representedTaxId: options.representedTaxId,
-    forceRefresh: options.forceRefresh
+  return {
+    voucherClass,
+    voucherType: data.voucherType,
+    amounts,
+    request: data
   };
-  const includeRaw = options.include?.raw === true;
-  const includeExact = options.include?.exactInput === true;
+}
+async function issueInvoice(wsfe, input, options, context) {
+  validateOptions(options);
+  validateKeyStore(options, context);
+  const prepared = deriveWsfeInvoice(input);
+  return await runOperation(
+    wsfe,
+    "issue",
+    input,
+    () => Promise.resolve(prepared),
+    options,
+    context,
+    prepared.amounts
+  );
+}
+async function runOperation(wsfe, operation, input, prepare, options, context, replayAmounts) {
+  const store = context?.store;
+  if (options.idempotencyKey === void 0 || !store || !context) {
+    return runAuthorization(wsfe, await prepare(), options);
+  }
+  const key = attemptKey(
+    context.environment,
+    context.taxId,
+    options.idempotencyKey
+  );
+  const representedTaxId = options.representedTaxId === void 0 ? void 0 : String(options.representedTaxId);
+  const inputHash = canonicalHash({ input, representedTaxId });
+  const existing = await storeCall(() => store.get(key));
+  if (existing !== null) {
+    return replay(existing);
+  }
+  const prepared = await prepare();
+  const number = await nextNumber(wsfe, prepared.data, options);
+  const record = {
+    v: 1,
+    operation,
+    representedTaxId,
+    inputHash,
+    number,
+    salesPoint: prepared.data.salesPoint,
+    voucherType: prepared.data.voucherType,
+    sent: prepared.data,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  if (await storeCall(() => store.add(key, JSON.stringify(record)))) {
+    return runAuthorization(wsfe, prepared, options, number);
+  }
+  const winner = await storeCall(() => store.get(key));
+  if (winner === null) {
+    throw new ArcaConfigurationError(
+      "ARCA reservation disappeared after atomic creation lost."
+    );
+  }
+  return replay(winner);
+  function replay(json) {
+    const stored = readRecord(json);
+    if (stored.operation !== operation || stored.inputHash !== inputHash || stored.representedTaxId !== representedTaxId) {
+      throw new ArcaInputError(
+        "The idempotency key was already used with different input or operation.",
+        {
+          code: "ARCA_INPUT_IDEMPOTENCY_MISMATCH",
+          field: "options.idempotencyKey"
+        }
+      );
+    }
+    return runAuthorization(
+      wsfe,
+      {
+        ...preparedFromRecord(stored),
+        ...replayAmounts ? { amounts: replayAmounts } : {}
+      },
+      options,
+      stored.number,
+      true
+    );
+  }
+}
+function validateKeyStore(options, context) {
+  if (options.idempotencyKey === void 0) {
+    return;
+  }
+  if (typeof options.idempotencyKey !== "string" || options.idempotencyKey.length < 1 || options.idempotencyKey.length > 255) {
+    throw new ArcaInputError(
+      "idempotencyKey must contain 1 to 255 characters.",
+      { code: "ARCA_INPUT_INVALID_VALUE", field: "options.idempotencyKey" }
+    );
+  }
+  if (!context?.store) {
+    throw new ArcaConfigurationError(
+      'idempotencyKey requires a store. Add import { createPostgresStore } from "facturas"; and store: createPostgresStore({ query }) to createArcaClient().'
+    );
+  }
+}
+function readRecord(json) {
+  try {
+    const record = JSON.parse(json);
+    if (!record || record.v !== 1 || !["issue", "creditNote"].includes(record.operation) || typeof record.inputHash !== "string" || !record.sent || !Number.isSafeInteger(record.number) || record.number < 1 || record.number > 99999999 || record.sent.salesPoint !== record.salesPoint || record.sent.voucherType !== record.voucherType) {
+      throw new Error("Invalid reservation structure");
+    }
+    normalizeWsfeVoucherInput(record.sent);
+    return record;
+  } catch (cause) {
+    throw new ArcaConfigurationError(
+      "Invalid ARCA reservation record; preserve it for reconciliation.",
+      { cause }
+    );
+  }
+}
+function preparedFromRecord(record) {
+  const sentTotal = Number(
+    normalizeArcaAmountToMinorUnits(record.sent.totalAmount, "totalAmount")
+  );
+  return {
+    data: record.sent,
+    voucherClass: [1, 3].includes(record.voucherType) ? "A" : [6, 8].includes(record.voucherType) ? "B" : "C",
+    amounts: { computedTotal: sentTotal, sentTotal, vatAdjustment: 0 }
+  };
+}
+async function nextNumber(wsfe, data, options) {
   const number = await wsfe.getNextVoucherNumber({
-    ...auth,
+    representedTaxId: options.representedTaxId,
+    forceRefresh: options.forceRefresh,
     salesPoint: data.salesPoint,
     voucherType: data.voucherType
   });
   if (!Number.isSafeInteger(number) || number < 1 || number > 99999999) {
     throw new ArcaServiceError(
       "WSFE returned an invalid next voucher number.",
-      {
-        service: "wsfe",
-        operation: "FECompUltimoAutorizado"
-      }
+      { service: "wsfe", operation: "FECompUltimoAutorizado" }
     );
   }
+  return number;
+}
+async function runAuthorization(wsfe, { data, voucherClass, amounts }, options, reservedNumber, replay = false) {
+  const auth = {
+    representedTaxId: options.representedTaxId,
+    forceRefresh: options.forceRefresh
+  };
+  const includeRaw = options.include?.raw === true;
+  const includeExact = options.include?.exactInput === true;
+  const number = reservedNumber ?? await nextNumber(wsfe, data, options);
   const attempted = {
     salesPoint: data.salesPoint,
     voucherType: data.voucherType,
     number
   };
   const exact = includeExact ? { sent: data } : {};
-  const authorization = await wsfe.authorizeVoucherOutcome({
-    ...auth,
-    data,
-    voucherNumber: number
-  });
   const voucher = (cae, caeExpiry) => ({
     ...attempted,
     voucherClass,
@@ -795,6 +1296,29 @@ async function issueInvoice(wsfe, input, options) {
     caeExpiry,
     amounts
   });
+  const recovery = { wsfe, auth, data, attempted, includeRaw, exact, voucher };
+  if (replay) {
+    const attempt2 = replayEvidence();
+    let lookup;
+    try {
+      lookup = await wsfe.lookupVoucher({ ...auth, ...attempted });
+    } catch (error) {
+      return {
+        kind: "indeterminate",
+        attempted,
+        attempt: attempt2,
+        lookup: { kind: "failed", error: toArcaSafeErrorMetadata(error) }
+      };
+    }
+    if (lookup.kind === "found") {
+      return recoverInvoice({ ...recovery, attempt: attempt2, lookup });
+    }
+  }
+  const authorization = await wsfe.issue({
+    ...auth,
+    data,
+    voucherNumber: number
+  });
   if (authorization.kind === "authorized" && authorization.caeExpiry && authorization.voucherNumber === number) {
     return {
       kind: "authorized",
@@ -805,6 +1329,24 @@ async function issueInvoice(wsfe, input, options) {
     };
   }
   if (authorization.kind === "rejected") {
+    if (options.idempotencyKey !== void 0 && [...authorization.errors, ...authorization.observations].some(
+      (issue) => issue.code === "10016"
+    )) {
+      const recovered = await recoverInvoice({
+        ...recovery,
+        attempt: projectEvidence(
+          {
+            ...authorization,
+            kind: "indeterminate",
+            reason: "contradictory_response"
+          },
+          includeRaw
+        )
+      });
+      if (recovered.kind === "authorized" || recovered.kind === "conflict") {
+        return recovered;
+      }
+    }
     return {
       kind: "rejected",
       attempted,
@@ -839,11 +1381,12 @@ async function recoverInvoice({
   attempt,
   includeRaw,
   exact,
-  voucher
+  voucher,
+  lookup: suppliedLookup
 }) {
   let lookup;
   try {
-    lookup = await wsfe.lookupVoucher({ ...auth, ...attempted });
+    lookup = suppliedLookup ?? await wsfe.lookupVoucher({ ...auth, ...attempted });
   } catch (error) {
     return {
       kind: "indeterminate",
@@ -873,7 +1416,7 @@ async function recoverInvoice({
         attempted,
         attempt,
         found: { ...toVoucherSummary(lookup.voucher), ...raw },
-        reason: `${matched.reason}. ${SERIALIZATION_NOTICE}`
+        reason: `${matched.reason}. Configure a store and pass idempotencyKey for retries.`
       };
     }
     return {
@@ -947,7 +1490,7 @@ function validateOptions(options) {
   assertIssueObject(options, "options");
   assertIssueKeys(
     options,
-    ["representedTaxId", "forceRefresh", "include"],
+    ["representedTaxId", "forceRefresh", "include", "idempotencyKey"],
     "options"
   );
   if (options.representedTaxId !== void 0) {
@@ -980,6 +1523,55 @@ function validateOptions(options) {
     }
   }
 }
+function replayEvidence() {
+  return {
+    kind: "indeterminate",
+    service: "wsfe",
+    operation: "FECAESolicitar",
+    reason: "incomplete_response",
+    results: {},
+    errors: [],
+    observations: []
+  };
+}
+async function issueCreditNote(wsfe, input, options, context) {
+  validateOptions(options);
+  validateKeyStore(options, context);
+  const note = assertCreditNoteInput(input);
+  const target = note.for;
+  return await runOperation(
+    wsfe,
+    "creditNote",
+    note,
+    async () => {
+      const original = await wsfe.lookupVoucher({
+        representedTaxId: options.representedTaxId,
+        forceRefresh: options.forceRefresh,
+        salesPoint: target.salesPoint,
+        voucherType: target.voucherType,
+        number: target.number
+      });
+      if (original.kind === "not_found") {
+        throw new ArcaInputError(
+          "issueCreditNote failed: original voucher not found.",
+          {
+            code: "ARCA_INPUT_INVALID_VALUE",
+            field: "input.for"
+          }
+        );
+      }
+      if (original.voucher.salesPoint !== target.salesPoint || original.voucher.voucherType !== target.voucherType || original.voucher.voucherNumber !== target.number) {
+        throw new ArcaInputError(
+          "issueCreditNote failed: the original lookup coordinates do not match input.for.",
+          { code: "ARCA_INPUT_INVALID_VALUE", field: "input.for" }
+        );
+      }
+      return note.all === true ? deriveWsfeFullCreditNote(original.voucher, note) : deriveWsfePartialCreditNote(original.voucher, note);
+    },
+    options,
+    context
+  );
+}
 
 // src/internal/http.ts
 import https from "https";
@@ -1389,7 +1981,7 @@ function createSoapTransport(options) {
 }
 
 // src/wsaa/index.ts
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 import forge from "node-forge";
 
 // src/wsaa/session-store.ts
@@ -1623,7 +2215,7 @@ function buildWsaaSessionKey(config, service) {
   };
 }
 function getCertificateFingerprint(config) {
-  return createHash("sha256").update(config.certificatePem).digest("hex");
+  return createHash2("sha256").update(config.certificatePem).digest("hex");
 }
 function getCachedCredentials(cache, cacheKey) {
   const localCached = cache.get(cacheKey);
@@ -1814,10 +2406,40 @@ function parseLoginTicketResponse(xml) {
   };
 }
 
+// src/wsaa/store-adapter.ts
+function createWsaaStoreAdapter(store) {
+  const key = (value) => `arca:v1:wsaa:${serializeWsaaSessionKey(value)}`;
+  const remove = store.delete?.bind(store);
+  const lock = store.withLock?.bind(store);
+  return {
+    get: (value) => storeCall(async () => {
+      const json = await store.get(key(value));
+      if (json === null) {
+        return null;
+      }
+      const credentials = JSON.parse(json);
+      return credentials && typeof credentials.token === "string" && typeof credentials.sign === "string" && isWsaaCredentialValid(credentials) ? credentials : null;
+    }),
+    set: (value, credentials) => storeCall(() => store.set(key(value), JSON.stringify(credentials))),
+    ...remove ? {
+      delete: (value) => storeCall(() => remove(key(value)))
+    } : {},
+    ...lock ? {
+      withLock: (value, fn) => lock(key(value), fn)
+    } : {}
+  };
+}
+
 // src/client.ts
-function createArcaClient(config) {
-  assertArcaClientConfig(config);
-  const normalizedConfig = normalizeArcaClientConfig(config);
+function createArcaClient(config = {}) {
+  const discovered = discoverArcaClientConfig(config);
+  assertArcaClientConfig(discovered);
+  const normalizedConfig = normalizeArcaClientConfig(discovered);
+  if (normalizedConfig.store && !normalizedConfig.wsaaSessionStore) {
+    normalizedConfig.wsaaSessionStore = createWsaaStoreAdapter(
+      normalizedConfig.store
+    );
+  }
   const logger = createArcaLogger(normalizedConfig.logger);
   const auth = createWsaaAuthModule({ config: normalizedConfig, logger });
   const soap = createSoapTransport({ config: normalizedConfig, logger });
@@ -1829,14 +2451,177 @@ function createArcaClient(config) {
     retryDelay: normalizedConfig.retryDelay
   });
   const wsfe = createWsfeService({ config: normalizedConfig, auth, soap });
+  const vouchers = createVouchersService(wsfe, normalizedConfig);
   return {
     config: publicConfig,
+    issue: vouchers.issue,
+    preview: vouchers.preview,
+    issueCreditNote: vouchers.issueCreditNote,
     wsfe,
-    vouchers: createVouchersService(wsfe),
     wsmtxca: createWsmtxcaService({ config: normalizedConfig, auth, soap }),
     padron: createPadronService({ config: normalizedConfig, auth, soap })
   };
 }
+
+// src/store/file.ts
+import { createHash as createHash3, randomUUID } from "crypto";
+import { mkdir, readFile, rename, unlink, writeFile } from "fs/promises";
+import { join } from "path";
+function createFileStore(directory) {
+  const path = (key) => join(directory, createHash3("sha256").update(key).digest("hex"));
+  const ensure = () => mkdir(directory, { recursive: true, mode: 448 });
+  return {
+    get: (key) => storeCall(async () => {
+      try {
+        return await readFile(path(key), "utf8");
+      } catch (error) {
+        if (error.code === "ENOENT") {
+          return null;
+        }
+        throw error;
+      }
+    }),
+    set: (key, value) => storeCall(async () => {
+      await ensure();
+      const temporary = `${path(key)}.${randomUUID()}.tmp`;
+      try {
+        await writeFile(temporary, value, { mode: 384, flag: "wx" });
+        await rename(temporary, path(key));
+      } finally {
+        await unlink(temporary).catch(() => void 0);
+      }
+    }),
+    add: (key, value) => storeCall(async () => {
+      await ensure();
+      try {
+        await writeFile(path(key), value, { flag: "wx", mode: 384 });
+        return true;
+      } catch (error) {
+        if (error.code === "EEXIST") {
+          return false;
+        }
+        throw error;
+      }
+    }),
+    delete: (key) => storeCall(async () => {
+      try {
+        await unlink(path(key));
+      } catch (error) {
+        if (error.code !== "ENOENT") {
+          throw error;
+        }
+      }
+    })
+  };
+}
+
+// src/store/memory.ts
+function createMemoryStore() {
+  const values = /* @__PURE__ */ new Map();
+  const locks = /* @__PURE__ */ new Map();
+  return {
+    get: (key) => Promise.resolve(values.get(key) ?? null),
+    set(key, value) {
+      values.set(key, value);
+      return Promise.resolve();
+    },
+    add(key, value) {
+      if (values.has(key)) {
+        return Promise.resolve(false);
+      }
+      values.set(key, value);
+      return Promise.resolve(true);
+    },
+    delete(key) {
+      values.delete(key);
+      return Promise.resolve();
+    },
+    async withLock(key, fn) {
+      const previous = locks.get(key) ?? Promise.resolve();
+      let release = () => void 0;
+      const current = new Promise((resolve) => {
+        release = resolve;
+      });
+      const queued = previous.catch(() => void 0).then(() => current);
+      locks.set(key, queued);
+      await previous.catch(() => void 0);
+      try {
+        return await fn();
+      } finally {
+        release();
+        if (locks.get(key) === queued) {
+          locks.delete(key);
+        }
+      }
+    }
+  };
+}
+
+// src/store/postgres.ts
+function createPostgresStore({
+  query,
+  table = "arca_store"
+}) {
+  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(table)) {
+    throw new ArcaConfigurationError("Invalid ARCA store table identifier.");
+  }
+  const name = `"${table}"`;
+  const run = (text, params) => storeCall(async () => {
+    const result = await query(text, params);
+    return Array.isArray(result) ? result : result.rows;
+  });
+  return {
+    async get(key) {
+      return (await run(`SELECT value FROM ${name} WHERE key = $1`, [key]))[0]?.value ?? null;
+    },
+    async set(key, value) {
+      await run(
+        `INSERT INTO ${name} (key, value) VALUES ($1, $2) ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value, updated_at = now()`,
+        [key, value]
+      );
+    },
+    async add(key, value) {
+      return (await run(
+        `INSERT INTO ${name} (key, value) VALUES ($1, $2) ON CONFLICT DO NOTHING RETURNING key`,
+        [key, value]
+      )).length > 0;
+    },
+    async delete(key) {
+      await run(`DELETE FROM ${name} WHERE key = $1`, [key]);
+    }
+  };
+}
+
+// src/store/redis.ts
+function createRedisStore(client, options = {}) {
+  const flavor = options.flavor ?? (typeof client.call === "function" ? "ioredis" : "upstash");
+  if (flavor === "ioredis" && !client.call) {
+    throw new ArcaConfigurationError(
+      "ARCA Redis ioredis flavor requires client.call."
+    );
+  }
+  const upstashSet = client.set;
+  return {
+    get: (key) => storeCall(async () => {
+      const value = await client.get(key);
+      if (value === null) {
+        return null;
+      }
+      return typeof value === "string" ? value : JSON.stringify(value);
+    }),
+    set: (key, value) => storeCall(async () => {
+      await client.set(key, value);
+    }),
+    add: (key, value) => storeCall(
+      async () => (flavor === "ioredis" ? await client.call?.("SET", key, value, "NX") : await upstashSet.call(client, key, value, { nx: true })) === "OK"
+    ),
+    ...client.del ? {
+      delete: (key) => storeCall(async () => {
+        await client.del?.(key);
+      })
+    } : {}
+  };
+}
 export {
   ARCA_ENVIRONMENTS,
   ARCA_ENV_VARIABLES,
@@ -1857,8 +2642,12 @@ export {
   buildFacturaC,
   createArcaClient,
   createArcaClientConfigFromEnv,
+  createFileStore,
+  createMemoryStore,
   createMemoryWsaaSessionStore,
   createPadronService,
+  createPostgresStore,
+  createRedisStore,
   createWsfeService,
   createWsmtxcaService,
   isArcaAuthenticationError,