@tribe-nest/forge 3.63.0 → 3.65.0

package/src/seo/index.ts

@@ -7,3 +7,4 @@ export * from "./resolve";
 export * from "./seoHead";
 export * from "./siteSeoHead";
 export * from "./applySeoToHead";
+export * from "./markdown";

package/src/seo/markdown.ts

@@ -0,0 +1,76 @@
+import { normalizePathname } from "./resolve";
+import type { SeoLinkEntry, SeoRecord } from "./types";
+
+/**
+ * Readable copies for agents (docs/proposals/seo-initiative.md, section 5.4).
+ *
+ * The edge answers `Accept: text/markdown` or `?md` on a page with Markdown.
+ * These helpers decide which pages have such a copy, so a page only ever
+ * advertises one the edge will actually serve.
+ *
+ * KEEP IN STEP with `isMarkdownPath` in apps/dispatch-worker/src/markdown.ts.
+ * The dispatch Worker does not depend on Forge, so the rule is written twice;
+ * both specs run the same table of paths.
+ */
+
+/** Hosted families with a public page per item. Everything else under /i/ is private or transactional. */
+export const MARKDOWN_HOSTED_FAMILIES = [
+  "store",
+  "events",
+  "courses",
+  "coaching",
+  "blog",
+  "blog-category",
+  "podcasts",
+  "films",
+  "series",
+  "communities",
+] as const;
+
+/** Segments that mark a step in a flow, not a page about something. */
+const FLOW_SEGMENTS = new Set(["finalise", "library", "claim", "watch"]);
+
+/** Whether the edge serves a Markdown copy of this path. */
+export function isMarkdownPath(pathname: string): boolean {
+  const path = normalizePathname(pathname);
+  if (path.startsWith("/api/") || path.startsWith("/__tn/") || path.startsWith("/.well-known/")) return false;
+  const segments = path.split("/").filter(Boolean);
+  // A file, not a page: `/logo.png`, `/sw.js`, `/robots.txt`.
+  const last = segments[segments.length - 1] ?? "";
+  if (last.includes(".")) return false;
+  if (segments[0] !== "i") return true;
+
+  const [, family, ...rest] = segments;
+  if (!family || !(MARKDOWN_HOSTED_FAMILIES as readonly string[]).includes(family)) return false;
+  if (rest.some((s) => FLOW_SEGMENTS.has(s))) return false;
+  // The index and one item. A podcast episode is the one page a level deeper.
+  return rest.length <= (family === "podcasts" ? 2 : 1);
+}
+
+/**
+ * Where the Markdown copy of a page lives: the canonical with `md` added, when
+ * the canonical is one of this profile's websites (they all serve Markdown).
+ * A canonical pointing anywhere else may not, so the page's own URL is used.
+ */
+export function markdownAlternateHref(seo: SeoRecord, pathname: string, canonical?: string | null): string {
+  const own = [seo.origin, seo.defaultWebsiteOrigin].filter(Boolean).map((o) => o.replace(/\/+$/, ""));
+  const onOurs = !!canonical && own.some((o) => canonical === o || canonical.startsWith(`${o}/`));
+  const path = normalizePathname(pathname);
+  const base = onOurs ? canonical! : `${seo.origin.replace(/\/+$/, "")}${path === "/" ? "/" : path}`;
+  return `${base}${base.includes("?") ? "&" : "?"}md`;
+}
+
+/**
+ * The `<link rel="alternate" type="text/markdown">` for an indexable page, or
+ * null when there is no copy to point at (readable copies off, a noindex page,
+ * a path the edge does not convert).
+ */
+export function markdownAlternateLink(
+  seo: SeoRecord,
+  pathname: string,
+  options: { canonical?: string | null; noindex?: boolean },
+): SeoLinkEntry | null {
+  if (seo.markdownEnabled === false || options.noindex || seo.indexing === false) return null;
+  if (!isMarkdownPath(pathname)) return null;
+  return { rel: "alternate", type: "text/markdown", href: markdownAlternateHref(seo, pathname, options.canonical) };
+}

package/src/seo/resolve.ts

@@ -40,8 +40,36 @@ export function seoRecordFromContext(ctx: SeoHeadContext | undefined | null): Se
   return seo && typeof seo === "object" && typeof seo.siteName === "string" ? seo : null;
 }
 
