@aloma.io/integration-sdk 3.8.55 → 3.8.56

package/MULTI_RESOURCE_GUIDE.md

@@ -13,26 +13,27 @@ src/
 ├── controller/
 │   └── index.mts          # Main controller (extends AbstractController)
 └── resources/
-    ├── companies.mts      # CompaniesResource (plain class)
-    ├── contacts.mts       # ContactsResource (plain class)
-    └── lists.mts          # ListsResource (plain class)
+    ├── companies.mts      # Companies resource functions
+    ├── contacts.mts       # Contacts resource functions
+    └── lists.mts          # Lists resource functions
 ```
 
 ### Main Controller
 - Extends `AbstractController`
 - Has `private api: any` and `protected async start()`
-- Composes all resources
-- Initializes API client once
+- Binds resource functions to controller context with `function.bind(this)`
+- Initializes API client once and provides context to bound functions
 
-### Resource Classes
-- Plain TypeScript classes (no inheritance)
-- Receive controller reference in constructor
-- Access `api` via getter: `this.controller['api']`
+### Resource Functions (New Pattern!)
+- Plain TypeScript exported functions (no classes)
+- Bound to controller context using `function.bind(this)`
+- Access `api` directly via `this.api` (bound context)
 - Focus on their specific domain
+- Enable proper API introspection by the framework
 
 ## Creating Multi-Resource Connectors
 
-### 1. Create from Multiple OpenAPI Specs
+### 1. Generate Base Controller (Functions Pattern)
 
 ```bash
 npx @aloma.io/integration-sdk@latest create-multi-resource "MyConnector" \
@@ -42,7 +43,7 @@ npx @aloma.io/integration-sdk@latest create-multi-resource "MyConnector" \
 ```
 
 **Parameters:**
-- `--resources`: Comma-separated list of `ClassName:specFile` pairs
+- `--resources`: Comma-separated list of `ResourceName:specFile` pairs
 - `--base-url`: API base URL (optional, extracted from first spec if not provided)
 - `--no-build`: Skip dependency installation and building
 
@@ -72,12 +73,13 @@ The `--resources` parameter accepts a comma-separated list in this format:
 ```bash
 npx @aloma.io/integration-sdk@latest add-resource ./existing-project \
   --className "DealsResource" \
-  --spec "deals.json"
+  --spec "deals.json" \
+  --no-build
 ```
 
 This will:
-- Generate the new resource class
-- Save it to `src/resources/deals.mts`
+- Generate the new resource functions
+- Save them to `src/resources/deals.mts`
 - Provide instructions for updating the main controller
 
 ### 2. Update Main Controller Manually
@@ -86,13 +88,13 @@ After adding a resource, you need to update the main controller:
 
 ```typescript
 // 1. Add import
-import DealsResource from '../resources/deals.mjs';
+import * as dealsResource from '../resources/deals.mjs';
 
 // 2. Add property
-deals!: DealsResource;
+deals!: typeof dealsResource;
 
 // 3. Add initialization in start()
