@silkweave/nestjs 1.10.0 → 1.12.0

package/build/index.mjs

@@ -2,7 +2,7 @@ import { authMiddleware, mcpCors, mcpTransport, oauthRoutes, protectedResourceMe
 import express from "express";
 import { ForbiddenException, HttpException, Inject, Injectable, Module, SetMetadata } from "@nestjs/common";
 import { validateToken } from "@silkweave/auth";
-import { SilkweaveError, createAction, createContext } from "@silkweave/core";
+import { SilkweaveError, actionMethod, createAction, createContext, methodHasBody, pathParamNames, resolveActionInput, validateActionRouting } from "@silkweave/core";
 import { buildLogLevels } from "@silkweave/logger";
 import { z } from "zod/v4";
 import { buildRouter, createActionLogger, resolveAuth } from "@silkweave/trpc";
@@ -11,7 +11,7 @@ import { renderTypegen } from "@silkweave/typegen";
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { DiscoveryModule, DiscoveryService, HttpAdapterHost, MetadataScanner, ModuleRef, Reflector } from "@nestjs/core";
-import { kebabCase } from "change-case";
+import { camelCase, kebabCase } from "change-case";
 import { GUARDS_METADATA } from "@nestjs/common/constants.js";
 //#region \0rolldown/runtime.js
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
@@ -167,7 +167,13 @@ function createActionHandler(action, context, auth, logger) {
 				}
 				authInfo = result.auth;
 			}
