@bash-app/bash-common 30.260.1 → 30.262.0

package/src/ticketBnplPaymentMethods.ts

@@ -0,0 +1,79 @@
+/**
+ * Stripe Checkout BNPL (Klarna, Afterpay/Clearpay) for paid ticket orders.
+ * Pure functions — safe for SSR/tests; no IO.
+ *
+ * @see ADR-011, api/docs/STRIPE_PAYMENT_LINKS_INSTALLMENTS.md
+ */
+
+export type TicketCheckoutPaymentMethodType =
+  | "card"
+  | "link"
+  | "klarna"
+  | "afterpay_clearpay"
+  | "cashapp";
+
+/** USD floors/ceilings aligned with typical Stripe BNPL eligibility (conservative). */
+export const TICKET_BNPL_MIN_CENTS_USD = 3_500; // $35
+export const TICKET_BNPL_MAX_CENTS_USD = 4_000_00; // $4,000 (Afterpay US Pay in 4 band)
+
+export interface TicketBnplPaymentMethodInput {
+  /** Per-event host toggle (`BashEvent.installmentsEnabled`). */
+  installmentsEnabled: boolean;
+  /** Per-event host toggle (`BashEvent.cashAppEnabled`). */
+  cashAppEnabled?: boolean;
+  /** Buyer total charged at checkout (tickets + guest-visible fees), in cents. */
+  totalChargedCents: number;
+  /** ISO currency lowercase, e.g. "usd". */
+  currency: string;
+  /** Platform kill switch (API env `TICKET_BNPL_ENABLED`). Default true in tests. */
+  bnplGloballyEnabled?: boolean;
+  /** Platform kill switch (API env `TICKET_CASHAPP_ENABLED`). Default true in tests. */
+  cashAppGloballyEnabled?: boolean;
+}
+
+/**
+ * Resolve `payment_method_types` for Stripe Checkout ticket sessions.
+ * BNPL is offered only when the host enabled installments and the order is in range.
+ */
+export function resolveTicketCheckoutPaymentMethodTypes(
+  input: TicketBnplPaymentMethodInput
+): TicketCheckoutPaymentMethodType[] {
+  const base: TicketCheckoutPaymentMethodType[] = ["card", "link"];
+  const methods = new Set<TicketCheckoutPaymentMethodType>(base);
+
+  const globallyBnplOn = input.bnplGloballyEnabled !== false;
+  const globallyCashAppOn = input.cashAppGloballyEnabled !== false;
+  const isUsd = input.currency.toLowerCase() === "usd";
+  const cents = input.totalChargedCents;
+
+  if (
+    globallyBnplOn &&
+    input.installmentsEnabled &&
+    isUsd &&
+    cents >= TICKET_BNPL_MIN_CENTS_USD &&
+    cents <= TICKET_BNPL_MAX_CENTS_USD
+  ) {
+    methods.add("klarna");
+    methods.add("afterpay_clearpay");
+  }
+
+  if (globallyCashAppOn && input.cashAppEnabled && isUsd && cents > 0) {
+    methods.add("cashapp");
+  }
+
+  return [...methods];
+}
+
+export function ticketCheckoutOffersBnpl(
+  input: TicketBnplPaymentMethodInput
+): boolean {
+  const methods = resolveTicketCheckoutPaymentMethodTypes(input);
+  return methods.includes("klarna");
+}
+
+export function ticketCheckoutOffersCashApp(
+  input: TicketBnplPaymentMethodInput
+): boolean {
+  const methods = resolveTicketCheckoutPaymentMethodTypes(input);
+  return methods.includes("cashapp");
+}

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

