@postedin/cms-client 0.1.0

package/dist/payload-types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=payload-types.js.map

package/dist/payload-types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@postedin/cms-client",
+  "version": "0.1.0",
+  "description": "Payload CMS data access, wiring, routes and form proxy for postedin sites.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/postedin/cms-sites.git",
+    "directory": "packages/cms-client"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "bin",
+    "!**/__tests__",
+    "!**/__fixtures__"
+  ],
+  "bin": {
+    "cms-profile-build": "./bin/profile/build.mjs",
+    "cms-profile-report": "./bin/profile/report.mjs",
+    "cms-profile-interference": "./bin/profile/interference.mjs",
+    "cms-dissect-build-log": "./bin/dissect/cli.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js"
+    },
+    "./upload-policy": {
+      "types": "./dist/form-proxy/upload-policy.d.ts",
+      "import": "./dist/form-proxy/upload-policy.js"
+    },
+    "./payload-types": {
+      "types": "./dist/payload-types.d.ts",
+      "import": "./dist/payload-types.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "natural": "^8.1.1",
+    "qs-esm": "^7.0.3"
+  },
+  "peerDependencies": {
+    "vite": ">=6"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.2"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/api.ts

@@ -0,0 +1,387 @@
+import { stringify } from 'qs-esm';
+import type { Locale } from './locales';
+import type { Media, Project } from './payload-types';
+import { getRandomPlaceholderUrl } from './placeholder';
+
+// The scheme names the CMS collection the key belongs to. Build credentials
+// are project-scoped `api-keys` documents — a principal that can read one
+// project and write nothing — rather than a person's key in `users`, which
+// authenticates as that person with all of their permissions.
+const CMS_API_KEY_COLLECTION = 'api-keys';
+
+const DEPTH = 2;
+const LIMIT = 1000;
+
+// How many pages of one collection are fetched at a time. A CMS on a
+// shared-tier database tears down connections under a build's request fan-out:
+// `media` on a large site is 20k+ documents, so firing its remaining 20 pages
+// in a single `Promise.all` made the CMS answer 500 and failed the build.
+// Pages are still fetched in parallel, just a few at a time.
+const PAGE_CONCURRENCY = 4;
+
+/** Which of the two URL helpers is asking: a download link or an `<img>`. */
+export type UploadUse = 'file' | 'image';
+
+/**
+ * A site's own rule for where an upload is served from. Return a URL to use
+ * it, or `undefined` to let the default rule decide. Consulted for every
+ * production build, bucket or not, since a site's rewrites do not depend on
+ * one; in dev the URL the CMS returned is always used.
+ */
+export type ResolveUploadUrl = (
+	media: Media,
+	use: UploadUse,
+) => string | null | undefined;
+
+export interface ApiOptions {
+	apiUrl: string;
+	apiKey: string;
+	projectSlug: string;
+	uploadsBaseUrl?: string;
+	protectionBypassSecret?: string;
+	isDev: boolean;
+	pageConcurrency?: number;
+	resolveUploadUrl?: ResolveUploadUrl;
+}
+
+export type Collection<T> = {
+	docs: T[];
+	totalDocs: number;
+	limit: number;
+	totalPages: number;
+	page: number;
+	pagingCounter: number;
+	hasPrevPage: boolean;
+	hasNextPage: boolean;
+	prevPage: number | null;
+	nextPage: number | null;
+};
+
+// Runs `worker` over `items` with at most `limit` in flight. Results keep the
+// order of `items`, and the first rejection rejects the whole call — the same
+// contract as the `Promise.all` this replaces.
+export async function mapWithConcurrency<TItem, TResult>(
+	items: TItem[],
+	limit: number,
+	worker: (item: TItem, index: number) => Promise<TResult>,
+): Promise<TResult[]> {
+	const results = new Array<TResult>(items.length);
+	let next = 0;
+
+	const runner = async () => {
+		while (next < items.length) {
+			const index = next++;
+			results[index] = await worker(items[index], index);
+		}
+	};
+
+	await Promise.all(
+		Array.from({ length: Math.min(limit, items.length) }, runner),
+	);
+
+	return results;
+}
+
+export type FallbackMode = 'null' | 'default';
+
+function applyLocale(
+	query: any,
+	locale: Locale | undefined,
+	fallback: FallbackMode,
+) {
+	if (!locale) {
+		return query;
+	}
+	query.locale = locale;
+	// 'null' → untranslated localized fields come back as null so callers can
+	// use null slug/title as the "not translated" signal (used by collections
+	// that drive getStaticPaths to skip untranslated entries).
+	// 'default' → let Payload fall back to the default-locale value. Right for
+	// globals/chrome (header, footer, seo, appearance) where we'd rather show
+	// the default-locale content than an empty UI.
+	if (fallback === 'null') {
+		query['fallback-locale'] = 'null';
+	}
+	return query;
+}
+
+export type FetchCmsGlobalOptions = {
+	query?: any;
+	depth?: number;
+	locale?: Locale;
+	fallback?: FallbackMode;
+};
+
+export type FetchCmsCollectionOptions = FetchCmsGlobalOptions & {
+	status?: string;
+	limit?: number;
+	sort?: string;
+};
+
+export type Api = ReturnType<typeof createApi>;
+
+export function createApi(options: ApiOptions) {
+	const pageConcurrency = options.pageConcurrency ?? PAGE_CONCURRENCY;
+
+	function buildHeaders(): Record<string, string> {
+		const headers: Record<string, string> = {
+			Authorization: `${CMS_API_KEY_COLLECTION} API-Key ${options.apiKey}`,
+		};
+
+		if (options.protectionBypassSecret) {
+			headers['x-vercel-protection-bypass'] = options.protectionBypassSecret;
+		}
+
+		return headers;
+	}
+
+	// `false` asks for no project scope at all — the one query that needs it is
+	// the project lookup itself.
+	function apiUrl(url: string, query: any = {}, scoped = true) {
+		if (scoped) {
+			query.where = {
+				and: [
+					{ 'project.slug': { equals: options.projectSlug } },
+					...(query.where ? [query.where] : []),
+				],
+			};
+		}
+
+		return options.apiUrl + url + stringify(query, { addQueryPrefix: true });
+	}
+
+	function getUploadsPublicUrl(endpoint: string) {
+		return `${options.uploadsBaseUrl}/${endpoint}`;
+	}
+
+	// Uploads are served straight from the bucket at `uploadsBaseUrl`, unless
+	// the site's `resolveUploadUrl` says otherwise. The site is asked first,
+	// with or without a bucket: its rule points at its own rewrites.
+	//
+	// Without a bucket the default rule has nothing to point at, so fall back
+	// to the absolute URL Payload itself returns and let the CMS serve the
+	// file. Testing `isDev` alone is not enough: `pnpm build` is a production
+	// build, so a local build took the bucket branch with no bucket configured
+	// and emitted `/<filename>` — a root-relative path to a file that exists
+	// nowhere in the output. That is why images render in `pnpm dev` but not
+	// in `pnpm preview`.
+	const hasUploadsBucket = !!options.uploadsBaseUrl;
+
+	function siteUploadUrl(media: Media, use: UploadUse) {
+		return options.resolveUploadUrl?.(media, use) ?? undefined;
+	}
+
+	function fileUrl(media?: Media | null) {
+		if (!media) {
+			return null;
+		}
+
+		if (options.isDev) {
+			return media.url ?? null;
+		}
+
+		const own = siteUploadUrl(media, 'file');
+		if (own !== undefined) {
+			return own;
+		}
+
+		if (hasUploadsBucket && media.filename) {
+			return getUploadsPublicUrl(media.filename);
+		}
+
+		return media.url ?? null;
+	}
+
+	function imageUrl(media?: Media | null) {
+		if (!media) {
+			return getRandomPlaceholderUrl();
+		}
+
+		if (options.isDev) {
+			return media.url ?? getRandomPlaceholderUrl();
+		}
+
+		const own = siteUploadUrl(media, 'image');
+		if (own !== undefined) {
+			return own ?? getRandomPlaceholderUrl();
+		}
+
+		if (hasUploadsBucket && media.filename) {
+			return getUploadsPublicUrl(media.filename);
+		}
+
+		return media.url || getRandomPlaceholderUrl();
+	}
+
+	// Fetch a raw uploaded file through the CMS API. Upload docs' `url` is
+	// relative to the CMS host (e.g. /api/vcards/file/{filename}).
+	async function fetchCmsFile(url: string): Promise<Response> {
+		return await fetch(new URL(url, options.apiUrl), {
+			headers: buildHeaders(),
+		});
+	}
+
+	async function fetchCmsGlobal<T>(
+		global: string,
+		fetchOptions: FetchCmsGlobalOptions = {},
+	): Promise<T> {
+		const query = fetchOptions.query || {};
+		const depth = fetchOptions.depth ?? DEPTH;
+
+		applyLocale(query, fetchOptions.locale, fetchOptions.fallback ?? 'null');
+
+		const res = await fetch(
+			apiUrl(`/api/globals/${global}`, { depth, ...query }),
+			{ headers: buildHeaders() },
+		);
+
+		return (await res.json()) as T;
+	}
+
+	async function fetchCmsGlobalCollection<T>(
+		collection: string,
+		fetchOptions: FetchCmsGlobalOptions = {},
+	): Promise<T> {
+		const query = fetchOptions.query || {};
+		const depth = fetchOptions.depth ?? DEPTH;
+
+		applyLocale(query, fetchOptions.locale, fetchOptions.fallback ?? 'null');
+
+		const res = await fetch(apiUrl(`/api/${collection}`, { depth, ...query }), {
+			headers: buildHeaders(),
+		});
+
+		if (!res.ok) {
+			const url = apiUrl(`/api/${collection}`, { depth, ...query });
+			const text = await res.text();
+			let error: string;
+
+			try {
+				const json = JSON.parse(text);
+				error = `${res.status} (${url})j: ${json.message || JSON.stringify(json)}`;
+			} catch {
+				error = `${res.status} (${url})t: ${text}`;
+			}
+
+			throw new Error(error);
+		}
+
+		const docs = (await res.json()).docs;
+
+		if (!docs.length) {
+			throw new Error(
+				`Failed to load global collection "${collection}", no docs found.`,
+			);
+		}
+
+		return docs[0];
+	}
+
+	async function fetchCmsCollection<T>(
+		collection: string,
+		fetchOptions: FetchCmsCollectionOptions = {},
+	): Promise<T[]> {
+		const query = fetchOptions.query || {};
+		const depth = fetchOptions.depth ?? DEPTH;
+		const limit = fetchOptions.limit || LIMIT;
+		const sort = fetchOptions.sort || '-createdAt';
+		const fields = query.fields || {};
+
+		if (fetchOptions.status) {
+			query.where = query?.where || {};
+			query.where._status = { equals: fetchOptions.status };
+		}
+
+		applyLocale(query, fetchOptions.locale, fetchOptions.fallback ?? 'null');
+
+		const fetchPage = async (page: number = 1): Promise<Collection<T>> => {
+			const res = await fetch(
+				apiUrl(`/api/${collection}`, {
+					depth,
+					limit,
+					sort,
+					fields,
+					...query,
+					page,
+				}),
+				{ headers: buildHeaders() },
+			);
+
+			if (!res.ok) {
+				const errorText = await res.text();
+
+				throw new Error(
+					`CMS API request failed for ${collection} (page ${page})\n` +
+						`Status: ${res.status} ${res.statusText}\n` +
+						`Details: ${errorText.substring(0, 500)}${errorText.length > 500 ? '...' : ''}`,
+				);
+			}
+
+			return await res.json();
+		};
+
+		const firstPage = await fetchPage();
+
+		let otherPagesData: T[][] = [];
+		if (firstPage.totalPages > 1) {
+			const otherPages = Array.from(
+				{ length: firstPage.totalPages - 1 },
+				(_, i) => i + 2,
+			);
+			otherPagesData = await mapWithConcurrency(
+				otherPages,
+				pageConcurrency,
+				async (p) => (await fetchPage(p)).docs,
+			);
+		}
+
+		return firstPage.docs.concat(otherPagesData.flat());
+	}
+
+	async function fetchCmsProject(): Promise<Project> {
+		const slug = options.projectSlug;
+		const res = await fetch(
+			apiUrl(
+				'/api/projects',
+				{ limit: 1, where: { slug: { equals: slug } } },
+				false,
+			),
+			{ headers: buildHeaders() },
+		);
+
+		if (!res.ok) {
+			const errorText = await res.text();
+
+			throw new Error(
+				`CMS API request failed for ProjectBySlug\n` +
+					`Status: ${res.status} ${res.statusText}\n` +
+					`Details: ${errorText.substring(0, 500)}${errorText.length > 500 ? '...' : ''}`,
+			);
+		}
+
+		const docs = (await res.json()).docs;
+
+		if (!docs) {
+			throw new Error(
+				`CMS API request failed for ProjectBySlug\n` +
+					`Status: ${res.status} ${res.statusText}\n` +
+					`Details: failed to find project by slug "${slug}"`,
+			);
+		}
+
+		return docs[0];
+	}
+
+	return {
+		apiUrl,
+		buildHeaders,
+		getUploadsPublicUrl,
+		fileUrl,
+		imageUrl,
+		fetchCmsFile,
+		fetchCmsGlobal,
+		fetchCmsGlobalCollection,
+		fetchCmsCollection,
+		fetchCmsProject,
+	};
+}

package/src/blog-listing.ts

@@ -0,0 +1,75 @@
+import type { Context } from './context';
+import type { Locale } from './locales';
+import type { Page } from './payload-types';
+
+export interface BlogListing {
+	/**
+	 * What the project calls its blog. `null` when no blog page is configured or
+	 * the editor left the field blank, in which case the caller falls back to the
+	 * `blog.title` translation.
+	 */
+	name: string | null;
+	/** Intro copy for the listing, in the dual Lexical/HTML shape. */
+	description: Page['listingDescription'] | null;
+}
+
+const EMPTY: BlogListing = { name: null, description: null };
+
+async function fetchBlogListing(
+	ctx: Context,
+	locale: Locale,
+): Promise<BlogListing> {
+	const options = await ctx.cms(locale).options();
+	const configured = options.blog?.page;
+	const id =
+		typeof configured === 'string' ? configured : (configured?.id ?? null);
+
+	if (!id) {
+		return EMPTY;
+	}
+
+	// Read the standalone document rather than the copy embedded in the options
+	// global, for the same reason `home-page.ts` does: globals are fetched
+	// without locale fallback, so an untranslated blog page comes back with a
+	// null `listingName` and would head the English listing with nothing at all.
+	const [doc] = await ctx.api.fetchCmsCollection<Page>('pages', {
+		locale,
+		fallback: 'default',
+		status: 'published',
+		limit: 1,
+		query: { where: { id: { equals: id } } },
+	});
+
+	if (!doc) {
+		return EMPTY;
+	}
+
+	return {
+		name: doc.listingName || null,
+		description: doc.listingDescription ?? null,
+	};
+}
+
+export function createBlogListing(ctx: Context) {
+	const cache = new Map<Locale, Promise<BlogListing>>();
+
+	/**
+	 * The name and intro copy the CMS holds for the blog listing. Every surface that
+	 * heads a blog listing — the paginated index, the category and tag pages —
+	 * reads it from here, so a project that calls its blog something else says so
+	 * everywhere rather than only in its menu.
+	 *
+	 * Server-only. Cached per locale, so calling it from several components costs
+	 * one fetch per locale per build.
+	 */
+	return function getBlogListing(locale: Locale): Promise<BlogListing> {
+		let pending = cache.get(locale);
+
+		if (!pending) {
+			pending = fetchBlogListing(ctx, locale);
+			cache.set(locale, pending);
+		}
+
+		return pending;
+	};
+}

package/src/browser.ts

@@ -0,0 +1,24 @@
+// Everything a hydrated island may import. Nothing here reaches the CMS or
+// holds a credential, so it is safe in the client bundle.
+export type {
+	CmsCallToActionLinks,
+	CmsFooter,
+	CmsHeader,
+	CmsLink,
+	CmsMainMenu,
+	CmsMenuItem,
+	CmsSocialLinks,
+} from './collections/header-footer';
+export { type CmsToHref, defineCmsToHref } from './cms-to-href';
+export {
+	defineLocales,
+	type Locale,
+	type LocaleOptions,
+	type Locales,
+} from './locales';
+export {
+	type CreateRoutes,
+	defineRoutes,
+	type HomePageRef,
+	type Routes,
+} from './routes';

package/src/client.ts

@@ -0,0 +1,144 @@
+import { createApi, type ResolveUploadUrl } from './api';
+import { createBlogListing } from './blog-listing';
+import { buildCms, type Cms } from './cms';
+import { defineCmsToHref } from './cms-to-href';
+import type { AppearanceFallbacks } from './collections/appearance';
+import { wirePost } from './collections/posts';
+import { createConfigTime } from './config-time';
+import type { Context } from './context';
+import { createFormProxy, createFormProxyCmsClient } from './form-proxy';
+import { createHomePage } from './home-page';
+import { createCollectionLoader, createGlobalLoader } from './loader';
+import { defineLocales, type Locale, type LocaleOptions } from './locales';
+import type { Appearance, Post, Project } from './payload-types';
+import { defineRoutes } from './routes';
+
+/** What an extension collection is built from. */
+export interface ExtensionContext {
+	api: Context['api'];
+	locale: Locale;
+	/** The client's other services, for a collection that wires against them. */
+	cms: (locale: Locale) => Cms;
+	createCollectionLoader: typeof createCollectionLoader;
+	createGlobalLoader: typeof createGlobalLoader;
+}
+
+/**
+ * A collection only one site reads. It is built per locale and appears on
+ * `client.cms(locale)` under the key it was registered with.
+ */
+export type Extension<T = unknown> = (context: ExtensionContext) => T;
+
+/** What each extension builds, by the key it appears under. */
+export type Extensions = Record<string, unknown>;
+
+export type CmsWith<E extends Extensions> = Cms & E;
+
+export interface ClientOptions<E extends Extensions = Record<never, never>>
+	extends LocaleOptions {
+	/** The CMS origin, e.g. `https://cms.example.com`. */
+	apiUrl: string;
+	/** A project-scoped `api-keys` document's key. */
+	apiKey: string;
+	/** Every query is scoped to this project. */
+	projectSlug: string;
+	/** Public origin of the uploads bucket. Without it the CMS serves files. */
+	uploadsBaseUrl?: string;
+	/** Sent as `x-vercel-protection-bypass` when the CMS sits behind it. */
+	protectionBypassSecret?: string;
+	/** Dev serves every upload from the CMS's own URL. */
+	isDev: boolean;
+	/**
+	 * The Appearance document, fetched at config time. Required for
+	 * `cms.appearance()`; a config-time client leaves it out.
+	 */
+	appearance?: Appearance;
+	/** What a blank Appearance field falls back to. */
+	appearanceFallbacks?: AppearanceFallbacks;
+	/**
+	 * The Project document, fetched at config time. Required for
+	 * `cms.project()` and the form proxy; a config-time client leaves it out.
+	 */
+	project?: Project;
+	/** Collection pages fetched at a time. Default 4. */
+	pageConcurrency?: number;
+	/** A site's own rule for where an upload is served from. */
+	resolveUploadUrl?: ResolveUploadUrl;
+	/** Collections only this site reads, by the key they appear under. */
+	extensions?: { [K in keyof E]: Extension<E[K]> };
+}
+
+export type Client<E extends Extensions = Record<never, never>> = ReturnType<
+	typeof createClient<E>
+>;
+
+/**
+ * The CMS client a site builds once from its environment. Nothing in here
+ * reads the environment itself: an npm-installed package is externalised by
+ * Astro, so `import.meta.env` would be empty by the time it ran.
+ */
+export function createClient<E extends Extensions = Record<never, never>>(
+	options: ClientOptions<E>,
+) {
+	const locales = defineLocales(options);
+	const api = createApi(options);
+	const createRoutes = defineRoutes(locales);
+	const cmsToHref = defineCmsToHref(createRoutes);
+
+	const instances = new Map<Locale, CmsWith<E>>();
+
+	const ctx: Context = {
+		api,
+		locales,
+		options,
+		cms: (locale) => cms(locale),
+	};
+
+	function cms(locale: Locale = locales.defaultLocale): CmsWith<E> {
+		let instance = instances.get(locale);
+		if (!instance) {
+			const base = buildCms(ctx, locale);
+			const extended: Record<string, unknown> = {};
+			for (const [key, extension] of Object.entries<Extension>(
+				options.extensions ?? {},
+			)) {
+				extended[key] = extension({
+					api,
+					locale,
+					cms: ctx.cms,
+					createCollectionLoader,
+					createGlobalLoader,
+				});
+			}
+			instance = { ...base, ...extended } as CmsWith<E>;
+			instances.set(locale, instance);
+		}
+		return instance;
+	}
+
+	const { getHomePage, getHomePageRef } = createHomePage(ctx);
+
+	const formProxy = createFormProxy(
+		createFormProxyCmsClient(api, options.apiUrl),
+		() => cms().project(),
+		locales.locales,
+	);
+
+	return {
+		options,
+		locales,
+		api,
+		cms,
+		routes: createRoutes,
+		cmsToHref,
+		getHomePage,
+		getHomePageRef,
+		getBlogListing: createBlogListing(ctx),
+		/** Wires a single post document, e.g. a draft for live preview. */
+		wirePost: (post: Post | undefined, locale: Locale) =>
+			wirePost(ctx, post, locale),
+		formProxy,
+		/** The fetches `astro.config.mjs` makes before the build starts. */
+		config: createConfigTime(api, createRoutes(locales.defaultLocale)),
+	};
+}