@tribe-nest/forge 3.14.0 → 3.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.14.0",
+  "version": "3.19.0",
   "publishConfig": {
     "access": "public"
   },

package/src/contexts/CartContext.tsx

@@ -29,7 +29,22 @@ export type CartItem = {
   quantity: number;
   recipientMessage?: string;
   payWhatYouWant: boolean;
+  /**
+   * WHICH version this line is — "Format: FLAC", "Size: L".
+   *
+   * The cart used to show a colour swatch and a size string, which is all a
+   * variant could be. Anything else was unnameable: a buyer who chose FLAC over
+   * MP3 saw two identical lines at two prices and no way to tell which was
+   * which, right at the moment they are deciding whether to pay.
+   *
+   * Optional because a product sold one way has no versions to distinguish, and
+   * because carts persist — a line saved before this existed still has to
+   * render.
+   */
+  options?: { axis: string; value: string; swatchHex?: string | null }[];
+  /** @deprecated Superseded by `options`. Still read for carts saved earlier. */
   color?: string;
+  /** @deprecated Superseded by `options`. Still read for carts saved earlier. */
   size?: string;
   /**
    * REQUIRED, and deliberately so.
@@ -67,7 +82,16 @@ export type TicketCartItem = {
   /** ticketId → quantity, matching `useEventCheckout`'s `selectedTickets`. */
   tickets: Record<string, number>;
   /** Display data per ticket id, so the cart can render lines without refetching. */
-  ticketMeta: Record<string, { title: string; price: number }>;
+  /**
+   * `price` is the per-unit figure the cart DISPLAYS — on a pay-what-you-want
+   * tier that is the buyer's chosen amount, not the tier's floor, so returning
+   * from an add-on page doesn't silently forget what they picked.
+   *
+   * `pwywAmount` is the same number carried explicitly, because the bundle
+   * endpoint treats a line's `price` as display-only and never charges it; the
+   * chosen amount has to arrive in a field the server actually reads.
+   */
+  ticketMeta: Record<string, { title: string; price: number; pwywAmount?: number }>;
 };
 
 interface CartContextType {

package/src/data/queries/useCheckouts.ts

@@ -25,7 +25,14 @@ export type CheckoutLineInput =
       eventId: string;
       ticketId: string;
       quantity: number;
+      /** Display only — the bundle never charges this. */
       price: number;
+      /**
+       * The buyer's chosen per-unit amount on a pay-what-you-want tier. Unlike
+       * `price`, this IS forwarded into the ticket order and charged (after the
+       * server clamps it against the tier's floor).
+       */
+      pwywAmount?: number;
       title: string;
       coverImage?: string;
     };
@@ -45,6 +52,13 @@ export function cartToCheckoutLines(cartItems: CartItem[], ticketItems: TicketCa
         ticketId,
         quantity: qty,
         price: t.ticketMeta[ticketId]?.price ?? 0,
+        // Sent SEPARATELY from `price` above, which the bundle treats as
+        // display-only and never charges. This is the field the server forwards
+        // into the ticket order — dropping it would charge the tier's floor and
+        // still return 200, so the buyer would be quietly undercharged.
+        ...(t.ticketMeta[ticketId]?.pwywAmount != null
+          ? { pwywAmount: t.ticketMeta[ticketId]?.pwywAmount }
+          : {}),
         title: t.ticketMeta[ticketId]?.title ?? t.eventTitle,
         coverImage: t.coverImage,
       })),

package/src/data/queries/useCoachingAvailability.ts

