@stainless-api/docs 0.1.0-beta.138 → 0.1.0-beta.139

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @stainless-api/docs
 
+## 0.1.0-beta.139
+
+### Minor Changes
+
+- d068123: bring-your-own spec loader
+- e5367b0: Move preview worker to @stainless/sdk-json package
+
+### Patch Changes
+
+- Updated dependencies [e5367b0]
+  - @stainless/sdk-json@0.1.0-beta.11
+
 ## 0.1.0-beta.138
 
 ### Patch Changes

package/eslint-suppressions.json

@@ -27,31 +27,6 @@
       "count": 1
     }
   },
-  "plugin/specs/generateSpec.ts": {
-    "@typescript-eslint/no-unsafe-assignment": {
-      "count": 2
-    }
-  },
-  "plugin/specs/worker.ts": {
-    "@typescript-eslint/no-explicit-any": {
-      "count": 3
-    },
-    "@typescript-eslint/no-unsafe-argument": {
-      "count": 1
-    },
-    "@typescript-eslint/no-unsafe-assignment": {
-      "count": 7
-    },
-    "@typescript-eslint/no-unsafe-member-access": {
-      "count": 4
-    },
-    "@typescript-eslint/no-unsafe-return": {
-      "count": 1
-    },
-    "@typescript-eslint/prefer-promise-reject-errors": {
-      "count": 4
-    }
-  },
   "stl-docs/components/sidebars/convertAstroSidebarToStl.tsx": {
     "@typescript-eslint/no-unsafe-argument": {
       "count": 1

package/eslint.config.ts

@@ -1,8 +1,4 @@
 import { defineConfig } from 'eslint/config';
 import { config } from '@stainless/eslint-config/astro';
 
-export default defineConfig(
-  config,
-
-  { ignores: ['plugin/vendor/**'] },
-);
+export default defineConfig(config);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "0.1.0-beta.138",
+  "version": "0.1.0-beta.139",
   "publishConfig": {
     "access": "public"
   },
@@ -71,10 +71,10 @@
     "remend": "^1.3.0",
     "shiki": "^4.0.2",
     "unified": "^11.0.5",
-    "web-worker": "^1.5.0",
     "@stainless-api/docs-search": "0.1.0-beta.49",
     "@stainless-api/docs-ui": "0.1.0-beta.95",
-    "@stainless-api/ui-primitives": "0.1.0-beta.53"
+    "@stainless-api/ui-primitives": "0.1.0-beta.53",
+    "@stainless/sdk-json": "^0.1.0-beta.11"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.9",
@@ -83,18 +83,16 @@
     "@types/react": "19.2.14",
     "@types/react-dom": "^19.2.3",
     "@types/react-syntax-highlighter": "^15.5.13",
-    "astro": "^6.2.2",
-    "react": "^19.2.5",
-    "react-dom": "^19.2.5",
+    "astro": "^6.3.1",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
     "typescript": "6.0.3",
     "vite": "^7.3.2",
     "vitest": "^4.1.5",
     "zod": "^4.4.3",
-    "@stainless/eslint-config": "0.1.0-beta.2",
-    "@stainless/sdk-json": "^0.1.0-beta.10"
+    "@stainless/eslint-config": "0.1.0-beta.2"
   },
   "scripts": {
-    "vendor-deps": "node scripts/vendor_deps.ts",
     "lint": "eslint --flag unstable_native_nodejs_ts_config . --max-warnings 0",
     "sync": "astro sync",
     "check:types": "astro check",

package/plugin/buildAlgoliaIndex.ts

@@ -2,7 +2,8 @@ import Markdoc from '@markdoc/markdoc';
 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';
+import type { LoadedSpecs } from './specs/utils';
+import { isSupportedLanguage } from '@stainless-api/docs-ui/routing';
 
 const markdocConfig = {
   nodes: {
@@ -19,10 +20,10 @@ function renderMarkdown(content?: string) {
 }
 
 export async function buildAlgoliaIndex({
-  specComposite,
+  loadedSpecs,
   logger,
 }: {
-  specComposite: SpecComposite;
+  loadedSpecs: LoadedSpecs;
   logger?: AstroIntegrationLogger;
 }) {
   function warnLog(message: string) {
@@ -57,15 +58,8 @@ export async function buildAlgoliaIndex({
     return;
   }
 
-  const indexEntries = specComposite.listUniqueSpecs().flatMap((spec) =>
-    Array.from(
-      generateIndex(
-        spec.data.sdkJson,
-        renderMarkdown,
-        true,
-        spec.data.languages.filter((l) => l !== 'sql' && l !== 'openapi'),
-      ),
-    ),
+  const indexEntries = loadedSpecs.flatMap((spec) =>
+    Array.from(generateIndex(spec.sdkJson, renderMarkdown, true, spec.languages.filter(isSupportedLanguage))),
   );
 
   await buildIndex(appId, indexName, algoliaWriteKey, indexEntries, renderMarkdown);

package/plugin/index.ts

@@ -26,11 +26,17 @@ import { getSharedLogger } from '../shared/getSharedLogger';
 import { resolveSrcFile } from '../resolveSrcFile';
 import { mkdir, writeFile } from 'fs/promises';
 import { fileURLToPath } from 'url';
-import { SpecLoader, startSpecLoader } from './specs';
 
 import type * as ReferenceSidebarsVirtualModule from 'virtual:stl-starlight-reference-sidebars';
-import { generateMissingRouteList } from '@stainless-api/docs-ui/routing';
+import type * as VirtualManifestModule from 'virtual:stainless-apis-manifest';
+
+import {
+  generateMissingRouteList,
+  isSupportedLanguage,
+  type DocsLanguage,
+} from '@stainless-api/docs-ui/routing';
 import { buildAlgoliaIndex } from './buildAlgoliaIndex';
+import { flatSpecsList, loadAllSpecs, LoadedSpecs } from './specs/utils';
 
 export { generateAPILink } from './generateAPIReferenceLink';
 export type { ReferenceSidebarConfigItem };
@@ -94,17 +100,18 @@ function stlStarlightAstroIntegration(pluginConfig: NormalizedStainlessStarlight
   const resolvedId = `\0${virtualId}`;
   let astroBase = '/';
 
-  let specLoader: SpecLoader | undefined;
-  async function resolveSpecs() {
-    if (!specLoader) throw new Error('Expected spec loader to exist');
-    const result = await specLoader.specPromise;
-    return result.specComposite;
+  let specsPromise: Promise<LoadedSpecs> | undefined;
+  async function specsPromiseResolved() {
+    if (!specsPromise) throw new Error('Expected spec promise to exist');
+    const result = await specsPromise;
+
+    return result;
   }
 
   return {
     name: 'stl-starlight-astro',
     hooks: {
-      'astro:config:setup': async ({
+      'astro:config:setup': ({
         injectRoute,
         updateConfig,
         logger: localLogger,
@@ -116,7 +123,16 @@ function stlStarlightAstroIntegration(pluginConfig: NormalizedStainlessStarlight
         const projectDir = astroConfig.root.pathname;
         astroBase = astroConfig.base;
 
-        specLoader = await startSpecLoader(pluginConfig, logger, createCodegenDir());
+        specsPromise = loadAllSpecs(
+          pluginConfig.loadSpecs({
+            stainlessProject: pluginConfig.stainlessProject,
+            branch: pluginConfig.branch,
+            apiKey: pluginConfig.apiKey?.value ?? null,
+            excludeLanguages: pluginConfig.excludeLanguages,
+            logger,
+            createCodegenDir,
+          }),
+        );
 
         const middlewareFileBase = path.join(projectDir, 'middleware.stainless');
         const middlewareFile = ['.tsx', '.ts']
@@ -171,24 +187,28 @@ function stlStarlightAstroIntegration(pluginConfig: NormalizedStainlessStarlight
                 'virtual:stl-starlight-reference-sidebars',
                 async () => {
                   // we know specLoader exists here
-                  const { specComposite } = await specLoader!.specPromise;
+                  const specs = await specsPromiseResolved();
 
                   const sidebars = [...sidebarConfigs.entries()]
                     // produce all { id, language } combos with the attached config
                     // flattens to one item per language * id combo
                     .flatMap(([id, config]) =>
-                      specComposite.listAllLanguagesAndIncludeSpecs().map((res) => ({
-                        id,
-                        config,
-                        language: res.language,
-                        spec: res.spec.data.sdkJson,
-                      })),
+                      flatSpecsList(specs)
+                        .filter((res): res is typeof res & { language: DocsLanguage } =>
+                          isSupportedLanguage(res.language),
+                        )
+                        .map((res) => ({
+                          id,
+                          config,
+                          language: res.language,
+                          sdkJson: res.sdkJson,
+                        })),
                     )
                     // produce a sidebar for each
                     // later we will .find() the sidebar that matches the (id, language)
-                    .map(({ id, config, language, spec }) => {
+                    .map(({ id, config, language, sdkJson }) => {
                       const configItemsBuilder = new SidebarConfigItemsBuilder(
-                        spec,
+                        sdkJson,
                         language,
                         config.options,
                       );
@@ -202,11 +222,11 @@ function stlStarlightAstroIntegration(pluginConfig: NormalizedStainlessStarlight
                       return {
                         id,
                         language,
-                        // this has to run multpile times because it depends on the
+                        // this has to run multiple times because it depends on the
                         // userSidebarConfig (which is per-id) and the language
                         entries: toStarlightSidebar({
                           basePath: path.posix.join(astroBase, pluginConfig.basePath),
-                          spec,
+                          spec: sdkJson,
                           entries: userSidebarConfig,
                           currentLanguage: language,
                         }),
@@ -216,7 +236,26 @@ function stlStarlightAstroIntegration(pluginConfig: NormalizedStainlessStarlight
                   return { sidebars };
                 },
               ),
-              ...specLoader.vitePlugins,
+              makeAsyncVirtualModPlugin<typeof VirtualManifestModule>(
+                'virtual:stainless-apis-manifest',
+                async () => {
+                  // this virtual module only resolves when the specs are loaded
+                  // this prevents the SSR module from trying to read the spec file before it's generated
+                  const specs = await specsPromiseResolved();
+
+                  return {
+                    api: {
+                      languages: specs
+                        .map((s) =>
+                          s.languages
+                            .filter(isSupportedLanguage)
+                            .map((lang) => ({ language: lang, sdkJSONFilePath: s.filePath })),
+                        )
+                        .flat(),
+                    },
+                  };
+                },
+              ),
               {
                 name: 'stl-starlight-vite',
                 // TODO: eventually - re-add support for watching local input changes (eg. reloading when OAS/config files change)
@@ -269,10 +308,10 @@ function stlStarlightAstroIntegration(pluginConfig: NormalizedStainlessStarlight
         };
         await writeFile(path.join(stainlessDir, 'stl-manifest.json'), JSON.stringify(manifest, null, 2));
 
-        const specComposite = await resolveSpecs();
+        const loadedSpecs = await specsPromiseResolved();
 
         await buildAlgoliaIndex({
-          specComposite,
+          loadedSpecs,
           logger,
         });
 
@@ -283,7 +322,7 @@ function stlStarlightAstroIntegration(pluginConfig: NormalizedStainlessStarlight
         // about the missing method and provide links to SDKs where it is available.
 
         // TODO: (multi-spec) support multiple specs
-        const spec = specComposite.listUniqueSpecs()[0]!.data.sdkJson;
+        const spec = loadedSpecs[0]!.sdkJson;
 
         const missingRoutes = generateMissingRouteList({
           spec,
@@ -338,18 +377,17 @@ export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserCon
           addIntegration(react());
         }
 
-        // 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 ('apiKey' in config) {
+          if (!config.apiKey) {
+            logger.info(`Stainless credentials not loaded`);
+          } else if (config.apiKey.source === 'explicit-config') {
+            logger.info(`Stainless credentials loaded from user config`);
+          } else if (config.apiKey.source === 'environment-variable') {
+            logger.info('Stainless credentials loaded from `STAINLESS_API_KEY` environment variable');
+          } else if (config.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
@@ -394,5 +432,3 @@ 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

@@ -5,13 +5,15 @@ import { existsSync, readFileSync } from 'fs';
 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[];
+import { defaultSpecLoader } from './specs/defaultSpecLoader';
+import { SpecLoaderFn } from './specs/utils';
+
+type ApiKeySource = 'explicit-config' | 'environment-variable' | 'cli';
+
+type LoadedApiKey = {
+  value: string;
+  source: ApiKeySource;
 };
 
 type AstroCommand = 'dev' | 'build' | 'preview' | 'sync';
@@ -50,17 +52,9 @@ export type StainlessStarlightUserConfig = {
   stainlessProject: string;
 
   /**
-   * Powerful configuration options for customized use cases
+   * Optional function to provide your own loader for API reference data.
    */
-  advanced?: {
-    /**
-     *
-     * More advanced replacement for versions, basePath, and excludeLanguages.
-     */
-    overrideSpecs?: {
-      specs: SpecInputResolver[];
-    };
-  };
+  loadSpecs?: SpecLoaderFn;
 
   /**
    * Optional list of versions to render in the API reference.
@@ -193,33 +187,6 @@ export type StainlessStarlightUserConfig = {
 
 export type SomeStainlessStarlightUserConfig = StainlessStarlightUserConfig;
 
-function resolvePath(inputPath: string) {
-  return path.resolve(process.cwd(), inputPath);
-}
-
-function getLocalFilePaths() {
-  // eslint-disable-next-line turbo/no-undeclared-env-vars
-  const oasPath = process.env.OPENAPI_PATH;
-  // eslint-disable-next-line turbo/no-undeclared-env-vars
-  const configPath = process.env.STAINLESS_CONFIG_PATH;
-
-  if (!oasPath || !configPath) {
-    return null;
-  }
-
-  return {
-    oasPath: resolvePath(oasPath),
-    configPath: resolvePath(configPath),
-  };
-}
-
-type ApiKeySource = 'explicit-config' | 'environment-variable' | 'cli';
-
-export type LoadedApiKey = {
-  value: string;
-  source: ApiKeySource;
-};
-
 function parseAuthJson(authJsonStr: string) {
   let json: unknown;
   try {
@@ -281,87 +248,6 @@ type AstroOptions = {
   base: string;
 };
 
-type ResolvedAPIConfigEntry = {
-  loadSpecs: () => Promise<SpecCacheResult[]>;
-};
-
-function makeSimpleAPIConfig(partial: SomeStainlessStarlightUserConfig): ResolvedAPIConfigEntry {
-  if (!('stainlessProject' in partial)) {
-    throw new Error('You must provide a stainlessProject when using Stainless Starlight');
-  }
-
-  const excludedLanguages = partial.excludeLanguages ?? [];
-
-  const apiKey = loadApiKey(partial.apiKey);
-
-  function getResolver() {
-    const localFilePaths = getLocalFilePaths();
-    if (localFilePaths) {
-      return resolveSpec.fromFiles({
-        oasPath: localFilePaths.oasPath,
-        configPath: localFilePaths.configPath,
-        languageOverrides: {
-          mode: 'exclude',
-          list: excludedLanguages,
-        },
-        stainlessProject: partial.stainlessProject,
-      });
-    }
-
-    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 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): 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);
-}
-
 function normalizeConfig(partial: SomeStainlessStarlightUserConfig, astroOptions: AstroOptions) {
   const configWithDefaults = {
     basePath: partial.basePath ?? '/api',
@@ -399,14 +285,12 @@ function normalizeConfig(partial: SomeStainlessStarlightUserConfig, astroOptions
       description: partial.llmsTxt?.description ?? null,
       detailThreshold: partial.llmsTxt?.detailThreshold ?? 2000,
     },
+    apiKey: loadApiKey(partial.apiKey),
+    loadSpecs: partial.loadSpecs ?? defaultSpecLoader,
+    branch: partial.versions?.[0]?.branch ?? 'main',
   };
 
-  const api = loadAPIConfig(partial);
-
-  return {
-    ...configWithDefaults,
-    api,
-  };
+  return configWithDefaults;
 }
 
 export type NormalizedStainlessStarlightConfig = ReturnType<typeof normalizeConfig>;