@ar-agents/mercadopago 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -66,6 +66,23 @@ declare class MercadoPagoRateLimitError extends MercadoPagoError {
     retryAfterSeconds: number | null;
     constructor(endpoint: string, retryAfterSeconds: number | null, body?: unknown);
 }
+/**
+ * Thrown when MP is overloaded and serves an HTML 503 page instead of a JSON
+ * error. The library detects content-type !== application/json on 5xx and
+ * raises this typed error so retry logic + agent UX can branch correctly.
+ */
+declare class MercadoPagoOverloadedError extends MercadoPagoError {
+    constructor(endpoint: string, status: number);
+}
+/**
+ * Thrown when a request exceeds the configured `requestTimeoutMs`. Retried
+ * automatically up to `maxRetries`; this surfaces only when the budget runs
+ * out.
+ */
+declare class MercadoPagoTimeoutError extends MercadoPagoError {
+    readonly timeoutMs: number;
+    constructor(endpoint: string, timeoutMs: number);
+}
 /**
  * Maps an MP error response body to the most specific known error class. Falls
  * back to the generic MercadoPagoError when no specific pattern matches.
@@ -546,6 +563,50 @@ declare const InstallmentOfferSchema: z.ZodObject<{
     }, z.core.$loose>>;
 }, z.core.$loose>;
 type InstallmentOffer = z.infer<typeof InstallmentOfferSchema>;
+declare const QrOrderSchema: z.ZodObject<{
+    in_store_order_id: z.ZodString;
+    qr_data: z.ZodString;
+}, z.core.$loose>;
+type QrOrder = z.infer<typeof QrOrderSchema>;
+interface CreateQrPaymentParams {
+    /** Pre-configured POS external_id from MP dashboard. Required. */
+    externalPosId: string;
+    /** Total amount in ARS. */
+    totalAmount: number;
+    /** Display title shown to the buyer when scanning. */
+    title: string;
+    description?: string;
+    /** Webhook URL — MP fires `point_integration_wh` then `payment` topic. */
+    notificationUrl?: string;
+    /** Your-system identifier for correlation. */
+    externalReference?: string;
+    /** ISO 8601 expiration (default 10 min from now). */
+    expirationDate?: string;
+    /** Itemized line items (optional but improves analytics). */
+    items?: Array<{
+        title: string;
+        quantity: number;
+        unit_price: number;
+        unit_measure?: string;
+        total_amount?: number;
+    }>;
+}
+declare const CardTokenSchema: z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodOptional<z.ZodString>;
+    date_due: z.ZodOptional<z.ZodString>;
+    card_id: z.ZodOptional<z.ZodString>;
+    cardholder: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$loose>;
+type CardToken = z.infer<typeof CardTokenSchema>;
+interface CreateCardTokenParams {
+    /** Saved card id (from list_customer_cards). */
+    cardId: string;
+    /** Customer that owns the card. */
+    customerId: string;
+    /** CVV — required for AR; MP doesn't store CVV. */
+    securityCode: string;
+}
 declare const AccountInfoSchema: z.ZodObject<{
     id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
     email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -558,6 +619,186 @@ declare const AccountInfoSchema: z.ZodObject<{
     }, z.core.$loose>>>;
 }, z.core.$loose>;
 type AccountInfo = z.infer<typeof AccountInfoSchema>;
