@stainless-api/docs 0.1.0-beta.92 → 0.1.0-beta.94

package/plugin/specs/index.ts

@@ -1,202 +1,77 @@
-import Stainless, { APIError } from '@stainless-api/sdk';
-import { mkdir, readdir, readFile, rm, writeFile } from 'fs/promises';
+import { mkdir } from 'fs/promises';
 import path from 'path';
-import crypto from 'crypto';
 
-import type * as VirtualManifestModule from 'virtual:stainless-sdk-json-manifest';
+import type * as VirtualManifestModule from 'virtual:stainless-apis-manifest';
 
 import { makeAsyncVirtualModPlugin } from '../../shared/virtualModule';
 
-import { NormalizedStainlessStarlightConfig, SDKJSONInputs } from '../loadPluginConfig';
+import { NormalizedStainlessStarlightConfig, ResolvedAPIConfigEntry } from '../loadPluginConfig';
 
-import { generateSpecFromStrings, SpecWithAuth } from './generateSpec';
-import previewWorkerCode from '../vendor/preview.worker.docs.js?raw';
-import { DocsLanguage } from '@stainless-api/docs-ui/routing';
+import { specCache, SpecCacheResult } from './generateSpec';
 import { AstroIntegrationLogger } from 'astro';
-import { bold } from '../../shared/terminalUtils';
-
-type VirtualManifestModuleType = typeof VirtualManifestModule;
-
-async function cleanupSpecsDirectory({
-  directory,
-  keep,
-  logger,
-}: {
-  directory: string;
-  keep: string[];
-  logger: AstroIntegrationLogger;
-}) {
-  const files = await readdir(directory);
-  const filesToDelete = files.filter((file) => !keep.includes(file));
-
-  if (filesToDelete.length > 0) {
-    await Promise.all(filesToDelete.map((file) => rm(path.join(directory, file))));
-    logger.info(`Removed ${filesToDelete.length} unused SDKJSON file(s)`);
-  }
-}
+import type * as SDKJSON from '@stainless/sdk-json';
 
