@ar-agents/mercadopago 0.9.0 → 0.11.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
-import { ToolSet } from 'ai';
-import { S as SubscriptionStateAdapter } from './state-C6Wzb_XX.js';
-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.js';
+import { I as IdempotencyCache, S as SubscriptionStateAdapter, A as AuditLogger, a as AuditOperation } from './audit-B9Nhj3PH.js';
+export { b as AuditEntry, c as AuditLogAdapter, d as InMemoryAuditLog, e as InMemoryIdempotencyCache, f as InMemoryOAuthTokenStore, g as InMemoryStateAdapter, O as OAuthTokenRecord, h as OAuthTokenStore, i as SubscriptionStateRecord } from './audit-B9Nhj3PH.js';
+import { ToolSet, Tool } from 'ai';
 
 /**
  * Circuit breaker — protects your app from cascading failures when MP
@@ -463,15 +463,86 @@ interface CreatePaymentParams {
     };
     /** Webhook override URL. Falls back to dashboard config if omitted. */
     notificationUrl?: string;
-    /** AFIP/ARCA discount/fee/tax additions. Used to discriminate IVA, marketplace fees, etc. */
+    /**
+     * Additional information passed to MP for fraud scoring + receipt details.
+     *
+     * **Critical for fraud scoring**: every field you fill in here improves
+     * MP's risk model's confidence and reduces false-positive rejections.
+     * For card payments above ~$50k ARS, ALWAYS include `payer` + `ip_address`
+     * + `shipments` (when applicable) — payments without enrichment have a
+     * 3-5x higher rejection rate per MP's published guidance (RG 5286/2023).
+     */
     additionalInfo?: {
+        /** Items in the cart — used for receipt + fraud scoring. */
         items?: Array<{
             id?: string;
             title: string;
             quantity: number;
             unit_price: number;
             description?: string;
+            picture_url?: string;
+            category_id?: string;
         }>;
+        /**
+         * Buyer profile fields. The more fields populated, the better MP's
+         * risk engine can assess the transaction. `registration_date` is
+         * particularly impactful (newer accounts = higher risk).
+         */
+        payer?: {
+            first_name?: string;
+            last_name?: string;
+            phone?: {
+                area_code?: string;
+                number?: string;
+            };
+            address?: {
+                zip_code?: string;
+                street_name?: string;
+                street_number?: number;
+            };
+            /** ISO 8601 date — when the buyer registered on YOUR platform. */
+            registration_date?: string;
+            /**
+             * Whether the buyer is a returning customer. Strong fraud-scoring
+             * signal — repeat buyers are lower risk.
+             */
+            authentication_type?: "Cellphone" | "Email" | "Facebook" | "Gmail" | "Native app" | string;
+            /** Whether the buyer has set up 2FA on YOUR platform. */
+            is_prime_user?: boolean;
+            /** Whether the buyer has paid you successfully before. */
+            is_first_purchase_online?: boolean;
+            /** ISO 8601 — last successful purchase on your platform. */
+            last_purchase?: string;
+        };
+        /**
+         * Shipping info. Used by fraud engine to compare against payer address.
+         * Mismatch (different city/province) = higher risk score.
+         */
+        shipments?: {
+            receiver_address?: {
+                zip_code?: string;
+                street_name?: string;
+                street_number?: number;
+                floor?: string;
+                apartment?: string;
+                city_name?: string;
+                state_name?: string;
+                country_name?: string;
+            };
+            /** Express shipment flag — fraud engine treats high-value+express as suspicious. */
+            express_shipment?: boolean;
+            /** True if the buyer picks up at a store (no shipment). Reduces fraud risk. */
+            local_pickup?: boolean;
+        };
+        /**
+         * Buyer's IP address (from your X-Forwarded-For / req.headers).
+         * **Strongly recommended** for any card payment — MP's fraud engine
+         * checks IP geolocation, ASN reputation, proxy/VPN detection.
+         * Without IP, MP defaults to "unknown" which raises risk score.
+         */
+        ip_address?: string;
+        /** Referrer URL — useful for affiliate / channel attribution + fraud signal. */
+        referral_url?: string;
     };
     /** Statement descriptor — what shows on the buyer's card statement. Max 13 chars. */
     statementDescriptor?: string;
