@odla-ai/chapter 0.7.0 → 0.8.0

package/README.md

@@ -97,18 +97,66 @@ export default {
 
 ## Adopting into an existing site
 
-1. **Schema + provisioning (safe, verifiable).** Replace a hand-rolled
-   `schema.mjs` / `rules.mjs` / group seed / provisioner with `defineChapter` +
-   `createChapterIntegration`. The emitted schema is directly comparable — diff
-   `chapter.schema` against your namespaces and expect byte-equality — so this is
-   a no-behavior-change deletion of hand-maintained code that also installs the
-   deny-all `crm_*` rules a hand-rolled provisioner tends to skip.
-2. **The worker.** Either use `chapterWorker({ chapter })` directly, or keep your
-   bespoke routes and pass them via `chapterWorker({ chapter, routes })` — they
-   run first and reuse chapter's auth through the shared context, so you never
-   verify a JWT twice. Path renames your frontend depends on are your own alias
-   routes in that array.
-
-Read `dist/*.d.ts` for the authoritative surface.
+A real conversion (the site this was extracted from) went from a 2,094-line
+worker to 6 lines and deleted ~2,500 lines. The order that worked:
+
+1. **Config first, assert parity BEFORE deleting anything.** `defineChapter()`
+   your site, then diff `chapter.schema` against your existing schema in a test
+   and require byte-equality. That single assertion is what makes the deletion
+   safe rather than hopeful.
+2. **Freeze the old schema as a test fixture** (e.g. `test/fixtures/legacy-schema.mjs`)
+   and keep asserting against it, so an upstream default change fails a test
+   instead of a live `provision`. It is the only durable guard against drift in a
+   generated schema.
+3. **Swap provisioning** — `createChapterIntegration(chapter)`, inert until the
+   next provision run. It supplies schema + rules + seeds, so your
+   `odla.config.mjs` `db` block goes away entirely.
+4. **Then the worker**, keeping every bespoke route as a host route
+   (`chapterWorker({ chapter, routes })`). Don't hand routes to chapter in the
+   same change as the framework swap.
+5. **Override rather than inherit** wherever local behavior was a decision.
+
+### Behavior deltas to audit
+
+These bite silently — a smoke test won't catch them:
+
+- **Per-field caps.** `application.defaultMaxLen` is 2000. If your form accepts
+  longer input, pass `maxLen` explicitly or the default starts rejecting it.
+- **`services` default** is `["db","calendar","o11y"]`; `smoke` compares config
+  against the platform, so set `services` explicitly if you don't run the o11y
+  collector.
+- **Which email fires from which route.** `adminNotification` fires from
+  `POST /api/applications` (on submit), `prepEmail` from `/api/schedule/book`,
+  `paymentConfirmation` from the Stripe webhook. If your policy differs (e.g.
+  notify on payment, not submit), override that route.
+- **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.
+- **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.
+
+### Install + scope notes
+
+- **Skip `@odla-ai/auth-clerk` for a worker-only adoption.** The worker never
+  imports it (JWTs are verified with `jose` via `ctx.verifyUser`); it is an
+  optional peer for `chapter/ui` only. Reach for `@odla-ai/auth-clerk/invitations`
+  when you want to send your own branded invitation mail.
+- **The admin surface is intentionally minimal** — `/api/admin/scheduling` +
+  `/api/admin/meetings`, plus `peopleSection`. Dashboard, billing, per-person
+  comms, approve/refund, etc. are your own host routes via the seam; don't plan
+  around them shipping.
+
+### Verify from the types, not this file
+
+At several releases a day, prose lags. Treat this README as intent and verify the
+real surface from `dist/*.d.ts` and by grepping the built bundle for route
+strings. One testing gotcha: Clerk session tokens expire in ~60s, so a script
+that mints a JWT then runs a batch of curls must re-mint per batch.
 
 MIT © odla

package/dist/index.cjs

@@ -33,8 +33,10 @@ __export(index_exports, {
   canceledPatch: () => canceledPatch,
   chapterDb: () => chapterDb,
   clerkInviteRequest: () => clerkInviteRequest,
+  clerkUserRequest: () => clerkUserRequest,
   createChapterIntegration: () => createChapterIntegration,
   createClerkInvitation: () => createClerkInvitation,
+  createClerkUser: () => createClerkUser,
   defaultCrm: () => defaultCrm,
   defineChapter: () => defineChapter,
   emailGroupFrom: () => emailGroupFrom,
@@ -308,7 +310,7 @@ Warmly,
 ${name}`;
   return {
     adminNotification: {
-      subject: `New application \u2014 {{firstName}} {{lastName}}`,
+      subject: `New application: {{firstName}} {{lastName}}`,
       text: `A new application came in for ${name}.
 
 Name: {{firstName}} {{lastName}}
@@ -327,7 +329,7 @@ Your membership payment is confirmed. We'll be in touch to schedule your intro c
 Looking forward to our call at {{meetingTime}}. {{meetingLink}}${sign}`
     },
     onboardingInvite: {
-      subject: `You're in \u2014 ${name}`,
+      subject: `You're in, ${name}`,
       text: `Hi {{firstName}},
 
 Welcome to ${name}. Your member area is here: {{membersUrl}}${sign}`
@@ -552,6 +554,10 @@ 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";
+  if (account !== "invite" && account !== "create" && account !== "none") {
+    throw new Error(`defineChapter.account: must be "invite", "create", or "none" \u2014 got "${String(account)}"`);
+  }
   const chapter = {
     config,
     id: id2,
@@ -564,6 +570,7 @@ function defineChapter(config) {
     schema,
     rules,
     services,
+    account,
     groupSeed: () => mode === "chapter" ? buildGroupSeed(config) : null
   };
   if (config.url !== void 0) chapter.url = config.url;
@@ -590,7 +597,7 @@ function createChapterIntegration(chapter, options = {}) {
   }
   return {
     id: "chapter",
-    title: `Chapter \u2014 ${chapter.name}`,
+    title: `Chapter: ${chapter.name}`,
     npm: "@odla-ai/chapter",
     schema: {
       entities: { ...crmDesc.schema.entities, ...chapter.schema.entities },
@@ -860,6 +867,26 @@ async function createClerkInvitation(secretKey, input, fetchImpl = fetch) {
   });
   return { ok: res.ok, status: res.status };
 }
+function clerkUserRequest(input) {
+  return {
+    path: "/v1/users",
+    body: {
+      email_address: [input.email],
+      skip_password_requirement: true,
+      ...input.firstName ? { first_name: input.firstName } : {},
+      ...input.lastName ? { last_name: input.lastName } : {}
+    }
+  };
+}
+async function createClerkUser(secretKey, input, fetchImpl = fetch) {
+  const { path, body } = clerkUserRequest(input);
+  const res = await fetchImpl(`https://api.clerk.com${path}`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${secretKey}`, "content-type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  return { ok: res.ok, status: res.status };
+}
 
 // src/session.ts
 function applicationSummary(app) {