@phis/ui 0.2.0 → 0.3.0

package/gateway/site-area.js

@@ -1,55 +1,42 @@
-import { cache } from "react";
+import { isPhiRecord } from "../helpers/is-record";
+import { definePhiRequestMemo } from "../server-helpers/request-memo";
 import "server-only";
-import { buildApiHeaders, buildApiUrl } from "../helpers/site-api";
-import { throwPhiCmsGatewayError } from "./errors";
-export const getExactSiteArea = cache(async function getExactSiteArea({ apiBaseUrl, internalToken, siteKey, path, locale, revision, review, cookieHeader, sourcePreset, }) {
-    if (!apiBaseUrl.trim()) {
-        throw new Error("Missing apiBaseUrl for getExactSiteArea.");
-    }
-    if (!internalToken.trim()) {
-        throw new Error("Missing internalToken for getExactSiteArea.");
-    }
-    if (!siteKey.trim()) {
-        throw new Error("Missing siteKey for getExactSiteArea.");
-    }
-    const url = new URL(buildApiUrl(apiBaseUrl, "/api/v1/site/area"));
-    url.searchParams.set("path", path);
-    url.searchParams.set("ownerModuleId", sourcePreset.ownerModuleId);
-    url.searchParams.set("presetKey", sourcePreset.presetKey);
+import { fetchPhiSiteApi } from "./site-api-request";
+export const getExactSiteArea = definePhiRequestMemo(async function getExactSiteArea({ apiBaseUrl, internalToken, siteKey, path, locale, revision, review, cookieHeader, sourcePreset, }) {
+    const searchParams = new URLSearchParams({
+        path,
+        ownerModuleId: sourcePreset.ownerModuleId,
+        presetKey: sourcePreset.presetKey,
+    });
     if (Number.isInteger(revision) && revision > 0) {
-        url.searchParams.set("revision", String(revision));
+        searchParams.set("revision", String(revision));
     }
     if (review?.kind === "area") {
-        url.searchParams.set("reviewKind", review.kind);
-        url.searchParams.set("reviewRevision", String(review.revisionId));
-    }
-    const response = await fetch(url.toString(), {
-        headers: buildApiHeaders({
-            token: internalToken,
-            siteKey,
-            locale,
-            includeToken: true,
-            includeSiteKey: true,
-            includeLocale: true,
-            gateway: true,
-            cookie: cookieHeader,
-        }),
-        cache: "no-store",
+        searchParams.set("reviewKind", review.kind);
+        searchParams.set("reviewRevision", String(review.revisionId));
+    }
+    const payload = await fetchPhiSiteApi({
+        context: "getExactSiteArea",
+        apiBaseUrl,
+        internalToken,
+        siteKey,
+        path: "/api/v1/site/area",
+        searchParams,
+        locale,
+        cookieHeader,
+        failure: "Failed to fetch exact CMS area",
+        notFoundIsNull: true,
     });
-    if (response.status === 404) {
+    if (payload === null) {
         return null;
     }
-    if (!response.ok) {
-        throwPhiCmsGatewayError(`Failed to fetch exact CMS area (${response.status}).`, response.status);
-    }
-    const payload = (await response.json());
     if (!payload?.preset?.preset) {
         throw new Error("Missing CMS area payload.");
     }
     return payload;
 });
 function readPublishedPublicPage(entry) {
-    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+    if (!isPhiRecord(entry)) {
         throw new Error("Invalid published Public Page projection.");
     }
     const value = entry;
@@ -78,28 +65,22 @@ function readPublishedPublicPage(entry) {
  * anonymous only, so no cookie is sent and no draft can be asked for.
  */
 export async function getPublicSiteAreaWithPublishedPages({ apiBaseUrl, internalToken, siteKey, locale, sourcePreset, }) {
-    const url = new URL(buildApiUrl(apiBaseUrl, "/api/v1/site/area"));
-    url.searchParams.set("path", "/");
-    url.searchParams.set("ownerModuleId", sourcePreset.ownerModuleId);
-    url.searchParams.set("presetKey", sourcePreset.presetKey);
-    url.searchParams.set("include", "publishedPages");
-    const response = await fetch(url.toString(), {
-        headers: buildApiHeaders({
-            token: internalToken,
-            siteKey,
-            locale,
-            includeToken: true,
-            includeSiteKey: true,
-            includeLocale: true,
-            gateway: true,
-            userAgent: "phis-ui-sitemap/1.0",
-        }),
-        cache: "no-store",
+    const payload = await fetchPhiSiteApi({
+        context: "getPublicSiteAreaWithPublishedPages",
+        apiBaseUrl,
+        internalToken,
+        siteKey,
+        path: "/api/v1/site/area",
+        searchParams: {
+            path: "/",
+            ownerModuleId: sourcePreset.ownerModuleId,
+            presetKey: sourcePreset.presetKey,
+            include: "publishedPages",
+        },
+        locale,
+        failure: "Failed to fetch the Public Area with its Pages",
+        userAgent: "phis-ui-sitemap/1.0",
     });
-    if (!response.ok) {
-        throwPhiCmsGatewayError(`Failed to fetch the Public Area with its Pages (${response.status}).`, response.status);
-    }
-    const payload = (await response.json().catch(() => null));
     if (!payload || !Array.isArray(payload.publishedPages)) {
         throw new Error("Missing published Public Page projection.");
     }
@@ -108,42 +89,46 @@ export async function getPublicSiteAreaWithPublishedPages({ apiBaseUrl, internal
         publishedPages: payload.publishedPages.map(readPublishedPublicPage),
     };
 }
-export const getCurrentSiteAreaDraft = cache(async function getCurrentSiteAreaDraft({ apiBaseUrl, internalToken, siteKey, area, path, locale, cookieHeader, sourcePreset, }) {
-    if (!apiBaseUrl.trim()) {
-        throw new Error("Missing apiBaseUrl for getCurrentSiteAreaDraft.");
-    }
-    if (!internalToken.trim()) {
-        throw new Error("Missing internalToken for getCurrentSiteAreaDraft.");
-    }
-    if (!siteKey.trim()) {
-        throw new Error("Missing siteKey for getCurrentSiteAreaDraft.");
-    }
-    const url = new URL(buildApiUrl(apiBaseUrl, "/api/site/cms/area/draft"));
-    url.searchParams.set("area", area?.trim() ? area.trim() : path === "/" ? "public" : path.replace(/^\//, ""));
-    url.searchParams.set("ownerModuleId", sourcePreset.ownerModuleId);
-    url.searchParams.set("presetKey", sourcePreset.presetKey);
-    const response = await fetch(url.toString(), {
-        headers: buildApiHeaders({
-            token: internalToken,
-            siteKey,
-            locale,
-            includeToken: true,
-            includeSiteKey: true,
-            includeLocale: true,
-            gateway: true,
-            cookie: cookieHeader,
-        }),
-        cache: "no-store",
-    });
-    if (response.status === 404) {
+function readAreaStructurePayload(value, area, kind) {
+    if (value === null) {
         return null;
     }
-    if (!response.ok) {
-        throwPhiCmsGatewayError(`Failed to fetch current CMS area draft (${response.status}).`, response.status);
-    }
-    const payload = (await response.json());
-    if (!payload?.preset?.preset) {
-        throw new Error("Missing CMS area draft payload.");
+    if (!isPhiRecord(value) || !isPhiRecord(value.preset) || !value.preset.preset) {
+        throw new Error(`Missing CMS area ${kind} payload for "${area}".`);
     }
-    return payload;
+    return value;
+}
+/**
+ * What several Areas store about their structure, in one request: per Area its open draft, else what is
+ * published, else nothing -- for each the answer of the draft read (`GET /api/site/cms/area/draft`) or of
+ * `getExactSiteArea`, without a request per Area and read (phis-server `POST /api/site/cms/area/structures`).
+ */
+export const getSiteAreaStructures = definePhiRequestMemo(async function getSiteAreaStructures({ apiBaseUrl, internalToken, siteKey, locale, cookieHeader, areas, }) {
+    const payload = await fetchPhiSiteApi({
+        context: "getSiteAreaStructures",
+        apiBaseUrl,
+        internalToken,
+        siteKey,
+        path: "/api/site/cms/area/structures",
+        method: "POST",
+        body: { areas },
+        locale,
+        cookieHeader,
+        failure: "Failed to fetch CMS area structures",
+    });
+    const answers = payload?.areas;
+    if (!Array.isArray(answers) || answers.length !== areas.length) {
+        throw new Error("Invalid CMS area structures payload.");
+    }
+    return areas.map((request, index) => {
+        const answer = answers[index];
+        if (!isPhiRecord(answer) || answer.area !== request.area) {
+            throw new Error(`CMS area structures answered out of order at "${request.area}".`);
+        }
+        return {
+            area: request.area,
+            draft: readAreaStructurePayload(answer.draft ?? null, request.area, "draft"),
+            published: readAreaStructurePayload(answer.published ?? null, request.area, "published"),
+        };
+    });
 });

package/gateway/site-auth-settings.d.ts

@@ -1,5 +1,5 @@
 import "server-only";
-export type PhiSiteAuthAdminSettings = {
+type PhiSiteAuthAdminSettings = {
     policy: {
         registrationMode: string;
         existingAccountLinking: string;
@@ -16,9 +16,10 @@ export type PhiSiteAuthAdminSettings = {
         roles: string[];
     };
 };
-export type GetResolvedSiteAuthAdminSettingsOptions = {
+type GetResolvedSiteAuthAdminSettingsOptions = {
     apiBaseUrl: string;
     internalToken: string;
     siteKey: string;
 };
-export declare const getResolvedSiteAuthAdminSettings: ({ apiBaseUrl, internalToken, siteKey, }: GetResolvedSiteAuthAdminSettingsOptions) => Promise<PhiSiteAuthAdminSettings>;
+export declare const getResolvedSiteAuthAdminSettings: (options: GetResolvedSiteAuthAdminSettingsOptions) => Promise<PhiSiteAuthAdminSettings>;
+export {};

package/gateway/site-auth-settings.js

@@ -1,32 +1,16 @@
-import { cache } from "react";
+import { definePhiRequestMemo } from "../server-helpers/request-memo";
 import "server-only";
-import { buildApiHeaders, buildApiUrl } from "../helpers/site-api";
-import { throwPhiCmsGatewayError } from "./errors";
-export const getResolvedSiteAuthAdminSettings = cache(async function getResolvedSiteAuthAdminSettings({ apiBaseUrl, internalToken, siteKey, }) {
-    if (!apiBaseUrl.trim()) {
-        throw new Error("Missing apiBaseUrl for getResolvedSiteAuthAdminSettings.");
-    }
-    if (!internalToken.trim()) {
-        throw new Error("Missing internalToken for getResolvedSiteAuthAdminSettings.");
-    }
-    if (!siteKey.trim()) {
-        throw new Error("Missing siteKey for getResolvedSiteAuthAdminSettings.");
-    }
-    const response = await fetch(buildApiUrl(apiBaseUrl, "/api/v1/site/auth/settings"), {
-        headers: buildApiHeaders({
-            token: internalToken,
-            siteKey,
-            includeToken: true,
-            includeSiteKey: true,
-            gateway: true,
-        }),
-        cache: "no-store",
+import { fetchPhiSiteApi } from "./site-api-request";
+export const getResolvedSiteAuthAdminSettings = definePhiRequestMemo(async function getResolvedSiteAuthAdminSettings({ apiBaseUrl, internalToken, siteKey, }) {
+    const payload = await fetchPhiSiteApi({
+        context: "getResolvedSiteAuthAdminSettings",
+        apiBaseUrl,
+        internalToken,
+        siteKey,
+        path: "/api/v1/site/auth/settings",
+        failure: "Failed to fetch site auth settings",
     });
-    if (!response.ok) {
-        throwPhiCmsGatewayError(`Failed to fetch site auth settings (${response.status}).`, response.status);
-    }
-    const payload = (await response.json());
-    if (typeof payload.auth?.policy?.registrationMode !== "string") {
+    if (typeof payload?.auth?.policy?.registrationMode !== "string") {
         throw new Error("Missing site auth settings payload.");
     }
     return payload.auth;

package/gateway/site-config.js

@@ -1,8 +1,7 @@
 import "server-only";
-import { buildApiHeaders, buildApiUrl } from "../helpers/site-api";
 import { syncPhiTranslationChangeMarkers } from "../helpers/translation-cache";
 import { clearPhiSiteReadCache, readPhiSiteReadCache } from "./site-read-cache";
-import { throwPhiCmsGatewayError } from "./errors";
+import { fetchPhiSiteApi } from "./site-api-request";
 /**
  * How long a Site process keeps its config before asking Core again. The config is small and carries the
  * change markers, so this is also how long a process can go on showing what another process's publish
@@ -38,23 +37,23 @@ export async function getResolvedSiteConfig({ apiBaseUrl, internalToken, siteKey
     return readPhiSiteReadCache(cacheKey, load, PHI_SITE_CONFIG_REFRESH_MS);
 }
 async function fetchSiteConfig({ apiBaseUrl, internalToken, siteKey }, cacheKey) {
-    const response = await fetch(buildApiUrl(apiBaseUrl, "/api/v1/site"), {
-        headers: buildApiHeaders({
-            token: internalToken,
-            siteKey,
-            includeToken: true,
-            includeSiteKey: true,
-            gateway: true,
-        }),
-        cache: "no-store",
+    const payload = await fetchPhiSiteApi({
+        context: "fetchSiteConfig",
+        apiBaseUrl,
+        internalToken,
+        siteKey,
+        path: "/api/v1/site",
+        failure: "Failed to fetch site config",
     });
-    if (!response.ok) {
-        throwPhiCmsGatewayError(`Failed to fetch site config (${response.status}).`, response.status);
-    }
-    const payload = (await response.json());
-    if (!payload.site) {
+    if (!payload?.site) {
         throw new Error("Missing site config payload.");
     }
+    if (typeof payload.site.sourceLocale !== "string" || !payload.site.sourceLocale.trim()) {
+        throw new Error("Missing source locale in site config payload.");
+    }
+    if (!Array.isArray(payload.site.localeCapabilities)) {
+        throw new Error("Missing locale capabilities in site config payload.");
+    }
     if (!payload.site.translationMarkers) {
         throw new Error("Missing translation markers in site config payload.");
     }

package/gateway/site-content.d.ts

@@ -0,0 +1,30 @@
+import "server-only";
+import type { PhiCmsResolvedContent } from "../types/cms";
+/** One Widget's bound content as phi-server answers it (phis-server CONTENT.md). */
+export type PhiBoundWidgetContent = {
+    instanceId: string;
+    contentId: number;
+    currentVersionId: number | null;
+    publishedVersionId: number | null;
+    submittedVersionId: number | null;
+    /** The bound value in the stage: a text, or an asset id; `null` where the stage has none. */
+    value: string | number | null;
+    /** The stage's version, resolved; `null` where the stage has none. */
+    content: PhiCmsResolvedContent | null;
+};
+type GetBoundWidgetContentsOptions = {
+    apiBaseUrl: string;
+    internalToken: string;
+    siteKey: string;
+    instanceIds: readonly string[];
+    /** `published` for the live Site; `current` for an editor, which needs the viewer's cookies. */
+    stage: "published" | "current";
+    locale?: string;
+    cookieHeader?: string | null;
+};
+/**
+ * The content bound to Widgets of a preset tree. A tree the Site stored answers its content with itself; a
+ * preset tree is the Module's and never reached phi-server, so its Widgets are asked for by instance.
+ */
+export declare const getBoundWidgetContents: (options: GetBoundWidgetContentsOptions) => Promise<PhiBoundWidgetContent[]>;
+export {};

package/gateway/site-content.js

@@ -0,0 +1,32 @@
+import "server-only";
+import { definePhiRequestMemo } from "../server-helpers/request-memo";
+import { fetchPhiSiteApi } from "./site-api-request";
+/** As many instances as one read of phi-server answers. */
+const PHI_BOUND_CONTENT_READ_LIMIT = 200;
+/**
+ * The content bound to Widgets of a preset tree. A tree the Site stored answers its content with itself; a
+ * preset tree is the Module's and never reached phi-server, so its Widgets are asked for by instance.
+ */
+export const getBoundWidgetContents = definePhiRequestMemo(async function getBoundWidgetContents({ apiBaseUrl, internalToken, siteKey, instanceIds, stage, locale, cookieHeader, }) {
+    const contents = [];
+    for (let start = 0; start < instanceIds.length; start += PHI_BOUND_CONTENT_READ_LIMIT) {
+        const searchParams = new URLSearchParams({
+            instanceIds: instanceIds.slice(start, start + PHI_BOUND_CONTENT_READ_LIMIT).join(","),
+            stage,
+            ...(locale ? { locale } : {}),
+        });
+        const payload = await fetchPhiSiteApi({
+            context: "getBoundWidgetContents",
+            apiBaseUrl,
+            internalToken,
+            siteKey,
+            path: "/api/v1/site/content",
+            searchParams,
+            locale,
+            cookieHeader,
+            failure: "Failed to fetch bound widget content",
+        });
+        contents.push(...(payload?.contents ?? []));
+    }
+    return contents;
+});

package/gateway/site-form-route.js

@@ -1,4 +1,4 @@
-import { buildPhiFormSubmitDescriptorFromHandlerProvider, resolvePhiFormSubmitTarget, } from "./form-submit";
+import { buildPhiFormSubmitRouteFromHandlerProvider, resolvePhiFormSubmitTarget, } from "./form-submit";
 import { resolvePhiServerFormHandler } from "./form-handler-resolution";
 import { PHIS_FORM_RELAY_HEADER, PHIS_SITE_KEY_HEADER } from "../constants/http-headers";
 import { isPhiRecord } from "../helpers/is-record";
@@ -161,10 +161,19 @@ export function buildPhiSiteFormRouteHandlers({ upstreamBaseUrl, buildHeaders, t
             signal: AbortSignal.timeout(timeoutMs),
         });
         const payload = (await response.json().catch(() => null));
-        if (!response.ok || typeof payload?.issuedAt !== "string" || typeof payload.formToken !== "string") {
+        if (!response.ok ||
+            typeof payload?.issuedAt !== "string" ||
+            typeof payload.formToken !== "string" ||
+            typeof payload.minSubmitMs !== "number" ||
+            typeof payload.maxSubmitMs !== "number") {
             return toJsonResponse({ ok: false, error: "Could not issue a form guard." }, response.status >= 400 ? response.status : 502);
         }
-        return toJsonResponse({ issuedAt: payload.issuedAt, formToken: payload.formToken }, 200);
+        return toJsonResponse({
+            issuedAt: payload.issuedAt,
+            formToken: payload.formToken,
+            minSubmitMs: payload.minSubmitMs,
+            maxSubmitMs: payload.maxSubmitMs,
+        }, 200);
     }
     async function GET(request) {
         const { searchParams } = new URL(request.url);
@@ -207,7 +216,7 @@ export function buildPhiSiteFormRouteHandlers({ upstreamBaseUrl, buildHeaders, t
         // A preview carries the credentials its Provider declares and no others -- the same rule a submit
         // follows. Forwarding the browser's cookies whole handed a Site session to a handler that asked for none.
         const previewHeaders = buildRelayHeaders(request, buildHeaders);
-        appendCredentialCookieForPolicy(previewHeaders, request, buildPhiFormSubmitDescriptorFromHandlerProvider(resolved.formId, resolved.provider).credentialPolicy);
+        appendCredentialCookieForPolicy(previewHeaders, request, buildPhiFormSubmitRouteFromHandlerProvider(resolved.formId, resolved.provider).credentialPolicy);
         return proxyJson(`${resolved.provider.upstreamPath}?token=${encodeURIComponent(token)}`, previewHeaders, upstreamBaseUrl, timeoutMs, { method: "GET" });
     }
     async function POST(request) {
@@ -233,7 +242,7 @@ export function buildPhiSiteFormRouteHandlers({ upstreamBaseUrl, buildHeaders, t
             if (!resolved) {
                 return toJsonResponse({ ok: false, error: "Form handler is not active for this Area." }, 404);
             }
-            const descriptor = buildPhiFormSubmitDescriptorFromHandlerProvider(resolved.formId, resolved.provider);
+            const descriptor = buildPhiFormSubmitRouteFromHandlerProvider(resolved.formId, resolved.provider);
             if (descriptor.transport !== "relay") {
                 // The relay is the only transport that is carried out; relaying a handler that declared another
                 // would send its values somewhere it never asked them to go.

package/gateway/site-media-settings.d.ts

@@ -1,5 +1,5 @@
 import "server-only";
-export type PhiSiteMediaSettings = {
+type PhiSiteMediaSettings = {
     userSpacesEnabled: boolean;
     groupSpacesEnabled: boolean;
     defaultUserQuotaBytes: number | null;
@@ -12,19 +12,20 @@ export type PhiSiteMediaSettings = {
     maxObjectBytes: number;
 };
 /** One Add-on's own store: what it holds, and the figure it is measured against. */
-export type PhiSiteAddonMediaSpace = {
+type PhiSiteAddonMediaSpace = {
     addonId: string;
     spaceId: number;
     usedBytes: number;
     reservedBytes: number;
     quotaBytes: number | null;
 };
-export type PhiSiteMediaSettingsResult = PhiSiteMediaSettings & {
+type PhiSiteMediaSettingsResult = PhiSiteMediaSettings & {
     addonSpaces: readonly PhiSiteAddonMediaSpace[];
 };
-export type GetResolvedSiteMediaSettingsOptions = {
+type GetResolvedSiteMediaSettingsOptions = {
     apiBaseUrl: string;
     internalToken: string;
     siteKey: string;
 };
-export declare const getResolvedSiteMediaSettings: ({ apiBaseUrl, internalToken, siteKey, }: GetResolvedSiteMediaSettingsOptions) => Promise<PhiSiteMediaSettingsResult>;
+export declare const getResolvedSiteMediaSettings: (options: GetResolvedSiteMediaSettingsOptions) => Promise<PhiSiteMediaSettingsResult>;
+export {};

package/gateway/site-media-settings.js

@@ -1,32 +1,16 @@
-import { cache } from "react";
+import { definePhiRequestMemo } from "../server-helpers/request-memo";
 import "server-only";
-import { buildApiHeaders, buildApiUrl } from "../helpers/site-api";
-import { throwPhiCmsGatewayError } from "./errors";
-export const getResolvedSiteMediaSettings = cache(async function getResolvedSiteMediaSettings({ apiBaseUrl, internalToken, siteKey, }) {
-    if (!apiBaseUrl.trim()) {
-        throw new Error("Missing apiBaseUrl for getResolvedSiteMediaSettings.");
-    }
-    if (!internalToken.trim()) {
-        throw new Error("Missing internalToken for getResolvedSiteMediaSettings.");
-    }
-    if (!siteKey.trim()) {
-        throw new Error("Missing siteKey for getResolvedSiteMediaSettings.");
-    }
-    const response = await fetch(buildApiUrl(apiBaseUrl, "/api/v1/site/media/settings"), {
-        headers: buildApiHeaders({
-            token: internalToken,
-            siteKey,
-            includeToken: true,
-            includeSiteKey: true,
-            gateway: true,
-        }),
-        cache: "no-store",
+import { fetchPhiSiteApi } from "./site-api-request";
+export const getResolvedSiteMediaSettings = definePhiRequestMemo(async function getResolvedSiteMediaSettings({ apiBaseUrl, internalToken, siteKey, }) {
+    const payload = await fetchPhiSiteApi({
+        context: "getResolvedSiteMediaSettings",
+        apiBaseUrl,
+        internalToken,
+        siteKey,
+        path: "/api/v1/site/media/settings",
+        failure: "Failed to fetch site media settings",
     });
-    if (!response.ok) {
-        throwPhiCmsGatewayError(`Failed to fetch site media settings (${response.status}).`, response.status);
-    }
-    const payload = (await response.json());
-    if (typeof payload.media?.userSpacesEnabled !== "boolean") {
+    if (typeof payload?.media?.userSpacesEnabled !== "boolean") {
         throw new Error("Missing site media settings payload.");
     }
     // A Site with no Add-on holding files reports none, which is an answer and not a missing field.

package/gateway/site-nav.js

@@ -1,6 +1,6 @@
+import { isPhiRecord } from "../helpers/is-record";
 import "server-only";
-import { buildApiHeaders, buildApiUrl } from "../helpers/site-api";
-import { throwPhiCmsGatewayError } from "./errors";
+import { fetchPhiSiteApi } from "./site-api-request";
 import { readPhiSiteReadCache } from "./site-read-cache";
 /**
  * Where a folder address of an Area leads on the live Site, as a Page reference, or null when it leads
@@ -8,48 +8,35 @@ import { readPhiSiteReadCache } from "./site-read-cache";
  * process at once, and a cache tag would reach only the one that saw it.
  */
 export async function fetchSiteNavigationFolderTarget({ apiBaseUrl, internalToken, siteKey, area, path, }) {
-    const url = new URL(buildApiUrl(apiBaseUrl, "/api/v1/site/nav/folder"));
-    url.searchParams.set("area", area);
-    url.searchParams.set("path", path);
-    const response = await fetch(url, {
-        headers: buildApiHeaders({
-            token: internalToken,
-            siteKey,
-            includeToken: true,
-            includeSiteKey: true,
-            gateway: true,
-        }),
-        cache: "no-store",
+    const payload = await fetchPhiSiteApi({
+        context: "fetchSiteNavigationFolderTarget",
+        apiBaseUrl,
+        internalToken,
+        siteKey,
+        path: "/api/v1/site/nav/folder",
+        searchParams: { area, path },
+        failure: "Failed to resolve folder address",
+        notFoundIsNull: true,
     });
-    if (response.status === 404) {
+    if (payload === null) {
         return null;
     }
-    if (!response.ok) {
-        throwPhiCmsGatewayError(`Failed to resolve folder address (${response.status}).`, response.status);
-    }
-    const payload = (await response.json());
     return typeof payload.reference === "string" ? payload.reference : null;
 }
 export async function fetchSiteNavigationScopes({ apiBaseUrl, internalToken, siteKey, }) {
-    const response = await fetch(buildApiUrl(apiBaseUrl, "/api/v1/site/nav/scopes"), {
-        headers: buildApiHeaders({
-            token: internalToken,
-            siteKey,
-            includeToken: true,
-            includeSiteKey: true,
-            gateway: true,
-        }),
-        cache: "no-store",
+    const payload = await fetchPhiSiteApi({
+        context: "fetchSiteNavigationScopes",
+        apiBaseUrl,
+        internalToken,
+        siteKey,
+        path: "/api/v1/site/nav/scopes",
+        failure: "Failed to fetch site navigation scopes",
     });
-    if (!response.ok) {
-        throwPhiCmsGatewayError(`Failed to fetch site navigation scopes (${response.status}).`, response.status);
-    }
-    const payload = (await response.json());
-    if (!Array.isArray(payload.scopes)) {
+    if (!Array.isArray(payload?.scopes)) {
         throw new Error("Missing site navigation scopes payload.");
     }
     return payload.scopes.flatMap((scope) => {
-        if (!scope || typeof scope !== "object" || Array.isArray(scope)) {
+        if (!isPhiRecord(scope)) {
             return [];
         }
         const record = scope;
@@ -65,15 +52,6 @@ export async function fetchSiteNavigationScopes({ apiBaseUrl, internalToken, sit
     });
 }
 export async function fetchSiteNavigationOverlay({ apiBaseUrl, internalToken, siteKey, navKey, locale, revision, review, cookieHeader, }) {
-    if (!apiBaseUrl.trim()) {
-        throw new Error("Missing apiBaseUrl for fetchSiteNavigationOverlay.");
-    }
-    if (!internalToken.trim()) {
-        throw new Error("Missing internalToken for fetchSiteNavigationOverlay.");
-    }
-    if (!siteKey.trim()) {
-        throw new Error("Missing siteKey for fetchSiteNavigationOverlay.");
-    }
     if (!navKey.trim()) {
         throw new Error("Missing navKey for fetchSiteNavigationOverlay.");
     }
@@ -89,34 +67,29 @@ export async function fetchSiteNavigationOverlay({ apiBaseUrl, internalToken, si
         search.set("reviewKind", review.kind);
         search.set("reviewRevision", String(review.revisionId));
     }
-    const url = buildApiUrl(apiBaseUrl, `/api/v1/site/nav?${search.toString()}`);
     // A revision or a review asks for a draft the author is looking at, never what visitors get.
     const readsDraft = search.has("revision") || search.has("reviewKind");
-    const load = () => fetchNavigationOverlay(url, internalToken, siteKey, readsDraft ? cookieHeader : undefined);
+    const load = () => fetchNavigationOverlay(apiBaseUrl, internalToken, siteKey, search, readsDraft ? cookieHeader : undefined);
     if (process.env.NODE_ENV === "development" || readsDraft) {
         return load();
     }
     return readPhiSiteReadCache(`site-nav:${siteKey.trim().toLowerCase()}:${search.toString()}`, load);
 }
-async function fetchNavigationOverlay(url, internalToken, siteKey, cookieHeader) {
-    const response = await fetch(url, {
-        headers: buildApiHeaders({
-            token: internalToken,
-            siteKey,
-            includeToken: true,
-            includeSiteKey: true,
-            gateway: true,
-            cookie: cookieHeader,
-        }),
-        cache: "no-store",
+async function fetchNavigationOverlay(apiBaseUrl, internalToken, siteKey, search, cookieHeader) {
+    const payload = await fetchPhiSiteApi({
+        context: "fetchSiteNavigationOverlay",
+        apiBaseUrl,
+        internalToken,
+        siteKey,
+        path: "/api/v1/site/nav",
+        searchParams: search,
+        cookieHeader,
+        failure: "Failed to fetch site nav",
+        notFoundIsNull: true,
     });
-    if (response.status === 404) {
+    if (payload === null) {
         return null;
     }
-    if (!response.ok) {
-        throwPhiCmsGatewayError(`Failed to fetch site nav (${response.status}).`, response.status);
-    }
-    const payload = (await response.json());
     if (!payload.overlay || typeof payload.overlay !== "object") {
         throw new Error("Missing site navigation overlay payload.");
     }