@aloma.io/integration-sdk 3.8.51 → 3.8.53

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aloma.io/integration-sdk",
-  "version": "3.8.51",
+  "version": "3.8.53",
   "description": "",
   "author": "aloma.io",
   "license": "Apache-2.0",

package/src/cli.mts

@@ -139,6 +139,12 @@ program
   .requiredOption('--connector-id <id>', 'id of the connector')
   .requiredOption('--spec <file>', 'OpenAPI specification file (JSON or YAML)')
   .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('--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');
@@ -156,9 +162,16 @@ program
       extract({...options, target, name});
 
       // Generate the controller from OpenAPI spec
-      console.log('Generating controller from OpenAPI specification...');
       const generator = new OpenAPIToConnector(spec, name);
-      const controllerCode = generator.generateController();
+      let controllerCode: string;
+
+      if (options.resource) {
+        console.log(`Generating resource class '${options.resource}' from OpenAPI specification...`);
+        controllerCode = generator.generateResourceClass(options.resource);
+      } else {
+        console.log('Generating controller from OpenAPI specification...');
+        controllerCode = generator.generateController();
+      }
 
       // Write the generated controller
       const controllerPath = `${target}/${options.out}`;
@@ -168,11 +181,28 @@ program
       console.log('Generating keys...');
       await generateKeys({target});
 
-      console.log('Installing dependencies...');
-      await exec(`cd ${target}; yarn --ignore-engines`);
+      if (options.build !== false) {
+        console.log('Installing dependencies...');
+        await exec(`cd ${target}; yarn --ignore-engines`);
 
-      console.log('Building...');
-      await exec(`cd ${target}; yarn build`);
+        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:
+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
@@ -180,11 +210,7 @@ program
 📊 Found ${generator.getOperationsCount()} operations
 📄 Controller generated: ${options.out}
       
-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`);
+${nextSteps}`);
     } catch (error) {
       console.error('❌ Error:', error instanceof Error ? error.message : 'Unknown error');
       // Clean up on error
@@ -221,4 +247,162 @@ class Extractor {
   }
 }
 
