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

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @stainless-api/docs
 
+## 0.1.0-beta.138
+
+### Patch Changes
+
+- bb5f952: Stop loading AI chat examples from obsolete Stainless endpoint
+- 25d7a11: Stop creating Algolia prose indexes during docs site builds. Vector-based prose indexing is unaffected and remains controlled by the `experimental.disableStainlessProseIndexing` flag.
+- Updated dependencies [25d7a11]
+  - @stainless-api/docs-search@0.1.0-beta.49
+
 ## 0.1.0-beta.137
 
 ### Minor Changes

package/eslint-suppressions.json

@@ -64,10 +64,5 @@
     "@typescript-eslint/restrict-template-expressions": {
       "count": 4
     }
-  },
-  "stl-docs/proseSearchIndexing.ts": {
-    "@typescript-eslint/restrict-template-expressions": {
-      "count": 1
-    }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "0.1.0-beta.137",
+  "version": "0.1.0-beta.138",
   "publishConfig": {
     "access": "public"
   },
@@ -72,9 +72,9 @@
     "shiki": "^4.0.2",
     "unified": "^11.0.5",
     "web-worker": "^1.5.0",
+    "@stainless-api/docs-search": "0.1.0-beta.49",
     "@stainless-api/docs-ui": "0.1.0-beta.95",
-    "@stainless-api/ui-primitives": "0.1.0-beta.53",
-    "@stainless-api/docs-search": "0.1.0-beta.48"
+    "@stainless-api/ui-primitives": "0.1.0-beta.53"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.9",
@@ -83,13 +83,13 @@
     "@types/react": "19.2.14",
     "@types/react-dom": "^19.2.3",
     "@types/react-syntax-highlighter": "^15.5.13",
-    "astro": "^6.2.1",
+    "astro": "^6.2.2",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
     "typescript": "6.0.3",
     "vite": "^7.3.2",
     "vitest": "^4.1.5",
-    "zod": "^4.4.2",
+    "zod": "^4.4.3",
     "@stainless/eslint-config": "0.1.0-beta.2",
     "@stainless/sdk-json": "^0.1.0-beta.10"
   },

package/plugin/components/RequestBuilder/index.tsx

