@bash-app/bash-common 30.225.0 → 30.227.0

package/src/__tests__/agePolicy.test.ts

@@ -0,0 +1,257 @@
+/**
+ * AgePolicy helpers — unit tests.
+ *
+ * `getAgeFromDob` and `meetsAgePolicy` are the source of truth for both:
+ *   - the `GET /me/id-status` endpoint (which returns `verifiedAge`)
+ *   - the checkout `IdRequirementGate` (which gates buy-button on min age)
+ *
+ * They must handle: missing input, invalid strings, the day-before-birthday
+ * edge case, and leap-day birthdays without throwing or off-by-one errors.
+ */
+import {
+  AgePolicy,
+  AgePolicyLabel,
+  AgePolicyMinimumAge,
+  agePolicyToFilterLabel,
+  eventMatchesAgeFilter,
+  getAgeFromDob,
+  legacyAgeRangeMatchesFilter,
+  meetsAgePolicy,
+} from "../definitions";
+
+describe("AgePolicyLabel", () => {
+  it("maps every enum value to a non-empty display label", () => {
+    for (const policy of Object.values(AgePolicy)) {
+      expect(typeof AgePolicyLabel[policy]).toBe("string");
+      expect(AgePolicyLabel[policy].length).toBeGreaterThan(0);
+    }
+  });
+
+  it("uses the marketing-friendly +/All Ages copy", () => {
+    expect(AgePolicyLabel[AgePolicy.AllAges]).toBe("All Ages");
+    expect(AgePolicyLabel[AgePolicy.EighteenPlus]).toBe("18+");
+    expect(AgePolicyLabel[AgePolicy.TwentyOnePlus]).toBe("21+");
+  });
+});
+
+describe("AgePolicyMinimumAge", () => {
+  it("returns null for unrestricted events", () => {
+    expect(AgePolicyMinimumAge[AgePolicy.AllAges]).toBeNull();
+  });
+
+  it("returns the explicit numeric minimum for restricted events", () => {
+    expect(AgePolicyMinimumAge[AgePolicy.EighteenPlus]).toBe(18);
+    expect(AgePolicyMinimumAge[AgePolicy.TwentyOnePlus]).toBe(21);
+  });
+});
+
+describe("getAgeFromDob", () => {
+  /** Build an ISO date string offset by a number of years, months, and days from now. */
+  const isoFromOffset = (years: number, months = 0, days = 0): string => {
+    const d = new Date();
+    d.setFullYear(d.getFullYear() - years);
+    d.setMonth(d.getMonth() - months);
+    d.setDate(d.getDate() - days);
+    return d.toISOString();
+  };
+
+  it("returns null for null / undefined / empty input", () => {
+    expect(getAgeFromDob(null)).toBeNull();
+    expect(getAgeFromDob(undefined)).toBeNull();
+    expect(getAgeFromDob("")).toBeNull();
+  });
+
+  it("returns null when the date string cannot be parsed", () => {
+    expect(getAgeFromDob("not-a-date")).toBeNull();
+    expect(getAgeFromDob("2025-13-99")).toBeNull();
+  });
+
+  it("computes whole-year age for a clearly-past birthday", () => {
+    // Born 25 years ago, 1 month ago — birthday already passed this year.
+    expect(getAgeFromDob(isoFromOffset(25, 1))).toBe(25);
+  });
+
+  it("subtracts a year when birthday hasn't occurred yet this year", () => {
+    // Born 25 years ago + 1 month from now (birthday is next month).
+    const d = new Date();
+    d.setFullYear(d.getFullYear() - 25);
+    d.setMonth(d.getMonth() + 1);
+    expect(getAgeFromDob(d.toISOString())).toBe(24);
+  });
+
+  it("treats today as 'birthday already happened' (not subtracting a year)", () => {
+    // Born exactly 30 years ago today.
+    const d = new Date();
+    d.setFullYear(d.getFullYear() - 30);
+    expect(getAgeFromDob(d.toISOString())).toBe(30);
+  });
+
+  it("treats tomorrow's birthday as still being last year's age", () => {
+    // Born 30 years ago - 1 day (so birthday is tomorrow).
+    const d = new Date();
+    d.setFullYear(d.getFullYear() - 30);
+    d.setDate(d.getDate() + 1);
+    expect(getAgeFromDob(d.toISOString())).toBe(29);
+  });
+
+  it("accepts a Date instance, not just a string", () => {
+    const d = new Date();
+    d.setFullYear(d.getFullYear() - 40);
+    d.setMonth(d.getMonth() - 2);
+    expect(getAgeFromDob(d)).toBe(40);
+  });
+
+  it("returns 0 for a baby born earlier this year", () => {
+    // Born ~3 months ago — under 1 year old.
+    expect(getAgeFromDob(isoFromOffset(0, 3))).toBe(0);
+  });
+});
+
+describe("meetsAgePolicy", () => {
+  const yearsAgo = (n: number): string => {
+    const d = new Date();
+    d.setFullYear(d.getFullYear() - n);
+    // back off a day to guarantee the birthday has occurred this year
+    d.setDate(d.getDate() - 1);
+    return d.toISOString();
+  };
+
+  it("All Ages always passes — even with no DOB", () => {
+    expect(meetsAgePolicy(AgePolicy.AllAges, null)).toBe(true);
+    expect(meetsAgePolicy(AgePolicy.AllAges, undefined)).toBe(true);
+    expect(meetsAgePolicy(AgePolicy.AllAges, yearsAgo(5))).toBe(true);
+  });
+
+  it("denies restricted policies when DOB is missing", () => {
+    expect(meetsAgePolicy(AgePolicy.EighteenPlus, null)).toBe(false);
+    expect(meetsAgePolicy(AgePolicy.TwentyOnePlus, undefined)).toBe(false);
+  });
+
+  it("18+ allows ages >= 18 and denies < 18", () => {
+    expect(meetsAgePolicy(AgePolicy.EighteenPlus, yearsAgo(17))).toBe(false);
+    expect(meetsAgePolicy(AgePolicy.EighteenPlus, yearsAgo(18))).toBe(true);
+    expect(meetsAgePolicy(AgePolicy.EighteenPlus, yearsAgo(40))).toBe(true);
+  });
+
+  it("21+ allows ages >= 21 and denies under-21 (including 18-, 20-year-olds)", () => {
+    expect(meetsAgePolicy(AgePolicy.TwentyOnePlus, yearsAgo(20))).toBe(false);
+    expect(meetsAgePolicy(AgePolicy.TwentyOnePlus, yearsAgo(21))).toBe(true);
+    expect(meetsAgePolicy(AgePolicy.TwentyOnePlus, yearsAgo(50))).toBe(true);
+  });
+
+  it("denies on invalid DOB strings (defensive fail-closed)", () => {
+    expect(meetsAgePolicy(AgePolicy.EighteenPlus, "not-a-date")).toBe(false);
+    expect(meetsAgePolicy(AgePolicy.TwentyOnePlus, "")).toBe(false);
+  });
+});
+
+describe("agePolicyToFilterLabel", () => {
+  it("maps each enum to its discover-filter chip label", () => {
+    expect(agePolicyToFilterLabel(AgePolicy.AllAges)).toBe("All Ages");
+    expect(agePolicyToFilterLabel(AgePolicy.EighteenPlus)).toBe("18+");
+    expect(agePolicyToFilterLabel(AgePolicy.TwentyOnePlus)).toBe("21+");
+  });
+
+  it("treats null / undefined (legacy events) as All Ages so they don't disappear from filters", () => {
+    expect(agePolicyToFilterLabel(null)).toBe("All Ages");
+    expect(agePolicyToFilterLabel(undefined)).toBe("All Ages");
+  });
+});
+
+describe("eventMatchesAgeFilter", () => {
+  it("matches everything when no labels are selected (no-op filter)", () => {
+    expect(eventMatchesAgeFilter(AgePolicy.AllAges, [])).toBe(true);
+    expect(eventMatchesAgeFilter(AgePolicy.TwentyOnePlus, [])).toBe(true);
+    expect(eventMatchesAgeFilter(null, [])).toBe(true);
+  });
+
+  it("matches when the event's policy is in the selected labels", () => {
+    expect(eventMatchesAgeFilter(AgePolicy.EighteenPlus, ["18+"])).toBe(true);
+    expect(
+      eventMatchesAgeFilter(AgePolicy.TwentyOnePlus, ["21+", "All Ages"])
+    ).toBe(true);
+  });
+
+  it("does not match when the event's policy is excluded by the selection", () => {
+    expect(eventMatchesAgeFilter(AgePolicy.EighteenPlus, ["21+"])).toBe(false);
+    expect(eventMatchesAgeFilter(AgePolicy.AllAges, ["18+", "21+"])).toBe(false);
+  });
+
+  it("treats legacy 'Everyone' label as All Ages (back-compat with old saved filters)", () => {
+    expect(eventMatchesAgeFilter(AgePolicy.AllAges, ["Everyone"])).toBe(true);
+    expect(eventMatchesAgeFilter(AgePolicy.EighteenPlus, ["Everyone"])).toBe(false);
+  });
+
+  it("treats legacy events without an agePolicy as All Ages", () => {
+    expect(eventMatchesAgeFilter(null, ["All Ages"])).toBe(true);
+    expect(eventMatchesAgeFilter(null, ["18+"])).toBe(false);
+  });
+});
+
+describe("legacyAgeRangeMatchesFilter", () => {
+  // The legacy `targetAudience.ageRange` field was schema-free, so we have to
+  // tolerate strings, arrays, objects, null, and even checkbox-style payloads.
+
+  it("matches everything when no filter labels are selected (no-op filter)", () => {
+    expect(legacyAgeRangeMatchesFilter(null, [])).toBe(true);
+    expect(legacyAgeRangeMatchesFilter(["18+"], [])).toBe(true);
+    expect(legacyAgeRangeMatchesFilter("anything", [])).toBe(true);
+  });
+
+  it("matches '18+' filter when the legacy blob contains '18+'", () => {
+    expect(legacyAgeRangeMatchesFilter(["18+"], ["18+"])).toBe(true);
+    expect(legacyAgeRangeMatchesFilter("18+", ["18+"])).toBe(true);
+    expect(
+      legacyAgeRangeMatchesFilter({ adults: "18+" }, ["18+"])
+    ).toBe(true);
+  });
+
+  it("matches '21+' filter only when the legacy blob contains '21+'", () => {
+    expect(legacyAgeRangeMatchesFilter(["21+"], ["21+"])).toBe(true);
+    expect(legacyAgeRangeMatchesFilter("18+", ["21+"])).toBe(false);
+  });
+
+  it("matches All Ages when blob is empty / missing (catches untagged legacy events)", () => {
+    expect(legacyAgeRangeMatchesFilter(null, ["All Ages"])).toBe(true);
+    expect(legacyAgeRangeMatchesFilter(undefined, ["All Ages"])).toBe(true);
+    expect(legacyAgeRangeMatchesFilter("", ["All Ages"])).toBe(true);
+    expect(legacyAgeRangeMatchesFilter([], ["All Ages"])).toBe(true);
+  });
+
+  it("matches All Ages when blob explicitly mentions 'All Ages' or 'Family Friendly'", () => {
+    expect(
+      legacyAgeRangeMatchesFilter(["All Ages"], ["All Ages"])
+    ).toBe(true);
+    expect(
+      legacyAgeRangeMatchesFilter(["Family Friendly"], ["All Ages"])
+    ).toBe(true);
+  });
+
+  it("does NOT match All Ages when blob carries a 21+ or 18+ marker", () => {
+    expect(legacyAgeRangeMatchesFilter(["18+"], ["All Ages"])).toBe(false);
+    expect(legacyAgeRangeMatchesFilter(["21+"], ["All Ages"])).toBe(false);
+  });
+
+  it("treats legacy 'Everyone' filter label as a synonym for All Ages", () => {
+    expect(legacyAgeRangeMatchesFilter(null, ["Everyone"])).toBe(true);
+    expect(legacyAgeRangeMatchesFilter(["18+"], ["Everyone"])).toBe(false);
+  });
+
+  it("returns true when ANY selected label matches (multi-select union semantics)", () => {
+    // Legacy blob says 21+; user selected both 18+ and 21+ — still a match.
+    expect(
+      legacyAgeRangeMatchesFilter(["21+"], ["18+", "21+"])
+    ).toBe(true);
+    // Legacy blob says 21+; user selected only 18+ — no match.
+    expect(legacyAgeRangeMatchesFilter(["21+"], ["18+"])).toBe(false);
+  });
+
+  it("does not throw on values that JSON.stringify can't handle (defensive)", () => {
+    const cyclic: Record<string, unknown> = {};
+    cyclic.self = cyclic;
+    // Cyclic objects throw inside JSON.stringify; the helper does NOT swallow
+    // that error today, so we document the contract: callers must pass
+    // serializable values. (The MyBashesPage code path always does.)
+    expect(() => legacyAgeRangeMatchesFilter(cyclic, ["18+"])).toThrow();
+  });
+});

