/* eslint-disable no-console */ /** * Generate guide-style MDX for Neynar Node.js SDK. * - Pulls param names/types from AxiosParamCreator (canonical) * - Merges JSDoc @param descriptions * - Falls back to *Request interfaces if needed */ const https = require("https"); const fs = require("fs"); const path = require("path"); /* ---------- Config ---------- */ const LOCAL_SDK_DIR = path.resolve(__dirname, "../../nodejs-sdk/src/api/apis"); const OUT_DIR = path.resolve(__dirname, "../nodejs-sdk"); const DOCS_JSON_PATH = path.resolve(__dirname, "../docs.json"); const GH_ROOT = "/repos/neynarxyz/nodejs-sdk/contents/src/api/apis"; /* ---------- HTTP helpers ---------- */ function ghHeaders() { const h = { "User-Agent": "nodejs", Accept: "application/vnd.github.v3+json", }; if (process.env.GITHUB_TOKEN) h.Authorization = `token ${process.env.GITHUB_TOKEN}`; return h; } function githubApiRequest(apiPath) { return new Promise((resolve, reject) => { https .get( { hostname: "api.github.com", path: apiPath, headers: ghHeaders() }, (res) => { let data = ""; res.on("data", (c) => (data += c)); res.on("end", () => { if (res.statusCode === 200) { try { resolve(JSON.parse(data)); } catch (e) { reject(e); } } else reject(new Error(`GitHub API error: ${res.statusCode} ${data}`)); }); } ) .on("error", reject); }); } function githubRawRequest(url) { return new Promise((resolve, reject) => { https .get(url, { headers: ghHeaders() }, (res) => { let data = ""; res.on("data", (c) => (data += c)); res.on("end", () => { if (res.statusCode === 200) resolve(data); else reject(new Error(`GitHub raw error: ${res.statusCode} ${data}`)); }); }) .on("error", reject); }); } async function checkRateLimit() { try { const resp = await new Promise((resolve, reject) => { https .get( "https://api.github.com/rate_limit", { headers: ghHeaders() }, (res) => { let data = ""; res.on("data", (c) => (data += c)); res.on("end", () => { try { resolve(JSON.parse(data)); } catch (e) { reject(e); } }); } ) .on("error", reject); }); const remaining = resp.rate?.remaining ?? 0; const reset = resp.rate?.reset ? new Date(resp.rate.reset * 1000) : null; return { remaining, reset }; } catch { return { remaining: 9999, reset: null }; } } /* ---------- FS utils ---------- */ function ensureDir(dir) { fs.mkdirSync(dir, { recursive: true }); } function hasLocalSdk() { try { return fs.statSync(LOCAL_SDK_DIR).isDirectory(); } catch { return false; } } function readLocalFilesRecursively(dir) { const out = []; for (const it of fs.readdirSync(dir, { withFileTypes: true })) { const p = path.join(dir, it.name); if (it.isDirectory()) out.push(...readLocalFilesRecursively(p)); else if (it.isFile() && p.endsWith(".ts")) out.push({ path: p, __local: true }); } return out; } async function fetchApiFilesFromGithub() { const out = []; async function recurse(apiPath) { const items = await githubApiRequest(apiPath); for (const it of items) { if (it.type === "dir") await recurse(`/repos/neynarxyz/nodejs-sdk/contents/${it.path}`); else if (it.type === "file" && it.name.endsWith(".ts")) out.push(it); } } await recurse(GH_ROOT); return out; } async function getFileContent(file) { return file.__local ? fs.readFileSync(file.path, "utf-8") : githubRawRequest(file.download_url); } /* ---------- tiny helpers ---------- */ const capitalize = (s) => (s ? s.charAt(0).toUpperCase() + s.slice(1) : s); const safeSlug = (s) => String(s) .toLowerCase() .replace(/[^a-z0-9]+/g, "-") .replace(/(^-|-$)/g, ""); const mdCode = (code, lang = "ts") => { const maxTicks = Math.max( 3, ...(code.match(/`+/g) || []).map((t) => t.length) ); return `${"`".repeat(maxTicks + 1)}${lang}\n${code}\n${"`".repeat( maxTicks + 1 )}`; }; /* ---------- Cross-linking helpers ---------- */ function camelCaseToKebabCase(str) { return str.replace(/[A-Z]/g, (match) => `-${match.toLowerCase()}`); } function findApiReferenceLink(methodName) { const kebabCase = camelCaseToKebabCase(methodName); const referencePath = path.resolve(__dirname, "../reference"); // Try exact match first const exactMatch = `${kebabCase}.mdx`; if (fs.existsSync(path.join(referencePath, exactMatch))) { return `/reference/${kebabCase}`; } // Try common variations const variations = [ kebabCase, kebabCase.replace(/^fetch-/, ''), kebabCase.replace(/^lookup-/, ''), kebabCase.replace(/^publish-/, ''), kebabCase.replace(/^delete-/, ''), kebabCase.replace(/^update-/, ''), kebabCase.replace(/^create-/, ''), ]; for (const variation of variations) { const filename = `${variation}.mdx`; if (fs.existsSync(path.join(referencePath, filename))) { return `/reference/${variation}`; } } return null; } function generateApiReferenceSection(methodName) { const apiLink = findApiReferenceLink(methodName); if (!apiLink) { return ''; } return ` ## Related API Reference 📖 **API Reference:** [${methodName}](${apiLink}) For detailed information about the HTTP endpoint, request/response schemas, and additional examples, see the complete API documentation. `; } function kebabCaseToCamelCase(str) { return str.replace(/-([a-z])/g, (match, letter) => letter.toUpperCase()); } function findSdkMethodLink(apiFileName) { const methodName = kebabCaseToCamelCase(apiFileName.replace('.mdx', '')); // Search for the method in the nodejs-sdk directory structure const sdkPath = path.resolve(__dirname, "../nodejs-sdk"); function searchInDirectory(dir) { try { const items = fs.readdirSync(dir, { withFileTypes: true }); for (const item of items) { const fullPath = path.join(dir, item.name); if (item.isDirectory()) { const result = searchInDirectory(fullPath); if (result) return result; } else if (item.isFile() && item.name === `${methodName}.mdx`) { // Get the relative path from nodejs-sdk const relativePath = path.relative(sdkPath, fullPath); return `/nodejs-sdk/${relativePath.replace('.mdx', '')}`; } } } catch (err) { // Directory doesn't exist or permission denied return null; } return null; } return searchInDirectory(sdkPath); } function addSdkLinkToApiReference(apiFilePath, methodName) { try { const content = fs.readFileSync(apiFilePath, 'utf-8'); const sdkLink = findSdkMethodLink(path.basename(apiFilePath)); if (!sdkLink) { return; // No corresponding SDK method found } // Check if SDK link section already exists if (content.includes('## Node.js SDK')) { return; // Already has SDK link } // Add the SDK section before the last line or before any existing sections we want to keep at the end let insertPosition = content.length; // Look for common end sections to insert before them const endSections = ['## Examples', '## Error Codes', '## Rate Limits']; for (const section of endSections) { const sectionIndex = content.lastIndexOf(section); if (sectionIndex !== -1 && sectionIndex < insertPosition) { insertPosition = sectionIndex; } } // If we don't find any end sections, insert before the last non-empty line if (insertPosition === content.length) { const lines = content.split('\n'); const lastNonEmptyIndex = lines.findLastIndex(line => line.trim() !== ''); if (lastNonEmptyIndex !== -1) { insertPosition = lines.slice(0, lastNonEmptyIndex + 1).join('\n').length; } } const sdkSection = ` ## Node.js SDK 🔗 **SDK Method:** [${methodName}](${sdkLink}) Use this API endpoint with the Neynar Node.js SDK for typed responses and better developer experience. `; const newContent = content.slice(0, insertPosition) + sdkSection + content.slice(insertPosition); fs.writeFileSync(apiFilePath, newContent); console.log(` -> Added SDK link to ${path.basename(apiFilePath)}`); } catch (err) { console.error(`Error updating API reference ${apiFilePath}:`, err.message); } } function updateApiReferenceFiles(generatedMethods) { const referencePath = path.resolve(__dirname, "../reference"); for (const methodData of generatedMethods) { const apiFileName = camelCaseToKebabCase(methodData.name) + '.mdx'; const apiFilePath = path.join(referencePath, apiFileName); if (fs.existsSync(apiFilePath)) { addSdkLinkToApiReference(apiFilePath, methodData.name); } } } function inferGroupFromFile(filePath) { const base = path.basename(filePath).replace(/\.ts$/, ""); const name = base.replace(/-api$/, "").replace(/-/g, " "); const nice = name.endsWith("s") ? name.slice(0, -1) : name; return `${capitalize(nice)} APIs`; } /* ---------- parsing utilities ---------- */ function cleanJsDoc(jsdoc) { return (jsdoc || "") .replace(/^\/\*\*|\*\/$/g, "") .split("\n") .map((l) => l.replace(/^\s*\*\s?/, "")) .join("\n") .trim(); } function extractSummary(jsdocText) { const m = jsdocText.match(/@summary\s+([^\n]+)/); if (m) return m[1].trim(); return jsdocText.split("\n")[0] || ""; } function parseJsdocParams(jsdocText) { const lines = cleanJsDoc(jsdocText).split("\n"); const params = []; for (const ln of lines) { const m = ln.match(/^@param\s+\{([^}]+)\}\s+([A-Za-z0-9_]+)\s*(.*)$/); if (m) params.push({ name: m[2], typeFromJsdoc: m[1].trim(), description: (m[3] || "").trim(), }); } return params; } /** split a function parameter list by commas at top level (ignore commas inside <> or []) */ function splitTopLevelParams(sig) { const parts = []; let cur = "", depthAngle = 0, depthParen = 0, depthSquare = 0; for (let i = 0; i < sig.length; i++) { const c = sig[i]; if (c === "<") depthAngle++; else if (c === ">") depthAngle = Math.max(0, depthAngle - 1); else if (c === "(") depthParen++; else if (c === ")") depthParen = Math.max(0, depthParen - 1); else if (c === "[") depthSquare++; else if (c === "]") depthSquare = Math.max(0, depthSquare - 1); if ( c === "," && depthAngle === 0 && depthParen === 0 && depthSquare === 0 ) { parts.push(cur.trim()); cur = ""; } else cur += c; } if (cur.trim()) parts.push(cur.trim()); return parts; } /* ---------- robust brace-matching helpers ---------- */ function findMatchingBrace(str, openIdx) { let depth = 0; for (let i = openIdx; i < str.length; i++) { const ch = str[i]; if (ch === "{") depth++; else if (ch === "}") { depth--; if (depth === 0) return i; } } return -1; } /** Get the object literal body returned by XApiAxiosParamCreator (without the surrounding braces) */ function getAxiosCreatorBodies(src) { const bodies = []; // match: export const ApiAxiosParamCreator = function (...) { ... } const startRe = /export\s+const\s+[A-Za-z0-9_]+ApiAxiosParamCreator\s*=\s*function[^{]*\{/g; let m; while ((m = startRe.exec(src))) { const fnOpen = m.index + m[0].length - 1; // index of '{' const fnClose = findMatchingBrace(src, fnOpen); if (fnClose < 0) continue; const fnBody = src.slice(fnOpen + 1, fnClose); // inside function body // find the "return { ... }" object const retIdx = fnBody.indexOf("return"); if (retIdx < 0) continue; const objOpen = fnBody.indexOf("{", retIdx); if (objOpen < 0) continue; const objClose = findMatchingBrace(fnBody, objOpen); if (objClose < 0) continue; // push just the contents of the object literal (remove outer braces) bodies.push(fnBody.slice(objOpen + 1, objClose)); } return bodies; } /** parse parameters from AxiosParamCreator (preferred) */ function parseFromAxiosCreator(src) { const results = []; const bodies = getAxiosCreatorBodies(src); const methRe = /(\/\*\*[\s\S]*?\*\/)\s*([A-Za-z_][A-Za-z0-9_]*)\s*:\s*async\s*$\s*([\s\S]*?)$\s*:\s*Promise<([^>]+)>\s*=>\s*{/gm; for (const body of bodies) { let m; while ((m = methRe.exec(body))) { const jsdoc = m[1] || ""; const name = m[2]; const paramsSig = m[3] || ""; const responseType = m[4]; const paramPieces = splitTopLevelParams(paramsSig) .map((p) => p.trim()) .filter((p) => p && !/^options\s*:/.test(p)); // ignore 'options' const params = paramPieces .map((p) => { // forms: "fids: string", "xNeynarExperimental?: boolean", // "addressTypes?: Array<'custody_address' | 'verified_address'> = []" const mm = p.match( /^([A-Za-z_][A-Za-z0-9_]*)(\?)?\s*:\s*([^=]+?)(?:=\s*.+)?$/ ); if (!mm) return null; return { name: mm[1], required: !mm[2], type: mm[3].trim() }; }) .filter(Boolean); // merge in jsdoc @param desc const jsdocParams = parseJsdocParams(jsdoc); for (const pr of params) { const hit = jsdocParams.find((j) => j.name === pr.name); if (hit) { pr.description = hit.description; if (hit.typeFromJsdoc) pr.type = hit.typeFromJsdoc; } } results.push({ jsdoc, name, responseType, params }); } } return results; } /** fallback: Request interfaces (still used when Axios block is missing) */ function parseRequestInterfaces(src) { const out = {}; const ifaceRe = /export\s+interface\s+([A-Za-z0-9_]+Request)\s*{([\s\S]*?)}/gm; let m; while ((m = ifaceRe.exec(src))) { const ifaceName = m[1]; const body = m[2]; const propRe = /(\/\*\*[\s\S]*?\*\/)?\s*(?:readonly\s+)?([A-Za-z0-9_]+)(\?)?:\s*([^;]+);/g; const props = []; let pm; while ((pm = propRe.exec(body))) { const jsdoc = cleanJsDoc(pm[1] || ""); props.push({ name: pm[2], required: !pm[3], type: pm[4].trim(), description: jsdoc || "", }); } out[ifaceName] = props; } return out; } /** if Axios parse failed, try the *ApiInterface method signatures to pair with Request interface names */ function parseFromInterface(src) { const results = []; const ifaceRe = /export\s+interface\s+([A-Za-z0-9_]+Api(?:Interface)?)\s*{([\s\S]*?)}/gm; let m; while ((m = ifaceRe.exec(src))) { const block = m[2]; const methodRe = /(\/\*\*[\s\S]*?\*\/)?\s*([A-Za-z_][A-Za-z0-9_]*)\s*$\s*([^)]*?)$\s*:\s*(?:AxiosPromise|Promise)\s*<\s*([^>]+)\s*>/g; let mm; while ((mm = methodRe.exec(block))) { const jsdoc = mm[1] || ""; const name = mm[2]; const paramsSig = mm[3] || ""; const responseType = mm[4]; const reqMatch = paramsSig.match(/:\s*([A-Za-z0-9_]+Request)\b/); const requestType = reqMatch ? reqMatch[1] : null; results.push({ jsdoc, name, responseType, requestType }); } } return results; } /* ---------- page generation ---------- */ function placeholderFor(type, paramName) { const t = String(type).replace(/\s+/g, ""); if (t.startsWith("number") || /^Array/.test(t)) return 123; if (t.startsWith("string") || /^Array/.test(t)) return `"example"`; if (t.startsWith("boolean")) return true; if (/\[\]$/.test(t) || /^Array<.+>$/.test(t)) return "[]"; if (/Record<|{/.test(t)) return "{ /* ... */ }"; // Special handling for complex SDK types if (t === "FarcasterActionReqBody") { return `{ signer_uuid: "19d0c5fd-9b33-4a48-a0e2-bc7b0555baec", // required base_url: "https://example.com", // required action: { type: "action_type", // required payload: { // optional // action-specific payload data } } }`; } // Handle other complex types that end with ReqBody if (t.endsWith("ReqBody") || t.endsWith("Body")) { return "{ /* request body */ }"; } return `"value"`; } function buildUsageSnippet(methodName, params) { const required = (params || []).filter((p) => p.required); const optional = (params || []).filter((p) => !p.required); const lines = []; // Special handling for methods with complex body parameters const hasComplexBody = required.some(p => p.type === "FarcasterActionReqBody" || p.type.endsWith("ReqBody") || p.type.endsWith("Body") ); if (hasComplexBody) { required.forEach((p) => { if (p.type === "FarcasterActionReqBody") { lines.push(` ${p.name}: ${placeholderFor(p.type, p.name)}`); } else { lines.push( ` ${p.name}: ${placeholderFor(p.type, p.name)}, // ${ p.description || "required" }` ); } }); } else { required.forEach((p) => lines.push( ` ${p.name}: ${placeholderFor(p.type, p.name)}, // ${ p.description || "required" }` ) ); } optional.forEach((p) => lines.push( ` // ${p.name}: ${placeholderFor(p.type, p.name)}, ${ p.description ? `// ${p.description}` : "" }` ) ); return mdCode( [ `import { NeynarAPIClient, Configuration } from "@neynar/nodejs-sdk";`, ``, `const client = new NeynarAPIClient(`, ` new Configuration({ apiKey: "YOUR_NEYNAR_API_KEY" })`, `);`, ``, `const res = await client.${methodName}({`, lines.join("\n"), `});`, `console.log(res);`, ].join("\n"), "ts" ); } function generateParameterRows(params, prefix = '') { const rows = []; for (const p of params) { const paramName = prefix + p.name; // Add main parameter row rows.push( `| \`${paramName}\` | \`${p.type}\` | ${p.required ? "✅" : "❌"} | ${ p.description || "-" } |` ); // Special handling for FarcasterActionReqBody to show nested structure if (p.type === "FarcasterActionReqBody") { rows.push( `| \`${paramName}.signer_uuid\` | \`string\` | ✅ | The signer_uuid of the user on behalf of whom the action is being performed. Must be paired with the API key |` ); rows.push( `| \`${paramName}.base_url\` | \`string\` | ✅ | The base URL of the app on which the action is being performed |` ); rows.push( `| \`${paramName}.action\` | \`FarcasterActionReqBodyAction\` | ✅ | The action object containing type and optional payload |` ); rows.push( `| \`${paramName}.action.type\` | \`string\` | ✅ | The type of action being performed |` ); rows.push( `| \`${paramName}.action.payload\` | \`object\` | ❌ | The payload of the action being performed (optional, action-specific data) |` ); } } return rows; } function buildErrorHandlingSnippet(methodName, params) { const required = (params || []).filter((p) => p.required); // Build a realistic example for error handling const exampleParams = []; for (const p of required) { if (p.type === "FarcasterActionReqBody") { exampleParams.push(` ${p.name}: { signer_uuid: "19d0c5fd-9b33-4a48-a0e2-bc7b0555baec", base_url: "https://example.com", action: { type: "action_type", payload: { // action-specific payload data } } }`); } else { exampleParams.push(` ${p.name}: ${placeholderFor(p.type, p.name)}`); } } const paramString = exampleParams.length ? `{\n${exampleParams.join(",\n")}\n }` : "{ /* required fields */ }"; return mdCode( [ "try {", ` const res = await client.${methodName}(${paramString});`, " // use res", "} catch (err) {", " // Axios/HTTP errors, invalid params, auth issues, etc.", " console.error(err);", "}", ].join("\n"), "ts" ); } function generateMdx({ groupLabel, method }) { const jsdocText = cleanJsDoc(method.jsdoc || ""); const summary = extractSummary(jsdocText); const usage = buildUsageSnippet(method.name, method.params || []); let paramsTable = "_This method has no parameters._"; if ((method.params || []).length) { const rows = generateParameterRows(method.params || []); paramsTable = [ "| Parameter | Type | Required | Description |", "|---|---|:--:|---|", ...rows, ].join("\n"); } const responseLine = method.responseType ? `Returns a \`${method.responseType}\` object.` : "Returns a response object."; const errorHandling = buildErrorHandlingSnippet(method.name, method.params || []); // Generate the API reference section const apiReferenceSection = generateApiReferenceSection(method.name); return `--- title: ${method.name} --- ${summary || ""} > **Group:** ${groupLabel} Use this when you need: **${summary || groupLabel.replace(/ APIs$/, "")}**. ## Usage ${usage} ## Parameters ${paramsTable} ## Response ${responseLine} ## Error Handling ${errorHandling} ${apiReferenceSection} ## Tips - Provide a **viewerFid** when supported to respect mutes/blocks and include \`viewer_context\`. - Keep requests scoped (e.g., use \`limit\`) to improve latency. - Cache results where sensible. `; } /* ---------- docs.json sidebar ---------- */ function ensureNodeSdkGroup(docsJson) { let nodeTab = docsJson.navigation.tabs.find((t) => t.tab === "Node.js SDK"); if (!nodeTab) { nodeTab = { "tab": "Node.js SDK", "groups": [ { "group": "Overview", "pages": ["nodejs-sdk/overview"] } ] }; docsJson.navigation.tabs.push(nodeTab); } // Return the entire tab so we can update its groups return nodeTab; } function updateDocsJsonSidebar(mdxFiles, apiGroupMap) { const docsJson = JSON.parse(fs.readFileSync(DOCS_JSON_PATH, "utf-8")); const nodeTab = ensureNodeSdkGroup(docsJson); const grouped = {}; for (const file of mdxFiles) { if (file === "overview.mdx") continue; const [folder, fileName] = file.split("/"); const fnName = fileName.replace(/\.mdx$/, ""); const group = apiGroupMap[fnName] || `${capitalize(folder)} APIs`; const slug = `nodejs-sdk/${folder}/${fnName}`; if (!grouped[group]) grouped[group] = []; grouped[group].push(slug); } for (const k of Object.keys(grouped)) grouped[k].sort(); nodeTab.groups = [ { "group": "Overview", "pages": ["nodejs-sdk/overview"] }, ...Object.entries(grouped).map(([group, pages]) => ({ group, pages })), ]; fs.writeFileSync(DOCS_JSON_PATH, JSON.stringify(docsJson, null, 2)); console.log("Updated docs.json sidebar."); } /* ---------- Main ---------- */ async function main() { ensureDir(OUT_DIR); const overviewPath = path.join(OUT_DIR, "overview.mdx"); if (!fs.existsSync(overviewPath)) { fs.writeFileSync( overviewPath, `---\ntitle: Node.js SDK Overview\n---\n\nWelcome to the Neynar Node.js SDK documentation!\n` ); console.log("Created nodejs-sdk/overview.mdx"); } let files = []; if (hasLocalSdk()) { console.log("Using local SDK files:", LOCAL_SDK_DIR); files = readLocalFilesRecursively(LOCAL_SDK_DIR); } else { const { remaining, reset } = await checkRateLimit(); if (remaining <= 0) { console.error( `GitHub rate limit exhausted. Resets at: ${ reset ? reset.toString() : "unknown" }` ); process.exit(1); } files = await fetchApiFilesFromGithub(); } console.log(`Found ${files.length} API files.`); const generated = []; const apiGroupMap = {}; const allMethods = []; // Track all methods for reverse linking for (const file of files) { const fileId = file.path || file.download_url; try { const content = await getFileContent(file); // Prefer AxiosParamCreator -> full param list + jsdoc @param let methods = parseFromAxiosCreator(content); // If Axios block missing, fall back to interface + request interface props if (!methods.length) { const ifaceMethods = parseFromInterface(content); const reqMap = parseRequestInterfaces(content); methods = ifaceMethods.map((m) => ({ jsdoc: m.jsdoc, name: m.name, responseType: m.responseType, params: reqMap[m.requestType] || [], })); } if (!methods.length) { console.log(`[parse] ${fileId}: 0 methods`); continue; } const groupLabel = inferGroupFromFile(fileId); const groupFolder = safeSlug(groupLabel); const groupDir = path.join(OUT_DIR, groupFolder); ensureDir(groupDir); for (const method of methods) { const mdx = generateMdx({ groupLabel, method }); const outName = `${method.name}.mdx`; const outPath = path.join(groupDir, outName); fs.writeFileSync(outPath, mdx); generated.push(`${groupFolder}/${outName}`); apiGroupMap[method.name] = groupLabel; allMethods.push(method); // Track for reverse linking console.log(` -> wrote ${outPath}`); } } catch (err) { console.error(`Error processing ${fileId}:`, err.message); } } if (!generated.length) console.warn("No MDX files were generated."); updateDocsJsonSidebar(generated.concat("overview.mdx"), apiGroupMap); // Add reverse links to API reference files console.log("Adding SDK links to API reference files..."); updateApiReferenceFiles(allMethods); console.log("✅ NodeJS SDK API guide pages generated with cross-linking."); } main().catch((e) => { console.error("❌ Script failed:", e); process.exit(1); });

Introduction

Guides

SDK

Reference

Blog

Documentation Index

Why Farcaster Doesn't Need OAuth 2.0