@aloma.io/integration-sdk 3.8.56 → 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/internal/dispatcher/index.mjs

@@ -139,10 +139,11 @@ ${arg.configurableClientScope}
             query = query
                 .filter((what) => !!what?.trim() && !['constructor', '__proto__', 'toString', 'toSource', 'prototype'].includes(what))
                 .slice(0, 20);
+            const originalQuery = [...query];
             const method = resolveMethod(query);
             if (!method && !_resolvers.__default)
-                throw new Error(`${query} not found`);
-            return method ? method(variables) : _resolvers.__default(variables ? { ...variables, __method: query } : variables);
+                throw new Error(`${originalQuery} not found`);
+            return method ? method(variables) : _resolvers.__default(variables ? { ...variables, __method: originalQuery } : variables);
         };
         const introspect = () => local._types;
         const configSchema = () => local._config;

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
@@ -186,7 +216,7 @@ export class OpenAPIToConnector {
                 this.addRequestBodyProperties(operation.requestBody, optionProps);
             }
             // Check if options parameter is required (has required query params or required body)
-            const hasRequiredNonPathParams = queryParams.some(p => p.required) || (hasBody && operation.requestBody?.required);
+            const hasRequiredNonPathParams = queryParams.some((p) => p.required) || (hasBody && operation.requestBody?.required);
             const optionsRequired = hasRequiredNonPathParams ? '' : '?';
             // Only add options parameter if there are actual options
             if (optionProps.length > 0) {
@@ -285,7 +315,7 @@ export class OpenAPIToConnector {
      * Sanitize a name to be a valid TypeScript identifier
      */
     sanitizeTypeName(name) {
-        return name
+        return (name
             // Replace dots with underscores
             .replace(/\./g, '_')
             // Replace + with _Plus (common in OpenAPI for enums)
@@ -297,9 +327,9 @@ export class OpenAPIToConnector {
             // Remove multiple consecutive underscores
             .replace(/_+/g, '_')
             // Remove trailing/leading underscores
-            .replace(/^_+|_+$/g, '')
+            .replace(/^_+|_+$/g, '') ||
             // Ensure it's not empty
-            || 'UnknownType';
+            'UnknownType');
     }
     /**
      * Get TypeScript type from schema object
@@ -323,7 +353,8 @@ export class OpenAPIToConnector {
         if (schema.type === 'object' && schema.properties) {
             const propNames = Object.keys(schema.properties);
             // For response objects, generate inline type definitions
-            if (propNames.length <= 5) { // Reasonable limit for inline types
+            if (propNames.length <= 5) {
+                // Reasonable limit for inline types
                 const propTypes = Object.entries(schema.properties).map(([key, prop]) => {
                     const propType = this.getTypeFromSchema(prop);
                     return `${key}: ${propType}`;
@@ -420,14 +451,15 @@ export class OpenAPIToConnector {
         if (schema.properties) {
             for (const [propName, propSchema] of Object.entries(schema.properties)) {
                 const propType = this.getTypeFromSchema(propSchema);
-                const required = (schema.required && schema.required.includes(propName)) || (requestBody.required);
+                const required = (schema.required && schema.required.includes(propName)) || requestBody.required;
                 const optional = required ? '' : '?';
                 // Add description as comment if available
                 const description = propSchema?.description;
                 if (description) {
                     // Clean up description for inline use
                     const cleanDesc = description.replace(/\n/g, ' ').replace(/\s+/g, ' ').trim();
-                    if (cleanDesc.length < 100) { // Only add short descriptions inline
+                    if (cleanDesc.length < 100) {
+                        // Only add short descriptions inline
                         optionProps.push(`${propName}${optional}: ${propType} /** ${cleanDesc} */`);
                     }
                     else {
@@ -708,23 +740,34 @@ export class OpenAPIToConnector {
         for (const resource of resources) {
             const resourceName = resource.fileName;
             // Find the corresponding spec for this resource
-            const resourceSpec = resourceSpecs?.find(rs => rs.fileName === resourceName);
+            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});
   }`);
                 }
@@ -756,10 +799,13 @@ ${jsdoc}
         const paramMatch = signature.match(/\(([^)]+)\)/);
         if (!paramMatch || paramMatch[1].trim() === '')
             return '';
