@bash-app/bash-common 30.235.0 → 30.237.0

package/src/utils/venueLoyalty/eligibilityUtils.ts

@@ -0,0 +1,84 @@
+/**
+ * Pure (no Prisma, no `bash-app` imports) eligibility evaluator for venue
+ * loyalty offers. Runs identically on the server (gating claim creation) and
+ * the client (rendering locked / progress states on the public loyalty
+ * section).
+ *
+ * The actual metric collection lives in
+ * `api/src/utils/venueLoyalty/eligibilityCalculator.ts` for the server and
+ * comes pre-computed from the eligibility endpoint for the client.
+ */
+
+import type {
+  VenueLoyaltyEligibilitySnapshot,
+  VenueLoyaltyOfferDto,
+  VenueLoyaltyOfferEligibility,
+} from "../../venueLoyaltyRedemption.js";
+
+/**
+ * Subset of `VenueLoyaltyOfferDto` the evaluator needs. Kept narrow so callers
+ * can pass in the Prisma row directly without remapping.
+ */
+export interface OfferGates {
+  id: string;
+  minTicketedEventsAttended: number | null;
+  minBookingsAsHost: number | null;
+}
+
+/**
+ * Evaluate one offer against one guest's metric snapshot. Optional
+ * `onCooldownUntil` (already computed from the latest non-active redemption +
+ * `offer.cooldownDays`) shadows eligibility so the UI shows "available in N
+ * days" instead of unlock progress.
+ */
+export function evaluateEligibility(
+  metrics: VenueLoyaltyEligibilitySnapshot,
+  offer: OfferGates,
+  onCooldownUntil: Date | string | null = null,
+): VenueLoyaltyOfferEligibility {
+  const ticketedEventsShort =
+    offer.minTicketedEventsAttended !== null &&
+    offer.minTicketedEventsAttended > metrics.ticketedEventsAttended
+      ? offer.minTicketedEventsAttended - metrics.ticketedEventsAttended
+      : null;
+
+  const bookingsAsHostShort =
+    offer.minBookingsAsHost !== null &&
+    offer.minBookingsAsHost > metrics.bookingsAsHost
+      ? offer.minBookingsAsHost - metrics.bookingsAsHost
+      : null;
+
+  const cooldownIso =
+    onCooldownUntil instanceof Date
+      ? onCooldownUntil.toISOString()
+      : onCooldownUntil;
+
+  const cooldownActive = cooldownIso !== null && new Date(cooldownIso) > new Date();
+
+  const gatesMet = ticketedEventsShort === null && bookingsAsHostShort === null;
+
+  return {
+    offerId: offer.id,
+    eligible: gatesMet && !cooldownActive,
+    missing: {
+      ticketedEventsShort,
+      bookingsAsHostShort,
+    },
+    onCooldownUntil: cooldownActive ? cooldownIso : null,
+    metrics,
+  };
+}
+
+/**
+ * Batch helper for rendering a venue's full offer list with eligibility in
+ * one pass. `cooldownMap` is keyed by `offerId`.
+ */
+export function evaluateOffersEligibility(
+  metrics: VenueLoyaltyEligibilitySnapshot,
+  offers: ReadonlyArray<Pick<VenueLoyaltyOfferDto, "id" | "minTicketedEventsAttended" | "minBookingsAsHost">>,
+  cooldownMap: Record<string, Date | string | null> = {},
+): VenueLoyaltyOfferEligibility[] {
+  return offers.map((offer) =>
+    evaluateEligibility(metrics, offer, cooldownMap[offer.id] ?? null),
+  );
+}

package/src/utils/venueLoyalty/redemptionCodeUtils.ts

