@aloma.io/integration-sdk 3.8.57 → 3.8.60

package/build/builder/runtime-context.d.mts

@@ -1,4 +1,15 @@
 import { AbstractController } from '../controller/index.mjs';
+/**
+ * Build a resolvers object from a list of method names and a controller.
+ *
+ * If a method name contains dots (e.g. 'crm.contacts.create'), it is registered
+ * as a nested object tree so that resolveMethod(['crm', 'contacts', 'create'])
+ * finds the handler.
+ *
+ * If a method name has no dots (e.g. 'contactsCreate'), it is registered flat
+ * as before: resolvers.contactsCreate = handler.
+ */
+export declare function buildResolvers(methods: string[], controller: any): any;
 /**
  * Runtime context to manage the lifecycle of the connector
  */

package/build/builder/runtime-context.mjs

@@ -1,6 +1,41 @@
 import fs from 'node:fs';
 import { AbstractController } from '../controller/index.mjs';
 import { Connector } from '../internal/index.mjs';
+/**
+ * Build a resolvers object from a list of method names and a controller.
+ *
+ * If a method name contains dots (e.g. 'crm.contacts.create'), it is registered
+ * as a nested object tree so that resolveMethod(['crm', 'contacts', 'create'])
+ * finds the handler.
+ *
+ * If a method name has no dots (e.g. 'contactsCreate'), it is registered flat
+ * as before: resolvers.contactsCreate = handler.
+ */
+export function buildResolvers(methods, controller) {
+    const resolvers = {};
+    methods.forEach((method) => {
+        const handler = async (args) => {
+            if (!methods.includes(method))
+                throw new Error(`${method} not found`);
+            return controller[method](args);
+        };
+        if (method.includes('.')) {
+            const parts = method.split('.');
+            let node = resolvers;
+            for (let i = 0; i < parts.length - 1; i++) {
+                if (!node[parts[i]] || typeof node[parts[i]] !== 'object') {
+                    node[parts[i]] = {};
+                }
+                node = node[parts[i]];
+            }
+            node[parts[parts.length - 1]] = handler;
+        }
+        else {
+            resolvers[method] = handler;
+        }
+    });
+    return resolvers;
+}
 /**
  * Runtime context to manage the lifecycle of the connector
  */
@@ -36,15 +71,8 @@ export default class RuntimeContext {
             icon,
         });
         const configuration = connector.configure().config(data.config || {});
-        const resolvers = {};
         const methods = [...data.methods, '__autocomplete', '__endpoint', '__default'];
