@stainless-api/docs 0.1.0-beta.13 → 0.1.0-beta.130

package/plugin/loadPluginConfig.ts

@@ -1,15 +1,24 @@
 import path from 'path';
+import { homedir } from 'os';
+import { existsSync, readFileSync } from 'fs';
 
 import type { CreateShikiHighlighterOptions } from '@astrojs/markdown-remark';
-import type { DocsLanguage } from '@stainless-api/docs-ui/src/routing';
-import type { PropertySettingsType } from '@stainless-api/docs-ui/src/contexts';
-import type { InputFilePaths } from '../plugin/cms/server';
+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';
+type AstroCommand = 'dev' | 'build' | 'preview' | 'sync';
 
-export type ContentLayout = 'double-pane' | 'single-pane';
+type ContentLayout = 'double-pane' | 'single-pane';
 
-export type VersionUserConfig = {
+type VersionUserConfig = {
   version: string;
   stainlessProject: string;
   branch: string;
@@ -18,7 +27,7 @@ export type VersionUserConfig = {
 type BreadcrumbUserConfig = {
   /**
    * Include the current page in the breadcrumb list.
-   * Defaults to `false`.
+   * Default: `false`
    */
   includeCurrentPage?: boolean;
 };
@@ -26,7 +35,12 @@ type BreadcrumbUserConfig = {
 export type StainlessStarlightUserConfig = {
   /**
    * Optional api key for Stainless API.
-   * If not provided, it will look for the STAINLESS_API_KEY environment variable.
+   * If not provided, we will handle Stainless auth via the `stl` CLI or look for the STAINLESS_API_KEY environment variable.
+   * Precedence:
+   * 1. Explicity `apiKey` option provided
+   * 2. `STAINLESS_API_KEY` environment variable
+   * 3. Login status from the `stl` CLI
+   * 4. Error (no auth found)
    */
   apiKey?: string;
 
@@ -35,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.
    */
@@ -42,8 +69,8 @@ export type StainlessStarlightUserConfig = {
 
   /**
    * Optional mount point for API reference docs.
-   * Defaults to `/api`.
    * Example: `/my-api` → docs available at `/my-api/…`.
+   * @default `/api`
    */
   basePath?: string;
 
@@ -55,8 +82,8 @@ export type StainlessStarlightUserConfig = {
 
   /**
    * Optional language to treat as the default when the user hasn't selected one.
-   * Defaults to `"http"` when none is provided.
-   * Example: `"python"`
+   * Example: `'python'`
+   * @default 'http'
    */
   defaultLanguage?: DocsLanguage;
 
@@ -90,7 +117,7 @@ export type StainlessStarlightUserConfig = {
   contentPanel?: {
     /**
      * Optional layout for the content panel.
-     * Defaults to `"double-pane"`.
+     * @default 'double-pane'
      */
     layout?: ContentLayout;
   };
@@ -100,78 +127,261 @@ export type StainlessStarlightUserConfig = {
    */
   propertySettings?: PropertySettingsType;
 
-  /**
-   * Options to control the documentation site's search functionality
-   */
-  search?: {
-    /**
-     * When set to `true`, the enableAISearch` setting turns on support for
-     * LLM-based conversations with the API documentation
-     */
-    enableAISearch?: boolean;
-  };
-
   /**
    * Enable experimental collapsible code snippets. Snippets will be collapsed by default for
    * single-pane and mobile layouts.
-   * Defaults to `false`.
+   *
+   * @default false
    */
   experimentalCollapsibleSnippets?: boolean;
 
   /**
-   * When set to `true`, a dropdown button will be included on all pages to allow users to
-   * view or send markdown to an LLM.
-   * Defaults to `false`.
+   * Enable experimental collapsible method descriptions. Method descriptions will be
+   * collapsed if their content exceeds a certain length.
+   *
+   * @default false
    */
-  includeAIDropdownOptions?: boolean;
-};
+  experimentalCollapsibleMethodDescriptions?: boolean;
 
-export type ExternalSpecServerUserConfig = Omit<StainlessStarlightUserConfig, 'stainlessProject'> & {
-  externalSpecServerUrl: string;
+  /**
+   * Whether to show the context menu with options like "Copy as Markdown" and "Open in ChatGPT".
+   *
+   * @default true
+   */
+
+  contextMenu?: boolean;
+
+  /**
+   * When set to `import playgrounds from '@stainless-api/playgrounds'`, code snippets will have a "Play" button,
+   * allowing users to edit and run code snippets in their browser.
+   */
+  experimentalPlaygrounds?: { playgroundsBase: string };
+
+  /** When set to true, enables the experimental request builder interface for testing API endpoints. */
+  experimentalRequestBuilder?: boolean;
+
+  /** Whether to prerender the api reference pages.
+   *
+   * @default true
+   */
+  experimentalPrerender?: boolean;
+
+  /**
+   * Configuration for the generated `/llms.txt` file.
+   */
+  llmsTxt?: {
+    /**
+     * Whether to disable the generated `/llms.txt` file.
+     *
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * A short description of the site, used as the blockquote summary at the top of the file.
+     * Falls back to the top-level Starlight `description` field if not set.
+     */
+    description?: string;
+    /**
+     * The maximum number of total routes (prose + API reference) at which the file switches
+     * from compact mode (resources only) to detailed mode (resources and
+     * methods).
+     *
+     * @default 2000
+     */
+    detailThreshold?: number;
+  };
 };
 
-export type SomeStainlessStarlightUserConfig = StainlessStarlightUserConfig | ExternalSpecServerUserConfig;
+// TODO: eventually? re-add support for external spec servers
+// export type ExternalSpecServerUserConfig = Omit<StainlessStarlightUserConfig, 'stainlessProject'> & {
+//   externalSpecServerUrl: string;
+// };
+
+export type SomeStainlessStarlightUserConfig = StainlessStarlightUserConfig;
 
 function resolvePath(inputPath: string) {
   return path.resolve(process.cwd(), inputPath);
 }
 
-function getLocalFilePaths(command: AstroCommand): InputFilePaths | null {
+function getLocalFilePaths(command: AstroCommand) {
   if (command !== 'dev') {
     return null;
   }
-  if (!process.env.OPENAPI_PATH || !process.env.STAINLESS_SPEC_PATH) {
+
+  // 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(process.env.OPENAPI_PATH),
-    configPath: resolvePath(process.env.STAINLESS_SPEC_PATH),
+    oasPath: resolvePath(oasPath),
+    configPath: resolvePath(configPath),
   };
 }
 
-export type SpecRetrieverConfig =
-  | {
-      kind: 'external_spec_server';
-      specServerUrl: string;
-      stainlessProject: null;
+type ApiKeySource = 'explicit-config' | 'environment-variable' | 'cli';
+
+export type LoadedApiKey = {
+  value: string;
+  source: ApiKeySource;
+};
+
+function parseAuthJson(authJsonStr: string) {
+  let json: unknown;
+  try {
+    json = JSON.parse(authJsonStr);
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  } catch (_error) {
+    return null;
+  }
+
+  if (typeof json !== 'object' || json === null) {
+    return null;
+  }
+  if (!('access_token' in json)) {
+    return null;
+  }
+  const accessToken = json['access_token'];
+  if (typeof accessToken !== 'string') {
+    return null;
+  }
+  return accessToken;
+}
+
+function loadApiKey(configValue: string | undefined): LoadedApiKey | null {
+  if (typeof configValue === 'string') {
+    return { value: configValue, source: 'explicit-config' };
+  }
+  if (process.env.STAINLESS_API_KEY) {
+    return { value: process.env.STAINLESS_API_KEY, source: 'environment-variable' };
+  }
+
+  const homeDirPath = homedir();
+
+  const authJsonPath = path.join(homeDirPath, '.config', 'stainless', 'auth.json');
+
+  if (!existsSync(authJsonPath)) {
+    return null;
+  }
+
+  const authJsonStr = readFileSync(authJsonPath, 'utf-8');
+  const accessToken = parseAuthJson(authJsonStr);
+  if (!accessToken) {
+    return null;
+  }
+
+  return { value: accessToken, source: 'cli' };
+}
+
+/** @public but discouraged - used by cloudflare via relative import */
+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;
+};
+
+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 = 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: 'local_spec_server_with_files';
-      stainlessProject: string;
-      devPaths: InputFilePaths;
-      apiKey: string | null;
-      version: VersionUserConfig;
+
+    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: 'local_spec_server_with_remote_files';
-      stainlessProject: string;
-      apiKey: string;
-      version: VersionUserConfig;
+    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,
     excludeLanguages: partial.excludeLanguages ?? [],
     defaultLanguage: partial.defaultLanguage ?? 'http',
     breadcrumbs: {
@@ -188,86 +398,51 @@ function normalizeConfig(partial: SomeStainlessStarlightUserConfig, command: Ast
       layout: partial.contentPanel?.layout ?? 'double-pane',
     },
     experimentalCollapsibleSnippets: partial.experimentalCollapsibleSnippets ?? false,
+    experimentalCollapsibleMethodDescriptions: partial.experimentalCollapsibleMethodDescriptions ?? false,
     propertySettings: {
       types: partial.propertySettings?.types ?? 'rich',
       collapseDescription: partial.propertySettings?.collapseDescription ?? true,
+      showTitle: partial.propertySettings?.showTitle ?? false,
       expandDepth: partial.propertySettings?.expandDepth ?? 0,
       includeModelProperties: partial.propertySettings?.includeModelProperties ?? true,
     },
-    search: {
-      enableAISearch: partial.search?.enableAISearch ?? false,
+    contextMenu: partial.contextMenu ?? true,
+    experimentalPlaygrounds: partial.experimentalPlaygrounds ?? undefined,
+    experimentalRequestBuilder: partial.experimentalRequestBuilder ?? false,
+    experimentalPrerender: partial.experimentalPrerender ?? true,
+    stainlessProject: partial.stainlessProject,
+    llmsTxt: {
+      enabled: partial.llmsTxt?.disabled ?? true,
+      description: partial.llmsTxt?.description ?? null,
+      detailThreshold: partial.llmsTxt?.detailThreshold ?? 2000,
     },
-    includeAIDropdownOptions: partial.includeAIDropdownOptions ?? false,
   };
 
-  function getSpecRetrieverConfig(): SpecRetrieverConfig {
-    if ('externalSpecServerUrl' in partial) {
-      return {
-        kind: 'external_spec_server',
-        specServerUrl: partial.externalSpecServerUrl,
-        stainlessProject: null,
-      };
-    }
-
-    if (!('stainlessProject' in partial)) {
-      throw new Error('You must provide a stainlessProject when using Stainless Starlight');
-    }
-
-    const apiKey = partial.apiKey ?? process.env.STAINLESS_API_KEY ?? null;
-
-    const version = {
-      stainlessProject: partial.stainlessProject,
-      branch: partial.versions?.[0]?.branch ?? 'main',
-      version: partial.versions?.[0]?.version ?? 'v1',
-    };
-
-    const localFilePaths = getLocalFilePaths(command);
-    if (localFilePaths) {
-      return {
-        kind: 'local_spec_server_with_files',
-        devPaths: localFilePaths,
-        stainlessProject: partial.stainlessProject,
-        apiKey,
-        version,
-      };
-    }
-
-    if (!apiKey) {
-      throw new Error(
-        'Please provide a Stainless API key via the STAINLESS_API_KEY environment variable or the apiKey option in the Stainless Starlight config.',
-      );
-    }
-
-    return {
-      kind: 'local_spec_server_with_remote_files',
-      apiKey,
-      stainlessProject: partial.stainlessProject,
-      version,
-    };
-  }
-
-  const specRetrieverConfig = getSpecRetrieverConfig();
+  const api = loadAPIConfig(partial, astroOptions);
 
   return {
     ...configWithDefaults,
-    specRetrieverConfig,
+    api,
   };
 }
 
 export type NormalizedStainlessStarlightConfig = ReturnType<typeof normalizeConfig>;
 
 /*
- The goal of the code in this file is to take a user's config and normalize it. 
+ The goal of the code in this file is to take a user's config and normalize it.
  Specifically: we want a single complete config format used throughout the internals of the plugin.
 
  We've tried to avoid any config values being optional/undefined. To accomplish this:
- - Any optional config values should have their defaults set here: eg. basePath defaults to /api 
- - If a field is only used in certain contexts, we make each context a discriminated union (see SpecRetrieverConfig)
+ - Any optional config values should have their defaults set here: eg. basePath defaults to /api
+ - 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,

package/plugin/markdown/highlighter.ts

@@ -0,0 +1,100 @@
+import {
+  createHighlighter,
+  type HighlighterGeneric,
+  type ThemeInput,
+  type BundledTheme,
+  type BundledLanguage,
+} from 'shiki';
+import { HIGHLIGHT_THEMES } from 'virtual:stl-starlight-virtual-module';
+import { SupportedLanguageSyntaxes } from '@stainless-api/docs-ui/routing';
+import type { CreateShikiHighlighterOptions } from '@astrojs/markdown-remark';
+
+const STAINLESS_DOCS_JSON_THEME = {
+  name: 'stainless-docs-json',
+  colors: {
+    'editor.background': 'var(--stl-color-background)',
+    'editor.foreground': 'var(--stl-color-foreground)',
+  },
+
+  tokenColors: [
+    {
+      scope: ['comment', 'punctuation.definition.comment'],
+      settings: { foreground: 'var(--stl-color-foreground-muted)' },
+    },
+    // numbers, booleans, null
+    {
+      scope: ['constant.numeric', 'constant.language'],
+      settings: { foreground: 'var(--stl-color-orange-foreground)' },
+    },
+    // strings
+    {
+      scope: ['string', 'string.quoted', 'string.template'],
+      settings: { foreground: 'var(--stl-color-green-foreground)' },
+    },
+    // Keys, brackets
+    {
+      scope: ['support.type', 'meta'],
+      settings: { foreground: 'var(--stl-color-foreground)' },
+    },
+    // brackets
+    {
+      scope: ['meta'],
+      settings: { foreground: 'var(--stl-color-foreground-muted)' },
+    },
+    // built-in types
+    {
+      scope: ['support.type.builtin'],
+      settings: { foreground: 'var(--stl-color-purple-foreground)' },
+    },
+  ],
+} satisfies ThemeInput;
+
+// singleton
+let astroShikiHighlighter:
+  | HighlighterGeneric<BundledLanguage, BundledTheme>
+  | Promise<HighlighterGeneric<BundledLanguage, BundledTheme>>
+  | null = null;
+async function getAstroHighlighter() {
+  if (astroShikiHighlighter) {
+    return astroShikiHighlighter;
+  }
+
+  astroShikiHighlighter = createHighlighter({
+    themes: [
+      HIGHLIGHT_THEMES?.dark ?? 'github-dark',
+      HIGHLIGHT_THEMES?.light ?? 'github-light',
+      STAINLESS_DOCS_JSON_THEME,
+    ],
+    langs: SupportedLanguageSyntaxes,
+  });
+
+  return astroShikiHighlighter;
+}
+
+function runHighlight({
+  highlighter,
+  content,
+  language,
+  themes,
+}: {
+  highlighter: HighlighterGeneric<BundledLanguage, BundledTheme>;
+  content: string;
+  language?: string;
+  themes?: CreateShikiHighlighterOptions['themes'] | Record<string, 'stainless-docs-json'>;
+}) {
+  return highlighter.codeToHtml(content, {
+    lang: language ?? 'javascript',
+    themes:
+      // Default to user-provided themes except in case of json
+      themes ??
+      (language === 'JSON'
+        ? { light: 'stainless-docs-json', dark: 'stainless-docs-json' }
+        : HIGHLIGHT_THEMES) ??
+      {},
+  });
+}
+
+export async function highlight(content: string, language?: string) {
+  const highlighter = await getAstroHighlighter();
+  return runHighlight({ highlighter, content, language });
+}

package/plugin/markdown/index.ts

@@ -0,0 +1,39 @@
+import { createMarkdownProcessor, type MarkdownProcessor } from '@astrojs/markdown-remark';
+import remarkGfmAlerts from 'remark-github-alerts';
+import { HIGHLIGHT_THEMES } from 'virtual:stl-starlight-virtual-module';
+
+// singleton
+let astroMarkdownProcessor: MarkdownProcessor;
+async function getAstroMarkdown() {
+  if (!astroMarkdownProcessor) {
+    astroMarkdownProcessor = await createMarkdownProcessor({
+      gfm: true,
+      remarkPlugins: [remarkGfmAlerts],
+      shikiConfig: { themes: HIGHLIGHT_THEMES },
+    });
+  }
+
+  return astroMarkdownProcessor;
+}
+
+export async function astroMarkdownRender(content: string) {
+  const md = await getAstroMarkdown();
+  const output = await md.render(content);
+
+  // Map GFM callouts to the closest Starlight equivalent
+  // TODO: this sucks; we should be rendering via ui-primitives callouts instead of ugly theme-incompatible starlight ones
+  output.code = output.code
+    .replaceAll('markdown-alert-caution', 'markdown-alert-danger')
+    .replaceAll('markdown-alert-warning', 'markdown-alert-caution')
+    .replaceAll('markdown-alert-important', 'markdown-alert-caution')
+    .replaceAll('markdown-alert-title', 'starlight-aside__title')
+    .replaceAll('markdown-alert-', 'starlight-aside--')
+    .replaceAll('markdown-alert', 'starlight-aside');
+
+  return output;
+}
+
+export async function astroMarkdownRenderText(content: string) {
+  const result = await astroMarkdownRender(content);
+  return result.code;
+}

package/plugin/middlewareBuilder/stainlessMiddleware.d.ts

@@ -1,5 +1,7 @@
-import type { TransformRequestSnippetFn } from '@stainless-api/docs-ui/src/components/sdk';
+import type { TransformRequestSnippetFn } from '@stainless-api/docs-ui/components/sdk';
+import type { AppComponents } from '@stainless-api/docs-ui/contexts/component';
 
 export type StlStarlightMiddleware = {
   transformRequestSnippet?: TransformRequestSnippetFn;
+  componentOverrides?: Partial<AppComponents>;
 };