@odla-ai/chapter 0.11.0 → 0.13.0

package/dist/index.d.cts

@@ -181,6 +181,26 @@ interface ChapterApplication {
      *  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 {
@@ -190,6 +210,11 @@ interface ResolvedApplication {
     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 {
@@ -632,15 +657,22 @@ declare function canceledPatch(): {
 
 /** Apply defaults + validate the application config. Throws at import on bad shape. */
 declare function resolveApplication(a: ChapterApplication | undefined): ResolvedApplication;
+/** Whether a string looks like an email address (see {@link EMAIL_RE}). Exported
+ *  so a site building its own submit path applies the same rule chapter does. */
+declare function isValidEmail(value: unknown): boolean;
+/** Bound an array-valued field: drop non-primitive elements and cap the length,
+ *  so a client cannot post an unbounded array. Non-arrays pass through unchanged. */
+declare function clampArray(value: unknown, max: number): unknown;
 /** Whether a submit body carries a genuine disclaimer acknowledgement. Accepts
  *  the boolean an API client sends and the string a plain HTML form posts. */
 declare function hasDisclaimerAck(fields: Record<string, unknown>): boolean;
 /**
- * The applicant profile written to the Clerk account's `public_metadata.profile`:
- * every configured application field Clerk does not already carry natively, plus
- * `focus`. Derived from `application.required`/`optional`, so a site's own field
- * names project without this package knowing them. Pure; returns `undefined` when
- * there is nothing to write.
+ * The applicant profile written to the Clerk account's client-readable
+ * `public_metadata.profile`. Projects each configured non-identity field, plus
+ * `focus` (clamped) — but ONLY those in `application.profileFields` when that
+ * allowlist is set, so a site keeps confidential fields (`message`, `referral`)
+ * db-only. Derived from config, so a site's own field names project without this
+ * package knowing them. Pure; returns `undefined` when there is nothing to write.
  */
 declare function applicantProfile(chapter: Chapter, fields: Record<string, unknown>): Record<string, unknown> | undefined;
 /** A validated submission, or a 400-worthy validation error the route returns.
@@ -722,7 +754,9 @@ interface ProjectionDeps {
 declare function projectSharedRecord(deps: ProjectionDeps, person: SharedPerson): Promise<{
     recordId: string;
 }>;
-/** An arriving applicant, as far as the CRM projection cares. */
+/** An arriving applicant, as far as the CRM projection cares. `extra` carries the
+ *  site-configured `crmFields` (values from the application), merged on top of the
+ *  built-in identity/contact set. */
 interface Applicant {
     applicationId: string;
     email: string;
@@ -730,12 +764,18 @@ interface Applicant {
     lastName?: string;
     phone?: string;
     linkedin?: string;
+    extra?: Record<string, unknown>;
 }
 /**
  * Project an arriving applicant into this chapter's `crm_record`, so a new
  * application shows up in the CRM immediately, unified by email with any prior
  * record. Idempotent per application (`apply:${applicationId}`). Best-effort at
  * the call site — a projection failure never fails the application.
+ *
+ * `extra` fields (a site's `crmFields`) are merged on top of the base person. If
+ * an extra field is not on the crm person type, crm validation throws — so the
+ * projection retries with the base person alone, ensuring a misconfigured
+ * enrichment never silently drops the applicant from the CRM entirely.
  */
 declare function projectApplicant(deps: ProjectionDeps, applicant: Applicant): Promise<{
     recordId: string;
@@ -793,6 +833,32 @@ declare function clerkUserRequest(input: ClerkUserInput): {
  *  re-application repairs a previously missed create (`refreshed: true`). */
 declare function createClerkUser(secretKey: string, input: ClerkUserInput, fetchImpl?: typeof fetch): Promise<ClerkResult>;
 
+/** A Clerk user as chapter's role layer sees it. `role` defaults to the lowest
+ *  rung when `public_metadata` carries none; `publicMetadata` is returned raw so a
+ *  site with a custom ladder can re-derive it. */
+interface ClerkUserRecord {
+    id: string;
+    email?: string;
+    role: string;
+    publicMetadata: Record<string, unknown>;
+}
+/** Look a Clerk user up by email. `null` when no such user — or when the lookup
+ *  fails (a role gate treats an unresolvable user as absent, matching the site's
+ *  own fallback). Role defaults to provisional when unset. */
+declare function clerkGetUserByEmail(secretKey: string, email: string, fetchImpl?: typeof fetch): Promise<ClerkUserRecord | null>;
+/** Fetch a Clerk user by id, for role-change gating. `null` when missing or on a
+ *  failed lookup. Role defaults to provisional when unset. */
+declare function clerkGetUser(secretKey: string, id: string, fetchImpl?: typeof fetch): Promise<ClerkUserRecord | null>;
+/** List ALL Clerk users with their roles, auto-paginating. A membership community
+ *  outgrows one page, and a fixed `limit=100` would silently drop members from the
+ *  admin roster with no error — so this pages (offset in steps of {@link PAGE})
+ *  until a short page. A page fetch that fails THROWS rather than returning a
+ *  partial list, so the caller never mistakes a truncated roster for the whole. */
+declare function clerkListUsers(secretKey: string, fetchImpl?: typeof fetch): Promise<ClerkUserRecord[]>;
+/** Write a user's role: a MERGE-PATCH of only `{ role }` on `public_metadata`, so
+ *  it leaves a separately-written `profile` untouched. Returns whether it stuck. */
+declare function clerkSetRole(secretKey: string, id: string, role: string, fetchImpl?: typeof fetch): Promise<boolean>;
+
 /** An application row, as far as the session cares about it. */
 interface ApplicationRecord {
     id: string;
@@ -1031,4 +1097,4 @@ type ApplicationBookingPatch = {
  *  already there (never backward). */
 declare function applicationBookingUpdate(currentStatus: string, startAt: number, htmlLink?: string | null): ApplicationBookingPatch;
 
-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, applicantProfile, applicationBookingUpdate, applicationSummary, bookingDecision, brandTokens, buildGroupSeed, canApprove, canBook, canChangeRole, canTransition, canceledPatch, chapterDb, clerkInviteRequest, clerkUserRequest, createChapterIntegration, createClerkInvitation, createClerkUser, defaultCrm, defineChapter, emailGroupFrom, endForSlot, findApplicationRef, firstPaymentPatch, getVaultSecret, hasDisclaimerAck, 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 };
+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 ClerkUserRecord, 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, applicantProfile, applicationBookingUpdate, applicationSummary, bookingDecision, brandTokens, buildGroupSeed, canApprove, canBook, canChangeRole, canTransition, canceledPatch, chapterDb, clampArray, clerkGetUser, clerkGetUserByEmail, clerkInviteRequest, clerkListUsers, clerkSetRole, clerkUserRequest, createChapterIntegration, createClerkInvitation, createClerkUser, defaultCrm, defineChapter, emailGroupFrom, endForSlot, findApplicationRef, firstPaymentPatch, getVaultSecret, hasDisclaimerAck, introIdempotencyKey, isAdminRole, isAlreadySent, isReconcilable, isSlotAvailable, isValidEmail, 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

@@ -181,6 +181,26 @@ interface ChapterApplication {
      *  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 {
@@ -190,6 +210,11 @@ interface ResolvedApplication {
     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 {
@@ -632,15 +657,22 @@ declare function canceledPatch(): {
 
 /** Apply defaults + validate the application config. Throws at import on bad shape. */
 declare function resolveApplication(a: ChapterApplication | undefined): ResolvedApplication;
+/** Whether a string looks like an email address (see {@link EMAIL_RE}). Exported
+ *  so a site building its own submit path applies the same rule chapter does. */
+declare function isValidEmail(value: unknown): boolean;
+/** Bound an array-valued field: drop non-primitive elements and cap the length,
+ *  so a client cannot post an unbounded array. Non-arrays pass through unchanged. */
+declare function clampArray(value: unknown, max: number): unknown;
 /** Whether a submit body carries a genuine disclaimer acknowledgement. Accepts
  *  the boolean an API client sends and the string a plain HTML form posts. */
 declare function hasDisclaimerAck(fields: Record<string, unknown>): boolean;
 /**
- * The applicant profile written to the Clerk account's `public_metadata.profile`:
- * every configured application field Clerk does not already carry natively, plus
- * `focus`. Derived from `application.required`/`optional`, so a site's own field
- * names project without this package knowing them. Pure; returns `undefined` when
- * there is nothing to write.
+ * The applicant profile written to the Clerk account's client-readable
+ * `public_metadata.profile`. Projects each configured non-identity field, plus
+ * `focus` (clamped) — but ONLY those in `application.profileFields` when that
+ * allowlist is set, so a site keeps confidential fields (`message`, `referral`)
+ * db-only. Derived from config, so a site's own field names project without this
+ * package knowing them. Pure; returns `undefined` when there is nothing to write.
  */
 declare function applicantProfile(chapter: Chapter, fields: Record<string, unknown>): Record<string, unknown> | undefined;
 /** A validated submission, or a 400-worthy validation error the route returns.
@@ -722,7 +754,9 @@ interface ProjectionDeps {
 declare function projectSharedRecord(deps: ProjectionDeps, person: SharedPerson): Promise<{
     recordId: string;
 }>;
-/** An arriving applicant, as far as the CRM projection cares. */
+/** An arriving applicant, as far as the CRM projection cares. `extra` carries the
+ *  site-configured `crmFields` (values from the application), merged on top of the
+ *  built-in identity/contact set. */
 interface Applicant {
     applicationId: string;
     email: string;
@@ -730,12 +764,18 @@ interface Applicant {
     lastName?: string;
     phone?: string;
     linkedin?: string;
+    extra?: Record<string, unknown>;
 }
 /**
  * Project an arriving applicant into this chapter's `crm_record`, so a new
  * application shows up in the CRM immediately, unified by email with any prior
  * record. Idempotent per application (`apply:${applicationId}`). Best-effort at
  * the call site — a projection failure never fails the application.
+ *
+ * `extra` fields (a site's `crmFields`) are merged on top of the base person. If
+ * an extra field is not on the crm person type, crm validation throws — so the
+ * projection retries with the base person alone, ensuring a misconfigured
+ * enrichment never silently drops the applicant from the CRM entirely.
  */
 declare function projectApplicant(deps: ProjectionDeps, applicant: Applicant): Promise<{
     recordId: string;
@@ -793,6 +833,32 @@ declare function clerkUserRequest(input: ClerkUserInput): {
  *  re-application repairs a previously missed create (`refreshed: true`). */
 declare function createClerkUser(secretKey: string, input: ClerkUserInput, fetchImpl?: typeof fetch): Promise<ClerkResult>;
 
+/** A Clerk user as chapter's role layer sees it. `role` defaults to the lowest
+ *  rung when `public_metadata` carries none; `publicMetadata` is returned raw so a
+ *  site with a custom ladder can re-derive it. */
+interface ClerkUserRecord {
+    id: string;
+    email?: string;
+    role: string;
+    publicMetadata: Record<string, unknown>;
+}
+/** Look a Clerk user up by email. `null` when no such user — or when the lookup
+ *  fails (a role gate treats an unresolvable user as absent, matching the site's
+ *  own fallback). Role defaults to provisional when unset. */
+declare function clerkGetUserByEmail(secretKey: string, email: string, fetchImpl?: typeof fetch): Promise<ClerkUserRecord | null>;
+/** Fetch a Clerk user by id, for role-change gating. `null` when missing or on a
+ *  failed lookup. Role defaults to provisional when unset. */
+declare function clerkGetUser(secretKey: string, id: string, fetchImpl?: typeof fetch): Promise<ClerkUserRecord | null>;
+/** List ALL Clerk users with their roles, auto-paginating. A membership community
+ *  outgrows one page, and a fixed `limit=100` would silently drop members from the
+ *  admin roster with no error — so this pages (offset in steps of {@link PAGE})
+ *  until a short page. A page fetch that fails THROWS rather than returning a
+ *  partial list, so the caller never mistakes a truncated roster for the whole. */
+declare function clerkListUsers(secretKey: string, fetchImpl?: typeof fetch): Promise<ClerkUserRecord[]>;
+/** Write a user's role: a MERGE-PATCH of only `{ role }` on `public_metadata`, so
+ *  it leaves a separately-written `profile` untouched. Returns whether it stuck. */
+declare function clerkSetRole(secretKey: string, id: string, role: string, fetchImpl?: typeof fetch): Promise<boolean>;
+
 /** An application row, as far as the session cares about it. */
 interface ApplicationRecord {
     id: string;
@@ -1031,4 +1097,4 @@ type ApplicationBookingPatch = {
  *  already there (never backward). */
 declare function applicationBookingUpdate(currentStatus: string, startAt: number, htmlLink?: string | null): ApplicationBookingPatch;
 
-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, applicantProfile, applicationBookingUpdate, applicationSummary, bookingDecision, brandTokens, buildGroupSeed, canApprove, canBook, canChangeRole, canTransition, canceledPatch, chapterDb, clerkInviteRequest, clerkUserRequest, createChapterIntegration, createClerkInvitation, createClerkUser, defaultCrm, defineChapter, emailGroupFrom, endForSlot, findApplicationRef, firstPaymentPatch, getVaultSecret, hasDisclaimerAck, 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 };
+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 ClerkUserRecord, 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, applicantProfile, applicationBookingUpdate, applicationSummary, bookingDecision, brandTokens, buildGroupSeed, canApprove, canBook, canChangeRole, canTransition, canceledPatch, chapterDb, clampArray, clerkGetUser, clerkGetUserByEmail, clerkInviteRequest, clerkListUsers, clerkSetRole, clerkUserRequest, createChapterIntegration, createClerkInvitation, createClerkUser, defaultCrm, defineChapter, emailGroupFrom, endForSlot, findApplicationRef, firstPaymentPatch, getVaultSecret, hasDisclaimerAck, introIdempotencyKey, isAdminRole, isAlreadySent, isReconcilable, isSlotAvailable, isValidEmail, 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

@@ -395,27 +395,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) {
@@ -429,6 +449,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" };
@@ -438,7 +461,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(
@@ -780,7 +803,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,
@@ -788,7 +811,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
@@ -853,6 +883,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 {
@@ -1069,7 +1146,12 @@ export {
   canTransition,
   canceledPatch,
   chapterDb,
+  clampArray,
+  clerkGetUser,
+  clerkGetUserByEmail,
   clerkInviteRequest,
+  clerkListUsers,
+  clerkSetRole,
   clerkUserRequest,
   createChapterIntegration,
   createClerkInvitation,
@@ -1087,6 +1169,7 @@ export {
   isAlreadySent,
   isReconcilable,
   isSlotAvailable,
+  isValidEmail,
   joinConfig,
   meetingCreateRow,
   meetingRescheduleUpdate,