@lenne.tech/nest-server 11.42.7 → 11.42.8

package/migration-guides/11.42.7-to-11.42.8.md

@@ -0,0 +1,74 @@
+# Migration Guide: 11.42.7 → 11.42.8
+
+## Overview
+
+| Category             | Details                                                                                              |
+| -------------------- | ---------------------------------------------------------------------------------------------------- |
+| **Bugfix**           | `setupSwagger()` enriches every operation an `@All()` route produces, including `SEARCH` (§1)        |
+| **Bugfix**           | The Better-Auth pass-through route no longer appears as `/iam/{path}` in the Swagger document (§2)   |
+| **Dependencies**     | dev: `vite` 8.3.3; override `js-yaml` 5.4.3 (§3)                                                     |
+| **Breaking Changes** | None                                                                                                 |
+| **Migration Effort** | None for most projects. Regenerate a client built from `/api-docs-json` if you keep one (§2)         |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+```
+
+Vendor-mode projects pick it up with the core update.
+
+## 1. `SEARCH` operations of `@All()` routes are enriched
+
+For an `@All()` route, `@nestjs/swagger` documents one operation per HTTP method — including
+`SEARCH`, which no OpenAPI version lists as a path-item method. 11.42.7 walked a fixed list of
+methods and skipped it, so that one operation stayed as Swagger built it: no API-token scope line,
+no `security: []` on a public route, no tenant header, and `operationTags` did not reach it — it
+landed in its own tag group next to the regrouped siblings.
+
+The helper now reads the operations from the path item itself, so `SEARCH` (and any other method
+`@nestjs/swagger` emits) is treated like every other operation — in the full document and in the
+API-token view.
+
+Nothing to change in your code. If you assert on the document in tests, a `search` operation of an
+`@All()` route now carries the same `x-api-token-scopes`, description line and tags as its siblings.
+
+## 2. `/iam/{path}` is gone from the document
+
+`CoreBetterAuthController.handlePluginRoutes` (`@All('*path')`) forwards every other `/iam/*` request
+to Better-Auth's own handler. It appeared in Swagger as eight `/iam/{path}` operations without
+parameters or description. It is now `@ApiExcludeEndpoint()`; the route itself is unchanged.
+
+- **Generated clients:** a client generated from `/api-docs-json` (hey-api, openapi-generator, …)
+  loses its `coreBetterAuthControllerHandlePluginRoutes*` functions on the next generation. They
+  could not express any real Better-Auth call, so nothing should depend on them — but regenerate and
+  let the compiler confirm it.
+- **Own controller:** a project controller that **overrides** `handlePluginRoutes` (re-declaring
+  `@All('*path')`) must also re-declare `@ApiExcludeEndpoint()` to keep it out of the document.
+  Decorator metadata belongs to the method, so an override starts without it. A controller that
+  only inherits the method is covered automatically.
+
+## 3. Dependency updates
+
+Maintenance only, nothing to change in your project:
+
+| Package | Old | New | Where |
+| --- | --- | --- | --- |
+| `vite` | 8.3.2 | 8.3.3 | devDependencies (test tooling) |
+| `js-yaml` 5.x | 5.4.2 | 5.4.3 | override target in `pnpm-workspace.yaml` (parser bug fix) |
+
+`mongoose` 9.11.0 / `mongodb` 7.7.0 are deliberately not part of this release: the framework and the
+starter have to raise `mongodb` together, because two driver copies make Better-Auth's Mongo adapter
+reject each other's ids.
+
+## Compatibility Notes
+
+- Both changes only affect the generated Swagger/OpenAPI document. Routing, guards and API-token
+  enforcement are unchanged.
+- The document gets smaller: the framework's own test server goes from 142 to 134 operations.
+
+## References
+
+- Helper: `src/core/common/helpers/swagger.helper.ts` (`operationsOf()`)
+- Controller: `src/core/modules/better-auth/core-better-auth.controller.ts` (`handlePluginRoutes`)
+- Tests: `tests/unit/swagger-helper.spec.ts`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.42.7",
+  "version": "11.42.8",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -221,7 +221,7 @@
     "tus-js-client": "4.3.1",
     "typescript": "5.9.3",
     "unplugin-swc": "2.0.0",
-    "vite": "8.3.2",
+    "vite": "8.3.3",
     "vite-plugin-node": "8.0.0",
     "vitest": "4.1.11"
   },

package/src/core/common/helpers/swagger.helper.ts

@@ -55,9 +55,12 @@ export const SWAGGER_TENANT_HEADER_PARAMETER = 'TenantHeader';
 /** Vendor extension listing the scopes an API token needs for an operation */
 export const SWAGGER_API_TOKEN_SCOPES_EXTENSION = 'x-api-token-scopes';
 
