@simmalugnt-se/payload-editor-assistant 0.9.1 → 0.11.0

package/dist/domain/batch.js

@@ -0,0 +1,342 @@
+import { changedPaths } from "../form/changed-paths.js";
+import { compileOperations } from "../form/compile.js";
+import { hashFormRevision } from "../form/hash.js";
+import { isFormOperation } from "../form/operations.js";
+import { cloneData, getAtPath, parseFieldPath, setAtPath } from "../form/path.js";
+import { relationValueError } from "../form/relation-shape.js";
+import { loadRichText } from "../form/rich-text.js";
+import { finalizeCompiled, openRichText } from "../form/shape.js";
+import { translationPaths } from "../form/translation.js";
+import { DEFAULT_APPROVAL_SLUG } from "../package-name.js";
+import { runAgentTurn } from "../runtime/agent.js";
+import { sourceLocale } from "../runtime/translation-source.js";
+import { configuredDefaultLocale, configuredLocales, entityFields, findCollectionConfig, hasDrafts, } from "../schema/discover.js";
+import { fieldAtPath } from "../schema/fields.js";
+import { projectRecord } from "../schema/project.js";
+import { hasCapability, resolveAllowlist } from "./allowlist.js";
+import { writeAudit } from "./audit.js";
+import { readDocument } from "./content.js";
+import { localApi } from "./local-api.js";
+import { verifyDocumentRelations } from "./relations.js";
+const BATCH_ID = /^[\w-]{1,64}$/;
+/** An editor's own wording in a batch card; longer than any meta text or alt text needs. */
+const MAX_EDIT_LENGTH = 5000;
+/**
+ * One document of a batch: a turn on the saved document, as if it were open with the finding's field
+ * selected. The model may only propose a `content.update` within the target's fields.
+ */
+export async function proposeBatchTarget(req, options, input, run = runAgentTurn) {
+    await loadRichText();
+    const { target } = input;
+    if (!BATCH_ID.test(input.batchId) || !input.prompt.trim()) {
+        return { ok: false, error: "tool_denied" };
+    }
+    const resolved = resolveAllowlist(options, { collection: target.collection });
+    if (!resolved || !hasCapability(resolved.allowlist, "content.update")) {
+        return { ok: false, error: "tool_denied", message: "Batch changes are not allowed here." };
+    }
+    const locale = target.locale ?? configuredDefaultLocale(req) ?? "en";
+    const saved = await readSaved(req, options, target.collection, target.id, locale);
+    if (!saved) {
+        return { ok: false, error: "tool_denied", message: "Document is not accessible." };
+    }
+    const fields = entityFields(req, options, { collection: target.collection });
+    const allowedPaths = await allowedPathsFor(req, options, input, locale, fields, saved.data);
+    if (!allowedPaths.ok) {
+        return { ok: false, error: allowedPaths.error };
+    }
+    const message = input.instruction?.trim()
+        ? `${input.prompt.trim()}\n\n${input.instruction.trim()}`
+        : input.prompt.trim();
+    const result = await run(req, options, {
+        message,
+        messages: [{ role: "user", text: message }],
+        bridge: {
+            collection: target.collection,
+            documentId: target.id,
+            title: saved.title,
+            locale,
+            language: input.language,
+            uiLanguage: input.language,
+            selection: input.scope === "field" ? target.path : undefined,
+            batch: { allowedPaths: allowedPaths.paths, requestId: `batch:${input.batchId}` },
+        },
+        formData: saved.data,
+    });
+    if (!result.ok) {
+        return { ok: false, error: result.error, message: result.message };
+    }
+    const pending = result.pendingApproval;
+    if (pending?.capability !== "content.update") {
+        return { ok: true, text: result.text };
+    }
+    return {
+        ok: true,
+        text: result.text,
+        proposal: {
+            approvalId: pending.approvalId,
+            nonce: pending.nonce,
+            lines: pending.lines ?? pending.summary.split("\n").map((text) => ({ path: "", text })),
+        },
+    };
+}
+/** The finding's field, or every field a translation still has to fill. */
+async function allowedPathsFor(req, options, input, locale, fields, saved) {
+    if (input.scope === "field") {
+        return fieldAtPath(fields, input.target.path, saved)
+            ? { ok: true, paths: [input.target.path] }
+            : { ok: false, error: "tool_denied" };
+    }
+    const source = sourceLocale({
+        open: locale,
+        locales: configuredLocales(req),
+        defaultLocale: configuredDefaultLocale(req),
+    });
+    const from = source
+        ? await readSaved(req, options, input.target.collection, input.target.id, source)
+        : null;
+    if (!from) {
+        return { ok: false, error: "tool_denied" };
+    }
+    const empty = translationPaths(fields, saved, from.data).empty;
+    return empty.length ? { ok: true, paths: empty } : { ok: false, error: "nothing_to_do" };
+}
+async function readSaved(req, options, collection, id, locale) {
+    const read = await readDocument(req, options, { collection, documentId: id, locale });
+    if (!read.ok) {
+        return null;
+    }
+    const useAsTitle = findCollectionConfig(req, collection)?.admin?.useAsTitle;
+    const title = useAsTitle ? read.doc[useAsTitle] : undefined;
+    return {
+        data: projectRecord(read.doc, read.fields, options.redact, read.slug).data,
+        raw: read.doc,
+        title: typeof title === "string" && title ? title : undefined,
+    };
+}
+/**
+ * Saves one batch proposal to the document, or rejects it. Checked again as it is saved: the editor,
+ * the one-time approval, `content.update`, and that the saved document is still the one the proposal
+ * was made for. A collection with drafts gets a draft; one without is saved.
+ */
+export async function applyBatchTarget(req, options, input) {
+    await loadRichText();
+    const requestId = BATCH_ID.test(input.batchId) ? `batch:${input.batchId}` : undefined;
+    let record;
+    try {
+        record = (await localApi(req).findByID({
+            collection: DEFAULT_APPROVAL_SLUG,
+            id: input.approvalId,
+            req,
+            overrideAccess: false,
+            user: req.user,
+            depth: 0,
+        }));
+    }
+    catch {
+        return { ok: false, error: "tool_denied", message: "Approval is not valid." };
+    }
+    if (!record ||
+        record.actor !== String(req.user?.id) ||
+        record.nonce !== input.nonce ||
+        record.capability !== "content.update" ||
+        !record.targetCollection ||
+        !record.documentId) {
+        return { ok: false, error: "tool_denied", message: "Approval is not valid." };
+    }
+    if (record.status !== "proposed") {
+        return { ok: false, error: "tool_denied", message: "Approval is no longer usable." };
+    }
+    const event = {
+        capability: "content.update",
+        risk: "approval",
+        targetCollection: record.targetCollection,
+        documentId: record.documentId,
+        locale: record.locale,
+        approvalId: String(record.id),
+        nonceId: record.nonce.slice(0, 8),
+        requestId,
+    };
+    if (new Date(record.expiresAt).getTime() <= Date.now()) {
+        await consume(req, record.id, "expired");
+        await writeAudit(req, options, { ...event, outcome: "expired" });
+        return { ok: false, error: "stale_context", message: "The proposal expired." };
+    }
+    if (input.action === "reject") {
+        await consume(req, record.id, "rejected");
+        await writeAudit(req, options, { ...event, outcome: "rejected" });
+        return { ok: true, status: "rejected" };
+    }
+    const fail = async (error, message) => {
+        await consume(req, record.id, "failed");
+        await writeAudit(req, options, { ...event, outcome: "failed", errorClass: error });
+        return { ok: false, error, message };
+    };
+    const resolved = resolveAllowlist(options, { collection: record.targetCollection });
+    if (!resolved || !hasCapability(resolved.allowlist, "content.update")) {
+        return fail("tool_denied", "Batch changes are not allowed here.");
+    }
+    if (!Array.isArray(record.operations) || !record.operations.every(isFormOperation)) {
+        return fail("tool_denied", "Stored operations are invalid.");
+    }
+    const stored = record.operations;
+    if ((await hashFormRevision(stored)) !== record.canonicalHash) {
+        return fail("tool_denied", "Proposal hash mismatch.");
+    }
+    const saved = await readSaved(req, options, record.targetCollection, record.documentId, record.locale);
+    if (!saved) {
+        return fail("tool_denied", "Document is not accessible.");
+    }
+    if ((await hashFormRevision(saved.data)) !== record.formRevision) {
+        return fail("stale_context", "The document changed after the proposal.");
+    }
+    const fields = entityFields(req, options, { collection: record.targetCollection });
+    const edited = withEdits(stored, input.edits, fields, saved.data);
+    if (!edited.ok) {
+        // Not the editor's approval to spend: the card can still be saved without the edit.
+        return { ok: false, error: "tool_denied", message: edited.message };
+    }
+    const operations = edited.operations;
+    const compiled = compileOperations(openRichText(saved.data, fields), operations, {
+        allowlist: resolved.allowlist.fields,
+        denyFields: options.denyFields,
+    });
+    if (!compiled.ok) {
+        return fail("tool_denied", compiled.error);
+    }
+    const finalized = finalizeCompiled(compiled.data, fields, saved.data);
+    if (!finalized.ok) {
+        return fail("tool_denied", finalized.error);
+    }
+    const paths = changedPaths(operations);
+    const relationError = relationValueError(fields, finalized.data, paths);
+    if (relationError) {
+        return fail("tool_denied", relationError);
+    }
+    if (options.validateProposal) {
+        const extra = await options.validateProposal({ operations, data: finalized.data });
+        if (!extra.ok) {
+            return fail("tool_denied", extra.errors.join(" "));
+        }
+    }
+    const relations = await verifyDocumentRelations(req, fields, finalized.data, finalized.links);
+    if (!relations.ok) {
+        return fail("tool_denied", relations.message);
+    }
+    const drafts = hasDrafts(findCollectionConfig(req, record.targetCollection)?.versions);
+    try {
+        await localApi(req).update({
+            collection: record.targetCollection,
+            id: record.documentId,
+            locale: record.locale,
+            data: changedTopLevel(saved.raw, finalized.data, paths),
+            draft: drafts,
+            depth: 0,
+            req,
+            user: req.user,
+            overrideAccess: false,
+            overrideLock: false,
+        });
+    }
+    catch (error) {
+        return isLocked(error)
+            ? fail("locked", "Someone else is editing the document.")
+            : fail("tool_denied", "The document could not be saved.");
+    }
+    const canonicalHash = await hashFormRevision(operations);
+    await consume(req, record.id, "executed");
+    // A hash that differs from the proposed event's says the editor changed the wording.
+    await writeAudit(req, options, {
+        ...event,
+        outcome: "executed",
+        fieldPaths: paths,
+        canonicalHash,
+        baseRevision: record.formRevision ?? undefined,
+    });
+    return { ok: true, status: drafts ? "draft" : "saved" };
+}
+/** The stored operations with the editor's wording, only where they set plain text. */
+function withEdits(operations, edits, fields, saved) {
+    if (!edits || Object.keys(edits).length === 0) {
+        return { ok: true, operations };
+    }
+    const next = cloneData(operations);
+    for (const [path, value] of Object.entries(edits)) {
+        const operation = next.find((entry) => entry.op === "set" && entry.path === path);
+        const type = fieldAtPath(fields, path, saved)?.type;
+        if (operation?.op !== "set" ||
+            typeof operation.value !== "string" ||
+            (type !== "text" && type !== "textarea") ||
+            typeof value !== "string" ||
+            value.length > MAX_EDIT_LENGTH) {
+            return { ok: false, message: `${path} cannot be edited here.` };
+        }
+        operation.value = value;
+    }
+    return { ok: true, operations: next };
+}
+/**
+ * The top-level fields the change reaches, as saved with only the changed values replaced, so
+ * fields the assistant does not see (denied, redacted) are written back as they were.
+ */
+function changedTopLevel(raw, changed, paths) {
+    const patched = cloneData(raw);
+    const data = {};
+    for (const path of paths) {
+        const segments = parseFieldPath(path);
+        setAtPath(patched, segments, getAtPath(changed, segments) ?? null);
+        const key = String(segments[0]);
+        data[key] = patched[key];
+    }
+    return data;
+}
+/** Payload's error for a document another editor has open (`Locked`, status 423). */
+function isLocked(error) {
+    const record = error;
+    return record?.name === "Locked" || record?.status === 423;
+}
+async function consume(req, id, status) {
+    await localApi(req).update({
+        collection: DEFAULT_APPROVAL_SLUG,
+        id,
+        data: { status },
+        req,
+        user: req.user,
+        overrideAccess: false,
+    });
+}
+/** What the panel shows before the batch runs: titles and whether each document can be changed. */
+export async function describeBatchTargets(req, options, targets) {
+    const infos = [];
+    // One after the other: the reads share the request.
+    for (const target of targets) {
+        const resolved = resolveAllowlist(options, { collection: target.collection });
+        const config = findCollectionConfig(req, target.collection);
+        const allowed = Boolean(resolved && hasCapability(resolved.allowlist, "content.update"));
+        const read = allowed
+            ? await readDocument(req, options, {
+                collection: target.collection,
+                documentId: target.id,
+                locale: target.locale ?? configuredDefaultLocale(req) ?? "en",
+            })
+            : undefined;
+        const doc = read?.ok ? read.doc : undefined;
+        const useAsTitle = config?.admin?.useAsTitle;
+        const title = [useAsTitle ? doc?.[useAsTitle] : undefined, doc?.filename].find((value) => typeof value === "string" && value.trim() !== "");
+        infos.push({
+            key: target.key,
+            title: title ?? target.id,
+            thumbnail: doc && config?.upload ? thumbnailOf(doc) : undefined,
+            drafts: hasDrafts(config?.versions),
+            allowed: Boolean(doc),
+        });
+    }
+    return infos;
+}
+function thumbnailOf(doc) {
+    const sizes = doc.sizes;
+    const candidates = [doc.thumbnailURL, sizes?.thumbnail?.url, doc.url];
+    const mimeType = typeof doc.mimeType === "string" ? doc.mimeType : "";
+    const url = candidates.find((value) => typeof value === "string" && !!value);
+    return url && (!mimeType || mimeType.startsWith("image/")) ? url : undefined;
+}

