@tribe-nest/forge 3.25.0 → 3.29.0

package/src/ui/headless/checkout/useCheckout.ts

@@ -20,9 +20,11 @@ import {
 } from "../../../data/queries/useCheckouts";
 import { bundleCouponSummary, bundleReturnUrl } from "./bundleCoupon";
 import { holdExpiredMessage, isHoldExpiredError } from "./inventoryHold";
+import { takeResumedCoupon } from "./resumedCoupon";
 import { useInventoryHold } from "./useInventoryHold";
 import { readAttributionRef } from "../../../utils/attribution";
 import { readLanding } from "../../../utils/landing";
+import { computeBookingFeeAmount } from "../../format/bookingFee";
 import { ProductDeliveryType, PaymentProviderName, type ApiError, type PublicTaxQuote } from "../../../types/models";
 
 /** The four checkout stages (guest details are skipped for a logged-in buyer;
@@ -114,7 +116,15 @@ function messageOf(e: unknown): string | undefined {
 export function useCheckout(opts: UseCheckoutOptions = {}) {
   const finalisePath = opts.finalisePath ?? "/checkout/finalise";
   const { user } = usePublicAuth();
-  const { cartItems, ticketItems, isBundle, isReady: isCartReady } = useCart();
+  const { cartItems, ticketItems, isReady: isCartReady } = useCart();
+  /**
+   * Any cart holding tickets settles through the checkout (bundle) engine,
+   * even with NO products beside them. Tickets have no single-surface order
+   * path from this page: `createOrder` only carries `cartItems`, so routing a
+   * tickets-only cart there minted an order with a total and no lines. (The
+   * event modal's own direct flow is unaffected; it never comes through here.)
+   */
+  const usesCheckoutEngine = ticketItems.length > 0;
   const { data: countries = [] } = useShippingCountries();
   const shippingRates = useShippingRates();
   const createOrder = useCreateOrder();
@@ -145,6 +155,27 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     [cartItems, ticketItems],
   );
 
+  /**
+   * The booking fee the ticket lines will be charged, summed per event from the
+   * resolved fee each selection carried out of the modal. An ESTIMATE with the
+   * same honesty contract as the modal's own line: it keeps the running total
+   * explained while no charge exists, and the server's charged total supersedes
+   * it the moment start-payment answers.
+   */
+  const bookingFeeCost = useMemo(
+    () =>
+      round2(
+        ticketItems.reduce((sum, t) => {
+          const ticketSubtotal = Object.entries(t.tickets).reduce(
+            (acc, [id, qty]) => acc + (t.ticketMeta[id]?.price ?? 0) * qty,
+            0,
+          );
+          return sum + computeBookingFeeAmount({ subtotal: ticketSubtotal, fee: t.bookingFee });
+        }, 0),
+      ),
+    [ticketItems],
+  );
+
   const [currentStage, setCurrentStage] = useState<CheckoutStage>("userDetails");
   const [guestUserData, setGuestUserData] = useState<GuestUserData | null>(null);
   const [shippingData, setShippingData] = useState<CheckoutShippingData>();
@@ -161,8 +192,14 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     [selectedShippingRates],
   );
 
-  const [couponCode, setCouponCode] = useState("");
-  const [showCouponInput, setShowCouponInput] = useState(false);
+  /**
+   * A code the buyer arrived with from a recovery link, prefilled but NOT
+   * applied: they still press Apply and the server re-evaluates it against
+   * today. The lazy initialiser consumes the stash, so a code cannot linger and
+   * prefill an unrelated checkout later in the same tab.
+   */
+  const [couponCode, setCouponCode] = useState(takeResumedCoupon);
+  const [showCouponInput, setShowCouponInput] = useState(() => couponCode.length > 0);
   const [couponError, setCouponError] = useState("");
   const [isApplyingCoupon, setIsApplyingCoupon] = useState(false);
   const [appliedCoupon, setAppliedCoupon] = useState<AppliedCoupon | null>(null);
@@ -211,10 +248,10 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     if (currentStage !== "payment" || !isPaidCheckout || startedRef.current) return;
     startedRef.current = true;
 
