@bymax-one/nest-core 1.3.1 → 1.4.0

package/dist/openapi/index.cjs

@@ -1,6 +1,7 @@
 'use strict';
 
 var common = require('@nestjs/common');
+var core = require('@nestjs/core');
 
 // src/openapi/openapi.bootstrap.ts
 
@@ -16,6 +17,120 @@ 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";
+
 // src/envelope/error-codes.ts
 var BYMAX_BAD_REQUEST = "BYMAX_BAD_REQUEST";
 var BYMAX_VALIDATION_FAILED = "BYMAX_VALIDATION_FAILED";
@@ -177,6 +292,19 @@ var CORE_PARAMETERS = {
 };
 
 // src/openapi/openapi.document.ts
+var OPERATION_METHODS = [
+  "get",
+  "post",
+  "put",
+  "patch",
+  "delete",
+  "head",
+  "options",
+  "trace"
+];
+var METRICS_SCHEME_NAME = "BymaxMetricsAuth";
+var ERROR_ENVELOPE_SCHEMA = "BymaxErrorEnvelope";
+var HEALTH_RESPONSE_SCHEMA = "BymaxHealthResponse";
 function asRecord(value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     return {};
@@ -186,21 +314,216 @@ function asRecord(value) {
 function mergeAbsent(existing, additions) {
   return { ...additions, ...existing };
 }
-function augmentDocument(document, options) {
-  const components = asRecord(document.components);
-  const merged = { ...components };
-  if (options.includeCoreSchemas) {
-    merged["schemas"] = mergeAbsent(asRecord(components["schemas"]), CORE_SCHEMAS);
-    merged["parameters"] = mergeAbsent(asRecord(components["parameters"]), CORE_PARAMETERS);
-  }
-  const securitySchemeNames = Object.keys(options.securitySchemes);
-  if (securitySchemeNames.length > 0) {
-    merged["securitySchemes"] = mergeAbsent(
-      asRecord(components["securitySchemes"]),
-      options.securitySchemes
+function operationsOf(item) {
+  return Object.entries(asRecord(item)).filter(([key]) => OPERATION_METHODS.includes(key));
+}
+function mergeResponses(existing, additions) {
+  const merged = new Map(Object.entries(existing));
+  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"];
+      merged.set(status, { ...current, ...contributed, description: described });
+    }
+  }
+  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]) => {
+    if (!disabled(path)) {
+      return [path, item];
+    }
+    const remaining = Object.fromEntries(
+      Object.entries(asRecord(item)).filter(([key]) => key !== "get")
     );
+    return [path, operationsOf(remaining).length === 0 ? void 0 : remaining];
+  });
+  return Object.fromEntries(kept.filter(([, item]) => item !== void 0));
+}
+function ownRouteSecurity(path, method, options, routes) {
+  if (method !== "get") {
+    return void 0;
+  }
+  if (options.metrics.authToken !== void 0 && routes.isMetrics(path)) {
+    return [{ [METRICS_SCHEME_NAME]: [] }];
   }
-  return { ...document, components: merged };
+  if (options.openapi.security.length > 0 && routes.isHealth(path)) {
+    return [];
+  }
+  return void 0;
+}
+function operationKey(method, path) {
+  return `${method.toUpperCase()} ${path}`;
+}
+function coreResponses(path, options, routes) {
+  const responses = {};
+  if (options.envelope.enabled) {
+    responses["default"] = {
+      description: "Error envelope returned by every failing request.",
+      content: {
+        "application/json": { schema: { $ref: `#/components/schemas/${ERROR_ENVELOPE_SCHEMA}` } }
+      }
+    };
+  }
+  if (routes.isHealth(path)) {
+    responses["200"] = {
+      description: "Aggregated health report.",
+      content: {
+        "application/json": { schema: { $ref: `#/components/schemas/${HEALTH_RESPONSE_SCHEMA}` } }
+      }
+    };
+  }
+  return responses;
+}
+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 describedByLibrary = result["security"] !== void 0;
+    const security = override ?? (describedByLibrary ? void 0 : ownRouteSecurity(path, method, options, routes));
+    if (security !== void 0) {
+      result["security"] = security;
+    }
+  }
+  if (options.openapi.includeCoreSchemas) {
+    result["responses"] = mergeResponses(
+      asRecord(result["responses"]),
+      coreResponses(path, options, routes)
+    );
+  }
+  return result;
+}
+function assertSchemesDeclared(openapi, schemes) {
+  const required = [...openapi.security, ...Object.values(openapi.operationSecurity).flat()];
+  const named = [...new Set(required.flatMap((requirement) => Object.keys(requirement)))];
+  const declared = Object.keys(schemes);
+  const missing = named.filter((name) => !declared.includes(name));
+  if (missing.length === 0) {
+    return;
+  }
+  throw new Error(
+    `[BymaxCoreModule] openapi security names ${missing.length} scheme(s) that the document does not define: ${missing.join(", ")}. Declare them in openapi.securitySchemes, or drop the requirement. The document defines: ${declared.length === 0 ? "(none)" : declared.join(", ")}.`
+  );
+}
+function assertScrapeSchemeIsOurs(openapi, components, contributes) {
+  if (!contributes) {
+    return;
+  }
+  const declaredByConsumer = Object.keys(openapi.securitySchemes).includes(METRICS_SCHEME_NAME);
+  const declaredByDocument = Object.keys(asRecord(components["securitySchemes"])).includes(
+    METRICS_SCHEME_NAME
+  );
+  if (!declaredByConsumer && !declaredByDocument) {
+    return;
+  }
+  throw new Error(
+    `[BymaxCoreModule] the security scheme "${METRICS_SCHEME_NAME}" is reserved: this package contributes it to document the bearer token the scrape endpoint checks, and it is already defined ${declaredByConsumer ? "in openapi.securitySchemes" : "by the generated document"}. Rename yours, or unset metrics.authToken if the endpoint is not protected.`
+  );
+}
+function documentedOperationKeys(paths) {
+  return Object.entries(paths).flatMap(
+    ([path, item]) => operationsOf(item).map(([method]) => operationKey(method, path))
+  );
+}
+function assertOverridesMatch(paths, openapi) {
+  const configured = Object.keys(openapi.operationSecurity);
+  const documented = documentedOperationKeys(paths);
+  const unmatched = configured.filter((key) => !documented.includes(key));
+  if (unmatched.length === 0) {
+    return;
+  }
+  throw new Error(
+    `[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, 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, contributions)
+      ]);
+      return [path, { ...asRecord(item), ...Object.fromEntries(augmented) }];
+    })
+  );
+}
+function augmentDocument(document, options, pathPrefixes = [""], contributions = []) {
+  const { openapi } = options;
+  const components = asRecord(document.components);
+  const merged = new Map(Object.entries(components));
+  if (openapi.includeCoreSchemas) {
+    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]: {
+      type: "http",
+      scheme: "bearer",
+      description: "Bearer token required by the metrics scrape endpoint."
+    }
+  };
+  assertScrapeSchemeIsOurs(openapi, components, options.metrics.authToken !== void 0);
+  const declaredSchemes = mergeAbsent(asRecord(components["securitySchemes"]), {
+    ...openapi.securitySchemes,
+    ...scrapeScheme
+  });
+  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, 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, contributions) };
+  const security = openapi.security.length > 0 && document.security === void 0 ? { security: openapi.security } : {};
+  return { ...document, components: Object.fromEntries(merged), ...paths, ...security };
 }
 
 // src/optional-peer.ts
@@ -234,6 +557,56 @@ function resolveCoreOptions(app) {
     throw new Error(OPTIONS_UNRESOLVED_MESSAGE, { cause });
   }
 }
+function readAppConfig(app) {
+  try {
+    return app.get(core.ApplicationConfig);
+  } catch {
+    return void 0;
+  }
+}
+function versionSegments(versioning) {
+  if (versioning === void 0 || versioning.type !== common.VersioningType.URI) {
+    return [""];
+  }
+  const prefix = versioning.prefix === false ? "" : versioning.prefix ?? "v";
+  const declared = versioning.defaultVersion;
+  if (declared === void 0) {
+    return [""];
+  }
+  const versions = Array.isArray(declared) ? declared : [declared];
+  return versions.map(
+    (version) => version === common.VERSION_NEUTRAL ? "" : `${prefix}${String(version)}`
+  );
+}
+function readPathPrefixes(app) {
+  const config = readAppConfig(app);
+  if (config === void 0) {
+    return [""];
+  }
+  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) {
@@ -243,7 +616,8 @@ function buildConfig(builder, options) {
 }
 async function applyBymaxOpenApi(app) {
   const logger = new common.Logger("BymaxCoreModule");
-  const options = resolveCoreOptions(app).openapi;
+  const resolved = resolveCoreOptions(app);
+  const options = resolved.openapi;
   if (isProductionRuntime()) {
     if (options.suppressedInProduction || options.enabled) {
       logger.warn(
@@ -257,7 +631,16 @@ async function applyBymaxOpenApi(app) {
   }
   const swagger = await loadSwagger();
   const config = buildConfig(new swagger.DocumentBuilder(), options);
-  const document = augmentDocument(swagger.SwaggerModule.createDocument(app, config), options);
+  const handlers = createHandlerIdMap();
+  const generated = swagger.SwaggerModule.createDocument(app, config, {
+    operationIdFactory: recordingOperationIdFactory(handlers, options.operationIdFactory)
+  });
+  const document = augmentDocument(
+    generated,
+    resolved,
+    readPathPrefixes(app),
+    readContributions(app, handlers)
+  );
   swagger.SwaggerModule.setup(options.path, app, document, {
     jsonDocumentUrl: options.jsonPath
   });
@@ -265,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 = 
@@ -30,10 +30,20 @@ interface OpenApiMountOutcome {
  * It is safe to call unconditionally: with the feature disabled, or in
  * production, it mounts nothing, loads no optional peer, and returns why.
  *
+ * Testing this under Jest needs one flag. `@nestjs/swagger` is loaded through a
+ * dynamic `import()`, which is what keeps the peer optional for everyone who
+ * never enables the document — and Jest's module registry cannot service a
+ * dynamic import without `NODE_OPTIONS=--experimental-vm-modules`. Without it,
+ * only the *enabled* path fails, with `dynamic import callback invoked without
+ * --experimental-vm-modules`; the disabled and production paths never reach the
+ * loader and pass either way, which is what makes the omission confusing.
+ *
  * @param app - The created Nest application, not yet listening.
  * @returns What happened: mounted, or skipped with a reason.
- * @throws Error When `BymaxCoreModule` is not registered, or when the feature is
- *   enabled and the optional peer `@nestjs/swagger` is not installed.
+ * @throws Error When `BymaxCoreModule` is not registered, when the feature is
+ *   enabled and the optional peer `@nestjs/swagger` is not installed, or when
+ *   `openapi.operationSecurity` addresses an operation the generated document
+ *   does not contain.
  * @example
  *   const app = await NestFactory.create(AppModule)
  *   await applyBymaxOpenApi(app)
@@ -41,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 };