@mvriu5/payload-ai 1.5.0 → 1.6.0

package/dist/handlers/translateDocumentHandler.d.ts

@@ -0,0 +1,14 @@
+import type { PayloadHandler } from "payload";
+import { type AIModelConfig, type ResolvedAIProviderConfig } from "../ai/providerOptions.js";
+import { type ResolvedMaxTokenUsageOptions } from "../ai/tokenUsage.js";
+import { type TranslationPageContext } from "../payload/documentTranslation.js";
+type TranslateDocumentOptions = {
+    allowUserApiKeys?: boolean;
+    maxOutputTokens?: number;
+    maxTokenUsage?: ResolvedMaxTokenUsageOptions;
+    models?: AIModelConfig;
+    pageContexts: Map<string, TranslationPageContext>;
+    providers?: ResolvedAIProviderConfig[];
+};
+export declare const createTranslateDocumentHandler: (options: TranslateDocumentOptions) => PayloadHandler;
+export {};

package/dist/handlers/translateDocumentHandler.js

@@ -0,0 +1,186 @@
+import { generateText } from "ai";
+import { isAIProvider } from "../ai/providerOptions.js";
+import { getModel, getProviderConfig } from "../ai/providerRuntime.js";
+import { getExceededTokenUsageLimit, recordTokenUsage } from "../ai/tokenUsage.js";
+import { getTranslationValues } from "../payload/documentTranslation.js";
+const getDefaultLocale = (req)=>{
+    const localization = req.payload.config.localization;
+    if (!localization) return null;
+    return localization.defaultLocale || null;
+};
+const loadDocument = async ({ context, id, locale, req })=>{
+    if (context.type === "collection") {
+        if (id === undefined || id === null || id === "") return null;
+        return req.payload.findByID({
+            collection: context.slug,
+            depth: 0,
+            fallbackLocale: false,
+            id,
+            locale: locale,
+            overrideAccess: false,
+            req
+        });
+    }
+    return req.payload.findGlobal({
+        depth: 0,
+        fallbackLocale: false,
+        locale: locale,
+        overrideAccess: false,
+        req,
+        slug: context.slug
+    });
+};
+const parseTranslations = (text, sourceCount)=>{
+    const value = text.trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
+    const parsed = JSON.parse(value);
+    if (!parsed.translations || typeof parsed.translations !== "object") throw new Error("Invalid translation response.");
+    return Array.from({
+        length: sourceCount
+    }, (_, index)=>parsed.translations?.[String(index)]);
+};
+export const createTranslateDocumentHandler = (options)=>async (req)=>{
+        if (!req.user) return Response.json({
+            error: "Unauthorized"
+        }, {
+            status: 401
+        });
+        const body = req.json ? await req.json().catch(()=>null) : null;
+        const locale = body?.locale?.trim();
+        const scopeSlug = body?.scope?.slug?.trim();
+        const scopeType = body?.scope?.type;
+        if (!body?.action || !locale || !scopeSlug || !scopeType) {
+            return Response.json({
+                error: "Action, locale, and page scope are required."
+            }, {
+                status: 400
+            });
+        }
+        const pageContext = options.pageContexts.get(`${scopeType}:${scopeSlug}`);
+        const defaultLocale = getDefaultLocale(req);
+        if (!pageContext || !defaultLocale || locale === defaultLocale) {
+            return Response.json({
+                available: false
+            });
+        }
+        try {
+            // Payload derives locale state on the request, so reads sharing one req must not run concurrently.
+            const sourceDocument = await loadDocument({
+                context: pageContext,
+                id: body.id,
+                locale: defaultLocale,
+                req
+            });
+            const targetDocument = await loadDocument({
+                context: pageContext,
+                id: body.id,
+                locale,
+                req
+            });
+            const sourceValues = getTranslationValues(pageContext.fields, sourceDocument);
+            const targetValues = getTranslationValues(pageContext.fields, targetDocument);
+            const populatedTargetPaths = new Set(targetValues.map((entry)=>entry.path));
+            const missingSourceValues = sourceValues.filter((entry)=>!populatedTargetPaths.has(entry.path));
+            const available = missingSourceValues.length > 0;
+            if (body.action === "status" || !available) return Response.json({
+                available
+            });
+            const user = req.user;
+            const exceededLimit = await getExceededTokenUsageLimit({
+                maxTokenUsage: options.maxTokenUsage,
+                req,
+                userID: user.id
+            });
+            if (exceededLimit) return Response.json({
+                error: "AI token usage limit reached."
+            }, {
+                status: 429
+            });
+            const managedProviders = options.providers?.length ? options.providers : null;
+            const requestedProvider = body.provider || (managedProviders ? managedProviders[0].id : user.aiProvider || "openai");
+            const managedProvider = managedProviders?.find((provider)=>provider.id === requestedProvider);
+            if (managedProviders && !managedProvider) {
+                return Response.json({
+                    error: `Unsupported AI provider: ${requestedProvider}`
+                }, {
+                    status: 400
+                });
+            }
+            if (!managedProvider && !isAIProvider(requestedProvider)) {
+                return Response.json({
+                    error: `Unsupported AI provider: ${requestedProvider}`
+                }, {
+                    status: 400
+                });
+            }
+            const provider = managedProvider?.provider || requestedProvider;
+            const requestedModel = body.model || managedProvider?.defaultModel;
+            const providerConfig = getProviderConfig({
+                apiKey: managedProvider ? managedProvider.apiKey : options.allowUserApiKeys === false ? null : user.aiApiKey,
+                defaultModels: options.models?.defaults,
+                model: requestedModel,
+                provider
+            });
+            if (!providerConfig.apiKey) return Response.json({
+                error: "Configure an AI provider API key first."
+            }, {
+                status: 400
+            });
+            const model = await getModel({
+                apiKey: providerConfig.apiKey,
+                ...managedProvider?.baseURL ? {
+                    baseURL: managedProvider.baseURL
+                } : {},
+                model: providerConfig.modelID,
+                provider
+            });
+            const result = await generateText({
+                maxOutputTokens: options.maxOutputTokens || 700,
+                model,
+                prompt: JSON.stringify({
+                    sourceLocale: defaultLocale,
+                    targetLocale: locale,
+                    values: missingSourceValues.map((entry, index)=>({
+                            id: String(index),
+                            value: entry.value
+                        }))
+                }),
+                system: [
+                    "Translate the human-readable content in every value to the target locale.",
+                    "Preserve JSON structure, keys, IDs, URLs, numbers, booleans, nulls, and Lexical rich-text structure exactly.",
+                    'Return strict JSON in the shape {"translations":{"0":translatedValue}} with one entry for every input ID.',
+                    "Return no Markdown or explanation."
+                ].join(" ")
+            });
+            const translatedValues = parseTranslations(result.text, missingSourceValues.length);
+            if (translatedValues.some((value)=>value === undefined)) throw new Error("Translation response is incomplete.");
+            if (result.usage && options.maxTokenUsage) {
+                await recordTokenUsage({
+                    model: providerConfig.modelID,
+                    provider: managedProvider?.id || provider,
+                    req,
+                    usage: result.usage,
+                    userID: user.id
+                });
+            }
+            return Response.json({
+                available: true,
+                values: missingSourceValues.map((entry, index)=>({
+                        fieldType: entry.fieldType,
+                        path: entry.path,
+                        value: translatedValues[index]
+                    }))
+            });
+        } catch (error) {
+            req.payload.logger.error({
+                err: error,
+                msg: "AI document translation failed",
+                scopeSlug,
+                scopeType
+            });
+            return Response.json({
+                error: "AI document translation failed."
+            }, {
+                status: 500
+            });
+        }
+    };

