@aloma.io/integration-sdk 3.8.50 → 3.8.51

package/src/cli.mts

@@ -10,6 +10,7 @@ import {TARGET_DIR} from './builder/index.mjs';
 import {notEmpty} from './internal/util/index.mjs';
 import JWE from './internal/util/jwe/index.mjs';
 import parseTypes from './transform/index.mjs';
+import {OpenAPIToConnector} from './openapi-to-connector.mjs';
 
 const exec = util.promisify(ChildProcess.exec);
 
@@ -101,7 +102,7 @@ program
     await generateKeys({target});
 
     console.log('Installing dependencies ...');
-    await exec(`cd ${target}; yarn`);
+    await exec(`cd ${target}; yarn --ignore-engines`);
 
     console.log('Building ...');
     await exec(`cd ${target}; yarn build`);
@@ -131,6 +132,69 @@ program
     new Extractor().extract('./src/controller/index.mts', './build/.controller.json');
   });
 
+program
+  .command('from-openapi')
+  .description('Generate a connector controller from an OpenAPI specification')
+  .argument('<name>', 'name of the connector project')
+  .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')
+  .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
+      console.log('Generating controller from OpenAPI specification...');
+      const generator = new OpenAPIToConnector(spec, name);
+      const 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});
+
+      console.log('Installing dependencies...');
+      await exec(`cd ${target}; yarn --ignore-engines`);
+
+      console.log('Building...');
+      await exec(`cd ${target}; yarn build`);
+
+      console.log(`
+✅ Success! Generated connector from OpenAPI specification
+📝 Connector name: ${name}
+📊 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`);
+    } 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});
+      }
+      process.exit(1);
+    }
+  });
+
 class Extractor {
   async extract(source, target) {
     notEmpty(source, 'source');

package/src/controller/index.mts

@@ -1,6 +1,6 @@
-import { ConfigField } from '../index.mjs';
+import {ConfigField} from '../index.mjs';
 import Fetcher from '../internal/fetcher/fetcher.mjs';
-import { OAuth } from '../internal/fetcher/oauth-fetcher.mjs';
+import {OAuth} from '../internal/fetcher/oauth-fetcher.mjs';
 
 /**
  * Abstract controller class

package/src/internal/connector/server/on-connect/index.mts

@@ -1,12 +1,12 @@
-import { init } from '@paralleldrive/cuid2';
-import { AbstractController } from '../../../../index.mjs';
+import {init} from '@paralleldrive/cuid2';
+import {AbstractController} from '../../../../index.mjs';
 import Dispatcher from '../../../dispatcher/index.mjs';
 import Fetcher from '../../../fetcher/fetcher.mjs';
-import { Config } from '../../../websocket/config.mjs';
-import { decryptConfig } from './decrypt-config.mjs';
-import { patchFinishOAuth } from './finish-oauth.mjs';
-import { makeOAuth } from './make-oauth.mjs';
-import { patchStartOAuth } from './start-oauth.mjs';
+import {Config} from '../../../websocket/config.mjs';
+import {decryptConfig} from './decrypt-config.mjs';
+import {patchFinishOAuth} from './finish-oauth.mjs';
+import {makeOAuth} from './make-oauth.mjs';
+import {patchStartOAuth} from './start-oauth.mjs';
 
 const cuid = init({length: 32});
 
@@ -28,9 +28,9 @@ export const onConnect = ({
         secrets,
         config,
       });
-      
+
       if (decrypted?.oauthResult?.scope) {
-        console.log(`Scope: ${decrypted.oauthResult.scope}`)
+        console.log(`Scope: ${decrypted.oauthResult.scope}`);
       }
 
       await patchStartOAuth({dispatcher, decrypted});

package/src/internal/fetcher/fetcher.mts

@@ -1,4 +1,4 @@
-import { unwrap } from '../util/index.mjs';
+import {unwrap} from '../util/index.mjs';
 
 /**
  * http request fetcher
@@ -17,7 +17,7 @@ export default class Fetcher {
     retry?: number;
     baseUrl?: string;
     onResponse?: (response: Response) => void;
-    customize?: (request: { [key: string]: any }) => void;
+    customize?: (request: {[key: string]: any}) => void;
   } = {}) {
     this.retry = retry;
     this.baseUrl = baseUrl;
@@ -68,7 +68,7 @@ export default class Fetcher {
       /**
        * request headers like Accept, Content-type
        */
-      headers?: { [key: string]: any };
+      headers?: {[key: string]: any};
       /**
        * request body like "hello world" or {hello: "world"}
        */
@@ -81,7 +81,7 @@ export default class Fetcher {
       baseUrl = local.baseUrl;
     options ||= {};
 
-    const options0: any = { ...options };
+    const options0: any = {...options};
 
     if (retries == null) retries = local.retry;
 
@@ -139,7 +139,7 @@ export default class Fetcher {
       }
 
       if (status === 204) {
-        return { ok: true };
+        return {ok: true};
       }
 
       return unwrap(ret, options0);

package/src/internal/websocket/transport/index.mjs

@@ -1,10 +1,10 @@
-import { init } from '@paralleldrive/cuid2';
+import {init} from '@paralleldrive/cuid2';
 import C from '../connection/constants.mjs';
 const cuid = init({length: 32});
 
 import WebSocket from 'ws';
-import { DurableWebsocket } from './durable.mjs';
-import { Callback, Packet } from './packet.mjs';
+import {DurableWebsocket} from './durable.mjs';
+import {Callback, Packet} from './packet.mjs';
 
 const cleanInterval = 45 * 1000;
 const pingInterval = 30 * 1000;
@@ -191,5 +191,4 @@ class Transport {
   }
 }
 
-export { Transport };
-
+export {Transport};

package/src/openapi-to-connector.mts

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+
+import {Command} from 'commander';
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import {OpenAPIV3} from 'openapi-types';
+import {z} from 'zod';
+
+// OpenAPI 3.x validation schema
+const OpenAPISchema = z.object({
+  openapi: z.string().regex(/^3\.\d+\.\d+$/),
+  info: z.object({
+    title: z.string(),
+    version: z.string(),
+    description: z.string().optional(),
+  }),
+  paths: z.record(z.string(), z.any()),
+  servers: z
+    .array(
+      z.object({
+        url: z.string(),
+        description: z.string().optional(),
+      })
+    )
+    .optional(),
+  components: z.any().optional(),
+});
+
+interface OperationInfo {
+  method: string;
+  path: string;
+  operationId?: string;
+  summary?: string;
+  description?: string;
+  parameters?: any[];
+  requestBody?: any;
+  responses?: any;
+}
+
+export class OpenAPIToConnector {
+  private spec: OpenAPIV3.Document;
+  private connectorName: string;
+
+  constructor(spec: OpenAPIV3.Document, connectorName: string) {
+    this.spec = spec;
+    this.connectorName = connectorName;
+  }
+
+  /**
+   * Parse OpenAPI spec from JSON or YAML string
+   */
+  static parseSpec(specString: string): OpenAPIV3.Document {
+    let parsed: any;
+
+    try {
+      // Try parsing as JSON first
+      parsed = JSON.parse(specString);
+    } catch {
+      try {
+        // If JSON fails, try YAML
+        parsed = yaml.load(specString);
+      } catch (error) {
+        throw new Error(`Failed to parse OpenAPI spec: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      }
+    }
+
+    // Validate against OpenAPI 3.x schema
+    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}`);
+    }
+
+    return parsed as OpenAPIV3.Document;
+  }
+
+  /**
+   * Extract all operations from the OpenAPI spec
+   */
+  private extractOperations(): OperationInfo[] {
+    const operations: OperationInfo[] = [];
+
+    for (const [path, pathItem] of Object.entries(this.spec.paths)) {
+      if (!pathItem) continue;
+
+      const methods = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'] as const;
+
+      for (const method of methods) {
+        const operation = pathItem[method];
+        if (!operation) continue;
+
+        operations.push({
+          method: method.toUpperCase(),
+          path,
+          operationId: operation.operationId,
+          summary: operation.summary,
+          description: operation.description,
+          parameters: operation.parameters,
+          requestBody: operation.requestBody,
+          responses: operation.responses,
+        });
+      }
+    }
+
+    return operations;
+  }
+
+  /**
+   * Generate a valid JavaScript identifier from a string
+   */
+  private toValidIdentifier(str: string): string {
+    return str
+      .replace(/[^a-zA-Z0-9_$]/g, '_')
+      .replace(/^[0-9]/, '_$&')
+      .replace(/_+/g, '_')
+      .replace(/^_|_$/g, '');
+  }
+
+  /**
+   * Generate method name from operation info
+   */
+  private generateMethodName(operation: OperationInfo): string {
+    if (operation.operationId) {
+      return this.toValidIdentifier(operation.operationId);
+    }
+
+    // Generate from method + path
+    const pathParts = operation.path
+      .replace(/[{}]/g, '') // Remove path parameters
+      .split('/')
+      .filter((part) => part.length > 0)
+      .map((part) => this.toValidIdentifier(part));
+
+    const methodPrefix = operation.method.toLowerCase();
+    const pathSuffix = pathParts.join('_') || 'root';
+
+    return `${methodPrefix}_${pathSuffix}`;
+  }
+
+  /**
+   * Generate JSDoc comment for an operation
+   */
+  private generateJSDoc(operation: OperationInfo): string {
+    const lines: string[] = [];
+
+    if (operation.summary) {
+      lines.push(` * ${operation.summary}`);
+    }
+
+    if (operation.description) {
+      lines.push(` * ${operation.description}`);
+    }
+
+    if (operation.parameters && operation.parameters.length > 0) {
+      lines.push(' *');
+      lines.push(' * @param args - Request arguments');
+      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 (operation.requestBody) {
+      lines.push(' *');
+      lines.push(' * @param args.body - Request body');
+    }
+
+    lines.push(' * @returns Response data');
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Get the number of operations in the OpenAPI spec
+   */
+  getOperationsCount(): number {
+    return this.extractOperations().length;
+  }
+
+  /**
+   * Generate the connector controller code
+   */
+  generateController(): 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);
+
+        return `  /**\n${jsdoc}\n   */\n  async ${methodName}(args: any) {\n    // TODO: Implement ${operation.method} ${operation.path}\n    throw new Error('Method not implemented');\n  }`;
+      })
+      .join('\n\n');
+
+    return `import {AbstractController} from '@aloma.io/integration-sdk';
+
+export default class Controller extends AbstractController {
+  
+${methods}
+}`;
+  }
+}
+
+// CLI setup
+const program = new Command();
+
+program
+  .name('openapi-to-connector')
+  .description('Generate a connector controller from an OpenAPI specification')
+  .version('1.0.0')
+  .showHelpAfterError();
+
+program
+  .command('generate')
+  .description('Generate connector controller from OpenAPI spec')
+  .requiredOption('--name <name>', 'Human-readable connector name')
+  .requiredOption('--spec <file>', 'OpenAPI specification file (JSON or YAML)')
+  .option('--out <file>', 'Output file path', 'index.mts')
+  .action(async (options) => {
+    try {
+      // Read and parse the OpenAPI spec
+      const specContent = fs.readFileSync(options.spec, 'utf-8');
+      const spec = OpenAPIToConnector.parseSpec(specContent);
+
+      // Generate the connector controller
+      const generator = new OpenAPIToConnector(spec, options.name);
+      const controllerCode = generator.generateController();
+
+      // Write the output file
+      fs.writeFileSync(options.out, controllerCode);
+
+      console.log(`✅ Successfully generated connector controller: ${options.out}`);
+      console.log(`📝 Connector name: ${options.name}`);
+      console.log(`📊 Found ${generator['extractOperations']().length} operations`);
+    } catch (error) {
+      console.error('❌ Error:', error instanceof Error ? error.message : 'Unknown error');
+      process.exit(1);
+    }
+  });
+
+// Only run CLI if this file is executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  // If no command is provided, show help
+  if (process.argv.length <= 2) {
+    program.help();
+  } else {
+    program.parse();
+  }
+}

