@stainless-api/docs 0.1.0-beta.0

package/plugin/loadPluginConfig.ts

@@ -0,0 +1,273 @@
+import path from 'path';
+
+import type { CreateShikiHighlighterOptions } from '@astrojs/markdown-remark';
+import type { DocsLanguage } from '@stainless-api/docs-ui/src/routing';
+import type { PropertySettingsType } from '@stainless-api/docs-ui/src/contexts';
+import type { InputFilePaths } from '../plugin/cms/server';
+
+export type AstroCommand = 'dev' | 'build' | 'preview' | 'sync';
+
+export type ContentLayout = 'double-pane' | 'single-pane';
+
+export type VersionUserConfig = {
+  version: string;
+  stainlessProject: string;
+  branch: string;
+};
+
+type BreadcrumbUserConfig = {
+  /**
+   * Include the current page in the breadcrumb list.
+   * Defaults to `false`.
+   */
+  includeCurrentPage?: boolean;
+};
+
+export type StainlessStarlightUserConfig = {
+  /**
+   * Optional api key for Stainless API.
+   * If not provided, it will look for the STAINLESS_API_KEY environment variable.
+   */
+  apiKey?: string;
+
+  /**
+   * The slug of your Stainless project.
+   */
+  stainlessProject: string;
+
+  /**
+   * Optional list of versions to render in the API reference.
+   */
+  versions?: VersionUserConfig[];
+
+  /**
+   * Optional mount point for API reference docs.
+   * Defaults to `/api`.
+   * Example: `/my-api` → docs available at `/my-api/…`.
+   */
+  basePath?: string;
+
+  /**
+   * Optional list of languages to exclude from the API reference.
+   * Example: `["python", "javascript"]`
+   */
+  excludeLanguages?: DocsLanguage[];
+
+  /**
+   * Optional language to treat as the default when the user hasn't selected one.
+   * Defaults to `"http"` when none is provided.
+   * Example: `"python"`
+   */
+  defaultLanguage?: DocsLanguage;
+
+  /**
+   * Configure breadcrumbs for API reference pages
+   */
+  breadcrumbs?: BreadcrumbUserConfig;
+
+  /**
+   * Optional setting that automatically expands the top-level sidebar resources when set to true.
+   * When no value is provided, top-level resources automatically expand if the total number of
+   * endpoints in the API is less than 20. You can explicitly set the value to `false` to prevent
+   * that behavior.
+   */
+  expandResources?: boolean;
+
+  /**
+   * Options that control syntax highlighting for embedded code snippets in the API reference.
+   */
+  highlighting?: {
+    /**
+     * Optionally set the syntax highlighting theme to use for code snippets.
+     * Defaults to Github Dark. Can accept any standard shiki syntax highlighting theme.
+     */
+    themes?: CreateShikiHighlighterOptions['themes'];
+  };
+
+  /**
+   * Configure the content panel for API reference pages.
+   */
+  contentPanel?: {
+    /**
+     * Optional layout for the content panel.
+     * Defaults to `"double-pane"`.
+     */
+    layout?: ContentLayout;
+  };
+
+  /**
+   * Configure the API reference property design
+   */
+  propertySettings?: PropertySettingsType;
+
+  /**
+   * Options to control the documentation site's search functionality
+   */
+  search?: {
+    /**
+     * When set to `true`, the enableAISearch` setting turns on support for
+     * LLM-based conversations with the API documentation
+     */
+    enableAISearch?: boolean;
+  };
+
+  /**
+   * Enable experimental collapsible code snippets. Snippets will be collapsed by default for
+   * single-pane and mobile layouts.
+   * Defaults to `false`.
+   */
+  experimentalCollapsibleSnippets?: boolean;
+};
+
+export type ExternalSpecServerUserConfig = Omit<StainlessStarlightUserConfig, 'stainlessProject'> & {
+  externalSpecServerUrl: string;
+};
+
+export type SomeStainlessStarlightUserConfig = StainlessStarlightUserConfig | ExternalSpecServerUserConfig;
+
+function resolvePath(inputPath: string) {
+  return path.resolve(process.cwd(), inputPath);
+}
+
+function getLocalFilePaths(command: AstroCommand): InputFilePaths | null {
+  if (command !== 'dev') {
+    return null;
+  }
+  if (!process.env.OPENAPI_PATH || !process.env.STAINLESS_SPEC_PATH) {
+    return null;
+  }
+  return {
+    oasPath: resolvePath(process.env.OPENAPI_PATH),
+    configPath: resolvePath(process.env.STAINLESS_SPEC_PATH),
+  };
+}
+
+export type SpecRetrieverConfig =
+  | {
+      kind: 'external_spec_server';
+      specServerUrl: string;
+      stainlessProject: null;
+    }
+  | {
+      kind: 'local_spec_server_with_files';
+      stainlessProject: string;
+      devPaths: InputFilePaths;
+      apiKey: string | null;
+      version: VersionUserConfig;
+    }
+  | {
+      kind: 'local_spec_server_with_remote_files';
+      stainlessProject: string;
+      apiKey: string;
+      version: VersionUserConfig;
+    };
+
+function normalizeConfig(partial: SomeStainlessStarlightUserConfig, command: AstroCommand) {
+  const configWithDefaults = {
+    basePath: partial.basePath ?? '/api',
+    excludeLanguages: partial.excludeLanguages ?? [],
+    defaultLanguage: partial.defaultLanguage ?? 'http',
+    breadcrumbs: {
+      includeCurrentPage: partial.breadcrumbs?.includeCurrentPage ?? false,
+    },
+    expandResources: partial.expandResources ?? true,
+    highlighting: {
+      themes: partial.highlighting?.themes ?? {
+        light: 'github-light',
+        dark: 'github-dark',
+      },
+    },
+    contentPanel: {
+      layout: partial.contentPanel?.layout ?? 'double-pane',
+    },
+    experimentalCollapsibleSnippets: partial.experimentalCollapsibleSnippets ?? false,
+    propertySettings: {
+      types: partial.propertySettings?.types ?? 'rich',
+      collapseDescription: partial.propertySettings?.collapseDescription ?? true,
+      expandDepth: partial.propertySettings?.expandDepth ?? 0,
+      includeModelProperties: partial.propertySettings?.includeModelProperties ?? true,
+    },
+    search: {
+      enableAISearch: partial.search?.enableAISearch ?? false,
+    },
+  };
+
+  function getSpecRetrieverConfig(): SpecRetrieverConfig {
+    if ('externalSpecServerUrl' in partial) {
+      return {
+        kind: 'external_spec_server',
+        specServerUrl: partial.externalSpecServerUrl,
+        stainlessProject: null,
+      };
+    }
+
+    if (!('stainlessProject' in partial)) {
+      throw new Error('You must provide a stainlessProject when using Stainless Starlight');
+    }
+
+    const apiKey = partial.apiKey ?? process.env.STAINLESS_API_KEY ?? null;
+
+    const version = {
+      stainlessProject: partial.stainlessProject,
+      branch: partial.versions?.[0]?.branch ?? 'main',
+      version: partial.versions?.[0]?.version ?? 'v1',
+    };
+
+    const localFilePaths = getLocalFilePaths(command);
+    if (localFilePaths) {
+      return {
+        kind: 'local_spec_server_with_files',
+        devPaths: localFilePaths,
+        stainlessProject: partial.stainlessProject,
+        apiKey,
+        version,
+      };
+    }
+
+    if (!apiKey) {
+      throw new Error(
+        'Please provide a Stainless API key via the STAINLESS_API_KEY environment variable or the apiKey option in the Stainless Starlight config.',
+      );
+    }
+
+    return {
+      kind: 'local_spec_server_with_remote_files',
+      apiKey,
+      stainlessProject: partial.stainlessProject,
+      version,
+    };
+  }
+
+  const specRetrieverConfig = getSpecRetrieverConfig();
+
+  return {
+    ...configWithDefaults,
+    specRetrieverConfig,
+  };
+}
+
+export type NormalizedStainlessStarlightConfig = ReturnType<typeof normalizeConfig>;
+
+/*
+ The goal of the code in this file is to take a user's config and normalize it. 
+ Specifically: we want a single complete config format used throughout the internals of the plugin.
+
+ We've tried to avoid any config values being optional/undefined. To accomplish this:
+ - Any optional config values should have their defaults set here: eg. basePath defaults to /api 
+ - If a field is only used in certain contexts, we make each context a discriminated union (see SpecRetrieverConfig)
+ - We prefer empty arrays over undefined/null
+*/
+export function parseStarlightPluginConfig(partial: SomeStainlessStarlightUserConfig, command: AstroCommand) {
+  try {
+    const config = normalizeConfig(partial, command);
+    return {
+      result: 'success' as const,
+      config,
+    };
+  } catch (error) {
+    return {
+      result: 'error' as const,
+      message: error instanceof Error ? error.message : 'An unknown error occurred',
+    };
+  }
+}

package/plugin/middlewareBuilder/stainlessMiddleware.d.ts

@@ -0,0 +1,5 @@
+import type { TransformRequestSnippetFn } from '@stainless-api/docs-ui/src/components/sdk';
+
+export type StlStarlightMiddleware = {
+  transformRequestSnippet?: TransformRequestSnippetFn;
+};

package/plugin/middlewareBuilder/stlStarlightMiddleware.ts

@@ -0,0 +1,5 @@
+import type { StlStarlightMiddleware } from './stainlessMiddleware';
+
+export function defineStainlessMiddleware(middleware: StlStarlightMiddleware) {
+  return middleware;
+}