aparavi-client 1.0.2

package/dist/cli/src/client.js

@@ -0,0 +1,1002 @@
+"use strict";
+/**
+ * MIT License
+ *
+ * Copyright (c) 2024 Aparavi Development Team
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = exports.AparaviClient = exports.DataPipe = void 0;
+const TransportWebSocket_1 = require("./core/TransportWebSocket");
+const DAPClient_1 = require("./core/DAPClient");
+const constants_1 = require("./constants");
+// Global counter for generating unique client IDs
+let clientId = 0;
+/**
+ * Streaming data pipe for sending large datasets to Aparavi pipelines.
+ *
+ * DataPipe provides a stream-like interface for uploading data to an Aparavi
+ * pipeline. It handles the low-level protocol details of opening, writing to,
+ * and closing data pipes on the server.
+ *
+ * Usage pattern:
+ * 1. Create pipe using client.pipe()
+ * 2. Call open() to establish the pipe
+ * 3. Call write() multiple times with data chunks
+ * 4. Call close() to finalize and get results
+ *
+ * @example
+ * ```typescript
+ * const pipe = await client.pipe(token, { filename: 'data.json' }, 'application/json');
+ * await pipe.open();
+ * await pipe.write(new TextEncoder().encode('{"data": "value"}'));
+ * const result = await pipe.close();
+ * ```
+ */
+class DataPipe {
+    /**
+     * Creates a new DataPipe instance.
+     *
+     * @param client - The AparaviClient instance managing this pipe
+     * @param token - Task token for the pipeline receiving the data
+     * @param objinfo - Metadata about the object being sent (e.g., filename, size)
+     * @param mimeType - MIME type of the data being sent (default: 'application/octet-stream')
+     * @param provider - Optional provider name for the data source
+     */
+    constructor(client, token, objinfo = {}, mimeType = 'application/octet-stream', provider) {
+        this._opened = false;
+        this._closed = false;
+        this._client = client;
+        this._token = token;
+        this._objinfo = objinfo;
+        this._mimeType = mimeType;
+        this._provider = provider;
+    }
+    /**
+     * Check if the pipe is currently open for writing.
+     *
+     * @returns true if the pipe has been opened and not yet closed
+     */
+    get isOpened() {
+        return this._opened;
+    }
+    /**
+     * Get the unique ID assigned to this pipe by the server.
+     *
+     * This ID is assigned when the pipe is opened and is used for subsequent
+     * write operations. It remains undefined until open() is called successfully.
+     *
+     * @returns The server-assigned pipe ID, or undefined if not yet opened
+     */
+    get pipeId() {
+        return this._pipeId;
+    }
+    /**
+     * Open the pipe for data transmission.
+     *
+     * Establishes a data pipe on the server for streaming data to the pipeline.
+     * Must be called before any write() operations. The server will assign a
+     * unique pipe ID that is used for subsequent operations.
+     *
+     * @returns This DataPipe instance (for method chaining)
+     * @throws Error if the pipe is already opened or if the pipeline is not running
+     */
+    async open() {
+        if (this._opened) {
+            throw new Error('Pipe already opened');
+        }
+        const request = this._client.buildRequest('apaext_process', {
+            arguments: {
+                subcommand: 'open',
+                object: this._objinfo,
+                mimeType: this._mimeType,
+                provider: this._provider,
+            },
+            token: this._token,
+        });
+        const response = await this._client.request(request);
+        if (this._client.didFail(response)) {
+            throw new Error(response.message || 'Your pipeline is not currently running.');
+        }
+        this._pipeId = response.body?.pipe_id;
+        this._opened = true;
+        return this;
+    }
+    /**
+     * Write data to the pipe.
+     *
+     * Sends a chunk of data through the pipe to the server pipeline. Can be called
+     * multiple times to stream large datasets. The pipe must be opened first.
+     *
+     * @param buffer - Data to write, must be a Uint8Array
+     * @throws Error if the pipe is not opened, buffer is invalid, or write fails
+     */
+    async write(buffer) {
+        if (!this._opened) {
+            throw new Error('Pipe not opened');
+        }
+        if (!(buffer instanceof Uint8Array)) {
+            throw new Error('Buffer must be Uint8Array');
+        }
+        const request = this._client.buildRequest('apaext_process', {
+            arguments: {
+                subcommand: 'write',
+                pipe_id: this._pipeId,
+                data: buffer,
+            },
+            token: this._token,
+        });
+        const response = await this._client.request(request);
+        if (this._client.didFail(response)) {
+            throw new Error(response.message || 'Failed to write to pipe');
+        }
+    }
+    /**
+     * Close the pipe and get the processing results.
+     *
+     * Finalizes the data stream and signals the server that no more data will be sent.
+     * The server processes any buffered data and returns the final result. After closing,
+     * the pipe cannot be reopened or written to again.
+     *
+     * @returns The processing result from the server, or undefined if already closed
+     * @throws Error if closing the pipe fails
+     */
+    async close() {
+        if (!this._opened || this._closed) {
+            return;
+        }
+        try {
+            const request = this._client.buildRequest('apaext_process', {
+                arguments: {
+                    subcommand: 'close',
+                    pipe_id: this._pipeId,
+                },
+                token: this._token,
+            });
+            const response = await this._client.request(request);
+            if (this._client.didFail(response)) {
+                throw new Error(response.message || 'Failed to close pipe');
+            }
+            return response.body;
+        }
+        finally {
+            this._closed = true;
+        }
+    }
+}
+exports.DataPipe = DataPipe;
+/**
+ * Main Aparavi client for connecting to Aparavi servers and services.
+ *
+ * This client provides a comprehensive API for interacting with Aparavi services,
+ * including connection management, pipeline execution, data operations, AI chat,
+ * event handling, and server connectivity testing.
+ *
+ * Key features:
+ * - Single shared WebSocket connection for all operations
+ * - Connection management (connect/disconnect) with optional persistence
+ * - Automatic reconnection when persist mode is enabled
+ * - Pipeline execution (use, terminate, getTaskStatus)
+ * - Data operations (send, sendFiles, pipe)
+ * - AI chat functionality (chat)
+ * - Event handling (setEvents, event callbacks)
+ * - Server connectivity testing (ping)
+ * - Full TypeScript type safety
+ */
+class AparaviClient extends DAPClient_1.DAPClient {
+    /**
+     * Creates a new AparaviClient instance.
+     *
+     * Configuration priority (highest to lowest):
+     * 1. Values passed in config parameter (auth, uri)
+     * 2. Values from env parameter (if provided)
+     * 3. Values from .env file (Node.js only)
+     * 4. Default values
+     *
+     * @param config - Configuration options for the client
+     * @param config.auth - API key for authentication (required)
+     * @param config.uri - Server URI (default: CONST_DEFAULT_SERVICE)
+     * @param config.env - Environment variables dictionary for configuration and substitution
+     * @param config.onEvent - Callback for server events
+     * @param config.onConnected - Callback when connection is established
+     * @param config.onDisconnected - Callback when connection is lost
+     * @param config.persist - Enable automatic reconnection
+     * @param config.reconnectDelay - Delay between reconnection attempts in ms
+     * @param config.module - Optional module name for client identification
+     *
+     * @throws Error if auth is not provided via config, env, or .env file
+     *
+     * @example
+     * ```typescript
+     * // Using explicit auth and URI
+     * const client = new AparaviClient({
+     *   auth: 'your-api-key',
+     *   uri: 'wss://your-server.com',
+     *   persist: true,
+     *   onEvent: (event) => console.log('Event:', event)
+     * });
+     *
+     * // Using custom env dictionary
+     * const client = new AparaviClient({
+     *   env: {
+     *     APARAVI_APIKEY: 'your-api-key',
+     *     APARAVI_URI: 'wss://your-server.com',
+     *     APARAVI_PROJECT_ID: 'my-project'
+     *   }
+     * });
+     * ```
+     */
+    constructor(config = {}) {
+        // Check if we're in Node.js or browser environment
+        const isBrowser = typeof window !== 'undefined';
+        // Build environment variables dictionary
+        // Priority: provided env > .env file
+        let clientEnv = {};
+        if (config.env) {
+            // Use provided env dictionary
+            clientEnv = { ...config.env };
+        }
+        else {
+            // Load from .env file only (Node.js only)
+            if (!isBrowser) {
+                try {
+                    const fs = require('fs');
+                    const path = require('path');
+                    const envPath = path.join(process.cwd(), '.env');
+                    if (fs.existsSync(envPath)) {
+                        const content = fs.readFileSync(envPath, 'utf-8');
+                        // Parse each line
+                        for (const line of content.split('\n')) {
+                            const trimmed = line.trim();
+                            // Skip comments and empty lines
+                            if (!trimmed || trimmed.startsWith('#')) {
+                                continue;
+                            }
+                            // Parse KEY=VALUE format
+                            const match = trimmed.match(/^([^=]+)=(.*)$/);
+                            if (match) {
+                                const key = match[1].trim();
+                                let value = match[2].trim();
+                                // Remove quotes if present
+                                if ((value.startsWith('"') && value.endsWith('"')) ||
+                                    (value.startsWith("'") && value.endsWith("'"))) {
+                                    value = value.slice(1, -1);
+                                }
+                                clientEnv[key] = value;
+                            }
+                        }
+                    }
+                }
+                catch {
+                    // File doesn't exist or can't be read - that's okay
+                }
+            }
+        }
+        const { auth = config.auth || clientEnv.APARAVI_APIKEY, uri = config.uri || clientEnv.APARAVI_URI || constants_1.CONST_DEFAULT_SERVICE, onEvent, onConnected, onDisconnected, persist, reconnectDelay, module, } = config;
+        if (!auth) {
+            throw new Error("Authentication key is required. Provide 'auth' parameter, 'env' parameter, or set 'APARAVI_APIKEY' in .env file.");
+        }
+        // Convert HTTP/HTTPS URI to WS/WSS for WebSocket connections
+        const wsUri = AparaviClient._convertToWebSocketUri(uri);
+        const fullUri = `${wsUri}/task/service`;
+        // Create unique client identifier
+        const clientName = module || `CLIENT-${clientId++}`;
+        // Set up WebSocket transport for server communication
+        const transport = new TransportWebSocket_1.TransportWebSocket(fullUri, auth);
+        // Initialize the DAPClient
+        super(clientName, transport, config);
+        this._dapAttempted = false;
+        this._nextChatId = 1;
+        // Persistence properties for automatic reconnection
+        this._persist = false;
+        this._reconnectDelay = 1000; // Default delay in milliseconds
+        this._manualDisconnect = false;
+        // Store connection details and environment
+        this._uri = fullUri;
+        this._apikey = auth;
+        this._env = clientEnv;
+        // Set up callbacks if provided
+        if (onEvent)
+            this._callerOnEvent = onEvent;
+        if (onConnected)
+            this._callerOnConnected = onConnected;
+        if (onDisconnected)
+            this._callerOnDisconnected = onDisconnected;
+        // Set up persistence options
+        this._persist = persist ?? false;
+        this._reconnectDelay = reconnectDelay ?? 1000;
+    }
+    /**
+     * Convert HTTP/HTTPS URI to WebSocket URI
+     */
+    static _convertToWebSocketUri(uri) {
+        try {
+            const url = new URL(uri);
+            const wsScheme = url.protocol === 'https:' ? 'wss:' : 'ws:';
+            return `${wsScheme}//${url.host}`;
+        }
+        catch {
+            return uri;
+        }
+    }
+    /**
+     * Clear any pending reconnection timeout
+     */
+    _clearReconnectTimeout() {
+        if (this._reconnectTimeout) {
+            clearTimeout(this._reconnectTimeout);
+            this._reconnectTimeout = undefined;
+        }
+    }
+    /**
+     * Schedule a reconnection attempt after the configured delay
+     */
+    _scheduleReconnect() {
+        this._clearReconnectTimeout();
+        this.debugMessage(`Scheduling reconnection in ${this._reconnectDelay}ms`);
+        this._reconnectTimeout = setTimeout(async () => {
+            if (this._persist && !this._manualDisconnect) {
+                this.debugMessage('Attempting to reconnect...');
+                try {
+                    await super.connect();
+                }
+                catch (error) {
+                    this.debugMessage(`Reconnection failed: ${error}`);
+                    // Will schedule another attempt via onDisconnected
+                }
+            }
+        }, this._reconnectDelay);
+    }
+    // ============================================================================
+    // CONNECTION METHODS
+    // ============================================================================
+    /**
+     * Check if the client is currently connected to the Aparavi server.
+     */
+    isConnected() {
+        return this._transport?.isConnected() || false;
+    }
+    /**
+     * Connect to the Aparavi server.
+     *
+     * Must be called before executing pipelines or other operations.
+     * In persist mode, enables automatic reconnection on disconnect.
+     */
+    async connect() {
+        this._manualDisconnect = false;
+        // If we are already connected, disconnect first
+        if (this.isConnected()) {
+            await this.disconnect();
+        }
+        // Call the DAP client function
+        await super.connect();
+    }
+    /**
+     * Disconnect from the Aparavi server and stop automatic reconnection.
+     *
+     * Should be called when finished with the client to clean up resources.
+     */
+    async disconnect() {
+        this._manualDisconnect = true;
+        this._clearReconnectTimeout();
+        // Call the DAP client function
+        await super.disconnect();
+    }
+    /**
+     * Send a request to the Aparavi server.
+     */
+    async request(request) {
+        // Delegate to parent class for actual request processing
+        return super.request(request);
+    }
+    // ============================================================================
+    // PING METHODS
+    // ============================================================================
+    /**
+     * Test connectivity to the Aparavi server.
+     *
+     * Sends a lightweight ping request to the server to verify it's responding
+     * and reachable. This is useful for connectivity testing, health checks,
+     * and measuring response times.
+     */
+    async ping(token) {
+        // Build ping request
+        const request = this.buildRequest('apaext_ping', { token });
+        // Send to server and wait for response
+        const response = await this.request(request);
+        // Check if ping failed
+        if (this.didFail(response)) {
+            const errorMsg = response.message || 'Ping failed';
+            throw new Error(`Ping failed: ${errorMsg}`);
+        }
+    }
+    // ============================================================================
+    // EXECUTION METHODS
+    // ============================================================================
+    /**
+     * Substitute environment variables in a string.
+     * Replaces ${APARAVI_*} patterns with values from client's env dictionary.
+     * If variable is not found, leaves it unchanged.
+     */
+    substituteEnvVars(value) {
+        // Match ${APARAVI_*} patterns
+        return value.replace(/\$\{(APARAVI_[^}]+)\}/g, (match, varName) => {
+            // Check if variable exists in client's env
+            if (varName in this._env) {
+                return String(this._env[varName]);
+            }
+            // If not found, leave as is
+            return match;
+        });
+    }
+    /**
+     * Recursively process an object/array to substitute environment variables.
+     * Only processes string values, leaving other types unchanged.
+     */
+    processEnvSubstitution(obj) {
+        if (typeof obj === 'string') {
+            // If it's a string, perform substitution
+            return this.substituteEnvVars(obj);
+        }
+        else if (Array.isArray(obj)) {
+            // If it's an array, process each element
+            return obj.map(item => this.processEnvSubstitution(item));
+        }
+        else if (obj !== null && typeof obj === 'object') {
+            // If it's an object, process each property
+            const result = {};
+            for (const [key, value] of Object.entries(obj)) {
+                result[key] = this.processEnvSubstitution(value);
+            }
+            return result;
+        }
+        // For other types (number, boolean, null), return as is
+        return obj;
+    }
+    /**
+     * Start an Aparavi pipeline for processing data.
+     *
+     * This method loads and executes a pipeline configuration. It automatically performs
+     * environment variable substitution on the pipeline config, replacing ${APARAVI_*}
+     * placeholders with values from the .env file.
+     *
+     * @param options - Pipeline execution options
+     * @param options.token - Custom token for the pipeline (auto-generated if not provided)
+     * @param options.filepath - Path to JSON file containing pipeline configuration
+     * @param options.pipeline - Pipeline configuration object (alternative to filepath)
+     * @param options.source - Override pipeline source
+     * @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
+     *
+     * @returns Promise resolving to an object containing the task token and other metadata
+     * @throws Error if neither pipeline nor filepath is provided
+     *
+     * @example
+     * ```typescript
+     * // Using pipeline file
+     * const result = await client.use({ filepath: './pipeline.json' });
+     *
+     * // Using pipeline object
+     * const result = await client.use({
+     *   pipeline: { components: [...], source: 'local', project_id: '123' }
+     * });
+     *
+     * // With environment variable substitution
+     * // Pipeline config: { "endpoint": "${APARAVI_URI}/api" }
+     * // Will be replaced with actual APARAVI_URI value from .env
+     * ```
+     */
+    async use(options = {}) {
+        const { token, filepath, pipeline, source, threads, useExisting, args } = options;
+        // Validate required parameters
+        if (!pipeline && !filepath) {
+            throw new Error('Pipeline configuration or file path is required and must be specified');
+        }
+        let pipelineConfig;
+        // Load pipeline configuration from file if needed
+        if (!pipeline && filepath) {
+            // Check if we're in Node.js environment
+            if (typeof window !== 'undefined') {
+                throw new Error('File loading not available in browser environment. Please provide pipeline object directly.');
+            }
+            // Load file in Node.js
+            const fs = require('fs');
+            const fileContent = fs.readFileSync(filepath, 'utf-8');
+            pipelineConfig = JSON.parse(fileContent);
+        }
+        else {
+            pipelineConfig = pipeline;
+        }
+        // Create a deep copy of the pipeline config to avoid modifying the original
+        let processedConfig = JSON.parse(JSON.stringify(pipelineConfig));
+        // Perform environment variable substitution on the pipeline configuration
+        processedConfig = this.processEnvSubstitution(processedConfig);
+        // Override source if specified (after substitution)
+        if (source !== undefined) {
+            processedConfig.pipeline.source = source;
+        }
+        // Build execution request with all parameters
+        const arguments_ = {
+            pipeline: processedConfig,
+            args: args || [],
+        };
+        // Add optional parameters if specified
+        if (token !== undefined) {
+            arguments_.token = token;
+        }
+        if (threads !== undefined) {
+            arguments_.threads = threads;
+        }
+        if (useExisting !== undefined) {
+            arguments_.useExisting = useExisting;
+        }
+        // Send execution request to server
+        const request = this.buildRequest('execute', { arguments: arguments_ });
+        const response = await this.request(request);
+        // Check for execution errors
+        if (this.didFail(response)) {
+            const errorMsg = response.message || 'Unknown execution error';
+            this.debugMessage(`Pipeline execution failed: ${errorMsg}`);
+            throw new Error(errorMsg);
+        }
+        // Extract and validate response
+        const responseBody = response.body || {};
+        const taskToken = responseBody.token;
+        if (!taskToken) {
+            throw new Error('Server did not return a task token in successful response');
+        }
+        this.debugMessage(`Pipeline execution started successfully, task token: ${taskToken}`);
+        // Type assertion to ensure token is present
+        return responseBody;
+    }
+    /**
+     * Terminate a running pipeline.
+     */
+    async terminate(token) {
+        // Send termination request
+        const request = this.buildRequest('terminate', { token });
+        const response = await this.request(request);
+        // Check for termination errors
+        if (this.didFail(response)) {
+            const errorMsg = response.message || 'Unknown termination error';
+            this.debugMessage(`Pipeline termination failed: ${errorMsg}`);
+            throw new Error(errorMsg);
+        }
+    }
+    /**
+     * Get the current status of a running pipeline.
+     */
+    async getTaskStatus(token) {
+        // Send status request
+        const request = this.buildRequest('apaext_get_task_status', { token });
+        const response = await this.request(request);
+        // Check for status retrieval errors
+        if (this.didFail(response)) {
+            const errorMsg = response.message || 'Unknown status retrieval error';
+            this.debugMessage(`Pipeline status retrieval failed: ${errorMsg}`);
+            throw new Error(errorMsg);
+        }
+        // Return status information
+        return response.body || {};
+    }
+    // ============================================================================
+    // DATA METHODS
+    // ============================================================================
+    /**
+     * Create a data pipe for streaming operations.
+     */
+    async pipe(token, objinfo = {}, mimeType, provider) {
+        return new DataPipe(this, token, objinfo, mimeType, provider);
+    }
+    /**
+     * Send data to a running pipeline.
+     */
+    async send(token, data, objinfo = {}, mimetype) {
+        // Convert string to bytes if needed
+        let buffer;
+        if (typeof data === 'string') {
+            buffer = new TextEncoder().encode(data);
+        }
+        else if (data instanceof Uint8Array) {
+            buffer = data;
+        }
+        else {
+            throw new Error('data must be either a string or Uint8Array');
+        }
+        // Create and use a temporary pipe for the data
+        const pipe = await this.pipe(token, objinfo, mimetype);
+        try {
+            await pipe.open();
+            await pipe.write(buffer);
+            return await pipe.close();
+        }
+        catch (error) {
+            // Clean up pipe on any error
+            if (pipe.isOpened) {
+                try {
+                    await pipe.close();
+                }
+                catch {
+                    // Ignore cleanup errors
+                }
+            }
+            throw error;
+        }
+    }
+    /**
+     * Upload multiple files to a pipeline with progress tracking and parallel execution.
+     *
+     * This method efficiently uploads files in parallel with configurable concurrency control.
+     * Each file is streamed through a data pipe, and progress events are emitted through the
+     * event system for all subscribers. The order of results matches the input file order.
+     *
+     * Progress events are sent through the event system as 'apaevt_status_upload' events
+     * (matching Python client behavior) rather than through a callback parameter.
+     *
+     * @param files - Array of file objects with optional metadata and MIME types
+     * @param token - Pipeline task token to receive the uploads
+     * @param maxConcurrent - Maximum number of concurrent uploads (default: 5)
+     *
+     * @returns Promise resolving to array of UPLOAD_RESULT objects in the same order as input
+     *
+     * @example
+     * ```typescript
+     * // Subscribe to upload events
+     * client.on('apaevt_status_upload', (event) => {
+     *   console.log(`${event.body.filepath}: ${event.body.bytes_sent}/${event.body.file_size}`);
+     * });
+     *
+     * // Upload files
+     * const results = await client.sendFiles(
+     *   [
+     *     { file: fileObject1 },
+     *     { file: fileObject2, mimetype: 'application/json' },
+     *     { file: fileObject3, objinfo: { custom: 'metadata' } }
+     *   ],
+     *   'task-token',
+     *   10  // Upload max 10 files concurrently
+     * );
+     * ```
+     */
+    async sendFiles(files, token, maxConcurrent = 5) {
+        const results = new Array(files.length);
+        /**
+         * Helper function to send upload events through the event system.
+         * This matches the Python implementation where events are emitted
+         * through the event system rather than callbacks.
+         */
+        const sendUploadEvent = (body) => {
+            const eventMessage = {
+                event: 'apaevt_status_upload',
+                body: body,
+                seq: 0,
+                type: 'event'
+            };
+            // Emit event through your event system
+            // Replace this with your actual event emission method
+            this.onEvent(eventMessage);
+        };
+        /**
+         * Upload a single file
+         */
+        const uploadFile = async (fileData, index) => {
+            const { file, objinfo = {}, mimetype } = fileData;
+            const startTime = Date.now();
+            let bytesUploaded = 0;
+            let pipe = null;
+            let error;
+            let result;
+            // Prepare objinfo with file metadata
+            const fullObjinfo = {
+                name: file.name,
+                size: file.size,
+                ...objinfo,
+            };
+            const finalMimetype = mimetype || file.type || 'application/octet-stream';
+            try {
+                const fileSize = file.size;
+                // Create and open pipe
+                pipe = await this.pipe(token, fullObjinfo, finalMimetype);
+                // Open the pipe
+                await pipe.open();
+                // Send upload start event (action: 'open')
+                sendUploadEvent({
+                    action: 'open',
+                    filepath: file.name,
+                    bytes_sent: 0,
+                    file_size: fileSize,
+                    upload_time: 0,
+                });
+                // Upload file in chunks
+                const reader = file.stream().getReader();
+                try {
+                    while (true) {
+                        const { done, value } = await reader.read();
+                        if (done)
+                            break;
+                        // Write chunk
+                        await pipe.write(value);
+                        bytesUploaded += value.length;
+                        // Send progress event for every chunk (action: 'write')
+                        sendUploadEvent({
+                            action: 'write',
+                            filepath: file.name,
+                            bytes_sent: bytesUploaded,
+                            file_size: fileSize,
+                            upload_time: (Date.now() - startTime) / 1000,
+                        });
+                    }
+                }
+                finally {
+                    reader.releaseLock();
+                }
+                // Send close event (action: 'close')
+                sendUploadEvent({
+                    action: 'close',
+                    filepath: file.name,
+                    bytes_sent: bytesUploaded,
+                    file_size: fileSize,
+                    upload_time: (Date.now() - startTime) / 1000,
+                });
+                // Close pipe and get result
+                result = await pipe.close();
+            }
+            catch (err) {
+                error = err instanceof Error ? err.message : String(err);
+            }
+            // Create final result
+            const uploadTime = (Date.now() - startTime) / 1000;
+            const finalResult = {
+                action: error ? 'error' : 'complete',
+                filepath: file.name,
+                bytes_sent: bytesUploaded,
+                file_size: file.size,
+                upload_time: uploadTime,
+                result,
+                error,
+            };
+            // Send final result event (action: 'complete' or 'error')
+            sendUploadEvent(finalResult);
+            // Store result at the correct index
+            results[index] = finalResult;
+        };
+        // Execute uploads with concurrency limit
+        const executing = new Set();
+        for (let i = 0; i < files.length; i++) {
+            const uploadPromise = uploadFile(files[i], i).then(() => {
+                // Remove this promise from the executing set when done
+                executing.delete(uploadPromise);
+            }).catch(() => {
+                // Remove this promise from the executing set even on error
+                executing.delete(uploadPromise);
+            });
+            executing.add(uploadPromise);
+            // If we've reached max concurrency, wait for one to complete
+            if (executing.size >= maxConcurrent) {
+                await Promise.race(executing);
+            }
+        }
+        // Wait for all remaining uploads to complete
+        await Promise.all(Array.from(executing));
+        return results;
+    }
+    // ============================================================================
+    // CHAT METHODS
+    // ============================================================================
+    /**
+     * Ask a question to Aparavi's AI and get an intelligent response.
+     */
+    async chat(options) {
+        const { token, question } = options;
+        try {
+            // Validate that we have a question to ask
+            if (!question) {
+                throw new Error('Question cannot be empty');
+            }
+            // Create unique identifier for this chat operation
+            const objinfo = { name: `Question ${this._nextChatId}` };
+            this._nextChatId += 1;
+            // Create pipe instance
+            const pipe = new DataPipe(this, token, objinfo, 'application/aparavi-question', 'chat');
+            try {
+                // Open the communication channel to the AI
+                await pipe.open();
+                // Send the question as JSON data to the AI system
+                const questionJson = JSON.stringify(question.toDict());
+                const questionBytes = new TextEncoder().encode(questionJson);
+                await pipe.write(questionBytes);
+                // Close the pipe and get the AI's response
+                const result = await pipe.close();
+                // Check it
+                if (!result) {
+                    throw new Error('No response received from AI');
+                }
+                // Return success response in standard format
+                return result;
+            }
+            finally {
+                // Ensure the pipe is properly closed even if errors occur
+                if (pipe.isOpened) {
+                    try {
+                        await pipe.close();
+                    }
+                    catch {
+                        // Ignore errors during cleanup
+                    }
+                }
+            }
+        }
+        catch (error) {
+            // Return error response in standard format
+            throw new Error(error instanceof Error ? error.message : String(error));
+        }
+    }
+    // ============================================================================
+    // EVENT METHODS
+    // ============================================================================
+    /**
+     * Send events to debugging interface if available (for development).
+     */
+    _sendVSCodeEvent(eventType, body) {
+        // Set up debugging integration on first use
+        if (!this._dapAttempted) {
+            this._dapAttempted = true;
+            try {
+                // In browser environment, check for debugging tools
+                if (typeof window !== 'undefined' && window.__APARAVI_DEBUG__) {
+                    this._dapSend = window.__APARAVI_DEBUG__.sendEvent;
+                }
+            }
+            catch {
+                // Not in debugging environment - no problem
+            }
+        }
+        // Send event to debugger if available
+        if (this._dapSend) {
+            const customEvent = {
+                type: 'event',
+                event: eventType,
+                body: body,
+            };
+            this._dapSend(customEvent);
+        }
+    }
+    /**
+     * Handle incoming events from the Aparavi server.
+     */
+    async onEvent(message) {
+        // Extract event information
+        const eventType = message.event || 'unknown';
+        const eventBody = message.body || {};
+        const seqNum = message.seq || 0;
+        // Forward to debugging interface if available
+        this._sendVSCodeEvent(eventType, eventBody);
+        // Call user-provided event handler if available
+        if (this._callerOnEvent) {
+            try {
+                await this._callerOnEvent(message);
+            }
+            catch (error) {
+                // Log errors but don't let user code break the connection
+                this.debugMessage(`Error in user onEvent handler for ${eventType} (seq ${seqNum}): ${error}`);
+            }
+        }
+    }
+    /**
+     * Handle connected events from the Aparavi server.
+     */
+    async onConnected(connectionInfo) {
+        this._manualDisconnect = false;
+        this._clearReconnectTimeout();
+        // Call user-provided event handler if available
+        if (this._callerOnConnected) {
+            try {
+                await this._callerOnConnected(connectionInfo);
+            }
+            catch (error) {
+                // Log errors but don't let user code break the connection
+                this.debugMessage(`Error in user onConnected handler for ${connectionInfo}: ${error}`);
+            }
+        }
+    }
+    /**
+     * Handle disconnected events from the Aparavi server.
+     */
+    async onDisconnected(reason, hasError) {
+        // Call user-provided event handler if available
+        if (this._callerOnDisconnected) {
+            try {
+                await this._callerOnDisconnected(reason, hasError);
+            }
+            catch (error) {
+                // Log errors but don't let user code break the connection
+                this.debugMessage(`Error in user onDisconnected handler for ${reason}: ${error}`);
+            }
+        }
+        // Schedule reconnection if persist is enabled and not a manual disconnect
+        if (this._persist && !this._manualDisconnect) {
+            this._scheduleReconnect();
+        }
+    }
+    /**
+     * Subscribe to specific types of events from the server.
+     */
+    async setEvents(token, eventTypes) {
+        // Build event subscription request
+        const request = this.buildRequest('apaext_monitor', {
+            arguments: { types: eventTypes },
+            token,
+        });
+        // Send to server
+        const response = await this.request(request);
+        // Check for errors
+        if (this.didFail(response)) {
+            const errorMsg = response.message || 'Event subscription failed';
+            throw new Error(errorMsg);
+        }
+    }
+    // ============================================================================
+    // CONTEXT MANAGER SUPPORT - Python-style async context manager
+    // ============================================================================
+    /**
+     * Async disposal support for 'await using' pattern.
+     * Equivalent to Python's __aexit__
+     */
+    async [Symbol.asyncDispose]() {
+        await this.disconnect();
+    }
+    /**
+     * Static factory method for automatic connection management.
+     * Equivalent to Python's async with pattern
+     */
+    static async withConnection(config, callback) {
+        const client = new AparaviClient(config);
+        try {
+            await client.connect();
+            return await callback(client);
+        }
+        finally {
+            await client.disconnect();
+        }
+    }
+    // ============================================================================
+    // ADDITIONAL CONVENIENCE METHODS
+    // ============================================================================
+    /**
+     * Get connection information (TypeScript-specific convenience)
+     */
+    getConnectionInfo() {
+        return {
+            connected: this.isConnected(),
+            transport: 'WebSocket',
+            uri: this._uri,
+        };
+    }
+    /**
+     * Get API key (for debugging/validation)
+     */
+    getApiKey() {
+        return this._apikey;
+    }
+}
+exports.AparaviClient = AparaviClient;
+exports.default = AparaviClient;
+//# sourceMappingURL=client.js.map