aparavi-client 1.0.8 → 1.0.10

package/dist/esm/client.js

@@ -325,11 +325,6 @@ export class AparaviClient extends DAPClient {
     static _convertToWebSocketUri(uri) {
         try {
             const url = new URL(uri);
-            // If already a WebSocket URI, preserve it
-            if (url.protocol === 'wss:' || url.protocol === 'ws:') {
-                return `${url.protocol}//${url.host}`;
-            }
-            // Convert HTTP/HTTPS to WS/WSS
             const wsScheme = url.protocol === 'https:' ? 'wss:' : 'ws:';
             return `${wsScheme}//${url.host}`;
         }
@@ -486,6 +481,7 @@ export class AparaviClient extends DAPClient {
      * @param options.threads - Number of threads for execution (default: 1)
      * @param options.useExisting - Use existing pipeline instance
      * @param options.args - Command line arguments to pass to pipeline
+     * @param options.ttl - Time-to-live in seconds for idle pipelines (optional, server default if not provided; use 0 for no timeout)
      *
      * @returns Promise resolving to an object containing the task token and other metadata
      * @throws Error if neither pipeline nor filepath is provided
@@ -506,7 +502,7 @@ export class AparaviClient extends DAPClient {
      * ```
      */
     async use(options = {}) {
-        const { token, filepath, pipeline, source, threads, useExisting, args } = options;
+        const { token, filepath, pipeline, source, threads, useExisting, args, ttl } = options;
         // Validate required parameters
         if (!pipeline && !filepath) {
             throw new Error('Pipeline configuration or file path is required and must be specified');
@@ -530,8 +526,6 @@ export class AparaviClient extends DAPClient {
         let processedConfig = JSON.parse(JSON.stringify(pipelineConfig));
         // Perform environment variable substitution on the pipeline configuration
         processedConfig = this.processEnvSubstitution(processedConfig);
-        // Sanitize webhook configs for remote servers (remove port parameter)
-        processedConfig = this.sanitizePipelineForRemote(processedConfig);
         // Override source if specified (after substitution)
         if (source !== undefined) {
             processedConfig.pipeline.source = source;
@@ -541,6 +535,10 @@ export class AparaviClient extends DAPClient {
             pipeline: processedConfig,
             args: args || [],
         };
+        // Add TTL if provided (server uses its default if not specified)
+        if (ttl !== undefined) {
+            arguments_.ttl = ttl;
+        }
         // Add optional parameters if specified
         if (token !== undefined) {
             arguments_.token = token;
@@ -570,105 +568,6 @@ export class AparaviClient extends DAPClient {
         // Type assertion to ensure token is present
         return responseBody;
     }
-    /**
-     * Check if the client is connected to a remote server (not localhost).
-     * @returns True if connecting to a remote server, False if localhost
-     */
-    isRemoteServer() {
-        try {
-            const uri = this._uri || '';
-            if (!uri) {
-                return true; // Assume remote if URI not available
-            }
-            // Normalize URI - remove protocol and check hostname
-            let uriLower = uri.toLowerCase();
-            // Remove ws://, wss://, http://, https://
-            uriLower = uriLower.replace(/^(ws|wss|http|https):\/\//, '');
-            // Remove port if present
-            uriLower = uriLower.replace(/:\d+/, '');
-            // Remove path
-            uriLower = uriLower.split('/')[0];
-            // Check if it's localhost or local
-            const localhostPatterns = ['localhost', '127.0.0.1', '::1', '0.0.0.0', 'local'];
-            return !localhostPatterns.some(pattern => uriLower.includes(pattern));
-        }
-        catch {
-            // If we can't determine, assume remote to be safe
-            return true;
-        }
-    }
-    /**
-     * Remove port parameter from webhook config for remote servers.
-     * @param config Webhook component configuration object
-     * @returns Sanitized configuration object
-     */
-    sanitizeWebhookConfig(config) {
-        if (!config || typeof config !== 'object') {
-            return config;
-        }
-        // Check if this is a webhook component
-        if (config.type === 'webhook' || String(config.provider || '').toLowerCase().includes('webhook')) {
-            // Check parameters
-            const parameters = config.parameters;
-            if (parameters && typeof parameters === 'object' && 'port' in parameters) {
-                // Remove port for remote servers
-                if (this.isRemoteServer()) {
-                    // Create a copy to avoid modifying original
-                    const sanitized = JSON.parse(JSON.stringify(config));
-                    const { port, ...restParams } = sanitized.parameters;
-                    sanitized.parameters = restParams;
-                    this.debugMessage('Removed port parameter from webhook config for remote server');
-                    return sanitized;
-                }
-            }
-        }
-        return config;
-    }
-    /**
-     * Recursively sanitize pipeline configuration for remote servers.
-     * Removes port parameters from webhook components.
-     * @param config Pipeline configuration object
-     * @returns Sanitized pipeline configuration
-     */
-    sanitizePipelineForRemote(config) {
-        if (!config || typeof config !== 'object') {
-            return config;
-        }
-        // Create a deep copy to avoid modifying original
-        const sanitized = JSON.parse(JSON.stringify(config));
-        // Check if this is a pipeline config with components
-        if (sanitized.pipeline) {
-            const pipeline = sanitized.pipeline;
-            if (pipeline.components && Array.isArray(pipeline.components)) {
-                // Process each component
-                for (let i = 0; i < pipeline.components.length; i++) {
-                    const component = pipeline.components[i];
-                    if (component && typeof component === 'object') {
-                        // Check if this is a webhook component by provider
-                        const provider = component.provider || '';
-                        if (provider === 'webhook' && component.config) {
-                            // Sanitize webhook configs
-                            pipeline.components[i].config = this.sanitizeWebhookConfig(component.config);
-                        }
-                    }
-                }
-            }
-        }
-        // Also check direct component arrays (for nested structures)
-        if (sanitized.components && Array.isArray(sanitized.components)) {
-            for (let i = 0; i < sanitized.components.length; i++) {
-                const component = sanitized.components[i];
-                if (component && typeof component === 'object') {
-                    // Check if this is a webhook component by provider
-                    const provider = component.provider || '';
-                    if (provider === 'webhook' && component.config) {
-                        component.config = this.sanitizeWebhookConfig(component.config);
-                    }
-                }
-            }
-        }
-        return sanitized;
-    }
     /**
      * Terminate a running pipeline.
      */
@@ -1056,6 +955,638 @@ export class AparaviClient extends DAPClient {
         }
     }
     // ============================================================================
+    // PROJECT STORAGE MANAGEMENT
+    // ============================================================================
+    /**
+     * Save or update a project pipeline.
+     *
+     * Stores a project pipeline configuration on the server. If the project
+     * already exists, it will be updated. Use expectedVersion to ensure
+     * you're updating the version you expect (prevents conflicts).
+     *
+     * @param options - Save project options
+     * @param options.projectId - Unique identifier for the project
+     * @param options.pipeline - Pipeline configuration object
+     * @param options.expectedVersion - Expected current version for atomic updates (optional)
+     * @returns Promise resolving to save result with success status, projectId, and new version
+     * @throws Error if save fails due to version mismatch, storage error, or invalid input
+     *
+     * @example
+     * ```typescript
+     * // Save a new project
+     * const result = await client.saveProject({
+     *   projectId: 'proj-123',
+     *   pipeline: {
+     *     name: 'Data Processor',
+     *     source: 'source_1',
+     *     components: [...]
+     *   }
+     * });
+     * console.log(`Saved version: ${result.version}`);
+     *
+     * // Update existing project with version check
+     * const existing = await client.getProject({ projectId: 'proj-123' });
+     * existing.pipeline.name = 'Updated Name';
+     * const updated = await client.saveProject({
+     *   projectId: 'proj-123',
+     *   pipeline: existing.pipeline,
+     *   expectedVersion: existing.version
+     * });
+     * ```
+     */
+    async saveProject(options) {
+        const { projectId, pipeline, expectedVersion } = options;
+        // Validate inputs
+        if (!projectId) {
+            throw new Error('projectId is required');
+        }
+        if (!pipeline || typeof pipeline !== 'object') {
+            throw new Error('pipeline must be a non-empty object');
+        }
+        // Build request arguments
+        const args = {
+            subcommand: 'save_project',
+            projectId,
+            pipeline,
+        };
+        // Add optional version for atomic updates
+        if (expectedVersion !== undefined) {
+            args.expectedVersion = expectedVersion;
+        }
+        // Send request to server
+        const request = this.buildRequest('apaext_store', { arguments: args });
+        const response = await this.request(request);
+        // Check for errors
+        if (this.didFail(response)) {
+            const errorMsg = response.message || 'Unknown error saving project';
+            this.debugMessage(`Project save failed: ${errorMsg}`);
+            throw new Error(errorMsg);
+        }
+        // Extract and return response
+        this.debugMessage(`Project saved successfully: ${projectId}, version: ${response.body?.version}`);
+        return response.body;
+    }
+    /**
+     * Retrieve a project by its ID.
+     *
+     * Fetches the complete pipeline configuration and current version for
+     * the specified project. Use this before updating to get the current
+     * version for atomic updates.
+     *
+     * @param options - Get project options
+     * @param options.projectId - Unique identifier of the project to retrieve
+     * @returns Promise resolving to project data with success status, pipeline, and version
+     * @throws Error if project doesn't exist or retrieval fails
+     *
+     * @example
+     * ```typescript
+     * // Get a project
+     * try {
+     *   const project = await client.getProject({ projectId: 'proj-123' });
+     *   console.log(`Project: ${project.pipeline.name}`);
+     *   console.log(`Version: ${project.version}`);
+     * } catch (error) {
+     *   if (error.message.includes('NOT_FOUND')) {
+     *     console.log("Project doesn't exist");
+     *   }
+     * }
+     *
+     * // Before updating - get current version
+     * const project = await client.getProject({ projectId: 'proj-123' });
+     * project.pipeline.name = 'Updated';
+     * await client.saveProject({
+     *   projectId: 'proj-123',
+     *   pipeline: project.pipeline,
+     *   expectedVersion: project.version
+     * });
+     * ```
+     */
+    async getProject(options) {
+        const { projectId } = options;
+        // Validate inputs
+        if (!projectId) {
+            throw new Error('projectId is required');
+        }
+        // Build request
+        const args = {
+            subcommand: 'get_project',
+            projectId,
+        };
+        // Send request to server
+        const request = this.buildRequest('apaext_store', { arguments: args });
+        const response = await this.request(request);
+        // Check for errors
+        if (this.didFail(response)) {
+            const errorMsg = response.message || 'Unknown error retrieving project';
+            this.debugMessage(`Project retrieval failed: ${errorMsg}`);
+            throw new Error(errorMsg);
+        }
+        // Extract and return response
+        this.debugMessage(`Project retrieved successfully: ${projectId}`);
+        return response.body;
+    }
+    /**
+     * Delete a project by its ID.
+     *
+     * Permanently removes a project from storage. Optionally verify the
+     * version before deletion to ensure you're deleting the version you
+     * expect (prevents accidental deletion of modified projects).
+     *
+     * @param options - Delete project options
+     * @param options.projectId - Unique identifier of the project to delete
+     * @param options.expectedVersion - Expected current version for atomic deletion (required)
+     * @returns Promise resolving to deletion result with success status and message
+     * @throws Error if project doesn't exist, version mismatch, or deletion fails
+     *
+     * @example
+     * ```typescript
+     * // Safe deletion with version check
+     * const project = await client.getProject({ projectId: 'proj-123' });
+     * try {
+     *   const result = await client.deleteProject({
+     *     projectId: 'proj-123',
+     *     expectedVersion: project.version
+     *   });
+     *   console.log('Project deleted successfully');
+     * } catch (error) {
+     *   if (error.message.includes('CONFLICT')) {
+     *     console.log('Project was modified, deletion cancelled');
+     *   }
+     * }
+     * ```
+     */
+    async deleteProject(options) {
+        const { projectId, expectedVersion } = options;
+        // Validate inputs
+        if (!projectId) {
+            throw new Error('projectId is required');
+        }
+        // Build request
+        const args = {
+            subcommand: 'delete_project',
+            projectId,
+        };
+        // Add optional version for atomic deletion
+        if (expectedVersion !== undefined) {
+            args.expectedVersion = expectedVersion;
+        }
+        // Send request to server
+        const request = this.buildRequest('apaext_store', { arguments: args });
+        const response = await this.request(request);
+        // Check for errors
+        if (this.didFail(response)) {
+            const errorMsg = response.message || 'Unknown error deleting project';
+            this.debugMessage(`Project deletion failed: ${errorMsg}`);
+            throw new Error(errorMsg);
+        }
+        // Extract and return response
+        this.debugMessage(`Project deleted successfully: ${projectId}`);
+        return response.body;
+    }
+    /**
+     * List all projects for the current user.
+     *
+     * Retrieves a summary of all projects stored for the authenticated user.
+     * Each project summary includes the ID, name, list of data sources, and total component count.
+     *
+     * @returns Promise resolving to list result with success status, projects array, and count
+     * @throws Error if retrieval fails
+     *
+     * @example
+     * ```typescript
+     * // List all projects
+     * const result = await client.getAllProjects();
+     * console.log(`Found ${result.count} projects:`);
+     * for (const project of result.projects) {
+     *   console.log(`- ${project.id}: ${project.name} (${project.totalComponents} components)`);
+     *   for (const source of project.sources) {
+     *     console.log(`  * ${source.name} (${source.provider})`);
+     *   }
+     * }
+     *
+     * // Find specific project
+     * const result = await client.getAllProjects();
+     * const myProject = result.projects.find(p => p.id === 'proj-123');
+     * ```
+     */
+    async getAllProjects() {
+        // Build request
+        const args = {
+            subcommand: 'get_all_projects',
+        };
+        // Send request to server
+        const request = this.buildRequest('apaext_store', { arguments: args });
+        const response = await this.request(request);
+        // Check for errors
+        if (this.didFail(response)) {
+            const errorMsg = response.message || 'Unknown error listing projects';
+            this.debugMessage(`Project list retrieval failed: ${errorMsg}`);
+            throw new Error(errorMsg);
+        }
+        // Extract and return response
+        const projectCount = response.body?.count || 0;
+        this.debugMessage(`Projects retrieved successfully: ${projectCount} projects`);
+        return response.body;
+    }
+    // ============================================================================
+    // TEMPLATE STORAGE MANAGEMENT (System-wide templates)
+    // ============================================================================
+    /**
+     * Save or update a template pipeline.
+     *
+     * Stores a template pipeline configuration on the server. Templates are system-wide
+     * and accessible to all users. If the template already exists, it will be updated.
+     * Use expectedVersion to ensure you're updating the version you expect.
+     *
+     * @param options - Save template options
+     * @param options.templateId - Unique identifier for the template
+     * @param options.pipeline - Pipeline configuration object
+     * @param options.expectedVersion - Expected current version for atomic updates (optional)
+     * @returns Promise resolving to save result with success status, templateId, and new version
+     * @throws Error if save fails due to version mismatch, storage error, or invalid input
+     *
+     * @example
+     * ```typescript
+     * // Save a new template
+     * const result = await client.saveTemplate({
+     *   templateId: 'tmpl-123',
+     *   pipeline: {
+     *     source: 'source_1',
+     *     pipeline: {
+     *       name: 'Data Processor Template',
+     *       components: [...]
+     *     }
+     *   }
+     * });
+     * console.log(`Saved version: ${result.version}`);
+     * ```
+     */
+    async saveTemplate(options) {
+        const { templateId, pipeline, expectedVersion } = options;
+        // Validate inputs
+        if (!templateId) {
+            throw new Error('templateId is required');
+        }
+        if (!pipeline || typeof pipeline !== 'object') {
+            throw new Error('pipeline must be a non-empty object');
+        }
+        // Build request arguments
+        const args = {
+            subcommand: 'save_template',
+            templateId,
+            pipeline,
+        };
+        // Add optional version for atomic updates
+        if (expectedVersion !== undefined) {
+            args.expectedVersion = expectedVersion;
+        }
+        // Send request to server
+        const request = this.buildRequest('apaext_store', { arguments: args });
+        const response = await this.request(request);
+        // Check for errors
+        if (this.didFail(response)) {
+            const errorMsg = response.message || 'Unknown error saving template';
+            this.debugMessage(`Template save failed: ${errorMsg}`);
+            throw new Error(errorMsg);
+        }
+        // Extract and return response
+        this.debugMessage(`Template saved successfully: ${templateId}, version: ${response.body?.version}`);
+        return response.body;
+    }
+    /**
+     * Retrieve a template by its ID.
+     *
+     * Fetches the complete pipeline configuration and current version for
+     * the specified template.
+     *
+     * @param options - Get template options
+     * @param options.templateId - Unique identifier of the template to retrieve
+     * @returns Promise resolving to template data with success status, pipeline, and version
+     * @throws Error if template doesn't exist or retrieval fails
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const template = await client.getTemplate({ templateId: 'tmpl-123' });
+     *   console.log(`Template: ${template.pipeline.pipeline.name}`);
+     *   console.log(`Version: ${template.version}`);
+     * } catch (error) {
+     *   if (error.message.includes('NOT_FOUND')) {
+     *     console.log("Template doesn't exist");
+     *   }
+     * }
+     * ```
+     */
+    async getTemplate(options) {
+        const { templateId } = options;
+        // Validate inputs
+        if (!templateId) {
+            throw new Error('templateId is required');
+        }
+        // Build request
+        const args = {
+            subcommand: 'get_template',
+            templateId,
+        };
+        // Send request to server
+        const request = this.buildRequest('apaext_store', { arguments: args });
+        const response = await this.request(request);
+        // Check for errors
+        if (this.didFail(response)) {
+            const errorMsg = response.message || 'Unknown error retrieving template';
+            this.debugMessage(`Template retrieval failed: ${errorMsg}`);
+            throw new Error(errorMsg);
+        }
+        // Extract and return response
+        this.debugMessage(`Template retrieved successfully: ${templateId}`);
+        return response.body;
+    }
+    /**
+     * Delete a template by its ID.
+     *
+     * Permanently removes a template from storage. Optionally verify the
+     * version before deletion to ensure you're deleting the version you expect.
+     *
+     * @param options - Delete template options
+     * @param options.templateId - Unique identifier of the template to delete
+     * @param options.expectedVersion - Expected current version for atomic deletion (optional)
+     * @returns Promise resolving to deletion result with success status and message
+     * @throws Error if template doesn't exist, version mismatch, or deletion fails
+     *
+     * @example
+     * ```typescript
+     * // Safe deletion with version check
+     * const template = await client.getTemplate({ templateId: 'tmpl-123' });
+     * try {
+     *   const result = await client.deleteTemplate({
+     *     templateId: 'tmpl-123',
+     *     expectedVersion: template.version
+     *   });
+     *   console.log('Template deleted successfully');
+     * } catch (error) {
+     *   if (error.message.includes('CONFLICT')) {
+     *     console.log('Template was modified, deletion cancelled');
+     *   }
+     * }
+     * ```
+     */
+    async deleteTemplate(options) {
+        const { templateId, expectedVersion } = options;
+        // Validate inputs
+        if (!templateId) {
+            throw new Error('templateId is required');
+        }
+        // Build request
+        const args = {
+            subcommand: 'delete_template',
+            templateId,
+        };
+        // Add optional version for atomic deletion
+        if (expectedVersion !== undefined) {
+            args.expectedVersion = expectedVersion;
+        }
+        // Send request to server
+        const request = this.buildRequest('apaext_store', { arguments: args });
+        const response = await this.request(request);
+        // Check for errors
+        if (this.didFail(response)) {
+            const errorMsg = response.message || 'Unknown error deleting template';
+            this.debugMessage(`Template deletion failed: ${errorMsg}`);
+            throw new Error(errorMsg);
+        }
+        // Extract and return response
+        this.debugMessage(`Template deleted successfully: ${templateId}`);
+        return response.body;
+    }
+    /**
+     * List all templates.
+     *
+     * Retrieves a summary of all templates stored in the system.
+     * Each template summary includes the ID, name, list of data sources, and total component count.
+     *
+     * @returns Promise resolving to list result with success status, templates array, and count
+     * @throws Error if retrieval fails
+     *
+     * @example
+     * ```typescript
+     * // List all templates
+     * const result = await client.getAllTemplates();
+     * console.log(`Found ${result.count} templates:`);
+     * for (const template of result.templates) {
+     *   console.log(`- ${template.id}: ${template.name} (${template.totalComponents} components)`);
+     *   for (const source of template.sources) {
+     *     console.log(`  * ${source.name} (${source.provider})`);
+     *   }
+     * }
+     * ```
+     */
+    async getAllTemplates() {
+        // Build request
+        const args = {
+            subcommand: 'get_all_templates',
+        };
+        // Send request to server
+        const request = this.buildRequest('apaext_store', { arguments: args });
+        const response = await this.request(request);
+        // Check for errors
+        if (this.didFail(response)) {
+            const errorMsg = response.message || 'Unknown error listing templates';
+            this.debugMessage(`Template list retrieval failed: ${errorMsg}`);
+            throw new Error(errorMsg);
+        }
+        // Extract and return response
+        const templateCount = response.body?.count || 0;
+        this.debugMessage(`Templates retrieved successfully: ${templateCount} templates`);
+        return response.body;
+    }
+    // ============================================================================
+    // LOG STORAGE MANAGEMENT (Per-project log files for historical tracking)
+    // ============================================================================
+    /**
+     * Save a log file for a source run.
+     *
+     * Creates or overwrites a log file in the project's log directory.
+     * The filename is constructed as <source>-<startTime>.log where startTime
+     * is extracted from contents.body.startTime.
+     *
+     * @param options - Save log options
+     * @param options.projectId - Project ID
+     * @param options.source - Name of the source
+     * @param options.contents - Log contents object containing body.startTime
+     * @returns Promise resolving to save result with success status and filename
+     * @throws Error if save fails
+     *
+     * @example
+     * ```typescript
+     * const logContents = {
+     *   type: 'event',
+     *   event: 'apaevt_status_update',
+     *   body: {
+     *     source: 'source_1',
+     *     startTime: 1764337626.6564875,
+     *     status: 'Completed',
+     *     completed: true,
+     *     totalCount: 100,
+     *     completedCount: 100
+     *   }
+     * };
+     * const result = await client.saveLog({
+     *   projectId: 'proj-123',
+     *   source: 'source_1',
+     *   contents: logContents
+     * });
+     * console.log(`Saved: ${result.filename}`);
+     * ```
+     */
+    async saveLog(options) {
+        const { projectId, source, contents } = options;
+        // Validate inputs
+        if (!projectId) {
+            throw new Error('projectId is required');
+        }
+        if (!source) {
+            throw new Error('source is required');
+        }
+        if (!contents || typeof contents !== 'object') {
+            throw new Error('contents must be a non-empty object');
+        }
+        // Build request arguments
+        const args = {
+            subcommand: 'save_log',
+            projectId,
+            source,
+            contents,
+        };
+        // Send request to server
+        const request = this.buildRequest('apaext_store', { arguments: args });
+        const response = await this.request(request);
+        // Check for errors
+        if (this.didFail(response)) {
+            const errorMsg = response.message || 'Unknown error saving log';
+            this.debugMessage(`Log save failed: ${errorMsg}`);
+            throw new Error(errorMsg);
+        }
+        // Extract and return response
+        this.debugMessage(`Log saved successfully: ${response.body?.filename}`);
+        return response.body;
+    }
+    /**
+     * Get a log file by source name and start time.
+     *
+     * @param options - Get log options
+     * @param options.projectId - Project ID
+     * @param options.source - Name of the source
+     * @param options.startTime - Start time of the run
+     * @returns Promise resolving to log data with success status and contents
+     * @throws Error if log not found or retrieval fails
+     *
+     * @example
+     * ```typescript
+     * const log = await client.getLog({
+     *   projectId: 'proj-123',
+     *   source: 'source_1',
+     *   startTime: 1764337626.6564875
+     * });
+     * console.log(`Status: ${log.contents.body.status}`);
+     * ```
+     */
+    async getLog(options) {
+        const { projectId, source, startTime } = options;
+        // Validate inputs
+        if (!projectId) {
+            throw new Error('projectId is required');
+        }
+        if (!source) {
+            throw new Error('source is required');
+        }
+        if (startTime === undefined || startTime === null) {
+            throw new Error('startTime is required');
+        }
+        // Build request
+        const args = {
+            subcommand: 'get_log',
+            projectId,
+            source,
+            startTime,
+        };
+        // Send request to server
+        const request = this.buildRequest('apaext_store', { arguments: args });
+        const response = await this.request(request);
+        // Check for errors
+        if (this.didFail(response)) {
+            const errorMsg = response.message || 'Unknown error retrieving log';
+            this.debugMessage(`Log retrieval failed: ${errorMsg}`);
+            throw new Error(errorMsg);
+        }
+        // Extract and return response
+        this.debugMessage(`Log retrieved successfully: ${projectId}/${source}`);
+        return response.body;
+    }
+    /**
+     * List log files for a project.
+     *
+     * @param options - List logs options
+     * @param options.projectId - Project ID
+     * @param options.source - Optional source name to filter logs (filters files starting with '<source>-')
+     * @param options.page - Page number (0-indexed). If negative or undefined, defaults to 0. Page size is 100.
+     * @returns Promise resolving to list result with success status, logs array, counts, and pagination info
+     * @throws Error if retrieval fails
+     *
+     * @example
+     * ```typescript
+     * // List all logs
+     * const result = await client.listLogs({ projectId: 'proj-123' });
+     * console.log(`Found ${result.total_count} logs`);
+     * for (const log of result.logs) {
+     *   console.log(`  - ${log}`);
+     * }
+     *
+     * // Filter by source
+     * const filtered = await client.listLogs({
+     *   projectId: 'proj-123',
+     *   source: 'source_1'
+     * });
+     *
+     * // With pagination
+     * const page2 = await client.listLogs({
+     *   projectId: 'proj-123',
+     *   page: 1
+     * });
+     * ```
+     */
+    async listLogs(options) {
+        const { projectId, source, page } = options;
+        // Validate inputs
+        if (!projectId) {
+            throw new Error('projectId is required');
+        }
+        // Build request
+        const args = {
+            subcommand: 'list_logs',
+            projectId,
+        };
+        // Add optional parameters
+        if (source !== undefined) {
+            args.source = source;
+        }
+        if (page !== undefined) {
+            args.page = page;
+        }
+        // Send request to server
+        const request = this.buildRequest('apaext_store', { arguments: args });
+        const response = await this.request(request);
+        // Check for errors
+        if (this.didFail(response)) {
+            const errorMsg = response.message || 'Unknown error listing logs';
+            this.debugMessage(`Log list retrieval failed: ${errorMsg}`);
+            throw new Error(errorMsg);
+        }
+        // Extract and return response
+        const logCount = response.body?.total_count || 0;
+        this.debugMessage(`Logs retrieved successfully: ${logCount} logs`);
+        return response.body;
+    }
+    // ============================================================================
     // CONTEXT MANAGER SUPPORT - Python-style async context manager
     // ============================================================================
     /**