@ar-agents/mercadopago 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 0.14.0
+
+### Minor Changes — deep-audit hardening pass
+
+**Critical: Browser-context guard in MercadoPagoClient constructor.**
+Throws if instantiated in a context where `window` is defined — prevents
+the access token from being bundled into a client-side JavaScript bundle.
+Edge Runtime, Node, Workers, and any server context pass through. To
+opt out for jsdom-based tests, pass `__allowBrowser: true`.
+
+**`z.unknown()` schemas replaced with strict Zod.** Two tools previously
+used `z.record(z.string(), z.unknown())`:
+- `update_merchant_order.patch` → narrow object with documented MP fields
+  (`external_reference`, `notification_url`, `additional_info`, `status`),
+  `.strict()` so unknown keys are rejected.
+- `explain_payment_status.payment` → typed shape with `.passthrough()` for
+  ergonomic interop, marked clearly as ADVANCED — LLMs should use
+  `payment_id` instead.
+
+**Stricter validation on `search_payments`:**
+- `payer_email` now requires `.email()` (was bare `z.string()`).
+- `begin_date` / `end_date` now require `.datetime()` ISO 8601.
+
+**Deterministic idempotency on subscription + preference creation.**
+`create_subscription` and `create_payment_preference` now derive their
+idempotency key from input fields (customer_email + amount + frequency
+for subscriptions; items + payer + external_reference for preferences).
+LLM retries with the same inputs return the EXISTING resource instead
+of creating a duplicate.
+
+**Human-in-the-loop warnings on irreversible / money-moving tools.**
+Updated 7 tool descriptions to explicitly tell the LLM to confirm with
+the user before calling: `cancel_payment`, `capture_payment`,
+`refund_payment`, `delete_customer_card`, `cancel_qr_payment`,
+`cancel_order`, `cancel_point_payment_intent`, `delete_webhook`. Each
+description now states what's irreversible, what the user should be
+told before confirmation, and what the post-call state is.
+
+`CreatePreapprovalParams` and `CreatePreferenceParams` now accept an
+optional `idempotencyKey` field for callers that want explicit control.
+
 ## 0.13.0
 
 ### Minor Changes — Distributed rate limiter via Vercel KV

package/dist/index.cjs

