lua-cli 3.0.0-alpha.1 → 3.0.0-alpha.5

package/USER_DATA_INSTANCE.md

@@ -1,621 +0,0 @@
-# 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