@tribe-nest/forge 3.9.0 → 3.14.0

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;
@@ -559,15 +584,35 @@ export type IMedia = {
   previewStatus?: 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 = {
@@ -633,11 +678,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). */
@@ -725,8 +795,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;
@@ -752,6 +826,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 +872,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 +948,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 +1020,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,

package/src/ui/headless/index.ts

@@ -76,3 +76,4 @@ export * from "./work";
 // Funnel instrumentation — wrap a multi-step flow to record step-through and
 // drop-off on the first-party analytics feed.
 export * from "./funnel";
+export * from "./useVariantSelection";

package/src/ui/headless/membership/MembershipGate.tsx

@@ -1,5 +1,6 @@
 import type { ReactNode } from "react";
 import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+import { getMembershipAccess } from "../../../utils/membershipAccess";
 
 export interface MembershipGateState {
   hasAccess: boolean;
@@ -28,10 +29,14 @@ export interface MembershipGateProps {
 export function MembershipGate({ tiers, access, children, fallback }: MembershipGateProps) {
   const { user, isAuthenticated } = usePublicAuth();
   const membership = user?.membership;
-  const activeMembership = !!membership && membership.status === "active";
+  // The SERVER's access decision, not a `status === "active"` compare. That
+  // compare locked out members in `past_due`/`grace` — states the backend
+  // deliberately keeps access through — so a card that bounced cost them the
+  // content they were still paying for.
+  const membershipGrantsAccess = getMembershipAccess(membership).hasAccess;
   const tierAllows = !tiers?.length || (membership ? tiers.includes(membership.membershipTierId) : false);
 
-  const hasAccess = access ?? (activeMembership && tierAllows);
+  const hasAccess = access ?? (membershipGrantsAccess && tierAllows);
 
   if (hasAccess) return <>{children}</>;
   if (typeof fallback === "function") return <>{fallback({ hasAccess, isAuthenticated })}</>;