lua-cli 2.4.1 → 2.5.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.0] - 2025-10-07
+
+### ✨ New Features
+- **Direct Property Access for UserDataInstance**: Now supports intuitive property access using Proxy pattern
+  - Access user data with `user.name` instead of `user.data.name`
+  - Set properties directly with `user.name = "John"`
+  - Full backward compatibility maintained - `user.data.name` still works
+  - Proper enumeration support for `Object.keys()` and `in` operator
+
+### 🔧 Improvements
+- **Reduced Sensitive Field Filtering**: Sanitization now only removes `agentId` and `userId`
+  - Allows access to more user data fields while maintaining essential privacy
+  - Custom keys and tokens are now accessible in tools
+
+### 📖 Documentation
+- **Comprehensive UserDataInstance Documentation**: Added full API reference with examples
+
+### Technical Details
+- Enhanced Proxy implementation with proper trap handlers for get, set, has, ownKeys, and getOwnPropertyDescriptor
+- Reserved properties (`data`, `userAPI`, `update`, `clear`, `toJSON`) protected from proxy interception
+- Maintains all existing methods and behavior while adding new access patterns
+
 ## [1.3.2-alpha.3] - 2025-09-25
 
 ### 🚀 Major Rewrite

package/USER_DATA_INSTANCE.md

