@stainless-api/docs 0.1.0-beta.0

package/plugin/buildAlgoliaIndex.ts

@@ -0,0 +1,72 @@
+import Markdoc from '@markdoc/markdoc';
+import Stainless from '@stainless-api/sdk';
+import { createSDKJSON, parseInputs, transformOAS } from './cms/worker';
+import type * as SDKJSON from '~/lib/json-spec-v2/types';
+import { Languages } from '@stainless-api/docs-ui/src/routing';
+import { buildIndex } from '@stainless-api/docs-ui/src/search/providers/algolia';
+import type { VersionUserConfig } from './loadPluginConfig';
+
+const markdocConfig = {
+  nodes: {
+    document: { ...Markdoc.nodes.document, render: '' },
+  },
+};
+
+function renderMarkdown(content?: string) {
+  if (!content) return null;
+
+  const ast = Markdoc.parse(content);
+  const transformed = Markdoc.transform(ast, markdocConfig);
+  return Markdoc.renderers.html(transformed);
+}
+
+export async function buildAlgoliaIndex({ version, apiKey }: { version: VersionUserConfig; apiKey: string }) {
+  const client = new Stainless({ apiKey });
+  const configs = await client.projects.configs.retrieve({
+    project: version.stainlessProject,
+    branch: version.branch,
+    include: 'openapi',
+  });
+
+  const configYML = Object.values(configs)[0] as { content: any };
+  const oasJson = Object.values(configs)[1] as { content: any };
+  const configStr = configYML['content'];
+  const oasStr = oasJson['content'];
+  const { oas, config } = await parseInputs({
+    oas: oasStr,
+    config: configStr,
+  });
+
+  const transformedOAS = await transformOAS({ oas, config });
+
+  const languages =
+    config.docs?.languages ??
+    (Object.entries(config.targets)
+      // @ts-expect-error we don't have the actual Stainless config type here
+      .filter(([name, target]) => Languages.includes(name) && !target.skip)
+      .map(([name]) => name) as SDKJSON.SpecLanguage[]);
+
+  const sdkJson = await createSDKJSON({
+    oas: transformedOAS,
+    config,
+    languages,
+  });
+
+  const {
+    PUBLIC_ALGOLIA_APP_ID: appId,
+    PUBLIC_ALGOLIA_INDEX: indexName,
+    PRIVATE_ALGOLIA_WRITE_KEY: algoliaWriteKey,
+  } = process.env;
+
+  if (!appId || !indexName || !algoliaWriteKey) {
+    const missing = [
+      !appId && 'PUBLIC_ALGOLIA_APP_ID',
+      !indexName && 'PUBLIC_ALGOLIA_INDEX',
+      !algoliaWriteKey && 'PRIVATE_ALGOLIA_WRITE_KEY',
+    ].filter(Boolean);
+    console.warn(`⚠️ Skipping Algolia indexing due to missing environment variables: ${missing.join(', ')}`);
+    return;
+  }
+  await buildIndex(appId, indexName, algoliaWriteKey, sdkJson, renderMarkdown);
+  console.log('Indexing complete.');
+}

package/plugin/cms/client.ts

