@forumone/throughline-plugin-contract 0.2.1 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Forum One Communications Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/auth.d.ts

@@ -15,5 +15,16 @@ export interface McpAuthResult {
     user: AuthenticatedUser;
     apiKeyName: string;
     apiKeyId: string;
+    /**
+     * What this key was granted, from the key record. A tool declaring a
+     * `requiredScope` is refused — and hidden from `tools/list` — unless it is
+     * named here.
+     *
+     * Optional so an authenticator predating scopes still type-checks; absent is
+     * read as "no scopes", which refuses every scoped tool rather than allowing
+     * them. A key that cannot say what it may do may not do the consequential
+     * things.
+     */
+    scopes?: string[];
 }
 //# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAEjD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAA;CAC9D;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,iBAAiB,CAAA;IACvB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;CACjB"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAEjD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAA;CAC9D;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,iBAAiB,CAAA;IACvB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;CAClB"}

package/dist/index.d.ts

@@ -29,5 +29,4 @@ export type CorePlugin<Options extends BaseCorePluginOptions = BaseCorePluginOpt
 export * from './mcp.js';
 export * from './auth.js';
 export * from './registry.js';
-export * from './example-plugin-pattern.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;;;;OAIG;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,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,6BAA6B,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;;;;OAIG;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,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA"}

package/dist/index.js

@@ -1,5 +1,4 @@
 export * from './mcp.js';
 export * from './auth.js';
 export * from './registry.js';
-export * from './example-plugin-pattern.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAkCA,cAAc,UAAU,CAAA;AACxB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,6BAA6B,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAkCA,cAAc,UAAU,CAAA;AACxB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA"}

package/dist/mcp.d.ts

@@ -10,6 +10,14 @@ export interface McpToolDefinition<Input extends z.ZodType = z.ZodType, Output =
     description: string;
     /** Zod schema for the input; used for validation and for generating the MCP tool schema. */
     inputSchema: Input;
+    /**
+     * The API-key scope a caller must hold, e.g. `'publishing.execute'`.
+     *
+     * Declared on the consequential tools — the ones that write, publish or
+     * decide. A tool with no `requiredScope` is callable by any authenticated
+     * key, which is the right default for a read.
+     */
+    requiredScope?: string;
     /** Handler invoked with validated input plus per-request context. */
     handler: (input: z.infer<Input>, context: McpToolContext) => Promise<Output>;
 }

package/dist/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAC5B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAExC;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,KAAK,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IACtF,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAA;IACZ,uFAAuF;IACvF,WAAW,EAAE,MAAM,CAAA;IACnB,4FAA4F;IAC5F,WAAW,EAAE,KAAK,CAAA;IAClB,qEAAqE;IACrE,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAC7E;AAED,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAA;IAC9B,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAA;IAClB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAC5B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAExC;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,KAAK,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IACtF,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAA;IACZ,uFAAuF;IACvF,WAAW,EAAE,MAAM,CAAA;IACnB,4FAA4F;IAC5F,WAAW,EAAE,KAAK,CAAA;IAClB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,qEAAqE;IACrE,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAC7E;AAED,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAA;IAC9B,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAA;IAClB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forumone/throughline-plugin-contract",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Shared plugin and MCP contract types and the cross-plugin registry for @forumone/throughline core packages.",
   "license": "MIT",
   "repository": {
@@ -24,22 +24,22 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "build": "tsc -b",
-    "dev": "tsc -b -w",
-    "clean": "rm -rf dist .turbo *.tsbuildinfo",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src"
-  },
   "dependencies": {
     "payload": "^3.0.0",
     "zod": "^3.23.0"
   },
   "devDependencies": {
-    "@forumone/throughline-eslint-config": "workspace:*",
-    "@forumone/throughline-tsconfig": "workspace:*",
     "@types/node": "^20.17.0",
     "eslint": "^9.15.0",
-    "typescript": "^5.6.0"
+    "typescript": "^5.6.0",
+    "@forumone/throughline-eslint-config": "0.0.0",
+    "@forumone/throughline-tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsc -b -w",
+    "clean": "rm -rf dist .turbo *.tsbuildinfo",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src"
   }
-}
+}

package/dist/example-plugin-pattern.d.ts

@@ -1,12 +0,0 @@
-import type { BaseCorePluginOptions, CorePlugin } from './index.js';
-/**
- * EXAMPLE ONLY — not a real plugin. Reference implementation showing the
- * shape every Throughline core plugin follows. Every future plugin should
- * lift this structure and fill in the feature-specific parts.
- */
-export interface ExamplePluginOptions extends BaseCorePluginOptions {
-    /** A plugin-specific option. */
-    greeting?: string;
-}
-export declare const examplePlugin: CorePlugin<ExamplePluginOptions>;
-//# sourceMappingURL=example-plugin-pattern.d.ts.map

package/dist/example-plugin-pattern.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"example-plugin-pattern.d.ts","sourceRoot":"","sources":["../src/example-plugin-pattern.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAGnE;;;;GAIG;AAEH,MAAM,WAAW,oBAAqB,SAAQ,qBAAqB;IACjE,gCAAgC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAKD,eAAO,MAAM,aAAa,EAAE,UAAU,CAAC,oBAAoB,CAuD1D,CAAA"}

