facturas 0.8.0 → 0.9.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-RCM4NAAG.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-XNBD5NVL.mjs";
+import "./chunk-4QVFXT35.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,
@@ -493,14 +548,11 @@ function assertIssueKeys(value, keys, prefix) {
   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 issue().`, {
+        code: "ARCA_INPUT_RESERVED_FIELD",
+        field,
+        expected: "a supported facade field; use the exact API for other fiscal fields"
+      });
     }
   }
 }
@@ -512,6 +564,129 @@ function invalid(field, expected) {
   });
 }
 
+// src/services/wsfe-cancel.ts
+var NOTES = {
+  1: { voucherType: 3, voucherClass: "A" },
+  6: { voucherType: 8, voucherClass: "B" },
+  11: { voucherType: 13, voucherClass: "C" }
+};
+function invalid2(reason) {
+  throw new ArcaInputError(
+    `Cannot cancel: ${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 deriveWsfeCancellation(original, date, now = /* @__PURE__ */ new Date()) {
+  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(
+    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 data = {
+    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,
+    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 })) },
+    associatedVouchers: [
+      {
+        type: required(original.voucherType, "voucherType"),
+        salesPoint: required(original.salesPoint, "salesPoint"),
+        number: original.voucherNumber,
+        voucherDate: originalDate
+      }
+    ]
+  };
+  copyServiceDates(original, data);
+  normalizeWsfeVoucherInput(data);
+  const total = Number(
+    normalizeArcaAmountToMinorUnits(data.totalAmount, "totalAmount")
+  );
+  return {
+    data,
+    voucherClass: note.voucherClass,
+    amounts: { computedTotal: total, sentTotal: total, vatAdjustment: 0 }
+  };
+}
+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, data) {
+  if (data.concept !== 2 && data.concept !== 3) {
+    return;
+  }
+  data.serviceStartDate = required(
+    original.serviceStartDate,
+    "serviceStartDate"
+  );
+  data.serviceEndDate = required(
+    original.serviceEndDate,
+    "serviceEndDate"
+  );
+  const due = normalizeWsfeDateInput(
+    required(original.paymentDueDate, "paymentDueDate"),
+    "original.paymentDueDate"
+  );
+  data.paymentDueDate = due < data.voucherDate ? data.voucherDate : due;
+}
+
 // src/services/wsfe-identity.ts
 function matchWsfeVoucherIdentity(sent, number, found) {
   let missing;
@@ -581,7 +756,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 +783,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 +803,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 +923,176 @@ 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 {
+    cancel: async (target, options) => {
+      const result = await cancelInvoice(wsfe, target, 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;
     }
   };
 }
-async function issueInvoice(wsfe, input, options) {
+async function issueInvoice(wsfe, input, options, context) {
   validateOptions(options);
-  const { data, voucherClass, amounts } = deriveWsfeInvoice(input);
-  const auth = {
-    representedTaxId: options.representedTaxId,
-    forceRefresh: options.forceRefresh
+  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()
   };
-  const includeRaw = options.include?.raw === true;
-  const includeExact = options.include?.exactInput === true;
+  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", "cancel"].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 +1101,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 +1134,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 +1186,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 +1221,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 +1295,7 @@ function validateOptions(options) {
   assertIssueObject(options, "options");
   assertIssueKeys(
     options,
-    ["representedTaxId", "forceRefresh", "include"],
+    ["representedTaxId", "forceRefresh", "include", "idempotencyKey"],
     "options"
   );
   if (options.representedTaxId !== void 0) {
@@ -980,6 +1328,73 @@ function validateOptions(options) {
     }
   }
 }
+function replayEvidence() {
+  return {
+    kind: "indeterminate",
+    service: "wsfe",
+    operation: "FECAESolicitar",
+    reason: "incomplete_response",
+    results: {},
+    errors: [],
+    observations: []
+  };
+}
+async function cancelInvoice(wsfe, target, options, context) {
+  assertIssueObject(options, "options");
+  const { date, ...issueOptions } = options;
+  validateOptions(issueOptions);
+  validateKeyStore(issueOptions, context);
+  assertIssueObject(target, "target");
+  for (const [field, max] of [
+    ["salesPoint", 99999],
+    ["voucherType", 999],
+    ["number", 99999999]
+  ]) {
+    if (!Number.isSafeInteger(target[field]) || target[field] < 1 || target[field] > max) {
+      throw new ArcaInputError(`Invalid cancel target ${field}.`, {
+        code: "ARCA_INPUT_INVALID_VALUE",
+        field
+      });
+    }
+  }
+  if (![1, 6, 11].includes(target.voucherType)) {
+    throw new ArcaInputError(
+      "cancel requires an invoice of type 1, 6 or 11; use wsfe.issue() for exact control.",
+      { code: "ARCA_INPUT_INVALID_VALUE" }
+    );
+  }
+  if (date !== void 0) {
+    normalizeWsfeDateInput(date, "date");
+  }
+  return await runOperation(
+    wsfe,
+    "cancel",
+    { target, date },
+    async () => {
+      const original = await wsfe.lookupVoucher({
+        representedTaxId: issueOptions.representedTaxId,
+        forceRefresh: issueOptions.forceRefresh,
+        salesPoint: target.salesPoint,
+        voucherType: target.voucherType,
+        number: target.number
+      });
+      if (original.kind === "not_found") {
+        throw new ArcaInputError("original voucher not found", {
+          code: "ARCA_INPUT_INVALID_VALUE"
+        });
+      }
+      if (original.voucher.salesPoint !== target.salesPoint || original.voucher.voucherType !== target.voucherType || original.voucher.voucherNumber !== target.number) {
+        throw new ArcaInputError(
+          "Original lookup coordinates do not match the cancel target.",
+          { code: "ARCA_INPUT_INVALID_VALUE" }
+        );
+      }
+      return deriveWsfeCancellation(original.voucher, date);
+    },
+    issueOptions,
+    context
+  );
+}
 
 // src/internal/http.ts
 import https from "https";
@@ -1389,7 +1804,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 +2038,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 +2229,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 +2274,176 @@ function createArcaClient(config) {
     retryDelay: normalizedConfig.retryDelay
   });
   const wsfe = createWsfeService({ config: normalizedConfig, auth, soap });
+  const vouchers = createVouchersService(wsfe, normalizedConfig);
   return {
     config: publicConfig,
+    issue: vouchers.issue,
+    cancel: vouchers.cancel,
     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 +2464,12 @@ export {
   buildFacturaC,
   createArcaClient,
   createArcaClientConfigFromEnv,
+  createFileStore,
+  createMemoryStore,
   createMemoryWsaaSessionStore,
   createPadronService,
+  createPostgresStore,
+  createRedisStore,
   createWsfeService,
   createWsmtxcaService,
   isArcaAuthenticationError,