@bash-app/bash-common 30.235.0 → 30.237.0

package/dist/utils/service/volunteerCompensationUtils.js

@@ -0,0 +1,88 @@
+/** 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"];
+/**
+ * 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) {
+    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) {
+    return t === "BashPointsStipend" || t === "BashPointsAndPerks";
+}
+/**
+ * Returns true if the given compensation type includes on-site perks.
+ */
+export function compensationTypeIncludesPerks(t) {
+    return t === "PerksOnly" || t === "BashPointsAndPerks";
+}
+export function validateVolunteerCompensation(args) {
+    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) {
+    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.";
+//# sourceMappingURL=volunteerCompensationUtils.js.map

package/dist/utils/service/volunteerCompensationUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"volunteerCompensationUtils.js","sourceRoot":"","sources":["../../../src/utils/service/volunteerCompensationUtils.ts"],"names":[],"mappings":"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"}

package/dist/utils/venueLoyalty/__tests__/eligibilityUtils.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=eligibilityUtils.test.d.ts.map

package/dist/utils/venueLoyalty/__tests__/eligibilityUtils.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eligibilityUtils.test.d.ts","sourceRoot":"","sources":["../../../../src/utils/venueLoyalty/__tests__/eligibilityUtils.test.ts"],"names":[],"mappings":""}

package/dist/utils/venueLoyalty/__tests__/eligibilityUtils.test.js

@@ -0,0 +1,67 @@
+/**
+ * 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);
+    });
+});
+//# sourceMappingURL=eligibilityUtils.test.js.map

package/dist/utils/venueLoyalty/__tests__/eligibilityUtils.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eligibilityUtils.test.js","sourceRoot":"","sources":["../../../../src/utils/venueLoyalty/__tests__/eligibilityUtils.test.ts"],"names":[],"mappings":"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"}

package/dist/utils/venueLoyalty/__tests__/redemptionCodeUtils.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=redemptionCodeUtils.test.d.ts.map

package/dist/utils/venueLoyalty/__tests__/redemptionCodeUtils.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redemptionCodeUtils.test.d.ts","sourceRoot":"","sources":["../../../../src/utils/venueLoyalty/__tests__/redemptionCodeUtils.test.ts"],"names":[],"mappings":""}

package/dist/utils/venueLoyalty/__tests__/redemptionCodeUtils.test.js

@@ -0,0 +1,71 @@
+/**
+ * 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();
+        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/);
+    });
+});
+//# sourceMappingURL=redemptionCodeUtils.test.js.map

package/dist/utils/venueLoyalty/__tests__/redemptionCodeUtils.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redemptionCodeUtils.test.js","sourceRoot":"","sources":["../../../../src/utils/venueLoyalty/__tests__/redemptionCodeUtils.test.ts"],"names":[],"mappings":"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"}

package/dist/utils/venueLoyalty/eligibilityUtils.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 declare function evaluateEligibility(metrics: VenueLoyaltyEligibilitySnapshot, offer: OfferGates, onCooldownUntil?: Date | string | null): VenueLoyaltyOfferEligibility;
+/**
+ * Batch helper for rendering a venue's full offer list with eligibility in
+ * one pass. `cooldownMap` is keyed by `offerId`.
+ */
+export declare function evaluateOffersEligibility(metrics: VenueLoyaltyEligibilitySnapshot, offers: ReadonlyArray<Pick<VenueLoyaltyOfferDto, "id" | "minTicketedEventsAttended" | "minBookingsAsHost">>, cooldownMap?: Record<string, Date | string | null>): VenueLoyaltyOfferEligibility[];
+//# sourceMappingURL=eligibilityUtils.d.ts.map

package/dist/utils/venueLoyalty/eligibilityUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eligibilityUtils.d.ts","sourceRoot":"","sources":["../../../src/utils/venueLoyalty/eligibilityUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,+BAA+B,EAC/B,oBAAoB,EACpB,4BAA4B,EAC7B,MAAM,iCAAiC,CAAC;AAEzC;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,yBAAyB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,+BAA+B,EACxC,KAAK,EAAE,UAAU,EACjB,eAAe,GAAE,IAAI,GAAG,MAAM,GAAG,IAAW,GAC3C,4BAA4B,CAgC9B;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,+BAA+B,EACxC,MAAM,EAAE,aAAa,CAAC,IAAI,CAAC,oBAAoB,EAAE,IAAI,GAAG,2BAA2B,GAAG,mBAAmB,CAAC,CAAC,EAC3G,WAAW,GAAE,MAAM,CAAC,MAAM,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAAM,GACrD,4BAA4B,EAAE,CAIhC"}

