@bymax-one/nest-core 1.3.2 → 1.4.0

package/dist/openapi/index.cjs

@@ -17,6 +17,116 @@ 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 common.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";
@@ -209,7 +319,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"];
@@ -289,11 +400,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;
     }
@@ -349,24 +478,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]: {
@@ -376,20 +505,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
@@ -452,6 +586,27 @@ 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(core.DiscoveryService);
+    reflector = app.get(core.Reflector);
+  } catch {
+    return [];
+  }
+  return collectContributions(discovery, reflector, handlers);
+}
 function buildConfig(builder, options) {
   builder.setTitle(options.title).setDescription(options.description).setVersion(options.version);
   for (const server of options.servers) {
@@ -476,10 +631,15 @@ async function applyBymaxOpenApi(app) {
   }
   const swagger = await loadSwagger();
   const config = buildConfig(new swagger.DocumentBuilder(), options);
+  const handlers = createHandlerIdMap();
+  const generated = swagger.SwaggerModule.createDocument(app, config, {
+    operationIdFactory: recordingOperationIdFactory(handlers, options.operationIdFactory)
+  });
   const document = augmentDocument(
-    swagger.SwaggerModule.createDocument(app, config),
+    generated,
     resolved,
-    readPathPrefixes(app)
+    readPathPrefixes(app),
+    readContributions(app, handlers)
   );
   swagger.SwaggerModule.setup(options.path, app, document, {
     jsonDocumentUrl: options.jsonPath
@@ -488,4 +648,7 @@ async function applyBymaxOpenApi(app) {
   return { mounted: true, path: options.path };
 }
 
+exports.BYMAX_OPENAPI_CONTRACT_VERSION = BYMAX_OPENAPI_CONTRACT_VERSION;
+exports.BYMAX_OPENAPI_CONTRIBUTOR_METADATA = BYMAX_OPENAPI_CONTRIBUTOR_METADATA;
+exports.BymaxOpenApiContributor = BymaxOpenApiContributor;
 exports.applyBymaxOpenApi = applyBymaxOpenApi;

package/dist/openapi/index.d.cts

@@ -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.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 };