@@ -0,0 +1,94 @@
+/**
+ * Redemption code generation + validation for venue loyalty claims.
+ *
+ * Codes are 8 characters from a 32-letter alphabet that excludes the visually
+ * ambiguous `I`, `O`, `0`, `1` so a host typing the code from a phone screen
+ * doesn't fat-finger it. Collisions are scoped per-venue (see the unique
+ * constraint on `VenueLoyaltyRedemption(venueId, redemptionCode)`), so the
+ * 32^8 ≈ 1.1 trillion keyspace is enormous overkill — the retry loop in
+ * `generateUniqueRedemptionCode` exists to be defensive, not because we
+ * expect contention.
+ */
+
+const REDEMPTION_CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+export const REDEMPTION_CODE_LENGTH = 8;
+
+const REDEMPTION_CODE_REGEX = new RegExp(
+  `^[${REDEMPTION_CODE_ALPHABET}]{${REDEMPTION_CODE_LENGTH}}$`,
+);
+
+/** True iff `code` matches the canonical 8-char alphabet. */
+export function isValidRedemptionCodeShape(code: string): boolean {
+  return REDEMPTION_CODE_REGEX.test(code);
+}
+
+/**
+ * Normalize user input — uppercase, strip whitespace + dashes — before
+ * validation or DB lookup. Lets us accept "ab12-cd34" from a phone keyboard.
+ */
+export function normalizeRedemptionCode(input: string): string {
+  return input.replace(/[\s-]/g, "").toUpperCase();
+}
+
+/** Single 8-char code, sampled from a CSPRNG when available. */
+export function generateRedemptionCode(
+  randomBytes: (length: number) => Uint8Array = defaultRandomBytes,
+): string {
+  const bytes = randomBytes(REDEMPTION_CODE_LENGTH);
+  let out = "";
+  for (let i = 0; i < REDEMPTION_CODE_LENGTH; i += 1) {
+    out += REDEMPTION_CODE_ALPHABET[bytes[i] % REDEMPTION_CODE_ALPHABET.length];
+  }
+  return out;
+}
+
+/**
+ * Sample fresh codes until `existsInVenue(code)` returns false. Bounded to
+ * `maxAttempts` so a misbehaving uniqueness probe can't spin forever. Throws
+ * after exhausting attempts — caller should surface a 5xx, this would mean
+ * the keyspace is exhausted (impossible in practice) or the DB is unhealthy.
+ */
+export async function generateUniqueRedemptionCode(
+  existsInVenue: (code: string) => Promise<boolean>,
+  options: {
+    randomBytes?: (length: number) => Uint8Array;
+    maxAttempts?: number;
+  } = {},
+): Promise<string> {
+  const maxAttempts = options.maxAttempts ?? 10;
+  const randomBytes = options.randomBytes ?? defaultRandomBytes;
+  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    const candidate = generateRedemptionCode(randomBytes);
+    if (!(await existsInVenue(candidate))) {
+      return candidate;
+    }
+  }
+  throw new Error(
+    `Could not generate a unique venue loyalty redemption code after ${maxAttempts} attempts`,
+  );
+}
+
+function defaultRandomBytes(length: number): Uint8Array {
+  const cryptoObj: Crypto | undefined =
+    typeof globalThis !== "undefined" &&
+    (globalThis as { crypto?: Crypto }).crypto
+      ? (globalThis as { crypto?: Crypto }).crypto
+      : undefined;
+  if (cryptoObj?.getRandomValues) {
+    const buf = new Uint8Array(length);
+    cryptoObj.getRandomValues(buf);
+    return buf;
+  }
+  // Last-resort fallback for environments without WebCrypto (legacy tests).
+  // Not security-critical because redemption codes are scoped per-venue
+  // behind auth, but still tries to spread entropy across the buffer.
+  const buf = new Uint8Array(length);
+  for (let i = 0; i < length; i += 1) {
+    buf[i] = Math.floor(Math.random() * 256);
+  }
+  return buf;
+}
+
+export const __testInternals = {
+  REDEMPTION_CODE_ALPHABET,
+};

package/src/venueLoyaltyRedemption.ts

@@ -1,22 +1,197 @@
 /**
- * API shapes for venue loyalty perk requests (guest claim + host list/redeem).
+ * API shapes for venue loyalty perk offers + redemptions (guest claim / decline
+ * / redeem / expire). All BashPoints movements through these flows ledger via
+ * `CreditSourceType.VenueLoyaltyRedemption` — see
+ * `api/src/services/venueLoyaltyRedemptionService.ts`.
  */
 
