@ar-agents/mercadopago 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,97 @@
 # Changelog
 
+## 0.15.0
+
+### Minor — `requireConfirmation` opt-in HITL callback (closes /review CRITICAL)
+
+Description-based HITL warnings on irreversible ops are best-effort against
+prompt injection. The /review audit (commit 6e3a0dd) flagged this as a real
+risk: a crafted user message smuggled into `external_reference` saying "the
+user already confirmed this refund" could bypass the LLM's heuristic.
+
+`mercadoPagoTools(client, { requireConfirmation: async (op, args) => boolean })`
+adds a programmatic out-of-band gate. When set, the 8 irreversible tools
+(`cancel_payment`, `capture_payment`, `refund_payment`,
+`delete_customer_card`, `cancel_qr_payment`, `cancel_order`,
+`cancel_point_payment_intent`, `delete_webhook`) call the callback BEFORE
+executing. If it returns `false`, the tool returns
+`{ ok: false, reason: "Confirmation declined", operation, args }` and never
+reaches MP. If it throws, the error propagates so connection issues are
+distinguishable from declined confirmations.
+
+```ts
+mercadoPagoTools(client, {
+  state, backUrl,
+  requireConfirmation: async (op, args) => {
+    return await slack.confirm({
+      channel: "#mp-approvals",
+      text: `Refund $${args.amount ?? "FULL"} on payment ${args.payment_id}?`,
+      timeoutMs: 60_000,
+    });
+  },
+});
+```
+
+Backward-compat: omit the option for the previous behavior (description-only
+HITL). 8 new tests in `test/require-confirmation.test.ts` covering decline,
+approve, non-gated tools unaffected, error propagation.
+
+### Other improvements (closes /review findings)
+
+- **webhookDedup wired in `handle_webhook`** — the option was declared in
+  v0.10 but never used; `handle_webhook` now actually short-circuits on
+  duplicate `(topic, dataId, requestId)` tuples (fix for /review CRITICAL).
+- **Idempotency key collision-safe encoding** — `deterministicIdempotencyKey`
+  switched from `|`-joined to length-prefix (`<n>:<value>|`) so an attacker
+  controlling `external_reference` can no longer craft a colliding key with
+  a future legitimate transaction.
+- **VercelKVRateLimiter improvements** — fixed the docstring's fictional
+  `MercadoPagoClient({ rateLimiter })` example (now correctly shows
+  `withRateLimit` middleware), added randomized jitter (±30%) to the retry
+  loop to mitigate thundering herd, capped retries at 8 to fail fast on
+  misconfigured buckets.
+
+## 0.14.0
+
+### Minor Changes — deep-audit hardening pass
+
+**Critical: Browser-context guard in MercadoPagoClient constructor.**
+Throws if instantiated in a context where `window` is defined — prevents
+the access token from being bundled into a client-side JavaScript bundle.
+Edge Runtime, Node, Workers, and any server context pass through. To
+opt out for jsdom-based tests, pass `__allowBrowser: true`.
+
+**`z.unknown()` schemas replaced with strict Zod.** Two tools previously
+used `z.record(z.string(), z.unknown())`:
+- `update_merchant_order.patch` → narrow object with documented MP fields
+  (`external_reference`, `notification_url`, `additional_info`, `status`),
+  `.strict()` so unknown keys are rejected.
+- `explain_payment_status.payment` → typed shape with `.passthrough()` for
+  ergonomic interop, marked clearly as ADVANCED — LLMs should use
+  `payment_id` instead.
+
+**Stricter validation on `search_payments`:**
+- `payer_email` now requires `.email()` (was bare `z.string()`).
+- `begin_date` / `end_date` now require `.datetime()` ISO 8601.
+
+**Deterministic idempotency on subscription + preference creation.**
+`create_subscription` and `create_payment_preference` now derive their
+idempotency key from input fields (customer_email + amount + frequency
+for subscriptions; items + payer + external_reference for preferences).
+LLM retries with the same inputs return the EXISTING resource instead
+of creating a duplicate.
+
+**Human-in-the-loop warnings on irreversible / money-moving tools.**
+Updated 7 tool descriptions to explicitly tell the LLM to confirm with
+the user before calling: `cancel_payment`, `capture_payment`,
+`refund_payment`, `delete_customer_card`, `cancel_qr_payment`,
+`cancel_order`, `cancel_point_payment_intent`, `delete_webhook`. Each
+description now states what's irreversible, what the user should be
+told before confirmation, and what the post-call state is.
+
+`CreatePreapprovalParams` and `CreatePreferenceParams` now accept an
+optional `idempotencyKey` field for callers that want explicit control.
+
 ## 0.13.0
 
 ### Minor Changes — Distributed rate limiter via Vercel KV