@@ -0,0 +1,62 @@
+import { CMS_PORT } from 'virtual:stl-starlight-virtual-module';
+import type { SpecResp } from './server';
+import type { StarlightRouteData } from '@astrojs/starlight/route-data';
+import type { BuildSidebarParams } from './sidebar-builder';
+
+const SERVER_URL = `http://localhost:${CMS_PORT}`;
+
+async function makeRequest<T>(method: 'POST' | 'GET', endpoint: string, body?: any) {
+  const response = await fetch(`${SERVER_URL}${endpoint}`, {
+    method,
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  return response.json() as T;
+}
+
+class Client {
+  private specCache: SpecResp | null = null;
+  private clientId: string;
+
+  get id() {
+    return this.clientId;
+  }
+
+  async buildSidebar(params: BuildSidebarParams & { sidebarId: number }) {
+    const response = await makeRequest<{ data: StarlightRouteData['sidebar'] }>(
+      'POST',
+      '/build_sidebar',
+      params,
+    );
+    return response.data;
+  }
+
+  async getSpec() {
+    const cached = this.specCache;
+
+    const response = await makeRequest<SpecResp>('POST', '/retrieve_spec', {
+      currentId: cached?.id,
+    });
+
+    if (response.data === null) {
+      if (!cached) {
+        throw new Error('Cache should not be null');
+      }
+      if (cached.data === null) {
+        throw new Error('Cached spec should not be null');
+      }
+      return cached.data;
+    }
+    // console.log("invalidating spec cache", this.clientId);
+    this.specCache = response;
+    return response.data;
+  }
+
+  constructor() {
+    this.clientId = crypto.randomUUID();
+  }
+}
+
+export const cmsClient = new Client();

package/plugin/cms/server.ts

@@ -0,0 +1,268 @@
+import { createServer, IncomingMessage } from 'http';
+import { readFile } from 'fs/promises';
+
+import type * as SDKJSON from '~/lib/json-spec-v2/types';
+import { createSDKJSON, parseInputs, transformOAS } from './worker';
+import { Languages, parseRoute, type DocsLanguage } from '@stainless-api/docs-ui/src/routing';
+import Stainless from '@stainless-api/sdk';
+
+import {
+  toStarlightSidebar,
+  type GeneratedSidebarConfig,
+  SidebarConfigItemsBuilder,
+} from './sidebar-builder';
+import type { VersionUserConfig } from '../loadPluginConfig';
+
+export type InputFilePaths = {
+  oasPath?: string;
+  configPath?: string;
+};
+
+async function versionInfo(project: string, apiKey: string) {
+  const data = await fetch(`https://api.stainless.com/api/projects/${project}/package-versions`, {
+    headers: { Authorization: `Bearer ${apiKey}` },
+  });
+
+  const content = await data.text();
+  return JSON.parse(content);
+}
+
+async function loadSpec({
+  apiKey,
+  devPaths,
+  version,
+}: {
+  apiKey: string;
+  devPaths: InputFilePaths;
+  version: VersionUserConfig;
+}) {
+  let oasStr: string;
+  let configStr: string;
+  let versions: Record<DocsLanguage, string> | undefined;
+
+  if (devPaths.oasPath && devPaths.configPath) {
+    [oasStr, configStr] = await Promise.all([
+      readFile(devPaths.oasPath, 'utf-8'),
+      readFile(devPaths.configPath, 'utf-8'),
+    ]);
+  } else {
+    const client = new Stainless({ apiKey });
+    const configs = await client.projects.configs.retrieve({
+      project: version.stainlessProject,
+      branch: version.branch,
+      include: 'openapi',
+    });
+
+    versions = await versionInfo(version.stainlessProject, apiKey);
+
+    const configYML = Object.values(configs)[0] as { content: any };
+    const oasJson = Object.values(configs)[1] as { content: any };
+    oasStr = oasJson['content'];
+    configStr = configYML['content'];
+  }
+
+  const { oas, config } = await parseInputs({
+    oas: oasStr,
+    config: configStr,
+  });
+
+  const transformedOAS = await transformOAS({ oas, config });
+
+  const languages =
+    config.docs?.languages ??
+    (Object.entries(config.targets)
+      // @ts-expect-error we don't have the actual Stainless config type here
+      .filter(([name, target]) => Languages.includes(name) && !target.skip)
+      .map(([name]) => name) as SDKJSON.SpecLanguage[]);
+
+  const sdkJson = await createSDKJSON({
+    oas: transformedOAS,
+    config,
+    languages,
+  });
+
+  if (versions) {
+    for (const [lang, version] of Object.entries(versions)) {
+      const meta = sdkJson.metadata[lang as DocsLanguage];
+      if (meta?.version) meta.version = version;
+    }
+  }
+
+  const id = crypto.randomUUID();
+
+  return {
+    data: sdkJson,
+    id,
+  };
+}
+
+class Spec {
+  private specPromise: Promise<{ id: string; data: SDKJSON.Spec }>;
+  private devPaths: InputFilePaths;
+  private apiKey: string;
+  private version: VersionUserConfig;
+
+  reload() {
+    this.specPromise = loadSpec({
+      apiKey: this.apiKey,
+      devPaths: this.devPaths,
+      version: this.version,
+    });
+  }
+
+  async forceGetSpec() {
+    const spec = await this.specPromise;
+    return spec;
+  }
+
+  async getSpec(currentId: string | undefined | null) {
+    const spec = await this.specPromise;
+
+    if (currentId === spec.id) {
+      return {
+        id: spec.id,
+        data: null,
+      };
+    }
+
+    return spec;
+  }
+
+  constructor(apiKey: string, version: VersionUserConfig, devPaths: InputFilePaths) {
+    this.specPromise = loadSpec({
+      apiKey,
+      devPaths,
+      version,
+    });
+    this.devPaths = devPaths;
+    this.apiKey = apiKey;
+    this.version = version;
+  }
+}
+
+export type SpecResp = Awaited<ReturnType<Spec['getSpec']>>;
+
+// will be necessary once we add POST methods
+function readJsonBody(req: IncomingMessage): Promise<any> {
+  return new Promise((resolve, reject) => {
+    let body = '';
+    req.on('data', (chunk) => {
+      body += chunk.toString();
+    });
+    req.on('end', () => {
+      try {
+        const data = JSON.parse(body);
+        resolve(data);
+      } catch (error) {
+        reject(error);
+      }
+    });
+  });
+}
+
+export function startDevServer({
+  port,
+  version,
+  devPaths,
+  apiKey,
+  getGeneratedSidebarConfig,
+}: {
+  port: number;
+  version: VersionUserConfig;
+  devPaths: InputFilePaths;
+  apiKey: string;
+  getGeneratedSidebarConfig: (id: number) => GeneratedSidebarConfig | null;
+}) {
+  const spec = new Spec(apiKey, version, devPaths);
+
+  const server = createServer(async (req, res) => {
+    // Add CORS headers
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+
+    // Handle preflight requests
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    function respond(code: number, body: any) {
+      res.setHeader('Content-Type', 'application/json');
+      res.writeHead(code);
+      res.end(JSON.stringify(body));
+    }
+
+    try {
+      if (req.method === 'POST' && req.url === '/retrieve_spec') {
+        const body = await readJsonBody(req);
+
+        const currentSpec = await spec.getSpec(body.currentId);
+
+        return respond(200, currentSpec);
+      }
+
+      if (req.method === 'POST' && req.url === '/build_sidebar') {
+        const currentSpec = await spec.forceGetSpec();
+        const body = await readJsonBody(req);
+        const sidebarId: number = body.sidebarId;
+
+        const sidebarConfig = getGeneratedSidebarConfig(sidebarId);
+
+        const sidebarGenerateOptions = sidebarConfig?.options;
+
+        const { stainlessPath: currentStainlessPath, language } = parseRoute(body.basePath, body.currentSlug);
+
+        const configItemsBuilder = new SidebarConfigItemsBuilder(
+          currentSpec.data,
+          language,
+          sidebarGenerateOptions,
+        );
+
+        let userSidebarConfig = configItemsBuilder.generateItems();
+
+        if (sidebarConfig && sidebarConfig.transformFn) {
+          const transformedSidebarConfig = sidebarConfig.transformFn(userSidebarConfig, language);
+          // the user may not have returned, but they may have mutated the config in place
+          // if they did return, we use that
+          if (transformedSidebarConfig) {
+            userSidebarConfig = transformedSidebarConfig;
+          }
+        }
+
+        const starlightSidebar = toStarlightSidebar({
+          basePath: body.basePath,
+          currentSlug: body.currentSlug,
+          spec: currentSpec.data,
+          entries: userSidebarConfig,
+          currentStainlessPath,
+          currentLanguage: language,
+        });
+
+        return respond(200, { data: starlightSidebar });
+      }
+
+      return respond(404, { message: 'Not found' });
+    } catch (e) {
+      return respond(500, { message: 'Unexpected error', error: e });
+    }
+  });
+
+  server.listen(port, () => {
+    console.log(`Server is running on port ${port}`);
+  });
+
+  return {
+    invalidate: () => {
+      spec.reload();
+    },
+    destroy: function destroy() {
+      return new Promise<void>((resolve) => {
+        server.close(() => {
+          resolve();
+        });
+      });
+    },
+  };
+}