lua-cli 3.1.0-alpha.3 → 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,25 +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",
-  version: "1.0.0",
-  description: "Processes abandoned basket reminders",
-  context: "Runs every 15 minutes to check for abandoned baskets and send recovery emails. " +
-           "Works with basket creation tools that schedule reminders.",
+  description: "Processes abandoned basket reminders and sends WhatsApp notifications",
 
   // Run every 15 minutes
   schedule: {
@@ -30,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
@@ -40,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
@@ -75,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,
@@ -86,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})`);
@@ -123,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}/jobs/DailyCleanupJob.ts

@@ -9,10 +9,7 @@ import { LuaJob, Data } from "lua-cli";
 
 const dailyCleanupJob = new LuaJob({
   name: "daily-cleanup",
-  version: "1.0.0",
   description: "Daily database cleanup and maintenance",
-  context: "Runs at 2 AM EST daily to remove old logs, expired sessions, and optimize data collections. " +
-           "This job helps maintain database performance and storage costs.",
 
   // Cron schedule: Every day at 2 AM EST
   schedule: {

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

@@ -9,10 +9,7 @@ import { LuaJob, Data } from "lua-cli";
 
 const dataMigrationJob = new LuaJob({
   name: "migrate-user-schema",
-  version: "1.0.0",
   description: "One-time migration to new user event schema",
-  context: "Scheduled one-time task to migrate user events from old schema to new schema. " +
-           "Runs once at the specified time and then automatically deactivates.",
 
   // One-time schedule: Run at specific date/time
   schedule: {

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

@@ -9,10 +9,7 @@ import { LuaJob, Data, Products } from "lua-cli";
 
 const healthCheckJob = new LuaJob({
   name: "health-check",
-  version: "1.0.0",
   description: "System health monitoring",
-  context: "Runs every 5 minutes to check API health, database connectivity, and service availability. " +
-           "Logs health metrics and can trigger alerts if issues are detected.",
 
   // Interval schedule: Every 5 minutes
   schedule: {

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

@@ -1,10 +1,9 @@
-import { ChatMessage, PostProcessor, UserDataInstance } from "lua-cli";
+import { PostProcessor, UserDataInstance } from "lua-cli";
 
 
 const modifyResponsePostProcessor = new PostProcessor({
     name: "modify-response",
     description: "Modifies the response to the user",
-    context: "Modifies the response to the user",
     execute: async (user: UserDataInstance, message: string, response: string, channel: string) => {
         console.log("Modify response post processor", user, message, response, channel);
         console.log("User data", await user.data);
@@ -12,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/examples/preprocessors/messageMatching.ts

@@ -0,0 +1,35 @@
+import { ChatMessage, PreProcessor, PreProcessorResult, UserDataInstance } from "lua-cli";
+
+
+const messageMatchingPreProcessor = new PreProcessor({
+    name: "message-matching",
+    description: "Matches the message to the appropriate skill",
+    execute: async (user: UserDataInstance, messages: ChatMessage[], channel: string): Promise<PreProcessorResult> => {
+        console.log("Message matching pre processor", user, messages, channel);
+        console.log("User data", await user.data);
+        console.log("Messages", messages);
+        console.log("Channel", channel);
+        
+        //check if message type text contains test and return the message
+        const testMessage = messages.find((message) => message.type === "text" && message.text.includes("test"));
+        if (testMessage) {
+            return {
+                action: 'proceed',
+                modifiedMessage: [{ type: "text", text: "Tell the user that you got their test message and nothing else" }]
+            };
+        }
+        
+        // Example blocking logic
+        const shouldBlock = messages.some((message) => message.type === "text" && message.text.includes("block"));
+        if (shouldBlock) {
+            return {
+                action: 'block',
+                response: "Message blocked by preprocessor"
+            };
+        }
+
+        return { action: 'proceed' };
+    }
+});
+
+export default messageMatchingPreProcessor;

package/template/{src → examples}/skills/basket.skill.ts

@@ -3,7 +3,6 @@ import { CreateBasketTool, GetBasketByIdTool, UpdateBasketStatusTool, UpdateBask
 
 const basketSkill = new LuaSkill({
     name: "basket-skill",
-    version: "1.0.0",
     description: "Basket management skill",
     context: "Basket management skill",
     tools: [new CreateBasketTool(), new GetBasketByIdTool(), new UpdateBasketStatusTool(), new UpdateBasketMetadataTool(), new CheckoutBasketTool(), new GetBasketsTool(), new AddItemToBasketTool(), new RemoveItemFromBasketTool(), new ClearBasketTool()],

package/template/{src → examples}/skills/product.skill.ts

@@ -4,7 +4,6 @@ import { SearchProductsTool, CreateProductTool, UpdateProductTool, GetAllProduct
 
 const productSkill = new LuaSkill({
     name: "product-skill",
-    version: "1.0.0",
     description: "Product management skill",
     context: "Product management skill",
     tools: [new SearchProductsTool(), new CreateProductTool(), new UpdateProductTool(), new GetAllProductsTool(), new GetProductByIdTool(), new DeleteProductTool()],

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/{src → examples}/skills/user.skill.ts

@@ -4,7 +4,6 @@ import { CreateInlineJobTool, GetUserDataTool, UpdateUserDataTool, WritePoemTool
 
 const userSkill = new LuaSkill({
     name: "user-skill",
-    version: "1.0.0",
     description: "User management skill",
     context: "User management skill",
     tools: [new GetUserDataTool(), new UpdateUserDataTool(), new WritePoemTool(), new CreateInlineJobTool()],