package/dist/domain/content.d.ts

@@ -1,5 +1,6 @@
 import type { PayloadRequest } from "payload";
 import type { ValidatedEditorAssistantOptions } from "../config/validate.ts";
+import type { FieldNode } from "../schema/fields.ts";
 export type ContentFindInput = {
     collection?: string;
     query: string;
@@ -28,3 +29,18 @@ export declare function findContentById(req: PayloadRequest, options: ValidatedE
     error: string;
     message: string;
 }>;
+/**
+ * A document or global as Admin reads it, with the editor's access: the latest draft, and a field
+ * nobody filled in this language empty rather than another language's text. Unprojected; callers
+ * project it or check their own capability first.
+ */
+export declare function readDocument(req: PayloadRequest, options: ValidatedEditorAssistantOptions, input: ContentFindByIdInput): Promise<{
+    ok: true;
+    doc: Record<string, unknown>;
+    fields: FieldNode[];
+    slug: string;
+} | {
+    ok: false;
+    error: string;
+    message: string;
+}>;

package/dist/domain/content.js

@@ -74,6 +74,18 @@ export async function findContentById(req, options, input) {
     if (!resolved || !hasCapability(resolved.allowlist, "content.findById")) {
         return { ok: false, error: "tool_denied", message: "Target is not allowlisted for read." };
     }
+    const read = await readDocument(req, options, input);
+    if (!read.ok) {
+        return read;
+    }
+    return { ok: true, ...projectRecord(read.doc, read.fields, options.redact, read.slug) };
+}
+/**
+ * A document or global as Admin reads it, with the editor's access: the latest draft, and a field
+ * nobody filled in this language empty rather than another language's text. Unprojected; callers
+ * project it or check their own capability first.
+ */
+export async function readDocument(req, options, input) {
     const fields = entityFields(req, options, input);
     try {
         if (input.global) {
@@ -85,15 +97,13 @@ export async function findContentById(req, options, input) {
                 slug: input.global,
                 depth: 0,
                 locale: input.locale,
-                // As Admin reads it: a field nobody filled in this language is empty, not another's text.
                 fallbackLocale: false,
                 draft: true,
                 req,
                 user: req.user,
                 overrideAccess: false,
             });
-            const projected = projectRecord(doc, fields, options.redact, input.global);
-            return { ok: true, ...projected };
+            return { ok: true, doc, fields, slug: input.global };
         }
         if (!input.collection || input.documentId === undefined) {
             return {
@@ -113,8 +123,7 @@ export async function findContentById(req, options, input) {
             user: req.user,
             overrideAccess: false,
         });
-        const projected = projectRecord(doc, fields, options.redact, input.collection);
-        return { ok: true, ...projected };
+        return { ok: true, doc, fields, slug: input.collection };
     }
     catch {
         return { ok: false, error: "tool_denied", message: "Document is not accessible." };

package/dist/domain/decide.js

@@ -27,6 +27,10 @@ export async function decideChange(req, options, input) {
     if (record.status !== "proposed") {
         return { ok: false, error: "tool_denied", message: "Approval is no longer usable." };
     }
+    // A batch change is saved or rejected from the batch, against the saved document.
+    if (record.capability === "content.update") {
+        return { ok: false, error: "tool_denied", message: "Approval belongs to a batch." };
+    }
     if (new Date(record.expiresAt).getTime() <= Date.now()) {
         await consume(req, record.id, "expired");
         return { ok: false, error: "stale_context", message: "Approval expired." };

package/dist/domain/guard.d.ts

@@ -9,5 +9,7 @@ export type GuardSuccess = {
     ok: true;
     actor: string;
 };
-export declare function guardMutationRequest(req: PayloadRequest, options: ValidatedEditorAssistantOptions): Promise<GuardFailure | GuardSuccess>;
+export declare function guardMutationRequest(req: PayloadRequest, options: ValidatedEditorAssistantOptions, guard?: {
+    rateLimit?: boolean;
+}): Promise<GuardFailure | GuardSuccess>;
 export declare function readJsonBody<T>(req: PayloadRequest): Promise<T | null>;

package/dist/domain/guard.js

@@ -1,6 +1,6 @@
 import { verifyCsrf, verifyOrigin } from "../endpoints/csrf.js";
 import { consumeRateLimit } from "../runtime/rate-limit.js";
-export async function guardMutationRequest(req, options) {
+export async function guardMutationRequest(req, options, guard = {}) {
     if (!req.user) {
         return { ok: false, status: 401, error: "unauthorized" };
     }
@@ -11,7 +11,7 @@ export async function guardMutationRequest(req, options) {
         return { ok: false, status: 403, error: "unavailable" };
     }
     const actor = String(req.user.id);
-    if (!consumeRateLimit(actor)) {
+    if (guard.rateLimit !== false && !consumeRateLimit(actor)) {
         return { ok: false, status: 429, error: "rate_limited" };
     }
     return { ok: true, actor };

package/dist/domain/propose.d.ts

@@ -1,7 +1,7 @@
 import type { PayloadRequest } from "payload";
 import type { ValidatedEditorAssistantOptions } from "../config/validate.ts";
 export type ProposeInput = {
-    capability: "form.propose" | "draft.create";
+    capability: "form.propose" | "draft.create" | "content.update";
     collection?: string;
     global?: string;
     documentId?: string | number;
@@ -10,6 +10,23 @@ export type ProposeInput = {
     language?: "sv" | "en";
     operations: unknown;
     formData?: Record<string, unknown>;
+    /**
+     * `content.update` only: the fields the change may reach, each with what is under it. A batch
+     * proposal is against the saved document, so `formData` is ignored.
+     */
+    allowedPaths?: string[];
+    /** Logged with the audit events, e.g. `batch:<id>`. */
+    requestId?: string;
+};
+/** One line of the change list; a plain text value the editor may rewrite before saving has `edit`. */
+export type ProposalLine = {
+    path: string;
+    text: string;
+    edit?: {
+        label: string;
+        before: string;
+        value: string;
+    };
 };
 /** The form as it would be with a proposal applied, so Admin can show it before it is kept. */
 export type ProposalPreview = {
@@ -23,6 +40,9 @@ export type ProposeResult = {
     expiresAt: string;
     summary: string;
     title: string;
+    lines: ProposalLine[];
+    /** Characters in each plain text value set, as content health counts them. */
+    characters: Record<string, number>;
     preview?: ProposalPreview;
 } | {
     ok: false;
@@ -30,3 +50,9 @@ export type ProposeResult = {
     message: string;
 };
 export declare function proposeChange(req: PayloadRequest, options: ValidatedEditorAssistantOptions, input: ProposeInput): Promise<ProposeResult>;
+/** A saved document as the batch sees it: allowlisted fields in the target's language. */
+export declare function readSavedForm(req: PayloadRequest, options: ValidatedEditorAssistantOptions, target: {
+    collection?: string;
+    documentId?: string | number;
+    locale: string;
+}): Promise<Record<string, unknown> | null>;