@odla-ai/chapter 0.5.0 → 0.8.0

package/README.md

@@ -1,9 +1,10 @@
 # @odla-ai/chapter
 
-A foundation for **membership sites**. One `defineChapter({...})` config
-stands up a full member site — join/apply, Stripe membership, Google booking, a
-member area, an admin console, and a CRM — or an **admin-only hub**, on odla-db +
-Clerk + [@odla-ai/crm](https://odla.ai/docs/packages/crm) + calendar + email.
+A foundation for **membership sites**. One `defineChapter({...})` config stands up
+a full public member site — join/apply → Stripe membership → Google booking →
+member area — plus an admin console and a CRM, or an **admin-only hub**, on
+odla-db + Clerk + [@odla-ai/crm](https://odla.ai/docs/packages/crm) + calendar +
+email.
 
 ```sh
 npm i @odla-ai/chapter
@@ -12,34 +13,53 @@ npm i @odla-ai/chapter
 > **Agentic experiment.** Built and maintained by AI agents from bounded runbooks
 > with human review. Review the documented guarantees before relying on it.
 
-> **Early access (pre-1.0).** Hub mode — the admin console, CRM, and provisioning
-> — is complete. The public member surface (join/apply, Stripe membership, Google
-> booking, member area) is being ported release by release.
+> **Pre-1.0.** The member surface and the operational worker (auth, join, Stripe,
+> booking, email, CRM projection, admin operational routes) ship. The admin *UI*
+> is a growing section catalog: `peopleSection` and the availability editor today,
+> more sections landing per release.
 
 ## The shape
 
 - **One config, two profiles.** `defineChapter()` validates at import and returns
   a resolved engine. `mode: "chapter"` is the full public member site; `mode:
-  "hub"` is admin-only and CRM-focused (a directory/registry over the same CRM).
-  Same worker shell, auth, CRM, chrome, and provisioning — the mode gates the
-  member/join/payment route surface.
+  "hub"` is admin-only and CRM-focused. The mode gates the member/join/payment
+  route surface; everything else (auth, CRM, chrome, provisioning) is shared.
 - **The worker is the package.** `chapterWorker({ chapter })` is the whole
-  Cloudflare `ExportedHandler` — today: Clerk-JWT verify, the odla-db
-  admins-allowlist gate, the mounted `@odla-ai/crm` routes, and the static-asset
-  fallback (the member/join/Stripe/booking routes are being added). A site's
-  `src/worker.ts` is ~3 lines. Observability is a host concern — wrap it with
-  `withObservability` from `@odla-ai/o11y` in your entry if you run it. Everything
-  brand-specific (prices, policy copy, email templates, scheduling) is read at
-  runtime from a single odla-db `groups` row, never hardcoded.
-- **Provisioning is declarative.** `createChapterIntegration(chapter, opts)` is a
-  CLI-consumable descriptor that composes the crm namespaces + the chapter
-  namespaces (`applications`, `groups`, `meetings`, `emailLog`, `admins`) + a
-  guarded group-row seed. Drop it in `odla.config.mjs` `integrations: [...]`.
-- **The admin UI.** `./ui` ships `<ChapterAdmin>` — the console shell (config
-  fetch, themed Clerk sign-in, the allowlist gate, and a TopBar that renders the
-  sections you pass), authored against React and rendered as Preact via
-  `preact/compat` in the reference sites. The member islands (join, members,
-  slot-picker) and brand-token theming are on the roadmap.
+  Cloudflare `ExportedHandler`. It serves `/api/health`, `/api/config`,
+  `/api/me`, `/api/crm/*`, `/api/network/shared`; chapter mode adds the public
+  member surface (`/api/join-config`, `/api/applications`,
+  `/api/schedule/{slots,book}`, `/api/payments/subscription`,
+  `/api/webhooks/stripe`) and the admin operational routes (`/api/admin/*`), then
+  falls back to static assets. Your `src/worker.ts` is ~3 lines. Observability is
+  a host concern — wrap it with `withObservability` from `@odla-ai/o11y`.
+  Everything brand-specific (prices, policy copy, email templates, scheduling
+  rules) is read at runtime from a single odla-db `groups` row, never hardcoded.
+- **A route seam, not a black box.** `chapterWorker({ chapter, routes })` runs
+  your handlers *before* the built-ins (add routes, or override/alias a path),
+  each receiving the same context the built-ins get. The worker entry also exports
+  `createWorkerContext` + the `WorkerContext`/`Route` types, so a wrapping worker
+  reuses chapter's JWT verify, db client, and role resolution
+  (`verifyUser`/`makeDb`/`roleFor`/`isAdmin`) instead of duplicating them.
+- **Source-aware auth.** A JWT role-claim ladder (`provisional → member → admin`)
+  *or* an odla-db `admins` allowlist, plus a read-only `superAdmins` tier —
+  selected by `auth.source`, defaulting per mode. Escalation guards
+  (`canChangeRole`) are package-enforced.
+- **Correctness is packaged, not per-site.** Exactly-once email
+  (`sendTemplated`/`isAlreadySent`), a non-prod delivery fail-safe
+  (`planDelivery`), status-never-backwards (`canTransition`), Stripe webhook
+  integrity (`verifyStripeSignature`) with the webhook as the authoritative writer
+  of paid/refunded, one-subscription-per-application idempotency, meetings-as-
+  canonical booking (a rebooking *reschedules* the event, preserving the Meet
+  link), Google-edit adoption (`reconcileMeetings`), and a one-way CRM projection.
+- **Provisioning is declarative.** `createChapterIntegration(chapter)` composes
+  the crm namespaces + the chapter namespaces (`applications`, `groups`,
+  `meetings`, `emailLog`, plus the auth tables) + a guarded group-row seed. Drop
+  it in `odla.config.mjs` `integrations: [...]`.
+- **The UI kit (`./ui`).** Member islands — `JoinIsland` (form → payment →
+  booking), `MembersArea`, `Rescheduler`, `SlotPicker`, `PaymentStep`; the admin
+  console `ChapterAdmin` + the section catalog (`peopleSection`); and brand tokens
+  (`brandTokens`/`<BrandStyle>`) that re-skin the whole UI from `brand`. Authored
+  against React, rendered as Preact via `preact/compat` in the reference sites.
 
 ## Quick start
 
@@ -50,9 +70,8 @@ import { defineChapter } from "@odla-ai/chapter";
 export const chapter = defineChapter({
   id: "example-chapter",
   name: "Example Chapter",
-  url: "example.com",
   mode: "chapter",
-  brand: { palette: { /* --ui-* overrides */ }, wordmark: "Example Chapter" },
+  brand: { palette: { "--ui-accent": "#2f6f4f" }, fonts: { display: "GT Sectra" } },
   prices: { standardCents: 100000, foundingDiscountCents: 10000 },
   emails: { notificationEmail: "hello@example.com" },
 });
@@ -76,4 +95,68 @@ export default {
 };
 ```
 
+## Adopting into an existing site
+
+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

@@ -20,7 +20,6 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  BOOKABLE_STATUSES: () => BOOKABLE_STATUSES,
   SCHEDULING_DEFAULTS: () => SCHEDULING_DEFAULTS,
   applicationBookingUpdate: () => applicationBookingUpdate,
   applicationSummary: () => applicationSummary,
@@ -29,14 +28,18 @@ __export(index_exports, {
   buildGroupSeed: () => buildGroupSeed,
   canApprove: () => canApprove,
   canBook: () => canBook,
-  canBookFrom: () => canBookFrom,
   canChangeRole: () => canChangeRole,
   canTransition: () => canTransition,
   canceledPatch: () => canceledPatch,
   chapterDb: () => chapterDb,
+  clerkInviteRequest: () => clerkInviteRequest,
+  clerkUserRequest: () => clerkUserRequest,
   createChapterIntegration: () => createChapterIntegration,
+  createClerkInvitation: () => createClerkInvitation,
+  createClerkUser: () => createClerkUser,
   defaultCrm: () => defaultCrm,
   defineChapter: () => defineChapter,
+  emailGroupFrom: () => emailGroupFrom,
   endForSlot: () => endForSlot,
   findApplicationRef: () => findApplicationRef,
   firstPaymentPatch: () => firstPaymentPatch,
@@ -44,6 +47,7 @@ __export(index_exports, {
   introIdempotencyKey: () => introIdempotencyKey,
   isAdminRole: () => isAdminRole,
   isAlreadySent: () => isAlreadySent,
+  isReconcilable: () => isReconcilable,
   isSlotAvailable: () => isSlotAvailable,
   joinConfig: () => joinConfig,
   meetingCreateRow: () => meetingCreateRow,
@@ -53,7 +57,9 @@ __export(index_exports, {
   normalizeWebhookEvent: () => normalizeWebhookEvent,
   paymentsReady: () => paymentsReady,
   planDelivery: () => planDelivery,
+  projectApplicant: () => projectApplicant,
   projectSharedRecord: () => projectSharedRecord,
+  reconcileMeetings: () => reconcileMeetings,
   refundedPatch: () => refundedPatch,
   render: () => render,
   renderSummary: () => renderSummary,
@@ -64,6 +70,7 @@ __export(index_exports, {
   resolvePipeline: () => resolvePipeline,
   resolveScheduling: () => resolveScheduling,
   roleFromClaim: () => roleFromClaim,
+  sendTemplated: () => sendTemplated,
   sharedPersonInput: () => sharedPersonInput,
   slotWindow: () => slotWindow,
   stageIndex: () => stageIndex,
@@ -303,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}}
@@ -322,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}`
@@ -547,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,
@@ -559,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;
@@ -585,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 },
@@ -633,6 +645,72 @@ function planDelivery(input) {
   return { deliver: true, transport, to, subject, text, redirected: redirect };
 }
 
+// src/notify.ts
+async function sendTemplated(deps, input) {
+  const { emailLog: emailLog2 } = await deps.db.query({ emailLog: { $: { where: { dedupeKey: input.dedupeKey } } } });
+  const prior = Array.isArray(emailLog2) ? emailLog2 : [];
+  if (isAlreadySent(prior)) return { sent: true, reason: "already-sent" };
+  const cloudflareReady = Boolean(deps.sender && deps.from);
+  const decision = planDelivery({
+    envName: deps.envName,
+    group: input.group,
+    template: input.template,
+    to: input.to,
+    vars: input.vars,
+    cloudflareReady,
+    force: input.force
+  });
+  if (!decision.deliver) return { sent: false, reason: decision.reason };
+  let error;
+  let messageId;
+  if (decision.transport === "cloudflare" && deps.sender && deps.from) {
+    try {
+      const res = await deps.sender.send({
+        from: deps.from,
+        to: [decision.to],
+        subject: decision.subject,
+        text: decision.text,
+        replyTo: input.group.replyTo
+      });
+      messageId = res.messageId;
+    } catch (e) {
+      error = e instanceof Error ? e.message : String(e);
+    }
+  }
+  const id2 = deps.newId();
+  const row = {
+    id: id2,
+    groupId: input.group.id,
+    to: decision.to,
+    template: input.template,
+    subject: decision.subject,
+    body: decision.text,
+    transport: decision.transport,
+    redirected: decision.redirected,
+    dedupeKey: input.dedupeKey,
+    sentAt: deps.now(),
+    ...input.applicationId ? { applicationId: input.applicationId } : {},
+    ...messageId ? { messageId } : {},
+    ...error ? { error } : {}
+  };
+  await deps.db.transact([{ t: "update", ns: "emailLog", id: id2, attrs: row }], error ? void 0 : { mutationId: `email:${input.dedupeKey}` });
+  return error ? { sent: false, reason: error } : { sent: true };
+}
+function emailGroupFrom(row) {
+  const str = (v) => typeof v === "string" ? v : void 0;
+  const templates = row.emailTemplates && typeof row.emailTemplates === "object" ? row.emailTemplates : {};
+  return {
+    id: String(row.id),
+    name: String(row.name ?? ""),
+    replyTo: str(row.replyTo) ?? "",
+    debugEmail: str(row.debugEmail),
+    refundPolicyText: str(row.refundPolicyText),
+    commitmentText: str(row.commitmentText),
+    normsText: str(row.normsText),
+    emailTemplates: templates
+  };
+}
+
 // src/payments.ts
 function parseSigHeader(header) {
   const parts = {};
@@ -742,21 +820,73 @@ function sharedPersonInput(person) {
   if (person.linkedin) input.linkedin = person.linkedin;
   return input;
 }
-async function projectSharedRecord(deps, person) {
-  const email = person.email.toLowerCase();
-  const input = sharedPersonInput(person);
+async function upsertPerson(deps, opts) {
+  const email = opts.email.toLowerCase();
   const crmDeps = { crm: deps.crm, db: deps.db, now: deps.now, newId: deps.newId };
-  const { crm_record } = await deps.db.query({
-    crm_record: { $: { where: { type: "person", primaryEmail: email }, limit: 1 } }
-  });
+  const { crm_record } = await deps.db.query({ crm_record: { $: { where: { type: "person", primaryEmail: email }, limit: 1 } } });
   const existing = crm_record?.[0];
   if (existing && typeof existing.id === "string") {
-    await (0, import_crm3.updateRecord)(crmDeps, { id: existing.id, input });
+    await (0, import_crm3.updateRecord)(crmDeps, { id: existing.id, input: opts.input });
     return { recordId: existing.id };
   }
-  const created = await (0, import_crm3.createRecord)(crmDeps, { type: "person", input, mutationId: `share:${person.hubRecordId}` });
+  const created = await (0, import_crm3.createRecord)(crmDeps, { type: "person", input: opts.input, mutationId: opts.mutationId });
   return { recordId: created.id };
 }
+async function projectSharedRecord(deps, person) {
+  return upsertPerson(deps, { email: person.email, input: sharedPersonInput(person), mutationId: `share:${person.hubRecordId}` });
+}
+async function projectApplicant(deps, applicant) {
+  const input = sharedPersonInput({
+    email: applicant.email,
+    firstName: applicant.firstName,
+    lastName: applicant.lastName,
+    phone: applicant.phone,
+    linkedin: applicant.linkedin,
+    hubRecordId: applicant.applicationId
+  });
+  return upsertPerson(deps, { email: applicant.email, input, mutationId: `apply:${applicant.applicationId}` });
+}
+
+// src/clerk.ts
+function clerkInviteRequest(input) {
+  return {
+    path: "/v1/invitations",
+    body: {
+      email_address: input.email,
+      notify: true,
+      ...input.redirectUrl ? { redirect_url: input.redirectUrl } : {}
+    }
+  };
+}
+async function createClerkInvitation(secretKey, input, fetchImpl = fetch) {
+  const { path, body } = clerkInviteRequest(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 };
+}
+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) {
@@ -822,6 +952,38 @@ function brandTokens(brand) {
 ` : "";
 }
 
+// src/reconcile.ts
+function isReconcilable(meeting, now) {
+  return meeting.status === "scheduled" && Boolean(meeting.googleEventId) && (meeting.startAt ?? 0) > now - 36e5;
+}
+function reconcileMeetings(meetings2, events, now) {
+  const byEvent = new Map(events.map((e) => [e.eventId, e]));
+  const decisions = [];
+  for (const m of meetings2) {
+    if (!isReconcilable(m, now) || !m.googleEventId) continue;
+    const g = byEvent.get(m.googleEventId);
+    if (!g || g.status === "cancelled") {
+      decisions.push({
+        meetingId: m.id,
+        applicationId: m.applicationId,
+        kind: "cancelled",
+        meetingPatch: { status: "cancelled", drift: "none", adoptedFromGoogleAt: now },
+        applicationPatch: { meetingAt: 0, meetingLink: "" }
+      });
+    } else if (g.startAt !== void 0 && g.startAt !== m.startAt) {
+      const duration = (m.endAt ?? 0) - (m.startAt ?? 0);
+      decisions.push({
+        meetingId: m.id,
+        applicationId: m.applicationId,
+        kind: "moved",
+        meetingPatch: { startAt: g.startAt, endAt: g.endAt ?? g.startAt + duration, drift: "none", adoptedFromGoogleAt: now },
+        applicationPatch: { meetingAt: g.startAt }
+      });
+    }
+  }
+  return decisions;
+}
+
 // src/scheduling.ts
 var SCHEDULING_DEFAULTS = {
   slotMinutes: 45,
@@ -868,10 +1030,6 @@ function resolveScheduling(config) {
   if (typeof c.summaryTemplate !== "string") fail("summaryTemplate must be a string");
   return { ...c, days };
 }
-var BOOKABLE_STATUSES = ["submitted", "paid_pending_vetting", "call_scheduled"];
-function canBookFrom(status) {
-  return BOOKABLE_STATUSES.includes(status);
-}
 function slotWindow(now, windowDays) {
   return { from: now, to: now + windowDays * 864e5 };
 }