-        methods.forEach((method) => {
-            resolvers[method] = async (args) => {
-                if (!methods.includes(method))
-                    throw new Error(`${method} not found`);
-                return controller[method](args);
-            };
-        });
+        const resolvers = buildResolvers(methods, controller);
         configuration.types(data.types).resolvers(resolvers);
         if (data.options?.endpoint?.enabled) {
             configuration.endpoint((arg) => controller.__endpoint(arg), data.options?.endpoint?.required);

package/build/cli.mjs

@@ -112,6 +112,7 @@ program
     .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('--controller-only', 'Generate only the controller file, do not create full project structure')
+    .option('--nested-paths', 'Use dotted namespace paths derived from URL structure (e.g., crm.contacts.getPage)')
     .option('--no-build', 'Skip installing dependencies and building the project')
     .action(async (name, options) => {
     name = name.replace(/[\/\.]/gi, '');
@@ -122,7 +123,8 @@ program
         const specContent = fs.readFileSync(options.spec, 'utf-8');
         const spec = OpenAPIToConnector.parseSpec(specContent);
         // Generate the controller from OpenAPI spec
-        const generator = new OpenAPIToConnector(spec, name);
+        const generatorOptions = { nestedPaths: !!options.nestedPaths };
+        const generator = new OpenAPIToConnector(spec, name, generatorOptions);
         let controllerCode;
         if (options.resource) {
             console.log(`Generating resource class '${options.resource}' from OpenAPI specification...`);
@@ -220,12 +222,14 @@ program
     .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('--nested-paths', 'Use dotted namespace paths derived from URL structure (e.g., crm.contacts.getPage)')
     .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}`;
+    const generatorOptions = { nestedPaths: !!options.nestedPaths };
     try {
         // Parse resources specification
         const resourceSpecs = options.resources.split(',').map((spec) => {
@@ -253,7 +257,7 @@ program
                 baseUrl = spec.servers[0].url;
             }
             // Generate the resource class
-            const generator = new OpenAPIToConnector(spec, name);
+            const generator = new OpenAPIToConnector(spec, name, generatorOptions);
             const resourceCode = generator.generateResourceClass(className);
             // Write the resource file
             const fileName = className.toLowerCase().replace('resource', '');
@@ -266,7 +270,7 @@ program
         // 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 mainGenerator = new OpenAPIToConnector(firstSpec, name, generatorOptions);
         const mainControllerCode = mainGenerator.generateMainController(resources, parsedResourceSpecs);
         // Write the main controller
         const controllerPath = `${target}/src/controller/index.mts`;
@@ -310,6 +314,7 @@ program
     .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('--nested-paths', 'Use dotted namespace paths derived from URL structure (e.g., crm.contacts.getPage)')
     .option('--no-build', 'Skip building the project after adding the resource')
     .action(async (projectPath, options) => {
     const target = path.resolve(projectPath);
@@ -326,7 +331,8 @@ program
         const specContent = fs.readFileSync(options.spec, 'utf-8');
         const spec = OpenAPIToConnector.parseSpec(specContent);
         // Generate the resource functions file (new function-based pattern)
-        const generator = new OpenAPIToConnector(spec, 'Resource');
+        const generatorOptions = { nestedPaths: !!options.nestedPaths };
+        const generator = new OpenAPIToConnector(spec, 'Resource', generatorOptions);
         const resourceCode = generator.generateResourceClass(options.className);
         // Write the resource file
         const fileName = options.className.toLowerCase().replace('resource', '');
@@ -384,7 +390,7 @@ program
         const resources = [{ className: options.className, fileName }];
         const resourceSpecs = [{ fileName, spec }];
         // Create a temporary generator to generate just the exposed methods for this resource
-        const tempGenerator = new OpenAPIToConnector(spec, 'temp');
+        const tempGenerator = new OpenAPIToConnector(spec, 'temp', generatorOptions);
         const exposedMethods = tempGenerator.generateExposedResourceMethods(resources, resourceSpecs);
         // Add the exposed methods to the controller before the closing brace
         if (exposedMethods.trim()) {

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

@@ -1,9 +1,19 @@
 #!/usr/bin/env node
 import { OpenAPIV3 } from 'openapi-types';
+export interface OpenAPIToConnectorOptions {
+    nestedPaths?: boolean;
+}
 export declare class OpenAPIToConnector {
     private spec;
     private connectorName;
-    constructor(spec: OpenAPIV3.Document, connectorName: string);
+    private options;
+    constructor(spec: OpenAPIV3.Document, connectorName: string, options?: OpenAPIToConnectorOptions);
+    /**
+     * Derive a dotted method path from URL path and operationId.
+     * When nestedPaths is enabled, builds a namespace from the URL segments.
+     * When disabled (default), falls back to the existing flat method name.
+     */
+    deriveMethodPath(httpMethod: string, urlPath: string, operationId: string): string;
     /**
      * Parse OpenAPI spec from JSON or YAML string
      */
@@ -20,6 +30,11 @@ export declare class OpenAPIToConnector {
      * Generate method name from operation info
      */
     private generateMethodName;
+    /**
+     * Disambiguate a colliding method name by prepending path context.
+     * E.g., "archive" from path "/contacts/batch/archive" becomes "batchArchive".
+     */
+    private disambiguateMethodName;
     /**
      * Get the number of operations in the OpenAPI spec
      */

package/build/openapi-to-connector.mjs

@@ -23,9 +23,51 @@ const OpenAPISchema = z.object({
 export class OpenAPIToConnector {
     spec;
     connectorName;
-    constructor(spec, connectorName) {
+    options;
+    constructor(spec, connectorName, options) {
         this.spec = spec;
         this.connectorName = connectorName;
+        this.options = options || {};
+    }
+    /**
+     * Derive a dotted method path from URL path and operationId.
+     * When nestedPaths is enabled, builds a namespace from the URL segments.
+     * When disabled (default), falls back to the existing flat method name.
+     */
+    deriveMethodPath(httpMethod, urlPath, operationId) {
+        if (!this.options.nestedPaths) {
+            return this.generateMethodName({ method: httpMethod, path: urlPath, operationId });
+        }
+        const VERSION_RE = /^v\d+$/;
+        const STRIP = new Set(['objects', 'items']);
+        // Build namespace parts from the URL path
+        const parts = urlPath
+            .replace(/\{[^}]+\}/g, '')
+            .split('/')
+            .filter(Boolean)
+            .filter((p) => !VERSION_RE.test(p))
+            .filter((p) => !STRIP.has(p));
+        // Extract the leaf action from operationId suffix
+        let suffix = operationId.includes('_')
+            ? operationId.split('_').pop()
+            : httpMethod.toLowerCase();
+        // Bug 3 fix: If the suffix looks like a raw URL path (contains slashes),
+        // clean it by extracting meaningful segments rather than using it literally
+        if (suffix.includes('/')) {
+            const suffixParts = suffix
+                .replace(/\{[^}]+\}/g, '')
+                .split('/')
+                .filter(Boolean)
+                .filter((p) => !VERSION_RE.test(p))
+                .filter((p) => !STRIP.has(p));
+            // Use the last meaningful segment from the URL-like suffix, or fall back to HTTP method
+            suffix = suffixParts.length > 0 ? suffixParts[suffixParts.length - 1] : httpMethod.toLowerCase();
+        }
+        // Dedup: if suffix equals last path segment, don't repeat it
+        const last = parts[parts.length - 1];
+        if (suffix === last)
+            return parts.join('.');
+        return [...parts, suffix].join('.');
     }
     /**
      * Parse OpenAPI spec from JSON or YAML string
@@ -137,6 +179,26 @@ export class OpenAPIToConnector {
         const pathSuffix = pathParts.join('_') || 'root';
         return `${methodPrefix}_${pathSuffix}`;
     }
+    /**
+     * Disambiguate a colliding method name by prepending path context.
+     * E.g., "archive" from path "/contacts/batch/archive" becomes "batchArchive".
+     */
+    disambiguateMethodName(baseName, operation) {
+        // Extract meaningful path segments excluding parameters and the base name itself
+        const pathParts = operation.path
+            .replace(/\{[^}]+\}/g, '')
+            .split('/')
+            .filter(Boolean)
+            .filter((p) => p.toLowerCase() !== baseName.toLowerCase());
+        // Use the last path segment before the method name as a distinguishing prefix
+        if (pathParts.length > 0) {
+            const prefix = pathParts[pathParts.length - 1];
+            const capitalizedBase = baseName.charAt(0).toUpperCase() + baseName.slice(1);
+            return `${prefix}${capitalizedBase}`;
+        }
+        // Fallback: prepend the HTTP method
+        return `${operation.method.toLowerCase()}${baseName.charAt(0).toUpperCase() + baseName.slice(1)}`;
+    }
     /**
      * Get the number of operations in the OpenAPI spec
      */
@@ -697,9 +759,9 @@ export class OpenAPIToConnector {
                 }
                 lines.push('');
             }
+            // Make the API call
+            lines.push(`  return this.api.fetch(url, fetchOptions);`);
         }
-        // Make the API call
-        lines.push(`    return this.api.fetch(url, fetchOptions);`);
         return lines.join('\n');
     }
     /**
@@ -713,20 +775,31 @@ export class OpenAPIToConnector {
             const resourceSpec = resourceSpecs?.find((rs) => rs.fileName === resourceName);
             if (resourceSpec) {
                 // Create a temporary generator for this resource's spec
-                const resourceGenerator = new OpenAPIToConnector(resourceSpec.spec, resourceName);
+                const resourceGenerator = new OpenAPIToConnector(resourceSpec.spec, resourceName, this.options);
                 const operations = resourceGenerator.extractOperations();
                 for (const operation of operations) {
                     const methodName = resourceGenerator.generateMethodName(operation);
                     const jsdoc = resourceGenerator.generateDetailedJSDoc(operation);
                     const signature = resourceGenerator.generateMethodSignature(operation);
                     // Generate the exposed method that delegates to the resource
-                    const exposedMethodName = `${resourceName}${methodName.charAt(0).toUpperCase() + methodName.slice(1)}`;
+                    let exposedMethodName;
+                    if (this.options.nestedPaths && operation.operationId) {
+                        // Use dotted path for nested method names
+                        exposedMethodName = resourceGenerator.deriveMethodPath(operation.method, operation.path, operation.operationId);
+                    }
+                    else {
+                        exposedMethodName = `${resourceName}${methodName.charAt(0).toUpperCase() + methodName.slice(1)}`;
+                    }
                     // Generate parameter call based on operation details
                     const parameterCall = this.generateParameterCallForOperation(operation, signature);
+                    // Use quoted method name if it contains dots
+                    const methodDecl = exposedMethodName.includes('.')
+                        ? `'${exposedMethodName}'`
+                        : exposedMethodName;
                     methods.push(`  /**
 ${jsdoc}
    */
-  async ${exposedMethodName}${signature} {
+  async ${methodDecl}${signature} {
     return this.${resourceName}.${methodName}(${parameterCall});
   }`);
                 }
@@ -1134,9 +1207,22 @@ ${jsdoc}
             throw new Error('No operations found in OpenAPI specification');
         }
         const resourceName = className.replace('Resource', '').toLowerCase();
+        // Bug 1 fix: Track used method names and disambiguate collisions
+        const usedNames = new Map();
         const functions = operations
             .map((operation) => {
-            const methodName = this.generateMethodName(operation);
+            let methodName = this.generateMethodName(operation);
+            // Disambiguate duplicate names by prepending path context
+            if (usedNames.has(methodName)) {
+                methodName = this.disambiguateMethodName(methodName, operation);
+                // If still colliding after disambiguation, append a numeric suffix
+                if (usedNames.has(methodName)) {
+                    const count = (usedNames.get(methodName) || 1) + 1;
+                    usedNames.set(methodName, count);
+                    methodName = `${methodName}${count}`;
+                }
+            }
+            usedNames.set(methodName, (usedNames.get(methodName) || 0) + 1);
             const jsdoc = this.generateDetailedJSDoc(operation);
             const signature = this.generateMethodSignature(operation);
             const implementation = this.generateResourceFunctionImplementation(operation);
@@ -1220,13 +1306,33 @@ ${exposedMethods}
         if (operations.length === 0) {
             throw new Error('No operations found in OpenAPI specification');
         }
+        // Bug 1 fix: Track used method names and disambiguate collisions
+        const usedNames = new Map();
         const methods = operations
             .map((operation) => {
-            const methodName = this.generateMethodName(operation);
+            let methodName;
+            if (this.options.nestedPaths && operation.operationId) {
+                methodName = this.deriveMethodPath(operation.method, operation.path, operation.operationId);
+            }
+            else {
+                methodName = this.generateMethodName(operation);
+            }
+            // Disambiguate duplicate names
+            if (usedNames.has(methodName)) {
+                methodName = this.disambiguateMethodName(methodName, operation);
+                if (usedNames.has(methodName)) {
+                    const count = (usedNames.get(methodName) || 1) + 1;
+                    usedNames.set(methodName, count);
+                    methodName = `${methodName}${count}`;
+                }
+            }
+            usedNames.set(methodName, (usedNames.get(methodName) || 0) + 1);
             const jsdoc = this.generateDetailedJSDoc(operation); // Use detailed JSDoc like multi-resource
             const signature = this.generateMethodSignature(operation);
             const implementation = this.generateControllerMethodImplementation(operation); // Use improved implementation
-            return `  /**\n${jsdoc}\n   */\n  async ${methodName}${signature} {\n${implementation}\n  }`;
+            // Use quoted method name if it contains dots
+            const methodDecl = methodName.includes('.') ? `'${methodName}'` : methodName;
+            return `  /**\n${jsdoc}\n   */\n  async ${methodDecl}${signature} {\n${implementation}\n  }`;
         })
             .join('\n\n');
         // Get base URL from servers if available

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aloma.io/integration-sdk",
-  "version": "3.8.57",
+  "version": "3.8.60",
   "description": "",
   "author": "aloma.io",
   "license": "Apache-2.0",

package/src/builder/runtime-context.mts

@@ -2,6 +2,43 @@ import fs from 'node:fs';
 import {AbstractController} from '../controller/index.mjs';
 import {Connector} from '../internal/index.mjs';
 
+/**
+ * Build a resolvers object from a list of method names and a controller.
+ *
+ * If a method name contains dots (e.g. 'crm.contacts.create'), it is registered
+ * as a nested object tree so that resolveMethod(['crm', 'contacts', 'create'])
+ * finds the handler.
+ *
+ * If a method name has no dots (e.g. 'contactsCreate'), it is registered flat
+ * as before: resolvers.contactsCreate = handler.
+ */
+export function buildResolvers(methods: string[], controller: any): any {
+  const resolvers: any = {};
+
+  methods.forEach((method) => {
+    const handler = async (args: any) => {
+      if (!methods.includes(method)) throw new Error(`${method} not found`);
+      return controller[method](args);
+    };
+
+    if (method.includes('.')) {
+      const parts = method.split('.');
+      let node = resolvers;
+      for (let i = 0; i < parts.length - 1; i++) {
+        if (!node[parts[i]] || typeof node[parts[i]] !== 'object') {
+          node[parts[i]] = {};
+        }
+        node = node[parts[i]];
+      }
+      node[parts[parts.length - 1]] = handler;
+    } else {
+      resolvers[method] = handler;
+    }
+  });
+
+  return resolvers;
+}
+
 /**
  * Runtime context to manage the lifecycle of the connector
  */
@@ -42,16 +79,8 @@ export default class RuntimeContext {
 
     const configuration = connector.configure().config(data.config || {});
 
-    const resolvers: any = {};
     const methods: string[] = [...data.methods, '__autocomplete', '__endpoint', '__default'];
-
-    methods.forEach((method) => {
-      resolvers[method] = async (args) => {
-        if (!methods.includes(method)) throw new Error(`${method} not found`);
-
-        return controller[method](args);
-      };
-    });
+    const resolvers = buildResolvers(methods, controller);
 
     configuration.types(data.types).resolvers(resolvers);
 

package/src/cli.mts

@@ -145,6 +145,7 @@ program
   )
   .option('--multi-resource', 'Generate multiple resource files + main controller (requires multiple --spec files)')
   .option('--controller-only', 'Generate only the controller file, do not create full project structure')
+  .option('--nested-paths', 'Use dotted namespace paths derived from URL structure (e.g., crm.contacts.getPage)')
   .option('--no-build', 'Skip installing dependencies and building the project')
   .action(async (name, options) => {
     name = name.replace(/[\/\.]/gi, '');
@@ -156,7 +157,8 @@ program
       const spec = OpenAPIToConnector.parseSpec(specContent);
 
       // Generate the controller from OpenAPI spec
-      const generator = new OpenAPIToConnector(spec, name);
+      const generatorOptions = {nestedPaths: !!options.nestedPaths};
+      const generator = new OpenAPIToConnector(spec, name, generatorOptions);
       let controllerCode: string;
 
       if (options.resource) {
@@ -278,12 +280,14 @@ program
     '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('--nested-paths', 'Use dotted namespace paths derived from URL structure (e.g., crm.contacts.getPage)')
   .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}`;
+    const generatorOptions = {nestedPaths: !!options.nestedPaths};
 
     try {
       // Parse resources specification
@@ -319,7 +323,7 @@ program
         }
 
         // Generate the resource class
-        const generator = new OpenAPIToConnector(spec, name);
+        const generator = new OpenAPIToConnector(spec, name, generatorOptions);
         const resourceCode = generator.generateResourceClass(className);
 
         // Write the resource file
@@ -335,7 +339,7 @@ program
       // 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 mainGenerator = new OpenAPIToConnector(firstSpec, name, generatorOptions);
       const mainControllerCode = mainGenerator.generateMainController(resources, parsedResourceSpecs);
 
       // Write the main controller
@@ -386,6 +390,7 @@ program
   .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('--nested-paths', 'Use dotted namespace paths derived from URL structure (e.g., crm.contacts.getPage)')
   .option('--no-build', 'Skip building the project after adding the resource')
   .action(async (projectPath, options) => {
     const target = path.resolve(projectPath);
@@ -409,7 +414,8 @@ program
       const spec = OpenAPIToConnector.parseSpec(specContent);
 
       // Generate the resource functions file (new function-based pattern)
-      const generator = new OpenAPIToConnector(spec, 'Resource');
+      const generatorOptions = {nestedPaths: !!options.nestedPaths};
+      const generator = new OpenAPIToConnector(spec, 'Resource', generatorOptions);
       const resourceCode = generator.generateResourceClass(options.className);
 
       // Write the resource file
@@ -476,7 +482,7 @@ program
       const resourceSpecs = [{fileName, spec}];
 
       // Create a temporary generator to generate just the exposed methods for this resource
-      const tempGenerator = new OpenAPIToConnector(spec, 'temp');
+      const tempGenerator = new OpenAPIToConnector(spec, 'temp', generatorOptions);
       const exposedMethods = tempGenerator.generateExposedResourceMethods(resources, resourceSpecs);
 
       // Add the exposed methods to the controller before the closing brace