@stainless-api/docs 0.1.0-beta.15 → 0.1.0-beta.16

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @stainless-api/docs
 
+## 0.1.0-beta.16
+
+### Patch Changes
+
+- 0618d05: Markdown rendering of prose pages, ai context menu, auth via cli, minor fixes
+- Updated dependencies [0618d05]
+  - @stainless-api/docs-ui@0.1.0-beta.13
+  - @stainless-api/ui-primitives@0.1.0-beta.14
+
 ## 0.1.0-beta.15
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "0.1.0-beta.15",
+  "version": "0.1.0-beta.16",
   "publishConfig": {
     "access": "public"
   },
@@ -9,23 +9,9 @@
   "exports": {
     ".": "./stl-docs/index.ts",
     "./plugin": "./plugin/index.ts",
-    "./OverviewRoute": "./plugin/routes/Overview.astro",
-    "./DocsRoute": "./plugin/routes/Docs.astro",
-    "./DocsStaticRoute": "./plugin/routes/DocsStatic.astro",
-    "./MarkdownRoute": "./plugin/routes/markdown.ts",
-    "./Search": "./plugin/components/search/Search.astro",
-    "./replaceSidebarPlaceholderMiddleware": "./plugin/replaceSidebarPlaceholderMiddleware.ts",
     "./plugin/middleware": "./plugin/middlewareBuilder/stlStarlightMiddleware.ts",
     "./plugin/MiddlewareTypes": "./plugin/middlewareBuilder/stainlessMiddleware.d.ts",
-    "./Header": "./stl-docs/components/Header.astro",
-    "./ThemeSelect": "./stl-docs/components/ThemeSelect.astro",
-    "./BaseSidebar": "./stl-docs/components/sidebars/BaseSidebar.astro",
-    "./SDKSelectSidebar": "./stl-docs/components/sidebars/SDKSelectSidebar.astro",
-    "./ContentPanel": "./stl-docs/components/content-panel/ContentPanel.astro",
-    "./TableOfContents": "./stl-docs/components/TableOfContents.astro",
-    "./tabsMiddleware": "./stl-docs/tabsMiddleware.ts",
     "./stainless-docs/mintlify-compat": "./stl-docs/components/mintlify-compat/index.ts",
-    "./theme": "./theme.css",
     "./mintlify-compat.css": "./styles/mintlify-compat.css",
     "./font-imports": "./styles/fonts.css",
     "./components": "./stl-docs/components/index.ts"
@@ -57,8 +43,14 @@
     "shiki": "^3.9.2",
     "web-worker": "^1.5.0",
     "yaml": "^2.8.0",
-    "@stainless-api/ui-primitives": "0.1.0-beta.13",
-    "@stainless-api/docs-ui": "0.1.0-beta.12"
+    "node-html-parser": "^7.0.1",
+    "rehype-parse": "^9.0.1",
+    "rehype-remark": "^10.0.1",
+    "remark-gfm": "^4.0.1",
+    "remark-stringify": "^11.0.0",
+    "unified": "^11.0.5",
+    "@stainless-api/docs-ui": "0.1.0-beta.13",
+    "@stainless-api/ui-primitives": "0.1.0-beta.14"
   },
   "devDependencies": {
     "@markdoc/markdoc": "^0.5.2",

package/plugin/buildAlgoliaIndex.ts

@@ -5,6 +5,7 @@ import type * as SDKJSON from '~/lib/json-spec-v2/types';
 import { Languages } from '@stainless-api/docs-ui/src/routing';
 import { buildIndex } from '@stainless-api/docs-ui/src/search/providers/algolia';
 import type { VersionUserConfig } from './loadPluginConfig';
+import type { AstroIntegrationLogger } from 'astro';
 
 const markdocConfig = {
   nodes: {
@@ -20,7 +21,31 @@ function renderMarkdown(content?: string) {
   return Markdoc.renderers.html(transformed);
 }
 
-export async function buildAlgoliaIndex({ version, apiKey }: { version: VersionUserConfig; apiKey: string }) {
+export async function buildAlgoliaIndex({
+  version,
+  apiKey,
+  logger,
+}: {
+  version: VersionUserConfig;
+  apiKey: string;
+  logger?: AstroIntegrationLogger;
+}) {
+  function warnLog(message: string) {
+    if (logger) {
+      logger.warn(message);
+    } else {
+      console.warn(message);
+    }
+  }
+
+  function infoLog(message: string) {
+    if (logger) {
+      logger.info(message);
+    } else {
+      console.log(message);
+    }
+  }
+
   const client = new Stainless({ apiKey });
   const configs = await client.projects.configs.retrieve({
     project: version.stainlessProject,
@@ -64,9 +89,9 @@ export async function buildAlgoliaIndex({ version, apiKey }: { version: VersionU
       !indexName && 'PUBLIC_ALGOLIA_INDEX',
       !algoliaWriteKey && 'PRIVATE_ALGOLIA_WRITE_KEY',
     ].filter(Boolean);
-    console.warn(`⚠️ Skipping Algolia indexing due to missing environment variables: ${missing.join(', ')}`);
+    warnLog(`Skipping Algolia indexing due to missing environment variables: ${missing.join(', ')}`);
     return;
   }
   await buildIndex(appId, indexName, algoliaWriteKey, sdkJson, renderMarkdown);
-  console.log('Indexing complete.');
+  infoLog('Indexing complete.');
 }

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 { createSDKJSON, parseInputs, transformOAS } from './worker';
 import { Languages, parseRoute, type DocsLanguage } from '@stainless-api/docs-ui/src/routing';
-import Stainless from '@stainless-api/sdk';
+import Stainless, { APIError } from '@stainless-api/sdk';
 
 import {
   toStarlightSidebar,
@@ -12,6 +13,7 @@ import {
   SidebarConfigItemsBuilder,
 } from './sidebar-builder';
 import type { VersionUserConfig } from '../loadPluginConfig';
+import { bold } from '../../shared/terminalUtils';
 
 export type InputFilePaths = {
   oasPath?: string;
@@ -24,76 +26,105 @@ async function versionInfo(project: string, apiKey: string) {
   });
 
   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

@@ -208,13 +208,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 +221,6 @@ export class SidebarConfigItemsBuilder {
         methodPages.push(this.toMethodPage(m, langDecl));
       }
     }
-    this.sortByLabel(methodPages);
     entries.push(...methodPages);
 
     const subresources = Object.values(resource.subresources ?? {});
@@ -238,7 +230,6 @@ export class SidebarConfigItemsBuilder {
         subresourceGroups.push(this.generateResourceGroup(sub, true));
       }
     }
-    this.sortByLabel(subresourceGroups);
     entries.push(...subresourceGroups);
 
     return {

package/plugin/globalJs/ai-dropdown-options.ts

@@ -0,0 +1,161 @@
+import { initDropdownButton } from '@stainless-api/ui-primitives/scripts';
+import { getPageLoadEvent } from '../helpers/getPageLoadEvent';
+
+export type DropdownIcon = 'markdown' | 'copy' | 'claude' | 'chatgpt';
+
+interface DropdownOptionInputProps {
+  onClick: () => void;
+  icon: DropdownIcon;
+  primaryAction?: boolean;
+  label: string[] | string;
+}
+
+function getMarkdownUrl(type: 'relative' | 'absolute') {
+  const currentUrl = new URL(window.location.href);
+  const hasTrailingSlash = currentUrl.pathname.endsWith('/');
+
+  const markdownUrl = [
+    type === 'absolute' ? currentUrl.origin : '',
+    currentUrl.pathname,
+    hasTrailingSlash ? '' : '/',
+    'index.md',
+  ].join('');
+
+  return markdownUrl;
+}
+
+function openInLLM(serviceUrl: string) {
+  const mdUrl = getMarkdownUrl('absolute');
+  const prompt = encodeURIComponent(
+    `Load the contents of ${mdUrl} into this chat's context so we can discuss it.`,
+  );
+  window.open(`${serviceUrl}${prompt}`, '_blank');
+}
+
+// 2d array of dropdown options
+// each sub-array is a group, separated by a horizontal rule in the UI
+const aiDropdownOptions: DropdownOptionInputProps[][] = [
+  [
+    {
+      label: 'View as Markdown',
+      onClick: () => {
+        window.open(getMarkdownUrl('absolute'), '_blank');
+      },
+      icon: 'markdown',
+      primaryAction: true,
+    },
+    {
+      label: 'Copy Markdown',
+      onClick: () => {
+        // Source: https://wolfgangrittner.dev/how-to-use-clipboard-api-in-firefox/
+        const markdownUrl = getMarkdownUrl('relative');
+        // ClipboardItem doesn't exist in every browser
+        // eslint-disable-next-line no-constant-binary-expression
+        if (typeof ClipboardItem && navigator.clipboard.write) {
+          // NOTE: Safari locks down the clipboard API to only work when triggered
+          //   by a direct user interaction. You can't use it async in a promise.
+          //   But! You can wrap the promise in a ClipboardItem, and give that to
+          //   the clipboard API.
+          //   Found this on https://developer.apple.com/forums/thread/691873
+          const text = new ClipboardItem({
+            'text/plain': fetch(markdownUrl)
+              .then((response) => response.text())
+              .then((text) => new Blob([text], { type: 'text/plain' })),
+          });
+          navigator.clipboard.write([text]);
+        } else {
+          // NOTE: Firefox has support for ClipboardItem and navigator.clipboard.write,
+          //   but those are behind `dom.events.asyncClipboard.clipboardItem` preference.
+          //   Good news is that other than Safari, Firefox does not care about
+          //   Clipboard API being used async in a Promise.
+          fetch(markdownUrl)
+            .then((response) => response.text())
+            .then((text) => navigator.clipboard.writeText(text));
+        }
+      },
+      icon: 'copy',
+      primaryAction: false,
+    },
+  ],
+  [
+    {
+      label: ['Open in ', 'Claude'],
+      onClick: () => {
+        openInLLM('https://claude.ai/new?q=');
+      },
+      icon: 'claude',
+      primaryAction: false,
+    },
+    {
+      label: ['Open in ', 'ChatGPT'],
+      onClick: () => {
+        openInLLM('https://chatgpt.com/?hints=search&prompt=');
+      },
+      icon: 'chatgpt',
+      primaryAction: false,
+    },
+    // TODO: Add Cursor support
+    // {
+    //   label: ['Open in ', 'Cursor'],
+    //   onClick: () => {
+    //     openInLLM('https://www.cursor.so/?prompt=');
+    //   },
+    //   icon: 'cursor',
+    //   primaryAction: false,
+    // }
+  ],
+];
+
+function renderGroup(group: DropdownOptionInputProps[]) {
+  return group.map((option) => {
+    const label = typeof option.label === 'string' ? [option.label] : option.label;
+    return {
+      ...option,
+      label: label,
+      primaryAction: option.primaryAction ?? false,
+      id: label.join('').toLowerCase().replace(/ /g, '-'),
+    };
+  });
+}
+
+export function getAIDropdownOptions() {
+  const renderedOptions = aiDropdownOptions.map((group, index) => {
+    return {
+      options: renderGroup(group),
+      isLast: index === aiDropdownOptions.length - 1,
+      reactKey: index,
+    };
+  });
+
+  const allOptions = renderedOptions.flatMap((group) => group.options);
+  const primaryAction = allOptions.find((o) => o.primaryAction) ?? allOptions[0]!;
+
+  return {
+    primaryAction,
+    groups: renderedOptions,
+  };
+}
+
+export function wireAIDropdown() {
+  const { primaryAction, groups } = getAIDropdownOptions();
+  function triggerOption(id: string) {
+    const option = groups.flatMap((group) => group.options).find((option) => option.id === id);
+    if (!option) return;
+    option.onClick();
+  }
+
+  document.addEventListener(getPageLoadEvent(), () => {
+    const dropdowns = document.querySelectorAll('[data-dropdown-id]');
+    dropdowns.forEach((dropdown) => {
+      initDropdownButton({
+        dropdown: dropdown,
+        onSelect: (value) => {
+          triggerOption(value);
+        },
+        onPrimaryAction: () => {
+          triggerOption(primaryAction.id);
+        },
+      });
+    });
+  });
+}

package/plugin/globalJs/navigation.ts

@@ -5,8 +5,6 @@ import { navigate } from 'astro:transitions/client';
 import { getPageLoadEvent } from '../helpers/getPageLoadEvent.ts';
 
 import { initDropdown } from '@stainless-api/docs-ui/src/components/scripts/dropdown';
-import { initDropdownButton } from '@stainless-api/ui-primitives/scripts';
-import { copyCurrentPageAsMarkdown, onSelectAIOption } from './ai-dropdown.ts';
 
 history.scrollRestoration = 'auto';
 
@@ -36,26 +34,6 @@ document.addEventListener(getPageLoadEvent(), () => {
   if (path) setTimeout(() => scrollToPath(path.slice(1)), 10);
 });
 
-document.addEventListener(getPageLoadEvent(), () => {
-  initDropdownButton({
-    dropdownId: 'ai-dropdown-button',
-    onSelect: onSelectAIOption,
-    onPrimaryAction: (el) => {
-      copyCurrentPageAsMarkdown();
-      const innerText = el.querySelector('[data-part="primary-action-text"]');
-      if (!innerText) return;
-
-      const originalInnerHtml = innerText.innerHTML;
-      innerText.innerHTML = 'Copied!';
-      el.classList.add('disabled');
-      setTimeout(() => {
-        innerText.innerHTML = originalInnerHtml;
-        el.classList.remove('disabled');
-      }, 1000);
-    },
-  });
-});
-
 document.addEventListener('click', (event) => {
   const toggle = (event.target as HTMLElement).closest(
     '[data-stldocs-property-toggle-expanded] > .stldocs-expand-toggle-content',