@ar-agents/mercadopago 0.15.3 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## 0.17.0
+
+### Minor Changes
+
+- Add `mercadopago doctor` CLI for environment diagnosis.
+
+  ```bash
+  npx @ar-agents/mercadopago doctor
+  pnpm exec mercadopago doctor
+  ```
+
+  Reports:
+
+  - Node version (must be ≥ 20)
+  - `MP_ACCESS_TOKEN` presence + format + sandbox/prod prefix detection
+  - Live token validation against `GET /users/me` (free, no charge)
+  - `NEXT_PUBLIC_BACK_URL` presence + HTTPS check (MP rejects localhost server-side)
+  - `MP_WEBHOOK_SECRET` presence + length sanity
+  - Peer-dependency installation: `ai`, `zod`, `@vercel/kv`, `@opentelemetry/api`
+  - Tool count grouped by inferred category (auto-derived from `tools.manifest.json`)
+  - The 8 irreversible ops gated by `requireConfirmation()`
+
+  Pass `--probe` to additionally dry-call `validate_tax_id` against your sandbox token (also free):
+
+  ```bash
+  npx @ar-agents/mercadopago doctor --probe
+  ```
+
+  Exit codes follow the convention: `0` = ok or warn-only, `1` = at least one fail. CI scripts can `npx @ar-agents/mercadopago doctor` to gate deploys on having credentials wired up.
+
+  Also exposes `mercadopago help` and `mercadopago version`. Output respects `NO_COLOR`.
+
+  10 new subprocess tests (test/cli.test.ts), 328 tests total.
+
+## 0.16.0
+
+### Minor Changes
+
+- Add `@ar-agents/mercadopago/testing` subpath: factories + a mock client for tests.
+
+  What ships:
+
+  - **Factories**: `mockPayment`, `mockPreapproval`, `mockSubscriptionPayment`, `mockPreference`, `mockRefund`, `mockCustomer`. Each takes a partial overrides object so test setup is one line.
+  - **`MockMercadoPagoClient`**: in-memory client with the most-common create/get/cancel/refund paths. Read-only methods that don't fit a clean store model throw `MockNotImplementedError` to nudge users toward MSW or a real sandbox token rather than silently growing the mock.
+  - **`mockSignedWebhook`**: produces a `{ headers, searchParams, body }` triple whose `x-signature` header is a real HMAC-SHA256 against the secret you pass. Drops directly into `verifyWebhookSignature` — test the full webhook stack without hand-rolling the signature manifest.
+
+  Subpath was chosen over the main entry to keep the production bundle clean (the testing helpers are dev-only).
+
+  ```ts
+  import {
+    MockMercadoPagoClient,
+    mockPayment,
+    mockSignedWebhook,
+  } from "@ar-agents/mercadopago/testing";
+  ```
+
+  15 new unit tests (testing-subpath.test.ts), still 100% passing.
+
 ## 0.15.3
 
 ### Patch Changes

package/README.md

