@odla-ai/chapter 0.58.0 → 0.59.0

package/dist/worker/index.d.cts

@@ -1,6 +1,11 @@
 import { CrmConfig, Crm, FieldConditions } from '@odla-ai/crm';
 import { initAdmin } from '@odla-ai/db';
 
+/** The part of a Workers ExecutionContext a chapter route needs: let work outlive the response. */
+interface ExecutionLike {
+    waitUntil(promise: Promise<unknown>): void;
+}
+
 /** One membership tier a chapter offers. `priceCents: 0` means free. */
 interface ChapterTier {
     /** Stable slug, referenced by `applications.tierId`. Never renumbered. */
@@ -83,6 +88,10 @@ interface ChapterCopy {
         booking: TextFields<"unavailable" | "loadFailed" | "slotTaken" | "failed" | "loading" | "book" | "booking"> & {
             title?: string;
             intro?: string;
+            /** Shown under the booking button until a date is chosen. */
+            pickDate?: string;
+            /** Shown under the booking button once a date is chosen, until a time is. */
+            pickTime?: string;
         };
         /**
          * `consent` is the affirmative statement a member agrees to before the card
@@ -1493,6 +1502,8 @@ declare function createWorkerContext(options: ChapterWorkerOptions): {
         stripeSecretName?: string;
     } | undefined;
     recordError: ChapterErrorRecorder;
+    bindExecution: (req: Request, execution: ExecutionLike | undefined) => void;
+    defer: (req: Request, task: () => Promise<unknown>) => Promise<void>;
     getPublicConfig: (env: ChapterEnv) => Promise<PublicConfig>;
     verifyUser: (req: Request, env: ChapterEnv) => Promise<Verified | null>;
     makeDb: (env: ChapterEnv) => Db;
@@ -1564,6 +1575,55 @@ type NamedSeatOperatorRefundInput = MembershipQuoteTarget & {
  */
 declare function refundNamedSeatByOperator(db: ChapterDb, input: NamedSeatOperatorRefundInput, stripeSecretKey: string, now: number): Promise<NamedSeatRefundReceipt>;
 
+/** Membership status while a card-network dispute has the payment pulled back. Access is refused until the dispute is won
+ * or an operator re-issues the charge. */
+declare const MEMBERSHIP_DISPUTED_STATUS = "payment_disputed";
+/** The charge a dispute names, read from Stripe so a webhook body never chooses which membership it touches. */
+interface DisputedCharge {
+    chargeId: string;
+    customerId: string;
+    invoiceId?: string;
+    subscriptionId?: string;
+    paymentIntentId?: string;
+    /** Present when the charge paid a named seat; the primary membership is then not the disputed purchase. */
+    seatId?: string;
+}
+/** Billing receipt plus the dispute's current standing and whether this event changed anything. */
+interface MembershipDisputeReceipt extends MembershipRenewalReceipt {
+    disputeStatus?: string;
+    applied: boolean;
+}
+/** Resolve the disputed charge, and the subscription behind its invoice, with the network's own Stripe credential. */
+declare function readDisputedCharge(secretKey: string, chargeId: string, fetch?: typeof globalThis.fetch): Promise<DisputedCharge>;
+/** Apply one verified `charge.dispute.*` fact to the membership it names. An open dispute suspends access; a won dispute
+ * restores the status it interrupted; a lost one leaves the membership suspended until an operator re-issues the charge.
+ * Idempotent per event, a closed dispute outranks a late opening event, and a charge that is not this membership's
+ * (a seat, another purchase) changes nothing. */
+declare function reconcileMembershipDispute(db: ChapterDb, input: MembershipQuoteTarget & {
+    eventId: string;
+}, now: number, secretKey: string, resolved?: DisputedCharge): Promise<MembershipDisputeReceipt>;
+
+/** What an operator sees after asking the network to collect a lost dispute's amount again. */
+interface MembershipRechargeReceipt {
+    membershipId: string;
+    status: string;
+    paymentIntentId: string;
+    amountCents: number;
+    currency: string;
+    replayed?: true;
+}
+/** Stripe's final answer to a re-issued charge, with the decline code when the card refused it. */
+interface MembershipRechargeError extends Error {
+    code: string;
+    declineCode?: string;
+    paymentStatus?: string;
+}
+/** Collect a lost dispute's amount again on the member's saved card, because an operator decided to after the member cleared the
+ * report with their bank. Never automatic. One idempotency key lives on the row until Stripe answers, so a lost response cannot
+ * charge twice; a declined card ends the attempt so the next click starts a fresh one. Success restores the status the dispute
+ * interrupted. */
+declare function rechargeDisputedMembership(db: ChapterDb, membershipId: string, secretKey: string, now: number): Promise<MembershipRechargeReceipt>;
+
 /** Seat states in which the purchaser may still name someone else: invited or accepted, never active, refunded or unpaid. */
 declare const REGIFTABLE_SEAT_STATUSES: readonly ["pending_acceptance", "pending_approval", "pending_primary"];
 /** Whether a seat may be given to a different recipient (BNF bug 38000934): final once active. */
@@ -2332,7 +2392,9 @@ declare function withActiveSignupControlTheme(response: Response, options: Activ
  * keep those alerts as structured `console.error` lines.
  */
 declare function chapterWorker(options: ChapterWorkerOptions): {
-    fetch(req: Request, env: ChapterEnv): Promise<Response>;
+    fetch(req: Request, env: ChapterEnv, execution?: {
+        waitUntil(promise: Promise<unknown>): void;
+    }): Promise<Response>;
 };
 
-export { type ActiveSignupControlHtml, type ActiveSignupControlThemeOptions, AdmissionGrantDeliveryError, type AdmissionGrantDeliveryOptions, type BuilderLibraryDeliveryOptions, type ChapterEnv, type ChapterErrorRecorder, type ChapterErrorReport, type ChapterWorkerOptions, DECLINABLE_FROM, type FormerNamedSeatRecipient, type IncludedNamedSeatReceipt, type LeaderAdmissionAssignment, type LeaderAdmissionDelivery, type LeaderAdmissionDeliveryStatus, MEMBERSHIP_AUTHORITY_PATH, MEMBERSHIP_CHAPTER_EFFECT_KINDS, type MemberContentDeliveryOptions, type MembershipAuthorityHandlerOptions, type MembershipAuthorityPeer, type MembershipChapterEffect, type MembershipChapterEffectKind, type MembershipEffectScope, type MembershipRetermInput, type MembershipRetermReceipt, type MembershipRetermSkipReason, type MembershipWorkerAdapter, type MembershipWorkerAdapterOptions, type NamedSeatOffer, type NamedSeatOfferSeat, type NamedSeatOperatorRefundInput, type NamedSeatRecipientState, type NamedSeatRefundReason, type NamedSeatRegiftReceipt, type NamedSeatReleaseInput, type NetworkTargetTransport, NetworkTargetTransportError, REGIFTABLE_SEAT_STATUSES, type RegiftNamedSeatInput, type Route, type SeatRepriceReceipt, type SeatRepriceScope, type SignupControlDeliveryOptions, type SignupEligibility, type SignupPredecessor, type WorkerContext, chapterMembershipAccess, chapterWorker, closedApplication, continueApplicationOnFreeTier, createMembershipAuthorityHandler, createMembershipAuthorityStorage, createMembershipChapterEffectRoute, createMembershipWorkerAdapter, createWorkerContext, declineApplication, deliverAdmissionGrants, deliverBuilderLibrary, deliverMemberContent, deliverMembershipChapterEffect, deliverSignupControl, drainMembershipEffects, grantIncludedNamedSeat, liftSeatPurchaseWindow, lowerSeatPrice, namedSeatIncluded, namedSeatInvitationOpen, namedSeatRecipientState, namedSeatRegiftable, readNamedSeatOffer, refundNamedSeatByOperator, regiftNamedSeat, releaseNamedSeatRecipientApplications, renderActiveSignupControlHtml, resolveNetworkTargetTransport, resolveSignupEligibility, retermMembershipDiscount, retryChapterApprovalEffects, retryLeaderAdmissionDeliveries, withActiveSignupControlTheme };
+export { type ActiveSignupControlHtml, type ActiveSignupControlThemeOptions, AdmissionGrantDeliveryError, type AdmissionGrantDeliveryOptions, type BuilderLibraryDeliveryOptions, type ChapterEnv, type ChapterErrorRecorder, type ChapterErrorReport, type ChapterWorkerOptions, DECLINABLE_FROM, type DisputedCharge, type FormerNamedSeatRecipient, type IncludedNamedSeatReceipt, type LeaderAdmissionAssignment, type LeaderAdmissionDelivery, type LeaderAdmissionDeliveryStatus, MEMBERSHIP_AUTHORITY_PATH, MEMBERSHIP_CHAPTER_EFFECT_KINDS, MEMBERSHIP_DISPUTED_STATUS, type MemberContentDeliveryOptions, type MembershipAuthorityHandlerOptions, type MembershipAuthorityPeer, type MembershipChapterEffect, type MembershipChapterEffectKind, type MembershipDisputeReceipt, type MembershipEffectScope, type MembershipRechargeError, type MembershipRechargeReceipt, type MembershipRetermInput, type MembershipRetermReceipt, type MembershipRetermSkipReason, type MembershipWorkerAdapter, type MembershipWorkerAdapterOptions, type NamedSeatOffer, type NamedSeatOfferSeat, type NamedSeatOperatorRefundInput, type NamedSeatRecipientState, type NamedSeatRefundReason, type NamedSeatRegiftReceipt, type NamedSeatReleaseInput, type NetworkTargetTransport, NetworkTargetTransportError, REGIFTABLE_SEAT_STATUSES, type RegiftNamedSeatInput, type Route, type SeatRepriceReceipt, type SeatRepriceScope, type SignupControlDeliveryOptions, type SignupEligibility, type SignupPredecessor, type WorkerContext, chapterMembershipAccess, chapterWorker, closedApplication, continueApplicationOnFreeTier, createMembershipAuthorityHandler, createMembershipAuthorityStorage, createMembershipChapterEffectRoute, createMembershipWorkerAdapter, createWorkerContext, declineApplication, deliverAdmissionGrants, deliverBuilderLibrary, deliverMemberContent, deliverMembershipChapterEffect, deliverSignupControl, drainMembershipEffects, grantIncludedNamedSeat, liftSeatPurchaseWindow, lowerSeatPrice, namedSeatIncluded, namedSeatInvitationOpen, namedSeatRecipientState, namedSeatRegiftable, readDisputedCharge, readNamedSeatOffer, rechargeDisputedMembership, reconcileMembershipDispute, refundNamedSeatByOperator, regiftNamedSeat, releaseNamedSeatRecipientApplications, renderActiveSignupControlHtml, resolveNetworkTargetTransport, resolveSignupEligibility, retermMembershipDiscount, retryChapterApprovalEffects, retryLeaderAdmissionDeliveries, withActiveSignupControlTheme };

package/dist/worker/index.d.ts

@@ -1,6 +1,11 @@
 import { CrmConfig, Crm, FieldConditions } from '@odla-ai/crm';
 import { initAdmin } from '@odla-ai/db';
 
+/** The part of a Workers ExecutionContext a chapter route needs: let work outlive the response. */
+interface ExecutionLike {
+    waitUntil(promise: Promise<unknown>): void;
+}
+
 /** One membership tier a chapter offers. `priceCents: 0` means free. */
 interface ChapterTier {
     /** Stable slug, referenced by `applications.tierId`. Never renumbered. */
@@ -83,6 +88,10 @@ interface ChapterCopy {
         booking: TextFields<"unavailable" | "loadFailed" | "slotTaken" | "failed" | "loading" | "book" | "booking"> & {
             title?: string;
             intro?: string;
+            /** Shown under the booking button until a date is chosen. */
+            pickDate?: string;
+            /** Shown under the booking button once a date is chosen, until a time is. */
+            pickTime?: string;
         };
         /**
          * `consent` is the affirmative statement a member agrees to before the card
@@ -1493,6 +1502,8 @@ declare function createWorkerContext(options: ChapterWorkerOptions): {
         stripeSecretName?: string;
     } | undefined;
     recordError: ChapterErrorRecorder;
+    bindExecution: (req: Request, execution: ExecutionLike | undefined) => void;
+    defer: (req: Request, task: () => Promise<unknown>) => Promise<void>;
     getPublicConfig: (env: ChapterEnv) => Promise<PublicConfig>;
     verifyUser: (req: Request, env: ChapterEnv) => Promise<Verified | null>;
     makeDb: (env: ChapterEnv) => Db;
@@ -1564,6 +1575,55 @@ type NamedSeatOperatorRefundInput = MembershipQuoteTarget & {
  */
 declare function refundNamedSeatByOperator(db: ChapterDb, input: NamedSeatOperatorRefundInput, stripeSecretKey: string, now: number): Promise<NamedSeatRefundReceipt>;
 
+/** Membership status while a card-network dispute has the payment pulled back. Access is refused until the dispute is won
+ * or an operator re-issues the charge. */
+declare const MEMBERSHIP_DISPUTED_STATUS = "payment_disputed";
+/** The charge a dispute names, read from Stripe so a webhook body never chooses which membership it touches. */
+interface DisputedCharge {
+    chargeId: string;
+    customerId: string;
+    invoiceId?: string;
+    subscriptionId?: string;
+    paymentIntentId?: string;
+    /** Present when the charge paid a named seat; the primary membership is then not the disputed purchase. */
+    seatId?: string;
+}
+/** Billing receipt plus the dispute's current standing and whether this event changed anything. */
+interface MembershipDisputeReceipt extends MembershipRenewalReceipt {
+    disputeStatus?: string;
+    applied: boolean;
+}
+/** Resolve the disputed charge, and the subscription behind its invoice, with the network's own Stripe credential. */
+declare function readDisputedCharge(secretKey: string, chargeId: string, fetch?: typeof globalThis.fetch): Promise<DisputedCharge>;
+/** Apply one verified `charge.dispute.*` fact to the membership it names. An open dispute suspends access; a won dispute
+ * restores the status it interrupted; a lost one leaves the membership suspended until an operator re-issues the charge.
+ * Idempotent per event, a closed dispute outranks a late opening event, and a charge that is not this membership's
+ * (a seat, another purchase) changes nothing. */
+declare function reconcileMembershipDispute(db: ChapterDb, input: MembershipQuoteTarget & {
+    eventId: string;
+}, now: number, secretKey: string, resolved?: DisputedCharge): Promise<MembershipDisputeReceipt>;
+
+/** What an operator sees after asking the network to collect a lost dispute's amount again. */
+interface MembershipRechargeReceipt {
+    membershipId: string;
+    status: string;
+    paymentIntentId: string;
+    amountCents: number;
+    currency: string;
+    replayed?: true;
+}
+/** Stripe's final answer to a re-issued charge, with the decline code when the card refused it. */
+interface MembershipRechargeError extends Error {
+    code: string;
+    declineCode?: string;
+    paymentStatus?: string;
+}
+/** Collect a lost dispute's amount again on the member's saved card, because an operator decided to after the member cleared the
+ * report with their bank. Never automatic. One idempotency key lives on the row until Stripe answers, so a lost response cannot
+ * charge twice; a declined card ends the attempt so the next click starts a fresh one. Success restores the status the dispute
+ * interrupted. */
+declare function rechargeDisputedMembership(db: ChapterDb, membershipId: string, secretKey: string, now: number): Promise<MembershipRechargeReceipt>;
+
 /** Seat states in which the purchaser may still name someone else: invited or accepted, never active, refunded or unpaid. */
 declare const REGIFTABLE_SEAT_STATUSES: readonly ["pending_acceptance", "pending_approval", "pending_primary"];
 /** Whether a seat may be given to a different recipient (BNF bug 38000934): final once active. */
@@ -2332,7 +2392,9 @@ declare function withActiveSignupControlTheme(response: Response, options: Activ
  * keep those alerts as structured `console.error` lines.
  */
 declare function chapterWorker(options: ChapterWorkerOptions): {
-    fetch(req: Request, env: ChapterEnv): Promise<Response>;
+    fetch(req: Request, env: ChapterEnv, execution?: {
+        waitUntil(promise: Promise<unknown>): void;
+    }): Promise<Response>;
 };
 
-export { type ActiveSignupControlHtml, type ActiveSignupControlThemeOptions, AdmissionGrantDeliveryError, type AdmissionGrantDeliveryOptions, type BuilderLibraryDeliveryOptions, type ChapterEnv, type ChapterErrorRecorder, type ChapterErrorReport, type ChapterWorkerOptions, DECLINABLE_FROM, type FormerNamedSeatRecipient, type IncludedNamedSeatReceipt, type LeaderAdmissionAssignment, type LeaderAdmissionDelivery, type LeaderAdmissionDeliveryStatus, MEMBERSHIP_AUTHORITY_PATH, MEMBERSHIP_CHAPTER_EFFECT_KINDS, type MemberContentDeliveryOptions, type MembershipAuthorityHandlerOptions, type MembershipAuthorityPeer, type MembershipChapterEffect, type MembershipChapterEffectKind, type MembershipEffectScope, type MembershipRetermInput, type MembershipRetermReceipt, type MembershipRetermSkipReason, type MembershipWorkerAdapter, type MembershipWorkerAdapterOptions, type NamedSeatOffer, type NamedSeatOfferSeat, type NamedSeatOperatorRefundInput, type NamedSeatRecipientState, type NamedSeatRefundReason, type NamedSeatRegiftReceipt, type NamedSeatReleaseInput, type NetworkTargetTransport, NetworkTargetTransportError, REGIFTABLE_SEAT_STATUSES, type RegiftNamedSeatInput, type Route, type SeatRepriceReceipt, type SeatRepriceScope, type SignupControlDeliveryOptions, type SignupEligibility, type SignupPredecessor, type WorkerContext, chapterMembershipAccess, chapterWorker, closedApplication, continueApplicationOnFreeTier, createMembershipAuthorityHandler, createMembershipAuthorityStorage, createMembershipChapterEffectRoute, createMembershipWorkerAdapter, createWorkerContext, declineApplication, deliverAdmissionGrants, deliverBuilderLibrary, deliverMemberContent, deliverMembershipChapterEffect, deliverSignupControl, drainMembershipEffects, grantIncludedNamedSeat, liftSeatPurchaseWindow, lowerSeatPrice, namedSeatIncluded, namedSeatInvitationOpen, namedSeatRecipientState, namedSeatRegiftable, readNamedSeatOffer, refundNamedSeatByOperator, regiftNamedSeat, releaseNamedSeatRecipientApplications, renderActiveSignupControlHtml, resolveNetworkTargetTransport, resolveSignupEligibility, retermMembershipDiscount, retryChapterApprovalEffects, retryLeaderAdmissionDeliveries, withActiveSignupControlTheme };
+export { type ActiveSignupControlHtml, type ActiveSignupControlThemeOptions, AdmissionGrantDeliveryError, type AdmissionGrantDeliveryOptions, type BuilderLibraryDeliveryOptions, type ChapterEnv, type ChapterErrorRecorder, type ChapterErrorReport, type ChapterWorkerOptions, DECLINABLE_FROM, type DisputedCharge, type FormerNamedSeatRecipient, type IncludedNamedSeatReceipt, type LeaderAdmissionAssignment, type LeaderAdmissionDelivery, type LeaderAdmissionDeliveryStatus, MEMBERSHIP_AUTHORITY_PATH, MEMBERSHIP_CHAPTER_EFFECT_KINDS, MEMBERSHIP_DISPUTED_STATUS, type MemberContentDeliveryOptions, type MembershipAuthorityHandlerOptions, type MembershipAuthorityPeer, type MembershipChapterEffect, type MembershipChapterEffectKind, type MembershipDisputeReceipt, type MembershipEffectScope, type MembershipRechargeError, type MembershipRechargeReceipt, type MembershipRetermInput, type MembershipRetermReceipt, type MembershipRetermSkipReason, type MembershipWorkerAdapter, type MembershipWorkerAdapterOptions, type NamedSeatOffer, type NamedSeatOfferSeat, type NamedSeatOperatorRefundInput, type NamedSeatRecipientState, type NamedSeatRefundReason, type NamedSeatRegiftReceipt, type NamedSeatReleaseInput, type NetworkTargetTransport, NetworkTargetTransportError, REGIFTABLE_SEAT_STATUSES, type RegiftNamedSeatInput, type Route, type SeatRepriceReceipt, type SeatRepriceScope, type SignupControlDeliveryOptions, type SignupEligibility, type SignupPredecessor, type WorkerContext, chapterMembershipAccess, chapterWorker, closedApplication, continueApplicationOnFreeTier, createMembershipAuthorityHandler, createMembershipAuthorityStorage, createMembershipChapterEffectRoute, createMembershipWorkerAdapter, createWorkerContext, declineApplication, deliverAdmissionGrants, deliverBuilderLibrary, deliverMemberContent, deliverMembershipChapterEffect, deliverSignupControl, drainMembershipEffects, grantIncludedNamedSeat, liftSeatPurchaseWindow, lowerSeatPrice, namedSeatIncluded, namedSeatInvitationOpen, namedSeatRecipientState, namedSeatRegiftable, readDisputedCharge, readNamedSeatOffer, rechargeDisputedMembership, reconcileMembershipDispute, refundNamedSeatByOperator, regiftNamedSeat, releaseNamedSeatRecipientApplications, renderActiveSignupControlHtml, resolveNetworkTargetTransport, resolveSignupEligibility, retermMembershipDiscount, retryChapterApprovalEffects, retryLeaderAdmissionDeliveries, withActiveSignupControlTheme };