@odla-ai/chapter 0.9.0 → 0.10.1

package/README.md

@@ -135,15 +135,39 @@ These bite silently — a smoke test won't catch them:
 - **`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.
+- **Which email fires from which route.** Content and addressing are owner-editable
+  on the `groups` row; the *trigger* is config:
+
+  | Template | Fires from | Configurable |
+  |---|---|---|
+  | `adminNotification` | `POST /api/applications` (submit) — or the Stripe webhook (first payment) | `sends.adminNotification: "submit" \| "payment" \| "never"` (default `"submit"`) |
+  | `prepEmail` | `POST /api/schedule/book` | template `enabled` flag |
+  | `paymentConfirmation` | Stripe webhook, first successful invoice | template `enabled` flag |
+
+  ```ts
+  defineChapter({ /* … */ sends: { adminNotification: "payment" } });
+  ```
+
+  **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.
+- **What lands on the Clerk account.** Both models write `public_metadata` as
+  `{ applicationId, profile }`, where `profile` is every configured
+  `application.required`/`optional` field Clerk doesn't already carry natively
+  (so *not* email/firstName/lastName), plus `focus`. It follows your field names —
+  `applicantProfile(chapter, fields)` is exported if you want to assert the exact
+  shape in a test before deleting a local override.
+- **Disclaimer acknowledgement.** A truthy `disclaimerAck` on the submit body
+  (boolean or the string a plain form posts) stamps `disclaimerAckAt` from the
+  *server* clock; no ack leaves the attr absent, and a client-supplied
+  `disclaimerAckAt` is ignored. If your join page collects consent, post the flag —
+  an unstamped row is the honest record that nobody acked, so a missing flag
+  fails silently in exactly the way a compliance record must not.
 - **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.
@@ -153,20 +177,30 @@ These bite silently — a smoke test won't catch them:
 
 ### Install + scope notes
 
-- **`@odla-ai/auth-clerk` is only needed for the admin console.** The worker never
-  imports it (JWTs are verified with `jose` via `ctx.verifyUser`), and neither
-  does `@odla-ai/chapter/ui/member`. Install it when you adopt
-  `@odla-ai/chapter/ui/admin` (or want the themed sign-in components); reach for
+- **`@odla-ai/auth-clerk` is not a chapter peer.** It is deliberately absent from
+  this package's manifest, because only one entry imports it: the worker verifies
+  JWTs with `jose` via `ctx.verifyUser`, and `@odla-ai/chapter/ui/member` is
+  react-only. **Install `@odla-ai/auth-clerk` yourself if (and only if) you adopt
+  `@odla-ai/chapter/ui/admin`** or want the themed sign-in components; reach for
   `@odla-ai/auth-clerk/invitations` when you want to send your own branded
-  invitation mail. Importing the full `@odla-ai/chapter/ui` barrel pulls it, so
-  prefer the narrower entry.
+  invitation mail. Importing the full `@odla-ai/chapter/ui` barrel pulls the admin
+  half, so prefer the narrower entry.
+- **Known-good version set** (installs clean, no flags): `@odla-ai/chapter` 0.10.0,
+  `@odla-ai/ui` 0.9.0, `@odla-ai/crm` 0.1.4, `@odla-ai/db` 0.6.6,
+  `@odla-ai/calendar` 0.2.0, `@odla-ai/email` 0.3.1, CLI 0.16.7, plus `jose` and
+  react (or `preact` + `preact/compat`). chapter is the package that pulls the
+  others together, so this is the line to check when an install complains.
 - **`--legacy-peer-deps` is a diagnostic, not a setting.** It suppresses exactly
   the peer conflict that tells you a pair is unsupported. If you need it, find out
   why first.
-- **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.
+- **The admin surface is intentionally minimal, and staying that way.** chapter
+  ships `/api/admin/scheduling` (booking rules, with field-keyed validation
+  messages) and `/api/admin/meetings` (the reconciled agenda, with the applicant
+  joined, `?all=1`, `from`/`to`, drift fields, Meet/Calendar links and the group
+  timezone), plus `peopleSection`. **Dashboard, billing, email config/log/test,
+  per-person comms, people list, role changes, approve and refund are out of
+  scope** — they are yours as host routes via the seam. Don't plan around them
+  shipping.
 
 ### Verify from the types, not this file
 

package/dist/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   SCHEDULING_DEFAULTS: () => SCHEDULING_DEFAULTS,
+  applicantProfile: () => applicantProfile,
   applicationBookingUpdate: () => applicationBookingUpdate,
   applicationSummary: () => applicationSummary,
   bookingDecision: () => bookingDecision,
@@ -77,6 +78,7 @@ __export(index_exports, {
   stripeForm: () => stripeForm,
   submitApplication: () => submitApplication,
   subscriptionIdempotencyKey: () => subscriptionIdempotencyKey,
+  validateScheduling: () => validateScheduling,
   verifyStripeSignature: () => verifyStripeSignature,
   webhookMutationId: () => webhookMutationId
 });
@@ -487,6 +489,17 @@ function resolveApplication(a) {
     bodyCap: a?.bodyCap ?? 32768
   };
 }
+var IDENTITY_FIELDS = /* @__PURE__ */ new Set(["email", "firstName", "lastName"]);
+function applicantProfile(chapter, fields) {
+  const profile = {};
+  for (const f of [...chapter.application.required, ...chapter.application.optional]) {
+    if (IDENTITY_FIELDS.has(f)) continue;
+    const v = fields[f];
+    if (typeof v === "string" && v.trim() !== "") profile[f] = v.trim();
+  }
+  if (fields.focus !== void 0) profile.focus = fields.focus;
+  return Object.keys(profile).length > 0 ? profile : void 0;
+}
 async function submitApplication(db, chapter, fields, opts) {
   const app = chapter.application;
   for (const f of app.required) {
@@ -505,6 +518,7 @@ async function submitApplication(db, chapter, fields, opts) {
   }
   if (fields.focus !== void 0) row.focus = fields.focus;
   if (opts.groupId) row.groupId = opts.groupId;
+  if (fields.disclaimerAck === true || fields.disclaimerAck === "true") row.disclaimerAckAt = opts.now;
   const { duplicate } = await db.transact(
     [{ t: "update", ns: "applications", id: id2, attrs: row }],
     opts.submissionId ? { mutationId: `join:${opts.submissionId}` } : void 0
@@ -558,6 +572,13 @@ function defineChapter(config) {
   if (account !== "invite" && account !== "create" && account !== "none") {
     throw new Error(`defineChapter.account: must be "invite", "create", or "none" \u2014 got "${String(account)}"`);
   }
+  const adminNotification = config.sends?.adminNotification ?? "submit";
+  if (adminNotification !== "submit" && adminNotification !== "payment" && adminNotification !== "never") {
+    throw new Error(
+      `defineChapter.sends.adminNotification: must be "submit", "payment", or "never" \u2014 got "${String(adminNotification)}"`
+    );
+  }
+  const sends = { adminNotification };
   const chapter = {
     config,
     id: id2,
@@ -571,6 +592,7 @@ function defineChapter(config) {
     rules,
     services,
     account,
+    sends,
     groupSeed: () => mode === "chapter" ? buildGroupSeed(config) : null
   };
   if (config.url !== void 0) chapter.url = config.url;
@@ -881,6 +903,20 @@ function clerkUserRequest(input) {
     }
   };
 }
+async function refreshUserMetadata(secretKey, email, publicMetadata, fetchImpl) {
+  const auth = { authorization: `Bearer ${secretKey}` };
+  const found = await fetchImpl(`https://api.clerk.com/v1/users?email_address=${encodeURIComponent(email)}&limit=1`, { headers: auth });
+  if (!found.ok) return false;
+  const users = await found.json().catch(() => null);
+  const id2 = Array.isArray(users) && typeof users[0]?.id === "string" ? users[0].id : void 0;
+  if (!id2) return false;
+  const patched = await fetchImpl(`https://api.clerk.com/v1/users/${id2}/metadata`, {
+    method: "PATCH",
+    headers: { ...auth, "content-type": "application/json" },
+    body: JSON.stringify({ public_metadata: publicMetadata })
+  });
+  return patched.ok;
+}
 async function createClerkUser(secretKey, input, fetchImpl = fetch) {
   const { path, body } = clerkUserRequest(input);
   const res = await fetchImpl(`https://api.clerk.com${path}`, {
@@ -888,7 +924,11 @@ async function createClerkUser(secretKey, input, fetchImpl = fetch) {
     headers: { authorization: `Bearer ${secretKey}`, "content-type": "application/json" },
     body: JSON.stringify(body)
   });
-  return res.ok ? { ok: true, status: res.status } : heal(res.status);
+  if (res.ok) return { ok: true, status: res.status };
+  const healed = heal(res.status);
+  if (!healed.existed || !input.publicMetadata) return healed;
+  const refreshed = await refreshUserMetadata(secretKey, input.email, input.publicMetadata, fetchImpl).catch(() => false);
+  return { ...healed, refreshed };
 }
 
 // src/session.ts
@@ -1007,6 +1047,12 @@ function isValidTimeZone(tz) {
   }
 }
 function resolveScheduling(config) {
+  const result = validateScheduling(config);
+  if (result.ok) return result.value;
+  const detail = Object.entries(result.errors).map(([field, message]) => `${field}: ${message}`).join(" ");
+  throw new Error(`scheduling: ${detail}`);
+}
+function validateScheduling(config) {
   const d = config ?? {};
   const c = {
     slotMinutes: d.slotMinutes ?? SCHEDULING_DEFAULTS.slotMinutes,
@@ -1018,20 +1064,29 @@ function resolveScheduling(config) {
     windowDays: d.windowDays ?? SCHEDULING_DEFAULTS.windowDays,
     summaryTemplate: d.summaryTemplate ?? SCHEDULING_DEFAULTS.summaryTemplate
   };
-  const fail = (msg) => {
-    throw new Error(`scheduling: ${msg}`);
-  };
-  if (!(c.slotMinutes >= 15 && c.slotMinutes <= 240)) fail("slotMinutes must be 15\u2013240");
-  if (!(c.windowDays >= 1 && c.windowDays <= 62)) fail("windowDays must be 1\u201362 (FreeBusy caps at 62)");
-  if (!(c.minNoticeHours >= 0 && c.minNoticeHours <= 336)) fail("minNoticeHours must be 0\u2013336");
-  if (!(c.startHour >= 0 && c.startHour < c.endHour && c.endHour <= 24)) fail("require 0 \u2264 startHour < endHour \u2264 24");
+  const errors = {};
+  if (!(c.slotMinutes >= 15 && c.slotMinutes <= 240)) {
+    errors.slotMinutes = "Slot length must be between 15 and 240 minutes.";
+  }
+  if (!(c.windowDays >= 1 && c.windowDays <= 62)) {
+    errors.windowDays = "Booking window must be between 1 and 62 days (the calendar caps look-ahead at 62).";
+  }
+  if (!(c.minNoticeHours >= 0 && c.minNoticeHours <= 336)) {
+    errors.minNoticeHours = "Minimum notice must be between 0 and 336 hours.";
+  }
+  if (!(c.startHour >= 0 && c.startHour < c.endHour && c.endHour <= 24)) {
+    errors.hours = "Hours must satisfy 0 \u2264 start < end \u2264 24.";
+  }
   const days = [...c.days];
-  if (!days.length || !days.every((n) => Number.isInteger(n) && n >= 0 && n <= 6)) {
-    fail("days must be a non-empty list of weekday integers 0\u20136");
+  if (!days.length) errors.days = "Pick at least one day.";
+  else if (!days.every((n) => Number.isInteger(n) && n >= 0 && n <= 6)) {
+    errors.days = "Days must be weekday numbers, 0 (Sunday) through 6 (Saturday).";
+  }
+  if (typeof c.timezone !== "string" || !isValidTimeZone(c.timezone)) {
+    errors.timezone = `"${String(c.timezone)}" is not a valid IANA timezone (for example "America/Los_Angeles").`;
   }
-  if (typeof c.timezone !== "string" || !isValidTimeZone(c.timezone)) fail(`invalid IANA timezone "${c.timezone}"`);
-  if (typeof c.summaryTemplate !== "string") fail("summaryTemplate must be a string");
-  return { ...c, days };
+  if (typeof c.summaryTemplate !== "string") errors.summaryTemplate = "Calendar summary template must be text.";
+  return Object.keys(errors).length > 0 ? { ok: false, errors } : { ok: true, value: { ...c, days } };
 }
 function slotWindow(now, windowDays) {
   return { from: now, to: now + windowDays * 864e5 };