@ar-agents/mercadopago 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 0.8.0
+
+### Minor Changes — Edge Runtime + Vercel KV + Cookbook
+
+**Edge Runtime support (was: Node-only)**
+
+- Replaced `node:crypto` with the universal Web Crypto API across all crypto helpers.
+- The toolkit now runs in **Vercel Edge Runtime, Cloudflare Workers, Deno, browsers, and Node 18+** with zero changes.
+- New module `./crypto` exposes `hmacSha256Hex`, `sha256Hex`, `timingSafeEqualHex`.
+
+**Webhook signature verify is now async + replay-attack protected**
+
+- `verifyWebhookSignature(...)` returns `Promise<boolean>` (was `boolean`). All call sites in `handle_webhook` tool already awaited.
+- New default 5-minute replay window: signatures with `ts` more than `replayToleranceSeconds` (default 300) old are rejected as replay attempts.
+- Override the window per-call with the new `replayToleranceSeconds` option.
+- **Breaking**: callers using the exported `verifyWebhookSignature` directly need to add `await`.
+
+**Vercel KV adapters via subpath `@ar-agents/mercadopago/vercel-kv`**
+
+- `VercelKVSubscriptionStateAdapter` — drop-in `SubscriptionStateAdapter` backed by Vercel KV (Upstash Redis).
+- `VercelKVOAuthTokenStore` — persists per-seller OAuth tokens for marketplace flows. Key namespace `mp:oauth:{userId}`.
+- `VercelKVIdempotencyCache` — TTL-aware cache for short-circuiting agent retries.
+- `@vercel/kv` is an **optional** peer dependency — only consumers who use the subpath install it. Main bundle untouched.
+- All three adapters work in Edge Runtime.
+
+**New state adapter interfaces in main package**
+
+- `OAuthTokenStore` + `InMemoryOAuthTokenStore` — token bundle persistence for marketplace OAuth.
+- `IdempotencyCache` + `InMemoryIdempotencyCache` — agent-retry deduplication layer on top of MP's server-side dedup.
+
+**Cookbook (8 recipes)**
+
+- `cookbook/01-checkout-pro-basic.ts` — first-time hosted checkout
+- `cookbook/02-saas-subscription.ts` — reusable plan + first payment + card swap on rejection
+- `cookbook/03-webhook-handler.ts` — production-grade Edge handler with HMAC verify
+- `cookbook/04-marketplace-split.ts` — OAuth seller link → preference with fee → reconciliation
+- `cookbook/05-qr-in-store.ts` — QR generation → buyer scan → WhatsApp notify
+- `cookbook/06-3ds-challenge.ts` — detect → redirect → recover via webhook
+- `cookbook/07-auth-only-order.ts` — Order with manual capture (ride-share / hotel pattern)
+- `cookbook/08-recovery-patterns.ts` — recover stuck-pending, card-swap on rejected sub, idempotent upsert via search, cron-driven monitoring
+
+**Quality**
+
+- 185 tests pass (was 169; +16 for KV adapters + 2 for replay protection).
+- publint clean, attw all 🟢 across both subpaths.
+- Bundle: main 31.9 KB brotli'd; vercel-kv subpath 0.6 KB brotli'd.
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -25,6 +25,9 @@ Compatible with any caller that uses `tool()`.
 | Side effects | `create_subscription` creates a preapproval. `cancel`/`pause`/`resume` mutate state. `get_status` is read-only. |
 | Agent safety | `cancel_subscription` description triggers confirm-before-call in Claude Sonnet 4.6+ |
 | Sites supported | MLA (Argentina) verified end-to-end. Other LATAM sites should work but aren't exercised by tests. |
+| Runtime | **Edge Runtime + Node 18+** — Web Crypto under the hood, no `node:crypto`. Drops into Vercel Edge Functions, Cloudflare Workers, Deno deploy, or any modern Node. |
+| Vercel-native | First-class adapters for **Vercel KV** (subscription state, OAuth tokens, idempotency cache) via `@ar-agents/mercadopago/vercel-kv` subpath. |
+| Cookbook | 8 production-grade recipes shipped in `cookbook/` — checkout, subscriptions, webhook handler, marketplace OAuth, QR in-store, 3DS challenge, auth-only Order, recovery patterns. |
 
 ## Why this exists
 
