@odla-ai/chapter 0.5.0 → 0.8.0

package/dist/worker/index.d.cts

@@ -1,4 +1,5 @@
 import { CrmConfig, Crm } from '@odla-ai/crm';
+import { initAdmin } from '@odla-ai/db';
 
 /** Which feature profile a site runs. `chapter` is the full public member site
  * (join, Stripe membership, booking, member area, admin, CRM); `hub` is
@@ -188,7 +189,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;
@@ -208,6 +216,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;
 }
@@ -246,15 +256,68 @@ interface ChapterWorkerOptions {
     chapter: Chapter;
     /** CRM mount point. Default "/api/crm". */
     crmBasePath?: string;
+    /** Host routes, tried BEFORE the built-ins — so a wrapping site can add its own
+     *  routes (or override/alias a built-in path) and reuse chapter's auth via the
+     *  shared {@link WorkerContext}, instead of re-verifying JWTs itself. */
+    routes?: Route[];
 }
+/** The registry public-config a site reads to boot Clerk sign-in. */
+type PublicConfig = {
+    env?: string;
+    clerkPublishableKey?: string | null;
+    issuer?: string | null;
+};
+/** The odla-db admin client type. */
+type Db = ReturnType<typeof initAdmin>;
+/** A verified session: the Clerk `sub`, optional email, and the raw JWT payload
+ *  (so the role claim can be read for auth source "claim"). */
+interface Verified {
+    userId: string;
+    email?: string;
+    payload: Record<string, unknown>;
+}
+/**
+ * Build the per-site Worker context: env-independent helpers closing over the
+ * public-config and JWKS caches, plus the source-aware auth gate (JWT claim or
+ * the odla-db `admins` allowlist). Constructed once per `chapterWorker` and
+ * shared by every route module.
+ */
+declare function createWorkerContext(options: ChapterWorkerOptions): {
+    chapter: Chapter;
+    auth: ResolvedAuth;
+    crmBase: string;
+    getPublicConfig: (env: ChapterEnv) => Promise<PublicConfig>;
+    verifyUser: (req: Request, env: ChapterEnv) => Promise<Verified | null>;
+    makeDb: (env: ChapterEnv) => Db;
+    isAdminEmail: (db: Db, email: string | undefined) => Promise<boolean>;
+    isSuperAdminEmail: (db: Db, email: string | undefined) => Promise<boolean>;
+    roleFor: (db: Db, u: Verified) => Promise<string>;
+    isAdmin: (db: Db, u: Verified) => Promise<boolean>;
+    crmSender: (env: ChapterEnv) => {
+        send(payload: EmailPayload): Promise<{
+            messageId: string;
+        }>;
+    } | undefined;
+};
+/** The value returned by {@link createWorkerContext}, threaded to every route. */
+type WorkerContext = ReturnType<typeof createWorkerContext>;
+/** A worker route handler: owns the request (returns a Response) or falls through
+ *  (returns null). Host routes passed to `chapterWorker` compose against the same
+ *  {@link WorkerContext} the built-ins receive. */
+type Route = (req: Request, url: URL, env: ChapterEnv, ctx: WorkerContext) => Promise<Response | null>;
 
 /**
  * Build the Cloudflare `ExportedHandler` for a chapter/hub site: Clerk-JWT
- * verification, the odla-db admins-allowlist gate, the mounted @odla-ai/crm
- * routes, the hub→chapter network projection, and the static-asset fallback. In
- * hub mode it serves /api/config, /api/me, /api/crm/*, /api/network/shared;
- * chapter mode adds the public member surface (join/apply; Stripe + booking
- * land in the member-experience release).
+ * verification, the source-aware admin gate, the mounted @odla-ai/crm routes, the
+ * hub→chapter network projection, and the static-asset fallback. Hub mode serves
+ * /api/health, /api/config, /api/me, /api/crm/*, /api/network/shared; chapter mode
+ * adds the public member surface (join/apply/pay/book) and the admin surface
+ * (/api/admin/*).
+ *
+ * A wrapping site adds its own routes via `options.routes` — each receives the
+ * same {@link WorkerContext} the built-ins get (so it reuses chapter's JWT
+ * verify, db client, and role resolution instead of duplicating them), and runs
+ * BEFORE the built-ins so it can override or alias a path.
  *
  * Observability is a host concern, not a chapter dependency. To trace, wrap the
  * result in your worker entry — `export default withObservability(chapterWorker(
@@ -265,4 +328,4 @@ declare function chapterWorker(options: ChapterWorkerOptions): {
     fetch(req: Request, env: ChapterEnv): Promise<Response>;
 };
 
-export { type ChapterEnv, type ChapterWorkerOptions, chapterWorker };
+export { type ChapterEnv, type ChapterWorkerOptions, type Route, type WorkerContext, chapterWorker, createWorkerContext };

package/dist/worker/index.d.ts

@@ -1,4 +1,5 @@
 import { CrmConfig, Crm } from '@odla-ai/crm';
+import { initAdmin } from '@odla-ai/db';
 
 /** Which feature profile a site runs. `chapter` is the full public member site
  * (join, Stripe membership, booking, member area, admin, CRM); `hub` is
@@ -188,7 +189,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;
@@ -208,6 +216,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;
 }
@@ -246,15 +256,68 @@ interface ChapterWorkerOptions {
     chapter: Chapter;
     /** CRM mount point. Default "/api/crm". */
     crmBasePath?: string;
