@bash-app/bash-common 30.236.0 → 30.237.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (180) hide show
  1. package/dist/__tests__/statusEnums.test.js +88 -7
  2. package/dist/__tests__/statusEnums.test.js.map +1 -1
  3. package/dist/definitions.d.ts +39 -8
  4. package/dist/definitions.d.ts.map +1 -1
  5. package/dist/definitions.js +31 -10
  6. package/dist/definitions.js.map +1 -1
  7. package/dist/extendedSchemas.d.ts +6 -0
  8. package/dist/extendedSchemas.d.ts.map +1 -1
  9. package/dist/extendedSchemas.js.map +1 -1
  10. package/dist/index.d.ts +13 -1
  11. package/dist/index.d.ts.map +1 -1
  12. package/dist/index.js +16 -4
  13. package/dist/index.js.map +1 -1
  14. package/dist/mirroredPrismaEnums.d.ts +145 -0
  15. package/dist/mirroredPrismaEnums.d.ts.map +1 -0
  16. package/dist/mirroredPrismaEnums.js +136 -0
  17. package/dist/mirroredPrismaEnums.js.map +1 -0
  18. package/dist/utils/__tests__/nonprofitUtils.test.d.ts +2 -0
  19. package/dist/utils/__tests__/nonprofitUtils.test.d.ts.map +1 -0
  20. package/dist/utils/__tests__/nonprofitUtils.test.js +84 -0
  21. package/dist/utils/__tests__/nonprofitUtils.test.js.map +1 -0
  22. package/dist/utils/__tests__/paymentUtils.test.js +87 -0
  23. package/dist/utils/__tests__/paymentUtils.test.js.map +1 -1
  24. package/dist/utils/nonprofitUtils.d.ts +21 -0
  25. package/dist/utils/nonprofitUtils.d.ts.map +1 -0
  26. package/dist/utils/nonprofitUtils.js +29 -0
  27. package/dist/utils/nonprofitUtils.js.map +1 -0
  28. package/dist/utils/paymentUtils.d.ts +23 -0
  29. package/dist/utils/paymentUtils.d.ts.map +1 -1
  30. package/dist/utils/paymentUtils.js +24 -7
  31. package/dist/utils/paymentUtils.js.map +1 -1
  32. package/dist/utils/service/__tests__/billingCapUtils.test.d.ts +2 -0
  33. package/dist/utils/service/__tests__/billingCapUtils.test.d.ts.map +1 -0
  34. package/dist/utils/service/__tests__/billingCapUtils.test.js +120 -0
  35. package/dist/utils/service/__tests__/billingCapUtils.test.js.map +1 -0
  36. package/dist/utils/service/__tests__/cancellationPolicyRefundResolver.test.js +1 -1
  37. package/dist/utils/service/__tests__/cancellationPolicyRefundResolver.test.js.map +1 -1
  38. package/dist/utils/service/__tests__/eventPromoterPhase3.test.d.ts +2 -0
  39. package/dist/utils/service/__tests__/eventPromoterPhase3.test.d.ts.map +1 -0
  40. package/dist/utils/service/__tests__/eventPromoterPhase3.test.js +243 -0
  41. package/dist/utils/service/__tests__/eventPromoterPhase3.test.js.map +1 -0
  42. package/dist/utils/service/__tests__/eventPromoterUtils.test.d.ts +2 -0
  43. package/dist/utils/service/__tests__/eventPromoterUtils.test.d.ts.map +1 -0
  44. package/dist/utils/service/__tests__/eventPromoterUtils.test.js +333 -0
  45. package/dist/utils/service/__tests__/eventPromoterUtils.test.js.map +1 -0
  46. package/dist/utils/service/__tests__/offerAllowListUtils.test.d.ts +2 -0
  47. package/dist/utils/service/__tests__/offerAllowListUtils.test.d.ts.map +1 -0
  48. package/dist/utils/service/__tests__/offerAllowListUtils.test.js +52 -0
  49. package/dist/utils/service/__tests__/offerAllowListUtils.test.js.map +1 -0
  50. package/dist/utils/service/__tests__/offerComparisonUtils.test.d.ts +2 -0
  51. package/dist/utils/service/__tests__/offerComparisonUtils.test.d.ts.map +1 -0
  52. package/dist/utils/service/__tests__/offerComparisonUtils.test.js +111 -0
  53. package/dist/utils/service/__tests__/offerComparisonUtils.test.js.map +1 -0
  54. package/dist/utils/service/__tests__/serviceBookingExposureUtils.test.d.ts +2 -0
  55. package/dist/utils/service/__tests__/serviceBookingExposureUtils.test.d.ts.map +1 -0
  56. package/dist/utils/service/__tests__/serviceBookingExposureUtils.test.js +155 -0
  57. package/dist/utils/service/__tests__/serviceBookingExposureUtils.test.js.map +1 -0
  58. package/dist/utils/service/__tests__/unifiedPricingResolver.test.d.ts +2 -0
  59. package/dist/utils/service/__tests__/unifiedPricingResolver.test.d.ts.map +1 -0
  60. package/dist/utils/service/__tests__/unifiedPricingResolver.test.js +77 -0
  61. package/dist/utils/service/__tests__/unifiedPricingResolver.test.js.map +1 -0
  62. package/dist/utils/service/__tests__/venueFBSettlementUtils.test.d.ts +2 -0
  63. package/dist/utils/service/__tests__/venueFBSettlementUtils.test.d.ts.map +1 -0
  64. package/dist/utils/service/__tests__/venueFBSettlementUtils.test.js +157 -0
  65. package/dist/utils/service/__tests__/venueFBSettlementUtils.test.js.map +1 -0
  66. package/dist/utils/service/__tests__/venueSettlementUtils.test.d.ts +2 -0
  67. package/dist/utils/service/__tests__/venueSettlementUtils.test.d.ts.map +1 -0
  68. package/dist/utils/service/__tests__/venueSettlementUtils.test.js +175 -0
  69. package/dist/utils/service/__tests__/venueSettlementUtils.test.js.map +1 -0
  70. package/dist/utils/service/__tests__/volunteerCompensationUtils.test.d.ts +2 -0
  71. package/dist/utils/service/__tests__/volunteerCompensationUtils.test.d.ts.map +1 -0
  72. package/dist/utils/service/__tests__/volunteerCompensationUtils.test.js +118 -0
  73. package/dist/utils/service/__tests__/volunteerCompensationUtils.test.js.map +1 -0
  74. package/dist/utils/service/apiServiceBookingApiUtils.d.ts.map +1 -1
  75. package/dist/utils/service/apiServiceBookingApiUtils.js +4 -0
  76. package/dist/utils/service/apiServiceBookingApiUtils.js.map +1 -1
  77. package/dist/utils/service/billingCapUtils.d.ts +86 -0
  78. package/dist/utils/service/billingCapUtils.d.ts.map +1 -0
  79. package/dist/utils/service/billingCapUtils.js +96 -0
  80. package/dist/utils/service/billingCapUtils.js.map +1 -0
  81. package/dist/utils/service/cancellationPolicyRefundResolver.d.ts +1 -1
  82. package/dist/utils/service/cancellationPolicyRefundResolver.d.ts.map +1 -1
  83. package/dist/utils/service/cancellationPolicyRefundResolver.js +1 -1
  84. package/dist/utils/service/cancellationPolicyRefundResolver.js.map +1 -1
  85. package/dist/utils/service/eventPromoterUtils.d.ts +319 -0
  86. package/dist/utils/service/eventPromoterUtils.d.ts.map +1 -0
  87. package/dist/utils/service/eventPromoterUtils.js +372 -0
  88. package/dist/utils/service/eventPromoterUtils.js.map +1 -0
  89. package/dist/utils/service/offerAllowListUtils.d.ts +42 -0
  90. package/dist/utils/service/offerAllowListUtils.d.ts.map +1 -0
  91. package/dist/utils/service/offerAllowListUtils.js +49 -0
  92. package/dist/utils/service/offerAllowListUtils.js.map +1 -0
  93. package/dist/utils/service/offerComparisonUtils.d.ts +69 -0
  94. package/dist/utils/service/offerComparisonUtils.d.ts.map +1 -0
  95. package/dist/utils/service/offerComparisonUtils.js +110 -0
  96. package/dist/utils/service/offerComparisonUtils.js.map +1 -0
  97. package/dist/utils/service/serviceBookingExposureUtils.d.ts +111 -0
  98. package/dist/utils/service/serviceBookingExposureUtils.d.ts.map +1 -0
  99. package/dist/utils/service/serviceBookingExposureUtils.js +133 -0
  100. package/dist/utils/service/serviceBookingExposureUtils.js.map +1 -0
  101. package/dist/utils/service/serviceBookingTypes.d.ts +1 -1
  102. package/dist/utils/service/serviceBookingTypes.d.ts.map +1 -1
  103. package/dist/utils/service/serviceUtils.d.ts +2 -1
  104. package/dist/utils/service/serviceUtils.d.ts.map +1 -1
  105. package/dist/utils/service/serviceUtils.js +17 -16
  106. package/dist/utils/service/serviceUtils.js.map +1 -1
  107. package/dist/utils/service/unifiedPricingResolver.d.ts +67 -0
  108. package/dist/utils/service/unifiedPricingResolver.d.ts.map +1 -0
  109. package/dist/utils/service/unifiedPricingResolver.js +75 -0
  110. package/dist/utils/service/unifiedPricingResolver.js.map +1 -0
  111. package/dist/utils/service/venueFBSettlementUtils.d.ts +122 -0
  112. package/dist/utils/service/venueFBSettlementUtils.d.ts.map +1 -0
  113. package/dist/utils/service/venueFBSettlementUtils.js +106 -0
  114. package/dist/utils/service/venueFBSettlementUtils.js.map +1 -0
  115. package/dist/utils/service/venueSettlementUtils.d.ts +107 -0
  116. package/dist/utils/service/venueSettlementUtils.d.ts.map +1 -0
  117. package/dist/utils/service/venueSettlementUtils.js +117 -0
  118. package/dist/utils/service/venueSettlementUtils.js.map +1 -0
  119. package/dist/utils/service/volunteerCompensationUtils.d.ts +75 -0
  120. package/dist/utils/service/volunteerCompensationUtils.d.ts.map +1 -0
  121. package/dist/utils/service/volunteerCompensationUtils.js +88 -0
  122. package/dist/utils/service/volunteerCompensationUtils.js.map +1 -0
  123. package/dist/utils/venueLoyalty/__tests__/eligibilityUtils.test.d.ts +2 -0
  124. package/dist/utils/venueLoyalty/__tests__/eligibilityUtils.test.d.ts.map +1 -0
  125. package/dist/utils/venueLoyalty/__tests__/eligibilityUtils.test.js +67 -0
  126. package/dist/utils/venueLoyalty/__tests__/eligibilityUtils.test.js.map +1 -0
  127. package/dist/utils/venueLoyalty/__tests__/redemptionCodeUtils.test.d.ts +2 -0
  128. package/dist/utils/venueLoyalty/__tests__/redemptionCodeUtils.test.d.ts.map +1 -0
  129. package/dist/utils/venueLoyalty/__tests__/redemptionCodeUtils.test.js +71 -0
  130. package/dist/utils/venueLoyalty/__tests__/redemptionCodeUtils.test.js.map +1 -0
  131. package/dist/utils/venueLoyalty/eligibilityUtils.d.ts +33 -0
  132. package/dist/utils/venueLoyalty/eligibilityUtils.d.ts.map +1 -0
  133. package/dist/utils/venueLoyalty/eligibilityUtils.js +49 -0
  134. package/dist/utils/venueLoyalty/eligibilityUtils.js.map +1 -0
  135. package/dist/utils/venueLoyalty/redemptionCodeUtils.d.ts +35 -0
  136. package/dist/utils/venueLoyalty/redemptionCodeUtils.d.ts.map +1 -0
  137. package/dist/utils/venueLoyalty/redemptionCodeUtils.js +74 -0
  138. package/dist/utils/venueLoyalty/redemptionCodeUtils.js.map +1 -0
  139. package/dist/venueLoyaltyRedemption.d.ts +146 -1
  140. package/dist/venueLoyaltyRedemption.d.ts.map +1 -1
  141. package/dist/venueLoyaltyRedemption.js +18 -2
  142. package/dist/venueLoyaltyRedemption.js.map +1 -1
  143. package/package.json +1 -1
  144. package/prisma/schema.prisma +609 -214
  145. package/src/__tests__/statusEnums.test.ts +119 -11
  146. package/src/definitions.ts +57 -14
  147. package/src/extendedSchemas.ts +6 -0
  148. package/src/index.ts +16 -6
  149. package/src/mirroredPrismaEnums.ts +181 -0
  150. package/src/utils/__tests__/nonprofitUtils.test.ts +117 -0
  151. package/src/utils/__tests__/paymentUtils.test.ts +93 -0
  152. package/src/utils/nonprofitUtils.ts +44 -0
  153. package/src/utils/paymentUtils.ts +33 -7
  154. package/src/utils/service/__tests__/billingCapUtils.test.ts +175 -0
  155. package/src/utils/service/__tests__/cancellationPolicyRefundResolver.test.ts +1 -1
  156. package/src/utils/service/__tests__/eventPromoterPhase3.test.ts +296 -0
  157. package/src/utils/service/__tests__/eventPromoterUtils.test.ts +396 -0
  158. package/src/utils/service/__tests__/offerAllowListUtils.test.ts +76 -0
  159. package/src/utils/service/__tests__/offerComparisonUtils.test.ts +124 -0
  160. package/src/utils/service/__tests__/serviceBookingExposureUtils.test.ts +171 -0
  161. package/src/utils/service/__tests__/unifiedPricingResolver.test.ts +83 -0
  162. package/src/utils/service/__tests__/venueSettlementUtils.test.ts +219 -0
  163. package/src/utils/service/__tests__/volunteerCompensationUtils.test.ts +172 -0
  164. package/src/utils/service/apiServiceBookingApiUtils.ts +4 -0
  165. package/src/utils/service/billingCapUtils.ts +145 -0
  166. package/src/utils/service/cancellationPolicyRefundResolver.ts +1 -1
  167. package/src/utils/service/eventPromoterUtils.ts +644 -0
  168. package/src/utils/service/offerAllowListUtils.ts +81 -0
  169. package/src/utils/service/offerComparisonUtils.ts +197 -0
  170. package/src/utils/service/serviceBookingExposureUtils.ts +218 -0
  171. package/src/utils/service/serviceBookingTypes.ts +4 -0
  172. package/src/utils/service/serviceUtils.ts +18 -21
  173. package/src/utils/service/unifiedPricingResolver.ts +149 -0
  174. package/src/utils/service/venueSettlementUtils.ts +198 -0
  175. package/src/utils/service/volunteerCompensationUtils.ts +145 -0
  176. package/src/utils/venueLoyalty/__tests__/eligibilityUtils.test.ts +103 -0
  177. package/src/utils/venueLoyalty/__tests__/redemptionCodeUtils.test.ts +92 -0
  178. package/src/utils/venueLoyalty/eligibilityUtils.ts +84 -0
  179. package/src/utils/venueLoyalty/redemptionCodeUtils.ts +94 -0
  180. package/src/venueLoyaltyRedemption.ts +177 -2
