@forumone/throughline-integrations 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,91 @@
 # @forumone/throughline-integrations
 
+## 0.8.0
+
+### Minor Changes
+
+- 3ca0453: Sync now: a button on the integrations document, and the endpoint behind it
+
+  Manual sync was complete except for any way to reach it. The
+  `integration/manual-sync` event existed, every integration handled it, the run
+  wrote `lastSyncAt` / `lastSyncStatus` / `lastError` and an audit row — and the
+  only ways in were a `trigger_sync` MCP call, which needs a minted API key and a
+  JSON-RPC round trip, or hand-sending the event in the Inngest dashboard. Neither
+  is available to the operator who has just rotated a token or fixed a record
+  upstream and is looking at the instance in the admin, where the next scheduled
+  run may be an hour away.
+  - **`requestManualSync()`** is now the one definition of what a trigger means:
+    the instance exists, the instance is enabled, this event shape. The MCP tool
+    calls it, and so does the new endpoint, so the two cannot drift.
+  - **`POST /api/<integrations>/:id/sync`** — session-cookie auth, admin only,
+    `202` when queued, `404` / `409` / `502` for an unknown id, a disabled
+    instance, and an Inngest that would not take the event.
+  - **A Sync now button** in the document sidebar, above `lastSyncAt`. It says the
+    run was queued rather than implying a result it does not have, then watches
+    `lastSyncAt` for two minutes and reports the outcome when it moves.
+
+  An unreachable Inngest used to escape `trigger_sync` as an unhandled rejection
+  and reach the caller as a generic tool failure. It is now a refusal that says
+  nothing was queued — the distinction a button depends on, since a sync that was
+  never requested otherwise looks exactly like one that has not finished.
+
+  This is the package's first admin component, so hosts must run
+  `payload generate:importmap` after upgrading; a stale import map 500s the admin
+  screen. `react` and `@payloadcms/ui` are optional peers, needed only by
+  `@forumone/throughline-integrations/client`.
+
+## 0.7.0
+
+### Minor Changes
+
+- a9262da: Per-tool gating works, because tool names no longer wait for `onInit`
+
+  `@payloadcms/plugin-mcp` generates one per-key checkbox per tool while the host's
+  config is being built, and then gates every call on the checkbox matching the
+  tool's name. Every Throughline tool was built at `onInit` — each closes over
+  `payload`, the publishing service or the manifest loader — so the array it maps
+  over was empty, no checkboxes were generated, and its `?? false` denied all 27
+  tools to every key. A valid key got a 200 and an empty `tools/list`, with nothing
+  wrong on either side.
+
+  The plugin needs only `name` and `description` then, and neither needs a Payload.
+  So a server now **declares** its tools as the config is built and **binds** their
+  handlers at `onInit`:
+
+  ```ts
+  options.mcpTools?.declare(PUBLISHING_TOOL_DESCRIPTORS, { serverName: 'publishing' })
+  // …later, at onInit:
+  options.mcpTools?.add(tools, { serverName: 'publishing' })
+  ```
+
+  Each package gained a `tools/descriptors.ts` holding every tool's name and
+  description; the factories spread from it, so the checkbox and the MCP client
+  cannot describe a tool differently. A `descriptors.test.ts` in each package
+  asserts the two sets match, without needing a database.
+
+  `createMcpToolCollector` gains `declare()` and an `unbound` list. Both mismatches
+  are refused rather than absorbed: a tool built but never declared throws at
+  `onInit` (it would otherwise be denied to every key, silently), and a tool
+  declared but never bound stays advertised with a handler that explains itself.
+
+  **Order in the host's plugin array is now load-bearing.** Every tool-bearing
+  server must come before `mcpPlugin`, or it declares into an array that has
+  already been read. It was only a convention before; it is a requirement now, and
+  the failure mode — a server's tools missing from every key — is the one this
+  change exists to remove.
+
+  `requiredScope` stays declared and read by nothing. Enforcement is the checkbox;
+  these record which tools are consequential, and are the mapping a scope-aware
+  default would be built from.
+
+  The playground registers `mcpPlugin` for the first time, so the suite's only
+  end-to-end host now exercises the tools rather than just their composition.
+
+### Patch Changes
+
+- Updated dependencies [a9262da]
+  - @forumone/throughline-core@0.8.0
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -7,6 +7,7 @@ Plugin architecture for connecting Throughline-powered Payload sites to external
 - **`Integration` contract** — id, name, description, configFields, validateConfig, subscribes, createFunctions, mcpTools (optional), healthcheck. Every Salesforce / Mailchimp / Slack / etc. integration uses this exact shape.
 - **`IntegrationRegistry`** — process-local, per-plugin-init store keyed by integration id. Rejects duplicates synchronously.
 - **Integrations collection** — `name`, `integrationType`, `enabled`, `config` (json), and read-only `lastSyncAt` / `lastSyncStatus` / `lastError`. Admin-only writes; admin/editor reads.
