@ar-agents/mercadopago 0.9.0 → 0.10.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
+import { I as IdempotencyCache, S as SubscriptionStateAdapter } from './state-C6Wzb_XX.cjs';
+export { a as InMemoryIdempotencyCache, b as InMemoryOAuthTokenStore, c as InMemoryStateAdapter, O as OAuthTokenRecord, d as OAuthTokenStore, e as SubscriptionStateRecord } from './state-C6Wzb_XX.cjs';
 import { ToolSet } from 'ai';
-import { S as SubscriptionStateAdapter } from './state-C6Wzb_XX.cjs';
-export { I as IdempotencyCache, a as InMemoryIdempotencyCache, b as InMemoryOAuthTokenStore, c as InMemoryStateAdapter, O as OAuthTokenRecord, d as OAuthTokenStore, e as SubscriptionStateRecord } from './state-C6Wzb_XX.cjs';
 
 /**
  * Circuit breaker — protects your app from cascading failures when MP
@@ -1876,6 +1876,338 @@ declare class MercadoPagoClient {
     }>;
 }
 
+/**
+ * Webhook idempotency / dedup — short-circuits duplicate webhook deliveries
+ * from MP to prevent double-processing.
+ *
+ * # The problem
+ *
+ * MP retries webhook deliveries on 5xx responses. The retry policy is
+ * exponential backoff: 5min, 15min, 30min, 1h, 6h, 24h, 48h, 96h, 192h
+ * (~12 attempts over 8 days). If your handler temporarily 5xx'd (DB
+ * down, deploy in progress, etc.) and then recovered, you'll receive
+ * the SAME webhook 5+ times. Without dedup:
+ *
+ * - You double-charge (if the webhook triggers a charge)
+ * - You double-send notifications (5 emails to the buyer instead of 1)
+ * - You double-create downstream resources
+ *
+ * # The fix
+ *
+ * Cache the unique "delivery key" of every webhook you've successfully
+ * processed. On retry, recognize the key, return 200 immediately, skip
+ * processing.
+ *
+ * # The "delivery key"
+ *
+ * MP doesn't ship a single canonical id per delivery, but the tuple
+ * `${topic}:${dataId}:${requestId}` is stable for retries (same delivery
+ * attempt → same x-request-id) and unique enough to dedupe.
+ *
+ * # Storage
+ *
+ * Reuse `IdempotencyCache` from `state.ts`. Default TTL: 7 days (matches
+ * MP's webhook retry window). Override per-deployment.
+ */
+
+interface WebhookDedupOptions {
+    /**
+     * Storage for processed webhook ids. Plug in `VercelKVIdempotencyCache`
+     * for production or `InMemoryIdempotencyCache` for tests.
+     */
+    cache: IdempotencyCache;
+    /**
+     * Time-to-live for dedup entries (seconds). Default 7 days — covers MP's
+     * full retry window (~8 days) with a safety margin.
+     */
+    ttlSeconds?: number;
+    /**
+     * Optional callback fired when a duplicate is detected. Useful for
+     * metrics ("webhooks deduped" counter).
+     */
+    onDuplicate?: (deliveryKey: string) => void;
+}
+interface DedupResult {
+    /**
+     * `true` if this is the first time we've seen this delivery — caller
+     * should process it.
+     * `false` if it's a retry of a previously-seen delivery — caller should
+     * acknowledge with 200 and skip processing.
+     */
+    shouldProcess: boolean;
+    /** The deduplication key derived from the webhook. */
+    deliveryKey: string;
+}
+/**
+ * Dedup helper. Use this BEFORE processing a webhook to short-circuit retries.
+ *
+ * @example
+ * ```ts
+ * import { WebhookDedup, VercelKVIdempotencyCache } from "@ar-agents/mercadopago";
+ *
+ * const dedup = new WebhookDedup({
+ *   cache: new VercelKVIdempotencyCache(),
+ *   onDuplicate: (key) => metrics.increment("mp.webhook.duplicate"),
+ * });
+ *
+ * export async function POST(req: Request) {
+ *   const event = parseWebhookEvent(...);
+ *   if (!event) return new Response("bad request", { status: 400 });
+ *
+ *   const requestId = req.headers.get("x-request-id");
+ *   const { shouldProcess } = await dedup.check({
+ *     topic: event.topic,
+ *     dataId: event.dataId,
+ *     requestId,
+ *   });
+ *   if (!shouldProcess) return new Response("ok (duplicate)", { status: 200 });
+ *
+ *   // ... process the webhook ...
+ *
+ *   return new Response("ok", { status: 200 });
+ * }
+ * ```
+ */
+declare class WebhookDedup {
+    private readonly cache;
+    private readonly ttlSeconds;
+    private readonly onDuplicate;
+    constructor(opts: WebhookDedupOptions);
+    /**
+     * 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.
+     */
+    check(args: {
+        topic: string;
+        dataId: string;
+        requestId: string | null;
+    }): Promise<DedupResult>;
+    /**
+     * 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.
+     */
+    markProcessed(args: {
+        topic: string;
+        dataId: string;
+        requestId: string | null;
+    }): Promise<void>;
+    /**
+     * 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).
+     */
+    peekIsDuplicate(args: {
+        topic: string;
+        dataId: string;
+        requestId: string | null;
+    }): Promise<DedupResult>;
+    private deriveKey;
+}
+
+/**
+ * Compute SHA-256 hash of `input`. Returns the full 64-char hex digest.
+ *
+ * Used for deterministic idempotency keys derived from caller-meaningful
+ * fields. Truncate the output to 32 chars for storage if needed.
+ */
+declare function sha256Hex(input: string): Promise<string>;
+
+/**
+ * Audit logging — financial-grade compliance trail for every state-mutating
+ * operation. Captures who/what/when/idempotency_key/before/after/result.
+ *
+ * # Why this is a tier-1 feature
+ *
+ * Every mature payment integration has an audit log. The compliance officer
+ * asks "show me every refund issued in March 2026 by user X" and you need
+ * to answer in <60 seconds. Without an audit log, you're trawling through
+ * application logs hoping nothing was filtered out.
+ *
+ * # What gets logged
+ *
+ * Every **state-mutating** tool call automatically:
+ * - `create_payment`, `charge_saved_card`, `cancel_payment`, `capture_payment`
+ * - `refund_payment`
+ * - `create_subscription`, `cancel/pause/resume_subscription`, `update_subscription`
+ * - `create_order`, `capture_order`, `cancel_order`
+ * - `create_payment_preference`, `update_payment_preference`
+ * - `create_customer`, `update_customer`, `create_customer_card`, `delete_customer_card`
+ * - `create_subscription_plan`, `update_subscription_plan`
+ * - `create_store/pos`, `update_store/pos`, `delete_store/pos`
+ * - `create_qr_payment`, `cancel_qr_payment`
+ * - `create_point_payment_intent`, `cancel_point_payment_intent`, `update_point_device_mode`
+ * - OAuth: `oauth_exchange_code`, `oauth_refresh_token`
+ * - `register_bank_account`
+ * - `create_webhook`, `update_webhook`, `delete_webhook`
+ *
+ * **Read-only** tools do NOT emit audit entries (would flood the log without
+ * value): get_*, search_*, list_*, calculate_*, validate_*, lookup_*, analyze_*.
+ *
+ * # PII handling
+ *
+ * The audit log captures `inputSummary` (a deterministic hash of the input
+ * fields, NOT the raw input) by default. Configure `redact: false` to log
+ * raw inputs (payer email, CUIT, etc.) — only when your data-residency
+ * policy permits.
+ *
+ * # Storage
+ *
+ * Pluggable adapter pattern. Ships:
+ * - `InMemoryAuditLog` — for tests + single-process demos.
+ * - `VercelKVAuditLog` (in `/vercel-kv` subpath) — production-ready, KV-backed
+ *   with daily-bucket indexing for efficient time-range queries.
+ *
+ * Implement your own for Postgres / S3 / SIEM integration.
+ */
+
+type AuditOperation = "create_payment" | "charge_saved_card" | "cancel_payment" | "capture_payment" | "refund_payment" | "create_subscription" | "cancel_subscription" | "pause_subscription" | "resume_subscription" | "update_subscription" | "subscribe_to_plan" | "create_subscription_plan" | "update_subscription_plan" | "create_order" | "capture_order" | "cancel_order" | "update_order" | "create_payment_preference" | "update_payment_preference" | "create_customer" | "update_customer" | "create_customer_card" | "delete_customer_card" | "create_store" | "update_store" | "delete_store" | "create_pos" | "update_pos" | "delete_pos" | "create_qr_payment" | "cancel_qr_payment" | "create_point_payment_intent" | "cancel_point_payment_intent" | "update_point_device_mode" | "oauth_exchange_code" | "oauth_refresh_token" | "register_bank_account" | "create_webhook" | "update_webhook" | "delete_webhook" | (string & {});
+interface AuditEntry {
+    /**
+     * Unique entry id. Format: `mpaud-{ISO date}-{random}`. Use as primary
+     * key in your storage layer.
+     */
+    id: string;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+    /** The MP operation performed. */
+    operation: AuditOperation;
+    /**
+     * Logical actor that initiated the call. Caller-provided. Examples:
+     * `"agent:billing-bot"`, `"user:42"`, `"cron:daily-charge"`.
+     *
+     * Defaults to `"unknown"` when not provided. **Always pass this in
+     * production** — without it, your compliance trail is meaningless.
+     */
+    actor: string;
+    /** Optional tenant/seller id for multi-tenant marketplace setups. */
+    tenantId?: string;
+    /**
+     * SHA-256 hex of the meaningful input fields (deterministic). Useful as
+     * a join key with the IdempotencyCache. Does NOT contain raw PII.
+     */
+    inputHash: string;
+    /**
+     * Optional raw input — only populated when `redact: false` was configured.
+     * Defaults to undefined to comply with data-minimization principles.
+     */
+    inputRaw?: Record<string, unknown>;
+    /** Outcome: success or error code. */
+    outcome: "ok" | "error";
+    /** Error code when `outcome === "error"`. */
+    errorCode?: string;
+    /** Error message when `outcome === "error"`. */
+    errorMessage?: string;
+    /**
+     * MP resource id created/updated by the operation (e.g., payment id).
+     * Allows joining audit entries to the actual MP resource.
+     */
+    resourceId?: string;
+    /** Idempotency key passed to MP (for join with MP-side dedup logs). */
+    idempotencyKey?: string;
+    /** Duration in ms. */
+    durationMs?: number;
+    /** Free-form metadata bag. */
+    metadata?: Record<string, unknown>;
+}
+interface AuditLogAdapter {
+    append(entry: AuditEntry): Promise<void>;
+    /** Query a time range. Optional — implementations that don't support it can omit. */
+    query?(filter: {
+        actor?: string;
+        operation?: AuditOperation;
+        tenantId?: string;
+        from?: string;
+        to?: string;
+        limit?: number;
+    }): Promise<AuditEntry[]>;
+}
+/**
+ * Volatile, single-process audit log. Tests + dev only. Production deployments
+ * must use a durable adapter (`VercelKVAuditLog`, your Postgres/S3 impl, etc.)
+ */
+declare class InMemoryAuditLog implements AuditLogAdapter {
+    private readonly entries;
+    append(entry: AuditEntry): Promise<void>;
+    query(filter: {
+        actor?: string;
+        operation?: AuditOperation;
+        tenantId?: string;
+        from?: string;
+        to?: string;
+        limit?: number;
+    }): Promise<AuditEntry[]>;
+    /** All entries (test helper, not part of the adapter interface). */
+    all(): AuditEntry[];
+    reset(): void;
+}
+/**
+ * Audit logger — the user-facing facade that builds + ships entries.
+ *
+ * @example
+ * ```ts
+ * const audit = new AuditLogger({
+ *   adapter: new InMemoryAuditLog(),
+ *   defaultActor: "agent:billing-bot",
+ *   redact: true, // default — hashes input, no raw PII
+ * });
+ *
+ * const tools = mercadoPagoTools(client, {
+ *   state, backUrl, audit,
+ * });
+ * ```
+ */
+declare class AuditLogger {
+    private readonly adapter;
+    private readonly defaultActor;
+    private readonly redact;
+    private readonly hash;
+    constructor(options: {
+        adapter: AuditLogAdapter;
+        defaultActor?: string;
+        redact?: boolean;
+        /** Override hash (testing). */
+        hashFn?: typeof sha256Hex;
+    });
+    /**
+     * 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.
+     */
+    record<I, O>(args: {
+        operation: AuditOperation;
+        input: I;
+        actor?: string;
+        tenantId?: string;
+        idempotencyKey?: string;
+        /**
+         * Function that extracts the resourceId from the result. Default: tries
+         * `result.id`, `result.payment_id`, `result.subscription_id`, `result.order_id`.
+         */
+        extractResourceId?: (result: O) => string | undefined;
+        /** The actual operation to execute. */
+        fn: () => Promise<O>;
+    }): Promise<O>;
+}
+
 interface MercadoPagoToolsOptions {
     /** State adapter for persisting subscription records. */
     state: SubscriptionStateAdapter;
@@ -1913,8 +2245,26 @@ interface MercadoPagoToolsOptions {
         clientId: string;
         clientSecret: string;
     };
+    /**
+     * v0.10 — Audit logger. When passed, every state-mutating tool call
+     * automatically emits an audit entry with operation/actor/inputHash/
+     * resourceId/outcome/duration. Read-only tools (get/search/list) skip
+     * audit logging.
+     */
+    audit?: AuditLogger;
+    /**
+     * v0.10 — Logical actor for audit entries (e.g., "agent:billing-bot",
+     * "user:42"). Defaults to the AuditLogger's defaultActor.
+     */
+    auditActor?: string;
+    /**
+     * v0.10 — Webhook deduplication for handle_webhook tool. Caches
+     * processed (topic, dataId, requestId) tuples to short-circuit MP's
+     * retries (which fire on 5xx and can deliver the same event 5+ times).
+     */
+    webhookDedup?: WebhookDedup;
 }
