@odla-ai/chapter 0.0.2 → 0.3.0

package/dist/index.d.cts

@@ -4,6 +4,28 @@ import { CrmConfig, Crm } from '@odla-ai/crm';
  * (join, Stripe membership, booking, member area, admin, CRM); `hub` is
  * admin-only and CRM-focused (a directory/registry over the same CRM). */
 type ChapterMode = "chapter" | "hub";
+/** One odla-db transaction op — the wire shape both the real admin client and a
+ *  test double (`FakeDb`) accept. Built as a plain object, never via a `tx` proxy. */
+interface DbOp {
+    t: "update" | "merge" | "retract" | "delete";
+    ns: string;
+    id: string;
+    attrs?: Record<string, unknown>;
+}
+/** The structural view of the odla-db admin client the worker builds and the
+ *  member routes consume — so route logic is testable against an in-memory fake. */
+interface ChapterDb {
+    query(q: Record<string, unknown>): Promise<Record<string, Array<Record<string, unknown>>>>;
+    transact(ops: DbOp[], opts?: {
+        mutationId?: string;
+    }): Promise<{
+        txId: number;
+        duplicate: boolean;
+    }>;
+    secrets: {
+        get(name: string): Promise<string>;
+    };
+}
 /** The scalar kinds an odla-db attribute can hold. */
 type AttrType = "string" | "number" | "boolean" | "json";
 /** One odla-db attribute: its type and index/uniqueness/optionality flags. */
@@ -93,6 +115,75 @@ interface ChapterScheduling {
     windowDays?: number;
     summaryTemplate?: string;
 }
