@ar-agents/mercadopago 0.14.0 → 0.15.0

package/dist/index.d.cts

@@ -2167,7 +2167,49 @@ interface MercadoPagoToolsOptions {
      * retries (which fire on 5xx and can deliver the same event 5+ times).
      */
     webhookDedup?: WebhookDedup;
+    /**
+     * v0.15 — Programmatic Human-In-The-Loop gate for irreversible /
+     * money-moving operations. When set, every call to one of the gated
+     * tools (cancel_payment, capture_payment, refund_payment,
+     * delete_customer_card, cancel_qr_payment, cancel_order,
+     * cancel_point_payment_intent, delete_webhook) invokes this callback
+     * BEFORE executing. Return `true` to proceed, `false` to reject the
+     * call (the tool returns `{ ok: false, reason: "Confirmation declined" }`).
+     *
+     * The description-based HITL warnings still apply (they nudge the LLM
+     * to confirm in-conversation), but those depend on the LLM's heuristic
+     * and can be bypassed via prompt injection. This callback is the actual
+     * out-of-band enforcement: wire it to your UI / Slack / email / SMS
+     * confirmation flow so a human approves money-movement explicitly.
+     *
+     * @example
+     * ```ts
+     * mercadoPagoTools(client, {
+     *   state, backUrl,
+     *   requireConfirmation: async (op, args) => {
+     *     // Send a Slack DM to the operator with the operation summary
+     *     // and wait for their button click. Throw or return false to reject.
+     *     return await slack.confirm({
+     *       channel: "#mp-approvals",
+     *       text: `Refund $${args.amount ?? "FULL"} on payment ${args.payment_id}?`,
+     *       timeoutMs: 60_000,
+     *     });
+     *   },
+     * });
+     * ```
+     *
+     * If omitted (default), the description-based HITL is the only line of
+     * defense — fine for trusted/internal agents, NOT recommended for
+     * untrusted-input agents (anything reading from a public webhook).
+     */
+    requireConfirmation?: (operation: GatedOperation, args: Record<string, unknown>) => Promise<boolean>;
 }
+/**
+ * Tool names that go through `requireConfirmation` when configured.
+ * Adding a new irreversible operation? Add it here AND in the
+ * `applyConfirmationGate` wrapper at the bottom of this file.
+ */
+type GatedOperation = "cancel_payment" | "capture_payment" | "refund_payment" | "delete_customer_card" | "cancel_qr_payment" | "cancel_order" | "cancel_point_payment_intent" | "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" | "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" | "mp_health_check" | "find_applicable_promos" | "confirm_3ds_challenge" | "search_payments_all" | "list_settlements_all" | "validate_tax_id";
 /**
  * Build a tool set for the Vercel AI SDK that exposes Mercado Pago to an

package/dist/index.d.ts

@@ -2167,7 +2167,49 @@ interface MercadoPagoToolsOptions {
      * retries (which fire on 5xx and can deliver the same event 5+ times).
      */
     webhookDedup?: WebhookDedup;
+    /**
+     * v0.15 — Programmatic Human-In-The-Loop gate for irreversible /
+     * money-moving operations. When set, every call to one of the gated
+     * tools (cancel_payment, capture_payment, refund_payment,
+     * delete_customer_card, cancel_qr_payment, cancel_order,
+     * cancel_point_payment_intent, delete_webhook) invokes this callback
+     * BEFORE executing. Return `true` to proceed, `false` to reject the
+     * call (the tool returns `{ ok: false, reason: "Confirmation declined" }`).
+     *
+     * The description-based HITL warnings still apply (they nudge the LLM
+     * to confirm in-conversation), but those depend on the LLM's heuristic
+     * and can be bypassed via prompt injection. This callback is the actual
+     * out-of-band enforcement: wire it to your UI / Slack / email / SMS
+     * confirmation flow so a human approves money-movement explicitly.
+     *
+     * @example
+     * ```ts
+     * mercadoPagoTools(client, {
+     *   state, backUrl,
+     *   requireConfirmation: async (op, args) => {
+     *     // Send a Slack DM to the operator with the operation summary
+     *     // and wait for their button click. Throw or return false to reject.
+     *     return await slack.confirm({
+     *       channel: "#mp-approvals",
+     *       text: `Refund $${args.amount ?? "FULL"} on payment ${args.payment_id}?`,
+     *       timeoutMs: 60_000,
+     *     });
+     *   },
+     * });
+     * ```
+     *
+     * If omitted (default), the description-based HITL is the only line of
+     * defense — fine for trusted/internal agents, NOT recommended for
+     * untrusted-input agents (anything reading from a public webhook).
+     */
+    requireConfirmation?: (operation: GatedOperation, args: Record<string, unknown>) => Promise<boolean>;
 }
