@tribe-nest/forge 3.61.0 → 3.63.0

package/src/utils/structuredData.ts

@@ -1,4 +1,6 @@
-import type { WebPage } from "../types";
+import type { IEvent, ITicket, WebPage } from "../types";
+import type { SeoIdentity } from "../seo/types";
+import { ticketSeatsUnsold } from "../ui/format/ticketAvailability";
 
 /**
  * Generates Organization/Person JSON-LD for every page.
@@ -529,3 +531,339 @@ export function jsonLdScripts(
     .filter((s): s is Record<string, unknown> => !!s)
     .map((s) => ({ type: "application/ld+json", children: JSON.stringify(s) }));
 }
+
+// ---- Events, posts, podcasts, the site and who runs it --------------------------
+//
+// Same rule as the sellables above: say only what the page itself says. A
+// cancelled event is still described (so a search result can show it as
+// cancelled) but sells nothing; a tier nobody may buy anonymously gets no
+// offer; a missing currency drops the offers rather than guessing one.
+
+/** A post's or episode's author, and the site's publisher, as the SEO record names them. */
+export type SchemaIdentityInput = Pick<SeoIdentity, "kind" | "name"> & Partial<Omit<SeoIdentity, "kind" | "name">>;
+
+const schemaTypeForIdentity = (kind: SeoIdentity["kind"]) =>
+  kind === "person" ? "Person" : kind === "local_business" ? "LocalBusiness" : "Organization";
+
+const cleanUrls = (urls?: (string | null | undefined)[] | null) =>
+  (urls ?? []).filter((u): u is string => typeof u === "string" && /^https?:\/\//i.test(u.trim())).map((u) => u.trim());
+
+function postalAddress(address?: SeoIdentity["address"]): Record<string, unknown> | undefined {
+  if (!address) return undefined;
+  const node = {
+    ...(address.street ? { streetAddress: address.street } : {}),
+    ...(address.locality ? { addressLocality: address.locality } : {}),
+    ...(address.region ? { addressRegion: address.region } : {}),
+    ...(address.postalCode ? { postalCode: address.postalCode } : {}),
+    ...(address.country ? { addressCountry: address.country } : {}),
+  };
+  return Object.keys(node).length ? { "@type": "PostalAddress", ...node } : undefined;
+}
+
+/** A short reference to the identity, for `author` / `publisher` inside another node. */
+function identityRef(identity?: SchemaIdentityInput | null, origin?: string | null): Record<string, unknown> | undefined {
+  const name = identity?.name?.trim();
+  if (!identity || !name) return undefined;
+  return {
+    "@type": schemaTypeForIdentity(identity.kind),
+    name,
+    ...(origin ? { url: origin } : {}),
+    ...(identity.logo && identity.kind !== "person" ? { logo: identity.logo } : {}),
+  };
+}
+
+/** The `@id` the WebSite node's `publisher` points at, so the two link up. */
+export const identitySchemaId = (origin: string) => `${origin.replace(/\/+$/, "")}/#identity`;
+
+/**
+ * schema.org Person, Organization or LocalBusiness for whoever runs the site.
+ *
+ * `logo` is an Organization property; a Person carries the same picture as
+ * `image`. `address` and `telephone` are emitted for any kind that has them,
+ * because a coach working from a studio is as findable by address as a shop.
+ */
+export function buildIdentitySchema(
+  identity: SchemaIdentityInput | null | undefined,
+  options: { origin?: string | null } = {},
+): Record<string, unknown> | null {
+  const name = identity?.name?.trim();
+  if (!identity || !name) return null;
+  const origin = options.origin?.replace(/\/+$/, "");
+  const sameAs = cleanUrls(identity.sameAs);
+  const address = postalAddress(identity.address);
+  return {
+    "@context": "https://schema.org",
+    "@type": schemaTypeForIdentity(identity.kind),
+    ...(origin ? { "@id": identitySchemaId(origin), url: origin } : {}),
+    name,
+    ...(identity.logo ? (identity.kind === "person" ? { image: identity.logo } : { logo: identity.logo }) : {}),
+    ...(sameAs.length ? { sameAs } : {}),
+    ...(address ? { address } : {}),
+    ...(identity.phone ? { telephone: identity.phone } : {}),
+  };
+}
+
+/** schema.org/WebSite for the home page. */
+export function buildWebSiteSchema(input: {
+  name: string;
+  url: string;
+  description?: string | null;
+  /** Links the site to its identity node by `@id`. */
+  publisherId?: string | null;
+}): Record<string, unknown> | null {
+  const name = input.name?.trim();
+  if (!name || !input.url) return null;
+  return {
+    "@context": "https://schema.org",
+    "@type": "WebSite",
+    name,
+    url: input.url,
+    ...(input.description ? { description: input.description } : {}),
+    ...(input.publisherId ? { publisher: { "@id": input.publisherId } } : {}),
+  };
+}
+
+/** schema.org/BreadcrumbList. Each item needs an absolute URL, so pass full ones. */
+export function buildBreadcrumbSchema(items: { name: string; url: string }[]): Record<string, unknown> | null {
+  const list = items.filter((i) => i.name?.trim() && i.url);
+  if (list.length < 2) return null;
+  return {
+    "@context": "https://schema.org",
+    "@type": "BreadcrumbList",
+    itemListElement: list.map((item, index) => ({
+      "@type": "ListItem",
+      position: index + 1,
+      name: item.name.trim(),
+      item: item.url,
+    })),
+  };
+}
+
+/** Structural view of `GET /public/events/:id`. `IEvent` satisfies it. */
+export interface EventSchemaSource {
+  title: string;
+  description?: string | null;
+  dateTime: string;
+  endDateTime?: string | null;
+  doorsOpenAt?: string | null;
+  status?: IEvent["status"];
+  cancelledAt?: string | null;
+  type: IEvent["type"];
+  address?: IEvent["address"] | null;
+  media?: { url: string; type?: string }[] | null;
+  tickets?: Pick<
+    ITicket,
+    "title" | "price" | "quantity" | "sold" | "availableFrom" | "archivedAt" | "isHidden" | "membershipGate"
+  >[];
+  membershipGate?: { allowed: boolean } | null;
+  bookingFee?: { currency: string } | null;
+}
+
+const ATTENDANCE_MODE: Record<IEvent["type"], string> = {
+  physical: "https://schema.org/OfflineEventAttendanceMode",
+  virtual: "https://schema.org/OnlineEventAttendanceMode",
+  hybrid: "https://schema.org/MixedEventAttendanceMode",
+};
+
+/**
+ * schema.org/Event.
+ *
+ * `offers` is one Offer per public ticket tier, priced in the event's own
+ * settlement currency. A tier is left out when it is hidden, archived or
+ * members-only; a members-only EVENT sells nothing to the anonymous visitor
+ * Googlebot is, so it has no offers at all. Neither has a cancelled or finished
+ * event: there is nothing left to buy.
+ *
+ * A virtual event's location is a VirtualLocation at the event page itself,
+ * which is where a ticket-holder is let in. A hybrid event carries both.
+ */
+export function buildEventSchema(
+  event: EventSchemaSource | null | undefined,
+  options: SellableSchemaOptions & { organizer?: SchemaIdentityInput | null; origin?: string | null } = {},
+): Record<string, unknown> | null {
+  const name = event?.title?.trim();
+  if (!event || !name || !event.dateTime) return null;
+
+  const cancelled = event.status === "cancelled" || !!event.cancelledAt;
+  const description = toSchemaText(event.description);
+  const images = imageUrls(event.media);
+
+  const place = (() => {
+    if (event.type === "virtual" || !event.address) return undefined;
+    const a = event.address;
+    const address = postalAddress({
+      street: a.street || undefined,
+      locality: a.city || undefined,
+      region: a.state || undefined,
+      postalCode: a.zipCode || undefined,
+      country: a.country || undefined,
+    });
+    return { "@type": "Place", ...(a.name ? { name: a.name } : {}), ...(address ? { address } : {}) };
+  })();
+  const virtual =
+    event.type !== "physical" && options.url ? { "@type": "VirtualLocation", url: options.url } : undefined;
+  const locations = [place, virtual].filter(Boolean);
+
+  const currency = event.bookingFee?.currency || options.currency || undefined;
+  const sellable =
+    !!currency &&
+    !cancelled &&
+    event.status !== "completed" &&
+    !(event.membershipGate && event.membershipGate.allowed === false);
+  const now = Date.now();
+  const offers = sellable
+    ? (event.tickets ?? [])
+        .filter((t) => !t.archivedAt && !t.isHidden && !(t.membershipGate && t.membershipGate.allowed === false))
+        .map((t) => {
+          const price = toPrice(t.price);
+          if (price === undefined) return null;
+          const notYet = !!t.availableFrom && Date.parse(t.availableFrom) > now;
+          const soldOut = event.status === "sold_out" || ticketSeatsUnsold(t) <= 0;
+          return {
+            "@type": "Offer",
+            ...(t.title ? { name: t.title } : {}),
+            price: money(price),
+            priceCurrency: currency,
+            availability: `https://schema.org/${soldOut ? "SoldOut" : notYet ? "PreOrder" : "InStock"}`,
+            ...(t.availableFrom ? { validFrom: t.availableFrom } : {}),
+            ...(options.url ? { url: options.url } : {}),
+          };
+        })
+        .filter((o): o is NonNullable<typeof o> => !!o)
+    : [];
+
+  const organizer =
+    identityRef(options.organizer, options.origin) ??
+    (options.brand ? { "@type": "Organization", name: options.brand } : undefined);
+
+  return {
+    "@context": "https://schema.org",
+    "@type": "Event",
+    name,
+    startDate: event.dateTime,
+    ...(event.endDateTime ? { endDate: event.endDateTime } : {}),
+    ...(event.doorsOpenAt ? { doorTime: event.doorsOpenAt } : {}),
+    eventStatus: `https://schema.org/${cancelled ? "EventCancelled" : "EventScheduled"}`,
+    eventAttendanceMode: ATTENDANCE_MODE[event.type] ?? ATTENDANCE_MODE.physical,
+    ...(locations.length ? { location: locations.length === 1 ? locations[0] : locations } : {}),
+    ...(description ? { description } : {}),
+    ...(images.length ? { image: images.length === 1 ? images[0] : images } : {}),
+    ...(options.url ? { url: options.url } : {}),
+    ...(organizer ? { organizer } : {}),
+    ...(offers.length ? { offers: offers.length === 1 ? offers[0] : offers } : {}),
+  };
+}
+
+/** Structural view of `GET /public/blog/posts/:id`. `BlogPost` satisfies it. */
+export interface BlogPostingSchemaSource {
+  title: string;
+  content?: string | null;
+  publishedAt?: string | null;
+  updatedAt?: string | null;
+  media?: { url: string; type?: string }[] | null;
+}
+
+/** schema.org/BlogPosting. `author` and `publisher` both come from the site's identity. */
+export function buildBlogPostingSchema(
+  post: BlogPostingSchemaSource | null | undefined,
+  options: { url?: string | null; identity?: SchemaIdentityInput | null; origin?: string | null } = {},
+): Record<string, unknown> | null {
+  const headline = post?.title?.trim();
+  if (!post || !headline) return null;
+  const description = toSchemaText(post.content, 300);
+  const images = imageUrls((post.media ?? []).filter((m) => (m.type ?? "").startsWith("image")));
+  const author = identityRef(options.identity, options.origin);
+  return {
+    "@context": "https://schema.org",
+    "@type": "BlogPosting",
+    // Google truncates a headline past 110 characters; clamping keeps it valid.
+    headline: headline.length > 110 ? `${headline.slice(0, 109).trimEnd()}…` : headline,
+    ...(description ? { description } : {}),
+    ...(post.publishedAt ? { datePublished: post.publishedAt } : {}),
+    ...(post.updatedAt || post.publishedAt ? { dateModified: post.updatedAt || post.publishedAt } : {}),
+    ...(images.length ? { image: images.length === 1 ? images[0] : images } : {}),
+    ...(options.url ? { url: options.url, mainEntityOfPage: { "@type": "WebPage", "@id": options.url } } : {}),
+    ...(author ? { author } : {}),
+    ...(author && options.identity?.kind !== "person" ? { publisher: author } : {}),
+  };
+}
+
+/** Structural view of a podcast show. `PodcastShow` and `BlogCategory` both satisfy it. */
+export interface PodcastSeriesSchemaSource {
+  title: string;
+  description?: string | null;
+  coverImage?: { url: string } | null;
+  author?: string | null;
+}
+
+/** schema.org/PodcastSeries. */
+export function buildPodcastSeriesSchema(
+  show: PodcastSeriesSchemaSource | null | undefined,
+  options: { url?: string | null; identity?: SchemaIdentityInput | null; origin?: string | null } = {},
+): Record<string, unknown> | null {
+  const name = show?.title?.trim();
+  if (!show || !name) return null;
+  const description = toSchemaText(show.description);
+  const author = show.author?.trim()
+    ? { "@type": "Person", name: show.author.trim() }
+    : identityRef(options.identity, options.origin);
+  return {
+    "@context": "https://schema.org",
+    "@type": "PodcastSeries",
+    name,
+    ...(description ? { description } : {}),
+    ...(show.coverImage?.url ? { image: show.coverImage.url } : {}),
+    ...(options.url ? { url: options.url } : {}),
+    ...(author ? { author } : {}),
+  };
+}
+
+/** Structural view of a podcast episode (a blog post with an audio medium). */
+export interface PodcastEpisodeSchemaSource {
+  title: string;
+  content?: string | null;
+  publishedAt?: string | null;
+  media?: { url: string; type?: string; durationSec?: number | null }[] | null;
+}
+
+/** schema.org/PodcastEpisode, linked to its series. */
+export function buildPodcastEpisodeSchema(
+  episode: PodcastEpisodeSchemaSource | null | undefined,
+  options: { url?: string | null; series?: { name: string; url?: string | null } | null } = {},
+): Record<string, unknown> | null {
+  const name = episode?.title?.trim();
+  if (!episode || !name) return null;
+  const description = toSchemaText(episode.content);
+  const audio = (episode.media ?? []).find((m) => (m.type ?? "").startsWith("audio"));
+  const image = (episode.media ?? []).find((m) => (m.type ?? "").startsWith("image"))?.url;
+  const duration = isoDuration(audio?.durationSec);
+  return {
+    "@context": "https://schema.org",
+    "@type": "PodcastEpisode",
+    name,
+    ...(description ? { description } : {}),
+    ...(episode.publishedAt ? { datePublished: episode.publishedAt } : {}),
+    ...(options.url ? { url: options.url } : {}),
+    ...(image ? { image } : {}),
+    ...(duration ? { timeRequired: duration } : {}),
+    ...(audio?.url
+      ? {
+          associatedMedia: {
+            "@type": "MediaObject",
+            contentUrl: audio.url,
+            ...(audio.type ? { encodingFormat: audio.type } : {}),
+            ...(duration ? { duration } : {}),
+          },
+        }
+      : {}),
+    ...(options.series?.name
+      ? {
+          partOfSeries: {
+            "@type": "PodcastSeries",
+            name: options.series.name,
+            ...(options.series.url ? { url: options.series.url } : {}),
+          },
+        }
+      : {}),
+  };
+}