@stainless-api/docs 0.1.0-beta.2 → 0.1.0-beta.20

package/plugin/loadPluginConfig.ts

@@ -1,9 +1,12 @@
 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 { bold } from '../shared/terminalUtils';
 
 export type AstroCommand = 'dev' | 'build' | 'preview' | 'sync';
 
@@ -18,7 +21,7 @@ export type VersionUserConfig = {
 type BreadcrumbUserConfig = {
   /**
    * Include the current page in the breadcrumb list.
-   * Defaults to `false`.
+   * Default: `false`
    */
   includeCurrentPage?: boolean;
 };
@@ -26,7 +29,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;
 
@@ -42,7 +50,7 @@ export type StainlessStarlightUserConfig = {
 
   /**
    * Optional mount point for API reference docs.
-   * Defaults to `/api`.
+   * Default: `/api`
    * Example: `/my-api` → docs available at `/my-api/…`.
    */
   basePath?: string;
@@ -55,7 +63,7 @@ export type StainlessStarlightUserConfig = {
 
   /**
    * Optional language to treat as the default when the user hasn't selected one.
-   * Defaults to `"http"` when none is provided.
+   * Default: `"http"`
    * Example: `"python"`
    */
   defaultLanguage?: DocsLanguage;
@@ -90,7 +98,7 @@ export type StainlessStarlightUserConfig = {
   contentPanel?: {
     /**
      * Optional layout for the content panel.
-     * Defaults to `"double-pane"`.
+     * Default: `"double-pane"`
      */
     layout?: ContentLayout;
   };
@@ -107,6 +115,8 @@ export type StainlessStarlightUserConfig = {
     /**
      * When set to `true`, the enableAISearch` setting turns on support for
      * LLM-based conversations with the API documentation
+     *
+     * Default: `false`
      */
     enableAISearch?: boolean;
   };
@@ -114,7 +124,8 @@ export type StainlessStarlightUserConfig = {
   /**
    * Enable experimental collapsible code snippets. Snippets will be collapsed by default for
    * single-pane and mobile layouts.
-   * Defaults to `false`.
+   *
+   * Default: `false`
    */
   experimentalCollapsibleSnippets?: boolean;
 };
@@ -133,15 +144,29 @@ function getLocalFilePaths(command: AstroCommand): InputFilePaths | null {
   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 ApiKeySource = 'explicit-config' | 'environment-variable' | 'cli';
+
+export type LoadedApiKey = {
+  value: string;
+  source: ApiKeySource;
+};
+
 export type SpecRetrieverConfig =
   | {
       kind: 'external_spec_server';
@@ -152,16 +177,63 @@ export type SpecRetrieverConfig =
       kind: 'local_spec_server_with_files';
       stainlessProject: string;
       devPaths: InputFilePaths;
-      apiKey: string | null;
+      apiKey: LoadedApiKey | null;
       version: VersionUserConfig;
     }
   | {
       kind: 'local_spec_server_with_remote_files';
       stainlessProject: string;
-      apiKey: string;
+      apiKey: LoadedApiKey;
       version: VersionUserConfig;
     };
 
+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' };
+}
+
 function normalizeConfig(partial: SomeStainlessStarlightUserConfig, command: AstroCommand) {
   const configWithDefaults = {
     basePath: partial.basePath ?? '/api',
@@ -205,7 +277,7 @@ function normalizeConfig(partial: SomeStainlessStarlightUserConfig, command: Ast
       throw new Error('You must provide a stainlessProject when using Stainless Starlight');
     }
 
-    const apiKey = partial.apiKey ?? process.env.STAINLESS_API_KEY ?? null;
+    const apiKey = loadApiKey(partial.apiKey);
 
     const version = {
       stainlessProject: partial.stainlessProject,
@@ -226,7 +298,14 @@ function normalizeConfig(partial: SomeStainlessStarlightUserConfig, command: Ast
 
     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.',
+        [
+          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'),
       );
     }
 

package/plugin/react/Routing.tsx

@@ -6,8 +6,8 @@ import remarkGfmAlerts from 'remark-github-alerts';
 
 import type { MarkdownHeading } from 'astro';
 import type { StarlightRouteData } from '@astrojs/starlight/route-data';
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
-import type { DocsLanguage } from '@stainless-api/docs-ui/src/routing';
+import type * as SDKJSON from '@stainless/sdk-json';
+import { LanguageNames, type DocsLanguage } from '@stainless-api/docs-ui/src/routing';
 
 import {
   generateRouteList,
@@ -48,14 +48,14 @@ import {
   HIGHLIGHT_THEMES,
   BREADCRUMB_CONFIG,
   PROPERTY_SETTINGS,
+  ENABLE_CONTEXT_MENU,
 } from 'virtual:stl-starlight-virtual-module';
 import style from '@stainless-api/docs-ui/src/style';
 import { createHighlighter, type BundledLanguage, type BundledTheme, type HighlighterGeneric } from 'shiki';
 import { SnippetCode, SnippetContainer, SnippetRequestContainer } from '../components/SnippetCode';
-import clsx from 'clsx';
 import type { StlStarlightMiddleware } from '../middlewareBuilder/stainlessMiddleware';
 import { ComponentProvider } from '@stainless-api/docs-ui/src/contexts/component';
-import { APIReferenceAIDropdown } from '../../stl-docs/components/APIReferenceAIDropdown';
+import { AIDropdown } from '../../stl-docs/components/AIDropdown';
 
 export function generateDocsRoutes(spec: SDKJSON.Spec) {
   const paths = generateRouteList({
@@ -120,7 +120,6 @@ export function buildSidebar(
 
       const meths: SidebarEntry[] = Object.values(resource.methods ?? [])
         .filter((method) => spec.decls?.[language]?.[method.stainlessPath])
-        .toSorted((first, second) => first.name.localeCompare(second.name))
         .map((method) => ({
           type: 'link',
           isCurrent: current === method.stainlessPath,
@@ -179,25 +178,25 @@ export function SDKSelectReactComponent({
   return (
     <Dropdown id={id} data-current-value={selected} className={className}>
       <DropdownTrigger
-        className="dropdown-toggle stldocs-button-tertiary"
+        className="dropdown-toggle"
         type="button"
-        id="stldocs-snippet-title-button"
+        id="stl-docs-snippet-title-button"
         aria-expanded="false"
         withChevron
       >
         <SDKIcon language={getLanguageSnippet(selected)} size={16} />
-        <span className={clsx('stl-snippet-dropdown-button-text', selected)}>{selected}</span>
+        <span className="stl-snippet-dropdown-button-text">{LanguageNames[selected]}</span>
       </DropdownTrigger>
       <DropdownMenu
         className="dropdown-menu stl-sdk-select-dropdown-menu"
         position="below"
-        aria-labelledby="stldocs-snippet-title-button"
+        aria-labelledby="stl-docs-snippet-title-button"
       >
         {languages.map((item) => (
           <DropdownItem key={item} value={item} selected={item === selected}>
             <div>
               <SDKIcon language={getLanguageSnippet(item)} size={16} />
-              <span className={clsx('stl-snippet-dropdown-button-text', item)}>{item}</span>
+              <span className="stl-snippet-dropdown-button-text">{LanguageNames[item]}</span>
             </div>
           </DropdownItem>
         ))}
@@ -302,7 +301,10 @@ export function RenderSpec({
   const parsed = parseStainlessPath(path);
   const resource = getResourceFromSpec(path, spec);
 
-  if (!resource || !parsed) return null;
+  if (!resource || !parsed) {
+    console.warn(`Could not find resource or parsed path for '${path}'`);
+    return null;
+  }
 
   return (
     <DocsProvider
@@ -323,7 +325,7 @@ export function RenderSpec({
       >
         <NavigationProvider basePath={BASE_PATH} selectedPath={path}>
           <MarkdownProvider render={renderMarkdown} highlight={highlight}>
-            {kind === 'http_method' ? (
+            {
               <div className="stldocs-root stl-ui-not-prose">
                 <div className="stl-page-nav-container">
                   <SDKBreadcrumbs
@@ -332,27 +334,18 @@ export function RenderSpec({
                     basePath={BASE_PATH}
                     config={BREADCRUMB_CONFIG}
                   />
-                  <APIReferenceAIDropdown />
+                  {ENABLE_CONTEXT_MENU && <AIDropdown />}
                 </div>
-                <SDKMethod
-                  method={resource.methods[parsed.method]}
-                  transformRequestSnippet={transformRequestSnippet}
-                />
-              </div>
-            ) : (
-              <div className="stldocs-root stl-ui-not-prose">
-                <div className="stl-page-nav-container">
-                  <SDKBreadcrumbs
-                    spec={spec as SDKJSON.Spec}
-                    currentPath={currentPath}
-                    basePath={BASE_PATH}
-                    config={BREADCRUMB_CONFIG}
+                {kind === 'http_method' ? (
+                  <SDKMethod
+                    method={resource.methods[parsed.method!]!}
+                    transformRequestSnippet={transformRequestSnippet}
                   />
-                  <APIReferenceAIDropdown />
-                </div>
-                <SDKOverview resource={resource} />
+                ) : (
+                  <SDKOverview resource={resource} />
+                )}
               </div>
-            )}
+            }
           </MarkdownProvider>
         </NavigationProvider>
       </ComponentProvider>
@@ -366,10 +359,14 @@ export function RenderMethod({ path }: { path: string }) {
 
   const parsed = parseStainlessPath(path);
   const resource = getResourceFromSpec(path, spec);
-  if (!resource || !parsed) return null;
 
-  const meth = resource.methods[parsed.method];
-  return <SDKMethod method={meth} />;
+  if (!resource || !parsed) {
+    console.warn(`Could not find resource or parsed path for '${path}'`);
+    return null;
+  }
+
+  const method = resource.methods[parsed.method!]!;
+  return <SDKMethod method={method} />;
 }
 
 export async function getReadmeContent(spec: SDKJSON.Spec, language: DocsLanguage) {

package/plugin/referencePlaceholderUtils.ts

@@ -58,7 +58,7 @@ function recursiveGetPlaceholderItems(
   items: PlaceholderItemResult[],
 ): PlaceholderItemResult[] {
   for (let i = 0; i < sidebar.length; i++) {
-    const entry = sidebar[i];
+    const entry = sidebar[i]!;
     if ('attrs' in entry && entry.attrs?.about === INTERNAL_REFERENCE_ENTRY_MARKER) {
       items.push({
         index: i,

package/plugin/replaceSidebarPlaceholderMiddleware.ts

@@ -15,6 +15,10 @@ export const onRequest = defineRouteMiddleware(async (context) => {
 
   const slug = `/${context.locals.starlightRoute.id}`; // same as .slug but not deprecated
 
+  context.locals.starlightRoute._stlStarlight = {
+    basePath: BASE_PATH,
+  };
+
   const apiReferencePlaceholderItems = getAPIReferencePlaceholderItems(context.locals.starlightRoute.sidebar);
 
   const spec = await cmsClient.getSpec();

package/plugin/routes/Docs.astro

@@ -1,24 +1,15 @@
 ---
-import StarlightPage from "@astrojs/starlight/components/StarlightPage.astro";
-import { cmsClient } from "../cms/client";
-
-import "@stainless-api/docs-ui/src/styles/resets.css";
-import "@stainless-api/docs-ui/src/styles/primitives.css";
-import "@stainless-api/docs-ui/src/styles/main.css";
-import "@stainless-api/docs-ui/src/styles/snippets.css";
-// TODO: fix variables.css import
-// import "./variables.css";
-
+import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
+import { cmsClient } from '../cms/client';
 import {
   getReadmeContent,
   generateDocsRoutes,
   buildPageNavigation,
   RenderSpec,
   astroMarkdownRender,
-} from "../react/Routing";
-import { getResourceFromSpec } from "@stainless-api/docs-ui/src/utils";
-import { BASE_PATH, CONTENT_PANEL_LAYOUT,MIDDLEWARE } from "virtual:stl-starlight-virtual-module";
-
+} from '../react/Routing';
+import { getResourceFromSpec } from '@stainless-api/docs-ui/src/utils';
+import { BASE_PATH, CONTENT_PANEL_LAYOUT, MIDDLEWARE } from 'virtual:stl-starlight-virtual-module';
 
 const spec = await cmsClient.getSpec();
 const routes = generateDocsRoutes(spec);
@@ -26,23 +17,23 @@ const routes = generateDocsRoutes(spec);
 const route = routes.find((r) => r.params.slug === Astro.params.slug);
 
 if (!route) {
-  throw new Error("No such route");
+  throw new Error(`Could not find a route for slug '${Astro.params.slug}'`);
 }
 
+// PageTitle override will skip rendering the default Starlight title
+Astro.locals._stlStarlightPage = {
+  skipRenderingStarlightTitle: route.props.kind === 'readme' ? false : true,
+};
+
 const readmeContent = await getReadmeContent(spec, route.props.language);
-const readme =
-  route.props.kind === "readme"
-    ? await astroMarkdownRender(readmeContent ?? "")
-    : null;
+const readme = route.props.kind === 'readme' ? await astroMarkdownRender(readmeContent ?? '') : null;
 
-const resource = route.props.stainlessPath
-  ? getResourceFromSpec(route.props.stainlessPath, spec)
-  : null;
+const resource = route.props.stainlessPath ? getResourceFromSpec(route.props.stainlessPath, spec) : null;
 
 const pageNav =
-  route.props.kind === "resource" && resource
+  route.props.kind === 'resource' && resource
     ? buildPageNavigation(resource)
-    : route.props.kind === "readme" && readme?.metadata
+    : route.props.kind === 'readme' && readme?.metadata
       ? readme?.metadata.headings
       : [];
 
@@ -50,38 +41,27 @@ const props = route.props;
 
 if (readme) {
   const repo = spec.metadata?.[props.language]?.code_url;
-  readme.code = readme.code.replace(
-    /<a href="(?!(?:https?:\/\/|\/\/))([^"]+)"/g,
-    `<a href="${repo}/$1"`);
-  props.title = readme.metadata.headings[0].text ?? "Overview";
+  readme.code = readme.code.replace(/<a href="(?!(?:https?:\/\/|\/\/))([^"]+)"/g, `<a href="${repo}/$1"`);
+  props.title = readme.metadata.headings[0]!.text ?? 'Overview';
 }
-
 ---
 
-
 <StarlightPage
   headings={pageNav}
   frontmatter={{
     title: props?.title,
     head: [
       {
-        tag: "link",
+        tag: 'link',
         attrs: {
-          rel: "alternate",
-          type: "text/markdown",
-          href: `${BASE_PATH}/${Astro.params.slug}.md`
-        }
-      }
+          rel: 'alternate',
+          type: 'text/markdown',
+          href: `${BASE_PATH}/${Astro.params.slug}.md`,
+        },
+      },
     ],
     pagefind: false,
-    tableOfContents: ["resource", "readme"].includes(props.kind)
-      ? { maxHeadingLevel: 6 }
-      : false,
-    // @ts-ignore
-    stainlessStarlight: {
-      basePath: BASE_PATH,
-      ...props,
-    },
+    tableOfContents: ['resource', 'readme'].includes(props.kind) ? { maxHeadingLevel: 6 } : false,
   }}
 >
   {
@@ -97,7 +77,9 @@ if (readme) {
           transformRequestSnippet={MIDDLEWARE.transformRequestSnippet}
         />
 
-        <style is:inline>
+        <style
+          is:inline
+          set:text={`
           #stldocs-snippet-title {
             display: flex;
             gap: 5px;
@@ -105,61 +87,53 @@ if (readme) {
 
           .stldocs-snippet-code:not(.stldocs-snippet-response .stldocs-snippet-code) {
             padding: 0 !important;
-            
+
             .astro-code {
               padding: 1rem;
             }
           }
 
-
           [data-has-sidebar]:not([data-has-toc]) .sl-container {
             max-width: 1428px;
           }
-
-          .content-panel:nth-of-type(1) {
-            display: none;
-          }
-          .content-panel:nth-of-type(2) .stl-page-nav-container {
-            display: none;
-          }
-
-          .content-panel:nth-of-type(2) .stldocs-root .stl-page-nav-container {
-            display: flex;
-          }
-        </style>
+        `}
+        />
       </div>
     ) : (
       <>
         <Fragment set:html={readme?.code} />
-        <style is:inline>
-          .sl-markdown-content h1:first-of-type {
-            display: none;
-          }
+        <style
+          is:inline
+          set:text={`
+            .sl-markdown-content h1:first-of-type {
+              display: none;
+            }
 
-          .sl-markdown-content img {
-            display: inline-block;
-            vertical-align: text-bottom;
-          }
+            .sl-markdown-content img {
+              display: inline-block;
+              vertical-align: text-bottom;
+            }
 
-          .sl-markdown-content .octicon {
-            margin-right: 0.2rem;
-            overflow: visible !important;
-            -webkit-mask: var(--oct-icon) no-repeat;
-            mask: var(--oct-icon) no-repeat;
-            -webkit-mask-size: 100% 100%;
-            mask-size: 100% 100%;
-            background-color: currentColor;
-            color: inherit;
-            display: inline-block;
-            vertical-align: text-bottom;
-            width: 1em;
-            height: 1em;
-          }
+            .sl-markdown-content .octicon {
+              margin-right: 0.2rem;
+              overflow: visible !important;
+              -webkit-mask: var(--oct-icon) no-repeat;
+              mask: var(--oct-icon) no-repeat;
+              -webkit-mask-size: 100% 100%;
+              mask-size: 100% 100%;
+              background-color: currentColor;
+              color: inherit;
+              display: inline-block;
+              vertical-align: text-bottom;
+              width: 1em;
+              height: 1em;
+            }
 
-          .sl-markdown-content code {
-            white-space: pre-wrap;
-          }
-        </style>
+            .sl-markdown-content code {
+              white-space: pre-wrap;
+            }
+          `}
+        />
       </>
     )
   }

package/plugin/routes/Overview.astro

@@ -1,24 +1,22 @@
 ---
 import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
-import { BASE_PATH, EXCLUDE_LANGUAGES } from 'virtual:stl-starlight-virtual-module';
+import { EXCLUDE_LANGUAGES } from 'virtual:stl-starlight-virtual-module';
 import { cmsClient } from '../cms/client';
 import type { DocsLanguage } from '@stainless-api/docs-ui/src/routing';
-
-import '@stainless-api/docs-ui/src/styles/resets.css';
-import '@stainless-api/docs-ui/src/styles/primitives.css';
-import '@stainless-api/docs-ui/src/styles/main.css';
-import '@stainless-api/docs-ui/src/styles/snippets.css';
-// TODO: fix variables.css import
-// import '../components/variables.css';
 import { RenderLibraries, RenderSpecOverview, type SpecMetadata } from '../react/Routing';
 
 const spec = await cmsClient.getSpec();
 
 const languages: DocsLanguage[] = spec.docs!.languages ?? ['http'];
-const metadata = languages
+const metadata: SpecMetadata = languages
   .filter((language) => !['http', 'terraform'].includes(language) && spec.metadata[language])
   .filter((language) => !EXCLUDE_LANGUAGES.includes(language))
-  .map((language) => [language, spec.metadata[language]]) as SpecMetadata;
+  .map<SpecMetadata[number]>((language) => [language, spec.metadata[language]!]);
+
+// PageTitle override will skip rendering the default Starlight title
+Astro.locals._stlStarlightPage = {
+  hasMarkdownRoute: false,
+};
 ---
 
 <StarlightPage
@@ -26,15 +24,11 @@ const metadata = languages
     title: 'API Reference',
     pagefind: false,
     tableOfContents: false,
-    stainlessStarlight: {
-      basePath: BASE_PATH,
-      language: 'http',
-    },
   }}
 >
   <h3>Libraries</h3>
 
-  <div class="stldocs-root language-blocks stl-ui-not-prose">
+  <div class="stldocs-root language-blocks stl-ui-not-prose not-content">
     <RenderLibraries metadata={metadata} />
   </div>
 

package/plugin/routes/markdown.ts

@@ -47,7 +47,7 @@ export const GET: APIRoute<RouteProps> = async ({ props }) => {
     },
   };
 
-  const target = props.kind === 'http_method' && parsed?.method ? resource.methods[parsed.method] : resource;
+  const target = props.kind === 'http_method' && parsed?.method ? resource.methods[parsed.method]! : resource;
   const output = renderMarkdown(env, target);
 
   return new Response(output, {