-/** The leaf pathname: the last match is the page being rendered. */
+/**
+ * Whether this render is a not-found page: a URL no route matches, or a route
+ * whose loader threw `notFound()`. TanStack marks the boundary match with
+ * `_notFound` and the throwing match with `status: "notFound"`.
+ */
+export function isNotFoundContext(ctx: SeoHeadContext | undefined | null): boolean {
+  const all = [...(ctx?.matches ?? []), ctx?.match];
+  return all.some((m) => !!m && (m._notFound === true || m.status === "notFound"));
+}
+
+/** The browser's own pathname, when there is a browser. Undefined on the server. */
+function locationPathname(): string | undefined {
+  const loc = (globalThis as { location?: { pathname?: unknown } }).location;
+  return typeof loc?.pathname === "string" && loc.pathname ? loc.pathname : undefined;
+}
+
+/**
+ * The pathname of the page being rendered: the leaf match's.
+ *
+ * A not-found render is the exception. A URL no route matches has only the
+ * root match left, whose pathname is "/", so the leaf would claim to be the
+ * home page. There the location is used when there is one (in the browser),
+ * and the leaf only when nothing better is known. Callers must not state a
+ * canonical for a not-found render whatever this returns (see siteSeoHead).
+ */
 export function pathnameFromContext(ctx: SeoHeadContext | undefined | null): string {
+  if (isNotFoundContext(ctx)) {
+    const fromLocation = locationPathname();
+    if (fromLocation) return normalizePathname(fromLocation);
+  }
   const matches = ctx?.matches ?? [];
   for (let i = matches.length - 1; i >= 0; i--) {
     const pathname = matches[i]?.pathname;
@@ -97,9 +125,20 @@ export function fillTemplate(template: string, values: { title: string; site: st
     .trim();
 }
 
+/**
+ * Whether a stored title template can be used: it must say where the page's
+ * title goes. The API refuses one without `{title}`, but a record saved before
+ * that check (or by an older API) may still carry "%s | Clay Studio", which
+ * would otherwise become every page's literal title.
+ */
+export function isUsableTitleTemplate(template: string | null | undefined): template is string {
+  return typeof template === "string" && template.includes("{title}");
+}
+
 /**
  * The document title for a code title.
  *
+ * A template without `{title}` is ignored in favour of the default.
  * The template is skipped when the title already names the site, so a code
  * title of "Clay Studio | Pottery in Hackney" does not become
  * "Clay Studio | Pottery in Hackney | Clay Studio".
@@ -110,7 +149,8 @@ export function applyTitleTemplate(title: string, siteName: string, template?: s
   if (!site) return base;
   if (!base) return site;
   if (base.toLowerCase().includes(site.toLowerCase())) return base;
-  const filled = fillTemplate(template?.trim() || DEFAULT_TITLE_TEMPLATE, { title: base, site });
+  const usable = isUsableTitleTemplate(template?.trim()) ? template!.trim() : DEFAULT_TITLE_TEMPLATE;
+  const filled = fillTemplate(usable, { title: base, site });
   return filled || base;
 }
 
@@ -183,7 +223,10 @@ export function resolvePageSeo(seo: SeoRecord | null | undefined, input: Resolve
     shareTitle = title;
   } else {
     shareTitle = codeTitle || site;
-    title = applyTitleTemplate(shareTitle, site, typeTemplate?.title || seo.titleTemplate);
+    // The page type's template, else the site's: whichever first says where the
+    // title goes. Neither usable means the default.
+    const template = [typeTemplate?.title, seo.titleTemplate].find(isUsableTitleTemplate);
+    title = applyTitleTemplate(shareTitle, site, template);
   }
 
   const description =

package/src/seo/seoHead.ts

@@ -1,4 +1,5 @@
 import {
+  isNotFoundContext,
   pathnameFromContext,
   resolvePageSeo,
   routePatternFromContext,
@@ -57,5 +58,10 @@ export function seoHead(ctx: SeoHeadContext | undefined | null, input: SeoHeadIn
     image: input.image,
     noindex: input.noindex,
   });
+  // A page whose loader threw notFound() renders the not-found page under its
+  // own URL. That is not a page to index or to share as itself.
+  if (isNotFoundContext(ctx)) {
+    return { meta: pageMeta({ ...resolved, noindex: true, canonical: null }) };
+  }
   return { meta: [...pageMeta(resolved), ...jsonLdMeta(input.jsonLd)] };
 }

package/src/seo/siteSeoHead.ts

@@ -3,10 +3,12 @@ import {
   canonicalFor,
   findOverride,
   isHostedPath,
+  isNotFoundContext,
   leafRoutePatternFromContext,
   pathnameFromContext,
   seoRecordFromContext,
 } from "./resolve";
+import { markdownAlternateLink } from "./markdown";
 import { jsonLdMeta } from "./seoHead";
 import type { SeoHeadContext, SeoLinkEntry, SeoMetaEntry } from "./types";
 
@@ -30,10 +32,16 @@ export type SiteSeoFallback = {
  *    than replaced. It is skipped under `/i/`, where the hosted page emits its
  *    own (an entity's canonical is on the default website, which only that page
  *    knows to say);
- *  - the WebSite and identity JSON-LD, on "/" only.
+ *  - the WebSite and identity JSON-LD, on "/" only;
+ *  - the `alternate` link to the page's Markdown copy, beside the canonical.
  *
  * `robots` is set here when the whole site is noindex or this path's override
  * says so, so it holds even on a page whose code never calls `seoHead`.
+ *
+ * A not-found render states none of the three: no canonical, no Markdown copy
+ * and no site JSON-LD, and it is `noindex`. On a URL no route matches, the only
+ * match left is the root's, at "/", so without this every 404 would claim to
+ * be the home page.
  */
 export function siteSeoHead(
   ctx: SeoHeadContext | undefined | null,
@@ -55,10 +63,13 @@ export function siteSeoHead(
     };
   }
 
-  const override = findOverride(seo, pathname, leafRoutePatternFromContext(ctx));
+  const notFound = isNotFoundContext(ctx);
+  // A missing page has no override: one keyed to "/" or to the route pattern
+  // belongs to a page that exists.
+  const override = notFound ? null : findOverride(seo, pathname, leafRoutePatternFromContext(ctx));
   const description = seo.defaultDescription || fallback.description || undefined;
   const image = seo.defaultImage || fallback.image || undefined;
-  const noindex = seo.indexing === false || override?.noindex === true;
+  const noindex = notFound || seo.indexing === false || override?.noindex === true;
 
   const meta: SeoMetaEntry[] = [
     { title: seo.siteName },
@@ -71,7 +82,7 @@ export function siteSeoHead(
     ...(noindex ? [{ name: "robots", content: "noindex, nofollow" }] : []),
   ];
 
-  if (pathname === "/") {
+  if (pathname === "/" && !notFound) {
     const origin = seo.origin.replace(/\/+$/, "");
     const identity = buildIdentitySchema(seo.identity, { origin });
     meta.push(
@@ -89,9 +100,15 @@ export function siteSeoHead(
     );
   }
 
-  const links: SeoLinkEntry[] = isHostedPath(pathname)
-    ? []
-    : [{ rel: "canonical", href: canonicalFor(seo, pathname, override) }];
+  const links: SeoLinkEntry[] = [];
+  if (!notFound && !isHostedPath(pathname)) {
+    const canonical = canonicalFor(seo, pathname, override);
+    links.push({ rel: "canonical", href: canonical });
+    // The page's readable copy for agents (section 5.4). A hosted page states
+    // its own, beside its own canonical (see applySeoToHead).
+    const markdown = markdownAlternateLink(seo, pathname, { canonical, noindex });
+    if (markdown) links.push(markdown);
+  }
 
   return { meta, links };
 }

package/src/seo/types.ts

@@ -53,6 +53,12 @@ export type SeoRecord = {
   verification: { google?: string | null; bing?: string | null };
   /** false = the whole site is noindex. */
   indexing: boolean;
+  /**
+   * false = readable copies are off: the edge serves no Markdown and pages do
+   * not advertise one. Optional because an API older than Forge 3.64 omits it,
+   * which means on.
+   */
+  markdownEnabled?: boolean;
   /**
    * Key = exact pathname ("/about", "/i/store/mug") OR route pattern
    * ("/team/$slug"). Entity overrides arrive already expanded to their /i/
@@ -84,6 +90,14 @@ export type SeoMatchLike = {
   routeId?: string;
   fullPath?: string;
   loaderData?: unknown;
+  /** "notFound" on the match whose loader threw `notFound()`. */
+  status?: string;
+  /**
+   * TanStack sets this on the match that renders the not-found boundary. On a
+   * URL no route matches, that is the ROOT match, whose pathname is "/": read
+   * without this flag, every unknown URL looks like the home page.
+   */
+  _notFound?: boolean;
 };
 
 export type SeoHeadContext = {
@@ -96,4 +110,4 @@ export type SeoHeadContext = {
 /** One `head()` meta entry. A JSON-LD node rides as `{ "script:ld+json": obj }`. */
 export type SeoMetaEntry = Record<string, unknown>;
 
-export type SeoLinkEntry = { rel: string; href: string };
+export type SeoLinkEntry = { rel: string; href: string; type?: string };

package/src/server/_tests/buildPwaHead.spec.ts

@@ -7,7 +7,7 @@
 //  - apple-touch-icon derive (icon192 preferred, icon512 fallback, absent → omit)
 //  - theme-color derivation + default fallback (bare + localized + no doc)
 //  - manifestHref override / default
-//  - apple-mobile-web-app-title fallback chain (shortName → name → siteName → "App")
+//  - apple-mobile-web-app-title fallback chain (shortName → name → SEO siteName → siteName → "App")
 //  - null/undefined siteConfig degradation (never throws)
 //  - the known client bug this fixes: apple-touch-icon is always emitted when an icon exists
 //
@@ -165,6 +165,23 @@ describe("buildPwaHead — apple-mobile-web-app-title fallback chain", () => {
     const head = buildPwaHead({ siteConfig: siteConfig({ pwa: null, siteName: null }) });
     expect(metaFor(head.metas, "apple-mobile-web-app-title")?.content).toBe("App");
   });
+
+  it("prefers the SEO record's site name over the site config's (the profile's)", () => {
+    const head = buildPwaHead({ siteConfig: siteConfig({ pwa: null, siteName: "Ada Potter" }), seo: { siteName: "Clay Studio" } });
+    expect(metaFor(head.metas, "apple-mobile-web-app-title")?.content).toBe("Clay Studio");
+  });
+
+  it("keeps an explicit PWA name ahead of the SEO site name", () => {
+    const head = buildPwaHead({ siteConfig: siteConfig({ pwa: fullPwa({ shortName: "Nv" }) }), seo: { siteName: "Clay Studio" } });
+    expect(metaFor(head.metas, "apple-mobile-web-app-title")?.content).toBe("Nv");
+  });
+
+  it("ignores a blank SEO site name, and no record at all", () => {
+    const blank = buildPwaHead({ siteConfig: siteConfig({ pwa: null, siteName: "Ada Potter" }), seo: { siteName: "  " } });
+    expect(metaFor(blank.metas, "apple-mobile-web-app-title")?.content).toBe("Ada Potter");
+    const none = buildPwaHead({ siteConfig: siteConfig({ pwa: null, siteName: "Ada Potter" }), seo: null });
+    expect(metaFor(none.metas, "apple-mobile-web-app-title")?.content).toBe("Ada Potter");
+  });
 });
 
 describe("buildPwaHead — degradation (never throws)", () => {

package/src/server/pwa.ts

@@ -178,6 +178,13 @@ export interface BuildPwaHeadOptions {
   contentDoc?: ContentDocument | null;
   /** Where the manifest route lives (default `/manifest.webmanifest`). */
   manifestHref?: string;
+  /**
+   * The website's SEO record, as the root loader returned it. Its `siteName` is
+   * what the creator calls the site in search, so the Home Screen label uses it
+   * ahead of the site config's name (the profile's). A PWA name the creator set
+   * explicitly still wins: that is the app's own label.
+   */
+  seo?: { siteName?: string | null } | null;
 }
 
 /** A TanStack `head()`-shaped link entry. */
@@ -219,7 +226,15 @@ export function buildPwaHead(opts: BuildPwaHeadOptions): PwaHead {
     { name: "mobile-web-app-capable", content: "yes" },
     { name: "apple-mobile-web-app-capable", content: "yes" },
     { name: "apple-mobile-web-app-status-bar-style", content: "default" },
-    { name: "apple-mobile-web-app-title", content: siteConfig?.pwa?.shortName || siteConfig?.pwa?.name || siteConfig?.siteName || "App" },
+    {
+      name: "apple-mobile-web-app-title",
+      content:
+        siteConfig?.pwa?.shortName ||
+        siteConfig?.pwa?.name ||
+        opts.seo?.siteName?.trim() ||
+        siteConfig?.siteName ||
+        "App",
+    },
   ];
   return { links, metas };
 }

package/src/types/models.ts

@@ -1097,6 +1097,17 @@ export type CoachingProduct = {
   reviewAggregate?: IReviewAggregate | null;
   /** The seller's CURRENT cancellation terms — present on the detail endpoint only. */
   cancellation?: CancellationTermsView | null;
+  /**
+   * How the product is sold. Absent on older backends, which means one session.
+   * `package`: exactly `packageSessionCount` sessions for `packagePrice`, and
+   * `price` is the single-session price shown as the saving (0 = none).
+   * `per_session`: 1 to `maxSessionsPerBooking` sessions at `price` each.
+   * The buyer picks every session in one booking.
+   */
+  pricingMode?: "single" | "package" | "per_session";
+  packageSessionCount?: number | null;
+  packagePrice?: string | number | null;
+  maxSessionsPerBooking?: number | null;
 };
 
 // ---- Membership gates (S.4) --------------------------------------------------
@@ -1862,6 +1873,8 @@ export type CoachingBooking = {
   productTitle?: string | null;
   durationMinutes?: number | null;
   timezone?: string | null;
+  /** Every session of a multi-session booking, earliest first. Absent for one session. */
+  sessions?: { startTime: string; endTime: string }[];
   /**
    * The session's `.ics`, both forms — see {@link CalendarFeedLinks}. Null
    * unless the booking is CONFIRMED: a held slot is not a session, and offering

package/src/ui/format/_tests/ticketPrice.spec.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import { isFreeTicket, isSingleFreeTicketEvent, summarizeTicketPrices } from "../ticketPrice";
+
+const tier = (price: number, payWhatYouWant = false) => ({ price, payWhatYouWant });
+
+describe("isFreeTicket", () => {
+  it("is true for a zero price", () => {
+    expect(isFreeTicket(tier(0))).toBe(true);
+  });
+
+  it("is false for a paid tier", () => {
+    expect(isFreeTicket(tier(12))).toBe(false);
+  });
+
+  it("is false for a PWYW tier with a zero floor: the floor is not a gift", () => {
+    expect(isFreeTicket(tier(0, true))).toBe(false);
+  });
+
+  it("reads a decimal string price from the wire", () => {
+    expect(isFreeTicket({ price: "0.00" as unknown as number })).toBe(true);
+  });
+});
+
+describe("summarizeTicketPrices", () => {
+  it("all free reads free", () => {
+    expect(summarizeTicketPrices([tier(0), tier(0)])).toEqual({ kind: "free" });
+  });
+
+  it("free and paid reads free to the dearest tier", () => {
+    expect(summarizeTicketPrices([tier(0), tier(25), tier(40)])).toEqual({ kind: "free_to", max: 40 });
+  });
+
+  it("all paid keeps the cheapest tier", () => {
+    expect(summarizeTicketPrices([tier(40), tier(25)])).toEqual({ kind: "from", min: 25 });
+  });
+
+  it("a zero-floor PWYW tier keeps the From wording", () => {
+    expect(summarizeTicketPrices([tier(0, true), tier(20)])).toEqual({ kind: "from", min: 0 });
+  });
+
+  it("no tiers summarise to nothing", () => {
+    expect(summarizeTicketPrices([])).toBeNull();
+    expect(summarizeTicketPrices(undefined)).toBeNull();
+  });
+});
+
+describe("isSingleFreeTicketEvent", () => {
+  it("one free tier is a reservation", () => {
+    expect(isSingleFreeTicketEvent([tier(0)])).toBe(true);
+  });
+
+  it("two free tiers, one paid tier, or one PWYW tier are not", () => {
+    expect(isSingleFreeTicketEvent([tier(0), tier(0)])).toBe(false);
+    expect(isSingleFreeTicketEvent([tier(10)])).toBe(false);
+    expect(isSingleFreeTicketEvent([tier(0, true)])).toBe(false);
+    expect(isSingleFreeTicketEvent([])).toBe(false);
+  });
+});

package/src/ui/format/bookingPricing.ts

@@ -0,0 +1,55 @@
+import type { CoachingProduct } from "../../types/models";
+
+/**
+ * How a booking product is priced when one booking can hold several sessions.
+ *
+ * Mirrors the backend's `db/types/bookingPricing.ts`, which is the authority:
+ * the server re-prices at reserve and at the details step, so these numbers
+ * are only ever what the buyer is SHOWN before that. Kept in Forge rather than
+ * imported because the storefront ships without the backend.
+ */
+export type BookingPricingMode = "single" | "package" | "per_session";
+
+type PricingFields = Pick<CoachingProduct, "price"> &
+  Partial<Pick<CoachingProduct, "pricingMode" | "packageSessionCount" | "packagePrice" | "maxSessionsPerBooking">>;
+
+export function bookingPricingMode(product: PricingFields | null | undefined): BookingPricingMode {
+  const mode = product?.pricingMode;
+  return mode === "package" || mode === "per_session" ? mode : "single";
+}
+
+/** The number of sessions one booking must hold, inclusive. */
+export function bookingSessionRange(product: PricingFields | null | undefined): { min: number; max: number } {
+  const mode = bookingPricingMode(product);
+  if (mode === "package") {
+    const n = Math.max(1, Number(product?.packageSessionCount ?? 1));
+    return { min: n, max: n };
+  }
+  if (mode === "per_session") return { min: 1, max: Math.max(1, Number(product?.maxSessionsPerBooking ?? 1)) };
+  return { min: 1, max: 1 };
+}
+
+const money = (value: unknown) => {
+  const n = Number(value ?? 0);
+  return Number.isFinite(n) && n > 0 ? Math.round(n * 100) / 100 : 0;
+};
+
+/** The gross price of `sessionCount` sessions, before any discount or tax. */
+export function bookingGrossAmount(product: PricingFields | null | undefined, sessionCount: number): number {
+  const mode = bookingPricingMode(product);
+  if (mode === "package") return money(product?.packagePrice);
+  if (mode === "per_session") return Math.round(money(product?.price) * 100 * sessionCount) / 100;
+  return money(product?.price);
+}
+
+/**
+ * What a package saves against buying its sessions one at a time. 0 when the
+ * creator gave no single-session price, or the package is not cheaper.
+ */
+export function packageSaving(product: PricingFields | null | undefined): number {
+  if (bookingPricingMode(product) !== "package") return 0;
+  const single = money(product?.price);
+  const count = Number(product?.packageSessionCount ?? 0);
+  if (!single || !count) return 0;
+  return Math.max(0, Math.round((single * count - money(product?.packagePrice)) * 100) / 100);
+}

package/src/ui/format/ticketPrice.ts

@@ -0,0 +1,52 @@
+import type { ITicket } from "../../types/models";
+import { isPayWhatYouWant } from "./pwyw";
+
+/**
+ * Free event tickets, as a buyer-facing surface has to word them.
+ *
+ * A tier priced at zero is FREE, and "$0.00" reads as a price, not as a gift.
+ * Every surface that quotes a ticket price runs it through these helpers so a
+ * free tier says "Free" everywhere, and a checkout with nothing to pay says
+ * "Reserve" rather than "Pay $0.00".
+ *
+ * Pay-what-you-want is the exception that matters: on a PWYW tier `price` is
+ * the FLOOR, so a zero floor means "pay what you like, from nothing", not
+ * "free". Those tiers keep their existing "From" wording.
+ */
+
+type PricedTicket = Pick<ITicket, "price"> & Partial<Pick<ITicket, "payWhatYouWant">>;
+
+/** A tier with nothing to pay: priced at zero and not pay-what-you-want. */
+export const isFreeTicket = (ticket: PricedTicket): boolean =>
+  !isPayWhatYouWant(ticket as ITicket) && Number(ticket.price) === 0;
+
+/**
+ * The one-line price summary an event page shows beside its buy button.
+ *
+ * - every tier free: `free`
+ * - some free, some paid: `free_to` with the dearest tier, so the page reads
+ *   "Free to $40" instead of "From $0.00"
+ * - none free: `from` with the cheapest tier, which is the existing wording
+ *
+ * `null` for no tiers at all, so the caller renders nothing.
+ */
+export type TicketPriceSummary =
+  | { kind: "free" }
+  | { kind: "free_to"; max: number }
+  | { kind: "from"; min: number };
+
+export function summarizeTicketPrices(tickets: readonly PricedTicket[] | null | undefined): TicketPriceSummary | null {
+  if (!tickets || tickets.length === 0) return null;
+  const free = tickets.filter(isFreeTicket);
+  if (free.length === tickets.length) return { kind: "free" };
+  const prices = tickets.map((ticket) => Number(ticket.price)).filter((price) => Number.isFinite(price));
+  if (free.length > 0) return { kind: "free_to", max: Math.max(...prices) };
+  return { kind: "from", min: prices.length ? Math.min(...prices) : 0 };
+}
+
+/**
+ * The event sells exactly one tier and it is free, so the call to action is a
+ * reservation, not a purchase ("Reserve" rather than "Buy tickets").
+ */
+export const isSingleFreeTicketEvent = (tickets: readonly PricedTicket[] | null | undefined): boolean =>
+  !!tickets && tickets.length === 1 && isFreeTicket(tickets[0]);