@tribe-nest/forge 3.59.0 → 3.61.0

package/src/ui/analytics/_tests/ForgeAnalytics.meta.spec.tsx

@@ -0,0 +1,129 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, act, cleanup } from "@testing-library/react";
+
+/**
+ * The page view's Meta pair: the profile pixel's PageView and its server copy
+ * (POST /public/websites/meta-event) carry the id the first-party page view
+ * already has, so Meta keeps one. Consent loads AFTER mount, which used to
+ * mean the first page never sent a Meta PageView at all.
+ */
+
+const tracked: { eventType: string; data: Record<string, unknown> }[] = [];
+let seq = 0;
+
+vi.mock("../../../data/queries/useAnalytics", () => ({
+  newEventId: () => `evt-${++seq}`,
+  useTrackEvent: () => ({
+    track: (eventType: string, data: Record<string, unknown>) => tracked.push({ eventType, data }),
+    trackBeacon: () => {},
+    apiUrl: "https://api.test",
+    subdomain: "artist",
+  }),
+}));
+vi.mock("../../../data/queries/useWebsite", () => ({
+  useSiteConfig: () => ({ data: { metaPixelId: "999", currency: "USD" }, isLoading: false }),
+}));
+
+import { ForgeAnalytics } from "../ForgeAnalytics";
+import { resetMetaPolicy } from "../../../utils/metaEvents";
+import { saveCookieConsent, GRANT_ALL, DENY_ALL } from "../../../utils/cookieConsent";
+import { suppressProfilePixel, unsuppressProfilePixel } from "../../../utils/analyticsBus";
+
+let fetchSpy: ReturnType<typeof vi.fn>;
+let fbq: ReturnType<typeof vi.fn>;
+
+const metaPosts = () =>
+  fetchSpy.mock.calls
+    .filter((c) => String(c[0]).endsWith("/public/websites/meta-event"))
+    .map((c) => JSON.parse((c[1] as RequestInit).body as string));
+
+const flush = () => act(async () => {});
+
+beforeEach(() => {
+  tracked.length = 0;
+  seq = 0;
+  resetMetaPolicy();
+  window.localStorage.clear();
+  fetchSpy = vi.fn().mockResolvedValue({ ok: true });
+  vi.stubGlobal("fetch", fetchSpy);
+  fbq = vi.fn();
+  (window as unknown as { fbq: unknown }).fbq = fbq;
+  window.history.replaceState({}, "", "/first");
+});
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+  resetMetaPolicy();
+});
+
+describe("<ForgeAnalytics /> Meta PageView", () => {
+  it("sends the pixel PageView and its server copy with the page view's id, once consent loads", async () => {
+    saveCookieConsent(GRANT_ALL);
+    render(<ForgeAnalytics trackClicks={false} firstPartyMode="cookieless" />);
+    await flush();
+
+    const pageView = tracked.find((t) => t.eventType === "page_view");
+    expect(pageView?.data.eventId).toBe("evt-1");
+    expect(metaPosts()).toEqual([
+      {
+        subdomain: "artist",
+        pixel: "profile",
+        eventName: "PageView",
+        eventId: "evt-1",
+        eventSourceUrl: "http://localhost:3000/first",
+        metaSignals: { pageUrl: "http://localhost:3000/first", marketingConsent: true },
+      },
+    ]);
+    expect(fbq).toHaveBeenCalledWith("trackSingle", "999", "PageView", {}, { eventID: "evt-1" });
+    // One first-party page view, not a second one when consent arrived.
+    expect(tracked.filter((t) => t.eventType === "page_view")).toHaveLength(1);
+  });
+
+  it("sends a fresh pair on an SPA navigation", async () => {
+    saveCookieConsent(GRANT_ALL);
+    render(<ForgeAnalytics trackClicks={false} firstPartyMode="cookieless" />);
+    await flush();
+    act(() => window.history.pushState({}, "", "/second"));
+    await flush();
+
+    expect(metaPosts().map((b) => [b.eventId, b.eventSourceUrl])).toEqual([
+      ["evt-1", "http://localhost:3000/first"],
+      ["evt-2", "http://localhost:3000/second"],
+    ]);
+  });
+
+  it("sends no server copy where a campaign pixel took the page over", async () => {
+    saveCookieConsent(GRANT_ALL);
+    suppressProfilePixel("/first");
+    render(<ForgeAnalytics trackClicks={false} firstPartyMode="cookieless" />);
+    await flush();
+    unsuppressProfilePixel("/first");
+    expect(metaPosts()).toEqual([]);
+  });
+
+  it("sends nothing to Meta when marketing was declined", async () => {
+    saveCookieConsent(DENY_ALL);
+    render(<ForgeAnalytics trackClicks={false} firstPartyMode="cookieless" />);
+    await flush();
+    expect(metaPosts()).toEqual([]);
+    expect(tracked.filter((t) => t.eventType === "page_view")).toHaveLength(1);
+  });
+
+  it("sends a plain click first-party only", async () => {
+    saveCookieConsent(GRANT_ALL);
+    const { container } = render(
+      <>
+        <ForgeAnalytics firstPartyMode="cookieless" />
+        <button type="button">Buy</button>
+      </>,
+    );
+    await flush();
+    const before = metaPosts().length;
+    act(() => container.querySelector("button")!.click());
+    await flush();
+    expect(tracked.some((t) => t.eventType === "click")).toBe(true);
+    expect(metaPosts()).toHaveLength(before);
+  });
+});

