@bash-app/bash-common 30.432.0 → 30.434.0

package/src/promoCodeScope.ts

@@ -0,0 +1,180 @@
+import { getPublicBashDetailPath } from "./utils/slugUtils.js";
+
+/**
+ * Which bash and tiers a promo code applies to, and what kind of discount it
+ * gives, for both legacy single-tier rows and bash-level rows. Every reader goes
+ * through these instead of `promo.ticketTier.bashEventId` or `promo.ticketTierId`.
+ */
+
+export type PromoDiscountKind = "NONE" | "PERCENT" | "FIXED_CASH";
+export type PromoEligibilityMode = "ALL_TIERS" | "SELECTED_TIERS";
+
+/** How the host pays a promoter for a code. BashPoints is credited here; the others are paid outside Bash. */
+export const PROMO_COMPENSATION_METHODS = ["Venmo", "Zelle", "CashApp", "BashPoints"] as const;
+export type PromoCompensationMethod = (typeof PROMO_COMPENSATION_METHODS)[number];
+
+export function isPromoCompensationMethod(value: unknown): value is PromoCompensationMethod {
+  return (
+    typeof value === "string" &&
+    (PROMO_COMPENSATION_METHODS as readonly string[]).includes(value)
+  );
+}
+
+export type PromoScopeFields = {
+  ticketTierId?: string | null;
+  bashEventId?: string | null;
+  eligibilityMode?: PromoEligibilityMode | null;
+  discountType?: PromoDiscountKind | null;
+  discountAmountInCents?: number | null;
+  discountAmountPercentage?: number | null;
+  eligibleTiers?: ReadonlyArray<{ ticketTierId: string }> | null;
+  ticketTier?: { bashEventId: string } | null;
+};
+
+/** Explicit type wins; legacy rows derive it from whichever amount is set. */
+export function promoCodeDiscountKind(promo: PromoScopeFields): PromoDiscountKind {
+  if (promo.discountType) return promo.discountType;
+  if ((promo.discountAmountPercentage ?? 0) > 0) return "PERCENT";
+  if ((promo.discountAmountInCents ?? 0) > 0) return "FIXED_CASH";
+  return "NONE";
+}
+
+export function promoCodeBashEventId(promo: PromoScopeFields): string | null {
+  return promo.bashEventId ?? promo.ticketTier?.bashEventId ?? null;
+}
+
+/**
+ * "ALL" for an all-tiers code (including tiers added later); otherwise the
+ * selected tier ids, falling back to the legacy single tier.
+ */
+export function promoCodeEligibleTierIds(promo: PromoScopeFields): "ALL" | string[] {
+  if (promo.eligibilityMode === "ALL_TIERS") return "ALL";
+  const selected = (promo.eligibleTiers ?? []).map((t) => t.ticketTierId);
+  if (selected.length > 0) return [...new Set(selected)];
+  return promo.ticketTierId ? [promo.ticketTierId] : [];
+}
+
+export function promoCodeAppliesToTier(promo: PromoScopeFields, ticketTierId: string): boolean {
+  const ids = promoCodeEligibleTierIds(promo);
+  return ids === "ALL" || ids.includes(ticketTierId);
+}
+
+export type PromoCodeStatusReason =
+  | "expired"
+  | "exhausted"
+  | "already_used"
+  | "disabled"
+  | "invalid"
+  | "host_review_required";
+
+/** Public, logged-out view of a code. Never includes a promoter id or email. */
+export type PromoCodeStatus = {
+  status: "valid" | PromoCodeStatusReason;
+  reason: PromoCodeStatusReason | null;
+  code: string;
+  discountType: PromoDiscountKind | null;
+  /** Percent for PERCENT, cents for FIXED_CASH, 0 for NONE. */
+  value: number;
+  eligibilityMode: PromoEligibilityMode | null;
+  /** Empty for all-tiers codes. */
+  eligibleTierIds: string[];
+  appliesToBashPoints: boolean;
+};
+
+/**
+ * Promoter share link: `/bash/<active vanity>?promo=CODE`, else the public
+ * id-slug path. The code is uppercased and URL-encoded. Legacy `?promocode=`
+ * and `?ref=` links keep working on the bash page.
+ */
+export function getPromoterShareUrl(args: {
+  bashEventId: string;
+  slug?: string | null;
+  vanityPaths?: ReadonlyArray<{ segment: string; status: string }> | null;
+  code: string;
+  /** Absolute origin, e.g. "https://bash.community". Omit for a relative path. */
+  origin?: string;
+}): string {
+  const active = args.vanityPaths?.find((v) => v.status === "Active" && v.segment.trim());
+  const path = active
+    ? `/bash/${encodeURIComponent(active.segment.trim().toLowerCase())}`
+    : getPublicBashDetailPath(args.bashEventId, args.slug);
+  const query = `?promo=${encodeURIComponent(args.code.trim().toUpperCase())}`;
+  const origin = args.origin?.replace(/\/$/, "") ?? "";
+  return `${origin}${path}${query}`;
+}
+
+/** Host form payload for a bash-level promoter or promo code. */
+export type PromoterCodeInput = {
+  code: string;
+  promoterUserId?: string | null;
+  promoterEmail?: string | null;
+  discountType: PromoDiscountKind;
+  /** Percent (0-100) for PERCENT, cents (0 or more) for FIXED_CASH, ignored for NONE. */
+  discountValue?: number | null;
+  eligibilityMode: PromoEligibilityMode;
+  eligibleTierIds?: string[];
+  discountAppliesToBashPoints?: boolean;
+  redeemBy?: string | null;
+  /** Maximum orders. */
+  maxRedemptions?: number | null;
+  maxUsesPerAccount?: number | null;
+  bashPointsRewardPerTicket?: number | null;
+  /** The promoter's rate for this bash, 0-10000 bps of eligible net ticket proceeds. */
+  promoterCommissionBps?: number | null;
+  /** The host opened and confirmed the Promoter reward section. */
+  promoterRewardReviewed?: boolean;
+  /** Venmo, Zelle, Cash App, or BashPoints. Null clears a saved choice. */
+  compensationMethod?: PromoCompensationMethod | null;
+};
+
+export type PromoterCodeStatusLabel = "active" | "expired" | "exhausted" | "disabled";
+
+/** Validation shared by the host form and the API. Empty array means valid. */
+export function promoterCodeInputErrors(
+  input: PromoterCodeInput,
+  bashTierIds: readonly string[]
+): string[] {
+  const errors: string[] = [];
+  const code = input.code?.trim() ?? "";
+  if (!code) errors.push("Enter a code.");
+  else if (!/^[A-Za-z0-9_-]{2,32}$/.test(code)) {
+    errors.push("Codes use 2-32 letters, numbers, dashes, or underscores.");
+  }
+  if (input.discountType === "PERCENT") {
+    const pct = Number(input.discountValue);
+    if (!Number.isInteger(pct) || pct < 0 || pct > 100) {
+      errors.push("Guest discount must be between 0% and 100%.");
+    }
+  } else if (input.discountType === "FIXED_CASH") {
+    const cents = Number(input.discountValue);
+    if (!Number.isInteger(cents) || cents < 0) errors.push("Enter a fixed discount of $0 or more.");
+  }
+  if (input.eligibilityMode === "SELECTED_TIERS") {
+    const ids = input.eligibleTierIds ?? [];
+    if (ids.length === 0) errors.push("Pick at least one ticket tier.");
+    if (ids.some((id) => !bashTierIds.includes(id))) errors.push("A selected tier isn't on this bash.");
+  }
+  if (input.promoterCommissionBps != null) {
+    const bps = input.promoterCommissionBps;
+    if (!Number.isInteger(bps) || bps < 0 || bps > 10_000) {
+      errors.push("Promoter commission must be between 0% and 100%.");
+    }
+  }
+  for (const [label, value] of [
+    ["Maximum orders", input.maxRedemptions],
+    ["Per-guest limit", input.maxUsesPerAccount],
+    ["BashPoints per ticket", input.bashPointsRewardPerTicket],
+  ] as const) {
+    if (value != null && (!Number.isInteger(value) || value < 0)) {
+      errors.push(`${label} must be a whole number of 0 or more.`);
+    }
+  }
+  const hasPromoter = !!(input.promoterUserId || input.promoterEmail?.trim());
+  if (hasPromoter && !input.promoterRewardReviewed) {
+    errors.push("Review the promoter reward before saving.");
+  }
+  if (input.compensationMethod != null && !isPromoCompensationMethod(input.compensationMethod)) {
+    errors.push("Choose Venmo, Zelle, Cash App, or BashPoints.");
+  }
+  return errors;
+}

