lua-cli 2.5.8 → 3.0.0-alpha.4

package/dist/utils/webhook-management.js

@@ -0,0 +1,256 @@
+/**
+ * Webhook Management Utilities
+ * Handles webhook creation via API and YAML configuration management
+ */
+import fs from "fs";
+import path from "path";
+import yaml from "js-yaml";
+import WebhookApi from '../api/webhook.api.service.js';
+import { BASE_URLS } from '../config/constants.js';
+import { loadApiKey } from '../services/auth.js';
+import { COMPILE_FILES, SKILL_DEFAULTS, YAML_FORMAT, } from '../config/compile.constants.js';
+/**
+ * Ensures all detected webhooks exist in the YAML config with valid webhook IDs.
+ * If a webhook doesn't exist or has no ID, creates it via the API.
+ *
+ * @param webhooksArray - Array of webhooks detected from source code
+ * @param config - The skill configuration from lua.skill.yaml
+ * @returns Updated webhooks array with valid webhook IDs
+ */
+export async function ensureWebhooksExistInYaml(webhooksArray, config) {
+    const updatedWebhooksArray = [];
+    let yamlUpdated = false;
+    const existingWebhooks = config?.webhooks || [];
+    const existingWebhooksMap = createWebhooksMap(existingWebhooks);
+    // Process each detected webhook
+    for (const webhook of webhooksArray) {
+        const existingWebhook = existingWebhooksMap.get(webhook.name);
+        if (existingWebhook && existingWebhook.webhookId && existingWebhook.webhookId !== '') {
+            // Webhook exists with valid webhookId - reuse it
+            updatedWebhooksArray.push({
+                ...webhook,
+                webhookId: existingWebhook.webhookId
+            });
+        }
+        else {
+            // Webhook doesn't exist or missing webhookId - create via API
+            const createdWebhook = await createWebhookViaApi(webhook, config, existingWebhooks, existingWebhook);
+            updatedWebhooksArray.push(createdWebhook);
+            yamlUpdated = true;
+        }
+    }
+    // Update YAML file if any changes were made
+    if (yamlUpdated) {
+        await updateYamlWithWebhooks(config);
+    }
+    return updatedWebhooksArray;
+}
+/**
+ * Creates a map of existing webhooks for quick lookup by name.
+ *
+ * @param existingWebhooks - Array of webhooks from YAML config
+ * @returns Map of webhook names to webhook objects
+ */
+function createWebhooksMap(existingWebhooks) {
+    const map = new Map();
+    existingWebhooks.forEach((webhook) => {
+        map.set(webhook.name, webhook);
+    });
+    return map;
+}
+/**
+ * Creates a new webhook via the Lua API and updates the config.
+ *
+ * @param webhook - The webhook to create
+ * @param config - The skill configuration
+ * @param existingWebhooks - Array of existing webhooks (mutated)
+ * @param existingWebhook - The existing webhook entry if one exists (may be without ID)
+ * @returns The webhook with its new ID
+ */
+async function createWebhookViaApi(webhook, config, existingWebhooks, existingWebhook) {
+    try {
+        // Validate prerequisites
+        const apiKey = await loadApiKey();
+        if (!apiKey) {
+            throw new Error("No API key found. Run 'lua auth configure' first.");
+        }
+        const agentId = config?.agent?.agentId;
+        if (!agentId) {
+            throw new Error("No agent ID found in lua.skill.yaml. Run 'lua init' first.");
+        }
+        // Create webhook via API
+        const webhookPayload = {
+            name: webhook.name,
+            description: webhook.description || `A Lua webhook for ${webhook.name}`,
+            context: webhook.context || ''
+        };
+        const webhookApi = new WebhookApi(BASE_URLS.API, apiKey, agentId);
+        const result = await webhookApi.createWebhook(webhookPayload);
+        if (result.success && result.data && result.data.id) {
+            const newWebhookId = result.data.id;
+            // Update YAML config with new webhook ID
+            if (!existingWebhook) {
+                existingWebhooks.push({
+                    name: webhook.name || '',
+                    version: webhook.version || SKILL_DEFAULTS.VERSION,
+                    webhookId: newWebhookId
+                });
+            }
+            else {
+                existingWebhook.webhookId = newWebhookId;
+            }
+            // Add webhooks to config if not already present
+            if (!config.webhooks) {
+                config.webhooks = existingWebhooks;
+            }
+            return {
+                ...webhook,
+                webhookId: newWebhookId
+            };
+        }
+        else {
+            console.error(`❌ Failed to create webhook ${webhook.name}:`, result.error);
+            throw new Error(result.error?.message || 'Failed to create webhook - no ID returned from API');
+        }
+    }
+    catch (error) {
+        console.error(`❌ Failed to create webhook ${webhook.name}:`, error);
+        throw error;
+    }
+}
+/**
+ * Updates the lua.skill.yaml file with the current webhooks array.
+ * Ensures no undefined values are written to the YAML file.
+ *
+ * @param config - Current skill configuration to merge with
+ */
+async function updateYamlWithWebhooks(config) {
+    const webhooks = config?.webhooks || [];
+    // Clean webhooks array to ensure no undefined values
+    const cleanedWebhooks = webhooks.map(webhook => ({
+        name: webhook.name || '',
+        version: webhook.version || SKILL_DEFAULTS.VERSION,
+        webhookId: webhook.webhookId || ''
+    }));
+    // Update config with cleaned webhooks array
+    const updatedConfig = {
+        ...config,
+        webhooks: cleanedWebhooks
+    };
+    // Write updated YAML with consistent formatting
+    const yamlPath = path.join(process.cwd(), COMPILE_FILES.LUA_SKILL_YAML);
+    const yamlContent = yaml.dump(updatedConfig, {
+        indent: YAML_FORMAT.INDENT,
+        lineWidth: YAML_FORMAT.LINE_WIDTH,
+        noRefs: YAML_FORMAT.NO_REFS,
+        replacer: (key, value) => {
+            // Replace undefined values with empty strings
+            return value === undefined ? '' : value;
+        }
+    });
+    fs.writeFileSync(yamlPath, yamlContent);
+}
+/**
+ * Syncs the server webhooks with the YAML configuration.
+ * Performs a two-way sync:
+ * 1. Deletes/deactivates webhooks from server that aren't in YAML
+ * 2. Updates YAML with active version numbers from server
+ *
+ * @param config - The skill configuration from lua.skill.yaml
+ * @returns Array of messages about sync operations
+ */
+export async function syncServerWebhooksWithYaml(config) {
+    const messages = [];
+    let yamlNeedsUpdate = false;
+    try {
+        // Validate prerequisites
+        const apiKey = await loadApiKey();
+        if (!apiKey) {
+            console.warn("⚠️  No API key found. Skipping server webhook sync.");
+            return messages;
+        }
+        const agentId = config?.agent?.agentId;
+        if (!agentId) {
+            console.warn("⚠️  No agent ID found in lua.skill.yaml. Skipping server webhook sync.");
+            return messages;
+        }
+        // Get webhooks from server
+        const webhookApi = new WebhookApi(BASE_URLS.API, apiKey, agentId);
+        const serverWebhooksResponse = await webhookApi.getWebhooks();
+        if (!serverWebhooksResponse.success || !serverWebhooksResponse.data?.webhooks) {
+            console.warn("⚠️  Could not retrieve server webhooks. Skipping server webhook sync.");
+            return messages;
+        }
+        const serverWebhooks = serverWebhooksResponse.data.webhooks;
+        const yamlWebhooks = config?.webhooks || [];
+        // Create maps for efficient lookup
+        const yamlWebhooksMap = new Map(yamlWebhooks
+            .filter((webhook) => webhook.webhookId)
+            .map((webhook) => [webhook.webhookId, webhook]));
+        const serverWebhooksMap = new Map(serverWebhooks.map(webhook => [webhook.id, webhook]));
+        // Part 1: Delete webhooks from server that aren't in YAML
+        const webhooksToDelete = serverWebhooks.filter(serverWebhook => !yamlWebhooksMap.has(serverWebhook.id));
+        for (const webhook of webhooksToDelete) {
+            try {
+                const deleteResponse = await webhookApi.deleteWebhook(webhook.id);
+                if (deleteResponse.success && deleteResponse.data) {
+                    if (deleteResponse.data.deleted) {
+                        const msg = `✅ Deleted webhook "${webhook.name}" from server`;
+                        messages.push(msg);
+                        console.log(msg);
+                    }
+                    else if (deleteResponse.data.deactivated) {
+                        const msg = `⚠️  Webhook "${webhook.name}" has versions and cannot be deleted. It has been deactivated instead.`;
+                        messages.push(msg);
+                        console.warn(msg);
+                    }
+                }
+                else {
+                    const msg = `❌ Failed to delete webhook "${webhook.name}": ${deleteResponse.error?.message || 'Unknown error'}`;
+                    messages.push(msg);
+                    console.error(msg);
+                }
+            }
+            catch (error) {
+                const msg = `❌ Error deleting webhook "${webhook.name}": ${error}`;
+                messages.push(msg);
+                console.error(msg);
+            }
+        }
+        // Part 2: Sync version numbers from server to YAML
+        const updatedYamlWebhooks = yamlWebhooks.map((yamlWebhook) => {
+            const serverWebhook = serverWebhooksMap.get(yamlWebhook.webhookId);
+            if (serverWebhook && serverWebhook.versions && serverWebhook.versions.length > 0) {
+                // Find the active version on the server
+                const activeVersion = serverWebhook.versions.find((v) => v.isActive);
+                if (activeVersion && activeVersion.version !== yamlWebhook.version) {
+                    const msg = `📝 Updated "${yamlWebhook.name}" webhook version in YAML: ${yamlWebhook.version} → ${activeVersion.version}`;
+                    messages.push(msg);
+                    console.log(msg);
+                    yamlNeedsUpdate = true;
+                    return {
+                        ...yamlWebhook,
+                        version: activeVersion.version
+                    };
+                }
+            }
+            return yamlWebhook;
+        });
+        // Update YAML file if versions changed
+        if (yamlNeedsUpdate) {
+            const updatedConfig = {
+                ...config,
+                webhooks: updatedYamlWebhooks
+            };
+            await updateYamlWithWebhooks(updatedConfig);
+            console.log("✅ YAML webhook versions synced with server");
+        }
+        if (webhooksToDelete.length === 0 && !yamlNeedsUpdate) {
+            console.log("✅ Server webhooks and YAML are fully in sync");
+        }
+    }
+    catch (error) {
+        console.error("❌ Error syncing server webhooks:", error);
+    }
+    return messages;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lua-cli",
-  "version": "2.5.8",
+  "version": "3.0.0-alpha.4",
   "description": "Command-line interface for Lua AI platform - develop, test, and deploy LuaSkills with custom tools",
   "readmeFilename": "README.md",
   "main": "dist/api-exports.js",

package/template/README.md

@@ -7,12 +7,19 @@ Welcome to your Lua AI skill project! This project is ready to customize and dep
 ## 🎯 What You Have
 
 This project includes:
+- ✅ **LuaAgent** - New simplified agent configuration (RECOMMENDED!)
 - ✅ **7 Example Skills** - Pre-configured skill examples
 - ✅ **30+ Example Tools** - Working tool implementations
-- ✅ **All Platform APIs** - User, Products, Baskets, Orders, Custom Data
+- ✅ **2 Webhook Examples** - HTTP endpoints for external integrations
+- ✅ **4 Job Examples** - Scheduled tasks (cron, interval, one-time)
+- ✅ **Smart Basket Example** - Dynamic job creation from tools
+- ✅ **All Platform APIs** - User, Products, Baskets, Orders, Custom Data, Webhooks, Jobs
 - ✅ **TypeScript Setup** - Full type safety
 - ✅ **Ready to Deploy** - Just customize and go!
 
+> **NEW!** Check out `AGENT_CONFIGURATION.md` to learn about the simplified `LuaAgent` approach.
+> It's easier and cleaner than the legacy approach!
+
 ---
 
 ## 🚀 Quick Start
@@ -67,7 +74,28 @@ your-project/
 
 ## 🎓 Getting Started
 
-### Step 1: Understand the Template
+### Step 1: Choose Your Configuration Style
+
+**Option A: LuaAgent (Recommended for new projects)**
+
+The simplified approach - define everything in one place:
+
+```typescript
+import { LuaAgent, LuaSkill } from 'lua-cli';
+
+export const agent = new LuaAgent({
+  name: 'my-assistant',
+  persona: 'You are a helpful e-commerce assistant...',
+  welcomeMessage: 'Hello! How can I help you today?',
+  skills: [weatherSkill, productSkill, basketSkill],
+  webhooks: [userWebhook],
+  jobs: [healthCheckJob]
+});
+```
+
+See `src/index-agent-example.ts` and `AGENT_CONFIGURATION.md` for details.
+
+**Option B: Individual Components (Legacy)**
 
 Open **`src/index.ts`** - this is where your skills are defined:
 

package/template/lua.skill.yaml

@@ -0,0 +1,47 @@
+agent:
+  agentId: baseAgent_agent_1760922427216_fk9w0ezhh
+  orgId: 026cc41b-e013-4474-9b65-5a15f8881f92
+  persona: |
+    Meet Vivienne, the vibrant and dynamic assistant at V3 Test, a lively retail and consumer goods store that specializes in bringing a splash of color and excitement to everyday life. Vivienne embodies the brand's energetic and fun personality, always ready to engage with customers in a way that makes shopping an enjoyable and memorable experience. Her role is to be the friendly face and knowledgeable guide for anyone who steps into the store, whether they're looking for the latest fashion trends or a unique gift for a loved one.
+
+    V3 Test is all about creating a joyful and spirited shopping environment, and Vivienne is the perfect personification of this ethos. She is lively, approachable, and always ready with a smile, making every interaction feel like a conversation with a good friend. Her voice is warm and enthusiastic, with a hint of playfulness that puts customers at ease and encourages them to explore the store's offerings.
+
+    Vivienne's target customers are diverse, ranging from young adults in their twenties who are fashion-forward and tech-savvy, to busy parents looking for quality products that add a touch of fun to their family life. She understands the fast-paced lifestyle of her customers and is adept at tailoring her approach to meet their individual needs, whether they're in a hurry or have time to browse.
+
+    Her sales approach is consultative and friendly, focusing on understanding the customer's needs and preferences before suggesting products that align with their style and personality. Vivienne is confident in her recommendations, always ready to upsell when appropriate, but never pushy. She believes in building relationships with customers, ensuring they leave the store not only with products they love but also with a positive impression of the brand.
+
+    In terms of communication style, Vivienne strikes a perfect balance between being informal and efficient. She is warm and engaging, making customers feel valued and appreciated, while also being mindful of their time. Her interactions are peppered with humor and light-hearted banter, creating a shopping experience that is both enjoyable and efficient. Whether it's through in-person interactions or digital communication, Vivienne ensures that every customer feels like a part of the V3 Test family.
+  welcomeMessage: Hi, I am your AI assistant. How can I help you today?
+skills:
+  - name: general-skill
+    version: 0.0.3
+    skillId: 1faf9b3a-e352-4e63-a6c4-a3deca815361
+  - name: user-data-skill
+    version: 0.0.1
+    skillId: e0c382c1-f469-4880-962a-a756ea3c1411
+  - name: product-skill
+    version: 0.0.1
+    skillId: d4cdc7bc-6d42-4232-902d-2b9cf68bd74a
+  - name: basket-skill
+    version: 0.0.1
+    skillId: 5b06c5ff-7cf3-49c4-8641-142270c81db4
+  - name: order-skill
+    version: 0.0.1
+    skillId: d4045304-7c30-4750-9edd-340eb1357a39
+  - name: custom-data-skill
+    version: 0.0.1
+    skillId: 83fe411c-90a1-4bd3-9271-ac8e03d6a3be
+  - name: payment-skill
+    version: 0.0.1
+    skillId: f2248c02-c6c6-4c3a-89bf-ff09ec11529a
+jobs:
+  - name: test-job
+    version: 1.0.2
+    jobId: d66b73a0-f944-4718-b6a2-f07bfeabd625
+    schedule:
+      type: once
+      executeAt: '2025-10-20T01:08:04.639Z'
+webhooks:
+  - name: test-webhook
+    version: 1.0.1
+    webhookId: c967fd58-1d4d-49b6-8fa6-ec36b4d23e7f