package/test/openapi-to-connector.test.mts

@@ -0,0 +1,207 @@
+import { describe, it } from 'mocha';
+import { expect } from 'chai';
+import { OpenAPIToConnector } from '../build/openapi-to-connector.mjs';
+
+describe('OpenAPIToConnector', () => {
+  const validOpenAPISpec = {
+    openapi: '3.0.0' as const,
+    info: {
+      title: 'Test API',
+      version: '1.0.0',
+      description: 'A test API'
+    },
+    paths: {
+      '/users': {
+        get: {
+          operationId: 'getUsers',
+          summary: 'Get all users',
+          description: 'Retrieve a list of all users',
+          responses: {
+            '200': {
+              description: 'Successful response',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'array' as const,
+                    items: {
+                      type: 'object' as const,
+                      properties: {
+                        id: { type: 'string' as const },
+                        name: { type: 'string' as const }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        post: {
+          operationId: 'createUser',
+          summary: 'Create a new user',
+          description: 'Create a new user in the system',
+          requestBody: {
+            required: true,
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object' as const,
+                  properties: {
+                    name: { type: 'string' as const },
+                    email: { type: 'string' as const }
+                  }
+                }
+              }
+            }
+          },
+          responses: {
+            '201': {
+              description: 'User created successfully'
+            }
+          }
+        }
+      },
+      '/users/{id}': {
+        get: {
+          operationId: 'getUserById',
+          summary: 'Get user by ID',
+          parameters: [
+            {
+              name: 'id',
+              in: 'path' as const,
+              required: true,
+              schema: { type: 'string' as const },
+              description: 'User ID'
+            }
+          ],
+          responses: {
+            '200': {
+              description: 'User found'
+            }
+          }
+        }
+      }
+    }
+  };
+
+  describe('parseSpec', () => {
+    it('should parse valid OpenAPI 3.0 JSON spec', () => {
+      const specString = JSON.stringify(validOpenAPISpec);
+      const result = OpenAPIToConnector.parseSpec(specString);
+      
+      expect(result.openapi).to.equal('3.0.0');
+      expect(result.info.title).to.equal('Test API');
+      expect(result.paths).to.have.property('/users');
+    });
+
+    it('should parse valid OpenAPI 3.0 YAML spec', () => {
+      const yamlSpec = `
+openapi: 3.0.0
+info:
+  title: Test API
+  version: 1.0.0
+  description: A test API
+paths:
+  /users:
+    get:
+      operationId: getUsers
+      summary: Get all users
+      responses:
+        '200':
+          description: Successful response
+`;
+      const result = OpenAPIToConnector.parseSpec(yamlSpec);
+      
+      expect(result.openapi).to.equal('3.0.0');
+      expect(result.info.title).to.equal('Test API');
+    });
+
+    it('should reject invalid OpenAPI version', () => {
+      const invalidSpec = {
+        ...validOpenAPISpec,
+        openapi: '2.0.0'
+      };
+      
+      expect(() => {
+        OpenAPIToConnector.parseSpec(JSON.stringify(invalidSpec));
+      }).to.throw('Invalid OpenAPI 3.x specification');
+    });
+
+    it('should reject spec without required fields', () => {
+      const invalidSpec = {
+        openapi: '3.0.0'
+        // Missing info and paths
+      };
+      
+      expect(() => {
+        OpenAPIToConnector.parseSpec(JSON.stringify(invalidSpec));
+      }).to.throw('Invalid OpenAPI 3.x specification');
+    });
+
+    it('should reject invalid JSON/YAML', () => {
+      expect(() => {
+        OpenAPIToConnector.parseSpec('invalid json {');
+      }).to.throw('Failed to parse OpenAPI spec');
+    });
+  });
+
+  describe('generateController', () => {
+    it('should generate controller with all operations', () => {
+      const generator = new OpenAPIToConnector(validOpenAPISpec, 'Test Connector');
+      const controllerCode = generator.generateController();
+      
+      expect(controllerCode).to.include('import {AbstractController}');
+      expect(controllerCode).to.include('export default class Controller extends AbstractController');
+      expect(controllerCode).to.include('async getUsers(args: any)');
+      expect(controllerCode).to.include('async createUser(args: any)');
+      expect(controllerCode).to.include('async get_users_{id}(args: any)');
+    });
+
+    it('should generate proper JSDoc comments', () => {
+      const generator = new OpenAPIToConnector(validOpenAPISpec, 'Test Connector');
+      const controllerCode = generator.generateController();
+      
+      expect(controllerCode).to.include('* Get all users');
+      expect(controllerCode).to.include('* Retrieve a list of all users');
+      expect(controllerCode).to.include('* @param args.body - Request body');
+      expect(controllerCode).to.include('* @param args.id - User ID');
+    });
+
+    it('should handle operations without operationId', () => {
+      const specWithoutOperationId = {
+        ...validOpenAPISpec,
+        paths: {
+          '/test': {
+            get: {
+              summary: 'Test endpoint',
+              responses: {
+                '200': {
+                  description: 'Success'
+                }
+              }
+            }
+          }
+        }
+      };
+      
+      const generator = new OpenAPIToConnector(specWithoutOperationId, 'Test Connector');
+      const controllerCode = generator.generateController();
+      
+      expect(controllerCode).to.include('async get_test(args: any)');
+    });
+
+    it('should throw error for empty spec', () => {
+      const emptySpec = {
+        openapi: '3.0.0',
+        info: { title: 'Test', version: '1.0.0' },
+        paths: {}
+      };
+      
+      const generator = new OpenAPIToConnector(emptySpec, 'Test Connector');
+      
+      expect(() => {
+        generator.generateController();
+      }).to.throw('No operations found in OpenAPI specification');
+    });
+  });
+});