@odla-ai/chapter 0.7.0 → 0.9.0

package/dist/index.d.cts

@@ -210,7 +210,14 @@ interface ChapterConfig {
     auth?: ChapterAuth;
     /** odla services (db implied). Default `["db","calendar","o11y"]`. */
     services?: readonly string[];
-}
+    /** Apply-time account provisioning: `"invite"` (default) mints a Clerk
+     *  invitation, `"create"` makes the account server-side (so join can say the
+     *  account is ready), `"none"` skips it. Any of these needs a `clerk_secret_key`
+     *  vault secret to act. */
+    account?: AccountModel;
+}
+/** Apply-time Clerk account provisioning model. */
+type AccountModel = "invite" | "create" | "none";
 /** The resolved engine `defineChapter()` returns. */
 interface Chapter {
     config: ChapterConfig;
@@ -230,6 +237,8 @@ interface Chapter {
     schema: DbSchema;
     rules: DbRules;
     services: readonly string[];
+    /** Resolved apply-time account provisioning model (default `"invite"`). */
+    account: AccountModel;
     /** The seed `groups` row derived from config (chapter mode), else `null`. */
     groupSeed(): Record<string, unknown> | null;
 }
@@ -692,11 +701,22 @@ declare function projectApplicant(deps: ProjectionDeps, applicant: Applicant): P
     recordId: string;
 }>;
 
+/** The outcome of a Clerk provisioning call. `existed` marks the heal case: Clerk
+ *  rejected it because the account/invitation is already there, which is the end
+ *  state we wanted anyway. */
+interface ClerkResult {
+    ok: boolean;
+    status: number;
+    existed?: boolean;
+}
 /** Inputs for a Clerk invitation. */
 interface ClerkInviteInput {
     email: string;
     /** Where the accept-invitation link lands (usually the member area). */
     redirectUrl?: string;
+    /** Written to the invitation's `public_metadata`, so the accepted account
+     *  carries your own profile fields. */
+    publicMetadata?: Record<string, unknown>;
 }
 /** Build the Clerk Backend API invitation request (path + JSON body). Pure, so
  *  the wire shape is testable without a network call. */
@@ -704,13 +724,30 @@ declare function clerkInviteRequest(input: ClerkInviteInput): {
     path: string;
     body: Record<string, unknown>;
 };
