@simmalugnt-se/payload-editor-assistant 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.1
+
+- Provider failures are logged on the server through Payload's logger (missing model, `ai` not
+  installed, or the provider's own error), instead of only showing `provider_error` in the drawer.
+- README: how to connect the provider's API key, what the assistant may do, and the options.
+
+## 0.1.0
+
+- First release.
+- `ai` is a required peer: the AI SDK is loaded with a literal import so bundlers can resolve it.

package/README.md

@@ -9,24 +9,84 @@ your choice.
 
 ## Setup
 
-```ts
-import { deepSeek } from "@ai-sdk/deepseek";
-import { editorAssistantPlugin } from "@simmalugnt-se/payload-editor-assistant";
-
-plugins: [
-  editorAssistantPlugin({
-    model: deepSeek("deepseek-chat"),
-    collections: {
-      pages: {
-        capabilities: ["content.find", "content.findById", "form.read", "form.propose", "draft.create"],
-      },
-    },
-    globals: {
-      header: { capabilities: ["content.findById", "form.read", "form.propose"] },
-    },
-  }),
-];
-```
-
-Then regenerate the import map (`pnpm payload generate:importmap`). See `EditorAssistantPluginOptions`
-for allowlists, host tools and instructions. Design notes live in `docs/research` and `.wayfinder`.
+1. Install the plugin, the AI SDK and a provider (DeepSeek here; any AI SDK provider works):
+
+   ```bash
+   pnpm add @simmalugnt-se/payload-editor-assistant ai @ai-sdk/deepseek
+   ```
+
+2. Put the provider's API key in the server environment, e.g. `.env.local` locally and the
+   hosting provider's environment variables in production. Never expose it to the browser
+   (no `NEXT_PUBLIC_` prefix):
+
+   ```bash
+   DEEPSEEK_API_KEY=sk-...
+   ```
+
+3. Create the model with that key and pass it to the plugin:
+
+   ```ts
+   import { createDeepSeek } from "@ai-sdk/deepseek";
+   import { editorAssistantPlugin } from "@simmalugnt-se/payload-editor-assistant";
+
+   const deepSeek = createDeepSeek({ apiKey: process.env.DEEPSEEK_API_KEY });
+
+   plugins: [
+     editorAssistantPlugin({
+       model: deepSeek("deepseek-chat"),
+       collections: {
+         pages: {
+           capabilities: ["content.find", "content.findById", "form.read", "form.propose", "draft.create"],
+         },
+       },
+       globals: {
+         header: { capabilities: ["content.findById", "form.read", "form.propose"] },
+       },
+     }),
+   ];
+   ```
+
+4. Regenerate the import map: `pnpm payload generate:importmap`.
+
+## API keys
+
+The plugin has no provider or key of its own: it only receives the `model` you create, and the model
+is called on the server. To switch provider, install another AI SDK provider and create the model
+with its key, e.g. `createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY })`.
+
+Providers also read a default environment variable (`DEEPSEEK_API_KEY`, `ANTHROPIC_API_KEY`, ...)
+when no `apiKey` is passed, but passing it explicitly keeps the connection visible in your config.
+
+If the key is missing or wrong, the drawer shows `provider_error` and the cause is logged on the
+server through Payload's logger.
+
+## What the assistant may do
+
+Nothing is reachable unless you list it. Each collection or global gets the capabilities it allows:
+
+| Capability | What it does | Needs approval |
+|---|---|---|
+| `content.find` | search and list documents | no |
+| `content.findById` | read one document | no |
+| `form.read` | read the open edit form, including unsaved changes | no |
+| `form.propose` | propose changes to the open form; the editor reviews them before they apply | yes |
+| `draft.create` | create a new draft document (collections only) | yes |
+
+The assistant never publishes. Approved form changes land in the open form and the editor saves as
+usual; an approved `draft.create` saves a new, unpublished draft. The `users` collection, Payload's own collections and fields that look like
+secrets (`password`, `token`, `apiKey`, ...) are always off limits.
+
+## Options
+
+| Option | |
+|---|---|
+| `model` | The AI SDK model, or `({ userId }) => model` to choose per user. Required unless `disabled`. |
+| `collections`, `globals` | `{ [slug]: { capabilities, fields? } }`. `fields` narrows what is visible: `{ include: [...] }` or `{ exclude: [...] }`. |
+| `denyFields` | Field names hidden from the assistant in every collection and global. |
+| `instructions` | Project rules the assistant cannot infer from the schema, e.g. "the start page has slug `home`". |
+| `shortcuts` | One-click prompts in the drawer: `{ id, label, prompt, when?, entities? }`. |
+| `enabled` | `({ userId }) => boolean` to offer the assistant to some users only. |
+| `redact` | `({ slug, data }) => data` to strip values before documents reach the model. |
+| `trustedOrigins` | Origins allowed to call the assistant's endpoints. Default: only the origin serving Admin. When set, only the listed origins. |
+| `audit.collection` | Slug of the collection that logs assistant actions (default `editor-assistant-audit`). |
+| `disabled` | Turn the plugin off without removing its config. |

package/dist/runtime/agent.js

@@ -1,3 +1,4 @@
+import { PACKAGE_NAME } from "../package-name.js";
 import { loadTurnContext } from "./context.js";
 import { needsProposeRetry } from "./propose-loop.js";
 import { buildSystemPrompt } from "./system-prompt.js";
@@ -9,10 +10,12 @@ const TIMEOUT_MS = 60_000;
 export async function runAgentTurn(req, options, input) {
     const model = await resolveModel(options, req.user?.id);
     if (!model) {
+        logProviderError(req, "no model: the `model` option resolved to nothing for this user");
         return { ok: false, error: "provider_error" };
     }
     const ai = await loadAiSdk();
     if (!ai) {
+        logProviderError(req, "could not load the AI SDK: is `ai` installed in the project?");
         return { ok: false, error: "provider_error" };
     }
     const ctx = {
@@ -39,6 +42,7 @@ export async function runAgentTurn(req, options, input) {
             signal,
         });
         if (!first) {
+            logProviderError(req, "the model returned no result");
             return { ok: false, error: "provider_error" };
         }
         const collected = collectResult(String(first.text ?? ""), first, captured, input.bridge.language ?? input.bridge.locale);
@@ -79,6 +83,7 @@ export async function runAgentTurn(req, options, input) {
         if (signal.aborted) {
             return { ok: false, error: "timeout" };
         }
+        logProviderError(req, "the model provider failed", error);
         return {
             ok: false,
             error: "provider_error",
@@ -246,6 +251,13 @@ async function resolveModel(options, userId) {
     }
     return options.model;
 }
+/**
+ * The drawer only shows "provider_error"; the cause (missing key, wrong model id, provider outage)
+ * belongs in the server log where the host can see it.
+ */
+function logProviderError(req, message, error) {
+    req.payload?.logger?.error({ err: error, msg: `${PACKAGE_NAME}: ${message}` });
+}
 async function loadAiSdk() {
     try {
         // A literal specifier: bundlers only resolve `import()` they can read, and the host's `ai`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simmalugnt-se/payload-editor-assistant",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Context-aware editor assistant plugin for Payload Admin",
   "keywords": [
     "payload",
@@ -18,7 +18,8 @@
     "node": ">=22"
   },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md"
   ],
   "sideEffects": [
     "*.css"