@stainless-api/docs 0.1.0-beta.7 → 0.1.0-beta.70

package/package.json

@@ -1,32 +1,27 @@
 {
   "name": "@stainless-api/docs",
-  "version": "0.1.0-beta.7",
+  "version": "0.1.0-beta.70",
   "publishConfig": {
     "access": "public"
   },
   "description": "",
   "type": "module",
   "exports": {
+    ".": "./stl-docs/index.ts",
     "./plugin": "./plugin/index.ts",
-    "./OverviewRoute": "./plugin/routes/Overview.astro",
-    "./DocsRoute": "./plugin/routes/Docs.astro",
-    "./DocsStaticRoute": "./plugin/routes/DocsStatic.astro",
-    "./MarkdownRoute": "./plugin/routes/markdown.ts",
-    "./Search": "./plugin/components/search/Search.astro",
-    "./replaceSidebarPlaceholderMiddleware": "./plugin/replaceSidebarPlaceholderMiddleware.ts",
     "./plugin/middleware": "./plugin/middlewareBuilder/stlStarlightMiddleware.ts",
     "./plugin/MiddlewareTypes": "./plugin/middlewareBuilder/stainlessMiddleware.d.ts",
-    "./stainless-docs": "./stl-docs/index.ts",
-    "./Header": "./stl-docs/components/Header.astro",
-    "./ThemeSelect": "./stl-docs/components/ThemeSelect.astro",
-    "./BaseSidebar": "./stl-docs/components/sidebars/BaseSidebar.astro",
-    "./SDKSelectSidebar": "./stl-docs/components/sidebars/SDKSelectSidebar.astro",
-    "./ContentPanel": "./stl-docs/components/content-panel/ContentPanel.astro",
-    "./tabsMiddleware": "./stl-docs/tabsMiddleware.ts",
+    "./plugin/languages": "./plugin/languages.ts",
     "./stainless-docs/mintlify-compat": "./stl-docs/components/mintlify-compat/index.ts",
-    "./theme": "./theme.css",
     "./mintlify-compat.css": "./styles/mintlify-compat.css",
-    "./font-imports": "./styles/fonts.css"
+    "./font-imports": "./styles/fonts.css",
+    "./components": "./stl-docs/components/index.ts",
+    "./components/scripts": "./stl-docs/components/scripts.ts",
+    "./docs-config": "./stl-docs/loadStlDocsConfig.ts",
+    "./cms-client": "./plugin/cms/client.ts",
+    "./generate-docs-routes": "./plugin/helpers/generateDocsRoutes.ts",
+    "./components/Head": "./stl-docs/components/Head.astro",
+    "./components/ContentBreadcrumbs": "./stl-docs/components/ContentBreadcrumbs.tsx"
   },
   "keywords": [],
   "author": "",
@@ -35,41 +30,57 @@
     "node": ">=18.17.1"
   },
   "peerDependencies": {
-    "@astrojs/starlight": ">=0.34.0",
-    "astro": ">=5.5.0"
+    "@astrojs/starlight": ">=0.37.0",
+    "astro": ">=5.15.3",
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0",
+    "vite": ">=6.2.1"
   },
   "dependencies": {
-    "@astrojs/markdown-remark": "^6.3.2",
-    "@astrojs/react": "^4.3.1",
-    "@stainless-api/sdk": "0.1.0-alpha.12",
+    "@astrojs/markdown-remark": "^6.3.10",
+    "@astrojs/react": "^4.4.2",
+    "@stainless-api/sdk": "0.1.0-alpha.19",
+    "astro-expressive-code": "^0.41.3",
     "cheerio": "^1.1.2",
     "clsx": "^2.1.1",
-    "dotenv": "17.2.2",
+    "dotenv": "17.2.3",
     "get-port": "^7.1.0",
-    "highlight.js": "^11.11.1",
-    "lucide-react": "^0.544.0",
-    "marked": "^16.0.0",
-    "react": "^19.1.1",
-    "react-dom": "^19.1.1",
+    "lucide-react": "^0.562.0",
+    "marked": "^17.0.1",
+    "node-html-parser": "^7.0.1",
+    "rehype-parse": "^9.0.1",
+    "rehype-remark": "^10.0.1",
+    "remark-gfm": "^4.0.1",
     "remark-github-alerts": "^0.1.1",
-    "shiki": "^3.9.2",
+    "remark-stringify": "^11.0.0",
+    "shiki": "^3.20.0",
+    "unified": "^11.0.5",
+    "vite-plugin-prebundle-workers": "^0.2.0",
     "web-worker": "^1.5.0",
-    "yaml": "^2.8.0",
-    "@stainless-api/docs-ui": "0.1.0-beta.6",
-    "@stainless-api/ui-primitives": "0.1.0-beta.7"
+    "yaml": "^2.8.2",
+    "@stainless-api/docs-search": "0.1.0-beta.7",
+    "@stainless-api/docs-ui": "0.1.0-beta.55",
+    "@stainless-api/ui-primitives": "0.1.0-beta.41"
   },
   "devDependencies": {
-    "@markdoc/markdoc": "^0.5.2",
-    "@types/node": "^24.4.0",
-    "@types/react": "^19.1.13",
-    "@types/react-dom": "^19.1.9",
-    "tsx": "^4.20.3",
-    "zod": "^4.0.0",
-    "@stainless/eslint-config": "0.0.0"
+    "@astrojs/check": "^0.9.6",
+    "@markdoc/markdoc": "^0.5.4",
+    "@types/node": "24.10.4",
+    "@types/react": "19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "tsx": "^4.21.0",
+    "typescript": "5.9.3",
+    "vite": "^6.4.1",
+    "zod": "^4.3.5",
+    "@stainless/eslint-config": "0.1.0-beta.1",
+    "@stainless/sdk-json": "^0.1.0-beta.2"
   },
   "scripts": {
-    "vendor-deps": "pnpm tsx scripts/vendor_deps.ts",
+    "vendor-deps": "tsx scripts/vendor_deps.ts",
     "lint": "eslint . --max-warnings 0",
-    "sync": "astro sync"
+    "sync": "astro sync",
+    "check:types": "astro check"
   }
 }

