@phis/ui 0.2.1 → 0.4.0

package/gateway/content-entries.d.ts

@@ -0,0 +1,57 @@
+import "server-only";
+import type { PhiContentEntryKind } from "../constants/content-entry-kinds";
+import type { PhiSiteContentEntry, PhiSiteContentEntryPage } from "../types/content-entries";
+type FetchPhiSiteContentEntryBase = {
+    kind: PhiContentEntryKind;
+    apiBaseUrl: string;
+    internalToken: string;
+    siteKey: string;
+    /** The language the page is being drawn in; Core resolves each entry's text for it. */
+    locale: string;
+};
+export type FetchPhiSiteContentEntriesOptions = FetchPhiSiteContentEntryBase & {
+    /**
+     * How many entries the caller will show, newest first. Core cuts the list there before it translates,
+     * so a Site with years of entries does not pay for translating all of them to draw ten.
+     */
+    limit: number;
+    /**
+     * Which categories, by id, and `none` for the entries filed under no category; absent or empty is every
+     * entry. Core filters before it cuts at `limit`, so a list of ten still shows ten.
+     */
+    categories?: readonly string[];
+};
+/**
+ * One kind's published entries, read while the page is being rendered.
+ *
+ * A gateway read rather than a browser one, which the endpoint enforces anyway: it wants the internal
+ * token, which a browser must never hold. It also means an entry that has expired is absent from the HTML
+ * instead of appearing and then vanishing.
+ *
+ * `no-store` is right here despite the page being cached: on a Public page this fetch runs inside the
+ * static render, which is itself kept and renewed at most once a minute
+ * ([STATIC_RENDERING.md](../STATIC_RENDERING.md)). A second cache underneath it would only add a second
+ * age to reason about.
+ */
+export declare function fetchPhiSiteContentEntries(options: FetchPhiSiteContentEntriesOptions): Promise<PhiSiteContentEntry[]>;
+type FetchPhiSiteContentEntryPageOptions = FetchPhiSiteContentEntryBase & {
+    slug: string;
+    /** How many related entries to answer beside it; absent asks for none. Core allows 1 to 12. */
+    relatedLimit?: number;
+};
+/**
+ * One published entry by its address and, where asked, the entries closest to it -- everything a detail
+ * Page shows, in one question; `null` where the kind has none answering there: never published, expired,
+ * or a slug nobody wrote. The detail route answers 404 on `null`.
+ *
+ * Once per request for the same question (`definePhiRequestMemo`): the detail route's tree reads it for
+ * the Page's title and status, and the header, the body and the related list read it again while the page
+ * is drawn. All of them ask with the same options, so Core is asked once.
+ */
+export declare const fetchPhiSiteContentEntryPage: (options: FetchPhiSiteContentEntryPageOptions) => Promise<PhiSiteContentEntryPage | null>;
+/**
+ * How many relatives a detail Page asks for. One number for the whole Page, because every part asks the
+ * same question and a part asking for four while another asks for three would be two questions to Core.
+ */
+export declare const PHI_CONTENT_ENTRY_RELATED_LIMIT = 3;
+export {};

package/gateway/content-entries.js

