@sdk-it/spec 0.46.3 → 0.46.5

package/dist/lib/processing-plugins/normalize-security.js

@@ -0,0 +1,142 @@
+import { iterateOperations } from "../for-each-operation.js";
+function normalizeSecurity() {
+  return {
+    name: "normalize-security",
+    process({ spec, report }) {
+      for (const [name, scheme] of Object.entries(
+        spec.components.securitySchemes
+      )) {
+        const message = invalidSecurityScheme(scheme);
+        if (message) {
+          report({
+            code: "invalid-security-scheme",
+            severity: "error",
+            path: `components.securitySchemes.${name}`,
+            message
+          });
+        }
+      }
+      for (const { entry, operation } of iterateOperations(spec)) {
+        operation.security = structuredClone(
+          operation.security ?? spec.security ?? []
+        );
+        const path = `${entry.method.toUpperCase()} ${entry.path}`;
+        for (const requirement of operation.security) {
+          const targets = /* @__PURE__ */ new Map();
+          for (const [name, values] of Object.entries(requirement)) {
+            const scheme = spec.components.securitySchemes[name];
+            if (!scheme) {
+              report({
+                code: "unresolved-security-scheme",
+                severity: "error",
+                path,
+                message: `Security scheme ${name} must be resolved in components.securitySchemes`
+              });
+              continue;
+            }
+            if (scheme.type === "oauth2") {
+              const availableScopes = new Set(
+                Object.values(scheme.flows ?? {}).flatMap(
+                  (flow) => Object.keys(flow?.scopes ?? {})
+                )
+              );
+              for (const scope of values) {
+                if (!availableScopes.has(scope)) {
+                  report({
+                    code: "unknown-oauth-scope",
+                    severity: "error",
+                    path,
+                    message: `OAuth2 scheme ${name} does not declare scope ${scope}`
+                  });
+                }
+              }
+            }
+            const target = credentialTarget(scheme);
+            const existing = target ? targets.get(target) : void 0;
+            if (target && existing) {
+              report({
+                code: "conflicting-security-target",
+                severity: "error",
+                path,
+                message: `Security schemes ${existing} and ${name} both use ${target}`
+              });
+            } else if (target) {
+              targets.set(target, name);
+            }
+          }
+        }
+      }
+    }
+  };
+}
+function invalidSecurityScheme(scheme) {
+  const value = scheme;
+  switch (value.type) {
+    case "apiKey":
+      if (typeof value.name !== "string" || value.name.length === 0) {
+        return "apiKey security schemes require a name";
+      }
+      if (!["header", "query", "cookie"].includes(value.in)) {
+        return "apiKey security schemes require header, query, or cookie in";
+      }
+      return void 0;
+    case "http":
+      return typeof value.scheme === "string" && value.scheme.length > 0 ? void 0 : "HTTP security schemes require a scheme";
+    case "mutualTLS":
+      return void 0;
+    case "openIdConnect":
+      return typeof value.openIdConnectUrl === "string" && value.openIdConnectUrl.length > 0 ? void 0 : "OpenID Connect security schemes require openIdConnectUrl";
+    case "oauth2": {
+      if (!value.flows || typeof value.flows !== "object") {
+        return "OAuth2 security schemes require flows";
+      }
+      const flows = value.flows;
+      const requiredUrls = {
+        implicit: ["authorizationUrl"],
+        password: ["tokenUrl"],
+        clientCredentials: ["tokenUrl"],
+        authorizationCode: ["authorizationUrl", "tokenUrl"],
+        deviceAuthorization: ["deviceAuthorizationUrl", "tokenUrl"]
+      };
+      const configured = Object.entries(requiredUrls).filter(
+        ([flow]) => flows[flow] !== void 0
+      );
+      if (configured.length === 0) {
+        return "OAuth2 security schemes require at least one flow";
+      }
+      for (const [flowName, fields] of configured) {
+        const flow = flows[flowName];
+        if (!flow.scopes || typeof flow.scopes !== "object") {
+          return `OAuth2 ${flowName} flow requires scopes`;
+        }
+        for (const field of fields) {
+          if (typeof flow[field] !== "string" || flow[field].length === 0) {
+            return `OAuth2 ${flowName} flow requires ${field}`;
+          }
+        }
+      }
+      return void 0;
+    }
+    default:
+      return `Unsupported security scheme type ${String(value.type)}`;
+  }
+}
+function credentialTarget(scheme) {
+  switch (scheme.type) {
+    case "apiKey": {
+      if (!scheme.in || !scheme.name) return void 0;
+      const name = scheme.in === "header" ? scheme.name.toLowerCase() : scheme.name;
+      return `${scheme.in}:${name}`;
+    }
+    case "http":
+    case "oauth2":
+    case "openIdConnect":
+      return "header:authorization";
+    case "mutualTLS":
+      return "transport:client-certificate";
+  }
+}
+export {
+  normalizeSecurity
+};
+//# sourceMappingURL=normalize-security.js.map

