@ar-agents/mercadopago 0.7.0 → 0.8.0

package/cookbook/08-recovery-patterns.ts

@@ -0,0 +1,191 @@
+/**
+ * Recipe 08 — Recovery patterns: retry, recover stuck payments, handle expirations.
+ *
+ * # Common stuck states and how to recover
+ *
+ * 1. **Subscription card expired → recurring charge rejected**
+ *    Recover by: capture fresh card token from buyer + `update_subscription({ card_token_id })`
+ *
+ * 2. **Payment stuck in `pending_challenge` (3DS not completed)**
+ *    Recover by: redirect buyer back to the challenge URL via
+ *    `analyze_payment_3ds(payment_id).challengeUrl`
+ *
+ * 3. **Payment in `pending_review_manual` (MP fraud team review)**
+ *    Recover by: WAIT — MP processes within 24-72h. Don't retry.
+ *
+ * 4. **Subscription auto-cancelled because first payment failed**
+ *    Recover by: create a fresh subscription (the original is dead, MP doesn't
+ *    let you "reactivate" — that's documented in `MercadoPagoPaymentRejectedError`).
+ *
+ * 5. **`pending_waiting_payment` for cash methods (Rapipago, Pago Fácil)**
+ *    Recover by: NOTHING — the buyer must complete payment within the
+ *    timeout (typically 3-5 days). Polling or push-webhooks notify when done.
+ *
+ * 6. **Webhook arrived but payment not in your DB**
+ *    Recover by: idempotent upsert via `searchPayments({ external_reference })`
+ *    instead of trusting the webhook payload alone.
+ */
+
+import {
+  classifyError,
+  explainPaymentStatus,
+  MercadoPagoClient,
+  MercadoPagoPaymentRejectedError,
+  type PaymentStatusExplanation,
+} from "@ar-agents/mercadopago";
+
+const mp = new MercadoPagoClient({
+  accessToken: process.env.MP_ACCESS_TOKEN!,
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pattern 1 — Subscription card swap on rejection
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function recoverFromCardRejection(input: {
+  subscriptionId: string;
+  buyerWhatsAppNumber: string;
+}) {
+  const sub = await mp.getPreapproval(input.subscriptionId);
+  if (sub.status !== "paused" && sub.status !== "cancelled") {
+    return { ok: true, action: "none" };
+  }
+
+  // Send buyer a link to update their card via MP frontend SDK
+  const updateUrl = `https://yourapp.com/billing/update-card?sub=${input.subscriptionId}`;
+  // ... send via WhatsApp with the toolkit's whatsappTools ...
+
+  return {
+    ok: false,
+    action: "card_swap_required",
+    sentTo: input.buyerWhatsAppNumber,
+    updateUrl,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pattern 2 — Recover stuck-pending payment with status explanation
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function inspectStuckPayment(paymentId: string): Promise<{
+  paymentId: string;
+  status: string;
+  explanation: PaymentStatusExplanation;
+  nextAction: string;
+}> {
+  const payment = await mp.getPayment(paymentId);
+  const explanation = explainPaymentStatus(payment);
+
+  let nextAction = explanation.recommendedAction;
+  if (explanation.retryable) {
+    nextAction = `Reintentar con otra tarjeta. Razón: ${explanation.summary}`;
+  } else if (!explanation.final) {
+    nextAction = `Esperar webhook (${explanation.summary}). Sin acción de tu parte.`;
+  } else if (explanation.paid) {
+    nextAction = `Acreditado. Continuar con flujo posterior.`;
+  }
+
+  return {
+    paymentId,
+    status: payment.status as string,
+    explanation,
+    nextAction,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pattern 3 — Idempotent upsert via search (don't trust webhook payload alone)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function reconcilePaymentByExternalRef(externalReference: string) {
+  // Search MP for ALL payments under this external_reference. There may be
+  // multiple if the buyer retried.
+  const result = await mp.searchPayments({ external_reference: externalReference });
+
+  // Find the latest approved one (winning attempt)
+  const approved = result.results
+    ?.filter((p) => p.status === "approved")
+    .sort((a, b) => (b.date_created ?? "").localeCompare(a.date_created ?? ""))[0];
+
+  if (approved) {
+    return { found: true, paymentId: approved.id, amount: approved.transaction_amount };
+  }
+
+  // No approved payment — find the latest attempt (could be pending or rejected)
+  const latest = result.results
+    ?.sort((a, b) => (b.date_created ?? "").localeCompare(a.date_created ?? ""))[0];
+
+  return { found: false, lastAttempt: latest };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pattern 4 — Handle MercadoPagoPaymentRejectedError explicitly
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function chargeWithRetry(input: {
+  cardId: string;
+  customerId: string;
+  amountArs: number;
+  cvv: string;
+  externalReference: string;
+}): Promise<
+  { ok: true; paymentId: string } | { ok: false; reason: string; recoverable: boolean }
+> {
+  try {
+    const payment = await mp.chargeSavedCard({
+      cardId: input.cardId,
+      customerId: input.customerId,
+      transactionAmount: input.amountArs,
+      securityCode: input.cvv,
+      payerEmail: "—", // populated server-side from customer
+      description: "Recurring charge",
+      externalReference: input.externalReference,
+    });
+    return { ok: true, paymentId: payment.id };
+  } catch (err) {
+    if (err instanceof MercadoPagoPaymentRejectedError) {
+      // The lib's MercadoPagoPaymentRejectedError carries status_detail —
+      // use it to drive recovery.
+      const detail = (err as MercadoPagoPaymentRejectedError & { statusDetail?: string }).statusDetail;
+      const recoverable =
+        detail === "cc_rejected_call_for_authorize" ||
+        detail === "cc_rejected_insufficient_amount" ||
+        detail === "cc_rejected_bad_filled_security_code";
+      return { ok: false, reason: detail ?? "rejected", recoverable };
+    }
+    const classified = classifyError(err);
+    throw classified; // Re-throw for ops/observability
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pattern 5 — Cron-driven monitoring (Vercel Cron Job)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Hypothetical Vercel Cron Job (`vercel.json`):
+ * ```json
+ * { "crons": [{ "path": "/api/cron/mp-monitor", "schedule": "0 *\/4 * * *" }] }
+ * ```
+ *
+ * Runs every 4 hours; surfaces:
+ * - Subscriptions that haven't auto-charged in >35 days (probably broken)
+ * - Stuck-pending payments older than 24h (need investigation)
+ * - Disputes opened in the last 24h (need response)
+ */
+export async function cronMonitorMpHealth() {
+  const since = new Date(Date.now() - 24 * 3600 * 1000).toISOString();
+  const stuck = await mp.searchPayments({
+    status: "pending",
+    range: "date_created",
+    begin_date: since.slice(0, 10),
+  } as never);
+
+  // Surface to ops via Slack/email/Sentry
+  const stuckCount = stuck.results?.length ?? 0;
+  if (stuckCount > 5) {
+    // alertOps(...)
+  }
+
+  return { stuckCount };
+}

package/cookbook/README.md

@@ -0,0 +1,36 @@
+# Cookbook — `@ar-agents/mercadopago`
+
+Real, copy-pasteable recipes for the most common MP integration flows. Every
+recipe is a self-contained Next.js route handler or agent loop you can
+deploy on Vercel as-is.
+
+## Recipes
+
+| #   | File                              | Pattern                                                                 |
+| --- | --------------------------------- | ----------------------------------------------------------------------- |
+| 01  | `01-checkout-pro-basic.ts`        | First-time hosted-checkout sale (Checkout Pro preference + back URLs)   |
+| 02  | `02-saas-subscription.ts`         | Reusable plan + subscription with first-payment + card swap on failure  |
+| 03  | `03-webhook-handler.ts`           | Vercel route handler with HMAC verify + auto-fetch + dispatch by topic  |
+| 04  | `04-marketplace-split.ts`         | OAuth seller link → preference with `marketplace_fee` → reconciliation  |
+| 05  | `05-qr-in-store.ts`               | Create POS → generate QR → poll status → notify buyer via WhatsApp      |
+| 06  | `06-3ds-challenge.ts`             | Detect challenge → redirect buyer → recover via webhook                 |
+| 07  | `07-auth-only-order.ts`           | `Order` with manual capture → capture later when service completes      |
+| 08  | `08-recovery-patterns.ts`         | Retry expired subscriptions, recover stuck-pending payments, etc.       |
+
+## Conventions
+
+- All recipes assume `MP_ACCESS_TOKEN` is set (TEST- prefix in sandbox).
+- All recipes show the agent path AND the manual-client path side by side
+  where relevant.
+- Recipes that need state use `VercelKVSubscriptionStateAdapter` —
+  swap for `InMemoryStateAdapter` in tests.
+- Recipes that need OAuth credentials assume `MP_CLIENT_ID` + `MP_CLIENT_SECRET`.
+- Recipes that need webhook secrets assume `MP_WEBHOOK_SECRET`.
+- All `Edge Runtime` compatible (Web Crypto only — no `node:crypto`).
+
+## Deploying as Vercel functions
+
+Each recipe is a standalone TypeScript file you can drop into
+`apps/your-app/src/app/api/mp/{route}.ts` (App Router) or
+`apps/your-app/pages/api/mp/{route}.ts` (Pages Router). Add `export const runtime = "edge"` if
+you want Edge Runtime; the toolkit is fully Edge-compatible.

package/dist/index.cjs

@@ -1,6 +1,5 @@
 'use strict';
 
-var crypto = require('crypto');
 var ai = require('ai');
 var zod = require('zod');
 
@@ -1235,6 +1234,54 @@ var MercadoPagoClient = class {
     return { id: intentId, canceled: true };
   }
 };
+
+// src/crypto.ts
+var subtle = (() => {
+  const c = globalThis.crypto;
+  if (!c?.subtle) {
+    throw new Error(
+      "@ar-agents/mercadopago: Web Crypto API is not available in this runtime. Use Node 18+, Vercel Edge Runtime, Cloudflare Workers, or any modern browser."
+    );
+  }
+  return c.subtle;
+})();
+var encoder = new TextEncoder();
+async function hmacSha256Hex(secret, message) {
+  const keyMaterial = await subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sigBuf = await subtle.sign(
+    "HMAC",
+    keyMaterial,
+    encoder.encode(message)
+  );
+  return bufferToHex(sigBuf);
+}
+async function sha256Hex(input) {
+  const digest = await subtle.digest("SHA-256", encoder.encode(input));
+  return bufferToHex(digest);
+}
+function timingSafeEqualHex(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+function bufferToHex(buf) {
+  const bytes = new Uint8Array(buf);
+  let hex = "";
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i];
+    hex += (b < 16 ? "0" : "") + b.toString(16);
+  }
+  return hex;
+}
 zod.z.enum(["MLA", "MLB", "MLM", "MCO", "MLC", "MLU"]);
 var CurrencyIdSchema = zod.z.enum(["ARS", "USD", "BRL", "MXN"]);
 var FrequencyTypeSchema = zod.z.enum(["months", "days"]);
@@ -2102,6 +2149,8 @@ function analyze3DS(payment) {
     description: "No se pudo determinar el estado 3DS \u2014 revisar payment.three_d_secure_mode + payment.status_detail manualmente."
   };
 }
+
+// src/webhook.ts
 function parseWebhookEvent(body, searchParams) {
   const parseResult = WebhookBodySchema.safeParse(body ?? {});
   const parsedBody = parseResult.success ? parseResult.data : {};
@@ -2117,7 +2166,8 @@ function parseWebhookEvent(body, searchParams) {
     raw: parsedBody
   };
 }
-function verifyWebhookSignature(params) {
+var DEFAULT_REPLAY_TOLERANCE_SECONDS = 300;
+async function verifyWebhookSignature(params) {
   if (!params.signatureHeader || !params.requestId) return false;
   const parts = Object.fromEntries(
     params.signatureHeader.split(",").map((segment) => segment.trim().split("="))
@@ -2125,16 +2175,20 @@ function verifyWebhookSignature(params) {
   const ts = parts.ts;
   const v1 = parts.v1;
   if (!ts || !v1) return false;
+  const tolerance = params.replayToleranceSeconds ?? DEFAULT_REPLAY_TOLERANCE_SECONDS;
+  const tsNumber = Number(ts);
+  if (!Number.isFinite(tsNumber)) return false;
+  const ageSeconds = Math.abs(Math.floor(Date.now() / 1e3) - tsNumber);
+  if (ageSeconds > tolerance) return false;
   const manifest = `id:${params.dataId};request-id:${params.requestId};ts:${ts};`;
-  const expected = crypto.createHmac("sha256", params.secret).update(manifest).digest("hex");
-  if (expected.length !== v1.length) return false;
-  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
+  const expected = await hmacSha256Hex(params.secret, manifest);
+  return timingSafeEqualHex(expected, v1);
 }
 
 // src/tools.ts
-function deterministicIdempotencyKey(...parts) {
+async function deterministicIdempotencyKey(...parts) {
   const payload = parts.filter((p) => p !== void 0 && p !== null).map(String).join("|");
-  return crypto.createHash("sha256").update(payload).digest("hex").slice(0, 32);
+  return (await sha256Hex(payload)).slice(0, 32);
 }
 var DEFAULT_DESCRIPTIONS = {
   // ── Subscriptions ────────────────────────────────────────────────────────
@@ -2390,7 +2444,7 @@ function mercadoPagoTools(client, options) {
           ...options.notificationUrl !== void 0 ? { notificationUrl: options.notificationUrl } : {},
           // Deterministic idempotency key — safe to retry, same inputs always
           // produce the same key (MP dedupes on its side).
-          idempotencyKey: deterministicIdempotencyKey(
+          idempotencyKey: await deterministicIdempotencyKey(
             "create_payment",
             input.external_reference ?? input.payer_email,
             input.amount_ars,
@@ -2513,7 +2567,7 @@ function mercadoPagoTools(client, options) {
         const refund = await client.createRefund({
           paymentId: payment_id,
           ...amount_ars !== void 0 ? { amount: amount_ars } : {},
-          idempotencyKey: deterministicIdempotencyKey("refund", payment_id, amount_ars ?? "full")
+          idempotencyKey: await deterministicIdempotencyKey("refund", payment_id, amount_ars ?? "full")
         });
         return {
           refund_id: refund.id,
@@ -2779,7 +2833,7 @@ function mercadoPagoTools(client, options) {
           ...input.installments !== void 0 ? { installments: input.installments } : {},
           ...input.external_reference !== void 0 ? { externalReference: input.external_reference } : {},
           ...input.statement_descriptor !== void 0 ? { statementDescriptor: input.statement_descriptor } : {},
-          idempotencyKey: deterministicIdempotencyKey(
+          idempotencyKey: await deterministicIdempotencyKey(
             "charge_saved_card",
             input.card_id,
             input.amount_ars,
@@ -3290,7 +3344,7 @@ function mercadoPagoTools(client, options) {
             resource: null
           };
         }
-        const verified = verifyWebhookSignature({
+        const verified = await verifyWebhookSignature({
           requestId: request_id_header,
           dataId: event.dataId,
           signatureHeader: signature_header,
@@ -3488,7 +3542,7 @@ function mercadoPagoTools(client, options) {
         if (input.marketplace_fee !== void 0) params.marketplace_fee = input.marketplace_fee;
         if (input.collector_id !== void 0) params.collector_id = input.collector_id;
         const order = await client.createOrder(params, {
-          idempotencyKey: deterministicIdempotencyKey(
+          idempotencyKey: await deterministicIdempotencyKey(
             "create_order",
             input.external_reference,
             input.total_amount,
@@ -4052,7 +4106,50 @@ var InMemoryStateAdapter = class {
     this.store.clear();
   }
 };
+var InMemoryOAuthTokenStore = class {
+  store = /* @__PURE__ */ new Map();
+  async set(userId, token) {
+    this.store.set(userId, token);
+  }
+  async get(userId) {
+    return this.store.get(userId) ?? null;
+  }
+  async delete(userId) {
+    this.store.delete(userId);
+  }
+  async list() {
+    return Array.from(this.store.keys());
+  }
+  /** Test helper. */
+  reset() {
+    this.store.clear();
+  }
+};
+var InMemoryIdempotencyCache = class {
+  store = /* @__PURE__ */ new Map();
+  async get(key) {
+    const entry = this.store.get(key);
+    if (!entry) return null;
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      return null;
+    }
+    return entry.value;
+  }
+  async set(key, value, ttlSeconds = 86400) {
+    this.store.set(key, { value, expiresAt: Date.now() + ttlSeconds * 1e3 });
+  }
+  async delete(key) {
+    this.store.delete(key);
+  }
+  /** Test helper. */
+  reset() {
+    this.store.clear();
+  }
+};
 
+exports.InMemoryIdempotencyCache = InMemoryIdempotencyCache;
+exports.InMemoryOAuthTokenStore = InMemoryOAuthTokenStore;
 exports.InMemoryStateAdapter = InMemoryStateAdapter;
 exports.MercadoPagoAccountTypeMismatchError = MercadoPagoAccountTypeMismatchError;
 exports.MercadoPagoAuthError = MercadoPagoAuthError;