@aloma.io/integration-sdk 3.8.55 → 3.8.56

package/test/scenarios/README.md

@@ -0,0 +1,148 @@
+# Scenario Tests
+
+This directory contains full scenario tests that verify the complete code generation pipeline from OpenAPI specifications to generated connector code.
+
+## Purpose
+
+These tests ensure that:
+1. Generated code exactly matches expected fixtures
+2. All features work correctly end-to-end
+3. Regressions are caught immediately
+4. Code generation is deterministic and consistent
+
+## Structure
+
+```
+test/scenarios/
+├── README.md                          # This file
+├── simple/                            # Simple single-controller scenario
+│   ├── simple-api.json               # Input OpenAPI spec (copied from examples/)
+│   └── expected-controller.mts       # Expected generated controller output
+└── complex/                          # Complex multi-resource scenario
+    ├── specs/                        # Input OpenAPI specs
+    │   ├── products.json            # Products API specification
+    │   └── orders.json              # Orders API specification
+    └── expected/                     # Expected generated outputs
+        ├── controller.mts           # Expected main controller
+        ├── products-resource.mts    # Expected products resource functions
+        └── orders-resource.mts      # Expected orders resource functions
+```
+
+## Scenarios
+
+### Simple Scenario
+
+**Input**: `simple/simple-api.json`
+- Basic Products API with 2 endpoints
+- Tests single-controller generation (`from-openapi` command)
+- Verifies methods without options don't have unnecessary code
+
+**Expected Output**: `simple/expected-controller.mts`
+- Clean controller with proper TypeScript types
+- Methods without options parameters are minimal
+- Methods with options have proper signatures
+
+### Complex Scenario
+
+**Inputs**: 
+- `complex/specs/products.json` - Products management API (5 endpoints)
+- `complex/specs/orders.json` - Orders management API (5 endpoints)
+
+**Tests multi-resource generation** (`create-multi-resource` command):
+- Resource function generation
+- Main controller with exposed methods
+- Resource binding and composition
+- Complex TypeScript interface generation
+- Path parameter handling
+
+**Expected Outputs**:
+- `complex/expected/controller.mts` - Main controller with resource bindings
+- `complex/expected/products-resource.mts` - Products resource functions
+- `complex/expected/orders-resource.mts` - Orders resource functions
+
+## Test Coverage
+
+The scenario tests verify:
+
+### Core Functionality
+- ✅ Single controller generation (`from-openapi`)
+- ✅ Multi-resource generation (`create-multi-resource`)
+- ✅ TypeScript interface generation from schemas
+- ✅ Method signature generation (path params + options)
+- ✅ JSDoc comment generation
+
+### Quality Features
+- ✅ Schema name sanitization (dots → underscores)
+- ✅ Clean code generation (no unnecessary options)
+- ✅ Resource method exposure in main controller
+- ✅ Path parameter vs options separation
+- ✅ Request body inline construction
+
+### Regression Protection
+- ✅ Invalid TypeScript interface names
+- ✅ Unnecessary options parameter in simple methods
+- ✅ Missing headers property access
+- ✅ Circular schema reference handling
+
+## Running Tests
+
+```bash
+# Run scenario tests only
+npm run test:scenarios
+
+# Run all tests
+npm run test:all
+
+# Direct execution
+node test/verify-scenarios.mjs
+```
+
+## Updating Fixtures
+
+When code generation logic changes, you may need to update the expected fixtures:
+
+### Simple Scenario
+```bash
+# Regenerate expected output
+node build/cli.mjs from-openapi simple-test \
+  --connector-id "simple-test" \
+  --spec "test/scenarios/simple/simple-api.json" \
+  --controller-only \
+  --out "test/scenarios/simple/expected-controller.mts"
+```
+
+### Complex Scenario
+```bash
+# Regenerate multi-resource outputs
+node build/cli.mjs create-multi-resource \
+  --connector-id "test-shop" \
+  --resources "ProductsResource:test/scenarios/complex/specs/products.json,OrdersResource:test/scenarios/complex/specs/orders.json" \
+  --base-url "https://api.testshop.com" \
+  --no-build test-shop-temp
+
+# Copy to expected fixtures
+cp test-shop-temp/src/controller/index.mts test/scenarios/complex/expected/controller.mts
+cp test-shop-temp/src/resources/products.mts test/scenarios/complex/expected/products-resource.mts
+cp test-shop-temp/src/resources/orders.mts test/scenarios/complex/expected/orders-resource.mts
+
+# Cleanup
+rm -rf test-shop-temp
+```
+
+## Benefits
+
+1. **Confidence**: Any change to code generation is immediately tested against real scenarios
+2. **Documentation**: Fixtures serve as examples of expected output
+3. **Regression Prevention**: Prevents accidental breaking changes
+4. **Quality Assurance**: Ensures generated code meets quality standards
+5. **Debugging**: Easy to compare actual vs expected output when tests fail
+
+## API Examples
+
+The test scenarios use realistic API examples:
+
+- **Simple API**: Basic product CRUD operations
+- **Products API**: Product management with categories, pricing, inventory
+- **Orders API**: Order lifecycle management with status updates, addresses
+
+These examples demonstrate real-world usage patterns and edge cases that the code generator must handle correctly.

