@forumone/throughline-publishing 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @forumone/throughline-publishing
 
+## 0.3.0
+
+### Minor Changes
+
+- 422b970: Ship the admin Publish/Unpublish controls and a server-side publishing API.
+
+  `publishingPlugin` blocked direct writes to `_status` — which is what Payload's native Publish button submits — but shipped no replacement, so no document in a publishable collection could be published from the admin. The pipeline was reachable only over the MCP endpoint, which requires an API key.
+  - **Admin controls.** The plugin now installs its own `PublishButton` and `UnpublishButton` on every configured collection, exported from `@forumone/throughline-publishing/client`. They run the pipeline as the logged-in editor over the session cookie — no API key, correct audit attribution — and render the failing step, its issues and its suggestion instead of a generic error. Hosts must run `payload generate:importmap`. Opt out with `adminComponents: false`; an explicit host-set slot is never overwritten.
+  - **Server-side API.** `publishDocument`, `unpublishDocument`, `getPublishStatus` and `getPublishingService` are now public, for host code that needs to publish outside the admin.
+  - **Audit attribution.** Publishes are attributed to the user who made them rather than to the API key that transported the call. Admin publishes record `mcpTool: 'admin:publish'`.
+  - **Access control.** Admin and host-API publishes run the underlying write with `overrideAccess: false` as that user, so bypassing the status hook does not bypass collection permissions.
+  - **Diagnosis.** The status-write hook now throws `APIError(…, 400)` rather than `Error`, so the message reaches the admin instead of becoming a 500 and a generic "Something went wrong" toast.
+
+  The MCP tools now route through the same service as the admin path, so the two channels cannot drift. Their input and output shapes are unchanged.
+
 ## 0.2.3
 
 ### Patch Changes

package/README.md

@@ -2,4 +2,130 @@
 
 Policy-gated publishing server for Throughline. The trust boundary that decides what's allowed to ship.
 
