# Lua CLI - Complete API Documentation

Welcome to the comprehensive API documentation for lua-cli v3.5.0-alpha.5. 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.5
**Last Updated:** February 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');
```