package/test/scenarios/complex/expected/controller.mts

@@ -0,0 +1,271 @@
+import {AbstractController} from '@aloma.io/integration-sdk';
+import * as productsFunctions from '../resources/products.mjs';
+import * as ordersFunctions from '../resources/orders.mjs';
+
+export default class Controller extends AbstractController {
+  products: any = {};
+  orders: any = {};
+
+  private api: any;
+
+  protected async start(): Promise<void> {
+    const config = this.config;
+    
+    this.api = this.getClient({
+      baseUrl: 'https://api.testshop.com',
+      customize(request) {
+        request.headers ||= {};
+        // Add authentication headers based on your API requirements
+        // Example: request.headers["Authorization"] = `Bearer ${config.apiToken}`;
+      },
+    });
+    
+    // Bind resource functions to this controller context
+    // This allows using this.resourceName.method() syntax
+    this.bindResourceFunctions('products', productsFunctions);
+    this.bindResourceFunctions('orders', ordersFunctions);
+  }
+
+  private bindResourceFunctions(resourceName: string, functions: any) {
+    for (const [functionName, func] of Object.entries(functions)) {
+      if (typeof func === 'function') {
+        this[resourceName][functionName] = func.bind(this);
+      }
+    }
+  }
+
+  /**
+   * Generic API request method
+   * @param url - API endpoint
+   * @param options - Request options
+   */
+  async request({ url, options }: { url: string; options?: any }) {
+    return this.api.fetch(url, options);
+  }
+
+  /**
+ * List all products
+ *
+ * @param {Object} options - Request options
+ * @param {number} options.limit (optional) - Maximum number of products to return [query]
+ * @param {string} options.category (optional) - Filter by category [query]
+ * @param {boolean} options.archived (optional) - Include archived products [query]
+ *
+ * @returns {Promise<ProductList>} GET /products response
+ *
+ * response fields:
+ * - products?: Product[]
+ * - total?: number - Total number of products
+ * - hasMore?: boolean - Whether there are more products available
+   */
+  async productsGetProducts(options?: {limit?: number, category?: string, archived?: boolean}) {
+    return this.products.getProducts(options);
+  }
+
+  /**
+ * Create a new product
+ *
+ * @param {Object} options - Request options
+ * @param {string} options.name (required) - Product name [body property]
+ * @param {string} options.description (required) - Product description [body property]
+ * @param {number} options.price (required) - Product price [body property]
+ * @param {string} options.category (required) - Product category [body property]
+ * @param {string[]} options.tags (required) - Product tags [body property]
+ *
+ * @returns {Promise<Product>} POST /products response
+ *
+ * response fields:
+ * - id: string - Unique product identifier
+ * - name: string - Product name
+ * - description?: string - Product description
+ * - price: number - Product price
+ * - category?: string - Product category
+ * - inStock?: boolean - Whether product is in stock
+ * - tags?: string[] - Product tags
+ * - createdAt?: string - Creation timestamp
+ * - updatedAt?: string - Last update timestamp
+   */
+  async productsCreateProduct(options: {name: string /** Product name */, description: string /** Product description */, price: number /** Product price */, category: string /** Product category */, tags: string[] /** Product tags */}) {
+    return this.products.createProduct(options);
+  }
+
+  /**
+ * Get a specific product
+ *
+ * @param {string} productId The product ID
+ * @param {Object} options (optional) - Request options
+ *
+ * @returns {Promise<Product>} GET /products/{productId} response
+ *
+ * response fields:
+ * - id: string - Unique product identifier
+ * - name: string - Product name
+ * - description?: string - Product description
+ * - price: number - Product price
+ * - category?: string - Product category
+ * - inStock?: boolean - Whether product is in stock
+ * - tags?: string[] - Product tags
+ * - createdAt?: string - Creation timestamp
+ * - updatedAt?: string - Last update timestamp
+   */
+  async productsGetProduct(productId: string) {
+    return this.products.getProduct(productId);
+  }
+
+  /**
+ * Update a product
+ *
+ * @param {string} productId The product ID
+ * @param {Object} options - Request options
+ * @param {string} options.name (required) - Product name [body property]
+ * @param {string} options.description (required) - Product description [body property]
+ * @param {number} options.price (required) - Product price [body property]
+ * @param {string} options.category (required) - Product category [body property]
+ * @param {boolean} options.inStock (required) - Whether product is in stock [body property]
+ * @param {string[]} options.tags (required) - Product tags [body property]
+ *
+ * @returns {Promise<Product>} PUT /products/{productId} response
+ *
+ * response fields:
+ * - id: string - Unique product identifier
+ * - name: string - Product name
+ * - description?: string - Product description
+ * - price: number - Product price
+ * - category?: string - Product category
+ * - inStock?: boolean - Whether product is in stock
+ * - tags?: string[] - Product tags
+ * - createdAt?: string - Creation timestamp
+ * - updatedAt?: string - Last update timestamp
+   */
+  async productsUpdateProduct(productId: string, options: {name: string /** Product name */, description: string /** Product description */, price: number /** Product price */, category: string /** Product category */, inStock: boolean /** Whether product is in stock */, tags: string[] /** Product tags */}) {
+    return this.products.updateProduct(productId, options);
+  }
+
+  /**
+ * Delete a product
+ *
+ * @param {string} productId The product ID
+ * @param {Object} options (optional) - Request options
+ *
+ * @returns {Promise<any>} DELETE /products/{productId} response
+   */
+  async productsDeleteProduct(productId: string) {
+    return this.products.deleteProduct(productId);
+  }
+
+  /**
+ * List all orders
+ *
+ * @param {Object} options - Request options
+ * @param {string} options.status (optional) - Filter by order status [query]
+ * @param {string} options.customerId (optional) - Filter by customer ID [query]
+ * @param {number} options.limit (optional) - Maximum number of orders to return [query]
+ *
+ * @returns {Promise<OrderList>} GET /orders response
+ *
+ * response fields:
+ * - orders?: Order[]
+ * - total?: number - Total number of orders
+ * - hasMore?: boolean - Whether there are more orders available
+   */
+  async ordersGetOrders(options?: {status?: string, customerId?: string, limit?: number}) {
+    return this.orders.getOrders(options);
+  }
+
+  /**
+ * Create a new order
+ *
+ * @param {Object} options - Request options
+ * @param {string} options.customerId (required) - Customer who is placing the order [body property]
+ * @param {OrderItemRequest[]} options.items (required) - Items to order [body property]
+ * @param {Address} options.shippingAddress (required) -  [body property]
+ * @param {Address} options.billingAddress (required) -  [body property]
+ *
+ * @returns {Promise<Order>} POST /orders response
+ *
+ * response fields:
+ * - id: string - Unique order identifier
+ * - customerId: string - Customer who placed the order
+ * - items: OrderItem[] - Items in the order
+ * - status: string - Current order status
+ * - totalAmount: number - Total order amount
+ * - shippingAddress?: Address
+ * - billingAddress?: Address
+ * - createdAt?: string - Order creation timestamp
+ * - updatedAt?: string - Last update timestamp
+   */
+  async ordersCreateOrder(options: {customerId: string /** Customer who is placing the order */, items: OrderItemRequest[] /** Items to order */, shippingAddress: Address, billingAddress: Address}) {
+    return this.orders.createOrder(options);
+  }
+
+  /**
+ * Get a specific order
+ *
+ * @param {string} orderId The order ID
+ * @param {Object} options (optional) - Request options
+ *
+ * @returns {Promise<Order>} GET /orders/{orderId} response
+ *
+ * response fields:
+ * - id: string - Unique order identifier
+ * - customerId: string - Customer who placed the order
+ * - items: OrderItem[] - Items in the order
+ * - status: string - Current order status
+ * - totalAmount: number - Total order amount
+ * - shippingAddress?: Address
+ * - billingAddress?: Address
+ * - createdAt?: string - Order creation timestamp
+ * - updatedAt?: string - Last update timestamp
+   */
+  async ordersGetOrder(orderId: string) {
+    return this.orders.getOrder(orderId);
+  }
+
+  /**
+ * Update order status
+ *
+ * @param {string} orderId The order ID
+ * @param {Object} options - Request options
+ * @param {string} options.status (required) - New order status [body property]
+ * @param {string} options.trackingNumber (required) - Tracking number (for shipped status) [body property]
+ *
+ * @returns {Promise<Order>} PATCH /orders/{orderId} response
+ *
+ * response fields:
+ * - id: string - Unique order identifier
+ * - customerId: string - Customer who placed the order
+ * - items: OrderItem[] - Items in the order
+ * - status: string - Current order status
+ * - totalAmount: number - Total order amount
+ * - shippingAddress?: Address
+ * - billingAddress?: Address
+ * - createdAt?: string - Order creation timestamp
+ * - updatedAt?: string - Last update timestamp
+   */
+  async ordersUpdateOrderStatus(orderId: string, options: {status: string /** New order status */, trackingNumber: string /** Tracking number (for shipped status) */}) {
+    return this.orders.updateOrderStatus(orderId, options);
+  }
+
+  /**
+ * Cancel an order
+ *
+ * @param {string} orderId The order ID
+ * @param {Object} options (optional) - Request options
+ *
+ * @returns {Promise<Order>} POST /orders/{orderId}/cancel response
+ *
+ * response fields:
+ * - id: string - Unique order identifier
+ * - customerId: string - Customer who placed the order
+ * - items: OrderItem[] - Items in the order
+ * - status: string - Current order status
+ * - totalAmount: number - Total order amount
+ * - shippingAddress?: Address
+ * - billingAddress?: Address
+ * - createdAt?: string - Order creation timestamp
+ * - updatedAt?: string - Last update timestamp
+   */
+  async ordersCancelOrder(orderId: string) {
+    return this.orders.cancelOrder(orderId);
+  }
+}

