@mvriu5/payload-ai 0.5.0

package/dist/endpoints/aiApplyActionEndpointHandler.js

@@ -0,0 +1,164 @@
+import { verifyAIActionProposal } from "../ai/proposals.js";
+import { containsSensitiveData } from "../ai/sensitiveData.js";
+import { getCollectionFields, isAuthCollection, normalizeAuthData, normalizeDataForFields } from "../payload/normalizeData.js";
+const getProposalMeta = (proposal)=>{
+    if (!proposal) return {};
+    return {
+        action: proposal.action,
+        collection: "collection" in proposal ? proposal.collection : undefined,
+        id: "id" in proposal ? proposal.id : undefined,
+        slug: "slug" in proposal ? proposal.slug : undefined
+    };
+};
+const getAppliedDocReference = (doc)=>{
+    return doc?.id === undefined ? undefined : {
+        id: doc.id
+    };
+};
+const isKnownCollection = (req, collection)=>{
+    return req.payload.config.collections.some((item)=>item.slug === collection);
+};
+const isAllowedCollection = (req, collection, collections)=>{
+    if (!collections) return isKnownCollection(req, collection);
+    return collections.includes(collection) && isKnownCollection(req, collection);
+};
+const isKnownGlobal = (req, slug)=>{
+    return req.payload.config.globals?.some((item)=>item.slug === slug) || false;
+};
+const isRecord = (value)=>{
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+};
+const isActionProposal = (proposal)=>{
+    if (!isRecord(proposal) || typeof proposal.label !== "string") return false;
+    if (proposal.action === "create") {
+        return typeof proposal.collection === "string" && isRecord(proposal.data);
+    }
+    if (proposal.action === "update") {
+        return typeof proposal.collection === "string" && typeof proposal.id === "string" && isRecord(proposal.data);
+    }
+    if (proposal.action === "delete") {
+        return typeof proposal.collection === "string" && typeof proposal.id === "string";
+    }
+    if (proposal.action === "updateGlobal") {
+        return typeof proposal.slug === "string" && isRecord(proposal.data);
+    }
+    return false;
+};
+export const createAIApplyActionEndpointHandler = (options = {})=>async (req)=>{
+        if (!req.user) return Response.json({
+            error: "Unauthorized"
+        }, {
+            status: 401
+        });
+        const body = req.json ? await req.json().catch(()=>null) : null;
+        const proposal = body?.proposal;
+        if (!proposal) return Response.json({
+            error: "Proposal is required"
+        }, {
+            status: 400
+        });
+        if (!verifyAIActionProposal(proposal)) return Response.json({
+            error: "Proposal signature is invalid or expired."
+        }, {
+            status: 400
+        });
+        if (!isActionProposal(proposal)) return Response.json({
+            error: "Proposal is invalid."
+        }, {
+            status: 400
+        });
+        if ("data" in proposal && containsSensitiveData(proposal.data)) return Response.json({
+            error: "Proposal contains sensitive fields and cannot be applied."
+        }, {
+            status: 400
+        });
+        let normalized;
+        try {
+            if (proposal.action === "updateGlobal") {
+                if (!isKnownGlobal(req, proposal.slug)) return Response.json({
+                    error: "Unknown global"
+                }, {
+                    status: 400
+                });
+                const globalConfig = req.payload.config.globals?.find((global)=>global.slug === proposal.slug);
+                normalized = normalizeDataForFields(globalConfig?.fields || [], proposal.data);
+                const doc = await req.payload.updateGlobal({
+                    data: normalized.data,
+                    overrideAccess: false,
+                    req,
+                    slug: proposal.slug
+                });
+                return Response.json({
+                    doc: getAppliedDocReference(doc),
+                    status: "applied"
+                });
+            }
+            if (!isAllowedCollection(req, proposal.collection, options.collections)) return Response.json({
+                error: "Unknown collection"
+            }, {
+                status: 400
+            });
+            if (proposal.action === "delete") {
+                const doc = await req.payload.delete({
+                    collection: proposal.collection,
+                    id: proposal.id,
+                    overrideAccess: false,
+                    req
+                });
+                return Response.json({
+                    doc: getAppliedDocReference(doc),
+                    status: "applied"
+                });
+            }
+            const collectionConfig = req.payload.config.collections.find((collection)=>collection.slug === proposal.collection);
+            normalized = normalizeAuthData(collectionConfig, normalizeDataForFields(getCollectionFields(collectionConfig), proposal.data));
+            if (proposal.action === "create" && isAuthCollection(collectionConfig) && !normalized.data.password) {
+                return Response.json({
+                    error: "Password is required when creating a user."
+                }, {
+                    status: 400
+                });
+            }
+            if (proposal.action === "create" && isAuthCollection(collectionConfig) && !normalized.data.email) {
+                return Response.json({
+                    error: "Email is required when creating a user."
+                }, {
+                    status: 400
+                });
+            }
+            if (proposal.action === "create") {
+                const doc = await req.payload.create({
+                    collection: proposal.collection,
+                    data: normalized.data,
+                    overrideAccess: false,
+                    req
+                });
+                return Response.json({
+                    doc: getAppliedDocReference(doc),
+                    status: "applied"
+                });
+            }
+            const doc = await req.payload.update({
+                collection: proposal.collection,
+                data: normalized.data,
+                id: proposal.id,
+                overrideAccess: false,
+                req
+            });
+            return Response.json({
+                doc: getAppliedDocReference(doc),
+                status: "applied"
+            });
+        } catch (err) {
+            req.payload.logger.error({
+                err,
+                msg: "AI apply action failed",
+                proposal: getProposalMeta(proposal)
+            });
+            return Response.json({
+                error: "Could not apply proposal."
+            }, {
+                status: 400
+            });
+        }
+    };