+/** How a signed-in user's role is determined.
+ *
+ * - `"claim"` reads a role ladder from a JWT claim (Silver & Salt's model:
+ *   `provisional → member → admin`). Admin is the last (highest) rung; the
+ *   read-only `superAdmins` tier sits above it.
+ * - `"table"` gates on the deny-all `admins` allowlist (Built Not Found's model):
+ *   a binary "email is an admin or isn't", set only in odla Studio.
+ *
+ * Defaults: `"claim"` in `chapter` mode, `"table"` in `hub` mode. */
+interface ChapterAuth {
+    source?: "claim" | "table";
+    /** JWT claim holding the role, for `source: "claim"`. Default `"role"`. */
+    claim?: string;
+    /** Role ladder low→high, for `source: "claim"`. The last entry is admin.
+     *  Default `["provisional", "member", "admin"]`. */
+    ladder?: readonly string[];
+    /** Provision the read-only `superAdmins` tier table — the only tier that may
+     *  create/modify admins, and (like every namespace) deny-all + written only in
+     *  odla Studio. Default: `true` for `"claim"`, `false` for `"table"`. */
+    superAdmins?: boolean;
+}
+/** The fully-resolved auth policy (defaults applied) carried on the {@link Chapter}. */
+interface ResolvedAuth {
+    source: "claim" | "table";
+    claim: string;
+    ladder: readonly string[];
+    /** The highest ladder rung (last entry) — the "admin" gate. */
+    adminRole: string;
+    superAdmins: boolean;
+}
+/** The application status pipeline. Which statuses exist, and the subsets a site
+ *  allows a call to be booked from / an application approved from. Defaults to
+ *  Silver & Salt's pipeline. Status never moves backwards (package-enforced). */
+interface ChapterPipeline {
+    stages?: readonly string[];
+    bookableFrom?: readonly string[];
+    approvableFrom?: readonly string[];
+    /** The status a new application starts at. Default: the first stage. */
+    initial?: string;
+}
+/** The fully-resolved pipeline (defaults applied) carried on the {@link Chapter}. */
+interface ResolvedPipeline {
+    stages: readonly string[];
+    bookableFrom: readonly string[];
+    approvableFrom: readonly string[];
+    initial: string;
+}
+/** The application (join form) validation surface — which string fields are
+ *  required vs accepted, their max lengths, and the request body cap. Drives
+ *  submit validation + the CRM slot projection; defaults to Silver & Salt's form.
+ *  The `applications` schema attrs stay fixed (byte-equal to S&S); this is
+ *  validation config, not schema generation. */
+interface ChapterApplication {
+    required?: readonly string[];
+    optional?: readonly string[];
+    /** Per-field character cap. Fields not listed use `defaultMaxLen`. */
+    maxLen?: Record<string, number>;
+    defaultMaxLen?: number;
+    /** Max JSON request body in bytes. Default 32768. */
+    bodyCap?: number;
+}
+/** The fully-resolved application config carried on the {@link Chapter}. */
+interface ResolvedApplication {
+    required: readonly string[];
+    optional: readonly string[];
+    maxLen: Record<string, number>;
+    defaultMaxLen: number;
+    bodyCap: number;
+}
 /** The `defineChapter()` config a site fills in. */
 interface ChapterConfig {
     /** Slug: app id, tenant, group id, worker name. `[a-z0-9-]`. */
@@ -111,6 +202,12 @@ interface ChapterConfig {
     /** `notificationEmail` required in `chapter` mode. */
     emails?: ChapterEmails;
     scheduling?: ChapterScheduling;
+    /** Application status pipeline (stages + bookable/approvable subsets). Defaults to S&S's. */
+    pipeline?: ChapterPipeline;
+    /** Join-form validation (required/optional fields, max lengths, body cap). */
+    application?: ChapterApplication;
+    /** Role source + ladder + super-admin tier. Defaults by mode (see {@link ChapterAuth}). */
+    auth?: ChapterAuth;
     /** odla services (db implied). Default `["db","calendar","o11y"]`. */
     services?: readonly string[];
 }
@@ -123,6 +220,12 @@ interface Chapter {
     mode: ChapterMode;
     /** Resolved CRM engine (from `defineCrm`). */
     crm: Crm;
+    /** Resolved auth policy (source, claim, ladder, super-admin tier). */
+    auth: ResolvedAuth;
+    /** Resolved application status pipeline (stages + bookable/approvable subsets). */
+    pipeline: ResolvedPipeline;
+    /** Resolved join-form validation config. */
+    application: ResolvedApplication;
     /** The chapter's own odla-db namespaces (mode-dependent; excludes `crm_*`). */
     schema: DbSchema;
     rules: DbRules;
@@ -179,10 +282,15 @@ interface ChapterIntegrationDescriptor {
  */
 declare function createChapterIntegration(chapter: Chapter, options?: ChapterIntegrationOptions): ChapterIntegrationDescriptor;
 
-/** The chapter's own schema + deny-all rules for a mode. `hub` needs only the
- * `admins` allowlist (its records live in `crm_*`); `chapter` adds the
- * operational membership tables. */
-declare function chapterDb(mode: ChapterMode): {
+/** The chapter's own schema + deny-all rules for a mode + auth policy.
+ *
+ * Operational tables (`applications`/`groups`/`meetings`/`emailLog`) are added in
+ * `chapter` mode only. The auth tables follow {@link ResolvedAuth}: `source:
+ * "table"` adds the `admins` allowlist (hub/BNF); `superAdmins` adds the
+ * read-only super-admin tier (default on for the `"claim"` ladder). A `"claim"`
+ * chapter therefore emits exactly Silver & Salt's namespace set — `applications`,
+ * `groups`, `meetings`, `emailLog`, `superAdmins` — with no `admins` table. */
+declare function chapterDb(mode: ChapterMode, auth: ResolvedAuth): {
     schema: DbSchema;
     rules: DbRules;
 };
@@ -195,4 +303,247 @@ declare function defaultCrm(mode: ChapterMode): CrmConfig;
  * empty copy / defaults, so a minimal config still provisions cleanly. */
 declare function buildGroupSeed(config: ChapterConfig): Record<string, unknown>;
 
-export { type Attr, type AttrType, type Chapter, type ChapterBrand, type ChapterConfig, type ChapterEmails, type ChapterIntegrationDescriptor, type ChapterIntegrationOptions, type ChapterMode, type ChapterPolicy, type ChapterPrices, type ChapterScheduling, type DbRules, type DbSchema, type EmailTemplate, type Entity, type Rule, buildGroupSeed, chapterDb, createChapterIntegration, defaultCrm, defineChapter };
+/**
+ * Apply defaults + validate the auth config into a {@link ResolvedAuth}. Defaults
+ * by mode: `chapter` → the `provisional/member/admin` claim ladder with the
+ * `superAdmins` tier (Silver & Salt); `hub` → the `admins` allowlist table, no
+ * super tier (Built Not Found). Throws at import on a bad policy.
+ */
+declare function resolveAuth(mode: ChapterMode, auth: ChapterAuth | undefined): ResolvedAuth;
+/** The role from a verified JWT payload, per the resolved policy. An unknown or
+ *  missing claim falls back to the lowest ladder rung (fail safe, never admin). */
+declare function roleFromClaim(payload: Record<string, unknown>, auth: ResolvedAuth): string;
+/** Does a role meet the admin bar (the highest ladder rung)? */
+declare function isAdminRole(role: string, auth: ResolvedAuth): boolean;
+/** Inputs to the role-change guard — resolved by the caller (route) from the
+ *  identity provider + the read-only `superAdmins` table. */
+interface RoleChangeContext {
+    actorId: string;
+    actorIsSuper: boolean;
+    targetId: string;
+    targetCurrentRole: string;
+    targetIsSuper: boolean;
+    newRole: string;
+    auth: ResolvedAuth;
+}
+/** The result of {@link canChangeRole}: allow, or deny with the HTTP status +
+ *  message the route should return. */
+type GuardResult = {
+    ok: true;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+};
+/**
+ * The privilege-escalation guard — package-enforced so every site gets it and
+ * none re-derives it. Denies: an out-of-ladder role; changing your own role;
+ * touching a super-admin unless you are one; and (when a `superAdmins` tier
+ * exists) creating or altering an admin unless you are a super-admin. Note the
+ * super-admin tier itself is never writable here — it lives in the read-only
+ * `superAdmins` table, set only in odla Studio.
+ */
+declare function canChangeRole(ctx: RoleChangeContext): GuardResult;
+/** Structural view of odla-db's tenant-vault read, so chapter takes no runtime
+ *  dependency on @odla-ai/db. The worker's admin client satisfies this. */
+interface SecretStore {
+    secrets: {
+        get(name: string): Promise<string>;
+    };
+}
+/**
+ * Read a tenant-vault secret by name; `undefined` when it is absent or the vault
+ * errors, so callers degrade gracefully (e.g. `paymentsReady: false`) rather than
+ * throwing. Never logs the value.
+ */
+declare function getVaultSecret(db: SecretStore, name: string): Promise<string | undefined>;
+
+/** One owner-editable template row on the group. `enabled` absent = enabled. */
+interface EmailTemplateRow {
+    subject: string;
+    text: string;
+    enabled?: boolean;
+}
+/** The `groups`-row fields the email pipeline reads. */
+interface EmailGroup {
+    id: string;
+    name: string;
+    replyTo: string;
+    /** Non-prod debug inbox: all mail redirects here outside prod (E2). */
+    debugEmail?: string;
+    refundPolicyText?: string;
+    commitmentText?: string;
+    normsText?: string;
+    emailTemplates: Record<string, EmailTemplateRow>;
+}
+/** `{{placeholder}}` substitution; unknown placeholders render empty. */
+declare function render(template: string, vars: Record<string, string>): string;
+/**
+ * Re-render a template's body for history/preview (E4): the CRM comms history
+ * reads back emails whose body predates `emailLog.body` by rendering the current
+ * template with the recipient's vars. Same substitution + group vars as the send
+ * path. `null` for an unknown template. Reflects the copy as it reads today, not
+ * necessarily the exact bytes originally sent (only `emailLog.body` is byte-exact).
+ */
+declare function renderTemplateBody(group: EmailGroup, template: string, vars: Record<string, string>): string | null;
+/**
+ * E1 (exactly-once): given the prior `emailLog` rows for a `dedupeKey`, has the
+ * mail already been delivered? A prior row with **no error** means yes — the
+ * caller short-circuits the resend. Failure rows (which carry an `error` and are
+ * written without the dedupe mutationId) do not count, so a retry after a failure
+ * can still succeed.
+ */
+declare function isAlreadySent(priorRows: ReadonlyArray<{
+    error?: unknown;
+}>): boolean;
+/** The pure delivery decision produced by {@link planDelivery}. */
+type DeliveryDecision = {
+    deliver: false;
+    reason: "template-missing" | "disabled";
+} | {
+    deliver: true;
+    /** Which transport to use — `log-only` records the send but delivers nothing. */
+    transport: "cloudflare" | "log-only";
+    to: string;
+    subject: string;
+    text: string;
+    /** True when redirected to the non-prod debug inbox. */
+    redirected: boolean;
+};
+/**
+ * The pure delivery decision (E2 fail-safe + E3 enabled). Given the env, group,
+ * template, recipient, and whether a real Cloudflare transport is wired:
+ * - missing template → not delivered (`template-missing`);
+ * - disabled template and not forced → not delivered (`disabled`);
+ * - **non-prod with a debug inbox** → REDIRECT to it, `"[dev] "` subject prefix,
+ *   a dev-redirect note in the body, so test applicants never receive real mail;
+ * - **non-prod with NO debug inbox** → force `log-only` (deliver nothing) — the
+ *   fail-safe that protects every site's test data;
+ * - prod → deliver via the real transport (`cloudflare` if wired, else `log-only`).
+ */
+declare function planDelivery(input: {
+    envName: string;
+    group: EmailGroup;
+    template: string;
+    to: string;
+    vars: Record<string, string>;
+    /** Whether a Cloudflare Email Service transport (binding + verified from) is wired. */
+    cloudflareReady: boolean;
+    /** The admin test route may send a disabled template. */
+    force?: boolean;
+}): DeliveryDecision;
+
+/**
+ * Apply defaults + validate the pipeline config. With no config, the full Silver
+ * & Salt pipeline. With `stages` given but the subsets omitted, the subsets
+ * default to empty (a site opts in to bookable/approvable states explicitly).
+ * Throws at import on a bad pipeline (empty/duplicate stages, an initial or a
+ * subset entry not on the ladder).
+ */
+declare function resolvePipeline(p: ChapterPipeline | undefined): ResolvedPipeline;
+/** The ordinal of a status in the ladder, or -1 if unknown. */
+declare function stageIndex(status: string, p: ResolvedPipeline): number;
+/**
+ * The status-never-moves-backwards invariant: a transition is allowed only when
+ * both statuses are on the ladder and `to` is at or ahead of `from`. The worker
+ * calls this before every status write; a violation is a 409, never a silent
+ * downgrade.
+ */
+declare function canTransition(from: string, to: string, p: ResolvedPipeline): boolean;
+/** May an intro call be booked from this status? */
+declare function canBook(status: string, p: ResolvedPipeline): boolean;
+/** May an application be approved (→ member) from this status? */
+declare function canApprove(status: string, p: ResolvedPipeline): boolean;
+
+/**
+ * Verify a Stripe webhook signature (C3): HMAC-SHA256 over `` `${t}.${payload}` ``
+ * with the endpoint signing secret, a replay window (default 5 minutes), and a
+ * constant-time compare. Package-enforced — never left to a site. Returns `false`
+ * (never throws) on a malformed header, a non-numeric or stale timestamp, or a
+ * signature mismatch. `now`/`toleranceSec` are injectable for tests.
+ */
+declare function verifyStripeSignature(payload: string, header: string, secret: string, opts?: {
+    now?: number;
+    toleranceSec?: number;
+}): Promise<boolean>;
+
+/** Apply defaults + validate the application config. Throws at import on bad shape. */
+declare function resolveApplication(a: ChapterApplication | undefined): ResolvedApplication;
+/** A validated submission, or a 400-worthy validation error the route returns. */
+type SubmitResult = {
+    ok: true;
+    id: string;
+    duplicate: boolean;
+    status: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Submit a membership application (B2 + B3). Validates the configured required
+ * fields + max lengths, writes the `applications` row at the pipeline's initial
+ * status, and — when the client supplies a `submissionId` — stamps it as the
+ * transaction's mutationId (`join:${submissionId}`) so a double-tap can never
+ * create two applications (the second returns `duplicate: true`). Idempotency is
+ * package-enforced. `now`/`newId` are injected (deterministic in tests).
+ */
+declare function submitApplication(db: ChapterDb, chapter: Chapter, fields: Record<string, unknown>, opts: {
+    submissionId?: string;
+    groupId?: string;
+    now: number;
+    newId: () => string;
+}): Promise<SubmitResult>;
+/** The `groups`-row fields the join config exposes. */
+interface JoinConfigGroup {
+    id: string;
+    name: string;
+    standardPriceCents?: number;
+    foundingDiscountCents?: number;
+    disclaimerText?: string;
+    refundPolicyText?: string;
+    trustCopy?: string;
+    commitmentText?: string;
+    normsText?: string;
+}
+/**
+ * The public join config (B1) a site's join page reads: copy + prices from the
+ * group row plus `paymentsReady`. When payments aren't wired the join flow drops
+ * the payment step (C2) — the worker computes `paymentsReady` from the group's
+ * Stripe keys + vault secret. Pure.
+ */
+declare function joinConfig(group: JoinConfigGroup, paymentsReady: boolean): Record<string, unknown>;
+
+/** The contact data the hub shares for a prospect. `hubRecordId` is the stable
+ *  idempotency key (the hub's crm_record id). */
+interface SharedPerson {
+    email: string;
+    name?: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+    linkedin?: string;
+    hubRecordId: string;
+}
+/** Map a shared prospect to a crm `person` input (only the fields the default
+ *  person type accepts). Name falls back to first+last, then the email. */
+declare function sharedPersonInput(person: SharedPerson): Record<string, unknown>;
+/** Deps for the projection — the resolved CRM engine, the structural db, and
+ *  injected clock/id (deterministic in tests). */
+interface ProjectionDeps {
+    crm: Crm;
+    db: ChapterDb;
+    now: () => number;
+    newId: () => string;
+}
+/**
+ * Upsert a hub-shared prospect into this chapter's `crm_record` (push
+ * projection). Resolves an existing person by lowercased `primaryEmail` and
+ * updates it, else creates one with a `share:${hubRecordId}` mutationId. Returns
+ * the chapter-side record id. Callers wrap this in `.catch` so a projection
+ * failure never fails the hub's share request.
+ */
+declare function projectSharedRecord(deps: ProjectionDeps, person: SharedPerson): Promise<{
+    recordId: string;
+}>;
+
+export { 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 DbOp, type DbRules, type DbSchema, type DeliveryDecision, type EmailGroup, type EmailTemplate, type EmailTemplateRow, type Entity, type GuardResult, type JoinConfigGroup, type ProjectionDeps, type ResolvedApplication, type ResolvedAuth, type ResolvedPipeline, type RoleChangeContext, type Rule, type SecretStore, type SharedPerson, type SubmitResult, buildGroupSeed, canApprove, canBook, canChangeRole, canTransition, chapterDb, createChapterIntegration, defaultCrm, defineChapter, getVaultSecret, isAdminRole, isAlreadySent, joinConfig, planDelivery, projectSharedRecord, render, renderTemplateBody, resolveApplication, resolveAuth, resolvePipeline, roleFromClaim, sharedPersonInput, stageIndex, submitApplication, verifyStripeSignature };