create-ailk 0.15.0 → 0.16.0

package/templates/apps/api/src/services/person.ts

@@ -0,0 +1,541 @@
+/**
+ * @file person.ts
+ * @description Person — one client of one workspace (#852, spec
+ * docs/specs/852-person-the-per-workspace-client-spec.md D3, D5, D6). This
+ * file is the ONLY writer of `Person`:
+ *
+ *   - `findOrCreatePerson` — the one creator, called by lead capture
+ *     (`lead-routing.ts`), the hub's own Stripe checkout webhook (through
+ *     `recordCheckoutPerson` below), appointment creation
+ *     (`scheduling/appointments.ts`) and the Admin inbox accept
+ *     (`inbox-messages.ts`).
+ *   - `stampPersonUser` — links a Person to a User, only on a verified-email
+ *     match, never overwriting a link.
+ *   - `recordCheckoutPerson` — the webhook's step: the Person of a completed
+ *     hub checkout, with its live-mode customer id.
+ *   - `resolveMemberPersonId` — the member reads' Person (#7877 D8): the one
+ *     linked to the caller, else the one whose email is the caller's
+ *     verified email, linked on first read by `stampPersonUser`'s rule.
+ *   - `resolveCallerBillingCustomerId` — the customer id the hub vouches for
+ *     in `GET /v1/hub-sign-in/me` (#7961, spec 7894 D13): that same Person's,
+ *     only while its `userId` is the caller.
+ *   - `setPersonPlanOffering` — the plan's only writer (#7877 D8), called by
+ *     the Admin's plan route and the checkout-lead rule in `lead-routing.ts`.
+ *
+ * ## Match order (D3) — fixed, and there is no merge
+ *
+ * 1. Normalize the email (trim ASCII whitespace, lowercase ASCII letters);
+ *    not storable → `invalid_email`, before any read.
+ * 2. A customer id given → the oldest Person of this workspace carrying it.
+ *    A hit is returned with NO write — its email is never rewritten.
+ * 3. The Person of this workspace with this email. A hit gains the customer
+ *    id only when it has none AND is linked to no user (first writer wins,
+ *    else `billing: "kept"`), and a name only when it has none. The email is
+ *    whatever the caller typed, never verified here, so it never pins a
+ *    customer on a Person whose `userId` the verified-email stamp set
+ *    (SEC-7894-6, decided on #7961 2026-10-09).
+ * 4. No hit → `createMany({ skipDuplicates })` — Postgres INSERT … ON
+ *    CONFLICT DO NOTHING — then a re-read that finds the winner of any
+ *    concurrent create. The duplicate is absorbed IN THE DATABASE, never as
+ *    a caught P2002: the appointment path calls this inside an interactive
+ *    transaction, where a raised unique violation aborts the transaction
+ *    (C4). One implementation serves both.
+ *
+ * ## Why public, and what it may import (D3)
+ *
+ * The base-tree `lead-routing.ts` imports this file, so it ships in every
+ * build and must never reach the paid import closure: it imports
+ * `lib/prisma.js`, `verified-email.js` and types only — never
+ * `lead-promotion.ts`, `owner-workspaces.ts`, `lead-accept-user.ts` (whose
+ * find-or-create shape it mirrors) or `lib/tenant-db.ts`.
+ * `packages/create-ailk/__tests__/paid-module-exclusions.test.ts` holds this
+ * file and `lead-routing.ts` in `MUST_SHIP`.
+ *
+ * ## Tenancy
+ *
+ * Every `Person` statement is scoped by a server-resolved `workspaceId`;
+ * there is no list read here (the reads are `tenantDb(tenant).people`).
+ * `recordCheckoutPerson`'s two other reads are by a server-minted
+ * `FlowCheckout` id from a signature-verified webhook, matched on that
+ * session's own `stripeSessionId`, then that row's lead scoped by the row's
+ * own `workspaceId`. `resolveMemberPersonId` reads by `(workspaceId, userId)`
+ * and by `(workspaceId, email)`, and `resolveCallerBillingCustomerId` by
+ * `(id, workspaceId, userId)`, the workspace server-resolved and the user
+ * the authenticated caller. `architecture.yaml` names this file as an
+ * exclusion with that reason.
+ *
+ * ## Errors and logs
+ *
+ * A store error is caught and returned as a bare kind; no Prisma message is
+ * returned or logged (SEC-006). These functions log nothing: each caller
+ * logs the outcome kind, never an email, a name or a customer id. The
+ * exceptions are `resolveMemberPersonId`, whose `null` hides a refused stamp,
+ * and `resolveCallerBillingCustomerId`, whose `null` hides a failed read: each
+ * logs that outcome's kind through the logger its caller passes.
+ */
+
+import type { Prisma } from "@working-theory/database";
+import type { Id } from "@working-theory/ids";
+
+import { prisma } from "../lib/prisma.js";
+
+import { findVerifiedEmail } from "./verified-email.js";
+
+// ─── Normalization ────────────────────────────────────────────────────────────
+
+/** The ASCII whitespace the backfill's btrim set names: SP, HT, LF, CR, FF, VT. */
+const EDGE_WHITESPACE = /^[ \t\n\r\f\v]+|[ \t\n\r\f\v]+$/g;
+/** Printable ASCII, one `@`, a non-empty side each — the `people_email_normalized` CHECK. */
+const STORABLE_EMAIL = /^[!-?A-~]+@[!-?A-~]+$/;
+const MAX_EMAIL_LENGTH = 254;
+const MAX_NAME_CODE_POINTS = 200;
+const MAX_CUSTOMER_ID_LENGTH = 255;
+/** C0 and C1 controls and the bidi controls, removed from a name (SEC-852-I). */
+// eslint-disable-next-line no-control-regex -- the control-character range is exactly what a stored name must not carry.
+const NAME_STRIP = /[\u0000-\u001F\u007F-\u009F\u200E\u200F\u202A-\u202E\u2066-\u2069]/g;
+
+/**
+ * Trim ASCII whitespace, then lowercase ASCII letters only — the same value
+ * Postgres computes as `lower(btrim(x, E' \t\n\r\f\x0B') COLLATE "C")`.
+ */
+export function normalizePersonEmail(raw: string): string {
+  return raw
+    .replace(EDGE_WHITESPACE, "")
+    .replace(/[A-Z]/g, (c) => c.toLowerCase());
+}
+
+/**
+ * Printable ASCII, one `@` with a non-empty side each, at most 254
+ * characters — the `people_email_normalized` CHECK's regex. ASCII only, so
+ * the TypeScript length and the Postgres length agree.
+ */
+export function isStorablePersonEmail(email: string): boolean {
+  return email.length <= MAX_EMAIL_LENGTH && STORABLE_EMAIL.test(email);
+}
+
+/**
+ * A name as stored: controls and bidi controls removed, trimmed of spaces, cut
+ * to 200 code points; empty → `null`.
+ */
+export function normalizePersonName(raw: unknown): string | null {
+  if (typeof raw !== "string") return null;
+  // Spaces only, as the backfill's `btrim(x)` trims, so a live-written
+  // name and a backfilled one agree.
+  const cleaned = Array.from(raw.replace(NAME_STRIP, "").replace(/^ +| +$/g, ""))
+    .slice(0, MAX_NAME_CODE_POINTS)
+    .join("");
+  return cleaned === "" ? null : cleaned;
+}
+
+function usableCustomerId(raw: string | null | undefined): string | null {
+  return typeof raw === "string" &&
+    raw.length > 0 &&
+    raw.length <= MAX_CUSTOMER_ID_LENGTH
+    ? raw
+    : null;
+}
+
+// ─── findOrCreatePerson ───────────────────────────────────────────────────────
+
+/** The one delegate this file writes through — the shared client or a transaction's. */
+export type PersonDb = Pick<Prisma.TransactionClient, "person">;
+
+export type FindOrCreatePersonResult =
+  | {
+      ok: true;
+      value: {
+        personId: Id<"person">;
+        created: boolean;
+        billing: "written" | "kept" | "unchanged";
+      };
+    }
+  | { ok: false; error: { kind: "invalid_email" | "internal_error" } };
+
+type MatchedPerson = {
+  id: string;
+  name: string | null;
+  userId: string | null;
+  billingCustomerId: string | null;
+};
+
+const MATCH_SELECT = {
+  id: true,
+  name: true,
+  userId: true,
+  billingCustomerId: true,
+} as const;
+
+/**
+ * Step 3's writes on an email match: the customer id only when the Person
+ * has none and is linked to no user, the name only when it has none — each
+ * one guarded `updateMany`, so a concurrent writer's value, or a stamp that
+ * lands between the read and the write, is never overwritten or bypassed.
+ */
+async function enrichMatched(
+  db: PersonDb,
+  workspaceId: string,
+  person: MatchedPerson,
+  name: string | null,
+  customerId: string | null,
+): Promise<"written" | "kept" | "unchanged"> {
+  let billing: "written" | "kept" | "unchanged" = "unchanged";
+  if (customerId !== null) {
+    if (person.billingCustomerId !== null || person.userId !== null) {
+      billing = "kept";
+    } else {
+      const written = await db.person.updateMany({
+        where: { id: person.id, workspaceId, userId: null, billingCustomerId: null },
+        data: { billingProvider: "stripe", billingCustomerId: customerId },
+      });
+      billing = written.count === 1 ? "written" : "kept";
+    }
+  }
+  if (name !== null && person.name === null) {
+    await db.person.updateMany({
+      where: { id: person.id, workspaceId, name: null },
+      data: { name },
+    });
+  }
+  return billing;
+}
+
+/**
+ * Find this workspace's Person for an email, or create it.
+ *
+ * @param workspaceId the SERVER-RESOLVED workspace id — never a request value.
+ * @param input.email the raw address; normalized here.
+ * @param input.name an optional display name, from anonymous text.
+ * @param input.billingCustomerId an optional provider customer id.
+ * @param db the shared client by default; the appointment path passes its
+ *   transaction client so the step runs on the lock's own connection.
+ */
+export async function findOrCreatePerson(
+  workspaceId: string,
+  input: {
+    email: string;
+    name?: string | null;
+    billingCustomerId?: string | null;
+  },
+  db: PersonDb = prisma,
+): Promise<FindOrCreatePersonResult> {
+  const email =
+    typeof input.email === "string" ? normalizePersonEmail(input.email) : "";
+  if (!isStorablePersonEmail(email)) {
+    return { ok: false, error: { kind: "invalid_email" } };
+  }
+  const name = normalizePersonName(input.name);
+  const customerId = usableCustomerId(input.billingCustomerId);
+
+  try {
+    // Step 2 — a customer id names its Person; nothing is written.
+    if (customerId !== null) {
+      const byCustomer = await db.person.findFirst({
+        where: { workspaceId, billingCustomerId: customerId },
+        orderBy: [{ createdAt: "asc" }, { id: "asc" }],
+        select: { id: true },
+      });
+      if (byCustomer) {
+        return {
+          ok: true,
+          value: {
+            personId: byCustomer.id as Id<"person">,
+            created: false,
+            billing: "unchanged",
+          },
+        };
+      }
+    }
+
+    // Step 3 — the email's Person.
+    const byEmail = await db.person.findFirst({
+      where: { workspaceId, email },
+      select: MATCH_SELECT,
+    });
+    if (byEmail) {
+      const billing = await enrichMatched(db, workspaceId, byEmail, name, customerId);
+      return {
+        ok: true,
+        value: { personId: byEmail.id as Id<"person">, created: false, billing },
+      };
+    }
+
+    // Step 4 — insert, absorbing a concurrent duplicate in the database.
+    const inserted = await db.person.createMany({
+      data: [
+        {
+          workspaceId,
+          email,
+          name,
+          ...(customerId !== null && {
+            billingProvider: "stripe",
+            billingCustomerId: customerId,
+          }),
+        },
+      ],
+      skipDuplicates: true,
+    });
+    const winner = await db.person.findFirst({
+      where: { workspaceId, email },
+      select: MATCH_SELECT,
+    });
+    if (!winner) return { ok: false, error: { kind: "internal_error" } };
+    if (inserted.count === 1) {
+      return {
+        ok: true,
+        value: {
+          personId: winner.id as Id<"person">,
+          created: true,
+          billing: customerId !== null ? "written" : "unchanged",
+        },
+      };
+    }
+    // A concurrent create won the race: treat its row as an email match.
+    const billing = await enrichMatched(db, workspaceId, winner, name, customerId);
+    return {
+      ok: true,
+      value: { personId: winner.id as Id<"person">, created: false, billing },
+    };
+  } catch {
+    return { ok: false, error: { kind: "internal_error" } };
+  }
+}
+
+// ─── stampPersonUser (D5) ─────────────────────────────────────────────────────
+
+export type StampPersonUserOutcome =
+  | "stamped"
+  | "already_linked"
+  | "user_unverified"
+  | "email_mismatch"
+  | "linked_to_other_user"
+  | "user_on_other_person"
+  | "not_found"
+  | "internal_error";
+
+function isUniqueViolation(err: unknown): boolean {
+  return (
+    typeof err === "object" &&
+    err !== null &&
+    (err as { code?: unknown }).code === "P2002"
+  );
+}
+
+/**
+ * Link a Person to a User — only when the User's VERIFIED email normalizes
+ * to the Person's (`verified-email.ts`'s rule), and never over an existing
+ * link. Creating a Person never calls this: no verified email is needed to
+ * exist. Runs outside any transaction, so catching a P2002 is safe here.
+ */
+export async function stampPersonUser(
+  workspaceId: string,
+  personId: string,
+  userId: string,
+): Promise<StampPersonUserOutcome> {
+  try {
+    const person = await prisma.person.findFirst({
+      where: { id: personId, workspaceId },
+      select: { email: true, userId: true },
+    });
+    if (!person) return "not_found";
+    if (person.userId === userId) return "already_linked";
+    if (person.userId !== null) return "linked_to_other_user";
+
+    const verified = await findVerifiedEmail(userId);
+    if (!verified.ok) return "user_unverified";
+    if (normalizePersonEmail(verified.value.email) !== person.email) {
+      return "email_mismatch";
+    }
+
+    let count: number;
+    try {
+      ({ count } = await prisma.person.updateMany({
+        where: { id: personId, workspaceId, userId: null },
+        data: { userId },
+      }));
+    } catch (err) {
+      if (isUniqueViolation(err)) return "user_on_other_person";
+      throw err;
+    }
+    if (count === 1) return "stamped";
+
+    const reread = await prisma.person.findFirst({
+      where: { id: personId, workspaceId },
+      select: { userId: true },
+    });
+    if (!reread) return "not_found";
+    return reread.userId === userId ? "already_linked" : "linked_to_other_user";
+  } catch {
+    return "internal_error";
+  }
+}
+
+// ─── recordCheckoutPerson (D6) ────────────────────────────────────────────────
+
+export type CheckoutPersonOutcome =
+  | "person_written"
+  | "person_kept"
+  | "person_unchanged"
+  | "person_skipped"
+  | "person_failed";
+
+/**
+ * The hub webhook's Person step for a paid `checkout.session.completed` of
+ * its OWN site carrying `metadata.flowCheckoutId`.
+ *
+ * Reads the checkout row THIS session completed (`stripeSessionId` must be
+ * this session's id and the row `completed`), so a session that merely names
+ * another checkout's id matches nothing (SEC-852-H); then that row's lead,
+ * scoped by the row's workspace. The customer id's one source is
+ * `session.customer`, and it is passed only for a LIVE-mode event: a
+ * test-mode checkout typed with someone else's email cannot pin a customer
+ * id on their Person (SEC-852-A). Never throws.
+ */
+export async function recordCheckoutPerson(input: {
+  flowCheckoutId: string;
+  stripeSessionId: string | null | undefined;
+  customer: unknown;
+  livemode: boolean;
+}): Promise<CheckoutPersonOutcome> {
+  if (typeof input.stripeSessionId !== "string" || input.stripeSessionId === "") {
+    return "person_skipped";
+  }
+  try {
+    const checkout = await prisma.flowCheckout.findFirst({
+      where: {
+        id: input.flowCheckoutId,
+        stripeSessionId: input.stripeSessionId,
+        status: "completed",
+      },
+      select: { leadId: true, workspaceId: true },
+    });
+    if (!checkout) return "person_skipped";
+
+    const lead = await prisma.lead.findFirst({
+      where: { id: checkout.leadId, workspaceId: checkout.workspaceId },
+      select: { email: true },
+    });
+    if (!lead) return "person_skipped";
+
+    const customerId =
+      input.livemode === true && typeof input.customer === "string"
+        ? input.customer
+        : undefined;
+    const result = await findOrCreatePerson(checkout.workspaceId, {
+      email: lead.email,
+      ...(customerId !== undefined && { billingCustomerId: customerId }),
+    });
+    if (!result.ok) {
+      return result.error.kind === "invalid_email" ? "person_skipped" : "person_failed";
+    }
+    switch (result.value.billing) {
+      case "written":
+        return "person_written";
+      case "kept":
+        return "person_kept";
+      default:
+        return "person_unchanged";
+    }
+  } catch {
+    return "person_failed";
+  }
+}
+
+// ─── The member area (#7877 D8) ───────────────────────────────────────────────
+
+/**
+ * The Person a member read answers for: this workspace's Person linked to
+ * the caller, else the one whose email is the caller's VERIFIED email —
+ * linked now through `stampPersonUser` (its rule, unchanged) and the answer
+ * only on `stamped` or `already_linked`. `null` is "not a client here";
+ * every other stamp outcome, and a store error, is `null` too, logged by its
+ * kind only. Never throws.
+ *
+ * @param workspaceId the SERVER-RESOLVED workspace (the calling spoke's).
+ * @param userId the authenticated caller.
+ * @param verifiedEmail the caller's verified address, read by the caller.
+ */
+export async function resolveMemberPersonId(
+  workspaceId: string,
+  userId: string,
+  verifiedEmail: string,
+  log?: { warn: (obj: object, msg: string) => void },
+): Promise<string | null> {
+  let byEmail: { id: string } | null;
+  try {
+    const linked = await prisma.person.findFirst({
+      where: { workspaceId, userId },
+      select: { id: true },
+    });
+    if (linked) return linked.id;
+
+    byEmail = await prisma.person.findFirst({
+      where: { workspaceId, email: normalizePersonEmail(verifiedEmail) },
+      select: { id: true },
+    });
+  } catch {
+    // A store error is "not a client here" for this read: never thrown.
+    log?.warn({ event: "member-person-stamp", outcome: "internal_error" }, "[person] member read failed");
+    return null;
+  }
+  if (!byEmail) return null;
+
+  const outcome = await stampPersonUser(workspaceId, byEmail.id, userId);
+  if (outcome === "stamped" || outcome === "already_linked") return byEmail.id;
+  log?.warn({ event: "member-person-stamp", outcome }, "[person] member link refused");
+  return null;
+}
+
+/**
+ * The customer id the hub vouches for to a spoke's buy route (#7961, spec
+ * 7894 D13): the `billingCustomerId` of the Person `resolveMemberPersonId`
+ * answers for (workspace, caller), read only while that Person's `userId` is
+ * the caller — never a Person matched by email alone (SEC-7894-6). `null` is
+ * "no customer to reuse"; a store error is `null` too, logged by its kind
+ * only. Never throws.
+ *
+ * @param workspaceId the SERVER-RESOLVED workspace (the calling spoke's).
+ * @param userId the authenticated caller.
+ * @param verifiedEmail the caller's verified address, read by the caller.
+ */
+export async function resolveCallerBillingCustomerId(
+  workspaceId: string,
+  userId: string,
+  verifiedEmail: string,
+  log?: { warn: (obj: object, msg: string) => void },
+): Promise<string | null> {
+  const personId = await resolveMemberPersonId(workspaceId, userId, verifiedEmail, log);
+  if (personId === null) return null;
+  try {
+    const person = await prisma.person.findFirst({
+      where: { id: personId, workspaceId, userId },
+      select: { billingCustomerId: true },
+    });
+    return person?.billingCustomerId ?? null;
+  } catch {
+    log?.warn({ event: "buyer-customer-read", outcome: "internal_error" }, "[person] buyer read failed");
+    return null;
+  }
+}
+
+export type SetPlanOfferingOutcome = "set" | "not_found" | "internal_error";
+
+/**
+ * Set — or, with `null`, clear — a Person's plan: the ONE writer of
+ * `Person.planOffering`. One `updateMany` scoped by the server-resolved
+ * workspace; no row → `not_found`. Never throws.
+ */
+export async function setPersonPlanOffering(
+  workspaceId: string,
+  personId: string,
+  planOffering: string | null,
+): Promise<SetPlanOfferingOutcome> {
+  try {
+    const { count } = await prisma.person.updateMany({
+      where: { id: personId, workspaceId },
+      data: { planOffering },
+    });
+    return count === 0 ? "not_found" : "set";
+  } catch {
+    return "internal_error";
+  }
+}

