@tribe-nest/forge 3.21.0 → 3.22.0

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

@@ -0,0 +1,275 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildCourseSchema,
+  buildEntitySchema,
+  buildEntityReviewSchema,
+  buildProductSchema,
+  buildServiceSchema,
+  jsonLdScripts,
+  type ProductSchemaSource,
+} from "../structuredData";
+
+/**
+ * The regression this file exists for: `buildEntityReviewSchema` used to return
+ * `null` whenever an entity had no review aggregate, so a brand-new product —
+ * the one that most needs a rich result and a free Shopping listing — emitted
+ * no schema.org/Product at all.
+ *
+ * Reviews must ENRICH the node, never gate it. The mirror-image rule is that an
+ * empty or zero `aggregateRating` is a schema violation Google penalises, so
+ * "no reviews yet" must be an ABSENT key, not a zero.
+ */
+
+const PRODUCT: ProductSchemaSource = {
+  title: "Midnight Pressing (Vinyl)",
+  description: "<p>Limited <strong>180g</strong> pressing.</p>",
+  artist: "Nova Wren",
+  media: [
+    { url: "https://cdn.example/front.jpg", type: "image/jpeg" },
+    { url: "https://cdn.example/back.jpg", type: "image/jpeg" },
+  ],
+  variants: [{ price: 32, availabilityStatus: "active" }],
+};
+
+describe("buildProductSchema — reviews enrich, they do not gate", () => {
+  it("emits a Product for a product with NO reviews at all", () => {
+    const schema = buildProductSchema(PRODUCT, { currency: "USD" });
+    expect(schema).not.toBeNull();
+    expect(schema).toMatchObject({ "@context": "https://schema.org", "@type": "Product", name: PRODUCT.title });
+  });
+
+  it("omits aggregateRating entirely rather than emitting a zero", () => {
+    for (const aggregate of [null, undefined, { avgRating: 0, reviewCount: 0 }]) {
+      const schema = buildProductSchema({ ...PRODUCT, reviewAggregate: aggregate }, { currency: "USD" })!;
+      expect(schema).not.toHaveProperty("aggregateRating");
+      expect(schema).not.toHaveProperty("review");
+    }
+  });
+
+  it("adds aggregateRating once there genuinely are reviews", () => {
+    const schema = buildProductSchema(
+      { ...PRODUCT, reviewAggregate: { avgRating: 4.6666, reviewCount: 3 } },
+      {
+        currency: "USD",
+        reviews: [{ rating: 5, title: "Superb", body: "Sounds huge.", reviewerName: "Ada", publishedAt: "2026-01-02" }],
+      },
+    )!;
+    expect(schema.aggregateRating).toEqual({
+      "@type": "AggregateRating",
+      ratingValue: 4.67,
+      reviewCount: 3,
+      bestRating: 5,
+      worstRating: 1,
+    });
+    expect(schema.review).toHaveLength(1);
+  });
+
+  it("drops out-of-range review ratings from the sample", () => {
+    const schema = buildProductSchema(
+      { ...PRODUCT, reviewAggregate: { avgRating: 5, reviewCount: 2 } },
+      { currency: "USD", reviews: [{ rating: 5 }, { rating: 0 }, { rating: 9 }] },
+    )!;
+    expect(schema.review).toHaveLength(1);
+  });
+
+  it("returns null only when there is no name — nothing truthful to say", () => {
+    expect(buildProductSchema(null, { currency: "USD" })).toBeNull();
+    expect(buildProductSchema({ title: "   " }, { currency: "USD" })).toBeNull();
+  });
+});
+
+describe("buildProductSchema — offers stay honest", () => {
+  it("emits a single Offer for one fixed price", () => {
+    const schema = buildProductSchema(PRODUCT, { currency: "GBP" })!;
+    expect(schema.offers).toEqual({
+      "@type": "Offer",
+      priceCurrency: "GBP",
+      price: 32,
+      availability: "https://schema.org/InStock",
+    });
+  });
+
+  it("emits NO offers without a settlement currency — an Offer with no currency is invalid", () => {
+    expect(buildProductSchema(PRODUCT, {})!).not.toHaveProperty("offers");
+    expect(buildProductSchema(PRODUCT, { currency: null })!).not.toHaveProperty("offers");
+  });
+
+  it("emits NO offers for a product the caller may not buy (membership gate)", () => {
+    const gated = buildProductSchema({ ...PRODUCT, membershipGate: { allowed: false } }, { currency: "USD" })!;
+    expect(gated).not.toHaveProperty("offers");
+    // …but the Product node itself still exists, so the page is still indexable.
+    expect(gated["@type"]).toBe("Product");
+
+    const allowed = buildProductSchema({ ...PRODUCT, membershipGate: { allowed: true } }, { currency: "USD" })!;
+    expect(allowed).toHaveProperty("offers");
+  });
+
+  it("mirrors availabilityStatus — the same field the Add-to-cart button reads", () => {
+    const soldOut = buildProductSchema(
+      { ...PRODUCT, variants: [{ price: 32, availabilityStatus: "temporarily_out_of_stock" }] },
+      { currency: "USD" },
+    )!;
+    expect(soldOut.offers).toMatchObject({ availability: "https://schema.org/OutOfStock" });
+
+    const partial = buildProductSchema(
+      {
+        ...PRODUCT,
+        variants: [
+          { price: 32, availabilityStatus: "temporarily_out_of_stock" },
+          { price: 45, availabilityStatus: "active" },
+        ],
+      },
+      { currency: "USD" },
+    )!;
+    expect(partial.offers).toMatchObject({ availability: "https://schema.org/InStock" });
+  });
+
+  it("emits an AggregateOffer across several variant prices", () => {
+    const schema = buildProductSchema(
+      {
+        ...PRODUCT,
+        variants: [
+          { price: 32, availabilityStatus: "active" },
+          { price: "45.5", availabilityStatus: "active" },
+          { price: 40, availabilityStatus: "active" },
+        ],
+      },
+      { currency: "EUR" },
+    )!;
+    expect(schema.offers).toEqual({
+      "@type": "AggregateOffer",
+      priceCurrency: "EUR",
+      lowPrice: 32,
+      highPrice: 45.5,
+      offerCount: 3,
+      availability: "https://schema.org/InStock",
+    });
+  });
+
+  it("leaves highPrice OFF for an open-ended pay-what-you-want floor", () => {
+    // `price` IS the floor for a PWYW variant; with no maximum there is no
+    // ceiling, and inventing one would be a claim the storefront cannot back.
+    const schema = buildProductSchema(
+      { ...PRODUCT, variants: [{ price: 5, availabilityStatus: "active", payWhatYouWant: true }] },
+      { currency: "USD" },
+    )!;
+    expect(schema.offers).toEqual({
+      "@type": "AggregateOffer",
+      priceCurrency: "USD",
+      lowPrice: 5,
+      offerCount: 1,
+      availability: "https://schema.org/InStock",
+    });
+  });
+
+  it("uses the pay-what-you-want maximum as highPrice when one is set", () => {
+    const schema = buildProductSchema(
+      {
+        ...PRODUCT,
+        variants: [{ price: 5, availabilityStatus: "active", payWhatYouWant: true, payWhatYouWantMaximum: 50 }],
+      },
+      { currency: "USD" },
+    )!;
+    expect(schema.offers).toMatchObject({ "@type": "AggregateOffer", lowPrice: 5, highPrice: 50 });
+  });
+
+  it("emits no offers for a product with no variants", () => {
+    expect(buildProductSchema({ ...PRODUCT, variants: [] }, { currency: "USD" })!).not.toHaveProperty("offers");
+  });
+});
+
+describe("buildProductSchema — the rest of the node", () => {
+  it("strips HTML out of the description", () => {
+    expect(buildProductSchema(PRODUCT, {})!.description).toBe("Limited 180g pressing.");
+  });
+
+  it("emits every image, and a bare string when there is only one", () => {
+    expect(buildProductSchema(PRODUCT, {})!.image).toEqual([
+      "https://cdn.example/front.jpg",
+      "https://cdn.example/back.jpg",
+    ]);
+    const single = buildProductSchema({ ...PRODUCT, media: [PRODUCT.media![0]] }, {})!;
+    expect(single.image).toBe("https://cdn.example/front.jpg");
+  });
+
+  it("prefers the release artist as brand, falling back to the creator", () => {
+    expect(buildProductSchema(PRODUCT, { brand: "Wren Records" })!.brand).toEqual({
+      "@type": "Organization",
+      name: "Nova Wren",
+    });
+    expect(buildProductSchema({ ...PRODUCT, artist: "" }, { brand: "Wren Records" })!.brand).toEqual({
+      "@type": "Organization",
+      name: "Wren Records",
+    });
+    expect(buildProductSchema({ ...PRODUCT, artist: "" }, {})!).not.toHaveProperty("brand");
+  });
+
+  it("omits url when the caller has no canonical URL to give", () => {
+    expect(buildProductSchema(PRODUCT, {})!).not.toHaveProperty("url");
+    expect(buildProductSchema(PRODUCT, { url: "https://nova.example/i/store/vinyl" })!.url).toBe(
+      "https://nova.example/i/store/vinyl",
+    );
+  });
+});
+
+describe("buildCourseSchema / buildServiceSchema", () => {
+  const COURSE = { title: "Mixing in a Bedroom", description: "<p>8 modules.</p>", price: "99", media: [] };
+
+  it("emits a Course with no reviews, and uses `provider` not `brand`", () => {
+    const schema = buildCourseSchema(COURSE, { currency: "USD", brand: "Nova Wren" })!;
+    expect(schema["@type"]).toBe("Course");
+    expect(schema.provider).toEqual({ "@type": "Organization", name: "Nova Wren" });
+    expect(schema).not.toHaveProperty("brand");
+    expect(schema).not.toHaveProperty("aggregateRating");
+    expect(schema.offers).toEqual({
+      "@type": "Offer",
+      priceCurrency: "USD",
+      price: 99,
+      availability: "https://schema.org/InStock",
+    });
+  });
+
+  it("never claims hasCourseInstance — the platform has no scheduled instance to point at", () => {
+    expect(buildCourseSchema(COURSE, { currency: "USD" })!).not.toHaveProperty("hasCourseInstance");
+  });
+
+  it("drops the Course offer for a members-only course", () => {
+    const schema = buildCourseSchema({ ...COURSE, membershipGate: { allowed: false } }, { currency: "USD" })!;
+    expect(schema["@type"]).toBe("Course");
+    expect(schema).not.toHaveProperty("offers");
+  });
+
+  it("emits a Service for a coaching product with no reviews", () => {
+    const schema = buildServiceSchema({ title: "1:1 Mix Review", price: "150" }, { currency: "USD" })!;
+    expect(schema["@type"]).toBe("Service");
+    expect(schema.offers).toMatchObject({ "@type": "Offer", price: 150 });
+    expect(schema).not.toHaveProperty("aggregateRating");
+  });
+
+  it("emits no offer for a free/unpriced entity's missing price", () => {
+    expect(buildServiceSchema({ title: "1:1 Mix Review", price: null }, { currency: "USD" })!).not.toHaveProperty(
+      "offers",
+    );
+    // Zero is a real price (a free course), not a missing one.
+    expect(buildCourseSchema({ ...COURSE, price: 0 }, { currency: "USD" })!.offers).toMatchObject({ price: 0 });
+  });
+});
+
+describe("buildEntitySchema + jsonLdScripts", () => {
+  it("keeps buildEntityReviewSchema as an alias so a deployed site's import survives", () => {
+    expect(buildEntityReviewSchema).toBe(buildEntitySchema);
+    // …and the alias no longer returns null for an unreviewed entity.
+    expect(buildEntityReviewSchema({ type: "Product", name: "Tote" })).not.toBeNull();
+  });
+
+  it("produces one ld+json script per non-null schema, and drops nulls", () => {
+    const scripts = jsonLdScripts(buildProductSchema(PRODUCT, { currency: "USD" }), null, undefined);
+    expect(scripts).toHaveLength(1);
+    expect(scripts[0].type).toBe("application/ld+json");
+    expect(JSON.parse(scripts[0].children)["@type"]).toBe("Product");
+  });
+
+  it("returns an empty array so a head() can spread it unconditionally", () => {
+    expect(jsonLdScripts(buildProductSchema(null))).toEqual([]);
+  });
+});

