@stainless-api/docs 0.1.0-beta.9 → 0.1.0-beta.90

package/plugin/specs/index.ts

@@ -0,0 +1,238 @@
+import Stainless, { APIError } from '@stainless-api/sdk';
+import { mkdir, readdir, readFile, rm, writeFile } from 'fs/promises';
+import path from 'path';
+import crypto from 'crypto';
+
+import type * as VirtualManifestModule from 'virtual:stainless-sdk-json-manifest';
+
+import { makeAsyncVirtualModPlugin } from '../../shared/virtualModule';
+
+import { NormalizedStainlessStarlightConfig, SDKJSONInputs } from '../loadPluginConfig';
+
+import { generateSpecFromStrings, SpecWithAuth } from './generateSpec';
+import previewWorkerCode from '../vendor/preview.worker.docs.js?raw';
+import { DocsLanguage } from '@stainless-api/docs-ui/routing';
+import { AstroIntegrationLogger } from 'astro';
+import { bold } from '../../shared/terminalUtils';
+
+type VirtualManifestModuleType = typeof VirtualManifestModule;
+
+async function cleanupSpecsDirectory({
+  directory,
+  keep,
+  logger,
+}: {
+  directory: string;
+  keep: string[];
+  logger: AstroIntegrationLogger;
+}) {
+  const files = await readdir(directory);
+  const filesToDelete = files.filter((file) => !keep.includes(file));
+
+  if (filesToDelete.length > 0) {
+    await Promise.all(filesToDelete.map((file) => rm(path.join(directory, file))));
+    logger.info(`Removed ${filesToDelete.length} unused SDKJSON file(s)`);
+  }
+}
+
+type ResolvedSpecInputs = {
+  oasStr: string;
+  configStr: string;
+  versions: Record<DocsLanguage, string> | null;
+  project: string;
+};
+
+async function versionInfo(project: string, apiKey: string): Promise<Record<DocsLanguage, 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) as Record<DocsLanguage, string>;
+}
+
+function redactApiKey(apiKey: string) {
+  return apiKey
+    .split('')
+    .map((char, index) => (index < 10 ? char : '*'))
+    .join('');
+}
+
+async function resolveFileInputs(
+  inputs: Extract<SDKJSONInputs, { kind: 'file_inputs' }>,
+  logger: AstroIntegrationLogger,
+) {
+  try {
+    const oasStr = await readFile(inputs.oasPath, 'utf8');
+    const configStr = await readFile(inputs.configPath, 'utf8');
+    return {
+      inputs,
+      resolved: {
+        oasStr,
+        configStr,
+        versions: null,
+        project: inputs.project,
+      },
+    };
+  } catch (error) {
+    logger.error(bold('Failed to read file inputs:'));
+    logger.error(error instanceof Error ? error.message : 'Unknown error');
+    process.exit(1);
+  }
+}
+
+async function resolveStainlessApiInputs(
+  inputs: Extract<SDKJSONInputs, { kind: 'stainless_api_inputs' }>,
+  logger: AstroIntegrationLogger,
+) {
+  try {
+    const client = new Stainless({ apiKey: inputs.apiKey.value });
+    const configs = await client.projects.configs.retrieve({
+      project: inputs.project,
+      branch: inputs.branch,
+      include: 'openapi',
+    });
+    const versions = await versionInfo(inputs.project, inputs.apiKey.value);
+
+    const configYML = Object.values(configs)[0] as { content: unknown };
+    const oasJson = Object.values(configs)[1] as { content: unknown };
+    const oasStr = oasJson['content'];
+    const configStr = configYML['content'];
+
+    if (typeof oasStr !== 'string' || typeof configStr !== 'string') {
+      throw new Error('Received invalid OAS or config from Stainless');
+    }
+
+    return {
+      inputs,
+      resolved: {
+        versions,
+        oasStr,
+        configStr,
+        project: inputs.project,
+      },
+    };
+  } catch (error) {
+    logger.error(bold('Failed to fetch API reference information from Stainless:'));
+    if (error instanceof APIError && error.status >= 400 && error.status < 500) {
+      logger.error(`Requested project slug: "${inputs.project}"`);
+      logger.error(`API key: "${redactApiKey(inputs.apiKey.value)}"`);
+      logger.error(
+        `This error can usually be corrected by re-authenticating with the Stainless.  Use the CLI (stl auth login) or verify that the Stainless API key you're using can access the project mentioned above.`,
+      );
+    } else {
+      logger.error(error instanceof Error ? error.message : 'Unknown error');
+    }
+
+    process.exit(1);
+  }
+}
+
+async function resolveStringInputs(inputs: Extract<SDKJSONInputs, { kind: 'string_inputs' }>) {
+  return {
+    inputs,
+    resolved: {
+      oasStr: inputs.oasStr,
+      configStr: inputs.configStr,
+      versions: null,
+      project: inputs.project,
+    },
+  };
+}
+
+async function resolveSpecInputs(
+  inputs: SDKJSONInputs,
+  logger: AstroIntegrationLogger,
+): Promise<{ inputs: SDKJSONInputs; resolved: ResolvedSpecInputs }> {
+  if (inputs.kind === 'file_inputs') return resolveFileInputs(inputs, logger);
+  if (inputs.kind === 'stainless_api_inputs') return resolveStainlessApiInputs(inputs, logger);
+  if (inputs.kind === 'string_inputs') return resolveStringInputs(inputs);
+  throw new Error(`Unexpected spec inputs: ${JSON.stringify(inputs)}`);
+}
+
+function hashResolvedSpecInputs(resolved: ResolvedSpecInputs): string {
+  return crypto
+    .createHash('sha256')
+    .update(resolved.oasStr + resolved.configStr + JSON.stringify(resolved.versions) + previewWorkerCode)
+    .digest('hex')
+    .slice(0, 10);
+}
+
+async function readCachedSpec(specPath: string): Promise<SpecWithAuth | null> {
+  try {
+    const cachedSpec = await readFile(specPath, 'utf8');
+    return JSON.parse(cachedSpec) as SpecWithAuth;
+  } catch {
+    return null;
+  }
+}
+
+async function fetchOrGenerateSpec(specPath: string, inputs: ResolvedSpecInputs) {
+  const cachedSpec = await readCachedSpec(specPath);
+  if (cachedSpec) {
+    return {
+      result: 'exists' as const,
+      specPath,
+      spec: cachedSpec,
+    };
+  }
+
+  const sdkJson = await generateSpecFromStrings({
+    oasStr: inputs.oasStr,
+    configStr: inputs.configStr,
+    projectName: inputs.project,
+  });
+
+  if (inputs.versions) {
+    for (const [lang, version] of Object.entries(inputs.versions)) {
+      const meta = sdkJson.data.metadata[lang as DocsLanguage];
+      if (meta?.version) meta.version = version;
+    }
+  }
+
+  await writeFile(specPath, JSON.stringify(sdkJson), 'utf8');
+
+  return {
+    result: 'generated' as const,
+    spec: sdkJson,
+    specPath,
+  };
+}
+
+/** Runs once in the build process */
+export async function startSpecLoader(
+  pluginConfig: NormalizedStainlessStarlightConfig,
+  logger: AstroIntegrationLogger,
+  codegenDir: URL,
+) {
+  const specsDirectory = path.join(codegenDir.pathname, 'specs');
+  await mkdir(specsDirectory, { recursive: true });
+  // TODO: can this promise also be deferred until after this function resolves? can this whole
+  // function return synchronously?
+  // TODO: arena to remember the conceptual reason why he didn’t want this
+  const resolvedSpecInputs = await resolveSpecInputs(pluginConfig.specInputs, logger);
+
+  const inputsHash = hashResolvedSpecInputs(resolvedSpecInputs.resolved);
+  const specFileName = `${inputsHash}.json`;
+  const specPath = path.join(specsDirectory, specFileName);
+
+  const specPromise = fetchOrGenerateSpec(specPath, resolvedSpecInputs.resolved);
+
+  // don't need to await, it's just cleanup
+  cleanupSpecsDirectory({ directory: specsDirectory, keep: [specFileName], logger });
+
+  return {
+    specPromise,
+    // this virtual module only resolves when the spec is generated
+    // this prevents the SSR module from trying to read the spec file before it's generated
+    vitePlugin: makeAsyncVirtualModPlugin<VirtualManifestModuleType>(
+      'virtual:stainless-sdk-json-manifest',
+      async () => {
+        const specResult = await specPromise;
+        return { specPath: specResult.specPath };
+      },
+    ),
+  };
+}
+
+export type SpecLoader = Awaited<ReturnType<typeof startSpecLoader>>;

