@odla-ai/chapter 0.13.0 → 0.15.0

package/README.md

@@ -151,11 +151,15 @@ These bite silently — a smoke test won't catch them:
   **Re-check this on every chapter upgrade.** Wiring a send changes a site's
   outbound mail with no local diff — release notes call out send changes
   explicitly for that reason.
-- **Account model.** `account: "invite"` (default) mints a Clerk invitation,
-  `"create"` makes the account server-side (so join can say the account is
-  ready), `"none"` skips it — all need `clerk_secret_key` in the tenant vault. A
-  site that wants server-side create must set `account: "create"`; inheriting the
-  default silently changes the model.
+- **Account model — the default is `"none"`, and that is deliberate.**
+  `account: "create"` makes the Clerk account server-side (so join can say the
+  account is ready), `"invite"` **emails the applicant a Clerk invitation**, and
+  `"none"` (the default) provisions nothing. Both non-default models need
+  `clerk_secret_key` in the tenant vault. The default is side-effect-free on
+  purpose: inviting mails a real person, and a site that never made that choice
+  must not be sending mail. **You must opt in — a site that wants accounts and
+  doesn't set `account` will silently provision none.** (Changed in 0.15.0: the
+  default was `"invite"`, which mailed applicants from a config nobody wrote.)
 - **What lands on the Clerk account (and its `public_metadata` is
   client-readable).** Both models write `public_metadata` as
   `{ applicationId, profile }`. By default `profile` is every configured
@@ -176,8 +180,11 @@ These bite silently — a smoke test won't catch them:
   A valid application is never newly rejected.
 - **CRM enrichment.** `projectApplicant` writes the base identity/contact person.
   To carry more of the application into the CRM, list `application: { crmFields:
-  [...] }` — each must be a field on your crm person type, else that field is
-  dropped and the base person still projects (it is never lost). Stage mirroring,
+  [...] }`. Each name is **cross-checked against your crm `person` type at
+  `defineChapter()` time and throws** if it isn't declared there — an undeclared
+  field would otherwise be dropped by the projection while the base person still
+  lands, making a typo invisible. (The runtime projection still falls back to the
+  base person if a write fails, so an applicant is never lost.) Stage mirroring,
   billing snapshots and Clerk-identity linking stay yours as host routes.
 - **Disclaimer acknowledgement.** A truthy `disclaimerAck` on the submit body
   (boolean or the string a plain form posts) stamps `disclaimerAckAt` from the

package/dist/index.cjs

@@ -36,6 +36,7 @@ __export(index_exports, {
   clampArray: () => clampArray,
   clerkGetUser: () => clerkGetUser,
   clerkGetUserByEmail: () => clerkGetUserByEmail,
+  clerkIntegration: () => clerkIntegration,
   clerkInviteRequest: () => clerkInviteRequest,
   clerkListUsers: () => clerkListUsers,
   clerkSetRole: () => clerkSetRole,
@@ -606,10 +607,23 @@ function defineChapter(config) {
   const application = resolveApplication(config.application);
   const { schema, rules } = chapterDb(mode, auth);
   const services = config.services ?? ["db", "calendar", "o11y"];
-  const account = config.account ?? "invite";
+  const account = config.account ?? "none";
   if (account !== "invite" && account !== "create" && account !== "none") {
     throw new Error(`defineChapter.account: must be "invite", "create", or "none" \u2014 got "${String(account)}"`);
   }
+  if (application.crmFields.length > 0) {
+    let personFields = null;
+    try {
+      personFields = Object.keys(crm.type("person").fields ?? {});
+    } catch {
+    }
+    const unknown = personFields ? application.crmFields.filter((f) => !personFields.includes(f)) : [];
+    if (unknown.length > 0) {
+      throw new Error(
+        `defineChapter.application.crmFields: ${unknown.map((f) => `"${f}"`).join(", ")} not declared on the CRM "person" type (declared: ${personFields?.join(", ")}). An undeclared field is silently dropped from the CRM projection \u2014 add it to your crm config's person fields, or remove it from crmFields.`
+      );
+    }
+  }
   const adminNotification = config.sends?.adminNotification ?? "submit";
   if (adminNotification !== "submit" && adminNotification !== "payment" && adminNotification !== "never") {
     throw new Error(
@@ -1023,6 +1037,72 @@ async function clerkSetRole(secretKey, id2, role, fetchImpl = fetch) {
   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 {