@odla-ai/chapter 0.9.0 → 0.10.0

package/dist/worker/index.d.cts

@@ -194,9 +194,24 @@ interface ChapterConfig {
      *  account is ready), `"none"` skips it. Any of these needs a `clerk_secret_key`
      *  vault secret to act. */
     account?: AccountModel;
+    /** WHEN lifecycle email fires. Addressing and content live on the group row
+     *  (owner-editable at runtime); this is the trigger, which is a build-time
+     *  decision. See {@link ChapterSends}. */
+    sends?: ChapterSends;
 }
 /** Apply-time Clerk account provisioning model. */
 type AccountModel = "invite" | "create" | "none";
+/** When the admin notification fires: on application `submit` (default), on the
+ *  first successful `payment`, or `never` (the site drives it itself). */
+type AdminNotificationTrigger = "submit" | "payment" | "never";
+/** Send-policy config: the trigger for each lifecycle email chapter owns. */
+interface ChapterSends {
+    adminNotification?: AdminNotificationTrigger;
+}
+/** Resolved send policy (every trigger present). */
+interface ResolvedSends {
+    adminNotification: AdminNotificationTrigger;
+}
 /** The resolved engine `defineChapter()` returns. */
 interface Chapter {
     config: ChapterConfig;
@@ -218,6 +233,8 @@ interface Chapter {
     services: readonly string[];
     /** Resolved apply-time account provisioning model (default `"invite"`). */
     account: AccountModel;
+    /** Resolved send policy — when each lifecycle email fires. */
+    sends: ResolvedSends;
     /** The seed `groups` row derived from config (chapter mode), else `null`. */
     groupSeed(): Record<string, unknown> | null;
 }

package/dist/worker/index.d.ts

@@ -194,9 +194,24 @@ interface ChapterConfig {
      *  account is ready), `"none"` skips it. Any of these needs a `clerk_secret_key`
      *  vault secret to act. */
     account?: AccountModel;
+    /** WHEN lifecycle email fires. Addressing and content live on the group row
+     *  (owner-editable at runtime); this is the trigger, which is a build-time
+     *  decision. See {@link ChapterSends}. */
+    sends?: ChapterSends;
 }
 /** Apply-time Clerk account provisioning model. */
 type AccountModel = "invite" | "create" | "none";
