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

package/template/WEBHOOKS_JOBS_QUICKSTART.md

@@ -1,318 +0,0 @@
-# Webhooks & Jobs - Quick Start Guide
-
-Get started with webhooks and scheduled jobs in 5 minutes!
-
----
-
-## 🚀 What Are They?
-
-### **Webhooks** = HTTP Endpoints
-Receive requests from external systems (Stripe, Zapier, your own apps)
-
-**Example:** Stripe sends payment notification → Your webhook processes it
-
-### **Jobs** = Scheduled Tasks
-Run code at specific times or intervals
-
-**Example:** Every night at 2 AM → Clean up old data
-
----
-
-## 📦 Quick Start - Webhooks
-
-### Step 1: Uncomment Example
-
-In `src/index.ts`, uncomment:
-```typescript
-import userEventWebhook from "./webhooks/UserEventWebhook";
-```
-
-### Step 2: Compile
-```bash
-lua compile
-# ✅ Found 1 webhook(s)
-```
-
-### Step 3: Test
-```bash
-lua test webhook
-
-# Prompts:
-# - Query params: {"source": "test"}
-# - Headers: {"x-api-key": "your-secret-key"}
-# - Body: {"eventType": "signup", "userId": "123", "email": "test@example.com", "timestamp": "2025-01-15T10:00:00Z"}
-
-# Result: Webhook executes and stores event
-```
-
-### Step 4: Deploy
-```bash
-lua push webhook
-lua webhooks production
-# Select: Deploy a version
-```
-
-### Step 5: Get Your URL
-After deployment, your webhook URL is:
-```
-https://api.heylua.ai/webhooks/{agentId}/{webhookId}
-```
-
-Configure this in Stripe, Zapier, or your external system!
-
----
-
-## ⏰ Quick Start - Jobs
-
-### Step 1: Uncomment Example
-
-In `src/index.ts`, uncomment:
-```typescript
-import dailyCleanupJob from "./jobs/DailyCleanupJob";
-```
-
-### Step 2: Compile
-```bash
-lua compile
-# ✅ Found 1 job(s)
-```
-
-### Step 3: Test (runs immediately)
-```bash
-lua test job
-# Select: daily-cleanup
-# Job executes now (ignores schedule)
-```
-
-### Step 4: Deploy
-```bash
-lua push job
-lua jobs production
-# Select: Deploy a version
-# Job will now run on its schedule!
-```
-
-### Step 5: Monitor
-```bash
-lua jobs production
-# Select: View deployed jobs
-# See: last run, next run, status
-
-# Select: View execution history
-# See: all past executions, results, errors
-```
-
----
-
-## 🛒 Quick Start - Smart Baskets (Advanced)
-
-This combines tools + jobs for abandoned cart recovery!
-
-### Step 1: Enable Components
-
-In `src/index.ts`, uncomment:
-```typescript
-import { CreateSmartBasketTool, CheckAbandonedBasketsTool } from "./tools/SmartBasketTool";
-import abandonedBasketProcessorJob from "./jobs/AbandonedBasketProcessorJob";
-```
-
-And add to a skill:
-```typescript
-const basketSkill = new LuaSkill({
-  name: "basket-skill",
-  version: "1.0.0",
-  description: "Smart basket with abandoned cart recovery",
-  context: "Manages baskets and sends reminders for abandoned carts",
-  tools: [
-    new CreateSmartBasketTool(),
-    new CheckAbandonedBasketsTool()
-  ]
-});
-```
-
-### Step 2: Compile & Deploy
-```bash
-lua compile
-lua push skill
-lua push job
-lua jobs production  # Activate the processor job
-```
-
-### Step 3: Use It
-
-When a user creates a basket:
-```
-User: "Create a shopping cart"
-  ↓
-Agent uses: create_smart_basket
-  ↓
-Tool creates basket
-  ↓
-Tool schedules reminder (3 hours)
-  ↓
-Job checks every 15 minutes
-  ↓
-After 3 hours: Job checks if checked out
-  ↓
-If abandoned: Log and notify!
-```
-
----
-
-## 📚 Available Examples
-
-### Webhooks (`src/webhooks/`)
-
-| File | Purpose | Complexity |
-|------|---------|------------|
-| **UserEventWebhook.ts** | Receive user events from external systems | ⭐ Easy |
-| **PaymentWebhook.ts** | Process payment notifications (Stripe) | ⭐⭐ Medium |
-
-### Jobs (`src/jobs/`)
-
-| File | Schedule Type | Purpose | Complexity |
-|------|--------------|---------|------------|
-| **DailyCleanupJob.ts** | Cron (daily) | Clean old data | ⭐⭐ Medium |
-| **HealthCheckJob.ts** | Interval (5 min) | Monitor system health | ⭐ Easy |
-| **DataMigrationJob.ts** | Once (specific date) | One-time migration | ⭐⭐⭐ Advanced |
-| **AbandonedBasketProcessorJob.ts** | Interval (15 min) | Process cart reminders | ⭐⭐⭐ Advanced |
-
-### Tools (`src/tools/`)
-
-| File | Purpose | Complexity |
-|------|---------|------------|
-| **SmartBasketTool.ts** | Create basket + schedule reminder | ⭐⭐⭐ Advanced |
-
----
-
-## 🔧 Customization Guide
-
-### Customize Webhook
-
-```typescript
-// Change what events you accept
-bodySchema: z.object({
-  eventType: z.enum(['signup', 'update', 'delete', 'login']), // Add 'login'
-  // ... rest
-}),
-
-// Add your processing logic
-execute: async ({ body }) => {
-  if (body.eventType === 'login') {
-    // Track login events
-    await Data.create('login-logs', body);
-  }
-  return { success: true };
-}
-```
-
-### Customize Job Schedule
-
-```typescript
-// Change from daily to weekly
-schedule: {
-  type: 'cron',
-  expression: '0 2 * * 0',  // Sunday at 2 AM
-  timezone: 'America/New_York'
-}
-
-// Or change to hourly
-schedule: {
-  type: 'interval',
-  seconds: 3600  // Every hour
-}
-```
-
-### Customize Reminder Timing
-
-In SmartBasketTool.ts:
-```typescript
-// Change from 3 hours to 1 hour
-const checkTime = new Date(Date.now() + 1 * 60 * 60 * 1000);
-
-// Or 24 hours
-const checkTime = new Date(Date.now() + 24 * 60 * 60 * 1000);
-```
-
----
-
-## 🧪 Testing Workflow
-
-### Test Webhook Locally
-```bash
-lua test webhook
-# Enter test data
-# See validation and execution
-
-# Example test data:
-{
-  "eventType": "signup",
-  "userId": "test_123",
-  "email": "test@example.com",
-  "name": "Test User",
-  "timestamp": "2025-01-15T10:00:00Z"
-}
-```
-
-### Test Job Locally
-```bash
-lua test job
-# Job runs immediately
-# Ignore schedule for testing
-# See execution result
-```
-
-### Test Smart Basket
-```bash
-lua test skill
-# Select: create_smart_basket
-# Enter: currency: USD
-# See basket created + reminder scheduled
-```
-
----
-
-## 🚨 Common Issues
-
-### "Webhook not found"
-**Cause:** Haven't enabled webhook in index.ts  
-**Fix:** Uncomment the import
-
-### "Job not running"
-**Cause:** Job not activated in production  
-**Fix:** 
-```bash
-lua jobs production
-# Select: Activate a job
-```
-
-### "Reminder not processed"
-**Cause:** Processor job not running  
-**Fix:** Enable and activate `AbandonedBasketProcessorJob`
-
----
-
-## 💡 Next Steps
-
-### Learn More
-1. Read `WEBHOOK_JOB_EXAMPLES.md` for detailed explanations
-2. Check `TOOL_EXAMPLES.md` for tool patterns
-3. See main docs for API reference
-
-### Build Your Own
-1. Copy an example file
-2. Rename and modify
-3. Test locally
-4. Deploy to production
-
-### Get Help
-- 📖 [Webhook API Spec](../WEBHOOK_API_SPEC.md)
-- 📖 [Job API Spec](../JOB_API_SPEC.md)
-- 📖 [Full Usage Guide](../WEBHOOKS_JOBS_USAGE_GUIDE.md)
-
----
-
-**Ready to build powerful integrations!** 🎉
-
-Try enabling one webhook and one job, compile, and test them out!
-