@bash-app/bash-common 30.381.0 → 30.385.0

package/src/__tests__/promoterCompetitionUtils.test.ts

@@ -0,0 +1,334 @@
+/**
+ * bash-common promoterCompetitionUtils — pure function tests.
+ *
+ * Covers: formatPromoterRewardLabel, computePromoterCompetitionEconomics,
+ *         suggestPromoterSalesGoal, getPromoterReputationLabel.
+ *
+ * No mocks needed — all functions are side-effect free.
+ */
+import {
+  formatPromoterRewardLabel,
+  computePromoterCompetitionEconomics,
+  suggestPromoterSalesGoal,
+  getPromoterReputationLabel,
+} from "../utils/promoterCompetitionUtils.js";
+import { PromoterRewardMode, PromoterRewardType } from "../definitions.js";
+
+// ─── formatPromoterRewardLabel ────────────────────────────────────────────────
+
+describe("formatPromoterRewardLabel", () => {
+  it("formats a threshold CASH milestone as 'N sales → $X'", () => {
+    expect(
+      formatPromoterRewardLabel({
+        threshold: 5,
+        rank: null,
+        rewardType: PromoterRewardType.CASH,
+        rewardAmountCents: 1500,
+        rewardDescription: null,
+      })
+    ).toBe("5 sales → $15");
+  });
+
+  it("formats a threshold CASH milestone with triple-digit amount", () => {
+    expect(
+      formatPromoterRewardLabel({
+        threshold: 35,
+        rank: null,
+        rewardType: PromoterRewardType.CASH,
+        rewardAmountCents: 25000,
+        rewardDescription: null,
+      })
+    ).toBe("35 sales → $250");
+  });
+
+  it("formats a threshold ACCESS milestone using rewardDescription", () => {
+    expect(
+      formatPromoterRewardLabel({
+        threshold: 10,
+        rank: null,
+        rewardType: PromoterRewardType.ACCESS,
+        rewardAmountCents: null,
+        rewardDescription: "Backstage access",
+      })
+    ).toBe("10 sales → Backstage access");
+  });
+
+  it("falls back to rewardType when description is missing and reward is non-cash", () => {
+    expect(
+      formatPromoterRewardLabel({
+        threshold: 10,
+        rank: null,
+        rewardType: PromoterRewardType.TICKET,
+        rewardAmountCents: null,
+        rewardDescription: null,
+      })
+    ).toBe("10 sales → TICKET");
+  });
+
+  it("formats rank=1 as 'Top promoter → ...'", () => {
+    expect(
+      formatPromoterRewardLabel({
+        threshold: null,
+        rank: 1,
+        rewardType: PromoterRewardType.CASH,
+        rewardAmountCents: 25000,
+        rewardDescription: null,
+      })
+    ).toBe("Top promoter → $250");
+  });
+
+  it("formats rank > 1 as 'Top N promoter → ...'", () => {
+    expect(
+      formatPromoterRewardLabel({
+        threshold: null,
+        rank: 3,
+        rewardType: PromoterRewardType.CASH,
+        rewardAmountCents: 10000,
+        rewardDescription: null,
+      })
+    ).toBe("Top 3 promoter → $100");
+  });
+
+  it("formats a CREDIT milestone the same as CASH (dollar sign, no cents when round)", () => {
+    expect(
+      formatPromoterRewardLabel({
+        threshold: 20,
+        rank: null,
+        rewardType: PromoterRewardType.CREDIT,
+        rewardAmountCents: 5000,
+        rewardDescription: null,
+      })
+    ).toBe("20 sales → $50");
+  });
+});
+
+// ─── computePromoterCompetitionEconomics (bash-common version) ────────────────
+
+describe("computePromoterCompetitionEconomics (bash-common)", () => {
+  const baseMilestones = [
+    { threshold: 5,  rank: null, rewardType: PromoterRewardType.CASH,   rewardAmountCents: 1500,  rewardDescription: null },
+    { threshold: 10, rank: null, rewardType: PromoterRewardType.CASH,   rewardAmountCents: 4000,  rewardDescription: null },
+    { threshold: 20, rank: null, rewardType: PromoterRewardType.ACCESS,  rewardAmountCents: null,  rewardDescription: "VIP access" },
+    { threshold: 35, rank: null, rewardType: PromoterRewardType.CASH,   rewardAmountCents: 10000, rewardDescription: null },
+  ];
+
+  it("computes correct gross potential revenue (100 tickets × $40)", () => {
+    const result = computePromoterCompetitionEconomics({
+      ticketPriceCents: 4000,
+      salesGoal: 100,
+      milestones: baseMilestones,
+      rewardMode: PromoterRewardMode.TOTAL_AT_MILESTONE,
+    });
+
+    expect(result.grossPotentialRevenueCents).toBe(400000); // 4000 × 100
+  });
+
+  it("TOTAL_AT_MILESTONE: max cash exposure is the highest threshold CASH reward ($100)", () => {
+    const result = computePromoterCompetitionEconomics({
+      ticketPriceCents: 4000,
+      salesGoal: 100,
+      milestones: baseMilestones,
+      rewardMode: PromoterRewardMode.TOTAL_AT_MILESTONE,
+    });
+
+    expect(result.maxCashRewardExposureCents).toBe(10000); // $100 (not $15+$40+$100)
+  });
+
+  it("ADDITIVE: max cash exposure sums all threshold CASH rewards ($15 + $40 + $100 = $155)", () => {
+    const result = computePromoterCompetitionEconomics({
+      ticketPriceCents: 4000,
+      salesGoal: 100,
+      milestones: baseMilestones,
+      rewardMode: PromoterRewardMode.ADDITIVE,
+    });
+
+    expect(result.maxCashRewardExposureCents).toBe(15500); // 1500 + 4000 + 10000
+  });
+
+  it("rank=1 CASH reward adds to exposure on top of threshold rewards regardless of mode", () => {
+    const milestonesWithRank = [
+      ...baseMilestones,
+      { threshold: null, rank: 1, rewardType: PromoterRewardType.CASH, rewardAmountCents: 20000, rewardDescription: null },
+    ];
+
+    const totalAt = computePromoterCompetitionEconomics({
+      ticketPriceCents: 4000,
+      salesGoal: 100,
+      milestones: milestonesWithRank,
+      rewardMode: PromoterRewardMode.TOTAL_AT_MILESTONE,
+    });
+    // TOTAL_AT_MILESTONE: max threshold cash = $100 (10000) + rank cash = $200 (20000)
+    expect(totalAt.maxCashRewardExposureCents).toBe(10000 + 20000);
+
+    const additive = computePromoterCompetitionEconomics({
+      ticketPriceCents: 4000,
+      salesGoal: 100,
+      milestones: milestonesWithRank,
+      rewardMode: PromoterRewardMode.ADDITIVE,
+    });
+    // ADDITIVE: sum of threshold cash + rank cash
+    expect(additive.maxCashRewardExposureCents).toBe(15500 + 20000);
+  });
+
+  it("effectiveAcquisitionCostPct is expressed as a 0–100 percentage rounded to 1 decimal", () => {
+    // 10000 / 400000 = 0.025 → × 1000 = 25 → round → 25 → /10 = 2.5
+    const result = computePromoterCompetitionEconomics({
+      ticketPriceCents: 4000,
+      salesGoal: 100,
+      milestones: baseMilestones,
+      rewardMode: PromoterRewardMode.TOTAL_AT_MILESTONE,
+    });
+    expect(result.effectiveAcquisitionCostPct).toBe(2.5);
+  });
+
+  it("returns 0 for effectiveAcquisitionCostPct when salesGoal is 0 (no division-by-zero)", () => {
+    const result = computePromoterCompetitionEconomics({
+      ticketPriceCents: 4000,
+      salesGoal: 0,
+      milestones: baseMilestones,
+      rewardMode: PromoterRewardMode.ADDITIVE,
+    });
+    expect(result.effectiveAcquisitionCostPct).toBe(0);
+    expect(result.grossPotentialRevenueCents).toBe(0);
+  });
+
+  it("includes a rewardBreakdown array with threshold milestones sorted ascending before rank", () => {
+    const result = computePromoterCompetitionEconomics({
+      ticketPriceCents: 4000,
+      salesGoal: 100,
+      milestones: [
+        { threshold: 10, rank: null, rewardType: PromoterRewardType.CASH, rewardAmountCents: 4000, rewardDescription: null },
+        { threshold: null, rank: 1, rewardType: PromoterRewardType.CASH, rewardAmountCents: 20000, rewardDescription: null },
+        { threshold: 5, rank: null, rewardType: PromoterRewardType.CASH, rewardAmountCents: 1500, rewardDescription: null },
+      ],
+      rewardMode: PromoterRewardMode.ADDITIVE,
+    });
+
+    expect(result.rewardBreakdown).toHaveLength(3);
+    // threshold 5 first, threshold 10 second, rank 1 last
+    expect(result.rewardBreakdown[0].label).toBe("5 sales → $15");
+    expect(result.rewardBreakdown[1].label).toBe("10 sales → $40");
+    expect(result.rewardBreakdown[2].label).toBe("Top promoter → $200");
+  });
+});
+
+// ─── suggestPromoterSalesGoal ─────────────────────────────────────────────────
+
+describe("suggestPromoterSalesGoal", () => {
+  it("returns null when capacity is null", () => {
+    expect(suggestPromoterSalesGoal({ capacity: null, ticketsSold: 50 })).toBeNull();
+  });
+
+  it("returns null when capacity is 0 or negative", () => {
+    expect(suggestPromoterSalesGoal({ capacity: 0,  ticketsSold: 0 })).toBeNull();
+    expect(suggestPromoterSalesGoal({ capacity: -1, ticketsSold: 0 })).toBeNull();
+  });
+
+  it("returns null when venue is full (remaining = 0)", () => {
+    expect(suggestPromoterSalesGoal({ capacity: 200, ticketsSold: 200 })).toBeNull();
+  });
+
+  it("snaps to nearest benchmark: capacity=200, sold=27 → remaining=173 → target≈86 → 75", () => {
+    // target = 173 × 0.5 = 86.5
+    // distances: |86.5-75|=11.5, |86.5-100|=13.5 → 75 wins
+    const result = suggestPromoterSalesGoal({ capacity: 200, ticketsSold: 27 });
+    expect(result).toBe(75);
+  });
+
+  it("treats null ticketsSold as 0", () => {
+    // capacity=100, sold=null → remaining=100 → target=50 → snap to 50
+    const result = suggestPromoterSalesGoal({ capacity: 100, ticketsSold: null });
+    expect(result).toBe(50);
+  });
+
+  it("snaps to lowest benchmark (25) for very small remaining capacity", () => {
+    // capacity=50, sold=45 → remaining=5 → target=2.5 → nearest to 25 (all benchmarks > 5, so 25 wins)
+    const result = suggestPromoterSalesGoal({ capacity: 50, ticketsSold: 45 });
+    expect(result).toBe(25);
+  });
+});
+
+// ─── getPromoterReputationLabel ───────────────────────────────────────────────
+
+describe("getPromoterReputationLabel", () => {
+  const base = {
+    lifetimeQualifiedTickets: 0,
+    totalCompetitionsWon: 0,
+    totalEventsPromoted: 0,
+    repeatOrganizerCount: 0,
+    totalMilestonesReached: 0,
+  };
+
+  it("returns null when totalEventsPromoted is 0 (no promoter track record yet)", () => {
+    expect(getPromoterReputationLabel({ ...base, totalEventsPromoted: 0 })).toBeNull();
+  });
+
+  it("returns 'Competition Winner' when at least one competition was won", () => {
+    expect(
+      getPromoterReputationLabel({
+        ...base,
+        totalEventsPromoted: 1,
+        totalCompetitionsWon: 1,
+      })
+    ).toBe("Competition Winner");
+  });
+
+  it("returns '100+ Tickets Sold' when lifetimeQualifiedTickets >= 100 (and no competition win)", () => {
+    expect(
+      getPromoterReputationLabel({
+        ...base,
+        totalEventsPromoted: 2,
+        lifetimeQualifiedTickets: 100,
+      })
+    ).toBe("100+ Tickets Sold");
+  });
+
+  it("returns 'Repeat Collaborator' when worked with 2+ organizers (and lower-priority conditions unmet)", () => {
+    expect(
+      getPromoterReputationLabel({
+        ...base,
+        totalEventsPromoted: 2,
+        repeatOrganizerCount: 2,
+      })
+    ).toBe("Repeat Collaborator");
+  });
+
+  it("returns 'Experienced Promoter' when 3+ events promoted and no higher-priority label applies", () => {
+    expect(
+      getPromoterReputationLabel({
+        ...base,
+        totalEventsPromoted: 3,
+      })
+    ).toBe("Experienced Promoter");
+  });
+
+  it("returns 'Top Seller' when at least one milestone was reached and no higher-priority label applies", () => {
+    expect(
+      getPromoterReputationLabel({
+        ...base,
+        totalEventsPromoted: 1,
+        totalMilestonesReached: 1,
+      })
+    ).toBe("Top Seller");
+  });
+
+  it("returns null when promoted 1 event but no notable achievements", () => {
+    expect(
+      getPromoterReputationLabel({
+        ...base,
+        totalEventsPromoted: 1,
+      })
+    ).toBeNull();
+  });
+
+  it("respects priority order: Competition Winner beats 100+ Tickets Sold", () => {
+    expect(
+      getPromoterReputationLabel({
+        ...base,
+        totalEventsPromoted: 5,
+        totalCompetitionsWon: 1,
+        lifetimeQualifiedTickets: 500,
+      })
+    ).toBe("Competition Winner");
+  });
+});