package/dist/endpoints/aiChatEndpointHandler.d.ts

@@ -0,0 +1,31 @@
+import type { PayloadHandler } from "payload";
+import { type AIActionSignature } from "../ai/proposals.js";
+export type AIActionProposal = ({
+    action: "create";
+    collection: string;
+    data: Record<string, unknown>;
+    label: string;
+} | {
+    action: "delete";
+    collection: string;
+    id: string;
+    label: string;
+} | {
+    action: "update";
+    collection: string;
+    data: Record<string, unknown>;
+    id: string;
+    label: string;
+} | {
+    action: "updateGlobal";
+    data: Record<string, unknown>;
+    label: string;
+    slug: string;
+}) & {
+    _aiSignature?: AIActionSignature;
+};
+type AIChatEndpointOptions = {
+    collections?: string[];
+};
+export declare const createAIChatEndpointHandler: (options?: AIChatEndpointOptions) => PayloadHandler;
+export {};

package/dist/endpoints/aiChatEndpointHandler.js

@@ -0,0 +1,297 @@
+import { generateText, stepCountIs } from "ai";
+import { z } from "zod";
+import { signAIActionProposal } from "../ai/proposals.js";
+import { getModel, getProviderConfig } from "../ai/providerRuntime.js";
+import { isAIProvider } from "../ai/providerOptions.js";
+import { containsSensitiveData } from "../ai/sensitiveData.js";
+import { buildPromptWithMentionContext, collectBlocks, describeField, getAllowedCollectionSlugs, getMentionContext } from "../payload/schemaContext.js";
+export const createAIChatEndpointHandler = (options = {})=>async (req)=>{
+        if (!req.user) return Response.json({
+            error: "Unauthorized"
+        }, {
+            status: 401
+        });
+        const body = req.json ? await req.json().catch(()=>null) : null;
+        const prompt = body?.prompt?.trim();
+        if (!prompt) return Response.json({
+            error: "Prompt is required"
+        }, {
+            status: 400
+        });
+        const user = req.user;
+        const requestedProvider = body?.provider || user.aiProvider || "openai";
+        if (!isAIProvider(requestedProvider)) return Response.json({
+            error: `Unsupported AI provider: ${requestedProvider}`
+        }, {
+            status: 400
+        });
+        const provider = requestedProvider;
+        const providerConfig = getProviderConfig({
+            apiKey: user.aiApiKey,
+            model: body?.model,
+            provider
+        });
+        const debug = {
+            model: providerConfig.modelID,
+            provider,
+            tools: [
+                "getDoc",
+                "getGlobal",
+                "listCollections",
+                "listGlobals",
+                "proposeCreateDoc",
+                "proposeDeleteDoc",
+                "proposeUpdateDoc",
+                "proposeUpdateGlobal",
+                "searchDocs"
+            ]
+        };
+        if (!providerConfig.apiKey) {
+            return Response.json({
+                error: `Add a ${provider} API key to your account settings first.`
+            }, {
+                status: 400
+            });
+        }
+        try {
+            const proposals = [];
+            const addSignedProposal = (proposal)=>{
+                if ("data" in proposal && containsSensitiveData(proposal.data)) {
+                    return {
+                        error: "Proposal contains sensitive fields and cannot be created."
+                    };
+                }
+                const signedProposal = signAIActionProposal(proposal);
+                proposals.push(signedProposal);
+                return signedProposal;
+            };
+            const collectionSlugs = getAllowedCollectionSlugs(req, options.collections);
+            const globalSlugs = req.payload.config.globals?.map((global)=>global.slug) || [];
+            const allowedCollections = req.payload.config.collections.filter((collection)=>collectionSlugs.includes(collection.slug));
+            if (collectionSlugs.length === 0) {
+                return Response.json({
+                    error: "No AI-enabled collections are configured."
+                }, {
+                    status: 400
+                });
+            }
+            const blockContexts = [
+                ...allowedCollections.flatMap((collection)=>collectBlocks({
+                        fields: collection.fields,
+                        parent: collection.slug
+                    })),
+                ...req.payload.config.globals?.flatMap((global)=>collectBlocks({
+                        fields: global.fields,
+                        parent: global.slug
+                    })) || []
+            ];
+            const mentionContext = await getMentionContext({
+                blockContexts,
+                collectionSlugs,
+                globalSlugs,
+                mentions: body?.mentions,
+                req
+            });
+            const collectionSlugSchema = z.enum(collectionSlugs);
+            const tools = {
+                getDoc: {
+                    description: "Read one document by collection slug and document id.",
+                    inputSchema: z.object({
+                        collection: collectionSlugSchema,
+                        id: z.string().min(1)
+                    }),
+                    execute: async ({ collection, id })=>{
+                        return req.payload.findByID({
+                            collection: collection,
+                            depth: 2,
+                            id,
+                            overrideAccess: false,
+                            req
+                        });
+                    }
+                },
+                listCollections: {
+                    description: "List all Payload CMS collections available in this app.",
+                    inputSchema: z.object({}),
+                    execute: async ()=>{
+                        return allowedCollections.map((collection)=>({
+                                fields: collection.fields.map(describeField),
+                                label: collection.labels?.plural || collection.slug,
+                                slug: collection.slug
+                            }));
+                    }
+                },
+                getGlobal: {
+                    description: "Read one Payload CMS global by slug.",
+                    inputSchema: z.object({
+                        slug: z.string().min(1)
+                    }),
+                    execute: async ({ slug })=>{
+                        const globalConfig = req.payload.config.globals?.find((global)=>global.slug === slug);
+                        if (!globalConfig) return {
+                            error: `Unknown global: ${slug}`
+                        };
+                        return req.payload.findGlobal({
+                            depth: 2,
+                            overrideAccess: false,
+                            req,
+                            slug: slug
+                        });
+                    }
+                },
+                listGlobals: {
+                    description: "List all Payload CMS globals available in this app.",
+                    inputSchema: z.object({}),
+                    execute: async ()=>{
+                        return req.payload.config.globals?.map((global)=>({
+                                fields: global.fields.map(describeField),
+                                label: global.label || global.slug,
+                                slug: global.slug
+                            })) || [];
+                    }
+                },
+                proposeCreateDoc: {
+                    description: "Prepare a CMS document creation proposal. This does not write to the database. Use exact field names from listCollections. For array fields, provide arrays of objects matching their child fields. For richText fields, prefer plain text or omit if unsure.",
+                    inputSchema: z.object({
+                        collection: collectionSlugSchema,
+                        data: z.record(z.string(), z.unknown()),
+                        label: z.string().min(1)
+                    }),
+                    execute: async ({ collection, data, label })=>{
+                        const proposal = {
+                            action: "create",
+                            collection,
+                            data,
+                            label
+                        };
+                        return addSignedProposal(proposal);
+                    }
+                },
+                proposeDeleteDoc: {
+                    description: "Prepare a CMS document deletion proposal. This does not write to the database.",
+                    inputSchema: z.object({
+                        collection: collectionSlugSchema,
+                        id: z.string().min(1),
+                        label: z.string().min(1)
+                    }),
+                    execute: async ({ collection, id, label })=>{
+                        const proposal = {
+                            action: "delete",
+                            collection,
+                            id,
+                            label
+                        };
+                        return addSignedProposal(proposal);
+                    }
+                },
+                proposeUpdateDoc: {
+                    description: "Prepare a CMS document update proposal. This does not write to the database. Use exact field names from listCollections. For array fields, provide arrays of objects matching their child fields. For richText fields, prefer plain text or omit if unsure.",
+                    inputSchema: z.object({
+                        collection: collectionSlugSchema,
+                        data: z.record(z.string(), z.unknown()),
+                        id: z.string().min(1),
+                        label: z.string().min(1)
+                    }),
+                    execute: async ({ collection, data, id, label })=>{
+                        const proposal = {
+                            action: "update",
+                            collection,
+                            data,
+                            id,
+                            label
+                        };
+                        return addSignedProposal(proposal);
+                    }
+                },
+                proposeUpdateGlobal: {
+                    description: "Prepare a Payload global update proposal. This does not write to the database.",
+                    inputSchema: z.object({
+                        data: z.record(z.string(), z.unknown()),
+                        label: z.string().min(1),
+                        slug: z.string().min(1)
+                    }),
+                    execute: async ({ data, label, slug })=>{
+                        const globalConfig = req.payload.config.globals?.find((global)=>global.slug === slug);
+                        if (!globalConfig) return {
+                            error: `Unknown global: ${slug}`
+                        };
+                        const proposal = {
+                            action: "updateGlobal",
+                            data,
+                            label,
+                            slug
+                        };
+                        return addSignedProposal(proposal);
+                    }
+                },
+                searchDocs: {
+                    description: "Search documents in one collection. Use query for a loose text search where possible.",
+                    inputSchema: z.object({
+                        collection: collectionSlugSchema,
+                        limit: z.number().int().min(1).max(10).default(5),
+                        query: z.string().optional()
+                    }),
+                    execute: async ({ collection, limit, query })=>{
+                        const collectionConfig = allowedCollections.find((item)=>item.slug === collection);
+                        const searchableFields = collectionConfig?.fields.filter((field)=>"name" in field && [
+                                "email",
+                                "text",
+                                "textarea"
+                            ].includes(field.type)).map((field)=>"name" in field ? field.name : null).filter(Boolean) || [];
+                        const where = query && searchableFields.length > 0 ? {
+                            or: searchableFields.map((field)=>({
+                                    [field]: {
+                                        contains: query
+                                    }
+                                }))
+                        } : undefined;
+                        return req.payload.find({
+                            collection: collection,
+                            depth: 1,
+                            limit,
+                            overrideAccess: false,
+                            req,
+                            where
+                        });
+                    }
+                }
+            };
+            const result = await generateText({
+                maxOutputTokens: 700,
+                model: getModel({
+                    apiKey: providerConfig.apiKey,
+                    model: providerConfig.modelID,
+                    provider
+                }),
+                prompt: buildPromptWithMentionContext({
+                    mentionContext,
+                    prompt
+                }),
+                stopWhen: stepCountIs(6),
+                system: [
+                    "You are a CMS assistant inside Payload CMS.",
+                    "Use tools to inspect CMS schema and content before answering content questions.",
+                    "When mention context is provided, use it as the selected CMS scope and prefer it over guessing collection names.",
+                    "Never claim that a write has been applied unless the user confirms an action proposal in the UI.",
+                    "For create, update, and delete requests, call the proposal tools instead of directly changing data.",
+                    "Keep the visible response under 80 words. Put concrete changes in proposal tool calls instead of long prose."
+                ].join("\n"),
+                tools
+            });
+            return Response.json({
+                proposals,
+                text: result.text
+            });
+        } catch (err) {
+            req.payload.logger.error({
+                debug,
+                err,
+                msg: "AI chat request failed"
+            });
+            return Response.json({
+                error: "AI request failed."
+            }, {
+                status: 500
+            });
+        }
+    };

