@abinnovision/payloadcms-mcpx 2.0.0-beta.8 → 2.0.0

package/dist/tools/run-confirmed.mjs

@@ -0,0 +1,114 @@
+import { defineMcpxTool, isToolEnabled, toolInputSchema } from "../define-tool.mjs";
+import { grantContext } from "../grants/grant.mjs";
+import { claimConfirmation, readConfirmation } from "../grants/confirmation.mjs";
+import { jsonResult, parseResult } from "../result.mjs";
+import { withRequestLocale } from "./document.mjs";
+import { z } from "zod";
+import { APIError } from "payload";
+//#region src/tools/run-confirmed.ts
+const DESCRIPTION = `Runs calls that returned a "confirmation", once the user approved them in the admin panel. Returns one result per id, in the order given: "done" with the call's "result", "pending" while it awaits a decision, "skipped" with a "reason" when it no longer passes its checks, or "refused" when it was rejected, expired, already run or is unknown. A pending id stays usable; no other id can run again.`;
+const NO_LONGER_ALLOWED = "This key no longer allows this call.";
+const CONFIRMED = {
+	confirmed: true,
+	request: () => Promise.reject(/* @__PURE__ */ new Error("A confirmed run cannot request a confirmation."))
+};
+const execute = async (tool, confirmation, scope, extra) => {
+	const { req } = scope;
+	const args = toolInputSchema(tool, scope).safeParse(confirmation.args);
+	if (!args.success) return {
+		status: "skipped",
+		reason: NO_LONGER_ALLOWED
+	};
+	return await withRequestLocale(req, async () => {
+		req.locale = confirmation.locale;
+		req.fallbackLocale = confirmation.fallbackLocale;
+		try {
+			const result = await tool.handler({
+				args: args.data,
+				scope,
+				req,
+				extra,
+				confirmation: CONFIRMED
+			});
+			const data = parseResult(result);
+			return result.isError === true ? {
+				status: "skipped",
+				reason: String(data["error"])
+			} : {
+				status: "done",
+				result: data
+			};
+		} catch (error) {
+			if (error instanceof APIError && error.isPublic) return {
+				status: "skipped",
+				reason: error.message
+			};
+			req.payload.logger.error({
+				err: error,
+				msg: "[payloadcms-mcpx] Confirmed call failed."
+			});
+			return {
+				status: "skipped",
+				reason: "Internal error"
+			};
+		}
+	});
+};
+const claimApproved = async (req, slug, apiKeyId, id) => {
+	const { payload } = req;
+	try {
+		const confirmation = await readConfirmation(payload, slug, apiKeyId, id);
+		if (confirmation?.state === "pending") return { status: "pending" };
+		return confirmation?.state === "approved" && await claimConfirmation(payload, slug, apiKeyId, id, confirmation.exp) ? confirmation : { status: "refused" };
+	} catch (error) {
+		payload.logger.error({
+			err: error,
+			msg: "[payloadcms-mcpx] Could not claim a confirmed call."
+		});
+		return {
+			status: "skipped",
+			reason: "Internal error"
+		};
+	}
+};
+/**
+* Runs approved calls of the confirmable tools in `tools`, which is read per
+* call so the list may include this tool. Registered when the key may call one
+* of them. Each call claims its entry first, so it runs at most once.
+*/ const createRunConfirmed = (tools) => defineMcpxTool({
+	name: "runConfirmed",
+	description: DESCRIPTION,
+	annotations: {
+		destructiveHint: true,
+		openWorldHint: false
+	},
+	isEnabled: (scope) => tools().some((tool) => tool.confirm !== void 0 && isToolEnabled(tool, scope)),
+	inputSchema: { ids: z.array(z.string().max(64)).min(1).max(50).describe("\"id\" of each \"confirmation\".") },
+	handler: async ({ args, scope, extra }) => {
+		const { req } = scope;
+		const { slug, apiKeyId } = grantContext(req);
+		const outcomes = [];
+		for (const id of args.ids) {
+			const confirmation = await claimApproved(req, slug, apiKeyId, id);
+			if (!("tool" in confirmation)) {
+				outcomes.push({
+					id,
+					...confirmation
+				});
+				continue;
+			}
+			const tool = tools().find((candidate) => candidate.name === confirmation.tool && candidate.confirm !== void 0);
+			const result = tool && isToolEnabled(tool, scope) ? await execute(tool, confirmation, scope, extra) : {
+				status: "skipped",
+				reason: NO_LONGER_ALLOWED
+			};
+			outcomes.push({
+				id,
+				...result
+			});
+		}
+		return jsonResult({ results: outcomes });
+	}
+});
+//#endregion
+export { createRunConfirmed };