+// Multi-resource connector creation
+program
+  .command('create-multi-resource')
+  .description('Create a multi-resource connector project with multiple OpenAPI specifications')
+  .argument('<name>', 'name of the connector project')
+  .requiredOption('--connector-id <id>', 'id of the connector')
+  .requiredOption(
+    '--resources <specs>',
+    'comma-separated list of "className:specFile" pairs (e.g., "CompaniesResource:companies.json,ContactsResource:contacts.json")'
+  )
+  .option('--base-url <url>', 'base URL for the API (if not specified, will be extracted from first OpenAPI spec)')
+  .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 {
+      // Parse resources specification
+      const resourceSpecs = options.resources.split(',').map((spec) => {
+        const [className, specFile] = spec.split(':');
+        if (!className || !specFile) {
+          throw new Error(`Invalid resource specification: ${spec}. Expected format: "ClassName:specFile"`);
+        }
+        return {className: className.trim(), specFile: specFile.trim()};
+      });
+
+      console.log(`Creating multi-resource connector '${name}' with ${resourceSpecs.length} resources...`);
+
+      // Create the connector project structure
+      fs.mkdirSync(target);
+      extract({...options, target, name});
+
+      // Generate each resource
+      const resources: Array<{className: string; fileName: string}> = [];
+      let baseUrl = options.baseUrl;
+
+      for (const {className, specFile} of resourceSpecs) {
+        console.log(`Generating ${className} from ${specFile}...`);
+
+        // Read and parse the OpenAPI spec
+        const specContent = fs.readFileSync(specFile, 'utf-8');
+        const spec = OpenAPIToConnector.parseSpec(specContent);
+
+        // Extract base URL from first spec if not provided
+        if (!baseUrl && spec.servers && spec.servers.length > 0) {
+          baseUrl = spec.servers[0].url;
+        }
+
+        // Generate the resource class
+        const generator = new OpenAPIToConnector(spec, name);
+        const resourceCode = generator.generateResourceClass(className);
+
+        // Write the resource file
+        const fileName = className.toLowerCase().replace('resource', '');
+        const resourcePath = `${target}/src/resources/${fileName}.mts`;
+        fs.mkdirSync(path.dirname(resourcePath), {recursive: true});
+        fs.writeFileSync(resourcePath, resourceCode);
+
+        resources.push({className, fileName});
+      }
+
+      // 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);
+
+      // Write the main controller
+      const controllerPath = `${target}/src/controller/index.mts`;
+      fs.writeFileSync(controllerPath, mainControllerCode);
+
+      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.) Start the connector with cd ./${name}/; yarn start`
+          : `Next steps:
+1.) Install dependencies: cd ./${name}/ && yarn --ignore-engines
+2.) Build the project: yarn build
+3.) Add the connector to a workspace
+4.) Edit ./${name}/.env and insert the registration token
+5.) Start the connector with yarn start`;
+
+      console.log(`\n✅ Multi-resource connector created successfully!
+      
+Generated resources:
+${resources.map((r) => `- ${r.className} (${r.fileName}.mts)`).join('\n')}
+
+Main controller: src/controller/index.mts
+${nextSteps}`);
+    } catch (error) {
+      console.error('Error creating multi-resource connector:', (error as Error).message);
+      process.exit(1);
+    }
+  });
+
+// Add resource to existing project
+program
+  .command('add-resource')
+  .description('Add a new resource to an existing multi-resource connector')
+  .argument('<projectPath>', 'path to the existing connector project')
+  .requiredOption('--className <name>', 'class name for the resource (e.g., DealsResource)')
+  .requiredOption('--spec <file>', 'OpenAPI specification file for the new resource')
+  .option('--no-build', 'Skip building the project after adding the resource')
+  .action(async (projectPath, options) => {
+    const target = path.resolve(projectPath);
+
+    if (!fs.existsSync(target)) {
+      throw new Error(`Project path does not exist: ${target}`);
+    }
+
+    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
+      const generator = new OpenAPIToConnector(spec, 'Resource');
+      const resourceCode = generator.generateResourceClass(options.className);
+
+      // Write the resource file
+      const fileName = options.className.toLowerCase().replace('resource', '');
+      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);`);
+
+      if (options.build !== false) {
+        console.log('\nBuilding project...');
+        await exec(`cd "${target}"; yarn build`);
+      }
+    } catch (error) {
+      console.error('Error adding resource:', (error as Error).message);
+      process.exit(1);
+    }
+  });
+
 program.parse();

package/src/openapi-to-connector.mts

