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

package/dist/config/constants.d.ts

@@ -1,11 +1,12 @@
 /**
  * Base URLs for the API, Auth, and Chat - Production
  */
-export declare const BASE_URLS: {
-    readonly API: "http://localhost:3022";
-    readonly AUTH: "https://auth.heylua.ai";
-    readonly CHAT: "http://localhost:3001";
-};
 /**
  * Base URLs for the API, Auth, and Chat - Development
  */
+export declare const BASE_URLS: {
+    readonly API: "https://api.heylua.ai";
+    readonly AUTH: "https://auth.heylua.ai";
+    readonly CHAT: "https://api.heylua.ai";
+    readonly WEBHOOK: "https://webhook.heylua.ai";
+};

package/dist/config/constants.js

@@ -1,16 +1,18 @@
 /**
  * Base URLs for the API, Auth, and Chat - Production
  */
-export const BASE_URLS = {
-    API: 'http://localhost:3022',
-    AUTH: 'https://auth.heylua.ai',
-    CHAT: 'http://localhost:3001',
-};
-/**
- * Base URLs for the API, Auth, and Chat - Development
- */
 // export const BASE_URLS = {
-//   API: 'https://api.heylua.ai',
+//   API: 'http://localhost:3022',
 //   AUTH: 'https://auth.heylua.ai',
-//   CHAT: 'https://api.heylua.ai',
+//   CHAT: 'http://localhost:3001',
+//   WEBHOOK: 'https://webhook.heylua.ai',
 // } as const;
+/**
+ * Base URLs for the API, Auth, and Chat - Development
+ */
+export const BASE_URLS = {
+    API: 'https://api.heylua.ai',
+    AUTH: 'https://auth.heylua.ai',
+    CHAT: 'https://api.heylua.ai',
+    WEBHOOK: 'https://webhook.heylua.ai',
+};

package/dist/interfaces/chat.d.ts

@@ -6,10 +6,21 @@
  * Chat message structure.
  * Currently only supports text messages.
  */
