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

package/plugin/cms/server.ts

@@ -1,10 +1,11 @@
+import type { AstroIntegrationLogger } from 'astro';
 import { createServer, IncomingMessage } from 'http';
 import { readFile } from 'fs/promises';
 
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
+import type * as SDKJSON from '@stainless/sdk-json';
 import { createSDKJSON, parseInputs, transformOAS } from './worker';
-import { Languages, parseRoute, type DocsLanguage } from '@stainless-api/docs-ui/src/routing';
-import Stainless from '@stainless-api/sdk';
+import { Languages, parseRoute, type DocsLanguage } from '@stainless-api/docs-ui/routing';
+import Stainless, { APIError } from '@stainless-api/sdk';
 
 import {
   toStarlightSidebar,
@@ -12,88 +13,118 @@ import {
   SidebarConfigItemsBuilder,
 } from './sidebar-builder';
 import type { VersionUserConfig } from '../loadPluginConfig';
+import { bold } from '../../shared/terminalUtils';
 
 export type InputFilePaths = {
   oasPath?: string;
   configPath?: string;
 };
 
-async function versionInfo(project: string, apiKey: string) {
+async function versionInfo(project: string, apiKey: string): Promise<Record<DocsLanguage, string>> {
   const data = await fetch(`https://api.stainless.com/api/projects/${project}/package-versions`, {
     headers: { Authorization: `Bearer ${apiKey}` },
   });
 
   const content = await data.text();
-  return JSON.parse(content);
+  return JSON.parse(content) as Record<DocsLanguage, string>;
+}
+
+function redactApiKey(apiKey: string) {
+  return apiKey
+    .split('')
+    .map((char, index) => (index < 10 ? char : '*'))
+    .join('');
 }
 
 async function loadSpec({
   apiKey,
   devPaths,
   version,
+  logger,
 }: {
   apiKey: string;
   devPaths: InputFilePaths;
   version: VersionUserConfig;
+  logger: AstroIntegrationLogger;
 }) {
-  let oasStr: string;
-  let configStr: string;
-  let versions: Record<DocsLanguage, string> | undefined;
-
-  if (devPaths.oasPath && devPaths.configPath) {
-    [oasStr, configStr] = await Promise.all([
-      readFile(devPaths.oasPath, 'utf-8'),
-      readFile(devPaths.configPath, 'utf-8'),
-    ]);
-  } else {
-    const client = new Stainless({ apiKey });
-    const configs = await client.projects.configs.retrieve({
-      project: version.stainlessProject,
-      branch: version.branch,
-      include: 'openapi',
-    });
+  async function unsafeLoad() {
+    let oasStr: string;
+    let configStr: string;
+    let versions: Record<DocsLanguage, string> | undefined;
+
+    if (devPaths.oasPath && devPaths.configPath) {
+      [oasStr, configStr] = await Promise.all([
+        readFile(devPaths.oasPath, 'utf-8'),
+        readFile(devPaths.configPath, 'utf-8'),
+      ]);
+    } else {
+      const client = new Stainless({ apiKey });
+      const configs = await client.projects.configs.retrieve({
+        project: version.stainlessProject,
+        branch: version.branch,
+        include: 'openapi',
+      });
 
-    versions = await versionInfo(version.stainlessProject, apiKey);
+      versions = await versionInfo(version.stainlessProject, apiKey);
 
-    const configYML = Object.values(configs)[0] as { content: any };
-    const oasJson = Object.values(configs)[1] as { content: any };
-    oasStr = oasJson['content'];
-    configStr = configYML['content'];
-  }
+      const configYML = Object.values(configs)[0] as { content: any };
+      const oasJson = Object.values(configs)[1] as { content: any };
+      oasStr = oasJson['content'];
+      configStr = configYML['content'];
+    }
 
-  const { oas, config } = await parseInputs({
-    oas: oasStr,
-    config: configStr,
-  });
+    const { oas, config } = await parseInputs({
+      oas: oasStr,
+      config: configStr,
+    });
 
-  const transformedOAS = await transformOAS({ oas, config });
+    const transformedOAS = await transformOAS({ oas, config });
 
-  const languages =
-    config.docs?.languages ??
-    (Object.entries(config.targets)
-      // @ts-expect-error we don't have the actual Stainless config type here
-      .filter(([name, target]) => Languages.includes(name) && !target.skip)
-      .map(([name]) => name) as SDKJSON.SpecLanguage[]);
+    const languages =
+      config.docs?.languages ??
+      (Object.entries(config.targets)
+        // @ts-expect-error we don't have the actual Stainless config type here
+        .filter(([name, target]) => Languages.includes(name) && !target.skip)
+        .map(([name]) => name) as SDKJSON.SpecLanguage[]);
 
-  const sdkJson = await createSDKJSON({
-    oas: transformedOAS,
-    config,
-    languages,
-  });
+    const sdkJson = await createSDKJSON({
+      oas: transformedOAS,
+      config,
+      languages,
+    });
 
-  if (versions) {
-    for (const [lang, version] of Object.entries(versions)) {
-      const meta = sdkJson.metadata[lang as DocsLanguage];
-      if (meta?.version) meta.version = version;
+    if (versions) {
+      for (const [lang, version] of Object.entries(versions)) {
+        const meta = sdkJson.metadata[lang as DocsLanguage];
+        if (meta?.version) meta.version = version;
+      }
     }
+
+    const id = crypto.randomUUID();
+
+    return {
+      data: sdkJson,
+      id,
+    };
   }
 
-  const id = crypto.randomUUID();
+  try {
+    const result = await unsafeLoad();
+    return result;
+  } catch (error) {
+    logger.error(bold('Failed to fetch API reference information from Stainless:'));
+    if (error instanceof APIError && error.status >= 400 && error.status < 500) {
+      logger.error(`Requested project slug: "${version.stainlessProject}"`);
+      logger.error(`API key: "${redactApiKey(apiKey)}"`);
+      logger.error(
+        `This error can usually be corrected by re-authenticating with the Stainless.  Use the CLI (stl auth login) or verify that the Stainless API key you're using can access the project mentioned above.`,
+      );
+    } else {
+      logger.error(error instanceof Error ? error.message : 'Unknown error');
+    }
 
-  return {
-    data: sdkJson,
-    id,
-  };
+    process.exit(1);
+  }
 }
 
 class Spec {
@@ -107,6 +138,7 @@ class Spec {
       apiKey: this.apiKey,
       devPaths: this.devPaths,
       version: this.version,
+      logger: this.logger,
     });
   }
 
@@ -128,15 +160,22 @@ class Spec {
     return spec;
   }
 
-  constructor(apiKey: string, version: VersionUserConfig, devPaths: InputFilePaths) {
+  constructor(
+    apiKey: string,
+    version: VersionUserConfig,
+    devPaths: InputFilePaths,
+    private logger: AstroIntegrationLogger,
+  ) {
     this.specPromise = loadSpec({
       apiKey,
       devPaths,
       version,
+      logger,
     });
     this.devPaths = devPaths;
     this.apiKey = apiKey;
     this.version = version;
+    this.logger = logger;
   }
 }
 
@@ -166,14 +205,16 @@ export function startDevServer({
   devPaths,
   apiKey,
   getGeneratedSidebarConfig,
+  logger,
 }: {
   port: number;
   version: VersionUserConfig;
   devPaths: InputFilePaths;
   apiKey: string;
   getGeneratedSidebarConfig: (id: number) => GeneratedSidebarConfig | null;
+  logger: AstroIntegrationLogger;
 }) {
-  const spec = new Spec(apiKey, version, devPaths);
+  const spec = new Spec(apiKey, version, devPaths, logger);
 
   const server = createServer(async (req, res) => {
     // Add CORS headers
@@ -250,7 +291,7 @@ export function startDevServer({
   });
 
   server.listen(port, () => {
-    console.log(`Server is running on port ${port}`);
+    logger.debug(`Stainless spec server is running on port: ${port}`);
   });
 
   return {
@@ -266,3 +307,5 @@ export function startDevServer({
     },
   };
 }
+
+export type DevSpecServer = Awaited<ReturnType<typeof startDevServer>>;

package/plugin/cms/sidebar-builder.ts

@@ -1,5 +1,5 @@
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
-import { generateRoute, walkTree, type DocsLanguage } from '@stainless-api/docs-ui/src/routing';
+import type * as SDKJSON from '@stainless/sdk-json';
+import { generateRoute, walkTree, type DocsLanguage } from '@stainless-api/docs-ui/routing';
 import type { StarlightRouteData } from '@astrojs/starlight/route-data';
 
 function isResourceNonEmpty(resource: SDKJSON.Resource) {
@@ -120,22 +120,12 @@ export type GeneratedSidebarConfig = {
 };
 
 function countKeys(obj?: Record<string, any>) {
-  let o = obj ?? {};
+  const o = obj ?? {};
   return Object.keys(o).length;
 }
 
-function getMethodDeclForLanguage(entry: SDKJSON.Method, spec: SDKJSON.Spec, language: DocsLanguage) {
-  const decls = spec.decls[language] ?? {};
-  const decl = decls[entry.stainlessPath];
-  if (decl !== undefined) {
-    if ('ident' in decl) {
-      return decl;
-    }
-  }
-  return null;
-}
-
-type MethodDecl = Exclude<ReturnType<typeof getMethodDeclForLanguage>, null>;
+type HasIdent<T> = T extends { ident: unknown } ? T : never;
+type MethodDecl = HasIdent<SDKJSON.LanguageDeclNodes[SDKJSON.SpecLanguage]>;
 
 function makeAPIOverviewPage(): UserSidebarAPIOverviewPage {
   return {
@@ -166,7 +156,7 @@ function pullOutSharedModelsResource(resources: SDKJSON.Resource[]): {
 }
 
 export class SidebarConfigItemsBuilder {
-  private getMethodDeclForLanguage(entry: SDKJSON.Method) {
+  private getMethodDeclForLanguage(entry: SDKJSON.Method): MethodDecl | null {
     const decls = this.spec.decls[this.language] ?? {};
     const decl = decls[entry.stainlessPath];
     if (decl !== undefined) {
@@ -208,13 +198,6 @@ export class SidebarConfigItemsBuilder {
     };
   }
 
-  private sortByLabel<T extends UserSidebarConfigItem>(items: T[]) {
-    // sorts in place
-    items.sort((a, b) => {
-      return a.label.localeCompare(b.label);
-    });
-  }
-
   private generateResourceGroup(resource: SDKJSON.Resource, collapsed: boolean): ReferenceSidebarGroup {
     const entries: ReferenceSidebarConfigItem[] = [];
     if (!this.options?.excludeResourceOverviewPages) {
@@ -228,7 +211,6 @@ export class SidebarConfigItemsBuilder {
         methodPages.push(this.toMethodPage(m, langDecl));
       }
     }
-    this.sortByLabel(methodPages);
     entries.push(...methodPages);
 
     const subresources = Object.values(resource.subresources ?? {});
@@ -238,7 +220,6 @@ export class SidebarConfigItemsBuilder {
         subresourceGroups.push(this.generateResourceGroup(sub, true));
       }
     }
-    this.sortByLabel(subresourceGroups);
     entries.push(...subresourceGroups);
 
     return {
@@ -253,7 +234,7 @@ export class SidebarConfigItemsBuilder {
 
   public generateItems(): ReferenceSidebarConfigItem[] {
     const resourceMap = this.spec.resources;
-    let { resources, sharedModelsResource } = pullOutSharedModelsResource(Object.values(resourceMap ?? {}));
+    const { resources, sharedModelsResource } = pullOutSharedModelsResource(Object.values(resourceMap ?? {}));
 
     const entries: ReferenceSidebarConfigItem[] = resources.filter(isResourceNonEmpty).map((r) => {
       return this.generateResourceGroup(r, false);

package/plugin/cms/worker.ts

@@ -1,6 +1,6 @@
 import Worker from 'web-worker';
-import { Languages, type DocsLanguage } from '@stainless-api/docs-ui/src/routing';
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
+import { Languages, type DocsLanguage } from '@stainless-api/docs-ui/routing';
+import type * as SDKJSON from '@stainless/sdk-json';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 import fs from 'fs/promises';
@@ -98,7 +98,7 @@ export async function createSDKJSON({
       try {
         const content = await fs.readFile(mdfile);
         return [language, content.toString()];
-      } catch (err) {
+      } catch {
         return [language, null];
       }
     }),

package/plugin/components/SDKSelect.astro

@@ -1,6 +1,6 @@
 ---
-import type { DocsLanguage } from '@stainless-api/docs-ui/src/routing';
-import { parseRoute } from '@stainless-api/docs-ui/src/routing';
+import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
+import { parseRoute } from '@stainless-api/docs-ui/routing';
 import { cmsClient } from '../cms/client';
 import { BASE_PATH, DEFAULT_LANGUAGE, EXCLUDE_LANGUAGES } from 'virtual:stl-starlight-virtual-module';
 import { Languages } from '../languages';
@@ -138,15 +138,17 @@ const readmeSlug = language === 'http' ? BASE_PATH : `${BASE_PATH}/${language}`;
 <script>
   import { navigate } from 'astro:transitions/client';
   import { updateSelectedLanguage } from '../languages';
-  import { initDropdown } from '@stainless-api/docs-ui/src/components/scripts/dropdown';
+  import { initDropdown } from '@stainless-api/docs/components/scripts';
   import { BASE_PATH } from 'virtual:stl-starlight-virtual-module';
   import { getPageLoadEvent } from '../helpers/getPageLoadEvent';
 
   document.addEventListener(getPageLoadEvent(), () => {
+    const sdkSelect = document.getElementById('sidebar-sdk-select');
+    if (!sdkSelect) return;
     initDropdown({
-      dropdownId: 'sidebar-sdk-select',
+      root: sdkSelect,
       onSelect: (value) => {
-        const originalLanguage = document.getElementById('sidebar-sdk-select')?.dataset.currentValue;
+        const originalLanguage = sdkSelect.dataset.currentValue;
         navigate(updateSelectedLanguage(BASE_PATH, originalLanguage, value));
       },
     });

package/plugin/components/SnippetCode.tsx

@@ -2,12 +2,14 @@ import type {
   SnippetCodeProps,
   SnippetContainerProps,
   SnippetRequestContainerProps,
-} from '@stainless-api/docs-ui/src/components';
-import { useHighlight, useLanguage } from '@stainless-api/docs-ui/src/contexts';
-import style from '@stainless-api/docs-ui/src/style';
+} from '@stainless-api/docs-ui/components';
+import { useHighlight, useLanguage } from '@stainless-api/docs-ui/contexts';
+import style from '@stainless-api/docs-ui/style';
 import * as cheerio from 'cheerio/slim';
 import { EXPERIMENTAL_COLLAPSIBLE_SNIPPETS } from 'virtual:stl-starlight-virtual-module';
 import clsx from 'clsx';
+import { Button } from '@stainless-api/ui-primitives';
+
 /*
  * This may be replaced by additional data from the sdk.
  * Without information from the sdk, we use simple heuristics per language.
@@ -53,7 +55,7 @@ function wrapFirstNSpaces($line: cheerio.Cheerio<any>, n: number) {
   const m = inner.match(new RegExp(`^( {1,${n}})`));
   if (!m) return;
 
-  const lead = m[1];
+  const lead = m[1]!;
   $firstSpan.html(`<span class="leading-ws">${lead}</span>${inner.slice(lead.length)}`);
 }
 
@@ -130,12 +132,14 @@ export function SnippetRequestContainer({ children, signature }: SnippetRequestC
     <div className="stl-snippet-request-container">
       {children}
       {signature && isCollapsible && (
-        <button
-          className={clsx(style.Button, style.ButtonSecondary, 'stl-snippet-expand-button')}
+        <Button
+          className={'stl-snippet-expand-button'}
           id="stl-snippet-expand-button"
+          size="sm"
+          variant="outline"
         >
           Show more
-        </button>
+        </Button>
       )}
     </div>
   );

package/plugin/components/search/SearchAlgolia.astro

@@ -1,30 +1,23 @@
 ---
 import { Icon } from '@astrojs/starlight/components';
 import { DocsSearch } from './SearchIsland';
-import { SEARCH } from 'virtual:stl-starlight-virtual-module';
-
-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';
-import '@stainless-api/docs-ui/src/styles/search.css';
-import '../../../components/variables.css';
+import { Button } from '@stainless-api/ui-primitives';
 ---
 
 <site-search>
-  <button
-    popovertarget="stldocs-search"
+  <Button
+    popoverTarget="stldocs-search"
     data-open-modal
     aria-label={Astro.locals.t('search.label')}
     aria-keyshortcuts="Control+K"
-    class="stldocs-button stldocs-button-secondary"
+    variant="outline"
   >
     <Icon name="magnifier" />
     <span class="sl-hidden md:sl-block" aria-hidden="true">{Astro.locals.t('search.label')}</span>
     <kbd class="sl-hidden md:sl-flex" style="display: none;">
       <kbd>{Astro.locals.t('search.ctrlKey')}</kbd><kbd>K</kbd>
     </kbd>
-  </button>
+  </Button>
 
   <DocsSearch
     client:only="react"
@@ -38,14 +31,6 @@ import '../../../components/variables.css';
   />
 </site-search>
 
-{
-  SEARCH?.enableAISearch === true && (
-    <button id="chat-button" popovertarget="stldocs-chat" data-open-modal>
-      <Icon name="comment" />
-    </button>
-  )
-}
-
 <style>
   #chat-button {
     background: var(--sl-color-bg-ui);

package/plugin/components/search/SearchIsland.tsx

@@ -1,19 +1,20 @@
 import * as React from 'react';
-import { BASE_PATH, SEARCH } from 'virtual:stl-starlight-virtual-module';
-import { parseRoute, generateRoute } from '@stainless-api/docs-ui/src/routing';
-import { SearchModal } from '@stainless-api/docs-ui/src/search/index';
-import { ChatModal } from '@stainless-api/docs-ui/src/components/chat';
+import { BASE_PATH, HIGHLIGHT_THEMES } from 'virtual:stl-starlight-virtual-module';
+import { parseRoute, generateRoute } from '@stainless-api/docs-ui/routing';
+import { SearchModal } from '@stainless-api/docs-ui/search';
 import * as Markdoc from '@markdoc/markdoc';
 import { createHighlighter } from 'shiki';
 import type { BundledLanguage, BundledTheme, HighlighterGeneric } from 'shiki';
 
 import {
   DocsProvider,
+  type MarkdownContext,
   MarkdownProvider,
   NavigationProvider,
   SearchProvider,
-} from '@stainless-api/docs-ui/src/contexts';
-import type { SearchSettings } from '@stainless-api/docs-ui/src/search/types';
+} from '@stainless-api/docs-ui/contexts';
+import { ComponentProvider } from '@stainless-api/docs-ui/contexts/component';
+import type { SearchSettings } from '@stainless-api/docs-ui/search/types';
 
 let $$highlighter: HighlighterGeneric<BundledLanguage, BundledTheme> | null = null;
 async function getHighlighter() {
@@ -27,7 +28,7 @@ async function getHighlighter() {
   return $$highlighter;
 }
 
-async function createMarkdownRenderer() {
+async function createMarkdownRenderer(): Promise<MarkdownContext> {
   const highlighter = await getHighlighter();
   const markdocConfig: Markdoc.Config = {
     nodes: {
@@ -66,16 +67,25 @@ async function createMarkdownRenderer() {
     },
   };
 
-  return (content: string) => {
-    const ast = Markdoc.parse(content);
-    const transformed = Markdoc.transform(ast, markdocConfig);
-    return Markdoc.renderers.html(transformed);
+  return {
+    render: (content: string) => {
+      const ast = Markdoc.parse(content);
+      const transformed = Markdoc.transform(ast, markdocConfig);
+      return Markdoc.renderers.html(transformed);
+    },
+    highlight: (content: string, language: string) => {
+      return highlighter.codeToHtml(content, {
+        lang: language ?? 'javascript',
+        themes: HIGHLIGHT_THEMES || {},
+      });
+    },
   };
 }
 
 export function DocsSearch({ settings, currentPath }: { settings: SearchSettings; currentPath: string }) {
-  const renderMarkdown = React.use(createMarkdownRenderer());
+  const markdownRenderer = React.use(createMarkdownRenderer());
   const { stainlessPath, language } = parseRoute(BASE_PATH, currentPath);
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
   const pageFind = import.meta.env.DEV ? undefined : '/pagefind/pagefind.js';
 
   function handleSelect(path: string) {
@@ -85,16 +95,17 @@ export function DocsSearch({ settings, currentPath }: { settings: SearchSettings
 
   return (
     <DocsProvider spec={null} language={language}>
-      <NavigationProvider basePath="/" selectedPath={stainlessPath}>
-        <MarkdownProvider render={renderMarkdown}>
-          <SearchProvider onSelect={handleSelect} pageFind={pageFind} settings={settings}>
-            <div className="stldocs-root">
-              <SearchModal id="stldocs-search" />
-              {SEARCH?.enableAISearch === true && <ChatModal id="stldocs-chat" />}
-            </div>
-          </SearchProvider>
-        </MarkdownProvider>
-      </NavigationProvider>
+      <ComponentProvider>
+        <NavigationProvider basePath="/" selectedPath={stainlessPath}>
+          <MarkdownProvider {...markdownRenderer}>
+            <SearchProvider onSelect={handleSelect} pageFind={pageFind} settings={settings}>
+              <div className="stldocs-root">
+                <SearchModal id="stldocs-search" />
+              </div>
+            </SearchProvider>
+          </MarkdownProvider>
+        </NavigationProvider>
+      </ComponentProvider>
     </DocsProvider>
   );
 }

package/plugin/generateAPIReferenceLink.ts

@@ -1,8 +1,8 @@
 // This is probably temporary, but it fills in functionality needed for Mintlify imports
 
 import type { StarlightRouteData } from '@astrojs/starlight/route-data';
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
-import { walkTree } from '@stainless-api/docs-ui/src/routing';
+import type * as SDKJSON from '@stainless/sdk-json';
+import { walkTree } from '@stainless-api/docs-ui/routing';
 
 const INTERNAL_REFERENCE_ENTRY_MARKER = 'STL_STARLIGHT_API_REFERENCE_METHOD_LINK_PLACEHOLDER';