@aloma.io/integration-sdk 3.8.52 → 3.8.53

package/MULTI_RESOURCE_GUIDE.md

@@ -0,0 +1,217 @@
+# Multi-Resource Connector Guide
+
+This guide explains how to create and manage multi-resource connectors using the Aloma Integration SDK.
+
+## Overview
+
+Multi-resource connectors allow you to organize large APIs into logical resource groups (e.g., `companies`, `contacts`, `deals`) while maintaining a clean, modular architecture. Each resource is generated from its own OpenAPI specification and composed in a main controller.
+
+## Architecture
+
+```
+src/
+├── controller/
+│   └── index.mts          # Main controller (extends AbstractController)
+└── resources/
+    ├── companies.mts      # CompaniesResource (plain class)
+    ├── contacts.mts       # ContactsResource (plain class)
+    └── lists.mts          # ListsResource (plain class)
+```
+
+### Main Controller
+- Extends `AbstractController`
+- Has `private api: any` and `protected async start()`
+- Composes all resources
+- Initializes API client once
+
+### Resource Classes
+- Plain TypeScript classes (no inheritance)
+- Receive controller reference in constructor
+- Access `api` via getter: `this.controller['api']`
+- Focus on their specific domain
+
+## Creating Multi-Resource Connectors
+
+### 1. Create from Multiple OpenAPI Specs
+
+```bash
+npx @aloma.io/integration-sdk@latest create-multi-resource "MyConnector" \
+  --connector-id "my-connector-123" \
+  --resources "CompaniesResource:companies.json,ContactsResource:contacts.json,ListsResource:lists.json" \
+  --base-url "https://api.example.com"
+```
+
+**Parameters:**
+- `--resources`: Comma-separated list of `ClassName:specFile` pairs
+- `--base-url`: API base URL (optional, extracted from first spec if not provided)
+- `--no-build`: Skip dependency installation and building
+
+### 2. Resource Specification Format
+
+The `--resources` parameter accepts a comma-separated list in this format:
+```
+"ClassName1:specFile1,ClassName2:specFile2,ClassName3:specFile3"
+```
+
+**Examples:**
+```bash
+# HubSpot connector
+--resources "CompaniesResource:hubspot-companies.json,ContactsResource:hubspot-contacts.json,ListsResource:hubspot-lists.json"
+
+# Salesforce connector  
+--resources "AccountsResource:sf-accounts.json,ContactsResource:sf-contacts.json,OpportunitiesResource:sf-opportunities.json"
+
+# Stripe connector
+--resources "CustomersResource:stripe-customers.json,PaymentsResource:stripe-payments.json,SubscriptionsResource:stripe-subscriptions.json"
+```
+
+## Adding Resources to Existing Projects
+
+### 1. Add New Resource
+
+```bash
+npx @aloma.io/integration-sdk@latest add-resource ./existing-project \
+  --className "DealsResource" \
+  --spec "deals.json"
+```
+
+This will:
+- Generate the new resource class
+- Save it to `src/resources/deals.mts`
+- Provide instructions for updating the main controller
+
+### 2. Update Main Controller Manually
+
+After adding a resource, you need to update the main controller:
+
+```typescript
+// 1. Add import
+import DealsResource from '../resources/deals.mjs';
+
+// 2. Add property
+deals!: DealsResource;
+
+// 3. Add initialization in start()
+this.deals = new DealsResource(this);
+```
+
+## Usage Examples
+
+### Generated API Calls
+
+```typescript
+// Companies resource
+await controller.companies.create({
+  body: { properties: { name: 'Acme Corp', domain: 'acme.com' } }
+});
+
+await controller.companies.getPage({
+  limit: 10,
+  properties: ['name', 'domain', 'industry']
+});
+
+await controller.companies.getById('12345', {
+  properties: ['name', 'email']
+});
+
+// Contacts resource
+await controller.contacts.create({
+  body: { properties: { firstname: 'John', lastname: 'Doe', email: 'john@example.com' } }
+});
+
+await controller.contacts.getPage({
+  limit: 20,
+  properties: ['firstname', 'lastname', 'email']
+});
+
+// Lists resource
+await controller.lists.getAll({ limit: 50 });
+
+await controller.lists.create({
+  body: { name: 'My Contact List', processingType: 'MANUAL' }
+});
+```
+
+### With Custom Headers
+
+```typescript
+await controller.companies.getPage({
+  limit: 10,
+  headers: {
+    'X-Request-ID': 'unique-id-123',
+    'X-Custom-Header': 'value'
+  }
+});
+```
+
+## Best Practices
+
+### 1. Resource Naming
+- Use descriptive class names: `CompaniesResource`, `ContactsResource`
+- File names are auto-generated: `companies.mts`, `contacts.mts`
+- Property names in controller: `companies`, `contacts`
+
+### 2. OpenAPI Specifications
+- Each resource should have its own focused OpenAPI spec
+- Ensure all specs use the same base URL or provide `--base-url`
+- Use consistent parameter naming across specs
+
+### 3. Error Handling
+- All generated methods return promises
+- API errors are handled by the underlying `api.fetch()` method
+- Add custom error handling in your connector logic as needed
+
+### 4. Type Safety
+- Generated code uses `any` types for flexibility
+- Consider adding TypeScript interfaces for better type safety
+- Use JSDoc comments for parameter documentation
+
+## Example: Complete HubSpot Connector
+
+```bash
+# Create the connector
+npx @aloma.io/integration-sdk@latest create-multi-resource "HubSpot-v2" \
+  --connector-id "hubspot-123" \
+  --resources "CompaniesResource:examples/hubspot-companies.json,ContactsResource:examples/hubspot-contacts.json,ListsResource:examples/hubspot-lists.json" \
+  --base-url "https://api.hubapi.com"
+
+# Install dependencies
+cd HubSpot-v2
+yarn --ignore-engines
+
+# Build
+yarn build
+
+# Start
+yarn start
+```
+
+## Troubleshooting
+
+### Import Path Errors
+If you see TypeScript errors about missing file extensions:
+- Ensure you're using `.mjs` extensions in imports
+- The generator handles this automatically in new projects
+
+### Resource Not Found
+If a resource property is undefined:
+- Check that the resource is properly initialized in `start()`
+- Verify the import path in the main controller
+- Ensure the resource file was generated correctly
+
+### Build Errors
+If the project fails to build:
+- Try using `--no-build` flag during creation
+- Install dependencies manually: `yarn --ignore-engines`
+- Check for TypeScript errors in generated files
+
+## Migration from Single-Resource
+
+To convert an existing single-resource connector to multi-resource:
+
+1. Extract the relevant endpoints into separate OpenAPI specs
+2. Create new resource classes using `from-openapi --resource`
+3. Update the main controller to compose the resources
+4. Remove the old single controller methods
+
+This approach maintains backward compatibility while providing better organization for large APIs.