@@ -0,0 +1,141 @@
+import "server-only";
+import { isPhiRecord } from "../helpers/is-record";
+import { readPhiLinkTarget } from "../types/references";
+import { definePhiRequestMemo } from "../server-helpers/request-memo";
+import { fetchPhiSiteApi } from "./site-api-request";
+function readString(value) {
+    return typeof value === "string" ? value : "";
+}
+function readTerm(value) {
+    if (!isPhiRecord(value))
+        return null;
+    const slug = readString(value.slug).trim();
+    const label = readString(value.label).trim();
+    return slug && label ? { slug, label } : null;
+}
+function readAuthor(value) {
+    if (!isPhiRecord(value))
+        return null;
+    const name = readString(value.name).trim();
+    if (!name)
+        return null;
+    const url = isPhiRecord(value.avatar) ? readString(value.avatar.url).trim() : "";
+    return { name, avatar: url ? { url } : null };
+}
+function readContentEntry(value) {
+    if (!isPhiRecord(value)) {
+        return null;
+    }
+    const title = readString(value.title).trim();
+    const created = readString(value.created).trim();
+    // An entry without a title or a date has nothing to show and nothing to sort by. Dropped rather than
+    // rendered as a gap, and dropped alone rather than taking the rest of the list with it.
+    if (!title || !created) {
+        return null;
+    }
+    return {
+        id: readString(value.id) || readString(value.slug),
+        slug: readString(value.slug),
+        created,
+        outdated: readString(value.outdated) || null,
+        title,
+        subtitle: readString(value.subtitle),
+        content: readString(value.content),
+        link: readPhiLinkTarget(value.link),
+        category: readTerm(value.category),
+        tags: Array.isArray(value.tags)
+            ? value.tags.map(readTerm).filter((tag) => tag !== null)
+            : [],
+        author: readAuthor(value.author),
+        sourceLocale: readString(value.sourceLocale).trim() || null,
+        // Absent means yes, which is the default everywhere this switch appears.
+        translate: value.translate !== false,
+    };
+}
+async function fetchEntries(options, searchParams) {
+    const payload = await fetchPhiSiteApi({
+        context: "fetchPhiSiteContentEntries",
+        apiBaseUrl: options.apiBaseUrl,
+        internalToken: options.internalToken,
+        siteKey: options.siteKey,
+        path: `/api/v1/entries/${options.kind}`,
+        searchParams,
+        locale: options.locale,
+        failure: `Entries fetch failed (${options.kind})`,
+        userAgent: "phis-ui-entries/1.0",
+    });
+    if (!isPhiRecord(payload) || !Array.isArray(payload.entries)) {
+        throw new Error("Entries answered without a list.");
+    }
+    return payload.entries
+        .map((entry) => readContentEntry(entry))
+        .filter((entry) => entry !== null);
+}
+/**
+ * One kind's published entries, read while the page is being rendered.
+ *
+ * A gateway read rather than a browser one, which the endpoint enforces anyway: it wants the internal
+ * token, which a browser must never hold. It also means an entry that has expired is absent from the HTML
+ * instead of appearing and then vanishing.
+ *
+ * `no-store` is right here despite the page being cached: on a Public page this fetch runs inside the
+ * static render, which is itself kept and renewed at most once a minute
+ * ([STATIC_RENDERING.md](../STATIC_RENDERING.md)). A second cache underneath it would only add a second
+ * age to reason about.
+ */
+export async function fetchPhiSiteContentEntries(options) {
+    if (!Number.isInteger(options.limit) || options.limit <= 0) {
+        throw new Error("fetchPhiSiteContentEntries needs a positive integer limit.");
+    }
+    return fetchEntries(options, {
+        limit: String(options.limit),
+        ...(options.categories?.length ? { categories: options.categories.join(",") } : {}),
+    });
+}
+/**
+ * One published entry by its address and, where asked, the entries closest to it -- everything a detail
+ * Page shows, in one question; `null` where the kind has none answering there: never published, expired,
+ * or a slug nobody wrote. The detail route answers 404 on `null`.
+ *
+ * Once per request for the same question (`definePhiRequestMemo`): the detail route's tree reads it for
+ * the Page's title and status, and the header, the body and the related list read it again while the page
+ * is drawn. All of them ask with the same options, so Core is asked once.
+ */
+export const fetchPhiSiteContentEntryPage = definePhiRequestMemo(async (options) => {
+    const slug = options.slug.trim();
+    if (!slug)
+        return null;
+    const payload = await fetchPhiSiteApi({
+        context: "fetchPhiSiteContentEntryPage",
+        apiBaseUrl: options.apiBaseUrl,
+        internalToken: options.internalToken,
+        siteKey: options.siteKey,
+        path: `/api/v1/entries/${options.kind}/${encodeURIComponent(slug)}`,
+        searchParams: options.relatedLimit
+            ? { include: "related", relatedLimit: String(options.relatedLimit) }
+            : {},
+        locale: options.locale,
+        failure: `Entry fetch failed (${options.kind})`,
+        userAgent: "phis-ui-entries/1.0",
+        notFoundIsNull: true,
+    });
+    if (payload === null)
+        return null;
+    if (!isPhiRecord(payload)) {
+        throw new Error("The entry answered without a body.");
+    }
+    const entry = readContentEntry(payload.entry);
+    if (!entry)
+        return null;
+    return {
+        entry,
+        related: Array.isArray(payload.related)
+            ? payload.related.map(readContentEntry).filter((item) => item !== null)
+            : null,
+    };
+});
+/**
+ * How many relatives a detail Page asks for. One number for the whole Page, because every part asks the
+ * same question and a part asking for four while another asks for three would be two questions to Core.
+ */
+export const PHI_CONTENT_ENTRY_RELATED_LIMIT = 3;

