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"], }; // Resources that were ported to native /api/v1 controllers — so the proxy no // longer stamps them with `x-group-title` — but we still want surfaced in the // main API Reference nav (not only the hidden beta tab) under their original // group. They are absent from the Stainless-sourced spec the tab renders from, // so their sub-group gets an `openapi` override (NATIVE_OPENAPI_SOURCE) pointing // its operation pages at the local native spec instead. Map: tag → group. const NATIVE_RESOURCES_IN_MAIN_REF = { Plans: "Payins", Users: "Identity", Products: "Payins", }; // Local native OpenAPI spec (same file the beta tab renders from) that actually // contains the NATIVE_RESOURCES_IN_MAIN_REF paths. Used as a per-group `openapi` // override so those operations resolve even though the tab-level Stainless spec // lacks them. Path is relative to docs.json. const NATIVE_OPENAPI_SOURCE = "openapi/api-v1-native.yml"; // The Stable API Reference tab renders from the Stainless-sourced public spec, // not backend/public/openapi.json. Keep this list narrow: these operation keys // exist in backend/public/openapi.json but do not resolve in the deployed Stable // OpenAPI source. const STABLE_OPENAPI_EXCLUDED_OPERATIONS = new Set(["GET /stats/sql"]); // Effective group title for an operation: the proxy's `x-group-title`, or the // pinned group for a native resource we surface in the main reference. function groupTitleFor(config) { return ( config["x-group-title"] || NATIVE_RESOURCES_IN_MAIN_REF[config.tags?.[0]] ); } 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 apiReferenceTab = docsJson.navigation.versions[0].tabs.find( (tab) => tab.tab === "API Reference", ); const openapiTab = apiReferenceTab?.dropdowns?.find( (dropdown) => dropdown.dropdown === "Stable", ); if (!openapiTab?.openapi) { throw new Error("Expected API Reference dropdown named Stable with openapi"); } const openapiRaw = readFileSync(openapiPath, "utf8"); const schema = JSON.parse(openapiRaw); 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. Native resources surfaced in the main reference // (NATIVE_RESOURCES_IN_MAIN_REF) are kept; their pages resolve against // the local native spec via a per-group openapi override. if (!groupTitleFor(config)) 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 enumValues = r.enums.flatMap((enumName) => (allSchemas[enumName]?.enum || []).filter((value) => value !== null), ); const children = []; const description = displayDescription(r.desc, enumValues); if (description) children.push(mdxSafe(oneLine(description))); // 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 || []).filter( (value) => value !== null, ); if (values?.length && shouldShowEnumOptions(name, values)) 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`; } function displayDescription(description, enumValues) { if (!description) return ""; if (description.startsWith("Represents a unique identifier that is Base64 obfuscated.")) { return ""; } if (enumValues.length === 1) { const escapedValue = enumValues[0].replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); const singletonEnumPattern = new RegExp( `^Object type\\. Always \`?${escapedValue}\`?\\.?$`, "i", ); if (singletonEnumPattern.test(description.trim())) return ""; } return description; } function shouldShowEnumOptions(name, enumValues) { return enumValues.length > 0 && !(name === "object" && enumValues.length === 1); } // 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 : ""; } // Extract the keys of the top-level `webhooks:` block from a YAML spec without // pulling in a YAML dependency: the block's keys sit at exactly two-space // indentation until the next top-level key. Returns null (never an empty set) // when the block is missing OR yields no keys — e.g. the spec's indentation // style changes and the key regex stops matching — so a malformed fetch never // reads as "zero webhooks published" and drops every webhook from the nav. function parseTopLevelWebhookKeys(yamlText) { const lines = yamlText.split("\n"); const start = lines.findIndex((line) => /^webhooks:\s*$/.test(line)); if (start === -1) return null; const keys = new Set(); for (let i = start + 1; i < lines.length; i++) { const line = lines[i]; if (/^\S/.test(line)) break; const match = line.match(/^ (['"]?)([^'":\s]+)\1:\s*$/); if (match) keys.add(match[2]); } return keys.size > 0 ? keys : null; } // The API Reference tab resolves webhook pages against the published Stainless // documented spec (the tab-level `openapi` URL), which only picks up a new // webhook after the change lands on main. A nav entry for a not-yet-published // webhook fails to resolve and breaks the Mintlify build, so fetch the // published spec and hold such entries back — the next regeneration after the // spec republishes (post-merge) adds them. On any fetch/parse failure, return // null so the caller keeps every webhook (the long-standing behavior) instead // of silently dropping live ones. async function fetchPublishedWebhookKeys(specUrl) { if (typeof specUrl !== "string" || !specUrl.startsWith("http")) return null; try { const res = await fetch(specUrl); if (!res.ok) throw new Error(`HTTP ${res.status}`); const keys = parseTopLevelWebhookKeys(await res.text()); if (!keys) throw new Error("no top-level webhooks block found"); return keys; } catch (err) { console.warn( `⚠ Could not read published spec (${err.message}); keeping all webhooks in the nav.`, ); return null; } } 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). Native resources we surface anyway // (NATIVE_RESOURCES_IN_MAIN_REF) get a per-group openapi override below // so their pages resolve against the local native spec. Other // natively-routed endpoints aren't in either spot, so skip them here — // adding them would produce nav entries that can't resolve at docs build // time. They are documented separately via the beta tab (api-v1-native). const group = groupTitleFor(config); if (!group) continue; const operationKey = `${method.toUpperCase()} ${endpoint}`; if (STABLE_OPENAPI_EXCLUDED_OPERATIONS.has(operationKey)) continue; const resource = config.tags[0]; groups[group] ||= {}; groups[group][resource] ||= []; groups[group][resource].push(operationKey); } } const publishedWebhooks = await fetchPublishedWebhookKeys(openapiTab.openapi); for (const [key, value] of Object.entries(schema.webhooks)) { // A webhook in the local spec but not yet in the published Stainless spec // would produce a nav entry Mintlify can't resolve. Leave it out of the nav // (non-blocking, like Unplaced beta endpoints) but still validate its group // placement below, so a webhook with an unmapped resource tag fails this // generation — not the post-merge rerun. Rerun `whop docs` after the merge // publishes the spec to pick the entry up. const unpublished = publishedWebhooks && !publishedWebhooks.has(key); if (unpublished) { console.warn( `⚠ Webhook ${key} is not in the published spec yet; leaving it out of the nav until the spec republishes (rerun \`whop docs\` after merge).`, ); } const resource = value.post.tags[0]; let found = false; for (const group of Object.values(groups)) { if (group[resource]) { if (!unpublished) 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(([resource, pages]) => { const subGroup = { group: resource, pages }; // Native resources aren't in the tab-level Stainless spec, so point just // this sub-group's operation pages at the local native spec. Mintlify // resolves each page against the nearest `openapi` in the hierarchy. if (NATIVE_RESOURCES_IN_MAIN_REF[resource]) { subGroup.openapi = NATIVE_OPENAPI_SOURCE; } return subGroup; }), })); openapiTab.groups = [GETTING_STARTED_SECTION, ...groupsJson]; delete apiReferenceTab.groups; const newDocs = `${JSON.stringify(docsJson, null, "\t")}\n`; writeFileSync(docsJsonPath, newDocs);