-type ToolName = "create_subscription" | "get_subscription_status" | "cancel_subscription" | "pause_subscription" | "resume_subscription" | "create_payment" | "get_payment" | "search_payments" | "cancel_payment" | "capture_payment" | "refund_payment" | "list_refunds" | "create_payment_preference" | "get_payment_preference" | "create_customer" | "find_customer_by_email" | "list_customer_cards" | "delete_customer_card" | "list_payment_methods" | "calculate_installments" | "get_account_info" | "charge_saved_card" | "create_qr_payment" | "cancel_qr_payment" | "create_subscription_plan" | "list_subscription_plans" | "update_subscription_plan" | "subscribe_to_plan" | "list_subscription_payments" | "create_store" | "list_stores" | "create_pos" | "list_pos" | "list_payment_disputes" | "get_dispute" | "list_identification_types" | "list_issuers" | "list_webhooks" | "create_webhook" | "update_webhook" | "delete_webhook" | "handle_webhook" | "oauth_authorize_url" | "oauth_exchange_code" | "oauth_refresh_token" | "create_order" | "get_order" | "update_order" | "capture_order" | "cancel_order" | "get_account_balance" | "list_account_movements" | "list_settlements" | "get_settlement" | "analyze_payment_3ds" | "get_test_cards" | "get_customer" | "update_customer" | "create_customer_card" | "get_customer_card" | "get_subscription_plan" | "update_subscription" | "search_subscriptions" | "get_refund" | "update_payment_preference" | "get_merchant_order" | "search_merchant_orders" | "update_merchant_order" | "get_store" | "update_store" | "delete_store" | "get_pos" | "update_pos" | "delete_pos" | "list_bank_accounts" | "register_bank_account" | "list_point_devices" | "update_point_device_mode" | "create_point_payment_intent" | "get_point_payment_intent" | "cancel_point_payment_intent" | "compute_marketplace_fee" | "explain_payment_status" | "mp_health_check";
+type ToolName = "create_subscription" | "get_subscription_status" | "cancel_subscription" | "pause_subscription" | "resume_subscription" | "create_payment" | "get_payment" | "search_payments" | "cancel_payment" | "capture_payment" | "refund_payment" | "list_refunds" | "create_payment_preference" | "get_payment_preference" | "create_customer" | "find_customer_by_email" | "list_customer_cards" | "delete_customer_card" | "list_payment_methods" | "calculate_installments" | "get_account_info" | "charge_saved_card" | "create_qr_payment" | "cancel_qr_payment" | "create_subscription_plan" | "list_subscription_plans" | "update_subscription_plan" | "subscribe_to_plan" | "list_subscription_payments" | "create_store" | "list_stores" | "create_pos" | "list_pos" | "list_payment_disputes" | "get_dispute" | "list_identification_types" | "list_issuers" | "list_webhooks" | "create_webhook" | "update_webhook" | "delete_webhook" | "handle_webhook" | "oauth_authorize_url" | "oauth_exchange_code" | "oauth_refresh_token" | "create_order" | "get_order" | "update_order" | "capture_order" | "cancel_order" | "get_account_balance" | "list_account_movements" | "list_settlements" | "get_settlement" | "analyze_payment_3ds" | "get_test_cards" | "get_customer" | "update_customer" | "create_customer_card" | "get_customer_card" | "get_subscription_plan" | "update_subscription" | "search_subscriptions" | "get_refund" | "update_payment_preference" | "get_merchant_order" | "search_merchant_orders" | "update_merchant_order" | "get_store" | "update_store" | "delete_store" | "get_pos" | "update_pos" | "delete_pos" | "list_bank_accounts" | "register_bank_account" | "list_point_devices" | "update_point_device_mode" | "create_point_payment_intent" | "get_point_payment_intent" | "cancel_point_payment_intent" | "compute_marketplace_fee" | "explain_payment_status" | "mp_health_check" | "find_applicable_promos" | "confirm_3ds_challenge" | "search_payments_all" | "list_settlements_all";
 /**
  * Build a tool set for the Vercel AI SDK that exposes Mercado Pago to an
  * agent. Pass directly to `Experimental_Agent`'s `tools` option, or merge with
@@ -2241,6 +2591,366 @@ declare function buildTestCardScenario(cardKey: keyof typeof TEST_CARDS_AR, scen
  * Analyze a Payment's 3DS state. Pure function, no I/O.
  */
 declare function analyze3DS(payment: Payment): ThreeDSInfo;
