@tribe-nest/forge 3.26.0 → 3.29.0

package/package.json

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

package/src/client/_tests/localeHeader.spec.tsx

@@ -0,0 +1,98 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+import type { AxiosRequestConfig } from "axios";
+import { createForgeClient } from "../createForgeClient";
+import { getSiteLocale, setSiteLocale } from "../activeLocale";
+import { SiteConfigProvider } from "../../provider/SiteConfigProvider";
+import type { SiteConfig } from "../../data/queries/useWebsite";
+
+/**
+ * The last link in the chain that lets a German site be German all the way down:
+ * the tenant's locale rides every API request as `x-locale`, which the backend
+ * reads into its request store and answers in.
+ *
+ * The failure this guards against is quiet. Nothing errors when the header is
+ * missing: the page renders German, the API answers English, and the only
+ * person who notices is the visitor who gets told "Product not found" on an
+ * otherwise German checkout.
+ */
+
+// Captures the outgoing config without a network round trip. The request
+// interceptor has already run by the time the adapter is called, so whatever
+// lands here is exactly what would have gone over the wire.
+function clientCapturingHeaders() {
+  const sent: AxiosRequestConfig[] = [];
+  const client = createForgeClient({ baseURL: "https://api.example.test" });
+  client.defaults.adapter = async (config) => {
+    sent.push(config);
+    return { data: {}, status: 200, statusText: "OK", headers: {}, config } as never;
+  };
+  return { client, sent };
+}
+
+describe("x-locale on every Forge request", () => {
+  beforeEach(() => {
+    setSiteLocale(null);
+  });
+
+  it("sends nothing before any site config has been seen", async () => {
+    const { client, sent } = clientCapturingHeaders();
+    await client.get("/public/products");
+    expect(sent[0].headers?.["x-locale"]).toBeUndefined();
+  });
+
+  it("sends the tenant's locale once it is known", async () => {
+    setSiteLocale("de");
+    const { client, sent } = clientCapturingHeaders();
+    await client.get("/public/products");
+    expect(sent[0].headers?.["x-locale"]).toBe("de");
+  });
+
+  // The locale is read per request rather than captured when the client is
+  // built: the client is created once, before any site config exists.
+  it("picks up a locale set after the client was created", async () => {
+    const { client, sent } = clientCapturingHeaders();
+    await client.get("/public/products");
+    setSiteLocale("de");
+    await client.get("/public/products");
+    expect(sent[0].headers?.["x-locale"]).toBeUndefined();
+    expect(sent[1].headers?.["x-locale"]).toBe("de");
+  });
+
+  it("leaves the other tenant headers alone", async () => {
+    setSiteLocale("de");
+    const { client, sent } = clientCapturingHeaders();
+    await client.get("/public/products");
+    expect(sent[0].headers?.["x-timezone-offset"]).toBeDefined();
+  });
+});
+
+describe("the site config publishes the locale to the client", () => {
+  beforeEach(() => {
+    setSiteLocale(null);
+  });
+
+  // Mounted by every site through TribeNestApp, which is what makes the header
+  // arrive on a Forge upgrade alone, with no edit to a tenant's __root.tsx.
+  it("SiteConfigProvider sets it during render, before any child can fetch", () => {
+    renderToStaticMarkup(
+      <SiteConfigProvider initialConfig={{ locale: "de" } as SiteConfig}>
+        <span>{getSiteLocale()}</span>
+      </SiteConfigProvider>,
+    );
+    expect(getSiteLocale()).toBe("de");
+  });
+
+  // An older backend returns a config with no `locale` at all, and a failed SSR
+  // bootstrap returns no config. Both mean English, which is what an absent
+  // header already gets.
+  it("clears the locale when the config carries none", () => {
+    setSiteLocale("de");
+    renderToStaticMarkup(
+      <SiteConfigProvider initialConfig={{} as SiteConfig}>
+        <span />
+      </SiteConfigProvider>,
+    );
+    expect(getSiteLocale()).toBeNull();
+  });
+});