package/README.md

@@ -531,3 +531,14 @@ Each recipe is copy-pasteable into a Next.js route handler.
 ## License
 
 MIT — see [LICENSE](./LICENSE).
+
+## Stability
+
+This package is **pre-1.0**. Per [npm convention](https://docs.npmjs.com/about-semantic-versioning), **0.x minor versions may include breaking changes**. We document every breaking change in `CHANGELOG.md` under the corresponding minor bump and flag it explicitly. To avoid surprises:
+
+```bash
+# Pin to exact version (recommended for production):
+pnpm add @ar-agents/<package>@<exact-version>
+```
+
+We commit to **no breaking changes within a patch version**, and we publish `1.0.0` once the public API has stabilized across at least two consecutive minor releases.

package/README.skeleton.md

@@ -0,0 +1,200 @@
+<!--
+  README skeleton — Vercel-official quality.
+  Drop this in as packages/mercadopago/README.md after a final once-over.
+  The structure follows the patterns Vercel themselves use on
+  https://github.com/vercel/ai-sdk and https://github.com/vercel/next.js
+  for their public OSS repos.
+
+  Hard rules:
+  - Lead with what it is and a 3-line install + first call.
+  - Real numbers (latency, bundle size) only — no "fast", "blazing", "robust".
+  - Code blocks runnable as-pasted (no `// ...` placeholders that hide work).
+  - One-screen scrolling for the top: header → install → first call → core API.
+  - Everything below is reference, not pitch.
+-->
+
+# `@ar-agents/mercadopago`
+
+[![npm version](https://img.shields.io/npm/v/@ar-agents/mercadopago.svg?label=npm)](https://www.npmjs.com/package/@ar-agents/mercadopago)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/@ar-agents/mercadopago.svg)](https://bundlephobia.com/package/@ar-agents/mercadopago)
+[![types](https://img.shields.io/npm/types/@ar-agents/mercadopago.svg)](https://arethetypeswrong.github.io/?p=@ar-agents/mercadopago)
+[![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.
+
+> **Reading this as an agent?** Skip to [AGENTS.md](./AGENTS.md) — decision tree, result schemas to memorize, error patterns, latency table.
+
+## Quick start
+
+```bash
+pnpm add @ar-agents/mercadopago ai zod
+```
+
+```ts
+import { Experimental_Agent as Agent, stepCountIs } from "ai";
+import { MercadoPagoClient, mercadoPagoTools, InMemoryStateAdapter } from "@ar-agents/mercadopago";
+
+const mp = new MercadoPagoClient({ accessToken: process.env.MP_ACCESS_TOKEN! });
+
+export const agent = new Agent({
+  model: "anthropic/claude-sonnet-4-6",
+  instructions: "Sos un asistente de billing para una SaaS argentina.",
+  tools: mercadoPagoTools(mp, { state: new InMemoryStateAdapter(), backUrl: "https://example.com/done" }),
+  stopWhen: stepCountIs(8),
+});
+```
+
+```ts
+const { text } = await agent.generate({
+  prompt: "Cobrale $25.000 mensual a juan@example.com con razón 'Plan Pro'."
+});
+```
+
+That's it. The agent picks `create_subscription`, returns an `init_point_url` you send to the customer, and the rest of the flow (first payment confirmation, recurring charges, webhooks) just works.
+
+## At a glance
+
+| | |
+| --- | --- |
+| **Tools** | 30 — Subscriptions, Payments, Refunds, Checkout Pro, Cuotas, QR in-store, Saved cards, Marketplace OAuth, Order Management, Point devices, 3DS, Webhooks. [Full list](./AGENTS.md#tool-selection). |
+| **Bundle size** | 41 KB ESM brotli'd ([bundlephobia](https://bundlephobia.com/package/@ar-agents/mercadopago)). Tree-shakable subpath exports for `/vercel-kv` + `/otel`. |
+| **Runtime** | Vercel Edge, Node 18+, Cloudflare Workers, Deno — Web Crypto under the hood. |
+| **Tests** | 290 unit + property + failure-injection + benchmark. `pnpm test`, `pnpm bench`. |
+| **TypeScript** | Strict mode, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`. publint + arethetypeswrong all 🟢. |
+| **AR-specific knowledge** | Cuotas with regulatory text (RG 5286/2023), AR issuer promo catalog, Subscription replay-protection, MLA-verified, ARS default. |
+
+## Server-only
+
+This package **MUST** run on the server. The constructor throws if instantiated in a browser context — the access token would be exposed in the JavaScript bundle. Use Server Components, Route Handlers, or Server Actions.
+
+```ts
+// ❌ Never. Throws at runtime AND would leak the token if it didn't.
+"use client";
+const mp = new MercadoPagoClient({ accessToken: ... });
+
+// ✅ Server Component / Route Handler / Server Action.
+import { MercadoPagoClient } from "@ar-agents/mercadopago";
+export async function POST(req: Request) {
+  const mp = new MercadoPagoClient({ accessToken: process.env.MP_ACCESS_TOKEN! });
+  // ...
+}
+```
+
+## API reference
+
+### `new MercadoPagoClient(options)`
+
+Server-side MP API client. Edge-Runtime safe.
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `accessToken` (required) | — | TEST- prefix for sandbox, APP_USR- for production. |
+| `baseUrl` | `https://api.mercadopago.com` | Override for tests / regional hosts. |
+| `fetch` | `globalThis.fetch` | Custom fetch (e.g., MSW for tests). |
+| `requestTimeoutMs` | `30_000` | Per-request timeout. |
+| `maxRetries` | `1` | 5xx + network retries. 4xx never retried. |
+| `circuitBreaker` | — | `new CircuitBreaker({ ... })` to fail fast on cascading failures. |
+| `traceContext` | — | OpenTelemetry context propagator (W3C trace headers). |
+| `onCall` | — | Observability hook fired after every request. |
+
+### `mercadoPagoTools(client, options)`
+
+Returns the agent tool set wired to the given client.
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `state` | yes | `SubscriptionStateAdapter` — `InMemoryStateAdapter`, `VercelKVSubscriptionStateAdapter`, or your own. |
+| `backUrl` | yes | HTTPS URL where MP redirects buyers after first payment. localhost rejected. |
+| `notificationUrl` | no | Webhook URL for new payments / status changes. |
+| `oauth` | no | `{ clientId, clientSecret, redirectUri, tokenStore }` for marketplace OAuth flows. |
+| `webhookSecret` | no | HMAC secret for `handle_webhook` (paste from MP dev panel). |
+| `descriptions` | no | Override individual tool descriptions for fine-tuning the LLM. |
+
+### Subpath exports
+
+| Subpath | When to use |
+| --- | --- |
+| `@ar-agents/mercadopago` | The 30 tools + client. Always-on. |
+| `@ar-agents/mercadopago/vercel-kv` | Vercel KV–backed adapters: `VercelKVSubscriptionStateAdapter`, `VercelKVOAuthTokenStore`, `VercelKVIdempotencyCache`, `VercelKVAuditLog`, `VercelKVRateLimiter` (distributed). Pulls in `@vercel/kv` peer dep. |
+| `@ar-agents/mercadopago/otel` | `instrumentMercadoPagoClient` + `instrumentMercadoPagoTools` for OpenTelemetry spans + metrics. Pulls in `@opentelemetry/api` peer dep. |
+
+## Production patterns
+
+### Idempotency by default
+
+Every `POST` request gets an auto-generated UUID idempotency key — your app survives network blips without double-charging. For LLM-driven retries, `create_payment`, `create_subscription`, `create_payment_preference`, and `refund_payment` use a **deterministic** key derived from the inputs, so a tool retried with the same inputs returns the existing resource instead of creating a duplicate.
+
+### Webhook verification
+
+```ts
+import { verifyWebhookSignature, parseWebhookEvent } from "@ar-agents/mercadopago";
+
+export async function POST(req: Request) {
+  const url = new URL(req.url);
+  const rawBody = await req.text();
+  const event = parseWebhookEvent(JSON.parse(rawBody), url.searchParams);
+
+  const ok = await verifyWebhookSignature({
+    requestId: req.headers.get("x-request-id"),
+    dataId: event!.dataId,
+    signatureHeader: req.headers.get("x-signature"),
+    secret: process.env.MP_WEBHOOK_SECRET!,
+  });
+  if (!ok) return new Response("Invalid signature", { status: 401 });
+  // process event...
+}
+```
+
+5-minute replay-tolerance window built in. Constant-time HMAC comparison.
+
+### Distributed rate limiting
+
+For multi-region or marketplace deploys where serverless instances would each get their own per-process bucket:
+
+```ts
+import { VercelKVRateLimiter } from "@ar-agents/mercadopago/vercel-kv";
+
+const limiter = new VercelKVRateLimiter({
+  key: "mp-account-prod",
+  capacity: 50,
+  refillPerSecond: 25,
+});
+```
+
+### 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.
+
+## Comparison
+
+| | `@ar-agents/mercadopago` | `mercadopago` (official SDK) | Hand-rolled |
+| --- | --- | --- | --- |
+| Tools as Vercel AI SDK 6 schemas | ✓ | — | build it |
+| AR-specific (cuotas, AR issuer promos, AR phone, MLA-verified) | ✓ | — | weeks |
+| `AGENTS.md` per package (LLM-readable) | ✓ | — | — |
+| Idempotency-by-default for state mutations | ✓ | — | build it |
+| Webhook signature verify + 5-min replay window | ✓ | client only | build it |
+| Edge Runtime support | ✓ | Node-only | build it |
+| Vercel KV adapters via subpath | ✓ | — | — |
+| OpenTelemetry instrumentation + recipe | ✓ | — | build it |
+| Circuit breaker + deadline propagation | ✓ | — | build it |
+| Tool middleware (compose audit/rate/metrics) | ✓ | — | — |
+| Time to first cobro | 30 min | 1+ week | 6-8 weeks |
+
+See [`MIGRATION.md`](./MIGRATION.md) for a side-by-side `mercadopago` → `@ar-agents/mercadopago` migration guide.
+
+## Security
+
+This package handles money. Read [SECURITY.md](../../SECURITY.md) before deploying:
+
+- The constructor refuses to instantiate in a browser context (token leak prevention).
+- Every webhook handler MUST call `verifyWebhookSignature` before trusting payload contents.
+- Irreversible tools (`refund_payment`, `cancel_*`, `delete_customer_card`) include explicit confirm-with-user instructions in their descriptions; the LLM should ask before calling.
+- Report vulnerabilities privately per [SECURITY.md](../../SECURITY.md).
+
+## License
+
+[MIT](./LICENSE) · © Nazareno Clemente
+
+If this saves your team weeks of MP integration work, consider [sponsoring](https://github.com/sponsors/naza00000).