@@ -255,6 +255,12 @@ var MercadoPagoClient = class {
   circuitBreaker;
   traceContext;
   constructor(options) {
+    const w = globalThis.window;
+    if (typeof w !== "undefined" && !options.__allowBrowser) {
+      throw new Error(
+        "MercadoPagoClient must NEVER be instantiated in a browser context \u2014 the access token would be exposed in the JavaScript bundle and visible to anyone in DevTools. Use a Server Component, Route Handler, Server Action, or any server-only execution context. If you're running in jsdom for tests and KNOW this is safe, pass `__allowBrowser: true`."
+      );
+    }
     if (!options.accessToken) {
       throw new Error(
         "MercadoPagoClient requires an accessToken. Get one from https://www.mercadopago.com.ar/developers/panel/credentials"
@@ -453,7 +459,10 @@ var MercadoPagoClient = class {
           currency_id: params.currency
         }
       },
-      { classifyContext: { payerEmail: params.payerEmail } }
+      {
+        ...params.idempotencyKey ? { idempotencyKey: params.idempotencyKey } : {},
+        classifyContext: { payerEmail: params.payerEmail }
+      }
     );
   }
   async getPreapproval(id) {
@@ -649,7 +658,12 @@ var MercadoPagoClient = class {
     if (params.marketplace) body.marketplace = params.marketplace;
     if (params.marketplaceFee !== void 0) body.marketplace_fee = params.marketplaceFee;
     if (params.collectorId !== void 0) body.collector_id = params.collectorId;
-    return this.request("POST", "/checkout/preferences", body);
+    return this.request(
+      "POST",
+      "/checkout/preferences",
+      body,
+      params.idempotencyKey ? { idempotencyKey: params.idempotencyKey } : void 0
+    );
   }
   async getPreference(id) {
     return this.request("GET", `/checkout/preferences/${id}`);
@@ -3030,10 +3044,10 @@ var DEFAULT_DESCRIPTIONS = {
   create_payment: "Create a one-time payment. Two flows: (a) with a card token from MP frontend Cardform \u2014 for transparent checkout; (b) without token, for non-card methods like 'account_money', 'rapipago', 'pagofacil'. For most agent flows where you only have a payer email and want to send them a payment link, use create_payment_preference instead (Checkout Pro hosted form). Returns the Payment object with status \u2014 typically 'approved' for account_money and 'pending' for tickets.",
   get_payment: "Fetch a single payment by ID. Use to confirm status after webhook arrives, or to inspect details (status_detail explains rejections).",
   search_payments: "Search payments with filters. Most common: by external_reference (your-system identifier) to find all payments for an order, or by status='approved' to list successful charges in a date range. Returns paginated results.",
-  cancel_payment: "Cancel a pending or in_process payment (only works before approval). Once approved, use refund_payment instead. Common use: cancel an unpaid ticket payment that's still pending.",
-  capture_payment: "Capture an authorized credit-card payment that was created with capture=false. Use for hold-then-capture flows (e.g., authorize on order, capture on shipment). Optional partial amount.",
+  cancel_payment: "Cancel a pending or in_process payment (only works before approval). Once approved, use refund_payment instead. Common use: cancel an unpaid ticket payment that's still pending. **IRREVERSIBLE \u2014 confirm with the user before calling. Surface the payment_id, amount, payer_email, and current status, ask 's\xED, cancel\xE1' (or equivalent), then proceed.**",
+  capture_payment: "Capture an authorized credit-card payment that was created with capture=false. Use for hold-then-capture flows (e.g., authorize on order, capture on shipment). Optional partial amount. **MOVES MONEY \u2014 confirm the amount with the user before calling.**",
   // ── Refunds ──────────────────────────────────────────────────────────────
-  refund_payment: "Refund an approved payment. Pass amount for partial refund; omit for full refund. Idempotency key is auto-generated based on paymentId+amount to prevent double-refunds on retries.",
+  refund_payment: "Refund an approved payment. Pass amount for partial refund; omit for full refund. Idempotency key is auto-generated based on paymentId+amount to prevent double-refunds on retries. **IRREVERSIBLE AND MOVES MONEY \u2014 confirm with the user before calling. Restate the payment_id, the refund amount (full vs partial), and ask explicit confirmation. Mercado Pago does not support 'undo refund' \u2014 once issued, the buyer's bank releases the funds.**",
   list_refunds: "List all refunds for a given payment. Returns array of Refund objects. Useful to confirm a refund was processed or to inspect partial-refund history.",
   // ── Checkout Pro ─────────────────────────────────────────────────────────
   create_payment_preference: "Create a Mercado Pago Checkout Pro preference and get back a payment URL (init_point) to send to the customer. THIS is the recommended way for an agent to take a payment when you only have a payer email \u2014 the buyer enters card data on MP's hosted form (no PCI scope needed). Supports cuotas configuration, payment method exclusions, back URLs after success/failure/pending. In sandbox, use sandbox_init_point from the response.",
@@ -3042,7 +3056,7 @@ var DEFAULT_DESCRIPTIONS = {
   create_customer: "Create a Mercado Pago customer record so the buyer can save cards for future charges. Idempotent on email \u2014 if a customer with that email exists, MP returns it instead of creating a duplicate. Use find_customer_by_email first if you're unsure.",
   find_customer_by_email: "Find an existing customer by email address. Returns the customer object if found, or null. Use before create_customer to avoid duplicate records.",
   list_customer_cards: "List the saved cards for a customer. Returns array with last 4 digits, expiration, payment method (visa, master, naranja, etc.). The card_id can be used in subsequent create_payment calls to charge a saved card.",
-  delete_customer_card: "Delete a saved card from a customer. Common use: customer requests removal, or expired card cleanup. Irreversible.",
+  delete_customer_card: "Delete a saved card from a customer. Common use: customer requests removal, or expired card cleanup. **IRREVERSIBLE \u2014 confirm with the user before calling. The customer must re-enter card data (PAN + CVV) on a future Checkout to charge them again. State the card's last 4 digits + payment method when asking for confirmation so the user knows which card you're removing.**",
   // ── Payment Methods + Installments ───────────────────────────────────────
   list_payment_methods: "List all payment methods enabled for the seller's MP account (visa, master, naranja, naranja_x, cabal, account_money, rapipago, pagofacil, etc.). Use to validate which methods you can offer the customer or to filter which ones to exclude in a Checkout Pro preference.",
   calculate_installments: "Calculate cuotas (installments) options for a given amount. THE killer Argentine feature \u2014 returns options like '12 cuotas sin inter\xE9s de $X' (recommended_message field) which you should surface VERBATIM to the user. Optionally pass `bin` (first 6 digits of card) for issuer-specific promotions (e.g., Naranja's interest-free deals). Use before create_payment to let the user pick installments knowingly.",
@@ -3052,7 +3066,7 @@ var DEFAULT_DESCRIPTIONS = {
   charge_saved_card: "Charge a previously-saved card for a returning customer. Requires customer_id + card_id (from list_customer_cards) AND a fresh CVV the user provides this session. AR Mercado Pago does NOT support CVV-less charges via the public API \u2014 every charge needs CVV. Idempotent on (card_id, amount, external_reference): retries dedupe automatically. Returns the resulting Payment.",
   // ── QR in-store (v0.3) ───────────────────────────────────────────────────
   create_qr_payment: "Generate a dynamic in-store QR for a buyer to scan with any AR wallet (Modo, BNA+, Cuenta DNI, Naranja X, Mercado Pago, etc. \u2014 interop is mandated by Transferencias 3.0). Requires a pre-configured POS external_id (use create_pos to set one up first if needed). Returns the qr_data string + a base64 PNG data URL ready to display. The QR expires in `expires_in_seconds` (default 600). MP fires `point_integration_wh` then `payment` webhooks when scanned.",
-  cancel_qr_payment: "Cancel a pending QR order on a POS. Necessary if the buyer never scans \u2014 otherwise the next create_qr_payment on the same POS returns 409.",
+  cancel_qr_payment: "Cancel a pending QR order on a POS. Necessary if the buyer never scans \u2014 otherwise the next create_qr_payment on the same POS returns 409. **IRREVERSIBLE \u2014 but low-stakes since the QR has not been paid yet. Confirm before calling if the user is mid-flow.**",
   // ── Subscription Plans (v0.4) ────────────────────────────────────────────
   create_subscription_plan: "Create a REUSABLE subscription plan (preapproval_plan). Different from create_subscription: a plan defines price + frequency once, then customers subscribe to it via subscribe_to_plan. Use plans for SaaS-style billing (B\xE1sico/Pro/Enterprise tiers). For per-customer custom amounts, use create_subscription directly.",
   list_subscription_plans: "List all subscription plans defined for this MP account. Useful before create_subscription_plan to check if one already exists, or for surfacing options to a customer.",
@@ -3074,7 +3088,7 @@ var DEFAULT_DESCRIPTIONS = {
   list_webhooks: "List all webhook subscriptions configured for this MP application. Use to see what topics + URLs are wired before adding new ones.",
   create_webhook: "Subscribe a webhook URL to a MP topic (payment, subscription_authorized_payment, subscription_preapproval, merchant_order, point_integration_wh). MP will POST to this URL when events of that topic fire.",
   update_webhook: "Update a webhook's URL or topic. Useful when you change deployment URLs without resubscribing from scratch.",
-  delete_webhook: "Delete a webhook subscription. MP stops POSTing to it immediately.",
+  delete_webhook: "Delete a webhook subscription. MP stops POSTing to it immediately. **IRREVERSIBLE \u2014 confirm before calling. State the webhook URL + topic so the user knows which subscription is being removed. Re-subscribing requires a new create_webhook call.**",
   // ── Webhook handler combo (v0.5) ─────────────────────────────────────────
   handle_webhook: "Process an incoming MP webhook in ONE call: verify the HMAC-SHA256 signature, parse the event, and (optionally) auto-fetch the underlying resource (Payment, Subscription, Order). Returns the structured event PLUS the full resource. USE THIS in your webhook endpoint INSTEAD of chaining verify_webhook_signature + parse_webhook_event + get_payment manually. Pass the raw request body, x-signature header, x-request-id header, and your MP webhook secret. SAFE: returns { verified: false } when signature mismatches \u2014 caller should respond 401 and stop processing. WHEN auto_fetch is true (default), the resource is fetched as the SAME MP user the client is configured for (so for marketplace integrations, instantiate a per-seller client).",
   // ── OAuth Marketplace (v0.5) ─────────────────────────────────────────────
@@ -3086,7 +3100,7 @@ var DEFAULT_DESCRIPTIONS = {
   get_order: "Fetch an Order by ID. Returns the Order with its lifecycle status and any attached payments/refunds.",
   update_order: "Patch an existing Order before it's captured/canceled. Common use: update items or external_reference.",
   capture_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. Common use: ride-share marks ride complete \u2192 capture; hotel checks-out guest \u2192 capture.",
-  cancel_order: "Cancel an Order. Releases any auth-holds and marks the Order as canceled. For orders that have already been CAPTURED, use refund_payment instead \u2014 cancel only works pre-capture.",
+  cancel_order: "Cancel an Order. Releases any auth-holds and marks the Order as canceled. For orders that have already been CAPTURED, use refund_payment instead \u2014 cancel only works pre-capture. **IRREVERSIBLE \u2014 confirm with the user. State the order_id, total_amount, and current status before asking 's\xED, cancel\xE1'. The buyer's hold is released to their bank within 24-72h depending on issuer.**",
   // ── Account / Balance / Movements / Settlements (v0.6) ───────────────────
   get_account_balance: "Get the seller's current MP wallet balance. Returns { available_balance, unavailable_balance, total_amount, currency_id }. The available balance is what the seller can withdraw or pay with right now; unavailable is in retention (typically 14-21 days for new sellers or risk-flagged transactions). For per-seller marketplace setups, instantiate the client AS THE SELLER first.",
   list_account_movements: "List wallet movements (incoming payments, transfers, refunds, holdings) for the active MP account. Filter by date range with `from`/`to` (ISO 8601). Useful for monthly conciliation or 'show me what came in this month' workflows.",
@@ -3126,7 +3140,7 @@ var DEFAULT_DESCRIPTIONS = {
   update_point_device_mode: "Switch a Point device's operating_mode between 'PDV' (bound to a logical POS, takes payments triggered through that POS) and 'STANDALONE' (works independently, accepts any payment). PDV is for cash-register integrations; STANDALONE is for free-form retail. Affects how payments hit the device.",
   create_point_payment_intent: "Create a payment intent on a physical Point device \u2014 the device prompts the buyer to tap/insert/swipe their card. Returns immediately with intent_id; query state via get_point_payment_intent or wait for point_integration_wh webhook. **AMOUNT IS IN CENTAVOS**, NOT pesos (Point API differs from Payments API): 100 = $1, 1000 = $10, 10000 = $100.",
   get_point_payment_intent: "Get the current state of a Point payment intent (OPEN, PROCESSING, FINISHED, CANCELED, ERROR). USE in polling loops if you can't wait for the webhook. When state=FINISHED, the intent.payment.id is the resulting Payment id usable with get_payment.",
-  cancel_point_payment_intent: "Cancel an OPEN point payment intent before the buyer interacts with the device. ONLY WORKS while state='OPEN' \u2014 once the buyer taps, you can't cancel; refund_payment after the fact instead.",
+  cancel_point_payment_intent: "Cancel an OPEN point payment intent before the buyer interacts with the device. ONLY WORKS while state='OPEN' \u2014 once the buyer taps, you can't cancel; refund_payment after the fact instead. **IRREVERSIBLE \u2014 confirm with the cashier/operator before calling. State the device_id and amount.**",
   // ── Pure helpers (v0.7) ──────────────────────────────────────────────────
   compute_marketplace_fee: "PURE HELPER (no network) \u2014 given a transaction amount + fee rule (% or flat ARS, with optional min/max floors), returns the exact `marketplace_fee` value in ARS to pass to create_order or create_payment_preference. USE WHEN your platform takes a commission and you need to compute the exact fee per transaction. Examples: { percent: 5, minArs: 50, maxArs: 5000 } for percentage with floor + cap; { flatArs: 200, percent: 2 } for fixed + percentage.",
   explain_payment_status: "PURE HELPER (no network) \u2014 given a Payment object (from get_payment / create_payment / handle_webhook), returns { summary, recommendedAction, final, paid, retryable } in Spanish. Translates MP's cryptic status_detail codes to plain Spanish + actionable guidance ('reintentar con otra tarjeta' vs 'esperar webhook' vs 'estado final'). USE THIS instead of having to memorize 30+ status_detail codes \u2014 surface summary + recommendedAction directly to the user.",
@@ -3158,16 +3172,28 @@ function mercadoPagoTools(client, options) {
         external_reference: zod.z.string().optional().describe("Optional id from your system to track this subscription")
       }),
       execute: async ({ customer_email, amount_ars, frequency_months, reason, external_reference }) => {
-        const created = await client.createPreapproval({
-          reason,
-          payerEmail: customer_email,
-          amount: amount_ars,
-          currency: "ARS",
-          frequency: frequency_months,
-          frequencyType: "months",
-          backUrl: options.backUrl,
-          ...external_reference !== void 0 ? { externalReference: external_reference } : {}
-        });
+        const created = await client.createPreapproval(
+          {
+            reason,
+            payerEmail: customer_email,
+            amount: amount_ars,
+            currency: "ARS",
+            frequency: frequency_months,
+            frequencyType: "months",
+            backUrl: options.backUrl,
+            ...external_reference !== void 0 ? { externalReference: external_reference } : {},
+            // Deterministic idempotency — if the LLM retries this tool call
+            // with the same inputs (e.g., timeout + retry), MP returns the
+            // EXISTING subscription instead of creating a duplicate.
+            idempotencyKey: await deterministicIdempotencyKey(
+              "create_subscription",
+              customer_email,
+              amount_ars,
+              frequency_months,
+              external_reference
+            )
+          }
+        );
         await options.state.set(created.id, {
           status: created.status,
           payerEmail: customer_email,
@@ -3374,9 +3400,9 @@ function mercadoPagoTools(client, options) {
       inputSchema: zod.z.object({
         external_reference: zod.z.string().optional(),
         status: zod.z.string().optional().describe("'approved' | 'pending' | 'rejected' | 'cancelled' | 'refunded' etc."),
-        payer_email: zod.z.string().optional(),
-        begin_date: zod.z.string().optional().describe("ISO 8601, e.g. 2026-01-01T00:00:00Z"),
-        end_date: zod.z.string().optional().describe("ISO 8601"),
+        payer_email: zod.z.string().email().optional().describe("Filter by payer email (exact match)."),
+        begin_date: zod.z.string().datetime().optional().describe("ISO 8601, e.g. 2026-01-01T00:00:00Z"),
+        end_date: zod.z.string().datetime().optional().describe("ISO 8601"),
         limit: zod.z.number().int().min(1).max(100).optional().describe("Default 30, max 100"),
         offset: zod.z.number().int().min(0).optional().describe("Pagination offset (default 0)")
       }),
@@ -3494,28 +3520,36 @@ function mercadoPagoTools(client, options) {
         excluded_payment_types: zod.z.array(zod.z.enum(["credit_card", "debit_card", "ticket", "atm", "bank_transfer"])).optional().describe("Block payment types \u2014 e.g., ['ticket'] to disable Rapipago/Pago F\xE1cil")
       }),
       execute: async (input) => {
-        const pref = await client.createPreference({
-          items: input.items.map((it) => ({
-            title: it.title,
-            quantity: it.quantity,
-            unit_price: it.unit_price,
-            currency_id: "ARS",
-            ...it.description !== void 0 ? { description: it.description } : {},
-            ...it.picture_url !== void 0 ? { picture_url: it.picture_url } : {}
-          })),
-          ...input.payer_email !== void 0 ? { payer: { email: input.payer_email } } : {},
-          ...input.external_reference !== void 0 ? { externalReference: input.external_reference } : {},
-          ...input.statement_descriptor !== void 0 ? { statementDescriptor: input.statement_descriptor } : {},
-          backUrls: { success: options.backUrl, failure: options.backUrl, pending: options.backUrl },
-          autoReturn: "approved",
-          ...options.notificationUrl !== void 0 ? { notificationUrl: options.notificationUrl } : {},
-          ...input.max_installments !== void 0 || input.excluded_payment_types !== void 0 ? {
-            paymentMethods: {
-              ...input.max_installments !== void 0 ? { installments: input.max_installments } : {},
-              ...input.excluded_payment_types !== void 0 ? { excluded_payment_types: input.excluded_payment_types.map((id) => ({ id })) } : {}
-            }
-          } : {}
-        });
+        const idemKey = await deterministicIdempotencyKey(
+          "create_payment_preference",
+          input.external_reference ?? input.payer_email ?? "",
+          input.items.map((it) => `${it.title}:${it.quantity}:${it.unit_price}`).join("|")
+        );
+        const pref = await client.createPreference(
+          {
+            items: input.items.map((it) => ({
+              title: it.title,
+              quantity: it.quantity,
+              unit_price: it.unit_price,
+              currency_id: "ARS",
+              ...it.description !== void 0 ? { description: it.description } : {},
+              ...it.picture_url !== void 0 ? { picture_url: it.picture_url } : {}
+            })),
+            ...input.payer_email !== void 0 ? { payer: { email: input.payer_email } } : {},
+            ...input.external_reference !== void 0 ? { externalReference: input.external_reference } : {},
+            ...input.statement_descriptor !== void 0 ? { statementDescriptor: input.statement_descriptor } : {},
+            backUrls: { success: options.backUrl, failure: options.backUrl, pending: options.backUrl },
+            autoReturn: "approved",
+            ...options.notificationUrl !== void 0 ? { notificationUrl: options.notificationUrl } : {},
+            ...input.max_installments !== void 0 || input.excluded_payment_types !== void 0 ? {
+              paymentMethods: {
+                ...input.max_installments !== void 0 ? { installments: input.max_installments } : {},
+                ...input.excluded_payment_types !== void 0 ? { excluded_payment_types: input.excluded_payment_types.map((id) => ({ id })) } : {}
+              }
+            } : {},
+            idempotencyKey: idemKey
+          }
+        );
         return {
           preference_id: pref.id,
           init_point_url: pref.init_point ?? null,
@@ -4735,8 +4769,17 @@ function mercadoPagoTools(client, options) {
     update_merchant_order: ai.tool({
       description: desc("update_merchant_order"),
       inputSchema: zod.z.object({
-        merchant_order_id: zod.z.string(),
-        patch: zod.z.record(zod.z.string(), zod.z.unknown())
+        merchant_order_id: zod.z.string().min(1),
+        // Narrow to MP's documented merchant_order PATCH fields. Previously
+        // this was z.record(z.string(), z.unknown()) which let the LLM pass
+        // arbitrary JSON; MP would silently ignore unknown keys, masking
+        // typos. Strict schema = LLM gets a clear validation error instead.
+        patch: zod.z.object({
+          external_reference: zod.z.string().max(256).optional().describe("Your system's id for this order. Updateable while order is open."),
+          notification_url: zod.z.string().url().optional().describe("Where MP sends webhook notifications for this order."),
+          additional_info: zod.z.string().max(600).optional().describe("Free-form metadata stored alongside the order."),
+          status: zod.z.enum(["opened", "closed", "expired"]).optional().describe("Open orders can be closed (final) or expired (cleanup).")
+        }).strict().describe("Subset of merchant_order fields to update. Unknown keys rejected.")
       }),
       execute: async ({ merchant_order_id, patch }) => {
         return client.updateMerchantOrder(merchant_order_id, patch);
@@ -4955,8 +4998,24 @@ function mercadoPagoTools(client, options) {
     explain_payment_status: ai.tool({
       description: desc("explain_payment_status"),
       inputSchema: zod.z.object({
-        payment_id: zod.z.string().optional().describe("If provided, fetches the Payment first."),
-        payment: zod.z.record(zod.z.string(), zod.z.unknown()).optional().describe("Alternatively, pass a Payment object directly (saves a network round-trip).")
+        payment_id: zod.z.string().min(1).optional().describe(
+          "If provided, fetches the Payment first. RECOMMENDED PATH for agents \u2014 pass the id and let the lib fetch."
+        ),
+        // Loose object kept for advanced manual callers that have already
+        // fetched a Payment from another path. LLMs should prefer payment_id.
+        // We don't strictly type the Payment shape here because MP's actual
+        // response includes 100+ optional fields; the helper consumes only
+        // status / status_detail / payment_method_id / etc. Exposed loosely
+        // for ergonomic interop, NOT for LLM use.
+        payment: zod.z.object({
+          id: zod.z.union([zod.z.string(), zod.z.number()]).optional(),
+          status: zod.z.string().optional(),
+          status_detail: zod.z.string().optional(),
+          payment_method_id: zod.z.string().optional(),
+          transaction_amount: zod.z.number().optional()
+        }).passthrough().optional().describe(
+          "ADVANCED \u2014 pass a pre-fetched Payment object to skip the network call. LLMs: use payment_id instead."
+        )
       }),
       execute: async ({ payment_id, payment }) => {
         let p;