@tribe-nest/forge 3.9.0 → 3.11.0

package/package.json

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

package/src/data/queries/useCoachingAvailability.ts

@@ -1,4 +1,4 @@
-import type { BookingSlot, PillarDiscountQuote } from "../../types/models";
+import type { BookingSlot, CancellationTermsView, PillarDiscountQuote } from "../../types/models";
 import { useForge } from "../../provider/ForgeProvider";
 import { useMutation, useQuery } from "@tanstack/react-query";
 
@@ -18,11 +18,22 @@ export function useCoachingAvailability(productId?: string, fromDate?: string, t
   });
 }
 
-/** Reserve a coaching booking slot. Returns the created booking id. */
+export type ReserveCoachingBookingResult = {
+  bookingId: string;
+  totalAmount?: number;
+  /**
+   * The cancellation terms SNAPSHOTTED onto this booking (S.6). Authoritative
+   * from here on — the product's live policy may be edited while the hour is
+   * held, and the buyer's rights are governed by this copy, not by that read.
+   */
+  cancellation?: CancellationTermsView | null;
+};
+
+/** Reserve a coaching booking slot. Returns the created booking + its agreed terms. */
 export function useReserveCoachingBooking(productId?: string) {
   const { client } = useForge();
 
-  return useMutation<{ bookingId: string }, unknown, { slotId: string }>({
+  return useMutation<ReserveCoachingBookingResult, unknown, { slotId: string }>({
     mutationFn: async ({ slotId }) => {
       const res = await client.post(`/public/coaching/products/${productId}/booking/reserve`, {
         slotId,

package/src/data/queries/useEventSeries.ts

@@ -0,0 +1,42 @@
+import type { IEventSeries } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+import { useQuery } from "@tanstack/react-query";
+
+/**
+ * A named, multi-date event series by slug (or id).
+ *
+ * ## There is deliberately no `useEventSeriesList`
+ *
+ * Every event belongs to a series, so a list endpoint would be a list of every
+ * event on the site wearing a different hat — and the ones the API refuses to
+ * publish (unnamed containers, single-date shows) would show up as holes in it.
+ * A series is a DESTINATION the operator shares, not a browsable index; the
+ * events list is already the browsable index.
+ *
+ * ## A 404 is the normal answer
+ *
+ * The API refuses any series that nobody named or that holds fewer than two
+ * publicly-visible dates. That is not an error state to surface as "something
+ * went wrong" — it means there is no such page — so a renderer should treat
+ * `isError` here the same way it treats a missing event.
+ *
+ * Pass `initialData` (a series fetched server-side in a route loader) to seed
+ * the query, so the page server-renders for SEO with no client spinner.
+ */
+export function useEventSeries(slugOrId?: string, options?: { initialData?: IEventSeries }) {
+  const { client, profileId } = useForge();
+
+  return useQuery<IEventSeries>({
+    queryKey: ["event-series", slugOrId, profileId],
+    queryFn: async () => {
+      const res = await client.get(`/public/event-series/${encodeURIComponent(slugOrId!)}`, {
+        params: { profileId },
+      });
+      return res.data;
+    },
+    enabled: !!slugOrId && !!profileId && !!client,
+    initialData: options?.initialData,
+    // A 404 here means "no such page", which no amount of retrying changes.
+    retry: false,
+  });
+}

package/src/data/queries/useEvents.ts

@@ -59,12 +59,21 @@ export type CreateEventOrderInput = {
 export type CreateEventOrderResult = {
   orderId: string;
   isFreeCheckout?: boolean;
-  /** NET of any discount. */
+  /** NET of any discount, and INCLUSIVE of the booking fee below. */
   totalAmount?: number;
   // Additive (S.3) — present on every response, discounted or not.
   /** GROSS, before any discount. */
   subTotal?: number;
   discountAmount?: number;
+  /**
+   * The artist's booking fee this order was ACTUALLY charged, in major units —
+   * the server's own snapshot, not a re-derivation.
+   *
+   * It is what closes the arithmetic: `subTotal - discountAmount + feeAmount`
+   * is `totalAmount`. Before it existed the three fields did not reconcile and
+   * no line on any checkout explained the gap.
+   */
+  feeAmount?: number;
   couponId?: string | null;
   /** Every discount that applied, entered OR automatic. */
   appliedCoupons?: AppliedDiscountCoupon[];

package/src/data/queries/useSubscriptions.ts

@@ -1,5 +1,12 @@
 import { useForge } from "../../provider/ForgeProvider";
 import { useMutation } from "@tanstack/react-query";
+import { usePublicAuth } from "../../contexts/PublicAuthContext";
+import {
+  getMembershipAccess,
+  getMembershipStatusMessage,
+  type MembershipAccessSummary,
+  type MembershipStatusMessage,
+} from "../../utils/membershipAccess";
 
 export type CreateSubscriptionInput = {
   amount?: number;
@@ -48,6 +55,52 @@ export function useCancelMembership() {
   });
 }
 
+/**
+ * The signed-in member's access + billing message, in one call.
+ *
+ * Every membership-aware surface should use this instead of reading
+ * `user.membership.status`. `access` answers "can they see it", `message`
+ * answers "what do we tell them" — two different questions, and conflating
+ * them is what locked past_due members out while calling them "Cancelled".
+ */
+export function useMembershipAccess(): {
+  access: MembershipAccessSummary;
+  message: MembershipStatusMessage;
+} {
+  const { user } = usePublicAuth();
+  const access = getMembershipAccess(user?.membership);
+  return { access, message: getMembershipStatusMessage(access) };
+}
+
+/**
+ * Open the payment provider's billing-management page for the signed-in member.
+ *
+ * This is the other half of keeping access through `past_due`: the grace window
+ * is only a recovery window if the member can actually fix their card inside
+ * it. Nothing about the caller is sent — the server derives the provider
+ * customer from the session, because a customer id in a request body is a
+ * cross-tenant leak waiting to happen.
+ *
+ * `returnUrl` defaults to the current page so the member lands back where they
+ * were. The returned `url` is a one-time link — redirect, never render it.
+ */
+export function useOpenBillingPortal() {
+  const { client, profileId } = useForge();
+
+  return useMutation<{ url: string; provider: string }, unknown, { returnUrl?: string } | void>({
+    mutationFn: async (input) => {
+      const returnUrl =
+        (input && "returnUrl" in input ? input.returnUrl : undefined) ??
+        (typeof window !== "undefined" ? window.location.href : undefined);
+      const res = await client.post("/public/payments/subscriptions/billing-portal", {
+        profileId,
+        ...(returnUrl ? { returnUrl } : {}),
+      });
+      return res.data;
+    },
+  });
+}
+
 /**
  * Reconcile the most recent subscription after a checkout return.
  * Returns the latest subscription status (e.g. "active").

package/src/index.ts

@@ -69,6 +69,7 @@ export * from "./data/queries/useBlog";
 export * from "./data/queries/usePodcast";
 export * from "./data/queries/useCollections";
 export * from "./data/queries/useEvents";
+export * from "./data/queries/useEventSeries";
 export * from "./data/queries/useInvoice";
 export * from "./data/queries/usePaymentLink";
 export * from "./data/queries/useLeadMagnet";
@@ -123,3 +124,6 @@ export * from "./utils/structuredData";
 // reaches existing sites through the normal Forge publish.
 export * from "./utils/headMeta";
 export * from "./utils/formatDateTime";
+// The ONE membership access predicate + the messaging that is deliberately
+// separate from it. Every surface that gates on a membership imports from here.
+export * from "./utils/membershipAccess";

package/src/server/index.ts

@@ -33,6 +33,7 @@ import type { ApiProbeResult, ForgeSsrDiagnostics, SsrFetchFailure } from "../ty
 export type { ApiProbeResult, ForgeSsrDiagnostics, SsrFetchFailure };
 import type {
   IEvent,
+  IEventSeries,
   IPublicProduct,
   PublicCourse,
   CoachingProduct,
@@ -221,6 +222,25 @@ export function fetchEventServer(opts: { apiUrl: string; profileId?: string; idO
   });
 }
 
+/**
+ * Fetch a NAMED, multi-date event series by slug (or id) for SSR.
+ *
+ * Resolves to `null` for a series that does not exist, is not this profile's,
+ * was never named by a human, or holds fewer than two publicly-visible dates —
+ * the API answers 404 to all four identically, on purpose, so that a caller
+ * cannot tell them apart and turn the endpoint into an oracle. A `null` here
+ * means "render the not-found page", not "the fetch failed".
+ */
+export function fetchEventSeriesServer(opts: {
+  apiUrl: string;
+  profileId?: string;
+  idOrSlug: string;
+}): Promise<IEventSeries | null> {
+  return getJson<IEventSeries>(opts.apiUrl, `/public/event-series/${encodeURIComponent(opts.idOrSlug)}`, {
+    profileId: opts.profileId,
+  });
+}
+
 /** Fetch a single product by id or slug for SSR. */
 export function fetchProductServer(opts: {
   apiUrl: string;

package/src/types/models.ts

@@ -238,13 +238,38 @@ export type MembershipTier = {
   cancellationMessageContent?: string | null;
 };
 
+/**
+ * The server's access + billing decision, shipped with every membership.
+ *
+ * Read this through `getMembershipAccess()` rather than destructuring it — the
+ * helper handles a server that predates the block, and is the single place any
+ * surface is allowed to answer "does this grant access".
+ */
+export interface MembershipAccess {
+  hasAccess: boolean;
+  billingState: "active" | "ending" | "past_due" | "grace" | "pending" | "ended";
+  paymentFailed: boolean;
+  graceUntil: string | null;
+  pastDueAt: string | null;
+  cancelAtPeriodEnd: boolean;
+}
+
 export interface Membership {
   id: string;
   membershipTierId: string;
   profilePaymentSubscriptionId?: string;
   paymentProviderSubscriptionId?: string;
   endDate: string;
+  /**
+   * Raw lifecycle status. **Do not compare this to `"active"` to decide access
+   * or to label the membership** — `past_due` and `grace` still grant access.
+   * Use `getMembershipAccess(membership)` / `getMembershipStatusMessage()`.
+   */
   status: string;
+  access?: MembershipAccess;
+  cancelAtPeriodEnd?: boolean;
+  graceUntil?: string | null;
+  pastDueAt?: string | null;
   membershipTier: MembershipTier;
   startDate: string;
   subscriptionAmount: number;
@@ -752,6 +777,31 @@ export type QuestionnaireQuestion = {
   optional?: boolean;
 };
 
+/**
+ * S.6 — the cancellation terms a buyer is entitled to read BEFORE they pay.
+ *
+ * Two endpoints return this shape and they answer different questions:
+ *  - `GET /public/coaching/products/:id` → the product's LIVE policy, i.e. "what
+ *    would I be agreeing to". Show it on the storefront.
+ *  - `POST …/booking/reserve` → the SNAPSHOT written onto the booking, i.e.
+ *    "what did I agree to". Show it from the details step onwards, because an
+ *    operator editing the policy mid-checkout must not move the terms under a
+ *    buyer who already holds the hour.
+ *
+ * `description` is rendered SERVER-side by the shared `describeCancellationPolicy`
+ * so the sentence at checkout is byte-identical to the one in the buyer's portal.
+ * It is `null` when the seller configured no policy — render nothing rather than
+ * inventing a right, and note that "no policy" is a different fact from `none`.
+ */
+export type CancellationTermsView = {
+  policy: "none" | "until" | "anytime" | null;
+  cutoffHours: number | null;
+  /** The seller's own free text, when they wrote any. */
+  terms: string | null;
+  /** One ready-made sentence, or null when there is no policy at all. */
+  description: string | null;
+};
+
 export type CoachingProduct = {
   id: string;
   title: string;
@@ -773,6 +823,8 @@ export type CoachingProduct = {
   questionnaire?: QuestionnaireQuestion[];
   /** Rating aggregate — present on the detail endpoint, null until first published review. */
   reviewAggregate?: IReviewAggregate | null;
+  /** The seller's CURRENT cancellation terms — present on the detail endpoint only. */
+  cancellation?: CancellationTermsView | null;
 };
 
 export type PublicCourseLesson = {
@@ -847,6 +899,29 @@ export type PodcastShow = {
 
 // ---- Events ------------------------------------------------------------------
 
+/**
+ * The artist's booking fee, RESOLVED — what `GET /public/events/:id` publishes
+ * so a storefront can quote the real price before the buyer commits.
+ *
+ * The fee is charged per ORDER (`total_amount` goes up by it), and until this
+ * shipped no buyer-facing surface mentioned it anywhere.
+ *
+ * These are NOT the event's raw `ticketFeeCents` / `ticketFeeBps` columns. Those
+ * are `null` whenever the event inherits the artist's default — the ordinary
+ * case — so reading them shows no fee while one is being charged. The server
+ * merges the event's override over the profile default and sends the result.
+ */
+export interface IBookingFee {
+  /** The flat part per ORDER, in major units of `currency`. */
+  feeAmount: number;
+  /** The percentage of the discounted subtotal, in basis points. 2.5% = 250. */
+  feeBps: number;
+  /** The artist's currency — the one ticket prices and `feeAmount` are in. */
+  currency: string;
+  /** 100, or 1 for a zero-decimal currency (JPY). The percentage rounds to it. */
+  minorUnitFactor: number;
+}
+
 export interface IEvent {
   id: string;
   profileId: string;
@@ -896,6 +971,77 @@ export interface IEvent {
   tickets: ITicket[];
   media: IMedia[];
   slug: string;
+  /**
+   * The booking fee this event's buyers will be charged, already resolved.
+   *
+   * Optional because the detail endpoint composes it and the LIST endpoint does
+   * not — no list surface quotes a ticket price, so there is no figure there for
+   * a buyer to mistake for a final one. A page reached through `useEvents()`
+   * must not assume it is present.
+   */
+  bookingFee?: IBookingFee | null;
+}
+
+// ---- Event series ------------------------------------------------------------
+
+/**
+ * One date within a series, as `GET /public/event-series/:slug` returns it.
+ *
+ * DELIBERATELY not `IEvent`. A series page lists dates; it does not sell them —
+ * the buyer follows a date through to `/events/:slug`, which is the page that
+ * carries tickets, the questionnaire, terms and the checkout. Restating the
+ * narrow shape here keeps that boundary visible: if a field is missing from
+ * this type, the series endpoint does not publish it, and adding it is a
+ * decision made on the server first.
+ */
+export interface IEventSeriesDate {
+  id: string;
+  title: string;
+  /** Links through to the event page — `/events/:slug`. */
+  slug: string;
+  dateTime: string;
+  endDateTime: string | null;
+  doorsOpenAt: string | null;
+  timezone?: string;
+  type: "physical" | "virtual" | "hybrid" | string;
+  /**
+   * A `cancelled` date STAYS in this list — a ticket-holder following their
+   * link must learn why rather than meet a 404 — so any renderer MUST mark it
+   * rather than assume every entry is going ahead.
+   */
+  status: "scheduled" | "on_sale" | "sold_out" | "cancelled" | "completed";
+  cancelledAt: string | null;
+  cancellationReason: string | null;
+  address?: {
+    name?: string;
+    street?: string;
+    city?: string;
+    state?: string;
+    country?: string;
+    zipCode?: string;
+  };
+}
+
+/**
+ * A NAMED, multi-date event series.
+ *
+ * Every event on the platform belongs to a series (a one-off show is a series
+ * of one), but only a series that a human NAMED and that holds at least two
+ * publicly-visible dates has a page. Everything else 404s from the API, so this
+ * type never describes a container-of-one and a renderer never has to ask.
+ */
+export interface IEventSeries {
+  id: string;
+  title: string;
+  slug: string;
+  description: string | null;
+  /** The publicly-visible dates, ordered by `dateTime`, earliest first. */
+  events: IEventSeriesDate[];
+  media: IMedia[];
+  /** `events.length`, derived server-side off the SAME list — they cannot disagree. */
+  dateCount: number;
+  firstDateTime: string | null;
+  lastDateTime: string | null;
 }
 
 export type ITicket = {

package/src/ui/format/bookingFee.ts

@@ -0,0 +1,98 @@
+import type { IBookingFee } from "../../types/models";
+
+/**
+ * The artist's booking fee, as a buyer-facing surface has to show it.
+ *
+ * ## Why this file exists
+ *
+ * The fee was CHARGED and displayed nowhere. `createOrder` raised the order
+ * total by it and no storefront on either rendering stack said a word, so the
+ * buyer met it for the first time on the card statement. That is not only
+ * unfair, it is regulated — FTC junk-fee rules, CMA guidance and the EU
+ * price-indication rules all require a mandatory charge to be visible BEFORE
+ * the buyer commits.
+ *
+ * ## What is safe to compute here, and what is not
+ *
+ * The RESOLUTION — the event's override merged over the artist's profile
+ * default, `null` meaning "inherit" and `0` meaning "deliberately zero" — is NOT
+ * done here. It happens once on the server and arrives already resolved on
+ * `IEvent.bookingFee`. Reimplementing it on two separate rendering stacks is
+ * exactly how a displayed fee drifts away from a charged one, and the raw
+ * columns are `null` in the ordinary inheriting case, so a client reading them
+ * would show no fee at all.
+ *
+ * What is left is the arithmetic, and it is deterministic: a flat part plus a
+ * percentage of the subtotal, rounded to the currency's minor unit. The factor
+ * comes down in the payload precisely so no storefront needs its own copy of
+ * the zero-decimal currency list to round the way the server rounds.
+ *
+ * ## This is still an ESTIMATE
+ *
+ * It exists to keep the running total honest while the buyer is still choosing
+ * quantities, when no order exists and the server has no figure to give. The
+ * moment an order is created, `POST /public/events/:id/orders` returns the
+ * `feeAmount` it actually wrote, and THAT is what the payment step shows. The
+ * two agree by construction; if the artist changes their fee mid-session, the
+ * server's number is the one the buyer sees before paying.
+ *
+ * Mirrors `computeBookingFee` in `apps/backend/src/db/types/bookingFee.ts`.
+ */
+export function computeBookingFeeAmount(input: {
+  /** The DISCOUNTED subtotal, in major units of the artist's currency. */
+  subtotal: number;
+  fee: IBookingFee | null | undefined;
+}): number {
+  const { subtotal, fee } = input;
+  if (!fee) return 0;
+
+  /**
+   * A free order pays nothing — the flat part included.
+   *
+   * A comp, a members' freebie or a giveaway must not be shown a booking fee,
+   * because it is not charged one. The server takes the same branch, so showing
+   * one here would be a line the buyer is never billed for.
+   */
+  if (subtotal <= 0) return 0;
+
+  const factor = fee.minorUnitFactor > 0 ? fee.minorUnitFactor : 100;
+  const subtotalMinor = Math.round(subtotal * factor);
+  const percentMinor = Math.round((subtotalMinor * fee.feeBps) / 10_000);
+  const flatMinor = Math.round(fee.feeAmount * factor);
+
+  return Math.max(0, flatMinor + percentMinor) / factor;
+}
+
+/**
+ * Whether this artist charges a booking fee at all.
+ *
+ * The payload is always present so a surface can rely on its shape, which means
+ * "no fee" arrives as zeros rather than as an absent object. A storefront that
+ * rendered those zeros would print a "+$0.00 booking fee" line — inventing a
+ * charge that does not exist and implying one might appear later. There is
+ * nothing to disclose when nothing is charged, so every surface suppresses the
+ * line on this.
+ */
+export function hasBookingFee(fee: IBookingFee | null | undefined): boolean {
+  return !!fee && (fee.feeAmount > 0 || fee.feeBps > 0);
+}
+
+/**
+ * The fee rule in words, for a price that is quoted WITHOUT a cart behind it.
+ *
+ * An event page saying "From $25" is a price a buyer can reasonably read as
+ * final, but there is no selection yet, so there is no amount — only the rule.
+ * Naming it ("+ $1.50 booking fee", "+ 2.5% booking fee") is what stops the
+ * quoted figure from being the whole story. Returns `null` when there is no fee,
+ * so the caller renders nothing.
+ */
+export function describeBookingFee(
+  fee: IBookingFee | null | undefined,
+  formatAmount: (amount: number) => string,
+): string | null {
+  if (!hasBookingFee(fee)) return null;
+  const parts: string[] = [];
+  if (fee!.feeAmount > 0) parts.push(formatAmount(fee!.feeAmount));
+  if (fee!.feeBps > 0) parts.push(`${+(fee!.feeBps / 100).toFixed(2)}%`);
+  return `+ ${parts.join(" + ")} booking fee`;
+}

package/src/ui/headless/coaching/useCoachingBooking.ts

@@ -11,6 +11,7 @@ import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
 import { useCouponField, type CouponQuoteFn } from "../coupon/useCouponField";
 import { readAttributionRef } from "../../../utils/attribution";
 import { readLanding } from "../../../utils/landing";
+import type { CancellationTermsView } from "../../../types/models";
 
 export type CoachingBookingStep = "slot" | "details" | "payment";
 
@@ -88,6 +89,13 @@ export function useCoachingBooking(slug?: string, opts: UseCoachingBookingOption
   const [questionnaire, setQuestionnaire] = useState<unknown>(undefined);
   const [returnUrl, setReturnUrl] = useState("");
   const [error, setError] = useState<string | null>(null);
+  /**
+   * S.6 — the terms this buyer actually agreed to, as snapshotted onto the
+   * booking at reserve. Held separately from `product.cancellation` (the
+   * seller's live setting) because they can diverge the moment the operator
+   * edits the policy while the hour is held, and only this copy governs.
+   */
+  const [agreedCancellation, setAgreedCancellation] = useState<CancellationTermsView | null>(null);
   // Epoch ms when the current slot hold expires (null when nothing is held).
   const [reservationExpiresAt, setReservationExpiresAt] = useState<number | null>(null);
 
@@ -153,6 +161,7 @@ export function useCoachingBooking(slug?: string, opts: UseCoachingBookingOption
       if (bookingId) await unreserve.mutateAsync({ bookingId }).catch(() => undefined);
       const data = await reserve.mutateAsync({ slotId: selectedSlotId });
       setBookingId(data.bookingId);
+      setAgreedCancellation(data.cancellation ?? null);
       setReservationExpiresAt(Date.now() + RESERVATION_HOLD_MS);
       setStep("details");
     } catch (e) {
@@ -171,6 +180,9 @@ export function useCoachingBooking(slug?: string, opts: UseCoachingBookingOption
     setBookingId(null);
     setSelectedSlotId(null);
     setReservationExpiresAt(null);
+    // The agreed terms belonged to a booking that no longer exists — the next
+    // reserve snapshots afresh, and may snapshot something different.
+    setAgreedCancellation(null);
     // The quote belonged to a booking that no longer exists — keeping it would
     // show a discount against a price nothing has agreed to.
     coupon.reset();
@@ -234,6 +246,13 @@ export function useCoachingBooking(slug?: string, opts: UseCoachingBookingOption
     setStep,
     selectedSlotId,
     bookingId,
+    /**
+     * The cancellation terms in force for THIS checkout (S.6): the booking's
+     * snapshot once a slot is held, the product's live policy before that. Never
+     * both — a surface rendering `product.cancellation` after the reserve would
+     * show the buyer terms other than the ones they are bound by.
+     */
+    cancellation: agreedCancellation ?? product?.cancellation ?? null,
     selectSlot,
     reserveSelected,
     reservationExpiresAt,

package/src/ui/headless/event/useEventCheckout.ts

@@ -4,6 +4,7 @@ import { useCart } from "../../../contexts/CartContext";
 import { useEvent, useCreateEventOrder } from "../../../data/queries/useEvents";
 import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
 import { useCouponField } from "../coupon/useCouponField";
+import { computeBookingFeeAmount } from "../../format/bookingFee";
 import { readAttributionRef } from "../../../utils/attribution";
 import { readLanding } from "../../../utils/landing";
 
@@ -47,6 +48,14 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
   const [questionnaire, setQuestionnaire] = useState<unknown>(undefined);
   const [returnUrl, setReturnUrl] = useState("");
   const [error, setError] = useState<string | null>(null);
+  /**
+   * The booking fee the SERVER charged, once an order exists.
+   *
+   * Kept separately from the coupon quote because it is not a discount concern:
+   * it is the one figure on the payment screen that the client must never
+   * compute for itself, since it is the number on the card.
+   */
+  const [serverFeeAmount, setServerFeeAmount] = useState<number | null>(null);
 
   /**
    * Discount code — STAGED, not quoted.
@@ -71,6 +80,29 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
     [selectedTickets],
   );
 
+  /**
+   * The artist's booking fee (1.4) — the thing the buyer was charged and never
+   * told about, on any surface, on either rendering stack.
+   *
+   * Resolved by the server (`event.bookingFee`), because the event's own
+   * `ticketFeeCents`/`ticketFeeBps` are `null` whenever it inherits the artist's
+   * default, and that is the ordinary case.
+   */
+  const bookingFee = event?.bookingFee ?? null;
+
+  /**
+   * The fee to SHOW, in the artist's currency.
+   *
+   * Once an order exists the server has told us what it charged, and that wins
+   * outright — a locally derived figure on the payment screen is how a displayed
+   * total drifts from a billed one. Before then there is no order to ask, so the
+   * running total carries an estimate off the resolved rule; it keeps the "Total"
+   * honest while the buyer is still choosing quantities, which is precisely when
+   * the disclosure has to happen.
+   */
+  const bookingFeeAmount =
+    serverFeeAmount ?? computeBookingFeeAmount({ subtotal: totalAmount, fee: bookingFee });
+
   // Keep only positive quantities in state — a ticket dropped to 0 is removed
   // entirely, so `items` never carries a 0-quantity entry (the orders endpoint
   // rejects those with "quantity must be positive").
@@ -151,6 +183,11 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
         couponId: data.couponId ?? null,
         appliedCoupons: data.appliedCoupons ?? [],
       });
+      // From here on the fee on screen is the fee on the card. `?? 0` rather
+      // than `?? null`: the response always carries it, and a free order
+      // legitimately reports 0 — falling back to the estimate there would put a
+      // fee on a comp.
+      setServerFeeAmount(data.feeAmount ?? 0);
       const origin = typeof window !== "undefined" ? window.location.origin : "";
       const ru = `${origin}${finalisePath(slug, data.orderId)}`;
       setReturnUrl(ru);
@@ -185,6 +222,10 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
     // The started payment described the DISCOUNTED order; leaving it would keep
     // the reduced total on screen after the discount is gone.
     flow.reset();
+    // Same reason: the abandoned order's fee was a percentage of the DISCOUNTED
+    // subtotal, so keeping it would understate the fee on the fresh, full-price
+    // order the next `continueToPayment` creates.
+    setServerFeeAmount(null);
     setStep("details");
   };
 
@@ -199,9 +240,27 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
     // The server's figure wins the moment there is one: start-payment first,
     // then the order response (which is already net of any discount), and only
     // the locally summed ticket prices before either exists.
-    totalAmount: flow.result?.totalAmount ?? coupon.quote?.totalAmount ?? totalAmount,
-    /** GROSS ticket total, before any discount. */
+    //
+    // Both server figures already INCLUDE the booking fee — `total_amount` has
+    // always been raised by it. The local sum did not, which is what made the
+    // pre-payment "Total" a number the buyer would not be charged; the estimated
+    // fee is added so the figure on screen means what it says.
+    totalAmount:
+      flow.result?.totalAmount ?? coupon.quote?.totalAmount ?? totalAmount + bookingFeeAmount,
+    /** GROSS ticket total, before any discount OR booking fee. */
     subTotal: coupon.quote?.subTotal ?? totalAmount,
+    /**
+     * The resolved fee RULE, for surfaces that quote a price with no cart behind
+     * it (an event page's "From $25"). `null` when the artist charges none.
+     */
+    bookingFee,
+    /**
+     * The fee for THIS selection — the server's own number once an order exists,
+     * an estimate off the rule before that. Zero when nothing is charged, which
+     * is what every surface checks before drawing the line: a "+$0.00 booking
+     * fee" row invents a charge that does not exist.
+     */
+    bookingFeeAmount,
     /** Discount code state + the server's quote. See `useCouponField`. */
     coupon,
     clearCoupon,