@@ -1876,6 +1947,150 @@ 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;
+}
+
 interface MercadoPagoToolsOptions {
     /** State adapter for persisting subscription records. */
     state: SubscriptionStateAdapter;
@@ -1913,8 +2128,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" | "validate_tax_id";
 /**
  * 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 +2474,559 @@ 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[];
+
+/**
+ * Tool middleware — composable wrappers around any Vercel AI SDK tool.
+ *
+ * # The pattern
+ *
+ * Vercel AI SDK tools have a uniform shape: `{ description, inputSchema, execute }`.
+ * Middleware wraps a tool's `execute()` with cross-cutting concerns (logging,
+ * rate limiting, retries, metrics) WITHOUT modifying the tool itself.
+ *
+ * Compose middleware to layer behaviors:
+ *
+ * ```ts
+ * import { withAuditLog, withRateLimit, withMetrics, compose } from "@ar-agents/mercadopago";
+ *
+ * const baseTools = mercadoPagoTools(client, { state, backUrl });
+ *
+ * const tools = Object.fromEntries(
+ *   Object.entries(baseTools).map(([name, tool]) => [
+ *     name,
+ *     compose(
+ *       withMetrics(name, { onMetric: (m) => statsd.increment(...) }),
+ *       withRateLimit(rateLimiter),
+ *       withAuditLog(auditLogger, name),
+ *     )(tool),
+ *   ])
+ * );
+ * ```
+ *
+ * # Why this matters
+ *
+ * Without middleware, every cross-cutting concern (audit, rate limit, retry)
+ * has to be wired INTO the tool implementation OR repeated at every call
+ * site. Middleware lets you add/remove/swap concerns from a single config
+ * point — clean separation of concerns + testable in isolation.
+ */
+
+/**
+ * A tool middleware — takes a tool, returns a wrapped tool with the same
+ * shape but enhanced behavior in `execute()`.
+ */
+type ToolMiddleware = <T extends Tool<unknown, unknown>>(tool: T) => T;
+/**
+ * Compose multiple middleware functions. The LAST middleware in the list
+ * runs INNERMOST (closest to the original tool's execute):
+ *
+ * ```
+ * compose(a, b, c)(tool) == a(b(c(tool)))
+ * ```
+ *
+ * Reasoning: the most "core" concerns (e.g. audit log) typically wrap the
+ * actual call closely (innermost), while observability layers (e.g. metrics,
+ * tracing) sit outside.
+ *
+ * @example
+ * ```ts
+ * const enhance = compose(
+ *   withMetrics("create_payment"),       // outer (records duration of everything below)
+ *   withRateLimit(limiter),              // middle (rate-limits before the call)
+ *   withAuditLog(audit, "create_payment"), // inner (records the call result)
+ * );
+ * const enhanced = enhance(originalTool);
+ * ```
+ */
+declare function compose(...middlewares: ToolMiddleware[]): ToolMiddleware;
+/**
+ * Wrap a tool's `execute()` with audit logging. Every call records an entry
+ * with operation, actor, inputHash, outcome, and duration.
+ *
+ * @param logger The configured AuditLogger.
+ * @param operation The operation name (matches AuditOperation union).
+ * @param actor Optional actor override (defaults to logger's defaultActor).
+ */
+declare function withAuditLog(logger: AuditLogger, operation: AuditOperation, actor?: string): ToolMiddleware;
+/**
+ * Wrap a tool's `execute()` with rate limiting. Acquires a token from the
+ * bucket BEFORE the call; if the bucket is empty, awaits up to the bucket's
+ * `acquireTimeoutMs`. Throws `RateLimitTimeoutError` if the wait exceeds it.
+ */
+declare function withRateLimit(limiter: TokenBucketRateLimiter): ToolMiddleware;
+interface MetricsHook {
+    /**
+     * Called after every tool invocation. Synchronous, fire-and-forget.
+     * Compatible with Datadog, StatsD, Prometheus client, OTEL meter, etc.
+     */
+    onMetric: (event: {
+        toolName: string;
+        durationMs: number;
+        success: boolean;
+        errorCode?: string;
+    }) => void;
+}
+/**
+ * Wrap a tool's `execute()` with metrics emission. Records duration + a
+ * success/error counter for every call.
+ */
+declare function withMetrics(toolName: string, hook: MetricsHook): ToolMiddleware;
+interface RetryOptions {
+    /** Max attempts including initial. Default 3. */
+    maxAttempts?: number;
+    /** Base backoff in ms (multiplied by 2^attempt). Default 250. */
+    baseBackoffMs?: number;
+    /**
+     * Predicate: should this error trigger a retry? Default: retries on
+     * any thrown Error EXCEPT MercadoPagoError 4xx (those are user errors).
+     */
+    shouldRetry?: (err: unknown, attempt: number) => boolean;
+    /** Optional hook fired on every retry attempt. */
+    onRetry?: (event: {
+        attempt: number;
+        error: unknown;
+        delayMs: number;
+    }) => void;
+}
+/**
+ * Wrap a tool's `execute()` with retry-with-backoff. Useful for tools that
+ * call external APIs not protected by the underlying client's retry budget
+ * (e.g., agent-side aggregation tools).
+ *
+ * The MercadoPagoClient already retries internally on 5xx/429, so layering
+ * this on top of MP-backed tools usually means total retries = client × tool.
+ * Use sparingly.
+ */
+declare function withRetry(opts?: RetryOptions): ToolMiddleware;
+/**
+ * Apply a middleware to every tool in a ToolSet. Useful for blanket policies:
+ * "all tools rate-limited", "all tools metrics-emitted".
+ *
+ * @example
+ * ```ts
+ * const baseTools = mercadoPagoTools(client, { state, backUrl });
+ * const limited = applyToAllTools(baseTools, withRateLimit(limiter));
+ * ```
+ */
+declare function applyToAllTools<T extends Record<string, Tool<unknown, unknown>>>(tools: T, middleware: ToolMiddleware): T;
+
+/**
+ * TaxID validation across LATAM — pure-algorithm validators for the major
+ * jurisdictions where MP operates. NO network calls.
+ *
+ * # Why
+ *
+ * Marketplace-style apps that span multiple LATAM countries need to
+ * validate buyer/seller tax IDs in their respective formats: AR (DNI/CUIT/CUIL),
+ * BR (CPF/CNPJ), MX (RFC), CL (RUT), CO (NIT), UY (RUT), PE (RUC).
+ *
+ * Each country has its own checksum algorithm. Wiring this once per app
+ * is annoying + error-prone. Embedding it here means the agent can
+ * validate ANY LATAM tax ID with a single tool call.
+ *
+ * # Sources
+ *
+ * - AR DNI/CUIT/CUIL: AFIP RG 100/1998 (modulo-11 checksum)
+ * - BR CPF: Receita Federal (two-step modulo-11)
+ * - BR CNPJ: Receita Federal (two-step weighted modulo)
+ * - MX RFC: SAT regex + 13-char structure
+ * - CL RUT: SII modulo-11 + check digit "0-9, K"
+ * - CO NIT: DIAN modulo-11
+ * - UY RUT: 12-digit numeric + checksum
+ * - PE RUC: SUNAT 11-digit + checksum
+ */
+type TaxIdCountry = "AR" | "BR" | "MX" | "CL" | "CO" | "UY" | "PE";
+type TaxIdType = "DNI" | "CUIT" | "CUIL" | "CPF" | "CNPJ" | "RFC" | "RUT_CL" | "NIT" | "RUT_UY" | "RUC";
+interface TaxIdValidationResult {
+    valid: boolean;
+    /** Bare digits/chars after normalization (no separators). */
+    normalized: string;
+    /** Pretty-formatted version with country-specific separators. */
+    formatted: string | null;
+    type: TaxIdType;
+    country: TaxIdCountry;
+    /** Spanish error message when invalid. Surface verbatim to users. */
+    error: string | null;
+}
+/**
+ * Validate a tax ID against the appropriate country algorithm.
+ *
+ * @example
+ * validateTaxId("20-41758101-5", "CUIT")
+ * // → { valid: true, normalized: "20417581015", formatted: "20-41758101-5", ... }
+ *
+ * @example
+ * validateTaxId("123.456.789-09", "CPF")
+ * // → { valid: true, normalized: "12345678909", ... }
+ */
+declare function validateTaxId(input: string, type: TaxIdType): TaxIdValidationResult;
+/**
+ * Convenience: try to detect the type from the input shape + country, then
+ * validate. Useful when the agent doesn't know if it's a CPF or a CNPJ.
+ *
+ * @returns null when the input doesn't match any known type for the country
+ */
+declare function detectAndValidate(input: string, country: TaxIdCountry): TaxIdValidationResult | null;
 
 /**
  * Pure helpers — no I/O, deterministic, fast. Importable directly from the
@@ -2307,4 +3093,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, AuditLogger, 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, 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 MetricsHook, 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 RetryOptions, type SearchPaymentsParams, type Settlement, type SiteId, type Store, type SubscriptionPayment, type SubscriptionPlan, SubscriptionStateAdapter, TEST_CARDS_AR, TEST_PAYERS_AR, type TaxIdCountry, type TaxIdType, type TaxIdValidationResult, type TestCard, type ThreeDSInfo, type ThreeDSStatus, TokenBucketRateLimiter, type ToolMiddleware, type WebhookBody, type WebhookConfig, WebhookDedup, type WebhookDedupOptions, type WebhookTopic, analyze3DS, applyToAllTools, buildAuthorizeUrl, buildTestCardScenario, classifyError, collect, compose, computeMarketplaceFee, confirmChallengeAndPoll, detectAndValidate, exchangeCodeForToken, expirationTimeMs, explainPaymentStatus, findApplicablePromos, isExpiringSoon, mercadoPagoTools, paginate, paginateAccountMovements, paginateMerchantOrders, paginatePayments, paginateSettlements, paginateSubscriptionPayments, paginateSubscriptionPlans, paginateSubscriptions, parseWebhookEvent, refreshAccessToken, validateTaxId, verifyWebhookSignature, withAuditLog, withMetrics, withRateLimit, withRetry };