@aloma.io/integration-sdk 3.8.57 → 3.8.59

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
      */

package/build/openapi-to-connector.mjs

@@ -23,9 +23,39 @@ 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
+        const suffix = operationId.includes('_')
+            ? operationId.split('_').pop()
+            : 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
@@ -713,20 +743,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});
   }`);
                 }
@@ -1222,11 +1263,19 @@ ${exposedMethods}
         }
         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);
+            }
             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.59",
   "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

package/src/openapi-to-connector.mts

@@ -37,13 +37,51 @@ interface OperationInfo {
   responses?: any;
 }
 
+export interface OpenAPIToConnectorOptions {
+  nestedPaths?: boolean;
+}
+
 export class OpenAPIToConnector {
   private spec: OpenAPIV3.Document;
   private connectorName: string;
+  private options: OpenAPIToConnectorOptions;
 
-  constructor(spec: OpenAPIV3.Document, connectorName: string) {
+  constructor(spec: OpenAPIV3.Document, connectorName: string, options?: OpenAPIToConnectorOptions) {
     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: string, urlPath: string, operationId: string): string {
+    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
+    const suffix = operationId.includes('_')
+      ? operationId.split('_').pop()!
+      : 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('.');
   }
 
   /**
@@ -823,7 +861,7 @@ export class OpenAPIToConnector {
 
       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) {
@@ -832,15 +870,30 @@ export class OpenAPIToConnector {
           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: string;
+          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});
   }`);
         }