+/** When the admin notification fires: on application `submit` (default), on the
+ *  first successful `payment`, or `never` (the site drives it itself). */
+type AdminNotificationTrigger = "submit" | "payment" | "never";
+/** Send-policy config: the trigger for each lifecycle email chapter owns. */
+interface ChapterSends {
+    adminNotification?: AdminNotificationTrigger;
+}
+/** Resolved send policy (every trigger present). */
+interface ResolvedSends {
+    adminNotification: AdminNotificationTrigger;
+}
 /** The resolved engine `defineChapter()` returns. */
 interface Chapter {
     config: ChapterConfig;
@@ -218,6 +233,8 @@ interface Chapter {
     services: readonly string[];
     /** Resolved apply-time account provisioning model (default `"invite"`). */
     account: AccountModel;
+    /** Resolved send policy — when each lifecycle email fires. */
+    sends: ResolvedSends;
     /** The seed `groups` row derived from config (chapter mode), else `null`. */
     groupSeed(): Record<string, unknown> | null;
 }

package/dist/worker/index.js

@@ -128,6 +128,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 id = Array.isArray(users) && typeof users[0]?.id === "string" ? users[0].id : void 0;
+  if (!id) return false;
+  const patched = await fetchImpl(`https://api.clerk.com/v1/users/${id}/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}`, {
@@ -135,7 +149,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/member.ts
@@ -238,6 +256,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,
@@ -249,20 +273,29 @@ function resolveScheduling(config) {
     windowDays: d.windowDays ?? SCHEDULING_DEFAULTS.windowDays,
     summaryTemplate: d.summaryTemplate ?? SCHEDULING_DEFAULTS.summaryTemplate
   };
-  const fail2 = (msg) => {
-    throw new Error(`scheduling: ${msg}`);
-  };
-  if (!(c.slotMinutes >= 15 && c.slotMinutes <= 240)) fail2("slotMinutes must be 15\u2013240");
-  if (!(c.windowDays >= 1 && c.windowDays <= 62)) fail2("windowDays must be 1\u201362 (FreeBusy caps at 62)");
-  if (!(c.minNoticeHours >= 0 && c.minNoticeHours <= 336)) fail2("minNoticeHours must be 0\u2013336");
-  if (!(c.startHour >= 0 && c.startHour < c.endHour && c.endHour <= 24)) fail2("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)) {
-    fail2("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)) fail2(`invalid IANA timezone "${c.timezone}"`);
-  if (typeof c.summaryTemplate !== "string") fail2("summaryTemplate must be a string");
-  return { ...c, days };
+  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.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 };
@@ -592,7 +625,9 @@ var handleMember = async (req, url, env, ctx) => {
     });
     if (!result.ok) return json({ error: result.error }, 400);
     if (!result.duplicate) {
-      await notifyAdminOfApplication(db, env, chapter.id, result.id, parsed);
+      if (chapter.sends.adminNotification === "submit") {
+        await notifyAdminOfApplication(db, env, chapter.id, result.id, parsed);
+      }
       await provisionApplicant(db, chapter, result.id, parsed);
     }
     return json({ id: result.id, duplicate: result.duplicate, status: result.status });
@@ -972,6 +1007,25 @@ async function notifyPaymentConfirmed(db, env, eventId, app) {
   } catch {
   }
 }
+async function notifyAdminOfPayment(db, env, eventId, app) {
+  try {
+    const group = await firstRow2(db, "groups", { where: { id: String(app.groupId ?? "") }, limit: 1 });
+    if (!group || typeof group.notificationEmail !== "string" || !group.notificationEmail) return;
+    const s = (v) => typeof v === "string" ? v : "";
+    await sendTemplated(
+      { db, envName: env.ODLA_ENV, sender: env.SEND_EMAIL, from: env.EMAIL_FROM, now: () => Date.now(), newId: () => crypto.randomUUID() },
+      {
+        group: emailGroupFrom(group),
+        template: "adminNotification",
+        to: group.notificationEmail,
+        vars: { firstName: s(app.firstName), lastName: s(app.lastName), email: s(app.email), phone: s(app.phone), state: s(app.state) },
+        dedupeKey: `${eventId}:admin`,
+        applicationId: String(app.id)
+      }
+    );
+  } catch {
+  }
+}
 function webhookPatch(event, status) {
   switch (event.kind) {
     case "first_payment":
@@ -1043,7 +1097,10 @@ async function ingestWebhook(req, env, ctx) {
   if (Object.keys(patch).length) {
     await db.transact([{ t: "update", ns: "applications", id: String(app.id), attrs: patch }], { mutationId: webhookMutationId(eventId) });
   }
-  if (event.kind === "first_payment") await notifyPaymentConfirmed(db, env, eventId, app);
+  if (event.kind === "first_payment") {
+    await notifyPaymentConfirmed(db, env, eventId, app);
+    if (ctx.chapter.sends.adminNotification === "payment") await notifyAdminOfPayment(db, env, eventId, app);
+  }
   return json({ ok: true });
 }
 async function refundApplication(req, url, env, ctx) {
@@ -1140,14 +1197,10 @@ var handleAdminScheduling = async (req, url, env, ctx) => {
   } catch {
     return json({ error: "invalid JSON body" }, 400);
   }
-  let resolved;
-  try {
-    resolved = resolveScheduling(body);
-  } catch (e) {
-    return json({ error: e instanceof Error ? e.message : "invalid scheduling config" }, 400);
-  }
-  await db.transact([{ t: "update", ns: "groups", id: String(group.id), attrs: { schedulingJson: resolved } }]);
-  return json({ scheduling: resolved });
+  const checked = validateScheduling(body);
+  if (!checked.ok) return json({ error: "invalid scheduling config", errors: checked.errors }, 400);
+  await db.transact([{ t: "update", ns: "groups", id: String(group.id), attrs: { schedulingJson: checked.value } }]);
+  return json({ scheduling: checked.value });
 };
 async function upcomingEvents(env) {
   const cal = initCalendar2({ appId: env.ODLA_APP_ID, env: env.ODLA_ENV, adminToken: env.ODLA_API_KEY, endpoint: env.ODLA_PLATFORM });
@@ -1170,8 +1223,15 @@ var handleAdminMeetings = async (req, url, env, ctx) => {
   const u = await ctx.verifyUser(req, env);
   if (!u || !await ctx.isAdmin(rawDb, u)) return json({ error: "forbidden" }, 403);
   const db = rawDb;
-  const query = await db.query({ meetings: { $: { where: { status: "scheduled" }, order: { startAt: "asc" }, limit: 500 } } });
-  const rows = Array.isArray(query.meetings) ? query.meetings : [];
+  const all = url.searchParams.get("all") === "1";
+  const from = Number(url.searchParams.get("from"));
+  const to = Number(url.searchParams.get("to"));
+  const query = await db.query({
+    meetings: { $: { where: all ? {} : { status: "scheduled" }, order: { startAt: "asc" }, limit: 500 } }
+  });
+  let rows = Array.isArray(query.meetings) ? query.meetings : [];
+  if (Number.isFinite(from)) rows = rows.filter((m) => Number(m.startAt ?? 0) >= from);
+  if (Number.isFinite(to)) rows = rows.filter((m) => Number(m.startAt ?? 0) <= to);
   let decisions = [];
   try {
     decisions = reconcileMeetings(toReconcile(rows), await upcomingEvents(env), Date.now());
@@ -1189,8 +1249,20 @@ var handleAdminMeetings = async (req, url, env, ctx) => {
     } catch {
     }
   }
-  const meetings = rows.map((m) => ({ ...m, ...patched.get(String(m.id)) ?? {} })).filter((m) => m.status === "scheduled");
-  return json({ meetings, adopted: decisions.length });
+  const appQuery = await db.query({ applications: { $: { limit: 1e3 } } });
+  const byId = /* @__PURE__ */ new Map();
+  for (const a of Array.isArray(appQuery.applications) ? appQuery.applications : []) {
+    byId.set(String(a.id), a);
+  }
+  const applicantOf = (m) => {
+    const a = byId.get(String(m.applicationId));
+    if (!a) return null;
+    return { id: a.id, firstName: a.firstName, lastName: a.lastName, email: a.email, status: a.status };
+  };
+  const group = (await db.query({ groups: { $: { where: { id: ctx.chapter.id }, limit: 1 } } })).groups?.[0];
+  const timezone = resolveScheduling(group?.schedulingJson).timezone;
+  const meetings = rows.map((m) => ({ ...m, ...patched.get(String(m.id)) ?? {}, applicant: applicantOf(m) })).filter((m) => all || m.status === "scheduled");
+  return json({ meetings, adopted: decisions.length, timezone });
 };
 
 // src/worker.ts