-_Authoring guide and full API reference land in a later commit._
+## What this package provides
+
+- **A publish pipeline** — `exist` → `composition` → `accessibility` → `required-fields` → `embargo` → `approval` → `execute`. The first step to object stops the publish and reports which one, why, and what to do about it.
+- **A trust boundary** — a `beforeChange` hook on every configured collection that rejects direct writes to `_status`. The pipeline is the only sanctioned way to publish.
+- **Admin controls** — Publish and Unpublish buttons that run the pipeline as the logged-in editor. Installed automatically; no host-side code.
+- **A server-side API** — `publishDocument` / `unpublishDocument` / `getPublishStatus` for host code that needs to publish outside the admin.
+- **Five MCP tools** served at `/api/publishing/mcp`: `publish`, `unpublish`, `schedule_publish`, `get_publish_status`, `rollback`.
+
+## Installation
+
+```bash
+pnpm add @forumone/throughline-publishing
+```
+
+Peers: `payload@^3.0.0`, `inngest@^4.0.0`. Required runtime peer: `@forumone/throughline-core` (audit log). The admin controls additionally use `@payloadcms/ui` and `react`, both already present in any Payload 3 admin.
+
+## Usage
+
+```ts
+import { buildConfig } from 'payload'
+import { auditPlugin, createInngestClient } from '@forumone/throughline-core'
+import { publishingPlugin } from '@forumone/throughline-publishing'
+
+const inngest = createInngestClient({ id: 'my-site' })
+
+export default buildConfig({
+  // collections, db, secret...
+  plugins: [
+    auditPlugin({ inngest }),
+    publishingPlugin({
+      inngest,
+      collections: [{ slug: 'pages' }],
+    }),
+  ],
+})
+```
+
+Publishable collections must have drafts enabled (`versions: { drafts: true }`).
+
+## Publishing from the admin
+
+The plugin replaces Payload's native Publish and Unpublish buttons on every configured collection. It has to: the native buttons submit `_status: 'published'` straight to the update endpoint, which is exactly the write the trust boundary exists to reject.
+
+The replacements save pending edits as a draft, then call the plugin's own endpoint, which runs the full pipeline. **Run `payload generate:importmap` after adding the plugin** so Payload can resolve the components — the dev server does this for you; CI builds need it explicitly.
+
+What you get:
+
+- **No API key in the editorial publish path.** The endpoint authenticates off the Payload session cookie.
+- **The person is the actor.** The audit event records the logged-in editor, with `mcpTool` set to `admin:publish` so admin publishes are distinguishable from MCP ones.
+- **Access control still applies.** The write runs with `overrideAccess: false` as that user. Bypassing the status hook is not bypassing permissions.
+- **Real feedback.** A blocked publish renders the failing step, its issues, and its suggestion — not a generic error.
+
+The Publish button is hidden on the create view: the pipeline's first step is `exist`, so there is nothing to evaluate until the draft is saved. Use Payload's Save Draft button, then publish from the edit view.
+
+To supply your own controls instead, either set `admin.components.edit.PublishButton` on the collection yourself (an explicit host setting always wins), or turn the feature off entirely:
+
+```ts
+publishingPlugin({ inngest, collections: [{ slug: 'pages' }], adminComponents: false })
+```
+
+With `adminComponents: false` the admin has **no** working publish path until you supply one — the native buttons will still be rejected by the hook.
+
+### Endpoints
+
+| Route | Auth | Body |
+|---|---|---|
+| `POST /api/publishing/publish` | Payload session | `{ collection, id }` |
+| `POST /api/publishing/unpublish` | Payload session | `{ collection, id }` |
+| `POST /api/publishing/mcp` | Bearer API key | JSON-RPC |
+
+A publish blocked by the pipeline returns **200** with `{ published: false, failedAt, reason, code, issues, suggestion }`. The pipeline ran correctly and the answer was no; that is not a transport error. Non-2xx is reserved for auth (401/403), bad input (400), and genuine failures (500).
+
+## Publishing from host code
+
+`runPublishPipeline` needs plugin options and an audit writer that only exist inside the plugin. Rather than export the raw pipeline, the plugin attaches a service to the Payload instance at `onInit` and exposes these helpers:
+
+```ts
+import { publishDocument, unpublishDocument, getPublishStatus } from '@forumone/throughline-publishing'
+
+// In a custom endpoint, job, or Server Action:
+const result = await publishDocument({
+  payload: req.payload,
+  collection: 'pages',
+  id: '42',
+  user: req.user, // attributed in the audit log; their permissions apply
+})
+
+if (!result.published) {
+  console.log(result.failedAt, result.reason, result.suggestion)
+}
+```
+
+All three run the same pipeline the admin and MCP paths use, so host code cannot drift from the plugin's policy. `getPublishStatus` runs every check except the write and mutates nothing.
+
+## Bypassing the pipeline
+
+`bypassPublishingServer: true` in the Payload request context is the only way to write `_status` without the pipeline. It is intended for seed scripts and migrations:
+
+```ts
+await payload.update({
+  collection: 'pages',
+  id,
+  data: { _status: 'published' },
+  context: { bypassPublishingServer: true },
+})
+```
+
+It skips composition, accessibility, required-field, embargo, and approval checks. Nothing in the admin path uses it.
+
+> **Note:** the hook guards `update` only. `payload.create({ data: { _status: 'published' } })` is not intercepted, so a create can publish without the pipeline. Save as a draft and publish in a second step if that matters to you.
+
+## Custom accessibility checks
+
+The built-in checks (alt text, heading hierarchy, link labels) are exported from `@forumone/throughline-publishing/checks`. Add your own via `accessibilityChecks`:
+
+```ts
+publishingPlugin({
+  inngest,
+  collections: [{ slug: 'pages' }],
+  accessibilityChecks: [
+    {
+      name: 'no-empty-tables',
+      run: (doc) => (hasEmptyTable(doc) ? [{ message: 'Table has no rows', severity: 'error' }] : []),
+    },
+  ],
+})
+```

package/dist/admin/PublishButton.d.ts

@@ -0,0 +1,24 @@
+import React from 'react';
+export interface ThroughlinePublishButtonProps {
+    /** Route prefix the plugin is mounted under. Injected via `clientProps`. */
+    routePrefix?: string;
+    /** Publish-timestamp field for this collection. Injected via `clientProps`. */
+    publishedAtField?: string;
+}
+/**
+ * Replaces Payload's Publish button on collections the publishing plugin
+ * governs.
+ *
+ * The native button submits `_status: 'published'` straight to the update
+ * endpoint, which the plugin's trust boundary rejects by design. This one
+ * saves pending edits as a draft, then asks the publishing server to run the
+ * pipeline — as the logged-in editor, over the session cookie, with no API
+ * key. A block renders the failing step, its issues and its suggestion
+ * instead of a generic error.
+ *
+ * On the create view this renders nothing: the pipeline's first step is
+ * `exist`, so there is nothing to evaluate until the draft is saved.
+ * Payload's own Save Draft button covers that step.
+ */
+export declare function PublishButton(props?: ThroughlinePublishButtonProps): React.ReactNode;
+//# sourceMappingURL=PublishButton.d.ts.map