package/src/__tests__/getDisplayGender.test.ts

@@ -0,0 +1,50 @@
+/**
+ * `getDisplayGender` precedence tests.
+ *
+ * Pins the contract that:
+ *   - `genderIdentity` (free-text) **always wins** over the `gender` enum
+ *   - whitespace-only `genderIdentity` is treated as absent
+ *   - falsy `gender` (`null`, `undefined`) yields `null`, not the string "null"
+ *   - the helper never throws on partial input
+ */
+import { Gender } from "@prisma/client";
+import { getDisplayGender } from "../utils/userUtils.js";
+
+describe("getDisplayGender", () => {
+  it("returns genderIdentity when present, even if gender is also set", () => {
+    expect(
+      getDisplayGender({
+        gender: Gender.Female,
+        genderIdentity: "Non-binary",
+      }),
+    ).toBe("Non-binary");
+  });
+
+  it("returns the gender enum value when genderIdentity is empty/null", () => {
+    expect(
+      getDisplayGender({ gender: Gender.Male, genderIdentity: null }),
+    ).toBe("Male");
+    expect(
+      getDisplayGender({ gender: Gender.Male, genderIdentity: "" }),
+    ).toBe("Male");
+  });
+
+  it("trims whitespace-only genderIdentity and falls back to gender", () => {
+    expect(
+      getDisplayGender({ gender: Gender.NoPreference, genderIdentity: "   " }),
+    ).toBe("NoPreference");
+  });
+
+  it("returns null when both fields are missing", () => {
+    expect(getDisplayGender({})).toBeNull();
+    expect(
+      getDisplayGender({ gender: null, genderIdentity: null }),
+    ).toBeNull();
+  });
+
+  it("returns the trimmed identity (no surrounding whitespace) when used alone", () => {
+    expect(
+      getDisplayGender({ genderIdentity: "  Genderfluid  " }),
+    ).toBe("Genderfluid");
+  });
+});

