@salesforce/ui-bundle-template-app-react-sample-b2e 11.55.1 → 11.56.0

package/dist/force-app/main/default/uiBundles/propertymanagementapp/src/features/search/adapters/cms/api/orgApiVersionService.ts

@@ -0,0 +1,26 @@
+/** Service to gate CMS search on the bundle's build-time API version. */
+
+import { getBuildApiVersion } from "./apiUtils";
+
+/** Minimum API version that supports CMS search. */
+export const MIN_CMS_API_VERSION = 68;
+
+/**
+ * Resolves whether CMS search can run. Gated on the bundle's build-time API
+ * version (`__SF_API_VERSION__`, injected from the resolved org's API version
+ * at build time) being >= {@link MIN_CMS_API_VERSION}.
+ *
+ * The build version is the version every SDK GraphQL/REST request is actually
+ * issued at, so it already reflects a concrete, org-supported API version: a
+ * bundle built against an org resolves that org's max version, and a bundle
+ * built below v68 sends its CMS query to `/services/data/v67.0/graphql` where
+ * the v68 CMS backend is unavailable. Gating on the build version alone is
+ * therefore both necessary and sufficient — and, unlike a runtime probe of the
+ * bare `/services/data/` version-listing endpoint (which is not routed on guest
+ * Experience Sites and would fail-close there), it works on every surface.
+ *
+ * Async to preserve the call-site contract; resolves synchronously.
+ */
+export function getOrgSupportsCmsSearch(): Promise<boolean> {
+	return Promise.resolve(getBuildApiVersion() >= MIN_CMS_API_VERSION);
+}

package/dist/force-app/main/default/uiBundles/propertymanagementapp/src/features/search/adapters/cms/api/searchableContentTypesService.ts

