@ar-agents/mercadopago 0.16.0 → 0.17.1

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # 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
+
+- Add `mercadopago doctor` CLI for environment diagnosis.
+
+  ```bash
+  npx @ar-agents/mercadopago doctor
+  pnpm exec mercadopago doctor
+  ```
+
+  Reports:
+
+  - Node version (must be ≥ 20)
+  - `MP_ACCESS_TOKEN` presence + format + sandbox/prod prefix detection
+  - Live token validation against `GET /users/me` (free, no charge)
+  - `NEXT_PUBLIC_BACK_URL` presence + HTTPS check (MP rejects localhost server-side)
+  - `MP_WEBHOOK_SECRET` presence + length sanity
+  - Peer-dependency installation: `ai`, `zod`, `@vercel/kv`, `@opentelemetry/api`
+  - Tool count grouped by inferred category (auto-derived from `tools.manifest.json`)
+  - The 8 irreversible ops gated by `requireConfirmation()`
+
+  Pass `--probe` to additionally dry-call `validate_tax_id` against your sandbox token (also free):
+
+  ```bash
+  npx @ar-agents/mercadopago doctor --probe
+  ```
+
+  Exit codes follow the convention: `0` = ok or warn-only, `1` = at least one fail. CI scripts can `npx @ar-agents/mercadopago doctor` to gate deploys on having credentials wired up.
+
+  Also exposes `mercadopago help` and `mercadopago version`. Output respects `NO_COLOR`.
+
+  10 new subprocess tests (test/cli.test.ts), 328 tests total.
+
 ## 0.16.0
 
 ### Minor Changes

package/README.md

@@ -95,6 +95,14 @@ console.log(result.text);
 //    https://www.mercadopago.com.ar/subscriptions/checkout?preapproval_id=..."
 ```
 
+## Diagnose your setup
+
+```bash
+npx @ar-agents/mercadopago doctor
+```
+
+Validates `MP_ACCESS_TOKEN` against the live API, checks peer deps, lists all 89 tools, surfaces the 8 irreversible operations gated by `requireConfirmation`, and warns on common misconfigurations (missing `NEXT_PUBLIC_BACK_URL`, non-HTTPS back URL, suspiciously short webhook secret, trailing-newline tokens). Pass `--probe` to also dry-call `validate_tax_id` against your sandbox. CI-friendly exit codes (`0` ok, `1` fail).
+
 ## Webhooks
 
 MP notifies your endpoint whenever a subscription's status changes. The

package/bin/mercadopago.js

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

package/cookbook/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,
+  });
+}