package/src/__tests__/statusEnums.test.ts

@@ -0,0 +1,36 @@
+/**
+ * Pin the value sets of the three status enums introduced as part of the
+ * "stringly-typed status" cleanup. These enums are the contract between
+ *   - api endpoints (uploadIdApi, serviceApi, adminDashboardSummaryApi)
+ *   - bash-app UI components (IdRequirementGate, IdVerificationSection,
+ *     CustomScopeRequestsAdminPage, ServicesRatesAndPricing)
+ *   - the database (Postgres ENUM columns)
+ *
+ * Adding/removing/renaming a member without intentionally updating the
+ * migration + all callers should fail this test loudly.
+ */
+import {
+  CustomScopeStatus,
+  GovIdRetentionPolicy,
+  SchoolNameSource,
+} from "@prisma/client";
+
+describe("status enum value sets", () => {
+  test("GovIdRetentionPolicy", () => {
+    expect(Object.values(GovIdRetentionPolicy).sort()).toEqual(
+      ["Indefinite", "ThirtyDays", "UntilIdExpires"].sort(),
+    );
+  });
+
+  test("SchoolNameSource", () => {
+    expect(Object.values(SchoolNameSource).sort()).toEqual(
+      ["AiInferred", "UserConfirmed"].sort(),
+    );
+  });
+
+  test("CustomScopeStatus", () => {
+    expect(Object.values(CustomScopeStatus).sort()).toEqual(
+      ["Approved", "None", "Pending", "Rejected"].sort(),
+    );
+  });
+});