package/gateway/dashboard-cards-route.js

@@ -1,3 +1,4 @@
+import { jsonResponse, readPhiInternalRequestPath, splitPhiRequestPath } from "./route-handler-helpers";
 import "server-only";
 import { isPhiCmsAreaKey, resolvePhiCmsAreaMask, } from "../constants/cms-areas";
 import { canPhiViewerAccess } from "../types/access";
@@ -9,38 +10,8 @@ import { getPhiExactSiteArea } from "../server-helpers/cms";
 import { resolveCmsRootRoute } from "../server-helpers/cms-route";
 import { buildPhiBlockRuntime, loadPhiSiteRequestContext, } from "../server-helpers/runtime";
 import { runWithPhiRequestRuntime } from "../server-helpers/request-runtime";
-import { isPhiDashboardCardId, } from "../types/dashboard-cards";
-function json(payload, status = 200) {
-    return Response.json(payload, {
-        status,
-        headers: { "cache-control": "no-store" },
-    });
-}
-/** An internal path, and only one: a card request never leaves this Site. */
-function readInternalPath(value, requestUrl) {
-    const normalized = value?.trim() ?? "";
-    if (!normalized.startsWith("/") || normalized.startsWith("//")) {
-        return null;
-    }
-    try {
-        return new URL(normalized, requestUrl).pathname;
-    }
-    catch {
-        return null;
-    }
-}
-function splitTargetPath(pathname) {
-    const segments = pathname.split("/").filter(Boolean).map((segment) => {
-        try {
-            return decodeURIComponent(segment);
-        }
-        catch {
-            return segment;
-        }
-    });
-    const [root, ...path] = segments;
-    return root ? { root, path } : null;
-}
+import { logRuntimeEvent } from "../net/log";
+import { createPhiDashboardCardId, isPhiDashboardCardId, } from "../types/dashboard-cards";
 /**
  * The path a card's target resolves to, or none.
  *
@@ -120,27 +91,60 @@ async function resolveDashboardCardScope({ bridge, area, locale, path, cookieHea
     return { activeModuleIds, routeTable, cardContext, scopeRuntime };
 }
 /**
- * The card providers of the Modules this Area actually runs.
+ * The card providers of the Modules this Area actually runs, and the Modules whose provider did not load.
  *
  * Keyed by Module so a payload request can find the one that owns a card without asking the other
  * eleven, and loaded here rather than at module scope because a Site whose Dashboard nobody opens
- * should never pull a provider into its graph.
+ * should never pull a provider into its graph. A contribution that fails to load is kept by name: the
+ * list answers for it with one error card (`buildContributorFailureRow`) rather than with silence.
  */