package/src/client/activeLocale.ts

@@ -0,0 +1,34 @@
+// The language the site is being served in, held outside React so the shared
+// axios client can read it.
+//
+// Why this exists: without it a German site renders German and every error the
+// API returns arrives in English, which is the failure the visitor sees rather
+// than the one the creator configured. The backend already reads an `x-locale`
+// header into its request store (`LOCALE_HEADER_KEY`), so the whole fix is
+// getting the tenant's locale onto every request.
+//
+// Why a module singleton rather than a prop threaded to `createForgeClient`:
+// the client is created once, per `apiUrl`, before any site config is known,
+// and the locale arrives later with the site config. The same reasoning as
+// `activeFunnel` applies too: put it in the transport and no call site can
+// forget it.
+//
+// Scope: one locale at a time. One deploy serves one tenant, so on the server
+// every request writes the same value, and a creator changing the setting is
+// picked up on the next SSR render.
+
+let siteLocale: string | null = null;
+
+/**
+ * Set the language every subsequent API request declares. Called with
+ * `siteConfig.locale` where the config enters the tree, so an existing site
+ * gains the header from a Forge upgrade with no edit to its `__root.tsx`.
+ */
+export function setSiteLocale(locale: string | null | undefined): void {
+  siteLocale = locale || null;
+}
+
+/** The active site locale, or null before any site config has been seen. */
+export function getSiteLocale(): string | null {
+  return siteLocale;
+}

package/src/client/createForgeClient.ts

@@ -1,5 +1,6 @@
 import axios, { type AxiosError, type AxiosInstance } from "axios";
 import { getActiveFunnelId } from "./activeFunnel";
+import { getSiteLocale } from "./activeLocale";
 
 /**
  * Access-token refresh (backend §7 cutover). Access tokens live ~15 minutes;
@@ -69,6 +70,18 @@ export const createForgeClient = ({
       config.headers["x-funnel-id"] = funnelId;
     }
 
+    // The tenant's language, so the API answers in the language the page is
+    // written in. Without it a German site renders German and every validation
+    // message, error and generated string comes back English. The backend reads
+    // this header into its request store, so it covers everything a request
+    // touches rather than the endpoints someone remembered to translate.
+    // Absent until the site config has been seen, and the backend defaults to
+    // English on an absent or unrecognised value.
+    const locale = getSiteLocale();
+    if (locale) {
+      config.headers["x-locale"] = locale;
+    }
+
     const token = getToken?.();
     if (token) {
       config.headers["authorization"] = `Bearer ${token}`;

package/src/contexts/CartContext.tsx

@@ -106,6 +106,35 @@ interface CartContextType {
   addToCart: (item: CartItem) => boolean;
   removeFromCart: (productId: string, isGift: boolean, recipientEmail?: string) => void;
   clearCart: () => void;
+  /**
+   * Put a whole basket back at once, MERGING with whatever is already there.
+   *
+   * Built for the recovery link (`/i/checkout/resume`), where the buyer arrives
+   * from an email with lines the server has just re-priced. It exists rather
+   * than a loop over `addToCart` for two reasons, both of which produced wrong
+   * baskets when tried:
+   *
+   * - `addToCart` reads `cartItems` from its closure, so a loop decides
+   *   "already in the cart?" against a snapshot that is one render old. A
+   *   restored line matching one the visitor already had appended a DUPLICATE
+   *   instead of replacing it. This merges inside a functional update, so every
+   *   line is matched against the real current state.
+   * - Restoring must not pop the drawer open per line. The resume page IS the
+   *   surface; a drawer sliding over it is noise.
+   *
+   * MERGE, not replace: a visitor who put something in their basket between the
+   * email and the click keeps it. The restored line wins on a collision,
+   * because it is the one that was just re-priced.
+   *
+   * Tickets merge PER TIER, not per event. An event's selection is a map, and
+   * treating it as one value threw away every tier the visitor had picked in
+   * this session the moment the resumed basket named the same event. On a tier
+   * both sides name, the restored quantity REPLACES the session's rather than
+   * adding to it, matching how a colliding product line is replaced whole: both
+   * sides describe the same intent at different prices, and the resumed one is
+   * the figure the server has just re-checked.
+   */
+  restoreCart: (input: { items?: CartItem[]; tickets?: TicketCartItem[] }) => void;
   /** Ticket selections, one entry per event. */
   ticketItems: TicketCartItem[];
   /** Add or replace the selection for an event (the modal always sends the whole map). */
