const { buildSchema, printSchema } = require("graphql"); const { readFileSync, writeFileSync, existsSync, readdirSync, statSync, mkdirSync, } = require("fs"); const path = require("path"); const { kebabCase } = require("lodash"); const { execSync } = require("child_process"); const INTROSPECTION_FILE = "../server/db/graphql_schemas/partner_api_schema.graphql"; const OUTPUT_DIR = "./partner-api-reference/mutations"; const FULL_MUTATIONS_DIR = "./partner-api-reference/mutations"; // Full mutations directory to scan // Read the schema as a string directly (not as JSON) const schemaString = readFileSync(INTROSPECTION_FILE, "utf8"); const schema = buildSchema(schemaString); const mutationType = schema.getMutationType(); const fields = mutationType.getFields(); // Recursively find a file in a directory function findFileRecursively(directory, fileName) { try { const items = readdirSync(directory); for (const item of items) { const itemPath = path.join(directory, item); const stat = statSync(itemPath); if (stat.isDirectory()) { const found = findFileRecursively(itemPath, fileName); if (found) return found; } else if (item === fileName) { return itemPath; } } } catch (error) { console.error(`Error searching directory ${directory}:`, error); } return null; } // Helper function to find all Ruby files function findFilesWithExtension(directory, extension, results = []) { try { const items = readdirSync(directory); for (const item of items) { const itemPath = path.join(directory, item); const stat = statSync(itemPath); if (stat.isDirectory()) { findFilesWithExtension(itemPath, extension, results); } else if (item.endsWith(extension)) { results.push(itemPath); } } } catch (error) { console.error(`Error searching directory ${directory}:`, error); } return results; } // Helper function to find files recursively function findFilesWithName(directory, fileName, results = []) { try { const items = readdirSync(directory); for (const item of items) { const itemPath = path.join(directory, item); const stat = statSync(itemPath); if (stat.isDirectory()) { findFilesWithName(itemPath, fileName, results); } else if (item === fileName) { results.push(itemPath); } } } catch (error) { console.error(`Error searching directory ${directory}:`, error); } return results; } // Generate front matter for the MDX file function generateFrontMatter(fieldName, description) { // Special case for refinanceReferralCreate if (fieldName === "refinanceReferralCreate") { return `--- title: 'Refinance referral create' description: "Creates a new refinance referral." --- `; } // Format the title - convert camelCase to normal text with proper capitalization const title = fieldName .replace(/([A-Z])/g, " $1") .replace(/^./, function (str) { return str.toUpperCase(); }) .trim(); return `--- title: '${title}' description: "${ description || `Creates a new ${kebabCase(fieldName).replace(/-/g, " ")}.` }" --- `; } // Replaces or adds sections by header function mergeSections(existingContent, newSections) { // Check if the existing content already has front matter const hasFrontMatter = existingContent.startsWith("---"); // If it has front matter, preserve only the content part let contentWithoutFrontMatter = existingContent; if (hasFrontMatter) { const endOfFrontMatter = existingContent.indexOf("---", 3) + 3; contentWithoutFrontMatter = existingContent .substring(endOfFrontMatter) .trim(); } // Split by section headers const parts = contentWithoutFrontMatter.split(/^## /gm); const sectionMap = {}; // Save the preamble (content before any section headers) let preamble = ""; if (parts.length > 0 && !parts[0].trim().match(/^[A-Za-z0-9 ]+$/)) { preamble = parts.shift().trim(); } // Build current section map for (const part of parts) { if (!part.trim()) continue; const [headerLine, ...bodyLines] = part.split("\n"); sectionMap[headerLine.trim()] = bodyLines.join("\n").trim(); } // Update controlled sections for (const [header, content] of Object.entries(newSections)) { if (header === "Types" && sectionMap[header]) { // Append types content to existing types section if it exists sectionMap[header] += `\n\n${content}`; } else { sectionMap[header] = content; } } // Sort sections by known header order + preserve others at the end const finalSections = []; for (const header of ["Arguments", "Return fields", "Types"]) { if (sectionMap[header]) { const headerLevel = header === "Mutation field" ? "##" : "###"; finalSections.push(`${headerLevel} ${header}\n\n${sectionMap[header]}`); delete sectionMap[header]; } } // Add back any custom sections for (const [header, content] of Object.entries(sectionMap)) { finalSections.push(`## ${header}\n\n${content}`); } // Combine preamble with sections const result = preamble ? `${preamble}\n\n${finalSections.join("\n\n")}` : finalSections.join("\n\n"); return result; } function unwrapType(type) { let current = type; while (current.ofType) current = current.ofType; return current; } // Add function to check if a type is an enum function isEnumType(type) { return type && type.astNode && type.astNode.kind === "EnumTypeDefinition"; } // Add function to check if a type is a scalar function isScalarType(type) { return type && type.astNode && type.astNode.kind === "ScalarTypeDefinition"; } // Helper: Render fields as nested ParamField/ResponseField/Expandable components function renderFieldsAsComponents( type, mode, visitedTypes, collectedEnumsScalars, pathPrefix = "", indentLevel = 0, ) { if (!type || visitedTypes.has(type.name)) return ""; visitedTypes.add(type.name); let content = ""; const isParam = mode === "param"; const FieldComponent = isParam ? "ParamField" : "ResponseField"; const indent = " ".repeat(indentLevel); if (type.getFields) { // Object, input, or interface type content += `${indent}\n`; const fields = type.getFields(); for (const fieldName in fields) { const field = fields[fieldName]; const fieldType = unwrapType(field.type); const fieldTypeStr = field.type.toString(); const description = field.description ? `\n${indent} ${field.description}` : ""; const required = fieldTypeStr.endsWith("!") ? " required" : ""; const fullPath = pathPrefix ? `${pathPrefix}.${fieldName}` : fieldName; if (isEnumType(fieldType) || isScalarType(fieldType)) { // Collect for types codeblock collectedEnumsScalars.add(fieldType.name); content += `${indent} <${FieldComponent} ${ isParam ? "path" : "name" }="${fieldName}" type="${fieldTypeStr}"${required}>${description}\n${indent} \n`; } else if (fieldType.getFields) { // Nested object/input/interface content += `${indent} <${FieldComponent} ${ isParam ? "path" : "name" }="${fieldName}" type="${fieldTypeStr}"${required}>${description}\n`; content += renderFieldsAsComponents( fieldType, mode, visitedTypes, collectedEnumsScalars, fullPath, indentLevel + 2, ); content += `${indent} \n`; } else { // Fallback content += `${indent} <${FieldComponent} ${ isParam ? "path" : "name" }="${fieldName}" type="${fieldTypeStr}"${required}>${description}\n${indent} \n`; } } content += `${indent}\n`; } return content; } // Helper: Get enum/scalar type definition function getEnumOrScalarTypeDef(type) { if (isEnumType(type)) { let typeDef = `enum ${type.name} {\n`; const values = type.getValues ? type.getValues() : []; for (const value of values) { typeDef += ` ${value.name}`; if (value.description) { typeDef += ` # ${value.description}`; } typeDef += "\n"; } typeDef += `}`; return typeDef; } if (isScalarType(type)) { let typeDef = `scalar ${type.name}`; if (type.description) { typeDef += ` # ${type.description}`; } return typeDef; } return null; } // Main function to process each mutation and generate its documentation function processMutation(fieldName, field) { console.log(`\nProcessing mutation: ${fieldName}`); // Generate the kebab case filename for the mutation const outputFileName = `${kebabCase(fieldName)}.mdx`; // Check if the file already exists anywhere under OUTPUT_DIR (including subfolders) let outputFilePath = findFileRecursively(OUTPUT_DIR, outputFileName); if (!outputFilePath) { // If not found, create it at the top level of OUTPUT_DIR outputFilePath = path.join(OUTPUT_DIR, outputFileName); } // Ensure the output directory exists const outputDirPath = path.dirname(outputFilePath); if (!existsSync(outputDirPath)) { mkdirSync(outputDirPath, { recursive: true }); } console.log(`Output file: ${outputFilePath}`); // Check if the file already exists let existingContent = ""; if (existsSync(outputFilePath)) { console.log(`File already exists, will update sections: ${outputFilePath}`); existingContent = readFileSync(outputFilePath, "utf8"); } // Generate front matter with title and description const frontMatter = generateFrontMatter(fieldName, field.description); // Generate Arguments section let argumentsContent = ""; let collectedTypes = new Set(); // Use a single set for all types if (field.args && field.args.length > 0) { for (const arg of field.args) { const argType = unwrapType(arg.type); const required = arg.type.toString().endsWith("!") ? " required" : ""; argumentsContent += `\n`; if (isEnumType(argType) || isScalarType(argType)) { collectedTypes.add(argType.name); if (arg.description) { argumentsContent += ` ${arg.description}\n`; } } else if (argType.getFields) { argumentsContent += renderFieldsAsComponents( argType, "param", new Set(), collectedTypes, ); } else if (arg.description) { argumentsContent += ` ${arg.description}\n`; } argumentsContent += `\n`; } } // Generate Return Fields section let returnFieldsContent = ""; const returnType = unwrapType(field.type); if (returnType && returnType.getFields) { const returnFields = returnType.getFields(); for (const returnFieldName in returnFields) { const returnField = returnFields[returnFieldName]; const returnFieldType = unwrapType(returnField.type); const returnFieldTypeStr = returnField.type.toString(); const description = returnField.description || ""; const required = returnFieldTypeStr.endsWith("!") ? " required" : ""; returnFieldsContent += `\n`; if (isEnumType(returnFieldType) || isScalarType(returnFieldType)) { collectedTypes.add(returnFieldType.name); if (description) { returnFieldsContent += ` ${description}\n`; } } else if (returnFieldType.getFields) { if (description) { returnFieldsContent += ` ${description}\n`; } returnFieldsContent += renderFieldsAsComponents( returnFieldType, "response", new Set(), collectedTypes, ); } else if (description) { returnFieldsContent += ` ${description}\n`; } returnFieldsContent += `\n\n`; } } // Generate combined Types section let typesContent = ""; if (collectedTypes.size > 0) { const scalars = []; const enums = []; for (const typeName of collectedTypes) { const typeObj = schema.getType(typeName); const typeDef = getEnumOrScalarTypeDef(typeObj); if (typeDef) { if (isScalarType(typeObj)) { scalars.push(typeDef); } else if (isEnumType(typeObj)) { enums.push(typeDef); } } } // Sort scalars and enums alphabetically scalars.sort(); enums.sort(); // Combine enums and scalars into typesContent typesContent += "### Types\n\n```graphql [expandable]\n"; typesContent += enums.join("\n\n"); if (scalars.length > 0 && enums.length > 0) { typesContent += "\n\n"; // Add space between enums and scalars } typesContent += scalars.join("\n\n"); typesContent += "\n```"; } // Combine all sections into a new MDX content const newSections = { "Mutation field": `\`${fieldName}\`\n\n### Arguments\n\n${argumentsContent}\n\n### Return fields\n\n${returnFieldsContent}\n\n${typesContent}`, }; // Merge with existing content if the file exists let finalContent; if (existingContent) { // Preserve the front matter from existing content if present if (existingContent.startsWith("---")) { const frontMatterEnd = existingContent.indexOf("---", 3) + 3; const existingFrontMatter = existingContent.substring(0, frontMatterEnd); const contentWithoutFrontMatter = existingContent .substring(frontMatterEnd) .trim(); finalContent = existingFrontMatter + "\n\n" + mergeSections(contentWithoutFrontMatter, newSections); } else { // No front matter in existing content finalContent = frontMatter + "\n\n" + mergeSections(existingContent, newSections); } } else { // Create new file with all sections finalContent = frontMatter + "\n\n" + mergeSections("", newSections); } // Write the MDX file writeFileSync(outputFilePath, finalContent, "utf8"); console.log(`Generated MDX file: ${outputFilePath}`); return outputFilePath; } // Main function to generate documentation for all mutations function generateMutationDocs() { console.log("Starting mutation documentation generation..."); // Ensure the output directory exists if (!existsSync(OUTPUT_DIR)) { mkdirSync(OUTPUT_DIR, { recursive: true }); console.log(`Created output directory: ${OUTPUT_DIR}`); } // Process each mutation field const generatedFiles = []; for (const fieldName in fields) { try { const outputPath = processMutation(fieldName, fields[fieldName]); generatedFiles.push(outputPath); } catch (error) { console.error(`Error processing mutation ${fieldName}:`, error); } } console.log(`Generated documentation for ${generatedFiles.length} mutations`); return generatedFiles; } // Execute the main function generateMutationDocs(); // After generating all the MDX files, update the docs.json navigation console.log( "Updating docs.json navigation to match generated files structure...", ); try { // Read the docs.json file const DOCS_JSON_PATH = "./docs.json"; if (!existsSync(DOCS_JSON_PATH)) { console.error(`docs.json not found at ${DOCS_JSON_PATH}`); process.exit(1); } const docsJson = JSON.parse(readFileSync(DOCS_JSON_PATH, "utf8")); // Function to find all MDX files in a directory recursively function findAllMdxFiles(dir, fileList = []) { if (!existsSync(dir)) { console.warn(`Directory not found: ${dir}`); return fileList; } const files = readdirSync(dir); for (const file of files) { const filePath = path.join(dir, file); const stat = statSync(filePath); if (stat.isDirectory()) { findAllMdxFiles(filePath, fileList); } else if (file.endsWith(".mdx")) { // Get relative path for docs.json const relativePath = path .relative("./", filePath) .replace(/\.mdx$/, ""); fileList.push({ relativePath, fullPath: filePath, fileName: file, baseName: path.basename(file, ".mdx"), directory: path.dirname(filePath), }); } } return fileList; } // Find the Mutations section in the docs.json navigation let mutationsGroup; const partnerApiTab = docsJson.navigation.tabs.find( (tab) => tab.tab === "Partner API Reference", ); if (partnerApiTab) { // Find or create the Mutations group mutationsGroup = partnerApiTab.groups.find( (group) => group.group === "Mutations", ); if (!mutationsGroup) { mutationsGroup = { group: "Mutations", pages: [] }; partnerApiTab.groups.push(mutationsGroup); } console.log(`Found or created 'Mutations' group in docs.json navigation`); // Find all MDX files in the mutations directory const allMdxFiles = findAllMdxFiles(FULL_MUTATIONS_DIR); console.log( `Found ${allMdxFiles.length} MDX files in the mutations directory`, ); // Separate top-level files and subfolder files const topLevelFiles = []; const filesByCategory = {}; allMdxFiles.forEach((file) => { // pathParts: [partner-api-reference, mutations, ...rest] const pathParts = file.relativePath.split("/"); if (pathParts.length === 3) { // partner-api-reference/mutations/file topLevelFiles.push(file); } else if (pathParts.length > 3) { // partner-api-reference/mutations/category[/subcategory]/file const category = pathParts[2]; if (!filesByCategory[category]) { filesByCategory[category] = []; } filesByCategory[category].push(file); } }); // Clear existing mutation pages to rebuild the structure mutationsGroup.pages = []; // Add all top-level files directly to the pages array mutationsGroup.pages.push( ...topLevelFiles.map((file) => file.relativePath), ); // Build the new navigation structure for subfolder files based on file grouping Object.keys(filesByCategory).forEach((category) => { const files = filesByCategory[category]; // If there are subcategories, further group the files const hasSubcategories = files.some((file) => { const pathParts = file.relativePath.split("/"); return pathParts.length > 4; // More than category depth }); if (hasSubcategories) { // Group by subcategory const subcategories = {}; files.forEach((file) => { const pathParts = file.relativePath.split("/"); if (pathParts.length > 4) { const subcategory = pathParts[3]; if (!subcategories[subcategory]) { subcategories[subcategory] = []; } subcategories[subcategory].push(file); } else { // Files directly in the category with no subcategory if (!subcategories["_root"]) { subcategories["_root"] = []; } subcategories["_root"].push(file); } }); // Format category name for display const displayCategory = category .split("-") .map((word) => word.charAt(0).toUpperCase() + word.slice(1)) .join(" "); // Create category group with subcategory groups const categoryGroup = { group: displayCategory, pages: [], }; // Add subcategories Object.keys(subcategories).forEach((subcategory) => { if (subcategory === "_root") { // Add files directly to the category subcategories[subcategory].forEach((file) => { categoryGroup.pages.push(file.relativePath); }); } else { // Format subcategory name for display const displaySubcategory = subcategory .split("-") .map((word) => word.charAt(0).toUpperCase() + word.slice(1)) .join(" "); // Create subcategory group const subcategoryGroup = { group: displaySubcategory, pages: subcategories[subcategory].map( (file) => file.relativePath, ), }; categoryGroup.pages.push(subcategoryGroup); } }); mutationsGroup.pages.push(categoryGroup); } else { // No subcategories, add files directly to category // Format category name for display const displayCategory = category .split("-") .map((word) => word.charAt(0).toUpperCase() + word.slice(1)) .join(" "); const categoryGroup = { group: displayCategory, pages: files.map((file) => file.relativePath), }; mutationsGroup.pages.push(categoryGroup); } }); console.log( `Updated navigation structure with ${ Object.keys(filesByCategory).length } categories`, ); // Remove duplicates in pages arrays function removeDuplicates(pagesArray) { if (!Array.isArray(pagesArray)) return pagesArray; // Create a Set to track unique paths const uniquePaths = new Set(); const result = []; for (const page of pagesArray) { if (typeof page === "string") { if (!uniquePaths.has(page)) { uniquePaths.add(page); result.push(page); } } else if (typeof page === "object" && page !== null) { // For groups, recurse if (page.pages) { page.pages = removeDuplicates(page.pages); } result.push(page); } } return result; } // Apply duplicate removal to all pages arrays function cleanNavigation(navItem) { if (!navItem) return; if (Array.isArray(navItem.pages)) { navItem.pages = removeDuplicates(navItem.pages); // Recurse into groups within pages navItem.pages.forEach((page) => { if (typeof page === "object" && page !== null) { cleanNavigation(page); } }); } if (Array.isArray(navItem.groups)) { navItem.groups.forEach((group) => { cleanNavigation(group); }); } } // Clean the entire navigation cleanNavigation(docsJson.navigation); // Write the updated docs.json back to disk writeFileSync(DOCS_JSON_PATH, JSON.stringify(docsJson, null, 2), "utf8"); console.log("docs.json navigation updated successfully!"); } else { console.error( "Could not find 'Partner API Reference' tab in docs.json navigation", ); } } catch (error) { console.error("Error updating docs.json navigation:", error); }

Overview

Queries

Mutations

Webhooks