@ar-agents/mercadopago 0.17.0 → 0.17.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 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/README.md

@@ -20,6 +20,9 @@ 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      |
 
 ## Conventions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar-agents/mercadopago",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "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.1",
   "factory": "mercadoPagoTools",
   "tools": [
     {