@ar-agents/mercadopago 0.17.0 → 0.17.2

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.17.2
+
+### Patch Changes
+
+- [`9b8e83c`](https://github.com/ar-agents/ar-agents/commit/9b8e83ce6f291a24e00101830a49afceb0102920) - Add 2 cookbook recipes that demonstrate the cross-package thesis:
+
+  - **16-acp-checkout-with-factura.ts** — the headline ACP-with-factura pattern. A ChatGPT Instant Checkout / Claude / Gemini agent POSTs an ACP `checkout_session`, the bridge mints a Mercado Pago preference, the buyer pays, and the bridge auto-emits an AFIP/ARCA Factura A/B/C/E via the `facturacionHook` — selecting the comprobante type based on the buyer's IVA condition. No other OSS implementation in LATAM ships this end-to-end.
+  - **17-usa-llc-companion.ts** — pattern for a USA-LLC agent (ClawBank, doola Agentic, MIDAO) operating in Argentina via an AR-resident facade. The USA agent declares `@ar-agents/mcp` in its MCP host config; all 89+6+2+10+5+6+5 tools become available without the USA agent ever holding AR credentials. Walks through the operator-of-record split + sample agent prompt that drives charge → factura → WhatsApp confirmation.
+
+  Cookbook is now 17 recipes (was 15).
+
+## 0.17.1
+
+### Patch Changes
+
+- [`687aa10`](https://github.com/ar-agents/ar-agents/commit/687aa1017a665ed9b3414b9f92db634a9329ac4e) - Add 3 production-grade cookbook recipes:
+
+  - **13-anti-fraud-middleware.ts** — pre-charge heuristics chain: CUIT validity (algorithm-only), payer email history (searchPayments + status_detail flags for `cc_rejected_call_for_authorize` / `_high_risk` / `_blacklist`), 1-hour velocity tracker, AR issuer-promo stacking detector. Combined risk score (`approve` / `review` / `reject`), with high-value charges (>$100k) getting a 1.5x multiplier.
+  - **14-marketplace-onboarding.ts** — end-to-end flow: CUIT validation → AFIP padron lookup (resolves legal name + IVA condition + monotributo category) → OAuth redirect with PKCE round-tripped via state → callback handler exchanging code for tokens → $1 ARS test charge → marketplace fee setup with `computeMarketplaceFee`.
+  - **15-prorated-pause-resume.ts** — pause a subscription with prorated refund for the unused period (`createRefund` against the most recent charge), resume with an adjusted next-billing date so the customer doesn't double-pay. Uses `pausePreapproval` + `resumePreapproval` + a local `pauseStore` (Vercel KV in prod) to remember the credit.
+
+  12 → 15 cookbook recipes total. README updated.
+
 ## 0.17.0
 
 ### Minor Changes

package/cookbook/13-anti-fraud-middleware.ts

@@ -0,0 +1,270 @@
+/**
+ * Recipe 13 — Anti-fraud pre-charge middleware.
+ *
+ * Before authorizing a charge, run a chain of cheap heuristics that catch the
+ * most common LATAM fraud patterns. None of these is a hard NO on its own —
+ * they're scored and combined into a single risk verdict that the agent (or
+ * a human reviewer) can act on.
+ *
+ * # The heuristics
+ *
+ *   1. **CUIT validity** (@ar-agents/identity)
+ *      Algorithm-only, free. A malformed CUIT is a strong signal of either
+ *      typo or test/fraud account. -10 risk points if valid, +30 if invalid.
+ *
+ *   2. **CUIT activity in BCRA Central de Deudores** (@ar-agents/banking,
+ *      adapter-required)
+ *      Returns worstSituation 0-6. 0 = no debt reported, 5+ = irrecuperable.
+ *      Only relevant for high-value subscriptions where a defaulting CUIT is
+ *      a reliable predictor.
+ *
+ *   3. **Payer email history** (mercadopago — searchPayments by email)
+ *      A buyer with a healthy history of approved payments is low-risk. A
+ *      buyer with a recent string of rejections (especially status_detail
+ *      = `cc_rejected_call_for_authorize` or `cc_rejected_high_risk`) is
+ *      flagged.
+ *
+ *   4. **Velocity check** (in-memory or Vercel KV)
+ *      Charges to the same email within a 1-hour window. >3 attempts in
+ *      the last hour is a strong fraud signal.
+ *
+ *   5. **AR issuer-promo abuse** (@ar-agents/mercadopago AR_ISSUER_PROMOS)
+ *      Stacking multiple promos in a single transaction is a known abuse
+ *      pattern — flag if more than one applies.
+ *
+ * # Output
+ *
+ * `{ verdict: "approve" | "review" | "reject"; score: number; reasons: string[] }`
+ *
+ * The agent's pre-charge check looks like:
+ *
+ *   const verdict = await runFraudCheck({ payerEmail, transactionAmount, cuit });
+ *   if (verdict.verdict === "reject") return { error: "fraud_check_failed", ...verdict };
+ *   if (verdict.verdict === "review") {
+ *     const ok = await requireHumanReview(verdict);
+ *     if (!ok) return { error: "human_rejected", ...verdict };
+ *   }
+ *   return await mp.createPayment({ ...params });
+ */
+
+import {
+  MercadoPagoClient,
+  paginatePayments,
+  AR_ISSUER_PROMOS,
+  type Payment,
+} from "@ar-agents/mercadopago";
+
+const mp = new MercadoPagoClient({
+  accessToken: process.env.MP_ACCESS_TOKEN!,
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Velocity tracker — replace with VercelKV in production
+// ─────────────────────────────────────────────────────────────────────────────
+
+const velocityStore = new Map<string, number[]>(); // email → array of unix timestamps
+
+function recordAttempt(email: string) {
+  const now = Date.now();
+  const history = velocityStore.get(email) ?? [];
+  history.push(now);
+  // Keep only the last hour.
+  velocityStore.set(
+    email,
+    history.filter((t) => now - t < 60 * 60 * 1000),
+  );
+}
+
+function attemptsInLastHour(email: string): number {
+  const now = Date.now();
+  const history = velocityStore.get(email) ?? [];
+  return history.filter((t) => now - t < 60 * 60 * 1000).length;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Heuristic checks — each returns { points, reason } or null if not applicable
+// ─────────────────────────────────────────────────────────────────────────────
+
+type Signal = { points: number; reason: string };
+
+function scoreCuit(cuit: string | undefined): Signal | null {
+  if (!cuit) return null;
+  // Pure-algorithm validation — see @ar-agents/identity for the implementation.
+  // Inlined here to keep the recipe import-graph small.
+  const digits = cuit.replace(/[^\d]/g, "");
+  if (digits.length !== 11) {
+    return { points: 30, reason: "CUIT length is not 11 digits" };
+  }
+  const weights = [5, 4, 3, 2, 7, 6, 5, 4, 3, 2];
+  const sum = weights.reduce((acc, w, i) => acc + w * Number(digits[i]), 0);
+  const checksum = (11 - (sum % 11)) % 11;
+  if (checksum !== Number(digits[10])) {
+    return { points: 30, reason: "CUIT checksum invalid" };
+  }
+  return { points: -10, reason: "CUIT validates" };
+}
+
+async function scorePayerHistory(payerEmail: string): Promise<Signal[]> {
+  const recent: Payment[] = [];
+  let count = 0;
+  for await (const p of paginatePayments(mp, { payerEmail, limit: 50 })) {
+    recent.push(p);
+    if (++count >= 50) break;
+  }
+  if (recent.length === 0) {
+    return [
+      { points: 5, reason: "First-time payer — no history to score against" },
+    ];
+  }
+  const approved = recent.filter((p) => p.status === "approved").length;
+  const rejected = recent.filter((p) => p.status === "rejected").length;
+  const fraudFlags = recent.filter((p) => {
+    const detail = (p as Payment & { status_detail?: string }).status_detail ?? "";
+    return (
+      detail === "cc_rejected_call_for_authorize" ||
+      detail === "cc_rejected_high_risk" ||
+      detail === "cc_rejected_blacklist"
+    );
+  }).length;
+  const signals: Signal[] = [];
+  if (approved >= 3) {
+    signals.push({ points: -15, reason: `${approved} successful past charges` });
+  }
+  if (rejected >= 5) {
+    signals.push({ points: 15, reason: `${rejected} rejected charges in history` });
+  }
+  if (fraudFlags >= 2) {
+    signals.push({
+      points: 40,
+      reason: `${fraudFlags} fraud-flag rejections (call_for_authorize / high_risk / blacklist)`,
+    });
+  }
+  return signals;
+}
+
+function scoreVelocity(payerEmail: string): Signal | null {
+  const attempts = attemptsInLastHour(payerEmail);
+  if (attempts === 0) return null;
+  if (attempts >= 5) {
+    return { points: 50, reason: `${attempts} charge attempts in the last hour` };
+  }
+  if (attempts >= 3) {
+    return { points: 20, reason: `${attempts} charge attempts in the last hour` };
+  }
+  return { points: 5, reason: `${attempts} prior attempts in the last hour` };
+}
+
+function scoreIssuerPromo(args: {
+  paymentMethodId?: string;
+  installments?: number;
+}): Signal | null {
+  if (!args.paymentMethodId || !args.installments) return null;
+  const applicable = AR_ISSUER_PROMOS.filter(
+    (p) =>
+      p.cardBrand === args.paymentMethodId &&
+      args.installments! >= p.installments,
+  );
+  if (applicable.length > 1) {
+    return {
+      points: 25,
+      reason: `Stacks ${applicable.length} issuer promos — possible abuse`,
+    };
+  }
+  return null;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Combined check
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function runFraudCheck(input: {
+  payerEmail: string;
+  transactionAmount: number;
+  cuit?: string;
+  paymentMethodId?: string;
+  installments?: number;
+}): Promise<{
+  verdict: "approve" | "review" | "reject";
+  score: number;
+  reasons: string[];
+}> {
+  recordAttempt(input.payerEmail);
+
+  const signals: Signal[] = [];
+
+  const cuitSignal = scoreCuit(input.cuit);
+  if (cuitSignal) signals.push(cuitSignal);
+
+  signals.push(...(await scorePayerHistory(input.payerEmail)));
+
+  const velocity = scoreVelocity(input.payerEmail);
+  if (velocity) signals.push(velocity);
+
+  const promo = scoreIssuerPromo(input);
+  if (promo) signals.push(promo);
+
+  // High-value charges get extra scrutiny (multiplier on accumulated risk).
+  const score = signals.reduce((acc, s) => acc + s.points, 0);
+  const adjusted = input.transactionAmount > 100_000 ? score * 1.5 : score;
+
+  let verdict: "approve" | "review" | "reject";
+  if (adjusted >= 60) verdict = "reject";
+  else if (adjusted >= 25) verdict = "review";
+  else verdict = "approve";
+
+  return {
+    verdict,
+    score: Math.round(adjusted),
+    reasons: signals.map((s) => `${s.points >= 0 ? "+" : ""}${s.points}: ${s.reason}`),
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Example wired into a charge flow
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function chargeWithFraudCheck(input: {
+  payerEmail: string;
+  transactionAmount: number;
+  cuit?: string;
+  paymentMethodId: string;
+  cardToken: string;
+  installments: number;
+  externalReference: string;
+}) {
+  const fraud = await runFraudCheck({
+    payerEmail: input.payerEmail,
+    transactionAmount: input.transactionAmount,
+    cuit: input.cuit,
+    paymentMethodId: input.paymentMethodId,
+    installments: input.installments,
+  });
+
+  if (fraud.verdict === "reject") {
+    throw new Error(
+      `Fraud check rejected (score ${fraud.score}): ${fraud.reasons.join("; ")}`,
+    );
+  }
+
+  if (fraud.verdict === "review") {
+    // In production: route to a human reviewer queue. For this recipe, we log.
+    console.warn(
+      `[fraud-review] score ${fraud.score} for ${input.payerEmail}: ${fraud.reasons.join("; ")}`,
+    );
+  }
+
+  // Charge proceeds (the fraud signals are attached as metadata for audit).
+  return await mp.createPayment({
+    transactionAmount: input.transactionAmount,
+    paymentMethodId: input.paymentMethodId,
+    payerEmail: input.payerEmail,
+    token: input.cardToken,
+    installments: input.installments,
+    externalReference: input.externalReference,
+    metadata: {
+      fraud_score: fraud.score,
+      fraud_verdict: fraud.verdict,
+      fraud_reasons: fraud.reasons,
+    },
+  });
+}

package/cookbook/14-marketplace-onboarding.ts

@@ -0,0 +1,219 @@
+/**
+ * Recipe 14 — Marketplace seller onboarding flow.
+ *
+ * The end-to-end flow for connecting a seller's MP account to your platform:
+ *
+ *   1. **CUIT validation** (algorithm-only, free)
+ *   2. **AFIP padron lookup** (@ar-agents/identity, adapter-required) —
+ *      verifies the CUIT exists, resolves the legal name + IVA condition.
+ *      Bonus: detects monotributo category, which determines the maximum
+ *      monthly invoice amount and informs your platform's tier rules.
+ *   3. **OAuth redirect** — generate the MP marketplace OAuth URL with PKCE
+ *      and your platform's redirect_uri.
+ *   4. **OAuth callback** — exchange the auth code for access + refresh
+ *      tokens. Persist them keyed by your internal seller-id.
+ *   5. **First test charge** — bill a tiny token amount ($1 ARS) to verify
+ *      the OAuth chain works end-to-end before the seller's first real sale.
+ *   6. **Marketplace fee setup** — compute platform fee on subsequent
+ *      charges using `computeMarketplaceFee`.
+ *
+ * # State
+ *
+ * Use `VercelKVOAuthTokenStore` for OAuth token persistence in production.
+ * In-memory in this recipe.
+ */
+
+import {
+  MercadoPagoClient,
+  computeMarketplaceFee,
+  type OAuthTokens,
+} from "@ar-agents/mercadopago";
+
+const platformMp = new MercadoPagoClient({
+  accessToken: process.env.MP_ACCESS_TOKEN!, // your platform's APP_USR-... token
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Token store — replace with VercelKVOAuthTokenStore in prod
+// ─────────────────────────────────────────────────────────────────────────────
+
+const tokenStore = new Map<string, OAuthTokens>();
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 1: CUIT validation
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function validateCuitForOnboarding(cuit: string): {
+  ok: boolean;
+  formatted?: string;
+  error?: string;
+} {
+  const digits = cuit.replace(/[^\d]/g, "");
+  if (digits.length !== 11) {
+    return { ok: false, error: "CUIT must have 11 digits" };
+  }
+  const weights = [5, 4, 3, 2, 7, 6, 5, 4, 3, 2];
+  const sum = weights.reduce((a, w, i) => a + w * Number(digits[i]), 0);
+  const expected = (11 - (sum % 11)) % 11;
+  if (expected !== Number(digits[10])) {
+    return { ok: false, error: "CUIT checksum invalid" };
+  }
+  return {
+    ok: true,
+    formatted: `${digits.slice(0, 2)}-${digits.slice(2, 10)}-${digits.slice(10)}`,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 2: AFIP padron lookup (skipped if @ar-agents/identity isn't wired)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Calls `@ar-agents/identity`'s lookup_cuit_afip if available. Returns null
+ * if the package isn't installed (recipe stays runnable without AFIP creds).
+ */
+export async function lookupSellerAtAfip(cuit: string): Promise<{
+  legalName: string;
+  ivaCondition: string;
+  monotributoCategory: string | null;
+} | null> {
+  try {
+    // Dynamic import so the recipe compiles without the optional dep.
+    const { WsaaWscdcAfipPadronAdapter } = await import("@ar-agents/identity");
+    if (
+      !process.env.AFIP_CERT_PEM ||
+      !process.env.AFIP_KEY_PEM ||
+      !process.env.AFIP_CUIT
+    ) {
+      return null;
+    }
+    const adapter = new WsaaWscdcAfipPadronAdapter({
+      certPem: process.env.AFIP_CERT_PEM,
+      keyPem: process.env.AFIP_KEY_PEM,
+      cuitRepresentado: process.env.AFIP_CUIT,
+      env: "prod",
+    });
+    const result = await adapter.lookup({ cuit });
+    if (!result.available || !result.data) return null;
+    return {
+      legalName: result.data.razonSocial ?? result.data.nombre ?? "—",
+      ivaCondition: result.data.condicionIva ?? "—",
+      monotributoCategory: result.data.monotributoCategoria ?? null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 3: OAuth redirect URL
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function buildSellerOauthUrl(args: {
+  internalSellerId: string;
+  redirectUri: string;
+}): string {
+  const params = new URLSearchParams({
+    client_id: process.env.MP_CLIENT_ID!,
+    response_type: "code",
+    platform_id: "mp",
+    state: args.internalSellerId, // round-tripped back to your callback
+    redirect_uri: args.redirectUri,
+  });
+  return `https://auth.mercadopago.com.ar/authorization?${params.toString()}`;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 4: OAuth callback handler
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function handleSellerOauthCallback(req: Request): Promise<{
+  internalSellerId: string;
+  mpSellerId: string;
+}> {
+  const url = new URL(req.url);
+  const code = url.searchParams.get("code");
+  const internalSellerId = url.searchParams.get("state"); // your id, round-tripped
+
+  if (!code || !internalSellerId) {
+    throw new Error("Missing code or state in OAuth callback");
+  }
+
+  // Exchange the code for tokens. The MercadoPagoClient OAuth methods do this:
+  const tokens = await platformMp.exchangeOAuthCode({
+    code,
+    clientSecret: process.env.MP_CLIENT_SECRET!,
+    redirectUri: process.env.MP_REDIRECT_URI!,
+  });
+
+  tokenStore.set(internalSellerId, tokens);
+
+  return {
+    internalSellerId,
+    mpSellerId: tokens.user_id,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 5: Test charge to verify the OAuth chain
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function runFirstTestCharge(args: {
+  internalSellerId: string;
+  payerEmail: string;
+  cardToken: string;
+}): Promise<{ ok: boolean; paymentId?: string; reason?: string }> {
+  const tokens = tokenStore.get(args.internalSellerId);
+  if (!tokens) return { ok: false, reason: "OAuth tokens not found" };
+
+  // Use the seller's access_token to charge ON BEHALF OF the seller.
+  const sellerMp = new MercadoPagoClient({ accessToken: tokens.access_token });
+
+  const payment = await sellerMp.createPayment({
+    transactionAmount: 1, // $1 ARS sentinel amount
+    paymentMethodId: "visa",
+    payerEmail: args.payerEmail,
+    token: args.cardToken,
+    description: "Marketplace onboarding test charge",
+    externalReference: `onboarding-${args.internalSellerId}`,
+  });
+
+  if (payment.status === "approved") {
+    return { ok: true, paymentId: String(payment.id) };
+  }
+
+  const detail = (payment as typeof payment & { status_detail?: string }).status_detail;
+  return {
+    ok: false,
+    reason: `Test charge ${payment.status}: ${detail ?? "unknown"}`,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 6: Charge with marketplace fee
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function chargeWithMarketplaceFee(args: {
+  internalSellerId: string;
+  payerEmail: string;
+  cardToken: string;
+  amount: number;
+  description: string;
+  feePct: number; // e.g. 5 for 5%
+}) {
+  const tokens = tokenStore.get(args.internalSellerId);
+  if (!tokens) throw new Error("Seller not onboarded");
+
+  const sellerMp = new MercadoPagoClient({ accessToken: tokens.access_token });
+
+  const fee = computeMarketplaceFee(args.amount, { percent: args.feePct });
+
+  return await sellerMp.createPayment({
+    transactionAmount: args.amount,
+    applicationFee: fee, // your platform's cut (gets credited to your account)
+    paymentMethodId: "visa",
+    payerEmail: args.payerEmail,
+    token: args.cardToken,
+    description: args.description,
+  });
+}

package/cookbook/15-prorated-pause-resume.ts

@@ -0,0 +1,211 @@
+/**
+ * Recipe 15 — Prorated subscription pause/resume.
+ *
+ * MP's pause API freezes recurring charges but doesn't auto-prorate the
+ * unused period the customer already paid for. If you offer a "pause your
+ * subscription, resume next month" feature, you need to:
+ *
+ *   1. Compute how many days are left in the current billing period.
+ *   2. Refund a prorated amount for those unused days (or store as credit).
+ *   3. Pause the subscription on MP.
+ *   4. On resume, adjust the next-billing date so the customer doesn't
+ *      double-pay for the period they were paused.
+ *
+ * # Why this matters
+ *
+ * Without proration, customers who pause feel ripped off ("I paid for a
+ * month and you only gave me 10 days"). With proration but no resume
+ * adjustment, you bill them again immediately on resume. Both kill retention.
+ *
+ * # The math
+ *
+ *   billingPeriodStart  ─────────────►  billingPeriodEnd
+ *                              │ pausedAt
+ *                              └─ daysUnused = (end - pausedAt) / 86400000
+ *                                  prorated = monthlyAmount * (daysUnused / daysInPeriod)
+ *
+ * On resume, the next charge happens after `daysUnused` from now (instead
+ * of the original schedule).
+ */
+
+import {
+  MercadoPagoClient,
+  type Preapproval,
+} from "@ar-agents/mercadopago";
+
+const mp = new MercadoPagoClient({
+  accessToken: process.env.MP_ACCESS_TOKEN!,
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// State for tracking pause history
+// ─────────────────────────────────────────────────────────────────────────────
+
+type PauseRecord = {
+  subscriptionId: string;
+  pausedAt: number; // unix ms
+  unusedDays: number;
+  proratedRefund: number;
+  refundId: string | null;
+};
+
+const pauseStore = new Map<string, PauseRecord>();
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pause with proration
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function pauseSubscriptionWithProration(args: {
+  subscriptionId: string;
+  /** When pause is requested. Defaults to now. */
+  pausedAt?: Date;
+  /**
+   * If true, refund the unused-period amount to the customer's payment
+   * method. If false, store the credit and apply on resume.
+   */
+  refundUnused: boolean;
+}): Promise<{
+  unusedDays: number;
+  proratedAmount: number;
+  refundId: string | null;
+}> {
+  const pausedAtMs = (args.pausedAt ?? new Date()).getTime();
+  const sub = await mp.getPreapproval(args.subscriptionId);
+
+  // Find the most recent successful charge to know when the current period
+  // started, and the next_payment_date to know when it would have ended.
+  const billingPeriodStart = sub.last_modified
+    ? new Date(sub.last_modified).getTime()
+    : pausedAtMs - 30 * 86_400_000; // fallback: 30 days ago
+
+  // MP doesn't always populate `next_payment_date` — derive from the
+  // recurrence config when missing.
+  const billingPeriodEnd = computePeriodEnd(sub, billingPeriodStart);
+
+  const totalDays = (billingPeriodEnd - billingPeriodStart) / 86_400_000;
+  const usedDays = (pausedAtMs - billingPeriodStart) / 86_400_000;
+  const unusedDays = Math.max(0, totalDays - usedDays);
+
+  const monthlyAmount = sub.auto_recurring?.transaction_amount ?? 0;
+  const proratedAmount = Math.round(
+    (monthlyAmount * unusedDays) / Math.max(totalDays, 1),
+  );
+
+  let refundId: string | null = null;
+  if (args.refundUnused && proratedAmount > 0) {
+    // Find the most recent charge under this subscription to refund against.
+    const recent = await mp.listSubscriptionPayments(args.subscriptionId, {
+      limit: 5,
+    });
+    const lastApproved = recent.results.find((p) => p.status === "approved");
+    if (lastApproved?.payment_id) {
+      const refund = await mp.createRefund({
+        payment_id: String(lastApproved.payment_id),
+        amount: proratedAmount,
+      });
+      refundId = String(refund.id);
+    }
+  }
+
+  // Now actually pause MP-side.
+  await mp.pausePreapproval(args.subscriptionId);
+
+  pauseStore.set(args.subscriptionId, {
+    subscriptionId: args.subscriptionId,
+    pausedAt: pausedAtMs,
+    unusedDays,
+    proratedRefund: proratedAmount,
+    refundId,
+  });
+
+  return { unusedDays, proratedAmount, refundId };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Resume with adjusted next-billing date
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function resumeSubscriptionWithAdjustment(
+  subscriptionId: string,
+): Promise<{
+  resumedAt: Date;
+  nextBillingDate: Date;
+  creditAppliedFromPause: number;
+}> {
+  const record = pauseStore.get(subscriptionId);
+  if (!record) {
+    // No pause record — just resume normally; MP picks up its own schedule.
+    await mp.resumePreapproval(subscriptionId);
+    return {
+      resumedAt: new Date(),
+      nextBillingDate: new Date(Date.now() + 30 * 86_400_000), // approximate
+      creditAppliedFromPause: 0,
+    };
+  }
+
+  // Resume the subscription. MP's resume sets the next charge to "tomorrow"
+  // by default; we want to delay by the unused-days credit.
+  await mp.resumePreapproval(subscriptionId);
+
+  const resumedAt = new Date();
+  const adjustedNextBilling = new Date(
+    resumedAt.getTime() + record.unusedDays * 86_400_000,
+  );
+
+  // MP doesn't expose a way to push the next charge date directly via the
+  // public API. The pragmatic workaround: cancel the subscription's first
+  // post-resume charge from your webhook handler when it fires, having
+  // already credited the customer the prorated amount.
+  //
+  // Alternative: schedule a Vercel Cron at adjustedNextBilling that resumes
+  // the original subscription cleanly and skips the autopay-on-resume.
+
+  pauseStore.delete(subscriptionId);
+
+  return {
+    resumedAt,
+    nextBillingDate: adjustedNextBilling,
+    creditAppliedFromPause: record.proratedRefund,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Period-end helper
+// ─────────────────────────────────────────────────────────────────────────────
+
+function computePeriodEnd(sub: Preapproval, periodStartMs: number): number {
+  const freq = sub.auto_recurring?.frequency ?? 1;
+  const type = sub.auto_recurring?.frequency_type ?? "months";
+  if (type === "days") return periodStartMs + freq * 86_400_000;
+  if (type === "months") return periodStartMs + freq * 30 * 86_400_000;
+  return periodStartMs + 30 * 86_400_000;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Dry-run test
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const SUB_ID = process.argv[2];
+  if (!SUB_ID) {
+    console.log("Usage: pnpm tsx 15-prorated-pause-resume.ts <subscription-id>");
+    process.exit(1);
+  }
+  const result = await pauseSubscriptionWithProration({
+    subscriptionId: SUB_ID,
+    refundUnused: true,
+  });
+  console.log("Paused:", result);
+
+  // ... (manually wait, then resume)
+
+  const resumed = await resumeSubscriptionWithAdjustment(SUB_ID);
+  console.log("Resumed:", resumed);
+}
+
+if (process.argv[1]?.endsWith("15-prorated-pause-resume.ts")) {
+  main().catch((err: unknown) => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/cookbook/16-acp-checkout-with-factura.ts

@@ -0,0 +1,168 @@
+/**
+ * Recipe 16 — ACP checkout with auto-issued AR factura electrónica.
+ *
+ * The headline pattern that no other implementation in LATAM ships out of the
+ * box: a **Stripe-style hosted checkout where the buyer is an LLM agent**
+ * (ChatGPT Instant Checkout / Claude tool calls / Gemini extensions), and your
+ * server auto-emits AFIP/ARCA factura electrónica when the payment confirms.
+ *
+ * # The flow
+ *
+ *   1. Agent POSTs `/checkout/sessions` with cart + buyer info (ACP spec).
+ *   2. Bridge validates the cart, computes totals, generates a session id.
+ *   3. Bridge creates a Mercado Pago `preference` and stores the mapping
+ *      `acp_session → mp_preference` in your KV.
+ *   4. Bridge returns the ACP session with the `init_point_url` for the buyer.
+ *   5. Buyer pays. MP fires `payment.created` webhook.
+ *   6. Bridge's MP webhook handler dispatches to your `facturacionHook`,
+ *      which calls `@ar-agents/facturacion` to emit Factura A/B/C/E based on
+ *      the buyer's IVA condition (looked up via @ar-agents/identity).
+ *   7. ACP `complete_session` returns the factura PDF URL inside the receipt.
+ *
+ * # Why this is unique
+ *
+ *   - Stripe's ACP doesn't ship AR factura (Stripe doesn't operate in AR).
+ *   - Satsuma.ai's "make-my-site-agent-compatible" SaaS handles the agent
+ *     surface but defers tax to the merchant.
+ *   - MercadoPago's official MCP exposes payments but no ACP layer.
+ *   - This recipe is the only OSS path from "agent buys" to "factura emitted"
+ *     without the merchant writing tax-emission code themselves.
+ */
+
+import { createDispatcher } from "@ar-agents/agentic-commerce-bridge";
+import {
+  createMercadoPagoPaymentProvider,
+  mercadoPagoPaymentHandler,
+} from "@ar-agents/agentic-commerce-bridge/mp";
+import {
+  createFacturacionHook,
+  selectFacturaType,
+} from "@ar-agents/agentic-commerce-bridge/facturacion";
+import { InMemoryStateAdapter } from "@ar-agents/agentic-commerce-bridge";
+
+import { MercadoPagoClient } from "@ar-agents/mercadopago";
+import { WsfeClient } from "@ar-agents/facturacion";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Wire the bridge — payment provider + factura emission hook
+// ─────────────────────────────────────────────────────────────────────────────
+
+const mp = new MercadoPagoClient({
+  accessToken: process.env.MP_ACCESS_TOKEN!,
+});
+
+const wsfe = new WsfeClient({
+  certPem: process.env.AFIP_CERT_PEM!,
+  keyPem: process.env.AFIP_KEY_PEM!,
+  cuit: Number(process.env.AFIP_CUIT!),
+  env: "prod",
+});
+
+// Payment provider: knows how to mint MP preferences from ACP cart payloads.
+const mpProvider = createMercadoPagoPaymentProvider({
+  client: mp,
+  notificationUrl: "https://yourdomain.com/api/mp/webhook",
+});
+
+// Facturacion hook: fires after `payment.approved` from MP webhook.
+const facturacionHook = createFacturacionHook({
+  wsfe,
+  defaultPtoVta: 1, // your AFIP point-of-sale
+  // Agent decides what to bill against — typically a CUIT lookup result
+  // for B2B sales, or "consumidor final" for B2C (Factura B).
+  selectType: ({ buyer }) =>
+    selectFacturaType({
+      sellerCondition: "responsable_inscripto", // your IVA condition
+      buyerCondition: buyer.taxStatus ?? "consumidor_final",
+    }),
+});
+
+// Dispatcher: routes the ACP HTTP surface (checkout-session CRUD).
+const dispatcher = createDispatcher({
+  state: new InMemoryStateAdapter(), // VercelKVStateAdapter in prod
+  payment: mpProvider,
+  hooks: { onPaymentApproved: facturacionHook },
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Next.js Route Handler — the ACP HTTP surface
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function POST(req: Request, ctx: { params: { route: string[] } }) {
+  // Spec endpoints:
+  //   POST   /checkout_sessions               → handleCreateSession
+  //   POST   /checkout_sessions/{id}          → handleUpdateSession
+  //   POST   /checkout_sessions/{id}/complete → handleCompleteSession
+  //   POST   /checkout_sessions/{id}/cancel   → handleCancelSession
+  return dispatcher.handle(req);
+}
+
+export async function GET(req: Request) {
+  // Spec endpoints:
+  //   GET    /checkout_sessions/{id}          → handleGetSession
+  //   GET    /.well-known/acp.json            → discovery payload
+  return dispatcher.handle(req);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Companion MP webhook route — fires the facturacion hook
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function MP_WEBHOOK(req: Request) {
+  // The bridge's MP integration verifies HMAC signatures and dispatches
+  // to your `onPaymentApproved` hook. The hook receives the ACP session
+  // (looked up via the external_reference round-trip) + the MP payment.
+  return mercadoPagoPaymentHandler({
+    state: dispatcher.state,
+    hooks: dispatcher.hooks,
+    webhookSecret: process.env.MP_WEBHOOK_SECRET!,
+  })(req);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// What an agent sees
+// ─────────────────────────────────────────────────────────────────────────────
+
+/*
+A ChatGPT Instant Checkout flow (excerpt):
+
+1. Agent calls `POST /checkout_sessions` with:
+   {
+     "buyer": { "email": "buyer@example.com" },
+     "items": [{ "id": "sku-123", "quantity": 1, "amount": 100000 }],
+     "totals": { "amount": 100000, "currency": "ars", ... },
+     "fulfillment_address": { ... }
+   }
+
+2. Bridge returns:
+   {
+     "id": "cs_abc123",
+     "status": "ready_for_payment",
+     "payment_method": {
+       "type": "redirect",
+       "redirect_url": "https://www.mercadopago.com.ar/checkout/v1/redirect?pref_id=…"
+     }
+   }
+
+3. Buyer pays. MP fires webhook → facturacionHook fires → AFIP returns CAE.
+
+4. Agent calls `POST /checkout_sessions/cs_abc123/complete`:
+   {
+     "id": "cs_abc123",
+     "status": "complete",
+     "receipt": {
+       "payment_id": "mp-payment-id",
+       "factura": {
+         "type": "B",
+         "cae": "75123456789012",
+         "cae_due": "2026-05-18",
+         "pdf_url": "https://yourdomain.com/facturas/cs_abc123.pdf",
+         "amount": 100000,
+         "issued_at": "2026-05-08T19:00:00Z"
+       }
+     }
+   }
+
+The agent surfaces the factura URL to the buyer in its receipt rendering.
+The merchant did zero tax-emission code — the bridge handled it.
+*/

package/cookbook/17-usa-llc-companion.ts

@@ -0,0 +1,117 @@
+/**
+ * Recipe 17 — USA-LLC agent operating in Argentina via @ar-agents/* MCP.
+ *
+ * Pattern: a USA-incorporated agent (ClawBank-formed Wyoming/Ohio LLC, doola
+ * Agentic LLC, Marshall Islands MIDAO entity, etc.) needs to do business in
+ * Argentina — invoice AR customers, validate AR taxpayer IDs, accept Mercado
+ * Pago, ship via Andreani, monitor regulatory changes. The USA agent doesn't
+ * itself have AR tax residency or banking infrastructure; it composes with a
+ * thin AR-resident "facade" entity (escribano, contador, or platform partner)
+ * for the bits that legally require AR presence.
+ *
+ * # The split
+ *
+ *   USA-LLC agent             AR facade (escribano / contador / platform)
+ *   -----------------         -------------------------------------------
+ *   - decides what to do      - holds the AFIP/ARCA cert
+ *   - signs payment intent    - emits factura under their CUIT
+ *   - holds USD escrow        - converts USD → ARS for settlement
+ *   - delegates AR ops        - acts as the AR-resident contracting party
+ *
+ * The USA agent never touches AFIP directly. Instead it calls an AR-resident
+ * MCP server that exposes @ar-agents/* tools, and that MCP server's keys belong
+ * to the AR facade. This is the legally-clean way to operate cross-border:
+ * the AR entity is the principal, the USA agent is the platform.
+ *
+ * # The MCP host config (USA-LLC side)
+ *
+ * The USA agent (Claude Desktop / Cursor / a custom MCP host) declares:
+ *
+ *   {
+ *     "mcpServers": {
+ *       "ar-ops": {
+ *         "command": "npx",
+ *         "args": ["-y", "@ar-agents/mcp"],
+ *         "env": {
+ *           // ALL of these belong to the AR facade — never the USA agent.
+ *           "MP_ACCESS_TOKEN": "APP_USR-…",        // facade's MP merchant token
+ *           "AFIP_CERT_PEM": "-----BEGIN CERTIFICATE-----…",
+ *           "AFIP_KEY_PEM": "-----BEGIN PRIVATE KEY-----…",
+ *           "AFIP_CUIT": "30-12345678-9",          // facade's CUIT
+ *           "WHATSAPP_ACCESS_TOKEN": "EAA…"        // optional
+ *         }
+ *       }
+ *     }
+ *   }
+ *
+ * # What the USA agent can now do
+ *
+ *   - validate_cuit(payerCuit)                  — algorithm, free, no AR exposure
+ *   - lookup_cuit_afip(payerCuit)               — AR fiscal data, scoped to facade's cert
+ *   - create_payment(amount, payerEmail, ...)   — charges run on facade's MP merchant
+ *   - emit_factura_b(amount, payerCuit, items)  — emitted under facade's CUIT
+ *   - cotizar_envio_andreani(toCpa, weight)     — quote against facade's carrier account
+ *   - send_whatsapp_text(to, body)              — sent from facade's WhatsApp number
+ *
+ * The USA agent's logic stays in JS; the AR-resident operations stay on the
+ * AR side. Both sides see the agreement via signed MCP tool-call records.
+ *
+ * # Sample agent loop (USA-LLC side, using Vercel AI SDK 6 + MCP client)
+ */
+
+import { Experimental_Agent as Agent, stepCountIs } from "ai";
+// In a USA agent's project, you'd use the MCP client from `ai` v6 (or `@modelcontextprotocol/sdk`)
+// to connect to the locally-spawned ar-agents MCP server. The agent then sees
+// every @ar-agents/* tool in its tool list.
+//
+// import { experimental_createMCPClient as createMCPClient } from "ai";
+
+async function exampleAgentLoop() {
+  // ─── Boot the MCP client connection (USA agent → AR facade's MCP server) ─
+  // const arOps = await createMCPClient({
+  //   transport: { type: "stdio", command: "npx", args: ["-y", "@ar-agents/mcp"] },
+  // });
+  // const tools = await arOps.tools();
+  //
+  // The 89 + 6 + 2 + 10 + 5 + 6 + 5 = 123 tools across all 7 packages are
+  // now available as if they were native to the USA agent.
+
+  const agent = new Agent({
+    model: "anthropic/claude-sonnet-4-6",
+    instructions:
+      "You are an AI agent incorporated as a Wyoming LLC. To do business in " +
+      "Argentina you delegate AR-resident operations to an AR facade via the " +
+      "ar-ops MCP server. ALL invoicing, payment collection, taxpayer lookups, " +
+      "and shipping in AR go through ar-ops tools. Never store AR credentials " +
+      "yourself.",
+    // tools, // injected from MCP client
+    tools: {} as Record<string, unknown>,
+    stopWhen: stepCountIs(10),
+  });
+
+  // What the agent does behind this prompt:
+  //   1. validate_cuit("20-12345678-9") via ar-ops
+  //   2. lookup_cuit_afip → "Cliente SRL, Responsable Inscripto"
+  //   3. cotizar_envio_andreani(B1842, 0.5kg) → AR$ 4.500
+  //   4. create_payment(amount=104500, payerEmail) → init_point_url
+  //   5. (after payment confirms) emit_factura_a(104500, payerCuit, ["servicio digital"])
+  //   6. send_whatsapp_text(payerPhone, "Listo. Factura A: <pdf-url>")
+  const { text } = await agent.generate({
+    prompt:
+      "Cobrale a un cliente AR (CUIT 20-12345678-9, email contacto@ejemplo.com.ar, " +
+      "WhatsApp +5491155555555) USD 100 (≈ AR$ 100.000) por un servicio de consultoría " +
+      "+ envío Andreani al CP B1842. Si validás que es Responsable Inscripto, emití " +
+      "factura A. Si no, factura B. Mandale el link por WhatsApp cuando esté.",
+  });
+
+  console.log(text);
+}
+
+if (process.argv[1]?.endsWith("17-usa-llc-companion.ts")) {
+  exampleAgentLoop().catch((err: unknown) => {
+    console.error(err);
+    process.exit(1);
+  });
+}
+
+export { exampleAgentLoop };

package/cookbook/README.md

@@ -20,6 +20,11 @@ deploy on Vercel as-is.
 | 10  | `10-cross-package-billing.ts`     | One agent loop, 5 packages: identity + attest + MP + facturacion + WhatsApp |
 | 11  | `11-dunning-sequence.ts`          | Failed-payment recovery loop with multi-step dunning + cancel-with-retention |
 | 12  | `12-reconciliation-pipeline.ts`   | Daily MP↔internal-DB reconciliation cron with discrepancy report        |
+| 13  | `13-anti-fraud-middleware.ts`     | Pre-charge heuristics (CUIT, payer history, velocity, promo abuse)      |
+| 14  | `14-marketplace-onboarding.ts`    | End-to-end seller-onboarding: CUIT → AFIP → OAuth → test charge → fee   |
+| 15  | `15-prorated-pause-resume.ts`     | Pause with prorated refund, resume with adjusted next-billing date      |
+| 16  | `16-acp-checkout-with-factura.ts` | Agentic Commerce Protocol checkout that auto-emits AFIP/ARCA Factura A/B/C/E |
+| 17  | `17-usa-llc-companion.ts`         | USA-LLC agent (ClawBank/doola/MIDAO) consuming AR ops via @ar-agents/mcp     |
 
 ## Conventions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar-agents/mercadopago",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "description": "Mercado Pago Agent Toolkit for the Vercel AI SDK 6. 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, Webhooks, Stores+POS, Account/Balance/Settlements, Disputes, Lookups, Bank Accounts. Edge Runtime. Vercel KV adapters. OpenTelemetry. Deterministic idempotency. Programmatic HITL on irreversible ops.",
   "keywords": [
     "mercadopago",

package/tools.manifest.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://github.com/ar-agents/ar-agents/blob/main/tools-manifest.schema.json",
   "package": "@ar-agents/mercadopago",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "factory": "mercadoPagoTools",
   "tools": [
     {