package/dist/admin/PublishButton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PublishButton.d.ts","sourceRoot":"","sources":["../../src/admin/PublishButton.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAgC,MAAM,OAAO,CAAA;AAYpD,MAAM,WAAW,6BAA6B;IAC5C,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,KAAK,GAAE,6BAAkC,GAAG,KAAK,CAAC,SAAS,CA2HxF"}

package/dist/admin/PublishButton.js

@@ -0,0 +1,116 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useState } from 'react';
+import { FormSubmit, toast, useConfig, useDocumentInfo, useForm, useFormModified, useTranslation, } from '@payloadcms/ui';
+import { callPublishingEndpoint, describeBlock } from './publishing-client.js';
+/**
+ * Replaces Payload's Publish button on collections the publishing plugin
+ * governs.
+ *
+ * The native button submits `_status: 'published'` straight to the update
+ * endpoint, which the plugin's trust boundary rejects by design. This one
+ * saves pending edits as a draft, then asks the publishing server to run the
+ * pipeline — as the logged-in editor, over the session cookie, with no API
+ * key. A block renders the failing step, its issues and its suggestion
+ * instead of a generic error.
+ *
+ * On the create view this renders nothing: the pipeline's first step is
+ * `exist`, so there is nothing to evaluate until the draft is saved.
+ * Payload's own Save Draft button covers that step.
+ */
+export function PublishButton(props = {}) {
+    const routePrefix = props.routePrefix ?? '/publishing';
+    const { collectionSlug, data, hasPublishedDoc, hasPublishPermission, id, setHasPublishedDoc, setMostRecentVersionIsAutosaved, setUnpublishedVersionCount, unpublishedVersionCount, uploadStatus, } = useDocumentInfo();
+    const { config } = useConfig();
+    const { reset, submit } = useForm();
+    const modified = useFormModified();
+    const { t } = useTranslation();
+    const [publishing, setPublishing] = useState(false);
+    const { api } = config.routes;
+    const serverURL = config.serverURL ?? '';
+    const publish = useCallback(async () => {
+        if (id === undefined || id === null || !collectionSlug || publishing)
+            return;
+        setPublishing(true);
+        try {
+            // Persist pending edits first. Draft writes never touch `_status`, so
+            // the trust boundary lets them through; the pipeline then evaluates
+            // what was actually saved rather than what is on screen.
+            if (modified) {
+                const saved = await submit({
+                    action: `${serverURL}${api}/${collectionSlug}/${id}?draft=true&depth=0`,
+                    method: 'PATCH',
+                    overrides: { _status: 'draft' },
+                    skipValidation: true,
+                });
+                // `submit` returns void and toasts its own error on most failures,
+                // but falls through with a non-ok response when the body carries no
+                // message. Check both so a failed save never reaches the pipeline.
+                if (!saved || !saved.res.ok)
+                    return;
+            }
+            const result = await callPublishingEndpoint({
+                serverURL,
+                apiRoute: api,
+                routePrefix,
+                action: 'publish',
+                collection: collectionSlug,
+                id,
+            });
+            if (!result.ok) {
+                toast.error(result.message);
+                return;
+            }
+            if (!result.body.published) {
+                const { title, description } = describeBlock(result.body);
+                toast.error(title, {
+                    ...(description ? { description } : {}),
+                    duration: 10_000,
+                });
+                return;
+            }
+            await reset({
+                ...(data ?? {}),
+                _status: 'published',
+                ...(props.publishedAtField && result.body.publishedAt
+                    ? { [props.publishedAtField]: result.body.publishedAt }
+                    : {}),
+            });
+            setHasPublishedDoc(true);
+            setUnpublishedVersionCount(0);
+            setMostRecentVersionIsAutosaved(false);
+            toast.success(t('version:published'));
+        }
+        finally {
+            setPublishing(false);
+        }
+    }, [
+        api,
+        collectionSlug,
+        data,
+        id,
+        modified,
+        props.publishedAtField,
+        publishing,
+        reset,
+        routePrefix,
+        serverURL,
+        setHasPublishedDoc,
+        setMostRecentVersionIsAutosaved,
+        setUnpublishedVersionCount,
+        submit,
+        t,
+    ]);
+    if (!hasPublishPermission)
+        return null;
+    // Create view — no document for the pipeline to evaluate yet.
+    if (id === undefined || id === null || !collectionSlug)
+        return null;
+    const canPublish = (modified || unpublishedVersionCount > 0 || !hasPublishedDoc) &&
+        uploadStatus !== 'uploading' &&
+        !publishing;
+    return (_jsx(FormSubmit, { buttonId: "action-save", disabled: !canPublish, onClick: () => {
+            void publish();
+        }, size: "medium", type: "button", children: publishing ? t('version:publishing') : t('version:publishChanges') }));
+}
+//# sourceMappingURL=PublishButton.js.map

