feat(portal): M10.1 — fill the 10 customer-area shells

Four real surfaces wired to tenant-registry (settings, settings/api-keys CRUD, audit pagination, products live entitlements), five forward-looking empty states with CTAs. 56 vitest tests + 10 Playwright canaries. lib/format.ts consolidates date helpers.

Refs: M10.1

src/lib/format.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "vitest";
+import { formatDateTime, formatRelative, truncate } from "./format";
+
+describe("formatRelative", () => {
+  const NOW = new Date("2026-05-20T12:00:00Z").getTime();
+  test("seconds ago", () => {
+    expect(formatRelative("2026-05-20T11:59:50Z", NOW)).toBe("10 seconds ago");
+  });
+  test("singular unit", () => {
+    expect(formatRelative("2026-05-20T11:59:59Z", NOW)).toBe("1 second ago");
+  });
+  test("minutes ago", () => {
+    expect(formatRelative("2026-05-20T11:55:00Z", NOW)).toBe("5 minutes ago");
+  });
+  test("hours ago", () => {
+    expect(formatRelative("2026-05-20T09:00:00Z", NOW)).toBe("3 hours ago");
+  });
+  test("days ago", () => {
+    expect(formatRelative("2026-05-13T12:00:00Z", NOW)).toBe("1 week ago");
+  });
+  test("future", () => {
+    expect(formatRelative("2026-06-03T12:00:00Z", NOW)).toBe("in 2 weeks");
+  });
+  test("malformed input returns the input", () => {
+    expect(formatRelative("not-a-date", NOW)).toBe("not-a-date");
+  });
+  test("years ago", () => {
+    expect(formatRelative("2024-05-20T12:00:00Z", NOW)).toBe("2 years ago");
+  });
+  test("months ago", () => {
+    expect(formatRelative("2026-01-20T12:00:00Z", NOW)).toBe("4 months ago");
+  });
+});
+
+describe("formatDateTime", () => {
+  test("formats UTC", () => {
+    expect(formatDateTime("2026-05-20T12:34:56Z")).toBe("2026-05-20 12:34:56 UTC");
+  });
+  test("malformed input returns input", () => {
+    expect(formatDateTime("nope")).toBe("nope");
+  });
+});
+
+describe("truncate", () => {
+  test("short string unchanged", () => {
+    expect(truncate("hi", 10)).toBe("hi");
+  });
+  test("long string truncated with ellipsis", () => {
+    expect(truncate("abcdefghij", 6)).toBe("abcde…");
+  });
+  test("default max", () => {
+    expect(truncate("x".repeat(50)).length).toBe(40);
+  });
+});

src/lib/format.ts

@@ -0,0 +1,56 @@
+// Lightweight date/time helpers — shared across server components so we
+// don't reinvent toLocaleString conventions per page.
+
+export function formatRelative(iso: string, now: number = Date.now()): string {
+  const t = new Date(iso).getTime();
+  if (Number.isNaN(t)) return iso;
+  const diff = t - now;
+  const abs = Math.abs(diff);
+  const ago = diff < 0;
+  const units: [string, number][] = [
+    ["second", 1000],
+    ["minute", 60 * 1000],
+    ["hour", 3600 * 1000],
+    ["day", 24 * 3600 * 1000],
+    ["week", 7 * 24 * 3600 * 1000],
+    ["month", 30 * 24 * 3600 * 1000],
+    ["year", 365 * 24 * 3600 * 1000],
+  ];
+  let unit = "second";
+  let n = Math.round(abs / 1000);
+  for (let i = units.length - 1; i >= 0; i--) {
+    if (abs >= units[i][1]) {
+      unit = units[i][0];
+      n = Math.round(abs / units[i][1]);
+      break;
+    }
+  }
+  const suffix = n === 1 ? unit : `${unit}s`;
+  return ago ? `${n} ${suffix} ago` : `in ${n} ${suffix}`;
+}
+
+export function formatDateTime(iso: string): string {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return iso;
+  // YYYY-MM-DD HH:MM:SS — locale-stable, sortable, no surprises.
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return (
+    d.getUTCFullYear() +
+    "-" +
+    pad(d.getUTCMonth() + 1) +
+    "-" +
+    pad(d.getUTCDate()) +
+    " " +
+    pad(d.getUTCHours()) +
+    ":" +
+    pad(d.getUTCMinutes()) +
+    ":" +
+    pad(d.getUTCSeconds()) +
+    " UTC"
+  );
+}
+
+export function truncate(s: string, max = 40): string {
+  if (s.length <= max) return s;
+  return s.slice(0, max - 1) + "…";
+}

src/lib/tenant-registry.test.ts

