@bash-app/bash-common 30.381.0 → 30.385.0

package/src/giveaway.ts

@@ -0,0 +1,182 @@
+/**
+ * Event giveaways — shared types, attendee identity, and guest-facing copy.
+ * Qualifying does not guarantee inventory (first-come among eligible people).
+ */
+
+export const GIVEAWAY_ELIGIBILITY = [
+  "AnyoneGoing",
+  "TicketHolders",
+  "CheckedIn",
+  "CompetitionParticipants",
+  "SideQuestCompleters",
+] as const;
+
+export type GiveawayEligibility = (typeof GIVEAWAY_ELIGIBILITY)[number];
+
+export const GIVEAWAY_ATTENDEE_PREFIX = {
+  ticket: "ticket:",
+  rsvp: "rsvp:",
+  guest: "guest:",
+  user: "user:",
+} as const;
+
+export type GiveawayAttendeeResolution = {
+  attendeeId: string;
+  userId?: string;
+  ticketId?: string;
+};
+
+export type PublicGiveaway = {
+  id: string;
+  bashEventId: string;
+  name: string;
+  description: string | null;
+  imageUrl: string | null;
+  quantityTotal: number;
+  quantityRemaining: number;
+  displayOrder: number;
+  sponsorLabel: string | null;
+  eligibility: GiveawayEligibility;
+  competitionId: string | null;
+  sideQuestId: string | null;
+  pickupNote: string | null;
+  qualifyCopy: string;
+};
+
+export type GiveawayScanPayload = {
+  eventId: string;
+  ticketId: string;
+  userId?: string;
+};
+
+export function isGiveawayEligibility(value: unknown): value is GiveawayEligibility {
+  return (
+    typeof value === "string" &&
+    (GIVEAWAY_ELIGIBILITY as readonly string[]).includes(value)
+  );
+}
+
+export function buildGiveawayAttendeeIdFromTicket(ticketId: string): string {
+  return `${GIVEAWAY_ATTENDEE_PREFIX.ticket}${ticketId}`;
+}
+
+export function buildGiveawayAttendeeIdFromRsvp(rsvpId: string): string {
+  return `${GIVEAWAY_ATTENDEE_PREFIX.rsvp}${rsvpId}`;
+}
+
+export function buildGiveawayAttendeeIdFromGuest(guestIdentityId: string): string {
+  return `${GIVEAWAY_ATTENDEE_PREFIX.guest}${guestIdentityId}`;
+}
+
+export function buildGiveawayAttendeeIdFromUser(userId: string): string {
+  return `${GIVEAWAY_ATTENDEE_PREFIX.user}${userId}`;
+}
+
+/** Parse door QR JSON. Accepts ticket payloads with eventId + ticketId (userId optional). */
+export function resolveGiveawayAttendeeFromScan(
+  bashEventId: string,
+  scanPayload: string
+): GiveawayAttendeeResolution | null {
+  const trimmed = scanPayload.trim();
+  if (!trimmed.startsWith("{")) return null;
+  try {
+    const data = JSON.parse(trimmed) as Record<string, unknown>;
+    const eventId = typeof data.eventId === "string" ? data.eventId.trim() : "";
+    const ticketId = typeof data.ticketId === "string" ? data.ticketId.trim() : "";
+    if (!eventId || !ticketId || eventId !== bashEventId) return null;
+    const userId =
+      typeof data.userId === "string" && data.userId.trim()
+        ? data.userId.trim()
+        : undefined;
+    return {
+      attendeeId: buildGiveawayAttendeeIdFromTicket(ticketId),
+      ticketId,
+      ...(userId ? { userId } : {}),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function giveawayQualifyCopy(input: {
+  eligibility: GiveawayEligibility;
+  competitionName?: string | null;
+  sideQuestTitle?: string | null;
+}): string {
+  switch (input.eligibility) {
+    case "AnyoneGoing":
+      return "Anyone going to this bash can qualify";
+    case "TicketHolders":
+      return "Ticket holders qualify";
+    case "CheckedIn":
+      return "Checked-in attendees qualify";
+    case "CompetitionParticipants":
+      return input.competitionName
+        ? `Enter ${input.competitionName} to qualify`
+        : "Enter the contest to qualify";
+    case "SideQuestCompleters":
+      return input.sideQuestTitle
+        ? `Complete ${input.sideQuestTitle} to qualify`
+        : "Complete the side quest to qualify";
+    default:
+      return "Qualifying attendees can receive one while supplies last";
+  }
+}
+
+export function giveawayRemainingCopy(quantityRemaining: number): string {
+  if (quantityRemaining <= 0) return "All distributed";
+  return `${quantityRemaining} remaining`;
+}
+
+export const GIVEAWAY_WHILE_SUPPLIES_LAST =
+  "Available to qualifying attendees while supplies last." as const;
+
+export const VALID_GIVEAWAY_TICKET_STATUSES = [
+  "Pending",
+  "CheckedIn",
+  "Attended",
+  "P2PConfirmed",
+] as const;
+
+export function ticketCountsAsGiveawayTicket(status: string): boolean {
+  return (VALID_GIVEAWAY_TICKET_STATUSES as readonly string[]).includes(status);
+}
+
+export function ticketCountsAsCheckedIn(ticket: {
+  status: string;
+  checkedInAt?: Date | string | null;
+}): boolean {
+  if (ticket.status === "CheckedIn" || ticket.status === "Attended") return true;
+  return Boolean(ticket.checkedInAt);
+}
+
+export function normalizeGiveawayEmail(email: string | null | undefined): string {
+  return (email ?? "").trim().toLowerCase();
+}
+
+export function matchesCompetitionParticipant(input: {
+  userId?: string | null;
+  email?: string | null;
+  participants: Array<{
+    status: string;
+    userId?: string | null;
+    email?: string | null;
+  }>;
+}): boolean {
+  const userId = input.userId?.trim() || null;
+  const email = normalizeGiveawayEmail(input.email);
+  return input.participants.some((p) => {
+    if (p.status !== "ACCEPTED") return false;
+    if (userId && p.userId && p.userId === userId) return true;
+    const participantEmail = normalizeGiveawayEmail(p.email);
+    return Boolean(email && participantEmail && email === participantEmail);
+  });
+}
+
+/** Active outstanding inventory — not historical "ever distributed". */
+export function giveawayActiveDistributedCount(
+  quantityTotal: number,
+  quantityRemaining: number
+): number {
+  return Math.max(0, quantityTotal - quantityRemaining);
+}

package/src/index.ts

@@ -1,4 +1,6 @@
 export * from "./definitions.js";
+export * from "./fundingMeter.js";
+export * from "./giveaway.js";
 export * from "./requestAuthUser.js";
 export * from "./sms/smsTemplates.js";
 export * from "./legalTemplates.js";
@@ -31,6 +33,7 @@ export * from "./venueMatch.js";
 export * from "./entertainmentNotableVenues.js";
 export * from "./productLaunch.js";
 export * from "./accessScreening.js";
+export * from "./applicationFunnel.js";
 export * from "./hostCrmSegments.js";
 export * from "./hostCrmCrowdPulse.js";
 export * from "./hostCrmLastBashProof.js";
@@ -397,6 +400,7 @@ export * from "./utils/service/cancellationPolicyRefundResolver.js";
 export * from "./utils/venueLoyalty/eligibilityUtils.js";
 export * from "./utils/venueLoyalty/redemptionCodeUtils.js";
 // Venue utils moved to paymentUtils.ts for better organization
+export * from "./utils/bashHostIdentity.js";
 export * from "./utils/slugUtils.js";
 export * from "./utils/sortUtils.js";
 export * from "./utils/stringUtils.js";
@@ -446,6 +450,16 @@ export type {
     MakeRequired, Override, RemoveCommonProperties, UnionFromArray
 } from "./utils/typeUtils.js";
 
+// Promoter Competition utilities (pure — safe to import in bash-app and api)
+export {
+  computePromoterCompetitionEconomics,
+  formatPromoterRewardLabel,
+  getPromoterReputationLabel,
+  suggestPromoterSalesGoal,
+  type PromoterMilestoneInput,
+  type PromoterCompetitionEconomics,
+} from "./utils/promoterCompetitionUtils.js";
+
 // Event Templates
 export * from "./templates/eventTemplates.js";
 

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

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "@jest/globals";
+import {
+  getBashHostAvatarUrl,
+  getBashHostDisplayName,
+} from "../bashHostIdentity.js";
+
+describe("getBashHostDisplayName", () => {
+  it("prefers the hosted service name", () => {
+    expect(
+      getBashHostDisplayName({
+        hostedByService: { serviceName: "  DJ Night  " },
+        organization: { name: "Funraising" },
+        creator: { givenName: "Ada", familyName: "Host" },
+      })
+    ).toBe("DJ Night");
+  });
+
+  it("uses the org name when not hosted as a service", () => {
+    expect(
+      getBashHostDisplayName({
+        organization: { name: "Funraising" },
+        creator: { givenName: "Ada", familyName: "Host" },
+      })
+    ).toBe("Funraising");
+  });
+
+  it("falls back to the person when Self", () => {
+    expect(
+      getBashHostDisplayName({
+        creator: { givenName: "Ada", familyName: "Host" },
+      })
+    ).toBe("Ada Host");
+  });
+});
+
+describe("getBashHostAvatarUrl", () => {
+  it("prefers the service cover photo", () => {
+    expect(
+      getBashHostAvatarUrl({
+        hostedByService: { coverPhoto: "https://cdn.example/svc.jpg" },
+        organization: { logoUrl: "https://cdn.example/org.png" },
+      })
+    ).toBe("https://cdn.example/svc.jpg");
+  });
+
+  it("uses the org logo when there is no service cover", () => {
+    expect(
+      getBashHostAvatarUrl({
+        organization: { logoUrl: "https://cdn.example/org.png" },
+      })
+    ).toBe("https://cdn.example/org.png");
+  });
+
+  it("returns null for Self so the caller can use the person photo", () => {
+    expect(getBashHostAvatarUrl({})).toBeNull();
+  });
+});

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

@@ -0,0 +1,128 @@
+import { describe, expect, test } from "@jest/globals";
+import { PromoterRewardMode, PromoterRewardType } from "../../definitions.js";
+import {
+  computePromoterCompetitionEconomics,
+  formatPromoterRewardLabel,
+  suggestPromoterSalesGoal,
+} from "../promoterCompetitionUtils.js";
+
+describe("formatPromoterRewardLabel", () => {
+  test("formats a cash threshold as sales → dollars", () => {
+    expect(
+      formatPromoterRewardLabel({
+        threshold: 5,
+        rewardType: PromoterRewardType.CASH,
+        rewardAmountCents: 1500,
+      })
+    ).toBe("5 sales → $15");
+  });
+
+  test("uses Top promoter for rank 1 and description for non-cash", () => {
+    expect(
+      formatPromoterRewardLabel({
+        rank: 1,
+        rewardType: PromoterRewardType.TICKET,
+        rewardDescription: "VIP access",
+      })
+    ).toBe("Top promoter → VIP access");
+  });
+
+  test("uses Top N promoter for rank > 1 and the reward type when there is no description", () => {
+    expect(
+      formatPromoterRewardLabel({
+        rank: 3,
+        rewardType: PromoterRewardType.TABLE,
+      })
+    ).toBe("Top 3 promoter → TABLE");
+  });
+
+  test("uses ? sales when threshold is missing", () => {
+    expect(
+      formatPromoterRewardLabel({
+        rewardType: PromoterRewardType.CREDIT,
+        rewardAmountCents: 2000,
+      })
+    ).toBe("? sales → $20");
+  });
+});
+
+describe("computePromoterCompetitionEconomics", () => {
+  const cash5 = {
+    threshold: 5,
+    rewardType: PromoterRewardType.CASH,
+    rewardAmountCents: 1000,
+  };
+  const cash10 = {
+    threshold: 10,
+    rewardType: PromoterRewardType.CASH,
+    rewardAmountCents: 4000,
+  };
+  const rankCash = {
+    rank: 1,
+    rewardType: PromoterRewardType.CASH,
+    rewardAmountCents: 5000,
+  };
+  const ticket = {
+    threshold: 3,
+    rewardType: PromoterRewardType.TICKET,
+    rewardDescription: "GA ticket",
+  };
+
+  test("TOTAL_AT_MILESTONE uses the highest threshold cash plus all rank cash", () => {
+    const result = computePromoterCompetitionEconomics({
+      ticketPriceCents: 2000,
+      salesGoal: 50,
+      milestones: [cash5, cash10, rankCash, ticket],
+      rewardMode: PromoterRewardMode.TOTAL_AT_MILESTONE,
+    });
+
+    expect(result.grossPotentialRevenueCents).toBe(100000);
+    expect(result.maxCashRewardExposureCents).toBe(9000);
+    expect(result.effectiveAcquisitionCostPct).toBe(9);
+    expect(result.estimatedNetRevenueCents).toBe(91000);
+    expect(result.rewardBreakdown.map((row) => row.label)).toEqual([
+      "3 sales → GA ticket",
+      "5 sales → $10",
+      "10 sales → $40",
+      "Top promoter → $50",
+    ]);
+  });
+
+  test("ADDITIVE stacks every threshold cash and still adds rank cash", () => {
+    const result = computePromoterCompetitionEconomics({
+      ticketPriceCents: 2000,
+      salesGoal: 50,
+      milestones: [cash5, cash10, rankCash],
+      rewardMode: PromoterRewardMode.ADDITIVE,
+    });
+
+    expect(result.maxCashRewardExposureCents).toBe(10000);
+  });
+
+  test("returns 0% acquisition cost when there is no gross revenue", () => {
+    const result = computePromoterCompetitionEconomics({
+      ticketPriceCents: 0,
+      salesGoal: 0,
+      milestones: [cash5],
+      rewardMode: PromoterRewardMode.ADDITIVE,
+    });
+
+    expect(result.effectiveAcquisitionCostPct).toBe(0);
+    expect(result.maxCashRewardExposureCents).toBe(1000);
+    expect(result.estimatedNetRevenueCents).toBe(-1000);
+  });
+});
+
+describe("suggestPromoterSalesGoal", () => {
+  test("returns null when capacity is missing, zero, or already sold out", () => {
+    expect(suggestPromoterSalesGoal({ capacity: null, ticketsSold: 0 })).toBeNull();
+    expect(suggestPromoterSalesGoal({ capacity: 0, ticketsSold: 0 })).toBeNull();
+    expect(suggestPromoterSalesGoal({ capacity: 40, ticketsSold: 40 })).toBeNull();
+  });
+
+  test("treats null ticketsSold as 0 and snaps 50% remaining to a benchmark", () => {
+    expect(suggestPromoterSalesGoal({ capacity: 100, ticketsSold: null })).toBe(50);
+    expect(suggestPromoterSalesGoal({ capacity: 40, ticketsSold: 0 })).toBe(25);
+    expect(suggestPromoterSalesGoal({ capacity: 400, ticketsSold: 0 })).toBe(200);
+  });
+});

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

@@ -2,8 +2,12 @@ import { describe, expect, test } from "@jest/globals";
 import {
   BASH_DETAIL_URL,
   BASH_EVENT_WIZARD_HOW_MAJOR_STEP,
+  BASH_EVENT_WIZARD_HOW_SUBSTEP,
   BASH_EVENT_WIZARD_HOW_SUBSTEP_PAYOUT,
+  BASH_EVENT_WIZARD_MAJOR,
   BASH_EVENT_WIZARD_PATH_PREFIX,
+  BASH_EVENT_WIZARD_TEMPLATES_SUBSTEP,
+  BASH_EVENT_WIZARD_WHAT_SUBSTEP,
 } from "../../definitions.js";
 import {
   generateSlug,
@@ -13,6 +17,7 @@ import {
   getPublicBashMemoriesPath,
   getBashEventWizardStepPath,
   getBashEventWizardPayoutStepPath,
+  getBashEventWizardStartPath,
   parseBashUrlParams,
   validateSlug,
 } from "../slugUtils.js";
@@ -108,6 +113,45 @@ describe("getBashEventWizardPayoutStepPath", () => {
       `${BASH_EVENT_WIZARD_PATH_PREFIX}/evt-1/${BASH_EVENT_WIZARD_HOW_MAJOR_STEP}/${BASH_EVENT_WIZARD_HOW_SUBSTEP_PAYOUT}`
     );
   });
+
+  test("How substep indices match host-flow order", () => {
+    expect(BASH_EVENT_WIZARD_HOW_SUBSTEP.PRICE).toBe(0);
+    expect(BASH_EVENT_WIZARD_HOW_SUBSTEP.APPLICATION).toBe(1);
+    expect(BASH_EVENT_WIZARD_HOW_SUBSTEP.PROMO_CODES).toBe(2);
+    expect(BASH_EVENT_WIZARD_HOW_SUBSTEP.TASKS).toBe(8);
+    expect(BASH_EVENT_WIZARD_HOW_SUBSTEP.PAYOUT).toBe(9);
+    expect(BASH_EVENT_WIZARD_HOW_SUBSTEP_PAYOUT).toBe(
+      BASH_EVENT_WIZARD_HOW_SUBSTEP.PAYOUT
+    );
+  });
+
+  test("major and What substep indices stay pinned", () => {
+    expect(BASH_EVENT_WIZARD_MAJOR.TEMPLATES).toBe(0);
+    expect(BASH_EVENT_WIZARD_MAJOR.WHO).toBe(2);
+    expect(BASH_EVENT_WIZARD_MAJOR.WHAT).toBe(3);
+    expect(BASH_EVENT_WIZARD_MAJOR.HOW).toBe(7);
+    expect(BASH_EVENT_WIZARD_MAJOR.FINISH).toBe(8);
+    expect(BASH_EVENT_WIZARD_WHAT_SUBSTEP.TITLE).toBe(0);
+    expect(BASH_EVENT_WIZARD_WHAT_SUBSTEP.TYPE).toBe(
+      BASH_EVENT_WIZARD_WHAT_SUBSTEP.TITLE
+    );
+    expect(BASH_EVENT_WIZARD_WHAT_SUBSTEP.VIBE_DRESS).toBe(1);
+    expect(BASH_EVENT_WIZARD_WHAT_SUBSTEP.SCHEDULE).toBe(2);
+  });
+});
+
+describe("getBashEventWizardStartPath", () => {
+  test("defaults to the new draft at Templates", () => {
+    expect(getBashEventWizardStartPath()).toBe(
+      `${BASH_EVENT_WIZARD_PATH_PREFIX}/new/${BASH_EVENT_WIZARD_MAJOR.TEMPLATES}/${BASH_EVENT_WIZARD_TEMPLATES_SUBSTEP.START}`
+    );
+  });
+
+  test("uses an event id when provided", () => {
+    expect(getBashEventWizardStartPath("evt-1")).toBe(
+      `${BASH_EVENT_WIZARD_PATH_PREFIX}/evt-1/${BASH_EVENT_WIZARD_MAJOR.TEMPLATES}/${BASH_EVENT_WIZARD_TEMPLATES_SUBSTEP.START}`
+    );
+  });
 });
 
 describe("parseBashUrlParams", () => {

package/src/utils/bashHostIdentity.ts

@@ -0,0 +1,30 @@
+import { getUserName } from "./apiUtils.js";
+
+export type BashHostIdentityInput = {
+  hostedByService?: { serviceName?: string | null; coverPhoto?: string | null } | null;
+  organization?: { name?: string | null; logoUrl?: string | null } | null;
+  /** `null` is treated the same as `undefined` (no creator info). DB relations are nullable. */
+  creator?: Parameters<typeof getUserName>[0] | null;
+};
+
+function trimmedOrNull(value: string | null | undefined): string | null {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : null;
+}
+
+/** Public host name: service, then org, then the person. */
+export function getBashHostDisplayName(input: BashHostIdentityInput): string {
+  return (
+    trimmedOrNull(input.hostedByService?.serviceName) ??
+    trimmedOrNull(input.organization?.name) ??
+    getUserName(input.creator ?? undefined)
+  );
+}
+
+/** Service cover or org logo when Host as is not Self. Caller falls back to the person. */
+export function getBashHostAvatarUrl(input: BashHostIdentityInput): string | null {
+  return (
+    trimmedOrNull(input.hostedByService?.coverPhoto) ??
+    trimmedOrNull(input.organization?.logoUrl)
+  );
+}