package/dist/index.d.ts

@@ -19,6 +19,8 @@ export type PayloadAIPluginOptions = {
     };
     models?: AIModelConfig;
     maxTokenUsage?: MaxTokenUsageOptions;
+    promptCaching?: boolean;
     providers?: AIProviderConfig[];
+    translate?: boolean;
 };
 export declare const payloadAiPlugin: (pluginOptions: PayloadAIPluginOptions) => (config: Config) => Config;

package/dist/index.js

@@ -3,6 +3,7 @@ import { resolveMaxTokenUsageOptions, tokenUsageCollectionSlug } from "./ai/toke
 import { createApplyActionHandler } from "./handlers/applyActionHandler.js";
 import { createChatHandler } from "./handlers/chatHandler.js";
 import { createGenerateFieldHandler } from "./handlers/generateFieldHandler.js";
+import { createTranslateDocumentHandler } from "./handlers/translateDocumentHandler.js";
 import { createMentionSuggestionHandler } from "./handlers/mentionSuggestionHandler.js";
 import { createMediaUploadHandler } from "./handlers/mediaUploadHandler.js";
 import { createProposalDiffHandler } from "./handlers/proposalDiffHandler.js";
@@ -10,6 +11,7 @@ import { createAuditLogHandler } from "./handlers/auditLogHandler.js";
 import { resolveCollectionPermissions } from "./payload/collectionPermissions.js";
 import { isInternalCollection } from "./payload/shared.js";
 import { addTextGenerationFields } from "./payload/textFieldGeneration.js";