package/dist/utils/venueLoyalty/eligibilityUtils.js

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ */
+/**
+ * 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, offer, onCooldownUntil = null) {
+    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, offers, cooldownMap = {}) {
+    return offers.map((offer) => evaluateEligibility(metrics, offer, cooldownMap[offer.id] ?? null));
+}
+//# sourceMappingURL=eligibilityUtils.js.map

package/dist/utils/venueLoyalty/eligibilityUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eligibilityUtils.js","sourceRoot":"","sources":["../../../src/utils/venueLoyalty/eligibilityUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAkBH;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAwC,EACxC,KAAiB,EACjB,kBAAwC,IAAI;IAE5C,MAAM,mBAAmB,GACvB,KAAK,CAAC,yBAAyB,KAAK,IAAI;QACxC,KAAK,CAAC,yBAAyB,GAAG,OAAO,CAAC,sBAAsB;QAC9D,CAAC,CAAC,KAAK,CAAC,yBAAyB,GAAG,OAAO,CAAC,sBAAsB;QAClE,CAAC,CAAC,IAAI,CAAC;IAEX,MAAM,mBAAmB,GACvB,KAAK,CAAC,iBAAiB,KAAK,IAAI;QAChC,KAAK,CAAC,iBAAiB,GAAG,OAAO,CAAC,cAAc;QAC9C,CAAC,CAAC,KAAK,CAAC,iBAAiB,GAAG,OAAO,CAAC,cAAc;QAClD,CAAC,CAAC,IAAI,CAAC;IAEX,MAAM,WAAW,GACf,eAAe,YAAY,IAAI;QAC7B,CAAC,CAAC,eAAe,CAAC,WAAW,EAAE;QAC/B,CAAC,CAAC,eAAe,CAAC;IAEtB,MAAM,cAAc,GAAG,WAAW,KAAK,IAAI,IAAI,IAAI,IAAI,CAAC,WAAW,CAAC,GAAG,IAAI,IAAI,EAAE,CAAC;IAElF,MAAM,QAAQ,GAAG,mBAAmB,KAAK,IAAI,IAAI,mBAAmB,KAAK,IAAI,CAAC;IAE9E,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,EAAE;QACjB,QAAQ,EAAE,QAAQ,IAAI,CAAC,cAAc;QACrC,OAAO,EAAE;YACP,mBAAmB;YACnB,mBAAmB;SACpB;QACD,eAAe,EAAE,cAAc,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI;QACpD,OAAO;KACR,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAwC,EACxC,MAA2G,EAC3G,cAAoD,EAAE;IAEtD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAC1B,mBAAmB,CAAC,OAAO,EAAE,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,CACnE,CAAC;AACJ,CAAC"}

package/dist/utils/venueLoyalty/redemptionCodeUtils.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ */
+export declare const REDEMPTION_CODE_LENGTH = 8;
+/** True iff `code` matches the canonical 8-char alphabet. */
+export declare function isValidRedemptionCodeShape(code: string): boolean;
+/**
+ * Normalize user input — uppercase, strip whitespace + dashes — before
+ * validation or DB lookup. Lets us accept "ab12-cd34" from a phone keyboard.
+ */
+export declare function normalizeRedemptionCode(input: string): string;
+/** Single 8-char code, sampled from a CSPRNG when available. */
+export declare function generateRedemptionCode(randomBytes?: (length: number) => Uint8Array): string;
+/**
+ * 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 declare function generateUniqueRedemptionCode(existsInVenue: (code: string) => Promise<boolean>, options?: {
+    randomBytes?: (length: number) => Uint8Array;
+    maxAttempts?: number;
+}): Promise<string>;
+export declare const __testInternals: {
+    REDEMPTION_CODE_ALPHABET: string;
+};
+//# sourceMappingURL=redemptionCodeUtils.d.ts.map

package/dist/utils/venueLoyalty/redemptionCodeUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redemptionCodeUtils.d.ts","sourceRoot":"","sources":["../../../src/utils/venueLoyalty/redemptionCodeUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAMxC,6DAA6D;AAC7D,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,gEAAgE;AAChE,wBAAgB,sBAAsB,CACpC,WAAW,GAAE,CAAC,MAAM,EAAE,MAAM,KAAK,UAA+B,GAC/D,MAAM,CAOR;AAED;;;;;GAKG;AACH,wBAAsB,4BAA4B,CAChD,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,EACjD,OAAO,GAAE;IACP,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,UAAU,CAAC;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;CACjB,GACL,OAAO,CAAC,MAAM,CAAC,CAYjB;AAuBD,eAAO,MAAM,eAAe;;CAE3B,CAAC"}

package/dist/utils/venueLoyalty/redemptionCodeUtils.js

@@ -0,0 +1,74 @@
+/**
+ * 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) {
+    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) {
+    return input.replace(/[\s-]/g, "").toUpperCase();
+}
+/** Single 8-char code, sampled from a CSPRNG when available. */
+export function generateRedemptionCode(randomBytes = defaultRandomBytes) {
+    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, options = {}) {
+    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) {
+    const cryptoObj = typeof globalThis !== "undefined" &&
+        globalThis.crypto
+        ? globalThis.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,
+};
+//# sourceMappingURL=redemptionCodeUtils.js.map

