@odla-ai/chapter 0.15.0 → 0.16.0

package/dist/worker/index.d.cts

@@ -221,18 +221,59 @@ 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. */
+    /** Apply-time account provisioning. **Default `"none"`** — it provisions
+     *  nothing, because the alternatives have an outbound side effect and a site
+     *  that never made the choice must not be mailing people. `"create"` makes the
+     *  Clerk account server-side (so join can say the account is ready);
+     *  `"invite"` **emails the applicant a Clerk invitation**. Both non-default
+     *  models need a `clerk_secret_key` vault secret to act. Opt in explicitly —
+     *  leaving this unset provisions no accounts. */
     account?: AccountModel;
     /** WHEN lifecycle email fires. Addressing and content live on the group row
      *  (owner-editable at runtime); this is the trigger, which is a build-time
      *  decision. See {@link ChapterSends}. */
     sends?: ChapterSends;
+    /** Site policy for admin operations (approve side effects, refund rules).
+     *  See {@link ChapterOperations}. */
+    operations?: ChapterOperations;
 }
 /** Apply-time Clerk account provisioning model. */
 type AccountModel = "invite" | "create" | "none";
+/** Site policy for admin OPERATIONS: the DECISIONS, where the mechanics stay
+ *  package-owned. Same model as {@link ChapterSends} — a site declares the rule,
+ *  chapter enforces it. Distinct from {@link ChapterPolicy}, which is member-facing
+ *  copy. (The privilege-escalation rules are NOT here: they are package-enforced
+ *  in `canChangeRole`, gated on `auth.superAdmins`, so a site cannot weaken them.) */
+interface ChapterOperations {
+    /** What approving an application does. */
+    onApprove?: {
+        /** Role to promote the applicant to in Clerk. Defaults to the ladder rung
+         *  directly below admin (e.g. `"member"`); `false` promotes nobody. */
+        promoteTo?: string | false;
+        /** Group email template to send on approve. Default `"onboardingInvite"`;
+         *  `false` sends nothing. */
+        send?: string | false;
+    };
+    /** Refund rules. */
+    refund?: {
+        /** Application statuses a refund may be issued from. Default: any status. */
+        allowedFrom?: readonly string[];
+        /** Also cancel the Stripe subscription. Default `true`. */
+        cancelSubscription?: boolean;
+    };
+}
+/** The fully-resolved {@link ChapterOperations} carried on the {@link Chapter}. */
+interface ResolvedOperations {
+    onApprove: {
+        promoteTo: string | false;
+        send: string | false;
+    };
+    /** `allowedFrom: null` means "any status". */
+    refund: {
+        allowedFrom: readonly string[] | null;
+        cancelSubscription: boolean;
+    };
+}
 /** When the admin notification fires: on application `submit` (default), on the
  *  first successful `payment`, or `never` (the site drives it itself). */
 type AdminNotificationTrigger = "submit" | "payment" | "never";
@@ -263,10 +304,12 @@ interface Chapter {
     schema: DbSchema;
     rules: DbRules;
     services: readonly string[];
-    /** Resolved apply-time account provisioning model (default `"invite"`). */
+    /** Resolved apply-time account provisioning model (default `"none"`). */
     account: AccountModel;
     /** Resolved send policy — when each lifecycle email fires. */
     sends: ResolvedSends;
+    /** Resolved admin-operation policy (approve side effects, refund rules). */
+    operations: ResolvedOperations;
     /** The seed `groups` row derived from config (chapter mode), else `null`. */
     groupSeed(): Record<string, unknown> | null;
 }

package/dist/worker/index.d.ts

@@ -221,18 +221,59 @@ 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. */
+    /** Apply-time account provisioning. **Default `"none"`** — it provisions
+     *  nothing, because the alternatives have an outbound side effect and a site
+     *  that never made the choice must not be mailing people. `"create"` makes the
+     *  Clerk account server-side (so join can say the account is ready);
+     *  `"invite"` **emails the applicant a Clerk invitation**. Both non-default
+     *  models need a `clerk_secret_key` vault secret to act. Opt in explicitly —
+     *  leaving this unset provisions no accounts. */
     account?: AccountModel;
     /** WHEN lifecycle email fires. Addressing and content live on the group row
      *  (owner-editable at runtime); this is the trigger, which is a build-time
      *  decision. See {@link ChapterSends}. */
     sends?: ChapterSends;
+    /** Site policy for admin operations (approve side effects, refund rules).
+     *  See {@link ChapterOperations}. */
+    operations?: ChapterOperations;
 }
 /** Apply-time Clerk account provisioning model. */
 type AccountModel = "invite" | "create" | "none";
+/** Site policy for admin OPERATIONS: the DECISIONS, where the mechanics stay
+ *  package-owned. Same model as {@link ChapterSends} — a site declares the rule,
+ *  chapter enforces it. Distinct from {@link ChapterPolicy}, which is member-facing
+ *  copy. (The privilege-escalation rules are NOT here: they are package-enforced
+ *  in `canChangeRole`, gated on `auth.superAdmins`, so a site cannot weaken them.) */
+interface ChapterOperations {
+    /** What approving an application does. */
+    onApprove?: {
+        /** Role to promote the applicant to in Clerk. Defaults to the ladder rung
+         *  directly below admin (e.g. `"member"`); `false` promotes nobody. */
+        promoteTo?: string | false;
+        /** Group email template to send on approve. Default `"onboardingInvite"`;
+         *  `false` sends nothing. */
+        send?: string | false;
+    };
+    /** Refund rules. */
+    refund?: {
+        /** Application statuses a refund may be issued from. Default: any status. */
+        allowedFrom?: readonly string[];
+        /** Also cancel the Stripe subscription. Default `true`. */
+        cancelSubscription?: boolean;
+    };
+}
+/** The fully-resolved {@link ChapterOperations} carried on the {@link Chapter}. */
+interface ResolvedOperations {
+    onApprove: {
+        promoteTo: string | false;
+        send: string | false;
+    };
+    /** `allowedFrom: null` means "any status". */
+    refund: {
+        allowedFrom: readonly string[] | null;
+        cancelSubscription: boolean;
+    };
+}
 /** When the admin notification fires: on application `submit` (default), on the
  *  first successful `payment`, or `never` (the site drives it itself). */
 type AdminNotificationTrigger = "submit" | "payment" | "never";
@@ -263,10 +304,12 @@ interface Chapter {
     schema: DbSchema;
     rules: DbRules;
     services: readonly string[];
-    /** Resolved apply-time account provisioning model (default `"invite"`). */
+    /** Resolved apply-time account provisioning model (default `"none"`). */
     account: AccountModel;
     /** Resolved send policy — when each lifecycle email fires. */
     sends: ResolvedSends;
+    /** Resolved admin-operation policy (approve side effects, refund rules). */
+    operations: ResolvedOperations;
     /** The seed `groups` row derived from config (chapter mode), else `null`. */
     groupSeed(): Record<string, unknown> | null;
 }