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

package/plugin/vendor/templates/cli.md

@@ -0,0 +1 @@
+SDK_Readme

package/plugin/vendor/templates/go.md

@@ -7,6 +7,8 @@ from applications written in Go.
 
 SDK_GeneratedByStainless
 
+SDK_MCPReadmeSection
+
 ## Installation
 
 SDK_ReleasePleaseMarkdownBlockStart
@@ -31,7 +33,7 @@ SDK_ReleasePleaseMarkdownBlockEnd
 
 ## Requirements
 
-This library requires Go 1.18+.
+This library requires Go 1.22+.
 
 ## Usage
 
@@ -307,7 +309,7 @@ This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) con
 
 We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
 
-We are keen for your feedback; please open an [issue](SDK_GitHubRepoURL/issues) with questions, bugs, or suggestions.
+We are keen for your feedback; please open an [issue](SDK_RepoURL/issues) with questions, bugs, or suggestions.
 
 ## Contributing
 

package/plugin/vendor/templates/java.md

@@ -11,6 +11,8 @@ SDK_SectionSimilarToOtherSDK
 
 SDK_GeneratedByStainless
 
+SDK_MCPReadmeSection
+
 SDK_SectionDocumentationReference
 
 SDK_SectionInstallation
@@ -57,6 +59,8 @@ SDK_SectionTimeouts
 
 SDK_SectionProxies
 
+SDK_SectionConnectionPooling
+
 SDK_SectionHTTPS
 
 SDK_SectionEnvironments
@@ -84,4 +88,4 @@ This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) con
 
 We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
 
-We are keen for your feedback; please open an [issue](SDK_GitHubRepoURL/issues) with questions, bugs, or suggestions.
+We are keen for your feedback; please open an [issue](SDK_RepoURL/issues) with questions, bugs, or suggestions.

package/plugin/vendor/templates/kotlin.md

@@ -11,6 +11,8 @@ SDK_SectionSimilarToOtherSDK
 
 SDK_GeneratedByStainless
 
+SDK_MCPReadmeSection
+
 SDK_SectionDocumentationReference
 
 SDK_SectionInstallation
@@ -57,6 +59,8 @@ SDK_SectionTimeouts
 
 SDK_SectionProxies
 
+SDK_SectionConnectionPooling
+
 SDK_SectionHTTPS
 
 SDK_SectionEnvironments
@@ -84,4 +88,4 @@ This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) con
 
 We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
 
-We are keen for your feedback; please open an [issue](SDK_GitHubRepoURL/issues) with questions, bugs, or suggestions.
+We are keen for your feedback; please open an [issue](SDK_RepoURL/issues) with questions, bugs, or suggestions.

package/plugin/vendor/templates/node.md

@@ -10,6 +10,8 @@ SDK_DocumentationReference
 
 SDK_GeneratedByStainless
 
+SDK_MCPReadmeSection
+
 ## Installation
 
 SDK_NPMInstallInstructions
