@aloma.io/integration-sdk 3.8.51 → 3.8.53

package/build/openapi-to-connector.mjs

@@ -95,7 +95,27 @@ export class OpenAPIToConnector {
      */
     generateMethodName(operation) {
         if (operation.operationId) {
-            return this.toValidIdentifier(operation.operationId);
+            // Clean up HubSpot-style operationIds like "get-/crm/v3/objects/companies_getPage"
+            let cleaned = operation.operationId;
+            // Extract the last part after underscore if it exists
+            const parts = cleaned.split('_');
+            if (parts.length > 1) {
+                const lastPart = parts[parts.length - 1];
+                // If the last part looks like a method name (camelCase), use it
+                if (lastPart && /^[a-z][a-zA-Z0-9]*$/.test(lastPart)) {
+                    cleaned = lastPart;
+                }
+            }
+            // Remove any remaining special characters and clean up
+            cleaned = cleaned
+                .replace(/^(get|post|put|patch|delete|head|options)-/i, '') // Remove HTTP method prefix
+                .replace(/[^a-zA-Z0-9_]/g, '_')
+                .replace(/_+/g, '_')
+                .replace(/^_|_$/g, '');
+            // If we still have a valid identifier, use it
+            if (cleaned && /^[a-zA-Z]/.test(cleaned)) {
+                return cleaned;
+            }
         }
         // Generate from method + path
         const pathParts = operation.path
@@ -112,26 +132,77 @@ export class OpenAPIToConnector {
      */
     generateJSDoc(operation) {
         const lines = [];
+        const pathParams = [];
+        const queryParams = [];
+        const hasBody = !!operation.requestBody;
         if (operation.summary) {
             lines.push(` * ${operation.summary}`);
         }
         if (operation.description) {
-            lines.push(` * ${operation.description}`);
+            lines.push(` *`);
+            // Split long descriptions into multiple lines
+            const descLines = operation.description.split('\n');
+            descLines.forEach((line) => {
+                if (line.trim()) {
+                    lines.push(` * ${line.trim()}`);
+                }
+            });
         }
-        if (operation.parameters && operation.parameters.length > 0) {
-            lines.push(' *');
-            lines.push(' * @param args - Request arguments');
+        // Identify path and query parameters
+        if (operation.parameters) {
             for (const param of operation.parameters) {
-                if (typeof param === 'object' && 'name' in param && 'description' in param) {
-                    lines.push(` * @param args.${param.name} - ${param.description || 'Parameter'}`);
+                if (typeof param === 'object' && 'name' in param && 'in' in param) {
+                    if (param.in === 'path') {
+                        pathParams.push(param);
+                    }
+                    else if (param.in === 'query') {
+                        queryParams.push(param);
+                    }
                 }
             }
         }
-        if (operation.requestBody) {
+        // Check if using simple signature
+        const useSimpleSignature = queryParams.length === 0 && !hasBody && pathParams.length <= 1;
+        if (useSimpleSignature && pathParams.length === 1) {
+            // Simple signature documentation
+            const param = pathParams[0];
+            const paramType = param.schema?.type || 'string';
+            const paramDesc = param.description || '';
             lines.push(' *');
-            lines.push(' * @param args.body - Request body');
+            lines.push(` * @param {${paramType}} ${param.name} ${paramDesc}`);
+            lines.push(` * @param {Object} options (optional) - Request options`);
+            lines.push(` * @param {Object} options.headers - Custom headers`);
+        }
+        else {
+            // Options object documentation
+            lines.push(' *');
+            lines.push(` * @param {Object} options (optional) - Request options`);
+            // Document path parameters
+            for (const param of pathParams) {
+                const paramType = param.schema?.type || 'string';
+                const paramDesc = param.description || '';
+                const paramRequired = param.required ? '(required)' : '(optional)';
+                lines.push(` * @param {${paramType}} options.${param.name} ${paramRequired} - ${paramDesc} [path]`);
+            }
+            // Document query parameters
+            for (const param of queryParams) {
+                const paramType = param.schema?.type || 'any';
+                const paramDesc = param.description || '';
+                const paramRequired = param.required ? '(required)' : '(optional)';
+                lines.push(` * @param {${paramType}} options.${param.name} ${paramRequired} - ${paramDesc} [query]`);
+            }
+            // Document request body
+            if (operation.requestBody) {
+                const bodyDesc = operation.requestBody.description || 'Request body';
+                const required = operation.requestBody.required ? '(required)' : '(optional)';
+                lines.push(` * @param {Object} options.body ${required} - ${bodyDesc}`);
+            }
+            // Document headers
+            lines.push(` * @param {Object} options.headers (optional) - Custom headers to include in the request`);
         }
-        lines.push(' * @returns Response data');
+        // Document response
+        lines.push(' *');
+        lines.push(` * @returns {Promise<Object>} ${operation.method} ${operation.path} response`);
         return lines.join('\n');
     }
     /**
@@ -140,6 +211,205 @@ export class OpenAPIToConnector {
     getOperationsCount() {
         return this.extractOperations().length;
     }
+    /**
+     * Generate method signature with options object
+     */
+    generateMethodSignature(operation) {
+        const pathParams = [];
+        const queryParams = [];
+        const hasBody = !!operation.requestBody;
+        // Identify path and query parameters
+        if (operation.parameters) {
+            for (const param of operation.parameters) {
+                if (typeof param === 'object' && 'name' in param && 'in' in param) {
+                    if (param.in === 'path') {
+                        pathParams.push(param.name);
+                    }
+                    else if (param.in === 'query') {
+                        queryParams.push(param.name);
+                    }
+                }
+            }
+        }
+        // If there are no query params, no body, and only path params, use simple signature
+        if (queryParams.length === 0 && !hasBody && pathParams.length <= 1) {
+            const params = [];
+            for (const paramName of pathParams) {
+                params.push(`${paramName}: string`);
+            }
+            params.push(`options?: {headers?: {[key: string]: any}}`);
+            return `(${params.join(', ')})`;
+        }
+        // Otherwise, use options object pattern
+        return `(options?: {${[
+            ...pathParams.map((p) => `${p}?: string`),
+            ...queryParams.map((p) => `${p}?: any`),
+            hasBody ? 'body?: any' : '',
+            'headers?: {[key: string]: any}',
+        ]
+            .filter(Boolean)
+            .join(', ')}})`;
+    }
+    /**
+     * Generate method implementation code
+     */
+    generateMethodImplementation(operation) {
+        const lines = [];
+        // Build URL with path parameters
+        let url = operation.path;
+        const pathParams = [];
+        const queryParams = [];
+        const hasBody = !!operation.requestBody;
+        // Identify path and query parameters
+        if (operation.parameters) {
+            for (const param of operation.parameters) {
+                if (typeof param === 'object' && 'name' in param && 'in' in param) {
+                    if (param.in === 'path') {
+                        pathParams.push(param.name);
+                    }
+                    else if (param.in === 'query') {
+                        queryParams.push(param.name);
+                    }
+                }
+            }
+        }
+        // Check if using simple signature (single path param, no query/body)
+        const useSimpleSignature = queryParams.length === 0 && !hasBody && pathParams.length <= 1;
+        if (useSimpleSignature && pathParams.length === 1) {
+            // Simple signature: (pathParam: string, options?: {headers?: ...})
+            const paramName = pathParams[0];
+            lines.push(`    let url = '${url}';`);
+            lines.push(`    if (${paramName}) {`);
+            lines.push(`      url = url.replace('{${paramName}}', ${paramName});`);
+            lines.push(`    }`);
+            lines.push('');
+            lines.push(`    return this.api.fetch(url, {`);
+            lines.push(`      method: '${operation.method}',`);
+            lines.push(`      headers: options?.headers,`);
+            lines.push(`    });`);
+        }
+        else {
+            // Options object pattern
+            lines.push(`    options = options || {};`);
+            lines.push('');
+            // Replace path parameters
+            if (pathParams.length > 0) {
+                lines.push(`    // Build URL with path parameters`);
+                lines.push(`    let url = '${url}';`);
+                for (const paramName of pathParams) {
+                    lines.push(`    if (options.${paramName}) {`);
+                    lines.push(`      url = url.replace('{${paramName}}', options.${paramName});`);
+                    lines.push(`    }`);
+                }
+                lines.push('');
+            }
+            else {
+                lines.push(`    const url = '${url}';`);
+                lines.push('');
+            }
+            // Build fetch options
+            lines.push(`    const fetchOptions: any = {`);
+            lines.push(`      method: '${operation.method}',`);
+            // Add query parameters
+            if (queryParams.length > 0) {
+                lines.push(`      params: {},`);
+            }
+            // Add body if present
+            if (hasBody) {
+                lines.push(`      body: options.body,`);
+            }
+            // Add headers if present
+            lines.push(`      headers: options.headers,`);
+            lines.push(`    };`);
+            lines.push('');
+            // Add query parameters to options
+            if (queryParams.length > 0) {
+                lines.push(`    // Add query parameters`);
+                for (const paramName of queryParams) {
+                    lines.push(`    if (options.${paramName} !== undefined) {`);
+                    lines.push(`      fetchOptions.params.${paramName} = options.${paramName};`);
+                    lines.push(`    }`);
+                }
+                lines.push('');
+            }
+            // Make the API call
+            lines.push(`    return this.api.fetch(url, fetchOptions);`);
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Generate proper import paths with .mjs extensions for TypeScript module resolution
+     */
+    generateImportPath(relativePath) {
+        // For resource classes, we need to reference the compiled .mjs files
+        return relativePath.endsWith('.mjs') ? relativePath : `${relativePath}.mjs`;
+    }
+    /**
+     * Generate a resource class (does NOT extend AbstractController, receives controller reference)
+     */
+    generateResourceClass(className) {
+        const operations = this.extractOperations();
+        if (operations.length === 0) {
+            throw new Error('No operations found in OpenAPI specification');
+        }
+        const methods = operations
+            .map((operation) => {
+            const methodName = this.generateMethodName(operation);
+            const jsdoc = this.generateJSDoc(operation);
+            const signature = this.generateMethodSignature(operation);
+            const implementation = this.generateMethodImplementation(operation);
+            return `  /**\n${jsdoc}\n   */\n  async ${methodName}${signature} {\n${implementation}\n  }`;
+        })
+            .join('\n\n');
+        return `import {AbstractController} from '@aloma.io/integration-sdk';
+
+export default class ${className} {
+  private controller: AbstractController;
+
+  constructor(controller: AbstractController) {
+    this.controller = controller;
+  }
+
+  private get api() {
+    return this.controller['api'];
+  }
+
+${methods}
+}`;
+    }
+    /**
+     * Generate a main controller that composes multiple resources
+     */
+    generateMainController(resources) {
+        // Get base URL from servers if available
+        const baseUrl = this.spec.servers && this.spec.servers.length > 0 ? this.spec.servers[0].url : 'API_BASE_URL';
+        const imports = resources
+            .map((resource) => `import ${resource.className} from '../resources/${resource.fileName}.mjs';`)
+            .join('\n');
+        const properties = resources
+            .map((resource) => `  ${resource.className.toLowerCase().replace('resource', '')}!: ${resource.className};`)
+            .join('\n');
+        const initializations = resources
+            .map((resource) => `    this.${resource.className.toLowerCase().replace('resource', '')} = new ${resource.className}(this);`)
+            .join('\n');
+        return `import {AbstractController} from '@aloma.io/integration-sdk';
+${imports}
+
+export default class Controller extends AbstractController {
+${properties}
+
+  private api: any;
+
+  protected async start(): Promise<void> {
+    this.api = this.getClient({
+      baseUrl: '${baseUrl}',
+    });
+    
+    // Initialize each resource - they receive 'this' controller reference
+${initializations}
+  }
+}`;
+    }
     /**
      * Generate the connector controller code
      */
@@ -152,13 +422,26 @@ export class OpenAPIToConnector {
             .map((operation) => {
             const methodName = this.generateMethodName(operation);
             const jsdoc = this.generateJSDoc(operation);
-            return `  /**\n${jsdoc}\n   */\n  async ${methodName}(args: any) {\n    // TODO: Implement ${operation.method} ${operation.path}\n    throw new Error('Method not implemented');\n  }`;
+            const signature = this.generateMethodSignature(operation);
+            const implementation = this.generateMethodImplementation(operation);
+            return `  /**\n${jsdoc}\n   */\n  async ${methodName}${signature} {\n${implementation}\n  }`;
         })
             .join('\n\n');
+        // Get base URL from servers if available
+        const baseUrl = this.spec.servers && this.spec.servers.length > 0 ? this.spec.servers[0].url : 'API_BASE_URL';
+        const startMethod = `  private api: any;
+
+  protected async start(): Promise<void> {
+    this.api = this.getClient({
+      baseUrl: '${baseUrl}',
+    });
+  }`;
         return `import {AbstractController} from '@aloma.io/integration-sdk';
 
 export default class Controller extends AbstractController {
   
+${startMethod}
+
 ${methods}
 }`;
     }

package/examples/api-without-servers.json

@@ -0,0 +1,32 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "Test API",
+    "version": "1.0.0",
+    "description": "API without servers definition"
+  },
+  "paths": {
+    "/users": {
+      "get": {
+        "summary": "List users",
+        "operationId": "listUsers",
+        "parameters": [
+          {
+            "name": "limit",
+            "in": "query",
+            "schema": {
+              "type": "integer"
+            },
+            "description": "Maximum number of users"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success"
+          }
+        }
+      }
+    }
+  }
+}
+

package/examples/companies-resource-class.mts

@@ -0,0 +1,310 @@
+import {AbstractController} from '@aloma.io/integration-sdk';
+
+export default class CompaniesResource extends AbstractController {
+  
+  /**
+ * Retrieve a batch of companies
+ *
+ * Retrieve a batch of companies by ID (`companyId`) or by a unique property (`idProperty`). You can specify what is returned using the `properties` query parameter.
+ *
+ * @param {boolean} archived (optional) - Whether to return only results that have been archived. [query]
+ *
+ * @param {Object} body (required) - Request body
+ *
+ * @returns {Promise<Object>} POST /crm/v3/objects/companies/batch/read response
+   */
+  async read(archived?: any, body?: any) {
+    const url = '/crm/v3/objects/companies/batch/read';
+    const options: any = {
+      method: 'POST',
+      params: {},
+      body,
+    };
+
+    // Add query parameters
+    if (archived !== undefined) {
+      options.params.archived = archived;
+    }
+
+    return this.api.fetch(url, options);
+  }
+
+  /**
+ * Retrieve companies
+ *
+ * Retrieve all companies, using query parameters to control the information that gets returned.
+ *
+ * @param {integer} limit (optional) - The maximum number of results to display per page. [query]
+ * @param {string} after (optional) - The paging cursor token of the last successfully read resource will be returned as the `paging.next.after` JSON property of a paged response containing more results. [query]
+ * @param {array} properties (optional) - A comma separated list of the properties to be returned in the response. If any of the specified properties are not present on the requested object(s), they will be ignored. [query]
+ * @param {array} propertiesWithHistory (optional) - A comma separated list of the properties to be returned along with their history of previous values. If any of the specified properties are not present on the requested object(s), they will be ignored. Usage of this parameter will reduce the maximum number of companies that can be read by a single request. [query]
+ * @param {array} associations (optional) - A comma separated list of object types to retrieve associated IDs for. If any of the specified associations do not exist, they will be ignored. [query]
+ * @param {boolean} archived (optional) - Whether to return only results that have been archived. [query]
+ *
+ * @returns {Promise<Object>} GET /crm/v3/objects/companies response
+   */
+  async getPage(limit?: any, after?: any, properties?: any, propertiesWithHistory?: any, associations?: any, archived?: any) {
+    const url = '/crm/v3/objects/companies';
+    const options: any = {
+      method: 'GET',
+      params: {},
+    };
+
+    // Add query parameters
+    if (limit !== undefined) {
+      options.params.limit = limit;
+    }
+    if (after !== undefined) {
+      options.params.after = after;
+    }
+    if (properties !== undefined) {
+      options.params.properties = properties;
+    }
+    if (propertiesWithHistory !== undefined) {
+      options.params.propertiesWithHistory = propertiesWithHistory;
+    }
+    if (associations !== undefined) {
+      options.params.associations = associations;
+    }
+    if (archived !== undefined) {
+      options.params.archived = archived;
+    }
+
+    return this.api.fetch(url, options);
+  }
+
+  /**
+ * Create a company
+ *
+ * Create a single company. Include a `properties` object to define [property values](https://developers.hubspot.com/docs/guides/api/crm/properties) for the company, along with an `associations` array to define [associations](https://developers.hubspot.com/docs/guides/api/crm/associations/associations-v4) with other CRM records.
+ *
+ * @param {Object} body (required) - Request body
+ *
+ * @returns {Promise<Object>} POST /crm/v3/objects/companies response
+   */
+  async create(body?: any) {
+    const url = '/crm/v3/objects/companies';
+    const options: any = {
+      method: 'POST',
+      body,
+    };
+
+    return this.api.fetch(url, options);
+  }
+
+  /**
+ * Search for companies
+ *
+ * Search for companies by filtering on properties, searching through associations, and sorting results. Learn more about [CRM search](https://developers.hubspot.com/docs/guides/api/crm/search#make-a-search-request).
+ *
+ * @param {Object} body (required) - Request body
+ *
+ * @returns {Promise<Object>} POST /crm/v3/objects/companies/search response
+   */
+  async doSearch(body?: any) {
+    const url = '/crm/v3/objects/companies/search';
+    const options: any = {
+      method: 'POST',
+      body,
+    };
+
+    return this.api.fetch(url, options);
+  }
+
+  /**
+ * Retrieve a company
+ *
+ * Retrieve a company by its ID (`companyId`) or by a unique property (`idProperty`). You can specify what is returned using the `properties` query parameter.
+ *
+ * @param {string} companyId (required) - The ID of the company [path]
+ * @param {array} properties (optional) - A comma separated list of the properties to be returned in the response. If any of the specified properties are not present on the requested object(s), they will be ignored. [query]
+ * @param {array} propertiesWithHistory (optional) - A comma separated list of the properties to be returned along with their history of previous values. If any of the specified properties are not present on the requested object(s), they will be ignored. [query]
+ * @param {array} associations (optional) - A comma separated list of object types to retrieve associated IDs for. If any of the specified associations do not exist, they will be ignored. [query]
+ * @param {boolean} archived (optional) - Whether to return only results that have been archived. [query]
+ * @param {string} idProperty (optional) - The name of a property whose values are unique for this object [query]
+ *
+ * @returns {Promise<Object>} GET /crm/v3/objects/companies/{companyId} response
+   */
+  async getById(companyId: string, properties?: any, propertiesWithHistory?: any, associations?: any, archived?: any, idProperty?: any) {
+    // Build URL with path parameters
+    let url = '/crm/v3/objects/companies/{companyId}';
+    if (companyId) {
+      url = url.replace('{companyId}', companyId);
+    }
+
+    const options: any = {
+      method: 'GET',
+      params: {},
+    };
+
+    // Add query parameters
+    if (properties !== undefined) {
+      options.params.properties = properties;
+    }
+    if (propertiesWithHistory !== undefined) {
+      options.params.propertiesWithHistory = propertiesWithHistory;
+    }
+    if (associations !== undefined) {
+      options.params.associations = associations;
+    }
+    if (archived !== undefined) {
+      options.params.archived = archived;
+    }
+    if (idProperty !== undefined) {
+      options.params.idProperty = idProperty;
+    }
+
+    return this.api.fetch(url, options);
+  }
+
+  /**
+ * Update a company
+ *
+ * Update a company by ID (`companyId`) or unique property value (`idProperty`). Provided property values will be overwritten. Read-only and non-existent properties will result in an error. Properties values can be cleared by passing an empty string.
+ *
+ * @param {string} companyId (required) [path]
+ * @param {string} idProperty (optional) - The name of a property whose values are unique for this object [query]
+ *
+ * @param {Object} body (required) - Request body
+ *
+ * @returns {Promise<Object>} PATCH /crm/v3/objects/companies/{companyId} response
+   */
+  async update(companyId: string, idProperty?: any, body?: any) {
+    // Build URL with path parameters
+    let url = '/crm/v3/objects/companies/{companyId}';
+    if (companyId) {
+      url = url.replace('{companyId}', companyId);
+    }
+
+    const options: any = {
+      method: 'PATCH',
+      params: {},
+      body,
+    };
+
+    // Add query parameters
+    if (idProperty !== undefined) {
+      options.params.idProperty = idProperty;
+    }
+
+    return this.api.fetch(url, options);
+  }
+
+  /**
+ * Archive a company
+ *
+ * Delete a company by ID. Deleted companies can be restored within 90 days of deletion. Learn more about [restoring records](https://knowledge.hubspot.com/records/restore-deleted-records).
+ *
+ * @param {string} companyId (required) [path]
+ *
+ * @returns {Promise<Object>} DELETE /crm/v3/objects/companies/{companyId} response
+   */
+  async archive(companyId: string) {
+    // Build URL with path parameters
+    let url = '/crm/v3/objects/companies/{companyId}';
+    if (companyId) {
+      url = url.replace('{companyId}', companyId);
+    }
+
+    const options: any = {
+      method: 'DELETE',
+    };
+
+    return this.api.fetch(url, options);
+  }
+
+  /**
+ * Create or update a batch of companies by unique property values
+ *
+ * Create or update companies identified by a unique property value as specified by the `idProperty` query parameter. `idProperty` query param refers to a property whose values are unique for the object.
+ *
+ * @param {Object} body (required) - Request body
+ *
+ * @returns {Promise<Object>} POST /crm/v3/objects/companies/batch/upsert response
+   */
+  async upsert(body?: any) {
+    const url = '/crm/v3/objects/companies/batch/upsert';
+    const options: any = {
+      method: 'POST',
+      body,
+    };
+
+    return this.api.fetch(url, options);
+  }
+
+  /**
+ * Create a batch of companies
+ *
+ * Create a batch of companies. The `inputs` array can contain a `properties` object to define property values for each company, along with an `associations` array to define [associations](https://developers.hubspot.com/docs/guides/api/crm/associations/associations-v4) with other CRM records.
+ *
+ * @param {Object} body (required) - Request body
+ *
+ * @returns {Promise<Object>} POST /crm/v3/objects/companies/batch/create response
+   */
+  async create(body?: any) {
+    const url = '/crm/v3/objects/companies/batch/create';
+    const options: any = {
+      method: 'POST',
+      body,
+    };
+
+    return this.api.fetch(url, options);
+  }
+
+  /**
+ * Update a batch of companies
+ *
+ * Update a batch of companies by ID.
+ *
+ * @param {Object} body (required) - Request body
+ *
+ * @returns {Promise<Object>} POST /crm/v3/objects/companies/batch/update response
+   */
+  async update(body?: any) {
+    const url = '/crm/v3/objects/companies/batch/update';
+    const options: any = {
+      method: 'POST',
+      body,
+    };
+
+    return this.api.fetch(url, options);
+  }
+
+  /**
+ * Archive a batch of companies
+ *
+ * Delete a batch of companies by ID. Deleted companies can be restored within 90 days of deletion. Learn more about [restoring records](https://knowledge.hubspot.com/records/restore-deleted-records).
+ *
+ * @param {Object} body (required) - Request body
+ *
+ * @returns {Promise<Object>} POST /crm/v3/objects/companies/batch/archive response
+   */
+  async archive(body?: any) {
+    const url = '/crm/v3/objects/companies/batch/archive';
+    const options: any = {
+      method: 'POST',
+      body,
+    };
+
+    return this.api.fetch(url, options);
+  }
+
+  /**
+ * Merge two companies
+ *
+ * Merge two company records. Learn more about [merging records](https://knowledge.hubspot.com/records/merge-records).
+ *
+ * @param {Object} body (required) - Request body
+ *
+ * @returns {Promise<Object>} POST /crm/v3/objects/companies/merge response
+   */
+  async merge(body?: any) {
+    const url = '/crm/v3/objects/companies/merge';
+    const options: any = {
+      method: 'POST',
+      body,
+    };
+
+    return this.api.fetch(url, options);
+  }
+}