@ar-agents/mercadopago 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -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>>;
@@ -572,6 +633,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 +668,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 +771,55 @@ 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>;
 }
 
 /**
@@ -752,7 +888,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";
 /**
  * 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 +954,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 CreatePreapprovalParams, type CreatePreferenceParams, type CreateQrPaymentParams, type CreateRefundParams, type CurrencyId, type Customer, type CustomerCard, type FrequencyType, InMemoryStateAdapter, type InstallmentOffer, 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 Preapproval, type PreapprovalStatus, type Preference, type PreferenceItem, type QrOrder, type Refund, type SearchPaymentsParams, type SiteId, type SubscriptionStateAdapter, type SubscriptionStateRecord, type WebhookBody, classifyError, mercadoPagoTools, parseWebhookEvent, verifyWebhookSignature };

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>>;
@@ -572,6 +633,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 +668,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 +771,55 @@ 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>;
 }
 
 /**
@@ -752,7 +888,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";
 /**
  * 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 +954,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 CreatePreapprovalParams, type CreatePreferenceParams, type CreateQrPaymentParams, type CreateRefundParams, type CurrencyId, type Customer, type CustomerCard, type FrequencyType, InMemoryStateAdapter, type InstallmentOffer, 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 Preapproval, type PreapprovalStatus, type Preference, type PreferenceItem, type QrOrder, type Refund, type SearchPaymentsParams, type SiteId, type SubscriptionStateAdapter, type SubscriptionStateRecord, type WebhookBody, classifyError, mercadoPagoTools, parseWebhookEvent, verifyWebhookSignature };