-async function loadActiveCardProviders(bridge, activeModuleIds) {
-    const loaded = await Promise.all([...activeModuleIds].map(async (moduleId) => {
+async function loadActiveCardProviders(bridge, area, activeModuleIds) {
+    const providers = [];
+    const failures = new Map();
+    await Promise.all([...activeModuleIds].map(async (moduleId) => {
         const contribution = bridge.runtimeModuleCatalog.get(moduleId)?.dashboardCards;
-        if (!contribution) {
-            return null;
+        // An Area the contribution does not name never loads its provider (`dashboardCards.areas`).
+        if (!contribution || !contribution.areas.includes(area)) {
+            return;
         }
         try {
-            return [moduleId, await contribution.load()];
+            providers.push([moduleId, await contribution.load()]);
         }
         catch (error) {
-            console.warn("[phi-dashboard-cards] Card provider failed to load.", { moduleId, error });
-            return null;
+            failures.set(moduleId, describeError(error, "The card provider could not be loaded."));
+            logRuntimeEvent("warn", "dashboard.cards.provider_load_failed", {
+                message: "Card provider failed to load.",
+                pluginKey: moduleId,
+                error,
+            });
         }
     }));
-    return loaded.filter((entry) => entry !== null);
+    return { providers, failures };
+}
+function describeError(error, fallback) {
+    return error instanceof Error && error.message ? error.message : fallback;
+}
+/**
+ * The one row a Module gets when it could not say which cards it has.
+ *
+ * A contributor whose provider did not load, or whose list threw, used to leave nothing behind -- and a
+ * Dashboard with a gap where a Module's cards should be reads as "this Module has no cards", which is a
+ * different statement from "this Module is broken". The row is in the Module's own namespace, carries
+ * its first payload already, and that payload is the error, so the card View draws it the way it draws
+ * any card whose payload failed (DASHBOARD.md, "A failure is one card").
+ */
+function buildContributorFailureRow(moduleId, message) {
+    const cardId = createPhiDashboardCardId(moduleId, "unavailable");
+    return {
+        cardId,
+        form: "stat",
+        title: moduleId,
+        payload: {
+            cardId,
+            error: message,
+            resolvedAt: new Date().toISOString(),
+        },
+    };
 }
 /**
  * A card belongs to the Module that offered it, and says so in its own id.
@@ -153,19 +157,45 @@ async function loadActiveCardProviders(bridge, activeModuleIds) {
 function ownsCardId(moduleId, cardId) {
     return isPhiDashboardCardId(cardId) && cardId.startsWith(`${moduleId}/cards/`);
 }
+/**
+ * One card's payload, from the Module that owns it.
+ *
+ * A payload that throws is this card saying so, not the request failing. The card is on screen
+ * already -- it was in the list -- so the honest answer is an error in it rather than a status the
+ * browser can only report as "unavailable". The same answer whether the card came with the list or was
+ * asked for on its own.
+ */
+async function resolveCardPayload(provider, cardId, cardContext, scopeRuntime) {
+    try {
+        return await runWithPhiRequestRuntime(scopeRuntime, () => provider.resolveCard(cardId, cardContext));
+    }
+    catch (error) {
+        logRuntimeEvent("warn", "dashboard.cards.payload_failed", {
+            message: "Card payload failed.",
+            targetType: "dashboard-card",
+            targetId: cardId,
+            error,
+        });
+        return {
+            cardId,
+            error: describeError(error, "This card could not be resolved."),
+            resolvedAt: new Date().toISOString(),
+        };
+    }
+}
 export function buildPhiDashboardCardsRouteHandler({ loadAreaBridge, }) {
     return async function GET(request) {
         const requestUrl = new URL(request.url);
         const area = requestUrl.searchParams.get("area")?.trim().toLowerCase() ?? "";
-        const pathname = readInternalPath(requestUrl.searchParams.get("path"), request.url);
+        const pathname = readPhiInternalRequestPath(requestUrl.searchParams.get("path"), request.url);
         const card = requestUrl.searchParams.get("card")?.trim() ?? "";
         if (!isPhiCmsAreaKey(area) || !pathname || (card && !isPhiDashboardCardId(card))) {
-            return json({ error: "bad_request" }, 400);
+            return jsonResponse({ error: "bad_request" }, 400);
         }
         const bridge = await loadAreaBridge(area);
-        const target = splitTargetPath(pathname);
+        const target = splitPhiRequestPath(pathname);
         if (!bridge?.runtime || !target) {
-            return json({ cards: [] });
+            return jsonResponse({ cards: [] });
         }
         try {
             /*
@@ -175,7 +205,7 @@ export function buildPhiDashboardCardsRouteHandler({ loadAreaBridge, }) {
              */
             const resolvedRoute = await resolveCmsRootRoute(target.root, target.path, bridge.runtime);
             if (resolvedRoute.area !== area) {
-                return json({ cards: [] });
+                return jsonResponse({ cards: [] });
             }
             const scope = await resolveDashboardCardScope({
                 bridge,
@@ -185,46 +215,32 @@ export function buildPhiDashboardCardsRouteHandler({ loadAreaBridge, }) {
                 cookieHeader: request.headers.get("cookie") ?? "",
             });
             if (!scope) {
-                return json({ cards: [] });
+                return jsonResponse({ cards: [] });
             }
             const { activeModuleIds, routeTable, cardContext, scopeRuntime } = scope;
-            const providers = await loadActiveCardProviders(bridge, activeModuleIds);
+            const { providers, failures } = await loadActiveCardProviders(bridge, area, activeModuleIds);
             if (card) {
                 const owner = providers.find(([moduleId]) => ownsCardId(moduleId, card));
                 if (!owner) {
-                    return json({ error: "unknown_card" }, 404);
-                }
-                /*
-                 * A payload that throws is this card saying so, not the request failing. The card is on screen
-                 * already -- it was in the list -- so the honest answer is an error in it rather than a status
-                 * the browser can only report as "unavailable".
-                 */
-                try {
-                    const payload = await runWithPhiRequestRuntime(scopeRuntime, () => owner[1].resolveCard(card, cardContext));
-                    return json(payload);
-                }
-                catch (error) {
-                    console.warn("[phi-dashboard-cards] Card payload failed.", { card, error });
-                    return json({
-                        cardId: card,
-                        error: error instanceof Error ? error.message : "This card could not be resolved.",
-                        resolvedAt: new Date().toISOString(),
-                    });
+                    return jsonResponse({ error: "unknown_card" }, 404);
                 }
+                return jsonResponse(await resolveCardPayload(owner[1], card, cardContext, scopeRuntime));
             }
             /*
              * Every Module is asked at once. One that throws loses its own cards and nobody else's, which is
-             * the list-half of the same promise the payloads keep: a broken contributor is a gap, not a blank
-             * Dashboard.
+             * the list-half of the same promise the payloads keep: a broken contributor is one error card in
+             * its own name, not a blank Dashboard and not a quiet gap.
              */
             const lists = await Promise.all(providers.map(async ([moduleId, provider]) => {
                 try {
                     const cards = await runWithPhiRequestRuntime(scopeRuntime, () => provider.listCards(cardContext));
                     return cards.filter((descriptor) => {
                         if (!ownsCardId(moduleId, descriptor.cardId)) {
-                            console.warn("[phi-dashboard-cards] Module offered a card it does not own.", {
-                                moduleId,
-                                cardId: descriptor.cardId,
+                            logRuntimeEvent("warn", "dashboard.cards.foreign_card_refused", {
+                                message: "Module offered a card it does not own.",
+                                pluginKey: moduleId,
+                                targetType: "dashboard-card",
+                                targetId: descriptor.cardId,
                             });
                             return false;
                         }
@@ -232,7 +248,12 @@ export function buildPhiDashboardCardsRouteHandler({ loadAreaBridge, }) {
                     });
                 }
                 catch (error) {
-                    console.warn("[phi-dashboard-cards] Card list failed.", { moduleId, error });
+                    logRuntimeEvent("warn", "dashboard.cards.list_failed", {
+                        message: "Card list failed.",
+                        pluginKey: moduleId,
+                        error,
+                    });
+                    failures.set(moduleId, describeError(error, "The card list could not be read."));
                     return [];
                 }
             }));
@@ -244,7 +265,7 @@ export function buildPhiDashboardCardsRouteHandler({ loadAreaBridge, }) {
              * is the one order that is stable across restarts and decided by nobody, and it holds until the
              * Site's own decisions arrive to replace it.
              */
-            const cards = lists
+            const rows = lists
                 .flat()
                 .sort((left, right) => left.cardId.localeCompare(right.cardId))
                 .map((descriptor) => ({
@@ -259,11 +280,34 @@ export function buildPhiDashboardCardsRouteHandler({ loadAreaBridge, }) {
                     return href ? { href } : {};
                 })(),
             }));
-            return json({ cards });
+            /*
+             * Each card's first payload, with the list and from the context this request already resolved.
+             *
+             * Asked for one by one from the browser, every card re-resolved the locale, the viewer, the
+             * capabilities and the Area for itself -- five cards, six request chains, some thirty Core calls
+             * for one Dashboard. Resolved here they share one context and run side by side; a payload that
+             * throws is still an error in its own row. The card endpoint above stays for what comes later,
+             * one card at a time: a refresh.
+             */
+            const cards = await Promise.all(rows.map(async (row) => {
+                const owner = providers.find(([moduleId]) => ownsCardId(moduleId, row.cardId));
+                return owner
+                    ? { ...row, payload: await resolveCardPayload(owner[1], row.cardId, cardContext, scopeRuntime) }
+                    : row;
+            }));
+            const failureRows = [...failures.entries()]
+                .sort(([left], [right]) => left.localeCompare(right))
+                .map(([moduleId, message]) => buildContributorFailureRow(moduleId, message));
+            return jsonResponse({ cards: [...cards, ...failureRows] });
         }
         catch (error) {
-            console.warn("[phi-dashboard-cards] Request failed.", { area, card, error });
-            return json({ error: "unavailable" }, 503);
+            logRuntimeEvent("warn", "dashboard.cards.request_failed", {
+                message: "Dashboard cards request failed.",
+                area,
+                error,
+                meta: { card },
+            });
+            return jsonResponse({ error: "unavailable" }, 503);
         }
     };
 }

package/gateway/errors.d.ts

@@ -3,6 +3,5 @@ export declare class PhiCmsGatewayError extends Error {
     readonly status: number;
     constructor(message: string, status: number);
 }
-export declare function isPhiCmsGatewayError(error: unknown): error is PhiCmsGatewayError;
 export declare function isPhiCmsGatewayAuthError(error: unknown): error is PhiCmsGatewayError;
 export declare function throwPhiCmsGatewayError(message: string, status: number): never;

package/gateway/errors.js

@@ -7,7 +7,7 @@ export class PhiCmsGatewayError extends Error {
         this.status = status;
     }
 }
-export function isPhiCmsGatewayError(error) {
+function isPhiCmsGatewayError(error) {
     return error instanceof PhiCmsGatewayError;
 }
 export function isPhiCmsGatewayAuthError(error) {

package/gateway/form-registry.d.ts

@@ -4,11 +4,6 @@ import { type PhiFormDefinitionLike, type PhiResolvedFormDefinition } from "../c
 import type { PhiFormDescriptor } from "../types/form-descriptor";
 import type { PhiRuntimeModuleId } from "../types/cms-module-descriptors";
 import type { PhiFormId } from "../types/form-id";
-export declare const PHI_FORM_DEFINITION_STATUS: {
-    readonly workingDraft: 0;
-    readonly published: 1;
-    readonly archived: 2;
-};
 export type PhiFormRegistryRecord = {
     id: number;
     ownerModuleId: PhiRuntimeModuleId;
@@ -41,7 +36,7 @@ export type GetResolvedFormDefinitionOptions = FormRegistryRequestOptions & {
 export type ListResolvedFormDefinitionsOptions = FormRegistryRequestOptions & {
     presetDefinitions: readonly PhiRuntimeModuleFormDefinition[];
 };
-export declare const fetchFormRegistry: ({ apiBaseUrl, internalToken, siteKey, }: FormRegistryRequestOptions) => Promise<PhiFormRegistryRecord[]>;
+export declare const fetchFormRegistry: (options: FormRegistryRequestOptions) => Promise<PhiFormRegistryRecord[]>;
 export declare function listResolvedFormDefinitions({ apiBaseUrl, internalToken, siteKey, presetDefinitions, }: ListResolvedFormDefinitionsOptions): Promise<PhiResolvedFormDefinition<PhiFormDefinitionLike>[]>;
 export declare function getResolvedFormDefinition({ apiBaseUrl, internalToken, siteKey, formId, presetDefinitions, }: GetResolvedFormDefinitionOptions): Promise<PhiResolvedFormDefinition<PhiFormDefinitionLike> | null>;
 export {};

package/gateway/form-registry.js

@@ -1,12 +1,11 @@
-import { cache } from "react";
+import { definePhiRequestMemo } from "../server-helpers/request-memo";
 import "server-only";
-import { buildApiHeaders, buildApiUrl } from "../helpers/site-api";
 import { resolvePhiFormDefinition, } from "../components/forms/form-resolution";
 import { parsePhiFormDescriptor } from "../components/forms/form-descriptor-contract";
 import { isPhiFormId, normalizePhiFormId } from "../types/form-id";
 import { isPhiRecord } from "../helpers/is-record";
-import { throwPhiCmsGatewayError } from "./errors";
-export const PHI_FORM_DEFINITION_STATUS = {
+import { fetchPhiSiteApi } from "./site-api-request";
+const PHI_FORM_DEFINITION_STATUS = {
     workingDraft: 0,
     published: 1,
     archived: 2,
@@ -99,30 +98,15 @@ function buildResolvedDefinition(formId, records, presetDefinitions) {
         overrideDefinition,
     });
 }
-export const fetchFormRegistry = cache(async function fetchFormRegistry({ apiBaseUrl, internalToken, siteKey, }) {
-    if (!apiBaseUrl.trim()) {
-        throw new Error("Missing apiBaseUrl for fetchFormRegistry.");
-    }
-    if (!internalToken.trim()) {
-        throw new Error("Missing internalToken for fetchFormRegistry.");
-    }
-    if (!siteKey.trim()) {
-        throw new Error("Missing siteKey for fetchFormRegistry.");
-    }
-    const response = await fetch(buildApiUrl(apiBaseUrl, "/api/v1/forms/registry"), {
-        headers: buildApiHeaders({
-            token: internalToken,
-            siteKey,
-            includeToken: true,
-            includeSiteKey: true,
-            gateway: true,
-        }),
-        cache: "no-store",
-    });
-    if (!response.ok) {
-        throwPhiCmsGatewayError(`Failed to fetch form registry (${response.status}).`, response.status);
-    }
-    return normalizeRegistryResponse(await response.json().catch(() => null));
+export const fetchFormRegistry = definePhiRequestMemo(async function fetchFormRegistry({ apiBaseUrl, internalToken, siteKey, }) {
+    return normalizeRegistryResponse(await fetchPhiSiteApi({
+        context: "fetchFormRegistry",
+        apiBaseUrl,
+        internalToken,
+        siteKey,
+        path: "/api/v1/forms/registry",
+        failure: "Failed to fetch form registry",
+    }));
 });
 export async function listResolvedFormDefinitions({ apiBaseUrl, internalToken, siteKey, presetDefinitions, }) {
     const registry = await fetchFormRegistry({ apiBaseUrl, internalToken, siteKey });

package/gateway/form-submit.d.ts

@@ -1,32 +1,17 @@
 import "server-only";
 import type { PhiFormDefinitionLike } from "../components/forms/form-resolution";
 import type { PhiFormHandlerCredentialPolicy, PhiFormHandlerProviderDescriptor } from "../types/form-descriptor";
-export type PhiFormSubmitCategory = "auth" | "account" | "forms" | "site";
-export type PhiFormSubmitTransport = "relay" | "api" | "serverAction";
-export type PhiFormSubmitMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
-export type PhiFormSubmitDescriptor = {
-    formId: string;
-    submitHandlerKey: string;
-    category: PhiFormSubmitCategory;
-    transport: PhiFormSubmitTransport;
-    method: PhiFormSubmitMethod;
-    endpointKey: string | null;
-    actionKey: string | null;
-    upstreamPath: string | null;
-    csrfPath: string | null;
-    requiresCsrf: boolean;
-    credentialPolicy: PhiFormHandlerCredentialPolicy;
-};
+import type { PhiFormSubmitRoute } from "../types/form-submit-route";
 export type PhiFormPreviewDescriptor = {
     formId: string;
 };
-export type PhiFormSubmitTarget = PhiFormSubmitDescriptor & {
+export type PhiFormSubmitTarget = PhiFormSubmitRoute & {
     upstreamPath: string | null;
     csrfPath: string | null;
     requiresCsrf: boolean;
     routeTarget: string;
 };
-type PhiFormSubmitDescriptorInput = {
+type PhiFormSubmitRouteInput = {
     formId: string;
     submitHandlerKey: string;
     category?: string | null;
@@ -43,9 +28,9 @@ type PhiFormDefinitionLikeWithPreview = Pick<PhiFormDefinitionLike, "formId" | "
     config?: Record<string, unknown>;
     defaultConfig?: Record<string, unknown>;
 };
-export declare function buildPhiFormSubmitDescriptor(input: PhiFormSubmitDescriptorInput): PhiFormSubmitDescriptor;
-export declare function resolvePhiFormSubmitTarget(descriptor: PhiFormSubmitDescriptor): PhiFormSubmitTarget;
-export declare function buildPhiFormSubmitDescriptorFromHandlerProvider(formId: string, provider: PhiFormHandlerProviderDescriptor): PhiFormSubmitDescriptor;
+export declare function buildPhiFormSubmitRoute(input: PhiFormSubmitRouteInput): PhiFormSubmitRoute;
+export declare function resolvePhiFormSubmitTarget(descriptor: PhiFormSubmitRoute): PhiFormSubmitTarget;
+export declare function buildPhiFormSubmitRouteFromHandlerProvider(formId: string, provider: PhiFormHandlerProviderDescriptor): PhiFormSubmitRoute;
 export declare function buildPhiFormPreviewDescriptor(input: Pick<PhiFormPreviewDescriptor, "formId">): PhiFormPreviewDescriptor;
 export declare function buildPhiFormPreviewDescriptorFromDefinition(definition: PhiFormDefinitionLikeWithPreview): PhiFormPreviewDescriptor | null;
 export {};