@mvriu5/payload-ai 1.5.0 → 1.6.1

package/README.md

@@ -25,18 +25,18 @@ npm add @mvriu5/payload-ai @openrouter/ai-sdk-provider
 ## Usage
 
 ```ts
-import { buildConfig } from "payload";
-import { payloadAiPlugin } from "@mvriu5/payload-ai";
+import { buildConfig } from "payload"
+import { payloadAiPlugin } from "@mvriu5/payload-ai"
 
 export default buildConfig({
-  plugins: [
-    payloadAiPlugin({
-      collections: {
-        posts: true,
-      },
-    }),
-  ],
-});
+    plugins: [
+        payloadAiPlugin({
+            collections: {
+                posts: true,
+            },
+        }),
+    ],
+})
 ```
 
 Without centrally configured providers, the plugin adds two fields to the configured Payload admin user collection:
@@ -51,62 +51,72 @@ When `providers` is configured, provider selection and API keys are managed cent
 ## Options
 
 ```ts
-import type { PayloadAIPluginOptions } from "@mvriu5/payload-ai";
+import type { PayloadAIPluginOptions } from "@mvriu5/payload-ai"
 
 const options: PayloadAIPluginOptions = {
-  aiInput: true,
-  allowUserApiKeys: false,
-  collections: {
-    media: {
-      read: true,
-      update: true,
+    aiInput: true,
+    allowUserApiKeys: false,
+    authCollections: {
+        aiInput: false,
+        generateFields: false,
     },
-    posts: {
-      read: true,
-      create: true,
-      update: true,
-      delete: false,
+    collections: {
+        media: {
+            read: true,
+            update: true,
+        },
+        posts: {
+            read: true,
+            create: true,
+            update: true,
+            delete: false,
+        },
+        users: true,
+    },
+    generateFields: true,
+    media: {
+        enabled: true,
+        collectionSlug: "media",
+        acceptedMimeTypes: ["image/*"],
+        maxFileSize: 10 * 1024 * 1024,
     },
-    users: true,
-  },
-  generateFields: true,
-  media: {
-    enabled: true,
-    collectionSlug: "media",
-    acceptedMimeTypes: ["image/*"],
-    maxFileSize: 10 * 1024 * 1024,
-  },
-  providers: [
-    {
-      id: "company-openai",
-      label: "Company OpenAI",
-      provider: "openai",
-      apiKey: process.env.COMPANY_OPENAI_API_KEY,
-      models: [
-        { label: "GPT-4.1 Mini", value: "gpt-4.1-mini" },
-        { label: "GPT-4.1", value: "gpt-4.1" },
-      ],
-      defaultModel: "gpt-4.1-mini",
+    providers: [
+        {
+            id: "company-openai",
+            label: "Company OpenAI",
+            provider: "openai",
+            apiKey: process.env.COMPANY_OPENAI_API_KEY,
+            models: [
+                { label: "GPT-4.1 Mini", value: "gpt-4.1-mini" },
+                { label: "GPT-4.1", value: "gpt-4.1" },
+            ],
+            defaultModel: "gpt-4.1-mini",
+        },
+        {
+            id: "ollama",
+            label: "Local Ollama",
+            provider: "openai",
+            baseURL: "http://localhost:11434/v1",
+            apiKey: "ollama",
+            models: [
+                { label: "Llama 3.3", value: "llama3.3" },
+                { label: "Qwen 3", value: "qwen3" },
+            ],
+        },
+    ],
+    maxOutputTokens: 1200,
+    promptCaching: true,
+    translate: true,
+    uploadCollections: {
+        aiInput: true,
+        generateFields: false,
     },
-    {
-      id: "ollama",
-      label: "Local Ollama",
-      provider: "openai",
-      baseURL: "http://localhost:11434/v1",
-      apiKey: "ollama",
-      models: [
-        { label: "Llama 3.3", value: "llama3.3" },
-        { label: "Qwen 3", value: "qwen3" },
-      ],
+    maxTokenUsage: {
+        type: "user",
+        perDay: 50_000,
+        perWeek: 250_000,
     },
-  ],
-  maxOutputTokens: 1200,
-  maxTokenUsage: {
-    type: "user",
-    perDay: 50_000,
-    perWeek: 250_000,
-  },
-};
+}
 ```
 
 `models` configures model choices for the user-selected provider mode. Use `providers` instead when provider selection, credentials, and endpoints should be managed centrally.
@@ -117,7 +127,7 @@ Controls whether the collapsible AI Assistant input is added to collection and g
 
 ```ts
 payloadAiPlugin({
-  aiInput: false,
+    aiInput: false,
 })
 ```
 
