@tribe-nest/forge 3.61.0 → 3.63.0

package/src/ui/analytics/ForgeAnalytics.tsx

@@ -6,6 +6,7 @@ import { setMetaPolicy, trackMeta } from "../../utils/metaEvents";
 import { setCurrentPageEventId, isProfilePixelSuppressed } from "../../utils/analyticsBus";
 import { useCookieConsent } from "../headless/consent/useCookieConsent";
 import { createEngagementTracker, scrollDepthOf, type EngagementTracker } from "../../utils/engagementTracker";
+import { onCLS, onINP, onLCP, type Metric } from "web-vitals";
 
 export interface ForgeAnalyticsProps {
   /**
@@ -60,6 +61,61 @@ function currentPage(): string {
   return window.location.pathname + window.location.search;
 }
 
+/**
+ * Web Vitals (LCP, INP, CLS), for the SEO tab's page speed report.
+ *
+ * `web-vitals` callbacks cannot be unregistered, so they are registered once
+ * per page load, the first time first-party analytics is allowed, and report
+ * through whichever `<ForgeAnalytics />` is mounted now (`vitalsSink`). With
+ * none mounted, or analytics switched off, a report is dropped. Observers are
+ * buffered, so a visitor who consents after the page painted still reports its
+ * LCP.
+ *
+ * Each metric instance is sent once (its first report): a page view, or a
+ * restore from the back/forward cache, which `web-vitals` treats as a new one.
+ * The path is the page the metric belongs to: the URL `web-vitals` names for
+ * it, else the page the document loaded on, since an SPA navigation does not
+ * start a new measurement.
+ */
+type VitalReport = { name: Metric["name"]; value: number; rating: Metric["rating"]; path: string };
+let vitalsSink: ((report: VitalReport) => void) | null = null;
+let vitalsRegistered = false;
+const vitalsSent = new Set<string>();
+
+function pathOfMetric(metric: Metric, loadPath: string): string {
+  try {
+    if (metric.navigationURL) return new URL(metric.navigationURL, window.location.href).pathname;
+  } catch {
+    // fall through to the page the document loaded on
+  }
+  return loadPath;
+}
+
+function registerWebVitals(): void {
+  if (vitalsRegistered || typeof window === "undefined") return;
+  vitalsRegistered = true;
+  const loadPath = currentPathname();
+  const report = (metric: Metric) => {
+    if (vitalsSent.has(metric.id) || !vitalsSink) return;
+    vitalsSent.add(metric.id);
+    vitalsSink({ name: metric.name, value: metric.value, rating: metric.rating, path: pathOfMetric(metric, loadPath) });
+  };
+  try {
+    onLCP(report);
+    onINP(report);
+    onCLS(report);
+  } catch {
+    // An unsupported browser measures nothing; never break the page for it.
+  }
+}
+
+/** For tests: forget the registration and what was sent, as a fresh page load would. */
+export function __resetWebVitalsForTests(): void {
+  vitalsSink = null;
+  vitalsRegistered = false;
+  vitalsSent.clear();
+}
+
 /** Engaged means the visitor can see the page and it has focus. */
 function isEngaged(): boolean {
   return typeof document !== "undefined" && document.visibilityState === "visible" && document.hasFocus();
@@ -74,6 +130,8 @@ function isEngaged(): boolean {
  * - Auto click tracking on links/buttons (opt out with `trackClicks={false}`).
  * - Time on page and scroll depth, as `engagement` events (engaged time only:
  *   visible and focused).
+ * - Page speed: LCP, INP and CLS (Web Vitals), as one `web_vital` event per
+ *   metric per page view, for the SEO tab.
  * - Optional Meta Pixel: pass `metaPixelId` to init the pixel and mirror each
  *   page view as a Meta `PageView` (event-id matched for CAPI de-dup).
  *
@@ -263,6 +321,18 @@ export function ForgeAnalytics({
     };
   }, [firstPartyOn]);
 
+  // Web Vitals: first-party only, like the page views they belong to. Sent by
+  // beacon, because INP and CLS are reported as the page is hidden.
+  useEffect(() => {
+    if (!firstPartyOn || typeof window === "undefined") return;
+    const sink = (report: VitalReport) => beaconRef.current("web_vital", report);
+    vitalsSink = sink;
+    registerWebVitals();
+    return () => {
+      if (vitalsSink === sink) vitalsSink = null;
+    };
+  }, [firstPartyOn]);
+
   // Click tracking: first-party only, one delegated listener for the document.
   useEffect(() => {
     if (!firstPartyOn || !trackClicks || typeof document === "undefined") return;

package/src/ui/analytics/_tests/ForgeAnalytics.webVitals.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";
+
+/**
+ * Web Vitals reporting (SEO step 4). `web-vitals` is mocked: each `onX`
+ * registration is captured so a test can fire the metric the browser would.
+ * What is asserted: one `web_vital` event per metric instance, by beacon, with
+ * `{ name, value, rating, path }`; nothing at all without first-party consent;
+ * the cookieless mode still reporting; and registration happening once per
+ * page load however often the component mounts.
+ */
+
+type Metric = {
+  name: "LCP" | "INP" | "CLS";
+  value: number;
+  rating: "good" | "needs-improvement" | "poor";
+  id: string;
+  navigationURL?: string;
+};
+const handlers: Record<string, Array<(m: Metric) => void>> = { LCP: [], INP: [], CLS: [] };
+vi.mock("web-vitals", () => ({
+  onLCP: (cb: (m: Metric) => void) => handlers.LCP.push(cb),
+  onINP: (cb: (m: Metric) => void) => handlers.INP.push(cb),
+  onCLS: (cb: (m: Metric) => void) => handlers.CLS.push(cb),
+}));
+
+const calls: { via: "track" | "beacon"; eventType: string; data: Record<string, unknown> }[] = [];
+vi.mock("../../../data/queries/useAnalytics", () => ({
+  newEventId: () => "evt",
+  useTrackEvent: () => ({
+    track: (eventType: string, data: Record<string, unknown>) => calls.push({ via: "track", eventType, data }),
+    trackBeacon: (eventType: string, data: Record<string, unknown>) => calls.push({ via: "beacon", eventType, data }),
+  }),
+}));
+vi.mock("../../../data/queries/useWebsite", () => ({ useSiteConfig: () => ({ data: undefined }) }));
+const consent = { performance: true, marketing: false };
+vi.mock("../../headless/consent/useCookieConsent", () => ({ useCookieConsent: () => consent }));
+
+import { ForgeAnalytics, __resetWebVitalsForTests } from "../ForgeAnalytics";
+
+const fire = (metric: Metric) => {
+  for (const cb of handlers[metric.name]) cb(metric);
+};
+const vitals = () => calls.filter((c) => c.eventType === "web_vital").map((c) => [c.via, c.data]);
+
+describe("<ForgeAnalytics /> web vitals", () => {
+  beforeEach(() => {
+    calls.length = 0;
+    for (const key of Object.keys(handlers)) handlers[key].length = 0;
+    consent.performance = true;
+    __resetWebVitalsForTests();
+    window.history.replaceState({}, "", "/classes?ref=x");
+  });
+
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("sends LCP, INP and CLS once each, by beacon, with the page the document loaded on", () => {
+    render(<ForgeAnalytics trackClicks={false} />);
+    expect(handlers.LCP).toHaveLength(1);
+    expect(handlers.INP).toHaveLength(1);
+    expect(handlers.CLS).toHaveLength(1);
+
+    // An SPA navigation does not start a new measurement.
+    act(() => window.history.pushState({}, "", "/about"));
+    fire({ name: "LCP", value: 1820.4, rating: "good", id: "v5-lcp-1" });
+    fire({ name: "CLS", value: 0.04, rating: "good", id: "v5-cls-1" });
+    fire({ name: "INP", value: 260, rating: "needs-improvement", id: "v5-inp-1" });
+    // A later report of the same instance (CLS grows) is not sent again.
+    fire({ name: "CLS", value: 0.3, rating: "poor", id: "v5-cls-1" });
+
+    expect(vitals()).toEqual([
+      ["beacon", { name: "LCP", value: 1820.4, rating: "good", path: "/classes" }],
+      ["beacon", { name: "CLS", value: 0.04, rating: "good", path: "/classes" }],
+      ["beacon", { name: "INP", value: 260, rating: "needs-improvement", path: "/classes" }],
+    ]);
+  });
+
+  it("sends a new instance (a back/forward cache restore) with the URL web-vitals names", () => {
+    render(<ForgeAnalytics trackClicks={false} />);
+    fire({ name: "LCP", value: 900, rating: "good", id: "a" });
+    fire({ name: "LCP", value: 300, rating: "good", id: "b", navigationURL: "https://site.test/events/x?y=1" });
+    expect(vitals().map(([, data]) => (data as { path: string }).path)).toEqual(["/classes", "/events/x"]);
+  });
+
+  it("measures nothing without performance consent, and starts once it is given", () => {
+    consent.performance = false;
+    const { rerender } = render(<ForgeAnalytics trackClicks={false} />);
+    expect(handlers.LCP).toHaveLength(0);
+    fire({ name: "LCP", value: 1000, rating: "good", id: "early" });
+    expect(vitals()).toEqual([]);
+
+    consent.performance = true;
+    rerender(<ForgeAnalytics trackClicks={false} />);
+    expect(handlers.LCP).toHaveLength(1);
+    // The observers are buffered, so the LCP that painted before consent still reports.
+    fire({ name: "LCP", value: 1000, rating: "good", id: "early" });
+    expect(vitals()).toEqual([["beacon", { name: "LCP", value: 1000, rating: "good", path: "/classes" }]]);
+  });
+
+  it("reports in cookieless mode without performance consent", () => {
+    consent.performance = false;
+    render(<ForgeAnalytics trackClicks={false} firstPartyMode="cookieless" />);
+    fire({ name: "INP", value: 120, rating: "good", id: "i1" });
+    expect(vitals()).toEqual([["beacon", { name: "INP", value: 120, rating: "good", path: "/classes" }]]);
+  });
+
+  it("records nothing when disabled, and nothing after the component unmounts", () => {
+    const { unmount } = render(<ForgeAnalytics enabled={false} />);
+    expect(handlers.LCP).toHaveLength(0);
+    unmount();
+
+    const mounted = render(<ForgeAnalytics trackClicks={false} />);
+    mounted.unmount();
+    fire({ name: "LCP", value: 1000, rating: "good", id: "late" });
+    expect(vitals()).toEqual([]);
+  });
+
+  it("registers once per page load however often it mounts", () => {
+    render(<ForgeAnalytics trackClicks={false} />);
+    cleanup();
+    render(<ForgeAnalytics trackClicks={false} />);
+    expect(handlers.LCP).toHaveLength(1);
+    fire({ name: "LCP", value: 700, rating: "good", id: "once" });
+    expect(vitals()).toHaveLength(1);
+  });
+});

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

@@ -0,0 +1,39 @@
+// @vitest-environment jsdom
+import { describe, it, expect, beforeEach } from "vitest";
+import { readLanding } from "../landing";
+
+/**
+ * SEO step 6: checkout credits a sale to the page the buyer first landed on.
+ * `readLanding` is spread into every Forge checkout body, so `landingPath` riding
+ * on it is what puts the pathname on the purchase row.
+ */
+function store(snapshot: Record<string, unknown>) {
+  window.localStorage.setItem("tn:landing", JSON.stringify(snapshot));
+}
+
+describe("readLanding", () => {
+  beforeEach(() => window.localStorage.clear());
+
+  it("returns the pathname of the first landing URL, without its query", () => {
+    store({
+      landingUtm: { utm_source: "tribenest" },
+      referrer: "https://instagram.com/",
+      landingUrl: "https://clayroom.example/i/blog/first-class?utm_source=tribenest#top",
+      at: Date.now(),
+    });
+    expect(readLanding()).toEqual({
+      landingUtm: { utm_source: "tribenest" },
+      referrer: "https://instagram.com/",
+      landingPath: "/i/blog/first-class",
+    });
+  });
+
+  it("leaves landingPath undefined when the stored URL cannot be parsed", () => {
+    store({ landingUtm: {}, referrer: "", landingUrl: "not a url", at: Date.now() });
+    expect(readLanding()).toEqual({ landingUtm: undefined, referrer: undefined, landingPath: undefined });
+  });
+
+  it("returns null when nothing is stored", () => {
+    expect(readLanding()).toBeNull();
+  });
+});

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

@@ -0,0 +1,247 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  buildBlogPostingSchema,
+  buildBreadcrumbSchema,
+  buildEventSchema,
+  buildIdentitySchema,
+  buildPodcastEpisodeSchema,
+  buildPodcastSeriesSchema,
+  buildWebSiteSchema,
+  type EventSchemaSource,
+} from "../structuredData";
+
+afterEach(() => vi.useRealTimers());
+
+const URL_ = "https://claystudio.com/i/events/late-show";
+
+const EVENT: EventSchemaSource = {
+  title: "Late Show",
+  description: "<p>An evening of <b>clay</b>.</p>",
+  dateTime: "2026-11-01T19:00:00.000Z",
+  endDateTime: "2026-11-01T22:00:00.000Z",
+  doorsOpenAt: "2026-11-01T18:30:00.000Z",
+  status: "on_sale",
+  cancelledAt: null,
+  type: "physical",
+  address: { name: "The Hall", street: "1 Mare St", city: "London", country: "GB", zipCode: "E8 1AA" },
+  media: [{ url: "https://cdn.example/poster.jpg", type: "image" }],
+  tickets: [
+    { title: "General", price: 15, quantity: 100, sold: 10 },
+    { title: "VIP", price: 40, quantity: 10, sold: 10 },
+    { title: "Hidden", price: 1, quantity: 10, sold: 0, isHidden: true },
+    { title: "Members", price: 5, quantity: 10, sold: 0, membershipGate: { allowed: false } as never },
+  ],
+  bookingFee: { currency: "GBP" },
+};
+
+describe("buildEventSchema", () => {
+  it("describes a physical event with a Place, status, mode and one offer per public tier", () => {
+    const s = buildEventSchema(EVENT, { url: URL_ })!;
+    expect(s).toMatchObject({
+      "@context": "https://schema.org",
+      "@type": "Event",
+      name: "Late Show",
+      startDate: EVENT.dateTime,
+      endDate: EVENT.endDateTime,
+      doorTime: EVENT.doorsOpenAt,
+      eventStatus: "https://schema.org/EventScheduled",
+      eventAttendanceMode: "https://schema.org/OfflineEventAttendanceMode",
+      description: "An evening of clay .",
+      image: "https://cdn.example/poster.jpg",
+      url: URL_,
+      location: {
+        "@type": "Place",
+        name: "The Hall",
+        address: {
+          "@type": "PostalAddress",
+          streetAddress: "1 Mare St",
+          addressLocality: "London",
+          postalCode: "E8 1AA",
+          addressCountry: "GB",
+        },
+      },
+    });
+    expect(s.offers).toEqual([
+      { "@type": "Offer", name: "General", price: 15, priceCurrency: "GBP", availability: "https://schema.org/InStock", url: URL_ },
+      { "@type": "Offer", name: "VIP", price: 40, priceCurrency: "GBP", availability: "https://schema.org/SoldOut", url: URL_ },
+    ]);
+  });
+
+  it("gives a virtual event a VirtualLocation and a hybrid event both", () => {
+    const v = buildEventSchema({ ...EVENT, type: "virtual" }, { url: URL_ })!;
+    expect(v.eventAttendanceMode).toBe("https://schema.org/OnlineEventAttendanceMode");
+    expect(v.location).toEqual({ "@type": "VirtualLocation", url: URL_ });
+    const h = buildEventSchema({ ...EVENT, type: "hybrid" }, { url: URL_ })!;
+    expect(h.eventAttendanceMode).toBe("https://schema.org/MixedEventAttendanceMode");
+    expect((h.location as unknown[]).map((l) => (l as { "@type": string })["@type"])).toEqual(["Place", "VirtualLocation"]);
+  });
+
+  it("marks a cancelled event and sells nothing", () => {
+    const s = buildEventSchema({ ...EVENT, status: "cancelled" })!;
+    expect(s.eventStatus).toBe("https://schema.org/EventCancelled");
+    expect(s).not.toHaveProperty("offers");
+  });
+
+  it("emits no offers without a currency, and none for a members-only event", () => {
+    expect(buildEventSchema({ ...EVENT, bookingFee: null })).not.toHaveProperty("offers");
+    expect(buildEventSchema({ ...EVENT, bookingFee: null }, { currency: "USD" })!.offers).toBeDefined();
+    expect(buildEventSchema({ ...EVENT, membershipGate: { allowed: false } })).not.toHaveProperty("offers");
+  });
+
+  it("says PreOrder for a tier that is not on sale yet", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-10-01T00:00:00.000Z"));
+    const s = buildEventSchema({
+      ...EVENT,
+      tickets: [{ title: "Early", price: 10, quantity: 5, sold: 0, availableFrom: "2026-10-10T00:00:00.000Z" }],
+    })!;
+    expect(s.offers).toMatchObject({ availability: "https://schema.org/PreOrder", validFrom: "2026-10-10T00:00:00.000Z" });
+  });
+
+  it("names the organizer from the identity", () => {
+    const s = buildEventSchema(EVENT, { organizer: { kind: "person", name: "Ada" }, origin: "https://claystudio.com" })!;
+    expect(s.organizer).toEqual({ "@type": "Person", name: "Ada", url: "https://claystudio.com" });
+  });
+
+  it("returns null with no title or no start", () => {
+    expect(buildEventSchema({ ...EVENT, title: " " })).toBeNull();
+    expect(buildEventSchema({ ...EVENT, dateTime: "" })).toBeNull();
+    expect(buildEventSchema(null)).toBeNull();
+  });
+});
+
+describe("buildBlogPostingSchema", () => {
+  it("builds a BlogPosting with author and publisher from an organization identity", () => {
+    const s = buildBlogPostingSchema(
+      {
+        title: "Glazes",
+        content: "<p>How we glaze.</p>",
+        publishedAt: "2026-09-01T00:00:00.000Z",
+        media: [{ url: "https://cdn.example/g.jpg", type: "image/jpeg" }, { url: "https://cdn.example/a.mp3", type: "audio/mpeg" }],
+      },
+      {
+        url: "https://claystudio.com/i/blog/glazes",
+        identity: { kind: "organization", name: "Clay Studio", logo: "https://cdn.example/logo.png" },
+        origin: "https://claystudio.com",
+      },
+    )!;
+    const org = { "@type": "Organization", name: "Clay Studio", url: "https://claystudio.com", logo: "https://cdn.example/logo.png" };
+    expect(s).toEqual({
+      "@context": "https://schema.org",
+      "@type": "BlogPosting",
+      headline: "Glazes",
+      description: "How we glaze.",
+      datePublished: "2026-09-01T00:00:00.000Z",
+      dateModified: "2026-09-01T00:00:00.000Z",
+      image: "https://cdn.example/g.jpg",
+      url: "https://claystudio.com/i/blog/glazes",
+      mainEntityOfPage: { "@type": "WebPage", "@id": "https://claystudio.com/i/blog/glazes" },
+      author: org,
+      publisher: org,
+    });
+  });
+
+  it("uses a person as author only, and clamps a long headline", () => {
+    const s = buildBlogPostingSchema({ title: "x".repeat(200) }, { identity: { kind: "person", name: "Ada" } })!;
+    expect((s.headline as string).length).toBe(110);
+    expect(s.author).toEqual({ "@type": "Person", name: "Ada" });
+    expect(s).not.toHaveProperty("publisher");
+  });
+});
+
+describe("podcast schemas", () => {
+  it("builds a PodcastSeries, preferring the show's own author", () => {
+    expect(
+      buildPodcastSeriesSchema(
+        { title: "Kiln Talk", description: "Weekly.", coverImage: { url: "https://cdn.example/c.jpg" }, author: "Ada" },
+        { url: "https://claystudio.com/i/podcasts/kiln-talk" },
+      ),
+    ).toEqual({
+      "@context": "https://schema.org",
+      "@type": "PodcastSeries",
+      name: "Kiln Talk",
+      description: "Weekly.",
+      image: "https://cdn.example/c.jpg",
+      url: "https://claystudio.com/i/podcasts/kiln-talk",
+      author: { "@type": "Person", name: "Ada" },
+    });
+  });
+
+  it("builds a PodcastEpisode with its audio, duration and series", () => {
+    expect(
+      buildPodcastEpisodeSchema(
+        {
+          title: "Ep 1",
+          content: "<p>Hello</p>",
+          publishedAt: "2026-09-02T00:00:00.000Z",
+          media: [{ url: "https://cdn.example/1.mp3", type: "audio/mpeg", durationSec: 3725 }],
+        },
+        { url: "https://claystudio.com/i/podcasts/kiln-talk/ep-1", series: { name: "Kiln Talk", url: "https://claystudio.com/i/podcasts/kiln-talk" } },
+      ),
+    ).toEqual({
+      "@context": "https://schema.org",
+      "@type": "PodcastEpisode",
+      name: "Ep 1",
+      description: "Hello",
+      datePublished: "2026-09-02T00:00:00.000Z",
+      url: "https://claystudio.com/i/podcasts/kiln-talk/ep-1",
+      timeRequired: "PT1H2M",
+      associatedMedia: { "@type": "MediaObject", contentUrl: "https://cdn.example/1.mp3", encodingFormat: "audio/mpeg", duration: "PT1H2M" },
+      partOfSeries: { "@type": "PodcastSeries", name: "Kiln Talk", url: "https://claystudio.com/i/podcasts/kiln-talk" },
+    });
+  });
+});
+
+describe("site schemas", () => {
+  it("builds Person, Organization and LocalBusiness identities", () => {
+    expect(buildIdentitySchema({ kind: "person", name: "Ada", logo: "https://x/a.jpg", sameAs: [] })).toEqual({
+      "@context": "https://schema.org",
+      "@type": "Person",
+      name: "Ada",
+      image: "https://x/a.jpg",
+    });
+    expect(buildIdentitySchema({ kind: "organization", name: "Clay", logo: "https://x/l.png", sameAs: ["https://x.com/clay"] }, { origin: "https://clay.com/" })).toEqual({
+      "@context": "https://schema.org",
+      "@type": "Organization",
+      "@id": "https://clay.com/#identity",
+      url: "https://clay.com",
+      name: "Clay",
+      logo: "https://x/l.png",
+      sameAs: ["https://x.com/clay"],
+    });
+    expect(buildIdentitySchema({ kind: "local_business", name: "Clay", sameAs: [], address: {}, phone: "123" })).toEqual({
+      "@context": "https://schema.org",
+      "@type": "LocalBusiness",
+      name: "Clay",
+      telephone: "123",
+    });
+    expect(buildIdentitySchema({ kind: "person", name: "", sameAs: [] })).toBeNull();
+  });
+
+  it("builds a WebSite linked to its publisher", () => {
+    expect(buildWebSiteSchema({ name: "Clay", url: "https://clay.com/", publisherId: "https://clay.com/#identity" })).toEqual({
+      "@context": "https://schema.org",
+      "@type": "WebSite",
+      name: "Clay",
+      url: "https://clay.com/",
+      publisher: { "@id": "https://clay.com/#identity" },
+    });
+  });
+
+  it("builds a BreadcrumbList, and nothing for a single crumb", () => {
+    expect(
+      buildBreadcrumbSchema([
+        { name: "Clay", url: "https://clay.com/" },
+        { name: "Store", url: "https://clay.com/i/store" },
+      ]),
+    ).toEqual({
+      "@context": "https://schema.org",
+      "@type": "BreadcrumbList",
+      itemListElement: [
+        { "@type": "ListItem", position: 1, name: "Clay", item: "https://clay.com/" },
+        { "@type": "ListItem", position: 2, name: "Store", item: "https://clay.com/i/store" },
+      ],
+    });
+    expect(buildBreadcrumbSchema([{ name: "Clay", url: "https://clay.com/" }])).toBeNull();
+  });
+});

package/src/utils/landing.ts

@@ -103,18 +103,31 @@ export function captureLandingFromUrl(): boolean {
   }
 }
 
+/** The pathname of a stored landing URL, or undefined when it cannot be read. */
+function landingPathOf(landingUrl: string | undefined): string | undefined {
+  if (!landingUrl) return undefined;
+  try {
+    const path = new URL(landingUrl).pathname;
+    return path.startsWith("/") ? path : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
- * Returns the first-touch `landingUtm` bag + `referrer` for the checkout
- * payload, or null when nothing is stored / it expired. `landingUtm` is
- * undefined when the bag is empty so we don't ship `{}`.
+ * Returns the first-touch `landingUtm` bag, `referrer` and `landingPath` (the
+ * pathname of the first page, so a sale can be credited to the blog post that
+ * brought the buyer) for the checkout payload, or null when nothing is stored /
+ * it expired. `landingUtm` is undefined when the bag is empty so we don't ship `{}`.
  */
-export function readLanding(): { landingUtm?: Record<string, string>; referrer?: string } | null {
+export function readLanding(): { landingUtm?: Record<string, string>; referrer?: string; landingPath?: string } | null {
   const snapshot = readSnapshot();
   if (!snapshot) return null;
   const hasParams = Object.keys(snapshot.landingUtm).length > 0;
   return {
     landingUtm: hasParams ? snapshot.landingUtm : undefined,
     referrer: snapshot.referrer || undefined,
+    landingPath: landingPathOf(snapshot.landingUrl),
   };
 }