package/src/aiApproval.ts

@@ -0,0 +1,118 @@
+/**
+ * Shared shapes for the AI bash-approval reviewer.
+ *
+ * The Zod runtime envelope lives in `api/src/utils/ai/aiApprovalEnvelope.ts` (zod is an api
+ * dependency, not a bash-common one). This file is the type-only source of truth that both
+ * the api worker and bash-app's admin UI/host-facing banners read.
+ *
+ * The persisted `BashEvent.aiApprovalReasons` JSON column is exactly an `AiApprovalReasons`.
+ */
+
+import type { AiApprovalVerdict } from "@prisma/client";
+
+/**
+ * Each criterion the model grades on.
+ *
+ * Keep this list short and stable — it controls the persisted JSON shape, the prompt
+ * the model sees, and the badges the admin UI renders. Adding a new criterion is a
+ * schema change (existing rows will be missing it).
+ */
+export const AI_APPROVAL_CRITERION_KEYS = [
+  "completeness",
+  "authenticity",
+  "safety",
+  "policyFit",
+] as const;
+
+export type AiApprovalCriterionKey = (typeof AI_APPROVAL_CRITERION_KEYS)[number];
+
+/**
+ * Display labels for criteria — used in the admin queue and any host-facing breakdown.
+ * Keep keys exhaustive against `AiApprovalCriterionKey` (compiler will yell if drift).
+ */
+export const AiApprovalCriterionLabel: Record<AiApprovalCriterionKey, string> = {
+  completeness: "Completeness",
+  authenticity: "Authenticity",
+  safety: "Safety",
+  policyFit: "Policy fit",
+};
+
+/**
+ * One criterion's grade. `score` is 0..1; `notes` is short free-text the model wrote
+ * about why (shown in the admin UI tooltip / host rejection reasons).
+ */
+export interface AiApprovalCriterionResult {
+  score: number;
+  notes: string;
+}
+
+/**
+ * Persisted shape for `BashEvent.aiApprovalReasons` (Json column).
+ *
+ * - `criteria` keys are exhaustive over `AiApprovalCriterionKey`.
+ * - `hostFacingMessage` is shown to the host on rejection; written specifically to be
+ *   actionable ("Add a start time and a location, then resubmit"), not generic.
+ *   Null on approve.
+ * - `adminFacingNotes` is for super-users in the review queue; can be more candid
+ *   ("Looks like a duplicate of bash xyz" / "Probably a service ad in disguise").
+ */
+export interface AiApprovalReasons {
+  criteria: Record<AiApprovalCriterionKey, AiApprovalCriterionResult>;
+  hostFacingMessage: string | null;
+  adminFacingNotes: string;
+}
+
+/**
+ * Runtime values for the Prisma `AiApprovalVerdict` enum.
+ *
+ * Browser code (bash-app) cannot rely on `@prisma/client`'s runtime enum exports — the
+ * package's `browser` resolution doesn't reliably surface them when imported transitively
+ * via `@bash-app/bash-common`. So we mirror the enum here as a plain string-keyed object
+ * and `satisfies Record<AiApprovalVerdict, AiApprovalVerdict>` to guarantee at compile
+ * time that the keys/values stay in lockstep with `schema.prisma`. Prefer
+ * `AI_APPROVAL_VERDICTS.Approve` over `AiApprovalVerdict.Approve` in any code path that
+ * may be bundled for the browser.
+ */
+export const AI_APPROVAL_VERDICTS = {
+  Approve: "Approve",
+  Flag: "Flag",
+  Reject: "Reject",
+} as const satisfies Record<AiApprovalVerdict, AiApprovalVerdict>;
+
+/**
+ * Display labels for the Prisma `AiApprovalVerdict` enum, used in admin pills and the
+ * host rejection banner so callers don't reach for ad-hoc switch statements.
+ *
+ * The `Record<AiApprovalVerdict, string>` annotation enforces exhaustiveness at compile
+ * time, so adding/renaming an enum member in `schema.prisma` will fail tsc here.
+ */
+export const AiApprovalVerdictLabel: Record<AiApprovalVerdict, string> = {
+  Approve: "Approve",
+  Flag: "Flag for review",
+  Reject: "Reject",
+};
+
+/**
+ * Feature-flag values for `AI_BASH_APPROVAL_MODE`.
+ *
+ * - `off`             - AI service is never invoked. Existing manual-only workflow.
+ * - `shadow`          - AI runs and persists verdict + reasons, but every outcome is `flag`.
+ *                       Admins still decide everything; we use the data to tune thresholds.
+ * - `auto-with-flag`  - High-confidence approve/reject act automatically; the rest flag for human.
+ * - `auto-approve-only` - High-confidence approve acts automatically; rejects always flag for human.
+ */
+export const AI_BASH_APPROVAL_MODES = [
+  "off",
+  "shadow",
+  "auto-with-flag",
+  "auto-approve-only",
+] as const;
+
+export type AiBashApprovalMode = (typeof AI_BASH_APPROVAL_MODES)[number];
+
+/**
+ * Default thresholds. Tune in the api consumer if behavior needs to change post-rollout;
+ * exporting here so tests in api can import a single source of truth.
+ */
+export const AI_APPROVAL_AUTO_APPROVE_CONFIDENCE = 0.85;
+export const AI_APPROVAL_AUTO_REJECT_CONFIDENCE = 0.9;