@@ -0,0 +1,120 @@
+import {
+  haversineMiles,
+  effectiveFeaturedForGeoScope,
+  sortPublicEventsForFeaturedDiscovery,
+} from "../featuredDiscoveryGeo.js";
+
+describe("haversineMiles", () => {
+  it("returns zero for identical coordinates", () => {
+    expect(haversineMiles(40.7128, -74.006, 40.7128, -74.006)).toBeCloseTo(0, 5);
+  });
+
+  it("computes a plausible distance between NYC and Philadelphia", () => {
+    const miles = haversineMiles(40.7128, -74.006, 39.9526, -75.1652);
+    expect(miles).toBeGreaterThan(75);
+    expect(miles).toBeLessThan(100);
+  });
+});
+
+describe("effectiveFeaturedForGeoScope", () => {
+  const viewer = { lat: 40.7128, lng: -74.006, radiusMiles: 10 };
+
+  it("returns false when event is not featured", () => {
+    expect(effectiveFeaturedForGeoScope(false, [{ lat: 40.71, lng: -74.0 }], viewer)).toBe(false);
+  });
+
+  it("returns true for featured events when no viewer geo is provided", () => {
+    expect(effectiveFeaturedForGeoScope(true, [{ lat: 40.71, lng: -74.0 }], undefined)).toBe(true);
+  });
+
+  it("returns false when featured event has no coordinates", () => {
+    expect(effectiveFeaturedForGeoScope(true, [{ lat: null, lng: null }], viewer)).toBe(false);
+    expect(effectiveFeaturedForGeoScope(true, [], viewer)).toBe(false);
+  });
+
+  it("returns true when featured event is within viewer radius", () => {
+    expect(
+      effectiveFeaturedForGeoScope(true, [{ lat: 40.72, lng: -74.01 }], viewer)
+    ).toBe(true);
+  });
+
+  it("returns false when featured event is outside viewer radius", () => {
+    expect(
+      effectiveFeaturedForGeoScope(true, [{ lat: 34.0522, lng: -118.2437 }], viewer)
+    ).toBe(false);
+  });
+});
+
+describe("sortPublicEventsForFeaturedDiscovery", () => {
+  const viewer = { lat: 40.7128, lng: -74.006, radiusMiles: 10 };
+
+  it("sorts effective featured events before non-featured", () => {
+    const events = [
+      {
+        id: "b",
+        isFeatured: false,
+        featuredUntil: null,
+        startDateTime: "2026-06-02T00:00:00Z",
+        coordinates: [{ lat: 40.72, lng: -74.01 }],
+      },
+      {
+        id: "a",
+        isFeatured: true,
+        featuredUntil: null,
+        startDateTime: "2026-06-01T00:00:00Z",
+        coordinates: [{ lat: 40.72, lng: -74.01 }],
+      },
+    ];
+
+    const sorted = sortPublicEventsForFeaturedDiscovery(events, viewer);
+    expect(sorted.map((e) => e.id)).toEqual(["a", "b"]);
+  });
+
+  it("sorts by startDateTime within the same featured bucket", () => {
+    const events = [
+      {
+        id: "late",
+        isFeatured: true,
+        featuredUntil: null,
+        startDateTime: "2026-06-03T00:00:00Z",
+        coordinates: [{ lat: 40.72, lng: -74.01 }],
+      },
+      {
+        id: "early",
+        isFeatured: true,
+        featuredUntil: null,
+        startDateTime: "2026-06-01T00:00:00Z",
+        coordinates: [{ lat: 40.72, lng: -74.01 }],
+      },
+    ];
+
+    expect(sortPublicEventsForFeaturedDiscovery(events, viewer).map((e) => e.id)).toEqual([
+      "early",
+      "late",
+    ]);
+  });
+
+  it("treats out-of-scope featured events as non-featured for ordering", () => {
+    const events = [
+      {
+        id: "far-featured",
+        isFeatured: true,
+        featuredUntil: null,
+        startDateTime: "2026-06-01T00:00:00Z",
+        coordinates: [{ lat: 34.05, lng: -118.24 }],
+      },
+      {
+        id: "local-regular",
+        isFeatured: false,
+        featuredUntil: null,
+        startDateTime: "2026-06-02T00:00:00Z",
+        coordinates: [{ lat: 40.72, lng: -74.01 }],
+      },
+    ];
+
+    expect(sortPublicEventsForFeaturedDiscovery(events, viewer).map((e) => e.id)).toEqual([
+      "far-featured",
+      "local-regular",
+    ]);
+  });
+});

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

@@ -18,6 +18,9 @@ import {
   FLYER_SPONSOR_LOGO_ALT_MAX_LENGTH,
   FLYER_SPONSOR_LOGO_MAX_BYTES,
   validateFlyerSponsorCreative,
+  flyerSponsorSlotPriceCents,
+  flyerSponsorSlotHostPct,
+  flyerSponsorSlotLabel,
 } from "../flyerUtils.js";
 
 describe("flyerUtils", () => {
@@ -89,6 +92,13 @@ describe("flyerUtils", () => {
     ]);
   });
 
