feat(portal): M11.1 catalog flow + M12.1 self-serve trial

Closes the customer loop: /start signup → tenant + KC org + IT_ADMIN invite → portal dashboard with trial banner → /[slug]/catalog with Request + Start trial server actions wired to tenant-registry.

Refs: M11.1 + M12.1

src/lib/tenant-registry.test.ts

@@ -1,14 +1,23 @@
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
-import { fetchTenantBySlug, type Tenant } from "./tenant-registry";
+import {
+  createTenant,
+  fetchCatalog,
+  fetchEntitlements,
+  fetchTenantBySlug,
+  requestProduct,
+  startTrial,
+  type Tenant,
+} from "./tenant-registry";
 
 const SAMPLE: Tenant = {
   id: "00000000-0000-0000-0000-000000000001",
   slug: "acme",
   name: "Acme Inc.",
   status: "active",
+  kind: "customer",
   plan: "professional",
-  products: ["certifai", "compliance"],
   created_at: "2026-05-18T22:00:00Z",
+  updated_at: "2026-05-18T22:00:00Z",
 };
 
 const originalFetch = globalThis.fetch;
@@ -20,45 +29,172 @@ afterEach(() => {
   vi.restoreAllMocks();
 });
 
+beforeEach(() => {
+  process.env.TENANT_REGISTRY_URL = "http://test:1234";
+});
+
+function mockJSON(status: number, body: unknown) {
+  return vi.fn<typeof fetch>(async () =>
+    new Response(JSON.stringify(body), {
+      status,
+      headers: { "content-type": "application/json" },
+    }),
+  );
+}
+
 describe("fetchTenantBySlug", () => {
-  beforeEach(() => {
-    process.env.TENANT_REGISTRY_URL = "http://test:1234";
-  });
-
   test("200 → parsed tenant", async () => {
-    globalThis.fetch = vi.fn(async () => new Response(JSON.stringify(SAMPLE), { status: 200 }));
-    const t = await fetchTenantBySlug("acme");
-    expect(t).toEqual(SAMPLE);
+    globalThis.fetch = mockJSON(200, SAMPLE);
+    expect(await fetchTenantBySlug("acme")).toEqual(SAMPLE);
   });
-
   test("404 → null", async () => {
-    globalThis.fetch = vi.fn(async () => new Response("", { status: 404 }));
-    const t = await fetchTenantBySlug("nope");
-    expect(t).toBeNull();
+    globalThis.fetch = mockJSON(404, {});
+    expect(await fetchTenantBySlug("nope")).toBeNull();
   });
-
   test("500 → throws", async () => {
-    globalThis.fetch = vi.fn(async () => new Response("", { status: 500, statusText: "boom" }));
-    await expect(fetchTenantBySlug("acme")).rejects.toThrow(/tenant-registry: 500/);
+    globalThis.fetch = mockJSON(500, {});
+    await expect(fetchTenantBySlug("acme")).rejects.toThrow(/500/);
   });
-
-  test("falls back to default base URL when env unset", async () => {
+  test("default base URL", async () => {
     delete process.env.TENANT_REGISTRY_URL;
-    const fetchSpy = vi.fn(async () => new Response(JSON.stringify(SAMPLE), { status: 200 }));
-    globalThis.fetch = fetchSpy;
+    const spy = mockJSON(200, SAMPLE);
+    globalThis.fetch = spy;
     await fetchTenantBySlug("acme");
-    expect(fetchSpy).toHaveBeenCalledWith(
-      "http://localhost:8090/v1/tenants/by-slug/acme",
-      expect.any(Object),
-    );
+    expect(spy.mock.calls[0]![0]).toBe("http://localhost:8090/v1/tenants/by-slug/acme");
   });
-
-  test("encodes slug to defend against weird input", async () => {
-    const fetchSpy = vi.fn<typeof fetch>(async () => new Response("", { status: 404 }));
-    globalThis.fetch = fetchSpy;
+  test("encodes slug", async () => {
+    const spy = mockJSON(404, {});
+    globalThis.fetch = spy;
     await fetchTenantBySlug("a/b c");
-    const firstCall = fetchSpy.mock.calls[0];
-    expect(firstCall).toBeDefined();
-    expect(firstCall![0]).toBe("http://test:1234/v1/tenants/by-slug/a%2Fb%20c");
+    expect(spy.mock.calls[0]![0]).toBe("http://test:1234/v1/tenants/by-slug/a%2Fb%20c");
+  });
+});
+
+describe("fetchCatalog", () => {
+  test("returns items[]", async () => {
+    globalThis.fetch = mockJSON(200, {
+      items: [
+        { key: "certifai", name: "CERTifAI", description: "x", plans_required: [], supports_trial: true },
+      ],
+    });
+    const list = await fetchCatalog();
+    expect(list).toHaveLength(1);
+    expect(list[0].key).toBe("certifai");
+  });
+  test("non-200 throws", async () => {
+    globalThis.fetch = mockJSON(500, {});
+    await expect(fetchCatalog()).rejects.toThrow();
+  });
+});
+
+describe("fetchEntitlements", () => {
+  test("happy path", async () => {
+    globalThis.fetch = mockJSON(200, {
+      items: [{ tenant_id: "t1", product: "certifai", enabled: true, config: {} }],
+    });
+    expect(await fetchEntitlements("t1")).toHaveLength(1);
+  });
+  test("404 → []", async () => {
+    globalThis.fetch = mockJSON(404, {});
+    expect(await fetchEntitlements("t1")).toEqual([]);
+  });
+});
+
+describe("requestProduct", () => {
+  test("202 → ok", async () => {
+    globalThis.fetch = mockJSON(202, { status: "accepted" });
+    expect(await requestProduct("t1", "certifai")).toEqual({ ok: true });
+  });
+  test("404 maps to tenant_not_found", async () => {
+    globalThis.fetch = mockJSON(404, {});
+    expect(await requestProduct("t1", "certifai")).toEqual({
+      ok: false,
+      error: "tenant_not_found",
+    });
+  });
+  test("400 maps to invalid_input", async () => {
+    globalThis.fetch = mockJSON(400, {});
+    expect(await requestProduct("t1", "x")).toEqual({ ok: false, error: "invalid_input" });
+  });
+  test("unexpected status surfaces with code", async () => {
+    globalThis.fetch = mockJSON(503, {});
+    expect(await requestProduct("t1", "x")).toEqual({ ok: false, error: "unexpected_503" });
+  });
+});
+
+describe("startTrial", () => {
+  test("201 → entitlement", async () => {
+    globalThis.fetch = mockJSON(201, {
+      tenant_id: "t1", product: "certifai", enabled: true, config: { source: "trial" },
+    });
+    const res = await startTrial("t1", "certifai");
+    expect(res.ok).toBe(true);
+    if (res.ok) expect(res.entitlement.product).toBe("certifai");
+  });
+  test("400 maps to invalid_input", async () => {
+    globalThis.fetch = mockJSON(400, {});
+    expect(await startTrial("t1", "x")).toEqual({ ok: false, error: "invalid_input" });
+  });
+});
+
+describe("createTenant", () => {
+  test("201 returns tenant", async () => {
+    globalThis.fetch = mockJSON(201, {
+      tenant: SAMPLE,
+      invite_url: "http://mock/invite",
+    });
+    const res = await createTenant({ slug: "x", name: "X", admin_email: "a@b.test" });
+    expect(res.ok).toBe(true);
+    if (res.ok) {
+      expect(res.tenant.slug).toBe("acme");
+      expect(res.invite_url).toBe("http://mock/invite");
+    }
+  });
+  test("409 maps to slug_taken", async () => {
+    globalThis.fetch = mockJSON(409, {});
+    expect(await createTenant({ slug: "x", name: "X" })).toEqual({
+      ok: false,
+      error: "slug_taken",
+    });
+  });
+});
+
+describe("coverage gaps", () => {
+  test("startTrial 404 maps to tenant_not_found", async () => {
+    globalThis.fetch = mockJSON(404, {});
+    expect(await startTrial("t1", "x")).toEqual({
+      ok: false,
+      error: "tenant_not_found",
+    });
+  });
+  test("startTrial unexpected status surfaces with code", async () => {
+    globalThis.fetch = mockJSON(503, {});
+    expect(await startTrial("t1", "x")).toEqual({ ok: false, error: "unexpected_503" });
+  });
+  test("createTenant 400 maps to invalid_input", async () => {
+    globalThis.fetch = mockJSON(400, {});
+    expect(await createTenant({ slug: "x", name: "X" })).toEqual({
+      ok: false,
+      error: "invalid_input",
+    });
+  });
+  test("createTenant unexpected status surfaces with code", async () => {
+    globalThis.fetch = mockJSON(500, {});
+    expect(await createTenant({ slug: "x", name: "X" })).toEqual({
+      ok: false,
+      error: "unexpected_500",
+    });
+  });
+  test("req() handles 204 with null data", async () => {
+    // Use a verb that returns 204 — none of our endpoints do, but make sure
+    // the helper handles it. Simulate via fetchEntitlements with 204.
+    globalThis.fetch = vi.fn<typeof fetch>(async () => new Response(null, { status: 204 }));
+    await expect(fetchEntitlements("t1")).rejects.toThrow();
+  });
+  test("fetchCatalog with no data throws", async () => {
+    globalThis.fetch = vi.fn<typeof fetch>(async () =>
+      new Response("not-json", { status: 200, headers: { "content-type": "text/plain" } }),
+    );
+    await expect(fetchCatalog()).rejects.toThrow();
   });
 });

src/lib/tenant-registry.ts

@@ -1,29 +1,159 @@
-// Tenant Registry client — fetches tenant data from the Go service.
-// Skeleton-mode: read-only by-slug lookup. The portal middleware uses this
-// to resolve `<slug>.localhost:3000` → tenant context before rendering.
+// Tenant Registry client — covers everything the portal needs to call
+// from server components and server actions.
 
 export type Tenant = {
   id: string;
   slug: string;
   name: string;
   status: "active" | "trial" | "frozen" | "archived" | "demo";
+  kind: "customer" | "demo";
   plan: "starter" | "professional" | "enterprise";
-  products: string[];
+  trial_ends_at?: string | null;
   created_at: string;
+  updated_at: string;
+};
+
+export type CatalogEntry = {
+  key: string;
+  name: string;
+  description: string;
+  plans_required: string[];
+  supports_trial: boolean;
+  demo_url?: string;
+};
+
+export type Entitlement = {
+  tenant_id: string;
+  product: string;
+  enabled: boolean;
+  config: Record<string, unknown>;
+  expires_at?: string | null;
 };
 
 function baseUrl(): string {
   return process.env.TENANT_REGISTRY_URL ?? "http://localhost:8090";
 }
 
-export async function fetchTenantBySlug(slug: string): Promise<Tenant | null> {
-  const res = await fetch(`${baseUrl()}/v1/tenants/by-slug/${encodeURIComponent(slug)}`, {
+async function req<T>(
+  method: string,
+  path: string,
+  body?: unknown,
+): Promise<{ status: number; data: T | null }> {
+  const init: RequestInit = {
+    method,
     headers: { accept: "application/json" },
     cache: "no-store",
-  });
-  if (res.status === 404) return null;
-  if (!res.ok) {
-    throw new Error(`tenant-registry: ${res.status} ${res.statusText}`);
+  };
+  if (body !== undefined) {
+    init.body = JSON.stringify(body);
+    init.headers = { ...init.headers, "content-type": "application/json" };
   }
-  return (await res.json()) as Tenant;
+  const res = await fetch(`${baseUrl()}${path}`, init);
+  if (res.status === 204) return { status: 204, data: null };
+  const data = (await res.json().catch(() => null)) as T | null;
+  return { status: res.status, data };
+}
+
+// ─── reads ───────────────────────────────────────────────────────────────
+
+export async function fetchTenantBySlug(slug: string): Promise<Tenant | null> {
+  const { status, data } = await req<Tenant>(
+    "GET",
+    `/v1/tenants/by-slug/${encodeURIComponent(slug)}`,
+  );
+  if (status === 404) return null;
+  if (status >= 400 || !data) {
+    throw new Error(`tenant-registry: GET tenant ${status}`);
+  }
+  return data;
+}
+
+export async function fetchCatalog(): Promise<CatalogEntry[]> {
+  const { status, data } = await req<{ items: CatalogEntry[] }>(
+    "GET",
+    "/v1/catalog",
+  );
+  if (status !== 200 || !data) {
+    throw new Error(`tenant-registry: GET catalog ${status}`);
+  }
+  return data.items;
+}
+
+export async function fetchEntitlements(tenantId: string): Promise<Entitlement[]> {
+  const { status, data } = await req<{ items: Entitlement[] }>(
+    "GET",
+    `/v1/entitlements?tenant_id=${encodeURIComponent(tenantId)}`,
+  );
+  if (status === 404) return [];
+  if (status !== 200 || !data) {
+    throw new Error(`tenant-registry: GET entitlements ${status}`);
+  }
+  return data.items;
+}
+
+// ─── mutations ───────────────────────────────────────────────────────────
+
+export type RequestProductResult =
+  | { ok: true }
+  | { ok: false; error: string };
+
+export async function requestProduct(
+  tenantId: string,
+  product: string,
+): Promise<RequestProductResult> {
+  const { status } = await req<unknown>("POST", "/v1/catalog/request", {
+    tenant_id: tenantId,
+    product,
+  });
+  if (status === 202) return { ok: true };
+  if (status === 404) return { ok: false, error: "tenant_not_found" };
+  if (status === 400) return { ok: false, error: "invalid_input" };
+  return { ok: false, error: `unexpected_${status}` };
+}
+
+export type StartTrialResult =
+  | { ok: true; entitlement: Entitlement }
+  | { ok: false; error: string };
+
+export async function startTrial(
+  tenantId: string,
+  product: string,
+): Promise<StartTrialResult> {
+  const { status, data } = await req<Entitlement>(
+    "POST",
+    "/v1/catalog/trial-request",
+    { tenant_id: tenantId, product },
+  );
+  if (status === 201 && data) return { ok: true, entitlement: data };
+  if (status === 404) return { ok: false, error: "tenant_not_found" };
+  if (status === 400) return { ok: false, error: "invalid_input" };
+  return { ok: false, error: `unexpected_${status}` };
+}
+
+export type CreateTenantInput = {
+  slug: string;
+  name: string;
+  plan?: "starter" | "professional" | "enterprise";
+  admin_email?: string;
+  admin_name?: string;
+};
+
+export type CreateTenantResult =
+  | { ok: true; tenant: Tenant; invite_url?: string }
+  | { ok: false; error: string };
+
+export async function createTenant(
+  in_: CreateTenantInput,
+): Promise<CreateTenantResult> {
+  const { status, data } = await req<{ tenant: Tenant; invite_url?: string }>(
+    "POST",
+    "/v1/tenants",
+    in_,
+  );
+  if (status === 201 && data) {
+    return { ok: true, tenant: data.tenant, invite_url: data.invite_url };
+  }
+  if (status === 409) return { ok: false, error: "slug_taken" };
+  if (status === 400) return { ok: false, error: "invalid_input" };
+  return { ok: false, error: `unexpected_${status}` };
 }