package/test/scenarios/complex/expected/orders-resource.mts

@@ -0,0 +1,264 @@
+// OrdersResource resource functions
+// These functions will be bound to the controller instance and accessible as orders.method()
+
+// Generated TypeScript interfaces from OpenAPI schemas
+
+export interface Order {
+  /** Unique order identifier */
+  id: string;
+  /** Customer who placed the order */
+  customerId: string;
+  /** Items in the order */
+  items: OrderItem[];
+  /** Current order status */
+  status: string;
+  /** Total order amount */
+  totalAmount: number;
+  shippingAddress?: Address;
+  billingAddress?: Address;
+  /** Order creation timestamp */
+  createdAt?: string;
+  /** Last update timestamp */
+  updatedAt?: string;
+}
+
+export interface OrderItem {
+  /** Product identifier */
+  productId: string;
+  /** Product name */
+  productName?: string;
+  /** Quantity ordered */
+  quantity: number;
+  /** Price per unit */
+  unitPrice: number;
+  /** Total price for this item */
+  totalPrice?: number;
+}
+
+export interface Address {
+  /** Street address */
+  street: string;
+  /** City */
+  city: string;
+  /** State or province */
+  state?: string;
+  /** ZIP or postal code */
+  zipCode: string;
+  /** Country */
+  country: string;
+}
+
+export interface OrderList {
+  orders?: Order[];
+  /** Total number of orders */
+  total?: number;
+  /** Whether there are more orders available */
+  hasMore?: boolean;
+}
+
+export interface CreateOrderRequest {
+  /** Customer who is placing the order */
+  customerId: string;
+  /** Items to order */
+  items: OrderItemRequest[];
+  shippingAddress?: Address;
+  billingAddress?: Address;
+}
+
+export interface OrderItemRequest {
+  /** Product to order */
+  productId: string;
+  /** Quantity to order */
+  quantity: number;
+}
+
+export interface UpdateOrderStatusRequest {
+  /** New order status */
+  status: string;
+  /** Tracking number (for shipped status) */
+  trackingNumber?: string;
+}
+
+
+/**
+ * List all orders
+ *
+ * @param {Object} options - Request options
+ * @param {string} options.status (optional) - Filter by order status [query]
+ * @param {string} options.customerId (optional) - Filter by customer ID [query]
+ * @param {number} options.limit (optional) - Maximum number of orders to return [query]
+ *
+ * @returns {Promise<OrderList>} GET /orders response
+ *
+ * response fields:
+ * - orders?: Order[]
+ * - total?: number - Total number of orders
+ * - hasMore?: boolean - Whether there are more orders available
+ */
+export function getOrders(this: any, options?: {status?: string, customerId?: string, limit?: number}) {
+  options = options || {};
+
+  const url = '/orders';
+
+  const fetchOptions: any = {
+    method: 'GET',
+    params: {},
+    headers: options.headers,
+  };
+
+  // Add query parameters
+  if (options.status !== undefined) {
+    fetchOptions.params.status = options.status;
+  }
+  if (options.customerId !== undefined) {
+    fetchOptions.params.customerId = options.customerId;
+  }
+  if (options.limit !== undefined) {
+    fetchOptions.params.limit = options.limit;
+  }
+
+    return this.api.fetch(url, fetchOptions);
+}
+
+/**
+ * Create a new order
+ *
+ * @param {Object} options - Request options
+ * @param {string} options.customerId (required) - Customer who is placing the order [body property]
+ * @param {OrderItemRequest[]} options.items (required) - Items to order [body property]
+ * @param {Address} options.shippingAddress (required) -  [body property]
+ * @param {Address} options.billingAddress (required) -  [body property]
+ *
+ * @returns {Promise<Order>} POST /orders response
+ *
+ * response fields:
+ * - id: string - Unique order identifier
+ * - customerId: string - Customer who placed the order
+ * - items: OrderItem[] - Items in the order
+ * - status: string - Current order status
+ * - totalAmount: number - Total order amount
+ * - shippingAddress?: Address
+ * - billingAddress?: Address
+ * - createdAt?: string - Order creation timestamp
+ * - updatedAt?: string - Last update timestamp
+ */
+export function createOrder(this: any, options: {customerId: string /** Customer who is placing the order */, items: OrderItemRequest[] /** Items to order */, shippingAddress: Address, billingAddress: Address}) {
+  options = options || {};
+
+  const url = '/orders';
+
+  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);
+}
+
+/**
+ * Get a specific order
+ *
+ * @param {string} orderId The order ID
+ * @param {Object} options (optional) - Request options
+ *
+ * @returns {Promise<Order>} GET /orders/{orderId} response
+ *
+ * response fields:
+ * - id: string - Unique order identifier
+ * - customerId: string - Customer who placed the order
+ * - items: OrderItem[] - Items in the order
+ * - status: string - Current order status
+ * - totalAmount: number - Total order amount
+ * - shippingAddress?: Address
+ * - billingAddress?: Address
+ * - createdAt?: string - Order creation timestamp
+ * - updatedAt?: string - Last update timestamp
+ */
+export function getOrder(this: any, orderId: string) {
+  let url = '/orders/{orderId}';
+  if (orderId) {
+    url = url.replace('{orderId}', orderId);
+  }
+
+  return this.api.fetch(url, {
+    method: 'GET',
+  });
+    return this.api.fetch(url, fetchOptions);
+}
+
+/**
+ * Update order status
+ *
+ * @param {string} orderId The order ID
+ * @param {Object} options - Request options
+ * @param {string} options.status (required) - New order status [body property]
+ * @param {string} options.trackingNumber (required) - Tracking number (for shipped status) [body property]
+ *
+ * @returns {Promise<Order>} PATCH /orders/{orderId} response
+ *
+ * response fields:
+ * - id: string - Unique order identifier
+ * - customerId: string - Customer who placed the order
+ * - items: OrderItem[] - Items in the order
+ * - status: string - Current order status
+ * - totalAmount: number - Total order amount
+ * - shippingAddress?: Address
+ * - billingAddress?: Address
+ * - createdAt?: string - Order creation timestamp
+ * - updatedAt?: string - Last update timestamp
+ */
+export function updateOrderStatus(this: any, orderId: string, options: {status: string /** New order status */, trackingNumber: string /** Tracking number (for shipped status */})) {
+  options = options || {};
+
+  // Build URL with path parameters
+  let url = '/orders/{orderId}';
+  if (orderId) {
+    url = url.replace('{orderId}', orderId);
+  }
+
+  const { headers, ...bodyData } = options;
+  const requestBody = Object.keys(bodyData).length > 0 ? bodyData : undefined;
+
+  const fetchOptions: any = {
+    method: 'PATCH',
+    body: requestBody,
+    headers: options.headers,
+  };
+
+    return this.api.fetch(url, fetchOptions);
+}
+
+/**
+ * Cancel an order
+ *
+ * @param {string} orderId The order ID
+ * @param {Object} options (optional) - Request options
+ *
+ * @returns {Promise<Order>} POST /orders/{orderId}/cancel response
+ *
+ * response fields:
+ * - id: string - Unique order identifier
+ * - customerId: string - Customer who placed the order
+ * - items: OrderItem[] - Items in the order
+ * - status: string - Current order status
+ * - totalAmount: number - Total order amount
+ * - shippingAddress?: Address
+ * - billingAddress?: Address
+ * - createdAt?: string - Order creation timestamp
+ * - updatedAt?: string - Last update timestamp
+ */
+export function cancelOrder(this: any, orderId: string) {
+  let url = '/orders/{orderId}/cancel';
+  if (orderId) {
+    url = url.replace('{orderId}', orderId);
+  }
+
+  return this.api.fetch(url, {
+    method: 'POST',
+  });
+    return this.api.fetch(url, fetchOptions);
+}