@ar-agents/mercadopago 0.17.2 → 0.18.0

package/cookbook/20-multi-tenant-marketplace.ts

@@ -0,0 +1,274 @@
+/**
+ * Recipe 20 — Multi-tenant marketplace spawning vendor sociedades-IA.
+ *
+ * # Pattern
+ *
+ * A platform (think: Tienda Nube, Mercado Shops, an SaaS marketplace)
+ * onboards vendors who each need a thin AR-side legal entity to operate
+ * within Argentina's jurisdiction. Pre-sociedad-IA, this was a manual
+ * escribono job per vendor. With `@ar-agents/incorporate`, the platform
+ * can spawn a fresh sociedad-IA spec on-demand at vendor sign-up — one
+ * API call, the vendor's deploy URL is materialized, the platform
+ * tracks the audit log per tenant.
+ *
+ * # When to use
+ *
+ * - Vertical SaaS where each vendor needs their own AR fiscal identity
+ *   (factura emission under their CUIT, not the platform's).
+ * - Marketplaces that scale to hundreds of vendors and can't manually
+ *   coordinate escribano + contador per spawn.
+ * - Cross-jurisdictional plays: a USA platform onboarding AR sellers who
+ *   need a properly-incorporated sociedad to receive Mercado Pago.
+ *
+ * # Architecture
+ *
+ *      Platform                       /api/auto-incorporate
+ *      ┌──────────┐    POST            ┌────────────────┐
+ *      │ vendor   │  ─────────────▶    │ ar-agents      │
+ *      │ signup   │  with vendor       │ generates spec │
+ *      │ flow     │  details + a       │ + signs audit  │
+ *      └──────────┘  per-vendor        │ entry under    │
+ *           │        sessionId         │ vendor's id    │
+ *           ▼                          └────────────────┘
+ *      ┌──────────┐                           │
+ *      │ Vercel   │  one-click deploy URL ◀───┘
+ *      │ deploy   │
+ *      └──────────┘
+ *           │
+ *           ▼
+ *      ┌──────────┐    GET /api/play/audit/{tenantId}?verify=1
+ *      │ ops      │  ◀──────────────────────────────────────┐
+ *      │ dash     │                                         │
+ *      └──────────┘                                         │
+ *           │                                               │
+ *           ▼ (recipe 19 cron)                              │
+ *      compliance digest per tenant ──────────────────────┘
+ *
+ * # Idempotency
+ *
+ * Calling /api/auto-incorporate with the same input + sessionId twice
+ * is idempotent on the spec output but writes two audit entries (one per
+ * call). For exact-once semantics, dedupe on the platform side keyed by
+ * (vendor_id, sociedad_denominacion). The audit log will show both
+ * attempts which is the more honest signal anyway.
+ *
+ * # Edge Runtime
+ *
+ * Yes — the @ar-agents/incorporate client is fetch-only.
+ */
+
+import {
+  incorporate,
+  fetchAudit,
+  type IncorporateInput,
+  type IncorporateSuccess,
+} from "@ar-agents/incorporate";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Platform's vendor model
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface Vendor {
+  id: string; // platform's internal vendor id
+  legalName: string;
+  representanteName: string;
+  representanteCuit: string;
+  contactEmail: string;
+  /** What the vendor sells. Used as the seed for objeto social. */
+  category: "software" | "services" | "products" | "ecommerce";
+  expectedMonthlyRevenueArs: number;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Spawn a sociedad-IA for a vendor at sign-up
+// ─────────────────────────────────────────────────────────────────────────────
+
+const OBJETO_BY_CATEGORY: Record<Vendor["category"], string> = {
+  software:
+    "Desarrollo y comercialización de software propio para empresas y consumidores en Argentina, incluyendo pero no limitándose a aplicaciones web, móviles y servicios cloud.",
+  services:
+    "Prestación de servicios profesionales digitales (consultoría, desarrollo, marketing, atención al cliente) a empresas y consumidores en territorio argentino.",
+  products:
+    "Comercialización mayorista y minorista de productos físicos y digitales propios y de terceros, incluyendo importación, almacenamiento, marketing y logística en Argentina.",
+  ecommerce:
+    "Operación de tiendas online y marketplaces para la venta de productos y servicios al consumidor final argentino, incluyendo procesamiento de pagos y logística.",
+};
+
+/**
+ * The platform's tenantId for this vendor's sociedad-IA. Becomes the
+ * sessionId for the entire forensic timeline (incorporation + ongoing
+ * tool calls). Pick something stable + opaque — UUID v4 or a hashed
+ * concatenation of vendor_id + a per-platform secret.
+ */
+function tenantSessionIdFor(vendor: Vendor): string {
+  // For the cookbook, derive deterministically. In production, prefer
+  // crypto.randomUUID() per tenant to avoid leaking enumerable ids.
+  return `tenant-${vendor.id.replace(/[^A-Za-z0-9_-]/g, "-").slice(0, 56)}`;
+}
+
+export async function spawnVendorSociedad(vendor: Vendor): Promise<IncorporateSuccess> {
+  const sessionId = tenantSessionIdFor(vendor);
+
+  // Pieza selection driven by vendor profile.
+  const piezas: IncorporateInput["piezas"] = [
+    "identity",
+    "gde-tad",
+    "mercadopago",
+    "banking",
+    "facturacion",
+    "boletin-oficial",
+    "igj",
+  ];
+  if (vendor.category === "ecommerce" || vendor.category === "products") {
+    piezas.push("shipping");
+  }
+  if (vendor.expectedMonthlyRevenueArs > 1_000_000) {
+    // Large-revenue tenants need WhatsApp customer-comms + ACP for LLM-buyer
+    // checkout. Smaller tenants can stay lean.
+    piezas.push("whatsapp", "agentic-commerce-bridge", "ap2");
+  }
+
+  // Capital social: SAS minimum is 100k. Bump for large-revenue vendors so
+  // BCRA and downstream banks don't flag the disparity later.
+  const capitalSocial =
+    vendor.expectedMonthlyRevenueArs > 1_000_000 ? 500_000 : 200_000;
+
+  const input: IncorporateInput = {
+    denominacion: `${vendor.legalName} SAS`,
+    tipo: "SAS", // SOCIEDAD-IA when the regime ships
+    capitalSocial,
+    objeto: OBJETO_BY_CATEGORY[vendor.category],
+    representante: {
+      nombre: vendor.representanteName,
+      cuit: vendor.representanteCuit,
+    },
+    emailContacto: vendor.contactEmail,
+    piezas,
+    sessionId,
+  };
+
+  const result = await incorporate(input);
+
+  if (!result.ok) {
+    // Pre-flight failure — surface the findings + reject the signup.
+    const errors = result.validation.findings
+      .filter((f) => f.severity === "error")
+      .map((f) => `${f.field}: ${f.message}`);
+    throw new Error(
+      `Vendor signup rejected at IGJ pre-flight: ${errors.join("; ")}`,
+    );
+  }
+  return result;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Platform's spawn flow: handle a fresh signup
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface SignupRecord {
+  vendorId: string;
+  tenantSessionId: string;
+  slug: string;
+  deployUrl: string;
+  auditDashboardUrl: string;
+  auditVerifyUrl: string;
+  badgeSvgUrl: string;
+  createdAt: string;
+}
+
+/**
+ * Persist this in the platform's vendor table (Postgres / KV / whatever).
+ * The badge SVG URL is what you embed in the vendor's profile page so any
+ * visitor sees their "verified · N/M" forensic-clean status.
+ */
+function recordFor(
+  vendor: Vendor,
+  result: IncorporateSuccess,
+): SignupRecord {
+  return {
+    vendorId: vendor.id,
+    tenantSessionId: result.audit.sessionId,
+    slug: result.sociedad.slug,
+    deployUrl: result.deploy.oneClickUrl,
+    auditDashboardUrl: result.audit.dashboardUrl,
+    auditVerifyUrl: result.audit.verifyUrl,
+    badgeSvgUrl: `https://ar-agents.ar/api/badge/${result.audit.sessionId}`,
+    createdAt: new Date().toISOString(),
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Periodic compliance digest per tenant (recipe 19 in a fan-out loop)
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface TenantHealth {
+  vendorId: string;
+  totalEvents: number;
+  tampered: number;
+  hmacWired: boolean;
+  alert: string | null;
+}
+
+export async function platformComplianceSweep(
+  records: SignupRecord[],
+): Promise<TenantHealth[]> {
+  const results: TenantHealth[] = [];
+  for (const r of records) {
+    const audit = (await fetchAudit(r.tenantSessionId, { verify: true })) as {
+      count: number;
+      verification?: { tampered: number; verified: number; total: number; hmacWired: boolean };
+    };
+    const v = audit.verification ?? { tampered: 0, verified: 0, total: 0, hmacWired: false };
+    let alert: string | null = null;
+    if (!v.hmacWired) alert = "HMAC not wired in deploy — log unverified.";
+    else if (v.tampered > 0)
+      alert = `Tampering detected on tenant ${r.vendorId}: ${v.tampered} entries.`;
+    results.push({
+      vendorId: r.vendorId,
+      totalEvents: audit.count,
+      tampered: v.tampered,
+      hmacWired: v.hmacWired,
+      alert,
+    });
+  }
+  return results;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Example: signup + initial audit verify
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function main() {
+  // 1. New vendor signs up on the platform.
+  const vendor: Vendor = {
+    id: "v_42",
+    legalName: "Berreta Software",
+    representanteName: "Pérez, Juan",
+    representanteCuit: "20-12345678-9",
+    contactEmail: "ops@berreta.example",
+    category: "software",
+    expectedMonthlyRevenueArs: 800_000,
+  };
+
+  // 2. Spawn the sociedad-IA spec.
+  const result = await spawnVendorSociedad(vendor);
+  const record = recordFor(vendor, result);
+
+  console.log("Vendor onboarded:", record);
+
+  // 3. Verify the signup audit entry was actually written + signed.
+  const sweep = await platformComplianceSweep([record]);
+  console.log("Initial compliance sweep:", sweep);
+
+  // 4. Embed the badge in the vendor's profile page in the platform UI.
+  console.log("Badge URL for vendor profile:", record.badgeSvgUrl);
+}
+
+if (typeof require !== "undefined" && require.main === module) {
+  main().catch((err) => {
+    console.error("Recipe 20 failed:", err);
+    process.exit(1);
+  });
+}
+
+export { main };

package/cookbook/21-cross-jurisdictional-ap2.ts

@@ -0,0 +1,298 @@
+/**
+ * Recipe 21 — Cross-jurisdictional commerce w/ AP2 mandate verification.
+ *
+ * # Pattern
+ *
+ * A USA-LLC agent (e.g., a Wyoming DAO LLC operating an Etsy-style
+ * marketplace) wants to sell to AR consumers via MP, but doesn't have AR
+ * fiscal residency. The AR-side is a sociedad-IA (or pre-launch SAS) that
+ * (a) issues factura A/B/C to the AR consumer, (b) cobra MP, (c) settles
+ * inter-entity to the USA-LLC weekly.
+ *
+ * Each cross-entity transaction is gated by an AP2 (Google Agent Payments
+ * Protocol) mandate the USA-LLC signs and the AR sociedad verifies before
+ * acting. This is what RFC-001 § 7 sketches as the contract surface for
+ * "agent commerce that crosses jurisdictions".
+ *
+ * The mandate has 3 critical fields:
+ *   - issuer: USA-LLC's stable identifier (DID, DAO LLC EIN, etc.)
+ *   - subject: the AR sociedad's CUIT
+ *   - claims: { action: "factura.emit", amount, currency: "ARS",
+ *               consumer: { dni, email }, allowance: { capPerMonth, capPerOp } }
+ *
+ * Verification:
+ *   1. AP2 verify chain — JWS ES256 signature against the issuer's pinned key.
+ *   2. Mandate hasn't expired (`exp` claim).
+ *   3. Operation respects the cap (cumulative against the audit log).
+ *   4. Consumer-side checks (CUIT validity, BCRA situation if amount large).
+ *
+ * If any check fails, the AR sociedad refuses + logs the refusal in the
+ * audit log. RFC-001 § 9.2 makes that audit entry probative — the USA-LLC
+ * can later challenge "you said no, prove the rule".
+ *
+ * # Edge Runtime
+ *
+ * Yes — @ar-agents/ap2 + @ar-agents/incorporate are both fetch-only.
+ * Verification uses Web Crypto's verify() against the issuer's pinned JWK.
+ *
+ * # Production caveats
+ *
+ * - The AR sociedad MUST emit the factura under its own CUIT, not the
+ *   USA-LLC's. Cross-CUIT factura is not legal in AR.
+ * - Settlement between entities is an SLA between the operator and the
+ *   USA-LLC. The toolkit doesn't dictate the cadence; recipe 22 (planned)
+ *   covers nightly reconciliation.
+ * - For amounts > certain BCRA thresholds, AR sociedad needs to hold
+ *   funds for ~2 days while AFIP IBPP processes. The agent should surface
+ *   this to the consumer at checkout.
+ */
+
+import { fetchAudit } from "@ar-agents/incorporate";
+import { verifyMandate, type Mandate } from "@ar-agents/ap2";
+import {
+  identityTools,
+  UnconfiguredAfipPadronAdapter,
+} from "@ar-agents/identity";
+import { facturacionTools } from "@ar-agents/facturacion";
+import { bankingTools } from "@ar-agents/banking";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Mandate the USA-LLC sends to the AR sociedad
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface CrossJurisdictionalClaims {
+  action: "factura.emit" | "mp.charge" | "shipment.create";
+  amountArs: number;
+  currency: "ARS";
+  consumer: { cuit: string; email: string };
+  allowance: {
+    capPerOpArs: number;
+    capPerMonthArs: number;
+  };
+  /** ISO 8601. Mandate expires here. */
+  exp: string;
+  /** USA-LLC's transaction reference for reconciliation. */
+  externalId: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AR sociedad's verify-then-act handler
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface VerifyAndActOptions {
+  /**
+   * The AR sociedad's audit-log session id. All operations under this
+   * mandate land in the same forensic timeline.
+   */
+  sessionId: string;
+  /**
+   * The USA-LLC's JWK that issued the mandate. In production: pinned
+   * via the platform's vendor table.
+   */
+  issuerJwk: JsonWebKey;
+  /** The mandate the USA-LLC delivered. */
+  mandate: Mandate<CrossJurisdictionalClaims>;
+}
+
+interface ActResult {
+  ok: boolean;
+  reason?: string;
+  facturaCae?: string;
+  auditDashboardUrl: string;
+}
+
+export async function verifyAndAct(
+  options: VerifyAndActOptions,
+): Promise<ActResult> {
+  const { sessionId, issuerJwk, mandate } = options;
+
+  // ─── 1. Verify the AP2 mandate ──────────────────────────────────────
+  const verification = await verifyMandate(mandate, { issuerJwk });
+  if (!verification.valid) {
+    return {
+      ok: false,
+      reason: `Mandate verification failed: ${verification.reason}`,
+      auditDashboardUrl: `https://ar-agents.ar/dashboard/${sessionId}`,
+    };
+  }
+
+  // ─── 2. Expiry check ────────────────────────────────────────────────
+  if (Date.parse(mandate.claims.exp) < Date.now()) {
+    return {
+      ok: false,
+      reason: "Mandate expired (exp claim in the past)",
+      auditDashboardUrl: `https://ar-agents.ar/dashboard/${sessionId}`,
+    };
+  }
+
+  // ─── 3. Per-op cap ──────────────────────────────────────────────────
+  if (mandate.claims.amountArs > mandate.claims.allowance.capPerOpArs) {
+    return {
+      ok: false,
+      reason: `Amount $${mandate.claims.amountArs} exceeds per-op cap $${mandate.claims.allowance.capPerOpArs}.`,
+      auditDashboardUrl: `https://ar-agents.ar/dashboard/${sessionId}`,
+    };
+  }
+
+  // ─── 4. Cumulative cap (querying the audit log) ─────────────────────
+  // Pull this month's prior emissions on the same sessionId + sum.
+  const audit = (await fetchAudit(sessionId, { verify: false })) as {
+    entries: Array<{
+      tool: string;
+      ts: string;
+      input: { amountArs?: number; externalId?: string };
+    }>;
+  };
+  const monthStart = new Date();
+  monthStart.setDate(1);
+  monthStart.setHours(0, 0, 0, 0);
+  const cumulative = audit.entries
+    .filter(
+      (e) =>
+        e.tool === "cross_jurisdictional_factura_emit" &&
+        Date.parse(e.ts) >= monthStart.getTime(),
+    )
+    .reduce((sum, e) => sum + (e.input.amountArs ?? 0), 0);
+
+  if (cumulative + mandate.claims.amountArs > mandate.claims.allowance.capPerMonthArs) {
+    return {
+      ok: false,
+      reason: `Cumulative monthly emissions ($${cumulative} + $${mandate.claims.amountArs}) exceed cap $${mandate.claims.allowance.capPerMonthArs}.`,
+      auditDashboardUrl: `https://ar-agents.ar/dashboard/${sessionId}`,
+    };
+  }
+
+  // ─── 5. Idempotency: did we already process this externalId? ────────
+  if (
+    audit.entries.some(
+      (e) =>
+        e.tool === "cross_jurisdictional_factura_emit" &&
+        e.input.externalId === mandate.claims.externalId,
+    )
+  ) {
+    return {
+      ok: false,
+      reason: `externalId ${mandate.claims.externalId} already processed (idempotency).`,
+      auditDashboardUrl: `https://ar-agents.ar/dashboard/${sessionId}`,
+    };
+  }
+
+  // ─── 6. Validate the consumer's CUIT ────────────────────────────────
+  // (Real prod would have an AfipPadronAdapter wired — using the
+  // unconfigured shim here just to demonstrate the flow.)
+  const idTools = identityTools({ afip: new UnconfiguredAfipPadronAdapter() });
+  const cuitCheck = await idTools.validate_cuit.execute({
+    cuit: mandate.claims.consumer.cuit,
+  });
+  if (!cuitCheck.valid) {
+    return {
+      ok: false,
+      reason: `Consumer CUIT ${mandate.claims.consumer.cuit} is malformed.`,
+      auditDashboardUrl: `https://ar-agents.ar/dashboard/${sessionId}`,
+    };
+  }
+
+  // ─── 7. For amounts above $500k ARS, BCRA credit-situation check ────
+  if (mandate.claims.amountArs > 500_000) {
+    const bk = bankingTools();
+    // In production this hits BCRA Central de Deudores for real; mock here.
+    const credit = await bk.lookup_credit_situation.execute({
+      cuit: mandate.claims.consumer.cuit,
+    });
+    if (
+      credit.available === false ||
+      (credit.worstSituation && credit.worstSituation > 2)
+    ) {
+      return {
+        ok: false,
+        reason: `Consumer has BCRA situation ${credit.worstSituation} (>2 = high risk).`,
+        auditDashboardUrl: `https://ar-agents.ar/dashboard/${sessionId}`,
+      };
+    }
+  }
+
+  // ─── 8. Emit the factura ────────────────────────────────────────────
+  // (Real prod requires AFIP cert; using mock returns CAE here.)
+  const fact = facturacionTools();
+  // Note: in real code, you'd select cbteTipo ("FACTURA_B" for
+  // CONSUMIDOR_FINAL etc.) based on AFIP padron lookup of the consumer.
+  // Demo just hardcodes Factura B + 21% IVA.
+  const result = await fact.crear_factura.execute({
+    cbteTipo: "FACTURA_B",
+    docTipo: "CUIT",
+    docNro: mandate.claims.consumer.cuit,
+    impTotal: mandate.claims.amountArs,
+    impNeto: Math.round(mandate.claims.amountArs / 1.21),
+    impIVA: mandate.claims.amountArs - Math.round(mandate.claims.amountArs / 1.21),
+  });
+
+  // ─── 9. Audit log entry happens automatically via the tool wrapper.
+  //       Surface the result + dashboard URL for the USA-LLC's records.
+
+  return {
+    ok: true,
+    facturaCae: result.cae ?? undefined,
+    auditDashboardUrl: `https://ar-agents.ar/dashboard/${sessionId}`,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Example: handle a cross-jurisdictional factura request
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const sessionId = "tenant-clawbank-llc-ar"; // pinned per USA-LLC tenant
+
+  // Mandate the USA-LLC produced (signed JWS; pretend it's already verified
+  // structurally — in real code, JWS parsing happens inside verifyMandate).
+  const mandate = {
+    issuer: "wyoming-dao-llc:claw-bank",
+    subject: "ar-sociedad:30123456789",
+    claims: {
+      action: "factura.emit" as const,
+      amountArs: 75_000,
+      currency: "ARS" as const,
+      consumer: { cuit: "20-12345678-9", email: "consumidor@example.com" },
+      allowance: {
+        capPerOpArs: 100_000,
+        capPerMonthArs: 2_000_000,
+      },
+      exp: new Date(Date.now() + 3600 * 1000).toISOString(),
+      externalId: "claw-bank:tx_42",
+    },
+    signature: "<JWS-ES256-signature>", // produced by USA-LLC
+  } as unknown as Mandate<CrossJurisdictionalClaims>;
+
+  // The USA-LLC's pinned issuer key. In production: pulled from the
+  // platform's vendor table at signup time.
+  const issuerJwk: JsonWebKey = {
+    kty: "EC",
+    crv: "P-256",
+    x: "<base64url-x>",
+    y: "<base64url-y>",
+  };
+
+  const result = await verifyAndAct({ sessionId, issuerJwk, mandate });
+
+  if (!result.ok) {
+    console.error("Refused:", result.reason);
+    console.error("Audit dashboard:", result.auditDashboardUrl);
+    process.exit(0);
+  }
+
+  console.log("Factura emitted:", result.facturaCae);
+  console.log("Audit dashboard:", result.auditDashboardUrl);
+  console.log(
+    "Settlement reference:",
+    `clawbank-llc:${mandate.claims.externalId}`,
+  );
+}
+
+if (typeof require !== "undefined" && require.main === module) {
+  main().catch((err) => {
+    console.error("Recipe 21 failed:", err);
+    process.exit(1);
+  });
+}
+
+export { main };