@aloma.io/integration-sdk 3.8.50 → 3.8.52

package/src/builder/index.mts

@@ -1,8 +1,8 @@
 import 'dotenv/config';
 import fs from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { notEmpty } from '../internal/util/index.mjs';
+import {fileURLToPath} from 'node:url';
+import {notEmpty} from '../internal/util/index.mjs';
 import RuntimeContext from './runtime-context.mjs';
 
 const DIR_OFFSET = '/../../../../../';
@@ -33,7 +33,7 @@ export type ConfigField =
       /**
        * minimum height of the field
        */
-      height?: number
+      height?: number;
       /**
        * the type of the field
        */

package/src/builder/runtime-context.mts

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
-import { AbstractController } from '../controller/index.mjs';
-import { Connector } from '../internal/index.mjs';
+import {AbstractController} from '../controller/index.mjs';
+import {Connector} from '../internal/index.mjs';
 
 /**
  * Runtime context to manage the lifecycle of the connector

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,305 @@
+#!/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) {
+      // 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
+    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(` *`);
+      // Split long descriptions into multiple lines
+      const descLines = operation.description.split('\n');
+      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');
+      
+      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}]`;
+          }
+          lines.push(paramDoc);
+        }
+      }
+    }
+
+    // Document request body
+    if (operation.requestBody) {
+      lines.push(' *');
+      const bodyDesc = operation.requestBody.description || 'Request body';
+      const required = operation.requestBody.required ? '(required)' : '(optional)';
+      lines.push(` * @param {Object} args.body ${required} - ${bodyDesc}`);
+    }
+
+    // Document response
+    lines.push(' *');
+    lines.push(` * @returns {Promise<Object>} ${operation.method} ${operation.path} response`);
+
+    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();
+  }
+}