+import { hasLocalizedFields } from "./payload/documentTranslation.js";
 const resolveMediaUploadOptions = (media)=>{
     if (!media || media.enabled === false) return null;
     return {
@@ -225,6 +227,7 @@ const aiField = {
         }
     }
 };
+const translateDocumentComponent = "@mvriu5/payload-ai/client#TranslateDocumentButton";
 const getEntityLabel = (label, fallback)=>{
     if (typeof label === "string") return label;
     if (label && typeof label === "object") {
@@ -233,8 +236,9 @@ const getEntityLabel = (label, fallback)=>{
     }
     return fallback;
 };
-const addAIFieldsToDocumentsAndGlobals = ({ addGenerateFields, addAIInput, config })=>{
+const addAIFieldsToDocumentsAndGlobals = ({ addGenerateFields, addAIInput, addTranslation, config })=>{
     const pageContexts = new Map();
+    const translationPageContexts = new Map();
     for (const collection of config.collections || []){
         if (isInternalCollection(collection.slug)) continue;
         if (collection.slug === "payload-ai-auditlog") continue;
@@ -251,6 +255,24 @@ const addAIFieldsToDocumentsAndGlobals = ({ addGenerateFields, addAIInput, confi
             aiField,
             ...collection.fields || []
         ];
+        if (addTranslation && hasLocalizedFields(collection.fields || [])) {
+            translationPageContexts.set(`collection:${collection.slug}`, {
+                fields: collection.fields || [],
+                label: getEntityLabel(collection.labels?.singular, collection.slug),
+                slug: collection.slug,
+                type: "collection"
+            });
+            collection.admin = collection.admin || {};
+            collection.admin.components = collection.admin.components || {};
+            collection.admin.components.edit = collection.admin.components.edit || {};
+            const controls = collection.admin.components.edit.beforeDocumentControls || [];
+            if (!controls.includes(translateDocumentComponent)) {
+                collection.admin.components.edit.beforeDocumentControls = [
+                    ...controls,
+                    translateDocumentComponent
+                ];
+            }
+        }
     }
     for (const global of config.globals || []){
         if (addGenerateFields) {
@@ -266,8 +288,29 @@ const addAIFieldsToDocumentsAndGlobals = ({ addGenerateFields, addAIInput, confi
             aiField,
             ...global.fields || []
         ];
+        if (addTranslation && hasLocalizedFields(global.fields || [])) {
+            translationPageContexts.set(`global:${global.slug}`, {
+                fields: global.fields || [],
+                label: getEntityLabel(global.label, global.slug),
+                slug: global.slug,
+                type: "global"
+            });
+            global.admin = global.admin || {};
+            global.admin.components = global.admin.components || {};
+            global.admin.components.elements = global.admin.components.elements || {};
+            const controls = global.admin.components.elements.beforeDocumentControls || [];
+            if (!controls.includes(translateDocumentComponent)) {
+                global.admin.components.elements.beforeDocumentControls = [
+                    ...controls,
+                    translateDocumentComponent
+                ];
+            }
+        }
     }
-    return pageContexts;
+    return {
+        textGenerationPageContexts: pageContexts,
+        translationPageContexts
+    };
 };
 export const payloadAiPlugin = (pluginOptions)=>(config)=>{
         const incomingOnInit = config.onInit;
@@ -292,9 +335,10 @@ export const payloadAiPlugin = (pluginOptions)=>(config)=>{
         });
         if (pluginOptions.disabled) return config;
         const generateFields = pluginOptions.generateFields !== false;
-        const textGenerationPageContexts = addAIFieldsToDocumentsAndGlobals({
+        const { textGenerationPageContexts, translationPageContexts } = addAIFieldsToDocumentsAndGlobals({
             addGenerateFields: generateFields,
             addAIInput: pluginOptions.aiInput !== false,
+            addTranslation: pluginOptions.translate !== false,
             config
         });
         const mentionCollectionSlugs = config.collections.flatMap((collection)=>{
@@ -333,6 +377,7 @@ export const payloadAiPlugin = (pluginOptions)=>(config)=>{
                 maxOutputTokens,
                 maxTokenUsage,
                 models: modelConfig,
+                promptCaching: pluginOptions.promptCaching !== false,
                 providers: providerConfigs
             }),
             method: "post",
@@ -381,6 +426,20 @@ export const payloadAiPlugin = (pluginOptions)=>(config)=>{
                 path: "/ai-generate-field"
             });
         }
+        if (translationPageContexts.size > 0) {
+            config.endpoints.push({
+                handler: createTranslateDocumentHandler({
+                    allowUserApiKeys,
+                    maxOutputTokens,
+                    maxTokenUsage,
+                    models: modelConfig,
+                    pageContexts: translationPageContexts,
+                    providers: providerConfigs
+                }),
+                method: "post",
+                path: "/ai-translate-document"
+            });
+        }
         if (mediaUploadOptions) {
             config.endpoints.push({
                 handler: createMediaUploadHandler(mediaUploadOptions),

package/dist/payload/documentTranslation.d.ts

@@ -0,0 +1,15 @@
+import type { Field } from "payload";
+export type TranslationFieldType = "json" | "richText" | "text" | "textarea" | "unknown";
+export type TranslationPageContext = {
+    fields: Field[];
+    label: string;
+    slug: string;
+    type: "collection" | "global";
+};
+export type TranslationValue = {
+    fieldType: TranslationFieldType;
+    path: string;
+    value: unknown;
+};
+export declare const getTranslationValues: (fields: Field[], data: unknown) => TranslationValue[];
+export declare const hasLocalizedFields: (fields: Field[]) => boolean;

package/dist/payload/documentTranslation.js

@@ -0,0 +1,120 @@
+const hasValue = (value)=>{
+    if (value === null || value === undefined || value === "") return false;
+    if (Array.isArray(value)) return value.some(hasValue);
+    if (typeof value === "object") return Object.values(value).some(hasValue);
+    return true;
+};
+const hasRichTextValue = (value)=>{
+    if (!value || typeof value !== "object") return false;
+    if (Array.isArray(value)) return value.some(hasRichTextValue);
+    const node = value;
+    if (node.type === "text") return typeof node.text === "string" && node.text.trim().length > 0;
+    if ([
+        "block",
+        "inlineBlock",
+        "relationship",
+        "upload"
+    ].includes(String(node.type))) return true;
+    if (node.root) return hasRichTextValue(node.root);
+    return Array.isArray(node.children) && node.children.some(hasRichTextValue);
+};
+const getFieldType = (field)=>[
+        "json",
+        "richText",
+        "text",
+        "textarea"
+    ].includes(field.type) ? field.type : "unknown";
+const collectFields = ({ data, fields, parentPath = "", result })=>{
+    for (const field of fields){
+        if (field.type === "tabs") {
+            for (const tab of field.tabs){
+                const tabData = "name" in tab && tab.name ? data[tab.name] || {} : data;
+                collectFields({
+                    data: tabData,
+                    fields: tab.fields,
+                    parentPath: "name" in tab && tab.name ? parentPath ? `${parentPath}.${tab.name}` : tab.name : parentPath,
+                    result
+                });
+            }
+            continue;
+        }
+        if (!("name" in field) || !field.name) {
+            if ("fields" in field && Array.isArray(field.fields)) collectFields({
+                data,
+                fields: field.fields,
+                parentPath,
+                result
+            });
+            continue;
+        }
+        const path = parentPath ? `${parentPath}.${field.name}` : field.name;
+        const value = data[field.name];
+        if ("localized" in field && field.localized) {
+            const valueExists = field.type === "richText" ? hasRichTextValue(value) : hasValue(value);
+            if (valueExists) {
+                result.push({
+                    fieldType: getFieldType(field),
+                    path,
+                    value
+                });
+            }
+            continue;
+        }
+        if (field.type === "array" && Array.isArray(value)) {
+            value.forEach((row, index)=>{
+                if (row && typeof row === "object") {
+                    collectFields({
+                        data: row,
+                        fields: field.fields,
+                        parentPath: `${path}.${index}`,
+                        result
+                    });
+                }
+            });
+            continue;
+        }
+        if (field.type === "blocks" && Array.isArray(value)) {
+            value.forEach((row, index)=>{
+                if (!row || typeof row !== "object") return;
+                const rowData = row;
+                const block = field.blocks.find((candidate)=>typeof candidate === "object" && candidate.slug === rowData.blockType);
+                if (block && typeof block === "object") {
+                    collectFields({
+                        data: rowData,
+                        fields: block.fields,
+                        parentPath: `${path}.${index}`,
+                        result
+                    });
+                }
+            });
+            continue;
+        }
+        if ("fields" in field && Array.isArray(field.fields) && value && typeof value === "object") {
+            collectFields({
+                data: value,
+                fields: field.fields,
+                parentPath: path,
+                result
+            });
+        }
+    }
+};
+export const getTranslationValues = (fields, data)=>{
+    if (!data || typeof data !== "object") return [];
+    const result = [];
+    collectFields({
+        data: data,
+        fields,
+        result
+    });
+    return result;
+};
+export const hasLocalizedFields = (fields)=>{
+    for (const field of fields){
+        if ("localized" in field && field.localized) return true;
+        if (field.type === "tabs" && field.tabs.some((tab)=>hasLocalizedFields(tab.fields))) return true;
+        if (field.type === "blocks" && field.blocks.some((block)=>typeof block === "object" && hasLocalizedFields(block.fields))) return true;
+        if ("fields" in field && Array.isArray(field.fields) && hasLocalizedFields(field.fields)) return true;
+    }
+    return false;
+};

package/dist/payload/toolFieldSelection.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import { type CollectionConfig } from "./normalizeData.js";
+export declare const maxToolSelectedFields = 12;
+export type ReadCollectionConfig = CollectionConfig & {
+    admin?: {
+        useAsTitle?: string;
+    };
+    timestamps?: boolean;
+    upload?: boolean | Record<string, unknown>;
+};
+export declare const getToolSelectableFieldNames: (config: ReadCollectionConfig) => string[];
+export declare const createToolFieldNamesSchema: (configs: ReadCollectionConfig[]) => z.ZodOptional<z.ZodArray<z.ZodString | z.ZodEnum<{
+    [x: string]: string;
+}>>>;
+export declare const resolveToolFieldSelection: ({ config, mode, requestedFields, }: {
+    config: ReadCollectionConfig;
+    mode?: "document" | "search";
+    requestedFields?: string[];
+}) => {
+    allowedFields: string[];
+    depth: number;
+    fields: string[];
+    invalidFields: string[];
+    select: Record<string, true>;
+};

package/dist/payload/toolFieldSelection.js

@@ -0,0 +1,118 @@
+import { z } from "zod";
+import { isSensitiveKey } from "../ai/sensitiveData.js";
+import { getSchemaFields } from "./normalizeData.js";
+export const maxToolSelectedFields = 12;
+const cheapFieldTypes = new Set([
+    "checkbox",
+    "date",
+    "email",
+    "number",
+    "point",
+    "radio",
+    "select",
+    "text"
+]);
+const populatedFieldTypes = new Set([
+    "relationship",
+    "upload"
+]);
+const systemFieldNames = [
+    "id",
+    "createdAt",
+    "updatedAt"
+];
+const uploadFieldNames = [
+    "filename",
+    "mimeType",
+    "filesize",
+    "width",
+    "height",
+    "url",
+    "thumbnailURL"
+];
+const getSelectableFields = (config)=>{
+    return getSchemaFields(config).filter((field)=>{
+        return Boolean(field.name && field.type !== "ui" && !isSensitiveKey(field.name));
+    });
+};
+export const getToolSelectableFieldNames = (config)=>{
+    const names = getSelectableFields(config).flatMap((field)=>field.name ? [
+            field.name
+        ] : []);
+    names.push("id");
+    if (config.timestamps !== false) names.push("createdAt", "updatedAt");
+    if (config.upload) names.push(...uploadFieldNames);
+    return [
+        ...new Set(names)
+    ];
+};
+const getDefaultFieldNames = (config, mode)=>{
+    const selectableFields = getSelectableFields(config);
+    const selectableNames = new Set(getToolSelectableFieldNames(config));
+    const candidates = [
+        config.admin?.useAsTitle,
+        "title",
+        "name",
+        "label",
+        "headline",
+        "slug",
+        "_status",
+        ...config.upload ? selectableFields.flatMap((field)=>field.name && cheapFieldTypes.has(field.type || "") ? [
+                field.name
+            ] : []).slice(0, 2) : [],
+        ...mode === "document" ? [
+            "updatedAt"
+        ] : [],
+        ...config.upload ? [
+            "filename",
+            "mimeType",
+            "filesize",
+            "url"
+        ] : []
+    ];
+    const defaults = candidates.filter((name)=>Boolean(name && (selectableNames.has(name) || systemFieldNames.includes(name))));
+    if (!defaults.some((fieldName)=>!systemFieldNames.includes(fieldName) && !uploadFieldNames.includes(fieldName))) {
+        const firstCheapField = selectableFields.find((field)=>field.name && cheapFieldTypes.has(field.type || ""));
+        const firstSelectableField = firstCheapField || selectableFields[0];
+        defaults.unshift(firstSelectableField?.name || "id");
+    }
+    return [
+        ...new Set(defaults)
+    ].slice(0, mode === "search" ? 4 : 6);
+};
+export const createToolFieldNamesSchema = (configs)=>{
+    const names = [
+        ...new Set(configs.flatMap(getToolSelectableFieldNames))
+    ];
+    const fieldNameSchema = names.length > 0 ? z.enum(names) : z.string().refine(()=>false, "No fields are selectable.");
+    return z.array(fieldNameSchema).max(maxToolSelectedFields).optional();
+};
+export const resolveToolFieldSelection = ({ config, mode = "document", requestedFields })=>{
+    const allowedNames = new Set(getToolSelectableFieldNames(config));
+    const normalizedRequestedFields = [
+        ...new Set((requestedFields || []).slice(0, maxToolSelectedFields).map((field)=>field.trim()).filter(Boolean))
+    ];
+    const invalidFields = normalizedRequestedFields.filter((field)=>!allowedNames.has(field));
+    const selectedFields = [
+        ...new Set((requestedFields?.length ? requestedFields : getDefaultFieldNames(config, mode)).map((field)=>field.trim()).filter((field)=>allowedNames.has(field)))
+    ].slice(0, maxToolSelectedFields);
+    const fields = selectedFields.length > 0 ? selectedFields : getDefaultFieldNames(config, mode);
+    const fieldTypesByName = new Map(getSelectableFields(config).flatMap((field)=>field.name ? [
+            [
+                field.name,
+                field.type
+            ]
+        ] : []));
+    return {
+        allowedFields: [
+            ...allowedNames
+        ],
+        depth: fields.some((field)=>populatedFieldTypes.has(fieldTypesByName.get(field) || "")) ? 1 : 0,
+        fields,
+        invalidFields,
+        select: Object.fromEntries(fields.map((field)=>[
+                field,
+                true
+            ]))
+    };
+};

package/dist/payload/toolSchemas.d.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+import { type CollectionConfig } from "./normalizeData.js";
+export declare const genericPayloadDataSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const createPayloadDataSchema: (config?: CollectionConfig | null) => z.ZodRecord<z.ZodString, z.ZodUnknown> | z.ZodObject<{
+    [x: string]: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+}, z.core.$strict>;
+export declare const createLocalizedPayloadDataSchema: (dataSchema: z.ZodType) => z.ZodRecord<z.ZodString, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;