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

package/template/WEBHOOK_JOB_EXAMPLES.md

@@ -1,817 +0,0 @@
-# Webhook & Job Examples
-
-Complete examples for creating webhooks, scheduled jobs, and dynamic job creation from tools.
-
----
-
-## 📋 Table of Contents
-
-- [Webhook Examples](#webhook-examples)
-  - [User Event Webhook](#1-user-event-webhook)
-  - [Payment Webhook](#2-payment-webhook)
-- [Job Examples](#job-examples)
-  - [Daily Cleanup Job](#1-daily-cleanup-job)
-  - [Health Check Job](#2-health-check-job)
-  - [Data Migration Job](#3-data-migration-job)
-  - [Abandoned Basket Processor](#4-abandoned-basket-processor-job)
-- [Dynamic Job Creation](#dynamic-job-creation)
-  - [Smart Basket Tool](#smart-basket-tool)
-- [Complete Integration Example](#complete-integration-example)
-
----
-
-## Webhook Examples
-
-Webhooks are HTTP endpoints that receive requests from external systems.
-
-### 1. User Event Webhook
-
-**File:** `src/webhooks/UserEventWebhook.ts`
-
-**What it does:** Receives user events from external systems (CRM, marketing tools, etc.).
-
-**Use cases:**
-- User signup notifications from external auth systems
-- Profile updates from CRM
-- User deletion events for GDPR compliance
-
-**Key features:**
-- ✅ Query parameter validation (source tracking)
-- ✅ Header validation (API key security)
-- ✅ Body validation (event data)
-- ✅ Stores events in custom data
-
-**Code highlights:**
-```typescript
-const webhook = new LuaWebhook({
-  name: "user-events",
-  
-  // Optional query params for tracking
-  querySchema: z.object({
-    source: z.string().optional()
-  }),
-  
-  // Require API key in headers
-  headerSchema: z.object({
-    'x-api-key': z.string()
-  }),
-  
-  // Event data validation
-  bodySchema: z.object({
-    eventType: z.enum(['signup', 'update', 'delete']),
-    userId: z.string(),
-    email: z.string().email()
-  }),
-  
-  execute: async ({ query, headers, body }) => {
-    // Validate API key
-    if (headers['x-api-key'] !== expectedKey) {
-      throw new Error('Invalid API key');
-    }
-    
-    // Store event
-    await Data.create('user-events', {
-      ...body,
-      source: query?.source,
-      receivedAt: new Date().toISOString()
-    });
-    
-    return { success: true };
-  }
-});
-```
-
-**How to call it:**
-```bash
-curl -X POST \
-  https://api.heylua.ai/webhooks/{agentId}/{webhookId} \
-  -H "Content-Type: application/json" \
-  -H "x-api-key: your-secret-key" \
-  -d '{
-    "eventType": "signup",
-    "userId": "user_123",
-    "email": "new@example.com"
-  }'
-```
-
----
-
-### 2. Payment Webhook
-
-**File:** `src/webhooks/PaymentWebhook.ts`
-
-**What it does:** Receives payment notifications from Stripe, PayPal, etc.
-
-**Use cases:**
-- Payment confirmation processing
-- Order status updates
-- Failed payment handling
-- Transaction logging
-
-**Key features:**
-- ✅ Stripe signature validation (security)
-- ✅ Multiple event type handling
-- ✅ Order status updates
-- ✅ Payment logging
-
-**Code highlights:**
-```typescript
-const webhook = new LuaWebhook({
-  name: "payment-notifications",
-  
-  headerSchema: z.object({
-    'stripe-signature': z.string().optional()
-  }),
-  
-  bodySchema: z.object({
-    type: z.string(),
-    data: z.object({
-      object: z.object({
-        id: z.string(),
-        amount: z.number(),
-        metadata: z.object({
-          orderId: z.string().optional()
-        }).optional()
-      })
-    })
-  }),
-  
-  execute: async ({ body }) => {
-    if (body.type === 'payment_intent.succeeded') {
-      // Update order status
-      if (body.data.object.metadata?.orderId) {
-        await Orders.updateStatus('confirmed', 
-          body.data.object.metadata.orderId);
-      }
-      
-      // Log payment
-      await Data.create('payment-logs', {
-        paymentId: body.data.object.id,
-        amount: body.data.object.amount,
-        status: 'succeeded'
-      });
-    }
-    
-    return { success: true };
-  }
-});
-```
-
-**Stripe integration:**
-```typescript
-// In Stripe dashboard, configure webhook URL:
-// https://api.heylua.ai/webhooks/{agentId}/{webhookId}
-
-// Select events to send:
-// - payment_intent.succeeded
-// - payment_intent.payment_failed
-```
-
----
-
-## Job Examples
-
-Jobs are scheduled tasks that run at specific times or intervals.
-
-### 1. Daily Cleanup Job
-
-**File:** `src/jobs/DailyCleanupJob.ts`
-
-**What it does:** Runs daily at 2 AM to clean up old data.
-
-**Use cases:**
-- Remove old logs
-- Archive expired data
-- Database maintenance
-- Cost optimization
-
-**Schedule:** Cron (daily at 2 AM EST)
-
-**Key features:**
-- ✅ Cron scheduling with timezone
-- ✅ Multiple data collection cleanup
-- ✅ Retry on failure
-- ✅ Performance tracking
-
-**Code highlights:**
-```typescript
-const job = new LuaJob({
-  name: "daily-cleanup",
-  
-  schedule: {
-    type: 'cron',
-    expression: '0 2 * * *',  // 2 AM daily
-    timezone: 'America/New_York'
-  },
-  
-  timeout: 600,  // 10 minutes
-  
-  retry: {
-    maxAttempts: 3,
-    backoffSeconds: 60
-  },
-  
-  execute: async () => {
-    // Clean old user events (90+ days)
-    const ninetyDaysAgo = new Date(Date.now() - 90 * 24 * 60 * 60 * 1000);
-    const oldEvents = await Data.get('user-events', {});
-    
-    let deleted = 0;
-    for (const event of oldEvents) {
-      if (new Date(event.receivedAt) < ninetyDaysAgo) {
-        await Data.delete('user-events', event.id);
-        deleted++;
-      }
-    }
-    
-    return { recordsDeleted: deleted };
-  }
-});
-```
-
-**Cron expressions:**
-```
-'0 2 * * *'     - Daily at 2 AM
-'0 */6 * * *'   - Every 6 hours
-'0 0 * * 0'     - Weekly on Sunday at midnight
-'0 0 1 * *'     - Monthly on 1st at midnight
-'*/30 * * * *'  - Every 30 minutes
-```
-
----
-
-### 2. Health Check Job
-
-**File:** `src/jobs/HealthCheckJob.ts`
-
-**What it does:** Runs every 5 minutes to monitor system health.
-
-**Use cases:**
-- API health monitoring
-- Database connectivity checks
-- Uptime tracking
-- Performance monitoring
-
-**Schedule:** Interval (every 5 minutes)
-
-**Key features:**
-- ✅ Interval-based scheduling
-- ✅ Multiple service checks
-- ✅ Health metric logging
-- ✅ Alert on failures
-
-**Code highlights:**
-```typescript
-const job = new LuaJob({
-  name: "health-check",
-  
-  schedule: {
-    type: 'interval',
-    seconds: 300  // Every 5 minutes
-  },
-  
-  timeout: 30,
-  
-  execute: async () => {
-    const checks: any = {};
-    
-    // Check database
-    try {
-      await Data.get('health-checks', {}, 1, 1);
-      checks.database = { status: 'healthy' };
-    } catch (error) {
-      checks.database = { status: 'unhealthy', error };
-    }
-    
-    // Check Products API
-    try {
-      await Products.get(1, 1);
-      checks.productsApi = { status: 'healthy' };
-    } catch (error) {
-      checks.productsApi = { status: 'unhealthy', error };
-    }
-    
-    const allHealthy = Object.values(checks)
-      .every((c: any) => c.status === 'healthy');
-    
-    // Log health status
-    await Data.create('health-checks', {
-      status: allHealthy ? 'healthy' : 'degraded',
-      checks,
-      timestamp: new Date().toISOString()
-    });
-    
-    return { status: allHealthy ? 'healthy' : 'degraded', checks };
-  }
-});
-```
-
----
-
-### 3. Data Migration Job
-
-**File:** `src/jobs/DataMigrationJob.ts`
-
-**What it does:** One-time migration at a specific date/time.
-
-**Use cases:**
-- Schema migrations
-- Data format updates
-- One-time data processing
-- Scheduled maintenance tasks
-
-**Schedule:** Once (specific date/time)
-
-**Key features:**
-- ✅ One-time execution
-- ✅ Batch processing
-- ✅ Progress logging
-- ✅ Migration reports
-
-**Code highlights:**
-```typescript
-const job = new LuaJob({
-  name: "migrate-user-schema",
-  
-  schedule: {
-    type: 'once',
-    executeAt: new Date('2025-12-31T02:00:00Z')
-  },
-  
-  timeout: 1800,  // 30 minutes for large migrations
-  
-  retry: {
-    maxAttempts: 3,
-    backoffSeconds: 300
-  },
-  
-  execute: async () => {
-    const oldEvents = await Data.get('user-events', {});
-    let migrated = 0;
-    
-    for (const event of oldEvents) {
-      // Transform to new schema
-      const newEvent = {
-        eventId: event.id,
-        eventType: event.type || 'unknown',
-        userId: event.userId || event.user_id,
-        // ... transform other fields
-      };
-      
-      await Data.create('user-events-v2', newEvent);
-      migrated++;
-      
-      if (migrated % 100 === 0) {
-        console.log(`Migrated ${migrated} records...`);
-      }
-    }
-    
-    return { migrated };
-  }
-});
-```
-
----
-
-### 4. Abandoned Basket Processor Job
-
-**File:** `src/jobs/AbandonedBasketProcessorJob.ts`
-
-**What it does:** Processes basket checkout reminders created by tools.
-
-**This is the companion job for SmartBasketTool!**
-
-**Schedule:** Interval (every 15 minutes)
-
-**Code highlights:**
-```typescript
-const job = new LuaJob({
-  name: "process-basket-reminders",
-  
-  schedule: {
-    type: 'interval',
-    seconds: 900  // 15 minutes
-  },
-  
-  execute: async () => {
-    // Get pending reminders
-    const reminders = await Data.get('basket-reminders', {});
-    const now = new Date();
-    
-    for (const reminder of reminders) {
-      if (new Date(reminder.scheduledFor) > now) continue;
-      if (reminder.status !== 'pending') continue;
-      
-      // Check basket status
-      const basket = await Baskets.getById(reminder.basketId);
-      
-      if (basket.status === 'active') {
-        // Abandoned! Send reminder
-        await Data.create('abandoned-baskets', {
-          basketId: basket.id,
-          abandonedAt: new Date().toISOString()
-        });
-        
-        // TODO: Send email/SMS reminder
-      }
-      
-      // Mark as processed
-      await Data.update('basket-reminders', reminder.id, {
-        status: 'completed'
-      });
-    }
-    
-    return { success: true };
-  }
-});
-```
-
----
-
-## Dynamic Job Creation
-
-### Smart Basket Tool
-
-**File:** `src/tools/SmartBasketTool.ts`
-
-**What it does:** Creates a basket AND schedules a reminder to check for abandonment.
-
-**This demonstrates creating jobs from within tools!**
-
-**The Flow:**
-```
-User: "Create a basket"
-       ↓
-Tool: Creates basket
-       ↓
-Tool: Schedules reminder (3 hours later)
-       ↓
-Job: Checks if basket was checked out
-       ↓
-If abandoned → Send reminder email
-```
-
-**Code highlights:**
-```typescript
-export class CreateSmartBasketTool implements LuaTool {
-  name = "create_smart_basket";
-  description = "Creates basket with auto-reminder";
-  
-  async execute(input: { currency: string }) {
-    // 1. Create basket
-    const basket = await Baskets.create({ 
-      currency: input.currency 
-    });
-    
-    // 2. Schedule reminder for 3 hours later
-    const checkTime = new Date(Date.now() + 3 * 60 * 60 * 1000);
-    
-    await Data.create('basket-reminders', {
-      type: 'basket-checkout-reminder',
-      basketId: basket.id,
-      scheduledFor: checkTime.toISOString(),
-      status: 'pending'
-    });
-    
-    return {
-      basket,
-      reminder: {
-        scheduledFor: checkTime.toISOString()
-      }
-    };
-  }
-}
-```
-
-**How it works:**
-
-1. **Tool creates basket** → Returns basket ID to user
-2. **Tool creates reminder** → Stores in custom data with future timestamp
-3. **Recurring job runs** → Every 15 minutes, checks for due reminders
-4. **Job processes reminder** → Checks if basket is still active
-5. **If abandoned** → Sends reminder email/notification
-
-**Companion tool:**
-```typescript
-export class CheckAbandonedBasketsTool implements LuaTool {
-  name = "check_abandoned_baskets";
-  
-  async execute(input: { basketId?: string }) {
-    const reminders = await Data.get('basket-reminders', {});
-    
-    for (const reminder of reminders) {
-      const basket = await Baskets.getById(reminder.basketId);
-      
-      if (basket.status === 'active') {
-        // Abandoned!
-        await Data.create('abandoned-baskets', {
-          basketId: basket.id,
-          abandonedAt: new Date().toISOString()
-        });
-      }
-    }
-    
-    return { success: true };
-  }
-}
-```
-
----
-
-## Complete Integration Example
-
-Here's how to use all these features together in your `src/index.ts`:
-
-```typescript
-import { LuaSkill } from "lua-cli";
-
-// Import webhooks
-import userEventWebhook from "./webhooks/UserEventWebhook";
-import paymentWebhook from "./webhooks/PaymentWebhook";
-
-// Import jobs
-import dailyCleanupJob from "./jobs/DailyCleanupJob";
-import healthCheckJob from "./jobs/HealthCheckJob";
-import dataMigrationJob from "./jobs/DataMigrationJob";
-import abandonedBasketProcessorJob from "./jobs/AbandonedBasketProcessorJob";
-
-// Import tools
-import { CreateSmartBasketTool, CheckAbandonedBasketsTool } from "./tools/SmartBasketTool";
-
-// Create skill with tools
-const basketSkill = new LuaSkill({
-  name: "basket-skill",
-  version: "1.0.0",
-  description: "Smart basket management with abandoned cart recovery",
-  context: "This skill manages shopping baskets and automatically sends reminders for abandoned carts.",
-  tools: [
-    new CreateSmartBasketTool(),
-    new CheckAbandonedBasketsTool()
-  ]
-});
-
-// Note: Webhooks and Jobs are standalone, not added to skills
-// They are detected automatically during compilation
-```
-
----
-
-## Testing Examples
-
-### Test Webhook
-```bash
-lua test webhook
-
-# You'll be prompted for:
-# - Query params: {"source": "mobile"}
-# - Headers: {"x-api-key": "test-key"}
-# - Body: {"eventType": "signup", "userId": "123", "email": "test@example.com"}
-
-# Output: Webhook executes and returns result
-```
-
-### Test Job
-```bash
-lua test job
-
-# Select job to test
-# Job executes immediately (ignores schedule)
-# See result
-```
-
-### Test Tool
-```bash
-lua test skill
-
-# Select: create_smart_basket
-# Enter: currency: USD
-# Tool creates basket AND schedules reminder!
-```
-
----
-
-## Deployment Workflow
-
-```bash
-# 1. Compile everything
-lua compile
-# ✅ Detects: tools, webhooks, jobs
-# ✅ Creates webhook/job IDs on backend
-# ✅ Updates lua.skill.yaml
-
-# 2. Test locally
-lua test skill
-lua test webhook
-lua test job
-
-# 3. Push to server
-lua push skill
-lua push webhook
-lua push job
-
-# 4. Deploy to production
-lua skills production      # Deploy skill
-lua webhooks production    # Deploy webhook
-lua jobs production        # Deploy and activate job
-```
-
----
-
-## Advanced Patterns
-
-### Pattern 1: Webhook → Data → Job
-
-**Flow:** Webhook receives data → Stores in DB → Job processes later
-
-```typescript
-// Webhook: Receive order
-const orderWebhook = new LuaWebhook({
-  execute: async ({ body }) => {
-    await Data.create('pending-orders', body);
-    return { queued: true };
-  }
-});
-
-// Job: Process orders every hour
-const processOrdersJob = new LuaJob({
-  schedule: { type: 'interval', seconds: 3600 },
-  execute: async () => {
-    const pending = await Data.get('pending-orders', {});
-    for (const order of pending) {
-      // Process order
-      await Orders.create(order);
-      await Data.delete('pending-orders', order.id);
-    }
-  }
-});
-```
-
----
-
-### Pattern 2: Tool → Job → Webhook
-
-**Flow:** Tool triggers job → Job processes → Webhook notifies external system
-
-```typescript
-// Tool: Start export
-class ExportDataTool implements LuaTool {
-  async execute(input: any) {
-    // Trigger export job
-    await Jobs.trigger('job_export_data');
-    return { started: true };
-  }
-}
-
-// Job: Export data
-const exportJob = new LuaJob({
-  execute: async () => {
-    const data = await Data.get('users', {});
-    // Export logic...
-    
-    // Notify webhook when done
-    // (Webhook would be configured to notify admin)
-    return { exported: data.length };
-  }
-});
-```
-
----
-
-### Pattern 3: Scheduled Job Creates Dynamic Jobs
-
-**Flow:** Recurring job → Checks conditions → Creates one-time jobs as needed
-
-```typescript
-const monitorJob = new LuaJob({
-  name: "monitor-and-schedule",
-  schedule: { type: 'cron', expression: '0 * * * *' }, // Hourly
-  
-  execute: async () => {
-    const orders = await Orders.get();
-    
-    for (const order of orders) {
-      if (order.status === 'pending' && needsFollowUp(order)) {
-        // Schedule a one-time follow-up job
-        await Data.create('follow-up-jobs', {
-          orderId: order.id,
-          scheduledFor: new Date(Date.now() + 24 * 60 * 60 * 1000),
-          type: 'order-follow-up'
-        });
-      }
-    }
-  }
-});
-```
-
----
-
-## 🎯 Recommended Usage
-
-### When to Use Webhooks
-- ✅ Receiving data from external systems
-- ✅ Real-time event processing
-- ✅ Third-party integrations (Stripe, Zapier, etc.)
-- ✅ API callbacks
-
-### When to Use Jobs
-- ✅ Scheduled maintenance (cleanup, backups)
-- ✅ Recurring reports (daily/weekly reports)
-- ✅ Batch processing (process queued items)
-- ✅ Monitoring and health checks
-- ✅ One-time migrations
-
-### When to Create Jobs from Tools
-- ✅ User-initiated scheduled actions
-- ✅ Delayed follow-ups (abandoned cart, renewal reminders)
-- ✅ Conditional future actions
-- ✅ Dynamic scheduling based on business logic
-
----
-
-## 📚 Learning Path
-
-### Beginner
-1. ✅ Read UserEventWebhook.ts (simple webhook)
-2. ✅ Read HealthCheckJob.ts (simple job)
-3. ✅ Test them locally
-
-### Intermediate
-4. ✅ Read PaymentWebhook.ts (real-world webhook)
-5. ✅ Read DailyCleanupJob.ts (practical cron job)
-6. ✅ Modify and deploy
-
-### Advanced
-7. ✅ Read SmartBasketTool.ts (dynamic job creation)
-8. ✅ Read AbandonedBasketProcessorJob.ts (companion job)
-9. ✅ Build your own integrated system
-
----
-
-## 🚀 Quick Start
-
-### 1. Enable the examples
-```typescript
-// In src/index.ts
-import userEventWebhook from "./webhooks/UserEventWebhook";
-import dailyCleanupJob from "./jobs/DailyCleanupJob";
-
-// They're automatically detected during compilation!
-```
-
-### 2. Compile
-```bash
-lua compile
-# ✅ Found 1 webhook(s), 1 job(s)
-```
-
-### 3. Test
-```bash
-lua test webhook
-lua test job
-```
-
-### 4. Deploy
-```bash
-lua push webhook
-lua push job
-lua webhooks production  # Activate
-lua jobs production      # Activate and start scheduling
-```
-
----
-
-## 💡 Tips
-
-### Webhooks
-- Always validate input with schemas
-- Use API keys for security
-- Keep execution under 30 seconds
-- Return structured responses
-- Log important events
-
-### Jobs
-- Use appropriate schedule type (cron/interval/once)
-- Set reasonable timeouts
-- Configure retries for critical jobs
-- Log execution results
-- Monitor execution history
-
-### Dynamic Jobs from Tools
-- Store job configuration in custom data
-- Use a recurring job to process scheduled items
-- Include enough context to execute the job later
-- Clean up processed job records
-
----
-
-## 📖 Related Documentation
-
-- **[WEBHOOK_API_SPEC.md](../WEBHOOK_API_SPEC.md)** - Complete webhook API reference
-- **[JOB_API_SPEC.md](../JOB_API_SPEC.md)** - Complete job API reference
-- **[WEBHOOKS_JOBS_USAGE_GUIDE.md](../WEBHOOKS_JOBS_USAGE_GUIDE.md)** - Detailed usage guide
-- **[TOOL_EXAMPLES.md](./TOOL_EXAMPLES.md)** - Tool examples
-
----
-
-**Ready to build powerful integrations with webhooks and scheduled jobs!** 🚀
-