@@ -169,7 +171,7 @@ import SDK_PackageName from 'SDK_NPMPackage';
 ```
 
 To do the inverse, add `import "SDK_NPMPackage/shims/node"` (which does import polyfills).
-This can also be useful if you are getting the wrong TypeScript types for `Response` ([more details](SDK_GitHubRepoCodeURL/src/_shims#readme)).
+This can also be useful if you are getting the wrong TypeScript types for `Response` ([more details](SDK_RepoCodeURL/src/_shims#readme)).
 
 ### Logging and middleware
 
@@ -214,7 +216,7 @@ This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) con
 
 We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
 
-We are keen for your feedback; please open an [issue](SDK_GitHubRepoURL/issues) with questions, bugs, or suggestions.
+We are keen for your feedback; please open an [issue](SDK_RepoURL/issues) with questions, bugs, or suggestions.
 
 ## Requirements
 

package/plugin/vendor/templates/python.md

@@ -9,6 +9,8 @@ SDK_ScreencastURL
 
 SDK_GeneratedByStainless
 
+SDK_MCPReadmeSection
+
 ## Documentation
 
 SDK_DocumentationCallout SDK_APIReferenceCallout
@@ -227,7 +229,7 @@ This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) con
 
 We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
 
-We are keen for your feedback; please open an [issue](SDK_GitHubRepoURL/issues) with questions, bugs, or suggestions.
+We are keen for your feedback; please open an [issue](SDK_RepoURL/issues) with questions, bugs, or suggestions.
 
 ### Determining the installed version
 
@@ -242,7 +244,7 @@ print(SDK_PythonPackageImportName.__version__)
 
 ## Requirements
 
-Python 3.8 or higher.
+Python 3.9 or higher.
 
 ## Contributing
 

package/plugin/vendor/templates/ruby.md

@@ -1,11 +1,13 @@
 # SDK_PackageTitle API library
 
-SDK_ReadmeOpening It ships with comprehensive types & docstrings in Yard, RBS, and RBI – [see below](SDK_GitHubURL#Sorbet) for usage with Sorbet. The standard library's `net/http` is used as the HTTP transport, with connection pooling via the `connection_pool` gem.
+SDK_ReadmeOpening It ships with comprehensive types & docstrings in Yard, RBS, and RBI – [see below](SDK_RepoURL#Sorbet) for usage with Sorbet. The standard library's `net/http` is used as the HTTP transport, with connection pooling via the `connection_pool` gem.
 
 SDK_ScreencastURL
 
 SDK_GeneratedByStainless
 
+SDK_MCPReadmeSection
+
 ## Documentation
 
 Documentation for releases of this gem can be found [on RubyDoc](SDK_RubyDocInfoURL).
@@ -142,4 +144,4 @@ Ruby SDK_RubyMinVersion or higher.
 
 ## Contributing
 
-See [the contributing documentation](SDK_GitHubAssetURL/CONTRIBUTING.md).
+See [the contributing documentation](SDK_RepoAssetURL/CONTRIBUTING.md).

package/plugin/vendor/templates/terraform.md

@@ -53,7 +53,7 @@ This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) con
 
 We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
 
-We are keen for your feedback; please open an [issue](SDK_GitHubRepoURL/issues) with questions, bugs, or suggestions.
+We are keen for your feedback; please open an [issue](SDK_RepoURL/issues) with questions, bugs, or suggestions.
 
 ## Contributing
 

package/plugin/vendor/templates/typescript.md

@@ -10,6 +10,8 @@ SDK_DocumentationReference
 
 SDK_GeneratedByStainless
 
+SDK_MCPReadmeSection
+
 ## Installation
 
 SDK_NPMInstallInstructions
@@ -298,7 +300,7 @@ This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) con
 
 We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
 
-We are keen for your feedback; please open an [issue](SDK_GitHubRepoURL/issues) with questions, bugs, or suggestions.
+We are keen for your feedback; please open an [issue](SDK_RepoURL/issues) with questions, bugs, or suggestions.
 
 ## Requirements
 

package/resolveSrcFile.ts

@@ -0,0 +1,10 @@
+import { join } from 'path';
+const dirName = import.meta.dirname;
+/**
+ * Resolve a source file path relative to the stl-starlight package.
+ * @param projectPath - The relative path to the source file.
+ * @returns The absolute path to the source file.
+ */
+export function resolveSrcFile(...projectPath: string[]) {
+  return join(dirName, ...projectPath);
+}

package/scripts/vendor_deps.ts

@@ -3,7 +3,7 @@ import fs from 'fs';
 import path from 'path';
 import { z } from 'zod';
 
-import { Languages } from '@stainless-api/docs-ui/src/routing';
+import { Languages } from '@stainless-api/docs-ui/routing';
 
 const DEPS_DIR = './plugin/vendor';
 
@@ -11,12 +11,12 @@ config();
 
 const envSchema = z.object({
   // absolute path to the Stainless monorepo root
-  STAINLESS_MONOREPO_PATH: z.string(),
+  STAINLESS_ROOT: z.string(),
 });
 
 const env = envSchema.parse(process.env);
 
-console.log(`Using Stainless monorepo at ${env.STAINLESS_MONOREPO_PATH}`);
+console.log(`Using Stainless monorepo at ${env.STAINLESS_ROOT}`);
 
 if (fs.existsSync(DEPS_DIR)) {
   fs.rmSync(DEPS_DIR, { recursive: true });
@@ -25,11 +25,11 @@ if (fs.existsSync(DEPS_DIR)) {
 fs.mkdirSync(DEPS_DIR, { recursive: true });
 
 const previewWorkerPath = path.join(
-  env.STAINLESS_MONOREPO_PATH,
+  env.STAINLESS_ROOT,
   '/packages/preview-worker/dist/stainless/preview.worker.docs.js',
 );
 
-const readmeTemplatePath = path.join(env.STAINLESS_MONOREPO_PATH, '/legacy-dir-root/templates');
+const readmeTemplatePath = path.join(env.STAINLESS_ROOT, '/legacy-dir-root/templates');
 
 fs.copyFileSync(previewWorkerPath, path.join(DEPS_DIR, 'preview.worker.docs.js'));
 

package/shared/conditionalIntegration.ts

@@ -0,0 +1,28 @@
+import { AstroIntegration, type AstroIntegrationLogger } from 'astro';
+import { getSharedLogger } from './getSharedLogger';
+
+export default function conditionalIntegration({
+  condition,
+  integration,
+  reason,
+}: {
+  condition: boolean;
+  integration: AstroIntegration;
+  reason?: string | undefined;
+}): AstroIntegration {
+  if (condition) {
+    return integration;
+  }
+  return {
+    name: integration.name,
+    hooks: Object.fromEntries(
+      Object.keys(integration.hooks).map((hookName) => [
+        hookName,
+        ({ logger: localLogger }: { logger: AstroIntegrationLogger }) => {
+          const logger = getSharedLogger({ fallback: localLogger });
+          logger.info(`Skipping ${integration.name} integration. Reason: ${reason ?? 'not provided'}`);
+        },
+      ]),
+    ),
+  };
+}

package/shared/getProsePages.ts

@@ -0,0 +1,41 @@
+import { readdir } from 'fs/promises';
+import { join, relative } from 'path';
+
+/**
+ * Get all prose pages after a build, by reading all HTML files from the
+ * given output directory, and not from assets.
+ *
+ * We cannot use the `assets` map here because it is not guaranteed to
+ * contain all files, especially if they were generated by other integrations.
+ * Other astro integrations may hijack the "[...slug]" entrypoint, and any files
+ * previously in the [...slug] asset map entry would be lost (this is where starlight stores
+ * its prose HTML files).
+ */
+export async function getProsePages({
+  apiReferenceBasePath,
+  outputBasePath,
+}: {
+  apiReferenceBasePath: string | null;
+  outputBasePath: string;
+}): Promise<string[]> {
+  const allFiles = await readdir(outputBasePath, {
+    recursive: true,
+    withFileTypes: true,
+  });
+
+  const htmlFiles = allFiles
+    .filter((file) => file.isFile() && file.name.endsWith('.html'))
+    .map((file) => join(file.parentPath, file.name));
+
+  if (!apiReferenceBasePath) return htmlFiles;
+  // Normalize by removing leading/trailing slashes from apiReferenceBasePath
+  const normalizedApiPath = apiReferenceBasePath.replace(/^\/+/g, '').replace(/\/+$/g, '');
+  const pagesToRender = htmlFiles.filter((absPath) => {
+    const relPath = relative(outputBasePath, absPath);
+    // Filter out API reference pages
+    if (relPath === normalizedApiPath || relPath.startsWith(`${normalizedApiPath}/`)) return false;
+    return true;
+  });
+
+  return pagesToRender;
+}

package/shared/getSharedLogger.ts

@@ -0,0 +1,15 @@
+import { AstroIntegrationLogger } from 'astro';
+
+let sharedLogger: AstroIntegrationLogger | null = null;
+
+// This is probably temporary, but it's a quick way to share a logger between our many integrations
+// we want to share a logger so they have the same "stainless" label
+
+export function setSharedLogger(logger: AstroIntegrationLogger) {
+  sharedLogger = logger;
+}
+
+// a fallback is probably not required, but it's a good safeguard in case we somehow call a logger before the shared logger is set
+export function getSharedLogger({ fallback }: { fallback: AstroIntegrationLogger }) {
+  return sharedLogger ?? fallback;
+}

package/shared/terminalUtils.ts

@@ -0,0 +1,3 @@
+export function bold(text: string) {
+  return `\x1b[1m${text}\x1b[0m`;
+}

package/shared/virtualModule.ts

@@ -1,7 +1,52 @@
-export function buildVirtualModuleString(vars: Record<string, any>) {
+import type { ViteUserConfig } from 'astro';
+
+type VitePlugin = NonNullable<ViteUserConfig['plugins']>[number];
+
+export function buildVirtualModuleString<T extends Record<string, unknown>>(vars: T) {
   return Object.entries(vars)
     .map(([key, value]) => {
       return `export const ${key} = ${JSON.stringify(value)};`;
     })
     .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>,
+): 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}`;
+      }
+    },
+    async load(id) {
+      if (id === `\0${bareId}`) {
+        const content = await contentLoader();
+        if (typeof content === 'string') {
+          return content;
+        }
+        return buildVirtualModuleString(content);
+      }
+    },
+  };
+}

package/src/content.config.ts

@@ -0,0 +1,9 @@
+// Stub here so that `astro sync` generates the correct types for the `docs` content collection
+
+import { defineCollection } from 'astro:content';
+import { docsLoader } from '@astrojs/starlight/loaders';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+};

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/chat/docs-chat-handler.ts

@@ -0,0 +1,18 @@
+import { FeedbackResponseBody, MetadataResponseBody, RequestBody, ResponseChunk } from './schemas';
+
+export type DocsChatHandler = {
+  generateResponse: (
+    {
+      query,
+      priorMessages,
+    }: {
+      query: string;
+      priorMessages: NonNullable<RequestBody['additionalContext']>['prior_messages'];
+    },
+    abortSignal: AbortSignal,
+  ) => AsyncGenerator<ResponseChunk>;
+
+  onRate: (spanId: string, score: 0 | 1) => Promise<FeedbackResponseBody>;
+
+  onAssignMetadata: (spanId: string, metadata: Record<string, string>) => Promise<MetadataResponseBody>;
+};