package/plugin/assets/languages/csharp.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" fill="none"><defs><linearGradient id="a-_r_1_" x1="46.77" x2="69.91" y1="86.46" y2="126.73" gradientTransform="matrix(8.78996,0,0,8.78996,-233.98,-518.97)" gradientUnits="userSpaceOnUse"><stop stop-color="#927be5"></stop><stop offset="1" stop-color="#512bd4"></stop></linearGradient><filter id="b-_r_1_" width="42.84" height="39.14" x="44.63" y="91.89" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"></feFlood><feColorMatrix in="SourceAlpha" result="hardAlpha" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"></feColorMatrix><feOffset></feOffset><feColorMatrix values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.1 0"></feColorMatrix><feBlend in2="BackgroundImageFix" result="effect1_dropShadow_2037_2800"></feBlend><feColorMatrix in="SourceAlpha" result="hardAlpha" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"></feColorMatrix><feOffset dy="1"></feOffset><feGaussianBlur stdDeviation="2.5"></feGaussianBlur><feColorMatrix values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.1 0"></feColorMatrix><feBlend in2="effect1_dropShadow_2037_2800" result="effect2_dropShadow_2037_2800"></feBlend><feColorMatrix in="SourceAlpha" result="hardAlpha" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"></feColorMatrix><feOffset dy="4"></feOffset><feGaussianBlur stdDeviation="2"></feGaussianBlur><feColorMatrix values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.09 0"></feColorMatrix><feBlend in2="effect2_dropShadow_2037_2800" result="effect3_dropShadow_2037_2800"></feBlend><feColorMatrix in="SourceAlpha" result="hardAlpha" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"></feColorMatrix><feOffset dy="9"></feOffset><feGaussianBlur stdDeviation="2.5"></feGaussianBlur><feColorMatrix values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.05 0"></feColorMatrix><feBlend in2="effect3_dropShadow_2037_2800" result="effect4_dropShadow_2037_2800"></feBlend><feColorMatrix in="SourceAlpha" result="hardAlpha" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"></feColorMatrix><feOffset dy="15"></feOffset><feGaussianBlur stdDeviation="3"></feGaussianBlur><feColorMatrix values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.01 0"></feColorMatrix><feBlend in2="effect4_dropShadow_2037_2800" result="effect5_dropShadow_2037_2800"></feBlend><feBlend in="SourceGraphic" in2="effect5_dropShadow_2037_2800" result="shape"></feBlend></filter></defs><path fill="url(#a-_r_1_)" d="M135.73 285.85v173.93a60.2 60.2 0 0 0 30.13 52.17l150.62 86.97a60.2 60.2 0 0 0 60.25 0l150.62-86.97a60.2 60.2 0 0 0 30.13-52.17V285.85a60.2 60.2 0 0 0-30.13-52.18l-150.62-86.95a60.2 60.2 0 0 0-60.25 0l-150.62 86.95a60.3 60.3 0 0 0-30.13 52.18" transform="scale(0.44288615) matrix(0.1,0,0,0.1,-7.57,-10.19)"></path><path fill="#fff" d="M54.06 98.03v6.86a1.7 1.7 0 0 0 1.71 1.7 1.7 1.7 0 0 0 1.71-1.7 1.71 1.71 0 1 1 3.43 0 5.14 5.14 0 1 1-10.28 0v-6.86a5.14 5.14 0 1 1 10.28 0 1.71 1.71 0 1 1-3.43 0 1.71 1.71 0 1 0-3.42 0zm27.41 6.86a1.7 1.7 0 0 1-1.71 1.7h-1.71v1.72c0 .46-.18.9-.5 1.21a1.7 1.7 0 0 1-2.43 0 1.7 1.7 0 0 1-.5-1.2v-1.72h-3.43v1.71a1.7 1.7 0 0 1-1.71 1.72 1.7 1.7 0 0 1-1.72-1.72v-1.71h-1.71a1.71 1.71 0 1 1 0-3.43h1.71v-3.43h-1.71a1.71 1.71 0 1 1 0-3.42h1.71V94.6a1.71 1.71 0 1 1 3.43 0v1.72h3.43V94.6a1.71 1.71 0 1 1 3.43 0v1.72h1.7c.46 0 .9.18 1.22.5a1.7 1.7 0 0 1 0 2.42 1.7 1.7 0 0 1-1.21.5h-1.71v3.43h1.7a1.7 1.7 0 0 1 1.72 1.71m-6.85-5.14h-3.43v3.42h3.43z" filter="url(#b-_r_1_)" style="mix-blend-mode: screen;" transform="scale(0.44288615) matrix(0.879,0,0,0.879,-30.96,-62.09)"></path></svg>

