@odla-ai/chapter 0.12.0 → 0.14.0

package/README.md

@@ -241,6 +241,15 @@ These bite silently — a smoke test won't catch them:
   it, because the moment it would fire — approval — is a host route (approval is
   out of scope, above). Send it from your own approve handler via `sendTemplated`;
   the seed existing does not mean the built-ins send it.
+- **Server-side Clerk is exported, even though the admin *routes* aren't.** A role
+  change is your host route — but you don't hand-roll the Clerk REST calls for it.
+  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`.
 
 ### Verify from the types, not this file
 

package/dist/index.cjs

@@ -34,7 +34,12 @@ __export(index_exports, {
   canceledPatch: () => canceledPatch,
   chapterDb: () => chapterDb,
   clampArray: () => clampArray,
+  clerkGetUser: () => clerkGetUser,
+  clerkGetUserByEmail: () => clerkGetUserByEmail,
+  clerkIntegration: () => clerkIntegration,
   clerkInviteRequest: () => clerkInviteRequest,
+  clerkListUsers: () => clerkListUsers,
+  clerkSetRole: () => clerkSetRole,
   clerkUserRequest: () => clerkUserRequest,
   createChapterIntegration: () => createChapterIntegration,
   createClerkInvitation: () => createClerkInvitation,
@@ -972,6 +977,119 @@ async function createClerkUser(secretKey, input, fetchImpl = fetch) {
   return { ...healed, refreshed };
 }
 
+// src/clerk-roles.ts
+var CLERK_API = "https://api.clerk.com";
+var DEFAULT_ROLE = "provisional";
+var PAGE = 100;
+function toRecord(u) {
+  if (typeof u.id !== "string") return null;
+  const pm = u.public_metadata ?? {};
+  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 };
+}
+async function clerkGet(path, secretKey, fetchImpl) {
+  const res = await fetchImpl(`${CLERK_API}${path}`, { headers: { authorization: `Bearer ${secretKey}` } });
+  if (!res.ok) throw new Error(`clerk GET ${path} \u2192 ${res.status}`);
+  return res.json();
+}
+async function clerkGetUserByEmail(secretKey, email, fetchImpl = fetch) {
+  const data = await clerkGet(`/v1/users?email_address=${encodeURIComponent(email)}&limit=1`, secretKey, fetchImpl).catch(() => null);
+  const user = Array.isArray(data) ? data[0] : void 0;
+  return user ? toRecord(user) : null;
+}
+async function clerkGetUser(secretKey, id2, fetchImpl = fetch) {
+  const data = await clerkGet(`/v1/users/${encodeURIComponent(id2)}`, secretKey, fetchImpl).catch(() => null);
+  return data ? toRecord(data) : null;
+}
+async function clerkListUsers(secretKey, fetchImpl = fetch) {
+  const out = [];
+  for (let offset = 0; ; offset += PAGE) {
+    const data = await clerkGet(`/v1/users?limit=${PAGE}&offset=${offset}`, secretKey, fetchImpl);
+    const page = Array.isArray(data) ? data : [];
+    for (const u of page) {
+      const record = toRecord(u);
+      if (record) out.push(record);
+    }
+    if (page.length < PAGE) break;
+  }
+  return out;
+}
+async function clerkSetRole(secretKey, id2, role, fetchImpl = fetch) {
+  const res = await fetchImpl(`${CLERK_API}/v1/users/${encodeURIComponent(id2)}/metadata`, {
+    method: "PATCH",
+    headers: { authorization: `Bearer ${secretKey}`, "content-type": "application/json" },
+    body: JSON.stringify({ public_metadata: { role } })
+  });
+  return res.ok;
+}
+
+// src/clerk-integration.ts
+var clerkIntegration = {
+  id: "clerk",
+  title: "Clerk end-user auth",
+  npm: "@odla-ai/chapter",
+  settings: [
+    {
+      key: "publishableKey",
+      description: "Clerk publishable key (pk_*). Public by design; served to the SPA (loads clerk-js from Clerk's CDN via @odla-ai/auth-clerk).",
+      public: true,
+      pattern: "pk_",
+      perEnv: true,
+      source: "apps-registry auth[env].publishableKey (from odla.config.mjs auth.clerk.<env>)"
+    }
+  ],
+  secrets: [
+    {
+      key: "CLERK_WEBHOOK_SECRET",
+      description: "Svix signing secret for Clerk user webhooks \u2014 verifies $users sync events.",
+      pattern: "whsec_",
+      mode: "full",
+      vault: true
+    },
+    {
+      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.",
+      pattern: "sk_",
+      mode: "full",
+      vault: true
+    }
+  ],
+  syncs: [
+    {
+      engine: "@odla-ai/db $users (Clerk webhook -> tenant graph)",
+      direction: "provider->odla",
+      entity: "$users",
+      // Matches the webhook mapper: the mirror carries id + primary email + name + avatar.
+      fields: ["id", "email", "name", "imageUrl"],
+      webhook: "whsec_ (svix-signed)",
+      onDelete: "tombstone (never row-delete)"
+    },
+    {
+      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"],
+      onDelete: "n/a (writes only)"
+    }
+  ],
+  provision: {
+    human: [
+      "Run `npx clerk auth login` \u2014 the one interactive step; the agent then creates + configures the Clerk app with the Clerk CLI (no pk_ to hand-paste).",
+      'For auth mode "full": create the Clerk user-sync webhook and store its whsec_, plus the sk_ as clerk_secret_key, in the tenant vault (Studio, write-only).'
+    ],
+    cli: [
+      "Clerk CLI (`npx clerk apps create/link/config patch`) creates + configures the instance and pulls the pk_.",
+      "odla `provision` records it: setAuth(env, publishableKey) -> apps-registry (issuer/JWKS derived from the key)."
+    ],
+    doctor: [
+      "registry auth[env] present when the app mounts <SignIn>?",
+      'auth mode "full" => whsec_ and clerk_secret_key present in the tenant vault?'
+    ]
+  }
+};
+
 // src/session.ts
 function applicationSummary(app) {
   return {