@@ -0,0 +1,621 @@
+# UserDataInstance API Reference
+
+## Overview
+
+`UserDataInstance` is a powerful, proxy-enhanced class that provides a fluent API for managing user-specific data in Lua AI tools. It automatically handles data sanitization, provides intuitive property access, and includes methods for updating and clearing user data.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+- [Property Access](#property-access)
+- [Methods](#methods)
+- [Examples](#examples)
+- [Best Practices](#best-practices)
+- [TypeScript Support](#typescript-support)
+
+## Features
+
+✨ **Direct Property Access** - Access data with `user.name` instead of `user.data.name`  
+🔒 **Automatic Sanitization** - Removes sensitive fields (agentId, userId) automatically  
+🔄 **Async Updates** - Built-in methods for updating and clearing user data  
+📝 **Console-Friendly** - Clean output when logging with `console.log()`  
+🎯 **Type-Safe** - Full TypeScript support with proper type definitions  
+⚡ **Proxy-Powered** - Seamless property access via JavaScript Proxy  
+🔙 **Backward Compatible** - Works with both new and old access patterns  
+
+## Installation
+
+```bash
+npm install lua-cli
+```
+
+## Quick Start
+
+```typescript
+import { UserDataTool } from 'lua-cli';
+
+// In your LuaSkill tool
+class MyTool extends LuaTool {
+  async execute(input: any, context: ToolContext) {
+    // Access user data through context
+    const user = context.user;
+    
+    // Direct property access (NEW! ✨)
+    console.log(user.name);
+    console.log(user.email);
+    console.log(user.preferences);
+    
+    // Set properties directly
+    user.favoriteColor = "blue";
+    
+    // Update on server
+    await user.update({ favoriteColor: "blue" });
+    
+    return { success: true };
+  }
+}
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+constructor(api: UserDataAPI, data: UserData)
+```
+
+**Parameters:**
+- `api` - The UserDataAPI instance for making API calls
+- `data` - The user data from the API (will be sanitized automatically)
+
+**Returns:** A proxied instance that allows direct access to data properties
+
+**Note:** You typically don't need to instantiate this directly. It's provided through the `context.user` object in your tools.
+
+## Property Access
+
+### Direct Access (Recommended ✨)
+
+```typescript
+// Reading properties
+const name = user.name;
+const email = user.email;
+const settings = user.settings;
+
+// Setting properties (updates local instance only)
+user.name = "John Doe";
+user.email = "john@example.com";
+user.settings = { theme: "dark" };
+
+// Checking if property exists
+if ('name' in user) {
+  console.log('User has a name');
+}
+```
+
+### Traditional Access (Still Supported)
+
+```typescript
+// Reading through .data property
+const name = user.data.name;
+const email = user.data.email;
+
+// Setting through .data property
+user.data.name = "John Doe";
+```
+
+### Property Enumeration
+
+```typescript
+// Get all user data keys
+const keys = Object.keys(user); // Returns all data keys + methods
+
+// Iterate over properties
+for (const key in user) {
+  console.log(`${key}: ${user[key]}`);
+}
+```
+
+## Methods
+
+### `update(data: Record<string, any>): Promise<any>`
+
+Updates the user's data on the server and locally.
+
+**Parameters:**
+- `data` - Object containing the fields to update or add
+
+**Returns:** Promise resolving to the updated sanitized user data
+
+**Throws:** Error if the update fails
+
+**Example:**
+```typescript
+// Update single field
+await user.update({ name: "John Doe" });
+
+// Update multiple fields
+await user.update({
+  name: "John Doe",
+  email: "john@example.com",
+  preferences: {
+    theme: "dark",
+    notifications: true
+  }
+});
+
+// Access updated data
+console.log(user.name); // "John Doe"
+console.log(user.preferences.theme); // "dark"
+```
+
+### `clear(): Promise<boolean>`
+
+Clears all user data for the current user on the server.
+
+**Returns:** Promise resolving to `true` if clearing was successful
+
+**Throws:** Error if the clear operation fails
+
+**Example:**
+```typescript
+try {
+  const success = await user.clear();
+  if (success) {
+    console.log('User data cleared successfully');
+  }
+} catch (error) {
+  console.error('Failed to clear user data');
+}
+```
+
+### `toJSON(): Record<string, any>`
+
+Custom serialization method used when converting to JSON or logging.
+
+**Returns:** The sanitized user data object
+
+**Example:**
+```typescript
+// Automatic usage in JSON.stringify
+const json = JSON.stringify(user);
+
+// Explicit usage
+const dataObject = user.toJSON();
+```
+
+## Data Sanitization
+
+The `UserDataInstance` automatically removes sensitive fields before storing data locally:
+
+**Removed Fields:**
+- `agentId`
+- `userId`
+
+**Accessible Fields:** All other fields including:
+- `name`, `email`, `phone`
+- Custom data fields
+- API keys and tokens (if stored in user data)
+- Preferences and settings
+
+```typescript
+// Server returns:
+{
+  userId: "12345",      // ❌ Removed
+  agentId: "agent-123", // ❌ Removed
+  name: "John Doe",     // ✅ Accessible
+  email: "john@example.com", // ✅ Accessible
+  customKey: "value"    // ✅ Accessible
+}
+
+// Local user instance has:
+{
+  name: "John Doe",
+  email: "john@example.com",
+  customKey: "value"
+}
+```
+
+## Examples
+
+### Example 1: Storing User Preferences
+
+```typescript
+class PreferencesTool extends LuaTool {
+  schema = {
+    input: z.object({
+      theme: z.enum(['light', 'dark']).optional(),
+      language: z.string().optional(),
+      notifications: z.boolean().optional()
+    }),
+    output: z.object({
+      message: z.string(),
+      preferences: z.any()
+    })
+  };
+
+  async execute(input: any, context: ToolContext) {
+    const user = context.user;
+    
+    // Get current preferences or initialize
+    const currentPrefs = user.preferences || {};
+    
+    // Update with new values
+    const newPrefs = {
+      ...currentPrefs,
+      ...input
+    };
+    
+    // Save to server
+    await user.update({ preferences: newPrefs });
+    
+    return {
+      message: 'Preferences updated successfully',
+      preferences: user.preferences
+    };
+  }
+}
+```
+
+### Example 2: User Profile Management
+
+```typescript
+class ProfileTool extends LuaTool {
+  schema = {
+    input: z.object({
+      action: z.enum(['get', 'update', 'clear']),
+      profile: z.object({
+        firstName: z.string().optional(),
+        lastName: z.string().optional(),
+        bio: z.string().optional(),
+        avatar: z.string().url().optional()
+      }).optional()
+    }),
+    output: z.object({
+      success: z.boolean(),
+      profile: z.any().optional(),
+      message: z.string()
+    })
+  };
+
+  async execute(input: any, context: ToolContext) {
+    const user = context.user;
+    
+    switch (input.action) {
+      case 'get':
+        return {
+          success: true,
+          profile: {
+            firstName: user.firstName,
+            lastName: user.lastName,
+            bio: user.bio,
+            avatar: user.avatar
+          },
+          message: 'Profile retrieved'
+        };
+        
+      case 'update':
+        await user.update(input.profile);
+        return {
+          success: true,
+          profile: input.profile,
+          message: 'Profile updated successfully'
+        };
+        
+      case 'clear':
+        await user.clear();
+        return {
+          success: true,
+          message: 'Profile cleared successfully'
+        };
+        
+      default:
+        throw new Error('Invalid action');
+    }
+  }
+}
+```
+
+### Example 3: Shopping Cart Persistence
+
+```typescript
+class CartTool extends LuaTool {
+  schema = {
+    input: z.object({
+      action: z.enum(['add', 'remove', 'get', 'clear']),
+      productId: z.string().optional(),
+      quantity: z.number().optional()
+    }),
+    output: z.object({
+      cart: z.array(z.any()),
+      total: z.number()
+    })
+  };
+
+  async execute(input: any, context: ToolContext) {
+    const user = context.user;
+    
+    // Get current cart (direct access!)
+    let cart = user.cart || [];
+    
+    switch (input.action) {
+      case 'add':
+        const existing = cart.find((item: any) => 
+          item.productId === input.productId
+        );
+        
+        if (existing) {
+          existing.quantity += input.quantity;
+        } else {
+          cart.push({
+            productId: input.productId,
+            quantity: input.quantity
+          });
+        }
+        
+        await user.update({ cart });
+        break;
+        
+      case 'remove':
+        cart = cart.filter((item: any) => 
+          item.productId !== input.productId
+        );
+        await user.update({ cart });
+        break;
+        
+      case 'clear':
+        await user.update({ cart: [] });
+        cart = [];
+        break;
+        
+      case 'get':
+        // Just return current cart
+        break;
+    }
+    
+    const total = cart.reduce((sum: number, item: any) => 
+      sum + (item.quantity || 0), 0
+    );
+    
+    return { cart, total };
+  }
+}
+```
+
+### Example 4: Session State Management
+
+```typescript
+class SessionTool extends LuaTool {
+  async execute(input: any, context: ToolContext) {
+    const user = context.user;
+    
+    // Track page visits
+    const visits = user.pageVisits || 0;
+    await user.update({ pageVisits: visits + 1 });
+    
+    // Track last seen timestamp
+    await user.update({ 
+      lastSeen: new Date().toISOString(),
+      sessionCount: (user.sessionCount || 0) + 1
+    });
+    
+    // Check if returning user
+    const isReturning = visits > 0;
+    
+    return {
+      isReturning,
+      visits: user.pageVisits,
+      sessionCount: user.sessionCount,
+      lastSeen: user.lastSeen
+    };
+  }
+}
+```
+
+### Example 5: Multi-Step Form Data
+
+```typescript
+class FormStateTool extends LuaTool {
+  async execute(input: any, context: ToolContext) {
+    const user = context.user;
+    
+    // Get or initialize form state
+    const formData = user.multiStepForm || {
+      step: 1,
+      completed: {},
+      currentData: {}
+    };
+    
+    // Update current step data
+    formData.completed[input.step] = true;
+    formData.currentData = {
+      ...formData.currentData,
+      ...input.data
+    };
+    
+    // Move to next step
+    formData.step = input.step + 1;
+    
+    // Save state
+    await user.update({ multiStepForm: formData });
+    
+    return {
+      currentStep: formData.step,
+      completedSteps: Object.keys(formData.completed),
+      isComplete: formData.step > 5
+    };
+  }
+}
+```
+
+## Best Practices
+
+### ✅ DO
+
+```typescript
+// Use direct property access for cleaner code
+const name = user.name;
+
+// Update multiple fields at once
+await user.update({
+  field1: value1,
+  field2: value2
+});
+
+// Check for property existence before accessing
+if ('preferences' in user) {
+  console.log(user.preferences);
+}
+
+// Initialize nested objects carefully
+const prefs = user.preferences || {};
+```
+
+### ❌ DON'T
+
+```typescript
+// Don't mutate and forget to call update()
+user.name = "John";
+// ❌ This only updates locally! Must call user.update()
+
+// Don't assume sensitive fields are available
+console.log(user.userId); // undefined (sanitized)
+console.log(user.agentId); // undefined (sanitized)
+
+// Don't make unnecessary update calls
+await user.update({ field1: value1 });
+await user.update({ field2: value2 }); // Combine these!
+```
+
+## TypeScript Support
+
+### Type Definitions
+
+```typescript
+interface UserDataInstance {
+  data: Record<string, any>;
+  
+  // Methods
+  update(data: Record<string, any>): Promise<any>;
+  clear(): Promise<boolean>;
+  toJSON(): Record<string, any>;
+  
+  // Index signature for dynamic property access
+  [key: string]: any;
+}
+```
+
+### Usage with Types
+
+```typescript
+// Define your user data shape
+interface MyUserData {
+  name: string;
+  email: string;
+  preferences: {
+    theme: 'light' | 'dark';
+    notifications: boolean;
+  };
+}
+
+// Access with type checking
+const user = context.user;
+const name: string = user.name;
+const prefs: MyUserData['preferences'] = user.preferences;
+```
+
+## Console Output
+
+The `UserDataInstance` includes custom serialization for clean console output:
+
+```typescript
+console.log(user);
+// Output:
+// {
+//   name: "John Doe",
+//   email: "john@example.com",
+//   preferences: { theme: "dark" }
+// }
+
+// Methods and internal properties are hidden
+// Only the actual user data is displayed
+```
+
+## Reserved Properties
+
+The following properties are reserved and cannot be overwritten via proxy:
+
+- `data` - The internal data storage
+- `userAPI` - The API client (non-enumerable)
+- `update` - The update method
+- `clear` - The clear method
+- `toJSON` - The serialization method
+
+Attempting to set these will maintain the original instance behavior.
+
+## Performance Considerations
+
+- **Proxy Overhead**: Minimal performance impact for property access
+- **Update Batching**: Combine multiple field updates into a single `update()` call
+- **Local Changes**: Setting properties directly only updates the local instance
+- **Server Sync**: Always call `update()` to persist changes to the server
+
+## Backward Compatibility
+
+The new direct property access pattern is fully backward compatible:
+
+```typescript
+// Old pattern (still works)
+user.data.name = "John";
+await user.update({ name: user.data.name });
+
+// New pattern (recommended)
+user.name = "John";
+await user.update({ name: user.name });
+
+// Mixed usage (also works)
+console.log(user.name);        // Direct access
+console.log(user.data.email);  // Traditional access
+```
+
+## Error Handling
+
+```typescript
+try {
+  await user.update({
+    name: "John Doe",
+    email: "john@example.com"
+  });
+} catch (error) {
+  console.error('Failed to update user data:', error);
+  // Handle error appropriately
+}
+
+try {
+  await user.clear();
+} catch (error) {
+  console.error('Failed to clear user data:', error);
+}
+```
+
+## Related Resources
+
+- [LuaTool Documentation](./TEMPLATE_GUIDE.md)
+- [API Reference](./API_REFERENCE.md)
+- [Getting Started](./GETTING_STARTED.md)
+- [UserDataTool Example](./template/src/tools/UserDataTool.ts)
+
+## Support
+
+For issues, questions, or contributions:
+- GitHub: [lua-ai-global/lua-cli](https://github.com/lua-ai-global/lua-cli)
+- Email: stefan@heylua.ai
+
+---
+
+**Version:** 2.5.0  
+**Last Updated:** October 7, 2025  
+**License:** MIT

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

@@ -3,14 +3,16 @@ import { UserDataAPI } from "../types/index.js";
 /**
  * User data instance class providing a fluent API for managing user data
  * Automatically sanitizes sensitive fields and provides methods for updating and clearing data
+ * Supports direct property access (e.g., user.name) instead of user.data.name
  */
 export default class UserDataInstance {
     data: Record<string, any>;
     private userAPI;
     /**
-     * Creates a new UserDataInstance
+     * Creates a new UserDataInstance with proxy support for direct property access
      * @param api - The UserDataAPI instance for making API calls
      * @param data - The user data from the API (will be sanitized automatically)
+     * @returns Proxied instance that allows direct access to data properties
      */
     constructor(api: UserDataAPI, data: UserData);
     /**

package/dist/common/user.instance.js

@@ -1,12 +1,14 @@
 /**
  * User data instance class providing a fluent API for managing user data
  * Automatically sanitizes sensitive fields and provides methods for updating and clearing data
+ * Supports direct property access (e.g., user.name) instead of user.data.name
  */
 export default class UserDataInstance {
     /**
-     * Creates a new UserDataInstance
+     * Creates a new UserDataInstance with proxy support for direct property access
      * @param api - The UserDataAPI instance for making API calls
      * @param data - The user data from the API (will be sanitized automatically)
+     * @returns Proxied instance that allows direct access to data properties
      */
     constructor(api, data) {
         this.data = this.sanitizeData(data);
@@ -17,6 +19,60 @@ export default class UserDataInstance {
             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', 'userAPI', 'update', 'clear', '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;
+            }
+        });
     }
     /**
      * Removes sensitive fields from the data before storing
@@ -31,7 +87,7 @@ export default class UserDataInstance {
         // Create a copy of the data to avoid mutating the original
         const sanitized = { ...data };
         // Remove sensitive fields
-        const sensitiveFields = ['apiKey', 'agentId', 'userId', 'token', 'secret', 'key'];
+        const sensitiveFields = ['agentId', 'userId'];
         sensitiveFields.forEach(field => {
             delete sanitized[field];
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lua-cli",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "description": "Command-line interface for Lua AI platform - develop, test, and deploy LuaSkills with custom tools",
   "readmeFilename": "README.md",
   "main": "dist/api-exports.js",
@@ -57,6 +57,7 @@
     "CLI_REFERENCE.md",
     "API_REFERENCE.md",
     "TEMPLATE_GUIDE.md",
+    "USER_DATA_INSTANCE.md",
     "CHANGELOG.md",
     "LICENSE"
   ],