package/dist/admin/PublishButton.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PublishButton.js","sourceRoot":"","sources":["../../src/admin/PublishButton.tsx"],"names":[],"mappings":"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"}

package/dist/admin/UnpublishButton.d.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+export interface ThroughlineUnpublishButtonProps {
+    /** Route prefix the plugin is mounted under. Injected via `clientProps`. */
+    routePrefix?: string;
+}
+/**
+ * Replaces Payload's Unpublish control on collections the publishing plugin
+ * governs. Same reasoning as the Publish button: the native control writes
+ * `_status: 'draft'` directly, which the trust boundary rejects. This one
+ * routes through the publishing server so the unpublish is audited against
+ * the logged-in editor and `content/page.unpublished` fires for
+ * revalidation.
+ */
+export declare function UnpublishButton(props?: ThroughlineUnpublishButtonProps): React.ReactNode;
+//# sourceMappingURL=UnpublishButton.d.ts.map

package/dist/admin/UnpublishButton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UnpublishButton.d.ts","sourceRoot":"","sources":["../../src/admin/UnpublishButton.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAgC,MAAM,OAAO,CAAA;AAapD,MAAM,WAAW,+BAA+B;IAC9C,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,KAAK,GAAE,+BAAoC,GAC1C,KAAK,CAAC,SAAS,CAmGjB"}

package/dist/admin/UnpublishButton.js

@@ -0,0 +1,81 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { useCallback, useState } from 'react';
+import { ConfirmationModal, PopupList, toast, useConfig, useDocumentInfo, useForm, useModal, useTranslation, } from '@payloadcms/ui';
+import { callPublishingEndpoint } from './publishing-client.js';
+/**
+ * Replaces Payload's Unpublish control on collections the publishing plugin
+ * governs. Same reasoning as the Publish button: the native control writes
+ * `_status: 'draft'` directly, which the trust boundary rejects. This one
+ * routes through the publishing server so the unpublish is audited against
+ * the logged-in editor and `content/page.unpublished` fires for
+ * revalidation.
+ */
+export function UnpublishButton(props = {}) {
+    const routePrefix = props.routePrefix ?? '/publishing';
+    const { collectionSlug, data, hasPublishedDoc, hasPublishPermission, id, incrementVersionCount, isTrashed, setHasPublishedDoc, setMostRecentVersionIsAutosaved, setUnpublishedVersionCount, } = useDocumentInfo();
+    const { config } = useConfig();
+    const { reset } = useForm();
+    const { t } = useTranslation();
+    const { toggleModal } = useModal();
+    const [unpublishing, setUnpublishing] = useState(false);
+    const modalSlug = `throughline-confirm-unpublish-${id}`;
+    const { api } = config.routes;
+    const serverURL = config.serverURL ?? '';
+    const unpublish = useCallback(async () => {
+        if (id === undefined || id === null || !collectionSlug || unpublishing)
+            return;
+        setUnpublishing(true);
+        try {
+            const result = await callPublishingEndpoint({
+                serverURL,
+                apiRoute: api,
+                routePrefix,
+                action: 'unpublish',
+                collection: collectionSlug,
+                id,
+            });
+            if (!result.ok) {
+                toast.error(result.message);
+                return;
+            }
+            if (!result.body.unpublished) {
+                toast.error(result.body.reason ?? t('error:unPublishingDocument'));
+                return;
+            }
+            await reset({ ...(data ?? {}), _status: 'draft' });
+            incrementVersionCount();
+            setUnpublishedVersionCount(1);
+            setMostRecentVersionIsAutosaved(false);
+            setHasPublishedDoc(false);
+            toast.success(t('version:unpublishedSuccessfully'));
+        }
+        finally {
+            setUnpublishing(false);
+        }
+    }, [
+        api,
+        collectionSlug,
+        data,
+        id,
+        incrementVersionCount,
+        reset,
+        routePrefix,
+        serverURL,
+        setHasPublishedDoc,
+        setMostRecentVersionIsAutosaved,
+        setUnpublishedVersionCount,
+        t,
+        unpublishing,
+    ]);
+    if (!hasPublishPermission || !hasPublishedDoc || isTrashed)
+        return null;
+    if (id === undefined || id === null || !collectionSlug)
+        return null;
+    return (_jsxs(React.Fragment, { children: [_jsx(PopupList.Button, { id: "action-unpublish", onClick: () => {
+                    toggleModal(modalSlug);
+                }, children: t('version:unpublish') }), _jsx(ConfirmationModal, { body: t('version:aboutToUnpublish'), confirmingLabel: t('version:unpublishing'), heading: t('version:confirmUnpublish'), modalSlug: modalSlug, onConfirm: () => {
+                    void unpublish();
+                } })] }));
+}
+//# sourceMappingURL=UnpublishButton.js.map