+/**
+ * Submit the 3DS challenge result back to MP after the buyer completes the
+ * issuer challenge. Used as the FINAL step in the 3DS challenge flow:
+ *
+ * 1. `createPayment` returns `pending` + `pending_challenge` status_detail
+ * 2. `analyze3DS(payment)` extracts the `challengeUrl`
+ * 3. Buyer is redirected to `challengeUrl` and completes the challenge
+ * 4. The issuer redirects to your `back_url` with a `challenge_complete=true`
+ *    (or similar query — depends on issuer / browser flow)
+ * 5. **You call this method** to confirm the challenge and finalize the payment
+ *
+ * # Why this is separate
+ *
+ * Step 5 isn't documented as a SINGLE endpoint in MP's public docs — different
+ * 3DS providers (Mastercard, Visa, Cabal) handle the challenge resolution
+ * differently. This method tries the documented path: re-fetching the payment
+ * via `getPayment` after the challenge — MP updates the status server-side
+ * once the issuer reports the challenge result via their backchannel.
+ *
+ * # When to call
+ *
+ * - **Before** showing the user a final "approved/rejected" screen
+ * - **After** the buyer is redirected back from the challenge URL
+ * - **With backoff**: MP sometimes lags by a few seconds — recommended to
+ *   poll `getPayment` 3-5 times with 1s spacing if the first call still
+ *   returns `pending_challenge`.
+ */
+declare function confirmChallengeAndPoll(client: MercadoPagoClient, paymentId: string, options?: {
+    /** Maximum number of polls. Default 5. */
+    maxAttempts?: number;
+    /** Sleep between polls in ms. Default 1000ms. */
+    pollIntervalMs?: number;
+    /** Optional AbortSignal to cap the total wait. */
+    signal?: AbortSignal;
+}): Promise<{
+    payment: Payment;
+    threeDs: ThreeDSInfo;
+    resolved: boolean;
+    attempts: number;
+}>;
+
+/**
+ * Pagination helpers — automatic pagination over MP's paginated endpoints
+ * via AsyncIterable. Replaces the manual offset/limit loop.
+ *
+ * # Why
+ *
+ * MP's paginated endpoints (search_payments, search_subscriptions,
+ * list_account_movements, list_settlements, search_merchant_orders, etc.)
+ * cap responses at 100 items per page. Iterating "all matching X" without
+ * helpers means writing the offset+limit loop in every caller — annoying
+ * + error-prone (off-by-one bugs are common).
+ *
+ * # Usage
+ *
+ * ```ts
+ * import { paginate } from "@ar-agents/mercadopago";
+ *
+ * for await (const payment of paginate(
+ *   (offset) => client.searchPayments({ offset, limit: 100, status: "approved" }),
+ *   { extractItems: (page) => page.results ?? [], extractTotal: (page) => page.paging?.total ?? 0 },
+ * )) {
+ *   console.log(payment.id);
+ * }
+ * ```
+ *
+ * Or use the convenience wrappers below:
+ *
+ * ```ts
+ * for await (const payment of paginatePayments(client, { status: "approved" })) {
+ *   console.log(payment.id);
+ * }
+ *
+ * // Materialize all (only when sure it fits in memory):
+ * const allPayments = await collect(paginatePayments(client, { status: "approved" }));
+ * ```
+ *
+ * # Performance
+ *
+ * - **Streaming**: items are yielded as each page arrives — your downstream
+ *   work can start before all pages are fetched.
+ * - **Bounded concurrency**: by default fetches one page at a time. Pass
+ *   `concurrency: 4` to prefetch up to 4 pages ahead (faster, more bandwidth).
+ * - **Total cap**: pass `maxItems: 1000` to bail out early.
+ *
+ * # Edge cases handled
+ *
+ * - Empty pages (returns no items, terminates).
+ * - Pages where total < expected (terminates correctly).
+ * - Mid-iteration cancellation (caller breaks the for-await — no further fetches).
+ * - Paging.total === 0 (terminates immediately).
+ */
+
+interface PaginateOptions<TPage, TItem> {
+    /** Extract the items array from a page. */
+    extractItems: (page: TPage) => TItem[];
+    /**
+     * Extract the total count from a page. Used to know when to stop.
+     * If not available, the iterator terminates when an empty page arrives.
+     */
+    extractTotal?: (page: TPage) => number | undefined;
+    /** Page size. Default 100 (MP's max for most endpoints). */
+    pageSize?: number;
+    /**
+     * Stop after yielding `maxItems` total. Useful for "first N matching"
+     * queries that would otherwise iterate the full result set.
+     */
+    maxItems?: number;
+    /**
+     * Number of pages to prefetch concurrently. Default 1 (no prefetch).
+     * Higher = lower wall-clock time but more concurrent MP requests.
+     */
+    concurrency?: number;
+}
+/**
+ * Generic paginator. Most callers use the typed convenience wrappers below.
+ *
+ * @param fetchPage Function that fetches page N given the offset.
+ */
+declare function paginate<TPage, TItem>(fetchPage: (offset: number, limit: number) => Promise<TPage>, opts: PaginateOptions<TPage, TItem>): AsyncGenerator<TItem, void, undefined>;
+/** Materialize an AsyncIterable into an array. Caller's responsibility to ensure it fits. */
+declare function collect<T>(iter: AsyncIterable<T>): Promise<T[]>;
+declare function paginatePayments(client: MercadoPagoClient, filter?: Parameters<MercadoPagoClient["searchPayments"]>[0], opts?: {
+    pageSize?: number;
+    maxItems?: number;
+    concurrency?: number;
+}): AsyncGenerator<Payment, void, undefined>;
+declare function paginateSubscriptions(client: MercadoPagoClient, filter?: Parameters<MercadoPagoClient["searchPreapprovals"]>[0], opts?: {
+    pageSize?: number;
+    maxItems?: number;
+    concurrency?: number;
+}): AsyncGenerator<Preapproval, void, undefined>;
+declare function paginateAccountMovements(client: MercadoPagoClient, filter?: {
+    from?: string;
+    to?: string;
+}, opts?: {
+    pageSize?: number;
+    maxItems?: number;
+    concurrency?: number;
+}): AsyncGenerator<AccountMovement, void, undefined>;
+declare function paginateSettlements(client: MercadoPagoClient, filter?: {
+    from?: string;
+    to?: string;
+    status?: string;
+}, opts?: {
+    pageSize?: number;
+    maxItems?: number;
+    concurrency?: number;
+}): AsyncGenerator<Settlement, void, undefined>;
+declare function paginateMerchantOrders(client: MercadoPagoClient, filter?: Parameters<MercadoPagoClient["searchMerchantOrders"]>[0], opts?: {
+    pageSize?: number;
+    maxItems?: number;
+    concurrency?: number;
+}): AsyncGenerator<MerchantOrder, void, undefined>;
+declare function paginateSubscriptionPlans(client: MercadoPagoClient, filter?: {
+    status?: string;
+}, opts?: {
+    pageSize?: number;
+    maxItems?: number;
+    concurrency?: number;
+}): AsyncGenerator<SubscriptionPlan, void, undefined>;
+declare function paginateSubscriptionPayments(client: MercadoPagoClient, preapprovalId: string, opts?: {
+    pageSize?: number;
+    maxItems?: number;
+    concurrency?: number;
+}): AsyncGenerator<SubscriptionPayment, void, undefined>;
+
+/**
+ * Token bucket rate limiter — proactive client-side rate limiting.
+ *
+ * # Why proactive
+ *
+ * The current client honors `Retry-After` after a 429 (reactive). That's
+ * good but suboptimal: every 429 still costs you a network round-trip, an
+ * error log, and adds latency to the retry. Proactive rate limiting reads
+ * MP's `x-rate-limit-remaining` header and slows down BEFORE the next 429.
+ *
+ * # The token bucket model
+ *
+ * - The bucket holds N tokens (the burst capacity).
+ * - Tokens refill at R tokens/second (the steady-state rate).
+ * - Each request consumes 1 token.
+ * - When the bucket is empty, requests wait until a token is available.
+ *
+ * Example: capacity=20, refill=10/s means "burst 20 requests, then 10/s
+ * sustained". Matches MP's typical limits (precise numbers vary by endpoint
+ * and aren't publicly documented).
+ *
+ * # Per-host vs global
+ *
+ * Default: one bucket per `MercadoPagoClient`. Pass a SHARED bucket to
+ * multiple clients in marketplace setups so they share the rate limit
+ * (otherwise each per-seller client would think it has its own quota).
+ *
+ * # Adaptive learning
+ *
+ * The bucket auto-tunes from response headers: if MP says
+ * `x-rate-limit-remaining: 5` and the bucket has 50 tokens, the bucket
+ * is over-spending. The `learnFromHeaders` method updates the available
+ * count to the lower of (current, MP's stated remaining).
+ */
+interface RateLimiterOptions {
+    /** Bucket capacity (max burst). Default 50. */
+    capacity?: number;
+    /** Refill rate in tokens per second. Default 25. */
+    refillPerSecond?: number;
+    /**
+     * If true, the limiter calls `learnFromHeaders` after every successful
+     * request to keep its bucket in sync with MP's actual quota. Default true.
+     */
+    adaptive?: boolean;
+    /**
+     * Hard cap on how long `acquire()` will wait. If the bucket can't refill
+     * in this time, `acquire()` rejects with `RateLimitTimeoutError`.
+     * Default 30s — anything longer is probably better handled as an error.
+     */
+    acquireTimeoutMs?: number;
+    /** Time provider (testing). Defaults to Date.now. */
+    now?: () => number;
+}
+declare class RateLimitTimeoutError extends Error {
+    readonly waitedMs: number;
+    constructor(waitedMs: number);
+}
+declare class TokenBucketRateLimiter {
+    private tokens;
+    private lastRefill;
+    private readonly capacity;
+    private readonly refillPerSecond;
+    private readonly adaptive;
+    private readonly acquireTimeoutMs;
+    private readonly now;
+    constructor(opts?: RateLimiterOptions);
+    /**
+     * Acquire a token. Resolves immediately if tokens are available;
+     * otherwise waits until one is. Rejects with `RateLimitTimeoutError`
+     * if the wait exceeds `acquireTimeoutMs`.
+     */
+    acquire(): Promise<void>;
+    /**
+     * 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(): boolean;
+    /**
+     * Adaptive learning hook — call after every API response with MP's
+     * rate-limit headers to keep the bucket in sync with reality.
+     */
+    learnFromHeaders(headers: {
+        remaining: number | null;
+        resetSeconds: number | null;
+    }): void;
+    /** Inspect the current bucket state. */
+    getStats(): {
+        tokens: number;
+        capacity: number;
+        refillPerSecond: number;
+    };
+    private refill;
+}
+
+/**
+ * Argentine issuer cuotas promotional catalog — embedded knowledge of which
+ * banks/cards have "cuotas sin interés" (interest-free installment) deals
+ * with which sellers, on which days.
+ *
+ * # Why embed this
+ *
+ * MP's `calculate_installments` API returns the CURRENT cuotas options for
+ * a given (payment_method, amount, bin) tuple — but it doesn't tell the
+ * agent which deals are GENERALLY available (e.g., "Naranja con Galicia, 6
+ * cuotas sin interés todos los martes"). Devs surface that information to
+ * buyers BEFORE checkout to drive conversion.
+ *
+ * This catalog is the AR-specific knowledge that turns the toolkit from
+ * "MP API wrapper" into "MP integration with retail context".
+ *
+ * # Sources
+ *
+ * - Each issuer's published "Cuotas Simples" / "Ahora 12" page
+ * - BCRA Comunicación A 7825 (financiamiento al consumo)
+ * - Manually verified against Naranja, Galicia, Santander, Macro, BBVA, ICBC
+ *   Patagonia, Banco Nación, Banco Provincia, Banco Ciudad, Comafi, HSBC
+ *   public landing pages
+ *
+ * # Maintenance
+ *
+ * The promos schedule changes seasonally. Update this file quarterly + when
+ * BCRA publishes a new "Ahora N" program. PRs welcomed.
+ *
+ * Last sync: 2026-Q2.
+ */
+interface CuotasPromo {
+    /** Issuer name (matches `list_issuers` response). */
+    issuer: string;
+    /** Card brand (visa, master, amex, naranja, cabal, etc.). */
+    paymentMethodId: string;
+    /** Number of interest-free installments. */
+    installments: number;
+    /** Days of the week the promo applies. Empty = always. */
+    daysOfWeek?: Array<"mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun">;
+    /** ISO date when the promo starts (inclusive). */
+    startDate?: string;
+    /** ISO date when the promo expires (inclusive). */
+    endDate?: string;
+    /** Minimum purchase amount in ARS for the promo to apply. */
+    minAmountArs?: number;
+    /** Maximum monthly cap on the promo per cardholder. Optional. */
+    maxAmountArs?: number;
+    /** Free-form description shown to the buyer. ALWAYS surface verbatim. */
+    description: string;
+    /** Categories where the promo applies (per BCRA codes). Empty = any. */
+    categories?: Array<"electronics" | "appliances" | "clothing" | "supermarket" | "travel" | "education" | "health" | "general">;
+}
+/**
+ * The "Ahora 12 / 18 / 24 / 30" national program — recurring federal scheme
+ * that subsidizes interest-free installments on essential categories.
+ *
+ * As of 2026-Q2: 3, 6, 12, 18, 24, 30 installment options on appliances,
+ * electronics, clothing, books, school supplies, tires, eyewear, motorcycles,
+ * national-tourism services. Not all categories qualify for all tiers.
+ */
+declare const AHORA_PROGRAM_PROMOS: CuotasPromo[];
+/**
+ * Issuer-specific promos (running in addition to the Ahora program).
+ *
+ * Note: these change frequently. Check `lastVerified` before relying.
+ */
+declare const AR_ISSUER_PROMOS: CuotasPromo[];
+/**
+ * Find applicable promos for a given context.
+ *
+ * Pure function — no I/O. Use to surface "cuotas sin interés" hints to the
+ * buyer BEFORE they call `calculate_installments` (the API only returns
+ * what's offered for the EXACT card, which the buyer hasn't entered yet).
+ *
+ * @example
+ * ```ts
+ * import { findApplicablePromos } from "@ar-agents/mercadopago";
+ *
+ * const promos = findApplicablePromos({
+ *   issuer: "Banco Galicia",
+ *   paymentMethodId: "visa",
+ *   amountArs: 50_000,
+ *   category: "supermarket",
+ *   date: new Date(), // optional, defaults to now
+ * });
+ * // → [{ installments: 12, description: "Galicia ... 12 cuotas sin interés ...", ... }]
+ * ```
+ */
+declare function findApplicablePromos(args: {
+    issuer?: string;
+    paymentMethodId?: string;
+    amountArs?: number;
+    category?: NonNullable<CuotasPromo["categories"]>[number];
+    date?: Date;
+    /** Include the Ahora program in addition to issuer-specific. Default true. */
+    includeAhoraProgram?: boolean;
+}): CuotasPromo[];
 
 /**
  * Pure helpers — no I/O, deterministic, fast. Importable directly from the
@@ -2307,4 +3017,4 @@ interface PaymentStatusExplanation {
  */
 declare function explainPaymentStatus(payment: Payment): PaymentStatusExplanation;
 
