@tribe-nest/forge 3.11.0 → 3.17.0

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.11.0",
+  "version": "3.17.0",
   "publishConfig": {
     "access": "public"
   },
-  "description": "Forge — the headless React SDK for building custom TribeNest creator sites (the Hydrogen of TribeNest). Exposes the backend (memberships, commerce, gated content, ticketing, courses, booking, auth) as data + behavior primitives.",
+  "description": "Forge \u2014 the headless React SDK for building custom TribeNest creator sites (the Hydrogen of TribeNest). Exposes the backend (memberships, commerce, gated content, ticketing, courses, booking, auth) as data + behavior primitives.",
   "exports": {
     ".": "./src/index.ts",
     "./ui": "./src/ui/index.ts",

package/src/contexts/CartContext.tsx

@@ -29,9 +29,36 @@ 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;
-  deliveryType?: ProductDeliveryType;
+  /**
+   * REQUIRED, and deliberately so.
+   *
+   * Checkout decides whether to ask for a shipping address from this field on
+   * the cart LINE. While it was optional, a caller that forgot it produced an
+   * item that silently read as non-physical — the Craft music page did exactly
+   * that, and a vinyl reached checkout with the buyer never asked where to send
+   * the record. A missing address is not recoverable after payment.
+   *
+   * Making it required turns that into a compile error instead of a defect
+   * nobody sees until an order arrives with nowhere to ship it.
+   */
+  deliveryType: ProductDeliveryType;
   /** Set automatically from `?addonFor=` — see `addToCart`. */
   attachedTo?: AttachedTo;
 };
@@ -55,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/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/useProducts.ts

@@ -1,23 +1,39 @@
-import type { IPublicProduct, PaginatedData, ProductCategory } from "../../types/models";
+import type { IPublicProduct, PaginatedData, ProductType } from "../../types/models";
 import { useForge } from "../../provider/ForgeProvider";
 import { useQuery } from "@tanstack/react-query";
 
 export interface GetProductsParams {
   query?: string;
-  category?: ProductCategory[];
+  /** What the products ARE. Renamed from `category` in the taxonomy split. */
+  productType?: ProductType[];
+  /**
+   * @deprecated The old name for `productType`. Still honoured, and honoured
+   * deliberately: callers usually build this object in a `useMemo` and pass it
+   * as a VARIABLE, which turns off TypeScript's excess-property check — so a
+   * caller left on the old name compiles clean and silently loses its filter,
+   * listing the whole catalogue on a page meant to show one type. Dropping the
+   * key would make that failure mode look like working code.
+   */
+  category?: ProductType[];
+  /**
+   * A creator-authored category. Descendant-inclusive: filtering on "Apparel"
+   * returns everything filed beneath it, at any depth.
+   */
+  categoryId?: string;
+  collectionId?: string;
   page?: number;
   releaseType?: string;
 }
 