package/dist/tools/shared.mjs

@@ -1,68 +1,63 @@
-import { canCreate, isLiveWrite } from "../capabilities.mjs";
+import { acceptsFiles } from "../upload/file.mjs";
 import { z } from "zod";
 //#region src/tools/shared.ts
 /**
-* An out-of-scope slug fails schema validation before a handler runs, so a
+* A value outside the list fails schema validation before a handler runs, so a
 * client only ever sees what its key may touch.
-*/ const slugEnum = (slugs) => z.enum(slugs);
-/** Payload's id type follows the adapter, so both forms are handed on as read. */ const idSchema = z.union([z.string(), z.number()]);
+*/ const stringEnum = (values) => z.enum(values);
+/**
+* Payload's id type follows the adapter, so both forms are handed on as read.
+*/ const idSchema = z.union([z.string(), z.number()]);
 const slugsOf = (scope, key) => ({
 	collections: scope.collections[key],
 	globals: scope.globals[key]
 });
 const slugsWhere = (scope, predicate, allowed) => {
 	const pick = (entities, slugs) => entities.filter((entity) => slugs.includes(entity.slug) && predicate(entity)).map((entity) => entity.slug);
-	return [...pick(scope.exposure.collections, allowed.collections), ...pick(scope.exposure.globals, allowed.globals)];
+	return {
+		collections: pick(scope.exposure.collections, allowed.collections),
+		globals: pick(scope.exposure.globals, allowed.globals)
+	};
 };
 /**
-* Slugs this key may write but never create in, because their documents are
-* files. Collection-only, since nothing creates a global either way.
-*/ const patchOnlySlugs = (scope) => slugsWhere(scope, (entity) => !canCreate(entity), {
-	collections: scope.collections.writable,
-	globals: []
-});
+* Collections this key may write but not create in: upload collections whose
+* files MCP does not accept. Nothing creates a global either way.
+*/ const patchOnlySlugs = (scope) => {
+	const creatable = slugsFor(scope, "create").collections;
+	return scope.collections.writable.filter((slug) => !creatable.includes(slug));
+};
 const widen = (branch) => branch;