package/README.md

@@ -2,7 +2,7 @@
 
 ## Creating a new Connector
 
-With the aloma integration SDK cli you can create a new connector in two ways:
+With the aloma integration SDK cli you can create a new connector in three ways:
 
 ### 1. Create from scratch
 ```bash
@@ -16,4 +16,57 @@ npx @aloma.io/integration-sdk@latest from-openapi connectorName --connector-id 1
 
 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).
+### 3. Generate with Resource Architecture (Recommended for large APIs)
+```bash
+npx @aloma.io/integration-sdk@latest from-openapi connectorName \
+  --connector-id 1234 \
+  --spec api.yaml \
+  --out src/resources/myresource.mts \
+  --resource MyResource \
+  --no-build
+```
+
+### 4. Create Multi-Resource Connector (Recommended for complex APIs)
+```bash
+npx @aloma.io/integration-sdk@latest create-multi-resource "HubSpot-v2" \
+  --connector-id "hubspot-123" \
+  --resources "CompaniesResource:examples/hubspot-companies.json,ContactsResource:examples/hubspot-contacts.json,ListsResource:examples/hubspot-lists.json" \
+  --base-url "https://api.hubapi.com"
+```
+
+This creates a complete multi-resource connector with:
+- Individual resource classes for each OpenAPI spec
+- Main controller that composes all resources
+- Proper TypeScript imports and architecture
+
+```typescript
+// Usage
+await controller.companies.create({ body: { properties: { name: 'Acme' } } });
+await controller.contacts.getPage({ limit: 10 });
+await controller.lists.getAll({ limit: 50 });
+```
+
+### 5. Add Resource to Existing Project
+```bash
+npx @aloma.io/integration-sdk@latest add-resource ./existing-project \
+  --className "DealsResource" \
+  --spec "deals.json"
+```
+
+This adds a new resource to an existing multi-resource connector.
+
+## 📚 Documentation
+
+- **[OPENAPI_TO_CONNECTOR.md](./OPENAPI_TO_CONNECTOR.md)** - OpenAPI generator details
+- **[MULTI_RESOURCE_GUIDE.md](./MULTI_RESOURCE_GUIDE.md)** - Complete guide for multi-resource connectors
+
+## 🚀 Quick Examples
+
+### HubSpot Multi-Resource Connector
+```bash
+# Create complete HubSpot connector with 3 resources
+npx @aloma.io/integration-sdk@latest create-multi-resource "HubSpot-v2" \
+  --connector-id "hubspot-123" \
+  --resources "CompaniesResource:examples/hubspot-companies.json,ContactsResource:examples/hubspot-contacts.json,ListsResource:examples/hubspot-lists.json"
+
+```

package/build/cli.mjs

@@ -109,6 +109,9 @@ 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)
@@ -123,30 +126,48 @@ program
         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();
+        let controllerCode;
+        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}`;
         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`);
+        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.) 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
 📝 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`);
+${nextSteps}`);
     }
     catch (error) {
         console.error('❌ Error:', error instanceof Error ? error.message : 'Unknown error');
@@ -173,4 +194,134 @@ class Extractor {
         }), { encoding: 'utf-8' });
     }
 }
+// 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 = [];
+        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.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.message);
+        process.exit(1);
+    }
+});
 program.parse();

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

@@ -28,6 +28,29 @@ export declare class OpenAPIToConnector {
      * Get the number of operations in the OpenAPI spec
      */
     getOperationsCount(): number;
+    /**
+     * Generate method signature with options object
+     */
+    private generateMethodSignature;
+    /**
+     * Generate method implementation code
+     */
+    private generateMethodImplementation;
+    /**
+     * Generate proper import paths with .mjs extensions for TypeScript module resolution
+     */
+    private generateImportPath;
+    /**
+     * Generate a resource class (does NOT extend AbstractController, receives controller reference)
+     */
+    generateResourceClass(className: string): string;
+    /**
+     * Generate a main controller that composes multiple resources
+     */
+    generateMainController(resources: Array<{
+        className: string;
+        fileName: string;
+    }>): string;
     /**
      * Generate the connector controller code
      */