@mvriu5/payload-ai 1.6.2 → 1.6.4

package/dist/{ai → features}/sensitiveData.js

@@ -1,4 +1,4 @@
-import { isRecord } from "../payload/shared.js";
+import { isRecord } from "../utils/data.js";
 const sensitiveKeyPatterns = [
     /^apiKey$/i,
     /^api_key$/i,

package/dist/{ai → features}/tokenUsage.d.ts

@@ -14,7 +14,7 @@ export type TokenUsageData = {
     outputTokens?: number;
     totalTokens?: number;
 };
-type TokenUsageLimit = {
+export type TokenUsageLimit = {
     limit: number;
     period: "day" | "week";
     used: number;
@@ -35,4 +35,3 @@ export declare const recordTokenUsage: ({ model, now, provider, req, usage, user
     usage: TokenUsageData;
     userID: number | string;
 }) => Promise<void>;
-export {};

package/dist/handlers/apply/audit.d.ts

@@ -0,0 +1,42 @@
+import type { PayloadHandler } from "payload";
+import type { ActionProposal } from "../../features/proposals/types.js";
+import type { ApplyActionLogContext } from "./types.js";
+type AppliedDoc = {
+    id?: unknown;
+};
+type ChangeLogTarget = {
+    after: unknown;
+    before: unknown;
+    documentID?: unknown;
+};
+export declare const getAppliedDocReference: (doc: AppliedDoc | null | undefined) => {
+    id: {} | null;
+} | undefined;
+export declare const logAIChange: ({ changeLogCollection, context, target, proposal, req, }: {
+    changeLogCollection?: string;
+    context?: ApplyActionLogContext;
+    proposal: ActionProposal;
+    req: Parameters<PayloadHandler>[0];
+    target: ChangeLogTarget;
+}) => Promise<{
+    action: "create" | "delete" | "update" | "updateGlobal";
+    additions: number;
+    after: unknown;
+    aiResponse: string | null;
+    before: unknown;
+    collection: string | null | undefined;
+    createdAt: string;
+    documentID: string | null;
+    inputTokens: number | null;
+    outputTokens: number | null;
+    prompt: string | null;
+    removals: number;
+    slug: string | null | undefined;
+    totalTokens: number | null;
+    targetType: string;
+    title: string;
+    userID: string | null;
+    userLabel: string | null;
+    url: string | null;
+} | null>;
+export {};

package/dist/handlers/apply/audit.js

@@ -0,0 +1,150 @@
+import { redactSensitiveData } from "../../features/sensitiveData.js";
+import { getJSONLineKey } from "../../utils/data.js";
+import { getProposalMeta } from "./validation.js";
+export const getAppliedDocReference = (doc)=>{
+    return doc?.id === undefined ? undefined : {
+        id: doc.id
+    };
+};
+const countDiffChanges = ({ after, before })=>{
+    const beforeLines = JSON.stringify(before, null, 2).split("\n");
+    const afterLines = JSON.stringify(after, null, 2).split("\n");
+    const dp = Array.from({
+        length: beforeLines.length + 1
+    }, ()=>Array(afterLines.length + 1).fill(0));
+    let additions = 0;
+    let removals = 0;
+    for(let i = beforeLines.length - 1; i >= 0; i -= 1){
+        for(let j = afterLines.length - 1; j >= 0; j -= 1){
+            dp[i][j] = beforeLines[i] === afterLines[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+        }
+    }
+    let beforeIndex = 0;
+    let afterIndex = 0;
+    while(beforeIndex < beforeLines.length && afterIndex < afterLines.length){
+        if (beforeLines[beforeIndex] === afterLines[afterIndex]) {
+            beforeIndex += 1;
+            afterIndex += 1;
+            continue;
+        }
+        const beforeKey = getJSONLineKey(beforeLines[beforeIndex]);
+        const afterKey = getJSONLineKey(afterLines[afterIndex]);
+        if (beforeKey && beforeKey === afterKey) {
+            removals += 1;
+            additions += 1;
+            beforeIndex += 1;
+            afterIndex += 1;
+            continue;
+        }
+        if (dp[beforeIndex + 1][afterIndex] >= dp[beforeIndex][afterIndex + 1]) {
+            removals += 1;
+            beforeIndex += 1;
+        } else {
+            additions += 1;
+            afterIndex += 1;
+        }
+    }
+    removals += beforeLines.length - beforeIndex;
+    additions += afterLines.length - afterIndex;
+    return {
+        additions,
+        removals
+    };
+};
+const getTargetURL = ({ documentID, proposal, req })=>{
+    const adminRoute = req.payload.config.routes.admin || "/admin";
+    if (proposal.action === "updateGlobal") return `${adminRoute}/globals/${proposal.slug}`;
+    if (proposal.action === "delete") return null;
+    const id = proposal.action === "create" ? documentID : proposal.id;
+    if (!id) return null;
+    return `${adminRoute}/collections/${proposal.collection}/${id}`;
+};
+const getUserID = (req)=>{
+    const user = req.user;
+    return user?.id === undefined ? undefined : String(user.id);
+};
+const getUserLabel = (req)=>{
+    const user = req.user;
+    if (typeof user?.email === "string" && user.email) return user.email;
+    if (typeof user?.name === "string" && user.name) return user.name;
+    if (typeof user?.username === "string" && user.username) return user.username;
+    if (user?.id !== undefined) return String(user.id);
+    return null;
+};
+export const logAIChange = async ({ changeLogCollection, context, target, proposal, req })=>{
+    if (!changeLogCollection) return null;
+    const before = redactSensitiveData(target.before);
+    const after = redactSensitiveData(target.after);
+    const { additions, removals } = countDiffChanges({
+        after,
+        before
+    });
+    const proposalForLog = {
+        ...proposal
+    };
+    delete proposalForLog._aiSignature;
+    try {
+        await req.payload.create({
+            collection: changeLogCollection,
+            data: {
+                action: proposal.action,
+                additions,
+                after,
+                aiResponse: context?.aiResponse,
+                before,
+                collection: "collection" in proposal ? proposal.collection : undefined,
+                documentID: target.documentID === undefined ? undefined : String(target.documentID),
+                inputTokens: context?.tokenUsage?.inputTokens,
+                outputTokens: context?.tokenUsage?.outputTokens,
+                prompt: context?.prompt,
+                proposal: redactSensitiveData(proposalForLog),
+                removals,
+                slug: "slug" in proposal ? proposal.slug : undefined,
+                totalTokens: context?.tokenUsage?.totalTokens,
+                targetType: proposal.action === "updateGlobal" ? "global" : "collection",
+                targetURL: getTargetURL({
+                    documentID: target.documentID,
+                    proposal,
+                    req
+                }),
+                title: proposal.label,
+                userID: getUserID(req),
+                userLabel: getUserLabel(req)
+            },
+            overrideAccess: true,
+            req
+        });
+        return {
+            action: proposal.action,
+            additions,
+            after,
+            aiResponse: context?.aiResponse || null,
+            before,
+            collection: "collection" in proposal ? proposal.collection : null,
+            createdAt: new Date().toISOString(),
+            documentID: target.documentID === undefined ? null : String(target.documentID),
+            inputTokens: context?.tokenUsage?.inputTokens ?? null,
+            outputTokens: context?.tokenUsage?.outputTokens ?? null,
+            prompt: context?.prompt || null,
+            removals,
+            slug: "slug" in proposal ? proposal.slug : null,
+            totalTokens: context?.tokenUsage?.totalTokens ?? null,
+            targetType: proposal.action === "updateGlobal" ? "global" : "collection",
+            title: proposal.label,
+            userID: getUserID(req) || null,
+            userLabel: getUserLabel(req),
+            url: getTargetURL({
+                documentID: target.documentID,
+                proposal,
+                req
+            })
+        };
+    } catch (err) {
+        req.payload.logger.error({
+            err,
+            msg: "AI change log entry could not be written",
+            proposal: getProposalMeta(proposal)
+        });
+        return null;
+    }
+};

package/dist/handlers/apply/operations.d.ts

@@ -0,0 +1,18 @@
+import type { PayloadHandler } from "payload";
+import type { ActionProposal } from "../../features/proposals/types.js";
+import type { ApplyActionLogContext, ApplyActionOptions, ApplyDebugPayload } from "./types.js";
+type FailApply = (failure: {
+    debug: ApplyDebugPayload;
+    error: string;
+    logMessage: string;
+    proposal?: Partial<ActionProposal>;
+    status?: number;
+}) => Response;
+export declare const applyActionProposal: ({ failApply, logContext, options, proposal, req, }: {
+    failApply: FailApply;
+    logContext: ApplyActionLogContext;
+    options: ApplyActionOptions;
+    proposal: ActionProposal;
+    req: Parameters<PayloadHandler>[0];
+}) => Promise<Response>;
+export {};

package/dist/handlers/apply/operations.js

@@ -0,0 +1,377 @@
+import { prepareLocalizedTargetUpdates, prepareProposalTargetData, resolveProposalTarget } from "../../features/proposals/target.js";
+import { applyLocalizedRequiredFallbackToPreparedData } from "../../features/proposals/data.js";
+import { isCollectionActionAllowed } from "../../features/collectionPermissions.js";
+import { getDefaultLocale, hasLocalizedData, mergeData } from "../../utils/data.js";
+import { logHandlerEvent } from "../../utils/logging.js";
+import { getAppliedDocReference, logAIChange } from "./audit.js";
+import { createApplyDebugPayload, getProposalLogSummary } from "./validation.js";
+const isAllowedCollection = (req, collection, collections, action = "read")=>isCollectionActionAllowed({
+        action,
+        permissions: collections,
+        req,
+        slug: collection
+    });
+export const applyActionProposal = async ({ failApply, logContext, options, proposal, req })=>{
+    const inferenceText = logContext.prompt;
+    const defaultLocale = getDefaultLocale(req);
+    const target = resolveProposalTarget({
+        proposal,
+        req
+    });
+    if (proposal.action === "updateGlobal") {
+        if (!target || target.type !== "global") {
+            return failApply({
+                debug: createApplyDebugPayload({
+                    phase: "apply_validation",
+                    proposal,
+                    reason: "unknown_global"
+                }),
+                error: "Unknown global",
+                logMessage: "AI apply blocked: unknown global",
+                proposal
+            });
+        }
+        if (hasLocalizedData(proposal)) {
+            const preparedData = prepareProposalTargetData({
+                inferenceText,
+                proposal,
+                target
+            });
+            if (preparedData.issues.length > 0 || !preparedData.localizedData) {
+                return failApply({
+                    debug: createApplyDebugPayload({
+                        details: {
+                            issues: preparedData.issues
+                        },
+                        phase: "apply_validation",
+                        proposal,
+                        reason: "invalid_global_write_shape"
+                    }),
+                    error: "Proposal is invalid.",
+                    logMessage: "AI apply blocked: invalid global proposal data",
+                    proposal
+                });
+            }
+            const localizedResults = await prepareLocalizedTargetUpdates({
+                defaultLocale: defaultLocale || undefined,
+                localizedData: preparedData.localizedData,
+                target
+            });
+            await Promise.all(localizedResults.map(({ data, locale })=>target.update(data, locale)));
+            const change = await logAIChange({
+                changeLogCollection: options.changeLogCollection,
+                context: logContext,
+                proposal,
+                req,
+                target: {
+                    after: Object.fromEntries(localizedResults.map(({ after, locale })=>[
+                            locale,
+                            after
+                        ])),
+                    before: Object.fromEntries(localizedResults.map(({ before, locale })=>[
+                            locale,
+                            before
+                        ]))
+                }
+            });
+            logHandlerEvent(req, "info", {
+                changeLogged: Boolean(change),
+                locales: Object.keys(proposal.localizedData),
+                msg: "AI apply succeeded",
+                proposal: getProposalLogSummary(proposal)
+            });
+            return Response.json({
+                change,
+                doc: undefined,
+                status: "applied"
+            });
+        }
+        const preparedData = prepareProposalTargetData({
+            inferenceText,
+            proposal,
+            target
+        });
+        if (preparedData.issues.length > 0 || !preparedData.data) {
+            return failApply({
+                debug: createApplyDebugPayload({
+                    details: {
+                        issues: preparedData.issues
+                    },
+                    phase: "apply_validation",
+                    proposal,
+                    reason: "invalid_global_write_shape"
+                }),
+                error: "Proposal is invalid.",
+                logMessage: "AI apply blocked: invalid global proposal data",
+                proposal
+            });
+        }
+        const before = await target.read({
+            locale: proposal.locale
+        });
+        const doc = await target.update(preparedData.data, proposal.locale);
+        const change = await logAIChange({
+            changeLogCollection: options.changeLogCollection,
+            context: logContext,
+            proposal,
+            req,
+            target: {
+                after: mergeData(before, preparedData.data),
+                before
+            }
+        });
+        logHandlerEvent(req, "info", {
+            changeLogged: Boolean(change),
+            locale: proposal.locale,
+            msg: "AI apply succeeded",
+            proposal: getProposalLogSummary(proposal)
+        });
+        return Response.json({
+            change,
+            doc: getAppliedDocReference(doc),
+            status: "applied"
+        });
+    }
+    if (!isAllowedCollection(req, proposal.collection, options.collections, proposal.action)) {
+        return failApply({
+            debug: createApplyDebugPayload({
+                phase: "authorization",
+                proposal,
+                reason: "unknown_or_disallowed_collection"
+            }),
+            error: "Unknown collection",
+            logMessage: "AI apply blocked: unknown or disallowed collection",
+            proposal
+        });
+    }
+    if (!target || target.type !== "collection") {
+        return failApply({
+            debug: createApplyDebugPayload({
+                phase: "authorization",
+                proposal,
+                reason: "unknown_or_disallowed_collection"
+            }),
+            error: "Unknown collection",
+            logMessage: "AI apply blocked: unknown or disallowed collection",
+            proposal
+        });
+    }
+    if (proposal.action === "delete") {
+        const doc = await target.delete();
+        const change = await logAIChange({
+            changeLogCollection: options.changeLogCollection,
+            context: logContext,
+            proposal,
+            req,
+            target: {
+                after: {},
+                before: doc,
+                documentID: proposal.id
+            }
+        });
+        logHandlerEvent(req, "info", {
+            changeLogged: Boolean(change),
+            documentID: proposal.id,
+            msg: "AI apply succeeded",
+            proposal: getProposalLogSummary(proposal)
+        });
+        return Response.json({
+            change,
+            doc: getAppliedDocReference(doc),
+            status: "applied"
+        });
+    }
+    if (hasLocalizedData(proposal)) {
+        const preparedData = prepareProposalTargetData({
+            inferenceText,
+            proposal,
+            target
+        });
+        if (preparedData.issues.length > 0 || !preparedData.localizedData) {
+            return failApply({
+                debug: createApplyDebugPayload({
+                    details: {
+                        issues: preparedData.issues
+                    },
+                    phase: "apply_validation",
+                    proposal,
+                    reason: "invalid_collection_write_shape"
+                }),
+                error: "Proposal is invalid.",
+                logMessage: "AI apply blocked: invalid collection proposal data",
+                proposal
+            });
+        }
+        if (proposal.action === "create") {
+            const localeEntries = Object.entries(preparedData.localizedData);
+            const [firstLocale, firstLocaleData] = localeEntries[0] || [];
+            if (!firstLocale) {
+                return failApply({
+                    debug: createApplyDebugPayload({
+                        phase: "apply_validation",
+                        proposal,
+                        reason: "localized_create_without_locales"
+                    }),
+                    error: "Proposal is invalid.",
+                    logMessage: "AI apply blocked: localized create proposal has no locales",
+                    proposal
+                });
+            }
+            const doc = await target.create(firstLocaleData, firstLocale);
+            const beforeByLocale = {
+                [firstLocale]: {}
+            };
+            const afterByLocale = {
+                [firstLocale]: doc
+            };
+            const fallbackSource = doc;
+            const localizedResults = await Promise.all(localeEntries.slice(1).map(async ([locale, localeData])=>{
+                const completedData = applyLocalizedRequiredFallbackToPreparedData({
+                    fallbackSource,
+                    fields: target.fields,
+                    preparedData: localeData
+                });
+                await target.update(completedData, locale, String(doc.id));
+                return {
+                    completedData,
+                    locale
+                };
+            }));
+            localizedResults.forEach(({ completedData, locale })=>{
+                beforeByLocale[locale] = {};
+                afterByLocale[locale] = completedData;
+            });
+            const change = await logAIChange({
+                changeLogCollection: options.changeLogCollection,
+                context: logContext,
+                proposal,
+                req,
+                target: {
+                    after: afterByLocale,
+                    before: beforeByLocale,
+                    documentID: doc.id
+                }
+            });
+            logHandlerEvent(req, "info", {
+                changeLogged: Boolean(change),
+                documentID: doc.id,
+                locales: localeEntries.map(([locale])=>locale),
+                msg: "AI apply succeeded",
+                proposal: getProposalLogSummary(proposal)
+            });
+            return Response.json({
+                change,
+                doc: getAppliedDocReference(doc),
+                status: "applied"
+            });
+        }
+        const localizedResults = await prepareLocalizedTargetUpdates({
+            defaultLocale: defaultLocale || undefined,
+            localizedData: preparedData.localizedData,
+            target
+        });
+        await Promise.all(localizedResults.map(({ data, locale })=>target.update(data, locale)));
+        const change = await logAIChange({
+            changeLogCollection: options.changeLogCollection,
+            context: logContext,
+            proposal,
+            req,
+            target: {
+                after: Object.fromEntries(localizedResults.map(({ after, locale })=>[
+                        locale,
+                        after
+                    ])),
+                before: Object.fromEntries(localizedResults.map(({ before, locale })=>[
+                        locale,
+                        before
+                    ])),
+                documentID: proposal.id
+            }
+        });
+        logHandlerEvent(req, "info", {
+            changeLogged: Boolean(change),
+            documentID: proposal.id,
+            locales: Object.keys(proposal.localizedData),
+            msg: "AI apply succeeded",
+            proposal: getProposalLogSummary(proposal)
+        });
+        return Response.json({
+            change,
+            doc: {
+                id: proposal.id
+            },
+            status: "applied"
+        });
+    }
+    const preparedData = prepareProposalTargetData({
+        inferenceText,
+        proposal,
+        target
+    });
+    if (preparedData.issues.length > 0 || !preparedData.data) {
+        return failApply({
+            debug: createApplyDebugPayload({
+                details: {
+                    issues: preparedData.issues
+                },
+                phase: "apply_validation",
+                proposal,
+                reason: "invalid_collection_write_shape"
+            }),
+            error: "Proposal is invalid.",
+            logMessage: "AI apply blocked: invalid collection proposal data",
+            proposal
+        });
+    }
+    if (proposal.action === "create") {
+        const doc = await target.create(preparedData.data, proposal.locale);
+        const change = await logAIChange({
+            changeLogCollection: options.changeLogCollection,
+            context: logContext,
+            proposal,
+            req,
+            target: {
+                after: doc,
+                before: {},
+                documentID: doc.id
+            }
+        });
+        logHandlerEvent(req, "info", {
+            changeLogged: Boolean(change),
+            documentID: doc.id,
+            msg: "AI apply succeeded",
+            proposal: getProposalLogSummary(proposal)
+        });
+        return Response.json({
+            change,
+            doc: getAppliedDocReference(doc),
+            status: "applied"
+        });
+    }
+    const before = await target.read({
+        locale: proposal.locale
+    });
+    const doc = await target.update(preparedData.data, proposal.locale);
+    const change = await logAIChange({
+        changeLogCollection: options.changeLogCollection,
+        context: logContext,
+        proposal,
+        req,
+        target: {
+            after: mergeData(before, preparedData.data),
+            before,
+            documentID: proposal.id
+        }
+    });
+    logHandlerEvent(req, "info", {
+        changeLogged: Boolean(change),
+        documentID: proposal.id,
+        msg: "AI apply succeeded",
+        proposal: getProposalLogSummary(proposal)
+    });
+    return Response.json({
+        change,
+        doc: getAppliedDocReference(doc),
+        status: "applied"
+    });
+};

package/dist/handlers/apply/types.d.ts

@@ -0,0 +1,33 @@
+import type { ResolvedCollectionPermissionMap } from "../../features/collectionPermissions.js";
+export type ApplyActionBody = {
+    aiResponse?: string;
+    tokenUsage?: {
+        inputTokens?: unknown;
+        outputTokens?: unknown;
+        totalTokens?: unknown;
+    };
+    prompt?: string;
+    proposal?: unknown;
+};
+export type ApplyActionOptions = {
+    changeLogCollection?: string;
+    collections?: ResolvedCollectionPermissionMap;
+};
+export type ApplyActionLogContext = {
+    aiResponse?: string;
+    prompt?: string;
+    tokenUsage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+};
+export type ApplyDebugPayload = {
+    action?: unknown;
+    collection?: unknown;
+    details?: Record<string, unknown>;
+    id?: unknown;
+    phase: "apply_validation" | "authorization" | "payload_operation";
+    reason: string;
+    slug?: unknown;
+};

package/dist/handlers/apply/types.js

@@ -0,0 +1 @@
+export { };

package/dist/handlers/apply/validation.d.ts

@@ -0,0 +1,45 @@
+import type { PayloadHandler } from "payload";
+import type { ActionProposal } from "../../features/proposals/types.js";
+import type { ApplyActionLogContext, ApplyDebugPayload } from "./types.js";
+type ProposalMeta = {
+    action?: unknown;
+    collection?: unknown;
+    id?: unknown;
+    slug?: unknown;
+};
+type ApplyFailure = {
+    debug: ApplyDebugPayload;
+    error: string;
+    logMessage: string;
+    proposal?: Partial<ActionProposal>;
+    status?: number;
+};
+type ApplyRequestResolution = {
+    failure: ApplyFailure;
+    ok: false;
+} | {
+    context: ApplyActionLogContext;
+    ok: true;
+    proposal: ActionProposal;
+};
+export declare const getProposalLogSummary: (proposal: ActionProposal) => {
+    action: "create" | "delete" | "update" | "updateGlobal";
+    collection: string | undefined;
+    hasData: boolean;
+    hasLocalizedData: boolean;
+    id: string | undefined;
+    label: string;
+    locale: string | undefined;
+    locales: string[] | undefined;
+    slug: string | undefined;
+};
+export declare const getProposalMeta: (proposal?: Partial<ActionProposal>) => ProposalMeta;
+export declare const createApplyDebugPayload: ({ details, phase, proposal, reason, }: {
+    details?: Record<string, unknown>;
+    phase: ApplyDebugPayload["phase"];
+    proposal?: Partial<ActionProposal>;
+    reason: string;
+}) => ApplyDebugPayload;
+export declare const resolveApplyRequest: (req: Parameters<PayloadHandler>[0]) => Promise<ApplyRequestResolution>;
+export declare const createApplyFailureResponse: (req: Parameters<PayloadHandler>[0], applyFailure: ApplyFailure) => Response;
+export {};