package/plugin/buildAlgoliaIndex.ts

@@ -1,10 +1,11 @@
 import Markdoc from '@markdoc/markdoc';
 import Stainless from '@stainless-api/sdk';
 import { createSDKJSON, parseInputs, transformOAS } from './cms/worker';
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
-import { Languages } from '@stainless-api/docs-ui/src/routing';
-import { buildIndex } from '@stainless-api/docs-ui/src/search/providers/algolia';
+import type * as SDKJSON from '@stainless/sdk-json';
+import { Languages } from '@stainless-api/docs-ui/routing';
+import { buildIndex } from '@stainless-api/docs-search/providers/algolia';
 import type { VersionUserConfig } from './loadPluginConfig';
+import type { AstroIntegrationLogger } from 'astro';
 
 const markdocConfig = {
   nodes: {
@@ -20,7 +21,31 @@ function renderMarkdown(content?: string) {
   return Markdoc.renderers.html(transformed);
 }
 
-export async function buildAlgoliaIndex({ version, apiKey }: { version: VersionUserConfig; apiKey: string }) {
+export async function buildAlgoliaIndex({
+  version,
+  apiKey,
+  logger,
+}: {
+  version: VersionUserConfig;
+  apiKey: string;
+  logger?: AstroIntegrationLogger;
+}) {
+  function warnLog(message: string) {
+    if (logger) {
+      logger.warn(message);
+    } else {
+      console.warn(message);
+    }
+  }
+
+  function infoLog(message: string) {
+    if (logger) {
+      logger.info(message);
+    } else {
+      console.log(message);
+    }
+  }
+
   const client = new Stainless({ apiKey });
   const configs = await client.projects.configs.retrieve({
     project: version.stainlessProject,
@@ -42,7 +67,6 @@ export async function buildAlgoliaIndex({ version, apiKey }: { version: VersionU
   const languages =
     config.docs?.languages ??
     (Object.entries(config.targets)
-      // @ts-expect-error we don't have the actual Stainless config type here
       .filter(([name, target]) => Languages.includes(name) && !target.skip)
       .map(([name]) => name) as SDKJSON.SpecLanguage[]);
 
@@ -50,6 +74,7 @@ export async function buildAlgoliaIndex({ version, apiKey }: { version: VersionU
     oas: transformedOAS,
     config,
     languages,
+    version,
   });
 
   const {
@@ -64,9 +89,9 @@ export async function buildAlgoliaIndex({ version, apiKey }: { version: VersionU
       !indexName && 'PUBLIC_ALGOLIA_INDEX',
       !algoliaWriteKey && 'PRIVATE_ALGOLIA_WRITE_KEY',
     ].filter(Boolean);
-    console.warn(`⚠️ Skipping Algolia indexing due to missing environment variables: ${missing.join(', ')}`);
+    warnLog(`Skipping Algolia indexing due to missing environment variables: ${missing.join(', ')}`);
     return;
   }
   await buildIndex(appId, indexName, algoliaWriteKey, sdkJson, renderMarkdown);
-  console.log('Indexing complete.');
+  infoLog('Indexing complete.');
 }

package/plugin/cms/server.ts

@@ -1,10 +1,11 @@
+import type { AstroIntegrationLogger } from 'astro';
 import { createServer, IncomingMessage } from 'http';
 import { readFile } from 'fs/promises';
 
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
+import type * as SDKJSON from '@stainless/sdk-json';
 import { createSDKJSON, parseInputs, transformOAS } from './worker';
-import { Languages, parseRoute, type DocsLanguage } from '@stainless-api/docs-ui/src/routing';
-import Stainless from '@stainless-api/sdk';
+import { Languages, parseRoute, type DocsLanguage } from '@stainless-api/docs-ui/routing';
+import Stainless, { APIError } from '@stainless-api/sdk';
 
 import {
   toStarlightSidebar,
@@ -12,92 +13,150 @@ import {
   SidebarConfigItemsBuilder,
 } from './sidebar-builder';
 import type { VersionUserConfig } from '../loadPluginConfig';
-
+import { bold } from '../../shared/terminalUtils';
 export type InputFilePaths = {
   oasPath?: string;
   configPath?: string;
 };
 
-async function versionInfo(project: string, apiKey: string) {
+async function versionInfo(project: string, apiKey: string): Promise<Record<DocsLanguage, string>> {
   const data = await fetch(`https://api.stainless.com/api/projects/${project}/package-versions`, {
     headers: { Authorization: `Bearer ${apiKey}` },
   });
 
   const content = await data.text();
-  return JSON.parse(content);
+  return JSON.parse(content) as Record<DocsLanguage, string>;
+}
+
+function redactApiKey(apiKey: string) {
+  return apiKey
+    .split('')
+    .map((char, index) => (index < 10 ? char : '*'))
+    .join('');
 }
 
+export type Auth = Array<{
+  type: 'http_bearer' | 'query' | 'header' | 'oauth2' | 'http_basic' | 'http_digest';
+  description?: string;
+  name: string;
+  title: string;
+  header: string | undefined;
+  example: string | undefined;
+  opts: {
+    type: 'string' | 'number' | 'boolean' | 'null' | 'integer';
+    nullable: boolean;
+    description?: string | undefined;
+    example?: unknown;
+    default?: unknown;
+    read_env?: string | undefined;
+    auth?:
+      | {
+          security_scheme: string;
+          role?: 'value' | 'password' | 'username' | 'client_id' | 'client_secret' | undefined;
+        }
+      | undefined;
+    name: string;
+  }[];
+}>;
+
 async function loadSpec({
   apiKey,
   devPaths,
   version,
+  logger,
 }: {
   apiKey: string;
   devPaths: InputFilePaths;
   version: VersionUserConfig;
-}) {
-  let oasStr: string;
-  let configStr: string;
-  let versions: Record<DocsLanguage, string> | undefined;
-
-  if (devPaths.oasPath && devPaths.configPath) {
-    [oasStr, configStr] = await Promise.all([
-      readFile(devPaths.oasPath, 'utf-8'),
-      readFile(devPaths.configPath, 'utf-8'),
-    ]);
-  } else {
-    const client = new Stainless({ apiKey });
-    const configs = await client.projects.configs.retrieve({
-      project: version.stainlessProject,
-      branch: version.branch,
-      include: 'openapi',
-    });
+  logger: AstroIntegrationLogger;
+}): Promise<{ data: SDKJSON.Spec; auth: Auth; id: string }> {
+  async function unsafeLoad(): Promise<{ data: SDKJSON.Spec; auth: Auth; id: string }> {
+    let oasStr: string;
+    let configStr: string;
+    let versions: Record<DocsLanguage, string> | undefined;
+
+    if (devPaths.oasPath && devPaths.configPath) {
+      [oasStr, configStr] = await Promise.all([
+        readFile(devPaths.oasPath, 'utf-8'),
+        readFile(devPaths.configPath, 'utf-8'),
+      ]);
+    } else {
+      const client = new Stainless({ apiKey });
+      const configs = await client.projects.configs.retrieve({
+        project: version.stainlessProject,
+        branch: version.branch,
+        include: 'openapi',
+      });
 
-    versions = await versionInfo(version.stainlessProject, apiKey);
+      versions = await versionInfo(version.stainlessProject, apiKey);
 
-    const configYML = Object.values(configs)[0] as { content: any };
-    const oasJson = Object.values(configs)[1] as { content: any };
-    oasStr = oasJson['content'];
-    configStr = configYML['content'];
-  }
+      const configYML = Object.values(configs)[0] as { content: any };
+      const oasJson = Object.values(configs)[1] as { content: any };
+      oasStr = oasJson['content'];
+      configStr = configYML['content'];
+    }
 
-  const { oas, config } = await parseInputs({
-    oas: oasStr,
-    config: configStr,
-  });
+    const { oas, config } = await parseInputs({
+      oas: oasStr,
+      config: configStr,
+    });
 
-  const transformedOAS = await transformOAS({ oas, config });
+    const transformedOAS = await transformOAS({ oas, config });
 
-  const languages =
-    config.docs?.languages ??
-    (Object.entries(config.targets)
-      // @ts-expect-error we don't have the actual Stainless config type here
-      .filter(([name, target]) => Languages.includes(name) && !target.skip)
-      .map(([name]) => name) as SDKJSON.SpecLanguage[]);
+    const languages =
+      config.docs?.languages ??
+      (Object.entries(config.targets)
+        .filter(([name, target]) => Languages.includes(name) && !target.skip)
+        .map(([name]) => name) as SDKJSON.SpecLanguage[]);
 
-  const sdkJson = await createSDKJSON({
-    oas: transformedOAS,
-    config,
-    languages,
-  });
+    const sdkJson = await createSDKJSON({
+      oas: transformedOAS,
+      config,
+      languages,
+      version,
+    });
 
-  if (versions) {
-    for (const [lang, version] of Object.entries(versions)) {
-      const meta = sdkJson.metadata[lang as DocsLanguage];
-      if (meta?.version) meta.version = version;
+    if (versions) {
+      for (const [lang, version] of Object.entries(versions)) {
+        const meta = sdkJson.metadata[lang as DocsLanguage];
+        if (meta?.version) meta.version = version;
+      }
     }
+
+    const id = crypto.randomUUID();
+    const opts = Object.entries(config.client_settings.opts).map(([k, v]) => ({ name: k, ...v }));
+
+    return {
+      data: sdkJson,
+      auth: sdkJson.security_schemes.map((scheme) => ({
+        ...scheme,
+        opts: opts.filter((opt) => opt.auth?.security_scheme === scheme.name),
+      })),
+      id,
+    };
   }
 
-  const id = crypto.randomUUID();
+  try {
+    const result = await unsafeLoad();
+    return result;
+  } catch (error) {
+    logger.error(bold('Failed to fetch API reference information from Stainless:'));
+    if (error instanceof APIError && error.status >= 400 && error.status < 500) {
+      logger.error(`Requested project slug: "${version.stainlessProject}"`);
+      logger.error(`API key: "${redactApiKey(apiKey)}"`);
+      logger.error(
+        `This error can usually be corrected by re-authenticating with the Stainless.  Use the CLI (stl auth login) or verify that the Stainless API key you're using can access the project mentioned above.`,
+      );
+    } else {
+      logger.error(error instanceof Error ? error.message : 'Unknown error');
+    }
 
-  return {
-    data: sdkJson,
-    id,
-  };
+    process.exit(1);
+  }
 }
 
 class Spec {
-  private specPromise: Promise<{ id: string; data: SDKJSON.Spec }>;
+  private specPromise: Promise<{ id: string; data: SDKJSON.Spec; auth: Auth }>;
   private devPaths: InputFilePaths;
   private apiKey: string;
   private version: VersionUserConfig;
@@ -107,6 +166,7 @@ class Spec {
       apiKey: this.apiKey,
       devPaths: this.devPaths,
       version: this.version,
+      logger: this.logger,
     });
   }
 
@@ -122,21 +182,29 @@ class Spec {
       return {
         id: spec.id,
         data: null,
+        auth: null,
       };
     }
 
     return spec;
   }
 
-  constructor(apiKey: string, version: VersionUserConfig, devPaths: InputFilePaths) {
+  constructor(
+    apiKey: string,
+    version: VersionUserConfig,
+    devPaths: InputFilePaths,
+    private logger: AstroIntegrationLogger,
+  ) {
     this.specPromise = loadSpec({
       apiKey,
       devPaths,
       version,
+      logger,
     });
     this.devPaths = devPaths;
     this.apiKey = apiKey;
     this.version = version;
+    this.logger = logger;
   }
 }
 
@@ -166,14 +234,16 @@ export function startDevServer({
   devPaths,
   apiKey,
   getGeneratedSidebarConfig,
+  logger,
 }: {
   port: number;
   version: VersionUserConfig;
   devPaths: InputFilePaths;
   apiKey: string;
   getGeneratedSidebarConfig: (id: number) => GeneratedSidebarConfig | null;
+  logger: AstroIntegrationLogger;
 }) {
-  const spec = new Spec(apiKey, version, devPaths);
+  const spec = new Spec(apiKey, version, devPaths, logger);
 
   const server = createServer(async (req, res) => {
     // Add CORS headers
@@ -250,7 +320,7 @@ export function startDevServer({
   });
 
   server.listen(port, () => {
-    console.log(`Server is running on port ${port}`);
+    logger.debug(`Stainless spec server is running on port: ${port}`);
   });
 
   return {
@@ -266,3 +336,5 @@ export function startDevServer({
     },
   };
 }
+
+export type DevSpecServer = Awaited<ReturnType<typeof startDevServer>>;

package/plugin/cms/sidebar-builder.ts

@@ -1,5 +1,5 @@
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
-import { generateRoute, walkTree, type DocsLanguage } from '@stainless-api/docs-ui/src/routing';
+import type * as SDKJSON from '@stainless/sdk-json';
+import { generateRoute, walkTree, type DocsLanguage } from '@stainless-api/docs-ui/routing';
 import type { StarlightRouteData } from '@astrojs/starlight/route-data';
 
 function isResourceNonEmpty(resource: SDKJSON.Resource) {
@@ -120,22 +120,12 @@ export type GeneratedSidebarConfig = {
 };
 
 function countKeys(obj?: Record<string, any>) {
-  let o = obj ?? {};
+  const o = obj ?? {};
   return Object.keys(o).length;
 }
 
-function getMethodDeclForLanguage(entry: SDKJSON.Method, spec: SDKJSON.Spec, language: DocsLanguage) {
-  const decls = spec.decls[language] ?? {};
-  const decl = decls[entry.stainlessPath];
-  if (decl !== undefined) {
-    if ('ident' in decl) {
-      return decl;
-    }
-  }
-  return null;
-}
-
-type MethodDecl = Exclude<ReturnType<typeof getMethodDeclForLanguage>, null>;
+type HasIdent<T> = T extends { ident: unknown } ? T : never;
+type MethodDecl = HasIdent<SDKJSON.LanguageDeclNodes[SDKJSON.SpecLanguage]>;
 
 function makeAPIOverviewPage(): UserSidebarAPIOverviewPage {
   return {
@@ -166,7 +156,7 @@ function pullOutSharedModelsResource(resources: SDKJSON.Resource[]): {
 }
 
 export class SidebarConfigItemsBuilder {
-  private getMethodDeclForLanguage(entry: SDKJSON.Method) {
+  private getMethodDeclForLanguage(entry: SDKJSON.Method): MethodDecl | null {
     const decls = this.spec.decls[this.language] ?? {};
     const decl = decls[entry.stainlessPath];
     if (decl !== undefined) {
@@ -208,13 +198,6 @@ export class SidebarConfigItemsBuilder {
     };
   }
 
-  private sortByLabel<T extends UserSidebarConfigItem>(items: T[]) {
-    // sorts in place
-    items.sort((a, b) => {
-      return a.label.localeCompare(b.label);
-    });
-  }
-
   private generateResourceGroup(resource: SDKJSON.Resource, collapsed: boolean): ReferenceSidebarGroup {
     const entries: ReferenceSidebarConfigItem[] = [];
     if (!this.options?.excludeResourceOverviewPages) {
@@ -228,7 +211,6 @@ export class SidebarConfigItemsBuilder {
         methodPages.push(this.toMethodPage(m, langDecl));
       }
     }
-    this.sortByLabel(methodPages);
     entries.push(...methodPages);
 
     const subresources = Object.values(resource.subresources ?? {});
@@ -238,7 +220,6 @@ export class SidebarConfigItemsBuilder {
         subresourceGroups.push(this.generateResourceGroup(sub, true));
       }
     }
-    this.sortByLabel(subresourceGroups);
     entries.push(...subresourceGroups);
 
     return {
@@ -253,7 +234,7 @@ export class SidebarConfigItemsBuilder {
 
   public generateItems(): ReferenceSidebarConfigItem[] {
     const resourceMap = this.spec.resources;
-    let { resources, sharedModelsResource } = pullOutSharedModelsResource(Object.values(resourceMap ?? {}));
+    const { resources, sharedModelsResource } = pullOutSharedModelsResource(Object.values(resourceMap ?? {}));
 
     const entries: ReferenceSidebarConfigItem[] = resources.filter(isResourceNonEmpty).map((r) => {
       return this.generateResourceGroup(r, false);