@@ -0,0 +1,116 @@
+/**
+ * Connect REST caller for a CMS channel's searchable content types:
+ *   GET /connect/cms/channels/{channelId}/searchable-content-types?page=N&pageSize=25
+ * Returns the validated content types (FQN + server label) that populate the
+ * content-type scope entries.
+ */
+
+import { connectGetJson, connectUrl, safeEncodePath } from "./apiUtils";
+import {
+	isValidCmsFqn,
+	formatContentTypeLabel,
+	type DiscoveredContentType,
+} from "../contentTypeUtils";
+
+/** Hard-coded REST page size. NEVER user input. */
+const REST_PAGE_SIZE = 25;
+
+/** Safety cap so a misbehaving backend cannot spin an unbounded loop. */
+const MAX_PAGES = 100;
+
+/** Channel id shape guard — `0ap` + 12–15 alphanumerics — validates the discovery channel id before the searchable-content-types REST call. */
+export const CHANNEL_ID_PATTERN = /^0ap[a-zA-Z0-9]{12,15}$/;
+
+/** One raw entry from the Connect response. */
+interface RawContentTypeEntry {
+	/** FQN with the `sfdc_cms__` prefix (e.g. "sfdc_cms__news"). */
+	id?: string;
+	/** Server-provided display name (e.g. "News"). */
+	label?: string;
+	/** Bare developer name without the prefix (e.g. "news"). */
+	name?: string;
+	// Legacy/alternate FQN field names kept as fallbacks.
+	contentType?: string;
+	fqn?: string;
+	developerName?: string;
+	isSearchable?: boolean;
+	searchable?: boolean;
+}
+
+/** Loose shape of one page of the Connect response. */
+interface RawContentTypesPage {
+	items?: RawContentTypeEntry[];
+	contentTypes?: RawContentTypeEntry[];
+}
+
+/** Reads the entries array from a page payload (array or object form). */
+function pageItems(payload: unknown): RawContentTypeEntry[] {
+	if (Array.isArray(payload)) return payload as RawContentTypeEntry[];
+	const obj = payload as RawContentTypesPage | null;
+	if (obj?.items && Array.isArray(obj.items)) return obj.items;
+	if (obj?.contentTypes && Array.isArray(obj.contentTypes)) return obj.contentTypes;
+	return [];
+}
+
+/** True when the entry is not explicitly marked non-searchable. */
+function isSearchable(entry: RawContentTypeEntry): boolean {
+	if (typeof entry.isSearchable === "boolean") return entry.isSearchable;
+	if (typeof entry.searchable === "boolean") return entry.searchable;
+	// No flag present → do not exclude on searchability (FQN validity still gates).
+	return true;
+}
+
+/**
+ * Extracts the prefixed FQN from an entry. `id` is the current field; the
+ * others are fallbacks for alternate/legacy payloads. `name` is intentionally
+ * NOT read here — it is the bare (unprefixed) developer name and would fail
+ * `isValidCmsFqn`.
+ */
+function entryFqn(entry: RawContentTypeEntry): string | undefined {
+	return entry.id ?? entry.contentType ?? entry.fqn ?? entry.developerName;
+}
+
+/**
+ * Fetches every searchable content type for `channelId`, paginating the
+ * Connect endpoint until a short page is returned, then filtering to searchable
+ * entries whose FQN passes `isValidCmsFqn`. Each result carries the FQN and the
+ * server-provided display `label` (falling back to a derived label only when
+ * the response omits one). De-duplicates by FQN, preserving first-seen order.
+ *
+ * @throws when `channelId` fails the shape guard (before any network call).
+ */
+export async function fetchSearchableContentTypes(
+	channelId: string,
+): Promise<DiscoveredContentType[]> {
+	if (!CHANNEL_ID_PATTERN.test(channelId)) {
+		throw new Error(`Invalid CMS channel id "${channelId}".`);
+	}
+
+	const encoded = safeEncodePath(channelId);
+	const collected: DiscoveredContentType[] = [];
+	const seen = new Set<string>();
+
+	for (let page = 0; page < MAX_PAGES; page++) {
+		const url = connectUrl(
+			`/cms/channels/${encoded}/searchable-content-types?page=${page}&pageSize=${REST_PAGE_SIZE}`,
+		);
+		const payload = await connectGetJson(url);
+		const items = pageItems(payload);
+
+		for (const entry of items) {
+			const fqn = entryFqn(entry);
+			if (!fqn || !isSearchable(entry) || !isValidCmsFqn(fqn) || seen.has(fqn)) {
+				continue;
+			}
+			seen.add(fqn);
+			// Prefer the server label; fall back to a label derived from the FQN.
+			const label = entry.label?.trim() || formatContentTypeLabel(fqn);
+			collected.push({ fqn, label });
+		}
+
+		// Last page reached when fewer than a full page came back.
+		if (items.length < REST_PAGE_SIZE) break;
+	}
+
+	return collected;
+}

package/dist/force-app/main/default/uiBundles/propertymanagementapp/src/features/search/adapters/cms/channelResolver.ts

@@ -0,0 +1,40 @@
+/**
+ * Extracts the CMS channel id from a search result so it can feed the
+ * searchable-content-types Connect endpoint. There is one CMS channel for the
+ * app, so any result carries it:
+ *
+ *   nodes[0].managedContentChannelDeliveryDetails[0].managedContentChannelDetails.id
+ *
+ * Returns `null` when any hop is missing (empty nodes, missing delivery
+ * details, missing channel details / id) — the caller simply skips discovery.
+ */
+
+import type { SourceResult } from "../../types";
+import type { CmsSearchResponse, CmsSearchItem } from "./types";
+
+/** Accepts either a normalised `SourceResult` or a raw `CmsSearchResponse`. */
+type ChannelSource = SourceResult | CmsSearchResponse | null | undefined;
+
+function getNodes(result: ChannelSource): unknown[] {
+	if (!result) return [];
+	// SourceResult carries `nodes`; CmsSearchResponse carries `items`.
+	if ("nodes" in result && Array.isArray(result.nodes)) return result.nodes;
+	if ("items" in result && Array.isArray(result.items)) return result.items;
+	return [];
+}
+
+/**
+ * Returns the channel id derived from the first result's delivery details, or
+ * `null` when any level is absent. Validate the returned id's shape before it
+ * enters a REST path (the discovery service does this).
+ */
+export function resolveChannelId(result: ChannelSource): string | null {
+	const nodes = getNodes(result);
+	const first = nodes[0] as Partial<CmsSearchItem> | undefined;
+	if (!first) return null;
+
+	const delivery = first.managedContentChannelDeliveryDetails?.[0];
+	const id = delivery?.managedContentChannelDetails?.id;
+
+	return typeof id === "string" && id.length > 0 ? id : null;
+}