package/src/accessScreening.ts

@@ -1,6 +1,14 @@
 /**
  * Event access screening — shared status values for API + app.
+ *
+ * Simple "Request access" (a note + host approve) is only for events that
+ * are not using the Application funnel. Application is the richer gate.
  */
+import {
+  eventHasApplication,
+  rsvpApplicationEnabled,
+} from "./applicationFunnel.js";
+
 export const ACCESS_REQUEST_STATUSES = [
   "None",
   "Pending",
@@ -11,6 +19,35 @@ export const ACCESS_REQUEST_STATUSES = [
 export type AccessRequestStatus =
   (typeof ACCESS_REQUEST_STATUSES)[number];
 
+export type AccessScreeningEventFlags = {
+  accessScreeningEnabled?: boolean | null;
+  applicationEnabled?: boolean | null;
+  entryMode?: string | null;
+  ticketTiers?: Array<{ requiresApplication?: boolean | null }> | null;
+};
+
+/**
+ * Event-wide note-only screening. False when Application is on so guests
+ * apply once instead of requesting access and then filling a form.
+ */
+export function accessScreeningApplies(
+  event: AccessScreeningEventFlags
+): boolean {
+  return Boolean(event.accessScreeningEnabled) && !eventHasApplication(event);
+}
+
+/**
+ * Host Access requests queue (ticketed). RSVP applications use Pending RSVPs.
+ */
+export function eventNeedsAccessRequestQueue(
+  event: AccessScreeningEventFlags
+): boolean {
+  if (rsvpApplicationEnabled(event)) return false;
+  if (accessScreeningApplies(event)) return true;
+  if (event.entryMode === "Rsvp") return false;
+  return eventHasApplication(event);
+}
+
 /** True when the viewer must complete access screening before tickets / affirmative RSVP. */
 export function accessScreeningBlocksAttendeeActions(
   enabled: boolean | undefined,
@@ -21,3 +58,15 @@ export function accessScreeningBlocksAttendeeActions(
   if (hasTicket) return false;
   return status !== "Approved";
 }
+
+export function accessScreeningBlocksAttendeeActionsForEvent(
+  event: AccessScreeningEventFlags,
+  status: AccessRequestStatus | null | undefined,
+  hasTicket: boolean
+): boolean {
+  return accessScreeningBlocksAttendeeActions(
+    accessScreeningApplies(event),
+    status,
+    hasTicket
+  );
+}

package/src/applicationFunnel.ts

@@ -0,0 +1,225 @@
+/**
+ * Host application funnel — shared evaluation for API + app.
+ * Choice questions can auto-deny or flag a mismatch; free text is review-only.
+ *
+ * Later Posh gaps (tracked, not in this module): bash-page screened badge /
+ * cover aesthetics, stronger host identity on Meet the host, who’s-going
+ * mutuals before apply, application analytics, AI screening assist (never
+ * auto-deny on LLM alone), waitlist → next approved applicant.
+ */
+
+export const QUESTION_MISMATCH_ACTIONS = [
+  "None",
+  "FlagForReview",
+  "AutoDeny",
+] as const;
+
+export type QuestionMismatchAction = (typeof QUESTION_MISMATCH_ACTIONS)[number];
+
+export const APPLICATION_QUESTION_TYPES = [
+  "ShortText",
+  "LongText",
+  "SingleChoice",
+  "MultiChoice",
+  "YesNo",
+] as const;
+
+export type ApplicationQuestionType =
+  (typeof APPLICATION_QUESTION_TYPES)[number];
+
+export type ApplicationFunnelQuestion = {
+  id: string;
+  type: ApplicationQuestionType;
+  required?: boolean;
+  ticketTierId?: string | null;
+  mismatchAction?: QuestionMismatchAction | null;
+  acceptableOptions?: string[] | null;
+  parentQuestionId?: string | null;
+  showWhenAnswer?: string | null;
+};
+
+export type ApplicationFunnelAnswer = {
+  questionId: string;
+  answer: string;
+};
+
+export type ApplicationFunnelEvaluation = {
+  outcome: "pass" | "flag" | "auto_deny";
+  flaggedQuestionIds: string[];
+  autoDenyQuestionIds: string[];
+};
+
+export function isChoiceQuestionType(
+  type: ApplicationQuestionType | string
+): boolean {
+  return (
+    type === "SingleChoice" || type === "MultiChoice" || type === "YesNo"
+  );
+}
+
+export function questionsForApplicationSurface<
+  T extends { ticketTierId?: string | null },
+>(questions: T[], ticketTierId: string | null): T[] {
+  return questions.filter(
+    (question) =>
+      question.ticketTierId == null || question.ticketTierId === ticketTierId
+  );
+}
+
+export function applicationsAreClosed(
+  closesAt: Date | string | null | undefined,
+  now: Date = new Date()
+): boolean {
+  if (!closesAt) return false;
+  const at = closesAt instanceof Date ? closesAt : new Date(closesAt);
+  if (Number.isNaN(at.getTime())) return false;
+  return now.getTime() > at.getTime();
+}
+
+export function isApplicationQuestionVisible(
+  question: ApplicationFunnelQuestion,
+  answers: ApplicationFunnelAnswer[],
+  allQuestions: ApplicationFunnelQuestion[],
+  seen: Set<string> = new Set()
+): boolean {
+  const parentId = question.parentQuestionId?.trim();
+  const when = question.showWhenAnswer?.trim();
+  if (!parentId || !when) return true;
+  if (seen.has(question.id)) return false;
+  seen.add(question.id);
+  const parent = allQuestions.find((row) => row.id === parentId);
+  if (parent && !isApplicationQuestionVisible(parent, answers, allQuestions, seen)) {
+    return false;
+  }
+  const raw = answers.find((row) => row.questionId === parentId)?.answer ?? "";
+  const parentType = parent?.type ?? "ShortText";
+  return answerValues(raw, parentType).some(
+    (value) => normalizeOption(value) === normalizeOption(when)
+  );
+}
+
+export function visibleApplicationQuestions<T extends ApplicationFunnelQuestion>(
+  questions: T[],
+  answers: ApplicationFunnelAnswer[]
+): T[] {
+  return questions.filter((question) =>
+    isApplicationQuestionVisible(question, answers, questions)
+  );
+}
+
+function normalizeOption(value: string): string {
+  return value.trim().toLowerCase();
+}
+
+function answerValues(
+  answer: string,
+  type: ApplicationQuestionType
+): string[] {
+  if (type === "MultiChoice") {
+    return answer
+      .split(",")
+      .map((part) => part.trim())
+      .filter(Boolean);
+  }
+  const trimmed = answer.trim();
+  return trimmed ? [trimmed] : [];
+}
+
+export function missingRequiredQuestionIds(
+  questions: ApplicationFunnelQuestion[],
+  answers: ApplicationFunnelAnswer[]
+): string[] {
+  const visible = visibleApplicationQuestions(questions, answers);
+  const byId = new Map(answers.map((row) => [row.questionId, row.answer]));
+  return visible
+    .filter((question) => question.required)
+    .filter((question) => {
+      const raw = byId.get(question.id) ?? "";
+      return answerValues(raw, question.type).length === 0;
+    })
+    .map((question) => question.id);
+}
+
+export function evaluateApplicationFunnel(
+  questions: ApplicationFunnelQuestion[],
+  answers: ApplicationFunnelAnswer[]
+): ApplicationFunnelEvaluation {
+  const byId = new Map(answers.map((row) => [row.questionId, row.answer]));
+  const flaggedQuestionIds: string[] = [];
+  const autoDenyQuestionIds: string[] = [];
+
+  const visible = visibleApplicationQuestions(questions, answers);
+  for (const question of visible) {
+    const action = question.mismatchAction ?? "None";
+    if (action === "None") continue;
+    if (!isChoiceQuestionType(question.type)) continue;
+    const acceptable = (question.acceptableOptions ?? [])
+      .map(normalizeOption)
+      .filter(Boolean);
+    if (acceptable.length === 0) continue;
+
+    const values = answerValues(byId.get(question.id) ?? "", question.type);
+    if (values.length === 0) continue;
+
+    const acceptableSet = new Set(acceptable);
+    const mismatch = values.some((value) => !acceptableSet.has(normalizeOption(value)));
+    if (!mismatch) continue;
+
+    if (action === "AutoDeny") {
+      autoDenyQuestionIds.push(question.id);
+    } else if (action === "FlagForReview") {
+      flaggedQuestionIds.push(question.id);
+    }
+  }
+
+  if (autoDenyQuestionIds.length > 0) {
+    return {
+      outcome: "auto_deny",
+      flaggedQuestionIds,
+      autoDenyQuestionIds,
+    };
+  }
+  if (flaggedQuestionIds.length > 0) {
+    return {
+      outcome: "flag",
+      flaggedQuestionIds,
+      autoDenyQuestionIds,
+    };
+  }
+  return {
+    outcome: "pass",
+    flaggedQuestionIds: [],
+    autoDenyQuestionIds: [],
+  };
+}
+
+export function eventHasApplication(event: {
+  applicationEnabled?: boolean | null;
+  ticketTiers?: Array<{ requiresApplication?: boolean | null }> | null;
+}): boolean {
+  if (event.applicationEnabled) return true;
+  return Boolean(event.ticketTiers?.some((tier) => tier.requiresApplication));
+}
+
+export function rsvpApplicationEnabled(event: {
+  applicationEnabled?: boolean | null;
+  entryMode?: string | null;
+}): boolean {
+  return event.entryMode === "Rsvp" && Boolean(event.applicationEnabled);
+}
+
+export function applicationBlocksTierPurchase(
+  tier: { requiresApplication?: boolean | null } | null | undefined,
+  status: string | null | undefined,
+  hasTicket: boolean
+): boolean {
+  if (hasTicket) return false;
+  if (!tier?.requiresApplication) return false;
+  return status !== "Approved";
+}
+
+export function selectedTiersRequireApplication(
+  tiers: Array<{ requiresApplication?: boolean | null }> | null | undefined
+): boolean {
+  return Boolean(tiers?.some((tier) => tier.requiresApplication));
+}