@mvriu5/payload-ai 1.3.2 → 1.4.0

package/README.md

@@ -39,19 +39,21 @@ export default buildConfig({
 });
 ```
 
-The plugin adds two fields to the configured Payload admin user collection:
+Without centrally configured providers, the plugin adds two fields to the configured Payload admin user collection:
 
 - `aiProvider`
 - `aiApiKey`
 
 Users can select their provider and optionally store their own API key in account settings. If no account-level key is set, the chat endpoint uses provider environment variables.
 
+When `providers` is configured, provider selection and API keys are managed centrally. The plugin does not add either field to the user collection. All configured provider models are grouped by provider in the AI input.
+
 ## Options
 
 ```ts
-import type { PayloadAiPluginOptions } from "@mvriu5/payload-ai";
+import type { PayloadAIPluginOptions } from "@mvriu5/payload-ai";
 
-const options: PayloadAiPluginOptions = {
+const options: PayloadAIPluginOptions = {
   allowUserApiKeys: false,
   collections: {
     media: {
@@ -72,22 +74,41 @@ const options: PayloadAiPluginOptions = {
     acceptedMimeTypes: ["image/*"],
     maxFileSize: 10 * 1024 * 1024,
   },
-  models: {
-    defaults: {
-      openai: "gpt-4.1-mini",
-      openrouter: "openai/gpt-oss-120b",
-    },
-    providers: {
-      openai: [
+  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,
+  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.
+
 ### `collections`
 
 Restricts AI read and write proposals to enabled collection slugs. If omitted, all non-internal Payload collections are available.
@@ -180,6 +201,27 @@ OpenRouter includes these built-in model options:
 - `anthropic/claude-3.5-sonnet`
 - `google/gemini-2.0-flash-001`
 
+### `providers`
+
+Enables centrally managed provider profiles. Each profile supports:
+
+- `id`: unique provider profile identifier
+- `label`: provider group label shown in the model select
+- `provider`: SDK adapter (`openai`, `openrouter`, `claude`, `mistral`, or `google`)
+- `models`: allowed model list
+- `defaultModel`: optional default; otherwise the first configured model is used
+- `baseURL`: optional custom provider URL
+- `apiKey`: optional server-side API key
+
+When at least one profile is configured:
+
+- `aiProvider` and `aiApiKey` are not added to the admin user collection.
+- Models from every configured profile are displayed in provider groups.
+- The chat endpoint validates both provider IDs and model IDs against this configuration.
+- User-level provider and API key values are ignored.
+
+`apiKey` and `baseURL` remain server-side and are not included in Payload's public admin configuration. Custom endpoints must implement the protocol expected by their selected SDK adapter. For Ollama, vLLM, and similar APIs, use the `openai` adapter with an OpenAI-compatible `/v1` endpoint.
+
 ### `maxOutputTokens`
 
 Controls the maximum number of output tokens the chat endpoint may generate per request. If omitted, the plugin uses `700`.
@@ -190,6 +232,24 @@ payloadAiPlugin({
 })
 ```
 
+### `maxTokenUsage`
+
+Limits total AI tokens across rolling 24-hour and 7-day windows.
+
+```ts
+payloadAiPlugin({
+  maxTokenUsage: {
+    type: "user",
+    perDay: 50_000,
+    perWeek: 250_000,
+  },
+})
+```
+
+Use `type: "user"` to enforce separate budgets per authenticated user, or `type: "site"` to share one budget across the entire Payload installation. `perDay` and `perWeek` are optional individually, but at least one must be configured.
+
+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.
+
 ### `allowUserApiKeys`
 
 Controls whether the plugin adds an `aiApiKey` field to the admin user collection.
@@ -202,6 +262,8 @@ payloadAiPlugin({
 
 When disabled, users can still select an AI provider, but API keys must come from environment variables.
 
+This option only applies when `providers` is not configured. Managed provider mode never adds user-level AI settings.
+
 ### `disabled`
 
 Disables endpoint and UI registration while keeping the plugin call in your config.
@@ -213,8 +275,9 @@ The package lazy-loads provider SDKs at runtime. If a user selects `claude`, `go
 
 API key priority is:
 
-1. account-level API key, unless `allowUserApiKeys: false`
-2. provider environment variables
+1. managed provider `apiKey`, when `providers` is configured
+2. account-level API key, unless `allowUserApiKeys: false`
+3. provider environment variables
 
 - `OPENAI_API_KEY`, `OPENAI_MODEL`
 - `OPENROUTER_API_KEY`, `OPENROUTER_MODEL`

package/dist/ai/providerOptions.d.ts

@@ -1,4 +1,4 @@
-type AIProviderModelOption = {
+export type AIProviderModelOption = {
     label: string;
     value: string;
 };
@@ -71,6 +71,26 @@ declare const aiProviderModels: {
 };
 export type AIProvider = keyof typeof aiProviderModels;
 type AIProviderModels = Record<AIProvider, AIProviderModelOption[]>;
+export type AIProviderConfig = {
+    apiKey?: string;
+    baseURL?: string;
+    defaultModel?: string;
+    id: string;
+    label: string;
+    models: AIProviderModelOption[];
+    provider: AIProvider;
+};
+export type AIProviderProfile = {
+    defaultModel: string;
+    id: string;
+    label: string;
+    models: AIProviderModelOption[];
+    provider: AIProvider;
+};
+export type ResolvedAIProviderConfig = AIProviderProfile & {
+    apiKey?: string;
+    baseURL?: string;
+};
 export declare const aiProviders: {
     label: string;
     value: AIProvider;
@@ -85,4 +105,7 @@ export declare const getResolvedAIModelConfig: (modelConfig?: AIModelConfig) =>
     providers: AIProviderModels;
 };
 export declare const isAIProvider: (provider: string) => provider is AIProvider;
+export declare const getLegacyAIProviderProfiles: (modelConfig?: AIModelConfig) => AIProviderProfile[];
+export declare const resolveAIProviderConfigs: (providers?: AIProviderConfig[]) => ResolvedAIProviderConfig[];
+export declare const toClientAIProviderProfiles: (providers: ResolvedAIProviderConfig[]) => AIProviderProfile[];
 export {};

package/dist/ai/providerOptions.js

@@ -144,3 +144,84 @@ export const getResolvedAIModelConfig = (modelConfig)=>{
     };
 };
 export const isAIProvider = (provider)=>provider in aiProviderModels;
+export const getLegacyAIProviderProfiles = (modelConfig)=>{
+    const resolvedModels = getResolvedAIModelConfig(modelConfig);
+    return aiProviders.map(({ label, value })=>({
+            defaultModel: resolvedModels.defaults[value],
+            id: value,
+            label,
+            models: resolvedModels.providers[value],
+            provider: value
+        }));
+};
+export const resolveAIProviderConfigs = (providers)=>{
+    if (!providers?.length) return [];
+    const providerIDs = new Set();
+    return providers.map((providerConfig, index)=>{
+        const path = `providers[${index}]`;
+        const id = providerConfig.id.trim();
+        const label = providerConfig.label.trim();
+        if (!id || !/^[a-z0-9][a-z0-9_-]*$/i.test(id)) {
+            throw new Error(`${path}.id must contain only letters, numbers, hyphens, or underscores.`);
+        }
+        if (providerIDs.has(id)) throw new Error(`Duplicate AI provider id: ${id}`);
+        providerIDs.add(id);
+        if (!label) throw new Error(`${path}.label is required.`);
+        if (!isAIProvider(providerConfig.provider)) {
+            throw new Error(`${path}.provider is unsupported: ${String(providerConfig.provider)}`);
+        }
+        if (!providerConfig.models.length) throw new Error(`${path}.models must contain at least one model.`);
+        const modelValues = new Set();
+        const models = providerConfig.models.map((model, modelIndex)=>{
+            const modelPath = `${path}.models[${modelIndex}]`;
+            const modelLabel = model.label.trim();
+            const value = model.value.trim();
+            if (!modelLabel) throw new Error(`${modelPath}.label is required.`);
+            if (!value) throw new Error(`${modelPath}.value is required.`);
+            if (modelValues.has(value)) throw new Error(`Duplicate model value "${value}" in AI provider "${id}".`);
+            modelValues.add(value);
+            return {
+                label: modelLabel,
+                value
+            };
+        });
+        const defaultModel = providerConfig.defaultModel?.trim() || models[0].value;
+        if (!modelValues.has(defaultModel)) {
+            throw new Error(`${path}.defaultModel must match a configured model value.`);
+        }
+        if (providerConfig.baseURL) {
+            let parsedURL;
+            try {
+                parsedURL = new URL(providerConfig.baseURL);
+            } catch  {
+                throw new Error(`${path}.baseURL must be a valid URL.`);
+            }
+            if (![
+                "http:",
+                "https:"
+            ].includes(parsedURL.protocol)) {
+                throw new Error(`${path}.baseURL must use http or https.`);
+            }
+        }
+        return {
+            ...providerConfig.apiKey ? {
+                apiKey: providerConfig.apiKey
+            } : {},
+            ...providerConfig.baseURL ? {
+                baseURL: providerConfig.baseURL
+            } : {},
+            defaultModel,
+            id,
+            label,
+            models,
+            provider: providerConfig.provider
+        };
+    });
+};
+export const toClientAIProviderProfiles = (providers)=>providers.map(({ defaultModel, id, label, models, provider })=>({
+            defaultModel,
+            id,
+            label,
+            models,
+            provider
+        }));

package/dist/ai/providerRuntime.d.ts

@@ -8,6 +8,7 @@ type ProviderConfig = {
 };
 type ModelConfig = {
     apiKey: string;
+    baseURL?: string;
     model: string;
     provider: AIProvider;
 };
@@ -15,5 +16,5 @@ export declare const getProviderConfig: ({ apiKey, defaultModels, model, provide
     apiKey: string | undefined;
     modelID: string;
 };
-export declare const getModel: ({ apiKey, model, provider }: ModelConfig) => Promise<LanguageModel>;
+export declare const getModel: ({ apiKey, baseURL, model, provider }: ModelConfig) => Promise<LanguageModel>;
 export {};

package/dist/ai/providerRuntime.js

@@ -33,9 +33,12 @@ export const getProviderConfig = ({ apiKey, defaultModels, model, provider })=>{
 const getMissingProviderDependencyError = (packageName, provider)=>{
     return new Error(`Missing optional dependency ${packageName}. Install it to use the ${provider} provider.`);
 };
-export const getModel = async ({ apiKey, model, provider })=>{
+export const getModel = async ({ apiKey, baseURL, model, provider })=>{
     const providerOptions = {
-        apiKey
+        apiKey,
+        ...baseURL ? {
+            baseURL
+        } : {}
     };
     if (provider === "claude") {
         try {

package/dist/ai/tokenUsage.d.ts

@@ -0,0 +1,38 @@
+import type { PayloadHandler } from "payload";
+export type MaxTokenUsageOptions = {
+    perDay?: number;
+    perWeek?: number;
+    type: "site" | "user";
+};
+export type ResolvedMaxTokenUsageOptions = {
+    perDay?: number;
+    perWeek?: number;
+    type: "site" | "user";
+};
+export type TokenUsageData = {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+};
+type TokenUsageLimit = {
+    limit: number;
+    period: "day" | "week";
+    used: number;
+};
+export declare const tokenUsageCollectionSlug = "payload-ai-usage";
+export declare const resolveMaxTokenUsageOptions: (options?: MaxTokenUsageOptions) => ResolvedMaxTokenUsageOptions | undefined;
+export declare const getExceededTokenUsageLimit: ({ maxTokenUsage, now, req, userID, }: {
+    maxTokenUsage?: ResolvedMaxTokenUsageOptions;
+    now?: Date;
+    req: Parameters<PayloadHandler>[0];
+    userID: number | string;
+}) => Promise<TokenUsageLimit | null>;
+export declare const recordTokenUsage: ({ model, now, provider, req, usage, userID, }: {
+    model: string;
+    now?: Date;
+    provider: string;
+    req: Parameters<PayloadHandler>[0];
+    usage: TokenUsageData;
+    userID: number | string;
+}) => Promise<void>;
+export {};

package/dist/ai/tokenUsage.js

@@ -0,0 +1,106 @@
+export const tokenUsageCollectionSlug = "payload-ai-usage";
+const dayInMilliseconds = 24 * 60 * 60 * 1000;
+const weekInMilliseconds = 7 * dayInMilliseconds;
+const resolvePositiveInteger = (value, path)=>{
+    if (value === undefined) return undefined;
+    if (!Number.isFinite(value) || value <= 0) throw new Error(`${path} must be a positive number.`);
+    return Math.floor(value);
+};
+export const resolveMaxTokenUsageOptions = (options)=>{
+    if (!options) return undefined;
+    if (![
+        "site",
+        "user"
+    ].includes(options.type)) throw new Error('maxTokenUsage.type must be either "user" or "site".');
+    const perDay = resolvePositiveInteger(options.perDay, "maxTokenUsage.perDay");
+    const perWeek = resolvePositiveInteger(options.perWeek, "maxTokenUsage.perWeek");
+    if (!perDay && !perWeek) throw new Error("maxTokenUsage must configure perDay, perWeek, or both.");
+    return {
+        ...perDay ? {
+            perDay
+        } : {},
+        ...perWeek ? {
+            perWeek
+        } : {},
+        type: options.type
+    };
+};
+const normalizeTokenCount = (value)=>typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+const getTokenCount = (usage)=>typeof usage.totalTokens === "number" ? normalizeTokenCount(usage.totalTokens) : normalizeTokenCount(usage.inputTokens) + normalizeTokenCount(usage.outputTokens);
+export const getExceededTokenUsageLimit = async ({ maxTokenUsage, now = new Date(), req, userID })=>{
+    if (!maxTokenUsage) return null;
+    const dayStart = new Date(now.getTime() - dayInMilliseconds);
+    const weekStart = new Date(now.getTime() - weekInMilliseconds);
+    const queryStart = maxTokenUsage.perWeek ? weekStart : dayStart;
+    let page = 1;
+    let usagePerDay = 0;
+    let usagePerWeek = 0;
+    while(true){
+        const result = await req.payload.find({
+            collection: tokenUsageCollectionSlug,
+            depth: 0,
+            limit: 500,
+            overrideAccess: true,
+            page,
+            req,
+            where: {
+                and: [
+                    {
+                        recordedAt: {
+                            greater_than_equal: queryStart.toISOString()
+                        }
+                    },
+                    ...maxTokenUsage.type === "user" ? [
+                        {
+                            userID: {
+                                equals: String(userID)
+                            }
+                        }
+                    ] : []
+                ]
+            }
+        });
+        for (const document of result.docs || []){
+            const tokenCount = getTokenCount(document);
+            usagePerWeek += tokenCount;
+            if (document.recordedAt && new Date(document.recordedAt).getTime() >= dayStart.getTime()) {
+                usagePerDay += tokenCount;
+            }
+        }
+        if (!result.hasNextPage || !result.nextPage) break;
+        page = result.nextPage;
+    }
+    if (maxTokenUsage.perDay && usagePerDay >= maxTokenUsage.perDay) {
+        return {
+            limit: maxTokenUsage.perDay,
+            period: "day",
+            used: usagePerDay
+        };
+    }
+    if (maxTokenUsage.perWeek && usagePerWeek >= maxTokenUsage.perWeek) {
+        return {
+            limit: maxTokenUsage.perWeek,
+            period: "week",
+            used: usagePerWeek
+        };
+    }
+    return null;
+};
+export const recordTokenUsage = async ({ model, now = new Date(), provider, req, usage, userID })=>{
+    const totalTokens = getTokenCount(usage);
+    if (!totalTokens) return;
+    await req.payload.create({
+        collection: tokenUsageCollectionSlug,
+        data: {
+            inputTokens: typeof usage.inputTokens === "number" ? normalizeTokenCount(usage.inputTokens) : undefined,
+            model,
+            outputTokens: typeof usage.outputTokens === "number" ? normalizeTokenCount(usage.outputTokens) : undefined,
+            provider,
+            recordedAt: now.toISOString(),
+            totalTokens,
+            userID: String(userID)
+        },
+        overrideAccess: true,
+        req
+    });
+};

package/dist/components/Icons.d.ts

@@ -4,3 +4,4 @@ export declare function OpenaiIcon(props: SVGProps<SVGSVGElement>): import("reac
 export declare function ClaudeIcon(props: SVGProps<SVGSVGElement>): import("react").JSX.Element;
 export declare function GoogleGeminiIcon(props: SVGProps<SVGSVGElement>): import("react").JSX.Element;
 export declare function OpenrouterIcon(props: SVGProps<SVGSVGElement>): import("react").JSX.Element;
+export declare function PaperclipIcon(props: SVGProps<SVGSVGElement>): import("react").JSX.Element;

package/dist/components/Icons.js

@@ -274,3 +274,18 @@ export function OpenrouterIcon(props) {
         })
     });
 }
+export function PaperclipIcon(props) {
+    return /*#__PURE__*/ _jsx("svg", {
+        xmlns: "http://www.w3.org/2000/svg",
+        viewBox: "0 0 24 24",
+        fill: "none",
+        stroke: "currentColor",
+        strokeWidth: "2",
+        strokeLinecap: "round",
+        strokeLinejoin: "round",
+        ...props,
+        children: /*#__PURE__*/ _jsx("path", {
+            d: "m16 6-8.414 8.586a2 2 0 0 0 2.829 2.829l8.414-8.586a4 4 0 1 0-5.657-5.657l-8.379 8.551a6 6 0 1 0 8.485 8.485l8.379-8.551"
+        })
+    });
+}

package/dist/components/action-toast/ActionToast.d.ts

@@ -5,8 +5,11 @@ export type ActionProposal = {
     };
     action: "create" | "delete" | "update" | "updateGlobal";
     collection?: string;
+    data?: Record<string, unknown>;
     id?: string;
     label: string;
+    locale?: string;
+    localizedData?: Record<string, Record<string, unknown>>;
     slug?: string;
 };
 type ActionToastProps = {
@@ -15,6 +18,7 @@ type ActionToastProps = {
     error?: string;
     getViewURL?: (proposal: ActionProposal) => string | null;
     isApplying: boolean;
+    isLoading: boolean;
     onDismiss?: () => void;
     onDismissError?: () => void;
     onApply: (proposal: ActionProposal, index: number) => void;
@@ -26,5 +30,5 @@ type ActionToastProps = {
         totalTokens?: number;
     } | null;
 };
-export declare const ActionToast: ({ apiRoute, description, error, getViewURL, isApplying, onDismiss, onDismissError, onApply, prompt, proposals, tokenUsage, }: ActionToastProps) => import("react").JSX.Element | null;
+export declare const ActionToast: ({ apiRoute, description, error, getViewURL, isApplying, isLoading, onDismiss, onDismissError, onApply, prompt, proposals, tokenUsage, }: ActionToastProps) => import("react").JSX.Element | null;
 export {};