@stainless-api/docs 0.1.0-beta.12 → 0.1.0-beta.120

package/plugin/vendor/templates/cli.md

@@ -0,0 +1 @@
+SDK_Readme

package/plugin/vendor/templates/go.md

@@ -7,6 +7,8 @@ from applications written in Go.
 
 SDK_GeneratedByStainless
 
+SDK_MCPReadmeSection
+
 ## Installation
 
 SDK_ReleasePleaseMarkdownBlockStart
@@ -31,7 +33,7 @@ SDK_ReleasePleaseMarkdownBlockEnd
 
 ## Requirements
 
-This library requires Go 1.18+.
+This library requires Go 1.22+.
 
 ## Usage
 
@@ -307,7 +309,7 @@ This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) con
 
 We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
 
-We are keen for your feedback; please open an [issue](SDK_GitHubRepoURL/issues) with questions, bugs, or suggestions.
+We are keen for your feedback; please open an [issue](SDK_RepoURL/issues) with questions, bugs, or suggestions.
 
 ## Contributing
 

package/plugin/vendor/templates/java.md

@@ -11,6 +11,8 @@ SDK_SectionSimilarToOtherSDK
 
 SDK_GeneratedByStainless
 
+SDK_MCPReadmeSection
+
 SDK_SectionDocumentationReference
 
 SDK_SectionInstallation
@@ -57,6 +59,8 @@ SDK_SectionTimeouts
 
 SDK_SectionProxies
 
+SDK_SectionConnectionPooling
+
 SDK_SectionHTTPS
 
 SDK_SectionEnvironments
@@ -84,4 +88,4 @@ This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) con
 
 We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
 
-We are keen for your feedback; please open an [issue](SDK_GitHubRepoURL/issues) with questions, bugs, or suggestions.
+We are keen for your feedback; please open an [issue](SDK_RepoURL/issues) with questions, bugs, or suggestions.

package/plugin/vendor/templates/kotlin.md

@@ -11,6 +11,8 @@ SDK_SectionSimilarToOtherSDK
 
 SDK_GeneratedByStainless
 
+SDK_MCPReadmeSection
+
 SDK_SectionDocumentationReference
 
 SDK_SectionInstallation
@@ -57,6 +59,8 @@ SDK_SectionTimeouts
 
 SDK_SectionProxies
 
+SDK_SectionConnectionPooling
+
 SDK_SectionHTTPS
 
 SDK_SectionEnvironments
@@ -84,4 +88,4 @@ This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) con
 
 We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
 
-We are keen for your feedback; please open an [issue](SDK_GitHubRepoURL/issues) with questions, bugs, or suggestions.
+We are keen for your feedback; please open an [issue](SDK_RepoURL/issues) with questions, bugs, or suggestions.

package/plugin/vendor/templates/node.md

@@ -10,6 +10,8 @@ SDK_DocumentationReference
 
 SDK_GeneratedByStainless
 
+SDK_MCPReadmeSection
+
 ## Installation
 
 SDK_NPMInstallInstructions