-			const raw = action.kind === "query" ? reqLike.query ?? parseQuery(req.url) : reqLike.body ?? await readJsonBody(req);
+			const query = reqLike.query ?? parseQuery(req.url);
+			const body = methodHasBody(actionMethod(action)) ? reqLike.body ?? await readJsonBody(req) : void 0;
+			const raw = resolveActionInput(action, {
+				params: reqLike.params,
+				query,
+				body
+			});
 			const input = action.input.parse(raw);
 			sendJson(res, await action.run(input, context.fork({
 				logger,
@@ -184,22 +190,29 @@ function createActionHandler(action, context, auth, logger) {
 * REST adapter for `@silkweave/nestjs`. Registers each discovered `@Action`
 * as an individual route on Nest's HTTP adapter:
 *
-* - `kind: 'query'` → `GET ${basePath}/${actionName-with-slashes}` (input from query string)
-* - `kind: 'mutation'` → `POST ${basePath}/${actionName-with-slashes}` (input from JSON body)
+* - HTTP verb comes from `method`, else `GET` for `kind: 'query'`, else `POST`.
+* - Path comes from `path` (joined to `basePath`, may contain `:param`
+*   placeholders), else `${basePath}/${actionName-with-slashes}`.
+* - Input is merged from the request body, the `queryParams` query-string
+*   fields, and any `:param` path placeholders (see `resolveActionInput`).
 *
-* Routes show up in Nest's `RoutesResolver` logger and are eligible for
-* `@nestjs/swagger` scanning. Works on `@nestjs/platform-express` out of the
-* box. For `@nestjs/platform-fastify`, register `@fastify/express` first.
+* Routes show up in Nest's `RoutesResolver` logger. They are registered
+* directly on the HTTP adapter (not as Nest controllers), so `@nestjs/swagger`'s
+* controller scanner does not see them - use `addSilkweaveActions()` to add them
+* to the OpenAPI document. Works on `@nestjs/platform-express` out of the box.
+* For `@nestjs/platform-fastify`, register `@fastify/express` first.
 */
 function rest(options = {}) {
+	const basePath = (options.basePath ?? "/api").replace(/\/$/, "");
 	return {
 		name: "rest",
+		basePath,
 		register({ httpAdapter, baseContext, actions }) {
-			const basePath = (options.basePath ?? "/api").replace(/\/$/, "");
 			const logger = createRestLogger();
 			for (const action of actions) {
-				const path = `${basePath}${actionNameToPath(action.name)}`;
-				const method = action.kind === "query" ? "get" : "post";
+				validateActionRouting(action);
+				const path = action.path ? `${basePath}/${action.path.replace(/^\//, "")}` : `${basePath}${actionNameToPath(action.name)}`;
+				const method = actionMethod(action).toLowerCase();
 				const handler = createActionHandler(action, baseContext, options.auth, logger);
 				httpAdapter[method](path, handler);
 			}
@@ -9035,16 +9048,21 @@ async function resolveGuard(ref, moduleRef) {
 	return ref;
 }
 /**
-* Run the configured guards against an HTTP request. Throws `ForbiddenException`
+* Run the configured guards against a request. Throws `ForbiddenException`
 * if any guard rejects, mirroring Nest's HTTP request-pipeline behavior.
 *
 * Pass `null` for `response` when running on top of a tRPC or MCP request that
 * doesn't surface a raw response object; guards that introspect the response
 * will receive `null`.
+*
+* `contextType` is reflected through `ExecutionContext.getType()` so guards can
+* branch on the transport. It is `'http'` for REST/tRPC and for MCP-over-HTTP
+* (where a header-bearing request stand-in is available); transports without any
+* HTTP request (e.g. MCP stdio) pass `'rpc'`.
 */
-async function runGuards(guards, moduleRef, reflector, classRef, handler, request, response) {
+async function runGuards(guards, moduleRef, reflector, classRef, handler, request, response, contextType = "http") {
 	if (guards.length === 0) return;
-	const context = new SilkweaveExecutionContext([request, response], classRef, handler, "http");
+	const context = new SilkweaveExecutionContext([request, response], classRef, handler, contextType);
 	for (const ref of guards) {
 		const result = (await resolveGuard(ref, moduleRef)).canActivate(context);
 		if (!((0, import_cjs.isObservable)(result) ? await (0, import_cjs.lastValueFrom)(result) : await Promise.resolve(result))) throw new ForbiddenException("Forbidden resource");
@@ -9078,9 +9096,10 @@ let ActionDiscovery = class ActionDiscovery {
 	* a list of core `Action` objects ready to feed into `silkweave().actions()`.
 	*
 	* Action invocation is wrapped to (a) run `@UseGuards` guards declared on the
-	* method or its class against the incoming HTTP request (read from
-	* `ctx.get('request')`) and (b) bind `this` to the resolved Nest provider so
-	* DI-injected dependencies remain available.
+	* method or its class against the incoming request (read from
+	* `ctx.get('request')`, populated by REST/tRPC and by MCP-over-HTTP from the
+	* SDK's `extra.requestInfo`) and (b) bind `this` to the resolved Nest provider
+	* so DI-injected dependencies remain available.
 	*/
 	discover() {
 		const discovered = [];
@@ -9119,8 +9138,14 @@ let ActionDiscovery = class ActionDiscovery {
 		const applyGuards = async (context) => {
 			if (guards.length === 0) return;
 			const request = context.getOptional("request");
-			const response = context.getOptional("response");
-			await runGuards(guards, moduleRef, reflector, d.classRef, d.method, request, response);
+			const response = context.getOptional("response") ?? null;
+			const hasRequest = request != null;
+			const guardRequest = hasRequest ? request : {
+				headers: {},
+				params: {},
+				query: {}
+			};
+			await runGuards(guards, moduleRef, reflector, d.classRef, d.method, guardRequest, response, hasRequest ? "http" : "rpc");
 		};
 		if (d.method.constructor?.name === "AsyncGeneratorFunction") {
 			if (!d.meta.chunk) throw new Error(`@Action "${name}" is an async generator but has no \`chunk\` schema`);
@@ -9132,6 +9157,9 @@ let ActionDiscovery = class ActionDiscovery {
 				input: d.meta.input,
 				chunk: d.meta.chunk,
 				kind: d.meta.kind ?? "mutation",
+				method: d.meta.method,
+				path: d.meta.path,
+				queryParams: d.meta.queryParams,
 				args: d.meta.args,
 				isEnabled,
 				toolResult: d.meta.toolResult,
@@ -9147,6 +9175,9 @@ let ActionDiscovery = class ActionDiscovery {
 			input: d.meta.input,
 			output: d.meta.output,
 			kind: d.meta.kind ?? "mutation",
+			method: d.meta.method,
+			path: d.meta.path,
+			queryParams: d.meta.queryParams,
 			args: d.meta.args,
 			isEnabled,
 			toolResult: d.meta.toolResult,
@@ -9164,6 +9195,103 @@ ActionDiscovery = __decorate([Injectable(), __decorateMetadata("design:paramtype
 	typeof (_ref4 = typeof ModuleRef !== "undefined" && ModuleRef) === "function" ? _ref4 : Object
 ])], ActionDiscovery);
 //#endregion
+//#region src/lib/openapi.ts
+/** Convert a route template's `:param` placeholders to OpenAPI `{param}` form. */
+function toOpenApiPath(template) {
+	return template.replace(/:([A-Za-z0-9_]+)/g, "{$1}");
+}
+/** The OpenAPI path key for an action - mirrors the `rest()` adapter's routing. */
+function actionRoute(action, basePath) {
+	return toOpenApiPath(`${basePath}/${action.path ? action.path.replace(/^\//, "") : action.name.replace(/\./g, "/")}`.replace(/\/{2,}/g, "/"));
+}
+/** `z.toJSONSchema` tags a top-level `$schema`; drop it for a tidy OpenAPI doc. */
+function toJsonSchema(schema) {
+	const { $schema: _schema, ...rest } = z.toJSONSchema(schema);
+	return rest;
+}
+function responseSchema(action) {
+	if (action.output) return toJsonSchema(action.output);
+	if (action.chunk) return {
+		type: "array",
+		items: toJsonSchema(action.chunk)
+	};
+}
+/** Split an action's input fields into OpenAPI path/query parameters and a body, matching the `rest()` adapter. */
+function splitInputSources(action, hasBody) {
+	const json = z.toJSONSchema(action.input);
+	const required = new Set(json.required ?? []);
+	const pathParams = new Set(pathParamNames(action.path));
+	const queryKeys = new Set((action.queryParams ?? []).map(String));
+	const split = {
+		parameters: [],
+		bodyProps: {},
+		bodyRequired: []
+	};
+	for (const [key, schema] of Object.entries(json.properties ?? {})) if (pathParams.has(key)) split.parameters.push({
+		name: key,
+		in: "path",
+		required: true,
+		schema
+	});
+	else if (!hasBody || queryKeys.has(key)) split.parameters.push({
+		name: key,
+		in: "query",
+		required: required.has(key),
+		schema
+	});
+	else {
+		split.bodyProps[key] = schema;
+		if (required.has(key)) split.bodyRequired.push(key);
+	}
+	return split;
+}
+/** Build the OpenAPI operation object for a single action. */
+function buildOperation(action, tag) {
+	const hasBody = methodHasBody(actionMethod(action));
+	const { parameters, bodyProps, bodyRequired } = splitInputSources(action, hasBody);
+	const response = responseSchema(action);
+	const operation = {
+		tags: [tag],
+		summary: action.description,
+		operationId: camelCase(action.name),
+		responses: { 200: {
+			description: "Successful response",
+			...response ? { content: { "application/json": { schema: response } } } : {}
+		} }
+	};
+	if (parameters.length) operation.parameters = parameters;
+	if (hasBody && Object.keys(bodyProps).length) operation.requestBody = {
+		required: bodyRequired.length > 0,
+		content: { "application/json": { schema: {
+			type: "object",
+			properties: bodyProps,
+			required: bodyRequired
+		} } }
+	};
+	return operation;
+}
+/**
+* Build an OpenAPI `paths` fragment for a set of Silkweave actions, mirroring
+* exactly how the `rest()` adapter routes them: the same HTTP verb (`method` ??
+* `kind`), the same `path`/`name`-derived route, and the same path/query/body
+* field split (`pathParamNames` + `queryParams`). Schemas are inlined from the
+* Zod input/output via `z.toJSONSchema`; no shared components are emitted.
+*/
+function buildActionPaths(actions, options = {}) {
+	const basePath = (options.basePath ?? "/api").replace(/\/$/, "");
+	const tag = options.tag ?? "Actions";
+	const paths = {};
+	for (const action of actions) {
+		const method = actionMethod(action).toLowerCase();
+		const route = actionRoute(action, basePath);
+		paths[route] = {
+			...paths[route] ?? {},
+			[method]: buildOperation(action, tag)
+		};
+	}
+	return paths;
+}
+//#endregion
 //#region src/lib/types.ts
 const SILKWEAVE_MODULE_OPTIONS = "__silkweave_module_options__";
 //#endregion
@@ -9223,6 +9351,55 @@ SilkweaveModule = _SilkweaveModule = __decorate([
 	])
 ], SilkweaveModule);
 //#endregion
-export { ACTIONS_METADATA, ACTION_METADATA, ACTION_RESPONSE_KEY, Action, ActionDiscovery, Actions, SILKWEAVE_MODULE_OPTIONS, SilkweaveModule, buildIsEnabled, collectGuards, mcp, rest, runGuards, trpc, typegen };
+//#region src/lib/swagger.ts
+/**
+* Merge every REST-exposed Silkweave `@Action` into a NestJS Swagger
+* `OpenAPIObject`.
+*
+* `@nestjs/swagger` builds its document by scanning **controllers**, but
+* Silkweave registers action routes directly on the HTTP adapter (so they sit
+* ahead of controllers in the request pipeline) - which means the scanner never
+* sees them. This helper closes that gap: it discovers the actions through the
+* same `ActionDiscovery` provider the `rest()` adapter uses, builds OpenAPI
+* paths with the same routing logic (`buildActionPaths`), and merges them into
+* the document. The result stays in sync with the live routes without any
+* dynamic controllers.
+*
+* Call it between `SwaggerModule.createDocument()` and `SwaggerModule.setup()`:
+*
+* @example
+* ```ts
+* const document = SwaggerModule.createDocument(app, config)
+* addSilkweaveActions(app, document)
+* SwaggerModule.setup('api/docs', app, document)
+* ```
+*/
+function addSilkweaveActions(app, document, options = {}) {
+	const discovery = app.get(ActionDiscovery);
+	const moduleOptions = app.get(SILKWEAVE_MODULE_OPTIONS);
+	const restAdapter = moduleOptions.adapters.find((adapter) => adapter.name === "rest");
+	const basePath = options.basePath ?? restAdapter?.basePath ?? "/api";
+	const allActions = discovery.discover();
+	const paths = buildActionPaths(options.includeDisabled ? allActions : allActions.filter((action) => isRestEnabled(action, moduleOptions)), {
+		basePath,
+		tag: options.tag
+	});
+	document.paths ??= {};
+	for (const [route, item] of Object.entries(paths)) document.paths[route] = {
+		...document.paths[route] ?? {},
+		...item
+	};
+	return document;
+}
+/** Whether an action would be registered by the `rest()` adapter (adapter: 'rest'). */
+function isRestEnabled(action, moduleOptions) {
+	if (!action.isEnabled) return true;
+	return action.isEnabled(createContext({
+		...moduleOptions.context ?? {},
+		adapter: "rest"
+	}));
+}
+//#endregion
+export { ACTIONS_METADATA, ACTION_METADATA, ACTION_RESPONSE_KEY, Action, ActionDiscovery, Actions, SILKWEAVE_MODULE_OPTIONS, SilkweaveModule, addSilkweaveActions, buildActionPaths, buildIsEnabled, collectGuards, mcp, rest, runGuards, trpc, typegen };
 
 //# sourceMappingURL=index.mjs.map