@odla-ai/chapter 0.48.3 → 0.50.0

package/dist/worker/index.d.cts

@@ -27,15 +27,28 @@ type TextFields$1<Key extends string> = {
 /** User-visible language for sharing, delivery state, and leader rollups. */
 type AdminNetworkCopy = TextFields$1<"title" | "allowlistDescription" | "sharing" | "shareWith" | "shared" | "shareFailed" | "deliveryFailed" | "loadingRollup" | "loadRollupFailed" | "overview" | "configuredFollowers" | "reachableFollowers" | "recordsAcrossFollowers" | "noFollowers" | "followers" | "available" | "unavailable" | "transportReachable" | "transportUnavailable" | "transportNotChecked" | "bindingTransport" | "urlTransport" | "activeConfiguration" | "noActiveConfiguration" | "publicSiteAvailable" | "publicSiteUnavailable" | "publicSiteNotChecked" | "recordTotals" | "noRecordTotals">;
 
+/** Copy for the person record panels: lifecycle actions, comms, scheduling, billing and meetings. */
+type AdminRecordsCopy = {
+    [Field in AdminRecordsCopyKey]: string;
+};
+/** Every key a host may override under `admin.records`. */
+type AdminRecordsCopyKey = "workflowMissing" | "invitation" | "comms" | "commsHistory" | "scheduling" | "billing" | "notes" | "access" | "sharing" | "lifecycle" | "role" | "superAdminHint" | "noAccount" | "approve" | "refund" | "approved" | "refunded" | "roleSet" | "messageSent" | "messageNotSent" | "loadingTemplates" | "template" | "chooseTemplate" | "sending" | "send" | "noMessages" | "message" | "newStartPrompt" | "parseFailed" | "cancelConfirm" | "callCancelled" | "callRescheduled" | "noApplication" | "loadingMeetings" | "noMeetings" | "joinMeeting" | "openCalendar" | "reschedule" | "cancel";
+
 type TextFields<Key extends string> = {
     [Field in Key]: string;
 };
+
 /** Complete serializable language for Chapter surfaces; use render slots for markup and `formatChapterCopy()` for placeholders. */
 interface ChapterCopy {
     common: TextFields<"loading" | "saved" | "unknown">;
     join: {
+        /** Prepaid invitation attribution, consent and recoverable error copy. */
+        namedSeat?: TextFields<"title" | "from" | "prepaid" | "body" | "consent" | "accept" | "accepting" | "loading" | "unavailable" | "retry" | "failure">;
         form: TextFields<"submit" | "submitting" | "submitFailed" | "unexpectedFailure">;
-        booking: TextFields<"unavailable" | "loadFailed" | "slotTaken" | "failed" | "loading" | "book" | "booking">;
+        booking: TextFields<"unavailable" | "loadFailed" | "slotTaken" | "failed" | "loading" | "book" | "booking"> & {
+            title?: string;
+            intro?: string;
+        };
         /**
          * `consent` is the affirmative statement a member agrees to before the card
          * form appears, rendered beside the checkbox and beneath the policy text.
@@ -43,7 +56,7 @@ interface ChapterCopy {
          * agree rather than merely restating the policy. Set it to an empty string
          * to render the checkbox with the policy as its only label.
          */
-        payment: TextFields<"setupFailed" | "preparing" | "pending" | "processing" | "payAndContinue" | "incomplete" | "consent">;
+        payment: TextFields<"setupFailed" | "preparing" | "pending" | "processing" | "payAndContinue" | "incomplete" | "consent" | "foundingMember" | "foundingDiscount">;
         done: TextFields<"label" | "calendarInvite" | "memberArea">;
         accepted: TextFields<"label" | "body">;
         gift: TextFields<"chooseSelf" | "optionsLabel" | "label" | "body" | "save" | "rotate" | "rotateFailed" | "claimTitle" | "claimBody" | "code" | "redeem" | "redeemed" | "redeemFailed">;
@@ -69,7 +82,7 @@ interface ChapterCopy {
         meetings: TextFields<"loading" | "loadFailed" | "cancelConfirm" | "newStartPrompt" | "parseFailed" | "agenda" | "empty" | "unknown" | "drift" | "meet" | "reschedule" | "cancel">;
         admission: TextFields<"title" | "description" | "email" | "decision" | "expires" | "note" | "waive" | "require" | "add" | "ledger" | "loading" | "consumed" | "revoked" | "expired" | "active" | "local" | "parent" | "revoke">;
         network: AdminNetworkCopy;
-        records: TextFields<"workflowMissing" | "comms" | "commsHistory" | "scheduling" | "billing" | "notes" | "access" | "sharing" | "lifecycle" | "role" | "superAdminHint" | "noAccount" | "approve" | "refund" | "approved" | "refunded" | "roleSet" | "messageSent" | "messageNotSent" | "loadingTemplates" | "template" | "chooseTemplate" | "sending" | "send" | "noMessages" | "message" | "newStartPrompt" | "parseFailed" | "cancelConfirm" | "callCancelled" | "callRescheduled" | "noApplication" | "loadingMeetings" | "noMeetings" | "joinMeeting" | "openCalendar" | "reschedule" | "cancel">;
+        records: AdminRecordsCopy;
     };
 }
 type DeepPartial<T> = T extends readonly (infer Item)[] ? readonly Item[] : T extends object ? {
@@ -880,6 +893,20 @@ interface IssuedMembershipOffer {
     digest: string;
     contract: MembershipCommercialOffer;
 }
+/** What a join page may show before anyone applies: the current promise, without coupon ids or cohort counts. */
+interface MembershipOfferPreview {
+    skuId: string;
+    offeringVersionId: string;
+    basePriceCents: number;
+    currency: string;
+    interval: "month" | "year";
+    founding: boolean;
+    cohortLabel?: string;
+    dueTodayCents: number;
+    renewalCents: number;
+    discountDuration?: "first_term" | "while_active";
+    initialTermEndsAt?: number;
+}
 
 /** Server-owned source identity; the browser never supplies an offer or its price. */
 interface MembershipQuoteTarget {
@@ -895,6 +922,19 @@ type MembershipOfferIssuer = (input: MembershipQuoteTarget & {
     requestId: string;
 }) => Promise<IssuedMembershipOffer>;
 
+/** A fresh purchase generation for the same previously approved application and membership. */
+type MembershipRestartInput = MembershipQuoteTarget & {
+    previousSubscriptionId: string;
+};
+/** Receipt authorizing a fresh checkout, never proof of payment or access. */
+interface MembershipRestartReceipt {
+    applicationId: string;
+    membershipId: string;
+    restartId: string;
+    memberNumber: number;
+    status: "ready";
+}
+
 /** A consented offer, bound once to the follower's immutable provider Price and quote. */
 interface MembershipCheckoutBindingInput extends MembershipQuoteTarget {
     offerId: string;
@@ -956,6 +996,7 @@ interface MembershipAccessReceipt {
     status: string;
     accessEndsAt: number;
     revision: number;
+    restartEligible?: boolean;
 }
 
 /** Named-seat offer for the authenticated purchaser, not a transferable gift or arbitrary quantity. */
@@ -1006,9 +1047,11 @@ interface MembershipChapterEffect extends MembershipQuoteTarget {
     seatId: string;
     kind: "invite_named_recipient" | "grant_named_recipient_access" | "revoke_named_recipient_access";
 }
-/** Recover provider effects and expired invitations from durable state, independently of browser/webhook retries.
+/** Recover provider effects from durable state, independently of browser/webhook retries.
  * The optional chapter adapter must return a durable, idempotent receipt. An absent adapter leaves work visibly pending.
  * Provider HTTP timeouts, ambiguous receipts and scope conflicts never become success or an unbounded automatic retry loop.
+ * An unaccepted seat is never refunded here: refunds are an operator decision (`refundNamedSeatByOperator`),
+ * a recipient decline, a closed primary, or a provider-initiated refund.
  */
 declare function drainMembershipEffects(db: ChapterDb, options: {
     scope: MembershipEffectScope;
@@ -1021,7 +1064,6 @@ declare function drainMembershipEffects(db: ChapterDb, options: {
 }, now: number): Promise<{
     complete: number;
     pending: number;
-    expired: number;
     more: boolean;
 }>;
 
@@ -1036,6 +1078,22 @@ interface MembershipChapterEffectData extends MembershipChapterEffect {
     applicable: boolean;
 }
 
+/** Inputs supplied by an authenticated chapter backend; no browser credentials cross this edge. */
+interface RequestMembershipOfferOptions {
+    secret: string;
+    targetUrl: string;
+    appId: string;
+    chapterId: string;
+    environment: string;
+    runtime: string;
+    applicationId: string;
+    skuId: string;
+    requestId: string;
+    /** A configured service binding may replace public fetch, but must not fall back when absent. */
+    fetch?: typeof globalThis.fetch;
+}
+/** Scope of a join-page preview; the browser never supplies it. */
+type MembershipOfferPreviewScope = Pick<RequestMembershipOfferOptions, "appId" | "chapterId" | "environment" | "runtime" | "skuId">;
 /** Only the named buyer's prepared payment details; no network credentials or canonical PII. */
 interface NamedSeatCheckoutReceipt {
     seatId: string;
@@ -1123,6 +1181,8 @@ interface ChapterWorkerOptions {
      * scope. Never implement these by promoting chapter-local projections to authority. */
     membershipAuthority?: {
         issueOffer: (input: Parameters<MembershipOfferIssuer>[0], env: ChapterEnv) => ReturnType<MembershipOfferIssuer>;
+        /** Read-only founding preview for a join page; absent on older adapters, in which case tiers carry no preview. */
+        previewOffer?: (input: MembershipOfferPreviewScope, env: ChapterEnv) => Promise<MembershipOfferPreview>;
         bindCheckout: (input: MembershipCheckoutBindingInput, env: ChapterEnv) => Promise<MembershipCheckoutBinding>;
         confirmPayment: (input: ConfirmMembershipPaymentInput, env: ChapterEnv) => Promise<MembershipPaymentReceipt>;
         approveMembership: (input: MembershipQuoteTarget, env: ChapterEnv) => Promise<MembershipPaymentReceipt>;
@@ -1130,6 +1190,8 @@ interface ChapterWorkerOptions {
         reconcileRenewal: (input: MembershipQuoteTarget & {
             eventId: string;
         }, env: ChapterEnv) => Promise<MembershipRenewalReceipt>;
+        cancelRenewal?: (input: MembershipQuoteTarget, env: ChapterEnv) => Promise<MembershipRenewalReceipt>;
+        restart?: (input: MembershipRestartInput, env: ChapterEnv) => Promise<MembershipRestartReceipt>;
         readAccess: (input: MembershipQuoteTarget, env: ChapterEnv) => Promise<MembershipAccessReceipt>;
         namedSeats?: {
             offer: (input: MembershipQuoteTarget, env: ChapterEnv) => Promise<NamedSeatOffer>;
@@ -1152,8 +1214,18 @@ interface ChapterWorkerOptions {
             accept: (input: NamedSeatRecipientInput, env: ChapterEnv) => Promise<NamedSeatRecipientReceipt>;
             approve: (input: NamedSeatRecipientInput, env: ChapterEnv) => Promise<NamedSeatRecipientReceipt>;
             decline: (input: NamedSeatRecipientInput, env: ChapterEnv) => Promise<NamedSeatRefundReceipt>;
+            /** A verified super admin refunds one purchased seat; never automatic. */
+            operatorRefund: (input: MembershipQuoteTarget & {
+                seatId: string;
+            }, env: ChapterEnv) => Promise<NamedSeatRefundReceipt>;
         };
     };
+    /** Network owner only: operate the membership authority this Worker hosts (seat refunds by a super admin).
+     * `makeDb` must return the authority storage mapping, never a chapter projection. */
+    membershipAuthorityOperator?: {
+        makeDb: (env: ChapterEnv) => ChapterDb;
+        stripeSecretName?: string;
+    };
     /** CRM mount point. Default "/api/crm". */
     crmBasePath?: string;
     /** Host routes, tried BEFORE the built-ins — so a wrapping site can add its own
@@ -1189,6 +1261,8 @@ declare function createWorkerContext(options: ChapterWorkerOptions): {
     requirePaymentQuote: boolean;
     membershipAuthority: {
         issueOffer: (input: Parameters<MembershipOfferIssuer>[0], env: ChapterEnv) => ReturnType<MembershipOfferIssuer>;
+        /** Read-only founding preview for a join page; absent on older adapters, in which case tiers carry no preview. */
+        previewOffer?: (input: MembershipOfferPreviewScope, env: ChapterEnv) => Promise<MembershipOfferPreview>;
         bindCheckout: (input: MembershipCheckoutBindingInput, env: ChapterEnv) => Promise<MembershipCheckoutBinding>;
         confirmPayment: (input: ConfirmMembershipPaymentInput, env: ChapterEnv) => Promise<MembershipPaymentReceipt>;
         approveMembership: (input: MembershipQuoteTarget, env: ChapterEnv) => Promise<MembershipPaymentReceipt>;
@@ -1196,6 +1270,8 @@ declare function createWorkerContext(options: ChapterWorkerOptions): {
         reconcileRenewal: (input: MembershipQuoteTarget & {
             eventId: string;
         }, env: ChapterEnv) => Promise<MembershipRenewalReceipt>;
+        cancelRenewal?: (input: MembershipQuoteTarget, env: ChapterEnv) => Promise<MembershipRenewalReceipt>;
+        restart?: (input: MembershipRestartInput, env: ChapterEnv) => Promise<MembershipRestartReceipt>;
         readAccess: (input: MembershipQuoteTarget, env: ChapterEnv) => Promise<MembershipAccessReceipt>;
         namedSeats?: {
             offer: (input: MembershipQuoteTarget, env: ChapterEnv) => Promise<NamedSeatOffer>;
@@ -1218,8 +1294,16 @@ declare function createWorkerContext(options: ChapterWorkerOptions): {
             accept: (input: NamedSeatRecipientInput, env: ChapterEnv) => Promise<NamedSeatRecipientReceipt>;
             approve: (input: NamedSeatRecipientInput, env: ChapterEnv) => Promise<NamedSeatRecipientReceipt>;
             decline: (input: NamedSeatRecipientInput, env: ChapterEnv) => Promise<NamedSeatRefundReceipt>;
+            /** A verified super admin refunds one purchased seat; never automatic. */
+            operatorRefund: (input: MembershipQuoteTarget & {
+                seatId: string;
+            }, env: ChapterEnv) => Promise<NamedSeatRefundReceipt>;
         };
     } | undefined;
+    membershipAuthorityOperator: {
+        makeDb: (env: ChapterEnv) => ChapterDb;
+        stripeSecretName?: string;
+    } | undefined;
     getPublicConfig: (env: ChapterEnv) => Promise<PublicConfig>;
     verifyUser: (req: Request, env: ChapterEnv) => Promise<Verified | null>;
     makeDb: (env: ChapterEnv) => Db;
@@ -1279,6 +1363,21 @@ declare function createMembershipAuthorityHandler(options: MembershipAuthorityHa
  */
 declare function createMembershipAuthorityStorage(db: ChapterDb, secretNames: readonly string[]): ChapterDb;
 
+/** Identity of one purchased seat inside its exact network scope. */
+type NamedSeatOperatorRefundInput = MembershipQuoteTarget & {
+    seatId: string;
+};
+/** Refund one purchased named seat because a verified super admin decided to.
+ * Nothing here is automatic or time-driven: the caller has already authenticated
+ * the operator on the chapter or on the network owner. The primary subscription
+ * is never canceled; an accepted recipient loses access through the durable
+ * revoke effect, and a replay after the refund is idempotent.
+ */
+declare function refundNamedSeatByOperator(db: ChapterDb, input: NamedSeatOperatorRefundInput, stripeSecretKey: string, now: number): Promise<NamedSeatRefundReceipt>;
+
+/** Reasons a purchased seat may be refunded. No reason is time-driven: an unaccepted seat waits for a person. */
+type NamedSeatRefundReason = "declined" | "operator" | "primary_closed" | "provider_refund";
+
 type Row = Record<string, unknown>;
 /** Host routes may reuse this gate after resolving a verified chapter/runtime account. */
 declare function chapterMembershipAccess(db: ChapterDb, env: ChapterEnv, ctx: WorkerContext, app: Row): Promise<boolean>;
@@ -1897,4 +1996,4 @@ declare function chapterWorker(options: ChapterWorkerOptions): {
     fetch(req: Request, env: ChapterEnv): Promise<Response>;
 };
 
-export { type ActiveSignupControlHtml, type ActiveSignupControlThemeOptions, AdmissionGrantDeliveryError, type AdmissionGrantDeliveryOptions, type BuilderLibraryDeliveryOptions, type ChapterEnv, type ChapterWorkerOptions, type LeaderAdmissionAssignment, type LeaderAdmissionDelivery, type LeaderAdmissionDeliveryStatus, MEMBERSHIP_AUTHORITY_PATH, type MemberContentDeliveryOptions, type MembershipAuthorityHandlerOptions, type MembershipAuthorityPeer, type MembershipChapterEffect, type MembershipEffectScope, type MembershipWorkerAdapter, type MembershipWorkerAdapterOptions, type NetworkTargetTransport, NetworkTargetTransportError, type Route, type SignupControlDeliveryOptions, type WorkerContext, chapterMembershipAccess, chapterWorker, createMembershipAuthorityHandler, createMembershipAuthorityStorage, createMembershipChapterEffectRoute, createMembershipWorkerAdapter, createWorkerContext, deliverAdmissionGrants, deliverBuilderLibrary, deliverMemberContent, deliverMembershipChapterEffect, deliverSignupControl, drainMembershipEffects, renderActiveSignupControlHtml, resolveNetworkTargetTransport, retryChapterApprovalEffects, retryLeaderAdmissionDeliveries, withActiveSignupControlTheme };
+export { type ActiveSignupControlHtml, type ActiveSignupControlThemeOptions, AdmissionGrantDeliveryError, type AdmissionGrantDeliveryOptions, type BuilderLibraryDeliveryOptions, type ChapterEnv, type ChapterWorkerOptions, type LeaderAdmissionAssignment, type LeaderAdmissionDelivery, type LeaderAdmissionDeliveryStatus, MEMBERSHIP_AUTHORITY_PATH, type MemberContentDeliveryOptions, type MembershipAuthorityHandlerOptions, type MembershipAuthorityPeer, type MembershipChapterEffect, type MembershipEffectScope, type MembershipWorkerAdapter, type MembershipWorkerAdapterOptions, type NamedSeatOperatorRefundInput, type NamedSeatRefundReason, type NetworkTargetTransport, NetworkTargetTransportError, type Route, type SignupControlDeliveryOptions, type WorkerContext, chapterMembershipAccess, chapterWorker, createMembershipAuthorityHandler, createMembershipAuthorityStorage, createMembershipChapterEffectRoute, createMembershipWorkerAdapter, createWorkerContext, deliverAdmissionGrants, deliverBuilderLibrary, deliverMemberContent, deliverMembershipChapterEffect, deliverSignupControl, drainMembershipEffects, refundNamedSeatByOperator, renderActiveSignupControlHtml, resolveNetworkTargetTransport, retryChapterApprovalEffects, retryLeaderAdmissionDeliveries, withActiveSignupControlTheme };

package/dist/worker/index.d.ts

@@ -27,15 +27,28 @@ type TextFields$1<Key extends string> = {
 /** User-visible language for sharing, delivery state, and leader rollups. */
 type AdminNetworkCopy = TextFields$1<"title" | "allowlistDescription" | "sharing" | "shareWith" | "shared" | "shareFailed" | "deliveryFailed" | "loadingRollup" | "loadRollupFailed" | "overview" | "configuredFollowers" | "reachableFollowers" | "recordsAcrossFollowers" | "noFollowers" | "followers" | "available" | "unavailable" | "transportReachable" | "transportUnavailable" | "transportNotChecked" | "bindingTransport" | "urlTransport" | "activeConfiguration" | "noActiveConfiguration" | "publicSiteAvailable" | "publicSiteUnavailable" | "publicSiteNotChecked" | "recordTotals" | "noRecordTotals">;
 
+/** Copy for the person record panels: lifecycle actions, comms, scheduling, billing and meetings. */
+type AdminRecordsCopy = {
+    [Field in AdminRecordsCopyKey]: string;
+};
+/** Every key a host may override under `admin.records`. */
+type AdminRecordsCopyKey = "workflowMissing" | "invitation" | "comms" | "commsHistory" | "scheduling" | "billing" | "notes" | "access" | "sharing" | "lifecycle" | "role" | "superAdminHint" | "noAccount" | "approve" | "refund" | "approved" | "refunded" | "roleSet" | "messageSent" | "messageNotSent" | "loadingTemplates" | "template" | "chooseTemplate" | "sending" | "send" | "noMessages" | "message" | "newStartPrompt" | "parseFailed" | "cancelConfirm" | "callCancelled" | "callRescheduled" | "noApplication" | "loadingMeetings" | "noMeetings" | "joinMeeting" | "openCalendar" | "reschedule" | "cancel";
+
 type TextFields<Key extends string> = {
     [Field in Key]: string;
 };
+
 /** Complete serializable language for Chapter surfaces; use render slots for markup and `formatChapterCopy()` for placeholders. */
 interface ChapterCopy {
     common: TextFields<"loading" | "saved" | "unknown">;
     join: {
+        /** Prepaid invitation attribution, consent and recoverable error copy. */
+        namedSeat?: TextFields<"title" | "from" | "prepaid" | "body" | "consent" | "accept" | "accepting" | "loading" | "unavailable" | "retry" | "failure">;
         form: TextFields<"submit" | "submitting" | "submitFailed" | "unexpectedFailure">;
-        booking: TextFields<"unavailable" | "loadFailed" | "slotTaken" | "failed" | "loading" | "book" | "booking">;
+        booking: TextFields<"unavailable" | "loadFailed" | "slotTaken" | "failed" | "loading" | "book" | "booking"> & {
+            title?: string;
+            intro?: string;
+        };
         /**
          * `consent` is the affirmative statement a member agrees to before the card
          * form appears, rendered beside the checkbox and beneath the policy text.
@@ -43,7 +56,7 @@ interface ChapterCopy {
          * agree rather than merely restating the policy. Set it to an empty string
          * to render the checkbox with the policy as its only label.
          */
-        payment: TextFields<"setupFailed" | "preparing" | "pending" | "processing" | "payAndContinue" | "incomplete" | "consent">;
+        payment: TextFields<"setupFailed" | "preparing" | "pending" | "processing" | "payAndContinue" | "incomplete" | "consent" | "foundingMember" | "foundingDiscount">;
         done: TextFields<"label" | "calendarInvite" | "memberArea">;
         accepted: TextFields<"label" | "body">;
         gift: TextFields<"chooseSelf" | "optionsLabel" | "label" | "body" | "save" | "rotate" | "rotateFailed" | "claimTitle" | "claimBody" | "code" | "redeem" | "redeemed" | "redeemFailed">;
@@ -69,7 +82,7 @@ interface ChapterCopy {
         meetings: TextFields<"loading" | "loadFailed" | "cancelConfirm" | "newStartPrompt" | "parseFailed" | "agenda" | "empty" | "unknown" | "drift" | "meet" | "reschedule" | "cancel">;
         admission: TextFields<"title" | "description" | "email" | "decision" | "expires" | "note" | "waive" | "require" | "add" | "ledger" | "loading" | "consumed" | "revoked" | "expired" | "active" | "local" | "parent" | "revoke">;
         network: AdminNetworkCopy;
-        records: TextFields<"workflowMissing" | "comms" | "commsHistory" | "scheduling" | "billing" | "notes" | "access" | "sharing" | "lifecycle" | "role" | "superAdminHint" | "noAccount" | "approve" | "refund" | "approved" | "refunded" | "roleSet" | "messageSent" | "messageNotSent" | "loadingTemplates" | "template" | "chooseTemplate" | "sending" | "send" | "noMessages" | "message" | "newStartPrompt" | "parseFailed" | "cancelConfirm" | "callCancelled" | "callRescheduled" | "noApplication" | "loadingMeetings" | "noMeetings" | "joinMeeting" | "openCalendar" | "reschedule" | "cancel">;
+        records: AdminRecordsCopy;
     };
 }
 type DeepPartial<T> = T extends readonly (infer Item)[] ? readonly Item[] : T extends object ? {
@@ -880,6 +893,20 @@ interface IssuedMembershipOffer {
     digest: string;
     contract: MembershipCommercialOffer;
 }
+/** What a join page may show before anyone applies: the current promise, without coupon ids or cohort counts. */
+interface MembershipOfferPreview {
+    skuId: string;
+    offeringVersionId: string;
+    basePriceCents: number;
+    currency: string;
+    interval: "month" | "year";
+    founding: boolean;
+    cohortLabel?: string;
+    dueTodayCents: number;
+    renewalCents: number;
+    discountDuration?: "first_term" | "while_active";
+    initialTermEndsAt?: number;
+}
 
 /** Server-owned source identity; the browser never supplies an offer or its price. */
 interface MembershipQuoteTarget {
@@ -895,6 +922,19 @@ type MembershipOfferIssuer = (input: MembershipQuoteTarget & {
     requestId: string;
 }) => Promise<IssuedMembershipOffer>;
 
+/** A fresh purchase generation for the same previously approved application and membership. */
+type MembershipRestartInput = MembershipQuoteTarget & {
+    previousSubscriptionId: string;
+};
+/** Receipt authorizing a fresh checkout, never proof of payment or access. */
+interface MembershipRestartReceipt {
+    applicationId: string;
+    membershipId: string;
+    restartId: string;
+    memberNumber: number;
+    status: "ready";
+}
+
 /** A consented offer, bound once to the follower's immutable provider Price and quote. */
 interface MembershipCheckoutBindingInput extends MembershipQuoteTarget {
     offerId: string;
@@ -956,6 +996,7 @@ interface MembershipAccessReceipt {
     status: string;
     accessEndsAt: number;
     revision: number;
+    restartEligible?: boolean;
 }
 
 /** Named-seat offer for the authenticated purchaser, not a transferable gift or arbitrary quantity. */
@@ -1006,9 +1047,11 @@ interface MembershipChapterEffect extends MembershipQuoteTarget {
     seatId: string;
     kind: "invite_named_recipient" | "grant_named_recipient_access" | "revoke_named_recipient_access";
 }
-/** Recover provider effects and expired invitations from durable state, independently of browser/webhook retries.
+/** Recover provider effects from durable state, independently of browser/webhook retries.
  * The optional chapter adapter must return a durable, idempotent receipt. An absent adapter leaves work visibly pending.
  * Provider HTTP timeouts, ambiguous receipts and scope conflicts never become success or an unbounded automatic retry loop.
+ * An unaccepted seat is never refunded here: refunds are an operator decision (`refundNamedSeatByOperator`),
+ * a recipient decline, a closed primary, or a provider-initiated refund.
  */
 declare function drainMembershipEffects(db: ChapterDb, options: {
     scope: MembershipEffectScope;
@@ -1021,7 +1064,6 @@ declare function drainMembershipEffects(db: ChapterDb, options: {
 }, now: number): Promise<{
     complete: number;
     pending: number;
-    expired: number;
     more: boolean;
 }>;
 
@@ -1036,6 +1078,22 @@ interface MembershipChapterEffectData extends MembershipChapterEffect {
     applicable: boolean;
 }
 
+/** Inputs supplied by an authenticated chapter backend; no browser credentials cross this edge. */
+interface RequestMembershipOfferOptions {
+    secret: string;
+    targetUrl: string;
+    appId: string;
+    chapterId: string;
+    environment: string;
+    runtime: string;
+    applicationId: string;
+    skuId: string;
+    requestId: string;
+    /** A configured service binding may replace public fetch, but must not fall back when absent. */
+    fetch?: typeof globalThis.fetch;
+}
+/** Scope of a join-page preview; the browser never supplies it. */
+type MembershipOfferPreviewScope = Pick<RequestMembershipOfferOptions, "appId" | "chapterId" | "environment" | "runtime" | "skuId">;
 /** Only the named buyer's prepared payment details; no network credentials or canonical PII. */
 interface NamedSeatCheckoutReceipt {
     seatId: string;
@@ -1123,6 +1181,8 @@ interface ChapterWorkerOptions {
      * scope. Never implement these by promoting chapter-local projections to authority. */
     membershipAuthority?: {
         issueOffer: (input: Parameters<MembershipOfferIssuer>[0], env: ChapterEnv) => ReturnType<MembershipOfferIssuer>;
+        /** Read-only founding preview for a join page; absent on older adapters, in which case tiers carry no preview. */
+        previewOffer?: (input: MembershipOfferPreviewScope, env: ChapterEnv) => Promise<MembershipOfferPreview>;
         bindCheckout: (input: MembershipCheckoutBindingInput, env: ChapterEnv) => Promise<MembershipCheckoutBinding>;
         confirmPayment: (input: ConfirmMembershipPaymentInput, env: ChapterEnv) => Promise<MembershipPaymentReceipt>;
         approveMembership: (input: MembershipQuoteTarget, env: ChapterEnv) => Promise<MembershipPaymentReceipt>;
@@ -1130,6 +1190,8 @@ interface ChapterWorkerOptions {
         reconcileRenewal: (input: MembershipQuoteTarget & {
             eventId: string;
         }, env: ChapterEnv) => Promise<MembershipRenewalReceipt>;
+        cancelRenewal?: (input: MembershipQuoteTarget, env: ChapterEnv) => Promise<MembershipRenewalReceipt>;
+        restart?: (input: MembershipRestartInput, env: ChapterEnv) => Promise<MembershipRestartReceipt>;
         readAccess: (input: MembershipQuoteTarget, env: ChapterEnv) => Promise<MembershipAccessReceipt>;
         namedSeats?: {
             offer: (input: MembershipQuoteTarget, env: ChapterEnv) => Promise<NamedSeatOffer>;
@@ -1152,8 +1214,18 @@ interface ChapterWorkerOptions {
             accept: (input: NamedSeatRecipientInput, env: ChapterEnv) => Promise<NamedSeatRecipientReceipt>;
             approve: (input: NamedSeatRecipientInput, env: ChapterEnv) => Promise<NamedSeatRecipientReceipt>;
             decline: (input: NamedSeatRecipientInput, env: ChapterEnv) => Promise<NamedSeatRefundReceipt>;
+            /** A verified super admin refunds one purchased seat; never automatic. */
+            operatorRefund: (input: MembershipQuoteTarget & {
+                seatId: string;
+            }, env: ChapterEnv) => Promise<NamedSeatRefundReceipt>;
         };
     };
+    /** Network owner only: operate the membership authority this Worker hosts (seat refunds by a super admin).
+     * `makeDb` must return the authority storage mapping, never a chapter projection. */
+    membershipAuthorityOperator?: {
+        makeDb: (env: ChapterEnv) => ChapterDb;
+        stripeSecretName?: string;
+    };
     /** CRM mount point. Default "/api/crm". */
     crmBasePath?: string;
     /** Host routes, tried BEFORE the built-ins — so a wrapping site can add its own
@@ -1189,6 +1261,8 @@ declare function createWorkerContext(options: ChapterWorkerOptions): {
     requirePaymentQuote: boolean;
     membershipAuthority: {
         issueOffer: (input: Parameters<MembershipOfferIssuer>[0], env: ChapterEnv) => ReturnType<MembershipOfferIssuer>;
+        /** Read-only founding preview for a join page; absent on older adapters, in which case tiers carry no preview. */
+        previewOffer?: (input: MembershipOfferPreviewScope, env: ChapterEnv) => Promise<MembershipOfferPreview>;
         bindCheckout: (input: MembershipCheckoutBindingInput, env: ChapterEnv) => Promise<MembershipCheckoutBinding>;
         confirmPayment: (input: ConfirmMembershipPaymentInput, env: ChapterEnv) => Promise<MembershipPaymentReceipt>;
         approveMembership: (input: MembershipQuoteTarget, env: ChapterEnv) => Promise<MembershipPaymentReceipt>;
@@ -1196,6 +1270,8 @@ declare function createWorkerContext(options: ChapterWorkerOptions): {
         reconcileRenewal: (input: MembershipQuoteTarget & {
             eventId: string;
         }, env: ChapterEnv) => Promise<MembershipRenewalReceipt>;
+        cancelRenewal?: (input: MembershipQuoteTarget, env: ChapterEnv) => Promise<MembershipRenewalReceipt>;
+        restart?: (input: MembershipRestartInput, env: ChapterEnv) => Promise<MembershipRestartReceipt>;
         readAccess: (input: MembershipQuoteTarget, env: ChapterEnv) => Promise<MembershipAccessReceipt>;
         namedSeats?: {
             offer: (input: MembershipQuoteTarget, env: ChapterEnv) => Promise<NamedSeatOffer>;
@@ -1218,8 +1294,16 @@ declare function createWorkerContext(options: ChapterWorkerOptions): {
             accept: (input: NamedSeatRecipientInput, env: ChapterEnv) => Promise<NamedSeatRecipientReceipt>;
             approve: (input: NamedSeatRecipientInput, env: ChapterEnv) => Promise<NamedSeatRecipientReceipt>;
             decline: (input: NamedSeatRecipientInput, env: ChapterEnv) => Promise<NamedSeatRefundReceipt>;
+            /** A verified super admin refunds one purchased seat; never automatic. */
+            operatorRefund: (input: MembershipQuoteTarget & {
+                seatId: string;
+            }, env: ChapterEnv) => Promise<NamedSeatRefundReceipt>;
         };
     } | undefined;
+    membershipAuthorityOperator: {
+        makeDb: (env: ChapterEnv) => ChapterDb;
+        stripeSecretName?: string;
+    } | undefined;
     getPublicConfig: (env: ChapterEnv) => Promise<PublicConfig>;
     verifyUser: (req: Request, env: ChapterEnv) => Promise<Verified | null>;
     makeDb: (env: ChapterEnv) => Db;
@@ -1279,6 +1363,21 @@ declare function createMembershipAuthorityHandler(options: MembershipAuthorityHa
  */
 declare function createMembershipAuthorityStorage(db: ChapterDb, secretNames: readonly string[]): ChapterDb;
 
+/** Identity of one purchased seat inside its exact network scope. */
+type NamedSeatOperatorRefundInput = MembershipQuoteTarget & {
+    seatId: string;
+};
+/** Refund one purchased named seat because a verified super admin decided to.
+ * Nothing here is automatic or time-driven: the caller has already authenticated
+ * the operator on the chapter or on the network owner. The primary subscription
+ * is never canceled; an accepted recipient loses access through the durable
+ * revoke effect, and a replay after the refund is idempotent.
+ */
+declare function refundNamedSeatByOperator(db: ChapterDb, input: NamedSeatOperatorRefundInput, stripeSecretKey: string, now: number): Promise<NamedSeatRefundReceipt>;
+
+/** Reasons a purchased seat may be refunded. No reason is time-driven: an unaccepted seat waits for a person. */
+type NamedSeatRefundReason = "declined" | "operator" | "primary_closed" | "provider_refund";
+
 type Row = Record<string, unknown>;
 /** Host routes may reuse this gate after resolving a verified chapter/runtime account. */
 declare function chapterMembershipAccess(db: ChapterDb, env: ChapterEnv, ctx: WorkerContext, app: Row): Promise<boolean>;
@@ -1897,4 +1996,4 @@ declare function chapterWorker(options: ChapterWorkerOptions): {
     fetch(req: Request, env: ChapterEnv): Promise<Response>;
 };
 
-export { type ActiveSignupControlHtml, type ActiveSignupControlThemeOptions, AdmissionGrantDeliveryError, type AdmissionGrantDeliveryOptions, type BuilderLibraryDeliveryOptions, type ChapterEnv, type ChapterWorkerOptions, type LeaderAdmissionAssignment, type LeaderAdmissionDelivery, type LeaderAdmissionDeliveryStatus, MEMBERSHIP_AUTHORITY_PATH, type MemberContentDeliveryOptions, type MembershipAuthorityHandlerOptions, type MembershipAuthorityPeer, type MembershipChapterEffect, type MembershipEffectScope, type MembershipWorkerAdapter, type MembershipWorkerAdapterOptions, type NetworkTargetTransport, NetworkTargetTransportError, type Route, type SignupControlDeliveryOptions, type WorkerContext, chapterMembershipAccess, chapterWorker, createMembershipAuthorityHandler, createMembershipAuthorityStorage, createMembershipChapterEffectRoute, createMembershipWorkerAdapter, createWorkerContext, deliverAdmissionGrants, deliverBuilderLibrary, deliverMemberContent, deliverMembershipChapterEffect, deliverSignupControl, drainMembershipEffects, renderActiveSignupControlHtml, resolveNetworkTargetTransport, retryChapterApprovalEffects, retryLeaderAdmissionDeliveries, withActiveSignupControlTheme };
+export { type ActiveSignupControlHtml, type ActiveSignupControlThemeOptions, AdmissionGrantDeliveryError, type AdmissionGrantDeliveryOptions, type BuilderLibraryDeliveryOptions, type ChapterEnv, type ChapterWorkerOptions, type LeaderAdmissionAssignment, type LeaderAdmissionDelivery, type LeaderAdmissionDeliveryStatus, MEMBERSHIP_AUTHORITY_PATH, type MemberContentDeliveryOptions, type MembershipAuthorityHandlerOptions, type MembershipAuthorityPeer, type MembershipChapterEffect, type MembershipEffectScope, type MembershipWorkerAdapter, type MembershipWorkerAdapterOptions, type NamedSeatOperatorRefundInput, type NamedSeatRefundReason, type NetworkTargetTransport, NetworkTargetTransportError, type Route, type SignupControlDeliveryOptions, type WorkerContext, chapterMembershipAccess, chapterWorker, createMembershipAuthorityHandler, createMembershipAuthorityStorage, createMembershipChapterEffectRoute, createMembershipWorkerAdapter, createWorkerContext, deliverAdmissionGrants, deliverBuilderLibrary, deliverMemberContent, deliverMembershipChapterEffect, deliverSignupControl, drainMembershipEffects, refundNamedSeatByOperator, renderActiveSignupControlHtml, resolveNetworkTargetTransport, retryChapterApprovalEffects, retryLeaderAdmissionDeliveries, withActiveSignupControlTheme };