@unitninety/site-kit 0.0.0-stage → 1.6.1

package/src/legacy/content.ts

@@ -0,0 +1,993 @@
+import { verifyWithDeadline, type VerifyVisitor } from './verification'
+/**
+ * Reading content from the platform.
+ *
+ * Two properties this layer guarantees, both deliberate and both load-bearing:
+ *
+ *  - **Every field is optional.** A site keeps the copy and assets it ships with as
+ *    defaults and only overrides what the CMS actually returns, so a missing field
+ *    changes nothing.
+ *  - **A failure is never fatal.** If the platform is unreachable, slow or
+ *    misconfigured, this returns an empty result and the site renders exactly as it
+ *    does with no CMS at all. A CMS outage must not take a client's site down.
+ *
+ * Server-side only — it holds the API key. The shapes and merge helpers the components
+ * need are in `./shape`, which is safe to import from a client component.
+ */
+
+import type { LanguageSnapshot } from './languages/runtime'
+
+export type LocaleReadOptions = { locale?: string }
+
+import { PREVIEW_TOKEN_COOKIE, PREVIEW_UNTIL_COOKIE, previewWindowClosed } from './preview'
+
+/** One section as stored: a `blockType` plus whatever the site's schema declares. */
+export type Section = Record<string, unknown> & { blockType?: string }
+
+/** A media reference the platform hydrated on egress — an absolute url, never a bare id. */
+export type SeoMedia = { alt: string; url: null | string }
+
+/** One page's own SEO group, as the platform resolved it. Every field explicit — see `readSeo`. */
+export type PageSeo = {
+  canonical: null | string
+  description: null | string
+  noindex: boolean
+  ogDescription: null | string
+  ogImage: null | SeoMedia
+  ogTitle: null | string
+  title: null | string
+}
+
+/** The seven days `openingHoursSpecification` addresses, spelled the way schema.org wants them. */
+export type OpeningHoursDay =
+  'friday' | 'monday' | 'saturday' | 'sunday' | 'thursday' | 'tuesday' | 'wednesday'
+
+/**
+ * One day's hours, as stored. `opens`/`closes` are 24-hour `HH:MM` — the one format that
+ * cannot mean two things (no am/pm to mistype, no locale to get wrong), and exactly what
+ * schema.org's own `opens`/`closes` properties expect, so the emitter never has to convert.
+ * Both are null while `closed` is true, or while a client has not filled the row in yet.
+ */
+export type OpeningHoursRow = {
+  closed: boolean
+  closes: null | string
+  day: OpeningHoursDay
+  opens: null | string
+}
+
+/** The organisation half of the site-wide SEO singleton — for JSON-LD and contact metadata. */
+export type SeoOrganisation = {
+  address: null | string
+  email: null | string
+  /**
+   * The free-text hours a client typed before the structured editor existed — "Mo-Fr
+   * 07:00-17:00", "7am-5pm daily", anything. Never parsed, never shown in the dashboard's own
+   * editor, and read only as a fallback: `organisationJsonLd` emits it verbatim, the old
+   * unstructured way, when `openingHours` below is empty — so a tenant who has not touched the
+   * new editor yet does not silently lose the hours they already published.
+   */
+  legacyOpeningHours: null | string
+  legalName: null | string
+  logo: null | SeoMedia
+  /** Empty means "not set" — the same as every other absent field here, not "closed every day". */
+  openingHours: OpeningHoursRow[]
+  phone: null | string
+  sameAs: string[]
+}
+
+/** The tenant's site-wide SEO singleton, as the platform resolved it. */
+export type SiteSeo = {
+  allowIndexing: boolean
+  bingVerification: null | string
+  description: null | string
+  googleVerification: null | string
+  locale: null | string
+  ogImage: null | SeoMedia
+  organisation: null | SeoOrganisation
+  siteName: null | string
+  titleTemplate: null | string
+  twitterCard: 'summary' | 'summary_large_image'
+  twitterHandle: null | string
+}
+
+/** One published page's address and when it last changed, for `sitemap.xml`. */
+export type SitemapEntry = { lastModified: null | string; slug: string }
+
+/**
+ * One row of a collection, as the platform stores it.
+ *
+ * The id travels with the values because it is what makes a row addressable: the
+ * editing bridge marks a field as `@projects.42.name`, and without the id a site
+ * could only say "the third project", which stops being true the moment a client
+ * reorders them.
+ */
+export type CollectionRow = {
+  data: Record<string, unknown>
+  id: number | string
+}
+
+export type ContentResult = {
+  /**
+   * `blockType` → its index in the sections array.
+   *
+   * Editable elements are addressed as `${sectionIndex}.${fieldPath}`, and the index
+   * has to come from the data rather than from render order — a reordered page would
+   * otherwise point every edit at the wrong section.
+   */
+  index: Record<string, number>
+  /**
+   * The layout this page renders inside, resolved by the platform. `null` when the platform
+   * said nothing, which a site answers with its own committed layout — the same guarantee
+   * every other reader here makes.
+   */
+  layout: null | {
+    entries: (Record<string, unknown> & { blockType: string })[]
+    /**
+     * Which layout document this is, when the platform said — the `12` in the
+     * `~12.0.tagline` a site's chrome stamps through `layoutField`.
+     *
+     * Optional, because only the editor needs it: a visitor's header renders identically
+     * without one, and `layoutField` emits no attribute at all for an `undefined` id. A
+     * site's own committed fallback layout has none by construction and never will — it is
+     * a declaration in a repo, not a row, and an edit has nothing to address.
+     */
+    id?: string
+  }
+  sections: Section[]
+  /**
+   * This page's own SEO, as the platform resolved it. `null` when the platform said nothing.
+   *
+   * `ogImage` arrives as a resolved reference with an ABSOLUTE url rather than an id, because
+   * the platform hydrates it on egress — `depth` cannot populate it here, and a relative
+   * `og:image` is resolved against the sharing service rather than the site, so every unfurl
+   * would 404. See `hydrateSeoMedia` on the platform.
+   */
+  seo: null | PageSeo
+  /**
+   * The page's own title, as stored on the platform.
+   *
+   * Carried because `applyTitleTemplate` substitutes it into `%page%`, and without it a site
+   * would have to reconstruct a title from its slug — which is how `about-us` ends up in a
+   * browser tab. Not for rendering: a site's own heading comes from its blocks.
+   */
+  title: null | string
+  /**
+   * Which of the three answers this is.
+   *
+   *  - `ok` — the platform answered and this page exists.
+   *  - `missing` — it answered, and there is no published page at this slug.
+   *  - `unavailable` — we could not ask, or the answer was unusable.
+   *
+   * **Only `missing` may become a 404.** A page and an outage used to be indistinguishable
+   * here — both returned an empty result — which is fine for a hand-built page that falls
+   * back to its committed copy, and wrong for a catch-all route: 404ing on an empty result
+   * turns one CMS outage into a site of 404s, and 200ing on a genuinely absent page hands
+   * search engines an empty document for every typo'd URL.
+   *
+   * A hand-built page can keep ignoring this. It renders its committed copy either way,
+   * which is the guarantee that has always mattered most here.
+   */
+  status: 'missing' | 'ok' | 'unavailable'
+}
+
+/** Could not ask, or could not use the answer. Never a 404 — see `ContentResult.status`. */
+const EMPTY: ContentResult = {
+  index: {},
+  layout: null,
+  seo: null,
+  sections: [],
+  status: 'unavailable',
+  title: null,
+}
+
+/** Asked, and there is no published page at that slug. The only result a 404 may follow. */
+const MISSING: ContentResult = {
+  index: {},
+  layout: null,
+  seo: null,
+  sections: [],
+  status: 'missing',
+  title: null,
+}
+
+/**
+ * Give up rather than hold a page render open on a slow CMS — but not before it has woken up.
+ *
+ * This was 4000, which a cold platform can miss. The platform is a serverless function with
+ * Payload, a Postgres pool and a schema to initialise; the first request after an idle spell
+ * is slow in a way that has nothing to do with anything being wrong. Missing it meant the site
+ * rendered its committed fallback copy and 404'd its collection routes — silently, and
+ * intermittently, which is the worst combination to debug.
+ *
+ * 8 seconds, and one retry, because a cold start is a single event: the attempt that pays for
+ * the wake-up fails and the next one is fast. A page that takes nine seconds once an hour is a
+ * far better trade than one that quietly drops half its content.
+ */
+const TIMEOUT_MS = 8000
+
+/** One retry, immediately. See TIMEOUT_MS — the second attempt meets a warm function. */
+const ATTEMPTS = 2
+
+export type ContentClientOptions = {
+  /** Select this site even when the authenticated actor can read several tenants. */
+  tenantId?: number | string
+  apiKey?: string
+  /** Defaults to the universal collection. */
+  collection?: string
+  platformUrl?: string
+  /** Next's `draftMode()`/`cookies()`, when the site supports preview. */
+  preview?: {
+    cookies: () => Promise<{ get: (name: string) => undefined | { value: string } }>
+    draftMode: () => Promise<{ isEnabled: boolean }>
+  }
+}
+
+const indexSections = (sections: Section[]): Record<string, number> => {
+  const index: Record<string, number> = {}
+  sections.forEach((section, position) => {
+    if (section.blockType && index[section.blockType] === undefined) {
+      index[section.blockType] = position
+    }
+  })
+  return index
+}
+
+/**
+ * `layout` only ever reaches a site because `attachResolvedLayout` on the platform put it
+ * there — there is no schema between us enforcing its shape. Read it as untrusted: a
+ * platform version skew, a hand-edited response, or a resolved row missing `entries`
+ * entirely must fall back to `null` here rather than hand a site something it renders a
+ * blank page over. `null` is also what every unresolved case already means — no layout
+ * configured, no default, a deleted row — so a malformed one joins that list rather than
+ * getting a category of its own.
+ */
+const readLayout = (value: unknown): ContentResult['layout'] => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+  const entries = (value as { entries?: unknown }).entries
+  if (!Array.isArray(entries)) return null
+  const rows = entries as (Record<string, unknown> & { blockType: string })[]
+  /*
+   * The id is the half a site cannot work out for itself, and the half it may be handed
+   * nothing for. Kept when it is there — as a string, since the address it prefixes is text
+   * and the platform's row ids are `number | string` — and simply absent when it is not.
+   * Refusing the layout over a missing id would blank a visitor's header for a reason only
+   * the editor has.
+   */
+  const id = (value as { id?: unknown }).id
+  return typeof id === 'number' || typeof id === 'string'
+    ? { entries: rows, id: String(id) }
+    : { entries: rows }
+}
+
+/** A media reference the platform hydrated, or null. Never a bare id — see `ContentResult.seo`. */
+const readSeoMedia = (value: unknown): null | SeoMedia => {
+  if (!value || typeof value !== 'object') return null
+  const record = value as { alt?: unknown; url?: unknown }
+  if (typeof record.url !== 'string' || record.url === '') return null
+  return { alt: typeof record.alt === 'string' ? record.alt : '', url: record.url }
+}
+
+const OPENING_HOURS_DAYS: readonly OpeningHoursDay[] = [
+  'monday',
+  'tuesday',
+  'wednesday',
+  'thursday',
+  'friday',
+  'saturday',
+  'sunday',
+]
+
+/** `07:00`, `17:30` — 24-hour `HH:MM`. Anything else is not a time this emitter can trust. */
+const isOpeningHoursTime = (value: unknown): value is string =>
+  typeof value === 'string' && /^([01]\d|2[0-3]):[0-5]\d$/.test(value)
+
+/**
+ * One row of the platform's `organisation.openingHours` array, believed field by field. An
+ * unrecognised `day` (a platform ahead of this package's enum, or a hand-edited response) drops
+ * the row rather than passing through a value `organisationJsonLd` cannot map to schema.org's
+ * `dayOfWeek`. A malformed time is dropped the same way `opens`/`closes` are on `PageSeo` —
+ * treated as absent, not as a reason to fail the whole row.
+ */
+const readOpeningHoursRow = (value: unknown): null | OpeningHoursRow => {
+  if (!value || typeof value !== 'object') return null
+  const record = value as Record<string, unknown>
+  if (!OPENING_HOURS_DAYS.includes(record.day as OpeningHoursDay)) return null
+  return {
+    closed: record.closed === true,
+    closes: isOpeningHoursTime(record.closes) ? record.closes : null,
+    day: record.day as OpeningHoursDay,
+    opens: isOpeningHoursTime(record.opens) ? record.opens : null,
+  }
+}
+
+/** The platform's `organisation.openingHours` array, believed row by row. Never throws on junk. */
+const readOpeningHours = (value: unknown): OpeningHoursRow[] =>
+  Array.isArray(value)
+    ? value.map(readOpeningHoursRow).filter((row): row is OpeningHoursRow => row !== null)
+    : []
+
+/**
+ * A page's SEO group, believed field by field.
+ *
+ * Every field is optional on the way in and explicit on the way out, so `metadataFor` never
+ * has to distinguish "absent" from "empty" — both are null here, and both mean inherit.
+ */
+const readSeo = (value: unknown): null | PageSeo => {
+  if (!value || typeof value !== 'object') return null
+  const record = value as Record<string, unknown>
+  const text = (key: string): null | string => {
+    const found = record[key]
+    return typeof found === 'string' && found.trim() !== '' ? found : null
+  }
+  return {
+    canonical: text('canonical'),
+    description: text('description'),
+    noindex: record.noindex === true,
+    ogDescription: text('ogDescription'),
+    ogImage: readSeoMedia(record.ogImage),
+    ogTitle: text('ogTitle'),
+    title: text('title'),
+  }
+}
+
+export const createContentClient = ({
+  apiKey = process.env.PAYLOAD_API_KEY,
+  collection = 'pages',
+  platformUrl = process.env.PLATFORM_URL,
+  preview,
+  tenantId,
+}: ContentClientOptions = {}) => {
+  /**
+   * Say so, once, when this site cannot reach its CMS at all.
+   *
+   * Both readers return empty on failure so that a CMS outage renders the site's committed
+   * fallbacks instead of an error page. That is the right behaviour for a visitor and it was
+   * indistinguishable from an empty CMS for everybody else: a site missing `PLATFORM_URL`
+   * renders its seed copy, looks entirely fine, and 404s every collection detail route —
+   * with nothing in any log to say why. It cost an hour of looking in the wrong place.
+   *
+   * Once per process, because these are read on every request of every render.
+   */
+  let warned = false
+  const unconfigured = (): boolean => {
+    if (platformUrl && apiKey) return false
+    if (!warned) {
+      warned = true
+      console.error(
+        `[u90] This site cannot read its CMS: ${
+          !platformUrl && !apiKey
+            ? 'PLATFORM_URL and PAYLOAD_API_KEY are both unset'
+            : !platformUrl
+              ? 'PLATFORM_URL is unset'
+              : 'PAYLOAD_API_KEY is unset'
+        }. Every page will render its committed fallback copy, and every collection route will 404. Set it in the site's environment — \`npx --yes @unitninety/u90@1.0.0 pair\` writes both.`,
+      )
+    }
+    return true
+  }
+  /**
+   * Whether this request should read staged content, and whose staged content.
+   *
+   * Shared by both readers so they can never disagree — a page showing the draft while
+   * its projects showed the published rows would be a preview that lies in exactly the
+   * place a client is most likely to be checking.
+   */
+  const resolvePreview = async (
+    request?: Request,
+  ): Promise<{ isDraft: boolean; token?: string }> => {
+    if (!preview) return { isDraft: false }
+    // Proxy does not have the render request's draft-mode provider. The explicit request
+    // carries only a preview attempt: the platform still authenticates its JWT and tenant.
+    if (request) {
+      const values = new Map<string, string>()
+      for (const entry of request.headers.get('cookie')?.split(';') ?? []) {
+        const separator = entry.indexOf('=')
+        if (separator < 0) continue
+        try {
+          values.set(
+            entry.slice(0, separator).trim(),
+            decodeURIComponent(entry.slice(separator + 1).trim()),
+          )
+        } catch {
+          /* Ignore malformed cookies. */
+        }
+      }
+      if (
+        !values.get('__prerender_bypass') ||
+        previewWindowClosed(values.get(PREVIEW_UNTIL_COOKIE))
+      )
+        return { isDraft: false }
+      return {
+        isDraft: Boolean(values.get(PREVIEW_TOKEN_COOKIE)),
+        token: values.get(PREVIEW_TOKEN_COOKIE),
+      }
+    }
+    try {
+      const isDraft = (await preview.draftMode()).isEnabled
+      if (!isDraft) return { isDraft: false }
+
+      const jar = await preview.cookies()
+
+      /*
+       * Next's draft cookie says a preview was started. It does not say one is still
+       * running, and nothing expires it — see `./preview`. A lapsed window reads as
+       * published, which is both the safe answer and the one a visitor would get.
+       */
+      if (previewWindowClosed(jar.get(PREVIEW_UNTIL_COOKIE)?.value)) return { isDraft: false }
+
+      return { isDraft, token: jar.get(PREVIEW_TOKEN_COOKIE)?.value }
+    } catch {
+      // Outside a request scope, e.g. at build time. Treat as published.
+      return { isDraft: false }
+    }
+  }
+
+  /**
+   * The site key remains the primary tenant boundary. The platform independently verifies
+   * the preview session and its editor permissions for that same explicit tenant; it never
+   * substitutes the editor's potentially broader access for the site's own access.
+   * Custom headers survive cross-origin redirects, so token-bearing requests reject them.
+   */
+  const contentAuth = (
+    isDraft: boolean,
+    token?: string,
+  ): Pick<RequestInit, 'headers' | 'redirect'> => ({
+    headers: {
+      Authorization: `users API-Key ${apiKey}`,
+      ...(isDraft && token ? { 'X-U90-Preview-Token': token } : {}),
+    },
+    ...(isDraft && token ? { redirect: 'error' as const } : {}),
+  })
+
+  /**
+   * Authentication and authorization are different failures. A valid site key can be
+   * refused because of tenant access or an editor's preview permissions.
+   */
+  const explain = (status: number, what: string): string => {
+    if (status === 401) {
+      return `[u90] The platform could not authenticate the request (401) reading ${what}. Check the site's configured credentials and any active preview session.`
+    }
+    if (status === 403) {
+      return `[u90] The platform denied access (403) reading ${what}. Check the site's tenant permissions and, for preview reads, the signed-in editor's permission to preview this tenant.`
+    }
+    if (status === 404) {
+      return `[u90] The platform has no ${what} (404). Check PLATFORM_URL points at the platform and that this tenant owns that content.`
+    }
+    if (status >= 500) {
+      return `[u90] The platform failed (${status}) reading ${what}. Rendering fallback copy.`
+    }
+    return `[u90] platform returned ${status} for ${what}`
+  }
+
+  /**
+   * `fetch` with one retry, and a log that says which attempt failed.
+   *
+   * Retries a timeout or a network error — the cold-start shapes. A *response* is never
+   * retried, however bad its status: a 403 will be a 403 again, and hammering the platform
+   * because it said no is how one broken credential becomes a load problem.
+   */
+  const fetchWithRetry = async (
+    url: URL,
+    init: RequestInit,
+    what: string,
+  ): Promise<null | Response> => {
+    for (let attempt = 1; attempt <= ATTEMPTS; attempt += 1) {
+      const controller = new AbortController()
+      const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS)
+      try {
+        return await fetch(url, { ...init, signal: controller.signal })
+      } catch (error) {
+        const last = attempt === ATTEMPTS
+        const aborted = (error as { name?: string })?.name === 'AbortError'
+        console.error(
+          `[u90] ${aborted ? `timed out after ${TIMEOUT_MS}ms` : 'could not reach the platform'} reading ${what} (attempt ${attempt}/${ATTEMPTS})${
+            last ? ' — rendering fallback copy' : ', retrying'
+          }`,
+        )
+        if (last) return null
+      } finally {
+        clearTimeout(timeout)
+      }
+    }
+    return null
+  }
+
+  const getPage = async (slug: string, options: LocaleReadOptions = {}): Promise<ContentResult> => {
+    if (unconfigured()) return EMPTY
+
+    const { isDraft, token } = await resolvePreview()
+
+    const url = new URL(`/api/${collection}`, platformUrl)
+    if (tenantId !== undefined) url.searchParams.set('where[tenant][equals]', String(tenantId))
+    if (options.locale) url.searchParams.set('u90Locale', options.locale)
+    url.searchParams.set('where[slug][equals]', slug)
+    url.searchParams.set('limit', '1')
+    /*
+     * `depth=0` deliberately. Uploads inside `content` are ids in a JSON column, so
+     * depth cannot populate them — the platform resolves them itself on the way out,
+     * and asking for depth only makes it join relations nothing here reads.
+     */
+    url.searchParams.set('depth', '0')
+
+    if (isDraft && token) {
+      url.searchParams.set('draft', 'true')
+    } else {
+      /*
+       * The published row is what a visitor must see. Drafts live in a separate
+       * versions table and the published row is left untouched when one is saved, so
+       * this filter is the thing keeping unpublished work off the live site.
+       */
+      url.searchParams.set('where[_status][equals]', 'published')
+    }
+
+    try {
+      const response = await fetchWithRetry(
+        url,
+        {
+          ...contentAuth(isDraft, token),
+          ...(isDraft
+            ? { cache: 'no-store' as const }
+            : {
+                next: {
+                  tags: [
+                    collection,
+                    `${collection}:${slug}`,
+                    ...(options.locale ? ['language-settings', 'translations', 'entries'] : []),
+                  ],
+                },
+              }),
+        },
+        `${collection}/${slug}`,
+      )
+
+      if (!response) return EMPTY
+
+      if (!response.ok) {
+        console.error(explain(response.status, `${collection}/${slug}`))
+        return EMPTY
+      }
+
+      const body = (await response.json()) as {
+        docs?: { content?: Section[]; layout?: unknown; seo?: unknown; title?: unknown }[]
+      }
+
+      /*
+       * No document is a *different answer* from no sections, and only this branch knows
+       * which happened: the platform replied, and the published-only filter matched nothing.
+       * A page that exists with an empty `content` array is `ok`, and renders as a page with
+       * no sections — which is what a client sees between adding a page and writing it.
+       */
+      const doc = body.docs?.[0]
+      if (!doc) return MISSING
+
+      const sections = doc.content ?? []
+
+      return {
+        index: indexSections(sections),
+        layout: readLayout(doc.layout),
+        seo: readSeo((doc as { seo?: unknown }).seo),
+        sections,
+        status: 'ok',
+        title: typeof doc.title === 'string' && doc.title !== '' ? doc.title : null,
+      }
+    } catch (error) {
+      console.error(
+        `[u90] could not load ${collection}/${slug}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      )
+      return EMPTY
+    }
+  }
+
+  /**
+   * Read one of this site's collections — its projects, its team — in the order the
+   * client arranged them.
+   *
+   * Same two guarantees as `getPage`: a failure returns an empty list rather than
+   * throwing, so a CMS outage renders the site's committed fallbacks instead of an
+   * error page.
+   *
+   * Rows stage like pages do. This used to read them unfiltered, because `entries` had
+   * no draft cycle and saving a row was publishing it — which meant a client's edit to
+   * a project reached visitors the moment they typed it, while the page around it
+   * waited for Publish. Both halves are staged now, and both are read the same way.
+   */
+  const readAllPages = async <T>(url: URL, init: RequestInit, label: string): Promise<T[]> => {
+    const docs: T[] = []
+    let page = 1
+    while (true) {
+      url.searchParams.set('page', String(page))
+      const response = await fetchWithRetry(url, init, label)
+      if (!response?.ok)
+        throw new Error(response ? explain(response.status, label) : 'Content unavailable')
+      const body = (await response.json()) as {
+        docs?: T[]
+        hasNextPage?: boolean
+        nextPage?: number
+      }
+      docs.push(...(body.docs ?? []))
+      if (!body.hasNextPage) return docs
+      const next = body.nextPage ?? page + 1
+      if (!Number.isInteger(next) || next <= page) throw new Error('Invalid content pagination')
+      page = next
+    }
+  }
+
+  const getCollection = async (
+    slug: string,
+    options: LocaleReadOptions = {},
+  ): Promise<CollectionRow[]> => {
+    if (unconfigured()) return []
+
+    const { isDraft, token } = await resolvePreview()
+
+    const url = new URL('/api/entries', platformUrl)
+    if (tenantId !== undefined) url.searchParams.set('where[tenant][equals]', String(tenantId))
+    if (options.locale) url.searchParams.set('u90Locale', options.locale)
+    url.searchParams.set('where[collection][equals]', slug)
+    // The order the client dragged them into. Ties fall back to creation order.
+    url.searchParams.set('sort', 'sortOrder')
+    url.searchParams.set('limit', '200')
+    // Uploads inside `data` are ids in a JSON column; the platform resolves them on
+    // the way out, exactly as it does for a page's sections.
+    url.searchParams.set('depth', '0')
+
+    if (isDraft && token) {
+      url.searchParams.set('draft', 'true')
+    } else {
+      // The filter that keeps a staged row off the live site, exactly as on `getPage`.
+      url.searchParams.set('where[_status][equals]', 'published')
+    }
+
+    try {
+      const docs = await readAllPages<{ data?: unknown; id: number | string }>(
+        url,
+        {
+          ...contentAuth(isDraft, token),
+          ...(isDraft
+            ? { cache: 'no-store' as const }
+            : {
+                next: {
+                  tags: [
+                    'entries',
+                    `entries:${slug}`,
+                    ...(options.locale ? ['language-settings', 'translations'] : []),
+                  ],
+                },
+              }),
+        },
+        `entries/${slug}`,
+      )
+
+      return docs.map((doc) => ({
+        data:
+          doc.data && typeof doc.data === 'object' && !Array.isArray(doc.data)
+            ? (doc.data as Record<string, unknown>)
+            : {},
+        id: doc.id,
+      }))
+    } catch (error) {
+      console.error(
+        `[u90] could not load entries/${slug}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      )
+      return []
+    }
+  }
+
+  /**
+   * The tenant's site-wide SEO, or null.
+   *
+   * Tagged `site-seo`, which is the same string the platform sends as `collection` when the
+   * row changes — so the revalidate route already purges this with no change of its own. Get
+   * that string wrong and a client's save appears to work and changes nothing until the cache
+   * expires on its own.
+   *
+   * No `_status` filter and no draft branch: this collection has no drafts on the platform. A
+   * site-wide setting is configuration, and there is no staged copy of it to choose between.
+   *
+   * Null on any failure, never a throw. A site whose layout throws renders an error page
+   * instead of the client's website, and missing SEO is not worth that.
+   */
+  const getSiteSeo = async (options: LocaleReadOptions = {}): Promise<null | SiteSeo> => {
+    if (unconfigured()) return null
+
+    const { isDraft, token } = options.locale
+      ? await resolvePreview()
+      : { isDraft: false, token: undefined }
+    const url = new URL('/api/site-seo', platformUrl)
+    if (tenantId !== undefined) url.searchParams.set('where[tenant][equals]', String(tenantId))
+    if (options.locale) url.searchParams.set('u90Locale', options.locale)
+    if (isDraft && token) url.searchParams.set('draft', 'true')
+    url.searchParams.set('limit', '1')
+    // depth=1 so `ogImage` and `organisation.logo` arrive as documents rather than ids. These
+    // are real relationships on a small single row, so the join is cheap and there is no JSON
+    // column in the way — unlike a page's `content`, which is why `getPage` stays at depth 0.
+    url.searchParams.set('depth', '1')
+
+    try {
+      const response = await fetchWithRetry(
+        url,
+        {
+          ...contentAuth(isDraft, token),
+          // Spread rather than a literal property: `next` isn't in DOM's `RequestInit`, and
+          // this package deliberately carries no Next types to widen it — see `getPage`.
+          ...(isDraft
+            ? { cache: 'no-store' as const }
+            : {
+                next: {
+                  tags: [
+                    'site-seo',
+                    ...(options.locale ? ['language-settings', 'translations'] : []),
+                  ],
+                },
+              }),
+        },
+        'site-seo',
+      )
+
+      if (!response) return null
+      if (!response.ok) {
+        console.error(explain(response.status, 'site-seo'))
+        return null
+      }
+
+      const body = (await response.json()) as { docs?: Record<string, unknown>[] }
+      const row = body.docs?.[0]
+      if (!row) return null
+
+      const text = (key: string): null | string => {
+        const found = row[key]
+        return typeof found === 'string' && found.trim() !== '' ? found : null
+      }
+
+      const organisation = (row.organisation ?? null) as null | Record<string, unknown>
+
+      return {
+        allowIndexing: row.allowIndexing === true,
+        bingVerification: text('bingVerification'),
+        description: text('description'),
+        googleVerification: text('googleVerification'),
+        locale: text('locale'),
+        ogImage: readSeoMedia(row.ogImage),
+        organisation: organisation
+          ? {
+              address:
+                typeof organisation.address === 'string' && organisation.address.trim() !== ''
+                  ? organisation.address
+                  : null,
+              email:
+                typeof organisation.email === 'string' && organisation.email.trim() !== ''
+                  ? organisation.email
+                  : null,
+              legacyOpeningHours:
+                typeof organisation.legacyOpeningHours === 'string' &&
+                organisation.legacyOpeningHours.trim() !== ''
+                  ? organisation.legacyOpeningHours
+                  : null,
+              legalName:
+                typeof organisation.legalName === 'string' && organisation.legalName.trim() !== ''
+                  ? organisation.legalName
+                  : null,
+              logo: readSeoMedia(organisation.logo),
+              openingHours: readOpeningHours(organisation.openingHours),
+              phone:
+                typeof organisation.phone === 'string' && organisation.phone.trim() !== ''
+                  ? organisation.phone
+                  : null,
+              sameAs: Array.isArray(organisation.sameAs)
+                ? (organisation.sameAs as { url?: unknown }[])
+                    .map((entry) => (typeof entry?.url === 'string' ? entry.url : ''))
+                    .filter((entry) => entry !== '')
+                : [],
+            }
+          : null,
+        siteName: text('siteName'),
+        titleTemplate: text('titleTemplate'),
+        twitterCard: row.twitterCard === 'summary' ? 'summary' : 'summary_large_image',
+        twitterHandle: text('twitterHandle'),
+      }
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Every published page's address and when it last changed, for `sitemap.xml`.
+   *
+   * `noindex` pages are dropped here rather than at the caller, so a sitemap and a meta tag
+   * can never contradict each other — a page listed in a sitemap and refused in a robots tag
+   * is an error crawlers report.
+   *
+   * Published only, never drafts: a sitemap is for visitors and crawlers, and a staged page
+   * has no address a visitor can reach.
+   */
+  const getSitemapEntries = async (): Promise<SitemapEntry[]> => {
+    if (unconfigured()) return []
+
+    const url = new URL(`/api/${collection}`, platformUrl)
+    if (tenantId !== undefined) url.searchParams.set('where[tenant][equals]', String(tenantId))
+    url.searchParams.set('where[_status][equals]', 'published')
+    url.searchParams.set('limit', '500')
+    url.searchParams.set('depth', '0')
+
+    try {
+      const docs = await readAllPages<{
+        seo?: { noindex?: unknown }
+        slug?: unknown
+        updatedAt?: unknown
+      }>(
+        url,
+        {
+          headers: { Authorization: `users API-Key ${apiKey}` },
+          // Spread rather than a literal property — see the note in `getSiteSeo`.
+          ...{ next: { tags: [collection] } },
+        },
+        'sitemap',
+      )
+
+      return docs
+        .filter((doc) => typeof doc.slug === 'string' && doc.slug !== '')
+        .filter((doc) => doc.seo?.noindex !== true)
+        .map((doc) => ({
+          lastModified: typeof doc.updatedAt === 'string' ? doc.updatedAt : null,
+          slug: doc.slug as string,
+        }))
+    } catch {
+      return []
+    }
+  }
+
+  /**
+   * Post a submission to one of this site's declared forms. Server-side only — it uses the
+   * API key.
+   *
+   * A browser action proof (or a retained retry grant) is mandatory. The platform chooses
+   * and assesses the configured provider. Proof and grant travel separately from answers.
+   * Keep requestId and the onGrant result for an identical retry after an uncertain response.
+   */
+  const submitForm = async (
+    slug: string,
+    data: Record<string, unknown>,
+    options?: {
+      protection?: {
+        honeypot?: string
+        /** Deprecated: public Forms use aggregate admission without a signed visitor cookie. */
+        clientIdentity?: string
+        verification?: {
+          proof?: string | null
+          grant?: string
+          requestId?: string
+          /** Supplemental only; never replaces the central assessment. */
+          verifyVisitor?: VerifyVisitor
+          onGrant?: (grant: string, requestId: string) => void
+        }
+      }
+    },
+  ): Promise<boolean> => {
+    if (unconfigured()) return false
+    try {
+      const protection = options?.protection
+      const honeypot = protection?.honeypot
+      const identity = protection?.clientIdentity
+      if (
+        honeypot !== undefined &&
+        (typeof honeypot !== 'string' || honeypot.length > 256 || honeypot !== '')
+      )
+        return false
+      if (
+        identity !== undefined &&
+        (typeof identity !== 'string' ||
+          !identity ||
+          new TextEncoder().encode(identity).length > 256 ||
+          /[\u0000-\u001f\u007f]/.test(identity))
+      )
+        return false
+      const url = new URL(`/api/u90/forms/${encodeURIComponent(slug)}`, platformUrl)
+      const headers = {
+        Authorization: `users API-Key ${apiKey}`,
+        'Content-Type': 'application/json',
+        ...(identity === undefined
+          ? {}
+          : { 'x-u90-protection-client': encodeURIComponent(identity) }),
+        ...(honeypot === undefined ? {} : { 'x-u90-protection-honeypot': honeypot }),
+      }
+      const verification = protection?.verification
+      if (!verification) return false
+      const requestId = verification.requestId ?? crypto.randomUUID()
+      let grant = verification.grant
+      if (!grant) {
+        const proof = verification.proof
+        if (proof !== null && (!proof || new TextEncoder().encode(proof).length > 4096))
+          return false
+        if (
+          proof !== null &&
+          verification.verifyVisitor &&
+          !(await verifyWithDeadline(verification.verifyVisitor, url.href, proof)).ok
+        )
+          return false
+        const response = await fetch(url, {
+          method: 'POST',
+          headers,
+          body: JSON.stringify({
+            values: data,
+            verification: { requestId, mode: 'verify', proof },
+          }),
+          redirect: 'error',
+          cache: 'no-store',
+          signal: AbortSignal.timeout(15000),
+        })
+        if (!response.ok) return false
+        const result = await response.json()
+        if (typeof result.grant !== 'string' || result.grant.length > 4096) return false
+        grant = result.grant
+        verification.onGrant?.(grant!, requestId)
+      }
+      const response = await fetch(url, {
+        method: 'POST',
+        headers,
+        redirect: 'error',
+        cache: 'no-store',
+        signal: AbortSignal.timeout(30000),
+        body: JSON.stringify({ values: data, verification: { requestId, mode: 'submit', grant } }),
+      })
+      return response.ok
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Post a contact-form submission. Server-side only — it uses the API key.
+   *
+   * Uses the lazily created contact form and the same mandatory verification options as
+   * submitForm. Sites must coordinate their browser proof integration with this upgrade.
+   */
+  const submitEnquiry = async (
+    enquiry: {
+      email: string
+      message: string
+      name: string
+      phone?: string
+      sourcePage?: string
+    },
+    options?: Parameters<typeof submitForm>[2],
+  ): Promise<boolean> => submitForm('contact', enquiry, options)
+
+  const getLanguages = async (request?: Request): Promise<LanguageSnapshot> => {
+    if (unconfigured() || tenantId === undefined)
+      throw new Error('Languages needs configured credentials and an explicit tenantId')
+    const { isDraft, token } = await resolvePreview(request)
+    const url = new URL(`/api/languages/${isDraft && token ? 'preview' : 'published'}`, platformUrl)
+    url.searchParams.set('tenant', String(tenantId))
+    const response = await fetchWithRetry(
+      url,
+      {
+        ...contentAuth(isDraft, token),
+        cache: 'no-store',
+      },
+      'languages',
+    )
+    if (!response) throw new Error('Languages unavailable (network)')
+    if (!response.ok) throw new Error(explain(response.status, 'languages'))
+    const result = (await response.json()) as LanguageSnapshot
+    if (
+      result.version !== 1 ||
+      !Array.isArray(result.owners) ||
+      !(result.settings === null || typeof result.settings === 'object')
+    )
+      throw new Error('Invalid Languages response')
+    return result
+  }
+  return {
+    getCollection,
+    getPage,
+    getSitemapEntries,
+    getSiteSeo,
+    getLanguages,
+    submitEnquiry,
+    submitForm,
+  }
+}