import { createHash } from "node:crypto"; import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"; import { join } from "node:path"; const GETTING_STARTED_SECTION = { group: "Introduction", pages: ["developer/api/quickstart", "developer/api/getting-started"], }; const docsJsonPath = join(import.meta.dirname, "..", "docs.json"); const apiRefDir = join(import.meta.dirname, "..", "api-reference"); const openapiPath = join( import.meta.dirname, "..", "..", "backend", "public", "openapi.json", ); const docs = readFileSync(docsJsonPath, "utf8"); const docsJson = JSON.parse(docs); const openapiTab = docsJson.navigation.versions[0].tabs.find( (tab) => tab.openapi, ); const openapiRaw = readFileSync(openapiPath, "utf8"); const schema = JSON.parse(openapiRaw); // Write a content hash so Mintlify redeploys when the OpenAPI spec changes, // even if the generated docs.json and MDX files are identical. const openapiHash = createHash("sha256").update(openapiRaw).digest("hex"); writeFileSync( join(import.meta.dirname, "..", ".openapi-hash"), `${openapiHash}\n`, ); const endpoints = schema.paths; const allSchemas = schema.components?.schemas || {}; // Build tag → schema name mapping from response types const tagToSchema = {}; for (const [, methods] of Object.entries(endpoints)) { for (const [, config] of Object.entries(methods)) { const tag = config.tags?.[0]; if (!tag || tagToSchema[tag]) continue; // Natively-routed endpoints aren't in the Stainless-sourced public // OpenAPI spec (the proxy never stamps them with x-group-title), so an // `openapi-schema` index page would fail to resolve at docs build time. // Skip the schema page — these resources still get their per-operation // pages in the nav. if (!config["x-group-title"]) continue; const resp = config.responses?.["200"] || config.responses?.["201"]; if (!resp) continue; const content = resp.content?.["application/json"]; if (!content) continue; const ref = content.schema?.$ref; if (ref) { const schemaName = ref.split("/").pop(); if ( !schemaName.endsWith("ListItem") && !schemaName.endsWith("PageInfo") && allSchemas[schemaName] ) { tagToSchema[tag] = schemaName; } } } } function toKebabCase(str) { return str .replace(/([a-z])([A-Z])/g, "$1-$2") .replace(/([A-Z])([A-Z][a-z])/g, "$1-$2") .toLowerCase(); } function tagToSlug(tag) { return tag.toLowerCase().replace(/\s+/g, "-"); } function toTitleCase(str) { return str .replace(/([a-z])([A-Z])/g, "$1 $2") .replace(/([A-Z])([A-Z][a-z])/g, "$1 $2"); } function escapeYamlString(str) { return str.replace(/\\/g, "\\\\").replace(/"/g, '\\"'); } // Pull the resource description straight from the OpenAPI schema so the // generated index pages (and therefore the llms.txt entries Mintlify builds // from their frontmatter) are never blank. Collapsed to a single line for // YAML; Mintlify truncates the llms.txt entry at ~300 chars, so we cap here // to keep the page meta description sane. function schemaDescription(schemaName) { const raw = allSchemas[schemaName]?.description; if (!raw) return ""; const oneLine = raw.replace(/\s+/g, " ").trim(); if (oneLine.length <= 300) return oneLine; const truncated = oneLine.slice(0, 297); const lastSpace = truncated.lastIndexOf(" "); return `${truncated.slice(0, lastSpace > 0 ? lastSpace : 297)}…`; } function oneLine(str) { return str.replace(/\s+/g, " ").trim(); } // Escape characters MDX would otherwise parse as JSX (`<`) or an expression // (`{`) in plain prose. Type values are emitted inside code spans and so are // exempt; this is only for free-text (descriptions) rendered outside backticks. function mdxSafe(str) { return str.replace(/([<{])/g, "\\$1"); } // Inline-code example value for a field; empty when the field has none. function exampleCell(prop) { if (prop.example === undefined) return ""; const raw = typeof prop.example === "string" ? prop.example : JSON.stringify(prop.example); let s = oneLine(String(raw)).replace(/`/g, ""); if (s.length > 60) s = `${s.slice(0, 57)}…`; return `\`${s.replace(/\|/g, "\\|")}\``; } function refName(ref) { return ref.split("/").pop(); } // Derive a human label for a union variant: an explicit `title`, else the // const value of the discriminator property (e.g. typename: "User"), else a // generic fallback. function variantName(branch, discProp) { if (branch.title) return branch.title; const c = branch.properties?.[discProp || "typename"]?.const; return c || "object"; } // Resolve a property schema to { typeStr, nullable, desc, nested(, variants) }. // `nested` is an inline object schema to render as its own field list, or null. // `nullable` (value may be null — a null branch / "null" type member) is // independent of whether the field is required (which the caller derives from // the parent schema's `required` array). Enum component schemas referenced by // the property's type are returned in `enums` (for inline "Available options"). function resolveProp(prop) { let desc = prop.description || ""; // Nullable via the 3.0 `nullable: true` keyword OR the 3.1 null-in-type / // oneOf-null forms (the branches below OR more in). let nullable = prop.nullable === true; let typeStr = "`object`"; let nested = null; const enums = []; const noteRef = (name) => { if (allSchemas[name]?.enum) enums.push(name); if (!desc) desc = allSchemas[name]?.description || ""; return `\`${name}\``; }; if (prop.$ref) { typeStr = noteRef(refName(prop.$ref)); return { typeStr, nullable, desc, nested, enums }; } const branches = prop.oneOf || prop.anyOf; if (branches) { const discProp = prop.discriminator?.propertyName; const includesNull = (b) => b.type === "null" || (Array.isArray(b.type) && b.type.includes("null")); nullable = nullable || branches.some(includesNull); const nonNull = branches.filter((b) => b.type !== "null"); const variants = []; const parts = nonNull.map((b) => { if (b.$ref) return noteRef(refName(b.$ref)); // Inline object variants (e.g. User/Company on a discriminated union) // carry their fields here; surface them by name and render sub-tables. if (b.properties) { const vName = variantName(b, discProp); variants.push({ name: vName, schema: b }); return `\`${vName}\``; } if (b.type) return `\`${[] .concat(b.type) .filter((t) => t !== "null") .join(" | ")}\``; return "`object`"; }); typeStr = parts.join(" or ") || "`object`"; return { typeStr, nullable, desc, nested, variants, enums }; } if (prop.type !== undefined) { const types = [].concat(prop.type); nullable = nullable || types.includes("null"); const base = types.filter((t) => t !== "null"); if (prop.properties) { typeStr = "`object`"; nested = prop; } else if (base.includes("array")) { const items = prop.items || {}; let itemType = "object"; if (items.$ref) { itemType = refName(items.$ref); if (allSchemas[itemType]?.enum) enums.push(itemType); } else if (items.properties) { nested = items; } else if (items.type) { itemType = [] .concat(items.type) .filter((t) => t !== "null") .join(" | "); } typeStr = `\`array<${itemType}>\``; } else if (base.length) { const fmt = prop.format ? `<${prop.format}>` : ""; typeStr = `\`${base[0]}${fmt}\``; } return { typeStr, nullable, desc, nested, enums }; } if (prop.properties) { nested = prop; } return { typeStr, nullable, desc, nested, enums }; } // Marker at the top of the generated body so regeneration can strip+replace it // idempotently while preserving hand-written prose above it. (MDX comment.) const SCHEMA_SENTINEL = "{/* GENERATED-SCHEMA */}"; // Make a value safe to sit inside a double-quoted JSX attribute. function attrSafe(str) { return String(str).replace(/"/g, "'"); } // Per-field example as an MDX child line (empty when the field has none). function exampleLine(prop) { const ex = exampleCell(prop); return ex ? `Example: ${ex}` : ""; } // Render one property as a Mintlify (native field-row styling // that also serializes into the .md/llms export). Nested objects and union // variants become sections inside it. Emitted flat (no leading // indentation) so MDX never treats nested content as an indented code block. function renderField(name, prop, requiredSet) { const r = resolveProp(prop); // `required` (field is always present) and `nullable` (value may be null) // are independent: a field can be both. Required comes from the parent's // `required` array; `| null` is appended to the type when nullable. const type = `${r.typeStr.replace(/`/g, "")}${r.nullable ? " | null" : ""}`; const attrs = `name="${attrSafe(name)}" type="${attrSafe(type)}"${ requiredSet.has(name) ? " required" : "" }`; const children = []; if (r.desc) children.push(mdxSafe(oneLine(r.desc))); // Enum values inline on the field (matching the live API reference), instead // of a separate section the reader has to cross-reference by name. for (const enumName of r.enums) { const values = allSchemas[enumName]?.enum; if (values?.length) children.push( `Available options: ${values.map((v) => `\`${v}\``).join(", ")}`, ); } const ex = exampleLine(prop); if (ex) children.push(ex); if (r.nested) children.push( `\n\n${renderFields( r.nested, )}`, ); for (const v of r.variants || []) children.push( `\n\n${renderFields( v.schema, )}`, ); if (!children.length) return `\n`; return `\n${children.join("\n\n")}\n\n`; } // Render all properties of an object schema as a flat list of s. function renderFields(objSchema) { const props = objSchema.properties || {}; const requiredSet = new Set(objSchema.required || []); return Object.keys(props) .sort() .map((name) => renderField(name, props[name], requiredSet)) .join("\n"); } // Build a sample value for a schema, mirroring the openapi-schema widget's // example panel: use an explicit `example`/`const` where present, otherwise a // type-based placeholder. Used to emit a JSON example block which — unlike the // widget panel — also lands in the .md/llms export. Depth-capped against cycles. function exampleValue(sch, depth) { if (!sch || depth > 6) return null; if (sch.example !== undefined) return sch.example; if (sch.const !== undefined) return sch.const; if (sch.$ref) return exampleValue(allSchemas[refName(sch.$ref)], depth + 1); const branches = sch.oneOf || sch.anyOf; if (branches) { const b = branches.find((x) => x.type !== "null"); return b ? exampleValue(b, depth + 1) : null; } if (sch.properties) { const obj = {}; for (const k of Object.keys(sch.properties)) obj[k] = exampleValue(sch.properties[k], depth + 1); return obj; } const base = [].concat(sch.type || []).filter((t) => t !== "null"); if (base.includes("array") || sch.items) return [exampleValue(sch.items || {}, depth + 1)]; if (sch.enum) return sch.enum[0]; if (base[0] === "string") return sch.format ? `<${sch.format}>` : ""; if (base[0] === "integer" || base[0] === "number") return 0; if (base[0] === "boolean") return true; if (base[0] === "object") return {}; return null; } // Render a schema (object or discriminated union) into a Markdown body — the // part Mintlify serializes into the page's `.md`/llms export. We render this // ourselves (instead of the `openapi-schema` widget, which only renders in // HTML and exports blank) so the field reference is available to AI agents. // Returns "" when there is nothing tabular to show. function schemaBody(schemaName) { const s = allSchemas[schemaName]; if (!s) return ""; let fields = ""; if (Array.isArray(s.oneOf) && s.discriminator) { const disc = s.discriminator.propertyName; fields += `This object is one of the following variants${ disc ? `, distinguished by \`${disc}\`` : "" }:\n\n`; for (const branch of s.oneOf) { // Variants may be $refs or inline object schemas (PaymentMethod uses // inline branches with a `title` and `const` typename). const vSchema = branch.$ref ? allSchemas[refName(branch.$ref)] : branch; if (!vSchema?.properties) continue; const vName = branch.$ref ? refName(branch.$ref) : variantName(branch, s.discriminator?.propertyName); fields += `### ${toTitleCase(vName || "Variant")}\n\n${renderFields( vSchema, )}\n`; } } else if (s.properties) { fields += renderFields(s); } else { return ""; } // pins the JSON to the floating right-side panel (Mintlify // routes it there on any page) and still serializes into the .md export. const ex = exampleValue(s, 0); const example = ex && typeof ex === "object" ? `\n\n\`\`\`json Example\n${JSON.stringify( ex, null, 2, )}\n\`\`\`\n\n\n\n` : ""; return `${SCHEMA_SENTINEL}\n\n${example}${fields}`.trimEnd() + "\n"; } // Strip a previously generated schema block (from the sentinel to the end) so // regeneration is idempotent while preserving hand-written prose above it. Cuts // only on the sentinel, so hand-written `##` headings are never touched. function stripGeneratedSchema(body) { if (!body) return ""; const idx = body.indexOf(SCHEMA_SENTINEL); return (idx >= 0 ? body.slice(0, idx) : body).trimEnd(); } function getExistingBody(filePath) { if (!existsSync(filePath)) return ""; const existingContent = readFileSync(filePath, "utf8"); const frontmatterMatch = existingContent.match( /^---\n[\s\S]*?\n---\n?([\s\S]*)$/, ); const body = frontmatterMatch?.[1]?.replace(/^\n/, "") ?? ""; return body.trim() ? body : ""; } const groups = {}; for (const endpoint of Object.keys(endpoints)) { for (const method of Object.keys(endpoints[endpoint])) { const config = endpoints[endpoint][method]; // The API Reference tab renders from the Stainless-sourced public spec, // which only contains proxy endpoints (the ones the proxy stamps with // x-group-title). Natively-routed endpoints aren't in it, so skip them // here — adding them would produce nav entries that can't resolve at // docs build time. They are documented separately via local OpenAPI // files (see public-docs/openapi/). if (!config["x-group-title"]) continue; const group = config["x-group-title"]; const resource = config.tags[0]; groups[group] ||= {}; groups[group][resource] ||= []; groups[group][resource].push(`${method.toUpperCase()} ${endpoint}`); } } for (const [key, value] of Object.entries(schema.webhooks)) { const resource = value.post.tags[0]; let found = false; for (const group of Object.values(groups)) { if (group[resource]) { group[resource].push(`webhook ${key}`); found = true; } } if (!found) { throw new Error( `Webhook ${key} for resource ${resource} not found in any group`, ); } } // Generate index pages for each resource for (const resources of Object.values(groups)) { for (const resource of Object.keys(resources)) { const schemaName = tagToSchema[resource]; if (!schemaName) continue; const dirSlug = tagToSlug(resource); const fileSlug = toKebabCase(schemaName); const dirPath = join(apiRefDir, dirSlug); const filePath = join(dirPath, `${fileSlug}.mdx`); const pagePath = `api-reference/${dirSlug}/${fileSlug}`; mkdirSync(dirPath, { recursive: true }); const title = toTitleCase(schemaName); const description = schemaDescription(schemaName); const frontmatter = description ? `---\ntitle: "${title}"\ndescription: "${escapeYamlString( description, )}"\n---\n` : `---\ntitle: "${title}"\n---\n`; // Render the schema as Markdown ourselves rather than via the // `openapi-schema` widget: the widget renders only in HTML (its .md // export is blank) and, since the page description mirrors the schema // description, it also produced a duplicate line on the HTML page. const prose = stripGeneratedSchema(getExistingBody(filePath)); const generated = schemaBody(schemaName); const body = [prose, generated] .filter((part) => part && part.trim()) .join("\n\n"); const mdxContent = `${frontmatter}${body ? `\n${body}\n` : ""}`; writeFileSync(filePath, mdxContent); resources[resource].unshift(pagePath); } } const groupsJson = Object.entries(groups).map(([group, resources]) => ({ group, pages: Object.entries(resources).map(([group, pages]) => ({ group, pages, })), })); openapiTab.groups = [GETTING_STARTED_SECTION, ...groupsJson]; const newDocs = JSON.stringify(docsJson, null, "\t"); writeFileSync(docsJsonPath, newDocs);