-/** POST the invitation to the Clerk Backend API. `ignore_existing` isn't set, so
- *  a repeat invite for an already-invited/known email returns non-ok — the caller
- *  swallows that (idempotent-enough for a best-effort apply-time invite). */
-declare function createClerkInvitation(secretKey: string, input: ClerkInviteInput, fetchImpl?: typeof fetch): Promise<{
-    ok: boolean;
-    status: number;
-}>;
+/** POST the invitation to the Clerk Backend API. A repeat invite for an
+ *  already-invited email heals to `{ ok: true, existed: true }` rather than
+ *  reporting a failure the caller would have to special-case. */
+declare function createClerkInvitation(secretKey: string, input: ClerkInviteInput, fetchImpl?: typeof fetch): Promise<ClerkResult>;
+/** Inputs for a server-side Clerk user create. */
+interface ClerkUserInput {
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    /** Written to the user's `public_metadata` — the site's own profile fields
+     *  (role, tier, whatever the member area reads). */
+    publicMetadata?: Record<string, unknown>;
+}
+/** Build the Clerk Backend API user-create request. The account is created
+ *  passwordless (the member signs in via the site's Clerk flow), so join step 3
+ *  can say the account is ready — the "create" alternative to an invitation. */
+declare function clerkUserRequest(input: ClerkUserInput): {
+    path: string;
+    body: Record<string, unknown>;
+};
+/** 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. */
+declare function createClerkUser(secretKey: string, input: ClerkUserInput, fetchImpl?: typeof fetch): Promise<ClerkResult>;
 
 /** An application row, as far as the session cares about it. */
 interface ApplicationRecord {
@@ -934,4 +971,4 @@ type ApplicationBookingPatch = {
  *  already there (never backward). */
 declare function applicationBookingUpdate(currentStatus: string, startAt: number, htmlLink?: string | null): ApplicationBookingPatch;
 
-export { 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 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, createChapterIntegration, createClerkInvitation, 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 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 };

package/dist/index.d.ts

@@ -210,7 +210,14 @@ interface ChapterConfig {
     auth?: ChapterAuth;
     /** odla services (db implied). Default `["db","calendar","o11y"]`. */
     services?: readonly string[];
-}
+    /** Apply-time account provisioning: `"invite"` (default) mints a Clerk
+     *  invitation, `"create"` makes the account server-side (so join can say the
+     *  account is ready), `"none"` skips it. Any of these needs a `clerk_secret_key`
+     *  vault secret to act. */
+    account?: AccountModel;
+}
+/** Apply-time Clerk account provisioning model. */
+type AccountModel = "invite" | "create" | "none";
 /** The resolved engine `defineChapter()` returns. */
 interface Chapter {
     config: ChapterConfig;
@@ -230,6 +237,8 @@ interface Chapter {
     schema: DbSchema;
     rules: DbRules;
     services: readonly string[];
+    /** Resolved apply-time account provisioning model (default `"invite"`). */
+    account: AccountModel;
     /** The seed `groups` row derived from config (chapter mode), else `null`. */
     groupSeed(): Record<string, unknown> | null;
 }
@@ -692,11 +701,22 @@ declare function projectApplicant(deps: ProjectionDeps, applicant: Applicant): P
     recordId: string;
 }>;
 
+/** The outcome of a Clerk provisioning call. `existed` marks the heal case: Clerk
+ *  rejected it because the account/invitation is already there, which is the end
+ *  state we wanted anyway. */
+interface ClerkResult {
+    ok: boolean;
+    status: number;
+    existed?: boolean;
+}
 /** Inputs for a Clerk invitation. */
 interface ClerkInviteInput {
     email: string;
     /** Where the accept-invitation link lands (usually the member area). */
     redirectUrl?: string;
+    /** Written to the invitation's `public_metadata`, so the accepted account
+     *  carries your own profile fields. */
+    publicMetadata?: Record<string, unknown>;
 }
 /** Build the Clerk Backend API invitation request (path + JSON body). Pure, so
  *  the wire shape is testable without a network call. */
@@ -704,13 +724,30 @@ declare function clerkInviteRequest(input: ClerkInviteInput): {
     path: string;
     body: Record<string, unknown>;
 };
-/** POST the invitation to the Clerk Backend API. `ignore_existing` isn't set, so
- *  a repeat invite for an already-invited/known email returns non-ok — the caller
- *  swallows that (idempotent-enough for a best-effort apply-time invite). */
-declare function createClerkInvitation(secretKey: string, input: ClerkInviteInput, fetchImpl?: typeof fetch): Promise<{
-    ok: boolean;
-    status: number;
-}>;
+/** POST the invitation to the Clerk Backend API. A repeat invite for an
+ *  already-invited email heals to `{ ok: true, existed: true }` rather than
+ *  reporting a failure the caller would have to special-case. */
+declare function createClerkInvitation(secretKey: string, input: ClerkInviteInput, fetchImpl?: typeof fetch): Promise<ClerkResult>;
+/** Inputs for a server-side Clerk user create. */
+interface ClerkUserInput {
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    /** Written to the user's `public_metadata` — the site's own profile fields
+     *  (role, tier, whatever the member area reads). */
+    publicMetadata?: Record<string, unknown>;
+}
+/** Build the Clerk Backend API user-create request. The account is created
+ *  passwordless (the member signs in via the site's Clerk flow), so join step 3
+ *  can say the account is ready — the "create" alternative to an invitation. */
+declare function clerkUserRequest(input: ClerkUserInput): {
+    path: string;
+    body: Record<string, unknown>;
+};
+/** 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. */
+declare function createClerkUser(secretKey: string, input: ClerkUserInput, fetchImpl?: typeof fetch): Promise<ClerkResult>;
 
 /** An application row, as far as the session cares about it. */
 interface ApplicationRecord {
@@ -934,4 +971,4 @@ type ApplicationBookingPatch = {
  *  already there (never backward). */
 declare function applicationBookingUpdate(currentStatus: string, startAt: number, htmlLink?: string | null): ApplicationBookingPatch;
 
-export { 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 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, createChapterIntegration, createClerkInvitation, 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 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 };

package/dist/index.js

@@ -226,7 +226,7 @@ Warmly,
 ${name}`;
   return {
     adminNotification: {
-      subject: `New application \u2014 {{firstName}} {{lastName}}`,
+      subject: `New application: {{firstName}} {{lastName}}`,
       text: `A new application came in for ${name}.
 
 Name: {{firstName}} {{lastName}}
@@ -245,7 +245,7 @@ Your membership payment is confirmed. We'll be in touch to schedule your intro c
 Looking forward to our call at {{meetingTime}}. {{meetingLink}}${sign}`
     },
     onboardingInvite: {
-      subject: `You're in \u2014 ${name}`,
+      subject: `You're in, ${name}`,
       text: `Hi {{firstName}},
 
 Welcome to ${name}. Your member area is here: {{membersUrl}}${sign}`
@@ -470,6 +470,10 @@ function defineChapter(config) {
   const application = resolveApplication(config.application);
   const { schema, rules } = chapterDb(mode, auth);
   const services = config.services ?? ["db", "calendar", "o11y"];
+  const account = config.account ?? "invite";
+  if (account !== "invite" && account !== "create" && account !== "none") {
+    throw new Error(`defineChapter.account: must be "invite", "create", or "none" \u2014 got "${String(account)}"`);
+  }
   const chapter = {
     config,
     id: id2,
@@ -482,6 +486,7 @@ function defineChapter(config) {
     schema,
     rules,
     services,
+    account,
     groupSeed: () => mode === "chapter" ? buildGroupSeed(config) : null
   };
   if (config.url !== void 0) chapter.url = config.url;
@@ -508,7 +513,7 @@ function createChapterIntegration(chapter, options = {}) {
   }
   return {
     id: "chapter",
-    title: `Chapter \u2014 ${chapter.name}`,
+    title: `Chapter: ${chapter.name}`,
     npm: "@odla-ai/chapter",
     schema: {
       entities: { ...crmDesc.schema.entities, ...chapter.schema.entities },
@@ -759,13 +764,15 @@ async function projectApplicant(deps, applicant) {
 }
 
 // src/clerk.ts
+var heal = (status) => status === 422 ? { ok: true, status, existed: true } : { ok: false, status };
 function clerkInviteRequest(input) {
   return {
     path: "/v1/invitations",
     body: {
       email_address: input.email,
       notify: true,
-      ...input.redirectUrl ? { redirect_url: input.redirectUrl } : {}
+      ...input.redirectUrl ? { redirect_url: input.redirectUrl } : {},
+      ...input.publicMetadata ? { public_metadata: input.publicMetadata } : {}
     }
   };
 }
@@ -776,7 +783,28 @@ async function createClerkInvitation(secretKey, input, fetchImpl = fetch) {
     headers: { authorization: `Bearer ${secretKey}`, "content-type": "application/json" },
     body: JSON.stringify(body)
   });
-  return { ok: res.ok, status: res.status };
+  return res.ok ? { ok: true, status: res.status } : heal(res.status);
+}
+function clerkUserRequest(input) {
+  return {
+    path: "/v1/users",
+    body: {
+      email_address: [input.email],
+      skip_password_requirement: true,
+      ...input.firstName ? { first_name: input.firstName } : {},
+      ...input.lastName ? { last_name: input.lastName } : {},
+      ...input.publicMetadata ? { public_metadata: input.publicMetadata } : {}
+    }
+  };
+}
+async function createClerkUser(secretKey, input, fetchImpl = fetch) {
+  const { path, body } = clerkUserRequest(input);
+  const res = await fetchImpl(`https://api.clerk.com${path}`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${secretKey}`, "content-type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  return res.ok ? { ok: true, status: res.status } : heal(res.status);
 }
 
 // src/session.ts
@@ -980,8 +1008,10 @@ export {
   canceledPatch,
   chapterDb,
   clerkInviteRequest,
+  clerkUserRequest,
   createChapterIntegration,
   createClerkInvitation,
+  createClerkUser,
   defaultCrm,
   defineChapter,
   emailGroupFrom,