@stainless-api/docs 0.1.0-beta.93 → 0.1.0-beta.94

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @stainless-api/docs
 
+## 0.1.0-beta.94
+
+### Minor Changes
+
+- beff534: Adds support for multiple sdkjsons
+
+### Patch Changes
+
+- Updated dependencies [cd578b7]
+- Updated dependencies [beff534]
+  - @stainless-api/docs-ui@0.1.0-beta.71
+  - @stainless-api/docs-search@0.1.0-beta.24
+
 ## 0.1.0-beta.93
 
 ### Patch Changes

package/eslint-suppressions.json

@@ -1,9 +1,4 @@
 {
-  "plugin/buildAlgoliaIndex.ts": {
-    "@typescript-eslint/no-explicit-any": {
-      "count": 2
-    }
-  },
   "plugin/components/SnippetCode.tsx": {
     "@typescript-eslint/no-explicit-any": {
       "count": 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "0.1.0-beta.93",
+  "version": "0.1.0-beta.94",
   "publishConfig": {
     "access": "public"
   },
@@ -56,8 +56,8 @@
     "vite-plugin-prebundle-workers": "^0.2.0",
     "web-worker": "^1.5.0",
     "yaml": "^2.8.2",
-    "@stainless-api/docs-search": "0.1.0-beta.23",
-    "@stainless-api/docs-ui": "0.1.0-beta.70",
+    "@stainless-api/docs-search": "0.1.0-beta.24",
+    "@stainless-api/docs-ui": "0.1.0-beta.71",
     "@stainless-api/ui-primitives": "0.1.0-beta.47"
   },
   "devDependencies": {

package/plugin/buildAlgoliaIndex.ts

@@ -1,10 +1,8 @@
 import Markdoc from '@markdoc/markdoc';
-import Stainless from '@stainless-api/sdk';
-import { createSDKJSON, parseInputs, transformOAS } from './specs/worker';
-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 { AstroIntegrationLogger } from 'astro';
+import { generateIndex } from '@stainless-api/docs-search/indexer';
+import { SpecComposite } from './specs';
 
 const markdocConfig = {
   nodes: {
@@ -21,14 +19,10 @@ function renderMarkdown(content?: string) {
 }
 
 export async function buildAlgoliaIndex({
-  stainlessProject,
-  branch,
-  apiKey,
+  specComposite,
   logger,
 }: {
-  stainlessProject: string;
-  branch: string;
-  apiKey: string;
+  specComposite: SpecComposite;
   logger?: AstroIntegrationLogger;
 }) {
   function warnLog(message: string) {
@@ -47,38 +41,6 @@ export async function buildAlgoliaIndex({
     }
   }
 
-  // TODO: this is all redundant with the spec code and should be DRYed
-  const client = new Stainless({ apiKey });
-  const configs = await client.projects.configs.retrieve({
-    project: stainlessProject,
-    branch,
-    include: 'openapi',
-  });
-
-  const configYML = Object.values(configs)[0] as { content: any };
-  const oasJson = Object.values(configs)[1] as { content: any };
-  const configStr = configYML['content'];
-  const oasStr = oasJson['content'];
-  const { oas, config } = await parseInputs({
-    oas: oasStr,
-    config: configStr,
-  });
-
-  const transformedOAS = await transformOAS({ oas, config });
-
-  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,
-    projectName: stainlessProject,
-  });
-
   const {
     PUBLIC_ALGOLIA_APP_ID: appId,
     PUBLIC_ALGOLIA_INDEX: indexName,
@@ -94,6 +56,13 @@ export async function buildAlgoliaIndex({
     warnLog(`Skipping Algolia indexing due to missing environment variables: ${missing.join(', ')}`);
     return;
   }
-  await buildIndex(appId, indexName, algoliaWriteKey, sdkJson, renderMarkdown);
+
+  const indexEntries = specComposite
+    .listUniqueSpecs()
+    .flatMap((spec) =>
+      Array.from(generateIndex(spec.data.sdkJson, renderMarkdown, true, spec.data.languages)),
+    );
+
+  await buildIndex(appId, indexName, algoliaWriteKey, indexEntries, renderMarkdown);
   infoLog('Indexing complete.');
 }

package/plugin/components/SDKSelect.astro

@@ -1,10 +1,9 @@
 ---
 import { parseRoute } from '@stainless-api/docs-ui/routing';
-import { DEFAULT_LANGUAGE, EXCLUDE_LANGUAGES } from 'virtual:stl-starlight-virtual-module';
+import { DEFAULT_LANGUAGE } from 'virtual:stl-starlight-virtual-module';
 import { Languages } from '../languages';
 import { SDKSelectReactComponent } from '../react/Routing';
-import { getSDKJSONInSSR } from '../specs/fetchSpecSSR';
-import { getDocsLanguages } from '../helpers/getDocsLanguages';
+import { getDocsLanguages } from '../helpers/multiSpec';
 import { API_REFERENCE_BASE_PATH } from 'virtual:stl-docs-virtual-module';
 
 const slug = `/${Astro.locals.starlightRoute.id}`;
@@ -20,9 +19,7 @@ const data = {
   defaultLanguage,
 };
 
-const spec = await getSDKJSONInSSR();
-
-const options = getDocsLanguages(spec, EXCLUDE_LANGUAGES).map((value) => ({
+const options = getDocsLanguages().map((value) => ({
   value,
   label: Languages[value].name,
   selected: data.language === value,

package/plugin/helpers/generateDocsRoutes.ts

@@ -1,6 +1,8 @@
 import type * as SDKJSON from '@stainless/sdk-json';
 import { DocsLanguage, generateRouteList } from '@stainless-api/docs-ui/routing';
 import { EXCLUDE_LANGUAGES } from 'virtual:stl-starlight-virtual-module';
+import { api } from 'virtual:stainless-apis-manifest';
+import { getSDKJSONInSSR } from '../specs/fetchSpecSSR';
 
 export function generateDocsRoutes(spec: SDKJSON.Spec, excludeLanguages: DocsLanguage[] = EXCLUDE_LANGUAGES) {
   const paths = generateRouteList({
@@ -25,3 +27,33 @@ export function generateDocsRoutes(spec: SDKJSON.Spec, excludeLanguages: DocsLan
     };
   });
 }
+
+export async function generateAllDocsRoutes() {
+  const uniquePaths = new Set<string>();
+
+  const allRoutes = (
+    await Promise.all(
+      api.languages.map(async (entry) => {
+        const spec = await getSDKJSONInSSR(entry.language);
+
+        // this is super annoying, but preview worker _always_ generates HTTP routes
+        // so, we exclude them unless the we're explicitly told to include them
+        const excludeLanguages = [...EXCLUDE_LANGUAGES];
+        if (entry.language !== 'http') {
+          excludeLanguages.push('http');
+        }
+
+        const routes = generateDocsRoutes(spec, excludeLanguages);
+        return routes.filter((route) => {
+          if (uniquePaths.has(route.params.slug)) {
+            return false;
+          }
+          uniquePaths.add(route.params.slug);
+          return true;
+        });
+      }),
+    )
+  ).flat();
+
+  return allRoutes;
+}

package/plugin/helpers/multiSpec.ts

@@ -0,0 +1,8 @@
+import { api } from 'virtual:stainless-apis-manifest';
+import { EXCLUDE_LANGUAGES } from 'virtual:stl-starlight-virtual-module';
+
+export function getDocsLanguages() {
+  return api.languages
+    .map((language) => language.language)
+    .filter((language) => !EXCLUDE_LANGUAGES.includes(language));
+}

package/plugin/index.ts

@@ -3,7 +3,7 @@ import type { StarlightPlugin } from '@astrojs/starlight/types';
 import type { AstroIntegration } from 'astro';
 import type { BundledTheme } from 'shiki';
 import { config } from 'dotenv';
-import { buildAlgoliaIndex } from './buildAlgoliaIndex';
+// import { buildAlgoliaIndex } from './buildAlgoliaIndex';
 import {
   getAPIReferencePlaceholderItemFromSidebarConfig,
   makePlaceholderItems,
@@ -32,8 +32,8 @@ import prebundleWorkers from 'vite-plugin-prebundle-workers';
 import { SpecLoader, startSpecLoader } from './specs';
 
 import type * as ReferenceSidebarsVirtualModule from 'virtual:stl-starlight-reference-sidebars';
-import { getDocsLanguages } from './helpers/getDocsLanguages';
 import { generateMissingRouteList } from '@stainless-api/docs-ui/routing';
+import { buildAlgoliaIndex } from './buildAlgoliaIndex';
 
 export { generateAPILink } from './generateAPIReferenceLink';
 export type { ReferenceSidebarConfigItem };
@@ -102,13 +102,10 @@ async function stlStarlightAstroIntegration(
   let astroBase = '/';
 
   let specLoader: SpecLoader | undefined;
-  async function getSpec() {
+  async function resolveSpecs() {
     if (!specLoader) throw new Error('Expected spec loader to exist');
     const result = await specLoader.specPromise;
-    return {
-      spec: result.spec.data,
-      auth: result.spec.auth,
-    };
+    return result.specComposite;
   }
 
   let building: Promise<void> | undefined;
@@ -119,9 +116,16 @@ async function stlStarlightAstroIntegration(
     if (!pluginConfig.experimentalPlaygrounds) return;
     if (building) return building;
     return (building = (async () => {
-      const { spec, auth } = await getSpec();
+      const specComposite = await resolveSpecs();
+
+      if (specComposite.listUniqueSpecs().length > 1) {
+        throw new Error('Multiple specs found. This is not supported for Playgrounds.');
+      }
 
-      const langs = getDocsLanguages(spec, pluginConfig.excludeLanguages);
+      const spec = specComposite.listUniqueSpecs()[0]!.data.sdkJson;
+      const auth = specComposite.listUniqueSpecs()[0]!.data.auth;
+
+      const langs = specComposite.getLanguages();
 
       await buildPlaygrounds!({
         spec,
@@ -150,14 +154,9 @@ async function stlStarlightAstroIntegration(
         const projectDir = astroConfig.root.pathname;
         astroBase = astroConfig.base;
 
+        logger.warn('Starting spec loader!!!');
+
         specLoader = await startSpecLoader(pluginConfig, logger, createCodegenDir());
-        specLoader.specPromise.then((specResult) => {
-          if (specResult.result === 'generated') {
-            logger.info(`Generated new SDKJSON`);
-          } else if (specResult.result === 'exists') {
-            logger.info(`Loaded SDKJSON`);
-          }
-        });
 
         reportError = (message: string) => logger.error(message);
 
@@ -198,22 +197,23 @@ async function stlStarlightAstroIntegration(
               makeAsyncVirtualModPlugin<typeof ReferenceSidebarsVirtualModule>(
                 'virtual:stl-starlight-reference-sidebars',
                 async () => {
-                  const { spec } = await getSpec();
-                  const languages = getDocsLanguages(spec, pluginConfig.excludeLanguages);
+                  // we know specLoader exists here
+                  const { specComposite } = await specLoader!.specPromise;
 
                   const sidebars = [...sidebarConfigs.entries()]
                     // produce all { id, language } combos with the attached config
                     // flattens to one item per language * id combo
                     .flatMap(([id, config]) =>
-                      languages.map((language) => ({
+                      specComposite.listAllLanguagesAndIncludeSpecs().map((res) => ({
                         id,
                         config,
-                        language,
+                        language: res.language,
+                        spec: res.spec.data.sdkJson,
                       })),
                     )
                     // produce a sidebar for each
                     // later we will .find() the sidebar that matches the (id, language)
-                    .map(({ id, config, language }) => {
+                    .map(({ id, config, language, spec }) => {
                       const configItemsBuilder = new SidebarConfigItemsBuilder(
                         spec,
                         language,
@@ -232,7 +232,7 @@ async function stlStarlightAstroIntegration(
                         // this has to run multpile times because it depends on the
                         // userSidebarConfig (which is per-id) and the language
                         entries: toStarlightSidebar({
-                          basePath: path.posix.join(astroBase, pluginConfig.basePath), // TODO, is this right?
+                          basePath: path.posix.join(astroBase, pluginConfig.basePath),
                           spec,
                           entries: userSidebarConfig,
                           currentLanguage: language,
@@ -243,7 +243,7 @@ async function stlStarlightAstroIntegration(
                   return { sidebars };
                 },
               ),
-              specLoader.vitePlugin,
+              ...specLoader.vitePlugins,
               {
                 name: 'stl-starlight-vite',
                 buildStart() {
@@ -314,7 +314,7 @@ async function stlStarlightAstroIntegration(
                         ENABLE_CONTEXT_MENU: pluginConfig.contextMenu,
                         EXPERIMENTAL_PLAYGROUNDS: !!pluginConfig.experimentalPlaygrounds,
                         EXPERIMENTAL_REQUEST_BUILDER: pluginConfig.experimentalRequestBuilder,
-                        STAINLESS_PROJECT: pluginConfig.specInputs.project,
+                        STAINLESS_PROJECT: pluginConfig.stainlessProject,
                       } satisfies Omit<typeof StlStarlightVirtualModule, 'MIDDLEWARE'>),
                       vmMiddlewareExport,
                     ].join('\n');
@@ -363,12 +363,22 @@ async function stlStarlightAstroIntegration(
         };
         await writeFile(path.join(stainlessDir, 'stl-manifest.json'), JSON.stringify(manifest, null, 2));
 
+        const specComposite = await resolveSpecs();
+
+        await buildAlgoliaIndex({
+          specComposite,
+          logger,
+        });
+
         // Generate a list of missing API routes to enable graceful handling of unimplemented SDK methods.
         // When users switch languages in the docs, some API methods may not be implemented in the target SDK.
         // Instead of showing a generic 404, we statically generate pages for these routes and mark them
         // in this file so Cloudflare can serve them with a 404 status. These pages display helpful information
         // about the missing method and provide links to SDKs where it is available.
-        const { spec } = await getSpec();
+
+        // TODO: (multi-spec) support multiple specs
+        const spec = specComposite.listUniqueSpecs()[0]!.data.sdkJson;
+
         const missingRoutes = generateMissingRouteList({
           spec,
           basePath: path.posix.join(astroBase, pluginConfig.basePath),
@@ -402,7 +412,10 @@ export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserCon
 
         const logger = getSharedLogger({ fallback: localLogger });
 
-        const configParseResult = parseStarlightPluginConfig(someUserConfig, command);
+        const configParseResult = parseStarlightPluginConfig(someUserConfig, {
+          command,
+          base: astroConfig.base,
+        });
         if (configParseResult.result === 'error') {
           const errorLines = configParseResult.message.split('\n');
           for (const line of errorLines) {
@@ -419,26 +432,18 @@ export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserCon
           addIntegration(react());
         }
 
-        if ('apiKey' in config.specInputs) {
-          if (!config.specInputs.apiKey) {
-            logger.info(`Stainless credentials not loaded`);
-          } else if (config.specInputs.apiKey.source === 'explicit-config') {
-            logger.info(`Stainless credentials loaded from user config`);
-          } else if (config.specInputs.apiKey.source === 'environment-variable') {
-            logger.info('Stainless credentials loaded from `STAINLESS_API_KEY` environment variable');
-          } else if (config.specInputs.apiKey.source === 'cli') {
-            logger.info('Stainless credentials loaded from `stl` CLI');
-          }
-        }
-
-        if (command === 'build' && config.specInputs.kind === 'stainless_api_inputs') {
-          await buildAlgoliaIndex({
-            stainlessProject: config.specInputs.project,
-            branch: config.specInputs.branch,
-            apiKey: config.specInputs.apiKey.value,
-            logger,
-          });
-        }
+        // TODO: (multi-spec) re-add this? not strictly necessary to merge
+        // if ('apiKey' in config.specInputs) {
+        //   if (!config.specInputs.apiKey) {
+        //     logger.info(`Stainless credentials not loaded`);
+        //   } else if (config.specInputs.apiKey.source === 'explicit-config') {
+        //     logger.info(`Stainless credentials loaded from user config`);
+        //   } else if (config.specInputs.apiKey.source === 'environment-variable') {
+        //     logger.info('Stainless credentials loaded from `STAINLESS_API_KEY` environment variable');
+        //   } else if (config.specInputs.apiKey.source === 'cli') {
+        //     logger.info('Stainless credentials loaded from `stl` CLI');
+        //   }
+        // })
 
         if (starlightConfig.sidebar) {
           // for pagination (https://starlight.astro.build/reference/configuration/#pagination) to work correctly
@@ -483,3 +488,5 @@ export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserCon
 // Additional exports we want for Stainless <-> docs integration.
 export { parseStainlessPath } from '@stainless-api/docs-ui/routing';
 export { renderMarkdown } from '@stainless-api/docs-ui/markdown';
+
+export { resolveSpec } from './specs/inputResolver';

package/plugin/loadPluginConfig.ts

@@ -6,6 +6,13 @@ import type { CreateShikiHighlighterOptions } from '@astrojs/markdown-remark';
 import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
 import type { PropertySettingsType } from '@stainless-api/docs-ui/contexts';
 import { bold } from '../shared/terminalUtils';
+import { resolveSpec, SpecInputResolver } from './specs/inputResolver';
+import { specCache, SpecCacheResult } from './specs/generateSpec';
+
+export type LanguageGenerateQuery = {
+  mode: 'exclude' | 'only';
+  list: DocsLanguage[];
+};
 
 export type AstroCommand = 'dev' | 'build' | 'preview' | 'sync';
 
@@ -42,6 +49,19 @@ export type StainlessStarlightUserConfig = {
    */
   stainlessProject: string;
 
+  /**
+   * Powerful configuration options for customized use cases
+   */
+  advanced?: {
+    /**
+     *
+     * More advanced replacement for versions, basePath, and excludeLanguages.
+     */
+    overrideSpecs?: {
+      specs: SpecInputResolver[];
+    };
+  };
+
   /**
    * Optional list of versions to render in the API reference.
    */
@@ -147,11 +167,12 @@ export type StainlessStarlightUserConfig = {
   experimentalPrerender?: boolean;
 };
 
-export type ExternalSpecServerUserConfig = Omit<StainlessStarlightUserConfig, 'stainlessProject'> & {
-  externalSpecServerUrl: string;
-};
+// TODO: eventually? re-add support for external spec servers
+// export type ExternalSpecServerUserConfig = Omit<StainlessStarlightUserConfig, 'stainlessProject'> & {
+//   externalSpecServerUrl: string;
+// };
 
-export type SomeStainlessStarlightUserConfig = StainlessStarlightUserConfig | ExternalSpecServerUserConfig;
+export type SomeStainlessStarlightUserConfig = StainlessStarlightUserConfig;
 
 function resolvePath(inputPath: string) {
   return path.resolve(process.cwd(), inputPath);
@@ -231,29 +252,110 @@ function loadApiKey(configValue: string | undefined): LoadedApiKey | null {
   return { value: accessToken, source: 'cli' };
 }
 
-export type SDKJSONInputs =
-  | {
-      kind: 'file_inputs';
-      project: string;
-      oasPath: string;
-      configPath: string;
+export function forceLoadStainlessCredentials(): LoadedApiKey {
+  const v = loadApiKey(undefined);
+  if (!v) {
+    throw new Error(`Failed to load Stainless credentials.`);
+  }
+  return v;
+}
+
+type AstroOptions = {
+  command: AstroCommand;
+  base: string;
+};
+
+export type ResolvedAPIConfigEntry = {
+  loadSpecs: () => Promise<SpecCacheResult[]>;
+};
+
+function makeSimpleAPIConfig(
+  partial: SomeStainlessStarlightUserConfig,
+  astroOptions: AstroOptions,
+): ResolvedAPIConfigEntry {
+  if (!('stainlessProject' in partial)) {
+    throw new Error('You must provide a stainlessProject when using Stainless Starlight');
+  }
+
+  const excludedLanguages = ['php' as const, ...(partial.excludeLanguages ?? [])];
+
+  const apiKey = loadApiKey(partial.apiKey);
+
+  function getResolver() {
+    const localFilePaths = getLocalFilePaths(astroOptions.command);
+    if (localFilePaths) {
+      return resolveSpec.fromFiles({
+        oasPath: localFilePaths.oasPath,
+        configPath: localFilePaths.configPath,
+        languageOverrides: {
+          mode: 'exclude',
+          list: excludedLanguages,
+        },
+        stainlessProject: partial.stainlessProject,
+      });
     }
-  | {
-      kind: 'stainless_api_inputs';
-      project: string;
-      branch: string;
-      apiKey: LoadedApiKey;
+
+    if (!apiKey) {
+      throw new Error(
+        [
+          bold(
+            'No Stainless credentials found. Please choose one of the following options to authenticate with Stainless:',
+          ),
+          '- Run `stl auth login` to authenticate via the Stainless CLI',
+          '- Provide a Stainless API key via the `STAINLESS_API_KEY` environment variable (eg. in a .env file)',
+          '- Set the `apiKey` option in the Stainless Docs config',
+        ].join('\n'),
+      );
     }
-  | {
-      kind: 'string_inputs';
-      oasStr: string;
-      configStr: string;
-      project: string;
+    return resolveSpec.fromStainlessApi({
+      stainlessProject: partial.stainlessProject,
+      branch: partial.versions?.[0]?.branch ?? 'main',
+      apiKey: apiKey,
+      languageOverrides: {
+        mode: 'exclude',
+        list: excludedLanguages,
+      },
+    });
+  }
+
+  const resolver = getResolver();
+
+  return {
+    loadSpecs: async function loadSpecs() {
+      const inputs = await resolver.resolve({ apiKey });
+
+      const result = await specCache.get(inputs);
+
+      return [result];
+    },
+  };
+}
+
+function loadAPIConfig(
+  partial: SomeStainlessStarlightUserConfig,
+  astroOptions: AstroOptions,
+): ResolvedAPIConfigEntry {
+  if (partial.advanced?.overrideSpecs) {
+    const overrides = partial.advanced.overrideSpecs;
+    const apiKey = loadApiKey(partial.apiKey);
+    return {
+      loadSpecs: async function loadSpecs() {
+        const specsPromises = overrides.specs.map(async (spec) => {
+          const inputs = await spec.resolve({ apiKey });
+          return await specCache.get(inputs);
+        });
+
+        return await Promise.all(specsPromises);
+      },
     };
+  }
+  return makeSimpleAPIConfig(partial, astroOptions);
+}
 
-function normalizeConfig(partial: SomeStainlessStarlightUserConfig, command: AstroCommand) {
+function normalizeConfig(partial: SomeStainlessStarlightUserConfig, astroOptions: AstroOptions) {
   const configWithDefaults = {
     basePath: partial.basePath ?? '/api',
+    astroBase: astroOptions.base,
     // TODO: why are we excluding php; do we need to
     excludeLanguages: ['php' as const, ...(partial.excludeLanguages ?? [])],
     defaultLanguage: partial.defaultLanguage ?? 'http',
@@ -283,50 +385,14 @@ function normalizeConfig(partial: SomeStainlessStarlightUserConfig, command: Ast
     experimentalPlaygrounds: partial.experimentalPlaygrounds ?? undefined,
     experimentalRequestBuilder: partial.experimentalRequestBuilder ?? false,
     experimentalPrerender: partial.experimentalPrerender ?? true,
+    stainlessProject: partial.stainlessProject,
   };
 
-  function getSpecInputs(): SDKJSONInputs {
-    if (!('stainlessProject' in partial)) {
-      throw new Error('You must provide a stainlessProject when using Stainless Starlight');
-    }
-
-    const localFilePaths = getLocalFilePaths(command);
-    if (localFilePaths) {
-      return {
-        kind: 'file_inputs',
-        project: partial.stainlessProject,
-        oasPath: localFilePaths.oasPath,
-        configPath: localFilePaths.configPath,
-      };
-    }
-
-    const apiKey = loadApiKey(partial.apiKey);
-
-    if (!apiKey) {
-      throw new Error(
-        [
-          bold(
-            'No Stainless credentials found. Please choose one of the following options to authenticate with Stainless:',
-          ),
-          '- Run `stl auth login` to authenticate via the Stainless CLI',
-          '- Provide a Stainless API key via the `STAINLESS_API_KEY` environment variable (eg. in a .env file)',
-          '- Set the `apiKey` option in the Stainless Docs config',
-        ].join('\n'),
-      );
-    }
-    return {
-      kind: 'stainless_api_inputs',
-      project: partial.stainlessProject,
-      branch: partial.versions?.[0]?.branch ?? 'main',
-      apiKey,
-    };
-  }
-
-  const specInputs = getSpecInputs();
+  const api = loadAPIConfig(partial, astroOptions);
 
   return {
     ...configWithDefaults,
-    specInputs,
+    api,
   };
 }
 
@@ -341,9 +407,12 @@ export type NormalizedStainlessStarlightConfig = ReturnType<typeof normalizeConf
  - If a field is only used in certain contexts, we make each context a discriminated union (see SDKJSONInputs)
  - We prefer empty arrays over undefined/null
 */
-export function parseStarlightPluginConfig(partial: SomeStainlessStarlightUserConfig, command: AstroCommand) {
+export function parseStarlightPluginConfig(
+  partial: SomeStainlessStarlightUserConfig,
+  astroOptions: AstroOptions,
+) {
   try {
-    const config = normalizeConfig(partial, command);
+    const config = normalizeConfig(partial, astroOptions);
     return {
       result: 'success' as const,
       config,