@aloma.io/integration-sdk 3.8.52 → 3.8.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aloma.io/integration-sdk",
-  "version": "3.8.52",
+  "version": "3.8.54",
   "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

@@ -65,11 +65,23 @@ export class OpenAPIToConnector {
       }
     }
 
-    // Validate against OpenAPI 3.x schema
+    // Validate against OpenAPI 3.x schema with lenient validation
     const validationResult = OpenAPISchema.safeParse(parsed);
     if (!validationResult.success) {
-      const errors = validationResult.error.errors.map((err) => `${err.path.join('.')}: ${err.message}`).join(', ');
-      throw new Error(`Invalid OpenAPI 3.x specification: ${errors}`);
+      // Check if the errors are just about missing 'type' fields in schemas
+      const criticalErrors = validationResult.error.errors.filter((err) => {
+        const path = err.path.join('.');
+        // Allow missing 'type' in schema definitions as many OpenAPI specs don't include it
+        return !path.includes('components.schemas') || !err.message.includes('Required');
+      });
+
+      if (criticalErrors.length > 0) {
+        const errors = criticalErrors.map((err) => `${err.path.join('.')}: ${err.message}`).join(', ');
+        throw new Error(`Invalid OpenAPI 3.x specification: ${errors}`);
+      }
+
+      // Log a warning about lenient validation
+      console.warn('⚠️  OpenAPI spec has some validation warnings but proceeding with lenient validation...');
     }
 
     return parsed as OpenAPIV3.Document;
@@ -124,7 +136,7 @@ export class OpenAPIToConnector {
     if (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) {
@@ -134,14 +146,14 @@ export class OpenAPIToConnector {
           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;
@@ -166,6 +178,9 @@ 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}`);
@@ -175,44 +190,68 @@ export class OpenAPIToConnector {
       lines.push(` *`);
       // Split long descriptions into multiple lines
       const descLines = operation.description.split('\n');
-      descLines.forEach(line => {
+      descLines.forEach((line) => {
         if (line.trim()) {
           lines.push(` * ${line.trim()}`);
         }
       });
     }
 
-    // Document parameters with full details
-    if (operation.parameters && operation.parameters.length > 0) {
-      lines.push(' *');
-      lines.push(' * @param {Object} args - Request arguments');
-      
+    // Identify path and query parameters
+    if (operation.parameters) {
       for (const param of operation.parameters) {
-        if (typeof param === 'object' && 'name' in param) {
-          const paramName = param.name;
-          const paramDesc = param.description || '';
-          const paramRequired = param.required ? '(required)' : '(optional)';
-          const paramType = param.schema?.type || 'any';
-          const paramIn = param.in || '';
-          
-          let paramDoc = ` * @param {${paramType}} args.${paramName} ${paramRequired}`;
-          if (paramDesc) {
-            paramDoc += ` - ${paramDesc}`;
-          }
-          if (paramIn) {
-            paramDoc += ` [${paramIn}]`;
+        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);
           }
-          lines.push(paramDoc);
         }
       }
     }
 
-    // Document request body
-    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(' *');
-      const bodyDesc = operation.requestBody.description || 'Request body';
-      const required = operation.requestBody.required ? '(required)' : '(optional)';
-      lines.push(` * @param {Object} args.body ${required} - ${bodyDesc}`);
+      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`);
     }
 
     // Document response
@@ -229,6 +268,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
    */
@@ -243,15 +509,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}
 }`;
   }