package/dist/endpoints/aiMentionSuggestionsEndpointHandler.d.ts

@@ -0,0 +1,6 @@
+import type { PayloadHandler } from "payload";
+type AIMentionSuggestionsEndpointOptions = {
+    collections?: string[];
+};
+export declare const createAIMentionSuggestionsEndpointHandler: (options?: AIMentionSuggestionsEndpointOptions) => PayloadHandler;
+export {};

package/dist/endpoints/aiMentionSuggestionsEndpointHandler.js

@@ -0,0 +1,63 @@
+import { isInternalCollection } from "../payload/shared.js";
+const isAllowedCollectionSlug = (slug, collections)=>{
+    if (isInternalCollection(slug)) return false;
+    if (!collections) return true;
+    return collections.includes(slug);
+};
+const getDocLabel = (doc, useAsTitle)=>{
+    const titleField = useAsTitle && typeof doc[useAsTitle] === "string" ? doc[useAsTitle] : null;
+    return (titleField || doc.title || doc.name || doc.email || doc.id || "Untitled").toString();
+};
+export const createAIMentionSuggestionsEndpointHandler = (options = {})=>async (req)=>{
+        if (!req.user) return Response.json({
+            error: "Unauthorized"
+        }, {
+            status: 401
+        });
+        const body = req.json ? await req.json().catch(()=>null) : null;
+        const query = body?.query?.trim();
+        const collectionSlug = body?.collectionSlug?.trim();
+        if (!query && !collectionSlug) return Response.json({
+            suggestions: []
+        });
+        const suggestions = [];
+        const collections = req.payload.config.collections.filter((collection)=>{
+            if (!isAllowedCollectionSlug(collection.slug, options.collections)) return false;
+            if (collectionSlug) return collection.slug === collectionSlug;
+            return true;
+        });
+        for (const collection of collections){
+            const searchableFields = collection.fields.filter((field)=>"name" in field && [
+                    "email",
+                    "text",
+                    "textarea"
+                ].includes(field.type)).map((field)=>"name" in field ? field.name : null).filter(Boolean);
+            if (query && searchableFields.length === 0) continue;
+            const result = await req.payload.find({
+                collection: collection.slug,
+                depth: 0,
+                limit: 3,
+                overrideAccess: false,
+                req,
+                where: query && searchableFields.length > 0 ? {
+                    or: searchableFields.map((field)=>({
+                            [field]: {
+                                contains: query
+                            }
+                        }))
+                } : undefined
+            });
+            for (const doc of result.docs){
+                suggestions.push({
+                    collection: collection.slug,
+                    id: doc.id?.toString(),
+                    label: getDocLabel(doc, collection.admin?.useAsTitle),
+                    slug: `${collection.slug}:${doc.id?.toString()}`,
+                    type: "doc"
+                });
+            }
+        }
+        return Response.json({
+            suggestions: suggestions.slice(0, 5)
+        });
+    };

