@humaan/payload-plugin-ai-assistant 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,278 @@
-# Temporary Holding Version
+# @humaan/payload-plugin-ai-assistant
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Adds Humaan AI to the Payload admin: a side panel where editors chat with an assistant that reads the site's content, answers questions, and proposes changes as plans. Nothing is saved until the editor reviews the plan and chooses Proceed.
+
+Models run through [Vercel AI Gateway](https://vercel.com/docs/ai-gateway), authenticated with the deployment's [OIDC token](https://vercel.com/docs/ai-gateway/authentication-and-byok/oidc), so spend is billed to the Vercel project. The site must run on Vercel. Requires Payload 3.90 or later.
+
+## Install
+
+```bash
+pnpm add @humaan/payload-plugin-ai-assistant
+```
+
+The admin styles are Sass modules, so the project needs `sass` installed.
+
+Add the plugin **last** in `plugins`, so it sees collections other plugins add:
+
+```ts
+import { aiAssistantPlugin } from '@humaan/payload-plugin-ai-assistant'
+
+export default buildConfig({
+  plugins: [
+    // …other plugins first
+    aiAssistantPlugin({
+      roles: [
+        { label: 'Admin', value: 'admin' },
+        { label: 'Editor', value: 'editor' },
+      ],
+      siteRules: 'Write in Australian English. Use the Oxford comma.',
+      timeZone: 'Australia/Perth',
+    }),
+  ],
+})
+```
+
+Then:
+
+1. Register the attachments collection, if editors should attach files (see [Attachments](#attachments)).
+2. Run `pnpm generate:importmap && pnpm generate:types`.
+3. Set up Vercel (below).
+
+## Options
+
+| Option                                | Default                         | Purpose                                                                                                                 |
+| ------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `roles`                               | required                        | User roles an admin can allow to run the assistant. Users need a `role` field.                                          |
+| `siteRules`                           | required                        | Editorial rules editors' prompts cannot override.                                                                       |
+| `model`                               | `"anthropic/claude-sonnet-5.5"` | AI Gateway model id. Needs vision and tool use.                                                                         |
+| `deniedCollections` / `deniedGlobals` | `[]`                            | Can be read but not changed. Unknown slugs throw at startup.                                                            |
+| `byok`                                | none                            | The site's own provider credentials. See [Own provider key](#own-provider-key).                                         |
+| `timeZone`                            | `"UTC"`                         | When the daily cap resets, and how dates are shown.                                                                     |
+| `adminGroup`                          | `"Settings"`                    | Admin nav group for the settings.                                                                                       |
+| `collectionRules`                     | none                            | Guidance for a whole collection or global. Prefer field guidance (see [Guiding the assistant](#guiding-the-assistant)). |
+| `enabled`                             | `true`                          | `false` keeps the schema but adds no panel or endpoints.                                                                |
+
+## Vercel setup
+
+| Needs                      | Where from                                                                  |
+| -------------------------- | --------------------------------------------------------------------------- |
+| `VERCEL_OIDC_TOKEN`        | Issued to each deployment. Locally, pulled with the Vercel CLI.             |
+| A project budget           | **AI Gateway → Budgets → Projects** in Vercel.                              |
+| `VERCEL_BUDGET_READ_TOKEN` | A read-only Vercel access token. Used for the budget bar and the daily cap. |
+
+### Budgets
+
+Each site is held to its own **project budget**. Set:
+
+- a **project default budget** as a catch-all for every project without one;
+- a **custom budget** on each client project, monthly, with spend alerts at 50%, 75%, and 100%;
+- optionally, a **team budget** across all clients.
+
+```sh
+vercel ai-gateway budgets set project --default --limit 20 --refresh-period monthly
+vercel ai-gateway budgets set project <project-name> --limit 100 --refresh-period monthly
+```
+
+Budgets reset at the start of each period in UTC. A project's admins can change its budget, so keep client users off the Vercel team.
+
+### Budget-reading token
+
+1. Invite a shared service account (such as `support+vercel@humaan.com.au`) to the team with the **Pro Viewer** role. It's free and read-only.
+2. Signed in as that account, create a token at [vercel.com/account/tokens](https://vercel.com/account/tokens), scoped to the team with **All Projects**, with an expiry.
+3. Add it as a team **shared environment variable**, `VERCEL_BUDGET_READ_TOKEN`, type **Secret**, for Production and Preview, linked to each project. Redeploy.
+
+To rotate: create a new token, update the variable, redeploy, then delete the old token.
+
+### Check it
+
+**Settings → Humaan AI** shows the share of the budget used and the reset date, or why it can't be read:
+
+| Message                                   | Fix                                                               |
+| ----------------------------------------- | ----------------------------------------------------------------- |
+| No Vercel OIDC token                      | Locally, see [Local development](#local-development).             |
+| Set `VERCEL_BUDGET_READ_TOKEN`            | Link the variable to this project and environment, then redeploy. |
+| Vercel refused `VERCEL_BUDGET_READ_TOKEN` | The token expired, was revoked, or is scoped to another team.     |
+| No AI Gateway budget                      | Add a custom budget to the project.                               |
+
+### Local development
+
+Use a current Vercel CLI (`brew install --cask vercel`; version 41 can't log in).
+
+```sh
+vercel login
+vercel link                        # the existing project; don't create one
+vercel env pull .env.vercel.local  # copy VERCEL_OIDC_TOKEN into .env.local, then delete the file
+```
+
+Add `VERCEL_BUDGET_READ_TOKEN` to `.env.local` by hand: Secret values can't be pulled. Without it the assistant still runs, with no budget bar or daily cap.
+
+## Own provider key
+
+A client can pay for the model with their own provider account. The site still calls the gateway, but sends the client's credentials with each request ([request-scoped BYOK](https://vercel.com/docs/ai-gateway/authentication-and-byok/byok#request-scoped-byok)), so the provider bills the client with no markup.
+
+Pass credentials in the `byok` option, in the gateway's shape, reading environment variables you choose:
+
+```ts
+byok: {
+	anthropic: { apiKey: process.env.AI_ASSISTANT_ANTHROPIC_API_KEY },
+	// bedrock: { accessKeyId: process.env.…, secretAccessKey: process.env.…, region: "ap-southeast-2" },
+	// openai: [{ apiKey: process.env.… }, { apiKey: process.env.… }],  // tried in order
+},
+```
+
+- Any [gateway provider](https://vercel.com/docs/ai-gateway/authentication-and-byok/byok#credential-structure-by-provider) works, as long as it serves the `model`.
+- A credential is used only when every value is set, so the option can stay in the config everywhere and turns on where its variables are populated. A malformed option throws at startup.
+- Set the variables on that client's project as **Secret**, then redeploy. Don't add them on Vercel's team **Bring Your Own Key** page, which applies them to every project.
+- Choose it in **Settings → Humaan AI → AI Source**.
+
+On the own key:
+
+- **No budget or daily cap applies.** The client's provider account is the limit.
+- **Fallbacks bill Humaan.** If the credentials fail, the gateway retries on Vercel's credentials, which can't be turned off. Keep a small project budget on every site. Fallbacks are flagged at the top of the settings screen and in the panel.
+- **Admins see spend in US dollars** at the gateway's list price, this month and today. The provider's invoice is the record.
+- **Credentials stay on the server.** They are only sent to the gateway, and removed from error messages.
+
+## Settings
+
+The **Humaan AI** global, admin only:
+
+| Setting                    | What it does                                                                                                              |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Alerts                     | Warnings at the top: own key misconfigured, or calls that fell back to Humaan AI's credit this month.                     |
+| AI Source                  | **Humaan AI** or **Own provider key**. Only shown when `byok` credentials are complete.                                   |
+| Humaan AI Budget           | Read-only. Share of the budget used and the reset date, or, on the own key, spend on it. Follows AI Source before saving. |
+| Who can run it             | Roles from the `roles` option.                                                                                            |
+| Daily spend cap per editor | Share of the budget each editor can spend per day. Default `5`, `0` for none. Humaan AI only.                             |
+
+The panel shows editors their share of today's cap, and admins the share of the budget left, flagged low at 80% used. When the budget runs out, editors see the reset date rather than dollar amounts.
+
+## Database
+
+The plugin adds these to the database. All collections are hidden from the admin nav.
+
+| Slug                       | Type              | Holds                                                                                         |
+| -------------------------- | ----------------- | --------------------------------------------------------------------------------------------- |
+| `ai-assistant`             | Global            | AI Source, allowed roles, daily cap.                                                          |
+| `ai-assistant-threads`     | Collection        | Each editor's conversations: messages and attached file ids.                                  |
+| `ai-assistant-plans`       | Collection        | Proposed changes awaiting Proceed or Cancel, with status.                                     |
+| `ai-assistant-usage`       | Collection        | Spend per editor per day: Humaan AI cost, own-key cost, fallbacks, tokens, replies.           |
+| `ai-assistant-attachments` | Upload collection | Files editors attach. **The project registers it** (see below). Deleted 30 days after upload. |
+
+Each document belongs to one user. Users read and delete their own; admins can also read everyone's usage. Only the plugin's endpoints write them.
+
+## Attachments
+
+Editors can attach images, PDFs, and other files. Register the collection in the project, so your storage adapter handles it:
+
+```ts
+import {
+  aiAssistantAttachmentSlug,
+  aiAssistantAttachmentsCollection,
+} from '@humaan/payload-plugin-ai-assistant'
+
+export default buildConfig({
+  collections: [...collections, aiAssistantAttachmentsCollection()],
+  plugins: [
+    s3Storage({ collections: { [aiAssistantAttachmentSlug]: true }, clientUploads: true }),
+    // …Humaan AI last
+  ],
+})
+```
+
+- Works with any storage adapter. Without the collection, the panel works without attachments.
+- Turn on `clientUploads`: Vercel limits request bodies to 4.5 MB.
+- Keep the files private (for example `{ private: true }` with ImageKit).
+- Limits: 8 files per conversation, images up to 6 MB, other files up to 20 MB. Programs and scripts are refused.
+
+## Guiding the assistant
+
+The assistant learns each collection from the schema. Add guidance:
+
+- `admin.description` on a field, when it helps editors too;
+- `custom: { aiAssistant: "…" }` on a field, block, collection, or global, when only the assistant needs it;
+- `siteRules` for rules that apply everywhere.
+
+```ts
+{ name: "pageType", type: "select", custom: { aiAssistant: "New pages are content pages. Choose home only when asked." } }
+```
+
+## Security
+
+- Endpoints need a logged-in user with an allowed role.
+- Every read and write runs with that user's access (`overrideAccess: false`), so the assistant can only do what the editor could.
+- The model only proposes. Proceed applies the stored plan after checking its owner, its status, and the denied lists.
+- Always denied: auth collections, `payload-*` collections, and the plugin's own. Publish status can't be set.
+- Content the assistant reads could contain instructions aimed at it. The editor's review of each plan, showing current and proposed values, is the safeguard.
+
+## Development
+
+The `dev` folder holds a Payload app for working on the plugin. To run it:
+
+1. Copy `dev/.env.example` to `dev/.env`. Set `PAYLOAD_SECRET` to any random string, and point `DATABASE_URL` at a local MongoDB. The example value, `mongodb://127.0.0.1/payload-plugin-ai-assistant`, works with MongoDB's default port.
+2. To chat with the assistant, add `VERCEL_OIDC_TOKEN` to `dev/.env` (see [Local development](#local-development)). Without it the admin still loads, but the panel can't reach a model.
+3. Run `pnpm dev` and open `http://localhost:3000/admin`. Add `--port 3001` if another app already uses port 3000.
+
+```bash
+pnpm generate:importmap
+pnpm generate:types
+pnpm lint
+pnpm test:int
+pnpm test:e2e
+pnpm build
+```
+
+`pnpm test:int` runs the unit tests in `src/**/*.test.ts` with Node's test runner. `src/plugin.test.ts` checks the plugin against Payload's plugin contract.
+
+`pnpm test:e2e` runs the Playwright tests. Install their browser once with `pnpm exec playwright install chromium`. The tests start the dev app with an in-memory database on port 3000. If something is already running on port 3000, they use it instead, so stop any other app there first.
+
+## Releasing
+
+Features land on `main` by pull request as usual. To cut a release:
+
+1. **Actions → Version → Run workflow**, and pick a bump type (`patch`, `minor`, `major`,
+   `prerelease`, or `custom` with an explicit version).
+
+   It bumps `package.json`, regenerates `CHANGELOG.md`, and opens a `chore(release): vX.Y.Z`
+   pull request.
+
+2. Nothing else to do. `humaan-bot` opens the pull request, its checks start automatically, and
+   GitHub merges it with the repository's normal squash strategy once all lifecycle gates pass.
+   Failed checks leave the pull request open and unmerged.
+
+3. CI runs on `main`, then the `Release` workflow publishes to npm, tags
+   `vX.Y.Z`, and creates the GitHub release.
+
+The version bump cannot be pushed to `main` by CI — the branch ruleset requires status checks a
+direct push can never satisfy — so it goes through the protected pull request path like any other
+change. See [ADR 0001](docs/adr/0001-release-by-pull-request.md) for the reasoning.
+
+### If a publish fails
+
+Re-run **Actions → Release → Run workflow** with `confirm` set to `publish`. Nothing on `main`
+changed, so the same unpublished version is picked up, and the tag is only pushed after a
+successful publish — a failure never leaves an orphan tag behind.
+
+Do **not** cut a new version to work around a failed publish. `Version` will refuse to bump while
+the version on `main` is missing from npm, because that would skip a version number.
+
+Ticking `dry_run` on `Release` reports the version and dist-tag it would use and publishes
+nothing.
+
+### Bumping locally
+
+`Version` runs the same script you can run yourself, if you would rather prepare the release
+branch by hand:
+
+```bash
+pnpm release:bump patch
+```
+
+It rewrites `package.json`, regenerates `CHANGELOG.md`, and prints the branch and commit steps.
+The pull request title must be exactly `chore(release): vX.Y.Z` — `validate` requires a
+conventional commit, and `Release` keys off that prefix to decide whether a merge is a release.
+
+### Prerelease versions
+
+A version with a prerelease identifier publishes under a matching dist-tag instead of `latest`:
+`alpha`, `beta`, `rc`, and `next` map to themselves, anything else to `next`. The `prerelease`
+bump type uses the `beta` identifier.

package/dist/admin/AiAssistantControl.d.ts

@@ -0,0 +1,11 @@
+import type { ServerProps } from 'payload';
+import type { AssistantSettings } from '../types.js';
+type AiAssistantControlProps = {
+    fallbackSettings?: AssistantSettings;
+} & ServerProps;
+/**
+ * Header control, rendered beside the account link.
+ * Settings are read on the server and only the panel's own props reach the client.
+ */
+export declare function AiAssistantControl({ payload, user, fallbackSettings, }: AiAssistantControlProps): Promise<import("react").JSX.Element | null>;
+export {};

package/dist/admin/AiAssistantControl.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { aiAssistantAttachmentSlug, aiAssistantGlobalSlug, defaultDailySpendCapPercent } from '../constants.js';
+import { canUseAssistant, parseSettings } from '../settings.js';
+import { AiAssistantPanel } from './AiAssistantPanel.js';
+/**
+ * Header control, rendered beside the account link.
+ * Settings are read on the server and only the panel's own props reach the client.
+ */ export async function AiAssistantControl({ payload, user, fallbackSettings }) {
+    const stored = await payload.findGlobal({
+        slug: aiAssistantGlobalSlug,
+        depth: 0,
+        overrideAccess: true
+    });
+    const fallback = fallbackSettings ?? {
+        billing: 'vercel',
+        allowedRoles: [
+            'admin'
+        ],
+        dailySpendCapPercent: defaultDailySpendCapPercent
+    };
+    const settings = parseSettings(stored, fallback);
+    if (!canUseAssistant(user, settings)) {
+        return null;
+    }
+    // Attaching files needs the project to register the attachments collection with its storage.
+    return /*#__PURE__*/ _jsx(AiAssistantPanel, {
+        attachmentsEnabled: Boolean(payload.collections[aiAssistantAttachmentSlug])
+    });
+}
+
+//# sourceMappingURL=AiAssistantControl.js.map

package/dist/admin/AiAssistantControl.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/admin/AiAssistantControl.tsx"],"sourcesContent":["import type { GlobalSlug, ServerProps } from 'payload'\n\nimport type { AssistantSettings } from '../types.js'\n\nimport {\n  aiAssistantAttachmentSlug,\n  aiAssistantGlobalSlug,\n  defaultDailySpendCapPercent,\n} from '../constants.js'\nimport { canUseAssistant, parseSettings } from '../settings.js'\nimport { AiAssistantPanel } from './AiAssistantPanel.js'\n\ntype AiAssistantControlProps = {\n  fallbackSettings?: AssistantSettings\n} & ServerProps\n\n/**\n * Header control, rendered beside the account link.\n * Settings are read on the server and only the panel's own props reach the client.\n */\nexport async function AiAssistantControl({\n  payload,\n  user,\n  fallbackSettings,\n}: AiAssistantControlProps) {\n  const stored = await payload.findGlobal({\n    slug: aiAssistantGlobalSlug as GlobalSlug,\n    depth: 0,\n    overrideAccess: true,\n  })\n  const fallback: AssistantSettings = fallbackSettings ?? {\n    billing: 'vercel',\n    allowedRoles: ['admin'],\n    dailySpendCapPercent: defaultDailySpendCapPercent,\n  }\n  const settings = parseSettings(stored, fallback)\n  if (!canUseAssistant(user, settings)) {\n    return null\n  }\n\n  // Attaching files needs the project to register the attachments collection with its storage.\n  return (\n    <AiAssistantPanel\n      attachmentsEnabled={Boolean(payload.collections[aiAssistantAttachmentSlug as never])}\n    />\n  )\n}\n"],"names":["aiAssistantAttachmentSlug","aiAssistantGlobalSlug","defaultDailySpendCapPercent","canUseAssistant","parseSettings","AiAssistantPanel","AiAssistantControl","payload","user","fallbackSettings","stored","findGlobal","slug","depth","overrideAccess","fallback","billing","allowedRoles","dailySpendCapPercent","settings","attachmentsEnabled","Boolean","collections"],"mappings":";AAIA,SACEA,yBAAyB,EACzBC,qBAAqB,EACrBC,2BAA2B,QACtB,kBAAiB;AACxB,SAASC,eAAe,EAAEC,aAAa,QAAQ,iBAAgB;AAC/D,SAASC,gBAAgB,QAAQ,wBAAuB;AAMxD;;;CAGC,GACD,OAAO,eAAeC,mBAAmB,EACvCC,OAAO,EACPC,IAAI,EACJC,gBAAgB,EACQ;IACxB,MAAMC,SAAS,MAAMH,QAAQI,UAAU,CAAC;QACtCC,MAAMX;QACNY,OAAO;QACPC,gBAAgB;IAClB;IACA,MAAMC,WAA8BN,oBAAoB;QACtDO,SAAS;QACTC,cAAc;YAAC;SAAQ;QACvBC,sBAAsBhB;IACxB;IACA,MAAMiB,WAAWf,cAAcM,QAAQK;IACvC,IAAI,CAACZ,gBAAgBK,MAAMW,WAAW;QACpC,OAAO;IACT;IAEA,6FAA6F;IAC7F,qBACE,KAACd;QACCe,oBAAoBC,QAAQd,QAAQe,WAAW,CAACtB,0BAAmC;;AAGzF"}

package/dist/admin/AiAssistantPanel.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A side panel, not a modal, so the page being edited stays visible and usable beside the conversation.
+ * It stays mounted once opened, so closing it keeps the conversation.
+ */
+interface AiAssistantPanelProps {
+    /** Whether the project registered the attachments collection. */
+    attachmentsEnabled: boolean;
+}
+export declare function AiAssistantPanel({ attachmentsEnabled }: AiAssistantPanelProps): import("react").JSX.Element;
+export {};

package/dist/admin/AiAssistantPanel.js

@@ -0,0 +1,208 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Button, useConfig } from '@payloadcms/ui';
+import { generateId } from 'ai';
+import { useEffect, useId, useState } from 'react';
+import { createPortal } from 'react-dom';
+import styles from './AiAssistantPanel.module.scss';
+import { Conversation } from './Conversation.js';
+import { listThreads, loadThread, threadOptionLabel } from './threads.js';
+import { UsageSummary } from './UsageSummary.js';
+export function AiAssistantPanel({ attachmentsEnabled }) {
+    const { config } = useConfig();
+    const apiRoute = config.routes?.api ?? '/api';
+    const toggleId = useId();
+    const panelId = useId();
+    const titleId = useId();
+    const [open, setOpen] = useState(false);
+    // The portal needs document.body, so the panel renders only after the first open, which is client only.
+    const [opened, setOpened] = useState(false);
+    const show = ()=>{
+        setOpened(true);
+        setOpen(true);
+        requestAnimationFrame(()=>document.getElementById(panelId)?.querySelector('textarea')?.focus());
+    };
+    const close = ()=>{
+        setOpen(false);
+        document.getElementById(toggleId)?.focus();
+    };
+    // Escape closes the panel while focus is inside it, and hands focus back to the button that opened it.
+    useEffect(()=>{
+        if (!open) {
+            return;
+        }
+        const onKeyDown = (event)=>{
+            if (event.key !== 'Escape' || event.defaultPrevented) {
+                return;
+            }
+            if (!(event.target instanceof Node) || !document.getElementById(panelId)?.contains(event.target)) {
+                return;
+            }
+            event.preventDefault();
+            setOpen(false);
+            document.getElementById(toggleId)?.focus();
+        };
+        document.addEventListener('keydown', onKeyDown);
+        return ()=>document.removeEventListener('keydown', onKeyDown);
+    }, [
+        open,
+        panelId,
+        toggleId
+    ]);
+    return /*#__PURE__*/ _jsxs(_Fragment, {
+        children: [
+            /*#__PURE__*/ _jsx(Button, {
+                buttonStyle: "secondary",
+                extraButtonProps: {
+                    'aria-expanded': open,
+                    'aria-controls': panelId
+                },
+                id: toggleId,
+                margin: false,
+                onClick: ()=>open ? close() : show(),
+                size: "small",
+                type: "button",
+                children: "Humaan AI"
+            }),
+            opened ? /*#__PURE__*/ createPortal(/*#__PURE__*/ _jsxs("aside", {
+                "aria-labelledby": titleId,
+                className: styles.panel,
+                hidden: !open,
+                id: panelId,
+                children: [
+                    /*#__PURE__*/ _jsxs("div", {
+                        className: styles.panel__header,
+                        children: [
+                            /*#__PURE__*/ _jsx("h2", {
+                                className: styles.panel__title,
+                                id: titleId,
+                                children: "Humaan AI"
+                            }),
+                            /*#__PURE__*/ _jsx(UsageSummary, {
+                                apiRoute: apiRoute,
+                                open: open
+                            }),
+                            /*#__PURE__*/ _jsxs("button", {
+                                className: styles.panel__iconButton,
+                                onClick: close,
+                                type: "button",
+                                children: [
+                                    /*#__PURE__*/ _jsx("span", {
+                                        "aria-hidden": "true",
+                                        children: "×"
+                                    }),
+                                    /*#__PURE__*/ _jsx("span", {
+                                        className: styles.assistant__sr,
+                                        children: "Close Humaan AI"
+                                    })
+                                ]
+                            })
+                        ]
+                    }),
+                    /*#__PURE__*/ _jsx(AssistantThreads, {
+                        apiRoute: apiRoute,
+                        attachmentsEnabled: attachmentsEnabled
+                    })
+                ]
+            }), document.body) : null
+        ]
+    });
+}
+function AssistantThreads({ apiRoute, attachmentsEnabled }) {
+    const pickerId = useId();
+    const [session, setSession] = useState(newSession);
+    const [threads, setThreads] = useState([]);
+    const [threadsVersion, setThreadsVersion] = useState(0);
+    const [loadError, setLoadError] = useState('');
+    useEffect(()=>{
+        const controller = new AbortController();
+        listThreads(apiRoute, controller.signal).then(setThreads).catch(()=>undefined);
+        return ()=>controller.abort();
+    }, [
+        apiRoute,
+        threadsVersion
+    ]);
+    const openThread = async (chatId)=>{
+        setLoadError('');
+        if (!chatId) {
+            setSession(newSession());
+            return;
+        }
+        try {
+            setSession(await loadThread(apiRoute, chatId));
+        } catch (caught) {
+            setLoadError(caught instanceof Error ? caught.message : 'That conversation could not be opened.');
+        }
+    };
+    const listed = threads.some((thread)=>thread.chatId === session.chatId);
+    return /*#__PURE__*/ _jsxs("div", {
+        className: styles.assistant,
+        children: [
+            /*#__PURE__*/ _jsxs("div", {
+                className: styles.assistant__bar,
+                children: [
+                    /*#__PURE__*/ _jsx("label", {
+                        className: styles.assistant__sr,
+                        htmlFor: pickerId,
+                        children: "Conversation"
+                    }),
+                    /*#__PURE__*/ _jsx("div", {
+                        className: styles.assistant__selectWrap,
+                        children: /*#__PURE__*/ _jsxs("select", {
+                            className: styles.assistant__select,
+                            id: pickerId,
+                            onChange: (event)=>void openThread(event.target.value),
+                            value: listed ? session.chatId : '',
+                            children: [
+                                /*#__PURE__*/ _jsx("option", {
+                                    value: "",
+                                    children: "New conversation"
+                                }),
+                                threads.map((thread)=>/*#__PURE__*/ _jsx("option", {
+                                        value: thread.chatId,
+                                        children: threadOptionLabel(thread)
+                                    }, thread.chatId))
+                            ]
+                        })
+                    }),
+                    /*#__PURE__*/ _jsxs("button", {
+                        className: styles.assistant__barButton,
+                        onClick: ()=>void openThread(''),
+                        type: "button",
+                        children: [
+                            /*#__PURE__*/ _jsx("span", {
+                                "aria-hidden": "true",
+                                children: "+"
+                            }),
+                            " New",
+                            /*#__PURE__*/ _jsx("span", {
+                                className: styles.assistant__sr,
+                                children: " conversation"
+                            })
+                        ]
+                    })
+                ]
+            }),
+            loadError ? /*#__PURE__*/ _jsx("p", {
+                className: styles.assistant__error,
+                role: "alert",
+                children: loadError
+            }) : null,
+            /*#__PURE__*/ _jsx(Conversation, {
+                apiRoute: apiRoute,
+                attachmentsEnabled: attachmentsEnabled,
+                onReply: ()=>setThreadsVersion((version)=>version + 1),
+                session: session
+            }, session.chatId)
+        ]
+    });
+}
+function newSession() {
+    return {
+        chatId: generateId(),
+        messages: [],
+        attachments: []
+    };
+}
+
+//# sourceMappingURL=AiAssistantPanel.js.map

package/dist/admin/AiAssistantPanel.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/admin/AiAssistantPanel.tsx"],"sourcesContent":["'use client'\n\nimport { Button, useConfig } from '@payloadcms/ui'\nimport { generateId } from 'ai'\nimport { useEffect, useId, useState } from 'react'\nimport { createPortal } from 'react-dom'\n\nimport type { LoadedThread, ThreadSummary } from './threads.js'\n\nimport styles from './AiAssistantPanel.module.scss'\nimport { Conversation } from './Conversation.js'\nimport { listThreads, loadThread, threadOptionLabel } from './threads.js'\nimport { UsageSummary } from './UsageSummary.js'\n\n/**\n * A side panel, not a modal, so the page being edited stays visible and usable beside the conversation.\n * It stays mounted once opened, so closing it keeps the conversation.\n */\ninterface AiAssistantPanelProps {\n  /** Whether the project registered the attachments collection. */\n  attachmentsEnabled: boolean\n}\n\nexport function AiAssistantPanel({ attachmentsEnabled }: AiAssistantPanelProps) {\n  const { config } = useConfig()\n  const apiRoute = config.routes?.api ?? '/api'\n  const toggleId = useId()\n  const panelId = useId()\n  const titleId = useId()\n  const [open, setOpen] = useState(false)\n  // The portal needs document.body, so the panel renders only after the first open, which is client only.\n  const [opened, setOpened] = useState(false)\n\n  const show = () => {\n    setOpened(true)\n    setOpen(true)\n    requestAnimationFrame(() =>\n      document.getElementById(panelId)?.querySelector('textarea')?.focus(),\n    )\n  }\n\n  const close = () => {\n    setOpen(false)\n    document.getElementById(toggleId)?.focus()\n  }\n\n  // Escape closes the panel while focus is inside it, and hands focus back to the button that opened it.\n  useEffect(() => {\n    if (!open) {\n      return\n    }\n    const onKeyDown = (event: KeyboardEvent) => {\n      if (event.key !== 'Escape' || event.defaultPrevented) {\n        return\n      }\n      if (\n        !(event.target instanceof Node) ||\n        !document.getElementById(panelId)?.contains(event.target)\n      ) {\n        return\n      }\n      event.preventDefault()\n      setOpen(false)\n      document.getElementById(toggleId)?.focus()\n    }\n    document.addEventListener('keydown', onKeyDown)\n    return () => document.removeEventListener('keydown', onKeyDown)\n  }, [open, panelId, toggleId])\n\n  return (\n    <>\n      <Button\n        buttonStyle=\"secondary\"\n        extraButtonProps={{ 'aria-expanded': open, 'aria-controls': panelId }}\n        id={toggleId}\n        margin={false}\n        onClick={() => (open ? close() : show())}\n        size=\"small\"\n        type=\"button\"\n      >\n        Humaan AI\n      </Button>\n      {opened\n        ? createPortal(\n            <aside aria-labelledby={titleId} className={styles.panel} hidden={!open} id={panelId}>\n              <div className={styles.panel__header}>\n                <h2 className={styles.panel__title} id={titleId}>\n                  Humaan AI\n                </h2>\n                <UsageSummary apiRoute={apiRoute} open={open} />\n                <button className={styles.panel__iconButton} onClick={close} type=\"button\">\n                  <span aria-hidden=\"true\">×</span>\n                  <span className={styles.assistant__sr}>Close Humaan AI</span>\n                </button>\n              </div>\n              <AssistantThreads apiRoute={apiRoute} attachmentsEnabled={attachmentsEnabled} />\n            </aside>,\n            document.body,\n          )\n        : null}\n    </>\n  )\n}\n\nfunction AssistantThreads({\n  apiRoute,\n  attachmentsEnabled,\n}: {\n  apiRoute: string\n  attachmentsEnabled: boolean\n}) {\n  const pickerId = useId()\n  const [session, setSession] = useState<LoadedThread>(newSession)\n  const [threads, setThreads] = useState<ThreadSummary[]>([])\n  const [threadsVersion, setThreadsVersion] = useState(0)\n  const [loadError, setLoadError] = useState('')\n\n  useEffect(() => {\n    const controller = new AbortController()\n    listThreads(apiRoute, controller.signal)\n      .then(setThreads)\n      .catch(() => undefined)\n    return () => controller.abort()\n  }, [apiRoute, threadsVersion])\n\n  const openThread = async (chatId: string) => {\n    setLoadError('')\n    if (!chatId) {\n      setSession(newSession())\n      return\n    }\n    try {\n      setSession(await loadThread(apiRoute, chatId))\n    } catch (caught) {\n      setLoadError(\n        caught instanceof Error ? caught.message : 'That conversation could not be opened.',\n      )\n    }\n  }\n\n  const listed = threads.some((thread) => thread.chatId === session.chatId)\n\n  return (\n    <div className={styles.assistant}>\n      <div className={styles.assistant__bar}>\n        <label className={styles.assistant__sr} htmlFor={pickerId}>\n          Conversation\n        </label>\n        <div className={styles.assistant__selectWrap}>\n          <select\n            className={styles.assistant__select}\n            id={pickerId}\n            onChange={(event) => void openThread(event.target.value)}\n            value={listed ? session.chatId : ''}\n          >\n            <option value=\"\">New conversation</option>\n            {threads.map((thread) => (\n              <option key={thread.chatId} value={thread.chatId}>\n                {threadOptionLabel(thread)}\n              </option>\n            ))}\n          </select>\n        </div>\n        <button\n          className={styles.assistant__barButton}\n          onClick={() => void openThread('')}\n          type=\"button\"\n        >\n          <span aria-hidden=\"true\">+</span> New\n          <span className={styles.assistant__sr}> conversation</span>\n        </button>\n      </div>\n      {loadError ? (\n        <p className={styles.assistant__error} role=\"alert\">\n          {loadError}\n        </p>\n      ) : null}\n      <Conversation\n        apiRoute={apiRoute}\n        attachmentsEnabled={attachmentsEnabled}\n        key={session.chatId}\n        onReply={() => setThreadsVersion((version) => version + 1)}\n        session={session}\n      />\n    </div>\n  )\n}\n\nfunction newSession(): LoadedThread {\n  return { chatId: generateId(), messages: [], attachments: [] }\n}\n"],"names":["Button","useConfig","generateId","useEffect","useId","useState","createPortal","styles","Conversation","listThreads","loadThread","threadOptionLabel","UsageSummary","AiAssistantPanel","attachmentsEnabled","config","apiRoute","routes","api","toggleId","panelId","titleId","open","setOpen","opened","setOpened","show","requestAnimationFrame","document","getElementById","querySelector","focus","close","onKeyDown","event","key","defaultPrevented","target","Node","contains","preventDefault","addEventListener","removeEventListener","buttonStyle","extraButtonProps","id","margin","onClick","size","type","aside","aria-labelledby","className","panel","hidden","div","panel__header","h2","panel__title","button","panel__iconButton","span","aria-hidden","assistant__sr","AssistantThreads","body","pickerId","session","setSession","newSession","threads","setThreads","threadsVersion","setThreadsVersion","loadError","setLoadError","controller","AbortController","signal","then","catch","undefined","abort","openThread","chatId","caught","Error","message","listed","some","thread","assistant","assistant__bar","label","htmlFor","assistant__selectWrap","select","assistant__select","onChange","value","option","map","assistant__barButton","p","assistant__error","role","onReply","version","messages","attachments"],"mappings":"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"}