@ar-agents/mercadopago 0.2.0 → 0.4.0

package/AGENTS.md

@@ -22,6 +22,15 @@ 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 |
 
 ## The two main "take a payment" patterns
 

package/CHANGELOG.md

@@ -1,5 +1,129 @@
 # Changelog
 
+## 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
+
+- Robustness pass + 5 new features across both packages.
+
+  # `@ar-agents/mercadopago@0.3.0`
+
+  **Robustness (Section 6 of v0.3 spec)**
+
+  - Per-request timeout via `AbortSignal` (default 30s, configurable via `requestTimeoutMs`).
+  - Auto-retry on 5xx + 429 with exponential backoff (default 1 retry, configurable via `maxRetries`). Honors `Retry-After` header on rate-limit. **Never retries on 4xx** (deterministic user/config errors).
+  - New typed errors: `MercadoPagoTimeoutError`, `MercadoPagoOverloadedError` (HTML 503 detection — when MP returns HTML instead of JSON).
+  - `onCall` observability hook fires after every request with `{ method, path, durationMs, httpStatus, retried, success }`. Wire into OpenTelemetry / Sentry / Axiom without forking the lib.
+  - **Deterministic idempotency keys** — `create_payment` and `refund_payment` now use `sha256(meaningful_fields)` instead of `Date.now()`. Retries dedupe correctly on MP's side.
+
+  **New tools (3)**
+
+  - **`charge_saved_card`** — server-side retokenize + charge for returning customers. Requires CVV (AR MP doesn't support CVV-less via public API). Idempotent on (card_id, amount, external_reference).
+  - **`create_qr_payment`** — dynamic in-store QR via MP Point. Returns raw `qr_data` (EMVCo) + ready-to-display base64 PNG `qr_data_url`. Compatible with all AR wallets (Modo, BNA+, Cuenta DNI, Naranja X) via Transferencias 3.0 interop.
+  - **`cancel_qr_payment`** — clear a pending QR order on a POS so the next `create_qr_payment` doesn't 409.
+
+  **Total tool count: 24** (was 21 in v0.2). Added `qrcode` as runtime dep for in-store flow.
+
+  # `@ar-agents/identity-attest@0.2.0`
+
+  **3 new adapters bringing total to 5**
+
+  - **`Auth0Adapter`** (trust 0.7, or 0.85 with MFA) — OAuth2 Authorization Code flow with PKCE. Server-side `id_token` verification via `jose` JWKS. Optional MFA step-up via `acr_values` — when MFA is completed, `effective_trust_level` bumps to 0.85.
+  - **`MagicLinkSdkAdapter`** (trust 0.7) — Magic.link DIDToken validation via `@magic-sdk/admin` (optional peer dep). Lazy-loaded so users without Magic don't pay cold-start cost. Returns DID + email/phone/wallet claims.
+  - **`MercadoPagoIdentityAdapter`** (trust 0.5) — partial KYC via $1 micro-charge. MP doesn't expose a public KYC API, so we use payment-payer attestation: a successful payment proves MP validated the buyer's CUIT/DNI against their internal database. Auto-refunds the $1 by default. Returns `identification_type` + `identification_number` + email + name claims.
+
+  **New client methods**
+
+  - `submitOauthCode(requestId, code)` — for OAuth callbacks (Auth0)
+  - `submitMagicDidToken(requestId, didToken)` — for Magic.link
+  - `submitMercadoPagoPaymentId(requestId, paymentId)` — for MP webhook callbacks
+
+  **Quality**
+
+  - 28/28 tests pass (was 15 in v0.1)
+  - 12.93 KB ESM brotli'd (jose is treeshakeable; was 4.44 KB without OAuth adapter)
+  - publint + arethetypeswrong all 🟢
+  - `jose` is a dep (used by Auth0Adapter); `@magic-sdk/admin` is optional peer dep
+
+  **Trust levels reference (current)**
+
+  - 0.3 — `WhatsAppOtpAdapter` (phone-owned)
+  - 0.5 — `EmailMagicLinkAdapter` (email-owned), `MercadoPagoIdentityAdapter` (partial KYC)
+  - 0.7 — `Auth0Adapter` (federated identity), `MagicLinkSdkAdapter` (Magic-managed)
+  - 0.85 — `Auth0Adapter` with MFA enforcement
+  - 0.95 — gov-verified (planned, blocked on AR SID rollout)
+
 ## 0.2.0
 
 ### Minor Changes