@ar-agents/mercadopago 0.8.0 → 0.10.0

package/dist/index.js

@@ -1,6 +1,75 @@
 import { tool } from 'ai';
 import { z } from '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) {
@@ -164,6 +233,8 @@ var MercadoPagoClient = class {
   requestTimeoutMs;
   maxRetries;
   onCall;
+  circuitBreaker;
+  traceContext;
   constructor(options) {
     if (!options.accessToken) {
       throw new Error(
@@ -176,8 +247,24 @@ var MercadoPagoClient = class {
     this.requestTimeoutMs = options.requestTimeoutMs ?? 3e4;
     this.maxRetries = Math.max(0, options.maxRetries ?? 1);
     this.onCall = options.onCall;
+    this.circuitBreaker = options.circuitBreaker;
+    this.traceContext = options.traceContext;
+  }
+  /**
+   * v0.9 — Inspect the circuit breaker state (when configured). Returns
+   * `null` when no circuit breaker is wired. Useful for health checks.
+   */
+  getCircuitState() {
+    return this.circuitBreaker?.getStats() ?? null;
   }
   async request(method, path, body, options) {
+    const exec = () => this.requestUnprotected(method, path, body, options);
+    if (this.circuitBreaker) {
+      return this.circuitBreaker.execute(exec);
+    }
+    return exec();
+  }
+  async requestUnprotected(method, path, body, options) {
     const headers = {
       Authorization: `Bearer ${this.accessToken}`,
       "Content-Type": "application/json"
@@ -185,6 +272,11 @@ var MercadoPagoClient = class {
     if (options?.idempotencyKey) {
       headers["X-Idempotency-Key"] = options.idempotencyKey;
     }
+    const trace = this.traceContext?.();
+    if (trace?.traceId && trace?.spanId) {
+      const flags = (trace.traceFlags ?? 1).toString(16).padStart(2, "0");
+      headers["traceparent"] = `00-${trace.traceId}-${trace.spanId}-${flags}`;
+    }
     let url = `${this.baseUrl}${path}`;
     if (options?.query) {
       const search = new URLSearchParams();
@@ -201,24 +293,54 @@ var MercadoPagoClient = class {
     let attempt = 0;
     let lastError;
     let lastStatus = null;
+    const fireOnCall = (event) => {
+      const traceCtx = trace?.traceId ? {
+        traceId: trace.traceId,
+        ...trace.spanId !== void 0 ? { spanId: trace.spanId } : {}
+      } : void 0;
+      this.onCall?.({
+        method,
+        path,
+        durationMs: Date.now() - t0,
+        ...event,
+        ...this.circuitBreaker ? { circuitState: this.circuitBreaker.getState() } : {},
+        ...traceCtx ? { traceContext: traceCtx } : {}
+      });
+    };
     while (attempt <= this.maxRetries) {
       const controller = new AbortController();
       const timer = setTimeout(() => controller.abort(), this.requestTimeoutMs);
+      const parentSignal = options?.signal;
+      const onParentAbort = () => controller.abort();
+      if (parentSignal) {
+        if (parentSignal.aborted) {
+          clearTimeout(timer);
+          throw new MercadoPagoTimeoutError(path, 0);
+        }
+        parentSignal.addEventListener("abort", onParentAbort, { once: true });
+      }
       const init = { method, headers, signal: controller.signal };
       if (body !== void 0) init.body = JSON.stringify(body);
       try {
         const res = await fetchFn(url, init);
         clearTimeout(timer);
+        if (parentSignal) parentSignal.removeEventListener("abort", onParentAbort);
         lastStatus = res.status;
+        const requestId = res.headers.get("x-request-id");
+        const rlRemaining = res.headers.get("x-rate-limit-remaining");
+        const rlReset = res.headers.get("x-rate-limit-reset");
+        const rateLimit = {
+          remaining: rlRemaining !== null ? Number(rlRemaining) : null,
+          resetSeconds: rlReset !== null ? Number(rlReset) : null
+        };
         if (res.ok) {
           const text2 = await res.text();
-          this.onCall?.({
-            method,
-            path,
-            durationMs: Date.now() - t0,
+          fireOnCall({
+            success: true,
             httpStatus: res.status,
             retried: attempt,
-            success: true
+            requestId,
+            rateLimit
           });
           if (!text2) return void 0;
           return JSON.parse(text2);
@@ -233,13 +355,12 @@ var MercadoPagoClient = class {
         }
         const contentType = res.headers.get("content-type") ?? "";
         if (res.status >= 500 && !contentType.includes("application/json")) {
-          this.onCall?.({
-            method,
-            path,
-            durationMs: Date.now() - t0,
+          fireOnCall({
+            success: false,
             httpStatus: res.status,
             retried: attempt,
-            success: false
+            requestId,
+            rateLimit
           });
           throw new MercadoPagoOverloadedError(path, res.status);
         }
@@ -251,33 +372,33 @@ var MercadoPagoClient = class {
           parsed = text;
         }
         const err = classifyError(res.status, path, parsed, options?.classifyContext);
-        this.onCall?.({
-          method,
-          path,
-          durationMs: Date.now() - t0,
+        fireOnCall({
+          success: false,
           httpStatus: res.status,
           retried: attempt,
-          success: false
+          requestId,
+          rateLimit
         });
         throw err;
       } catch (err) {
         clearTimeout(timer);
+        if (parentSignal) parentSignal.removeEventListener("abort", onParentAbort);
         if (err instanceof MercadoPagoError) throw err;
         const isAbort = err instanceof Error && err.name === "AbortError";
+        const isParentAbort = parentSignal?.aborted ?? false;
         const isNetwork = !lastStatus && !isAbort;
-        if ((isNetwork || isAbort) && attempt < this.maxRetries) {
+        if ((isNetwork || isAbort && !isParentAbort) && attempt < this.maxRetries) {
           lastError = err;
           attempt++;
           await sleep(250 * Math.pow(2, attempt - 1));
           continue;
         }
-        this.onCall?.({
-          method,
-          path,
-          durationMs: Date.now() - t0,
+        fireOnCall({
+          success: false,
           httpStatus: lastStatus,
           retried: attempt,
-          success: false
+          requestId: null,
+          rateLimit: { remaining: null, resetSeconds: null }
         });
         if (isAbort) {
           throw new MercadoPagoTimeoutError(path, this.requestTimeoutMs);
@@ -1231,55 +1352,57 @@ var MercadoPagoClient = class {
     );
     return { id: intentId, canceled: true };
   }
+  // ──────────────────────────────────────────────────────────────────────────
+  // v0.9 — Health check
+  //
+  // No dedicated ping endpoint exists in MP's public API. We use `getMe()`
+  // (`/users/me`) as a lightweight liveness probe — it requires only a valid
+  // accessToken, returns ~200 bytes of JSON, and is the same call MP's own
+  // dashboard makes on startup. A successful response proves: (a) network
+  // path to MP is up, (b) accessToken is valid, (c) MP is responding.
+  // ──────────────────────────────────────────────────────────────────────────
+  /**
+   * Liveness probe against MP. Returns latency + circuit-breaker state.
+   * Use as a /health endpoint for k8s, Vercel cron, or status-page checks.
+   *
+   * Returns `{ ok: false, ... }` instead of throwing — designed for
+   * monitoring loops that want to keep running.
+   *
+   * @param signal Optional AbortSignal to cap wait time (e.g., 2s for
+   *               status-page polling).
+   */
+  async healthCheck(signal) {
+    const t0 = Date.now();
+    const circuitBefore = this.circuitBreaker?.getStats() ?? null;
+    try {
+      const me = await this.request(
+        "GET",
+        "/users/me",
+        void 0,
+        signal ? { signal } : {}
+      );
+      return {
+        ok: true,
+        latencyMs: Date.now() - t0,
+        userId: String(me.id),
+        error: null,
+        circuit: this.circuitBreaker?.getStats() ?? null
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        ok: false,
+        latencyMs: Date.now() - t0,
+        userId: null,
+        error: message,
+        circuit: this.circuitBreaker?.getStats() ?? circuitBefore
+      };
+    }
+  }
 };
 
-// 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();
 z.enum(["MLA", "MLB", "MLM", "MCO", "MLC", "MLU"]);
 var CurrencyIdSchema = z.enum(["ARS", "USD", "BRL", "MXN"]);
 var FrequencyTypeSchema = z.enum(["months", "days"]);
@@ -1783,6 +1906,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;
@@ -2020,6 +2317,116 @@ 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/test-cards.ts
 var TEST_CARDS_AR = {
   VISA_CREDIT: {
@@ -2147,8 +2554,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 : {};
@@ -2298,7 +2737,16 @@ var DEFAULT_DESCRIPTIONS = {
   cancel_point_payment_intent: "Cancel an OPEN point payment intent before the buyer interacts with the device. ONLY WORKS while state='OPEN' \u2014 once the buyer taps, you can't cancel; refund_payment after the fact instead.",
   // ── Pure helpers (v0.7) ──────────────────────────────────────────────────
   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."
+  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.",
+  // ── 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."
 };
 function mercadoPagoTools(client, options) {
   const desc = (name) => options.descriptions?.[name] ?? DEFAULT_DESCRIPTIONS[name];
@@ -4056,6 +4504,21 @@ function mercadoPagoTools(client, options) {
         };
       }
     }),
+    mp_health_check: tool({
+      description: desc("mp_health_check"),
+      inputSchema: z.object({
+        timeout_ms: z.number().int().positive().max(3e4).optional().describe("Cap the wait time (default 5s). Use lower for status-page polling.")
+      }),
+      execute: async ({ timeout_ms }) => {
+        const controller = new AbortController();
+        const t = setTimeout(() => controller.abort(), timeout_ms ?? 5e3);
+        try {
+          return await client.healthCheck(controller.signal);
+        } finally {
+          clearTimeout(t);
+        }
+      }
+    }),
     explain_payment_status: tool({
       description: desc("explain_payment_status"),
       inputSchema: z.object({
@@ -4082,6 +4545,101 @@ function mercadoPagoTools(client, options) {
           ...explanation
         };
       }
+    }),
+    // ─────────────────────────────────────────────────────────────────────
+    // v0.10 — AR issuer promos (pure)
+    // ─────────────────────────────────────────────────────────────────────
+    find_applicable_promos: tool({
+      description: desc("find_applicable_promos"),
+      inputSchema: z.object({
+        issuer: z.string().optional().describe("Issuer name (e.g. 'Banco Galicia')"),
+        payment_method_id: z.string().optional().describe("e.g. 'visa', 'master', 'naranja'"),
+        amount_ars: z.number().positive().optional(),
+        category: z.enum([
+          "electronics",
+          "appliances",
+          "clothing",
+          "supermarket",
+          "travel",
+          "education",
+          "health",
+          "general"
+        ]).optional(),
+        date: z.string().datetime().optional(),
+        include_ahora_program: 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: tool({
+      description: desc("confirm_3ds_challenge"),
+      inputSchema: z.object({
+        payment_id: z.string(),
+        max_attempts: z.number().int().positive().max(20).optional(),
+        poll_interval_ms: 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: tool({
+      description: desc("search_payments_all"),
+      inputSchema: z.object({
+        status: z.string().optional(),
+        external_reference: z.string().optional(),
+        from: z.string().optional(),
+        to: z.string().optional(),
+        max_items: 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: tool({
+      description: desc("list_settlements_all"),
+      inputSchema: z.object({
+        from: z.string().optional(),
+        to: z.string().optional(),
+        status: z.string().optional(),
+        max_items: 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 };
+      }
     })
   };
 }
@@ -4146,6 +4704,452 @@ var InMemoryIdempotencyCache = class {
   }
 };
 
-export { InMemoryIdempotencyCache, InMemoryOAuthTokenStore, InMemoryStateAdapter, MercadoPagoAccountTypeMismatchError, MercadoPagoAuthError, MercadoPagoAuthorizeForbiddenError, MercadoPagoBackUrlInvalidError, MercadoPagoClient, MercadoPagoError, MercadoPagoOverloadedError, MercadoPagoPaymentRejectedError, MercadoPagoRateLimitError, MercadoPagoSelfPaymentError, MercadoPagoTimeoutError, TEST_CARDS_AR, TEST_PAYERS_AR, analyze3DS, buildAuthorizeUrl, buildTestCardScenario, classifyError, computeMarketplaceFee, exchangeCodeForToken, expirationTimeMs, explainPaymentStatus, isExpiringSoon, mercadoPagoTools, parseWebhookEvent, refreshAccessToken, verifyWebhookSignature };
+// src/circuit-breaker.ts
+var CircuitOpenError = class extends Error {
+  constructor(retryAfterMs, consecutiveFailures) {
+    super(
+      `Circuit breaker is OPEN \u2014 failing fast. Retry in ${Math.ceil(
+        retryAfterMs / 1e3
+      )}s. Consecutive upstream failures: ${consecutiveFailures}.`
+    );
+    this.retryAfterMs = retryAfterMs;
+    this.consecutiveFailures = consecutiveFailures;
+    this.name = "CircuitOpenError";
+  }
+  retryAfterMs;
+  consecutiveFailures;
+};
+var CircuitBreaker = class {
+  state = "CLOSED";
+  consecutiveFailures = 0;
+  halfOpenSuccesses = 0;
+  openedAt = 0;
+  /** Timestamps of failures within the monitoring window. */
+  failureWindow = [];
+  failureThreshold;
+  successThreshold;
+  resetTimeoutMs;
+  monitoringWindowMs;
+  onStateChange;
+  isFailureFn;
+  now;
+  constructor(opts = {}) {
+    this.failureThreshold = opts.failureThreshold ?? 5;
+    this.successThreshold = opts.successThreshold ?? 2;
+    this.resetTimeoutMs = opts.resetTimeoutMs ?? 3e4;
+    this.monitoringWindowMs = opts.monitoringWindowMs ?? 6e4;
+    this.onStateChange = opts.onStateChange ?? null;
+    this.isFailureFn = opts.isFailure ?? (() => true);
+    this.now = opts.now ?? Date.now;
+  }
+  /** Read the current state. Useful for health checks + metrics. */
+  getState() {
+    if (this.state === "OPEN" && this.now() - this.openedAt >= this.resetTimeoutMs) {
+      this.transitionTo("HALF_OPEN");
+    }
+    return this.state;
+  }
+  /** Read diagnostic state for health checks + dashboards. */
+  getStats() {
+    const state = this.getState();
+    const msSinceOpened = this.openedAt > 0 ? this.now() - this.openedAt : null;
+    const msUntilHalfOpen = state === "OPEN" && msSinceOpened !== null ? Math.max(0, this.resetTimeoutMs - msSinceOpened) : null;
+    return {
+      state,
+      consecutiveFailures: this.consecutiveFailures,
+      failuresInWindow: this.failuresInCurrentWindow(),
+      msSinceOpened,
+      msUntilHalfOpen
+    };
+  }
+  /**
+   * Execute `fn` under the breaker's protection.
+   * - If the breaker is OPEN, throws `CircuitOpenError` immediately.
+   * - If `fn` succeeds, may transition HALF_OPEN → CLOSED.
+   * - If `fn` fails (and the error counts as a failure), records the
+   *   failure; may transition CLOSED → OPEN or HALF_OPEN → OPEN.
+   */
+  async execute(fn) {
+    const state = this.getState();
+    if (state === "OPEN") {
+      const elapsed = this.now() - this.openedAt;
+      throw new CircuitOpenError(
+        Math.max(0, this.resetTimeoutMs - elapsed),
+        this.consecutiveFailures
+      );
+    }
+    try {
+      const result = await fn();
+      this.recordSuccess();
+      return result;
+    } catch (err) {
+      if (this.isFailureFn(err)) {
+        this.recordFailure(err);
+      }
+      throw err;
+    }
+  }
+  /** Manually force the breaker open. Useful for runbook / manual ops. */
+  trip(reason) {
+    if (this.state !== "OPEN") {
+      this.transitionTo("OPEN", reason);
+    }
+  }
+  /** Manually reset the breaker to CLOSED. */
+  reset() {
+    this.consecutiveFailures = 0;
+    this.halfOpenSuccesses = 0;
+    this.failureWindow = [];
+    if (this.state !== "CLOSED") {
+      this.transitionTo("CLOSED");
+    }
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Internal
+  // ─────────────────────────────────────────────────────────────────────────
+  recordSuccess() {
+    this.consecutiveFailures = 0;
+    if (this.state === "HALF_OPEN") {
+      this.halfOpenSuccesses++;
+      if (this.halfOpenSuccesses >= this.successThreshold) {
+        this.transitionTo("CLOSED");
+      }
+    }
+  }
+  recordFailure(cause) {
+    this.consecutiveFailures++;
+    this.failureWindow.push(this.now());
+    this.pruneWindow();
+    if (this.state === "HALF_OPEN") {
+      this.transitionTo("OPEN", cause);
+      return;
+    }
+    if (this.state === "CLOSED" && this.failuresInCurrentWindow() >= this.failureThreshold) {
+      this.transitionTo("OPEN", cause);
+    }
+  }
+  transitionTo(to, cause) {
+    const from = this.state;
+    if (from === to) return;
+    this.state = to;
+    if (to === "OPEN") {
+      this.openedAt = this.now();
+      this.halfOpenSuccesses = 0;
+    } else if (to === "CLOSED") {
+      this.consecutiveFailures = 0;
+      this.halfOpenSuccesses = 0;
+      this.failureWindow = [];
+      this.openedAt = 0;
+    } else if (to === "HALF_OPEN") {
+      this.halfOpenSuccesses = 0;
+    }
+    this.onStateChange?.({
+      from,
+      to,
+      cause,
+      consecutiveFailures: this.consecutiveFailures
+    });
+  }
+  pruneWindow() {
+    const cutoff = this.now() - this.monitoringWindowMs;
+    while (this.failureWindow.length > 0 && this.failureWindow[0] < cutoff) {
+      this.failureWindow.shift();
+    }
+  }
+  failuresInCurrentWindow() {
+    this.pruneWindow();
+    return this.failureWindow.length;
+  }
+};
+
+// 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));
+}
+
+export { AHORA_PROGRAM_PROMOS, AR_ISSUER_PROMOS, AuditLogger, CircuitBreaker, CircuitOpenError, InMemoryAuditLog, InMemoryIdempotencyCache, InMemoryOAuthTokenStore, InMemoryStateAdapter, MercadoPagoAccountTypeMismatchError, MercadoPagoAuthError, MercadoPagoAuthorizeForbiddenError, MercadoPagoBackUrlInvalidError, MercadoPagoClient, MercadoPagoError, MercadoPagoOverloadedError, MercadoPagoPaymentRejectedError, MercadoPagoRateLimitError, MercadoPagoSelfPaymentError, MercadoPagoTimeoutError, RateLimitTimeoutError, TEST_CARDS_AR, TEST_PAYERS_AR, TokenBucketRateLimiter, WebhookDedup, analyze3DS, buildAuthorizeUrl, buildTestCardScenario, classifyError, collect, computeMarketplaceFee, confirmChallengeAndPoll, exchangeCodeForToken, expirationTimeMs, explainPaymentStatus, findApplicablePromos, isExpiringSoon, mercadoPagoTools, paginate, paginateAccountMovements, paginateMerchantOrders, paginatePayments, paginateSettlements, paginateSubscriptionPayments, paginateSubscriptionPlans, paginateSubscriptions, parseWebhookEvent, refreshAccessToken, verifyWebhookSignature };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map