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

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;

package/dist/schema/path.mjs

@@ -24,5 +24,8 @@ const PROTOTYPE_SEGMENTS = /* @__PURE__ */ new Set([
 * Pointer, so everything handed back addresses documents the same way. The
 * path already carries real indices, so it maps directly.
 */ const pointerFromPayloadPath = (path) => path ? joinPath(path.split(".")) : "";
+/**
+* The pointer one segment up. The root pointer stays the root.
+*/ const parentPointer = (pointer) => joinPath(splitPath(pointer).slice(0, -1));
 //#endregion
-export { JSON_POINTER_PATTERN, isIndexSegment, joinPath, pointerFromPayloadPath, prototypeSegmentProblem, splitPath };
+export { JSON_POINTER_PATTERN, isIndexSegment, joinPath, parentPointer, pointerFromPayloadPath, prototypeSegmentProblem, splitPath };

package/dist/schema/pointer.mjs

@@ -1,14 +1,10 @@
-import { isIndexSegment, joinPath, splitPath } from "./path.mjs";
-import { blockOf, blockSlugsOf, describeAddressableFields, findBlocksField, findRichTextField, schemaOf } from "./walk.mjs";
+import { propOf } from "../guards.mjs";
 import { SchemaError } from "./errors.mjs";
+import { isIndexSegment, joinPath, splitPath } from "./path.mjs";
+import { blockSlugsOf, describeAddressableFields, findFieldAt, longestMatch, requireBlock, schemaOf } from "./walk.mjs";
 import { resolveLexicalPointer } from "./lexical-pointer.mjs";
 //#region src/schema/pointer.ts
 const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isIndexSegment(segment) : part === segment);
-const matchPointerSegments = (descriptors, segments) => descriptors.map((descriptor) => ({
-	consumed: splitPath(descriptor.path).length,
-	descriptor,
-	parts: splitPath(descriptor.path)
-})).filter(({ parts }) => parts.every((part, offset) => partMatches(part, segments[offset]))).sort((left, right) => right.consumed - left.consumed)[0];
 const isSubtreePrefix = (descriptors, segments) => descriptors.some((descriptor) => {
 	const parts = splitPath(descriptor.path);
 	return parts.length > segments.length && segments.every((segment, offset) => {
@@ -21,17 +17,15 @@ const stepIntoBlock = (at) => {
 	const { addedValue, config, descriptor, rows } = at;
 	const [index, ...remaining] = at.rest;
 	if (!isIndexSegment(index)) throw new SchemaError(`"${descriptor.path}" is an array; "${index}" is not an index.`);
-	const field = findBlocksField(at.fields, splitPath(descriptor.path));
+	const field = findFieldAt(at.fields, splitPath(descriptor.path), "blocks");
 	const existing = Array.isArray(rows) && index !== "-" ? rows[Number(index)] : void 0;
-	const slug = existing?.blockType ?? addedValue?.blockType;
+	const slug = propOf(existing, "blockType") ?? propOf(addedValue, "blockType");
 	if (!field || slug === void 0) throw new SchemaError(`Cannot tell which block "${descriptor.path}/${index}" is. Supply a "blockType" on the value, one of: ${field ? blockSlugsOf(field).join(", ") : ""}`);
 	if (typeof slug !== "string") throw new SchemaError(`"blockType" must be a string naming a block at "${descriptor.path}". Allowed: ${blockSlugsOf(field).join(", ")}`);
-	const block = blockOf(config, field, slug);
-	if (!block) throw new SchemaError(`"${slug}" is not allowed at "${descriptor.path}". Allowed: ${blockSlugsOf(field).join(", ")}`);
 	return {
 		blockType: slug,
 		data: existing,
-		fields: block.flattenedFields,
+		fields: requireBlock(config, field, slug, descriptor.path).flattenedFields,
 		rest: remaining
 	};
 };
@@ -48,7 +42,7 @@ const stepIntoBlock = (at) => {
 	let inLexical;
 	while (segments.length > 0) {
 		const descriptors = describeAddressableFields(fields);
-		const match = matchPointerSegments(descriptors, segments);
+		const match = longestMatch(descriptors, segments, partMatches);
 		if (!match) {
 			if (isSubtreePrefix(descriptors, segments)) return {
 				...blockType === void 0 ? {} : { blockType },
@@ -57,7 +51,7 @@ const stepIntoBlock = (at) => {
 			};
 			throw new SchemaError(`"${joinPath(segments)}" is not a field here. Available: ${descriptors.map((descriptor) => descriptor.path).join(", ")}`);
 		}
-		const rest = segments.slice(match.consumed);
+		const rest = segments.slice(match.parts.length);
 		if (rest.length === 0) return {
 			...blockType === void 0 ? {} : { blockType },
 			descriptor: match.descriptor,
@@ -67,7 +61,7 @@ const stepIntoBlock = (at) => {
 			...readOnly === void 0 ? {} : { readOnly }
 		};
 		if (match.descriptor.type === "richText") {
-			const field = findRichTextField(fields, splitPath(match.descriptor.path));
+			const field = findFieldAt(fields, splitPath(match.descriptor.path), "richText");
 			if (!field) throw new Error(`"${match.descriptor.path}" could not be resolved.`);
 			const step = resolveLexicalPointer({
 				...target.addedValue === void 0 ? {} : { addedValue: target.addedValue },
@@ -75,7 +69,7 @@ const stepIntoBlock = (at) => {
 				descriptor: match.descriptor,
 				field,
 				segments: rest,
-				state: valueAtSegments(data, segments.slice(0, match.consumed))
+				state: valueAtSegments(data, segments.slice(0, match.parts.length))
 			});
 			if (step.kind === "position") return {
 				...blockType === void 0 ? {} : { blockType },
@@ -99,7 +93,7 @@ const stepIntoBlock = (at) => {
 			descriptor: match.descriptor,
 			fields,
 			rest,
-			rows: valueAtSegments(data, segments.slice(0, match.consumed)),
+			rows: valueAtSegments(data, segments.slice(0, match.parts.length)),
 			config
 		});
 		readOnly = match.descriptor.readOnly ?? readOnly;

package/dist/schema/shape.mjs

@@ -1,7 +1,7 @@
-import { isPlainObject, ownValue } from "../guards.mjs";
-import { ROOT_PROPERTIES, constrainsFields, lexicalSubSchema, nodeProblems, propertyProblem, rootProblems } from "./lexical.mjs";
+import { isPlainObject, ownValue, propOf } from "../guards.mjs";
+import { ROOT_PROPERTIES, constrainsFields, editorRoot, lexicalSubSchema, nodeProblems, propertyProblem, rootProblems } from "./lexical.mjs";
 import { splitPath } from "./path.mjs";
-import { ROW_KEYS, blockOf, blockSlugsOf, descriptorsUnder, findBlocksField, findRichTextField } from "./walk.mjs";
+import { ROW_KEYS, blockForRow, blockSlugsOf, classifyKey, descriptorsUnder, findFieldAt } from "./walk.mjs";
 //#region src/schema/shape.ts
 /**
 * Lexical throws when it hydrates a state whose root holds nothing. An empty
@@ -33,10 +33,9 @@ const checkNodeFields = (scope, field, node) => {
 		}, data);
 		return;
 	}
-	const slug = data["blockType"];
-	const block = typeof slug === "string" ? blockOf(scope.config, sub.blocksField, slug) : void 0;
+	const block = blockForRow(scope.config, sub.blocksField, data);
 	if (!block) {
-		scope.problems.push(`${scope.pointer}/fields: ${refusedSlug(slug)}. Allowed: ${blockSlugsOf(sub.blocksField).join(", ")}`);
+		scope.problems.push(`${scope.pointer}/fields: ${refusedSlug(data["blockType"])}. Allowed: ${blockSlugsOf(sub.blocksField).join(", ")}`);
 		return;
 	}
 	checkValue({
@@ -81,11 +80,11 @@ const checkNodes = (scope, editor, nodes, pointer) => {
 	});
 };
 const checkRichText = (scope, editor, value) => {
-	if (!isPlainObject(value) || !isPlainObject(value["root"])) {
+	const root = editorRoot(value);
+	if (!root) {
 		scope.problems.push(`${scope.pointer}: expected a Lexical editor state with a "root".`);
 		return;
 	}
-	const root = value["root"];
 	const { missing, rejected, unexpected } = rootProblems(root);
 	if (missing.length > 0) scope.problems.push(`${scope.pointer}/root: the root node is missing ${quoted(missing)}. Write nodes as Lexical serializes them.`);
 	for (const problem of rejected) scope.problems.push(`${scope.pointer}/root/${problem.property}: the root node needs ${problem.needs} here.`);
@@ -148,7 +147,7 @@ const checkLeafValue = (scope, descriptor, value) => {
 	if (descriptor.type === "richText") {
 		checkRichText(scope, {
 			allowed: descriptor.nodes ?? [],
-			field: findRichTextField(scope.fields, splitPath(descriptor.path)),
+			field: findFieldAt(scope.fields, splitPath(descriptor.path), "richText"),
 			nodeOptions: descriptor.nodeOptions
 		}, value);
 		return;
@@ -158,13 +157,12 @@ const checkLeafValue = (scope, descriptor, value) => {
 		scope.problems.push(`${scope.pointer}: expected an array of blocks.`);
 		return;
 	}
-	const field = findBlocksField(scope.fields, splitPath(descriptor.path));
-	if (!field) return;
+	const field = findFieldAt(scope.fields, splitPath(descriptor.path), "blocks");
 	value.forEach((row, index) => {
-		const slug = isPlainObject(row) ? row["blockType"] : void 0;
-		const block = typeof slug === "string" ? blockOf(scope.config, field, slug) : void 0;
+		const block = field && blockForRow(scope.config, field, row);
+		if (!field) return;
 		if (!block) {
-			scope.problems.push(`${scope.pointer}/${String(index)}: ${refusedSlug(slug)}. Allowed: ${blockSlugsOf(field).join(", ")}`);
+			scope.problems.push(`${scope.pointer}/${String(index)}: ${refusedSlug(propOf(row, "blockType"))}. Allowed: ${blockSlugsOf(field).join(", ")}`);
 			return;
 		}
 		checkValue({
@@ -177,47 +175,37 @@ const checkLeafValue = (scope, descriptor, value) => {
 };
 const checkValue = (scope, value) => {
 	if (!isPlainObject(value)) return;
-	const prefixParts = scope.prefix;
-	const relative = descriptorsUnder(scope.fields, prefixParts);
+	const relative = descriptorsUnder(scope.fields, scope.prefix);
 	for (const [key, entry] of Object.entries(value)) {
 		if (ROW_KEYS.has(key)) continue;
-		const candidates = relative.filter(({ parts }) => parts[0] === key);
 		const pointer = `${scope.pointer}/${key}`;
-		if (candidates.length === 0) {
-			scope.problems.push(`${pointer}: no such field. Available: ${[...new Set(relative.map(({ parts }) => parts[0]))].join(", ")}`);
-			continue;
-		}
-		const exact = candidates.find(({ parts }) => parts.length === 1);
-		if (exact) {
-			checkLeafValue({
-				...scope,
-				pointer
-			}, exact.descriptor, entry);
-			continue;
-		}
-		if (candidates.some(({ parts }) => parts[1] === "*")) {
-			if (!Array.isArray(entry)) {
-				scope.problems.push(`${pointer}: expected an array.`);
-				continue;
-			}
-			entry.forEach((row, index) => {
-				checkValue({
+		const found = classifyKey(relative, scope.prefix, key);
+		switch (found.kind) {
+			case "none":
+				scope.problems.push(`${pointer}: no such field. Available: ${[...new Set(relative.map(({ parts }) => parts[0]))].join(", ")}`);
+				break;
+			case "leaf":
+				checkLeafValue({
 					...scope,
-					pointer: `${pointer}/${String(index)}`,
-					prefix: [
-						...prefixParts,
-						key,
-						"*"
-					]
-				}, row);
-			});
-			continue;
+					pointer
+				}, found.descriptor, entry);
+				break;
+			case "rows":
+				if (Array.isArray(entry)) entry.forEach((row, index) => {
+					checkValue({
+						...scope,
+						pointer: `${pointer}/${String(index)}`,
+						prefix: found.prefix
+					}, row);
+				});
+				else scope.problems.push(`${pointer}: expected an array.`);
+				break;
+			case "group": checkValue({
+				...scope,
+				pointer,
+				prefix: found.prefix
+			}, entry);
 		}
-		checkValue({
-			...scope,
-			pointer,
-			prefix: [...prefixParts, key]
-		}, entry);
 	}
 };
 const validateWriteValue = (config, target, value) => {

package/dist/schema/walk.mjs

@@ -1,3 +1,5 @@
+import { propOf } from "../guards.mjs";
+import { SchemaError } from "./errors.mjs";
 import { allowedNodeTypes, nodeOptions } from "./lexical.mjs";
 import { joinPath, splitPath } from "./path.mjs";
 import { translateAny } from "../i18n.mjs";
@@ -34,9 +36,17 @@ const RESERVED_FIELD_NAMES = /* @__PURE__ */ new Set([
 /**
 * Payload's `fieldIsHiddenOrDisabled` reads `hidden` and `admin.disabled`, not
 * `admin.hidden`, which its own upload base fields carry.
-*/ const isAdminHidden = (field) => "admin" in field && field.admin.hidden === true;
-const isSkipped = (field) => !("name" in field) || field.type === "join" || RESERVED_FIELD_NAMES.has(field.name) || fieldIsVirtual(field) || isAdminHidden(field) || fieldIsHiddenOrDisabled(field);
-const isReadOnly = (field) => "admin" in field && field.admin.readOnly === true;
+*/ const adminFlag = (field, key) => "admin" in field && field.admin[key] === true;
+const blockForRow = (config, field, row) => {
+	const slug = propOf(row, "blockType");
+	return typeof slug === "string" ? blockOf(config, field, slug) : void 0;
+};
+const requireBlock = (config, field, slug, at) => {
+	const block = blockOf(config, field, slug);
+	if (!block) throw new SchemaError(`"${slug}" is not allowed at "${at}". Allowed: ${blockSlugsOf(field).join(", ")}`);
+	return block;
+};
+const isSkipped = (field) => !("name" in field) || field.type === "join" || RESERVED_FIELD_NAMES.has(field.name) || fieldIsVirtual(field) || adminFlag(field, "hidden") || fieldIsHiddenOrDisabled(field);
 const describeBase = (field, { path, readOnly, translate }) => {
 	const description = translate("admin" in field ? field.admin.description : void 0);
 	return {
@@ -71,17 +81,11 @@ const withRows = (descriptor, field) => ({
 });
 const isContainer = (descriptor) => descriptor.type === "array" || descriptor.type === "group" || descriptor.type === "tab";
 const isInformative = (descriptor) => descriptor.description !== void 0 || descriptor.required === true || descriptor.localized === true;
-/**
-* Named tabs, groups and arrays add a path segment and are described
-* themselves only when they declare something of their own: an array always,
-* since its row counts live nowhere else. The walk stops at every blocks field
-* and names the slugs, so a node's size follows the number of blocks it
-* allows, not their definitions. Omitting `translate` costs language
-* selection, never the description itself.
-*/ const describeFields = (fields, translate = translateAny) => {
+const describedByFields = /* @__PURE__ */ new WeakMap();
+const describeWith = (fields, translate) => {
 	const walk = (current, prefix, parentReadOnly) => current.flatMap((field) => {
 		if (isSkipped(field)) return [];
-		const readOnly = parentReadOnly || isReadOnly(field);
+		const readOnly = parentReadOnly || adminFlag(field, "readOnly");
 		const path = [...prefix, field.name];
 		const at = {
 			path: joinPath(path),
@@ -102,6 +106,22 @@ const isInformative = (descriptor) => descriptor.description !== void 0 || descr
 	return walk(fields, [], false);
 };
 /**
+* Named tabs, groups and arrays add a path segment and are described
+* themselves only when they declare something of their own: an array always,
+* since its row counts live nowhere else. The walk stops at every blocks field
+* and names the slugs, so a node's size follows the number of blocks it
+* allows, not their definitions. Omitting `translate` costs language
+* selection, never the description itself.
+*/ const describeFields = (fields, translate = translateAny) => {
+	if (translate !== translateAny) return describeWith(fields, translate);
+	let described = describedByFields.get(fields);
+	if (!described) {
+		described = describeWith(fields, translate);
+		describedByFields.set(fields, described);
+	}
+	return described;
+};
+/**
 * The descriptors that address a value, which every walk resolving a path
 * against a document needs. Containers are left out, since only
 * {@link nodeDescriber} reports one.
@@ -124,11 +144,30 @@ const findFieldAt = (fields, path, type) => {
 		if (field.type === "array" && path[1] === "*") return findFieldAt(field.flattenedFields, path.slice(2), type);
 	}
 };
-const findBlocksField = (fields, path) => findFieldAt(fields, path, "blocks");
-/**
-* Locates the rich text field a resolved descriptor path refers to, so its
-* editor can be introspected for the fields its nodes carry.
-*/ const findRichTextField = (fields, path) => findFieldAt(fields, path, "richText");
+const longestMatch = (descriptors, segments, eq) => descriptors.map((descriptor) => ({
+	descriptor,
+	parts: splitPath(descriptor.path)
+})).filter(({ parts }) => parts.every((part, offset) => eq(part, segments[offset]))).sort((left, right) => right.parts.length - left.parts.length)[0];
+const classifyKey = (relative, prefix, key) => {
+	const candidates = relative.filter(({ parts }) => parts[0] === key);
+	const exact = candidates.find(({ parts }) => parts.length === 1);
+	if (exact) return {
+		descriptor: exact.descriptor,
+		kind: "leaf"
+	};
+	if (candidates.length === 0) return { kind: "none" };
+	return candidates.some(({ parts }) => parts[1] === "*") ? {
+		kind: "rows",
+		prefix: [
+			...prefix,
+			key,
+			"*"
+		]
+	} : {
+		kind: "group",
+		prefix: [...prefix, key]
+	};
+};
 /**
 * Looks up the sanitized config for a collection or global as an
 * {@link EntitySchema}. Throws on an unknown slug instead of returning
@@ -140,4 +179,4 @@ const findBlocksField = (fields, path) => findFieldAt(fields, path, "blocks");
 	return found;
 };
 //#endregion
-export { RESERVED_FIELD_NAMES, ROW_KEYS, blockOf, blockSlugsOf, describeAddressableFields, describeFields, descriptorsUnder, findBlocksField, findRichTextField, isAdminHidden, schemaOf };
+export { RESERVED_FIELD_NAMES, ROW_KEYS, adminFlag, blockForRow, blockOf, blockSlugsOf, classifyKey, describeAddressableFields, describeFields, descriptorsUnder, findFieldAt, longestMatch, requireBlock, schemaOf };

package/dist/tools/builtin.mjs

@@ -1,11 +1,14 @@
 import { createDocument } from "./create-document.mjs";
+import { deleteDocument } from "./delete-document.mjs";
 import { describeSchema } from "./describe-schema.mjs";
+import { duplicateDocument } from "./duplicate-document.mjs";
 import { findDocuments } from "./find-documents.mjs";
 import { findVersions } from "./find-versions.mjs";
 import { getDocument } from "./get-document.mjs";
 import { listCapabilities } from "./list-capabilities.mjs";
 import { patchDocument } from "./patch-document.mjs";
 import { publishDocument } from "./publish-document.mjs";
+import { createRunConfirmed } from "./run-confirmed.mjs";
 import { validateDocument } from "./validate-document.mjs";
 //#region src/tools/builtin.ts
 /**
@@ -21,8 +24,11 @@ import { validateDocument } from "./validate-document.mjs";
 	findVersions,
 	patchDocument,
 	createDocument,
+	duplicateDocument,
 	validateDocument,
-	publishDocument
+	publishDocument,
+	deleteDocument,
+	createRunConfirmed(() => BUILTIN_TOOLS)
 ];
 //#endregion
 export { BUILTIN_TOOLS };

package/dist/tools/create-document.mjs

@@ -1,23 +1,26 @@
 import { defineMcpxTool } from "../define-tool.mjs";
-import { errorResult, jsonResult } from "../result.mjs";
+import { definedProps } from "../guards.mjs";
+import { errorResult } from "../result.mjs";
 import { validateWriteValue } from "../schema/shape.mjs";
 import "../schema/index.mjs";
-import { liveWriteSentence, localeOf, localeShape, patchOnlySlugs, slugEnum, slugsFor } from "./shared.mjs";
-import { collectPublishBlockers } from "../write/publish-blockers.mjs";
-import { readDraft, resolveEntity } from "./document.mjs";
+import { assertAcceptsFile, fileShape, fileWriteRefusal, uploadHandoff, uploadedFile } from "../upload/file.mjs";
+import { liveWriteSentence, localeOf, localeShape, patchOnlySlugs, slugsFor, stringEnum } from "./shared.mjs";
+import { resolveCollection, writtenResult } from "./document.mjs";
 import { stripRowIds } from "../write/row-ids.mjs";
 import { z } from "zod";
+import { APIError } from "payload";
 //#region src/tools/create-document.ts
 const uploadSentence = (scope) => {
 	const slugs = patchOnlySlugs(scope);
 	return slugs.length === 0 ? "" : ` Documents in ${slugs.join(", ")} are files and cannot be created here. Upload the file in the admin panel, then edit its fields with patchDocument.`;
 };
-const DESCRIPTION = (scope) => `Creates a document in a collection. Use it only when the document does not exist yet. Returns "id", "status", "updatedAt" and, if any, "publishBlockers". "publishBlockersUnavailable" means that check failed. "data" may leave required fields empty for patchDocument to fill later, except in a collection whose listCapabilities entry has "draftValidation" true or "drafts" false. A field describeSchema does not list is refused, and "id" is always assigned.
+const DESCRIPTION = (scope) => `Creates a document in a collection. Use it only when the document does not exist yet. Returns "id", "status", "updatedAt" and, if any, "publishBlockers". "publishBlockersUnavailable" means that check failed. "data" may leave required fields empty for patchDocument to fill later, except in a collection whose listCapabilities entry has "draftValidation" true or "drafts" false. A field describeSchema does not list is refused, and "id" is always assigned. The response links the document with "adminUrl" and "previewUrl".
 
 ${liveWriteSentence(scope, "create")}${uploadSentence(scope)}`;
 /**
-* Collection-only, because a global always exists. Upload collections are
-* excluded because a create there would need the file.
+* Collection-only, because a global always exists. A create in an upload
+* collection needs `file`: the call then returns an upload grant, and the PUT
+* to it runs the call again with the bytes.
 *
 * The seed is checked against the collection's fields first, so an unknown key
 * is refused along with its valid siblings. Row ids in the seed are stripped
@@ -35,18 +38,21 @@ ${liveWriteSentence(scope, "create")}${uploadSentence(scope)}`;
 	},
 	isEnabled: (scope) => slugsFor(scope, "create").collections.length > 0,
 	inputSchema: (scope) => ({
-		collection: slugEnum(slugsFor(scope, "create").collections),
+		collection: stringEnum(slugsFor(scope, "create").collections),
 		...localeShape(scope, {
 			required: true,
 			description: "Locale of the localized fields in \"data\"."
 		}),
-		data: z.record(z.string(), z.unknown()).describe("Field values by name, e.g. {\"title\":\"Home\",\"slug\":\"home\"}.")
+		data: z.record(z.string(), z.unknown()).describe("Field values by name, e.g. {\"title\":\"Home\",\"slug\":\"home\"}."),
+		...fileShape(scope, (slugs) => `Required in ${slugs}. The call returns an "upload" for the bytes instead of writing.`)
 	}),
 	handler: async ({ args, scope }) => {
-		const target = resolveEntity(scope, { collection: args.collection }, "create");
-		if (target.kind === "global") throw new Error("createDocument resolved a global.");
+		const target = resolveCollection(scope, args.collection, "create");
 		const { payload } = scope.req;
 		const locale = localeOf(scope, args.locale);
+		const { file } = args;
+		if (file !== void 0) assertAcceptsFile(scope, target, file);
+		else if (scope.exposure.collections.some((entity) => entity.slug === target.slug && entity.isUpload)) throw new APIError(`"${target.slug}" stores files, so "file" is required.`, 400);
 		if (Object.hasOwn(args.data, "id")) return errorResult("Nothing was created.", { problems: ["/id: Payload assigns the id; it cannot be supplied."] });
 		const problems = validateWriteValue(payload.config, {
 			pointer: "",
@@ -56,6 +62,21 @@ ${liveWriteSentence(scope, "create")}${uploadSentence(scope)}`;
 			}
 		}, args.data);
 		if (problems.length > 0) return errorResult("Nothing was created.", { problems });
+		const bytes = uploadedFile(scope.req);
+		if (file !== void 0) {
+			const refusal = await fileWriteRefusal(scope, {
+				entity: target,
+				data: args.data
+			});
+			if (refusal) return refusal;
+			if (!bytes) return await uploadHandoff(scope, {
+				tool: "createDocument",
+				args: {
+					...args,
+					file
+				}
+			});
+		}
 		const created = await payload.create({
 			collection: args.collection,
 			data: stripRowIds(args.data),
@@ -63,26 +84,17 @@ ${liveWriteSentence(scope, "create")}${uploadSentence(scope)}`;
 			draft: true,
 			overrideAccess: false,
 			req: scope.req,
-			...locale === void 0 ? {} : { locale }
+			...definedProps({
+				locale,
+				file: bytes
+			})
 		});
-		const saved = await readDraft(scope, {
+		return await writtenResult(scope, {
 			target: {
 				...target,
 				id: created["id"]
 			},
-			locale,
-			privileged: true
-		});
-		const validation = await collectPublishBlockers(scope.req, {
-			doc: saved,
-			entity: target
-		});
-		return jsonResult({
-			id: saved["id"],
-			status: saved["_status"],
-			updatedAt: saved["updatedAt"],
-			...validation.blockers.length > 0 ? { publishBlockers: validation.blockers } : {},
-			...validation.unavailable ? { publishBlockersUnavailable: true } : {}
+			locale
 		});
 	}
 });