@odla-ai/chapter 0.24.0 → 0.25.1

package/README.md

@@ -8,7 +8,7 @@ email. The host still builds the public pages, routing, and brand presentation;
 Chapter supplies their application mechanics.
 
 ```sh
-npm i --save-exact @odla-ai/chapter@0.24.0
+npm install @odla-ai/chapter
 ```
 
 > **Agentic experiment.** Built and maintained by AI agents from bounded runbooks
@@ -16,7 +16,14 @@ npm i --save-exact @odla-ai/chapter@0.24.0
 
 > **Pre-1.0.** The member surface, operational worker, standard admin console,
 > and leader → follower record delivery ship. APIs may still tighten before 1.0;
-> pin the package and run schema/route contract tests in every site.
+> commit the lockfile and run schema/route contract tests after every update.
+
+> **Ask the runbooks first.** odla's operational procedures live in a database,
+> not in this file: `npx @odla-ai/cli runbook ask "<question>"` returns the current
+> steps, and unlike anything written here it cannot be out of date. Use it before
+> searching the web or working from memory. This README and the JSDoc in the
+> shipped `.d.ts` are the version-matched **API** reference; a runbook is the
+> **procedure**. Most tasks need an answer from both.
 
 ## Agent runbooks
 
@@ -589,14 +596,18 @@ These bite silently — a smoke test won't catch them:
   that omits `account`, so forgetting the decision cannot silently disable or
   enable account provisioning. Both side-effecting models need
   `clerk_secret_key` in the tenant vault. Hub mode resolves to inert `"none"`.
-- **What lands on the Clerk account (and its `public_metadata` is
-  client-readable).** Both side-effecting models write `applicationId` and,
-  when explicitly selected fields are present, `profile`. The
-  `application.profileFields` default is `[]`, so application details remain
-  db-only. Set `profileFields: ["phone", "state", "focus"]` to a deliberate
-  browser-readable allowlist. Array fields
-  (`focus`) are clamped to `maxArrayLen` (default 100) and non-primitive elements
-  dropped, so a client can't post an unbounded array into metadata.
+- **What lands on the Clerk account.** `public_metadata` is reserved for small
+  browser/session-readable authorization claims such as `role`. Chapter writes
+  `applicationId` and the explicitly selected `profile` fields to backend-only
+  `private_metadata`; `application.profileFields` defaults to `[]`. Treat that
+  copy as a bounded account/admin snapshot—the application row and CRM remain
+  canonical. Array fields (`focus`) are clamped to `maxArrayLen` (default 100)
+  and non-primitive elements are dropped. `"create"` writes the private snapshot
+  with the account. Clerk application invitations cannot carry private
+  metadata, so `"invite"` completes the write on the accepted account's first
+  `/api/me` request. A one-time application marker prevents repeated Clerk API
+  writes. That repair also removes Chapter's former `applicationId` and
+  `profile` keys from public metadata without disturbing `role`.
   `applicantProfile(chapter, fields)` is exported to assert the exact shape in a
   test before deleting a local override.
 - **Email + input validation.** The field literally named `email` is checked
@@ -630,9 +641,14 @@ These bite silently — a smoke test won't catch them:
 - **CRM projection points.** chapter projects the person on application submit
   (`projectApplicant`), not on booking or on webhook status change. If you mirror
   pipeline stage into the CRM, keep those routes.
-- **Route names.** chapter serves `/api/config`, `/api/join-config`, etc. Alias
-  legacy names in ~4 lines with a host route in `chapterWorker({ routes })` rather
-  than rewriting pages.
+- **Route contracts, not route names.** Chapter serves `/api/config`,
+  `/api/join-config`, etc. Alias a legacy URL with a host route only after
+  method, auth, request, response shape, units, status, and header parity are
+  proven. Equal values with different JSON contracts are not compatible. For a
+  join flow, adopt `JoinIsland` end to end or keep an explicit tested adapter;
+  do not merely repoint an existing page at `/api/join-config`. `PaymentStep`
+  obtains Stripe's `clientSecret`, `publishableKey`, and `lineItems` from
+  `POST /api/payments/subscription`, not from the public join-config response.
 
 ### Install + scope notes
 