@@ -13,6 +13,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/@ar-agents/mercadopago.svg)](https://www.npmjs.com/package/@ar-agents/mercadopago)
 [![license](https://img.shields.io/npm/l/@ar-agents/mercadopago.svg)](./LICENSE)
 [![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)
+[![npm provenance](https://img.shields.io/badge/npm%20provenance-SLSA%20v1-7C3AED?logo=npm)](https://docs.npmjs.com/generating-provenance-statements)
 [![bundle size](https://img.shields.io/bundlephobia/minzip/@ar-agents/mercadopago.svg)](https://bundlephobia.com/package/@ar-agents/mercadopago)
 
 Wraps the Mercado Pago API as a typed tool collection for AI agents. Built for
@@ -94,6 +95,14 @@ console.log(result.text);
 //    https://www.mercadopago.com.ar/subscriptions/checkout?preapproval_id=..."
 ```
 
+## Diagnose your setup
+
+```bash
+npx @ar-agents/mercadopago doctor
+```
+
+Validates `MP_ACCESS_TOKEN` against the live API, checks peer deps, lists all 89 tools, surfaces the 8 irreversible operations gated by `requireConfirmation`, and warns on common misconfigurations (missing `NEXT_PUBLIC_BACK_URL`, non-HTTPS back URL, suspiciously short webhook secret, trailing-newline tokens). Pass `--probe` to also dry-call `validate_tax_id` against your sandbox. CI-friendly exit codes (`0` ok, `1` fail).
+
 ## Webhooks
 
 MP notifies your endpoint whenever a subscription's status changes. The

package/bin/mercadopago.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Thin shim: import the bundled CLI and forward argv. Compiled output lives
+// at dist/cli.js. Keeping this file small means we don't have to rebuild it
+// when CLI logic changes — only the bundle changes.
+import { runCli } from "../dist/cli.js";
+
+runCli(process.argv).then(
+  (code) => process.exit(code),
+  (err) => {
+    console.error(err);
+    process.exit(1);
+  },
+);

package/cookbook/10-cross-package-billing.ts

@@ -0,0 +1,172 @@
+/**
+ * Recipe 10 — Cross-package billing assistant.
+ *
+ * The killer demo of the @ar-agents/* toolkit's composability. ONE agent loop,
+ * five packages working together to do what would normally be 200 lines of
+ * orchestration code:
+ *
+ *   1. @ar-agents/identity         — validate the buyer's CUIT, look up
+ *                                    AFIP padron (monotributo + IVA condition)
+ *   2. @ar-agents/identity-attest  — gate large charges behind WhatsApp OTP
+ *   3. @ar-agents/mercadopago      — run the actual subscription / payment
+ *   4. @ar-agents/facturacion      — emit factura electrónica WSFE on success
+ *   5. @ar-agents/whatsapp         — send confirmation + invoice link
+ *
+ * Real production pattern: invoice an Argentine SMB customer, fully driven
+ * by an LLM agent reading natural-language business prompts.
+ *
+ * Run with `pnpm tsx cookbook/10-cross-package-billing.ts` after wiring env:
+ *   MP_ACCESS_TOKEN
+ *   AFIP_CERT_PEM, AFIP_KEY_PEM, AFIP_CUIT
+ *   WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_NUMBER_ID
+ *   ATTESTATION_HMAC_SECRET
+ */
+
+import { Experimental_Agent as Agent, stepCountIs, type ToolSet } from "ai";
+
+// 1. Mercado Pago — always present, the headline package.
+import {
+  MercadoPagoClient,
+  mercadoPagoTools,
+  InMemoryStateAdapter,
+} from "@ar-agents/mercadopago";
+
+// 2-5. Sidecar packages. Imported up-front because every cross-package agent
+//      will eventually need them; tree-shaking handles unused ones.
+import {
+  identityTools,
+  WsaaWscdcAfipPadronAdapter,
+  UnconfiguredAfipPadronAdapter,
+  type AfipPadronAdapter,
+} from "@ar-agents/identity";
+import {
+  AttestationClient,
+  identityAttestTools,
+  InMemoryAttestationStore,
+} from "@ar-agents/identity-attest";
+import {
+  WsfeClient,
+  facturacionTools,
+} from "@ar-agents/facturacion";
+import {
+  WhatsAppClient,
+  whatsappTools,
+} from "@ar-agents/whatsapp";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Build the cross-package tool surface
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function buildBillingAgent() {
+  const tools: ToolSet = {};
+
+  // ── Mercado Pago ──────────────────────────────────────────────────────────
+  const mp = new MercadoPagoClient({
+    accessToken: process.env.MP_ACCESS_TOKEN!,
+  });
+  Object.assign(
+    tools,
+    mercadoPagoTools(mp, {
+      state: new InMemoryStateAdapter(),
+      backUrl: process.env.NEXT_PUBLIC_BACK_URL ?? "https://example.com/done",
+      // HITL on irreversible ops. In production: push approval request to a
+      // dashboard / Slack / email and block on user UI. For the demo: auto-OK.
+      requireConfirmation: async (toolName, params) => {
+        console.log(`[HITL] ${toolName} called with`, params);
+        return true;
+      },
+    }),
+  );
+
+  // ── Identity (CUIT + AFIP/ARCA padron) ────────────────────────────────────
+  // Wire the real WSAA adapter only when the cert is present; otherwise the
+  // unconfigured adapter is registered so `validate_cuit` works (algorithm
+  // only) but `lookup_padron` returns "not configured" cleanly.
+  const afipAdapter: AfipPadronAdapter =
+    process.env.AFIP_CERT_PEM && process.env.AFIP_KEY_PEM
+      ? new WsaaWscdcAfipPadronAdapter({
+          certPem: process.env.AFIP_CERT_PEM,
+          keyPem: process.env.AFIP_KEY_PEM,
+          cuitRepresentado: process.env.AFIP_CUIT!,
+          env: "prod",
+        })
+      : new UnconfiguredAfipPadronAdapter();
+  Object.assign(tools, identityTools({ afip: afipAdapter }));
+
+  // ── Identity-attest (WhatsApp OTP gate for >$50k) ─────────────────────────
+  if (process.env.ATTESTATION_HMAC_SECRET) {
+    const attestClient = new AttestationClient({
+      hmacSecret: process.env.ATTESTATION_HMAC_SECRET,
+      store: new InMemoryAttestationStore(),
+    });
+    Object.assign(tools, identityAttestTools(attestClient));
+  }
+
+  // ── Facturación (factura electrónica WSFE) ────────────────────────────────
+  if (process.env.AFIP_CERT_PEM && process.env.AFIP_KEY_PEM) {
+    const wsfe = new WsfeClient({
+      certPem: process.env.AFIP_CERT_PEM,
+      keyPem: process.env.AFIP_KEY_PEM,
+      cuit: Number(process.env.AFIP_CUIT!),
+      env: "prod",
+    });
+    Object.assign(tools, facturacionTools({ wsfe }));
+  }
+
+  // ── WhatsApp (confirmation + invoice link) ────────────────────────────────
+  if (process.env.WHATSAPP_ACCESS_TOKEN && process.env.WHATSAPP_PHONE_NUMBER_ID) {
+    const wa = new WhatsAppClient({
+      accessToken: process.env.WHATSAPP_ACCESS_TOKEN,
+      phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID,
+    });
+    Object.assign(tools, whatsappTools({ client: wa }));
+  }
+
+  return new Agent({
+    model: "anthropic/claude-sonnet-4-6",
+    instructions:
+      "Sos un asistente de billing para SaaS argentinas. Antes de cobrar, " +
+      "validás el CUIT con `validate_cuit` y consultás el padrón AFIP con " +
+      "`lookup_padron` para conocer la condición IVA del receptor. Para " +
+      "cargos sobre $50.000 ARS, gatillás verificación WhatsApp OTP via " +
+      "`request_attestation`. Después del cobro emitís factura electrónica " +
+      "con `crear_factura` (B si es Consumidor Final, A si es Responsable " +
+      "Inscripto, C si tu emisor es monotributo). Mandás link del " +
+      "comprobante por WhatsApp con `send_text`. Respondé en castellano " +
+      "rioplatense, breve, sin emojis.",
+    tools,
+    stopWhen: stepCountIs(15), // higher than usual — multi-package flows take steps
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Example invocation
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const agent = await buildBillingAgent();
+
+  // What the agent should do behind this prompt:
+  //   1. validate_cuit("20-12345678-9") → ok
+  //   2. lookup_padron("20-12345678-9") → returns "Acme SRL, monotributo Cat A, Responsable Inscripto"
+  //   3. amount > $50k → request_attestation(method="whatsapp_otp", target="+5491155555555")
+  //   4. (after OTP confirmed) create_subscription({ amount: 75000, frequency: "monthly", payerEmail })
+  //   5. (async, after first payment webhook) crear_factura(B, monto, items)
+  //   6. send_text(phone, "Suscripción activa. Factura: $url")
+  const result = await agent.generate({
+    prompt:
+      "Cobrale $75.000 mensual a Acme SRL (CUIT 20-12345678-9, " +
+      "email contacto@acme.example, WhatsApp +5491155555555) por el plan Pro. " +
+      "Como supera los $50k, gatillá la verificación primero. Después emití " +
+      "factura B y mandales el link por WhatsApp.",
+  });
+
+  console.log(result.text);
+}
+
+if (process.argv[1]?.endsWith("10-cross-package-billing.ts")) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/cookbook/11-dunning-sequence.ts

@@ -0,0 +1,305 @@
+/**
+ * Recipe 11 — Dunning sequence: failed-payment recovery loop.
+ *
+ * Real production pattern. A subscription's recurring charge fails. You don't
+ * just give up — you run a multi-step recovery sequence that maximises revenue
+ * recovery and minimises customer churn.
+ *
+ * # The dunning sequence
+ *
+ *   Day 0   Charge fails (most commonly: insufficient funds, card expired).
+ *           → MP retries automatically (configurable on the subscription, default 3 attempts).
+ *   Day 0   Webhook: `subscription_authorized_payment` with status=rejected.
+ *           → Send "Hubo un problema con tu cobro" email + WhatsApp.
+ *           → Include the buyer's `init_point_url` so they can retry the
+ *             card on MP's UI without you collecting card data.
+ *   Day 3   Still no successful retry.
+ *           → Pause the subscription via `pause_subscription`.
+ *           → Send a softer "Tu suscripción está pausada — ¿querés que
+ *             actualicemos la tarjeta?" message.
+ *   Day 7   No card swap.
+ *           → Send retention offer: "Te damos un mes gratis si volvés".
+ *   Day 14  No response to retention.
+ *           → Cancel the subscription. Send "Cancelamos. ¿Te podemos ayudar
+ *             con algo?" message with feedback link.
+ *
+ * # What this recipe shows
+ *
+ *   - Webhook handler reading `subscription_authorized_payment` events.
+ *   - State machine driven by elapsed time + buyer responses.
+ *   - Composition with @ar-agents/whatsapp for the dunning message channel.
+ *   - HITL gating on the cancellation step (retention managers might want
+ *     to manually approve cancellations of high-value accounts).
+ */
+
+import {
+  MercadoPagoClient,
+  parseWebhookEvent,
+  verifyWebhookSignature,
+  explainPaymentStatus,
+  type ParsedWebhookEvent,
+  type SubscriptionPayment,
+} from "@ar-agents/mercadopago";
+
+const mp = new MercadoPagoClient({
+  accessToken: process.env.MP_ACCESS_TOKEN!,
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// State store
+// ─────────────────────────────────────────────────────────────────────────────
+
+// In production: VercelKV / Redis / Postgres. Schema:
+//   key: dunning:<subscriptionId>
+//   value: { firstFailureAt, attemptsSent, status: "active" | "paused" | "cancelled" }
+type DunningState = {
+  subscriptionId: string;
+  firstFailureAt: number;
+  attemptsSent: number;
+  status: "active" | "paused" | "cancelled";
+  buyerEmail: string;
+  buyerWhatsApp?: string;
+};
+
+const dunningStore = new Map<string, DunningState>();
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Webhook handler — entry point for the dunning sequence
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function POST(req: Request) {
+  const url = new URL(req.url);
+  const rawBody = await req.text();
+
+  const ok = await verifyWebhookSignature({
+    requestId: req.headers.get("x-request-id"),
+    dataId: parseWebhookEvent(JSON.parse(rawBody), url.searchParams)?.dataId ?? "",
+    signatureHeader: req.headers.get("x-signature"),
+    secret: process.env.MP_WEBHOOK_SECRET!,
+  });
+  if (!ok) return new Response("invalid signature", { status: 401 });
+
+  const event = parseWebhookEvent(JSON.parse(rawBody), url.searchParams);
+  if (!event) return new Response("ok", { status: 200 });
+
+  // Two relevant topics: subscription_authorized_payment (recurring charge),
+  // and payment.updated (in case of one-shot charge associated to a sub).
+  if (event.topic === "subscription_authorized_payment") {
+    await handleRecurringChargeWebhook(event);
+  }
+
+  return new Response("ok", { status: 200 });
+}
+
+/**
+ * The webhook payload includes a `data.id` for the SubscriptionPayment that
+ * fired. To find the parent preapproval we hit MP's auth payments endpoint
+ * directly — there's no single-record getter on the client (MP's API returns
+ * authorized_payments only via the search endpoint), so the recipe goes
+ * through the raw request helper.
+ */
+async function fetchSubscriptionPaymentById(
+  authPaymentId: string,
+): Promise<SubscriptionPayment | null> {
+  // The toolkit doesn't expose a single-record getter for SubscriptionPayment
+  // because MP doesn't ship one either. The closest stable path is the
+  // /authorized_payments search query. In your dunning state store you'll
+  // already know the preapproval_id, so this lookup is rarely needed —
+  // included here for completeness when the webhook is the only source.
+  try {
+    const url = `https://api.mercadopago.com/authorized_payments/${authPaymentId}`;
+    const res = await fetch(url, {
+      headers: {
+        Authorization: `Bearer ${process.env.MP_ACCESS_TOKEN}`,
+      },
+    });
+    if (!res.ok) return null;
+    return (await res.json()) as SubscriptionPayment;
+  } catch {
+    return null;
+  }
+}
+
+async function handleRecurringChargeWebhook(event: ParsedWebhookEvent) {
+  const ap = await fetchSubscriptionPaymentById(event.dataId);
+  if (!ap || !ap.preapproval_id) return;
+
+  if (ap.status === "approved") {
+    // Reset dunning state — recurring charge recovered.
+    dunningStore.delete(ap.preapproval_id);
+    return;
+  }
+
+  if (ap.status !== "rejected") return; // pending — wait for next event
+
+  // Charge was rejected. Engage the dunning sequence. explainPaymentStatus
+  // wants a full Payment shape; the relevant fields (status + status_detail)
+  // come from the SubscriptionPayment, so we widen the cast.
+  const explained = explainPaymentStatus({
+    id: String(ap.id),
+    status: ap.status,
+    status_detail: ap.reason ?? "",
+    transaction_amount: ap.transaction_amount ?? 0,
+    currency_id: ap.currency_id ?? "ARS",
+  } as unknown as Parameters<typeof explainPaymentStatus>[0]);
+
+  const sub = await mp.getPreapproval(ap.preapproval_id);
+  let state = dunningStore.get(ap.preapproval_id);
+
+  if (!state) {
+    state = {
+      subscriptionId: ap.preapproval_id,
+      firstFailureAt: Date.now(),
+      attemptsSent: 0,
+      status: "active",
+      buyerEmail: sub.payer_email ?? "",
+    };
+    dunningStore.set(ap.preapproval_id, state);
+  }
+
+  await runDunningStep(state, explained);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Dunning state machine
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function runDunningStep(
+  state: DunningState,
+  explained: ReturnType<typeof explainPaymentStatus>,
+) {
+  const elapsedDays = (Date.now() - state.firstFailureAt) / (24 * 60 * 60 * 1000);
+
+  if (elapsedDays < 3 && state.attemptsSent === 0) {
+    // Day 0: friendly heads-up. The buyer can retry the card via the
+    // subscription's init_point_url (MP UI handles re-auth).
+    await sendMessage(state.buyerEmail, "first-failure", {
+      reason: explained.summary,
+      retryUrl: await fetchInitPoint(state.subscriptionId),
+    });
+    state.attemptsSent = 1;
+    return;
+  }
+
+  if (elapsedDays >= 3 && elapsedDays < 7 && state.attemptsSent === 1) {
+    // Day 3: pause the subscription.
+    await mp.pausePreapproval(state.subscriptionId);
+    state.status = "paused";
+    await sendMessage(state.buyerEmail, "paused", {
+      retryUrl: await fetchInitPoint(state.subscriptionId),
+    });
+    state.attemptsSent = 2;
+    return;
+  }
+
+  if (elapsedDays >= 7 && elapsedDays < 14 && state.attemptsSent === 2) {
+    // Day 7: retention offer.
+    await sendMessage(state.buyerEmail, "retention-offer", {
+      offer: "1 mes gratis si volvés en los próximos 7 días",
+      retryUrl: await fetchInitPoint(state.subscriptionId),
+    });
+    state.attemptsSent = 3;
+    return;
+  }
+
+  if (elapsedDays >= 14 && state.attemptsSent === 3) {
+    // Day 14: cancel.
+    // HITL: in production, route this to a human approval queue first.
+    // For this recipe, we cancel immediately.
+    await mp.cancelPreapproval(state.subscriptionId);
+    state.status = "cancelled";
+    await sendMessage(state.buyerEmail, "cancelled", {});
+    state.attemptsSent = 4;
+    return;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Side-effects (replace with your channel of choice)
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function fetchInitPoint(subscriptionId: string): Promise<string> {
+  const sub = await mp.getPreapproval(subscriptionId);
+  return sub.init_point;
+}
+
+async function sendMessage(
+  email: string,
+  template: "first-failure" | "paused" | "retention-offer" | "cancelled",
+  data: Record<string, string>,
+) {
+  // In production: compose an email via Resend / Postmark, AND send a
+  // WhatsApp via @ar-agents/whatsapp. Keeping this stub here so the recipe
+  // is copy-pasteable into any channel.
+  console.log(`[dunning] ${template} -> ${email}`, data);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Cron job — fallback when webhooks miss
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Run on a daily Vercel Cron. Catches dunning states that didn't progress
+ * because the buyer never triggered a webhook (e.g. they ignored the email
+ * and didn't retry their card — no event fires until their NEXT scheduled
+ * recurring charge).
+ *
+ * Add to vercel.json:
+ *
+ *   {
+ *     "crons": [
+ *       { "path": "/api/cron/dunning-tick", "schedule": "0 9 * * *" }
+ *     ]
+ *   }
+ */
+export async function dunningTick() {
+  for (const state of dunningStore.values()) {
+    if (state.status === "cancelled") continue;
+    await runDunningStep(
+      state,
+      explainPaymentStatus({
+        id: "tick",
+        status: "rejected",
+        status_detail: "cc_rejected_call_for_authorize",
+        transaction_amount: 0,
+        currency_id: "ARS",
+      } as unknown as Parameters<typeof explainPaymentStatus>[0]),
+    );
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Test harness — run with `pnpm tsx cookbook/11-dunning-sequence.ts`
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function main() {
+  // Simulate a failure event on subscription "abc123".
+  const fakeState: DunningState = {
+    subscriptionId: "abc123",
+    firstFailureAt: Date.now() - 4 * 24 * 60 * 60 * 1000, // 4 days ago
+    attemptsSent: 1,
+    status: "active",
+    buyerEmail: "test@example.com",
+  };
+  dunningStore.set("abc123", fakeState);
+
+  await runDunningStep(
+    fakeState,
+    explainPaymentStatus({
+      id: "test",
+      status: "rejected",
+      status_detail: "cc_rejected_insufficient_amount",
+      transaction_amount: 1000,
+      currency_id: "ARS",
+    } as unknown as Parameters<typeof explainPaymentStatus>[0]),
+  );
+
+  console.log("Dunning state after step:", dunningStore.get("abc123"));
+}
+
+if (process.argv[1]?.endsWith("11-dunning-sequence.ts")) {
+  main().catch((err: unknown) => {
+    console.error(err);
+    process.exit(1);
+  });
+}