@tribe-nest/forge 3.60.0 → 3.63.0

package/src/utils/metaEvents.ts

@@ -0,0 +1,302 @@
+// Meta conversion events from the browser: one call fires the profile pixel
+// AND posts the server (CAPI) copy, both carrying the same event id, so Meta
+// counts the pair once. Nothing here can send one half without the other.
+//
+// The policy (which pixel, whether Meta may run, where the API is) is set by
+// `<ForgeAnalytics/>` and read synchronously, so non-React code (the cart, a
+// mutation) can fire an event without threading props or context through.
+//
+// Consent is read LIVE from the consent store at send time. Without marketing
+// consent on a site that requires it, nothing is fired, posted, built or read:
+// no pixel call, no server copy, no `fbp` / `fbc`.
+
+import { newEventId } from "../data/queries/useAnalytics";
+import { getCookieConsent } from "./cookieConsent";
+import { readLandingClickId } from "./landing";
+import { fireMetaEventSingle, initMetaPixelScoped, readMetaCookies } from "./metaPixel";
+
+/** The browser signals every visitor-record create request carries (`metaSignals`). */
+export type MetaSignals = {
+  fbp?: string;
+  fbc?: string;
+  pageUrl?: string;
+  /** True: allowed (or the site does not require consent). False: declined. Absent: undecided. */
+  marketingConsent?: boolean;
+};
+
+/** What a create response carries when the server queued a Meta event for that record. */
+export type ServerMetaEvent = { name: string; eventId: string; customData?: Record<string, unknown> };
+
+export type MetaPolicy = {
+  /** The profile pixel id, if the profile has one. */
+  pixelId?: string;
+  /** False in the editor / preview: nothing is sent. */
+  enabled: boolean;
+  /** Whether marketing consent is required before Meta may run. */
+  requireConsent: boolean;
+  apiUrl?: string;
+  subdomain?: string;
+  /** The tenant's settlement currency, used when an event has a value but no currency. */
+  currency?: string;
+  /**
+   * False while the pixel id is still loading. Events fired before then wait
+   * (the detail page often mounts before the site config resolves).
+   */
+  resolved: boolean;
+};
+
+export type MetaCustomData = {
+  value?: number;
+  currency?: string;
+  content_ids?: string[];
+  content_name?: string;
+  content_type?: "product" | "product_group";
+  content_category?: string;
+  num_items?: number;
+  search_string?: string;
+  [key: string]: unknown;
+};
+
+let policy: MetaPolicy | null = null;
+const MAX_PENDING = 25;
+let pending: (() => void)[] = [];
+
+function isReady(): boolean {
+  return !!policy && (policy.resolved || !policy.enabled);
+}
+
+/** Run now if the policy is known, else once it is (bounded queue). */
+function whenReady(fn: () => void): void {
+  if (isReady()) {
+    fn();
+    return;
+  }
+  if (pending.length < MAX_PENDING) pending.push(fn);
+}
+
+/** Set by `<ForgeAnalytics/>`. Flushes events that were waiting for it. */
+export function setMetaPolicy(next: MetaPolicy): void {
+  policy = next;
+  if (!isReady() || pending.length === 0) return;
+  const queued = pending;
+  pending = [];
+  for (const fn of queued) {
+    try {
+      fn();
+    } catch {
+      // A tracking failure never breaks the page.
+    }
+  }
+}
+
+export function getMetaPolicy(): MetaPolicy | null {
+  return policy;
+}
+
+/** Test helper: forget the policy and anything queued. */
+export function resetMetaPolicy(): void {
+  policy = null;
+  pending = [];
+}
+
+/**
+ * The consent half of the Meta gate: true when the site does not require
+ * consent or the visitor allowed marketing, false when they declined,
+ * undefined while they have not decided.
+ */
+export function readMarketingConsent(): boolean | undefined {
+  if (policy && !policy.requireConsent) return true;
+  const consent = getCookieConsent();
+  if (!consent) return undefined;
+  return consent.marketing;
+}
+
+/** Whether a profile-pixel event may fire right now. */
+function profileAllowed(p: MetaPolicy | null): p is MetaPolicy & { pixelId: string } {
+  return !!p && p.enabled && !!p.pixelId && readMarketingConsent() === true;
+}
+
+function buildFbc(): string | undefined {
+  const landing = readLandingClickId("fbclid");
+  if (landing) return `fb.1.${landing.at}.${landing.value}`;
+  // The landing snapshot is written after the page's own effects run, so the
+  // very first page can still hold the click id only in its URL.
+  try {
+    const fbclid = new URL(window.location.href).searchParams.get("fbclid");
+    if (fbclid && fbclid.length <= 512) return `fb.1.${Date.now()}.${fbclid}`;
+  } catch {
+    // ignore
+  }
+  return undefined;
+}
+
+/**
+ * The `metaSignals` body field for a create request. `fbp` / `fbc` are read
+ * (or built) only when marketing is allowed; otherwise they are never touched.
+ */
+export function readMetaSignals(): MetaSignals {
+  if (typeof window === "undefined") return {};
+  const marketingConsent = readMarketingConsent();
+  const signals: MetaSignals = { pageUrl: window.location.href };
+  if (marketingConsent !== undefined) signals.marketingConsent = marketingConsent;
+  if (marketingConsent === true) {
+    const { fbp, fbc } = readMetaCookies();
+    if (fbp) signals.fbp = fbp;
+    const builtFbc = fbc || buildFbc();
+    if (builtFbc) signals.fbc = builtFbc;
+  }
+  return signals;
+}
+
+/** Drop empty fields, keep `value` only when it is a finite number, default the currency. */
+function normaliseCustomData(data: MetaCustomData | undefined, fallbackCurrency?: string): MetaCustomData | undefined {
+  if (!data) return undefined;
+  const out: MetaCustomData = {};
+  for (const [key, val] of Object.entries(data)) {
+    if (val === undefined || val === null || val === "") continue;
+    out[key] = val;
+  }
+  if ("value" in out) {
+    const n = Number(out.value);
+    if (Number.isFinite(n)) out.value = n;
+    else delete out.value;
+  }
+  if (typeof out.currency === "string") out.currency = out.currency.toUpperCase();
+  else if (out.value !== undefined && fallbackCurrency) out.currency = fallbackCurrency.toUpperCase();
+  if (Array.isArray(out.content_ids)) out.content_ids = out.content_ids.map(String).slice(0, 50);
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+type ServerCopy = {
+  pixel: "profile" | "page";
+  pathname?: string;
+  eventName: string;
+  eventId: string;
+  eventSourceUrl: string;
+  customData?: MetaCustomData;
+};
+
+/** POST the server copy. keepalive, like `trackBeacon`, so a navigation does not cancel it. */
+function postServerCopy(p: MetaPolicy, copy: ServerCopy): void {
+  if (!p.apiUrl || !p.subdomain || typeof fetch === "undefined") return;
+  try {
+    void fetch(`${p.apiUrl.replace(/\/$/, "")}/public/websites/meta-event`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      keepalive: true,
+      body: JSON.stringify({ subdomain: p.subdomain, ...copy, metaSignals: readMetaSignals() }),
+    }).catch(() => {});
+  } catch {
+    // Best effort; never disrupt the page.
+  }
+}
+
+function currentHref(): string {
+  return typeof window === "undefined" ? "" : window.location.href;
+}
+
+/**
+ * Fire a Meta event to the profile pixel AND post its server copy, with one
+ * event id. A no-op unless the profile has a pixel, Meta is enabled and
+ * marketing is allowed. Returns the event id.
+ */
+export function trackMeta(eventName: string, customData?: MetaCustomData, opts?: { eventId?: string }): string {
+  const eventId = opts?.eventId ?? newEventId();
+  if (typeof window === "undefined") return eventId;
+  const eventSourceUrl = currentHref();
+  whenReady(() => {
+    const p = policy;
+    if (!profileAllowed(p)) return;
+    const data = normaliseCustomData(customData, p.currency);
+    initMetaPixelScoped(p.pixelId);
+    fireMetaEventSingle(p.pixelId, eventName, data ?? {}, eventId);
+    postServerCopy(p, { pixel: "profile", eventName, eventId, eventSourceUrl, customData: data });
+  });
+  return eventId;
+}
+
+/**
+ * The server copy of an event fired to a PAGE (campaign) pixel. The caller
+ * fires the pixel itself and decides consent for it (`<PageMetaPixel/>`).
+ */
+export function sendPageMetaEvent(input: {
+  eventName: string;
+  eventId: string;
+  pathname: string;
+  customData?: MetaCustomData;
+}): void {
+  if (typeof window === "undefined") return;
+  const eventSourceUrl = currentHref();
+  whenReady(() => {
+    const p = policy;
+    if (!p || !p.enabled) return;
+    postServerCopy(p, {
+      pixel: "page",
+      pathname: input.pathname,
+      eventName: input.eventName,
+      eventId: input.eventId,
+      eventSourceUrl,
+      customData: normaliseCustomData(input.customData, p.currency),
+    });
+  });
+}
+
+/**
+ * The pixel copy of an event the SERVER already queued (a response's
+ * `metaEvent`). No server copy: it exists.
+ */
+export function firePixelOnly(eventName: string, eventId: string, customData?: MetaCustomData): void {
+  if (typeof window === "undefined" || !eventName || !eventId) return;
+  whenReady(() => {
+    const p = policy;
+    if (!profileAllowed(p)) return;
+    initMetaPixelScoped(p.pixelId);
+    fireMetaEventSingle(p.pixelId, eventName, normaliseCustomData(customData, p.currency) ?? {}, eventId);
+  });
+}
+
+/** Fire the pixel copy of a response's `metaEvent`, if it carries one. */
+export function fireServerMetaEvent(response: unknown): void {
+  const metaEvent = (response as { metaEvent?: ServerMetaEvent } | null | undefined)?.metaEvent;
+  if (!metaEvent || typeof metaEvent.name !== "string" || typeof metaEvent.eventId !== "string") return;
+  firePixelOnly(metaEvent.name, metaEvent.eventId, metaEvent.customData as MetaCustomData | undefined);
+}
+
+const PURCHASE_KEY_PREFIX = "tn:meta:purchase:";
+
+function purchaseAlreadyFired(eventId: string): boolean {
+  try {
+    return window.sessionStorage.getItem(PURCHASE_KEY_PREFIX + eventId) === "1";
+  } catch {
+    return false;
+  }
+}
+
+function markPurchaseFired(eventId: string): void {
+  try {
+    window.sessionStorage.setItem(PURCHASE_KEY_PREFIX + eventId, "1");
+  } catch {
+    // Storage disabled: a reload may fire it again, and Meta dedupes on the id.
+  }
+}
+
+/**
+ * The browser copy of a Purchase the server bridge sends on payment. The id is
+ * the record id the server used, so the two dedupe. Pixel only (the server
+ * copy is the bridge's), at most once per tab per record.
+ */
+export function trackPurchase(input: { recordId: string; value: number | string | null | undefined; currency?: string | null }): void {
+  if (typeof window === "undefined" || !input.recordId) return;
+  const value = Number(input.value);
+  if (!Number.isFinite(value) || value <= 0) return;
+  const eventId = input.recordId;
+  if (purchaseAlreadyFired(eventId)) return;
+  whenReady(() => {
+    const p = policy;
+    if (!profileAllowed(p) || purchaseAlreadyFired(eventId)) return;
+    const currency = (input.currency || p.currency || "").toUpperCase() || undefined;
+    initMetaPixelScoped(p.pixelId);
+    fireMetaEventSingle(p.pixelId, "Purchase", currency ? { value, currency } : { value }, eventId);
+    markPurchaseFired(eventId);
+  });
+}

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