lua-cli 2.5.0 → 2.5.2

package/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.5.2] - 2025-10-07
+
+### ✨ New Features
+- **Direct Property Access for All Instance Classes**: Extended Proxy pattern to all instance types
+  - `ProductInstance` now supports `product.name` instead of `product.data.name`
+  - `DataEntryInstance` now supports `entry.fieldName` instead of `entry.data.fieldName`
+  - `BasketInstance` now supports `basket.items` (checks instance → data → common)
+  - `OrderInstance` now supports `order.shippingAddress` (checks instance → data → common)
+  
+- **Array-Like Methods for Product Collections**: Direct iteration support
+  - `ProductSearchInstance` now supports `.map()`, `.filter()`, `.forEach()`, etc.
+  - `ProductPaginationInstance` now supports all array methods
+  - Both support `for...of` loops and spread operators
+  - Direct `.length` property access
+
+### 🔧 Improvements
+- **Consistent API**: All instance classes now follow the same intuitive access patterns
+- **Enhanced Iteration**: Product collections can be treated as arrays
+- **Better TypeScript Support**: Index signatures on all instance classes
+
+### 📖 Documentation
+- **Comprehensive Instance Types Documentation**: Added complete guide for all instance types
+
+### Technical Details
+- Added Proxy implementations to ProductInstance, DataEntryInstance, BasketInstance, OrderInstance
+- Added array method delegation to ProductSearchInstance and ProductPaginationInstance
+- Added Symbol.iterator support for proper iteration
+- Type-safe implementations with proper generics
+
+## [2.5.1] - 2025-10-07
+
+### 🐛 Bug Fixes
+- **TypeScript Index Signature**: Added index signature to `UserDataInstance` class to fix TypeScript linting errors
+  - Resolves "Property does not exist on type" errors when accessing dynamic properties like `user.name`
+  - Now properly typed for dynamic property access via Proxy
+
 ## [2.5.0] - 2025-10-07
 
 ### ✨ New Features

package/dist/api/products.api.service.js