@@ -169,7 +171,7 @@ import SDK_PackageName from 'SDK_NPMPackage';
 ```
 
 To do the inverse, add `import "SDK_NPMPackage/shims/node"` (which does import polyfills).
-This can also be useful if you are getting the wrong TypeScript types for `Response` ([more details](SDK_GitHubRepoCodeURL/src/_shims#readme)).
+This can also be useful if you are getting the wrong TypeScript types for `Response` ([more details](SDK_RepoCodeURL/src/_shims#readme)).
 
 ### Logging and middleware
 
@@ -214,7 +216,7 @@ This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) con
 
 We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
 
-We are keen for your feedback; please open an [issue](SDK_GitHubRepoURL/issues) with questions, bugs, or suggestions.
+We are keen for your feedback; please open an [issue](SDK_RepoURL/issues) with questions, bugs, or suggestions.
 
 ## Requirements
 

package/plugin/vendor/templates/python.md

@@ -9,6 +9,8 @@ SDK_ScreencastURL
 
 SDK_GeneratedByStainless
 
+SDK_MCPReadmeSection
+
 ## Documentation
 
 SDK_DocumentationCallout SDK_APIReferenceCallout
@@ -227,7 +229,7 @@ This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) con
 
 We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
 
-We are keen for your feedback; please open an [issue](SDK_GitHubRepoURL/issues) with questions, bugs, or suggestions.
+We are keen for your feedback; please open an [issue](SDK_RepoURL/issues) with questions, bugs, or suggestions.
 
 ### Determining the installed version
 
@@ -242,7 +244,7 @@ print(SDK_PythonPackageImportName.__version__)
 
 ## Requirements
 
-Python 3.8 or higher.
+Python 3.9 or higher.
 
 ## Contributing
 

package/plugin/vendor/templates/ruby.md

@@ -1,11 +1,13 @@
 # SDK_PackageTitle API library
 
-SDK_ReadmeOpening It ships with comprehensive types & docstrings in Yard, RBS, and RBI – [see below](SDK_GitHubURL#Sorbet) for usage with Sorbet. The standard library's `net/http` is used as the HTTP transport, with connection pooling via the `connection_pool` gem.
+SDK_ReadmeOpening It ships with comprehensive types & docstrings in Yard, RBS, and RBI – [see below](SDK_RepoURL#Sorbet) for usage with Sorbet. The standard library's `net/http` is used as the HTTP transport, with connection pooling via the `connection_pool` gem.
 
 SDK_ScreencastURL
 
 SDK_GeneratedByStainless
 
+SDK_MCPReadmeSection
+
 ## Documentation
 
 Documentation for releases of this gem can be found [on RubyDoc](SDK_RubyDocInfoURL).
@@ -142,4 +144,4 @@ Ruby SDK_RubyMinVersion or higher.
 
 ## Contributing
 
-See [the contributing documentation](SDK_GitHubAssetURL/CONTRIBUTING.md).
+See [the contributing documentation](SDK_RepoAssetURL/CONTRIBUTING.md).

package/plugin/vendor/templates/terraform.md

@@ -53,7 +53,7 @@ This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) con
 
 We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
 
-We are keen for your feedback; please open an [issue](SDK_GitHubRepoURL/issues) with questions, bugs, or suggestions.
+We are keen for your feedback; please open an [issue](SDK_RepoURL/issues) with questions, bugs, or suggestions.
 
 ## Contributing
 

package/plugin/vendor/templates/typescript.md

@@ -10,6 +10,8 @@ SDK_DocumentationReference
 
 SDK_GeneratedByStainless
 
+SDK_MCPReadmeSection
+
 ## Installation
 
 SDK_NPMInstallInstructions
@@ -298,7 +300,7 @@ This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) con
 
 We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
 
-We are keen for your feedback; please open an [issue](SDK_GitHubRepoURL/issues) with questions, bugs, or suggestions.
+We are keen for your feedback; please open an [issue](SDK_RepoURL/issues) with questions, bugs, or suggestions.
 
 ## Requirements
 

package/resolveSrcFile.ts

@@ -0,0 +1,10 @@
+import { join } from 'path';
+const dirName = import.meta.dirname;
+/**
+ * Resolve a source file path relative to the stl-starlight package.
+ * @param projectPath - The relative path to the source file.
+ * @returns The absolute path to the source file.
+ */
+export function resolveSrcFile(...projectPath: string[]) {
+  return join(dirName, ...projectPath);
+}

package/scripts/vendor_deps.ts

@@ -3,7 +3,7 @@ import fs from 'fs';
 import path from 'path';
 import { z } from 'zod';
 
-import { Languages } from '@stainless-api/docs-ui/src/routing';
+import { Languages } from '@stainless-api/docs-ui/routing';
 
 const DEPS_DIR = './plugin/vendor';
 
@@ -11,12 +11,12 @@ config();
 
 const envSchema = z.object({
   // absolute path to the Stainless monorepo root
-  STAINLESS_MONOREPO_PATH: z.string(),
+  STAINLESS_ROOT: z.string(),
 });
 
 const env = envSchema.parse(process.env);
 
-console.log(`Using Stainless monorepo at ${env.STAINLESS_MONOREPO_PATH}`);
+console.log(`Using Stainless monorepo at ${env.STAINLESS_ROOT}`);
 
 if (fs.existsSync(DEPS_DIR)) {
   fs.rmSync(DEPS_DIR, { recursive: true });
@@ -25,11 +25,11 @@ if (fs.existsSync(DEPS_DIR)) {
 fs.mkdirSync(DEPS_DIR, { recursive: true });
 
 const previewWorkerPath = path.join(
-  env.STAINLESS_MONOREPO_PATH,
+  env.STAINLESS_ROOT,
   '/packages/preview-worker/dist/stainless/preview.worker.docs.js',
 );
 
-const readmeTemplatePath = path.join(env.STAINLESS_MONOREPO_PATH, '/legacy-dir-root/templates');
+const readmeTemplatePath = path.join(env.STAINLESS_ROOT, '/legacy-dir-root/templates');
 
 fs.copyFileSync(previewWorkerPath, path.join(DEPS_DIR, 'preview.worker.docs.js'));
 

package/shared/conditionalIntegration.ts

@@ -0,0 +1,28 @@
+import { AstroIntegration, type AstroIntegrationLogger } from 'astro';
+import { getSharedLogger } from './getSharedLogger';
+
+export default function conditionalIntegration({
+  condition,
+  integration,
+  reason,
+}: {
+  condition: boolean;
+  integration: AstroIntegration;
+  reason?: string | undefined;
+}): AstroIntegration {
+  if (condition) {
+    return integration;
+  }
+  return {
+    name: integration.name,
+    hooks: Object.fromEntries(
+      Object.keys(integration.hooks).map((hookName) => [
+        hookName,
+        ({ logger: localLogger }: { logger: AstroIntegrationLogger }) => {
+          const logger = getSharedLogger({ fallback: localLogger });
+          logger.info(`Skipping ${integration.name} integration. Reason: ${reason ?? 'not provided'}`);
+        },
+      ]),
+    ),
+  };
+}

package/shared/getProsePages.ts

@@ -0,0 +1,41 @@
+import { readdir } from 'fs/promises';
+import { join, relative } from 'path';
+
+/**
+ * Get all prose pages after a build, by reading all HTML files from the
+ * given output directory, and not from assets.
+ *
+ * We cannot use the `assets` map here because it is not guaranteed to
+ * contain all files, especially if they were generated by other integrations.
+ * Other astro integrations may hijack the "[...slug]" entrypoint, and any files
+ * previously in the [...slug] asset map entry would be lost (this is where starlight stores
+ * its prose HTML files).
+ */
+export async function getProsePages({
+  apiReferenceBasePath,
+  outputBasePath,
+}: {
+  apiReferenceBasePath: string | null;
+  outputBasePath: string;
+}): Promise<string[]> {
+  const allFiles = await readdir(outputBasePath, {
+    recursive: true,
+    withFileTypes: true,
+  });
+
+  const htmlFiles = allFiles
+    .filter((file) => file.isFile() && file.name.endsWith('.html'))
+    .map((file) => join(file.parentPath, file.name));
+
+  if (!apiReferenceBasePath) return htmlFiles;
+  // Normalize by removing leading/trailing slashes from apiReferenceBasePath
+  const normalizedApiPath = apiReferenceBasePath.replace(/^\/+/g, '').replace(/\/+$/g, '');
+  const pagesToRender = htmlFiles.filter((absPath) => {
+    const relPath = relative(outputBasePath, absPath);
+    // Filter out API reference pages
+    if (relPath === normalizedApiPath || relPath.startsWith(`${normalizedApiPath}/`)) return false;
+    return true;
+  });
+
+  return pagesToRender;
+}

package/shared/getSharedLogger.ts

@@ -0,0 +1,15 @@
+import { AstroIntegrationLogger } from 'astro';
+
+let sharedLogger: AstroIntegrationLogger | null = null;
+
+// This is probably temporary, but it's a quick way to share a logger between our many integrations
+// we want to share a logger so they have the same "stainless" label
+
+export function setSharedLogger(logger: AstroIntegrationLogger) {
+  sharedLogger = logger;
+}
+
+// a fallback is probably not required, but it's a good safeguard in case we somehow call a logger before the shared logger is set
+export function getSharedLogger({ fallback }: { fallback: AstroIntegrationLogger }) {
+  return sharedLogger ?? fallback;
+}

package/shared/terminalUtils.ts

@@ -0,0 +1,3 @@
+export function bold(text: string) {
+  return `\x1b[1m${text}\x1b[0m`;
+}

package/shared/virtualModule.ts

@@ -1,7 +1,60 @@
-export function buildVirtualModuleString(vars: Record<string, any>) {
+import type { ViteUserConfig } from 'astro';
+
+export type VitePlugin = NonNullable<ViteUserConfig['plugins']>[number];
+
+export function buildVirtualModuleString<T extends Record<string, unknown>>(vars: T) {
   return Object.entries(vars)
     .map(([key, value]) => {
       return `export const ${key} = ${JSON.stringify(value)};`;
     })
     .join('\n');
 }
+
+export function makeVirtualModPlugin(bareId: string, content: string): VitePlugin {
+  return {
+    name: `stl-virtual-module-loader-${bareId}`,
+    resolveId(id) {
+      // The '\0' prefix tells Vite “this is a virtual module” and prevents it from being resolved again.
+      if (id === bareId) {
+        return `\0${bareId}`;
+      }
+    },
+    load(id) {
+      if (id === `\0${bareId}`) {
+        return content;
+      }
+    },
+  };
+}
+
+export function makeAsyncVirtualModPlugin<T extends Record<string, unknown>>(
+  bareId: string,
+  contentLoader: () => Promise<T | string>,
+): VitePlugin {
+  return {
+    name: `stl-virtual-module-loader-${bareId}`,
+    resolveId(id) {
+      // The '\0' prefix tells Vite “this is a virtual module” and prevents it from being resolved again.
+      if (id === bareId) {
+        return `\0${bareId}`;
+      }
+    },
+    async load(id) {
+      if (id === `\0${bareId}`) {
+        const content = await contentLoader();
+        if (typeof content === 'string') {
+          return content;
+        }
+        return buildVirtualModuleString(content);
+      }
+    },
+  };
+}
+
+export function virtualModule(id: string) {
+  return {
+    fromString: (content: string) => makeVirtualModPlugin(id, content),
+    fromObject: <T extends Record<string, unknown>>(content: T) =>
+      makeVirtualModPlugin(id, buildVirtualModuleString(content)),
+  };
+}

package/src/content.config.ts

@@ -0,0 +1,9 @@
+// Stub here so that `astro sync` generates the correct types for the `docs` content collection
+
+import { defineCollection } from 'astro:content';
+import { docsLoader } from '@astrojs/starlight/loaders';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+};

package/stl-docs/components/AIDropdown.tsx

@@ -0,0 +1,63 @@
+import { DropdownButton } from '@stainless-api/ui-primitives';
+import { CopyIcon } from 'lucide-react';
+import { ChatGPTIcon } from './icons/chat-gpt';
+import { ClaudeIcon } from './icons/claude';
+import { GeminiIcon } from './icons/gemini';
+import { MarkdownIcon } from './icons/markdown';
+import { CursorIcon } from './icons/cursor';
+import React from 'react';
+
+import { getAIDropdownOptions, type DropdownIcon } from '../../plugin/globalJs/ai-dropdown-options';
+
+const iconMap: { [key in DropdownIcon]: React.ReactNode } = {
+  markdown: <MarkdownIcon />,
+  copy: <CopyIcon size={16} />,
+  claude: <ClaudeIcon />,
+  chatgpt: <ChatGPTIcon />,
+  gemini: <GeminiIcon />,
+  cursor: <CursorIcon />,
+};
+
+const { primaryAction, groups } = getAIDropdownOptions();
+
+function ItemLabel({ label }: { label: string[] }) {
+  if (label.length > 1) {
+    return (
+      <DropdownButton.MenuItemText subtle>
+        {label[0]}
+        <strong>{label[1]}</strong>
+      </DropdownButton.MenuItemText>
+    );
+  }
+
+  return (
+    <DropdownButton.MenuItemText>
+      <strong>{label[0]}</strong>
+    </DropdownButton.MenuItemText>
+  );
+}
+
+export function AIDropdown() {
+  return (
+    <DropdownButton data-dropdown-id="ai-dropdown-button">
+      <DropdownButton.PrimaryAction>
+        {iconMap[primaryAction.icon]}
+        <DropdownButton.PrimaryActionText>{primaryAction.label}</DropdownButton.PrimaryActionText>
+      </DropdownButton.PrimaryAction>
+      <DropdownButton.Trigger />
+      <DropdownButton.Menu>
+        {groups.map((group) => (
+          <React.Fragment key={group.reactKey}>
+            {group.options.map((option) => (
+              <DropdownButton.MenuItem value={option.id} isExternalLink={option.external} key={option.id}>
+                <DropdownButton.Icon>{iconMap[option.icon]}</DropdownButton.Icon>
+                <ItemLabel label={option.label} />
+              </DropdownButton.MenuItem>
+            ))}
+            {group.isLast ? null : <hr />}
+          </React.Fragment>
+        ))}
+      </DropdownButton.Menu>
+    </DropdownButton>
+  );
+}

package/stl-docs/components/AiChatIsland.tsx

@@ -0,0 +1,14 @@
+import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
+import AiChat, { STAINLESS_PROJECT } from 'virtual:stl-docs/components/AiChat.tsx';
+
+export default function AiChatIsland({
+  currentLanguage,
+  siteTitle,
+}: {
+  currentLanguage: DocsLanguage | undefined;
+  siteTitle: string | undefined;
+}) {
+  if (!AiChat) throw new Error('AiChatIsland was rendered but could not load AiChat component');
+  if (!STAINLESS_PROJECT) return null;
+  return <AiChat projectId={STAINLESS_PROJECT} language={currentLanguage} siteTitle={siteTitle} />;
+}

package/stl-docs/components/{content-panel/ContentBreadcrumbs.tsx → ContentBreadcrumbs.tsx}

@@ -1,6 +1,6 @@
 import { ChevronRight } from 'lucide-react';
-import { Join } from '@stainless-api/docs-ui/src/components';
-import style from '@stainless-api/docs-ui/src/style';
+import { Join } from '@stainless-api/docs-ui/components';
+import style from '@stainless-api/docs-ui/style';
 import type { StarlightRouteData } from '@astrojs/starlight/route-data';
 
 type Breadcrumb = { title: string; href: string };

package/stl-docs/components/ContentPanel.astro

@@ -0,0 +1,9 @@
+<div class="stl-ui-prose stl-content-panel">
+  <slot />
+</div>
+
+<style>
+  .stl-content-panel + .stl-content-panel {
+    margin-top: 24px;
+  }
+</style>

package/stl-docs/components/Footer.astro

@@ -0,0 +1,89 @@
+---
+import EditLink from 'virtual:starlight/components/EditLink';
+import LastUpdated from 'virtual:starlight/components/LastUpdated';
+import Pagination from 'virtual:starlight/components/Pagination';
+import { RENDER_CREDITS } from 'virtual:stl-docs-virtual-module';
+import StainlessLogo from './StainlessLogo.svg';
+---
+
+<footer class="stl-footer">
+  <div class="stl-footer-row meta">
+    <EditLink />
+    <LastUpdated />
+  </div>
+
+  <Pagination />
+
+  {
+    RENDER_CREDITS && (
+      <div class="stl-footer-row">
+        <a
+          class="stl-footer-credits"
+          href="https://www.stainless.com/products/docs"
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          Powered by <StainlessLogo />
+        </a>
+      </div>
+    )
+  }
+</footer>
+
+<style is:global>
+  .stl-footer {
+    display: flex;
+    flex-direction: column;
+    gap: 1.5rem;
+    margin-block-start: 4rem;
+    padding-block-start: 1rem;
+    padding-block-end: 4rem;
+
+    .stl-footer-row {
+      display: flex;
+      gap: 1rem;
+      justify-content: space-between;
+
+      &:empty,
+      &:not(:has(> *)) {
+        display: none;
+      }
+    }
+
+    .pagination-links {
+      margin-inline: calc(-0.25 * var(--stl-ui-pagination-border-radius-outer));
+    }
+  }
+
+  .stl-footer-credits {
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    text-decoration: none;
+    margin-inline-start: auto;
+    margin-block-start: 1rem;
+    font-size: var(--stl-typography-scale-sm);
+
+    /* duck text opacity by more than image opacity */
+    opacity: 0.75;
+    color: rgb(from var(--stl-color-foreground-reduced) r g b / calc(alpha * 0.9));
+    transition:
+      opacity 0.15s ease,
+      color 0.15s ease;
+    /* both text & image to full opacity */
+    &:hover {
+      opacity: 1;
+      color: var(--stl-color-foreground-reduced);
+    }
+
+    svg {
+      height: 1.4em;
+      width: auto;
+      display: inline-block;
+      margin-inline-start: 0.5ch;
+      image {
+        transform: translateX(0.15ch);
+      }
+    }
+  }
+</style>

package/stl-docs/components/Head.astro

@@ -0,0 +1,20 @@
+---
+import { Font } from 'astro:assets';
+import { FONTS } from 'virtual:stl-docs-virtual-module';
+import Default from '@astrojs/starlight/components/Head.astro';
+import path from 'path';
+
+const mdPath = path.posix.join(Astro.url.pathname, 'index.md');
+const fonts = [FONTS.primary, FONTS.heading, FONTS.mono, ...(FONTS.additional ?? [])].filter(Boolean);
+---
+
+<Default />
+
+{fonts.map((font) => <Font cssVariable={font.cssVariable} preload={font.preload} />)}
+
+<link rel="alternate" type="text/markdown" href={mdPath} />
+
+<script>
+  import { wireAIDropdown } from '../../plugin/globalJs/ai-dropdown-options.ts';
+  wireAIDropdown();
+</script>

package/stl-docs/components/Header.astro

@@ -23,14 +23,6 @@ const shouldRenderSearch = !!(
 
 <style is:global>
   @layer starlight.core {
-    header {
-      border-color: var(--sl-color-hairline);
-
-      &.header {
-        border-bottom-color: var(--sl-color-hairline);
-      }
-    }
-
     .header {
       display: flex;
       gap: var(--sl-nav-gap);
@@ -44,9 +36,10 @@ const shouldRenderSearch = !!(
       overflow: clip;
       /* Avoid clipping focus ring around link inside title wrapper. */
       padding: 0.25rem;
-      padding-left: 0;
       margin: -0.25rem;
       min-width: 0;
+      /* Max height should match button height */
+      max-height: 32px;
     }
 
     .default-tabs-container {
@@ -84,7 +77,7 @@ const shouldRenderSearch = !!(
 
     @media (min-width: 50rem) {
       .default-tabs-container {
-        min-width: 440px;
+        min-width: 540px;
       }
     }
   }