@odla-ai/chapter 0.11.0 → 0.13.0

package/README.md

@@ -156,12 +156,29 @@ These bite silently — a smoke test won't catch them:
   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
+- **What lands on the Clerk account (and its `public_metadata` is
+  client-readable).** Both models write `public_metadata` as
+  `{ applicationId, profile }`. By default `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.
+  (so *not* email/firstName/lastName), plus `focus` — **which means free-text or
+  third-party fields like `message` or `referral` are exposed to the browser
+  unless you curate.** Set `application: { profileFields: ["phone", "state",
+  "focus", ...] }` to an allowlist and everything else stays db-only. Array fields
+  (`focus`) are clamped to `maxArrayLen` (default 100) and non-primitive elements
+  dropped, so a client can't post an unbounded array into metadata.
+  `applicantProfile(chapter, fields)` is exported to assert the exact shape in a
+  test before deleting a local override. (Default is back-compat today; expected
+  to tighten at 1.0.)
+- **Email + input validation.** The field literally named `email` is checked
+  against a permissive email shape (400 on `"notanemail"`, so it fails cleanly
+  here rather than at the downstream Clerk create) — set
+  `application: { validateEmail: false }` to opt out; `isValidEmail` is exported.
+  A valid application is never newly rejected.
+- **CRM enrichment.** `projectApplicant` writes the base identity/contact person.
+  To carry more of the application into the CRM, list `application: { crmFields:
+  [...] }` — each must be a field on your crm person type, else that field is
+  dropped and the base person still projects (it is never lost). Stage mirroring,
+  billing snapshots and Clerk-identity linking stay yours as host routes.
 - **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
@@ -219,6 +236,20 @@ These bite silently — a smoke test won't catch them:
   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.
+- **`onboardingInvite` is a template with no built-in caller.** It is seeded into
+  the group's email settings (so you can edit its copy) but chapter never fires
+  it, because the moment it would fire — approval — is a host route (approval is
+  out of scope, above). Send it from your own approve handler via `sendTemplated`;
+  the seed existing does not mean the built-ins send it.
+- **Server-side Clerk is exported, even though the admin *routes* aren't.** A role
+  change is your host route — but you don't hand-roll the Clerk REST calls for it.
+  Beside `createClerkUser`/`createClerkInvitation`/`canChangeRole`, chapter exports
+  the odla→Clerk write half: `clerkGetUserByEmail`, `clerkGetUser`, `clerkListUsers`
+  (auto-paginated — never a silent 100-user cap), and `clerkSetRole`. Two
+  load-bearing semantics: an absent `public_metadata.role` reads as the lowest rung
+  (`"provisional"`), and `clerkSetRole` merge-`PATCH`es only `{ role }` so it never
+  clobbers a separately-written `public_metadata.profile`. All take an injectable
+  `fetch` and the vault `clerk_secret_key`.
 
 ### Verify from the types, not this file
 

package/dist/index.cjs

@@ -33,7 +33,12 @@ __export(index_exports, {
   canTransition: () => canTransition,
   canceledPatch: () => canceledPatch,
   chapterDb: () => chapterDb,
+  clampArray: () => clampArray,
+  clerkGetUser: () => clerkGetUser,
+  clerkGetUserByEmail: () => clerkGetUserByEmail,
   clerkInviteRequest: () => clerkInviteRequest,
+  clerkListUsers: () => clerkListUsers,
+  clerkSetRole: () => clerkSetRole,
   clerkUserRequest: () => clerkUserRequest,
   createChapterIntegration: () => createChapterIntegration,
   createClerkInvitation: () => createClerkInvitation,
@@ -51,6 +56,7 @@ __export(index_exports, {
   isAlreadySent: () => isAlreadySent,
   isReconcilable: () => isReconcilable,
   isSlotAvailable: () => isSlotAvailable,
+  isValidEmail: () => isValidEmail,
   joinConfig: () => joinConfig,
   meetingCreateRow: () => meetingCreateRow,
   meetingRescheduleUpdate: () => meetingRescheduleUpdate,
@@ -482,27 +488,47 @@ function resolveApplication(a) {
       throw new Error(`defineChapter.application.${name}: must be an array of field-name strings`);
     }
   }
+  if (a?.profileFields !== void 0 && (!Array.isArray(a.profileFields) || !a.profileFields.every((f) => typeof f === "string" && f !== ""))) {
+    throw new Error("defineChapter.application.profileFields: must be an array of field-name strings");
+  }
+  if (a?.crmFields !== void 0 && (!Array.isArray(a.crmFields) || !a.crmFields.every((f) => typeof f === "string" && f !== ""))) {
+    throw new Error("defineChapter.application.crmFields: must be an array of field-name strings");
+  }
   return {
     required,
     optional,
     maxLen: a?.maxLen ?? {},
     defaultMaxLen: a?.defaultMaxLen ?? 2e3,
     bodyCap: a?.bodyCap ?? 32768,
-    requireDisclaimerAck: a?.requireDisclaimerAck ?? false
+    requireDisclaimerAck: a?.requireDisclaimerAck ?? false,
+    profileFields: a?.profileFields ?? null,
+    crmFields: a?.crmFields ?? [],
+    maxArrayLen: a?.maxArrayLen ?? 100,
+    validateEmail: a?.validateEmail ?? true
   };
 }
+var EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+function isValidEmail(value) {
+  return typeof value === "string" && EMAIL_RE.test(value);
+}
+function clampArray(value, max) {
+  if (!Array.isArray(value)) return value;
+  return value.filter((x) => typeof x === "string" || typeof x === "number" || typeof x === "boolean").slice(0, max);
+}
 function hasDisclaimerAck(fields) {
   return fields.disclaimerAck === true || fields.disclaimerAck === "true";
 }
 var IDENTITY_FIELDS = /* @__PURE__ */ new Set(["email", "firstName", "lastName"]);
 function applicantProfile(chapter, fields) {
+  const app = chapter.application;
+  const allowed = (f) => app.profileFields === null || app.profileFields.includes(f);
   const profile = {};
-  for (const f of [...chapter.application.required, ...chapter.application.optional]) {
-    if (IDENTITY_FIELDS.has(f)) continue;
+  for (const f of [...app.required, ...app.optional]) {
+    if (IDENTITY_FIELDS.has(f) || !allowed(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;
+  if (fields.focus !== void 0 && allowed("focus")) profile.focus = clampArray(fields.focus, app.maxArrayLen);
   return Object.keys(profile).length > 0 ? profile : void 0;
 }
 async function submitApplication(db, chapter, fields, opts) {
@@ -516,6 +542,9 @@ async function submitApplication(db, chapter, fields, opts) {
     const cap = app.maxLen[f] ?? app.defaultMaxLen;
     if (typeof v === "string" && v.length > cap) return { ok: false, error: `${f} exceeds ${cap} characters` };
   }
+  if (app.validateEmail && typeof fields.email === "string" && !isValidEmail(fields.email)) {
+    return { ok: false, error: "email must be a valid email address" };
+  }
   const acked = hasDisclaimerAck(fields);
   if (app.requireDisclaimerAck && !acked) {
     return { ok: false, error: "disclaimerAck is required" };
@@ -525,7 +554,7 @@ async function submitApplication(db, chapter, fields, opts) {
   for (const f of [...app.required, ...app.optional]) {
     if (typeof fields[f] === "string") row[f] = fields[f].trim();
   }
-  if (fields.focus !== void 0) row.focus = fields.focus;
+  if (fields.focus !== void 0) row.focus = clampArray(fields.focus, app.maxArrayLen);
   if (opts.groupId) row.groupId = opts.groupId;
   if (acked) row.disclaimerAckAt = opts.now;
   const { duplicate } = await db.transact(
@@ -867,7 +896,7 @@ 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({
+  const base = sharedPersonInput({
     email: applicant.email,
     firstName: applicant.firstName,
     lastName: applicant.lastName,
@@ -875,7 +904,14 @@ async function projectApplicant(deps, applicant) {
     linkedin: applicant.linkedin,
     hubRecordId: applicant.applicationId
   });
-  return upsertPerson(deps, { email: applicant.email, input, mutationId: `apply:${applicant.applicationId}` });
+  const mutationId = `apply:${applicant.applicationId}`;
+  const extra = applicant.extra ?? {};
+  if (Object.keys(extra).length === 0) return upsertPerson(deps, { email: applicant.email, input: base, mutationId });
+  try {
+    return await upsertPerson(deps, { email: applicant.email, input: { ...base, ...extra }, mutationId });
+  } catch {
+    return upsertPerson(deps, { email: applicant.email, input: base, mutationId });
+  }
 }
 
 // src/clerk.ts
@@ -940,6 +976,53 @@ async function createClerkUser(secretKey, input, fetchImpl = fetch) {
   return { ...healed, refreshed };
 }
 
+// src/clerk-roles.ts
+var CLERK_API = "https://api.clerk.com";
+var DEFAULT_ROLE = "provisional";
+var PAGE = 100;
+function toRecord(u) {
+  if (typeof u.id !== "string") return null;
+  const pm = u.public_metadata ?? {};
+  const role = typeof pm.role === "string" && pm.role ? pm.role : DEFAULT_ROLE;
+  const email = u.email_addresses?.[0]?.email_address;
+  return { id: u.id, email: typeof email === "string" ? email : void 0, role, publicMetadata: pm };
+}
+async function clerkGet(path, secretKey, fetchImpl) {
+  const res = await fetchImpl(`${CLERK_API}${path}`, { headers: { authorization: `Bearer ${secretKey}` } });
+  if (!res.ok) throw new Error(`clerk GET ${path} \u2192 ${res.status}`);
+  return res.json();
+}
+async function clerkGetUserByEmail(secretKey, email, fetchImpl = fetch) {
+  const data = await clerkGet(`/v1/users?email_address=${encodeURIComponent(email)}&limit=1`, secretKey, fetchImpl).catch(() => null);
+  const user = Array.isArray(data) ? data[0] : void 0;
+  return user ? toRecord(user) : null;
+}
+async function clerkGetUser(secretKey, id2, fetchImpl = fetch) {
+  const data = await clerkGet(`/v1/users/${encodeURIComponent(id2)}`, secretKey, fetchImpl).catch(() => null);
+  return data ? toRecord(data) : null;
+}
+async function clerkListUsers(secretKey, fetchImpl = fetch) {
+  const out = [];
+  for (let offset = 0; ; offset += PAGE) {
+    const data = await clerkGet(`/v1/users?limit=${PAGE}&offset=${offset}`, secretKey, fetchImpl);
+    const page = Array.isArray(data) ? data : [];
+    for (const u of page) {
+      const record = toRecord(u);
+      if (record) out.push(record);
+    }
+    if (page.length < PAGE) break;
+  }
+  return out;
+}
+async function clerkSetRole(secretKey, id2, role, fetchImpl = fetch) {
+  const res = await fetchImpl(`${CLERK_API}/v1/users/${encodeURIComponent(id2)}/metadata`, {
+    method: "PATCH",
+    headers: { authorization: `Bearer ${secretKey}`, "content-type": "application/json" },
+    body: JSON.stringify({ public_metadata: { role } })
+  });
+  return res.ok;
+}
+
 // src/session.ts
 function applicationSummary(app) {
   return {