@@ -1409,12 +1462,19 @@ ${exposedMethods}
 
     const methods = operations
       .map((operation) => {
-        const methodName = this.generateMethodName(operation);
+        let methodName: string;
+        if (this.options.nestedPaths && operation.operationId) {
+          methodName = this.deriveMethodPath(operation.method, operation.path, operation.operationId);
+        } else {
+          methodName = this.generateMethodName(operation);
+        }
         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');
 

package/test/nested-resolver.test.mjs

@@ -0,0 +1,184 @@
+import { Dispatcher } from '../build/internal/dispatcher/index.mjs';
+
+// Simple test framework matching project convention
+const colors = {
+  green: '\x1b[32m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  reset: '\x1b[0m',
+  cyan: '\x1b[36m'
+};
+
+let passed = 0;
+let failed = 0;
+
+async function test(name, fn) {
+  try {
+    console.log(`${colors.cyan}Running: ${name}${colors.reset}`);
+    await fn();
+    console.log(`${colors.green}✓ PASS: ${name}${colors.reset}\n`);
+    passed++;
+  } catch (error) {
+    console.log(`${colors.red}✗ FAIL: ${name}${colors.reset}`);
+    console.log(`${colors.red}  Error: ${error.message}${colors.reset}\n`);
+    failed++;
+  }
+}
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message || 'Assertion failed');
+}
+
+function assertEqual(actual, expected, message) {
+  if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+    throw new Error(message || `Expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+  }
+}
+
+// Helper: build a dispatcher with given resolvers and execute a query
+async function buildAndExecute(resolvers, query, variables) {
+  const dispatcher = new Dispatcher();
+  dispatcher.types({ fields: {} });
+  dispatcher.resolvers(resolvers);
+  dispatcher.main(async () => {});
+  const built = dispatcher.build();
+  return built.execute({ query, variables });
+}
+
+// --- TESTS ---
+
+// Test 1: Dispatcher correctly resolves pre-built nested structures (baseline)
+await test('Dispatcher resolves pre-built nested structure (baseline)', async () => {
+  const handler = async (args) => ({ created: true, ...args });
+  const resolvers = { crm: { contacts: { create: handler } } };
+  const result = await buildAndExecute(resolvers, ['crm', 'contacts', 'create'], { name: 'test' });
+  assertEqual(result, { created: true, name: 'test' });
+});
+
+// Test 2: Dispatcher resolves flat keys (baseline)
+await test('Dispatcher resolves flat key (baseline)', async () => {
+  const handler = async (args) => ({ flat: true, ...args });
+  const resolvers = { contactsCreate: handler };
+  const result = await buildAndExecute(resolvers, ['contactsCreate'], { id: 1 });
+  assertEqual(result, { flat: true, id: 1 });
+});
+
+// Test 3: CRITICAL — import buildResolvers from runtime-context and verify it
+// handles dotted method names by creating nested structures.
+// This is the RED test: buildResolvers doesn't exist yet.
+await test('buildResolvers creates nested structure for dotted method names', async () => {
+  const { buildResolvers } = await import('../build/builder/runtime-context.mjs');
+
+  assert(typeof buildResolvers === 'function', 'buildResolvers should be exported from runtime-context');
+
+  const mockController = {
+    'crm.contacts.create': async (args) => ({ method: 'crm.contacts.create', ...args }),
+    'crm.contacts.list': async (args) => ({ method: 'crm.contacts.list', ...args }),
+    'flatMethod': async (args) => ({ method: 'flatMethod', ...args }),
+    '__autocomplete': async () => ({}),
+    '__endpoint': async () => ({}),
+    '__default': async () => ({}),
+  };
+
+  const methods = ['crm.contacts.create', 'crm.contacts.list', 'flatMethod', '__autocomplete', '__endpoint', '__default'];
+  const resolvers = buildResolvers(methods, mockController);
+
+  // Nested structure for dotted names
+  assert(resolvers.crm, 'resolvers.crm should exist');
+  assert(resolvers.crm.contacts, 'resolvers.crm.contacts should exist');
+  assert(typeof resolvers.crm.contacts.create === 'function', 'crm.contacts.create should be a function');
+  assert(typeof resolvers.crm.contacts.list === 'function', 'crm.contacts.list should be a function');
+
+  // Flat structure for non-dotted names
+  assert(typeof resolvers.flatMethod === 'function', 'flatMethod should be a function');
+  assert(typeof resolvers.__autocomplete === 'function', '__autocomplete should be a function');
+  assert(typeof resolvers.__endpoint === 'function', '__endpoint should be a function');
+  assert(typeof resolvers.__default === 'function', '__default should be a function');
+});
+
+// Test 4: buildResolvers nested methods resolve correctly through dispatcher
+await test('buildResolvers nested methods resolve through dispatcher end-to-end', async () => {
+  const { buildResolvers } = await import('../build/builder/runtime-context.mjs');
+
+  const mockController = {
+    'crm.contacts.create': async (args) => ({ created: true, ...(args || {}) }),
+    'crm.contacts.list': async () => ({ items: ['a', 'b'] }),
+    'flatMethod': async (args) => ({ flat: true, ...(args || {}) }),
+    '__autocomplete': async () => ({}),
+    '__endpoint': async () => ({}),
+    '__default': async () => ({}),
+  };
+
+  const methods = ['crm.contacts.create', 'crm.contacts.list', 'flatMethod', '__autocomplete', '__endpoint', '__default'];
+  const resolvers = buildResolvers(methods, mockController);
+
+  // Execute through dispatcher
+  const nestedResult = await buildAndExecute(resolvers, ['crm', 'contacts', 'create'], { name: 'Acme' });
+  assertEqual(nestedResult, { created: true, name: 'Acme' });
+
+  const listResult = await buildAndExecute(resolvers, ['crm', 'contacts', 'list'], {});
+  assertEqual(listResult, { items: ['a', 'b'] });
+
+  const flatResult = await buildAndExecute(resolvers, ['flatMethod'], { x: 42 });
+  assertEqual(flatResult, { flat: true, x: 42 });
+});
+
+// Test 5: buildResolvers preserves existing flat registration for non-dotted names
+await test('buildResolvers flat names are unchanged (backward compat)', async () => {
+  const { buildResolvers } = await import('../build/builder/runtime-context.mjs');
+
+  const mockController = {
+    'simpleMethodA': async () => ({ a: true }),
+    'simpleMethodB': async () => ({ b: true }),
+    '__autocomplete': async () => ({}),
+    '__endpoint': async () => ({}),
+    '__default': async () => ({}),
+  };
+
+  const methods = ['simpleMethodA', 'simpleMethodB', '__autocomplete', '__endpoint', '__default'];
+  const resolvers = buildResolvers(methods, mockController);
+
+  // All flat — no nested structures
+  assert(typeof resolvers.simpleMethodA === 'function', 'simpleMethodA should be a function');
+  assert(typeof resolvers.simpleMethodB === 'function', 'simpleMethodB should be a function');
+
+  const resultA = await buildAndExecute(resolvers, ['simpleMethodA'], {});
+  assertEqual(resultA, { a: true });
+
+  const resultB = await buildAndExecute(resolvers, ['simpleMethodB'], {});
+  assertEqual(resultB, { b: true });
+});
+
+// Test 6: Nested and flat coexist without overwriting each other
+await test('buildResolvers nested and flat coexist without conflicts', async () => {
+  const { buildResolvers } = await import('../build/builder/runtime-context.mjs');
+
+  const mockController = {
+    'crm.contacts.create': async () => ({ source: 'nested' }),
+    'contactsCreate': async () => ({ source: 'flat' }),
+    '__autocomplete': async () => ({}),
+    '__endpoint': async () => ({}),
+    '__default': async () => ({}),
+  };
+
+  const methods = ['crm.contacts.create', 'contactsCreate', '__autocomplete', '__endpoint', '__default'];
+  const resolvers = buildResolvers(methods, mockController);
+
+  const nestedResult = await buildAndExecute(resolvers, ['crm', 'contacts', 'create'], {});
+  assertEqual(nestedResult, { source: 'nested' });
+
+  const flatResult = await buildAndExecute(resolvers, ['contactsCreate'], {});
+  assertEqual(flatResult, { source: 'flat' });
+});
+
+// --- SUMMARY ---
+console.log(`\n${colors.yellow}📊 Nested Resolver Test Results:${colors.reset}`);
+console.log(`${colors.green}✓ Passed: ${passed}${colors.reset}`);
+console.log(`${colors.red}✗ Failed: ${failed}${colors.reset}`);
+
+if (failed > 0) {
+  console.log(`\n${colors.red}❌ Some tests failed!${colors.reset}`);
+  process.exit(1);
+} else {
+  console.log(`\n${colors.green}🎉 All nested resolver tests passed!${colors.reset}`);
+}

package/test/openapi-nested-paths.test.mjs

@@ -0,0 +1,100 @@
+import { OpenAPIToConnector } from '../build/openapi-to-connector.mjs';
+
+// Simple test framework matching project convention
+const colors = {
+  green: '\x1b[32m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  reset: '\x1b[0m',
+  cyan: '\x1b[36m'
+};
+
+let passed = 0;
+let failed = 0;
+
+async function test(name, fn) {
+  try {
+    console.log(`${colors.cyan}Running: ${name}${colors.reset}`);
+    await fn();
+    console.log(`${colors.green}✓ PASS: ${name}${colors.reset}\n`);
+    passed++;
+  } catch (error) {
+    console.log(`${colors.red}✗ FAIL: ${name}${colors.reset}`);
+    console.log(`${colors.red}  Error: ${error.message}${colors.reset}\n`);
+    failed++;
+  }
+}
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message || 'Assertion failed');
+}
+
+function assertEqual(actual, expected, message) {
+  if (actual !== expected) {
+    throw new Error(message || `Expected "${expected}", got "${actual}"`);
+  }
+}
+
+// Minimal OpenAPI spec for testing
+const minimalSpec = {
+  openapi: '3.0.0',
+  info: { title: 'Test API', version: '1.0.0' },
+  paths: {}
+};
+
+// --- TESTS ---
+
+// Test 1: GET /crm/v3/objects/contacts with opId -> crm.contacts.getPage
+await test('nestedPaths: GET /crm/v3/objects/contacts -> crm.contacts.getPage', async () => {
+  const generator = new OpenAPIToConnector(minimalSpec, 'hubspot', { nestedPaths: true });
+  assert(typeof generator.deriveMethodPath === 'function', 'deriveMethodPath should be a method on the generator');
+  const result = generator.deriveMethodPath('GET', '/crm/v3/objects/contacts', 'get-/crm/v3/objects/contacts_getPage');
+  assertEqual(result, 'crm.contacts.getPage');
+});
+
+// Test 2: POST /crm/v3/objects/contacts with opId -> crm.contacts.create
+await test('nestedPaths: POST /crm/v3/objects/contacts -> crm.contacts.create', async () => {
+  const generator = new OpenAPIToConnector(minimalSpec, 'hubspot', { nestedPaths: true });
+  const result = generator.deriveMethodPath('POST', '/crm/v3/objects/contacts', 'post-/crm/v3/objects/contacts_create');
+  assertEqual(result, 'crm.contacts.create');
+});
+
+// Test 3: Dedup - POST /crm/v3/objects/contacts/merge with opId _merge -> crm.contacts.merge (NOT crm.contacts.merge.merge)
+await test('nestedPaths: dedup - POST /crm/v3/objects/contacts/merge -> crm.contacts.merge', async () => {
+  const generator = new OpenAPIToConnector(minimalSpec, 'hubspot', { nestedPaths: true });
+  const result = generator.deriveMethodPath('POST', '/crm/v3/objects/contacts/merge', 'post-/crm/v3/objects/contacts/merge_merge');
+  assertEqual(result, 'crm.contacts.merge');
+});
+
+// Test 4: Batch - POST /crm/v3/objects/contacts/batch/archive -> crm.contacts.batch.archive (NOT duplicated)
+await test('nestedPaths: batch - POST /crm/v3/objects/contacts/batch/archive -> crm.contacts.batch.archive', async () => {
+  const generator = new OpenAPIToConnector(minimalSpec, 'hubspot', { nestedPaths: true });
+  const result = generator.deriveMethodPath('POST', '/crm/v3/objects/contacts/batch/archive', 'post-/crm/v3/objects/contacts/batch/archive_archive');
+  assertEqual(result, 'crm.contacts.batch.archive');
+});
+
+// Test 5: Flat mode (nestedPaths: false) -> just getPage (existing behavior unchanged)
+await test('flat mode (nestedPaths: false): same input -> just getPage', async () => {
+  const generator = new OpenAPIToConnector(minimalSpec, 'hubspot', { nestedPaths: false });
+  const result = generator.deriveMethodPath('GET', '/crm/v3/objects/contacts', 'get-/crm/v3/objects/contacts_getPage');
+  assertEqual(result, 'getPage');
+});
+
+// Test 6: Flat mode with no options (default behavior unchanged)
+await test('flat mode (no options): same input -> just getPage', async () => {
+  const generator = new OpenAPIToConnector(minimalSpec, 'hubspot');
+  const result = generator.deriveMethodPath('GET', '/crm/v3/objects/contacts', 'get-/crm/v3/objects/contacts_getPage');
+  assertEqual(result, 'getPage');
+});
+
+// --- SUMMARY ---
+console.log(`\n${colors.yellow}--- OpenAPI Nested Paths Test Results ---${colors.reset}`);
+console.log(`${colors.green}Passed: ${passed}${colors.reset}`);
+console.log(`${colors.red}Failed: ${failed}${colors.reset}`);
+
+if (failed > 0) {
+  console.log(`\n${colors.red}Some tests failed!${colors.reset}`);
+  process.exit(1);
+} else {
+  console.log(`\n${colors.green}All nested path tests passed!${colors.reset}`);
+}