@bash-app/bash-common 30.235.0 → 30.237.0

package/src/utils/service/unifiedPricingResolver.ts

@@ -0,0 +1,149 @@
+/**
+ * Phase 6 of the unified-pricing roadmap — forward-looking dual-read.
+ *
+ * Reads the unified pricing block from whichever subtype owns it (EventService,
+ * Vendor, Exhibitor, Sponsor, Venue, EntertainmentService, VolunteerService),
+ * then falls back to the legacy `ServiceRate` row pinned on the service if the
+ * unified block is null. Plain object passing only — no Prisma client calls,
+ * no fetches, no I/O.
+ *
+ * Use this from the booking + checkout paths so existing data keeps working
+ * while new wizard saves only write the unified block. When zero reads hit
+ * the fallback path, callers can drop `ServiceRate` + `ServiceRatesAssociation`
+ * entirely (the actual table drop is a follow-up migration).
+ */
+import type { PricingModel } from "@prisma/client";
+
+export interface UnifiedPricingBlock {
+  pricingModel: PricingModel | null;
+  baseRateCents: number | null;
+  baseRateBashPoints: number | null;
+  rateUnit: string | null;
+  minimumChargeCents: number | null;
+  minimumQuantity: number | null;
+  /** Json — keep `unknown` so callers narrow at use sites. */
+  tierPricing: unknown;
+  pricingNotes: string | null;
+  /** True iff this came from a unified block (vs the legacy ServiceRate). */
+  fromUnifiedBlock: boolean;
+  /** True iff `baseRateCents` was zero/null/missing in both paths. */
+  noRateConfigured: boolean;
+}
+
+export interface UnifiedPricingSourceCandidates {
+  /** Subtype rows on the parent Service. Pass whichever ones the include surfaced. */
+  eventService?: PartialPricingBlock | null;
+  vendor?: PartialPricingBlock | null;
+  exhibitor?: PartialPricingBlock | null;
+  sponsor?: PartialPricingBlock | null;
+  venue?: PartialPricingBlock | null;
+  entertainmentService?: PartialPricingBlock | null;
+  volunteerService?: PartialPricingBlock | null;
+  /** Legacy fallback — the active `ServiceRate` row. */
+  legacyRate?: LegacyServiceRateShape | null;
+}
+
+type PartialPricingBlock = {
+  pricingModel?: PricingModel | null;
+  baseRateCents?: number | null;
+  baseRateBashPoints?: number | null;
+  rateUnit?: string | null;
+  minimumChargeCents?: number | null;
+  minimumQuantity?: number | null;
+  tierPricing?: unknown;
+  pricingNotes?: string | null;
+};
+
+type LegacyServiceRateShape = {
+  /** Legacy doesn't carry a pricing model — caller can default to FLAT_FEE. */
+  ratePerUnitCents?: number | null;
+  rateUnit?: string | null;
+  minimumQuantity?: number | null;
+  minimumChargeCents?: number | null;
+};
+
+const EMPTY: UnifiedPricingBlock = {
+  pricingModel: null,
+  baseRateCents: null,
+  baseRateBashPoints: null,
+  rateUnit: null,
+  minimumChargeCents: null,
+  minimumQuantity: null,
+  tierPricing: null,
+  pricingNotes: null,
+  fromUnifiedBlock: false,
+  noRateConfigured: true,
+};
+
+function hasUnifiedSignal(b: PartialPricingBlock | null | undefined): boolean {
+  if (!b) return false;
+  return (
+    b.pricingModel != null ||
+    b.baseRateCents != null ||
+    b.baseRateBashPoints != null ||
+    b.minimumChargeCents != null ||
+    b.minimumQuantity != null
+  );
+}
+
+/**
+ * Walk the candidate subtypes in order, returning the first one that has
+ * unified pricing populated. Falls back to legacy `ServiceRate` if nothing
+ * has been migrated yet.
+ */
+export function resolveUnifiedPricingBlock(
+  c: UnifiedPricingSourceCandidates
+): UnifiedPricingBlock {
+  const candidates: Array<PartialPricingBlock | null | undefined> = [
+    c.eventService,
+    c.vendor,
+    c.exhibitor,
+    c.sponsor,
+    c.venue,
+    c.entertainmentService,
+    c.volunteerService,
+  ];
+
+  for (const cand of candidates) {
+    if (hasUnifiedSignal(cand)) {
+      const b = cand!;
+      const baseRateCents = b.baseRateCents ?? null;
+      return {
+        pricingModel: b.pricingModel ?? null,
+        baseRateCents,
+        baseRateBashPoints: b.baseRateBashPoints ?? null,
+        rateUnit: b.rateUnit ?? null,
+        minimumChargeCents: b.minimumChargeCents ?? null,
+        minimumQuantity: b.minimumQuantity ?? null,
+        tierPricing: b.tierPricing ?? null,
+        pricingNotes: b.pricingNotes ?? null,
+        fromUnifiedBlock: true,
+        noRateConfigured:
+          baseRateCents == null && (b.baseRateBashPoints ?? null) == null,
+      };
+    }
+  }
+
+  const legacy = c.legacyRate;
+  if (
+    legacy &&
+    (legacy.ratePerUnitCents != null ||
+      legacy.minimumQuantity != null ||
+      legacy.minimumChargeCents != null)
+  ) {
+    return {
+      pricingModel: "FLAT_FEE" as PricingModel,
+      baseRateCents: legacy.ratePerUnitCents ?? null,
+      baseRateBashPoints: null,
+      rateUnit: legacy.rateUnit ?? null,
+      minimumChargeCents: legacy.minimumChargeCents ?? null,
+      minimumQuantity: legacy.minimumQuantity ?? null,
+      tierPricing: null,
+      pricingNotes: null,
+      fromUnifiedBlock: false,
+      noRateConfigured: legacy.ratePerUnitCents == null,
+    };
+  }
+
+  return EMPTY;
+}

