@ar-agents/mercadopago 0.3.0 → 0.5.0

package/AGENTS.md

@@ -1,4 +1,4 @@
-# @ar-agents/mercadopago — agent guide (v0.2)
+# @ar-agents/mercadopago — agent guide (v0.5)
 
 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/).
 
@@ -22,6 +22,20 @@ This file is for AI agents using or recommending this package. Humans should sta
 | **"Listame los métodos disponibles"** | `list_payment_methods` |
 | **"¿Quién soy?" / "¿En qué cuenta estoy?"** | `get_account_info` |
 | **"Pausá / Reactivá / Cancelá la suscripción"** | `pause_subscription` / `resume_subscription` / `cancel_subscription` |
+| **"Listame los cobros recurrentes del último mes"** | `list_subscription_payments` (authorized_payments under a preapproval) |
+| **"Quiero un plan reutilizable de $X/mes"** | `create_subscription_plan` → after, `subscribe_to_plan(plan_id, customer)` per buyer |
+| **"Mostrame los planes que tengo configurados"** | `list_subscription_plans` |
+| **"Cambiá el precio del Plan Pro a $30k"** | `update_subscription_plan(plan_id, amount: 30000)` (existing subscribers keep old price; only NEW signups pay new) |
+| **"Necesito armar un POS para cobrar con QR en mi local"** | `list_stores` → if empty `create_store` → then `create_pos(store_id)` → then `create_qr_payment(external_pos_id)` |
+| **"Mostrame las disputas que tiene este pago"** | `list_payment_disputes(payment_id)` (read-only; surface `dashboard_url` to user) |
+| **"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 |
+| **"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)` |
+| **"Cancelar una orden no capturada"** (v0.5) | `cancel_order` (libera el auth-hold). Si ya capturó, usá `refund_payment`. |
 
 ## The two main "take a payment" patterns
 
