@tribe-nest/forge 1.13.0

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

@@ -0,0 +1,438 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCart } from "../../../contexts/CartContext";
+import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+import { useCreateOrder, type CreateOrderShippingRate, type CreateOrderResult } from "../../../data/queries/useOrders";
+import {
+  useShippingCountries,
+  useShippingRates,
+  useApplyCoupon,
+  type ShippingGroup,
+  type ShippingRate,
+  type ShippingCountry,
+} from "../../../data/queries/useShipping";
+import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
+import { readAttributionRef } from "../../../utils/attribution";
+import { readLanding } from "../../../utils/landing";
+import { ProductDeliveryType, PaymentProviderName, type ApiError, type PublicTaxQuote } from "../../../types/models";
+
+/** The four checkout stages (guest details are skipped for a logged-in buyer;
+ * the shipping stages are skipped when the cart holds no physical item). */
+export type CheckoutStage = "userDetails" | "shippingAddress" | "shippingRates" | "payment";
+
+/** Ordered stage list — used to drive the progress indicator. */
+export const CHECKOUT_STAGE_ORDER: CheckoutStage[] = ["userDetails", "shippingAddress", "shippingRates", "payment"];
+
+export interface UseCheckoutOptions {
+  /** Path used to build the post-payment return URL. Defaults to `/checkout/finalise`. */
+  finalisePath?: string;
+}
+
+/** Guest buyer identity (collected when there is no logged-in user). */
+export interface GuestUserData {
+  firstName: string;
+  lastName: string;
+  email: string;
+}
+
+/** Buyer-supplied shipping address (only relevant for physical items). */
+export interface CheckoutShippingData {
+  address1: string;
+  city: string;
+  stateCode: string;
+  countryCode: string;
+  zip: string;
+  phone: string;
+}
+
+/** A shipping rate the buyer has selected for a given product. */
+export type SelectedShippingRate = CreateOrderShippingRate;
+
+interface AppliedCoupon {
+  code: string;
+  discountType: string | null;
+  discountValue: number | null;
+}
+
+interface CouponPaymentUpdate {
+  paymentSecret: string;
+  paymentId: string;
+  chargedAmount: number;
+  chargedCurrency: string;
+}
+
+const round2 = (n: number) => Math.round(n * 100) / 100;
+
+/** Best-effort extraction of an API error message. */
+function messageOf(e: unknown): string | undefined {
+  return (e as ApiError)?.response?.data?.message;
+}
+
+/**
+ * Headless cart-checkout behavior — the complete staged flow the client app
+ * ships, composed from the existing data hooks:
+ *
+ *   guest details (guest only) → shipping address + per-product rate selection
+ *   (physical only) → create order + start payment → coupon apply/remove →
+ *   redirect payment (or a free-order shortcut).
+ *
+ * The order is created lazily on entering the payment stage (via
+ * `useCreateOrder` + `usePaymentFlow`), and a coupon is applied against that
+ * created order (`useApplyCoupon` re-issues the payment intent). Shipping cost
+ * is owned by the rate selector (which sums multi-currency rates into the
+ * display currency) and fed back via `setSelectedShipping` — it is never
+ * overwritten from the raw order response, which keeps the order-summary total
+ * in step with the rate the buyer picked.
+ *
+ * This hook holds state + async transitions only; formatting, navigation and
+ * the payment UI live in the consuming component (`<Checkout />`).
+ */
+export function useCheckout(opts: UseCheckoutOptions = {}) {
+  const finalisePath = opts.finalisePath ?? "/checkout/finalise";
+  const { user } = usePublicAuth();
+  const { cartItems, isReady: isCartReady } = useCart();
+  const { data: countries = [] } = useShippingCountries();
+  const shippingRates = useShippingRates();
+  const createOrder = useCreateOrder();
+  const applyCouponMutation = useApplyCoupon();
+
+  const hasPhysicalProduct = useMemo(
+    () => cartItems.some((item) => item.deliveryType === ProductDeliveryType.Physical),
+    [cartItems],
+  );
+  const subTotal = useMemo(
+    () => round2(cartItems.reduce((sum, item) => sum + item.price * item.quantity, 0)),
+    [cartItems],
+  );
+
+  const [currentStage, setCurrentStage] = useState<CheckoutStage>("userDetails");
+  const [guestUserData, setGuestUserData] = useState<GuestUserData | null>(null);
+  const [shippingData, setShippingData] = useState<CheckoutShippingData>();
+  const [joinEmailList, setJoinEmailList] = useState(false);
+  const [pageError, setPageError] = useState("");
+
+  // Shipping groups from the last rate fetch + the buyer's per-group selection
+  // (flat/external auto-selected; the dynamic group is the buyer's choice).
+  const [shippingGroups, setShippingGroups] = useState<ShippingGroup[]>([]);
+  const [selections, setSelections] = useState<Record<string, SelectedShippingRate>>({});
+  const selectedShippingRates = useMemo<SelectedShippingRate[]>(() => Object.values(selections), [selections]);
+  const shippingCost = useMemo(
+    () => round2(selectedShippingRates.reduce((sum, r) => sum + r.amount, 0)),
+    [selectedShippingRates],
+  );
+
+  const [couponCode, setCouponCode] = useState("");
+  const [showCouponInput, setShowCouponInput] = useState(false);
+  const [couponError, setCouponError] = useState("");
+  const [isApplyingCoupon, setIsApplyingCoupon] = useState(false);
+  const [appliedCoupon, setAppliedCoupon] = useState<AppliedCoupon | null>(null);
+  const [discountAmount, setDiscountAmount] = useState(0);
+  const [couponPaymentUpdate, setCouponPaymentUpdate] = useState<CouponPaymentUpdate | null>(null);
+  const [chargedTotal, setChargedTotal] = useState<{ amount: number; currency: string } | null>(null);
+  // Authoritative sales-tax quote for the current payment intent. A coupon
+  // re-issues the intent (and re-quotes tax), so its quote supersedes the
+  // start-payment one. Display only — the charged amount already reflects it.
+  const [couponTaxQuote, setCouponTaxQuote] = useState<PublicTaxQuote | null>(null);
+
+  const [isFreeCheckoutLoading, setIsFreeCheckoutLoading] = useState(false);
+  const [created, setCreated] = useState<CreateOrderResult | null>(null);
+  const [startError, setStartError] = useState("");
+  const startedRef = useRef(false);
+
+  const isPaidCheckout = subTotal - discountAmount + shippingCost > 0;
+
+  const selectedCountry: ShippingCountry | undefined = useMemo(
+    () => countries.find((cc) => cc.code === shippingData?.countryCode),
+    [countries, shippingData?.countryCode],
+  );
+
+  // Pick the entry stage from the buyer + cart: a logged-in buyer skips the
+  // guest-details stage; a cart with no physical item skips shipping entirely.
+  useEffect(() => {
+    if (user) {
+      setCurrentStage(hasPhysicalProduct ? "shippingAddress" : "payment");
+    } else {
+      setCurrentStage("userDetails");
+    }
+  }, [user, hasPhysicalProduct]);
+
+  // ── Order creation + payment start (lazy: only on the payment stage) ─────────
+  // Create the order once we land on the payment stage for a paid checkout, then
+  // start the payment (usePaymentFlow) against it. Guarded so it fires once.
+  useEffect(() => {
+    if (currentStage !== "payment" || !isPaidCheckout || startedRef.current) return;
+    startedRef.current = true;
+    createOrder
+      .mutateAsync({
+        amount: subTotal,
+        email: guestUserData?.email || user?.email || "",
+        firstName: guestUserData?.firstName || user?.firstName,
+        lastName: guestUserData?.lastName || user?.lastName,
+        accountId: user?.id,
+        cartItems,
+        shippingAddress: shippingData,
+        selectedShippingRates: selectedShippingRates.length ? selectedShippingRates : undefined,
+        joinEmailList: joinEmailList || undefined,
+        // Last-touch attribution: the most recent tracked-link click (≤30 days)
+        // that landed this buyer gets credit for the order.
+        attributionRefId: readAttributionRef() ?? undefined,
+        // First-touch landing snapshot (all utm/click-id params + referrer).
+        ...(readLanding() ?? {}),
+      })
+      .then(setCreated)
+      .catch((e) => setStartError(messageOf(e) || "An error occurred"));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [currentStage, isPaidCheckout]);
+
+  const returnUrl = created
+    ? `${typeof window !== "undefined" ? window.location.origin : ""}${finalisePath}?orderId=${created.orderId}`
+    : "";
+  const flow = usePaymentFlow({
+    path: "/public/orders/start-payment",
+    body: { orderId: created?.orderId },
+    returnUrl,
+    enabled: !!created?.orderId,
+  });
+
+  const orderId = created?.orderId ?? null;
+
+  // A coupon re-issues the payment intent, so its update supersedes the initial
+  // start-payment result. Otherwise use the started payment once both the order
+  // and start-payment have resolved.
+  const effectivePayment = useMemo<CouponPaymentUpdate | null>(() => {
+    if (couponPaymentUpdate) return couponPaymentUpdate;
+    if (created && flow.result?.paymentSecret && flow.result?.paymentId) {
+      return {
+        paymentSecret: flow.result.paymentSecret,
+        paymentId: flow.result.paymentId,
+        chargedAmount: flow.result.amount ?? 0,
+        chargedCurrency: flow.result.currency ?? "",
+      };
+    }
+    return null;
+  }, [created, flow.result, couponPaymentUpdate]);
+
+  // Surface the charged total (for the summary) as soon as a payment resolves.
+  useEffect(() => {
+    if (effectivePayment) setChargedTotal({ amount: effectivePayment.chargedAmount, currency: effectivePayment.chargedCurrency });
+  }, [effectivePayment]);
+
+  // The tax quote for the summary: the coupon re-quote wins over the initial
+  // start-payment quote (same supersede rule as the payment intent itself).
+  const taxQuote: PublicTaxQuote | null = couponTaxQuote ?? flow.result?.taxQuote ?? null;
+
+  // ── Stage transitions ───────────────────────────────────────────────────────
+  const submitGuest = useCallback(
+    (data: GuestUserData) => {
+      setGuestUserData(data);
+      setCurrentStage(hasPhysicalProduct ? "shippingAddress" : "payment");
+    },
+    [hasPhysicalProduct],
+  );
+
+  const submitAddress = useCallback(
+    async (data: CheckoutShippingData) => {
+      setShippingData(data);
+      setPageError("");
+      try {
+        const ratesData = await shippingRates.mutateAsync({
+          shippingAddress: data,
+          cartItems: cartItems.map((item) => ({
+            productId: item.productId,
+            productVariantId: item.productVariantId,
+            quantity: item.quantity,
+          })),
+        });
+        setShippingGroups(ratesData.groups);
+        // Auto-select the fixed groups (flat / external); the buyer chooses the
+        // dynamic (carrier) group.
+        const auto: Record<string, SelectedShippingRate> = {};
+        for (const g of ratesData.groups) {
+          if (!g.selectable && g.rates.length > 0) auto[g.id] = toSelected(g, g.rates[0]);
+        }
+        setSelections(auto);
+        setCurrentStage("shippingRates");
+      } catch (e) {
+        setPageError(messageOf(e) || "Failed to fetch shipping rates. Please check your address and try again.");
+      }
+    },
+    [cartItems, shippingRates],
+  );
+
+  /** Pick a rate for one shipping group (the dynamic/carrier group). */
+  const selectShippingRate = useCallback((group: ShippingGroup, rate: ShippingRate) => {
+    setSelections((prev) => ({ ...prev, [group.id]: toSelected(group, rate) }));
+  }, []);
+
+  const confirmRates = useCallback(() => {
+    // Every group the buyer must choose (selectable = dynamic) needs a selection.
+    const missing = shippingGroups.some((g) => g.selectable && !selections[g.id]);
+    if (missing) {
+      setPageError("Please select a shipping option before continuing.");
+      return;
+    }
+    setPageError("");
+    setCurrentStage("payment");
+  }, [shippingGroups, selections]);
+
+  // ── Coupon (applied against the created order) ──────────────────────────────
+  const applyCoupon = useCallback(async () => {
+    if (!couponCode.trim() || !orderId) return;
+    setCouponError("");
+    setIsApplyingCoupon(true);
+    try {
+      const ru = `${window.location.origin}${finalisePath}?orderId=${orderId}`;
+      const data = await applyCouponMutation.mutateAsync({ orderId, couponCode: couponCode.trim(), returnUrl: ru });
+      setAppliedCoupon(data.coupon);
+      setDiscountAmount(data.discountAmount);
+      setChargedTotal({ amount: data.chargedAmount, currency: data.chargedCurrency });
+      setCouponTaxQuote(data.taxQuote ?? null);
+      setCouponPaymentUpdate(
+        data.paymentSecret && data.paymentId
+          ? {
+              paymentSecret: data.paymentSecret,
+              paymentId: data.paymentId,
+              chargedAmount: data.chargedAmount,
+              chargedCurrency: data.chargedCurrency,
+            }
+          : null,
+      );
+    } catch (e) {
+      setCouponError(messageOf(e) || "Invalid coupon code");
+    } finally {
+      setIsApplyingCoupon(false);
+    }
+  }, [couponCode, orderId, finalisePath, applyCouponMutation]);
+
+  const removeCoupon = useCallback(async () => {
+    if (!orderId) return;
+    setCouponError("");
+    setIsApplyingCoupon(true);
+    try {
+      const ru = `${window.location.origin}${finalisePath}?orderId=${orderId}`;
+      const data = await applyCouponMutation.mutateAsync({ orderId, returnUrl: ru });
+      setAppliedCoupon(null);
+      setCouponCode("");
+      setShowCouponInput(false);
+      setDiscountAmount(0);
+      setChargedTotal({ amount: data.chargedAmount, currency: data.chargedCurrency });
+      setCouponTaxQuote(data.taxQuote ?? null);
+      if (data.paymentSecret && data.paymentId) {
+        setCouponPaymentUpdate({
+          paymentSecret: data.paymentSecret,
+          paymentId: data.paymentId,
+          chargedAmount: data.chargedAmount,
+          chargedCurrency: data.chargedCurrency,
+        });
+      }
+    } catch (e) {
+      setCouponError(messageOf(e) || "Failed to remove coupon");
+    } finally {
+      setIsApplyingCoupon(false);
+    }
+  }, [orderId, finalisePath, applyCouponMutation]);
+
+  // ── Free checkout (nothing to charge) ───────────────────────────────────────
+  /** Create the (free) order and return its id so the caller can navigate to the
+   * finalise page. Returns null on failure (with `pageError` set). */
+  const freeCheckout = useCallback(async (): Promise<string | null> => {
+    setIsFreeCheckoutLoading(true);
+    setPageError("");
+    try {
+      const data = await createOrder.mutateAsync({
+        amount: subTotal,
+        email: guestUserData?.email || user?.email || "",
+        firstName: guestUserData?.firstName || user?.firstName || "",
+        lastName: guestUserData?.lastName || user?.lastName || "",
+        accountId: user?.id,
+        cartItems,
+        shippingAddress: shippingData,
+        selectedShippingRates: selectedShippingRates.length ? selectedShippingRates : undefined,
+        couponCode: appliedCoupon?.code,
+        joinEmailList: joinEmailList || undefined,
+      });
+      return data.orderId;
+    } catch (e) {
+      setPageError(messageOf(e) || "An error occurred");
+      return null;
+    } finally {
+      setIsFreeCheckoutLoading(false);
+    }
+  }, [subTotal, guestUserData, user, cartItems, shippingData, selectedShippingRates, appliedCoupon, joinEmailList, createOrder]);
+
+  const provider = flow.provider;
+
+  return {
+    // ── Cart + totals ────────────────────────────────────────────────────────
+    cartItems,
+    isCartReady,
+    subTotal,
+    shippingCost,
+    discountAmount,
+    hasPhysicalProduct,
+    isPaidCheckout,
+    chargedTotal,
+    taxQuote,
+    // ── Stage machine ──────────────────────────────────────────────────────────
+    currentStage,
+    setCurrentStage,
+    // ── Buyer ──────────────────────────────────────────────────────────────────
+    user,
+    guestUserData,
+    joinEmailList,
+    setJoinEmailList,
+    submitGuest,
+    // ── Shipping ───────────────────────────────────────────────────────────────
+    countries,
+    selectedCountry,
+    shippingData,
+    submitAddress,
+    isFetchingRates: shippingRates.isPending,
+    shippingGroups,
+    selections,
+    selectShippingRate,
+    selectedShippingRates,
+    confirmRates,
+    // ── Order + payment ────────────────────────────────────────────────────────
+    orderId,
+    isCreatingOrder: createOrder.isPending || flow.isStarting,
+    startError,
+    provider,
+    isPaystack: provider === PaymentProviderName.Paystack,
+    paymentSecret: effectivePayment?.paymentSecret,
+    paymentId: effectivePayment?.paymentId,
+    chargedAmount: effectivePayment?.chargedAmount ?? 0,
+    chargedCurrency: effectivePayment?.chargedCurrency ?? "",
+    returnUrl: `${typeof window !== "undefined" ? window.location.origin : ""}${finalisePath}?orderId=${orderId || ""}`,
+    // ── Free checkout ──────────────────────────────────────────────────────────
+    isFreeCheckoutLoading,
+    freeCheckout,
+    // ── Coupon ─────────────────────────────────────────────────────────────────
+    couponCode,
+    setCouponCode,
+    showCouponInput,
+    setShowCouponInput,
+    appliedCoupon,
+    couponError,
+    isApplyingCoupon,
+    applyCoupon,
+    removeCoupon,
+    // ── Errors ─────────────────────────────────────────────────────────────────
+    pageError,
+    setPageError,
+  };
+}
+
+/** Narrow a group + chosen rate into the order-selection payload. */
+function toSelected(group: ShippingGroup, rate: ShippingRate): SelectedShippingRate {
+  return {
+    groupId: group.id,
+    type: group.type,
+    productIds: group.productIds,
+    rateId: rate.rateId,
+    shipmentId: rate.shipmentId,
+    amount: rate.amount,
+    currency: rate.currency,
+    carrier: rate.carrier,
+    service: rate.service,
+  };
+}

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

@@ -0,0 +1,223 @@
+import { useCallback, useState } from "react";
+import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+import { useGetCoachingProduct } from "../../../data/queries/useCoachingProducts";
+import {
+  useCoachingAvailability,
+  useReserveCoachingBooking,
+  useUpdateCoachingBooking,
+  useUnreserveCoachingBooking,
+} from "../../../data/queries/useCoachingAvailability";
+import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
+import { readAttributionRef } from "../../../utils/attribution";
+import { readLanding } from "../../../utils/landing";
+
+export type CoachingBookingStep = "slot" | "details" | "payment";
+
+/** How long a reserved slot is held before it auto-releases (client-side, matches the client app). */
+export const RESERVATION_HOLD_MS = 15 * 60 * 1000;
+
+export interface UseCoachingBookingOptions {
+  /** Stripe return URL for a PAID booking (its `return_url`). Default
+   * `/i/coaching/:slug/finalise`. A real URL is required for the redirect leg. */
+  finalisePath?: (slug: string, bookingId: string) => string;
+  /** Called when a FREE booking completes in-app — the host navigates however it
+   * wants, instead of Forge doing a `window.location` redirect. */
+  onComplete?: (info: { slug: string; bookingId: string }) => void;
+  /**
+   * Fix the availability window (ISO) and disable the built-in week navigation.
+   * Leave unset to browse availability week-by-week (the default, matches the client app).
+   */
+  fromDate?: string;
+  toDate?: string;
+}
+
+const errMessage = (e: unknown) =>
+  (e as { response?: { data?: { message?: string } } })?.response?.data?.message || "Something went wrong.";
+
+// Sunday-anchored start of the week for `d`, at 00:00 local.
+const startOfWeekSunday = (d: Date) => {
+  const x = new Date(d.getFullYear(), d.getMonth(), d.getDate());
+  x.setDate(x.getDate() - x.getDay());
+  return x;
+};
+const addDays = (d: Date, n: number) => {
+  const x = new Date(d);
+  x.setDate(x.getDate() + n);
+  return x;
+};
+const endOfDay = (d: Date) => new Date(d.getFullYear(), d.getMonth(), d.getDate(), 23, 59, 59, 999);
+
+/**
+ * Headless coaching booking: slot selection (reserve) → buyer details (update,
+ * confirms free bookings) → payment. Composes `useGetCoachingProduct`,
+ * `useCoachingAvailability`, the reserve/update/unreserve mutations and
+ * `usePaymentFlow`. Finalize via `useCoachingBookingFinalize`.
+ */
+export function useCoachingBooking(slug?: string, opts: UseCoachingBookingOptions = {}) {
+  const { user } = usePublicAuth();
+  // Detail by slug; availability + payment are scoped by the real product id
+  // (availability slots are filtered by the product's id).
+  const { data: product, isLoading } = useGetCoachingProduct(slug);
+  const productId = product?.id;
+
+  // Week navigation: browse availability one Sunday–Saturday week at a time,
+  // unless a fixed window was passed via opts. `currentWeekStart` is anchored at
+  // mount so "this week" doesn't drift while the modal is open.
+  const [currentWeekStart] = useState(() => startOfWeekSunday(new Date()));
+  const [weekStart, setWeekStart] = useState<Date>(currentWeekStart);
+  const weekEnd = addDays(weekStart, 6);
+  const canGoPrevWeek = weekStart.getTime() > currentWeekStart.getTime();
+  const goPrevWeek = () => setWeekStart((w) => (w.getTime() > currentWeekStart.getTime() ? addDays(w, -7) : w));
+  const goNextWeek = () => setWeekStart((w) => addDays(w, 7));
+
+  const windowFrom = opts.fromDate ?? weekStart.toISOString();
+  const windowTo = opts.toDate ?? endOfDay(weekEnd).toISOString();
+  const availability = useCoachingAvailability(productId, windowFrom, windowTo);
+  const reserve = useReserveCoachingBooking(productId);
+  const update = useUpdateCoachingBooking(productId);
+  const unreserve = useUnreserveCoachingBooking(productId);
+  const flow = usePaymentFlow({ path: `/public/coaching/products/${productId}/booking/start-payment`, autoStart: false });
+
+  const [step, setStep] = useState<CoachingBookingStep>("slot");
+  const [bookingId, setBookingId] = useState<string | null>(null);
+  const [selectedSlotId, setSelectedSlotId] = useState<string | null>(null);
+  const [firstName, setFirstName] = useState(user?.firstName ?? "");
+  const [lastName, setLastName] = useState(user?.lastName ?? "");
+  const [email, setEmail] = useState(user?.email ?? "");
+  const [questionnaire, setQuestionnaire] = useState<unknown>(undefined);
+  const [returnUrl, setReturnUrl] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  // Epoch ms when the current slot hold expires (null when nothing is held).
+  const [reservationExpiresAt, setReservationExpiresAt] = useState<number | null>(null);
+
+  const finalisePath =
+    opts.finalisePath ?? ((s, bId) => `/i/coaching/${s}/finalise?orderId=${bId}`);
+
+  // Highlight a slot (no server hold yet — the slot is reserved on "Continue").
+  const selectSlot = (slotId: string) => {
+    setError(null);
+    setSelectedSlotId(slotId);
+  };
+
+  const changeWeek = (dir: -1 | 1) => {
+    setSelectedSlotId(null);
+    if (dir === -1) goPrevWeek();
+    else goNextWeek();
+  };
+
+  /**
+   * Reserve the highlighted slot and advance to buyer details. On failure
+   * (e.g. the slot was just taken) it refetches availability and clears the
+   * selection so the user can pick another.
+   */
+  const reserveSelected = async () => {
+    setError(null);
+    if (!selectedSlotId) {
+      setError("Please select an available time slot.");
+      return;
+    }
+    try {
+      // Release any previously-held slot before reserving a new one.
+      if (bookingId) await unreserve.mutateAsync({ bookingId }).catch(() => undefined);
+      const data = await reserve.mutateAsync({ slotId: selectedSlotId });
+      setBookingId(data.bookingId);
+      setReservationExpiresAt(Date.now() + RESERVATION_HOLD_MS);
+      setStep("details");
+    } catch (e) {
+      setError(errMessage(e));
+      setSelectedSlotId(null);
+      availability.refetch();
+    }
+  };
+
+  /**
+   * Release the currently-held slot: unreserve the booking and clear the hold,
+   * returning to slot selection. Call this when the user leaves/closes the flow.
+   */
+  const releaseReservation = useCallback(async () => {
+    if (bookingId) await unreserve.mutateAsync({ bookingId }).catch(() => undefined);
+    setBookingId(null);
+    setSelectedSlotId(null);
+    setReservationExpiresAt(null);
+    setStep("slot");
+  }, [bookingId, unreserve]);
+
+  /** Release the hold and surface a notice — call when the reservation timer runs out. */
+  const expireReservation = useCallback(async () => {
+    await releaseReservation();
+    setError("Your reservation expired. Please pick a new time slot.");
+  }, [releaseReservation]);
+
+  const continueToPayment = async () => {
+    setError(null);
+    if (!slug || !productId || !bookingId) return;
+    if (!firstName.trim() || !lastName.trim() || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+      setError("Please enter your name and a valid email.");
+      return;
+    }
+    try {
+      const updated = await update.mutateAsync({
+        bookingId,
+        email,
+        firstName,
+        lastName,
+        confirmIfFree: true,
+        questionnaire,
+        attributionRefId: readAttributionRef() ?? undefined,
+        ...(readLanding() ?? {}),
+      });
+      const origin = typeof window !== "undefined" ? window.location.origin : "";
+      const ru = `${origin}${finalisePath(slug, bookingId)}`;
+      setReturnUrl(ru);
+      // Free bookings are confirmed by `update` — there's no payment to start
+      // (start-payment rejects a confirmed booking), so go straight to finalise.
+      if (updated.isConfirmed) {
+        if (opts.onComplete) opts.onComplete({ slug, bookingId });
+        else if (typeof window !== "undefined") window.location.href = ru;
+        return;
+      }
+      const result = await flow.start({ bookingId, returnUrl: ru });
+      if (result.provider && result.provider !== "stripe") return;
+      setStep("payment");
+    } catch (e) {
+      setError(errMessage(e));
+    }
+  };
+
+  return {
+    product,
+    isLoading,
+    availability,
+    step,
+    setStep,
+    selectedSlotId,
+    bookingId,
+    selectSlot,
+    reserveSelected,
+    reservationExpiresAt,
+    expireReservation,
+    releaseReservation,
+    // Week navigation
+    weekStart,
+    weekEnd,
+    canGoPrevWeek,
+    goPrevWeek: () => changeWeek(-1),
+    goNextWeek: () => changeWeek(1),
+    firstName,
+    setFirstName,
+    lastName,
+    setLastName,
+    email,
+    setEmail,
+    questionnaire,
+    setQuestionnaire,
+    continueToPayment,
+    clientSecret: flow.clientSecret,
+    totalAmount: flow.result?.totalAmount,
+    /** Authoritative sales-tax quote from start-payment (display only). */
+    taxQuote: flow.result?.taxQuote ?? null,
+    returnUrl,
+    isProcessing: reserve.isPending || update.isPending || flow.isStarting,
+    error,
+  };
+}

package/src/ui/headless/community/index.ts

@@ -0,0 +1,20 @@
+// Community headless primitives. NOTE: this is a lane-local aggregator — the
+// integrator re-exports it from `ui/headless/index.ts` (`export * from "./community"`).
+export {
+  buildLexicalState,
+  lexicalToPlainText,
+  mentionsInText,
+  type LexicalNodeJson,
+  type MentionRef,
+} from "./lexical";
+export { buildReplyTree, findReplyNode, type ReplyNode } from "./replyTree";
+export {
+  useCommunityAttachmentUpload,
+  MAX_COMMUNITY_ATTACHMENT_BYTES,
+  type PendingCommunityAttachment,
+} from "./useCommunityAttachmentUpload";
+export { useMentionComposer, type MentionSuggestion } from "./useMentionComposer";
+export { useRichMentionComposer, type RichCommand } from "./useRichMentionComposer";
+export { serializeRichToLexical, collectMentions, isRichEmpty } from "./richLexical";
+export { useCommunitySpaceFeed } from "./useCommunitySpaceFeed";
+export { useCommunityThread } from "./useCommunityThread";