@bash-app/bash-common 30.285.0 → 30.289.0

package/src/utils/entertainmentDrawFit.ts

@@ -0,0 +1,180 @@
+import type { AmountOfGuests } from "@prisma/client";
+
+export type CrowdSizeLike = Pick<
+  AmountOfGuests,
+  | "minimum"
+  | "ideal"
+  | "expected"
+  | "showMinimumGuests"
+  | "showIdealGuests"
+  | "showExpectedGuests"
+> | null | undefined;
+
+export type VenueCapacityLike = {
+  capacity?: number | null;
+  anticipatedAttendees?: number | null;
+} | null | undefined;
+
+/** Effective draw the entertainer shares publicly, or best estimate from preferences. */
+export function getEntertainerEffectiveDraw(
+  crowdSize: CrowdSizeLike
+): number | null {
+  if (!crowdSize) return null;
+
+  if (
+    crowdSize.showExpectedGuests &&
+    crowdSize.expected != null &&
+    crowdSize.expected > 0
+  ) {
+    return crowdSize.expected;
+  }
+
+  if (crowdSize.showIdealGuests && crowdSize.ideal != null && crowdSize.ideal > 0) {
+    return crowdSize.ideal;
+  }
+
+  if (
+    crowdSize.showMinimumGuests &&
+    crowdSize.minimum != null &&
+    crowdSize.minimum > 0
+  ) {
+    return crowdSize.minimum;
+  }
+
+  return null;
+}
+
+export function getVenueEffectiveCapacity(
+  venue: VenueCapacityLike
+): number | null {
+  if (!venue) return null;
+  const capacity = venue.capacity ?? venue.anticipatedAttendees;
+  return capacity != null && capacity > 0 ? capacity : null;
+}
+
+export interface DrawCapacityFitResult {
+  points: number;
+  maxPoints: number;
+  reason?: string;
+}
+
+/**
+ * Score how well an entertainer's draw fits a venue's capacity (0–15 points).
+ * Partial credit when only one side has data.
+ */
+export function scoreDrawCapacityFit(
+  venue: VenueCapacityLike,
+  crowdSize: CrowdSizeLike
+): DrawCapacityFitResult {
+  const maxPoints = 15;
+  const venueCapacity = getVenueEffectiveCapacity(venue);
+  const draw = getEntertainerEffectiveDraw(crowdSize);
+
+  if (!venueCapacity && !draw) {
+    return { points: 3, maxPoints, reason: "Draw and capacity not specified" };
+  }
+
+  if (!venueCapacity || !draw) {
+    return {
+      points: 5,
+      maxPoints,
+      reason: venueCapacity
+        ? "Entertainer draw not specified"
+        : "Venue capacity not specified",
+    };
+  }
+
+  const ratio = draw / venueCapacity;
+
+  if (ratio >= 0.2 && ratio <= 1.25) {
+    return {
+      points: maxPoints,
+      maxPoints,
+      reason: `Draw (~${draw}) fits venue capacity (~${venueCapacity})`,
+    };
+  }
+
+  if (ratio > 1.25 && ratio <= 1.75) {
+    return {
+      points: 8,
+      maxPoints,
+      reason: `Draw (~${draw}) slightly above capacity (~${venueCapacity})`,
+    };
+  }
+
+  if (ratio < 0.2 && ratio >= 0.05) {
+    return {
+      points: 7,
+      maxPoints,
+      reason: `Draw (~${draw}) modest for venue size (~${venueCapacity})`,
+    };
+  }
+
+  return {
+    points: 2,
+    maxPoints,
+    reason: `Draw (~${draw}) and capacity (~${venueCapacity}) may not align`,
+  };
+}
+
+/**
+ * Host browse filter: expected guest count vs entertainer's shared draw.
+ * When entertainer has no draw data, do not exclude them.
+ */
+export function entertainerFitsHostExpectedCrowd(
+  hostExpectedGuests: number,
+  crowdSize: CrowdSizeLike
+): boolean {
+  if (!Number.isFinite(hostExpectedGuests) || hostExpectedGuests <= 0) {
+    return true;
+  }
+
+  const draw = getEntertainerEffectiveDraw(crowdSize);
+  if (draw == null) {
+    return true;
+  }
+
+  const low = hostExpectedGuests * 0.2;
+  const high = hostExpectedGuests * 2.5;
+  return draw >= low && draw <= high;
+}
+
+function normalizeVenueName(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/** Fuzzy match venue listing name against entertainer's notable venue names. */
+export function findNotableVenueNameMatch(
+  venueServiceName: string | null | undefined,
+  notableVenuesPerformed: string[] | null | undefined,
+  showNotableVenuesPerformed?: boolean
+): string | null {
+  if (!showNotableVenuesPerformed) {
+    return null;
+  }
+
+  if (!venueServiceName?.trim() || !notableVenuesPerformed?.length) {
+    return null;
+  }
+
+  const normalizedVenue = normalizeVenueName(venueServiceName);
+  if (!normalizedVenue) return null;
+
+  for (const notable of notableVenuesPerformed) {
+    const normalizedNotable = normalizeVenueName(notable);
+    if (!normalizedNotable) continue;
+
+    if (
+      normalizedVenue.includes(normalizedNotable) ||
+      normalizedNotable.includes(normalizedVenue)
+    ) {
+      return notable.trim();
+    }
+  }
+
+  return null;
+}

package/src/utils/guestSurface.ts

@@ -20,7 +20,11 @@ export type AttendeeVisibility =
 export type GuestListDepth = "None" | "Partial" | "Full";
 
 /** Who may see the full attendee roster on the bash detail page (Layer 1). */
-export type AttendeeListAccess = "Preview" | "Public" | "TicketHolders";
+export type AttendeeListAccess =
+  | "Preview"
+  | "Public"
+  | "TicketHolders"
+  | "RsvpGoing";
 
 export type { PublicTeaserUser };
 
@@ -35,7 +39,12 @@ export type NetworkOverlapPayload = {
 };
 
 export type GuestSurfacePayload = {
-  count: { totalTickets: number; visibleAttendees: number };
+  count: {
+    totalTickets: number;
+    visibleAttendees: number;
+    /** Going RSVPs on Rsvp-mode events (ticket count may be 0). */
+    rsvpGoingCount?: number;
+  };
   preview: PublicTeaserUser[];
   featured: PublicTeaserUser[];
   featuredHeadline: string | null;
@@ -65,6 +74,14 @@ export type GuestSurfacePayload = {
   attendeeListPublic?: boolean;
   /** Preview | Public | TicketHolders — supersedes attendeeListPublic when set */
   attendeeListAccess?: string | null;
+  /**
+   * When set, the viewer sees a blurred preview and must RSVP (or buy a ticket)
+   * to unlock the full attendee list.
+   */
+  listLock?: {
+    reason: "rsvp_required" | "ticket_required";
+    goingCount: number;
+  } | null;
 };
 
 export type AttendeeRosterMeta = {
@@ -109,7 +126,7 @@ export function resolveAttendeeListAccess(event: {
   attendeeListPublic?: boolean | null;
 }): AttendeeListAccess {
   const raw = event.attendeeListAccess;
-  if (raw === "Public" || raw === "TicketHolders" || raw === "Preview") {
+  if (raw === "Public" || raw === "TicketHolders" || raw === "Preview" || raw === "RsvpGoing") {
     return raw;
   }
   return event.attendeeListPublic ? "Public" : "Preview";

package/src/utils/locationVisibility.ts

@@ -17,6 +17,11 @@ export type ViewerLocationContext = {
   viewerOwnsValidTicket: boolean;
   viewerPublicRsvpGoing: boolean;
   viewerHasAcceptedInvitation: boolean;
+  /**
+   * Active guest-session grant with status Going for this event (no password account).
+   * Mirrors viewerPublicRsvpGoing for location unlock when hideLocation is on.
+   */
+  viewerGuestRsvpGoing?: boolean;
 };
 
 const VALID_TICKET_STATUSES_EXCLUDED = new Set(["Cancelled", "WaitlistPending"]);
@@ -47,7 +52,9 @@ export function viewerCanSeeFullBashLocation(
   if (!bash.hideLocation) return true;
   if (bash.locationRevealedAt) return true;
   if (ctx.isHostOrOrganizer) return true;
-  if (!ctx.viewerUserId) return false;
+
+  const guestGoing = ctx.viewerGuestRsvpGoing === true;
+  if (!ctx.viewerUserId && !guestGoing) return false;
 
   const audience = bash.locationRevealAudience ?? "TicketHolders";
 
@@ -55,8 +62,10 @@ export function viewerCanSeeFullBashLocation(
 
   if (audience === "TicketHolders") return false;
 
+  const rsvpGoing = ctx.viewerPublicRsvpGoing || guestGoing;
+
   if (audience === "TicketHoldersAndRsvps" || audience === "TicketHoldersAndInvited") {
-    if (ctx.viewerPublicRsvpGoing) return true;
+    if (rsvpGoing) return true;
   }
 
   if (audience === "TicketHoldersAndInvited" && ctx.viewerHasAcceptedInvitation) {

package/src/utils/organizationEntitlements.ts

@@ -0,0 +1,37 @@
+/**
+ * Organization plan entitlements (pure predicates shared by api + bash-app).
+ *
+ * Keep these free of Prisma/DB access so both the frontend (gating UI + subdomain
+ * routing) and backend (SSR + API responses) evaluate the same rules. Pass only the
+ * subscription fields, not a full Prisma model, so partial selects work everywhere.
+ */
+
+/** Subscription statuses where a paid plan's perks are considered live. */
+export const ACTIVE_ORG_SUBSCRIPTION_STATUSES = [
+  "Active",
+  "Trialing",
+] as const;
+
+export interface OrganizationEntitlementInput {
+  subscriptionTier?: string | null;
+  subscriptionStatus?: string | null;
+}
+
+/**
+ * Vanity subdomains ({slug}.bash.community) are an Enterprise-only perk. All other
+ * orgs use the canonical path URL (bash.community/org/{slug}). Requires an active
+ * (or trialing) subscription so a lapsed Enterprise org falls back to the path.
+ */
+export function organizationHasVanitySubdomain(
+  org: OrganizationEntitlementInput | null | undefined
+): boolean {
+  if (!org) return false;
+  if (org.subscriptionTier !== "Enterprise") return false;
+  // Treat a missing status as active: legacy/ops-provisioned Enterprise orgs may
+  // predate subscriptionStatus being populated, and we don't want to silently
+  // drop their vanity domain.
+  if (org.subscriptionStatus == null) return true;
+  return (ACTIVE_ORG_SUBSCRIPTION_STATUSES as readonly string[]).includes(
+    org.subscriptionStatus
+  );
+}

package/src/utils/reputationUtils.ts

@@ -0,0 +1,94 @@
+/**
+ * Unified reputation summary across actor types (hosts, services/venues/artists).
+ *
+ * Stars on profiles show the raw average; leaderboards and cross-actor comparisons
+ * use a Bayesian-adjusted score so a 5.0 from two people doesn't outrank a 4.8
+ * from two hundred (see the Ratings explainer copy). Keeping the math here means
+ * host and service reputation stay consistent without duplicating the formula.
+ */
+
+export type ReputationActorType = "host" | "service" | "venue" | "artist";
+
+export interface ReputationSummary {
+  actorType: ReputationActorType;
+  /** Raw average rating (0–5), or null when there isn't enough signal. */
+  averageRating: number | null;
+  /** Number of ratings behind the average. */
+  totalRatings: number;
+  /** Bayesian-adjusted score (0–5) for ranking; null below the minimum. */
+  bayesianScore: number | null;
+  /** Whether there are enough ratings to show stars publicly. */
+  hasEnoughSignal: boolean;
+}
+
+/** Below this many ratings we don't show a star number (avoids misleading 5.0s). */
+export const MIN_RATINGS_FOR_DISPLAY = 3;
+
+/** Prior strength (how many "virtual" average-rated reviews to blend in). */
+const BAYESIAN_PRIOR_COUNT = 10;
+/** Prior mean — the platform's assumed baseline rating. */
+const BAYESIAN_PRIOR_MEAN = 4.0;
+
+/**
+ * Bayesian average: pulls low-volume ratings toward the prior mean, so a couple
+ * of glowing reviews can't outrank a large, consistently-strong record.
+ */
+export function bayesianAverage(
+  averageRating: number | null | undefined,
+  totalRatings: number | null | undefined,
+  opts: { priorCount?: number; priorMean?: number } = {}
+): number | null {
+  const avg = averageRating ?? 0;
+  const count = totalRatings ?? 0;
+  if (count <= 0) return null;
+  const priorCount = opts.priorCount ?? BAYESIAN_PRIOR_COUNT;
+  const priorMean = opts.priorMean ?? BAYESIAN_PRIOR_MEAN;
+  const score = (priorCount * priorMean + count * avg) / (priorCount + count);
+  return Math.round(score * 100) / 100;
+}
+
+/** Build a normalized reputation summary from a rating + count pair. */
+export function getReputationSummary(
+  actorType: ReputationActorType,
+  averageRating: number | null | undefined,
+  totalRatings: number | null | undefined
+): ReputationSummary {
+  const count = totalRatings ?? 0;
+  const hasEnoughSignal = count >= MIN_RATINGS_FOR_DISPLAY;
+  return {
+    actorType,
+    averageRating: hasEnoughSignal ? (averageRating ?? null) : null,
+    totalRatings: count,
+    bayesianScore: bayesianAverage(averageRating, totalRatings),
+    hasEnoughSignal,
+  };
+}
+
+export interface ServiceListingReputation {
+  averageRating: number;
+  totalRatings: number;
+  sourceLabel?: string;
+}
+
+/** Compact browse/detail reputation from aggregate service rating fields. */
+export function getServiceListingReputation(service: {
+  serviceRating?: number | null;
+  totalRatings?: number | null;
+  externalReviewSource?: string | null;
+}): ServiceListingReputation | null {
+  const summary = getReputationSummary(
+    "service",
+    service.serviceRating,
+    service.totalRatings
+  );
+  if (!summary.hasEnoughSignal || summary.averageRating == null) {
+    return null;
+  }
+  const sourceLabel =
+    service.externalReviewSource === "google" ? "Google" : undefined;
+  return {
+    averageRating: summary.averageRating,
+    totalRatings: summary.totalRatings,
+    sourceLabel,
+  };
+}

package/src/utils/service/serviceUtils.ts

@@ -411,8 +411,12 @@ export interface ServiceSpecificTypeInfo {
   specificId: string;
 }
 
-export function serviceGetSpecificType<BookingType extends Service>(
-  service: BookingType
+export type ServiceSpecificTypeLookup = Pick<Service, "id"> & {
+  serviceType: ServiceTypes | null;
+} & Partial<Record<`${ServiceSpecificName}Id`, string | null>>;
+
+export function serviceGetSpecificType(
+  service: ServiceSpecificTypeLookup
 ): ServiceSpecificTypeInfo | null {
   if (service.serviceType == null) {
     // throw new Error(`serviceGetSpecificType invalid serviceType`);

package/src/utils/serviceAvailabilityDisplay.ts

@@ -0,0 +1,199 @@
+/**
+ * Shared helpers for displaying and quick-configuring service availability.
+ *
+ * A service stores weekly availability in `Service.availableHours` as a JSON
+ * string shaped like:
+ *   { hours: { Monday: [{ open, close }] }, openDays: { Monday: true } }
+ *
+ * These helpers derive a simple "weekdays / weekends / custom" preset from that
+ * shape, apply a preset, and compute the earliest open date for a public profile.
+ * They intentionally avoid timezone math and live-booking awareness: the earliest
+ * date reflects the owner's published schedule and owner-blocked dates only.
+ */
+
+export type AvailabilityPreset = "weekdays" | "weekends" | "custom";
+
+export interface AvailabilityTimeSlot {
+  open: string;
+  close: string;
+}
+
+export interface AvailabilityHoursConfig {
+  hours?: Record<string, AvailabilityTimeSlot[]>;
+  openDays?: Record<string, boolean>;
+  enableInstantBooking?: boolean;
+}
+
+/** Inclusive date range a service owner has blocked off (unavailable). */
+export interface AvailabilityBlockedRange {
+  start: Date | string;
+  end: Date | string;
+}
+
+const WEEKDAY_NAMES = [
+  "Monday",
+  "Tuesday",
+  "Wednesday",
+  "Thursday",
+  "Friday",
+] as const;
+const WEEKEND_NAMES = ["Saturday", "Sunday"] as const;
+const ALL_DAY_NAMES = [...WEEKDAY_NAMES, ...WEEKEND_NAMES] as const;
+
+/** JS `Date.getDay()` index (0 = Sunday) to day name used in `openDays`. */
+const DAY_INDEX_TO_NAME = [
+  "Sunday",
+  "Monday",
+  "Tuesday",
+  "Wednesday",
+  "Thursday",
+  "Friday",
+  "Saturday",
+] as const;
+
+/** All-day open slot, matching the wizard's default day hours. */
+const DEFAULT_OPEN_SLOT: AvailabilityTimeSlot = {
+  open: "12:00 AM",
+  close: "11:59 PM",
+};
+const CLOSED_SLOT: AvailabilityTimeSlot = { open: "", close: "" };
+
+/** Parse `Service.availableHours` (string or object) into a config, or null. */
+export function parseAvailableHours(
+  availableHours: unknown
+): AvailabilityHoursConfig | null {
+  if (!availableHours) return null;
+  try {
+    const parsed =
+      typeof availableHours === "string"
+        ? JSON.parse(availableHours)
+        : availableHours;
+    if (parsed && typeof parsed === "object") {
+      return parsed as AvailabilityHoursConfig;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+/**
+ * Classify an `openDays` map as a known preset. Returns null when there is no
+ * day information to classify.
+ */
+export function detectAvailabilityPreset(
+  openDays: Record<string, boolean> | null | undefined
+): AvailabilityPreset | null {
+  if (!openDays) return null;
+  const hasAnyKnownDay = ALL_DAY_NAMES.some(
+    (day) => openDays[day] !== undefined
+  );
+  if (!hasAnyKnownDay) return null;
+
+  const weekdaysAllOpen = WEEKDAY_NAMES.every((day) => openDays[day] === true);
+  const weekdaysAllClosed = WEEKDAY_NAMES.every(
+    (day) => openDays[day] === false
+  );
+  const weekendsAllOpen = WEEKEND_NAMES.every((day) => openDays[day] === true);
+  const weekendsAllClosed = WEEKEND_NAMES.every(
+    (day) => openDays[day] === false
+  );
+
+  if (weekdaysAllOpen && weekendsAllClosed) return "weekdays";
+  if (weekendsAllOpen && weekdaysAllClosed) return "weekends";
+  return "custom";
+}
+
+/**
+ * Produce an `availableHours` config for a quick preset. Open days get an
+ * all-day slot; closed days get an empty slot. Any extra fields on `base`
+ * (e.g. `enableInstantBooking`) are preserved.
+ */
+export function applyAvailabilityPreset(
+  preset: Exclude<AvailabilityPreset, "custom">,
+  base?: AvailabilityHoursConfig | null
+): AvailabilityHoursConfig {
+  const openDayNames =
+    preset === "weekdays" ? WEEKDAY_NAMES : WEEKEND_NAMES;
+  const hours: Record<string, AvailabilityTimeSlot[]> = {};
+  const openDays: Record<string, boolean> = {};
+
+  for (const day of ALL_DAY_NAMES) {
+    const isOpen = (openDayNames as readonly string[]).includes(day);
+    openDays[day] = isOpen;
+    hours[day] = isOpen ? [{ ...DEFAULT_OPEN_SLOT }] : [{ ...CLOSED_SLOT }];
+  }
+
+  return { ...(base ?? {}), hours, openDays };
+}
+
+/** User-facing label for a preset (e.g. shown on the public profile). */
+export function formatAvailabilityPresetLabel(
+  preset: AvailabilityPreset
+): string {
+  switch (preset) {
+    case "weekdays":
+      return "Available on weekdays";
+    case "weekends":
+      return "Available on weekends";
+    default:
+      return "Custom availability";
+  }
+}
+
+function startOfLocalDay(date: Date): Date {
+  return new Date(date.getFullYear(), date.getMonth(), date.getDate());
+}
+
+/** Whether a given date's weekday is open per the `openDays` map. */
+export function isAvailabilityDayOpen(
+  openDays: Record<string, boolean> | null | undefined,
+  date: Date
+): boolean {
+  if (!openDays) return true;
+  const name = DAY_INDEX_TO_NAME[date.getDay()];
+  // Treat unset days as open; only an explicit false closes a day.
+  return openDays[name] !== false;
+}
+
+/** Whether a date falls within any owner-blocked (unavailable) range. */
+export function isDateBlocked(
+  blockedRanges: AvailabilityBlockedRange[],
+  date: Date
+): boolean {
+  const day = startOfLocalDay(date).getTime();
+  return blockedRanges.some((range) => {
+    const start = startOfLocalDay(new Date(range.start)).getTime();
+    const end = startOfLocalDay(new Date(range.end)).getTime();
+    if (Number.isNaN(start) || Number.isNaN(end)) return false;
+    return day >= start && day <= end;
+  });
+}
+
+/**
+ * Earliest date the service is open per its weekly schedule and not within an
+ * owner-blocked range. Does NOT account for existing bookings, so callers should
+ * frame it as an estimate. Returns null when no day is open within the lookahead.
+ */
+export function computeEarliestOpenDate(params: {
+  openDays?: Record<string, boolean> | null;
+  blockedRanges?: AvailabilityBlockedRange[] | null;
+  fromDate?: Date;
+  maxLookaheadDays?: number;
+}): Date | null {
+  const { openDays, blockedRanges, fromDate, maxLookaheadDays = 365 } = params;
+  const ranges = blockedRanges ?? [];
+  const cursor = startOfLocalDay(fromDate ?? new Date());
+
+  for (let i = 0; i <= maxLookaheadDays; i++) {
+    const candidate = new Date(cursor);
+    candidate.setDate(candidate.getDate() + i);
+    if (
+      isAvailabilityDayOpen(openDays, candidate) &&
+      !isDateBlocked(ranges, candidate)
+    ) {
+      return candidate;
+    }
+  }
+  return null;
+}

package/src/utils/ticketCheckInDisplay.ts

@@ -0,0 +1,37 @@
+/** GPS / geofence auto check-in (legacy values: auto, geofence, GPS_RADIUS). */
+export function isGpsCheckInMethod(
+  method: string | null | undefined
+): boolean {
+  if (!method) return false;
+  const m = method.toLowerCase();
+  return m === "auto" || m === "geofence" || m === "gps_radius";
+}
+
+function isTicketCheckedIn(
+  checkedInAt: Date | string | null | undefined,
+  ticketStatus: string | null | undefined
+): boolean {
+  return checkedInAt != null || ticketStatus === "CheckedIn";
+}
+
+/**
+ * Attendee-facing label for ticket check-in on My Tickets and similar surfaces.
+ * Returns null when the ticket has not been checked in.
+ */
+export function getTicketCheckInDisplayLabel(
+  checkedInAt: Date | string | null | undefined,
+  checkedInMethod: string | null | undefined,
+  ticketStatus?: string | null
+): string | null {
+  if (!isTicketCheckedIn(checkedInAt, ticketStatus ?? null)) return null;
+  if (isGpsCheckInMethod(checkedInMethod)) {
+    return "GPS check-in";
+  }
+  if (checkedInMethod === "manual") {
+    return "Scanned at door";
+  }
+  if (checkedInMethod === "door_card" || checkedInMethod === "door_cash") {
+    return "Checked in at door";
+  }
+  return "Checked in";
+}

package/src/utils/userUtils.ts

@@ -1,4 +1,4 @@
-import { Gender } from "@prisma/client";
+import { Gender, SocialEventCadence } from "@prisma/client";
 
 export const MAX_USER_NAME_CHANGES = 3 as const;
 
@@ -39,3 +39,38 @@ export function getDisplayGender(user: GenderDisplayUser): string | null {
   if (user.gender) return user.gender;
   return null;
 }
+
+/**
+ * Plain labels for the social event cadence enum — used in Settings, the account
+ * edit forms, and the host CRM filter where clarity beats personality.
+ */
+export const SOCIAL_EVENT_CADENCE_LABELS: Record<SocialEventCadence, string> = {
+  Always: "Always",
+  Often: "Often",
+  Sometimes: "Sometimes",
+  Rarely: "Rarely",
+  Never: "Never",
+};
+
+/**
+ * Promoter-voice labels for the public profile — friendlier phrasing of how often
+ * someone likes to go out. Falls back to the plain label when no flourish exists.
+ */
+export const SOCIAL_EVENT_CADENCE_PROFILE_LABELS: Record<SocialEventCadence, string> = {
+  Always: "Always down for a bash",
+  Often: "Out most weekends",
+  Sometimes: "Out now and then",
+  Rarely: "Rarely out",
+  Never: "Prefers to stay in",
+};
+
+/**
+ * Resolve the public-facing cadence label for a user. Returns `null` when the
+ * value is unset so callers can omit the line entirely.
+ */
+export function getSocialEventCadenceDisplay(
+  cadence: SocialEventCadence | null | undefined
+): string | null {
+  if (!cadence) return null;
+  return SOCIAL_EVENT_CADENCE_PROFILE_LABELS[cadence] ?? cadence;
+}