@aloma.io/integration-sdk 3.8.50 → 3.8.52

package/OPENAPI_TO_CONNECTOR.md

@@ -0,0 +1,216 @@
+# OpenAPI to Connector Generator
+
+A deterministic script that generates Aloma connector controllers from OpenAPI 3.x specifications.
+
+## Features
+
+- ✅ **Deterministic**: Same OpenAPI input always produces the same connector definition
+- ✅ **No LLM involvement**: Pure parsing and code generation
+- ✅ **OpenAPI 3.x support**: Validates against OpenAPI 3.x schema
+- ✅ **JSON & YAML support**: Handles both JSON and YAML OpenAPI specifications
+- ✅ **Comprehensive coverage**: Generates methods for all endpoints and operations
+- ✅ **Rich documentation**: Uses OpenAPI descriptions and summaries for JSDoc comments
+- ✅ **Parameter mapping**: Maps OpenAPI parameters to method arguments
+- ✅ **Error handling**: Clear error messages for invalid specifications
+
+## Installation
+
+The script is included in the integration-sdk package. Install dependencies:
+
+```bash
+npm install
+```
+
+Build the project:
+
+```bash
+npm run build
+```
+
+## Usage
+
+### CLI Usage (Recommended)
+
+After deploying to npm, you can use the integrated CLI command:
+
+```bash
+# Create a complete connector project from OpenAPI spec
+npx @aloma.io/integration-sdk@latest from-openapi "My Connector" --connector-id "my-connector-123" --spec api.yaml
+
+# With custom output path
+npx @aloma.io/integration-sdk@latest from-openapi "My Connector" --connector-id "my-connector-123" --spec api.yaml --out src/controller/index.mts
+```
+
+#### Options
+
+- `<name>` (required): Name of the connector project
+- `--connector-id <id>` (required): ID of the connector
+- `--spec <file>` (required): OpenAPI specification file (JSON or YAML)
+- `--out <file>` (optional): Output file path for the controller (default: `src/controller/index.mts`)
+
+### Standalone Script Usage
+
+You can also use the standalone script directly:
+
+```bash
+node ./build/openapi-to-connector.mjs generate --name "My Connector" --spec api.yaml --out controller.mts
+```
+
+#### Options
+
+- `--name <name>` (required): Human-readable connector name
+- `--spec <file>` (required): OpenAPI specification file (JSON or YAML)
+- `--out <file>` (optional): Output file path (default: `index.mts`)
+
+### Programmatic Usage
+
+```typescript
+import { OpenAPIToConnector } from './build/openapi-to-connector.mjs';
+
+// Parse OpenAPI spec
+const spec = OpenAPIToConnector.parseSpec(specString);
+
+// Generate controller
+const generator = new OpenAPIToConnector(spec, 'My Connector');
+const controllerCode = generator.generateController();
+```
+
+## Example
+
+### Input: OpenAPI Specification
+
+```yaml
+openapi: 3.0.0
+info:
+  title: User API
+  version: 1.0.0
+paths:
+  /users:
+    get:
+      operationId: listUsers
+      summary: List all users
+      parameters:
+        - name: page
+          in: query
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: Success
+    post:
+      operationId: createUser
+      summary: Create user
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+      responses:
+        '201':
+          description: Created
+```
+
+### Output: Generated Controller
+
+```typescript
+import {AbstractController} from '@aloma.io/integration-sdk';
+
+export default class Controller extends AbstractController {
+  
+  /**
+   * List all users
+   *
+   * @param args - Request arguments
+   * @param args.page - Page number for pagination
+   * @returns Response data
+   */
+  async listUsers(args: any) {
+    // TODO: Implement GET /users
+    throw new Error('Method not implemented');
+  }
+
+  /**
+   * Create user
+   *
+   * @param args.body - Request body
+   * @returns Response data
+   */
+  async createUser(args: any) {
+    // TODO: Implement POST /users
+    throw new Error('Method not implemented');
+  }
+}
+```
+
+## Generated Method Names
+
+The script generates method names using the following priority:
+
+1. **Operation ID**: If `operationId` is present, use it directly
+2. **Method + Path**: Combine HTTP method with path segments
+   - `GET /users` → `getUsers`
+   - `POST /users/{id}/posts` → `post_users_{id}_posts`
+
+## Parameter Mapping
+
+- **Path parameters**: Mapped to `args.paramName`
+- **Query parameters**: Mapped to `args.paramName`
+- **Request body**: Mapped to `args.body`
+- **Headers**: Mapped to `args.headerName`
+
+## JSDoc Generation
+
+The script generates comprehensive JSDoc comments using:
+
+- **Summary**: From `operation.summary`
+- **Description**: From `operation.description`
+- **Parameters**: From `operation.parameters` with descriptions
+- **Request body**: When present
+- **Return type**: Always includes `@returns Response data`
+
+## Error Handling
+
+The script provides clear error messages for:
+
+- Invalid JSON/YAML syntax
+- Non-OpenAPI 3.x specifications
+- Missing required fields (`openapi`, `info`, `paths`)
+- Empty specifications (no operations)
+
+## Testing
+
+Run the included tests:
+
+```bash
+npm test
+```
+
+Or test manually:
+
+```bash
+# Test with sample API
+node ./build/openapi-to-connector.mjs generate --name "Sample API" --spec ./examples/sample-api.yaml --out ./test-output.mts
+```
+
+## Requirements Met
+
+✅ **Runnable script**: CLI with proper argument parsing  
+✅ **OpenAPI 3.x support**: Validates and parses OpenAPI 3.x specs  
+✅ **JSON/YAML support**: Handles both formats  
+✅ **Deterministic**: Same input always produces same output  
+✅ **No inference**: Fails fast on missing information  
+✅ **Full coverage**: Generates methods for all operations  
+✅ **Rich documentation**: Uses all available descriptions  
+✅ **Testing**: Includes unit tests for core functionality  
+
+## Integration with Aloma SDK
+
+The generated controller extends `AbstractController` and follows the Aloma connector pattern:
+
+- Each OpenAPI operation becomes a public async method
+- Methods receive `args` parameter with all request data
+- Methods should return response data or throw errors
+- JSDoc comments provide rich documentation for the UI
+
+The generated controller can be used directly in an Aloma connector project after implementing the actual API calls.

