@odla-ai/chapter 0.52.1 → 0.54.0

package/dist/worker/index.d.cts

@@ -847,6 +847,8 @@ interface MembershipOfferingVersion {
     };
     autoRenew: true;
     paymentGraceDays: number;
+    /** Price of the one named additional seat, in cents. `0` means the membership includes the seat: it is granted
+     * without a provider payment or renewal line, and still needs a named recipient, acceptance and approval. */
     seatPriceCents: number;
     /** Calendar months after the initial payment during which a seat may be bought. Absent: no window; a seat
      * may be bought whenever the primary membership is paid and active, renewals included. */
@@ -1007,6 +1009,55 @@ interface MembershipAccessReceipt {
     restartEligible?: boolean;
 }
 
+/** The adapter verifies the purchaser session and supplies its canonical email and the configured seat Price. */
+interface ReserveNamedMembershipSeatInput extends MembershipQuoteTarget {
+    recipientName: string;
+    recipientEmail: string;
+    purchaserEmail: string;
+    purchaserUserId: string;
+    priceId: string;
+}
+
+/** A seat the frozen offering prices at zero: the membership includes it, so it has no provider payment and no renewal line. */
+declare const namedSeatIncluded: (seat: {
+    amountCents?: unknown;
+}) => boolean;
+/** Where the named recipient stands, from the purchaser's side, folded from the seat's lifecycle status. */
+type NamedSeatRecipientState = "payment_pending" | "invited" | "accepted" | "joined" | "declined" | "refunded" | "canceled";
+/** Fold the seat status machine into the words a members page needs: whether the person was invited, accepted, joined or left. */
+declare function namedSeatRecipientState(seat: {
+    status?: unknown;
+    refundReason?: unknown;
+}): NamedSeatRecipientState;
+/** Receipt for a seat the membership includes; there is no PaymentIntent to confirm and nothing for a card to pay. */
+interface IncludedNamedSeatReceipt {
+    seatId: string;
+    amountCents: 0;
+    currency: string;
+    termEndsAt: number;
+    status: string;
+    included: true;
+}
+/** Grant the one included seat: reserve it, then move it straight to `pending_acceptance` with its entitlement and the
+ * invitation effect, exactly where a paid seat lands after payment and renewal attachment. No provider object is created,
+ * so nothing renews separately: the seat co-terminates with the primary through the renewal authority. Replays converge. */
+declare function grantIncludedNamedSeat(db: ChapterDb, input: ReserveNamedMembershipSeatInput, now: number): Promise<IncludedNamedSeatReceipt>;
+
+/** The purchaser's one named seat as the members page shows it: who was named, and whether they accepted or joined. */
+interface NamedSeatOfferSeat {
+    seatId: string;
+    status: string;
+    recipientName: string;
+    recipientEmail: string;
+    /** The recipient's standing from the purchaser's side; `joined` means the seat is active and the recipient is a member. */
+    recipientState: NamedSeatRecipientState;
+    /** When the seat was paid for or, for an included seat, granted. */
+    purchasedAt?: number;
+    /** When the named recipient accepted the invitation with their own account. */
+    acceptedAt?: number;
+    /** When the recipient's own application was approved; the seat is active from then, once the primary is. */
+    joinedAt?: number;
+}
 /** Named-seat offer for the authenticated purchaser, not a transferable gift or arbitrary quantity. */
 interface NamedSeatOffer {
     membershipId: string;
@@ -1018,15 +1069,14 @@ interface NamedSeatOffer {
     autoRenew: boolean;
     eligible: boolean;
     digest: string;
+    /** True when the frozen offering prices the seat at zero: the membership includes it, and checkout charges no card. */
+    included: boolean;
     /** False when the frozen offering sets no purchase window: seats may be bought for as long as the membership is paid. */
     purchaseWindowed?: boolean;
-    seat?: {
-        seatId: string;
-        status: string;
-        recipientName: string;
-        recipientEmail: string;
-    };
+    seat?: NamedSeatOfferSeat;
 }
+/** Read the frozen offering and any existing seat without reserving or charging anything. */
+declare function readNamedSeatOffer(db: ChapterDb, input: MembershipQuoteTarget, now: number): Promise<NamedSeatOffer>;
 
 /** Identity attested by the recipient's chapter after checking Clerk's verified primary email. */
 interface NamedSeatInvitationRequest {
@@ -1107,12 +1157,15 @@ type MembershipOfferPreviewScope = Pick<RequestMembershipOfferOptions, "appId" |
 /** Only the named buyer's prepared payment details; no network credentials or canonical PII. */
 interface NamedSeatCheckoutReceipt {
     seatId: string;
-    paymentIntentId: string;
-    clientSecret: string;
     amountCents: number;
     currency: string;
     termEndsAt: number;
     status: string;
+    /** Present for a priced seat: the PaymentIntent the purchaser's card confirms. Absent for an included seat. */
+    paymentIntentId?: string;
+    clientSecret?: string;
+    /** True when the membership includes the seat: it was granted at checkout and no card is charged. */
+    included?: true;
 }
 /** Result of attesting one verified recipient's acceptance or completed Journey. */
 interface NamedSeatRecipientReceipt {
@@ -1414,9 +1467,63 @@ type NamedSeatOperatorRefundInput = MembershipQuoteTarget & {
  */
 declare function refundNamedSeatByOperator(db: ChapterDb, input: NamedSeatOperatorRefundInput, stripeSecretKey: string, now: number): Promise<NamedSeatRefundReceipt>;
 
+/** Why one membership was left as it was. `would_not_widen` is the only-widens rule: the version would raise the renewal. */
+type MembershipRetermSkipReason = "not_found" | "scope_mismatch" | "status" | "not_founding" | "cohort_mismatch" | "sku_not_discounted" | "would_not_widen" | "provider_mismatch";
+/** What a re-term run did, member by member. Everything a super admin needs to read back is here; nothing is inferred later. */
+interface MembershipRetermReceipt {
+    policyVersionId: string;
+    retermed: {
+        membershipId: string;
+        previousPolicyVersionId?: string;
+        previousRenewalAmountCents: number;
+        renewalAmountCents: number;
+        providerUpdated: boolean;
+    }[];
+    /** Already frozen on this version; nothing was read from or written to the provider. */
+    unchanged: string[];
+    skipped: {
+        membershipId: string;
+        reason: MembershipRetermSkipReason;
+    }[];
+    more: boolean;
+}
+/** Which memberships to move: every member in scope (bounded), or the named ones. */
+interface MembershipRetermInput {
+    policyVersionId: string;
+    membershipIds?: string[];
+    limit?: number;
+}
+/** Move already-paid memberships onto a later discount policy version of the same cohort, so their next renewal carries
+ * its while-active benefit. Only ever widens: a version that would raise a member's renewal is skipped, and a lapsed,
+ * refunded, canceled, declined or restarting purchase is never revived. The provider is written first and the frozen row
+ * second, under the row's revision, so a run that dies between the two is completed by running it again. Bounded. */
+declare function retermMembershipDiscount(db: ChapterDb, stripeSecretKey: string, scope: MembershipEffectScope, input: MembershipRetermInput, now: number): Promise<MembershipRetermReceipt>;
+
 /** 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";
 
+/** Scope of one reprice: a chapter's memberships of one SKU inside one exact runtime. */
+type SeatRepriceScope = MembershipEffectScope & {
+    skuId: string;
+};
+/** What one bounded run did: memberships whose frozen seat price came down, and those left alone with the reason. */
+interface SeatRepriceReceipt {
+    seatPriceCents: number;
+    repriced: number;
+    skipped: Array<{
+        membershipId: string;
+        reason: string;
+    }>;
+    more: boolean;
+}
+/** Lower the frozen seat price on a chapter's existing memberships of one SKU to what the SKU's current published
+ * offering carries (`0` makes the seat included), so a member who paid before the change gets the new terms without
+ * a new purchase. It only ever lowers, never raises: a frozen price at or below the current one, a seat already paid
+ * for or in provider flight, and a lapsed or closed membership are left alone and named in the receipt. An unpaid,
+ * never-started reservation follows the membership, so its checkout charges the new amount. Bounded and repeatable;
+ * each row is fenced by revision. */
+declare function lowerSeatPrice(db: ChapterDb, scope: SeatRepriceScope, now: number, limit?: number): Promise<SeatRepriceReceipt>;
+
 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>;
@@ -2038,4 +2145,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 ChapterErrorRecorder, type ChapterErrorReport, 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 };
+export { type ActiveSignupControlHtml, type ActiveSignupControlThemeOptions, AdmissionGrantDeliveryError, type AdmissionGrantDeliveryOptions, type BuilderLibraryDeliveryOptions, type ChapterEnv, type ChapterErrorRecorder, type ChapterErrorReport, type ChapterWorkerOptions, type IncludedNamedSeatReceipt, type LeaderAdmissionAssignment, type LeaderAdmissionDelivery, type LeaderAdmissionDeliveryStatus, MEMBERSHIP_AUTHORITY_PATH, type MemberContentDeliveryOptions, type MembershipAuthorityHandlerOptions, type MembershipAuthorityPeer, type MembershipChapterEffect, type MembershipEffectScope, type MembershipRetermInput, type MembershipRetermReceipt, type MembershipRetermSkipReason, type MembershipWorkerAdapter, type MembershipWorkerAdapterOptions, type NamedSeatOffer, type NamedSeatOfferSeat, type NamedSeatOperatorRefundInput, type NamedSeatRecipientState, type NamedSeatRefundReason, type NetworkTargetTransport, NetworkTargetTransportError, type Route, type SeatRepriceReceipt, type SeatRepriceScope, type SignupControlDeliveryOptions, type WorkerContext, chapterMembershipAccess, chapterWorker, createMembershipAuthorityHandler, createMembershipAuthorityStorage, createMembershipChapterEffectRoute, createMembershipWorkerAdapter, createWorkerContext, deliverAdmissionGrants, deliverBuilderLibrary, deliverMemberContent, deliverMembershipChapterEffect, deliverSignupControl, drainMembershipEffects, grantIncludedNamedSeat, lowerSeatPrice, namedSeatIncluded, namedSeatRecipientState, readNamedSeatOffer, refundNamedSeatByOperator, renderActiveSignupControlHtml, resolveNetworkTargetTransport, retermMembershipDiscount, retryChapterApprovalEffects, retryLeaderAdmissionDeliveries, withActiveSignupControlTheme };

package/dist/worker/index.d.ts

@@ -847,6 +847,8 @@ interface MembershipOfferingVersion {
     };
     autoRenew: true;
     paymentGraceDays: number;
+    /** Price of the one named additional seat, in cents. `0` means the membership includes the seat: it is granted
+     * without a provider payment or renewal line, and still needs a named recipient, acceptance and approval. */
     seatPriceCents: number;
     /** Calendar months after the initial payment during which a seat may be bought. Absent: no window; a seat
      * may be bought whenever the primary membership is paid and active, renewals included. */
@@ -1007,6 +1009,55 @@ interface MembershipAccessReceipt {
     restartEligible?: boolean;
 }
 
+/** The adapter verifies the purchaser session and supplies its canonical email and the configured seat Price. */
+interface ReserveNamedMembershipSeatInput extends MembershipQuoteTarget {
+    recipientName: string;
+    recipientEmail: string;
+    purchaserEmail: string;
+    purchaserUserId: string;
+    priceId: string;
+}
+
+/** A seat the frozen offering prices at zero: the membership includes it, so it has no provider payment and no renewal line. */
+declare const namedSeatIncluded: (seat: {
+    amountCents?: unknown;
+}) => boolean;
+/** Where the named recipient stands, from the purchaser's side, folded from the seat's lifecycle status. */
+type NamedSeatRecipientState = "payment_pending" | "invited" | "accepted" | "joined" | "declined" | "refunded" | "canceled";
+/** Fold the seat status machine into the words a members page needs: whether the person was invited, accepted, joined or left. */
+declare function namedSeatRecipientState(seat: {
+    status?: unknown;
+    refundReason?: unknown;
+}): NamedSeatRecipientState;
+/** Receipt for a seat the membership includes; there is no PaymentIntent to confirm and nothing for a card to pay. */
+interface IncludedNamedSeatReceipt {
+    seatId: string;
+    amountCents: 0;
+    currency: string;
+    termEndsAt: number;
+    status: string;
+    included: true;
+}
+/** Grant the one included seat: reserve it, then move it straight to `pending_acceptance` with its entitlement and the
+ * invitation effect, exactly where a paid seat lands after payment and renewal attachment. No provider object is created,
+ * so nothing renews separately: the seat co-terminates with the primary through the renewal authority. Replays converge. */
+declare function grantIncludedNamedSeat(db: ChapterDb, input: ReserveNamedMembershipSeatInput, now: number): Promise<IncludedNamedSeatReceipt>;
+
+/** The purchaser's one named seat as the members page shows it: who was named, and whether they accepted or joined. */
+interface NamedSeatOfferSeat {
+    seatId: string;
+    status: string;
+    recipientName: string;
+    recipientEmail: string;
+    /** The recipient's standing from the purchaser's side; `joined` means the seat is active and the recipient is a member. */
+    recipientState: NamedSeatRecipientState;
+    /** When the seat was paid for or, for an included seat, granted. */
+    purchasedAt?: number;
+    /** When the named recipient accepted the invitation with their own account. */
+    acceptedAt?: number;
+    /** When the recipient's own application was approved; the seat is active from then, once the primary is. */
+    joinedAt?: number;
+}
 /** Named-seat offer for the authenticated purchaser, not a transferable gift or arbitrary quantity. */
 interface NamedSeatOffer {
     membershipId: string;
@@ -1018,15 +1069,14 @@ interface NamedSeatOffer {
     autoRenew: boolean;
     eligible: boolean;
     digest: string;
+    /** True when the frozen offering prices the seat at zero: the membership includes it, and checkout charges no card. */
+    included: boolean;
     /** False when the frozen offering sets no purchase window: seats may be bought for as long as the membership is paid. */
     purchaseWindowed?: boolean;
-    seat?: {
-        seatId: string;
-        status: string;
-        recipientName: string;
-        recipientEmail: string;
-    };
+    seat?: NamedSeatOfferSeat;
 }
+/** Read the frozen offering and any existing seat without reserving or charging anything. */
+declare function readNamedSeatOffer(db: ChapterDb, input: MembershipQuoteTarget, now: number): Promise<NamedSeatOffer>;
 
 /** Identity attested by the recipient's chapter after checking Clerk's verified primary email. */
 interface NamedSeatInvitationRequest {
@@ -1107,12 +1157,15 @@ type MembershipOfferPreviewScope = Pick<RequestMembershipOfferOptions, "appId" |
 /** Only the named buyer's prepared payment details; no network credentials or canonical PII. */
 interface NamedSeatCheckoutReceipt {
     seatId: string;
-    paymentIntentId: string;
-    clientSecret: string;
     amountCents: number;
     currency: string;
     termEndsAt: number;
     status: string;
+    /** Present for a priced seat: the PaymentIntent the purchaser's card confirms. Absent for an included seat. */
+    paymentIntentId?: string;
+    clientSecret?: string;
+    /** True when the membership includes the seat: it was granted at checkout and no card is charged. */
+    included?: true;
 }
 /** Result of attesting one verified recipient's acceptance or completed Journey. */
 interface NamedSeatRecipientReceipt {
@@ -1414,9 +1467,63 @@ type NamedSeatOperatorRefundInput = MembershipQuoteTarget & {
  */
 declare function refundNamedSeatByOperator(db: ChapterDb, input: NamedSeatOperatorRefundInput, stripeSecretKey: string, now: number): Promise<NamedSeatRefundReceipt>;
 
+/** Why one membership was left as it was. `would_not_widen` is the only-widens rule: the version would raise the renewal. */
+type MembershipRetermSkipReason = "not_found" | "scope_mismatch" | "status" | "not_founding" | "cohort_mismatch" | "sku_not_discounted" | "would_not_widen" | "provider_mismatch";
+/** What a re-term run did, member by member. Everything a super admin needs to read back is here; nothing is inferred later. */
+interface MembershipRetermReceipt {
+    policyVersionId: string;
+    retermed: {
+        membershipId: string;
+        previousPolicyVersionId?: string;
+        previousRenewalAmountCents: number;
+        renewalAmountCents: number;
+        providerUpdated: boolean;
+    }[];
+    /** Already frozen on this version; nothing was read from or written to the provider. */
+    unchanged: string[];
+    skipped: {
+        membershipId: string;
+        reason: MembershipRetermSkipReason;
+    }[];
+    more: boolean;
+}
+/** Which memberships to move: every member in scope (bounded), or the named ones. */
+interface MembershipRetermInput {
+    policyVersionId: string;
+    membershipIds?: string[];
+    limit?: number;
+}
+/** Move already-paid memberships onto a later discount policy version of the same cohort, so their next renewal carries
+ * its while-active benefit. Only ever widens: a version that would raise a member's renewal is skipped, and a lapsed,
+ * refunded, canceled, declined or restarting purchase is never revived. The provider is written first and the frozen row
+ * second, under the row's revision, so a run that dies between the two is completed by running it again. Bounded. */
+declare function retermMembershipDiscount(db: ChapterDb, stripeSecretKey: string, scope: MembershipEffectScope, input: MembershipRetermInput, now: number): Promise<MembershipRetermReceipt>;
+
 /** 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";
 
+/** Scope of one reprice: a chapter's memberships of one SKU inside one exact runtime. */
+type SeatRepriceScope = MembershipEffectScope & {
+    skuId: string;
+};
+/** What one bounded run did: memberships whose frozen seat price came down, and those left alone with the reason. */
+interface SeatRepriceReceipt {
+    seatPriceCents: number;
+    repriced: number;
+    skipped: Array<{
+        membershipId: string;
+        reason: string;
+    }>;
+    more: boolean;
+}
+/** Lower the frozen seat price on a chapter's existing memberships of one SKU to what the SKU's current published
+ * offering carries (`0` makes the seat included), so a member who paid before the change gets the new terms without
+ * a new purchase. It only ever lowers, never raises: a frozen price at or below the current one, a seat already paid
+ * for or in provider flight, and a lapsed or closed membership are left alone and named in the receipt. An unpaid,
+ * never-started reservation follows the membership, so its checkout charges the new amount. Bounded and repeatable;
+ * each row is fenced by revision. */
+declare function lowerSeatPrice(db: ChapterDb, scope: SeatRepriceScope, now: number, limit?: number): Promise<SeatRepriceReceipt>;
+
 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>;
@@ -2038,4 +2145,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 ChapterErrorRecorder, type ChapterErrorReport, 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 };
+export { type ActiveSignupControlHtml, type ActiveSignupControlThemeOptions, AdmissionGrantDeliveryError, type AdmissionGrantDeliveryOptions, type BuilderLibraryDeliveryOptions, type ChapterEnv, type ChapterErrorRecorder, type ChapterErrorReport, type ChapterWorkerOptions, type IncludedNamedSeatReceipt, type LeaderAdmissionAssignment, type LeaderAdmissionDelivery, type LeaderAdmissionDeliveryStatus, MEMBERSHIP_AUTHORITY_PATH, type MemberContentDeliveryOptions, type MembershipAuthorityHandlerOptions, type MembershipAuthorityPeer, type MembershipChapterEffect, type MembershipEffectScope, type MembershipRetermInput, type MembershipRetermReceipt, type MembershipRetermSkipReason, type MembershipWorkerAdapter, type MembershipWorkerAdapterOptions, type NamedSeatOffer, type NamedSeatOfferSeat, type NamedSeatOperatorRefundInput, type NamedSeatRecipientState, type NamedSeatRefundReason, type NetworkTargetTransport, NetworkTargetTransportError, type Route, type SeatRepriceReceipt, type SeatRepriceScope, type SignupControlDeliveryOptions, type WorkerContext, chapterMembershipAccess, chapterWorker, createMembershipAuthorityHandler, createMembershipAuthorityStorage, createMembershipChapterEffectRoute, createMembershipWorkerAdapter, createWorkerContext, deliverAdmissionGrants, deliverBuilderLibrary, deliverMemberContent, deliverMembershipChapterEffect, deliverSignupControl, drainMembershipEffects, grantIncludedNamedSeat, lowerSeatPrice, namedSeatIncluded, namedSeatRecipientState, readNamedSeatOffer, refundNamedSeatByOperator, renderActiveSignupControlHtml, resolveNetworkTargetTransport, retermMembershipDiscount, retryChapterApprovalEffects, retryLeaderAdmissionDeliveries, withActiveSignupControlTheme };