@stainless-api/docs 0.1.0-beta.87 → 0.1.0-beta.89

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @stainless-api/docs
 
+## 0.1.0-beta.89
+
+### Minor Changes
+
+- 4b2bd1c: Adds Webhook events overview page
+
+### Patch Changes
+
+- 7bda782: fix bug when detecting current sidebar item
+- de83f02: fix api reference base path
+- 31457f3: support for setting custom fonts
+- Updated dependencies [31457f3]
+  - @stainless-api/ui-primitives@0.1.0-beta.47
+  - @stainless-api/docs-search@0.1.0-beta.20
+  - @stainless-api/docs-ui@0.1.0-beta.67
+
+## 0.1.0-beta.88
+
+### Minor Changes
+
+- c1fb4e5: remove CMS server; refactor and simplify spec generation pipeline
+
+### Patch Changes
+
+- Updated dependencies [65a1c9b]
+- Updated dependencies [4f1cee7]
+- Updated dependencies [4c72a83]
+- Updated dependencies [068469b]
+  - @stainless-api/docs-ui@0.1.0-beta.66
+  - @stainless-api/docs-search@0.1.0-beta.19
+
 ## 0.1.0-beta.87
 
 ### Patch Changes

package/eslint-suppressions.json

@@ -4,26 +4,6 @@
       "count": 2
     }
   },
-  "plugin/cms/client.ts": {
-    "@typescript-eslint/no-explicit-any": {
-      "count": 1
-    }
-  },
-  "plugin/cms/server.ts": {
-    "@typescript-eslint/no-explicit-any": {
-      "count": 3
-    }
-  },
-  "plugin/cms/sidebar-builder.ts": {
-    "@typescript-eslint/no-explicit-any": {
-      "count": 1
-    }
-  },
-  "plugin/cms/worker.ts": {
-    "@typescript-eslint/no-explicit-any": {
-      "count": 3
-    }
-  },
   "plugin/components/SnippetCode.tsx": {
     "@typescript-eslint/no-explicit-any": {
       "count": 1
@@ -44,9 +24,9 @@
       "count": 1
     }
   },
