const { buildSchema, isObjectType, isInterfaceType, isInputObjectType, isEnumType, isScalarType, isUnionType, isNonNullType, isListType, } = require("graphql"); const { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, } = require("fs"); const path = require("path"); // ============================================================================= // Configuration // ============================================================================= const APIs = [ { name: "Partner API", schemaPath: "../server/db/graphql_schemas/partner_api_schema.graphql", outputDir: "./partner-api/reference", docsJsonTab: "Partner API", endpointUrl: "https://api.ownright.com/partners/graphql", exclude: { queries: ["currentBusinessContact", "organization"], mutations: [ "businessContactUpdate", "matterNotificationsMute", "matterNotificationsUnmute", "notificationDeliveryMechanismsSubscribe", "notificationDeliveryMechanismsUnsubscribe", "partnerInquiryPersonCreate", ], }, groups: { queries: { referral: "Referrals", referrals: "Referrals", matter: "Matters", matters: "Matters", }, mutations: { refinanceReferralCreate: "Referrals/Refinance", refinanceReferralBulkCreate: "Referrals/Refinance", propertyClosingReferralCreate: "Referrals/Property Closings", propertyClosingReferralBulkCreate: "Referrals/Property Closings", statusCertificateReviewReferralCreate: "Referrals/Status Certificate Review", statusCertificateReviewReferralBulkCreate: "Referrals/Status Certificate Review", stagedFileUploadCreate: "Files", }, }, }, { name: "Lender API", schemaPath: "../server/db/graphql_schemas/lender_api_schema.graphql", outputDir: "./lender-api/reference", docsJsonTab: "Lender API", endpointUrl: "https://api.ownright.com/lenders/graphql", exclude: { queries: [], mutations: [] }, groups: { queries: { engagement: "Engagements", engagements: "Engagements", lender: "Lender", teamMembers: "Lender", }, mutations: { engagementCancel: "Engagements", engagementCreate: "Engagements", stagedFileUploadCreate: "Files", }, }, }, ]; const DOCS_JSON_PATH = "./docs.json"; const GENERATED_NAV_GROUPS = ["Queries", "Mutations", "Members"]; const MAX_SELECTION_DEPTH = 3; const MAX_FIELD_DEPTH = 2; const MAX_INTERFACE_FRAGMENTS = 3; const BUILT_IN_SCALARS = new Set(["String", "Int", "Float", "Boolean", "ID"]); const SKIP_TYPES = new Set(["QueryRoot", "MutationRoot", "PageInfo"]); // ============================================================================= // Utility functions // ============================================================================= function kebabCase(str) { return str .replace(/([a-z0-9])([A-Z])/g, "$1-$2") .replace(/([A-Z])([A-Z][a-z])/g, "$1-$2") .replace(/[\s_]+/g, "-") .toLowerCase(); } function pascalCase(str) { return str.charAt(0).toUpperCase() + str.slice(1); } function humanizeFieldName(str) { return str .replace(/([A-Z])/g, " $1") .replace(/^./, (s) => s.toUpperCase()) .trim(); } function escapeDescription(desc) { return (desc || "").replace(/"/g, '\\"').replace(/\n/g, " ").trim(); } function ensureDir(dir) { if (!existsSync(dir)) mkdirSync(dir, { recursive: true }); } // ============================================================================= // GraphQL type helpers // ============================================================================= function unwrapType(type) { let current = type; while (current.ofType) current = current.ofType; return current; } function typeToString(type) { if (isNonNullType(type)) return typeToString(type.ofType) + "!"; if (isListType(type)) return "[" + typeToString(type.ofType) + "]"; return type.name; } function isScalarLike(type) { return ( BUILT_IN_SCALARS.has(type.name) || isScalarType(type) || isEnumType(type) ); } function isConnectionType(type) { return type.name && type.name.endsWith("Connection"); } function getConnectionNodeType(type) { if (!type.getFields) return null; const fields = type.getFields(); if (fields.nodes) return unwrapType(fields.nodes.type); if (fields.edges) { const edgeType = unwrapType(fields.edges.type); if (edgeType.getFields && edgeType.getFields().node) { return unwrapType(edgeType.getFields().node.type); } } return null; } function isFieldList(type) { if (isNonNullType(type)) return isFieldList(type.ofType); return isListType(type); } function isInfrastructureType(name) { if (BUILT_IN_SCALARS.has(name)) return true; if (SKIP_TYPES.has(name)) return true; if (name.endsWith("Connection")) return true; if (name.endsWith("Edge")) return true; if (name.endsWith("Payload")) return true; if (name.includes("UserError")) return true; if (name === "Node" || name === "Error") return true; return false; } function getTypeKindDir(type) { if (isObjectType(type)) return "objects"; if (isInterfaceType(type)) return "interfaces"; if (isInputObjectType(type)) return "inputs"; if (isEnumType(type)) return "enums"; if (isScalarType(type)) return "scalars"; if (isUnionType(type)) return "unions"; return null; } function getOperationFilePath(name, kind, apiConfig) { const groupsKey = kind === "query" ? "queries" : "mutations"; const groupPath = apiConfig.groups[groupsKey][name]; const slug = kebabCase(name); if (groupPath) { const dirParts = groupPath.split("/").map((p) => kebabCase(p)); return `${kind === "query" ? "queries" : "mutations"}/${dirParts.join("/")}/${slug}`; } return `${kind === "query" ? "queries" : "mutations"}/${slug}`; } // ============================================================================= // Type usage analysis // ============================================================================= function collectReferencedTypes(type, visited) { const unwrapped = unwrapType(type); if ( !unwrapped.name || visited.has(unwrapped.name) || BUILT_IN_SCALARS.has(unwrapped.name) ) return; visited.add(unwrapped.name); if (unwrapped.getFields) { for (const field of Object.values(unwrapped.getFields())) { collectReferencedTypes(field.type, visited); if (field.args) { for (const arg of field.args) collectReferencedTypes(arg.type, visited); } } } } function buildTypeUsageMap(schema, queries, mutations, apiConfig) { const usageMap = {}; function processOperation(name, field, kind) { const visited = new Set(); if (field.args) { for (const arg of field.args) collectReferencedTypes(arg.type, visited); } collectReferencedTypes(field.type, visited); const filePath = getOperationFilePath(name, kind, apiConfig); const docPath = `${apiConfig.outputDir.replace("./", "")}/${filePath}`; for (const typeName of visited) { if (!usageMap[typeName]) usageMap[typeName] = []; usageMap[typeName].push({ name, kind, path: docPath }); } } for (const [name, field] of Object.entries(queries)) { if (!apiConfig.exclude.queries.includes(name)) { processOperation(name, field, "query"); } } for (const [name, field] of Object.entries(mutations)) { if (!apiConfig.exclude.mutations.includes(name)) { processOperation(name, field, "mutation"); } } return usageMap; } // ============================================================================= // Field selection builder (structured representation for examples) // ============================================================================= function buildSelection(type, schema, depth = 0, visited = new Set()) { const unwrapped = unwrapType(type); if (depth > MAX_SELECTION_DEPTH || !unwrapped.name) return []; if (isConnectionType(unwrapped)) { const nodeType = getConnectionNodeType(unwrapped); if (nodeType) { return [ { name: "nodes", selection: buildSelection( nodeType, schema, depth + 1, new Set(visited), ), }, { name: "pageInfo", selection: [{ name: "hasNextPage" }, { name: "endCursor" }], }, ]; } } if (!unwrapped.getFields || visited.has(unwrapped.name)) return []; visited.add(unwrapped.name); const fields = unwrapped.getFields(); const result = []; for (const [fieldName, field] of Object.entries(fields)) { const fu = unwrapType(field.type); if (isScalarLike(fu) || BUILT_IN_SCALARS.has(fu.name)) { result.push({ name: fieldName }); } } for (const [fieldName, field] of Object.entries(fields)) { const fu = unwrapType(field.type); if ( (isObjectType(fu) || isInterfaceType(fu) || isConnectionType(fu)) && !isScalarLike(fu) && depth + 1 <= MAX_SELECTION_DEPTH ) { const sub = buildSelection( field.type, schema, depth + 1, new Set(visited), ); if (sub.length > 0) result.push({ name: fieldName, selection: sub }); } } if (isInterfaceType(unwrapped)) { try { const possibleTypes = schema.getPossibleTypes(unwrapped); const interfaceFieldNames = new Set(Object.keys(fields)); let fragmentCount = 0; for (const impl of possibleTypes) { if (fragmentCount >= MAX_INTERFACE_FRAGMENTS) break; const implFields = impl.getFields(); const uniqueEntries = Object.entries(implFields).filter( ([n]) => !interfaceFieldNames.has(n), ); if (uniqueEntries.length > 0) { const fragmentSelection = []; for (const [fn, f] of uniqueEntries) { const fu = unwrapType(f.type); if (isScalarLike(fu) || BUILT_IN_SCALARS.has(fu.name)) { fragmentSelection.push({ name: fn }); } else if ( (isObjectType(fu) || isInterfaceType(fu)) && depth + 1 <= MAX_SELECTION_DEPTH ) { const sub = buildSelection( f.type, schema, depth + 1, new Set(visited), ); if (sub.length > 0) fragmentSelection.push({ name: fn, selection: sub }); } } if (fragmentSelection.length > 0) { result.push({ fragmentOn: impl.name, selection: fragmentSelection, }); fragmentCount++; } } } } catch { // getPossibleTypes may fail for some interface configurations } } return result; } // ============================================================================= // Example formatters // ============================================================================= function formatSelectionAsGraphQL(selection, indent = " ") { const lines = []; for (const item of selection) { if (item.fragmentOn) { lines.push(`${indent}... on ${item.fragmentOn} {`); lines.push(formatSelectionAsGraphQL(item.selection, indent + " ")); lines.push(`${indent}}`); } else if (item.selection) { lines.push(`${indent}${item.name} {`); lines.push(formatSelectionAsGraphQL(item.selection, indent + " ")); lines.push(`${indent}}`); } else { lines.push(`${indent}${item.name}`); } } return lines.join("\n"); } function getPlaceholderValue(type, fieldName) { const unwrapped = unwrapType(type); const typeName = unwrapped.name; if (typeName && typeName.endsWith("GID")) { const entity = typeName.replace("GID", "") || "Object"; return `"gid://ownright/${entity}/1"`; } if (BUILT_IN_SCALARS.has(typeName)) { switch (typeName) { case "String": { const fn = fieldName.toLowerCase(); if (fn.includes("email")) return '"jane@example.com"'; if (fn.includes("phone") || fn.includes("fax")) return '"+14165551234"'; if ( fn.includes("firstname") || (fn.includes("first") && fn.includes("name")) ) return '"Jane"'; if ( fn.includes("lastname") || (fn.includes("last") && fn.includes("name")) ) return '"Doe"'; if ( fn.includes("middlename") || (fn.includes("middle") && fn.includes("name")) ) return '"M"'; if (fn.includes("street")) return '"123 Main St"'; if (fn.includes("city")) return '"Toronto"'; if (fn.includes("postal")) return '"M5V 1A1"'; if (fn.includes("unit")) return '"Suite 100"'; if (fn.includes("cursor")) return '"cursor_abc123"'; if (fn.includes("query")) return '"search term"'; if (fn.includes("filename")) return '"document.pdf"'; if (fn.includes("url") || fn.includes("logo")) return '"https://example.com/image.png"'; if (fn.includes("owner")) return '"Jane Doe"'; if (fn.includes("notes")) return '"Additional notes here"'; if (fn.includes("shortid")) return '"ABC-123"'; if (fn.includes("title")) return '"123 Main St, Toronto"'; if ( fn.includes("label") || fn.includes("handle") || fn.includes("description") ) return `"example-${kebabCase(fieldName)}"`; return `"example-${kebabCase(fieldName)}"`; } case "Int": if (fieldName === "first" || fieldName === "last") return "10"; if (fieldName.toLowerCase().includes("size")) return "1024"; return "1"; case "Float": return "1.0"; case "Boolean": return fieldName.toLowerCase().includes("has") ? "true" : "true"; case "ID": return '"1"'; } } if (isScalarType(unwrapped)) { if (typeName === "ISO8601DateTime") return '"2025-01-15T10:30:00Z"'; if (typeName === "ISO8601Date") return '"2025-06-15"'; if (typeName === "E164PhoneNumber") return '"+14165551234"'; if (typeName === "Url") return '"https://example.com"'; if (typeName === "Decimal") return '"100.00"'; if (typeName.endsWith("GID")) { const entity = typeName.replace("GID", ""); return `"gid://ownright/${entity}/1"`; } return `"example-${kebabCase(typeName)}"`; } if (isEnumType(unwrapped)) { const values = unwrapped.getValues(); if (values.length > 0) return `"${values[0].name}"`; return '"UNKNOWN"'; } return "null"; } function buildVariablesJson(args, schema, depth = 0) { if (depth > 3) return {}; const result = {}; for (const arg of args) { const unwrapped = unwrapType(arg.type); const isList = isFieldList(arg.type); if (isInputObjectType(unwrapped)) { const inputFields = unwrapped.getFields(); const obj = {}; const hasOneOf = unwrapped.astNode && unwrapped.astNode.directives && unwrapped.astNode.directives.some((d) => d.name.value === "oneOf"); let fieldEntries = Object.entries(inputFields); if (hasOneOf) fieldEntries = fieldEntries.slice(0, 1); for (const [fieldName, field] of fieldEntries) { const fieldUnwrapped = unwrapType(field.type); const fieldIsList = isFieldList(field.type); if (isInputObjectType(fieldUnwrapped)) { const nested = buildVariablesJson( [{ name: fieldName, type: field.type }], schema, depth + 1, ); obj[fieldName] = nested[fieldName]; } else { const placeholder = getPlaceholderValue(field.type, fieldName); try { const val = JSON.parse(placeholder); obj[fieldName] = fieldIsList ? [val] : val; } catch { obj[fieldName] = placeholder; } } } result[arg.name] = isList ? [obj] : obj; } else { const placeholder = getPlaceholderValue(arg.type, arg.name); try { const val = JSON.parse(placeholder); result[arg.name] = isList ? [val] : val; } catch { result[arg.name] = placeholder; } } } return result; } function buildResponseJson(fieldName, selection, returnType, schema) { const unwrapped = unwrapType(returnType); const isList = isFieldList(returnType); function buildObject(sel, typeName) { const type = schema.getType(typeName); const fields = type && type.getFields ? type.getFields() : {}; const obj = {}; for (const item of sel) { if (item.fragmentOn) { const fragmentObj = buildObject(item.selection, item.fragmentOn); Object.assign(obj, fragmentObj); } else if (item.selection) { const nestedField = fields[item.name]; if (nestedField) { const nestedUnwrapped = unwrapType(nestedField.type); const nestedIsList = isFieldList(nestedField.type); if (isConnectionType(nestedUnwrapped)) { obj[item.name] = buildObject(item.selection, nestedUnwrapped.name); } else if (item.name === "nodes") { const nodeType = getConnectionNodeType(unwrapped) || nestedUnwrapped; obj[item.name] = [ buildObject( item.selection, nodeType.name || nestedUnwrapped.name, ), ]; } else if (nestedIsList) { obj[item.name] = [ buildObject(item.selection, nestedUnwrapped.name), ]; } else { obj[item.name] = buildObject(item.selection, nestedUnwrapped.name); } } else if (item.name === "pageInfo") { obj.pageInfo = { hasNextPage: true, endCursor: "cursor_abc123" }; } else if (item.name === "nodes") { obj[item.name] = [buildObject(item.selection, "")]; } else { obj[item.name] = buildObject(item.selection, ""); } } else { const field = fields[item.name]; if (field) { const placeholder = getPlaceholderValue(field.type, item.name); const fieldIsList = isFieldList(field.type); try { const val = JSON.parse(placeholder); obj[item.name] = fieldIsList ? [val] : val; } catch { obj[item.name] = null; } } else { if (item.name === "hasNextPage") obj[item.name] = true; else if (item.name === "endCursor") obj[item.name] = "cursor_abc123"; else obj[item.name] = null; } } } return obj; } const responseObj = buildObject(selection, unwrapped.name); const value = isConnectionType(unwrapped) ? responseObj : isList ? [responseObj] : responseObj; return { data: { [fieldName]: value } }; } // ============================================================================= // ParamField / ResponseField renderers (for Arguments and Return fields) // ============================================================================= function renderParamFields(args, schema, depth = 0) { let content = ""; for (const arg of args) { const typeStr = typeToString(arg.type); const required = typeStr.endsWith("!") ? " required" : ""; const description = arg.description || ""; const unwrapped = unwrapType(arg.type); const deprecated = arg.deprecationReason; content += `\n`; if (deprecated) content += ` Deprecated: ${deprecated}\n`; if (description) content += ` ${description}\n`; if (isInputObjectType(unwrapped) && depth < MAX_FIELD_DEPTH) { const inputFields = unwrapped.getFields(); const hasOneOf = unwrapped.astNode && unwrapped.astNode.directives && unwrapped.astNode.directives.some((d) => d.name.value === "oneOf"); if (hasOneOf) { content += ` Exactly one of the following fields must be provided.\n`; } content += ` \n`; for (const [fieldName, field] of Object.entries(inputFields)) { content += renderParamFields( [ { name: fieldName, type: field.type, description: field.description, deprecationReason: field.deprecationReason, }, ], schema, depth + 1, ); } content += ` \n`; } content += `\n\n`; } return content; } function renderResponseFields(type, schema, depth = 0) { let content = ""; if (!type || !type.getFields) return content; const fields = type.getFields(); for (const [fieldName, field] of Object.entries(fields)) { const typeStr = typeToString(field.type); const required = typeStr.endsWith("!") ? " required" : ""; const description = field.description || ""; const unwrapped = unwrapType(field.type); const deprecated = field.deprecationReason; content += `\n`; if (deprecated) content += ` Deprecated: ${deprecated}\n`; if (description) content += ` ${description}\n`; if ( (isObjectType(unwrapped) || isInterfaceType(unwrapped)) && depth < MAX_FIELD_DEPTH ) { content += ` \n`; content += renderResponseFields(unwrapped, schema, depth + 1); content += ` \n`; } content += `\n\n`; } return content; } // ============================================================================= // Enum/scalar type block for the Types section // ============================================================================= function collectTypesForSection(field, schema) { const collected = new Set(); function walk(type, visited = new Set()) { const unwrapped = unwrapType(type); if ( !unwrapped.name || visited.has(unwrapped.name) || BUILT_IN_SCALARS.has(unwrapped.name) ) return; visited.add(unwrapped.name); if ( isEnumType(unwrapped) || (isScalarType(unwrapped) && !BUILT_IN_SCALARS.has(unwrapped.name)) ) { collected.add(unwrapped.name); } if (unwrapped.getFields) { for (const f of Object.values(unwrapped.getFields())) { walk(f.type, visited); if (f.args) for (const a of f.args) walk(a.type, visited); } } } if (field.args) for (const arg of field.args) walk(arg.type); walk(field.type); return collected; } function generateTypesBlock(typeNames, schema) { if (typeNames.size === 0) return ""; const enums = []; const scalars = []; for (const typeName of [...typeNames].sort()) { const typeObj = schema.getType(typeName); if (!typeObj) continue; if (isEnumType(typeObj)) { let def = `enum ${typeObj.name} {`; for (const val of typeObj.getValues()) { def += `\n ${val.name}`; if (val.description) def += ` # ${val.description}`; } def += "\n}"; enums.push(def); } else if (isScalarType(typeObj)) { let def = `scalar ${typeObj.name}`; if (typeObj.description) def += ` # ${typeObj.description}`; scalars.push(def); } } if (enums.length === 0 && scalars.length === 0) return ""; const parts = [...enums, ...scalars]; return "```graphql [expandable]\n" + parts.join("\n\n") + "\n```"; } // ============================================================================= // Operation page generator (queries and mutations) // ============================================================================= function generateOperationPage(fieldName, field, kind, apiConfig, schema) { const operationType = kind === "query" ? "query" : "mutation"; const operationDisplayName = pascalCase(fieldName); const operationName = kind === "query" ? `Get${operationDisplayName}` : operationDisplayName; const returnType = field.type; const returnUnwrapped = unwrapType(returnType); let selection = buildSelection(returnType, schema); // For mutations, ensure userErrors is included in the selection if (kind === "mutation" && returnUnwrapped.getFields) { const payloadFields = returnUnwrapped.getFields(); if ( payloadFields.userErrors && !selection.some((s) => s.name === "userErrors") ) { const ueType = unwrapType(payloadFields.userErrors.type); const ueSelection = []; if (ueType.getFields) { for (const [fn, f] of Object.entries(ueType.getFields())) { const fu = unwrapType(f.type); if (isScalarLike(fu) || BUILT_IN_SCALARS.has(fu.name)) { ueSelection.push({ name: fn }); } } } selection.push({ name: "userErrors", selection: ueSelection.length > 0 ? ueSelection : [{ name: "message" }], }); } } // Build operation signature let argsSignature = ""; let fieldCallArgs = ""; if (field.args && field.args.length > 0) { argsSignature = `(${field.args.map((a) => `$${a.name}: ${typeToString(a.type)}`).join(", ")})`; fieldCallArgs = `(${field.args.map((a) => `${a.name}: $${a.name}`).join(", ")})`; } const selectionStr = formatSelectionAsGraphQL(selection); const requestGql = `${operationType} ${operationName}${argsSignature} {\n ${fieldName}${fieldCallArgs} {\n${selectionStr}\n }\n}`; const variables = field.args && field.args.length > 0 ? buildVariablesJson(field.args, schema) : null; const responseJson = buildResponseJson( fieldName, selection, returnType, schema, ); // For mutations, always show empty userErrors in the success response if (kind === "mutation" && responseJson.data[fieldName]) { responseJson.data[fieldName].userErrors = []; } const description = escapeDescription( field.description || `${humanizeFieldName(fieldName)}.`, ); let content = `---\ntitle: "${humanizeFieldName(fieldName)}"\ndescription: "${description}"\n---\n\n`; content += `{/* This file is auto-generated by generate.js. To customize, create an override in _overrides/. */}\n\n`; // Request example content += `\n`; content += `\`\`\`graphql Request [expandable]\n${requestGql}\n\`\`\`\n\n`; if (variables) { content += `\`\`\`graphql Variables\n${JSON.stringify(variables, null, 2)}\n\`\`\`\n`; } content += `\n\n`; // Response example content += `\n`; content += `\`\`\`json Response\n${JSON.stringify(responseJson, null, 2)}\n\`\`\`\n`; content += `\n\n`; // Operation field heading const kindTitle = kind === "query" ? "Query field" : "Mutation field"; content += `## ${kindTitle}\n\n\`${fieldName}\`\n\n`; // Arguments if (field.args && field.args.length > 0) { content += `### Arguments\n\n`; content += renderParamFields(field.args, schema); } // Return fields content += `### Return fields\n\n`; if (kind === "mutation" && returnUnwrapped.getFields) { content += renderResponseFields(returnUnwrapped, schema); } else { const typeStr = typeToString(field.type); const required = typeStr.endsWith("!") ? " required" : ""; const fieldDesc = field.description || ""; content += `\n`; if (fieldDesc) content += ` ${fieldDesc}\n`; if ( (isObjectType(returnUnwrapped) || isInterfaceType(returnUnwrapped)) && returnUnwrapped.getFields ) { content += ` \n`; content += renderResponseFields(returnUnwrapped, schema, 1); content += ` \n`; } content += `\n\n`; } // Types section const collectedTypes = collectTypesForSection(field, schema); const typesBlock = generateTypesBlock(collectedTypes, schema); if (typesBlock) { content += `### Types\n\n${typesBlock}\n`; } return content; } // ============================================================================= // Member page generator // ============================================================================= function generateMemberPage(typeName, type, apiConfig, schema, usageMap) { const description = escapeDescription( type.description || `The ${typeName} type.`, ); let content = `---\ntitle: "${typeName}"\ndescription: "${description}"\n---\n\n`; content += `{/* This file is auto-generated by generate.js. To customize, create an override in _overrides/. */}\n\n`; if (isEnumType(type)) { content += `## Values\n\n`; content += `| Value | Description |\n|-------|-------------|\n`; for (const val of type.getValues()) { const desc = val.description ? val.description.replace(/\|/g, "\\|") : ""; const deprecated = val.deprecationReason ? ` **(Deprecated: ${val.deprecationReason})**` : ""; content += `| \`${val.name}\` | ${desc}${deprecated} |\n`; } content += "\n"; } else if (isScalarType(type)) { content += `## Description\n\n`; content += `${type.description || `A custom scalar type.`}\n\n`; } else if (isObjectType(type) || isInterfaceType(type)) { content += `## Fields\n\n`; if (type.getFields) { for (const [fieldName, field] of Object.entries(type.getFields())) { const typeStr = typeToString(field.type); const required = typeStr.endsWith("!") ? " required" : ""; const desc = field.description || ""; const deprecated = field.deprecationReason; content += `\n`; if (deprecated) content += ` Deprecated: ${deprecated}\n`; if (desc) content += ` ${desc}\n`; content += `\n\n`; } } if (isInterfaceType(type)) { try { const implementations = schema.getPossibleTypes(type); if (implementations.length > 0) { content += `## Implementations\n\n`; for (const impl of implementations) { const kindDir = getTypeKindDir(impl); const slug = kebabCase(impl.name); const implPath = `/${apiConfig.outputDir.replace("./", "")}/members/${kindDir}/${slug}`; content += `- [${impl.name}](${implPath})\n`; } content += "\n"; } } catch { // getPossibleTypes may fail } } } else if (isInputObjectType(type)) { const hasOneOf = type.astNode && type.astNode.directives && type.astNode.directives.some((d) => d.name.value === "oneOf"); if (hasOneOf) { content += `Exactly one of the following fields must be provided.\n\n`; } content += `## Fields\n\n`; if (type.getFields) { for (const [fieldName, field] of Object.entries(type.getFields())) { const typeStr = typeToString(field.type); const required = typeStr.endsWith("!") ? " required" : ""; const desc = field.description || ""; content += `\n`; if (desc) content += ` ${desc}\n`; content += `\n\n`; } } } else if (isUnionType(type)) { content += `## Possible types\n\n`; for (const memberType of type.getTypes()) { const kindDir = getTypeKindDir(memberType); const slug = kebabCase(memberType.name); const memberPath = `/${apiConfig.outputDir.replace("./", "")}/members/${kindDir}/${slug}`; content += `- [${memberType.name}](${memberPath})\n`; } content += "\n"; } // Used by section const usage = usageMap[typeName]; if (usage && usage.length > 0) { content += `## Used by\n\n`; const seen = new Set(); for (const { name, kind, path: docPath } of usage) { const key = `${name}-${kind}`; if (seen.has(key)) continue; seen.add(key); content += `- [\`${name}\`](/${docPath}) (${kind})\n`; } content += "\n"; } return content; } // ============================================================================= // Override system // ============================================================================= function parseMdxSections(content) { const result = { frontmatter: "", preamble: "", sections: [] }; let body = content; if (content.startsWith("---")) { const endIdx = content.indexOf("---", 3); if (endIdx !== -1) { result.frontmatter = content.substring(0, endIdx + 3); body = content.substring(endIdx + 3).trim(); } } const sectionRegex = /^## /gm; const matches = [...body.matchAll(sectionRegex)]; if (matches.length === 0) { result.preamble = body; return result; } result.preamble = body.substring(0, matches[0].index).trim(); for (let i = 0; i < matches.length; i++) { const start = matches[i].index; const end = i + 1 < matches.length ? matches[i + 1].index : body.length; const sectionContent = body.substring(start, end).trim(); const headingEnd = sectionContent.indexOf("\n"); const heading = headingEnd === -1 ? sectionContent.substring(3) : sectionContent.substring(3, headingEnd); const sectionBody = headingEnd === -1 ? "" : sectionContent.substring(headingEnd + 1).trim(); result.sections.push({ heading: heading.trim(), body: sectionBody }); } return result; } function applyOverrides(generatedContent, overridePath) { if (!existsSync(overridePath)) return generatedContent; const overrideContent = readFileSync(overridePath, "utf8"); const gen = parseMdxSections(generatedContent); const ovr = parseMdxSections(overrideContent); const mergedFrontmatter = ovr.frontmatter || gen.frontmatter; const mergedPreamble = ovr.preamble || gen.preamble; const sectionMap = new Map(); const sectionOrder = []; for (const s of gen.sections) { sectionMap.set(s.heading, s.body); sectionOrder.push(s.heading); } for (const s of ovr.sections) { if (!sectionMap.has(s.heading)) sectionOrder.push(s.heading); sectionMap.set(s.heading, s.body); } let result = mergedFrontmatter + "\n\n"; if (mergedPreamble) result += mergedPreamble + "\n\n"; for (const heading of sectionOrder) { result += `## ${heading}\n\n${sectionMap.get(heading)}\n\n`; } return result.trim() + "\n"; } // ============================================================================= // Navigation updater // ============================================================================= function buildNavTree(operations, kind, apiConfig) { const groupsKey = kind === "query" ? "queries" : "mutations"; const groupsConfig = apiConfig.groups[groupsKey]; const tree = { _pages: [], _children: {} }; for (const name of Object.keys(operations)) { const excludeKey = kind === "query" ? "queries" : "mutations"; if (apiConfig.exclude[excludeKey].includes(name)) continue; const filePath = getOperationFilePath(name, kind, apiConfig); const docPath = `${apiConfig.outputDir.replace("./", "")}/${filePath}`; const groupPath = groupsConfig[name]; if (!groupPath) { tree._pages.push(docPath); continue; } const parts = groupPath.split("/"); let current = tree; for (const part of parts) { if (!current._children[part]) { current._children[part] = { _pages: [], _children: {} }; } current = current._children[part]; } current._pages.push(docPath); } return tree; } function navTreeToPages(tree) { const pages = [...tree._pages]; for (const [groupName, child] of Object.entries(tree._children)) { const childPages = navTreeToPages(child); if (childPages.length > 0) { pages.push({ group: groupName, pages: childPages }); } } return pages; } function buildMembersNavGroup(memberFiles, apiConfig) { const categories = {}; for (const { kindDir, docPath } of memberFiles) { const displayName = kindDir.charAt(0).toUpperCase() + kindDir.slice(1); if (!categories[displayName]) categories[displayName] = []; categories[displayName].push(docPath); } const pages = []; const order = [ "Objects", "Interfaces", "Inputs", "Enums", "Scalars", "Unions", ]; for (const cat of order) { if (categories[cat] && categories[cat].length > 0) { pages.push({ group: cat, pages: categories[cat].sort() }); } } return pages; } function updateDocsJsonNav( apiConfig, queryFields, mutationFields, memberFiles, ) { if (!existsSync(DOCS_JSON_PATH)) { console.error(`docs.json not found at ${DOCS_JSON_PATH}`); return; } const docsJson = JSON.parse(readFileSync(DOCS_JSON_PATH, "utf8")); const tab = docsJson.navigation.tabs.find( (t) => t.tab === apiConfig.docsJsonTab, ); if (!tab) { console.error(`Tab "${apiConfig.docsJsonTab}" not found in docs.json`); return; } // Remove existing generated groups tab.groups = tab.groups.filter( (g) => !GENERATED_NAV_GROUPS.includes(g.group), ); // Find insertion point (after "API Reference" or at end) let insertIdx = tab.groups.findIndex((g) => g.group === "API Reference"); insertIdx = insertIdx !== -1 ? insertIdx + 1 : tab.groups.length; // Build Queries nav const queryTree = buildNavTree(queryFields, "query", apiConfig); const queryPages = navTreeToPages(queryTree); if (queryPages.length > 0) { tab.groups.splice(insertIdx, 0, { group: "Queries", pages: queryPages }); insertIdx++; } // Build Mutations nav const mutationTree = buildNavTree(mutationFields, "mutation", apiConfig); const mutationPages = navTreeToPages(mutationTree); if (mutationPages.length > 0) { tab.groups.splice(insertIdx, 0, { group: "Mutations", pages: mutationPages, }); insertIdx++; } // Build Members nav const membersPages = buildMembersNavGroup(memberFiles, apiConfig); if (membersPages.length > 0) { // Find insertion point: before "Webhooks" if it exists, otherwise at end let membersIdx = tab.groups.findIndex((g) => g.group === "Webhooks"); membersIdx = membersIdx !== -1 ? membersIdx : tab.groups.length; tab.groups.splice(membersIdx, 0, { group: "Members", pages: membersPages }); } writeFileSync(DOCS_JSON_PATH, JSON.stringify(docsJson, null, 2), "utf8"); console.log(` Updated docs.json navigation for "${apiConfig.docsJsonTab}"`); } // ============================================================================= // Main execution // ============================================================================= function generateApiDocs(apiConfig) { console.log(`\nGenerating docs for ${apiConfig.name}...`); if (!existsSync(apiConfig.schemaPath)) { console.warn(` Schema not found: ${apiConfig.schemaPath}, skipping.`); return; } const schemaString = readFileSync(apiConfig.schemaPath, "utf8"); const schema = buildSchema(schemaString); const queryType = schema.getQueryType(); const mutationType = schema.getMutationType(); const queryFields = queryType ? queryType.getFields() : {}; const mutationFields = mutationType ? mutationType.getFields() : {}; // Build type usage map const usageMap = buildTypeUsageMap( schema, queryFields, mutationFields, apiConfig, ); // Clean generated directories for (const subdir of ["queries", "mutations", "members"]) { const dir = path.join(apiConfig.outputDir, subdir); if (existsSync(dir)) rmSync(dir, { recursive: true, force: true }); } // Ensure _overrides directory exists const overridesDir = path.join(apiConfig.outputDir, "_overrides"); ensureDir(overridesDir); const generatedFiles = { queries: [], mutations: [], members: [] }; // Generate query pages for (const [name, field] of Object.entries(queryFields)) { if (apiConfig.exclude.queries.includes(name)) continue; try { const filePath = getOperationFilePath(name, "query", apiConfig); const fullPath = path.join(apiConfig.outputDir, filePath + ".mdx"); ensureDir(path.dirname(fullPath)); let content = generateOperationPage( name, field, "query", apiConfig, schema, ); const overridePath = path.join(overridesDir, filePath + ".mdx"); content = applyOverrides(content, overridePath); writeFileSync(fullPath, content, "utf8"); const docPath = `${apiConfig.outputDir.replace("./", "")}/${filePath}`; generatedFiles.queries.push(docPath); console.log(` Generated query: ${fullPath}`); } catch (error) { console.error(` Error generating query ${name}:`, error.message); } } // Generate mutation pages for (const [name, field] of Object.entries(mutationFields)) { if (apiConfig.exclude.mutations.includes(name)) continue; try { const filePath = getOperationFilePath(name, "mutation", apiConfig); const fullPath = path.join(apiConfig.outputDir, filePath + ".mdx"); ensureDir(path.dirname(fullPath)); let content = generateOperationPage( name, field, "mutation", apiConfig, schema, ); const overridePath = path.join(overridesDir, filePath + ".mdx"); content = applyOverrides(content, overridePath); writeFileSync(fullPath, content, "utf8"); const docPath = `${apiConfig.outputDir.replace("./", "")}/${filePath}`; generatedFiles.mutations.push(docPath); console.log(` Generated mutation: ${fullPath}`); } catch (error) { console.error(` Error generating mutation ${name}:`, error.message); } } // Generate member pages const memberFiles = []; const typeMap = schema.getTypeMap(); for (const [typeName, type] of Object.entries(typeMap)) { if (typeName.startsWith("__")) continue; if (isInfrastructureType(typeName)) continue; const kindDir = getTypeKindDir(type); if (!kindDir) continue; try { const slug = kebabCase(typeName); const filePath = `members/${kindDir}/${slug}`; const fullPath = path.join(apiConfig.outputDir, filePath + ".mdx"); ensureDir(path.dirname(fullPath)); let content = generateMemberPage( typeName, type, apiConfig, schema, usageMap, ); const overridePath = path.join(overridesDir, filePath + ".mdx"); content = applyOverrides(content, overridePath); writeFileSync(fullPath, content, "utf8"); const docPath = `${apiConfig.outputDir.replace("./", "")}/${filePath}`; memberFiles.push({ kindDir, docPath }); console.log(` Generated member: ${fullPath}`); } catch (error) { console.error(` Error generating member ${typeName}:`, error.message); } } generatedFiles.members = memberFiles; // Update navigation updateDocsJsonNav(apiConfig, queryFields, mutationFields, memberFiles); const total = generatedFiles.queries.length + generatedFiles.mutations.length + generatedFiles.members.length; console.log(` Done: ${total} pages generated for ${apiConfig.name}`); } function main() { console.log("Starting multi-API documentation generation...\n"); for (const apiConfig of APIs) { generateApiDocs(apiConfig); } console.log("\nAll APIs processed."); } main();

Getting Started

Core Concepts

Guides

API Reference

Queries

Mutations

Members

Webhooks