-    // A cart spanning tickets AND products goes through the bundle engine so
-    // both settle on one payment. Every single-surface cart keeps the flow it
-    // has always had, below.
-    if (isBundle) {
+    // A cart holding tickets (with or without products) goes through the
+    // bundle engine so everything settles on one payment. A products-only
+    // cart keeps the flow it has always had, below.
+    if (usesCheckoutEngine) {
       const enteredCode = couponCode.trim() || undefined;
       createCheckout
         .mutateAsync({
@@ -457,7 +494,7 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
    * the checkout was created — which for a signed-in buyer with a digital-only
    * cart was on mount, so the code could never be typed at all.
    */
-  const isCouponEditable = isBundle ? !settledCheckoutId : !!orderId;
+  const isCouponEditable = usesCheckoutEngine ? !settledCheckoutId : !!orderId;
 
   /** Fold an apply/remove answer for a bundle back into the summary + payment. */
   const absorbBundleCoupon = useCallback((data: ApplyCheckoutCouponResult) => {
@@ -479,7 +516,7 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
   }, []);
 
   const applyCoupon = useCallback(async () => {
-    if (isBundle) {
+    if (usesCheckoutEngine) {
       if (!couponCode.trim()) return;
       setCouponError("");
       // Not created yet (a guest, or a cart with a shipping stage still ahead):
@@ -534,10 +571,10 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     } finally {
       setIsApplyingCoupon(false);
     }
-  }, [couponCode, orderId, checkoutId, finalisePath, applyCouponMutation, applyCheckoutCouponMutation, absorbBundleCoupon, isBundle]);
+  }, [couponCode, orderId, checkoutId, finalisePath, applyCouponMutation, applyCheckoutCouponMutation, absorbBundleCoupon, usesCheckoutEngine]);
 
   const removeCoupon = useCallback(async () => {
-    if (isBundle) {
+    if (usesCheckoutEngine) {
       setCouponError("");
       // Nothing created yet — the staged code simply never travels.
       if (!checkoutId) {
@@ -592,7 +629,7 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     } finally {
       setIsApplyingCoupon(false);
     }
-  }, [orderId, checkoutId, finalisePath, applyCouponMutation, applyCheckoutCouponMutation, absorbBundleCoupon, isBundle]);
+  }, [orderId, checkoutId, finalisePath, applyCouponMutation, applyCheckoutCouponMutation, absorbBundleCoupon, usesCheckoutEngine]);
 
   // ── Free checkout (nothing to charge) ───────────────────────────────────────
   /** Create the (free) order and return its id so the caller can navigate to the
@@ -660,6 +697,8 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     isCartReady,
     subTotal,
     shippingCost,
+    /** Estimated booking fee across the cart's ticket lines; 0 with no tickets. */
+    bookingFeeCost,
     discountAmount,
     hasPhysicalProduct,
     isPaidCheckout,
@@ -695,7 +734,9 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
      * page instead of waiting for a payment that will never be asked for.
      */
     settledCheckoutId,
-    isBundle,
+    /** True when this checkout settles through the bundle engine (any cart
+        holding tickets), which is what the coupon field and summary key off. */
+    isBundle: usesCheckoutEngine,
     ticketItems,
     isCreatingOrder: createOrder.isPending || flow.isStarting,
     startError,
@@ -731,7 +772,11 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     paymentId: effectivePayment?.paymentId,
     chargedAmount: effectivePayment?.chargedAmount ?? 0,
     chargedCurrency: effectivePayment?.chargedCurrency ?? "",
-    returnUrl: `${typeof window !== "undefined" ? window.location.origin : ""}${finalisePath}?orderId=${orderId || ""}`,
+    // The SAME bundle-aware URL handed to start-payment. This was previously
+    // rebuilt here from `orderId` alone, so a bundle (which has a checkoutId
+    // and no order) confirmed its Stripe payment with `?orderId=` empty and
+    // landed on a finalise page that could not resolve anything.
+    returnUrl,
     // ── Free checkout ──────────────────────────────────────────────────────────
     isFreeCheckoutLoading,
     freeCheckout,

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

@@ -264,6 +264,9 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
       eventSlug: slug ?? event.id,
       eventTitle: event.title,
       coverImage: event.media?.find((m: { type: string }) => m.type === "image")?.url,
+      // The resolved fee travels with the selection so the CART checkout can
+      // show the booking-fee line this modal already shows.
+      bookingFee: event.bookingFee ?? null,
       tickets: { ...selectedTickets },
       ticketMeta: Object.fromEntries(
         event.tickets

package/src/ui/headless/funnel/Funnel.tsx

@@ -1,4 +1,5 @@
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, type ReactNode } from "react";
+import { setActiveFunnel } from "../../../client/activeFunnel";
 import { useTrackEvent } from "../../../data/queries/useAnalytics";
 import { useCookieConsent } from "../consent/useCookieConsent";
 import { getFunnelSessionId, markOnce, resetFunnelSession } from "./funnelSession";
@@ -114,6 +115,18 @@ export function Funnel({ id, steps, name, enabled = true, requireConsent = true,
   const emitRef = useRef(emit);
   emitRef.current = emit;
 
+  // Attribution is registered on `enabled`, NOT on `on`. Analytics is what
+  // cookie consent governs; "this lead came from this funnel" is first-party
+  // business data about a conversion the visitor deliberately started, and
+  // gating it behind performance consent would silently drop the attribution of
+  // every lead who declined cookies. Nothing behavioural is attached to the
+  // person: the funnel id travels, the funnel SESSION id never does.
+  useEffect(() => {
+    if (!enabled) return;
+    setActiveFunnel(id);
+    return () => setActiveFunnel(null);
+  }, [enabled, id]);
+
   useEffect(() => {
     if (!on) return;
     if (!markOnce(id, "entered")) return;

package/src/ui/headless/index.ts

@@ -29,6 +29,24 @@ export {
   type InventoryHoldState,
   type UseInventoryHoldOptions,
 } from "./checkout/useInventoryHold";
+// Cart recovery: what a resume link does when the buyer clicks it. Shared so
+// `apps/client` and a Forge code site cannot decide differently.
+export {
+  useCartResume,
+  effectiveUnitCents,
+  partitionResumeLines,
+  resumeLineToCartItem,
+  resumeLinesToTicketItems,
+  type ResumePartition,
+  type UseCartResumeOptions,
+  type UseCartResumeResult,
+  type CartResumeStatus,
+  type ResumeLine,
+  type ResumedCheckout,
+  type ResumeLineOption,
+  type ResumeLineUnavailableReason,
+} from "./checkout/useCartResume";
+export { rememberResumedCoupon, takeResumedCoupon } from "./checkout/resumedCoupon";
 export {
   isHoldExpiredError,
   holdExpiredMessage,

package/src/ui/index.ts

@@ -55,6 +55,8 @@ export { PresaleCodeField, type PresaleCodeFieldProps } from "./styled/PresaleCo
 export { MembershipCheckout, type MembershipCheckoutProps } from "./styled/MembershipCheckout";
 export { ForgeStripePayment } from "./payment/ForgeStripePayment";
 export { Cart, type CartProps } from "./styled/Cart";
+/** The page a cart-recovery email lands on. Drop in at `/i/checkout/resume`. */
+export { ResumeCart, type ResumeCartProps } from "./styled/ResumeCart";
 // The resolver is exported alongside the component because the Craft themes
 // are a separate rendering stack (Tailwind, not inline styles) and cannot use
 // the component — but the legacy `color`/`size` fallback must not diverge.

package/src/ui/shell/TribeNestApp.tsx

@@ -8,6 +8,7 @@ import { CookieConsent } from "../styled/CookieConsent";
 import { AiAgentWidget } from "../styled/AiAgentWidget";
 import { useThemeTokens } from "../theme/ForgeThemeProvider";
 import { useInitialSiteConfig } from "../../provider/SiteConfigProvider";
+import { ForgeI18nProvider } from "../../i18n";
 import { PoweredBy } from "./PoweredBy";
 import { PreviewDiagnostics } from "./PreviewDiagnostics";
 import { shellAiAgentEnabled, shellPoweredByEnabled, shellPwaEnabled } from "./shellGating";
@@ -142,33 +143,41 @@ export function TribeNestApp({
     : null;
   return (
     <ForgeProvider editable={editable} {...forgeProps}>
-      {/* First in the tree: it must render even if everything below it doesn't. */}
-      {ssrFailure && <PreviewDiagnostics diagnostics={ssrFailure} />}
-      {children}
-      {/* "Powered by TribeNest" — last in the page flow, so it sits below the
-          tenant's own footer. Released builds only (live + published). */}
-      <PoweredByGate editable={editable} state={state} />
-      {/* Global playback bar — self-pins to the viewport bottom, renders nothing
-          until a track loads. */}
-      <AudioPlayer />
-      {/* Auto page views + clicks (+ Meta Pixel, gated on marketing consent).
-          First-party runs cookieless. Off in the editor so preview isn't counted. */}
-      {analytics && <ForgeAnalytics enabled={!editable} firstPartyMode="cookieless" />}
-      {/* Ad attribution capture (tracked-link ref + first-touch landing + visit
-          beacon). Off in the editor so preview visits aren't credited. */}
-      <AttributionCapture enabled={!editable} apiUrl={forgeProps.apiUrl} profileId={forgeProps.profileId} />
-      {/* PWA — SW registration + install banner + (fallback) manifest link. */}
-      {pwa && <PwaRegistration enabled={pwaEnabled} />}
-      {pwa && <InstallBanner enabled={pwaEnabled} />}
-      {pwa && <PwaHeadClient enabled={pwaEnabled} manifestHref={manifestHref} />}
-      {/* Consent banner — shown on first visit, re-openable from anywhere via
-          useCookieConsent().reopen(). Hidden in the editor. */}
-      {cookieConsent && !editable && <CookieConsent useTribeNestPrivacy />}
-      {/* Website AI agent — floating bubble, self-hiding when the profile has no
-          agent enabled. Lives here rather than in each __root so enabling the
-          agent in admin is enough to make it appear; before this it shipped only
-          on the Craft stack and no code site ever rendered it. */}
-      {shellAiAgentEnabled({ aiAgent, editable, appId: forgeProps.appId }) && <AiAgentWidget />}
+      {/* Forge's own copy, in the site's language. Mounted here rather than in
+          each tenant's __root.tsx, so a Forge upgrade is enough to give an
+          existing site i18n. `locale` is the ForgeProvider prop the site
+          already passes (absent or unsupported resolves to English). When
+          `profile_configurations.locale` lands on SiteConfig, that becomes the
+          source and this prop stays the override. */}
+      <ForgeI18nProvider locale={forgeProps.locale}>
+        {/* First in the tree: it must render even if everything below it doesn't. */}
+        {ssrFailure && <PreviewDiagnostics diagnostics={ssrFailure} />}
+        {children}
+        {/* "Powered by TribeNest" — last in the page flow, so it sits below the
+            tenant's own footer. Released builds only (live + published). */}
+        <PoweredByGate editable={editable} state={state} />
+        {/* Global playback bar — self-pins to the viewport bottom, renders nothing
+            until a track loads. */}
+        <AudioPlayer />
+        {/* Auto page views + clicks (+ Meta Pixel, gated on marketing consent).
+            First-party runs cookieless. Off in the editor so preview isn't counted. */}
+        {analytics && <ForgeAnalytics enabled={!editable} firstPartyMode="cookieless" />}
+        {/* Ad attribution capture (tracked-link ref + first-touch landing + visit
+            beacon). Off in the editor so preview visits aren't credited. */}
+        <AttributionCapture enabled={!editable} apiUrl={forgeProps.apiUrl} profileId={forgeProps.profileId} />
+        {/* PWA — SW registration + install banner + (fallback) manifest link. */}
+        {pwa && <PwaRegistration enabled={pwaEnabled} />}
+        {pwa && <InstallBanner enabled={pwaEnabled} />}
+        {pwa && <PwaHeadClient enabled={pwaEnabled} manifestHref={manifestHref} />}
+        {/* Consent banner — shown on first visit, re-openable from anywhere via
+            useCookieConsent().reopen(). Hidden in the editor. */}
+        {cookieConsent && !editable && <CookieConsent useTribeNestPrivacy />}
+        {/* Website AI agent — floating bubble, self-hiding when the profile has no
+            agent enabled. Lives here rather than in each __root so enabling the
+            agent in admin is enough to make it appear; before this it shipped only
+            on the Craft stack and no code site ever rendered it. */}
+        {shellAiAgentEnabled({ aiAgent, editable, appId: forgeProps.appId }) && <AiAgentWidget />}
+      </ForgeI18nProvider>
     </ForgeProvider>
   );
 }