@stainless-api/docs 1.0.0-beta.142 → 1.0.0-beta.143

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @stainless-api/docs
 
+## 1.0.0-beta.143
+
+### Minor Changes
+
+- d358f02: Bugfix
+- d358f02: Bug fixes + new API to override package versions etc.
+
 ## 1.0.0-beta.142
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "1.0.0-beta.142",
+  "version": "1.0.0-beta.143",
   "publishConfig": {
     "access": "public"
   },

package/plugin/index.ts

@@ -39,7 +39,7 @@ import { buildAlgoliaIndex } from './buildAlgoliaIndex';
 import { flatSpecsList, loadAllSpecs, LoadedSpecs } from './specs/utils';
 
 export { generateAPILink } from './generateAPIReferenceLink';
-export { makeFileSystemSDKJSONFilesLoader } from './specs/makeFileSystemSDKJSONFilesLoader';
+export { fileSystemSDKJSONLoader } from './specs/fileSystemSDKJSONLoader';
 export type { ReferenceSidebarConfigItem };
 
 config({

package/plugin/loadPluginConfig.ts

@@ -6,7 +6,7 @@ import type { CreateShikiHighlighterOptions } from '@astrojs/markdown-remark';
 import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
 import type { PropertySettingsType } from '@stainless-api/docs-ui/contexts';
 
-import { defaultSpecLoader } from './specs/defaultSDKJSONLoader';
+import { defaultSDKJSONLoader } from './specs/defaultSDKJSONLoader';
 import { SDKJSONFilesLoaderFn as SDKJSONFilesLoaderFn } from './specs/utils';
 
 type ApiKeySource = 'explicit-config' | 'environment-variable' | 'cli';
@@ -286,7 +286,7 @@ function normalizeConfig(partial: SomeStainlessStarlightUserConfig, astroOptions
       detailThreshold: partial.llmsTxt?.detailThreshold ?? 2000,
     },
     apiKey: loadApiKey(partial.apiKey),
-    loadSDKJSONFiles: partial.loadSDKJSONFiles ?? defaultSpecLoader,
+    loadSDKJSONFiles: partial.loadSDKJSONFiles ?? defaultSDKJSONLoader,
     branch: partial.versions?.[0]?.branch ?? 'main',
   };
 

package/plugin/react/Routing.tsx

@@ -128,7 +128,6 @@ export type SpecMetadata = [
   {
     repo_url?: string;
     code_url?: string;
-    package_title?: string;
     version?: string;
     install?: string;
   },

package/plugin/specs/defaultSDKJSONLoader.ts

@@ -1,11 +1,12 @@
 import path from 'path';
 import type { SDKJSONFilesLoaderFn, SDKJSONFilesLoaderParams } from './utils';
+import { sdkJSONCacheReaderWriter } from './utils';
 import Stainless, { APIError } from '@stainless-api/sdk';
-import { DocsLanguage } from '@stainless-api/docs-ui/routing';
+import { DocsLanguage, isSupportedLanguage } from '@stainless-api/docs-ui/routing';
 import { bold } from '../../shared/terminalUtils';
-import { mkdir, readdir, readFile, rm, writeFile } from 'fs/promises';
+import { mkdir, readdir, readFile, rm } from 'fs/promises';
 import { generateSpecFromStrings, previewWorkerCode } from '@stainless/sdk-json/spec';
-import { Spec, SpecLanguage } from '@stainless/sdk-json';
+import { Spec } from '@stainless/sdk-json';
 import crypto from 'crypto';
 
 function resolvePath(inputPath: string) {
@@ -115,13 +116,11 @@ async function loadInputs({ apiKey, logger, stainlessProject, branch }: SDKJSONF
   }
 }
 
-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;
+function getLanguagesFromSDKJSON(spec: Spec) {
+  if (spec.docs?.languages) {
+    return spec.docs.languages;
   }
+  return Object.keys(spec.decls).filter(isSupportedLanguage);
 }
 
 async function cleanupDirectory(directory: string, filesToKeep: string[]) {
@@ -133,12 +132,12 @@ async function cleanupDirectory(directory: string, filesToKeep: string[]) {
   };
 }
 
-export const defaultSpecLoader: SDKJSONFilesLoaderFn = async (params) => {
+export const defaultSDKJSONLoader: SDKJSONFilesLoaderFn = async (params) => {
   const { createCodegenDir } = params;
 
   const inputs = await loadInputs(params);
 
-  const specsDirectory = path.join(createCodegenDir().pathname, 'specs2');
+  const specsDirectory = path.join(createCodegenDir().pathname, 'sdk_json_cache');
   await mkdir(specsDirectory, { recursive: true });
 
   const fileName =
@@ -150,20 +149,28 @@ export const defaultSpecLoader: SDKJSONFilesLoaderFn = async (params) => {
 
   const filePath = path.join(specsDirectory, fileName);
 
-  const cachedSpec = await maybeLoadJSONFile<{ languages: SpecLanguage[]; sdkJson: Spec }>(filePath);
+  const cachedSpec = await (async () => {
+    try {
+      return await sdkJSONCacheReaderWriter.readFile(filePath);
+    } catch {
+      return null;
+    }
+  })();
+
   // skip generation since we already have a cached spec
   if (cachedSpec) {
+    const languages = getLanguagesFromSDKJSON(cachedSpec);
     params.logger.info(`Loaded cached spec: ${fileName}`);
     return [
       {
         filePath,
-        languages: cachedSpec.languages,
-        sdkJson: cachedSpec.sdkJson,
+        languages,
+        sdkJson: cachedSpec,
       },
     ];
   }
 
-  const { sdkJson, languages } = await generateSpecFromStrings({
+  const { sdkJson } = await generateSpecFromStrings({
     oasStr: inputs.oasStr,
     configStr: inputs.configStr,
     languageOverrides: {
@@ -174,9 +181,11 @@ export const defaultSpecLoader: SDKJSONFilesLoaderFn = async (params) => {
     stainlessProject: params.stainlessProject,
   });
 
-  await writeFile(filePath, JSON.stringify(sdkJson), 'utf8');
-  params.logger.info(`Generated: ${fileName}`);
+  const languages = getLanguagesFromSDKJSON(sdkJson);
 
+  await sdkJSONCacheReaderWriter.writeFile(filePath, sdkJson);
+
+  params.logger.info(`Generated: ${fileName}`);
   const { deletedCount } = await cleanupDirectory(specsDirectory, [fileName]);
   if (deletedCount > 0) {
     params.logger.info(`Cleaned up ${deletedCount} unused spec file(s)`);
@@ -185,7 +194,7 @@ export const defaultSpecLoader: SDKJSONFilesLoaderFn = async (params) => {
   return [
     {
       filePath,
-      languages: languages.filter((language) => language !== 'sql' && language !== 'openapi'),
+      languages,
       sdkJson,
     },
   ];

package/plugin/specs/fileSystemSDKJSONLoader.ts

@@ -0,0 +1,126 @@
+import { Spec, SpecLanguage } from '@stainless/sdk-json';
+import { SDKJSONFilesLoaderFn, SDKJSONFilesLoaderParams, sdkJSONCacheReaderWriter } from './utils';
+import { mkdir, readFile } from 'fs/promises';
+import path from 'path';
+import { generateSpecFromStrings } from '@stainless/sdk-json/spec';
+
+interface GenerateSDKJSONOptions {
+  /** Raw OpenAPI spec contents (JSON or YAML). */
+  spec: string;
+  /** Raw Stainless config contents (YAML). */
+  config: string;
+  /** Language to build the SDK JSON spec for. */
+  language: SpecLanguage;
+  /** The name of the project. */
+  stainlessProject: string;
+}
+
+type GenerateSDKJSONFn<T> = (options: GenerateSDKJSONOptions) => Promise<{ spec: T }>;
+
+type NonHttpSpecLanguage = Exclude<SpecLanguage, 'http'>;
+
+type LibraryInformationOverride = Partial<{
+  [key in NonHttpSpecLanguage]: {
+    repo_url?: string;
+    code_url?: string;
+    version?: string;
+    install?: string;
+  };
+}>;
+
+type FileSystemSpecLoaderParams<T> = {
+  /**
+   * The path to the OpenAPI spec file.
+   *
+   */
+  specPath: string;
+  /**
+   * The path to your Stainless config file.
+   */
+  configFilePath: string;
+  /**
+   * The function used to generate your SDKJSON.
+   */
+  generateSDKJSON?: GenerateSDKJSONFn<T>;
+  /**
+   * The languages for which you want to render documentation.
+   */
+  languages: SpecLanguage[];
+  /**
+   * A key:value map of languages to overrides. Used to manually set things like the install command or SDK version.
+   */
+  override?: LibraryInformationOverride;
+};
+
+const defaultGenerateSDKJSON: GenerateSDKJSONFn<Spec> = async ({
+  config,
+  spec,
+  language,
+  stainlessProject,
+}) => {
+  const { sdkJson } = await generateSpecFromStrings({
+    oasStr: spec,
+    configStr: config,
+    languageOverrides: {
+      mode: 'only',
+      list: [language],
+    },
+    versionInfo: null,
+    stainlessProject,
+  });
+
+  return { spec: sdkJson };
+};
+
+export function fileSystemSDKJSONLoader<T>({
+  specPath,
+  configFilePath,
+  generateSDKJSON,
+  languages,
+  override,
+}: FileSystemSpecLoaderParams<T>): SDKJSONFilesLoaderFn {
+  const generateFn = generateSDKJSON ?? defaultGenerateSDKJSON;
+  return async function fileSystemSpecLoader(opts: SDKJSONFilesLoaderParams) {
+    const { createCodegenDir, logger } = opts;
+    const [spec, config] = await Promise.all([readFile(specPath, 'utf8'), readFile(configFilePath, 'utf8')]);
+
+    const specsDirectory = path.join(createCodegenDir().pathname, 'fs_spec_loader_specs');
+    await mkdir(specsDirectory, { recursive: true });
+
+    const r = languages.map(async (language) => {
+      const generateResult = await generateFn({
+        spec,
+        config,
+        language,
+        stainlessProject: opts.stainlessProject,
+      });
+
+      // type casting here is a little weird
+      // it prevents type errors from slightly incompatible SDKJSON types (since generateSDKJSON comes from the user)
+      const sdkJson = generateResult.spec as unknown as Spec;
+
+      if (override && language !== 'http' && override[language]) {
+        sdkJson.metadata[language] = {
+          ...sdkJson.metadata[language],
+          ...override[language],
+        };
+      }
+
+      const filePath = path.join(specsDirectory, `${language}.json`);
+
+      await sdkJSONCacheReaderWriter.writeFile(filePath, sdkJson);
+
+      logger.info(`Loaded SDKJSON for ${language} to ${filePath}`);
+
+      return {
+        filePath: filePath,
+        languages: [language],
+        sdkJson,
+      };
+    });
+
+    const results = await Promise.all(r);
+
+    return results;
+  };
+}

package/plugin/specs/utils.ts

@@ -1,5 +1,5 @@
 import { Spec } from '@stainless/sdk-json';
-import { readFile } from 'fs/promises';
+import { readFile, writeFile } from 'fs/promises';
 import { DocsLanguage } from '@stainless-api/docs-ui/routing';
 import { AstroIntegrationLogger } from 'astro';
 
@@ -84,3 +84,17 @@ export function flatSpecsList(specs: LoadedSpecs) {
     )
     .flat();
 }
+
+function typedReaderWriter<T>() {
+  return {
+    async readFile(filePath: string) {
+      const fileContents = await readFile(filePath, 'utf8');
+      return JSON.parse(fileContents) as T;
+    },
+    async writeFile(filePath: string, data: T) {
+      await writeFile(filePath, JSON.stringify(data), 'utf8');
+    },
+  };
+}
+
+export const sdkJSONCacheReaderWriter = typedReaderWriter<Spec>();

package/plugin/specs/makeFileSystemSDKJSONFilesLoader.ts

@@ -1,63 +0,0 @@
-import { Spec, SpecLanguage } from '@stainless/sdk-json';
-import { SDKJSONFilesLoaderFn, SDKJSONFilesLoaderParams } from './utils';
-import { mkdir, readFile, writeFile } from 'fs/promises';
-import path from 'path';
-
-interface GenerateSDKJSONOptions {
-  /** Raw OpenAPI spec contents (JSON or YAML). */
-  spec: string;
-  /** Raw Stainless config contents (YAML). */
-  config: string;
-  /** Language to build the SDK JSON spec for. */
-  language: SpecLanguage;
-}
-
-type GenerateSDKJSONFn<T> = (options: GenerateSDKJSONOptions) => Promise<T>;
-
-type FileSystemSpecLoaderParams<T> = {
-  specPath: string;
-  configFilePath: string;
-  generateSDKJSON: GenerateSDKJSONFn<T>;
-  languages: SpecLanguage[];
-};
-
-export function makeFileSystemSDKJSONFilesLoader<T>({
-  specPath,
-  configFilePath,
-  generateSDKJSON,
-  languages,
-}: FileSystemSpecLoaderParams<T>): SDKJSONFilesLoaderFn {
-  return async function fileSystemSpecLoader(opts: SDKJSONFilesLoaderParams) {
-    const { createCodegenDir, logger } = opts;
-    const [spec, config] = await Promise.all([readFile(specPath, 'utf8'), readFile(configFilePath, 'utf8')]);
-
-    const specsDirectory = path.join(createCodegenDir().pathname, 'fsSpecLoaderSpecs');
-    await mkdir(specsDirectory, { recursive: true });
-
-    const r = languages.map(async (language) => {
-      // type casting here is a little weird
-      // it prevents type errors from slightly incompatible SDKJSON types (since generateSDKJSON comes from the user)
-      const sdkJson = (await generateSDKJSON({
-        spec,
-        config,
-        language,
-      })) as unknown as Spec;
-
-      const filePath = path.join(specsDirectory, `${language}.json`);
-
-      await writeFile(filePath, JSON.stringify(sdkJson));
-
-      logger.info(`Loaded SDKJSON for ${language} to ${filePath}`);
-
-      return {
-        filePath: filePath,
-        languages: [language],
-        sdkJson,
-      };
-    });
-
-    const results = await Promise.all(r);
-
-    return results;
-  };
-}