package/src/utils/service/venueSettlementUtils.ts

@@ -0,0 +1,198 @@
+/**
+ * Phase 2 of the unified-pricing roadmap — pure math for Venue F&B minimums
+ * and revenue share. Pure functions only (no Prisma / no fetches) so the
+ * wizard, api validators, settlement worker, and offer-suggestion AI can all
+ * share one source of truth.
+ *
+ * See `docs/help-center/pricing-models/` and the plan at
+ * `unified-pricing-roadmap_21d456c6.plan.md` for the policy story.
+ *
+ * Amounts are always integer cents.
+ */
+
+/** Days of week used in `Venue.fbMinimumSchedule`. Locale-agnostic short keys. */
+export const FB_MINIMUM_SCHEDULE_DAYS = [
+  "Sun",
+  "Mon",
+  "Tue",
+  "Wed",
+  "Thu",
+  "Fri",
+  "Sat",
+] as const;
+export type FBMinimumScheduleDay = (typeof FB_MINIMUM_SCHEDULE_DAYS)[number];
+
+/** Shape of the JSON stored at `Venue.fbMinimumSchedule`. */
+export type FBMinimumSchedule = Partial<Record<FBMinimumScheduleDay, number>>;
+
+/** Allowed values for `Venue.revenueShareBasis` (kept as plain strings since
+ *  the column is `String?` rather than an enum). */
+export const REVENUE_SHARE_BASES = [
+  "FB_SALES",
+  "TICKET_REVENUE",
+  "TOTAL_GROSS",
+] as const;
+export type RevenueShareBasis = (typeof REVENUE_SHARE_BASES)[number];
+
+/** Internal helper — cents → non-negative rounded integer. */
+function nonNegInt(value: number): number {
+  if (!Number.isFinite(value) || value <= 0) return 0;
+  return Math.round(value);
+}
+
+// ---------- F&B minimum: resolution + shortfall math ----------
+
+export interface ResolveFBMinimumInput {
+  /** Per-day-of-week schedule from `Venue.fbMinimumSchedule`. */
+  schedule: FBMinimumSchedule | null | undefined;
+  /** Optional date-windowed overrides from `VenueFBMinimumOverride`. */
+  overrides?: ReadonlyArray<{
+    startDate: Date;
+    endDate: Date;
+    minimumCents: number;
+  }>;
+  /** Bash start as it should be evaluated for day-of-week / override match. */
+  eventStartDateTime: Date;
+}
+
+/**
+ * Resolve the effective F&B minimum (in cents) for a given bash date.
+ *
+ * Override precedence: any matching window in `overrides` (inclusive endpoints)
+ * wins; otherwise the schedule entry for the day-of-week of `eventStartDateTime`
+ * is used. Returns `null` if neither produces a value.
+ *
+ * Callers that need timezone-aware day-of-week selection should pre-shift the
+ * Date before passing it in — this function uses `Date.getDay()` directly.
+ */
+export function resolveFBMinimumForDate(
+  input: ResolveFBMinimumInput
+): number | null {
+  if (input.overrides && input.overrides.length > 0) {
+    const ms = input.eventStartDateTime.getTime();
+    for (const o of input.overrides) {
+      if (o.startDate.getTime() <= ms && ms <= o.endDate.getTime()) {
+        return Math.max(0, Math.floor(o.minimumCents));
+      }
+    }
+  }
+  const schedule = input.schedule ?? null;
+  if (!schedule) return null;
+  const dayIdx = input.eventStartDateTime.getDay();
+  const dayKey = FB_MINIMUM_SCHEDULE_DAYS[dayIdx];
+  const value = schedule[dayKey];
+  if (value == null || !Number.isFinite(value)) return null;
+  return Math.max(0, Math.floor(value));
+}
+
+export interface FBShortfallInput {
+  /** Effective minimum (resolved via `resolveFBMinimumForDate`). */
+  fbMinimumCents: number;
+  /** Final food+bev sticker price from the venue invoice. */
+  fbActualSpendCents: number;
+  /** Service-charge cents the venue charged on top of the F&B subtotal. */
+  serviceChargeCents?: number | null;
+  /** Tax cents the venue charged on top of subtotal+service. */
+  taxCents?: number | null;
+  /** Snapshot of `Venue.fbServiceChargeCountsTowardMinimum`. */
+  serviceChargeCountsTowardMinimum: boolean;
+  /** Snapshot of `Venue.fbMinimumIncludesTax`. */
+  includesTax: boolean;
+}
+
+export interface FBShortfallResult {
+  /** Spend credited toward the minimum after svc-charge/tax flags. */
+  coveredSpendCents: number;
+  /** max(0, minimum - covered). */
+  shortfallCents: number;
+  /** max(0, covered - minimum). Useful for carryover-credit issuance. */
+  excessCents: number;
+  /** True if `shortfallCents === 0 && excessCents === 0`. */
+  metExactly: boolean;
+}
+
+/**
+ * Compute how much of the bash's F&B invoice counts toward the venue's
+ * minimum and the resulting shortfall (or excess) at settlement.
+ *
+ * Rules:
+ *   - Subtotal (`fbActualSpendCents`) ALWAYS counts toward the minimum.
+ *   - Service charge counts iff `serviceChargeCountsTowardMinimum`.
+ *   - Tax counts iff `includesTax`.
+ *
+ * All cents are integers and always non-negative.
+ */
+export function computeFBMinimumShortfallCents(
+  input: FBShortfallInput
+): FBShortfallResult {
+  const subtotal = nonNegInt(input.fbActualSpendCents);
+  const svc = nonNegInt(input.serviceChargeCents ?? 0);
+  const tax = nonNegInt(input.taxCents ?? 0);
+  const coveredSpendCents =
+    subtotal +
+    (input.serviceChargeCountsTowardMinimum ? svc : 0) +
+    (input.includesTax ? tax : 0);
+  const minimum = nonNegInt(input.fbMinimumCents);
+  const shortfallCents = Math.max(0, minimum - coveredSpendCents);
+  const excessCents = Math.max(0, coveredSpendCents - minimum);
+  return {
+    coveredSpendCents,
+    shortfallCents,
+    excessCents,
+    metExactly: shortfallCents === 0 && excessCents === 0,
+  };
+}
+
+// ---------- Revenue share ----------
+
+export interface RevenueShareInput {
+  /** The basis amount in cents (ticket revenue, F&B sales, etc.). */
+  basisCents: number;
+  /** Host percentage (0..100). Venue cut = basisCents * (100 - hostPct) / 100. */
+  hostPct: number;
+}
+
+export interface RevenueShareResult {
+  /** Host's share in cents. */
+  hostCents: number;
+  /** Venue's share in cents. Equals basis - host. */
+  venueCents: number;
+}
+
+/**
+ * Compute the revenue-share split given a basis and host percentage.
+ * Returns integer cents. Out-of-range hostPct is clamped to [0, 100].
+ */
+export function computeRevenueShareCents(
+  input: RevenueShareInput
+): RevenueShareResult {
+  const basis = nonNegInt(input.basisCents);
+  const hostPct = Math.max(0, Math.min(100, input.hostPct));
+  const hostCents = nonNegInt((basis * hostPct) / 100);
+  const venueCents = Math.max(0, basis - hostCents);
+  return { hostCents, venueCents };
+}
+
+// ---------- Cancellation copy ----------
+
+/** Surfaced on offer sheets + booking detail when an F&B minimum is attached. */
+export const FB_MINIMUM_CANCELLATION_COPY =
+  "If the bash is canceled within the venue's cancellation window, the host may still owe the F&B minimum shortfall. See the venue's cancellation policy for the exact timing.";
+
+/** Surfaced when a venue booking has revenue share configured. */
+export const REVENUE_SHARE_CANCELLATION_COPY =
+  "If the bash is canceled before tickets sell, no revenue-share payment is owed. See the venue's cancellation policy for late-cancel rules.";
+
+/** Default lifetime for a `VenueFBCarryoverCredit`, in days (12 months). */
+export const DEFAULT_FB_CARRYOVER_EXPIRY_DAYS = 365;
+
+/**
+ * Compute the default expiry timestamp for a newly-issued carryover credit.
+ */
+export function defaultFBCarryoverExpiresAt(
+  issuedAt: Date = new Date(),
+  days: number = DEFAULT_FB_CARRYOVER_EXPIRY_DAYS
+): Date {
+  const ms = issuedAt.getTime() + Math.max(1, Math.floor(days)) * 86_400_000;
+  return new Date(ms);
+}