@@ -1,10 +1,14 @@
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 import {
+  createAPIKey,
   createTenant,
+  fetchAPIKeys,
+  fetchAudit,
   fetchCatalog,
   fetchEntitlements,
   fetchTenantBySlug,
   requestProduct,
+  revokeAPIKey,
   startTrial,
   type Tenant,
 } from "./tenant-registry";
@@ -198,3 +202,119 @@ describe("coverage gaps", () => {
     await expect(fetchCatalog()).rejects.toThrow();
   });
 });
+
+describe("fetchAPIKeys", () => {
+  test("happy path", async () => {
+    globalThis.fetch = mockJSON(200, {
+      items: [
+        { id: "1", tenant_id: "t1", name: "k1", scopes: [], prefix: "bp_a", created_at: "x" },
+      ],
+    });
+    const list = await fetchAPIKeys("t1");
+    expect(list).toHaveLength(1);
+  });
+  test("404 → []", async () => {
+    globalThis.fetch = mockJSON(404, {});
+    expect(await fetchAPIKeys("t1")).toEqual([]);
+  });
+  test("non-200 throws", async () => {
+    globalThis.fetch = mockJSON(500, {});
+    await expect(fetchAPIKeys("t1")).rejects.toThrow();
+  });
+});
+
+describe("createAPIKey", () => {
+  test("201 returns plaintext", async () => {
+    globalThis.fetch = mockJSON(201, {
+      api_key: { id: "1", tenant_id: "t1", name: "k", scopes: [], prefix: "bp_a", created_at: "x" },
+      plaintext: "bp_abc123",
+    });
+    const res = await createAPIKey({ tenant_id: "t1", name: "k" });
+    expect(res.ok).toBe(true);
+    if (res.ok) expect(res.plaintext).toBe("bp_abc123");
+  });
+  test("404 → tenant_not_found", async () => {
+    globalThis.fetch = mockJSON(404, {});
+    expect(await createAPIKey({ tenant_id: "t1", name: "k" })).toEqual({
+      ok: false,
+      error: "tenant_not_found",
+    });
+  });
+  test("400 → invalid_input", async () => {
+    globalThis.fetch = mockJSON(400, {});
+    expect(await createAPIKey({ tenant_id: "t1", name: "" })).toEqual({
+      ok: false,
+      error: "invalid_input",
+    });
+  });
+  test("409 → name_taken", async () => {
+    globalThis.fetch = mockJSON(409, {});
+    expect(await createAPIKey({ tenant_id: "t1", name: "k" })).toEqual({
+      ok: false,
+      error: "name_taken",
+    });
+  });
+  test("unexpected status", async () => {
+    globalThis.fetch = mockJSON(500, {});
+    expect(await createAPIKey({ tenant_id: "t1", name: "k" })).toEqual({
+      ok: false,
+      error: "unexpected_500",
+    });
+  });
+});
+
+describe("revokeAPIKey", () => {
+  test("204 → ok", async () => {
+    globalThis.fetch = vi.fn<typeof fetch>(async () => new Response(null, { status: 204 }));
+    expect(await revokeAPIKey("k1")).toEqual({ ok: true });
+  });
+  test("404 → not_found", async () => {
+    globalThis.fetch = mockJSON(404, {});
+    expect(await revokeAPIKey("k1")).toEqual({ ok: false, error: "not_found" });
+  });
+  test("unexpected status", async () => {
+    globalThis.fetch = mockJSON(500, {});
+    expect(await revokeAPIKey("k1")).toEqual({ ok: false, error: "unexpected_500" });
+  });
+});
+
+describe("fetchAudit", () => {
+  test("happy path with filters", async () => {
+    const spy = mockJSON(200, {
+      items: [{ id: 1, action: "tenant.created", created_at: "x" }],
+      next_cursor: 1,
+    });
+    globalThis.fetch = spy;
+    const res = await fetchAudit({
+      tenant_id: "t1",
+      product: "certifai",
+      actor_id: "u1",
+      action: "tenant.created",
+      since: "2026-05-01T00:00:00Z",
+      until: "2026-05-20T00:00:00Z",
+      limit: 50,
+      cursor: 10,
+    });
+    expect(res.items).toHaveLength(1);
+    expect(res.next_cursor).toBe(1);
+    const url = String(spy.mock.calls[0]![0]);
+    expect(url).toContain("tenant_id=t1");
+    expect(url).toContain("product=certifai");
+    expect(url).toContain("actor_id=u1");
+    expect(url).toContain("action=tenant.created");
+    expect(url).toContain("limit=50");
+    expect(url).toContain("cursor=10");
+  });
+  test("no filters", async () => {
+    const spy = mockJSON(200, { items: [] });
+    globalThis.fetch = spy;
+    const res = await fetchAudit({});
+    expect(res.items).toEqual([]);
+    const url = String(spy.mock.calls[0]![0]);
+    expect(url).toBe("http://test:1234/v1/audit?");
+  });
+  test("non-200 throws", async () => {
+    globalThis.fetch = mockJSON(500, {});
+    await expect(fetchAudit({ tenant_id: "t1" })).rejects.toThrow();
+  });
+});

