lua-cli 3.5.0-alpha.3 → 3.5.0-beta.1

package/docs/README.md

@@ -0,0 +1,270 @@
+# Lua CLI - Complete API Documentation
+
+Welcome to the comprehensive API documentation for lua-cli v3.5.0-alpha.3. This guide covers every API, class, and function exported by the package.
+
+## 📚 Documentation Index
+
+### Core Primitives
+- [LuaAgent](./api/LuaAgent.md) - Unified agent configuration
+- [LuaSkill](./api/LuaSkill.md) - Tool collections
+- [LuaTool](./api/LuaTool.md) - Individual tools
+- [LuaWebhook](./api/LuaWebhook.md) - HTTP endpoints for external integrations
+- [LuaJob](./api/LuaJob.md) - Scheduled tasks (cron, once, interval)
+- [PreProcessor](./api/PreProcessor.md) - Message preprocessing (block/modify messages)
+- [PostProcessor](./api/PostProcessor.md) - Response postprocessing (format/enhance responses)
+- LuaMCPServer - MCP server integration (also auto-created via `lua integrations` command)
+
+### Runtime APIs
+- [User API](./api/User.md) - User data management
+- [Products API](./api/Products.md) - Product catalog (with filter support)
+- [Data API](./api/Data.md) - Custom data storage with vector search
+- [Jobs API](./api/Jobs.md) - Dynamic job creation
+- [AI API](./api/AI.md) - AI text generation
+- [Baskets API](./api/Baskets.md) - Shopping cart management
+- [Orders API](./api/Orders.md) - Order management and fulfillment
+- [Templates API](./api/Templates.md) - WhatsApp template messages
+- [CDN API](./api/CDN.md) - File upload/download
+- Lua Runtime - Channel detection (`import { Lua } from 'lua-cli'`)
+
+### Utilities
+- `env()` - Environment variable access (`import { env } from 'lua-cli'`)
+- `BasketStatus` - Basket state enum
+- `OrderStatus` - Order state enum
+
+---
+
+## 🚀 Quick Reference
+
+### Import Everything
+
+```typescript
+import {
+  // Core Primitives
+  LuaAgent,
+  LuaSkill,
+  LuaTool,
+  LuaWebhook,
+  LuaJob,
+  PreProcessor,
+  PostProcessor,
+  
+  // Runtime APIs
+  User,
+  Products,
+  Baskets,
+  Orders,
+  Data,
+  Jobs,
+  Webhooks,
+  
+  // Instances
+  UserDataInstance,
+  ProductInstance,
+  BasketInstance,
+  OrderInstance,
+  DataEntryInstance,
+  JobInstance,
+  
+  // Enums
+  BasketStatus,
+  OrderStatus,
+  
+  // Utilities
+  env
+} from 'lua-cli';
+```
+
+### Common Patterns
+
+#### Create a Tool
+```typescript
+import { LuaTool } from 'lua-cli/skill';
+import { z } from 'zod';
+
+export default class MyTool implements LuaTool {
+  name = 'my_tool';
+  description = 'Tool description';
+  inputSchema = z.object({ param: z.string() });
+  
+  async execute(input: z.infer<typeof this.inputSchema>) {
+    return { result: 'success' };
+  }
+}
+```
+
+#### Create an Agent
+```typescript
+import { LuaAgent, LuaSkill } from 'lua-cli';
+
+export const agent = new LuaAgent({
+  name: 'my-agent',
+  persona: 'Agent personality...',
+  skills: [skill1, skill2]
+});
+```
+
+#### Use Runtime APIs
+```typescript
+import { User, Products, Data } from 'lua-cli';
+
+const user = await User.get();
+const products = await Products.get();
+await Data.create('notes', { text: 'Hello' });
+```
+
+---
+
+## 📖 By Category
+
+### For Building Agents
+- Start with [LuaAgent](./api/LuaAgent.md)
+- Learn about [LuaSkill](./api/LuaSkill.md)
+- Create [LuaTool](./api/LuaTool.md)
+- Build [LuaWebhook](./api/LuaWebhook.md) integrations
+- Schedule [LuaJob](./api/LuaJob.md) tasks
+
+### For Data Management
+- [User API](./api/User.md) - User profiles
+- [Data API](./api/Data.md) - Custom collections
+- [Products API](./api/Products.md) - Product catalog
+
+### For E-commerce
+- [Products API](./api/Products.md) - Product catalog
+- [Baskets API](./api/Baskets.md) - Shopping carts
+- [Orders API](./api/Orders.md) - Order fulfillment
+
+### For Automation
+- [LuaJob](./api/LuaJob.md) - Scheduled tasks (cron, intervals)
+- [Jobs API](./api/Jobs.md) - Dynamic job creation from tools
+- [LuaWebhook](./api/LuaWebhook.md) - HTTP endpoints for external triggers
+
+### For Message Processing
+- [PreProcessor](./api/PreProcessor.md) - Filter/modify incoming messages
+- [PostProcessor](./api/PostProcessor.md) - Format/enhance agent responses
+
+### For Third-Party Integrations
+- `lua integrations` command - Connect accounts (Linear, Discord, Google Calendar, etc.)
+- Auto-creates MCP servers for connected integrations
+
+---
+
+## 🎯 Learning Path
+
+### Beginner
+1. Read [LuaAgent](./api/LuaAgent.md) - Understand agent configuration
+2. Read [LuaTool](./api/LuaTool.md) - Learn to create tools
+3. Read [LuaSkill](./api/LuaSkill.md) - Organize tools into skills
+
+### Intermediate
+1. [User API](./api/User.md) - Work with user data
+2. [Products API](./api/Products.md) - Manage products
+3. [Data API](./api/Data.md) - Use custom storage
+
+### Advanced
+1. [LuaJob](./api/LuaJob.md) - Schedule automated tasks
+2. [Jobs API](./api/Jobs.md) - Create jobs dynamically
+3. [LuaWebhook](./api/LuaWebhook.md) - Build integrations
+4. [PreProcessor](./api/PreProcessor.md) & [PostProcessor](./api/PostProcessor.md)
+
+---
+
+## 🔍 Search by Use Case
+
+### "I want to..."
+
+**...build a simple chatbot**
+→ [LuaAgent](./api/LuaAgent.md) + [LuaTool](./api/LuaTool.md)
+
+**...access user data**
+→ [User API](./api/User.md)
+
+**...manage products**
+→ [Products API](./api/Products.md)
+
+**...create a shopping cart**
+→ [Baskets API](./api/Baskets.md)
+
+**...process orders**
+→ [Orders API](./api/Orders.md)
+
+**...store custom data**
+→ [Data API](./api/Data.md)
+
+**...schedule automated tasks**
+→ [LuaJob](./api/LuaJob.md)
+
+**...receive webhooks**
+→ [LuaWebhook](./api/LuaWebhook.md)
+
+**...create jobs from tools**
+→ [Jobs API](./api/Jobs.md)
+
+**...filter incoming messages**
+→ [PreProcessor](./api/PreProcessor.md)
+
+**...format responses**
+→ [PostProcessor](./api/PostProcessor.md)
+
+**...send WhatsApp templates**
+→ [Templates API](./api/Templates.md)
+
+**...upload/download files**
+→ [CDN API](./api/CDN.md)
+
+---
+
+## 📝 Documentation Standards
+
+Each API doc includes:
+- ✅ Overview and purpose
+- ✅ Type definitions
+- ✅ Complete method reference
+- ✅ Parameters and return types
+- ✅ Code examples
+- ✅ Common patterns
+- ✅ Error handling
+- ✅ Best practices
+
+---
+
+## 💡 Tips
+
+- All examples are runnable TypeScript code
+- Copy-paste examples as starting points
+- Type definitions are in each doc
+- Examples show both simple and advanced usage
+- Error handling patterns included
+
+---
+
+## 🔗 External Resources
+
+- [Zod Documentation](https://zod.dev/) - For schema validation
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/) - Language reference
+- [Lua Platform Docs](https://docs.heylua.ai) - Platform guides
+
+---
+
+**Version:** 3.5.0-alpha.2  
+**Last Updated:** January 2026
+
+---
+
+## Additional Utilities
+
+### Lua Runtime
+```typescript
+import { Lua } from 'lua-cli';
+
+if (Lua.request.channel === 'whatsapp') {
+  // WhatsApp-specific logic
+}
+```
+
+### env() Utility
+```typescript
+import { env } from 'lua-cli';
+
+const apiKey = env('MY_API_KEY');
+```
+