+- **A Sync now button**, in the document's sidebar beside those status fields, and the `POST /api/<slug>/:id/sync` endpoint behind it. See below.
 - **Five MCP tools**, handed to the host's collector at `onInit` and served by `@payloadcms/plugin-mcp` on one `/api/mcp`. Pass `mcpTools` or they reach nobody:
 
 | Tool | Use it for | Access |
@@ -19,6 +20,32 @@ Plugin architecture for connecting Throughline-powered Payload sites to external
 
 - **Webhook integration** — generic outbound HTTPS POST with HMAC-SHA256 signing, configurable event filter, retries (5x), timeout, and a HEAD-based healthcheck. RFC 4231 known-answer test vectors pin the wire format so refactoring can never silently break receivers.
 
+## Triggering a sync from the admin
+
+Everything behind a manual sync — the `integration/manual-sync` event, a handler on every integration, the status fields, the audit rows — was reachable only over MCP or by hand-sending an event in the Inngest dashboard. Neither is available to the person who has just fixed a record in the upstream system and wants it on the site before the next cron.
+
+So the collection ships one admin component: **Sync now**, in the sidebar, above `lastSyncAt`. It POSTs to a collection endpoint:
+
+```
+POST /api/integrations/:id/sync      { "reason": "optional" }
+```
+
+authenticated by the Payload session cookie — no API key in the operator's path — and admin-only, matching `trigger_sync`. The endpoint and the tool both call `requestManualSync()`, which is the single definition of what a trigger checks and what event it sends; neither re-implements the rules.
+
+| Answer | Means |
+|---|---|
+| `202` | Queued. The run has **not** happened yet. |
+| `403` | Not an admin. |
+| `404` | No instance with that id. |
+| `409` | The instance is disabled. Enable it first. |
+| `502` | Inngest would not take the event — nothing was queued. |
+
+`202`, not `200`: it fires an event and returns. The button says the run was queued, then watches `lastSyncAt` for two minutes and reports the outcome when it moves — against the value the endpoint returned rather than what the page last rendered, so a cron run that lands mid-wait is not mistaken for this one. Giving up watching is not failing, and the copy says so.
+
+`requestManualSync` and `createSyncEndpoint` are exported, so a host with its own screen can reuse either.
+
+Because this is the package's first admin component, hosts must run `payload generate:importmap` after upgrading. A stale import map 500s the admin screen.
+
 ## Why this is separate from the other server packages
 
 The other server packages do one job well. This is a **framework within the framework**: a contract for integration modules plus tooling to register, configure, observe, and trigger them. Every real client engagement needs integrations; building them ad-hoc produces unmaintainable tangle. This package keeps the surface area bounded as the integration count grows.
