@stainless-api/docs 0.1.0-beta.102 → 0.1.0-beta.104

package/stl-docs/components/Header.astro

@@ -23,11 +23,6 @@ const shouldRenderSearch = !!(
 
 <style is:global>
   @layer starlight.core {
-    header,
-    header.header {
-      border-color: var(--stl-color-border-faint);
-    }
-
     .header {
       display: flex;
       gap: var(--sl-nav-gap);

package/stl-docs/components/PageFrame.astro

@@ -1,18 +1,34 @@
 ---
-import Default from '@astrojs/starlight/components/PageFrame.astro';
+import Sidebar from 'virtual:starlight/components/Sidebar';
+import MobileMenuToggle from 'virtual:starlight/components/MobileMenuToggle';
+
 import AiChat from 'virtual:stl-docs/components/AiChat.tsx'; // conditionally resolves to null if ai chat module is not injected
 import AiChatIsland from './AiChatIsland.tsx'; // entrypoint for client island can’t be a virtual module
 
 import starlightConfig from 'virtual:starlight/user-config';
 const locale = Astro.currentLocale ?? starlightConfig.defaultLocale.lang;
 const siteTitle = locale && starlightConfig.title[locale];
+
+const { hasSidebar } = Astro.locals.starlightRoute;
+import clsx from 'clsx';
 ---
 
-<Default>
-  <slot name="header" slot="header" />
-  <slot name="sidebar" slot="sidebar" />
+<div class="page">
+  <header>
+    <slot name="header" slot="header" />
+  </header>
+
+  <nav
+    class={clsx('sidebar', !hasSidebar && 'hidden')}
+    aria-label={Astro.locals.t('sidebarNav.accessibleLabel')}
+  >
+    <MobileMenuToggle />
+    <div id="starlight__sidebar" class="sidebar-pane">
+      <Sidebar />
+    </div>
+  </nav>
 
   <slot />
 
   {!!AiChat && <AiChatIsland client:load currentLanguage={Astro.locals.language} siteTitle={siteTitle} />}
-</Default>
+</div>

package/stl-docs/components/PageSidebar.astro

@@ -0,0 +1,11 @@
+---
+import TableOfContents from 'virtual:starlight/components/TableOfContents';
+---
+
+{
+  Astro.locals.starlightRoute.toc && (
+    <div class="right-sidebar-panel">
+      <TableOfContents />
+    </div>
+  )
+}

package/stl-docs/components/TwoColumnContent.astro

@@ -0,0 +1,2 @@
+<slot />
+<slot name="right-sidebar" slot="right-sidebar" />

package/stl-docs/components/content-panel/ContentPanel.astro

@@ -1,42 +1,9 @@
----
-
----
-
-<div class="content-panel sl-container stl-ui-prose">
+<div class="stl-ui-prose stl-content-panel">
   <slot />
 </div>
 
 <style>
-  @layer starlight.core {
-    .content-panel {
-      padding: 1.5rem var(--sl-content-pad-x);
-    }
-    .sl-container {
-      max-width: var(--sl-content-width);
-    }
-
-    @media (min-width: 72rem) {
-      .sl-container {
-        margin-inline: var(--sl-content-margin-inline, auto);
-      }
-    }
-  }
-
-  .content-panel {
-    padding: 0 var(--sl-content-pad-x) 0 var(--sl-content-pad-x);
-  }
-
-  .content-panel + .content-panel {
+  .stl-content-panel + .stl-content-panel {
     margin-top: 24px;
   }
-
-  @media (min-width: 50rem) {
-    .content-panel {
-      padding: 0 0 0 var(--sl-content-pad-x);
-    }
-  }
-
-  .stl-prose-page-nav-container {
-    padding: 1rem 0 0;
-  }
 </style>

package/stl-docs/components/headers/DefaultHeader.astro

@@ -6,17 +6,15 @@ import HeaderLinks from './HeaderLinks.astro';
 import NavLinks from '../nav-tabs/NavTabs.astro';
 import { TABS } from 'virtual:stl-docs-virtual-module';
 import ThemeSelect from 'virtual:starlight/components/ThemeSelect';
-import SplashMobileMenuToggle from './SplashMobileMenuToggle.astro';
 
 interface Props {
   shouldRenderSearch?: boolean;
 }
 
 const { shouldRenderSearch } = Astro.props;
-const { hasSidebar } = Astro.locals.starlightRoute;
 ---
 
-<div class="header my-header">
+<div class="header">
   <div class="left-group">
     <div class="title-wrapper sl-flex">
       <SiteTitle />
@@ -24,9 +22,9 @@ const { hasSidebar } = Astro.locals.starlightRoute;
   </div>
   {TABS.length > 0 && <NavLinks />}
 
-  <div class={'sl-flex print:hidden right-group default-tabs-container'}>
-    {shouldRenderSearch && <Search />}
-    {!hasSidebar && <SplashMobileMenuToggle />}
+  {shouldRenderSearch && <Search />}
+
+  <div class="right-group">
     <div class="sl-hidden md:sl-flex">
       <ThemeSelect />
       <HeaderLinks />

package/stl-docs/components/headers/StackedHeader.astro

@@ -3,32 +3,26 @@ import LanguageSelect from 'virtual:starlight/components/LanguageSelect';
 import Search from 'virtual:starlight/components/Search';
 import SiteTitle from 'virtual:starlight/components/SiteTitle';
 import HeaderLinks from './HeaderLinks.astro';
-import { TABS } from 'virtual:stl-docs-virtual-module';
 import ThemeSelect from 'virtual:starlight/components/ThemeSelect';
 import SecondaryNavTabs from '../nav-tabs/SecondaryNavTabs.astro';
-import SplashMobileMenuToggle from './SplashMobileMenuToggle.astro';
 
 interface Props {
   shouldRenderSearch?: boolean;
 }
 
 const { shouldRenderSearch } = Astro.props;
-const { hasSidebar } = Astro.locals.starlightRoute;
 ---
 
-<div class="header my-header">
+<div class="header">
   <div class="left-group">
     <div class="title-wrapper sl-flex">
       <SiteTitle />
     </div>
   </div>
 
-  <div class="stl-top-container">
-    {shouldRenderSearch && <Search />}
-    {!hasSidebar && <SplashMobileMenuToggle />}
-  </div>
+  {shouldRenderSearch && <Search />}
 
-  <div class={`sl-hidden md:sl-flex print:hidden right-group`}>
+  <div class="right-group">
     <ThemeSelect />
     <HeaderLinks />
     <LanguageSelect />
@@ -36,45 +30,3 @@ const { hasSidebar } = Astro.locals.starlightRoute;
 </div>
 
 <SecondaryNavTabs />
-
-<style is:inline>
-  .stl-top-container {
-    display: flex;
-    flex-direction: row;
-    align-items: center;
-    justify-content: end;
-    gap: 0.5rem;
-    width: 100%;
-  }
-  @media (min-width: 50rem) {
-    :root {
-      --sl-nav-height: 88px;
-    }
-
-    header.header {
-      display: flex;
-      flex-direction: column;
-      gap: 0.29rem;
-      padding-bottom: 0;
-    }
-
-    .stl-top-container {
-      justify-content: center;
-    }
-  }
-</style>
-
-{
-  TABS.length === 0 && (
-    <style
-      is:inline
-      set:text={`
-        @media (min-width: 50rem) {
-          :root {
-            --sl-nav-height: 56px;
-          }
-        }
-      `}
-    />
-  )
-}

package/stl-docs/components/nav-tabs/NavTabs.astro

@@ -90,8 +90,8 @@ const navLinks = buildNavLinks(Astro.locals.starlightRoute);
 
       localStorage.setItem('stl-nav-links-mode', mode);
 
-      document.documentElement.classList.remove('stl-nav-links-mode-desktop', 'stl-nav-links-mode-mobile');
-      document.documentElement.classList.add('stl-nav-links-mode-' + mode);
+      document.documentElement.classList.toggle('stl-nav-links-mode-desktop', mode === 'desktop');
+      document.documentElement.classList.toggle('stl-nav-links-mode-mobile', mode === 'mobile');
     }
 
     const resizeObserver = new ResizeObserver(() => {

package/stl-docs/index.ts

@@ -21,7 +21,8 @@ import type * as StlDocsVirtualModule from 'virtual:stl-docs-virtual-module';
 import { resolveSrcFile } from '../resolveSrcFile';
 import { stainlessDocsMarkdownRenderer } from './proseMarkdown/proseMarkdownIntegration';
 import { setSharedLogger } from '../shared/getSharedLogger';
-import { stainlessDocsAlgoliaProseIndexing, stainlessDocsVectorProseIndexing } from './proseSearchIndexing';
+import { stainlessDocsVectorProseIndexing } from './proseDocSync';
+import { stainlessDocsAlgoliaProseIndexing } from './proseSearchIndexing';
 import { stainlessStarlight } from '../plugin';
 import { getFontRoles, flattenFonts } from './fonts';
 
@@ -50,6 +51,7 @@ function stainlessDocsStarlightIntegration(config: NormalizedStainlessDocsConfig
   type ComponentOverrides = StarlightConfigDefined['components'];
   const componentOverrides: ComponentOverrides = {
     PageFrame: resolveSrcFile(COMPONENTS_FOLDER, './PageFrame.astro'),
+    TwoColumnContent: resolveSrcFile(COMPONENTS_FOLDER, './TwoColumnContent.astro'),
 
     Head: resolveSrcFile(COMPONENTS_FOLDER, './Head.astro'),
     Header: resolveSrcFile(COMPONENTS_FOLDER, './Header.astro'),
@@ -58,6 +60,7 @@ function stainlessDocsStarlightIntegration(config: NormalizedStainlessDocsConfig
 
     Sidebar: resolveSrcFile(COMPONENTS_FOLDER, './sidebars/BaseSidebar.astro'),
     ContentPanel: resolveSrcFile(COMPONENTS_FOLDER, './content-panel/ContentPanel.astro'),
+    PageSidebar: resolveSrcFile(COMPONENTS_FOLDER, './PageSidebar.astro'),
     TableOfContents: resolveSrcFile(COMPONENTS_FOLDER, './TableOfContents.astro'),
 
     PageTitle: resolveSrcFile(COMPONENTS_FOLDER, './PageTitle.astro'),

package/stl-docs/proseDocSync.ts

@@ -0,0 +1,314 @@
+import type { AstroIntegration, AstroIntegrationLogger } from 'astro';
+import crypto from 'crypto';
+import { readFile } from 'fs/promises';
+import path from 'path';
+import { getProsePages } from '../shared/getProsePages';
+import { getSharedLogger } from '../shared/getSharedLogger';
+import { bold } from '../shared/terminalUtils';
+import { NormalizedStainlessDocsConfig } from './loadStlDocsConfig';
+
+const DOCS_API_BASE_URL = 'https://api.stainlessapi.com';
+
+// ─── API client ──────────────────────────────────────────────────────
+
+async function docsApiRequest(
+  method: string,
+  apiPath: string,
+  apiKey: string,
+  body?: object,
+): Promise<Response> {
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${apiKey}`,
+  };
+  if (body) {
+    headers['Content-Type'] = 'application/json';
+  }
+  return fetch(`${DOCS_API_BASE_URL}${apiPath}`, {
+    method,
+    headers,
+    ...(body ? { body: JSON.stringify(body) } : {}),
+  });
+}
+
+// ─── Manifest & diffing ─────────────────────────────────────────────
+
+type LocalDoc = { content: Buffer; sha256: string; source: string };
+
+function sha256(content: Buffer): string {
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+async function buildLocalManifest(pages: string[], outputBasePath: string): Promise<Map<string, LocalDoc>> {
+  const docs = new Map<string, LocalDoc>();
+  for (const absHtmlPath of pages) {
+    const content = await readFile(absHtmlPath);
+    const docId = path.relative(outputBasePath, absHtmlPath);
+    docs.set(docId, { content, sha256: sha256(content), source: '/' + docId });
+  }
+  return docs;
+}
+
+async function fetchRemoteManifest(
+  docsSiteId: string,
+  project: string,
+  apiKey: string,
+  logger: AstroIntegrationLogger,
+): Promise<Map<string, string>> {
+  try {
+    const response = await docsApiRequest(
+      'GET',
+      `/api/docs-sites/${docsSiteId}/documents?project=${encodeURIComponent(project)}`,
+      apiKey,
+    );
+
+    if (response.ok) {
+      const data = (await response.json()) as {
+        documents: { id: string; content_sha256: string }[];
+      };
+      return new Map(data.documents.map((d) => [d.id, d.content_sha256]));
+    }
+
+    logger.error(`Failed to list remote documents (HTTP ${response.status}): ${await response.text()}`);
+  } catch (err) {
+    logger.error(`Failed to list remote documents: ${err}`);
+  }
+  return new Map();
+}
+
+function diffManifests(
+  localDocs: Map<string, LocalDoc>,
+  remoteDocs: Map<string, string>,
+): { toPut: (LocalDoc & { docId: string })[]; toDelete: string[] } {
+  const toPut: (LocalDoc & { docId: string })[] = [];
+  for (const [docId, local] of localDocs) {
+    if (remoteDocs.get(docId) !== local.sha256) {
+      toPut.push({ docId, ...local });
+    }
+  }
+
+  const toDelete: string[] = [];
+  for (const remoteDocId of remoteDocs.keys()) {
+    if (!localDocs.has(remoteDocId)) {
+      toDelete.push(remoteDocId);
+    }
+  }
+
+  return { toPut, toDelete };
+}
+
+// ─── Import & delete ────────────────────────────────────────────────
+
+type ImportJobResult = { succeeded: number; failed: number; errors: string[] };
+
+async function importDocuments(
+  docs: (LocalDoc & { docId: string })[],
+  docsSiteId: string,
+  project: string,
+  apiKey: string,
+  logger: AstroIntegrationLogger,
+): Promise<ImportJobResult> {
+  const totals: ImportJobResult = { succeeded: 0, failed: 0, errors: [] };
+
+  for (let i = 0; i < docs.length; i += 100) {
+    const batch = docs.slice(i, i + 100);
+
+    let response: Response;
+    try {
+      response = await docsApiRequest('POST', `/api/docs-sites/${docsSiteId}/documents/import`, apiKey, {
+        project,
+        documents: batch.map(({ docId, content, source }) => ({
+          id: docId,
+          content: content.toString('utf-8'),
+          content_type: 'text/html',
+          source,
+        })),
+      });
+    } catch (err) {
+      logger.error(`Failed to submit import batch: ${err}`);
+      totals.failed += batch.length;
+      continue;
+    }
+
+    if (!response.ok) {
+      logger.error(`Failed to submit import batch (HTTP ${response.status}): ${await response.text()}`);
+      totals.failed += batch.length;
+      continue;
+    }
+
+    const { job_id } = (await response.json()) as { job_id: string };
+    const result = await pollImportJob(docsSiteId, job_id, apiKey, logger);
+    totals.succeeded += result.succeeded;
+    totals.failed += result.failed;
+    totals.errors.push(...result.errors);
+  }
+
+  return totals;
+}
+
+async function pollImportJob(
+  docsSiteId: string,
+  jobId: string,
+  apiKey: string,
+  logger: AstroIntegrationLogger,
+): Promise<ImportJobResult> {
+  const maxWait = 5 * 60_000;
+  const start = Date.now();
+
+  while (Date.now() - start < maxWait) {
+    await new Promise((r) => setTimeout(r, 2_000));
+
+    let response: Response;
+    try {
+      response = await docsApiRequest('GET', `/api/docs-sites/${docsSiteId}/documents/jobs/${jobId}`, apiKey);
+    } catch (err) {
+      logger.error(`Failed to poll import job ${jobId}: ${err}`);
+      continue;
+    }
+
+    if (!response.ok) {
+      logger.error(`Failed to poll import job ${jobId} (HTTP ${response.status}): ${await response.text()}`);
+      continue;
+    }
+
+    const job = (await response.json()) as {
+      status: string;
+      succeeded: number;
+      failed: number;
+      errors: string[] | null;
+    };
+
+    if (job.status === 'queued' || job.status === 'processing') continue;
+
+    return { succeeded: job.succeeded, failed: job.failed, errors: job.errors ?? [] };
+  }
+
+  logger.error(`Import job ${jobId} timed out after ${maxWait / 1000}s`);
+  return { succeeded: 0, failed: 0, errors: [`Job ${jobId} timed out`] };
+}
+
+async function deleteDocuments(
+  docIds: string[],
+  docsSiteId: string,
+  project: string,
+  apiKey: string,
+  logger: AstroIntegrationLogger,
+): Promise<{ succeeded: number; failed: number }> {
+  let succeeded = 0;
+  let failed = 0;
+
+  await Promise.all(
+    docIds.map(async (docId) => {
+      try {
+        const response = await docsApiRequest(
+          'DELETE',
+          `/api/docs-sites/${docsSiteId}/documents/${encodeURIComponent(docId)}?project=${encodeURIComponent(project)}`,
+          apiKey,
+        );
+        if (response.ok) {
+          succeeded++;
+        } else {
+          logger.error(`Failed to delete ${docId} (HTTP ${response.status}): ${await response.text()}`);
+          failed++;
+        }
+      } catch (err) {
+        logger.error(`Failed to delete ${docId}: ${err}`);
+        failed++;
+      }
+    }),
+  );
+
+  return { succeeded, failed };
+}
+
+// ─── Sync orchestrator ──────────────────────────────────────────────
+
+async function syncProseDocuments(opts: {
+  docsSiteId: string;
+  project: string;
+  apiKey: string;
+  pages: string[];
+  outputBasePath: string;
+  logger: AstroIntegrationLogger;
+}) {
+  const { docsSiteId, project, apiKey, pages, outputBasePath, logger } = opts;
+
+  logger.info(bold(`Syncing ${pages.length} prose pages to docs search index`));
+
+  const localDocs = await buildLocalManifest(pages, outputBasePath);
+  const remoteDocs = await fetchRemoteManifest(docsSiteId, project, apiKey, logger);
+  const { toPut, toDelete } = diffManifests(localDocs, remoteDocs);
+
+  const unchanged = localDocs.size - toPut.length;
+  logger.info(bold(`${toPut.length} to upload, ${toDelete.length} to delete, ${unchanged} unchanged`));
+
+  if (toPut.length === 0 && toDelete.length === 0) {
+    logger.info('Docs search index is up to date');
+    return;
+  }
+
+  const uploaded =
+    toPut.length > 0
+      ? await importDocuments(toPut, docsSiteId, project, apiKey, logger)
+      : { succeeded: 0, failed: 0, errors: [] as string[] };
+
+  const deleted =
+    toDelete.length > 0
+      ? await deleteDocuments(toDelete, docsSiteId, project, apiKey, logger)
+      : { succeeded: 0, failed: 0 };
+
+  for (const err of uploaded.errors) {
+    logger.error(`Import error: ${err}`);
+  }
+
+  const failures = uploaded.failed + deleted.failed;
+  if (failures > 0) {
+    logger.error(
+      `Docs search index sync completed with ${failures} error(s): ${uploaded.succeeded} uploaded, ${deleted.succeeded} deleted`,
+    );
+  } else {
+    logger.info(
+      bold(`Docs search index synced: ${uploaded.succeeded} uploaded, ${deleted.succeeded} deleted`),
+    );
+  }
+}
+
+// ─── Astro integration ──────────────────────────────────────────────
+
+export function stainlessDocsVectorProseIndexing(
+  config: NormalizedStainlessDocsConfig,
+  apiReferenceBasePath: string | null,
+): AstroIntegration {
+  return {
+    name: 'stl-docs-prose-indexing',
+    hooks: {
+      'astro:build:done': async ({ logger: localLogger, dir }) => {
+        const logger = getSharedLogger({ fallback: localLogger });
+        const outputBasePath = dir.pathname;
+
+        const project = config.apiReference?.stainlessProject;
+        const { STAINLESS_API_KEY: apiKey, STAINLESS_DOCS_SITE_ID: docsSiteId } = process.env;
+
+        if (!apiKey || !project || !docsSiteId) {
+          logger.info(
+            `Skipping vector prose search indexing: required environment/config variables not set, missing: ${[
+              !apiKey && 'STAINLESS_API_KEY',
+              !docsSiteId && 'STAINLESS_DOCS_SITE_ID',
+              !project && 'stainlessProject in apiReference config',
+            ]
+              .filter(Boolean)
+              .join(', ')}`,
+          );
+          return;
+        }
+
+        const pages = await getProsePages({ apiReferenceBasePath, outputBasePath });
+        if (pages.length === 0) {
+          logger.info('No prose pages found to index for vector search');
+          return;
+        }
+
+        await syncProseDocuments({ docsSiteId, project, apiKey, pages, outputBasePath, logger });
+      },
+    },
+  };
+}