@sdk-it/spec 0.26.0 → 0.28.0

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export * from './lib/loaders/remote-loader.js';
 export * from './lib/metadata.js';
 export * from './lib/operation.js';
 export * from './lib/options.js';
+export * from './lib/overview-docs/overview-errors.js';
 export * from './lib/reserved-keywords.js';
 export * from './lib/security.js';
 export * from './lib/sidebar.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oCAAoC,CAAC;AACnD,cAAc,kCAAkC,CAAC;AACjD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,aAAa,CAAC;AAC5B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wBAAwB,CAAC;AACvC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oCAAoC,CAAC;AACnD,cAAc,kCAAkC,CAAC;AACjD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,aAAa,CAAC;AAC5B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,wCAAwC,CAAC;AACvD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wBAAwB,CAAC;AACvC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -12,6 +12,7 @@ export * from "./lib/loaders/remote-loader.js";
 export * from "./lib/metadata.js";
 export * from "./lib/operation.js";
 export * from "./lib/options.js";
+export * from "./lib/overview-docs/overview-errors.js";
 export * from "./lib/reserved-keywords.js";
 export * from "./lib/security.js";
 export * from "./lib/sidebar.js";

package/dist/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/index.ts"],
-  "sourcesContent": ["export * from './lib/create-operation.js';\nexport * from './lib/find-polymorphic-varients.js';\nexport * from './lib/find-unique-schema-name.js';\nexport * from './lib/for-each-operation.js';\nexport * from './lib/format-name.js';\nexport * from './lib/get-ref-usage.js';\nexport * from './lib/is-primitive-schema.js';\nexport * from './lib/is.js';\nexport * from './lib/loaders/load-spec.js';\nexport * from './lib/loaders/local-loader.js';\nexport * from './lib/loaders/remote-loader.js';\nexport * from './lib/metadata.js';\nexport * from './lib/operation.js';\nexport * from './lib/options.js';\nexport * from './lib/reserved-keywords.js';\nexport * from './lib/security.js';\nexport * from './lib/sidebar.js';\nexport * from './lib/tag.js';\nexport * from './lib/tune-request-body.js';\nexport * from './lib/tune-response.js';\nexport * from './lib/tune.js';\nexport * from './lib/types.js';\n"],
-  "mappings": "AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;",
+  "sourcesContent": ["export * from './lib/create-operation.js';\nexport * from './lib/find-polymorphic-varients.js';\nexport * from './lib/find-unique-schema-name.js';\nexport * from './lib/for-each-operation.js';\nexport * from './lib/format-name.js';\nexport * from './lib/get-ref-usage.js';\nexport * from './lib/is-primitive-schema.js';\nexport * from './lib/is.js';\nexport * from './lib/loaders/load-spec.js';\nexport * from './lib/loaders/local-loader.js';\nexport * from './lib/loaders/remote-loader.js';\nexport * from './lib/metadata.js';\nexport * from './lib/operation.js';\nexport * from './lib/options.js';\nexport * from './lib/overview-docs/overview-errors.js';\nexport * from './lib/reserved-keywords.js';\nexport * from './lib/security.js';\nexport * from './lib/sidebar.js';\nexport * from './lib/tag.js';\nexport * from './lib/tune-request-body.js';\nexport * from './lib/tune-response.js';\nexport * from './lib/tune.js';\nexport * from './lib/types.js';\n"],
+  "mappings": "AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;",
   "names": []
 }

package/dist/lib/operation.js

@@ -3,7 +3,7 @@ import { resolveRef } from "@sdk-it/core/ref.js";
 import { snakecase } from "@sdk-it/core/utils.js";
 import { toResource } from "./guess/guess-resource.js";
 import { coeraceConfig } from "./options.js";
-import { extractOverviewDocs } from "./overview-docs.js";
+import { extractOverviewDocs } from "./overview-docs/overview-docs.js";
 import { toPagination } from "./pagination/pagination.js";
 import { tuneRequestBody } from "./tune-request-body.js";
 import { resolveResponses } from "./tune-response.js";