@@ -129,12 +139,51 @@ Controls whether supported fields receive a Generate control. It defaults to `tr
 
 ```ts
 payloadAiPlugin({
-  generateFields: false,
+    generateFields: false,
 })
 ```
 
 Generate controls are added to `text`, `textarea`, `richText`, and `json` fields in collection and global edit views. When disabled, the plugin also omits the `/ai-generate-field` endpoint. The embedded AI Assistant and dashboard remain available.
 
+### `authCollections` and `uploadCollections`
+
+Auth and upload collections do not receive the embedded AI Assistant or Generate controls by default. Enable either feature explicitly for the respective collection type:
+
+```ts
+payloadAiPlugin({
+    authCollections: {
+        aiInput: true,
+        generateFields: true,
+    },
+    uploadCollections: {
+        aiInput: true,
+        generateFields: true,
+    },
+})
+```
+
+The global `aiInput` and `generateFields` options still take precedence when set to `false`.
+
+### `translate`
+
+Controls document translation for localized collections and globals. It defaults to `true`.
+
+```ts
+payloadAiPlugin({
+    translate: false,
+})
+```
+
+When enabled, the plugin adds a `Translate` action to the document header. It is shown only when:
+
+- a non-default locale is selected
+- at least one localized field is empty in that locale
+- the corresponding field in the default locale contains source content
+
+Translation fills only empty localized fields in the current Payload form and marks it as modified. Existing translated values are never overwritten. It does not save the document or global, so the generated values can be reviewed and validated before saving.
+
+When disabled, the plugin does not register the header control or the `/ai-translate-document` endpoint.
+
 ### `collections`
 
 Restricts AI read and write proposals to enabled collection slugs. If omitted, all non-internal Payload collections are available.
@@ -143,9 +192,9 @@ Use `true` to enable all AI actions for a collection:
 
 ```ts
 payloadAiPlugin({
-  collections: {
-    posts: true,
-  },
+    collections: {
+        posts: true,
+    },
 })
 ```
 
@@ -153,14 +202,14 @@ Use granular permissions to control each action:
 
 ```ts
 payloadAiPlugin({
-  collections: {
-    posts: {
-      read: true,
-      create: true,
-      update: true,
-      delete: false,
+    collections: {
+        posts: {
+            read: true,
+            create: true,
+            update: true,
+            delete: false,
+        },
     },
-  },
 })
 ```
 
@@ -168,14 +217,14 @@ You can mix both forms in the same object:
 
 ```ts
 payloadAiPlugin({
-  collections: {
-    posts: true,
-    pages: true,
-    users: {
-      read: true,
-      update: true,
+    collections: {
+        posts: true,
+        pages: true,
+        users: {
+            read: true,
+            update: true,
+        },
     },
-  },
 })
 ```
 
@@ -187,19 +236,19 @@ Enables media uploads from the AI assistant. Uploaded files are created through
 
 ```ts
 payloadAiPlugin({
-  collections: {
+    collections: {
+        media: {
+            read: true,
+            update: true,
+        },
+        posts: true,
+    },
     media: {
-      read: true,
-      update: true,
+        enabled: true,
+        collectionSlug: "media",
+        acceptedMimeTypes: ["image/*"],
+        maxFileSize: 10 * 1024 * 1024,
     },
-    posts: true,
-  },
-  media: {
-    enabled: true,
-    collectionSlug: "media",
-    acceptedMimeTypes: ["image/*"],
-    maxFileSize: 10 * 1024 * 1024,
-  },
 })
 ```
 
@@ -254,7 +303,7 @@ Controls the maximum number of output tokens the chat endpoint may generate per
 
 ```ts
 payloadAiPlugin({
-  maxOutputTokens: 1200,
+    maxOutputTokens: 1200,
 })
 ```
 
@@ -264,11 +313,11 @@ Limits total AI tokens across rolling 24-hour and 7-day windows.
 
 ```ts
 payloadAiPlugin({
-  maxTokenUsage: {
-    type: "user",
-    perDay: 50_000,
-    perWeek: 250_000,
-  },
+    maxTokenUsage: {
+        type: "user",
+        perDay: 50_000,
+        perWeek: 250_000,
+    },
 })
 ```
 
@@ -276,13 +325,25 @@ Use `type: "user"` to enforce separate budgets per authenticated user, or `type:
 
 Completed model usage is stored in the hidden `payload-ai-usage` collection. Requests made after a limit is reached return HTTP `429`. Because providers report token usage after completion, the request that crosses a limit is allowed to finish and subsequent requests are blocked.
 
+### `promptCaching`
+
+Enables provider prompt-caching hints and defaults to `true`. The chat endpoint keeps static instructions and Payload schemas in a stable prompt prefix, adds Anthropic cache-control breakpoints, and supplies a stable OpenAI prompt cache key. Gemini uses the same stable prefix with its implicit caching.
+
+```ts
+payloadAiPlugin({
+    promptCaching: false,
+})
+```
+
+Disable it when explicit provider-side caching is not desired. Dynamic document data and user prompts are never placed in the cacheable schema section. Managed providers with a custom `baseURL` receive the stable prefix but no provider-specific cache parameters, preserving compatibility with Ollama, vLLM, and other OpenAI-compatible endpoints.
+
 ### `allowUserApiKeys`
 
 Controls whether the plugin adds an `aiApiKey` field to the admin user collection.
 
 ```ts
 payloadAiPlugin({
-  allowUserApiKeys: false,
+    allowUserApiKeys: false,
 })
 ```
 
@@ -322,12 +383,12 @@ The apply endpoint returns only minimal status/doc references and does not retur
 ## Exports
 
 ```ts
-import { payloadAiPlugin } from "@mvriu5/payload-ai";
-import type { PayloadAiPluginOptions } from "@mvriu5/payload-ai";
+import { payloadAiPlugin } from "@mvriu5/payload-ai"
+import type { PayloadAiPluginOptions } from "@mvriu5/payload-ai"
 ```
 
 Client components are exported through:
 
 ```ts
-import { AIInput, AIApiKeyField } from "@mvriu5/payload-ai/client";
+import { AIInput, AIApiKeyField } from "@mvriu5/payload-ai/client"
 ```

package/dist/ai/promptCaching.d.ts

@@ -0,0 +1,23 @@
+import type { SystemModelMessage } from "ai";
+import type { AIProvider } from "./providerOptions.js";
+type PromptCacheContext = {
+    cacheable: Record<string, unknown>[];
+    dynamic: Record<string, unknown>[];
+};
+type PromptCacheProviderOptions = NonNullable<SystemModelMessage["providerOptions"]>;
+export declare const splitPromptCacheContext: (mentionContext: Record<string, unknown>[]) => PromptCacheContext;
+export declare const createCachedSystemMessages: ({ cacheableContext, cacheableInstructions, dynamicInstructions, enabled, provider, staticInstructions, }: {
+    cacheableContext: Record<string, unknown>[];
+    cacheableInstructions: string[];
+    dynamicInstructions: string[];
+    enabled: boolean;
+    provider: AIProvider;
+    staticInstructions: string[];
+}) => SystemModelMessage[];
+export declare const createPromptCacheProviderOptions: ({ cacheKeyParts, enabled, model, provider, }: {
+    cacheKeyParts: unknown[];
+    enabled: boolean;
+    model: string;
+    provider: AIProvider;
+}) => PromptCacheProviderOptions | undefined;
+export {};

package/dist/ai/promptCaching.js

@@ -0,0 +1,120 @@
+import { createHash } from "node:crypto";
+const getContextKey = (context)=>{
+    return [
+        context.type,
+        context.parent,
+        context.collection,
+        context.slug
+    ].filter(Boolean).join(":") || JSON.stringify(context);
+};
+export const splitPromptCacheContext = (mentionContext)=>{
+    const cacheable = [];
+    const dynamic = [];
+    const cacheableKeys = new Set();
+    const addCacheable = (context)=>{
+        const key = getContextKey(context);
+        if (cacheableKeys.has(key)) return;
+        cacheableKeys.add(key);
+        cacheable.push(context);
+    };
+    for (const context of mentionContext){
+        if ([
+            "block",
+            "collection"
+        ].includes(String(context.type))) {
+            addCacheable(context);
+            continue;
+        }
+        if (context.type === "global" && "doc" in context) {
+            const { doc, ...schema } = context;
+            addCacheable(schema);
+            dynamic.push({
+                doc,
+                slug: context.slug,
+                type: "globalDocument"
+            });
+            continue;
+        }
+        if (context.type === "global") {
+            addCacheable(context);
+            continue;
+        }
+        if (context.type === "mediaAttachment" && context.schema && typeof context.schema === "object") {
+            addCacheable(context.schema);
+            const { schema: _schema, ...attachmentContext } = context;
+            dynamic.push(attachmentContext);
+            continue;
+        }
+        dynamic.push(context);
+    }
+    return {
+        cacheable,
+        dynamic
+    };
+};
+const withAnthropicCacheControl = (message, enabled, provider)=>{
+    if (!enabled || provider !== "claude") return message;
+    return {
+        ...message,
+        providerOptions: {
+            anthropic: {
+                cacheControl: {
+                    type: "ephemeral"
+                }
+            }
+        }
+    };
+};
+export const createCachedSystemMessages = ({ cacheableContext, cacheableInstructions, dynamicInstructions, enabled, provider, staticInstructions })=>{
+    const messages = [
+        withAnthropicCacheControl({
+            content: staticInstructions.join("\n"),
+            role: "system"
+        }, enabled, provider)
+    ];
+    const scopedContent = [
+        ...cacheableContext.length ? [
+            "Payload schema references JSON. Use exact field names and values:",
+            JSON.stringify(cacheableContext)
+        ] : [],
+        ...cacheableInstructions
+    ];
+    if (scopedContent.length > 0) {
+        messages.push(withAnthropicCacheControl({
+            content: scopedContent.join("\n"),
+            role: "system"
+        }, enabled, provider));
+    }
+    if (dynamicInstructions.length > 0) {
+        messages.push({
+            content: dynamicInstructions.join("\n"),
+            role: "system"
+        });
+    }
+    return messages;
+};
+export const createPromptCacheProviderOptions = ({ cacheKeyParts, enabled, model, provider })=>{
+    if (!enabled) return undefined;
+    if (provider === "openai") {
+        const digest = createHash("sha256").update(JSON.stringify([
+            "payload-ai-v1",
+            model,
+            ...cacheKeyParts
+        ])).digest("hex").slice(0, 32);
+        return {
+            openai: {
+                promptCacheKey: `payload-ai-${digest}`
+            }
+        };
+    }
+    if (provider === "openrouter" && model.toLowerCase().startsWith("anthropic/")) {
+        return {
+            openrouter: {
+                cache_control: {
+                    type: "ephemeral"
+                }
+            }
+        };
+    }
+    return undefined;
+};

package/dist/ai/proposalRepair.d.ts

@@ -0,0 +1,30 @@
+import type { ProposalValidationIssue } from "../payload/proposalData.js";
+export declare const maxProposalRepairAttempts = 1;
+export type CompactProposalRepairIssue = {
+    code: string;
+    hint: string;
+    path: string;
+};
+type ProposalRepairTarget = {
+    collection?: string;
+    id?: string;
+    slug?: string;
+    tool: string;
+};
+export declare const compactProposalRepairIssues: (issues: ProposalValidationIssue[]) => CompactProposalRepairIssue[];
+export declare const createProposalRepairKey: ({ collection, id, slug, tool }: ProposalRepairTarget) => string;
+export declare const createProposalRepairTracker: () => {
+    beginCall(target: ProposalRepairTarget): "initial" | "blocked" | "repair";
+    registerFailure(target: ProposalRepairTarget): {
+        attempt: number;
+        errorCode: "REPAIR_EXHAUSTED";
+        maxAttempts: number;
+        retryable: boolean;
+    } | {
+        attempt: number;
+        errorCode: "INVALID_PROPOSAL_DATA";
+        maxAttempts: number;
+        retryable: boolean;
+    };
+};
+export {};

package/dist/ai/proposalRepair.js

@@ -0,0 +1,76 @@
+export const maxProposalRepairAttempts = 1;
+const getIssueHint = (issue)=>{
+    switch(issue.code){
+        case "invalid_array":
+            return "Use an array of complete objects matching the child fields.";
+        case "invalid_block_type":
+            return "Use an exact blockType from the schema.";
+        case "invalid_blocks":
+            return "Use an array of block objects with blockType and exact field names.";
+        case "invalid_checkbox":
+            return "Use true or false.";
+        case "invalid_container":
+            return "Use an object matching the nested field schema.";
+        case "invalid_date":
+            return "Use a valid date string.";
+        case "invalid_option":
+            return issue.message;
+        case "invalid_relationship":
+            return "Use an existing document ID or { relationTo, value } for polymorphic relationships.";
+        case "missing_required_field":
+            return "Add the required field with a schema-compatible value.";
+        case "non_localized_field_in_secondary_locale":
+            return "Move this field to the primary locale data.";
+        case "unknown_field":
+            return "Remove it and use exact schema field names only.";
+        default:
+            return issue.message;
+    }
+};
+export const compactProposalRepairIssues = (issues)=>{
+    return issues.slice(0, 6).map((issue)=>({
+            code: issue.code,
+            hint: getIssueHint(issue).slice(0, 180),
+            path: issue.path
+        }));
+};
+export const createProposalRepairKey = ({ collection, id, slug, tool })=>{
+    return [
+        tool,
+        collection || slug || "",
+        id || ""
+    ].join(":");
+};
+export const createProposalRepairTracker = ()=>{
+    const statesByTarget = new Map();
+    return {
+        beginCall (target) {
+            const state = statesByTarget.get(createProposalRepairKey(target));
+            if (!state) return "initial";
+            if (state.repairCallConsumed) return "blocked";
+            state.repairCallConsumed = true;
+            return "repair";
+        },
+        registerFailure (target) {
+            const key = createProposalRepairKey(target);
+            const state = statesByTarget.get(key);
+            if (state) {
+                return {
+                    attempt: maxProposalRepairAttempts,
+                    errorCode: "REPAIR_EXHAUSTED",
+                    maxAttempts: maxProposalRepairAttempts,
+                    retryable: false
+                };
+            }
+            statesByTarget.set(key, {
+                repairCallConsumed: false
+            });
+            return {
+                attempt: 1,
+                errorCode: "INVALID_PROPOSAL_DATA",
+                maxAttempts: maxProposalRepairAttempts,
+                retryable: true
+            };
+        }
+    };
+};

package/dist/ai/sensitiveData.d.ts

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

package/dist/ai/sensitiveData.js

@@ -5,10 +5,12 @@ const sensitiveKeyPatterns = [
     /^aiApiKey$/i,
     /^authorization$/i,
     /^accessToken$/i,
+    /^password$/i,
+    /^privateKey$/i,
     /^refreshToken$/i,
     /^secret$/i
 ];
-const isSensitiveKey = (key)=>sensitiveKeyPatterns.some((pattern)=>pattern.test(key));
+export const isSensitiveKey = (key)=>sensitiveKeyPatterns.some((pattern)=>pattern.test(key));
 export const containsSensitiveData = (value)=>{
     if (Array.isArray(value)) return value.some(containsSensitiveData);
     if (!isRecord(value)) return false;

package/dist/components/ai-input/AIInput.d.ts

@@ -1,5 +1,5 @@
 type AIInputProps = {
     isDashboard?: boolean;
 };
-declare const AIInput: ({ isDashboard }: AIInputProps) => import("react").JSX.Element;
+declare const AIInput: ({ isDashboard }: AIInputProps) => import("react").JSX.Element | null;
 export default AIInput;

package/dist/components/ai-input/AIInput.js

@@ -1,6 +1,6 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { Button, ChevronIcon, useConfig, useDocumentForm, useDocumentInfo, useLocale } from "@payloadcms/ui";
+import { Button, ChevronIcon, useAuth, useConfig, useDocumentForm, useDocumentInfo, useLocale } from "@payloadcms/ui";
 import { formatAdminURL } from "payload/shared";
 import { useEffect, useRef, useState } from "react";
 import { mergeData } from "../../payload/shared.js";
@@ -540,6 +540,8 @@ const DocumentAIInput = ()=>{
     });
 };
 const AIInput = ({ isDashboard = false })=>{
+    const { user } = useAuth();
+    if (!user) return null;
     if (isDashboard) return /*#__PURE__*/ _jsx(AIInputCore, {
         isDashboard: true
     });

package/dist/components/generate-field/GenerateField.js

@@ -1,6 +1,6 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useConfig, useDocumentForm, useDocumentInfo, useField, useLocale } from "@payloadcms/ui";
+import { useAuth, useConfig, useDocumentForm, useDocumentInfo, useField, useLocale } from "@payloadcms/ui";
 import { formatAdminURL } from "payload/shared";
 import { useState } from "react";
 import { createGeneratedRichTextValue } from "./richText.js";
@@ -27,6 +27,7 @@ const requestGeneratedValue = ({ apiRoute, body, cacheKey })=>{
     return request;
 };
 const GenerateField = ({ field, generationFieldKey, generationFieldType, path, readOnly })=>{
+    const { user } = useAuth();
     const configContext = useConfig();
     const documentForm = useDocumentForm();
     const documentInfo = useDocumentInfo();
@@ -87,7 +88,7 @@ const GenerateField = ({ field, generationFieldKey, generationFieldType, path, r
             setIsGenerating(false);
         }
     };
-    if (!scope) return null;
+    if (!user || !scope) return null;
     return /*#__PURE__*/ _jsxs("div", {
         className: styles.generateField,
         children: [