@odla-ai/chapter 0.5.0 → 0.7.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,20 @@ 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.
+
 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,16 @@ __export(index_exports, {
   buildGroupSeed: () => buildGroupSeed,
   canApprove: () => canApprove,
   canBook: () => canBook,
-  canBookFrom: () => canBookFrom,
   canChangeRole: () => canChangeRole,
   canTransition: () => canTransition,
   canceledPatch: () => canceledPatch,
   chapterDb: () => chapterDb,
+  clerkInviteRequest: () => clerkInviteRequest,
   createChapterIntegration: () => createChapterIntegration,
+  createClerkInvitation: () => createClerkInvitation,
   defaultCrm: () => defaultCrm,
   defineChapter: () => defineChapter,
+  emailGroupFrom: () => emailGroupFrom,
   endForSlot: () => endForSlot,
   findApplicationRef: () => findApplicationRef,
   firstPaymentPatch: () => firstPaymentPatch,
@@ -44,6 +45,7 @@ __export(index_exports, {
   introIdempotencyKey: () => introIdempotencyKey,
   isAdminRole: () => isAdminRole,
   isAlreadySent: () => isAlreadySent,
+  isReconcilable: () => isReconcilable,
   isSlotAvailable: () => isSlotAvailable,
   joinConfig: () => joinConfig,
   meetingCreateRow: () => meetingCreateRow,
@@ -53,7 +55,9 @@ __export(index_exports, {
   normalizeWebhookEvent: () => normalizeWebhookEvent,
   paymentsReady: () => paymentsReady,
   planDelivery: () => planDelivery,
+  projectApplicant: () => projectApplicant,
   projectSharedRecord: () => projectSharedRecord,
+  reconcileMeetings: () => reconcileMeetings,
   refundedPatch: () => refundedPatch,
   render: () => render,
   renderSummary: () => renderSummary,
@@ -64,6 +68,7 @@ __export(index_exports, {
   resolvePipeline: () => resolvePipeline,
   resolveScheduling: () => resolveScheduling,
   roleFromClaim: () => roleFromClaim,
+  sendTemplated: () => sendTemplated,
   sharedPersonInput: () => sharedPersonInput,
   slotWindow: () => slotWindow,
   stageIndex: () => stageIndex,
@@ -633,6 +638,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 +813,53 @@ 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 };
+}
 
 // src/session.ts
 function applicationSummary(app) {
@@ -822,6 +925,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 +1003,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 };
 }