-        const allParams = paramMatch[1].split(',').map(p => {
+        const allParams = paramMatch[1]
+            .split(',')
+            .map((p) => {
             const paramName = p.trim().split(':')[0].trim();
             return paramName.replace(/[?]/g, '');
-        }).filter(p => p.length > 0);
+        })
+            .filter((p) => p.length > 0);
         // Check if signature actually has options parameter
         const hasOptionsParam = allParams.includes('options');
         // Always extract path parameters as discrete parameters when they exist
@@ -807,7 +853,7 @@ ${jsdoc}
         }
         // Handle allOf, oneOf, anyOf
         if (schema.allOf) {
-            lines.push(`  // Inherits from: ${schema.allOf.map((s) => s.$ref ? this.resolveSchemaRef(s.$ref) : 'unknown').join(', ')}`);
+            lines.push(`  // Inherits from: ${schema.allOf.map((s) => (s.$ref ? this.resolveSchemaRef(s.$ref) : 'unknown')).join(', ')}`);
         }
         lines.push('}');
         return lines.join('\n');
@@ -845,7 +891,7 @@ ${jsdoc}
             lines.push(' *');
             // Split long descriptions into multiple lines
             const descLines = operation.description.split('\n');
-            descLines.forEach(line => {
+            descLines.forEach((line) => {
                 lines.push(` * ${line}`);
             });
         }
@@ -866,7 +912,7 @@ ${jsdoc}
             }
         }
         // Document discrete path parameters
-        pathParams.forEach(param => {
+        pathParams.forEach((param) => {
             const paramType = this.getParameterType(param);
             const paramDesc = param.description || '';
             lines.push(` * @param {${paramType}} ${param.name} ${paramDesc}`);
@@ -875,7 +921,7 @@ ${jsdoc}
         if (queryParams.length > 0 || operation.requestBody) {
             lines.push(' * @param {Object} options - Request options');
             // Document query parameters
-            queryParams.forEach(param => {
+            queryParams.forEach((param) => {
                 const paramType = this.getParameterType(param);
                 const paramDesc = param.description || '';
                 const required = param.required ? '(required)' : '(optional)';
@@ -938,7 +984,7 @@ ${jsdoc}
         if (schema.properties) {
             for (const [propName, propSchema] of Object.entries(schema.properties)) {
                 const propType = this.getTypeFromSchema(propSchema);
-                const propRequired = (schema.required && schema.required.includes(propName)) || (requestBody.required);
+                const propRequired = (schema.required && schema.required.includes(propName)) || requestBody.required;
                 const requiredText = propRequired ? '(required)' : '(optional)';
                 const propDesc = propSchema?.description || '';
                 lines.push(` * @param {${propType}} options.${propName} ${requiredText} - ${propDesc} [body property]`);
@@ -1156,9 +1202,7 @@ ${functions}`;
         const imports = resources
             .map((resource) => `import * as ${resource.fileName}Functions from '../resources/${resource.fileName}.mjs';`)
             .join('\n');
-        const properties = resources
-            .map((resource) => `  ${resource.fileName}: any = {};`)
-            .join('\n');
+        const properties = resources.map((resource) => `  ${resource.fileName}: any = {};`).join('\n');
         const bindings = resources
             .map((resource) => `    this.bindResourceFunctions('${resource.fileName}', ${resource.fileName}Functions);`)
             .join('\n');
@@ -1219,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.56",
+  "version": "3.8.59",
   "description": "",
   "author": "aloma.io",
   "license": "Apache-2.0",
@@ -53,5 +53,17 @@
     "mocha": "^10",
     "prettier": "^3",
     "ts-node": "^10.9.2"
+  },
+  "resolutions": {
+    "path-to-regexp": "0.1.13"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aloma-io/integration.git",
+    "directory": "integration-sdk"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
   }
 }

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/internal/dispatcher/index.mts

@@ -172,10 +172,12 @@ ${arg.configurableClientScope}
         )
         .slice(0, 20);
 
+      const originalQuery = [...query];
+
       const method = resolveMethod(query);
-      if (!method && !_resolvers.__default) throw new Error(`${query} not found`);
+      if (!method && !_resolvers.__default) throw new Error(`${originalQuery} not found`);
 
-      return method ? method(variables) : _resolvers.__default(variables ? {...variables, __method: query} : variables);
+      return method ? method(variables) : _resolvers.__default(variables ? {...variables, __method: originalQuery} : variables);
     };
 
     const introspect = () => local._types;

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}`);
+}