@abinnovision/payloadcms-mcpx 2.0.0-beta.9 → 2.1.0-beta.1

package/dist/leases/lease.mjs

@@ -0,0 +1,115 @@
+import { isPlainObject } from "../guards.mjs";
+import { generateApiKey, hashApiKey } from "../api-keys/key.mjs";
+import { APIError, ValidationError } from "payload";
+//#region src/leases/lease.ts
+const LEASE_ID = /^[\w-]{43}$/;
+const NO_REQ = {};
+/**
+* The key prefixes of a kind of lease: waiting leases and the markers of used
+* ones.
+*/ const leasePrefixes = (kind, apiKeyId) => ({
+	prefix: `mcpx-${kind}:${String(apiKeyId)}:`,
+	usedPrefix: `mcpx-${kind}-used:${String(apiKeyId)}:`
+});
+/**
+* What a lease is addressed by: the HMAC of its id, which the row key ends in.
+*/ const leaseHandle = (payload, id) => hashApiKey(payload.secret, id);
+const expOf = (data) => isPlainObject(data) && typeof data["exp"] === "number" ? data["exp"] : 0;
+/**
+* The KV collection slug, when Payload's database KV adapter backs it with a
+* unique `key`, which the single-use claim relies on. `undefined` otherwise.
+*/ const leaseKvSlug = (config) => {
+	const kv = config.kv;
+	const key = kv?.kvCollection?.fields.find((field) => "name" in field && field.name === "key");
+	return key && "unique" in key && key.unique ? kv?.kvCollection?.slug : void 0;
+};
+/**
+* KV rows whose key contains one of `fragments`.
+*/ const leasesMatching = async (payload, slug, fragments) => {
+	const { docs } = await payload.db.find({
+		collection: slug,
+		where: { or: fragments.map((fragment) => ({ key: { like: fragment } })) },
+		limit: 0,
+		pagination: false,
+		req: NO_REQ
+	});
+	return docs;
+};
+/**
+* KV rows whose key starts with one of `prefixes`. `like` matches a
+* substring, so the prefix is checked again here.
+*/ const leasesWith = async (payload, slug, prefixes) => (await leasesMatching(payload, slug, prefixes)).filter((row) => prefixes.some((prefix) => row.key.startsWith(prefix)));
+/**
+* Stores `data` under `prefix` and the HMAC of a fresh id, and returns the id,
+* the only copy of which goes to the client. Expired rows under `prefix` and
+* `usedPrefix` are purged first, and at most `cap` unexpired rows may wait
+* under `prefix`; past that, `capMessage` is thrown with 429.
+*/ const issueLease = async (payload, slug, args) => {
+	const now = Date.now();
+	const rows = await leasesWith(payload, slug, [args.prefix, args.usedPrefix]);
+	const expired = rows.filter((row) => expOf(row.data) <= now);
+	if (expired.length > 0) await payload.db.deleteMany({
+		collection: slug,
+		where: { key: { in: expired.map((row) => row.key) } },
+		req: NO_REQ
+	});
+	if (rows.filter((row) => row.key.startsWith(args.prefix) && expOf(row.data) > now).length >= args.cap) throw new APIError(args.capMessage, 429);
+	const id = generateApiKey();
+	const exp = now + args.ttlMs;
+	await payload.db.create({
+		collection: slug,
+		data: {
+			key: `${args.prefix}${leaseHandle(payload, id)}`,
+			data: {
+				...args.data,
+				exp
+			}
+		},
+		req: NO_REQ
+	});
+	return {
+		id,
+		exp
+	};
+};
+/**
+* Marks the row under `handle` used and removes it. The marker is a
+* unique-key insert, so of two concurrent claims exactly one returns `true`.
+*/ const claimLease = async (payload, slug, prefixes, handle, exp) => {
+	try {
+		await payload.db.create({
+			collection: slug,
+			data: {
+				key: `${prefixes.usedPrefix}${handle}`,
+				data: { exp }
+			},
+			req: NO_REQ
+		});
+	} catch (error) {
+		if (error instanceof ValidationError) return false;
+		throw error;
+	}
+	await payload.db.deleteOne({
+		collection: slug,
+		where: { key: { equals: `${prefixes.prefix}${handle}` } },
+		req: NO_REQ
+	});
+	return true;
+};
+/**
+* The KV slug and key id of the request, which a call that stores a lease
+* needs. Throws where the endpoint would not offer one.
+*/ const leaseContext = (req) => {
+	const slug = leaseKvSlug(req.payload.config);
+	const apiKeyId = req.context.mcpx?.apiKeyId;
+	if (slug === void 0 || apiKeyId === void 0) throw new Error("A lease needs a database KV and a key.");
+	return {
+		slug,
+		apiKeyId
+	};
+};
+/**
+* The data of `row` when it has not expired at `now`, otherwise `undefined`.
+*/ const unexpired = (row, now) => row && expOf(row.data) > now ? row.data : void 0;
+//#endregion
+export { LEASE_ID, NO_REQ, claimLease, issueLease, leaseContext, leaseHandle, leaseKvSlug, leasePrefixes, leasesMatching, leasesWith, unexpired };

