@ar-agents/mercadopago 0.9.0 → 0.11.0

package/dist/index.cjs

@@ -3,6 +3,75 @@
 var ai = require('ai');
 var zod = require('zod');
 
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/crypto.ts
+var crypto_exports = {};
+__export(crypto_exports, {
+  hmacSha256Hex: () => hmacSha256Hex,
+  sha256Hex: () => sha256Hex,
+  timingSafeEqualHex: () => timingSafeEqualHex
+});
+async function hmacSha256Hex(secret, message) {
+  const keyMaterial = await subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sigBuf = await subtle.sign(
+    "HMAC",
+    keyMaterial,
+    encoder.encode(message)
+  );
+  return bufferToHex(sigBuf);
+}
+async function sha256Hex(input) {
+  const digest = await subtle.digest("SHA-256", encoder.encode(input));
+  return bufferToHex(digest);
+}
+function timingSafeEqualHex(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+function bufferToHex(buf) {
+  const bytes = new Uint8Array(buf);
+  let hex = "";
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i];
+    hex += (b < 16 ? "0" : "") + b.toString(16);
+  }
+  return hex;
+}
+var subtle, encoder;
+var init_crypto = __esm({
+  "src/crypto.ts"() {
+    subtle = (() => {
+      const c = globalThis.crypto;
+      if (!c?.subtle) {
+        throw new Error(
+          "@ar-agents/mercadopago: Web Crypto API is not available in this runtime. Use Node 18+, Vercel Edge Runtime, Cloudflare Workers, or any modern browser."
+        );
+      }
+      return c.subtle;
+    })();
+    encoder = new TextEncoder();
+  }
+});
+
 // src/errors.ts
 var MercadoPagoError = class extends Error {
   constructor(message, status, endpoint, mpResponse) {
@@ -1334,53 +1403,8 @@ var MercadoPagoClient = class {
   }
 };
 
-// src/crypto.ts
-var subtle = (() => {
-  const c = globalThis.crypto;
-  if (!c?.subtle) {
-    throw new Error(
-      "@ar-agents/mercadopago: Web Crypto API is not available in this runtime. Use Node 18+, Vercel Edge Runtime, Cloudflare Workers, or any modern browser."
-    );
-  }
-  return c.subtle;
-})();
-var encoder = new TextEncoder();
-async function hmacSha256Hex(secret, message) {
-  const keyMaterial = await subtle.importKey(
-    "raw",
-    encoder.encode(secret),
-    { name: "HMAC", hash: "SHA-256" },
-    false,
-    ["sign"]
-  );
-  const sigBuf = await subtle.sign(
-    "HMAC",
-    keyMaterial,
-    encoder.encode(message)
-  );
-  return bufferToHex(sigBuf);
-}
-async function sha256Hex(input) {
-  const digest = await subtle.digest("SHA-256", encoder.encode(input));
-  return bufferToHex(digest);
-}
-function timingSafeEqualHex(a, b) {
-  if (a.length !== b.length) return false;
-  let diff = 0;
-  for (let i = 0; i < a.length; i++) {
-    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
-  }
-  return diff === 0;
-}
-function bufferToHex(buf) {
-  const bytes = new Uint8Array(buf);
-  let hex = "";
-  for (let i = 0; i < bytes.length; i++) {
-    const b = bytes[i];
-    hex += (b < 16 ? "0" : "") + b.toString(16);
-  }
-  return hex;
-}
+// src/tools.ts
+init_crypto();
 zod.z.enum(["MLA", "MLB", "MLM", "MCO", "MLC", "MLU"]);
 var CurrencyIdSchema = zod.z.enum(["ARS", "USD", "BRL", "MXN"]);
 var FrequencyTypeSchema = zod.z.enum(["months", "days"]);
@@ -1884,6 +1908,180 @@ function isExpiringSoon(expirationMs, skewSeconds = 300) {
   return Date.now() + skewSeconds * 1e3 >= expirationMs;
 }
 
+// src/ar-issuer-promos.ts
+var AHORA_PROGRAM_PROMOS = [
+  {
+    issuer: "*",
+    // any AR-resident card
+    paymentMethodId: "*",
+    installments: 3,
+    description: "Ahora 3 \u2014 3 cuotas sin inter\xE9s (programa nacional)",
+    categories: ["electronics", "appliances", "clothing", "general"]
+  },
+  {
+    issuer: "*",
+    paymentMethodId: "*",
+    installments: 6,
+    description: "Ahora 6 \u2014 6 cuotas sin inter\xE9s (programa nacional, electrodom\xE9sticos l\xEDnea blanca)",
+    categories: ["appliances"]
+  },
+  {
+    issuer: "*",
+    paymentMethodId: "*",
+    installments: 12,
+    description: "Ahora 12 \u2014 12 cuotas sin inter\xE9s (programa nacional)",
+    categories: ["electronics", "appliances", "clothing"]
+  },
+  {
+    issuer: "*",
+    paymentMethodId: "*",
+    installments: 18,
+    description: "Ahora 18 \u2014 18 cuotas sin inter\xE9s (turismo nacional + electrodom\xE9sticos)",
+    categories: ["appliances", "travel"]
+  },
+  {
+    issuer: "*",
+    paymentMethodId: "*",
+    installments: 24,
+    description: "Ahora 24 \u2014 24 cuotas sin inter\xE9s (electrodom\xE9sticos l\xEDnea blanca premium)",
+    categories: ["appliances"]
+  }
+];
+var AR_ISSUER_PROMOS = [
+  // Naranja X
+  {
+    issuer: "Naranja X",
+    paymentMethodId: "naranja",
+    installments: 3,
+    description: "Naranja Z (Plan Z) \u2014 3 cuotas con CFT promocional, todos los rubros"
+  },
+  {
+    issuer: "Naranja X",
+    paymentMethodId: "naranja",
+    installments: 6,
+    description: "Naranja \u2014 6 cuotas sin inter\xE9s con comercios adheridos (electro/indumentaria)",
+    daysOfWeek: ["thu"],
+    categories: ["electronics", "appliances", "clothing"]
+  },
+  // Galicia
+  {
+    issuer: "Banco Galicia",
+    paymentMethodId: "visa",
+    installments: 12,
+    description: "Galicia Eminent / Quiero! \u2014 12 cuotas sin inter\xE9s en supermercados (jueves)",
+    daysOfWeek: ["thu"],
+    categories: ["supermarket"]
+  },
+  {
+    issuer: "Banco Galicia",
+    paymentMethodId: "master",
+    installments: 6,
+    description: "Galicia \u2014 6 cuotas sin inter\xE9s en gastronom\xEDa (viernes y s\xE1bados)",
+    daysOfWeek: ["fri", "sat"]
+  },
+  // Santander
+  {
+    issuer: "Banco Santander",
+    paymentMethodId: "visa",
+    installments: 6,
+    description: "Santander Black / Platinum \u2014 6 cuotas sin inter\xE9s en cines + viajes",
+    categories: ["travel"]
+  },
+  {
+    issuer: "Banco Santander",
+    paymentMethodId: "amex",
+    installments: 9,
+    description: "Santander American Express \u2014 9 cuotas sin inter\xE9s en supermercados (martes y mi\xE9rcoles)",
+    daysOfWeek: ["tue", "wed"],
+    categories: ["supermarket"]
+  },
+  // Macro
+  {
+    issuer: "Banco Macro",
+    paymentMethodId: "visa",
+    installments: 6,
+    description: "Macro Selecta / Premia \u2014 6 cuotas sin inter\xE9s en farmacias y librer\xEDas",
+    categories: ["health", "education"]
+  },
+  // BBVA
+  {
+    issuer: "BBVA Banco Franc\xE9s",
+    paymentMethodId: "visa",
+    installments: 3,
+    description: "BBVA Lat / Black \u2014 3 cuotas sin inter\xE9s en restaurantes (lunes a mi\xE9rcoles)",
+    daysOfWeek: ["mon", "tue", "wed"]
+  },
+  // ICBC
+  {
+    issuer: "ICBC",
+    paymentMethodId: "visa",
+    installments: 6,
+    description: "ICBC Cuenta Corriente \u2014 6 cuotas sin inter\xE9s en electro y indumentaria",
+    categories: ["electronics", "appliances", "clothing"]
+  },
+  // Patagonia
+  {
+    issuer: "Banco Patagonia",
+    paymentMethodId: "visa",
+    installments: 3,
+    description: "Patagonia 365 / Eminent \u2014 3 cuotas sin inter\xE9s en supermercados (s\xE1bados)",
+    daysOfWeek: ["sat"],
+    categories: ["supermarket"]
+  },
+  // Banco Nación
+  {
+    issuer: "Banco de la Naci\xF3n Argentina",
+    paymentMethodId: "visa",
+    installments: 12,
+    description: "BNA \u2014 12 cuotas sin inter\xE9s con plan 'Ahora 12' del programa nacional",
+    categories: ["electronics", "appliances", "clothing"]
+  },
+  // Banco Provincia
+  {
+    issuer: "Banco de la Provincia de Buenos Aires",
+    paymentMethodId: "visa",
+    installments: 6,
+    description: "Cuenta DNI \u2014 6 cuotas sin inter\xE9s (mensual cap aplica)",
+    maxAmountArs: 2e5
+  },
+  // Banco Ciudad
+  {
+    issuer: "Banco de la Ciudad de Buenos Aires",
+    paymentMethodId: "visa",
+    installments: 12,
+    description: "Banco Ciudad \u2014 12 cuotas sin inter\xE9s en electrodom\xE9sticos (Plan Sue\xF1os)",
+    categories: ["appliances"]
+  }
+];
+function findApplicablePromos(args) {
+  const date = args.date ?? /* @__PURE__ */ new Date();
+  const dayOfWeek = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"][date.getDay()];
+  const candidates = [
+    ...args.includeAhoraProgram !== false ? AHORA_PROGRAM_PROMOS : [],
+    ...AR_ISSUER_PROMOS
+  ];
+  return candidates.filter((promo) => {
+    if (args.issuer !== void 0 && promo.issuer !== "*" && promo.issuer !== args.issuer) {
+      return false;
+    }
+    if (args.paymentMethodId !== void 0 && promo.paymentMethodId !== "*" && promo.paymentMethodId !== args.paymentMethodId) {
+      return false;
+    }
+    if (promo.daysOfWeek && promo.daysOfWeek.length > 0 && !promo.daysOfWeek.includes(dayOfWeek)) {
+      return false;
+    }
+    if (args.category !== void 0 && promo.categories && promo.categories.length > 0 && !promo.categories.includes(args.category)) {
+      return false;
+    }
+    if (args.amountArs !== void 0 && promo.minAmountArs !== void 0 && args.amountArs < promo.minAmountArs) {
+      return false;
+    }
+    if (promo.startDate && date < new Date(promo.startDate)) return false;
+    if (promo.endDate && date > new Date(promo.endDate)) return false;
+    return true;
+  });
+}
+
 // src/helpers.ts
 function computeMarketplaceFee(amountArs, rule) {
   if (amountArs <= 0) return 0;
@@ -2121,6 +2319,487 @@ function explainPaymentStatus(payment) {
   }
 }
 
+// src/pagination.ts
+async function* paginate(fetchPage, opts) {
+  const pageSize = opts.pageSize ?? 100;
+  const concurrency = Math.max(1, opts.concurrency ?? 1);
+  let yielded = 0;
+  let offset = 0;
+  let knownTotal = void 0;
+  while (true) {
+    if (opts.maxItems !== void 0 && yielded >= opts.maxItems) return;
+    const inFlight = [];
+    for (let i = 0; i < concurrency; i++) {
+      const pageOffset = offset + i * pageSize;
+      if (knownTotal !== void 0 && pageOffset >= knownTotal) break;
+      inFlight.push(fetchPage(pageOffset, pageSize));
+    }
+    if (inFlight.length === 0) return;
+    const pages = await Promise.all(inFlight);
+    let allEmpty = true;
+    for (const page of pages) {
+      const items = opts.extractItems(page);
+      const total = opts.extractTotal?.(page);
+      if (total !== void 0) knownTotal = total;
+      if (items.length > 0) allEmpty = false;
+      for (const item of items) {
+        if (opts.maxItems !== void 0 && yielded >= opts.maxItems) return;
+        yield item;
+        yielded++;
+      }
+    }
+    if (allEmpty) return;
+    offset += pages.length * pageSize;
+    if (knownTotal !== void 0 && offset >= knownTotal) return;
+  }
+}
+async function collect(iter) {
+  const out = [];
+  for await (const item of iter) out.push(item);
+  return out;
+}
+function paginatePayments(client, filter = {}, opts = {}) {
+  return paginate(
+    (offset, limit) => client.searchPayments({ ...filter, offset, limit }),
+    {
+      extractItems: (p) => p.results ?? [],
+      extractTotal: (p) => p.paging?.total,
+      ...opts
+    }
+  );
+}
+function paginateSubscriptions(client, filter = {}, opts = {}) {
+  return paginate(
+    (offset, limit) => client.searchPreapprovals({ ...filter, offset, limit }),
+    {
+      extractItems: (p) => p.results,
+      extractTotal: (p) => p.paging.total,
+      ...opts
+    }
+  );
+}
+function paginateAccountMovements(client, filter = {}, opts = {}) {
+  return paginate(
+    (offset, limit) => client.listAccountMovements({ ...filter, offset, limit }),
+    {
+      extractItems: (p) => p.movements,
+      extractTotal: (p) => p.paging.total,
+      ...opts
+    }
+  );
+}
+function paginateSettlements(client, filter = {}, opts = {}) {
+  return paginate(
+    (offset, limit) => client.listSettlements({ ...filter, offset, limit }),
+    {
+      extractItems: (p) => p.settlements,
+      extractTotal: (p) => p.paging.total,
+      ...opts
+    }
+  );
+}
+function paginateMerchantOrders(client, filter = {}, opts = {}) {
+  return paginate(
+    (offset, limit) => client.searchMerchantOrders({ ...filter, offset, limit }),
+    {
+      extractItems: (p) => p.elements,
+      extractTotal: (p) => p.paging.total,
+      ...opts
+    }
+  );
+}
+function paginateSubscriptionPlans(client, filter = {}, opts = {}) {
+  return paginate(
+    (offset, limit) => client.listSubscriptionPlans({ ...filter, offset, limit }),
+    {
+      extractItems: (p) => p.results,
+      extractTotal: (p) => p.paging.total,
+      ...opts
+    }
+  );
+}
+function paginateSubscriptionPayments(client, preapprovalId, opts = {}) {
+  return paginate(
+    (offset, limit) => client.listSubscriptionPayments(preapprovalId, { offset, limit }),
+    {
+      extractItems: (p) => p.results,
+      extractTotal: (p) => p.paging.total,
+      ...opts
+    }
+  );
+}
+
+// src/tax-id.ts
+function validateTaxId(input, type) {
+  switch (type) {
+    case "DNI":
+      return validateAR_DNI(input);
+    case "CUIT":
+    case "CUIL":
+      return validateAR_CUIT(input, type);
+    case "CPF":
+      return validateBR_CPF(input);
+    case "CNPJ":
+      return validateBR_CNPJ(input);
+    case "RFC":
+      return validateMX_RFC(input);
+    case "RUT_CL":
+      return validateCL_RUT(input);
+    case "NIT":
+      return validateCO_NIT(input);
+    case "RUT_UY":
+      return validateUY_RUT(input);
+    case "RUC":
+      return validatePE_RUC(input);
+  }
+}
+function validateAR_DNI(input) {
+  const normalized = (input ?? "").replace(/\D/g, "");
+  if (normalized.length === 0) {
+    return failure(normalized, "DNI", "AR", "DNI vac\xEDo.");
+  }
+  if (normalized.length < 7 || normalized.length > 8) {
+    return failure(
+      normalized,
+      "DNI",
+      "AR",
+      `Debe tener 7 u 8 d\xEDgitos; recib\xED ${normalized.length}.`
+    );
+  }
+  return {
+    valid: true,
+    normalized,
+    formatted: normalized.replace(/^(\d{1,2})(\d{3})(\d{3})$/, "$1.$2.$3"),
+    type: "DNI",
+    country: "AR",
+    error: null
+  };
+}
+var AR_CHECK_WEIGHTS = [5, 4, 3, 2, 7, 6, 5, 4, 3, 2];
+function validateAR_CUIT(input, type) {
+  const normalized = (input ?? "").replace(/\D/g, "");
+  if (normalized.length !== 11) {
+    return failure(
+      normalized,
+      type,
+      "AR",
+      `Debe tener 11 d\xEDgitos; recib\xED ${normalized.length}.`
+    );
+  }
+  const sum = AR_CHECK_WEIGHTS.reduce(
+    (acc, w, i) => acc + w * Number(normalized[i]),
+    0
+  );
+  const remainder = sum % 11;
+  const expected = remainder === 0 ? 0 : remainder === 1 ? 9 : 11 - remainder;
+  const actual = Number(normalized[10]);
+  if (actual !== expected) {
+    return failure(
+      normalized,
+      type,
+      "AR",
+      `D\xEDgito verificador inv\xE1lido. Esperado: ${expected}, recibido: ${actual}.`
+    );
+  }
+  return {
+    valid: true,
+    normalized,
+    formatted: `${normalized.slice(0, 2)}-${normalized.slice(2, 10)}-${normalized.slice(10)}`,
+    type,
+    country: "AR",
+    error: null
+  };
+}
+function validateBR_CPF(input) {
+  const normalized = (input ?? "").replace(/\D/g, "");
+  if (normalized.length !== 11) {
+    return failure(
+      normalized,
+      "CPF",
+      "BR",
+      `Debe tener 11 d\xEDgitos; recib\xED ${normalized.length}.`
+    );
+  }
+  if (/^(\d)\1{10}$/.test(normalized)) {
+    return failure(normalized, "CPF", "BR", "CPF inv\xE1lido (todos los d\xEDgitos iguales).");
+  }
+  const computeDigit = (slice, weights) => {
+    const sum = weights.reduce((acc, w, i) => acc + w * Number(slice[i]), 0);
+    const r = sum * 10 % 11;
+    return r === 10 ? 0 : r;
+  };
+  const d1 = computeDigit(normalized.slice(0, 9), [10, 9, 8, 7, 6, 5, 4, 3, 2]);
+  const d2 = computeDigit(
+    normalized.slice(0, 10),
+    [11, 10, 9, 8, 7, 6, 5, 4, 3, 2]
+  );
+  if (d1 !== Number(normalized[9]) || d2 !== Number(normalized[10])) {
+    return failure(normalized, "CPF", "BR", "D\xEDgitos verificadores inv\xE1lidos.");
+  }
+  return {
+    valid: true,
+    normalized,
+    formatted: normalized.replace(
+      /^(\d{3})(\d{3})(\d{3})(\d{2})$/,
+      "$1.$2.$3-$4"
+    ),
+    type: "CPF",
+    country: "BR",
+    error: null
+  };
+}
+function validateBR_CNPJ(input) {
+  const normalized = (input ?? "").replace(/\D/g, "");
+  if (normalized.length !== 14) {
+    return failure(
+      normalized,
+      "CNPJ",
+      "BR",
+      `Debe tener 14 d\xEDgitos; recib\xED ${normalized.length}.`
+    );
+  }
+  if (/^(\d)\1{13}$/.test(normalized)) {
+    return failure(normalized, "CNPJ", "BR", "CNPJ inv\xE1lido (todos los d\xEDgitos iguales).");
+  }
+  const computeDigit = (slice, weights) => {
+    const sum = weights.reduce((acc, w, i) => acc + w * Number(slice[i]), 0);
+    const r = sum % 11;
+    return r < 2 ? 0 : 11 - r;
+  };
+  const w1 = [5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2];
+  const w2 = [6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2];
+  const d1 = computeDigit(normalized.slice(0, 12), w1);
+  const d2 = computeDigit(normalized.slice(0, 13), w2);
+  if (d1 !== Number(normalized[12]) || d2 !== Number(normalized[13])) {
+    return failure(normalized, "CNPJ", "BR", "D\xEDgitos verificadores inv\xE1lidos.");
+  }
+  return {
+    valid: true,
+    normalized,
+    formatted: normalized.replace(
+      /^(\d{2})(\d{3})(\d{3})(\d{4})(\d{2})$/,
+      "$1.$2.$3/$4-$5"
+    ),
+    type: "CNPJ",
+    country: "BR",
+    error: null
+  };
+}
+function validateMX_RFC(input) {
+  const normalized = (input ?? "").trim().toUpperCase().replace(/[\s-]/g, "");
+  const pfPattern = /^[A-ZÑ&]{4}\d{6}[A-Z\d]{3}$/;
+  const pmPattern = /^[A-ZÑ&]{3}\d{6}[A-Z\d]{3}$/;
+  if (!pfPattern.test(normalized) && !pmPattern.test(normalized)) {
+    return failure(
+      normalized,
+      "RFC",
+      "MX",
+      "RFC mal formado. Persona f\xEDsica: 4 letras + YYMMDD + 3 alfanum\xE9ricos. Persona moral: 3 letras + YYMMDD + 3 alfanum\xE9ricos."
+    );
+  }
+  return {
+    valid: true,
+    normalized,
+    formatted: normalized,
+    type: "RFC",
+    country: "MX",
+    error: null
+  };
+}
+function validateCL_RUT(input) {
+  const cleaned = (input ?? "").replace(/[^0-9kK]/g, "").toUpperCase();
+  if (cleaned.length < 2) {
+    return failure(cleaned, "RUT_CL", "CL", "RUT vac\xEDo o muy corto.");
+  }
+  const body = cleaned.slice(0, -1);
+  const dv = cleaned.slice(-1);
+  if (!/^\d+$/.test(body)) {
+    return failure(cleaned, "RUT_CL", "CL", "Cuerpo del RUT debe ser num\xE9rico.");
+  }
+  let sum = 0;
+  let multiplier = 2;
+  for (let i = body.length - 1; i >= 0; i--) {
+    sum += Number(body[i]) * multiplier;
+    multiplier = multiplier === 7 ? 2 : multiplier + 1;
+  }
+  const r = 11 - sum % 11;
+  const expected = r === 11 ? "0" : r === 10 ? "K" : String(r);
+  if (dv !== expected) {
+    return failure(
+      cleaned,
+      "RUT_CL",
+      "CL",
+      `D\xEDgito verificador inv\xE1lido. Esperado: ${expected}, recibido: ${dv}.`
+    );
+  }
+  return {
+    valid: true,
+    normalized: cleaned,
+    formatted: `${formatThousands(body)}-${dv}`,
+    type: "RUT_CL",
+    country: "CL",
+    error: null
+  };
+}
+var CO_NIT_WEIGHTS = [3, 7, 13, 17, 19, 23, 29, 37, 41, 43, 47, 53, 59, 67, 71];
+function validateCO_NIT(input) {
+  const cleaned = (input ?? "").replace(/[^0-9-]/g, "");
+  const parts = cleaned.split("-");
+  if (parts.length !== 2 || !/^\d+$/.test(parts[0]) || !/^\d$/.test(parts[1])) {
+    return failure(
+      cleaned,
+      "NIT",
+      "CO",
+      "NIT debe tener formato: d\xEDgitos + '-' + d\xEDgito verificador."
+    );
+  }
+  const body = parts[0];
+  const dv = Number(parts[1]);
+  if (body.length > CO_NIT_WEIGHTS.length) {
+    return failure(cleaned, "NIT", "CO", "NIT excesivamente largo.");
+  }
+  let sum = 0;
+  for (let i = 0; i < body.length; i++) {
+    sum += Number(body[body.length - 1 - i]) * CO_NIT_WEIGHTS[i];
+  }
+  const r = sum % 11;
+  const expected = r > 1 ? 11 - r : r;
+  if (dv !== expected) {
+    return failure(
+      cleaned,
+      "NIT",
+      "CO",
+      `D\xEDgito verificador inv\xE1lido. Esperado: ${expected}, recibido: ${dv}.`
+    );
+  }
+  return {
+    valid: true,
+    normalized: body + parts[1],
+    formatted: cleaned,
+    type: "NIT",
+    country: "CO",
+    error: null
+  };
+}
+var UY_RUT_WEIGHTS = [4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2];
+function validateUY_RUT(input) {
+  const normalized = (input ?? "").replace(/\D/g, "");
+  if (normalized.length !== 12) {
+    return failure(
+      normalized,
+      "RUT_UY",
+      "UY",
+      `Debe tener 12 d\xEDgitos; recib\xED ${normalized.length}.`
+    );
+  }
+  let sum = 0;
+  for (let i = 0; i < 11; i++) {
+    sum += Number(normalized[i]) * UY_RUT_WEIGHTS[i];
+  }
+  const r = sum % 11;
+  const expected = r === 0 ? 0 : 11 - r;
+  if (Number(normalized[11]) !== expected) {
+    return failure(
+      normalized,
+      "RUT_UY",
+      "UY",
+      `D\xEDgito verificador inv\xE1lido. Esperado: ${expected}, recibido: ${normalized[11]}.`
+    );
+  }
+  return {
+    valid: true,
+    normalized,
+    formatted: normalized.replace(
+      /^(\d{2})(\d{6})(\d{3})(\d{1})$/,
+      "$1$2$3$4"
+    ),
+    type: "RUT_UY",
+    country: "UY",
+    error: null
+  };
+}
+var PE_RUC_WEIGHTS = [5, 4, 3, 2, 7, 6, 5, 4, 3, 2];
+function validatePE_RUC(input) {
+  const normalized = (input ?? "").replace(/\D/g, "");
+  if (normalized.length !== 11) {
+    return failure(
+      normalized,
+      "RUC",
+      "PE",
+      `Debe tener 11 d\xEDgitos; recib\xED ${normalized.length}.`
+    );
+  }
+  const prefix = normalized.slice(0, 2);
+  if (!["10", "15", "17", "20"].includes(prefix)) {
+    return failure(
+      normalized,
+      "RUC",
+      "PE",
+      `Prefijo ${prefix} no v\xE1lido. Debe ser 10, 15, 17 o 20.`
+    );
+  }
+  let sum = 0;
+  for (let i = 0; i < 10; i++) {
+    sum += Number(normalized[i]) * PE_RUC_WEIGHTS[i];
+  }
+  const r = 11 - sum % 11;
+  const expected = r === 11 ? 0 : r === 10 ? 1 : r;
+  if (Number(normalized[10]) !== expected) {
+    return failure(
+      normalized,
+      "RUC",
+      "PE",
+      `D\xEDgito verificador inv\xE1lido. Esperado: ${expected}, recibido: ${normalized[10]}.`
+    );
+  }
+  return {
+    valid: true,
+    normalized,
+    formatted: normalized,
+    type: "RUC",
+    country: "PE",
+    error: null
+  };
+}
+function failure(normalized, type, country, error) {
+  return {
+    valid: false,
+    normalized,
+    formatted: null,
+    type,
+    country,
+    error
+  };
+}
+function formatThousands(s) {
+  return s.replace(/\B(?=(\d{3})+(?!\d))/g, ".");
+}
+function detectAndValidate(input, country) {
+  const cleaned = input.replace(/\D/g, "");
+  switch (country) {
+    case "AR": {
+      if (cleaned.length === 7 || cleaned.length === 8) return validateTaxId(input, "DNI");
+      if (cleaned.length === 11) return validateTaxId(input, "CUIT");
+      return null;
+    }
+    case "BR": {
+      if (cleaned.length === 11) return validateTaxId(input, "CPF");
+      if (cleaned.length === 14) return validateTaxId(input, "CNPJ");
+      return null;
+    }
+    case "MX":
+      return validateTaxId(input, "RFC");
+    case "CL":
+      return validateTaxId(input, "RUT_CL");
+    case "CO":
+      return validateTaxId(input, "NIT");
+    case "UY":
+      return validateTaxId(input, "RUT_UY");
+    case "PE":
+      return validateTaxId(input, "RUC");
+  }
+}
+
 // src/test-cards.ts
 var TEST_CARDS_AR = {
   VISA_CREDIT: {
@@ -2248,8 +2927,40 @@ function analyze3DS(payment) {
     description: "No se pudo determinar el estado 3DS \u2014 revisar payment.three_d_secure_mode + payment.status_detail manualmente."
   };
 }
+async function confirmChallengeAndPoll(client, paymentId, options = {}) {
+  const maxAttempts = options.maxAttempts ?? 5;
+  const interval = options.pollIntervalMs ?? 1e3;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    if (options.signal?.aborted) {
+      const payment3 = await client.getPayment(paymentId);
+      return { payment: payment3, threeDs: analyze3DS(payment3), resolved: false, attempts: attempt };
+    }
+    const payment2 = await client.getPayment(paymentId);
+    const threeDs = analyze3DS(payment2);
+    const stillWaiting = threeDs.status === "challenge_required" || payment2.status === "pending" || payment2.status === "in_process";
+    if (!stillWaiting) {
+      return { payment: payment2, threeDs, resolved: true, attempts: attempt };
+    }
+    if (attempt < maxAttempts) {
+      await new Promise((resolve) => {
+        const timer = setTimeout(resolve, interval);
+        options.signal?.addEventListener(
+          "abort",
+          () => {
+            clearTimeout(timer);
+            resolve(void 0);
+          },
+          { once: true }
+        );
+      });
+    }
+  }
+  const payment = await client.getPayment(paymentId);
+  return { payment, threeDs: analyze3DS(payment), resolved: false, attempts: maxAttempts };
+}
 
 // src/webhook.ts
+init_crypto();
 function parseWebhookEvent(body, searchParams) {
   const parseResult = WebhookBodySchema.safeParse(body ?? {});
   const parsedBody = parseResult.success ? parseResult.data : {};
@@ -2401,7 +3112,16 @@ var DEFAULT_DESCRIPTIONS = {
   compute_marketplace_fee: "PURE HELPER (no network) \u2014 given a transaction amount + fee rule (% or flat ARS, with optional min/max floors), returns the exact `marketplace_fee` value in ARS to pass to create_order or create_payment_preference. USE WHEN your platform takes a commission and you need to compute the exact fee per transaction. Examples: { percent: 5, minArs: 50, maxArs: 5000 } for percentage with floor + cap; { flatArs: 200, percent: 2 } for fixed + percentage.",
   explain_payment_status: "PURE HELPER (no network) \u2014 given a Payment object (from get_payment / create_payment / handle_webhook), returns { summary, recommendedAction, final, paid, retryable } in Spanish. Translates MP's cryptic status_detail codes to plain Spanish + actionable guidance ('reintentar con otra tarjeta' vs 'esperar webhook' vs 'estado final'). USE THIS instead of having to memorize 30+ status_detail codes \u2014 surface summary + recommendedAction directly to the user.",
   // ── v0.9 — Health check + observability ──────────────────────────────────
-  mp_health_check: "Liveness probe against MP. Returns { ok, latencyMs, userId, circuit }. USE THIS as the first call in long-running agent workflows to verify (a) network path to MP is up, (b) accessToken is valid, (c) MP is responding. Circuit-breaker state included when configured \u2014 surface to ops dashboards. Returns ok=false instead of throwing \u2014 safe to call in monitoring loops without try/catch."
+  mp_health_check: "Liveness probe against MP. Returns { ok, latencyMs, userId, circuit }. USE THIS as the first call in long-running agent workflows to verify (a) network path to MP is up, (b) accessToken is valid, (c) MP is responding. Circuit-breaker state included when configured \u2014 surface to ops dashboards. Returns ok=false instead of throwing \u2014 safe to call in monitoring loops without try/catch.",
+  // ── v0.10 — AR issuer cuotas promos (pure) ───────────────────────────────
+  find_applicable_promos: "PURE HELPER (no network, sub-ms) \u2014 returns the 'cuotas sin inter\xE9s' promotions applicable to a given (issuer, paymentMethodId, amount, category, date) tuple. Includes the federal Ahora 3/6/12/18/24/30 program AND issuer-specific deals (Naranja con Galicia los jueves, Santander Amex en supermercados los martes, etc.). USE THIS BEFORE checkout to surface 'pag\xE1 en 12 cuotas sin inter\xE9s con tu Galicia' hints to the buyer \u2014 drives conversion. Returns an array of CuotasPromo objects; the `description` field is in Spanish and ALWAYS surface verbatim. Catalog updated quarterly.",
+  // ── v0.10 — 3DS challenge resolution ────────────────────────────────────
+  confirm_3ds_challenge: "After the buyer completes a 3DS challenge (redirected back from challengeUrl), call this to poll MP and confirm whether the payment is now resolved. Polls get_payment up to N times with exponential backoff. Returns { payment, threeDs, resolved, attempts }. USE THIS as the FINAL step in the 3DS flow (after analyze_payment_3ds detected a challenge_required). Without confirming, the payment stays in 'pending' indefinitely from the buyer's perspective.",
+  // ── v0.10 — Auto-paginate variants ──────────────────────────────────────
+  search_payments_all: "Collect ALL payments matching a filter \u2014 auto-paginates under the hood. Returns an array (NOT paginated) so the agent doesn't have to manage offset/limit loops manually. SAFETY: pass `max_items` to cap; without it, MP traversal is bounded by the toolkit's internal max (10,000 items) to prevent runaway iterations. USE WHEN the agent needs to enumerate everything (e.g., monthly reconciliation 'all approved payments in March'). For agent flows that only need 'first N matches', pass `max_items` directly.",
+  list_settlements_all: "Collect ALL settlements matching a filter \u2014 auto-paginates. Pass `max_items` to cap. Use for monthly bank-conciliation reports.",
+  // ── v0.11 — TaxID validation cross-LATAM (pure) ──────────────────────────
+  validate_tax_id: "PURE HELPER (no network, sub-ms) \u2014 validates a tax ID against the appropriate country algorithm. Supports AR (DNI/CUIT/CUIL with modulo-11), BR (CPF/CNPJ with two-step weighted modulo), MX (RFC structure), CL (RUT with K digit), CO (NIT modulo-11), UY (RUT 12-digit checksum), PE (RUC 11-digit + prefix validation). Returns { valid, normalized, formatted, type, country, error }. USE THIS BEFORE submitting buyer identification to MP \u2014 invalid tax IDs cause 4xx rejections. Surface the Spanish error verbatim."
 };
 function mercadoPagoTools(client, options) {
   const desc = (name) => options.descriptions?.[name] ?? DEFAULT_DESCRIPTIONS[name];
@@ -2529,7 +3249,45 @@ function mercadoPagoTools(client, options) {
           type: zod.z.enum(["DNI", "CUIT", "CUIL"]),
           number: zod.z.string()
         }).optional().describe("Payer identification \u2014 required for some payment types in AR"),
-        statement_descriptor: zod.z.string().max(13).optional().describe("Shows on buyer's card statement (max 13 chars)")
+        statement_descriptor: zod.z.string().max(13).optional().describe("Shows on buyer's card statement (max 13 chars)"),
+        // v0.11 — fraud scoring enrichment fields
+        additional_info: zod.z.object({
+          ip_address: zod.z.string().optional().describe(
+            "Buyer's IP address (from req.headers X-Forwarded-For). STRONGLY RECOMMENDED for card payments \u2014 improves MP fraud scoring confidence and reduces false-positive rejections (3-5x lower per RG 5286/2023)."
+          ),
+          referral_url: zod.z.string().url().optional().describe("Page the buyer came from"),
+          payer: zod.z.object({
+            first_name: zod.z.string().optional(),
+            last_name: zod.z.string().optional(),
+            phone: zod.z.object({ area_code: zod.z.string().optional(), number: zod.z.string().optional() }).optional(),
+            address: zod.z.object({
+              zip_code: zod.z.string().optional(),
+              street_name: zod.z.string().optional(),
+              street_number: zod.z.number().optional()
+            }).optional(),
+            registration_date: zod.z.string().optional().describe("ISO 8601 \u2014 when the buyer registered on YOUR platform"),
+            authentication_type: zod.z.string().optional(),
+            is_prime_user: zod.z.boolean().optional(),
+            is_first_purchase_online: zod.z.boolean().optional(),
+            last_purchase: zod.z.string().optional()
+          }).optional(),
+          shipments: zod.z.object({
+            receiver_address: zod.z.object({
+              zip_code: zod.z.string().optional(),
+              street_name: zod.z.string().optional(),
+              street_number: zod.z.number().optional(),
+              floor: zod.z.string().optional(),
+              apartment: zod.z.string().optional(),
+              city_name: zod.z.string().optional(),
+              state_name: zod.z.string().optional(),
+              country_name: zod.z.string().optional()
+            }).optional(),
+            express_shipment: zod.z.boolean().optional(),
+            local_pickup: zod.z.boolean().optional()
+          }).optional()
+        }).optional().describe(
+          "Fraud scoring enrichment. Pass IP address + payer profile + shipping address for materially better approval rates on card payments."
+        )
       }),
       execute: async (input) => {
         const payment = await client.createPayment({
@@ -2542,6 +3300,7 @@ function mercadoPagoTools(client, options) {
           ...input.external_reference !== void 0 ? { externalReference: input.external_reference } : {},
           ...input.identification !== void 0 ? { identification: input.identification } : {},
           ...input.statement_descriptor !== void 0 ? { statementDescriptor: input.statement_descriptor } : {},
+          ...input.additional_info !== void 0 ? { additionalInfo: input.additional_info } : {},
           ...options.notificationUrl !== void 0 ? { notificationUrl: options.notificationUrl } : {},
           // Deterministic idempotency key — safe to retry, same inputs always
           // produce the same key (MP dedupes on its side).
@@ -4200,6 +4959,129 @@ function mercadoPagoTools(client, options) {
           ...explanation
         };
       }
+    }),
+    // ─────────────────────────────────────────────────────────────────────
+    // v0.10 — AR issuer promos (pure)
+    // ─────────────────────────────────────────────────────────────────────
+    find_applicable_promos: ai.tool({
+      description: desc("find_applicable_promos"),
+      inputSchema: zod.z.object({
+        issuer: zod.z.string().optional().describe("Issuer name (e.g. 'Banco Galicia')"),
+        payment_method_id: zod.z.string().optional().describe("e.g. 'visa', 'master', 'naranja'"),
+        amount_ars: zod.z.number().positive().optional(),
+        category: zod.z.enum([
+          "electronics",
+          "appliances",
+          "clothing",
+          "supermarket",
+          "travel",
+          "education",
+          "health",
+          "general"
+        ]).optional(),
+        date: zod.z.string().datetime().optional(),
+        include_ahora_program: zod.z.boolean().optional()
+      }),
+      execute: async (input) => {
+        const args = {};
+        if (input.issuer !== void 0) args.issuer = input.issuer;
+        if (input.payment_method_id !== void 0) args.paymentMethodId = input.payment_method_id;
+        if (input.amount_ars !== void 0) args.amountArs = input.amount_ars;
+        if (input.category !== void 0) args.category = input.category;
+        if (input.date !== void 0) args.date = new Date(input.date);
+        if (input.include_ahora_program !== void 0) args.includeAhoraProgram = input.include_ahora_program;
+        const promos = findApplicablePromos(args);
+        return { ok: true, count: promos.length, promos };
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────
+    // v0.10 — 3DS challenge resolution (poll-and-confirm)
+    // ─────────────────────────────────────────────────────────────────────
+    confirm_3ds_challenge: ai.tool({
+      description: desc("confirm_3ds_challenge"),
+      inputSchema: zod.z.object({
+        payment_id: zod.z.string(),
+        max_attempts: zod.z.number().int().positive().max(20).optional(),
+        poll_interval_ms: zod.z.number().int().positive().max(1e4).optional()
+      }),
+      execute: async ({ payment_id, max_attempts, poll_interval_ms }) => {
+        const args = {};
+        if (max_attempts !== void 0) args.maxAttempts = max_attempts;
+        if (poll_interval_ms !== void 0) args.pollIntervalMs = poll_interval_ms;
+        return confirmChallengeAndPoll(client, payment_id, args);
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────
+    // v0.10 — Auto-paginate variants (collect-all)
+    // ─────────────────────────────────────────────────────────────────────
+    search_payments_all: ai.tool({
+      description: desc("search_payments_all"),
+      inputSchema: zod.z.object({
+        status: zod.z.string().optional(),
+        external_reference: zod.z.string().optional(),
+        from: zod.z.string().optional(),
+        to: zod.z.string().optional(),
+        max_items: zod.z.number().int().positive().max(1e4).optional().describe("Cap on total items returned (default 10,000 hard limit).")
+      }),
+      execute: async ({ max_items, ...filter }) => {
+        const filterClean = {};
+        for (const [k, v] of Object.entries(filter)) {
+          if (v !== void 0) filterClean[k] = v;
+        }
+        const opts = {};
+        if (max_items !== void 0) opts.maxItems = max_items;
+        else opts.maxItems = 1e4;
+        const all = await collect(paginatePayments(client, filterClean, opts));
+        return { ok: true, count: all.length, payments: all };
+      }
+    }),
+    list_settlements_all: ai.tool({
+      description: desc("list_settlements_all"),
+      inputSchema: zod.z.object({
+        from: zod.z.string().optional(),
+        to: zod.z.string().optional(),
+        status: zod.z.string().optional(),
+        max_items: zod.z.number().int().positive().max(1e4).optional()
+      }),
+      execute: async ({ max_items, ...filter }) => {
+        const filterClean = {};
+        if (filter.from !== void 0) filterClean.from = filter.from;
+        if (filter.to !== void 0) filterClean.to = filter.to;
+        if (filter.status !== void 0) filterClean.status = filter.status;
+        const opts = {};
+        if (max_items !== void 0) opts.maxItems = max_items;
+        else opts.maxItems = 1e4;
+        const all = await collect(paginateSettlements(client, filterClean, opts));
+        return { ok: true, count: all.length, settlements: all };
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────
+    // v0.11 — TaxID validation cross-LATAM (pure)
+    // ─────────────────────────────────────────────────────────────────────
+    validate_tax_id: ai.tool({
+      description: desc("validate_tax_id"),
+      inputSchema: zod.z.object({
+        tax_id: zod.z.string().min(1).describe(
+          "The tax ID to validate. Accepts any format with or without separators (20-41758101-5, 20.41758101.5, 20417581015 all work for AR CUIT)."
+        ),
+        type: zod.z.enum([
+          "DNI",
+          "CUIT",
+          "CUIL",
+          "CPF",
+          "CNPJ",
+          "RFC",
+          "RUT_CL",
+          "NIT",
+          "RUT_UY",
+          "RUC"
+        ]).describe(
+          "TaxID type. AR: DNI/CUIT/CUIL. BR: CPF (persona f\xEDsica) / CNPJ (persona jur\xEDdica). MX: RFC. CL: RUT_CL. CO: NIT. UY: RUT_UY. PE: RUC."
+        )
+      }),
+      execute: async ({ tax_id, type }) => {
+        return validateTaxId(tax_id, type);
+      }
     })
   };
 }
@@ -4422,8 +5304,417 @@ var CircuitBreaker = class {
   }
 };
 
+// src/audit.ts
+var InMemoryAuditLog = class {
+  entries = [];
+  async append(entry) {
+    this.entries.push(entry);
+  }
+  async query(filter) {
+    const filtered = this.entries.filter((e) => {
+      if (filter.actor && e.actor !== filter.actor) return false;
+      if (filter.operation && e.operation !== filter.operation) return false;
+      if (filter.tenantId && e.tenantId !== filter.tenantId) return false;
+      if (filter.from && e.timestamp < filter.from) return false;
+      if (filter.to && e.timestamp > filter.to) return false;
+      return true;
+    });
+    return filter.limit ? filtered.slice(0, filter.limit) : filtered;
+  }
+  /** All entries (test helper, not part of the adapter interface). */
+  all() {
+    return [...this.entries];
+  }
+  reset() {
+    this.entries.length = 0;
+  }
+};
+var AuditLogger = class {
+  adapter;
+  defaultActor;
+  redact;
+  hash;
+  constructor(options) {
+    this.adapter = options.adapter;
+    this.defaultActor = options.defaultActor ?? "unknown";
+    this.redact = options.redact ?? true;
+    this.hash = options.hashFn ?? defaultHasher;
+  }
+  /**
+   * Wrap a tool execute() function with auto-audit. The returned function:
+   * 1. Computes inputHash before the call.
+   * 2. Invokes the original execute().
+   * 3. On success, appends an entry with outcome="ok" + resourceId.
+   * 4. On failure, appends an entry with outcome="error" + errorCode/Message.
+   * 5. Re-throws the error transparently.
+   */
+  async record(args) {
+    const t0 = Date.now();
+    const inputHash = await this.hash(stableStringify(args.input));
+    try {
+      const result = await args.fn();
+      const resourceId = (args.extractResourceId ?? defaultExtractResourceId)(result);
+      const entry = {
+        id: `mpaud-${(/* @__PURE__ */ new Date()).toISOString()}-${Math.random().toString(36).slice(2, 10)}`,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        operation: args.operation,
+        actor: args.actor ?? this.defaultActor,
+        inputHash,
+        outcome: "ok",
+        durationMs: Date.now() - t0
+      };
+      if (args.tenantId !== void 0) entry.tenantId = args.tenantId;
+      if (resourceId !== void 0) entry.resourceId = resourceId;
+      if (args.idempotencyKey !== void 0) entry.idempotencyKey = args.idempotencyKey;
+      if (!this.redact) entry.inputRaw = args.input;
+      await this.adapter.append(entry);
+      return result;
+    } catch (err) {
+      const entry = {
+        id: `mpaud-${(/* @__PURE__ */ new Date()).toISOString()}-${Math.random().toString(36).slice(2, 10)}`,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        operation: args.operation,
+        actor: args.actor ?? this.defaultActor,
+        inputHash,
+        outcome: "error",
+        errorCode: extractErrorCode(err),
+        errorMessage: err instanceof Error ? err.message : String(err),
+        durationMs: Date.now() - t0
+      };
+      if (args.tenantId !== void 0) entry.tenantId = args.tenantId;
+      if (args.idempotencyKey !== void 0) entry.idempotencyKey = args.idempotencyKey;
+      if (!this.redact) entry.inputRaw = args.input;
+      await this.adapter.append(entry);
+      throw err;
+    }
+  }
+};
+async function defaultHasher(input) {
+  const { sha256Hex: sha256Hex2 } = await Promise.resolve().then(() => (init_crypto(), crypto_exports));
+  return sha256Hex2(input);
+}
+function stableStringify(obj) {
+  return JSON.stringify(obj, (_, v) => {
+    if (v && typeof v === "object" && !Array.isArray(v)) {
+      const sorted = {};
+      for (const k of Object.keys(v).sort()) {
+        sorted[k] = v[k];
+      }
+      return sorted;
+    }
+    return v;
+  });
+}
+function defaultExtractResourceId(result) {
+  if (!result || typeof result !== "object") return void 0;
+  const r = result;
+  for (const key of [
+    "id",
+    "payment_id",
+    "subscription_id",
+    "order_id",
+    "preference_id",
+    "customer_id",
+    "refund_id",
+    "store_id",
+    "pos_id",
+    "merchant_order_id",
+    "intent_id",
+    "device_id"
+  ]) {
+    const v = r[key];
+    if (typeof v === "string" || typeof v === "number") return String(v);
+  }
+  return void 0;
+}
+function extractErrorCode(err) {
+  if (err && typeof err === "object") {
+    const e = err;
+    return e.code ?? e.name ?? "unknown_error";
+  }
+  return "unknown_error";
+}
+
+// src/webhook-dedup.ts
+var WebhookDedup = class {
+  cache;
+  ttlSeconds;
+  onDuplicate;
+  constructor(opts) {
+    this.cache = opts.cache;
+    this.ttlSeconds = opts.ttlSeconds ?? 7 * 24 * 3600;
+    this.onDuplicate = opts.onDuplicate;
+  }
+  /**
+   * Check whether a webhook delivery has been seen before. If new, mark it
+   * as seen (so subsequent retries return shouldProcess=false). If seen,
+   * return shouldProcess=false WITHOUT marking again.
+   *
+   * **Important**: this method is not atomic across concurrent calls — two
+   * simultaneous deliveries with the same key may both pass shouldProcess=true.
+   * For strict at-most-once processing, follow with a transaction or use a
+   * cache that supports `setNX`-style semantics (Redis, Cloudflare KV with
+   * conditional writes).
+   *
+   * For most webhook handlers this race is acceptable: even if two get
+   * through, the downstream business logic (e.g., "charge if not already
+   * charged") will be idempotent on its own.
+   */
+  async check(args) {
+    const deliveryKey = this.deriveKey(args);
+    const seen = await this.cache.get(deliveryKey);
+    if (seen) {
+      this.onDuplicate?.(deliveryKey);
+      return { shouldProcess: false, deliveryKey };
+    }
+    await this.cache.set(deliveryKey, true, this.ttlSeconds);
+    return { shouldProcess: true, deliveryKey };
+  }
+  /**
+   * Manually mark a delivery as processed. Call this AFTER your business
+   * logic succeeds — useful when you want to control when the dedup
+   * marker is written (e.g., only on success).
+   *
+   * Combined with calling `check()` BEFORE the work, this gives "at-least-once"
+   * semantics: failed processing → no marker → retry will be processed again.
+   */
+  async markProcessed(args) {
+    const deliveryKey = this.deriveKey(args);
+    await this.cache.set(deliveryKey, true, this.ttlSeconds);
+  }
+  /**
+   * Variant of `check` that doesn't mark on first sight — caller must
+   * explicitly `markProcessed` when their business logic succeeds.
+   * Use this for at-least-once semantics (each delivery processed at
+   * least once, possibly more if processing fails before mark).
+   */
+  async peekIsDuplicate(args) {
+    const deliveryKey = this.deriveKey(args);
+    const seen = await this.cache.get(deliveryKey);
+    if (seen) this.onDuplicate?.(deliveryKey);
+    return { shouldProcess: !seen, deliveryKey };
+  }
+  deriveKey(args) {
+    return `mp:webhook:${args.topic}:${args.dataId}:${args.requestId ?? "noreqid"}`;
+  }
+};
+
+// src/rate-limiter.ts
+var RateLimitTimeoutError = class extends Error {
+  constructor(waitedMs) {
+    super(`Rate limit acquire timed out after ${waitedMs}ms.`);
+    this.waitedMs = waitedMs;
+    this.name = "RateLimitTimeoutError";
+  }
+  waitedMs;
+};
+var TokenBucketRateLimiter = class {
+  tokens;
+  lastRefill;
+  capacity;
+  refillPerSecond;
+  adaptive;
+  acquireTimeoutMs;
+  now;
+  constructor(opts = {}) {
+    this.capacity = opts.capacity ?? 50;
+    this.refillPerSecond = opts.refillPerSecond ?? 25;
+    this.adaptive = opts.adaptive ?? true;
+    this.acquireTimeoutMs = opts.acquireTimeoutMs ?? 3e4;
+    this.now = opts.now ?? Date.now;
+    this.tokens = this.capacity;
+    this.lastRefill = this.now();
+  }
+  /**
+   * Acquire a token. Resolves immediately if tokens are available;
+   * otherwise waits until one is. Rejects with `RateLimitTimeoutError`
+   * if the wait exceeds `acquireTimeoutMs`.
+   */
+  async acquire() {
+    this.refill();
+    if (this.tokens >= 1) {
+      this.tokens -= 1;
+      return;
+    }
+    const tokensNeeded = 1 - this.tokens;
+    const waitMs = Math.ceil(tokensNeeded / this.refillPerSecond * 1e3);
+    if (waitMs > this.acquireTimeoutMs) {
+      throw new RateLimitTimeoutError(waitMs);
+    }
+    await sleep2(waitMs);
+    this.refill();
+    this.tokens -= 1;
+  }
+  /**
+   * Best-effort acquire: returns true if a token was available, false
+   * otherwise. Doesn't wait. Useful for "non-blocking" code paths that
+   * want to fall back to a cached response or queue the request elsewhere.
+   */
+  tryAcquire() {
+    this.refill();
+    if (this.tokens >= 1) {
+      this.tokens -= 1;
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Adaptive learning hook — call after every API response with MP's
+   * rate-limit headers to keep the bucket in sync with reality.
+   */
+  learnFromHeaders(headers) {
+    if (!this.adaptive) return;
+    if (headers.remaining === null) return;
+    this.refill();
+    if (headers.remaining < this.tokens) {
+      this.tokens = Math.max(0, headers.remaining);
+    }
+  }
+  /** Inspect the current bucket state. */
+  getStats() {
+    this.refill();
+    return {
+      tokens: this.tokens,
+      capacity: this.capacity,
+      refillPerSecond: this.refillPerSecond
+    };
+  }
+  refill() {
+    const now = this.now();
+    const elapsedMs = now - this.lastRefill;
+    if (elapsedMs <= 0) return;
+    const refilled = elapsedMs / 1e3 * this.refillPerSecond;
+    this.tokens = Math.min(this.capacity, this.tokens + refilled);
+    this.lastRefill = now;
+  }
+};
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/middleware.ts
+function compose(...middlewares) {
+  return (tool2) => {
+    return middlewares.reduceRight((wrapped, mw) => mw(wrapped), tool2);
+  };
+}
+function withAuditLog(logger, operation, actor) {
+  return (tool2) => {
+    const original = tool2.execute;
+    if (!original) return tool2;
+    return {
+      ...tool2,
+      execute: (async (input, opts) => {
+        return logger.record({
+          operation,
+          input,
+          ...actor !== void 0 ? { actor } : {},
+          fn: () => original(input, opts)
+        });
+      })
+    };
+  };
+}
+function withRateLimit(limiter) {
+  return (tool2) => {
+    const original = tool2.execute;
+    if (!original) return tool2;
+    return {
+      ...tool2,
+      execute: (async (input, opts) => {
+        await limiter.acquire();
+        return original(input, opts);
+      })
+    };
+  };
+}
+function withMetrics(toolName, hook) {
+  return (tool2) => {
+    const original = tool2.execute;
+    if (!original) return tool2;
+    return {
+      ...tool2,
+      execute: (async (input, opts) => {
+        const t0 = Date.now();
+        try {
+          const result = await original(input, opts);
+          hook.onMetric({
+            toolName,
+            durationMs: Date.now() - t0,
+            success: true
+          });
+          return result;
+        } catch (err) {
+          hook.onMetric({
+            toolName,
+            durationMs: Date.now() - t0,
+            success: false,
+            errorCode: extractErrorCode2(err)
+          });
+          throw err;
+        }
+      })
+    };
+  };
+}
+var defaultShouldRetry = (err) => {
+  if (err && typeof err === "object" && "status" in err) {
+    const status = err.status;
+    if (typeof status === "number" && status >= 400 && status < 500) {
+      return false;
+    }
+  }
+  return true;
+};
+function withRetry(opts = {}) {
+  const maxAttempts = opts.maxAttempts ?? 3;
+  const baseBackoff = opts.baseBackoffMs ?? 250;
+  const shouldRetry = opts.shouldRetry ?? defaultShouldRetry;
+  return (tool2) => {
+    const original = tool2.execute;
+    if (!original) return tool2;
+    return {
+      ...tool2,
+      execute: (async (input, opts2) => {
+        let attempt = 0;
+        while (true) {
+          try {
+            return await original(input, opts2);
+          } catch (err) {
+            attempt++;
+            if (attempt >= maxAttempts || !shouldRetry(err, attempt)) {
+              throw err;
+            }
+            const delayMs = baseBackoff * Math.pow(2, attempt - 1);
+            opts.onRetry?.({ attempt, error: err, delayMs });
+            await new Promise((r) => setTimeout(r, delayMs));
+          }
+        }
+      })
+    };
+  };
+}
+function applyToAllTools(tools, middleware) {
+  const out = {};
+  for (const [name, tool2] of Object.entries(tools)) {
+    out[name] = middleware(tool2);
+  }
+  return out;
+}
+function extractErrorCode2(err) {
+  if (err && typeof err === "object") {
+    const e = err;
+    return e.code ?? e.name ?? "unknown_error";
+  }
+  return "unknown_error";
+}
+
+exports.AHORA_PROGRAM_PROMOS = AHORA_PROGRAM_PROMOS;
+exports.AR_ISSUER_PROMOS = AR_ISSUER_PROMOS;
+exports.AuditLogger = AuditLogger;
 exports.CircuitBreaker = CircuitBreaker;
 exports.CircuitOpenError = CircuitOpenError;
+exports.InMemoryAuditLog = InMemoryAuditLog;
 exports.InMemoryIdempotencyCache = InMemoryIdempotencyCache;
 exports.InMemoryOAuthTokenStore = InMemoryOAuthTokenStore;
 exports.InMemoryStateAdapter = InMemoryStateAdapter;
@@ -4438,20 +5729,42 @@ exports.MercadoPagoPaymentRejectedError = MercadoPagoPaymentRejectedError;
 exports.MercadoPagoRateLimitError = MercadoPagoRateLimitError;
 exports.MercadoPagoSelfPaymentError = MercadoPagoSelfPaymentError;
 exports.MercadoPagoTimeoutError = MercadoPagoTimeoutError;
+exports.RateLimitTimeoutError = RateLimitTimeoutError;
 exports.TEST_CARDS_AR = TEST_CARDS_AR;
 exports.TEST_PAYERS_AR = TEST_PAYERS_AR;
+exports.TokenBucketRateLimiter = TokenBucketRateLimiter;
+exports.WebhookDedup = WebhookDedup;
 exports.analyze3DS = analyze3DS;
+exports.applyToAllTools = applyToAllTools;
 exports.buildAuthorizeUrl = buildAuthorizeUrl;
 exports.buildTestCardScenario = buildTestCardScenario;
 exports.classifyError = classifyError;
+exports.collect = collect;
+exports.compose = compose;
 exports.computeMarketplaceFee = computeMarketplaceFee;
+exports.confirmChallengeAndPoll = confirmChallengeAndPoll;
+exports.detectAndValidate = detectAndValidate;
 exports.exchangeCodeForToken = exchangeCodeForToken;
 exports.expirationTimeMs = expirationTimeMs;
 exports.explainPaymentStatus = explainPaymentStatus;
+exports.findApplicablePromos = findApplicablePromos;
 exports.isExpiringSoon = isExpiringSoon;
 exports.mercadoPagoTools = mercadoPagoTools;
+exports.paginate = paginate;
+exports.paginateAccountMovements = paginateAccountMovements;
+exports.paginateMerchantOrders = paginateMerchantOrders;
+exports.paginatePayments = paginatePayments;
+exports.paginateSettlements = paginateSettlements;
+exports.paginateSubscriptionPayments = paginateSubscriptionPayments;
+exports.paginateSubscriptionPlans = paginateSubscriptionPlans;
+exports.paginateSubscriptions = paginateSubscriptions;
 exports.parseWebhookEvent = parseWebhookEvent;
 exports.refreshAccessToken = refreshAccessToken;
+exports.validateTaxId = validateTaxId;
 exports.verifyWebhookSignature = verifyWebhookSignature;
+exports.withAuditLog = withAuditLog;
+exports.withMetrics = withMetrics;
+exports.withRateLimit = withRateLimit;
+exports.withRetry = withRetry;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map