@odla-ai/chapter 0.10.1 → 0.12.0

package/dist/worker/index.d.cts

@@ -154,6 +154,32 @@ interface ChapterApplication {
     defaultMaxLen?: number;
     /** Max JSON request body in bytes. Default 32768. */
     bodyCap?: number;
+    /** Reject a submit that carries no truthy `disclaimerAck` (400), instead of
+     *  writing a row with no consent record. Default `false` for back-compat —
+     *  but turn it on if the disclaimer is a compliance record: a missing ack is
+     *  otherwise silent, permanent and unreconstructible. Failure is deterministic
+     *  and surfaces on the first test submit, not intermittently in production. */
+    requireDisclaimerAck?: boolean;
+    /** Allowlist of fields that reach the Clerk account's client-readable
+     *  `public_metadata.profile`. Default (unset) projects every non-identity
+     *  configured field — convenient, but it also exposes free-text and
+     *  third-party fields (`message`, `referral`). Set this to a curated list
+     *  (e.g. `["phone", "state", "focus"]`) to keep confidential fields db-only.
+     *  Expected to become required-in-spirit at 1.0. */
+    profileFields?: readonly string[];
+    /** Extra application fields carried into the one-way CRM projection, on top of
+     *  the built-in identity/contact set. Each MUST be declared on your crm person
+     *  type or the enrichment is dropped (the base person still projects). Default
+     *  none. */
+    crmFields?: readonly string[];
+    /** Cap on the element count of array-valued fields (e.g. `focus`), so a client
+     *  cannot post a 10k-element array into a row or into Clerk metadata.
+     *  Non-primitive elements are dropped. Default 100. */
+    maxArrayLen?: number;
+    /** Validate that a field literally named `email` looks like an email address,
+     *  returning a 400 rather than accepting input the downstream Clerk create will
+     *  reject anyway. Default `true`; a valid application is never newly rejected. */
+    validateEmail?: boolean;
 }
 /** The fully-resolved application config carried on the {@link Chapter}. */
 interface ResolvedApplication {
@@ -162,6 +188,12 @@ interface ResolvedApplication {
     maxLen: Record<string, number>;
     defaultMaxLen: number;
     bodyCap: number;
+    requireDisclaimerAck: boolean;
+    /** Resolved Clerk-metadata allowlist; `null` means "all non-identity fields". */
+    profileFields: readonly string[] | null;
+    crmFields: readonly string[];
+    maxArrayLen: number;
+    validateEmail: boolean;
 }
 /** The `defineChapter()` config a site fills in. */
 interface ChapterConfig {

package/dist/worker/index.d.ts

@@ -154,6 +154,32 @@ interface ChapterApplication {
     defaultMaxLen?: number;
     /** Max JSON request body in bytes. Default 32768. */
     bodyCap?: number;
+    /** Reject a submit that carries no truthy `disclaimerAck` (400), instead of
+     *  writing a row with no consent record. Default `false` for back-compat —
+     *  but turn it on if the disclaimer is a compliance record: a missing ack is
+     *  otherwise silent, permanent and unreconstructible. Failure is deterministic
+     *  and surfaces on the first test submit, not intermittently in production. */
+    requireDisclaimerAck?: boolean;
+    /** Allowlist of fields that reach the Clerk account's client-readable
+     *  `public_metadata.profile`. Default (unset) projects every non-identity
+     *  configured field — convenient, but it also exposes free-text and
+     *  third-party fields (`message`, `referral`). Set this to a curated list
+     *  (e.g. `["phone", "state", "focus"]`) to keep confidential fields db-only.
+     *  Expected to become required-in-spirit at 1.0. */
+    profileFields?: readonly string[];
+    /** Extra application fields carried into the one-way CRM projection, on top of
+     *  the built-in identity/contact set. Each MUST be declared on your crm person
+     *  type or the enrichment is dropped (the base person still projects). Default
+     *  none. */
+    crmFields?: readonly string[];
+    /** Cap on the element count of array-valued fields (e.g. `focus`), so a client
+     *  cannot post a 10k-element array into a row or into Clerk metadata.
+     *  Non-primitive elements are dropped. Default 100. */
+    maxArrayLen?: number;
+    /** Validate that a field literally named `email` looks like an email address,
+     *  returning a 400 rather than accepting input the downstream Clerk create will
+     *  reject anyway. Default `true`; a valid application is never newly rejected. */
+    validateEmail?: boolean;
 }
 /** The fully-resolved application config carried on the {@link Chapter}. */
 interface ResolvedApplication {
@@ -162,6 +188,12 @@ interface ResolvedApplication {
     maxLen: Record<string, number>;
     defaultMaxLen: number;
     bodyCap: number;
+    requireDisclaimerAck: boolean;
+    /** Resolved Clerk-metadata allowlist; `null` means "all non-identity fields". */
+    profileFields: readonly string[] | null;
+    crmFields: readonly string[];
+    maxArrayLen: number;
+    validateEmail: boolean;
 }
 /** The `defineChapter()` config a site fills in. */
 interface ChapterConfig {

package/dist/worker/index.js

@@ -157,15 +157,28 @@ async function createClerkUser(secretKey, input, fetchImpl = fetch) {
 }
 
 // src/member.ts
+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) {
@@ -179,19 +192,26 @@ 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" };
+  }
   const id = opts.newId();
   const row = { id, status: chapter.pipeline.initial, createdAt: opts.now };
   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 (fields.disclaimerAck === true || fields.disclaimerAck === "true") row.disclaimerAckAt = opts.now;
+  if (acked) row.disclaimerAckAt = opts.now;
   const { duplicate } = await db.transact(
     [{ t: "update", ns: "applications", id, attrs: row }],
     opts.submissionId ? { mutationId: `join:${opts.submissionId}` } : void 0
   );
-  return { ok: true, id, duplicate, status: chapter.pipeline.initial };
+  return { ok: true, id, duplicate, status: chapter.pipeline.initial, disclaimerAckAt: acked ? opts.now : null };
 }
 function joinConfig(group, paymentsReady) {
   return {
@@ -237,7 +257,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,
@@ -245,7 +265,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/scheduling.ts
@@ -489,10 +516,14 @@ async function provisionApplicant(db, chapter, applicationId, fields) {
   const email = typeof fields.email === "string" ? fields.email : "";
   if (!email) return;
   const s = (v) => typeof v === "string" ? v : void 0;
+  const extra = {};
+  for (const f of chapter.application.crmFields) {
+    if (fields[f] !== void 0) extra[f] = fields[f];
+  }
   try {
     await projectApplicant(
       { crm: chapter.crm, db, now: () => Date.now(), newId: () => crypto.randomUUID() },
-      { applicationId, email, firstName: s(fields.firstName), lastName: s(fields.lastName), phone: s(fields.phone), linkedin: s(fields.linkedin) }
+      { applicationId, email, firstName: s(fields.firstName), lastName: s(fields.lastName), phone: s(fields.phone), linkedin: s(fields.linkedin), extra }
     );
   } catch {
   }
@@ -647,7 +678,14 @@ var handleMember = async (req, url, env, ctx) => {
       }
       await provisionApplicant(db, chapter, result.id, parsed);
     }
-    return json({ id: result.id, duplicate: result.duplicate, status: result.status });
+    return json({
+      id: result.id,
+      duplicate: result.duplicate,
+      status: result.status,
+      // Echoed so a site can see (and assert in an integration test) whether its
+      // join page actually posted the ack. Absent consent is otherwise invisible.
+      disclaimerAckAt: result.disclaimerAckAt
+    });
   }
   return null;
 };