@tribe-nest/forge 3.26.0 → 3.31.0

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

@@ -0,0 +1,340 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCart, type CartItem, type TicketCartItem } from "../../../contexts/CartContext";
+import { useResumeCheckout, type ResumeLine, type ResumedCheckout } from "../../../data/queries/useCheckouts";
+import { rememberResumedCoupon } from "./resumedCoupon";
+import { ProductDeliveryType } from "../../../types/models";
+
+/**
+ * The landing behaviour of a cart-recovery link, shared by both storefronts.
+ *
+ * `apps/client` and a Forge code website draw this page completely differently
+ * (Tailwind against `themeSettings` on one, inline styles against the Forge
+ * theme on the other) and they must not decide DIFFERENTLY what a resumed
+ * basket does. So the exchange, the restore and the arithmetic live here once
+ * and each stack owns only how it looks, exactly as `ticketAvailability` and
+ * `useClaimPassTransfer` already do.
+ *
+ * ## What lands in the basket, and what does not
+ *
+ * Only the lines the server says can still be bought. Every OTHER line is
+ * still returned to the caller in `unavailableLines`, because the two failure
+ * modes here are asymmetric and both are bad:
+ *
+ * - Silently dropping a line is the worst outcome. The buyer came back for the
+ *   thing they left, the basket is quietly one item lighter, and they find out
+ *   after paying (or never).
+ * - Restoring a line nobody will sell them is the second worst. They reach the
+ *   payment screen and are refused, which reads as a broken shop.
+ *
+ * Showing it, greyed out, with the reason next to it is neither.
+ *
+ * ## An add-on never lands without the ticket it hangs off
+ *
+ * A product line carrying `attachedTo` was added from an event's add-on block
+ * and is only sellable next to that event's own ticket line. If the ticket
+ * cannot be restored (sold out, withdrawn) the add-on cannot either: the server
+ * refuses a bundle whose add-on has no base, so restoring it alone builds a
+ * basket that fails at the payment screen with nothing on the page saying why.
+ *
+ * The base has to come from THIS payload, not from whatever is in the basket
+ * already. The buckets below are derived from the server answer alone, so they
+ * cannot change under the page once the restore has run.
+ *
+ * Those add-ons come back in `droppedLines` rather than disappearing, for the
+ * same reason unavailable lines do: a basket that is quietly one item lighter
+ * is the worst of the outcomes above.
+ *
+ * ## Courses and coaching are not basket items
+ *
+ * The cart holds products and event tickets. A course or a coaching session is
+ * bought through its own page, so those lines come back as `continueLines`:
+ * nothing is restored and the caller draws a link back to the page where the
+ * purchase resumes. Reporting them as "restored" would be a lie, and dropping
+ * them would strand the only recovery path those two pillars have.
+ */
+
+// Re-exported so a caller reaches the whole vocabulary from `forge/ui` without
+// also importing the data layer.
+export type {
+  ResumeLine,
+  ResumedCheckout,
+  ResumeLineOption,
+  ResumeLineUnavailableReason,
+} from "../../../data/queries/useCheckouts";
+
+export type CartResumeStatus = "loading" | "restored" | "empty" | "error";
+
+export type UseCartResumeOptions = {
+  /** The `?token=` from the recovery link. Absent or blank means an invalid link. */
+  token?: string | null;
+  /**
+   * Put the basket back as soon as the exchange answers. On by default: the
+   * point of the link is that the buyer arrives with a full basket, not with a
+   * button that promises one.
+   */
+  autoRestore?: boolean;
+};
+
+export type UseCartResumeResult = {
+  status: CartResumeStatus;
+  /** The whole server answer, for a caller that wants a field this hook does not surface. */
+  resumed: ResumedCheckout | null;
+  /** Lines that went back in the basket. */
+  restoredLines: ResumeLine[];
+  /** Lines that could not, each with its `unavailableReason`. Draw these. */
+  unavailableLines: ResumeLine[];
+  /**
+   * Add-ons the shop would still sell, left out because the event ticket they
+   * hang off was not restored. Draw these too: they were in the basket the
+   * buyer left, and they are not in the one they got back.
+   */
+  droppedLines: ResumeLine[];
+  /** Course and coaching lines: not basket items, link the buyer onward. */
+  continueLines: ResumeLine[];
+  /** Restored lines whose price moved while the buyer was away. */
+  repricedLines: ResumeLine[];
+  /** Units restored. */
+  itemCount: number;
+  /** Minor units, restored lines only, at today's prices and before discount. */
+  subtotalCents: number;
+  currency: string;
+  /** A code to re-apply, already stashed for the checkout page. Display it. */
+  couponCode: string | null;
+  /** Set when the link itself failed (missing, expired, another artist's). */
+  error: string | null;
+  /** Restore by hand. A no-op once the basket has been restored. */
+  restore: () => void;
+};
+
+/**
+ * A resumed product line as the cart stores it.
+ *
+ * Exported so the translation can be tested without a DOM: every field here is
+ * one the checkout later branches on, and getting `deliveryType` wrong ships an
+ * order with nowhere to send it.
+ */
+export function resumeLineToCartItem(line: ResumeLine): CartItem | null {
+  if (!line.productId || !line.productVariantId) return null;
+  return {
+    productId: line.productId,
+    productVariantId: line.productVariantId,
+    title: line.title,
+    price: line.price,
+    coverImage: line.coverImage ?? undefined,
+    isGift: !!line.isGift,
+    recipientName: line.recipientName ?? undefined,
+    recipientEmail: line.recipientEmail ?? undefined,
+    recipientMessage: line.recipientMessage ?? undefined,
+    /**
+     * The buyer chose this quantity once; restoring it as 1 would make them
+     * re-count. `canIncreaseQuantity` follows the ordinary shop default so the
+     * cart's stepper behaves as it does for any other line.
+     */
+    quantity: line.quantity,
+    canIncreaseQuantity: true,
+    payWhatYouWant: !!line.payWhatYouWant,
+    options: line.options ?? undefined,
+    /**
+     * Never guessed. Checkout reads shipping-or-not off this field, and a
+     * physical line restored as non-physical means an order arrives with
+     * nowhere to send it. The server always sends it for a line it declared
+     * available; `Digital` here would be a bug upstream, not a default.
+     */
+    deliveryType: line.deliveryType ?? ProductDeliveryType.Digital,
+    attachedTo: line.attachedTo ?? undefined,
+  };
+}
+
+/** Ticket lines regrouped into the per-event shape the cart holds. */
+export function resumeLinesToTicketItems(lines: ResumeLine[]): TicketCartItem[] {
+  const byEvent = new Map<string, TicketCartItem>();
+  for (const line of lines) {
+    if (!line.eventId || !line.ticketId) continue;
+    const existing = byEvent.get(line.eventId) ?? {
+      eventId: line.eventId,
+      eventSlug: line.eventSlug ?? "",
+      eventTitle: line.eventTitle ?? line.title,
+      coverImage: line.coverImage ?? undefined,
+      tickets: {},
+      ticketMeta: {},
+      bookingFee: line.bookingFee ?? null,
+    };
+    existing.tickets[line.ticketId] = (existing.tickets[line.ticketId] ?? 0) + line.quantity;
+    existing.ticketMeta[line.ticketId] = {
+      title: line.title,
+      // On a pay-what-you-want tier the buyer's own amount is what the cart
+      // shows and what the bundle charges, so it wins over the tier's floor.
+      price: line.pwywAmount ?? line.price,
+      ...(line.pwywAmount != null ? { pwywAmount: line.pwywAmount } : {}),
+    };
+    byEvent.set(line.eventId, existing);
+  }
+  return [...byEvent.values()];
+}
+
+const CONTINUE_TYPES = new Set(["course", "coaching"]);
+
+/** The four buckets a resumed payload splits into. */
+export type ResumePartition = {
+  restoredLines: ResumeLine[];
+  unavailableLines: ResumeLine[];
+  continueLines: ResumeLine[];
+  droppedLines: ResumeLine[];
+};
+
+/**
+ * Split the server's lines into what goes back in the basket and what only gets
+ * drawn. Pure, and exported, because this is the decision the whole page rests
+ * on and it must be assertable without a DOM.
+ *
+ * The subtle bucket is `droppedLines`. An add-on is only sellable next to its
+ * base, so a base that is not itself being restored takes the add-on with it.
+ * "Being restored" is checked against the fields `resumeLinesToTicketItems`
+ * actually needs (`eventId` and `ticketId`), so a ticket line that function
+ * would skip does not count as a base either.
+ */
+export function partitionResumeLines(lines: ResumeLine[]): ResumePartition {
+  const unavailableLines = lines.filter((line) => !line.available);
+  const available = lines.filter((line) => line.available);
+  const continueLines = available.filter((line) => CONTINUE_TYPES.has(line.type));
+  const restorable = available.filter((line) => !CONTINUE_TYPES.has(line.type));
+
+  const baseEventIds = new Set(
+    restorable
+      .filter((line) => line.type === "event_ticket" && line.eventId && line.ticketId)
+      .map((line) => line.eventId as string),
+  );
+  const isOrphanedAddon = (line: ResumeLine) =>
+    line.type === "product" &&
+    line.attachedTo?.type === "event" &&
+    !baseEventIds.has(line.attachedTo.entityId);
+
+  return {
+    restoredLines: restorable.filter((line) => !isOrphanedAddon(line)),
+    unavailableLines,
+    continueLines,
+    droppedLines: restorable.filter(isOrphanedAddon),
+  };
+}
+
+/** What this line will actually cost per unit, in minor units. */
+export function effectiveUnitCents(line: ResumeLine): number {
+  return line.pwywAmount != null ? Math.round(line.pwywAmount * 100) : line.unitPriceCents;
+}
+
+export function useCartResume(options: UseCartResumeOptions): UseCartResumeResult {
+  const { token, autoRestore = true } = options;
+  const { restoreCart, isReady } = useCart();
+  const { mutateAsync } = useResumeCheckout();
+
+  const [resumed, setResumed] = useState<ResumedCheckout | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [restored, setRestored] = useState(false);
+  /**
+   * One exchange per token. The endpoint stamps the arrival that cart-recovery
+   * attributes on, so firing it twice is not merely wasteful, and StrictMode
+   * runs every effect twice in development.
+   */
+  const requestedFor = useRef<string | null>(null);
+
+  useEffect(() => {
+    const value = (token ?? "").trim();
+    if (!value) {
+      setError("missing_token");
+      return;
+    }
+    if (requestedFor.current === value) return;
+    requestedFor.current = value;
+
+    let cancelled = false;
+    void mutateAsync({ token: value })
+      .then((data) => {
+        if (cancelled) return;
+        setResumed(data);
+        setError(null);
+        // Stashed even when the caller does not auto-restore, so the code
+        // survives the walk from this page to checkout either way.
+        rememberResumedCoupon(data.couponCode);
+      })
+      .catch((err: unknown) => {
+        if (cancelled) return;
+        setError(
+          (err as { response?: { data?: { message?: string } } })?.response?.data?.message ?? "invalid_link",
+        );
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [token, mutateAsync]);
+
+  const { restoredLines, unavailableLines, continueLines, droppedLines } = useMemo(
+    () => partitionResumeLines(resumed?.lines ?? []),
+    [resumed],
+  );
+
+  const repricedLines = useMemo(
+    () => restoredLines.filter((line) => line.priceChanged),
+    [restoredLines],
+  );
+
+  const restore = useCallback(() => {
+    /**
+     * `isReady` is not belt and braces. `CartProvider` hydrates from
+     * localStorage in a mount effect and that effect REPLACES the whole list,
+     * so anything written before it lands is thrown away. The network round
+     * trip makes that practically impossible, and "practically impossible"
+     * silent data loss is the kind that surfaces once, on somebody's phone, and
+     * is never reproduced.
+     */
+    if (!isReady || restored || restoredLines.length === 0) return;
+    restoreCart({
+      items: restoredLines
+        .filter((line) => line.type === "product")
+        .map(resumeLineToCartItem)
+        .filter((item): item is CartItem => item !== null),
+      tickets: resumeLinesToTicketItems(restoredLines.filter((line) => line.type === "event_ticket")),
+    });
+    setRestored(true);
+    /**
+     * `isReady` belongs here. Without it the callback keeps the `false` it
+     * closed over on the first render, React hands the same stale function back
+     * on every later one, and the effect below never re-runs once hydration
+     * finishes: the guard stops being a wait and becomes a permanent refusal on
+     * exactly the slow load it was written for.
+     */
+  }, [isReady, restored, restoredLines, restoreCart]);
+
+  useEffect(() => {
+    if (autoRestore) restore();
+  }, [autoRestore, restore]);
+
+  const status: CartResumeStatus = error
+    ? "error"
+    : !resumed
+      ? "loading"
+      : restoredLines.length === 0 && continueLines.length === 0
+        ? "empty"
+        : "restored";
+
+  return {
+    status,
+    resumed,
+    restoredLines,
+    unavailableLines,
+    continueLines,
+    droppedLines,
+    repricedLines,
+    itemCount: restoredLines.reduce((sum, line) => sum + line.quantity, 0),
+    // The figure the CART will show, so a pay-what-you-want tier counts the
+    // buyer's own amount rather than the tier's floor.
+    subtotalCents: restoredLines.reduce(
+      (sum, line) => sum + effectiveUnitCents(line) * line.quantity,
+      0,
+    ),
+    currency: resumed?.currency ?? "USD",
+    couponCode: resumed?.couponCode ?? null,
+    error,
+    restore,
+  };
+}

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

@@ -20,6 +20,7 @@ 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";
@@ -191,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);

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

@@ -18,7 +18,7 @@ import {
 import { holdExpiredMessage, isHoldExpiredError } from "../checkout/inventoryHold";
 import { useInventoryHold } from "../checkout/useInventoryHold";
 import { computeBookingFeeAmount } from "../../format/bookingFee";
-import { isPayWhatYouWant, pwywDefaultAmount, resolveUnitPrice, ticketSubtotals } from "../../format/pwyw";
+import { checkoutAmounts, isPayWhatYouWant, resolveUnitPrice, ticketSubtotals } from "../../format/pwyw";
 import { parseMembershipGateError, type MembershipGateRefusal } from "../../format/membershipGate";
 import { readAttributionRef } from "../../../utils/attribution";
 import { readLanding } from "../../../utils/landing";
@@ -151,18 +151,13 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
    * they have not. This is what gets SENT, so an untouched box is not the same
    * as choosing the minimum: the suggestion is the default offer.
    */
-  const effectiveAmounts = useMemo(() => {
-    if (!event) return {} as Record<string, number>;
-    const out: Record<string, number> = {};
-    for (const ticket of event.tickets) {
-      if (!isPayWhatYouWant(ticket) || (selectedTickets[ticket.id] ?? 0) <= 0) continue;
-      out[ticket.id] =
-        pwywAmounts[ticket.id] != null
-          ? resolveUnitPrice(ticket, pwywAmounts[ticket.id])
-          : pwywDefaultAmount(ticket);
-    }
-    return out;
-  }, [event, selectedTickets, pwywAmounts]);
+  const effectiveAmounts = useMemo(
+    () =>
+      event
+        ? checkoutAmounts({ tickets: event.tickets, quantities: selectedTickets, chosen: pwywAmounts })
+        : ({} as Record<string, number>),
+    [event, selectedTickets, pwywAmounts],
+  );
 
   /**
    * `paid` is what the buyer owes for tickets; `floor` is the same cart valued

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,
@@ -81,6 +99,20 @@ export {
 export { useInvoicePayment, type UseInvoicePaymentOptions } from "./invoice/useInvoicePayment";
 export { usePaymentLinkPayment, type UsePaymentLinkPaymentOptions } from "./paymentLink/usePaymentLinkPayment";
 export { useBroadcastWatch } from "./broadcast/useBroadcastWatch";
+export {
+  broadcastListStatus,
+  broadcastSessionKey,
+  hasBroadcastEnded,
+  isPassValidated,
+  minTicketPrice,
+  needsPassValidation,
+  selectBroadcastScreen,
+  type BroadcastListStatus,
+  type BroadcastListStatusText,
+  type BroadcastScreen,
+  type BroadcastScreenInput,
+  type BroadcastView,
+} from "./broadcast/broadcastState";
 export { useChatRoom } from "./chat/useChatRoom";
 export { useMessageThread, type UseMessageThreadResult } from "./chat/useMessageThread";
 export { useChatAttachmentUpload, type PendingAttachment } from "./chat/useChatAttachmentUpload";