package/src/ui/analytics/_tests/metaCommerceEvents.spec.tsx

@@ -0,0 +1,159 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { act, renderHook } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { useMetaInitiateCheckout, useMetaPurchase, useMetaViewContent } from "../useMetaEvents";
+import { resetMetaPolicy, setMetaPolicy } from "../../../utils/metaEvents";
+import { saveCookieConsent, GRANT_ALL } from "../../../utils/cookieConsent";
+import { CartProvider, useCart, type CartItem, type TicketCartItem } from "../../../contexts/CartContext";
+import { ProductDeliveryType } from "../../../types/models";
+
+/**
+ * The commerce funnel's Meta events fire once per act: a re-render, a cart
+ * that refreshes, or a confirmation page reloaded in the same tab must not
+ * count a second ViewContent, InitiateCheckout or Purchase.
+ */
+
+let fetchSpy: ReturnType<typeof vi.fn>;
+let fbq: ReturnType<typeof vi.fn>;
+
+const posted = () => fetchSpy.mock.calls.map((c) => JSON.parse((c[1] as RequestInit).body as string));
+const pixel = () => fbq.mock.calls.filter((c) => c[0] === "trackSingle");
+
+beforeEach(() => {
+  resetMetaPolicy();
+  window.localStorage.clear();
+  window.sessionStorage.clear();
+  fetchSpy = vi.fn().mockResolvedValue({ ok: true });
+  vi.stubGlobal("fetch", fetchSpy);
+  fbq = vi.fn();
+  (window as unknown as { fbq: unknown }).fbq = fbq;
+  saveCookieConsent(GRANT_ALL);
+  setMetaPolicy({
+    pixelId: "777",
+    enabled: true,
+    requireConsent: true,
+    apiUrl: "https://api.test",
+    subdomain: "artist",
+    currency: "GBP",
+    resolved: true,
+  });
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  resetMetaPolicy();
+});
+
+describe("InitiateCheckout", () => {
+  const line = { productId: "p1", quantity: 2 };
+
+  it("fires once per mount, after the cart is ready and not empty", () => {
+    const { rerender } = renderHook((props: Parameters<typeof useMetaInitiateCheckout>[0]) => useMetaInitiateCheckout(props), {
+      initialProps: { ready: false, cartItems: [], ticketItems: [], subTotal: 0 } as Parameters<typeof useMetaInitiateCheckout>[0],
+    });
+    expect(posted()).toEqual([]);
+
+    rerender({ ready: true, cartItems: [line], ticketItems: [{ eventId: "e1", tickets: { t1: 3 } }], subTotal: 80 });
+    rerender({ ready: true, cartItems: [line], ticketItems: [], subTotal: 50 });
+
+    expect(posted()).toHaveLength(1);
+    expect(posted()[0]).toMatchObject({
+      pixel: "profile",
+      eventName: "InitiateCheckout",
+      customData: { value: 80, currency: "GBP", num_items: 5, content_ids: ["p1", "e1"], content_type: "product" },
+    });
+    expect(pixel()[0][4]).toEqual({ eventID: posted()[0].eventId });
+  });
+
+  it("does not fire for an empty cart", () => {
+    renderHook(() => useMetaInitiateCheckout({ ready: true, cartItems: [], ticketItems: [], subTotal: 0 }));
+    expect(posted()).toEqual([]);
+  });
+});
+
+describe("Purchase", () => {
+  it("fires once with the record id, and not again after a reload", () => {
+    const props = { recordId: "order-9", paid: true, value: 30, currency: "usd" };
+    const first = renderHook(() => useMetaPurchase(props));
+    first.rerender();
+    first.unmount();
+    // A reload: a fresh mount in the same tab.
+    renderHook(() => useMetaPurchase(props));
+
+    expect(pixel()).toEqual([["trackSingle", "777", "Purchase", { value: 30, currency: "USD" }, { eventID: "order-9" }]]);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("waits for the record to be paid", () => {
+    const { rerender } = renderHook((p: { paid: boolean }) => useMetaPurchase({ recordId: "order-10", value: 30, ...p }), {
+      initialProps: { paid: false },
+    });
+    expect(pixel()).toEqual([]);
+    rerender({ paid: true });
+    expect(pixel()).toHaveLength(1);
+  });
+});
+
+describe("ViewContent", () => {
+  it("fires once per entity and again for a different one", () => {
+    const { rerender } = renderHook((e: { id: string; name: string; value: number }) => useMetaViewContent(e), {
+      initialProps: { id: "c1", name: "Course", value: 99 },
+    });
+    rerender({ id: "c1", name: "Course", value: 99 });
+    rerender({ id: "c2", name: "Other", value: 10 });
+
+    expect(posted().map((b) => [b.eventName, b.customData])).toEqual([
+      ["ViewContent", { content_ids: ["c1"], content_name: "Course", content_type: "product", value: 99, currency: "GBP" }],
+      ["ViewContent", { content_ids: ["c2"], content_name: "Other", content_type: "product", value: 10, currency: "GBP" }],
+    ]);
+  });
+});
+
+describe("AddToCart", () => {
+  const wrapper = ({ children }: { children: ReactNode }) => <CartProvider>{children}</CartProvider>;
+  const item: CartItem = {
+    productId: "prod-1",
+    productVariantId: "var-1",
+    title: "Tour Tee",
+    price: 25,
+    isGift: false,
+    canIncreaseQuantity: true,
+    quantity: 2,
+    payWhatYouWant: false,
+    deliveryType: ProductDeliveryType.Physical,
+  };
+
+  it("fires for a new line and not for a duplicate", () => {
+    const { result } = renderHook(() => useCart(), { wrapper });
+    act(() => void result.current.addToCart(item));
+    act(() => void result.current.addToCart(item));
+
+    expect(posted().map((b) => [b.eventName, b.customData])).toEqual([
+      [
+        "AddToCart",
+        { content_ids: ["prod-1"], content_name: "Tour Tee", content_type: "product", value: 50, num_items: 2, currency: "GBP" },
+      ],
+    ]);
+  });
+
+  it("fires for tickets only when the selection grows", () => {
+    const { result } = renderHook(() => useCart(), { wrapper });
+    const selection = (qty: number): TicketCartItem => ({
+      eventId: "event-1",
+      eventSlug: "tour",
+      eventTitle: "Spring Tour",
+      tickets: { ga: qty },
+      ticketMeta: { ga: { title: "GA", price: 15 } },
+    });
+    act(() => result.current.setTickets(selection(2)));
+    act(() => result.current.setTickets(selection(1)));
+    act(() => result.current.setTickets(selection(3)));
+
+    expect(posted().map((b) => [b.customData.num_items, b.customData.value])).toEqual([
+      [2, 30],
+      [2, 30],
+    ]);
+    expect(posted()[0].customData.content_ids).toEqual(["event-1"]);
+  });
+});

package/src/ui/analytics/useMetaEvents.ts

@@ -0,0 +1,78 @@
+import { useEffect, useRef } from "react";
+import { trackMeta, trackPurchase } from "../../utils/metaEvents";
+
+export type MetaViewContentInput = {
+  id: string;
+  name?: string;
+  /** The lowest (or selected) price, major units. Ignored unless a finite number. */
+  value?: number | string | null;
+};
+
+/**
+ * Fire `ViewContent` once per loaded entity: a new id (navigating to another
+ * product) fires again, a re-render does not. Pass `null` while loading.
+ */
+export function useMetaViewContent(entity: MetaViewContentInput | null | undefined): void {
+  const firedFor = useRef<string | null>(null);
+  const id = entity?.id;
+  const name = entity?.name;
+  const value = entity?.value;
+  useEffect(() => {
+    if (!id || firedFor.current === id) return;
+    firedFor.current = id;
+    const n = value === null || value === undefined || value === "" ? NaN : Number(value);
+    trackMeta("ViewContent", {
+      content_ids: [id],
+      content_name: name,
+      content_type: "product",
+      value: Number.isFinite(n) ? n : undefined,
+    });
+  }, [id, name, value]);
+}
+
+/**
+ * Fire `InitiateCheckout` once per mount, as soon as the saved cart has loaded
+ * and holds something. Value is the cart's own estimate, before shipping and
+ * coupons.
+ */
+export function useMetaInitiateCheckout(input: {
+  ready: boolean;
+  cartItems: { productId: string; quantity: number }[];
+  ticketItems: { eventId: string; tickets: Record<string, number> }[];
+  subTotal: number;
+}): void {
+  const fired = useRef(false);
+  const { ready, cartItems, ticketItems, subTotal } = input;
+  const hasLines = cartItems.length > 0 || ticketItems.length > 0;
+  useEffect(() => {
+    if (fired.current || !ready || !hasLines) return;
+    fired.current = true;
+    const numItems =
+      cartItems.reduce((sum, item) => sum + (item.quantity || 0), 0) +
+      ticketItems.reduce((sum, t) => sum + Object.values(t.tickets).reduce((a, b) => a + b, 0), 0);
+    trackMeta("InitiateCheckout", {
+      value: subTotal,
+      num_items: numItems,
+      content_ids: [...cartItems.map((item) => item.productId), ...ticketItems.map((t) => t.eventId)],
+      content_type: "product",
+    });
+  }, [ready, hasLines, cartItems, ticketItems, subTotal]);
+}
+
+/**
+ * Fire the browser copy of `Purchase` on a confirmation page once the record
+ * is paid. The id is the record id the server bridge used, so the two dedupe;
+ * a reload in the same tab does not fire it again.
+ */
+export function useMetaPurchase(input: {
+  recordId?: string | null;
+  paid: boolean;
+  value?: number | string | null;
+  currency?: string | null;
+}): void {
+  const { recordId, paid, value, currency } = input;
+  useEffect(() => {
+    if (!paid || !recordId) return;
+    trackPurchase({ recordId, value, currency });
+  }, [paid, recordId, value, currency]);
+}

package/src/ui/format/_tests/membershipGate.spec.ts

@@ -72,7 +72,7 @@ describe("parseMembershipGateError", () => {
     });
   });
 
