stacked-server-typescript-types 1.1.3

package/process-openapi-types.js

@@ -0,0 +1,747 @@
+#!/usr/bin/env node
+
+/**
+ * Process OpenAPI JSON files and generate TypeScript types
+ * that combine message types from ts-proto with endpoint types from OpenAPI
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const openapiJsonFile = process.argv[2];
+const outputFile = process.argv[3];
+const serviceName = process.argv[4];
+const messagesDir = process.argv[5];
+const serverDir = process.argv[6] || path.join(__dirname, '..');
+
+if (!openapiJsonFile || !outputFile || !serviceName) {
+    console.error('Usage: process-openapi-types.js <openapi-json> <output-file> <service-name> <messages-dir> [server-dir]');
+    process.exit(1);
+}
+
+if (!fs.existsSync(openapiJsonFile)) {
+    console.error(`OpenAPI JSON file not found: ${openapiJsonFile}`);
+    process.exit(1);
+}
+
+// Read OpenAPI spec
+const openapiSpec = JSON.parse(fs.readFileSync(openapiJsonFile, 'utf8'));
+
+// Normalize service name for matching
+const normalizedServiceName = (serviceName || '')
+    .toLowerCase()
+    .replace(/service$/i, '')
+    .replace(/-/g, '');
+
+// Find all message type files
+const messageTypes = new Set();
+if (fs.existsSync(messagesDir)) {
+    // Include nested directories (e.g., messages/google/protobuf) so types like BoolValue resolve.
+    function walkMessages(dir) {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walkMessages(full);
+            } else if (entry.isFile() && entry.name.endsWith('.ts') && entry.name !== 'index.ts') {
+                const basename = path.basename(entry.name, '.ts');
+                messageTypes.add(basename);
+            }
+        }
+    }
+
+    walkMessages(messagesDir);
+}
+
+// Parse proto files to map RPC names to request/response message names
+function buildProtoRpcMap() {
+    const protoRoot = path.join(serverDir, 'services');
+    const rpcMap = {};
+
+    function walkDir(dir) {
+        if (!fs.existsSync(dir)) return;
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walkDir(full);
+            } else if (entry.isFile() && entry.name.endsWith('.proto')) {
+                try {
+                    const content = fs.readFileSync(full, 'utf8');
+
+                    // Derive service dir name (first component under protoRoot) to avoid cross-service collisions.
+                    const rel = path.relative(protoRoot, full);
+                    const parts = rel.split(path.sep);
+                    const serviceDir = parts.length > 1 ? parts[0] : '';
+                    const normalizedDir = serviceDir
+                        .toLowerCase()
+                        .replace(/-service$/i, '')
+                        .replace(/service$/i, '')
+                        .replace(/-/g, '');
+
+                    const isCurrentService = !serviceDir
+                        ? true
+                        : (normalizedDir === normalizedServiceName ||
+                           normalizedDir.includes(normalizedServiceName) ||
+                           normalizedServiceName.includes(normalizedDir));
+
+                    if (!isCurrentService) continue;
+
+                    const svcRegex = /service\s+\w+\s*\{([\s\S]*?)\n\}/gm;
+                    const rpcRegex = /rpc\s+(\w+)\s*\(\s*([\w.]+)\s*\)\s*returns\s*\(\s*([\w.]+)\s*\)/g;
+
+                    let svc;
+                    while ((svc = svcRegex.exec(content)) !== null) {
+                        const body = svc[1];
+                        let m;
+                        while ((m = rpcRegex.exec(body)) !== null) {
+                            const rpcName = m[1];
+                            const request = m[2];
+                            const response = m[3];
+                            // Same rpcName can exist across services; within a service it should be unique.
+                            rpcMap[rpcName] = { request, response };
+                        }
+                    }
+                } catch (e) {
+                    // ignore parse errors
+                }
+            }
+        }
+    }
+
+    walkDir(protoRoot);
+    return rpcMap;
+}
+
+// Build a map of rpcName -> leading comment block (2-5 sentences) from .proto files.
+// We treat consecutive //-comments immediately above the rpc line as the doc.
+function buildProtoRpcDocsMap() {
+    const protoRoot = path.join(serverDir, 'services');
+    const docsMap = {};
+
+    function normalizeDoc(lines) {
+        const cleaned = (lines || [])
+            .map(l => String(l).trim())
+            .map(l => l.replace(/^\/\/\s?/, '').trim())
+            .filter(Boolean);
+        return cleaned.join('\n');
+    }
+
+    function walkDir(dir) {
+        if (!fs.existsSync(dir)) return;
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walkDir(full);
+            } else if (entry.isFile() && entry.name.endsWith('.proto')) {
+                try {
+                    const content = fs.readFileSync(full, 'utf8');
+
+                    // Filter to current service's proto files.
+                    const rel = path.relative(protoRoot, full);
+                    const parts = rel.split(path.sep);
+                    const serviceDir = parts.length > 1 ? parts[0] : '';
+                    const normalizedDir = serviceDir
+                        .toLowerCase()
+                        .replace(/-service$/i, '')
+                        .replace(/service$/i, '')
+                        .replace(/-/g, '');
+
+                    const isCurrentService = !serviceDir
+                        ? true
+                        : (normalizedDir === normalizedServiceName ||
+                           normalizedDir.includes(normalizedServiceName) ||
+                           normalizedServiceName.includes(normalizedDir));
+
+                    if (!isCurrentService) continue;
+
+                    const lines = content.split(/\r?\n/);
+                    let commentBuf = [];
+                    for (let i = 0; i < lines.length; i++) {
+                        const line = lines[i];
+                        const commentMatch = line.match(/^\s*\/\//);
+                        if (commentMatch) {
+                            commentBuf.push(line);
+                            continue;
+                        }
+
+                        const rpcMatch = line.match(/^\s*rpc\s+(\w+)\s*\(/);
+                        if (rpcMatch) {
+                            const rpcName = rpcMatch[1];
+                            const doc = normalizeDoc(commentBuf);
+                            if (doc) docsMap[rpcName] = doc;
+                            commentBuf = [];
+                            continue;
+                        }
+
+                        // Reset buffer on non-comment lines (blank lines end the doc block)
+                        if (String(line).trim() === '') {
+                            commentBuf = [];
+                        } else {
+                            commentBuf = [];
+                        }
+                    }
+                } catch (e) {
+                    // ignore parse errors
+                }
+            }
+        }
+    }
+
+    walkDir(protoRoot);
+    return docsMap;
+}
+
+const protoRpcMap = buildProtoRpcMap();
+const protoRpcDocsMap = buildProtoRpcDocsMap();
+
+// Build a map of proto message names to their fields (used to generate GET query params)
+// ONLY from the current service's proto files
+const protoMessageMap = (function buildProtoMessageMap() {
+    const protoRoot = path.join(serverDir, 'services');
+    const map = {};
+
+    function walkDir(dir) {
+        if (!fs.existsSync(dir)) return;
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walkDir(full);
+            } else if (entry.isFile() && entry.name.endsWith('.proto')) {
+                try {
+                    const content = fs.readFileSync(full, 'utf8');
+                    const msgRegex = /message\s+(\w+)\s*\{([\s\S]*?)\n\}/gm;
+                    let m;
+                    
+                    // Derive service dir name (first component under protoRoot)
+                    const rel = path.relative(protoRoot, full);
+                    const parts = rel.split(path.sep);
+                    const serviceDir = parts.length > 1 ? parts[0] : '';
+                    
+                    // Normalize the service directory for comparison
+                    const normalizedDir = serviceDir
+                        .toLowerCase()
+                        .replace(/-service$/i, '')
+                        .replace(/service$/i, '')
+                        .replace(/-/g, '');
+                    
+                    // Only process messages from the current service
+                    const isCurrentService = normalizedDir === normalizedServiceName ||
+                        normalizedDir.includes(normalizedServiceName) ||
+                        normalizedServiceName.includes(normalizedDir);
+                    
+                    if (!isCurrentService && serviceDir !== '') {
+                        return; // Skip messages from other services
+                    }
+                    
+                    while ((m = msgRegex.exec(content)) !== null) {
+                        const msgName = m[1];
+                        const body = m[2];
+                        const fields = [];
+                        const fieldRegex = /(?:repeated\s+)?(map<[^>]+>|[A-Za-z0-9_.]+)\s+(\w+)\s*=\s*\d+\s*;/g;
+                        let f;
+                        while ((f = fieldRegex.exec(body)) !== null) {
+                            const rawType = f[1];
+                            const fieldName = f[2];
+                            let tsType = 'any';
+                            if (/^string$/.test(rawType) || /^bytes$/.test(rawType)) tsType = 'string';
+                            else if (/^(?:int|uint|sint|fixed|sfixed)\w*/.test(rawType) || /^(?:double|float)$/.test(rawType)) tsType = 'number';
+                            else if (/^bool$/.test(rawType)) tsType = 'boolean';
+                            else if (/^map</.test(rawType)) tsType = 'Record<string,string>';
+                            else if (/^repeated\s+/.test(f[0]) || rawType.startsWith('repeated ')) tsType = 'any[]';
+                            fields.push({ name: fieldName, type: rawType, tsType });
+                        }
+                        // Only store if we don't already have this message (first match wins for current service)
+                        if (!map[msgName]) {
+                            map[msgName] = fields;
+                        }
+                    }
+                } catch (e) {
+                    // ignore parse errors
+                }
+            }
+        }
+    }
+
+    walkDir(protoRoot);
+    return map;
+})();
+
+// Helper to get proto message fields (now simple since we only have current service's messages)
+function getProtoFieldsForMessage(msgName) {
+    if (!msgName || !protoMessageMap[msgName]) return null;
+    return protoMessageMap[msgName];
+}
+
+// Helper to convert snake_case to camelCase
+function toCamelCase(str) {
+    return str.replace(/[_-]([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+
+// Helper to convert to PascalCase
+function toPascalCase(str) {
+    const camel = toCamelCase(str);
+    return camel.charAt(0).toUpperCase() + camel.slice(1);
+}
+
+// Extract message type name from schema reference
+function extractMessageType(ref) {
+    if (!ref || typeof ref !== 'string') return null;
+    const match = ref.match(/#\/components\/schemas\/(.+)/);
+    if (match) {
+        return match[1];
+    }
+    return null;
+}
+
+// Check if a type is a message type we generated
+function isMessageType(typeName) {
+    if (messageTypes.has(typeName)) {
+        return true;
+    }
+    for (const msgType of messageTypes) {
+        if (msgType.toLowerCase() === typeName.toLowerCase()) {
+            return msgType;
+        }
+    }
+    return false;
+}
+
+// Generate TypeScript type from OpenAPI schema
+function generateTypeFromSchema(schema, indent = '') {
+    if (!schema) return 'any';
+    
+    if (schema.$ref) {
+        const typeName = extractMessageType(schema.$ref);
+        if (typeName) {
+            const msgType = isMessageType(typeName);
+            if (msgType) {
+                const actualName = typeof msgType === 'string' ? msgType : typeName;
+                return `Messages.${actualName}`;
+            }
+            return toPascalCase(typeName);
+        }
+        return 'any';
+    }
+    
+    if (schema.type === 'object' && schema.properties) {
+        const props = Object.entries(schema.properties).map(([key, prop]) => {
+            const optional = schema.required && !schema.required.includes(key) ? '?' : '';
+            const propType = generateTypeFromSchema(prop, indent + '  ');
+            return `${indent}  ${key}${optional}: ${propType};`;
+        }).join('\n');
+        return `{\n${props}\n${indent}}`;
+    }
+    
+    if (schema.type === 'array') {
+        const itemType = generateTypeFromSchema(schema.items, indent);
+        return `${itemType}[]`;
+    }
+    
+    if (schema.type === 'string') {
+        if (schema.enum) {
+            return schema.enum.map(v => `'${v}'`).join(' | ');
+        }
+        return 'string';
+    }
+    
+    if (schema.type === 'integer' || schema.type === 'number') {
+        return 'number';
+    }
+    
+    if (schema.type === 'boolean') {
+        return 'boolean';
+    }
+    
+    return 'any';
+}
+
+// Extract parameters from OpenAPI operation
+function extractParameters(operation) {
+    if (!operation.parameters) return {};
+    
+    const params = {};
+    operation.parameters.forEach(param => {
+        if (param.in === 'query' || param.in === 'path') {
+            const optional = param.required === false ? '?' : '';
+            let type = 'string';
+            
+            if (param.schema) {
+                if (param.schema.type === 'integer' || param.schema.type === 'number') {
+                    type = 'number';
+                } else if (param.schema.type === 'boolean') {
+                    type = 'boolean';
+                } else if (param.schema.type === 'array') {
+                    type = 'string[]';
+                }
+            }
+            
+            params[param.name] = {
+                type,
+                optional,
+                deprecated: param.deprecated || false,
+                description: param.description
+            };
+        }
+    });
+    
+    return params;
+}
+
+// Extract request body type
+function extractRequestBody(operation) {
+    if (!operation.requestBody) return null;
+    
+    const content = operation.requestBody.content;
+    if (content && content['application/json']) {
+        return generateTypeFromSchema(content['application/json'].schema);
+    }
+    
+    return null;
+}
+
+// Extract response type
+function extractResponseType(operation) {
+    if (!operation.responses) return null;
+
+    const successResponse = operation.responses['200'] || operation.responses['201'] || operation.responses['204'] || Object.values(operation.responses)[0];
+    if (!successResponse) return null;
+
+    const content = successResponse.content;
+    if (content && typeof content === 'object') {
+        for (const key of Object.keys(content)) {
+            if (key && key.toLowerCase().includes('json') && content[key] && content[key].schema) {
+                return generateTypeFromSchema(content[key].schema);
+            }
+        }
+        const firstKey = Object.keys(content)[0];
+        if (firstKey && content[firstKey] && content[firstKey].schema) {
+            return generateTypeFromSchema(content[firstKey].schema);
+        }
+    }
+
+    if (successResponse.schema) {
+        return generateTypeFromSchema(successResponse.schema);
+    }
+
+    if (successResponse.description && !content) {
+        return 'void';
+    }
+
+    return null;
+}
+
+// Prefer per-operation description/summary (often derived from proto comments).
+// When protoc-gen-openapiv2 is too old to include source_info, we still keep whatever
+// description/summary exists in the swagger output.
+function getOperationDoc(op) {
+  if (!op) return '';
+  const parts = [];
+  if (typeof op.summary === 'string' && op.summary.trim()) parts.push(op.summary.trim());
+  if (typeof op.description === 'string' && op.description.trim()) parts.push(op.description.trim());
+  // De-duplicate if summary is a prefix of description
+  if (parts.length === 2 && parts[1].startsWith(parts[0])) {
+    return parts[1];
+  }
+  return parts.join('\n\n');
+}
+
+const outDir = path.dirname(outputFile);
+if (!fs.existsSync(outDir)) {
+    fs.mkdirSync(outDir, { recursive: true });
+}
+
+// Ensure an env wrapper exists alongside generated endpoints so imports resolve.
+const envWrapperPath = path.join(outDir, 'envWrapper.ts');
+if (!fs.existsSync(envWrapperPath)) {
+    fs.writeFileSync(envWrapperPath, `let backendApiDomain = ""
+
+export function getBackendApiDomain(): string {
+  if (!backendApiDomain) {
+    throw new Error("Backend API domain is not set. Please call setBackendApiDomain first.")
+  }
+  return backendApiDomain
+}
+
+export function setBackendApiDomain(domain: string): void {
+  if (backendApiDomain) {
+    throw new Error("Backend API domain is already set.")
+  }
+  backendApiDomain = domain
+}`);
+}
+
+// Generate endpoints mapping file
+const endpoints = {};
+const pathsObj = openapiSpec.paths || {};
+Object.entries(pathsObj).forEach(([p, methods]) => {
+    Object.entries(methods).forEach(([m, operation]) => {
+        if (!operation || !operation.operationId) return;
+        let opId = operation.operationId;
+        const usIdx = opId.indexOf('_');
+        const dIdx = opId.indexOf('.');
+        if (usIdx !== -1) {
+            opId = opId.substring(usIdx + 1);
+        } else if (dIdx !== -1) {
+            opId = opId.substring(dIdx + 1);
+        }
+        const rpcName = toPascalCase(opId);
+
+        const paramsObj = extractParameters(operation);
+        const requestBodyType = extractRequestBody(operation);
+        const responseType = extractResponseType(operation) || 'void';
+
+        function findMessageByCandidates(candidates) {
+            for (const cand of candidates) {
+                for (const mt of messageTypes) {
+                    if (mt.toLowerCase() === cand.toLowerCase()) return mt;
+                }
+            }
+            return null;
+        }
+        
+        let inferredResponseType = responseType;
+        if (!inferredResponseType || inferredResponseType === 'any' || /^\s*\{\s*\}?$/m.test(String(inferredResponseType))) {
+            const respCandidates = [
+                `${rpcName}Response`, `${rpcName}Reply`, `${rpcName}Res`, `${rpcName}Result`, `${rpcName}Output`, `${rpcName}Dto`,
+                `${rpcName}ResponseMessage`, `${rpcName}ResponseDto`
+            ];
+            const foundResp = findMessageByCandidates(respCandidates);
+            if (foundResp) {
+                inferredResponseType = `Messages.${foundResp}`;
+            }
+        }
+
+        let inferredRequestBodyType = requestBodyType;
+        if (!inferredRequestBodyType || inferredRequestBodyType === 'any') {
+            const reqCandidates = [
+                `${rpcName}Request`, `${rpcName}Req`, `${rpcName}Params`, `${rpcName}Input`, `${rpcName}Body`,
+                `${rpcName}RequestMessage`, `${rpcName}RequestDto`
+            ];
+            const foundReq = findMessageByCandidates(reqCandidates);
+            if (foundReq) {
+                inferredRequestBodyType = `Messages.${foundReq}`;
+            }
+        }
+
+        let inputTypeStr = 'void';
+        if (inferredRequestBodyType) {
+            inputTypeStr = inferredRequestBodyType;
+        } else if (Object.keys(paramsObj).length > 0) {
+            const parts = Object.entries(paramsObj).map(([name, pinfo]) => `${name}${pinfo.optional}: ${pinfo.type}`);
+            inputTypeStr = `{ ${parts.join(', ')} }`;
+        }
+
+        const protoEntry = protoRpcMap[rpcName];
+        let protoInputName = null;
+        let protoOutputName = null;
+        if (protoEntry) {
+            if (protoEntry.request) protoInputName = String(protoEntry.request).split('.').pop();
+            if (protoEntry.response) protoOutputName = String(protoEntry.response).split('.').pop();
+        }
+
+        function displayTypeName(t) {
+            if (!t) return 'void';
+            if (t === 'Empty') return '{}';
+            if (typeof t === 'string' && t.startsWith('Messages.')) return t.split('.')[1] || t;
+            return t;
+        }
+        
+        const chosenInput = protoInputName || inputTypeStr;
+        const chosenOutput = protoOutputName || inferredResponseType || 'void';
+
+        const protoDoc = protoRpcDocsMap[rpcName] || '';
+        const fallbackDoc = (operation.description || operation.summary || '').trim();
+        const doc = (protoDoc || fallbackDoc).trim();
+
+        const operationDoc = getOperationDoc(operation);
+
+        const info = {
+            path: p,
+            method: (m || '').toUpperCase(),
+            input: displayTypeName(chosenInput),
+            output: displayTypeName(chosenOutput),
+            deprecated: !!operation.deprecated,
+            summary: operation.summary || '',
+            description: doc,
+            doc: doc
+        };
+
+        const lines = [];
+        if (operationDoc) {
+          lines.push('/**');
+          for (const line of operationDoc.split('\n')) {
+            lines.push(` * ${line}`.trimEnd());
+          }
+          lines.push(' */');
+        }
+
+        if (!endpoints[rpcName]) {
+            endpoints[rpcName] = info;
+        }
+    });
+});
+
+let serviceObjectName = toPascalCase(serviceName).replace(/-/g, '');
+if (!serviceObjectName.endsWith('Service')) {
+    serviceObjectName = `${serviceObjectName}Service`;
+}
+
+// Build method strings and track all referenced types
+const methodLines = [];
+const allReferencedTypes = new Set();
+
+Object.entries(endpoints).forEach(([k, info]) => {
+    // Track input and output types for imports
+    if (info.input && !isSkippableImportType(info.input) && /^[A-Za-z_][A-Za-z0-9_]*$/.test(info.input)) {
+        allReferencedTypes.add(info.input);
+    }
+    if (info.output && !isSkippableImportType(info.output) && /^[A-Za-z_][A-ZaZ0-9_]*$/.test(info.output)) {
+        allReferencedTypes.add(info.output);
+    }
+
+    let methodStr = '/**\n';
+    if (info.doc) {
+        const docLines = String(info.doc).split(/\r?\n/);
+        for (const dl of docLines) {
+            methodStr += ` * ${dl}\n`;
+        }
+        methodStr += ' *\n';
+    }
+    methodStr += ` * @method ${info.method}\n`;
+    methodStr += ` * @input ${info.input}\n`;
+    methodStr += ` * @output ${info.output}\n`;
+    methodStr += ` */\n`;
+
+    const urlPath = info.path || '';
+    const params = [];
+    const paramRegex = /\{([^}]+)\}/g;
+    let match;
+    while ((match = paramRegex.exec(urlPath)) !== null) {
+        params.push(match[1]);
+    }
+
+    // For GET endpoints, include fields from proto input message as optional query params
+    // Only uses messages from current service (no cross-service pollution)
+    const extraParams = [];
+    if (info.method === 'GET' && info.input && !isNoInputType(info.input)) {
+        const msgName = info.input;
+        const protoFields = getProtoFieldsForMessage(msgName);
+        if (msgName && protoFields) {
+            for (const field of protoFields) {
+                const camel = toCamelCase(field.name);
+                const snake = field.name;
+                if (params.includes(camel) || params.includes(snake)) continue;
+                extraParams.push(`${camel}?: ${field.tsType}`);
+            }
+        }
+    }
+
+    const paramsSignatureParts = [];
+    for (const p of params) {
+        const paramName = toCamelCase(p);
+        paramsSignatureParts.push(`${paramName}: string`);
+    }
+    for (const ep of extraParams) paramsSignatureParts.push(ep);
+    const paramsSignature = paramsSignatureParts.join(', ');
+
+    const templateForOutput = urlPath.replace(/\{([^}]+)\}/g, (_, p) => '${' + toCamelCase(p) + '}');
+    const extraParamNames = extraParams.map(ep => ep.split('?')[0].split(':')[0].trim());
+
+    // If this is a GET and we have a named input type, emit a single destructured param typed as that request
+    if (info.method === 'GET' && info.input && !isNoInputType(info.input)) {
+        const pathParamNames = params.map(p => toCamelCase(p));
+        const allDestructureNames = Array.from(new Set([...pathParamNames, ...extraParamNames]));
+        const destructureList = allDestructureNames.join(', ');
+        const typeName = info.input;
+        if (typeName && !isSkippableImportType(typeName) && /^[A-Za-z_][A-ZaZ0-9_]*$/.test(typeName)) allReferencedTypes.add(typeName);
+
+        const queryTemplate = extraParamNames.length > 0 ? '?' + extraParamNames.map(n => n + '=${' + n + '}').join('&') : '';
+        const methodParts = [
+            '  ',
+            k,
+            '({ ',
+            destructureList,
+            ' }: ',
+            typeName,
+            '): string { ',
+            prefixedReturn('`' + templateForOutput + queryTemplate + '`'),
+            ' }'
+        ];
+        methodStr += methodParts.join('');
+        methodLines.push(methodStr);
+        return;
+    }
+
+    // If there are no params and this endpoint has no meaningful input, emit a no-arg method.
+    if (paramsSignatureParts.length === 0) {
+        methodStr += `  ${k}(): string { ` + prefixedReturn("'" + urlPath + "'") + ` }`;
+        methodLines.push(methodStr);
+        return;
+    }
+
+    // Non-destructured emission
+    if (extraParamNames.length > 0) {
+        const queryTemplate = '?' + extraParamNames.map(n => n + '=${' + n + '}').join('&');
+        const methodParts = ['  ', k, '(', paramsSignature, '): string { ', prefixedReturn('`' + templateForOutput + queryTemplate + '`'), ' }'];
+        methodStr += methodParts.join('');
+        methodLines.push(methodStr);
+    } else {
+        methodStr += `  ${k}(${paramsSignature}): string { ` + prefixedReturn('`' + templateForOutput + '`') + ` }`;
+        methodLines.push(methodStr);
+    }
+});
+
+// Prefix returned URL strings with the configured base URL.
+// Input (expr) must be a JS/TS string expression (e.g. "'/v1/x'" or "`/v1/${id}`").
+function prefixedReturn(expr) {
+    return `return getBackendApiDomain() + ${expr};`;
+}
+
+// Build import list
+const importTypes = Array.from(allReferencedTypes)
+    .filter(t => !isSkippableImportType(t))
+    .filter(t => /^[A-Za-z_][A-Za-z0-9_]*$/.test(String(t)))
+    .sort();
+
+// Determine the correct message file to import from based on service name
+const normalizedSvc = (serviceName || '').replace(/service$/i, '');
+const messageFile = normalizedSvc; // e.g., "post" for post-service
+
+let endpointsOutput = '';
+
+endpointsOutput += `import { getBackendApiDomain } from "./envWrapper";\n`;
+
+// Add imports if there are types to import
+if (importTypes.length > 0) {
+    endpointsOutput += `import type { ${importTypes.join(', ')} } from './messages/${messageFile}';\n`;
+    // Re-export all imported types for convenience
+    endpointsOutput += `export type { ${importTypes.join(', ')} } from './messages/${messageFile}';\n\n`;
+} else {
+    endpointsOutput += `\n`;
+}
+
+endpointsOutput += `// Auto-generated endpoint URLs for ${serviceObjectName} service\n\n`;
+endpointsOutput += `export const ${serviceObjectName} = {\n`;
+endpointsOutput += methodLines.join(',\n\n');
+endpointsOutput += `,\n};\n`;
+
+const endpointsOutFile = path.join(path.dirname(outputFile), `${serviceName.replace("_", "-")}-endpoints.ts`);
+fs.writeFileSync(endpointsOutFile, endpointsOutput);
+console.log(`Generated endpoints for ${serviceObjectName}: ${Object.keys(endpoints).length} entries`);
+
+// Some inferred "types" are not real TS type exports and must never be imported.
+function isSkippableImportType(t) {
+    if (!t) return true;
+    const s = String(t).trim();
+    return s === 'void' || s === '{}' || s === 'Empty' || s === 'any';
+}
+
+// True when an endpoint has no meaningful input payload for clients.
+function isNoInputType(t) {
+    if (!t) return true;
+    const s = String(t).trim();
+    return s === 'void' || s === '{}' || s === 'Empty';
+}