@@ -20,6 +20,13 @@ export function useCoachingAvailability(productId?: string, fromDate?: string, t
 
 export type ReserveCoachingBookingResult = {
   bookingId: string;
+  /**
+   * The per-booking credential, returned EXACTLY ONCE and never re-readable.
+   * Every later call on this booking (`booking/update`, `start-payment`,
+   * `finalize`) must present it. Persist it immediately — see
+   * `utils/bookingSecret`. Absent for bookings the backend grandfathered.
+   */
+  bookingSecret?: string;
   totalAmount?: number;
   /**
    * The cancellation terms SNAPSHOTTED onto this booking (S.6). Authoritative
@@ -45,6 +52,12 @@ export function useReserveCoachingBooking(productId?: string) {
 
 export type UpdateCoachingBookingInput = {
   bookingId: string | null;
+  /**
+   * The per-booking credential from `useReserveCoachingBooking`. Required by the
+   * backend for every call on a booking it minted one for — without it the call
+   * 404s (a 403 would confirm the id exists). See `utils/bookingSecret`.
+   */
+  bookingSecret?: string;
   email: string;
   firstName: string;
   lastName: string;

package/src/data/queries/useCourseAccess.ts

@@ -2,6 +2,75 @@ import type { CourseAccessData } from "../../types/models";
 import { useForge } from "../../provider/ForgeProvider";
 import { useMutation, useQuery } from "@tanstack/react-query";
 
+/**
+ * Why a course grant refused to open.
+ *
+ * `course_access.account_id` decides this PER ROW. A NULL binds to nobody — the
+ * emailed `/i/course-access/:accessId` link is the whole credential, and every
+ * one of those links must keep working, so a legacy grant still answers 200 to
+ * an anonymous caller. A grant with `account_id` set answers only to that
+ * account, and the API splits the refusal in two on purpose:
+ *
+ *   - **401 `account_required`** — nobody is signed in. Overwhelmingly the
+ *     LEGITIMATE owner following an old email on a new device. Needs a sign-in
+ *     that comes back to this page.
+ *   - **403 `wrong_account`** — signed in, but as somebody else. Telling this
+ *     person to "sign in" is a loop with no exit; they need to be told whose
+ *     enrolment it is and offered a way to switch.
+ *
+ * Collapsing the two into one "error" strands one of the two groups, which is
+ * exactly why the API bothers to distinguish them.
+ */
+export type CourseAccessDenialReason = "account_required" | "wrong_account";
+
+export type CourseAccessDenial = {
+  reason: CourseAccessDenialReason;
+  /** 401 for `account_required`, 403 for `wrong_account`. */
+  status: 401 | 403;
+  /** The API's own already-translated sentence, when it sent one. */
+  message: string | null;
+};
+
+/** Status off an axios-ish rejection, without importing axios or trusting its shape. */
+const errorStatus = (error: unknown): number | null => {
+  const status = (error as { response?: { status?: unknown } } | null | undefined)?.response?.status;
+  return typeof status === "number" ? status : null;
+};
+
+const errorMessage = (error: unknown): string | null => {
+  const message = (error as { response?: { data?: { message?: unknown } } } | null | undefined)?.response?.data
+    ?.message;
+  return typeof message === "string" && message.trim() ? message : null;
+};
+
+/**
+ * The account-binding refusal behind a failed course-access read, or `null` when
+ * the failure was something else (404 for a revoked/unknown grant, a 500, an
+ * offline browser).
+ *
+ * A total function over `unknown` so a caller cannot forget to narrow first, and
+ * the one place the status→meaning mapping is written down.
+ */
+export const courseAccessDenial = (error: unknown): CourseAccessDenial | null => {
+  const status = errorStatus(error);
+  if (status !== 401 && status !== 403) return null;
+  return {
+    reason: status === 401 ? "account_required" : "wrong_account",
+    status,
+    message: errorMessage(error),
+  };
+};
+
+/**
+ * Is this grant still open to anyone holding the link?
+ *
+ * `access.accountId === null` is the legacy shape. Worth surfacing on a
+ * SUCCESSFUL load too: the student can be nudged to put the course behind their
+ * account before the link is forwarded, screenshotted or indexed.
+ */
+export const isLegacyCourseAccess = (data?: CourseAccessData | null): boolean =>
+  !!data && (data.access.accountId ?? null) === null;
+
 /** A purchased course-access record (course content + progress) by access id. */
 export function useCourseAccess(accessId?: string) {
   const { client, profileId } = useForge();
@@ -15,6 +84,18 @@ export function useCourseAccess(accessId?: string) {
       return res.data;
     },
     enabled: !!client && !!accessId,
+    // Every failure here is an ANSWER, not a fault: 401 means "sign in", 403
+    // means "wrong account", 404 means the grant is revoked or unknown. Retrying
+    // three times (the react-query default) only makes the owner of an old email
+    // link watch a spinner before being shown the sign-in button that was always
+    // the outcome.
+    //
+    // Callers MUST NOT fire this until `usePublicAuth().isInitialized` — a
+    // request sent before the session is restored goes out anonymous, and a
+    // bound grant would 401 a reader who is in fact signed in, which is the one
+    // dead end this whole split exists to prevent. `useCourseClassroom` handles
+    // that gate; a hand-rolled caller has to do it too.
+    retry: false,
   });
 }
 

