@bash-app/bash-common 30.381.0 → 30.385.0

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/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('-');