Fleshed out settings so that try-it-now is optional

Author: nebrius

packages/docs-md/src/generator/codeSnippets.ts

@@ -10,42 +10,17 @@ import { getSettings } from "./settings.ts";
 
 const CODE_SNIPPETS_API_URL = "http://api.speakeasy.com";
 
-async function fetchCodeSnippets(
-  language: string,
-  schemeFile: {
-    fileName: string;
-    content: string;
-  },
-  packageName: string
-): Promise<CodeSnippet[]> {
-  const formData = new FormData();
-
-  const blob = new Blob([schemeFile.content]);
-  formData.append("language", language);
-  formData.append("schema_file", blob, schemeFile.fileName);
-  formData.append("package_name", packageName);
-
-  const res = await fetch(`${CODE_SNIPPETS_API_URL}/v1/code_sample/preview`, {
-    method: "POST",
-    body: formData,
-  });
-
-  const json = (await res.json()) as unknown;
-
-  if (!res.ok) {
-    const error = json as ErrorResponse;
-    throw new Error(`Failed to generate code sample: ${error.message}`);
-  }
-  return (json as CodeSamplesResponse).snippets;
-}
-
 export type DocsCodeSnippets = Record<OperationChunk["id"], CodeSnippet>;
 
 export const generateDocsCodeSnippets = async (
   docsData: Map<string, Chunk>,
   specContents: string
 ): Promise<DocsCodeSnippets> => {
-  const { spec, npmPackageName } = getSettings();
+  const { spec, tryItNow } = getSettings();
+  if (!tryItNow) {
+    return {};
+  }
+
   const docsCodeSnippets: DocsCodeSnippets = {};
 
   const specFilename = basename(spec);
@@ -57,14 +32,26 @@ export const generateDocsCodeSnippets = async (
     }
   }
   try {
-    const codeSnippets = await fetchCodeSnippets(
-      "typescript",
-      {
-        fileName: specFilename,
-        content: specContents,
-      },
-      npmPackageName
-    );
+    const formData = new FormData();
+
+    const blob = new Blob([specContents]);
+    formData.append("language", "typescript");
+    formData.append("schema_file", blob, specFilename);
+    formData.append("package_name", tryItNow.npmPackageName);
+    formData.append("sdk_class_name", tryItNow.sdkClassName);
+
+    const res = await fetch(`${CODE_SNIPPETS_API_URL}/v1/code_sample/preview`, {
+      method: "POST",
+      body: formData,
+    });
+
+    const json = (await res.json()) as unknown;
+
+    if (!res.ok) {
+      const error = json as ErrorResponse;
+      throw new Error(`Failed to generate code sample: ${error.message}`);
+    }
+    const codeSnippets = (json as CodeSamplesResponse).snippets;
 
     for (const snippet of codeSnippets) {
       const chunk = operationChunksByOperationId.get(snippet.operationId);

packages/docs-md/src/generator/generatePages.ts

@@ -1,4 +1,5 @@
 import type { Settings } from "../types/settings.ts";
+import { generateDocsCodeSnippets } from "./codeSnippets.ts";
 import { getDocsData } from "./docsData/getDocsData.ts";
 import { generateContent } from "./mdx/generateContent.ts";
 import { setSettings } from "./settings.ts";
@@ -18,9 +19,14 @@ export async function generatePages({
   setSettings(settings);
 
   // Get the docs data from the spec
+  console.log("Getting docs data");
   const data = await getDocsData(specContents);
 
+  // Get code snippets
+  console.log("Generating code snippets");
+  const docsCodeSnippets = await generateDocsCodeSnippets(data, specContents);
+
   // Generate the content
   console.log("Generating Markdown pages");
-  return generateContent(data);
+  return generateContent(data, docsCodeSnippets);
 }

packages/docs-md/src/generator/mdx/chunks/operation.ts

@@ -12,7 +12,7 @@ type RenderOperationOptions = {
   docsData: Map<string, Chunk>;
   baseHeadingLevel: number;
   docsCodeSnippets: DocsCodeSnippets;
-}
+};
 
 export function renderOperation({
   renderer,
@@ -94,14 +94,17 @@ export function renderOperation({
     }
   }
 
+  const { tryItNow } = getSettings();
+
   const usageSnippet = docsCodeSnippets[chunk.id];
-  if (usageSnippet) {
+  if (usageSnippet && tryItNow) {
+    renderer.appendHeading(baseHeadingLevel + 1, "Try it Now");
     // TODO: Zod is actually hard coded for now since its always a dependency
     // in our SDKs. Ideally this will come from the SDK package.
     renderer.appendTryItNow({
       externalDependencies: {
         zod: "^3.25.64",
-        [getSettings().npmPackageName]: "latest",
+        [tryItNow.npmPackageName]: "latest",
       },
       defaultValue: usageSnippet.code,
     });

packages/docs-md/src/generator/mdx/generateContent.ts

@@ -2,8 +2,7 @@ import { join, resolve } from "node:path";
 
 import type { Chunk, SchemaChunk, TagChunk } from "../../types/chunk.ts";
 import { assertNever } from "../../util/assertNever.ts";
-import type { DocsCodeSnippets} from "../codeSnippets.ts";
-import { generateDocsCodeSnippets } from "../codeSnippets.ts";
+import type { DocsCodeSnippets } from "../codeSnippets.ts";
 import { getSettings } from "../settings.ts";
 import { renderAbout } from "./chunks/about.ts";
 import { renderOperation } from "./chunks/operation.ts";
@@ -146,8 +145,12 @@ function getPageMap(data: Data) {
   return pageMap;
 }
 
-function renderPages(site: Site, pageMap: PageMap, data: Map<string, Chunk>, docsCodeSnippets: DocsCodeSnippets) {
-
+function renderPages(
+  site: Site,
+  pageMap: PageMap,
+  data: Map<string, Chunk>,
+  docsCodeSnippets: DocsCodeSnippets
+) {
   for (const [currentPagePath, pageMapEntry] of pageMap) {
     if (pageMapEntry.type === "renderer") {
       const renderer = site.createPage(currentPagePath);
@@ -284,11 +287,12 @@ function renderScaffoldSupport(site: Site) {
   }
 }
 
-export async function generateContent(data: Data): Promise<Record<string, string>> {
+export function generateContent(
+  data: Data,
+  docsCodeSnippets: DocsCodeSnippets
+): Record<string, string> {
   // First, get a mapping of pages to chunks
   const pageMap = getPageMap(data);
-  const { spec } = getSettings();
-  const docsCodeSnippets = await generateDocsCodeSnippets(data, spec);
   // Then, render each page
   const site = new Site();
   renderPages(site, pageMap, data, docsCodeSnippets);

packages/docs-md/src/types/settings.ts

@@ -2,7 +2,6 @@ import { z } from "zod";
 
 export const settingsSchema = z.strictObject({
   spec: z.string(),
-  npmPackageName: z.string(),
   output: z.strictObject({
     pageOutDir: z.string(),
     componentOutDir: z.string(),
@@ -27,6 +26,12 @@ export const settingsSchema = z.strictObject({
       suggestions: z.array(z.string()).optional(),
     })
     .optional(),
+  tryItNow: z
+    .strictObject({
+      npmPackageName: z.string(),
+      sdkClassName: z.string(),
+    })
+    .optional(),
 });
 
 export type Settings = z.infer<typeof settingsSchema>;