lua-cli 2.5.8 → 3.0.0-alpha.4

package/dist/types/skill.d.ts

@@ -3,6 +3,8 @@
  * Core types and classes for building Lua AI skills
  */
 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.
@@ -140,3 +142,522 @@ export declare class LuaSkill {
      */
     run(input: Record<string, any>): Promise<any>;
 }
+/**
+ * Job schedule configuration
+ * Supports either cron-style recurring schedules or one-time execution
+ */
+export type JobSchedule = {
+    type: 'cron';
+    expression: string;
+    timezone?: string;
+} | {
+    type: 'once';
+    executeAt: Date | string;
+} | {
+    type: 'interval';
+    seconds: number;
+};
+/**
+ * Lua Job configuration.
+ * Used to initialize a new LuaJob instance.
+ */
+export interface LuaJobConfig {
+    /** Job name (optional, defaults to 'unnamed-job') */
+    name?: string;
+    /** Job version (optional, defaults to '1.0.0') */
+    version?: string;
+    /** Short description of the job (1-2 sentences) */
+    description: string;
+    /** Detailed context for what this job does */
+    context: string;
+    /** Schedule configuration - cron, once, or interval */
+    schedule: JobSchedule;
+    /**
+     * 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 */
+    retry?: {
+        maxAttempts: number;
+        backoffSeconds?: number;
+    };
+    /**
+     * 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>;
+}
+/**
+ * Lua Job class.
+ * Main class for building scheduled jobs (cron jobs, one-time tasks, intervals).
+ *
+ * A job is a scheduled task that executes at specific times or intervals.
+ * Jobs can run once, on a recurring schedule (cron), or at fixed intervals.
+ *
+ * @example
+ * ```typescript
+ * import { LuaJob } from 'lua-cli';
+ *
+ * // Daily cleanup job at 2 AM
+ * const dailyCleanup = new LuaJob({
+ *   name: 'daily-cleanup',
+ *   version: '1.0.0',
+ *   description: "Daily database cleanup job",
+ *   context: "Runs at 2 AM daily to clean up old records and optimize tables.",
+ *   schedule: {
+ *     type: 'cron',
+ *     expression: '0 2 * * *',  // 2 AM every day
+ *     timezone: 'America/New_York'
+ *   },
+ *   timeout: 600, // 10 minutes
+ *   retry: {
+ *     maxAttempts: 3,
+ *     backoffSeconds: 60
+ *   },
+ *   execute: async () => {
+ *     // Cleanup logic
+ *     console.log('Running cleanup...');
+ *     return { recordsDeleted: 150 };
+ *   }
+ * });
+ *
+ * // One-time job
+ * const sendWelcome = new LuaJob({
+ *   name: 'send-welcome',
+ *   version: '1.0.0',
+ *   description: "Send welcome email to new users",
+ *   context: "Scheduled one-time task to send welcome emails.",
+ *   schedule: {
+ *     type: 'once',
+ *     executeAt: new Date('2025-12-31T10:00:00Z')
+ *   },
+ *   execute: async () => {
+ *     console.log('Sending welcome emails...');
+ *     return { emailsSent: 100 };
+ *   }
+ * });
+ *
+ * // Interval-based job (every 5 minutes)
+ * const healthCheck = new LuaJob({
+ *   name: 'health-check',
+ *   version: '1.0.0',
+ *   description: "System health check",
+ *   context: "Runs every 5 minutes to check system health.",
+ *   schedule: {
+ *     type: 'interval',
+ *     seconds: 300  // 5 minutes
+ *   },
+ *   execute: async () => {
+ *     return { status: 'healthy' };
+ *   }
+ * });
+ * ```
+ */
+export declare class LuaJob {
+    private readonly name;
+    private readonly version;
+    private readonly description;
+    private readonly context;
+    private readonly schedule;
+    private readonly timeout;
+    private readonly retry?;
+    private readonly metadata?;
+    private readonly executeFunction;
+    /**
+     * Creates a new LuaJob instance.
+     *
+     * @param config - Configuration object containing job metadata
+     * @param config.name - Job name (optional, defaults to 'unnamed-job')
+     * @param config.version - Job version (optional, defaults to '1.0.0')
+     * @param config.description - Short description of what the job does (1-2 sentences)
+     * @param config.context - Detailed explanation of the job's purpose
+     * @param config.schedule - Schedule configuration (cron, once, or interval)
+     * @param config.timeout - Optional timeout in seconds (default: 300)
+     * @param config.retry - Optional retry configuration
+     * @param config.metadata - Optional metadata for the job
+     * @param config.execute - Function that processes the job (receives job instance as parameter)
+     */
+    constructor(config: LuaJobConfig);
+    /**
+     * Gets the job name.
+     */
+    getName(): string;
+    /**
+     * Gets the job version.
+     */
+    getVersion(): string;
+    /**
+     * Gets the job description.
+     */
+    getDescription(): string;
+    /**
+     * Gets the job context.
+     */
+    getContext(): string;
+    /**
+     * Gets the job schedule.
+     */
+    getSchedule(): JobSchedule;
+    /**
+     * Gets the job timeout in seconds.
+     */
+    getTimeout(): number;
+    /**
+     * Gets the retry configuration.
+     */
+    getRetry(): {
+        maxAttempts: number;
+        backoffSeconds?: number;
+    } | undefined;
+    /**
+     * Gets the job metadata.
+     */
+    getMetadata(): Record<string, any> | undefined;
+}
+/**
+ * Lua Webhook configuration.
+ * Used to initialize a new LuaWebhook instance.
+ */
+export interface LuaWebhookConfig {
+    /** Webhook name (optional, defaults to 'unnamed-webhook') */
+    name?: string;
+    /** Webhook version (optional, defaults to '1.0.0') */
+    version?: string;
+    /** Short description of the webhook (1-2 sentences) */
+    description: string;
+    /** Detailed context for what this webhook does and how it should be used */
+    context: string;
+    /** Optional Zod schema for query parameter validation */
+    querySchema?: ZodType;
+    /** Optional Zod schema for header validation */
+    headerSchema?: ZodType;
+    /** Optional Zod schema for body validation */
+    bodySchema?: ZodType;
+    /** Function that executes the webhook logic */
+    execute: (query?: any, headers?: any, body?: any) => Promise<any>;
+}
+/**
+ * Lua Webhook class.
+ * Main class for building webhooks with validated inputs.
+ *
+ * A webhook is an HTTP endpoint that can receive requests with validated
+ * query parameters, headers, and body. The execute function processes the
+ * validated input and returns a response.
+ *
+ * @example
+ * ```typescript
+ * import { LuaWebhook } from 'lua-cli';
+ * import { z } from 'zod';
+ *
+ * const webhook = new LuaWebhook({
+ *   name: 'user-created',
+ *   version: '1.0.0',
+ *   description: "Webhook that handles user creation events",
+ *   context: "This webhook processes new user registration events. " +
+ *            "It validates the user data and sends welcome emails.",
+ *   querySchema: z.object({
+ *     source: z.string().optional()
+ *   }),
+ *   headerSchema: z.object({
+ *     'x-api-key': z.string(),
+ *     'content-type': z.string().optional()
+ *   }),
+ *   bodySchema: z.object({
+ *     userId: z.string(),
+ *     email: z.string().email(),
+ *     name: z.string()
+ *   }),
+ *   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 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 {
+    private readonly name;
+    private readonly version;
+    private readonly description;
+    private readonly context;
+    private readonly querySchema?;
+    private readonly headerSchema?;
+    private readonly bodySchema?;
+    private readonly executeFunction;
+    /**
+     * Creates a new LuaWebhook instance.
+     *
+     * @param config - Configuration object containing webhook metadata
+     * @param config.name - Webhook name (optional, defaults to 'unnamed-webhook')
+     * @param config.version - Webhook version (optional, defaults to '1.0.0')
+     * @param config.description - Short description of what the webhook does (1-2 sentences)
+     * @param config.context - Detailed explanation of the webhook's purpose and behavior
+     * @param config.querySchema - Optional Zod schema for query parameter validation
+     * @param config.headerSchema - Optional Zod schema for header validation
+     * @param config.bodySchema - Optional Zod schema for body validation
+     * @param config.execute - Function that processes the webhook request
+     */
+    constructor(config: LuaWebhookConfig);
+    /**
+     * Gets the webhook name.
+     */
+    getName(): string;
+    /**
+     * Gets the webhook version.
+     */
+    getVersion(): string;
+    /**
+     * Gets the webhook description.
+     */
+    getDescription(): string;
+    /**
+     * Gets the webhook context.
+     */
+    getContext(): string;
+    /**
+     * Executes the webhook with validated input.
+     * Validates query parameters, headers, and body against their respective schemas
+     * before executing the webhook function.
+     *
+     * @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(
+     *   { limit: '10' },
+     *   { 'x-api-key': 'secret' },
+     *   { data: 'value' }
+     * );
+     * ```
+     */
+    execute(query?: Record<string, any>, headers?: Record<string, any>, body?: any): Promise<any>;
+}
+/**
+ * PreProcessor configuration.
+ */
+export interface PreProcessorConfig {
+    /** PreProcessor name (optional, defaults to 'unnamed-preprocessor') */
+    name?: string;
+    /** PreProcessor version (optional, defaults to '1.0.0') */
+    version?: string;
+    /** Short description of the preprocessor */
+    description: string;
+    /** Detailed context for what this preprocessor does */
+    context: 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 contentFilter = new PreProcessor({
+ *   name: 'content-filter',
+ *   version: '1.0.0',
+ *   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;
+ *     });
+ *   }
+ * });
+ * ```
+ */
+export declare class PreProcessor {
+    private readonly name;
+    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;
+    getAsync(): boolean;
+    execute(user: UserDataInstance, messages: import("../interfaces/chat.js").ChatMessage[], channel: string): Promise<import("../interfaces/chat.js").ChatMessage[]>;
+}
+/**
+ * PostProcessor configuration.
+ */
+export interface PostProcessorConfig {
+    /** PostProcessor name (optional, defaults to 'unnamed-postprocessor') */
+    name?: string;
+    /** PostProcessor version (optional, defaults to '1.0.0') */
+    version?: string;
+    /** Short description of the postprocessor */
+    description: string;
+    /** Detailed context for what this postprocessor does */
+    context: string;
+    /**
+     * 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>;
+}
+/**
+ * PostProcessor class.
+ * Processes agent responses before they reach the user.
+ *
+ * @example
+ * ```typescript
+ * const responseFormatter = new PostProcessor({
+ *   name: 'response-formatter',
+ *   version: '1.0.0',
+ *   description: 'Formats responses with branding',
+ *   context: 'Adds company signature to all responses',
+ *   execute: async (user, message, response, channel) => {
+ *     return response + '\n\n---\nPowered by Acme Corp';
+ *   }
+ * });
+ * ```
+ */
+export declare class PostProcessor {
+    private readonly name;
+    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>;
+}
+/**
+ * LuaAgent configuration interface.
+ * Provides a simplified, unified way to configure an agent with all its components.
+ *
+ * This is the recommended approach for defining your agent. Instead of exporting
+ * individual skills, jobs, webhooks, etc., you export a single LuaAgent object
+ * that contains everything.
+ */
+export interface LuaAgentConfig {
+    /** Agent name (used for identification) */
+    name: string;
+    /** Agent persona - defines the agent's behavior and personality */
+    persona: string;
+    /** Optional welcome message shown when users first interact */
+    welcomeMessage?: string;
+    /** Array of skills (each with tools) */
+    skills?: LuaSkill[];
+    /** Array of webhooks */
+    webhooks?: LuaWebhook[];
+    /** Array of scheduled jobs */
+    jobs?: LuaJob[];
+    /** Array of preprocessors (run before messages reach the agent) */
+    preProcessors?: PreProcessor[];
+    /** Array of postprocessors (run after agent generates responses) */
+    postProcessors?: PostProcessor[];
+}
+/**
+ * LuaAgent class.
+ * Unified agent configuration that consolidates skills, webhooks, jobs, and processors.
+ *
+ * This is the simplest way to define an agent. Instead of exporting multiple separate
+ * components, you create one LuaAgent that contains everything.
+ *
+ * @example
+ * ```typescript
+ * import { LuaAgent, LuaSkill, LuaJob, LuaWebhook } from 'lua-cli';
+ *
+ * // Define your skills, jobs, webhooks in separate files
+ * import { userSkill } from './skills/user-skill';
+ * import { healthCheckJob } from './jobs/health-check';
+ * import { webhookHandler } from './webhooks/handler';
+ *
+ * // Create a single agent configuration
+ * export const agent = new LuaAgent({
+ *   name: 'my-assistant',
+ *   persona: 'You are a helpful AI assistant that can manage users and products.',
+ *   welcomeMessage: 'Hello! How can I help you today?',
+ *   skills: [userSkill],
+ *   jobs: [healthCheckJob],
+ *   webhooks: [webhookHandler],
+ *   preProcessors: [],
+ *   postProcessors: []
+ * });
+ * ```
+ */
+export declare class LuaAgent {
+    private readonly name;
+    private readonly persona;
+    private readonly welcomeMessage?;
+    private readonly skills;
+    private readonly webhooks;
+    private readonly jobs;
+    private readonly preProcessors;
+    private readonly postProcessors;
+    /**
+     * Creates a new LuaAgent instance.
+     *
+     * @param config - Agent configuration
+     * @param config.name - Agent name
+     * @param config.persona - Agent persona (behavior and personality)
+     * @param config.welcomeMessage - Optional welcome message
+     * @param config.skills - Optional array of skills
+     * @param config.webhooks - Optional array of webhooks
+     * @param config.jobs - Optional array of jobs
+     * @param config.preProcessors - Optional array of preprocessors
+     * @param config.postProcessors - Optional array of postprocessors
+     */
+    constructor(config: LuaAgentConfig);
+    getName(): string;
+    getPersona(): string;
+    getWelcomeMessage(): string | undefined;
+    getSkills(): LuaSkill[];
+    getWebhooks(): LuaWebhook[];
+    getJobs(): LuaJob[];
+    getPreProcessors(): PreProcessor[];
+    getPostProcessors(): PostProcessor[];
+}