@forumone/throughline-plugin-contract 0.4.1 → 0.5.0

package/README.md

@@ -6,11 +6,29 @@ Shared type contracts every Throughline core plugin satisfies, plus the cross-pl
 
 - `CorePlugin<Options>` — the Payload plugin signature every core package exports
 - `BaseCorePluginOptions` — options every plugin accepts (`enabled`, `logger`, and `routePrefix` for a plugin that serves HTTP endpoints of its own)
+- `CollectionPluginOptions`, `PluginAdminOptions`, `DEFAULT_ADMIN_GROUP`, `resolveAdminGroup` — the `admin: { group }` option every plugin that declares a collection accepts, its `'Throughline'` default, and the helper that turns it into a collection's `admin.group` (see below)
 - `McpToolDefinition`, `McpToolContext`, `McpMeta` — the MCP tool surface
 - `AuthenticatedUser` — the actor a tool handler receives
+- `EnvRequirement` — `{ name, minLength?, why }`: one environment variable a plugin cannot start without, as data. A plugin exports a list of them as `<plugin>Env` (`approvalsEnv`), and a site passes the lists to `assertEnvironment` from `@forumone/throughline-core`
 - `getPluginRegistry` — the runtime registry plugins use to announce themselves and check for sibling plugins
 - `examplePlugin` — a reference implementation showing the exact shape every future plugin follows
 
+## Admin group for plugin-owned collections
+
+A plugin that declares a collection extends `CollectionPluginOptions` and spreads `resolveAdminGroup(options.admin)` into each collection's `admin` block:
+
+```ts
+admin: { ...resolveAdminGroup(options.admin), useAsTitle: 'title' }
+```
+
+| `admin.group` | Result |
+| --- | --- |
+| omitted | the `'Throughline'` group (`DEFAULT_ADMIN_GROUP`) |
+| `'Workflow'` (or `{ en: 'Workflow', fr: 'Flux' }`) | that group |
+| `false` | ungrouped — Payload's default "Collections" section |
+
+`false` here means *ungrouped*. On a collection's own `admin.group`, Payload reads `false` as "leave out of the nav entirely"; `resolveAdminGroup` never passes `false` through.
+
 ## Authoring a plugin
 
 See `docs/building-plugins.md` at the repo root.

package/dist/admin.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Where a plugin-owned collection sits in the admin sidebar.
+ *
+ * A string (or a map of locale to string, as Payload accepts) names the
+ * group. `false` leaves the collection ungrouped, in Payload's default
+ * "Collections" section — which is not what `false` means on a collection's
+ * own `admin.group`: there Payload reads it as "leave out of the nav
+ * entirely". A plugin translates this value; it never passes `false` through.
+ */
+export type PluginAdminGroup = string | Record<string, string> | false;
+/**
+ * Admin options accepted by every Throughline plugin that declares a
+ * collection. Plugins that declare none do not accept it, for the same reason
+ * a plugin with no endpoints omits `routePrefix`: an option it cannot honour
+ * would be a silent no-op.
+ */
+export interface PluginAdminOptions {
+    /**
+     * Sidebar group for every collection the plugin declares. Defaults to
+     * {@link DEFAULT_ADMIN_GROUP}. `false` leaves them ungrouped.
+     *
+     * Payload renders an ungrouped collection loose at the top of the sidebar,
+     * above every group — which is why the default is a group and not nothing.
+     */
+    group?: PluginAdminGroup;
+}
+/**
+ * The options a collection-declaring plugin adds to its own. Kept apart from
+ * `BaseCorePluginOptions` so that only those plugins carry it.
+ */
+export interface CollectionPluginOptions {
+    /** Admin UI placement for the collections this plugin declares. */
+    admin?: PluginAdminOptions;
+}
+/** The sidebar group plugin-owned collections land in when no group is given. */
+export declare const DEFAULT_ADMIN_GROUP = "Throughline";
+/**
+ * Resolves a plugin's `admin` option to the fragment it spreads into each
+ * collection's `admin` block: `{ group }` for a named group, `{}` for
+ * ungrouped. Never returns `group: false`, which Payload would read as hidden.
+ */
+export declare function resolveAdminGroup(admin?: PluginAdminOptions): {
+    group?: string | Record<string, string>;
+};
+//# sourceMappingURL=admin.d.ts.map

package/dist/admin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.d.ts","sourceRoot":"","sources":["../src/admin.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,KAAK,CAAA;AAEtE;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAA;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,mEAAmE;IACnE,KAAK,CAAC,EAAE,kBAAkB,CAAA;CAC3B;AAED,iFAAiF;AACjF,eAAO,MAAM,mBAAmB,gBAAgB,CAAA;AAEhD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,CAAC,EAAE,kBAAkB,GAAG;IAC7D,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACxC,CAGA"}

package/dist/admin.js