package/dist/lib/operation.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/operation.ts"],
-  "sourcesContent": ["import type {\n  OperationObject,\n  ParameterObject,\n  PathsObject,\n  SchemaObject,\n} from 'openapi3-ts/oas31';\n\nimport { type Method, methods } from '@sdk-it/core/paths.js';\nimport { resolveRef } from '@sdk-it/core/ref.js';\nimport { snakecase } from '@sdk-it/core/utils.js';\n\nimport { toResource } from './guess/guess-resource.js';\nimport { type GenerateSdkConfig, coeraceConfig } from './options.js';\nimport { extractOverviewDocs } from './overview-docs.js';\nimport { toPagination } from './pagination/pagination.js';\nimport { tuneRequestBody } from './tune-request-body.js';\nimport { resolveResponses } from './tune-response.js';\nimport { expandSpec, fixSpec } from './tune.js';\nimport type { OurOpenAPIObject, TunedOperationObject } from './types.js';\n\nfunction findUniqueOperationId(\n  usedOperationIds: Set<string>,\n  initialId: string,\n  choices: string[],\n  formatter: (id: string) => string,\n) {\n  let counter = 1;\n  let uniqueOperationId = formatter(initialId);\n\n  while (usedOperationIds.has(uniqueOperationId)) {\n    // Try each prepend option\n    const prependIndex = Math.min(counter - 1, choices.length - 1);\n    const prefix = choices[prependIndex];\n\n    if (prependIndex < choices.length - 1) {\n      // Using one of the prepend options\n      uniqueOperationId = formatter(\n        `${prefix}${initialId.charAt(0).toUpperCase() + initialId.slice(1)}`,\n      );\n    } else {\n      // If we've exhausted all prepend options, start adding numbers\n      uniqueOperationId = formatter(\n        `${prefix}${initialId.charAt(0).toUpperCase() + initialId.slice(1)}${counter - choices.length + 1}`,\n      );\n    }\n    counter++;\n  }\n\n  return uniqueOperationId;\n}\n\nexport function augmentSpec(\n  config: GenerateSdkConfig,\n  verbose = false,\n): OurOpenAPIObject {\n  const coearcedConfig = coeraceConfig(config);\n  if ('x-sdk-augmented' in config.spec) {\n    return config.spec as OurOpenAPIObject; // Already augmented\n  }\n\n  const paths: PathsObject = {};\n  const usedOperationIds = new Set<string>();\n\n  for (const [path, pathItem] of Object.entries(coearcedConfig.spec.paths)) {\n    // Convert Express-style routes (:param) to OpenAPI-style routes ({param})\n    const fixedPath = path.replace(/:([^/]+)/g, '{$1}');\n    for (const [method, operation] of Object.entries(pathItem) as [\n      Method,\n      OperationObject,\n    ][]) {\n      if (!methods.includes(method)) {\n        continue;\n      }\n      const { name } = toResource(operation, fixedPath, method);\n      const operationTag = coearcedConfig.tag(operation, fixedPath);\n      const operationId = findUniqueOperationId(\n        usedOperationIds,\n        coearcedConfig.operationId(operation, fixedPath, method),\n        [operationTag, method, fixedPath.split('/').filter(Boolean).join('')],\n        (id) =>\n          coearcedConfig.operationId(\n            { ...operation, operationId: id },\n            fixedPath,\n            method,\n          ),\n      );\n      usedOperationIds.add(operationId);\n\n      const parameters = [\n        ...(pathItem.parameters ?? []),\n        ...(operation.parameters ?? []),\n      ].map((it) => resolveRef<ParameterObject>(coearcedConfig.spec, it));\n\n      const tunedOperation: TunedOperationObject = {\n        ...operation,\n        parameters,\n        'x-fn-name': name,\n        'x-fn-group': operationTag,\n        tags: [snakecase(operationTag)],\n        operationId: operationId,\n        responses: resolveResponses(\n          coearcedConfig.spec,\n          operationId,\n          operation,\n          coearcedConfig.responses,\n        ),\n        requestBody: tuneRequestBody(\n          coearcedConfig.spec,\n          operationId,\n          // camelcase(`${name} ${operationTag}`),\n          operation,\n          parameters,\n          operation.security ?? [],\n        ),\n      };\n\n      if (coearcedConfig.pagination.enabled) {\n        if (coearcedConfig.pagination.guess) {\n          tunedOperation['x-pagination'] = toPagination(\n            coearcedConfig.spec,\n            tunedOperation,\n          );\n        }\n      } else {\n        delete tunedOperation['x-pagination'];\n      }\n\n      Object.assign(paths, {\n        [fixedPath]: {\n          ...paths[fixedPath],\n          [method]: tunedOperation,\n        },\n      });\n    }\n  }\n\n  fixSpec(\n    coearcedConfig.spec,\n    Object.values(coearcedConfig.spec.components.schemas),\n  );\n\n  if (verbose) {\n    const newRefs: { name: string; value: SchemaObject }[] = [];\n    expandSpec(\n      coearcedConfig.spec,\n      coearcedConfig.spec.components.schemas,\n      newRefs,\n    );\n  }\n\n  return {\n    ...coearcedConfig.spec,\n    paths,\n    'x-docs': extractOverviewDocs(coearcedConfig.spec),\n    'x-sdk-augmented': true,\n  };\n}\n"],
+  "sourcesContent": ["import type {\n  OperationObject,\n  ParameterObject,\n  PathsObject,\n  SchemaObject,\n} from 'openapi3-ts/oas31';\n\nimport { type Method, methods } from '@sdk-it/core/paths.js';\nimport { resolveRef } from '@sdk-it/core/ref.js';\nimport { snakecase } from '@sdk-it/core/utils.js';\n\nimport { toResource } from './guess/guess-resource.js';\nimport { type GenerateSdkConfig, coeraceConfig } from './options.js';\nimport { extractOverviewDocs } from './overview-docs/overview-docs.js';\nimport { toPagination } from './pagination/pagination.js';\nimport { tuneRequestBody } from './tune-request-body.js';\nimport { resolveResponses } from './tune-response.js';\nimport { expandSpec, fixSpec } from './tune.js';\nimport type { OurOpenAPIObject, TunedOperationObject } from './types.js';\n\nfunction findUniqueOperationId(\n  usedOperationIds: Set<string>,\n  initialId: string,\n  choices: string[],\n  formatter: (id: string) => string,\n) {\n  let counter = 1;\n  let uniqueOperationId = formatter(initialId);\n\n  while (usedOperationIds.has(uniqueOperationId)) {\n    // Try each prepend option\n    const prependIndex = Math.min(counter - 1, choices.length - 1);\n    const prefix = choices[prependIndex];\n\n    if (prependIndex < choices.length - 1) {\n      // Using one of the prepend options\n      uniqueOperationId = formatter(\n        `${prefix}${initialId.charAt(0).toUpperCase() + initialId.slice(1)}`,\n      );\n    } else {\n      // If we've exhausted all prepend options, start adding numbers\n      uniqueOperationId = formatter(\n        `${prefix}${initialId.charAt(0).toUpperCase() + initialId.slice(1)}${counter - choices.length + 1}`,\n      );\n    }\n    counter++;\n  }\n\n  return uniqueOperationId;\n}\n\nexport function augmentSpec(\n  config: GenerateSdkConfig,\n  verbose = false,\n): OurOpenAPIObject {\n  const coearcedConfig = coeraceConfig(config);\n  if ('x-sdk-augmented' in config.spec) {\n    return config.spec as OurOpenAPIObject; // Already augmented\n  }\n\n  const paths: PathsObject = {};\n  const usedOperationIds = new Set<string>();\n\n  for (const [path, pathItem] of Object.entries(coearcedConfig.spec.paths)) {\n    // Convert Express-style routes (:param) to OpenAPI-style routes ({param})\n    const fixedPath = path.replace(/:([^/]+)/g, '{$1}');\n    for (const [method, operation] of Object.entries(pathItem) as [\n      Method,\n      OperationObject,\n    ][]) {\n      if (!methods.includes(method)) {\n        continue;\n      }\n      const { name } = toResource(operation, fixedPath, method);\n      const operationTag = coearcedConfig.tag(operation, fixedPath);\n      const operationId = findUniqueOperationId(\n        usedOperationIds,\n        coearcedConfig.operationId(operation, fixedPath, method),\n        [operationTag, method, fixedPath.split('/').filter(Boolean).join('')],\n        (id) =>\n          coearcedConfig.operationId(\n            { ...operation, operationId: id },\n            fixedPath,\n            method,\n          ),\n      );\n      usedOperationIds.add(operationId);\n\n      const parameters = [\n        ...(pathItem.parameters ?? []),\n        ...(operation.parameters ?? []),\n      ].map((it) => resolveRef<ParameterObject>(coearcedConfig.spec, it));\n\n      const tunedOperation: TunedOperationObject = {\n        ...operation,\n        parameters,\n        'x-fn-name': name,\n        'x-fn-group': operationTag,\n        tags: [snakecase(operationTag)],\n        operationId: operationId,\n        responses: resolveResponses(\n          coearcedConfig.spec,\n          operationId,\n          operation,\n          coearcedConfig.responses,\n        ),\n        requestBody: tuneRequestBody(\n          coearcedConfig.spec,\n          operationId,\n          // camelcase(`${name} ${operationTag}`),\n          operation,\n          parameters,\n          operation.security ?? [],\n        ),\n      };\n\n      if (coearcedConfig.pagination.enabled) {\n        if (coearcedConfig.pagination.guess) {\n          tunedOperation['x-pagination'] = toPagination(\n            coearcedConfig.spec,\n            tunedOperation,\n          );\n        }\n      } else {\n        delete tunedOperation['x-pagination'];\n      }\n\n      Object.assign(paths, {\n        [fixedPath]: {\n          ...paths[fixedPath],\n          [method]: tunedOperation,\n        },\n      });\n    }\n  }\n\n  fixSpec(\n    coearcedConfig.spec,\n    Object.values(coearcedConfig.spec.components.schemas),\n  );\n\n  if (verbose) {\n    const newRefs: { name: string; value: SchemaObject }[] = [];\n    expandSpec(\n      coearcedConfig.spec,\n      coearcedConfig.spec.components.schemas,\n      newRefs,\n    );\n  }\n\n  return {\n    ...coearcedConfig.spec,\n    paths,\n    'x-docs': extractOverviewDocs(coearcedConfig.spec),\n    'x-sdk-augmented': true,\n  };\n}\n"],
   "mappings": "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",
   "names": []
 }

package/dist/lib/options.d.ts

