@tribe-nest/forge 3.59.0 → 3.61.0

package/src/utils/_tests/metaEvents.spec.ts

@@ -0,0 +1,264 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import {
+  firePixelOnly,
+  fireServerMetaEvent,
+  readMetaSignals,
+  resetMetaPolicy,
+  sendPageMetaEvent,
+  setMetaPolicy,
+  trackMeta,
+  trackPurchase,
+  type MetaPolicy,
+} from "../metaEvents";
+import { saveCookieConsent, GRANT_ALL, DENY_ALL } from "../cookieConsent";
+
+/**
+ * The browser half of Meta conversion tracking. Every event is a PAIR (pixel
+ * + server copy) under one id, so Meta counts it once; and nothing about the
+ * visitor's Meta identity (`fbp` / `fbc`) is read or sent without marketing
+ * consent.
+ */
+
+const POLICY: MetaPolicy = {
+  pixelId: "123456",
+  enabled: true,
+  requireConsent: true,
+  apiUrl: "https://api.test/",
+  subdomain: "artist",
+  currency: "eur",
+  resolved: true,
+};
+
+let fbq: ReturnType<typeof vi.fn>;
+let fetchSpy: ReturnType<typeof vi.fn>;
+
+function clearCookies() {
+  for (const name of ["_fbp", "_fbc"]) document.cookie = `${name}=; path=/; max-age=0`;
+}
+
+function postedBodies(): Record<string, unknown>[] {
+  return fetchSpy.mock.calls.map((call) => JSON.parse((call[1] as RequestInit).body as string));
+}
+
+function pixelCalls(): unknown[][] {
+  return fbq.mock.calls.filter((c) => c[0] === "trackSingle");
+}
+
+beforeEach(() => {
+  resetMetaPolicy();
+  window.localStorage.clear();
+  window.sessionStorage.clear();
+  clearCookies();
+  fbq = vi.fn();
+  (window as unknown as { fbq: unknown }).fbq = fbq;
+  fetchSpy = vi.fn().mockResolvedValue({ ok: true });
+  vi.stubGlobal("fetch", fetchSpy);
+  window.history.replaceState({}, "", "/shop");
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  resetMetaPolicy();
+});
+
+describe("readMetaSignals", () => {
+  it("sends the _fbc cookie when it exists", () => {
+    saveCookieConsent(GRANT_ALL);
+    setMetaPolicy(POLICY);
+    document.cookie = "_fbp=fb.1.111.222; path=/";
+    document.cookie = "_fbc=fb.1.333.cookieclick; path=/";
+    window.localStorage.setItem(
+      "tn:landing",
+      JSON.stringify({ landingUtm: { fbclid: "landingclick" }, referrer: "", landingUrl: "x", at: Date.now() }),
+    );
+
+    expect(readMetaSignals()).toEqual({
+      pageUrl: "http://localhost:3000/shop",
+      marketingConsent: true,
+      fbp: "fb.1.111.222",
+      fbc: "fb.1.333.cookieclick",
+    });
+  });
+
+  it("builds fbc from the landing fbclid and its capture time when the cookie is missing", () => {
+    saveCookieConsent(GRANT_ALL);
+    setMetaPolicy(POLICY);
+    const at = Date.now() - 60_000;
+    window.localStorage.setItem(
+      "tn:landing",
+      JSON.stringify({ landingUtm: { fbclid: "AbC123" }, referrer: "", landingUrl: "x", at }),
+    );
+
+    expect(readMetaSignals().fbc).toBe(`fb.1.${at}.AbC123`);
+  });
+
+  it("sends no fbp or fbc when marketing was declined, and says so", () => {
+    saveCookieConsent(DENY_ALL);
+    setMetaPolicy(POLICY);
+    document.cookie = "_fbp=fb.1.111.222; path=/";
+    document.cookie = "_fbc=fb.1.333.cookieclick; path=/";
+    window.localStorage.setItem(
+      "tn:landing",
+      JSON.stringify({ landingUtm: { fbclid: "AbC123" }, referrer: "", landingUrl: "x", at: Date.now() }),
+    );
+
+    expect(readMetaSignals()).toEqual({ pageUrl: "http://localhost:3000/shop", marketingConsent: false });
+  });
+
+  it("leaves marketingConsent out while the visitor has not decided", () => {
+    setMetaPolicy(POLICY);
+    document.cookie = "_fbp=fb.1.111.222; path=/";
+    expect(readMetaSignals()).toEqual({ pageUrl: "http://localhost:3000/shop" });
+  });
+
+  it("is true without a decision when the site does not require consent", () => {
+    setMetaPolicy({ ...POLICY, requireConsent: false });
+    document.cookie = "_fbp=fb.1.111.222; path=/";
+    expect(readMetaSignals()).toMatchObject({ marketingConsent: true, fbp: "fb.1.111.222" });
+  });
+});
+
+describe("trackMeta", () => {
+  it("fires the pixel and posts the server copy under the SAME event id", () => {
+    saveCookieConsent(GRANT_ALL);
+    setMetaPolicy(POLICY);
+    document.cookie = "_fbp=fb.1.111.222; path=/";
+
+    const id = trackMeta("AddToCart", { content_ids: ["p1"], value: 12.5 });
+
+    expect(pixelCalls()).toEqual([
+      ["trackSingle", "123456", "AddToCart", { content_ids: ["p1"], value: 12.5, currency: "EUR" }, { eventID: id }],
+    ]);
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    expect(fetchSpy.mock.calls[0][0]).toBe("https://api.test/public/websites/meta-event");
+    expect((fetchSpy.mock.calls[0][1] as RequestInit).keepalive).toBe(true);
+    expect(postedBodies()[0]).toEqual({
+      subdomain: "artist",
+      pixel: "profile",
+      eventName: "AddToCart",
+      eventId: id,
+      eventSourceUrl: "http://localhost:3000/shop",
+      customData: { content_ids: ["p1"], value: 12.5, currency: "EUR" },
+      metaSignals: { pageUrl: "http://localhost:3000/shop", marketingConsent: true, fbp: "fb.1.111.222" },
+    });
+  });
+
+  it("uses the event id it is given", () => {
+    saveCookieConsent(GRANT_ALL);
+    setMetaPolicy(POLICY);
+    expect(trackMeta("PageView", undefined, { eventId: "pv-1" })).toBe("pv-1");
+    expect(postedBodies()[0]).toMatchObject({ eventId: "pv-1", eventName: "PageView" });
+    expect(postedBodies()[0].customData).toBeUndefined();
+  });
+
+  it("does nothing without marketing consent", () => {
+    saveCookieConsent(DENY_ALL);
+    setMetaPolicy(POLICY);
+    trackMeta("ViewContent", { content_ids: ["p1"] });
+    expect(pixelCalls()).toEqual([]);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("does nothing while the visitor has not decided", () => {
+    setMetaPolicy(POLICY);
+    trackMeta("ViewContent", { content_ids: ["p1"] });
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("does nothing when the profile has no pixel", () => {
+    saveCookieConsent(GRANT_ALL);
+    setMetaPolicy({ ...POLICY, pixelId: undefined });
+    trackMeta("ViewContent", { content_ids: ["p1"] });
+    expect(pixelCalls()).toEqual([]);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("does nothing when disabled (editor / preview)", () => {
+    saveCookieConsent(GRANT_ALL);
+    setMetaPolicy({ ...POLICY, enabled: false });
+    trackMeta("ViewContent", { content_ids: ["p1"] });
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("waits for the pixel id, then sends what was fired before it resolved", () => {
+    saveCookieConsent(GRANT_ALL);
+    trackMeta("ViewContent", { content_ids: ["p1"] }, { eventId: "vc-1" });
+    expect(fetchSpy).not.toHaveBeenCalled();
+
+    setMetaPolicy({ ...POLICY, pixelId: undefined, resolved: false });
+    expect(fetchSpy).not.toHaveBeenCalled();
+
+    setMetaPolicy(POLICY);
+    expect(postedBodies()).toEqual([expect.objectContaining({ eventId: "vc-1", eventName: "ViewContent" })]);
+    expect(pixelCalls()).toHaveLength(1);
+  });
+});
+
+describe("server-originated events", () => {
+  it("firePixelOnly fires the pixel and posts nothing", () => {
+    saveCookieConsent(GRANT_ALL);
+    setMetaPolicy(POLICY);
+    firePixelOnly("Lead", "sub-1", { content_name: "Contact" });
+    expect(pixelCalls()).toEqual([["trackSingle", "123456", "Lead", { content_name: "Contact" }, { eventID: "sub-1" }]]);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("fireServerMetaEvent reads a response's metaEvent and ignores a response without one", () => {
+    saveCookieConsent(GRANT_ALL);
+    setMetaPolicy(POLICY);
+    fireServerMetaEvent({ id: "x" });
+    fireServerMetaEvent(undefined);
+    fireServerMetaEvent({ metaEvent: { name: "Schedule", eventId: "booking-1" } });
+    expect(pixelCalls()).toEqual([["trackSingle", "123456", "Schedule", {}, { eventID: "booking-1" }]]);
+  });
+});
+
+describe("sendPageMetaEvent", () => {
+  it("posts the page-pixel server copy with the pathname", () => {
+    setMetaPolicy(POLICY);
+    sendPageMetaEvent({ eventName: "Lead", eventId: "click-1", pathname: "/l/song", customData: { content_name: "Spotify" } });
+    expect(postedBodies()[0]).toMatchObject({
+      pixel: "page",
+      pathname: "/l/song",
+      eventName: "Lead",
+      eventId: "click-1",
+      customData: { content_name: "Spotify" },
+    });
+  });
+});
+
+describe("trackPurchase", () => {
+  beforeEach(() => {
+    saveCookieConsent(GRANT_ALL);
+    setMetaPolicy(POLICY);
+  });
+
+  it("fires once per record id, with the record id as the event id", () => {
+    trackPurchase({ recordId: "order-1", value: "49.90", currency: "usd" });
+    trackPurchase({ recordId: "order-1", value: "49.90", currency: "usd" });
+    expect(pixelCalls()).toEqual([
+      ["trackSingle", "123456", "Purchase", { value: 49.9, currency: "USD" }, { eventID: "order-1" }],
+    ]);
+    expect(window.sessionStorage.getItem("tn:meta:purchase:order-1")).toBe("1");
+    // Purchase's server copy is the payment bridge's; the browser posts none.
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("falls back to the site currency", () => {
+    trackPurchase({ recordId: "booking-1", value: 20 });
+    expect(pixelCalls()[0][3]).toEqual({ value: 20, currency: "EUR" });
+  });
+
+  it("fires nothing for a free record", () => {
+    trackPurchase({ recordId: "order-2", value: 0, currency: "usd" });
+    expect(pixelCalls()).toEqual([]);
+  });
+
+  it("does not mark a purchase fired when consent blocked it, so it can fire later", () => {
+    saveCookieConsent(DENY_ALL);
+    trackPurchase({ recordId: "order-3", value: 10 });
+    expect(pixelCalls()).toEqual([]);
+    expect(window.sessionStorage.getItem("tn:meta:purchase:order-3")).toBeNull();
+  });
+});

package/src/utils/_tests/safeRedirect.spec.ts

@@ -72,11 +72,11 @@ describe("safeRedirectPath (C13)", () => {
   describe("keeps legitimate in-app destinations", () => {
     it.each([
       "/i/account",
-      "/i/members",
+      "/i/communities",
       "/i/courses/123",
       "/i/checkout?step=2",
       "/i/orders?status=paid&page=3",
-      "/i/members#section",
+      "/i/communities#section",
       "/",
       // A path that merely CONTAINS a scheme-looking segment is still a path.
       "/i/redirect?to=https%3A%2F%2Fexample.com",

package/src/utils/landing.ts

@@ -2,9 +2,9 @@
 //
 // The FIRST time a visitor lands on the artist's site we snapshot the full
 // query-param bag (every `utm_*`, ad click-id like `fbclid`/`gclid`/`ttclid`,
-// and any other param — verbatim) plus `document.referrer` and the landing
+// and any other param, verbatim) plus `document.referrer` and the landing
 // URL. Checkout reads it back and sends `landingUtm` + `referrer` with every
-// purchase, so later attribution/ROAS can tie a sale to the ad that drove it —
+// purchase, so later attribution/ROAS can tie a sale to the ad that drove it,
 // regardless of whether the ad was created on TribeNest or elsewhere.
 //
 // First-touch wins with a 30-day TTL: the very first landing is preserved for
@@ -23,7 +23,7 @@ export type LandingSnapshot = {
   landingUrl: string;
   /** Capture timestamp (ms) for the TTL check. */
   at: number;
-  /** Stable per-visitor session id — dedupes repeat beacons server-side. */
+  /** Stable per-visitor session id; dedupes repeat beacons server-side. */
   sessionId?: string;
 };
 
@@ -70,7 +70,7 @@ function readSnapshot(): LandingSnapshot | null {
 
 /**
  * Snapshots the current URL's params + referrer into localStorage on the
- * FIRST landing only (idempotent — safe to call on every render). Does NOT
+ * FIRST landing only (idempotent, safe to call on every render). Does NOT
  * strip the params from the URL: the page's own ad pixels / analytics may
  * still need them. Returns true when a fresh snapshot was written.
  */
@@ -97,7 +97,7 @@ export function captureLandingFromUrl(): boolean {
     window.localStorage.setItem(STORAGE_KEY, JSON.stringify(snapshot));
     return true;
   } catch {
-    // Quota / disabled storage — quietly drop. The purchase still succeeds,
+    // Quota / disabled storage: quietly drop. The purchase still succeeds,
     // only the landing attribution is lost.
     return false;
   }
@@ -121,7 +121,7 @@ export function readLanding(): { landingUtm?: Record<string, string>; referrer?:
 /**
  * Fire-and-forget POST of the stored first-touch snapshot to the visit-level
  * landing beacon. Records a landing_session server-side even when the visitor
- * never buys — powering per-campaign visit counts + external click-id matching.
+ * never buys, powering per-campaign visit counts + external click-id matching.
  * Call ONCE on fresh capture (when captureLandingFromUrl returned true), so a
  * visit is counted a single time within the 30-day window.
  */
@@ -151,3 +151,16 @@ export function postLandingBeacon(apiUrl: string, profileId: string, attribution
     // Beacon is best-effort; never disrupt the page.
   }
 }
+
+/**
+ * One click id from the stored first-touch landing, with the moment it was
+ * captured (ms). Meta's `fbc` is `fb.1.<capture ms>.<fbclid>`, so the time is
+ * part of the value, not a detail. Null when nothing is stored, it expired, or
+ * the first landing carried no such param.
+ */
+export function readLandingClickId(param: string): { value: string; at: number } | null {
+  const snapshot = readSnapshot();
+  const value = snapshot?.landingUtm[param];
+  if (!snapshot || !value) return null;
+  return { value, at: snapshot.at };
+}

package/src/utils/metaEvents.ts

@@ -0,0 +1,302 @@
+// Meta conversion events from the browser: one call fires the profile pixel
+// AND posts the server (CAPI) copy, both carrying the same event id, so Meta
+// counts the pair once. Nothing here can send one half without the other.
+//
+// The policy (which pixel, whether Meta may run, where the API is) is set by
+// `<ForgeAnalytics/>` and read synchronously, so non-React code (the cart, a
+// mutation) can fire an event without threading props or context through.
+//
+// Consent is read LIVE from the consent store at send time. Without marketing
+// consent on a site that requires it, nothing is fired, posted, built or read:
+// no pixel call, no server copy, no `fbp` / `fbc`.
+
+import { newEventId } from "../data/queries/useAnalytics";
+import { getCookieConsent } from "./cookieConsent";
+import { readLandingClickId } from "./landing";
+import { fireMetaEventSingle, initMetaPixelScoped, readMetaCookies } from "./metaPixel";
+
+/** The browser signals every visitor-record create request carries (`metaSignals`). */
+export type MetaSignals = {
+  fbp?: string;
+  fbc?: string;
+  pageUrl?: string;
+  /** True: allowed (or the site does not require consent). False: declined. Absent: undecided. */
+  marketingConsent?: boolean;
+};
+
+/** What a create response carries when the server queued a Meta event for that record. */
+export type ServerMetaEvent = { name: string; eventId: string; customData?: Record<string, unknown> };
+
+export type MetaPolicy = {
+  /** The profile pixel id, if the profile has one. */
+  pixelId?: string;
+  /** False in the editor / preview: nothing is sent. */
+  enabled: boolean;
+  /** Whether marketing consent is required before Meta may run. */
+  requireConsent: boolean;
+  apiUrl?: string;
+  subdomain?: string;
+  /** The tenant's settlement currency, used when an event has a value but no currency. */
+  currency?: string;
+  /**
+   * False while the pixel id is still loading. Events fired before then wait
+   * (the detail page often mounts before the site config resolves).
+   */
+  resolved: boolean;
+};
+
+export type MetaCustomData = {
+  value?: number;
+  currency?: string;
+  content_ids?: string[];
+  content_name?: string;
+  content_type?: "product" | "product_group";
+  content_category?: string;
+  num_items?: number;
+  search_string?: string;
+  [key: string]: unknown;
+};
+
+let policy: MetaPolicy | null = null;
+const MAX_PENDING = 25;
+let pending: (() => void)[] = [];
+
+function isReady(): boolean {
+  return !!policy && (policy.resolved || !policy.enabled);
+}
+
+/** Run now if the policy is known, else once it is (bounded queue). */
+function whenReady(fn: () => void): void {
+  if (isReady()) {
+    fn();
+    return;
+  }
+  if (pending.length < MAX_PENDING) pending.push(fn);
+}
+
+/** Set by `<ForgeAnalytics/>`. Flushes events that were waiting for it. */
+export function setMetaPolicy(next: MetaPolicy): void {
+  policy = next;
+  if (!isReady() || pending.length === 0) return;
+  const queued = pending;
+  pending = [];
+  for (const fn of queued) {
+    try {
+      fn();
+    } catch {
+      // A tracking failure never breaks the page.
+    }
+  }
+}
+
+export function getMetaPolicy(): MetaPolicy | null {
+  return policy;
+}
+
+/** Test helper: forget the policy and anything queued. */
+export function resetMetaPolicy(): void {
+  policy = null;
+  pending = [];
+}
+
+/**
+ * The consent half of the Meta gate: true when the site does not require
+ * consent or the visitor allowed marketing, false when they declined,
+ * undefined while they have not decided.
+ */
+export function readMarketingConsent(): boolean | undefined {
+  if (policy && !policy.requireConsent) return true;
+  const consent = getCookieConsent();
+  if (!consent) return undefined;
+  return consent.marketing;
+}
+
+/** Whether a profile-pixel event may fire right now. */
+function profileAllowed(p: MetaPolicy | null): p is MetaPolicy & { pixelId: string } {
+  return !!p && p.enabled && !!p.pixelId && readMarketingConsent() === true;
+}
+
+function buildFbc(): string | undefined {
+  const landing = readLandingClickId("fbclid");
+  if (landing) return `fb.1.${landing.at}.${landing.value}`;
+  // The landing snapshot is written after the page's own effects run, so the
+  // very first page can still hold the click id only in its URL.
+  try {
+    const fbclid = new URL(window.location.href).searchParams.get("fbclid");
+    if (fbclid && fbclid.length <= 512) return `fb.1.${Date.now()}.${fbclid}`;
+  } catch {
+    // ignore
+  }
+  return undefined;
+}
+
+/**
+ * The `metaSignals` body field for a create request. `fbp` / `fbc` are read
+ * (or built) only when marketing is allowed; otherwise they are never touched.
+ */
+export function readMetaSignals(): MetaSignals {
+  if (typeof window === "undefined") return {};
+  const marketingConsent = readMarketingConsent();
+  const signals: MetaSignals = { pageUrl: window.location.href };
+  if (marketingConsent !== undefined) signals.marketingConsent = marketingConsent;
+  if (marketingConsent === true) {
+    const { fbp, fbc } = readMetaCookies();
+    if (fbp) signals.fbp = fbp;
+    const builtFbc = fbc || buildFbc();
+    if (builtFbc) signals.fbc = builtFbc;
+  }
+  return signals;
+}
+
+/** Drop empty fields, keep `value` only when it is a finite number, default the currency. */
+function normaliseCustomData(data: MetaCustomData | undefined, fallbackCurrency?: string): MetaCustomData | undefined {
+  if (!data) return undefined;
+  const out: MetaCustomData = {};
+  for (const [key, val] of Object.entries(data)) {
+    if (val === undefined || val === null || val === "") continue;
+    out[key] = val;
+  }
+  if ("value" in out) {
+    const n = Number(out.value);
+    if (Number.isFinite(n)) out.value = n;
+    else delete out.value;
+  }
+  if (typeof out.currency === "string") out.currency = out.currency.toUpperCase();
+  else if (out.value !== undefined && fallbackCurrency) out.currency = fallbackCurrency.toUpperCase();
+  if (Array.isArray(out.content_ids)) out.content_ids = out.content_ids.map(String).slice(0, 50);
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+type ServerCopy = {
+  pixel: "profile" | "page";
+  pathname?: string;
+  eventName: string;
+  eventId: string;
+  eventSourceUrl: string;
+  customData?: MetaCustomData;
+};
+
+/** POST the server copy. keepalive, like `trackBeacon`, so a navigation does not cancel it. */
+function postServerCopy(p: MetaPolicy, copy: ServerCopy): void {
+  if (!p.apiUrl || !p.subdomain || typeof fetch === "undefined") return;
+  try {
+    void fetch(`${p.apiUrl.replace(/\/$/, "")}/public/websites/meta-event`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      keepalive: true,
+      body: JSON.stringify({ subdomain: p.subdomain, ...copy, metaSignals: readMetaSignals() }),
+    }).catch(() => {});
+  } catch {
+    // Best effort; never disrupt the page.
+  }
+}
+
+function currentHref(): string {
+  return typeof window === "undefined" ? "" : window.location.href;
+}
+
+/**
+ * Fire a Meta event to the profile pixel AND post its server copy, with one
+ * event id. A no-op unless the profile has a pixel, Meta is enabled and
+ * marketing is allowed. Returns the event id.
+ */
+export function trackMeta(eventName: string, customData?: MetaCustomData, opts?: { eventId?: string }): string {
+  const eventId = opts?.eventId ?? newEventId();
+  if (typeof window === "undefined") return eventId;
+  const eventSourceUrl = currentHref();
+  whenReady(() => {
+    const p = policy;
+    if (!profileAllowed(p)) return;
+    const data = normaliseCustomData(customData, p.currency);
+    initMetaPixelScoped(p.pixelId);
+    fireMetaEventSingle(p.pixelId, eventName, data ?? {}, eventId);
+    postServerCopy(p, { pixel: "profile", eventName, eventId, eventSourceUrl, customData: data });
+  });
+  return eventId;
+}
+
+/**
+ * The server copy of an event fired to a PAGE (campaign) pixel. The caller
+ * fires the pixel itself and decides consent for it (`<PageMetaPixel/>`).
+ */
+export function sendPageMetaEvent(input: {
+  eventName: string;
+  eventId: string;
+  pathname: string;
+  customData?: MetaCustomData;
+}): void {
+  if (typeof window === "undefined") return;
+  const eventSourceUrl = currentHref();
+  whenReady(() => {
+    const p = policy;
+    if (!p || !p.enabled) return;
+    postServerCopy(p, {
+      pixel: "page",
+      pathname: input.pathname,
+      eventName: input.eventName,
+      eventId: input.eventId,
+      eventSourceUrl,
+      customData: normaliseCustomData(input.customData, p.currency),
+    });
+  });
+}
+
+/**
+ * The pixel copy of an event the SERVER already queued (a response's
+ * `metaEvent`). No server copy: it exists.
+ */
+export function firePixelOnly(eventName: string, eventId: string, customData?: MetaCustomData): void {
+  if (typeof window === "undefined" || !eventName || !eventId) return;
+  whenReady(() => {
+    const p = policy;
+    if (!profileAllowed(p)) return;
+    initMetaPixelScoped(p.pixelId);
+    fireMetaEventSingle(p.pixelId, eventName, normaliseCustomData(customData, p.currency) ?? {}, eventId);
+  });
+}
+
+/** Fire the pixel copy of a response's `metaEvent`, if it carries one. */
+export function fireServerMetaEvent(response: unknown): void {
+  const metaEvent = (response as { metaEvent?: ServerMetaEvent } | null | undefined)?.metaEvent;
+  if (!metaEvent || typeof metaEvent.name !== "string" || typeof metaEvent.eventId !== "string") return;
+  firePixelOnly(metaEvent.name, metaEvent.eventId, metaEvent.customData as MetaCustomData | undefined);
+}
+
+const PURCHASE_KEY_PREFIX = "tn:meta:purchase:";
+
+function purchaseAlreadyFired(eventId: string): boolean {
+  try {
+    return window.sessionStorage.getItem(PURCHASE_KEY_PREFIX + eventId) === "1";
+  } catch {
+    return false;
+  }
+}
+
+function markPurchaseFired(eventId: string): void {
+  try {
+    window.sessionStorage.setItem(PURCHASE_KEY_PREFIX + eventId, "1");
+  } catch {
+    // Storage disabled: a reload may fire it again, and Meta dedupes on the id.
+  }
+}
+
+/**
+ * The browser copy of a Purchase the server bridge sends on payment. The id is
+ * the record id the server used, so the two dedupe. Pixel only (the server
+ * copy is the bridge's), at most once per tab per record.
+ */
+export function trackPurchase(input: { recordId: string; value: number | string | null | undefined; currency?: string | null }): void {
+  if (typeof window === "undefined" || !input.recordId) return;
+  const value = Number(input.value);
+  if (!Number.isFinite(value) || value <= 0) return;
+  const eventId = input.recordId;
+  if (purchaseAlreadyFired(eventId)) return;
+  whenReady(() => {
+    const p = policy;
+    if (!profileAllowed(p) || purchaseAlreadyFired(eventId)) return;
+    const currency = (input.currency || p.currency || "").toUpperCase() || undefined;
+    initMetaPixelScoped(p.pixelId);
+    fireMetaEventSingle(p.pixelId, "Purchase", currency ? { value, currency } : { value }, eventId);
+    markPurchaseFired(eventId);
+  });
+}

package/src/ui/headless/membership/MembershipGate.tsx

@@ -1,44 +0,0 @@
-import type { ReactNode } from "react";
-import { usePublicAuth } from "../../../contexts/PublicAuthContext";
-import { getMembershipAccess } from "../../../utils/membershipAccess";
-
-export interface MembershipGateState {
-  hasAccess: boolean;
-  isAuthenticated: boolean;
-}
-
-export interface MembershipGateProps {
-  /**
-   * Tier ids that unlock the content. Omitted/empty → any active membership
-   * unlocks. (For per-item gates where the server already returns `hasAccess`,
-   * pass it via `access`.)
-   */
-  tiers?: string[];
-  /** Override the access decision (e.g. server-provided `post.hasAccess`). */
-  access?: boolean;
-  children: ReactNode;
-  /** Rendered when locked — static node or a render-fn given the gate state. */
-  fallback?: ReactNode | ((state: MembershipGateState) => ReactNode);
-}
-
-/**
- * Headless access gate. Renders children when the member has access, otherwise
- * the fallback. Behavior (who has access) is fixed by the server/membership;
- * the locked UI is entirely yours.
- */
-export function MembershipGate({ tiers, access, children, fallback }: MembershipGateProps) {
-  const { user, isAuthenticated } = usePublicAuth();
-  const membership = user?.membership;
-  // The SERVER's access decision, not a `status === "active"` compare. That
-  // compare locked out members in `past_due`/`grace` — states the backend
-  // deliberately keeps access through — so a card that bounced cost them the
-  // content they were still paying for.
-  const membershipGrantsAccess = getMembershipAccess(membership).hasAccess;
-  const tierAllows = !tiers?.length || (membership ? tiers.includes(membership.membershipTierId) : false);
-
-  const hasAccess = access ?? (membershipGrantsAccess && tierAllows);
-
-  if (hasAccess) return <>{children}</>;
-  if (typeof fallback === "function") return <>{fallback({ hasAccess, isAuthenticated })}</>;
-  return <>{fallback ?? null}</>;
-}