@ar-agents/mercadopago 0.15.2 → 0.16.0

package/AGENTS.md

@@ -1,10 +1,10 @@
-# @ar-agents/mercadopago — agent guide
+# @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 89 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
+## Decision tree: pick the right tool
 
 | User intent | Tool to call |
 |---|---|
@@ -13,12 +13,12 @@ This file is for AI agents using or recommending this package. Humans should sta
 | **"Aceptale $X con account_money / Rapipago / Pago Fácil"** (server-side, no card form) | `create_payment` (omit `token`) |
 | **"Aceptale con tarjeta token X"** (you have a card_token from MP frontend SDK) | `create_payment` (with `token`) |
 | **"¿Pagó ya?"** (check status) | `get_payment` (one-off) or `get_subscription_status` (recurring) |
-| **"Devolvele la plata"** | `refund_payment` — full or partial. Confirm first if amount > 1000 ARS. |
-| **"Cuántas cuotas tiene esta tarjeta para $X?"** | `calculate_installments` — surface the `recommended_message` strings VERBATIM (already in compliant Spanish format) |
+| **"Devolvele la plata"** | `refund_payment`: full or partial. Confirm first if amount > 1000 ARS. |
+| **"Cuántas cuotas tiene esta tarjeta para $X?"** | `calculate_installments`: surface the `recommended_message` strings VERBATIM (already in compliant Spanish format) |
 | **"Buscá los pagos de [referencia/email]"** | `search_payments` |
 | **"Cancelá ese pago pendiente"** | `cancel_payment` (only `pending`/`in_process`; for approved use `refund_payment`) |
 | **"Capturá ese pago autorizado"** | `capture_payment` (for capture-later flows with `capture: false`) |
-| **"Buscá / Creá al cliente con email X"** | `find_customer_by_email` then `create_customer` (or call `create_customer` directly — MP is idempotent on email) |
+| **"Buscá / Creá al cliente con email X"** | `find_customer_by_email` then `create_customer` (or call `create_customer` directly: MP is idempotent on email) |
 | **"Listame las tarjetas guardadas de X"** | `list_customer_cards` |
 | **"Borrá esa tarjeta"** | `delete_customer_card` |
 | **"Listame los métodos disponibles"** | `list_payment_methods` |
@@ -33,7 +33,7 @@ This file is for AI agents using or recommending this package. Humans should sta
 | **"Qué bancos emiten Visa?"** | `list_issuers(payment_method_id: "visa")` (pass `bin` for accurate match) |
 | **"Listame los tipos de identificación válidos en AR"** | `list_identification_types` (DNI/CUIT/CUIL/etc) |
 | **"Configurame un webhook para recibir notificaciones de pagos"** | `list_webhooks` first, then `create_webhook(url, topic: "payment")` if not present |
-| **"Procesame este webhook que me llegó de MP"** (v0.5) | `handle_webhook` — verifica HMAC + parsea + auto-fetch del recurso en una sola call |
+| **"Procesame este webhook que me llegó de MP"** (v0.5) | `handle_webhook`: verifica HMAC + parsea + auto-fetch del recurso en una sola call |
 | **"Vincular cuenta MP de un vendedor a mi marketplace"** (v0.5) | `oauth_authorize_url` → vendedor aprueba → `oauth_exchange_code` → persistir token → `oauth_refresh_token` cuando expira |
 | **"Cobrar a través de un seller third-party con fee de marketplace"** (v0.5) | `create_order` con `marketplace_fee` + `collector_id` (o `create_payment_preference` con los mismos campos) |
 | **"Autorizar ahora, capturar después"** (ride-share, hotel, marketplace) (v0.5) | `create_order` con `capture_mode: "manual"` → cuando completás el servicio, `capture_order(order_id)` |
@@ -45,12 +45,12 @@ This file is for AI agents using or recommending this package. Humans should sta
 | **"Listame mis dispositivos Point/Smart"** (v0.7) | `list_point_devices` |
 | **"Cobrá $1000 en el Point que está en la caja"** (v0.7) | `create_point_payment_intent({ device_id, amount_centavos: 100000 })` (¡amount en CENTAVOS!) |
 | **"A qué CBU me deposita MP"** (v0.7) | `list_bank_accounts` (el `is_default: true` es el activo) |
