@ar-agents/mercadopago 0.17.1 → 0.17.2

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 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

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

@@ -23,6 +23,8 @@ deploy on Vercel as-is.
 | 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.1",
+  "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.1",
+  "version": "0.17.2",
   "factory": "mercadoPagoTools",
   "tools": [
     {