feat: add tryitnow for usage snippets through code samples API

packages/docs-md/assets/TryItNow/index.tsx

@@ -92,7 +92,7 @@ export const TryItNow = ({
           entry: "index.tsx",
           ...sandpackSetupOptions,
         }}
-        theme="auto"
+        theme="dark"
       >
         <SandpackLayout>
           <SandpackPreview style={styles.preview} />

packages/docs-md/src/cli/cli.ts

@@ -26,6 +26,7 @@ const CONFIG_FILE_NAMES = [
 ];
 
 const args = arg({
+  "--npm-package-name": String,
   "--help": Boolean,
   "--config": String,
   "--spec": String,
@@ -37,6 +38,7 @@ const args = arg({
   "-p": "--page-out-dir",
   "-o": "--component-out-dir",
   "-f": "--framework",
+  "-n": "--npm-package-name",
 });
 
 function printHelp() {
@@ -48,7 +50,8 @@ Options:
   --spec, -s     Path to OpenAPI spec
   --page-out-dir, -p  Output directory for page contents
   --component-out-dir, -o  Output directory for component contents
-  --framework, -f  Framework to use (docusaurus, nextra)`);
+  --framework, -f  Framework to use (docusaurus, nextra)
+  --npm-package-name, -n  npm package to use for the SDK code snippets`);
 }
 
 if (args["--help"]) {

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

@@ -0,0 +1,68 @@
+import { basename } from "node:path";
+
+import type { Chunk, OperationChunk } from "../types/chunk.ts";
+import type {
+  CodeSamplesResponse,
+  CodeSnippet,
+  ErrorResponse,
+} from "../types/codeSnippet.ts";
+import { getSettings } from "./settings.ts";
+
+const CODE_SNIPPETS_API_URL = "http://localhost:35290";
+
+export type DocsCodeSnippets = Record<OperationChunk["id"], CodeSnippet>;
+
+export const generateDocsCodeSnippets = async (
+  docsData: Map<string, Chunk>,
+  specContents: string
+): Promise<DocsCodeSnippets> => {
+  const { spec, tryItNow } = getSettings();
+  if (!tryItNow) {
+    return {};
+  }
+
+  const docsCodeSnippets: DocsCodeSnippets = {};
+
+  const specFilename = basename(spec);
+  // create a by operationId map of the operation chunks
+  const operationChunksByOperationId = new Map<string, OperationChunk>();
+  for (const chunk of docsData.values()) {
+    if (chunk.chunkType === "operation") {
+      operationChunksByOperationId.set(chunk.chunkData.operationId, chunk);
+    }
+  }
+  try {
+    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);
+      // only set the usage snippet if the operation id exists in the spec
+      if (chunk) {
+        docsCodeSnippets[chunk.id] = snippet;
+      }
+    }
+  } catch (error) {
+    console.error("There was an error generating code snippets", error);
+    return {};
+  }
+  return docsCodeSnippets;
+};

packages/docs-md/src/generator/docsData/getDocsData.ts

@@ -7,7 +7,6 @@ import { fileURLToPath } from "node:url";
 import { unzipSync } from "node:zlib";
 
 import type { Chunk } from "../../types/chunk.ts";
