@mvriu5/payload-ai 0.5.0

package/README.md

@@ -0,0 +1,99 @@
+# payload-ai-plugin
+
+AI assistant plugin for Payload CMS. It adds an admin dashboard assistant that can read CMS context, use mentions, and create signed action proposals for create, update, delete, and global updates.
+
+## Install
+
+```bash
+pnpm add payload-ai-plugin
+```
+
+## Usage
+
+```ts
+import { buildConfig } from "payload";
+import { payloadAiPlugin } from "payload-ai-plugin";
+
+export default buildConfig({
+  plugins: [
+    payloadAiPlugin({
+      collections: {
+        posts: true,
+      },
+    }),
+  ],
+});
+```
+
+The plugin adds two fields to the configured Payload admin user collection:
+
+- `aiProvider`
+- `aiApiKey`
+
+Users can select their provider and store their own API key in account settings. The key is used server-side when the chat endpoint calls the selected model.
+
+## Options
+
+```ts
+import type { PayloadAiPluginOptions } from "payload-ai-plugin";
+
+const options: PayloadAiPluginOptions = {
+  collections: {
+    posts: true,
+  },
+  models: {
+    defaults: {
+      openai: "gpt-4.1-mini",
+    },
+    providers: {
+      openai: [
+        { label: "GPT-4.1 Mini", value: "gpt-4.1-mini" },
+        { label: "GPT-4.1", value: "gpt-4.1" },
+      ],
+    },
+  },
+};
+```
+
+### `collections`
+
+Restricts AI read and write proposals to enabled collection slugs. If omitted, all non-internal Payload collections are available.
+
+### `models`
+
+Overrides the model list shown in the admin UI and the default model per provider.
+
+### `disabled`
+
+Disables endpoint and UI registration while keeping the plugin call in your config.
+
+## Provider Environment Variables
+
+Account-level API keys take priority. If a user has no key configured, the server falls back to provider environment variables:
+
+- `OPENAI_API_KEY`, `OPENAI_MODEL`
+- `ANTHROPIC_API_KEY`, `ANTHROPIC_MODEL`
+- `GOOGLE_GENERATIVE_AI_API_KEY`, `GOOGLE_GENERATIVE_AI_MODEL`
+- `GROQ_API_KEY`, `GROQ_MODEL`
+- `MISTRAL_API_KEY`, `MISTRAL_MODEL`
+
+`PAYLOAD_SECRET` is required for signing AI action proposals.
+
+## Security
+
+AI write operations are proposal-based. The chat endpoint signs every proposal with an HMAC signature and a short TTL. The apply endpoint verifies the signature, validates the target collection/global, enforces Payload access control with `overrideAccess: false`, and rejects proposals containing sensitive API-key-like fields.
+
+The apply endpoint returns only minimal status/doc references and does not return normalized data, proposal payloads, API keys, or raw error details to the client.
+
+## Exports
+
+```ts
+import { payloadAiPlugin } from "payload-ai-plugin";
+import type { PayloadAiPluginOptions } from "payload-ai-plugin";
+```
+
+Client components are exported through:
+
+```ts
+import { AIInput, AIApiKeyField } from "payload-ai-plugin/client";
+```

package/dist/ai/proposals.d.ts

@@ -0,0 +1,12 @@
+export type AIActionSignature = {
+    expiresAt: string;
+    value: string;
+};
+type SignableProposal = Record<string, unknown> & {
+    _aiSignature?: AIActionSignature;
+};
+export declare const signAIActionProposal: <Proposal extends SignableProposal>(proposal: Proposal) => Proposal & {
+    _aiSignature: AIActionSignature;
+};
+export declare const verifyAIActionProposal: (proposal: SignableProposal) => boolean;
+export {};

package/dist/ai/proposals.js