-/** Featured products for the profile, optionally filtered by category. */
-export function useFeaturedProducts(category?: ProductCategory) {
+/** Featured products for the profile, optionally filtered by product type. */
+export function useFeaturedProducts(productType?: ProductType) {
   const { client, profileId } = useForge();
 
   return useQuery<IPublicProduct[]>({
-    queryKey: ["featured-products", profileId, category],
+    queryKey: ["featured-products", profileId, productType],
     queryFn: async () => {
       const res = await client.get("/public/products/featured", {
-        params: { profileId, category },
+        params: { profileId, productType },
       });
       return res.data;
     },
@@ -34,7 +50,9 @@ export function useGetProducts(params?: GetProductsParams, enabled = true) {
       const res = await client.get("/public/products", {
         params: {
           profileId: profileId,
-          category: params?.category,
+          productType: params?.productType ?? params?.category,
+          categoryId: params?.categoryId,
+          collectionId: params?.collectionId,
           page: params?.page || 1,
           limit: 10,
           filter: {
@@ -90,11 +108,21 @@ export function useGetProductsByIds(productIds: string[]) {
   });
 }
 
-export function useGetProductCategories() {
+/**
+ * The product TYPES this creator has products in, plus a synthetic "Coaching"
+ * entry when they sell coaching. This is what the storefront's top-level tabs
+ * are built from.
+ *
+ * The endpoint keeps its `/categories` path: every code-site published before
+ * the taxonomy split calls it and reads this exact payload, and the hook name
+ * is what changed. For the creator's OWN categories use
+ * {@link useProductCategories}.
+ */
+export function useGetProductTypes() {
   const { client, profileId } = useForge();
 
-  return useQuery<{ title: ProductCategory; description: string }[]>({
-    queryKey: ["product-categories", profileId],
+  return useQuery<{ title: string; description: string }[]>({
+    queryKey: ["product-types", profileId],
     queryFn: async () => {
       const res = await client.get("/public/products/categories", {
         params: {
@@ -106,3 +134,69 @@ export function useGetProductCategories() {
     enabled: !!profileId && !!client,
   });
 }
+
+/**
+ * @deprecated Renamed to {@link useGetProductTypes}, which is what it always
+ * returned. Kept so a site built against an earlier Forge keeps compiling; it
+ * will go in a future major.
+ */
+export const useGetProductCategories = useGetProductTypes;
+
+/** A node in the creator's category tree. Children are nested, never repeated at the root. */
+export interface IPublicProductCategory {
+  id: string;
+  title: string;
+  slug: string;
+  description: string | null;
+  parentId: string | null;
+  position: number;
+  productCount: number;
+  children: IPublicProductCategory[];
+}
+
+export interface IPublicProductCollection {
+  id: string;
+  title: string;
+  slug: string;
+  description: string | null;
+  isFeatured: boolean;
+  position: number;
+  productCount: number;
+}
+
+/**
+ * The creator's OWN category tree — what they organise their store by, as
+ * opposed to {@link useGetProductTypes} which is what their products ARE.
+ *
+ * Counts are descendant-inclusive, so "Apparel" reports everything beneath it.
+ */
+export function useProductCategories() {
+  const { client, profileId } = useForge();
+
+  return useQuery<IPublicProductCategory[]>({
+    queryKey: ["public-product-categories", profileId],
+    queryFn: async () => {
+      const res = await client.get("/public/products/product-categories", {
+        params: { profileId },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client,
+  });
+}
+
+/** The creator's curated collections — drops, seasons, hand-picked edits. */
+export function useProductCollections() {
+  const { client, profileId } = useForge();
+
+  return useQuery<IPublicProductCollection[]>({
+    queryKey: ["public-product-collections", profileId],
+    queryFn: async () => {
+      const res = await client.get("/public/products/product-collections", {
+        params: { profileId },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client,
+  });
+}

package/src/index.ts

@@ -26,6 +26,14 @@ export * from "./types";
 export { AudioPlayerProvider, useAudioPlayer } from "./contexts/AudioPlayerContext";
 export type { AudioTrack } from "./contexts/AudioPlayerContext";
 export { CartProvider, useCart } from "./contexts/CartContext";
+// Variant selection, shared with the Craft themes in frontend-shared the same
+// 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 {
   ACCESS_TOKEN_KEY,

package/src/types/models.ts

@@ -582,17 +582,46 @@ 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;
 };
 
-export enum ProductCategory {
+/**
+ * What a product IS, which decides how it renders: Music shows a track list,
+ * Merch shows variants, Digital is a download, Service is fulfilled by the
+ * creator.
+ *
+ * Renamed from `ProductType` in the taxonomy split. It used to be the only
+ * taxonomy a product had, pointing into a four-row table shared by every artist
+ * on the platform — so no creator could organise their own store. Creator
+ * authored categories and collections are separate now (`categories`,
+ * `collections` on {@link IPublicProduct}).
+ *
+ * Coaching and Course are gone: they are separate surfaces with their own
+ * tables and never appeared in `products`. The storefront still shows a
+ * Coaching tab — see {@link STOREFRONT_COACHING_TAB}.
+ */
+export enum ProductType {
   Music = "Music",
   Merch = "Merch",
   Digital = "Digital",
   Service = "Service",
-  Coaching = "Coaching",
-  Course = "Course",
 }
 
+/**
+ * The storefront's product-type navigation is not purely {@link ProductType}: a
+ * creator with coaching products gets a "Coaching" tab alongside them, though
+ * no product row is ever of that type.
+ */
+export const STOREFRONT_COACHING_TAB = "Coaching" as const;
+
 export type PostType = "image" | "video" | "audio" | "poll";
 
 export type IPublicComment = {
@@ -658,11 +687,36 @@ export type IPublicProductVariant = {
   payWhatYouWant?: boolean;
   payWhatYouWantMaximum?: number;
   upcCode: string;
+  /**
+   * Where this variant sits on its product's axes, in the axes' own order.
+   *
+   * This is what the picker reads. `color` and `size` below are the two
+   * hardcoded axes that predate the option library — they cannot express a
+   * third ("Format: MP3 / WAV / Stems"), and one product's `color` may hold a
+   * hex while another's holds a name, because three different writers filled
+   * it. Prefer `options`.
+   */
+  options: IPublicVariantOption[];
+  /** @deprecated Read `options`. */
   color: string;
+  /** @deprecated Read `options`. */
   size: string;
+  /** Whether a buyer of this version also receives the downloadable files. */
+  includesDownload?: boolean;
   availabilityStatus: "active" | "temporarily_out_of_stock";
 };
 
+export type IPublicVariantOption = {
+  optionValueId: string;
+  optionTypeId: string;
+  /** "Colour", "Size", "Format" — as the creator named it. */
+  axis: string;
+  value: string;
+  /** Set only when the value genuinely is a colour; a guessed hex would lie. */
+  swatchHex: string | null;
+  displayType: string;
+};
+
 // ---- Reviews -------------------------------------------------------------------
 
 /** Reviewable entity types (v1 — events deferred). */
@@ -750,8 +804,12 @@ export type IPublicProduct = {
   slug?: string;
   title: string;
   description: string;
-  category: ProductCategory;
+  productType: ProductType;
   media: IMedia[];
+  /** Creator-authored categories this product is filed under. Direct only — a parent category resolves its descendants server-side. */
+  categories?: { id: string; title: string; slug: string; parentId: string | null }[];
+  /** Curated collections this product belongs to, with its position in each. */
+  collections?: { id: string; title: string; slug: string; isFeatured: boolean; position: number }[];
   variants: IPublicProductVariant[];
   artist: string;
   credits: string;
@@ -1048,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;
@@ -1219,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;
 };
 

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 };
+}