@stainless-api/docs 0.1.0-beta.135 → 0.1.0-beta.137

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @stainless-api/docs
 
+## 0.1.0-beta.137
+
+### Minor Changes
+
+- ce2dd81: Add interface for customizing ai-chat behaviour
+
+### Patch Changes
+
+- 5f0fdda: Vendor dependencies for Stainless Config change
+- 680889d: feat: support disabling third-party context menu options
+
+## 0.1.0-beta.136
+
+### Minor Changes
+
+- 5a6e598: [og image] migrate Takumi to v1
+
+### Patch Changes
+
+- 8b7aaff: Adds markdown representation for overview
+- 23bd8f7: Update preview worker
+
 ## 0.1.0-beta.135
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "0.1.0-beta.135",
+  "version": "0.1.0-beta.137",
   "publishConfig": {
     "access": "public"
   },
@@ -28,7 +28,8 @@
     "./components/Pagination": "./stl-docs/components/pagination/Pagination.astro",
     "./og-image/components/OpenGraphImage": "./stl-docs/og-image/components/OpenGraphImage.tsx",
     "./og-image/components/OpenGraphFunctionSignature": "./stl-docs/og-image/components/OpenGraphFunctionSignature.tsx",
-    "./schema-extension": "./stl-docs/schema-extension.ts"
+    "./schema-extension": "./stl-docs/schema-extension.ts",
+    "./chat": "./stl-docs/chat/docs-chat-handler.ts"
   },
   "keywords": [],
   "author": "",