package/templates/apps/web/.env.example

@@ -93,17 +93,26 @@ CONTENT_ADAPTER=mdx
 # NEXT_PUBLIC_AILK_API_URL=http://localhost:3002
 
 # =============================================================================
-# Listicle directory (#7521) — server-side only, never NEXT_PUBLIC_
+# Listicle directory (#7521) — switched on by the site's listing key (#7872)
 # =============================================================================
 # The site's public listing key: the SAME value apps/api reads as
 # AILK_LISTING_PUBLIC_KEY (single-tenant) or holds as a SiteListingConfig
 # publicKey row (multi-tenant). Public by design — it names a site, it grants
-# nothing — but it is read on the server only. When it is set and the paid
-# @working-theory/ui-signal-collectors package is installed, the page a live
-# listicle names as its landing page shows that listicle's accepted entries,
-# and each entry gets a page at /<landingPage>/<slug>. Unset, no page reads
+# nothing. When it is set and the paid @working-theory/ui-signal-collectors
+# package is installed, the page a live listicle names as its landing page
+# shows that listicle's accepted entries, and each entry gets a page at
+# /<landingPage>/<slug>. Unset, the listings module is off and no page reads
 # the directory. One web deployment is one site: a hub's spokes are separate
 # web deployments, each with its own key.