package/src/utils/presaleCode.ts

@@ -0,0 +1,96 @@
+/**
+ * Where a buyer's presale code lives between typing it and paying with it.
+ *
+ * ## Why this is a module-level store and not component state
+ *
+ * The code has to be in three places at once, in components that do not share a
+ * parent: the event page's own `useEvent` (to reveal the hidden tiers), the
+ * ticket modal's `useEventCheckout` (its own separate `useEvent`), and the
+ * order body (the sell guard re-checks the code on every purchase, so a buyer
+ * who unlocks a tier and then checks out without the code is refused AFTER
+ * entering their card). Threading it through props would work for one host app
+ * and break for every code-site that composes the Forge pieces differently.
+ *
+ * ## Why sessionStorage and not localStorage
+ *
+ * A presale code is a right to buy now, not a saved preference. Session scope
+ * survives the reload, the Stripe redirect and the back button — everything
+ * inside one purchase — and does not silently re-apply a spent code to a
+ * different show weeks later.
+ *
+ * Keyed per event, because two presales are two different codes.
+ */
+
+const KEY_PREFIX = "tn:presale:";
+
+/** eventKey → code, mirroring sessionStorage so reads are synchronous. */
+const memory = new Map<string, string>();
+const listeners = new Set<() => void>();
+
+/** Loaded lazily so a server render never touches storage. */
+const hydrated = new Set<string>();
+
+const storageKey = (eventKey: string) => `${KEY_PREFIX}${eventKey}`;
+
+function hydrate(eventKey: string): void {
+  if (hydrated.has(eventKey) || typeof window === "undefined") return;
+  hydrated.add(eventKey);
+  try {
+    const stored = window.sessionStorage.getItem(storageKey(eventKey));
+    if (stored) memory.set(eventKey, stored);
+  } catch {
+    // Private mode / disabled storage. The code still works for this render;
+    // it just will not survive a reload.
+  }
+}
+
+export function readPresaleCode(eventKey: string): string | null {
+  if (!eventKey) return null;
+  hydrate(eventKey);
+  return memory.get(eventKey) ?? null;
+}
+
+export function writePresaleCode(eventKey: string, code: string | null): void {
+  if (!eventKey) return;
+  hydrated.add(eventKey);
+  const trimmed = code?.trim();
+  if (trimmed) memory.set(eventKey, trimmed);
+  else memory.delete(eventKey);
+
+  if (typeof window !== "undefined") {
+    try {
+      if (trimmed) window.sessionStorage.setItem(storageKey(eventKey), trimmed);
+      else window.sessionStorage.removeItem(storageKey(eventKey));
+    } catch {
+      // As above — in-memory only.
+    }
+  }
+
+  for (const listener of listeners) listener();
+}
+
+export function subscribePresaleCode(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/**
+ * `?accessCode=PRESALE24` on the URL, so the link an artist mails to their list
+ * unlocks the page on arrival instead of asking the recipient to retype what
+ * they just clicked.
+ *
+ * The parameter is left ON the URL deliberately, unlike the attribution ref: a
+ * presale link is meant to be forwardable, and stripping it would break the
+ * one thing the recipient is most likely to do with it.
+ */
+export function readPresaleCodeFromUrl(): string | null {
+  if (typeof window === "undefined") return null;
+  try {
+    const value = new URL(window.location.href).searchParams.get("accessCode");
+    return value?.trim() || null;
+  } catch {
+    return null;
+  }
+}