@ar-agents/mercadopago 0.17.1 → 0.18.0

package/cookbook/19-forensic-compliance-dashboard.ts

@@ -0,0 +1,320 @@
+/**
+ * Recipe 19 — Forensic-grade compliance dashboard powered by the
+ * `/api/play/audit/{sessionId}` endpoint.
+ *
+ * Every operator running an Argentine sociedad-IA accumulates an
+ * append-only HMAC-signed audit log under a sessionId. RFC-001 § 9.2
+ * makes that log legally probative — but "legally probative" only
+ * matters if a regulator can actually inspect it. This recipe is the
+ * compliance-side companion: a Node.js process that ingests audit
+ * entries on a schedule, checks for tampering, and routes alerts to
+ * the operator's SOC + the contador's monthly summary.
+ *
+ * # Pattern
+ *
+ * 1. Pull the latest audit entries via `fetchAudit(sessionId, { verify: true })`
+ *    from `@ar-agents/incorporate` — same primitives the incorporation flow uses.
+ * 2. Reconcile the verified count + tampered count + entry count against
+ *    expected ranges. Tampering immediately escalates.
+ * 3. Bucket entries by tool, governance class, and durationMs to surface
+ *    operational anomalies (e.g., a `crear_factura` tool started running
+ *    in 12s instead of <1s — that's an AFIP slowdown worth noting).
+ * 4. Stream a daily digest to the contador (Slack, email, WhatsApp)
+ *    summarizing volume + categories + any anomalies.
+ *
+ * # When to use
+ *
+ * - Multi-tenant marketplace operating many sociedades-IA, one audit log
+ *   per tenant. Daily compliance roll-up scales linearly.
+ * - Regulated SaaS where the audit log is contractually required to be
+ *   monitored, not just retained.
+ * - Periodic third-party audit cycles where the auditor wants a
+ *   reproducible forensic report (the JSON returned by `?verify=1` is
+ *   already that report).
+ *
+ * # Edge Runtime
+ *
+ * Yes. The client is fetch-based, zero deps. Schedule via Vercel Cron
+ * (`vercel.json → crons`) or Cloudflare Workers Cron Triggers — either
+ * works.
+ *
+ * # Production-only assertions
+ *
+ * The audit log is HMAC-signed with `AUDIT_HMAC_SECRET` server-side.
+ * The verifier here delegates to `?verify=1` (so the secret never
+ * leaves the server) but the consumer can independently re-verify by
+ * re-implementing the canonical-JSON + HMAC check. The agent endpoint
+ * uses constant-time comparison; the read endpoint exposes per-entry
+ * hmac so external libraries can recompute.
+ */
+
+import { fetchAudit } from "@ar-agents/incorporate";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface AuditEntry {
+  id: string;
+  sessionId: string;
+  ts: string; // ISO 8601
+  tool: string;
+  governance:
+    | "algorithm-only"
+    | "audit-logged"
+    | "mocked-upstream"
+    | "requires-confirmation";
+  input: unknown;
+  output?: unknown;
+  errored?: boolean;
+  durationMs?: number;
+  hmac: string | null;
+}
+
+interface AuditEnvelope {
+  sessionId: string;
+  backend: "vercel-kv" | "in-memory";
+  count: number;
+  entries: AuditEntry[];
+  verification?: {
+    total: number;
+    verified: number;
+    tampered: number;
+    hmacWired: boolean;
+  };
+}
+
+interface DailyDigest {
+  sessionId: string;
+  generatedAt: string;
+  rangeStart: string;
+  rangeEnd: string;
+  totals: { all: number; errored: number; byGovernance: Record<string, number> };
+  byTool: Record<string, { count: number; avgDurationMs: number; errors: number }>;
+  anomalies: string[];
+  /** Highest-priority issue. If null, the day is clean. */
+  alert: { severity: "tampered" | "performance" | "errors"; message: string } | null;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Core: pull + verify + bucket
+// ─────────────────────────────────────────────────────────────────────────────
+
+const PERFORMANCE_THRESHOLDS_MS: Record<string, number> = {
+  // Per-tool latency expectations. If an entry's durationMs exceeds 4× this,
+  // the operator gets pinged. Numbers are heuristic — replace with your
+  // observed p95 from /api/play/audit/* over the last 30 days.
+  validate_cuit: 50,
+  validate_cbu: 50,
+  validate_solicitar_cae: 50,
+  validate_igj_inscription: 100,
+  lookup_cuit_afip: 1500,
+  lookup_credit_situation: 1200,
+  get_usd_oficial: 800,
+  bo_today: 2000,
+  igj_get_entity: 1200,
+  list_domicilio_inbox: 1500,
+  crear_factura: 3000,
+  send_whatsapp_text: 800,
+  mp_create_subscription: 1500,
+  auto_incorporate: 200,
+};
+
+export async function buildDailyDigest(
+  sessionId: string,
+  options: { rangeStart?: Date; rangeEnd?: Date; baseUrl?: string } = {},
+): Promise<DailyDigest> {
+  const rangeEnd = options.rangeEnd ?? new Date();
+  const rangeStart = options.rangeStart ?? new Date(rangeEnd.getTime() - 86_400_000);
+
+  const raw = (await fetchAudit(sessionId, {
+    verify: true,
+    baseUrl: options.baseUrl,
+  })) as AuditEnvelope;
+
+  // Bucket entries to the requested range (24h default).
+  const inRange = raw.entries.filter((e) => {
+    const t = Date.parse(e.ts);
+    return t >= rangeStart.getTime() && t < rangeEnd.getTime();
+  });
+
+  const totals = {
+    all: inRange.length,
+    errored: inRange.filter((e) => e.errored).length,
+    byGovernance: groupCount(inRange, (e) => e.governance),
+  };
+
+  const byTool: Record<
+    string,
+    { count: number; avgDurationMs: number; errors: number }
+  > = {};
+  for (const e of inRange) {
+    const slot = (byTool[e.tool] ??= { count: 0, avgDurationMs: 0, errors: 0 });
+    slot.count++;
+    if (e.errored) slot.errors++;
+    if (typeof e.durationMs === "number") {
+      // running mean
+      slot.avgDurationMs =
+        (slot.avgDurationMs * (slot.count - 1) + e.durationMs) / slot.count;
+    }
+  }
+
+  const anomalies: string[] = [];
+
+  // 1. Tampering — highest-severity escalation.
+  const tampered = raw.verification?.tampered ?? 0;
+  const hmacWired = raw.verification?.hmacWired ?? false;
+  if (!hmacWired) {
+    anomalies.push(
+      "AUDIT_HMAC_SECRET no está cableado en el deploy — el log no está firmado.",
+    );
+  }
+  if (tampered > 0) {
+    anomalies.push(
+      `${tampered} entrada${tampered === 1 ? "" : "s"} con tampering detectado en la sesión completa.`,
+    );
+  }
+
+  // 2. Performance — flag tools whose avg latency is 4× threshold.
+  for (const [tool, slot] of Object.entries(byTool)) {
+    const threshold = PERFORMANCE_THRESHOLDS_MS[tool];
+    if (threshold && slot.avgDurationMs > threshold * 4 && slot.count > 1) {
+      anomalies.push(
+        `${tool}: avg ${Math.round(slot.avgDurationMs)}ms (esperado <${threshold * 4}ms) en ${slot.count} llamadas.`,
+      );
+    }
+  }
+
+  // 3. Error rate — flag tools above 5% error rate over 10+ calls.
+  for (const [tool, slot] of Object.entries(byTool)) {
+    if (slot.count >= 10 && slot.errors / slot.count > 0.05) {
+      anomalies.push(
+        `${tool}: ${slot.errors}/${slot.count} (${Math.round((slot.errors / slot.count) * 100)}%) errores.`,
+      );
+    }
+  }
+
+  // Pick the highest-severity alert.
+  let alert: DailyDigest["alert"] = null;
+  if (tampered > 0) {
+    alert = {
+      severity: "tampered",
+      message: `URGENTE: ${tampered} entrada(s) con tampering detectado en la sesión ${sessionId}. Investigar acceso al audit log.`,
+    };
+  } else if (totals.errored / Math.max(totals.all, 1) > 0.1 && totals.all > 10) {
+    alert = {
+      severity: "errors",
+      message: `Tasa de error del día (${totals.errored}/${totals.all}) supera el 10%.`,
+    };
+  } else if (anomalies.some((a) => a.includes("avg"))) {
+    alert = {
+      severity: "performance",
+      message: anomalies.find((a) => a.includes("avg")) ?? "Performance anomaly",
+    };
+  }
+
+  return {
+    sessionId,
+    generatedAt: new Date().toISOString(),
+    rangeStart: rangeStart.toISOString(),
+    rangeEnd: rangeEnd.toISOString(),
+    totals,
+    byTool,
+    anomalies,
+    alert,
+  };
+}
+
+function groupCount<T>(arr: T[], key: (v: T) => string): Record<string, number> {
+  const out: Record<string, number> = {};
+  for (const v of arr) {
+    const k = key(v);
+    out[k] = (out[k] ?? 0) + 1;
+  }
+  return out;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Sink: contador's monthly summary
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Render a digest as a readable Spanish-language summary the contador
+ * can paste into a monthly compliance report. Structurally similar to
+ * a balance summary — totals + observations.
+ */
+export function renderForContador(digest: DailyDigest): string {
+  const date = digest.rangeEnd.slice(0, 10);
+  const lines: string[] = [
+    `RESUMEN AUDITORÍA · ${date}`,
+    `Sesión: ${digest.sessionId}`,
+    "",
+    "TOTALES",
+    `  Tool calls: ${digest.totals.all}`,
+    `  Errores: ${digest.totals.errored}`,
+    "",
+    "POR CLASE DE GOVERNANCE",
+  ];
+  for (const [k, v] of Object.entries(digest.totals.byGovernance)) {
+    lines.push(`  ${k}: ${v}`);
+  }
+  lines.push("", "POR TOOL");
+  const sorted = Object.entries(digest.byTool).sort(
+    ([, a], [, b]) => b.count - a.count,
+  );
+  for (const [tool, slot] of sorted) {
+    lines.push(
+      `  ${tool}: ${slot.count} llamadas (avg ${Math.round(slot.avgDurationMs)}ms${slot.errors ? `, ${slot.errors} errores` : ""})`,
+    );
+  }
+  if (digest.anomalies.length > 0) {
+    lines.push("", "ANOMALÍAS");
+    for (const a of digest.anomalies) lines.push(`  - ${a}`);
+  }
+  if (digest.alert) {
+    lines.push(
+      "",
+      `ALERTA [${digest.alert.severity.toUpperCase()}]`,
+      `  ${digest.alert.message}`,
+    );
+  }
+  return lines.join("\n");
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Cron entrypoint (drop in /api/cron/compliance-digest in your Next.js app)
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function main(sessionId: string) {
+  const digest = await buildDailyDigest(sessionId);
+
+  // 1. Always log the structured digest for the operator's metrics pipeline.
+  console.log(JSON.stringify(digest));
+
+  // 2. Render a contador-friendly summary for the monthly compliance report.
+  console.log(renderForContador(digest));
+
+  // 3. Escalate on tampering or high error rate. In production, replace
+  //    these console.warn calls with WhatsApp template / email / PagerDuty.
+  if (digest.alert) {
+    console.warn(`ESCALATE [${digest.alert.severity}]: ${digest.alert.message}`);
+    // await sendWhatsAppTemplate({ to: process.env.SOC_WHATSAPP, template: "audit_alert", ... });
+    // await sendEmail({ to: process.env.CONTADOR_EMAIL, subject: "...", body: ... });
+  }
+
+  return digest;
+}
+
+if (typeof require !== "undefined" && require.main === module) {
+  const sid = process.argv[2];
+  if (!sid) {
+    console.error("usage: pnpm tsx 19-forensic-compliance-dashboard.ts <sessionId>");
+    process.exit(1);
+  }
+  main(sid).catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}
+
+export { main };

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 };