@@ -188,10 +202,75 @@ v0.2 ships `parseWebhookEvent()` for the `preapproval` topic (subscription lifec
 - Take raw card data in the agent runtime (PCI scope violation).
 - Bypass MP's first-payment-CVV requirement for subscriptions (impossible).
 - Reactivate a cancelled subscription or payment (MP doesn't allow).
-- Implement Marketplace splits (different MP product, different OAuth flow — out of scope until v0.4+).
 - Pay out the seller (transfers + withdrawals are dashboard-only / closed API).
 - Make decisions about pricing or installments — caller's responsibility.
 
+## 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
+URL and forge state changes. **Always verify.**
+
+The `handle_webhook` tool consolidates the 3-step pattern (verify → parse →
+fetch resource) into ONE call:
+
+```
+result = handle_webhook(raw_body, signature_header, request_id_header, auto_fetch)
+→ { verified, event: { topic, dataId, action }, resource, resource_error }
+```
+
+Behavior:
+- `verified: false` + `error` → reject with HTTP 401, do NOT process. Either signature mismatch, missing webhookSecret, or invalid JSON body.
+- `verified: true` + `resource: <Payment|Preapproval>` → safe to act on. The resource is fetched AS the MP user the client is configured for.
+- `auto_fetch: false` → just verify+parse, skip the GET. Use when you only need to enqueue a job for async processing.
+
+**Per-seller webhooks (marketplace)**: in a marketplace setup, instantiate
+the `MercadoPagoClient` with the SELLER's access_token before calling
+`handle_webhook` so the auto-fetch resolves correctly. Your routing layer
+needs to look up the seller from the webhook payload's `user_id` and pick
+the right client.
+
+## 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.
+
+**Token storage shape** (per seller):
+```
+{
+  user_id: string,           // identifies the seller
+  access_token: string,      // expires in ~6h
+  refresh_token: string,     // long-lived, ROTATES on refresh
+  expires_at: number,        // Date.now() + expires_in*1000
+}
+```
+
+**State for every API call**: instantiate `new MercadoPagoClient({ accessToken: token.access_token })` AS THE SELLER. All subsequent payments / subscriptions / refunds happen on that seller's account.
+
+**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
+
+| When                                    | Use                       |
+| --------------------------------------- | ------------------------- |
+| Simple hosted pay-link (most common)    | `create_payment_preference` |
+| Auth-only flow (capture later)          | `create_order` w/ `capture_mode: "manual"` |
+| Multi-payment-per-order                 | `create_order` |
+| Mix online + in-store with unified status | `create_order` |
+| You need MP's modern Order lifecycle    | `create_order` |
+
+`create_order` returns an Order with explicit lifecycle:
+- `created` → Order opened, no payment yet
+- `processed` → at least one payment attached
+- `action_required` → manual-capture mode, awaits `capture_order`
+- `canceled` → `cancel_order` was called
+- `refunded` → all payments refunded
+
 ## Mercado Pago context (for non-AR agents)
 
 - **Mercado Pago** = dominant Argentine consumer payment platform (also Brazil/Mexico/Chile/Colombia/Uruguay). Owned by Mercado Libre. Like Stripe in scope but with deeper LATAM-specific features (cuotas sin interés, in-store QR, account_money instant transfer).

package/CHANGELOG.md

@@ -1,5 +1,110 @@
 # Changelog
 
+## 0.5.0
+
+### Minor Changes
+
+- MP v0.5: production hardening + marketplace flows. **+9 tools (50 total)**.
+
+  **Webhook handler combo (1 tool)**:
+
+  - `handle_webhook` — verifies HMAC-SHA256 signature, parses the event, and (optionally) auto-fetches the underlying resource (Payment, Subscription) in ONE call. Replaces the manual chain of verify_webhook_signature + parse_webhook_event + get_payment.
+  - `mercadoPagoTools({ webhookSecret })` to enable.
+  - Returns `{ verified, event, resource, resource_error }`. Reject with HTTP 401 when `verified: false`.
+
+  **OAuth Marketplace flow (3 tools + 5 helper functions)**:
+
+  - `oauth_authorize_url` — pure function, builds the URL the seller visits to authorize your marketplace app.
+  - `oauth_exchange_code` — server-side exchange of the OAuth code for an `OAuthToken` (`access_token` + `refresh_token` + `user_id` + `expires_in`).
+  - `oauth_refresh_token` — refresh a per-seller token before it expires (~6h).
+  - Helper functions exported: `buildAuthorizeUrl`, `exchangeCodeForToken`, `refreshAccessToken`, `expirationTimeMs`, `isExpiringSoon`.
+  - `mercadoPagoTools({ oauth: { clientId, clientSecret } })` to enable.
+
+  **Order Management API (5 tools)**:
+
+  - `create_order`, `get_order`, `update_order`, `capture_order`, `cancel_order` — MP's modern Order API. Distinct from Preference: explicit lifecycle, manual-capture support (auth-only flows for ride-share, hotels, marketplaces), multi-payment-per-order semantics.
+  - `capture_mode: "manual"` enables the auth-only flow → `capture_order(id, amount?)` later.
+
+  **Marketplace split payments**:
+
+  - `marketplace`, `marketplace_fee` (in ARS), `collector_id` (seller MP user_id) supported on BOTH `create_order` AND `create_payment_preference`.
+  - Funds route to the seller; `marketplace_fee` is split off to the marketplace's MP account.
+
+  117 tests pass. publint clean. attw all green. 21.6 KB brotli'd (within 32 KB budget).
+
+  The MCP wrapper auto-picks up the new tools — `@ar-agents/mcp` patch bump.
+
+## 0.4.0
+
+### Minor Changes
+
+- v0.4.0 — full toolkit: Subscription Plans + Stores/POS + Disputes + Subscription Payment History + Lookup helpers + Webhooks management
+
+  **41 tools total** (was 24 in v0.3). Adds 17 new tools covering the rest of the agent-relevant MP API surface.
+
+  # New: Subscription Plans (5 tools)
+
+  For SaaS-style billing where you have fixed tiers (Básico/Pro/Enterprise), use plans instead of per-customer preapprovals.
+
+  - `create_subscription_plan` — define reusable plan (price + frequency + optional free trial)
+  - `list_subscription_plans` — list all plans
+  - `update_subscription_plan` — change reason / amount / status / back_url (existing subs keep old amount)
+  - `subscribe_to_plan` — enroll a customer in a plan; returns init_point URL
+  - `list_subscription_payments` — auto-charge attempts (authorized_payments) under a preapproval. Useful for "show me cobros del último mes for this client" or to debug failing recurring charges.
+
+  # New: Stores + POS management (4 tools)
+
+  Self-serve setup for in-store QR payments. Eliminates the previous one-time MP dashboard step.
+
+  - `create_store` — create a store under the seller
+  - `list_stores` — list configured stores
+  - `create_pos` — create a POS under a store (the `external_id` is what `create_qr_payment` uses)
+  - `list_pos` — list POSes (optionally filtered by store_id)
+
+  # New: Disputes / Chargebacks (2 tools, read-only)
+
+  - `list_payment_disputes` — list disputes raised against a payment (surfaces `dashboard_url`)
+  - `get_dispute` — full dispute details (reason, amount, resolution status)
+
+  Resolution remains dashboard-only; the lib surfaces the right URL.
+
+  # New: Lookup helpers (2 tools)
+
+  - `list_identification_types` — AR returns DNI/CI/LE/LC/Otro/Pasaporte/CUIT/CUIL with min/max length
+  - `list_issuers` — banks issuing a card type. Pass `bin` (first 6-8 digits) for precise issuer detection — needed for issuer-specific cuotas promos like Naranja Galicia 6 cuotas sin interés
+
+  # New: Webhooks management (4 tools)
+
+  Programmatically configure webhook subscriptions instead of clicking around the MP dashboard.
+
+  - `list_webhooks` — see what's configured
+  - `create_webhook` — subscribe a URL to a topic (`payment`, `subscription_authorized_payment`, `merchant_order`, `point_integration_wh`, etc.)
+  - `update_webhook` — change URL or topic
+  - `delete_webhook` — unsubscribe
+
+  # Quality
+
+  - 81/81 tests pass (was 61 in v0.3) — added 20 tests for v0.4 endpoints
+  - 21.72 KB ESM brotli'd (under 32 KB budget)
+  - publint + arethetypeswrong all 🟢
+  - Type-safe end-to-end; new types: SubscriptionPlan, Store, Pos, Dispute, IdentificationType, Issuer, WebhookConfig, SubscriptionPayment
+
+  # Cumulative tool inventory (41 total)
+
+  - Subscriptions: 5 (create, get, cancel, pause, resume)
+  - Subscription Plans: 5 (create, list, update, subscribe, list_payments)
+  - Payments: 5 (create, get, search, cancel, capture)
+  - Refunds: 2 (create, list)
+  - Checkout Pro: 2 (create_preference, get_preference)
+  - Customers + Cards: 4 (create, find, list_cards, delete_card)
+  - Saved-card charging: 1 (charge_saved_card)
+  - Methods + Installments: 2 (list_methods, calculate_installments)
+  - Account: 1 (get_account_info)
+  - QR + POS: 6 (create_qr, cancel_qr, create_store, list_stores, create_pos, list_pos)
+  - Disputes: 2 (list, get)
+  - Lookup: 2 (identification_types, issuers)
+  - Webhooks: 4 (list, create, update, delete)
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -18,7 +18,7 @@ Compatible with any caller that uses `tool()`.
 
 | What | Value |
 | --- | --- |
-| Tools shipped | `create_subscription`, `get_subscription_status`, `cancel_subscription`, `pause_subscription`, `resume_subscription` |
+| Tools shipped | **50 tools** — Subscriptions, Payments, Refunds, Checkout Pro, Customers, Saved Cards, Cuotas, QR in-store, Subscription Plans, Stores+POS, Disputes, Lookups, Webhooks management, **handle_webhook combo**, **OAuth Marketplace flow**, **Order Management API** |
 | 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 |
@@ -264,15 +264,20 @@ Methods:
 
 ### `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                                      |
+Returns a `ToolSet` with **50 tools** spanning the full MP API surface an
+agent typically needs. See [AGENTS.md](./AGENTS.md) for the full list with
+selection guidance. Highlights:
+
+- **Subscriptions + Plans** (10 tools): create_subscription, create_subscription_plan, subscribe_to_plan, list_subscription_payments, pause/resume/cancel
+- **Payments + Refunds** (7 tools): create_payment, search_payments, capture_payment, refund_payment, list_refunds…
+- **Checkout Pro** (2 tools): create_payment_preference, get_payment_preference
+- **Customers + Saved Cards** (4 tools): create_customer, find_customer_by_email, list_customer_cards, charge_saved_card (CVV-required)
+- **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
 
 Options:
 
@@ -281,9 +286,68 @@ mercadoPagoTools(client, {
   state: SubscriptionStateAdapter;       // required
   backUrl: string;                        // required, must be HTTPS
   descriptions?: Partial<Record<ToolName, string>>; // optional override
+  webhookSecret?: string;                 // for handle_webhook (HMAC verify)
+  oauth?: { clientId, clientSecret };     // for OAuth marketplace flow
 });
 ```
 
+### v0.5 — Webhook handler combo
+
+```ts
+// In your /api/mercadopago/webhook handler
+const result = await tools.handle_webhook.execute({
+  raw_body: await req.text(),
+  signature_header: req.headers.get("x-signature"),
+  request_id_header: req.headers.get("x-request-id"),
+  auto_fetch: true, // also fetches the Payment / Subscription
+}, ctx);
+
+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)
+
+```ts
+// 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
+}, ctx);
+
+// 2. On redirect, exchange the code (server-side, secret required)
+const { token } = await tools.oauth_exchange_code.execute({
+  code: req.query.code,
+  redirect_uri: "https://app.test/oauth/callback",
+}, ctx);
+// Persist { token.user_id, token.access_token, token.refresh_token, token.expires_in }
+
+// 3. Refresh proactively (or reactively on 401)
+const { token } = await tools.oauth_refresh_token.execute({
+  refresh_token: savedRefreshToken,
+}, ctx);
+
+// Then operate AS the seller:
+const sellerClient = new MercadoPagoClient({ accessToken: token.access_token });
+```
+
+### 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
+`create_order` (or `create_payment_preference`). Funds route to the seller's
+MP account; `marketplace_fee` (in ARS) goes to your marketplace account.
+
+```ts
+await tools.create_order.execute({
+  type: "online",
+  total_amount: 10_000,
+  marketplace: "MyApp",
+  marketplace_fee: 500,            // ARS (NOT %)
+  collector_id: token.user_id,     // seller MP user_id from OAuth
+}, ctx);
+```
+
 ### Errors
 
 All errors extend `MercadoPagoError` which carries `status`, `endpoint`,