@odla-ai/chapter 0.9.0 → 0.10.0

package/dist/index.d.cts

@@ -215,9 +215,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;
@@ -239,6 +254,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;
 }
@@ -708,6 +725,8 @@ interface ClerkResult {
     ok: boolean;
     status: number;
     existed?: boolean;
+    /** Set when an `existed` heal also refreshed the account's public_metadata. */
+    refreshed?: boolean;
 }
 /** Inputs for a Clerk invitation. */
 interface ClerkInviteInput {
@@ -746,7 +765,9 @@ declare function clerkUserRequest(input: ClerkUserInput): {
 };
 /** Create the applicant's Clerk account server-side. A repeat for an email that
  *  already has an account heals to `{ ok: true, existed: true }` — the account
- *  exists, which is the state apply-time provisioning wanted. */
+ *  exists, which is the state apply-time provisioning wanted — and, when
+ *  `publicMetadata` was supplied, refreshes it on the existing account so a
+ *  re-application repairs a previously missed create (`refreshed: true`). */
 declare function createClerkUser(secretKey: string, input: ClerkUserInput, fetchImpl?: typeof fetch): Promise<ClerkResult>;
 
 /** An application row, as far as the session cares about it. */
@@ -888,6 +909,22 @@ declare const SCHEDULING_DEFAULTS: ResolvedScheduling;
  * `windowDays` is capped at 62 because Google FreeBusy is.
  */
 declare function resolveScheduling(config?: ChapterScheduling): ResolvedScheduling;
+/** Validation messages keyed by form field. */
+type SchedulingErrors = Record<string, string>;
+/**
+ * Validate a scheduling config field by field, collecting owner-readable messages
+ * rather than throwing on the first problem. An admin settings form needs to say
+ * *which* field is wrong and why — "pick at least one day" beats a stack trace —
+ * so the admin route returns these directly. {@link resolveScheduling} is the
+ * throwing wrapper for internal/config-time use.
+ */
+declare function validateScheduling(config?: ChapterScheduling): {
+    ok: true;
+    value: ResolvedScheduling;
+} | {
+    ok: false;
+    errors: SchedulingErrors;
+};
 /** Statuses a member may book/reschedule from (early pipeline only). */
 /** The availability window: `[now, now + windowDays]` in epoch ms. */
 declare function slotWindow(now: number, windowDays: number): {
@@ -971,4 +1008,4 @@ type ApplicationBookingPatch = {
  *  already there (never backward). */
 declare function applicationBookingUpdate(currentStatus: string, startAt: number, htmlLink?: string | null): ApplicationBookingPatch;
 
-export { type AccountModel, type Applicant, type ApplicationBookingPatch, type ApplicationRecord, type ApplicationSummary, type Attr, type AttrType, type Chapter, type ChapterApplication, type ChapterAuth, type ChapterBrand, type ChapterConfig, type ChapterDb, type ChapterEmails, type ChapterIntegrationDescriptor, type ChapterIntegrationOptions, type ChapterMode, type ChapterPipeline, type ChapterPolicy, type ChapterPrices, type ChapterScheduling, type ClerkInviteInput, type ClerkResult, type ClerkUserInput, type DbOp, type DbRules, type DbSchema, type DeliveryDecision, type EmailGroup, type EmailTemplate, type EmailTemplateRow, type Entity, type ExistingMeeting, type GuardResult, type JoinConfigGroup, type LiveEvent, type MailSender, type MeetingForReconcile, type MeetingRecord, type MeetingReschedulePatch, type MemberApplication, type MemberSession, type NewMeetingRow, type NotifyDeps, type NotifyInput, type NotifyResult, type PaymentsGroup, type ProjectionDeps, type ReconcileDecision, type ResolvedApplication, type ResolvedAuth, type ResolvedPipeline, type ResolvedScheduling, type RoleChangeContext, type Rule, SCHEDULING_DEFAULTS, type SecretStore, type SessionUser, type SharedPerson, type StripeEvent, type SubmitResult, type WebhookEvent, applicationBookingUpdate, applicationSummary, bookingDecision, brandTokens, buildGroupSeed, canApprove, canBook, canChangeRole, canTransition, canceledPatch, chapterDb, clerkInviteRequest, clerkUserRequest, createChapterIntegration, createClerkInvitation, createClerkUser, defaultCrm, defineChapter, emailGroupFrom, endForSlot, findApplicationRef, firstPaymentPatch, getVaultSecret, introIdempotencyKey, isAdminRole, isAlreadySent, isReconcilable, isSlotAvailable, joinConfig, meetingCreateRow, meetingRescheduleUpdate, memberApplication, memberSession, normalizeWebhookEvent, paymentsReady, planDelivery, projectApplicant, projectSharedRecord, reconcileMeetings, refundedPatch, render, renderSummary, renderTemplateBody, renewalPatch, resolveApplication, resolveAuth, resolvePipeline, resolveScheduling, roleFromClaim, sendTemplated, sharedPersonInput, slotWindow, stageIndex, stripeForm, submitApplication, subscriptionIdempotencyKey, verifyStripeSignature, webhookMutationId };
+export { type AccountModel, type AdminNotificationTrigger, type Applicant, type ApplicationBookingPatch, type ApplicationRecord, type ApplicationSummary, type Attr, type AttrType, type Chapter, type ChapterApplication, type ChapterAuth, type ChapterBrand, type ChapterConfig, type ChapterDb, type ChapterEmails, type ChapterIntegrationDescriptor, type ChapterIntegrationOptions, type ChapterMode, type ChapterPipeline, type ChapterPolicy, type ChapterPrices, type ChapterScheduling, type ChapterSends, type ClerkInviteInput, type ClerkResult, type ClerkUserInput, type DbOp, type DbRules, type DbSchema, type DeliveryDecision, type EmailGroup, type EmailTemplate, type EmailTemplateRow, type Entity, type ExistingMeeting, type GuardResult, type JoinConfigGroup, type LiveEvent, type MailSender, type MeetingForReconcile, type MeetingRecord, type MeetingReschedulePatch, type MemberApplication, type MemberSession, type NewMeetingRow, type NotifyDeps, type NotifyInput, type NotifyResult, type PaymentsGroup, type ProjectionDeps, type ReconcileDecision, type ResolvedApplication, type ResolvedAuth, type ResolvedPipeline, type ResolvedScheduling, type ResolvedSends, type RoleChangeContext, type Rule, SCHEDULING_DEFAULTS, type SchedulingErrors, type SecretStore, type SessionUser, type SharedPerson, type StripeEvent, type SubmitResult, type WebhookEvent, applicationBookingUpdate, applicationSummary, bookingDecision, brandTokens, buildGroupSeed, canApprove, canBook, canChangeRole, canTransition, canceledPatch, chapterDb, clerkInviteRequest, clerkUserRequest, createChapterIntegration, createClerkInvitation, createClerkUser, defaultCrm, defineChapter, emailGroupFrom, endForSlot, findApplicationRef, firstPaymentPatch, getVaultSecret, introIdempotencyKey, isAdminRole, isAlreadySent, isReconcilable, isSlotAvailable, joinConfig, meetingCreateRow, meetingRescheduleUpdate, memberApplication, memberSession, normalizeWebhookEvent, paymentsReady, planDelivery, projectApplicant, projectSharedRecord, reconcileMeetings, refundedPatch, render, renderSummary, renderTemplateBody, renewalPatch, resolveApplication, resolveAuth, resolvePipeline, resolveScheduling, roleFromClaim, sendTemplated, sharedPersonInput, slotWindow, stageIndex, stripeForm, submitApplication, subscriptionIdempotencyKey, validateScheduling, verifyStripeSignature, webhookMutationId };

package/dist/index.d.ts

@@ -215,9 +215,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;
@@ -239,6 +254,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;
 }
@@ -708,6 +725,8 @@ interface ClerkResult {
     ok: boolean;
     status: number;
     existed?: boolean;
+    /** Set when an `existed` heal also refreshed the account's public_metadata. */
+    refreshed?: boolean;
 }
 /** Inputs for a Clerk invitation. */
 interface ClerkInviteInput {
@@ -746,7 +765,9 @@ declare function clerkUserRequest(input: ClerkUserInput): {
 };
 /** Create the applicant's Clerk account server-side. A repeat for an email that
  *  already has an account heals to `{ ok: true, existed: true }` — the account
- *  exists, which is the state apply-time provisioning wanted. */
+ *  exists, which is the state apply-time provisioning wanted — and, when
+ *  `publicMetadata` was supplied, refreshes it on the existing account so a
+ *  re-application repairs a previously missed create (`refreshed: true`). */
 declare function createClerkUser(secretKey: string, input: ClerkUserInput, fetchImpl?: typeof fetch): Promise<ClerkResult>;
 
 /** An application row, as far as the session cares about it. */
@@ -888,6 +909,22 @@ declare const SCHEDULING_DEFAULTS: ResolvedScheduling;
  * `windowDays` is capped at 62 because Google FreeBusy is.
  */
 declare function resolveScheduling(config?: ChapterScheduling): ResolvedScheduling;
+/** Validation messages keyed by form field. */
+type SchedulingErrors = Record<string, string>;
+/**
+ * Validate a scheduling config field by field, collecting owner-readable messages
+ * rather than throwing on the first problem. An admin settings form needs to say
+ * *which* field is wrong and why — "pick at least one day" beats a stack trace —
+ * so the admin route returns these directly. {@link resolveScheduling} is the
+ * throwing wrapper for internal/config-time use.
+ */
+declare function validateScheduling(config?: ChapterScheduling): {
+    ok: true;
+    value: ResolvedScheduling;
+} | {
+    ok: false;
+    errors: SchedulingErrors;
+};
 /** Statuses a member may book/reschedule from (early pipeline only). */
 /** The availability window: `[now, now + windowDays]` in epoch ms. */
 declare function slotWindow(now: number, windowDays: number): {
@@ -971,4 +1008,4 @@ type ApplicationBookingPatch = {
  *  already there (never backward). */
 declare function applicationBookingUpdate(currentStatus: string, startAt: number, htmlLink?: string | null): ApplicationBookingPatch;
 
-export { type AccountModel, type Applicant, type ApplicationBookingPatch, type ApplicationRecord, type ApplicationSummary, type Attr, type AttrType, type Chapter, type ChapterApplication, type ChapterAuth, type ChapterBrand, type ChapterConfig, type ChapterDb, type ChapterEmails, type ChapterIntegrationDescriptor, type ChapterIntegrationOptions, type ChapterMode, type ChapterPipeline, type ChapterPolicy, type ChapterPrices, type ChapterScheduling, type ClerkInviteInput, type ClerkResult, type ClerkUserInput, type DbOp, type DbRules, type DbSchema, type DeliveryDecision, type EmailGroup, type EmailTemplate, type EmailTemplateRow, type Entity, type ExistingMeeting, type GuardResult, type JoinConfigGroup, type LiveEvent, type MailSender, type MeetingForReconcile, type MeetingRecord, type MeetingReschedulePatch, type MemberApplication, type MemberSession, type NewMeetingRow, type NotifyDeps, type NotifyInput, type NotifyResult, type PaymentsGroup, type ProjectionDeps, type ReconcileDecision, type ResolvedApplication, type ResolvedAuth, type ResolvedPipeline, type ResolvedScheduling, type RoleChangeContext, type Rule, SCHEDULING_DEFAULTS, type SecretStore, type SessionUser, type SharedPerson, type StripeEvent, type SubmitResult, type WebhookEvent, applicationBookingUpdate, applicationSummary, bookingDecision, brandTokens, buildGroupSeed, canApprove, canBook, canChangeRole, canTransition, canceledPatch, chapterDb, clerkInviteRequest, clerkUserRequest, createChapterIntegration, createClerkInvitation, createClerkUser, defaultCrm, defineChapter, emailGroupFrom, endForSlot, findApplicationRef, firstPaymentPatch, getVaultSecret, introIdempotencyKey, isAdminRole, isAlreadySent, isReconcilable, isSlotAvailable, joinConfig, meetingCreateRow, meetingRescheduleUpdate, memberApplication, memberSession, normalizeWebhookEvent, paymentsReady, planDelivery, projectApplicant, projectSharedRecord, reconcileMeetings, refundedPatch, render, renderSummary, renderTemplateBody, renewalPatch, resolveApplication, resolveAuth, resolvePipeline, resolveScheduling, roleFromClaim, sendTemplated, sharedPersonInput, slotWindow, stageIndex, stripeForm, submitApplication, subscriptionIdempotencyKey, verifyStripeSignature, webhookMutationId };
+export { type AccountModel, type AdminNotificationTrigger, type Applicant, type ApplicationBookingPatch, type ApplicationRecord, type ApplicationSummary, type Attr, type AttrType, type Chapter, type ChapterApplication, type ChapterAuth, type ChapterBrand, type ChapterConfig, type ChapterDb, type ChapterEmails, type ChapterIntegrationDescriptor, type ChapterIntegrationOptions, type ChapterMode, type ChapterPipeline, type ChapterPolicy, type ChapterPrices, type ChapterScheduling, type ChapterSends, type ClerkInviteInput, type ClerkResult, type ClerkUserInput, type DbOp, type DbRules, type DbSchema, type DeliveryDecision, type EmailGroup, type EmailTemplate, type EmailTemplateRow, type Entity, type ExistingMeeting, type GuardResult, type JoinConfigGroup, type LiveEvent, type MailSender, type MeetingForReconcile, type MeetingRecord, type MeetingReschedulePatch, type MemberApplication, type MemberSession, type NewMeetingRow, type NotifyDeps, type NotifyInput, type NotifyResult, type PaymentsGroup, type ProjectionDeps, type ReconcileDecision, type ResolvedApplication, type ResolvedAuth, type ResolvedPipeline, type ResolvedScheduling, type ResolvedSends, type RoleChangeContext, type Rule, SCHEDULING_DEFAULTS, type SchedulingErrors, type SecretStore, type SessionUser, type SharedPerson, type StripeEvent, type SubmitResult, type WebhookEvent, applicationBookingUpdate, applicationSummary, bookingDecision, brandTokens, buildGroupSeed, canApprove, canBook, canChangeRole, canTransition, canceledPatch, chapterDb, clerkInviteRequest, clerkUserRequest, createChapterIntegration, createClerkInvitation, createClerkUser, defaultCrm, defineChapter, emailGroupFrom, endForSlot, findApplicationRef, firstPaymentPatch, getVaultSecret, introIdempotencyKey, isAdminRole, isAlreadySent, isReconcilable, isSlotAvailable, joinConfig, meetingCreateRow, meetingRescheduleUpdate, memberApplication, memberSession, normalizeWebhookEvent, paymentsReady, planDelivery, projectApplicant, projectSharedRecord, reconcileMeetings, refundedPatch, render, renderSummary, renderTemplateBody, renewalPatch, resolveApplication, resolveAuth, resolvePipeline, resolveScheduling, roleFromClaim, sendTemplated, sharedPersonInput, slotWindow, stageIndex, stripeForm, submitApplication, subscriptionIdempotencyKey, validateScheduling, verifyStripeSignature, webhookMutationId };

package/dist/index.js

@@ -474,6 +474,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,
@@ -487,6 +494,7 @@ function defineChapter(config) {
     rules,
     services,
     account,
+    sends,
     groupSeed: () => mode === "chapter" ? buildGroupSeed(config) : null
   };
   if (config.url !== void 0) chapter.url = config.url;
@@ -797,6 +805,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}`, {
@@ -804,7 +826,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
@@ -923,6 +949,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,
@@ -934,20 +966,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 };
@@ -1052,6 +1093,7 @@ export {
   stripeForm,
   submitApplication,
   subscriptionIdempotencyKey,
+  validateScheduling,
   verifyStripeSignature,
   webhookMutationId
 };