@ar-agents/mercadopago 0.14.0 → 0.15.1

package/AGENTS.md

@@ -1,7 +1,9 @@
-# @ar-agents/mercadopago — agent guide (v0.7)
+# @ar-agents/mercadopago — agent guide
 
 This file is for AI agents using or recommending this package. Humans should start with [README.md](./README.md). Format follows the [agents.md convention](https://agents.md/).
 
+`@ar-agents/mercadopago` is a Mercado Pago Agent Toolkit for the Vercel AI SDK 6. It exposes 87 typed tools spanning the agent-relevant Mercado Pago API surface (Subscriptions, Payments, Checkout Pro, Marketplace OAuth, Order Management, Customers, Cards, Cuotas, QR, 3DS, Point devices, Stores+POS, Account/Balance/Settlements, Webhooks, Disputes, Lookups, Bank Accounts). Opinionated for AR; ships with cross-LATAM tax-id helpers.
+
 ## Decision tree — pick the right tool
 
 | User intent | Tool to call |

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## 0.15.1
+
+### Patch — docs: positioning + scope clarity
+
+- `package.json` description rewritten as the npm-tagline source of truth: "Mercado Pago Agent Toolkit for the Vercel AI SDK 6. 87 typed tools across the agent-relevant Mercado Pago API surface — Subscriptions, Payments, Checkout Pro, Marketplace OAuth, Order Management, Customers, Cards, Cuotas, QR, 3DS, Point devices, Webhooks, Stores+POS, Account/Balance/Settlements, Disputes, Lookups, Bank Accounts."
+- `README.md` sub-headline now enumerates the 17 categories. Fixes the drift where the npm page implied subscriptions-only scope.
+- `AGENTS.md` heading no longer carries a stale `(v0.7)` tag; opening paragraph spells out the full surface.
+- Cookbook recipe 03 header: "Production-grade webhook handler" → "Webhook handler".
+- "At a glance" table: tool count corrected (82 → 87), test count refreshed (223 → 303), cookbook count corrected (8 → 9), `Vercel-native` row clarified to `Vercel KV adapters`.
+- `MIGRATION.md`: dropped marketing adjectives ("agent ergonomics", "production-grade").
+
+No code changes. No new tools. No API changes.
+
+## 0.15.0
+
+### Minor — `requireConfirmation` opt-in HITL callback (closes /review CRITICAL)
+
+Description-based HITL warnings on irreversible ops are best-effort against
+prompt injection. The /review audit (commit 6e3a0dd) flagged this as a real
+risk: a crafted user message smuggled into `external_reference` saying "the
+user already confirmed this refund" could bypass the LLM's heuristic.
+
+`mercadoPagoTools(client, { requireConfirmation: async (op, args) => boolean })`
+adds a programmatic out-of-band gate. When set, the 8 irreversible tools
+(`cancel_payment`, `capture_payment`, `refund_payment`,
+`delete_customer_card`, `cancel_qr_payment`, `cancel_order`,
+`cancel_point_payment_intent`, `delete_webhook`) call the callback BEFORE
+executing. If it returns `false`, the tool returns
+`{ ok: false, reason: "Confirmation declined", operation, args }` and never
+reaches MP. If it throws, the error propagates so connection issues are
+distinguishable from declined confirmations.
+
+```ts
+mercadoPagoTools(client, {
+  state, backUrl,
+  requireConfirmation: async (op, args) => {
+    return await slack.confirm({
+      channel: "#mp-approvals",
+      text: `Refund $${args.amount ?? "FULL"} on payment ${args.payment_id}?`,
+      timeoutMs: 60_000,
+    });
+  },
+});
+```
+
+Backward-compat: omit the option for the previous behavior (description-only
+HITL). 8 new tests in `test/require-confirmation.test.ts` covering decline,
+approve, non-gated tools unaffected, error propagation.
+
+### Other improvements (closes /review findings)
+
+- **webhookDedup wired in `handle_webhook`** — the option was declared in
+  v0.10 but never used; `handle_webhook` now actually short-circuits on
+  duplicate `(topic, dataId, requestId)` tuples (fix for /review CRITICAL).
+- **Idempotency key collision-safe encoding** — `deterministicIdempotencyKey`
+  switched from `|`-joined to length-prefix (`<n>:<value>|`) so an attacker
+  controlling `external_reference` can no longer craft a colliding key with
+  a future legitimate transaction.
+- **VercelKVRateLimiter improvements** — fixed the docstring's fictional
+  `MercadoPagoClient({ rateLimiter })` example (now correctly shows
+  `withRateLimit` middleware), added randomized jitter (±30%) to the retry
+  loop to mitigate thundering herd, capped retries at 8 to fail fast on
+  misconfigured buckets.
+
 ## 0.14.0
 
 ### Minor Changes — deep-audit hardening pass
@@ -170,8 +234,7 @@ partitions. This makes the safe default: safe.
 
 ### Minor Changes — Production hardening: circuit breaker, deadline propagation, property-based tests, real MP sandbox integration tests, benchmarks
 
-The "100/100, top-1 in the world" upgrade. Architectural production-grade
-features that separate a toolkit-with-tests from a toolkit-deployed-at-scale.
+Architectural features for at-scale deployment.
 
 **Circuit Breaker (NEW)**
 
@@ -278,7 +341,7 @@ features that separate a toolkit-with-tests from a toolkit-deployed-at-scale.
 
 - `cookbook/01-checkout-pro-basic.ts` — first-time hosted checkout
 - `cookbook/02-saas-subscription.ts` — reusable plan + first payment + card swap on rejection
-- `cookbook/03-webhook-handler.ts` — production-grade Edge handler with HMAC verify
+- `cookbook/03-webhook-handler.ts` — Edge handler with HMAC verify
 - `cookbook/04-marketplace-split.ts` — OAuth seller link → preference with fee → reconciliation
 - `cookbook/05-qr-in-store.ts` — QR generation → buyer scan → WhatsApp notify
 - `cookbook/06-3ds-challenge.ts` — detect → redirect → recover via webhook
@@ -295,7 +358,7 @@ features that separate a toolkit-with-tests from a toolkit-deployed-at-scale.
 
 ### Minor Changes
 
-- MP v0.7: completeness máxima — el agente de MP más completo posible. **+25 tools (81 total)**.
+- MP v0.7: +25 new tools (81 total).
 
   **Cierre de gaps obvios (8 tools)**:
   - `get_customer`, `update_customer`, `create_customer_card`, `get_customer_card`

package/MIGRATION.md

@@ -150,7 +150,7 @@ new MercadoPagoClient({
 - **Status detail explainer** (`explainPaymentStatus` — Spanish actionable guidance)
 - **Marketplace fee calculator** (`computeMarketplaceFee`)
 - **Vercel KV state adapters** (subscription state + OAuth tokens + idempotency cache + audit log)
-- **Cookbook** with 8 production-grade recipes
+- **Cookbook** with 8 cookbook recipes
 - **Edge Runtime support** (Web Crypto, no `node:crypto`)
 - **Property-based testing** with fast-check (~1500 random scenarios)
 - **Failure injection tests** + integration tests vs MP sandbox
@@ -160,14 +160,14 @@ new MercadoPagoClient({
 
 - Your codebase is already deeply integrated with the official SDK
 - You don't need the agent layer (no Vercel AI SDK)
-- You operate primarily server-side with cron jobs and don't care about
-  agent ergonomics, audit logs, circuit breakers, or status explainers
+- You operate primarily server-side with cron jobs and don't need
+  AI-SDK-shaped tool schemas, audit logs, circuit breakers, or status explainers
 
 ## When to add `@ar-agents/mercadopago`
 
 - You're building anything with an AI agent (Claude, GPT, Gemini)
 - You're deploying to Vercel and want first-class KV adapters
-- You need **production-grade webhook handling** (HMAC + dedup + replay protection)
+- You need **cookbook webhook handling** (HMAC + dedup + replay protection)
 - You operate a **marketplace** with per-seller OAuth flows
 - You need **compliance-grade audit logging** for refunds/payments
 - You want **AR-specific knowledge** (cuotas catalog, status_detail explainer in Spanish, AR landmines documented)

package/README.md

@@ -1,6 +1,13 @@
 # @ar-agents/mercadopago
 
-> Mercado Pago Subscriptions as drop-in tools for the [Vercel AI SDK](https://ai-sdk.dev/). Argentine-focused, agent-ready.
+> Mercado Pago Agent Toolkit. Built on Vercel.
+>
+> 87 typed tools across the agent-relevant Mercado Pago API surface, for the
+> [Vercel AI SDK](https://ai-sdk.dev/) 6 `Experimental_Agent`.
+>
+> _Payments · Subscriptions · Checkout Pro · Marketplace OAuth · Order Management ·
+> Customers · Cards · Cuotas · QR · 3DS · Point devices · Stores+POS ·
+> Account/Balance/Settlements · Webhooks · Disputes · Lookups · Bank Accounts_
 
 [![npm version](https://img.shields.io/npm/v/@ar-agents/mercadopago.svg)](https://www.npmjs.com/package/@ar-agents/mercadopago)
 [![npm downloads](https://img.shields.io/npm/dm/@ar-agents/mercadopago.svg)](https://www.npmjs.com/package/@ar-agents/mercadopago)
@@ -8,9 +15,9 @@
 [![CI](https://github.com/ar-agents/ar-agents/actions/workflows/ci.yml/badge.svg)](https://github.com/ar-agents/ar-agents/actions/workflows/ci.yml)
 [![bundle size](https://img.shields.io/bundlephobia/minzip/@ar-agents/mercadopago.svg)](https://bundlephobia.com/package/@ar-agents/mercadopago)
 
-Exposes Mercado Pago's recurring-billing API to AI agents through a typed,
-opinionated tool collection. Built for the Vercel AI SDK 6 `Experimental_Agent`.
-Compatible with any caller that uses `tool()`.
+Wraps the Mercado Pago API as a typed tool collection for AI agents. Built for
+the Vercel AI SDK 6 `Experimental_Agent`. Compatible with any caller that uses
+`tool()`.
 
 > **Reading this as an agent?** Skip to [AGENTS.md](./AGENTS.md) — it's targeted at LLM consumption with explicit tool-selection rules and error-recovery patterns.
 
@@ -18,9 +25,9 @@ Compatible with any caller that uses `tool()`.
 
 | What | Value |
 | --- | --- |
-| Tools shipped | **82 tools** — covers the full agent-relevant MP API surface. Subscriptions, Payments, Refunds, Checkout Pro, Order Management, Customers, Saved Cards, Cuotas, QR in-store, Subscription Plans, Stores+POS, **Point Devices físicos**, **Merchant Orders**, **Bank Accounts**, Disputes, Lookups, Webhooks management, **handle_webhook combo**, **OAuth Marketplace flow**, **Account/Balance/Settlements**, **3DS analyzer**, **Test cards**, **mp_health_check**, plus pure helpers `compute_marketplace_fee` + `explain_payment_status`. |
-| Production hardening (v0.9) | **Circuit breaker** with state machine + rolling window, **deadline propagation** via parent AbortSignal, **W3C Trace Context** propagation (OpenTelemetry-compatible without peer dep), **replay-attack protection** on webhook signatures (5-min default tolerance), **health check** endpoint. |
-| Test coverage | **223 unit tests** + **14 property-based tests** (~1400 random scenarios via fast-check) + **11 failure injection tests** (network errors, timeouts, races, malformed responses) + **integration tests vs MP sandbox** (gated by env var) + **benchmarks** (`pnpm bench`). |
+| Tools shipped | **87 tools** — covers the agent-relevant MP API surface. Subscriptions, Payments, Refunds, Checkout Pro, Order Management, Customers, Saved Cards, Cuotas, QR in-store, Subscription Plans, Stores+POS, Point Devices físicos, Merchant Orders, Bank Accounts, Disputes, Lookups, Webhooks management, `handle_webhook` combo, OAuth Marketplace flow, Account/Balance/Settlements, 3DS analyzer, Test cards, `mp_health_check`, plus pure helpers `compute_marketplace_fee` + `explain_payment_status`. |
+| Production hardening | Circuit breaker with state machine + rolling window, deadline propagation via parent AbortSignal, W3C Trace Context propagation (OpenTelemetry-compatible without peer dep), replay-attack protection on webhook signatures (5-min default tolerance), `mp_health_check` endpoint. |
+| Test coverage | **303 tests** — unit + property-based (~1400 random scenarios via fast-check) + failure injection (network errors, timeouts, races, malformed responses) + integration vs MP sandbox (gated by env var) + benchmarks (`pnpm bench`). |
 | External dependencies | Mercado Pago access token (TEST or APP_USR), state adapter (Upstash, Redis, Postgres, in-memory, etc.) |
 | Latency | 200–600ms per MP call; <1ms for state ops |
 | Cost | $0 — MP API is free; merchant pays per-transaction fees on auto-charges |
@@ -28,18 +35,17 @@ Compatible with any caller that uses `tool()`.
 | Agent safety | `cancel_subscription` description triggers confirm-before-call in Claude Sonnet 4.6+ |
 | Sites supported | MLA (Argentina) verified end-to-end. Other LATAM sites should work but aren't exercised by tests. |
 | Runtime | **Edge Runtime + Node 18+** — Web Crypto under the hood, no `node:crypto`. Drops into Vercel Edge Functions, Cloudflare Workers, Deno deploy, or any modern Node. |
-| Vercel-native | First-class adapters for **Vercel KV** (subscription state, OAuth tokens, idempotency cache) via `@ar-agents/mercadopago/vercel-kv` subpath. |
-| Cookbook | 8 production-grade recipes shipped in `cookbook/` — checkout, subscriptions, webhook handler, marketplace OAuth, QR in-store, 3DS challenge, auth-only Order, recovery patterns. |
+| Vercel KV adapters | Subpath `@ar-agents/mercadopago/vercel-kv` ships adapters for subscription state, OAuth tokens, idempotency cache, audit log, and rate limiter. |
+| Cookbook | 9 recipes shipped in `cookbook/` — checkout, subscriptions, webhook handler, marketplace OAuth, QR in-store, 3DS challenge, auth-only Order, recovery patterns, full OpenTelemetry wiring. |
 
 ## Why this exists
 
-Building an agent that operates a real Argentine business means integrating
-Mercado Pago. MP's API has a surface area of dozens of endpoints, a docs site
-that is partially translated to Spanish-from-the-90s, and at least 11
-non-obvious landmines that take days each to discover. This package encapsulates
-the subset of MP that an agent typically needs (recurring subscriptions: create,
-check status, pause/resume, cancel) and turns the documented gotchas into typed
-errors with actionable messages.
+Building an agent that operates an Argentine business means integrating Mercado
+Pago. The API surface is dozens of endpoints, the docs are partially translated,
+and there are 11+ non-obvious landmines that take days each to discover the
+first time around. This package wraps the agent-relevant surface (subscriptions,
+payments, marketplace OAuth, cuotas, QR, 3DS, point devices, webhooks) and turns
+the documented gotchas into typed errors with actionable messages.
 
 ## Install
 
@@ -531,3 +537,14 @@ Each recipe is copy-pasteable into a Next.js route handler.
 ## License
 
 MIT — see [LICENSE](./LICENSE).
+
+## Stability
+
+This package is **pre-1.0**. Per [npm convention](https://docs.npmjs.com/about-semantic-versioning), **0.x minor versions may include breaking changes**. We document every breaking change in `CHANGELOG.md` under the corresponding minor bump and flag it explicitly. To avoid surprises:
+
+```bash
+# Pin to exact version (recommended for production):
+pnpm add @ar-agents/<package>@<exact-version>
+```
+
+We commit to **no breaking changes within a patch version**, and we publish `1.0.0` once the public API has stabilized across at least two consecutive minor releases.

package/README.skeleton.md

@@ -0,0 +1,200 @@
+<!--
+  README skeleton — Vercel-official quality.
+  Drop this in as packages/mercadopago/README.md after a final once-over.
+  The structure follows the patterns Vercel themselves use on
+  https://github.com/vercel/ai-sdk and https://github.com/vercel/next.js
+  for their public OSS repos.
+
+  Hard rules:
+  - Lead with what it is and a 3-line install + first call.
+  - Real numbers (latency, bundle size) only — no "fast", "blazing", "robust".
+  - Code blocks runnable as-pasted (no `// ...` placeholders that hide work).
+  - One-screen scrolling for the top: header → install → first call → core API.
+  - Everything below is reference, not pitch.
+-->
+
+# `@ar-agents/mercadopago`
+
+[![npm version](https://img.shields.io/npm/v/@ar-agents/mercadopago.svg?label=npm)](https://www.npmjs.com/package/@ar-agents/mercadopago)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/@ar-agents/mercadopago.svg)](https://bundlephobia.com/package/@ar-agents/mercadopago)
+[![types](https://img.shields.io/npm/types/@ar-agents/mercadopago.svg)](https://arethetypeswrong.github.io/?p=@ar-agents/mercadopago)
+[![CI](https://github.com/ar-agents/ar-agents/actions/workflows/ci.yml/badge.svg)](https://github.com/ar-agents/ar-agents/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+Mercado Pago Agent Toolkit. Built on Vercel. 87 typed tools across the agent-relevant Mercado Pago API surface (Subscriptions, Payments, Checkout Pro, Marketplace OAuth, Order Management, Customers, Cards, Cuotas, QR, 3DS, Point devices, Stores+POS, Account/Balance/Settlements, Webhooks, Disputes, Lookups, Bank Accounts) for the [Vercel AI SDK](https://ai-sdk.dev/) 6 `Experimental_Agent`. Edge-Runtime-safe.
+
+> **Reading this as an agent?** Skip to [AGENTS.md](./AGENTS.md) — decision tree, result schemas to memorize, error patterns, latency table.
+
+## Quick start
+
+```bash
+pnpm add @ar-agents/mercadopago ai zod
+```
+
+```ts
+import { Experimental_Agent as Agent, stepCountIs } from "ai";
+import { MercadoPagoClient, mercadoPagoTools, InMemoryStateAdapter } from "@ar-agents/mercadopago";
+
+const mp = new MercadoPagoClient({ accessToken: process.env.MP_ACCESS_TOKEN! });
+
+export const agent = new Agent({
+  model: "anthropic/claude-sonnet-4-6",
+  instructions: "Sos un asistente de billing para una SaaS argentina.",
+  tools: mercadoPagoTools(mp, { state: new InMemoryStateAdapter(), backUrl: "https://example.com/done" }),
+  stopWhen: stepCountIs(8),
+});
+```
+
+```ts
+const { text } = await agent.generate({
+  prompt: "Cobrale $25.000 mensual a juan@example.com con razón 'Plan Pro'."
+});
+```
+
+That's it. The agent picks `create_subscription`, returns an `init_point_url` you send to the customer, and the rest of the flow (first payment confirmation, recurring charges, webhooks) just works.
+
+## At a glance
+
+| | |
+| --- | --- |
+| **Tools** | 30 — Subscriptions, Payments, Refunds, Checkout Pro, Cuotas, QR in-store, Saved cards, Marketplace OAuth, Order Management, Point devices, 3DS, Webhooks. [Full list](./AGENTS.md#tool-selection). |
+| **Bundle size** | 41 KB ESM brotli'd ([bundlephobia](https://bundlephobia.com/package/@ar-agents/mercadopago)). Tree-shakable subpath exports for `/vercel-kv` + `/otel`. |
+| **Runtime** | Vercel Edge, Node 18+, Cloudflare Workers, Deno — Web Crypto under the hood. |
+| **Tests** | 290 unit + property + failure-injection + benchmark. `pnpm test`, `pnpm bench`. |
+| **TypeScript** | Strict mode, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`. publint + arethetypeswrong all 🟢. |
+| **AR-specific knowledge** | Cuotas with regulatory text (RG 5286/2023), AR issuer promo catalog, Subscription replay-protection, MLA-verified, ARS default. |
+
+## Server-only
+
+This package **MUST** run on the server. The constructor throws if instantiated in a browser context — the access token would be exposed in the JavaScript bundle. Use Server Components, Route Handlers, or Server Actions.
+
+```ts
+// ❌ Never. Throws at runtime AND would leak the token if it didn't.
+"use client";
+const mp = new MercadoPagoClient({ accessToken: ... });
+
+// ✅ Server Component / Route Handler / Server Action.
+import { MercadoPagoClient } from "@ar-agents/mercadopago";
+export async function POST(req: Request) {
+  const mp = new MercadoPagoClient({ accessToken: process.env.MP_ACCESS_TOKEN! });
+  // ...
+}
+```
+
+## API reference
+
+### `new MercadoPagoClient(options)`
+
+Server-side MP API client. Edge-Runtime safe.
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `accessToken` (required) | — | TEST- prefix for sandbox, APP_USR- for production. |
+| `baseUrl` | `https://api.mercadopago.com` | Override for tests / regional hosts. |
+| `fetch` | `globalThis.fetch` | Custom fetch (e.g., MSW for tests). |
+| `requestTimeoutMs` | `30_000` | Per-request timeout. |
+| `maxRetries` | `1` | 5xx + network retries. 4xx never retried. |
+| `circuitBreaker` | — | `new CircuitBreaker({ ... })` to fail fast on cascading failures. |
+| `traceContext` | — | OpenTelemetry context propagator (W3C trace headers). |
+| `onCall` | — | Observability hook fired after every request. |
+
+### `mercadoPagoTools(client, options)`
+
+Returns the agent tool set wired to the given client.
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `state` | yes | `SubscriptionStateAdapter` — `InMemoryStateAdapter`, `VercelKVSubscriptionStateAdapter`, or your own. |
+| `backUrl` | yes | HTTPS URL where MP redirects buyers after first payment. localhost rejected. |
+| `notificationUrl` | no | Webhook URL for new payments / status changes. |
+| `oauth` | no | `{ clientId, clientSecret, redirectUri, tokenStore }` for marketplace OAuth flows. |
+| `webhookSecret` | no | HMAC secret for `handle_webhook` (paste from MP dev panel). |
+| `descriptions` | no | Override individual tool descriptions for fine-tuning the LLM. |
+
+### Subpath exports
+
+| Subpath | When to use |
+| --- | --- |
+| `@ar-agents/mercadopago` | The 30 tools + client. Always-on. |
+| `@ar-agents/mercadopago/vercel-kv` | Vercel KV–backed adapters: `VercelKVSubscriptionStateAdapter`, `VercelKVOAuthTokenStore`, `VercelKVIdempotencyCache`, `VercelKVAuditLog`, `VercelKVRateLimiter` (distributed). Pulls in `@vercel/kv` peer dep. |
+| `@ar-agents/mercadopago/otel` | `instrumentMercadoPagoClient` + `instrumentMercadoPagoTools` for OpenTelemetry spans + metrics. Pulls in `@opentelemetry/api` peer dep. |
+
+## Production patterns
+
+### Idempotency by default
+
+Every `POST` request gets an auto-generated UUID idempotency key — your app survives network blips without double-charging. For LLM-driven retries, `create_payment`, `create_subscription`, `create_payment_preference`, and `refund_payment` use a **deterministic** key derived from the inputs, so a tool retried with the same inputs returns the existing resource instead of creating a duplicate.
+
+### Webhook verification
+
+```ts
+import { verifyWebhookSignature, parseWebhookEvent } from "@ar-agents/mercadopago";
+
+export async function POST(req: Request) {
+  const url = new URL(req.url);
+  const rawBody = await req.text();
+  const event = parseWebhookEvent(JSON.parse(rawBody), url.searchParams);
+
+  const ok = await verifyWebhookSignature({
+    requestId: req.headers.get("x-request-id"),
+    dataId: event!.dataId,
+    signatureHeader: req.headers.get("x-signature"),
+    secret: process.env.MP_WEBHOOK_SECRET!,
+  });
+  if (!ok) return new Response("Invalid signature", { status: 401 });
+  // process event...
+}
+```
+
+5-minute replay-tolerance window built in. Constant-time HMAC comparison.
+
+### Distributed rate limiting
+
+For multi-region or marketplace deploys where serverless instances would each get their own per-process bucket:
+
+```ts
+import { VercelKVRateLimiter } from "@ar-agents/mercadopago/vercel-kv";
+
+const limiter = new VercelKVRateLimiter({
+  key: "mp-account-prod",
+  capacity: 50,
+  refillPerSecond: 25,
+});
+```
+
+### Cookbook
+
+9 recipes in [`./cookbook`](./cookbook/) — Checkout Pro, SaaS subscription, webhook handler, marketplace split, QR in-store, 3DS challenge, manual capture, recovery patterns, full OpenTelemetry wiring.
+
+## Comparison
+
+| | `@ar-agents/mercadopago` | `mercadopago` (official SDK) | Hand-rolled |
+| --- | --- | --- | --- |
+| Tools as Vercel AI SDK 6 schemas | ✓ | — | build it |
+| AR-specific (cuotas, AR issuer promos, AR phone, MLA-verified) | ✓ | — | weeks |
+| `AGENTS.md` per package (LLM-readable) | ✓ | — | — |
+| Idempotency-by-default for state mutations | ✓ | — | build it |
+| Webhook signature verify + 5-min replay window | ✓ | client only | build it |
+| Edge Runtime support | ✓ | Node-only | build it |
+| Vercel KV adapters via subpath | ✓ | — | — |
+| OpenTelemetry instrumentation + recipe | ✓ | — | build it |
+| Circuit breaker + deadline propagation | ✓ | — | build it |
+| Tool middleware (compose audit/rate/metrics) | ✓ | — | — |
+| Time to first cobro | 30 min | 1+ week | 6-8 weeks |
+
+See [`MIGRATION.md`](./MIGRATION.md) for a side-by-side `mercadopago` → `@ar-agents/mercadopago` migration guide.
+
+## Security
+
+This package handles money. Read [SECURITY.md](../../SECURITY.md) before deploying:
+
+- The constructor refuses to instantiate in a browser context (token leak prevention).
+- Every webhook handler MUST call `verifyWebhookSignature` before trusting payload contents.
+- Irreversible tools (`refund_payment`, `cancel_*`, `delete_customer_card`) include explicit confirm-with-user instructions in their descriptions; the LLM should ask before calling.
+- Report vulnerabilities privately per [SECURITY.md](../../SECURITY.md).
+
+## License
+
+[MIT](./LICENSE) · © Nazareno Clemente
+
+If this saves your team weeks of MP integration work, consider [sponsoring](https://github.com/sponsors/naza00000).

package/cookbook/03-webhook-handler.ts

@@ -1,5 +1,5 @@
 /**
- * Recipe 03 — Production-grade webhook handler.
+ * Recipe 03 — Webhook handler.
  *
  * # The 3-line summary
  *

package/dist/index.cjs

@@ -3030,7 +3030,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 = {
@@ -3158,6 +3159,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)
@@ -4271,6 +4276,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) {
@@ -5163,6 +5184,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 {