busabase-cms-sdk 0.1.3

package/dist/content-BXgsWQjQ.js

@@ -0,0 +1,1175 @@
+import { z } from "zod";
+import { Busabase } from "busabase-sdk";
+//#region src/errors.ts
+var BusabaseCmsError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "BusabaseCmsError";
+	}
+};
+var BusabaseCmsSetupError = class extends BusabaseCmsError {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "BusabaseCmsSetupError";
+	}
+};
+var BusabaseCmsSchemaDriftError = class extends BusabaseCmsSetupError {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "BusabaseCmsSchemaDriftError";
+	}
+};
+//#endregion
+//#region src/schema.ts
+const BUSABASE_CMS_SCHEMA_VERSION = 1;
+const BUSABASE_CMS_METADATA_KEY = "busabaseCms";
+const BUSABASE_CMS_ROLES = [
+	"categories",
+	"tags",
+	"posts",
+	"pages"
+];
+/** The only profile the SDK itself ships a field shape for. Any other non-empty string is a
+* caller-owned profile label (see `fieldsOverride`/`legacyOptionalFields` on the provisioning
+* options) — the SDK stores and round-trips it but never branches on its value. */
+const BUSABASE_CMS_SCHEMA_PROFILES = ["standard"];
+const i18nName = (en, zhCN) => ({
+	en,
+	"zh-CN": zhCN
+});
+const selectOptions = (values) => ({ choices: values.map(([id, en, zhCN]) => ({
+	id,
+	name: `${en} / ${zhCN}`
+})) });
+const localeOptions = selectOptions([
+	[
+		"en",
+		"English",
+		"英文"
+	],
+	[
+		"zh-CN",
+		"Simplified Chinese",
+		"简体中文"
+	],
+	[
+		"zh-TW",
+		"Traditional Chinese",
+		"繁體中文"
+	],
+	[
+		"ja",
+		"Japanese",
+		"日文"
+	],
+	[
+		"pt",
+		"Portuguese",
+		"葡萄牙文"
+	]
+]);
+const statusOptions = selectOptions([
+	[
+		"draft",
+		"Draft",
+		"草稿"
+	],
+	[
+		"in-review",
+		"In review",
+		"审核中"
+	],
+	[
+		"published",
+		"Published",
+		"已发布"
+	],
+	[
+		"archived",
+		"Archived",
+		"已归档"
+	]
+]);
+const taxonomyFields = () => [
+	{
+		slug: "name",
+		name: i18nName("Name", "名称"),
+		type: "text",
+		required: true,
+		options: {}
+	},
+	{
+		slug: "slug",
+		name: i18nName("Slug", "标识"),
+		type: "text",
+		required: true,
+		options: {}
+	},
+	{
+		slug: "locale",
+		name: i18nName("Locale", "语言"),
+		type: "select",
+		required: true,
+		options: localeOptions
+	},
+	{
+		slug: "description",
+		name: i18nName("Description", "描述"),
+		type: "longtext",
+		required: false,
+		options: {}
+	},
+	{
+		slug: "updated-at",
+		name: i18nName("Updated at", "更新时间"),
+		type: "updated_time",
+		required: false,
+		options: {}
+	}
+];
+const postFields = () => [
+	[
+		"path",
+		"Path",
+		"网址",
+		"text",
+		true
+	],
+	[
+		"title",
+		"Title",
+		"标题",
+		"text",
+		true
+	],
+	[
+		"slug",
+		"Slug",
+		"标识",
+		"text",
+		true
+	]
+].map(([slug, en, zhCN, type, required]) => ({
+	slug,
+	name: i18nName(en, zhCN),
+	type,
+	required,
+	options: {}
+}));
+const buildPostFields = (baseIds) => [
+	...postFields(),
+	{
+		slug: "locale",
+		name: i18nName("Locale", "语言"),
+		type: "select",
+		required: true,
+		options: localeOptions
+	},
+	{
+		slug: "status",
+		name: i18nName("Status", "状态"),
+		type: "select",
+		required: true,
+		options: statusOptions
+	},
+	{
+		slug: "description",
+		name: i18nName("Excerpt", "摘要"),
+		type: "longtext",
+		required: false,
+		options: {}
+	},
+	{
+		slug: "body",
+		name: i18nName("Body", "正文"),
+		type: "markdown",
+		required: true,
+		options: {}
+	},
+	{
+		slug: "cover-image",
+		name: i18nName("Cover image", "封面图片"),
+		type: "attachment",
+		required: false,
+		options: { attachment: {
+			maxFiles: 1,
+			allowedMimeTypes: ["image/*"],
+			maxFileSize: 10485760
+		} }
+	},
+	{
+		slug: "attachments",
+		name: i18nName("Attachments", "附件"),
+		type: "attachment",
+		required: false,
+		options: { attachment: {
+			maxFiles: 20,
+			allowedMimeTypes: ["image/*", "application/pdf"],
+			maxFileSize: 20971520
+		} }
+	},
+	{
+		slug: "author",
+		name: i18nName("Author", "作者"),
+		type: "text",
+		required: false,
+		options: {}
+	},
+	{
+		slug: "categories",
+		name: i18nName("Categories", "分类"),
+		type: "relation",
+		required: false,
+		options: {
+			...baseIds.categories ? { targetBaseId: baseIds.categories } : {},
+			multiple: true
+		}
+	},
+	{
+		slug: "tags",
+		name: i18nName("Tags", "标签"),
+		type: "relation",
+		required: false,
+		options: {
+			...baseIds.tags ? { targetBaseId: baseIds.tags } : {},
+			multiple: true
+		}
+	},
+	{
+		slug: "published-at",
+		name: i18nName("Published at", "发布时间"),
+		type: "date",
+		required: false,
+		options: {}
+	},
+	{
+		slug: "canonical-url",
+		name: i18nName("Canonical URL", "规范网址"),
+		type: "url",
+		required: false,
+		options: {}
+	},
+	{
+		slug: "legacy-paths",
+		name: i18nName("Legacy paths", "旧网址"),
+		type: "json",
+		required: false,
+		options: {}
+	},
+	{
+		slug: "seo-title",
+		name: i18nName("SEO title", "SEO 标题"),
+		type: "text",
+		required: false,
+		options: {}
+	},
+	{
+		slug: "seo-description",
+		name: i18nName("SEO description", "SEO 描述"),
+		type: "longtext",
+		required: false,
+		options: {}
+	},
+	{
+		slug: "schema-version",
+		name: i18nName("Schema version", "结构版本"),
+		type: "number",
+		required: true,
+		options: {}
+	},
+	{
+		slug: "updated-at",
+		name: i18nName("Updated at", "更新时间"),
+		type: "updated_time",
+		required: false,
+		options: {}
+	}
+];
+const pageFields = () => [
+	{
+		slug: "path",
+		name: i18nName("Path", "网址"),
+		type: "text",
+		required: true,
+		options: {}
+	},
+	{
+		slug: "title",
+		name: i18nName("Title", "标题"),
+		type: "text",
+		required: true,
+		options: {}
+	},
+	{
+		slug: "slug",
+		name: i18nName("Slug", "标识"),
+		type: "text",
+		required: true,
+		options: {}
+	},
+	{
+		slug: "locale",
+		name: i18nName("Locale", "语言"),
+		type: "select",
+		required: true,
+		options: localeOptions
+	},
+	{
+		slug: "status",
+		name: i18nName("Status", "状态"),
+		type: "select",
+		required: true,
+		options: statusOptions
+	},
+	{
+		slug: "template",
+		name: i18nName("Template", "模板"),
+		type: "select",
+		required: true,
+		options: selectOptions([
+			[
+				"standard",
+				"Standard",
+				"标准"
+			],
+			[
+				"landing",
+				"Landing",
+				"落地页"
+			],
+			[
+				"product",
+				"Product",
+				"产品"
+			],
+			[
+				"use-case",
+				"Use case",
+				"使用场景"
+			]
+		])
+	},
+	{
+		slug: "body",
+		name: i18nName("Body", "正文"),
+		type: "html",
+		required: true,
+		options: {}
+	},
+	{
+		slug: "hero",
+		name: i18nName("Hero", "首屏"),
+		type: "json",
+		required: false,
+		options: {}
+	},
+	{
+		slug: "features",
+		name: i18nName("Features", "功能"),
+		type: "json",
+		required: false,
+		options: {}
+	},
+	{
+		slug: "faqs",
+		name: i18nName("FAQs", "常见问题"),
+		type: "json",
+		required: false,
+		options: {}
+	},
+	{
+		slug: "canonical-url",
+		name: i18nName("Canonical URL", "规范网址"),
+		type: "url",
+		required: false,
+		options: {}
+	},
+	{
+		slug: "legacy-paths",
+		name: i18nName("Legacy paths", "旧网址"),
+		type: "json",
+		required: false,
+		options: {}
+	},
+	{
+		slug: "seo-title",
+		name: i18nName("SEO title", "SEO 标题"),
+		type: "text",
+		required: false,
+		options: {}
+	},
+	{
+		slug: "seo-description",
+		name: i18nName("SEO description", "SEO 描述"),
+		type: "longtext",
+		required: false,
+		options: {}
+	},
+	{
+		slug: "schema-version",
+		name: i18nName("Schema version", "结构版本"),
+		type: "number",
+		required: true,
+		options: {}
+	},
+	{
+		slug: "updated-at",
+		name: i18nName("Updated at", "更新时间"),
+		type: "updated_time",
+		required: false,
+		options: {}
+	}
+];
+const replaceField = (fields, slug, replacement) => fields.map((field) => field.slug === slug ? replacement : field);
+const getBusabaseCmsBaseDefinition = (role, baseIds = {}, fieldsOverride) => {
+	if (role === "categories" || role === "tags") return {
+		role,
+		name: role === "categories" ? "Categories / 分类" : "Tags / 标签",
+		description: role === "categories" ? "Reusable content categories / 可复用的内容分类" : "Reusable content tags / 可复用的内容标签",
+		fields: taxonomyFields()
+	};
+	if (role === "posts") {
+		const standard = buildPostFields(baseIds);
+		return {
+			role,
+			name: "Posts / 文章",
+			description: "Publishable Markdown posts / 可发布的 Markdown 文章",
+			fields: fieldsOverride ? fieldsOverride("posts", standard, baseIds) : standard
+		};
+	}
+	const standard = pageFields();
+	return {
+		role,
+		name: "Pages / 页面",
+		description: "Publishable HTML pages / 可发布的 HTML 页面",
+		fields: fieldsOverride ? fieldsOverride("pages", standard, baseIds) : standard
+	};
+};
+//#endregion
+//#region src/provision.ts
+const isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const parseMetadata = (folder) => {
+	const raw = folder.metadata[BUSABASE_CMS_METADATA_KEY];
+	if (raw === void 0) return null;
+	if (!isRecord(raw) || raw.schemaVersion !== 1 || !isRecord(raw.bases)) throw new BusabaseCmsSchemaDriftError(`Folder "${folder.name}" has unsupported ${BUSABASE_CMS_METADATA_KEY} metadata`);
+	const rawBases = raw.bases;
+	const profile = raw.profile === void 0 ? "standard" : raw.profile;
+	if (typeof profile !== "string" || profile.length === 0) throw new BusabaseCmsSchemaDriftError(`Folder "${folder.name}" has unsupported Busabase CMS profile metadata`);
+	const bases = Object.fromEntries(BUSABASE_CMS_ROLES.map((role) => [role, rawBases[role]]));
+	for (const role of BUSABASE_CMS_ROLES) if (typeof bases[role] !== "string" || bases[role].length === 0) throw new BusabaseCmsSchemaDriftError(`Folder "${folder.name}" metadata is missing the ${role} Base ID`);
+	return {
+		schemaVersion: 1,
+		profile,
+		bases
+	};
+};
+const assertMetadataProfile = (folder, metadata, requested) => {
+	const stored = metadata.profile ?? "standard";
+	if (stored !== requested) throw new BusabaseCmsSchemaDriftError(`Folder "${folder.name}" is bound to the ${stored} CMS profile, not ${requested}`);
+};
+const requireProvisioningSource = (source) => {
+	if (!source.getBaseById || !source.getNode || !source.listDirectChildren || !source.updateNodeMetadata) throw new BusabaseCmsSetupError("folderId requires a Busabase client/config or a source with node, Base, and metadata discovery methods");
+	return source;
+};
+const requireLazyProvisioningSource = (source) => {
+	if (!source.createBase || !source.createField) throw new BusabaseCmsSetupError("lazyCreate requires direct Base and field creation methods from the Busabase SDK");
+	return source;
+};
+const getFolder = async (source, folderId) => {
+	const folder = await source.getNode(folderId);
+	if (!folder) throw new BusabaseCmsSetupError(`Busabase CMS Folder "${folderId}" was not found`);
+	if (folder.type !== "folder") throw new BusabaseCmsSetupError(`Busabase CMS node "${folderId}" is not a Folder`);
+	return folder;
+};
+const getDirectBaseNodes = async (source, folderId) => (await source.listDirectChildren(folderId)).filter((node) => node.parentId === folderId && node.type === "base" && Boolean(node.baseId));
+const normalizeName = (value) => value.trim().toLocaleLowerCase();
+const roleAliases = {
+	posts: [
+		"posts / 文章",
+		"posts",
+		"文章",
+		"blog posts",
+		"blog posts / 博客文章",
+		"博客文章"
+	],
+	pages: [
+		"pages / 页面",
+		"pages",
+		"页面"
+	],
+	categories: [
+		"categories / 分类",
+		"categories",
+		"分类"
+	],
+	tags: [
+		"tags / 标签",
+		"tags",
+		"标签"
+	]
+};
+const candidateScore = (role, folder, node) => {
+	const name = normalizeName(node.name);
+	const expectedSlug = `${folder.slug}-${role}`;
+	if (roleAliases[role].includes(name)) return 100;
+	if (role === "posts" && node.slug === "blog") return 90;
+	if (node.slug === expectedSlug) return 80;
+	if (node.slug === `busabase-cms-${role}`) return 70;
+	return 0;
+};
+const adoptExistingBases = async (source, folder, nodes) => {
+	const available = [];
+	for (const node of nodes) {
+		const base = await source.getBaseById(node.baseId);
+		if (base) available.push({
+			node,
+			base
+		});
+	}
+	const adopted = {};
+	const used = /* @__PURE__ */ new Set();
+	for (const role of BUSABASE_CMS_ROLES) {
+		const candidates = available.filter(({ base }) => !used.has(base.id)).map((candidate) => ({
+			...candidate,
+			score: candidateScore(role, folder, candidate.node)
+		})).filter(({ score }) => score > 0).sort((a, b) => b.score - a.score);
+		if (!candidates[0]) continue;
+		if (candidates[1]?.score === candidates[0].score) throw new BusabaseCmsSetupError(`Could not uniquely identify the ${role} Base below Folder "${folder.name}"`);
+		adopted[role] = candidates[0].base.id;
+		used.add(candidates[0].base.id);
+	}
+	return adopted;
+};
+const validateMetadataBases = async (source, folder, nodes, baseIds) => {
+	const nodeByBaseId = new Map(nodes.map((node) => [node.baseId, node]));
+	for (const role of BUSABASE_CMS_ROLES) {
+		const baseId = baseIds[role];
+		const node = nodeByBaseId.get(baseId);
+		if (!node || node.parentId !== folder.id) throw new BusabaseCmsSchemaDriftError(`Folder metadata maps ${role} to Base "${baseId}", but it is not a direct child`);
+		if (!await source.getBaseById(baseId)) throw new BusabaseCmsSchemaDriftError(`Folder metadata maps ${role} to missing Base "${baseId}"`);
+	}
+};
+const sameStringSet = (actual, expected) => {
+	if (!expected) return true;
+	if (!actual) return false;
+	return [...actual].sort().join("\0") === [...expected].sort().join("\0");
+};
+const mimePatternIsWithin = (actual, expected) => {
+	actual = actual.trim().toLocaleLowerCase();
+	expected = expected.trim().toLocaleLowerCase();
+	if (actual === expected || expected === "*/*") return true;
+	if (!expected.endsWith("/*")) return false;
+	if (actual.endsWith("/*")) return actual === expected;
+	return actual.startsWith(expected.slice(0, -1));
+};
+/** An existing attachment policy may be stricter, but never broader, than the CMS contract. */
+const mimePolicyIsCompatible = (actual, expected) => {
+	if (!expected || expected.length === 0) return true;
+	if (!actual || actual.length === 0) return false;
+	return actual.every((actualPattern) => expected.some((expectedPattern) => mimePatternIsWithin(actualPattern, expectedPattern)));
+};
+const upperBoundIsCompatible = (actual, expected) => {
+	if (expected === void 0) return true;
+	return actual !== void 0 && actual <= expected;
+};
+const allowsLegacyOptionalRequiredField = (expected, context) => context.allowLegacyExisting && (context.schema.legacyOptionalFields ?? []).some((legacy) => legacy.role === context.role && legacy.slug === expected.slug);
+const fieldDrift = (actual, expected, context) => {
+	const drift = [];
+	if (actual.type !== expected.type) drift.push(`type is ${actual.type}, expected ${expected.type}`);
+	if (expected.required && !actual.required && !allowsLegacyOptionalRequiredField(expected, context)) drift.push(`required is ${actual.required}, expected ${expected.required}`);
+	if (expected.options.multiple !== void 0 && actual.options.multiple !== expected.options.multiple) drift.push(`multiple is ${String(actual.options.multiple)}, expected ${expected.options.multiple}`);
+	if (expected.options.targetBaseId && actual.options.targetBaseId !== expected.options.targetBaseId) drift.push(`targetBaseId is ${String(actual.options.targetBaseId)}, expected ${expected.options.targetBaseId}`);
+	if (expected.options.choices) {
+		const actualIds = actual.options.choices?.map((choice) => choice.id);
+		const expectedIds = expected.options.choices.map((choice) => choice.id);
+		if (!sameStringSet(actualIds, expectedIds)) drift.push("select choices do not match");
+	}
+	const attachment = expected.options.attachment;
+	if (attachment) {
+		const actualAttachment = actual.options.attachment;
+		if (!upperBoundIsCompatible(actualAttachment?.maxFiles, attachment.maxFiles)) drift.push("attachment maxFiles is broader than expected");
+		if (!upperBoundIsCompatible(actualAttachment?.maxFileSize, attachment.maxFileSize)) drift.push("attachment maxFileSize is broader than expected");
+		if (!mimePolicyIsCompatible(actualAttachment?.allowedMimeTypes, attachment.allowedMimeTypes)) drift.push("attachment allowedMimeTypes are broader than expected");
+	}
+	return drift;
+};
+const preflightBaseFields = async (source, role, baseIds, schema, allowLegacyExisting) => {
+	const expected = getBusabaseCmsBaseDefinition(role, baseIds, schema.fieldsOverride);
+	const baseId = baseIds[role];
+	if (!baseId) throw new BusabaseCmsSetupError(`Busabase CMS ${role} Base was not resolved`);
+	const base = await source.getBaseById(baseId);
+	if (!base) throw new BusabaseCmsSetupError(`Busabase CMS ${role} Base was not found`);
+	const missing = [];
+	for (const field of expected.fields) {
+		const actual = base.fields.find((candidate) => candidate.slug === field.slug);
+		if (!actual) {
+			missing.push({
+				role,
+				baseId: base.id,
+				field
+			});
+			continue;
+		}
+		const drift = fieldDrift(actual, field, {
+			role,
+			schema,
+			allowLegacyExisting
+		});
+		if (field.type === "relation" && !field.options.targetBaseId) drift.push("target Base cannot be validated before its CMS role is resolved");
+		if (drift.length > 0) throw new BusabaseCmsSchemaDriftError(`Busabase CMS ${role}.${field.slug} schema drift: ${drift.join("; ")}`);
+	}
+	return missing;
+};
+const preflightAllFields = async (source, baseIds, schema, allowLegacyExisting) => {
+	const missing = [];
+	for (const role of BUSABASE_CMS_ROLES) missing.push(...await preflightBaseFields(source, role, baseIds, schema, allowLegacyExisting));
+	return missing;
+};
+const preflightResolvedFields = async (source, baseIds, schema) => {
+	for (const role of BUSABASE_CMS_ROLES) if (baseIds[role]) await preflightBaseFields(source, role, baseIds, schema, true);
+};
+const createMissingFields = async (source, missing, schema) => {
+	for (const { role, baseId, field } of missing) try {
+		const actual = (await source.createField({
+			baseId,
+			...field
+		})).fields.find((candidate) => candidate.slug === field.slug);
+		if (!actual) throw new BusabaseCmsSetupError(`Busabase did not materialize field "${field.slug}" in the ${role} Base`);
+		const drift = fieldDrift(actual, field, {
+			role,
+			schema,
+			allowLegacyExisting: false
+		});
+		if (drift.length > 0) throw new BusabaseCmsSchemaDriftError(`Busabase CMS ${role}.${field.slug} schema drift: ${drift.join("; ")}`);
+	} catch (cause) {
+		if (cause instanceof BusabaseCmsSchemaDriftError) throw cause;
+		const actual = (await source.getBaseById(baseId))?.fields.find((candidate) => candidate.slug === field.slug);
+		if (!actual) throw new BusabaseCmsSetupError(`Could not create field "${field.slug}" in the ${role} Base`, { cause });
+		const drift = fieldDrift(actual, field, {
+			role,
+			schema,
+			allowLegacyExisting: false
+		});
+		if (drift.length > 0) throw new BusabaseCmsSchemaDriftError(`Busabase CMS ${role}.${field.slug} schema drift: ${drift.join("; ")}`, { cause });
+	}
+};
+const findCreatedBase = async (source, folder, role) => {
+	const expectedName = roleAliases[role][0];
+	const expectedSlug = `${folder.slug}-${role}`;
+	const node = (await getDirectBaseNodes(source, folder.id)).find((candidate) => candidate.slug === expectedSlug || normalizeName(candidate.name) === expectedName);
+	return node?.baseId ? source.getBaseById(node.baseId) : null;
+};
+const createMissingBase = async (source, folder, role, baseIds, schema) => {
+	const definition = getBusabaseCmsBaseDefinition(role, baseIds, schema.fieldsOverride);
+	try {
+		const created = await source.createBase({
+			parentNodeId: folder.id,
+			slug: `${folder.slug}-${role}`,
+			name: definition.name,
+			description: definition.description,
+			fields: definition.fields,
+			autoMerge: true
+		});
+		if (!created.id || !created.nodeId) throw new BusabaseCmsSetupError(`Busabase did not immediately materialize the ${role} Base with autoMerge`);
+		return created;
+	} catch (cause) {
+		const concurrent = await findCreatedBase(source, folder, role);
+		if (concurrent) return concurrent;
+		if (cause instanceof BusabaseCmsSetupError) throw cause;
+		throw new BusabaseCmsSetupError(`Could not create the Busabase CMS ${role} Base`, { cause });
+	}
+};
+const saveMetadata = async (source, folder, baseIds, schema) => {
+	const value = {
+		schemaVersion: 1,
+		profile: schema.profile,
+		bases: baseIds
+	};
+	try {
+		await source.updateNodeMetadata({
+			nodeId: folder.id,
+			metadata: { [BUSABASE_CMS_METADATA_KEY]: value }
+		});
+	} catch (cause) {
+		const refreshed = await source.getNode(folder.id);
+		const concurrent = refreshed ? parseMetadata(refreshed) : null;
+		if (concurrent && (concurrent.profile ?? "standard") === schema.profile && BUSABASE_CMS_ROLES.every((role) => concurrent.bases[role] === baseIds[role])) return;
+		throw new BusabaseCmsSetupError("Could not persist the Busabase CMS Base ID mapping", { cause });
+	}
+};
+const resolveFolderBases = async ({ source: rawSource, folderId, lazyCreate, schema }) => {
+	const source = requireProvisioningSource(rawSource);
+	const folder = await getFolder(source, folderId);
+	let nodes = await getDirectBaseNodes(source, folderId);
+	const metadata = parseMetadata(folder);
+	if (metadata) {
+		assertMetadataProfile(folder, metadata, schema.profile);
+		await validateMetadataBases(source, folder, nodes, metadata.bases);
+		const missing = await preflightAllFields(source, metadata.bases, schema, true);
+		if (missing.length > 0 && !lazyCreate) {
+			const first = missing[0];
+			throw new BusabaseCmsSetupError(`Busabase CMS ${first.role} Base is missing required field "${first.field.slug}"; enable lazyCreate to add it`);
+		}
+		if (missing.length > 0) {
+			await createMissingFields(requireLazyProvisioningSource(source), missing, schema);
+			if ((await preflightAllFields(source, metadata.bases, schema, true)).length > 0) throw new BusabaseCmsSetupError("Busabase did not materialize the complete CMS schema");
+		}
+		return metadata.bases;
+	}
+	const resolved = await adoptExistingBases(source, folder, nodes);
+	const createdRoles = /* @__PURE__ */ new Set();
+	await preflightResolvedFields(source, resolved, schema);
+	for (const role of BUSABASE_CMS_ROLES) {
+		if (resolved[role]) continue;
+		if (!lazyCreate) throw new BusabaseCmsSetupError(`Folder "${folder.name}" is missing the ${role} Base; enable lazyCreate to create it`);
+		const writable = requireLazyProvisioningSource(source);
+		resolved[role] = (await createMissingBase(writable, folder, role, resolved, schema)).id;
+		createdRoles.add(role);
+		nodes = await getDirectBaseNodes(source, folderId);
+	}
+	const baseIds = resolved;
+	await validateMetadataBases(source, folder, nodes, baseIds);
+	for (const role of createdRoles) await preflightBaseFields(source, role, baseIds, schema, false);
+	const missing = await preflightAllFields(source, baseIds, schema, true);
+	if (missing.length > 0 && !lazyCreate) {
+		const first = missing[0];
+		throw new BusabaseCmsSetupError(`Busabase CMS ${first.role} Base is missing required field "${first.field.slug}"; enable lazyCreate to add it`);
+	}
+	if (missing.length > 0) {
+		await createMissingFields(requireLazyProvisioningSource(source), missing, schema);
+		if ((await preflightAllFields(source, baseIds, schema, true)).length > 0) throw new BusabaseCmsSetupError("Busabase did not materialize the complete CMS schema");
+	}
+	await saveMetadata(source, folder, baseIds, schema);
+	return baseIds;
+};
+const createBusabaseCmsBaseResolver = (options) => {
+	let resolution;
+	const resolve = () => {
+		resolution ??= resolveFolderBases(options).catch((error) => {
+			resolution = void 0;
+			throw error;
+		});
+		return resolution;
+	};
+	return async (role) => (await resolve())[role];
+};
+//#endregion
+//#region src/source.ts
+const findNode = (nodes, nodeId) => {
+	for (const node of nodes) {
+		if (node.id === nodeId) return node;
+		const child = findNode(node.children, nodeId);
+		if (child) return child;
+	}
+	return null;
+};
+const createBusabaseCmsSource = (client = new Busabase()) => ({
+	getBaseBySlug: async (slug) => client.bases.get({ baseId: slug }),
+	getBaseById: async (baseId) => client.bases.get({ baseId }),
+	getNode: async (nodeId) => findNode(await client.nodes.list(), nodeId),
+	listDirectChildren: async (parentNodeId) => client.nodes.list({
+		parentId: parentNodeId,
+		depth: 1
+	}),
+	createBase: async (input) => {
+		const result = await client.bases.create(input);
+		if (!("fields" in result)) throw new Error("Busabase did not materialize the Base despite autoMerge: true");
+		return result;
+	},
+	createField: async (input) => client.bases.createField(input),
+	updateNodeMetadata: async (input) => client.nodes.updateMetadata(input),
+	listRecordsPage: async (input) => client.records.list(input),
+	getRecordByField: client.records.getByField ? async (input) => client.records.getByField?.(input) ?? null : void 0
+});
+const createBusabaseCmsSourceFromConfig = (config) => createBusabaseCmsSource(new Busabase(config));
+//#endregion
+//#region src/types.ts
+const contentPathSchema = z.string().startsWith("/");
+const optionalTextSchema = z.string().min(1).nullable();
+const rawFieldsSchema = z.record(z.string(), z.unknown());
+const attachmentVOSchema = z.object({
+	id: z.string(),
+	attachmentId: z.string(),
+	assetId: z.string().nullable(),
+	url: z.url(),
+	fileName: z.string(),
+	mimeType: z.string(),
+	size: z.number().nonnegative()
+});
+const attachmentFieldsDTOSchema = z.object({
+	id: z.string(),
+	attachmentId: z.string().optional(),
+	assetId: z.string().optional(),
+	url: z.url(),
+	fileName: z.string().optional(),
+	mimeType: z.string().optional(),
+	size: z.number().nonnegative().optional()
+}).passthrough();
+const relationFieldsDTOSchema = z.union([z.string(), z.array(z.string())]);
+const postFieldsDTOSchema = z.object({
+	path: contentPathSchema,
+	title: z.string().min(1),
+	slug: z.string().min(1),
+	locale: z.string().min(1),
+	status: z.literal("published"),
+	description: z.string().optional(),
+	body: z.string().min(1),
+	"cover-image": z.union([
+		attachmentFieldsDTOSchema,
+		z.array(attachmentFieldsDTOSchema),
+		z.url()
+	]).optional(),
+	attachments: z.array(attachmentFieldsDTOSchema).optional().default([]),
+	author: z.string().optional(),
+	categories: relationFieldsDTOSchema.optional(),
+	tags: relationFieldsDTOSchema.optional(),
+	"published-at": z.string().optional(),
+	"canonical-url": z.url().optional(),
+	"legacy-paths": z.unknown().optional(),
+	"seo-title": z.string().optional(),
+	"seo-description": z.string().optional(),
+	"schema-version": z.number().int().positive().optional().default(1),
+	"updated-at": z.string().optional()
+}).passthrough();
+const postVOSchema = z.object({
+	id: z.string(),
+	path: contentPathSchema,
+	title: z.string(),
+	slug: z.string(),
+	locale: z.string(),
+	status: z.literal("published"),
+	description: optionalTextSchema,
+	body: z.string(),
+	coverImage: attachmentVOSchema.nullable(),
+	attachments: z.array(attachmentVOSchema),
+	author: optionalTextSchema,
+	categoryIds: z.array(z.string()),
+	tagIds: z.array(z.string()),
+	publishedAt: optionalTextSchema,
+	canonicalUrl: optionalTextSchema,
+	legacyPaths: z.array(z.string()),
+	seoTitle: optionalTextSchema,
+	seoDescription: optionalTextSchema,
+	schemaVersion: z.number().int().positive(),
+	updatedAt: z.string(),
+	rawFields: rawFieldsSchema
+});
+const pageFieldsDTOSchema = z.object({
+	path: contentPathSchema,
+	title: z.string().min(1),
+	slug: z.string().min(1),
+	locale: z.string().min(1),
+	status: z.literal("published"),
+	template: z.enum([
+		"standard",
+		"landing",
+		"product",
+		"use-case"
+	]).optional(),
+	body: z.string().min(1),
+	hero: z.unknown().optional(),
+	features: z.unknown().optional(),
+	faqs: z.unknown().optional(),
+	"canonical-url": z.url().optional(),
+	"legacy-paths": z.unknown().optional(),
+	"seo-title": z.string().optional(),
+	"seo-description": z.string().optional(),
+	"schema-version": z.number().int().positive().optional().default(1),
+	"updated-at": z.string().optional()
+}).passthrough();
+const pageVOSchema = z.object({
+	id: z.string(),
+	path: contentPathSchema,
+	title: z.string(),
+	slug: z.string(),
+	locale: z.string(),
+	status: z.literal("published"),
+	template: z.enum([
+		"standard",
+		"landing",
+		"product",
+		"use-case"
+	]).nullable(),
+	body: z.string(),
+	hero: z.unknown(),
+	features: z.unknown(),
+	faqs: z.unknown(),
+	canonicalUrl: optionalTextSchema,
+	legacyPaths: z.array(z.string()),
+	seoTitle: optionalTextSchema,
+	seoDescription: optionalTextSchema,
+	schemaVersion: z.number().int().positive(),
+	updatedAt: z.string(),
+	rawFields: rawFieldsSchema
+});
+const taxonomyFieldsDTOSchema = z.object({
+	name: z.string().min(1),
+	slug: z.string().min(1),
+	locale: z.string().min(1),
+	description: z.string().optional(),
+	"updated-at": z.string().optional()
+}).passthrough();
+const taxonomyVOSchema = z.object({
+	id: z.string(),
+	name: z.string(),
+	slug: z.string(),
+	locale: z.string(),
+	description: optionalTextSchema,
+	updatedAt: z.string(),
+	rawFields: rawFieldsSchema
+});
+const categoryFieldsDTOSchema = taxonomyFieldsDTOSchema;
+const tagFieldsDTOSchema = taxonomyFieldsDTOSchema;
+const categoryVOSchema = taxonomyVOSchema;
+const tagVOSchema = taxonomyVOSchema;
+//#endregion
+//#region src/content.ts
+const DEFAULT_POSTS_BASE_SLUG = "busabase-cms-posts";
+const DEFAULT_PAGES_BASE_SLUG = "busabase-cms-pages";
+const DEFAULT_CATEGORIES_BASE_SLUG = "busabase-cms-categories";
+const DEFAULT_TAGS_BASE_SLUG = "busabase-cms-tags";
+const DEFAULT_PAGE_SIZE = 100;
+const optional = (value) => value ?? null;
+const parseJsonField = (raw, fieldSlug, schema, fallback) => {
+	if (raw === void 0 || raw === null || raw === "") return fallback;
+	let decoded = raw;
+	if (typeof raw === "string") try {
+		decoded = JSON.parse(raw);
+	} catch (cause) {
+		throw new BusabaseCmsError(`Busabase field "${fieldSlug}" contains malformed JSON`, { cause });
+	}
+	const parsed = schema.safeParse(decoded);
+	if (!parsed.success) throw new BusabaseCmsError(`Busabase field "${fieldSlug}" has an invalid shape`, { cause: parsed.error });
+	return parsed.data;
+};
+const attachmentFromFields = (fields) => attachmentVOSchema.parse({
+	id: fields.id,
+	attachmentId: fields.attachmentId ?? fields.id,
+	assetId: fields.assetId ?? null,
+	url: fields.url,
+	fileName: fields.fileName ?? fields.url.split("/").at(-1) ?? "attachment",
+	mimeType: fields.mimeType ?? "application/octet-stream",
+	size: fields.size ?? 0
+});
+const attachmentFromLegacyUrl = (url) => attachmentVOSchema.parse({
+	id: url,
+	attachmentId: url,
+	assetId: null,
+	url,
+	fileName: url.split("/").at(-1) ?? "attachment",
+	mimeType: "application/octet-stream",
+	size: 0
+});
+const normalizeCoverImage = (raw) => {
+	if (!raw) return null;
+	if (typeof raw === "string") return attachmentFromLegacyUrl(raw);
+	const first = Array.isArray(raw) ? raw[0] : raw;
+	return first ? attachmentFromFields(first) : null;
+};
+const normalizeAttachments = (raw) => raw.map(attachmentFromFields);
+const normalizeRelationIds = (raw) => {
+	if (!raw) return [];
+	return [...new Set(Array.isArray(raw) ? raw : [raw])];
+};
+const isPublishedRecord = (record) => record.status === "active" && record.headCommit.payload.status === "published";
+const mapPublishedPostRecord = (record) => {
+	if (!isPublishedRecord(record)) return null;
+	const parsed = postFieldsDTOSchema.safeParse(record.headCommit.payload);
+	if (!parsed.success) throw new BusabaseCmsError(`Published Busabase Post record ${record.id} is invalid`, { cause: parsed.error });
+	const fields = parsed.data;
+	return postVOSchema.parse({
+		id: record.id,
+		path: fields.path,
+		title: fields.title,
+		slug: fields.slug,
+		locale: fields.locale,
+		status: fields.status,
+		description: optional(fields.description),
+		body: fields.body,
+		coverImage: normalizeCoverImage(fields["cover-image"]),
+		attachments: normalizeAttachments(fields.attachments),
+		author: optional(fields.author),
+		categoryIds: normalizeRelationIds(fields.categories),
+		tagIds: normalizeRelationIds(fields.tags),
+		publishedAt: optional(fields["published-at"]),
+		canonicalUrl: optional(fields["canonical-url"]),
+		legacyPaths: parseJsonField(fields["legacy-paths"], "legacy-paths", z.array(z.string()), []),
+		seoTitle: optional(fields["seo-title"]),
+		seoDescription: optional(fields["seo-description"]),
+		schemaVersion: fields["schema-version"],
+		updatedAt: fields["updated-at"] ?? record.updatedAt,
+		rawFields: record.headCommit.payload
+	});
+};
+const mapPublishedPageRecord = (record) => {
+	if (!isPublishedRecord(record)) return null;
+	const parsed = pageFieldsDTOSchema.safeParse(record.headCommit.payload);
+	if (!parsed.success) throw new BusabaseCmsError(`Published Busabase Page record ${record.id} is invalid`, { cause: parsed.error });
+	const fields = parsed.data;
+	return pageVOSchema.parse({
+		id: record.id,
+		path: fields.path,
+		title: fields.title,
+		slug: fields.slug,
+		locale: fields.locale,
+		status: fields.status,
+		template: optional(fields.template),
+		body: fields.body,
+		hero: parseJsonField(fields.hero, "hero", z.unknown(), null),
+		features: parseJsonField(fields.features, "features", z.unknown(), []),
+		faqs: parseJsonField(fields.faqs, "faqs", z.unknown(), []),
+		canonicalUrl: optional(fields["canonical-url"]),
+		legacyPaths: parseJsonField(fields["legacy-paths"], "legacy-paths", z.array(z.string()), []),
+		seoTitle: optional(fields["seo-title"]),
+		seoDescription: optional(fields["seo-description"]),
+		schemaVersion: fields["schema-version"],
+		updatedAt: fields["updated-at"] ?? record.updatedAt,
+		rawFields: record.headCommit.payload
+	});
+};
+const mapTaxonomyRecord = (record, kind) => {
+	if (record.status !== "active") return null;
+	const parsed = (kind === "Category" ? categoryFieldsDTOSchema : tagFieldsDTOSchema).safeParse(record.headCommit.payload);
+	if (!parsed.success) throw new BusabaseCmsError(`Active Busabase ${kind} record ${record.id} is invalid`, { cause: parsed.error });
+	const fields = parsed.data;
+	const value = {
+		id: record.id,
+		name: fields.name,
+		slug: fields.slug,
+		locale: fields.locale,
+		description: optional(fields.description),
+		updatedAt: fields["updated-at"] ?? record.updatedAt,
+		rawFields: record.headCommit.payload
+	};
+	return kind === "Category" ? categoryVOSchema.parse(value) : tagVOSchema.parse(value);
+};
+const mapActiveCategoryRecord = (record) => mapTaxonomyRecord(record, "Category");
+const mapActiveTagRecord = (record) => mapTaxonomyRecord(record, "Tag");
+const resolveOptions = (options) => {
+	const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
+	if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > 100) throw new BusabaseCmsError("pageSize must be an integer between 1 and 100");
+	if (options.source && (options.client || options.config)) throw new BusabaseCmsError("Provide source or client/config, not both");
+	if (options.client && options.config) throw new BusabaseCmsError("Provide client or config, not both");
+	if (options.lazyCreate && !options.folderId) throw new BusabaseCmsError("lazyCreate requires folderId");
+	if (options.source && options.lazyCreate && (!options.source.getBaseById || !options.source.getNode || !options.source.listDirectChildren || !options.source.createBase || !options.source.createField || !options.source.updateNodeMetadata)) throw new BusabaseCmsError("lazyCreate with a custom source requires node, Base, field, and metadata provisioning methods");
+	const source = options.source ?? (options.client ? createBusabaseCmsSource(options.client) : createBusabaseCmsSourceFromConfig(options.config));
+	return {
+		source,
+		resolveBaseId: options.folderId ? createBusabaseCmsBaseResolver({
+			source,
+			folderId: options.folderId,
+			lazyCreate: options.lazyCreate ?? false,
+			schema: {
+				profile: options.schemaProfile ?? "standard",
+				fieldsOverride: options.fieldsOverride,
+				legacyOptionalFields: options.legacyOptionalFields
+			}
+		}) : void 0,
+		baseSlugs: {
+			posts: options.baseSlugs?.posts ?? "busabase-cms-posts",
+			pages: options.baseSlugs?.pages ?? "busabase-cms-pages",
+			categories: options.baseSlugs?.categories ?? "busabase-cms-categories",
+			tags: options.baseSlugs?.tags ?? "busabase-cms-tags"
+		},
+		pageSize,
+		invalidRecords: options.invalidRecords ?? "skip",
+		onInvalidRecord: options.onInvalidRecord
+	};
+};
+const resolveRoleBaseId = async (options, role) => {
+	const baseSlug = options.baseSlugs[role];
+	const baseId = options.resolveBaseId ? await options.resolveBaseId(role) : (await options.source.getBaseBySlug(baseSlug))?.id;
+	if (!baseId) throw new BusabaseCmsError(`Busabase Base "${baseSlug}" was not found`);
+	return baseId;
+};
+/**
+* Point lookup by an exact field value (e.g. `path`, `slug`), scoped to one role's Base.
+* Returns `undefined` — not `null` — when the source has no `getRecordByField` capability,
+* so callers can tell "unsupported, fall back to list+find" apart from "supported, not found".
+*/
+const findRecordByField = async (options, role, fieldSlug, valueText) => {
+	if (!options.source.getRecordByField) return void 0;
+	const baseId = await resolveRoleBaseId(options, role);
+	return options.source.getRecordByField({
+		baseId,
+		fieldSlug,
+		valueText
+	});
+};
+const listAllRecords = async (options, role) => {
+	const baseId = await resolveRoleBaseId(options, role);
+	const records = [];
+	const visitedCursors = /* @__PURE__ */ new Set();
+	let cursor;
+	do {
+		const page = await options.source.listRecordsPage({
+			baseId,
+			limit: options.pageSize,
+			cursor
+		});
+		records.push(...page.records);
+		if (!page.nextCursor) break;
+		if (visitedCursors.has(page.nextCursor)) throw new BusabaseCmsError(`Busabase returned a repeated cursor for Base "${options.baseSlugs[role]}"`);
+		visitedCursors.add(page.nextCursor);
+		cursor = page.nextCursor;
+	} while (cursor);
+	return records;
+};
+const mapValidRecords = (options, records, kind, mapper) => records.flatMap((record) => {
+	try {
+		const content = mapper(record);
+		return content ? [content] : [];
+	} catch (cause) {
+		const error = cause instanceof BusabaseCmsError ? cause : new BusabaseCmsError(`Could not map Busabase record ${record.id}`, { cause });
+		if (options.invalidRecords === "throw") throw error;
+		const issue = {
+			kind,
+			recordId: record.id,
+			error
+		};
+		if (options.onInvalidRecord) options.onInvalidRecord(issue);
+		else console.warn(`[busabase-cms] Skipping invalid ${kind} record ${record.id}`, error);
+		return [];
+	}
+});
+/**
+* Resolve one record by an exact field value. Prefers the source's `getRecordByField`
+* point lookup (a single indexed query); falls back to `list()` + client-side `.find()`
+* when the source doesn't support it (e.g. a demo/test source).
+*/
+const getSingleByField = async (options, role, fieldSlug, valueText, kind, mapper, fallbackList, matches) => {
+	const found = await findRecordByField(options, role, fieldSlug, valueText);
+	if (found !== void 0) {
+		if (!found) return null;
+		const [mapped] = mapValidRecords(options, [found], kind, mapper);
+		return mapped ?? null;
+	}
+	return (await fallbackList()).find(matches) ?? null;
+};
+const createBusabaseCms = (options = {}) => {
+	const resolved = resolveOptions(options);
+	const listPosts = async () => mapValidRecords(resolved, await listAllRecords(resolved, "posts"), "post", mapPublishedPostRecord);
+	const listPages = async () => mapValidRecords(resolved, await listAllRecords(resolved, "pages"), "page", mapPublishedPageRecord);
+	const listCategories = async () => mapValidRecords(resolved, await listAllRecords(resolved, "categories"), "category", mapActiveCategoryRecord);
+	const listTags = async () => mapValidRecords(resolved, await listAllRecords(resolved, "tags"), "tag", mapActiveTagRecord);
+	return {
+		posts: {
+			list: listPosts,
+			getByPath: (path) => getSingleByField(resolved, "posts", "path", path, "post", mapPublishedPostRecord, listPosts, (post) => post.path === path)
+		},
+		pages: {
+			list: listPages,
+			getByPath: (path) => getSingleByField(resolved, "pages", "path", path, "page", mapPublishedPageRecord, listPages, (page) => page.path === path)
+		},
+		categories: {
+			list: listCategories,
+			getBySlug: (slug) => getSingleByField(resolved, "categories", "slug", slug, "category", mapActiveCategoryRecord, listCategories, (category) => category.slug === slug)
+		},
+		tags: {
+			list: listTags,
+			getBySlug: (slug) => getSingleByField(resolved, "tags", "slug", slug, "tag", mapActiveTagRecord, listTags, (tag) => tag.slug === slug)
+		}
+	};
+};
+//#endregion
+export { replaceField as A, createBusabaseCmsSourceFromConfig as C, BUSABASE_CMS_SCHEMA_VERSION as D, BUSABASE_CMS_SCHEMA_PROFILES as E, BusabaseCmsSchemaDriftError as M, BusabaseCmsSetupError as N, getBusabaseCmsBaseDefinition as O, createBusabaseCmsSource as S, BUSABASE_CMS_ROLES as T, postVOSchema as _, createBusabaseCms as a, tagVOSchema as b, mapPublishedPageRecord as c, attachmentVOSchema as d, categoryFieldsDTOSchema as f, postFieldsDTOSchema as g, pageVOSchema as h, DEFAULT_TAGS_BASE_SLUG as i, BusabaseCmsError as j, i18nName as k, mapPublishedPostRecord as l, pageFieldsDTOSchema as m, DEFAULT_PAGES_BASE_SLUG as n, mapActiveCategoryRecord as o, categoryVOSchema as p, DEFAULT_POSTS_BASE_SLUG as r, mapActiveTagRecord as s, DEFAULT_CATEGORIES_BASE_SLUG as t, attachmentFieldsDTOSchema as u, relationFieldsDTOSchema as v, BUSABASE_CMS_METADATA_KEY as w, taxonomyFieldsDTOSchema as x, tagFieldsDTOSchema as y };