package/dist/force-app/main/default/uiBundles/propertymanagementapp/src/features/search/adapters/cms/cmsQueryFragment.ts

@@ -0,0 +1,97 @@
+/**
+ * Builds the CMS `managed_content { search { searchContentInChannels … } }`
+ * fragment as a {@link QueryFragmentContribution} with `placement: "root"` — a
+ * sibling of the `uiapi` block in the combined document.
+ *
+ * The `$cmsContentTypeFQNs` declaration, its `contentTypeFQNs:` argument, and
+ * its variable value are all emitted only when a non-empty content-type list is
+ * passed; on the bootstrap call (no types known) they are omitted entirely.
+ */
+
+import type { QueryFragmentContribution } from "../types";
+
+export interface BuildCmsFragmentParams {
+	/** Search keyword → `$cmsKeyword`. */
+	keyword: string;
+	/** UIBundle Id fed into the query → `$UIBundleId` (from `getUIBundleId()`). */
+	uiBundleId: string;
+	/** Pagination offset → `$cmsOffset` (already clamped `>= 0` by the caller). */
+	offset: number;
+	/** Page size → `$cmsLimit` (validated against `pageSizeOptions` upstream). */
+	limit: number;
+	/**
+	 * Discovered/selected content-type FQNs → the schema's `contentTypeFQNs`
+	 * argument (via `$cmsContentTypeFQNs`). When absent, null, or empty, those
+	 * pieces are omitted entirely (bootstrap call). Callers pass ONLY
+	 * `isValidCmsFqn`-validated values.
+	 */
+	contentTypes?: string[] | null;
+}
+
+/**
+ * Builds the CMS fragment contribution. The content-type filter pieces are
+ * included only when `params.contentTypes` is a non-empty array.
+ */
+export function buildCmsQueryFragment(params: BuildCmsFragmentParams): QueryFragmentContribution {
+	const { keyword, uiBundleId, offset, limit, contentTypes } = params;
+
+	const hasContentTypes = Array.isArray(contentTypes) && contentTypes.length > 0;
+
+	const variableDeclarations = [
+		"$cmsKeyword: String!",
+		"$UIBundleId: ID!",
+		"$cmsOffset: Int!",
+		"$cmsLimit: Int!",
+	];
+
+	const variables: Record<string, unknown> = {
+		cmsKeyword: keyword,
+		UIBundleId: uiBundleId,
+		cmsOffset: offset,
+		cmsLimit: limit,
+	};
+
+	// CONDITIONAL: declare + pass + supply the content-type filter only when a
+	// non-empty list is provided. Otherwise these three pieces are all absent.
+	// The schema argument is `contentTypeFQNs` (a list of content-type FQNs) —
+	// NOT `contentTypes`; the latter is rejected as an unknown field argument.
+	const contentTypesArg = hasContentTypes ? "\n          contentTypeFQNs: $cmsContentTypeFQNs" : "";
+	if (hasContentTypes) {
+		variableDeclarations.push("$cmsContentTypeFQNs: [String!]");
+		variables.cmsContentTypeFQNs = contentTypes;
+	}
+
+	const fragment = `managed_content {
+  search {
+    searchContentInChannels(
+      searchIdentifiers: { uibundleIds: [$UIBundleId] }
+      keyword: $cmsKeyword
+      pagination: { limit: $cmsLimit, offset: $cmsOffset }${contentTypesArg}
+    ) {
+      total
+      offset
+      pageSize
+      items {
+        managedContentId
+        managedContentKey
+        title
+        contentType
+        language
+        highlightedSnippet
+        managedContentChannelDeliveryDetails {
+          contentUrl
+          publishedDate
+          managedContentChannelDetails { id name type }
+        }
+      }
+    }
+  }
+}`;
+
+	return {
+		variableDeclarations,
+		variables,
+		placement: "root",
+		fragment,
+	};
+}

