@abinnovision/payloadcms-mcpx 2.0.0-beta.19 → 2.0.0-beta.20

package/dist/grants/grant.mjs

@@ -1,14 +1,21 @@
 import { isPlainObject } from "../guards.mjs";
-import { hashApiKey } from "../api-keys/key.mjs";
+import { generateApiKey, hashApiKey } from "../api-keys/key.mjs";
 import { APIError, ValidationError } from "payload";
-import crypto from "node:crypto";
 //#region src/grants/grant.ts
 const GRANT_TTL_MS = 3e5;
 const GRANTS_PER_KEY = 10;
-const GRANT_ID = /^[\w-]{43}$/;
+const ROW_ID = /^[\w-]{43}$/;
 const NO_REQ = {};
-const grantPrefix = (apiKeyId) => `mcpx-grant:${String(apiKeyId)}:`;
-const usedPrefix = (apiKeyId) => `mcpx-grant-used:${String(apiKeyId)}:`;
+/**
+* The key prefixes of a kind of row: waiting rows and the markers of used
+* ones.
+*/ const rowPrefixes = (kind, apiKeyId) => ({
+	prefix: `mcpx-${kind}:${String(apiKeyId)}:`,
+	usedPrefix: `mcpx-${kind}-used:${String(apiKeyId)}:`
+});
+/**
+* What a row is addressed by: the HMAC of its id, which the row key ends in.
+*/ const rowHandle = (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
@@ -49,12 +56,12 @@ const expOf = (data) => isPlainObject(data) && typeof data["exp"] === "number" ?
 		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 = crypto.randomBytes(32).toString("base64url");
+	const id = generateApiKey();
 	const exp = now + args.ttlMs;
 	await payload.db.create({
 		collection: slug,
 		data: {
-			key: `${args.prefix}${hashApiKey(payload.secret, id)}`,
+			key: `${args.prefix}${rowHandle(payload, id)}`,
 			data: {
 				...args.data,
 				exp
@@ -68,52 +75,63 @@ const expOf = (data) => isPlainObject(data) && typeof data["exp"] === "number" ?
 	};
 };
 /**
-* Stores a grant and returns its id. A key may hold at most
-* {@link GRANTS_PER_KEY} grants.
-*/ const issueGrant = async (payload, slug, grant) => {
-	const { id, exp } = await issueRow(payload, slug, {
-		prefix: grantPrefix(grant.apiKeyId),
-		usedPrefix: usedPrefix(grant.apiKeyId),
-		cap: GRANTS_PER_KEY,
-		capMessage: `This key already has ${String(GRANTS_PER_KEY)} uploads or downloads waiting. Use or abandon them first; each expires 5 minutes after it was issued.`,
-		ttlMs: GRANT_TTL_MS,
-		data: grant
-	});
-	return {
-		grantId: id,
-		exp
-	};
-};
-/**
-* Loads the grant for `grantId` and marks it used, or returns `undefined` for
-* a malformed, unknown, expired or used one. The marker is a unique-key
-* insert, so of two concurrent claims exactly one succeeds. A malformed id
-* is refused before any database read.
-*/ const claimGrant = async (payload, slug, grantId) => {
-	if (!GRANT_ID.test(grantId)) return;
-	const hash = hashApiKey(payload.secret, grantId);
-	const row = (await findRows(payload, slug, [hash])).find((candidate) => candidate.key.startsWith("mcpx-grant:") && candidate.key.endsWith(`:${hash}`));
-	const grant = row?.data;
-	if (!row || !isPlainObject(grant) || row.key !== `${grantPrefix(grant.apiKeyId)}${hash}` || expOf(grant) <= Date.now()) return;
+* 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 claimRow = async (payload, slug, prefixes, handle, exp) => {
 	try {
 		await payload.db.create({
 			collection: slug,
 			data: {
-				key: `${usedPrefix(grant.apiKeyId)}${hash}`,
-				data: { exp: grant.exp }
+				key: `${prefixes.usedPrefix}${handle}`,
+				data: { exp }
 			},
 			req: NO_REQ
 		});
 	} catch (error) {
-		if (error instanceof ValidationError) return;
+		if (error instanceof ValidationError) return false;
 		throw error;
 	}
 	await payload.db.deleteOne({
 		collection: slug,
-		where: { key: { equals: row.key } },
+		where: { key: { equals: `${prefixes.prefix}${handle}` } },
 		req: NO_REQ
 	});
-	return grant;
+	return true;
+};
+/**
+* The KV slug and key id of the request, which a call that stores a grant or
+* a confirmation needs. Throws where the endpoint would not offer one.
+*/ const grantContext = (req) => {
+	const slug = grantKvSlug(req.payload.config);
+	const apiKeyId = req.context.mcpx?.apiKeyId;
+	if (slug === void 0 || apiKeyId === void 0) throw new Error("A grant or confirmation needs a database KV and a key.");
+	return {
+		slug,
+		apiKeyId
+	};
+};
+/**
+* Stores a grant and returns its id. A key may hold at most
+* {@link GRANTS_PER_KEY} grants.
+*/ const issueGrant = async (payload, slug, grant) => await issueRow(payload, slug, {
+	...rowPrefixes("grant", grant.apiKeyId),
+	cap: GRANTS_PER_KEY,
+	capMessage: `This key already has ${String(GRANTS_PER_KEY)} uploads or downloads waiting. Use or abandon them first; each expires 5 minutes after it was issued.`,
+	ttlMs: GRANT_TTL_MS,
+	data: grant
+});
+/**
+* Loads the grant for `grantId` and marks it used, or returns `undefined` for
+* a malformed, unknown, expired or used one. A malformed id is refused before
+* any database read.
+*/ const claimGrant = async (payload, slug, grantId) => {
+	if (!ROW_ID.test(grantId)) return;
+	const handle = rowHandle(payload, grantId);
+	const row = (await findRows(payload, slug, [handle])).find((candidate) => candidate.key.startsWith("mcpx-grant:") && candidate.key.endsWith(`:${handle}`));
+	const grant = row?.data;
+	if (!row || !isPlainObject(grant) || expOf(grant) <= Date.now()) return;
+	const prefixes = rowPrefixes("grant", grant.apiKeyId);
+	return row.key === `${prefixes.prefix}${handle}` && await claimRow(payload, slug, prefixes, handle, grant.exp) ? grant : void 0;
 };
 //#endregion
-export { GRANT_ID, NO_REQ, claimGrant, expOf, grantKvSlug, issueGrant, issueRow, rowsWith };
+export { NO_REQ, ROW_ID, claimGrant, claimRow, expOf, grantContext, grantKvSlug, issueGrant, issueRow, rowHandle, rowPrefixes, rowsWith };

package/dist/guards.mjs

@@ -1,7 +1,14 @@
 //#region src/guards.ts
 const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /**
+* A property of a plain object, `undefined` for any other value.
+*/ const propOf = (value, key) => isPlainObject(value) ? value[key] : void 0;
+/**
 * An own property only, so a client-chosen key never reads the prototype.
 */ const ownValue = (record, key) => record !== void 0 && Object.hasOwn(record, key) ? record[key] : void 0;
+/**
+* The entries whose value is not `undefined`, for spreading optional arguments
+* into a call.
+*/ const definedProps = (props) => Object.fromEntries(Object.entries(props).filter(([, value]) => value !== void 0));
 //#endregion
-export { isPlainObject, ownValue };
+export { definedProps, isPlainObject, ownValue, propOf };

package/dist/index.d.mts

@@ -1,8 +1,8 @@
 import { DocumentId } from "./entity.mjs";
-import { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxScopeSlugs, McpxTool, McpxToolExtra, McpxToolScope, McpxWriteMode } from "./types.mjs";
+import { McpxAnyTool, McpxAuthResult, McpxCollectionOptions, McpxEntityCapabilities, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxScopeSlugs, McpxTool, McpxToolExtra, McpxToolScope } from "./types.mjs";
 import { defineMcpxTool } from "./define-tool.mjs";
 import { mcpxPlugin } from "./plugin.mjs";
 import { isMcpxRequest } from "./request.mjs";
 import { errorResult, jsonResult } from "./result.mjs";
 import { mcpxReadRequest } from "./tools/read-request.mjs";
-export { type McpxAnyTool, type McpxAuthResult, type McpxCollectionCapabilities, type McpxCollectionOptions, type DocumentId as McpxDocumentId, type McpxExposedEntity, type McpxGlobalOptions, type McpxPluginOptions, type McpxRequestContext, type McpxResolvedCapabilities, type McpxScopeSlugs, type McpxTool, type McpxToolExtra, type McpxToolScope, type McpxWriteMode, defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin, mcpxReadRequest };
+export { type McpxAnyTool, type McpxAuthResult, type McpxCollectionOptions, type DocumentId as McpxDocumentId, type McpxEntityCapabilities, type McpxExposedEntity, type McpxGlobalOptions, type McpxPluginOptions, type McpxRequestContext, type McpxResolvedCapabilities, type McpxScopeSlugs, type McpxTool, type McpxToolExtra, type McpxToolScope, defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin, mcpxReadRequest };

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { defineMcpxTool } from "./define-tool.mjs";
+import { isMcpxRequest } from "./request.mjs";
 import { errorResult, jsonResult } from "./result.mjs";
 import { mcpxReadRequest } from "./tools/read-request.mjs";
-import { isMcpxRequest } from "./request.mjs";
 import { mcpxPlugin } from "./plugin.mjs";
 export { defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin, mcpxReadRequest };

package/dist/options.mjs

@@ -1,6 +1,5 @@
 import { isPlainObject } from "./guards.mjs";
 import "./version.mjs";
-import { BUILTIN_TOOL_NAMES } from "./builtin-tool-names.mjs";
 import { InvalidConfiguration } from "payload";
 import { hasDraftsEnabled, hasLocalizeStatusEnabled } from "payload/shared";
 //#region src/options.ts
@@ -15,10 +14,10 @@ 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",
@@ -40,8 +39,8 @@ 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 {
@@ -75,68 +74,47 @@ const normalizeCapabilities = (kind, config, raw) => {
 	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),
 		...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);
 	}
@@ -153,19 +131,21 @@ 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);
-	const collections = normalizeCollections(config, options, apiKeysSlug);
+	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,
-		globals: normalizeGlobals(config, options),
+		globals: normalizeEntities("Global", bySlug(config.globals ?? []), options.globals ?? {}, apiKeysSlug),
 		userCollection,
 		apiKeysSlug,
 		endpointPath: options.endpoint?.path ?? DEFAULT_ENDPOINT_PATH,

package/dist/plugin.mjs

@@ -1,4 +1,5 @@
 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";
@@ -14,7 +15,7 @@ import { definePlugin } from "payload";
 	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 {

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 };

package/dist/schema/outline.mjs

@@ -1,5 +1,5 @@
 import { isPlainObject, ownValue } from "../guards.mjs";
-import { allowedNodeTypes, nodeOptions } from "./lexical.mjs";
+import { allowedNodeTypes, editorRoot, nodeOptions } from "./lexical.mjs";
 //#region src/schema/outline.ts
 const TEXT_PREVIEW_LENGTH = 80;
 const collectText = (node) => {
@@ -43,12 +43,11 @@ const walk = (node, pointer, options, entries) => {
 * entry's `pointer` extends it with "/root" and the node's real indices, which
 * makes it directly usable in a patch operation.
 */ const lexicalOutline = (state, basePointer, field) => {
-	if (!isPlainObject(state)) return [];
-	const root = state["root"];
-	if (!isPlainObject(root) || !Array.isArray(root["children"])) return [];
+	const rootChildren = editorRoot(state)?.["children"];
+	if (!Array.isArray(rootChildren)) return [];
 	const options = nodeOptions(field, allowedNodeTypes(field));
 	const entries = [];
-	root["children"].forEach((child, index) => {
+	rootChildren.forEach((child, index) => {
 		if (isPlainObject(child)) walk(child, `${basePointer}/root/children/${String(index)}`, options, entries);
 	});
 	return entries;