@@ -122,7 +122,30 @@ export class OpenAPIToConnector {
    */
   private generateMethodName(operation: OperationInfo): string {
     if (operation.operationId) {
-      return this.toValidIdentifier(operation.operationId);
+      // Clean up HubSpot-style operationIds like "get-/crm/v3/objects/companies_getPage"
+      let cleaned = operation.operationId;
+
+      // Extract the last part after underscore if it exists
+      const parts = cleaned.split('_');
+      if (parts.length > 1) {
+        const lastPart = parts[parts.length - 1];
+        // If the last part looks like a method name (camelCase), use it
+        if (lastPart && /^[a-z][a-zA-Z0-9]*$/.test(lastPart)) {
+          cleaned = lastPart;
+        }
+      }
+
+      // Remove any remaining special characters and clean up
+      cleaned = cleaned
+        .replace(/^(get|post|put|patch|delete|head|options)-/i, '') // Remove HTTP method prefix
+        .replace(/[^a-zA-Z0-9_]/g, '_')
+        .replace(/_+/g, '_')
+        .replace(/^_|_$/g, '');
+
+      // If we still have a valid identifier, use it
+      if (cleaned && /^[a-zA-Z]/.test(cleaned)) {
+        return cleaned;
+      }
     }
 
     // Generate from method + path
@@ -143,31 +166,85 @@ export class OpenAPIToConnector {
    */
   private generateJSDoc(operation: OperationInfo): string {
     const lines: string[] = [];
+    const pathParams: any[] = [];
+    const queryParams: any[] = [];
+    const hasBody = !!operation.requestBody;
 
     if (operation.summary) {
       lines.push(` * ${operation.summary}`);
     }
 
     if (operation.description) {
-      lines.push(` * ${operation.description}`);
+      lines.push(` *`);
+      // Split long descriptions into multiple lines
+      const descLines = operation.description.split('\n');
+      descLines.forEach((line) => {
+        if (line.trim()) {
+          lines.push(` * ${line.trim()}`);
+        }
+      });
     }
 
-    if (operation.parameters && operation.parameters.length > 0) {
-      lines.push(' *');
-      lines.push(' * @param args - Request arguments');
+    // Identify path and query parameters
+    if (operation.parameters) {
       for (const param of operation.parameters) {
-        if (typeof param === 'object' && 'name' in param && 'description' in param) {
-          lines.push(` * @param args.${param.name} - ${param.description || 'Parameter'}`);
+        if (typeof param === 'object' && 'name' in param && 'in' in param) {
+          if (param.in === 'path') {
+            pathParams.push(param);
+          } else if (param.in === 'query') {
+            queryParams.push(param);
+          }
         }
       }
     }
 
-    if (operation.requestBody) {
+    // Check if using simple signature
+    const useSimpleSignature = queryParams.length === 0 && !hasBody && pathParams.length <= 1;
+
+    if (useSimpleSignature && pathParams.length === 1) {
+      // Simple signature documentation
+      const param = pathParams[0];
+      const paramType = param.schema?.type || 'string';
+      const paramDesc = param.description || '';
+      lines.push(' *');
+      lines.push(` * @param {${paramType}} ${param.name} ${paramDesc}`);
+      lines.push(` * @param {Object} options (optional) - Request options`);
+      lines.push(` * @param {Object} options.headers - Custom headers`);
+    } else {
+      // Options object documentation
       lines.push(' *');
-      lines.push(' * @param args.body - Request body');
+      lines.push(` * @param {Object} options (optional) - Request options`);
+
+      // Document path parameters
+      for (const param of pathParams) {
+        const paramType = param.schema?.type || 'string';
+        const paramDesc = param.description || '';
+        const paramRequired = param.required ? '(required)' : '(optional)';
+        lines.push(` * @param {${paramType}} options.${param.name} ${paramRequired} - ${paramDesc} [path]`);
+      }
+
+      // Document query parameters
+      for (const param of queryParams) {
+        const paramType = param.schema?.type || 'any';
+        const paramDesc = param.description || '';
+        const paramRequired = param.required ? '(required)' : '(optional)';
+        lines.push(` * @param {${paramType}} options.${param.name} ${paramRequired} - ${paramDesc} [query]`);
+      }
+
+      // Document request body
+      if (operation.requestBody) {
+        const bodyDesc = operation.requestBody.description || 'Request body';
+        const required = operation.requestBody.required ? '(required)' : '(optional)';
+        lines.push(` * @param {Object} options.body ${required} - ${bodyDesc}`);
+      }
+
+      // Document headers
+      lines.push(` * @param {Object} options.headers (optional) - Custom headers to include in the request`);
     }
 
-    lines.push(' * @returns Response data');
+    // Document response
+    lines.push(' *');
+    lines.push(` * @returns {Promise<Object>} ${operation.method} ${operation.path} response`);
 
     return lines.join('\n');
   }
@@ -179,6 +256,233 @@ export class OpenAPIToConnector {
     return this.extractOperations().length;
   }
 
+  /**
+   * Generate method signature with options object
+   */
+  private generateMethodSignature(operation: OperationInfo): string {
+    const pathParams: string[] = [];
+    const queryParams: string[] = [];
+    const hasBody = !!operation.requestBody;
+
+    // Identify path and query parameters
+    if (operation.parameters) {
+      for (const param of operation.parameters) {
+        if (typeof param === 'object' && 'name' in param && 'in' in param) {
+          if (param.in === 'path') {
+            pathParams.push(param.name);
+          } else if (param.in === 'query') {
+            queryParams.push(param.name);
+          }
+        }
+      }
+    }
+
+    // If there are no query params, no body, and only path params, use simple signature
+    if (queryParams.length === 0 && !hasBody && pathParams.length <= 1) {
+      const params: string[] = [];
+      for (const paramName of pathParams) {
+        params.push(`${paramName}: string`);
+      }
+      params.push(`options?: {headers?: {[key: string]: any}}`);
+      return `(${params.join(', ')})`;
+    }
+
+    // Otherwise, use options object pattern
+    return `(options?: {${[
+      ...pathParams.map((p) => `${p}?: string`),
+      ...queryParams.map((p) => `${p}?: any`),
+      hasBody ? 'body?: any' : '',
+      'headers?: {[key: string]: any}',
+    ]
+      .filter(Boolean)
+      .join(', ')}})`;
+  }
+
+  /**
+   * Generate method implementation code
+   */
+  private generateMethodImplementation(operation: OperationInfo): string {
+    const lines: string[] = [];
+
+    // Build URL with path parameters
+    let url = operation.path;
+    const pathParams: string[] = [];
+    const queryParams: string[] = [];
+    const hasBody = !!operation.requestBody;
+
+    // Identify path and query parameters
+    if (operation.parameters) {
+      for (const param of operation.parameters) {
+        if (typeof param === 'object' && 'name' in param && 'in' in param) {
+          if (param.in === 'path') {
+            pathParams.push(param.name);
+          } else if (param.in === 'query') {
+            queryParams.push(param.name);
+          }
+        }
+      }
+    }
+
+    // Check if using simple signature (single path param, no query/body)
+    const useSimpleSignature = queryParams.length === 0 && !hasBody && pathParams.length <= 1;
+
+    if (useSimpleSignature && pathParams.length === 1) {
+      // Simple signature: (pathParam: string, options?: {headers?: ...})
+      const paramName = pathParams[0];
+      lines.push(`    let url = '${url}';`);
+      lines.push(`    if (${paramName}) {`);
+      lines.push(`      url = url.replace('{${paramName}}', ${paramName});`);
+      lines.push(`    }`);
+      lines.push('');
+      lines.push(`    return this.api.fetch(url, {`);
+      lines.push(`      method: '${operation.method}',`);
+      lines.push(`      headers: options?.headers,`);
+      lines.push(`    });`);
+    } else {
+      // Options object pattern
+      lines.push(`    options = options || {};`);
+      lines.push('');
+
+      // Replace path parameters
+      if (pathParams.length > 0) {
+        lines.push(`    // Build URL with path parameters`);
+        lines.push(`    let url = '${url}';`);
+        for (const paramName of pathParams) {
+          lines.push(`    if (options.${paramName}) {`);
+          lines.push(`      url = url.replace('{${paramName}}', options.${paramName});`);
+          lines.push(`    }`);
+        }
+        lines.push('');
+      } else {
+        lines.push(`    const url = '${url}';`);
+        lines.push('');
+      }
+
+      // Build fetch options
+      lines.push(`    const fetchOptions: any = {`);
+      lines.push(`      method: '${operation.method}',`);
+
+      // Add query parameters
+      if (queryParams.length > 0) {
+        lines.push(`      params: {},`);
+      }
+
+      // Add body if present
+      if (hasBody) {
+        lines.push(`      body: options.body,`);
+      }
+
+      // Add headers if present
+      lines.push(`      headers: options.headers,`);
+
+      lines.push(`    };`);
+      lines.push('');
+
+      // Add query parameters to options
+      if (queryParams.length > 0) {
+        lines.push(`    // Add query parameters`);
+        for (const paramName of queryParams) {
+          lines.push(`    if (options.${paramName} !== undefined) {`);
+          lines.push(`      fetchOptions.params.${paramName} = options.${paramName};`);
+          lines.push(`    }`);
+        }
+        lines.push('');
+      }
+
+      // Make the API call
+      lines.push(`    return this.api.fetch(url, fetchOptions);`);
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Generate proper import paths with .mjs extensions for TypeScript module resolution
+   */
+  private generateImportPath(relativePath: string): string {
+    // For resource classes, we need to reference the compiled .mjs files
+    return relativePath.endsWith('.mjs') ? relativePath : `${relativePath}.mjs`;
+  }
+
+  /**
+   * Generate a resource class (does NOT extend AbstractController, receives controller reference)
+   */
+  generateResourceClass(className: string): string {
+    const operations = this.extractOperations();
+
+    if (operations.length === 0) {
+      throw new Error('No operations found in OpenAPI specification');
+    }
+
+    const methods = operations
+      .map((operation) => {
+        const methodName = this.generateMethodName(operation);
+        const jsdoc = this.generateJSDoc(operation);
+        const signature = this.generateMethodSignature(operation);
+        const implementation = this.generateMethodImplementation(operation);
+
+        return `  /**\n${jsdoc}\n   */\n  async ${methodName}${signature} {\n${implementation}\n  }`;
+      })
+      .join('\n\n');
+
+    return `import {AbstractController} from '@aloma.io/integration-sdk';
+
+export default class ${className} {
+  private controller: AbstractController;
+
+  constructor(controller: AbstractController) {
+    this.controller = controller;
+  }
+
+  private get api() {
+    return this.controller['api'];
+  }
+
+${methods}
+}`;
+  }
+
+  /**
+   * Generate a main controller that composes multiple resources
+   */
+  generateMainController(resources: Array<{className: string; fileName: string}>): string {
+    // Get base URL from servers if available
+    const baseUrl = this.spec.servers && this.spec.servers.length > 0 ? this.spec.servers[0].url : 'API_BASE_URL';
+
+    const imports = resources
+      .map((resource) => `import ${resource.className} from '../resources/${resource.fileName}.mjs';`)
+      .join('\n');
+
+    const properties = resources
+      .map((resource) => `  ${resource.className.toLowerCase().replace('resource', '')}!: ${resource.className};`)
+      .join('\n');
+
+    const initializations = resources
+      .map(
+        (resource) =>
+          `    this.${resource.className.toLowerCase().replace('resource', '')} = new ${resource.className}(this);`
+      )
+      .join('\n');
+
+    return `import {AbstractController} from '@aloma.io/integration-sdk';
+${imports}
+
+export default class Controller extends AbstractController {
+${properties}
+
+  private api: any;
+
+  protected async start(): Promise<void> {
+    this.api = this.getClient({
+      baseUrl: '${baseUrl}',
+    });
+    
+    // Initialize each resource - they receive 'this' controller reference
+${initializations}
+  }
+}`;
+  }
+
   /**
    * Generate the connector controller code
    */
@@ -193,15 +497,30 @@ export class OpenAPIToConnector {
       .map((operation) => {
         const methodName = this.generateMethodName(operation);
         const jsdoc = this.generateJSDoc(operation);
+        const signature = this.generateMethodSignature(operation);
+        const implementation = this.generateMethodImplementation(operation);
 
-        return `  /**\n${jsdoc}\n   */\n  async ${methodName}(args: any) {\n    // TODO: Implement ${operation.method} ${operation.path}\n    throw new Error('Method not implemented');\n  }`;
+        return `  /**\n${jsdoc}\n   */\n  async ${methodName}${signature} {\n${implementation}\n  }`;
       })
       .join('\n\n');
 
+    // Get base URL from servers if available
+    const baseUrl = this.spec.servers && this.spec.servers.length > 0 ? this.spec.servers[0].url : 'API_BASE_URL';
+
+    const startMethod = `  private api: any;
+
+  protected async start(): Promise<void> {
+    this.api = this.getClient({
+      baseUrl: '${baseUrl}',
+    });
+  }`;
+
     return `import {AbstractController} from '@aloma.io/integration-sdk';
 
 export default class Controller extends AbstractController {
   
+${startMethod}
+
 ${methods}
 }`;
   }