-
 declare class Go {
   argv: string[];
   env: { [envKey: string]: string };
@@ -32,8 +31,10 @@ export async function getDocsData(
   const result = await WebAssembly.instantiate(wasmBuffer, go.importObject);
   void go.run(result.instance);
   const serializedDocsData = await SerializeDocsData(specContents);
+
   const docsData = (JSON.parse(serializedDocsData) as string[]).map(
     (chunk) => JSON.parse(chunk) as Chunk
   );
+
   return new Map(docsData.map((chunk) => [chunk.id, chunk]));
 }

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

@@ -1,4 +1,6 @@
 import type { Chunk, OperationChunk } from "../../../types/chunk.ts";
+import type { DocsCodeSnippets } from "../../codeSnippets.ts";
+import { getSettings } from "../../settings.ts";
 import type { Renderer, Site } from "../renderer.ts";
 import { getSchemaFromId } from "../util.ts";
 import { renderSchema } from "./schema.ts";
@@ -9,6 +11,7 @@ type RenderOperationOptions = {
   chunk: OperationChunk;
   docsData: Map<string, Chunk>;
   baseHeadingLevel: number;
+  docsCodeSnippets: DocsCodeSnippets;
 };
 
 export function renderOperation({
@@ -17,6 +20,7 @@ export function renderOperation({
   chunk,
   docsData,
   baseHeadingLevel,
+  docsCodeSnippets,
 }: RenderOperationOptions) {
   renderer.appendHeading(
     baseHeadingLevel,
@@ -90,6 +94,22 @@ export function renderOperation({
     }
   }
 
+  const { tryItNow } = getSettings();
+
+  const usageSnippet = docsCodeSnippets[chunk.id];
+  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",
+        [tryItNow.npmPackageName]: "latest",
+      },
+      defaultValue: usageSnippet.code,
+    });
+  }
+
   if (chunk.chunkData.requestBody) {
     renderer.appendHeading(
       baseHeadingLevel + 1,

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

@@ -2,6 +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 { getSettings } from "../settings.ts";
 import { renderAbout } from "./chunks/about.ts";
 import { renderOperation } from "./chunks/operation.ts";
@@ -144,7 +145,12 @@ function getPageMap(data: Data) {
   return pageMap;
 }
 
-function renderPages(site: Site, pageMap: PageMap, data: Map<string, Chunk>) {
+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);
@@ -195,6 +201,7 @@ function renderPages(site: Site, pageMap: PageMap, data: Map<string, Chunk>) {
             chunk,
             docsData: data,
             baseHeadingLevel: 2,
+            docsCodeSnippets,
           });
           break;
         }
@@ -280,13 +287,15 @@ function renderScaffoldSupport(site: Site) {
   }
 }
 
-export function generateContent(data: Data): 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);
-
   // Then, render each page
   const site = new Site();
-  renderPages(site, pageMap, data);
+  renderPages(site, pageMap, data, docsCodeSnippets);
 
   // Now do any post-processing needed by the scaffold
   renderScaffoldSupport(site);

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

@@ -231,7 +231,12 @@ sidebarTitle: ${this.escapeText(sidebarLabel)}
 
   // TODO: need to type this properly, but we can't import types from assets
   // since they can't be built as part of this TS project
-  public appendTryItNow(props: Record<string, unknown> = {}) {
+  public appendTryItNow(
+    props: {
+      externalDependencies?: Record<string, string>;
+      defaultValue?: string;
+    } & Record<string, unknown>
+  ) {
     this.insertComponentImport("TryItNow", "TryItNow/index.tsx");
     const escapedProps = Object.fromEntries(
       Object.entries(props).map(([key, value]) => [
@@ -241,7 +246,9 @@ sidebarTitle: ${this.escapeText(sidebarLabel)}
           : JSON.stringify(value),
       ])
     );
-    this.#lines.push(`<TryItNow {...${JSON.stringify(escapedProps)}} />`);
+    this.#lines.push(
+      `<TryItNow {...${JSON.stringify(escapedProps)}} externalDependencies={${JSON.stringify(props.externalDependencies)}} defaultValue={\`${props.defaultValue}\`} />`
+    );
   }
 
   public finalize() {

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

@@ -0,0 +1,14 @@
+export type CodeSnippet = {
+  operationId: string;
+  language: string;
+  code: string;
+};
+
+export type CodeSamplesResponse = {
+  snippets: CodeSnippet[];
+};
+
+export type ErrorResponse = {
+  message: string;
+  statusCode: number;
+};

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

@@ -26,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>;

scaffold-templates/docusaurus/package.json

@@ -16,6 +16,8 @@
     "typecheck": "tsc"
   },
   "dependencies": {
+    "@codesandbox/sandpack-client": "^2.19.8",
+    "@codesandbox/sandpack-react": "^2.20.0",
     "@docusaurus/core": "3.7.0",
     "@docusaurus/preset-classic": "3.7.0",
     "@mdx-js/react": "^3.0.0",

scaffold-templates/nextra/package.json

@@ -13,6 +13,8 @@
   "license": "ISC",
   "description": "",
   "dependencies": {
+    "@codesandbox/sandpack-client": "^2.19.8",
+    "@codesandbox/sandpack-react": "^2.20.0",
     "@radix-ui/colors": "^3.0.0",
     "@speakeasy-api/docs-md": "^0.1.0-beta3",
     "jotai": "^2.12.5",