package/dist/options.mjs

@@ -1,5 +1,4 @@
 import { isPlainObject } from "./guards.mjs";
-import { BUILTIN_TOOL_NAMES } from "./builtin-tool-names.mjs";
 import "./version.mjs";
 import { InvalidConfiguration } from "payload";
 import { hasDraftsEnabled, hasLocalizeStatusEnabled } from "payload/shared";
@@ -15,12 +14,18 @@ const fail = (message) => {
 /**
 * The same transform the stock MCP plugin uses to derive field names.
 */ const toCamelCase = (value) => value.replace(/[-_\s]+(.)?/g, (_, char) => char ? char.toUpperCase() : "").replace(/^(.)/, (_, char) => char.toLowerCase());
-const assertExposable = (collection, apiKeysSlug) => {
-	const { slug } = collection;
-	if (slug === apiKeysSlug || slug.startsWith("payload-")) fail(`Collection "${slug}" cannot be exposed.`);
-	if (collection.auth) fail(`Auth collection "${slug}" cannot be exposed. Its documents carry credentials.`);
+const assertExposable = (kind, config, apiKeysSlug) => {
+	const { slug } = config;
+	if (slug.startsWith("payload-") || kind === "Collection" && slug === apiKeysSlug) fail(`${kind} "${slug}" cannot be exposed.`);
+	if ("auth" in config && config.auth) fail(`Auth collection "${slug}" cannot be exposed. Its documents carry credentials.`);
 };
 const OPTION_NAMES = [
+	"read",
+	"write",
+	"publish",
+	"delete"
+];
+const GLOBAL_OPTION_NAMES = [
 	"read",
 	"write",
 	"publish"
@@ -34,87 +39,82 @@ const readFlag = (kind, slug, name, value) => {
 	const moved = name === "write" && typeof value === "string" ? REMOVED_WRITE_MODES[value] : void 0;
 	return fail(`${kind} "${slug}" has ${name}: ${JSON.stringify(value)}. ${moved ?? "Use true or false."}`);
 };
-const assertWritable = (kind, config, write) => {
-	if (write === "live" && hasLocalizeStatusEnabled(config)) fail(`${kind} "${config.slug}" has versions.drafts.localizeStatus enabled, which live writes do not support yet. Set publish: false or write: false.`);
+const assertWritable = (kind, config, publish) => {
+	if (publish && hasLocalizeStatusEnabled(config)) fail(`${kind} "${config.slug}" has versions.drafts.localizeStatus enabled, which live writes do not support yet. Set publish: false or write: false.`);
+};
+const normalizeDelete = (kind, config, value) => {
+	if (value !== "unattended") return {
+		delete: readFlag(kind, config.slug, "delete", value) ?? false,
+		deleteUnattended: false
+	};
+	if (!("trash" in config) || !config.trash) fail(`${kind} "${config.slug}" has delete: "unattended" but no trash, so a delete without approval would be permanent. Enable trash or set delete: true.`);
+	return {
+		delete: true,
+		deleteUnattended: true
+	};
 };
 const normalizeCapabilities = (kind, config, raw) => {
 	const { slug } = config;
+	const names = kind === "Global" ? GLOBAL_OPTION_NAMES : OPTION_NAMES;
 	if (raw === false) fail(`${kind} "${slug}" is set to false. Remove the entry to hide the ${kind.toLowerCase()}.`);
-	if (raw !== true && !isPlainObject(raw)) fail(`${kind} "${slug}" has ${JSON.stringify(raw)}. Use true or an object of ${OPTION_NAMES.join(", ")}.`);
+	if (raw !== true && !isPlainObject(raw)) fail(`${kind} "${slug}" has ${JSON.stringify(raw)}. Use true or an object of ${names.join(", ")}.`);
 	const settings = isPlainObject(raw) ? raw : {};
-	const unknownKey = Object.keys(settings).find((key) => !OPTION_NAMES.includes(key));
-	if (unknownKey !== void 0) fail(`${kind} "${slug}" has the unknown option "${unknownKey}". The options are ${OPTION_NAMES.join(", ")}.`);
+	const unknownKey = Object.keys(settings).find((key) => !names.includes(key));
+	if (unknownKey !== void 0) fail(`${kind} "${slug}" has the unknown option "${unknownKey}". The options are ${names.join(", ")}.`);
 	const flag = (name) => readFlag(kind, slug, name, settings[name]);
 	const read = flag("read") ?? true;
-	const write = flag("write") ?? true;
+	const write = flag("write") ?? read;
 	const publish = flag("publish");
 	const hasDrafts = hasDraftsEnabled(config);
 	if (publish === false && write && !hasDrafts) fail(`${kind} "${slug}" has no drafts, so every write goes live. Set write: false or remove publish: false.`);
 	if (publish === true && !hasDrafts) fail(`${kind} "${slug}" has no drafts, so there is nothing to publish. Enable versions.drafts or remove publish: true.`);
+	if (!read && (flag("write") === true || publish === true)) fail(`${kind} "${slug}" has read: false but write or publish on. Writing and publishing need read.`);
 	if (publish === true && !write) fail(`${kind} "${slug}" has publish: true but write: false. Publishing follows write.`);
+	const deleting = normalizeDelete(kind, config, settings["delete"]);
+	if (!read && deleting.delete) fail(`${kind} "${slug}" has read: false but delete on. Deleting needs read.`);
 	return {
 		read,
-		write: write ? publish === false ? "draft" : "live" : false,
+		write,
+		publish: write && publish !== false && hasDrafts,
+		liveWrite: write && !hasDrafts,
 		hasDrafts,
-		hasVersions: read && Boolean(config.versions)
+		hasVersions: read && Boolean(config.versions),
+		...deleting
 	};
 };
-const assertGlobalExposable = (global) => {
-	if (global.slug.startsWith("payload-")) fail(`Global "${global.slug}" cannot be exposed.`);
-};
-const normalizeCollections = (config, options, apiKeysSlug) => {
-	const collections = config.collections ?? [];
+const bySlug = (configs) => new Map(configs.map((config) => [config.slug, config]));
+const normalizeEntities = (kind, configs, entries, apiKeysSlug) => {
 	const fieldNames = /* @__PURE__ */ new Set();
-	return Object.entries(options.collections).flatMap(([slug, raw]) => {
+	return Object.entries(entries).flatMap(([slug, raw]) => {
 		if (raw === void 0) return [];
-		const collection = collections.find((candidate) => candidate.slug === slug);
-		if (!collection) return fail(`Exposed collection "${slug}" does not exist.`);
-		assertExposable(collection, apiKeysSlug);
+		const config = configs.get(slug);
+		if (!config) return fail(`Exposed ${kind.toLowerCase()} "${slug}" does not exist.`);
+		assertExposable(kind, config, apiKeysSlug);
 		const normalized = {
 			slug,
-			...normalizeCapabilities("Collection", collection, raw),
-			isUpload: Boolean(collection.upload),
+			...normalizeCapabilities(kind, config, raw),
+			isUpload: "upload" in config && Boolean(config.upload),
 			fieldName: toCamelCase(slug)
 		};
-		if (normalized.write !== false) {
-			if (collection.timestamps === false) fail(`Collection "${slug}" has timestamps disabled, which write tools need for concurrency checks.`);
-			assertWritable("Collection", collection, normalized.write);
+		if (normalized.write) {
+			if ("timestamps" in config && config.timestamps === false) fail(`Collection "${slug}" has timestamps disabled, which write tools need for concurrency checks.`);
+			assertWritable(kind, config, normalized.publish);
 		}
-		if (fieldNames.has(normalized.fieldName)) fail(`Collection "${slug}" maps to capability field "${normalized.fieldName}", which another exposed collection already uses.`);
-		fieldNames.add(normalized.fieldName);
-		return [normalized];
-	});
-};
-const normalizeGlobals = (config, options) => {
-	const globals = config.globals ?? [];
-	const fieldNames = /* @__PURE__ */ new Set();
-	return Object.entries(options.globals ?? {}).flatMap(([slug, raw]) => {
-		if (raw === void 0) return [];
-		const global = globals.find((candidate) => candidate.slug === slug);
-		if (!global) return fail(`Exposed global "${slug}" does not exist.`);
-		assertGlobalExposable(global);
-		const normalized = {
-			slug,
-			...normalizeCapabilities("Global", global, raw),
-			isUpload: false,
-			fieldName: toCamelCase(slug)
-		};
-		if (normalized.write !== false) assertWritable("Global", global, normalized.write);
-		if (fieldNames.has(normalized.fieldName)) fail(`Global "${slug}" maps to capability field "${normalized.fieldName}", which another exposed global already uses.`);
+		if (fieldNames.has(normalized.fieldName)) fail(`${kind} "${slug}" maps to capability field "${normalized.fieldName}", which another exposed ${kind.toLowerCase()} already uses.`);
 		fieldNames.add(normalized.fieldName);
 		return [normalized];
 	});
 };
-const assertUserCollection = (config, slug) => {
-	const collection = (config.collections ?? []).find((candidate) => candidate.slug === slug);
+const assertUserCollection = (collections, slug) => {
+	const collection = collections.get(slug);
 	if (!collection) fail(`User collection "${slug}" does not exist.`);
-	else if (!collection.auth) fail(`User collection "${slug}" is not an auth collection.`);
+	else if (!("auth" in collection && collection.auth)) fail(`User collection "${slug}" is not an auth collection.`);
 };
-const assertTools = (tools) => {
+const assertTools = (tools, reserved) => {
 	const names = /* @__PURE__ */ new Set();
 	for (const tool of tools) {
 		if (!TOOL_NAME_PATTERN.test(tool.name)) fail(`Tool name "${tool.name}" must match ${String(TOOL_NAME_PATTERN)}.`);
-		if (BUILTIN_TOOL_NAMES.includes(tool.name)) fail(`Tool name "${tool.name}" is reserved for a builtin tool.`);
+		if (reserved.includes(tool.name)) fail(`Tool name "${tool.name}" is reserved for a builtin tool.`);
 		if (names.has(tool.name)) fail(`Tool name "${tool.name}" is used twice.`);
 		names.add(tool.name);
 	}
@@ -131,27 +131,34 @@ const normalizeLimits = (limits) => {
 };
 /**
 * Every problem is an `InvalidConfiguration`, so it fails at startup.
-*/ const normalizeOptions = (config, options) => {
+* `reservedToolNames` are the builtin tool names custom tools must not reuse.
+*/ const normalizeOptions = (config, options, reservedToolNames) => {
 	const apiKeysSlug = options.apiKeys?.slug ?? DEFAULT_API_KEYS_SLUG;
 	const userCollection = options.userCollection ?? config.admin?.user ?? "users";
-	if ((config.collections ?? []).some((c) => c.slug === apiKeysSlug)) fail(`API key collection slug "${apiKeysSlug}" is already taken.`);
-	assertUserCollection(config, userCollection);
+	const collectionConfigs = bySlug(config.collections ?? []);
+	if (collectionConfigs.has(apiKeysSlug)) fail(`API key collection slug "${apiKeysSlug}" is already taken.`);
+	assertUserCollection(collectionConfigs, userCollection);
 	const tools = options.tools ?? [];
-	assertTools(tools);
+	assertTools(tools, reservedToolNames);
+	const collections = normalizeEntities("Collection", collectionConfigs, options.collections, apiKeysSlug);
+	const confirmations = collections.some((entity) => entity.delete);
+	if (confirmations && options.auth?.resolve) fail("delete needs approval on the API key document, which a custom auth.resolve does not support. Remove delete: true or auth.resolve.");
 	return {
-		collections: normalizeCollections(config, options, apiKeysSlug),
-		globals: normalizeGlobals(config, options),
+		collections,
+		globals: normalizeEntities("Global", bySlug(config.globals ?? []), options.globals ?? {}, apiKeysSlug),
 		userCollection,
 		apiKeysSlug,
 		endpointPath: options.endpoint?.path ?? DEFAULT_ENDPOINT_PATH,
 		setupGuide: options.apiKeys?.setupGuide ?? true,
 		limits: normalizeLimits(options.limits),
 		tools,
+		confirmations,
 		auth: options.auth,
 		serverInfo: {
 			name: options.serverInfo?.name ?? "payloadcms-mcpx",
-			version: options.serverInfo?.version ?? "1.0.0"
-		}
+			version: options.serverInfo?.version ?? "2.0.0"
+		},
+		diagnostics: options.diagnostics ?? true
 	};
 };
 //#endregion

package/dist/plugin.d.mts

@@ -1,8 +1,9 @@
 import { McpxPluginOptions } from "./types.mjs";
 //#region src/plugin.d.ts
 /**
- * Mounts the MCP endpoint, adds the API key collection and installs the
- * draft guard on every collection and global.
+ * Mounts the MCP, upload and download endpoints, and the confirmation
+ * endpoints where a collection exposes `delete`. Adds the API key collection
+ * and installs the draft guard on every collection and global.
  */
 export declare const mcpxPlugin: (options: McpxPluginOptions) => import("payload").Plugin;
 //#endregion

package/dist/plugin.mjs

@@ -1,17 +1,21 @@
 import { createApiKeysCollection } from "./api-keys/collection.mjs";
+import { BUILTIN_TOOLS } from "./tools/builtin.mjs";
+import { confirmationEndpoints } from "./endpoint/confirmations.mjs";
 import { createMcpxHandler, methodNotAllowed } from "./endpoint/handler.mjs";
+import { createDownloadHandler, createUploadHandler } from "./endpoint/upload.mjs";
 import { normalizeOptions } from "./options.mjs";
 import { installDraftGuards, installGlobalDraftGuards } from "./write/draft-guard.mjs";
 import { definePlugin } from "payload";
 //#region src/plugin.ts
 /**
-* Mounts the MCP endpoint, adds the API key collection and installs the
-* draft guard on every collection and global.
+* Mounts the MCP, upload and download endpoints, and the confirmation
+* endpoints where a collection exposes `delete`. Adds the API key collection
+* and installs the draft guard on every collection and global.
 */ const mcpxPlugin = definePlugin({
 	slug: "@abinnovision/payloadcms-mcpx",
 	order: 100,
 	plugin: ({ config, plugins: _plugins, ...options }) => {
-		const normalized = normalizeOptions(config, options);
+		const normalized = normalizeOptions(config, options, BUILTIN_TOOLS.map((tool) => tool.name));
 		const apiKeys = createApiKeysCollection(normalized);
 		const apiKeysCollection = options.apiKeys?.overrideCollection?.(apiKeys) ?? apiKeys;
 		return {
@@ -34,7 +38,18 @@ import { definePlugin } from "payload";
 					path: normalized.endpointPath,
 					method: "delete",
 					handler: methodNotAllowed
-				}
+				},
+				{
+					path: `${normalized.endpointPath}/upload`,
+					method: "put",
+					handler: createUploadHandler(normalized)
+				},
+				{
+					path: `${normalized.endpointPath}/file`,
+					method: "get",
+					handler: createDownloadHandler(normalized)
+				},
+				...normalized.confirmations ? confirmationEndpoints(normalized) : []
 			]
 		};
 	}

package/dist/request.mjs

@@ -3,5 +3,9 @@
 * Whether `req` came through the MCP endpoint, which stamps `req.context.mcpx`.
 * The stamp follows `req` into every local API call, including custom tools.
 */ const isMcpxRequest = (req) => req.context.mcpx !== void 0;
+/**
+* The origin links to this server use: `serverURL` when set, else that of the
+* MCP request.
+*/ const publicOrigin = (req) => req.payload.config.serverURL || new URL(req.url ?? "").origin;
 //#endregion
-export { isMcpxRequest };
+export { isMcpxRequest, publicOrigin };

package/dist/result.mjs

@@ -1,4 +1,14 @@
 //#region src/result.ts
+/**
+* The JSON of a result's first text block. Other text comes back as `{ text }`.
+*/ const parseResult = (result) => {
+	const [first] = result.content;
+	try {
+		return first?.type === "text" ? JSON.parse(first.text) : {};
+	} catch {
+		return { text: first?.type === "text" ? first.text : void 0 };
+	}
+};
 const jsonResult = (value) => ({ content: [{
 	type: "text",
 	text: JSON.stringify(value)
@@ -17,4 +27,4 @@ const jsonResult = (value) => ({ content: [{
 	isError: true
 });
 //#endregion
-export { errorResult, jsonResult };
+export { errorResult, jsonResult, parseResult };

package/dist/schema/admin-hidden.mjs

@@ -1,5 +1,5 @@
 import { isPlainObject } from "../guards.mjs";
-import { RESERVED_FIELD_NAMES, ROW_KEYS, blockOf, blockSlugsOf, isAdminHidden, schemaOf } from "./walk.mjs";
+import { RESERVED_FIELD_NAMES, ROW_KEYS, adminFlag, blockForRow, blockOf, blockSlugsOf, schemaOf } from "./walk.mjs";
 //#region src/schema/admin-hidden.ts
 const UPLOAD_BASE_FIELDS = /* @__PURE__ */ new Set([
 	"filename",
@@ -22,7 +22,7 @@ const stripFields = (config, fields, doc, exempt = NONE) => {
 	const result = { ...doc };
 	for (const field of fields) {
 		if (!("name" in field) || exempt.has(field.name) || isPayloadKey(field.name) || !Object.hasOwn(result, field.name)) continue;
-		if (isAdminHidden(field)) Reflect.deleteProperty(result, field.name);
+		if (adminFlag(field, "hidden")) Reflect.deleteProperty(result, field.name);
 		else result[field.name] = stripValue(config, field, result[field.name]);
 	}
 	return result;
@@ -45,7 +45,7 @@ const stripValue = (config, field, value) => {
 		case "tab": return isPlainObject(value) ? stripFields(config, field.flattenedFields, value) : value;
 		case "array": return mapEach(value, (row) => isPlainObject(row) ? stripFields(config, field.flattenedFields, row) : row);
 		case "blocks": return mapEach(value, (row) => {
-			const block = isPlainObject(row) && typeof row["blockType"] === "string" ? blockOf(config, field, row["blockType"]) : void 0;
+			const block = blockForRow(config, field, row);
 			return block && isPlainObject(row) ? stripFields(config, block.flattenedFields, row) : row;
 		});
 		case "relationship":
@@ -76,7 +76,7 @@ const stripValue = (config, field, value) => {
 		const matches = fields.filter((field) => "name" in field && field.name === segment);
 		if (matches.length === 0) return locales.includes(segment) ? walk(fields, rest) : false;
 		return matches.some((field) => {
-			if (isAdminHidden(field)) return true;
+			if (adminFlag(field, "hidden")) return true;
 			if (field.type === "group" || field.type === "tab" || field.type === "array") return walk(field.flattenedFields, rest);
 			return field.type === "blocks" && blockSlugsOf(field).some((slug) => {
 				const block = blockOf(config, field, slug);

package/dist/schema/describe.mjs

@@ -1,25 +1,22 @@
+import { SchemaError } from "./errors.mjs";
 import { lexicalSubSchema, subSchemaNodeTypes } from "./lexical.mjs";
 import { joinPath, splitPath } from "./path.mjs";
 import { translateAny } from "../i18n.mjs";
-import { blockOf, blockSlugsOf, describeFields, findBlocksField, findRichTextField, schemaOf } from "./walk.mjs";
-import { SchemaError } from "./errors.mjs";
+import { blockSlugsOf, describeFields, findFieldAt, longestMatch, requireBlock, schemaOf } from "./walk.mjs";
 //#region src/schema/describe.ts
-const matchSchemaSegments = (descriptors, remaining) => descriptors.map((descriptor) => splitPath(descriptor.path)).filter((parts) => parts.every((part, offset) => part === remaining[offset])).sort((left, right) => right.length - left.length)[0];
 const stepThroughBlocks = ({ config, fields, match, remaining }) => {
-	const field = findBlocksField(fields, match);
+	const field = findFieldAt(fields, match, "blocks");
 	if (!field) throw new Error(`"${joinPath(match)}" could not be resolved.`);
 	const slug = remaining.at(match.length);
 	if (slug === void 0) throw new SchemaError(`"${joinPath(match)}" is a blocks field; append one of: ${blockSlugsOf(field).join(", ")}`);
-	const block = blockOf(config, field, slug);
-	if (!block) throw new SchemaError(`"${slug}" is not allowed at "${joinPath(match)}". Allowed: ${blockSlugsOf(field).join(", ")}`);
 	return {
 		blockType: slug,
-		fields: block.flattenedFields,
+		fields: requireBlock(config, field, slug, joinPath(match)).flattenedFields,
 		rest: remaining.slice(match.length + 1)
 	};
 };
 const stepThroughLexical = ({ config, fields, match, remaining }) => {
-	const field = findRichTextField(fields, match);
+	const field = findFieldAt(fields, match, "richText");
 	if (!field) throw new Error(`"${joinPath(match)}" could not be resolved.`);
 	const available = subSchemaNodeTypes(field).join(", ") || "none";
 	const nodeType = remaining.at(match.length);
@@ -32,13 +29,10 @@ const stepThroughLexical = ({ config, fields, match, remaining }) => {
 		rest: remaining.slice(match.length + 1)
 	};
 	const slug = remaining.at(match.length + 1);
-	const slugs = blockSlugsOf(sub.blocksField).join(", ");
-	if (slug === void 0) throw new SchemaError(`"${reached}" selects a block; append one of: ${slugs}`);
-	const block = blockOf(config, sub.blocksField, slug);
-	if (!block) throw new SchemaError(`"${slug}" is not allowed at "${reached}". Allowed: ${slugs}`);
+	if (slug === void 0) throw new SchemaError(`"${reached}" selects a block; append one of: ${blockSlugsOf(sub.blocksField).join(", ")}`);
 	return {
 		blockType: slug,
-		fields: block.flattenedFields,
+		fields: requireBlock(config, sub.blocksField, slug, reached).flattenedFields,
 		rest: remaining.slice(match.length + 2)
 	};
 };
@@ -48,15 +42,15 @@ const fieldsAtSchemaPath = (config, target, schemaPath) => {
 	let remaining = splitPath(schemaPath);
 	while (remaining.length > 0) {
 		const descendable = describeFields(fields).filter((descriptor) => descriptor.type === "blocks" || descriptor.type === "richText");
-		const match = matchSchemaSegments(descendable, remaining);
-		if (!match) throw new SchemaError(`"${joinPath(remaining)}" does not address a blocks or rich text field. Available here: ${descendable.map((descriptor) => descriptor.path).join(", ") || "none"}`);
+		const found = longestMatch(descendable, remaining, (part, segment) => part === segment);
+		if (!found) throw new SchemaError(`"${joinPath(remaining)}" does not address a blocks or rich text field. Available here: ${descendable.map((descriptor) => descriptor.path).join(", ") || "none"}`);
 		const at = {
 			config,
 			fields,
-			match,
+			match: found.parts,
 			remaining
 		};
-		const step = findBlocksField(fields, match) === void 0 ? stepThroughLexical(at) : stepThroughBlocks(at);
+		const step = found.descriptor.type === "blocks" ? stepThroughBlocks(at) : stepThroughLexical(at);
 		blockType = step.blockType;
 		fields = step.fields;
 		remaining = step.rest;
@@ -69,7 +63,7 @@ const fieldsAtSchemaPath = (config, target, schemaPath) => {
 const branchesOf = (fields, descriptor, schemaPath) => {
 	const base = `${schemaPath}${descriptor.path}`;
 	if (descriptor.type === "richText") {
-		const field = findRichTextField(fields, splitPath(descriptor.path));
+		const field = findFieldAt(fields, splitPath(descriptor.path), "richText");
 		if (!field) return [];
 		return subSchemaNodeTypes(field).flatMap((nodeType) => {
 			const sub = lexicalSubSchema(field, nodeType);

package/dist/schema/index.mjs

@@ -1,11 +1,10 @@
-import { REQUIRED_NODE_PROPERTIES, ROOT_PROPERTIES, allowedNodeTypes, constrainsFields, lexicalSubSchema, nodeOptions, nodeProblems, nodePropertiesFor, propertyProblem, rootProblems, subSchemaNodeTypes } from "./lexical.mjs";
-import { JSON_POINTER_PATTERN, isIndexSegment, joinPath, pointerFromPayloadPath, prototypeSegmentProblem, splitPath } from "./path.mjs";
-import { RESERVED_FIELD_NAMES, ROW_KEYS, blockOf, blockSlugsOf, describeAddressableFields, describeFields, descriptorsUnder, findBlocksField, findRichTextField, isAdminHidden, schemaOf } from "./walk.mjs";
-import { addressesAdminHidden, stripAdminHidden } from "./admin-hidden.mjs";
 import { SchemaError } from "./errors.mjs";
+import { editorRoot, nodePropertiesFor } from "./lexical.mjs";
+import { JSON_POINTER_PATTERN, isIndexSegment, parentPointer, pointerFromPayloadPath, prototypeSegmentProblem, splitPath } from "./path.mjs";
+import { RESERVED_FIELD_NAMES, ROW_KEYS, blockForRow, classifyKey, descriptorsUnder, findFieldAt } from "./walk.mjs";
+import { addressesAdminHidden, stripAdminHidden } from "./admin-hidden.mjs";
 import { nodeDescriber, reachableSchemaPaths } from "./describe.mjs";
-import { resolveLexicalPointer } from "./lexical-pointer.mjs";
 import { lexicalOutline } from "./outline.mjs";
 import { resolveDataPointer } from "./pointer.mjs";
 import { EMPTY_ROOT, validateWriteValue } from "./shape.mjs";
-export { EMPTY_ROOT, JSON_POINTER_PATTERN, REQUIRED_NODE_PROPERTIES, RESERVED_FIELD_NAMES, ROOT_PROPERTIES, ROW_KEYS, SchemaError, addressesAdminHidden, allowedNodeTypes, blockOf, blockSlugsOf, constrainsFields, describeAddressableFields, describeFields, descriptorsUnder, findBlocksField, findRichTextField, isAdminHidden, isIndexSegment, joinPath, lexicalOutline, lexicalSubSchema, nodeDescriber, nodeOptions, nodeProblems, nodePropertiesFor, pointerFromPayloadPath, propertyProblem, prototypeSegmentProblem, reachableSchemaPaths, resolveDataPointer, resolveLexicalPointer, rootProblems, schemaOf, splitPath, stripAdminHidden, subSchemaNodeTypes, validateWriteValue };
+export { EMPTY_ROOT, JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, ROW_KEYS, SchemaError, addressesAdminHidden, blockForRow, classifyKey, descriptorsUnder, editorRoot, findFieldAt, isIndexSegment, lexicalOutline, nodeDescriber, nodePropertiesFor, parentPointer, pointerFromPayloadPath, prototypeSegmentProblem, reachableSchemaPaths, resolveDataPointer, splitPath, stripAdminHidden, validateWriteValue };

package/dist/schema/lexical-pointer.mjs

@@ -1,8 +1,8 @@
-import { isPlainObject } from "../guards.mjs";
-import { lexicalSubSchema, subSchemaNodeTypes } from "./lexical.mjs";
+import { isPlainObject, propOf } from "../guards.mjs";
+import { SchemaError } from "./errors.mjs";
+import { editorRoot, lexicalSubSchema, subSchemaNodeTypes } from "./lexical.mjs";
 import { isIndexSegment, joinPath } from "./path.mjs";
 import { blockOf, blockSlugsOf } from "./walk.mjs";
-import { SchemaError } from "./errors.mjs";
 //#region src/schema/lexical-pointer.ts
 const stepIntoFields = (at) => {
 	const { addedValue, config, field, node, nodeType, rest } = at;
@@ -15,8 +15,7 @@ const stepIntoFields = (at) => {
 		kind: "fields",
 		rest
 	};
-	const added = addedValue?.fields;
-	const slug = (isPlainObject(data) ? data["blockType"] : void 0) ?? (isPlainObject(added) ? added["blockType"] : void 0);
+	const slug = propOf(data, "blockType") ?? propOf(propOf(addedValue, "fields"), "blockType");
 	if (slug === void 0) throw new SchemaError(`Cannot tell which block a "${nodeType}" node holds. Supply a "blockType" on the value, one of: ${blockSlugsOf(sub.blocksField).join(", ")}`);
 	if (typeof slug !== "string") throw new SchemaError(`"blockType" must be a string naming a block in a "${nodeType}" node here. Allowed: ${blockSlugsOf(sub.blocksField).join(", ")}`);
 	const block = blockOf(config, sub.blocksField, slug);
@@ -41,10 +40,11 @@ const stepIntoFields = (at) => {
 		descriptor,
 		field
 	};
-	if (!isPlainObject(state) || !isPlainObject(state["root"])) throw new SchemaError(`"${descriptor.path}" holds no editor state yet. Write the whole field once, then address positions inside it.`);
+	const root = editorRoot(state);
+	if (!root) throw new SchemaError(`"${descriptor.path}" holds no editor state yet. Write the whole field once, then address positions inside it.`);
 	const [entry, ...rest] = at.segments;
 	if (entry !== "root") throw new SchemaError(`"${String(entry)}" is not a position in a rich text field. An editor state is entered at "root", e.g. "${descriptor.path}/root/children/0". getDocument with "outline" lists every position this field holds.`);
-	let node = state["root"];
+	let node = root;
 	let nodeType = "root";
 	let segments = rest;
 	let walked = ["root"];
@@ -73,7 +73,7 @@ const stepIntoFields = (at) => {
 			if (!isIndexSegment(index)) throw new SchemaError(`"${descriptor.path}${joinPath([...walked, "children"])}" is a list; "${index}" is not an index. getDocument with "outline" reports the pointer of each node in it.`);
 			const children = node?.["children"];
 			const child = Array.isArray(children) && index !== "-" ? children[Number(index)] : void 0;
-			const type = isPlainObject(child) ? child["type"] : addedValue?.type;
+			const type = isPlainObject(child) ? child["type"] : propOf(addedValue, "type");
 			if (typeof type !== "string") {
 				if (beyond.length === 0) return {
 					kind: "position",

package/dist/schema/lexical.mjs

@@ -1,4 +1,4 @@
-import { isPlainObject, ownValue } from "../guards.mjs";
+import { isPlainObject, ownValue, propOf } from "../guards.mjs";
 import { flattenAllFields } from "payload";
 //#region src/schema/lexical.ts
 const LEXICAL_CORE_NODES = [
@@ -148,6 +148,16 @@ const UNIVERSAL_PROPERTIES = { version: "number" };
 	}
 };
 /**
+* The `root` node of an editor state, if it has one.
+*/ const editorRoot = (state) => {
+	const root = propOf(state, "root");
+	return isPlainObject(root) ? root : void 0;
+};
+const constraintsFor = (type) => ({
+	...UNIVERSAL_PROPERTIES,
+	...ownValue(REQUIRED_NODE_PROPERTIES, type)
+});
+/**
 * Whether the table already says what a node type's `fields` must be, so the
 * sub-field walk does not report the same problem twice.
 */ const constrainsFields = (type) => "fields" in (ownValue(REQUIRED_NODE_PROPERTIES, type) ?? {});
@@ -159,8 +169,7 @@ const describeConstraints = (constraints) => Object.fromEntries(Object.entries(c
 * {@link UNIVERSAL_PROPERTIES} omits it: the validator finds the entry by
 * `type` and so never reports it missing, but a client must still write one.
 */ const nodePropertiesFor = (types) => Object.fromEntries([...new Set(types)].sort().map((type) => [type, describeConstraints(type === "root" ? ROOT_PROPERTIES : {
-	...ownValue(REQUIRED_NODE_PROPERTIES, type),
-	...UNIVERSAL_PROPERTIES,
+	...constraintsFor(type),
 	type: "string"
 })]));
 const check = (node, constraints) => {
@@ -177,10 +186,7 @@ const check = (node, constraints) => {
 	problems.rejected.sort((left, right) => left.property.localeCompare(right.property));
 	return problems;
 };
-const nodeProblems = (node) => check(node, {
-	...UNIVERSAL_PROPERTIES,
-	...ownValue(REQUIRED_NODE_PROPERTIES, node["type"])
-});
+const nodeProblems = (node) => check(node, constraintsFor(node["type"]));
 /**
 * The root is the one node Payload describes itself, down to refusing an
 * unknown property, so it is checked against that description instead of the
@@ -194,11 +200,7 @@ const nodeProblems = (node) => check(node, {
 * instead of a whole node. Absent where the table says nothing, matching the
 * node walk: a project's own node may carry any property.
 */ const propertyProblem = (nodeType, property, value) => {
-	const constraints = nodeType === "root" ? ROOT_PROPERTIES : {
-		...UNIVERSAL_PROPERTIES,
-		...ownValue(REQUIRED_NODE_PROPERTIES, nodeType)
-	};
-	const constraint = ownValue(constraints, property);
+	const constraint = ownValue(nodeType === "root" ? ROOT_PROPERTIES : constraintsFor(nodeType), property);
 	return constraint === void 0 || accepts(constraint, value) ? void 0 : { needs: needs(constraint) };
 };
 const NODE_OPTION_SOURCES = [{
@@ -233,4 +235,4 @@ const stringList = (value) => Array.isArray(value) && value.every((entry) => typ
 	return entries.length > 0 ? Object.fromEntries(entries) : void 0;
 };
 //#endregion
-export { REQUIRED_NODE_PROPERTIES, ROOT_PROPERTIES, allowedNodeTypes, constrainsFields, lexicalSubSchema, nodeOptions, nodeProblems, nodePropertiesFor, propertyProblem, rootProblems, subSchemaNodeTypes };
+export { REQUIRED_NODE_PROPERTIES, ROOT_PROPERTIES, allowedNodeTypes, constrainsFields, editorRoot, lexicalSubSchema, nodeOptions, nodeProblems, nodePropertiesFor, propertyProblem, rootProblems, subSchemaNodeTypes };