-this.deals = new DealsResource(this);
+this.deals = this.bindResourceFunctions(dealsResource);
 ```
 
 ## Usage Examples
@@ -147,9 +149,9 @@ await controller.companies.getPage({
 ## Best Practices
 
 ### 1. Resource Naming
-- Use descriptive class names: `CompaniesResource`, `ContactsResource`
+- Use descriptive resource names: `CompaniesResource`, `ContactsResource`
 - File names are auto-generated: `companies.mts`, `contacts.mts`
-- Property names in controller: `companies`, `contacts`
+- Property names in controller (bound functions): `companies`, `contacts`
 
 ### 2. OpenAPI Specifications
 - Each resource should have its own focused OpenAPI spec
@@ -193,9 +195,10 @@ If you see TypeScript errors about missing file extensions:
 - Ensure you're using `.mjs` extensions in imports
 - The generator handles this automatically in new projects
 
-### Resource Not Found
+### Resource Functions Not Found
 If a resource property is undefined:
-- Check that the resource is properly initialized in `start()`
+- Check that the resource functions are properly bound in `start()`
+- Ensure `bindResourceFunctions()` was called correctly
 - Verify the import path in the main controller
 - Ensure the resource file was generated correctly
 

package/OPENAPI_TO_CONNECTOR.md

@@ -4,13 +4,30 @@ A deterministic script that generates Aloma connector controllers from OpenAPI 3
 
 ## Features
 
+### Core Generation
 - ✅ **Deterministic**: Same OpenAPI input always produces the same connector definition
 - ✅ **No LLM involvement**: Pure parsing and code generation
 - ✅ **OpenAPI 3.x support**: Validates against OpenAPI 3.x schema
 - ✅ **JSON & YAML support**: Handles both JSON and YAML OpenAPI specifications
 - ✅ **Comprehensive coverage**: Generates methods for all endpoints and operations
-- ✅ **Rich documentation**: Uses OpenAPI descriptions and summaries for JSDoc comments
-- ✅ **Parameter mapping**: Maps OpenAPI parameters to method arguments
+
+### TypeScript & Code Quality
+- ✅ **TypeScript Interface Generation**: Automatically generates interfaces from OpenAPI schemas
+- ✅ **Schema Name Sanitization**: Converts invalid names (e.g., `Complex.Name.With.Dots` → `Complex_Name_With_Dots`)
+- ✅ **Clean Parameter Handling**: No unnecessary options parameters for simple methods
+- ✅ **Path Parameter Separation**: Discrete path parameters with optional options object
+- ✅ **Inline Body Construction**: Direct body building without helper methods
+
+### Documentation & Usability
+- ✅ **Rich JSDoc Generation**: Detailed documentation with parameter descriptions and examples
+- ✅ **Schema Field Documentation**: Documents response object fields and properties
+- ✅ **Parameter Type Documentation**: Includes TypeScript types in JSDoc comments
+- ✅ **Controller-Only Mode**: Generate just the controller file for existing projects
+
+### Architecture Support
+- ✅ **Multi-Resource Architecture**: Support for complex APIs with multiple resource groups
+- ✅ **Resource Function Pattern**: Functions bound to controller context for proper introspection
+- ✅ **API Introspection**: Exposed methods for framework compatibility
 - ✅ **Error handling**: Clear error messages for invalid specifications
 
 ## Installation
@@ -39,6 +56,19 @@ npx @aloma.io/integration-sdk@latest from-openapi "My Connector" --connector-id
 
 # With custom output path
 npx @aloma.io/integration-sdk@latest from-openapi "My Connector" --connector-id "my-connector-123" --spec api.yaml --out src/controller/index.mts
+
+# Controller-only mode (NEW!) - Generate just the controller file
+npx @aloma.io/integration-sdk@latest from-openapi "My Connector" \
+  --connector-id "my-connector-123" \
+  --spec api.yaml \
+  --controller-only \
+  --out "./src/controller/index.mts"
+
+# Multi-resource connector
+npx @aloma.io/integration-sdk@latest create-multi-resource "My Connector" \
+  --connector-id "my-connector-123" \
+  --resources "ProductsResource:products.json,OrdersResource:orders.json" \
+  --base-url "https://api.example.com"
 ```
 
 #### Options
@@ -47,6 +77,9 @@ npx @aloma.io/integration-sdk@latest from-openapi "My Connector" --connector-id
 - `--connector-id <id>` (required): ID of the connector
 - `--spec <file>` (required): OpenAPI specification file (JSON or YAML)
 - `--out <file>` (optional): Output file path for the controller (default: `src/controller/index.mts`)
+- `--controller-only` (optional): Generate only the controller file, no project structure
+- `--resource <className>` (optional): Generate as a resource class instead of controller
+- `--no-build` (optional): Skip installing dependencies and building the project
 
 ### Standalone Script Usage
 