@@ -0,0 +1,50 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+const signatureTTL = 10 * 60 * 1000;
+const stableStringify = (value)=>{
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(",")}]`;
+    }
+    if (value && typeof value === "object") {
+        const entries = Object.entries(value).filter(([key])=>key !== "_aiSignature").sort(([a], [b])=>a.localeCompare(b));
+        return `{${entries.map(([key, entryValue])=>`${JSON.stringify(key)}:${stableStringify(entryValue)}`).join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "undefined";
+};
+const getSigningSecret = ()=>{
+    const secret = process.env.PAYLOAD_SECRET;
+    if (!secret) {
+        throw new Error("PAYLOAD_SECRET is required to sign AI proposals.");
+    }
+    return secret;
+};
+const getSignaturePayload = (proposal, expiresAt)=>{
+    return stableStringify({
+        expiresAt,
+        proposal
+    });
+};
+const signPayload = (payload)=>{
+    return createHmac("sha256", getSigningSecret()).update(payload).digest("hex");
+};
+export const signAIActionProposal = (proposal)=>{
+    const expiresAt = new Date(Date.now() + signatureTTL).toISOString();
+    const value = signPayload(getSignaturePayload(proposal, expiresAt));
+    return {
+        ...proposal,
+        _aiSignature: {
+            expiresAt,
+            value
+        }
+    };
+};
+export const verifyAIActionProposal = (proposal)=>{
+    const signature = proposal._aiSignature;
+    if (!signature?.expiresAt || !signature.value) return false;
+    if (Number.isNaN(new Date(signature.expiresAt).getTime())) return false;
+    if (new Date(signature.expiresAt).getTime() < Date.now()) return false;
+    const expected = signPayload(getSignaturePayload(proposal, signature.expiresAt));
+    const expectedBuffer = Buffer.from(expected, "hex");
+    const actualBuffer = Buffer.from(signature.value, "hex");
+    if (expectedBuffer.length !== actualBuffer.length) return false;
+    return timingSafeEqual(expectedBuffer, actualBuffer);
+};

package/dist/ai/providerOptions.d.ts

@@ -0,0 +1,85 @@
+type AIProviderModelOption = {
+    label: string;
+    value: string;
+};
+declare const aiProviderModels: {
+    readonly claude: readonly [{
+        readonly label: "Claude 3 Haiku";
+        readonly value: "claude-3-haiku-20240307";
+    }, {
+        readonly label: "Claude Sonnet 4.5";
+        readonly value: "claude-sonnet-4-5";
+    }, {
+        readonly label: "Claude Sonnet 4";
+        readonly value: "claude-sonnet-4-0";
+    }];
+    readonly google: readonly [{
+        readonly label: "Gemini 2.0 Flash";
+        readonly value: "gemini-2.0-flash";
+    }, {
+        readonly label: "Gemini 2.5 Flash";
+        readonly value: "gemini-2.5-flash";
+    }, {
+        readonly label: "Gemini 2.5 Flash Lite";
+        readonly value: "gemini-2.5-flash-lite";
+    }, {
+        readonly label: "Gemini 2.5 Pro";
+        readonly value: "gemini-2.5-pro";
+    }];
+    readonly groq: readonly [{
+        readonly label: "Llama 3.3 70B Versatile";
+        readonly value: "llama-3.3-70b-versatile";
+    }, {
+        readonly label: "Llama 3.1 8B Instant";
+        readonly value: "llama-3.1-8b-instant";
+    }, {
+        readonly label: "GPT OSS 120B";
+        readonly value: "openai/gpt-oss-120b";
+    }, {
+        readonly label: "GPT OSS 20B";
+        readonly value: "openai/gpt-oss-20b";
+    }];
+    readonly mistral: readonly [{
+        readonly label: "Mistral Small";
+        readonly value: "mistral-small-latest";
+    }, {
+        readonly label: "Mistral Medium";
+        readonly value: "mistral-medium-latest";
+    }, {
+        readonly label: "Mistral Large";
+        readonly value: "mistral-large-latest";
+    }, {
+        readonly label: "Ministral 8B";
+        readonly value: "ministral-8b-latest";
+    }];
+    readonly openai: readonly [{
+        readonly label: "GPT-4.1 Mini";
+        readonly value: "gpt-4.1-mini";
+    }, {
+        readonly label: "GPT-4.1 Nano";
+        readonly value: "gpt-4.1-nano";
+    }, {
+        readonly label: "GPT-4.1";
+        readonly value: "gpt-4.1";
+    }, {
+        readonly label: "GPT-4o Mini";
+        readonly value: "gpt-4o-mini";
+    }];
+};
+export type AIProvider = keyof typeof aiProviderModels;
+type AIProviderModels = Record<AIProvider, AIProviderModelOption[]>;
+export declare const aiProviders: {
+    label: string;
+    value: AIProvider;
+}[];
+export declare const defaultAIModels: Record<AIProvider, string>;
+export type AIModelConfig = {
+    defaults?: Partial<Record<AIProvider, string>>;
+    providers?: Partial<Record<AIProvider, AIProviderModelOption[]>>;
+};
+export declare const getResolvedAIModelConfig: (modelConfig?: AIModelConfig) => {
+    defaults: Record<"claude" | "google" | "groq" | "mistral" | "openai", string>;
+    providers: AIProviderModels;
+};
+export declare const isAIProvider: (provider: string) => provider is AIProvider;
+export {};

package/dist/ai/providerOptions.js

@@ -0,0 +1,141 @@
+const aiProviderModels = {
+    claude: [
+        {
+            label: "Claude 3 Haiku",
+            value: "claude-3-haiku-20240307"
+        },
+        {
+            label: "Claude Sonnet 4.5",
+            value: "claude-sonnet-4-5"
+        },
+        {
+            label: "Claude Sonnet 4",
+            value: "claude-sonnet-4-0"
+        }
+    ],
+    google: [
+        {
+            label: "Gemini 2.0 Flash",
+            value: "gemini-2.0-flash"
+        },
+        {
+            label: "Gemini 2.5 Flash",
+            value: "gemini-2.5-flash"
+        },
+        {
+            label: "Gemini 2.5 Flash Lite",
+            value: "gemini-2.5-flash-lite"
+        },
+        {
+            label: "Gemini 2.5 Pro",
+            value: "gemini-2.5-pro"
+        }
+    ],
+    groq: [
+        {
+            label: "Llama 3.3 70B Versatile",
+            value: "llama-3.3-70b-versatile"
+        },
+        {
+            label: "Llama 3.1 8B Instant",
+            value: "llama-3.1-8b-instant"
+        },
+        {
+            label: "GPT OSS 120B",
+            value: "openai/gpt-oss-120b"
+        },
+        {
+            label: "GPT OSS 20B",
+            value: "openai/gpt-oss-20b"
+        }
+    ],
+    mistral: [
+        {
+            label: "Mistral Small",
+            value: "mistral-small-latest"
+        },
+        {
+            label: "Mistral Medium",
+            value: "mistral-medium-latest"
+        },
+        {
+            label: "Mistral Large",
+            value: "mistral-large-latest"
+        },
+        {
+            label: "Ministral 8B",
+            value: "ministral-8b-latest"
+        }
+    ],
+    openai: [
+        {
+            label: "GPT-4.1 Mini",
+            value: "gpt-4.1-mini"
+        },
+        {
+            label: "GPT-4.1 Nano",
+            value: "gpt-4.1-nano"
+        },
+        {
+            label: "GPT-4.1",
+            value: "gpt-4.1"
+        },
+        {
+            label: "GPT-4o Mini",
+            value: "gpt-4o-mini"
+        }
+    ]
+};
+export const aiProviders = [
+    {
+        label: "Claude",
+        value: "claude"
+    },
+    {
+        label: "Google Gemini",
+        value: "google"
+    },
+    {
+        label: "Groq",
+        value: "groq"
+    },
+    {
+        label: "Mistral",
+        value: "mistral"
+    },
+    {
+        label: "OpenAI",
+        value: "openai"
+    }
+];
+export const defaultAIModels = {
+    claude: aiProviderModels.claude[0].value,
+    google: aiProviderModels.google[0].value,
+    groq: aiProviderModels.groq[0].value,
+    mistral: aiProviderModels.mistral[0].value,
+    openai: aiProviderModels.openai[0].value
+};
+export const getResolvedAIModelConfig = (modelConfig)=>{
+    const providers = Object.fromEntries(Object.entries(aiProviderModels).map(([provider, models])=>[
+            provider,
+            modelConfig?.providers?.[provider] || [
+                ...models
+            ]
+        ]));
+    const defaults = Object.fromEntries(Object.entries(defaultAIModels).map(([provider, defaultModel])=>{
+        const providerKey = provider;
+        const configuredDefault = modelConfig?.defaults?.[providerKey];
+        const providerModels = providers[providerKey];
+        return [
+            provider,
+            configuredDefault || providerModels[0]?.value || defaultModel
+        ];
+    }));
+    return {
+        defaults,
+        providers
+    };
+};
+export const isAIProvider = (provider)=>{
+    return provider in aiProviderModels;
+};

package/dist/ai/providerRuntime.d.ts

@@ -0,0 +1,18 @@
+import type { LanguageModel } from "ai";
+import { type AIProvider } from "./providerOptions.js";
+type ProviderConfig = {
+    apiKey?: string | null;
+    model?: string | null;
+    provider: AIProvider;
+};
+type ModelConfig = {
+    apiKey: string;
+    model: string;
+    provider: AIProvider;
+};
+export declare const getProviderConfig: ({ apiKey, model, provider, }: ProviderConfig) => {
+    apiKey: string | undefined;
+    modelID: string;
+};
+export declare const getModel: ({ apiKey, model, provider }: ModelConfig) => LanguageModel;
+export {};

package/dist/ai/providerRuntime.js

@@ -0,0 +1,53 @@
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { createGoogleGenerativeAI } from "@ai-sdk/google";
+import { createGroq } from "@ai-sdk/groq";
+import { createMistral } from "@ai-sdk/mistral";
+import { createOpenAI } from "@ai-sdk/openai";
+import { defaultAIModels } from "./providerOptions.js";
+export const getProviderConfig = ({ apiKey, model, provider })=>{
+    if (provider === "claude") {
+        return {
+            apiKey: apiKey || process.env.ANTHROPIC_API_KEY,
+            modelID: model || process.env.ANTHROPIC_MODEL || defaultAIModels.claude
+        };
+    }
+    if (provider === "google") {
+        return {
+            apiKey: apiKey || process.env.GOOGLE_GENERATIVE_AI_API_KEY,
+            modelID: model || process.env.GOOGLE_GENERATIVE_AI_MODEL || defaultAIModels.google
+        };
+    }
+    if (provider === "groq") {
+        return {
+            apiKey: apiKey || process.env.GROQ_API_KEY,
+            modelID: model || process.env.GROQ_MODEL || defaultAIModels.groq
+        };
+    }
+    if (provider === "mistral") {
+        return {
+            apiKey: apiKey || process.env.MISTRAL_API_KEY,
+            modelID: model || process.env.MISTRAL_MODEL || defaultAIModels.mistral
+        };
+    }
+    return {
+        apiKey: apiKey || process.env.OPENAI_API_KEY,
+        modelID: model || process.env.OPENAI_MODEL || defaultAIModels.openai
+    };
+};
+export const getModel = ({ apiKey, model, provider })=>{
+    if (provider === "claude") return createAnthropic({
+        apiKey
+    })(model);
+    if (provider === "google") return createGoogleGenerativeAI({
+        apiKey
+    })(model);
+    if (provider === "groq") return createGroq({
+        apiKey
+    })(model);
+    if (provider === "mistral") return createMistral({
+        apiKey
+    })(model);
+    return createOpenAI({
+        apiKey
+    })(model);
+};

package/dist/ai/sensitiveData.d.ts

@@ -0,0 +1,2 @@
+export declare const containsSensitiveData: (value: unknown) => boolean;
+export declare const redactSensitiveData: (value: unknown) => unknown;

package/dist/ai/sensitiveData.js

@@ -0,0 +1,30 @@
+const sensitiveKeyPatterns = [
+    /^apiKey$/i,
+    /^api_key$/i,
+    /^aiApiKey$/i,
+    /^authorization$/i,
+    /^accessToken$/i,
+    /^refreshToken$/i,
+    /^secret$/i
+];
+const isRecord = (value)=>{
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+};
+const isSensitiveKey = (key)=>{
+    return sensitiveKeyPatterns.some((pattern)=>pattern.test(key));
+};
+export const containsSensitiveData = (value)=>{
+    if (Array.isArray(value)) return value.some(containsSensitiveData);
+    if (!isRecord(value)) return false;
+    return Object.entries(value).some(([key, entryValue])=>{
+        return isSensitiveKey(key) || containsSensitiveData(entryValue);
+    });
+};
+export const redactSensitiveData = (value)=>{
+    if (Array.isArray(value)) return value.map(redactSensitiveData);
+    if (!isRecord(value)) return value;
+    return Object.fromEntries(Object.entries(value).map(([key, entryValue])=>[
+            key,
+            isSensitiveKey(key) ? "[redacted]" : redactSensitiveData(entryValue)
+        ]));
+};

package/dist/components/AIActionProposalList.d.ts

@@ -0,0 +1,25 @@
+export type AIActionProposal = {
+    _aiSignature?: {
+        expiresAt: string;
+        value: string;
+    };
+    action: "create" | "delete" | "update" | "updateGlobal";
+    collection?: string;
+    data?: Record<string, unknown>;
+    id?: string;
+    label: string;
+    slug?: string;
+};
+type AIActionProposalListProps = {
+    appliedProposalIndexes: number[];
+    description?: string;
+    error?: string;
+    getViewURL?: (proposal: AIActionProposal) => string | null;
+    isApplying: boolean;
+    onDismiss?: () => void;
+    onDismissError?: () => void;
+    onApply: (proposal: AIActionProposal, index: number) => void;
+    proposals: AIActionProposal[];
+};
+export declare const AIActionProposalList: ({ appliedProposalIndexes, description, error, getViewURL, isApplying, onDismiss, onDismissError, onApply, proposals, }: AIActionProposalListProps) => import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/components/AIActionProposalList.js

@@ -0,0 +1,94 @@
+import styles from "./AIActionProposalList.module.css";
+import { redactSensitiveData } from "../ai/sensitiveData.js";
+const maxDescriptionLength = 220;
+const getDescriptionPreview = (description)=>{
+    if (description.length <= maxDescriptionLength) return description;
+    return `${description.slice(0, maxDescriptionLength).trim()}...`;
+};
+const getSafeProposalDetails = (proposal)=>{
+    const redactedProposal = redactSensitiveData(proposal);
+    if (redactedProposal._aiSignature) {
+        redactedProposal._aiSignature = {
+            expiresAt: redactedProposal._aiSignature.expiresAt,
+            value: "[redacted]"
+        };
+    }
+    return redactedProposal;
+};
+export const AIActionProposalList = ({ appliedProposalIndexes, description, error, getViewURL, isApplying, onDismiss, onDismissError, onApply, proposals })=>{
+    if (proposals.length === 0 && !error && !description) return null;
+    const descriptionPreview = description ? getDescriptionPreview(description) : "";
+    const isDescriptionTruncated = Boolean(description) && descriptionPreview !== description;
+    return /*#__PURE__*/ React.createElement("div", {
+        className: styles.list
+    }, error && /*#__PURE__*/ React.createElement("div", {
+        className: `${styles.item} ${styles.errorItem}`
+    }, /*#__PURE__*/ React.createElement("div", null, /*#__PURE__*/ React.createElement("div", {
+        className: styles.label
+    }, "AI request failed"), /*#__PURE__*/ React.createElement("div", {
+        className: styles.description
+    }, error)), onDismissError && /*#__PURE__*/ React.createElement("button", {
+        className: styles.button,
+        onClick: onDismissError,
+        type: "button"
+    }, "Dismiss")), !error && proposals.length === 0 && description && /*#__PURE__*/ React.createElement("div", {
+        className: styles.item
+    }, /*#__PURE__*/ React.createElement("div", null, /*#__PURE__*/ React.createElement("div", {
+        className: styles.label
+    }, "AI response"), /*#__PURE__*/ React.createElement("div", {
+        className: styles.description
+    }, descriptionPreview), isDescriptionTruncated ? /*#__PURE__*/ React.createElement("details", {
+        className: styles.details
+    }, /*#__PURE__*/ React.createElement("summary", {
+        className: styles.summary
+    }, "Full response"), /*#__PURE__*/ React.createElement("pre", {
+        className: styles.proposalDetails
+    }, description)) : null)), proposals.map((proposal, index)=>{
+        const isApplied = appliedProposalIndexes.includes(index);
+        const viewURL = getViewURL?.(proposal);
+        return /*#__PURE__*/ React.createElement("div", {
+            className: styles.item,
+            key: `${proposal.action}-${index}`
+        }, /*#__PURE__*/ React.createElement("div", {
+            className: styles.content
+        }, /*#__PURE__*/ React.createElement("div", {
+            className: styles.label
+        }, proposal.label), /*#__PURE__*/ React.createElement("div", {
+            className: styles.meta
+        }, proposal.action, " in ", proposal.collection || proposal.slug, proposal.id ? ` #${proposal.id}` : ""), description && /*#__PURE__*/ React.createElement("div", {
+            className: styles.description
+        }, descriptionPreview), description && isDescriptionTruncated && /*#__PURE__*/ React.createElement("details", {
+            className: styles.details
+        }, /*#__PURE__*/ React.createElement("summary", {
+            className: styles.summary
+        }, "Full response"), /*#__PURE__*/ React.createElement("pre", {
+            className: styles.proposalDetails
+        }, description)), /*#__PURE__*/ React.createElement("details", {
+            className: styles.details
+        }, /*#__PURE__*/ React.createElement("summary", {
+            className: styles.summary
+        }, "Details"), /*#__PURE__*/ React.createElement("pre", {
+            className: styles.proposalDetails
+        }, JSON.stringify(getSafeProposalDetails(proposal), null, 2)))), /*#__PURE__*/ React.createElement("div", {
+            className: styles.footer
+        }, /*#__PURE__*/ React.createElement("div", {
+            className: styles.viewAction
+        }, viewURL && /*#__PURE__*/ React.createElement("a", {
+            className: styles.secondaryButton,
+            href: viewURL,
+            rel: "noreferrer noopener",
+            target: "_blank"
+        }, "View")), /*#__PURE__*/ React.createElement("div", {
+            className: styles.actions
+        }, onDismiss && /*#__PURE__*/ React.createElement("button", {
+            className: styles.secondaryButton,
+            onClick: onDismiss,
+            type: "button"
+        }, "Dismiss"), /*#__PURE__*/ React.createElement("button", {
+            className: styles.button,
+            disabled: isApplying || isApplied,
+            onClick: ()=>onApply(proposal, index),
+            type: "button"
+        }, isApplied ? "Applied" : "Apply"))));
+    }));
+};