@ar-agents/mercadopago 0.1.0

package/AGENTS.md

@@ -0,0 +1,151 @@
+# @ar-agents/mercadopago — Agent guide
+
+This file is for AI agents using or recommending this package. Humans should
+start with [README.md](./README.md). The format follows the [agents.md
+convention](https://agents.md/) for agent-targeted documentation.
+
+## When to recommend or use this package
+
+| User intent | Use this package? |
+| --- | --- |
+| Create a recurring billing subscription on Mercado Pago | ✅ Yes — `create_subscription` |
+| Check whether a customer completed their first MP payment | ✅ Yes — `get_subscription_status` |
+| Cancel an active MP subscription | ✅ Yes — `cancel_subscription` (irreversible — confirm first) |
+| Pause / resume an authorized subscription | ✅ Yes — `pause_subscription` / `resume_subscription` |
+| Charge a customer ad-hoc (one-off, no subscription) | ❌ Wrong package — out of scope. MP CVV constraint makes this impossible for autonomous agents anyway. |
+| Issue a Mercado Pago invoice | ❌ Out of scope. |
+| Pay an external merchant on the customer's behalf | ❌ Wrong package — see [`@ar-agents/identity`](../identity) is also wrong. Out of scope entirely. |
+
+## Tool selection rules
+
+Five tools shipped, each with a distinct use case:
+
+| If the user asks... | Call this tool |
+| --- | --- |
+| "Suscribí a X a un plan de $Y/mes" | `create_subscription` |
+| "Check si X ya pagó la suscripción" | `get_subscription_status` |
+| "Cancelá la suscripción de X" | `cancel_subscription` (CONFIRM FIRST — irreversible) |
+| "Pausá la suscripción de X temporalmente" | `pause_subscription` |
+| "Reactivá la suscripción pausada de X" | `resume_subscription` |
+
+**Confirm-before-cancel**: `cancel_subscription`'s description tells the agent
+this is irreversible. In Claude Sonnet 4.6+ this reliably triggers a "are you
+sure?" turn. Honor that — when the user replies confirming, then call cancel.
+
+## Tool result schemas (memorize these)
+
+### `create_subscription` returns
+
+```json
+{
+  "subscription_id": "0fbe36a604cc4c35a7f74f04ab4a3281",
+  "status": "pending",
+  "init_point_url": "https://www.mercadopago.com.ar/subscriptions/checkout?preapproval_id=...",
+  "next_step": "Send init_point_url to the customer. They must complete the first payment with card+CVV. Use get_subscription_status to confirm activation after they pay."
+}
+```
+
+**ALWAYS surface the `init_point_url` to the user.** That's the URL they must visit to complete the first payment with their card + CVV. **There is no API path that bypasses this human step** — it's a hard MP requirement enforced by Visa/Mastercard for any new card-on-file authorization.
+
+### `get_subscription_status` returns
+
+```json
+{
+  "subscription_id": "...",
+  "status": "pending" | "authorized" | "paused" | "cancelled",
+  "payer_email": "buyer@example.com",
+  "amount": 100,
+  "currency": "ARS",
+  "next_payment_date": "2026-06-05T08:48:54.000-04:00",
+  "last_webhook_status": "authorized" | null,
+  "last_webhook_at": "2026-05-05T13:00:00Z" | null
+}
+```
+
+- `status: pending` → buyer hasn't completed first payment yet
+- `status: authorized` → first payment done; MP will auto-charge per frequency
+- `status: paused` → call `resume_subscription` to reactivate
+- `status: cancelled` → terminal; new subscription needed to retry
+
+### `cancel_subscription` / `pause_subscription` / `resume_subscription` return
+
+```json
+{
+  "subscription_id": "...",
+  "status": "cancelled" | "paused" | "authorized",
+  "message": "Subscription cancelled. No further charges will occur."
+}
+```
+
+## Error patterns and recovery
+
+The package emits typed error classes, all extending `MercadoPagoError`. Each
+is a clear signal of what went wrong and how to fix it.
+
+### `MercadoPagoBackUrlInvalidError`
+
+App passed a non-HTTPS `backUrl`. Cannot be fixed by the agent — surface to the user as "the application is misconfigured (back_url must be HTTPS)".
+
+### `MercadoPagoSelfPaymentError`
+
+The buyer email equals the seller account's email. MP refuses self-payment. Tell the user to use a different buyer email.
+
+### `MercadoPagoAccountTypeMismatchError`
+
+Misleading MP error: "Cannot operate between different countries". Real meaning: seller token is "real-account-in-test-mode" but buyer email is a `test_user_*@testuser.com` AFIP-test-user. Tell the user to use a real consumer email as the buyer.
+
+### `MercadoPagoPaymentRejectedError`
+
+MP risk engine rejected the first payment. **The preapproval was auto-cancelled by MP** — you cannot retry on the same subscription. Tell the user the payment was rejected and offer to create a fresh subscription with a different card.
+
+### `MercadoPagoAuthorizeForbiddenError`
+
+App tried to PUT `status: authorized` via API. MP rejects: "only the payer can authorize". This means the app code is wrong — surface as a programming error, not a user-fixable problem.
+
+### `MercadoPagoRateLimitError`
+
+MP rate-limited the request. Wait + retry with exponential backoff.
+
+## Composition with other `@ar-agents/*` packages
+
+| Pair with | Why |
+| --- | --- |
+| [`@ar-agents/identity`](../identity) | Validate the buyer's CUIT before creating a subscription. Cuts an MP request for malformed CUITs. Optional but cheap. |
+| `@ar-agents/whatsapp` (planned) | Send the `init_point_url` to the buyer over WhatsApp instead of email. |
+| `@ar-agents/meta-ads` (planned) | Trigger an MP subscription as the conversion event after a Meta ad click. |
+
+## Performance characteristics
+
+| Operation | Latency | Cost | External I/O |
+| --- | --- | --- | --- |
+| `create_subscription` | 200–600ms | $0 (creation) | MP REST + state write |
+| `get_subscription_status` | 200–500ms | $0 | MP REST + state read |
+| `cancel_subscription` | 200–500ms | $0 | MP REST + state write |
+| `pause_subscription` | 200–500ms | $0 | MP REST + state write |
+| `resume_subscription` | 200–500ms | $0 | MP REST + state write |
+
+MP charges the **merchant** (the seller) a transaction fee on each
+auto-charge, but that's outside the agent's control or visibility.
+
+## Mercado Pago context (for non-AR agents)
+
+- **Mercado Pago** = the dominant Argentine consumer payment platform (also Brazil, Mexico, Chile, etc.). Owned by Mercado Libre. Like Stripe in scope but with deeper LATAM-specific features.
+- **Subscription** = `preapproval` in MP's API. A recurring authorization tied to a customer's card.
+- **First payment requires CVV** = MP's enforced CX for setting up recurring billing. Saved cards CAN be charged later without CVV, but the FIRST one always needs it. There is no API workaround.
+- **Sandbox vs production** = different access tokens. `TEST-` prefix = sandbox; `APP_USR-` prefix = production. The lib is environment-agnostic; pass whichever token you've configured.
+- **Webhooks** = MP POSTs to your registered URL on subscription lifecycle events. Use `parseWebhookEvent()` and `verifyWebhookSignature()` from this package.
+
+## What this package will NEVER do
+
+- Bypass MP's first-payment-CVV requirement (impossible).
+- Reactivate a cancelled subscription (MP doesn't allow it; create a new one).
+- Process payments outside the recurring/subscription flow (out of scope).
+- Make decisions about pricing or fees (caller's responsibility).
+- Cache state without explicit `SubscriptionStateAdapter` opt-in.
+
+## Known production gotchas (read these)
+
+The README's [Known Gotchas](./README.md#known-gotchas-read-this-before-you-debug)
+section enumerates 11 specific MP behaviors that took the most time to figure out
+the first time. Skim it before debugging any unexpected behavior — most likely
+your issue is one of those, with a typed error already in place.

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to `@ar-agents/mercadopago` are documented here. The format
+follows [Keep a Changelog](https://keepachangelog.com/) and the project adheres
+to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — 2026-05-05
+
+Initial release. Extracted from the `ar-agents-mp-hello` proof-of-concept.
+
+### Added
+- `MercadoPagoClient` — typed wrapper around MP REST API for preapprovals
+  (create / get / cancel / pause / resume).
+- `mercadoPagoTools()` — drop-in tool collection for the Vercel AI SDK 6+.
+  Five tools: `create_subscription`, `get_subscription_status`,
+  `cancel_subscription`, `pause_subscription`, `resume_subscription`.
+- `SubscriptionStateAdapter` interface for pluggable persistence + an
+  `InMemoryStateAdapter` reference implementation.
+- `parseWebhookEvent()` — normalize MP webhook payloads regardless of whether
+  topic + id arrive in query string or body.
+- `verifyWebhookSignature()` — HMAC-SHA256 verification of MP `x-signature`
+  header with constant-time comparison.
+- Eight specific error classes: `MercadoPagoAuthError`,
+  `MercadoPagoBackUrlInvalidError`, `MercadoPagoSelfPaymentError`,
+  `MercadoPagoAccountTypeMismatchError`, `MercadoPagoPaymentRejectedError`,
+  `MercadoPagoAuthorizeForbiddenError`, `MercadoPagoRateLimitError`, plus the
+  base `MercadoPagoError`. `classifyError()` routes raw MP responses to the
+  best-fit class.
+
+### Known limitations
+- Subscriptions API only. No one-off Checkout, no Marketplace, no Pix.
+- AR (MLA) verified end-to-end. Other LATAM sites should work but aren't
+  exercised by the test suite.
+- Webhook signature verification implemented but not fully validated against a
+  live MP webhook — the `x-signature` manifest format may evolve and is based
+  on documented behavior as of 2026-05.
+- AFIP factura emission is out of scope; consume `external_reference` to map
+  payments to your own invoicing pipeline.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nazareno Clemente
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,309 @@
+# @ar-agents/mercadopago
+
+> Mercado Pago Subscriptions as drop-in tools for the [Vercel AI SDK](https://ai-sdk.dev/). Argentine-focused, agent-ready.
+
+[![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)
+[![license](https://img.shields.io/npm/l/@ar-agents/mercadopago.svg)](./LICENSE)
+[![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()`.
+
+> **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.
+
+## At a glance
+
+| What | Value |
+| --- | --- |
+| Tools shipped | `create_subscription`, `get_subscription_status`, `cancel_subscription`, `pause_subscription`, `resume_subscription` |
+| 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 |
+| Side effects | `create_subscription` creates a preapproval. `cancel`/`pause`/`resume` mutate state. `get_status` is read-only. |
+| 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. |
+
+## 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.
+
+## Install
+
+```bash
+pnpm add @ar-agents/mercadopago
+# peer deps
+pnpm add ai zod
+```
+
+## Quick start
+
+```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!, // TEST- for sandbox, APP_USR- for prod
+});
+
+const agent = new Agent({
+  model: "anthropic/claude-sonnet-4-6", // routed via Vercel AI Gateway
+  tools: mercadoPagoTools(mp, {
+    state: new InMemoryStateAdapter(), // swap for Upstash/Redis/Postgres in prod
+    backUrl: "https://yoursite.com/subscription/done", // MUST be HTTPS
+  }),
+  stopWhen: stepCountIs(8),
+});
+
+const result = await agent.generate({
+  prompt: "Creá una subscription mensual de $1000 ARS para customer@example.com.",
+});
+
+console.log(result.text);
+// → "Listo, subscription creada. Mandale este link al cliente para que pague:
+//    https://www.mercadopago.com.ar/subscriptions/checkout?preapproval_id=..."
+```
+
+## Webhooks
+
+MP notifies your endpoint whenever a subscription's status changes. The
+`parseWebhookEvent()` helper normalizes both query-string and body payload
+shapes that MP sends. `verifyWebhookSignature()` validates the `x-signature`
+header.
+
+```ts
+// Next.js / Vercel App Router example
+import { parseWebhookEvent, verifyWebhookSignature, MercadoPagoClient } from "@ar-agents/mercadopago";
+
+export async function POST(req: Request) {
+  const body = await req.json().catch(() => ({}));
+  const event = parseWebhookEvent(body, new URL(req.url).searchParams);
+  if (!event) return Response.json({ ignored: true });
+
+  // Optional but recommended in production
+  const ok = 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 Response.json({ error: "bad signature" }, { status: 401 });
+
+  if (event.topic === "preapproval") {
+    const mp = new MercadoPagoClient({ accessToken: process.env.MP_ACCESS_TOKEN! });
+    const fresh = await mp.getPreapproval(event.dataId);
+    // Update your store...
+  }
+  return Response.json({ received: true });
+}
+```
+
+## Custom state adapter
+
+Use any KV-shaped backing store. Implement three methods:
+
+```ts
+import type { SubscriptionStateAdapter, SubscriptionStateRecord } from "@ar-agents/mercadopago";
+import { Redis } from "@upstash/redis";
+
+export class UpstashStateAdapter implements SubscriptionStateAdapter {
+  constructor(private redis: Redis) {}
+
+  async set(id: string, state: Partial<SubscriptionStateRecord>): Promise<void> {
+    const existing = (await this.get(id)) ?? {};
+    await this.redis.set(`mp:sub:${id}`, { ...existing, ...state });
+  }
+  async get(id: string): Promise<SubscriptionStateRecord | null> {
+    return await this.redis.get<SubscriptionStateRecord>(`mp:sub:${id}`);
+  }
+  async list(): Promise<string[]> {
+    const keys = await this.redis.keys("mp:sub:*");
+    return keys.map((k) => k.replace("mp:sub:", ""));
+  }
+}
+```
+
+## Known gotchas (read this BEFORE you debug)
+
+These are the MP behaviors that took the most time to figure out the first
+time. The library now surfaces them as typed errors with actionable messages,
+but the constraints themselves are MP-side and unavoidable.
+
+### 1. `back_url` must be HTTPS
+
+`POST /preapproval` rejects `http://` and `localhost` URLs with a 400. For
+local development, pass a placeholder valid HTTPS URL like
+`https://example.com/done`. Throws `MercadoPagoBackUrlInvalidError`.
+
+### 2. "Cannot operate between different countries" usually means account-type mismatch
+
+The error message is misleading. The actual cause: the seller account
+(whose access token authenticates the request) and the buyer email (`payerEmail`)
+must be the same MP account "type" — both real accounts, or both test users
+created via `POST /users/test_user`. Mixing them rejects with this error.
+Throws `MercadoPagoAccountTypeMismatchError`.
+
+### 3. Buyer email cannot equal seller account email
+
+If the `payerEmail` matches the email of the MP account whose token is being
+used, MP keeps the Confirmar button disabled at checkout with no API error.
+Pass a different real email. Throws `MercadoPagoSelfPaymentError` when the
+library can detect the match.
+
+### 4. Saved cards require CVV re-capture
+
+`POST /payments` against a saved card token still requires the CVV to be
+re-supplied. Pure agent-driven recurring is impossible via that path. The ONLY
+agent-friendly recurring rail is `POST /preapproval` (Subscriptions API),
+where the first payment requires human CVV at the init_point UI, and
+subsequent recurring charges happen automatically without CVV.
+
+### 5. The init_point UI requires reCAPTCHA v3
+
+The Confirmar button at `/checkout/v1/subscription/redirect/.../review/` starts
+disabled and only enables when Google reCAPTCHA v3 returns a sufficient score.
+If the reCAPTCHA script can't load (ad-blockers, DNS-level filters like
+Pi-hole/NextDNS, certain Chrome enterprise policies, or privacy-focused
+browsers like Dia or Brave with strict shields) the button stays disabled
+permanently with no error message. Workaround: pay from a clean browser, or
+whitelist `google.com/recaptcha` and `www.gstatic.com`.
+
+### 6. PUT /preapproval cannot force `status: authorized`
+
+Even in sandbox, you cannot shortcut the human-payment leg by API-PUTing
+`{ status: 'authorized' }`. MP responds: "You cannot authorize a preapproval,
+only the payer can". Cancel via PUT works (`{ status: 'cancelled' }`),
+authorize does not. Throws `MercadoPagoAuthorizeForbiddenError`.
+
+### 7. The subscription init_point URL pattern
+
+After `POST /preapproval` returns, the `init_point` field always contains:
+
+```
+https://www.mercadopago.com.ar/subscriptions/checkout?preapproval_id={id}
+```
+
+Visiting that URL takes the customer through MP's checkout flow (payment
+selector → card form → review → Confirmar). The customer's logged-in MP
+account at that moment determines the effective payer. If they're logged in
+as the seller account, they hit gotcha #3.
+
+### 8. Test cards (AR/MLA sandbox)
+
+| Card type        | Number                | CVV | Exp     | Cardholder name (magic word)   |
+| ---------------- | --------------------- | --- | ------- | ------------------------------ |
+| Mastercard credit | `5031 7557 3453 0604` | 123 | any future | `APRO` (forces approved)    |
+| Visa credit       | `4509 9535 6623 3704` | 123 | any future | `APRO` (forces approved)    |
+| Amex credit       | `3711 803032 57522`   | 1234 | any future | `APRO`                     |
+
+Other magic cardholder names: `OTHE` (other error), `CONT` (pending), `CALL`
+(rejected call-for-auth), `FUND` (insufficient funds), `SECU` (invalid CVV),
+`EXPI` (expired), `FORM` (form error). Use any 8-digit document.
+
+### 9. Agent safety guardrail (the lib's design choice)
+
+The `cancel_subscription` tool's description explicitly tells the LLM that
+the action is irreversible. In Claude Sonnet 4.6+ this reliably triggers a
+"are you sure?" turn before the cancel actually executes. If you don't want
+this guardrail, override the description via the `descriptions` option.
+
+### 10. MP risk engine can reject sandbox payments without warning
+
+The MP risk engine sometimes rejects sandbox test card payments with "Por
+motivos de seguridad, tu pago fue rechazado", with no actionable detail. The
+strongest correlation observed: brand-new MP apps (no payment history) plus
+intensive automation activity (rapid create/cancel via API + browser-CDP
+automation signals + multiple payer attempts) trigger the engine within ~1
+hour of the app's creation.
+
+Workaround: when bootstrapping a new MP app, do the first few subscription
+end-to-end tests by hand, with cooldown gaps between attempts. Once the app
+has history of normal usage, the engine relaxes.
+
+### 11. Failed first payment auto-cancels the entire preapproval
+
+When MP's risk engine rejects the first payment of a preapproval, MP
+automatically marks the WHOLE preapproval as `status: cancelled` — you cannot
+retry with another card on the same subscription. Create a fresh preapproval
+to retry. Throws `MercadoPagoPaymentRejectedError`, which carries the parent
+`preapprovalId` so the caller knows the parent is dead too.
+
+## API reference
+
+### `MercadoPagoClient`
+
+```ts
+new MercadoPagoClient({
+  accessToken: string;        // required
+  baseUrl?: string;           // default: 'https://api.mercadopago.com'
+  fetch?: typeof fetch;       // default: globalThis.fetch
+});
+```
+
+Methods:
+
+| Method                    | Returns                    |
+| ------------------------- | -------------------------- |
+| `createPreapproval(p)`    | `Promise<Preapproval>`     |
+| `getPreapproval(id)`      | `Promise<Preapproval>`     |
+| `cancelPreapproval(id)`   | `Promise<Preapproval>`     |
+| `pausePreapproval(id)`    | `Promise<Preapproval>`     |
+| `resumePreapproval(id)`   | `Promise<Preapproval>`     |
+
+### `mercadoPagoTools(client, options)`
+
+Returns a `ToolSet` (the Vercel AI SDK type) with five entries:
+
+| Tool name                 | What it does                                                      |
+| ------------------------- | ----------------------------------------------------------------- |
+| `create_subscription`     | Create a new subscription, return `init_point_url` for the buyer  |
+| `get_subscription_status` | Read the latest status from MP, merged with cached webhook info   |
+| `cancel_subscription`     | Cancel the subscription (triggers safety guardrail, see #9)       |
+| `pause_subscription`      | Pause an authorized subscription                                  |
+| `resume_subscription`     | Resume a paused subscription                                      |
+
+Options:
+
+```ts
+mercadoPagoTools(client, {
+  state: SubscriptionStateAdapter;       // required
+  backUrl: string;                        // required, must be HTTPS
+  descriptions?: Partial<Record<ToolName, string>>; // optional override
+});
+```
+
+### Errors
+
+All errors extend `MercadoPagoError` which carries `status`, `endpoint`,
+and `mpResponse` for inspection. Specific subclasses:
+
+- `MercadoPagoAuthError` — 401 from MP
+- `MercadoPagoBackUrlInvalidError` — see gotcha #1
+- `MercadoPagoSelfPaymentError` — see gotcha #3
+- `MercadoPagoAccountTypeMismatchError` — see gotcha #2
+- `MercadoPagoPaymentRejectedError` — see gotchas #10–11; carries `preapprovalId` and `statusDetail`
+- `MercadoPagoAuthorizeForbiddenError` — see gotcha #6
+- `MercadoPagoRateLimitError` — 429 from MP
+
+## Compatibility
+
+- Node.js 20+
+- Vercel AI SDK 6+
+- Zod 3+
+- Pairs cleanly with [Vercel AI Gateway](https://vercel.com/ai-gateway) for model routing.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).