+    /** Host routes, tried BEFORE the built-ins — so a wrapping site can add its own
+     *  routes (or override/alias a built-in path) and reuse chapter's auth via the
+     *  shared {@link WorkerContext}, instead of re-verifying JWTs itself. */
+    routes?: Route[];
 }
+/** The registry public-config a site reads to boot Clerk sign-in. */
+type PublicConfig = {
+    env?: string;
+    clerkPublishableKey?: string | null;
+    issuer?: string | null;
+};
+/** The odla-db admin client type. */
+type Db = ReturnType<typeof initAdmin>;
+/** A verified session: the Clerk `sub`, optional email, and the raw JWT payload
+ *  (so the role claim can be read for auth source "claim"). */
+interface Verified {
+    userId: string;
+    email?: string;
+    payload: Record<string, unknown>;
+}
+/**
+ * Build the per-site Worker context: env-independent helpers closing over the
+ * public-config and JWKS caches, plus the source-aware auth gate (JWT claim or
+ * the odla-db `admins` allowlist). Constructed once per `chapterWorker` and
+ * shared by every route module.
+ */
+declare function createWorkerContext(options: ChapterWorkerOptions): {
+    chapter: Chapter;
+    auth: ResolvedAuth;
+    crmBase: string;
+    getPublicConfig: (env: ChapterEnv) => Promise<PublicConfig>;
+    verifyUser: (req: Request, env: ChapterEnv) => Promise<Verified | null>;
+    makeDb: (env: ChapterEnv) => Db;
+    isAdminEmail: (db: Db, email: string | undefined) => Promise<boolean>;
+    isSuperAdminEmail: (db: Db, email: string | undefined) => Promise<boolean>;
+    roleFor: (db: Db, u: Verified) => Promise<string>;
+    isAdmin: (db: Db, u: Verified) => Promise<boolean>;
+    crmSender: (env: ChapterEnv) => {
+        send(payload: EmailPayload): Promise<{
+            messageId: string;
+        }>;
+    } | undefined;
+};
+/** The value returned by {@link createWorkerContext}, threaded to every route. */
+type WorkerContext = ReturnType<typeof createWorkerContext>;
+/** A worker route handler: owns the request (returns a Response) or falls through
+ *  (returns null). Host routes passed to `chapterWorker` compose against the same
+ *  {@link WorkerContext} the built-ins receive. */
+type Route = (req: Request, url: URL, env: ChapterEnv, ctx: WorkerContext) => Promise<Response | null>;
 
 /**
  * Build the Cloudflare `ExportedHandler` for a chapter/hub site: Clerk-JWT
- * verification, the odla-db admins-allowlist gate, the mounted @odla-ai/crm
- * routes, the hub→chapter network projection, and the static-asset fallback. In
- * hub mode it serves /api/config, /api/me, /api/crm/*, /api/network/shared;
- * chapter mode adds the public member surface (join/apply; Stripe + booking
- * land in the member-experience release).
+ * verification, the source-aware admin gate, the mounted @odla-ai/crm routes, the
+ * hub→chapter network projection, and the static-asset fallback. Hub mode serves
+ * /api/health, /api/config, /api/me, /api/crm/*, /api/network/shared; chapter mode
+ * adds the public member surface (join/apply/pay/book) and the admin surface
+ * (/api/admin/*).
+ *
+ * A wrapping site adds its own routes via `options.routes` — each receives the
+ * same {@link WorkerContext} the built-ins get (so it reuses chapter's JWT
+ * verify, db client, and role resolution instead of duplicating them), and runs
+ * BEFORE the built-ins so it can override or alias a path.
  *
  * Observability is a host concern, not a chapter dependency. To trace, wrap the
  * result in your worker entry — `export default withObservability(chapterWorker(
@@ -265,4 +328,4 @@ declare function chapterWorker(options: ChapterWorkerOptions): {
     fetch(req: Request, env: ChapterEnv): Promise<Response>;
 };
 
-export { type ChapterEnv, type ChapterWorkerOptions, chapterWorker };
+export { type ChapterEnv, type ChapterWorkerOptions, type Route, type WorkerContext, chapterWorker, createWorkerContext };