package/dist/lib/processing-plugins/normalize-security.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/processing-plugins/normalize-security.ts"],
+  "sourcesContent": ["import type { OpenAPISecuritySchemeObject } from '@sdk-it/core';\n\nimport { iterateOperations } from '../for-each-operation.js';\nimport type { ProcessingPlugin } from '../processing.js';\n\nexport function normalizeSecurity(): ProcessingPlugin {\n  return {\n    name: 'normalize-security',\n    process({ spec, report }) {\n      for (const [name, scheme] of Object.entries(\n        spec.components.securitySchemes,\n      )) {\n        const message = invalidSecurityScheme(scheme);\n        if (message) {\n          report({\n            code: 'invalid-security-scheme',\n            severity: 'error',\n            path: `components.securitySchemes.${name}`,\n            message,\n          });\n        }\n      }\n      for (const { entry, operation } of iterateOperations(spec)) {\n        operation.security = structuredClone(\n          operation.security ?? spec.security ?? [],\n        );\n        const path = `${entry.method.toUpperCase()} ${entry.path}`;\n        for (const requirement of operation.security) {\n          const targets = new Map<string, string>();\n          for (const [name, values] of Object.entries(requirement)) {\n            const scheme = spec.components.securitySchemes[name];\n            if (!scheme) {\n              // OpenAPI 3.2 allows external URI references here, but no\n              // generator can emit a credential for one.\n              report({\n                code: 'unresolved-security-scheme',\n                severity: 'error',\n                path,\n                message: `Security scheme ${name} must be resolved in components.securitySchemes`,\n              });\n              continue;\n            }\n            if (scheme.type === 'oauth2') {\n              const availableScopes = new Set(\n                Object.values(scheme.flows ?? {}).flatMap((flow) =>\n                  Object.keys(flow?.scopes ?? {}),\n                ),\n              );\n              for (const scope of values) {\n                if (!availableScopes.has(scope)) {\n                  report({\n                    code: 'unknown-oauth-scope',\n                    severity: 'error',\n                    path,\n                    message: `OAuth2 scheme ${name} does not declare scope ${scope}`,\n                  });\n                }\n              }\n            }\n            const target = credentialTarget(scheme);\n            const existing = target ? targets.get(target) : undefined;\n            if (target && existing) {\n              report({\n                code: 'conflicting-security-target',\n                severity: 'error',\n                path,\n                message: `Security schemes ${existing} and ${name} both use ${target}`,\n              });\n            } else if (target) {\n              targets.set(target, name);\n            }\n          }\n        }\n      }\n    },\n  };\n}\n\nfunction invalidSecurityScheme(\n  scheme: OpenAPISecuritySchemeObject,\n): string | undefined {\n  const value = scheme as OpenAPISecuritySchemeObject & Record<string, unknown>;\n  switch (value.type as string) {\n    case 'apiKey':\n      if (typeof value.name !== 'string' || value.name.length === 0) {\n        return 'apiKey security schemes require a name';\n      }\n      if (!['header', 'query', 'cookie'].includes(value.in as string)) {\n        return 'apiKey security schemes require header, query, or cookie in';\n      }\n      return undefined;\n    case 'http':\n      return typeof value.scheme === 'string' && value.scheme.length > 0\n        ? undefined\n        : 'HTTP security schemes require a scheme';\n    case 'mutualTLS':\n      return undefined;\n    case 'openIdConnect':\n      return typeof value.openIdConnectUrl === 'string' &&\n        value.openIdConnectUrl.length > 0\n        ? undefined\n        : 'OpenID Connect security schemes require openIdConnectUrl';\n    case 'oauth2': {\n      if (!value.flows || typeof value.flows !== 'object') {\n        return 'OAuth2 security schemes require flows';\n      }\n      const flows = value.flows as Record<\n        string,\n        Record<string, unknown> | undefined\n      >;\n      const requiredUrls: Record<string, string[]> = {\n        implicit: ['authorizationUrl'],\n        password: ['tokenUrl'],\n        clientCredentials: ['tokenUrl'],\n        authorizationCode: ['authorizationUrl', 'tokenUrl'],\n        deviceAuthorization: ['deviceAuthorizationUrl', 'tokenUrl'],\n      };\n      const configured = Object.entries(requiredUrls).filter(\n        ([flow]) => flows[flow] !== undefined,\n      );\n      if (configured.length === 0) {\n        return 'OAuth2 security schemes require at least one flow';\n      }\n      for (const [flowName, fields] of configured) {\n        const flow = flows[flowName]!;\n        if (!flow.scopes || typeof flow.scopes !== 'object') {\n          return `OAuth2 ${flowName} flow requires scopes`;\n        }\n        for (const field of fields) {\n          if (typeof flow[field] !== 'string' || flow[field].length === 0) {\n            return `OAuth2 ${flowName} flow requires ${field}`;\n          }\n        }\n      }\n      return undefined;\n    }\n    default:\n      return `Unsupported security scheme type ${String(value.type)}`;\n  }\n}\n\nfunction credentialTarget(\n  scheme: OpenAPISecuritySchemeObject,\n): string | undefined {\n  switch (scheme.type) {\n    case 'apiKey': {\n      if (!scheme.in || !scheme.name) return undefined;\n      const name =\n        scheme.in === 'header' ? scheme.name.toLowerCase() : scheme.name;\n      return `${scheme.in}:${name}`;\n    }\n    case 'http':\n    case 'oauth2':\n    case 'openIdConnect':\n      return 'header:authorization';\n    case 'mutualTLS':\n      return 'transport:client-certificate';\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/lib/processing-plugins/resolve-security-scheme-uris.d.ts

@@ -0,0 +1,9 @@
+import type { ProcessingPlugin } from '../processing.js';
+/**
+ * OpenAPI 3.2 lets a security requirement key be a URI of a Security Scheme
+ * Object instead of a `components.securitySchemes` name. Generators key
+ * credentials by scheme name, so each URI is fetched, registered locally, and
+ * the requirement rewritten to point at the registered name.
+ */
+export declare function resolveSecuritySchemeUris(): ProcessingPlugin;
+//# sourceMappingURL=resolve-security-scheme-uris.d.ts.map

package/dist/lib/processing-plugins/resolve-security-scheme-uris.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-security-scheme-uris.d.ts","sourceRoot":"","sources":["../../../src/lib/processing-plugins/resolve-security-scheme-uris.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGzD;;;;;GAKG;AACH,wBAAgB,yBAAyB,IAAI,gBAAgB,CAkD5D"}

package/dist/lib/processing-plugins/resolve-security-scheme-uris.js

@@ -0,0 +1,139 @@
+import { fileURLToPath } from "node:url";
+import {
+  followRef,
+  isRef
+} from "@sdk-it/core";
+import { iterateOperations } from "../for-each-operation.js";
+import { loadFile } from "../loaders/load-spec.js";
+function resolveSecuritySchemeUris() {
+  return {
+    name: "resolve-security-scheme-uris",
+    async process({ spec, report }) {
+      const requirements = collectRequirements(spec);
+      const uris = new Set(
+        requirements.flatMap((requirement) => Object.keys(requirement)).filter(
+          (key) => !spec.components.securitySchemes[key] && isUriKey(key)
+        )
+      );
+      if (!uris.size) {
+        return;
+      }
+      const documents = /* @__PURE__ */ new Map();
+      const registered = /* @__PURE__ */ new Map();
+      for (const uri of uris) {
+        try {
+          const scheme = await resolveScheme(uri, spec, documents);
+          const [alias] = Object.entries(spec.components.securitySchemes).find(
+            ([, registeredScheme]) => registeredScheme === scheme
+          ) ?? [];
+          const name = alias ?? availableName(spec, schemeName(uri));
+          spec.components.securitySchemes[name] = scheme;
+          registered.set(uri, name);
+        } catch (error) {
+          report({
+            code: "unresolvable-security-scheme-uri",
+            severity: "error",
+            path: uri,
+            message: `Could not resolve security scheme URI ${uri}: ${error instanceof Error ? error.message : String(error)}`
+          });
+        }
+      }
+      for (const requirement of requirements) {
+        for (const [uri, name] of registered) {
+          if (Object.hasOwn(requirement, uri)) {
+            requirement[name] = requirement[uri];
+            delete requirement[uri];
+          }
+        }
+      }
+    }
+  };
+}
+function collectRequirements(spec) {
+  const requirements = [...spec.security ?? []];
+  for (const { operation } of iterateOperations(spec)) {
+    requirements.push(...operation.security ?? []);
+  }
+  return requirements;
+}
+function isUriKey(key) {
+  return !/^[a-zA-Z0-9._-]+$/.test(key);
+}
+async function resolveScheme(uri, spec, documents) {
+  const [location, fragment] = splitFragment(uri);
+  const document = location ? await loadDocument(location, spec, documents) : spec;
+  let scheme = fragment ? readPointer(document, fragment) : document;
+  if (isRef(scheme)) {
+    scheme = followRef(document, scheme.$ref);
+  }
+  if (scheme === null || typeof scheme !== "object" || typeof scheme.type !== "string") {
+    return Promise.reject(
+      new Error("the target is not a Security Scheme Object")
+    );
+  }
+  return scheme;
+}
+function loadDocument(location, spec, documents) {
+  const base = spec.$self;
+  if (!base && !isAbsolute(location)) {
+    return Promise.reject(
+      new Error(
+        "the document declares no $self, so a relative URI has no base to resolve against"
+      )
+    );
+  }
+  const url = new URL(location, base);
+  if (url.href === base) {
+    return Promise.resolve(spec);
+  }
+  let pending = documents.get(url.href);
+  if (!pending) {
+    pending = loadFile(
+      url.protocol === "file:" ? fileURLToPath(url) : url.href
+    );
+    documents.set(url.href, pending);
+  }
+  return pending;
+}
+function isAbsolute(location) {
+  return URL.canParse(location);
+}
+function splitFragment(uri) {
+  const index = uri.indexOf("#");
+  return index === -1 ? [uri, void 0] : [uri.slice(0, index), uri.slice(index + 1)];
+}
+function readPointer(document, fragment) {
+  let current = document;
+  for (const segment of fragment.split("/")) {
+    if (!segment) {
+      continue;
+    }
+    const key = decodeURIComponent(segment).replaceAll("~1", "/").replaceAll("~0", "~");
+    if (current === null || typeof current !== "object" || !(key in current)) {
+      throw new Error(`no value at pointer #${fragment}`);
+    }
+    current = current[key];
+  }
+  return current;
+}
+function schemeName(uri) {
+  const [location, fragment] = splitFragment(uri);
+  const candidate = lastSegment(fragment ?? "") ?? lastSegment(location.split("?")[0])?.replace(/\.(json|ya?ml)$/i, "");
+  const sanitized = (candidate ?? "").replace(/[^a-zA-Z0-9._-]/g, "");
+  return sanitized || "externalSecurityScheme";
+}
+function lastSegment(value) {
+  return value.split("/").filter(Boolean).at(-1);
+}
+function availableName(spec, candidate) {
+  let name = candidate;
+  let suffix = 2;
+  while (spec.components.securitySchemes[name]) {
+    name = `${candidate}${suffix++}`;
+  }
+  return name;
+}
+export {
+  resolveSecuritySchemeUris
+};
+//# sourceMappingURL=resolve-security-scheme-uris.js.map

package/dist/lib/processing-plugins/resolve-security-scheme-uris.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/processing-plugins/resolve-security-scheme-uris.ts"],
+  "sourcesContent": ["import { fileURLToPath } from 'node:url';\nimport type { SecurityRequirementObject } from 'openapi3-ts/oas31';\n\nimport {\n  type OpenAPISecuritySchemeObject,\n  followRef,\n  isRef,\n} from '@sdk-it/core';\n\nimport { iterateOperations } from '../for-each-operation.js';\nimport { loadFile } from '../loaders/load-spec.js';\nimport type { ProcessingPlugin } from '../processing.js';\nimport type { IR } from '../types.js';\n\n/**\n * OpenAPI 3.2 lets a security requirement key be a URI of a Security Scheme\n * Object instead of a `components.securitySchemes` name. Generators key\n * credentials by scheme name, so each URI is fetched, registered locally, and\n * the requirement rewritten to point at the registered name.\n */\nexport function resolveSecuritySchemeUris(): ProcessingPlugin {\n  return {\n    name: 'resolve-security-scheme-uris',\n    async process({ spec, report }) {\n      const requirements = collectRequirements(spec);\n      const uris = new Set(\n        requirements\n          .flatMap((requirement) => Object.keys(requirement))\n          .filter(\n            (key) => !spec.components.securitySchemes[key] && isUriKey(key),\n          ),\n      );\n      if (!uris.size) {\n        return;\n      }\n\n      const documents = new Map<string, Promise<unknown>>();\n      const registered = new Map<string, string>();\n      for (const uri of uris) {\n        try {\n          const scheme = await resolveScheme(uri, spec, documents);\n          // A same-document pointer lands on an already registered object;\n          // reuse its name instead of registering a second copy.\n          const [alias] =\n            Object.entries(spec.components.securitySchemes).find(\n              ([, registeredScheme]) => registeredScheme === scheme,\n            ) ?? [];\n          const name = alias ?? availableName(spec, schemeName(uri));\n          spec.components.securitySchemes[name] = scheme;\n          registered.set(uri, name);\n        } catch (error) {\n          report({\n            code: 'unresolvable-security-scheme-uri',\n            severity: 'error',\n            path: uri,\n            message: `Could not resolve security scheme URI ${uri}: ${error instanceof Error ? error.message : String(error)}`,\n          });\n        }\n      }\n\n      for (const requirement of requirements) {\n        for (const [uri, name] of registered) {\n          if (Object.hasOwn(requirement, uri)) {\n            requirement[name] = requirement[uri];\n            delete requirement[uri];\n          }\n        }\n      }\n    },\n  };\n}\n\nfunction collectRequirements(spec: IR) {\n  const requirements: SecurityRequirementObject[] = [...(spec.security ?? [])];\n  for (const { operation } of iterateOperations(spec)) {\n    requirements.push(...(operation.security ?? []));\n  }\n  return requirements;\n}\n\n/**\n * Component keys are limited to `^[a-zA-Z0-9._-]+$`, so anything else can only\n * be a URI. A bare `auth.yaml` stays a name \u2014 treating it as a document would\n * turn a typo into a file read.\n */\nfunction isUriKey(key: string) {\n  return !/^[a-zA-Z0-9._-]+$/.test(key);\n}\n\nasync function resolveScheme(\n  uri: string,\n  spec: IR,\n  documents: Map<string, Promise<unknown>>,\n): Promise<OpenAPISecuritySchemeObject> {\n  const [location, fragment] = splitFragment(uri);\n  const document = location\n    ? await loadDocument(location, spec, documents)\n    : spec;\n  let scheme = fragment ? readPointer(document, fragment) : document;\n  if (isRef(scheme)) {\n    scheme = followRef(document as never, scheme.$ref);\n  }\n  if (\n    scheme === null ||\n    typeof scheme !== 'object' ||\n    typeof (scheme as { type?: unknown }).type !== 'string'\n  ) {\n    return Promise.reject(\n      new Error('the target is not a Security Scheme Object'),\n    );\n  }\n  return scheme as OpenAPISecuritySchemeObject;\n}\n\nfunction loadDocument(\n  location: string,\n  spec: IR,\n  documents: Map<string, Promise<unknown>>,\n) {\n  const base = spec.$self;\n  if (!base && !isAbsolute(location)) {\n    return Promise.reject(\n      new Error(\n        'the document declares no $self, so a relative URI has no base to resolve against',\n      ),\n    );\n  }\n  const url = new URL(location, base);\n  if (url.href === base) {\n    return Promise.resolve(spec);\n  }\n  let pending = documents.get(url.href);\n  if (!pending) {\n    pending = loadFile(\n      url.protocol === 'file:' ? fileURLToPath(url) : url.href,\n    );\n    documents.set(url.href, pending);\n  }\n  return pending;\n}\n\nfunction isAbsolute(location: string) {\n  return URL.canParse(location);\n}\n\nfunction splitFragment(uri: string): [string, string | undefined] {\n  const index = uri.indexOf('#');\n  return index === -1\n    ? [uri, undefined]\n    : [uri.slice(0, index), uri.slice(index + 1)];\n}\n\nfunction readPointer(document: unknown, fragment: string) {\n  let current: unknown = document;\n  for (const segment of fragment.split('/')) {\n    if (!segment) {\n      continue;\n    }\n    const key = decodeURIComponent(segment)\n      .replaceAll('~1', '/')\n      .replaceAll('~0', '~');\n    if (\n      current === null ||\n      typeof current !== 'object' ||\n      !(key in (current as object))\n    ) {\n      throw new Error(`no value at pointer #${fragment}`);\n    }\n    current = (current as Record<string, unknown>)[key];\n  }\n  return current;\n}\n\nfunction schemeName(uri: string) {\n  const [location, fragment] = splitFragment(uri);\n  const candidate =\n    lastSegment(fragment ?? '') ??\n    lastSegment(location.split('?')[0])?.replace(/\\.(json|ya?ml)$/i, '');\n  const sanitized = (candidate ?? '').replace(/[^a-zA-Z0-9._-]/g, '');\n  return sanitized || 'externalSecurityScheme';\n}\n\nfunction lastSegment(value: string) {\n  return value.split('/').filter(Boolean).at(-1);\n}\n\nfunction availableName(spec: IR, candidate: string) {\n  let name = candidate;\n  let suffix = 2;\n  while (spec.components.securitySchemes[name]) {\n    name = `${candidate}${suffix++}`;\n  }\n  return name;\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/lib/processing.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/processing.ts"],
-  "sourcesContent": ["import type { OpenAPIObject } from 'openapi3-ts/oas31';\n\nimport {\n  type GenerateSdkConfig,\n  coeraceConfig as coerceConfig,\n} from './options.js';\nimport type { IR } from './types.js';\n\nexport type ProcessingDiagnosticSeverity = 'info' | 'warning' | 'error';\n\nexport interface ProcessingDiagnostic {\n  plugin: string;\n  severity: ProcessingDiagnosticSeverity;\n  code: string;\n  message: string;\n  path?: string;\n}\n\nexport type ProcessingOptions = Omit<ReturnType<typeof coerceConfig>, 'spec'>;\n\nexport interface ProcessingContext {\n  spec: IR;\n  options: ProcessingOptions;\n  diagnostics: ProcessingDiagnostic[];\n  signal?: AbortSignal;\n  report(\n    diagnostic: Omit<ProcessingDiagnostic, 'plugin'>,\n  ): ProcessingDiagnostic;\n}\n\nexport interface ProcessingPlugin {\n  name: string;\n  process(context: ProcessingContext): void | Promise<void>;\n}\n\nexport interface ProcessSpecConfig extends GenerateSdkConfig {\n  plugins: readonly ProcessingPlugin[];\n  signal?: AbortSignal;\n  onDiagnostic?: (diagnostic: ProcessingDiagnostic) => void;\n}\n\nexport interface ProcessingResult {\n  spec: IR;\n  diagnostics: ProcessingDiagnostic[];\n}\n\nexport async function processSpec(\n  config: ProcessSpecConfig,\n): Promise<ProcessingResult> {\n  const { plugins, signal, onDiagnostic, ...generateConfig } = config;\n  signal?.throwIfAborted();\n  const coerced = coerceConfig({\n    ...generateConfig,\n    spec: structuredClone(generateConfig.spec) as OpenAPIObject,\n  });\n  const { spec, ...options } = coerced;\n  const diagnostics: ProcessingDiagnostic[] = [];\n  const pluginNames = plugins.map((plugin) => plugin.name);\n  const configuration = JSON.stringify({\n    pagination: options.pagination,\n    responses: options.responses,\n  });\n\n  for (const plugin of plugins) {\n    signal?.throwIfAborted();\n    const context: ProcessingContext = {\n      spec,\n      options,\n      diagnostics,\n      signal,\n      report(diagnostic) {\n        const reported = { ...diagnostic, plugin: plugin.name };\n        diagnostics.push(reported);\n        onDiagnostic?.(reported);\n        return reported;\n      },\n    };\n    await plugin.process(context);\n    signal?.throwIfAborted();\n  }\n\n  spec['x-sdk-processing'] = { plugins: pluginNames, configuration };\n\n  return { spec, diagnostics };\n}\n"],
+  "sourcesContent": ["import type { OpenAPIDocument } from '@sdk-it/core';\n\nimport {\n  type GenerateSdkConfig,\n  coeraceConfig as coerceConfig,\n} from './options.js';\nimport type { IR } from './types.js';\n\nexport type ProcessingDiagnosticSeverity = 'info' | 'warning' | 'error';\n\nexport interface ProcessingDiagnostic {\n  plugin: string;\n  severity: ProcessingDiagnosticSeverity;\n  code: string;\n  message: string;\n  path?: string;\n}\n\nexport type ProcessingOptions = Omit<ReturnType<typeof coerceConfig>, 'spec'>;\n\nexport interface ProcessingContext {\n  spec: IR;\n  options: ProcessingOptions;\n  diagnostics: ProcessingDiagnostic[];\n  signal?: AbortSignal;\n  report(\n    diagnostic: Omit<ProcessingDiagnostic, 'plugin'>,\n  ): ProcessingDiagnostic;\n}\n\nexport interface ProcessingPlugin {\n  name: string;\n  process(context: ProcessingContext): void | Promise<void>;\n}\n\nexport interface ProcessSpecConfig extends GenerateSdkConfig {\n  plugins: readonly ProcessingPlugin[];\n  signal?: AbortSignal;\n  onDiagnostic?: (diagnostic: ProcessingDiagnostic) => void;\n}\n\nexport interface ProcessingResult {\n  spec: IR;\n  diagnostics: ProcessingDiagnostic[];\n}\n\nexport async function processSpec(\n  config: ProcessSpecConfig,\n): Promise<ProcessingResult> {\n  const { plugins, signal, onDiagnostic, ...generateConfig } = config;\n  signal?.throwIfAborted();\n  const coerced = coerceConfig({\n    ...generateConfig,\n    spec: structuredClone(generateConfig.spec) as OpenAPIDocument,\n  });\n  const { spec, ...options } = coerced;\n  const diagnostics: ProcessingDiagnostic[] = [];\n  const pluginNames = plugins.map((plugin) => plugin.name);\n  const configuration = JSON.stringify({\n    pagination: options.pagination,\n    responses: options.responses,\n  });\n\n  for (const plugin of plugins) {\n    signal?.throwIfAborted();\n    const context: ProcessingContext = {\n      spec,\n      options,\n      diagnostics,\n      signal,\n      report(diagnostic) {\n        const reported = { ...diagnostic, plugin: plugin.name };\n        diagnostics.push(reported);\n        onDiagnostic?.(reported);\n        return reported;\n      },\n    };\n    await plugin.process(context);\n    signal?.throwIfAborted();\n  }\n\n  spec['x-sdk-processing'] = { plugins: pluginNames, configuration };\n\n  return { spec, diagnostics };\n}\n"],
   "mappings": "AAEA;AAAA,EAEE,iBAAiB;AAAA,OACZ;AAyCP,eAAsB,YACpB,QAC2B;AAC3B,QAAM,EAAE,SAAS,QAAQ,cAAc,GAAG,eAAe,IAAI;AAC7D,UAAQ,eAAe;AACvB,QAAM,UAAU,aAAa;AAAA,IAC3B,GAAG;AAAA,IACH,MAAM,gBAAgB,eAAe,IAAI;AAAA,EAC3C,CAAC;AACD,QAAM,EAAE,MAAM,GAAG,QAAQ,IAAI;AAC7B,QAAM,cAAsC,CAAC;AAC7C,QAAM,cAAc,QAAQ,IAAI,CAAC,WAAW,OAAO,IAAI;AACvD,QAAM,gBAAgB,KAAK,UAAU;AAAA,IACnC,YAAY,QAAQ;AAAA,IACpB,WAAW,QAAQ;AAAA,EACrB,CAAC;AAED,aAAW,UAAU,SAAS;AAC5B,YAAQ,eAAe;AACvB,UAAM,UAA6B;AAAA,MACjC;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA,OAAO,YAAY;AACjB,cAAM,WAAW,EAAE,GAAG,YAAY,QAAQ,OAAO,KAAK;AACtD,oBAAY,KAAK,QAAQ;AACzB,uBAAe,QAAQ;AACvB,eAAO;AAAA,MACT;AAAA,IACF;AACA,UAAM,OAAO,QAAQ,OAAO;AAC5B,YAAQ,eAAe;AAAA,EACzB;AAEA,OAAK,kBAAkB,IAAI,EAAE,SAAS,aAAa,cAAc;AAEjE,SAAO,EAAE,MAAM,YAAY;AAC7B;",
   "names": []
 }