src/lib/tenant-registry.ts

@@ -30,6 +30,41 @@ export type Entitlement = {
   expires_at?: string | null;
 };
 
+export type APIKey = {
+  id: string;
+  tenant_id: string;
+  product?: string;
+  name: string;
+  scopes: string[];
+  prefix: string;
+  created_by?: string;
+  last_used_at?: string | null;
+  revoked_at?: string | null;
+  created_at: string;
+};
+
+export type AuditEvent = {
+  id: number;
+  tenant_id?: string;
+  actor_id?: string;
+  actor_name?: string;
+  actor_type?: string;
+  action: string;
+  target_id?: string;
+  target_type?: string;
+  target_name?: string;
+  product?: string;
+  metadata?: Record<string, unknown>;
+  source_ip?: string;
+  user_agent?: string;
+  created_at: string;
+};
+
+export type AuditPage = {
+  items: AuditEvent[];
+  next_cursor?: number;
+};
+
 function baseUrl(): string {
   return process.env.TENANT_REGISTRY_URL ?? "http://localhost:8090";
 }
@@ -157,3 +192,79 @@ export async function createTenant(
   if (status === 400) return { ok: false, error: "invalid_input" };
   return { ok: false, error: `unexpected_${status}` };
 }
+
+// ─── api keys ────────────────────────────────────────────────────────────
+
+export async function fetchAPIKeys(tenantId: string): Promise<APIKey[]> {
+  const { status, data } = await req<{ items: APIKey[] }>(
+    "GET",
+    `/v1/api-keys?tenant_id=${encodeURIComponent(tenantId)}`,
+  );
+  if (status === 404) return [];
+  if (status !== 200 || !data) {
+    throw new Error(`tenant-registry: GET api-keys ${status}`);
+  }
+  return data.items;
+}
+
+export type CreateAPIKeyInput = {
+  tenant_id: string;
+  name: string;
+  product?: string;
+  scopes?: string[];
+  created_by?: string;
+};
+
+export type CreateAPIKeyResult =
+  | { ok: true; api_key: APIKey; plaintext: string }
+  | { ok: false; error: string };
+
+export async function createAPIKey(in_: CreateAPIKeyInput): Promise<CreateAPIKeyResult> {
+  const { status, data } = await req<{ api_key: APIKey; plaintext: string }>(
+    "POST",
+    "/v1/api-keys",
+    in_,
+  );
+  if (status === 201 && data) return { ok: true, api_key: data.api_key, plaintext: data.plaintext };
+  if (status === 404) return { ok: false, error: "tenant_not_found" };
+  if (status === 400) return { ok: false, error: "invalid_input" };
+  if (status === 409) return { ok: false, error: "name_taken" };
+  return { ok: false, error: `unexpected_${status}` };
+}
+
+export async function revokeAPIKey(id: string): Promise<{ ok: boolean; error?: string }> {
+  const { status } = await req<unknown>("DELETE", `/v1/api-keys/${encodeURIComponent(id)}`);
+  if (status === 204) return { ok: true };
+  if (status === 404) return { ok: false, error: "not_found" };
+  return { ok: false, error: `unexpected_${status}` };
+}
+
+// ─── audit ───────────────────────────────────────────────────────────────
+
+export type AuditFilter = {
+  tenant_id?: string;
+  product?: string;
+  actor_id?: string;
+  action?: string;
+  since?: string;
+  until?: string;
+  limit?: number;
+  cursor?: number;
+};
+
+export async function fetchAudit(f: AuditFilter): Promise<AuditPage> {
+  const qs = new URLSearchParams();
+  if (f.tenant_id) qs.set("tenant_id", f.tenant_id);
+  if (f.product) qs.set("product", f.product);
+  if (f.actor_id) qs.set("actor_id", f.actor_id);
+  if (f.action) qs.set("action", f.action);
+  if (f.since) qs.set("since", f.since);
+  if (f.until) qs.set("until", f.until);
+  if (f.limit) qs.set("limit", String(f.limit));
+  if (f.cursor) qs.set("cursor", String(f.cursor));
+  const { status, data } = await req<AuditPage>("GET", `/v1/audit?${qs.toString()}`);
+  if (status !== 200 || !data) {
+    throw new Error(`tenant-registry: GET audit ${status}`);
+  }
+  return data;
+}