+/**
+ * A reusable subscription plan. Different from a per-customer subscription:
+ * a plan defines the price + frequency once, then customers subscribe to it
+ * via `subscribe_to_plan` (which creates a preapproval pointing at the plan).
+ *
+ * Use plans for SaaS-style billing where you have a fixed set of tiers
+ * (Básico/Pro/Enterprise) instead of negotiating amounts per customer.
+ */
+declare const SubscriptionPlanSchema: z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodString;
+    reason: z.ZodString;
+    back_url: z.ZodOptional<z.ZodString>;
+    external_reference: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    date_created: z.ZodString;
+    last_modified: z.ZodString;
+    auto_recurring: z.ZodObject<{
+        frequency: z.ZodNumber;
+        frequency_type: z.ZodEnum<{
+            months: "months";
+            days: "days";
+        }>;
+        transaction_amount: z.ZodNumber;
+        currency_id: z.ZodEnum<{
+            ARS: "ARS";
+            USD: "USD";
+            BRL: "BRL";
+            MXN: "MXN";
+        }>;
+        start_date: z.ZodOptional<z.ZodString>;
+        end_date: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$loose>;
+type SubscriptionPlan = z.infer<typeof SubscriptionPlanSchema>;
+interface CreateSubscriptionPlanParams {
+    /** Customer-facing plan name shown at checkout. */
+    reason: string;
+    /** Where MP redirects buyer after first payment. HTTPS only. */
+    backUrl: string;
+    /** Recurrence (e.g., 1 + months = monthly). */
+    frequency: number;
+    frequencyType: FrequencyType;
+    /** Amount per cycle. */
+    amount: number;
+    /** ARS for AR. */
+    currency: CurrencyId;
+    /** Optional plan-level identifier from your system. */
+    externalReference?: string;
+    /** Free trial days before first charge. */
+    freeTrialFrequency?: number;
+    freeTrialFrequencyType?: FrequencyType;
+}
+declare const StoreSchema: z.ZodObject<{
+    id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    name: z.ZodOptional<z.ZodString>;
+    external_id: z.ZodOptional<z.ZodString>;
+    date_creation: z.ZodOptional<z.ZodString>;
+    location: z.ZodOptional<z.ZodObject<{
+        address_line: z.ZodOptional<z.ZodString>;
+        city_name: z.ZodOptional<z.ZodString>;
+        state_name: z.ZodOptional<z.ZodString>;
+        country_id: z.ZodOptional<z.ZodString>;
+        latitude: z.ZodOptional<z.ZodNumber>;
+        longitude: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+type Store = z.infer<typeof StoreSchema>;
+interface CreateStoreParams {
+    /** Display name for the store. */
+    name: string;
+    /** Caller-defined identifier (must be unique within the seller's stores). */
+    externalId: string;
+    /** Optional physical location. */
+    location?: {
+        addressLine?: string;
+        cityName?: string;
+        stateName?: string;
+        countryId?: string;
+        latitude?: number;
+        longitude?: number;
+    };
+}
+declare const PosSchema: z.ZodObject<{
+    id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    name: z.ZodOptional<z.ZodString>;
+    external_id: z.ZodOptional<z.ZodString>;
+    store_id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    category: z.ZodOptional<z.ZodNumber>;
+    fixed_amount: z.ZodOptional<z.ZodBoolean>;
+    qr: z.ZodOptional<z.ZodObject<{
+        template_image: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    date_creation: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+type Pos = z.infer<typeof PosSchema>;
+interface CreatePosParams {
+    /** Display name. */
+    name: string;
+    /** Caller-defined POS id (used in QR endpoints; unique within store). */
+    externalId: string;
+    /** Parent store id (number from createStore). */
+    storeId: string | number;
+    /** MP category code (default 621102 = Other Food and Beverage Services). */
+    category?: number;
+    /** If true, the QR has a fixed amount; if false, dynamic per-order. */
+    fixedAmount?: boolean;
+}
+declare const DisputeSchema: z.ZodObject<{
+    id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    status: z.ZodString;
+    resource: z.ZodOptional<z.ZodString>;
+    resource_id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    amount: z.ZodOptional<z.ZodNumber>;
+    date_created: z.ZodOptional<z.ZodString>;
+    reason: z.ZodOptional<z.ZodString>;
+    resolution: z.ZodOptional<z.ZodObject<{
+        reason: z.ZodOptional<z.ZodString>;
+        result: z.ZodOptional<z.ZodString>;
+        date: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    documents: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    reason_description: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+type Dispute = z.infer<typeof DisputeSchema>;
+declare const SubscriptionPaymentSchema: z.ZodObject<{
+    id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    preapproval_id: z.ZodOptional<z.ZodString>;
+    status: z.ZodString;
+    payment_id: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+    transaction_amount: z.ZodOptional<z.ZodNumber>;
+    currency_id: z.ZodOptional<z.ZodString>;
+    date_created: z.ZodOptional<z.ZodString>;
+    debit_date: z.ZodOptional<z.ZodString>;
+    next_retry_date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    retry_attempt: z.ZodOptional<z.ZodNumber>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+type SubscriptionPayment = z.infer<typeof SubscriptionPaymentSchema>;
+declare const IdentificationTypeSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    type: z.ZodString;
+    min_length: z.ZodOptional<z.ZodNumber>;
+    max_length: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+type IdentificationType = z.infer<typeof IdentificationTypeSchema>;
+declare const IssuerSchema: z.ZodObject<{
+    id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    name: z.ZodString;
+    secure_thumbnail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    thumbnail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    processing_mode: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+type Issuer = z.infer<typeof IssuerSchema>;
+/** Topics MP can fire webhooks for. Add more as MP exposes them. */
+declare const WebhookTopicSchema: z.ZodEnum<{
+    payment: "payment";
+    subscription_authorized_payment: "subscription_authorized_payment";
+    subscription_preapproval: "subscription_preapproval";
+    merchant_order: "merchant_order";
+    point_integration_wh: "point_integration_wh";
+    stop_delivery_op_wh: "stop_delivery_op_wh";
+}>;
+type WebhookTopic = z.infer<typeof WebhookTopicSchema>;
+declare const WebhookConfigSchema: z.ZodObject<{
+    id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    url: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodString>;
+    topic: z.ZodOptional<z.ZodString>;
+    date_created: z.ZodOptional<z.ZodString>;
+    date_modified: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+type WebhookConfig = z.infer<typeof WebhookConfigSchema>;
+interface CreateWebhookParams {
+    url: string;
+    /** Topic to subscribe to. */
+    topic: WebhookTopic | string;
+}
 
 interface MercadoPagoClientOptions {
     /** Access token. TEST- prefix for sandbox, APP_USR- for production. */
@@ -572,6 +813,29 @@ interface MercadoPagoClientOptions {
      * inject your own retry/instrumentation layer or to test with MSW.
      */
     fetch?: typeof fetch;
+    /**
+     * Per-request timeout in ms. Aborts the request and throws if exceeded.
+     * Default 30_000 (30s). MP can be slow under load; 30s is a safe upper bound.
+     */
+    requestTimeoutMs?: number;
+    /**
+     * Number of retries on 5xx + network errors. Default 1 (single retry).
+     * 4xx errors are NEVER retried (they're user/config errors). Each retry
+     * uses exponential backoff: 250ms, 500ms, 1000ms, ...
+     */
+    maxRetries?: number;
+    /**
+     * Observability hook fired AFTER every request (success or failure).
+     * Useful for logging, metrics, tracing. Synchronous, fire-and-forget.
+     */
+    onCall?: (event: {
+        method: string;
+        path: string;
+        durationMs: number;
+        httpStatus: number | null;
+        retried: number;
+        success: boolean;
+    }) => void;
 }
 /**
  * Thin, typed wrapper around Mercado Pago's REST API. Exposes the surface
@@ -584,6 +848,9 @@ declare class MercadoPagoClient {
     private readonly accessToken;
     private readonly baseUrl;
     private readonly fetchImpl;
+    private readonly requestTimeoutMs;
+    private readonly maxRetries;
+    private readonly onCall;
     constructor(options: MercadoPagoClientOptions);
     private request;
     /**
@@ -684,6 +951,152 @@ declare class MercadoPagoClient {
     }): Promise<InstallmentOffer[]>;
     /** Get info about the account that owns this access token. */
     getMe(): Promise<AccountInfo>;
+    /**
+     * Create a single-use card token from a saved card. This is the server-side
+     * retokenization path (PCI-safe because the card data lives in MP's vault,
+     * we only pass the saved card_id + customer_id + the user-supplied CVV).
+     *
+     * Tokens expire in 7 days but typically burn on first use. AR currently
+     * REQUIRES CVV on every charge (MP doesn't store it); skipping CVV requires
+     * a private MP product enablement, not a public API.
+     */
+    createCardToken(params: CreateCardTokenParams): Promise<CardToken>;
+    /**
+     * High-level helper: charge a saved card in 3 steps.
+     * 1. Mint a card token from {customer_id, card_id, security_code}
+     * 2. Lookup card to fill payment_method_id (avoids agent guessing)
+     * 3. Create the payment with the token + idempotency key
+     *
+     * Returns the resulting Payment. Uses deterministic idempotency from
+     * (card_id, amount, externalReference) so retries dedupe on MP's side.
+     */
+    chargeSavedCard(params: {
+        customerId: string;
+        cardId: string;
+        securityCode: string;
+        amount: number;
+        description: string;
+        installments?: number;
+        externalReference?: string;
+        statementDescriptor?: string;
+        idempotencyKey?: string;
+    }): Promise<Payment>;
+    /**
+     * Create a dynamic in-store QR order. Returns `qr_data` (EMVCo TLV string)
+     * + `in_store_order_id`. The buyer scans the QR with any AR wallet (Modo,
+     * BNA+, Cuenta DNI, Naranja X, etc. — interop is mandated by Transferencias
+     * 3.0). On payment, MP fires `point_integration_wh` then `payment` topics.
+     *
+     * Requires a pre-configured POS (`external_pos_id` from MP dashboard or
+     * `POST /pos`). The seller's `user_id` is auto-fetched from `/users/me`.
+     *
+     * The lib does NOT render the QR image — pass `qr_data` to a QR renderer
+     * (e.g., `qrcode` package) to get a data URL. The agent tool layer wraps
+     * this and returns both raw + data URL.
+     */
+    createQrPayment(userId: string, params: CreateQrPaymentParams): Promise<QrOrder>;
+    /**
+     * Cancel a pending QR order on a POS. Necessary if the buyer never scans
+     * — otherwise the next `createQrPayment` on the same POS returns 409.
+     */
+    cancelQrPayment(userId: string, externalPosId: string): Promise<void>;
+    /**
+     * Create a reusable subscription plan. Customers later subscribe to it via
+     * `subscribeToPlan` (which creates a preapproval pointing at the plan).
+     *
+     * Use this when you have fixed tiers (Básico/Pro/Enterprise). For custom
+     * per-customer amounts, skip plans and use `createPreapproval` directly.
+     */
+    createSubscriptionPlan(params: CreateSubscriptionPlanParams): Promise<SubscriptionPlan>;
+    getSubscriptionPlan(id: string): Promise<SubscriptionPlan>;
+    listSubscriptionPlans(params?: {
+        limit?: number;
+        offset?: number;
+        status?: string;
+    }): Promise<{
+        paging: {
+            total: number;
+            limit: number;
+            offset: number;
+        };
+        results: SubscriptionPlan[];
+    }>;
+    updateSubscriptionPlan(id: string, patch: {
+        reason?: string;
+        status?: "active" | "cancelled";
+        amount?: number;
+        backUrl?: string;
+    }): Promise<SubscriptionPlan>;
+    /**
+     * Subscribe a customer to an existing plan. Returns a Preapproval with
+     * `init_point` URL where the buyer completes the first payment.
+     */
+    subscribeToPlan(params: {
+        planId: string;
+        payerEmail: string;
+        cardTokenId?: string;
+        externalReference?: string;
+    }): Promise<Preapproval>;
+    /**
+     * List the auto-charge attempts (authorized_payments) under a preapproval.
+     * Useful for "show me the cobros of the last 6 months for this client".
+     */
+    listSubscriptionPayments(preapprovalId: string, params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        paging: {
+            total: number;
+            limit: number;
+            offset: number;
+        };
+        results: SubscriptionPayment[];
+    }>;
+    /** Create a store for the seller. POSes (for QR) live under stores. */
+    createStore(userId: string, params: CreateStoreParams): Promise<Store>;
+    listStores(userId: string, params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        paging: {
+            total: number;
+            limit: number;
+            offset: number;
+        };
+        results: Store[];
+    }>;
+    /** Create a POS under a store. The POS's `external_id` is what `createQrPayment` uses. */
+    createPos(params: CreatePosParams): Promise<Pos>;
+    listPos(params?: {
+        storeId?: string | number;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        paging: {
+            total: number;
+            limit: number;
+            offset: number;
+        };
+        results: Pos[];
+    }>;
+    listPaymentDisputes(paymentId: string): Promise<Dispute[]>;
+    getDispute(paymentId: string, disputeId: string): Promise<Dispute>;
+    /** List valid identification types for the seller's site. AR returns DNI/CI/LE/LC/Otro/Pasaporte/CUIT/CUIL. */
+    listIdentificationTypes(): Promise<IdentificationType[]>;
+    /** List card issuers for a payment method. Useful with `bin` for installments. */
+    listIssuers(params: {
+        paymentMethodId: string;
+        bin?: string;
+    }): Promise<Issuer[]>;
+    /** List configured webhook subscriptions. */
+    listWebhooks(): Promise<WebhookConfig[]>;
+    /** Create a webhook subscription for a topic. */
+    createWebhook(params: CreateWebhookParams): Promise<WebhookConfig>;
+    updateWebhook(id: string, patch: {
+        url?: string;
+        topic?: string;
+    }): Promise<WebhookConfig>;
+    deleteWebhook(id: string): Promise<void>;
 }
 
 /**
@@ -752,7 +1165,7 @@ interface MercadoPagoToolsOptions {
      */
     notificationUrl?: 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";
+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";
 /**
  * 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
@@ -818,4 +1231,4 @@ declare function verifyWebhookSignature(params: {
     secret: string;
 }): boolean;
 
-export { type AccountInfo, type AutoRecurring, type CreateCustomerParams, type CreatePaymentParams, type CreatePreapprovalParams, type CreatePreferenceParams, type CreateRefundParams, type CurrencyId, type Customer, type CustomerCard, type FrequencyType, InMemoryStateAdapter, type InstallmentOffer, MercadoPagoAccountTypeMismatchError, MercadoPagoAuthError, MercadoPagoAuthorizeForbiddenError, MercadoPagoBackUrlInvalidError, MercadoPagoClient, type MercadoPagoClientOptions, MercadoPagoError, MercadoPagoPaymentRejectedError, MercadoPagoRateLimitError, MercadoPagoSelfPaymentError, type MercadoPagoToolsOptions, type ParsedWebhookEvent, type Payment, type PaymentMethod, type PaymentStatus, type PaymentsSearchResult, type Preapproval, type PreapprovalStatus, type Preference, type PreferenceItem, type Refund, type SearchPaymentsParams, type SiteId, type SubscriptionStateAdapter, type SubscriptionStateRecord, type WebhookBody, classifyError, mercadoPagoTools, parseWebhookEvent, verifyWebhookSignature };
+export { type AccountInfo, type AutoRecurring, type CardToken, type CreateCardTokenParams, type CreateCustomerParams, 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, MercadoPagoAccountTypeMismatchError, MercadoPagoAuthError, MercadoPagoAuthorizeForbiddenError, MercadoPagoBackUrlInvalidError, MercadoPagoClient, type MercadoPagoClientOptions, MercadoPagoError, MercadoPagoOverloadedError, MercadoPagoPaymentRejectedError, MercadoPagoRateLimitError, MercadoPagoSelfPaymentError, MercadoPagoTimeoutError, type MercadoPagoToolsOptions, 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 SiteId, type Store, type SubscriptionPayment, type SubscriptionPlan, type SubscriptionStateAdapter, type SubscriptionStateRecord, type WebhookBody, type WebhookConfig, type WebhookTopic, classifyError, mercadoPagoTools, parseWebhookEvent, verifyWebhookSignature };