@bash-app/bash-common 30.112.0 → 30.114.0

package/src/definitions.ts

@@ -2,6 +2,7 @@ import {
     BashEventDressTags,
     BashEventType,
     BashEventVibeTags,
+    BracketType,
     CompetitionType,
     Contact,
     EntertainmentServiceType,
@@ -879,7 +880,7 @@ export const YearsOfExperienceToString: { [key in YearsOfExperience]: string } =
   };
 
 // Export Prisma enums for use in frontend
-export { YearsOfExperience, EntertainmentServiceType, MusicGenreType, ServiceTypes, CompetitionType, JudgingType };
+export { YearsOfExperience, EntertainmentServiceType, MusicGenreType, ServiceTypes, CompetitionType, JudgingType, BracketType };
 
 export type BashEventTypeToStringType = {
   [key in BashEventType]: string;

package/src/index.ts

@@ -8,6 +8,8 @@ export * from "./utils/awsS3Utils";
 export * from "./utils/bashCashPaymentUtils";
 export * from "./utils/contentFilterUtils";
 export * from "./utils/dateTimeUtils";
+export * from "./utils/discountEngine/bestPriceResolver";
+export * from "./utils/discountEngine/eligibilityValidator";
 export * from "./utils/objUtils";
 export * from "./utils/paymentUtils";
 export * from "./utils/promoCodesUtils";

package/src/utils/discountEngine/bestPriceResolver.ts

@@ -0,0 +1,212 @@
+import { BashEventPromoCode, SpecialOffer } from "@prisma/client";
+import {
+  calculatePromoCodeDiscount,
+  calculateSpecialOfferDiscount,
+  DiscountResult,
+  formatDiscountDescription,
+} from "./discountCalculator";
+
+export interface BestPriceOptions {
+  ticketPrice: number; // In cents
+  quantity: number;
+  userId?: string;
+  promoCodes: BashEventPromoCode[];
+  specialOffers: SpecialOffer[];
+  allowStacking: boolean; // Global setting
+}
+
+export interface BestPriceResult {
+  appliedDiscounts: DiscountResult[];
+  originalTotal: number; // In cents
+  finalTotal: number; // In cents
+  totalSavings: number; // In cents
+  explanation: string; // "Early Bird -$10 + Code SUMMER20 -$5"
+}
+
+/**
+ * Find the best price by evaluating all possible discount combinations
+ * Implements "best price wins" logic with stacking rules
+ */
+export const findBestPrice = (options: BestPriceOptions): BestPriceResult => {
+  const { ticketPrice, quantity, userId, promoCodes, specialOffers, allowStacking } = options;
+  const originalTotal = ticketPrice * quantity;
+
+  // Early return if no discounts available
+  if (promoCodes.length === 0 && specialOffers.length === 0) {
+    return {
+      appliedDiscounts: [],
+      originalTotal,
+      finalTotal: originalTotal,
+      totalSavings: 0,
+      explanation: "No discounts applied",
+    };
+  }
+
+  // Calculate all possible discount results
+  const promoCodeResults = promoCodes.map(code =>
+    calculatePromoCodeDiscount(code, ticketPrice, quantity)
+  );
+
+  const offerResults = specialOffers.map(offer =>
+    calculateSpecialOfferDiscount(offer, ticketPrice, quantity, userId)
+  );
+
+  // Generate all valid combinations
+  const combinations: DiscountResult[][] = [];
+
+  // Single promo code only
+  promoCodeResults.forEach(promoResult => {
+    combinations.push([promoResult]);
+  });
+
+  // Single special offer only
+  offerResults.forEach(offerResult => {
+    combinations.push([offerResult]);
+  });
+
+  // If stacking is allowed, try combinations
+  if (allowStacking) {
+    promoCodeResults.forEach(promoResult => {
+      offerResults.forEach(offerResult => {
+        // Find the original offer to check stacking rules
+        const originalOffer = specialOffers.find(o => o.id === offerResult.sourceId);
+        
+        if (originalOffer && originalOffer.canStackWithPromoCodes) {
+          // Create a combination of promo code + special offer
+          const stackedDiscounts = stackDiscounts(
+            [promoResult, offerResult],
+            originalTotal
+          );
+          combinations.push(stackedDiscounts);
+        }
+      });
+    });
+
+    // Check if any offers can stack with each other
+    for (let i = 0; i < offerResults.length; i++) {
+      for (let j = i + 1; j < offerResults.length; j++) {
+        const offer1 = specialOffers.find(o => o.id === offerResults[i].sourceId);
+        const offer2 = specialOffers.find(o => o.id === offerResults[j].sourceId);
+
+        if (offer1?.canStackWithOtherOffers && offer2?.canStackWithOtherOffers) {
+          const stackedDiscounts = stackDiscounts(
+            [offerResults[i], offerResults[j]],
+            originalTotal
+          );
+          combinations.push(stackedDiscounts);
+        }
+      }
+    }
+  }
+
+  // Find the combination with the lowest final price
+  let bestCombination: DiscountResult[] = [];
+  let lowestPrice = originalTotal;
+
+  combinations.forEach(combo => {
+    const totalDiscount = combo.reduce((sum, d) => sum + d.amountDiscounted, 0);
+    const finalPrice = Math.max(0, originalTotal - totalDiscount);
+
+    if (finalPrice < lowestPrice) {
+      lowestPrice = finalPrice;
+      bestCombination = combo;
+    }
+  });
+
+  // Calculate total savings
+  const totalSavings = bestCombination.reduce((sum, d) => sum + d.amountDiscounted, 0);
+
+  // Create explanation
+  const explanation = bestCombination.length > 0
+    ? bestCombination.map(formatDiscountDescription).join(" + ")
+    : "No discounts applied";
+
+  return {
+    appliedDiscounts: bestCombination,
+    originalTotal,
+    finalTotal: lowestPrice,
+    totalSavings,
+    explanation,
+  };
+};
+
+/**
+ * Stack multiple discounts, applying guardrails to ensure they work correctly together
+ * Discounts are applied sequentially, not compounded
+ */
+const stackDiscounts = (
+  discounts: DiscountResult[],
+  originalTotal: number
+): DiscountResult[] => {
+  // Sort by priority (percentage discounts first, then fixed amounts)
+  const sorted = [...discounts].sort((a, b) => {
+    if (a.discountType === 'PERCENTAGE' && b.discountType !== 'PERCENTAGE') return -1;
+    if (a.discountType !== 'PERCENTAGE' && b.discountType === 'PERCENTAGE') return 1;
+    return 0;
+  });
+
+  // Apply discounts sequentially
+  let runningTotal = originalTotal;
+  const stackedResults: DiscountResult[] = [];
+
+  sorted.forEach(discount => {
+    // Recalculate discount based on current running total
+    let actualDiscount = discount.amountDiscounted;
+
+    if (discount.discountType === 'PERCENTAGE') {
+      // Apply percentage to current running total
+      actualDiscount = Math.floor((runningTotal * discount.discountValue) / 100);
+    } else {
+      // Fixed amount, but don't exceed running total
+      actualDiscount = Math.min(discount.amountDiscounted, runningTotal);
+    }
+
+    runningTotal = Math.max(0, runningTotal - actualDiscount);
+
+    stackedResults.push({
+      ...discount,
+      amountDiscounted: actualDiscount,
+      finalPrice: runningTotal,
+    });
+  });
+
+  return stackedResults;
+};
+
+/**
+ * Apply guardrails to ensure discount doesn't violate business rules
+ */
+export const applyGuardrails = (
+  result: DiscountResult,
+  minFloor?: number,
+  maxDiscountPercent?: number
+): DiscountResult => {
+  let adjustedResult = { ...result };
+
+  // Enforce minimum price floor
+  if (minFloor && adjustedResult.finalPrice < minFloor) {
+    const maxAllowedDiscount = adjustedResult.originalPrice - minFloor;
+    adjustedResult.amountDiscounted = Math.min(adjustedResult.amountDiscounted, maxAllowedDiscount);
+    adjustedResult.finalPrice = adjustedResult.originalPrice - adjustedResult.amountDiscounted;
+  }
+
+  // Enforce maximum discount percentage
+  if (maxDiscountPercent) {
+    const maxAllowedDiscount = Math.floor((adjustedResult.originalPrice * maxDiscountPercent) / 100);
+    if (adjustedResult.amountDiscounted > maxAllowedDiscount) {
+      adjustedResult.amountDiscounted = maxAllowedDiscount;
+      adjustedResult.finalPrice = adjustedResult.originalPrice - maxAllowedDiscount;
+    }
+  }
+
+  return adjustedResult;
+};
+
+/**
+ * Calculate the effective discount rate as a percentage
+ */
+export const calculateEffectiveRate = (result: BestPriceResult): number => {
+  if (result.originalTotal === 0) return 0;
+  return Math.floor((result.totalSavings / result.originalTotal) * 100);
+};
+

package/src/utils/discountEngine/discountCalculator.ts

@@ -0,0 +1,281 @@
+import { BashEventPromoCode, SpecialOffer, SpecialOfferType, OfferDiscountType } from "@prisma/client";
+import { convertCentsToDollars } from "../paymentUtils";
+
+export interface DiscountResult {
+  sourceType: 'PROMO_CODE' | 'SPECIAL_OFFER';
+  sourceId: string;
+  sourceName: string;
+  discountType: 'PERCENTAGE' | 'FIXED_AMOUNT';
+  discountValue: number;
+  amountDiscounted: number; // In cents
+  originalPrice: number; // In cents
+  finalPrice: number; // In cents
+  attribution?: {
+    userId: string;
+    commissionRate: number;
+    commissionAmount: number; // In cents
+  };
+}
+
+/**
+ * Calculate discount from a promo code
+ */
+export const calculatePromoCodeDiscount = (
+  promoCode: BashEventPromoCode,
+  ticketPrice: number, // In cents
+  quantity: number
+): DiscountResult => {
+  const originalTotal = ticketPrice * quantity;
+  let amountDiscounted = 0;
+  let discountType: 'PERCENTAGE' | 'FIXED_AMOUNT' = 'PERCENTAGE';
+  let discountValue = 0;
+
+  if (promoCode.discountAmountPercentage) {
+    // Percentage discount
+    discountType = 'PERCENTAGE';
+    discountValue = promoCode.discountAmountPercentage;
+    amountDiscounted = Math.floor((originalTotal * promoCode.discountAmountPercentage) / 100);
+  } else if (promoCode.discountAmountInCents) {
+    // Fixed amount discount (per order, not per ticket)
+    discountType = 'FIXED_AMOUNT';
+    discountValue = promoCode.discountAmountInCents;
+    amountDiscounted = Math.min(promoCode.discountAmountInCents, originalTotal);
+  }
+
+  const finalPrice = Math.max(0, originalTotal - amountDiscounted);
+
+  return {
+    sourceType: 'PROMO_CODE',
+    sourceId: promoCode.id,
+    sourceName: promoCode.code,
+    discountType,
+    discountValue,
+    amountDiscounted,
+    originalPrice: originalTotal,
+    finalPrice,
+    // Promo codes always have attribution if there's a promoter
+    ...(promoCode.promoterId && {
+      attribution: {
+        userId: promoCode.promoterId,
+        commissionRate: 5.0, // Default 5% commission
+        commissionAmount: Math.floor(amountDiscounted * 0.05),
+      },
+    }),
+  };
+};
+
+/**
+ * Calculate discount from a special offer
+ */
+export const calculateSpecialOfferDiscount = (
+  offer: SpecialOffer,
+  ticketPrice: number, // In cents
+  quantity: number,
+  userId?: string
+): DiscountResult => {
+  const originalTotal = ticketPrice * quantity;
+  let amountDiscounted = 0;
+  let discountType: 'PERCENTAGE' | 'FIXED_AMOUNT' = 'PERCENTAGE';
+  let discountValue = offer.discountValue;
+
+  // Calculate based on offer type
+  switch (offer.offerType) {
+    case SpecialOfferType.BOGO:
+      amountDiscounted = calculateBOGODiscount(offer, quantity, ticketPrice);
+      discountType = 'FREE_ITEMS' as any; // Special case
+      break;
+
+    case SpecialOfferType.GROUP_DISCOUNT:
+      amountDiscounted = calculateGroupDiscount(offer, quantity, ticketPrice);
+      discountType = offer.discountType === OfferDiscountType.PERCENTAGE ? 'PERCENTAGE' : 'FIXED_AMOUNT';
+      break;
+
+    case SpecialOfferType.VOLUME_DISCOUNT:
+      amountDiscounted = calculateVolumeDiscount(offer, quantity, ticketPrice);
+      discountType = offer.discountType === OfferDiscountType.PERCENTAGE ? 'PERCENTAGE' : 'FIXED_AMOUNT';
+      break;
+
+    case SpecialOfferType.EARLY_BIRD:
+    case SpecialOfferType.FLASH_SALE:
+    case SpecialOfferType.LOYALTY:
+    case SpecialOfferType.COUNTDOWN:
+      // These are simple percentage or fixed amount discounts
+      if (offer.discountType === OfferDiscountType.PERCENTAGE) {
+        discountType = 'PERCENTAGE';
+        amountDiscounted = Math.floor((originalTotal * offer.discountValue) / 100);
+      } else {
+        discountType = 'FIXED_AMOUNT';
+        amountDiscounted = Math.min(offer.discountValue * quantity, originalTotal);
+      }
+      break;
+
+    case SpecialOfferType.BUNDLE:
+      // Bundle savings are pre-calculated
+      amountDiscounted = offer.bundleSavings || 0;
+      discountType = 'FIXED_AMOUNT';
+      break;
+
+    case SpecialOfferType.REFERRAL:
+      // Referral discounts apply to both parties
+      amountDiscounted = offer.referralDiscountForBuyer || 0;
+      discountType = 'FIXED_AMOUNT';
+      break;
+
+    case SpecialOfferType.FAMILY_PACK:
+      // Family pack is typically a percentage off
+      if (offer.discountType === OfferDiscountType.PERCENTAGE) {
+        discountType = 'PERCENTAGE';
+        amountDiscounted = Math.floor((originalTotal * offer.discountValue) / 100);
+      } else {
+        discountType = 'FIXED_AMOUNT';
+        amountDiscounted = Math.min(offer.discountValue, originalTotal);
+      }
+      break;
+
+    default:
+      // Default to simple discount
+      if (offer.discountType === OfferDiscountType.PERCENTAGE) {
+        discountType = 'PERCENTAGE';
+        amountDiscounted = Math.floor((originalTotal * offer.discountValue) / 100);
+      } else {
+        discountType = 'FIXED_AMOUNT';
+        amountDiscounted = Math.min(offer.discountValue, originalTotal);
+      }
+  }
+
+  const finalPrice = Math.max(0, originalTotal - amountDiscounted);
+
+  return {
+    sourceType: 'SPECIAL_OFFER',
+    sourceId: offer.id,
+    sourceName: offer.title,
+    discountType,
+    discountValue,
+    amountDiscounted,
+    originalPrice: originalTotal,
+    finalPrice,
+    // Only referral offers have attribution
+    ...(offer.requiresAttribution && userId && offer.commissionRate && {
+      attribution: {
+        userId,
+        commissionRate: offer.commissionRate,
+        commissionAmount: Math.floor(amountDiscounted * (offer.commissionRate / 100)),
+      },
+    }),
+  };
+};
+
+/**
+ * Calculate BOGO (Buy One Get One) discount
+ * Example: Buy 2 get 1 free, Buy 3 get 2 at 50% off
+ */
+export const calculateBOGODiscount = (
+  offer: SpecialOffer,
+  quantity: number,
+  ticketPrice: number
+): number => {
+  const buyQuantity = offer.buyQuantity || 1;
+  const getQuantity = offer.getQuantity || 1;
+  const getDiscountPercent = offer.getDiscountPercent || 100; // Default 100% off (free)
+
+  // Calculate how many sets of the offer apply
+  const sets = Math.floor(quantity / (buyQuantity + getQuantity));
+  const freeTickets = sets * getQuantity;
+
+  // Calculate discount on free tickets
+  const discountPerTicket = Math.floor((ticketPrice * getDiscountPercent) / 100);
+  return freeTickets * discountPerTicket;
+};
+
+/**
+ * Calculate group discount based on quantity
+ */
+export const calculateGroupDiscount = (
+  offer: SpecialOffer,
+  quantity: number,
+  ticketPrice: number
+): number => {
+  // Check if quantity qualifies
+  if (offer.minGroupSize && quantity < offer.minGroupSize) {
+    return 0;
+  }
+  if (offer.maxGroupSize && quantity > offer.maxGroupSize) {
+    return 0; // Or cap at max group size
+  }
+
+  // Check for tiered discounts
+  if (offer.tieredDiscounts) {
+    const tiers = offer.tieredDiscounts as Array<{ qty: number; discount: number }>;
+    // Find the highest tier that applies
+    const applicableTier = tiers
+      .filter(tier => quantity >= tier.qty)
+      .sort((a, b) => b.discount - a.discount)[0];
+
+    if (applicableTier) {
+      return Math.floor((ticketPrice * quantity * applicableTier.discount) / 100);
+    }
+  }
+
+  // Fall back to simple discount
+  if (offer.discountType === OfferDiscountType.PERCENTAGE) {
+    return Math.floor((ticketPrice * quantity * offer.discountValue) / 100);
+  } else {
+    return Math.min(offer.discountValue * quantity, ticketPrice * quantity);
+  }
+};
+
+/**
+ * Calculate volume discount (buy more save more)
+ * Similar to group discount but typically for larger quantities
+ */
+export const calculateVolumeDiscount = (
+  offer: SpecialOffer,
+  quantity: number,
+  ticketPrice: number
+): number => {
+  // Reuse group discount logic
+  return calculateGroupDiscount(offer, quantity, ticketPrice);
+};
+
+/**
+ * Calculate early bird discount (time-based)
+ */
+export const calculateEarlyBirdDiscount = (
+  offer: SpecialOffer,
+  ticketPrice: number,
+  currentDate: Date
+): number => {
+  // Check if we're still in early bird period
+  if (offer.availableUntil && currentDate > offer.availableUntil) {
+    return 0;
+  }
+
+  if (offer.discountType === OfferDiscountType.PERCENTAGE) {
+    return Math.floor((ticketPrice * offer.discountValue) / 100);
+  } else {
+    return Math.min(offer.discountValue, ticketPrice);
+  }
+};
+
+/**
+ * Calculate bundle discount
+ */
+export const calculateBundleDiscount = (
+  offer: SpecialOffer,
+  bundledItems: Array<{ type: string; price: number }>
+): number => {
+  // Bundle savings are pre-calculated and stored in the offer
+  return offer.bundleSavings || 0;
+};
+
+/**
+ * Helper: Convert discount result to human-readable string
+ */
+export const formatDiscountDescription = (result: DiscountResult): string => {
+  if (result.discountType === 'PERCENTAGE') {
+    return `${result.sourceName}: -${result.discountValue}% ($${convertCentsToDollars(result.amountDiscounted).toFixed(2)})`;
+  } else {
+    return `${result.sourceName}: -$${convertCentsToDollars(result.amountDiscounted).toFixed(2)}`;
+  }
+};
+