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

package/INSTANCE_TYPES.md

@@ -1,1158 +0,0 @@
-# Instance Types API Reference
-
-Complete guide to all instance types in lua-cli, when they're returned, and how to use them.
-
-## Table of Contents
-
-- [Overview](#overview)
-- [UserDataInstance](#userdatainstance)
-- [ProductInstance](#productinstance)
-- [ProductSearchInstance](#productsearchinstance)
-- [ProductPaginationInstance](#productpaginationinstance)
-- [BasketInstance](#basketinstance)
-- [OrderInstance](#orderinstance)
-- [DataEntryInstance](#dataentryinstance)
-- [Common Patterns](#common-patterns)
-- [TypeScript Support](#typescript-support)
-
----
-
-## Overview
-
-All instance classes in lua-cli now support **direct property access** via JavaScript Proxy. This means you can access nested data properties directly without going through `.data` or `.common` objects.
-
-### Key Features
-
-✅ **Direct Property Access** - `instance.name` instead of `instance.data.name`  
-✅ **Backward Compatible** - Old patterns still work  
-✅ **Type Safe** - Full TypeScript support  
-✅ **Array Methods** - Collections support `.map()`, `.filter()`, etc.  
-✅ **Iteration** - Use `for...of` loops and spread operators  
-
----
-
-## UserDataInstance
-
-User-specific data storage with automatic sanitization.
-
-### When It's Returned
-
-```typescript
-// Available in tool context
-class MyTool extends LuaTool {
-  async execute(input: any, context: ToolContext) {
-    const user = context.user; // UserDataInstance
-  }
-}
-```
-
-### Properties
-
-- **`data`** - The sanitized user data object
-- All user data fields accessible directly
-
-### Methods
-
-#### `update(data: Record<string, any>): Promise<any>`
-
-Updates user data on the server.
-
-```typescript
-await user.update({
-  name: "John Doe",
-  email: "john@example.com",
-  preferences: {
-    theme: "dark",
-    notifications: true
-  }
-});
-```
-
-#### `clear(): Promise<boolean>`
-
-Clears all user data.
-
-```typescript
-await user.clear();
-```
-
-### Usage Examples
-
-```typescript
-// Direct property access
-const name = user.name;
-const email = user.email;
-const prefs = user.preferences;
-
-// Setting properties (local only)
-user.favoriteColor = "blue";
-
-// Persist to server
-await user.update({ favoriteColor: user.favoriteColor });
-
-// Check property existence
-if ('preferences' in user) {
-  console.log('User has preferences');
-}
-
-// Get all keys
-const keys = Object.keys(user);
-```
-
-### Data Sanitization
-
-The following fields are automatically removed:
-- `agentId`
-- `userId`
-
-All other fields are accessible including custom data, preferences, and metadata.
-
----
-
-## ProductInstance
-
-Individual product with update and delete capabilities.
-
-### When It's Returned
-
-```typescript
-// From product search
-const results = await products.search("laptop");
-const product = results.products[0]; // ProductInstance
-
-// From pagination
-const page = await products.get(1, 10);
-const product = page.products[0]; // ProductInstance
-
-// From create
-const newProduct = await products.create({
-  name: "Gaming Laptop",
-  price: 1299.99
-}); // ProductInstance
-```
-
-### Properties
-
-- **`data`** - The product data object
-- All product fields accessible directly (name, price, sku, etc.)
-
-### Methods
-
-#### `update(data: Record<string, any>): Promise<Product>`
-
-Updates the product data.
-
-```typescript
-await product.update({
-  price: 999.99,
-  stock: 50,
-  description: "Updated description"
-});
-```
-
-#### `delete(): Promise<Product>`
-
-Deletes the product from the catalog.
-
-```typescript
-await product.delete();
-```
-
-### Usage Examples
-
-```typescript
-// Direct property access
-const name = product.name;
-const price = product.price;
-const sku = product.sku;
-const inStock = product.stock > 0;
-
-// Update product
-await product.update({
-  price: product.price * 0.9, // 10% discount
-  onSale: true
-});
-
-// Conditional operations
-if (product.stock < 10) {
-  await product.update({ lowStock: true });
-}
-
-// Delete out of stock items
-if (product.stock === 0) {
-  await product.delete();
-}
-
-// Console output shows clean data
-console.log(product);
-// { name: "Gaming Laptop", price: 1299.99, sku: "LAP-001", ... }
-```
-
-### Backward Compatibility
-
-```typescript
-// Both work:
-product.name;        // ✅ New way
-product.data.name;   // ✅ Old way still works
-```
-
----
-
-## ProductSearchInstance
-
-Collection of products from a search query with array-like methods.
-
-### When It's Returned
-
-```typescript
-// From search operations
-const results = await products.search("laptop");
-// Returns ProductSearchInstance
-```
-
-### Properties
-
-- **`products`** - Array of ProductInstance objects
-- **`length`** - Number of products (getter)
-
-### Array Methods
-
-All standard array methods are available:
-
-- `map<T>(callback)` - Transform each product
-- `filter(callback)` - Filter products
-- `forEach(callback)` - Iterate over products
-- `find(callback)` - Find first matching product
-- `findIndex(callback)` - Find index of product
-- `some(callback)` - Test if some match
-- `every(callback)` - Test if all match
-- `reduce<T>(callback, initial)` - Reduce to single value
-- `[Symbol.iterator]()` - Make iterable
-
-### Usage Examples
-
-```typescript
-// Search for products
-const results = await products.search("laptop");
-
-// Direct array methods
-const names = results.map(p => p.name);
-const expensive = results.filter(p => p.price > 1000);
-const cheapest = results.reduce((min, p) => 
-  p.price < min.price ? p : min
-);
-
-// Check length
-if (results.length > 0) {
-  console.log(`Found ${results.length} products`);
-}
-
-// Find specific product
-const product = results.find(p => p.sku === "LAP-001");
-
-// For...of iteration
-for (const product of results) {
-  console.log(`${product.name}: $${product.price}`);
-}
-
-// Spread operator
-const allProducts = [...results];
-
-// Array destructuring
-const [first, second, ...rest] = results;
-
-// Check if any match
-const hasExpensive = results.some(p => p.price > 2000);
-const allInStock = results.every(p => p.stock > 0);
-
-// forEach for side effects
-results.forEach(async (product) => {
-  if (product.stock < 5) {
-    await product.update({ lowStock: true });
-  }
-});
-
-// Calculate total value
-const totalValue = results.reduce((sum, p) => 
-  sum + (p.price * p.stock), 0
-);
-
-// Chain methods
-const availableNames = results
-  .filter(p => p.stock > 0)
-  .map(p => p.name)
-  .sort();
-```
-
-### Backward Compatibility
-
-```typescript
-// Both work:
-results.map(p => p.name);          // ✅ New way
-results.products.map(p => p.name); // ✅ Old way still works
-```
-
----
-
-## ProductPaginationInstance
-
-Paginated collection of products with navigation methods.
-
-### When It's Returned
-
-```typescript
-// From get operations with pagination
-const page = await products.get(1, 10);
-// Returns ProductPaginationInstance
-
-// From nextPage/prevPage calls
-const nextPage = await page.nextPage();
-// Returns ProductPaginationInstance
-```
-
-### Properties
-
-- **`products`** - Array of ProductInstance objects
-- **`pagination`** - Pagination metadata object:
-  - `currentPage` - Current page number
-  - `totalPages` - Total number of pages
-  - `totalCount` - Total number of products
-  - `limit` - Items per page
-  - `hasNextPage` - Whether next page exists
-  - `hasPrevPage` - Whether previous page exists
-  - `nextPage` - Next page number or null
-  - `prevPage` - Previous page number or null
-- **`length`** - Number of products on current page (getter)
-
-### Array Methods
-
-Same as ProductSearchInstance:
-- `map`, `filter`, `forEach`, `find`, `findIndex`, `some`, `every`, `reduce`, `[Symbol.iterator]`
-
-### Methods
-
-#### `nextPage(): Promise<ProductPaginationInstance>`
-
-Fetches the next page of products.
-
-```typescript
-if (page.pagination.hasNextPage) {
-  const next = await page.nextPage();
-}
-```
-
-#### `prevPage(): Promise<ProductPaginationInstance>`
-
-Fetches the previous page of products.
-
-```typescript
-if (page.pagination.hasPrevPage) {
-  const prev = await page.prevPage();
-}
-```
-
-### Usage Examples
-
-```typescript
-// Get first page
-const page = await products.get(1, 10);
-
-// Direct array methods
-const names = page.map(p => p.name);
-const inStock = page.filter(p => p.stock > 0);
-
-// Check pagination info
-console.log(`Page ${page.pagination.currentPage} of ${page.pagination.totalPages}`);
-console.log(`Showing ${page.length} of ${page.pagination.totalCount} products`);
-
-// Navigate pages
-if (page.pagination.hasNextPage) {
-  const nextPage = await page.nextPage();
-  console.log(`Now on page ${nextPage.pagination.currentPage}`);
-}
-
-// Iterate current page
-for (const product of page) {
-  console.log(product.name);
-}
-
-// Process all pages
-let currentPage = await products.get(1, 20);
-const allProducts = [];
-
-while (true) {
-  allProducts.push(...currentPage.products);
-  
-  if (!currentPage.pagination.hasNextPage) {
-    break;
-  }
-  
-  currentPage = await currentPage.nextPage();
-}
-
-// Conditional rendering based on pagination
-if (page.pagination.totalPages > 1) {
-  console.log('Multiple pages available');
-}
-
-// Calculate page-specific metrics
-const pageTotal = page.reduce((sum, p) => sum + p.price, 0);
-const pageAverage = pageTotal / page.length;
-```
-
-### Backward Compatibility
-
-```typescript
-// Both work:
-page.map(p => p.name);          // ✅ New way
-page.products.map(p => p.name); // ✅ Old way still works
-```
-
----
-
-## BasketInstance
-
-Shopping basket/cart with items and metadata.
-
-### When It's Returned
-
-```typescript
-// Get current basket
-const basket = await context.basket.get();
-// Returns BasketInstance
-
-// Create new basket
-const basket = await context.basket.create();
-// Returns BasketInstance
-```
-
-### Properties
-
-All properties from both `data` and `common` are directly accessible:
-
-**Instance Properties:**
-- `id` - Basket ID
-- `userId` - User ID (private)
-- `agentId` - Agent ID (private)
-- `metadata` - Basket metadata
-- `totalAmount` - Total basket value
-- `itemCount` - Number of items
-- `status` - Basket status
-
-**Data Properties (via proxy):**
-- `items` - Array of basket items
-- `currency` - Currency code
-- And any custom data fields
-
-**Common Properties (via proxy):**
-- `createdAt` - Creation timestamp
-- `updatedAt` - Last update timestamp
-- And any common fields
-
-### Methods
-
-#### `addItem(item: BasketItem): Promise<any>`
-
-Adds an item to the basket.
-
-```typescript
-await basket.addItem({
-  productId: "prod-123",
-  quantity: 2,
-  price: 29.99
-});
-```
-
-#### `removeItem(itemId: string): Promise<any>`
-
-Removes an item from the basket.
-
-```typescript
-await basket.removeItem("item-456");
-```
-
-#### `updateMetadata(metadata: any): Promise<any>`
-
-Updates basket metadata.
-
-```typescript
-await basket.updateMetadata({
-  giftWrap: true,
-  message: "Happy Birthday!"
-});
-```
-
-#### `updateStatus(status: BasketStatus): Promise<any>`
-
-Updates basket status.
-
-```typescript
-await basket.updateStatus(BasketStatus.CHECKED_OUT);
-```
-
-#### `clear(): Promise<any>`
-
-Removes all items from the basket.
-
-```typescript
-await basket.clear();
-```
-
-#### `placeOrder(data: Record<string, any>): Promise<OrderInstance>`
-
-Places an order from basket contents.
-
-```typescript
-const order = await basket.placeOrder({
-  shippingAddress: {
-    street: "123 Main St",
-    city: "New York",
-    zip: "10001"
-  },
-  paymentMethod: "credit_card"
-});
-```
-
-### Usage Examples
-
-```typescript
-// Get basket
-const basket = await context.basket.get();
-
-// Direct property access
-const items = basket.items;
-const total = basket.totalAmount;
-const count = basket.itemCount;
-const status = basket.status;
-
-// Add items
-await basket.addItem({
-  productId: "laptop-001",
-  quantity: 1,
-  price: 1299.99,
-  name: "Gaming Laptop"
-});
-
-// Access items
-basket.items.forEach(item => {
-  console.log(`${item.name}: ${item.quantity} x $${item.price}`);
-});
-
-// Calculate custom total
-const subtotal = basket.items.reduce((sum, item) => 
-  sum + (item.price * item.quantity), 0
-);
-
-// Update metadata
-await basket.updateMetadata({
-  couponCode: "SAVE10",
-  giftWrap: true
-});
-
-// Check metadata
-if (basket.metadata.couponCode) {
-  console.log('Coupon applied:', basket.metadata.couponCode);
-}
-
-// Clear basket
-if (basket.itemCount > 0) {
-  await basket.clear();
-}
-
-// Place order
-const order = await basket.placeOrder({
-  shippingAddress: userAddress,
-  paymentMethod: "stripe",
-  notes: "Please ring doorbell"
-});
-```
-
-### Multi-Level Property Access
-
-The basket checks three levels for properties:
-1. Instance properties (id, metadata, totalAmount, etc.)
-2. Data properties (items, custom fields)
-3. Common properties (createdAt, updatedAt, etc.)
-
-```typescript
-// All accessible directly
-basket.id;           // Instance property
-basket.items;        // Data property
-basket.totalAmount;  // Instance property
-basket.createdAt;    // Common property (via proxy)
-```
-
----
-
-## OrderInstance
-
-Completed order with status and data management.
-
-### When It's Returned
-
-```typescript
-// From placing an order
-const order = await basket.placeOrder(orderData);
-// Returns OrderInstance
-
-// From order history
-const orders = await context.orders.getAll();
-const order = orders[0]; // OrderInstance
-```
-
-### Properties
-
-All properties from both `data` and `common` are directly accessible:
-
-**Instance Properties:**
-- `id` - Order ID (private)
-- `userId` - User ID (private)
-- `agentId` - Agent ID (private)
-- `orderId` - Public order ID (private)
-
-**Data Properties (via proxy):**
-- `items` - Order items array
-- `shippingAddress` - Shipping address object
-- `billingAddress` - Billing address object
-- `paymentMethod` - Payment method
-- `notes` - Order notes
-- And any custom data fields
-
-**Common Properties (via proxy):**
-- `status` - Order status
-- `totalAmount` - Total order value
-- `createdAt` - Order creation time
-- `updatedAt` - Last update time
-- And any common fields
-
-### Methods
-
-#### `updateStatus(status: OrderStatus): Promise<any>`
-
-Updates the order status.
-
-```typescript
-await order.updateStatus(OrderStatus.SHIPPED);
-```
-
-#### `update(data: Record<string, any>): Promise<any>`
-
-Updates order data fields.
-
-```typescript
-await order.update({
-  trackingNumber: "1Z999AA10123456784",
-  estimatedDelivery: "2025-10-15",
-  notes: "Package shipped via express"
-});
-```
-
-### Order Status Values
-
-- `PENDING` - Order placed, awaiting processing
-- `PROCESSING` - Order being prepared
-- `SHIPPED` - Order shipped to customer
-- `DELIVERED` - Order delivered
-- `CANCELLED` - Order cancelled
-
-### Usage Examples
-
-```typescript
-// Get order
-const order = await basket.placeOrder(orderData);
-
-// Direct property access
-const items = order.items;
-const total = order.totalAmount;
-const status = order.status;
-const shipping = order.shippingAddress;
-
-// Display order summary
-console.log(`Order #${order.orderId}`);
-console.log(`Status: ${order.status}`);
-console.log(`Total: $${order.totalAmount}`);
-
-// Access order items
-order.items.forEach(item => {
-  console.log(`- ${item.name}: ${item.quantity} x $${item.price}`);
-});
-
-// Update shipping info
-await order.update({
-  trackingNumber: "1Z999AA10123456784",
-  carrier: "UPS",
-  estimatedDelivery: "2025-10-15"
-});
-
-// Update order status
-if (order.status === 'pending') {
-  await order.updateStatus(OrderStatus.PROCESSING);
-}
-
-// Add order notes
-await order.update({
-  notes: order.notes ? 
-    `${order.notes}\nPackage dispatched` : 
-    "Package dispatched"
-});
-
-// Check delivery address
-if (order.shippingAddress) {
-  console.log('Shipping to:', order.shippingAddress.city);
-}
-
-// Process based on status
-switch (order.status) {
-  case 'pending':
-    await order.updateStatus(OrderStatus.PROCESSING);
-    break;
-  case 'processing':
-    // Prepare shipment
-    break;
-  case 'shipped':
-    // Send tracking email
-    break;
-}
-```
-
-### Multi-Level Property Access
-
-The order checks three levels for properties:
-1. Instance properties (id, orderId, etc.)
-2. Data properties (items, shippingAddress, etc.)
-3. Common properties (status, totalAmount, createdAt, etc.)
-
-```typescript
-// All accessible directly
-order.orderId;          // Instance property
-order.items;            // Data property
-order.shippingAddress;  // Data property
-order.status;           // Common property (via proxy)
-order.totalAmount;      // Common property (via proxy)
-```
-
----
-
-## DataEntryInstance
-
-Custom data entry with search and update capabilities.
-
-### When It's Returned
-
-```typescript
-// From creating an entry
-const entry = await customData.create("users", {
-  name: "John Doe",
-  email: "john@example.com"
-}, "john doe email");
-// Returns DataEntryInstance
-
-// From search results
-const results = await customData.search("users", "john");
-const entry = results[0]; // DataEntryInstance
-
-// From getting by ID
-const entry = await customData.get("users", "entry-123");
-// Returns DataEntryInstance
-```
-
-### Properties
-
-- **`data`** - The custom data object
-- **`id`** - Entry ID
-- **`collectionName`** - Collection name
-- **`score`** - Search relevance score (optional)
-- All data fields accessible directly
-
-### Methods
-
-#### `update(data: Record<string, any>, searchText?: string): Promise<any>`
-
-Updates the entry data.
-
-```typescript
-await entry.update({
-  email: "newemail@example.com",
-  phone: "+1234567890"
-}, "john doe newemail phone");
-```
-
-#### `delete(): Promise<boolean>`
-
-Deletes the entry.
-
-```typescript
-await entry.delete();
-```
-
-### Usage Examples
-
-```typescript
-// Create entry
-const entry = await customData.create("contacts", {
-  name: "John Doe",
-  email: "john@example.com",
-  phone: "+1234567890",
-  company: "Acme Inc"
-}, "john doe acme email");
-
-// Direct property access
-const name = entry.name;
-const email = entry.email;
-const phone = entry.phone;
-const company = entry.company;
-
-// Check metadata
-console.log(`Entry ID: ${entry.id}`);
-console.log(`Collection: ${entry.collectionName}`);
-
-// Update entry
-await entry.update({
-  phone: "+9876543210",
-  department: "Engineering"
-}, "john doe engineering");
-
-// Search and update
-const results = await customData.search("contacts", "acme");
-
-for (const entry of results) {
-  if (entry.score > 0.8) {
-    console.log(`High relevance: ${entry.name} (score: ${entry.score})`);
-  }
-  
-  // Update based on search
-  if (entry.company === "Acme Inc") {
-    await entry.update({
-      verified: true,
-      lastContacted: new Date().toISOString()
-    });
-  }
-}
-
-// Delete old entries
-const oldEntries = await customData.search("contacts", "inactive");
-for (const entry of oldEntries) {
-  await entry.delete();
-}
-
-// Conditional updates
-if (entry.email && !entry.emailVerified) {
-  await entry.update({ emailVerified: true });
-}
-
-// Nested data access
-if (entry.address) {
-  console.log(`City: ${entry.address.city}`);
-}
-```
-
-### Search Scores
-
-When entries are returned from a search, they include a `score` property indicating relevance:
-
-```typescript
-const results = await customData.search("contacts", "john engineer");
-
-results.forEach(entry => {
-  console.log(`${entry.name}: ${entry.score}`);
-});
-
-// Filter by score
-const highRelevance = results.filter(entry => entry.score > 0.7);
-```
-
----
-
-## Common Patterns
-
-### Chaining Operations
-
-```typescript
-// Update and use result
-const user = await context.user.update({ name: "John" });
-console.log(user.name);
-
-// Create, update, and use
-const product = await products.create({ name: "Laptop" });
-await product.update({ price: 1299.99 });
-console.log(product.price);
-```
-
-### Error Handling
-
-```typescript
-try {
-  await product.update({ price: newPrice });
-} catch (error) {
-  console.error('Failed to update product:', error);
-}
-
-try {
-  await user.clear();
-} catch (error) {
-  console.error('Failed to clear user data:', error);
-}
-```
-
-### Conditional Operations
-
-```typescript
-// Check before operating
-if (product.stock < 10) {
-  await product.update({ lowStock: true });
-}
-
-if (basket.itemCount > 0) {
-  const order = await basket.placeOrder(orderData);
-}
-
-// Check existence
-if ('preferences' in user) {
-  const theme = user.preferences.theme;
-}
-```
-
-### Batch Operations
-
-```typescript
-// Update multiple products
-const products = await productsAPI.search("laptop");
-
-for (const product of products) {
-  if (product.price > 1000) {
-    await product.update({ premium: true });
-  }
-}
-
-// Process all pages
-let page = await productsAPI.get(1, 50);
-const allProducts = [];
-
-do {
-  allProducts.push(...page.products);
-  if (page.pagination.hasNextPage) {
-    page = await page.nextPage();
-  }
-} while (page.pagination.hasNextPage);
-```
-
-### Array Operations on Collections
-
-```typescript
-// Map and filter
-const searchResults = await products.search("laptop");
-
-const names = searchResults.map(p => p.name);
-const available = searchResults.filter(p => p.stock > 0);
-const sorted = [...searchResults].sort((a, b) => a.price - b.price);
-
-// Reduce for calculations
-const totalValue = searchResults.reduce((sum, p) => 
-  sum + (p.price * p.stock), 0
-);
-
-// Find specific items
-const cheapest = searchResults.reduce((min, p) => 
-  p.price < min.price ? p : min
-);
-
-const specific = searchResults.find(p => p.sku === "LAP-001");
-```
-
-### Iteration Patterns
-
-```typescript
-// For...of
-for (const product of searchResults) {
-  console.log(product.name);
-}
-
-// forEach with async
-searchResults.forEach(async (product) => {
-  await product.update({ viewed: true });
-});
-
-// Spread operator
-const allProducts = [...searchResults];
-
-// Array destructuring
-const [first, ...rest] = searchResults;
-```
-
-### Property Checks
-
-```typescript
-// Check if property exists
-if ('name' in user) {
-  console.log(user.name);
-}
-
-// Check if has value
-if (product.description) {
-  console.log(product.description);
-}
-
-// Get all keys
-const userKeys = Object.keys(user);
-const productKeys = Object.keys(product);
-```
-
----
-
-## TypeScript Support
-
-### Type Definitions
-
-All instances have proper TypeScript support with index signatures:
-
-```typescript
-// UserDataInstance
-interface UserDataInstance {
-  data: Record<string, any>;
-  [key: string]: any; // Allows dynamic property access
-  update(data: Record<string, any>): Promise<any>;
-  clear(): Promise<boolean>;
-}
-
-// ProductInstance
-interface ProductInstance {
-  data: Product;
-  [key: string]: any;
-  update(data: Record<string, any>): Promise<Product>;
-  delete(): Promise<Product>;
-}
-
-// ProductSearchInstance
-interface ProductSearchInstance {
-  products: ProductInstance[];
-  length: number;
-  map<T>(callback: ...): T[];
-  filter(callback: ...): ProductInstance[];
-  // ... other array methods
-}
-```
-
-### Using with Custom Types
-
-```typescript
-// Define your data shape
-interface UserPreferences {
-  theme: 'light' | 'dark';
-  notifications: boolean;
-  language: string;
-}
-
-interface MyUserData {
-  name: string;
-  email: string;
-  preferences: UserPreferences;
-}
-
-// Access with type checking
-const user = context.user;
-const prefs: UserPreferences = user.preferences;
-const theme: 'light' | 'dark' = user.preferences.theme;
-
-// Product data
-interface MyProduct {
-  name: string;
-  price: number;
-  sku: string;
-  stock: number;
-}
-
-const product = await products.create({...});
-const name: string = product.name;
-const price: number = product.price;
-```
-
-### Generic Array Methods
-
-```typescript
-// Map with type inference
-const prices: number[] = searchResults.map(p => p.price);
-const names: string[] = searchResults.map(p => p.name);
-
-// Type-safe reduce
-const total: number = searchResults.reduce((sum, p) => 
-  sum + p.price, 0
-);
-
-// Type-safe filter
-const available: ProductInstance[] = searchResults.filter(p => 
-  p.stock > 0
-);
-```
-
----
-
-## Best Practices
-
-### ✅ DO
-
-```typescript
-// Use direct property access
-const name = user.name;
-const price = product.price;
-
-// Use array methods on collections
-searchResults.map(p => p.name);
-paginatedResults.filter(p => p.stock > 0);
-
-// Update multiple fields at once
-await user.update({
-  field1: value1,
-  field2: value2
-});
-
-// Check property existence
-if ('preferences' in user) {
-  // Use preferences
-}
-
-// Use for...of for async operations
-for (const product of searchResults) {
-  await product.update({ viewed: true });
-}
-```
-
-### ❌ DON'T
-
-```typescript
-// Don't mutate without calling update()
-product.price = 999;
-// ❌ Only updates locally! Must call update()
-
-// Don't make multiple update calls
-await user.update({ field1: value1 });
-await user.update({ field2: value2 }); 
-// ✅ Combine: await user.update({ field1: value1, field2: value2 });
-
-// Don't assume sanitized fields exist
-console.log(user.userId);  // undefined (sanitized)
-console.log(user.agentId); // undefined (sanitized)
-
-// Don't use products.products when you can use products directly
-results.products.map(p => p.name); // ❌ Verbose
-results.map(p => p.name);          // ✅ Better
-```
-
----
-
-## Summary
-
-All instance classes now provide:
-
-1. **Direct Property Access** - Access nested data without `.data`
-2. **Array Methods** - Collections support `.map()`, `.filter()`, etc.
-3. **Iteration** - Use `for...of` loops and spread operators
-4. **Type Safety** - Full TypeScript support with index signatures
-5. **Backward Compatibility** - Old patterns still work
-
-This creates a more intuitive and JavaScript-friendly API while maintaining full backward compatibility with existing code.
-
----
-
-**Version:** 2.5.2  
-**Last Updated:** October 7, 2025  
-**License:** MIT