package/dist/lib/sidebar.js

@@ -2,7 +2,7 @@ import { camelcase } from "stringcase";
 import { notNullOrUndefined } from "@sdk-it/core/file-system.js";
 import { forEachOperation } from "./for-each-operation.js";
 function toSidebar(spec) {
-  const sidebar = spec["x-docs"];
+  const sidebar = [...spec["x-docs"]];
   for (const tagGroup of spec["x-tagGroups"]) {
     sidebar.push({
       id: camelcase(tagGroup.name),

package/dist/lib/sidebar.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/sidebar.ts"],
-  "sourcesContent": ["import { camelcase } from 'stringcase';\n\nimport { notNullOrUndefined } from '@sdk-it/core/file-system.js';\n\nimport { forEachOperation } from './for-each-operation.js';\nimport type { IR } from './types.js';\n\nexport type ChildNavItem = {\n  id: string;\n  title: string;\n  url: string;\n};\n\nexport type NavItem = {\n  id: string;\n  title: string;\n  description?: string;\n  url?: string;\n  items?: ChildNavItem[];\n  content?: string; // Markdown content\n};\n\nexport type CategoryItem = {\n  id: string;\n  category: string;\n  description?: string;\n  items: NavItem[];\n};\n\nexport type SidebarData = CategoryItem[];\n\nexport interface TagGroups {\n  name: string;\n  tags: string[];\n}\n\nexport function toSidebar(spec: IR) {\n  const sidebar: SidebarData = spec['x-docs'];\n  for (const tagGroup of spec['x-tagGroups']) {\n    sidebar.push({\n      id: camelcase(tagGroup.name),\n      category: tagGroup.name,\n      items: tagGroup.tags.map((tag) => {\n        const tagSpec = spec.tags?.find((t) => t.name === tag);\n        return {\n          id: crypto.randomUUID(),\n          description: tagSpec?.description,\n          title: tagSpec\n            ? tagSpec['x-displayName'] || tagSpec.name || tag\n            : tag,\n          items: forEachOperation(spec, (entry, operation) => {\n            if (operation.tags.includes(tag)) {\n              const title = operation.summary || operation.operationId;\n              return {\n                id: operation.operationId,\n                title,\n                url: `${camelcase(tag)}/${camelcase(operation.operationId)}`,\n              };\n            }\n            return null;\n          }).filter(notNullOrUndefined),\n        };\n      }),\n    });\n  }\n  return sidebar;\n}\n"],
-  "mappings": "AAAA,SAAS,iBAAiB;AAE1B,SAAS,0BAA0B;AAEnC,SAAS,wBAAwB;AAgC1B,SAAS,UAAU,MAAU;AAClC,QAAM,UAAuB,KAAK,QAAQ;AAC1C,aAAW,YAAY,KAAK,aAAa,GAAG;AAC1C,YAAQ,KAAK;AAAA,MACX,IAAI,UAAU,SAAS,IAAI;AAAA,MAC3B,UAAU,SAAS;AAAA,MACnB,OAAO,SAAS,KAAK,IAAI,CAAC,QAAQ;AAChC,cAAM,UAAU,KAAK,MAAM,KAAK,CAAC,MAAM,EAAE,SAAS,GAAG;AACrD,eAAO;AAAA,UACL,IAAI,OAAO,WAAW;AAAA,UACtB,aAAa,SAAS;AAAA,UACtB,OAAO,UACH,QAAQ,eAAe,KAAK,QAAQ,QAAQ,MAC5C;AAAA,UACJ,OAAO,iBAAiB,MAAM,CAAC,OAAO,cAAc;AAClD,gBAAI,UAAU,KAAK,SAAS,GAAG,GAAG;AAChC,oBAAM,QAAQ,UAAU,WAAW,UAAU;AAC7C,qBAAO;AAAA,gBACL,IAAI,UAAU;AAAA,gBACd;AAAA,gBACA,KAAK,GAAG,UAAU,GAAG,CAAC,IAAI,UAAU,UAAU,WAAW,CAAC;AAAA,cAC5D;AAAA,YACF;AACA,mBAAO;AAAA,UACT,CAAC,EAAE,OAAO,kBAAkB;AAAA,QAC9B;AAAA,MACF,CAAC;AAAA,IACH,CAAC;AAAA,EACH;AACA,SAAO;AACT;",
+  "sourcesContent": ["import { camelcase } from 'stringcase';\n\nimport { notNullOrUndefined } from '@sdk-it/core/file-system.js';\n\nimport { forEachOperation } from './for-each-operation.js';\nimport type { IR } from './types.js';\n\nexport type ChildNavItem = {\n  id: string;\n  title: string;\n  url: string;\n};\n\nexport type NavItem = {\n  id: string;\n  title: string;\n  description?: string;\n  url?: string;\n  items?: ChildNavItem[];\n  content?: string; // Markdown content\n};\n\nexport type CategoryItem = {\n  id: string;\n  category: string;\n  description?: string;\n  items: NavItem[];\n};\n\nexport type SidebarData = CategoryItem[];\n\nexport interface TagGroups {\n  name: string;\n  tags: string[];\n}\n\nexport function toSidebar(spec: IR) {\n  const sidebar: SidebarData = [...spec['x-docs']];\n  for (const tagGroup of spec['x-tagGroups']) {\n    sidebar.push({\n      id: camelcase(tagGroup.name),\n      category: tagGroup.name,\n      items: tagGroup.tags.map((tag) => {\n        const tagSpec = spec.tags?.find((t) => t.name === tag);\n        return {\n          id: crypto.randomUUID(),\n          description: tagSpec?.description,\n          title: tagSpec\n            ? tagSpec['x-displayName'] || tagSpec.name || tag\n            : tag,\n          items: forEachOperation(spec, (entry, operation) => {\n            if (operation.tags.includes(tag)) {\n              const title = operation.summary || operation.operationId;\n              return {\n                id: operation.operationId,\n                title,\n                url: `${camelcase(tag)}/${camelcase(operation.operationId)}`,\n              };\n            }\n            return null;\n          }).filter(notNullOrUndefined),\n        };\n      }),\n    });\n  }\n  return sidebar;\n}\n"],
+  "mappings": "AAAA,SAAS,iBAAiB;AAE1B,SAAS,0BAA0B;AAEnC,SAAS,wBAAwB;AAgC1B,SAAS,UAAU,MAAU;AAClC,QAAM,UAAuB,CAAC,GAAG,KAAK,QAAQ,CAAC;AAC/C,aAAW,YAAY,KAAK,aAAa,GAAG;AAC1C,YAAQ,KAAK;AAAA,MACX,IAAI,UAAU,SAAS,IAAI;AAAA,MAC3B,UAAU,SAAS;AAAA,MACnB,OAAO,SAAS,KAAK,IAAI,CAAC,QAAQ;AAChC,cAAM,UAAU,KAAK,MAAM,KAAK,CAAC,MAAM,EAAE,SAAS,GAAG;AACrD,eAAO;AAAA,UACL,IAAI,OAAO,WAAW;AAAA,UACtB,aAAa,SAAS;AAAA,UACtB,OAAO,UACH,QAAQ,eAAe,KAAK,QAAQ,QAAQ,MAC5C;AAAA,UACJ,OAAO,iBAAiB,MAAM,CAAC,OAAO,cAAc;AAClD,gBAAI,UAAU,KAAK,SAAS,GAAG,GAAG;AAChC,oBAAM,QAAQ,UAAU,WAAW,UAAU;AAC7C,qBAAO;AAAA,gBACL,IAAI,UAAU;AAAA,gBACd;AAAA,gBACA,KAAK,GAAG,UAAU,GAAG,CAAC,IAAI,UAAU,UAAU,WAAW,CAAC;AAAA,cAC5D;AAAA,YACF;AACA,mBAAO;AAAA,UACT,CAAC,EAAE,OAAO,kBAAkB;AAAA,QAC9B;AAAA,MACF,CAAC;AAAA,IACH,CAAC;AAAA,EACH;AACA,SAAO;AACT;",
   "names": []
 }

package/dist/lib/types.d.ts

@@ -1,21 +1,24 @@
-import type { ComponentsObject, MediaTypeObject, OpenAPIObject, OperationObject, ParameterObject, PathsObject, ReferenceObject, RequestBodyObject, ResponseObject, SchemaObject, SecuritySchemeObject, ServerObject, TagObject } from 'openapi3-ts/oas31';
+import type { MediaTypeObject, OperationObject, ParameterObject, PathsObject, ReferenceObject, RequestBodyObject, ResponseObject, SchemaObject, ServerObject, TagObject } from 'openapi3-ts/oas31';
+import type { OpenAPIComponentsObject, OpenAPIDocument, OpenAPISecuritySchemeObject } from '@sdk-it/core';
+import type { SdkDoc } from './overview-docs/types.js';
 import type { PaginationGuess } from './pagination/guess-pagination.js';
 import type { SidebarData, TagGroups } from './sidebar.js';
-export interface IR extends OpenAPIObject {
+export type IR = Omit<OpenAPIDocument, 'components' | 'paths' | 'servers' | 'tags'> & {
     servers: ServerObject[];
     'x-sdk-processing'?: {
         plugins: string[];
         configuration: string;
     };
     'x-docs': SidebarData;
+    'x-sdks': SdkDoc[];
     'x-tagGroups': TagGroups[];
-    components: Omit<ComponentsObject, 'schemas'> & {
+    components: Omit<OpenAPIComponentsObject, 'schemas' | 'securitySchemes'> & {
         schemas: Record<string, SchemaObject | ReferenceObject>;
-        securitySchemes: Record<string, SecuritySchemeObject>;
+        securitySchemes: Record<string, OpenAPISecuritySchemeObject>;
     };
     paths: PathsObject;
     tags: TagObject[];
-}
+};
 export interface OurRequestBodyObject extends RequestBodyObject {
     content: Record<string, Omit<MediaTypeObject, 'schema'> & {
         schema: ReferenceObject;

package/dist/lib/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,eAAe,EACf,eAAe,EACf,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,oBAAoB,EACpB,YAAY,EACZ,SAAS,EACV,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE3D,MAAM,WAAW,EAAG,SAAQ,aAAa;IACvC,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,kBAAkB,CAAC,EAAE;QACnB,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,QAAQ,EAAE,WAAW,CAAC;IACtB,aAAa,EAAE,SAAS,EAAE,CAAC;IAC3B,UAAU,EAAE,IAAI,CAAC,gBAAgB,EAAE,SAAS,CAAC,GAAG;QAC9C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,eAAe,CAAC,CAAC;QACxD,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;KACvD,CAAC;IACF,KAAK,EAAE,WAAW,CAAC;IACnB,IAAI,EAAE,SAAS,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,OAAO,EAAE,MAAM,CACb,MAAM,EACN,IAAI,CAAC,eAAe,EAAE,QAAQ,CAAC,GAAG;QAAE,MAAM,EAAE,eAAe,CAAA;KAAE,CAC9D,CAAC;CACH;AAED,MAAM,MAAM,oBAAoB,GAAG,IAAI,CACrC,eAAe,EACf,aAAa,GAAG,MAAM,GAAG,YAAY,GAAG,WAAW,GAAG,aAAa,GAAG,MAAM,CAC7E,GAAG;IACF,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IACtB,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CACf,MAAM,EACN,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,GAAG;QAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;KAC1C,CACF,CAAC;IACF,WAAW,EAAE,oBAAoB,CAAC;CACnC,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AACD,MAAM,MAAM,SAAS,GAAG;IACtB,KAAK,EAAE,cAAc,CAAC;IACtB,SAAS,EAAE,oBAAoB,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,eAAe,GAAG;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EACf,eAAe,EACf,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,SAAS,EACV,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EACV,uBAAuB,EACvB,eAAe,EACf,2BAA2B,EAC5B,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE3D,MAAM,MAAM,EAAE,GAAG,IAAI,CACnB,eAAe,EACf,YAAY,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAC5C,GAAG;IACF,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,kBAAkB,CAAC,EAAE;QACnB,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,QAAQ,EAAE,WAAW,CAAC;IACtB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,aAAa,EAAE,SAAS,EAAE,CAAC;IAC3B,UAAU,EAAE,IAAI,CAAC,uBAAuB,EAAE,SAAS,GAAG,iBAAiB,CAAC,GAAG;QACzE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,eAAe,CAAC,CAAC;QACxD,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,2BAA2B,CAAC,CAAC;KAC9D,CAAC;IACF,KAAK,EAAE,WAAW,CAAC;IACnB,IAAI,EAAE,SAAS,EAAE,CAAC;CACnB,CAAC;AAEF,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,OAAO,EAAE,MAAM,CACb,MAAM,EACN,IAAI,CAAC,eAAe,EAAE,QAAQ,CAAC,GAAG;QAAE,MAAM,EAAE,eAAe,CAAA;KAAE,CAC9D,CAAC;CACH;AAED,MAAM,MAAM,oBAAoB,GAAG,IAAI,CACrC,eAAe,EACf,aAAa,GAAG,MAAM,GAAG,YAAY,GAAG,WAAW,GAAG,aAAa,GAAG,MAAM,CAC7E,GAAG;IACF,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IACtB,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CACf,MAAM,EACN,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,GAAG;QAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;KAC1C,CACF,CAAC;IACF,WAAW,EAAE,oBAAoB,CAAC;CACnC,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AACD,MAAM,MAAM,SAAS,GAAG;IACtB,KAAK,EAAE,cAAc,CAAC;IACtB,SAAS,EAAE,oBAAoB,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,eAAe,GAAG;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdk-it/spec",
-  "version": "0.46.3",
+  "version": "0.46.5",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -27,7 +27,7 @@
     "!**/*.test.*"
   ],
   "dependencies": {
-    "@sdk-it/core": "0.46.3",
+    "@sdk-it/core": "0.46.5",
     "openapi3-ts": "4.5.0",
     "pluralize": "^8.0.0",
     "stringcase": "^4.3.1",

package/dist/lib/overview-docs/doc-templates.d.ts

@@ -1,51 +0,0 @@
-export declare const docTemplates: {
-    readonly servers: {
-        readonly sectionTitle: "API Server";
-        readonly description: "The following {count} {isAre} available for this API:";
-    };
-    readonly authMethods: {
-        readonly sectionTitle: "Available Authentication Method";
-        readonly introText: "This API provides secure access through {countText} authentication {method}. Below you'll find details about {articleCount} available authentication {scheme} and how to use {pronoun}.";
-        readonly noAuthText: "This API does not require authentication.";
-    };
-    readonly apiClients: {
-        readonly sectionTitle: "Official API Client";
-        readonly description: "{apiTitle} provides official client SDK{sdkPlural} for {languageText}. We recommend using {clientText} to interact with all stable endpoints. You can find {pronoun} here:";
-    };
-    readonly needHelp: {
-        readonly sectionTitle: "Need Help?";
-    };
-};
-interface CountTextOptions {
-    count: number;
-    word: string;
-    includeCount?: boolean;
-}
-export declare function getCountText(options: CountTextOptions): string;
-export declare function getPronoun(count: number, type?: 'subject' | 'object'): string;
-export declare function getArticle(count: number, word: string): string;
-export declare function getIsAre(count: number): string;
-export declare function getThisThese(count: number): string;
-export declare function processTemplate(template: string, replacements: Record<string, string | number>): string;
-export declare function getServerText(count: number): {
-    title: string;
-    description: string;
-};
-export declare function getAuthMethodText(count: number): {
-    title: string;
-    intro: string;
-};
-export declare function getApiClientText(count: number, apiTitle: string): {
-    title: string;
-    description: string;
-};
-export declare function getAuthText(count: number): {
-    title: string;
-    intro: string;
-};
-export declare function getErrorsApiClientText(count: number, apiTitle: string, sdkList: string[]): {
-    title: string;
-    description: string;
-};
-export {};
-//# sourceMappingURL=doc-templates.d.ts.map

package/dist/lib/overview-docs/doc-templates.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"doc-templates.d.ts","sourceRoot":"","sources":["../../../src/lib/overview-docs/doc-templates.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;CAmBf,CAAC;AAEX,UAAU,gBAAgB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAK9D;AAED,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,SAAS,GAAG,QAAmB,GACpC,MAAM,CAKR;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAC5C,MAAM,CAKR;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB,CAQA;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf,CAeA;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,GACf;IACD,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB,CAkBA;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf,CAeA;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EAAE,GAChB;IACD,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB,CAWA"}

package/dist/lib/overview-docs/doc-templates.js

@@ -1,123 +0,0 @@
-import pluralize from "pluralize";
-const docTemplates = {
-  servers: {
-    sectionTitle: "API Server",
-    description: "The following {count} {isAre} available for this API:"
-  },
-  authMethods: {
-    sectionTitle: "Available Authentication Method",
-    introText: "This API provides secure access through {countText} authentication {method}. Below you'll find details about {articleCount} available authentication {scheme} and how to use {pronoun}.",
-    noAuthText: "This API does not require authentication."
-  },
-  apiClients: {
-    sectionTitle: "Official API Client",
-    description: "{apiTitle} provides official client SDK{sdkPlural} for {languageText}. We recommend using {clientText} to interact with all stable endpoints. You can find {pronoun} here:"
-  },
-  needHelp: {
-    sectionTitle: "Need Help?"
-  }
-};
-function getCountText(options) {
-  const { count, word, includeCount = false } = options;
-  const pluralizedWord = count === 1 ? pluralize.singular(word) : pluralize.plural(word);
-  return includeCount ? `${count} ${pluralizedWord}` : pluralizedWord;
-}
-function getPronoun(count, type = "object") {
-  if (type === "subject") {
-    return count === 1 ? "it" : "they";
-  }
-  return count === 1 ? "it" : "them";
-}
-function getArticle(count, word) {
-  if (count === 1) {
-    const firstLetter = word.charAt(0).toLowerCase();
-    return ["a", "e", "i", "o", "u"].includes(firstLetter) ? "an" : "a";
-  }
-  return "";
-}
-function getIsAre(count) {
-  return count === 1 ? "is" : "are";
-}
-function getThisThese(count) {
-  return count === 1 ? "this" : "these";
-}
-function processTemplate(template, replacements) {
-  return template.replace(/\{([^}]+)\}/g, (match, key) => {
-    const value = replacements[key];
-    return value !== void 0 ? String(value) : match;
-  });
-}
-function getServerText(count) {
-  return {
-    title: `## ${getCountText({ count, word: "server", includeCount: false })}`,
-    description: processTemplate(docTemplates.servers.description, {
-      count: getCountText({ count, word: "server", includeCount: true }),
-      isAre: getIsAre(count)
-    })
-  };
-}
-function getAuthMethodText(count) {
-  const countText = count === 1 ? getArticle(count, "authentication method") : "various";
-  const articleCount = count === 1 ? "the" : "each";
-  return {
-    title: `## ${getCountText({ count, word: docTemplates.authMethods.sectionTitle })}`,
-    intro: processTemplate(docTemplates.authMethods.introText, {
-      countText,
-      method: getCountText({ count, word: "method" }),
-      articleCount,
-      scheme: getCountText({ count, word: "scheme" }),
-      pronoun: getPronoun(count)
-    })
-  };
-}
-function getApiClientText(count, apiTitle) {
-  const languageText = count === 1 ? "a programming language" : "multiple programming languages";
-  const clientText = count === 1 ? getThisThese(count) + " client" : getThisThese(count) + " clients";
-  return {
-    title: `## ${getCountText({ count, word: docTemplates.apiClients.sectionTitle })}`,
-    description: processTemplate(docTemplates.apiClients.description, {
-      apiTitle,
-      sdkPlural: count === 1 ? "" : "s",
-      languageText,
-      clientText,
-      pronoun: getPronoun(count)
-    })
-  };
-}
-function getAuthText(count) {
-  const countText = count === 1 ? getArticle(count, "authentication method") : "various";
-  const articleCount = count === 1 ? "the" : "each";
-  return {
-    title: `## ${getCountText({ count, word: docTemplates.authMethods.sectionTitle })}`,
-    intro: processTemplate(docTemplates.authMethods.introText, {
-      countText,
-      method: getCountText({ count, word: "method" }),
-      articleCount,
-      scheme: getCountText({ count, word: "scheme" }),
-      pronoun: getPronoun(count)
-    })
-  };
-}
-function getErrorsApiClientText(count, apiTitle, sdkList) {
-  const languageText = count === 1 ? sdkList[0] : sdkList.join(", ");
-  const clientText = count === 1 ? getThisThese(count) + " client" : getThisThese(count) + " clients";
-  return {
-    title: `## ${getCountText({ count, word: docTemplates.apiClients.sectionTitle })}`,
-    description: `${apiTitle} maintains official API ${getCountText({ count, word: "client" })}${count > 0 ? ` for ${languageText}` : ""}. We recommend using ${clientText} to interact with all stable endpoints. You can find ${getPronoun(count)} here:`
-  };
-}
-export {
-  docTemplates,
-  getApiClientText,
-  getArticle,
-  getAuthMethodText,
-  getAuthText,
-  getCountText,
-  getErrorsApiClientText,
-  getIsAre,
-  getPronoun,
-  getServerText,
-  getThisThese,
-  processTemplate
-};
-//# sourceMappingURL=doc-templates.js.map