@ar-agents/mercadopago 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -487,6 +487,15 @@ interface CreatePreferenceParams {
     expires?: boolean;
     expirationDateFrom?: string;
     expirationDateTo?: string;
+    /**
+     * Marketplace split — if set, funds route to `collector_id` (the seller)
+     * and `marketplaceFee` (in ARS) is credited to the marketplace's MP
+     * account. v0.5+. See `MarketplaceParams` for details.
+     */
+    marketplace?: string;
+    marketplaceFee?: number;
+    /** Seller's MP user_id. Funds route here when set. */
+    collectorId?: string | number;
 }
 declare const CustomerSchema: z.ZodObject<{
     id: z.ZodString;
@@ -799,6 +808,149 @@ interface CreateWebhookParams {
     /** Topic to subscribe to. */
     topic: WebhookTopic | string;
 }
+/**
+ * Token response from MP's OAuth `/oauth/token` endpoint. The `access_token`
+ * is what you use to make API calls AS the linked seller; the `refresh_token`
+ * is what you use to refresh the access_token before expiration (~6 hours).
+ *
+ * **Persist the refresh_token**: it does NOT expire and is the only way to
+ * keep the integration alive long-term.
+ *
+ * **Always store `user_id`** alongside the tokens — it identifies WHICH
+ * seller these tokens belong to (you'll have many in a marketplace).
+ */
+declare const OAuthTokenSchema: z.ZodObject<{
+    access_token: z.ZodString;
+    token_type: z.ZodOptional<z.ZodString>;
+    expires_in: z.ZodOptional<z.ZodNumber>;
+    scope: z.ZodOptional<z.ZodString>;
+    user_id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    refresh_token: z.ZodOptional<z.ZodString>;
+    public_key: z.ZodOptional<z.ZodString>;
+    live_mode: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+type OAuthToken = z.infer<typeof OAuthTokenSchema>;
+/**
+ * Status of an Order. Distinct from Payment status — an Order can have
+ * multiple payments and the Order status reflects the aggregate state.
+ */
+declare const OrderStatusSchema: z.ZodUnion<readonly [z.ZodLiteral<"created">, z.ZodLiteral<"processed">, z.ZodLiteral<"action_required">, z.ZodLiteral<"canceled">, z.ZodLiteral<"expired">, z.ZodLiteral<"refunded">, z.ZodString]>;
+type OrderStatus = z.infer<typeof OrderStatusSchema>;
+declare const OrderItemSchema: z.ZodObject<{
+    title: z.ZodString;
+    unit_price: z.ZodNumber;
+    quantity: z.ZodNumber;
+    description: z.ZodOptional<z.ZodString>;
+    id: z.ZodOptional<z.ZodString>;
+    category_id: z.ZodOptional<z.ZodString>;
+    picture_url: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+type OrderItem = z.infer<typeof OrderItemSchema>;
+declare const OrderSchema: z.ZodObject<{
+    id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    type: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"created">, z.ZodLiteral<"processed">, z.ZodLiteral<"action_required">, z.ZodLiteral<"canceled">, z.ZodLiteral<"expired">, z.ZodLiteral<"refunded">, z.ZodString]>>;
+    status_detail: z.ZodOptional<z.ZodString>;
+    external_reference: z.ZodOptional<z.ZodString>;
+    total_amount: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    currency_id: z.ZodOptional<z.ZodString>;
+    date_created: z.ZodOptional<z.ZodString>;
+    date_last_updated: z.ZodOptional<z.ZodString>;
+    items: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        unit_price: z.ZodNumber;
+        quantity: z.ZodNumber;
+        description: z.ZodOptional<z.ZodString>;
+        id: z.ZodOptional<z.ZodString>;
+        category_id: z.ZodOptional<z.ZodString>;
+        picture_url: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    transactions: z.ZodOptional<z.ZodObject<{
+        payments: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+        refunds: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    }, z.core.$loose>>;
+    capture_mode: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+type Order = z.infer<typeof OrderSchema>;
+interface CreateOrderParams {
+    /**
+     * Order type. Common values:
+     * - "online" — checkout-style (the most common)
+     * - "in_store" — POS QR / in-person
+     */
+    type: "online" | "in_store" | string;
+    /** Currency (e.g. "ARS"). */
+    currency_id?: string;
+    /** External reference for reconciliation (your internal id). */
+    external_reference?: string;
+    /** Items being ordered. */
+    items?: OrderItem[];
+    /** Total amount if you'd rather not itemize. */
+    total_amount?: number;
+    /** Customer info (payer). */
+    payer?: {
+        email?: string;
+        first_name?: string;
+        last_name?: string;
+        identification?: {
+            type?: string;
+            number?: string;
+        };
+    };
+    /**
+     * Capture mode:
+     * - "automatic" (default) — charge immediately when paid.
+     * - "manual" — authorize only, capture later via captureOrder().
+     */
+    capture_mode?: "automatic" | "manual";
+    /**
+     * Notification URL — MP fires webhooks for order lifecycle events here.
+     */
+    notification_url?: string;
+    /**
+     * Marketplace fee + collector — required for marketplace integrations
+     * where YOU collect on behalf of a third-party seller (you take a fee,
+     * the rest goes to the seller).
+     */
+    marketplace?: string;
+    marketplace_fee?: number;
+    collector_id?: string | number;
+}
+/**
+ * Marketplace fee + collector params, applied to a Preference or Order.
+ *
+ * **How it works**: when you create a Preference or Order with
+ * `collector_id` set to a SELLER's MP user_id (not yours), and you have a
+ * valid OAuth access_token for that seller, MP routes the funds to the
+ * seller's MP account, and credits `marketplace_fee` (in ARS, not %) to
+ * YOUR marketplace account.
+ *
+ * Used for two-sided platforms (Rappi, MercadoLibre, Tienda Nube, etc.)
+ * where your platform takes a fee and the seller keeps the rest.
+ */
+interface MarketplaceParams {
+    /**
+     * Marketplace identifier — your application's marketplace name (you set
+     * this when registering your app in MP's dev panel).
+     */
+    marketplace?: string;
+    /**
+     * Fee in ARS (NOT a percentage) that goes to your marketplace account.
+     * Compute it from your own commission rate before passing.
+     */
+    marketplace_fee?: number;
+    /**
+     * The SELLER's MP user_id. The funds go to this account; the
+     * `marketplace_fee` is split off and goes to YOUR account.
+     * Get this from `OAuthToken.user_id` after the seller authorizes your app.
+     */
+    collector_id?: string | number;
+    /**
+     * Optional: split among multiple sellers. If set, `collector_id` /
+     * `marketplace_fee` are ignored.
+     */
+    application_fee?: number;
+}
 
 interface MercadoPagoClientOptions {
     /** Access token. TEST- prefix for sandbox, APP_USR- for production. */
@@ -837,6 +989,20 @@ interface MercadoPagoClientOptions {
         success: boolean;
     }) => void;
 }
+interface RequestOptions {
+    /** Idempotency key. Required for POST/PUT to dedupe retries safely. */
+    idempotencyKey?: string;
+    /** Query string params. Object → URLSearchParams. */
+    query?: Record<string, string | number | undefined>;
+    /** Context for error classification. */
+    classifyContext?: {
+        preapprovalId?: string;
+        paymentId?: string;
+        customerId?: string;
+        payerEmail?: string;
+        sellerEmail?: string;
+    };
+}
 /**
  * Thin, typed wrapper around Mercado Pago's REST API. Exposes the surface
  * the agent layer needs: Subscriptions (Preapprovals), Payments, Checkout Pro
@@ -1097,6 +1263,27 @@ declare class MercadoPagoClient {
         topic?: string;
     }): Promise<WebhookConfig>;
     deleteWebhook(id: string): Promise<void>;
+    /**
+     * Create a new Order. Use `capture_mode: "manual"` for auth-only flows
+     * where you want to capture funds later (ride-share, hotels, marketplaces).
+     *
+     * For marketplace splits, set `marketplace`, `marketplace_fee`,
+     * `collector_id` — see `MarketplaceParams`.
+     */
+    createOrder(params: CreateOrderParams, options?: RequestOptions): Promise<Order>;
+    getOrder(id: string): Promise<Order>;
+    updateOrder(id: string, patch: Partial<CreateOrderParams>): Promise<Order>;
+    /**
+     * Capture a previously-authorized Order (only for orders created with
+     * `capture_mode: "manual"`). Captures up to the originally-authorized
+     * amount; pass `amount` for partial capture.
+     */
+    captureOrder(id: string, amount?: number): Promise<Order>;
+    /**
+     * Cancel an Order. Releases any auth-holds; marks the Order as canceled.
+     * For orders that have already been captured, use `createRefund` instead.
+     */
+    cancelOrder(id: string): Promise<Order>;
 }
 
 /**
@@ -1164,8 +1351,26 @@ interface MercadoPagoToolsOptions {
      * Optional — MP falls back to dashboard config if not set.
      */
     notificationUrl?: string;
+    /**
+     * Webhook secret for the `handle_webhook` tool. Required to verify
+     * incoming webhook HMAC-SHA256 signatures. Get it from MP dev panel →
+     * "Notificaciones" → "Webhooks" → "Configurar notificaciones".
+     * If omitted, `handle_webhook` returns `{ verified: false, error: ... }`
+     * and the agent should reject the webhook.
+     */
+    webhookSecret?: string;
+    /**
+     * OAuth credentials for the marketplace flow. Required for
+     * `oauth_exchange_code` and `oauth_refresh_token` (the secret cannot be
+     * passed by the agent — it's a server-side secret). If omitted, those
+     * tools return `{ available: false }` with setup instructions.
+     */
+    oauth?: {
+        clientId: string;
+        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";
+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";
 /**
  * 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
@@ -1231,4 +1436,116 @@ declare function verifyWebhookSignature(params: {
     secret: string;
 }): boolean;
 
-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 };
+/**
+ * Mercado Pago OAuth flow — for marketplace integrations where YOUR app
+ * cobra a través de cuentas MP de terceros (sellers in your platform).
+ *
+ * # The flow (3 legs)
+ *
+ * 1. **Authorize URL** — Redirect the seller to `buildAuthorizeUrl()`. They
+ *    log in to MP and approve your app. MP redirects them back to your
+ *    `redirect_uri` with `?code=AUTH_CODE&state=YOUR_STATE`.
+ * 2. **Code exchange** — Your server POSTs to `/oauth/token` via
+ *    `exchangeCodeForToken()` with the code. Returns `{ access_token,
+ *    refresh_token, user_id, expires_in (~6h), ... }`. **Persist all of it.**
+ * 3. **Token refresh** — Before `expires_in` runs out (or on 401), call
+ *    `refreshAccessToken()` with the saved `refresh_token` to get a fresh
+ *    access_token. The refresh_token does NOT expire and is the only way
+ *    to keep the integration alive long-term.
+ *
+ * # Per-seller MercadoPagoClient
+ *
+ * Once you have an OAuth `access_token` for a seller, instantiate a
+ * `MercadoPagoClient({ accessToken })` AS THAT SELLER. All API calls then
+ * happen on the seller's behalf — payments, refunds, subscriptions,
+ * everything.
+ *
+ * # Marketplace fee
+ *
+ * To take a fee while collecting on the seller's behalf, pass
+ * `marketplace`, `marketplaceFee`, `collectorId` to `createPreference()`
+ * or `createOrder()`. See `MarketplaceParams` for details.
+ *
+ * # Setup
+ *
+ * 1. Register your application in MP's dev panel
+ *    (https://www.mercadopago.com.ar/developers/panel/applications) to get
+ *    `clientId` (= application id) and `clientSecret`.
+ * 2. Configure the `redirect_uri` whitelist in the same panel — MP rejects
+ *    redirects to URIs not whitelisted.
+ * 3. Pick a `marketplace` identifier (used in fee routing).
+ */
+
+/**
+ * Build the URL the seller visits to authorize your app. Redirect them here.
+ * On approval, MP redirects them to `redirect_uri?code=...&state=...`.
+ *
+ * @param state Optional opaque value echoed back in the redirect — use this
+ *              to bind the OAuth round-trip to a specific user/session and
+ *              prevent CSRF. Always set it in production.
+ */
+declare function buildAuthorizeUrl(params: {
+    /** Your app's client ID (= application id from MP dev panel). */
+    clientId: string;
+    /** Where MP redirects after approval. Must be whitelisted in MP panel. */
+    redirectUri: string;
+    /** CSRF / session-binding token, echoed back. Strongly recommended. */
+    state?: string;
+    /**
+     * Override the authorize endpoint base. Default points to AR; for other
+     * sites use `https://auth.mercadopago.com.{br,mx,co,cl,uy}/authorization`.
+     */
+    authorizeUrl?: string;
+}): string;
+/**
+ * Exchange the authorization code (from the OAuth redirect) for an
+ * `OAuthToken`. POSTs to `/oauth/token` with `grant_type=authorization_code`.
+ *
+ * **Persist the entire response** — the `refresh_token` is the only way to
+ * keep the integration alive long-term, and `user_id` identifies the seller.
+ */
+declare function exchangeCodeForToken(params: {
+    clientId: string;
+    clientSecret: string;
+    /** The `code` query param from the OAuth redirect. */
+    code: string;
+    /** Must match the `redirect_uri` used in `buildAuthorizeUrl`. */
+    redirectUri: string;
+    /** Override the token endpoint (testing). */
+    tokenUrl?: string;
+    /** Custom fetch (testing). */
+    fetchImpl?: typeof fetch;
+}): Promise<OAuthToken>;
+/**
+ * Refresh an access_token using the saved refresh_token. Call this
+ * proactively before `expires_in` runs out, or reactively on a 401 from a
+ * per-seller MercadoPagoClient.
+ *
+ * The new response includes a fresh `refresh_token` — **always persist it,
+ * replacing the old one**, even though MP often returns the same value.
+ */
+declare function refreshAccessToken(params: {
+    clientId: string;
+    clientSecret: string;
+    refreshToken: string;
+    tokenUrl?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<OAuthToken>;
+/**
+ * Compute when an access_token will expire, given the timestamp it was
+ * issued and the `expires_in` value (in seconds).
+ *
+ * @returns A unix-ms timestamp.
+ */
+declare function expirationTimeMs(issuedAtMs: number, expiresInSeconds: number | undefined): number;
+/**
+ * Check whether an access_token is close to expiring. Use this to decide
+ * whether to proactively refresh BEFORE making an API call.
+ *
+ * @param skewSeconds Buffer to refresh early (default 5 min). MP tokens
+ *                    typically last 6h; refreshing in the last 5 min avoids
+ *                    races with API calls that take a few seconds.
+ */
+declare function isExpiringSoon(expirationMs: number, skewSeconds?: number): boolean;
+
+export { type AccountInfo, 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 SiteId, type Store, type SubscriptionPayment, type SubscriptionPlan, type SubscriptionStateAdapter, type SubscriptionStateRecord, type WebhookBody, type WebhookConfig, type WebhookTopic, buildAuthorizeUrl, classifyError, exchangeCodeForToken, expirationTimeMs, isExpiringSoon, mercadoPagoTools, parseWebhookEvent, refreshAccessToken, verifyWebhookSignature };