@getpeppr/cli 0.9.0 → 0.10.0

package/dist/index.js

@@ -623,7 +623,10 @@ var ICD_CODES = /* @__PURE__ */ new Set([
   "0242",
   "0243",
   "0244",
-  "0245"
+  "0245",
+  "0246",
+  "0247",
+  "0248"
 ]);
 var ISO6523_ICD_CODES = Object.freeze({
   has: (v) => ICD_CODES.has(v),
@@ -717,10 +720,41 @@ function formatVatRate(vatRate, field) {
   }
   return String(vatRate);
 }
-function formatBaseQuantity(baseQuantity, field) {
+function assertValidBaseQuantity(baseQuantity, field) {
   if (typeof baseQuantity !== "number" || !Number.isFinite(baseQuantity) || baseQuantity <= 0) {
     throw new UblBuilderInputError("baseQuantity must be a finite number greater than zero.", field, "PEPPOL-EN16931-R121");
   }
+}
+var ADJUSTMENT_CONTRACT_RULE = "GETPEPPR-ALLOWANCE-CHARGE-AMOUNT";
+var ADJUSTMENT_AMOUNT_MESSAGE = "Allowance and charge amounts must be finite numbers greater than or equal to zero. An allowance reduces the amount and a charge increases it; encode the direction in the field, never in the sign.";
+var DERIVED_AMOUNT_CONTRACT_RULE = "GETPEPPR-DERIVED-AMOUNT";
+var NON_FINITE_DERIVED_AMOUNT_MESSAGE = "Derived amount is not finite (overflow). Reduce quantities, prices or adjustment amounts so every total stays representable.";
+function survivesCents(value) {
+  return Number.isFinite(value) && Number.isFinite(value * 100);
+}
+function assertValidAdjustmentAmounts(items, field) {
+  if (items === void 0)
+    return;
+  if (!Array.isArray(items)) {
+    throw new UblBuilderInputError(`${field} must be an array \u2014 omit the field instead of sending ${items === null ? "null" : typeof items}`, field, ADJUSTMENT_CONTRACT_RULE);
+  }
+  for (const [i, item] of items.entries()) {
+    const amount = item?.amount;
+    if (item === null || typeof item !== "object" || typeof amount !== "number" || !Number.isFinite(amount) || amount < 0) {
+      throw new UblBuilderInputError(ADJUSTMENT_AMOUNT_MESSAGE, `${field}[${i}].amount`, ADJUSTMENT_CONTRACT_RULE);
+    }
+  }
+}
+function assertDocumentAdjustmentAmounts(input) {
+  for (const [i, line] of input.lines.entries()) {
+    assertValidAdjustmentAmounts(line.allowances, `lines[${i}].allowances`);
+    assertValidAdjustmentAmounts(line.charges, `lines[${i}].charges`);
+  }
+  assertValidAdjustmentAmounts(input.allowances, "allowances");
+  assertValidAdjustmentAmounts(input.charges, "charges");
+}
+function formatBaseQuantity(baseQuantity, field) {
+  assertValidBaseQuantity(baseQuantity, field);
   const numeric = String(baseQuantity);
   const exponentMarker = numeric.search(/[eE]/);
   if (exponentMarker === -1)
@@ -763,8 +797,8 @@ function buildPartyXml(party, role) {
       <cac:Party>
         <cbc:EndpointID schemeID="${escapeXml(endpointScheme)}">${escapeXml(endpointId)}</cbc:EndpointID>
         ${// ⛔ DEUX listes, pas une. `BR-CL-25` juge l'EndpointID ci-dessus contre la
-  // liste EAS (101 valeurs, jusqu'à `9959`) ; `BR-CL-10` juge CE champ-ci
-  // contre la liste ISO 6523 ICD (240 valeurs, `0002`–`0245`). `9932` (GB),
+  // liste EAS (104 valeurs, jusqu'à `9959`) ; `BR-CL-10` juge CE champ-ci
+  // contre la liste ISO 6523 ICD (243 valeurs, `0002`–`0248`). `9932` (GB),
   // `9935` (IE) et `9930` (DE) sont légaux là-haut et FATALS ici.
   //
   // Le champ (BT-29) est optionnel : l'omettre est la seule écriture
@@ -952,14 +986,21 @@ function buildLineAllowanceChargeXml(reason, amount, isCharge, currency) {
         <cbc:Amount currencyID="${escapeXml(currency)}">${formatAmount(amount)}</cbc:Amount>
       </cac:AllowanceCharge>`;
 }
-function calculateLineExtensionAmount(line) {
-  const base = line.quantity * line.unitPrice;
+function calculateLineExtensionAmount(line, lineIndex) {
+  if (line.baseQuantity !== void 0) {
+    assertValidBaseQuantity(line.baseQuantity, `lines[${lineIndex}].baseQuantity`);
+  }
+  const base = line.quantity * line.unitPrice / (line.baseQuantity ?? 1);
   const lineAllowances = (line.allowances ?? []).reduce((sum, a) => sum + a.amount, 0);
   const lineCharges = (line.charges ?? []).reduce((sum, c) => sum + c.amount, 0);
-  return base - lineAllowances + lineCharges;
+  const total = base - lineAllowances + lineCharges;
+  if (!survivesCents(total)) {
+    throw new UblBuilderInputError(NON_FINITE_DERIVED_AMOUNT_MESSAGE, `lines[${lineIndex}]`, DERIVED_AMOUNT_CONTRACT_RULE);
+  }
+  return total;
 }
 function buildDocumentLineXml(line, index, currency, lineTag, qtyTag) {
-  const lineTotal = calculateLineExtensionAmount(line);
+  const lineTotal = calculateLineExtensionAmount(line, index);
   const unit = resolveUnitCode(line.unit ?? DEFAULT_UNIT);
   const vatCategory = line.vatCategory ?? "S";
   const lineAllowancesXml = (line.allowances ?? []).map((a) => buildLineAllowanceChargeXml(a.reason, a.amount, false, currency)).join("");
@@ -1035,7 +1076,7 @@ function calculateTaxSubtotals(lines, allowances, charges, options = {}) {
     }
   }
   for (const [index, line] of lines.entries()) {
-    addToGroup(line.vatCategory ?? "S", line.vatRate, calculateLineExtensionAmount(line), line.taxExemptReason, `lines[${index}]`);
+    addToGroup(line.vatCategory ?? "S", line.vatRate, calculateLineExtensionAmount(line, index), line.taxExemptReason, `lines[${index}]`);
   }
   for (const [index, a] of (allowances ?? []).entries()) {
     addToGroup(a.vatCategory ?? "S", a.vatRate, -a.amount, a.taxExemptReason, `allowances[${index}]`);
@@ -1050,19 +1091,29 @@ function calculateTaxSubtotals(lines, allowances, charges, options = {}) {
       }
     }
   }
-  return Array.from(groups.values()).map((subtotal) => ({
-    ...subtotal,
-    taxAmount: round2(subtotal.taxableAmount * (subtotal.vatRate / 100))
-  }));
+  return Array.from(groups.values()).map((subtotal) => {
+    const taxableAmount = round2(subtotal.taxableAmount);
+    const taxAmount = round2(taxableAmount * (subtotal.vatRate / 100));
+    if (!survivesCents(taxableAmount) || !survivesCents(taxAmount)) {
+      throw new UblBuilderInputError(NON_FINITE_DERIVED_AMOUNT_MESSAGE, "totals", DERIVED_AMOUNT_CONTRACT_RULE);
+    }
+    return { ...subtotal, taxableAmount, taxAmount };
+  });
 }
 function calculateDocumentTotals(lines, allowances, charges, options = {}) {
   const taxSubtotals = calculateTaxSubtotals(lines, allowances, charges, options);
-  const lineExtensionAmount = lines.reduce((sum, line) => sum + calculateLineExtensionAmount(line), 0);
+  const lineExtensionAmount = lines.reduce((sum, line, index) => sum + calculateLineExtensionAmount(line, index), 0);
   const allowanceTotalAmount = (allowances ?? []).reduce((sum, a) => sum + a.amount, 0);
   const chargeTotalAmount = (charges ?? []).reduce((sum, c) => sum + c.amount, 0);
   const taxExclusiveAmount = round2(lineExtensionAmount - allowanceTotalAmount + chargeTotalAmount);
+  if (!survivesCents(allowanceTotalAmount) || !survivesCents(chargeTotalAmount) || !survivesCents(taxExclusiveAmount)) {
+    throw new UblBuilderInputError(NON_FINITE_DERIVED_AMOUNT_MESSAGE, "totals", DERIVED_AMOUNT_CONTRACT_RULE);
+  }
   const totalTax = round2(taxSubtotals.reduce((sum, st) => sum + st.taxAmount, 0));
   const taxInclusiveAmount = round2(taxExclusiveAmount + totalTax);
+  if (!survivesCents(totalTax) || !survivesCents(taxInclusiveAmount)) {
+    throw new UblBuilderInputError(NON_FINITE_DERIVED_AMOUNT_MESSAGE, "totals", DERIVED_AMOUNT_CONTRACT_RULE);
+  }
   return {
     lineExtensionAmount,
     allowanceTotalAmount,
@@ -1147,6 +1198,7 @@ function buildOrderReferenceXml(orderReference, salesOrderReference) {
   return parts.join("");
 }
 function buildInvoiceXml(input) {
+  assertDocumentAdjustmentAmounts(input);
   const currency = input.currency ?? "EUR";
   const date = formatDate(input.date);
   const dueDate = input.dueDate ? formatDate(input.dueDate) : void 0;
@@ -1194,6 +1246,7 @@ function buildInvoiceXml(input) {
 </Invoice>`;
 }
 function buildCreditNoteXml(input) {
+  assertDocumentAdjustmentAmounts(input);
   const currency = input.currency ?? "EUR";
   const date = formatDate(input.date);
   const dueDate = input.dueDate ? formatDate(input.dueDate) : void 0;
@@ -1437,8 +1490,13 @@ var CURRENCIES = /* @__PURE__ */ new Map([
   ["CZK", { code: "CZK", name: "Czech Koruna", minorUnits: 2 }],
   ["HUF", { code: "HUF", name: "Hungarian Forint", minorUnits: 2 }],
   ["RON", { code: "RON", name: "Romanian Leu", minorUnits: 2 }],
-  ["BGN", { code: "BGN", name: "Bulgarian Lev", minorUnits: 2 }],
-  ["HRK", { code: "HRK", name: "Croatian Kuna", minorUnits: 2 }],
+  // ⛔ BGN and HRK are GONE (GPR-1205). Neither is in BR-CL-04/BR-CL-05 of the
+  // graved 3.0.21 rulebooks — Bulgaria and Croatia both joined the euro — so
+  // accepting them here would wave through a document the network refuses, which
+  // is the exact failure this release closes. XCG replaces ANG (never carried
+  // here) for the Dutch Caribbean. `currency-codes-network-parity.test.ts` reds
+  // if this table ever readmits a code the rulebooks reject.
+  ["XCG", { code: "XCG", name: "Caribbean Guilder", minorUnits: 2 }],
   ["ISK", { code: "ISK", name: "Icelandic Krona", minorUnits: 0 }],
   ["TRY", { code: "TRY", name: "Turkish Lira", minorUnits: 2 }],
   ["JPY", { code: "JPY", name: "Japanese Yen", minorUnits: 0 }],
@@ -1564,6 +1622,11 @@ function assertString(value, fieldPath, errors) {
   return true;
 }
 var ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+var ALLOWANCE_CHARGE_CONTRACT_RULE = "GETPEPPR-ALLOWANCE-CHARGE-AMOUNT";
+var DERIVED_AMOUNT_CONTRACT_RULE2 = "GETPEPPR-DERIVED-AMOUNT";
+function survivesCents2(value) {
+  return Number.isFinite(value) && Number.isFinite(value * 100);
+}
 function validateParty(party, path) {
   const errors = [];
   if (party.name === void 0 || party.name === null || party.name === "") {
@@ -1637,6 +1700,31 @@ function validateLine(line, index, isCreditNote = false) {
   } else if (line.vatRate < 0 || line.vatRate > 100) {
     errors.push(error(`${path}.vatRate`, `VAT rate must be between 0 and 100, got ${line.vatRate}`, void 0, "Use 0 for zero-rated, 21 for standard Belgian VAT, etc."));
   }
+  const adjustmentItems = {
+    allowances: Array.isArray(line.allowances) ? line.allowances : [],
+    charges: Array.isArray(line.charges) ? line.charges : []
+  };
+  for (const kind of ["allowances", "charges"]) {
+    const items = line[kind];
+    if (items === void 0)
+      continue;
+    if (!Array.isArray(items)) {
+      errors.push(error(`${path}.${kind}`, `${kind} must be an array \u2014 omit the field instead of sending ${items === null ? "null" : typeof items}`, ALLOWANCE_CHARGE_CONTRACT_RULE));
+      continue;
+    }
+    for (const [i, item] of items.entries()) {
+      const amount = item?.amount;
+      if (typeof amount !== "number" || !Number.isFinite(amount) || amount < 0) {
+        errors.push(error(`${path}.${kind}[${i}].amount`, `Allowance and charge amounts must be zero or positive finite numbers, got ${String(amount)}`, ALLOWANCE_CHARGE_CONTRACT_RULE, "An allowance reduces the amount and a charge increases it \u2014 encode the direction in the field, never in the sign."));
+      }
+    }
+  }
+  const bq = typeof line.baseQuantity === "number" && line.baseQuantity > 0 ? line.baseQuantity : 1;
+  const derivedNet = (line.quantity ?? 0) * (line.unitPrice ?? 0) / bq - adjustmentItems.allowances.reduce((sum, a) => sum + (a?.amount ?? 0), 0) + adjustmentItems.charges.reduce((sum, c) => sum + (c?.amount ?? 0), 0);
+  const derivedVat = derivedNet * ((typeof line.vatRate === "number" ? line.vatRate : 0) / 100);
+  if (!survivesCents2(derivedNet) || !survivesCents2(derivedVat)) {
+    errors.push(error(path, "Derived amount is not finite (overflow). Reduce quantities, prices or adjustment amounts so every total stays representable.", DERIVED_AMOUNT_CONTRACT_RULE2));
+  }
   return errors;
 }
 function validateInvoice(input) {
@@ -1713,15 +1801,52 @@ function validateInvoice(input) {
     if (value === void 0)
       continue;
     if (!Array.isArray(value)) {
-      errors.push(error(field, `${field} must be an array`, void 0));
+      errors.push(error(field, `${field} must be an array \u2014 omit the field instead of sending ${value === null ? "null" : typeof value}`, ALLOWANCE_CHARGE_CONTRACT_RULE));
       continue;
     }
     for (const [index, item] of value.entries()) {
       if (item === null || typeof item !== "object") {
         errors.push(error(`${field}[${index}]`, `${field}[${index}] must be an object`, void 0));
+        continue;
+      }
+      const amount = item.amount;
+      if (typeof amount !== "number" || !Number.isFinite(amount) || amount < 0) {
+        errors.push(error(`${field}[${index}].amount`, `Allowance and charge amounts must be zero or positive finite numbers, got ${String(amount)}`, ALLOWANCE_CHARGE_CONTRACT_RULE, "An allowance reduces the amount and a charge increases it \u2014 encode the direction in the field, never in the sign."));
       }
     }
   }
+  if (Array.isArray(input.lines)) {
+    const itemsOf = (value) => Array.isArray(value) ? value : [];
+    const amountOf = (item) => typeof item?.amount === "number" ? item.amount : 0;
+    const lineNets = input.lines.reduce((sum, line) => {
+      if (typeof line !== "object" || line === null)
+        return sum;
+      const lbq = typeof line.baseQuantity === "number" && line.baseQuantity > 0 ? line.baseQuantity : 1;
+      return sum + (line.quantity ?? 0) * (line.unitPrice ?? 0) / lbq - itemsOf(line.allowances).reduce((s, a) => s + amountOf(a), 0) + itemsOf(line.charges).reduce((s, c) => s + amountOf(c), 0);
+    }, 0);
+    const allowanceTotal = itemsOf(input.allowances).reduce((s, a) => s + amountOf(a), 0);
+    const chargeTotal = itemsOf(input.charges).reduce((s, c) => s + amountOf(c), 0);
+    const vatOf = (items, sign) => {
+      if (!Array.isArray(items))
+        return 0;
+      return items.reduce((s, it) => {
+        const rec = it;
+        const amount = typeof rec?.amount === "number" ? rec.amount : 0;
+        const rate = typeof rec?.vatRate === "number" ? rec.vatRate : 0;
+        return s + sign * amount * (rate / 100);
+      }, 0);
+    };
+    const docVat = vatOf(input.allowances, -1) + vatOf(input.charges, 1) + input.lines.reduce((s, line) => {
+      if (typeof line !== "object" || line === null)
+        return s;
+      const lbq = typeof line.baseQuantity === "number" && line.baseQuantity > 0 ? line.baseQuantity : 1;
+      const net = (line.quantity ?? 0) * (line.unitPrice ?? 0) / lbq;
+      return s + net * ((typeof line.vatRate === "number" ? line.vatRate : 0) / 100);
+    }, 0);
+    if (!survivesCents2(lineNets - allowanceTotal + chargeTotal) || !survivesCents2(docVat)) {
+      errors.push(error("totals", "Derived amount is not finite (overflow). Reduce quantities, prices or adjustment amounts so every total stays representable.", DERIVED_AMOUNT_CONTRACT_RULE2));
+    }
+  }
   if (input.date) {
     if (!ISO_DATE_RE.test(input.date)) {
       errors.push(error("date", `Invalid date format: "${input.date}"`, void 0, "Use ISO 8601: YYYY-MM-DD"));
@@ -2331,18 +2456,171 @@ function statusFamily(status) {
 var TERMINAL_FAILURE_STATUSES = STATUS_PRECEDENCE.filter((e) => e.family === "terminal-failure").map((e) => e.status);
 
 // ../sdk/dist/version.js
-var SDK_VERSION = "4.8.0";
+var SDK_VERSION = "5.0.0";
+
+// ../sdk/dist/core/api-result.js
+var API_RESULT_HEADER_NAMES = {
+  requestId: "Getpeppr-Request-Id",
+  resultCode: "Getpeppr-Result-Code",
+  resultMessage: "Getpeppr-Result-Message",
+  retryable: "Getpeppr-Retryable",
+  remediation: "Getpeppr-Remediation",
+  docs: "Getpeppr-Result-Docs"
+};
+var CONTROL_CHARACTERS = /[\u0000-\u001F\u007F-\u009F]/g;
+function stripControls(value) {
+  return value.replace(CONTROL_CHARACTERS, " ");
+}
+function safeDocsUrl(value) {
+  if (typeof value !== "string")
+    return null;
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return null;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+    return null;
+  return parsed.href;
+}
+var MAX_BYTES = {
+  requestId: 256,
+  code: 256,
+  message: 1024,
+  remediation: 64,
+  docs: 2048,
+  // ⚠️ A COST bound, not a correctness one — and the distinction is measured.
+  // When this field was still trimmed, a huge padded value could normalise into
+  // `true`, so the ceiling changed the verdict. Now that the token is compared
+  // verbatim, no string can be both over-long and equal to "true"/"false": a
+  // mutation removing this ceiling SURVIVES the suite, and correctly so. It
+  // stays to bound the whitespace/control scan on an absurd value, and it is
+  // the one entry here with no test — deliberately, since any assertion would
+  // be satisfied by both answers.
+  retryable: 32
+};
+var STRICT_HTTPS_URL = /^https:\/\/[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?(?::\d{1,5})?(?:\/[^\s\\]*)?$/i;
+var TEXT_ENCODER = new TextEncoder();
+function withinBudget(raw, maxBytes) {
+  if (raw === null)
+    return void 0;
+  return TEXT_ENCODER.encode(raw).length > maxBytes ? void 0 : raw;
+}
+function readSentence(raw, maxBytes) {
+  const bounded = withinBudget(raw, maxBytes);
+  if (bounded === void 0)
+    return void 0;
+  const cleaned = stripControls(bounded).trim();
+  return cleaned === "" ? void 0 : cleaned;
+}
+function readMachineToken(raw, maxBytes) {
+  const bounded = withinBudget(raw, maxBytes);
+  if (bounded === void 0)
+    return void 0;
+  if (bounded === "")
+    return void 0;
+  if (new RegExp(CONTROL_CHARACTERS.source).test(bounded))
+    return void 0;
+  if (/\s/u.test(bounded))
+    return void 0;
+  return bounded;
+}
+function readBoolean(raw) {
+  const token = readMachineToken(raw, MAX_BYTES.retryable);
+  if (token === void 0)
+    return void 0;
+  if (token === "true")
+    return true;
+  if (token === "false")
+    return false;
+  return void 0;
+}
+function readDocsUrl(raw) {
+  const token = readMachineToken(raw, MAX_BYTES.docs);
+  if (token === void 0)
+    return void 0;
+  if (!STRICT_HTTPS_URL.test(token))
+    return void 0;
+  const parsed = safeDocsUrl(token);
+  if (parsed === null)
+    return void 0;
+  const url = new URL(parsed);
+  if (url.protocol !== "https:")
+    return void 0;
+  if (url.username !== "" || url.password !== "")
+    return void 0;
+  return url.href;
+}
+function parseApiResultHeaders(headers) {
+  const requestId = readMachineToken(headers.get(API_RESULT_HEADER_NAMES.requestId), MAX_BYTES.requestId);
+  const code = readMachineToken(headers.get(API_RESULT_HEADER_NAMES.resultCode), MAX_BYTES.code);
+  const message = readSentence(headers.get(API_RESULT_HEADER_NAMES.resultMessage), MAX_BYTES.message);
+  const retryable = readBoolean(headers.get(API_RESULT_HEADER_NAMES.retryable));
+  const remediation = readMachineToken(headers.get(API_RESULT_HEADER_NAMES.remediation), MAX_BYTES.remediation);
+  const docs = readDocsUrl(headers.get(API_RESULT_HEADER_NAMES.docs));
+  const result = {};
+  if (requestId !== void 0)
+    result.requestId = requestId;
+  if (code !== void 0)
+    result.code = code;
+  if (message !== void 0)
+    result.message = message;
+  if (retryable !== void 0)
+    result.retryable = retryable;
+  if (remediation !== void 0)
+    result.remediation = remediation;
+  if (docs !== void 0)
+    result.docs = docs;
+  return Object.keys(result).length === 0 ? void 0 : result;
+}
 
 // ../sdk/dist/core/client.js
-function findHeaderCaseInsensitive(headers, name) {
+function normalizeHeaderValue(value) {
+  return value.replace(/^[\t\n\r ]+|[\t\n\r ]+$/g, "");
+}
+function isCarriableHeaderValue(value) {
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    const carriable = code === 9 || code >= 32 && code <= 126 || code >= 128 && code <= 255;
+    if (!carriable)
+      return false;
+  }
+  return true;
+}
+function idempotencyKeyRefusal(message) {
+  return new PeppolValidationError(`Invalid idempotency key: ${message}`, {
+    valid: false,
+    errors: [{ field: "idempotencyKey", message }],
+    warnings: []
+  });
+}
+function applyIdempotencyKey(headers, options) {
+  const key = options?.idempotencyKey;
+  if (key === void 0 || key === null)
+    return;
+  if (typeof key !== "string") {
+    throw idempotencyKeyRefusal(`expected a string, received ${Array.isArray(key) ? "an array" : `a ${typeof key}`}.`);
+  }
+  const normalized = normalizeHeaderValue(key);
+  if (normalized === "") {
+    throw idempotencyKeyRefusal("the key is blank once HTTP whitespace is stripped, so it would reach the gateway empty and protect nothing. Pass a non-blank key, or omit the option.");
+  }
+  if (!isCarriableHeaderValue(normalized)) {
+    throw idempotencyKeyRefusal("the key contains a character no HTTP header can carry. A header value may hold only HTAB, space, U+0021-U+007E and U+0080-U+00FF (RFC 9110 field-value) \u2014 so every control character other than the tab, plus DEL and anything above U+00FF, is refused by the transport itself.");
+  }
+  headers["Idempotency-Key"] = normalized;
+}
+function carriesUsableIdempotencyKey(headers) {
   if (!headers)
-    return void 0;
-  const target = name.toLowerCase();
-  for (const [key, value] of Object.entries(headers)) {
-    if (key.toLowerCase() === target)
-      return value;
+    return false;
+  for (const [name, value] of Object.entries(headers)) {
+    if (name.toLowerCase() !== "idempotency-key")
+      continue;
+    if (typeof value === "string" && normalizeHeaderValue(value) !== "")
+      return true;
   }
-  return void 0;
+  return false;
 }
 var RETRYABLE_STATUS_CODES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
 function sleep(ms) {
@@ -2369,33 +2647,16 @@ function parseRetryAfter(headerValue) {
   }
   return void 0;
 }
-var CONTROL_CHARACTERS = /[\u0000-\u001F\u007F-\u009F]/g;
-function stripControls(value) {
-  return value.replace(CONTROL_CHARACTERS, " ");
-}
 function readOwn(source, key) {
   return Object.hasOwn(source, key) ? source[key] : void 0;
 }
-function readSentence(source, key) {
+function readSentence2(source, key) {
   const value = readOwn(source, key);
   if (typeof value !== "string")
     return null;
   const cleaned = stripControls(value).trim();
   return cleaned === "" ? null : cleaned;
 }
-function safeDocsUrl(value) {
-  if (typeof value !== "string")
-    return null;
-  let parsed;
-  try {
-    parsed = new URL(value);
-  } catch {
-    return null;
-  }
-  if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
-    return null;
-  return parsed.href;
-}
 function formatApiErrorMessage(status, rawBody) {
   const verbatim = `getpeppr API error (${status}): ${stripControls(rawBody)}`;
   let parsed;
@@ -2407,7 +2668,7 @@ function formatApiErrorMessage(status, rawBody) {
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
     return verbatim;
   }
-  const sentence = readSentence(parsed, "message") ?? readSentence(parsed, "error");
+  const sentence = readSentence2(parsed, "message") ?? readSentence2(parsed, "error");
   if (sentence === null)
     return verbatim;
   const link = safeDocsUrl(readOwn(parsed, "docs"));
@@ -2415,6 +2676,8 @@ function formatApiErrorMessage(status, rawBody) {
 }
 function isRetryableError(error2) {
   if (error2 instanceof PeppolApiError) {
+    if (error2.retryable !== void 0)
+      return error2.retryable;
     return RETRYABLE_STATUS_CODES.has(error2.statusCode);
   }
   if (error2 instanceof Error && error2.name === "AbortError") {
@@ -2456,7 +2719,7 @@ var GetpepprAdapter = class {
         lastError = err;
         const is429 = err instanceof PeppolApiError && err.statusCode === 429;
         const isSafeMethod = /^(GET|DELETE|HEAD)$/i.test(method);
-        const hasIdempotencyKey = !!findHeaderCaseInsensitive(extraHeaders, "Idempotency-Key");
+        const hasIdempotencyKey = carriesUsableIdempotencyKey(extraHeaders);
         const canRetry = is429 || isSafeMethod || hasIdempotencyKey;
         if (attempt < maxRetries && canRetry && isRetryableError(err)) {
           const retryAfterMs = err instanceof PeppolApiError ? err.retryAfterMs : void 0;
@@ -2499,6 +2762,7 @@ var GetpepprAdapter = class {
         body: body ? JSON.stringify(body) : void 0,
         signal: controller.signal
       });
+      const result = parseApiResultHeaders(response.headers);
       if (!response.ok) {
         const errorBody = await response.text().catch(() => "Unknown error");
         const retryAfterMs = response.status === 429 ? parseRetryAfter(response.headers.get("Retry-After")) : void 0;
@@ -2509,12 +2773,13 @@ var GetpepprAdapter = class {
               headers: Object.fromEntries(response.headers.entries()),
               body: errorBody,
               durationMs: Date.now() - startTime,
-              timestamp: Date.now()
+              timestamp: Date.now(),
+              result: cloneResultForHook(result)
             });
           } catch {
           }
         }
-        throw new PeppolApiError(formatApiErrorMessage(response.status, errorBody), response.status, errorBody, retryAfterMs);
+        throw new PeppolApiError(formatApiErrorMessage(response.status, errorBody), response.status, errorBody, retryAfterMs, result);
       }
       if (response.status === 204) {
         if (this.onResponse) {
@@ -2524,7 +2789,8 @@ var GetpepprAdapter = class {
               headers: Object.fromEntries(response.headers.entries()),
               body: void 0,
               durationMs: Date.now() - startTime,
-              timestamp: Date.now()
+              timestamp: Date.now(),
+              result: cloneResultForHook(result)
             });
           } catch {
           }
@@ -2535,7 +2801,20 @@ var GetpepprAdapter = class {
       try {
         responseBody = await response.json();
       } catch {
-        throw new PeppolApiError(`getpeppr API error: unexpected response format (status ${response.status})`, response.status, "Response body is not valid JSON");
+        if (this.onResponse) {
+          try {
+            this.onResponse({
+              status: response.status,
+              headers: Object.fromEntries(response.headers.entries()),
+              body: void 0,
+              durationMs: Date.now() - startTime,
+              timestamp: Date.now(),
+              result: cloneResultForHook(result)
+            });
+          } catch {
+          }
+        }
+        throw new PeppolApiError(`getpeppr API error: unexpected response format (status ${response.status})`, response.status, "Response body is not valid JSON", void 0, result);
       }
       if (this.onResponse) {
         try {
@@ -2554,7 +2833,8 @@ var GetpepprAdapter = class {
             // swallows everything — so the hook fires with a marker instead.
             body: cloneForHook(responseBody),
             durationMs: Date.now() - startTime,
-            timestamp: Date.now()
+            timestamp: Date.now(),
+            result: cloneResultForHook(result)
           });
         } catch {
         }
@@ -2568,9 +2848,7 @@ var GetpepprAdapter = class {
   // legacy `_draft` marker, which the current gateway rejects explicitly.
   async sendInvoice(input, options) {
     const headers = {};
-    if (options?.idempotencyKey) {
-      headers["Idempotency-Key"] = options.idempotencyKey;
-    }
+    applyIdempotencyKey(headers, options);
     if (options?.validateRecipient) {
       headers["X-Validate-Recipient"] = options.validateRecipient === true ? "warn" : String(options.validateRecipient);
     }
@@ -2579,17 +2857,17 @@ var GetpepprAdapter = class {
   }
   async createInvoice(input, options) {
     const headers = {};
-    if (options?.idempotencyKey) {
-      headers["Idempotency-Key"] = options.idempotencyKey;
-    }
+    applyIdempotencyKey(headers, options);
     if (options?.validateRecipient) {
       headers["X-Validate-Recipient"] = options.validateRecipient === true ? "warn" : String(options.validateRecipient);
     }
     const result = await this.request("POST", "/invoices", { ...input, _draft: true }, headers);
     return parseSendResult(result);
   }
-  async sendInvoiceById(id) {
-    await this.request("POST", `/invoices/send/${id}`);
+  async sendInvoiceById(id, options) {
+    const headers = {};
+    applyIdempotencyKey(headers, options);
+    await this.request("POST", `/invoices/send/${id}`, void 0, headers);
   }
   async sendCreditNote(input) {
     const result = await this.request("POST", "/credit-notes", input);
@@ -2695,6 +2973,7 @@ var GetpepprAdapter = class {
         headers: requestHeaders,
         signal: controller.signal
       });
+      const result = parseApiResultHeaders(response.headers);
       if (!response.ok) {
         const errorBody = await response.text().catch(() => "Unknown error");
         const retryAfterMs = response.status === 429 ? parseRetryAfter(response.headers.get("Retry-After")) : void 0;
@@ -2705,12 +2984,13 @@ var GetpepprAdapter = class {
               headers: Object.fromEntries(response.headers.entries()),
               body: errorBody,
               durationMs: Date.now() - startTime,
-              timestamp: Date.now()
+              timestamp: Date.now(),
+              result: cloneResultForHook(result)
             });
           } catch {
           }
         }
-        throw new PeppolApiError(formatApiErrorMessage(response.status, errorBody), response.status, errorBody, retryAfterMs);
+        throw new PeppolApiError(formatApiErrorMessage(response.status, errorBody), response.status, errorBody, retryAfterMs, result);
       }
       const responseBody = await response.arrayBuffer();
       if (this.onResponse) {
@@ -2720,7 +3000,8 @@ var GetpepprAdapter = class {
             headers: Object.fromEntries(response.headers.entries()),
             body: `[ArrayBuffer: ${responseBody.byteLength} bytes]`,
             durationMs: Date.now() - startTime,
-            timestamp: Date.now()
+            timestamp: Date.now(),
+            result: cloneResultForHook(result)
           });
         } catch {
         }
@@ -2771,8 +3052,10 @@ var GetpepprAdapter = class {
       }
     };
   }
-  async acknowledgeInvoice(id) {
-    const result = await this.request("POST", `/invoices/${id}/ack`);
+  async acknowledgeInvoice(id, options) {
+    const headers = {};
+    applyIdempotencyKey(headers, options);
+    const result = await this.request("POST", `/invoices/${id}/ack`, void 0, headers);
     return parseSendResult(result);
   }
   async updateInvoice(id, input) {
@@ -2823,8 +3106,10 @@ var GetpepprAdapter = class {
     const result = await this.request("GET", `/contacts/${id}`);
     return parseContact(result);
   }
-  async createContact(input) {
-    const result = await this.request("POST", "/contacts", input);
+  async createContact(input, options) {
+    const headers = {};
+    applyIdempotencyKey(headers, options);
+    const result = await this.request("POST", "/contacts", input, headers);
     return parseContact(result);
   }
   async updateContact(id, input) {
@@ -2836,8 +3121,7 @@ var GetpepprAdapter = class {
   }
   async createLegalEntity(input, options) {
     const headers = {};
-    if (options?.idempotencyKey)
-      headers["Idempotency-Key"] = options.idempotencyKey;
+    applyIdempotencyKey(headers, options);
     const result = await this.request("POST", "/legal-entities", input, headers);
     return parseLegalEntity(result);
   }
@@ -2876,8 +3160,7 @@ var GetpepprAdapter = class {
   }
   async requestLegalEntityAttestation(id, input, options) {
     const headers = {};
-    if (options?.idempotencyKey)
-      headers["Idempotency-Key"] = options.idempotencyKey;
+    applyIdempotencyKey(headers, options);
     const result = await this.request("POST", `/legal-entities/${id}/attestation`, input, headers);
     return {
       id: String(result.id ?? id),
@@ -2915,8 +3198,10 @@ var GetpepprAdapter = class {
     const result = await this.request("GET", `/bank-accounts/${id}`);
     return parseBankAccount(result);
   }
-  async createBankAccount(input) {
-    const result = await this.request("POST", "/bank-accounts", input);
+  async createBankAccount(input, options) {
+    const headers = {};
+    applyIdempotencyKey(headers, options);
+    const result = await this.request("POST", "/bank-accounts", input, headers);
     return parseBankAccount(result);
   }
   async updateBankAccount(id, input) {
@@ -2953,7 +3238,9 @@ var GetpepprAdapter = class {
       // tout en salissant le corps des envois standards.
       ...options.sender ? { sender: options.sender } : {}
     };
-    const result = await this.request("POST", "/invoices/import", body);
+    const headers = {};
+    applyIdempotencyKey(headers, options);
+    const result = await this.request("POST", "/invoices/import", body, headers);
     return parseSendResult(result);
   }
   async listTransportTypes() {
@@ -3007,6 +3294,9 @@ function detectMimeType(filename) {
   }
 }
 var PROTOCOL_ERROR_BODY_LIMIT = 2e3;
+function cloneResultForHook(result) {
+  return result === void 0 ? void 0 : { ...result };
+}
 function cloneForHook(body) {
   try {
     return structuredClone(body);
@@ -3209,12 +3499,24 @@ function parseLegalEntity(raw) {
     country: raw.country != null ? String(raw.country) : null,
     identifier: idObj && idObj.scheme != null && idObj.value != null ? { scheme: String(idObj.scheme), value: String(idObj.value) } : null,
     status: String(raw.status ?? "pending"),
+    networkDiscovery: raw.networkDiscovery && typeof raw.networkDiscovery === "object" ? raw.networkDiscovery : { state: "pending", attempts: 0 },
     environment: String(raw.environment ?? ""),
     createdAt: String(raw.createdAt ?? "")
   };
   if (raw.verificationDetail != null) {
     le.verificationDetail = raw.verificationDetail;
   }
+  if (raw.registrationDetail && typeof raw.registrationDetail === "object") {
+    const reason = raw.registrationDetail.reason;
+    const safeReasons = [
+      "already_registered",
+      "invalid_format",
+      "provider_error"
+    ];
+    le.registrationDetail = {
+      reason: safeReasons.includes(reason) ? reason : "provider_error"
+    };
+  }
   return le;
 }
 function parseAccountIdentity(raw) {
@@ -3437,14 +3739,95 @@ var PeppolProtocolError = class extends PeppolError {
 var PeppolApiError = class extends PeppolError {
   statusCode;
   responseBody;
-  /** Parsed Retry-After delay in milliseconds (present on 429 responses) */
+  /**
+   * Parsed `Retry-After` delay in milliseconds.
+   *
+   * `undefined` unless this response is a **429** AND carried a readable
+   * `Retry-After`. No other status reads that header, whatever its remediation
+   * says — measured, all 22 `retry_after` entries in the catalogue are 429s.
+   * The gateway does not attach the header to every throttled answer either.
+   */
   retryAfterMs;
-  constructor(message, statusCode, responseBody, retryAfterMs) {
+  /**
+   * The canonical result the gateway declared for this response, read from its
+   * six headers — no body parsing required.
+   *
+   * `undefined` against a gateway that has not activated the result catalogue,
+   * and behind any hop that strips unknown headers. The flattened accessors
+   * below all read from here, so they are `undefined` together.
+   */
+  result;
+  constructor(message, statusCode, responseBody, retryAfterMs, result) {
     super(message);
     this.statusCode = statusCode;
     this.responseBody = responseBody;
     this.name = "PeppolApiError";
     this.retryAfterMs = retryAfterMs;
+    this.result = result;
+  }
+  /**
+   * Stable getpeppr result code for this failure (e.g. `"auth.api_key_invalid"`).
+   *
+   * ⛔ NOT the same field as {@link code}, and they can both be present with
+   * different values: this one is the catalogue's global code, `code` is the
+   * route's own sub-reason from the body.
+   *
+   * `undefined` when the gateway sent no result headers.
+   */
+  get resultCode() {
+    return this.result?.code;
+  }
+  /**
+   * The catalogue's sentence for {@link resultCode}.
+   *
+   * ⚠️ Usually SHORTER on detail than `.message`, which is built from the
+   * response body and can name the offending field or rule. Show `.message` to
+   * a human; use this one when you want the stable phrasing.
+   *
+   * `undefined` when the gateway sent no result headers.
+   */
+  get resultMessage() {
+    return this.result?.message;
+  }
+  /**
+   * Server-generated correlation id for this exact request. Quote it to support.
+   *
+   * `undefined` when the gateway sent no result headers — which includes every
+   * response from a deployment predating the catalogue.
+   */
+  get requestId() {
+    return this.result?.requestId;
+  }
+  /**
+   * Whether retrying this same request can succeed, per the catalogue.
+   *
+   * ⚠️ `undefined` means "the gateway did not say", NOT "no" — the SDK then
+   * falls back to its historic status policy. A `false` here is an explicit
+   * refusal and the SDK will not retry, whatever the status.
+   */
+  get retryable() {
+    return this.result?.retryable;
+  }
+  /**
+   * What to do about it: `"none"`, `"fix_request"`, `"authenticate"`,
+   * `"retry"`, `"retry_after"`, `"wait"` or `"contact_support"` today.
+   *
+   * Typed open — a value added server-side reaches you rather than vanishing.
+   * `undefined` when the gateway sent no result headers.
+   */
+  get remediation() {
+    return this.result?.remediation;
+  }
+  /**
+   * Documentation link for {@link resultCode}, when the catalogue provides one.
+   *
+   * `undefined` when the gateway sent no result headers, when the catalogue
+   * entry has no docs link, or when the value was not a plain `https://` URL
+   * (`http:`, credentials in the authority, and anything the URL parser would
+   * have to repair are all refused).
+   */
+  get docs() {
+    return this.result?.docs;
   }
   /**
    * The gateway's machine-readable error code, parsed from the JSON response body
@@ -3617,8 +4000,8 @@ ${validation.errors.map((e) => `  - ${e.field}: ${e.message}${e.suggestion ? ` (
    * always returns 501. Submit the final document with `invoices.send()`.
    * @throws {PeppolApiError} 501 with the current gateway provider
    */
-  async sendById(id) {
-    return this.adapter.sendInvoiceById(id);
+  async sendById(id, options) {
+    return this.adapter.sendInvoiceById(id, options);
   }
   /**
    * Send an invoice via Peppol.
@@ -3792,8 +4175,8 @@ ${validation.errors.map((e) => `  - ${e.field}: ${e.message}${e.suggestion ? ` (
    * acknowledgement and always returns 501.
    * @throws {PeppolApiError} 501 with the current gateway provider
    */
-  async acknowledge(id) {
-    return this.adapter.acknowledgeInvoice(id);
+  async acknowledge(id, options) {
+    return this.adapter.acknowledgeInvoice(id, options);
   }
   /**
    * Request an update to an existing invoice.
@@ -4083,8 +4466,8 @@ var ContactOperations = class {
    * });
    * ```
    */
-  async create(input) {
-    return this.adapter.createContact(input);
+  async create(input, options) {
+    return this.adapter.createContact(input, options);
   }
   /**
    * Update an existing contact.
@@ -4309,8 +4692,8 @@ var BankAccountOperations = class {
    * });
    * ```
    */
-  async create(input) {
-    return this.adapter.createBankAccount(input);
+  async create(input, options) {
+    return this.adapter.createBankAccount(input, options);
   }
   /**
    * Update an existing bank account.
@@ -5261,6 +5644,12 @@ async function pollUntilTerminal(client, documentId, options = {}) {
   return { finalStatus: lastStatus, timedOut: true };
 }
 
+// src/lib/dashboard-url.ts
+var DASHBOARD_INVOICES_BASE = "https://console.getpeppr.dev/invoices";
+function dashboardUrlForSendResult(result) {
+  return `${DASHBOARD_INVOICES_BASE}/${result.id}`;
+}
+
 // src/formatters/send-result.ts
 import pc5 from "picocolors";
 function formatSendResult(result, mode) {
@@ -5286,7 +5675,6 @@ function formatSendResult(result, mode) {
 // src/commands/send.ts
 var API_BASE = "https://api.getpeppr.dev/v1";
 var LOCAL_BASE = "http://localhost:3001/api/v1";
-var DASHBOARD_BASE = "https://console.getpeppr.dev/invoices";
 function registerSendCommand(program2) {
   program2.command("send").description("Send an invoice to the Peppol network via getpeppr API").argument("[file]", "optional path to invoice JSON (mutex with --to/--amount/...)").option("--prod", "target production (live keys + confirmation)").option("--local", "target localhost:3001 dev server").option("--key <key>", "override API key \u2014 for CI/scripted use only; visible in `ps` and shell history. Prefer GETPEPPR_API_KEY env var.").option("--to <peppol-id>", "recipient peppol id (e.g., 9925:BE0314595348)").option("--country <iso>", "recipient ISO 3166-1 alpha-2 country override (e.g., BE)").option("--amount <number>", "line amount in major currency units (decimal allowed)").option("--currency <iso>", "ISO 4217 currency (default EUR)").option("--desc <text>", "line description").option("--attachment", "attach the test PDF").option("--watch", "poll status until a terminal state (60s timeout)").option("-y, --yes", "skip --prod confirmation prompt").option("--no-validate", "skip pre-validation locally").option("--json", "output JSON").option("--quiet", "exit code only, no output").action(async (file, flags) => {
     let auth;
@@ -5390,7 +5778,7 @@ function registerSendCommand(program2) {
 `);
       process.exit(1);
     }
-    const dashboardUrl = `${DASHBOARD_BASE}/${result.id}`;
+    const dashboardUrl = dashboardUrlForSendResult(result);
     let finalStatus = result.status;
     let timedOut = false;
     let watchFailed = false;