@odla-ai/chapter 0.13.0 → 0.14.0

package/dist/index.d.cts

@@ -859,6 +859,74 @@ declare function clerkListUsers(secretKey: string, fetchImpl?: typeof fetch): Pr
  *  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>;
 
+/** Which auth mode a secret is required for: `"client"` (publishable key only) or
+ *  `"full"` (server-side profile/role reads + writes, needing the vault secret). */
+type SecretMode = "client" | "full";
+/** A configuration value the capability needs (e.g. the publishable key). */
+interface IntegrationSetting {
+    key: string;
+    description: string;
+    /** Safe to ship to the browser? (publishable keys are; secrets are not). */
+    public: boolean;
+    /** Expected value shape, e.g. a "pk_" prefix. */
+    pattern?: string;
+    /** Stored per environment (dev/prod)? */
+    perEnv: boolean;
+    /** Where the value is stored and read from. */
+    source: string;
+}
+/** A secret the capability needs, held in the tenant vault. */
+interface IntegrationSecret {
+    key: string;
+    description: string;
+    pattern?: string;
+    /** Auth mode that requires this secret ("full" pulls user profiles). */
+    mode: SecretMode;
+    /** Stored in the tenant vault (never in graph rows or wrangler vars)? */
+    vault: boolean;
+}
+/** One data-sync contract. A capability may declare several (e.g. an inbound
+ *  webhook mirror AND an outbound write), so {@link IntegrationDescriptor.syncs}
+ *  is a list. The mechanism is declared, not reimplemented here. */
+interface IntegrationSync {
+    engine: string;
+    direction: "provider->odla" | "odla->provider" | "bidirectional";
+    entity: string;
+    fields: string[];
+    webhook?: string;
+    onDelete?: string;
+}
+/** The provisioning split: human, CLI, and doctor-assertable steps. */
+interface IntegrationProvision {
+    /** Steps a human performs (out-of-band, e.g. in the Clerk dashboard). */
+    human: string[];
+    /** Steps the odla CLI automates. */
+    cli: string[];
+    /** Checks `odla doctor` should assert. */
+    doctor: string[];
+}
+/** Documentation-as-data for a provider capability, consumed by the odla CLI,
+ *  `odla doctor`, and the docs. */
+interface IntegrationDescriptor {
+    id: string;
+    title: string;
+    npm: string;
+    settings: IntegrationSetting[];
+    secrets: IntegrationSecret[];
+    /** Every data-sync contract the capability declares, each with its direction. */
+    syncs: IntegrationSync[];
+    provision: IntegrationProvision;
+}
+/**
+ * The concrete {@link IntegrationDescriptor} for the Clerk capability. Declares
+ * the one public `setting` (the `pk_*` publishable key, served to the SPA), the
+ * `secrets` auth mode `"full"` needs in the tenant vault, BOTH sync directions —
+ * the inbound `$users` webhook mirror (`provider->odla`) and the outbound
+ * role/profile write via `clerk_secret_key` (`odla->provider`, chapter's
+ * `clerk.ts`) — and the `provision` split. Data only; it performs none of it.
+ */
+declare const clerkIntegration: IntegrationDescriptor;
+
 /** An application row, as far as the session cares about it. */
 interface ApplicationRecord {
     id: string;
@@ -1097,4 +1165,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 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 };
+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 IntegrationDescriptor, type IntegrationProvision, type IntegrationSecret, type IntegrationSetting, type IntegrationSync, 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 SecretMode, 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, clerkIntegration, 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

@@ -859,6 +859,74 @@ declare function clerkListUsers(secretKey: string, fetchImpl?: typeof fetch): Pr
  *  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>;
 