package/dist/example-plugin-pattern.js

@@ -1,58 +0,0 @@
-import { getPluginRegistry } from './registry.js';
-const EXAMPLE_PLUGIN_ID = '@forumone/throughline-example';
-const EXAMPLE_PLUGIN_VERSION = '0.0.0';
-export const examplePlugin = (options) => {
-    return (incomingConfig) => {
-        // Step 1 — honour the disabled flag before doing any work.
-        if (options.enabled === false)
-            return incomingConfig;
-        // Step 2 — apply defaults. Note: route prefixes here MUST NOT include
-        // `/api` — Payload mounts top-level endpoints under its API base
-        // (default `/api`), so the user-facing URL becomes `/api/example/mcp`.
-        const greeting = options.greeting ?? 'Hello';
-        const routePrefix = options.routePrefix ?? '/example';
-        // Step 3 — extend the incoming config by spreading and appending.
-        //          Never replace existing arrays; always concatenate.
-        return {
-            ...incomingConfig,
-            collections: [
-                ...(incomingConfig.collections ?? []),
-                // Plugin's own collections go here.
-            ],
-            endpoints: [
-                ...(incomingConfig.endpoints ?? []),
-                {
-                    path: `${routePrefix}/mcp`,
-                    method: 'post',
-                    handler: async () => {
-                        // Real plugins delegate this to an MCP server implementation.
-                        return new Response(JSON.stringify({ greeting }), {
-                            headers: { 'content-type': 'application/json' },
-                        });
-                    },
-                },
-            ],
-            hooks: {
-                ...(incomingConfig.hooks ?? {}),
-                afterError: [
-                    ...(incomingConfig.hooks?.afterError ?? []),
-                    // Plugin's global error hooks go here.
-                ],
-            },
-            onInit: async (payload) => {
-                // Always run any pre-existing onInit first so plugins compose cleanly.
-                if (incomingConfig.onInit) {
-                    await incomingConfig.onInit(payload);
-                }
-                // Announce presence and assert required capabilities from siblings.
-                const registry = getPluginRegistry(payload);
-                registry.register({
-                    id: EXAMPLE_PLUGIN_ID,
-                    version: EXAMPLE_PLUGIN_VERSION,
-                    capabilities: ['example'],
-                });
-            },
-        };
-    };
-};
-//# sourceMappingURL=example-plugin-pattern.js.map

package/dist/example-plugin-pattern.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"example-plugin-pattern.js","sourceRoot":"","sources":["../src/example-plugin-pattern.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAajD,MAAM,iBAAiB,GAAG,+BAA+B,CAAA;AACzD,MAAM,sBAAsB,GAAG,OAAO,CAAA;AAEtC,MAAM,CAAC,MAAM,aAAa,GAAqC,CAAC,OAAO,EAAE,EAAE;IACzE,OAAO,CAAC,cAAsB,EAAU,EAAE;QACxC,2DAA2D;QAC3D,IAAI,OAAO,CAAC,OAAO,KAAK,KAAK;YAAE,OAAO,cAAc,CAAA;QAEpD,sEAAsE;QACtE,iEAAiE;QACjE,uEAAuE;QACvE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAA;QAC5C,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,UAAU,CAAA;QAErD,kEAAkE;QAClE,8DAA8D;QAC9D,OAAO;YACL,GAAG,cAAc;YACjB,WAAW,EAAE;gBACX,GAAG,CAAC,cAAc,CAAC,WAAW,IAAI,EAAE,CAAC;gBACrC,oCAAoC;aACrC;YACD,SAAS,EAAE;gBACT,GAAG,CAAC,cAAc,CAAC,SAAS,IAAI,EAAE,CAAC;gBACnC;oBACE,IAAI,EAAE,GAAG,WAAW,MAAM;oBAC1B,MAAM,EAAE,MAAM;oBACd,OAAO,EAAE,KAAK,IAAI,EAAE;wBAClB,8DAA8D;wBAC9D,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE;4BAChD,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;yBAChD,CAAC,CAAA;oBACJ,CAAC;iBACF;aACF;YACD,KAAK,EAAE;gBACL,GAAG,CAAC,cAAc,CAAC,KAAK,IAAI,EAAE,CAAC;gBAC/B,UAAU,EAAE;oBACV,GAAG,CAAC,cAAc,CAAC,KAAK,EAAE,UAAU,IAAI,EAAE,CAAC;oBAC3C,uCAAuC;iBACxC;aACF;YACD,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;gBACxB,uEAAuE;gBACvE,IAAI,cAAc,CAAC,MAAM,EAAE,CAAC;oBAC1B,MAAM,cAAc,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;gBACtC,CAAC;gBAED,oEAAoE;gBACpE,MAAM,QAAQ,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAA;gBAC3C,QAAQ,CAAC,QAAQ,CAAC;oBAChB,EAAE,EAAE,iBAAiB;oBACrB,OAAO,EAAE,sBAAsB;oBAC/B,YAAY,EAAE,CAAC,SAAS,CAAC;iBAC1B,CAAC,CAAA;YACJ,CAAC;SACF,CAAA;IACH,CAAC,CAAA;AACH,CAAC,CAAA"}