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