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

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @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
+
+- 28bb924: updated API for SDKJSON
+
+### Patch Changes
+
+- 65c8fa0: Uses CSS for sidebar http icons instead of inline svg
+- Updated dependencies [65c8fa0]
+- Updated dependencies [28bb924]
+  - @stainless-api/docs-ui@1.0.0-beta.98
+  - @stainless-api/docs-search@1.0.0-beta.52
+
 ## 1.0.0-beta.141
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "1.0.0-beta.141",
+  "version": "1.0.0-beta.143",
   "publishConfig": {
     "access": "public"
   },
@@ -76,8 +76,8 @@
     "remend": "^1.3.0",
     "shiki": "^4.0.2",
     "unified": "^11.0.5",
-    "@stainless-api/docs-search": "1.0.0-beta.51",
-    "@stainless-api/docs-ui": "1.0.0-beta.97",
+    "@stainless-api/docs-search": "1.0.0-beta.52",
+    "@stainless-api/docs-ui": "1.0.0-beta.98",
     "@stainless-api/ui-primitives": "1.0.0-beta.55",
     "@stainless/sdk-json": "^0.1.0-beta.11"
   },
@@ -92,7 +92,7 @@
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "typescript": "6.0.3",
-    "vite": "^7.3.2",
+    "vite": "^7.3.3",
     "vitest": "^4.1.5",
     "zod": "^4.4.3",
     "@stainless/eslint-config": "0.1.0-beta.2"

package/plugin/index.ts

@@ -39,6 +39,7 @@ import { buildAlgoliaIndex } from './buildAlgoliaIndex';
 import { flatSpecsList, loadAllSpecs, LoadedSpecs } from './specs/utils';
 
 export { generateAPILink } from './generateAPIReferenceLink';