-export interface ChatMessage {
+export type ChatMessage = TextMessage | ImageMessage | FileMessage;
+export interface TextMessage {
     type: 'text';
     text: string;
 }
+export interface ImageMessage {
+    type: 'image';
+    image: string;
+    mimeType: string;
+}
+export interface FileMessage {
+    type: 'file';
+    data: string;
+    mimeType: string;
+}
 /**
  * Skill override for testing specific skill versions.
  * Used in dev mode to override production skills with sandbox versions.
@@ -18,6 +29,22 @@ export interface SkillOverride {
     skillId: string;
     sandboxId: string;
 }
+/**
+ * PreProcessor override for sandbox testing.
+ * Maps production preprocessor ID to sandbox version ID.
+ */
+export interface PreProcessorOverride {
+    preprocessorId: string;
+    sandboxId: string;
+}
+/**
+ * PostProcessor override for sandbox testing.
+ * Maps production postprocessor ID to sandbox version ID.
+ */
+export interface PostProcessorOverride {
+    postprocessorId: string;
+    sandboxId: string;
+}
 /**
  * Chat request payload.
  * Sent to the chat API to start or continue a conversation.
@@ -26,6 +53,8 @@ export interface ChatRequest {
     messages: ChatMessage[];
     navigate: boolean;
     skillOverride: SkillOverride[];
+    preprocessorOverride?: PreProcessorOverride[];
+    postprocessorOverride?: PostProcessorOverride[];
     personaOverride?: string;
     runtimeContext?: string;
 }

package/dist/interfaces/jobs.d.ts

@@ -13,6 +13,27 @@ export interface CreateJobDTO {
     timeout?: number;
     retry?: JobRetryConfig;
     metadata?: Record<string, any>;
+    dynamic?: boolean;
+    /**
+     * Optional initial version data.
+     * If provided, creates the first version automatically.
+     */
+    version?: {
+        version: string;
+        description?: string;
+        context?: string;
+        code: string;
+        executeFunction: string;
+        timeout?: number;
+        retry?: JobRetryConfig;
+        metadata?: Record<string, any>;
+    };
+    /**
+     * Auto-publish and activate the job after creation.
+     * If true, the job will be immediately active and running.
+     * Default: false
+     */
+    activate?: boolean;
 }
 /**
  * DTO for pushing a job version

package/dist/services/auth.d.ts

@@ -13,9 +13,15 @@ import { UserData } from "../interfaces/admin.js";
  */
 export declare function saveApiKey(apiKey: string): Promise<void>;
 /**
- * Loads API key from secure system keychain.
+ * Loads API key from multiple sources in priority order:
+ * 1. Secure system keychain (macOS Keychain, Windows Credential Vault, Linux libsecret)
+ * 2. LUA_API_KEY environment variable
+ * 3. LUA_API_KEY from .env file
  *
- * @returns Promise resolving to API key or null if not found
+ * This fallback mechanism allows the CLI to work in CI/CD environments where
+ * keychain access isn't available.
+ *
+ * @returns Promise resolving to API key or null if not found in any source
  */
 export declare function loadApiKey(): Promise<string | null>;
 /**

package/dist/services/auth.js

@@ -22,12 +22,44 @@ export async function saveApiKey(apiKey) {
     await keytar.setPassword(KEYTAR_SERVICE, KEYTAR_ACCOUNT, apiKey);
 }
 /**
- * Loads API key from secure system keychain.
+ * Loads API key from multiple sources in priority order:
+ * 1. Secure system keychain (macOS Keychain, Windows Credential Vault, Linux libsecret)
+ * 2. LUA_API_KEY environment variable
+ * 3. LUA_API_KEY from .env file
  *
- * @returns Promise resolving to API key or null if not found
+ * This fallback mechanism allows the CLI to work in CI/CD environments where
+ * keychain access isn't available.
+ *
+ * @returns Promise resolving to API key or null if not found in any source
  */
 export async function loadApiKey() {
-    return keytar.getPassword(KEYTAR_SERVICE, KEYTAR_ACCOUNT);
+    // Priority 1: Check secure system keychain
+    const keychainKey = await keytar.getPassword(KEYTAR_SERVICE, KEYTAR_ACCOUNT);
+    if (keychainKey) {
+        return keychainKey;
+    }
+    // Priority 2: Check environment variable
+    if (process.env.LUA_API_KEY) {
+        return process.env.LUA_API_KEY;
+    }
+    // Priority 3: Check .env file
+    try {
+        const fs = await import('fs');
+        const path = await import('path');
+        const envPath = path.join(process.cwd(), '.env');
+        if (fs.existsSync(envPath)) {
+            const envContent = fs.readFileSync(envPath, 'utf8');
+            const match = envContent.match(/^LUA_API_KEY=(.+)$/m);
+            if (match && match[1]) {
+                // Remove quotes if present
+                return match[1].trim().replace(/^["']|["']$/g, '');
+            }
+        }
+    }
+    catch (error) {
+        // Silently fail if .env file can't be read
+    }
+    return null;
 }
 /**
  * Deletes API key from secure system keychain.

package/dist/types/skill.d.ts

@@ -4,6 +4,7 @@
  */
 import { ZodType } from "zod";
 import UserDataInstance from "../common/user.instance.js";
+import { JobInstance } from "../common/job.instance.js";
 /**
  * Safe environment variable access function.
  * Gets injected at runtime with skill-specific environment variables.
@@ -171,8 +172,11 @@ export interface LuaJobConfig {
     context: string;
     /** Schedule configuration - cron, once, or interval */
     schedule: JobSchedule;
-    /** Function that executes the job logic - receives job instance as parameter */
-    execute: (job?: any) => Promise<any>;
+    /**
+     * Function that executes the job logic.
+     * Receives metadata as parameter for accessing job configuration.
+     */
+    execute: (job: JobInstance) => Promise<any>;
     /** Optional timeout in seconds (default: 300) */
     timeout?: number;
     /** Optional retry configuration */
@@ -180,7 +184,11 @@ export interface LuaJobConfig {
         maxAttempts: number;
         backoffSeconds?: number;
     };
-    /** Optional metadata for the job */
+    /**
+     * Optional metadata for the job.
+     * Can store any custom data (tags, config, context, etc.)
+     * Sent to server and accessible during execution.
+     */
     metadata?: Record<string, any>;
 }
 /**
@@ -309,19 +317,6 @@ export declare class LuaJob {
      * Gets the job metadata.
      */
     getMetadata(): Record<string, any> | undefined;
-    /**
-     * Executes the job.
-     * This is called by the scheduler at the appropriate time.
-     *
-     * @returns Promise resolving to job execution result
-     *
-     * @example
-     * ```typescript
-     * const result = await job.execute();
-     * console.log('Job completed:', result);
-     * ```
-     */
-    execute(): Promise<any>;
 }
 /**
  * Lua Webhook configuration.
@@ -343,11 +338,7 @@ export interface LuaWebhookConfig {
     /** Optional Zod schema for body validation */
     bodySchema?: ZodType;
     /** Function that executes the webhook logic */