-| **"Calculá el fee del marketplace para este monto"** (v0.7) | `compute_marketplace_fee({ amount_ars, percent, minArs, maxArs })` (PURE — no network) |
+| **"Calculá el fee del marketplace para este monto"** (v0.7) | `compute_marketplace_fee({ amount_ars, percent, minArs, maxArs })` (PURE: no network) |
 | **"Por qué falló este pago / qué hago ahora"** (v0.7) | `explain_payment_status({ payment_id })` (devuelve `{ summary, recommendedAction, retryable }` en español) |
 
 ## The two main "take a payment" patterns
 
-### Pattern A — hosted checkout (recommended for most agent flows)
+### Pattern A: hosted checkout (recommended for most agent flows)
 
 You only have a payer email. You don't want to handle PCI data. You want a URL to send via WhatsApp/email.
 
@@ -63,7 +63,7 @@ MP fires webhook with topic="payment", data.id=<payment_id>
 agent: get_payment(payment_id) → confirms status
 ```
 
-### Pattern B — server-side payment (when you have a card_token OR using non-card method)
+### Pattern B: server-side payment (when you have a card_token OR using non-card method)
 
 You have a `token` from MP frontend SDK (Cardform/Bricks) OR you're charging account_money / cash.
 
@@ -72,7 +72,7 @@ agent: create_payment({ amount, payment_method_id, payer_email, token?, installm
 agent: → returns { payment_id, status: "approved" | "pending" | "rejected", status_detail }
 ```
 
-**NEVER take raw card data in the agent runtime.** Card tokens come from MP's frontend SDK only. If the user pastes "4509 9535 6623 3704" into chat, REFUSE — that's a PCI violation. Always direct them to a hosted form via `create_payment_preference`.
+**NEVER take raw card data in the agent runtime.** Card tokens come from MP's frontend SDK only. If the user pastes "4509 9535 6623 3704" into chat, REFUSE: that's a PCI violation. Always direct them to a hosted form via `create_payment_preference`.
 
 ## Result schemas (memorize)
 
@@ -120,7 +120,7 @@ agent: → returns { payment_id, status: "approved" | "pending" | "rejected", st
   }]
 }
 ```
-**Surface `recommended_message` verbatim to the user** — it's already in compliant Argentine Spanish format with proper currency formatting and includes the total when there's interest. AR's E 51/2017 transparency regulation requires this exact phrasing.
+**Surface `recommended_message` verbatim to the user**: it's already in compliant Argentine Spanish format with proper currency formatting and includes the total when there's interest. AR's E 51/2017 transparency regulation requires this exact phrasing.
 
 ### `refund_payment` returns
 ```jsonc
