@ar-agents/mercadopago 0.4.0 → 0.6.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/).
 
@@ -31,6 +31,11 @@ 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 |
+| **"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
 
@@ -197,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,64 @@
 # Changelog
 
+## 0.6.0
+
+### Minor Changes
+
+- MP v0.6: account/balance + settlements + 3DS analyzer + test cards. **+6 tools (56 total)**.
+
+  **Account / Balance / Settlements (4 tools)**:
+
+  - `get_account_balance` — current MP wallet `{ available, unavailable, total, currency_id }`. Per-seller in marketplace setups.
+  - `list_account_movements({ from?, to?, limit?, offset? })` — wallet movement log (incoming payments, refunds, holdings, transfers).
+  - `list_settlements({ from?, to?, status? })` — `release_money` transfers from MP wallet → registered CBU.
+  - `get_settlement(id)` — single settlement detail with bank_account info.
+
+  **3DS analyzer (1 tool + 1 helper)**:
+
+  - `analyze_payment_3ds(payment_id)` — fetches the Payment, derives `{ status: 'not_required'|'frictionless'|'challenge_required'|'rejected'|'unknown', mode, challengeUrl, description }`. When `challengeUrl !== null`, MUST redirect the buyer to complete authentication.
+  - `analyze3DS(payment)` exported as a pure helper for callers who already have a Payment object.
+
+  **Test cards (1 tool + helpers)**:
+
+  - `get_test_cards` — returns the official AR (MLA) sandbox cards: VISA/Mastercard/Amex credit + debit. Each has the "magic" holder names that route to specific status_detail (APRO, OTHE, CONT, FUND, CALL, SECU, EXPI, FORM).
+  - `TEST_CARDS_AR`, `TEST_PAYERS_AR`, `buildTestCardScenario(card, scenario, amount)` exported for direct use in test files.
+
+  **132 tests pass** (was 117; +15 v0.6 tests). publint clean. attw 🟢. 24.3 KB brotli'd (within 32 KB budget).
+
+## 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

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`,