@@ -25,9 +25,11 @@ export default class ProductApi extends HttpClient {
      * @throws Error if the request fails or products cannot be retrieved
      */
     async get(page = 1, limit = 10) {
+        console.log('get products', page, limit, this.agentId, this.apiKey);
         const response = await this.httpGet(`/developer/agents/${this.agentId}/products?page=${page}&limit=${limit}`, {
             Authorization: `Bearer ${this.apiKey}`,
         });
+        console.log('get products response', response);
         if (response.success) {
             return new ProductPaginationInstance(this, response);
         }

package/dist/common/basket.instance.d.ts

@@ -4,6 +4,7 @@ import OrderInstance from "./order.instance.js";
 /**
  * Basket instance class providing a fluent API for managing user baskets
  * Provides methods for adding/removing items, updating metadata, and placing orders
+ * Supports direct property access (e.g., basket.items) for accessing data and common properties
  */
 export default class BasketInstance {
     private id;
@@ -16,10 +17,12 @@ export default class BasketInstance {
     itemCount: number;
     status: BasketStatus;
     private basketAPI;
+    [key: string]: any;
     /**
-     * Creates a new BasketInstance
+     * Creates a new BasketInstance with proxy support for direct property access
      * @param api - The BasketAPI instance for making API calls
      * @param basket - The basket data from the API
+     * @returns Proxied instance that allows direct access to data and common properties
      */
     constructor(api: BasketAPI, basket: Basket);
     /**

package/dist/common/basket.instance.js

@@ -2,12 +2,14 @@ import { BasketStatus } from "../interfaces/baskets.js";
 /**
  * Basket instance class providing a fluent API for managing user baskets
  * Provides methods for adding/removing items, updating metadata, and placing orders
+ * Supports direct property access (e.g., basket.items) for accessing data and common properties
  */
 export default class BasketInstance {
     /**
-     * Creates a new BasketInstance
+     * Creates a new BasketInstance with proxy support for direct property access
      * @param api - The BasketAPI instance for making API calls
      * @param basket - The basket data from the API
+     * @returns Proxied instance that allows direct access to data and common properties
      */
     constructor(api, basket) {
         this.data = basket.data;
@@ -26,6 +28,79 @@ export default class BasketInstance {
             enumerable: false,
             configurable: true
         });
+        // Return a proxy that allows direct property access
+        return new Proxy(this, {
+            get(target, prop, receiver) {
+                // If the property exists on the instance itself, return it
+                if (prop in target) {
+                    return Reflect.get(target, prop, receiver);
+                }
+                // Check data object
+                if (typeof prop === 'string' && prop in target.data) {
+                    return target.data[prop];
+                }
+                // Check common object
+                if (typeof prop === 'string' && prop in target.common) {
+                    return target.common[prop];
+                }
+                return undefined;
+            },
+            set(target, prop, value, receiver) {
+                // Reserved properties that should be set on the instance itself
+                const reservedProps = ['id', 'userId', 'agentId', 'data', 'common', 'metadata', 'totalAmount', 'itemCount', 'status', 'basketAPI', 'updateMetadata', 'updateStatus', 'addItem', 'removeItem', 'clear', 'placeOrder', 'toJSON'];
+                if (typeof prop === 'string' && reservedProps.includes(prop)) {
+                    return Reflect.set(target, prop, value, receiver);
+                }
+                // Check if property exists in data or common, otherwise default to data
+                if (typeof prop === 'string') {
+                    if (prop in target.common) {
+                        target.common[prop] = value;
+                    }
+                    else {
+                        target.data[prop] = value;
+                    }
+                    return true;
+                }
+                return false;
+            },
+            has(target, prop) {
+                // Check if property exists on instance, in data, or in common
+                return prop in target || (typeof prop === 'string' && (prop in target.data || prop in target.common));
+            },
+            ownKeys(target) {
+                // Return instance keys, data keys, and common keys
+                const instanceKeys = Reflect.ownKeys(target);
+                const dataKeys = Object.keys(target.data);
+                const commonKeys = Object.keys(target.common);
+                return [...new Set([...instanceKeys, ...dataKeys, ...commonKeys])];
+            },
+            getOwnPropertyDescriptor(target, prop) {
+                // First check if it's an instance property
+                const instanceDesc = Reflect.getOwnPropertyDescriptor(target, prop);
+                if (instanceDesc) {
+                    return instanceDesc;
+                }
+                // Then check data properties
+                if (typeof prop === 'string' && prop in target.data) {
+                    return {
+                        configurable: true,
+                        enumerable: true,
+                        writable: true,
+                        value: target.data[prop]
+                    };
+                }
+                // Then check common properties
+                if (typeof prop === 'string' && prop in target.common) {
+                    return {
+                        configurable: true,
+                        enumerable: true,
+                        writable: true,
+                        value: target.common[prop]
+                    };
+                }
+                return undefined;
+            }
+        });
     }
     /**
      * Custom toJSON method to control what gets serialized when logging

package/dist/common/data.entry.instance.d.ts

@@ -3,6 +3,7 @@ import { CreateCustomDataResponse } from "../interfaces/custom.data.js";
 /**
  * Data entry instance class providing a fluent API for managing custom data entries
  * Provides methods for updating and deleting individual data entries
+ * Supports direct property access (e.g., entry.fieldName) for accessing data properties
  */
 export default class DataEntryInstance {
     data: Record<string, any>;
@@ -10,11 +11,13 @@ export default class DataEntryInstance {
     collectionName: string;
     score?: number;
     private customDataAPI;
+    [key: string]: any;
     /**
-     * Creates a new DataEntryInstance
+     * Creates a new DataEntryInstance with proxy support for direct property access
      * @param api - The CustomDataAPI instance for making API calls
      * @param entry - The custom data entry response from the API
      * @param collectionName - The name of the collection this entry belongs to
+     * @returns Proxied instance that allows direct access to data properties
      */
     constructor(api: CustomDataAPI, entry: CreateCustomDataResponse, collectionName: string);
     /**

package/dist/common/data.entry.instance.js

@@ -1,13 +1,15 @@
 /**
  * Data entry instance class providing a fluent API for managing custom data entries
  * Provides methods for updating and deleting individual data entries
+ * Supports direct property access (e.g., entry.fieldName) for accessing data properties
  */
 export default class DataEntryInstance {
     /**
-     * Creates a new DataEntryInstance
+     * Creates a new DataEntryInstance with proxy support for direct property access
      * @param api - The CustomDataAPI instance for making API calls
      * @param entry - The custom data entry response from the API
      * @param collectionName - The name of the collection this entry belongs to
+     * @returns Proxied instance that allows direct access to data properties
      */
     constructor(api, entry, collectionName) {
         this.data = entry.data;
@@ -21,6 +23,60 @@ export default class DataEntryInstance {
             enumerable: false,
             configurable: true
         });
+        // Return a proxy that allows direct property access
+        return new Proxy(this, {
+            get(target, prop, receiver) {
+                // If the property exists on the instance itself, return it
+                if (prop in target) {
+                    return Reflect.get(target, prop, receiver);
+                }
+                // Otherwise, try to get it from the data object
+                if (typeof prop === 'string' && prop in target.data) {
+                    return target.data[prop];
+                }
+                return undefined;
+            },
+            set(target, prop, value, receiver) {
+                // Reserved properties that should be set on the instance itself
+                const reservedProps = ['data', 'id', 'collectionName', 'score', 'customDataAPI', 'update', 'delete', 'toJSON'];
+                if (typeof prop === 'string' && reservedProps.includes(prop)) {
+                    return Reflect.set(target, prop, value, receiver);
+                }
+                // All other properties get set on the data object
+                if (typeof prop === 'string') {
+                    target.data[prop] = value;
+                    return true;
+                }
+                return false;
+            },
+            has(target, prop) {
+                // Check if property exists on instance or in data
+                return prop in target || (typeof prop === 'string' && prop in target.data);
+            },
+            ownKeys(target) {
+                // Return both instance keys and data keys
+                const instanceKeys = Reflect.ownKeys(target);
+                const dataKeys = Object.keys(target.data);
+                return [...new Set([...instanceKeys, ...dataKeys])];
+            },
+            getOwnPropertyDescriptor(target, prop) {
+                // First check if it's an instance property
+                const instanceDesc = Reflect.getOwnPropertyDescriptor(target, prop);
+                if (instanceDesc) {
+                    return instanceDesc;
+                }
+                // Then check if it's a data property
+                if (typeof prop === 'string' && prop in target.data) {
+                    return {
+                        configurable: true,
+                        enumerable: true,
+                        writable: true,
+                        value: target.data[prop]
+                    };
+                }
+                return undefined;
+            }
+        });
     }
     /**
      * Custom toJSON method to control what gets serialized when logging

package/dist/common/order.instance.d.ts

@@ -3,6 +3,7 @@ import { OrderResponse, OrderStatus } from "../interfaces/orders.js";
 /**
  * Order instance class providing a fluent API for managing orders
  * Provides methods for updating order status and order data
+ * Supports direct property access (e.g., order.shippingAddress) for accessing data and common properties
  */
 export default class OrderInstance {
     private data;
@@ -12,10 +13,12 @@ export default class OrderInstance {
     private agentId;
     private orderId;
     private orderAPI;
+    [key: string]: any;
     /**
-     * Creates a new OrderInstance
+     * Creates a new OrderInstance with proxy support for direct property access
      * @param api - The OrderApi instance for making API calls
      * @param order - The order response data from the API
+     * @returns Proxied instance that allows direct access to data and common properties
      */
     constructor(api: OrderApi, order: OrderResponse);
     /**

package/dist/common/order.instance.js

@@ -1,12 +1,14 @@
 /**
  * Order instance class providing a fluent API for managing orders
  * Provides methods for updating order status and order data
+ * Supports direct property access (e.g., order.shippingAddress) for accessing data and common properties
  */
 export default class OrderInstance {
     /**
-     * Creates a new OrderInstance
+     * Creates a new OrderInstance with proxy support for direct property access
      * @param api - The OrderApi instance for making API calls
      * @param order - The order response data from the API
+     * @returns Proxied instance that allows direct access to data and common properties
      */
     constructor(api, order) {
         this.data = order.data;
@@ -22,6 +24,79 @@ export default class OrderInstance {
             enumerable: false,
             configurable: true
         });
+        // Return a proxy that allows direct property access
+        return new Proxy(this, {
+            get(target, prop, receiver) {
+                // If the property exists on the instance itself, return it
+                if (prop in target) {
+                    return Reflect.get(target, prop, receiver);
+                }
+                // Check data object
+                if (typeof prop === 'string' && prop in target.data) {
+                    return target.data[prop];
+                }
+                // Check common object
+                if (typeof prop === 'string' && prop in target.common) {
+                    return target.common[prop];
+                }
+                return undefined;
+            },
+            set(target, prop, value, receiver) {
+                // Reserved properties that should be set on the instance itself
+                const reservedProps = ['data', 'common', 'id', 'userId', 'agentId', 'orderId', 'orderAPI', 'updateStatus', 'update', 'toJSON'];
+                if (typeof prop === 'string' && reservedProps.includes(prop)) {
+                    return Reflect.set(target, prop, value, receiver);
+                }
+                // Check if property exists in data or common, otherwise default to data
+                if (typeof prop === 'string') {
+                    if (prop in target.common) {
+                        target.common[prop] = value;
+                    }
+                    else {
+                        target.data[prop] = value;
+                    }
+                    return true;
+                }
+                return false;
+            },
+            has(target, prop) {
+                // Check if property exists on instance, in data, or in common
+                return prop in target || (typeof prop === 'string' && (prop in target.data || prop in target.common));
+            },
+            ownKeys(target) {
+                // Return instance keys, data keys, and common keys
+                const instanceKeys = Reflect.ownKeys(target);
+                const dataKeys = Object.keys(target.data);
+                const commonKeys = Object.keys(target.common);
+                return [...new Set([...instanceKeys, ...dataKeys, ...commonKeys])];
+            },
+            getOwnPropertyDescriptor(target, prop) {
+                // First check if it's an instance property
+                const instanceDesc = Reflect.getOwnPropertyDescriptor(target, prop);
+                if (instanceDesc) {
+                    return instanceDesc;
+                }
+                // Then check data properties
+                if (typeof prop === 'string' && prop in target.data) {
+                    return {
+                        configurable: true,
+                        enumerable: true,
+                        writable: true,
+                        value: target.data[prop]
+                    };
+                }
+                // Then check common properties
+                if (typeof prop === 'string' && prop in target.common) {
+                    return {
+                        configurable: true,
+                        enumerable: true,
+                        writable: true,
+                        value: target.common[prop]
+                    };
+                }
+                return undefined;
+            }
+        });
     }
     /**
      * Custom toJSON method to control what gets serialized when logging

package/dist/common/product.instance.d.ts

@@ -2,14 +2,17 @@ import { Product } from "../interfaces/product.js";
 /**
  * Product instance class providing a fluent API for managing individual products
  * Provides methods for updating and deleting products
+ * Supports direct property access (e.g., product.name) instead of product.data.name
  */
 export default class ProductInstance {
     data: Product;
     private productAPI;
+    [key: string]: any;
     /**
-     * Creates a new ProductInstance
+     * Creates a new ProductInstance with proxy support for direct property access
      * @param api - The ProductAPI instance for making API calls
      * @param product - The product data from the API
+     * @returns Proxied instance that allows direct access to product properties
      */
     constructor(api: any, product: Product);
     /**

package/dist/common/product.instance.js

@@ -1,12 +1,14 @@
 /**
  * Product instance class providing a fluent API for managing individual products
  * Provides methods for updating and deleting products
+ * Supports direct property access (e.g., product.name) instead of product.data.name
  */
 export default class ProductInstance {
     /**
-     * Creates a new ProductInstance
+     * Creates a new ProductInstance with proxy support for direct property access
      * @param api - The ProductAPI instance for making API calls
      * @param product - The product data from the API
+     * @returns Proxied instance that allows direct access to product properties
      */
     constructor(api, product) {
         this.data = product;
@@ -17,6 +19,60 @@ export default class ProductInstance {
             enumerable: false,
             configurable: true
         });
+        // Return a proxy that allows direct property access
+        return new Proxy(this, {
+            get(target, prop, receiver) {
+                // If the property exists on the instance itself, return it
+                if (prop in target) {
+                    return Reflect.get(target, prop, receiver);
+                }
+                // Otherwise, try to get it from the data object
+                if (typeof prop === 'string' && prop in target.data) {
+                    return target.data[prop];
+                }
+                return undefined;
+            },
+            set(target, prop, value, receiver) {
+                // Reserved properties that should be set on the instance itself
+                const reservedProps = ['data', 'productAPI', 'update', 'delete', 'toJSON'];
+                if (typeof prop === 'string' && reservedProps.includes(prop)) {
+                    return Reflect.set(target, prop, value, receiver);
+                }
+                // All other properties get set on the data object
+                if (typeof prop === 'string') {
+                    target.data[prop] = value;
+                    return true;
+                }
+                return false;
+            },
+            has(target, prop) {
+                // Check if property exists on instance or in data
+                return prop in target || (typeof prop === 'string' && prop in target.data);
+            },
+            ownKeys(target) {
+                // Return both instance keys and data keys
+                const instanceKeys = Reflect.ownKeys(target);
+                const dataKeys = Object.keys(target.data);
+                return [...new Set([...instanceKeys, ...dataKeys])];
+            },
+            getOwnPropertyDescriptor(target, prop) {
+                // First check if it's an instance property
+                const instanceDesc = Reflect.getOwnPropertyDescriptor(target, prop);
+                if (instanceDesc) {
+                    return instanceDesc;
+                }
+                // Then check if it's a data property
+                if (typeof prop === 'string' && prop in target.data) {
+                    return {
+                        configurable: true,
+                        enumerable: true,
+                        writable: true,
+                        value: target.data[prop]
+                    };
+                }
+                return undefined;
+            }
+        });
     }
     /**
      * Custom toJSON method to control what gets serialized when logging

package/dist/common/product.pagination.instance.d.ts

@@ -3,6 +3,7 @@ import ProductInstance from "./product.instance.js";
 /**
  * Product pagination instance class providing a fluent API for paginated product results
  * Provides methods for navigating through pages of products
+ * Supports array methods like map, filter, forEach for direct iteration
  */
 export default class ProductPaginationInstance {
     products: ProductInstance[];
@@ -23,6 +24,63 @@ export default class ProductPaginationInstance {
      * @param results - The paginated product results from the API
      */
     constructor(api: any, results: ProductsResponse);
+    /**
+     * Returns the number of products in the current page
+     */
+    get length(): number;
+    /**
+     * Maps over the products array
+     * @param callback - Function to execute for each product
+     * @returns Array of mapped results
+     */
+    map<T>(callback: (product: ProductInstance, index: number, array: ProductInstance[]) => T): T[];
+    /**
+     * Filters the products array
+     * @param callback - Function to test each product
+     * @returns Array of products that pass the test
+     */
+    filter(callback: (product: ProductInstance, index: number, array: ProductInstance[]) => boolean): ProductInstance[];
+    /**
+     * Executes a function for each product
+     * @param callback - Function to execute for each product
+     */
+    forEach(callback: (product: ProductInstance, index: number, array: ProductInstance[]) => void): void;
+    /**
+     * Finds the first product that satisfies the test
+     * @param callback - Function to test each product
+     * @returns The first product that passes the test, or undefined
+     */
+    find(callback: (product: ProductInstance, index: number, array: ProductInstance[]) => boolean): ProductInstance | undefined;
+    /**
+     * Finds the index of the first product that satisfies the test
+     * @param callback - Function to test each product
+     * @returns The index of the first product that passes the test, or -1
+     */
+    findIndex(callback: (product: ProductInstance, index: number, array: ProductInstance[]) => boolean): number;
+    /**
+     * Checks if some products satisfy the test
+     * @param callback - Function to test each product
+     * @returns true if at least one product passes the test
+     */
+    some(callback: (product: ProductInstance, index: number, array: ProductInstance[]) => boolean): boolean;
+    /**
+     * Checks if all products satisfy the test
+     * @param callback - Function to test each product
+     * @returns true if all products pass the test
+     */
+    every(callback: (product: ProductInstance, index: number, array: ProductInstance[]) => boolean): boolean;
+    /**
+     * Reduces the products array to a single value
+     * @param callback - Function to execute on each product
+     * @param initialValue - Initial value for the accumulator
+     * @returns The final accumulated value
+     */
+    reduce<T>(callback: (accumulator: T, product: ProductInstance, index: number, array: ProductInstance[]) => T, initialValue: T): T;
+    /**
+     * Makes the instance iterable
+     * @returns Iterator for the products array
+     */
+    [Symbol.iterator](): Iterator<ProductInstance>;
     /**
      * Custom toJSON method to control what gets serialized when logging
      * @returns Serialized products and pagination data

package/dist/common/product.pagination.instance.js

@@ -2,6 +2,7 @@ import ProductInstance from "./product.instance.js";
 /**
  * Product pagination instance class providing a fluent API for paginated product results
  * Provides methods for navigating through pages of products
+ * Supports array methods like map, filter, forEach for direct iteration
  */
 export default class ProductPaginationInstance {
     /**
@@ -29,6 +30,83 @@ export default class ProductPaginationInstance {
             configurable: true
         });
     }
+    /**
+     * Returns the number of products in the current page
+     */
+    get length() {
+        return this.products.length;
+    }
+    /**
+     * Maps over the products array
+     * @param callback - Function to execute for each product
+     * @returns Array of mapped results
+     */
+    map(callback) {
+        return this.products.map(callback);
+    }
+    /**
+     * Filters the products array
+     * @param callback - Function to test each product
+     * @returns Array of products that pass the test
+     */
+    filter(callback) {
+        return this.products.filter(callback);
+    }
+    /**
+     * Executes a function for each product
+     * @param callback - Function to execute for each product
+     */
+    forEach(callback) {
+        this.products.forEach(callback);
+    }
+    /**
+     * Finds the first product that satisfies the test
+     * @param callback - Function to test each product
+     * @returns The first product that passes the test, or undefined
+     */
+    find(callback) {
+        return this.products.find(callback);
+    }
+    /**
+     * Finds the index of the first product that satisfies the test
+     * @param callback - Function to test each product
+     * @returns The index of the first product that passes the test, or -1
+     */
+    findIndex(callback) {
+        return this.products.findIndex(callback);
+    }
+    /**
+     * Checks if some products satisfy the test
+     * @param callback - Function to test each product
+     * @returns true if at least one product passes the test
+     */
+    some(callback) {
+        return this.products.some(callback);
+    }
+    /**
+     * Checks if all products satisfy the test
+     * @param callback - Function to test each product
+     * @returns true if all products pass the test
+     */
+    every(callback) {
+        return this.products.every(callback);
+    }
+    /**
+     * Reduces the products array to a single value
+     * @param callback - Function to execute on each product
+     * @param initialValue - Initial value for the accumulator
+     * @returns The final accumulated value
+     */
+    reduce(callback, initialValue) {
+        return this.products.reduce(callback, initialValue);
+    }
+    /**
+     * Makes the instance iterable
+     * @returns Iterator for the products array
+     */
+    [Symbol.iterator]() {
+        return this.products[Symbol.iterator]();
+    }
     /**
      * Custom toJSON method to control what gets serialized when logging
      * @returns Serialized products and pagination data