@ar-agents/mercadopago 0.15.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,18 @@
 # 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)
@@ -221,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)**
 
@@ -329,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
@@ -346,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
 

package/README.skeleton.md

@@ -21,7 +21,7 @@
 [![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 Subscriptions, Payments, Checkout Pro, Marketplace, and Point — as drop-in tools for the [Vercel AI SDK](https://ai-sdk.dev/). Argentine-focused, agent-ready, Edge-Runtime-safe.
+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.
 
@@ -164,7 +164,7 @@ const limiter = new VercelKVRateLimiter({
 
 ### Cookbook
 
-8 production-grade recipes in [`./cookbook`](./cookbook/) — Checkout Pro, SaaS subscription, webhook handler, marketplace split, QR in-store, 3DS challenge, manual capture, recovery patterns, full OpenTelemetry wiring.
+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
 

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ar-agents/mercadopago",
-  "version": "0.15.0",
-  "description": "The most complete Mercado Pago agent toolkit for Vercel AI SDK 6+. 82 tools, Edge Runtime, Vercel KV adapters, circuit breaker + deadline propagation + W3C trace context, HMAC webhook verify with replay protection, OAuth Marketplace, Order Management, Point Devices, marketplace splits, status_detail explainer in Spanish, AR-specific knowledge baked in. Property-tested + integration-tested vs MP sandbox + benchmarked.",
+  "version": "0.15.1",
+  "description": "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. Edge Runtime. Vercel KV adapters. OpenTelemetry. Deterministic idempotency. Programmatic HITL on irreversible ops.",
   "keywords": [
     "mercadopago",
     "mp",

package/tools.manifest.json

@@ -656,7 +656,6 @@
   ],
   "name": "@ar-agents/mercadopago",
   "meta": {
-    "generated_at": "2026-05-06T20:54:56.481Z",
     "generated_by": "scripts/regen-manifests.mjs",
     "tool_count": 89
   }