@tribe-nest/forge 1.20.2 → 2.2.0

package/package.json

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

package/src/contexts/AppAuthContext.tsx

@@ -20,6 +20,15 @@ export interface AppAuthUser {
   emailVerified: boolean;
   status: string;
   appId: string | null;
+  /**
+   * What YOUR app has decided this user may do. The strings are your own — the
+   * platform stores them and never reads them for meaning.
+   *
+   * Use them to decide what to RENDER. They are not a security boundary on their
+   * own: this object lives in the browser, so anything privileged must also be
+   * checked on your server with `verifyAppUser`.
+   */
+  permissions: string[];
 }
 
 export interface AppSignupInput {
@@ -47,6 +56,19 @@ interface AppAuthContextType {
   logout: () => Promise<void>;
   refetch: () => Promise<void>;
   clearError: () => void;
+  /**
+   * Whether the signed-in user holds a permission your app defined.
+   *
+   * For DECIDING WHAT TO SHOW — a nav item, a button, a route. A signed-out user
+   * is always false. Anything that actually does something privileged must be
+   * checked again on your server with `verifyAppUser(request, cfg, { require })`;
+   * hiding a button does not protect the route behind it.
+   *
+   * @example
+   * const { hasPermission } = useAppAuth()
+   * {hasPermission("bookings.manage") && <CancelButton />}
+   */
+  hasPermission: (permission: string) => boolean;
 }
 
 const AppAuthContext = createContext<AppAuthContextType | null>(null);
@@ -165,6 +187,10 @@ export function AppAuthProvider({ children }: { children: ReactNode }) {
       logout,
       refetch,
       clearError: () => setErrorMessage(null),
+      // Defensive `?? []`: a site running against an older API (or a cached
+      // response from before permissions existed) has no array here, and a
+      // crash in a render guard is worse than a hidden button.
+      hasPermission: (permission: string) => (user?.permissions ?? []).includes(permission),
     }),
     [appId, user, isInitialized, isLoading, errorMessage, signup, login, logout, refetch],
   );

package/src/contexts/CartContext.tsx

@@ -1,9 +1,21 @@
 "use client";
 import type { ProductDeliveryType } from "../types/models";
-import { createContext, useCallback, useContext, useState } from "react";
+import { createContext, useCallback, useContext, useMemo, useState } from "react";
 import type { ReactNode } from "react";
 import { useEffect } from "react";
 