+/** Which auth mode a secret is required for: `"client"` (publishable key only) or
+ *  `"full"` (server-side profile/role reads + writes, needing the vault secret). */
+type SecretMode = "client" | "full";
+/** A configuration value the capability needs (e.g. the publishable key). */
+interface IntegrationSetting {
+    key: string;
+    description: string;
+    /** Safe to ship to the browser? (publishable keys are; secrets are not). */
+    public: boolean;
+    /** Expected value shape, e.g. a "pk_" prefix. */
+    pattern?: string;
+    /** Stored per environment (dev/prod)? */
+    perEnv: boolean;
+    /** Where the value is stored and read from. */
+    source: string;
+}
+/** A secret the capability needs, held in the tenant vault. */
+interface IntegrationSecret {
+    key: string;
+    description: string;
+    pattern?: string;
+    /** Auth mode that requires this secret ("full" pulls user profiles). */
+    mode: SecretMode;
+    /** Stored in the tenant vault (never in graph rows or wrangler vars)? */
+    vault: boolean;
+}
+/** One data-sync contract. A capability may declare several (e.g. an inbound
+ *  webhook mirror AND an outbound write), so {@link IntegrationDescriptor.syncs}
+ *  is a list. The mechanism is declared, not reimplemented here. */
+interface IntegrationSync {
+    engine: string;
+    direction: "provider->odla" | "odla->provider" | "bidirectional";
+    entity: string;
+    fields: string[];
+    webhook?: string;
+    onDelete?: string;
+}
+/** The provisioning split: human, CLI, and doctor-assertable steps. */
+interface IntegrationProvision {
+    /** Steps a human performs (out-of-band, e.g. in the Clerk dashboard). */
+    human: string[];
+    /** Steps the odla CLI automates. */
+    cli: string[];
+    /** Checks `odla doctor` should assert. */
+    doctor: string[];
+}
+/** Documentation-as-data for a provider capability, consumed by the odla CLI,
+ *  `odla doctor`, and the docs. */
+interface IntegrationDescriptor {
+    id: string;
+    title: string;
+    npm: string;
+    settings: IntegrationSetting[];
+    secrets: IntegrationSecret[];
+    /** Every data-sync contract the capability declares, each with its direction. */
+    syncs: IntegrationSync[];
+    provision: IntegrationProvision;
+}
+/**
+ * The concrete {@link IntegrationDescriptor} for the Clerk capability. Declares
+ * the one public `setting` (the `pk_*` publishable key, served to the SPA), the
+ * `secrets` auth mode `"full"` needs in the tenant vault, BOTH sync directions —
+ * the inbound `$users` webhook mirror (`provider->odla`) and the outbound
+ * role/profile write via `clerk_secret_key` (`odla->provider`, chapter's
+ * `clerk.ts`) — and the `provision` split. Data only; it performs none of it.
+ */
+declare const clerkIntegration: IntegrationDescriptor;
+
 /** An application row, as far as the session cares about it. */
 interface ApplicationRecord {
     id: string;
@@ -1097,4 +1165,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 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 };
+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 IntegrationDescriptor, type IntegrationProvision, type IntegrationSecret, type IntegrationSetting, type IntegrationSync, 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 SecretMode, 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, clerkIntegration, 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

@@ -930,6 +930,72 @@ async function clerkSetRole(secretKey, id2, role, fetchImpl = fetch) {
   return res.ok;
 }
 
+// src/clerk-integration.ts
+var clerkIntegration = {
+  id: "clerk",
+  title: "Clerk end-user auth",
+  npm: "@odla-ai/chapter",
+  settings: [
+    {
+      key: "publishableKey",
+      description: "Clerk publishable key (pk_*). Public by design; served to the SPA (loads clerk-js from Clerk's CDN via @odla-ai/auth-clerk).",
+      public: true,
+      pattern: "pk_",
+      perEnv: true,
+      source: "apps-registry auth[env].publishableKey (from odla.config.mjs auth.clerk.<env>)"
+    }
+  ],
+  secrets: [
+    {
+      key: "CLERK_WEBHOOK_SECRET",
+      description: "Svix signing secret for Clerk user webhooks \u2014 verifies $users sync events.",
+      pattern: "whsec_",
+      mode: "full",
+      vault: true
+    },
+    {
+      key: "clerk_secret_key",
+      description: "Clerk backend key (sk_*) \u2014 powers the odla->Clerk writes (account create, role + profile via public_metadata) and lets odla-db resolve user email/name via the Clerk API.",
+      pattern: "sk_",
+      mode: "full",
+      vault: true
+    }
+  ],
+  syncs: [
+    {
+      engine: "@odla-ai/db $users (Clerk webhook -> tenant graph)",
+      direction: "provider->odla",
+      entity: "$users",
+      // Matches the webhook mapper: the mirror carries id + primary email + name + avatar.
+      fields: ["id", "email", "name", "imageUrl"],
+      webhook: "whsec_ (svix-signed)",
+      onDelete: "tombstone (never row-delete)"
+    },
+    {
+      engine: "@odla-ai/chapter clerk.ts (Clerk Backend API via vault clerk_secret_key)",
+      direction: "odla->provider",
+      entity: "clerk user",
+      // Separate merge-PATCHes so a role write never clobbers a profile write.
+      fields: ["public_metadata.role", "public_metadata.profile"],
+      onDelete: "n/a (writes only)"
+    }
+  ],
+  provision: {
+    human: [
+      "Run `npx clerk auth login` \u2014 the one interactive step; the agent then creates + configures the Clerk app with the Clerk CLI (no pk_ to hand-paste).",
+      'For auth mode "full": create the Clerk user-sync webhook and store its whsec_, plus the sk_ as clerk_secret_key, in the tenant vault (Studio, write-only).'
+    ],
+    cli: [
+      "Clerk CLI (`npx clerk apps create/link/config patch`) creates + configures the instance and pulls the pk_.",
+      "odla `provision` records it: setAuth(env, publishableKey) -> apps-registry (issuer/JWKS derived from the key)."
+    ],
+    doctor: [
+      "registry auth[env] present when the app mounts <SignIn>?",
+      'auth mode "full" => whsec_ and clerk_secret_key present in the tenant vault?'
+    ]
+  }
+};
+
 // src/session.ts
 function applicationSummary(app) {
   return {
@@ -1149,6 +1215,7 @@ export {
   clampArray,
   clerkGetUser,
   clerkGetUserByEmail,
+  clerkIntegration,
   clerkInviteRequest,
   clerkListUsers,
   clerkSetRole,