+  it("flyerSponsorSlotPriceCents and host pct follow slot type", () => {
+    expect(flyerSponsorSlotPriceCents("FEATURED")).toBe(10000);
+    expect(flyerSponsorSlotPriceCents("SUPPORTING_1")).toBe(5000);
+    expect(flyerSponsorSlotHostPct("FEATURED")).toBe(0.6);
+    expect(flyerSponsorSlotLabel("FEATURED")).toBe("Featured");
+  });
+
   it("validates sponsor creative text limits and trims fields before checking", () => {
     expect(
       validateFlyerSponsorCreative({

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

@@ -0,0 +1,128 @@
+import {
+  capRosterDepthForEventMode,
+  filterHiddenVisibilityUserIds,
+  orderPreviewAttendeeIds,
+  resolveEffectiveEventMode,
+  resolveGuestSurfacePolicy,
+  viewerMayFetchFullRoster,
+  maxGuestListDepth,
+} from "../guestSurface.js";
+
+describe("resolveEffectiveEventMode", () => {
+  it("maps legacy showAttendees false to Hidden", () => {
+    expect(resolveEffectiveEventMode({ showAttendees: false })).toBe("Hidden");
+  });
+
+  it("honours CountOnly", () => {
+    expect(
+      resolveEffectiveEventMode({ attendeeDisplayMode: "CountOnly" })
+    ).toBe("CountOnly");
+  });
+});
+
+describe("resolveGuestSurfacePolicy", () => {
+  it("Hidden mode hides everything for public viewers", () => {
+    const policy = resolveGuestSurfacePolicy({
+      eventMode: "Hidden",
+      isHost: false,
+      isAuthenticated: true,
+      viewerRosterDepth: "Full",
+    });
+    expect(policy.showCount).toBe(false);
+    expect(policy.showPreviewAvatars).toBe(false);
+  });
+
+  it("CountOnly shows count but not avatars", () => {
+    const policy = resolveGuestSurfacePolicy({
+      eventMode: "CountOnly",
+      isHost: false,
+      isAuthenticated: false,
+      viewerRosterDepth: "None",
+    });
+    expect(policy.showCount).toBe(true);
+    expect(policy.showPreviewAvatars).toBe(false);
+  });
+
+  it("All mode shows curated preview", () => {
+    const policy = resolveGuestSurfacePolicy({
+      eventMode: "All",
+      isHost: false,
+      isAuthenticated: true,
+      viewerRosterDepth: "None",
+    });
+    expect(policy.showPreviewAvatars).toBe(true);
+    expect(policy.showNetworkSlice).toBe(true);
+  });
+});
+
+describe("viewerMayFetchFullRoster", () => {
+  it("denies non-host with None depth", () => {
+    expect(
+      viewerMayFetchFullRoster({ isHost: false, viewerRosterDepth: "None" })
+    ).toBe(false);
+  });
+
+  it("allows host", () => {
+    expect(
+      viewerMayFetchFullRoster({ isHost: true, viewerRosterDepth: "None" })
+    ).toBe(true);
+  });
+
+  it("allows VIP Partial depth", () => {
+    expect(
+      viewerMayFetchFullRoster({ isHost: false, viewerRosterDepth: "Partial" })
+    ).toBe(true);
+  });
+});
+
+describe("orderPreviewAttendeeIds", () => {
+  it("puts featured first then by recency", () => {
+    const ids = orderPreviewAttendeeIds(
+      [
+        { userId: "a", paidOn: "2026-01-01" },
+        { userId: "b", paidOn: "2026-06-01" },
+        { userId: "c", paidOn: "2026-03-01" },
+      ],
+      ["a"],
+      10
+    );
+    expect(ids[0]).toBe("a");
+    expect(ids[1]).toBe("b");
+  });
+});
+
+describe("maxGuestListDepth", () => {
+  it("picks highest depth", () => {
+    expect(maxGuestListDepth("None", "Partial", "Full")).toBe("Full");
+  });
+});
+
+describe("capRosterDepthForEventMode", () => {
+  it("caps VIP to None when event is NetworkOnly", () => {
+    expect(
+      capRosterDepthForEventMode("Full", "NetworkOnly", false)
+    ).toBe("None");
+  });
+});
+
+describe("filterHiddenVisibilityUserIds", () => {
+  it("hides FeaturedInvited from public preview", () => {
+    const map = new Map([
+      ["a", "Visible" as const],
+      ["b", "FeaturedInvited" as const],
+      ["c", "FeaturedPending" as const],
+    ]);
+    expect(filterHiddenVisibilityUserIds(["a", "b", "c"], map, false)).toEqual([
+      "a",
+      "c",
+    ]);
+  });
+
+  it("shows all ids to host including FeaturedInvited", () => {
+    const map = new Map([["b", "FeaturedInvited" as const]]);
+    expect(filterHiddenVisibilityUserIds(["a", "b"], map, true)).toEqual([
+      "a",
+      "b",
+    ]);
+  });
+});

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

@@ -0,0 +1,131 @@
+import {
+  isTicketTierGuestListVisible,
+  resolveTicketTierScheduleState,
+  scheduleValidationHasErrors,
+  validateTicketTierScheduleInput,
+} from "../ticketTierSchedule.js";
+
+describe("resolveTicketTierScheduleState", () => {
+  const future = new Date("2030-06-01T18:00:00.000Z");
+  const past = new Date("2020-01-01T12:00:00.000Z");
+  const now = new Date("2030-05-01T12:00:00.000Z");
+
+  it("returns Live for immediate tier with inventory", () => {
+    const state = resolveTicketTierScheduleState(
+      { availabilityType: "Immediate" },
+      { now, availableInventory: 10 }
+    );
+    expect(state.phase).toBe("Live");
+    expect(state.canPurchase).toBe(true);
+  });
+
+  it("does not treat missing inventory as sold out", () => {
+    const state = resolveTicketTierScheduleState(
+      { availabilityType: "Immediate" },
+      { now }
+    );
+    expect(state.phase).toBe("Live");
+    expect(state.soldOut).toBe(false);
+    expect(state.hostPreviewLabel).toBe("Live");
+  });
+
+  it("returns TeasePreRelease before OnDate", () => {
+    const state = resolveTicketTierScheduleState(
+      {
+        availabilityType: "OnDate",
+        availableAt: future,
+        preReleaseDisplay: "Tease",
+      },
+      { now, availableInventory: 10 }
+    );
+    expect(state.phase).toBe("TeasePreRelease");
+    expect(state.canPurchase).toBe(false);
+    expect(state.availability.reason).toBe("OnDate");
+    expect(isTicketTierGuestListVisible(state)).toBe(true);
+  });
+
+  it("returns HiddenPreRelease when preReleaseDisplay is Hidden", () => {
+    const state = resolveTicketTierScheduleState(
+      {
+        availabilityType: "OnDate",
+        availableAt: future,
+        preReleaseDisplay: "Hidden",
+      },
+      { now, availableInventory: 10 }
+    );
+    expect(state.phase).toBe("HiddenPreRelease");
+    expect(isTicketTierGuestListVisible(state)).toBe(false);
+  });
+
+  it("returns Expired after expiresAt", () => {
+    const state = resolveTicketTierScheduleState(
+      { expiresAt: past },
+      { now, availableInventory: 10 }
+    );
+    expect(state.phase).toBe("Expired");
+    expect(state.canPurchase).toBe(false);
+  });
+
+  it("returns SoldOut when manually sold out", () => {
+    const state = resolveTicketTierScheduleState(
+      { isManuallySoldOut: true },
+      { now, availableInventory: 50 }
+    );
+    expect(state.phase).toBe("SoldOut");
+    expect(state.showWaitlistCta).toBe(false);
+  });
+
+  it("shows waitlist CTA when sold out and waitlist tier", () => {
+    const state = resolveTicketTierScheduleState(
+      { isWaitlistTier: true },
+      { now, availableInventory: 0 }
+    );
+    expect(state.phase).toBe("SoldOut");
+    expect(state.showWaitlistCta).toBe(true);
+  });
+
+  it("blocks EngagedUsersOnly when viewer not engaged", () => {
+    const state = resolveTicketTierScheduleState(
+      { availabilityType: "EngagedUsersOnly" },
+      { now, availableInventory: 5, isViewerEngaged: false }
+    );
+    expect(state.canPurchase).toBe(false);
+    expect(state.availability.reason).toBe("EngagedUsersOnly");
+  });
+
+  it("UnlockWhenTicketsSold unlocks at threshold", () => {
+    const locked = resolveTicketTierScheduleState(
+      {
+        availabilityType: "UnlockWhenTicketsSold",
+        unlockWhenTicketsSold: 50,
+      },
+      { now, availableInventory: 10, ticketsSoldCount: 10 }
+    );
+    expect(locked.canPurchase).toBe(false);
+
+    const open = resolveTicketTierScheduleState(
+      {
+        availabilityType: "UnlockWhenTicketsSold",
+        unlockWhenTicketsSold: 50,
+      },
+      { now, availableInventory: 10, ticketsSoldCount: 50 }
+    );
+    expect(open.canPurchase).toBe(true);
+  });
+});
+
+describe("validateTicketTierScheduleInput", () => {
+  it("requires availableAt for OnDate", () => {
+    const issues = validateTicketTierScheduleInput({ availabilityType: "OnDate" });
+    expect(scheduleValidationHasErrors(issues)).toBe(true);
+  });
+
+  it("rejects expires before release", () => {
+    const issues = validateTicketTierScheduleInput({
+      availabilityType: "OnDate",
+      availableAt: new Date("2030-06-02T12:00:00Z"),
+      expiresAt: new Date("2030-06-01T12:00:00Z"),
+    });
+    expect(scheduleValidationHasErrors(issues)).toBe(true);
+  });
+});

package/src/utils/featuredDiscoveryGeo.ts

@@ -0,0 +1,75 @@
+/** Default featured-discovery radius when the client omits `featuredRadiusMiles`. */
+export const DEFAULT_FEATURED_RADIUS_MILES = 200;
+
+/**
+ * Haversine distance in miles between two WGS84 points.
+ */
+export function haversineMiles(
+  lat1: number,
+  lng1: number,
+  lat2: number,
+  lng2: number
+): number {
+  const R = 3958.8;
+  const dLat = ((lat2 - lat1) * Math.PI) / 180;
+  const dLng = ((lng2 - lng1) * Math.PI) / 180;
+  const a =
+    Math.sin(dLat / 2) * Math.sin(dLat / 2) +
+    Math.cos((lat1 * Math.PI) / 180) *
+      Math.cos((lat2 * Math.PI) / 180) *
+      Math.sin(dLng / 2) *
+      Math.sin(dLng / 2);
+  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+  return R * c;
+}
+
+export interface ViewerGeoScope {
+  lat: number;
+  lng: number;
+  radiusMiles: number;
+}
+
+export function effectiveFeaturedForGeoScope(
+  isFeatured: boolean,
+  coordinates: Array<{ lat: number | null; lng: number | null }> | null | undefined,
+  viewer: ViewerGeoScope | undefined
+): boolean {
+  if (!isFeatured) return false;
+  if (!viewer) return true;
+  const first = coordinates?.find((c) => c.lat != null && c.lng != null);
+  if (!first || first.lat == null || first.lng == null) return false;
+  const d = haversineMiles(first.lat, first.lng, viewer.lat, viewer.lng);
+  return d <= viewer.radiusMiles;
+}
+
+export type EventWithFeaturedAndCoords = {
+  id: string;
+  isFeatured: boolean | null;
+  featuredUntil?: Date | null;
+  startDateTime: Date | string | null;
+  coordinates?: Array<{ lat: number | null; lng: number | null }> | null;
+};
+
+/**
+ * Sort: effective featured (in geo scope if viewer set) first, then by startDateTime.
+ */
+export function sortPublicEventsForFeaturedDiscovery<
+  T extends EventWithFeaturedAndCoords,
+>(events: T[], viewer: ViewerGeoScope | undefined): T[] {
+  const withKeys = events.map((e) => {
+    const eff = effectiveFeaturedForGeoScope(
+      !!e.isFeatured,
+      e.coordinates,
+      viewer
+    );
+    const start = e.startDateTime
+      ? new Date(e.startDateTime as Date | string).getTime()
+      : 0;
+    return { e, eff, start };
+  });
+  withKeys.sort((a, b) => {
+    if (a.eff !== b.eff) return (b.eff ? 1 : 0) - (a.eff ? 1 : 0);
+    return a.start - b.start;
+  });
+  return withKeys.map((x) => x.e);
+}

package/src/utils/flyerUtils.ts

@@ -158,6 +158,39 @@ export function computeHostTotalAfterSponsors(
   return Math.max(0, printPostageCostCents - sponsorRevenueCents);
 }
 
+/** Default slot price in cents for Featured vs Supporting flyer slots. */
+export function flyerSponsorSlotPriceCents(
+  slot: "FEATURED" | "SUPPORTING_1" | "SUPPORTING_2",
+  requestedPrice?: number
+): number {
+  if (requestedPrice != null) return requestedPrice;
+  return slot === "FEATURED"
+    ? FLYER_SPONSOR_DEFAULT_FEATURED_CENTS
+    : FLYER_SPONSOR_DEFAULT_SUPPORTING_CENTS;
+}
+
+/** Host revenue share for a flyer sponsor slot. */
+export function flyerSponsorSlotHostPct(
+  slot: "FEATURED" | "SUPPORTING_1" | "SUPPORTING_2"
+): number {
+  return slot === "FEATURED" ? 0.6 : 0.65;
+}
+
+export function flyerSponsorSlotLabel(
+  slot: "FEATURED" | "SUPPORTING_1" | "SUPPORTING_2"
+): string {
+  switch (slot) {
+    case "FEATURED":
+      return "Featured";
+    case "SUPPORTING_1":
+      return "Supporting 1";
+    case "SUPPORTING_2":
+      return "Supporting 2";
+    default:
+      return slot;
+  }
+}
+
 const EARTH_RADIUS_MI = 3958.8;
 
 /** Haversine distance in miles between two WGS84 points. */