+/**
+ * What a line is attached to. A product carrying this is an ADD-ON: it was
+ * added from another entity's page (an event's add-on block) and is only
+ * sellable alongside that entity's own line. The server enforces it —
+ * `POST /public/checkouts` rejects a bundle whose add-on has no base.
+ *
+ * Attachment describes how the item was added to THIS cart, never what the
+ * product is: the same product added from the shop carries nothing and sells
+ * on its own as always.
+ */
+export type AttachedTo = { type: "event"; entityId: string };
+
 export type CartItem = {
   productId: string;
   productVariantId: string;
@@ -20,6 +32,30 @@ export type CartItem = {
   color?: string;
   size?: string;
   deliveryType?: ProductDeliveryType;
+  /** Set automatically from `?addonFor=` — see `addToCart`. */
+  attachedTo?: AttachedTo;
+};
+
+/**
+ * A ticket selection for one event: the tier→quantity map exactly as the ticket
+ * modal produces it.
+ *
+ * Tickets live in their own collection rather than as a member of a `CartItem`
+ * union, deliberately. A dozen components read `cartItems` — four of the header
+ * layouts only want a count — and every one of them would need type narrowing
+ * for a shape they never render. Keeping products' shape untouched means the
+ * whole existing shop, on both rendering stacks, is unaffected; the two places
+ * that genuinely need both (the cart panel and checkout) read both lists.
+ */
+export type TicketCartItem = {
+  eventId: string;
+  eventSlug: string;
+  eventTitle: string;
+  coverImage?: string;
+  /** 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 }>;
 };
 
 interface CartContextType {
@@ -27,6 +63,17 @@ interface CartContextType {
   addToCart: (item: CartItem) => boolean;
   removeFromCart: (productId: string, isGift: boolean, recipientEmail?: string) => void;
   clearCart: () => void;
+  /** Ticket selections, one entry per event. */
+  ticketItems: TicketCartItem[];
+  /** Add or replace the selection for an event (the modal always sends the whole map). */
+  setTickets: (item: TicketCartItem) => void;
+  /** Drops the selection AND every add-on attached to that event. */
+  removeTickets: (eventId: string) => void;
+  hasTicketsFor: (eventId: string) => boolean;
+  /** Products + tickets, for the header badge. */
+  itemCount: number;
+  /** True when the cart spans more than one surface — i.e. the bundle path. */
+  isBundle: boolean;
   isCartOpen: boolean;
   setCartOpen: React.Dispatch<React.SetStateAction<boolean>>;
   /** False until the cart has been read from storage after mount. Gate any
@@ -38,8 +85,26 @@ const CartContext = createContext<CartContextType | undefined>(undefined);
 
 const CART_STORAGE_KEY = "tribenest-cart";
 
+/**
+ * The event this page is selling add-ons for, if any. The add-on card links to
+ * the ordinary product page with `?addonFor=<eventId>`, and stamping happens
+ * HERE rather than in the product page so that Forge's `ProductDetail` and the
+ * Craft themes' `ProductDetails` / `MusicItemDetails` need no changes at all —
+ * they don't know add-ons exist.
+ */
+function readAddonContext(): AttachedTo | undefined {
+  if (typeof window === "undefined") return undefined;
+  try {
+    const eventId = new URLSearchParams(window.location.search).get("addonFor");
+    return eventId ? { type: "event", entityId: eventId } : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export function CartProvider({ children }: { children: ReactNode }) {
   const [cartItems, setCartItems] = useState<CartItem[]>([]);
+  const [ticketItems, setTicketItems] = useState<TicketCartItem[]>([]);
   const [isInitialized, setIsInitialized] = useState(false);
   const [isCartOpen, setCartOpen] = useState(false);
 
@@ -49,7 +114,14 @@ export function CartProvider({ children }: { children: ReactNode }) {
       try {
         const savedCart = localStorage.getItem(CART_STORAGE_KEY);
         if (savedCart) {
-          setCartItems(JSON.parse(savedCart));
+          const parsed = JSON.parse(savedCart);
+          // Carts saved before tickets existed are a bare array — keep them.
+          if (Array.isArray(parsed)) {
+            setCartItems(parsed);
+          } else {
+            setCartItems(parsed.items ?? []);
+            setTicketItems(parsed.tickets ?? []);
+          }
         }
       } catch (error) {
         console.error("Failed to load cart from localStorage:", error);
@@ -62,15 +134,19 @@ export function CartProvider({ children }: { children: ReactNode }) {
   useEffect(() => {
     if (isInitialized) {
       try {
-        localStorage.setItem(CART_STORAGE_KEY, JSON.stringify(cartItems));
+        localStorage.setItem(CART_STORAGE_KEY, JSON.stringify({ items: cartItems, tickets: ticketItems }));
       } catch (error) {
         console.error("Failed to save cart to localStorage:", error);
       }
     }
-  }, [cartItems, isInitialized]);
+  }, [cartItems, ticketItems, isInitialized]);
 
   const addToCart = useCallback(
     (item: CartItem): boolean => {
+      // An add-on reached this page via `?addonFor=`; bind the line to it.
+      const attachedTo = item.attachedTo ?? readAddonContext();
+      const next = attachedTo ? { ...item, attachedTo } : item;
+
       const exists = cartItems.some(
         (i) =>
           i.productId === item.productId &&
@@ -88,7 +164,7 @@ export function CartProvider({ children }: { children: ReactNode }) {
               i.isGift === item.isGift &&
               i.recipientEmail === item.recipientEmail
             ) {
-              return item;
+              return next;
             } else {
               return i;
             }
@@ -98,7 +174,7 @@ export function CartProvider({ children }: { children: ReactNode }) {
         // decides whether to toast. (Was `toast.info("Item already in cart")`.)
         return false;
       }
-      setCartItems((prev) => [...prev, item]);
+      setCartItems((prev) => [...prev, next]);
       setCartOpen(true);
       return true;
     },
@@ -113,11 +189,59 @@ export function CartProvider({ children }: { children: ReactNode }) {
     );
   };
 
-  const clearCart = () => setCartItems([]);
+  const setTickets = useCallback((item: TicketCartItem) => {
+    setTicketItems((prev) => [...prev.filter((t) => t.eventId !== item.eventId), item]);
+    setCartOpen(true);
+  }, []);
+
+  /**
+   * Removing the base removes what hangs off it. Leaving orphaned add-ons in
+   * the cart would produce a checkout the server refuses, with nothing on
+   * screen explaining why — so they go, and the caller toasts.
+   */
+  const removeTickets = useCallback((eventId: string) => {
+    setTicketItems((prev) => prev.filter((t) => t.eventId !== eventId));
+    setCartItems((prev) => prev.filter((i) => i.attachedTo?.entityId !== eventId));
+  }, []);
+
+  const hasTicketsFor = useCallback(
+    (eventId: string) => ticketItems.some((t) => t.eventId === eventId),
+    [ticketItems],
+  );
+
+  const clearCart = () => {
+    setCartItems([]);
+    setTicketItems([]);
+  };
+
+  const itemCount = useMemo(
+    () =>
+      cartItems.reduce((acc, i) => acc + i.quantity, 0) +
+      ticketItems.reduce((acc, t) => acc + Object.values(t.tickets).reduce((a, b) => a + b, 0), 0),
+    [cartItems, ticketItems],
+  );
+
+  // Only a cart spanning both surfaces takes the bundle engine; a products-only
+  // or tickets-only cart keeps its existing single-surface flow untouched.
+  const isBundle = cartItems.length > 0 && ticketItems.length > 0;
 
   return (
     <CartContext.Provider
-      value={{ cartItems, addToCart, removeFromCart, clearCart, isCartOpen, setCartOpen, isReady: isInitialized }}
+      value={{
+        cartItems,
+        addToCart,
+        removeFromCart,
+        clearCart,
+        ticketItems,
+        setTickets,
+        removeTickets,
+        hasTicketsFor,
+        itemCount,
+        isBundle,
+        isCartOpen,
+        setCartOpen,
+        isReady: isInitialized,
+      }}
     >
       {children}
     </CartContext.Provider>

package/src/data/queries/useCheckouts.ts

@@ -0,0 +1,101 @@
+import { useMutation } from "@tanstack/react-query";
+import { useForge } from "../../provider/ForgeProvider";
+import type { CartItem, TicketCartItem } from "../../contexts/CartContext";
+
+/** One line of a bundle, in the shape `POST /public/checkouts` expects. */
+export type CheckoutLineInput =
+  | {
+      type: "product";
+      productId: string;
+      productVariantId: string;
+      quantity: number;
+      price: number;
+      title: string;
+      coverImage?: string;
+      isGift?: boolean;
+      recipientName?: string;
+      recipientEmail?: string;
+      recipientMessage?: string;
+      payWhatYouWant?: boolean;
+      attachedTo?: { type: "event"; entityId: string };
+    }
+  | {
+      type: "event_ticket";
+      eventId: string;
+      ticketId: string;
+      quantity: number;
+      price: number;
+      title: string;
+      coverImage?: string;
+    };
+
+/**
+ * Flatten the two cart collections into the flat line list the bundle endpoint
+ * takes. A ticket selection expands to one line per tier, because the server
+ * groups by event itself.
+ */
+export function cartToCheckoutLines(cartItems: CartItem[], ticketItems: TicketCartItem[]): CheckoutLineInput[] {
+  const ticketLines: CheckoutLineInput[] = ticketItems.flatMap((t) =>
+    Object.entries(t.tickets)
+      .filter(([, qty]) => qty > 0)
+      .map(([ticketId, qty]) => ({
+        type: "event_ticket" as const,
+        eventId: t.eventId,
+        ticketId,
+        quantity: qty,
+        price: t.ticketMeta[ticketId]?.price ?? 0,
+        title: t.ticketMeta[ticketId]?.title ?? t.eventTitle,
+        coverImage: t.coverImage,
+      })),
+  );
+
+  const productLines: CheckoutLineInput[] = cartItems.map((i) => ({
+    type: "product" as const,
+    productId: i.productId,
+    productVariantId: i.productVariantId,
+    quantity: i.quantity,
+    price: i.price,
+    title: i.title,
+    coverImage: i.coverImage,
+    isGift: i.isGift,
+    recipientName: i.recipientName,
+    recipientEmail: i.recipientEmail,
+    recipientMessage: i.recipientMessage,
+    payWhatYouWant: i.payWhatYouWant,
+    attachedTo: i.attachedTo,
+  }));
+
+  // Tickets first so the server's own ordering matches how the cart reads.
+  return [...ticketLines, ...productLines];
+}
+
+export type CreateCheckoutResult = { checkoutId: string; currency: string; subtotalCents: number };
+
+export function useCreateCheckout() {
+  const { client, profileId } = useForge();
+
+  return useMutation<CreateCheckoutResult, unknown, Record<string, unknown>>({
+    mutationFn: async (body) => {
+      const res = await client.post("/public/checkouts", { profileId, ...body });
+      return res.data;
+    },
+  });
+}
+
+export type FinalizeCheckoutResult = {
+  checkoutId: string;
+  status: string;
+  fulfillmentStatus: string;
+  children?: { sourceType: string; sourceId: string }[];
+};
+
+export function useFinalizeCheckout() {
+  const { client, profileId } = useForge();
+
+  return useMutation<FinalizeCheckoutResult, unknown, { checkoutId: string }>({
+    mutationFn: async ({ checkoutId }) => {
+      const res = await client.post("/public/checkouts/finalize", { profileId, checkoutId });
+      return res.data;
+    },
+  });
+}

package/src/data/queries/useCollections.ts

@@ -5,6 +5,7 @@ import type {
   CollectionQuery,
   CollectionAggregate,
   CollectionAggregateBucket,
+  CollectionAggregateResult,
   CollectionSearchResult,
 } from "../../types/models";
 import { useForge } from "../../provider/ForgeProvider";
@@ -96,6 +97,12 @@ export function useCollectionQuery(
  * Aggregate a collection (group-by + count/sum/avg/min/max) via POST /aggregate —
  * totals, leaderboards, "washes remaining". `scope: "mine"` restricts to the
  * member's own rows.
+ *
+ * Returns `{ buckets, truncated, limit }`. **Check `truncated` before summing
+ * buckets into a total** — a capped set and a complete one are otherwise
+ * indistinguishable, and a partial revenue figure looks exactly like a real one.
+ * You only get `truncated: true` if you passed a `limit`; without one, a
+ * grouping that overflows the cap fails outright rather than answering partially.
  */
 export function useCollectionAggregate(
   slug?: string,
@@ -104,7 +111,7 @@ export function useCollectionAggregate(
 ) {
   const { client, profileId } = useForge();
 
-  return useQuery<CollectionAggregateBucket[]>({
+  return useQuery<CollectionAggregateResult>({
     queryKey: ["collection-aggregate", profileId, slug, JSON.stringify({ aggregate, ...opts })],
     queryFn: async () => {
       const res = await client.post(`/public/collections/${slug}/aggregate`, {
@@ -114,12 +121,19 @@ export function useCollectionAggregate(
         search: opts?.search,
         aggregate,
       });
-      return res.data.data;
+      // The BODY still puts the array under `data` — that wire shape is frozen
+      // for sites already deployed against it. Only this hook's shape changed.
+      return {
+        buckets: res.data.data ?? [],
+        truncated: res.data.truncated === true,
+        limit: Number(res.data.groupLimit ?? 0),
+      };
     },
     enabled: (opts?.enabled ?? true) && !!profileId && !!client && !!slug && !!aggregate,
   });
 }
 
+
 // Prefer the app-user token (useAppAuth) when the viewer is an app user;
 // otherwise fall back to the Forge client's own token (an app-admin's TribeNest
 // session). Both are accepted by the app read endpoint. Returns a per-request
@@ -163,7 +177,7 @@ export function useAppCollectionAggregate(
 ) {
   const { client, appId } = useForge();
 
-  return useQuery<CollectionAggregateBucket[]>({
+  return useQuery<CollectionAggregateResult>({
     queryKey: ["app-collection-aggregate", appId, slug, JSON.stringify({ aggregate, ...opts })],
     queryFn: async () => {
       const res = await client.post(
@@ -176,7 +190,13 @@ export function useAppCollectionAggregate(
       // `{ data }`. Unwrapping here resolved undefined, which React Query
       // rejects outright, so every call errored before reaching the caller.
       // Matches useAppCollectionQuery above; keep the two in step.
-      return res.data;
+      //
+      // Because the body has no room for it, truncation rides in headers here.
+      return {
+        buckets: res.data ?? [],
+        truncated: String(res.headers?.["x-tn-aggregate-truncated"] ?? "") === "true",
+        limit: Number(res.headers?.["x-tn-aggregate-limit"] ?? 0),
+      };
     },
     enabled: (opts?.enabled ?? true) && !!appId && !!client && !!slug && !!aggregate,
   });

package/src/data/queries/useFinalize.ts

@@ -107,3 +107,44 @@ export function useCourseBookingFinalize(courseId?: string, bookingId?: string)
     enabled: !!profileId && !!client && !!bookingId,
   });
 }
+
+/** Statuses a bundle can still move on from while the gateway settles. */
+const PENDING_BUNDLE_STATES = new Set(["unpaid", "paid"]);
+
+export type BundleFinalizeResult = {
+  checkoutId: string;
+  status: string;
+  fulfillmentStatus: string;
+  children?: { sourceType: string; sourceId: string }[];
+};
+
+/**
+ * Finalize a bundle checkout (`/public/checkouts/finalize`). One call settles
+ * every surface in the bundle; the backend polls the single shared intent and
+ * fans out to each child's own fulfill.
+ *
+ * Idempotent, so the return page can poll: a checkout already `complete`
+ * short-circuits, and a `partial` one resumes only the children still owed
+ * (the reconciliation cron does the same thing on a schedule).
+ */
+export function useCheckoutFinalize(args: { checkoutId?: string }, opts?: { pollWhilePending?: boolean }) {
+  const { client, profileId } = useForge();
+  const { checkoutId } = args;
+
+  return useQuery<BundleFinalizeResult>({
+    queryKey: ["bundlePaymentStatus", profileId, checkoutId],
+    queryFn: async () => {
+      const res = await client.post("/public/checkouts/finalize", { profileId, checkoutId });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && !!checkoutId,
+    refetchInterval: opts?.pollWhilePending
+      ? (query) =>
+          query.state.data &&
+          query.state.data.fulfillmentStatus !== "complete" &&
+          PENDING_BUNDLE_STATES.has(query.state.data.status)
+            ? 2500
+            : false
+      : false,
+  });
+}

package/src/data/queries/usePageActions.ts

@@ -6,6 +6,8 @@ export type PageActionType =
   | "lead_magnet"
   | "offer"
   | "product_cards"
+  // Specific products sold as attachments to the page's own entity.
+  | "addons"
   | "donation"
   | "membership"
   | "button";

package/src/index.ts

@@ -21,7 +21,7 @@ export * from "./types";
 export { AudioPlayerProvider, useAudioPlayer } from "./contexts/AudioPlayerContext";
 export type { AudioTrack } from "./contexts/AudioPlayerContext";
 export { CartProvider, useCart } from "./contexts/CartContext";
-export type { CartItem } from "./contexts/CartContext";
+export type { CartItem, TicketCartItem, AttachedTo } from "./contexts/CartContext";
 export {
   ACCESS_TOKEN_KEY,
   PUBLIC_ACCESS_TOKEN_KEY,
@@ -96,3 +96,8 @@ export * from "./utils/landing";
 export * from "./utils/metaPixel";
 export * from "./utils/cookieConsent";
 export * from "./utils/structuredData";
+// Shared by BOTH starters. Kept here rather than in a starter's `/i/-lib` so an
+// app can use them without inheriting the fan-site route tree, and so a fix
+// reaches existing sites through the normal Forge publish.
+export * from "./utils/headMeta";
+export * from "./utils/formatDateTime";