-    execute: (input: {
-        query?: any;
-        headers?: any;
-        body?: any;
-    }) => Promise<any>;
+    execute: (query?: any, headers?: any, body?: any) => Promise<any>;
 }
 /**
  * Lua Webhook class.
@@ -380,19 +371,19 @@ export interface LuaWebhookConfig {
  *     email: z.string().email(),
  *     name: z.string()
  *   }),
- *   execute: async ({ query, headers, body }) => {
+ *   execute: async (query, headers, body) => {
  *     // Process the webhook...
  *     console.log('New user:', body.email);
  *     return { success: true, userId: body.userId };
  *   }
  * });
  *
- * // Execute the webhook with validated input
- * const result = await webhook.execute({
- *   query: { source: 'mobile' },
- *   headers: { 'x-api-key': 'secret-key' },
- *   body: { userId: '123', email: 'user@example.com', name: 'John' }
- * });
+ * // Execute the webhook with validated inputs
+ * const result = await webhook.execute(
+ *   { source: 'mobile' },
+ *   { 'x-api-key': 'secret-key' },
+ *   { userId: '123', email: 'user@example.com', name: 'John' }
+ * );
  * ```
  */
 export declare class LuaWebhook {
@@ -439,27 +430,22 @@ export declare class LuaWebhook {
      * Validates query parameters, headers, and body against their respective schemas
      * before executing the webhook function.
      *
-     * @param input - Input object containing query, headers, and/or body
-     * @param input.query - Query parameters object
-     * @param input.headers - Headers object
-     * @param input.body - Request body
+     * @param query - Query parameters object
+     * @param headers - Headers object
+     * @param body - Request body
      * @returns Promise resolving to webhook execution result
      * @throws Error if validation fails for any input
      *
      * @example
      * ```typescript
-     * const result = await webhook.execute({
-     *   query: { limit: '10' },
-     *   headers: { 'x-api-key': 'secret' },
-     *   body: { data: 'value' }
-     * });
+     * const result = await webhook.execute(
+     *   { limit: '10' },
+     *   { 'x-api-key': 'secret' },
+     *   { data: 'value' }
+     * );
      * ```
      */
-    execute(input: {
-        query?: Record<string, any>;
-        headers?: Record<string, any>;
-        body?: any;
-    }): Promise<any>;
+    execute(query?: Record<string, any>, headers?: Record<string, any>, body?: any): Promise<any>;
 }
 /**
  * PreProcessor configuration.
@@ -473,26 +459,45 @@ export interface PreProcessorConfig {
     description: string;
     /** Detailed context for what this preprocessor does */
     context: string;
-    /** Function that processes the message before sending to agent */
-    execute: (user: UserDataInstance, message: string, channel: string) => Promise<string>;
+    /**
+     * Async flag - indicates if processor should run in background on server:
+     * - true: Run asynchronously (non-blocking, for slow operations like API calls)
+     * - false: Run synchronously (blocking, for fast operations like text filtering)
+     * Default: false (synchronous)
+     */
+    async?: boolean;
+    /**
+     * Function that processes messages before sending to agent.
+     * MUST return ChatMessage[] - array of text, image, or file messages.
+     */
+    execute: (user: UserDataInstance, messages: import("../interfaces/chat.js").ChatMessage[], channel: string) => Promise<import("../interfaces/chat.js").ChatMessage[]>;
 }
 /**
  * PreProcessor class.
  * Processes user messages before they reach the agent.
+ * Can handle rich content (text, images, files).
  *
  * @example
  * ```typescript
- * const languageDetector = new PreProcessor({
- *   name: 'language-detector',
+ * const contentFilter = new PreProcessor({
+ *   name: 'content-filter',
  *   version: '1.0.0',
- *   description: 'Detects and translates messages',
- *   context: 'Detects language and translates to English if needed',
- *   execute: async (user, message, channel) => {
- *     const language = await detectLanguage(message);
- *     if (language !== 'en') {
- *       return await translate(message, 'en');
- *     }
- *     return message;
+ *   description: 'Filters and processes message content',
+ *   context: 'Filters spam, validates images, and adds context',
+ *   execute: async (user, messages, channel) => {
+ *     // Process each message
+ *     return messages.map(msg => {
+ *       if (msg.type === 'text') {
+ *         // Filter spam from text
+ *         const filtered = msg.text.replace(/spam/gi, '[filtered]');
+ *         return { type: 'text', text: filtered };
+ *       }
+ *       if (msg.type === 'image') {
+ *         // Could validate image, add watermark, etc.
+ *         return msg;
+ *       }
+ *       return msg;
+ *     });
  *   }
  * });
  * ```
@@ -502,13 +507,15 @@ export declare class PreProcessor {
     private readonly version;
     private readonly description;
     private readonly context;
+    private readonly asyncMode;
     private readonly executeFunction;
     constructor(config: PreProcessorConfig);
     getName(): string;
     getVersion(): string;
     getDescription(): string;
     getContext(): string;
-    execute(user: UserDataInstance, message: string, channel: string): Promise<string>;
+    getAsync(): boolean;
+    execute(user: UserDataInstance, messages: import("../interfaces/chat.js").ChatMessage[], channel: string): Promise<import("../interfaces/chat.js").ChatMessage[]>;
 }
 /**
  * PostProcessor configuration.
@@ -522,7 +529,17 @@ export interface PostProcessorConfig {
     description: string;
     /** Detailed context for what this postprocessor does */
     context: string;
