@ar-agents/mercadopago 0.17.2 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.18.0
+
+### Minor Changes
+
+- [`8c58aa0`](https://github.com/ar-agents/ar-agents/commit/8c58aa061a7579a2854ee4239ceb698c92148f28) Thanks [@naza00000](https://github.com/naza00000)! - `MercadoPagoError` now extends `ArAgentsError` from `@ar-agents/core`.
+
+  Brings family-coherence to the flagship integration. Every MP error
+  (`MercadoPagoAuthError`, `MercadoPagoRateLimitError`,
+  `MercadoPagoOverloadedError`, `MercadoPagoTimeoutError`,
+  `MercadoPagoPaymentRejectedError`, …) now exposes the uniform
+  `{ code, retryable, context }` contract so `@ar-agents/core`'s
+  `withRetry` middleware (and any external middleware) can switch on
+  the same fields used by every other `@ar-agents/*` package.
+
+  Codes assigned:
+
+  | Subclass                                                           | code              | retryable                         |
+  | ------------------------------------------------------------------ | ----------------- | --------------------------------- |
+  | `MercadoPagoError` (generic)                                       | `mp_api_error`    | `true` for 5xx / 429 / `status:0` |
+  | `MercadoPagoAuthError`                                             | `mp_auth_failed`  | `false`                           |
+  | `MercadoPagoRateLimitError`                                        | `mp_rate_limited` | `true`                            |
+  | `MercadoPagoOverloadedError`                                       | `mp_overloaded`   | `true`                            |
+  | `MercadoPagoTimeoutError`                                          | `mp_timeout`      | `true`                            |
+  | all 400 subclasses (back_url / self-payment / country / authorize) | `mp_api_error`    | `false`                           |
+
+  Backward compatible: all existing public properties (`status`,
+  `endpoint`, `mpResponse`, `retryAfterSeconds`, `preapprovalId`, …) are
+  preserved on the instance AND mirrored into `context` for new code
+  that reads the `ArAgentsError` contract. `instanceof MercadoPagoError`
+  keeps working; `isArAgentsError(e)` now additionally returns `true`.
+
+  All 328 existing mercadopago tests pass with no changes.
+
 ## 0.17.2
 
 ### Patch Changes

package/cookbook/18-usa-llc-self-incorporates-ar.ts

@@ -0,0 +1,208 @@
+/**
+ * Recipe 18 — USA-LLC agent self-incorporates an AR sociedad-IA.
+ *
+ * The end-to-end pattern that the headline of `/sociedades-ia` makes a
+ * concrete claim about: a USA-incorporated agent (ClawBank-formed
+ * Wyoming/Ohio LLC, doola Agentic LLC, Marshall Islands MIDAO) needs an
+ * AR-resident operating layer for some of its activity. Until now this
+ * was a manual escribano + contador job per spawn. Recipe 18 collapses
+ * the manual layer to one programmatic call:
+ *
+ *   POST https://ar-agents.ar/api/auto-incorporate
+ *
+ * via the `@ar-agents/incorporate` client. The output is everything the
+ * USA-LLC agent's deploy pipeline needs to spin up the AR side:
+ *
+ *   - package.json + lib/agent.ts + .env.example + README.md
+ *   - Vercel one-click deploy URL pointing at apps/sociedad-ia-starter
+ *   - Env-var manifest the agent must source from its secret store
+ *   - Legal + operational checklist (ARCA cert, MP token, Meta verify,
+ *     IGJ inscription via TAD)
+ *   - Signed audit-log reference — the entire incorporation request is
+ *     a forensic event under RFC-001 § 9.2, queryable later
+ *
+ * # Why this recipe matters
+ *
+ * RFC-001 § 7 sketches "cross-jurisdictional agent commerce". The USA
+ * side has its own corporate-form vehicles for AI-only entities (Wyoming
+ * DAO LLC, Marshall Islands MIDAO). What it doesn't have natively is a
+ * way to operate inside the AR jurisdiction — emit factura electrónica,
+ * receive Mercado Pago, monitor Boletín Oficial, pay monotributo. Recipe
+ * 18 is how that side fills.
+ *
+ * # The one-line pitch
+ *
+ * `pnpm add @ar-agents/incorporate` → `await incorporate({...})` →
+ * AR sociedad-IA spec ready in 100ms (then the human-pending bits:
+ * ARCA cert wait, IGJ inscription wait, Meta verification wait — all
+ * upstream timers we don't control).
+ *
+ * # Edge Runtime
+ *
+ * The client is fetch-only, zero dependencies. Runs on Vercel Edge,
+ * Cloudflare Workers, Deno, browsers. No `node:*` imports.
+ */
+
+import { incorporate, fetchAudit, type IncorporateInput } from "@ar-agents/incorporate";
+
+// ─── 1. The USA-LLC agent gathers the AR sociedad's parameters ─────────────
+//
+// Often these come from the human deal-maker once (corporate name + objeto)
+// and the rest is mechanical. The `sessionId` is what ties this incorporation
+// request to subsequent operational events under one forensic timeline.
+
+const sessionId = crypto.randomUUID();
+
+const input: IncorporateInput = {
+  // Public corporate name. IGJ rejects reserved words (Nacional / Estatal /
+  // Gobierno / Estado / Oficial). The pre-flight at the server side will
+  // catch them; surface the validation findings to the human if any.
+  denominacion: "ClawBank-AR Operations SAS",
+
+  // SOCIEDAD-IA is the eventual target — but until the AR regime is
+  // sancionado (estimated H1 2027), use SAS so the operator runs under the
+  // RFC-001 § 3.1 three-layer liability framework with a human representante.
+  tipo: "SAS",
+
+  // Capital social in ARS. SAS minimum is 100k. Set higher if the operator
+  // expects to handle larger incoming flows (banks may scrutinize disparities
+  // between capital and transaction volume).
+  capitalSocial: 200_000,
+
+  // Objeto social. IGJ rejects generic phrasing; be specific. 20-2000 chars.
+  objeto:
+    "Operación de servicios digitales y desarrollo de software propio para clientes argentinos, en representación de la entidad madre USA-incorporada bajo el marco RFC-001 § 7 (cross-jurisdictional agent commerce).",
+
+  // Human representante for the AR-side legal facade per RFC-001 § 3.1. In
+  // production the orchestrator pulls this from its operator-of-record store
+  // (e.g., the escribano contracted as the AR-presence layer).
+  representante: {
+    nombre: "Pérez, Juan",
+    cuit: "20-12345678-9",
+  },
+  emailContacto: "ops+ar@usa-llc.example",
+
+  // Pieza selection. The auto-incorporate endpoint always merges in the
+  // required set (identity, gde-tad, mercadopago, banking, facturacion).
+  // Add what this particular operator needs:
+  piezas: [
+    "identity",
+    "gde-tad",
+    "mercadopago",
+    "banking",
+    "facturacion",
+    "boletin-oficial",
+    "igj",
+    "whatsapp",
+    "ap2", // for AP2 mandate verification on incoming agent commerce
+    "agentic-commerce-bridge", // to expose ACP-compliant checkout to ChatGPT/Claude buyers
+  ],
+
+  // The session id chains every event under one forensic timeline.
+  sessionId,
+};
+
+// ─── 2. Call the endpoint ──────────────────────────────────────────────────
+
+async function main() {
+  const result = await incorporate(input);
+
+  if (!result.ok) {
+    // Validation failure (HTTP 422). The server caught a structural issue
+    // (reserved word, capital below minimum, malformed CUIT, etc). The agent
+    // should surface findings to the human and retry with a fix.
+    console.error("Incorporation rejected at pre-flight:");
+    for (const f of result.validation.findings) {
+      console.error(`  [${f.severity}] ${f.field}: ${f.message}`);
+    }
+    process.exit(1);
+  }
+
+  // ─── 3. Materialize the four generated files into the deploy repo ─────
+  //
+  // The output is plain strings — the USA-LLC's deploy pipeline writes them
+  // to a fresh GitHub repo, then triggers the Vercel deploy. Below we just
+  // print to stdout for the recipe's purposes.
+
+  console.log("Sociedad:", result.sociedad);
+  console.log();
+  console.log("Generated files:");
+  for (const path of Object.keys(result.config) as Array<
+    keyof typeof result.config
+  >) {
+    console.log(`\n--- ${path} (${result.config[path].length} chars) ---`);
+    console.log(result.config[path].slice(0, 200) + "…");
+  }
+
+  // ─── 4. Surface the deploy URL to the human (or auto-deploy) ──────────
+  //
+  // The Vercel one-click clone URL is pre-filled with the right env-var
+  // slots. In production: pipe to the orchestrator's deploy runner. For
+  // a manual flow: print the URL and let the human click.
+
+  console.log("\nDeploy:", result.deploy.oneClickUrl);
+
+  // ─── 5. Hand off the operational checklist to the human ───────────────
+  //
+  // These are the human-pending steps: ARCA cert wait, MP creds, Meta
+  // business verify, IGJ inscription via TAD. The agent can't shortcut
+  // them — they're upstream gov/private-co timers — but it can emit them
+  // all at once so nothing falls through the cracks.
+
+  console.log("\nChecklist (human-pending):");
+  for (const [i, step] of result.checklist.entries()) {
+    console.log(`  ${i + 1}. ${step}`);
+  }
+
+  // ─── 6. Log + verify the forensic event ───────────────────────────────
+  //
+  // The incorporation request is itself a tool call recorded in the audit
+  // log. Anyone (regulator, journalist, downstream agent) can later hit
+  //   /api/play/audit/{sessionId}?verify=1
+  // and confirm the entry is HMAC-clean. This is what makes RFC-001 § 9.2's
+  // claim that the log is "legally probative" mechanically true.
+
+  console.log("\nAudit:");
+  console.log("  sessionId:", result.audit.sessionId);
+  console.log("  backend:", result.audit.backend);
+  console.log("  hmac:", result.audit.entry.hmac?.slice(0, 30) + "…");
+  console.log("  dashboard:", result.audit.dashboardUrl);
+
+  // Optional: re-verify the entry the agent just wrote. Useful if the orchestrator
+  // wants to assert tamper-free state before proceeding to step 7+.
+  const audit = (await fetchAudit(sessionId, { verify: true })) as {
+    verification?: { tampered: number; verified: number; total: number };
+  };
+  if (audit.verification && audit.verification.tampered > 0) {
+    throw new Error(
+      `Audit log shows ${audit.verification.tampered} tampered entries — abort`,
+    );
+  }
+  console.log("\nVerified clean:", audit.verification);
+}
+
+main().catch((err) => {
+  console.error("Recipe 18 failed:", err);
+  process.exit(1);
+});
+
+// ─── 7. What happens after ─────────────────────────────────────────────────
+//
+// Once the AR side is provisioned, the USA-LLC agent and the AR sociedad-IA
+// can transact under a single trust contract:
+//
+//   - The USA agent calls the AR sociedad's /api/agent endpoint with mandate
+//     proof (AP2 § 4 — see @ar-agents/ap2 cookbook recipe 02 — multi-hop).
+//   - The AR sociedad executes within its jurisdiction (factura emission,
+//     MP cobro, BCRA credit checks, etc).
+//   - Every tool call lands in the same audit log (chain via the same
+//     sessionId).
+//   - At end-of-month, the USA-LLC's accountant + the AR sociedad's contador
+//     settle the inter-entity ledger off the audit log's signed events.
+//
+// This is the reference implementation of cross-jurisdictional agent
+// commerce. The whole stack — from the npm package this recipe imports to
+// the audit log it leaves behind — is MIT-licensed and SLSA-provenanced.
+//
+// `agent self-incorporates → operates → settles` in three contractual hops,
+// no escribono in the loop after step 1.

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