@bymax-one/nest-core 1.3.2 → 1.5.0

package/dist/openapi/index.d.ts

@@ -1,4 +1,4 @@
-import { INestApplication } from '@nestjs/common';
+import { INestApplication, CustomDecorator } from '@nestjs/common';
 
 /** Why the document was not mounted. */
 type OpenApiSkipReason = 
@@ -51,4 +51,149 @@ interface OpenApiMountOutcome {
  */
 declare function applyBymaxOpenApi(app: INestApplication): Promise<OpenApiMountOutcome>;
 
-export { type OpenApiMountOutcome, type OpenApiSkipReason, applyBymaxOpenApi };
+/**
+ * Addresses one route handler, as `'<ControllerClassName>.<methodName>'`.
+ *
+ * Controller handlers only. A route the application mounts some other way — raw
+ * middleware, a router the framework never scanned — produces no operation in
+ * the generated document and therefore no handler to address; a fragment naming
+ * one fails the build rather than being quietly dropped.
+ *
+ * This is the key a library writes its fragments against, and it is a contract:
+ * `@nestjs/swagger` hands the same pair to the operation-id factory this package
+ * installs, so a fragment can be matched to the operation the scan produced
+ * without either side reconstructing a path.
+ *
+ * Deliberately not the operation id itself. The id is whatever the ecosystem
+ * already produces — `AuthController_login` by default — and a library keying on
+ * it would break the moment a consumer supplied their own naming, while a
+ * consumer changing that naming would silently unmatch every fragment.
+ *
+ * @example 'AuthController.login'
+ * @example 'PasswordResetController.resetPassword'
+ */
+type OpenApiHandlerKey = `${string}.${string}`;
+/**
+ * A single OpenAPI object, copied into the document and never interpreted.
+ * Modelled as an open record for the same reason the contributed schemas are: a
+ * partial local model of the specification would be a second contract to keep in
+ * sync with the real one.
+ */
+type OpenApiFragmentObject = Readonly<Record<string, unknown>>;
+/**
+ * What a contributor hands over: operation fragments addressed by handler, and
+ * the components those fragments reference.
+ *
+ * The dialect is **OpenAPI 3.0**, which is what `@nestjs/swagger` produces —
+ * measured, not assumed: its `DocumentBuilder` writes `openapi: '3.0.0'` and a
+ * served document reports the same. A 3.1 fragment merged into a 3.0 document
+ * produces one that validates as neither, so nullability belongs in `nullable`
+ * rather than in a union type.
+ */
+interface OpenApiFragment {
+    /**
+     * Which revision of this contract the fragment is written against. Always
+     * {@link BYMAX_OPENAPI_CONTRACT_VERSION}.
+     *
+     * A fragment is data crossing a boundary between independently released
+     * packages, and on that boundary compile-time types protect nothing: a
+     * library compiled against one revision of this contract runs inside an
+     * application that installed another, each having type-checked against its
+     * own copy. Only the value travelling at runtime can say which shape it is.
+     * So it self-describes, and a revision this package does not know fails the
+     * document build naming both — the same reason a Kubernetes object carries
+     * `apiVersion` rather than trusting that client and server agree.
+     *
+     * A plain integer rather than a semver range: this is the shape of the
+     * exchange, not the version of any package, and it changes only when the
+     * shape does.
+     */
+    readonly contractVersion: typeof BYMAX_OPENAPI_CONTRACT_VERSION;
+    /**
+     * Operation objects to merge, keyed by the handler that produced the
+     * operation. A key addressing a handler the document does not contain fails
+     * the build naming the contributor: a fragment for a renamed handler is a
+     * check that stopped running, which is worse than one that fails.
+     */
+    readonly operations?: Readonly<Record<OpenApiHandlerKey, OpenApiFragmentObject>>;
+    /**
+     * Entries to merge under the document's `components`, keyed by member —
+     * `schemas`, `securitySchemes`, `responses`, and so on. Additive: an entry the
+     * document already defines under that name is kept.
+     */
+    readonly components?: Readonly<Record<string, Readonly<Record<string, OpenApiFragmentObject>>>>;
+}
+/**
+ * A library that describes its own routes in the document.
+ *
+ * Called once, while the document is being built, and only when the OpenAPI
+ * feature is enabled — so a library implementing it costs an application that
+ * never builds a document nothing beyond one metadata entry.
+ */
+interface IOpenApiContributor {
+    /**
+     * Produce this library's fragments.
+     *
+     * Called after the application's options have resolved, so a contributor may
+     * derive its contribution from its own configuration — which is the case that
+     * makes this contract necessary rather than convenient. A library whose
+     * credential names or transport are configurable cannot state its security
+     * statically; only it can say what its resolved options mean.
+     *
+     * @returns The fragments to merge. Return an empty object to contribute
+     *   nothing; throwing fails the document build with the contributor named.
+     */
+    contributeOpenApi(): OpenApiFragment;
+}
+/**
+ * The revision of the fragment exchange this package speaks.
+ *
+ * Bumped only when the shape of {@link OpenApiFragment} changes in a way a
+ * previous revision's fragment would be misread under — not when a member is
+ * added, which older fragments simply do not carry.
+ */
+declare const BYMAX_OPENAPI_CONTRACT_VERSION = 1;
+/**
+ * Reflect metadata key carrying the contributor marker.
+ *
+ * A literal string rather than a key from `DiscoveryService.createDecorator()`,
+ * which mints a random key per module load: this package ships one bundle per
+ * subpath, so a library decorating its class through `./openapi` would get a
+ * different key than the scan running from the package root and nothing would
+ * ever be discovered. The same reasoning governs the health and metrics markers.
+ * Namespaced so it cannot collide with a consumer's own metadata.
+ */
+declare const BYMAX_OPENAPI_CONTRIBUTOR_METADATA = "bymax-one:openapi-contributor";
+/**
+ * Mark a provider class as an OpenAPI contributor, so `applyBymaxOpenApi` finds
+ * it without the application wiring anything.
+ *
+ * The class must implement {@link IOpenApiContributor}; a marked provider that
+ * does not fails the document build with a message naming it, rather than being
+ * skipped silently.
+ *
+ * @returns The class decorator carrying the marker.
+ * @example
+ *   \@BymaxOpenApiContributor()
+ *   \@Injectable()
+ *   export class AuthOpenApi implements IOpenApiContributor {
+ *     constructor(private readonly options: ResolvedAuthOptions) {}
+ *     contributeOpenApi(): OpenApiFragment {
+ *       return {
+ *         components: {
+ *           securitySchemes: {
+ *             authCookie: { type: 'apiKey', in: 'cookie', name: this.options.cookies.accessTokenName },
+ *             refreshCookie: { type: 'apiKey', in: 'cookie', name: this.options.cookies.refreshTokenName }
+ *           }
+ *         },
+ *         operations: {
+ *           'AuthController.login': { security: [] },
+ *           'AuthController.refresh': { security: [{ refreshCookie: [] }] }
+ *         }
+ *       }
+ *     }
+ *   }
+ */
+declare function BymaxOpenApiContributor(): CustomDecorator<string>;
+
+export { BYMAX_OPENAPI_CONTRACT_VERSION, BYMAX_OPENAPI_CONTRIBUTOR_METADATA, BymaxOpenApiContributor, type IOpenApiContributor, type OpenApiFragment, type OpenApiFragmentObject, type OpenApiHandlerKey, type OpenApiMountOutcome, type OpenApiSkipReason, applyBymaxOpenApi };

package/dist/openapi/index.mjs

@@ -1,5 +1,5 @@
-import { Logger, VersioningType, VERSION_NEUTRAL } from '@nestjs/common';
-import { ApplicationConfig } from '@nestjs/core';
+import { SetMetadata, Logger, VersioningType, VERSION_NEUTRAL } from '@nestjs/common';
+import { DiscoveryService, Reflector, ApplicationConfig } from '@nestjs/core';
 
 // src/openapi/openapi.bootstrap.ts
 
@@ -15,10 +15,148 @@ function isProductionRuntime(value = process.env["NODE_ENV"]) {
   return !NON_PRODUCTION_ENVIRONMENTS.has(value.trim().toLowerCase());
 }
 
+// src/discovery.ts
+function labelFor(className, token) {
+  return className === "" ? String(token) : className;
+}
+function findMarkedProviders(discovery, reflector, metadataKey) {
+  const marked = [];
+  for (const wrapper of discovery.getProviders()) {
+    const metatype = wrapper.metatype;
+    if (typeof metatype !== "function") {
+      continue;
+    }
+    if (reflector.get(metadataKey, metatype) !== true) {
+      continue;
+    }
+    marked.push({ instance: wrapper.instance, label: labelFor(metatype.name, wrapper.name) });
+  }
+  return marked;
+}
+var BYMAX_OPENAPI_CONTRACT_VERSION = 1;
+var BYMAX_OPENAPI_CONTRIBUTOR_METADATA = "bymax-one:openapi-contributor";
+function BymaxOpenApiContributor() {
+  return SetMetadata(BYMAX_OPENAPI_CONTRIBUTOR_METADATA, true);
+}
+
+// src/openapi/openapi.contribution.ts
+function createHandlerIdMap() {
+  const ids = /* @__PURE__ */ new Map();
+  const versions = /* @__PURE__ */ new Map();
+  return {
+    record: (controllerKey, methodKey, version, id) => {
+      const handlerKey = `${controllerKey}.${methodKey}`;
+      const seen = versions.get(handlerKey) ?? /* @__PURE__ */ new Set();
+      if (seen.has(version)) {
+        throw new Error(
+          `[BymaxCoreModule] two route handlers in this application answer to "${handlerKey}", so an OpenAPI fragment addressing it would apply to both. Handler keys are "<ControllerClassName>.<methodName>"; rename one of the controller classes.`
+        );
+      }
+      seen.add(version);
+      versions.set(handlerKey, seen);
+      ids.set(handlerKey, [...ids.get(handlerKey) ?? [], id]);
+    },
+    idsFor: (handlerKey) => ids.get(handlerKey) ?? [],
+    keys: () => [...ids.keys()]
+  };
+}
+function isContributor(instance) {
+  return typeof instance?.contributeOpenApi === "function";
+}
+function callContributor(contributor, label) {
+  try {
+    return contributor.contributeOpenApi();
+  } catch (cause) {
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    throw new Error(
+      `[BymaxCoreModule] "${label}" failed to contribute to the OpenAPI document: ${reason}`,
+      {
+        cause
+      }
+    );
+  }
+}
+function assertContractVersion(fragment, label) {
+  if (fragment.contractVersion === BYMAX_OPENAPI_CONTRACT_VERSION) {
+    return;
+  }
+  throw new Error(
+    `[BymaxCoreModule] "${label}" contributed a fragment written against OpenAPI contract version ${String(fragment.contractVersion)}, and this package speaks version ${String(BYMAX_OPENAPI_CONTRACT_VERSION)}. Upgrade whichever of the two is behind; the shapes are not interchangeable.`
+  );
+}
+function resolveOperations(fragment, label, handlers) {
+  const entries = Object.entries(fragment.operations ?? {});
+  const unmatched = entries.filter(([handlerKey]) => handlers.idsFor(handlerKey).length === 0);
+  if (unmatched.length > 0) {
+    const known = handlers.keys();
+    throw new Error(
+      `[BymaxCoreModule] "${label}" contributed fragments for ${unmatched.length} handler(s) this application does not have: ${unmatched.map(([key]) => key).join(", ")}. Keys are "<ControllerClassName>.<methodName>". The application has: ${known.length === 0 ? "(none)" : known.join(", ")}.`
+    );
+  }
+  return Object.fromEntries(
+    entries.flatMap(
+      ([handlerKey, operation]) => handlers.idsFor(handlerKey).map((id) => [id, operation])
+    )
+  );
+}
+function collectContributions(discovery, reflector, handlers) {
+  const marked = [...findMarkedProviders(discovery, reflector, BYMAX_OPENAPI_CONTRIBUTOR_METADATA)];
+  const labels = marked.map(({ label }) => label);
+  const duplicated = labels.filter((label, index) => labels.indexOf(label) !== index);
+  if (duplicated.length > 0) {
+    throw new Error(
+      `[BymaxCoreModule] more than one OpenAPI contributor is named "${[...new Set(duplicated)].join('", "')}", so the order they merge in would depend on the container rather than on anything stated. Rename one of the contributor classes.`
+    );
+  }
+  marked.sort((left, right) => left.label.localeCompare(right.label));
+  return marked.map(({ instance, label }) => {
+    if (!isContributor(instance)) {
+      throw new Error(
+        `[BymaxCoreModule] "${label}" is marked @BymaxOpenApiContributor() but does not implement IOpenApiContributor: it must expose a "contributeOpenApi" method.`
+      );
+    }
+    const fragment = callContributor(instance, label);
+    assertContractVersion(fragment, label);
+    return {
+      label,
+      operations: resolveOperations(fragment, label, handlers),
+      components: fragment.components ?? {}
+    };
+  });
+}
+
 // src/route-defaults.ts
 var DEFAULT_HEALTH_PATH = "health";
 var DEFAULT_METRICS_PATH = "metrics";
 
+// src/openapi/openapi.routes.ts
+function trimSlashes(segment) {
+  return segment.split("/").filter((part) => part !== "").join("/");
+}
+function routePath(prefix, suffix) {
+  return prefix === "" ? `/${suffix}` : `/${prefix}/${suffix}`;
+}
+function healthRoutes(options) {
+  const bases = /* @__PURE__ */ new Set([trimSlashes(options.health.path), DEFAULT_HEALTH_PATH]);
+  return [...bases].flatMap((base) => [`${base}/live`, `${base}/ready`]);
+}
+function metricsRoutes(options) {
+  return [.../* @__PURE__ */ new Set([trimSlashes(options.metrics.path), DEFAULT_METRICS_PATH])];
+}
+function indexOwnRoutes(options, prefixes) {
+  const normalized = prefixes.map(trimSlashes);
+  const expand = (suffixes) => normalized.flatMap((prefix) => suffixes.map((suffix) => routePath(prefix, suffix)));
+  const health = expand(healthRoutes(options));
+  const metrics = expand(metricsRoutes(options));
+  return {
+    isHealth: (path) => health.includes(path),
+    isMetrics: (path) => metrics.includes(path)
+  };
+}
+function isOwnRoute(path, method, routes) {
+  return method === "get" && (routes.isHealth(path) || routes.isMetrics(path));
+}
+
 // src/envelope/error-codes.ts
 var BYMAX_BAD_REQUEST = "BYMAX_BAD_REQUEST";
 var BYMAX_VALIDATION_FAILED = "BYMAX_VALIDATION_FAILED";
@@ -207,7 +345,8 @@ function operationsOf(item) {
 }
 function mergeResponses(existing, additions) {
   const merged = new Map(Object.entries(existing));
-  for (const [status, contributed] of Object.entries(additions)) {
+  for (const [status, value] of Object.entries(additions)) {
+    const contributed = asRecord(value);
     const current = asRecord(merged.get(status));
     if (current["content"] === void 0 && current["$ref"] === void 0) {
       const described = current["description"] === void 0 || current["description"] === "" ? contributed["description"] : current["description"];
@@ -216,29 +355,6 @@ function mergeResponses(existing, additions) {
   }
   return Object.fromEntries(merged);
 }
-function trimSlashes(segment) {
-  return segment.split("/").filter((part) => part !== "").join("/");
-}
-function routePath(prefix, suffix) {
-  return prefix === "" ? `/${suffix}` : `/${prefix}/${suffix}`;
-}
-function healthRoutes(options) {
-  const bases = /* @__PURE__ */ new Set([trimSlashes(options.health.path), DEFAULT_HEALTH_PATH]);
-  return [...bases].flatMap((base) => [`${base}/live`, `${base}/ready`]);
-}
-function metricsRoutes(options) {
-  return [.../* @__PURE__ */ new Set([trimSlashes(options.metrics.path), DEFAULT_METRICS_PATH])];
-}
-function indexOwnRoutes(options, prefixes) {
-  const normalized = prefixes.map(trimSlashes);
-  const expand = (suffixes) => normalized.flatMap((prefix) => suffixes.map((suffix) => routePath(prefix, suffix)));
-  const health = expand(healthRoutes(options));
-  const metrics = expand(metricsRoutes(options));
-  return {
-    isHealth: (path) => health.includes(path),
-    isMetrics: (path) => metrics.includes(path)
-  };
-}
 function withoutDisabledRoutes(paths, options, routes) {
   const disabled = (path) => !options.health.enabled && routes.isHealth(path) || !options.metrics.enabled && routes.isMetrics(path);
   const kept = Object.entries(paths).map(([path, item]) => {
@@ -287,11 +403,29 @@ function coreResponses(path, options, routes) {
   }
   return responses;
 }
-function augmentOperation(operation, path, method, options, routes) {
-  const result = { ...operation };
-  if (result["security"] === void 0) {
+function fragmentsFor(operationId, contributions) {
+  return contributions.flatMap(
+    (contribution) => Object.entries(contribution.operations).filter(([id]) => id === operationId).map(([, fragment]) => fragment)
+  );
+}
+function mergeFragment(operation, fragment) {
+  const { responses, ...members } = fragment;
+  const merged = { ...members, ...operation };
+  if (responses !== void 0) {
+    merged["responses"] = mergeResponses(asRecord(operation["responses"]), asRecord(responses));
+  }
+  return merged;
+}
+function augmentOperation(operation, path, method, options, routes, contributions) {
+  const declaredByDocument = operation["security"] !== void 0;
+  let result = { ...operation };
+  for (const fragment of fragmentsFor(result["operationId"], contributions)) {
+    result = { ...mergeFragment(result, fragment) };
+  }
+  if (!declaredByDocument) {
     const override = options.openapi.operationSecurity[operationKey(method, path)];
-    const security = override ?? ownRouteSecurity(path, method, options, routes);
+    const describedByLibrary = result["security"] !== void 0;
+    const security = override ?? (describedByLibrary ? void 0 : ownRouteSecurity(path, method, options, routes));
     if (security !== void 0) {
       result["security"] = security;
     }
@@ -304,6 +438,25 @@ function augmentOperation(operation, path, method, options, routes) {
   }
   return result;
 }
+function consumerOperations(paths, routes) {
+  return Object.entries(paths).flatMap(
+    ([path, item]) => operationsOf(item).filter(([method]) => !isOwnRoute(path, method, routes)).map(([method, operation]) => ({
+      key: operationKey(method, path),
+      operation: asRecord(operation)
+    }))
+  );
+}
+function unsecuredOperations(document, options, pathPrefixes = [""]) {
+  if (document.security !== void 0) {
+    return [];
+  }
+  const routes = indexOwnRoutes(options, pathPrefixes);
+  const candidates = consumerOperations(asRecord(document.paths), routes);
+  if (!candidates.some(({ operation }) => operation["security"] !== void 0)) {
+    return [];
+  }
+  return candidates.filter(({ operation }) => operation["security"] === void 0).map(({ key }) => key);
+}
 function assertSchemesDeclared(openapi, schemes) {
   const required = [...openapi.security, ...Object.values(openapi.operationSecurity).flat()];
   const named = [...new Set(required.flatMap((requirement) => Object.keys(requirement)))];
@@ -347,24 +500,24 @@ function assertOverridesMatch(paths, openapi) {
     `[BymaxCoreModule] openapi.operationSecurity addresses ${unmatched.length} operation(s) that the document does not contain: ${unmatched.join(", ")}. Keys are "<METHOD> <path>" with the path exactly as documented, including any global prefix. The document contains: ${documented.length === 0 ? "(none)" : documented.join(", ")}.`
   );
 }
-function augmentPaths(paths, options, routes) {
+function augmentPaths(paths, options, routes, contributions) {
   return Object.fromEntries(
     Object.entries(paths).map(([path, item]) => {
       const augmented = operationsOf(item).map(([method, operation]) => [
         method,
-        augmentOperation(asRecord(operation), path, method, options, routes)
+        augmentOperation(asRecord(operation), path, method, options, routes, contributions)
       ]);
       return [path, { ...asRecord(item), ...Object.fromEntries(augmented) }];
     })
   );
 }
-function augmentDocument(document, options, pathPrefixes = [""]) {
+function augmentDocument(document, options, pathPrefixes = [""], contributions = []) {
   const { openapi } = options;
   const components = asRecord(document.components);
-  const merged = { ...components };
+  const merged = new Map(Object.entries(components));
   if (openapi.includeCoreSchemas) {
-    merged["schemas"] = mergeAbsent(asRecord(components["schemas"]), CORE_SCHEMAS);
-    merged["parameters"] = mergeAbsent(asRecord(components["parameters"]), CORE_PARAMETERS);
+    merged.set("schemas", mergeAbsent(asRecord(components["schemas"]), CORE_SCHEMAS));
+    merged.set("parameters", mergeAbsent(asRecord(components["parameters"]), CORE_PARAMETERS));
   }
   const scrapeScheme = options.metrics.authToken === void 0 ? {} : {
     [METRICS_SCHEME_NAME]: {
@@ -374,20 +527,25 @@ function augmentDocument(document, options, pathPrefixes = [""]) {
     }
   };
   assertScrapeSchemeIsOurs(openapi, components, options.metrics.authToken !== void 0);
-  const schemes = mergeAbsent(asRecord(components["securitySchemes"]), {
+  const declaredSchemes = mergeAbsent(asRecord(components["securitySchemes"]), {
     ...openapi.securitySchemes,
     ...scrapeScheme
   });
-  if (Object.keys(schemes).length > 0) {
-    merged["securitySchemes"] = schemes;
+  if (Object.keys(declaredSchemes).length > 0) {
+    merged.set("securitySchemes", declaredSchemes);
+  }
+  for (const contribution of contributions) {
+    for (const [member, entries] of Object.entries(contribution.components)) {
+      merged.set(member, mergeAbsent(asRecord(merged.get(member)), entries));
+    }
   }
-  assertSchemesDeclared(openapi, schemes);
+  assertSchemesDeclared(openapi, asRecord(merged.get("securitySchemes")));
   const routes = indexOwnRoutes(options, pathPrefixes);
   const served = withoutDisabledRoutes(asRecord(document.paths), options, routes);
   assertOverridesMatch(served, openapi);
-  const paths = document.paths === void 0 ? {} : { paths: augmentPaths(served, options, routes) };
+  const paths = document.paths === void 0 ? {} : { paths: augmentPaths(served, options, routes, contributions) };
   const security = openapi.security.length > 0 && document.security === void 0 ? { security: openapi.security } : {};
-  return { ...document, components: merged, ...paths, ...security };
+  return { ...document, components: Object.fromEntries(merged), ...paths, ...security };
 }
 
 // src/optional-peer.ts
@@ -413,6 +571,7 @@ async function loadSwagger() {
 }
 
 // src/openapi/openapi.bootstrap.ts
+var MAX_WARNED_OPERATIONS = 10;
 var OPTIONS_UNRESOLVED_MESSAGE = "[BymaxCoreModule] applyBymaxOpenApi could not resolve BYMAX_CORE_OPTIONS from the application. Register BymaxCoreModule (forRoot or forRootAsync) before calling it, and keep the module global or import it into the module you bootstrap.";
 function resolveCoreOptions(app) {
   try {
@@ -450,6 +609,37 @@ function readPathPrefixes(app) {
   const globalPrefix = config.getGlobalPrefix();
   return versionSegments(config.getVersioning()).map((segment) => `${globalPrefix}/${segment}`);
 }
+function recordingOperationIdFactory(handlers, configured) {
+  return (controllerKey, methodKey, version) => {
+    const id = configured === void 0 ? defaultOperationId(controllerKey, methodKey, version) : configured(controllerKey, methodKey, version);
+    handlers.record(controllerKey, methodKey, version, id);
+    return id;
+  };
+}
+function defaultOperationId(controllerKey, methodKey, version) {
+  return version === void 0 ? `${controllerKey}_${methodKey}` : `${controllerKey}_${methodKey}_${version}`;
+}
+function readContributions(app, handlers) {
+  let discovery;
+  let reflector;
+  try {
+    discovery = app.get(DiscoveryService);
+    reflector = app.get(Reflector);
+  } catch {
+    return [];
+  }
+  return collectContributions(discovery, reflector, handlers);
+}
+function warnUnsecuredOperations(logger, keys) {
+  if (keys.length === 0) {
+    return;
+  }
+  const elided = keys.length - MAX_WARNED_OPERATIONS;
+  const listed = keys.slice(0, MAX_WARNED_OPERATIONS).join(", ");
+  logger.warn(
+    `a client generated from the OpenAPI document will send no credentials to ${keys.length} operation(s): ${listed}${elided > 0 ? `, and ${elided} more` : ""}. They state no security requirement, the document declares no default, and other operations in it do state one \u2014 so this is more often a missing openapi.security default than a public API. Set openapi.security, or state the intent per operation with an explicit [] in openapi.operationSecurity.`
+  );
+}
 function buildConfig(builder, options) {
   builder.setTitle(options.title).setDescription(options.description).setVersion(options.version);
   for (const server of options.servers) {
@@ -474,11 +664,13 @@ async function applyBymaxOpenApi(app) {
   }
   const swagger = await loadSwagger();
   const config = buildConfig(new swagger.DocumentBuilder(), options);
-  const document = augmentDocument(
-    swagger.SwaggerModule.createDocument(app, config),
-    resolved,
-    readPathPrefixes(app)
-  );
+  const handlers = createHandlerIdMap();
+  const generated = swagger.SwaggerModule.createDocument(app, config, {
+    operationIdFactory: recordingOperationIdFactory(handlers, options.operationIdFactory)
+  });
+  const prefixes = readPathPrefixes(app);
+  const document = augmentDocument(generated, resolved, prefixes, readContributions(app, handlers));
+  warnUnsecuredOperations(logger, unsecuredOperations(document, resolved, prefixes));
   swagger.SwaggerModule.setup(options.path, app, document, {
     jsonDocumentUrl: options.jsonPath
   });
@@ -486,4 +678,4 @@ async function applyBymaxOpenApi(app) {
   return { mounted: true, path: options.path };
 }
 
-export { applyBymaxOpenApi };
+export { BYMAX_OPENAPI_CONTRACT_VERSION, BYMAX_OPENAPI_CONTRIBUTOR_METADATA, BymaxOpenApiContributor, applyBymaxOpenApi };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-core",
-  "version": "1.3.2",
+  "version": "1.5.0",
   "description": "Zero-dependency NestJS 11 application foundation kit: error-envelope exception filter, request-timing interceptor, pagination helpers, health endpoints with indicator discovery, an optional Prometheus metrics endpoint with a contribution contract, OpenAPI documents in development, and OpenTelemetry trace correlation.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",
@@ -136,6 +136,7 @@
     "@nestjs/common": "^11.1.20",
     "@nestjs/core": "^11.1.20",
     "@nestjs/platform-express": "^11.1.20",
+    "@nestjs/platform-fastify": "^11.1.29",
     "@nestjs/swagger": "^11.4.6",
     "@nestjs/testing": "^11.1.20",
     "@opentelemetry/api": "^1.9.1",
@@ -155,6 +156,7 @@
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-prettier": "^5.5.5",
     "eslint-plugin-security": "^4.0.0",
+    "fastify": "^5.11.3",
     "globals": "^17.6.0",
     "husky": "^9.1.7",
     "jest": "^30.4.2",