package/src/definitions.ts

@@ -1,14 +1,18 @@
 import {
+    AgePolicy,
     BashEventType,
     BashPassTier,
     BracketType,
     CompetitionType,
     Contact,
+    CustomScopeStatus,
     EntertainmentServiceType,
+    GovIdRetentionPolicy,
     JudgingType,
     MembershipTier,
     MusicGenreType,
     Prisma,
+    SchoolNameSource,
     ServiceTypes,
     Ticket,
     TicketTier,
@@ -922,7 +926,140 @@ export const YearsOfExperienceToString: { [key in YearsOfExperience]: string } =
   };
 
 // Export Prisma enums for use in frontend
-export { YearsOfExperience, EntertainmentServiceType, MusicGenreType, ServiceTypes, CompetitionType, JudgingType, BracketType };
+export {
+    AgePolicy,
+    BracketType,
+    CompetitionType,
+    CustomScopeStatus,
+    EntertainmentServiceType,
+    GovIdRetentionPolicy,
+    JudgingType,
+    MusicGenreType,
+    SchoolNameSource,
+    ServiceTypes,
+    YearsOfExperience,
+};
+
+/**
+ * Display labels for `User.govIdRetentionPolicy` (settings UI, ID verification gate).
+ *
+ * The enum is the source of truth - read sites should never branch on a string literal
+ * like `"30days"`; use `GovIdRetentionPolicy.ThirtyDays` instead so a typo can't quietly
+ * mismatch on either the API or DB side.
+ */
+export const GovIdRetentionPolicyLabel: Record<GovIdRetentionPolicy, string> = {
+    [GovIdRetentionPolicy.ThirtyDays]: "Delete after 30 days",
+    [GovIdRetentionPolicy.UntilIdExpires]: "Keep until ID expires",
+    [GovIdRetentionPolicy.Indefinite]: "Keep on file (indefinite)",
+};
+
+/**
+ * Display labels for `Service.customScopeStatus` (admin dashboard, provider pricing UI).
+ */
+export const CustomScopeStatusLabel: Record<CustomScopeStatus, string> = {
+    [CustomScopeStatus.None]: "None",
+    [CustomScopeStatus.Pending]: "Pending Review",
+    [CustomScopeStatus.Approved]: "Approved",
+    [CustomScopeStatus.Rejected]: "Rejected",
+};
+
+/** Display label for an event's age policy (BashCard pill, filter UI, wizard). */
+export const AgePolicyLabel: Record<AgePolicy, string> = {
+  [AgePolicy.AllAges]: "All Ages",
+  [AgePolicy.EighteenPlus]: "18+",
+  [AgePolicy.TwentyOnePlus]: "21+",
+};
+
+/** Minimum age (in years) implied by an event's age policy. `null` for All Ages. */
+export const AgePolicyMinimumAge: Record<AgePolicy, number | null> = {
+  [AgePolicy.AllAges]: null,
+  [AgePolicy.EighteenPlus]: 18,
+  [AgePolicy.TwentyOnePlus]: 21,
+};
+
+/** Returns the user's age in whole years, or null if the DOB is missing/invalid. */
+export function getAgeFromDob(dob: Date | string | null | undefined): number | null {
+  if (!dob) return null;
+  const birth = dob instanceof Date ? dob : new Date(dob);
+  if (Number.isNaN(birth.getTime())) return null;
+  const now = new Date();
+  let age = now.getFullYear() - birth.getFullYear();
+  const monthDelta = now.getMonth() - birth.getMonth();
+  if (monthDelta < 0 || (monthDelta === 0 && now.getDate() < birth.getDate())) {
+    age -= 1;
+  }
+  return age;
+}
+
+/** Whether the given DOB satisfies the policy's minimum age. AllAges is always true. */
+export function meetsAgePolicy(
+  policy: AgePolicy,
+  dob: Date | string | null | undefined
+): boolean {
+  const min = AgePolicyMinimumAge[policy];
+  if (min === null) return true;
+  const age = getAgeFromDob(dob);
+  if (age === null) return false;
+  return age >= min;
+}
+
+/** Discover-filter labels (kept human-friendly for chips and modal options). */
+export type AgePolicyFilterLabel = "All Ages" | "18+" | "21+";
+
+/** Map an enum value to the discover-filter label. */
+export function agePolicyToFilterLabel(
+  policy: AgePolicy | null | undefined
+): AgePolicyFilterLabel {
+  if (policy === AgePolicy.EighteenPlus) return "18+";
+  if (policy === AgePolicy.TwentyOnePlus) return "21+";
+  // Untagged legacy events behave as All Ages so old data doesn't disappear from filters.
+  return "All Ages";
+}
+
+/**
+ * Whether an event's `agePolicy` matches a set of selected filter labels.
+ * Tolerates legacy "Everyone" copy by treating it as a synonym for "All Ages".
+ */
+export function eventMatchesAgeFilter(
+  eventAgePolicy: AgePolicy | null | undefined,
+  selectedLabels: ReadonlyArray<string>
+): boolean {
+  if (selectedLabels.length === 0) return true;
+  const eventLabel = agePolicyToFilterLabel(eventAgePolicy);
+  return selectedLabels.some(
+    (raw) => (raw === "Everyone" ? "All Ages" : raw) === eventLabel
+  );
+}
+
+/**
+ * Legacy fallback for events without `agePolicy`: scans the unstructured
+ * `targetAudience.ageRange` blob (which historically held arrays of strings,
+ * checkbox payloads, and free-text) for the canonical filter labels so that
+ * old data still appears in the All Ages / 18+ / 21+ filters.
+ *
+ * Matching rules (in priority order):
+ *   - "21+" filter matches when the blob contains "21+".
+ *   - "18+" filter matches when the blob contains "18+".
+ *   - "All Ages" / "Everyone" matches when the blob contains "All Ages" or
+ *     "Family Friendly", OR when neither "18+" nor "21+" appears.
+ */
+export function legacyAgeRangeMatchesFilter(
+  ageRange: unknown,
+  selectedLabels: ReadonlyArray<string>
+): boolean {
+  if (selectedLabels.length === 0) return true;
+  const blob = JSON.stringify(ageRange ?? "");
+  return selectedLabels.some((raw) => {
+    const normalized = raw === "Everyone" ? "All Ages" : raw;
+    if (normalized === "18+") return blob.includes("18+");
+    if (normalized === "21+") return blob.includes("21+");
+    return (
+      blob.includes("All Ages") ||
+      blob.includes("Family Friendly") ||
+      (!blob.includes("18+") && !blob.includes("21+"))
+    );
+  });
+}
 
 export type BashEventTypeToStringType = {
   [key in BashEventType]: string;