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

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @stainless-api/docs
 
+## 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.142",
   "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 { makeFileSystemSDKJSONFilesLoader } from './specs/makeFileSystemSDKJSONFilesLoader';
 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 { defaultSpecLoader } 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 ?? defaultSpecLoader,
     branch: partial.versions?.[0]?.branch ?? 'main',
   };
 

package/plugin/specs/{defaultSpecLoader.ts → defaultSDKJSONLoader.ts}

@@ -1,5 +1,5 @@
 import path from 'path';
-import type { SpecLoaderFn, SpecLoaderParams } from './utils';
+import type { SDKJSONFilesLoaderFn, SDKJSONFilesLoaderParams } from './utils';
 import Stainless, { APIError } from '@stainless-api/sdk';
 import { DocsLanguage } from '@stainless-api/docs-ui/routing';
 import { bold } from '../../shared/terminalUtils';
@@ -44,7 +44,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) {
@@ -133,7 +133,7 @@ async function cleanupDirectory(directory: string, filesToKeep: string[]) {
   };
 }
 
-export const defaultSpecLoader: SpecLoaderFn = async (params) => {
+export const defaultSpecLoader: SDKJSONFilesLoaderFn = async (params) => {
   const { createCodegenDir } = params;
 
   const inputs = await loadInputs(params);
@@ -163,7 +163,7 @@ export const defaultSpecLoader: SpecLoaderFn = async (params) => {
     ];
   }
 
-  const result = await generateSpecFromStrings({
+  const { sdkJson, languages } = await generateSpecFromStrings({
     oasStr: inputs.oasStr,
     configStr: inputs.configStr,
     languageOverrides: {
@@ -174,7 +174,7 @@ export const defaultSpecLoader: SpecLoaderFn = async (params) => {
     stainlessProject: params.stainlessProject,
   });
 
-  await writeFile(filePath, JSON.stringify(result), 'utf8');
+  await writeFile(filePath, JSON.stringify(sdkJson), 'utf8');
   params.logger.info(`Generated: ${fileName}`);
 
   const { deletedCount } = await cleanupDirectory(specsDirectory, [fileName]);
@@ -185,8 +185,8 @@ export const defaultSpecLoader: SpecLoaderFn = async (params) => {
   return [
     {
       filePath,
-      languages: result.languages.filter((language) => language !== 'sql' && language !== 'openapi'),
-      sdkJson: result.sdkJson,
+      languages: languages.filter((language) => language !== 'sql' && language !== 'openapi'),
+      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/makeFileSystemSDKJSONFilesLoader.ts

@@ -0,0 +1,63 @@
+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;
+  };
+}

package/plugin/specs/utils.ts

@@ -5,7 +5,7 @@ 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) => {

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;