-  "shared/virtualModule.ts": {
+  "plugin/specs/worker.ts": {
     "@typescript-eslint/no-explicit-any": {
-      "count": 1
+      "count": 3
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "0.1.0-beta.87",
+  "version": "0.1.0-beta.89",
   "publishConfig": {
     "access": "public"
   },
@@ -14,11 +14,10 @@
     "./plugin/languages": "./plugin/languages.ts",
     "./stainless-docs/mintlify-compat": "./stl-docs/components/mintlify-compat/index.ts",
     "./mintlify-compat.css": "./styles/mintlify-compat.css",
-    "./font-imports": "./styles/fonts.css",
     "./components": "./stl-docs/components/index.ts",
     "./components/scripts": "./stl-docs/components/scripts.ts",
     "./docs-config": "./stl-docs/loadStlDocsConfig.ts",
-    "./cms-client": "./plugin/cms/client.ts",
+    "./specs/fetchSpecSSR": "./plugin/specs/fetchSpecSSR.ts",
     "./generate-docs-routes": "./plugin/helpers/generateDocsRoutes.ts",
     "./components/Head": "./stl-docs/components/Head.astro",
     "./components/ContentBreadcrumbs": "./stl-docs/components/ContentBreadcrumbs.tsx"
@@ -44,7 +43,6 @@
     "cheerio": "^1.1.2",
     "clsx": "^2.1.1",
     "dotenv": "17.2.3",
-    "get-port": "^7.1.0",
     "lucide-react": "^0.562.0",
     "marked": "^17.0.1",
     "node-html-parser": "^7.0.1",
@@ -58,9 +56,9 @@
     "vite-plugin-prebundle-workers": "^0.2.0",
     "web-worker": "^1.5.0",
     "yaml": "^2.8.2",
-    "@stainless-api/docs-search": "0.1.0-beta.18",
-    "@stainless-api/docs-ui": "0.1.0-beta.65",
-    "@stainless-api/ui-primitives": "0.1.0-beta.46"
+    "@stainless-api/docs-search": "0.1.0-beta.20",
+    "@stainless-api/docs-ui": "0.1.0-beta.67",
+    "@stainless-api/ui-primitives": "0.1.0-beta.47"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.6",

package/playground-virtual-modules.d.ts

@@ -0,0 +1,96 @@
+declare module 'virtual:stl-playground/typescript.json' {
+  const data: {
+    links: [string, string][];
+    files: [string, string][];
+  } | null;
+  export { data as default };
+}
+declare module 'virtual:stl-playground/python.json' {
+  const data: { files: Record<string, string>; wheel: string } | null;
+  export { data as default };
+}
+declare module 'virtual:stl-playground/auth.json' {
+  const data:
+    | ({
+        type: 'http_bearer' | 'query' | 'header' | 'oauth2' | 'http_basic' | 'http_digest';
+        description?: string;
+        name: string;
+        title: string;
+        header: string | undefined;
+        example: string | undefined;
+      } & {
+        opts: {
+          name: string;
+          type: 'string' | 'number' | 'boolean' | 'null' | 'integer';
+          nullable: boolean;
+          description?: string | undefined;
+          example?: unknown;
+          default?: unknown;
+          read_env?: string | undefined;
+          auth?:
+            | {
+                security_scheme: string;
+                role?: 'value' | 'password' | 'username' | 'client_id' | 'client_secret' | undefined;
+              }
+            | undefined;
+        }[];
+      })[]
+    | null;
+  export { data as default };
+}
+declare module 'virtual:stl-playground/data' {
+  import type { Config } from 'virtual:stl-playground/create';
+  declare const data: Config;
+  export { data as default };
+}
+declare module 'virtual:stl-playground/create' {
+  export type PlaygroundLanguage = 'python' | 'typescript' | 'http';
+  export type Config = {
+    wheelUrl: string;
+    pyTypes: {
+      files: Record<string, string>;
+      wheel: string;
+    } | null;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    HIGHLIGHT_THEMES: any;
+    tsTypes: {
+      links: [string, string][];
+      files: [string, string][];
+    } | null;
+    authData:
+      | ({
+          type: 'http_bearer' | 'query' | 'header' | 'oauth2' | 'http_basic' | 'http_digest';
+          description?: string;
+          name: string;
+          title: string;
+          header: string | undefined;
+          example: string | undefined;
+        } & {
+          opts: {
+            name: string;
+            type: 'string' | 'number' | 'boolean' | 'null' | 'integer';
+            nullable: boolean;
+            description?: string | undefined;
+            example?: unknown;
+            default?: unknown;
+            read_env?: string | undefined;
+            auth?:
+              | {
+                  security_scheme: string;
+                  role?: 'value' | 'password' | 'username' | 'client_id' | 'client_secret' | undefined;
+                }
+              | undefined;
+          }[];
+        })[]
+      | null;
+  };
+  export function createPlayground(
+    props: {
+      lang: PlaygroundLanguage;
+      doc: string;
+      /** div.stl-snippet-request-container */
+      container: HTMLElement;
+      onLanguageSelect: (value: string) => void;
+    } & Config,
+  ): () => Promise<void>;
+}

package/plugin/buildAlgoliaIndex.ts

@@ -1,10 +1,9 @@
 import Markdoc from '@markdoc/markdoc';
 import Stainless from '@stainless-api/sdk';
-import { createSDKJSON, parseInputs, transformOAS } from './cms/worker';
+import { createSDKJSON, parseInputs, transformOAS } from './specs/worker';
 import type * as SDKJSON from '@stainless/sdk-json';
 import { Languages } from '@stainless-api/docs-ui/routing';
 import { buildIndex } from '@stainless-api/docs-search/providers/algolia';
-import type { VersionUserConfig } from './loadPluginConfig';
 import type { AstroIntegrationLogger } from 'astro';
 
 const markdocConfig = {
@@ -22,11 +21,13 @@ function renderMarkdown(content?: string) {
 }
 
 export async function buildAlgoliaIndex({
-  version,
+  stainlessProject,
+  branch,
   apiKey,
   logger,
 }: {
-  version: VersionUserConfig;
+  stainlessProject: string;
+  branch: string;
   apiKey: string;
   logger?: AstroIntegrationLogger;
 }) {
@@ -46,10 +47,11 @@ export async function buildAlgoliaIndex({
     }
   }
 
+  // TODO: this is all redundant with the spec code and should be DRYed
   const client = new Stainless({ apiKey });
   const configs = await client.projects.configs.retrieve({
-    project: version.stainlessProject,
-    branch: version.branch,
+    project: stainlessProject,
+    branch,
     include: 'openapi',
   });
 
@@ -74,7 +76,7 @@ export async function buildAlgoliaIndex({
     oas: transformedOAS,
     config,
     languages,
-    projectName: version.stainlessProject,
+    projectName: stainlessProject,
   });
 
   const {

package/plugin/components/SDKSelect.astro

@@ -1,14 +1,19 @@
 ---
-import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
 import { parseRoute } from '@stainless-api/docs-ui/routing';
-import { cmsClient } from '../cms/client';
-import { BASE_PATH, DEFAULT_LANGUAGE, EXCLUDE_LANGUAGES } from 'virtual:stl-starlight-virtual-module';
+import {
+  RESOLVED_API_REFERENCE_PATH,
+  DEFAULT_LANGUAGE,
+  EXCLUDE_LANGUAGES,
+} from 'virtual:stl-starlight-virtual-module';
 import { Languages } from '../languages';
 import { SDKSelectReactComponent } from '../react/Routing';
+import { getSDKJSONInSSR } from '../specs/fetchSpecSSR';
+import { getDocsLanguages } from '../helpers/getDocsLanguages';
+import { API_REFERENCE_BASE_PATH } from 'virtual:stl-docs-virtual-module';
 
 const slug = `/${Astro.locals.starlightRoute.id}`;
 
-const basePath = BASE_PATH;
+const basePath = API_REFERENCE_BASE_PATH;
 const defaultLanguage = DEFAULT_LANGUAGE;
 const { language, stainlessPath } = parseRoute(basePath, slug);
 
@@ -19,19 +24,16 @@ const data = {
   defaultLanguage,
 };
 
-const spec = await cmsClient.getSpec();
+const spec = await getSDKJSONInSSR();
 
-// TODO: should not force unwrap this
-const languages: DocsLanguage[] = spec.docs!.languages ?? ['http'];
-const options = languages
-  .filter((language) => !EXCLUDE_LANGUAGES.includes(language))
-  .map((value) => ({
-    value,
-    label: Languages[value].name,
-    selected: data.language === value,
-  }));
+const options = getDocsLanguages(spec, EXCLUDE_LANGUAGES).map((value) => ({
+  value,
+  label: Languages[value].name,
+  selected: data.language === value,
+}));
 
-const readmeSlug = language === 'http' ? BASE_PATH : `${BASE_PATH}/${language}`;
+const readmeSlug =
+  language === 'http' ? RESOLVED_API_REFERENCE_PATH : `${RESOLVED_API_REFERENCE_PATH}/${language}`;
 ---
 
 <span
@@ -56,7 +58,7 @@ const readmeSlug = language === 'http' ? BASE_PATH : `${BASE_PATH}/${language}`;
   import { navigate } from 'astro:transitions/client';
   import { updateSelectedLanguage } from '../languages';
   import { initDropdown } from '@stainless-api/docs/components/scripts';
-  import { BASE_PATH } from 'virtual:stl-starlight-virtual-module';
+  import { RESOLVED_API_REFERENCE_PATH } from 'virtual:stl-starlight-virtual-module';
   import { getPageLoadEvent } from '../helpers/getPageLoadEvent';
 
   document.addEventListener(getPageLoadEvent(), () => {
@@ -66,7 +68,7 @@ const readmeSlug = language === 'http' ? BASE_PATH : `${BASE_PATH}/${language}`;
       root: sdkSelect,
       onSelect: (value) => {
         const originalLanguage = sdkSelect.dataset.currentValue;
-        navigate(updateSelectedLanguage(BASE_PATH, originalLanguage, value));
+        navigate(updateSelectedLanguage(RESOLVED_API_REFERENCE_PATH, originalLanguage, value));
       },
     });
   });

package/plugin/components/search/SearchIsland.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { BASE_PATH, HIGHLIGHT_THEMES } from 'virtual:stl-starlight-virtual-module';
+import { RESOLVED_API_REFERENCE_PATH, HIGHLIGHT_THEMES } from 'virtual:stl-starlight-virtual-module';
 import { parseRoute, generateRoute } from '@stainless-api/docs-ui/routing';
 import { SearchModal } from '@stainless-api/docs-search';
 import * as Markdoc from '@markdoc/markdoc';
@@ -63,7 +63,7 @@ async function createMarkdownRenderer(): Promise<MarkdownContext> {
         transform(node, config) {
           const children = node.transformChildren(config);
           const attrs = node.transformAttributes(config);
-          const href = attrs['href'].replace('docs://BASE_PATH', BASE_PATH);
+          const href = attrs['href'].replace('docs://BASE_PATH', RESOLVED_API_REFERENCE_PATH);
           return new Markdoc.Tag(this.render, { ...attrs, href }, children);
         },
       },
@@ -87,7 +87,7 @@ async function createMarkdownRenderer(): Promise<MarkdownContext> {
 
 export function DocsSearch({ settings, currentPath }: { settings: SearchSettings; currentPath: string }) {
   const markdownRenderer = React.use(createMarkdownRenderer());
-  const { stainlessPath, language } = parseRoute(BASE_PATH, currentPath);
+  const { stainlessPath, language } = parseRoute(RESOLVED_API_REFERENCE_PATH, currentPath);
   // eslint-disable-next-line turbo/no-undeclared-env-vars
   const pageFind = import.meta.env.DEV
     ? undefined
@@ -96,7 +96,7 @@ export function DocsSearch({ settings, currentPath }: { settings: SearchSettings
   function handleSelect(selectedPath: string) {
     const url = selectedPath.startsWith('/')
       ? selectedPath
-      : generateRoute(BASE_PATH, language, selectedPath);
+      : generateRoute(RESOLVED_API_REFERENCE_PATH, language, selectedPath);
     if (url) window.location.href = url;
   }
 

package/plugin/globalJs/copy.ts

@@ -1,4 +1,7 @@
-import { BASE_PATH, EXPERIMENTAL_COLLAPSIBLE_SNIPPETS } from 'virtual:stl-starlight-virtual-module';
+import {
+  RESOLVED_API_REFERENCE_PATH,
+  EXPERIMENTAL_COLLAPSIBLE_SNIPPETS,
+} from 'virtual:stl-starlight-virtual-module';
 import { getPageLoadEvent } from '../helpers/getPageLoadEvent';
 import { updateSelectedLanguage } from '../languages';
 import { navigate } from 'astro/virtual-modules/transitions-router.js';
@@ -90,7 +93,7 @@ function loadPlayground(playButton: HTMLElement) {
       container,
       onLanguageSelect: (value) => {
         const originalLanguage = document.getElementById('stldocs-snippet-select')?.dataset.currentValue;
-        const path: string = updateSelectedLanguage(BASE_PATH, originalLanguage, value);
+        const path: string = updateSelectedLanguage(RESOLVED_API_REFERENCE_PATH, originalLanguage, value);
         navigate(path.replace(/(\?.+)?($|#)/, (_, str, end) => (str ? str + '&play' : '?play') + end));
       },
       ...playgroundData,

package/plugin/globalJs/navigation.ts

@@ -1,5 +1,5 @@
 import { parseRoute, scrollToPath } from '@stainless-api/docs-ui/routing';
-import { BASE_PATH } from 'virtual:stl-starlight-virtual-module';
+import { RESOLVED_API_REFERENCE_PATH } from 'virtual:stl-starlight-virtual-module';
 import { updateSelectedLanguage } from '../languages';
 import { navigate } from 'astro:transitions/client';
 import { getPageLoadEvent } from '../helpers/getPageLoadEvent.ts';
@@ -11,7 +11,7 @@ history.scrollRestoration = 'auto';
 function getStainlessPathForLocation() {
   return document.location.hash
     ? decodeURI(document.location.hash)
-    : parseRoute(BASE_PATH, document.location.href)?.stainlessPath;
+    : parseRoute(RESOLVED_API_REFERENCE_PATH, document.location.href)?.stainlessPath;
 }
 
 window.addEventListener('popstate', (ev: PopStateEvent) => {
@@ -29,7 +29,7 @@ document.addEventListener(getPageLoadEvent(), () => {
     root: rootElement,
     onSelect: (value) => {
       const originalLanguage = rootElement?.dataset.currentValue;
-      navigate(updateSelectedLanguage(BASE_PATH, originalLanguage, value));
+      navigate(updateSelectedLanguage(RESOLVED_API_REFERENCE_PATH, originalLanguage, value));
     },
   });
 

package/plugin/helpers/getDocsLanguages.ts

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