package/src/utils/service/volunteerCompensationUtils.ts

@@ -0,0 +1,145 @@
+/**
+ * Volunteer compensation — closed-loop BashPoints stipends + on-site perks.
+ *
+ * Volunteers are NOT employees or contractors. This util intentionally avoids
+ * any USD rate / wage / per-attendee math, because crossing that line would
+ * trigger worker-classification, minimum-wage, and 1099 reporting concerns.
+ *
+ * BashPoints stipends are safe because BP is closed-loop platform credit:
+ *   - never cashed out,
+ *   - never used to settle third-party USD invoices,
+ *   - only redeemable against Bash-issued goods (tickets, BashPass upgrades,
+ *     premium features) — see the closed-loop BP plan.
+ *
+ * Pure functions only so the wizard, api validators, and help-center page
+ * share one source of truth.
+ */
+import { VolunteerCompensationType } from "../../mirroredPrismaEnums.js";
+
+/** Suggested starter BP stipend per shift. Hosts can override in the wizard. */
+export const DEFAULT_VOLUNTEER_STIPEND_BP_PER_SHIFT = 100;
+
+/** Suggested starter BP stipend per hour. */
+export const DEFAULT_VOLUNTEER_STIPEND_BP_PER_HOUR = 25;
+
+/** Allowed values for `VolunteerService.rateUnit`. */
+export const VOLUNTEER_RATE_UNITS = ["shift", "hour"] as const;
+export type VolunteerRateUnit = (typeof VOLUNTEER_RATE_UNITS)[number];
+
+/**
+ * Returns the suggested starter BP stipend for a volunteer profile based on
+ * how the host wants to denominate it. Wizard pre-fills `bashPointsStipend`
+ * with this; host can override.
+ */
+export function defaultStipendBpFor(args: {
+  rateUnit: VolunteerRateUnit | string | null | undefined;
+}): number {
+  if (args.rateUnit === "hour") {
+    return DEFAULT_VOLUNTEER_STIPEND_BP_PER_HOUR;
+  }
+  return DEFAULT_VOLUNTEER_STIPEND_BP_PER_SHIFT;
+}
+
+/**
+ * Returns true if the given compensation type pays any BashPoints. Used by
+ * the booking detail page + settlement worker to decide whether to surface
+ * BP-stipend fields.
+ */
+export function compensationTypePaysBashPoints(
+  t: VolunteerCompensationType | string | null | undefined
+): boolean {
+  return t === "BashPointsStipend" || t === "BashPointsAndPerks";
+}
+
+/**
+ * Returns true if the given compensation type includes on-site perks.
+ */
+export function compensationTypeIncludesPerks(
+  t: VolunteerCompensationType | string | null | undefined
+): boolean {
+  return t === "PerksOnly" || t === "BashPointsAndPerks";
+}
+
+/**
+ * Validates a saved volunteer compensation block. Returns a friendly error
+ * when the host's choices contradict (e.g. `PerksOnly` with a BP stipend
+ * filled in, or `BashPointsStipend` with no BP amount).
+ */
+export type VolunteerCompensationValidation =
+  | { ok: true }
+  | { ok: false; reason: string };
+
+export function validateVolunteerCompensation(args: {
+  compensationType: VolunteerCompensationType | string;
+  bashPointsStipend?: number | null;
+  rateUnit?: string | null;
+  perksDescription?: string | null;
+}): VolunteerCompensationValidation {
+  const paysBp = compensationTypePaysBashPoints(args.compensationType);
+  const hasPerks = compensationTypeIncludesPerks(args.compensationType);
+
+  if (paysBp) {
+    if (args.bashPointsStipend == null || args.bashPointsStipend <= 0) {
+      return {
+        ok: false,
+        reason: "BashPoints stipend amount required when compensation type pays BashPoints.",
+      };
+    }
+    if (!args.rateUnit) {
+      return {
+        ok: false,
+        reason: "Rate unit (shift or hour) required when paying a BashPoints stipend.",
+      };
+    }
+  }
+  if (!paysBp && args.bashPointsStipend != null && args.bashPointsStipend > 0) {
+    return {
+      ok: false,
+      reason: "BashPoints stipend set but compensation type doesn't pay BashPoints.",
+    };
+  }
+  if (hasPerks && !args.perksDescription) {
+    return {
+      ok: false,
+      reason: "Describe the perks volunteers will receive.",
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * Plain-English label for the booking detail page + booking thread system
+ * messages. Stable across renders.
+ */
+export function volunteerCompensationSummary(args: {
+  compensationType: VolunteerCompensationType | string;
+  bashPointsStipend?: number | null;
+  rateUnit?: string | null;
+  perksDescription?: string | null;
+}): string {
+  switch (args.compensationType) {
+    case "None":
+      return "Pure volunteer — no stipend or perks beyond appreciation.";
+    case "BashPointsStipend":
+      return `${args.bashPointsStipend ?? 0} BashPoints per ${args.rateUnit ?? "shift"}.`;
+    case "PerksOnly":
+      return args.perksDescription
+        ? `Perks only: ${args.perksDescription}`
+        : "Perks only.";
+    case "BashPointsAndPerks":
+      return `${args.bashPointsStipend ?? 0} BashPoints per ${
+        args.rateUnit ?? "shift"
+      } + perks${
+        args.perksDescription ? ` (${args.perksDescription})` : ""
+      }.`;
+    default:
+      return "Compensation unspecified.";
+  }
+}
+
+/**
+ * Disclaimer copy for the volunteer wizard step + help-center page + booking
+ * detail. Kept here so wizard, api, and docs cite the exact same wording.
+ */
+export const VOLUNTEER_COMPENSATION_DISCLAIMER =
+  "Volunteers are not employees or contractors. BashPoints stipends are platform credit redeemable on Bash, not wages, and don't count toward employment or 1099 reporting.";

package/src/utils/venueLoyalty/__tests__/eligibilityUtils.test.ts

@@ -0,0 +1,103 @@
+/**
+ * Pure eligibility evaluator — same logic runs on API + bash-app, so this
+ * suite locks the truth table for both call sites.
+ */
+import {
+  evaluateEligibility,
+  evaluateOffersEligibility,
+} from "../eligibilityUtils.js";
+
+const baseMetrics = { ticketedEventsAttended: 2, bookingsAsHost: 0 };
+
+describe("evaluateEligibility", () => {
+  test("offer with no gates and no cooldown is eligible", () => {
+    const result = evaluateEligibility(baseMetrics, {
+      id: "o1",
+      minTicketedEventsAttended: null,
+      minBookingsAsHost: null,
+    });
+    expect(result.eligible).toBe(true);
+    expect(result.missing.ticketedEventsShort).toBeNull();
+    expect(result.missing.bookingsAsHostShort).toBeNull();
+    expect(result.onCooldownUntil).toBeNull();
+  });
+
+  test("guest meets ticketed gate exactly is eligible", () => {
+    const result = evaluateEligibility(
+      { ticketedEventsAttended: 3, bookingsAsHost: 0 },
+      { id: "o2", minTicketedEventsAttended: 3, minBookingsAsHost: null },
+    );
+    expect(result.eligible).toBe(true);
+    expect(result.missing.ticketedEventsShort).toBeNull();
+  });
+
+  test("guest one short on ticketed gate surfaces shortfall + locked state", () => {
+    const result = evaluateEligibility(
+      { ticketedEventsAttended: 2, bookingsAsHost: 0 },
+      { id: "o3", minTicketedEventsAttended: 3, minBookingsAsHost: null },
+    );
+    expect(result.eligible).toBe(false);
+    expect(result.missing.ticketedEventsShort).toBe(1);
+    expect(result.missing.bookingsAsHostShort).toBeNull();
+  });
+
+  test("guest short on both gates surfaces both shortfalls", () => {
+    const result = evaluateEligibility(
+      { ticketedEventsAttended: 1, bookingsAsHost: 0 },
+      { id: "o4", minTicketedEventsAttended: 4, minBookingsAsHost: 2 },
+    );
+    expect(result.eligible).toBe(false);
+    expect(result.missing.ticketedEventsShort).toBe(3);
+    expect(result.missing.bookingsAsHostShort).toBe(2);
+  });
+
+  test("gates met but cooldown active surfaces onCooldownUntil + ineligible", () => {
+    const futureDate = new Date(Date.now() + 86400_000);
+    const result = evaluateEligibility(
+      { ticketedEventsAttended: 5, bookingsAsHost: 5 },
+      { id: "o5", minTicketedEventsAttended: 1, minBookingsAsHost: 1 },
+      futureDate,
+    );
+    expect(result.eligible).toBe(false);
+    expect(result.onCooldownUntil).toBe(futureDate.toISOString());
+  });
+
+  test("gates met and cooldown elapsed flips back to eligible", () => {
+    const pastDate = new Date(Date.now() - 86400_000);
+    const result = evaluateEligibility(
+      { ticketedEventsAttended: 5, bookingsAsHost: 5 },
+      { id: "o6", minTicketedEventsAttended: 1, minBookingsAsHost: 1 },
+      pastDate,
+    );
+    expect(result.eligible).toBe(true);
+    expect(result.onCooldownUntil).toBeNull();
+  });
+
+  test("cooldown accepts ISO string input", () => {
+    const futureIso = new Date(Date.now() + 3600_000).toISOString();
+    const result = evaluateEligibility(
+      { ticketedEventsAttended: 5, bookingsAsHost: 5 },
+      { id: "o7", minTicketedEventsAttended: null, minBookingsAsHost: null },
+      futureIso,
+    );
+    expect(result.eligible).toBe(false);
+    expect(result.onCooldownUntil).toBe(futureIso);
+  });
+});
+
+describe("evaluateOffersEligibility", () => {
+  test("maps each offer with the right cooldown from the keyed map", () => {
+    const future = new Date(Date.now() + 86400_000).toISOString();
+    const result = evaluateOffersEligibility(
+      { ticketedEventsAttended: 2, bookingsAsHost: 1 },
+      [
+        { id: "a", minTicketedEventsAttended: null, minBookingsAsHost: null },
+        { id: "b", minTicketedEventsAttended: 3, minBookingsAsHost: null },
+        { id: "c", minTicketedEventsAttended: 1, minBookingsAsHost: 1 },
+      ],
+      { c: future },
+    );
+    expect(result.map((r) => r.eligible)).toEqual([true, false, false]);
+    expect(result[2].onCooldownUntil).toBe(future);
+  });
+});

package/src/utils/venueLoyalty/__tests__/redemptionCodeUtils.test.ts

@@ -0,0 +1,92 @@
+/**
+ * Pin the redemption code alphabet, length, normalization, and uniqueness
+ * retry loop. Hosts type these codes from a phone — fat-finger characters
+ * (I, O, 0, 1) must never appear.
+ */
+import {
+  REDEMPTION_CODE_LENGTH,
+  __testInternals,
+  generateRedemptionCode,
+  generateUniqueRedemptionCode,
+  isValidRedemptionCodeShape,
+  normalizeRedemptionCode,
+} from "../redemptionCodeUtils.js";
+
+describe("redemption code shape", () => {
+  test("alphabet excludes ambiguous characters", () => {
+    const alphabet = __testInternals.REDEMPTION_CODE_ALPHABET;
+    expect(alphabet).not.toMatch(/[IO01]/);
+    expect(alphabet).toHaveLength(32);
+  });
+
+  test("isValidRedemptionCodeShape accepts canonical codes", () => {
+    expect(isValidRedemptionCodeShape("ABCDEF23")).toBe(true);
+  });
+
+  test("isValidRedemptionCodeShape rejects wrong length", () => {
+    expect(isValidRedemptionCodeShape("ABCDEF2")).toBe(false);
+    expect(isValidRedemptionCodeShape("ABCDEF234")).toBe(false);
+  });
+
+  test("isValidRedemptionCodeShape rejects ambiguous chars", () => {
+    expect(isValidRedemptionCodeShape("ABCDEFI2")).toBe(false);
+    expect(isValidRedemptionCodeShape("ABCDEFO2")).toBe(false);
+    expect(isValidRedemptionCodeShape("ABCDEF02")).toBe(false);
+    expect(isValidRedemptionCodeShape("ABCDEF12")).toBe(false);
+  });
+
+  test("isValidRedemptionCodeShape rejects lowercase", () => {
+    expect(isValidRedemptionCodeShape("abcdef23")).toBe(false);
+  });
+});
+
+describe("normalizeRedemptionCode", () => {
+  test("strips whitespace + dashes and uppercases", () => {
+    expect(normalizeRedemptionCode("ab12-cd34")).toBe("AB12CD34");
+    expect(normalizeRedemptionCode("  abcdef23  ")).toBe("ABCDEF23");
+    expect(normalizeRedemptionCode("a b\tc-d\n2 3 4 5")).toBe("ABCD2345");
+  });
+});
+
+describe("generateRedemptionCode", () => {
+  test("produces 8-char codes from the alphabet", () => {
+    const code = generateRedemptionCode();
+    expect(code).toHaveLength(REDEMPTION_CODE_LENGTH);
+    expect(isValidRedemptionCodeShape(code)).toBe(true);
+  });
+
+  test("respects injected random bytes", () => {
+    const bytes = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7]);
+    const code = generateRedemptionCode(() => bytes);
+    const alphabet = __testInternals.REDEMPTION_CODE_ALPHABET;
+    expect(code).toBe(
+      Array.from(bytes)
+        .map((b) => alphabet[b % alphabet.length])
+        .join(""),
+    );
+  });
+});
+
+describe("generateUniqueRedemptionCode", () => {
+  test("returns the first non-colliding candidate", async () => {
+    const seen = new Set<string>();
+    const code = await generateUniqueRedemptionCode(async (c) => seen.has(c));
+    expect(isValidRedemptionCodeShape(code)).toBe(true);
+  });
+
+  test("retries until one succeeds", async () => {
+    let calls = 0;
+    const code = await generateUniqueRedemptionCode(async () => {
+      calls += 1;
+      return calls < 3;
+    });
+    expect(calls).toBe(3);
+    expect(isValidRedemptionCodeShape(code)).toBe(true);
+  });
+
+  test("throws after exhausting attempts", async () => {
+    await expect(
+      generateUniqueRedemptionCode(async () => true, { maxAttempts: 4 }),
+    ).rejects.toThrow(/Could not generate a unique/);
+  });
+});