-  it("matches on CODE, not on status — a read refusal is 401/403, a checkout refusal 400", () => {
+  it("matches on CODE, not on status: a read refusal is 401/403, a checkout refusal 400", () => {
     // Nothing here reads a status at all; the same payload parses whichever
     // status carried it. A client switching on 401 would render this as a
     // session timeout.
@@ -113,7 +113,7 @@ describe("joinTierNames", () => {
     expect(joinTierNames(["Gold", "Silver", "Bronze"])).toBe("Gold, Silver or Bronze");
   });
 
-  it("drops blanks — an unresolved tier must not become an empty slot", () => {
+  it("drops blanks: an unresolved tier must not become an empty slot", () => {
     expect(joinTierNames(["", "  ", "Gold"])).toBe("Gold");
     expect(joinTierNames([])).toBe("");
   });
@@ -160,18 +160,18 @@ describe("buildMembershipGateNotice", () => {
     expect(notice!.body).toBe("This ticket is for Gold members. Already one? Sign in and it unlocks.");
   });
 
-  it("offers the TIER to someone already signed in — never sign-in again", () => {
+  it("offers the TIER to someone already signed in: never sign-in again", () => {
     const notice = buildMembershipGateNotice({
       gate: gate({ reason: "membership_required", requiredTierIds: ["gold", "plat"] }),
       tierNames: ["Gold", "Platinum"],
       itemLabel: "This course",
-      membershipPath: "/i/membership",
+      membershipPath: "/i/communities/fan-club?tier=gold",
     });
 
     expect(notice).toMatchObject({
       reason: "membership_required",
       actionLabel: "View Gold or Platinum",
-      actionHref: "/i/membership",
+      actionHref: "/i/communities/fan-club?tier=gold",
     });
     expect(notice!.body).toBe("This course is for Gold or Platinum members. Your current plan doesn't include it.");
     // Telling a signed-in member to sign in is a loop with no exit.
@@ -214,7 +214,7 @@ describe("buildMembershipGateNotice", () => {
   });
 
   it("uses default paths when the host names none", () => {
-    expect(buildMembershipGateNotice({ gate: gate() })!.actionHref).toBe("/membership");
+    expect(buildMembershipGateNotice({ gate: gate() })!.actionHref).toBe("/i/communities");
     expect(buildMembershipGateNotice({ gate: gate({ reason: "sign_in_required" }) })!.actionHref).toBe("/login");
   });
 });

package/src/ui/format/membershipGate.ts

@@ -8,22 +8,22 @@ import type { MembershipGateReason, PublicMembershipGate } from "../../types/mod
  *
  * The gate shipped ENFORCED and UNANNOUNCED. A logged-out buyer saw an ordinary
  * ticket, chose a seat, typed their name and their email twice, and was refused
- * on the last screen with a `MEMBERSHIP_GATE` 400 — the restriction was
+ * on the last screen with a `MEMBERSHIP_GATE` 400: the restriction was
  * discoverable only by failing it. And the "members save X, sign in" funnel the
  * feature was justified by existed on no surface at all, because nothing drew a
  * way OUT of the refusal.
  *
  * ## Why it is pure, and why it lives in `format/`
  *
- * There are two rendering stacks — `apps/client` and the Forge SDK that code
- * websites build against — and a members-only badge that says one thing on an
+ * There are two rendering stacks (`apps/client` and the Forge SDK that code
+ * websites build against), and a members-only badge that says one thing on an
  * artist's PWA and another on their website is the same bug twice. So the words
  * and the resolving ACTION are decided once, here, with no React and no client;
  * each stack owns only how it looks. `apps/client` imports this from
  * `@tribe-nest/forge/ui`, exactly as it already does for the PWYW arithmetic.
  *
  * Pure and total also means the whole mapping is testable without a DOM or a
- * session — and getting the two reasons backwards is the failure mode that
+ * session, and getting the two reasons backwards is the failure mode that
  * matters most: telling someone who is already signed in to "sign in" is a loop
  * with no exit, and telling a logged-out visitor to "upgrade" asks them to buy a
  * membership they may already hold.
@@ -94,7 +94,7 @@ export function parseMembershipGateError(error: unknown): MembershipGateRefusal
 /**
  * Is this thing refused to the caller looking at it?
  *
- * `null` means "nothing gates it" — which is also what every read returns while
+ * `null` means "nothing gates it", which is also what every read returns while
  * the `membership_entitlement_gates` switch is off. Treating an absent gate as
  * "gated and permitted" would badge every item on every site the day the field
  * shipped, so absent must read as false here and nowhere else.
@@ -110,7 +110,7 @@ export type MembershipGateNotice = {
   badge: string;
   title: string;
   body: string;
-  /** Primary CTA label — the way OUT of the refusal, which is the whole point. */
+  /** Primary CTA label: the way OUT of the refusal, which is the whole point. */
   actionLabel: string;
   /**
    * Where the CTA goes. `null` only when the caller passed no path to send them
@@ -120,12 +120,16 @@ export type MembershipGateNotice = {
   actionHref: string | null;
 };
 
-/** Default sign-in path. Overridden per site — code websites mount theirs under `/i`. */
+/** Default sign-in path. Overridden per site: code websites mount theirs under `/i`. */
 export const MEMBERSHIP_GATE_LOGIN_PATH = "/login";
-/** Default tier-listing path, i.e. where "become a member" actually leads. */
-export const MEMBERSHIP_GATE_MEMBERSHIP_PATH = "/membership";
+/**
+ * Default "become a member" path when the tier's community is not known: the
+ * communities list. `useMembershipGateNotice` sends the buyer to the About page
+ * of the community the required tier belongs to, with that tier preselected.
+ */
+export const MEMBERSHIP_GATE_MEMBERSHIP_PATH = "/i/communities";
 
-/** "Gold", "Gold or Platinum", "Gold, Silver or Bronze" — ANY one unlocks, hence "or". */
+/** "Gold", "Gold or Platinum", "Gold, Silver or Bronze". ANY one unlocks, hence "or". */
 export function joinTierNames(names: string[]): string {
   const clean = names.map((name) => name.trim()).filter(Boolean);
   if (clean.length === 0) return "";
@@ -133,7 +137,7 @@ export function joinTierNames(names: string[]): string {
   return `${clean.slice(0, -1).join(", ")} or ${clean[clean.length - 1]}`;
 }
 
-/** `path?redirect=<here>` — a sign-in that lands back on the thing they wanted. */
+/** `path?redirect=<here>`: a sign-in that lands back on the thing they wanted. */
 export function membershipSignInHref(loginPath: string, currentPath: string): string {
   const target = safeRedirectPath(currentPath, "");
   return target ? `${loginPath}?redirect=${encodeURIComponent(target)}` : loginPath;
@@ -142,7 +146,7 @@ export function membershipSignInHref(loginPath: string, currentPath: string): st
 export interface BuildMembershipGateNoticeInput {
   /** The announced gate from a listing/detail read. */
   gate?: PublicMembershipGate | null;
-  /** A `MEMBERSHIP_GATE` refusal from a failed purchase. Wins over `gate` — it is the newer fact. */
+  /** A `MEMBERSHIP_GATE` refusal from a failed purchase. Wins over `gate`: it is the newer fact. */
   refusal?: MembershipGateRefusal | null;
   /**
    * Names for `requiredTierIds`, already resolved by the caller (both stacks
@@ -150,7 +154,7 @@ export interface BuildMembershipGateNoticeInput {
    * 8f3c-…" is not a sentence anyone can act on.
    */
   tierNames?: string[];
-  /** What the thing IS, in the buyer's words — "This ticket", "This course". */
+  /** What the thing IS, in the buyer's words: "This ticket", "This course". */
   itemLabel?: string;
   loginPath?: string;
   membershipPath?: string;
@@ -185,7 +189,7 @@ export function buildMembershipGateNotice(
       // The API's own sentence is deliberately NOT used for this half. It is
       // written for the refusal ("You must be a member to buy this"), and what
       // an anonymous visitor needs first is the possibility that they already
-      // are one — which is the difference between a dead end and a funnel.
+      // are one, which is the difference between a dead end and a funnel.
       body: tiers
         ? `${item} is for ${tiers} members. Already one? Sign in and it unlocks.`
         : `${item} is for members. Already one? Sign in and it unlocks.`,
@@ -201,7 +205,7 @@ export function buildMembershipGateNotice(
     body: tiers
       ? `${item} is for ${tiers} members. Your current plan doesn't include it.`
       : `${item} is for members. Your current plan doesn't include it.`,
-    // NOT "sign in" — they already are, and offering it again is a loop with no
+    // NOT "sign in": they already are, and offering it again is a loop with no
     // exit. The only move that changes anything is joining the tier.
     actionLabel: tiers ? `View ${tiers}` : "View membership",
     actionHref: membershipPath,