@voltagent/libsql 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,519 @@
+import { WorkflowHistoryEntry, WorkflowStepHistoryEntry, WorkflowTimelineEvent, WorkflowStats, MemoryOptions, Memory, MessageFilterOptions, MemoryMessage, NewTimelineEvent, CreateConversationInput, Conversation, ConversationQueryOptions } from '@voltagent/core';
+import { Logger } from '@voltagent/logger';
+import { Client } from '@libsql/client';
+
+/**
+ * LibSQL extension for workflow memory operations
+ * This class provides workflow-specific storage operations for LibSQL
+ */
+declare class LibSQLWorkflowExtension {
+    private client;
+    private _tablePrefix;
+    private logger;
+    constructor(client: Client, _tablePrefix?: string, logger?: Logger);
+    /**
+     * Store a workflow history entry
+     */
+    storeWorkflowHistory(entry: WorkflowHistoryEntry): Promise<void>;
+    /**
+     * Get a workflow history entry by ID
+     */
+    getWorkflowHistory(id: string): Promise<WorkflowHistoryEntry | null>;
+    /**
+     * Get all workflow history entries for a specific workflow
+     */
+    getWorkflowHistoryByWorkflowId(workflowId: string): Promise<WorkflowHistoryEntry[]>;
+    /**
+     * Update a workflow history entry
+     */
+    updateWorkflowHistory(id: string, updates: Partial<WorkflowHistoryEntry>): Promise<void>;
+    /**
+     * Delete a workflow history entry
+     */
+    deleteWorkflowHistory(id: string): Promise<void>;
+    /**
+     * Store a workflow step entry
+     */
+    storeWorkflowStep(step: WorkflowStepHistoryEntry): Promise<void>;
+    /**
+     * Get a workflow step by ID
+     */
+    getWorkflowStep(id: string): Promise<WorkflowStepHistoryEntry | null>;
+    /**
+     * Get all workflow steps for a specific workflow history
+     */
+    getWorkflowSteps(workflowHistoryId: string): Promise<WorkflowStepHistoryEntry[]>;
+    /**
+     * Update a workflow step
+     */
+    updateWorkflowStep(id: string, updates: Partial<WorkflowStepHistoryEntry>): Promise<void>;
+    /**
+     * Delete a workflow step
+     */
+    deleteWorkflowStep(id: string): Promise<void>;
+    /**
+     * Store a workflow timeline event
+     */
+    storeWorkflowTimelineEvent(event: WorkflowTimelineEvent): Promise<void>;
+    /**
+     * Get a workflow timeline event by ID
+     */
+    getWorkflowTimelineEvent(id: string): Promise<WorkflowTimelineEvent | null>;
+    /**
+     * Get all workflow timeline events for a specific workflow history
+     */
+    getWorkflowTimelineEvents(workflowHistoryId: string): Promise<WorkflowTimelineEvent[]>;
+    /**
+     * Delete a workflow timeline event
+     */
+    deleteWorkflowTimelineEvent(id: string): Promise<void>;
+    /**
+     * Get all workflow IDs
+     */
+    getAllWorkflowIds(): Promise<string[]>;
+    /**
+     * Get workflow statistics
+     */
+    getWorkflowStats(workflowId: string): Promise<WorkflowStats>;
+    /**
+     * Get workflow history with all related data (steps and events)
+     */
+    getWorkflowHistoryWithStepsAndEvents(id: string): Promise<WorkflowHistoryEntry | null>;
+    /**
+     * Delete workflow history and all related data
+     */
+    deleteWorkflowHistoryWithRelated(id: string): Promise<void>;
+    /**
+     * Clean up old workflow histories
+     */
+    cleanupOldWorkflowHistories(workflowId: string, maxEntries: number): Promise<number>;
+    /**
+     * Parse workflow history row from database
+     */
+    private parseWorkflowHistoryRow;
+    /**
+     * Parse workflow step row from database
+     */
+    private parseWorkflowStepRow;
+    /**
+     * Parse workflow timeline event row from database
+     */
+    private parseWorkflowTimelineEventRow;
+}
+
+/**
+ * Options for configuring the LibSQLStorage
+ */
+interface LibSQLStorageOptions extends MemoryOptions {
+    /**
+     * LibSQL connection URL
+     * Can be either a remote Turso URL or a local file path
+     * @default "file:./.voltagent/memory.db"
+     * @example "libsql://your-database.turso.io" for remote Turso
+     * @example "file:memory.db" for local SQLite in current directory
+     * @example "file:.voltagent/memory.db" for local SQLite in .voltagent folder
+     */
+    url?: string;
+    /**
+     * Auth token for LibSQL/Turso
+     * Not needed for local SQLite
+     */
+    authToken?: string;
+    /**
+     * Prefix for table names
+     * @default "voltagent_memory"
+     */
+    tablePrefix?: string;
+    /**
+     * Whether to enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Storage limit for the LibSQLStorage
+     * @default 100
+     */
+    storageLimit?: number;
+    /**
+     * Number of retry attempts for database operations when encountering busy/locked errors
+     * @default 3
+     */
+    retryAttempts?: number;
+    /**
+     * Base delay in milliseconds before retrying a failed operation
+     * Uses a jittered exponential backoff strategy for better load distribution
+     * @default 50
+     */
+    baseDelayMs?: number;
+    /**
+     * Optional logger instance
+     */
+    logger?: Logger;
+}
+declare class LibSQLStorage implements Memory {
+    private client;
+    private options;
+    private initialized;
+    private workflowExtension;
+    private logger;
+    private retryAttempts;
+    private baseDelayMs;
+    /**
+     * Create a new LibSQL storage
+     * @param options Configuration options
+     */
+    constructor(options: LibSQLStorageOptions);
+    /**
+     * Log a debug message if debug is enabled
+     * @param message Message to log
+     * @param data Additional data to log
+     */
+    private debug;
+    /**
+     * Calculate delay with jitter for better load distribution
+     * @param attempt Current retry attempt number
+     * @returns Delay in milliseconds
+     */
+    private calculateRetryDelay;
+    /**
+     * Execute a database operation with retry strategy
+     * Implements jittered exponential backoff
+     * @param operationFn The operation function to execute
+     * @param operationName Operation name for logging
+     * @returns The result of the operation
+     */
+    private executeWithRetryStrategy;
+    /**
+     * Initialize workflow tables
+     */
+    private initializeWorkflowTables;
+    /**
+     * Initialize the database tables
+     * @returns Promise that resolves when initialization is complete
+     */
+    private initializeDatabase;
+    /**
+     * Generate a unique ID for a message
+     * @returns Unique ID
+     */
+    private generateId;
+    /**
+     * Get messages with filtering options
+     * @param options Filtering options
+     * @returns Filtered messages
+     */
+    getMessages(options?: MessageFilterOptions): Promise<MemoryMessage[]>;
+    /**
+     * Add a message to the conversation history
+     * @param message Message to add
+     * @param userId User identifier (optional, defaults to "default")
+     * @param conversationId Conversation identifier (optional, defaults to "default")
+     */
+    addMessage(message: MemoryMessage, conversationId?: string): Promise<void>;
+    /**
+     * Prune old messages to respect storage limit
+     * @param conversationId Conversation ID to prune messages for
+     */
+    private pruneOldMessages;
+    /**
+     * Clear messages from memory
+     */
+    clearMessages(options: {
+        userId: string;
+        conversationId?: string;
+    }): Promise<void>;
+    /**
+     * Close the database connection
+     */
+    close(): Promise<void>;
+    /**
+     * Add or update a history entry
+     * @param key Entry ID
+     * @param value Entry data
+     * @param agentId Agent ID for filtering
+     */
+    addHistoryEntry(key: string, value: any, agentId: string): Promise<void>;
+    /**
+     * Update an existing history entry
+     * @param key Entry ID
+     * @param value Updated entry data
+     * @param agentId Agent ID for filtering
+     */
+    updateHistoryEntry(key: string, value: any, agentId: string): Promise<void>;
+    /**
+     * Add a history step
+     * @param key Step ID
+     * @param value Step data
+     * @param historyId Related history entry ID
+     * @param agentId Agent ID for filtering
+     */
+    addHistoryStep(key: string, value: any, historyId: string, agentId: string): Promise<void>;
+    /**
+     * Update a history step
+     * @param key Step ID
+     * @param value Updated step data
+     * @param historyId Related history entry ID
+     * @param agentId Agent ID for filtering
+     */
+    updateHistoryStep(key: string, value: any, historyId: string, agentId: string): Promise<void>;
+    /**
+     * Add a timeline event
+     * @param key Event ID (UUID)
+     * @param value Timeline event data
+     * @param historyId Related history entry ID
+     * @param agentId Agent ID for filtering
+     */
+    addTimelineEvent(key: string, value: NewTimelineEvent, historyId: string, agentId: string): Promise<void>;
+    /**
+     * Get a history entry by ID
+     * @param key Entry ID
+     * @returns The history entry or undefined if not found
+     */
+    getHistoryEntry(key: string): Promise<any | undefined>;
+    /**
+     * Get a history step by ID
+     * @param key Step ID
+     * @returns The history step or undefined if not found
+     */
+    getHistoryStep(key: string): Promise<any | undefined>;
+    createConversation(conversation: CreateConversationInput): Promise<Conversation>;
+    getConversation(id: string): Promise<Conversation | null>;
+    getConversations(resourceId: string): Promise<Conversation[]>;
+    getConversationsByUserId(userId: string, options?: Omit<ConversationQueryOptions, "userId">): Promise<Conversation[]>;
+    /**
+     * Query conversations with filtering and pagination options
+     *
+     * @param options Query options for filtering and pagination
+     * @returns Promise that resolves to an array of conversations matching the criteria
+     * @see {@link https://voltagent.dev/docs/agents/memory/libsql#querying-conversations | Querying Conversations}
+     */
+    queryConversations(options: ConversationQueryOptions): Promise<Conversation[]>;
+    /**
+     * Get messages for a specific conversation with pagination support
+     *
+     * @param conversationId The unique identifier of the conversation to retrieve messages from
+     * @param options Optional pagination and filtering options
+     * @returns Promise that resolves to an array of messages in chronological order (oldest first)
+     * @see {@link https://voltagent.dev/docs/agents/memory/libsql#conversation-messages | Getting Conversation Messages}
+     */
+    getConversationMessages(conversationId: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<MemoryMessage[]>;
+    updateConversation(id: string, updates: Partial<Omit<Conversation, "id" | "createdAt" | "updatedAt">>): Promise<Conversation>;
+    deleteConversation(id: string): Promise<void>;
+    /**
+     * Get all history entries for an agent with pagination
+     * @param agentId Agent ID
+     * @param page Page number (0-based)
+     * @param limit Number of entries per page
+     * @returns Object with entries array and total count
+     */
+    getAllHistoryEntriesByAgent(agentId: string, page: number, limit: number): Promise<{
+        entries: any[];
+        total: number;
+    }>;
+    /**
+     * Migrates agent history data from old structure to new structure.
+     * If migration fails, it can be rolled back using the backup mechanism.
+     *
+     * Old database structure:
+     * CREATE TABLE voltagent_memory_agent_history (
+     *   key TEXT PRIMARY KEY,
+     *   value TEXT NOT NULL,
+     *   agent_id TEXT
+     * );
+     */
+    migrateAgentHistoryData(options?: {
+        createBackup?: boolean;
+        restoreFromBackup?: boolean;
+        deleteBackupAfterSuccess?: boolean;
+    }): Promise<{
+        success: boolean;
+        migratedCount?: number;
+        error?: Error;
+        backupCreated?: boolean;
+    }>;
+    /**
+     * Migrate conversation schema to add user_id and update messages table
+     *
+     * ⚠️  **CRITICAL WARNING: DESTRUCTIVE OPERATION** ⚠️
+     *
+     * This method performs a DESTRUCTIVE schema migration that:
+     * - DROPS and recreates existing tables
+     * - Creates temporary tables during migration
+     * - Modifies the primary key structure of the messages table
+     * - Can cause DATA LOSS if interrupted or if errors occur
+     *
+     * **IMPORTANT SAFETY REQUIREMENTS:**
+     * - 🛑 STOP all application instances before running this migration
+     * - 🛑 Ensure NO concurrent database operations are running
+     * - 🛑 Take a full database backup before running (independent of built-in backup)
+     * - 🛑 Test the migration on a copy of production data first
+     * - 🛑 Plan for downtime during migration execution
+     *
+     * **What this migration does:**
+     * 1. Creates backup tables (if createBackup=true)
+     * 2. Creates temporary tables with new schema
+     * 3. Migrates data from old tables to new schema
+     * 4. DROPS original tables
+     * 5. Renames temporary tables to original names
+     * 6. All operations are wrapped in a transaction for atomicity
+     *
+     * @param options Migration configuration options
+     * @param options.createBackup Whether to create backup tables before migration (default: true, HIGHLY RECOMMENDED)
+     * @param options.restoreFromBackup Whether to restore from existing backup instead of migrating (default: false)
+     * @param options.deleteBackupAfterSuccess Whether to delete backup tables after successful migration (default: false)
+     *
+     * @returns Promise resolving to migration result with success status, migrated count, and backup info
+     *
+     * @example
+     * ```typescript
+     * // RECOMMENDED: Run with backup creation (default)
+     * const result = await storage.migrateConversationSchema({
+     *   createBackup: true,
+     *   deleteBackupAfterSuccess: false // Keep backup for safety
+     * });
+     *
+     * if (result.success) {
+     *   console.log(`Migrated ${result.migratedCount} conversations successfully`);
+     * } else {
+     *   console.error('Migration failed:', result.error);
+     *   // Consider restoring from backup
+     * }
+     *
+     * // If migration fails, restore from backup:
+     * const restoreResult = await storage.migrateConversationSchema({
+     *   restoreFromBackup: true
+     * });
+     * ```
+     *
+     * @throws {Error} If migration fails and transaction is rolled back
+     *
+     * @since This migration is typically only needed when upgrading from older schema versions
+     */
+    private migrateConversationSchema;
+    /**
+     * Get conversations for a user with a fluent query builder interface
+     * @param userId User ID to filter by
+     * @returns Query builder object
+     */
+    getUserConversations(userId: string): {
+        /**
+         * Limit the number of results
+         * @param count Number of conversations to return
+         * @returns Query builder
+         */
+        limit: (count: number) => {
+            /**
+             * Order results by a specific field
+             * @param field Field to order by
+             * @param direction Sort direction
+             * @returns Query builder
+             */
+            orderBy: (field?: "created_at" | "updated_at" | "title", direction?: "ASC" | "DESC") => {
+                /**
+                 * Execute the query and return results
+                 * @returns Promise of conversations
+                 */
+                execute: () => Promise<Conversation[]>;
+            };
+            /**
+             * Execute the query with default ordering
+             * @returns Promise of conversations
+             */
+            execute: () => Promise<Conversation[]>;
+        };
+        /**
+         * Order results by a specific field
+         * @param field Field to order by
+         * @param direction Sort direction
+         * @returns Query builder
+         */
+        orderBy: (field?: "created_at" | "updated_at" | "title", direction?: "ASC" | "DESC") => {
+            /**
+             * Limit the number of results
+             * @param count Number of conversations to return
+             * @returns Query builder
+             */
+            limit: (count: number) => {
+                /**
+                 * Execute the query and return results
+                 * @returns Promise of conversations
+                 */
+                execute: () => Promise<Conversation[]>;
+            };
+            /**
+             * Execute the query without limit
+             * @returns Promise of conversations
+             */
+            execute: () => Promise<Conversation[]>;
+        };
+        /**
+         * Execute the query with default options
+         * @returns Promise of conversations
+         */
+        execute: () => Promise<Conversation[]>;
+    };
+    /**
+     * Get conversation by ID and ensure it belongs to the specified user
+     * @param conversationId Conversation ID
+     * @param userId User ID to validate ownership
+     * @returns Conversation or null
+     */
+    getUserConversation(conversationId: string, userId: string): Promise<Conversation | null>;
+    /**
+     * Get paginated conversations for a user
+     * @param userId User ID
+     * @param page Page number (1-based)
+     * @param pageSize Number of items per page
+     * @returns Object with conversations and pagination info
+     */
+    getPaginatedUserConversations(userId: string, page?: number, pageSize?: number): Promise<{
+        conversations: Conversation[];
+        page: number;
+        pageSize: number;
+        hasMore: boolean;
+    }>;
+    /**
+     * Check and create migration flag table, return if migration already completed
+     * @param migrationType Type of migration to check
+     * @returns Object with completion status and details
+     */
+    private checkMigrationFlag;
+    /**
+     * Set migration flag after successful completion
+     * @param migrationType Type of migration completed
+     * @param migratedCount Number of records migrated
+     */
+    private setMigrationFlag;
+    /**
+     * Migrate agent history schema to add userId and conversationId columns
+     */
+    private migrateAgentHistorySchema;
+    storeWorkflowHistory(entry: any): Promise<void>;
+    getWorkflowHistory(id: string): Promise<any>;
+    getWorkflowHistoryByWorkflowId(workflowId: string): Promise<any[]>;
+    updateWorkflowHistory(id: string, updates: any): Promise<void>;
+    deleteWorkflowHistory(id: string): Promise<void>;
+    storeWorkflowStep(step: any): Promise<void>;
+    getWorkflowStep(id: string): Promise<any>;
+    getWorkflowSteps(workflowHistoryId: string): Promise<any[]>;
+    updateWorkflowStep(id: string, updates: any): Promise<void>;
+    deleteWorkflowStep(id: string): Promise<void>;
+    storeWorkflowTimelineEvent(event: any): Promise<void>;
+    getWorkflowTimelineEvent(id: string): Promise<any>;
+    getWorkflowTimelineEvents(workflowHistoryId: string): Promise<any[]>;
+    deleteWorkflowTimelineEvent(id: string): Promise<void>;
+    getAllWorkflowIds(): Promise<string[]>;
+    getWorkflowStats(workflowId: string): Promise<any>;
+    getWorkflowHistoryWithStepsAndEvents(id: string): Promise<any>;
+    deleteWorkflowHistoryWithRelated(id: string): Promise<void>;
+    cleanupOldWorkflowHistories(workflowId: string, maxEntries: number): Promise<number>;
+    /**
+     * Get the workflow extension for advanced workflow operations
+     */
+    getWorkflowExtension(): LibSQLWorkflowExtension;
+}
+
+export { LibSQLStorage, type LibSQLStorageOptions };