+/**
+ * Tool names that go through `requireConfirmation` when configured.
+ * Adding a new irreversible operation? Add it here AND in the
+ * `applyConfirmationGate` wrapper at the bottom of this file.
+ */
+type GatedOperation = "cancel_payment" | "capture_payment" | "refund_payment" | "delete_customer_card" | "cancel_qr_payment" | "cancel_order" | "cancel_point_payment_intent" | "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" | "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" | "mp_health_check" | "find_applicable_promos" | "confirm_3ds_challenge" | "search_payments_all" | "list_settlements_all" | "validate_tax_id";
 /**
  * Build a tool set for the Vercel AI SDK that exposes Mercado Pago to an

package/dist/index.js

@@ -3028,7 +3028,8 @@ async function verifyWebhookSignature(params) {
 
 // src/tools.ts
 async function deterministicIdempotencyKey(...parts) {
-  const payload = parts.filter((p) => p !== void 0 && p !== null).map(String).join("|");
+  const filtered = parts.filter((p) => p !== void 0 && p !== null).map(String);
+  const payload = filtered.map((p) => `${p.length}:${p}`).join("|");
   return (await sha256Hex(payload)).slice(0, 32);
 }
 var DEFAULT_DESCRIPTIONS = {
@@ -3156,6 +3157,10 @@ var DEFAULT_DESCRIPTIONS = {
 };
 function mercadoPagoTools(client, options) {
   const desc = (name) => options.descriptions?.[name] ?? DEFAULT_DESCRIPTIONS[name];
+  const built = buildAllTools(client, options, desc);
+  return options.requireConfirmation ? applyConfirmationGate(built, options.requireConfirmation) : built;
+}
+function buildAllTools(client, options, desc) {
   return {
     // ─────────────────────────────────────────────────────────────────────────
     // Subscriptions (v0.1 — kept identical for backward compatibility)
@@ -4269,6 +4274,22 @@ function mercadoPagoTools(client, options) {
             resource: null
           };
         }
+        if (options.webhookDedup && request_id_header) {
+          const { shouldProcess } = await options.webhookDedup.check({
+            topic: event.topic,
+            dataId: event.dataId,
+            requestId: request_id_header
+          });
+          if (!shouldProcess) {
+            return {
+              verified: true,
+              deduplicated: true,
+              event,
+              resource: null,
+              resource_error: "Webhook is a duplicate (same topic+dataId+requestId seen recently). Side effects skipped."
+            };
+          }
+        }
         let resource = null;
         let resourceError = null;
         if (auto_fetch) {
@@ -5161,6 +5182,43 @@ function mercadoPagoTools(client, options) {
     })
   };
 }
+var GATED_TOOL_NAMES = [
+  "cancel_payment",
+  "capture_payment",
+  "refund_payment",
+  "delete_customer_card",
+  "cancel_qr_payment",
+  "cancel_order",
+  "cancel_point_payment_intent",
+  "delete_webhook"
+];
+function applyConfirmationGate(tools, requireConfirmation) {
+  const wrapped = { ...tools };
+  for (const name of GATED_TOOL_NAMES) {
+    const original = tools[name];
+    if (!original) continue;
+    wrapped[name] = {
+      ...original,
+      execute: async (input, ctx) => {
+        const args = input ?? {};
+        const approved = await requireConfirmation(name, args);
+        if (!approved) {
+          return {
+            ok: false,
+            reason: "Confirmation declined by requireConfirmation gate.",
+            operation: name,
+            args
+          };
+        }
+        return await original.execute(
+          input,
+          ctx
+        );
+      }
+    };
+  }
+  return wrapped;
+}
 
 // src/state.ts
 var InMemoryStateAdapter = class {