-/** The one list the shape helpers and {@link resolveEntity} both read. */ const slugsFor = (scope, operation) => {
+/**
+* The one list the shape helpers and {@link resolveEntity} both read.
+*/ const slugsFor = (scope, operation) => {
 	switch (operation) {
-		case "create": return {
-			collections: slugsWhere(scope, canCreate, {
-				collections: scope.collections.writable,
-				globals: []
-			}),
+		case "create": return slugsWhere(scope, (entity) => entity.write && (!entity.isUpload || acceptsFiles(scope, entity.slug)), {
+			collections: scope.collections.writable,
+			globals: []
+		});
+		case "delete": return {
+			collections: scope.collections.deletable,
 			globals: []
 		};
 		case "publish": return slugsOf(scope, "publishable");
 		case "read": return slugsOf(scope, "readable");
-		case "versions": return {
-			collections: slugsWhere(scope, (entity) => entity.hasVersions, {
-				collections: scope.collections.readable,
-				globals: []
-			}),
-			globals: slugsWhere(scope, (entity) => entity.hasVersions, {
-				collections: [],
-				globals: scope.globals.readable
-			})
-		};
+		case "versions": return slugsWhere(scope, (entity) => entity.hasVersions, slugsOf(scope, "readable"));
 		case "write": return slugsOf(scope, "writable");
 	}
 };
 /**
-* The slugs of {@link slugsFor} `"versions"` that also have drafts. Only they
-* have `_status` on their versions, so only they can be queried by status.
-*/ const draftVersionSlugs = (scope) => {
-	const { collections, globals } = slugsFor(scope, "versions");
-	return {
-		collections: slugsWhere(scope, (entity) => entity.hasDrafts, {
-			collections,
-			globals: []
-		}),
-		globals: slugsWhere(scope, (entity) => entity.hasDrafts, {
-			collections: [],
-			globals
-		})
-	};
+* Whether `operation` reaches any collection or global.
+*/ const reaches = (scope, operation) => {
+	const { collections, globals } = slugsFor(scope, operation);
+	return collections.length + globals.length > 0;
+};
+/**
+* Slugs reachable by `operation` whose writes go live, because they have no
+* draft to write.
+*/ const liveWriteSlugs = (scope, operation) => {
+	const { collections, globals } = slugsWhere(scope, (entity) => entity.liveWrite, slugsFor(scope, operation));
+	return [...collections, ...globals];
 };
-/** Slugs reachable by `operation` whose writes go live, because they have no draft to write. */ const liveWriteSlugs = (scope, operation) => slugsWhere(scope, isLiveWrite, slugsFor(scope, operation));
 /**
 * Stated on the tools that write, since a client calling them must know before
 * the call which writes are public.
@@ -72,16 +67,16 @@ const widen = (branch) => branch;
 };
 /**
 * With no reachable global, `global` is left out and `collection` stays
-* required, so a deployment without globals sees an unchanged schema. Only the
+* required, so a deployment without globals gets no extra argument. Only the
 * mixed case makes either optional, and the handler enforces exclusivity there.
 * `globalRule` states that rule on `global` for a tool without an `id`.
 */ const entityShape = (scope, operation, globalRule) => {
 	const { collections, globals } = slugsFor(scope, operation);
-	if (globals.length === 0) return widen({ collection: slugEnum(collections) });
-	if (collections.length === 0) return widen({ global: slugEnum(globals) });
-	const global = slugEnum(globals).optional();
+	if (globals.length === 0) return widen({ collection: stringEnum(collections) });
+	if (collections.length === 0) return widen({ global: stringEnum(globals) });
+	const global = stringEnum(globals).optional();
 	return widen({
-		collection: slugEnum(collections).optional(),
+		collection: stringEnum(collections).optional(),
 		global: globalRule === void 0 ? global : global.describe(globalRule)
 	});
 };
@@ -94,10 +89,12 @@ const widen = (branch) => branch;
 	if (globals.length === 0) return widen({ id: idSchema });
 	return widen({ id: idSchema.optional().describe("Required with \"collection\", omitted with \"global\".") });
 };
-/** For the reads that fall back to the default locale, unlike the writes. */ const READ_LOCALE_DESCRIPTION = "Default: the default locale. A value missing in this locale is shown from the default locale.";
+/**
+* For the reads that fall back to the default locale, unlike the writes.
+*/ const READ_LOCALE_DESCRIPTION = "Default: the default locale. A value missing in this locale is shown from the default locale.";
 const localeShape = (scope, options) => {
 	if (!scope.localization) return widen({});
-	const enumerated = z.enum(scope.localization.locales);
+	const enumerated = stringEnum(scope.localization.locales);
 	const locale = options.required ? enumerated : enumerated.optional();
 	return widen({ locale: options.description === void 0 ? locale : locale.describe(options.description) });
 };
@@ -106,6 +103,25 @@ const localeShape = (scope, options) => {
 * it can write back, and populating a relation costs a query.
 */ const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.limits.maxDepth).optional().describe("Default 0. A relationship into a collection this key cannot read stays an id.") });
 /**
+* For the writes that refuse a document changed since the client read it.
+*/ const expectedUpdatedAtShape = { expectedUpdatedAt: z.string().optional().describe("\"updatedAt\" from your last read. Refused if the document changed since.") };
+/**
+* `limit` is bounded by the configured ceiling, so the client sees it instead
+* of being clamped silently.
+*/ const pageShape = (scope) => ({
+	limit: z.number().int().min(1).max(scope.limits.maxLimit).optional().describe("Default 10."),
+	page: z.number().int().min(1).optional()
+});
+/**
+* The paging fields of a result.
+*/ const pageFields = (result) => ({
+	totalDocs: result.totalDocs,
+	page: result.page,
+	totalPages: result.totalPages,
+	limit: result.limit,
+	hasNextPage: result.hasNextPage
+});
+/**
 * The locale to operate on: the explicit argument, else the request's, else
 * the default. `undefined` when localization is off.
 */ const localeOf = (scope, locale) => {
@@ -115,4 +131,4 @@ const localeShape = (scope, options) => {
 	return requested && locales.includes(requested) ? requested : defaultLocale;
 };
 //#endregion
-export { READ_LOCALE_DESCRIPTION, depthShape, draftVersionSlugs, entityShape, idSchema, idShape, liveWriteSentence, liveWriteSlugs, localeOf, localeShape, patchOnlySlugs, slugEnum, slugsFor, widen };
+export { READ_LOCALE_DESCRIPTION, depthShape, entityShape, expectedUpdatedAtShape, idSchema, idShape, liveWriteSentence, liveWriteSlugs, localeOf, localeShape, pageFields, pageShape, patchOnlySlugs, reaches, slugsFor, slugsWhere, stringEnum, widen };

package/dist/tools/validate-document.mjs

@@ -1,11 +1,11 @@
 import { defineMcpxTool } from "../define-tool.mjs";
 import { jsonResult } from "../result.mjs";
-import { entityShape, idShape, localeOf, localeShape } from "./shared.mjs";
-import { identityOf, readDraft, resolveDocument } from "./document.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
+import { entityShape, idShape, localeOf, localeShape, reaches } from "./shared.mjs";
+import { collectLocaleBlockers, documentSummary, readDraft, resolveDocument } from "./document.mjs";
 /**
-* Gated on write rather than read, because publish blockers only mean something
-* to a caller who can act on them.
+* Gated on write, which implies read, because publish blockers only mean
+* something to a caller who can act on them.
 *
 * It reads the document twice on purpose: once under the key's own access to
 * refuse a caller who may not see it, then privileged, so the check covers every
@@ -13,16 +13,17 @@ import { collectPublishBlockers } from "../write/publish-blockers.mjs";
 * the traversal fires field hooks.
 */ const validateDocument = defineMcpxTool({
 	name: "validateDocument",
-	description: `Lists what still blocks publishing one document or global, without saving. Returns "publishBlockers", each with a pointer and a message. An empty list means it can be published, unless "publishBlockersUnavailable" is true: then the check itself failed. The check runs the field hooks a save runs.`,
+	description: `Lists what still blocks publishing one document or global, without saving. Checks one locale when "locale" is given, otherwise every locale. Returns "publishBlockers", each with a pointer and a message, and a "locale" when every locale was checked. An empty list means it can be published, unless "publishBlockersUnavailable" is true: then the check itself failed. The check runs the field hooks a save runs.`,
 	annotations: { openWorldHint: false },
-	isEnabled: (scope) => scope.collections.writable.length + scope.globals.writable.length > 0,
+	isEnabled: (scope) => reaches(scope, "write"),
 	inputSchema: (scope) => ({
 		...entityShape(scope, "write"),
 		...idShape(scope, "write"),
-		...localeShape(scope, { required: true })
+		...localeShape(scope, { required: false })
 	}),
 	handler: async ({ args, scope }) => {
 		const target = resolveDocument(scope, args, "write");
+		const { localization } = scope;
 		const locale = localeOf(scope, args.locale);
 		await readDraft(scope, {
 			target,
@@ -33,14 +34,12 @@ import { collectPublishBlockers } from "../write/publish-blockers.mjs";
 			locale,
 			privileged: true
 		});
-		const validation = await collectPublishBlockers(scope.req, {
+		const validation = localization && args.locale === void 0 ? await collectLocaleBlockers(scope, target, localization.locales) : await collectPublishBlockers(scope.req, {
 			doc,
 			entity: target
 		});
 		return jsonResult({
-			...identityOf(target, doc["id"]),
-			status: doc["_status"],
-			updatedAt: doc["updatedAt"],
+			...documentSummary(target, doc),
 			publishBlockers: validation.blockers,
 			...validation.unavailable ? { publishBlockersUnavailable: true } : {}
 		});

package/dist/tools/versions.mjs

@@ -1,3 +1,4 @@
+import { definedProps, isPlainObject } from "../guards.mjs";
 import { stripAdminHidden } from "../schema/admin-hidden.mjs";
 import "../schema/index.mjs";
 import { mcpxReadRequest } from "./read-request.mjs";
@@ -12,14 +13,19 @@ const NOISE = [
 	"_status"
 ];
 const NEWEST_FIRST = ["-updatedAt", "-id"];
-/** The document or global as the key's user sees it, without `admin.hidden` fields. */ const readLive = async (scope, read, options) => {
+/**
+* The document or global as the key's user sees it, without `admin.hidden`
+* fields.
+*/ const readLive = async (scope, read, options) => {
 	const shared = {
 		depth: read.depth,
 		draft: options.draft,
 		overrideAccess: false,
 		req: mcpxReadRequest(scope),
-		...options.select === void 0 ? {} : { select: options.select },
-		...read.locale === void 0 ? {} : { locale: read.locale }
+		...definedProps({
+			select: options.select,
+			locale: read.locale
+		})
 	};
 	const doc = await (read.target.kind === "collection" ? scope.req.payload.findByID({
 		...shared,
@@ -44,9 +50,11 @@ const assertReadable = async (scope, read) => {
 		select: {}
 	});
 };
-/** `parent` comes back as a raw id or, populated, as the document itself. */ const isVersionOf = (version, id) => {
+/**
+* `parent` comes back as a raw id or, populated, as the document itself.
+*/ const isVersionOf = (version, id) => {
 	const parent = version["parent"];
-	const parentId = typeof parent === "object" && parent !== null ? parent["id"] : parent;
+	const parentId = isPlainObject(parent) ? parent["id"] : parent;
 	return (typeof parentId === "string" || typeof parentId === "number") && String(parentId) === String(id);
 };
 /**
@@ -63,7 +71,7 @@ const assertReadable = async (scope, read) => {
 		disableErrors: true,
 		overrideAccess: false,
 		req: mcpxReadRequest(scope),
-		...read.locale === void 0 ? {} : { locale: read.locale }
+		...definedProps({ locale: read.locale })
 	};
 	const version = await (read.target.kind === "collection" ? payload.findVersionByID({
 		...shared,
@@ -76,7 +84,9 @@ const assertReadable = async (scope, read) => {
 	if (read.target.kind === "collection" && !isVersionOf(version, read.target.id)) return null;
 	return withoutHidden(scope, read, version);
 };
-/** One page of a document's or global's history, newest first. */ const queryVersions = async (scope, read, options) => {
+/**
+* One page of a document's or global's history, newest first.
+*/ const queryVersions = async (scope, read, options) => {
 	await assertReadable(scope, read);
 	const where = {
 		...read.target.kind === "collection" ? { parent: { equals: read.target.id } } : {},
@@ -89,8 +99,10 @@ const assertReadable = async (scope, read) => {
 		overrideAccess: false,
 		req: mcpxReadRequest(scope),
 		where,
-		...options.page === void 0 ? {} : { page: options.page },
-		...read.locale === void 0 ? {} : { locale: read.locale }
+		...definedProps({
+			page: options.page,
+			locale: read.locale
+		})
 	};
 	return await (read.target.kind === "collection" ? scope.req.payload.findVersions({
 		...shared,
@@ -100,7 +112,9 @@ const assertReadable = async (scope, read) => {
 		slug: read.target.slug
 	}));
 };
-/** The newest version whose status is published, or `null` if none is. */ const loadPublished = async (scope, read) => {
+/**
+* The newest version whose status is published, or `null` if none is.
+*/ const loadPublished = async (scope, read) => {
 	if (!hasDraftsEnabled(read.target.config)) return null;
 	const [newest] = (await queryVersions(scope, read, {
 		status: "published",