@aloma.io/integration-sdk 3.8.55 → 3.8.56

package/build/cli.mjs

@@ -111,20 +111,16 @@ program
     .option('--out <file>', 'output file path for the controller', 'src/controller/index.mts')
     .option('--resource <className>', 'Generate as a resource class with the specified class name (e.g., CompaniesResource)')
     .option('--multi-resource', 'Generate multiple resource files + main controller (requires multiple --spec files)')
+    .option('--controller-only', 'Generate only the controller file, do not create full project structure')
     .option('--no-build', 'Skip installing dependencies and building the project')
     .action(async (name, options) => {
     name = name.replace(/[\/\.]/gi, '');
     if (!name)
         throw new Error('name is empty');
-    const target = `${process.cwd()}/${name}`;
     try {
         // Read and parse the OpenAPI spec
         const specContent = fs.readFileSync(options.spec, 'utf-8');
         const spec = OpenAPIToConnector.parseSpec(specContent);
-        // Create the connector project structure
-        fs.mkdirSync(target);
-        console.log('Creating connector project...');
-        extract({ ...options, target, name });
         // Generate the controller from OpenAPI spec
         const generator = new OpenAPIToConnector(spec, name);
         let controllerCode;
@@ -136,44 +132,66 @@ program
             console.log('Generating controller from OpenAPI specification...');
             controllerCode = generator.generateController();
         }
-        // Write the generated controller
-        const controllerPath = `${target}/${options.out}`;
-        fs.mkdirSync(path.dirname(controllerPath), { recursive: true });
-        fs.writeFileSync(controllerPath, controllerCode);
-        console.log('Generating keys...');
-        await generateKeys({ target });
-        if (options.build !== false) {
-            console.log('Installing dependencies...');
-            await exec(`cd ${target}; yarn --ignore-engines`);
-            console.log('Building...');
-            await exec(`cd ${target}; yarn build`);
+        if (options.controllerOnly) {
+            // Controller-only mode: just generate the controller file
+            const controllerPath = path.resolve(options.out);
+            fs.mkdirSync(path.dirname(controllerPath), { recursive: true });
+            fs.writeFileSync(controllerPath, controllerCode);
+            console.log(`\n✅ Success! Generated controller from OpenAPI specification
+📝 Connector name: ${name}
+📊 Found ${generator.getOperationsCount()} operations
+📄 Controller file: ${controllerPath}
+      
+Controller file generated successfully! You can now use it in your existing project.`);
         }
-        const nextSteps = options.build !== false
-            ? `Next steps:
+        else {
+            // Full project mode: create complete project structure
+            const target = `${process.cwd()}/${name}`;
+            // Create the connector project structure
+            fs.mkdirSync(target);
+            console.log('Creating connector project...');
+            extract({ ...options, target, name });
+            // Write the generated controller
+            const controllerPath = `${target}/${options.out}`;
+            fs.mkdirSync(path.dirname(controllerPath), { recursive: true });
+            fs.writeFileSync(controllerPath, controllerCode);
+            console.log('Generating keys...');
+            await generateKeys({ target });
+            if (options.build !== false) {
+                console.log('Installing dependencies...');
+                await exec(`cd ${target}; yarn --ignore-engines`);
+                console.log('Building...');
+                await exec(`cd ${target}; yarn build`);
+            }
+            const nextSteps = options.build !== false
+                ? `Next steps:
 1.) Add the connector to a workspace
 2.) Edit ./${name}/.env and insert the registration token
 3.) Implement the actual API calls in each method in ${options.out}
 4.) Start the connector with cd ./${name}/; yarn start`
-            : `Next steps:
+                : `Next steps:
 1.) Install dependencies: cd ./${name}/ && yarn --ignore-engines
 2.) Implement the actual API calls in each method in ${options.out}
 3.) Build the project: yarn build
 4.) Add the connector to a workspace
 5.) Edit ./${name}/.env and insert the registration token
 6.) Start the connector: yarn start`;
