@ar-agents/mercadopago 0.17.1 → 0.18.0

package/cookbook/27-live-conformance-monitoring.ts

@@ -0,0 +1,260 @@
+/**
+ * Recipe 27 — Live conformance monitoring with time-series + alerting.
+ *
+ * # Pattern
+ *
+ * Many sociedades-IA operate in production. They want to know: am I
+ * still conformant? If my score drops, when did it drop? Can I be
+ * notified before the regulator sees it?
+ *
+ * Recipe 27 is the monitoring loop:
+ *
+ *   1. Every N minutes (cron), POST /api/conformance-history?url=YOUR_URL
+ *      to the public ar-agents.ar endpoint. This re-runs the
+ *      certifier + appends the new point to a 365-entry time-series.
+ *
+ *   2. Compare the latest point against a sliding-window baseline
+ *      (default: median of last 24 points = ~1 day at 1h intervals).
+ *      If the new score is N% below baseline, fire an alert.
+ *
+ *   3. Optional Slack / email / webhook destinations.
+ *
+ * Properties:
+ *   - The history endpoint already does the storage + capping. Recipe
+ *     27 is just the orchestration + alert logic.
+ *   - Designed to run on Vercel cron, GitHub Actions schedule, or any
+ *     other scheduler. Idempotent: re-running it appends another point.
+ *   - Threshold is a flat percentage drop, not a fancy CUSUM. Easy to
+ *     reason about; tune to taste.
+ *   - Reports drift, not just regression: if score IMPROVED unexpectedly,
+ *     that's interesting too (operator made a change worth noting in
+ *     the audit log).
+ *
+ * # When to use
+ *
+ *   - In production. The day after you deploy your sociedad-IA.
+ *   - For regulator-facing reporting: "I monitored continuously, here
+ *     are the 90 days of scores, here's when drift was detected and
+ *     how it was remediated."
+ *   - For multi-tenant marketplaces (recipe 20): run for each tenant
+ *     sociedad-IA in parallel.
+ *
+ * # Edge Runtime
+ *
+ * Pure fetch + JSON shaping. Runs anywhere Node 18+ / Edge / browser
+ * has `fetch`. No filesystem.
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface Point {
+  ts: string;
+  score: number;
+  rating: "A" | "B" | "C" | "D" | "F" | "N/A";
+}
+
+interface HistoryResponse {
+  target: { baseUrl: string };
+  points: Point[];
+  latest?: Point;
+}
+
+interface MonitorResult {
+  url: string;
+  latest: Point | null;
+  baseline: number | null;
+  baselineWindow: number;
+  drift: "regression" | "improvement" | "stable" | "no-baseline" | "no-data";
+  driftPct: number | null;
+  threshold: number;
+  totalPoints: number;
+  alertFired: boolean;
+  alertMessage: string | null;
+}
+
+interface MonitorOptions {
+  /** Public ar-agents endpoint (allow override for self-hosted). */
+  apiBaseUrl?: string;
+  /** How many recent points form the baseline. Default 24. */
+  baselineWindow?: number;
+  /** Percent drop that triggers an alert. Default 10. */
+  threshold?: number;
+  /** Override fetch impl (testing). */
+  fetchImpl?: typeof fetch;
+  /** Optional alert destination URLs. Slack-style webhook expected. */
+  alertWebhooks?: string[];
+}
+
+const DEFAULT_API_BASE = "https://ar-agents.ar";
+const DEFAULT_BASELINE_WINDOW = 24;
+const DEFAULT_THRESHOLD_PCT = 10;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Core monitoring loop
+// ─────────────────────────────────────────────────────────────────────────────
+
+function median(nums: number[]): number {
+  if (nums.length === 0) return 0;
+  const sorted = [...nums].sort((a, b) => a - b);
+  const m = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0 ? (sorted[m - 1] + sorted[m]) / 2 : sorted[m];
+}
+
+export async function monitorConformance(
+  url: string,
+  options: MonitorOptions = {},
+): Promise<MonitorResult> {
+  const api = options.apiBaseUrl ?? DEFAULT_API_BASE;
+  const baselineWindow = options.baselineWindow ?? DEFAULT_BASELINE_WINDOW;
+  const threshold = options.threshold ?? DEFAULT_THRESHOLD_PCT;
+  const fetchImpl = options.fetchImpl ?? fetch;
+
+  // 1. Append a new point + read the full history.
+  const postUrl = `${api}/api/conformance-history?url=${encodeURIComponent(url)}`;
+  let history: HistoryResponse | null = null;
+  try {
+    const r = await fetchImpl(postUrl, {
+      method: "POST",
+      headers: { "user-agent": "ar-agents-recipe-27-monitor" },
+    });
+    if (r.ok) history = (await r.json()) as HistoryResponse;
+  } catch {
+    // fall through
+  }
+  if (!history) {
+    return {
+      url,
+      latest: null,
+      baseline: null,
+      baselineWindow,
+      drift: "no-data",
+      driftPct: null,
+      threshold,
+      totalPoints: 0,
+      alertFired: false,
+      alertMessage: null,
+    };
+  }
+
+  const points = history.points;
+  const latest = history.latest ?? points[points.length - 1] ?? null;
+  if (!latest) {
+    return {
+      url,
+      latest: null,
+      baseline: null,
+      baselineWindow,
+      drift: "no-data",
+      driftPct: null,
+      threshold,
+      totalPoints: 0,
+      alertFired: false,
+      alertMessage: null,
+    };
+  }
+
+  // 2. Compute baseline (excluding the latest point so it's "before").
+  const beforeLatest = points.slice(0, -1);
+  const baselineSlice = beforeLatest.slice(-baselineWindow);
+  if (baselineSlice.length === 0) {
+    return {
+      url,
+      latest,
+      baseline: null,
+      baselineWindow,
+      drift: "no-baseline",
+      driftPct: null,
+      threshold,
+      totalPoints: points.length,
+      alertFired: false,
+      alertMessage: null,
+    };
+  }
+
+  const baseline = median(baselineSlice.map((p) => p.score));
+  const driftPct = baseline > 0 ? ((latest.score - baseline) / baseline) * 100 : 0;
+
+  let drift: MonitorResult["drift"];
+  if (Math.abs(driftPct) < threshold / 2) drift = "stable";
+  else if (driftPct < 0) drift = "regression";
+  else drift = "improvement";
+
+  // 3. Alert if regression exceeded threshold.
+  const alertFired = drift === "regression" && Math.abs(driftPct) >= threshold;
+  let alertMessage: string | null = null;
+  if (alertFired) {
+    alertMessage = `RFC conformance regression: ${url} dropped ${driftPct.toFixed(1)}% (from baseline ${baseline.toFixed(1)} to ${latest.score}/${latest.rating}). Baseline window: ${baselineSlice.length} points.`;
+
+    // Fire webhooks in parallel; don't fail the function if a webhook fails.
+    if (options.alertWebhooks && options.alertWebhooks.length > 0) {
+      await Promise.allSettled(
+        options.alertWebhooks.map((hook) =>
+          fetchImpl(hook, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ text: alertMessage }),
+          }),
+        ),
+      );
+    }
+  }
+
+  return {
+    url,
+    latest,
+    baseline,
+    baselineWindow,
+    drift,
+    driftPct,
+    threshold,
+    totalPoints: points.length,
+    alertFired,
+    alertMessage,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CLI: tsx 27-live-conformance-monitoring.ts <url> [--threshold=N] [--webhook=URL ...]
+// ─────────────────────────────────────────────────────────────────────────────
+
+declare const process: { argv: string[]; env: Record<string, string | undefined> } | undefined;
+
+async function main() {
+  if (typeof process === "undefined") return;
+  const args = process.argv.slice(2);
+  const url = args.find((a) => !a.startsWith("--"));
+  if (!url) {
+    console.error("usage: tsx 27-live-conformance-monitoring.ts <url> [--threshold=N] [--webhook=URL]");
+    return;
+  }
+  const threshold = (() => {
+    const arg = args.find((a) => a.startsWith("--threshold="));
+    return arg ? parseFloat(arg.split("=")[1]) : DEFAULT_THRESHOLD_PCT;
+  })();
+  const alertWebhooks = args.filter((a) => a.startsWith("--webhook=")).map((a) => a.split("=")[1]);
+
+  const result = await monitorConformance(url, {
+    threshold,
+    alertWebhooks,
+  });
+
+  console.log(JSON.stringify(result, null, 2));
+
+  if (typeof process !== "undefined" && "exit" in process) {
+    (process as unknown as { exit: (code: number) => void }).exit(
+      result.alertFired ? 1 : 0,
+    );
+  }
+}
+
+const isMain = typeof require !== "undefined" && require.main === module;
+if (isMain) {
+  main().catch((e) => {
+    console.error(e);
+    if (typeof process !== "undefined" && "exit" in process) {
+      (process as unknown as { exit: (code: number) => void }).exit(1);
+    }
+  });
+}

package/cookbook/28-operator-onboarding-checklist.ts

@@ -0,0 +1,315 @@
+/**
+ * Recipe 28 — Operator onboarding checklist + automated verification.
+ *
+ * # Pattern
+ *
+ * You're an operator about to launch your first sociedad-IA. There are
+ * 18 items to wire up across MercadoPago, AFIP/ARCA, WhatsApp, banking,
+ * KV storage, HMAC signing, Ed25519 signing (optional v2), env vars,
+ * domain DNS, /.well-known publication.
+ *
+ * Recipe 28 is the inventory + auto-verifier: a single function
+ * `checkOperatorReadiness(baseUrl)` that walks the checklist
+ * programmatically and returns a per-item pass/fail/skip with
+ * remediation links.
+ *
+ * The output is a deterministic JSON readiness report — the operator's
+ * pre-launch sign-off. Used internally by the auto-incorporation wizard
+ * (/api/auto-incorporate) to confirm a freshly-deployed sociedad-IA is
+ * production-ready before adding it to /registro.
+ *
+ * # When to use
+ *
+ *   - Right after running `vercel deploy` of a freshly-generated
+ *     sociedad-IA from the sociedad-ia-starter template.
+ *   - Before listing in /registro (the registry rejects entries with a
+ *     readiness < B).
+ *   - As a pre-merge gate in the operator's own CI (analogous to recipe 26
+ *     but covers operator-wiring, not just RFC conformance).
+ *
+ * # Edge Runtime
+ *
+ * Pure fetch + JSON shaping. Runs anywhere fetch is available.
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface Item {
+  id: string;
+  category:
+    | "discovery"
+    | "audit"
+    | "providers"
+    | "security"
+    | "legal"
+    | "ops"
+    | "tooling";
+  label: string;
+  status: "pass" | "fail" | "skip" | "warn";
+  detail: string;
+  remediation?: string;
+  ref?: string;
+}
+
+export interface Readiness {
+  $schema: string;
+  generatedAt: string;
+  target: { baseUrl: string };
+  readiness: "ready" | "almost" | "blocked" | "not-deployed";
+  passedCount: number;
+  totalCount: number;
+  items: Item[];
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The checklist
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface Check {
+  id: string;
+  category: Item["category"];
+  label: string;
+  ref?: string;
+  /** Returns the Item details. */
+  run: (base: string, fetchImpl: typeof fetch) => Promise<Omit<Item, "id" | "category" | "label" | "ref">>;
+}
+
+async function fetchOk(
+  url: string,
+  fetchImpl: typeof fetch,
+): Promise<{ ok: boolean; status: number; body?: unknown }> {
+  try {
+    const r = await fetchImpl(url, { signal: AbortSignal.timeout(8000) });
+    if (!r.ok) return { ok: false, status: r.status };
+    let body: unknown;
+    try {
+      const ct = r.headers.get("content-type") || "";
+      body = ct.includes("application/json") ? await r.json() : await r.text();
+    } catch {
+      body = null;
+    }
+    return { ok: true, status: r.status, body };
+  } catch {
+    return { ok: false, status: 0 };
+  }
+}
+
+const CHECKS: ReadonlyArray<Check> = [
+  {
+    id: "discovery-well-known",
+    category: "discovery",
+    label: "/.well-known/agents.json serves manifest with issuer.jurisdiction",
+    ref: "https://ar-agents.ar/rfcs/002",
+    run: async (base, fetchImpl) => {
+      const r = await fetchOk(`${base}/.well-known/agents.json`, fetchImpl);
+      if (!r.ok) return { status: "fail", detail: `HTTP ${r.status || "network error"}`, remediation: "Add apps/landing/public/.well-known/agents.json per RFC-002 schema." };
+      const m = r.body as Record<string, unknown> | null;
+      const j = m?.issuer as Record<string, unknown> | undefined;
+      if (!j?.jurisdiction) return { status: "fail", detail: "Missing issuer.jurisdiction.", remediation: "Add issuer.jurisdiction to your agents.json." };
+      return { status: "pass", detail: `jurisdiction=${j.jurisdiction}.` };
+    },
+  },
+  {
+    id: "discovery-rfc-conformance",
+    category: "discovery",
+    label: "Manifest declares rfcConformance",
+    run: async (base, fetchImpl) => {
+      const r = await fetchOk(`${base}/.well-known/agents.json`, fetchImpl);
+      if (!r.ok) return { status: "skip", detail: "Manifest fetch failed." };
+      const arr = (r.body as Record<string, unknown> | null)?.rfcConformance;
+      if (Array.isArray(arr) && arr.length > 0) {
+        return { status: "pass", detail: `Claims: ${(arr as string[]).join(", ")}.` };
+      }
+      return { status: "warn", detail: "No rfcConformance array.", remediation: "Declare which RFCs your impl conforms to (e.g. ['rfc-001-v1', 'rfc-002-v1', 'rfc-004-draft'])." };
+    },
+  },
+  {
+    id: "audit-read",
+    category: "audit",
+    label: "Audit-read endpoint /api/play/audit/{sessionId} responds",
+    ref: "https://ar-agents.ar/rfcs/004",
+    run: async (base, fetchImpl) => {
+      const r = await fetchOk(`${base}/api/play/audit/demo-public-ar-001`, fetchImpl);
+      if (!r.ok) return { status: "fail", detail: `HTTP ${r.status}.`, remediation: "Verify your audit-log route is deployed + has the {sessionId} dynamic segment." };
+      return { status: "pass", detail: "Endpoint responds 200." };
+    },
+  },
+  {
+    id: "audit-verify",
+    category: "audit",
+    label: "Audit-verify (?verify=1) returns HMAC verification counts",
+    ref: "https://ar-agents.ar/rfcs/004",
+    run: async (base, fetchImpl) => {
+      const r = await fetchOk(`${base}/api/play/audit/demo-public-ar-001?verify=1`, fetchImpl);
+      if (!r.ok) return { status: "fail", detail: `HTTP ${r.status}.` };
+      const d = r.body as Record<string, unknown> | null;
+      const v = (d?.verification ?? d) as Record<string, unknown> | undefined;
+      if (typeof v?.hmacWired === "boolean") {
+        return v.hmacWired
+          ? { status: "pass", detail: `hmacWired=true.` }
+          : { status: "warn", detail: "hmacWired=false (production must wire AUDIT_HMAC_SECRET).", remediation: "Set AUDIT_HMAC_SECRET env var in your Vercel project." };
+      }
+      return { status: "warn", detail: "Response missing verification counts." };
+    },
+  },
+  {
+    id: "audit-csv",
+    category: "audit",
+    label: "CSV export endpoint returns text/csv",
+    run: async (base, fetchImpl) => {
+      try {
+        const r = await fetchImpl(`${base}/api/play/audit/demo-public-ar-001/csv`, { signal: AbortSignal.timeout(8000) });
+        if (!r.ok) return { status: "fail", detail: `HTTP ${r.status}.` };
+        const ct = r.headers.get("content-type") || "";
+        return ct.includes("text/csv")
+          ? { status: "pass", detail: `Content-Type: ${ct}.` }
+          : { status: "warn", detail: `Content-Type is ${ct}, expected text/csv.` };
+      } catch (e) {
+        return { status: "fail", detail: `Network error: ${(e as Error).message}` };
+      }
+    },
+  },
+  {
+    id: "rfc-005-keys",
+    category: "audit",
+    label: "RFC-005 /.well-known/sociedad-ia/keys publishes Ed25519 key",
+    ref: "https://ar-agents.ar/rfcs/005",
+    run: async (base, fetchImpl) => {
+      const r = await fetchOk(`${base}/.well-known/sociedad-ia/keys`, fetchImpl);
+      if (!r.ok) return { status: "skip", detail: `Not advertised (HTTP ${r.status}). v1 HMAC-only is OK.`, remediation: "Optional: publish your Ed25519 public key per RFC-005 § 4 for asymmetric verifier support." };
+      const keys = (r.body as Record<string, unknown> | null)?.keys;
+      return Array.isArray(keys) && keys.length > 0
+        ? { status: "pass", detail: `${keys.length} key(s) advertised.` }
+        : { status: "warn", detail: "Endpoint exists but no keys advertised." };
+    },
+  },
+  {
+    id: "tooling-openapi",
+    category: "tooling",
+    label: "/api/openapi returns OpenAPI 3.x spec",
+    run: async (base, fetchImpl) => {
+      const r = await fetchOk(`${base}/api/openapi`, fetchImpl);
+      if (!r.ok) return { status: "skip", detail: `Not advertised (HTTP ${r.status}).`, remediation: "Optional but recommended for tooling generators." };
+      const d = r.body as Record<string, unknown> | null;
+      return typeof d?.openapi === "string" && (d.openapi as string).startsWith("3.")
+        ? { status: "pass", detail: `OpenAPI ${d.openapi}.` }
+        : { status: "warn", detail: "Not an OpenAPI 3.x doc." };
+    },
+  },
+  {
+    id: "security-hsts",
+    category: "security",
+    label: "HSTS header present on root response",
+    run: async (base, fetchImpl) => {
+      try {
+        const r = await fetchImpl(base, { signal: AbortSignal.timeout(5000) });
+        const hsts = r.headers.get("strict-transport-security");
+        return hsts
+          ? { status: "pass", detail: hsts }
+          : { status: "warn", detail: "HSTS missing.", remediation: "Vercel sets HSTS by default on .vercel.app domains; on custom domains, ensure the redirect is configured." };
+      } catch (e) {
+        return { status: "fail", detail: `Network error: ${(e as Error).message}` };
+      }
+    },
+  },
+  {
+    id: "tooling-sitemap",
+    category: "tooling",
+    label: "Sitemap.xml is published",
+    run: async (base, fetchImpl) => {
+      const r = await fetchOk(`${base}/sitemap.xml`, fetchImpl);
+      return r.ok
+        ? { status: "pass", detail: "sitemap.xml present." }
+        : { status: "warn", detail: "No sitemap.xml advertised." };
+    },
+  },
+  {
+    id: "tooling-llms-txt",
+    category: "tooling",
+    label: "/llms.txt is published for AI crawlers",
+    run: async (base, fetchImpl) => {
+      const r = await fetchOk(`${base}/llms.txt`, fetchImpl);
+      return r.ok
+        ? { status: "pass", detail: "/llms.txt present." }
+        : { status: "warn", detail: "No /llms.txt advertised.", remediation: "Publish /llms.txt per the llmstxt.org convention so AI crawlers can ingest your sociedad's surface." };
+    },
+  },
+];
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Public API
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function checkOperatorReadiness(
+  baseUrl: string,
+  options: { fetchImpl?: typeof fetch } = {},
+): Promise<Readiness> {
+  const parsed = new URL(baseUrl);
+  const base = parsed.origin;
+  const fetchImpl = options.fetchImpl ?? fetch;
+
+  const items: Item[] = await Promise.all(
+    CHECKS.map(async (c): Promise<Item> => {
+      const r = await c.run(base, fetchImpl);
+      return {
+        id: c.id,
+        category: c.category,
+        label: c.label,
+        ref: c.ref,
+        ...r,
+      };
+    }),
+  );
+
+  const passing = items.filter((i) => i.status === "pass").length;
+  const failing = items.filter((i) => i.status === "fail").length;
+
+  let readiness: Readiness["readiness"];
+  if (failing > 2) readiness = "blocked";
+  else if (failing > 0 || passing < items.length - 2) readiness = "almost";
+  else readiness = "ready";
+
+  return {
+    $schema: "https://ar-agents.ar/schemas/readiness.v1.json",
+    generatedAt: new Date().toISOString(),
+    target: { baseUrl: base },
+    readiness,
+    passedCount: passing,
+    totalCount: items.length,
+    items,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CLI: `tsx 28-operator-onboarding-checklist.ts <baseUrl>`
+// ─────────────────────────────────────────────────────────────────────────────
+
+declare const process: { argv: string[] } | undefined;
+
+async function main() {
+  if (typeof process === "undefined") return;
+  const baseUrl = process.argv[2];
+  if (!baseUrl) {
+    console.error("usage: tsx 28-operator-onboarding-checklist.ts <baseUrl>");
+    return;
+  }
+  const r = await checkOperatorReadiness(baseUrl);
+  console.log(JSON.stringify(r, null, 2));
+  if (typeof process !== "undefined" && "exit" in process) {
+    (process as unknown as { exit: (code: number) => void }).exit(
+      r.readiness === "blocked" ? 1 : 0,
+    );
+  }
+}
+
+const isMain = typeof require !== "undefined" && require.main === module;
+if (isMain) {
+  main().catch((e) => {
+    console.error(e);
+    if (typeof process !== "undefined" && "exit" in process) {
+      (process as unknown as { exit: (code: number) => void }).exit(1);
+    }
+  });
+}