package/dist/utils/venueLoyalty/redemptionCodeUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redemptionCodeUtils.js","sourceRoot":"","sources":["../../../src/utils/venueLoyalty/redemptionCodeUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,wBAAwB,GAAG,kCAAkC,CAAC;AACpE,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAExC,MAAM,qBAAqB,GAAG,IAAI,MAAM,CACtC,KAAK,wBAAwB,KAAK,sBAAsB,IAAI,CAC7D,CAAC;AAEF,6DAA6D;AAC7D,MAAM,UAAU,0BAA0B,CAAC,IAAY;IACrD,OAAO,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAa;IACnD,OAAO,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;AACnD,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,sBAAsB,CACpC,cAA8C,kBAAkB;IAEhE,MAAM,KAAK,GAAG,WAAW,CAAC,sBAAsB,CAAC,CAAC;IAClD,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,sBAAsB,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACnD,GAAG,IAAI,wBAAwB,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,wBAAwB,CAAC,MAAM,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,aAAiD,EACjD,UAGI,EAAE;IAEN,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,EAAE,CAAC;IAC9C,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,kBAAkB,CAAC;IAC9D,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,WAAW,EAAE,OAAO,IAAI,CAAC,EAAE,CAAC;QAC1D,MAAM,SAAS,GAAG,sBAAsB,CAAC,WAAW,CAAC,CAAC;QACtD,IAAI,CAAC,CAAC,MAAM,aAAa,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC;YACtC,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IACD,MAAM,IAAI,KAAK,CACb,mEAAmE,WAAW,WAAW,CAC1F,CAAC;AACJ,CAAC;AAED,SAAS,kBAAkB,CAAC,MAAc;IACxC,MAAM,SAAS,GACb,OAAO,UAAU,KAAK,WAAW;QAChC,UAAkC,CAAC,MAAM;QACxC,CAAC,CAAE,UAAkC,CAAC,MAAM;QAC5C,CAAC,CAAC,SAAS,CAAC;IAChB,IAAI,SAAS,EAAE,eAAe,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;QACnC,SAAS,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;QAC/B,OAAO,GAAG,CAAC;IACb,CAAC;IACD,0EAA0E;IAC1E,sEAAsE;IACtE,oEAAoE;IACpE,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;IACnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,wBAAwB;CACzB,CAAC"}

package/dist/venueLoyaltyRedemption.d.ts

@@ -1,21 +1,166 @@
 /**
- * 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;
 }
+/** 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 declare function getVenueLoyaltyRedemptionStatus(redemption: {
+    redeemedAt: string | null;
+    declinedAt: string | null;
+    expiredAt: string | null;
+}): VenueLoyaltyRedemptionStatus;
+/**
+ * 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;
 }
 //# sourceMappingURL=venueLoyaltyRedemption.d.ts.map