@@ -361,11 +364,70 @@ and `mpResponse` for inspection. Specific subclasses:
 - `MercadoPagoAuthorizeForbiddenError` — see gotcha #6
 - `MercadoPagoRateLimitError` — 429 from MP
 
+## Vercel-native (v0.8+)
+
+The toolkit ships first-class adapters for Vercel infrastructure via the
+`@ar-agents/mercadopago/vercel-kv` subpath. `@vercel/kv` is an **optional**
+peer dep — only install it if you use the subpath.
+
+```ts
+import { mercadoPagoTools, MercadoPagoClient } from "@ar-agents/mercadopago";
+import {
+  VercelKVSubscriptionStateAdapter,
+  VercelKVOAuthTokenStore,
+  VercelKVIdempotencyCache,
+} from "@ar-agents/mercadopago/vercel-kv";
+
+const tools = mercadoPagoTools(
+  new MercadoPagoClient({ accessToken: process.env.MP_ACCESS_TOKEN! }),
+  {
+    state: new VercelKVSubscriptionStateAdapter(),
+    backUrl: "https://yourapp.com/done",
+    webhookSecret: process.env.MP_WEBHOOK_SECRET,
+    oauth: {
+      clientId: process.env.MP_CLIENT_ID!,
+      clientSecret: process.env.MP_CLIENT_SECRET!,
+    },
+  },
+);
+```
+
+### Edge Runtime
+
+The toolkit (including HMAC webhook verification) is fully Edge-Runtime
+compatible. Add `export const runtime = "edge"` to any Vercel route handler
+that uses MP tools — sub-100ms global cold starts.
+
+### Vercel Cron + Blob + Functions
+
+See `cookbook/08-recovery-patterns.ts` for a Vercel Cron Job example that
+monitors stuck-pending payments. For label/invoice PDF storage, the
+`crear_envio` tool (in `@ar-agents/shipping`) returns label URLs you can
+mirror to [Vercel Blob](https://vercel.com/docs/storage/vercel-blob).
+
+## Cookbook
+
+Production-grade recipes shipped in [`cookbook/`](./cookbook):
+
+| Recipe | What it shows |
+|---|---|
+| `01-checkout-pro-basic.ts` | First-time hosted checkout sale via the agent |
+| `02-saas-subscription.ts` | Reusable plan + first payment + card swap on rejection |
+| `03-webhook-handler.ts` | Edge Runtime webhook handler with HMAC verify + dispatch |
+| `04-marketplace-split.ts` | OAuth seller link + preference with `marketplace_fee` + reconciliation |
+| `05-qr-in-store.ts` | QR generation → buyer scan → cashier WhatsApp notify |
+| `06-3ds-challenge.ts` | Detect → redirect to challenge → recover via webhook |
+| `07-auth-only-order.ts` | Order with `capture_mode: "manual"` (ride-share / hotel pattern) |
+| `08-recovery-patterns.ts` | Card swap on subscription, stuck-pending recovery, idempotent upsert via search, Vercel Cron monitoring |
+
+Each recipe is copy-pasteable into a Next.js route handler.
+
 ## Compatibility
 
-- Node.js 20+
+- **Node.js 18+** (Web Crypto required) or **Vercel Edge Runtime** / **Cloudflare Workers** / **Deno**
 - Vercel AI SDK 6+
 - Zod 3+
+- Optional: `@vercel/kv >=2` for the `vercel-kv` subpath
 - Pairs cleanly with [Vercel AI Gateway](https://vercel.com/ai-gateway) for model routing.
 
 ## License

package/cookbook/01-checkout-pro-basic.ts

@@ -0,0 +1,99 @@
+/**
+ * Recipe 01 — First-time Checkout Pro sale via an agent.
+ *
+ * # Pattern
+ *
+ * 1. Agent receives the user's intent ("comprar 3 unidades a $X")
+ * 2. Agent calls `create_payment_preference` to get a hosted checkout URL
+ * 3. Agent surfaces the `init_point_url` to the user (or sends via WhatsApp)
+ * 4. The buyer completes payment on MP's hosted form (no PCI scope for you)
+ * 5. MP fires a `payment` webhook to your endpoint (see recipe 03)
+ *
+ * # When to use
+ *
+ * - Single one-off purchase (not recurring → use recipe 02 for that)
+ * - You only have a payer email; no card token from MP frontend SDK
+ * - You want PCI-out-of-scope (buyer enters card data on MP's form)
+ *
+ * # Edge Runtime
+ *
+ * Fully Edge-compatible. Uncomment `export const runtime = "edge"` to deploy
+ * as a Vercel Edge Function for sub-100ms global cold starts.
+ */
+
+import { Experimental_Agent as Agent, stepCountIs } from "ai";
+import {
+  InMemoryStateAdapter,
+  MercadoPagoClient,
+  mercadoPagoTools,
+} from "@ar-agents/mercadopago";
+
+// export const runtime = "edge"; // Uncomment for Edge deployment
+
+const mp = new MercadoPagoClient({
+  accessToken: process.env.MP_ACCESS_TOKEN!,
+  // Production robustez defaults: 30s timeout, 1 retry on 5xx, exponential backoff
+  requestTimeoutMs: 30_000,
+  maxRetries: 1,
+});
+
+const agent = new Agent({
+  model: "anthropic/claude-sonnet-4-6",
+  instructions: `Sos el asistente de checkout de un e-commerce argentino.
+Cuando el cliente quiere comprar:
+1. Confirmá el monto y la descripción del producto.
+2. Llamá a create_payment_preference con back_urls de éxito/error.
+3. Devolvele el init_point_url (Checkout Pro) al cliente.
+4. NO pidas datos de tarjeta — los cargan en MP.`,
+  tools: mercadoPagoTools(mp, {
+    state: new InMemoryStateAdapter(),
+    backUrl: "https://yourapp.com/payment-result",
+    notificationUrl: "https://yourapp.com/api/mp/webhook",
+  }),
+  stopWhen: stepCountIs(5),
+});
+
+// In a Next.js route handler:
+export async function POST(req: Request) {
+  const { prompt } = (await req.json()) as { prompt: string };
+  const result = await agent.generate({ prompt });
+  return Response.json({ text: result.text });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Manual / non-agent path (for direct API use)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function createCheckoutPreference(input: {
+  customerEmail: string;
+  productTitle: string;
+  unitPriceArs: number;
+  quantity: number;
+  externalReference: string;
+}) {
+  const preference = await mp.createPreference({
+    items: [
+      {
+        title: input.productTitle,
+        quantity: input.quantity,
+        unit_price: input.unitPriceArs,
+        currency_id: "ARS",
+      },
+    ],
+    payer: { email: input.customerEmail },
+    backUrls: {
+      success: "https://yourapp.com/payment-success",
+      failure: "https://yourapp.com/payment-failure",
+      pending: "https://yourapp.com/payment-pending",
+    },
+    autoReturn: "approved",
+    externalReference: input.externalReference,
+    notificationUrl: "https://yourapp.com/api/mp/webhook",
+  });
+
+  return {
+    preferenceId: preference.id,
+    initPoint: preference.init_point,
+    sandboxInitPoint: preference.sandbox_init_point, // Use this in TEST mode
+  };
+}

package/cookbook/02-saas-subscription.ts

@@ -0,0 +1,137 @@
+/**
+ * Recipe 02 — SaaS subscription with reusable plan + first payment + card swap.
+ *
+ * # Pattern
+ *
+ * **One-time setup**: create a `Plan` (price + frequency) — re-use across customers.
+ *
+ * **Per-customer**:
+ * 1. `subscribe_to_plan` → returns init_point for first-payment authorization
+ * 2. Buyer pays first installment with card+CVV (MP requirement, can't bypass)
+ * 3. `subscription_preapproval` webhook fires → status flips to `authorized`
+ * 4. MP auto-charges at the configured frequency thereafter
+ *
+ * **Card swap on failure** (when buyer's card expires):
+ * - You receive a `subscription_authorized_payment` webhook with rejection
+ * - Generate a fresh card token via MP frontend SDK on the buyer's side
+ * - Call `update_subscription({ card_token_id })` to swap without recreating
+ *
+ * # When to use
+ *
+ * - Monthly/quarterly SaaS billing (Básico/Pro/Enterprise tiers)
+ * - You want one Plan definition shared across all subscribers
+ * - You need the option to update price for new subscribers without
+ *   touching existing ones
+ */
+
+import {
+  InMemoryStateAdapter,
+  MercadoPagoClient,
+} from "@ar-agents/mercadopago";
+
+const mp = new MercadoPagoClient({
+  accessToken: process.env.MP_ACCESS_TOKEN!,
+});
+
+const state = new InMemoryStateAdapter();
+// In production, swap for VercelKVSubscriptionStateAdapter:
+// import { VercelKVSubscriptionStateAdapter } from "@ar-agents/mercadopago/vercel-kv";
+// const state = new VercelKVSubscriptionStateAdapter();
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 1 — One-time setup: create the plan
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function createPlanProMonthly() {
+  const plan = await mp.createSubscriptionPlan({
+    reason: "Plan Pro mensual",
+    backUrl: "https://yourapp.com/subscription-result",
+    frequency: 1,
+    frequencyType: "months",
+    amount: 25_000,
+    currency: "ARS",
+  });
+  return plan; // persist plan.id in your DB
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 2 — Per-customer: subscribe to the plan
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function subscribeUserToProPlan(input: {
+  planId: string;
+  customerEmail: string;
+  externalReference: string; // your-system user id
+}) {
+  const sub = await mp.subscribeToPlan({
+    planId: input.planId,
+    payerEmail: input.customerEmail,
+    externalReference: input.externalReference,
+  });
+
+  // Persist locally for fast lookups + webhook routing
+  await state.set(sub.id, {
+    payerEmail: input.customerEmail,
+    initPoint: sub.init_point,
+    externalReference: input.externalReference,
+    createdAt: new Date().toISOString(),
+    status: sub.status,
+  });
+
+  return {
+    subscriptionId: sub.id,
+    initPoint: sub.init_point,
+    nextStep:
+      "Send init_point to the customer. They must complete the first payment with card+CVV. Listen for subscription_preapproval webhook to confirm activation.",
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 3 — Webhook: subscription_preapproval activation
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function handlePreapprovalWebhook(subscriptionId: string) {
+  const sub = await mp.getPreapproval(subscriptionId);
+  await state.set(sub.id, {
+    status: sub.status,
+    lastWebhookStatus: sub.status,
+    lastWebhookAt: new Date().toISOString(),
+  });
+  if (sub.status === "authorized") {
+    // First payment cleared — provision the user's plan in your DB
+    // await db.users.update({ where: { externalReference: sub.external_reference }, data: { plan: "pro", status: "active" } });
+  }
+  return sub;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 4 — Card swap (when buyer's card is rejected on a recurring charge)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function swapCardOnSubscription(input: {
+  subscriptionId: string;
+  newCardToken: string; // from MP frontend SDK / Cardform on buyer's side
+}) {
+  const sub = await mp.updatePreapproval(input.subscriptionId, {
+    card_token_id: input.newCardToken,
+  });
+  await state.set(sub.id, {
+    status: sub.status,
+    lastWebhookStatus: "card_swapped",
+    lastWebhookAt: new Date().toISOString(),
+  });
+  return sub;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 5 — Cancel
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function cancelSubscription(subscriptionId: string) {
+  const sub = await mp.cancelPreapproval(subscriptionId);
+  await state.set(sub.id, {
+    status: sub.status,
+    cancelledAt: new Date().toISOString(),
+  });
+  return sub;
+}

package/cookbook/03-webhook-handler.ts

@@ -0,0 +1,162 @@
+/**
+ * Recipe 03 — Production-grade webhook handler.
+ *
+ * # The 3-line summary
+ *
+ * - Verify HMAC-SHA256 signature → reject with 401 if invalid (replay protection included)
+ * - Parse the event (topic + dataId) from query/body (MP sends in both)
+ * - Auto-fetch the underlying resource (Payment / Preapproval / Order)
+ * - Dispatch by topic to your business logic
+ *
+ * Without HMAC verify, ANYONE can POST to your webhook URL and forge
+ * payments/cancellations. The lib's `verifyWebhookSignature` rejects
+ * stale signatures (>5min old) too — replay attack protection.
+ *
+ * # Why use the agent's `handle_webhook` tool vs calling primitives manually
+ *
+ * The tool consolidates verify + parse + auto-fetch + dispatch into one
+ * call. Saves ~30 lines per webhook handler vs the manual chain.
+ *
+ * # Edge Runtime
+ *
+ * This recipe is fully Edge-compatible. Webhook handlers benefit from Edge
+ * (lower cold-start = faster MP-acked, fewer 500s during traffic spikes).
+ */
+
+import {
+  MercadoPagoClient,
+  parseWebhookEvent,
+  verifyWebhookSignature,
+} from "@ar-agents/mercadopago";
+
+export const runtime = "edge";
+
+const mp = new MercadoPagoClient({
+  accessToken: process.env.MP_ACCESS_TOKEN!,
+});
+
+const WEBHOOK_SECRET = process.env.MP_WEBHOOK_SECRET!;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Approach A — Manual primitives (more control, more code)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function POST(req: Request) {
+  // 1. Read the RAW body — DO NOT use req.json() before HMAC verify, as
+  //    JSON.stringify changes whitespace and breaks the signature.
+  const rawBody = await req.text();
+
+  const signatureHeader = req.headers.get("x-signature");
+  const requestId = req.headers.get("x-request-id");
+  const url = new URL(req.url);
+
+  // 2. Parse the event from body or query (MP sends in both).
+  let parsedBody: unknown;
+  try {
+    parsedBody = JSON.parse(rawBody);
+  } catch {
+    return new Response("invalid JSON", { status: 400 });
+  }
+  const event = parseWebhookEvent(parsedBody, url.searchParams);
+  if (!event) {
+    return new Response("unrecognized webhook shape", { status: 400 });
+  }
+
+  // 3. Verify HMAC + replay-tolerance window.
+  const verified = await verifyWebhookSignature({
+    requestId,
+    dataId: event.dataId,
+    signatureHeader,
+    secret: WEBHOOK_SECRET,
+  });
+  if (!verified) {
+    return new Response("unauthorized", { status: 401 });
+  }
+
+  // 4. Dispatch by topic.
+  try {
+    switch (event.topic) {
+      case "payment":
+      case "payment.created":
+      case "payment.updated": {
+        const payment = await mp.getPayment(event.dataId);
+        await handlePayment(payment);
+        break;
+      }
+      case "subscription_preapproval":
+      case "preapproval": {
+        const sub = await mp.getPreapproval(event.dataId);
+        await handleSubscription(sub);
+        break;
+      }
+      case "subscription_authorized_payment": {
+        // The dataId IS the authorized_payment id — list under parent
+        // preapproval to get full context.
+        await handleRecurringCharge(event.dataId);
+        break;
+      }
+      case "merchant_order": {
+        const mo = await mp.getMerchantOrder(event.dataId);
+        await handleMerchantOrder(mo);
+        break;
+      }
+      case "point_integration_wh": {
+        const intent = await mp.getPointPaymentIntent(event.dataId);
+        await handlePointPaymentIntent(intent);
+        break;
+      }
+      default:
+        // Unknown topic — log and acknowledge so MP doesn't retry forever.
+        console.warn(`Unhandled webhook topic: ${event.topic}`);
+    }
+  } catch (err) {
+    // Return 5xx so MP retries (it has built-in exponential backoff).
+    console.error("webhook handler failed:", err);
+    return new Response("internal error", { status: 500 });
+  }
+
+  return new Response("ok", { status: 200 });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Approach B — Agent tool (let the agent dispatch)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Alternative: pass everything to an agent + the `handle_webhook` tool.
+ * Useful when your business logic varies by webhook content and an LLM
+ * makes the decision (e.g., "if this payment is for an old SKU, refund it").
+ *
+ * Note: this is HIGHER LATENCY than approach A and uses LLM tokens. Only
+ * use when LLM reasoning is genuinely required.
+ */
+// export async function POST_via_agent(req: Request) {
+//   const rawBody = await req.text();
+//   const result = await agent.generate({
+//     prompt: `Procesá este webhook de MP. Topic + body:\n${rawBody}`,
+//     toolChoice: "required",
+//     tools: mercadoPagoTools(mp, {
+//       state, backUrl, webhookSecret: WEBHOOK_SECRET, oauth: {...}
+//     }),
+//   });
+// }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Business logic stubs
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function handlePayment(payment: unknown) {
+  // Update your DB, fire shipping flow, send notification, etc.
+}
+async function handleSubscription(sub: unknown) {
+  /* ... */
+}
+async function handleRecurringCharge(authorizedPaymentId: string) {
+  /* ... */
+}
+async function handleMerchantOrder(mo: unknown) {
+  /* ... */
+}
+async function handlePointPaymentIntent(intent: unknown) {
+  /* ... */
+}