@bagelink/sdk 1.20.52 → 1.20.56

package/src/openAPITools/functionGenerator.js

@@ -0,0 +1,979 @@
+import { isSSEStream, extractSSEEventTypes, extractSSEEventInfo, extractSSEEventSchemas } from './streamDetector';
+import { dereference, isReferenceObject } from './types/utils';
+import { cleanPath, formatType, formatVarType, schemaToType, toCamelCaseSafe, toPascalCase, } from './utils';
+/**
+ * Collection of types referenced across generated functions
+ */
+const allTypes = [];
+const primitiveTypes = [
+    'string',
+    'number',
+    'boolean',
+    'null',
+    'void',
+    'any',
+    '{ [key: string]: any }',
+    'undefined',
+];
+// Tracking for function generation
+const functionsInventory = {};
+const pathOperations = [];
+const streamEventTypes = {}; // Track stream endpoints and their event types
+const streamEventInfo = {}; // Track detailed event info for type generation
+const streamEventSchemas = {}; // Track typed schemas: streamTypeName → {event → TSType}
+/**
+ * Collects non-primitive types for import statements
+ * @param typeName - The type name to analyze
+ */
+function collectTypeForImportStatement(typeName) {
+    typeName = typeName.trim().replace('[]', '');
+    // Handle union types
+    if (typeName.includes('|')) {
+        typeName.split('|').forEach((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) {
+    const type = schemaToType(schema);
+    collectTypeForImportStatement(type);
+    return type;
+}
+/**
+ * Extracts the response type from an OpenAPI response object
+ * @param response - The OpenAPI response object
+ * @returns Object with type string and whether it's an array
+ */
+function getResponseType(response) {
+    if (isReferenceObject(response)) {
+        return { type: undefined, isArray: false };
+    }
+    const mediaTypeObject = response.content?.['application/json'];
+    if (!mediaTypeObject?.schema) {
+        return { type: undefined, isArray: false };
+    }
+    const schema = dereference(mediaTypeObject.schema);
+    const typeString = schemaToTypeWithCollection(schema);
+    // Check if schema is an array type
+    const isArray = schema?.type === 'array' || typeString?.endsWith('[]') || false;
+    return { type: typeString, isArray };
+}
+/**
+ * Generates the response type string from OpenAPI responses
+ * @param responses - The OpenAPI responses object
+ * @returns Object with type string and array detection
+ */
+function generateResponseType(responses) {
+    if (!responses) {
+        return { type: '', isArray: false };
+    }
+    const types = [];
+    let isArrayResponse = false;
+    for (const [statusCode, response] of Object.entries(responses)) {
+        if (statusCode.startsWith('2')) {
+            const { type: responseType, isArray } = getResponseType(response);
+            if (responseType && responseType !== 'any') {
+                types.push(responseType);
+                // If any successful response is an array, mark as array
+                if (isArray) {
+                    isArrayResponse = true;
+                }
+            }
+        }
+    }
+    return { type: types.join(' | '), isArray: isArrayResponse };
+}
+/**
+ * Extracts path parameters from an API path
+ * @param path - The API path
+ * @returns Array of parameter names or undefined
+ */
+function getParamsFromPath(path) {
+    const pathParamRegex = /\{[^}]+\}/g;
+    return path.match(pathParamRegex)?.map(p => p.slice(1, -1));
+}
+/**
+ * Formats a path with template literals for parameters
+ * @param path - The API path
+ * @returns The formatted path string
+ */
+function formatPathWithParams(path) {
+    const params = getParamsFromPath(path);
+    if (!params) {
+        return `'${path}'`;
+    }
+    return `\`${path.replace(/\{([^}]+)\}/g, (_, paramName) => `\${${toCamelCaseSafe(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) {
+    // if (!requestBody || !requestBody?.content)
+    // 	return { requestBodyParam: '', requestBodyPayload: '' }
+    const content = dereference(requestBody)?.content;
+    if (!content || Object.keys(content).length === 0) {
+        return { requestBodyParam: '', requestBodyPayload: '' };
+    }
+    // Handle multipart/form-data requests (file uploads)
+    if (content['multipart/form-data']) {
+        const multipartFormData = content['multipart/form-data'];
+        // Special case for file uploads
+        if (isReferenceObject(multipartFormData.schema) && multipartFormData.schema?.$ref?.includes('Body_upload_files')) {
+            return {
+                requestBodyParam: 'file: File, options?: UploadOptions & { dirPath?: string, tags?: string[] }',
+                requestBodyPayload: 'formData',
+            };
+        }
+        // Generic form data handling
+        return {
+            requestBodyParam: 'formData: FormData',
+            requestBodyPayload: 'formData',
+        };
+    }
+    // Handle regular JSON requests
+    const jsonContent = content['application/json'];
+    if (!jsonContent || !jsonContent.schema) {
+        return { requestBodyParam: '', requestBodyPayload: '' };
+    }
+    const bodySchema = dereference(jsonContent.schema);
+    const requestBodyType = schemaToType(bodySchema);
+    collectTypeForImportStatement(requestBodyType);
+    const requestBodyPayload = (toCamelCaseSafe(bodySchema.title) || toCamelCaseSafe(requestBodyType) || 'requestBody');
+    const requestBodyParam = formatVarType({
+        varName: requestBodyPayload,
+        schema: bodySchema,
+        defaultValue: bodySchema.default,
+    });
+    return { requestBodyParam, requestBodyPayload };
+}
+/**
+ * Generates function parameters from OpenAPI parameters
+ * @param path - The API path (used to detect path params missing from spec)
+ * @param params - The OpenAPI parameters
+ * @param isFileUpload - Whether this is a file upload operation
+ * @returns Object containing parameter information
+ */
+function generateFunctionParameters(path, params, isFileUpload = false) {
+    // Special handling for file uploads
+    if (isFileUpload) {
+        return {
+            config: {
+                params: 'dir_path: options?.dirPath, tags: options?.tags',
+            },
+            params: '', // Empty string to ensure file is the first parameter
+        };
+    }
+    const functionParams = [];
+    const queryParams = [];
+    // Track which path params are already declared from the spec
+    const declaredPathParams = new Set();
+    for (const p of (params ?? [])) {
+        const param = dereference(p);
+        const pSchema = dereference(param.schema);
+        const paramType = schemaToType(pSchema);
+        collectTypeForImportStatement(paramType);
+        const paramName = param.name;
+        let varName = toCamelCaseSafe(param.name);
+        // If param name differs from varName (e.g., "last-event-id" → "lastEventId"),
+        // prefix with underscore to avoid unused variable linting errors
+        const needsMapping = paramName !== varName;
+        if (needsMapping && (param.in === 'query' || param.in === 'header')) {
+            varName = `_${varName}`;
+        }
+        if (param.in === 'path') {
+            declaredPathParams.add(paramName);
+        }
+        if (param.in === 'path' || param.in === 'query' || param.in === 'header') {
+            functionParams.push(formatVarType({
+                varName,
+                schema: pSchema,
+                required: param.required,
+                defaultValue: pSchema?.default,
+            }));
+        }
+        if (param.in === 'query' || param.in === 'header') {
+            queryParams.push(needsMapping ? `'${paramName}': ${varName}` : paramName);
+        }
+    }
+    // Inject any path params present in the URL but missing from the spec's parameters list
+    const pathParamsInUrl = getParamsFromPath(path) ?? [];
+    for (const paramName of pathParamsInUrl) {
+        if (!declaredPathParams.has(paramName)) {
+            const varName = toCamelCaseSafe(paramName);
+            functionParams.unshift(`${varName}: string`);
+        }
+    }
+    if (functionParams.length === 0 && queryParams.length === 0) {
+        return {};
+    }
+    return {
+        params: functionParams.join(', '),
+        config: queryParams.length ? { params: queryParams.join(', ') } : undefined,
+    };
+}
+/**
+ * Parses a parameter string into name, type, and default value
+ * @param paramStr - The parameter string to parse
+ * @returns Object containing parsed parameter information
+ */
+function parseParameter(paramStr) {
+    const trimmed = paramStr.trim();
+    // Check if parameter is optional (has ?)
+    const isOptional = trimmed.includes('?:');
+    // Extract parameter name
+    const nameMatch = trimmed.match(/^([a-z_$][\w$]*)/i);
+    const name = nameMatch?.[1] || '';
+    // Extract type (between : and = or end of string)
+    const typeMatch = trimmed.match(/:\s*([^=]+)/);
+    const type = typeMatch?.[1]?.trim() || 'any';
+    // Extract default value if exists
+    const defaultMatch = trimmed.match(/[=](.+)$/);
+    const defaultValue = defaultMatch?.[1]?.trim();
+    return { name, type, defaultValue, isOptional };
+}
+/**
+ * Combines and formats all parameters into a single object destructuring parameter
+ * @param parameters - The parameters object
+ * @param requestBodyParam - The request body parameter
+ * @returns A formatted parameter string with object destructuring
+ */
+function combineAllParams(parameters, requestBodyParam) {
+    let allParamsArray = [];
+    if (parameters.params) {
+        allParamsArray = parameters.params.split(',').map(p => p.trim());
+    }
+    if (requestBodyParam) {
+        allParamsArray.push(requestBodyParam.trim());
+    }
+    if (allParamsArray.length === 0) {
+        return '';
+    }
+    // Parse all parameters
+    const parsedParams = allParamsArray.filter(Boolean).map(parseParameter);
+    // Build destructuring pattern with default values
+    const destructuredNames = parsedParams
+        .map(p => p.defaultValue ? `${p.name} = ${p.defaultValue}` : p.name)
+        .join(', ');
+    // Build type definition - all parameters should be optional in the type
+    const typeDefinition = parsedParams
+        .map((p) => {
+        // Remove default value from type, make all optional
+        return `${p.name}?: ${p.type}`;
+    })
+        .join(', ');
+    return `{ ${destructuredNames} }: { ${typeDefinition} } = {}`;
+}
+/**
+ * Generates a unique type name for a stream endpoint
+ */
+function generateStreamTypeName(path) {
+    return `${toPascalCase(path
+        .split('/')
+        .filter(p => p && !/\{|\}/.test(p))
+        .join('_'))}StreamEvents`;
+}
+/**
+ * Generates a Stream function for SSE endpoints with full type safety
+ * @param method - The HTTP method
+ * @param path - The original API path
+ * @param formattedPath - The formatted API path
+ * @param allParams - The combined parameter string
+ * @param requestBodyPayload - The request body payload
+ * @param eventTypes - Array of SSE event types
+ * @param queryParams - Query/header parameter mappings (e.g. "'run_id': _runId")
+ * @returns A string with the SSE stream function
+ */
+function generateStreamFunction(method, path, formattedPath, allParams, requestBodyPayload, eventTypes, queryParams) {
+    if (allParams === 'undefined') {
+        allParams = '';
+    }
+    // Extract parameter names for the stream call (unused but kept for future use)
+    // const paramNames = allParams ? allParams.match(/\w+(?=\s*[?:])/g) || [] : []
+    const bodyVar = requestBodyPayload || '{}';
+    // Generate type name for this stream
+    const streamTypeName = generateStreamTypeName(path);
+    // Store event types for later type generation
+    if (eventTypes?.length) {
+        streamEventTypes[streamTypeName] = eventTypes;
+    }
+    const eventTypesComment = eventTypes?.length
+        ? `\n   * Event types: ${eventTypes.map(t => `"${t}"`).join(', ')}`
+        : '';
+    const eventTypesExample = eventTypes?.length
+        ? eventTypes.map(t => `\n   *   .on('${t}', (data) => console.log(data))`).join('')
+        : '\n   *   .on(\'message\', (data) => console.log(data))';
+    const typeAnnotation = eventTypes?.length
+        ? `StreamController<${streamTypeName}>`
+        : 'StreamController';
+    const streamParams = allParams ? `${allParams}, options?: SSEStreamOptions` : `options?: SSEStreamOptions`;
+    const regularParams = allParams;
+    if (method === 'post') {
+        return `{
+  /**
+   * Stream SSE events from this endpoint (returns StreamController)${eventTypesComment}
+   * 
+   * @example
+   * const stream = api.endpoint.stream(params)${eventTypesExample}
+   *   .on('error', (err) => console.error(err))
+   *   .on('complete', () => console.log('Done!'))
+   * 
+   * // Close stream when needed
+   * stream.close()
+   */
+  stream: (${streamParams}): ${typeAnnotation} => {
+    return __transport.createSSEStreamPost<${streamTypeName}>(${formattedPath}, ${bodyVar}, options)
+  },
+  /**
+   * Regular POST request (non-streaming)
+   */
+  post: async (${regularParams}): Promise<AxiosResponse<any>> => {
+    return __transport.axios.post(${formattedPath}, ${bodyVar})
+  }
+}`;
+    }
+    else {
+        // Build query string construction for GET SSE streams
+        let queryStringCode = '';
+        if (queryParams?.length) {
+            // Generate URLSearchParams code to append query params to the SSE URL
+            // Query params use 'original_name': varName mapping format
+            const paramEntries = queryParams.map(p => {
+                const match = p.match(/^'([^']+)':\s*(.+)$/);
+                if (match)
+                    return { key: match[1], varName: match[2] };
+                // Simple case: param name is the same as var name
+                return { key: p, varName: p };
+            });
+            const conditions = paramEntries.map(({ key, varName }) => `if (${varName}) __qs.set('${key}', String(${varName}))`).join('\n    ');
+            queryStringCode = [
+                `const __qs = new URLSearchParams()`,
+                conditions,
+                `const __qsSuffix = __qs.size ? "?" + __qs.toString() : ""`,
+            ].join('\n    ');
+        }
+        const regularParamStr = queryParams?.length ? `, { params: {${queryParams.join(', ')}} }` : '';
+        // For GET streams with query params, build URL with suffix; otherwise plain URL
+        const urlLine = queryParams?.length
+            ? `const url = ${formattedPath} + __qsSuffix`
+            : `const url = ${formattedPath}`;
+        const streamBody = queryParams?.length
+            ? `\n    ${queryStringCode}\n    ${urlLine}`
+            : `\n    ${urlLine}`;
+        return `{
+  /**
+   * Stream SSE events from this endpoint (returns StreamController)${eventTypesComment}
+   * 
+   * @example
+   * const stream = api.endpoint.stream(params)${eventTypesExample}
+   *   .on('error', (err) => console.error(err))
+   *   .on('complete', () => console.log('Done!'))
+   * 
+   * // Close stream when needed
+   * stream.close()
+   */
+  stream: (${streamParams}): ${typeAnnotation} => {${streamBody}
+    return __transport.createSSEStream<${streamTypeName}>(url, options)
+  },
+  /**
+   * Regular GET request (non-streaming)
+   */
+  get: async (${regularParams}): Promise<AxiosResponse<any>> => {
+    return __transport.axios.get(${formattedPath}${regularParamStr})
+  }
+}`;
+    }
+}
+/**
+ * Generates an Axios function call as a string that returns ApiResponse
+ * @param method - The HTTP method
+ * @param formattedPath - The formatted API path
+ * @param allParams - The combined parameter string
+ * @param responseTypeStr - The response type string (will be converted to ApiResponse)
+ * @param parameters - Additional parameters
+ * @param requestBodyPayload - The request body payload
+ * @returns A string with the Axios function that returns ApiResponse
+ */
+function generateAxiosFunction(method, formattedPath, allParams, responseTypeStr, parameters, requestBodyPayload, isPrimitiveResponse) {
+    if (allParams === 'undefined') {
+        allParams = '';
+    }
+    // Convert AxiosResponse<T> to ApiResponse<T> in the return type
+    const apiResponseType = responseTypeStr.replace(/Promise<AxiosResponse<(.+)>>/, 'Promise<ApiResponse<$1>>');
+    let axiosFunction = `async (${allParams})${apiResponseType} => {`;
+    const returnExpression = isPrimitiveResponse
+        ? 'response.data'
+        : 'ApiResponse.create(response.data, response)';
+    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('file', file)
+		formData.append('upload', file)
+        const response = await __transport.axios.${method}(${formattedPath}, formData, {
+            headers: { 'Content-Type': 'multipart/form-data' },
+            onUploadProgress: options?.onUploadProgress${paramStr ? `, ${paramStr}` : ''}
+        })
+        return ${returnExpression}`;
+        }
+        else {
+            // Generic FormData handling
+            axiosFunction += `
+        const response = await __transport.axios.${method}(${formattedPath}, formData, {
+            headers: { 'Content-Type': 'multipart/form-data' }${paramStr ? `, ${paramStr}` : ''}
+        })
+        return ${returnExpression}`;
+        }
+    }
+    else {
+        const configParams = paramStr ? `, { ${paramStr} }` : '';
+        const bodyVar = requestBodyPayload || '{}';
+        axiosFunction += `
+        const response = await __transport.axios.${method}(${formattedPath}${['get', 'delete'].includes(method)
+            ? configParams
+            : `, ${bodyVar}${configParams}`})
+        return ${returnExpression}`;
+    }
+    axiosFunction += '}';
+    return axiosFunction;
+}
+/**
+ * Builds a JSDoc comment for an OpenAPI operation
+ * @param operation - The OpenAPI operation object
+ * @param method - The HTTP method
+ * @param path - The API path
+ * @returns The JSDoc comment as a string
+ */
+function buildJSDocComment(operation, method, path) {
+    let functionComment = '/**\n';
+    // Add summary
+    if (operation.summary) {
+        functionComment += ` * ${operation.summary}\n`;
+    }
+    // Add description if available
+    if (operation.description) {
+        // If there's already a summary, add a line break
+        if (operation.summary) {
+            functionComment += ` *\n`;
+        }
+        // Split description into lines and add each line with proper JSDoc formatting
+        const descriptionLines = operation.description.split('\n');
+        descriptionLines.forEach((line) => {
+            functionComment += ` * ${line}\n`;
+        });
+    }
+    // Add endpoint path and method information
+    functionComment += ` *\n * @endpoint ${method.toUpperCase()} ${path}\n`;
+    functionComment += ' */\n';
+    return functionComment;
+}
+/**
+ * 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, path, operation) {
+    if (!operation) {
+        return '';
+    }
+    // Check if this is an SSE stream endpoint
+    const isStream = isSSEStream(operation);
+    // Validate: GET and DELETE requests should not have request bodies
+    const methodLower = method.toLowerCase();
+    if (['get', 'delete'].includes(methodLower) && operation.requestBody) {
+        const requestBodyDeref = dereference(operation.requestBody);
+        const content = requestBodyDeref?.content;
+        // Check if request body has actual content with schemas
+        if (content && Object.keys(content).length > 0) {
+            // Check if any content type has a schema (indicating actual body data)
+            const hasSchema = Object.values(content).some(mediaType => mediaType && 'schema' in mediaType && mediaType.schema !== undefined && mediaType.schema !== null);
+            if (hasSchema) {
+                throw new Error(`Invalid OpenAPI spec: ${method.toUpperCase()} request at path "${path}" has a request body. `
+                    + `GET and DELETE requests should not have request bodies according to HTTP standards. `
+                    + `Please move the body parameters to query parameters or use a different HTTP method.`);
+            }
+        }
+    }
+    // Check if this is a file upload
+    const multiPartSchema = dereference(operation.requestBody)?.content?.['multipart/form-data']?.schema;
+    const isFileUpload = isReferenceObject(multiPartSchema) && multiPartSchema?.$ref?.includes('Body_upload_files');
+    const parameters = generateFunctionParameters(path, operation.parameters, isFileUpload);
+    const { requestBodyParam, requestBodyPayload } = generateRequestBody(operation.requestBody);
+    // Handle parameters appropriately based on operation type
+    const allParams = isFileUpload
+        ? 'file: File, options?: UploadOptions & { dirPath?: string, tags?: string[] }'
+        : combineAllParams(parameters, requestBodyParam);
+    const { type: responseType, isArray: isArrayResponse } = generateResponseType(operation.responses);
+    const isPrimitiveResponse = primitiveTypes.includes(responseType);
+    // For arrays: ApiResponse<T[]> (works as array, has metadata)
+    // For single objects: T (runtime adds metadata, but type is plain T for assignment)
+    // Note: At runtime, single objects have metadata but TypeScript sees plain type for better DX
+    const responseTypeStr = responseType
+        ? isArrayResponse
+            ? `: Promise<ApiResponse<${responseType}>>`
+            : `: Promise<${responseType}>`
+        : '';
+    // Create JSDoc comment with OpenAPI documentation
+    const functionComment = buildJSDocComment(operation, method, path);
+    // Generate stream function for SSE endpoints
+    if (isStream) {
+        const eventTypes = extractSSEEventTypes(operation);
+        const eventInfo = extractSSEEventInfo(operation);
+        const eventSchemas = extractSSEEventSchemas(operation);
+        // Store detailed event info and typed schemas for type generation
+        const streamTypeName = generateStreamTypeName(path);
+        if (eventInfo?.length) {
+            streamEventInfo[streamTypeName] = eventInfo;
+        }
+        if (eventSchemas && Object.keys(eventSchemas).length > 0) {
+            streamEventSchemas[streamTypeName] = eventSchemas;
+            // Collect schema type names for import statements
+            Object.values(eventSchemas).forEach(tsType => collectTypeForImportStatement(tsType));
+        }
+        // Extract query param mappings for GET SSE streams (e.g. "'run_id': _runId")
+        const queryParams = parameters.config?.params
+            ? parameters.config.params.split(',').map(p => p.trim()).filter(Boolean)
+            : undefined;
+        return functionComment + generateStreamFunction(method, path, formatPathWithParams(path), allParams, requestBodyPayload, eventTypes, queryParams);
+    }
+    return functionComment + generateAxiosFunction(method, formatPathWithParams(path), allParams, responseTypeStr, parameters, requestBodyPayload, isPrimitiveResponse);
+}
+/**
+ * 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, method) {
+    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;
+}
+/**
+ * Generates a random string for function IDs
+ * @returns A random string
+ */
+function generateRandomString() {
+    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, method, operation) {
+    const funcID = generateRandomString();
+    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, operation, existingObj = {}) {
+    const methods = Object.keys(operation);
+    const obj = {};
+    for (const method of methods) {
+        let functionName = method.toLowerCase();
+        if (hasConflict(path, method)) {
+            const params = getParamsFromPath(path);
+            functionName += params ? `By${toPascalCase(params.pop() || '')}` : 'All';
+        }
+        obj[functionName] = createFunctionPlaceholder(path, method, operation[method]);
+    }
+    return { ...obj, ...existingObj };
+}
+/**
+ * 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
+ */
+function generateFunctionsInternal(paths, baseUrl, moduleFactoryName) {
+    // Generation can run more than once in the same process (for example, one
+    // invocation per explicitly owned module). Keep each result independent.
+    allTypes.length = 0;
+    pathOperations.length = 0;
+    for (const inventory of [functionsInventory, streamEventTypes, streamEventInfo, streamEventSchemas]) {
+        for (const key of Object.keys(inventory))
+            delete inventory[key];
+    }
+    const body = {};
+    const allPathsClean = Object.keys(paths).map(cleanPath);
+    const httpMethods = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']);
+    // 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, index, array) => {
+            const objFuncKey = toCamelCaseSafe(key);
+            if (!objFuncKey) {
+                return acc;
+            }
+            const methods = Object.keys(operation)
+                .filter(method => httpMethods.has(method));
+            if (methods.length === 0)
+                return acc;
+            const currentPathClean = cleanPath(path);
+            const currentPathPrefix = splitPath.slice(0, index + 1).join('/');
+            // Check if any other path has this path as a prefix (indicating child paths exist)
+            const prefixWithSlash = `${currentPathPrefix}/`;
+            const hasChildPaths = allPathsClean.some(otherPath => otherPath !== currentPathClean && otherPath.startsWith(prefixWithSlash));
+            if (index === array.length - 1
+                && methods.length === 1
+                && allPathsClean.filter(p => p === currentPathClean).length === 1
+                && !hasChildPaths) {
+                // Single method endpoint with unique path and no child paths
+                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 or has child paths
+                // Ensure we have an object to merge with (handlePathSegment expects an object)
+                const existingValue = acc[objFuncKey];
+                const existingObj = (existingValue && typeof existingValue === 'object' && !Array.isArray(existingValue))
+                    ? existingValue
+                    : {};
+                acc[objFuncKey] = handlePathSegment(path, operation, existingObj);
+            }
+            else if (!acc[objFuncKey] || typeof acc[objFuncKey] !== 'object') {
+                // Intermediate path segment - ensure it's an object
+                // If it's already a function, we need to preserve it but this shouldn't happen
+                // if hasChildPaths check works correctly
+                acc[objFuncKey] = {};
+            }
+            return acc[objFuncKey];
+        }, body);
+    }
+    // Generate TypeScript code from processed paths
+    let tsString = 'function createEndpointNamespaces(__transport: ApiTransport) {\n';
+    const apiObjectEntries = [];
+    // Convert object structure to TypeScript
+    for (const [parent, object] of Object.entries(body)) {
+        tsString += `
+/**
+ * API functions for ${parent} endpoints
+ */
+const ${parent} = ${JSON.stringify(object, undefined, 2)};\n`;
+        apiObjectEntries.push(parent);
+    }
+    // Create aggregated api object
+    tsString += `
+/**
+ * Aggregated API object containing all endpoints
+ */
+const api = {
+${apiObjectEntries.map(name => `	${name},`).join('\n')}
+};
+return { api, ${apiObjectEntries.join(', ')} }
+}\n`;
+    // Replace placeholders with actual function bodies
+    Object.entries(functionsInventory).forEach(([key, value]) => {
+        tsString = tsString.replace(`"${key}"`, value);
+    });
+    // Generate the final TypeScript file
+    return moduleFactoryName
+        ? moduleFileTemplate(tsString, allTypes, moduleFactoryName)
+        : fileTemplate(tsString, allTypes, baseUrl, apiObjectEntries);
+}
+export function generateFunctions(paths, baseUrl) {
+    return generateFunctionsInternal(paths, baseUrl);
+}
+/** Generate a transport-bound module client without legacy singleton state. */
+export function generateModuleFunctions(paths, baseUrl, moduleFactoryName) {
+    return generateFunctionsInternal(paths, baseUrl, moduleFactoryName);
+}
+/**
+ * Generates TypeScript type definitions for stream events
+ * Uses detailed event info if available, falls back to simple event list
+ * @returns TypeScript type definitions string
+ */
+function generateStreamEventTypeDefinitions() {
+    if (Object.keys(streamEventTypes).length === 0) {
+        return '';
+    }
+    let typeDefs = '\n// ============================================================================\n';
+    typeDefs += '// Stream Event Type Definitions (Fully Typed!)\n';
+    typeDefs += '// ============================================================================\n\n';
+    for (const [typeName, events] of Object.entries(streamEventTypes)) {
+        const eventInfo = streamEventInfo[typeName];
+        const eventSchemas = streamEventSchemas[typeName]; // {event_name: "TSTypeName"} or undefined
+        typeDefs += `/**\n * Event types for ${typeName.replace('StreamEvents', '')} stream\n`;
+        typeDefs += ` * Events: ${events.map(e => `"${e}"`).join(', ')}\n`;
+        if (eventInfo?.length) {
+            typeDefs += ` *\n`;
+            for (const info of eventInfo) {
+                typeDefs += ` * - **${info.name}**: ${info.description || 'Event data'}\n`;
+            }
+        }
+        typeDefs += ` */\n`;
+        typeDefs += `export interface ${typeName} {\n`;
+        if (eventSchemas && Object.keys(eventSchemas).length > 0) {
+            // Fully typed: each event maps to its Pydantic model's TypeScript type
+            for (const event of events) {
+                const tsType = eventSchemas[event];
+                if (tsType) {
+                    typeDefs += `  /** ${event} event — payload shape defined by ${tsType} */\n`;
+                    typeDefs += `  ${event}: ${tsType}\n`;
+                }
+                else {
+                    typeDefs += `  /** ${event} event data */\n`;
+                    typeDefs += `  ${event}: any\n`;
+                }
+            }
+        }
+        else if (eventInfo?.length) {
+            // Field-level info from markdown docs but no schema refs
+            for (const info of eventInfo) {
+                typeDefs += `  /**\n   * ${info.description || info.name}\n`;
+                if (info.fields?.length) {
+                    info.fields.forEach(field => {
+                        typeDefs += `   * - \`${field.name}\`: ${field.description || 'Field data'}\n`;
+                    });
+                }
+                typeDefs += `   */\n`;
+                if (info.fields?.length) {
+                    typeDefs += `  ${info.name}: {\n`;
+                    for (const field of info.fields) {
+                        typeDefs += `    /** ${field.description || field.name} */\n`;
+                        typeDefs += `    ${field.name}: any\n`;
+                    }
+                    typeDefs += `  }\n`;
+                }
+                else {
+                    typeDefs += `  ${info.name}: any\n`;
+                }
+            }
+        }
+        else {
+            // Fallback: no type info at all
+            for (const event of events) {
+                typeDefs += `  /** ${event} event data */\n`;
+                typeDefs += `  ${event}: any\n`;
+            }
+        }
+        typeDefs += '}\n\n';
+    }
+    return typeDefs;
+}
+/**
+ * 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, typeForImport, baseURL, apiObjectEntries) {
+    const streamTypeDefs = generateStreamEventTypeDefinitions();
+    const hasStreamEndpoints = Object.keys(streamEventTypes).length > 0;
+    const streamImports = hasStreamEndpoints
+        ? `type StreamController, type SSEStreamOptions,`
+        : '';
+    const templateCode = `import type { AxiosResponse } from 'axios';
+import type { ${typeForImport.join(', ')} } from './types.d';
+import {
+	ApiResponse,
+	createApiTransport,
+	configureApiTransport,
+	parseApiError,
+	formatFieldErrors,
+	useApiRequest,
+	useCancellableRequest,
+	unwrap,
+	${streamImports}
+	type ApiConfig,
+	type ParsedError,
+	type FastAPIValidationError,
+	type FastAPIErrorResponse,
+	type ResponseMetadata,
+	type ApiRequestState,
+	type RequestInterceptor,
+	type ResponseInterceptor,
+	type ApiTransport,
+	type Unwrapped
+} from '@bagelink/sdk';
+import type { Ref } from 'vue';
+
+/**
+ * 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[]
+}
+
+${streamTypeDefs}
+
+const defaultTransport = createApiTransport({ baseURL: '${baseURL}' })
+
+${tsString}
+
+const defaultBindings = createEndpointNamespaces(defaultTransport)
+export const api = defaultBindings.api
+${apiObjectEntries.map(name => `export const ${name} = defaultBindings.${name}`).join('\n')}
+export const axios = defaultTransport.axios
+
+/** Bind all generated endpoint namespaces to an isolated transport. */
+export function createApiClient(transport: ApiTransport) {
+	return createEndpointNamespaces(transport)
+}
+
+/** Resolve the default client's SSE base URL. */
+export function getStreamBaseURL(): string {
+	return defaultTransport.getStreamBaseURL()
+}
+
+// ============================================================================
+// API Instance & Configuration
+// ============================================================================
+
+/**
+ * API instance type with enhanced response objects
+ */
+type ApiInstance = typeof api & {
+	$raw: typeof api
+	$lastResponse: Ref<AxiosResponse | null>
+	$axios: typeof axios
+	$ApiResponse: typeof ApiResponse
+	$config: Ref<ApiConfig | null>
+}
+
+// Global state
+let apiInstance: ApiInstance | null = null
+
+/**
+ * Create and configure the API instance
+ * @param config - API configuration options
+ * @returns Configured API instance
+ */
+export function createApi(config: ApiConfig = {}): ApiInstance {
+	configureApiTransport(defaultTransport, config)
+
+	// API already returns ApiResponse directly!
+	// Just add the special properties
+	apiInstance = {
+		...api,
+		$raw: api,
+		$lastResponse: defaultTransport.lastResponse,
+		$axios: axios,
+		$ApiResponse: ApiResponse,
+		$config: defaultTransport.config
+	} as ApiInstance
+
+	return apiInstance
+}
+
+/**
+ * Access the configured API instance
+ * @returns API instance with enhanced response objects
+ * @throws Error if createApi hasn't been called
+ */
+export function useApi(): ApiInstance {
+	if (!apiInstance) {
+		throw new Error(
+			'API not initialized. Call createApi() first.\\n\\n' +
+			'Example:\\n' +
+			'import { createApi } from \\'./generated/api\\'\\n' +
+			'createApi({ baseURL: \\'/api\\' })'
+		)
+	}
+	return apiInstance
+}
+
+// ============================================================================
+// Re-export utilities for convenience
+// ============================================================================
+
+export {
+	parseApiError,
+	formatFieldErrors,
+	useApiRequest,
+	useCancellableRequest,
+	unwrap,
+	ApiResponse,
+	type ApiConfig,
+	type ParsedError,
+	type ResponseMetadata,
+	type ApiRequestState,
+	type FastAPIValidationError,
+	type FastAPIErrorResponse,
+	type RequestInterceptor,
+	type ResponseInterceptor,
+	type Unwrapped
+}
+`;
+    // Remove potential double quotes around property names
+    return templateCode.replace(/"([^"]+)":/g, '$1:');
+}
+function moduleFileTemplate(tsString, typeForImport, moduleFactoryName) {
+    const streamTypeDefs = generateStreamEventTypeDefinitions();
+    const hasStreamEndpoints = Object.keys(streamEventTypes).length > 0;
+    const streamImports = hasStreamEndpoints
+        ? 'type StreamController, type SSEStreamOptions,'
+        : '';
+    const typeImport = typeForImport.length
+        ? `import type { ${typeForImport.join(', ')} } from './types.d';`
+        : '';
+    const templateCode = `${typeImport}
+import {
+\tApiResponse,
+\t${streamImports}
+\ttype ApiTransport
+} from '@bagelink/sdk';
+
+export interface UploadOptions {
+\tonUploadProgress?: (progressEvent: any) => void
+\tdirPath?: string
+\ttags?: string[]
+}
+
+${streamTypeDefs}
+
+${tsString}
+
+/** Bind this module's generated endpoint namespaces to the app transport. */
+export function ${moduleFactoryName}(transport: ApiTransport) {
+\treturn createEndpointNamespaces(transport)
+}
+`;
+    return templateCode.replace(/"([^"]+)":/g, '$1:');
+}