-        console.log(`
-✅ Success! Generated connector from OpenAPI specification
+            console.log(`\n✅ Success! Generated connector from OpenAPI specification
 📝 Connector name: ${name}
 📊 Found ${generator.getOperationsCount()} operations
 📄 Controller generated: ${options.out}
       
 ${nextSteps}`);
+        }
     }
     catch (error) {
         console.error('❌ Error:', error instanceof Error ? error.message : 'Unknown error');
-        // Clean up on error
-        if (fs.existsSync(target)) {
-            fs.rmSync(target, { recursive: true, force: true });
+        // Clean up on error (only if we created a project directory)
+        if (!options.controllerOnly) {
+            const target = `${process.cwd()}/${name}`;
+            if (fs.existsSync(target)) {
+                fs.rmSync(target, { recursive: true, force: true });
+            }
         }
         process.exit(1);
     }
@@ -223,6 +241,7 @@ program
         extract({ ...options, target, name });
         // Generate each resource
         const resources = [];
+        const parsedResourceSpecs = [];
         let baseUrl = options.baseUrl;
         for (const { className, specFile } of resourceSpecs) {
             console.log(`Generating ${className} from ${specFile}...`);
@@ -242,12 +261,13 @@ program
             fs.mkdirSync(path.dirname(resourcePath), { recursive: true });
             fs.writeFileSync(resourcePath, resourceCode);
             resources.push({ className, fileName });
+            parsedResourceSpecs.push({ fileName, spec });
         }
         // Generate the main controller
         console.log('Generating main controller...');
         const firstSpec = OpenAPIToConnector.parseSpec(fs.readFileSync(resourceSpecs[0].specFile, 'utf-8'));
         const mainGenerator = new OpenAPIToConnector(firstSpec, name);
-        const mainControllerCode = mainGenerator.generateMainController(resources);
+        const mainControllerCode = mainGenerator.generateMainController(resources, parsedResourceSpecs);
         // Write the main controller
         const controllerPath = `${target}/src/controller/index.mts`;
         fs.writeFileSync(controllerPath, mainControllerCode);
@@ -296,12 +316,16 @@ program
     if (!fs.existsSync(target)) {
         throw new Error(`Project path does not exist: ${target}`);
     }
+    const controllerPath = `${target}/src/controller/index.mts`;
+    if (!fs.existsSync(controllerPath)) {
+        throw new Error(`Controller file not found: ${controllerPath}. This might not be a multi-resource connector project.`);
+    }
     try {
         console.log(`Adding ${options.className} resource to existing project...`);
         // Read and parse the OpenAPI spec
         const specContent = fs.readFileSync(options.spec, 'utf-8');
         const spec = OpenAPIToConnector.parseSpec(specContent);
-        // Generate the resource class
+        // Generate the resource functions file (new function-based pattern)
         const generator = new OpenAPIToConnector(spec, 'Resource');
         const resourceCode = generator.generateResourceClass(options.className);
         // Write the resource file
@@ -309,18 +333,83 @@ program
         const resourcePath = `${target}/src/resources/${fileName}.mts`;
         fs.mkdirSync(path.dirname(resourcePath), { recursive: true });
         fs.writeFileSync(resourcePath, resourceCode);
-        console.log(`✅ Resource ${options.className} added successfully at ${resourcePath}`);
-        console.log('\n⚠️  You need to manually update the main controller to include this new resource:');
-        console.log(`1.) Add import: import ${options.className} from '../resources/${fileName}.mjs';`);
-        console.log(`2.) Add property: ${fileName}!: ${options.className};`);
-        console.log(`3.) Add initialization in start(): this.${fileName} = new ${options.className}(this);`);
+        // Update the main controller to include the new resource
+        console.log('Updating main controller...');
+        let controllerContent = fs.readFileSync(controllerPath, 'utf-8');
+        // Add import
+        const importStatement = `import * as ${fileName}Functions from '../resources/${fileName}.mjs';`;
+        if (!controllerContent.includes(importStatement)) {
+            // Find the last import and add after it
+            const importRegex = /^import.*from.*?;$/gm;
+            const imports = controllerContent.match(importRegex);
+            if (imports && imports.length > 0) {
+                const lastImport = imports[imports.length - 1];
+                controllerContent = controllerContent.replace(lastImport, `${lastImport}\n${importStatement}`);
+            }
+            else {
+                // If no imports found, add at the beginning
+                controllerContent = `${importStatement}\n\n${controllerContent}`;
+            }
+        }
+        // Add property declaration
+        const propertyDeclaration = `  ${fileName}: any = {};`;
+        if (!controllerContent.includes(propertyDeclaration)) {
+            // Find the existing properties and add the new one
+            const propertyRegex = /^  \w+: any = \{\};$/gm;
+            const properties = controllerContent.match(propertyRegex);
+            if (properties && properties.length > 0) {
+                const lastProperty = properties[properties.length - 1];
+                controllerContent = controllerContent.replace(lastProperty, `${lastProperty}\n${propertyDeclaration}`);
+            }
+            else {
+                // Add after class declaration
+                controllerContent = controllerContent.replace(/^export default class Controller extends AbstractController \{$/gm, `export default class Controller extends AbstractController {\n${propertyDeclaration}`);
+            }
+        }
+        // Add binding in start() method
+        const bindingStatement = `    this.bindResourceFunctions('${fileName}', ${fileName}Functions);`;
+        if (!controllerContent.includes(bindingStatement)) {
+            // Find the existing bindings and add the new one
+            const bindingRegex = /^    this\.bindResourceFunctions\(.*?\);$/gm;
+            const bindings = controllerContent.match(bindingRegex);
+            if (bindings && bindings.length > 0) {
+                const lastBinding = bindings[bindings.length - 1];
+                controllerContent = controllerContent.replace(lastBinding, `${lastBinding}\n${bindingStatement}`);
+            }
+        }
+        // Write the updated controller
+        fs.writeFileSync(controllerPath, controllerContent);
+        // Generate exposed methods for the new resource
+        console.log('Generating exposed methods for the new resource...');
+        const resources = [{ className: options.className, fileName }];
+        const resourceSpecs = [{ fileName, spec }];
+        // Create a temporary generator to generate just the exposed methods for this resource
+        const tempGenerator = new OpenAPIToConnector(spec, 'temp');
+        const exposedMethods = tempGenerator.generateExposedResourceMethods(resources, resourceSpecs);
+        // Add the exposed methods to the controller before the closing brace
+        if (exposedMethods.trim()) {
+            controllerContent = fs.readFileSync(controllerPath, 'utf-8');
+            // Find the last method and add the new exposed methods
+            const lastBrace = controllerContent.lastIndexOf('}');
+            if (lastBrace !== -1) {
+                const beforeBrace = controllerContent.substring(0, lastBrace);
+                const afterBrace = controllerContent.substring(lastBrace);
+                const updatedContent = `${beforeBrace}\n${exposedMethods}\n${afterBrace}`;
+                fs.writeFileSync(controllerPath, updatedContent);
+            }
+        }
+        console.log(`✅ Resource ${options.className} added successfully!`);
+        console.log(`📄 Resource functions: ${resourcePath}`);
+        console.log(`🎛️  Controller updated: ${controllerPath}`);
+        console.log(`\n🎉 The new resource is fully integrated and ready to use!`);
         if (options.build !== false) {
-            console.log('\nBuilding project...');
+            console.log('\n🔨 Building project...');
             await exec(`cd "${target}"; yarn build`);
+            console.log('✅ Build complete!');
         }
     }
     catch (error) {
-        console.error('Error adding resource:', error.message);
+        console.error('❌ Error adding resource:', error.message);
         process.exit(1);
     }
 });

package/build/openapi-to-connector.d.mts

@@ -20,10 +20,6 @@ export declare class OpenAPIToConnector {
      * Generate method name from operation info
      */
     private generateMethodName;
-    /**
-     * Generate JSDoc comment for an operation
-     */
-    private generateJSDoc;
     /**
      * Get the number of operations in the OpenAPI spec
      */
@@ -32,31 +28,112 @@ export declare class OpenAPIToConnector {
      * Generate method signature with options object
      */
     private generateMethodSignature;
+    /**
+     * Resolve a schema reference to a TypeScript type name
+     */
+    private resolveSchemaRef;
+    /**
+     * Sanitize a name to be a valid TypeScript identifier
+     */
+    private sanitizeTypeName;
+    /**
+     * Get TypeScript type from schema object
+     */
+    private getTypeFromSchema;
+    /**
+     * Get TypeScript type for request body
+     */
+    private getRequestBodyType;
+    /**
+     * Add request body properties directly to options array (flatten the body)
+     */
+    private addRequestBodyProperties;
+    /**
+     * Get TypeScript type for response
+     */
+    private getResponseType;
     /**
      * Get TypeScript type for a parameter based on its schema
      */
     private getParameterType;
     /**
-     * Generate method implementation code
+     * Generate method implementation code for controller methods with discrete path parameters
      */
-    private generateMethodImplementation;
+    private generateControllerMethodImplementation;
+    /**
+     * Generate method implementation for resource functions (using this.api instead of this.controller)
+     */
+    private generateResourceFunctionImplementation;
+    /**
+     * Generate exposed resource methods for API introspection
+     */
+    generateExposedResourceMethods(resources: Array<{
+        className: string;
+        fileName: string;
+    }>, resourceSpecs?: Array<{
+        fileName: string;
+        spec: OpenAPIV3.Document;
+    }>): string;
     /**
-     * Generate proper import paths with .mjs extensions for TypeScript module resolution
+     * Generate parameter call for a specific operation based on path parameters
      */
-    private generateImportPath;
+    private generateParameterCallForOperation;
     /**
-     * Generate a resource class (does NOT extend AbstractController, receives controller reference)
+     * Generate TypeScript interface from OpenAPI schema
+     */
+    private generateInterfaceFromSchema;
+    /**
+     * Generate all TypeScript interfaces from OpenAPI components
+     */
+    private generateAllInterfaces;
+    /**
+     * Generate detailed JSDoc with schema field information
+     */
+    private generateDetailedJSDoc;
+    /**
+     * Add flattened request body documentation to JSDoc
+     */
+    private addFlattenedBodyDocumentation;
+    /**
+     * Add detailed schema field information to JSDoc
+     */
+    private addSchemaDetails;
+    /**
+     * Collect all schema types used in operations (including nested references)
+     */
+    private collectUsedSchemaTypes;
+    /**
+     * Collect types from request body schema
+     */
+    private collectTypesFromRequestBody;
+    /**
+     * Collect types from response schemas
+     */
+    private collectTypesFromResponses;
+    /**
+     * Collect types from a schema object
+     */
+    private collectTypesFromSchema;
+    /**
+     * Generate type imports for used schema types
+     */
+    private generateTypeImports;
+    /**
+     * Generate a resource file with exported functions (new pattern for proper introspection)
      */
     generateResourceClass(className: string): string;
     /**
-     * Generate a main controller that composes multiple resources
+     * Generate a main controller that composes multiple resources using function binding
      */
     generateMainController(resources: Array<{
         className: string;
         fileName: string;
+    }>, resourceSpecs?: Array<{
+        fileName: string;
+        spec: OpenAPIV3.Document;
     }>): string;
     /**
-     * Generate the connector controller code
+     * Generate the connector controller code with improved pattern
      */
     generateController(): string;
 }