camox 0.44.0 → 0.45.0

package/dist/features/routes/pageRuntime.d.ts

@@ -1,10 +1,50 @@
-import { QueryClient } from "@tanstack/react-query";
+import "../../core/createLayout.js";
+import "../../core/createApp.js";
+import { LocaleView } from "../../lib/locale-path.js";
+import "../../lib/studio-reads.js";
 import { Router } from "@camox/api-contract";
+import { EndedDraft } from "@camox/api-contract/drafts";
+import { QueryClient } from "@tanstack/react-query";
 import { RouterClient } from "@orpc/server";
-
 //#region src/features/routes/pageRuntime.d.ts
-declare function createServerApiClient(apiUrl: string, environmentName?: string, options?: {
+type PageWithBlocks = Awaited<ReturnType<RouterClient<Router>["pages"]["getByPath"]>>;
+export type MemberProject = Awaited<ReturnType<RouterClient<Router>["projects"]["getByUuid"]>>;
+export type PageStructure = {
+  page: PageWithBlocks["page"];
+  layout: PageWithBlocks["layout"];
+  projectName: string;
+  project: PageWithBlocks["project"];
+};
+/**
+ * Why a member can't see the draft a URL names: it doesn't exist, it's someone else's
+ * development draft, or it was published or discarded (ADR 0011). In dev mode, the caller's
+ * own development draft doesn't exist until the dev server's first sync creates it.
+ */
+export type DraftNotice = {
+  reason: "missing";
+} | {
+  reason: "noDevelopmentDraft";
+} | {
+  reason: "forbidden";
+} | ({
+  reason: "ended";
+} & EndedDraft);
+/** Which draft a render read: the URL's, or Live when there was none or it couldn't be read. */
+export interface DraftRead {
+  /** The draft the render read. Absent for Live. */
+  draftId?: string;
+  /**
+   * Present when the URL named a draft the render couldn't read, so it read Live instead. Only a
+   * member gets a notice explaining why; anyone else sees Live as if the URL named no draft.
+   */
+  refusedDraft?: {
+    notice: DraftNotice | null;
+  };
+}
+export declare function createServerApiClient(apiUrl: string, options?: {
   authCookieHeader?: string;
+  draftId?: string;
+  locale?: LocaleView;
 }): RouterClient<Router>;
 //#endregion
-export { createServerApiClient };
+export {};

package/dist/features/routes/pageRuntime.js

@@ -1,4 +1,8 @@
-import { queryKeys } from "@camox/api-contract/query-keys";
+import { localeHeaders, localizedPath } from "../../lib/locale-path.js";
+import { createDraftScope, withoutDraft } from "../../lib/draft-scope.js";
+import { createStudioCache, reads } from "../../lib/studio-reads.js";
+import { linkFallbackLocale } from "../../lib/link-pages.js";
+import { DRAFT_ENDED_ERROR_CODE, DRAFT_HEADER, NO_DEVELOPMENT_DRAFT_ERROR } from "@camox/api-contract/drafts";
 import { createORPCClient } from "@orpc/client";
 import { RPCLink } from "@orpc/client/fetch";
 
@@ -17,9 +21,20 @@ function prefersMarkdown(accept) {
 	}
 	return markdownQ > 0 && markdownQ >= htmlQ;
 }
-function createServerApiClient(apiUrl, environmentName, options) {
-	const headers = {};
-	if (environmentName) headers["x-environment-name"] = environmentName;
+/** Where a page's Markdown Representation lives: `/index.md` for the home page, `<path>.md` otherwise. */
+function getMarkdownPath(pageFullPath) {
+	const path = pageFullPath.replace(/\/+$/, "");
+	return path ? `${path}.md` : "/index.md";
+}
+/** The page path a Markdown URL represents, or null when the URL isn't one. */
+function parseMarkdownPath(pathname) {
+	if (!pathname.endsWith(".md")) return null;
+	if (pathname === "/index.md") return "/";
+	return pathname.slice(0, -3) || null;
+}
+function createServerApiClient(apiUrl, options) {
+	const headers = localeHeaders(options?.locale);
+	if (options?.draftId && options.authCookieHeader) headers[DRAFT_HEADER] = options.draftId;
 	return createORPCClient(new RPCLink({
 		url: `${apiUrl}/rpc`,
 		headers,
@@ -49,163 +64,235 @@ function isNotFoundError(error) {
 	const { code, status } = getErrorDetails(error);
 	return code === "NOT_FOUND" || status === 404;
 }
-function visitForFileIds(value, ids) {
-	if (value == null || typeof value !== "object") return;
-	if ("_fileId" in value && typeof value._fileId === "number") {
-		ids.add(value._fileId);
-		return;
-	}
-	if (Array.isArray(value)) {
-		for (const item of value) visitForFileIds(item, ids);
-		return;
-	}
-	for (const child of Object.values(value)) visitForFileIds(child, ids);
-}
-function collectFileIdsFromContent(content, ids) {
-	for (const value of Object.values(content)) visitForFileIds(value, ids);
-}
-function seedBlockCaches(queryClient, pageData, source = "draft") {
-	const filesById = new Map(pageData.files.map((f) => [f.id, f]));
-	for (const block of pageData.blocks) {
-		const blockItems = pageData.repeatableItems.filter((i) => i.blockId === block.id);
-		const fileIds = /* @__PURE__ */ new Set();
-		collectFileIdsFromContent(block.content, fileIds);
-		for (const item of blockItems) collectFileIdsFromContent(item.content, fileIds);
-		const blockFiles = [...fileIds].map((id) => filesById.get(id)).filter((f) => f != null);
-		queryClient.setQueryData(queryKeys.blocks.get(block.id, source), {
-			block,
-			repeatableItems: blockItems,
-			files: blockFiles
-		});
-		for (const file of blockFiles) queryClient.setQueryData(queryKeys.files.get(file.id), file);
+/**
+* The notice for an API error refusing the draft a member named, or undefined when the error
+* isn't about the draft.
+*/
+function draftRefusalNotice(error, draftId) {
+	const { code, status } = getErrorDetails(error);
+	const data = error?.data;
+	if (code === DRAFT_ENDED_ERROR_CODE && data) return {
+		reason: "ended",
+		...data
+	};
+	if (code === NO_DEVELOPMENT_DRAFT_ERROR) return { reason: "noDevelopmentDraft" };
+	if (isNotFoundError(error) && data?.draftId === draftId) return { reason: "missing" };
+	if (code === "FORBIDDEN" || status === 403) return { reason: "forbidden" };
+	if (code === "UNAUTHORIZED" || status === 401) return null;
+}
+/**
+* Reads with the draft a URL names, or Live (ADR 0011). Only a member's request names the draft;
+* anyone else reads Live. When the API refuses the draft, the same response reads Live instead.
+*/
+async function readDraftOrLive(draftId, member, read) {
+	if (!draftId) return { value: await read(void 0) };
+	if (!member) return {
+		value: await read(void 0),
+		refusedDraft: { notice: null }
+	};
+	try {
+		return {
+			value: await read(draftId),
+			draftId
+		};
+	} catch (error) {
+		const notice = draftRefusalNotice(error, draftId);
+		if (notice === void 0) throw error;
+		return {
+			value: await read(void 0),
+			refusedDraft: { notice }
+		};
 	}
 }
-async function loadCamoxPage({ apiUrl, authCookieHeader, environmentName, pathname, projectSlug, queryClient, source }) {
-	const serverApi = createServerApiClient(apiUrl, environmentName, { authCookieHeader });
-	return queryClient.ensureQueryData({
-		queryKey: queryKeys.pages.getByPath(pathname, source),
-		queryFn: async () => {
-			const [data, pagesList] = await Promise.all([serverApi.pages.getByPath({
-				path: pathname,
-				projectSlug,
-				source
-			}), serverApi.pages.listBySlug({ projectSlug }).catch(() => null)]);
-			seedBlockCaches(queryClient, data, source);
-			queryClient.setQueryData(queryKeys.pages.getByPath(pathname, source), {
-				page: data.page,
-				layout: data.layout,
-				projectName: data.projectName,
-				project: data.project
-			});
-			if (source === "live") {
-				seedBlockCaches(queryClient, data, "draft");
-				queryClient.setQueryData(queryKeys.pages.getByPath(pathname, "draft"), {
-					page: data.page,
-					layout: data.layout,
-					projectName: data.projectName,
-					project: data.project
-				});
-			}
-			if (pagesList) queryClient.setQueryData(queryKeys.pages.list, pagesList);
-			return {
-				page: data.page,
-				layout: data.layout,
-				projectName: data.projectName,
-				project: data.project
-			};
-		},
-		staleTime: Infinity
+/** The URL a render shows: without the draft param when the draft couldn't be read. */
+function renderedHref(url, read) {
+	return read.refusedDraft ? withoutDraft(url) : url;
+}
+async function loadCamoxPage({ apiUrl, authCookieHeader, draftId, locale, pathname, projectUuid, queryClient }) {
+	const studioCache = createServerStudioCache(queryClient, {
+		apiUrl,
+		authCookieHeader,
+		locale
 	});
+	const inDraft = { in: draftId && authCookieHeader ? draftId : null };
+	const fallback = locale && linkFallbackLocale(locale);
+	const [page] = await Promise.all([
+		studioCache.ensure(reads.pageStructure({
+			path: pathname,
+			projectUuid
+		}), inDraft),
+		studioCache.ensure(reads.pageList({ projectUuid }), inDraft).catch(() => null),
+		fallback && studioCache.ensure(reads.pageList({ projectUuid }), {
+			...inDraft,
+			locale: fallback
+		}).catch(() => null)
+	]);
+	return page;
 }
-async function loadLivePage(options) {
-	return loadCamoxPage({
-		...options,
-		source: "live"
+/**
+* The studio's reads for one server request, read with its session. Each operation names the
+* draft it acts in, once the request settled which one it reads.
+*/
+function createServerStudioCache(queryClient, { apiUrl, authCookieHeader, locale }) {
+	return createStudioCache({
+		queryClient,
+		scope: createDraftScope({ queryClient }),
+		api: (draft, inLocale) => createServerApiClient(apiUrl, {
+			authCookieHeader,
+			draftId: draft ?? void 0,
+			locale: inLocale
+		}),
+		...locale && { locale: () => locale }
 	});
 }
+/**
+* The locales of the scope a request reads: the URL's draft's for a session naming one, else
+* Live's. A draft the API refuses reads Live's, as the request's other reads then do.
+*/
+async function readScopeLocales({ apiUrl, authCookieHeader, draftId, projectUuid }) {
+	const { value } = await readDraftOrLive(draftId, !!authCookieHeader, (readDraftId) => createServerApiClient(apiUrl, {
+		authCookieHeader: readDraftId ? authCookieHeader : void 0,
+		draftId: readDraftId
+	}).locales.list({ projectUuid }));
+	return value;
+}
+/**
+* The project, when the auth cookie is a valid session of one of its members. A successful
+* protected project lookup validates both session and project access: cookie presence alone
+* is not proof of authentication. An invalid session asks for the cookie to be cleared.
+*/
+async function resolveMemberProject({ apiUrl, authCookieHeader, projectUuid }) {
+	if (!authCookieHeader) return { clearAuthCookie: false };
+	try {
+		return {
+			project: await createServerApiClient(apiUrl, { authCookieHeader }).projects.getByUuid({ projectUuid }),
+			clearAuthCookie: false
+		};
+	} catch (error) {
+		if (!isAuthSessionError(error)) throw error;
+		return { clearAuthCookie: true };
+	}
+}
+/**
+* The project's favicon, which falls back to the Camox mark when none was uploaded. Pass
+* `placeholder: false` to get a 404 instead, to learn whether there is one.
+*/
+function buildFaviconUrl(apiUrl, project, { placeholder = true } = {}) {
+	const url = `${apiUrl}/favicons/${project.id}?v=${project.updatedAt}`;
+	return placeholder ? `${url}&placeholder=camox` : url;
+}
+/** The Camox mark a project without a favicon shows. */
+function buildFaviconPlaceholderUrl(apiUrl) {
+	return `${apiUrl}/favicons/placeholder`;
+}
 function buildCamoxPageLoaderData(apiUrl, page, origin) {
 	return {
 		page,
 		origin,
-		faviconUrl: `${apiUrl}/favicons/${page.project.id}?v=${page.project.updatedAt}`
+		faviconUrl: buildFaviconUrl(apiUrl, page.project)
 	};
 }
-async function loadCamoxPageForRequest({ apiUrl, authCookieHeader, environmentName, origin, pathname, projectSlug, queryClient }) {
-	const loadOptions = {
+async function loadCamoxPageForRequest({ apiUrl, authCookieHeader, draftId, locale, origin, pathname, projectUuid, queryClient }) {
+	const member = await resolveMemberProject({
 		apiUrl,
-		environmentName,
+		authCookieHeader,
+		projectUuid
+	});
+	if (member.clearAuthCookie) console.warn("[camox] Ignoring stale camox_auth_cookie.");
+	const { value: page, ...read } = await readDraftOrLive(draftId, !!member.project, (readDraftId) => loadCamoxPage({
+		apiUrl,
+		authCookieHeader: member.project ? authCookieHeader : void 0,
+		draftId: readDraftId,
+		locale,
 		pathname,
-		projectSlug,
+		projectUuid,
 		queryClient
+	}));
+	return {
+		...read,
+		data: buildCamoxPageLoaderData(apiUrl, page, origin),
+		project: member.project,
+		shouldClearAuthCookie: member.clearAuthCookie
 	};
-	if (!authCookieHeader) return {
-		data: buildCamoxPageLoaderData(apiUrl, await loadLivePage(loadOptions), origin),
-		shouldClearAuthCookie: false,
-		source: "live"
-	};
-	try {
-		return {
-			data: buildCamoxPageLoaderData(apiUrl, await loadCamoxPage({
-				...loadOptions,
-				authCookieHeader,
-				source: "draft"
-			}), origin),
-			shouldClearAuthCookie: false,
-			source: "draft"
-		};
-	} catch (error) {
-		if (!isAuthSessionError(error)) throw error;
-		console.warn("[camox] Ignoring stale camox_auth_cookie and retrying published page load.");
-		return {
-			data: buildCamoxPageLoaderData(apiUrl, await loadLivePage(loadOptions), origin),
-			shouldClearAuthCookie: true,
-			source: "live"
-		};
-	}
 }
-async function createMarkdownResponse({ apiUrl, environmentName, pathname, projectSlug, request }) {
-	if (!prefersMarkdown(request.headers.get("Accept") ?? "")) return null;
-	const api = createServerApiClient(apiUrl, environmentName);
+async function createMarkdownResponse({ apiUrl, camoxApp, locale, pathname, projectUuid, request, url, onNotFound }) {
+	const api = createServerApiClient(apiUrl, { locale });
 	const requestPathname = pathname ?? new URL(request.url).pathname;
 	try {
 		const page = await api.pages.getByPath({
 			path: requestPathname,
-			projectSlug,
-			source: "live"
+			projectUuid
 		});
 		const { markdown } = await api.blocks.getPageMarkdown({ pageId: page.page.id });
 		if (!markdown) return null;
-		return new Response(markdown, { headers: { "Content-Type": "text/markdown; charset=utf-8" } });
-	} catch {
+		const meta = buildPageMeta(curatedPageMetaInput(camoxApp, page, locale));
+		return new Response(withFrontMatter(markdown, {
+			...meta,
+			url
+		}), { headers: { "Content-Type": "text/markdown; charset=utf-8" } });
+	} catch (error) {
+		if (onNotFound && isNotFoundError(error)) return onNotFound();
 		return null;
 	}
 }
-function buildCamoxPageHead(camoxApp, loaderData) {
-	if (!loaderData) return {};
-	const { page, origin, faviconUrl } = loaderData;
-	const pageMetaTitle = page.page.metaTitle ?? page.page.pathSegment;
-	const meta = [];
-	let title = pageMetaTitle;
-	if (page.layout) {
-		const layout = camoxApp.getLayoutById(page.layout.layoutId);
-		if (layout) title = layout._internal.buildMetaTitle({
-			pageMetaTitle,
-			projectName: page.projectName,
-			pageFullPath: page.page.fullPath
-		});
-	}
-	meta.push({ title });
-	if (page.page.metaDescription) meta.push({
+/** A page's title and description, built by its layout's callbacks. */
+function buildPageMeta(input) {
+	const context = {
+		data: input.data,
+		...input.item && { item: input.item },
+		params: input.params,
+		projectName: input.projectName,
+		pageFullPath: input.pageFullPath
+	};
+	const title = input.layout?.buildMetaTitle({
+		...context,
+		pageMetaTitle: input.pageMetaTitle
+	}) ?? input.pageMetaTitle;
+	const description = input.layout?.buildMetaDescription ? input.layout.buildMetaDescription({
+		...context,
+		pageMetaDescription: input.pageMetaDescription
+	}) : input.pageMetaDescription;
+	return {
+		title,
+		...description && { description }
+	};
+}
+/** A curated page's meta input: its editor metadata and its layout. */
+/** A curated page's meta input. Its path keeps the prefix of the page's `locale`. */
+function curatedPageMetaInput(camoxApp, page, locale) {
+	return {
+		layout: page.layout ? camoxApp?.getLayoutById(page.layout.layoutId)?._internal : void 0,
+		pageMetaTitle: page.page.metaTitle ?? page.page.pathSegment,
+		pageMetaDescription: page.page.metaDescription ?? void 0,
+		data: void 0,
+		params: {},
+		projectName: page.projectName,
+		pageFullPath: locale ? localizedPath(page.page.fullPath, locale) : page.page.fullPath
+	};
+}
+/** A Markdown Representation, opened by YAML front matter stating the page's title, description and URL. */
+function withFrontMatter(markdown, meta) {
+	return `---\n${Object.entries({
+		title: meta.title,
+		description: meta.description,
+		url: meta.url
+	}).filter((field) => !!field[1]).map(([key, value]) => `${key}: ${JSON.stringify(value)}`).join("\n")}\n---\n\n${markdown}`;
+}
+/** The head every page gets, whatever its layout kind. */
+function buildPageHead(input) {
+	const { title, description } = buildPageMeta(input);
+	const meta = [{ title }];
+	if (description) meta.push({
 		name: "description",
-		content: page.page.metaDescription
+		content: description
 	});
 	const ogImageParams = new URLSearchParams({
-		...page.layout && { layoutId: page.layout.layoutId },
-		title: pageMetaTitle,
-		...page.page.metaDescription && { description: page.page.metaDescription },
-		...page.projectName && { projectName: page.projectName }
+		...input.layout && { layoutId: input.layout.id },
+		title: input.ogImageTitle ?? title,
+		...description && { description },
+		...input.projectName && { projectName: input.projectName }
 	});
-	const ogImageUrl = page.page.customOgImageUrl ?? `${origin}/og?${ogImageParams.toString()}`;
+	const ogImageUrl = input.customOgImageUrl ?? `${input.origin}/og?${ogImageParams.toString()}`;
 	meta.push({
 		property: "og:title",
 		content: title
@@ -219,18 +306,38 @@ function buildCamoxPageHead(camoxApp, loaderData) {
 		property: "og:image:height",
 		content: "630"
 	});
-	if (page.page.metaDescription) meta.push({
+	if (description) meta.push({
 		property: "og:description",
-		content: page.page.metaDescription
+		content: description
+	});
+	const links = [{
+		rel: "icon",
+		href: input.faviconUrl
+	}];
+	if (input.hasMarkdown) links.push({
+		rel: "alternate",
+		type: "text/markdown",
+		href: `${input.origin}${getMarkdownPath(input.pageFullPath)}`
 	});
 	return {
 		meta,
-		links: [{
-			rel: "icon",
-			href: faviconUrl
-		}]
+		links
 	};
 }
+/** A curated page's head. Its paths keep the prefix of the page's `locale`. */
+function buildCamoxPageHead(camoxApp, loaderData, locale) {
+	if (!loaderData) return {};
+	const { page, origin, faviconUrl } = loaderData;
+	const metaInput = curatedPageMetaInput(camoxApp, page, locale);
+	return buildPageHead({
+		...metaInput,
+		ogImageTitle: metaInput.pageMetaTitle,
+		customOgImageUrl: page.page.customOgImageUrl,
+		origin,
+		faviconUrl,
+		hasMarkdown: true
+	});
+}
 
 //#endregion
-export { buildCamoxPageHead, createMarkdownResponse, createServerApiClient, isAuthSessionError, isNotFoundError, loadCamoxPageForRequest, seedBlockCaches };
+export { buildCamoxPageHead, buildCamoxPageLoaderData, buildFaviconPlaceholderUrl, buildFaviconUrl, buildPageHead, buildPageMeta, createMarkdownResponse, createServerApiClient, createServerStudioCache, getMarkdownPath, isAuthSessionError, isNotFoundError, loadCamoxPage, loadCamoxPageForRequest, parseMarkdownPath, parseQuality, prefersMarkdown, readDraftOrLive, readScopeLocales, renderedHref, resolveMemberProject, withFrontMatter };