package/dist/exports/client.d.ts

@@ -0,0 +1,2 @@
+export { AIInput } from "../components/AIInput.js";
+export { AIApiKeyField } from "../components/AIApiKeyField.js";

package/dist/exports/client.js

@@ -0,0 +1,2 @@
+export { AIInput } from "../components/AIInput.js";
+export { AIApiKeyField } from "../components/AIApiKeyField.js";

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import type { CollectionSlug, Config } from "payload";
+import { type AIModelConfig } from "./ai/providerOptions.js";
+export type PayloadAiPluginOptions = {
+    collections?: Partial<Record<CollectionSlug, true>>;
+    disabled?: boolean;
+    models?: AIModelConfig;
+};
+export type PayloadAiPluginConfig = PayloadAiPluginOptions;
+export declare const payloadAiPlugin: (pluginOptions: PayloadAiPluginOptions) => (config: Config) => Config;

package/dist/index.js

@@ -0,0 +1,75 @@
+import { aiProviders, getResolvedAIModelConfig } from "./ai/providerOptions.js";
+import { createAIApplyActionEndpointHandler } from "./endpoints/aiApplyActionEndpointHandler.js";
+import { createAIChatEndpointHandler } from "./endpoints/aiChatEndpointHandler.js";
+import { createAIMentionSuggestionsEndpointHandler } from "./endpoints/aiMentionSuggestionsEndpointHandler.js";
+const getEnabledCollections = (collections)=>{
+    if (!collections) return undefined;
+    return Object.entries(collections).filter(([, enabled])=>enabled).map(([slug])=>slug);
+};
+const addAccountFields = (config)=>{
+    const adminUserSlug = config.admin?.user;
+    if (!adminUserSlug || !config.collections) return;
+    const userCollection = config.collections.find((c)=>c.slug === adminUserSlug);
+    if (!userCollection) return;
+    userCollection.fields.push({
+        name: "aiProvider",
+        type: "select",
+        defaultValue: "openai",
+        options: aiProviders
+    }, {
+        name: "aiApiKey",
+        type: "text",
+        admin: {
+            components: {
+                Field: "payload-ai-plugin/client#AIApiKeyField"
+            }
+        }
+    });
+};
+export const payloadAiPlugin = (pluginOptions)=>(config)=>{
+        const incomingOnInit = config.onInit;
+        const enabledCollections = getEnabledCollections(pluginOptions.collections);
+        const modelConfig = getResolvedAIModelConfig(pluginOptions.models);
+        if (!config.collections) config.collections = [];
+        addAccountFields(config);
+        if (pluginOptions.disabled) return config;
+        if (!config.endpoints) config.endpoints = [];
+        if (!config.admin) config.admin = {};
+        config.admin.custom = {
+            ...config.admin.custom || {},
+            payloadAiPlugin: {
+                ...config.admin.custom?.payloadAiPlugin || {},
+                models: modelConfig
+            }
+        };
+        if (!config.admin.components) config.admin.components = {};
+        if (!config.admin.components.beforeDashboard) config.admin.components.beforeDashboard = [];
+        config.admin.components.beforeDashboard.push(`payload-ai-plugin/client#AIInput`);
+        config.endpoints.push({
+            handler: createAIChatEndpointHandler({
+                collections: enabledCollections
+            }),
+            method: "post",
+            path: "/ai-chat"
+        });
+        config.endpoints.push({
+            handler: createAIApplyActionEndpointHandler({
+                collections: enabledCollections
+            }),
+            method: "post",
+            path: "/ai-apply-action"
+        });
+        config.endpoints.push({
+            handler: createAIMentionSuggestionsEndpointHandler({
+                collections: enabledCollections
+            }),
+            method: "post",
+            path: "/ai-mention-suggestions"
+        });
+        if (incomingOnInit) {
+            config.onInit = async (payload)=>{
+                await incomingOnInit(payload);
+            };
+        }
+        return config;
+    };