package/src/utils/__tests__/discountEngine/discountCalculator.test.ts

@@ -1,5 +1,6 @@
 import {
   OfferDiscountType,
+  PromoCodeEligibilityMode,
   SpecialOffer,
   SpecialOfferType,
 } from "@prisma/client";
@@ -23,10 +24,17 @@ function basePromoCode(
     Pick<BashEventPromoCodeWithPromoter, "id" | "code">
 ): BashEventPromoCodeWithPromoter {
   return {
+    bashEventId: null,
     ticketTierId: "tier-1",
+    eligibilityMode: PromoCodeEligibilityMode.SELECTED_TIERS,
+    discountType: null,
+    discountAppliesToBashPoints: false,
+    disabledAt: null,
+    legacyReviewFlag: null,
     discountAmountInCents: null,
     discountAmountPercentage: null,
     maxRedemptions: null,
+    maxUsesPerAccount: null,
     redeemBy: null,
     promoterId: null,
     stripeCouponId: null,

package/src/utils/__tests__/paymentUtils.test.ts

@@ -23,7 +23,9 @@ import {
   computeTicketApplicationFeeAmountCents,
   computeGuestTicketCheckoutBreakdown,
   ticketCommissionCents,
-  clampTicketCommissionBps,
+  eligibleNetTicketProceedsCents,
+  ticketCommissionBpsError,
+  TEMPORARY_SETTLEMENT_SAFETY_REMAINDER_CENTS,
   MAX_TICKET_COMMISSION_BPS,
   guestAllInUnitPriceCents,
   guestCheckoutHasNoAddedFees,
@@ -282,13 +284,105 @@ describe("PaymentUtils - Core Functions", () => {
       expect(r.applicationFeeAmountCents).toBe(r.stripeProcessingCents);
     });
 
-    test("ticketCommissionCents floors bps of the subtotal and caps at 50%", () => {
+    test("ticketCommissionCents floors bps of the basis and pays up to 100%", () => {
+      expect(MAX_TICKET_COMMISSION_BPS).toBe(10000);
       expect(ticketCommissionCents(10000, 1500)).toBe(1500);
       expect(ticketCommissionCents(10000, 0)).toBe(0);
-      expect(ticketCommissionCents(10000, MAX_TICKET_COMMISSION_BPS + 100)).toBe(
-        5000
-      );
-      expect(clampTicketCommissionBps(99999)).toBe(MAX_TICKET_COMMISSION_BPS);
+      expect(ticketCommissionCents(1912, 10000)).toBe(1912);
+      expect(ticketCommissionCents(1912, 5000)).toBe(956);
+      expect(ticketCommissionCents(1912, 99999)).toBe(1912);
+      expect(ticketCommissionCents(0, 10000)).toBe(0);
+    });
+
+    test("ticketCommissionBpsError accepts 0-100% and rejects the rest", () => {
+      expect(ticketCommissionBpsError(0)).toBeNull();
+      expect(ticketCommissionBpsError(5000)).toBeNull();
+      expect(ticketCommissionBpsError(10000)).toBeNull();
+      expect(ticketCommissionBpsError(null)).toBeNull();
+      expect(ticketCommissionBpsError(10001)).toMatch(/between 0% and 100%/);
+      expect(ticketCommissionBpsError(-1)).toMatch(/between 0% and 100%/);
+      expect(ticketCommissionBpsError(12.5)).toMatch(/whole number/);
+    });
+
+    describe("eligibleNetTicketProceedsCents: $20 sale", () => {
+      const fees = (feeHandling: string, platformFeeEnabled: boolean) =>
+        computeTicketApplicationFeeAmountCents({
+          discountedSubtotalCents: 2000,
+          platformFeeEnabled,
+          platformFeeRate: 0.03,
+          feeHandling,
+          bashPassWaivesGuestFee: false,
+        });
+      const net = (f: ReturnType<typeof fees>, eligible = 2000) =>
+        eligibleNetTicketProceedsCents({
+          eligibleSubtotalCents: eligible,
+          discountedSubtotalCents: 2000,
+          bashPlatformTotalCents: f.bashPlatformTotalCents,
+          guestPlatformLineCents: f.guestPlatformLineCents,
+          stripeProcessingCents: f.stripeProcessingCents,
+          guestProcessingLineCents: f.guestProcessingLineCents,
+        });
+
+      test("host absorbs, platform fee off: 2000 - 88 = 1912; 100% owes 1912, 50% owes 956", () => {
+        const f = fees("HostAbsorbs", false);
+        expect(f.applicationFeeAmountCents).toBe(88);
+        expect(net(f)).toBe(1912);
+        expect(ticketCommissionCents(net(f), 10000)).toBe(1912);
+        expect(ticketCommissionCents(net(f), 5000)).toBe(956);
+      });
+
+      test("host absorbs a 3% platform fee: app fee 148, net 1852", () => {
+        const f = fees("HostAbsorbs", true);
+        expect(f.applicationFeeAmountCents).toBe(148);
+        expect(net(f)).toBe(1852);
+        expect(ticketCommissionCents(net(f), 5000)).toBe(926);
+      });
+
+      test("guest pays the fees: the guest lines cover them, so the host share is close to the subtotal", () => {
+        const f = fees("GuestPays", true);
+        const hostShare =
+          Math.max(0, f.bashPlatformTotalCents - f.guestPlatformLineCents) +
+          Math.max(0, f.stripeProcessingCents - f.guestProcessingLineCents);
+        expect(net(f)).toBe(2000 - hostShare);
+        expect(net(f)).toBeGreaterThan(1900);
+      });
+
+      test("only the code's tier counts: a $20 eligible line in a $40 cart carries half the fees", () => {
+        const both = computeTicketApplicationFeeAmountCents({
+          discountedSubtotalCents: 4000,
+          platformFeeEnabled: false,
+          platformFeeRate: 0.03,
+          feeHandling: "HostAbsorbs",
+          bashPassWaivesGuestFee: false,
+        });
+        const eligible = eligibleNetTicketProceedsCents({
+          eligibleSubtotalCents: 2000,
+          discountedSubtotalCents: 4000,
+          bashPlatformTotalCents: both.bashPlatformTotalCents,
+          guestPlatformLineCents: both.guestPlatformLineCents,
+          stripeProcessingCents: both.stripeProcessingCents,
+          guestProcessingLineCents: both.guestProcessingLineCents,
+        });
+        expect(eligible).toBe(2000 - Math.ceil(both.stripeProcessingCents / 2));
+      });
+
+      test("zero eligible proceeds owe nothing", () => {
+        expect(net(fees("HostAbsorbs", false), 0)).toBe(0);
+      });
+    });
+
+    test("withholding can take the full eligible net when the safety remainder is 0", () => {
+      expect(TEMPORARY_SETTLEMENT_SAFETY_REMAINDER_CENTS).toBe(0);
+      const r = computeTicketApplicationFeeAmountCents({
+        discountedSubtotalCents: 2000,
+        platformFeeEnabled: false,
+        platformFeeRate: 0.03,
+        feeHandling: "HostAbsorbs",
+        bashPassWaivesGuestFee: false,
+        performerCommissionCents: 1912,
+      });
+      expect(r.performerCommissionCents).toBe(1912);
+      expect(r.totalChargedCents - r.applicationFeeAmountCents).toBe(0);
     });
 
     test("PROMO-002: performer cut is withheld on the application fee, not the guest total", () => {

package/src/utils/paymentUtils.ts

@@ -448,12 +448,35 @@ 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;
+/** A host can assign up to 100% of eligible net ticket proceeds to a promoter. */
+export const MAX_TICKET_COMMISSION_BPS = 10_000;
 
 /**
- * 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.
+ * Cents left on the host transfer when withholding commission. Stripe test mode
+ * accepted application_fee_amount equal to the charge (check 4b, 2026-10-14),
+ * so a $0 host transfer is allowed and this stays 0. This is not a host share.
+ */
+export const TEMPORARY_SETTLEMENT_SAFETY_REMAINDER_CENTS = 0;
+
+/** Error message for an out-of-range rate, or null when 0-100% (0-10000 bps). */
+export function ticketCommissionBpsError(
+  commissionBps: number | null | undefined
+): string | null {
+  if (commissionBps == null) return null;
+  if (!Number.isInteger(commissionBps)) {
+    return "Commission must be a whole number of basis points.";
+  }
+  if (commissionBps < 0 || commissionBps > MAX_TICKET_COMMISSION_BPS) {
+    return "Commission must be between 0% and 100% of eligible net ticket proceeds.";
+  }
+  return null;
+}
+
+/**
+ * Floor cents owed to a promoter: `commissionBps` of `basisCents`, where the basis
+ * is eligible net ticket proceeds. Guest price is unchanged; the amount is
+ * withheld from the host via application_fee. Rates are validated when written;
+ * this never pays more than 100% of the basis.
  */
 export function ticketCommissionCents(
   basisCents: number,
@@ -462,16 +485,34 @@ export function ticketCommissionCents(
   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);
+  return Math.floor((basisCents * Math.min(MAX_TICKET_COMMISSION_BPS, bps)) / 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);
+/**
+ * What the host would otherwise receive for the eligible ticket lines: the
+ * eligible discounted subtotal, less its share of the Bash platform fee and the
+ * Stripe processing estimate that no guest fee line pays. Tax, guest fee lines,
+ * coat check, and delivery are never part of it. Floored at 0.
+ */
+export function eligibleNetTicketProceedsCents(args: {
+  /** Discounted subtotal of the lines the code applies to. */
+  eligibleSubtotalCents: number;
+  /** Discounted ticket subtotal of the whole cart (the fee basis). */
+  discountedSubtotalCents: number;
+  bashPlatformTotalCents: number;
+  guestPlatformLineCents: number;
+  stripeProcessingCents: number;
+  guestProcessingLineCents: number;
+}): number {
+  const eligible = Math.max(0, Math.floor(args.eligibleSubtotalCents));
+  const cart = Math.max(0, Math.floor(args.discountedSubtotalCents));
+  if (eligible <= 0 || cart <= 0) return 0;
+  const share = Math.min(1, eligible / cart);
+  const hostPlatform = Math.max(0, args.bashPlatformTotalCents - args.guestPlatformLineCents);
+  const hostProcessing = Math.max(0, args.stripeProcessingCents - args.guestProcessingLineCents);
+  const net =
+    eligible - Math.ceil(hostPlatform * share) - Math.ceil(hostProcessing * share);
+  return Math.max(0, net);
 }
 
 /**
@@ -528,7 +569,9 @@ export function computeTicketApplicationFeeAmountCents(args: {
   );
   const maxWithhold = Math.max(
     0,
-    breakdown.totalDueCents - breakdown.applicationFeeAmountCents - 1
+    breakdown.totalDueCents -
+      breakdown.applicationFeeAmountCents -
+      TEMPORARY_SETTLEMENT_SAFETY_REMAINDER_CENTS
   );
   const withheld = Math.min(performerCommissionCents, maxWithhold);
   return {