@@ -0,0 +1,12 @@
+/** The sidebar group plugin-owned collections land in when no group is given. */
+export const DEFAULT_ADMIN_GROUP = 'Throughline';
+/**
+ * Resolves a plugin's `admin` option to the fragment it spreads into each
+ * collection's `admin` block: `{ group }` for a named group, `{}` for
+ * ungrouped. Never returns `group: false`, which Payload would read as hidden.
+ */
+export function resolveAdminGroup(admin) {
+    const group = admin?.group ?? DEFAULT_ADMIN_GROUP;
+    return group === false ? {} : { group };
+}
+//# sourceMappingURL=admin.js.map

package/dist/admin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.js","sourceRoot":"","sources":["../src/admin.ts"],"names":[],"mappings":"AAqCA,iFAAiF;AACjF,MAAM,CAAC,MAAM,mBAAmB,GAAG,aAAa,CAAA;AAEhD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAA0B;IAG1D,MAAM,KAAK,GAAG,KAAK,EAAE,KAAK,IAAI,mBAAmB,CAAA;IACjD,OAAO,KAAK,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAA;AACzC,CAAC"}

package/dist/env.d.ts

@@ -0,0 +1,29 @@
+/**
+ * One environment variable something needs before it can start, as data.
+ *
+ * A plugin that falls back to `process.env` at init exports a list of these
+ * beside its factory — `approvalsPlugin` / `approvalsEnv`, `emailPlugin` /
+ * `emailEnv` — and its own init check reads the same entries. A site hands
+ * every list, plus its own variables, to `assertEnvironment` from
+ * `@forumone/throughline-core`, which reports everything wrong in one error
+ * before any plugin gets to throw on the first thing it finds.
+ *
+ * It describes the *environment fallback*. A site that passes the value as an
+ * option instead (say `tokenSecret` from a secrets manager) leaves that
+ * plugin's list out of its `assertEnvironment` call.
+ */
+export interface EnvRequirement {
+    /** The variable's name, e.g. `APPROVAL_TOKEN_SECRET`. */
+    readonly name: string;
+    /**
+     * The shortest value accepted. For secrets that sign or key something,
+     * where a short value is as bad as none.
+     */
+    readonly minLength?: number;
+    /**
+     * Why it is needed and how to get one, in a sentence a person fixing a
+     * deploy can act on. Printed beside the name; never include a value.
+     */
+    readonly why: string;
+}
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB"}

package/dist/env.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -32,6 +32,8 @@ export interface Logger {
  * returns a standard Payload {@link Plugin}.
  */
 export type CorePlugin<Options extends BaseCorePluginOptions = BaseCorePluginOptions> = (options: Options) => Plugin;
+export * from './admin.js';
+export * from './env.js';
 export * from './mcp.js';
 export * from './registry.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAErC;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,4FAA4F;IAC5F,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;IACnE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;IAClE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;IAClE,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;CACpE;AAED;;;GAGG;AACH,MAAM,MAAM,UAAU,CAAC,OAAO,SAAS,qBAAqB,GAAG,qBAAqB,IAAI,CACtF,OAAO,EAAE,OAAO,KACb,MAAM,CAAA;AAEX,cAAc,UAAU,CAAA;AACxB,cAAc,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAErC;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,4FAA4F;IAC5F,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;IACnE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;IAClE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;IAClE,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;CACpE;AAED;;;GAGG;AACH,MAAM,MAAM,UAAU,CAAC,OAAO,SAAS,qBAAqB,GAAG,qBAAqB,IAAI,CACtF,OAAO,EAAE,OAAO,KACb,MAAM,CAAA;AAEX,cAAc,YAAY,CAAA;AAC1B,cAAc,UAAU,CAAA;AACxB,cAAc,UAAU,CAAA;AACxB,cAAc,eAAe,CAAA"}

package/dist/index.js

@@ -1,3 +1,5 @@
+export * from './admin.js';
+export * from './env.js';
 export * from './mcp.js';
 export * from './registry.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAwCA,cAAc,UAAU,CAAA;AACxB,cAAc,eAAe,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAwCA,cAAc,YAAY,CAAA;AAC1B,cAAc,UAAU,CAAA;AACxB,cAAc,UAAU,CAAA;AACxB,cAAc,eAAe,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forumone/throughline-plugin-contract",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Shared plugin and MCP contract types and the cross-plugin registry for @forumone/throughline core packages.",
   "license": "MIT",
   "repository": {
@@ -25,12 +25,12 @@
     "dist"
   ],
   "dependencies": {
-    "payload": "^3.0.0",
+    "payload": "^3.89.0",
     "zod": "^3.23.0"
   },
   "devDependencies": {
     "@types/node": "^24.13.2",
-    "eslint": "^9.15.0",
+    "eslint": "^10.11.0",
     "typescript": "^5.6.0",
     "@forumone/throughline-eslint-config": "0.0.0",
     "@forumone/throughline-tsconfig": "0.0.0"