lua-cli 3.1.0-alpha.4 → 3.1.0-alpha.5

package/template/examples/README.md

@@ -0,0 +1,106 @@
+# 📚 Example Code
+
+This folder contains example implementations of all Lua AI Agent features. Use these as reference when building your own agent.
+
+## 📁 What's Inside
+
+### skills/
+Example skills and tools demonstrating platform APIs:
+
+| File | What it shows |
+|------|--------------|
+| `tools/GetWeatherTool.ts` | External API integration |
+| `tools/UserDataTool.ts` | User API - get/update user data, chat history, AI generation |
+| `tools/ProductsTool.ts` | Products API - CRUD operations |
+| `tools/BasketTool.ts` | Baskets API - shopping cart |
+| `tools/OrderTool.ts` | Orders API - order management, status & data updates |
+| `tools/CustomDataTool.ts` | Data API - custom collections with semantic search |
+| `tools/PaymentTool.ts` | Stripe integration, environment variables |
+| `tools/SmartBasketTool.ts` | Dynamic job creation from tools |
+| `tools/GameScoreTrackerTool.ts` | Jobs API - interval jobs, deactivation, getAll |
+
+### webhooks/
+HTTP endpoints for external integrations:
+
+| File | What it shows |
+|------|--------------|
+| `PaymentWebhook.ts` | Stripe payment notifications, Orders API |
+| `UserEventWebhook.ts` | External events, **Templates API** (WhatsApp) |
+| `FileUploadWebhook.ts` | **CDN API** - file uploads, Data API |
+
+### jobs/
+Scheduled background tasks:
+
+| File | What it shows |
+|------|--------------|
+| `HealthCheckJob.ts` | Interval schedule, health monitoring |
+| `DailyCleanupJob.ts` | Cron schedule, data cleanup |
+| `DataMigrationJob.ts` | One-time schedule, batch processing |
+| `AbandonedBasketProcessorJob.ts` | **Templates API** (WhatsApp), batch reminders |
+
+### preprocessors/
+Message filtering before the agent:
+
+| File | What it shows |
+|------|--------------|
+| `messageMatching.ts` | Modify/block messages based on content |
+
+### postprocessors/
+Response transformation after the agent:
+
+| File | What it shows |
+|------|--------------|
+| `modifyResponse.ts` | Transform agent responses |
+
+### services/
+Helper utilities:
+
+| File | What it shows |
+|------|--------------|
+| `ApiService.ts` | HTTP client wrapper |
+| `GetWeather.ts` | Mock service for testing |
+
+## 🎯 API Coverage
+
+| API | Where it's demonstrated |
+|-----|------------------------|
+| **User** | `UserDataTool.ts` |
+| **Products** | `ProductsTool.ts` |
+| **Baskets** | `BasketTool.ts`, `SmartBasketTool.ts` |
+| **Orders** | `OrderTool.ts`, `PaymentWebhook.ts` |
+| **Data** | `CustomDataTool.ts`, `FileUploadWebhook.ts` |
+| **Jobs** | `SmartBasketTool.ts`, `GameScoreTrackerTool.ts` |
+| **AI** | `UserDataTool.ts` |
+| **Templates** | `UserEventWebhook.ts`, `AbandonedBasketProcessorJob.ts` |
+| **CDN** | `FileUploadWebhook.ts` |
+
+## 🚀 How to Use
+
+### Option 1: Copy what you need
+
+```bash
+# Copy a tool
+cp examples/skills/tools/GetWeatherTool.ts src/skills/tools/
+
+# Copy a webhook
+cp examples/webhooks/PaymentWebhook.ts src/webhooks/
+
+# Copy a job
+cp examples/jobs/HealthCheckJob.ts src/jobs/
+```
+
+### Option 2: Move entire directories
+
+```bash
+mv examples/skills src/
+mv examples/webhooks src/
+mv examples/jobs src/
+```
+
+Then import them in your `src/index.ts`.
+
+## 📖 Documentation
+
+- **API Reference:** https://docs.heylua.ai/api
+- **Examples Guide:** https://docs.heylua.ai/examples
+- **Best Practices:** https://docs.heylua.ai/template/best-practices

package/template/{src → examples}/jobs/AbandonedBasketProcessorJob.ts