@@ -116,29 +149,94 @@ paths:
 ```typescript
 import {AbstractController} from '@aloma.io/integration-sdk';
 
+// Generated TypeScript interfaces from OpenAPI schemas
+
+export interface User {
+  id: string;
+  name: string;
+  email?: string;
+  createdAt: string;
+}
+
+export interface UserList {
+  users: User[];
+  total: number;
+  hasMore: boolean;
+}
+
 export default class Controller extends AbstractController {
   
+  private api: any;
+
+  protected async start(): Promise<void> {
+    const config = this.config;
+    
+    this.api = this.getClient({
+      baseUrl: 'https://api.example.com',
+      customize(request) {
+        request.headers ||= {};
+        // Add authentication headers based on your API requirements
+        // Example: request.headers["Authorization"] = `Bearer ${config.apiToken}`;
+      },
+    });
+  }
+
   /**
    * List all users
    *
-   * @param args - Request arguments
-   * @param args.page - Page number for pagination
-   * @returns Response data
+   * @param {Object} options - Request options
+   * @param {number} options.page (optional) - Page number for pagination [query]
+   *
+   * @returns {Promise<UserList>} GET /users response
+   *
+   * response fields:
+   * - users: User[] - Array of user objects
+   * - total: number - Total number of users
+   * - hasMore: boolean - Whether there are more users available
    */
-  async listUsers(args: any) {
-    // TODO: Implement GET /users
-    throw new Error('Method not implemented');
+  async listUsers(options?: {page?: number}) {
+    options = options || {};
+
+    const url = '/users';
+
+    const fetchOptions: any = {
+      method: 'GET',
+      params: {},
+      headers: options.headers,
+    };
+
+    // Add query parameters
+    if (options.page !== undefined) {
+      fetchOptions.params.page = options.page;
+    }
+
+    return this.api.fetch(url, fetchOptions);
   }
 
   /**
    * Create user
    *
-   * @param args.body - Request body
-   * @returns Response data
+   * @param {Object} options - Request options
+   * @param {string} options.name (required) - User's full name [body property]
+   * @param {string} options.email (optional) - User's email address [body property]
+   *
+   * @returns {Promise<User>} POST /users response
    */
-  async createUser(args: any) {
-    // TODO: Implement POST /users
-    throw new Error('Method not implemented');
+  async createUser(options: {name: string, email?: string}) {
+    options = options || {};
+
+    const url = '/users';
+
+    const { headers, ...bodyData } = options;
+    const requestBody = Object.keys(bodyData).length > 0 ? bodyData : undefined;
+
+    const fetchOptions: any = {
+      method: 'POST',
+      body: requestBody,
+      headers: options.headers,
+    };
+
+    return this.api.fetch(url, fetchOptions);
   }
 }
 ```
@@ -180,17 +278,49 @@ The script provides clear error messages for:
 
 ## Testing
 
-Run the included tests:
+### Comprehensive Scenario Tests
+
+The SDK includes comprehensive scenario tests that verify the complete code generation pipeline:
 
 ```bash
-npm test
+# Run all scenario tests with fixtures
+npm run test:scenarios
+
+# Run all tests (including unit tests)
+npm run test:all
 ```
 
-Or test manually:
+### Test Coverage
+
+The scenario tests verify:
+- ✅ **Complete code generation** from OpenAPI specs to connector code
+- ✅ **TypeScript interface generation** with proper schema sanitization
+- ✅ **Clean parameter handling** (no unnecessary options for simple methods)
+- ✅ **Multi-resource architecture** with resource binding and exposure
+- ✅ **Schema name sanitization** (e.g., `Complex.Name.With.Dots` → `Complex_Name_With_Dots`)
+- ✅ **Path parameter separation** from options object
+- ✅ **JSDoc generation** with detailed parameter documentation
+- ✅ **Regression protection** against common code generation issues
+
+### Test Scenarios
+- **Simple Scenario**: Basic single-controller generation using `examples/simple-api.json`
+- **Complex Scenario**: Multi-resource generation with Products + Orders APIs
+- **Regression Tests**: Edge cases, schema sanitization, and clean code generation
+
+All tests compare generated output against fixtures to ensure deterministic, high-quality code generation.
+
+### Manual Testing
 
 ```bash
 # Test with sample API
 node ./build/openapi-to-connector.mjs generate --name "Sample API" --spec ./examples/sample-api.yaml --out ./test-output.mts
+
+# Test controller-only mode
+node build/cli.mjs from-openapi test-connector \
+  --connector-id "test" \
+  --spec "examples/simple-api.json" \
+  --controller-only \
+  --out "./test-controller.mts"
 ```
 
 ## Requirements Met

package/README.md

@@ -1,8 +1,19 @@
 # nodejs - Aloma Integration SDK
 
-## Creating a new Connector
+A powerful toolkit for generating production-ready Aloma connectors from OpenAPI specifications with advanced features like multi-resource architecture, TypeScript type generation, and comprehensive testing.
 
-With the aloma integration SDK cli you can create a new connector in three ways:
+## ✨ Key Features
+
+- 🎯 **Deterministic Code Generation** - Same input always produces the same output
+- 🔧 **Multi-Resource Architecture** - Organize large APIs into logical resource groups
+- 📘 **TypeScript First** - Full TypeScript support with proper interface generation
+- 🧪 **Comprehensive Testing** - Built-in scenario tests with fixtures
+- 🔍 **Schema Sanitization** - Converts invalid TypeScript names to valid identifiers
+- 📝 **Rich Documentation** - Detailed JSDoc generation from OpenAPI descriptions
+- 🎨 **Clean Code Generation** - No unnecessary parameters or boilerplate
+- 📦 **Controller-Only Mode** - Generate just the controller for existing projects
+
+## 🚀 Quick Start
 
 ### 1. Create from scratch
 ```bash
@@ -11,12 +22,25 @@ npx @aloma.io/integration-sdk@latest create connectorName --connector-id 1234
 
 ### 2. Generate from OpenAPI specification
 ```bash
