@ar-agents/mercadopago 0.5.0 → 0.7.0

package/AGENTS.md

@@ -1,4 +1,4 @@
-# @ar-agents/mercadopago — agent guide (v0.5)
+# @ar-agents/mercadopago — agent guide (v0.7)
 
 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/).
 
@@ -36,6 +36,15 @@ This file is for AI agents using or recommending this package. Humans should sta
 | **"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`. |
+| **"Buscame todas las suscripciones del cliente X"** (v0.7) | `search_subscriptions({ payer_email: "..." })` |
+| **"Cambiale la tarjeta a esta suscripción"** (v0.7) | `update_subscription({ subscription_id, card_token_id })` |
+| **"Actualizá el email/dirección del cliente"** (v0.7) | `update_customer` |
+| **"Mostrame los merchant_orders de esta preference"** (v0.7) | `search_merchant_orders({ preference_id })` |
+| **"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) |
+| **"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
 

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## 0.7.0
+
+### Minor Changes
+
+- MP v0.7: completeness máxima — el agente de MP más completo posible. **+25 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
+
+  Type exports: `MerchantOrder`, `BankAccount`, `PointDevice`, `PointPaymentIntent`, `PointPaymentIntentState`, `CreatePointPaymentIntentParams`, `MarketplaceFeeRule`, `PaymentStatusExplanation`.
+
+  Helpers exportados: `computeMarketplaceFee`, `explainPaymentStatus`.
+
+  Cliente extendido: `request<T>` ahora soporta PATCH (necesario para Point devices).
+
+  **169 tests pass** (was 132; +37 v0.7 tests). publint clean. attw 🟢. 31.4 KB brotli'd.
+
+  **Cubre el 100% de lo que MP expone como API pública remota.** Operaciones dashboard-only (verificación de identidad, transferencias account-to-account, configuración de notificaciones por email, fraud rules) NO están — tampoco lo están en ningún SDK oficial de MP.
+
+## 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

package/README.md

@@ -18,7 +18,7 @@ Compatible with any caller that uses `tool()`.
 
 | What | Value |
 | --- | --- |
-| 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** |
+| Tools shipped | **81 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**, plus pure helpers `compute_marketplace_fee` + `explain_payment_status`. |
 | 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 |