-    /** Function that processes the agent's response before sending to user */
+    /**
+     * Async flag - indicates if processor should run in background on server:
+     * - true: Run asynchronously (non-blocking, for slow operations like API calls, translations)
+     * - false: Run synchronously (blocking, for fast operations like text formatting)
+     * Default: false (synchronous)
+     */
+    async?: boolean;
+    /**
+     * Function that processes the agent's response before sending to user.
+     * MUST return string - the formatted response text.
+     */
     execute: (user: UserDataInstance, message: string, response: string, channel: string) => Promise<string>;
 }
 /**
@@ -547,12 +564,14 @@ export declare class PostProcessor {
     private readonly version;
     private readonly description;
     private readonly context;
+    private readonly asyncMode;
     private readonly executeFunction;
     constructor(config: PostProcessorConfig);
     getName(): string;
     getVersion(): string;
     getDescription(): string;
     getContext(): string;
+    getAsync(): boolean;
     execute(user: UserDataInstance, message: string, response: string, channel: string): Promise<string>;
 }
 /**

package/dist/types/skill.js

@@ -283,21 +283,6 @@ export class LuaJob {
     getMetadata() {
         return this.metadata;
     }
-    /**
-     * Executes the job.
-     * This is called by the scheduler at the appropriate time.
-     *
-     * @returns Promise resolving to job execution result
-     *
-     * @example
-     * ```typescript
-     * const result = await job.execute();
-     * console.log('Job completed:', result);
-     * ```
-     */
-    async execute() {
-        return this.executeFunction();
-    }
 }
 /**
  * Lua Webhook class.
@@ -330,19 +315,19 @@ export class LuaJob {
  *     email: z.string().email(),
  *     name: z.string()
  *   }),
- *   execute: async ({ query, headers, body }) => {
+ *   execute: async (query, headers, body) => {
  *     // Process the webhook...
  *     console.log('New user:', body.email);
  *     return { success: true, userId: body.userId };
  *   }
  * });
  *
- * // Execute the webhook with validated input
- * const result = await webhook.execute({
- *   query: { source: 'mobile' },
- *   headers: { 'x-api-key': 'secret-key' },
- *   body: { userId: '123', email: 'user@example.com', name: 'John' }
- * });
+ * // Execute the webhook with validated inputs
+ * const result = await webhook.execute(
+ *   { source: 'mobile' },
+ *   { 'x-api-key': 'secret-key' },
+ *   { userId: '123', email: 'user@example.com', name: 'John' }
+ * );
  * ```
  */
 export class LuaWebhook {
@@ -398,81 +383,82 @@ export class LuaWebhook {
      * Validates query parameters, headers, and body against their respective schemas
      * before executing the webhook function.
      *
-     * @param input - Input object containing query, headers, and/or body
-     * @param input.query - Query parameters object
-     * @param input.headers - Headers object
-     * @param input.body - Request body
+     * @param query - Query parameters object
+     * @param headers - Headers object
+     * @param body - Request body
      * @returns Promise resolving to webhook execution result
      * @throws Error if validation fails for any input
      *
      * @example
      * ```typescript
-     * const result = await webhook.execute({
-     *   query: { limit: '10' },
-     *   headers: { 'x-api-key': 'secret' },
-     *   body: { data: 'value' }
-     * });
+     * const result = await webhook.execute(
+     *   { limit: '10' },
+     *   { 'x-api-key': 'secret' },
+     *   { data: 'value' }
+     * );
      * ```
      */
-    async execute(input) {
-        const validatedInput = {};
+    async execute(query, headers, body) {
+        let validatedQuery = query;
+        let validatedHeaders = headers;
+        let validatedBody = body;
         // Validate query parameters if schema is provided
         if (this.querySchema) {
             try {
-                validatedInput.query = this.querySchema.parse(input.query || {});
+                validatedQuery = this.querySchema.parse(query || {});
             }
             catch (error) {
                 throw new Error(`Query parameter validation failed: ${error}`);
             }
         }
-        else {
-            validatedInput.query = input.query;
-        }
         // Validate headers if schema is provided
         if (this.headerSchema) {
             try {
-                validatedInput.headers = this.headerSchema.parse(input.headers || {});
+                validatedHeaders = this.headerSchema.parse(headers || {});
             }
             catch (error) {
                 throw new Error(`Header validation failed: ${error}`);
             }
         }
-        else {
-            validatedInput.headers = input.headers;
-        }
         // Validate body if schema is provided
         if (this.bodySchema) {
             try {
-                validatedInput.body = this.bodySchema.parse(input.body);
+                validatedBody = this.bodySchema.parse(body);
             }
             catch (error) {
                 throw new Error(`Body validation failed: ${error}`);
             }
         }
-        else {
-            validatedInput.body = input.body;
-        }
-        // Execute the webhook function with validated input
-        return this.executeFunction(validatedInput);
+        // Execute the webhook function with validated inputs as separate parameters
+        return this.executeFunction(validatedQuery, validatedHeaders, validatedBody);
     }
 }
 /**
  * PreProcessor class.
  * Processes user messages before they reach the agent.
+ * Can handle rich content (text, images, files).
  *
  * @example
  * ```typescript
- * const languageDetector = new PreProcessor({
- *   name: 'language-detector',
+ * const contentFilter = new PreProcessor({
+ *   name: 'content-filter',
  *   version: '1.0.0',
- *   description: 'Detects and translates messages',
- *   context: 'Detects language and translates to English if needed',
- *   execute: async (user, message, channel) => {
- *     const language = await detectLanguage(message);
- *     if (language !== 'en') {
- *       return await translate(message, 'en');
- *     }
- *     return message;
+ *   description: 'Filters and processes message content',
+ *   context: 'Filters spam, validates images, and adds context',
+ *   execute: async (user, messages, channel) => {
+ *     // Process each message
+ *     return messages.map(msg => {
+ *       if (msg.type === 'text') {
+ *         // Filter spam from text
+ *         const filtered = msg.text.replace(/spam/gi, '[filtered]');
+ *         return { type: 'text', text: filtered };
+ *       }
+ *       if (msg.type === 'image') {
+ *         // Could validate image, add watermark, etc.
+ *         return msg;
+ *       }
+ *       return msg;
+ *     });
  *   }
  * });
  * ```
@@ -483,6 +469,7 @@ export class PreProcessor {
         this.version = config.version || '1.0.0';
         this.description = config.description;
         this.context = config.context;
+        this.asyncMode = config.async ?? false; // Default to synchronous
         this.executeFunction = config.execute;
     }
     getName() {
@@ -497,8 +484,11 @@ export class PreProcessor {
     getContext() {
         return this.context;
     }
-    async execute(user, message, channel) {
-        return this.executeFunction(user, message, channel);
+    getAsync() {
+        return this.asyncMode;
+    }
+    async execute(user, messages, channel) {
+        return this.executeFunction(user, messages, channel);
     }
 }
 /**
@@ -524,6 +514,7 @@ export class PostProcessor {
         this.version = config.version || '1.0.0';
         this.description = config.description;
         this.context = config.context;
+        this.asyncMode = config.async ?? false; // Default to synchronous
         this.executeFunction = config.execute;
     }
     getName() {
@@ -538,6 +529,9 @@ export class PostProcessor {
     getContext() {
         return this.context;
     }
+    getAsync() {
+        return this.asyncMode;
+    }
     async execute(user, message, response, channel) {
         return this.executeFunction(user, message, response, channel);
     }