@tribe-nest/forge 3.61.0 → 3.64.0

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

@@ -0,0 +1,283 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  buildBlogPostingSchema,
+  buildBreadcrumbSchema,
+  buildCourseSchema,
+  buildEventSchema,
+  buildFilmSchema,
+  buildIdentitySchema,
+  buildPodcastEpisodeSchema,
+  buildPodcastSeriesSchema,
+  buildProductSchema,
+  buildServiceSchema,
+  buildWebSiteSchema,
+  seoBrandName,
+  withSeoBrand,
+  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();
+  });
+});
+
+describe("the business name in structured data", () => {
+  it("is the SEO identity's name, then the SEO site name, then the profile's", () => {
+    const seo = { identity: { name: " Clay Studio Ltd " }, siteName: "Clay Studio" };
+    expect(seoBrandName(seo, "Ada Potter")).toBe("Clay Studio Ltd");
+    expect(seoBrandName({ identity: null, siteName: "Clay Studio" }, "Ada Potter")).toBe("Clay Studio");
+    expect(seoBrandName({ identity: { name: "  " }, siteName: "" }, "Ada Potter")).toBe("Ada Potter");
+    expect(seoBrandName(null, "Ada Potter")).toBe("Ada Potter");
+    expect(seoBrandName(null, null)).toBeUndefined();
+  });
+
+  it("names Product brand and Course, Service and Film provider the same way", () => {
+    const context = withSeoBrand({ currency: "GBP", brand: "Ada Potter" }, { identity: { name: "Clay Studio Ltd" }, siteName: "Clay Studio" });
+    expect(context).toEqual({ currency: "GBP", brand: "Clay Studio Ltd" });
+
+    const product = buildProductSchema({ title: "Mug", variants: [] } as never, context);
+    expect(product?.brand).toEqual({ "@type": "Organization", name: "Clay Studio Ltd" });
+    const course = buildCourseSchema({ title: "Wheel basics" } as never, context);
+    expect(course?.provider).toEqual({ "@type": "Organization", name: "Clay Studio Ltd" });
+    const service = buildServiceSchema({ title: "Studio hour" } as never, context);
+    expect(service?.provider).toEqual({ "@type": "Organization", name: "Clay Studio Ltd" });
+    const film = buildFilmSchema({ title: "Throwing", kind: "film" } as never, context);
+    expect(film?.provider).toEqual({ "@type": "Organization", name: "Clay Studio Ltd" });
+  });
+
+  it("keeps the profile name when there is no SEO record", () => {
+    expect(withSeoBrand({ currency: "GBP", brand: "Ada Potter" }, null)).toEqual({ currency: "GBP", brand: "Ada Potter" });
+    expect(withSeoBrand(null, null)).toEqual({ brand: undefined });
+  });
+});

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),
   };
 }