@ar-agents/mercadopago 0.6.0 → 0.7.0

package/dist/index.d.cts

@@ -1017,6 +1017,79 @@ interface ThreeDSInfo {
     /** Human-readable explanation suitable for surfacing to the user. */
     description: string;
 }
+declare const MerchantOrderSchema: z.ZodObject<{
+    id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    status: z.ZodOptional<z.ZodString>;
+    external_reference: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    preference_id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    payments: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    shipments: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    payer: z.ZodOptional<z.ZodUnknown>;
+    collector: z.ZodOptional<z.ZodUnknown>;
+    marketplace: z.ZodOptional<z.ZodString>;
+    total_amount: z.ZodOptional<z.ZodNumber>;
+    paid_amount: z.ZodOptional<z.ZodNumber>;
+    refunded_amount: z.ZodOptional<z.ZodNumber>;
+    shipping_cost: z.ZodOptional<z.ZodNumber>;
+    date_created: z.ZodOptional<z.ZodString>;
+    last_updated: z.ZodOptional<z.ZodString>;
+    site_id: z.ZodOptional<z.ZodString>;
+    order_status: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+type MerchantOrder = z.infer<typeof MerchantOrderSchema>;
+declare const BankAccountSchema: z.ZodObject<{
+    id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    cbu: z.ZodOptional<z.ZodString>;
+    alias: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    bank_name: z.ZodOptional<z.ZodString>;
+    account_type: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodString>;
+    is_default: z.ZodOptional<z.ZodBoolean>;
+    date_created: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+type BankAccount = z.infer<typeof BankAccountSchema>;
+declare const PointDeviceSchema: z.ZodObject<{
+    id: z.ZodString;
+    pos_id: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+    store_id: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+    external_pos_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    operating_mode: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"PDV">, z.ZodLiteral<"STANDALONE">, z.ZodString]>>;
+}, z.core.$loose>;
+type PointDevice = z.infer<typeof PointDeviceSchema>;
+type PointPaymentIntentState = "OPEN" | "PROCESSING" | "FINISHED" | "CANCELED" | "ERROR" | string;
+declare const PointPaymentIntentSchema: z.ZodObject<{
+    id: z.ZodString;
+    device_id: z.ZodOptional<z.ZodString>;
+    amount: z.ZodOptional<z.ZodNumber>;
+    state: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"OPEN">, z.ZodLiteral<"PROCESSING">, z.ZodLiteral<"FINISHED">, z.ZodLiteral<"CANCELED">, z.ZodLiteral<"ERROR">, z.ZodString]>>;
+    payment: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        type: z.ZodOptional<z.ZodString>;
+        installments: z.ZodOptional<z.ZodNumber>;
+        installments_cost: z.ZodOptional<z.ZodString>;
+        print_on_terminal: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>>;
+    additional_info: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$loose>;
+type PointPaymentIntent = z.infer<typeof PointPaymentIntentSchema>;
+interface CreatePointPaymentIntentParams {
+    /** Amount in centavos (yes, centavos — Point API differs from Payments API). */
+    amount: number;
+    /** Description shown on the device screen + the buyer's receipt. */
+    description?: string;
+    /** Your-system reference (echoed back in the resulting Payment). */
+    externalReference?: string;
+    /** Number of installments (default 1). */
+    installments?: number;
+    /** "seller" or "buyer" — who pays the installment cost. */
+    installmentsCost?: "seller" | "buyer";
+    /**
+     * Print receipt on the terminal (default true). Some kiosks set false.
+     */
+    printOnTerminal?: boolean;
+    /** Ticket number (your sequential receipt number). */
+    ticketNumber?: string;
+}
 
 interface MercadoPagoClientOptions {
     /** Access token. TEST- prefix for sandbox, APP_USR- for production. */
@@ -1398,6 +1471,158 @@ declare class MercadoPagoClient {
      * including bank_account info (CBU, bank name).
      */
     getSettlement(id: string): Promise<Settlement>;
+    /**
+     * Update a customer's profile (name, last name, address, etc.). MP merges
+     * the patch — fields you don't send remain unchanged.
+     */
+    updateCustomer(id: string, patch: Partial<{
+        first_name: string;
+        last_name: string;
+        phone: {
+            area_code?: string;
+            number?: string;
+        };
+        identification: {
+            type: string;
+            number: string;
+        };
+        address: {
+            street_name?: string;
+            street_number?: number;
+            zip_code?: string;
+        };
+        description: string;
+        default_card?: string;
+    }>): Promise<Customer>;
+    /**
+     * Add a saved card to a customer using a card token (one-time, get from
+     * MP's frontend Cardform). The card is then chargeable with charge_saved_card.
+     */
+    createCustomerCard(customerId: string, cardToken: string): Promise<CustomerCard>;
+    /**
+     * Update an existing subscription. Common patches:
+     * - `transaction_amount` to change the recurring amount
+     * - `card_token_id` to switch payment method (e.g., expired card)
+     * - `status: "cancelled" | "paused"` (alternative to dedicated cancel/pause endpoints)
+     * - `reason` to update the description shown to the buyer
+     */
+    updatePreapproval(id: string, patch: Partial<{
+        transaction_amount: number;
+        card_token_id: string;
+        status: "authorized" | "paused" | "cancelled";
+        reason: string;
+        external_reference: string;
+    }>): Promise<Preapproval>;
+    /**
+     * Search subscriptions across the seller's account. Common filters:
+     * `status` (pending/authorized/paused/cancelled), `payer_email`,
+     * `external_reference`. Paginated.
+     */
+    searchPreapprovals(params?: {
+        status?: string;
+        payerEmail?: string;
+        externalReference?: string;
+        preapproval_plan_id?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        results: Preapproval[];
+        paging: {
+            limit: number;
+            offset: number;
+            total: number;
+        };
+    }>;
+    /**
+     * Get a merchant_order with all its associated payments + shipments.
+     * Useful for reconciling "which payments belong to which preference"
+     * — typical webhook handler use case.
+     */
+    getMerchantOrder(id: string): Promise<MerchantOrder>;
+    /**
+     * Search merchant_orders by external_reference, preference_id, or status.
+     */
+    searchMerchantOrders(params?: {
+        preferenceId?: string;
+        externalReference?: string;
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        elements: MerchantOrder[];
+        paging: {
+            limit: number;
+            offset: number;
+            total: number;
+        };
+    }>;
+    /**
+     * Update a merchant_order — typically to add items or update shipping.
+     */
+    updateMerchantOrder(id: string, patch: Record<string, unknown>): Promise<MerchantOrder>;
+    getStore(userId: string, storeId: string): Promise<Store>;
+    updateStore(userId: string, storeId: string, patch: Partial<CreateStoreParams>): Promise<Store>;
+    deleteStore(userId: string, storeId: string): Promise<void>;
+    getPos(posId: string): Promise<Pos>;
+    updatePos(posId: string, patch: Partial<CreatePosParams>): Promise<Pos>;
+    deletePos(posId: string): Promise<void>;
+    /**
+     * List bank accounts registered by the seller. The default is the one
+     * that receives `release_money` settlements.
+     */
+    listBankAccounts(): Promise<BankAccount[]>;
+    /**
+     * Register a new bank account (CBU) for the seller. Note: MP usually
+     * requires this through the dashboard for compliance — this endpoint may
+     * not work for all sellers.
+     */
+    registerBankAccount(params: {
+        cbu: string;
+        alias?: string;
+    }): Promise<BankAccount>;
+    /**
+     * List the Point devices linked to the seller's MP account. Each device
+     * has an id (the device serial), an operating_mode (PDV vs STANDALONE),
+     * and an optional pos_id (when bound to a logical POS).
+     */
+    listPointDevices(params?: {
+        posId?: string | number;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        devices: PointDevice[];
+        paging: {
+            total: number;
+            limit: number;
+            offset: number;
+        };
+    }>;
+    /**
+     * Switch a Point device's operating mode:
+     * - "PDV": device is bound to a logical Pos and only takes payments
+     *   triggered through that Pos (typical for cash-register integrations).
+     * - "STANDALONE": device works independently, accepts any payment.
+     */
+    updatePointDeviceOperatingMode(deviceId: string, operatingMode: "PDV" | "STANDALONE"): Promise<PointDevice>;
+    /**
+     * Create a payment intent on a Point device — the device prompts the buyer
+     * to tap/insert/swipe. Returns immediately with intent id; query state via
+     * `getPointPaymentIntent()` or wait for `point_integration_wh` webhook.
+     *
+     * NOTE: amount is in CENTAVOS (Point API differs from Payments API which
+     * uses pesos). 100 = $1 ARS, 1000 = $10, 10000 = $100, etc.
+     */
+    createPointPaymentIntent(deviceId: string, params: CreatePointPaymentIntentParams): Promise<PointPaymentIntent>;
+    /** Get the current state of a Point payment intent. */
+    getPointPaymentIntent(intentId: string): Promise<PointPaymentIntent>;
+    /**
+     * Cancel an OPEN payment intent before the buyer interacts with the device.
+     * Only works while state is "OPEN" — once the buyer taps, you can't cancel.
+     */
+    cancelPointPaymentIntent(deviceId: string, intentId: string): Promise<{
+        id: string;
+        canceled: true;
+    }>;
 }
 
 /**
@@ -1484,7 +1709,7 @@ interface MercadoPagoToolsOptions {
         clientSecret: string;
     };
 }
-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";
+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";
 /**
  * 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
@@ -1789,4 +2014,69 @@ declare function buildTestCardScenario(cardKey: keyof typeof TEST_CARDS_AR, scen
  */
 declare function analyze3DS(payment: Payment): ThreeDSInfo;
 
-export { type AccountBalance, type AccountInfo, type AccountMovement, type AutoRecurring, type CardToken, type CreateCardTokenParams, type CreateCustomerParams, type CreateOrderParams, type CreatePaymentParams, 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, InMemoryStateAdapter, type InstallmentOffer, type Issuer, type MarketplaceParams, MercadoPagoAccountTypeMismatchError, MercadoPagoAuthError, MercadoPagoAuthorizeForbiddenError, MercadoPagoBackUrlInvalidError, MercadoPagoClient, type MercadoPagoClientOptions, MercadoPagoError, MercadoPagoOverloadedError, MercadoPagoPaymentRejectedError, MercadoPagoRateLimitError, MercadoPagoSelfPaymentError, MercadoPagoTimeoutError, type MercadoPagoToolsOptions, type OAuthToken, type Order, type OrderItem, type OrderStatus, type ParsedWebhookEvent, type Payment, type PaymentMethod, type PaymentStatus, type PaymentsSearchResult, 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, type SubscriptionStateAdapter, type SubscriptionStateRecord, TEST_CARDS_AR, TEST_PAYERS_AR, type TestCard, type ThreeDSInfo, type ThreeDSStatus, type WebhookBody, type WebhookConfig, type WebhookTopic, analyze3DS, buildAuthorizeUrl, buildTestCardScenario, classifyError, exchangeCodeForToken, expirationTimeMs, isExpiringSoon, mercadoPagoTools, parseWebhookEvent, refreshAccessToken, verifyWebhookSignature };
+/**
+ * Pure helpers — no I/O, deterministic, fast. Importable directly from the
+ * package root or used via the agent tools (`compute_marketplace_fee`,
+ * `explain_payment_status`).
+ */
+
+interface MarketplaceFeeRule {
+    /** Fixed fee in ARS (added on top of percentage). */
+    flatArs?: number;
+    /** Percentage of the transaction amount (0-100). */
+    percent?: number;
+    /** Minimum fee floor in ARS. */
+    minArs?: number;
+    /** Maximum fee cap in ARS. */
+    maxArs?: number;
+    /** Round to nearest peso (default true). */
+    round?: boolean;
+}
+/**
+ * Compute the exact `marketplace_fee` (in ARS) to pass to `create_order` /
+ * `create_payment_preference` for a given transaction amount and fee rule.
+ *
+ * @example
+ * // 5% fee with $50 floor and $5000 cap
+ * computeMarketplaceFee(10000, { percent: 5, minArs: 50, maxArs: 5000 })
+ * // → 500
+ *
+ * computeMarketplaceFee(500, { percent: 5, minArs: 50 })
+ * // → 50 (would be 25 by percent, floor lifts to 50)
+ *
+ * @example
+ * // Flat $200 + 2%
+ * computeMarketplaceFee(10000, { flatArs: 200, percent: 2 })
+ * // → 400
+ */
+declare function computeMarketplaceFee(amountArs: number, rule: MarketplaceFeeRule): number;
+interface PaymentStatusExplanation {
+    /** Spanish summary of the current state — surface to user. */
+    summary: string;
+    /** What the agent should do next. Actionable guidance. */
+    recommendedAction: string;
+    /**
+     * Whether this state is FINAL (no further changes) or transient
+     * (can still flip with another webhook).
+     */
+    final: boolean;
+    /** Whether the buyer paid successfully (approved). */
+    paid: boolean;
+    /**
+     * Whether this is a recoverable rejection (user can retry with another
+     * card / different installments) vs a hard rejection (stop trying).
+     */
+    retryable: boolean;
+}
+/**
+ * Human-readable explanation of a Payment's current state — derives summary,
+ * recommended action, finality, and whether the rejection is retryable from
+ * `payment.status` + `payment.status_detail`.
+ *
+ * Pure function. Use the output to drive agent decisions ("¿reintento?
+ * ¿le digo al cliente que cambie de tarjeta?") without having to memorize
+ * every MP status_detail code.
+ */
+declare function explainPaymentStatus(payment: Payment): PaymentStatusExplanation;
+
+export { type AccountBalance, type AccountInfo, type AccountMovement, type AutoRecurring, type BankAccount, type CardToken, 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, InMemoryStateAdapter, 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, type SubscriptionStateAdapter, type SubscriptionStateRecord, 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 };

package/dist/index.d.ts

@@ -1017,6 +1017,79 @@ interface ThreeDSInfo {
     /** Human-readable explanation suitable for surfacing to the user. */
     description: string;
 }
+declare const MerchantOrderSchema: z.ZodObject<{
+    id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    status: z.ZodOptional<z.ZodString>;
+    external_reference: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    preference_id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    payments: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    shipments: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    payer: z.ZodOptional<z.ZodUnknown>;
+    collector: z.ZodOptional<z.ZodUnknown>;
+    marketplace: z.ZodOptional<z.ZodString>;
+    total_amount: z.ZodOptional<z.ZodNumber>;
+    paid_amount: z.ZodOptional<z.ZodNumber>;
+    refunded_amount: z.ZodOptional<z.ZodNumber>;
+    shipping_cost: z.ZodOptional<z.ZodNumber>;
+    date_created: z.ZodOptional<z.ZodString>;
+    last_updated: z.ZodOptional<z.ZodString>;
+    site_id: z.ZodOptional<z.ZodString>;
+    order_status: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+type MerchantOrder = z.infer<typeof MerchantOrderSchema>;
+declare const BankAccountSchema: z.ZodObject<{
+    id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    cbu: z.ZodOptional<z.ZodString>;
+    alias: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    bank_name: z.ZodOptional<z.ZodString>;
+    account_type: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodString>;
+    is_default: z.ZodOptional<z.ZodBoolean>;
+    date_created: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+type BankAccount = z.infer<typeof BankAccountSchema>;
+declare const PointDeviceSchema: z.ZodObject<{
+    id: z.ZodString;
+    pos_id: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+    store_id: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+    external_pos_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    operating_mode: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"PDV">, z.ZodLiteral<"STANDALONE">, z.ZodString]>>;
+}, z.core.$loose>;
+type PointDevice = z.infer<typeof PointDeviceSchema>;
+type PointPaymentIntentState = "OPEN" | "PROCESSING" | "FINISHED" | "CANCELED" | "ERROR" | string;
+declare const PointPaymentIntentSchema: z.ZodObject<{
+    id: z.ZodString;
+    device_id: z.ZodOptional<z.ZodString>;
+    amount: z.ZodOptional<z.ZodNumber>;
+    state: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"OPEN">, z.ZodLiteral<"PROCESSING">, z.ZodLiteral<"FINISHED">, z.ZodLiteral<"CANCELED">, z.ZodLiteral<"ERROR">, z.ZodString]>>;
+    payment: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        type: z.ZodOptional<z.ZodString>;
+        installments: z.ZodOptional<z.ZodNumber>;
+        installments_cost: z.ZodOptional<z.ZodString>;
+        print_on_terminal: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>>;
+    additional_info: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$loose>;
+type PointPaymentIntent = z.infer<typeof PointPaymentIntentSchema>;
+interface CreatePointPaymentIntentParams {
+    /** Amount in centavos (yes, centavos — Point API differs from Payments API). */
+    amount: number;
+    /** Description shown on the device screen + the buyer's receipt. */
+    description?: string;
+    /** Your-system reference (echoed back in the resulting Payment). */
+    externalReference?: string;
+    /** Number of installments (default 1). */
+    installments?: number;
+    /** "seller" or "buyer" — who pays the installment cost. */
+    installmentsCost?: "seller" | "buyer";
+    /**
+     * Print receipt on the terminal (default true). Some kiosks set false.
+     */
+    printOnTerminal?: boolean;
+    /** Ticket number (your sequential receipt number). */
+    ticketNumber?: string;
+}
 
 interface MercadoPagoClientOptions {
     /** Access token. TEST- prefix for sandbox, APP_USR- for production. */
@@ -1398,6 +1471,158 @@ declare class MercadoPagoClient {
      * including bank_account info (CBU, bank name).
      */
     getSettlement(id: string): Promise<Settlement>;
+    /**
+     * Update a customer's profile (name, last name, address, etc.). MP merges
+     * the patch — fields you don't send remain unchanged.
+     */
+    updateCustomer(id: string, patch: Partial<{
+        first_name: string;
+        last_name: string;
+        phone: {
+            area_code?: string;
+            number?: string;
+        };
+        identification: {
+            type: string;
+            number: string;
+        };
+        address: {
+            street_name?: string;
+            street_number?: number;
+            zip_code?: string;
+        };
+        description: string;
+        default_card?: string;
+    }>): Promise<Customer>;
+    /**
+     * Add a saved card to a customer using a card token (one-time, get from
+     * MP's frontend Cardform). The card is then chargeable with charge_saved_card.
+     */
+    createCustomerCard(customerId: string, cardToken: string): Promise<CustomerCard>;
+    /**
+     * Update an existing subscription. Common patches:
+     * - `transaction_amount` to change the recurring amount
+     * - `card_token_id` to switch payment method (e.g., expired card)
+     * - `status: "cancelled" | "paused"` (alternative to dedicated cancel/pause endpoints)
+     * - `reason` to update the description shown to the buyer
+     */
+    updatePreapproval(id: string, patch: Partial<{
+        transaction_amount: number;
+        card_token_id: string;
+        status: "authorized" | "paused" | "cancelled";
+        reason: string;
+        external_reference: string;
+    }>): Promise<Preapproval>;
+    /**
+     * Search subscriptions across the seller's account. Common filters:
+     * `status` (pending/authorized/paused/cancelled), `payer_email`,
+     * `external_reference`. Paginated.
+     */
+    searchPreapprovals(params?: {
+        status?: string;
+        payerEmail?: string;
+        externalReference?: string;
+        preapproval_plan_id?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        results: Preapproval[];
+        paging: {
+            limit: number;
+            offset: number;
+            total: number;
+        };
+    }>;
+    /**
+     * Get a merchant_order with all its associated payments + shipments.
+     * Useful for reconciling "which payments belong to which preference"
+     * — typical webhook handler use case.
+     */
+    getMerchantOrder(id: string): Promise<MerchantOrder>;
+    /**
+     * Search merchant_orders by external_reference, preference_id, or status.
+     */
+    searchMerchantOrders(params?: {
+        preferenceId?: string;
+        externalReference?: string;
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        elements: MerchantOrder[];
+        paging: {
+            limit: number;
+            offset: number;
+            total: number;
+        };
+    }>;
+    /**
+     * Update a merchant_order — typically to add items or update shipping.
+     */
+    updateMerchantOrder(id: string, patch: Record<string, unknown>): Promise<MerchantOrder>;
+    getStore(userId: string, storeId: string): Promise<Store>;
+    updateStore(userId: string, storeId: string, patch: Partial<CreateStoreParams>): Promise<Store>;
+    deleteStore(userId: string, storeId: string): Promise<void>;
+    getPos(posId: string): Promise<Pos>;
+    updatePos(posId: string, patch: Partial<CreatePosParams>): Promise<Pos>;
+    deletePos(posId: string): Promise<void>;
+    /**
+     * List bank accounts registered by the seller. The default is the one
+     * that receives `release_money` settlements.
+     */
+    listBankAccounts(): Promise<BankAccount[]>;
+    /**
+     * Register a new bank account (CBU) for the seller. Note: MP usually
+     * requires this through the dashboard for compliance — this endpoint may
+     * not work for all sellers.
+     */
+    registerBankAccount(params: {
+        cbu: string;
+        alias?: string;
+    }): Promise<BankAccount>;
+    /**
+     * List the Point devices linked to the seller's MP account. Each device
+     * has an id (the device serial), an operating_mode (PDV vs STANDALONE),
+     * and an optional pos_id (when bound to a logical POS).
+     */
+    listPointDevices(params?: {
+        posId?: string | number;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        devices: PointDevice[];
+        paging: {
+            total: number;
+            limit: number;
+            offset: number;
+        };
+    }>;
+    /**
+     * Switch a Point device's operating mode:
+     * - "PDV": device is bound to a logical Pos and only takes payments
+     *   triggered through that Pos (typical for cash-register integrations).
+     * - "STANDALONE": device works independently, accepts any payment.
+     */
+    updatePointDeviceOperatingMode(deviceId: string, operatingMode: "PDV" | "STANDALONE"): Promise<PointDevice>;
+    /**
+     * Create a payment intent on a Point device — the device prompts the buyer
+     * to tap/insert/swipe. Returns immediately with intent id; query state via
+     * `getPointPaymentIntent()` or wait for `point_integration_wh` webhook.
+     *
+     * NOTE: amount is in CENTAVOS (Point API differs from Payments API which
+     * uses pesos). 100 = $1 ARS, 1000 = $10, 10000 = $100, etc.
+     */
+    createPointPaymentIntent(deviceId: string, params: CreatePointPaymentIntentParams): Promise<PointPaymentIntent>;
+    /** Get the current state of a Point payment intent. */
+    getPointPaymentIntent(intentId: string): Promise<PointPaymentIntent>;
+    /**
+     * Cancel an OPEN payment intent before the buyer interacts with the device.
+     * Only works while state is "OPEN" — once the buyer taps, you can't cancel.
+     */
+    cancelPointPaymentIntent(deviceId: string, intentId: string): Promise<{
+        id: string;
+        canceled: true;
+    }>;
 }
 
 /**
@@ -1484,7 +1709,7 @@ interface MercadoPagoToolsOptions {
         clientSecret: string;
     };
 }
-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";
+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";
 /**
  * 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
@@ -1789,4 +2014,69 @@ declare function buildTestCardScenario(cardKey: keyof typeof TEST_CARDS_AR, scen
  */
 declare function analyze3DS(payment: Payment): ThreeDSInfo;
 
-export { type AccountBalance, type AccountInfo, type AccountMovement, type AutoRecurring, type CardToken, type CreateCardTokenParams, type CreateCustomerParams, type CreateOrderParams, type CreatePaymentParams, 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, InMemoryStateAdapter, type InstallmentOffer, type Issuer, type MarketplaceParams, MercadoPagoAccountTypeMismatchError, MercadoPagoAuthError, MercadoPagoAuthorizeForbiddenError, MercadoPagoBackUrlInvalidError, MercadoPagoClient, type MercadoPagoClientOptions, MercadoPagoError, MercadoPagoOverloadedError, MercadoPagoPaymentRejectedError, MercadoPagoRateLimitError, MercadoPagoSelfPaymentError, MercadoPagoTimeoutError, type MercadoPagoToolsOptions, type OAuthToken, type Order, type OrderItem, type OrderStatus, type ParsedWebhookEvent, type Payment, type PaymentMethod, type PaymentStatus, type PaymentsSearchResult, 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, type SubscriptionStateAdapter, type SubscriptionStateRecord, TEST_CARDS_AR, TEST_PAYERS_AR, type TestCard, type ThreeDSInfo, type ThreeDSStatus, type WebhookBody, type WebhookConfig, type WebhookTopic, analyze3DS, buildAuthorizeUrl, buildTestCardScenario, classifyError, exchangeCodeForToken, expirationTimeMs, isExpiringSoon, mercadoPagoTools, parseWebhookEvent, refreshAccessToken, verifyWebhookSignature };
+/**
+ * Pure helpers — no I/O, deterministic, fast. Importable directly from the
+ * package root or used via the agent tools (`compute_marketplace_fee`,
+ * `explain_payment_status`).
+ */
+
+interface MarketplaceFeeRule {
+    /** Fixed fee in ARS (added on top of percentage). */
+    flatArs?: number;
+    /** Percentage of the transaction amount (0-100). */
+    percent?: number;
+    /** Minimum fee floor in ARS. */
+    minArs?: number;
+    /** Maximum fee cap in ARS. */
+    maxArs?: number;
+    /** Round to nearest peso (default true). */
+    round?: boolean;
+}
+/**
+ * Compute the exact `marketplace_fee` (in ARS) to pass to `create_order` /
+ * `create_payment_preference` for a given transaction amount and fee rule.
+ *
+ * @example
+ * // 5% fee with $50 floor and $5000 cap
+ * computeMarketplaceFee(10000, { percent: 5, minArs: 50, maxArs: 5000 })
+ * // → 500
+ *
+ * computeMarketplaceFee(500, { percent: 5, minArs: 50 })
+ * // → 50 (would be 25 by percent, floor lifts to 50)
+ *
+ * @example
+ * // Flat $200 + 2%
+ * computeMarketplaceFee(10000, { flatArs: 200, percent: 2 })
+ * // → 400
+ */
+declare function computeMarketplaceFee(amountArs: number, rule: MarketplaceFeeRule): number;
+interface PaymentStatusExplanation {
+    /** Spanish summary of the current state — surface to user. */
+    summary: string;
+    /** What the agent should do next. Actionable guidance. */
+    recommendedAction: string;
+    /**
+     * Whether this state is FINAL (no further changes) or transient
+     * (can still flip with another webhook).
+     */
+    final: boolean;
+    /** Whether the buyer paid successfully (approved). */
+    paid: boolean;
+    /**
+     * Whether this is a recoverable rejection (user can retry with another
+     * card / different installments) vs a hard rejection (stop trying).
+     */
+    retryable: boolean;
+}
+/**
+ * Human-readable explanation of a Payment's current state — derives summary,
+ * recommended action, finality, and whether the rejection is retryable from
+ * `payment.status` + `payment.status_detail`.
+ *
+ * Pure function. Use the output to drive agent decisions ("¿reintento?
+ * ¿le digo al cliente que cambie de tarjeta?") without having to memorize
+ * every MP status_detail code.
+ */
+declare function explainPaymentStatus(payment: Payment): PaymentStatusExplanation;
+
+export { type AccountBalance, type AccountInfo, type AccountMovement, type AutoRecurring, type BankAccount, type CardToken, 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, InMemoryStateAdapter, 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, type SubscriptionStateAdapter, type SubscriptionStateRecord, 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 };