package/dist/admin/UnpublishButton.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UnpublishButton.js","sourceRoot":"","sources":["../../src/admin/UnpublishButton.tsx"],"names":[],"mappings":"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"}

package/dist/admin/publishing-client.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Client-side helpers shared by the admin Publish and Unpublish controls.
+ * No JSX here so the message formatting can be unit tested directly.
+ */
+export interface PublishingIssue {
+    field?: string;
+    message: string;
+    severity?: 'error' | 'warning';
+    rule?: string;
+}
+export interface PublishingResponse {
+    published?: boolean;
+    unpublished?: boolean;
+    publishedAt?: string;
+    failedAt?: string;
+    reason?: string;
+    code?: string;
+    issues?: PublishingIssue[];
+    suggestion?: string;
+    error?: string;
+}
+export interface CallPublishingEndpointArgs {
+    serverURL: string;
+    apiRoute: string;
+    routePrefix: string;
+    action: 'publish' | 'unpublish';
+    collection: string;
+    id: number | string;
+}
+export type PublishingCallResult = {
+    ok: true;
+    body: PublishingResponse;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * POSTs to the plugin's admin endpoint using the browser's session cookie.
+ * Returns a transport-level failure as `ok: false`; a pipeline block comes
+ * back as `ok: true` with a `published: false` body.
+ */
+export declare function callPublishingEndpoint(args: CallPublishingEndpointArgs): Promise<PublishingCallResult>;
+/**
+ * Turns a pipeline block into something an editor can act on: which step
+ * said no, what it objected to, and what to do about it. This is the
+ * information the pipeline already returns — it just never had a way to
+ * reach the screen.
+ */
+export declare function describeBlock(body: PublishingResponse): {
+    title: string;
+    description: string;
+};
+//# sourceMappingURL=publishing-client.d.ts.map

package/dist/admin/publishing-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publishing-client.d.ts","sourceRoot":"","sources":["../../src/admin/publishing-client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,eAAe,EAAE,CAAA;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,SAAS,GAAG,WAAW,CAAA;IAC/B,UAAU,EAAE,MAAM,CAAA;IAClB,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;CACpB;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,kBAAkB,CAAA;CAAE,GACtC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAElC;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,0BAA0B,GAC/B,OAAO,CAAC,oBAAoB,CAAC,CA8B/B;AAID;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,kBAAkB,GAAG;IACvD,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;CACpB,CAqBA"}

package/dist/admin/publishing-client.js

@@ -0,0 +1,64 @@
+/**
+ * Client-side helpers shared by the admin Publish and Unpublish controls.
+ * No JSX here so the message formatting can be unit tested directly.
+ */
+/**
+ * POSTs to the plugin's admin endpoint using the browser's session cookie.
+ * Returns a transport-level failure as `ok: false`; a pipeline block comes
+ * back as `ok: true` with a `published: false` body.
+ */
+export async function callPublishingEndpoint(args) {
+    const url = `${args.serverURL}${args.apiRoute}${args.routePrefix}/${args.action}`;
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'POST',
+            credentials: 'include',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ collection: args.collection, id: args.id }),
+        });
+    }
+    catch {
+        return { ok: false, message: 'Could not reach the publishing server.' };
+    }
+    let body;
+    try {
+        body = (await response.json());
+    }
+    catch {
+        return { ok: false, message: `Publishing server returned ${response.status}.` };
+    }
+    if (!response.ok) {
+        return {
+            ok: false,
+            message: body.error ?? `Publishing server returned ${response.status}.`,
+        };
+    }
+    return { ok: true, body };
+}
+const MAX_LISTED_ISSUES = 5;
+/**
+ * Turns a pipeline block into something an editor can act on: which step
+ * said no, what it objected to, and what to do about it. This is the
+ * information the pipeline already returns — it just never had a way to
+ * reach the screen.
+ */
+export function describeBlock(body) {
+    const title = body.reason ?? `Publish blocked at the ${body.failedAt ?? 'policy'} check.`;
+    const lines = [];
+    if (body.failedAt && body.reason) {
+        lines.push(`Blocked at: ${body.failedAt}`);
+    }
+    const issues = body.issues ?? [];
+    for (const issue of issues.slice(0, MAX_LISTED_ISSUES)) {
+        lines.push(`• ${issue.field ? `${issue.field}: ` : ''}${issue.message}`);
+    }
+    if (issues.length > MAX_LISTED_ISSUES) {
+        lines.push(`• …and ${issues.length - MAX_LISTED_ISSUES} more`);
+    }
+    if (body.suggestion) {
+        lines.push(`Suggestion: ${body.suggestion}`);
+    }
+    return { title, description: lines.join('\n') };
+}
+//# sourceMappingURL=publishing-client.js.map