@@ -232,6 +261,52 @@ export function CartProvider({ children }: { children: ReactNode }) {
     );
   };
 
+  /** The identity of a product line, as `addToCart` already defines it. */
+  const lineKey = (item: CartItem) =>
+    `${item.productId}|${item.productVariantId}|${item.isGift}|${item.recipientEmail ?? ""}`;
+
+  const restoreCart = useCallback((input: { items?: CartItem[]; tickets?: TicketCartItem[] }) => {
+    const items = input.items ?? [];
+    const tickets = input.tickets ?? [];
+
+    if (items.length > 0) {
+      setCartItems((prev) => {
+        const incoming = new Map(items.map((item) => [lineKey(item), item]));
+        const merged = prev.map((item) => incoming.get(lineKey(item)) ?? item);
+        const seen = new Set(prev.map(lineKey));
+        return [...merged, ...items.filter((item) => !seen.has(lineKey(item)))];
+      });
+    }
+
+    if (tickets.length > 0) {
+      setTicketItems((prev) => {
+        const byEvent = new Map(prev.map((ticket) => [ticket.eventId, ticket]));
+        for (const incoming of tickets) {
+          const existing = byEvent.get(incoming.eventId);
+          byEvent.set(
+            incoming.eventId,
+            existing
+              ? {
+                  ...existing,
+                  ...incoming,
+                  // Tier by tier, so a tier only the session knows about
+                  // survives and a tier both name takes the resumed quantity.
+                  tickets: { ...existing.tickets, ...incoming.tickets },
+                  ticketMeta: { ...existing.ticketMeta, ...incoming.ticketMeta },
+                  // A resumed payload predating booking fees carries none, and
+                  // an absent fee must not erase the one the modal captured.
+                  bookingFee: incoming.bookingFee ?? existing.bookingFee ?? null,
+                }
+              : incoming,
+          );
+        }
+        // Insertion order: the events already in the basket keep their place,
+        // and events only the recovery link knows about go on the end.
+        return [...byEvent.values()];
+      });
+    }
+  }, []);
+
   const setTickets = useCallback((item: TicketCartItem) => {
     setTicketItems((prev) => [...prev.filter((t) => t.eventId !== item.eventId), item]);
     setCartOpen(true);
@@ -275,6 +350,7 @@ export function CartProvider({ children }: { children: ReactNode }) {
         addToCart,
         removeFromCart,
         clearCart,
+        restoreCart,
         ticketItems,
         setTickets,
         removeTickets,

package/src/contexts/_tests/CartContext.spec.tsx

@@ -0,0 +1,210 @@
+// @vitest-environment jsdom
+import { describe, it, expect, beforeEach } from "vitest";
+import { act, renderHook } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { CartProvider, useCart, type CartItem, type TicketCartItem } from "../CartContext";
+import { ProductDeliveryType } from "../../types/models";
+
+/**
+ * `restoreCart`, the one entry point that writes the WHOLE basket at once.
+ *
+ * It exists for the recovery link, and it is the only cart mutation that runs
+ * without the visitor pressing anything: they click a link in an email and the
+ * basket changes underneath them. So the thing worth asserting is not that the
+ * restored lines arrive, it is that nothing the visitor put in the basket
+ * THEMSELVES leaves while that happens. A restore that quietly drops a tier is
+ * indistinguishable, to the buyer, from a shop that lost their basket twice.
+ *
+ * jsdom rather than `renderToStaticMarkup`, because a provider that hydrates in
+ * a mount effect and persists in another has no behaviour at all without
+ * effects and without `localStorage`.
+ */
+
+const wrapper = ({ children }: { children: ReactNode }) => <CartProvider>{children}</CartProvider>;
+
+const item = (overrides: Partial<CartItem> = {}): CartItem => ({
+  productId: "prod-1",
+  productVariantId: "var-1",
+  title: "Tour Tee",
+  price: 25,
+  isGift: false,
+  canIncreaseQuantity: true,
+  quantity: 1,
+  payWhatYouWant: false,
+  deliveryType: ProductDeliveryType.Physical,
+  ...overrides,
+});
+
+const selection = (overrides: Partial<TicketCartItem> = {}): TicketCartItem => ({
+  eventId: "event-1",
+  eventSlug: "spring-tour",
+  eventTitle: "Spring Tour",
+  tickets: { "tier-ga": 1 },
+  ticketMeta: { "tier-ga": { title: "General Admission", price: 25 } },
+  bookingFee: null,
+  ...overrides,
+});
+
+const mount = () => renderHook(() => useCart(), { wrapper });
+
+beforeEach(() => {
+  localStorage.clear();
+});
+
+describe("restoreCart: tickets", () => {
+  it("REGRESSION: keeps a tier the visitor picked in this session when the same event is restored", () => {
+    // The defect this replaces overwrote the event's whole selection, so a
+    // visitor holding two tiers who clicked a recovery email for one of them
+    // was left with one. Nothing on the page said so and the total simply
+    // shrank.
+    const { result } = mount();
+
+    act(() => {
+      result.current.setTickets(
+        selection({
+          tickets: { "tier-ga": 2, "tier-vip": 1 },
+          ticketMeta: {
+            "tier-ga": { title: "General Admission", price: 25 },
+            "tier-vip": { title: "VIP", price: 80 },
+          },
+        }),
+      );
+    });
+
+    act(() => {
+      result.current.restoreCart({
+        tickets: [
+          selection({
+            tickets: { "tier-early": 3 },
+            ticketMeta: { "tier-early": { title: "Early bird", price: 15 } },
+          }),
+        ],
+      });
+    });
+
+    expect(result.current.ticketItems).toHaveLength(1);
+    expect(result.current.ticketItems[0].tickets).toEqual({
+      "tier-ga": 2,
+      "tier-vip": 1,
+      "tier-early": 3,
+    });
+    expect(Object.keys(result.current.ticketItems[0].ticketMeta).sort()).toEqual([
+      "tier-early",
+      "tier-ga",
+      "tier-vip",
+    ]);
+    // The badge counts every unit, so a lost tier is visible there too.
+    expect(result.current.itemCount).toBe(6);
+  });
+
+  it("takes the restored quantity on a tier both sides name, rather than adding to it", () => {
+    // Both sides describe the same intent. Summing would hand the buyer five
+    // tickets they never asked for, and the resumed figure is the one the
+    // server has just re-checked, so it wins outright.
+    const { result } = mount();
+
+    act(() => result.current.setTickets(selection({ tickets: { "tier-ga": 3 } })));
+    act(() => result.current.restoreCart({ tickets: [selection({ tickets: { "tier-ga": 2 } })] }));
+
+    expect(result.current.ticketItems[0].tickets).toEqual({ "tier-ga": 2 });
+  });
+
+  it("takes the restored display data for a tier both sides name", () => {
+    const { result } = mount();
+
+    act(() => result.current.setTickets(selection()));
+    act(() =>
+      result.current.restoreCart({
+        tickets: [selection({ ticketMeta: { "tier-ga": { title: "General Admission", price: 30 } } })],
+      }),
+    );
+
+    expect(result.current.ticketItems[0].ticketMeta["tier-ga"]).toEqual({
+      title: "General Admission",
+      price: 30,
+    });
+  });
+
+  it("does not erase a captured booking fee when the resumed payload carries none", () => {
+    // A payload saved before booking fees existed answers `null`, and the fee
+    // the modal captured is what the cart shows the buyer they will pay.
+    const fee = { feeAmount: 1.5, feeBps: 250, currency: "USD", minorUnitFactor: 100 };
+    const { result } = mount();
+
+    act(() => result.current.setTickets(selection({ bookingFee: fee })));
+    act(() => result.current.restoreCart({ tickets: [selection({ bookingFee: null })] }));
+
+    expect(result.current.ticketItems[0].bookingFee).toEqual(fee);
+  });
+
+  it("leaves an event the recovery link says nothing about alone, and appends a new one", () => {
+    const { result } = mount();
+
+    act(() => result.current.setTickets(selection({ eventId: "event-9", eventTitle: "Autumn" })));
+    act(() => result.current.restoreCart({ tickets: [selection({ eventId: "event-1" })] }));
+
+    expect(result.current.ticketItems.map((t) => t.eventId)).toEqual(["event-9", "event-1"]);
+  });
+});
+
+describe("restoreCart: products", () => {
+  it("replaces a matching line rather than appending a duplicate of it", () => {
+    const { result } = mount();
+
+    act(() => void result.current.addToCart(item({ quantity: 1, price: 25 })));
+    act(() => result.current.restoreCart({ items: [item({ quantity: 3, price: 30 })] }));
+
+    expect(result.current.cartItems).toHaveLength(1);
+    expect(result.current.cartItems[0]).toMatchObject({ quantity: 3, price: 30 });
+  });
+
+  it("keeps a line the recovery link does not name", () => {
+    const { result } = mount();
+
+    act(() => void result.current.addToCart(item({ productId: "prod-9", productVariantId: "var-9" })));
+    act(() => result.current.restoreCart({ items: [item()] }));
+
+    expect(result.current.cartItems.map((i) => i.productId)).toEqual(["prod-9", "prod-1"]);
+  });
+
+  it("treats a gift to a different recipient as its own line", () => {
+    // The line identity `addToCart` already uses. Collapsing these would send
+    // one of two presents.
+    const { result } = mount();
+
+    act(() => void result.current.addToCart(item({ isGift: true, recipientEmail: "ada@test.com" })));
+    act(() =>
+      result.current.restoreCart({ items: [item({ isGift: true, recipientEmail: "grace@test.com" })] }),
+    );
+
+    expect(result.current.cartItems).toHaveLength(2);
+  });
+
+  it("does not open the drawer, because the resume page IS the surface", () => {
+    const { result } = mount();
+    act(() => result.current.restoreCart({ items: [item()], tickets: [selection()] }));
+    expect(result.current.isCartOpen).toBe(false);
+  });
+});
+
+describe("removeTickets", () => {
+  it("takes every add-on attached to the event with it", () => {
+    // The server refuses a bundle whose add-on has no base, so an orphan left
+    // behind here is a checkout that fails with nothing on screen saying why.
+    const { result } = mount();
+
+    act(() => {
+      result.current.restoreCart({
+        items: [
+          item({ attachedTo: { type: "event", entityId: "event-1" } }),
+          item({ productId: "prod-2", productVariantId: "var-2" }),
+        ],
+        tickets: [selection()],
+      });
+    });
+    act(() => result.current.removeTickets("event-1"));
+
+    expect(result.current.ticketItems).toEqual([]);
+    expect(result.current.cartItems.map((i) => i.productId)).toEqual(["prod-2"]);
+  });
+});

package/src/data/queries/useCheckouts.ts

@@ -2,6 +2,7 @@ import { useMutation } from "@tanstack/react-query";
 import { useForge } from "../../provider/ForgeProvider";
 import { bundleCouponRequestBody } from "../../ui/headless/checkout/bundleCoupon";
 import type { CartItem, TicketCartItem } from "../../contexts/CartContext";
+import type { IBookingFee, ProductDeliveryType } from "../../types/models";
 
 /** One line of a bundle, in the shape `POST /public/checkouts` expects. */
 export type CheckoutLineInput =
@@ -201,3 +202,85 @@ export function useFinalizeCheckout() {
     },
   });
 }