@@ -0,0 +1,319 @@
1
+ import { PricingModel, PromotionAndMarketingSubType } from "@prisma/client";
2
+ /**
3
+ * Event Promoter is a productized hire-a-promoter service profile under
4
+ * `EventService` → `PromotionAndMarketing` → `Promoter`. Its pricing model
5
+ * is intentionally locked to PER_ATTENDEE so:
6
+ *
7
+ * 1. Bookings can compute a deposit at booking time from
8
+ * `bashEvent.expectedAttendees * baseRateCents`.
9
+ * 2. The bash-close settlement job can run a delta charge/refund based on
10
+ * final checked-in attendee count (see
11
+ * `apiEventPromoterSettlementMath` below).
12
+ *
13
+ * Keep the disambiguation: this is the **Event Promoter** service, not the
14
+ * **Promo-code Promoter** referral program (`model Promoter` +
15
+ * `BashEventPromoCode`), which earns BashPoints per ticket purchased.
16
+ */
17
+ /**
18
+ * Returns true when the given `PromotionAndMarketing` subtype is locked to a
19
+ * specific `PricingModel`. Today only `Promoter` is locked (PER_ATTENDEE).
20
+ *
21
+ * Compared with the **string literal** rather than the Prisma enum object
22
+ * because the browser bundle (`index-browser`) does not always re-export
23
+ * Prisma enums as runtime values — see `bash-common/src/mirroredPrismaEnums.ts`
24
+ * for the same pattern.
25
+ */
26
+ export declare function isPerAttendeeLockedPromotionSubType(subType: PromotionAndMarketingSubType | string | null | undefined): boolean;
27
+ /**
28
+ * Build the URL the host clicks from an Event Promoter booking thread to
29
+ * issue/edit a `BashEventPromoCode` with the promoter pre-selected. The
30
+ * landing page reads `promoterUserId` from the query string and opens the
31
+ * promo-code create modal already focused on that user.
32
+ *
33
+ * Keeping this in `bash-common` so api emails + bash-app threads + push
34
+ * notifications all generate the same deep link.
35
+ */
36
+ export declare function buildIssuePromoCodeDeepLink(args: {
37
+ bashEventId: string;
38
+ promoterUserId: string;
39
+ /** Optional preselected ticket tier (skip the chooser screen when set). */
40
+ ticketTierId?: string | null;
41
+ }): string;
42
+ /** Hours-before-bash threshold under which a host cancellation is "late". */
43
+ export declare const EVENT_PROMOTER_LATE_CANCEL_HOURS = 48;
44
+ /**
45
+ * Late-cancellation penalty as a fraction of the deposit (0..1). 0.25 means
46
+ * the host forfeits 25% of the deposit when they cancel inside the
47
+ * `EVENT_PROMOTER_LATE_CANCEL_HOURS` window — covers the promoter's
48
+ * sunk planning time.
49
+ */
50
+ export declare const EVENT_PROMOTER_LATE_CANCEL_PENALTY_FRACTION = 0.25;
51
+ /** Who is cancelling the Event Promoter booking. Maps to refund policy. */
52
+ export type EventPromoterCanceller = "host" | "promoter" | "admin";
53
+ export interface EventPromoterCancellationInput {
54
+ who: EventPromoterCanceller;
55
+ /** ISO timestamp of "now" — injected so callers can test edge cases. */
56
+ nowMs: number;
57
+ /** Bash start time. */
58
+ bashStartMs: number | null;
59
+ /** Bash end time — once we're past this, settlement takes over instead. */
60
+ bashEndMs: number | null;
61
+ /** Deposit cents already charged at booking. */
62
+ depositCents: number;
63
+ /** Has settlement already run? If so, cancellation is a no-op. */
64
+ alreadySettled: boolean;
65
+ }
66
+ export interface EventPromoterCancellationDecision {
67
+ /** Whether the cancellation can run automatically right now. */
68
+ allow: boolean;
69
+ /**
70
+ * Outcome category for telemetry + thread messaging:
71
+ * - `FullRefund` — full deposit returned (host cancel outside window, or
72
+ * promoter cancel any time before the bash).
73
+ * - `PartialRefund` — host cancels inside the late-cancel window; promoter
74
+ * keeps `EVENT_PROMOTER_LATE_CANCEL_PENALTY_FRACTION` of the deposit.
75
+ * - `NoRefund` — bash already happened; settlement handles it instead.
76
+ * - `Blocked` — booking already settled, or impossible state; admin only.
77
+ */
78
+ outcome: "FullRefund" | "PartialRefund" | "NoRefund" | "Blocked";
79
+ /** Refund amount in cents (0 when outcome is NoRefund/Blocked). */
80
+ refundCents: number;
81
+ /** Penalty fraction applied (0 when not late-cancelled by host). */
82
+ penaltyFraction: number;
83
+ /** Human-readable reason, suitable for booking-thread system messages. */
84
+ reason: string;
85
+ }
86
+ /**
87
+ * Pure decision function that returns what should happen when someone tries
88
+ * to cancel an Event Promoter booking. Mirrors the matrix called out in the
89
+ * plan:
90
+ *
91
+ * - Host, bash hasn't started, > 48h out → FullRefund.
92
+ * - Host, bash hasn't started, ≤ 48h out → PartialRefund (25% penalty).
93
+ * - Host, bash already running/ended → NoRefund (settlement takes over).
94
+ * - Promoter, bash not started → FullRefund + promoter notified
95
+ * (Bash never holds a promoter to a job they can't do).
96
+ * - Promoter, bash already running/ended → Blocked (use the booking thread
97
+ * to coordinate; nothing automatic).
98
+ * - Admin always allowed; refund amount decided by caller.
99
+ * - Already settled → Blocked (no automatic cancel).
100
+ *
101
+ * The actual Stripe refund + DB mutation lives in the api-side counterpart;
102
+ * this function only encodes policy so the same matrix surfaces in tests,
103
+ * the booking thread copy, and the audit log.
104
+ */
105
+ export declare function decideEventPromoterCancellation(input: EventPromoterCancellationInput): EventPromoterCancellationDecision;
106
+ /**
107
+ * The single allowed pricing model for the locked promotion subtype. Exposed
108
+ * as a constant so wizard + api validators share the same source of truth.
109
+ *
110
+ * Retained for backwards compatibility; new call sites should prefer
111
+ * {@link EVENT_PROMOTER_LOCKED_PRICING_MODELS} to allow Phase 3's
112
+ * `PER_PAID_ATTENDEE` and `PER_BASHPOINTS_ATTENDEE`.
113
+ */
114
+ export declare const EVENT_PROMOTER_LOCKED_PRICING_MODEL: PricingModel;
115
+ /**
116
+ * Phase 3 — set of pricing models the locked Event Promoter subtype may use.
117
+ * Any of these guarantees a per-head settlement at bash close, which is the
118
+ * actual constraint the worker cares about. Wizard offers them as a choice;
119
+ * api validator accepts any.
120
+ */
121
+ export declare const EVENT_PROMOTER_LOCKED_PRICING_MODELS: ReadonlyArray<PricingModel>;
122
+ export type EventPromoterPricingValidation = {
123
+ ok: true;
124
+ } | {
125
+ ok: false;
126
+ reason: string;
127
+ expected: ReadonlyArray<PricingModel>;
128
+ };
129
+ /**
130
+ * Validates that an `EventService` save with `subType === "Promoter"` uses
131
+ * one of the {@link EVENT_PROMOTER_LOCKED_PRICING_MODELS}. Intended for both:
132
+ *
133
+ * - the Event Services wizard (block save with a friendly message), and
134
+ * - the api save path (reject the request even if the wizard is bypassed).
135
+ *
136
+ * Returns `{ ok: true }` for any non-locked subtype.
137
+ */
138
+ export declare function validateEventPromoterPricing(args: {
139
+ eventServiceSubType: PromotionAndMarketingSubType | string | null | undefined;
140
+ pricingModel: PricingModel | null | undefined;
141
+ }): EventPromoterPricingValidation;
142
+ /**
143
+ * Computes the deposit cents to charge a host at Event Promoter booking time.
144
+ *
145
+ * Logic:
146
+ * - Baseline = max(`bashExpectedAttendees`, `minimumQuantity ?? 0`).
147
+ * - Deposit = baseline * `baseRateCents`.
148
+ *
149
+ * Returns `null` if `baseRateCents` is not set (caller should surface a
150
+ * validation error rather than silently charge $0).
151
+ */
152
+ export declare function computeEventPromoterDepositCents(args: {
153
+ bashExpectedAttendees: number;
154
+ baseRateCents: number | null | undefined;
155
+ minimumQuantity: number | null | undefined;
156
+ }): number | null;
157
+ export interface EventPromoterSettlementInput {
158
+ baseRateCents: number;
159
+ expectedAttendeesAtBooking: number;
160
+ totalCheckedInAttendees: number;
161
+ /** Per-booking host-set ceiling on attributable attendees; `null` = no cap. */
162
+ maxAttendeesAttributable?: number | null;
163
+ /** Optional floor — usually `EventService.minimumQuantity` at booking time. */
164
+ minimumQuantity?: number | null;
165
+ }
166
+ export interface EventPromoterSettlementResult {
167
+ /**
168
+ * Attendee count actually used to bill, after applying the ceiling and any
169
+ * minimum-quantity floor. Always ≥ 0.
170
+ */
171
+ finalCount: number;
172
+ /**
173
+ * True iff `maxAttendeesAttributable` capped `finalCount`. Useful for
174
+ * analytics — high `ceilingHit` rates signal v2 (per-ticket attribution).
175
+ */
176
+ ceilingHit: boolean;
177
+ /**
178
+ * Signed delta in cents:
179
+ * - positive → charge the host this additional amount.
180
+ * - negative → refund the host this amount (refund magnitude = |delta|).
181
+ * - 0 → no Stripe action needed; mark `settledAt`.
182
+ */
183
+ settlementDeltaCents: number;
184
+ /**
185
+ * Total cents the host owes for the booking after settlement
186
+ * (`finalCount * baseRateCents`). Useful for receipts / analytics.
187
+ */
188
+ totalCents: number;
189
+ }
190
+ /**
191
+ * Pure function: compute the per-attendee settlement delta for an Event
192
+ * Promoter `ServiceBooking`. Caller is responsible for translating the result
193
+ * into Stripe API calls (charge if positive delta, refund if negative).
194
+ *
195
+ * Worked example (host hires two promoters for the same bash @ $5/attendee):
196
+ *
197
+ * Promoter A: expected=200, ceiling=250, checked-in=220
198
+ * → finalCount=220, delta = (220-200) * 500 = +$100
199
+ *
200
+ * Promoter B: expected=100, ceiling=150, same 220 checked-in
201
+ * → finalCount=min(220,150)=150, delta = (150-100) * 500 = +$250
202
+ *
203
+ * @see plan: docs/design/CONTENT-PATTERNS.md, .cursor/plans/ambashadors_page_tiers_ux_*.plan.md
204
+ */
205
+ export declare function computeEventPromoterSettlement(input: EventPromoterSettlementInput): EventPromoterSettlementResult;
206
+ /**
207
+ * Which checked-in attendees count toward the settlement headcount?
208
+ *
209
+ * - `AllCheckedIn` — every checked-in, non-comp guest (legacy PER_ATTENDEE).
210
+ * - `PaidUsdOnly` — only guests on USD-priced tiers (PER_PAID_ATTENDEE without
211
+ * `countsBashPointsTickets`).
212
+ * - `PaidBpOnly` — only guests on BashPoints-priced tiers
213
+ * (PER_BASHPOINTS_ATTENDEE).
214
+ * - `PaidAny` — paid guests on either currency
215
+ * (PER_PAID_ATTENDEE with `countsBashPointsTickets = true`).
216
+ */
217
+ export type EventPromoterCountingBasis = "AllCheckedIn" | "PaidUsdOnly" | "PaidBpOnly" | "PaidAny";
218
+ /**
219
+ * Choose the correct counting basis given the pricing model and the
220
+ * per-booking `countsBashPointsTickets` knob. Pure function so wizard +
221
+ * worker share one mapping.
222
+ */
223
+ export declare function eventPromoterCountingBasisFor(args: {
224
+ pricingModel: PricingModel | string | null | undefined;
225
+ countsBashPointsTickets?: boolean | null;
226
+ }): EventPromoterCountingBasis;
227
+ /**
228
+ * Pick the matching checked-in count from the snapshots a worker has gathered
229
+ * at settlement time. Returns the **paying** head count regardless of
230
+ * currency, narrowed by basis.
231
+ */
232
+ export interface EventPromoterAttendeeSnapshots {
233
+ /** All checked-in attendees (`AllCheckedIn` basis). */
234
+ totalCheckedInAttendees: number;
235
+ /** Checked-in attendees on USD-priced tiers (`PaidUsdOnly` / `PaidAny`). */
236
+ paidAttendeesAtSettle?: number | null;
237
+ /** Checked-in attendees on BP-priced tiers (`PaidBpOnly` / `PaidAny`). */
238
+ paidInBashPointsAttendeesAtSettle?: number | null;
239
+ }
240
+ export declare function pickCheckedInForBasis(basis: EventPromoterCountingBasis, s: EventPromoterAttendeeSnapshots): number;
241
+ export interface EventPromoterMixedSettlementInput {
242
+ /** Per-attendee USD rate (cents). 0/null = no USD owed. */
243
+ baseRateCents?: number | null;
244
+ /** Per-attendee BP rate. 0/null = no BP owed. */
245
+ baseRateBashPoints?: number | null;
246
+ /** Expected USD-paying head count at booking. */
247
+ expectedPaidAttendeesAtBooking?: number | null;
248
+ /** Expected BP-paying head count at booking. */
249
+ expectedBpAttendeesAtBooking?: number | null;
250
+ /** Snapshots from the bash checkout (see `EventPromoterAttendeeSnapshots`). */
251
+ snapshots: EventPromoterAttendeeSnapshots;
252
+ /** Optional ceilings — separate caps for USD and BP. */
253
+ maxUsdAttendeesAttributable?: number | null;
254
+ maxBpAttendeesAttributable?: number | null;
255
+ /** Optional dollar cap on USD side (from `maxBillableCents`). */
256
+ maxBillableCents?: number | null;
257
+ /** Optional BP cap on BP side (from `maxBillableBashPoints`). */
258
+ maxBillableBashPoints?: number | null;
259
+ }
260
+ export interface EventPromoterMixedSettlementResult {
261
+ /** USD owed at settlement. */
262
+ usdTotalCents: number;
263
+ /** USD delta vs the deposit pre-paid at booking. */
264
+ usdDeltaCents: number;
265
+ /** BashPoints owed at settlement. */
266
+ bpTotal: number;
267
+ /** BP delta vs the deposit pre-paid at booking. */
268
+ bpDelta: number;
269
+ /** True if either cap kicked in. */
270
+ cappedUsd: boolean;
271
+ cappedBp: boolean;
272
+ }
273
+ /**
274
+ * Pure function for mixed PER_PAID_ATTENDEE / PER_BASHPOINTS_ATTENDEE
275
+ * settlement. Either side can be unset (the worker only computes the side
276
+ * that applies). Caller is responsible for the actual Stripe + BP ledger
277
+ * postings.
278
+ */
279
+ export declare function computeEventPromoterMixedSettlement(input: EventPromoterMixedSettlementInput): EventPromoterMixedSettlementResult;
280
+ export type BashPointsPayoutSourceValue = "HostWallet" | "BashBpPool";
281
+ export interface BashPointsPayoutResolverInput {
282
+ /** From `BashEvent.bashPointsPayoutSource`. */
283
+ source: BashPointsPayoutSourceValue;
284
+ /** BP the worker owes the provider for this settlement. */
285
+ payoutBp: number;
286
+ /** BP the host has in their wallet at settlement time. */
287
+ hostWalletBp: number;
288
+ /**
289
+ * For `BashBpPool` source: live remaining BP in the bash's BP pool. This is
290
+ * `sum(BP from BP-ticket purchases) − sum(BP already paid out) −
291
+ * sum(outstanding BP-refund obligations)`. Caller computes; resolver only
292
+ * drains.
293
+ */
294
+ bashPoolBp?: number;
295
+ }
296
+ export interface BashPointsPayoutResolverResult {
297
+ /** BP drained from the bash's BashPoints pool. */
298
+ fromPoolBp: number;
299
+ /** BP debited from the host's wallet. */
300
+ fromWalletBp: number;
301
+ /** BP that could NOT be sourced (resulting failure → dunning). */
302
+ shortfallBp: number;
303
+ /** True when fromWalletBp > 0 — used to surface UI / push notifications. */
304
+ walletDebited: boolean;
305
+ }
306
+ /**
307
+ * Pure function that decides which BashPoints buckets to drain to satisfy a
308
+ * provider payout. Mirrors the worker's behavior:
309
+ *
310
+ * - `HostWallet`: take everything from the host's wallet; any shortfall is
311
+ * a payment failure (`SettlementPaymentFailed`).
312
+ * - `BashBpPool`: drain the pool first; pay the remainder from the host's
313
+ * wallet; if still short, mark `SettlementPaymentFailed`.
314
+ *
315
+ * Negative inputs are clamped to zero so the resolver never returns a
316
+ * negative bucket.
317
+ */
318
+ export declare function resolveBashPointsPayoutSources(input: BashPointsPayoutResolverInput): BashPointsPayoutResolverResult;
319
+ //# sourceMappingURL=eventPromoterUtils.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"eventPromoterUtils.d.ts","sourceRoot":"","sources":["../../../src/utils/service/eventPromoterUtils.ts"],"names":[],"mappings":"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"}