@@ -653,25 +669,23 @@ These bite silently — a smoke test won't catch them:
   `@odla-ai/auth-clerk/invitations` when you want to send your own branded
   invitation mail. Importing the full `@odla-ai/chapter/ui` barrel pulls the admin
   half, so prefer the narrower entry.
-- **Known-good application set** (installs clean, no flags):
-  `@odla-ai/chapter` 0.24.0, `@odla-ai/brand` 0.2.0,
-  `@odla-ai/ui` 0.12.1, `@odla-ai/crm` 0.3.1,
-  `@odla-ai/db` 0.6.7,
-  `@odla-ai/calendar` 0.2.0, `@odla-ai/email` 0.3.1,
-  `@odla-ai/auth-clerk` 0.4.1, `@odla-ai/o11y` 2.2.2, `jose` 6.2.3, and
-  Preact 10.29.7.
-- **Known-good Preact host toolchain:** `@odla-ai/cli` 0.17.1,
-  `@odla-ai/security` 0.3.1, `@cloudflare/workers-types` 4.20260702.1,
-  TypeScript 6.0.3, Vite 8.1.4, Vitest 4.1.10, and Wrangler 4.107.0. The
-  greenfield runbook standardizes on this exact Preact matrix.
+- **Use normal dependency declarations during active development.** Install
+  Chapter, its selected peers, and the Preact host toolchain without exact
+  pins. Commit `package-lock.json`, use `npm ci` for repeatable installs, record
+  `npm ls` output in PM evidence, and rerun conformance after updates. The
+  package manifest's dependency and peer ranges are the compatibility
+  contract.
 - **`--legacy-peer-deps` is a diagnostic, not a setting.** It suppresses exactly
   the peer conflict that tells you a pair is unsupported. If you need it, find out
   why first.
 - **The admin operational surface ships (0.16.0).** `/api/admin/*` is now a full
   membership-operations API, admin-gated (`verifyUser` + `isAdmin`):
   - **Roster/identity:** `GET /people` (union of `$users` + applications by email,
-    roles from `clerkListUsers`), `GET /people/access`, `POST /people/role`,
-    `POST /crm/sync` (backfill/reproject).
+    roles and backend-only profile signals from `clerkListUsers`),
+    `GET /people/access`, `POST /people/role`, `POST /crm/sync`
+    (backfill/reproject), and
+    `POST /clerk/private-profiles/sync?offset=0&limit=50` (bounded,
+    resumable migration/repair from Chapter's former public profile keys).
   - **Pipeline/meetings:** `GET /dashboard` (flow counts, stage counts + weekly
     delta, agenda, live revenue), `GET /meetings` (reconciled agenda),
     `GET/PUT /scheduling`, `POST /meetings/:id/{reschedule,cancel}`,
@@ -698,12 +712,14 @@ These bite silently — a smoke test won't catch them:
 - **The server-side Clerk primitives are exported too** — for host routes beyond
   the built-in `/people/role`. Beside
   `createClerkUser`/`createClerkInvitation`/`canChangeRole`, chapter exports
-  the odla→Clerk write half: `clerkGetUserByEmail`, `clerkGetUser`, `clerkListUsers`
-  (auto-paginated — never a silent 100-user cap), and `clerkSetRole`. Two
-  load-bearing semantics: an absent `public_metadata.role` reads as the lowest rung
-  (`"provisional"`), and `clerkSetRole` merge-`PATCH`es only `{ role }` so it never
-  clobbers a separately-written `public_metadata.profile`. All take an injectable
-  `fetch` and the vault `clerk_secret_key`.
+  the odla→Clerk write half: `clerkGetUserByEmail`, `clerkGetUser`,
+  `clerkListUsers` (auto-paginated — never a silent 100-user cap),
+  `clerkSetRole`, `updateClerkUserMetadata`, and
+  `updateClerkUserMetadataByEmail`. An absent `public_metadata.role` reads as
+  the lowest rung (`"provisional"`); normalized `profile` and `applicationId`
+  reads come only from backend-only private metadata; and `clerkSetRole`
+  merge-`PATCH`es only the public role, so it cannot clobber the private profile.
+  All take an injectable `fetch` and the vault `clerk_secret_key`.
 
 ### Verify from the types, not this file
 

package/dist/{copy-context-Dp5hvj5W.d.ts → copy-context-DI21CYQ3.d.ts}

@@ -300,10 +300,9 @@ interface ChapterApplication {
      *  writing a row with no consent record. Default `true`. Set `false`
      *  deliberately only when the site renders no consent control. */
     requireDisclaimerAck?: boolean;
-    /** Allowlist of fields that reach the Clerk account's client-readable
-     *  `public_metadata.profile`. Default `[]`, so application details remain
-     *  db-only. Set a curated list (e.g. `["phone", "state", "focus"]`) for
-     *  fields the browser may read. */
+    /** Allowlist of application fields mirrored into the Clerk account's
+     *  backend-only `private_metadata.profile`. Default `[]`. Use this for small
+     *  account/admin signals; the application row and CRM remain canonical. */
     profileFields?: readonly string[];
     /** Extra application fields carried into the one-way CRM projection, on top of
      *  the built-in identity/contact set. Each MUST be declared on your crm person

package/dist/index.cjs

@@ -101,6 +101,8 @@ __export(index_exports, {
   submitApplication: () => submitApplication,
   subscriptionIdempotencyKey: () => subscriptionIdempotencyKey,
   syncApplicationToCrm: () => syncApplicationToCrm,
+  updateClerkUserMetadata: () => updateClerkUserMetadata,
+  updateClerkUserMetadataByEmail: () => updateClerkUserMetadataByEmail,
   validateScheduling: () => validateScheduling,
   verifyStripeSignature: () => verifyStripeSignature,
   webhookMutationId: () => webhookMutationId
@@ -153,6 +155,10 @@ var applications = {
     meetingAt: attr("number", { indexed: true, optional: true }),
     meetingLink: attr("string", { optional: true }),
     clerkUserId: attr("string", { indexed: true, optional: true }),
+    // One-time/effect-repair marker. Absent means /api/me should copy the
+    // allowlisted application snapshot into Clerk private_metadata and remove
+    // the former public_metadata copy.
+    clerkPrivateMetadataSyncedAt: attr("number", { optional: true }),
     phone: attr("string", { optional: true }),
     state: attr("string", { optional: true }),
     groupId: attr("string", { indexed: true, optional: true }),
@@ -1611,23 +1617,30 @@ function clerkUserRequest(input) {
       skip_password_requirement: true,
       ...input.firstName ? { first_name: input.firstName } : {},
       ...input.lastName ? { last_name: input.lastName } : {},
-      ...input.publicMetadata ? { public_metadata: input.publicMetadata } : {}
+      ...input.publicMetadata !== void 0 ? { public_metadata: input.publicMetadata } : {},
+      ...input.privateMetadata !== void 0 ? { private_metadata: input.privateMetadata } : {}
     }
   };
 }
-async function refreshUserMetadata(secretKey, email, publicMetadata, fetchImpl) {
+async function updateClerkUserMetadata(secretKey, userId, input, fetchImpl = fetch) {
+  const res = await fetchImpl(`https://api.clerk.com/v1/users/${encodeURIComponent(userId)}/metadata`, {
+    method: "PATCH",
+    headers: { authorization: `Bearer ${secretKey}`, "content-type": "application/json" },
+    body: JSON.stringify({
+      ...input.publicMetadata !== void 0 ? { public_metadata: input.publicMetadata } : {},
+      ...input.privateMetadata !== void 0 ? { private_metadata: input.privateMetadata } : {}
+    })
+  });
+  return res.ok;
+}
+async function updateClerkUserMetadataByEmail(secretKey, email, input, fetchImpl = fetch) {
   const auth = { authorization: `Bearer ${secretKey}` };
   const found = await fetchImpl(`https://api.clerk.com/v1/users?email_address=${encodeURIComponent(email)}&limit=1`, { headers: auth });
   if (!found.ok) return false;
   const users = await found.json().catch(() => null);
   const id2 = Array.isArray(users) && typeof users[0]?.id === "string" ? users[0].id : void 0;
   if (!id2) return false;
-  const patched = await fetchImpl(`https://api.clerk.com/v1/users/${id2}/metadata`, {
-    method: "PATCH",
-    headers: { ...auth, "content-type": "application/json" },
-    body: JSON.stringify({ public_metadata: publicMetadata })
-  });
-  return patched.ok;
+  return updateClerkUserMetadata(secretKey, id2, input, fetchImpl);
 }
 async function createClerkUser(secretKey, input, fetchImpl = fetch) {
   const { path, body } = clerkUserRequest(input);
@@ -1638,8 +1651,15 @@ async function createClerkUser(secretKey, input, fetchImpl = fetch) {
   });
   if (res.ok) return { ok: true, status: res.status };
   const healed = heal(res.status);
-  if (!healed.existed || !input.publicMetadata) return healed;
-  const refreshed = await refreshUserMetadata(secretKey, input.email, input.publicMetadata, fetchImpl).catch(() => false);
+  const repair = input.repairMetadata ?? {
+    ...input.publicMetadata !== void 0 ? { publicMetadata: input.publicMetadata } : {},
+    ...input.privateMetadata !== void 0 ? { privateMetadata: input.privateMetadata } : {}
+  };
+  if (!healed.existed || repair.publicMetadata === void 0 && repair.privateMetadata === void 0) return healed;
+  const refreshed = await updateClerkUserMetadataByEmail(secretKey, input.email, {
+    ...repair.publicMetadata !== void 0 ? { publicMetadata: repair.publicMetadata } : {},
+    ...repair.privateMetadata !== void 0 ? { privateMetadata: repair.privateMetadata } : {}
+  }, fetchImpl).catch(() => false);
   return { ...healed, refreshed };
 }
 
@@ -1650,9 +1670,21 @@ var PAGE = 100;
 function toRecord(u) {
   if (typeof u.id !== "string") return null;
   const pm = u.public_metadata ?? {};
+  const privateMetadata = u.private_metadata ?? {};
+  const rawProfile = privateMetadata.profile;
+  const profile = rawProfile && typeof rawProfile === "object" && !Array.isArray(rawProfile) ? rawProfile : {};
+  const applicationId = typeof privateMetadata.applicationId === "string" ? privateMetadata.applicationId : void 0;
   const role = typeof pm.role === "string" && pm.role ? pm.role : DEFAULT_ROLE;
   const email = u.email_addresses?.[0]?.email_address;
-  return { id: u.id, email: typeof email === "string" ? email : void 0, role, publicMetadata: pm };
+  return {
+    id: u.id,
+    email: typeof email === "string" ? email : void 0,
+    role,
+    publicMetadata: pm,
+    privateMetadata,
+    profile,
+    ...applicationId ? { applicationId } : {}
+  };
 }
 async function clerkGet(path, secretKey, fetchImpl) {
   const res = await fetchImpl(`${CLERK_API}${path}`, { headers: { authorization: `Bearer ${secretKey}` } });
@@ -1715,7 +1747,7 @@ var clerkIntegration = {
     },
     {
       key: "clerk_secret_key",
-      description: "Clerk backend key (sk_*) \u2014 powers the odla->Clerk writes (account create, role + profile via public_metadata) and lets odla-db resolve user email/name via the Clerk API.",
+      description: "Clerk backend key (sk_*) \u2014 powers account creation, the public role claim, and backend-only private profile signals; it also lets odla-db resolve user email/name via the Clerk API.",
       pattern: "sk_",
       mode: "full",
       vault: true
@@ -1735,8 +1767,13 @@ var clerkIntegration = {
       engine: "@odla-ai/chapter clerk.ts (Clerk Backend API via vault clerk_secret_key)",
       direction: "odla->provider",
       entity: "clerk user",
-      // Separate merge-PATCHes so a role write never clobbers a profile write.
-      fields: ["public_metadata.role", "public_metadata.profile"],
+      // Separate metadata fields so a public role write cannot expose or
+      // clobber backend-only account/profile signals.
+      fields: [
+        "public_metadata.role",
+        "private_metadata.applicationId",
+        "private_metadata.profile"
+      ],
       onDelete: "n/a (writes only)"
     }
   ],