@@ -1,4 +1,4 @@
-import type { OpenAPIObject, OperationObject } from 'openapi3-ts/oas31';
+import type { OpenAPIObject, OperationObject, SecuritySchemeObject } from 'openapi3-ts/oas31';
 export interface GenerateSdkConfig {
     spec: OpenAPIObject;
     responses?: ResponsesConfig;
@@ -26,7 +26,7 @@ export declare function coeraceConfig(config: GenerateSdkConfig): {
                 [schema: string]: import("openapi3-ts/oas31").SchemaObject | import("openapi3-ts/oas31").ReferenceObject;
             };
             securitySchemes: {
-                [securityScheme: string]: import("openapi3-ts/oas31").ReferenceObject | import("openapi3-ts/oas31").SecuritySchemeObject;
+                [k: string]: SecuritySchemeObject;
             };
             responses?: {
                 [response: string]: import("openapi3-ts/oas31").ResponseObject | import("openapi3-ts/oas31").ReferenceObject;

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

@@ -1 +1 @@
-{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/lib/options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAMxE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,aAAa,CAAC;IACpB,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,UAAU,CAAC,EAAE,gBAAgB,GAAG,KAAK,CAAC;IACtC,WAAW,CAAC,EAAE,CACZ,SAAS,EAAE,eAAe,EAC1B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,KACX,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,CAAC,SAAS,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CAC5D;AACD,MAAM,WAAW,eAAe;IAC9B,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,UAOnD;AAED,eAAO,MAAM,QAAQ,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAC/C,QAAQ,CAAC,IAAI,CAAC,iBAAiB,EAAE,aAAa,GAAG,KAAK,CAAC,CAkBxD,CAAC;AAEF,wBAAgB,aAAa,CAAC,MAAM,EAAE,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6BA5CxC,eAAe,QACpB,MAAM,UACJ,MAAM,KACX,MAAM;qBACO,eAAe,QAAQ,MAAM,KAAK,MAAM;EA+D3D;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,gBAAgB,GAAG,SAAS,GAAG,KAAK;;;EAmB9C"}
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/lib/options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,oBAAoB,EACrB,MAAM,mBAAmB,CAAC;AAQ3B,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,aAAa,CAAC;IACpB,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,UAAU,CAAC,EAAE,gBAAgB,GAAG,KAAK,CAAC;IACtC,WAAW,CAAC,EAAE,CACZ,SAAS,EAAE,eAAe,EAC1B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,KACX,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,CAAC,SAAS,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CAC5D;AACD,MAAM,WAAW,eAAe;IAC9B,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,UAOnD;AAED,eAAO,MAAM,QAAQ,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAC/C,QAAQ,CAAC,IAAI,CAAC,iBAAiB,EAAE,aAAa,GAAG,KAAK,CAAC,CAkBxD,CAAC;AAEF,wBAAgB,aAAa,CAAC,MAAM,EAAE,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6BA5CxC,eAAe,QACpB,MAAM,UACJ,MAAM,KACX,MAAM;qBACO,eAAe,QAAQ,MAAM,KAAK,MAAM;EAsE3D;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,gBAAgB,GAAG,SAAS,GAAG,KAAK;;;EAmB9C"}

package/dist/lib/options.js

@@ -1,4 +1,5 @@
 import { camelcase } from "stringcase";
+import { resolveRef } from "@sdk-it/core";
 import { determineGenericTag, sanitizeTag } from "./tag.js";
 function cleanOperationId(operationId) {
   return camelcase(
@@ -27,7 +28,14 @@ function coeraceConfig(config) {
       components: {
         ...config.spec.components,
         schemas: config.spec.components?.schemas ?? {},
-        securitySchemes: config.spec.components?.securitySchemes ?? {}
+        securitySchemes: Object.fromEntries(
+          Object.entries(config.spec.components?.securitySchemes ?? {}).map(
+            ([name, schema]) => [
+              name,
+              resolveRef(config.spec, schema)
+            ]
+          )
+        )
       },
       paths: config.spec.paths ?? {},
       "x-docs": [],

package/dist/lib/options.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/options.ts"],
-  "sourcesContent": ["import type { OpenAPIObject, OperationObject } from 'openapi3-ts/oas31';\nimport { camelcase } from 'stringcase';\n\nimport { determineGenericTag, sanitizeTag } from './tag.js';\nimport type { OurOpenAPIObject } from './types.js';\n\nexport interface GenerateSdkConfig {\n  spec: OpenAPIObject;\n  responses?: ResponsesConfig;\n  pagination?: PaginationConfig | false;\n  operationId?: (\n    operation: OperationObject,\n    path: string,\n    method: string,\n  ) => string;\n  tag?: (operation: OperationObject, path: string) => string;\n}\nexport interface ResponsesConfig {\n  flattenErrorResponses?: boolean;\n}\n\nexport type PaginationConfig = {\n  guess?: boolean;\n};\n\nexport function cleanOperationId(operationId: string) {\n  return camelcase(\n    operationId\n      .split('#')\n      .pop()!\n      .replace(/-(?=\\d)/g, ''),\n  );\n}\n\nexport const defaults: Partial<GenerateSdkConfig> &\n  Required<Pick<GenerateSdkConfig, 'operationId' | 'tag'>> = {\n  operationId: (operation, path, method) => {\n    if (operation.operationId) {\n      return cleanOperationId(operation.operationId);\n    }\n\n    return camelcase(\n      [method, ...path.replace(/[\\\\/\\\\{\\\\}]/g, ' ').split(' ')]\n        .filter(Boolean)\n        .join(' ')\n        .trim(),\n    );\n  },\n  tag: (operation, path) => {\n    return operation.tags?.[0]\n      ? sanitizeTag(operation.tags?.[0])\n      : determineGenericTag(path, operation);\n  },\n};\n\nexport function coeraceConfig(config: GenerateSdkConfig) {\n  return {\n    pagination: coearcePaginationConfig(config.pagination),\n    responses: config.responses ?? {},\n    spec: {\n      ...config.spec,\n      components: {\n        ...config.spec.components,\n        schemas: config.spec.components?.schemas ?? {},\n        securitySchemes: config.spec.components?.securitySchemes ?? {},\n      },\n      paths: config.spec.paths ?? {},\n      'x-docs': [],\n      'x-tagGroups': config.spec['x-tagGroups'] ?? [\n        {\n          name: 'API',\n          tags: config.spec.tags?.map((tag) => tag.name) ?? [],\n        },\n      ],\n    } satisfies OurOpenAPIObject,\n    operationId: config.operationId ?? defaults.operationId,\n    tag: config.tag ?? defaults.tag,\n  };\n}\n\nexport function coearcePaginationConfig(\n  options: PaginationConfig | undefined | false,\n) {\n  if (options === undefined) {\n    return {\n      guess: true,\n      enabled: true,\n    };\n  }\n  if (options === false) {\n    return {\n      enabled: false,\n      guess: false,\n    };\n  }\n  // If options is true, we assume pagination is enabled with guessing\n  return {\n    guess: options.guess ?? true,\n    enabled: true,\n  };\n}\n"],
-  "mappings": "AACA,SAAS,iBAAiB;AAE1B,SAAS,qBAAqB,mBAAmB;AAsB1C,SAAS,iBAAiB,aAAqB;AACpD,SAAO;AAAA,IACL,YACG,MAAM,GAAG,EACT,IAAI,EACJ,QAAQ,YAAY,EAAE;AAAA,EAC3B;AACF;AAEO,MAAM,WACgD;AAAA,EAC3D,aAAa,CAAC,WAAW,MAAM,WAAW;AACxC,QAAI,UAAU,aAAa;AACzB,aAAO,iBAAiB,UAAU,WAAW;AAAA,IAC/C;AAEA,WAAO;AAAA,MACL,CAAC,QAAQ,GAAG,KAAK,QAAQ,gBAAgB,GAAG,EAAE,MAAM,GAAG,CAAC,EACrD,OAAO,OAAO,EACd,KAAK,GAAG,EACR,KAAK;AAAA,IACV;AAAA,EACF;AAAA,EACA,KAAK,CAAC,WAAW,SAAS;AACxB,WAAO,UAAU,OAAO,CAAC,IACrB,YAAY,UAAU,OAAO,CAAC,CAAC,IAC/B,oBAAoB,MAAM,SAAS;AAAA,EACzC;AACF;AAEO,SAAS,cAAc,QAA2B;AACvD,SAAO;AAAA,IACL,YAAY,wBAAwB,OAAO,UAAU;AAAA,IACrD,WAAW,OAAO,aAAa,CAAC;AAAA,IAChC,MAAM;AAAA,MACJ,GAAG,OAAO;AAAA,MACV,YAAY;AAAA,QACV,GAAG,OAAO,KAAK;AAAA,QACf,SAAS,OAAO,KAAK,YAAY,WAAW,CAAC;AAAA,QAC7C,iBAAiB,OAAO,KAAK,YAAY,mBAAmB,CAAC;AAAA,MAC/D;AAAA,MACA,OAAO,OAAO,KAAK,SAAS,CAAC;AAAA,MAC7B,UAAU,CAAC;AAAA,MACX,eAAe,OAAO,KAAK,aAAa,KAAK;AAAA,QAC3C;AAAA,UACE,MAAM;AAAA,UACN,MAAM,OAAO,KAAK,MAAM,IAAI,CAAC,QAAQ,IAAI,IAAI,KAAK,CAAC;AAAA,QACrD;AAAA,MACF;AAAA,IACF;AAAA,IACA,aAAa,OAAO,eAAe,SAAS;AAAA,IAC5C,KAAK,OAAO,OAAO,SAAS;AAAA,EAC9B;AACF;AAEO,SAAS,wBACd,SACA;AACA,MAAI,YAAY,QAAW;AACzB,WAAO;AAAA,MACL,OAAO;AAAA,MACP,SAAS;AAAA,IACX;AAAA,EACF;AACA,MAAI,YAAY,OAAO;AACrB,WAAO;AAAA,MACL,SAAS;AAAA,MACT,OAAO;AAAA,IACT;AAAA,EACF;AAEA,SAAO;AAAA,IACL,OAAO,QAAQ,SAAS;AAAA,IACxB,SAAS;AAAA,EACX;AACF;",
+  "sourcesContent": ["import type {\n  OpenAPIObject,\n  OperationObject,\n  SecuritySchemeObject,\n} from 'openapi3-ts/oas31';\nimport { camelcase } from 'stringcase';\n\nimport { resolveRef } from '@sdk-it/core';\n\nimport { determineGenericTag, sanitizeTag } from './tag.js';\nimport type { OurOpenAPIObject } from './types.js';\n\nexport interface GenerateSdkConfig {\n  spec: OpenAPIObject;\n  responses?: ResponsesConfig;\n  pagination?: PaginationConfig | false;\n  operationId?: (\n    operation: OperationObject,\n    path: string,\n    method: string,\n  ) => string;\n  tag?: (operation: OperationObject, path: string) => string;\n}\nexport interface ResponsesConfig {\n  flattenErrorResponses?: boolean;\n}\n\nexport type PaginationConfig = {\n  guess?: boolean;\n};\n\nexport function cleanOperationId(operationId: string) {\n  return camelcase(\n    operationId\n      .split('#')\n      .pop()!\n      .replace(/-(?=\\d)/g, ''),\n  );\n}\n\nexport const defaults: Partial<GenerateSdkConfig> &\n  Required<Pick<GenerateSdkConfig, 'operationId' | 'tag'>> = {\n  operationId: (operation, path, method) => {\n    if (operation.operationId) {\n      return cleanOperationId(operation.operationId);\n    }\n\n    return camelcase(\n      [method, ...path.replace(/[\\\\/\\\\{\\\\}]/g, ' ').split(' ')]\n        .filter(Boolean)\n        .join(' ')\n        .trim(),\n    );\n  },\n  tag: (operation, path) => {\n    return operation.tags?.[0]\n      ? sanitizeTag(operation.tags?.[0])\n      : determineGenericTag(path, operation);\n  },\n};\n\nexport function coeraceConfig(config: GenerateSdkConfig) {\n  return {\n    pagination: coearcePaginationConfig(config.pagination),\n    responses: config.responses ?? {},\n    spec: {\n      ...config.spec,\n      components: {\n        ...config.spec.components,\n        schemas: config.spec.components?.schemas ?? {},\n        securitySchemes: Object.fromEntries(\n          Object.entries(config.spec.components?.securitySchemes ?? {}).map(\n            ([name, schema]) => [\n              name,\n              resolveRef<SecuritySchemeObject>(config.spec, schema),\n            ],\n          ),\n        ),\n      },\n      paths: config.spec.paths ?? {},\n      'x-docs': [],\n      'x-tagGroups': config.spec['x-tagGroups'] ?? [\n        {\n          name: 'API',\n          tags: config.spec.tags?.map((tag) => tag.name) ?? [],\n        },\n      ],\n    } satisfies OurOpenAPIObject,\n    operationId: config.operationId ?? defaults.operationId,\n    tag: config.tag ?? defaults.tag,\n  };\n}\n\nexport function coearcePaginationConfig(\n  options: PaginationConfig | undefined | false,\n) {\n  if (options === undefined) {\n    return {\n      guess: true,\n      enabled: true,\n    };\n  }\n  if (options === false) {\n    return {\n      enabled: false,\n      guess: false,\n    };\n  }\n  // If options is true, we assume pagination is enabled with guessing\n  return {\n    guess: options.guess ?? true,\n    enabled: true,\n  };\n}\n"],
+  "mappings": "AAKA,SAAS,iBAAiB;AAE1B,SAAS,kBAAkB;AAE3B,SAAS,qBAAqB,mBAAmB;AAsB1C,SAAS,iBAAiB,aAAqB;AACpD,SAAO;AAAA,IACL,YACG,MAAM,GAAG,EACT,IAAI,EACJ,QAAQ,YAAY,EAAE;AAAA,EAC3B;AACF;AAEO,MAAM,WACgD;AAAA,EAC3D,aAAa,CAAC,WAAW,MAAM,WAAW;AACxC,QAAI,UAAU,aAAa;AACzB,aAAO,iBAAiB,UAAU,WAAW;AAAA,IAC/C;AAEA,WAAO;AAAA,MACL,CAAC,QAAQ,GAAG,KAAK,QAAQ,gBAAgB,GAAG,EAAE,MAAM,GAAG,CAAC,EACrD,OAAO,OAAO,EACd,KAAK,GAAG,EACR,KAAK;AAAA,IACV;AAAA,EACF;AAAA,EACA,KAAK,CAAC,WAAW,SAAS;AACxB,WAAO,UAAU,OAAO,CAAC,IACrB,YAAY,UAAU,OAAO,CAAC,CAAC,IAC/B,oBAAoB,MAAM,SAAS;AAAA,EACzC;AACF;AAEO,SAAS,cAAc,QAA2B;AACvD,SAAO;AAAA,IACL,YAAY,wBAAwB,OAAO,UAAU;AAAA,IACrD,WAAW,OAAO,aAAa,CAAC;AAAA,IAChC,MAAM;AAAA,MACJ,GAAG,OAAO;AAAA,MACV,YAAY;AAAA,QACV,GAAG,OAAO,KAAK;AAAA,QACf,SAAS,OAAO,KAAK,YAAY,WAAW,CAAC;AAAA,QAC7C,iBAAiB,OAAO;AAAA,UACtB,OAAO,QAAQ,OAAO,KAAK,YAAY,mBAAmB,CAAC,CAAC,EAAE;AAAA,YAC5D,CAAC,CAAC,MAAM,MAAM,MAAM;AAAA,cAClB;AAAA,cACA,WAAiC,OAAO,MAAM,MAAM;AAAA,YACtD;AAAA,UACF;AAAA,QACF;AAAA,MACF;AAAA,MACA,OAAO,OAAO,KAAK,SAAS,CAAC;AAAA,MAC7B,UAAU,CAAC;AAAA,MACX,eAAe,OAAO,KAAK,aAAa,KAAK;AAAA,QAC3C;AAAA,UACE,MAAM;AAAA,UACN,MAAM,OAAO,KAAK,MAAM,IAAI,CAAC,QAAQ,IAAI,IAAI,KAAK,CAAC;AAAA,QACrD;AAAA,MACF;AAAA,IACF;AAAA,IACA,aAAa,OAAO,eAAe,SAAS;AAAA,IAC5C,KAAK,OAAO,OAAO,SAAS;AAAA,EAC9B;AACF;AAEO,SAAS,wBACd,SACA;AACA,MAAI,YAAY,QAAW;AACzB,WAAO;AAAA,MACL,OAAO;AAAA,MACP,SAAS;AAAA,IACX;AAAA,EACF;AACA,MAAI,YAAY,OAAO;AACrB,WAAO;AAAA,MACL,SAAS;AAAA,MACT,OAAO;AAAA,IACT;AAAA,EACF;AAEA,SAAO;AAAA,IACL,OAAO,QAAQ,SAAS;AAAA,IACxB,SAAS;AAAA,EACX;AACF;",
   "names": []
 }

package/dist/lib/overview-docs/overview-auth.d.ts

@@ -0,0 +1,4 @@
+import type { NavItem } from '../sidebar.js';
+import type { OurOpenAPIObject } from '../types.js';
+export declare function generateAuthOverview(spec: OurOpenAPIObject): NavItem;
+//# sourceMappingURL=overview-auth.d.ts.map

package/dist/lib/overview-docs/overview-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overview-auth.d.ts","sourceRoot":"","sources":["../../../src/lib/overview-docs/overview-auth.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AA+GpD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAsDpE"}

package/dist/lib/overview-docs/overview-auth.js

@@ -0,0 +1,173 @@
+import { resolveRef } from "@sdk-it/core";
+function getSecuritySchemeDescription(scheme) {
+  switch (scheme.type) {
+    case "apiKey": {
+      const location = scheme.in === "header" ? "HTTP header" : scheme.in === "query" ? "query parameter" : "cookie";
+      return `API Key authentication requires you to provide an API key in the ${location} named \`${scheme.name}\`.`;
+    }
+    case "http":
+      if (scheme.scheme === "bearer") {
+        const format = scheme.bearerFormat ? ` The expected token format is \`${scheme.bearerFormat}\`.` : "";
+        return `Bearer token authentication requires you to include a bearer token in the \`Authorization\` header of your requests.${format}`;
+      }
+      if (scheme.scheme === "basic") {
+        return `Basic authentication requires you to provide a username and password, encoded in base64 format in the \`Authorization\` header.`;
+      }
+      return `HTTP ${scheme.scheme} authentication is required for accessing this API.`;
+    case "oauth2": {
+      const flows = Object.keys(scheme.flows || {});
+      const flowDescriptions = flows.map((flow) => {
+        switch (flow) {
+          case "authorizationCode":
+            return "Authorization Code (for server-side applications)";
+          case "implicit":
+            return "Implicit (for browser-based applications)";
+          case "password":
+            return "Resource Owner Password Credentials";
+          case "clientCredentials":
+            return "Client Credentials (for machine-to-machine authentication)";
+          default:
+            return flow;
+        }
+      });
+      return `OAuth 2.0 authentication is supported with the following grant type(s): ${flowDescriptions.join(", ")}.`;
+    }
+    case "openIdConnect":
+      return `OpenID Connect authentication is used for this API. You will need to authenticate through the OpenID provider to obtain access tokens.`;
+    default:
+      return "This API uses a custom authentication scheme. Please refer to the API documentation for specific details.";
+  }
+}
+function formatOAuth2Flows(flows) {
+  let result = "";
+  for (const [flowType, flow] of Object.entries(flows || {})) {
+    result += `#### ${getFlowDisplayName(flowType)}
+
+`;
+    if (flow.authorizationUrl) {
+      result += `- **Authorization URL:** \`${flow.authorizationUrl}\`
+`;
+    }
+    if (flow.tokenUrl) {
+      result += `- **Token URL:** \`${flow.tokenUrl}\`
+`;
+    }
+    if (flow.refreshUrl) {
+      result += `- **Refresh URL:** \`${flow.refreshUrl}\`
+`;
+    }
+    if (flow.scopes && Object.keys(flow.scopes).length > 0) {
+      result += `- **Available Scopes:**
+`;
+      for (const [scope, description] of Object.entries(flow.scopes)) {
+        result += `  - \`${scope}\`: ${description}
+`;
+      }
+    }
+    result += "\n";
+  }
+  return result;
+}
+function getFlowDisplayName(flowType) {
+  const flowNames = {
+    authorizationCode: "Authorization Code Flow",
+    implicit: "Implicit Flow",
+    password: "Resource Owner Password Flow",
+    clientCredentials: "Client Credentials Flow"
+  };
+  return flowNames[flowType] || flowType;
+}
+function formatSecurityRequirements(requirements) {
+  if (!requirements || requirements.length === 0) return "";
+  let result = "";
+  requirements.forEach((req, index) => {
+    const schemes = Object.entries(req);
+    if (schemes.length === 0) {
+      result += `${index + 1}. No authentication required
+`;
+    } else {
+      result += `${index + 1}. Requires: `;
+      const schemeDescriptions = schemes.map(([scheme, scopes]) => {
+        const scopeArray = scopes;
+        if (scopeArray && scopeArray.length > 0) {
+          return `\`${scheme}\` with scopes: ${scopeArray.map((s) => `\`${s}\``).join(", ")}`;
+        }
+        return `\`${scheme}\``;
+      });
+      result += schemeDescriptions.join(" AND ") + "\n";
+    }
+  });
+  return result;
+}
+function generateAuthOverview(spec) {
+  let markdown = `# Authorization
+
+`;
+  const securitySchemes = spec.components?.securitySchemes || {};
+  const globalSecurity = spec.security || [];
+  if (Object.keys(securitySchemes).length === 0 && globalSecurity.length === 0) {
+    markdown += `This API does not require authentication.
+
+`;
+  } else {
+    markdown += `This API provides secure access through various authentication methods. Below you'll find details about each available authentication scheme and how to use them.
+
+`;
+    if (Object.keys(securitySchemes).length > 0) {
+      markdown += `## Available Authentication Methods
+
+`;
+      for (const [name, scheme] of Object.entries(securitySchemes)) {
+        const schemeObj = resolveRef(spec, scheme);
+        markdown += `### ${name}
+
+`;
+        const description = schemeObj.description || getSecuritySchemeDescription(schemeObj);
+        markdown += `${description}
+
+`;
+        if (schemeObj.type === "apiKey") {
+          markdown += `**Details:**
+`;
+          markdown += `- Parameter Name: \`${schemeObj.name}\`
+`;
+          markdown += `- Location: ${schemeObj.in === "header" ? "HTTP Header" : schemeObj.in === "query" ? "Query Parameter" : "Cookie"}
+
+`;
+        } else if (schemeObj.type === "http") {
+          markdown += `**Details:**
+`;
+          markdown += `- Scheme: \`${schemeObj.scheme}\`
+`;
+          if (schemeObj.bearerFormat) {
+            markdown += `- Token Format: \`${schemeObj.bearerFormat}\`
+`;
+          }
+          markdown += "\n";
+        } else if (schemeObj.type === "oauth2" && schemeObj.flows) {
+          markdown += `**OAuth 2.0 Flows:**
+
+`;
+          markdown += formatOAuth2Flows(schemeObj.flows);
+        } else if (schemeObj.type === "openIdConnect") {
+          markdown += `**Details:**
+`;
+          markdown += `- Discovery URL: \`${schemeObj.openIdConnectUrl}\`
+
+`;
+        }
+      }
+    }
+  }
+  return {
+    id: "authorization",
+    url: "/authorization",
+    title: "Authorization",
+    description: "Authentication methods and security schemes",
+    content: markdown
+  };
+}
+export {
+  generateAuthOverview
+};
+//# sourceMappingURL=overview-auth.js.map

package/dist/lib/overview-docs/overview-auth.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/overview-docs/overview-auth.ts"],
+  "sourcesContent": ["import type { OAuthFlowsObject, SecuritySchemeObject } from 'openapi3-ts/oas31';\n\nimport { resolveRef } from '@sdk-it/core';\n\nimport type { NavItem } from '../sidebar.js';\nimport type { OurOpenAPIObject } from '../types.js';\n\nfunction getSecuritySchemeDescription(scheme: SecuritySchemeObject): string {\n  switch (scheme.type) {\n    case 'apiKey': {\n      const location =\n        scheme.in === 'header'\n          ? 'HTTP header'\n          : scheme.in === 'query'\n            ? 'query parameter'\n            : 'cookie';\n      return `API Key authentication requires you to provide an API key in the ${location} named \\`${scheme.name}\\`.`;\n    }\n    case 'http':\n      if (scheme.scheme === 'bearer') {\n        const format = scheme.bearerFormat\n          ? ` The expected token format is \\`${scheme.bearerFormat}\\`.`\n          : '';\n        return `Bearer token authentication requires you to include a bearer token in the \\`Authorization\\` header of your requests.${format}`;\n      }\n      if (scheme.scheme === 'basic') {\n        return `Basic authentication requires you to provide a username and password, encoded in base64 format in the \\`Authorization\\` header.`;\n      }\n      return `HTTP ${scheme.scheme} authentication is required for accessing this API.`;\n    case 'oauth2': {\n      const flows = Object.keys(scheme.flows || {});\n      const flowDescriptions = flows.map((flow) => {\n        switch (flow) {\n          case 'authorizationCode':\n            return 'Authorization Code (for server-side applications)';\n          case 'implicit':\n            return 'Implicit (for browser-based applications)';\n          case 'password':\n            return 'Resource Owner Password Credentials';\n          case 'clientCredentials':\n            return 'Client Credentials (for machine-to-machine authentication)';\n          default:\n            return flow;\n        }\n      });\n      return `OAuth 2.0 authentication is supported with the following grant type(s): ${flowDescriptions.join(', ')}.`;\n    }\n    case 'openIdConnect':\n      return `OpenID Connect authentication is used for this API. You will need to authenticate through the OpenID provider to obtain access tokens.`;\n    default:\n      return 'This API uses a custom authentication scheme. Please refer to the API documentation for specific details.';\n  }\n}\n\nfunction formatOAuth2Flows(flows: OAuthFlowsObject): string {\n  let result = '';\n\n  for (const [flowType, flow] of Object.entries(flows || {})) {\n    result += `#### ${getFlowDisplayName(flowType)}\\n\\n`;\n\n    if (flow.authorizationUrl) {\n      result += `- **Authorization URL:** \\`${flow.authorizationUrl}\\`\\n`;\n    }\n    if (flow.tokenUrl) {\n      result += `- **Token URL:** \\`${flow.tokenUrl}\\`\\n`;\n    }\n    if (flow.refreshUrl) {\n      result += `- **Refresh URL:** \\`${flow.refreshUrl}\\`\\n`;\n    }\n    if (flow.scopes && Object.keys(flow.scopes).length > 0) {\n      result += `- **Available Scopes:**\\n`;\n      for (const [scope, description] of Object.entries(flow.scopes)) {\n        result += `  - \\`${scope}\\`: ${description}\\n`;\n      }\n    }\n    result += '\\n';\n  }\n\n  return result;\n}\n\nfunction getFlowDisplayName(flowType: string): string {\n  const flowNames: Record<string, string> = {\n    authorizationCode: 'Authorization Code Flow',\n    implicit: 'Implicit Flow',\n    password: 'Resource Owner Password Flow',\n    clientCredentials: 'Client Credentials Flow',\n  };\n  return flowNames[flowType] || flowType;\n}\n\nfunction formatSecurityRequirements(\n  requirements: Array<Record<string, string[]>>,\n): string {\n  if (!requirements || requirements.length === 0) return '';\n\n  let result = '';\n  requirements.forEach((req, index) => {\n    const schemes = Object.entries(req);\n    if (schemes.length === 0) {\n      result += `${index + 1}. No authentication required\\n`;\n    } else {\n      result += `${index + 1}. Requires: `;\n      const schemeDescriptions = schemes.map(([scheme, scopes]) => {\n        const scopeArray = scopes as string[];\n        if (scopeArray && scopeArray.length > 0) {\n          return `\\`${scheme}\\` with scopes: ${scopeArray.map((s) => `\\`${s}\\``).join(', ')}`;\n        }\n        return `\\`${scheme}\\``;\n      });\n      result += schemeDescriptions.join(' AND ') + '\\n';\n    }\n  });\n  return result;\n}\n\nexport function generateAuthOverview(spec: OurOpenAPIObject): NavItem {\n  let markdown = `# Authorization\\n\\n`;\n\n  const securitySchemes = spec.components?.securitySchemes || {};\n  const globalSecurity = spec.security || [];\n\n  if (\n    Object.keys(securitySchemes).length === 0 &&\n    globalSecurity.length === 0\n  ) {\n    markdown += `This API does not require authentication.\\n\\n`;\n  } else {\n    markdown += `This API provides secure access through various authentication methods. Below you'll find details about each available authentication scheme and how to use them.\\n\\n`;\n\n    if (Object.keys(securitySchemes).length > 0) {\n      markdown += `## Available Authentication Methods\\n\\n`;\n\n      for (const [name, scheme] of Object.entries(securitySchemes)) {\n        const schemeObj = resolveRef<SecuritySchemeObject>(spec, scheme);\n        markdown += `### ${name}\\n\\n`;\n\n        const description =\n          schemeObj.description || getSecuritySchemeDescription(schemeObj);\n        markdown += `${description}\\n\\n`;\n\n        if (schemeObj.type === 'apiKey') {\n          markdown += `**Details:**\\n`;\n          markdown += `- Parameter Name: \\`${schemeObj.name}\\`\\n`;\n          markdown += `- Location: ${schemeObj.in === 'header' ? 'HTTP Header' : schemeObj.in === 'query' ? 'Query Parameter' : 'Cookie'}\\n\\n`;\n        } else if (schemeObj.type === 'http') {\n          markdown += `**Details:**\\n`;\n          markdown += `- Scheme: \\`${schemeObj.scheme}\\`\\n`;\n          if (schemeObj.bearerFormat) {\n            markdown += `- Token Format: \\`${schemeObj.bearerFormat}\\`\\n`;\n          }\n          markdown += '\\n';\n        } else if (schemeObj.type === 'oauth2' && schemeObj.flows) {\n          markdown += `**OAuth 2.0 Flows:**\\n\\n`;\n          markdown += formatOAuth2Flows(schemeObj.flows);\n        } else if (schemeObj.type === 'openIdConnect') {\n          markdown += `**Details:**\\n`;\n          markdown += `- Discovery URL: \\`${schemeObj.openIdConnectUrl}\\`\\n\\n`;\n        }\n      }\n    }\n  }\n\n  return {\n    id: 'authorization',\n    url: '/authorization',\n    title: 'Authorization',\n    description: 'Authentication methods and security schemes',\n    content: markdown,\n  };\n}\n"],
+  "mappings": "AAEA,SAAS,kBAAkB;AAK3B,SAAS,6BAA6B,QAAsC;AAC1E,UAAQ,OAAO,MAAM;AAAA,IACnB,KAAK,UAAU;AACb,YAAM,WACJ,OAAO,OAAO,WACV,gBACA,OAAO,OAAO,UACZ,oBACA;AACR,aAAO,oEAAoE,QAAQ,YAAY,OAAO,IAAI;AAAA,IAC5G;AAAA,IACA,KAAK;AACH,UAAI,OAAO,WAAW,UAAU;AAC9B,cAAM,SAAS,OAAO,eAClB,mCAAmC,OAAO,YAAY,QACtD;AACJ,eAAO,uHAAuH,MAAM;AAAA,MACtI;AACA,UAAI,OAAO,WAAW,SAAS;AAC7B,eAAO;AAAA,MACT;AACA,aAAO,QAAQ,OAAO,MAAM;AAAA,IAC9B,KAAK,UAAU;AACb,YAAM,QAAQ,OAAO,KAAK,OAAO,SAAS,CAAC,CAAC;AAC5C,YAAM,mBAAmB,MAAM,IAAI,CAAC,SAAS;AAC3C,gBAAQ,MAAM;AAAA,UACZ,KAAK;AACH,mBAAO;AAAA,UACT,KAAK;AACH,mBAAO;AAAA,UACT,KAAK;AACH,mBAAO;AAAA,UACT,KAAK;AACH,mBAAO;AAAA,UACT;AACE,mBAAO;AAAA,QACX;AAAA,MACF,CAAC;AACD,aAAO,2EAA2E,iBAAiB,KAAK,IAAI,CAAC;AAAA,IAC/G;AAAA,IACA,KAAK;AACH,aAAO;AAAA,IACT;AACE,aAAO;AAAA,EACX;AACF;AAEA,SAAS,kBAAkB,OAAiC;AAC1D,MAAI,SAAS;AAEb,aAAW,CAAC,UAAU,IAAI,KAAK,OAAO,QAAQ,SAAS,CAAC,CAAC,GAAG;AAC1D,cAAU,QAAQ,mBAAmB,QAAQ,CAAC;AAAA;AAAA;AAE9C,QAAI,KAAK,kBAAkB;AACzB,gBAAU,8BAA8B,KAAK,gBAAgB;AAAA;AAAA,IAC/D;AACA,QAAI,KAAK,UAAU;AACjB,gBAAU,sBAAsB,KAAK,QAAQ;AAAA;AAAA,IAC/C;AACA,QAAI,KAAK,YAAY;AACnB,gBAAU,wBAAwB,KAAK,UAAU;AAAA;AAAA,IACnD;AACA,QAAI,KAAK,UAAU,OAAO,KAAK,KAAK,MAAM,EAAE,SAAS,GAAG;AACtD,gBAAU;AAAA;AACV,iBAAW,CAAC,OAAO,WAAW,KAAK,OAAO,QAAQ,KAAK,MAAM,GAAG;AAC9D,kBAAU,SAAS,KAAK,OAAO,WAAW;AAAA;AAAA,MAC5C;AAAA,IACF;AACA,cAAU;AAAA,EACZ;AAEA,SAAO;AACT;AAEA,SAAS,mBAAmB,UAA0B;AACpD,QAAM,YAAoC;AAAA,IACxC,mBAAmB;AAAA,IACnB,UAAU;AAAA,IACV,UAAU;AAAA,IACV,mBAAmB;AAAA,EACrB;AACA,SAAO,UAAU,QAAQ,KAAK;AAChC;AAEA,SAAS,2BACP,cACQ;AACR,MAAI,CAAC,gBAAgB,aAAa,WAAW,EAAG,QAAO;AAEvD,MAAI,SAAS;AACb,eAAa,QAAQ,CAAC,KAAK,UAAU;AACnC,UAAM,UAAU,OAAO,QAAQ,GAAG;AAClC,QAAI,QAAQ,WAAW,GAAG;AACxB,gBAAU,GAAG,QAAQ,CAAC;AAAA;AAAA,IACxB,OAAO;AACL,gBAAU,GAAG,QAAQ,CAAC;AACtB,YAAM,qBAAqB,QAAQ,IAAI,CAAC,CAAC,QAAQ,MAAM,MAAM;AAC3D,cAAM,aAAa;AACnB,YAAI,cAAc,WAAW,SAAS,GAAG;AACvC,iBAAO,KAAK,MAAM,mBAAmB,WAAW,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,EAAE,KAAK,IAAI,CAAC;AAAA,QACnF;AACA,eAAO,KAAK,MAAM;AAAA,MACpB,CAAC;AACD,gBAAU,mBAAmB,KAAK,OAAO,IAAI;AAAA,IAC/C;AAAA,EACF,CAAC;AACD,SAAO;AACT;AAEO,SAAS,qBAAqB,MAAiC;AACpE,MAAI,WAAW;AAAA;AAAA;AAEf,QAAM,kBAAkB,KAAK,YAAY,mBAAmB,CAAC;AAC7D,QAAM,iBAAiB,KAAK,YAAY,CAAC;AAEzC,MACE,OAAO,KAAK,eAAe,EAAE,WAAW,KACxC,eAAe,WAAW,GAC1B;AACA,gBAAY;AAAA;AAAA;AAAA,EACd,OAAO;AACL,gBAAY;AAAA;AAAA;AAEZ,QAAI,OAAO,KAAK,eAAe,EAAE,SAAS,GAAG;AAC3C,kBAAY;AAAA;AAAA;AAEZ,iBAAW,CAAC,MAAM,MAAM,KAAK,OAAO,QAAQ,eAAe,GAAG;AAC5D,cAAM,YAAY,WAAiC,MAAM,MAAM;AAC/D,oBAAY,OAAO,IAAI;AAAA;AAAA;AAEvB,cAAM,cACJ,UAAU,eAAe,6BAA6B,SAAS;AACjE,oBAAY,GAAG,WAAW;AAAA;AAAA;AAE1B,YAAI,UAAU,SAAS,UAAU;AAC/B,sBAAY;AAAA;AACZ,sBAAY,uBAAuB,UAAU,IAAI;AAAA;AACjD,sBAAY,eAAe,UAAU,OAAO,WAAW,gBAAgB,UAAU,OAAO,UAAU,oBAAoB,QAAQ;AAAA;AAAA;AAAA,QAChI,WAAW,UAAU,SAAS,QAAQ;AACpC,sBAAY;AAAA;AACZ,sBAAY,eAAe,UAAU,MAAM;AAAA;AAC3C,cAAI,UAAU,cAAc;AAC1B,wBAAY,qBAAqB,UAAU,YAAY;AAAA;AAAA,UACzD;AACA,sBAAY;AAAA,QACd,WAAW,UAAU,SAAS,YAAY,UAAU,OAAO;AACzD,sBAAY;AAAA;AAAA;AACZ,sBAAY,kBAAkB,UAAU,KAAK;AAAA,QAC/C,WAAW,UAAU,SAAS,iBAAiB;AAC7C,sBAAY;AAAA;AACZ,sBAAY,sBAAsB,UAAU,gBAAgB;AAAA;AAAA;AAAA,QAC9D;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AAAA,IACL,IAAI;AAAA,IACJ,KAAK;AAAA,IACL,OAAO;AAAA,IACP,aAAa;AAAA,IACb,SAAS;AAAA,EACX;AACF;",
+  "names": []
+}

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

@@ -0,0 +1,4 @@
+import type { SidebarData } from '../sidebar.js';
+import type { OurOpenAPIObject } from '../types.js';
+export declare function extractOverviewDocs(spec: OurOpenAPIObject, availableSdks?: string[]): SidebarData;
+//# sourceMappingURL=overview-docs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"overview-docs.d.ts","sourceRoot":"","sources":["../../../src/lib/overview-docs/overview-docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAKpD,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,gBAAgB,EACtB,aAAa,GAAE,MAAM,EAAmB,GACvC,WAAW,CAYb"}

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

@@ -0,0 +1,20 @@
+import { generateAuthOverview } from "./overview-auth.js";
+import { generateErrorsOverview } from "./overview-errors.js";
+import { generateIntroOverview } from "./overview-intro.js";
+function extractOverviewDocs(spec, availableSdks = ["typescript"]) {
+  return [
+    {
+      id: "overview",
+      category: "Overview",
+      items: [
+        generateIntroOverview(spec, availableSdks),
+        generateAuthOverview(spec),
+        generateErrorsOverview(spec)
+      ]
+    }
+  ];
+}
+export {
+  extractOverviewDocs
+};
+//# sourceMappingURL=overview-docs.js.map

package/dist/lib/overview-docs/overview-docs.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/overview-docs/overview-docs.ts"],
+  "sourcesContent": ["import type { SidebarData } from '../sidebar.js';\nimport type { OurOpenAPIObject } from '../types.js';\nimport { generateAuthOverview } from './overview-auth.js';\nimport { generateErrorsOverview } from './overview-errors.js';\nimport { generateIntroOverview } from './overview-intro.js';\n\nexport function extractOverviewDocs(\n  spec: OurOpenAPIObject,\n  availableSdks: string[] = ['typescript'],\n): SidebarData {\n  return [\n    {\n      id: 'overview',\n      category: 'Overview',\n      items: [\n        generateIntroOverview(spec, availableSdks),\n        generateAuthOverview(spec),\n        generateErrorsOverview(spec),\n      ],\n    },\n  ];\n}\n"],
+  "mappings": "AAEA,SAAS,4BAA4B;AACrC,SAAS,8BAA8B;AACvC,SAAS,6BAA6B;AAE/B,SAAS,oBACd,MACA,gBAA0B,CAAC,YAAY,GAC1B;AACb,SAAO;AAAA,IACL;AAAA,MACE,IAAI;AAAA,MACJ,UAAU;AAAA,MACV,OAAO;AAAA,QACL,sBAAsB,MAAM,aAAa;AAAA,QACzC,qBAAqB,IAAI;AAAA,QACzB,uBAAuB,IAAI;AAAA,MAC7B;AAAA,IACF;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/lib/overview-docs/overview-errors.d.ts

@@ -0,0 +1,4 @@
+import type { NavItem } from '../sidebar.js';
+import type { OurOpenAPIObject } from '../types.js';
+export declare function generateErrorsOverview(spec: OurOpenAPIObject): NavItem;
+//# sourceMappingURL=overview-errors.d.ts.map

package/dist/lib/overview-docs/overview-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overview-errors.d.ts","sourceRoot":"","sources":["../../../src/lib/overview-docs/overview-errors.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AA6GpD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAyFtE"}

package/dist/lib/overview-docs/overview-errors.js

@@ -0,0 +1,137 @@
+import { resolveRef } from "@sdk-it/core";
+import { forEachOperation } from "../for-each-operation.js";
+import { isErrorStatusCode } from "../is.js";
+function resolveSchema(spec, schema) {
+  return resolveRef(spec, schema);
+}
+function formatSchemaForDisplay(spec, schema) {
+  const resolvedSchema = resolveSchema(spec, schema);
+  return `\`\`\`json
+${JSON.stringify(resolvedSchema, null, 2)}
+\`\`\``;
+}
+function getStatusDescription(statusCode) {
+  const descriptions = {
+    "400": "Bad Request - The request was invalid or cannot be served.",
+    "401": "Unauthorized - Authentication is required and has failed or has not been provided.",
+    "402": "Payment Required - Payment is required to access this resource.",
+    "403": "Forbidden - The request was valid, but the server is refusing action.",
+    "404": "Not Found - The requested resource could not be found.",
+    "405": "Method Not Allowed - The request method is not supported for this resource.",
+    "406": "Not Acceptable - The requested resource cannot generate content acceptable to the client.",
+    "407": "Proxy Authentication Required - Authentication with the proxy is required.",
+    "408": "Request Timeout - The server timed out waiting for the request.",
+    "409": "Conflict - The request could not be completed due to a conflict.",
+    "410": "Gone - The requested resource is no longer available.",
+    "411": "Length Required - The request did not specify the length of its content.",
+    "412": "Precondition Failed - The server does not meet one of the preconditions.",
+    "413": "Payload Too Large - The request is larger than the server is willing to process.",
+    "414": "URI Too Long - The URI provided was too long for the server to process.",
+    "415": "Unsupported Media Type - The request entity has a media type which the server does not support.",
+    "416": "Range Not Satisfiable - The client has asked for a portion of the file that the server cannot supply.",
+    "417": "Expectation Failed - The server cannot meet the requirements of the Expect request-header field.",
+    "418": "I'm a teapot - The server refuses the attempt to brew coffee with a teapot.",
+    "421": "Misdirected Request - The request was directed at a server that is not able to produce a response.",
+    "422": "Unprocessable Entity - The request was well-formed but contains semantic errors.",
+    "423": "Locked - The resource that is being accessed is locked.",
+    "424": "Failed Dependency - The request failed due to failure of a previous request.",
+    "425": "Too Early - The server is unwilling to risk processing a request that might be replayed.",
+    "426": "Upgrade Required - The client should switch to a different protocol.",
+    "428": "Precondition Required - The origin server requires the request to be conditional.",
+    "429": "Too Many Requests - The user has sent too many requests in a given amount of time.",
+    "431": "Request Header Fields Too Large - The server is unwilling to process the request because header fields are too large.",
+    "451": "Unavailable For Legal Reasons - The server is denying access to the resource for legal reasons.",
+    "500": "Internal Server Error - The server encountered an unexpected condition.",
+    "501": "Not Implemented - The server does not support the functionality required to fulfill the request.",
+    "502": "Bad Gateway - The server received an invalid response from the upstream server.",
+    "503": "Service Unavailable - The server is currently unavailable.",
+    "504": "Gateway Timeout - The server did not receive a timely response from the upstream server.",
+    "505": "HTTP Version Not Supported - The server does not support the HTTP protocol version used in the request.",
+    "506": "Variant Also Negotiates - The server has an internal configuration error.",
+    "507": "Insufficient Storage - The server is unable to store the representation needed to complete the request.",
+    "508": "Loop Detected - The server detected an infinite loop while processing the request.",
+    "510": "Not Extended - Further extensions to the request are required for the server to fulfill it.",
+    "511": "Network Authentication Required - The client needs to authenticate to gain network access."
+  };
+  return descriptions[statusCode] || "An error occurred while processing the request.";
+}
+function generateErrorsOverview(spec) {
+  const errorSchemas = /* @__PURE__ */ new Map();
+  const markdown = [];
+  markdown.push(`# Error Handling`);
+  markdown.push(
+    `This API uses conventional HTTP response codes to indicate the success or failure of an API request.`
+  );
+  markdown.push(`## Official API Clients`);
+  markdown.push(
+    `Vellum maintains official API clients for Python, Node/Typescript, and Go. We recommend using these clients to interact with all stable endpoints. You can find them here:`
+  );
+  markdown.push(`## HTTP Status Codes`);
+  forEachOperation(spec, (entry, operation) => {
+    if (operation.responses) {
+      for (const [statusCode, response] of Object.entries(
+        operation.responses
+      )) {
+        if (isErrorStatusCode(statusCode)) {
+          const content = response.content;
+          if (content?.["application/json"]?.schema) {
+            const key = `${statusCode}`;
+            const operationId = `${entry.method.toUpperCase()} ${entry.path}`;
+            if (!errorSchemas.has(key)) {
+              errorSchemas.set(key, {
+                statusCode,
+                title: response.description || `${statusCode} Error`,
+                description: response.description,
+                schema: content["application/json"].schema,
+                operations: [operationId]
+              });
+            } else {
+              const existing = errorSchemas.get(key);
+              if (existing && !existing.operations.includes(operationId)) {
+                existing.operations.push(operationId);
+              }
+            }
+          }
+        }
+      }
+    }
+  });
+  const errors = Array.from(errorSchemas.values()).sort(
+    (a, b) => parseInt(a.statusCode) - parseInt(b.statusCode)
+  );
+  if (errors.length === 0) {
+    markdown.push(
+      `No error responses are documented in this API specification.`
+    );
+  } else {
+    for (const error of errors) {
+      markdown.push(`### ${error.statusCode} - ${error.title}`);
+      const description = error.description || getStatusDescription(error.statusCode);
+      if (description) {
+        markdown.push(description);
+      }
+      if (error.operations.length > 0) {
+        const operationsList = [`**Used by operations:**`];
+        for (const operation of error.operations) {
+          operationsList.push(`- \`${operation}\``);
+        }
+        markdown.push(operationsList.join("\n"));
+      }
+      if (error.schema) {
+        markdown.push(`**Response Schema:**`);
+        markdown.push(formatSchemaForDisplay(spec, error.schema));
+      }
+    }
+  }
+  return {
+    id: "errors",
+    title: "Errors",
+    url: "/errors",
+    description: "Error handling and HTTP status codes",
+    content: markdown.join("\n\n")
+  };
+}
+export {
+  generateErrorsOverview
+};
+//# sourceMappingURL=overview-errors.js.map

package/dist/lib/overview-docs/overview-errors.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/overview-docs/overview-errors.ts"],
+  "sourcesContent": ["import type { ReferenceObject, SchemaObject } from 'openapi3-ts/oas31';\n\nimport { resolveRef } from '@sdk-it/core';\n\nimport { forEachOperation } from '../for-each-operation.js';\nimport { isErrorStatusCode } from '../is.js';\nimport type { NavItem } from '../sidebar.js';\nimport type { OurOpenAPIObject } from '../types.js';\n\ninterface ErrorSchema {\n  statusCode: string;\n  title: string;\n  description?: string;\n  schema: SchemaObject | ReferenceObject;\n  operations: string[]; // Track which operations use this error\n}\n\nfunction resolveSchema(\n  spec: OurOpenAPIObject,\n  schema: SchemaObject | ReferenceObject,\n): SchemaObject {\n  return resolveRef<SchemaObject>(spec, schema);\n}\n\nfunction formatSchemaForDisplay(\n  spec: OurOpenAPIObject,\n  schema: SchemaObject | ReferenceObject,\n): string {\n  const resolvedSchema = resolveSchema(spec, schema);\n\n  return `\\`\\`\\`json\n${JSON.stringify(resolvedSchema, null, 2)}\n\\`\\`\\``;\n}\n\nfunction getStatusDescription(statusCode: string): string {\n  const descriptions: Record<string, string> = {\n    '400': 'Bad Request - The request was invalid or cannot be served.',\n    '401':\n      'Unauthorized - Authentication is required and has failed or has not been provided.',\n    '402': 'Payment Required - Payment is required to access this resource.',\n    '403':\n      'Forbidden - The request was valid, but the server is refusing action.',\n    '404': 'Not Found - The requested resource could not be found.',\n    '405':\n      'Method Not Allowed - The request method is not supported for this resource.',\n    '406':\n      'Not Acceptable - The requested resource cannot generate content acceptable to the client.',\n    '407':\n      'Proxy Authentication Required - Authentication with the proxy is required.',\n    '408': 'Request Timeout - The server timed out waiting for the request.',\n    '409': 'Conflict - The request could not be completed due to a conflict.',\n    '410': 'Gone - The requested resource is no longer available.',\n    '411':\n      'Length Required - The request did not specify the length of its content.',\n    '412':\n      'Precondition Failed - The server does not meet one of the preconditions.',\n    '413':\n      'Payload Too Large - The request is larger than the server is willing to process.',\n    '414':\n      'URI Too Long - The URI provided was too long for the server to process.',\n    '415':\n      'Unsupported Media Type - The request entity has a media type which the server does not support.',\n    '416':\n      'Range Not Satisfiable - The client has asked for a portion of the file that the server cannot supply.',\n    '417':\n      'Expectation Failed - The server cannot meet the requirements of the Expect request-header field.',\n    '418':\n      \"I'm a teapot - The server refuses the attempt to brew coffee with a teapot.\",\n    '421':\n      'Misdirected Request - The request was directed at a server that is not able to produce a response.',\n    '422':\n      'Unprocessable Entity - The request was well-formed but contains semantic errors.',\n    '423': 'Locked - The resource that is being accessed is locked.',\n    '424':\n      'Failed Dependency - The request failed due to failure of a previous request.',\n    '425':\n      'Too Early - The server is unwilling to risk processing a request that might be replayed.',\n    '426':\n      'Upgrade Required - The client should switch to a different protocol.',\n    '428':\n      'Precondition Required - The origin server requires the request to be conditional.',\n    '429':\n      'Too Many Requests - The user has sent too many requests in a given amount of time.',\n    '431':\n      'Request Header Fields Too Large - The server is unwilling to process the request because header fields are too large.',\n    '451':\n      'Unavailable For Legal Reasons - The server is denying access to the resource for legal reasons.',\n    '500':\n      'Internal Server Error - The server encountered an unexpected condition.',\n    '501':\n      'Not Implemented - The server does not support the functionality required to fulfill the request.',\n    '502':\n      'Bad Gateway - The server received an invalid response from the upstream server.',\n    '503': 'Service Unavailable - The server is currently unavailable.',\n    '504':\n      'Gateway Timeout - The server did not receive a timely response from the upstream server.',\n    '505':\n      'HTTP Version Not Supported - The server does not support the HTTP protocol version used in the request.',\n    '506':\n      'Variant Also Negotiates - The server has an internal configuration error.',\n    '507':\n      'Insufficient Storage - The server is unable to store the representation needed to complete the request.',\n    '508':\n      'Loop Detected - The server detected an infinite loop while processing the request.',\n    '510':\n      'Not Extended - Further extensions to the request are required for the server to fulfill it.',\n    '511':\n      'Network Authentication Required - The client needs to authenticate to gain network access.',\n  };\n  return (\n    descriptions[statusCode] ||\n    'An error occurred while processing the request.'\n  );\n}\n\nexport function generateErrorsOverview(spec: OurOpenAPIObject): NavItem {\n  const errorSchemas: Map<string, ErrorSchema> = new Map();\n  const markdown: string[] = [];\n  markdown.push(`# Error Handling`);\n  markdown.push(\n    `This API uses conventional HTTP response codes to indicate the success or failure of an API request.`,\n  );\n  markdown.push(`## Official API Clients`);\n  markdown.push(\n    `Vellum maintains official API clients for Python, Node/Typescript, and Go. We recommend using these clients to interact with all stable endpoints. You can find them here:`,\n  );\n  markdown.push(`## HTTP Status Codes`);\n\n  // First, collect all error schemas from operations\n  forEachOperation(spec, (entry, operation) => {\n    if (operation.responses) {\n      for (const [statusCode, response] of Object.entries(\n        operation.responses,\n      )) {\n        if (isErrorStatusCode(statusCode)) {\n          const content = response.content;\n          if (content?.['application/json']?.schema) {\n            const key = `${statusCode}`;\n            const operationId = `${entry.method.toUpperCase()} ${entry.path}`;\n\n            if (!errorSchemas.has(key)) {\n              errorSchemas.set(key, {\n                statusCode,\n                title: response.description || `${statusCode} Error`,\n                description: response.description,\n                schema: content['application/json'].schema as\n                  | SchemaObject\n                  | ReferenceObject,\n                operations: [operationId],\n              });\n            } else {\n              // Add this operation to the existing error schema\n              const existing = errorSchemas.get(key);\n              if (existing && !existing.operations.includes(operationId)) {\n                existing.operations.push(operationId);\n              }\n            }\n          }\n        }\n      }\n    }\n  });\n\n  // Then sort and generate documentation\n  const errors = Array.from(errorSchemas.values()).sort(\n    (a, b) => parseInt(a.statusCode) - parseInt(b.statusCode),\n  );\n\n  if (errors.length === 0) {\n    markdown.push(\n      `No error responses are documented in this API specification.`,\n    );\n  } else {\n    for (const error of errors) {\n      markdown.push(`### ${error.statusCode} - ${error.title}`);\n      const description =\n        error.description || getStatusDescription(error.statusCode);\n      if (description) {\n        markdown.push(description);\n      }\n\n      // Show which operations return this error\n      if (error.operations.length > 0) {\n        const operationsList = [`**Used by operations:**`];\n        for (const operation of error.operations) {\n          operationsList.push(`- \\`${operation}\\``);\n        }\n        markdown.push(operationsList.join('\\n'));\n      }\n\n      if (error.schema) {\n        markdown.push(`**Response Schema:**`);\n        markdown.push(formatSchemaForDisplay(spec, error.schema));\n      }\n    }\n  }\n\n  return {\n    id: 'errors',\n    title: 'Errors',\n    url: '/errors',\n    description: 'Error handling and HTTP status codes',\n    content: markdown.join('\\n\\n'),\n  };\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/lib/overview-docs/overview-intro.d.ts

@@ -0,0 +1,4 @@
+import type { NavItem } from '../sidebar.js';
+import type { OurOpenAPIObject } from '../types.js';
+export declare function generateIntroOverview(spec: OurOpenAPIObject, availablesdks?: string[]): NavItem;
+//# sourceMappingURL=overview-intro.d.ts.map

package/dist/lib/overview-docs/overview-intro.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overview-intro.d.ts","sourceRoot":"","sources":["../../../src/lib/overview-docs/overview-intro.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,gBAAgB,EACtB,aAAa,WAAiB,GAC7B,OAAO,CAgFT"}