@bash-app/bash-common 30.383.0 → 30.386.0

package/src/utils/paymentUtils.ts

@@ -430,6 +430,32 @@ export function lowestGuestAllInPriceCents(
   return min;
 }
 
+/** Max share of attributed ticket subtotal a host can assign to a performer (50%). */
+export const MAX_TICKET_COMMISSION_BPS = 5000;
+
+/**
+ * Floor cents owed to a promo-code performer from the discounted ticket subtotal.
+ * Guest price is unchanged; this amount is withheld from the host via application_fee.
+ */
+export function ticketCommissionCents(
+  basisCents: number,
+  commissionBps: number | null | undefined
+): number {
+  if (basisCents <= 0) return 0;
+  const bps = Math.floor(Number(commissionBps) || 0);
+  if (bps <= 0) return 0;
+  const clamped = Math.min(MAX_TICKET_COMMISSION_BPS, bps);
+  return Math.floor((basisCents * clamped) / 10_000);
+}
+
+export function clampTicketCommissionBps(
+  commissionBps: number | null | undefined
+): number {
+  const bps = Math.floor(Number(commissionBps) || 0);
+  if (bps <= 0) return 0;
+  return Math.min(MAX_TICKET_COMMISSION_BPS, bps);
+}
+
 /**
  * Compute the Stripe Connect `application_fee_amount` for a ticket-style charge,
  * along with its constituent parts.
@@ -441,8 +467,10 @@ export function lowestGuestAllInPriceCents(
  *   - `bashPlatformTotalCents` and `guestPlatformLineCents` are both zero
  *   - `totalChargedCents` collapses to the discounted subtotal (no guest-line fee added)
  *   - `applicationFeeAmountCents` equals `stripeProcessingCents`
+ *     plus optional `performerCommissionCents`
  *
- * Default (`false`) preserves existing math bit-exact for every current caller.
+ * Default (`false`) preserves existing math bit-exact for every current caller
+ * when `performerCommissionCents` is omitted or 0.
  */
 export function computeTicketApplicationFeeAmountCents(args: {
   discountedSubtotalCents: number;
@@ -456,6 +484,11 @@ export function computeTicketApplicationFeeAmountCents(args: {
    * NEVER from `BashEvent.nonProfit`, which is user-entered.
    */
   isVerifiedNonprofitHost?: boolean;
+  /**
+   * Performer / street-team cut withheld from the host (not added to the guest).
+   * Must be less than remaining charge after Stripe + Bash platform fees.
+   */
+  performerCommissionCents?: number;
 }): {
   totalChargedCents: number;
   /** Stripe's 2.9% + $0.30 pass-through; unchanged by the nonprofit waiver. */
@@ -467,15 +500,27 @@ export function computeTicketApplicationFeeAmountCents(args: {
   guestPlatformLineCents: number;
   /** Guest-visible Stripe processing line (0 when host absorbs). */
   guestProcessingLineCents: number;
+  /** Host-withheld performer cut included in application_fee. */
+  performerCommissionCents: number;
 } {
   const breakdown = computeGuestTicketCheckoutBreakdown(args);
+  const performerCommissionCents = Math.max(
+    0,
+    Math.floor(args.performerCommissionCents ?? 0)
+  );
+  const maxWithhold = Math.max(
+    0,
+    breakdown.totalDueCents - breakdown.applicationFeeAmountCents - 1
+  );
+  const withheld = Math.min(performerCommissionCents, maxWithhold);
   return {
     totalChargedCents: breakdown.totalDueCents,
     stripeProcessingCents: breakdown.stripeProcessingCents,
     bashPlatformTotalCents: breakdown.bashPlatformTotalCents,
-    applicationFeeAmountCents: breakdown.applicationFeeAmountCents,
+    applicationFeeAmountCents: breakdown.applicationFeeAmountCents + withheld,
     guestPlatformLineCents: breakdown.guestPlatformLineCents,
     guestProcessingLineCents: breakdown.guestProcessingLineCents,
+    performerCommissionCents: withheld,
   };
 }
 

package/src/utils/promoterCompetitionUtils.ts

@@ -0,0 +1,235 @@
+/**
+ * Promoter Competition — pure utility functions for the Street Team / Promoter
+ * Competition workstream.
+ *
+ * No side effects, no DB imports — safe to import in bash-app (browser) and in api.
+ */
+import { PromoterRewardMode, PromoterRewardType } from '../definitions.js';
+
+// ---------------------------------------------------------------------------
+// Shared input / output types
+// ---------------------------------------------------------------------------
+
+export interface PromoterMilestoneInput {
+  threshold?: number | null;
+  rank?: number | null;
+  rewardType: PromoterRewardType;
+  rewardAmountCents?: number | null;
+  rewardDescription?: string | null;
+}
+
+export interface PromoterCompetitionEconomics {
+  grossPotentialRevenueCents: number;
+  maxCashRewardExposureCents: number;
+  /** 0–100 range; maxCashReward / grossRevenue × 100, rounded to 1 decimal. */
+  effectiveAcquisitionCostPct: number;
+  /** gross − maxCashReward */
+  estimatedNetRevenueCents: number;
+  rewardBreakdown: Array<{
+    /** e.g. "5 sales → $15" or "Top 1 promoter → VIP access" */
+    label: string;
+    rewardAmountCents: number | null;
+  }>;
+}
+
+// ---------------------------------------------------------------------------
+// formatPromoterRewardLabel
+// ---------------------------------------------------------------------------
+
+/**
+ * Produces a single human-readable label for a promoter milestone.
+ *
+ * Examples:
+ *   - threshold=5, CASH, rewardAmountCents=1500  → "5 sales → $15"
+ *   - rank=1, TICKET, rewardDescription="VIP access" → "Top 1 promoter → VIP access"
+ *   - threshold=10, TICKET, no description         → "10 sales → TICKET"
+ */
+export function formatPromoterRewardLabel(milestone: {
+  threshold?: number | null;
+  rank?: number | null;
+  rewardType: PromoterRewardType;
+  rewardAmountCents?: number | null;
+  rewardDescription?: string | null;
+}): string {
+  const isCashOrCredit =
+    milestone.rewardType === PromoterRewardType.CASH ||
+    milestone.rewardType === PromoterRewardType.CREDIT;
+
+  const rewardDisplay = isCashOrCredit && milestone.rewardAmountCents != null
+    ? `$${(milestone.rewardAmountCents / 100).toLocaleString('en-US', { minimumFractionDigits: 0, maximumFractionDigits: 2 })}`
+    : milestone.rewardDescription ?? milestone.rewardType;
+
+  if (milestone.rank != null) {
+    const ordinal = milestone.rank === 1 ? 'Top promoter' : `Top ${milestone.rank} promoter`;
+    return `${ordinal} → ${rewardDisplay}`;
+  }
+
+  const threshold = milestone.threshold ?? '?';
+  return `${threshold} sales → ${rewardDisplay}`;
+}
+
+// ---------------------------------------------------------------------------
+// computePromoterCompetitionEconomics
+// ---------------------------------------------------------------------------
+
+/**
+ * Pure economics calculator for a PROMOTER competition.
+ *
+ * Lets hosts sanity-check their milestone structure before publishing:
+ * how much revenue could the event generate and what is the max cash
+ * payout exposure?
+ *
+ * Rank-based (rank != null) CASH/CREDIT milestones are always added to the
+ * max cash exposure regardless of rewardMode because they represent real
+ * monetary obligations (just settled at competition close, not per-sale).
+ */
+export function computePromoterCompetitionEconomics(params: {
+  ticketPriceCents: number;
+  salesGoal: number;
+  milestones: PromoterMilestoneInput[];
+  rewardMode: PromoterRewardMode;
+}): PromoterCompetitionEconomics {
+  const { ticketPriceCents, salesGoal, milestones, rewardMode } = params;
+
+  const grossPotentialRevenueCents = ticketPriceCents * salesGoal;
+
+  // Partition milestones into threshold-based and rank-based.
+  const isCash = (m: PromoterMilestoneInput): boolean =>
+    m.rewardType === PromoterRewardType.CASH ||
+    m.rewardType === PromoterRewardType.CREDIT;
+
+  const thresholdCash = milestones.filter(
+    (m) => m.rank == null && m.threshold != null && isCash(m) && m.rewardAmountCents != null
+  );
+  const rankCash = milestones.filter(
+    (m) => m.rank != null && isCash(m) && m.rewardAmountCents != null
+  );
+
+  let thresholdExposure = 0;
+  if (rewardMode === PromoterRewardMode.TOTAL_AT_MILESTONE) {
+    // Only the highest single threshold reward is effective at once.
+    thresholdExposure = Math.max(0, ...thresholdCash.map((m) => m.rewardAmountCents ?? 0));
+  } else {
+    // ADDITIVE — every threshold reward stacks.
+    thresholdExposure = thresholdCash.reduce(
+      (sum, m) => sum + (m.rewardAmountCents ?? 0),
+      0
+    );
+  }
+
+  // Rank-based cash rewards always add on top (regardless of mode).
+  const rankExposure = rankCash.reduce(
+    (sum, m) => sum + (m.rewardAmountCents ?? 0),
+    0
+  );
+
+  const maxCashRewardExposureCents = thresholdExposure + rankExposure;
+
+  const effectiveAcquisitionCostPct =
+    grossPotentialRevenueCents > 0
+      ? Math.round((maxCashRewardExposureCents / grossPotentialRevenueCents) * 1000) / 10
+      : 0;
+
+  const estimatedNetRevenueCents = grossPotentialRevenueCents - maxCashRewardExposureCents;
+
+  // Build rewardBreakdown — threshold milestones sorted ascending, rank milestones last.
+  const sortedMilestones = [...milestones].sort((a, b) => {
+    const aIsRank = a.rank != null;
+    const bIsRank = b.rank != null;
+    if (aIsRank && !bIsRank) return 1;
+    if (!aIsRank && bIsRank) return -1;
+    if (!aIsRank && !bIsRank) {
+      return (a.threshold ?? Infinity) - (b.threshold ?? Infinity);
+    }
+    // Both rank-based — sort by rank ascending.
+    return (a.rank ?? Infinity) - (b.rank ?? Infinity);
+  });
+
+  const rewardBreakdown = sortedMilestones.map((m) => ({
+    label: formatPromoterRewardLabel(m),
+    rewardAmountCents: m.rewardAmountCents ?? null,
+  }));
+
+  return {
+    grossPotentialRevenueCents,
+    maxCashRewardExposureCents,
+    effectiveAcquisitionCostPct,
+    estimatedNetRevenueCents,
+    rewardBreakdown,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// suggestPromoterSalesGoal
+// ---------------------------------------------------------------------------
+
+const SALES_GOAL_SNAP_POINTS = [25, 50, 75, 100, 150, 200] as const;
+
+/**
+ * Suggests a sales goal for the promoter competition wizard.
+ *
+ * Logic: take 40–60% of remaining capacity (capacity − ticketsSold), then snap
+ * to the nearest common benchmark in [25, 50, 75, 100, 150, 200]. Returns null
+ * when data is insufficient (null inputs or capacity ≤ 0).
+ */
+export function suggestPromoterSalesGoal(params: {
+  capacity: number | null;
+  ticketsSold: number | null;
+}): number | null {
+  const { capacity, ticketsSold } = params;
+  if (capacity == null || capacity <= 0) return null;
+
+  const sold = ticketsSold ?? 0;
+  const remaining = Math.max(0, capacity - sold);
+  if (remaining === 0) return null;
+
+  // Target the midpoint of 40–60% of remaining.
+  const target = remaining * 0.5;
+
+  // Snap to the nearest benchmark.
+  let best: number = SALES_GOAL_SNAP_POINTS[0];
+  let bestDist = Math.abs(target - best);
+
+  for (const snap of SALES_GOAL_SNAP_POINTS) {
+    const dist = Math.abs(target - snap);
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = snap;
+    }
+  }
+
+  return best;
+}
+
+// ---------------------------------------------------------------------------
+// getPromoterReputationLabel
+// ---------------------------------------------------------------------------
+
+/**
+ * Produces a human-readable promoter reputation label based on lifetime stats.
+ * Returns null if the promoter has no completed events yet.
+ *
+ * Priority order (first match wins):
+ *   1. Competition winner (rank=1 achieved)
+ *   2. 100+ lifetime tickets sold
+ *   3. Repeat collaborator (worked with 2+ organizers more than once)
+ *   4. Experienced promoter (3+ events promoted)
+ *   5. Top seller within a competition (any milestone reached)
+ */
+export function getPromoterReputationLabel(stats: {
+  lifetimeQualifiedTickets: number;
+  totalCompetitionsWon: number;
+  totalEventsPromoted: number;
+  repeatOrganizerCount: number;
+  totalMilestonesReached?: number;
+}): string | null {
+  if (stats.totalEventsPromoted < 1) return null;
+
+  if (stats.totalCompetitionsWon >= 1) return 'Competition Winner';
+  if (stats.lifetimeQualifiedTickets >= 100) return '100+ Tickets Sold';
+  if (stats.repeatOrganizerCount >= 2) return 'Repeat Collaborator';
+  if (stats.totalEventsPromoted >= 3) return 'Experienced Promoter';
+  if ((stats.totalMilestonesReached ?? 0) >= 1) return 'Top Seller';
+
+  return null;
+}

package/src/utils/serviceAvailabilityDisplay.ts

@@ -30,6 +30,23 @@ export interface AvailabilityBlockedRange {
   end: Date | string;
 }
 
+/**
+ * Minimum shape needed to decide whether a service can take a bash on a
+ * calendar day. One confirmed/approved booking occupies the whole day.
+ */
+export interface ServiceDayAvailabilityInput {
+  availableHours?: unknown;
+  serviceRatesAssociation?: {
+    serviceSpecialRates?: Array<{
+      isAvailable?: boolean | null;
+      startDate?: Date | string | null;
+      endDate?: Date | string | null;
+    }> | null;
+  } | null;
+  /** Occupied ranges from Confirmed/Approved bookings (public list). */
+  bookedRanges?: readonly AvailabilityBlockedRange[] | null;
+}
+
 const WEEKDAY_NAMES = [
   "Monday",
   "Tuesday",
@@ -156,9 +173,72 @@ export function isAvailabilityDayOpen(
   return openDays[name] !== false;
 }
 
+/** Owner-blocked ranges from `ServiceSpecialRates` where `isAvailable` is false. */
+export function blockedRangesFromSpecialRates(
+  specialRates:
+    | NonNullable<
+        NonNullable<
+          ServiceDayAvailabilityInput["serviceRatesAssociation"]
+        >["serviceSpecialRates"]
+      >
+    | null
+    | undefined
+): AvailabilityBlockedRange[] {
+  if (!specialRates) return [];
+  const ranges: AvailabilityBlockedRange[] = [];
+  for (const rate of specialRates) {
+    if (rate?.isAvailable === false && rate.startDate && rate.endDate) {
+      ranges.push({ start: rate.startDate, end: rate.endDate });
+    }
+  }
+  return ranges;
+}
+
+/**
+ * True when the service can take a bash on `date`: weekly hours are open,
+ * the owner has not blocked the day, and no confirmed/approved booking
+ * already occupies it. Missing hours mean every weekday is treated as open.
+ */
+export function isServiceAvailableOnDate(
+  service: ServiceDayAvailabilityInput,
+  date: Date
+): boolean {
+  const config = parseAvailableHours(service.availableHours);
+  if (!isAvailabilityDayOpen(config?.openDays, date)) return false;
+  if (
+    isDateBlocked(
+      blockedRangesFromSpecialRates(
+        service.serviceRatesAssociation?.serviceSpecialRates
+      ),
+      date
+    )
+  ) {
+    return false;
+  }
+  if (isDateBlocked(service.bookedRanges ?? [], date)) return false;
+  return true;
+}
+
+export function filterServicesAvailableOnDate<T extends ServiceDayAvailabilityInput>(
+  services: readonly T[],
+  date: Date
+): T[] {
+  return services.filter((service) => isServiceAvailableOnDate(service, date));
+}
+
+export function countServicesAvailableOnDate<
+  T extends ServiceDayAvailabilityInput,
+>(services: readonly T[], date: Date): number {
+  let count = 0;
+  for (const service of services) {
+    if (isServiceAvailableOnDate(service, date)) count += 1;
+  }
+  return count;
+}
+
 /** Whether a date falls within any owner-blocked (unavailable) range. */
 export function isDateBlocked(
-  blockedRanges: AvailabilityBlockedRange[],
+  blockedRanges: readonly AvailabilityBlockedRange[],
   date: Date
 ): boolean {
   const day = startOfLocalDay(date).getTime();
@@ -177,7 +257,7 @@ export function isDateBlocked(
  */
 export function computeEarliestOpenDate(params: {
   openDays?: Record<string, boolean> | null;
-  blockedRanges?: AvailabilityBlockedRange[] | null;
+  blockedRanges?: readonly AvailabilityBlockedRange[] | null;
   fromDate?: Date;
   maxLookaheadDays?: number;
 }): Date | null {

package/src/utils/slugUtils.ts

@@ -3,7 +3,9 @@ import {
   BASH_DETAIL_URL,
   BASH_EVENT_WIZARD_HOW_MAJOR_STEP,
   BASH_EVENT_WIZARD_HOW_SUBSTEP_PAYOUT,
+  BASH_EVENT_WIZARD_MAJOR,
   BASH_EVENT_WIZARD_PATH_PREFIX,
+  BASH_EVENT_WIZARD_TEMPLATES_SUBSTEP,
 } from '../definitions.js';
 
 type SlugifyOptions = {
@@ -112,6 +114,15 @@ export function getBashEventWizardPayoutStepPath(bashEventId: string): string {
   );
 }
 
+/** Create / resume at Getting Started (Templates). Defaults to the `new` draft. */
+export function getBashEventWizardStartPath(bashEventId = "new"): string {
+  return getBashEventWizardStepPath(
+    bashEventId,
+    BASH_EVENT_WIZARD_MAJOR.TEMPLATES,
+    BASH_EVENT_WIZARD_TEMPLATES_SUBSTEP.START
+  );
+}
+
 export function parseBashUrlParams(param: string): { id: string; slug: string | null } | null {
   // Expected format: "id-slug" where id is first part before first dash
   const dashIndex = param.indexOf('-');