-const HTTP_METHODS = ['delete', 'get', 'head', 'options', 'patch', 'post', 'put', 'trace'] as const;
-
-type HttpMethod = (typeof HTTP_METHODS)[number];
+/**
+ * Fields of an OpenAPI path item that are not operations. Every other key is an operation: they are read
+ * from the path item rather than from a list of HTTP methods, because `@All()` makes @nestjs/swagger emit
+ * a `search` operation too, which no OpenAPI version lists — a fixed list left it unenriched.
+ */
+const PATH_ITEM_FIELDS = new Set(['$ref', 'description', 'parameters', 'servers', 'summary']);
 
 /** An operation with the vendor extension this helper writes */
 type EnrichedOperation = OperationObject & { [SWAGGER_API_TOKEN_SCOPES_EXTENSION]?: string[] };
@@ -243,10 +246,9 @@ export function buildApiTokenSwaggerDocument(
 
   const paths: OpenAPIObject['paths'] = {};
   for (const [path, item] of Object.entries(view.paths)) {
-    const kept: PathItemObject = {};
-    for (const method of HTTP_METHODS) {
-      const operation = item[method] as EnrichedOperation | undefined;
-      if (!operation?.[SWAGGER_API_TOKEN_SCOPES_EXTENSION]?.length) {
+    const kept: Record<string, EnrichedOperation> = {};
+    for (const [method, operation] of operationsOf(item)) {
+      if (!operation[SWAGGER_API_TOKEN_SCOPES_EXTENSION]?.length) {
         continue;
       }
       operation.security = [{ [SWAGGER_BEARER_SCHEME]: [] }];
@@ -440,25 +442,30 @@ function isRef(value: unknown): value is ReferenceObject {
 
 function forEachOperation(
   document: OpenAPIObject,
-  visit: (path: string, method: HttpMethod, operation: EnrichedOperation) => void,
+  visit: (path: string, method: string, operation: EnrichedOperation) => void,
 ): void {
   for (const [path, item] of Object.entries(document.paths ?? {})) {
-    for (const method of HTTP_METHODS) {
-      const operation = item[method];
-      if (operation) {
-        visit(path, method, operation);
-      }
+    for (const [method, operation] of operationsOf(item)) {
+      visit(path, method, operation);
     }
   }
 }
 
+/** A path-item key that is not an operation: a field OpenAPI defines there, or a vendor extension. */
+function isPathItemField(key: string): boolean {
+  return PATH_ITEM_FIELDS.has(key) || key.startsWith('x-');
+}
+
+/** The operations of a path item, keyed by their lower-case HTTP method (`get`, ..., `search`). */
+function operationsOf(item: PathItemObject): [string, EnrichedOperation][] {
+  return Object.entries(item).filter(
+    ([key, value]) => !isPathItemField(key) && typeof value === 'object' && value !== null && !Array.isArray(value),
+  ) as [string, EnrichedOperation][];
+}
+
 /** Fields of a path item that are not operations (summary, description, servers, shared parameters). */
 function pathLevelFields(item: PathItemObject): PathItemObject {
-  const fields: PathItemObject = { ...item };
-  for (const method of HTTP_METHODS) {
-    delete fields[method];
-  }
-  return fields;
+  return Object.fromEntries(Object.entries(item).filter(([key]) => isPathItemField(key))) as PathItemObject;
 }
 
 /**

package/src/core/modules/better-auth/core-better-auth.controller.ts

@@ -753,6 +753,7 @@ export class CoreBetterAuthController {
    * @see README.md "Architecture: Why Custom Controllers?"
    */
   @All('*path')
+  @ApiExcludeEndpoint() // A pass-through to Better-Auth: one `/iam/{path}` per HTTP method, with nothing to document
   @Roles(RoleEnum.S_EVERYONE)
   async handlePluginRoutes(@Req() req: Request, @Res() res: Response): Promise<void> {
     return this.handleBetterAuthPlugins(req, res);