@ar-agents/mercadopago 0.10.0 → 0.12.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 { I as IdempotencyCache, S as SubscriptionStateAdapter, A as AuditLogger, a as AuditOperation } from './audit-B9Nhj3PH.cjs';
+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.cjs';
+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;
@@ -2020,194 +2091,6 @@ declare class WebhookDedup {
     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;
@@ -2264,7 +2147,7 @@ interface MercadoPagoToolsOptions {
      */
     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" | "find_applicable_promos" | "confirm_3ds_challenge" | "search_payments_all" | "list_settlements_all";
+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
@@ -2952,6 +2835,199 @@ declare function findApplicablePromos(args: {
     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
  * package root or used via the agent tools (`compute_marketplace_fee`,
@@ -3017,4 +3093,4 @@ interface PaymentStatusExplanation {
  */
 declare function explainPaymentStatus(payment: Payment): PaymentStatusExplanation;
 
-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 };
+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 };