@stainless-api/docs 0.1.0-beta.120 → 0.1.0-beta.122

package/stl-docs/aiChatExamples.ts

@@ -0,0 +1,95 @@
+import { AstroIntegrationLogger } from 'astro';
+import z from 'zod';
+import {
+  buildVirtualModuleString,
+  makeAsyncVirtualModPlugin,
+  makeVirtualModPlugin,
+} 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>;
+
+// 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),
+    );
+  }
+  // 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(
+    ({ 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))};`;
+
+  return [...iconImports, exportBody].join('\n');
+}

package/stl-docs/index.ts

@@ -6,7 +6,7 @@ import { disableCalloutSyntaxStarlightPlugin } from './disableCalloutSyntax';
 import type { AstroIntegration } from 'astro';
 
 import { normalizeRedirects, type NormalizedRedirectConfig } from './redirects';
-import { join } from 'path';
+import path from 'node:path';
 import { mkdirSync, writeFileSync } from 'fs';
 import {
   parseStlDocsConfig,
@@ -20,12 +20,13 @@ import { buildVirtualModuleString } from '../shared/virtualModule';
 import type * as StlDocsVirtualModule from 'virtual:stl-docs-virtual-module';
 import { resolveSrcFile } from '../resolveSrcFile';
 import { stainlessDocsMarkdownRenderer } from './proseMarkdown/proseMarkdownIntegration';
-import { setSharedLogger } from '../shared/getSharedLogger';
+import { getSharedLogger, 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';
 
 export * from '../plugin';
 
@@ -168,19 +169,26 @@ function stainlessDocsIntegration(
   return {
     name: 'stl-docs-astro',
     hooks: {
-      'astro:config:setup': ({ updateConfig, command, config: astroConfig }) => {
+      'astro:config:setup': async ({ updateConfig, command, config: astroConfig, logger: localLogger }) => {
+        const logger = getSharedLogger({ fallback: localLogger });
         // we only handle redirects for builds
         // in dev, Astro handles them for us
         if (command === 'build' && astroConfig.redirects) {
           redirects = normalizeRedirects(astroConfig.redirects);
         }
 
+        const base = astroConfig.base ?? '/';
+        const withBase = (link: string) =>
+          ['http://', 'https://', '//'].some((prefix) => link.startsWith(prefix))
+            ? link
+            : path.posix.join(base, link);
+
         const virtualModules = new Map(
           Object.entries({
             'virtual:stl-docs-virtual-module': buildVirtualModuleString({
-              TABS: config.tabs,
+              TABS: config.tabs.map((tab) => ({ ...tab, link: withBase(tab.link) })),
               SPLIT_TABS_ENABLED: config.splitTabsEnabled,
-              HEADER_LINKS: config.header.links,
+              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',
@@ -218,6 +226,15 @@ function stainlessDocsIntegration(
                   if (virtualModules.has(bare)) return virtualModules.get(bare);
                 },
               },
+              ...(config.aiChat
+                ? [
+                    await generateExamplesPlugin({
+                      projectName: config.apiReference?.stainlessProject ?? undefined,
+                      logger,
+                      exampleOverrides: config.aiChat?.exampleOverrides,
+                    }),
+                  ]
+                : []),
             ],
             optimizeDeps: {
               include: config.aiChat
@@ -240,9 +257,9 @@ function stainlessDocsIntegration(
       },
       'astro:build:done': ({ dir }) => {
         if (redirects !== null) {
-          const stainlessDir = join(dir.pathname, '_stainless');
+          const stainlessDir = path.join(dir.pathname, '_stainless');
           mkdirSync(stainlessDir, { recursive: true });
-          const outputPath = join(stainlessDir, 'redirects.json');
+          const outputPath = path.join(stainlessDir, 'redirects.json');
           writeFileSync(outputPath, JSON.stringify(redirects, null, 2), {
             encoding: 'utf-8',
           });

package/stl-docs/loadStlDocsConfig.ts

@@ -4,6 +4,7 @@ import type { ButtonVariant } from '@stainless-api/ui-primitives';
 import type { AnchorHTMLAttributes } from 'react';
 import type starlight from '@astrojs/starlight';
 import { normalizeFonts, type StlDocsFontConfig } from './fonts';
+import type { ExamplePromptResponse } from './aiChatExamples';
 
 type StarlightConfig = Parameters<typeof starlight>[0];
 
@@ -79,7 +80,10 @@ export type StainlessDocsUserConfig = {
      */
     disableProseMarkdownRendering?: boolean;
     disableStainlessProseIndexing?: boolean;
-    aiChat?: { chatComponentPath: string };
+    aiChat?: {
+      chatComponentPath: string;
+      exampleOverrides?: ExamplePromptResponse;
+    };
     /**
      * Whether to link group titles to overview pages. Note: overview pages must already be present in the sidebar for this to work.
      *

package/virtual-module.d.ts

@@ -75,6 +75,16 @@ declare module 'virtual:stl-docs/components/AiChat.tsx' {
   export const STAINLESS_PROJECT: string | undefined;
 }
 
+declare module 'virtual:stl-docs-ai-chat-examples' {
+  export type ExamplePrompt = {
+    longPrompt: string;
+    shortPrompt: string;
+    icon: React.ComponentType;
+  };
+
+  export const examples: ExamplePrompt[] | undefined;
+}
+
 declare module 'virtual:stainless-apis-manifest' {
   import type { DocsLanguage } from '@stainless-api/docs-ui/routing';