+export { fileSystemSDKJSONLoader } from './specs/fileSystemSDKJSONLoader';
 export type { ReferenceSidebarConfigItem };
 
 config({
@@ -124,7 +125,7 @@ function stlStarlightAstroIntegration(pluginConfig: NormalizedStainlessStarlight
         astroBase = astroConfig.base;
 
         specsPromise = loadAllSpecs(
-          pluginConfig.loadSpecs({
+          pluginConfig.loadSDKJSONFiles({
             stainlessProject: pluginConfig.stainlessProject,
             branch: pluginConfig.branch,
             apiKey: pluginConfig.apiKey?.value ?? null,

package/plugin/loadPluginConfig.ts

@@ -6,8 +6,8 @@ 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/defaultSpecLoader';
-import { SpecLoaderFn } from './specs/utils';
+import { defaultSDKJSONLoader } from './specs/defaultSDKJSONLoader';
+import { SDKJSONFilesLoaderFn as SDKJSONFilesLoaderFn } from './specs/utils';
 
 type ApiKeySource = 'explicit-config' | 'environment-variable' | 'cli';
 
@@ -54,7 +54,7 @@ export type StainlessStarlightUserConfig = {
   /**
    * Optional function to provide your own loader for API reference data.
    */
-  loadSpecs?: SpecLoaderFn;
+  loadSDKJSONFiles?: SDKJSONFilesLoaderFn;
 
   /**
    * Optional list of versions to render in the API reference.
@@ -286,7 +286,7 @@ function normalizeConfig(partial: SomeStainlessStarlightUserConfig, astroOptions
       detailThreshold: partial.llmsTxt?.detailThreshold ?? 2000,
     },
     apiKey: loadApiKey(partial.apiKey),
-    loadSpecs: partial.loadSpecs ?? 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/{defaultSpecLoader.ts → defaultSDKJSONLoader.ts}

@@ -1,11 +1,12 @@
 import path from 'path';
-import type { SpecLoaderFn, SpecLoaderParams } from './utils';
+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) {
@@ -44,7 +45,7 @@ function redactApiKey(apiKey: string) {
     .join('');
 }
 
-async function loadInputs({ apiKey, logger, stainlessProject, branch }: SpecLoaderParams) {
+async function loadInputs({ apiKey, logger, stainlessProject, branch }: SDKJSONFilesLoaderParams) {
   const localFilePaths = getLocalFilePaths();
 
   if (localFilePaths) {
@@ -115,13 +116,11 @@ async function loadInputs({ apiKey, logger, stainlessProject, branch }: SpecLoad
   }
 }
 
-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: SpecLoaderFn = 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: SpecLoaderFn = 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 result = await generateSpecFromStrings({
+  const { sdkJson } = await generateSpecFromStrings({
     oasStr: inputs.oasStr,
     configStr: inputs.configStr,
     languageOverrides: {
@@ -174,9 +181,11 @@ export const defaultSpecLoader: SpecLoaderFn = async (params) => {
     stainlessProject: params.stainlessProject,
   });
 
-  await writeFile(filePath, JSON.stringify(result), '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,8 +194,8 @@ export const defaultSpecLoader: SpecLoaderFn = async (params) => {
   return [
     {
       filePath,
-      languages: result.languages.filter((language) => language !== 'sql' && language !== 'openapi'),
-      sdkJson: result.sdkJson,
+      languages,
+      sdkJson,
     },
   ];
 };

package/plugin/specs/fetchSpecSSR.ts

@@ -1,20 +1,10 @@
 import { readFile } from 'fs/promises';
 
 import { api } from 'virtual:stainless-apis-manifest';
-import type { SpecWithAuth } from '@stainless/sdk-json/spec';
+import { Spec } from '@stainless/sdk-json';
 import { DocsLanguage } from '@stainless-api/docs-ui/routing';
 
-const cachedSpecWithAuth: Record<string, SpecWithAuth> = {};
-
-async function getSpecWithAuthInSSR(filePath: string) {
-  if (cachedSpecWithAuth[filePath]) {
-    return cachedSpecWithAuth[filePath];
-  }
-  const specStr = await readFile(filePath, 'utf8');
-  const json = JSON.parse(specStr) as SpecWithAuth;
-  cachedSpecWithAuth[filePath] = json;
-  return json;
-}
+const cachedSpecs: Record<string, Spec> = {};
 
 export async function getSDKJSONInSSR(language: DocsLanguage) {
   const filePath = api.languages.find((l) => l.language === language)?.sdkJSONFilePath;
@@ -22,6 +12,12 @@ export async function getSDKJSONInSSR(language: DocsLanguage) {
     throw new Error(`No SDK JSON file path for language: ${language}`);
   }
 
-  const specWithAuth = await getSpecWithAuthInSSR(filePath);
-  return specWithAuth.sdkJson;
+  if (cachedSpecs[filePath]) {
+    return cachedSpecs[filePath];
+  }
+  const specStr = await readFile(filePath, 'utf8');
+  const json = JSON.parse(specStr) as Spec;
+  cachedSpecs[filePath] = json;
+
+  return json;
 }

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,11 +1,11 @@
 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';
 
 type PossibleLanguage = NonNullable<NonNullable<NonNullable<Spec['docs']>['languages']>[number]>;
 
-export type SpecLoaderParams = {
+export type SDKJSONFilesLoaderParams = {
   /**
    * The slug of your Stainless project.
    */
@@ -32,7 +32,7 @@ export type SpecLoaderParams = {
   createCodegenDir: () => URL;
 };
 
-type SpecLoaderResult = {
+type SDKJSONFilesLoaderResult = {
   /**
    * 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.
@@ -49,7 +49,7 @@ type SpecLoaderResult = {
   sdkJson?: Spec;
 };
 
-export type SpecLoaderFn = (opts: SpecLoaderParams) => Promise<SpecLoaderResult[]>;
+export type SDKJSONFilesLoaderFn = (opts: SDKJSONFilesLoaderParams) => Promise<SDKJSONFilesLoaderResult[]>;
 
 async function readSpecFromFile(filePath: string) {
   const txt = await readFile(filePath, 'utf8');
@@ -57,7 +57,7 @@ async function readSpecFromFile(filePath: string) {
   return json;
 }
 
-export async function loadAllSpecs(specLoaderResultsPromise: Promise<SpecLoaderResult[]>) {
+export async function loadAllSpecs(specLoaderResultsPromise: Promise<SDKJSONFilesLoaderResult[]>) {
   const specLoaderResults = await specLoaderResultsPromise;
   const specs = await Promise.all(
     specLoaderResults.map(async (result) => {
@@ -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/stl-docs/components/sidebars/convertAstroSidebarToStl.tsx

@@ -1,9 +1,7 @@
 import { StlSidebarEntry } from '@stainless-api/docs-ui/components';
 import { SidebarEntry } from '../pagination/util';
 import { ReactNode } from 'react';
-import { Badge, getHttpMethod } from '@stainless-api/ui-primitives';
-import { FunctionIcon } from '@stainless-api/ui-primitives/icons';
-import { BracesIcon } from 'lucide-react';
+import { getHttpMethod } from '@stainless-api/ui-primitives';
 
 function getIcon(entry: SidebarEntry): ReactNode | undefined {
   if (entry.type !== 'link') {
@@ -11,25 +9,34 @@ function getIcon(entry: SidebarEntry): ReactNode | undefined {
   }
   const methodAttr = entry.attrs['data-stldocs-method'];
   const httpMethod = getHttpMethod(methodAttr);
+  const classes = `stl-ui-badge stl-ui-badge--size-sm stl-sidebar-icon`;
+
   if (httpMethod) {
-    return <Badge.HTTP method={httpMethod} iconOnly size="sm" />;
+    const methodClass = `stl-ui-badge--http-${httpMethod.toLowerCase()}`;
+    return (
+      <span className={`${classes} stl-ui-badge--http ${methodClass}`} role="img" aria-label={httpMethod} />
+    );
   }
 
   // special handling for the webhooks resource overview page
   if (entry.attrs['data-stldocs-overview'] === 'webhooks') {
     return (
-      <Badge size="sm" icon={<BracesIcon />} intent="info">
-        {''}
-      </Badge>
+      <span
+        className={`${classes} stl-ui-badge--intent-info stl-sidebar-icon--braces`}
+        role="img"
+        aria-label="Webhook"
+      />
     );
   }
 
   // Support empty string as method to show generic "Function" badge
   else if (methodAttr === '') {
     return (
-      <Badge size="sm" icon={<FunctionIcon />} intent="info">
-        {''}
-      </Badge>
+      <span
+        className={`${classes} stl-ui-badge--intent-info stl-sidebar-icon--function`}
+        role="img"
+        aria-label="Method"
+      />
     );
   }
   return undefined;