+
+// ── The recovery link ─────────────────────────────────────────────────────────
+
+/** Why a resumed line cannot go back in the basket. `null` when it can. */
+export type ResumeLineUnavailableReason = "removed" | "unavailable" | "sold_out";
+
+export type ResumeLineOption = { axis: string; value: string; swatchHex: string | null };
+
+/**
+ * One line of an abandoned basket, as `POST /public/checkouts/resume` answers.
+ *
+ * Every line comes back, including the ones that cannot be bought: the server
+ * re-reads the catalogue and reports WHY rather than shrinking the basket
+ * behind the buyer's back. `price` is today's figure in MAJOR units;
+ * `quotedUnitPriceCents` is what they were quoted when they left, in minor
+ * units, and is display-only.
+ */
+export type ResumeLine = {
+  type: "product" | "event_ticket" | "course" | "coaching";
+  quantity: number;
+  title: string;
+  coverImage: string | null;
+  price: number;
+  unitPriceCents: number;
+  quotedUnitPriceCents: number | null;
+  priceChanged: boolean;
+  available: boolean;
+  unavailableReason: ResumeLineUnavailableReason | null;
+  productId?: string;
+  productVariantId?: string;
+  deliveryType?: ProductDeliveryType;
+  payWhatYouWant?: boolean;
+  options?: ResumeLineOption[];
+  isGift?: boolean;
+  recipientName?: string | null;
+  recipientEmail?: string | null;
+  recipientMessage?: string | null;
+  attachedTo?: { type: "event"; entityId: string } | null;
+  eventId?: string;
+  ticketId?: string;
+  eventSlug?: string;
+  eventTitle?: string;
+  pwywAmount?: number | null;
+  bookingFee?: IBookingFee | null;
+  courseId?: string;
+  courseSlug?: string;
+  coachingProductId?: string;
+  coachingProductSlug?: string;
+};
+
+export type ResumedCheckout = {
+  checkoutId: string;
+  profileId: string;
+  source: "product" | "checkout" | "event" | "course" | "coaching" | "membership";
+  currency: string;
+  buyer: { firstName: string | null; lastName: string | null; email: string | null };
+  /** A code to re-apply at checkout, never an amount. */
+  couponCode: string | null;
+  lines: ResumeLine[];
+  /** Units across AVAILABLE lines only. */
+  itemCount: number;
+  /** Minor units, AVAILABLE lines only, at today's prices and before discount. */
+  subtotalCents: number;
+};
+
+/**
+ * Exchange a recovery-email token for the basket it names.
+ *
+ * A POST rather than a GET so the token stays out of access logs and `Referer`
+ * headers on the API hop. Anonymous by design: the recipient is usually a guest
+ * who never had an account, and the token IS the credential.
+ */
+export function useResumeCheckout() {
+  const { client, profileId } = useForge();
+
+  return useMutation<ResumedCheckout, unknown, { token: string }>({
+    mutationFn: async ({ token }) => {
+      const res = await client.post("/public/checkouts/resume", { profileId, token });
+      return res.data;
+    },
+  });
+}

package/src/data/queries/useWebsite.ts

@@ -7,6 +7,13 @@ export interface SiteConfig {
   /** The tenant's settlement currency (e.g. "USD") — the currency API amounts
    * are in and payments are charged in. */
   currency: string;
+  /** The language the tenant speaks ("en" | "de" today), from
+   * `profile_configurations.locale`. Runtime, like `currency`: Forge renders its
+   * own copy in it, the site puts it on `<html lang>`, and the axios client sends
+   * it as `x-locale` so API messages arrive in the same language. Optional here
+   * because a site pinned to an older backend gets no such field, and every
+   * reader falls back to English. */
+  locale?: string;
   /** Sales-tax display mode: true = listing prices already contain tax
    * ("incl. VAT" style, EU/UK), false/absent = tax added at checkout (US).
    * Display-only — checkout totals come from the authoritative taxQuote. */