@stainless-api/docs 0.1.0-beta.4 → 0.1.0-beta.40

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 { DocsLanguage } from '@stainless-api/docs-ui/routing';
+import type { PropertySettingsType } from '@stainless-api/docs-ui/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,8 +50,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 +63,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 +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,9 +124,17 @@ 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;
+
+  /**
+   * Whether to show the context menu with options like "Copy as Markdown" and "Open in ChatGPT".
+   *
+   * @default true
+   */
+  contextMenu?: boolean;
 };
 
 export type ExternalSpecServerUserConfig = Omit<StainlessStarlightUserConfig, 'stainlessProject'> & {
@@ -133,15 +151,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 +184,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',
@@ -190,6 +269,7 @@ function normalizeConfig(partial: SomeStainlessStarlightUserConfig, command: Ast
     search: {
       enableAISearch: partial.search?.enableAISearch ?? false,
     },
+    contextMenu: partial.contextMenu ?? true,
   };
 
   function getSpecRetrieverConfig(): SpecRetrieverConfig {
@@ -205,7 +285,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 +306,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'),
       );
     }
 
@@ -249,11 +336,11 @@ function normalizeConfig(partial: SomeStainlessStarlightUserConfig, command: Ast
 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 
+ - 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)
  - We prefer empty arrays over undefined/null
 */

package/plugin/middlewareBuilder/stainlessMiddleware.d.ts

@@ -1,4 +1,4 @@
-import type { TransformRequestSnippetFn } from '@stainless-api/docs-ui/src/components/sdk';
+import type { TransformRequestSnippetFn } from '@stainless-api/docs-ui/components/sdk';
 
 export type StlStarlightMiddleware = {
   transformRequestSnippet?: TransformRequestSnippetFn;

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/routing';
 
 import {
   generateRouteList,
@@ -16,7 +16,7 @@ import {
   walkTree,
   SupportedLanguageSyntaxes,
   getLanguageSnippet,
-} from '@stainless-api/docs-ui/src/routing';
+} from '@stainless-api/docs-ui/routing';
 
 import {
   DocsProvider,
@@ -24,23 +24,22 @@ import {
   NavigationProvider,
   useSpec,
   type ContentPanelLayout,
-} from '@stainless-api/docs-ui/src/contexts';
+} from '@stainless-api/docs-ui/contexts';
 
-import { flatResources, getResourceFromSpec } from '@stainless-api/docs-ui/src/utils';
+import { flatResources, getResourceFromSpec } from '@stainless-api/docs-ui/utils';
 
 import {
   SDKMethod,
   SDKResource,
   type SDKRequestTitleProps,
   SDKBreadcrumbs,
-  Dropdown,
-  DropdownTrigger,
-  DropdownMenu,
-  DropdownItem,
   SDKIcon,
   SDKOverview,
   SDKLanguageBlock,
-} from '@stainless-api/docs-ui/src/components';
+} from '@stainless-api/docs-ui/components';
+
+import { Dropdown } from '@stainless-api/docs/components';
+
 import {
   BASE_PATH,
   EXCLUDE_LANGUAGES,
@@ -48,14 +47,15 @@ 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 style from '@stainless-api/docs-ui/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 { ComponentProvider } from '@stainless-api/docs-ui/contexts/component';
+import { AIDropdown } from '../../stl-docs/components/AIDropdown';
+import { ChevronsUpDownIcon } from 'lucide-react';
 
 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,
@@ -178,30 +177,36 @@ export function SDKSelectReactComponent({
 }) {
   return (
     <Dropdown id={id} data-current-value={selected} className={className}>
-      <DropdownTrigger
-        className="dropdown-toggle stldocs-button-tertiary"
-        type="button"
-        id="stldocs-snippet-title-button"
-        aria-expanded="false"
-        withChevron
-      >
-        <SDKIcon language={getLanguageSnippet(selected)} size={16} />
-        <span className={clsx('stl-snippet-dropdown-button-text', selected)}>{selected}</span>
-      </DropdownTrigger>
-      <DropdownMenu
+      <Dropdown.Trigger>
+        <Dropdown.TriggerSelectedItem>
+          <Dropdown.Icon>
+            <SDKIcon language={getLanguageSnippet(selected)} />
+          </Dropdown.Icon>
+          <span className="stl-snippet-dropdown-button-text">{LanguageNames[selected]}</span>
+        </Dropdown.TriggerSelectedItem>
+        <Dropdown.TriggerIcon>
+          <ChevronsUpDownIcon size={16} />
+        </Dropdown.TriggerIcon>
+      </Dropdown.Trigger>
+      <Dropdown.Menu
         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>
+          <Dropdown.MenuItem key={item} value={item} isSelected={item === selected}>
+            <Dropdown.Icon>
               <SDKIcon language={getLanguageSnippet(item)} size={16} />
-              <span className={clsx('stl-snippet-dropdown-button-text', item)}>{item}</span>
-            </div>
-          </DropdownItem>
+            </Dropdown.Icon>
+            <Dropdown.MenuItemText>{LanguageNames[item]}</Dropdown.MenuItemText>
+            <Dropdown.MenuItemTemplate>
+              <Dropdown.Icon>
+                <SDKIcon language={getLanguageSnippet(item)} size={16} />
+              </Dropdown.Icon>
+              <span className="stl-snippet-dropdown-button-text">{LanguageNames[item]}</span>
+            </Dropdown.MenuItemTemplate>
+          </Dropdown.MenuItem>
         ))}
-      </DropdownMenu>
+      </Dropdown.Menu>
     </Dropdown>
   );
 }
@@ -302,7 +307,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 +331,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 +340,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 +365,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

@@ -5,7 +5,7 @@ import { BASE_PATH } from 'virtual:stl-starlight-virtual-module';
 import { getAPIReferencePlaceholderItems } from './referencePlaceholderUtils';
 import { getMethodFromSDKJSON, recursiveReplacePlaceholderItems } from './generateAPIReferenceLink';
 import { forceGenerateRoute } from './cms/sidebar-builder';
-import { parseRoute } from '@stainless-api/docs-ui/src/routing';
+import { parseRoute } from '@stainless-api/docs-ui/routing';
 
 // this fn is loaded in the plugin via addRouteMiddleware
 
@@ -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();