@@ -142,12 +142,12 @@ agent: → returns { payment_id, status: "approved" | "pending" | "rejected", st
 | `cc_rejected_bad_filled_security_code` | CVV wrong | "El código de seguridad no coincide" |
 | `cc_rejected_bad_filled_date` | Expiration wrong | "La fecha de vencimiento es incorrecta" |
 | `cc_rejected_call_for_authorize` | Bank wants user to call | "Llamá a tu banco para autorizar el pago, después intentá de nuevo" |
-| `cc_rejected_card_disabled` | Card disabled | "Tu tarjeta está deshabilitada — usá otra" |
-| `cc_rejected_insufficient_amount` | Not enough funds | "Saldo insuficiente — usá otra tarjeta o método" |
+| `cc_rejected_card_disabled` | Card disabled | "Tu tarjeta está deshabilitada: usá otra" |
+| `cc_rejected_insufficient_amount` | Not enough funds | "Saldo insuficiente: usá otra tarjeta o método" |
 | `cc_rejected_high_risk` / `cc_rejected_other_reason` | MP risk engine rejection | "El pago fue rechazado. Probá con otro método (Rapipago / account money)" |
 | `cc_rejected_max_attempts` | Too many tries | "Esperá 24h antes de reintentar" |
-| `cc_rejected_invalid_installments` | Cuotas no allowed for this card | "Probá con menos cuotas" — re-call `calculate_installments` |
-| `pending_waiting_payment` | Ticket created (Rapipago/Pago Fácil) | "Pagá el ticket en cualquier sucursal — se acredita en 1-3 días" |
+| `cc_rejected_invalid_installments` | Cuotas no allowed for this card | "Probá con menos cuotas": re-call `calculate_installments` |
+| `pending_waiting_payment` | Ticket created (Rapipago/Pago Fácil) | "Pagá el ticket en cualquier sucursal: se acredita en 1-3 días" |
 | `pending_contingency` | MP manual review | "Esperá unos minutos, MP está revisando el pago" |
 
 ## Critical AR-specific gotchas
@@ -157,25 +157,25 @@ agent: → returns { payment_id, status: "approved" | "pending" | "rejected", st
 3. **Sandbox cardholder name selects outcome**: cardholder = `APRO` (approved), `OTHE` (rejected_other), `CONT` (pending_contingency), `CALL` (call_for_authorize), `FUND` (insufficient_amount), `SECU` (bad_filled_security_code), `EXPI` (bad_filled_date), `FORM` (bad_filled_other). DNI = `12345678`. ANY 3-digit CVV in sandbox.
 4. **Test cards (sandbox)**: Visa `4509 9535 6623 3704`, MasterCard `5031 7557 3453 0604`, Amex `3711 803032 57522`, debit Visa `4002 7686 9439 5619`. Expiration any future `MM/YY`.
 5. **`account_money` settles instantly** to seller. Card payments default to T+14 hold for new sellers (drops to T+1 after MP graduates the merchant). Tickets settle 1-3 days after the buyer pays.
-6. **First subscription payment requires CVV** — there is NO API path that bypasses this. The buyer MUST visit the `init_point_url` and complete the first card+CVV payment.
-7. **`back_url` MUST be HTTPS** — even in sandbox. `http://localhost:3000/done` is rejected.
-8. **`payer.identification`** — use `DNI` for consumers, `CUIT` for B2B (required for monotributo / IVA-discriminated invoicing), `CUIL` for employees.
+6. **First subscription payment requires CVV**: there is NO API path that bypasses this. The buyer MUST visit the `init_point_url` and complete the first card+CVV payment.
+7. **`back_url` MUST be HTTPS**: even in sandbox. `http://localhost:3000/done` is rejected.
+8. **`payer.identification`**: use `DNI` for consumers, `CUIT` for B2B (required for monotributo / IVA-discriminated invoicing), `CUIL` for employees.
 9. **CVV required on every saved-card charge** in AR by default. Merchant graduation can lift this for trusted sellers.
 10. **Idempotency-Key is mandatory** for POST since 2023. The lib auto-generates from caller-meaningful fields (external_reference + amount + timestamp); pass `idempotencyKey` explicitly if you want exact-match retry semantics.
-11. **`token` is single-use and expires in 7 days.** If a card payment fails, you can't reuse the token — re-tokenize on the frontend.
+11. **`token` is single-use and expires in 7 days.** If a card payment fails, you can't reuse the token: re-tokenize on the frontend.
 
-## Cuotas / installments — the killer AR feature
+## Cuotas / installments: the killer AR feature
 
 This is what makes MP unique vs Stripe in any country. Workflow:
 
 1. Buyer's card BIN (first 6 digits) hits your frontend (Cardform exposes it before tokenizing).
 2. Agent calls `calculate_installments({ amount_ars, payment_method_id, bin })`.
 3. Receive `payer_costs` array.
-4. **Surface the `recommended_message` strings verbatim** — they're already in compliant AR format ("3 cuotas sin interés de $X").
+4. **Surface the `recommended_message` strings verbatim**: they're already in compliant AR format ("3 cuotas sin interés de $X").
 5. User picks installments count.
 6. Agent calls `create_payment({ ..., installments: N })`.
 
-**Cuotas Simples** (gov interest-free 3 + 6 mo program) appears automatically as `installment_rate: 0` rows when the merchant category qualifies. Agent doesn't configure — just surfaces.
+**Cuotas Simples** (gov interest-free 3 + 6 mo program) appears automatically as `installment_rate: 0` rows when the merchant category qualifies. Agent doesn't configure: just surfaces.
 
 **Issuer-specific promos** (Día de la Madre, Hot Sale, Plan Z Naranja X) appear as new `payer_costs` entries when the BIN matches an active promo. Same treatment: surface verbatim.
 
@@ -199,7 +199,7 @@ This is what makes MP unique vs Stripe in any country. Workflow:
 | `refund_payment` | 300-800ms | 3s |
 | `create_subscription` | 200-600ms | 2s |
 
-Rate limit: ~250 req/min per access token. Lib does not retry — wrap with your own backoff if you exceed.
+Rate limit: ~250 req/min per access token. Lib does not retry: wrap with your own backoff if you exceed.
 
 ## Webhooks (planned for v0.3)
 
@@ -214,9 +214,9 @@ v0.2 ships `parseWebhookEvent()` for the `preapproval` topic (subscription lifec
 - Bypass MP's first-payment-CVV requirement for subscriptions (impossible).
 - Reactivate a cancelled subscription or payment (MP doesn't allow).
 - Pay out the seller (transfers + withdrawals are dashboard-only / closed API).
-- Make decisions about pricing or installments — caller's responsibility.
+- Make decisions about pricing or installments: caller's responsibility.
 
-## v0.5 — Webhook handler combo
+## v0.5: Webhook handler combo
 
 Webhooks are how MP tells you a payment cleared, a subscription was authorized,
 a QR was scanned. Without HMAC verification, anyone can POST to your webhook
@@ -241,15 +241,15 @@ the `MercadoPagoClient` with the SELLER's access_token before calling
 needs to look up the seller from the webhook payload's `user_id` and pick
 the right client.
 
-## v0.5 — OAuth Marketplace flow
+## v0.5: OAuth Marketplace flow
 
 For marketplace platforms (Rappi, MercadoLibre, Tienda Nube, etc.) where
 your app cobra a través de cuentas MP de terceros (sellers in your platform).
 
 **3 legs**:
-1. `oauth_authorize_url` — pure function, no network. Returns a URL; redirect the seller there.
-2. `oauth_exchange_code` — server-side. Takes the `code` from the OAuth callback, returns `{ user_id, access_token, refresh_token, expires_in }`. **Persist all of it.**
-3. `oauth_refresh_token` — server-side. Use saved `refresh_token` to get a fresh `access_token` before/at expiration.
+1. `oauth_authorize_url`: pure function, no network. Returns a URL; redirect the seller there.
+2. `oauth_exchange_code`: server-side. Takes the `code` from the OAuth callback, returns `{ user_id, access_token, refresh_token, expires_in }`. **Persist all of it.**
+3. `oauth_refresh_token`: server-side. Use saved `refresh_token` to get a fresh `access_token` before/at expiration.
 
 **Token storage shape** (per seller):
 ```
@@ -265,7 +265,7 @@ your app cobra a través de cuentas MP de terceros (sellers in your platform).
 
 **Marketplace fee**: pass `marketplace_fee` (in ARS) + `collector_id: token.user_id` to `create_order` or `create_payment_preference`. Funds route to the seller, fee goes to your marketplace account.
 
-## v0.5 — Order Management vs Preference
+## v0.5: Order Management vs Preference
 
 | When                                    | Use                       |
 | --------------------------------------- | ------------------------- |

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.16.0
+
+### Minor Changes
+
+- Add `@ar-agents/mercadopago/testing` subpath: factories + a mock client for tests.
+
+  What ships:
+
+  - **Factories**: `mockPayment`, `mockPreapproval`, `mockSubscriptionPayment`, `mockPreference`, `mockRefund`, `mockCustomer`. Each takes a partial overrides object so test setup is one line.
+  - **`MockMercadoPagoClient`**: in-memory client with the most-common create/get/cancel/refund paths. Read-only methods that don't fit a clean store model throw `MockNotImplementedError` to nudge users toward MSW or a real sandbox token rather than silently growing the mock.
+  - **`mockSignedWebhook`**: produces a `{ headers, searchParams, body }` triple whose `x-signature` header is a real HMAC-SHA256 against the secret you pass. Drops directly into `verifyWebhookSignature` — test the full webhook stack without hand-rolling the signature manifest.
+
+  Subpath was chosen over the main entry to keep the production bundle clean (the testing helpers are dev-only).
+
+  ```ts
+  import {
+    MockMercadoPagoClient,
+    mockPayment,
+    mockSignedWebhook,
+  } from "@ar-agents/mercadopago/testing";
+  ```
+
+  15 new unit tests (testing-subpath.test.ts), still 100% passing.
+
+## 0.15.3
+
+### Patch Changes
+
+- [`da49fde`](https://github.com/ar-agents/ar-agents/commit/da49fde136ecea89b4755fe74b3ed91ed9720f46) - Enable [npm provenance attestation](https://docs.npmjs.com/generating-provenance-statements) for all `@ar-agents/*` packages. From this version on, the npm registry includes a verifiable cryptographic record that the package was built from this exact GitHub commit, via the GitHub Actions `release.yml` workflow. Boosts supply-chain audit scores (Socket / Snyk / npm) and lets downstream agents verify package integrity without trusting the publisher.
+
+  No API or runtime changes.
+
 ## 0.15.2
 
 ### Patch — docs: tool-count accuracy (87 → 89)
@@ -51,7 +83,8 @@ distinguishable from declined confirmations.
 
 ```ts
 mercadoPagoTools(client, {
-  state, backUrl,
+  state,
+  backUrl,
   requireConfirmation: async (op, args) => {
     return await slack.confirm({
       channel: "#mp-approvals",
@@ -93,6 +126,7 @@ 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.
@@ -101,6 +135,7 @@ used `z.record(z.string(), z.unknown())`:
   `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.
 
@@ -191,6 +226,7 @@ partitions. This makes the safe default: safe.
   pause/resume — already deduped by id).
 
 6 new tests in `idempotency-default.test.ts` verify:
+
 - UUID v4 format on auto-gen
 - Different keys per call
 - Caller-supplied keys honored over auto-gen
@@ -378,28 +414,34 @@ Architectural features for at-scale deployment.
 - MP v0.7: +25 new tools (81 total).
 
   **Cierre de gaps obvios (8 tools)**:
+
   - `get_customer`, `update_customer`, `create_customer_card`, `get_customer_card`
   - `get_subscription_plan`, `update_subscription`, `search_subscriptions`
   - `get_refund`, `update_payment_preference`
 
   **Merchant Orders (3 tools — categoría completa nueva)**:
+
   - `get_merchant_order`, `search_merchant_orders`, `update_merchant_order`
   - MerchantOrder agrupa Payments asociados a una Preference — clave para reconciliar webhooks con `topic='merchant_order'`.
 
   **Stores + POS CRUD completion (6 tools)**:
+
   - `get_store`, `update_store`, `delete_store`
   - `get_pos`, `update_pos`, `delete_pos`
 
   **Bank Accounts (2 tools)**:
+
   - `list_bank_accounts`, `register_bank_account`
 
   **Point Devices físicos (5 tools — categoría nueva)**:
+
   - `list_point_devices` (terminales físicas: Smart, Tap to Pay)
   - `update_point_device_mode` (PDV vs STANDALONE)
   - `create_point_payment_intent` (push payment al device — amount en CENTAVOS)
   - `get_point_payment_intent`, `cancel_point_payment_intent`
 
   **Pure helpers (2 tools, high-leverage)**:
+
   - `compute_marketplace_fee` — given amount + (% o flat ARS, con min/max), returns exact `marketplace_fee`
   - `explain_payment_status` — dado un Payment, traduce los 30+ status_detail codes a `{ summary, recommendedAction, final, paid, retryable }` en español
 

package/MIGRATION.md

@@ -1,9 +1,9 @@
-# Migration guide — `mercadopago` (official SDK) → `@ar-agents/mercadopago`
+# Migration guide: `mercadopago` (official SDK) → `@ar-agents/mercadopago`
 
 If you're already using MP's official Node SDK and want to switch to (or
 add on top of) the agent toolkit, this guide shows the side-by-side mapping.
 
-The agent toolkit is **not** a drop-in replacement — it's a layer ABOVE
+The agent toolkit is **not** a drop-in replacement: it's a layer ABOVE
 the underlying API designed for AI agents. You can use both packages in
 the same project: keep `mercadopago` for traditional server flows, add
 `@ar-agents/mercadopago` for the agent layer.
@@ -47,7 +47,7 @@ const created = await payment.create({
 console.log(created.id, created.status);
 ```
 
-**After (`@ar-agents/mercadopago` — direct client):**
+**After (`@ar-agents/mercadopago`: direct client):**
 
 ```ts
 import { MercadoPagoClient } from "@ar-agents/mercadopago";
@@ -65,7 +65,7 @@ const created = await client.createPayment({
 console.log(created.id, created.status);
 ```
 
-**After (`@ar-agents/mercadopago` — agent tool):**
+**After (`@ar-agents/mercadopago`: agent tool):**
 
 ```ts
 import { MercadoPagoClient, mercadoPagoTools, InMemoryStateAdapter } from "@ar-agents/mercadopago";
@@ -82,7 +82,7 @@ const tools = mercadoPagoTools(client, {
 
 ## Side-by-side: webhook signature verification
 
-**Before (`mercadopago`)**: not provided — you implement HMAC-SHA256 yourself
+**Before (`mercadopago`)**: not provided: you implement HMAC-SHA256 yourself
 from the docs.
 
 **After (`@ar-agents/mercadopago`):**
@@ -139,7 +139,7 @@ new MercadoPagoClient({
 - **Deadline propagation** via parent `AbortSignal`
 - **W3C Trace Context** propagation (OpenTelemetry compat sin peer dep)
 - **Audit logging** with pluggable adapter (`AuditLogger` + `InMemoryAuditLog`)
-- **Webhook idempotency dedup** (`WebhookDedup` — short-circuits MP retries)
+- **Webhook idempotency dedup** (`WebhookDedup`: short-circuits MP retries)
 - **Pagination helpers** (`paginate()` AsyncIterable for 7 endpoints)
 - **Token bucket rate limiter** with adaptive learning from MP headers
 - **AR issuer cuotas catalog** (`AR_ISSUER_PROMOS`, `findApplicablePromos`)
@@ -147,7 +147,7 @@ new MercadoPagoClient({
 - **Tool middleware pattern** (`withAuditLog`, `withRateLimit`, `withMetrics`, `withRetry`)
 - **3DS challenge resolution** (`confirmChallengeAndPoll`)
 - **TaxID validation cross-LATAM** (DNI/CUIT/CPF/CNPJ/RFC/RUT/NIT/RUC)
-- **Status detail explainer** (`explainPaymentStatus` — Spanish actionable guidance)
+- **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 cookbook recipes
@@ -173,4 +173,4 @@ new MercadoPagoClient({
 - You want **AR-specific knowledge** (cuotas catalog, status_detail explainer in Spanish, AR landmines documented)
 - You want **OpenTelemetry-native** observability without writing instrumentation glue
 
-You can use BOTH packages in the same project — they don't conflict.
+You can use BOTH packages in the same project: they don't conflict.

package/README.md

@@ -13,30 +13,31 @@
 [![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)
+[![npm provenance](https://img.shields.io/badge/npm%20provenance-SLSA%20v1-7C3AED?logo=npm)](https://docs.npmjs.com/generating-provenance-statements)
 [![bundle size](https://img.shields.io/bundlephobia/minzip/@ar-agents/mercadopago.svg)](https://bundlephobia.com/package/@ar-agents/mercadopago)
 
 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.
+> **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 | **89 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`. |
+| Tools shipped | **89 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`). |
+| 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 |
+| 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. |
-| 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. |
+| 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 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. |
+| 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
 
@@ -51,7 +52,7 @@ the documented gotchas into typed errors with actionable messages.
 
 [![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Far-agents%2Far-agents&root-directory=apps%2Fmp-hello&env=MP_ACCESS_TOKEN%2CANTHROPIC_API_KEY%2CUPSTASH_REDIS_REST_URL%2CUPSTASH_REDIS_REST_TOKEN&envDescription=Mercado%20Pago%20access%20token%2C%20Anthropic%20API%20key%2C%20and%20Upstash%20Redis%20credentials%20for%20subscription%20state.&envLink=https%3A%2F%2Fgithub.com%2Far-agents%2Far-agents%2Ftree%2Fmain%2Fapps%2Fmp-hello%23setup&project-name=mp-hello&repository-name=mp-hello)
 
-`apps/mp-hello` ships as a clonable Vercel template — Edge Runtime API routes,
+`apps/mp-hello` ships as a clonable Vercel template: Edge Runtime API routes,
 MP webhook handler with HMAC verify, Upstash-backed subscription state.
 
 ## Install
@@ -169,7 +170,7 @@ local development, pass a placeholder valid HTTPS URL like
 
 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
+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`.
 
@@ -253,7 +254,7 @@ 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
+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.
@@ -293,9 +294,9 @@ selection guidance. Highlights:
 - **In-store QR + POS** (4 tools): create_qr_payment, cancel_qr_payment, create_store, create_pos
 - **Cuotas + lookups** (3 tools): calculate_installments, list_payment_methods, list_issuers
 - **Disputes + Webhooks management** (6 tools): list_payment_disputes, create_webhook, list_webhooks…
-- **v0.5 — Webhook handler combo** (1 tool): `handle_webhook` — verify HMAC + parse + auto-fetch in ONE call
-- **v0.5 — OAuth Marketplace** (3 tools): `oauth_authorize_url`, `oauth_exchange_code`, `oauth_refresh_token` — wire third-party MP accounts to your platform
-- **v0.5 — Order Management API** (5 tools): `create_order`, `get_order`, `update_order`, `capture_order`, `cancel_order` — modern API with auth-only support and marketplace splits
+- **v0.5: Webhook handler combo** (1 tool): `handle_webhook`: verify HMAC + parse + auto-fetch in ONE call
+- **v0.5: OAuth Marketplace** (3 tools): `oauth_authorize_url`, `oauth_exchange_code`, `oauth_refresh_token`: wire third-party MP accounts to your platform
+- **v0.5: Order Management API** (5 tools): `create_order`, `get_order`, `update_order`, `capture_order`, `cancel_order`: modern API with auth-only support and marketplace splits
 
 Options:
 
@@ -309,7 +310,7 @@ mercadoPagoTools(client, {
 });
 ```
 
-### v0.5 — Webhook handler combo
+### v0.5: Webhook handler combo
 
 ```ts
 // In your /api/mercadopago/webhook handler
@@ -324,10 +325,10 @@ if (!result.verified) return new Response("unauthorized", { status: 401 });
 // Use result.event.topic, result.event.dataId, result.resource (Payment | Preapproval | …)
 ```
 
-### v0.5 — OAuth Marketplace flow (3 legs)
+### v0.5: OAuth Marketplace flow (3 legs)
 
 ```ts
-// 1. Build authorize URL — redirect the seller here
+// 1. Build authorize URL: redirect the seller here
 const { url } = await tools.oauth_authorize_url.execute({
   redirect_uri: "https://app.test/oauth/callback",
   state: cryptoRandomToken(), // bind to user's session, verify on redirect
@@ -349,7 +350,7 @@ const { token } = await tools.oauth_refresh_token.execute({
 const sellerClient = new MercadoPagoClient({ accessToken: token.access_token });
 ```
 
-### v0.5 — Marketplace split payments
+### v0.5: Marketplace split payments
 
 For two-sided platforms (Rappi-style) where you collect on a seller's behalf
 and take a fee, pass `marketplace`, `marketplace_fee`, `collector_id` to
@@ -371,20 +372,20 @@ await tools.create_order.execute({
 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
+- `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
 
 ## Production hardening (v0.9+)
 
 ### Circuit breaker
 
 Protect your app from cascading failures when MP is degraded. The breaker
-observes failures over a rolling window — after enough, it OPENS and fails
+observes failures over a rolling window: after enough, it OPENS and fails
 fast (no network round-trip) until cooldown elapses.
 
 ```ts
@@ -393,7 +394,7 @@ import { CircuitBreaker, MercadoPagoClient, CircuitOpenError } from "@ar-agents/
 const breaker = new CircuitBreaker({
   failureThreshold: 5,
   resetTimeoutMs: 30_000,
-  // Don't count 4xx user errors toward circuit opening — only upstream failures
+  // Don't count 4xx user errors toward circuit opening: only upstream failures
   isFailure: (err) => err instanceof MercadoPagoError && err.status >= 500,
   onStateChange: (e) => metrics.gauge(`mp.circuit.${e.to}`, 1),
 });
@@ -407,7 +408,7 @@ try {
   await client.getPayment("123");
 } catch (err) {
   if (err instanceof CircuitOpenError) {
-    // MP is down, breaker tripped — fast-fail without network
+    // MP is down, breaker tripped: fast-fail without network
     return showFallbackUi(err.retryAfterMs);
   }
   throw err;
@@ -415,11 +416,11 @@ try {
 ```
 
 **Multi-tenant marketplace**: pass the same `CircuitBreaker` instance to all
-per-seller `MercadoPagoClient`s — they share backpressure signal.
+per-seller `MercadoPagoClient`s: they share backpressure signal.
 
 ### Deadline propagation
 
-Pass the agent's `AbortSignal` to chain deadlines through to MP — when the
+Pass the agent's `AbortSignal` to chain deadlines through to MP: when the
 agent's budget expires, MP requests cancel cleanly without retrying.
 
 ```ts
@@ -467,7 +468,7 @@ Vercel Cron monitoring loops.
 | Operation | Throughput |
 |---|---|
 | `hmacSha256Hex` (typical webhook manifest) | 45,932 ops/sec |
-| `sha256Hex` (40-byte input — idempotency key) | 92,218 ops/sec |
+| `sha256Hex` (40-byte input: idempotency key) | 92,218 ops/sec |
 | `timingSafeEqualHex` (64 chars) | 3,099,551 ops/sec |
 | `computeMarketplaceFee` | 20,662,947 ops/sec |
 | `explainPaymentStatus` | 21,289,436 ops/sec |
@@ -479,7 +480,7 @@ Run `pnpm bench` to reproduce.
 
 The toolkit ships first-class adapters for Vercel infrastructure via the
 `@ar-agents/mercadopago/vercel-kv` subpath. `@vercel/kv` is an **optional**
-peer dep — only install it if you use the subpath.
+peer dep: only install it if you use the subpath.
 
 ```ts
 import { mercadoPagoTools, MercadoPagoClient } from "@ar-agents/mercadopago";
@@ -507,7 +508,7 @@ const tools = mercadoPagoTools(
 
 The toolkit (including HMAC webhook verification) is fully Edge-Runtime
 compatible. Add `export const runtime = "edge"` to any Vercel route handler
-that uses MP tools — sub-100ms global cold starts.
+that uses MP tools: sub-100ms global cold starts.
 
 ### Vercel Cron + Blob + Functions
 
@@ -543,7 +544,7 @@ Each recipe is copy-pasteable into a Next.js route handler.
 
 ## License
 
-MIT — see [LICENSE](./LICENSE).
+MIT: see [LICENSE](./LICENSE).
 
 ## Stability