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

package/plugin/specs/inputResolver.ts

@@ -0,0 +1,148 @@
+import { DocsLanguage } from '@stainless-api/docs-ui/routing';
+import { readFile } from 'fs/promises';
+import { AstroIntegrationLogger } from 'astro';
+import { bold } from '../../shared/terminalUtils';
+import type { LanguageGenerateQuery, LoadedApiKey } from '../loadPluginConfig';
+import Stainless, { APIError } from '@stainless-api/sdk';
+import { GenerateSpecRawInputs } from './generateSpec';
+
+export type SpecInputResolver = {
+  resolve: (context: {
+    apiKey: LoadedApiKey | null;
+  }) => GenerateSpecRawInputs | Promise<GenerateSpecRawInputs>;
+  printError: (error: Error, logger: AstroIntegrationLogger) => void;
+};
+
+function fromFiles({
+  oasPath,
+  configPath,
+  languageOverrides,
+  stainlessProject,
+}: {
+  oasPath: string;
+  configPath: string;
+  languageOverrides: LanguageGenerateQuery | null;
+  stainlessProject: string;
+}): SpecInputResolver {
+  return {
+    resolve: async () => {
+      const oasStr = await readFile(oasPath, 'utf8');
+      const configStr = await readFile(configPath, 'utf8');
+      return {
+        oasStr,
+        configStr,
+        versionInfo: null,
+        languageOverrides,
+        stainlessProject,
+      };
+    },
+    printError: (error: Error, logger: AstroIntegrationLogger) => {
+      logger.error(bold('Failed to resolve spec inputs from files:'));
+      logger.error(error.message);
+    },
+  };
+}
+
+async function fetchVersionInfo(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('');
+}
+
+function fromStainlessApi(inputs: {
+  stainlessProject: string;
+  branch: string;
+  apiKey?: LoadedApiKey;
+  languageOverrides: LanguageGenerateQuery | null;
+}): SpecInputResolver {
+  let apiKey: string | undefined;
+  return {
+    async resolve(context) {
+      apiKey = context.apiKey?.value ?? inputs.apiKey?.value;
+
+      if (!apiKey) {
+        throw new Error('No API key provided');
+      }
+
+      const client = new Stainless({ apiKey });
+      const configs = await client.projects.configs.retrieve({
+        project: inputs.stainlessProject,
+        branch: inputs.branch,
+        include: 'openapi',
+      });
+      const versionInfo = await fetchVersionInfo(inputs.stainlessProject, apiKey);
+
+      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 {
+        oasStr,
+        configStr,
+        versionInfo,
+        languageOverrides: inputs.languageOverrides,
+        stainlessProject: inputs.stainlessProject,
+      };
+    },
+    printError: (error: Error, logger: AstroIntegrationLogger) => {
+      if (error instanceof APIError && error.status >= 400 && error.status < 500) {
+        logger.error(`Requested project slug: "${inputs.stainlessProject}"`);
+        if (apiKey) {
+          logger.error(`API key: "${redactApiKey(apiKey)}"`);
+        }
+        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.`,
+        );
+      }
+    },
+  };
+}
+
+function fromStrings({
+  oasStr,
+  configStr,
+  languageOverrides,
+  stainlessProject,
+}: {
+  oasStr: string;
+  configStr: string;
+  languageOverrides: LanguageGenerateQuery | null;
+  stainlessProject: string;
+}): SpecInputResolver {
+  return {
+    resolve() {
+      return {
+        oasStr,
+        configStr,
+        versionInfo: null,
+        languageOverrides,
+        stainlessProject,
+      };
+    },
+    printError(error: Error, logger: AstroIntegrationLogger) {
+      logger.error(bold('Failed to resolve spec inputs from strings:'));
+      logger.error(error.message);
+    },
+  };
+}
+
+export const resolveSpec = {
+  fromFiles,
+  fromStainlessApi,
+  fromStrings,
+} satisfies Record<string, (...args: never[]) => SpecInputResolver>;

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,
     },
   });