+import type { VenueLoyaltyTemplateId } from "./utils/service/serviceUtils.js";
+
+/**
+ * Public DTO for a `VenueLoyaltyOffer` row. `bashPointsCost` of `null` means
+ * the offer is a legacy "polite request" with no BashPoints price (host
+ * fulfills on goodwill).
+ */
+export interface VenueLoyaltyOfferDto {
+  id: string;
+  venueId: string;
+  templateId: string;
+  title: string;
+  description: string | null;
+  bashPointsCost: number | null;
+  minTicketedEventsAttended: number | null;
+  minBookingsAsHost: number | null;
+  cooldownDays: number;
+  claimExpiryDays: number;
+  enabled: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/**
+ * Payload for `POST /venue-loyalty/offers`. `title` defaults to the template
+ * label client-side if omitted; server validates it's non-empty before write.
+ */
+export interface CreateVenueLoyaltyOfferRequest {
+  venueId: string;
+  templateId: VenueLoyaltyTemplateId;
+  title: string;
+  description?: string | null;
+  bashPointsCost?: number | null;
+  minTicketedEventsAttended?: number | null;
+  minBookingsAsHost?: number | null;
+  cooldownDays?: number;
+  claimExpiryDays?: number;
+  enabled?: boolean;
+}
+
+/** Payload for `PATCH /venue-loyalty/offers/:id`. */
+export type UpdateVenueLoyaltyOfferRequest = Partial<
+  Omit<CreateVenueLoyaltyOfferRequest, "venueId" | "templateId">
+>;
+
+/**
+ * Snapshot of the gating metrics at claim time, persisted on the
+ * redemption row for audit. Stored as a Prisma `Json` column on the
+ * server; this type defines the canonical shape.
+ */
+export interface VenueLoyaltyEligibilitySnapshot {
+  ticketedEventsAttended: number;
+  bookingsAsHost: number;
+}
+
+/**
+ * Per-offer eligibility result for a specific guest viewing a venue's loyalty
+ * section. Drives the locked-state / progress-copy UI on the public detail page.
+ */
+export interface VenueLoyaltyOfferEligibility {
+  offerId: string;
+  eligible: boolean;
+  /**
+   * How short the guest is on each gate, if any. `null` if no gate of that
+   * kind exists on the offer.
+   */
+  missing: {
+    ticketedEventsShort: number | null;
+    bookingsAsHostShort: number | null;
+  };
+  /**
+   * `claimedAt + cooldownDays` for the guest's most recent non-active claim
+   * against this offer, when the cooldown has not yet elapsed. `null` when no
+   * cooldown applies.
+   */
+  onCooldownUntil: string | null;
+  /** Current metric values, useful for "1 of 3" style copy. */
+  metrics: VenueLoyaltyEligibilitySnapshot;
+}
+
+/** Response for `GET /venue-loyalty/eligibility/:venueId`. */
+export interface VenueLoyaltyEligibilityResponse {
+  venueId: string;
+  offers: VenueLoyaltyOfferEligibility[];
+}
+
+/**
+ * Guest-facing redemption DTO. `redemptionCode` is only populated for active
+ * (un-redeemed, un-declined, un-expired) claims so the guest can show it to
+ * the host. Once the redemption resolves, the code is preserved for history.
+ */
 export interface VenueLoyaltyRedemptionGuestDto {
   id: string;
   venueId: string;
+  offerId: string | null;
   userId: string;
   templateId: string;
+  bashPointsCost: number;
+  redemptionCode: string | null;
+  expiresAt: string | null;
   claimedAt: string;
   redeemedAt: string | null;
+  declinedAt: string | null;
+  expiredAt: string | null;
+  cancelReason: string | null;
   guestNotes: string | null;
   hostNotes: string | null;
 }
 
-export interface VenueLoyaltyRedemptionListItem extends VenueLoyaltyRedemptionGuestDto {
+/** Host-side row with guest identity for the venue's claims inbox. */
+export interface VenueLoyaltyRedemptionListItem
+  extends VenueLoyaltyRedemptionGuestDto {
   user: {
     email: string;
     givenName: string | null;
     familyName: string | null;
   };
+  eligibilitySnapshot: VenueLoyaltyEligibilitySnapshot | null;
+}
+
+/** Lifecycle states a guest sees on the "My loyalty claims" page. */
+export type VenueLoyaltyRedemptionStatus =
+  | "Active"
+  | "Redeemed"
+  | "Declined"
+  | "Expired";
+
+/**
+ * Compose the guest-facing status from the timestamp fields. Mirrors the
+ * server-side state machine; kept here so guards in UI + tests share one
+ * source of truth.
+ */
+export function getVenueLoyaltyRedemptionStatus(redemption: {
+  redeemedAt: string | null;
+  declinedAt: string | null;
+  expiredAt: string | null;
+}): VenueLoyaltyRedemptionStatus {
+  if (redemption.redeemedAt) return "Redeemed";
+  if (redemption.declinedAt) return "Declined";
+  if (redemption.expiredAt) return "Expired";
+  return "Active";
+}
+
+/**
+ * Extended view returned by `GET /venue-loyalty/my-claims` so the guest sees
+ * which venue + offer the code is for without a second round trip.
+ */
+export interface VenueLoyaltyRedemptionMyClaimItem
+  extends VenueLoyaltyRedemptionGuestDto {
+  status: VenueLoyaltyRedemptionStatus;
+  venue: {
+    id: string;
+    name: string;
+    serviceId: string | null;
+  };
+  offer: Pick<
+    VenueLoyaltyOfferDto,
+    "id" | "title" | "description" | "templateId"
+  > | null;
+}
+
+/** Body for `POST /venue-loyalty/claim` (extended with `offerId`). */
+export interface ClaimVenueLoyaltyRequest {
+  venueId: string;
+  offerId: string;
+  guestNotes?: string;
+}
+
+/** Successful response for `POST /venue-loyalty/claim`. */
+export interface ClaimVenueLoyaltyResponse {
+  redemption: VenueLoyaltyRedemptionGuestDto;
+  /**
+   * Convenience copy of `redemption.redemptionCode` so the success UI can
+   * pull it without branching on null. Equals `null` only when the offer was
+   * free (bashPointsCost == null) — currently still issued for traceability.
+   */
+  code: string;
+  remainingBashPoints: number;
+}
+
+/** Body for `PATCH /venue-loyalty/:id/redeem` (extended with `redemptionCode`). */
+export interface RedeemVenueLoyaltyRequest {
+  redemptionCode: string;
+  hostNotes?: string;
+}
+
+/** Body for `PATCH /venue-loyalty/:id/decline`. */
+export interface DeclineVenueLoyaltyRequest {
+  hostNotes?: string;
 }