-npx @aloma.io/integration-sdk@latest from-openapi connectorName --connector-id 1234 --spec api.yaml
+npx @aloma.io/integration-sdk@latest from-openapi connectorName --connector-id 1234 --spec api.yaml --no-build
 ```
 
-This will automatically generate a complete connector project with methods for all OpenAPI endpoints, ready for implementation.
+This will automatically generate a complete connector project with:
+- Methods for all OpenAPI endpoints
+- Proper TypeScript interfaces from schemas
+- Clean parameter handling (no unnecessary options)
+- Rich JSDoc documentation
+
+### 3. Controller-Only Generation (New!)
+```bash
+# Generate just the controller file for existing projects
+npx @aloma.io/integration-sdk@latest from-openapi connectorName \
+  --connector-id 1234 \
+  --spec api.yaml \
+  --controller-only \
+  --out "./src/controller/index.mts"
+```
 
-### 3. Generate with Resource Architecture (Recommended for large APIs)
 ```bash
 npx @aloma.io/integration-sdk@latest from-openapi connectorName \
   --connector-id 1234 \
@@ -26,12 +50,13 @@ npx @aloma.io/integration-sdk@latest from-openapi connectorName \
   --no-build
 ```
 
-### 4. Create Multi-Resource Connector (Recommended for complex APIs)
+### 5. Create Multi-Resource Connector (Recommended for complex APIs)
 ```bash
 npx @aloma.io/integration-sdk@latest create-multi-resource "HubSpot-v2" \
   --connector-id "hubspot-123" \
   --resources "CompaniesResource:examples/hubspot-companies.json,ContactsResource:examples/hubspot-contacts.json,ListsResource:examples/hubspot-lists.json" \
-  --base-url "https://api.hubapi.com"
+  --base-url "https://api.hubapi.com" \
+  --no-build
 ```
 
 This creates a complete multi-resource connector with:
@@ -46,15 +71,41 @@ await controller.contacts.getPage({ limit: 10 });
 await controller.lists.getAll({ limit: 50 });
 ```
 
-### 5. Add Resource to Existing Project
+### 6. Add Resource to Existing Project
 ```bash
 npx @aloma.io/integration-sdk@latest add-resource ./existing-project \
   --className "DealsResource" \
-  --spec "deals.json"
+  --spec "deals.json" \
+  --no-build
 ```
 
 This adds a new resource to an existing multi-resource connector.
 
+## 🧪 Testing & Quality
+
+### Run Scenario Tests
+```bash
+# Run comprehensive scenario tests with fixtures
+npm run test:scenarios
+
+# Run all tests
+npm run test:all
+```
+
+The SDK includes comprehensive scenario tests that verify:
+- ✅ **Complete code generation pipeline** from OpenAPI specs to connector code
+- ✅ **TypeScript interface generation** with schema sanitization
+- ✅ **Clean parameter handling** (no unnecessary options for simple methods)
+- ✅ **Multi-resource architecture** with proper resource binding
+- ✅ **Regression protection** against common code generation issues
+
+### Test Scenarios
+- **Simple Scenario**: Basic single-controller generation
+- **Complex Scenario**: Multi-resource generation with Products + Orders APIs
+- **Regression Tests**: Edge cases and schema sanitization
+
+All tests use real OpenAPI specifications and compare generated output against fixtures to ensure deterministic, high-quality code generation.
+
 ## 📚 Documentation
 
 - **[OPENAPI_TO_CONNECTOR.md](./OPENAPI_TO_CONNECTOR.md)** - OpenAPI generator details
@@ -67,6 +118,7 @@ This adds a new resource to an existing multi-resource connector.
 # Create complete HubSpot connector with 3 resources
 npx @aloma.io/integration-sdk@latest create-multi-resource "HubSpot-v2" \
   --connector-id "hubspot-123" \
-  --resources "CompaniesResource:examples/hubspot-companies.json,ContactsResource:examples/hubspot-contacts.json,ListsResource:examples/hubspot-lists.json"
+  --resources "CompaniesResource:examples/hubspot-companies.json,ContactsResource:examples/hubspot-contacts.json,ListsResource:examples/hubspot-lists.json" \
+  --no-build
 
 ```