@@ -1,22 +1,27 @@
 /**
  * Abandoned Basket Processor Job
  * 
- * This job runs every 15 minutes to process basket checkout reminders.
- * Works together with CreateSmartBasketTool to send abandoned cart notifications.
+ * Processes abandoned cart reminders and sends WhatsApp notifications.
  * 
  * Flow:
  * 1. User creates basket → Tool schedules reminder in custom data
  * 2. This job runs every 15 minutes
  * 3. Checks which reminders are due
  * 4. Checks if baskets were checked out
- * 5. Sends reminders for abandoned baskets
+ * 5. Sends WhatsApp template message for abandoned baskets
+ * 
+ * Demonstrates:
+ * - Interval job scheduling
+ * - Batch processing pattern
+ * - Templates API integration (WhatsApp)
+ * - Data API for tracking state
  */
 
-import { LuaJob, Data, Baskets } from "lua-cli";
+import { LuaJob, Data, Baskets, Templates, env } from "lua-cli";
 
 const abandonedBasketProcessorJob = new LuaJob({
   name: "process-basket-reminders",
-  description: "Processes abandoned basket reminders",
+  description: "Processes abandoned basket reminders and sends WhatsApp notifications",
 
   // Run every 15 minutes
   schedule: {
@@ -27,6 +32,10 @@ const abandonedBasketProcessorJob = new LuaJob({
   timeout: 120,  // 2 minutes
 
   execute: async () => {
+    // Configuration - set these in your environment variables
+    const WHATSAPP_CHANNEL_ID = env('WHATSAPP_CHANNEL_ID') || '';
+    const ABANDONED_CART_TEMPLATE_NAME = 'abandoned_cart_reminder';
+
     console.log('🔍 Processing basket reminders...');
 
     // Get all pending reminders
@@ -37,6 +46,7 @@ const abandonedBasketProcessorJob = new LuaJob({
     let processedCount = 0;
     let abandonedCount = 0;
     let checkedOutCount = 0;
+    let messagesSent = 0;
 
     for (const reminder of reminders) {
       // Skip if not yet time
@@ -72,9 +82,58 @@ const abandonedBasketProcessorJob = new LuaJob({
             totalValue,
             items: basket.items,
             abandonedAt: new Date().toISOString(),
-            reminderSent: true
+            reminderSent: false
           });
 
+          // Send WhatsApp reminder if we have a phone number
+          if (reminder.data.phoneNumber && WHATSAPP_CHANNEL_ID) {
+            try {
+              // Find the abandoned cart template
+              const templatesResponse = await Templates.whatsapp.list(WHATSAPP_CHANNEL_ID, {
+                search: ABANDONED_CART_TEMPLATE_NAME
+              });
+              
+              const template = templatesResponse.templates.find(
+                t => t.status === 'APPROVED'
+              );
+
+              if (template) {
+                // Send the template message
+                const result = await Templates.whatsapp.send(WHATSAPP_CHANNEL_ID, template.id, {
+                  phoneNumbers: [reminder.data.phoneNumber],
+                  values: {
+                    body: {
+                      item_count: String(basket.items?.length || 0),
+                      total_value: `${basket.currency} ${totalValue.toFixed(2)}`
+                    }
+                  }
+                });
+
+                if (result.totalErrors === 0) {
+                  console.log(`📱 WhatsApp reminder sent to ${reminder.data.phoneNumber}`);
+                  messagesSent++;
+                  
+                  // Update the abandoned basket record
+                  const abandonedRecords = await Data.get('abandoned-baskets', {}, 1, 100);
+                  const record = abandonedRecords.data?.find((r: any) => r.data.basketId === basket.id);
+                  if (record) {
+                    await Data.update('abandoned-baskets', record.id, {
+                      ...record.data,
+                      reminderSent: true,
+                      reminderSentAt: new Date().toISOString()
+                    });
+                  }
+                } else {
+                  console.warn(`⚠️ Failed to send WhatsApp: ${result.results[0]?.error}`);
+                }
+              } else {
+                console.warn(`⚠️ No approved template found: ${ABANDONED_CART_TEMPLATE_NAME}`);
+              }
+            } catch (templateError) {
+              console.error('Failed to send WhatsApp template:', templateError);
+            }
+          }
+
           // Update reminder status
           await Data.update('basket-reminders', reminder.id, {
             ...reminder.data,
@@ -83,9 +142,6 @@ const abandonedBasketProcessorJob = new LuaJob({
             processedAt: new Date().toISOString()
           });
 
-          // TODO: Send actual reminder email/SMS
-          console.log(`📧 Would send reminder: "You left ${basket.items?.length || 0} items in your cart!"`);
-
         } else {
           // Basket was checked out
           console.log(`✅ Basket ${basket.id} was checked out (${basket.status})`);
@@ -120,17 +176,17 @@ const abandonedBasketProcessorJob = new LuaJob({
     }
 
     console.log('✅ Reminder processing complete');
-    console.log(`📊 Processed: ${processedCount}, Abandoned: ${abandonedCount}, Checked out: ${checkedOutCount}`);
+    console.log(`📊 Processed: ${processedCount}, Abandoned: ${abandonedCount}, Checked out: ${checkedOutCount}, Messages sent: ${messagesSent}`);
 
     return {
       success: true,
       processedCount,
       abandonedCount,
       checkedOutCount,
+      messagesSent,
       timestamp: new Date().toISOString()
     };
   }
 });
 
 export default abandonedBasketProcessorJob;
-

package/template/{src → examples}/postprocessors/modifyResponse.ts

@@ -1,4 +1,4 @@
-import { ChatMessage, PostProcessor, UserDataInstance } from "lua-cli";
+import { PostProcessor, UserDataInstance } from "lua-cli";
 
 
 const modifyResponsePostProcessor = new PostProcessor({
@@ -11,9 +11,9 @@ const modifyResponsePostProcessor = new PostProcessor({
         console.log("Response", response);
         console.log("Channel", channel);
         if (response.includes("test")) {
-            return message.toUpperCase();
+            return { modifiedResponse: message.toUpperCase() };
         }
-        return response;
+        return { modifiedResponse: response };
     }
 });
 

package/template/{src → examples}/skills/tools/GameScoreTrackerTool.ts

@@ -101,8 +101,8 @@ export class TrackGameScoresTool implements LuaTool {
           if (gameData.data.status === 'finished') {
             console.log('🏁 Game ' + gameId + ' is already finished. Stopping job.');
             
-            // IMPORTANT: Job stops itself!
-            await Jobs.deactivate(job.jobId);
+            // IMPORTANT: Job stops itself using the instance method!
+            await job.deactivate();
             
             return {
               action: 'job-stopped',
@@ -168,8 +168,8 @@ export class TrackGameScoresTool implements LuaTool {
               finishedAt: new Date().toISOString()
             });
             
-            // IMPORTANT: Job stops itself when game ends!
-            await Jobs.deactivate(job.jobId);
+            // IMPORTANT: Job stops itself when game ends using instance method!
+            await job.deactivate();
             
             console.log('⏹️  Score tracking job stopped for game ' + gameId);
             
@@ -208,7 +208,7 @@ export class TrackGameScoresTool implements LuaTool {
       }
     });
 
-    console.log(`✅ Score tracking job created: ${job.jobId}`);
+    console.log(`✅ Score tracking job created: ${job.id}`);
     console.log(`📊 Job will update scores every ${input.updateIntervalSeconds} seconds`);
     console.log(`⏹️  Job will automatically stop when game ends`);
 
@@ -222,7 +222,7 @@ export class TrackGameScoresTool implements LuaTool {
         status: 'scheduled'
       },
       scoreTracker: {
-        jobId: job.jobId,
+        jobId: job.id,
         jobName: job.name,
         updateInterval: input.updateIntervalSeconds,
         startsAt: jobStartTime.toISOString(),
@@ -309,14 +309,10 @@ export class StopGameTrackingTool implements LuaTool {
   async execute(input: { gameId: string }) {
     console.log(`⏹️  Stopping score tracking for game ${input.gameId}...`);
 
-    // Find the tracking job
-    const allJobs = await Jobs.getAll();
-    
-    if (!allJobs.success || !allJobs.data) {
-      throw new Error('Failed to fetch jobs');
-    }
+    // Find the tracking job - Jobs.getAll() returns array of JobInstance
+    const allJobs = await Jobs.getAll({ includeDynamic: true });
 
-    const trackingJob = allJobs.data.jobs.find((j: any) => 
+    const trackingJob = allJobs.find((j: any) => 
       j.name === `track-game-${input.gameId}`
     );
 
@@ -328,8 +324,8 @@ export class StopGameTrackingTool implements LuaTool {
       };
     }
 
-    // Deactivate the job
-    const result = await Jobs.deactivate(trackingJob.id);
+    // Deactivate the job using instance method
+    await trackingJob.deactivate();
 
     // Update game status
     const games = await Data.get('games', {}, 1, 100);

package/template/{src → examples}/skills/tools/OrderTool.ts

@@ -52,3 +52,28 @@ export class GetOrderByIdTool implements LuaTool {
         return Orders.getById(input.orderId);
     }
 }
+
+/**
+ * Update custom data on an order.
+ * Useful for adding tracking info, notes, or custom metadata.
+ */
+export class UpdateOrderDataTool implements LuaTool {
+    name = "update_order_data";
+    description = "Update custom data on an order (tracking info, notes, etc.)";
+    inputSchema = z.object({
+        orderId: z.string().describe("The order ID to update"),
+        data: z.record(z.any()).describe("Custom data to add/update on the order")
+    });
+    async execute(input: z.infer<typeof this.inputSchema>) {
+        console.log(`📝 Updating order ${input.orderId} with data:`, input.data);
+        
+        const result = await Orders.updateData(input.data, input.orderId);
+        
+        return {
+            success: true,
+            orderId: input.orderId,
+            message: "Order data updated successfully",
+            updatedData: input.data
+        };
+    }
+}

package/template/examples/skills/tools/PremiumFeatureTool.ts

@@ -0,0 +1,98 @@
+import { LuaTool, Products, User } from "lua-cli";
+import { z } from "zod";
+
+/**
+ * Example tool with a condition.
+ * 
+ * The `condition` function determines if this tool should be available to the LLM.
+ * It runs BEFORE the tool is offered, so the LLM won't see this tool if condition returns false.
+ * 
+ * Use cases:
+ * - Premium/paid features only for subscribed users
+ * - Features based on user verification status
+ * - Region-specific tools
+ * - A/B testing tool availability
+ * - Time-based feature access
+ * 
+ * The condition has access to all Platform APIs: User, Data, Products, Baskets, Orders, etc.
+ */
+export default class PremiumFeatureTool implements LuaTool {
+    name = "premium_advanced_search";
+    description = "Advanced search with filters and sorting - available to premium users only";
+    
+    inputSchema = z.object({
+        query: z.string().describe("Search query"),
+        filters: z.object({
+            category: z.string().optional().describe("Filter by category"),
+            minPrice: z.number().optional().describe("Minimum price filter"),
+            maxPrice: z.number().optional().describe("Maximum price filter"),
+        }).optional().describe("Optional filters"),
+        sortBy: z.enum(["relevance", "price_asc", "price_desc", "newest"]).optional().describe("Sort order")
+    });
+
+    /**
+     * Condition function - determines if this tool should be available.
+     * 
+     * This runs once per request when tools are being built.
+     * Return true to enable the tool, false to hide it from the LLM.
+     * 
+     * If condition throws an error, the tool is disabled (fail-closed behavior).
+     */
+    condition = async () => {
+        // Get the current user's data
+        const user = await User.get();
+        
+        // Check if user has premium subscription
+        // The 'data' field contains custom user data stored via User.update()
+        const isPremium = user.data?.subscription === "premium" || user.data?.isPremium === true;
+        
+        // You can also check other conditions:
+        // - user.data?.trialEndsAt > Date.now() (trial period)
+        // - user.country?.code === "US" (region-based)
+        // - user.data?.featureFlags?.advancedSearch (feature flags)
+        
+        return isPremium;
+    };
+
+    async execute(input: z.infer<typeof this.inputSchema>) {
+        // This only runs if condition returned true
+        const { query, filters, sortBy } = input;
+        
+        // Example: Search products with advanced filters
+        const searchOptions: any = {
+            query,
+            limit: 20,
+        };
+        
+        if (filters?.category) {
+            searchOptions.category = filters.category;
+        }
+        
+        if (sortBy) {
+            searchOptions.sortBy = sortBy;
+        }
+
+        const searchResult = await Products.search(searchOptions);
+        const products = searchResult.products;
+        
+        // Apply price filters if provided
+        let filteredResults = products;
+        if (filters?.minPrice !== undefined || filters?.maxPrice !== undefined) {
+            filteredResults = products.filter((product) => {
+                const price = product.price || 0;
+                if (filters.minPrice !== undefined && price < filters.minPrice) return false;
+                if (filters.maxPrice !== undefined && price > filters.maxPrice) return false;
+                return true;
+            });
+        }
+        
+        return {
+            query,
+            totalResults: filteredResults.length,
+            results: filteredResults.slice(0, 10), // Return top 10
+            appliedFilters: filters,
+            sortedBy: sortBy || "relevance"
+        };
+    }
+}
+

package/template/{src → examples}/skills/tools/UserDataTool.ts

@@ -46,6 +46,40 @@ export class UpdateUserDataTool implements LuaTool {
     }
 }
 
+/**
+ * Get the conversation history for the current user.
+ * Useful for analyzing past interactions or providing context.
+ */
+export class GetChatHistoryTool implements LuaTool {
+    name = "get_chat_history";
+    description = "Get the conversation history for the current user";
+    inputSchema = z.object({
+        limit: z.number().optional().describe("Maximum number of messages to retrieve")
+    });
+
+    async execute(input: z.infer<typeof this.inputSchema>) {
+        const history = await User.getChatHistory();
+        
+        // Optionally limit the results
+        const messages = input.limit ? history.slice(-input.limit) : history;
+        
+        // Format the history for easier reading
+        const formattedHistory = messages.map(msg => ({
+            role: msg.role,
+            content: msg.content,
+            createdAt: msg.createdAt,
+            id: msg.id
+        }));
+        
+        return {
+            success: true,
+            totalMessages: history.length,
+            returnedMessages: messages.length,
+            history: formattedHistory
+        };
+    }
+}
+
 export class WritePoemTool implements LuaTool {
     name = "write_poem";
     description = "Write a poem about a given topic";

package/template/examples/webhooks/FileUploadWebhook.ts

@@ -0,0 +1,86 @@
+/**
+ * File Upload Webhook
+ * 
+ * Receives file uploads from external systems and stores them in the CDN.
+ * 
+ * Use cases:
+ * - Customer uploads documents via your website form
+ * - Integration with document management systems
+ * - Receiving images/files from third-party services
+ * 
+ * Webhook URL: https://webhook.heylua.ai/{agentId}/file-upload
+ */
+
+import { LuaWebhook, CDN, Data, User } from "lua-cli";
+import { z } from "zod";
+
+const fileUploadWebhook = new LuaWebhook({
+  name: "file-upload",
+  description: "Receives file uploads and stores them in CDN",
+
+  headerSchema: z.object({
+    'content-type': z.string(),
+    'x-api-key': z.string().optional()
+  }),
+
+  bodySchema: z.object({
+    filename: z.string(),
+    contentType: z.string(),
+    data: z.string().describe("Base64 encoded file data"),
+    metadata: z.object({
+      category: z.string().optional(),
+      description: z.string().optional(),
+      tags: z.array(z.string()).optional()
+    }).optional()
+  }),
+
+  execute: async (event: any) => {
+    const { body } = event;
+    console.log(`📁 Receiving file upload: ${body.filename}`);
+
+    // Decode base64 data
+    const buffer = Buffer.from(body.data, 'base64');
+    const blob = new Blob([buffer], { type: body.contentType });
+    const file = new File([blob], body.filename, { type: body.contentType });
+
+    console.log(`📤 Uploading to CDN: ${file.name} (${file.size} bytes)`);
+
+    // Upload to CDN
+    const fileId = await CDN.upload(file);
+
+    console.log(`✅ File stored with ID: ${fileId}`);
+
+    // Store file metadata in custom data for later retrieval
+    const fileRecord = await Data.create('uploaded-files', {
+      fileId: fileId,
+      filename: body.filename,
+      contentType: body.contentType,
+      size: file.size,
+      category: body.metadata?.category || 'uncategorized',
+      description: body.metadata?.description,
+      tags: body.metadata?.tags || [],
+      uploadedAt: new Date().toISOString()
+    }, `${body.filename} ${body.metadata?.category || ''} ${body.metadata?.tags?.join(' ') || ''}`);
+
+    // Notify user about the upload
+    const user = await User.get();
+    if (user) {
+      await user.send([{
+        type: "text",
+        text: `📁 New file uploaded: ${body.filename}`
+      }]);
+    }
+
+    return {
+      success: true,
+      fileId: fileId,
+      recordId: fileRecord.id,
+      filename: body.filename,
+      size: file.size,
+      message: 'File uploaded and stored successfully'
+    };
+  }
+});
+
+export default fileUploadWebhook;
+