-export { type AccountBalance, type AccountInfo, type AccountMovement, type AutoRecurring, type BankAccount, type CardToken, CircuitBreaker, type CircuitBreakerOptions, CircuitOpenError, type CircuitState, type CreateCardTokenParams, type CreateCustomerParams, type CreateOrderParams, type CreatePaymentParams, type CreatePointPaymentIntentParams, type CreatePosParams, type CreatePreapprovalParams, type CreatePreferenceParams, type CreateQrPaymentParams, type CreateRefundParams, type CreateStoreParams, type CreateSubscriptionPlanParams, type CreateWebhookParams, type CurrencyId, type Customer, type CustomerCard, type Dispute, type FrequencyType, type IdentificationType, type InstallmentOffer, type Issuer, type MarketplaceFeeRule, type MarketplaceParams, MercadoPagoAccountTypeMismatchError, MercadoPagoAuthError, MercadoPagoAuthorizeForbiddenError, MercadoPagoBackUrlInvalidError, MercadoPagoClient, type MercadoPagoClientOptions, MercadoPagoError, MercadoPagoOverloadedError, MercadoPagoPaymentRejectedError, MercadoPagoRateLimitError, MercadoPagoSelfPaymentError, MercadoPagoTimeoutError, type MercadoPagoToolsOptions, type MerchantOrder, type OAuthToken, type Order, type OrderItem, type OrderStatus, type ParsedWebhookEvent, type Payment, type PaymentMethod, type PaymentStatus, type PaymentStatusExplanation, type PaymentsSearchResult, type PointDevice, type PointPaymentIntent, type PointPaymentIntentState, type Pos, type Preapproval, type PreapprovalStatus, type Preference, type PreferenceItem, type QrOrder, type Refund, type SearchPaymentsParams, type Settlement, type SiteId, type Store, type SubscriptionPayment, type SubscriptionPlan, SubscriptionStateAdapter, TEST_CARDS_AR, TEST_PAYERS_AR, type TestCard, type ThreeDSInfo, type ThreeDSStatus, type WebhookBody, type WebhookConfig, type WebhookTopic, analyze3DS, buildAuthorizeUrl, buildTestCardScenario, classifyError, computeMarketplaceFee, exchangeCodeForToken, expirationTimeMs, explainPaymentStatus, isExpiringSoon, mercadoPagoTools, parseWebhookEvent, refreshAccessToken, verifyWebhookSignature };
+export { AHORA_PROGRAM_PROMOS, AR_ISSUER_PROMOS, type AccountBalance, type AccountInfo, type AccountMovement, type AuditEntry, type AuditLogAdapter, AuditLogger, type AuditOperation, type AutoRecurring, type BankAccount, type CardToken, CircuitBreaker, type CircuitBreakerOptions, CircuitOpenError, type CircuitState, type CreateCardTokenParams, type CreateCustomerParams, type CreateOrderParams, type CreatePaymentParams, type CreatePointPaymentIntentParams, type CreatePosParams, type CreatePreapprovalParams, type CreatePreferenceParams, type CreateQrPaymentParams, type CreateRefundParams, type CreateStoreParams, type CreateSubscriptionPlanParams, type CreateWebhookParams, type CuotasPromo, type CurrencyId, type Customer, type CustomerCard, type DedupResult, type Dispute, type FrequencyType, IdempotencyCache, type IdentificationType, InMemoryAuditLog, type InstallmentOffer, type Issuer, type MarketplaceFeeRule, type MarketplaceParams, MercadoPagoAccountTypeMismatchError, MercadoPagoAuthError, MercadoPagoAuthorizeForbiddenError, MercadoPagoBackUrlInvalidError, MercadoPagoClient, type MercadoPagoClientOptions, MercadoPagoError, MercadoPagoOverloadedError, MercadoPagoPaymentRejectedError, MercadoPagoRateLimitError, MercadoPagoSelfPaymentError, MercadoPagoTimeoutError, type MercadoPagoToolsOptions, type MerchantOrder, type OAuthToken, type Order, type OrderItem, type OrderStatus, type PaginateOptions, type ParsedWebhookEvent, type Payment, type PaymentMethod, type PaymentStatus, type PaymentStatusExplanation, type PaymentsSearchResult, type PointDevice, type PointPaymentIntent, type PointPaymentIntentState, type Pos, type Preapproval, type PreapprovalStatus, type Preference, type PreferenceItem, type QrOrder, RateLimitTimeoutError, type RateLimiterOptions, type Refund, type SearchPaymentsParams, type Settlement, type SiteId, type Store, type SubscriptionPayment, type SubscriptionPlan, SubscriptionStateAdapter, TEST_CARDS_AR, TEST_PAYERS_AR, type TestCard, type ThreeDSInfo, type ThreeDSStatus, TokenBucketRateLimiter, type WebhookBody, type WebhookConfig, WebhookDedup, type WebhookDedupOptions, type WebhookTopic, analyze3DS, buildAuthorizeUrl, buildTestCardScenario, classifyError, collect, computeMarketplaceFee, confirmChallengeAndPoll, exchangeCodeForToken, expirationTimeMs, explainPaymentStatus, findApplicablePromos, isExpiringSoon, mercadoPagoTools, paginate, paginateAccountMovements, paginateMerchantOrders, paginatePayments, paginateSettlements, paginateSubscriptionPayments, paginateSubscriptionPlans, paginateSubscriptions, parseWebhookEvent, refreshAccessToken, verifyWebhookSignature };