@tribe-nest/forge 3.20.0 → 3.22.0

package/src/utils/structuredData.ts

@@ -45,10 +45,29 @@ export function buildJsonLdScript(...schemas: Record<string, unknown>[]): string
     .join("");
 }
 
-// ---- Reviews / AggregateRating ------------------------------------------------
+// ---- Sellable entities (Product / Course / Service) ---------------------------
+//
+// ⚠️ THE RULE HERE: reviews ENRICH structured data, they do not GATE it.
+//
+// This file used to return `null` whenever an entity had no review aggregate,
+// so a product nobody had reviewed yet emitted no schema.org/Product at all —
+// no rich result, no free Shopping listing, for exactly the products that need
+// them most. `aggregateRating` is now the only part that waits for reviews
+// (an empty or zero rating is a schema violation Google penalises, so ABSENT is
+// the correct representation of "no reviews yet"); the entity node itself is
+// emitted for every published thing.
+//
+// The other half of the rule: never state a fact the storefront does not have.
+// An `Offer` is emitted only with a real settlement currency, its `availability`
+// mirrors the same `availabilityStatus` the Add-to-cart button reads, and a
+// membership-gated entity gets NO offer at all — the anonymous visitor (and
+// Googlebot, which is anonymous) cannot buy it at that price.
 
 export type ReviewSchemaEntityType = "Product" | "Course" | "Service";
 
