@bagelink/sdk 1.2.20 → 1.2.25

package/src/openAPITools/functionGenerator.ts

@@ -1,6 +1,7 @@
 import type {
 	OperationObject,
 	ParameterObject,
+	PathItemObject,
 	PathsObject,
 	RequestBodyObject,
 	ResponseObject,
@@ -17,6 +18,9 @@ import {
 	toPascalCase,
 } from './utils'
 
+/**
+ * Collection of types referenced across generated functions
+ */
 const allTypes: string[] = []
 
 const primitiveTypes = [
@@ -28,40 +32,82 @@ const primitiveTypes = [
 	'any',
 	'{ [key: string]: any }',
 	'undefined',
-	'{ [key: string]: any }',
 ]
 
-function collectTypeForImportStatement(typeName: string) {
+/**
+ * Upload options interface for file upload operations
+ */
+interface UploadOptions {
+	onUploadProgress?: (progressEvent: any) => void
+	dirPath?: string
+	tags?: string[]
+}
+
+/**
+ * Represents a unique path and method combination
+ */
+interface PathOperation {
+	path: string
+	method: string
+}
+
+// Tracking for function generation
+const functionsInventory: Record<string, string> = {}
+const pathOperations: PathOperation[] = []
+
+/**
+ * Collects non-primitive types for import statements
+ * @param typeName - The type name to analyze
+ */
+function collectTypeForImportStatement(typeName: string): void {
 	typeName = typeName.trim().replace('[]', '')
+
+	// Handle union types
 	if (typeName.includes('|')) {
 		typeName.split('|').forEach((singleType) => {
-			collectTypeForImportStatement(singleType)
+			collectTypeForImportStatement(singleType.trim())
 		})
 		return
 	}
+
 	const isPrimitive = primitiveTypes.includes(typeName)
 	typeName = formatType(typeName)
+
 	if (!typeName || isPrimitive) return
 	if (!allTypes.includes(typeName)) allTypes.push(typeName)
 }
 
+/**
+ * Wrapper for schemaToType that also collects types for import statements
+ * @param schema - The schema to convert to a type
+ * @returns The TypeScript type string
+ */
 function schemaToTypeWithCollection(schema?: SchemaObject): string {
 	const type = schemaToType(schema)
 	collectTypeForImportStatement(type)
 	return type
 }
 
+/**
+ * Extracts the response type from an OpenAPI response object
+ * @param response - The OpenAPI response object
+ * @returns The TypeScript type string or undefined
+ */
 function getResponseType(response: ResponseObject): string | undefined {
 	const mediaTypeObject = response.content?.['application/json']
-	if (!mediaTypeObject || !mediaTypeObject.schema) return
-	const responseType = schemaToTypeWithCollection(mediaTypeObject.schema)
-	return responseType
+	if (!mediaTypeObject?.schema) return undefined
+	return schemaToTypeWithCollection(mediaTypeObject.schema)
 }
 
+/**
+ * Generates the response type string from OpenAPI responses
+ * @param responses - The OpenAPI responses object
+ * @returns The TypeScript response type string
+ */
 function generateResponseType(responses?: ResponsesObject): string {
 	if (!responses) return ''
-	const types: string[] = []
 
+	const types: string[] = []
 	for (const [statusCode, response] of Object.entries(responses)) {
 		if (statusCode.startsWith('2')) {
 			const responseType = getResponseType(response)
@@ -70,88 +116,47 @@ function generateResponseType(responses?: ResponsesObject): string {
 			}
 		}
 	}
+
 	return types.join(' | ')
 }
 
 /**
- * Generates the string representation of an Axios function call.
- * @param method - The HTTP method (get, post, etc.).
- * @param formattedPath - The API endpoint path, formatted with template literals for parameters.
- * @param allParams - All parameters required for the function, formatted as a string.
- * @param responseTypeStr - The expected response type for the function.
- * @param parameters - Additional configuration parameters, if any.
- * @returns A string representing the Axios function.
+ * Extracts path parameters from an API path
+ * @param path - The API path
+ * @returns Array of parameter names or undefined
  */
-
-function generateAxiosFunction(
-	method: string,
-	formattedPath: string,
-	allParams: string,
-	responseTypeStr: string,
-	parameters: any,
-	requestBodyPayload: string
-): string {
-	if (allParams === 'undefined') allParams = ''
-
-	let axiosFunction = `async (${allParams})${responseTypeStr} => {`
-
-	if (requestBodyPayload === 'formData') {
-		const paramStr = parameters?.config?.params
-			? `params: {${parameters.config.params}}`
-			: ''
-
-		// Check if this is a file upload (with specific file parameter) or general form data
-		if (allParams.includes('file: File')) {
-			axiosFunction += `
-        const formData = new FormData()
-        formData.append('upload', file)
-        return axios.${method}(${formattedPath}, formData, {
-            headers: { 'Content-Type': 'multipart/form-data' },
-            onUploadProgress: options?.onUploadProgress${paramStr ? `, ${paramStr}` : ''}
-        })`
-		} else {
-			// Generic FormData handling
-			axiosFunction += `
-        return axios.${method}(${formattedPath}, formData, {
-            headers: { 'Content-Type': 'multipart/form-data' }${paramStr ? `, ${paramStr}` : ''}
-        })`
-		}
-	} else {
-		const paramStr = parameters?.config?.params
-			? `, { params: {${parameters.config.params}} }`
-			: ''
-		const bodyVar = requestBodyPayload ? `${requestBodyPayload}` : '{}'
-		axiosFunction += `return axios.${method}(${formattedPath}${['get', 'delete'].includes(method) ? paramStr : `, ${bodyVar}${paramStr}`})`
-	}
-
-	axiosFunction += '}'
-	return axiosFunction
-}
-
-// eslint-disable-next-line regexp/no-unused-capturing-group
-const pathParamRegex = /\{([^}]+)\}/g
-function getParamsFromPath(path: string) {
-	const params = path.match(pathParamRegex)?.map(p => p.slice(1, -1))
-	return params
+function getParamsFromPath(path: string): string[] | undefined {
+	const pathParamRegex = /\{[^}]+\}/g
+	return path.match(pathParamRegex)?.map(p => p.slice(1, -1))
 }
 
-function formatPathWithParams(path: string) {
+/**
+ * Formats a path with template literals for parameters
+ * @param path - The API path
+ * @returns The formatted path string
+ */
+function formatPathWithParams(path: string): string {
 	const params = getParamsFromPath(path)
-	const formattedPath = params
-		? `\`${path.replace(pathParamRegex, v => `$${toCamelCase(v)}`)}\``
-		: `'${path}'`
-	return formattedPath
+	if (!params) return `'${path}'`
+
+	return `\`${path.replace(/\{([^}]+)\}/g, (_, paramName) => `\${${toCamelCase(paramName)}}`)}\``
 }
 
+/**
+ * Processes request body information from an OpenAPI operation
+ * @param requestBody - The OpenAPI request body object
+ * @returns Object containing request body parameter and payload information
+ */
 function generateRequestBody(requestBody?: RequestBodyObject): {
-	[key: string]: string
+	requestBodyParam: string
+	requestBodyPayload: string
 } {
 	if (!requestBody?.content)
 		return { requestBodyParam: '', requestBodyPayload: '' }
 
 	const { content } = requestBody
 
-	// Check if this is a multipart/form-data request
+	// Handle multipart/form-data requests (file uploads)
 	if (content['multipart/form-data']) {
 		const multipartFormData = content['multipart/form-data']
 
@@ -180,6 +185,7 @@ function generateRequestBody(requestBody?: RequestBodyObject): {
 	const bodySchema = jsonContent.schema
 	const requestBodyType = schemaToType(bodySchema)
 	collectTypeForImportStatement(requestBodyType)
+
 	const requestBodyPayload = (
 		toCamelCase(bodySchema.title) || toCamelCase(requestBodyType) || 'requestBody'
 	)
@@ -189,40 +195,24 @@ function generateRequestBody(requestBody?: RequestBodyObject): {
 		schema: bodySchema,
 		defaultValue: bodySchema.default,
 	})
+
 	return { requestBodyParam, requestBodyPayload }
 }
 
 /**
- * Combines and formats function parameters and request body parameters into a single parameter string.
- * @param parameters - The parameters derived from the OpenAPI specification.
- * @param requestBodyParam - The parameter representing the request body.
- * @returns A string representing all combined parameters.
+ * Generates function parameters from OpenAPI parameters
+ * @param params - The OpenAPI parameters
+ * @param isFileUpload - Whether this is a file upload operation
+ * @returns Object containing parameter information
  */
-function combineAllParams(
-	parameters: { params?: string },
-	requestBodyParam: string
-): string {
-	let allParamsArray: string[] = []
-	if (parameters && parameters.params)
-		allParamsArray = parameters.params.split(',').map(p => p.trim())
-	if (requestBodyParam) allParamsArray.push(requestBodyParam.trim())
-
-	allParamsArray = allParamsArray
-		.filter(p => p)
-		.sort((a, b) => (a.includes('?') ? 1 : -1) - (b.includes('?') ? 1 : -1))
-
-	return allParamsArray.join(', ')
-}
-
 function generateFunctionParameters(
 	params?: ParameterObject[],
 	isFileUpload = false
-) {
+): { params?: string, config?: { params?: string } } {
 	if (!params?.length) return {}
 
-	// For file uploads, we want to handle query parameters differently
+	// Special handling for file uploads
 	if (isFileUpload) {
-		// Don't include these as function parameters, they'll be part of options
 		return {
 			config: {
 				params: 'dir_path: options?.dirPath, tags: options?.tags',
@@ -232,7 +222,7 @@ function generateFunctionParameters(
 	}
 
 	const functionParams: string[] = []
-	const paramList: string[] = []
+	const queryParams: string[] = []
 
 	for (const param of params) {
 		const paramType = schemaToType(param.schema)
@@ -252,7 +242,7 @@ function generateFunctionParameters(
 		}
 
 		if (param.in === 'query' || param.in === 'header') {
-			paramList.push(
+			queryParams.push(
 				paramName === varName ? paramName : `'${paramName}': ${varName}`
 			)
 		}
@@ -260,10 +250,102 @@ function generateFunctionParameters(
 
 	return {
 		params: functionParams.join(', '),
-		config: paramList.length ? { params: paramList.join(', ') } : {},
+		config: queryParams.length ? { params: queryParams.join(', ') } : undefined,
+	}
+}
+
+/**
+ * Combines and formats all parameters into a single parameter string
+ * @param parameters - The parameters object
+ * @param requestBodyParam - The request body parameter
+ * @returns A formatted parameter string
+ */
+function combineAllParams(
+	parameters: { params?: string },
+	requestBodyParam: string
+): string {
+	let allParamsArray: string[] = []
+
+	if (parameters.params) {
+		allParamsArray = parameters.params.split(',').map(p => p.trim())
+	}
+
+	if (requestBodyParam) {
+		allParamsArray.push(requestBodyParam.trim())
+	}
+
+	// Sort required parameters before optional ones
+	return allParamsArray
+		.filter(Boolean)
+		.sort((a, b) => (a.includes('?') ? 1 : -1) - (b.includes('?') ? 1 : -1))
+		.join(', ')
+}
+
+/**
+ * Generates an Axios function call as a string
+ * @param method - The HTTP method
+ * @param formattedPath - The formatted API path
+ * @param allParams - The combined parameter string
+ * @param responseTypeStr - The response type string
+ * @param parameters - Additional parameters
+ * @param requestBodyPayload - The request body payload
+ * @returns A string with the Axios function
+ */
+function generateAxiosFunction(
+	method: string,
+	formattedPath: string,
+	allParams: string,
+	responseTypeStr: string,
+	parameters: { config?: { params?: string } },
+	requestBodyPayload: string
+): string {
+	if (allParams === 'undefined') allParams = ''
+
+	let axiosFunction = `async (${allParams})${responseTypeStr} => {`
+	const paramStr = parameters.config?.params
+		? `params: {${parameters.config.params}}`
+		: ''
+
+	if (requestBodyPayload === 'formData') {
+		// Check if this is a file upload with specific file parameter
+		if (allParams.includes('file: File')) {
+			axiosFunction += `
+        const formData = new FormData()
+        formData.append('upload', file)
+        return axios.${method}(${formattedPath}, formData, {
+            headers: { 'Content-Type': 'multipart/form-data' },
+            onUploadProgress: options?.onUploadProgress${paramStr ? `, ${paramStr}` : ''}
+        })`
+		} else {
+			// Generic FormData handling
+			axiosFunction += `
+        return axios.${method}(${formattedPath}, formData, {
+            headers: { 'Content-Type': 'multipart/form-data' }${paramStr ? `, ${paramStr}` : ''}
+        })`
+		}
+	} else {
+		const configParams = paramStr ? `, { ${paramStr} }` : ''
+		const bodyVar = requestBodyPayload || '{}'
+
+		// Handle different HTTP methods appropriately
+		axiosFunction += `return axios.${method}(${formattedPath}${
+			['get', 'delete'].includes(method)
+				? configParams
+				: `, ${bodyVar}${configParams}`
+		})`
 	}
+
+	axiosFunction += '}'
+	return axiosFunction
 }
 
+/**
+ * Generates a function for an OpenAPI operation
+ * @param method - The HTTP method
+ * @param path - The API path
+ * @param operation - The OpenAPI operation object
+ * @returns The function as a string
+ */
 function generateFunctionForOperation(
 	method: string,
 	path: string,
@@ -271,11 +353,11 @@ function generateFunctionForOperation(
 ): string {
 	if (!operation) return ''
 
-	// Check if this is a file upload operation by looking at the schema reference
-	const isFileUpload
-		= operation.requestBody?.content[
-			'multipart/form-data'
-		]?.schema?.$ref?.includes('Body_upload_files')
+	// Check if this is a file upload
+	const isFileUpload = operation.requestBody?.content[
+		'multipart/form-data'
+	]?.schema?.$ref?.includes('Body_upload_files')
+
 	const parameters = generateFunctionParameters(
 		operation.parameters,
 		isFileUpload
@@ -284,7 +366,7 @@ function generateFunctionForOperation(
 		operation.requestBody
 	)
 
-	// For file uploads, ignore the regular parameter generation
+	// Handle parameters appropriately based on operation type
 	const allParams = isFileUpload
 		? 'file: File, options?: UploadOptions & { dirPath?: string, tags?: string[] }'
 		: combineAllParams(parameters, requestBodyParam)
@@ -294,129 +376,275 @@ function generateFunctionForOperation(
 		? `: Promise<AxiosResponse<${responseType}>>`
 		: ''
 
-	return generateAxiosFunction(
-		method,
-		formatPathWithParams(path),
-		allParams,
-		responseTypeStr,
-		parameters,
-		requestBodyPayload
-	)
-}
+	// Create JSDoc comment with OpenAPI documentation
+	let functionComment = '/**\n'
 
-const generateRandomString = () => Math.random().toString(36).slice(7)
+	// Add summary
+	if (operation.summary) {
+		functionComment += ` * ${operation.summary}\n`
+	}
 
-const DOUBLE_QUOTE_REGEX = /"([^"]+)":/g // ! TODO: @nevehallon believes this may not be necessary
+	// Add description if available
+	if (operation.description) {
+		// If there's already a summary, add a line break
+		if (operation.summary) functionComment += ` *\n`
 
-function fileTemplate(
-	tsString: string,
-	typeForImport: string[],
-	baseURL: string
-) {
-	const templateCode = `import ax from 'axios';
-		 import type { AxiosResponse } from 'axios';
-		 import type {${typeForImport.join(', ')}} from './types.d';
+		// Split description into lines and add each line with proper JSDoc formatting
+		const descriptionLines = operation.description.split('\n')
+		descriptionLines.forEach((line: string) => {
+			functionComment += ` * ${line}\n`
+		})
+	}
+
+	// Add endpoint path and method information
+	functionComment += ` *\n * @endpoint ${method.toUpperCase()} ${path}\n`
+
+	// Add parameter documentation if available
+	if (operation.parameters?.length) {
+		functionComment += ' *\n'
+		operation.parameters.forEach((param) => {
+			const paramType = schemaToType(param.schema)
+			const paramName = toCamelCase(param.name)
+			const required = param.required ? '' : '?'
+
+			functionComment += ` * @param {${paramType}} ${paramName}${required}`
+
+			// Add parameter description if available
+			if (param.description) {
+				functionComment += ` - ${param.description}`
+			} else {
+				functionComment += ` - ${param.name} parameter`
+			}
 
-	export interface UploadOptions {
-		onUploadProgress?: (progressEvent: any) => void
-		dirPath?: string
-		tags?: string[]
+			functionComment += '\n'
+		})
 	}
 
-	export const axios = ax.create({baseURL:${baseURL}, withCredentials: true});
-	${tsString}`
-	return templateCode.replace(DOUBLE_QUOTE_REGEX, '$1:')
-}
+	// Add requestBody documentation if available
+	if (operation.requestBody && requestBodyParam) {
+		const bodyParamName = requestBodyParam.split(':')[0].trim()
+		const bodyParamType = requestBodyParam.split(':')[1]?.split('=')[0]?.trim() || 'any'
 
-interface PathOperation {
-	path: string
-	method: string
-}
+		functionComment += ` * @param {${bodyParamType}} ${bodyParamName}`
 
-const functionsInventory: Record<string, string> = {}
-const pathOperations: PathOperation[] = []
+		if (operation.requestBody.description) {
+			functionComment += ` - ${operation.requestBody.description}`
+		} else {
+			functionComment += ` - Request body`
+		}
+
+		functionComment += '\n'
+	}
+
+	// Add response documentation
+	if (responseType) {
+		functionComment += ` * @returns {Promise<AxiosResponse<${responseType}>>} The API response\n`
+
+		// Include any response descriptions for 2xx status codes
+		for (const [statusCode, response] of Object.entries(operation.responses)) {
+			if (statusCode.startsWith('2') && response.description) {
+				functionComment += ` * @response ${statusCode} - ${response.description}\n`
+			}
+		}
+	}
+
+	functionComment += ' */\n'
+
+	return functionComment + generateAxiosFunction(
+		method,
+		formatPathWithParams(path),
+		allParams,
+		responseTypeStr,
+		parameters,
+		requestBodyPayload
+	)
+}
 
-function hasConflict(path: string, method: string) {
+/**
+ * Checks if there's a conflict with an existing path operation
+ * @param path - The API path
+ * @param method - The HTTP method
+ * @returns Whether there's a conflict
+ */
+function hasConflict(path: string, method: string): boolean {
 	const cleanPathName = path
 		.split('/')
 		.filter(p => p && !/\{|\}/.test(p))
 		.join('/')
+
 	const matchingPaths = pathOperations.filter(
 		p => p.path === cleanPathName && p.method === method
 	)
+
 	pathOperations.push({ path: cleanPathName, method })
 	return matchingPaths.length > 0
 }
 
-// Creates a placeholder for a function and stores its body in the inventory
+/**
+ * Generates a random string for function IDs
+ * @returns A random string
+ */
+function generateRandomString(): string {
+	return Math.random().toString(36).slice(7)
+}
+
+/**
+ * Creates a function placeholder and stores it in the inventory
+ * @param path - The API path
+ * @param method - The HTTP method
+ * @param operation - The OpenAPI operation
+ * @returns A function ID
+ */
 function createFunctionPlaceholder(
 	path: string,
 	method: string,
-	operation: any
-) {
+	operation: OperationObject | undefined
+): string {
 	const funcID = generateRandomString()
-	functionsInventory[funcID] = generateFunctionForOperation(
-		method,
-		path,
-		operation
-	)
+	if (operation) {
+		functionsInventory[funcID] = generateFunctionForOperation(
+			method,
+			path,
+			operation
+		)
+	} else {
+		functionsInventory[funcID] = ''
+	}
 	return funcID
 }
 
+/**
+ * Handles a path segment when generating functions
+ * @param path - The API path
+ * @param operation - The OpenAPI operation
+ * @param existingObj - Existing object to merge with
+ * @returns The updated object
+ */
 function handlePathSegment(
 	path: string,
-	operation: any,
-	existingObj: { [key: string]: any } = {}
-) {
-	const methods = Object.keys(operation)
-	const obj: { [key: string]: any } = {}
+	operation: PathItemObject,
+	existingObj: Record<string, any> = {}
+): Record<string, any> {
+	const methods = Object.keys(operation) as Array<keyof PathItemObject>
+	const obj: Record<string, any> = {}
+
 	for (const method of methods) {
 		let functionName = method.toLowerCase()
+
 		if (hasConflict(path, method)) {
-			const params: string[] | undefined = getParamsFromPath(path)
+			const params = getParamsFromPath(path)
 			functionName += params ? `By${toPascalCase(params.pop() || '')}` : 'All'
 		}
+
 		obj[functionName] = createFunctionPlaceholder(
 			path,
 			method,
 			operation[method]
 		)
 	}
+
 	return { ...obj, ...existingObj }
 }
 
-export function generateFunctions(paths: PathsObject, baseUrl: string) {
-	let tsString = ''
-	const body: { [key: string]: any } = {}
+/**
+ * Generates TypeScript API client functions from OpenAPI paths
+ * @param paths - The OpenAPI paths object
+ * @param baseUrl - The base URL for the API
+ * @returns The generated TypeScript code
+ */
+export function generateFunctions(paths: PathsObject, baseUrl: string): string {
+	const body: Record<string, any> = {}
 	const allPathsClean = Object.keys(paths).map(cleanPath)
+
+	// Process all paths to generate functions
 	for (const [path, operation] of Object.entries(paths)) {
 		const splitPath = path.split('/').filter(p => p && !/\{|\}/.test(p))
+
 		splitPath.reduce((acc, key: string, index: number, array: string[]) => {
 			const objFuncKey = toCamelCase(key)
 			if (!objFuncKey) return acc
-			const methods = Object.keys(operation)
+
+			const methods = Object.keys(operation) as Array<keyof PathItemObject>
+
 			if (
 				index === array.length - 1
 				&& methods.length === 1
 				&& allPathsClean.filter(p => p === cleanPath(path)).length === 1
 			) {
-				const method: string = methods[0]
-				const opp: any = { ...operation }[method]
-				acc[objFuncKey] = createFunctionPlaceholder(path, methods[0], opp)
+				// Single method endpoint with unique path
+				const method = methods[0]
+				const opp = operation[method]
+				acc[objFuncKey] = createFunctionPlaceholder(path, method, opp)
 			} else if (index === array.length - 1) {
+				// Multiple methods endpoint or path with conflicts
 				acc[objFuncKey] = handlePathSegment(path, operation, acc[objFuncKey])
 			} else if (!acc[objFuncKey] || typeof acc[objFuncKey] !== 'object') {
+				// Intermediate path segment
 				acc[objFuncKey] = {}
 			}
+
 			return acc[objFuncKey]
 		}, body)
 	}
+
+	// Generate TypeScript code from processed paths
+	let tsString = ''
+
+	// Convert object structure to TypeScript
 	for (const [parent, object] of Object.entries(body)) {
-		tsString += `export const ${parent} = ${JSON.stringify(object, undefined, 2)};\n`
+		tsString += `
+/**
+ * API functions for ${parent} endpoints
+ */
+export const ${parent} = ${JSON.stringify(object, undefined, 2)};\n`
 	}
+
+	// Replace placeholders with actual function bodies
 	Object.entries(functionsInventory).forEach(([key, value]) => {
 		tsString = tsString.replace(`"${key}"`, value)
 	})
-	tsString = fileTemplate(tsString, allTypes, baseUrl)
-	return tsString
+
+	// Generate the final TypeScript file
+	return fileTemplate(tsString, allTypes, baseUrl)
+}
+
+/**
+ * Generates the TypeScript file template
+ * @param tsString - The generated TypeScript code
+ * @param typeForImport - Types to import
+ * @param baseURL - The base URL for the API
+ * @returns The final TypeScript file content
+ */
+function fileTemplate(
+	tsString: string,
+	typeForImport: string[],
+	baseURL: string
+): string {
+	const templateCode = `import ax from 'axios';
+import type { AxiosResponse } from 'axios';
+import type { ${typeForImport.join(', ')} } from './types.d';
+
+/**
+ * Options for file upload operations
+ */
+export interface UploadOptions {
+	/** Progress callback for upload operations */
+	onUploadProgress?: (progressEvent: any) => void
+	/** Directory path for the uploaded file */
+	dirPath?: string
+	/** Tags to associate with the uploaded file */
+	tags?: string[]
+}
+
+/**
+ * Configured axios instance for API requests
+ * @example
+ * // Making a direct request with the axios instance
+ * const response = await axios.get('/some-endpoint');
+ */
+export const axios = ax.create({baseURL: ${baseURL}, withCredentials: true});
+${tsString}`
+
+	// Remove potential double quotes around property names
+	return templateCode.replace(/"([^"]+)":/g, '$1:')
 }