@stainless-api/docs 0.1.0-beta.98 → 1.0.0-beta.140

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/sidebar-utils/sidebar-builder.ts

@@ -1,6 +1,7 @@
 import type * as SDKJSON from '@stainless/sdk-json';
 import { generateRoute, walkTree, type DocsLanguage } from '@stainless-api/docs-ui/routing';
 import type { StarlightRouteData } from '@astrojs/starlight/route-data';
+import { isResourceEntirelyUnsupported } from '@stainless-api/docs-ui/languages/terraform';
 
 function makeMethodOrResourceKey(entry: SDKJSON.Method | SDKJSON.Resource): string {
   if (entry.kind === 'http_method') {
@@ -172,8 +173,8 @@ export class SidebarConfigItemsBuilder {
     const decls = this.spec.decls[this.language] ?? {};
     const decl = decls[entry.stainlessPath];
     if (decl !== undefined) {
-      if ('ident' in decl) {
-        return decl;
+      if ('ident' in decl && decl.ident !== undefined) {
+        return decl as MethodDecl;
       }
     }
     return null;
@@ -249,13 +250,43 @@ export class SidebarConfigItemsBuilder {
     };
   }
 
+  private generateTerraformItems(resources: SDKJSON.Resource[]) {
+    const entries: ReferenceSidebarConfigItem[] = [];
+
+    for (const resource of resources) {
+      if (isResourceEntirelyUnsupported(resource, this.spec.decls['terraform'])) {
+        continue;
+      }
+      entries.push({
+        kind: 'resource_overview_page',
+        label: resource.title,
+        key: makeMethodOrResourceKey(resource),
+        badge: undefined,
+        metadata: {
+          subResourceCount: countKeys(resource.subresources),
+          methodCount: countKeys(resource.methods),
+          modelCount: countKeys(resource.models),
+        },
+      });
+    }
+    return entries;
+  }
+
   public generateItems(): ReferenceSidebarConfigItem[] {
     const resourceMap = this.spec.resources;
     const { resources, sharedModelsResource } = pullOutSharedModelsResource(Object.values(resourceMap ?? {}));
 
-    const entries: ReferenceSidebarConfigItem[] = resources.filter(isResourceNonEmpty).map((r) => {
-      return this.generateResourceGroup(r, false);
-    });
+    let entries: ReferenceSidebarConfigItem[];
+
+    if (this.language === 'terraform') {
+      // Handle Terraform specifically
+      // In TF, we only render the top level resource, not the subresources.
+      entries = this.generateTerraformItems(resources);
+    } else {
+      entries = resources.filter(isResourceNonEmpty).map((r) => {
+        return this.generateResourceGroup(r, false);
+      });
+    }
 
     const includeSharedModels = this.options?.includeSharedModels ?? false;
     if (includeSharedModels && sharedModelsResource) {
@@ -307,11 +338,6 @@ function forceGenerateRoute({
   return route;
 }
 
-export type BuildSidebarParams = {
-  basePath: string;
-  currentSlug: string;
-};
-
 type ToStarlightSidebarParams = {
   basePath: string;
   spec: SDKJSON.Spec;
@@ -381,10 +407,10 @@ export function toStarlightSidebar({
         throw new Error(`Unknown entry kind ${JSON.stringify(entry)}`);
       }
     } else if (entry.kind === 'group') {
-      // Skip pushing the group if if the resource it represents is not available in the current language.
-      // This occurs when SDK generation for the current language is skipped in the Stainless config for that resource.
       if (entry.resourceGroupKey) {
         const resourceOrMethod = getResourceOrMethod(spec, entry.resourceGroupKey);
+        // Skip pushing the group if if the resource it represents is not available in the current language.
+        // This occurs when SDK generation for the current language is skipped in the Stainless config for that resource.
         if (resourceOrMethod?.data?.kind === 'resource' && !resourceOrMethod?.data?.[currentLanguage]) {
           continue;
         }

package/plugin/specs/defaultSpecLoader.ts

@@ -0,0 +1,192 @@
+import path from 'path';
+import type { SpecLoaderFn, SpecLoaderParams } from './utils';
+import Stainless, { APIError } from '@stainless-api/sdk';
+import { DocsLanguage } from '@stainless-api/docs-ui/routing';
+import { bold } from '../../shared/terminalUtils';
+import { mkdir, readdir, readFile, rm, writeFile } from 'fs/promises';
+import { generateSpecFromStrings, previewWorkerCode } from '@stainless/sdk-json/spec';
+import { Spec, SpecLanguage } from '@stainless/sdk-json';
+import crypto from 'crypto';
+
+function resolvePath(inputPath: string) {
+  return path.resolve(process.cwd(), inputPath);
+}
+
+function getLocalFilePaths() {
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  const oasPath = process.env.OPENAPI_PATH;
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  const configPath = process.env.STAINLESS_CONFIG_PATH;
+
+  if (!oasPath || !configPath) {
+    return null;
+  }
+
+  return {
+    oasPath: resolvePath(oasPath),
+    configPath: resolvePath(configPath),
+  };
+}
+
+async function fetchVersionInfo(project: string, apiKey: string): Promise<Record<DocsLanguage, string>> {
+  const data = await fetch(`https://api.stainless.com/api/projects/${project}/package-versions`, {
+    headers: { Authorization: `Bearer ${apiKey}` },
+  });
+
+  const content = await data.text();
+  return JSON.parse(content) as Record<DocsLanguage, string>;
+}
+
+function redactApiKey(apiKey: string) {
+  return apiKey
+    .split('')
+    .map((char, index) => (index < 10 ? char : '*'))
+    .join('');
+}
+
+async function loadInputs({ apiKey, logger, stainlessProject, branch }: SpecLoaderParams) {
+  const localFilePaths = getLocalFilePaths();
+
+  if (localFilePaths) {
+    try {
+      const oasStr = await readFile(localFilePaths.oasPath, 'utf8');
+      const configStr = await readFile(localFilePaths.configPath, 'utf8');
+      return {
+        oasStr,
+        configStr,
+        versionInfo: null,
+      };
+    } catch (e) {
+      logger.error(bold('Failed to load spec inputs from files:'));
+      logger.error(e instanceof Error ? e.message : String(e));
+      process.exit(1);
+    }
+  }
+
+  if (!apiKey) {
+    logger.error(
+      [
+        bold(
+          'No Stainless credentials found. Please choose one of the following options to authenticate with Stainless:',
+        ),
+        '- Run `stl auth login` to authenticate via the Stainless CLI',
+        '- Provide a Stainless API key via the `STAINLESS_API_KEY` environment variable (eg. in a .env file)',
+        '- Set the `apiKey` option in the Stainless Docs config',
+      ].join('\n'),
+    );
+    process.exit(1);
+  }
+
+  try {
+    const client = new Stainless({ apiKey });
+    const configs = await client.projects.configs.retrieve({
+      project: stainlessProject,
+      branch: branch,
+      include: 'openapi',
+    });
+    const versionInfo = await fetchVersionInfo(stainlessProject, apiKey);
+
+    const configYML = Object.values(configs)[0] as { content: unknown };
+    const oasJson = Object.values(configs)[1] as { content: unknown };
+    const oasStr = oasJson['content'];
+    const configStr = configYML['content'];
+
+    if (typeof oasStr !== 'string' || typeof configStr !== 'string') {
+      logger.error('Received invalid OAS or config from Stainless');
+      process.exit(1);
+    }
+
+    return {
+      oasStr,
+      configStr,
+      versionInfo,
+    };
+  } catch (e) {
+    if (e instanceof APIError && e.status >= 400 && e.status < 500) {
+      logger.error(`Failed to load requested project slug: "${stainlessProject}"`);
+      if (apiKey) {
+        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.`,
+      );
+    }
+    process.exit(1);
+  }
+}
+
+async function maybeLoadJSONFile<T>(filePath: string): Promise<T | null> {
+  try {
+    const fileContents = await readFile(filePath, 'utf8');
+    return JSON.parse(fileContents) as T;
+  } catch {
+    return null;
+  }
+}
+
+async function cleanupDirectory(directory: string, filesToKeep: string[]) {
+  const allFiles = await readdir(directory);
+  const unusedFiles = allFiles.filter((file) => !filesToKeep.includes(file));
+  await Promise.all(unusedFiles.map((file) => rm(path.join(directory, file))));
+  return {
+    deletedCount: unusedFiles.length,
+  };
+}
+
+export const defaultSpecLoader: SpecLoaderFn = async (params) => {
+  const { createCodegenDir } = params;
+
+  const inputs = await loadInputs(params);
+
+  const specsDirectory = path.join(createCodegenDir().pathname, 'specs2');
+  await mkdir(specsDirectory, { recursive: true });
+
+  const fileName =
+    crypto
+      .createHash('sha256')
+      .update(JSON.stringify(inputs) + previewWorkerCode)
+      .digest('hex')
+      .slice(0, 10) + '.json';
+
+  const filePath = path.join(specsDirectory, fileName);
+
+  const cachedSpec = await maybeLoadJSONFile<{ languages: SpecLanguage[]; sdkJson: Spec }>(filePath);
+  // skip generation since we already have a cached spec
+  if (cachedSpec) {
+    params.logger.info(`Loaded cached spec: ${fileName}`);
+    return [
+      {
+        filePath,
+        languages: cachedSpec.languages,
+        sdkJson: cachedSpec.sdkJson,
+      },
+    ];
+  }
+
+  const result = await generateSpecFromStrings({
+    oasStr: inputs.oasStr,
+    configStr: inputs.configStr,
+    languageOverrides: {
+      mode: 'exclude',
+      list: params.excludeLanguages ?? [],
+    },
+    versionInfo: inputs.versionInfo,
+    stainlessProject: params.stainlessProject,
+  });
+
+  await writeFile(filePath, JSON.stringify(result), 'utf8');
+  params.logger.info(`Generated: ${fileName}`);
+
+  const { deletedCount } = await cleanupDirectory(specsDirectory, [fileName]);
+  if (deletedCount > 0) {
+    params.logger.info(`Cleaned up ${deletedCount} unused spec file(s)`);
+  }
+
+  return [
+    {
+      filePath,
+      languages: result.languages.filter((language) => language !== 'sql' && language !== 'openapi'),
+      sdkJson: result.sdkJson,
+    },
+  ];
+};

package/plugin/specs/fetchSpecSSR.ts

@@ -1,7 +1,7 @@
 import { readFile } from 'fs/promises';
 
 import { api } from 'virtual:stainless-apis-manifest';
-import { SpecWithAuth } from './generateSpec';
+import type { SpecWithAuth } from '@stainless/sdk-json/spec';
 import { DocsLanguage } from '@stainless-api/docs-ui/routing';
 
 const cachedSpecWithAuth: Record<string, SpecWithAuth> = {};

package/plugin/specs/utils.ts

@@ -0,0 +1,86 @@
+import { Spec } from '@stainless/sdk-json';
+import { readFile } from 'fs/promises';
+import { DocsLanguage } from '@stainless-api/docs-ui/routing';
+import { AstroIntegrationLogger } from 'astro';
+
+type PossibleLanguage = NonNullable<NonNullable<NonNullable<Spec['docs']>['languages']>[number]>;
+
+export type SpecLoaderParams = {
+  /**
+   * The slug of your Stainless project.
+   */
+  stainlessProject: string;
+  /**
+   * The branch of your Stainless project.
+   */
+  branch: string;
+  /**
+   * The Stainless API key. This can be used to make requests against the Stainless API.
+   */
+  apiKey: string | null;
+  /**
+   * The languages that the user has explicitly asked to be excluded from the API reference.
+   */
+  excludeLanguages: DocsLanguage[] | null;
+  /**
+   * An Astro logger. This should be used for logging messages.
+   */
+  logger: AstroIntegrationLogger;
+  /**
+   * A function that creates a directory in .astro. See: https://docs.astro.build/en/reference/integrations-reference/#createcodegendir
+   */
+  createCodegenDir: () => URL;
+};
+
+type SpecLoaderResult = {
+  /**
+   * The file path to the loaded spec. The spec MUST be written to a path on disk.
+   * If you are not sure where to place it, create a directory in .astro using the `createCodegenDir` function passed in the parameters of the spec loader function.
+   */
+  filePath: string;
+  /**
+   * The languages that are represented in the spec.
+   */
+  languages: PossibleLanguage[];
+  /**
+   * Optionally, if you already have already the spec in memory, you can provide it. If not provided, the contents of the file at `filePath` will be read.
+   * IMPORTANT: This should be equivalent to the contents of the file at `filePath`. If not, bugs and inconsistencies will arise.
+   */
+  sdkJson?: Spec;
+};
+
+export type SpecLoaderFn = (opts: SpecLoaderParams) => Promise<SpecLoaderResult[]>;
+
+async function readSpecFromFile(filePath: string) {
+  const txt = await readFile(filePath, 'utf8');
+  const json = JSON.parse(txt) as Spec;
+  return json;
+}
+
+export async function loadAllSpecs(specLoaderResultsPromise: Promise<SpecLoaderResult[]>) {
+  const specLoaderResults = await specLoaderResultsPromise;
+  const specs = await Promise.all(
+    specLoaderResults.map(async (result) => {
+      return {
+        filePath: result.filePath,
+        languages: result.languages,
+        sdkJson: result.sdkJson ?? (await readSpecFromFile(result.filePath)),
+      };
+    }),
+  );
+  return specs;
+}
+
+export type LoadedSpecs = Awaited<ReturnType<typeof loadAllSpecs>>;
+
+export function flatSpecsList(specs: LoadedSpecs) {
+  return specs
+    .map((s) =>
+      s.languages.map((language) => ({
+        language,
+        sdkJson: s.sdkJson,
+        filePath: s.filePath,
+      })),
+    )
+    .flat();
+}

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

@@ -27,15 +27,14 @@ export async function getProsePages({
     .filter((file) => file.isFile() && file.name.endsWith('.html'))
     .map((file) => join(file.parentPath, file.name));
 
-  // Filter out API reference pages
+  if (!apiReferenceBasePath) return htmlFiles;
+  // Normalize by removing leading/trailing slashes from apiReferenceBasePath
+  const normalizedApiPath = apiReferenceBasePath.replace(/^\/+/g, '').replace(/\/+$/g, '');
   const pagesToRender = htmlFiles.filter((absPath) => {
-    if (!apiReferenceBasePath) {
-      return true;
-    }
     const relPath = relative(outputBasePath, absPath);
-    // Normalize by removing leading/trailing slashes from apiReferenceBasePath
-    const normalizedApiPath = apiReferenceBasePath.replace(/^\/+|\/+$/g, '');
-    return !relPath.startsWith(normalizedApiPath);
+    // Filter out API reference pages
+    if (relPath === normalizedApiPath || relPath.startsWith(`${normalizedApiPath}/`)) return false;
+    return true;
   });
 
   return pagesToRender;

package/shared/virtualModule.ts

@@ -1,6 +1,6 @@
 import type { ViteUserConfig } from 'astro';
 
-export type VitePlugin = NonNullable<ViteUserConfig['plugins']>[number];
+type VitePlugin = NonNullable<ViteUserConfig['plugins']>[number];
 
 export function buildVirtualModuleString<T extends Record<string, unknown>>(vars: T) {
   return Object.entries(vars)
@@ -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>,
@@ -50,11 +33,3 @@ export function makeAsyncVirtualModPlugin<T extends Record<string, unknown>>(
     },
   };
 }
-
-export function virtualModule(id: string) {
-  return {
-    fromString: (content: string) => makeVirtualModPlugin(id, content),
-    fromObject: <T extends Record<string, unknown>>(content: T) =>
-      makeVirtualModPlugin(id, buildVirtualModuleString(content)),
-  };
-}

package/stl-docs/aiChatExamples.ts

@@ -0,0 +1,31 @@
+import { buildVirtualModuleString } from '../shared/virtualModule';
+import type * as virtualExampleModule from 'virtual:stl-docs-ai-chat-examples';
+type VirtualExampleModule = typeof virtualExampleModule;
+
+export type ExamplePromptResponse = {
+  shortPrompt: string;
+  longPrompt: string;
+  icon: string;
+}[];
+
+export function generateExamplesVirtualModule(exampleOverrides: ExamplePromptResponse | undefined): string {
+  if (!exampleOverrides) {
+    return buildVirtualModuleString({ examples: undefined } satisfies VirtualExampleModule);
+  }
+
+  // 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 = 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(exampleOverrides))};`;
+
+  return [...iconImports, exportBody].join('\n');
+}

package/stl-docs/chat/docs-chat-handler.ts

@@ -0,0 +1,17 @@
+import { ResponseChunk } from './schemas';
+export { responseChunk, type ResponseChunk } from './schemas';
+
+export type DocsChatHandler = {
+  generateResponse: (
+    {
+      query,
+      priorMessages,
+    }: {
+      query: string;
+      priorMessages: { role: 'user' | 'assistant'; content: string }[];
+    },
+    abortSignal: AbortSignal,
+  ) => AsyncGenerator<ResponseChunk>;
+
+  onRate?: (spanId: string, score: 0 | 1) => Promise<unknown>;
+};