@ar-agents/mercadopago 0.15.2 → 0.16.0

package/README.skeleton.md

@@ -1,5 +1,5 @@
 <!--
-  README skeleton — Vercel-official quality.
+  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
@@ -7,7 +7,7 @@
 
   Hard rules:
   - Lead with what it is and a 3-line install + first call.
-  - Real numbers (latency, bundle size) only — no "fast", "blazing", "robust".
+  - 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.
@@ -23,7 +23,7 @@
 
 Mercado Pago Agent Toolkit. Built on Vercel. 89 typed tools across the agent-relevant Mercado Pago API surface (Subscriptions, Payments, Checkout Pro, Marketplace OAuth, Order Management, Customers, Cards, Cuotas, QR, 3DS, Point devices, Stores+POS, Account/Balance/Settlements, Webhooks, Disputes, Lookups, Bank Accounts) for the [Vercel AI SDK](https://ai-sdk.dev/) 6 `Experimental_Agent`. Edge-Runtime-safe.
 
-> **Reading this as an agent?** Skip to [AGENTS.md](./AGENTS.md) — decision tree, result schemas to memorize, error patterns, latency table.
+> **Reading this as an agent?** Skip to [AGENTS.md](./AGENTS.md): decision tree, result schemas to memorize, error patterns, latency table.
 
 ## Quick start
 
@@ -57,16 +57,16 @@ That's it. The agent picks `create_subscription`, returns an `init_point_url` yo
 
 | | |
 | --- | --- |
-| **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). |
+| **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. |
+| **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.
+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.
@@ -89,14 +89,14 @@ Server-side MP API client. Edge-Runtime safe.
 
 | Option | Default | Description |
 | --- | --- | --- |
-| `accessToken` (required) | — | TEST- prefix for sandbox, APP_USR- for production. |
+| `accessToken` (required) | no | 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. |
+| `circuitBreaker` | no | `new CircuitBreaker({ ... })` to fail fast on cascading failures. |
+| `traceContext` | no | OpenTelemetry context propagator (W3C trace headers). |
+| `onCall` | no | Observability hook fired after every request. |
 
 ### `mercadoPagoTools(client, options)`
 
@@ -104,7 +104,7 @@ Returns the agent tool set wired to the given client.
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `state` | yes | `SubscriptionStateAdapter` — `InMemoryStateAdapter`, `VercelKVSubscriptionStateAdapter`, or your own. |
+| `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. |
@@ -123,7 +123,7 @@ Returns the agent tool set wired to the given client.
 
 ### 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.
+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
 
@@ -164,22 +164,22 @@ const limiter = new VercelKVRateLimiter({
 
 ### Cookbook
 
-9 recipes in [`./cookbook`](./cookbook/) — Checkout Pro, SaaS subscription, webhook handler, marketplace split, QR in-store, 3DS challenge, manual capture, recovery patterns, full OpenTelemetry wiring.
+9 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 |
+| Tools as Vercel AI SDK 6 schemas | ✓ | no | build it |
+| AR-specific (cuotas, AR issuer promos, AR phone, MLA-verified) | ✓ | no | weeks |
+| `AGENTS.md` per package (LLM-readable) | ✓ | no |: |
+| Idempotency-by-default for state mutations | ✓ | no | 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) | ✓ | — | — |
+| Vercel KV adapters via subpath | ✓ | no |: |
+| OpenTelemetry instrumentation + recipe | ✓ | no | build it |
+| Circuit breaker + deadline propagation | ✓ | no | build it |
+| Tool middleware (compose audit/rate/metrics) | ✓ | no |: |
 | 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.

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);
+  });
+}