+/** schema.org ItemAvailability values this codebase can honestly assert. */
+export type SchemaAvailability = "InStock" | "OutOfStock";
+
 export interface ReviewSchemaAggregate {
   avgRating: number;
   reviewCount: number;
@@ -62,29 +81,110 @@ export interface ReviewSchemaReview {
   publishedAt?: string | null;
 }
 
-export interface EntityReviewSchemaInput {
-  /** schema.org type of the reviewed thing. */
+/**
+ * An offer, in major units of `currency`.
+ *
+ * Pass `price` for a single fixed price (→ `Offer`), or `lowPrice`/`highPrice`
+ * for a range (→ `AggregateOffer`). `highPrice` is omitted for an open-ended
+ * pay-what-you-want floor, which genuinely has no ceiling.
+ */
+export interface EntityOfferInput {
+  /** ISO 4217 code. REQUIRED — an Offer without a currency is invalid, so a
+   * missing one drops the whole offers node rather than guessing USD. */
+  currency: string;
+  price?: number;
+  lowPrice?: number;
+  highPrice?: number;
+  offerCount?: number;
+  availability?: SchemaAvailability;
+  url?: string | null;
+}
+
+export interface EntitySchemaInput {
+  /** schema.org type of the thing. */
   type: ReviewSchemaEntityType;
   name: string;
   description?: string | null;
-  image?: string | null;
+  /** One URL or several (Google prefers multiple aspect ratios). */
+  image?: string | string[] | null;
   url?: string | null;
+  /** The creator's name — rendered as `brand` on Product, `provider` otherwise. */
+  brand?: string | null;
   aggregate?: ReviewSchemaAggregate | null;
   /** A sample of published reviews (top-N is fine — Google reads a subset). */
   reviews?: ReviewSchemaReview[];
-  /** Optional offer (price in major units + ISO currency) for Product rich results. */
-  offer?: { price: number; currency: string } | null;
+  /** Offer/AggregateOffer. Omit for anything the visitor cannot actually buy. */
+  offer?: EntityOfferInput | null;
+}
+
+/** @deprecated Renamed to {@link EntitySchemaInput} — reviews are no longer what this is about. */
+export type EntityReviewSchemaInput = EntitySchemaInput;
+
+const money = (n: number) => Number(n.toFixed(2));
+
+/**
+ * A price, or `undefined` when there isn't one.
+ *
+ * `Number(null)` and `Number("")` are both `0`, so a naive coercion turns "this
+ * response has no price" into "this thing is free" — a claim the storefront
+ * never makes. Zero itself IS a real price (a free course), so only
+ * null/undefined/blank are rejected.
+ */
+function toPrice(value: unknown): number | undefined {
+  if (value === null || value === undefined) return undefined;
+  if (typeof value === "string" && value.trim() === "") return undefined;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+function buildOffersNode(offer?: EntityOfferInput | null): Record<string, unknown> | undefined {
+  if (!offer || !offer.currency) return undefined;
+  const availability = offer.availability ? { availability: `https://schema.org/${offer.availability}` } : {};
+  const url = offer.url ? { url: offer.url } : {};
+
+  const isRange = offer.price === undefined && offer.lowPrice !== undefined;
+  if (isRange) {
+    if (!Number.isFinite(offer.lowPrice as number)) return undefined;
+    return {
+      "@type": "AggregateOffer",
+      priceCurrency: offer.currency,
+      lowPrice: money(offer.lowPrice as number),
+      ...(offer.highPrice !== undefined && Number.isFinite(offer.highPrice)
+        ? { highPrice: money(offer.highPrice) }
+        : {}),
+      ...(offer.offerCount !== undefined ? { offerCount: offer.offerCount } : {}),
+      ...availability,
+      ...url,
+    };
+  }
+
+  if (offer.price === undefined || !Number.isFinite(offer.price)) return undefined;
+  return {
+    "@type": "Offer",
+    priceCurrency: offer.currency,
+    price: money(offer.price),
+    ...availability,
+    ...url,
+  };
 }
 
 /**
- * Generates schema.org JSON-LD for a reviewed entity: the entity node with an
- * `AggregateRating` and a sample of `Review` children — the shape Google reads
- * for star rich snippets. Returns null when there is no aggregate (no
- * published reviews), so callers can skip the script tag entirely.
+ * schema.org JSON-LD for a sellable entity — Product, Course or Service.
+ *
+ * Returns `null` only when there is no `name`, i.e. nothing truthful to say.
+ * A missing review aggregate simply omits `aggregateRating`; it never
+ * suppresses the node. See the rule at the top of this section.
  */
-export function buildEntityReviewSchema(input: EntityReviewSchemaInput): Record<string, unknown> | null {
+export function buildEntitySchema(input: EntitySchemaInput): Record<string, unknown> | null {
+  const name = input.name?.trim();
+  if (!name) return null;
+
   const { aggregate } = input;
-  if (!aggregate || aggregate.reviewCount <= 0) return null;
+  const hasRatings =
+    !!aggregate &&
+    aggregate.reviewCount > 0 &&
+    Number.isFinite(aggregate.avgRating) &&
+    aggregate.avgRating > 0;
 
   const reviews = (input.reviews ?? [])
     .filter((r) => r.rating >= 1 && r.rating <= 5)
@@ -98,29 +198,263 @@ export function buildEntityReviewSchema(input: EntityReviewSchemaInput): Record<
       ...(r.publishedAt ? { datePublished: r.publishedAt } : {}),
     }));
 
+  const images = (Array.isArray(input.image) ? input.image : input.image ? [input.image] : []).filter(Boolean);
+  const offers = buildOffersNode(input.offer);
+  // Product takes `brand`; Course and Service take `provider`. Organization is
+  // a valid value for all three, so one node shape serves every type.
+  const brandKey = input.type === "Product" ? "brand" : "provider";
+
   return {
     "@context": "https://schema.org",
     "@type": input.type,
-    name: input.name,
+    name,
     ...(input.description ? { description: input.description } : {}),
-    ...(input.image ? { image: input.image } : {}),
+    ...(images.length > 0 ? { image: images.length === 1 ? images[0] : images } : {}),
     ...(input.url ? { url: input.url } : {}),
-    aggregateRating: {
-      "@type": "AggregateRating",
-      ratingValue: Number(aggregate.avgRating.toFixed(2)),
-      reviewCount: aggregate.reviewCount,
-      bestRating: 5,
-      worstRating: 1,
-    },
-    ...(reviews.length > 0 ? { review: reviews } : {}),
-    ...(input.offer
+    ...(input.brand ? { [brandKey]: { "@type": "Organization", name: input.brand } } : {}),
+    ...(offers ? { offers } : {}),
+    ...(hasRatings
       ? {
-          offers: {
-            "@type": "Offer",
-            price: input.offer.price,
-            priceCurrency: input.offer.currency,
+          aggregateRating: {
+            "@type": "AggregateRating",
+            ratingValue: Number(aggregate!.avgRating.toFixed(2)),
+            reviewCount: aggregate!.reviewCount,
+            bestRating: 5,
+            worstRating: 1,
           },
         }
       : {}),
+    ...(reviews.length > 0 ? { review: reviews } : {}),
   };
 }
+
+/**
+ * @deprecated Use {@link buildEntitySchema}. Kept because Forge is a published
+ * SDK and a deployed site may import this name. Behaviour is now IDENTICAL —
+ * in particular it no longer returns null for an unreviewed entity.
+ */
+export const buildEntityReviewSchema = buildEntitySchema;
+
+// ---- Mapping the public API payloads onto the schema --------------------------
+//
+// These live here (not in a route) so the client PWA and a code website derive
+// the same JSON-LD from the same response, and a fix reaches both stacks.
+
+/** Strip tags/entities and clamp, for a JSON-LD `description`. */
+export function toSchemaText(html?: string | null, max = 500): string | undefined {
+  if (!html) return undefined;
+  const text = html
+    .replace(/<[^>]*>/g, " ")
+    .replace(/&[a-z]+;/gi, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!text) return undefined;
+  return text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text;
+}
+
+const imageUrls = (media?: { url: string; type?: string }[] | null) => {
+  const all = media ?? [];
+  const images = all.filter((m) => (m.type ?? "").startsWith("image")).map((m) => m.url);
+  // A product with no typed images still has SOMETHING to show; the storefront
+  // falls back to the first medium, so match it rather than emitting nothing.
+  return (images.length > 0 ? images : all.slice(0, 1).map((m) => m.url)).filter(Boolean).slice(0, 6);
+};
+
+/** Structural view of `GET /public/products/:id` — `IPublicProduct` satisfies it. */
+export interface ProductSchemaSource {
+  title: string;
+  description?: string | null;
+  artist?: string | null;
+  media?: { url: string; type?: string }[] | null;
+  variants?: {
+    price: number | string;
+    availabilityStatus?: string;
+    payWhatYouWant?: boolean | null;
+    payWhatYouWantMaximum?: number | null;
+  }[];
+  reviewAggregate?: ReviewSchemaAggregate | null;
+  /** Present (and `allowed:false`) when the caller may not buy this. */
+  membershipGate?: { allowed: boolean } | null;
+}
+
+export interface SellableSchemaOptions {
+  /** The tenant's settlement currency. Without it NO offer is emitted. */
+  currency?: string | null;
+  /** Absolute canonical URL of the page. Omit rather than guess an origin. */
+  url?: string | null;
+  /** The creator's display name (Product `brand`, Course/Service `provider`). */
+  brand?: string | null;
+  /** A sample of published reviews, when the caller fetched them. */
+  reviews?: ReviewSchemaReview[];
+}
+
+/**
+ * The tenant facts every builder here needs, as a route can obtain them.
+ *
+ * ⚠️ A detail route must fetch this in its OWN loader (`fetchSeoContextServer`
+ * from `@tribe-nest/forge/server`) — NOT read it off the root match. During SSR,
+ * TanStack hands a child route's `head()` a `matches` array whose parent entries
+ * still carry `loaderData: null`, so the root's already-fetched site config is
+ * invisible there and every `offers` node silently disappears.
+ */
+export type SiteSeoContext = Pick<SellableSchemaOptions, "currency" | "brand">;
+
+/** Narrow a tenant's site config down to the two facts the builders read. */
+export function seoContextFromSiteConfig(
+  config?: { currency?: string; siteName?: string | null } | null,
+): SiteSeoContext {
+  if (!config) return {};
+  return { currency: config.currency || undefined, brand: config.siteName || undefined };
+}
+
+/**
+ * The offer for a product, derived from its variants.
+ *
+ * - No currency, no variants, or a membership gate the caller fails → no offer.
+ * - One fixed price → `Offer`.
+ * - Several prices, or pay-what-you-want (where `price` is the FLOOR) →
+ *   `AggregateOffer`; an unbounded PWYW variant leaves `highPrice` off because
+ *   there genuinely is no ceiling.
+ * - `availability` mirrors `availabilityStatus`, the exact field the
+ *   Add-to-cart button reads on both stacks.
+ */
+function deriveProductOffer(product: ProductSchemaSource, currency?: string | null): EntityOfferInput | null {
+  if (!currency) return null;
+  if (product.membershipGate && product.membershipGate.allowed === false) return null;
+
+  const variants = (product.variants ?? [])
+    .map((v) => ({ ...v, price: toPrice(v.price) }))
+    .filter((v): v is typeof v & { price: number } => v.price !== undefined);
+  if (variants.length === 0) return null;
+
+  const availability: SchemaAvailability = variants.some((v) => (v.availabilityStatus ?? "active") === "active")
+    ? "InStock"
+    : "OutOfStock";
+
+  const floors = variants.map((v) => v.price);
+  const lowPrice = Math.min(...floors);
+  const anyPayWhatYouWant = variants.some((v) => !!v.payWhatYouWant);
+
+  if (!anyPayWhatYouWant) {
+    const highPrice = Math.max(...floors);
+    if (lowPrice === highPrice) return { currency, price: lowPrice, availability };
+    return { currency, lowPrice, highPrice, offerCount: variants.length, availability };
+  }
+
+  const openEnded = variants.some((v) => v.payWhatYouWant && toPrice(v.payWhatYouWantMaximum) === undefined);
+  const ceilings = variants.map((v) => (v.payWhatYouWant ? (toPrice(v.payWhatYouWantMaximum) ?? v.price) : v.price));
+  return {
+    currency,
+    lowPrice,
+    ...(openEnded ? {} : { highPrice: Math.max(...ceilings) }),
+    offerCount: variants.length,
+    availability,
+  };
+}
+
+/** schema.org/Product for a public product — emitted whether or not it has reviews. */
+export function buildProductSchema(
+  product: ProductSchemaSource | null | undefined,
+  options: SellableSchemaOptions = {},
+): Record<string, unknown> | null {
+  if (!product?.title) return null;
+  return buildEntitySchema({
+    type: "Product",
+    name: product.title,
+    description: toSchemaText(product.description),
+    image: imageUrls(product.media),
+    url: options.url ?? undefined,
+    // The release artist when there is one, otherwise the creator — both are
+    // the name a buyer would call the brand.
+    brand: product.artist?.trim() || options.brand || undefined,
+    aggregate: product.reviewAggregate ?? null,
+    reviews: options.reviews,
+    offer: deriveProductOffer(product, options.currency),
+  });
+}
+
+/** Structural view of `GET /public/courses/:id` — `PublicCourse` satisfies it. */
+export interface CourseSchemaSource {
+  title: string;
+  description?: string | null;
+  media?: { url: string; type?: string }[] | null;
+  price?: number | string | null;
+  reviewAggregate?: ReviewSchemaAggregate | null;
+  membershipGate?: { allowed: boolean } | null;
+}
+
+/**
+ * schema.org/Course for a public course.
+ *
+ * `hasCourseInstance` is deliberately absent: these courses are self-paced with
+ * no scheduled instance, and inventing one to chase the Course rich result
+ * would be a claim the platform cannot back.
+ */
+export function buildCourseSchema(
+  course: CourseSchemaSource | null | undefined,
+  options: SellableSchemaOptions = {},
+): Record<string, unknown> | null {
+  if (!course?.title) return null;
+  const price = toPrice(course.price);
+  const gated = !!course.membershipGate && course.membershipGate.allowed === false;
+  return buildEntitySchema({
+    type: "Course",
+    name: course.title,
+    description: toSchemaText(course.description),
+    image: imageUrls(course.media),
+    url: options.url ?? undefined,
+    brand: options.brand ?? undefined,
+    aggregate: course.reviewAggregate ?? null,
+    reviews: options.reviews,
+    offer:
+      options.currency && !gated && price !== undefined
+        ? { currency: options.currency, price, availability: "InStock" }
+        : null,
+  });
+}
+
+/** Structural view of `GET /public/coaching/products/:id` — `CoachingProduct` satisfies it. */
+export interface ServiceSchemaSource {
+  title: string;
+  description?: string | null;
+  media?: { url: string; type?: string }[] | null;
+  price?: number | string | null;
+  reviewAggregate?: ReviewSchemaAggregate | null;
+}
+
+/** schema.org/Service for a coaching product. */
+export function buildServiceSchema(
+  service: ServiceSchemaSource | null | undefined,
+  options: SellableSchemaOptions = {},
+): Record<string, unknown> | null {
+  if (!service?.title) return null;
+  const price = toPrice(service.price);
+  return buildEntitySchema({
+    type: "Service",
+    name: service.title,
+    description: toSchemaText(service.description),
+    image: imageUrls(service.media),
+    url: options.url ?? undefined,
+    brand: options.brand ?? undefined,
+    aggregate: service.reviewAggregate ?? null,
+    reviews: options.reviews,
+    offer:
+      options.currency && price !== undefined
+        ? { currency: options.currency, price, availability: "InStock" }
+        : null,
+  });
+}
+
+/**
+ * The `scripts` entry a TanStack `head()` needs for a JSON-LD node. Returns an
+ * empty array for a null schema, so it can be spread unconditionally:
+ *
+ *   return { ...buildHeadMeta(...), scripts: jsonLdScripts(buildProductSchema(...)) };
+ */
+export function jsonLdScripts(
+  ...schemas: (Record<string, unknown> | null | undefined)[]
+): { type: string; children: string }[] {
+  return schemas
+    .filter((s): s is Record<string, unknown> => !!s)
+    .map((s) => ({ type: "application/ld+json", children: JSON.stringify(s) }));
+}