@@ -16,8 +16,6 @@ export function RequestBuilder({
 }) {
   let params: Param[];
   const spec = useSpec();
-  // https://github.com/Rel1cx/eslint-react/issues/1617
-  /* eslint-disable @eslint-react/error-boundaries */
   try {
     if (!spec) throw new Error('Spec is required for RequestBuilder');
     params = spec && extractParams(spec, method);
@@ -25,7 +23,6 @@ export function RequestBuilder({
     console.warn(e);
     return <div className={className}>{children}</div>;
   }
-  /* eslint-enable */
   const [httpMethod, path] = method.endpoint.split(' ') as [string, string];
 
   return (

package/shared/virtualModule.ts

@@ -10,23 +10,6 @@ export function buildVirtualModuleString<T extends Record<string, unknown>>(vars
     .join('\n');
 }
 
-export function makeVirtualModPlugin(bareId: string, content: string): VitePlugin {
-  return {
-    name: `stl-virtual-module-loader-${bareId}`,
-    resolveId(id) {
-      // The '\0' prefix tells Vite “this is a virtual module” and prevents it from being resolved again.
-      if (id === bareId) {
-        return `\0${bareId}`;
-      }
-    },
-    load(id) {
-      if (id === `\0${bareId}`) {
-        return content;
-      }
-    },
-  };
-}
-
 export function makeAsyncVirtualModPlugin<T extends Record<string, unknown>>(
   bareId: string,
   contentLoader: () => Promise<T | string>,

package/stl-docs/aiChatExamples.ts

@@ -1,95 +1,31 @@
-import { AstroIntegrationLogger } from 'astro';
-import z from 'zod';
-import {
-  buildVirtualModuleString,
-  makeAsyncVirtualModPlugin,
-  makeVirtualModPlugin,
-} from '../shared/virtualModule';
+import { buildVirtualModuleString } from '../shared/virtualModule';
 import type * as virtualExampleModule from 'virtual:stl-docs-ai-chat-examples';
 type VirtualExampleModule = typeof virtualExampleModule;
 
-const exampleSchema = z.array(
-  z.object({
-    shortPrompt: z.string(),
-    longPrompt: z.string(),
-    icon: z.string(),
-  }),
-);
-export type ExamplePromptResponse = z.infer<typeof exampleSchema>;
+export type ExamplePromptResponse = {
+  shortPrompt: string;
+  longPrompt: string;
+  icon: string;
+}[];
 
-// handles actually retrieving the information via the Stainless API
-async function loadExamples(
-  projectName: string,
-  logger: AstroIntegrationLogger,
-): Promise<ExamplePromptResponse | undefined> {
-  try {
-    const response = await fetch(`https://api.stainless.com/api/ai/steelie-examples/${projectName}`, {
-      method: 'GET',
-    });
-
-    const text = await response.text();
-    if (!response.ok) {
-      logger.error(`failed to fetch AI chat examples: ${text}`);
-      return undefined;
-    }
-    const examples = exampleSchema.parse(JSON.parse(text));
-    return examples;
-  } catch (error) {
-    if (error instanceof Error) logger.error(`failed to fetch AI chat examples: ${error.message}`);
-    else throw error;
-    return undefined;
-  }
-}
-
-export default async function generateExamplesPlugin({
-  projectName,
-  logger,
-  exampleOverrides,
-}: {
-  projectName: string | undefined;
-  logger: AstroIntegrationLogger;
-  exampleOverrides?: ExamplePromptResponse;
-}) {
-  // if the user has specified any examples, return those immediately
-  // instead of loading them via the web.
-  if (exampleOverrides) {
-    return makeVirtualModPlugin(
-      'virtual:stl-docs-ai-chat-examples',
-      generateVirtualModuleString(exampleOverrides),
-    );
+export function generateExamplesVirtualModule(exampleOverrides: ExamplePromptResponse | undefined): string {
+  if (!exampleOverrides) {
+    return buildVirtualModuleString({ examples: undefined } satisfies VirtualExampleModule);
   }
-  // if we don't have a defined project name, don't try to fetch examples
-  if (!projectName) {
-    return makeVirtualModPlugin(
-      'virtual:stl-docs-ai-chat-examples',
-      buildVirtualModuleString({ examples: undefined } satisfies VirtualExampleModule),
-    );
-  }
-
-  // otherwise, promise to get the right examples at some point later on
-  const examplesPromise = loadExamples(projectName, logger);
-  return makeAsyncVirtualModPlugin<VirtualExampleModule>('virtual:stl-docs-ai-chat-examples', async () => {
-    const examples = await examplesPromise;
-    return generateVirtualModuleString(examples);
-  });
-}
-
-function generateVirtualModuleString(examples: ExamplePromptResponse | undefined) {
-  if (!examples) return 'export const examples = undefined;';
 
   // Generate icon imports
   // prettier-ignore
   const pascalToKebab = (str: string) => str.split(/(?=[A-Z])/).join('-').toLowerCase();
   const iconImportPath = (iconName: string) =>
     import.meta.resolve(`lucide-react/dist/esm/icons/${pascalToKebab(iconName)}.js`);
-  const iconImports = examples.map(
+  const iconImports = exampleOverrides.map(
     ({ icon }) => `import ${icon} from ${JSON.stringify(iconImportPath(icon))}`,
   );
 
   // Reference icon imports in `examples` exported object
   // "icon":"Sparkles" -> "icon":Sparkles
   const iconStringsToIdents = (jsonBlob: string) => jsonBlob.replace(/"icon":\s*"(\w+)"/g, '"icon":$1');
-  const exportBody = `export const examples = ${iconStringsToIdents(JSON.stringify(examples))};`;
+  const exportBody = `export const examples = ${iconStringsToIdents(JSON.stringify(exampleOverrides))};`;
 
   return [...iconImports, exportBody].join('\n');
 }

package/stl-docs/index.ts

@@ -20,13 +20,12 @@ import {
 import { buildVirtualModuleString } from '../shared/virtualModule';
 import { resolveSrcFile } from '../resolveSrcFile';
 import { stainlessDocsMarkdownRenderer } from './proseMarkdown/proseMarkdownIntegration';
-import { getSharedLogger, setSharedLogger } from '../shared/getSharedLogger';
+import { setSharedLogger } from '../shared/getSharedLogger';
 import { stainlessDocsVectorProseIndexing } from './proseDocSync';
-import { stainlessDocsAlgoliaProseIndexing } from './proseSearchIndexing';
 import { stainlessStarlight } from '../plugin';
 import { getFontRoles, flattenFonts } from './fonts';
 import conditionalIntegration from '../shared/conditionalIntegration';
-import generateExamplesPlugin from './aiChatExamples';
+import { generateExamplesVirtualModule } from './aiChatExamples';
 import { ogImageStarlightPlugin } from './og-image';
 
 export * from '../plugin';
@@ -172,8 +171,7 @@ function stainlessDocsIntegration(
   return {
     name: 'stl-docs-astro',
     hooks: {
-      'astro:config:setup': async ({ updateConfig, command, config: astroConfig, logger: localLogger }) => {
-        const logger = getSharedLogger({ fallback: localLogger });
+      'astro:config:setup': ({ updateConfig, command, config: astroConfig }) => {
         // we only handle redirects for builds
         // in dev, Astro handles them for us
         if (command === 'build' && astroConfig.redirects) {
@@ -195,30 +193,35 @@ function stainlessDocsIntegration(
           vmAiChatHandlerExport = `export { default as AI_CHAT_HANDLER } from '${handlerEntrypoint}';`;
         }
 
-        const virtualModules = new Map(
-          Object.entries({
-            'virtual:stl-docs-virtual-module': [
-              buildVirtualModuleString({
-                TABS: config.tabs.map((tab) => ({ ...tab, link: withBase(tab.link) })),
-                SPLIT_TABS_ENABLED: config.splitTabsEnabled,
-                HEADER_LINKS: config.header.links.map((link) => ({ ...link, link: withBase(link.link) })),
-                HEADER_LAYOUT: config.header.layout,
-                ENABLE_CLIENT_ROUTER: config.enableClientRouter,
-                API_REFERENCE_BASE_PATH: apiReferenceBasePath ?? '/api',
-                ENABLE_PROSE_MARKDOWN_RENDERING: config.enableProseMarkdownRendering,
-                ENABLE_CONTEXT_MENU: !!config.contextMenu, // TODO: do not duplicate this between both virtual modules
-                CONTEXT_MENU_ENABLE_THIRD_PARTY:
-                  (typeof config.contextMenu === 'object' ? config.contextMenu.thirdParty : null) ?? true,
-                RENDER_PAGE_DESCRIPTIONS: config.renderPageDescriptions,
-                FONTS: getFontRoles(config.fonts),
-                LINK_GROUP_TITLES_TO_OVERVIEW_PAGES: config.linkGroupTitlesToOverviewPages,
-                RENDER_CREDITS: config.credits,
-                SITE_TITLE: config.siteTitle,
-              }),
-            ].join('\n'),
-            'virtual:stl-docs-ai-chat': vmAiChatHandlerExport,
-          }),
-        );
+        const virtualModules = new Map<string, string>([
+          [
+            'virtual:stl-docs-virtual-module',
+            buildVirtualModuleString({
+              TABS: config.tabs.map((tab) => ({ ...tab, link: withBase(tab.link) })),
+              SPLIT_TABS_ENABLED: config.splitTabsEnabled,
+              HEADER_LINKS: config.header.links.map((link) => ({ ...link, link: withBase(link.link) })),
+              HEADER_LAYOUT: config.header.layout,
+              ENABLE_CLIENT_ROUTER: config.enableClientRouter,
+              API_REFERENCE_BASE_PATH: apiReferenceBasePath ?? '/api',
+              ENABLE_PROSE_MARKDOWN_RENDERING: config.enableProseMarkdownRendering,
+              ENABLE_CONTEXT_MENU: !!config.contextMenu, // TODO: do not duplicate this between both virtual modules
+              CONTEXT_MENU_ENABLE_THIRD_PARTY:
+                (typeof config.contextMenu === 'object' ? config.contextMenu.thirdParty : null) ?? true,
+              RENDER_PAGE_DESCRIPTIONS: config.renderPageDescriptions,
+              FONTS: getFontRoles(config.fonts),
+              LINK_GROUP_TITLES_TO_OVERVIEW_PAGES: config.linkGroupTitlesToOverviewPages,
+              RENDER_CREDITS: config.credits,
+              SITE_TITLE: config.siteTitle,
+            }),
+          ],
+          ['virtual:stl-docs-ai-chat', vmAiChatHandlerExport],
+        ]);
+        if (config.aiChat) {
+          virtualModules.set(
+            'virtual:stl-docs-ai-chat-examples',
+            generateExamplesVirtualModule(config.aiChat.examples),
+          );
+        }
 
         updateConfig({
           fonts: [...flattenFonts(config.fonts), ...(astroConfig?.fonts ?? [])],
@@ -239,17 +242,6 @@ function stainlessDocsIntegration(
                   if (virtualModules.has(bare)) return virtualModules.get(bare);
                 },
               },
-              // Separate plugin for the examples because it has async resolution; not a simple string
-              // like the above plugins
-              ...(config.aiChat
-                ? [
-                    await generateExamplesPlugin({
-                      projectName: config.apiReference?.stainlessProject ?? undefined,
-                      logger,
-                      exampleOverrides: config.aiChat.examples,
-                    }),
-                  ]
-                : []),
             ],
           },
           build: {
@@ -311,11 +303,6 @@ export function stainlessDocs(config: StainlessDocsUserConfig): AstroIntegration
       integration: stainlessDocsMarkdownRenderer({ apiReferenceBasePath }),
       reason: 'disabled by experimental config "disableProseMarkdownRendering"',
     }),
-    conditionalIntegration({
-      condition: !config.experimental?.disableStainlessProseIndexing,
-      integration: stainlessDocsAlgoliaProseIndexing({ apiReferenceBasePath }),
-      reason: 'disabled by experimental config "disableStainlessProseIndexing"',
-    }),
     conditionalIntegration({
       condition: !config.experimental?.disableStainlessProseIndexing,
       integration: stainlessDocsVectorProseIndexing(normalizedConfig, apiReferenceBasePath),

package/stl-docs/proseSearchIndexing.ts

@@ -1,218 +0,0 @@
-import type { AstroIntegration } from 'astro';
-import { readFile } from 'fs/promises';
-import { getProsePages } from '../shared/getProsePages';
-import { getSharedLogger } from '../shared/getSharedLogger';
-import { bold } from '../shared/terminalUtils';
-import * as cheerio from 'cheerio';
-import { buildProseIndex } from '@stainless-api/docs-search/providers/algolia';
-
-class SectionContext {
-  headers: { level: number; text: string }[] = [];
-  headerId: string | undefined;
-  headerTag: string | undefined;
-  headerText: string | undefined;
-  hasContent = false;
-
-  get(): string | undefined {
-    if (this.headers.length === 0) return;
-    return this.headers.map((h) => h.text).join(' > ');
-  }
-
-  header({ id, tag, text }: { id: string; tag: string; text: string }) {
-    const level = getHeaderLevel(tag);
-    if (level > 0) {
-      while (this.headers.length > 0 && this.headers[this.headers.length - 1]!.level >= level) {
-        this.headers.pop();
-      }
-      this.headers.push({ level, text });
-    }
-    this.headerId = id;
-    this.headerTag = tag;
-    this.headerText = text;
-    this.hasContent = false;
-  }
-}
-
-function slugify(text: string): string {
-  return text
-    .toLowerCase()
-    .replace(/`/g, '')
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-|-$/g, '');
-}
-
-function getHeaderLevel(tag: string): number {
-  const match = tag.match(/^h(\d)$/);
-  return match ? parseInt(match[1]!, 10) : 0;
-}
-
-// Chunking configuration
-// We target 64-256 tokens per chunk, using ~1.3 tokens/word for English text
-const TOKENS_PER_WORD = 1.3;
-const MIN_TOKENS = 64;
-const MAX_TOKENS = 256;
-const MIN_WORDS = Math.floor(MIN_TOKENS / TOKENS_PER_WORD); // ~49 words
-const MAX_WORDS = Math.floor(MAX_TOKENS / TOKENS_PER_WORD); // ~197 words
-const SENTENCE_BREAK_WORDS = Math.floor((MAX_TOKENS * 0.875) / TOKENS_PER_WORD); // ~172 words
-
-/**
- * Chunks text content into segments of 64-256 tokens using word-based boundaries.
- * Prefers breaking at sentence endings for natural chunk boundaries.
- */
-function chunkTextByWords(text: string): string[] {
-  const words = text.split(/\s+/).filter((w) => w.length > 0);
-
-  if (words.length <= MAX_WORDS) {
-    return words.length > 0 ? [words.join(' ')] : [];
-  }
-
-  const chunks: string[] = [];
-  let currentChunk: string[] = [];
-
-  for (const word of words) {
-    currentChunk.push(word);
-
-    // Force break at max words
-    if (currentChunk.length >= MAX_WORDS) {
-      chunks.push(currentChunk.join(' '));
-      currentChunk = [];
-      continue;
-    }
-
-    // Prefer breaking at sentence boundaries after threshold
-    if (currentChunk.length >= SENTENCE_BREAK_WORDS && /[.!?]["']?$/.test(word)) {
-      chunks.push(currentChunk.join(' '));
-      currentChunk = [];
-    }
-  }
-
-  if (currentChunk.length > 0) {
-    if (currentChunk.length < MIN_WORDS && chunks.length > 0) {
-      const lastChunk = chunks[chunks.length - 1]!;
-      const mergedWords = lastChunk.split(/\s+/).length + currentChunk.length;
-      if (mergedWords <= MAX_WORDS) {
-        chunks[chunks.length - 1] = lastChunk + ' ' + currentChunk.join(' ');
-      } else {
-        chunks.push(currentChunk.join(' '));
-      }
-    } else {
-      chunks.push(currentChunk.join(' '));
-    }
-  }
-
-  return chunks;
-}
-
-type IndexEntry = {
-  chunk: { id: string; index: number; total: number };
-  id: string;
-  tag: string;
-  content: string;
-  language?: string;
-  sectionContext?: string;
-};
-
-const DEFAULT_ROOT = 'main';
-const DEFAULT_PATTERN = 'h1, h2, h3, h4, h5, h6, p, li, pre code';
-
-/**
- * Indexes HTML content for search, with section context and code language extraction.
- *
- * Features:
- * - Tracks header hierarchy to prepend section context (e.g., "Guide > Setup: ...")
- * - Extracts language metadata from code blocks (class="language-js")
- * - Uses word-based chunking with sentence boundary detection
- */
-function* indexHTML(content: string, root = DEFAULT_ROOT, pattern = DEFAULT_PATTERN): Generator<IndexEntry> {
-  const $ = cheerio.load(content);
-  const matches = $(root).find(pattern);
-
-  const ctx = new SectionContext();
-
-  for (const match of matches) {
-    const tagName = match.tagName.toLowerCase();
-    const rawText = $(match).text().trim();
-
-    if (getHeaderLevel(tagName) > 0) {
-      ctx.header({ id: $(match).attr('id') ?? slugify(rawText), tag: tagName, text: rawText });
-      continue;
-    }
-
-    // Check if this is a code block and extract language
-    const isCode = tagName === 'code' && $(match).parent().is('pre');
-    let language: string | undefined;
-    if (isCode) {
-      const classes = $(match).attr('class') || '';
-      const langMatch = classes.match(/(?:language-|lang-)([a-zA-Z0-9+-]+)/);
-      language = langMatch ? langMatch[1] : undefined;
-    }
-
-    // Build content with section context
-    const sectionContext = ctx.get();
-    const chunks = chunkTextByWords(rawText);
-    const chunkId = crypto.randomUUID();
-
-    for (const [chunkN, chunkText] of chunks.entries()) {
-      yield {
-        id: ctx.headerId ?? $(match).attr('id') ?? chunkId,
-        tag: isCode ? 'code' : tagName,
-        content: chunkText,
-        ...(sectionContext ? { sectionContext } : {}),
-        ...(language && { language }),
-        chunk: {
-          id: chunkId,
-          index: chunkN,
-          total: chunks.length,
-        },
-      };
-      ctx.hasContent = true;
-    }
-  }
-}
-
-export function stainlessDocsAlgoliaProseIndexing({
-  apiReferenceBasePath,
-}: {
-  apiReferenceBasePath: string | null;
-}): AstroIntegration {
-  return {
-    name: 'stl-docs-prose-indexing',
-    hooks: {
-      'astro:build:done': async ({ logger: localLogger, dir }) => {
-        const logger = getSharedLogger({ fallback: localLogger });
-        const outputBasePath = dir.pathname;
-
-        const {
-          PUBLIC_ALGOLIA_APP_ID: appId,
-          PUBLIC_ALGOLIA_INDEX: indexName,
-          PRIVATE_ALGOLIA_WRITE_KEY: algoliaWriteKey,
-        } = process.env;
-
-        if (!appId || !indexName || !algoliaWriteKey) {
-          logger.info('Skipping algolia indexing due to missing environment variables');
-          return;
-        }
-
-        const pagesToRender = await getProsePages({ apiReferenceBasePath, outputBasePath });
-        logger.info(bold(`Indexing ${pagesToRender.length} prose pages for algolia search`));
-
-        const objects = [];
-        for (const absHtmlPath of pagesToRender) {
-          const content = await readFile(absHtmlPath, 'utf-8');
-          const idx = indexHTML(content);
-          for (const entry of idx)
-            objects.push({
-              ...entry,
-              source: absHtmlPath.slice(outputBasePath.length),
-            });
-        }
-
-        try {
-          await buildProseIndex(appId, `${indexName}-prose`, algoliaWriteKey, objects);
-        } catch (err) {
-          logger.error(`Failed to index prose content: ${err}`);
-        }
-      },
-    },
-  };
-}