package/README.md

@@ -2,4 +2,18 @@
 
 ## Creating a new Connector
 
-With the aloma integration SDK cli you can simply create a new connector via `npx @aloma.io/integration-sdk@latest create connectorName --connector-id 1234`.
+With the aloma integration SDK cli you can create a new connector in two ways:
+
+### 1. Create from scratch
+```bash
+npx @aloma.io/integration-sdk@latest create connectorName --connector-id 1234
+```
+
+### 2. Generate from OpenAPI specification
+```bash
+npx @aloma.io/integration-sdk@latest from-openapi connectorName --connector-id 1234 --spec api.yaml
+```
+
+This will automatically generate a complete connector project with methods for all OpenAPI endpoints, ready for implementation.
+
+For more details, see [OPENAPI_TO_CONNECTOR.md](./OPENAPI_TO_CONNECTOR.md).

package/build/cli.mjs

@@ -9,6 +9,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);
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const files = [
@@ -76,7 +77,7 @@ program
     console.log('Generating keys ...');
     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`);
     console.log(`
@@ -101,6 +102,61 @@ program
         console.log(stdout);
     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/build/internal/fetcher/fetcher.d.mts

@@ -1,3 +1,4 @@
+/// <reference types="node" resolution-mode="require"/>
 /**
  * http request fetcher
  */

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

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { OpenAPIV3 } from 'openapi-types';
+export declare class OpenAPIToConnector {
+    private spec;
+    private connectorName;
+    constructor(spec: OpenAPIV3.Document, connectorName: string);
+    /**
+     * Parse OpenAPI spec from JSON or YAML string
+     */
+    static parseSpec(specString: string): OpenAPIV3.Document;
+    /**
+     * Extract all operations from the OpenAPI spec
+     */
+    private extractOperations;
+    /**
+     * Generate a valid JavaScript identifier from a string
+     */
+    private toValidIdentifier;
+    /**
+     * 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
+     */
+    getOperationsCount(): number;
+    /**
+     * Generate the connector controller code
+     */
+    generateController(): string;
+}

package/build/openapi-to-connector.mjs

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import fs from 'node:fs';
+import yaml from 'js-yaml';
+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(),
+});
+export class OpenAPIToConnector {
+    spec;
+    connectorName;
+    constructor(spec, connectorName) {
+        this.spec = spec;
+        this.connectorName = connectorName;
+    }
+    /**
+     * Parse OpenAPI spec from JSON or YAML string
+     */
+    static parseSpec(specString) {
+        let parsed;
+        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;
+    }
+    /**
+     * Extract all operations from the OpenAPI spec
+     */
+    extractOperations() {
+        const operations = [];
+        for (const [path, pathItem] of Object.entries(this.spec.paths)) {
+            if (!pathItem)
+                continue;
+            const methods = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
+            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
+     */
+    toValidIdentifier(str) {
+        return str
+            .replace(/[^a-zA-Z0-9_$]/g, '_')
+            .replace(/^[0-9]/, '_$&')
+            .replace(/_+/g, '_')
+            .replace(/^_|_$/g, '');
+    }
+    /**
+     * Generate method name from operation info
+     */
+    generateMethodName(operation) {
+        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
+     */
+    generateJSDoc(operation) {
+        const lines = [];
+        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() {
+        return this.extractOperations().length;
+    }
+    /**
+     * Generate the connector controller code
+     */
+    generateController() {
+        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/examples/generate-connector.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+
+# Example script to generate a connector from OpenAPI specification
+# Usage: ./generate-connector.sh <connector-name> <openapi-file> [output-file]
+
+set -e
+
+CONNECTOR_NAME=${1:-"My API Connector"}
+OPENAPI_FILE=${2:-"./sample-api.yaml"}
+OUTPUT_FILE=${3:-"./generated-controller.mts"}
+
+echo "🚀 Generating connector: $CONNECTOR_NAME"
+echo "📄 OpenAPI spec: $OPENAPI_FILE"
+echo "📝 Output file: $OUTPUT_FILE"
+echo ""
+
+# Check if OpenAPI file exists
+if [ ! -f "$OPENAPI_FILE" ]; then
+    echo "❌ Error: OpenAPI file '$OPENAPI_FILE' not found"
+    exit 1
+fi
+
+# Generate the connector
+node ../build/openapi-to-connector.mjs generate \
+    --name "$CONNECTOR_NAME" \
+    --spec "$OPENAPI_FILE" \
+    --out "$OUTPUT_FILE"
+
+echo ""
+echo "✅ Success! Generated connector controller: $OUTPUT_FILE"
+echo ""
+echo "Next steps:"
+echo "1. Review the generated controller"
+echo "2. Implement the actual API calls in each method"
+echo "3. Add the controller to your Aloma connector project"