@@ -38,27 +39,26 @@
   },
   "peerDependencies": {
     "@astrojs/starlight": ">=0.38.0",
-    "@takumi-rs/image-response": ">=0.66.6",
+    "takumi-js": ">=1.0.5",
     "astro": ">=6.0.0",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0",
     "vite": ">=7.3.1"
   },
   "peerDependenciesMeta": {
-    "@takumi-rs/image-response": {
+    "takumi-js": {
       "optional": true
     }
   },
   "dependencies": {
-    "@astrojs/markdown-remark": "^7.1.0",
-    "@astrojs/react": "^5.0.3",
+    "@astrojs/markdown-remark": "^7.1.1",
+    "@astrojs/react": "^5.0.4",
     "@markdoc/markdoc": "^0.5.7",
     "@stainless-api/sdk": "0.5.0",
-    "@streamparser/json-whatwg": "^0.0.22",
     "cheerio": "^1.2.0",
     "clsx": "^2.1.1",
-    "dotenv": "17.4.1",
-    "lucide-react": "^0.577.0",
+    "dotenv": "17.4.2",
+    "lucide-react": "^1.14.0",
     "motion": "^12.38.0",
     "node-html-parser": "^7.1.0",
     "rehype-parse": "^9.0.1",
@@ -72,24 +72,24 @@
     "shiki": "^4.0.2",
     "unified": "^11.0.5",
     "web-worker": "^1.5.0",
-    "@stainless-api/docs-search": "0.1.0-beta.48",
     "@stainless-api/docs-ui": "0.1.0-beta.95",
-    "@stainless-api/ui-primitives": "0.1.0-beta.53"
+    "@stainless-api/ui-primitives": "0.1.0-beta.53",
+    "@stainless-api/docs-search": "0.1.0-beta.48"
   },
   "devDependencies": {
-    "@astrojs/check": "^0.9.8",
-    "@takumi-rs/image-response": "^0.73.1",
+    "@astrojs/check": "^0.9.9",
+    "takumi-js": "^1.1.2",
     "@types/node": "24.12.2",
     "@types/react": "19.2.14",
     "@types/react-dom": "^19.2.3",
     "@types/react-syntax-highlighter": "^15.5.13",
-    "astro": "^6.1.5",
+    "astro": "^6.2.1",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
-    "typescript": "6.0.2",
+    "typescript": "6.0.3",
     "vite": "^7.3.2",
-    "vitest": "^4.1.4",
-    "zod": "^4.3.6",
+    "vitest": "^4.1.5",
+    "zod": "^4.4.2",
     "@stainless/eslint-config": "0.1.0-beta.2",
     "@stainless/sdk-json": "^0.1.0-beta.10"
   },

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

@@ -1,5 +1,6 @@
 import { initDropdownButton } from '@stainless-api/ui-primitives/scripts';
 import { getPageLoadEvent } from '../helpers/getPageLoadEvent';
+import { CONTEXT_MENU_ENABLE_THIRD_PARTY } from 'virtual:stl-docs-virtual-module';
 
 export type DropdownIcon = 'markdown' | 'copy' | 'claude' | 'chatgpt' | 'gemini' | 'cursor';
 
@@ -9,6 +10,7 @@ interface DropdownOptionInputProps {
   primaryAction?: boolean;
   clientHidden?: () => boolean;
   external: boolean;
+  thirdParty?: boolean;
 }
 
 function option(label: string[] | string, props: DropdownOptionInputProps) {
@@ -101,6 +103,7 @@ const aiDropdownOptions: DropdownOption[][] = [
       icon: 'claude',
       primaryAction: false,
       external: true,
+      thirdParty: true,
     }),
     option(['Open in ', 'ChatGPT'], {
       onClick: () => {
@@ -109,6 +112,7 @@ const aiDropdownOptions: DropdownOption[][] = [
       icon: 'chatgpt',
       primaryAction: false,
       external: true,
+      thirdParty: true,
     }),
     option(['Open in ', 'Cursor'], {
       onClick: () => {
@@ -122,6 +126,7 @@ const aiDropdownOptions: DropdownOption[][] = [
       icon: 'cursor',
       primaryAction: false,
       external: true,
+      thirdParty: true,
     }),
   ],
   [
@@ -184,13 +189,16 @@ const aiDropdownOptions: DropdownOption[][] = [
 // },
 
 export function getAIDropdownOptions() {
-  const renderedOptions = aiDropdownOptions.map((group, index) => {
-    return {
-      options: group,
-      isLast: index === aiDropdownOptions.length - 1,
-      reactKey: index,
-    };
-  });
+  const renderedOptions = aiDropdownOptions
+    .map((e) => e.filter((e) => CONTEXT_MENU_ENABLE_THIRD_PARTY || !e.thirdParty))
+    .filter((e) => e.length)
+    .map((group, index, array) => {
+      return {
+        options: group,
+        isLast: index === array.length - 1,
+        reactKey: index,
+      };
+    });
 
   const allOptions = renderedOptions.flatMap((group) => group.options);
   const primaryAction = allOptions.find((o) => o.primaryAction) ?? allOptions[0]!;

package/plugin/index.ts

@@ -135,6 +135,12 @@ function stlStarlightAstroIntegration(pluginConfig: NormalizedStainlessStarlight
           prerender: pluginConfig.experimentalPrerender ? command === 'build' : false,
         });
 
+        injectRoute({
+          pattern: `${pluginConfig.basePath}/index.md`,
+          entrypoint: resolveSrcFile('/plugin/routes/markdown.ts'),
+          prerender: pluginConfig.experimentalPrerender ? command === 'build' : false,
+        });
+
         const astroFile = command === 'build' ? 'DocsStatic' : 'Docs';
         injectRoute({
           pattern: `${pluginConfig.basePath}/[...slug]`,
@@ -234,7 +240,11 @@ function stlStarlightAstroIntegration(pluginConfig: NormalizedStainlessStarlight
                         EXPERIMENTAL_COLLAPSIBLE_METHOD_DESCRIPTIONS:
                           pluginConfig.experimentalCollapsibleMethodDescriptions,
                         PROPERTY_SETTINGS: pluginConfig.propertySettings,
-                        ENABLE_CONTEXT_MENU: pluginConfig.contextMenu,
+                        ENABLE_CONTEXT_MENU: !!pluginConfig.contextMenu,
+                        CONTEXT_MENU_ENABLE_THIRD_PARTY:
+                          (typeof pluginConfig.contextMenu === 'object'
+                            ? pluginConfig.contextMenu.thirdParty
+                            : null) ?? true,
                         EXPERIMENTAL_REQUEST_BUILDER: pluginConfig.experimentalRequestBuilder,
                         STAINLESS_PROJECT: pluginConfig.stainlessProject,
                         LLMS_TXT_DESCRIPTION: pluginConfig.llmsTxt.description,

package/plugin/loadPluginConfig.ts

@@ -149,7 +149,7 @@ export type StainlessStarlightUserConfig = {
    * @default true
    */
 
-  contextMenu?: boolean;
+  contextMenu?: boolean | { thirdParty?: boolean };
 
   /** When set to true, enables the experimental request builder interface for testing API endpoints. */
   experimentalRequestBuilder?: boolean;

package/plugin/routes/Overview.astro

@@ -29,7 +29,7 @@ const metadata: SpecMetadata = langsWithSpecs.map(({ language, spec }) => [
 
 // PageTitle override will skip rendering the default Starlight title
 Astro.locals._stlStarlightPage = {
-  hasMarkdownRoute: false,
+  hasMarkdownRoute: true,
 };
 ---
 

package/plugin/routes/markdown.ts

@@ -1,14 +1,23 @@
 import type { APIRoute, GetStaticPaths } from 'astro';
+import type { Node } from '@markdoc/markdoc';
 import { getReadmeContent } from '../react/Routing';
-import { getResourceFromSpec } from '@stainless-api/docs-ui/utils';
+import { getResourceFromSpec, isResourceEmpty } from '@stainless-api/docs-ui/utils';
 
 import { renderMarkdown } from '@stainless-api/docs-ui/markdown';
+import * as md from '@stainless-api/docs-ui/markdown/md';
 
-import { parseStainlessPath, type DocsLanguage } from '@stainless-api/docs-ui/routing';
+import { parseStainlessPath, generateRoute, type DocsLanguage } from '@stainless-api/docs-ui/routing';
 import type { EnvironmentType } from '@stainless-api/docs-ui/markdown/utils';
-import { PROPERTY_SETTINGS, MIDDLEWARE } from 'virtual:stl-starlight-virtual-module';
+import {
+  PROPERTY_SETTINGS,
+  MIDDLEWARE,
+  RESOLVED_API_REFERENCE_PATH,
+} from 'virtual:stl-starlight-virtual-module';
 import { generateAllDocsRoutes } from '../helpers/generateDocsRoutes';
 import { getSDKJSONInSSR } from '../specs/fetchSpecSSR';
+import Markdoc from '@markdoc/markdoc';
+import type * as SDKJSON from '@stainless/sdk-json';
+import { API_REFERENCE_BASE_PATH } from 'virtual:stl-docs-virtual-module';
 
 type RouteProps = {
   stainlessPath: string;
@@ -21,20 +30,41 @@ export const getStaticPaths = (async () => {
   return paths;
 }) satisfies GetStaticPaths;
 
-export const GET: APIRoute<RouteProps> = async ({ props }) => {
-  const spec = await getSDKJSONInSSR(props.language);
+function renderLink(stainlessPath: string, title: string) {
+  const href = generateRoute(RESOLVED_API_REFERENCE_PATH, 'http', stainlessPath);
+  return href ? md.link(`${href}/index.md`, title) : md.text(title);
+}
 
-  if (props.kind === 'readme') {
-    const readmeContent = await getReadmeContent(spec, props.language);
-    return new Response(readmeContent, {
-      headers: { 'Content-Type': 'text/plain' },
-    });
+function renderOverviewResource(resource: SDKJSON.Resource, topLevel: boolean): Node[] {
+  const link = renderLink(resource.stainlessPath, resource.title);
+
+  const methodItems = Object.values(resource.methods).map((method) =>
+    md.item(md.paragraph(renderLink(method.stainlessPath, method.title))),
+  );
+
+  const subItems = Object.values(resource.subresources ?? {})
+    .filter((sub) => !isResourceEmpty(sub))
+    .flatMap((sub) => renderOverviewResource(sub, false));
+
+  const nestedItems = [...methodItems, ...subItems];
+  const list = nestedItems.length > 0 ? [md.list(...nestedItems)] : [];
+
+  return topLevel ? [md.heading(2, [link]), ...list] : [md.item(md.paragraph(link), ...list)];
+}
+
+function renderOverview({ spec }: EnvironmentType): string {
+  const output: Node[] = [md.heading(1, 'API Reference')];
+
+  for (const resource of Object.values(spec.resources)) {
+    if (!isResourceEmpty(resource)) output.push(...renderOverviewResource(resource, true));
   }
 
-  const parsed = parseStainlessPath(props.stainlessPath);
-  const resource = getResourceFromSpec(props.stainlessPath, spec);
+  const doc = new Markdoc.Ast.Node('document', {}, output);
+  return Markdoc.format(doc);
+}
 
-  if (!resource) throw new Error('Invalid route');
+export const GET: APIRoute<RouteProps> = async ({ props, routePattern }) => {
+  const spec = await getSDKJSONInSSR(props.language ?? 'http');
 
   const env: EnvironmentType = {
     spec,
@@ -48,6 +78,25 @@ export const GET: APIRoute<RouteProps> = async ({ props }) => {
     },
   };
 
+  if (routePattern === `${API_REFERENCE_BASE_PATH}/index.md`) {
+    const content = renderOverview({ ...env, language: 'http' });
+    return new Response(content, {
+      headers: { 'Content-Type': 'text/plain' },
+    });
+  }
+
+  if (props.kind === 'readme') {
+    const readmeContent = await getReadmeContent(spec, props.language);
+    return new Response(readmeContent, {
+      headers: { 'Content-Type': 'text/plain' },
+    });
+  }
+
+  const parsed = parseStainlessPath(props.stainlessPath);
+  const resource = getResourceFromSpec(props.stainlessPath, spec);
+
+  if (!resource) throw new Error('Invalid route');
+
   const target = props.kind === 'http_method' && parsed?.method ? resource.methods[parsed.method]! : resource;
   const output = renderMarkdown(env, target);
 

package/plugin/specs/generateSpec.ts

@@ -106,6 +106,4 @@ export const specCache = new FileCache({
 
 export type SpecCacheResult = Awaited<ReturnType<typeof specCache.get>>;
 
-export type GenerateSpecFn = typeof generateSpecFromStrings;
-
-export type SpecWithAuth = Awaited<ReturnType<GenerateSpecFn>>;
+export type SpecWithAuth = Awaited<ReturnType<typeof generateSpecFromStrings>>;