package/dist/admin/publishing-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publishing-client.js","sourceRoot":"","sources":["../../src/admin/publishing-client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAkCH;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,IAAgC;IAEhC,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,MAAM,EAAE,CAAA;IAEjF,IAAI,QAAkB,CAAA;IACtB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAC1B,MAAM,EAAE,MAAM;YACd,WAAW,EAAE,SAAS;YACtB,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC;SACnE,CAAC,CAAA;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,wCAAwC,EAAE,CAAA;IACzE,CAAC;IAED,IAAI,IAAwB,CAAA;IAC5B,IAAI,CAAC;QACH,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAuB,CAAA;IACtD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,8BAA8B,QAAQ,CAAC,MAAM,GAAG,EAAE,CAAA;IACjF,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EAAE,IAAI,CAAC,KAAK,IAAI,8BAA8B,QAAQ,CAAC,MAAM,GAAG;SACxE,CAAA;IACH,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;AAC3B,CAAC;AAED,MAAM,iBAAiB,GAAG,CAAC,CAAA;AAE3B;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,IAAwB;IAIpD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,IAAI,0BAA0B,IAAI,CAAC,QAAQ,IAAI,QAAQ,SAAS,CAAA;IAEzF,MAAM,KAAK,GAAa,EAAE,CAAA;IAC1B,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QACjC,KAAK,CAAC,IAAI,CAAC,eAAe,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAA;IAC5C,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,EAAE,CAAA;IAChC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,EAAE,CAAC;QACvD,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC,CAAA;IAC1E,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,GAAG,iBAAiB,EAAE,CAAC;QACtC,KAAK,CAAC,IAAI,CAAC,UAAU,MAAM,CAAC,MAAM,GAAG,iBAAiB,OAAO,CAAC,CAAA;IAChE,CAAC;IAED,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,KAAK,CAAC,IAAI,CAAC,eAAe,IAAI,CAAC,UAAU,EAAE,CAAC,CAAA;IAC9C,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAA;AACjD,CAAC"}

package/dist/endpoints/admin.d.ts

@@ -0,0 +1,19 @@
+import { type Endpoint } from 'payload';
+export interface CreateAdminEndpointsDeps {
+    /** Route prefix the plugin is mounted under, e.g. `/publishing`. */
+    routePrefix: string;
+    /** Collections registered as publishable; anything else is rejected. */
+    publishableSlugs: Set<string>;
+}
+/**
+ * The admin's path into the pipeline.
+ *
+ * These endpoints authenticate off the Payload session cookie, so `req.user`
+ * is the logged-in editor — no API key in the editorial publish path, and
+ * the audit event records the person rather than a service principal. The
+ * write still goes through the pipeline, and still runs with
+ * `overrideAccess: false`, so neither the policy checks nor the collection's
+ * access control are skipped.
+ */
+export declare function createAdminEndpoints(deps: CreateAdminEndpointsDeps): Endpoint[];
+//# sourceMappingURL=admin.d.ts.map

package/dist/endpoints/admin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.d.ts","sourceRoot":"","sources":["../../src/endpoints/admin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,QAAQ,EAAuB,MAAM,SAAS,CAAA;AAStE,MAAM,WAAW,wBAAwB;IACvC,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAA;IACnB,wEAAwE;IACxE,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAC9B;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,wBAAwB,GAAG,QAAQ,EAAE,CAa/E"}