@tribe-nest/forge 3.60.0 → 3.63.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/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

@@ -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,31 +97,44 @@ 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;
   }
 }
 
+/** 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),
   };
 }
 
 /**
  * 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 +164,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 };
+}