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

package/styles/toc.css

@@ -1,7 +1,15 @@
 .right-sidebar-panel {
+  font-size: var(--stl-typography-scale-sm);
+  overflow-wrap: break-word;
+
+  nav {
+    width: calc(16 * var(--vw));
+    min-width: 14ch;
+  }
+
   nav > ul {
     padding-top: 0;
-    border-left: 1px solid var(--sl-color-hairline-light);
+    border-left: 1px solid var(--stl-color-border);
   }
 
   ul ul {
@@ -12,24 +20,26 @@
     --pad-inline: 1rem;
     font-weight: 400;
     padding-block: 0.32rem;
-    color: var(--sl-color-text-secondary);
+    color: var(--stl-color-foreground-reduced);
     position: relative;
+    font-size: inherit;
+    text-decoration: none;
 
     &:hover {
       text-decoration: underline;
-      color: var(--sl-color-text);
-      text-decoration-color: var(--sl-color-text-tertiary);
+      color: var(--stl-color-foreground);
+      text-decoration-color: var(--stl-color-foreground-reduced);
     }
 
     &[aria-current='true'] {
-      color: var(--sl-color-text-accent);
+      color: var(--stl-color-accent-foreground);
 
       &::after {
         content: '';
         position: absolute;
         height: 100%;
         width: 2px;
-        background-color: var(--sl-color-text-accent);
+        background-color: var(--stl-color-accent-border-strong);
         left: -1px;
         top: 0;
       }
@@ -37,10 +47,11 @@
   }
 
   h2 {
-    color: var(--stldocs-color-text-secondary);
-    font-size: var(--stldocs-font-size-small);
+    color: var(--stl-color-foreground-reduced);
+    font-size: inherit;
     line-height: 150%;
     text-decoration: none;
     font-weight: 400;
+    margin-bottom: 0.5em;
   }
 }

package/theme.css

@@ -1,8 +1,6 @@
 @layer starlight.base, starlight.reset, starlight.core, starlight.content, starlight.components, starlight.utils;
 @layer starlight;
 
-@import './styles/fonts.css';
-@import './styles/variables.css';
 @import './styles/links.css';
 @import './styles/sidebar.css';
 @import './styles/search.css';
@@ -11,13 +9,17 @@
 @import './styles/overrides.css';
 @import './styles/code.css';
 @import './styles/sdk_select.css';
+@import './styles/method-descriptions.css';
+
 @import '@stainless-api/ui-primitives/styles.css';
-@import './styles/mintlify-compat.css';
 
-@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 './styles/sl-variables.css';
+@import '@stainless-api/ui-primitives/styles/starlight-compat.css';
+@import './styles/mintlify-compat.css';
 
-@import './components/variables.css';
+@import './styles/stldocs-variables.css';
+@import '@stainless-api/docs-ui/styles/resets.css';
+@import '@stainless-api/docs-ui/styles/primitives.css';
+@import '@stainless-api/docs-ui/styles/main.css';
+@import '@stainless-api/docs-ui/styles/search.css';
+@import '@stainless-api/docs-ui/styles/sidebar.css';

package/tsconfig.json

@@ -7,11 +7,8 @@
     ".stl-docs/**/*",
     "./plugin/**/*"
   ],
-  "exclude": ["dist"],
+  "exclude": ["dist", "**/preview.worker.docs.js"],
   "compilerOptions": {
-    "paths": {
-      "~/*": ["../../../stainless/legacy-dir-root/*"]
-    },
     "jsx": "react-jsx",
     "jsxImportSource": "react"
   }

package/virtual-module.d.ts