-type ResolvedSpecInputs = {
-  oasStr: string;
-  configStr: string;
-  versions: Record<DocsLanguage, string> | null;
-  project: string;
+export type LoadedAPIConfigEntry = Omit<ResolvedAPIConfigEntry, 'loadSpecs'> & {
+  specs: SpecCacheResult[];
+  languages: SDKJSON.SpecLanguage[];
 };
 
-async function versionInfo(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 resolveFileInputs(
-  inputs: Extract<SDKJSONInputs, { kind: 'file_inputs' }>,
-  logger: AstroIntegrationLogger,
-) {
-  try {
-    const oasStr = await readFile(inputs.oasPath, 'utf8');
-    const configStr = await readFile(inputs.configPath, 'utf8');
-    return {
-      inputs,
-      resolved: {
-        oasStr,
-        configStr,
-        versions: null,
-        project: inputs.project,
-      },
-    };
-  } catch (error) {
-    logger.error(bold('Failed to read file inputs:'));
-    logger.error(error instanceof Error ? error.message : 'Unknown error');
-    process.exit(1);
+/**
+ * A helper class to manage multiple spec cache results for a single API
+ * An API may have multiple spec cache results if it has multiple languages
+ * Note that one spec may contain multiple languages.
+ * */
+export class SpecComposite {
+  private languages: Set<SDKJSON.SpecLanguage>;
+  private readonly specs: Partial<Record<SDKJSON.SpecLanguage, SpecCacheResult>>;
+
+  public getLanguages() {
+    return Array.from(this.languages);
   }
-}
 
-async function resolveStainlessApiInputs(
-  inputs: Extract<SDKJSONInputs, { kind: 'stainless_api_inputs' }>,
-  logger: AstroIntegrationLogger,
-) {
-  try {
-    const client = new Stainless({ apiKey: inputs.apiKey.value });
-    const configs = await client.projects.configs.retrieve({
-      project: inputs.project,
-      branch: inputs.branch,
-      include: 'openapi',
-    });
-    const versions = await versionInfo(inputs.project, inputs.apiKey.value);
-
-    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') {
-      throw new Error('Received invalid OAS or config from Stainless');
-    }
-
-    return {
-      inputs,
-      resolved: {
-        versions,
-        oasStr,
-        configStr,
-        project: inputs.project,
-      },
-    };
-  } catch (error) {
-    logger.error(bold('Failed to fetch API reference information from Stainless:'));
-    if (error instanceof APIError && error.status >= 400 && error.status < 500) {
-      logger.error(`Requested project slug: "${inputs.project}"`);
-      logger.error(`API key: "${redactApiKey(inputs.apiKey.value)}"`);
-      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.`,
-      );
-    } else {
-      logger.error(error instanceof Error ? error.message : 'Unknown error');
+  public getByLanguage(language: SDKJSON.SpecLanguage) {
+    const spec = this.specs[language];
+    if (!spec) {
+      throw new Error(`Spec for language ${language} not found`);
     }
-
-    process.exit(1);
+    return spec;
   }
-}
-
-async function resolveStringInputs(inputs: Extract<SDKJSONInputs, { kind: 'string_inputs' }>) {
-  return {
-    inputs,
-    resolved: {
-      oasStr: inputs.oasStr,
-      configStr: inputs.configStr,
-      versions: null,
-      project: inputs.project,
-    },
-  };
-}
-
-async function resolveSpecInputs(
-  inputs: SDKJSONInputs,
-  logger: AstroIntegrationLogger,
-): Promise<{ inputs: SDKJSONInputs; resolved: ResolvedSpecInputs }> {
-  if (inputs.kind === 'file_inputs') return resolveFileInputs(inputs, logger);
-  if (inputs.kind === 'stainless_api_inputs') return resolveStainlessApiInputs(inputs, logger);
-  if (inputs.kind === 'string_inputs') return resolveStringInputs(inputs);
-  throw new Error(`Unexpected spec inputs: ${JSON.stringify(inputs)}`);
-}
 
-function hashResolvedSpecInputs(resolved: ResolvedSpecInputs): string {
-  return crypto
-    .createHash('sha256')
-    .update(resolved.oasStr + resolved.configStr + JSON.stringify(resolved.versions) + previewWorkerCode)
-    .digest('hex')
-    .slice(0, 10);
-}
-
-async function readCachedSpec(specPath: string): Promise<SpecWithAuth | null> {
-  try {
-    const cachedSpec = await readFile(specPath, 'utf8');
-    return JSON.parse(cachedSpec) as SpecWithAuth;
-  } catch {
-    return null;
+  /**
+   * Returns all specs. It will return each spec once, even if it has multiple languages.
+   * */
+  public listUniqueSpecs() {
+    const seen = new Set<SpecCacheResult>();
+    const unique: SpecCacheResult[] = [];
+    for (const spec of Object.values(this.specs)) {
+      if (!seen.has(spec)) {
+        seen.add(spec);
+        unique.push(spec);
+      }
+    }
+    return unique;
   }
-}
 
-async function fetchOrGenerateSpec(specPath: string, inputs: ResolvedSpecInputs) {
-  const cachedSpec = await readCachedSpec(specPath);
-  if (cachedSpec) {
-    return {
-      result: 'exists' as const,
-      specPath,
-      spec: cachedSpec,
-    };
+  public listAllLanguagesAndIncludeSpecs() {
+    return this.getLanguages().map((language) => ({
+      language,
+      spec: this.getByLanguage(language),
+    }));
   }
 
-  const sdkJson = await generateSpecFromStrings({
-    oasStr: inputs.oasStr,
-    configStr: inputs.configStr,
-    projectName: inputs.project,
-  });
-
-  if (inputs.versions) {
-    for (const [lang, version] of Object.entries(inputs.versions)) {
-      const meta = sdkJson.data.metadata[lang as DocsLanguage];
-      if (meta?.version) meta.version = version;
+  constructor(specs: SpecCacheResult[]) {
+    this.languages = new Set<SDKJSON.SpecLanguage>();
+    this.specs = {};
+    for (const spec of specs) {
+      for (const lang of spec.data.languages) {
+        if (this.languages.has(lang)) {
+          throw new Error(`Language appears multiple times in the same API: ${lang}`);
+        }
+        this.languages.add(lang);
+        this.specs[lang] = spec;
+      }
     }
   }
-
-  await writeFile(specPath, JSON.stringify(sdkJson), 'utf8');
-
-  return {
-    result: 'generated' as const,
-    spec: sdkJson,
-    specPath,
-  };
 }
 
 /** Runs once in the build process */
@@ -207,31 +82,49 @@ export async function startSpecLoader(
 ) {
   const specsDirectory = path.join(codegenDir.pathname, 'specs');
   await mkdir(specsDirectory, { recursive: true });
-  // TODO: can this promise also be deferred until after this function resolves? can this whole
-  // function return synchronously?
-  // TODO: arena to remember the conceptual reason why he didn’t want this
-  const resolvedSpecInputs = await resolveSpecInputs(pluginConfig.specInputs, logger);
 
-  const inputsHash = hashResolvedSpecInputs(resolvedSpecInputs.resolved);
-  const specFileName = `${inputsHash}.json`;
-  const specPath = path.join(specsDirectory, specFileName);
+  logger.debug(`Setting cache directory to ${specsDirectory}`);
+
+  // 🚨 Important! You cannot call loadSpecs() before setting the cache directory.
+  specCache.setCacheDirectory(specsDirectory);
 
-  const specPromise = fetchOrGenerateSpec(specPath, resolvedSpecInputs.resolved);
+  async function load() {
+    const specs = await pluginConfig.api.loadSpecs();
+
+    // not awaited since it's just cleanup
+    specCache.cleanupUnusedFiles().then((result) => {
+      if (result.deletedCount > 0) {
+        logger.info(`Cleaned up ${result.deletedCount} unused spec files`);
+      } else {
+        logger.debug(`No unused spec files to clean up`);
+      }
+    });
+
+    return {
+      specComposite: new SpecComposite(specs),
+    };
+  }
 
-  // don't need to await, it's just cleanup
-  cleanupSpecsDirectory({ directory: specsDirectory, keep: [specFileName], logger });
+  const specPromise = load();
 
   return {
     specPromise,
     // this virtual module only resolves when the spec is generated
     // this prevents the SSR module from trying to read the spec file before it's generated
-    vitePlugin: makeAsyncVirtualModPlugin<VirtualManifestModuleType>(
-      'virtual:stainless-sdk-json-manifest',
-      async () => {
-        const specResult = await specPromise;
-        return { specPath: specResult.specPath };
-      },
-    ),
+    vitePlugins: [
+      makeAsyncVirtualModPlugin<typeof VirtualManifestModule>('virtual:stainless-apis-manifest', async () => {
+        const api = await specPromise;
+
+        return {
+          api: {
+            languages: api.specComposite.listAllLanguagesAndIncludeSpecs().map((langSpec) => ({
+              language: langSpec.language,
+              sdkJSONFilePath: langSpec.spec.filePath,
+            })),
+          },
+        };
+      }),
+    ],
   };
 }
 

package/plugin/specs/inputResolver.ts

@@ -0,0 +1,146 @@
+import { DocsLanguage } from '@stainless-api/docs-ui/routing';
+import { readFile } from 'fs/promises';
+import { AstroIntegrationLogger } from 'astro';
+import { bold } from '../../shared/terminalUtils';
+import type { LanguageGenerateQuery, LoadedApiKey } from '../loadPluginConfig';
+import Stainless, { APIError } from '@stainless-api/sdk';
+import { GenerateSpecRawInputs } from './generateSpec';
+
+export type SpecInputResolver = {
+  resolve: (context: { apiKey: LoadedApiKey | null }) => Promise<GenerateSpecRawInputs>;
+  printError: (error: Error, logger: AstroIntegrationLogger) => void;
+};
+
+function fromFiles({
+  oasPath,
+  configPath,
+  languageOverrides,
+  stainlessProject,
+}: {
+  oasPath: string;
+  configPath: string;
+  languageOverrides: LanguageGenerateQuery | null;
+  stainlessProject: string;
+}): SpecInputResolver {
+  return {
+    resolve: async () => {
+      const oasStr = await readFile(oasPath, 'utf8');
+      const configStr = await readFile(configPath, 'utf8');
+      return {
+        oasStr,
+        configStr,
+        versionInfo: null,
+        languageOverrides,
+        stainlessProject,
+      };
+    },
+    printError: (error: Error, logger: AstroIntegrationLogger) => {
+      logger.error(bold('Failed to resolve spec inputs from files:'));
+      logger.error(error.message);
+    },
+  };
+}
+
+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('');
+}
+
+function fromStainlessApi(inputs: {
+  stainlessProject: string;
+  branch: string;
+  apiKey?: LoadedApiKey;
+  languageOverrides: LanguageGenerateQuery | null;
+}): SpecInputResolver {
+  let apiKey: string | undefined;
+  return {
+    async resolve(context) {
+      apiKey = context.apiKey?.value ?? inputs.apiKey?.value;
+
+      if (!apiKey) {
+        throw new Error('No API key provided');
+      }
+
+      const client = new Stainless({ apiKey });
+      const configs = await client.projects.configs.retrieve({
+        project: inputs.stainlessProject,
+        branch: inputs.branch,
+        include: 'openapi',
+      });
+      const versionInfo = await fetchVersionInfo(inputs.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') {
+        throw new Error('Received invalid OAS or config from Stainless');
+      }
+
+      return {
+        oasStr,
+        configStr,
+        versionInfo,
+        languageOverrides: inputs.languageOverrides,
+        stainlessProject: inputs.stainlessProject,
+      };
+    },
+    printError: (error: Error, logger: AstroIntegrationLogger) => {
+      if (error instanceof APIError && error.status >= 400 && error.status < 500) {
+        logger.error(`Requested project slug: "${inputs.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.`,
+        );
+      }
+    },
+  };
+}
+
+function fromStrings({
+  oasStr,
+  configStr,
+  languageOverrides,
+  stainlessProject,
+}: {
+  oasStr: string;
+  configStr: string;
+  languageOverrides: LanguageGenerateQuery | null;
+  stainlessProject: string;
+}): SpecInputResolver {
+  return {
+    async resolve() {
+      return {
+        oasStr,
+        configStr,
+        versionInfo: null,
+        languageOverrides,
+        stainlessProject,
+      };
+    },
+    printError(error: Error, logger: AstroIntegrationLogger) {
+      logger.error(bold('Failed to resolve spec inputs from strings:'));
+      logger.error(error.message);
+    },
+  };
+}
+
+export const resolveSpec = {
+  fromFiles,
+  fromStainlessApi,
+  fromStrings,
+} satisfies Record<string, (...args: never[]) => SpecInputResolver>;

package/virtual-module.d.ts

@@ -73,12 +73,28 @@ declare module 'virtual:stl-docs/components/AiChat.tsx' {
   export const STAINLESS_PROJECT: string | undefined;
 }
 
-declare module 'virtual:stainless-sdk-json-manifest' {
-  export const specPath: string;
+declare module 'virtual:stainless-apis-manifest' {
+  import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
+
+  export type APIManifestEntry = {
+    languages: {
+      sdkJSONFilePath: string;
+      language: DocsLanguage;
+    }[];
+  };
+
+  export const api: APIManifestEntry;
 }
 
 declare module 'virtual:stl-starlight-reference-sidebars' {
   import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
   import type { StarlightRouteData } from '@astrojs/starlight/route-data';
-  export const sidebars: { id: number; language: DocsLanguage; entries: StarlightRouteData['sidebar'] }[];
+
+  export type GeneratedSidebarDef = {
+    id: number;
+    language: DocsLanguage;
+    entries: StarlightRouteData['sidebar'];
+  };
+
+  export const sidebars: GeneratedSidebarDef[];
 }

package/plugin/helpers/getDocsLanguages.ts

@@ -1,9 +0,0 @@
-import { DocsLanguage } from '@stainless-api/docs-ui/routing';
-import type * as SDKJSON from '@stainless/sdk-json';
-
-export function getDocsLanguages(spec: SDKJSON.Spec, excludeLanguages: DocsLanguage[]) {
-  // TODO: should not force unwrap this
-  const languages: DocsLanguage[] = spec.docs!.languages ?? ['http'];
-
-  return languages.filter((language) => !excludeLanguages.includes(language));
-}