@tribe-nest/forge 3.9.0 → 3.14.0

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.9.0",
+  "version": "3.14.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

@@ -31,7 +31,19 @@ export type CartItem = {
   payWhatYouWant: boolean;
   color?: string;
   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;
 };

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/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/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

@@ -26,6 +26,11 @@ 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";
+export type { VariantAxis, VariantAxisValue } from "./ui/headless/useVariantSelection";
 export type { CartItem, TicketCartItem, AttachedTo } from "./contexts/CartContext";
 export {
   ACCESS_TOKEN_KEY,
@@ -69,6 +74,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 +129,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;