package/src/data/queries/useCourses.ts

@@ -12,6 +12,12 @@ export type CreateCourseBookingInput = {
 
 export type UpdateCourseBookingInput = {
   bookingId: string;
+  /**
+   * The per-booking credential from `useCreateCourseBooking`. Required by the
+   * backend for every call on a booking it minted one for — without it the call
+   * 404s (a 403 would confirm the id exists). See `utils/bookingSecret`.
+   */
+  bookingSecret?: string;
   email: string;
   firstName: string;
   lastName: string;
@@ -51,11 +57,23 @@ export function useUpdateCourseBooking(courseId?: string) {
   });
 }
 
+export type CreateCourseBookingResult = {
+  bookingId: string;
+  /**
+   * The per-booking credential, returned EXACTLY ONCE and never re-readable.
+   * Every later call on this booking (`booking/update`, `start-payment`,
+   * `finalize`) must present it. Persist it immediately — see
+   * `utils/bookingSecret`. Absent for bookings the backend grandfathered.
+   */
+  bookingSecret?: string;
+  isFree?: boolean;
+};
+
 /** Create a course booking (buyer details → bookingId; free courses skip payment). */
 export function useCreateCourseBooking(courseId?: string) {
   const { client, profileId } = useForge();
 
-  return useMutation<{ bookingId: string; isFree?: boolean }, unknown, CreateCourseBookingInput>({
+  return useMutation<CreateCourseBookingResult, unknown, CreateCourseBookingInput>({
     mutationFn: async (body) => {
       const res = await client.post(`/public/courses/${courseId}/bookings`, {
         courseId,

package/src/data/queries/useEvents.ts

@@ -43,6 +43,12 @@ export function useEvent(id?: string, options?: { initialData?: IEvent }) {
 
 export type CreateEventOrderInput = {
   items: Record<string, number>;
+  /**
+   * ticketId → the buyer's chosen amount, PER UNIT, on a pay-what-you-want
+   * tier. Ignored server-side for any tier that is not PWYW, and clamped up to
+   * the tier's own `price` — it can raise what is charged, never lower it.
+   */
+  amounts?: Record<string, number>;
   email: string;
   firstName?: string;
   lastName?: string;

package/src/data/queries/useFinalize.ts

@@ -59,8 +59,17 @@ export function useEventOrderFinalize(eventId?: string, orderId?: string) {
   });
 }
 
-/** Finalize a coaching booking (`/public/coaching/products/:productId/finalize`). */
-export function useCoachingBookingFinalize(productId?: string, orderId?: string) {
+/**
+ * Finalize a coaching booking (`/public/coaching/products/:productId/finalize`).
+ *
+ * `bookingSecret` is the per-booking credential minted at reserve — the id alone
+ * no longer resolves a booking that has one, and the call 404s without it. The
+ * confirmation page is reached via a provider redirect, so the caller reads it
+ * back out of `utils/bookingSecret` rather than off in-memory state. Optional
+ * because bookings created before the secret existed have no stored hash and
+ * still finalize on the id.
+ */
+export function useCoachingBookingFinalize(productId?: string, orderId?: string, bookingSecret?: string) {
   const { client, profileId } = useForge();
 
   return useQuery<CoachingBooking>({
@@ -69,6 +78,7 @@ export function useCoachingBookingFinalize(productId?: string, orderId?: string)
       const res = await client.post(`/public/coaching/products/${productId}/finalize`, {
         profileId,
         orderId,
+        bookingSecret,
       });
       return res.data;
     },
@@ -91,8 +101,17 @@ export function useDonationFinalize() {
   });
 }
 
-/** Finalize a course booking (`/public/courses/:courseId/finalize`). */
-export function useCourseBookingFinalize(courseId?: string, bookingId?: string) {
+/**
+ * Finalize a course booking (`/public/courses/:courseId/finalize`).
+ *
+ * `bookingSecret` is the per-booking credential minted at create — the id alone
+ * no longer resolves a booking that has one, and the call 404s without it. The
+ * confirmation page is reached via a provider redirect, so the caller reads it
+ * back out of `utils/bookingSecret` rather than off in-memory state. Optional
+ * because bookings created before the secret existed have no stored hash and
+ * still finalize on the id.
+ */
+export function useCourseBookingFinalize(courseId?: string, bookingId?: string, bookingSecret?: string) {
   const { client, profileId } = useForge();
 
   return useQuery<CourseBooking>({
@@ -101,6 +120,7 @@ export function useCourseBookingFinalize(courseId?: string, bookingId?: string)
       const res = await client.post(`/public/courses/${courseId}/finalize`, {
         profileId,
         bookingId,
+        bookingSecret,
       });
       return res.data;
     },

package/src/index.ts

@@ -30,6 +30,9 @@ export { CartProvider, useCart } from "./contexts/CartContext";
 // way the cart and audio player are — so a code site and a Craft site cannot
 // disagree about which version a buyer picked.
 export { useVariantSelection } from "./ui/headless/useVariantSelection";
+// Which version a cart line is. Exported from the package root because the
+// Craft themes render their own cart and must resolve it the same way.
+export { resolveCartLineOptions } from "./ui/styled/CartLineOptions";
 export type { VariantAxis, VariantAxisValue } from "./ui/headless/useVariantSelection";
 export type { CartItem, TicketCartItem, AttachedTo } from "./contexts/CartContext";
 export {
@@ -124,6 +127,10 @@ export * from "./utils/landing";
 export * from "./utils/metaPixel";
 export * from "./utils/cookieConsent";
 export * from "./utils/structuredData";
+// The per-booking checkout credential + where it is kept across the payment
+// redirect. Exported so a host that drives the booking endpoints itself can
+// hold the secret the same way the built-in flows do.
+export * from "./utils/bookingSecret";
 // Shared by BOTH starters. Kept here rather than in a starter's `/i/-lib` so an
 // app can use them without inheriting the fan-site route tree, and so a fix
 // reaches existing sites through the normal Forge publish.

package/src/types/models.ts

@@ -582,6 +582,15 @@ export type IMedia = {
   type: MediaType;
   previewUrl?: string | null;
   previewStatus?: string | null;
+  /**
+   * Which version this file is for, when it is a song's file.
+   *
+   * Null — and absent everywhere else — means every version gets it. Present so
+   * an EDITOR can round-trip a per-version file; a storefront never needs it,
+   * because the server has already filtered the list to the version being
+   * viewed.
+   */
+  productOptionValueId?: string | null;
 };
 
 /**
@@ -1097,11 +1106,22 @@ export type ITicket = {
   id: string;
   title: string;
   description: string;
+  /**
+   * On a pay-what-you-want tier this is the MINIMUM, not a fixed price — there
+   * is no separate minimum field. Every "from $X" on the storefront reads it,
+   * which is exactly why it stays the floor.
+   */
   price: number;
   // Optional display-only "compare-at" price (higher than `price`). When
   // present the storefront strikes it through next to `price`. Charging uses
-  // `price`.
+  // `price`. Mutually exclusive with `payWhatYouWant` — the API refuses both.
   compareAtPrice?: number | string | null;
+  /** Buyer chooses the amount, at or above `price`. */
+  payWhatYouWant?: boolean;
+  /** Pre-fills the buyer's amount box. Presentation only — never a floor. */
+  pwywSuggestedAmount?: number | string | null;
+  /** Enforced server-side at checkout. */
+  payWhatYouWantMaximum?: number | string | null;
   quantity: number;
   order: number;
   sold: number;
@@ -1268,7 +1288,20 @@ export type IPublicOrderItem = {
   quantity: number;
   recipientMessage?: string;
   payWhatYouWant: boolean;
+  /**
+   * What this line WAS, recorded when it was sold.
+   *
+   * Not resolved through `productVariantId` on read: the creator can rename an
+   * option value or delete the version, and an order that re-resolves would
+   * quietly start describing itself differently from how it was bought.
+   *
+   * Null for a product sold one way, and for every order placed before the
+   * snapshot existed — those fall back to `size` below.
+   */
+  variantOptions?: { axis: string; value: string; swatchHex?: string | null }[] | null;
+  /** @deprecated Superseded by `variantOptions`. The only record for older orders. */
   color: string;
+  /** @deprecated Superseded by `variantOptions`. The only record for older orders. */
   size: string;
 };
 
@@ -1415,6 +1448,13 @@ export type CourseAccessRecord = {
   firstName: string | null;
   lastName: string | null;
   currentLessonId: string | null;
+  /**
+   * The account this grant is bound to, or `null` for a LEGACY grant that any
+   * holder of the access id can open. Optional on the type because sites built
+   * against an older API still get payloads without the field — treat a missing
+   * value as legacy (see `isLegacyCourseAccess`).
+   */
+  accountId?: string | null;
 };
 
 export type CourseLessonProgress = {

package/src/ui/format/_tests/pwyw.spec.ts

@@ -0,0 +1,157 @@
+import { describe, it, expect } from "vitest";
+import type { ITicket } from "../../../types/models";
+import {
+  clampChosenAmount,
+  isPayWhatYouWant,
+  pwywDefaultAmount,
+  pwywMaximum,
+  resolveUnitPrice,
+  ticketSubtotals,
+} from "../pwyw";
+
+/**
+ * The pay-what-you-want arithmetic shared by BOTH storefront stacks (Forge and
+ * the legacy client). It is shared rather than written twice precisely so the
+ * two cannot drift from each other or from the server — these tests pin the
+ * behaviour they both depend on.
+ *
+ * The clamp here is UX, not enforcement: the server clamps again and is what
+ * decides the charge. What matters is that the number on screen matches the
+ * number that will be charged.
+ */
+
+const tier = (over: Partial<ITicket> = {}): ITicket => ({
+  id: over.id ?? "t1",
+  title: "GA",
+  description: "",
+  price: 20,
+  quantity: 100,
+  order: 0,
+  sold: 0,
+  maxPerPerson: 10,
+  ...over,
+});
+
+describe("pwyw helpers", () => {
+  describe("isPayWhatYouWant", () => {
+    it("is false when the flag is absent — every pre-feature tier", () => {
+      expect(isPayWhatYouWant(tier())).toBe(false);
+    });
+
+    it("is true only when explicitly set", () => {
+      expect(isPayWhatYouWant(tier({ payWhatYouWant: true }))).toBe(true);
+    });
+  });
+
+  describe("pwywMaximum", () => {
+    it("is null on a non-PWYW tier even if a maximum is stored", () => {
+      // A stale ceiling on a tier whose toggle was turned off must not start
+      // constraining a fixed price.
+      expect(pwywMaximum(tier({ payWhatYouWantMaximum: 50 }))).toBeNull();
+    });
+
+    it("parses a numeric string, as the API returns for decimals", () => {
+      expect(pwywMaximum(tier({ payWhatYouWant: true, payWhatYouWantMaximum: "50.00" }))).toBe(50);
+    });
+
+    it("is null for an unparseable value rather than NaN", () => {
+      expect(pwywMaximum(tier({ payWhatYouWant: true, payWhatYouWantMaximum: "nonsense" }))).toBeNull();
+    });
+  });
+
+  describe("pwywDefaultAmount", () => {
+    it("falls back to the floor with no suggestion", () => {
+      expect(pwywDefaultAmount(tier({ payWhatYouWant: true }))).toBe(20);
+    });
+
+    it("uses the operator's suggestion", () => {
+      expect(pwywDefaultAmount(tier({ payWhatYouWant: true, pwywSuggestedAmount: 35 }))).toBe(35);
+    });
+
+    it("never pre-fills below the floor", () => {
+      // Otherwise the form opens with a value its own validation rejects.
+      expect(pwywDefaultAmount(tier({ payWhatYouWant: true, pwywSuggestedAmount: 5 }))).toBe(20);
+    });
+
+    it("never pre-fills above the maximum", () => {
+      expect(
+        pwywDefaultAmount(tier({ payWhatYouWant: true, pwywSuggestedAmount: 80, payWhatYouWantMaximum: 50 })),
+      ).toBe(50);
+    });
+  });
+
+  describe("clampChosenAmount", () => {
+    const t = tier({ payWhatYouWant: true });
+
+    it("keeps a figure above the floor", () => {
+      expect(clampChosenAmount(t, 75)).toBe(75);
+    });
+
+    it("raises a figure below the floor — the one-directional property", () => {
+      expect(clampChosenAmount(t, 1)).toBe(20);
+    });
+
+    it.each([
+      ["null", null],
+      ["undefined", undefined],
+      ["NaN", NaN],
+      ["negative", -50],
+      ["zero", 0],
+    ])("falls back to the floor for %s", (_label, value) => {
+      expect(clampChosenAmount(t, value as number | null | undefined)).toBe(20);
+    });
+
+    it("caps at the maximum", () => {
+      expect(clampChosenAmount(tier({ payWhatYouWant: true, payWhatYouWantMaximum: 50 }), 5000)).toBe(50);
+    });
+  });
+
+  describe("resolveUnitPrice", () => {
+    it("ignores a chosen amount on a non-PWYW tier, matching the server", () => {
+      expect(resolveUnitPrice(tier(), 500)).toBe(20);
+      expect(resolveUnitPrice(tier(), 1)).toBe(20);
+    });
+
+    it("honours a chosen amount on a PWYW tier", () => {
+      expect(resolveUnitPrice(tier({ payWhatYouWant: true }), 75)).toBe(75);
+    });
+  });
+
+  describe("ticketSubtotals", () => {
+    it("returns identical paid and floor figures with no PWYW tier", () => {
+      // The property that makes every existing surface's numbers unchanged.
+      const result = ticketSubtotals({
+        tickets: [tier({ id: "a", price: 20 }), tier({ id: "b", price: 30 })],
+        quantities: { a: 2, b: 1 },
+      });
+      expect(result).toEqual({ paid: 70, floor: 70 });
+    });
+
+    it("separates what is paid from what the fee is computed on", () => {
+      const result = ticketSubtotals({
+        tickets: [tier({ id: "a", price: 20, payWhatYouWant: true })],
+        quantities: { a: 2 },
+        amounts: { a: 75 },
+      });
+      expect(result).toEqual({ paid: 150, floor: 40 });
+    });
+
+    it("mixes PWYW and fixed tiers correctly", () => {
+      const result = ticketSubtotals({
+        tickets: [tier({ id: "a", price: 10, payWhatYouWant: true }), tier({ id: "b", price: 40 })],
+        quantities: { a: 2, b: 1 },
+        amounts: { a: 35 },
+      });
+      expect(result).toEqual({ paid: 110, floor: 60 });
+    });
+
+    it("ignores tiers with no quantity selected", () => {
+      const result = ticketSubtotals({
+        tickets: [tier({ id: "a", price: 20, payWhatYouWant: true })],
+        quantities: {},
+        amounts: { a: 500 },
+      });
+      expect(result).toEqual({ paid: 0, floor: 0 });
+    });
+  });
+});

package/src/ui/format/pwyw.ts

@@ -0,0 +1,95 @@
+import type { ITicket } from "../../types/models";
+
+/**
+ * Pay-what-you-want, as a buyer-facing surface has to handle it.
+ *
+ * ## The floor is the ticket, everything above it is a tip
+ *
+ * On a PWYW tier `ticket.price` IS the minimum — there is no separate minimum
+ * field — so every existing "from $X" already reads the right number. What
+ * changes is that the buyer may choose to pay MORE, and two totals then exist
+ * at once:
+ *
+ *  - the **paid** subtotal, which is what the card is charged, and
+ *  - the **floor** subtotal, which is what discounts and the artist's booking
+ *    fee are calculated on.
+ *
+ * The server computes both the same way (`PublicEventsService.createOrder`).
+ * These helpers exist so a storefront cannot accidentally show a fee estimate
+ * derived from the paid figure and then be charged one derived from the floor.
+ *
+ * ## The client is not the guard
+ *
+ * `clampChosenAmount` is UX, not enforcement. The server reads the PWYW flag
+ * off the ticket row and refuses anything below `price` regardless of what a
+ * client sends — a buyer cannot pay less than the floor by editing anything
+ * here. The clamp exists so the number on screen is the number that will be
+ * charged, not to make the request safe.
+ */
+
+const toNumber = (value: number | string | null | undefined): number | null => {
+  if (value == null) return null;
+  const parsed = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+};
+
+export const isPayWhatYouWant = (ticket: ITicket): boolean => !!ticket.payWhatYouWant;
+
+/** The tier's ceiling, or `null` for no limit. */
+export const pwywMaximum = (ticket: ITicket): number | null =>
+  isPayWhatYouWant(ticket) ? toNumber(ticket.payWhatYouWantMaximum) : null;
+
+/**
+ * What the amount box should start at: the operator's suggestion when there is
+ * one, else the floor. Never below the floor — a suggestion under the minimum
+ * would pre-fill the form with a value the buyer is not allowed to pay.
+ */
+export const pwywDefaultAmount = (ticket: ITicket): number => {
+  const floor = ticket.price;
+  const suggested = toNumber(ticket.pwywSuggestedAmount);
+  if (suggested == null || suggested < floor) return floor;
+  const maximum = pwywMaximum(ticket);
+  return maximum != null ? Math.min(suggested, maximum) : suggested;
+};
+
+/** Pin a buyer-entered figure into [floor, maximum]. Mirrors the server clamp. */
+export const clampChosenAmount = (ticket: ITicket, chosen: number | null | undefined): number => {
+  const floor = ticket.price;
+  if (chosen == null || !Number.isFinite(chosen) || chosen < floor) return floor;
+  const maximum = pwywMaximum(ticket);
+  return maximum != null ? Math.min(chosen, maximum) : chosen;
+};
+
+/**
+ * The per-unit price this tier will actually be charged at.
+ *
+ * A non-PWYW tier ignores `chosen` entirely, exactly as the server does — so a
+ * stale amount left in state after the operator turns PWYW off cannot change
+ * what is shown.
+ */
+export const resolveUnitPrice = (ticket: ITicket, chosen: number | null | undefined): number =>
+  isPayWhatYouWant(ticket) ? clampChosenAmount(ticket, chosen) : ticket.price;
+
+/**
+ * Both subtotals for a selection, in one pass.
+ *
+ * `paid` is what the buyer owes for the tickets; `floor` is the base the
+ * booking-fee estimate and any percentage discount must be computed against.
+ * They are equal on any cart with no PWYW tier, which is why every existing
+ * surface keeps its current numbers untouched.
+ */
+export function ticketSubtotals(input: {
+  tickets: ITicket[];
+  quantities: Record<string, number>;
+  amounts?: Record<string, number>;
+}): { paid: number; floor: number } {
+  let paid = 0;
+  let floor = 0;
+  for (const ticket of input.tickets) {
+    const quantity = input.quantities[ticket.id] ?? 0;
+    if (quantity <= 0) continue;
+    paid += resolveUnitPrice(ticket, input.amounts?.[ticket.id]) * quantity;
+    floor += ticket.price * quantity;
+  }
+  return { paid, floor };
+}