package/dist/force-app/main/default/uiBundles/propertymanagementapp/src/features/search/adapters/cms/contentTypeSessionCache.ts

@@ -0,0 +1,134 @@
+/**
+ * `sessionStorage`-backed persistence for discovered CMS content types.
+ *
+ * Discovery is otherwise ephemeral: the in-memory module cache in
+ * {@link useSearchableContentTypes} is wiped on a hard reload, and content
+ * types are only re-derived once a CMS search actually returns a channel id.
+ * Persisting them per channel lets the scope dropdown keep showing the
+ * discovered types across any number of reloads, and lets the discovery hook
+ * rehydrate them synchronously (no re-fetch) on mount.
+ *
+ * Two things are persisted:
+ *   - `types:<channelId>`           — the validated `{ fqn, label }[]` for that
+ *     channel. Keyed by the channel id, which is channel-specific already.
+ *   - `last-channel-id:<uiBundleId>` — the most recently discovered channel id
+ *     FOR THAT UIBundle, so the hook can seed its discovery state on mount
+ *     before any CMS result arrives. Keyed by UIBundle id (not origin-wide):
+ *     content types are channel-specific, so a second UIBundle opened in the
+ *     same session must NOT inherit the first bundle's channel/types.
+ *
+ * Every access is wrapped: `sessionStorage` can be absent (SSR), throw
+ * (private-mode / disabled cookies), or hold corrupt JSON. On any failure we
+ * degrade to "no cache" rather than surfacing an error — persistence is an
+ * enhancement, never a hard dependency.
+ */
+
+import { isValidCmsFqn, type DiscoveredContentType } from "./contentTypeUtils";
+import { CHANNEL_ID_PATTERN } from "./api/searchableContentTypesService";
+import { UI_BUNDLE_ID_PATTERN } from "./searchChannel";
+
+const KEY_PREFIX = "cms-search:content-types:";
+const TYPES_KEY = (channelId: string) => `${KEY_PREFIX}types:${channelId}`;
+const LAST_CHANNEL_KEY = (uiBundleId: string) => `${KEY_PREFIX}last-channel-id:${uiBundleId}`;
+
+/** Returns the `sessionStorage` object, or `null` when it is unavailable/throws. */
+function storage(): Storage | null {
+	try {
+		if (typeof sessionStorage === "undefined") return null;
+		return sessionStorage;
+	} catch {
+		// Accessing `sessionStorage` can throw when storage is disabled.
+		return null;
+	}
+}
+
+/** Narrows an unknown parsed value to a clean `DiscoveredContentType[]`. */
+function sanitize(parsed: unknown): DiscoveredContentType[] {
+	if (!Array.isArray(parsed)) return [];
+	const out: DiscoveredContentType[] = [];
+	const seen = new Set<string>();
+	for (const entry of parsed) {
+		if (!entry || typeof entry !== "object") continue;
+		const { fqn, label } = entry as { fqn?: unknown; label?: unknown };
+		// Re-validate the FQN on read: cached data is untrusted input and its
+		// values flow straight into the query variable and rendered labels.
+		if (typeof fqn !== "string" || !isValidCmsFqn(fqn) || seen.has(fqn)) continue;
+		if (typeof label !== "string" || label.length === 0) continue;
+		seen.add(fqn);
+		out.push({ fqn, label });
+	}
+	return out;
+}
+
+/**
+ * Reads the persisted content types for `channelId`. Returns `null` when there
+ * is no (valid) cache entry, so callers can distinguish "never persisted" from
+ * "persisted as empty".
+ */
+export function readCachedContentTypes(channelId: string): DiscoveredContentType[] | null {
+	const store = storage();
+	if (!store || !CHANNEL_ID_PATTERN.test(channelId)) return null;
+	let raw: string | null;
+	try {
+		raw = store.getItem(TYPES_KEY(channelId));
+	} catch {
+		return null;
+	}
+	if (raw == null) return null;
+	try {
+		return sanitize(JSON.parse(raw));
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Persists `types` for `channelId`. No-ops (never throws) when storage is
+ * unavailable or the id is malformed. The last-discovered-channel pointer is
+ * written separately via {@link writeLastChannelId}, which needs the UIBundle
+ * id this channel belongs to.
+ */
+export function writeCachedContentTypes(channelId: string, types: DiscoveredContentType[]): void {
+	const store = storage();
+	if (!store || !CHANNEL_ID_PATTERN.test(channelId)) return;
+	try {
+		store.setItem(TYPES_KEY(channelId), JSON.stringify(types));
+	} catch {
+		// Quota exceeded / disabled storage — persistence is best-effort.
+	}
+}
+
+/**
+ * Records `channelId` as the last discovered channel FOR `uiBundleId`. Keyed by
+ * UIBundle id so a different bundle opened in the same session never inherits
+ * this channel. No-ops (never throws) when storage is unavailable or either id
+ * is malformed.
+ */
+export function writeLastChannelId(uiBundleId: string, channelId: string): void {
+	const store = storage();
+	if (!store || !UI_BUNDLE_ID_PATTERN.test(uiBundleId) || !CHANNEL_ID_PATTERN.test(channelId)) {
+		return;
+	}
+	try {
+		store.setItem(LAST_CHANNEL_KEY(uiBundleId), channelId);
+	} catch {
+		// Quota exceeded / disabled storage — persistence is best-effort.
+	}
+}
+
+/**
+ * Returns the last discovered channel id for `uiBundleId` (validated shape), or
+ * `null`. Lets the discovery hook seed its channel on mount so THIS bundle's
+ * cached types render immediately, before any CMS search result comes back.
+ */
+export function readLastChannelId(uiBundleId: string): string | null {
+	const store = storage();
+	if (!store || !UI_BUNDLE_ID_PATTERN.test(uiBundleId)) return null;
+	let raw: string | null;
+	try {
+		raw = store.getItem(LAST_CHANNEL_KEY(uiBundleId));
+	} catch {
+		return null;
+	}
+	return raw != null && CHANNEL_ID_PATTERN.test(raw) ? raw : null;
+}

package/dist/force-app/main/default/uiBundles/propertymanagementapp/src/features/search/adapters/cms/contentTypeUtils.ts

@@ -0,0 +1,38 @@
+/**
+ * CMS content-type FQN helpers.
+ *
+ * `isValidCmsFqn` / `CMS_FQN_PATTERN` guard every FQN before it enters query
+ * state, the GraphQL variable, or a rendered label. `formatContentTypeLabel`
+ * turns an FQN into a human-readable dropdown/section label.
+ */
+
+/**
+ * Formats a CMS content type FQN into a human-readable label.
+ * Strips "sfdc_cms__" prefix, splits camelCase, title-cases each word.
+ *
+ * Examples:
+ *   "sfdc_cms__blogPost" → "Blog Post"
+ *   "sfdc_cms__news" → "News"
+ *   "sfdc_cms__document" → "Document"
+ *   "sfdc_cms__pressRelease" → "Press Release"
+ */
+export function formatContentTypeLabel(fqn: string): string {
+	const stripped = fqn.replace(/^sfdc_cms__/, "");
+	const words = stripped.replace(/([a-z])([A-Z])/g, "$1 $2");
+	return words.charAt(0).toUpperCase() + words.slice(1);
+}
+
+export const CMS_FQN_PATTERN = /^sfdc_cms__[a-zA-Z][a-zA-Z0-9]{0,39}$/;
+
+export function isValidCmsFqn(fqn: string): boolean {
+	return CMS_FQN_PATTERN.test(fqn);
+}
+
+/**
+ * A discovered CMS content type: its FQN (`sfdc_cms__…`, used as the scope value
+ * and query filter) and its server-provided display `label` (e.g. "News").
+ */
+export interface DiscoveredContentType {
+	fqn: string;
+	label: string;
+}

package/dist/force-app/main/default/uiBundles/propertymanagementapp/src/features/search/adapters/cms/hooks/useSearchableContentTypes.ts

@@ -0,0 +1,128 @@
+/**
+ * Session-cache hook for a CMS channel's searchable content types.
+ *
+ * A module-level `Map` cache + a `Map` of in-flight promises, keyed by
+ * `channelId`, so the Connect endpoint is hit once per channel per session and
+ * concurrent callers share one request. A `null` channelId short-circuits (no
+ * fetch) — discovery only runs after a CMS result yields a channel id.
+ */
+
+import { useState, useEffect, useRef } from "react";
+import { fetchSearchableContentTypes } from "../api/searchableContentTypesService";
+import type { DiscoveredContentType } from "../contentTypeUtils";
+import { readCachedContentTypes, writeCachedContentTypes } from "../contentTypeSessionCache";
+
+/** Session cache: channelId → discovered content types. Populated once, reused after. */
+const cache = new Map<string, DiscoveredContentType[]>();
+/** In-flight dedupe: channelId → the pending fetch promise. */
+const inflight = new Map<string, Promise<DiscoveredContentType[]>>();
+
+/**
+ * Returns any already-known content types for `channelId` WITHOUT fetching:
+ * the in-memory module cache first, then the `sessionStorage` cache (which
+ * survives a hard reload). The `sessionStorage` hit is promoted into the module
+ * cache so subsequent lookups stay in memory. Returns `null` when neither holds
+ * the channel, so callers know a network fetch is still required.
+ */
+function peekCachedContentTypes(channelId: string): DiscoveredContentType[] | null {
+	const inMemory = cache.get(channelId);
+	if (inMemory) return inMemory;
+	const persisted = readCachedContentTypes(channelId);
+	if (persisted) {
+		cache.set(channelId, persisted);
+		return persisted;
+	}
+	return null;
+}
+
+/**
+ * Fetches (once per session) and caches the searchable content types for a
+ * channel. Concurrent callers for the same channel share one request. Results
+ * are cached in memory AND persisted to `sessionStorage` so a hard reload can
+ * rehydrate them without a re-fetch.
+ */
+export function getSearchableContentTypes(channelId: string): Promise<DiscoveredContentType[]> {
+	const cached = peekCachedContentTypes(channelId);
+	if (cached) return Promise.resolve(cached);
+
+	const pending = inflight.get(channelId);
+	if (pending) return pending;
+
+	const promise = (async () => {
+		try {
+			const result = await fetchSearchableContentTypes(channelId);
+			cache.set(channelId, result);
+			// Persist so the scope dropdown keeps the types across hard reloads.
+			writeCachedContentTypes(channelId, result);
+			return result;
+		} finally {
+			inflight.delete(channelId);
+		}
+	})();
+	inflight.set(channelId, promise);
+	return promise;
+}
+
+export interface UseSearchableContentTypesResult {
+	/** Discovered, validated content types (FQN + label; empty until resolved). */
+	contentTypes: DiscoveredContentType[];
+	loading: boolean;
+	error: string | null;
+}
+
+/**
+ * React hook wrapping {@link getSearchableContentTypes}. Re-runs only when the
+ * `channelId` string changes; a `null` id yields an empty, non-loading state.
+ */
+export function useSearchableContentTypes(
+	channelId: string | null,
+): UseSearchableContentTypesResult {
+	// Seed synchronously from the in-memory OR sessionStorage cache so a hard
+	// reload shows the persisted content types on the first render (before any
+	// CMS search result comes back), with no fetch and no loading flash.
+	const [state, setState] = useState<UseSearchableContentTypesResult>(() => {
+		const seeded = channelId ? peekCachedContentTypes(channelId) : null;
+		return {
+			contentTypes: seeded ?? [],
+			loading: channelId != null && seeded == null,
+			error: null,
+		};
+	});
+	const isCancelled = useRef(false);
+
+	useEffect(() => {
+		isCancelled.current = false;
+
+		if (channelId == null) {
+			setState({ contentTypes: [], loading: false, error: null });
+			return;
+		}
+
+		const cached = peekCachedContentTypes(channelId);
+		if (cached) {
+			setState({ contentTypes: cached, loading: false, error: null });
+			return;
+		}
+
+		setState((s) => ({ ...s, loading: true, error: null }));
+		getSearchableContentTypes(channelId)
+			.then((contentTypes) => {
+				if (isCancelled.current) return;
+				setState({ contentTypes, loading: false, error: null });
+			})
+			.catch((err) => {
+				if (isCancelled.current) return;
+				setState({
+					contentTypes: [],
+					loading: false,
+					error: err instanceof Error ? err.message : String(err),
+				});
+			});
+
+		return () => {
+			isCancelled.current = true;
+		};
+	}, [channelId]);
+
+	return state;
+}

package/dist/force-app/main/default/uiBundles/propertymanagementapp/src/features/search/adapters/cms/index.ts

@@ -0,0 +1,54 @@
+/**
+ * CMS adapter — fronts the `managed_content` GraphQL block behind the
+ * kind-agnostic {@link SourceAdapter} contract.
+ *
+ * `buildRequest` is SYNCHRONOUS (the query builder is sync): it reads the
+ * already-resolved `request.uiBundleId` (the caller resolves the async
+ * `getUIBundleId()` upstream and threads it in), decodes `afterCursor` → offset,
+ * and passes `request.contentTypes` through to the fragment builder ONLY when
+ * non-empty (bootstrap omits them). `parseResponse` delegates to the CMS parser.
+ *
+ * The registry (`../registry.ts`) imports `cmsAdapter` from here by name.
+ */
+
+import type { CmsSourceConfig } from "./types";
+import type { SourceAdapter, SourceRequest, QueryFragmentContribution } from "../types";
+import { buildCmsQueryFragment } from "./cmsQueryFragment";
+import { parseCmsResponse } from "./parseResponse";
+import { isValidCmsFqn } from "./contentTypeUtils";
+
+/** Decodes an opaque forward cursor into a non-negative integer offset. */
+function decodeOffset(afterCursor: string | undefined): number {
+	if (afterCursor == null) return 0;
+	const parsed = parseInt(afterCursor, 10);
+	if (!Number.isFinite(parsed) || parsed < 0) return 0;
+	return parsed;
+}
+
+/**
+ * Builds the CMS fragment contribution from a request. Content types are passed
+ * through only when non-empty AND every entry is a valid FQN (defence in depth —
+ * `useSearch` already validates before state).
+ */
+function buildCmsRequest(request: SourceRequest<CmsSourceConfig>): QueryFragmentContribution {
+	const offset = decodeOffset(request.afterCursor);
+
+	const contentTypes =
+		Array.isArray(request.contentTypes) && request.contentTypes.length > 0
+			? request.contentTypes.filter(isValidCmsFqn)
+			: null;
+
+	return buildCmsQueryFragment({
+		keyword: request.q,
+		uiBundleId: request.uiBundleId ?? "",
+		offset,
+		limit: request.pageSize,
+		contentTypes: contentTypes && contentTypes.length > 0 ? contentTypes : null,
+	});
+}
+
+export const cmsAdapter: SourceAdapter<CmsSourceConfig> = {
+	kind: "cms",
+	buildRequest: buildCmsRequest,
+	parseResponse: parseCmsResponse,
+};