@@ -1,12 +1,11 @@
 declare module 'virtual:stl-starlight-virtual-module' {
   import type { CreateShikiHighlighterOptions } from '@astrojs/markdown-remark';
-  import type { PropertySettingsType } from '@stainless-api/docs-ui/src/contexts';
+  import type { PropertySettingsType } from '@stainless-api/docs-ui/contexts';
   import type { StlStarlightMiddleware } from '@stainless-api/docs/plugin/MiddlewareTypes';
-  import type { StainlessStarlightUserConfig } from './plugin/loadPluginConfig';
+  import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
 
-  export const BASE_PATH: string;
-  export const CMS_PORT: number;
-  export const EXCLUDE_LANGUAGES: string[];
+  export const RESOLVED_API_REFERENCE_PATH: string;
+  export const EXCLUDE_LANGUAGES: DocsLanguage[];
   export const DEFAULT_LANGUAGE: string;
   export const BREADCRUMB_CONFIG: {
     includeCurrentPage?: boolean;
@@ -15,15 +14,21 @@ declare module 'virtual:stl-starlight-virtual-module' {
   export const HIGHLIGHT_THEMES: CreateShikiHighlighterOptions['themes'];
   export const CONTENT_PANEL_LAYOUT: 'double-pane' | 'single-pane';
   export const EXPERIMENTAL_COLLAPSIBLE_SNIPPETS: boolean | undefined;
+  export const EXPERIMENTAL_COLLAPSIBLE_METHOD_DESCRIPTIONS: boolean | undefined;
+  export const EXPERIMENTAL_PLAYGROUNDS: boolean | undefined;
+  export const EXPERIMENTAL_REQUEST_BUILDER: boolean | undefined;
   export const PROPERTY_SETTINGS: PropertySettingsType;
   export const MIDDLEWARE: StlStarlightMiddleware;
-  export const SEARCH: StainlessStarlightUserConfig['search'];
-  export const INCLUDE_AI_DROPDOWN_OPTIONS: boolean;
+  export const ENABLE_CONTEXT_MENU: boolean;
+  export const STAINLESS_PROJECT: string | undefined;
+  export const LLMS_TXT_DESCRIPTION: string | null;
+  export const LLMS_TXT_DETAIL_THRESHOLD: number;
 }
 
 declare module 'virtual:stl-docs-virtual-module' {
   import type { ButtonVariant } from '@stainless-api/ui-primitives';
   import type { AnchorHTMLAttributes } from 'react';
+  import { FontPreloadFilter } from 'astro:assets';
 
   type Tab = {
     label: string;
@@ -31,6 +36,11 @@ declare module 'virtual:stl-docs-virtual-module' {
     hidden?: boolean;
   };
 
+  type FontConfig = {
+    cssVariable: string;
+    preload?: FontPreloadFilter;
+  };
+
   export const HEADER_LINKS: {
     label: string;
     link: string;
@@ -41,5 +51,53 @@ declare module 'virtual:stl-docs-virtual-module' {
   export const SPLIT_TABS_ENABLED: boolean;
   export const HEADER_LAYOUT: 'default' | 'stacked';
   export const ENABLE_CLIENT_ROUTER: boolean;
-  export const INCLUDE_AI_DROPDOWN_OPTIONS: boolean;
+  export const API_REFERENCE_BASE_PATH: string;
+  export const ENABLE_PROSE_MARKDOWN_RENDERING: boolean;
+  export const ENABLE_CONTEXT_MENU: boolean;
+  export const RENDER_PAGE_DESCRIPTIONS: boolean;
+  export const LINK_GROUP_TITLES_TO_OVERVIEW_PAGES: boolean;
+  export const FONTS: {
+    primary?: FontConfig;
+    heading?: FontConfig;
+    mono?: FontConfig;
+    additional?: FontConfig[];
+  };
+  export const RENDER_CREDITS: boolean;
+  export const SITE_TITLE: string;
+  export const ENABLE_AI_CHAT: boolean;
 }
+
+declare module 'virtual:stl-docs-ai-chat-examples' {
+  import type { ExamplePrompt } from './stl-docs/chat/ui/types';
+
+  export const examples: ExamplePrompt[] | undefined;
+}
+
+declare module 'virtual:stainless-apis-manifest' {
+  import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
+
+  export type APIManifestEntry = {
+    languages: {
+      sdkJSONFilePath: string;
+      language: DocsLanguage;
+    }[];
+  };
+
+  export const api: APIManifestEntry;
+}
+
+declare module 'virtual:stl-starlight-reference-sidebars' {
+  import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
+  import type { StarlightRouteData } from '@astrojs/starlight/route-data';
+
+  export type GeneratedSidebarDef = {
+    id: number;
+    language: DocsLanguage;
+    entries: StarlightRouteData['sidebar'];
+  };
+
+  export const sidebars: GeneratedSidebarDef[];
+}
+
+declare const __STLDOCS_HAS_API_REFERENCE__: boolean;
+declare const __STLDOCS_ENABLE_AI_CHAT__: boolean;

package/components/variables.css

@@ -1,112 +0,0 @@
-:root {
-  --stldocs-font: var(--sl-font, system-ui, sans-serif);
-  --stldocs-font-mono: var(--sl-font-mono, ui-monospace, monospace);
-
-  --stldocs-color-white: var(--sl-color-white);
-  --stldocs-color-gray-1: var(--sl-color-gray-1);
-  --stldocs-color-gray-2: var(--sl-color-gray-2);
-  --stldocs-color-gray-3: var(--sl-color-gray-3);
-  --stldocs-color-gray-4: var(--sl-color-gray-4);
-  --stldocs-color-gray-5: var(--sl-color-gray-5);
-  --stldocs-color-gray-6: var(--sl-color-gray-6);
-  --stldocs-color-gray-7: var(--sl-color-gray-7);
-  --stldocs-color-gray-8: var(--sl-color-gray-8);
-
-  --stldocs-color-accent-low: var(--sl-color-accent-low);
-  --stldocs-color-accent-high: var(--sl-color-accent-high);
-  --stldocs-color-accent: var(--sl-color-accent);
-  --stldocs-color-red: var(--sl-color-red);
-
-  --stldocs-color-text: var(--sl-color-text);
-  --stldocs-color-text-accent: var(--sl-color-text-accent);
-  --stldocs-color-text-invert: var(--sl-color-text-invert);
-  --stldocs-color-text-secondary: var(--sl-color-text-secondary);
-  --stldocs-color-text-tertiary: var(--sl-color-text-tertiary);
-
-  --stldocs-color-bg: var(--sl-color-bg);
-  --stldocs-color-bg-nav: var(--sl-color-bg-nav);
-  --stldocs-color-bg-ui: var(--sl-color-bg-ui);
-
-  --stldocs-color-bg-inline-code: var(--sl-color-bg-inline-code);
-  --stldocs-color-bg-accent: var(--sl-color-bg-accent);
-  --stldocs-color-hairline: var(--sl-color-hairline);
-  --stldocs-color-hairline-shade: var(--sl-color-hairline-shade);
-  --stldocs-color-hairline-light: var(--sl-color-hairline-light);
-
-  --stldocs-badge-default-text: var(--sl-badge-default-text);
-  --stldocs-color-bg-inline-code-dark: var(--sl-color-bg-inline-code-dark);
-
-  --stldocs-font-size-h1: var(--sl-text-h1);
-  --stldocs-font-size-h2: var(--sl-text-h2);
-  --stldocs-font-size-h3: var(--sl-text-h3);
-  --stldocs-font-size-h4: var(--sl-text-h4);
-  --stldocs-font-size-h5: var(--sl-text-h5);
-
-  --stlodcs-font-size-body: var(--sl-text-body);
-  --stldocs-font-size-small: var(--sl-text-body-sm);
-  --stldocs-font-size-code: var(--sl-text-code);
-
-  --stldocs-content-width: var(--sl-content-width);
-  --stldocs-content-padding: var(--sl-content-pad-x);
-
-  --stldocs-color-http-get-bg: var(--sl-color-green-low);
-  --stldocs-color-http-get: var(--sl-color-green);
-  --stldocs-color-http-put-bg: var(--sl-color-orange-low);
-  --stldocs-color-http-put: var(--sl-color-orange);
-  --stldocs-color-http-post-bg: var(--sl-color-blue-low);
-  --stldocs-color-http-post: var(--sl-color-blue);
-  --stldocs-color-http-delete-bg: var(--sl-color-red-low);
-  --stldocs-color-http-delete: var(--sl-color-red);
-
-  --stldocs-syntax-color-red: var(--sl-color-red);
-  --stldocs-syntax-color-green: var(--sl-color-green);
-  --stldocs-syntax-color-blue: var(--sl-color-blue);
-  --stldocs-syntax-color-orange: var(--sl-color-orange);
-  --stldocs-syntax-color-teal: var(--sl-color-teal);
-  --stldocs-syntax-color-magenta: var(--sl-color-magenta);
-  --stldocs-syntax-color-purple: var(--sl-color-purple);
-
-  --stldocs-color-backdrop-overlay: var(--sl-color-backdrop-overlay);
-  --stldocs-expander-margin-shift: 24px;
-  --stldocs-expander-right-margin: 8px;
-  --stldocs-font-size-body: 14px;
-  --stldocs-font-size-body-xs: 12px;
-}
-
-/* These are the theme overrides - we need to come up with a good way to do this in starlight */
-:root {
-  /*
-  tmp remove the theme color in favor of the Shiki default theme background
-  commented out values are the original values in case we want them again
-  */
-  /* --stldocs-color-snippet-box-bg: #272727; */
-  --stldocs-color-snippet-box-bg: #1f1f1f;
-  /* --stldocs-color-snippet-title-bg: #161616; */
-  --stldocs-color-snippet-title-bg: #24292f;
-  --stldocs-color-snippet-title-muted: #8b8b8b;
-  --stldocs-color-snippet-title-bright: #ffffff;
-  --stldocs-color-snippet-code-bg: #1d1d1d;
-
-  --stldocs-title-padding-y: 2.5rem;
-
-  --stldocs-z-index-theme-select: 1000;
-  --stldocs-button-border-radius: var(--sl-button-border-radius);
-  --stldocs-button-size: var(--sl-button-size);
-  --stldocs-button-padding-x: var(--sl-button-padding-x);
-  --stldocs-button-padding-y: var(--sl-button-padding-y);
-
-  --sl-content-pad-x: 1rem;
-}
-
-:root[data-theme='light'] {
-  --stldocs-color-snippet-box-bg: #eeeeee;
-  /*
-  tmp remove the theme color in favor of the Shiki default theme background
-  commented out value is the original value in case we want it again
-  */
-  /* --stldocs-color-snippet-title-bg: #2a2a2a; */
-  --stldocs-color-snippet-title-bg: #24292f;
-  --stldocs-color-snippet-title-muted: #959595;
-  --stldocs-color-snippet-title-bright: #000;
-  --stldocs-color-snippet-code-bg: #383838;
-}

package/plugin/cms/client.ts

@@ -1,62 +0,0 @@
-import { CMS_PORT } from 'virtual:stl-starlight-virtual-module';
-import type { SpecResp } from './server';
-import type { StarlightRouteData } from '@astrojs/starlight/route-data';
-import type { BuildSidebarParams } from './sidebar-builder';
-
-const SERVER_URL = `http://localhost:${CMS_PORT}`;
-
-async function makeRequest<T>(method: 'POST' | 'GET', endpoint: string, body?: any) {
-  const response = await fetch(`${SERVER_URL}${endpoint}`, {
-    method,
-    headers: {
-      'Content-Type': 'application/json',
-    },
-    body: body ? JSON.stringify(body) : undefined,
-  });
-  return response.json() as T;
-}
-
-class Client {
-  private specCache: SpecResp | null = null;
-  private clientId: string;
-
-  get id() {
-    return this.clientId;
-  }
-
-  async buildSidebar(params: BuildSidebarParams & { sidebarId: number }) {
-    const response = await makeRequest<{ data: StarlightRouteData['sidebar'] }>(
-      'POST',
-      '/build_sidebar',
-      params,
-    );
-    return response.data;
-  }
-
-  async getSpec() {
-    const cached = this.specCache;
-
-    const response = await makeRequest<SpecResp>('POST', '/retrieve_spec', {
-      currentId: cached?.id,
-    });
-
-    if (response.data === null) {
-      if (!cached) {
-        throw new Error('Cache should not be null');
-      }
-      if (cached.data === null) {
-        throw new Error('Cached spec should not be null');
-      }
-      return cached.data;
-    }
-    // console.log("invalidating spec cache", this.clientId);
-    this.specCache = response;
-    return response.data;
-  }
-
-  constructor() {
-    this.clientId = crypto.randomUUID();
-  }
-}
-
-export const cmsClient = new Client();

package/plugin/cms/server.ts

@@ -1,268 +0,0 @@
-import { createServer, IncomingMessage } from 'http';
-import { readFile } from 'fs/promises';
-
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
-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 {
-  toStarlightSidebar,
-  type GeneratedSidebarConfig,
-  SidebarConfigItemsBuilder,
-} from './sidebar-builder';
-import type { VersionUserConfig } from '../loadPluginConfig';
-
-export type InputFilePaths = {
-  oasPath?: string;
-  configPath?: string;
-};
-
-async function versionInfo(project: string, apiKey: 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);
-}
-
-async function loadSpec({
-  apiKey,
-  devPaths,
-  version,
-}: {
-  apiKey: string;
-  devPaths: InputFilePaths;
-  version: VersionUserConfig;
-}) {
-  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);
-
-    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 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 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;
-    }
-  }
-
-  const id = crypto.randomUUID();
-
-  return {
-    data: sdkJson,
-    id,
-  };
-}
-
-class Spec {
-  private specPromise: Promise<{ id: string; data: SDKJSON.Spec }>;
-  private devPaths: InputFilePaths;
-  private apiKey: string;
-  private version: VersionUserConfig;
-
-  reload() {
-    this.specPromise = loadSpec({
-      apiKey: this.apiKey,
-      devPaths: this.devPaths,
-      version: this.version,
-    });
-  }
-
-  async forceGetSpec() {
-    const spec = await this.specPromise;
-    return spec;
-  }
-
-  async getSpec(currentId: string | undefined | null) {
-    const spec = await this.specPromise;
-
-    if (currentId === spec.id) {
-      return {
-        id: spec.id,
-        data: null,
-      };
-    }
-
-    return spec;
-  }
-
-  constructor(apiKey: string, version: VersionUserConfig, devPaths: InputFilePaths) {
-    this.specPromise = loadSpec({
-      apiKey,
-      devPaths,
-      version,
-    });
-    this.devPaths = devPaths;
-    this.apiKey = apiKey;
-    this.version = version;
-  }
-}
-
-export type SpecResp = Awaited<ReturnType<Spec['getSpec']>>;
-
-// will be necessary once we add POST methods
-function readJsonBody(req: IncomingMessage): Promise<any> {
-  return new Promise((resolve, reject) => {
-    let body = '';
-    req.on('data', (chunk) => {
-      body += chunk.toString();
-    });
-    req.on('end', () => {
-      try {
-        const data = JSON.parse(body);
-        resolve(data);
-      } catch (error) {
-        reject(error);
-      }
-    });
-  });
-}
-
-export function startDevServer({
-  port,
-  version,
-  devPaths,
-  apiKey,
-  getGeneratedSidebarConfig,
-}: {
-  port: number;
-  version: VersionUserConfig;
-  devPaths: InputFilePaths;
-  apiKey: string;
-  getGeneratedSidebarConfig: (id: number) => GeneratedSidebarConfig | null;
-}) {
-  const spec = new Spec(apiKey, version, devPaths);
-
-  const server = createServer(async (req, res) => {
-    // Add CORS headers
-    res.setHeader('Access-Control-Allow-Origin', '*');
-    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
-    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
-
-    // Handle preflight requests
-    if (req.method === 'OPTIONS') {
-      res.writeHead(204);
-      res.end();
-      return;
-    }
-
-    function respond(code: number, body: any) {
-      res.setHeader('Content-Type', 'application/json');
-      res.writeHead(code);
-      res.end(JSON.stringify(body));
-    }
-
-    try {
-      if (req.method === 'POST' && req.url === '/retrieve_spec') {
-        const body = await readJsonBody(req);
-
-        const currentSpec = await spec.getSpec(body.currentId);
-
-        return respond(200, currentSpec);
-      }
-
-      if (req.method === 'POST' && req.url === '/build_sidebar') {
-        const currentSpec = await spec.forceGetSpec();
-        const body = await readJsonBody(req);
-        const sidebarId: number = body.sidebarId;
-
-        const sidebarConfig = getGeneratedSidebarConfig(sidebarId);
-
-        const sidebarGenerateOptions = sidebarConfig?.options;
-
-        const { stainlessPath: currentStainlessPath, language } = parseRoute(body.basePath, body.currentSlug);
-
-        const configItemsBuilder = new SidebarConfigItemsBuilder(
-          currentSpec.data,
-          language,
-          sidebarGenerateOptions,
-        );
-
-        let userSidebarConfig = configItemsBuilder.generateItems();
-
-        if (sidebarConfig && sidebarConfig.transformFn) {
-          const transformedSidebarConfig = sidebarConfig.transformFn(userSidebarConfig, language);
-          // the user may not have returned, but they may have mutated the config in place
-          // if they did return, we use that
-          if (transformedSidebarConfig) {
-            userSidebarConfig = transformedSidebarConfig;
-          }
-        }
-
-        const starlightSidebar = toStarlightSidebar({
-          basePath: body.basePath,
-          currentSlug: body.currentSlug,
-          spec: currentSpec.data,
-          entries: userSidebarConfig,
-          currentStainlessPath,
-          currentLanguage: language,
-        });
-
-        return respond(200, { data: starlightSidebar });
-      }
-
-      return respond(404, { message: 'Not found' });
-    } catch (e) {
-      return respond(500, { message: 'Unexpected error', error: e });
-    }
-  });
-
-  server.listen(port, () => {
-    console.log(`Server is running on port ${port}`);
-  });
-
-  return {
-    invalidate: () => {
-      spec.reload();
-    },
-    destroy: function destroy() {
-      return new Promise<void>((resolve) => {
-        server.close(() => {
-          resolve();
-        });
-      });
-    },
-  };
-}