package/plugin/{cms → specs}/worker.ts

@@ -1,6 +1,6 @@
 import Worker from 'web-worker';
-import { Languages, type DocsLanguage } from '@stainless-api/docs-ui/src/routing';
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
+import { Languages, type DocsLanguage } from '@stainless-api/docs-ui/routing';
+import type * as SDKJSON from '@stainless/sdk-json';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 import fs from 'fs/promises';
@@ -12,7 +12,81 @@ const __dirname = dirname(__filename);
 const workerPath = resolve(__dirname, '..', 'vendor', 'preview.worker.docs.js');
 
 type OpenAPIDocument = Record<string, any>;
-type ParsedConfig = Record<string, any>;
+export type ParsedConfig = {
+  docs:
+    | {
+        title?: string | undefined;
+        favicon?: string | undefined;
+        logo_icon?: string | undefined;
+        search?:
+          | {
+              algolia?:
+                | {
+                    app_id: string;
+                    index_name: string;
+                    search_key: string;
+                  }
+                | undefined;
+            }
+          | undefined;
+        description?: string | undefined;
+        languages?:
+          | ('node' | 'typescript' | 'python' | 'java' | 'kotlin' | 'go' | 'ruby' | 'terraform' | 'http')[]
+          | undefined;
+        snippets?:
+          | {
+              exclude_languages?: string[] | undefined;
+            }
+          | undefined;
+        show_security?: boolean | undefined;
+        show_readme?: boolean | undefined;
+        base_path?: string | undefined;
+        navigation?:
+          | {
+              menubar?:
+                | {
+                    title: string;
+                    icon?: string;
+                    variant?: string;
+                    href?: string | undefined;
+                    page?: string | undefined;
+                  }[]
+                | undefined;
+              sidebar?:
+                | {
+                    title: string;
+                    icon?: string;
+                    variant?: string;
+                    href?: string | undefined;
+                    page?: string | undefined;
+                  }[]
+                | undefined;
+            }
+          | undefined;
+        pages?: unknown;
+        resources?: unknown[] | undefined;
+      }
+    | undefined;
+  targets: Record<string, { skip?: boolean }>;
+  client_settings: {
+    opts: {
+      [x: 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;
+      };
+    };
+  };
+};
 
 function runJob({ type, signal, data }: { type: string; signal?: AbortSignal; data: any }) {
   const stainlessWorker = new Worker(workerPath, {
@@ -22,6 +96,7 @@ function runJob({ type, signal, data }: { type: string; signal?: AbortSignal; da
 
   return new Promise<any>((resolve, reject) => {
     stainlessWorker.addEventListener('error', (e) => {
+      e.preventDefault();
       reject(e);
     });
 
@@ -85,10 +160,12 @@ export async function createSDKJSON({
   oas,
   config,
   languages,
+  projectName,
 }: {
   oas: OpenAPIDocument;
   config: ParsedConfig;
   languages: DocsLanguage[];
+  projectName: string;
 }) {
   const templatePath = resolve(__dirname, '../vendor/templates');
   const readmeLoader = await Promise.all(
@@ -98,7 +175,7 @@ export async function createSDKJSON({
       try {
         const content = await fs.readFile(mdfile);
         return [language, content.toString()];
-      } catch (err) {
+      } catch {
         return [language, null];
       }
     }),
@@ -113,7 +190,7 @@ export async function createSDKJSON({
       config,
       languages,
       transform: false,
-      projectName: '',
+      projectName,
       readmeTemplates,
     },
   });