+#
+# Two names, one reader (lib/listings-config.ts):
+#   1. NEXT_PUBLIC_AILK_LISTING_SITE_KEY wins when set. It is inlined into the
+#      build, so changing or rotating it needs a rebuild — and while it is set,
+#      a runtime change to AILK_LISTING_PUBLIC_KEY has no effect.
+#   2. AILK_LISTING_PUBLIC_KEY is the fallback (server-read), so a site
+#      configured before this name existed keeps its directory on upgrade.
+# An empty value counts as unset.
+# NEXT_PUBLIC_AILK_LISTING_SITE_KEY=
 # AILK_LISTING_PUBLIC_KEY=
 
 # =============================================================================
@@ -191,6 +200,36 @@ CONTENT_ADAPTER=mdx
 #
 # AILK_AUTH_TRUSTED_PROXIES=
 
+# =============================================================================
+# Sign-in through the hub — a spoke scaffolded with --hub-sign-in (#7894)
+# =============================================================================
+# A spoke has no database and no Better Auth of its own. With --hub-sign-in, a
+# visitor signs in on the HUB's own sign-in page and returns to this site's
+# /account; the hub-issued credential lives in a sealed, HttpOnly cookie. All
+# four are server-only — never rename one with a NEXT_PUBLIC_ prefix — and all
+# four must be set, or /account says sign-in is not available yet. The routes
+# under /api/hub-session answer 404 on any site not scaffolded in this mode.
+#
+# The hub's WEB origin (where its /sign-in lives), https: or http: on
+# localhost. create-ailk writes it to .env.local.
+# AILK_HUB_SIGN_IN_URL=https://hub.example.com
+#
+# This site's client id and secret, issued on the hub with
+#   pnpm --filter @working-theory/api spokes sign-in-client --id <spoke_id> \
+#     --redirect-uri <this site's origin>/api/hub-session/callback
+# The client id is the spoke's id. The secret is shown once; keep it out of git.
+# AILK_HUB_CLIENT_ID=
+# AILK_HUB_CLIENT_SECRET=
+#
+# This site's own cookie key material: at least 32 characters, generated per
+# site (create-ailk writes one to .env.local; `openssl rand -base64 32` makes
+# another). Never the client secret. Changing it signs every visitor out.
+# AILK_HUB_SESSION_SECRET=
+#
+# The redirect URI is built from this site's NEXT_PUBLIC_BASE_URL (else the
+# baseUrl in content/_site.mdx) — never from a request's Host — so set it to
+# the origin you registered on the hub.
+
 # =============================================================================
 # Observability
 # =============================================================================
@@ -228,3 +267,17 @@ CONTENT_ADAPTER=mdx
 # (see the relay block above, #7644), so the baseline CSP's
 # `connect-src 'self'` already covers them — no CSP extension is needed for
 # them, whatever NEXT_PUBLIC_AILK_API_URL is set to.
+#
+# On a SPOKE (create-ailk --topology spoke, #7872) this site has no apps/api:
+# /meet lists the meeting types the hub stores for this spoke's workspace and
+# books through the hub at AILK_API_URL with AILK_SPOKE_KEY. Then:
+#   - the FIRST segment (the owner) must name the provider account the hub
+#     uses for this spoke's workspace (its scheduling connection). It composes
+#     each booker's calLink; it is not an access control — the hub checks a
+#     spoke booking's slug, never its owner.
+#   - the SECOND segment is ignored: a workspace with no stored meeting-type
+#     list shows no meetings, because the hub books only a slug it stores.
+#   - the booker's two calls count against the relay's per-visitor budget,
+#     which holds per visitor only behind an edge that overwrites
+#     x-forwarded-for and x-real-ip (Vercel does); elsewhere every visitor
+#     shares one budget.