@@ -29,7 +56,7 @@ The other server packages do one job well. This is a **framework within the fram
 pnpm add @forumone/throughline-integrations
 ```
 
-Peers: `payload@^3.0.0`, `inngest@^4.0.0`. Required runtime peer: `@forumone/throughline-core` (audit log).
+Peers: `payload@^3.0.0`, `inngest@^4.0.0`. Required runtime peer: `@forumone/throughline-core` (audit log). `react` and `@payloadcms/ui` are optional peers, needed only to render the Sync now button — a host that never loads `@forumone/throughline-integrations/client` needs neither.
 
 ## Usage
 
@@ -71,7 +98,7 @@ Integration `createFunctions` returns Inngest functions, but **this plugin does
 
 A prompt-injection attacker could otherwise convince Claude to retarget a webhook to attacker-controlled infrastructure or rotate the signing secret. Claude can _trigger_ and _observe_ integrations conversationally, but configuration changes are deliberate human actions in the Payload admin.
 
-This asymmetry is intentional and is why `trigger_sync` is admin-only too — manual triggering writes to an external system, even if it doesn't change configuration.
+This asymmetry is intentional and is why `trigger_sync` is admin-only too — manual triggering writes to an external system, even if it doesn't change configuration. The Sync now button and its endpoint apply the same rule, and the button does not render for a non-admin.
 
 ## Webhook details
 

package/dist/admin/SyncButton.d.ts

@@ -0,0 +1,27 @@
+import React from 'react';
+export interface ThroughlineSyncButtonProps {
+    /** Slug the integrations collection is mounted at. Injected via `clientProps`. */
+    collectionSlug?: string;
+}
+/**
+ * "Sync now", in the sidebar beside the status fields it moves.
+ *
+ * Everything behind this button already existed — the `integration/manual-sync`
+ * event, a handler on every integration, the status fields, the audit rows —
+ * and reaching it meant an MCP round trip with a minted API key or a hand-sent
+ * event in the Inngest dashboard. Neither is available to the person who has
+ * just fixed a job posting and wants to see it on the site before the next
+ * hourly cron.
+ *
+ * It fires an event; it does not wait for the sync. So the button says the run
+ * was *queued*, then watches `lastSyncAt` for the two minutes a sync normally
+ * takes and reports the outcome when it moves. Stopping watching is not the
+ * same as failing, and the copy says so — the run continues either way.
+ *
+ * The form is deliberately untouched. Writing the new status into form state
+ * would put server values into a document the editor may not have saved, so
+ * the result is rendered here instead and the sidebar fields catch up on the
+ * next load.
+ */
+export declare function SyncButton(props?: ThroughlineSyncButtonProps): React.ReactNode;
+//# sourceMappingURL=SyncButton.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SyncButton.d.ts","sourceRoot":"","sources":["../../src/admin/SyncButton.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAmD,MAAM,OAAO,CAAA;AAWvE,MAAM,WAAW,0BAA0B;IACzC,kFAAkF;IAClF,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAQD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,UAAU,CAAC,KAAK,GAAE,0BAA+B,GAAG,KAAK,CAAC,SAAS,CAyHlF"}

package/dist/admin/SyncButton.js

@@ -0,0 +1,134 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { Button, FieldLabel, toast, useAuth, useConfig, useDocumentInfo } from '@payloadcms/ui';
+import { describeSyncOutcome, fetchSyncStatus, formatSyncTime, syncHasFinished, triggerSync, } from './sync-client.js';
+/** How long to watch for the run to finish before saying so and stopping. */
+const POLL_INTERVAL_MS = 3_000;
+const POLL_TIMEOUT_MS = 120_000;
+/**
+ * "Sync now", in the sidebar beside the status fields it moves.
+ *
+ * Everything behind this button already existed — the `integration/manual-sync`
+ * event, a handler on every integration, the status fields, the audit rows —
+ * and reaching it meant an MCP round trip with a minted API key or a hand-sent
+ * event in the Inngest dashboard. Neither is available to the person who has
+ * just fixed a job posting and wants to see it on the site before the next
+ * hourly cron.
+ *
+ * It fires an event; it does not wait for the sync. So the button says the run
+ * was *queued*, then watches `lastSyncAt` for the two minutes a sync normally
+ * takes and reports the outcome when it moves. Stopping watching is not the
+ * same as failing, and the copy says so — the run continues either way.
+ *
+ * The form is deliberately untouched. Writing the new status into form state
+ * would put server values into a document the editor may not have saved, so
+ * the result is rendered here instead and the sidebar fields catch up on the
+ * next load.
+ */
+export function SyncButton(props = {}) {
+    const collectionSlug = props.collectionSlug ?? 'integrations';
+    const { id, data } = useDocumentInfo();
+    const { config } = useConfig();
+    const { user } = useAuth();
+    const [phase, setPhase] = useState('idle');
+    const [baseline, setBaseline] = useState(null);
+    const [outcome, setOutcome] = useState(null);
+    const [gaveUpWaiting, setGaveUpWaiting] = useState(false);
+    const { api } = config.routes;
+    const serverURL = config.serverURL ?? '';
+    const instanceName = typeof data?.['name'] === 'string' ? data['name'] : undefined;
+    const enabled = data?.['enabled'] === true;
+    const roles = user?.['roles'];
+    const isAdmin = Array.isArray(roles) && roles.includes('admin');
+    // Read inside the poll effect, which must not restart every time the name
+    // changes — a restarted effect is a restarted timeout.
+    const instanceNameRef = useRef(instanceName);
+    instanceNameRef.current = instanceName;
+    const start = useCallback(async () => {
+        if (id === undefined || id === null || phase !== 'idle')
+            return;
+        setPhase('triggering');
+        setOutcome(null);
+        setGaveUpWaiting(false);
+        const result = await triggerSync({ serverURL, apiRoute: api, collectionSlug, id });
+        if (!result.ok) {
+            toast.error(result.message);
+            setPhase('idle');
+            return;
+        }
+        toast.success(result.body.message ?? 'Sync queued.');
+        setBaseline(result.body.lastSyncAt ?? null);
+        setPhase('waiting');
+    }, [api, collectionSlug, id, phase, serverURL]);
+    useEffect(() => {
+        if (phase !== 'waiting' || id === undefined || id === null)
+            return;
+        const controller = new AbortController();
+        let timer;
+        const deadline = Date.now() + POLL_TIMEOUT_MS;
+        const poll = async () => {
+            const status = await fetchSyncStatus({
+                serverURL,
+                apiRoute: api,
+                collectionSlug,
+                id,
+                signal: controller.signal,
+            });
+            if (controller.signal.aborted)
+                return;
+            if (status && syncHasFinished(baseline, status)) {
+                setOutcome(status);
+                setPhase('idle');
+                const described = describeSyncOutcome(status, instanceNameRef.current);
+                const options = described.description ? { description: described.description } : {};
+                if (described.severity === 'success')
+                    toast.success(described.title, options);
+                else if (described.severity === 'warning')
+                    toast.warning(described.title, options);
+                else
+                    toast.error(described.title, { ...options, duration: 10_000 });
+                return;
+            }
+            if (Date.now() >= deadline) {
+                setGaveUpWaiting(true);
+                setPhase('idle');
+                return;
+            }
+            timer = setTimeout(() => void poll(), POLL_INTERVAL_MS);
+        };
+        timer = setTimeout(() => void poll(), POLL_INTERVAL_MS);
+        return () => {
+            controller.abort();
+            if (timer)
+                clearTimeout(timer);
+        };
+    }, [api, baseline, collectionSlug, id, phase, serverURL]);
+    // Create view: no instance to sync, and no id to sync it by.
+    if (id === undefined || id === null)
+        return null;
+    // The endpoint refuses a non-admin anyway; not rendering the control is how
+    // an editor finds that out without pressing it.
+    if (!isAdmin)
+        return null;
+    const label = phase === 'idle' ? 'Sync now' : phase === 'triggering' ? 'Queueing…' : 'Syncing…';
+    return (_jsxs("div", { className: "field-type throughline-integration-sync", children: [_jsx(FieldLabel, { as: "span", label: "Manual sync" }), _jsx(Button, { buttonStyle: "secondary", disabled: !enabled || phase !== 'idle', onClick: () => {
+                    void start();
+                }, size: "small", type: "button", ...(enabled ? {} : { tooltip: 'Enable this integration first.' }), children: label }), _jsx("p", { "aria-live": "polite", className: "field-description", children: state({ enabled, gaveUpWaiting, outcome, phase }) })] }));
+}
+/** The line under the button. Pure, so the copy can be read in one place. */
+function state(args) {
+    if (!args.enabled)
+        return 'Disabled integrations cannot be synced. Enable and save first.';
+    if (args.phase === 'triggering')
+        return 'Asking the queue to run this integration…';
+    if (args.phase === 'waiting')
+        return 'Queued. Watching for the run to finish.';
+    if (args.gaveUpWaiting) {
+        return 'Still running after two minutes. It has not failed — reload to see the result.';
+    }
+    if (args.outcome)
+        return `Finished at ${formatSyncTime(args.outcome.lastSyncAt)}.`;
+    return 'Runs this integration now, instead of waiting for its schedule.';
+}
+//# sourceMappingURL=SyncButton.js.map

package/dist/admin/SyncButton.js.map

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

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

@@ -0,0 +1,83 @@
+/**
+ * Client-side helpers behind the admin's Sync now button. No JSX here, so the
+ * request handling and the message formatting can be unit tested without a
+ * form, a document or a browser.
+ */
+export type SyncStatusValue = 'never-run' | 'success' | 'partial' | 'failed';
+export interface TriggerSyncBody {
+    ok?: boolean;
+    triggered?: {
+        instanceId: string;
+        instanceName: string;
+        type: string;
+    };
+    /** The instance's `lastSyncAt` *before* the run. The baseline to poll against. */
+    lastSyncAt?: string | null;
+    message?: string;
+    error?: string;
+    code?: string;
+}
+export interface TriggerSyncArgs {
+    serverURL: string;
+    apiRoute: string;
+    collectionSlug: string;
+    id: number | string;
+    reason?: string;
+}
+export type TriggerSyncResult = {
+    ok: true;
+    body: TriggerSyncBody;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * POSTs to the collection's sync endpoint using the browser's session cookie.
+ *
+ * Every refusal — not found, disabled, Inngest unreachable — comes back as a
+ * non-2xx with a message, so all of them land in `ok: false` and get shown.
+ * A button that appears to work when nothing was queued is the failure this
+ * exists to avoid.
+ */
+export declare function triggerSync(args: TriggerSyncArgs): Promise<TriggerSyncResult>;
+export interface SyncStatus {
+    lastSyncAt: string | null;
+    lastSyncStatus: SyncStatusValue | null;
+    lastError: string | null;
+}
+export interface FetchSyncStatusArgs {
+    serverURL: string;
+    apiRoute: string;
+    collectionSlug: string;
+    id: number | string;
+    signal?: AbortSignal;
+}
+/**
+ * Reads the three status fields off the instance. Returns null on any failure,
+ * because this is called on a timer and a single missed poll is not something
+ * to tell anyone about — the caller keeps waiting.
+ */
+export declare function fetchSyncStatus(args: FetchSyncStatusArgs): Promise<null | SyncStatus>;
+/**
+ * True once the instance has recorded a run that started after the trigger.
+ *
+ * Compared against the `lastSyncAt` the endpoint returned rather than against
+ * whatever the page last rendered: the sidebar can be minutes stale, and a
+ * document opened during a cron run would otherwise report that run's result
+ * as this one's.
+ */
+export declare function syncHasFinished(baseline: null | string, current: null | SyncStatus): boolean;
+export interface SyncOutcome {
+    severity: 'error' | 'success' | 'warning';
+    title: string;
+    description?: string;
+}
+/**
+ * How a finished run reads. `partial` is deliberately a warning rather than a
+ * success: some of what was asked for did not happen, and the whole reason
+ * somebody pressed this button is to find out whether their change landed.
+ */
+export declare function describeSyncOutcome(status: SyncStatus, instanceName?: string): SyncOutcome;
+/** `2026-08-29T14:03:00.000Z` as something an operator reads at a glance. */
+export declare function formatSyncTime(value: null | string): string;
+//# sourceMappingURL=sync-client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sync-client.d.ts","sourceRoot":"","sources":["../../src/admin/sync-client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAA;AAE5E,MAAM,WAAW,eAAe;IAC9B,EAAE,CAAC,EAAE,OAAO,CAAA;IACZ,SAAS,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IACtE,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,cAAc,EAAE,MAAM,CAAA;IACtB,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;IACnB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,MAAM,iBAAiB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAEpG;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA2BnF;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,cAAc,EAAE,eAAe,GAAG,IAAI,CAAA;IACtC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,cAAc,EAAE,MAAM,CAAA;IACtB,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;IACnB,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,GAAG,UAAU,CAAC,CAkB3F;AAMD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,IAAI,GAAG,MAAM,EAAE,OAAO,EAAE,IAAI,GAAG,UAAU,GAAG,OAAO,CAI5F;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAAA;IACzC,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,WAAW,CAwB1F;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAK3D"}

package/dist/admin/sync-client.js

@@ -0,0 +1,121 @@
+/**
+ * Client-side helpers behind the admin's Sync now button. No JSX here, so the
+ * request handling and the message formatting can be unit tested without a
+ * form, a document or a browser.
+ */
+/**
+ * POSTs to the collection's sync endpoint using the browser's session cookie.
+ *
+ * Every refusal — not found, disabled, Inngest unreachable — comes back as a
+ * non-2xx with a message, so all of them land in `ok: false` and get shown.
+ * A button that appears to work when nothing was queued is the failure this
+ * exists to avoid.
+ */
+export async function triggerSync(args) {
+    const url = `${args.serverURL}${args.apiRoute}/${args.collectionSlug}/${args.id}/sync`;
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'POST',
+            credentials: 'include',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(args.reason ? { reason: args.reason } : {}),
+        });
+    }
+    catch {
+        return { ok: false, message: 'Could not reach the server to queue the sync.' };
+    }
+    let body;
+    try {
+        body = (await response.json());
+    }
+    catch {
+        return { ok: false, message: `The server returned ${response.status}.` };
+    }
+    if (!response.ok) {
+        return { ok: false, message: body.error ?? `The server returned ${response.status}.` };
+    }
+    return { ok: true, body };
+}
+/**
+ * Reads the three status fields off the instance. Returns null on any failure,
+ * because this is called on a timer and a single missed poll is not something
+ * to tell anyone about — the caller keeps waiting.
+ */
+export async function fetchSyncStatus(args) {
+    const url = `${args.serverURL}${args.apiRoute}/${args.collectionSlug}/${args.id}?depth=0`;
+    try {
+        const response = await fetch(url, {
+            credentials: 'include',
+            ...(args.signal ? { signal: args.signal } : {}),
+        });
+        if (!response.ok)
+            return null;
+        const doc = (await response.json());
+        return {
+            lastSyncAt: typeof doc['lastSyncAt'] === 'string' ? doc['lastSyncAt'] : null,
+            lastSyncStatus: isSyncStatusValue(doc['lastSyncStatus']) ? doc['lastSyncStatus'] : null,
+            lastError: typeof doc['lastError'] === 'string' ? doc['lastError'] : null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function isSyncStatusValue(value) {
+    return value === 'never-run' || value === 'success' || value === 'partial' || value === 'failed';
+}
+/**
+ * True once the instance has recorded a run that started after the trigger.
+ *
+ * Compared against the `lastSyncAt` the endpoint returned rather than against
+ * whatever the page last rendered: the sidebar can be minutes stale, and a
+ * document opened during a cron run would otherwise report that run's result
+ * as this one's.
+ */
+export function syncHasFinished(baseline, current) {
+    if (!current)
+        return false;
+    if (current.lastSyncAt === null)
+        return false;
+    return current.lastSyncAt !== baseline;
+}
+/**
+ * How a finished run reads. `partial` is deliberately a warning rather than a
+ * success: some of what was asked for did not happen, and the whole reason
+ * somebody pressed this button is to find out whether their change landed.
+ */
+export function describeSyncOutcome(status, instanceName) {
+    const subject = instanceName ? `"${instanceName}"` : 'The integration';
+    const description = status.lastError ?? undefined;
+    switch (status.lastSyncStatus) {
+        case 'success':
+            return { severity: 'success', title: `${subject} synced.` };
+        case 'partial':
+            return {
+                severity: 'warning',
+                title: `${subject} synced, with problems.`,
+                ...(description ? { description } : {}),
+            };
+        case 'failed':
+            return {
+                severity: 'error',
+                title: `${subject} failed to sync.`,
+                ...(description ? { description } : {}),
+            };
+        default:
+            // A run finished — `lastSyncAt` moved — without leaving a status. Nothing
+            // to celebrate and nothing to blame; say what is known.
+            return { severity: 'warning', title: `${subject} ran, but reported no status.` };
+    }
+}
+/** `2026-08-29T14:03:00.000Z` as something an operator reads at a glance. */
+export function formatSyncTime(value) {
+    if (!value)
+        return 'Never';
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime()))
+        return 'Unknown';
+    return date.toLocaleString();
+}
+//# sourceMappingURL=sync-client.js.map

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

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

package/dist/collection.d.ts

@@ -1,8 +1,10 @@
-import type { CollectionConfig } from 'payload';
+import type { CollectionConfig, Endpoint } from 'payload';
 import type { IntegrationRegistry } from './registry.js';
 export interface CreateIntegrationsCollectionOptions {
     slug?: string;
     registry: IntegrationRegistry;
+    /** Collection endpoints to mount, e.g. the manual-sync trigger. */
+    endpoints?: Endpoint[];
 }
 /**
  * Collection that persists per-instance integration configuration. Configuration
@@ -11,6 +13,9 @@ export interface CreateIntegrationsCollectionOptions {
  *
  * Editors can read instance status (used by the listing/status MCP tools);
  * write operations are reserved for admins editing in the Payload UI.
+ *
+ * The one control on the document that is not a field is the sidebar's Sync
+ * now button, which POSTs to the `:id/sync` endpoint passed in `endpoints`.
  */
 export declare function createIntegrationsCollection(options: CreateIntegrationsCollectionOptions): CollectionConfig;
 //# sourceMappingURL=collection.d.ts.map

package/dist/collection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,gBAAgB,EAAE,MAAM,SAAS,CAAA;AACvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AAGxD,MAAM,WAAW,mCAAmC;IAClD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,mBAAmB,CAAA;CAC9B;AAYD;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,mCAAmC,GAC3C,gBAAgB,CA4GlB"}
+{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,gBAAgB,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AACjE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AASxD,MAAM,WAAW,mCAAmC;IAClD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,mBAAmB,CAAA;IAC7B,mEAAmE;IACnE,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAA;CACvB;AAYD;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,mCAAmC,GAC3C,gBAAgB,CAqIlB"}

package/dist/collection.js

@@ -1,4 +1,9 @@
 import { DEFAULT_INTEGRATIONS_SLUG } from './options.js';
+/**
+ * Where Payload resolves the admin controls from. A package specifier, not a
+ * path, so the host's import map picks it up without any host-side file.
+ */
+const CLIENT_ENTRY = '@forumone/throughline-integrations/client';
 const adminOrEditor = ({ req }) => {
     const roles = req.user?.['roles'] ?? [];
     return roles.includes('admin') || roles.includes('editor');
@@ -14,6 +19,9 @@ const adminOnly = ({ req }) => {
  *
  * Editors can read instance status (used by the listing/status MCP tools);
  * write operations are reserved for admins editing in the Payload UI.
+ *
+ * The one control on the document that is not a field is the sidebar's Sync
+ * now button, which POSTs to the `:id/sync` endpoint passed in `endpoints`.
  */
 export function createIntegrationsCollection(options) {
     const slug = options.slug ?? DEFAULT_INTEGRATIONS_SLUG;
@@ -62,6 +70,30 @@ export function createIntegrationsCollection(options) {
                     description: 'Integration-specific configuration. The integration\'s configFields drive the admin UI; this JSON store carries the validated payload.',
                 },
             },
+            {
+                /*
+                The only admin component this plugin ships. In the sidebar rather than
+                `beforeDocumentControls` because it belongs with the three fields it
+                moves — an operator watching for a sync to land is already reading
+                `lastSyncAt` — and because `beforeDocumentControls` also renders on the
+                create view, where there is no instance to sync.
+        
+                A `ui` field: no column, no value, nothing to save.
+                */
+                name: 'triggerSync',
+                type: 'ui',
+                label: 'Manual sync',
+                admin: {
+                    position: 'sidebar',
+                    components: {
+                        Field: {
+                            path: CLIENT_ENTRY,
+                            exportName: 'SyncButton',
+                            clientProps: { collectionSlug: slug },
+                        },
+                    },
+                },
+            },
             {
                 name: 'lastSyncAt',
                 type: 'date',
@@ -85,6 +117,7 @@ export function createIntegrationsCollection(options) {
                 admin: { readOnly: true },
             },
         ],
+        endpoints: options.endpoints ?? [],
         indexes: [
             { fields: ['integrationType', 'enabled'] },
             { fields: ['lastSyncStatus'] },

package/dist/collection.js.map

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