@flowcore/sdk 1.24.3 → 1.25.0

package/esm/common/command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../src/common/command.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAA;AAE3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAG1D;;GAEG;AACH,8BAAsB,OAAO,CAAC,KAAK,EAAE,MAAM;IACzC;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAO;IAEjD;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAE9C;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,CAAC,QAAQ,GAAG,QAAQ,CAAC,EAAE,CAAuB;IAE/E;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;gBAEnB,KAAK,EAAE,KAAK;IAOxB;;OAEG;cACa,mBAAmB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA2CnF;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,UAAU,IAAI,MAAM;IAEvC;;OAEG;IACH,SAAS,CAAC,SAAS,IAAI,MAAM;IAI7B;;OAEG;IACH,SAAS,CAAC,OAAO,IAAI,MAAM;IAI3B;;OAEG;IACH,SAAS,CAAC,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,SAAS;IAOzE;;OAEG;IACH,SAAS,CAAC,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAQ9C;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM;IAE3D;;OAEG;IACH,SAAS,CAAC,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAIrD;;OAEG;IACU,UAAU,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;QACzE,YAAY,EAAE,CAAC,QAAQ,GAAG,QAAQ,CAAC,EAAE,CAAA;QACrC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,SAAS,CAAA;QACnE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC/B,OAAO,EAAE,MAAM,CAAA;QACf,IAAI,EAAE,MAAM,CAAA;QACZ,MAAM,EAAE,MAAM,CAAA;QACd,aAAa,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;QAC9D,eAAe,EAAE,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;QAC9E,iBAAiB,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAA;QAC/C,cAAc,EAAE,OAAO,CAAA;QACvB,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;KAC7D,CAAC;IAeF;;OAEG;cAEa,eAAe,CAAC,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAG5F"}
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../src/common/command.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAA;AAE3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAG1D;;GAEG;AACH,8BAAsB,OAAO,CAAC,KAAK,EAAE,MAAM;IACzC;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAO;IAEjD;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAE9C;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,CAAC,QAAQ,GAAG,QAAQ,CAAC,EAAE,CAAuB;IAE/E;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;gBAEnB,KAAK,EAAE,KAAK;IAOxB;;OAEG;cACa,mBAAmB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA0CnF;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,UAAU,IAAI,MAAM;IAEvC;;OAEG;IACH,SAAS,CAAC,SAAS,IAAI,MAAM;IAI7B;;OAEG;IACH,SAAS,CAAC,OAAO,IAAI,MAAM;IAI3B;;OAEG;IACH,SAAS,CAAC,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,SAAS;IAOzE;;OAEG;IACH,SAAS,CAAC,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAQ9C;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM;IAE3D;;OAEG;IACH,SAAS,CAAC,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAIrD;;OAEG;IACU,UAAU,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;QACzE,YAAY,EAAE,CAAC,QAAQ,GAAG,QAAQ,CAAC,EAAE,CAAA;QACrC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,SAAS,CAAA;QACnE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC/B,OAAO,EAAE,MAAM,CAAA;QACf,IAAI,EAAE,MAAM,CAAA;QACZ,MAAM,EAAE,MAAM,CAAA;QACd,aAAa,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;QAC9D,eAAe,EAAE,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;QAC9E,iBAAiB,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAA;QAC/C,cAAc,EAAE,OAAO,CAAA;QACvB,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;KAC7D,CAAC;IAeF;;OAEG;cAEa,eAAe,CAAC,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAG5F"}

package/esm/common/command.js

@@ -1,4 +1,3 @@
-import { TenantFetchCommand } from "../commands/tenant/tenant.fetch.js";
 import { ClientError } from "../exceptions/client-error.js";
 import { CommandError } from "../exceptions/command-error.js";
 import { tenantCache } from "./tenant.cache.js";
@@ -55,22 +54,22 @@ export class Command {
         if (!this.dedicatedSubdomain) {
             return null;
         }
-        console.log("getDedicatedBaseUrl", this.dedicatedSubdomain);
         const inputTenant = typeof this.input === "object" && this.input !== null && "tenant" in this.input &&
             typeof this.input.tenant === "string" && this.input.tenant;
         if (!inputTenant) {
             return null;
         }
-        console.log("getDedicatedBaseUrl", inputTenant);
         let tenant = tenantCache.get(inputTenant);
         if (!tenant) {
+            // Dynamically import TenantFetchCommand only when needed
+            const { TenantFetchCommand } = await import("../commands/tenant/tenant.fetch.js");
             tenant = await client.execute(new TenantFetchCommand({ tenant: inputTenant }))
                 .catch((error) => {
                 if (error instanceof ClientError && error.status === 403) {
                     return {
                         isDedicated: false,
                         dedicated: null,
-                    };
+                    }; // Cast needed as we are not returning the full Tenant shape
                 }
                 throw error;
             });

package/esm/common/websocket-client.d.ts

@@ -0,0 +1,109 @@
+import { Buffer } from "node:buffer";
+import { type Logger } from "../utils/logger.js";
+import type { ClientOptions } from "./flowcore-client.js";
+import type { ActiveStreamInterface, WebSocketCommand } from "./websocket-command.js";
+/**
+ * Interface for OIDC authentication client (reused from NotificationClient context)
+ */
+export type OidcClient = {
+    getToken: () => Promise<{
+        accessToken: string;
+    }>;
+};
+/**
+ * Configuration options for the WebSocketClient
+ */
+export type WebSocketClientOptions = {
+    /** Interval between reconnect attempts (ms). Defaults to 1000. */
+    reconnectInterval?: number;
+    /** Maximum number of reconnect attempts. Defaults to undefined (infinite). */
+    maxReconnects?: number;
+    /** Optional logger instance. */
+    logger?: Logger;
+};
+interface MinimalWebSocket {
+    readyState: number;
+    onopen: (() => void) | null;
+    onmessage: ((event: {
+        data: string | ArrayBuffer | Buffer;
+    }) => void) | null;
+    onclose: ((event: {
+        code: number;
+        reason: string;
+        wasClean: boolean;
+    }) => void) | null;
+    onerror: ((event: Event) => void) | null;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+}
+type WebSocketFactory = (url: string) => MinimalWebSocket;
+/**
+ * Generic client for managing a single, persistent WebSocket connection based on a command.
+ * Handles connection lifecycle, authentication, reconnection, and message sending/receiving.
+ */
+export declare class WebSocketClient {
+    private readonly authOptions;
+    private overrideBaseUrl;
+    private webSocket;
+    private options;
+    private logger;
+    private reconnectInterval;
+    private reconnectAttempts;
+    private _isOpen;
+    private _isConnecting;
+    private webSocketFactory;
+    private internalSubject;
+    private currentCommand;
+    private currentConfig;
+    /**
+     * Creates a new WebSocketClient instance.
+     * @param authOptions - Authentication options (Bearer token via OIDC client or API Key).
+     * @param options - Configuration options for the client.
+     * @param webSocketFactory - Optional WebSocket factory for testing.
+     */
+    constructor(authOptions: ClientOptions, options?: WebSocketClientOptions, webSocketFactory?: WebSocketFactory);
+    /**
+     * Override the base URL provided by commands.
+     * @param baseUrl - The new base URL to use (e.g., "wss://staging-server.api.flowcore.io").
+     */
+    setBaseUrl(baseUrl: string): void;
+    /**
+     * Returns true if the WebSocket connection is currently open.
+     */
+    get isOpen(): boolean;
+    /**
+     * Returns true if the client is currently attempting to establish a WebSocket connection.
+     */
+    get isConnecting(): boolean;
+    /**
+     * Establishes WebSocket connection based on the provided command.
+     * Disconnects any existing connection before starting the new one.
+     * @param command - The command defining the stream connection details.
+     * @returns An interface to interact with the active stream.
+     */
+    connect<Config, SendPayload>(command: WebSocketCommand<Config, SendPayload>): Promise<ActiveStreamInterface<SendPayload>>;
+    /**
+     * Sets up the WebSocket event handlers (onopen, onmessage, onclose, onerror).
+     */
+    private setupEventHandlers;
+    /**
+     * Attempts to reconnect to the WebSocket server using exponential backoff.
+     * Requires `currentConfig` to be set.
+     */
+    private attemptReconnect;
+    /**
+     * Sends a message to the currently connected WebSocket.
+     * @param message - The message object to send (e.g., { content: "user input" }).
+     */
+    private sendMessage;
+    /**
+     * Closes the WebSocket connection gracefully.
+     */
+    disconnect(): void;
+    /**
+     * Implements the Disposable interface for clean resource management.
+     */
+    [Symbol.dispose](): void;
+}
+export {};
+//# sourceMappingURL=websocket-client.d.ts.map

package/esm/common/websocket-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket-client.d.ts","sourceRoot":"","sources":["../../src/common/websocket-client.ts"],"names":[],"mappings":"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"}

package/esm/common/websocket-client.js

@@ -0,0 +1,391 @@
+import * as dntShim from "../_dnt.shims.js";
+import { Buffer } from "node:buffer";
+import { Subject } from "rxjs";
+import { defaultLogger } from "../utils/logger.js";
+// Maximum reconnection interval in milliseconds
+const MAX_RECONNECT_INTERVAL = 30_000;
+/**
+ * Generic client for managing a single, persistent WebSocket connection based on a command.
+ * Handles connection lifecycle, authentication, reconnection, and message sending/receiving.
+ */
+export class WebSocketClient {
+    /**
+     * Creates a new WebSocketClient instance.
+     * @param authOptions - Authentication options (Bearer token via OIDC client or API Key).
+     * @param options - Configuration options for the client.
+     * @param webSocketFactory - Optional WebSocket factory for testing.
+     */
+    constructor(authOptions, options, webSocketFactory) {
+        Object.defineProperty(this, "authOptions", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: authOptions
+        });
+        Object.defineProperty(this, "overrideBaseUrl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // Field to store the override URL
+        Object.defineProperty(this, "webSocket", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "options", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "logger", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "reconnectInterval", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "reconnectAttempts", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "_isOpen", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "_isConnecting", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "webSocketFactory", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        // Internal subject to push received data
+        Object.defineProperty(this, "internalSubject", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Subject()
+        });
+        // Store the current command and config for reconnects and sending
+        Object.defineProperty(this, "currentCommand", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "currentConfig", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        this.options = { reconnectInterval: 1000, ...options };
+        this.logger = options?.logger ?? defaultLogger;
+        this.reconnectInterval = this.options.reconnectInterval;
+        this.webSocketFactory = webSocketFactory ?? ((url) => new dntShim.WebSocket(url));
+        this.overrideBaseUrl = undefined; // Initialize override URL
+        if ("getBearerToken" in authOptions === false && ("apiKey" in authOptions === false)) {
+            throw new Error("Invalid authOptions: Must provide either getBearerToken or apiKey/apiKeyId");
+        }
+    }
+    /**
+     * Override the base URL provided by commands.
+     * @param baseUrl - The new base URL to use (e.g., "wss://staging-server.api.flowcore.io").
+     */
+    setBaseUrl(baseUrl) {
+        this.logger.info(`WebSocket base URL overridden to: ${baseUrl}`);
+        this.overrideBaseUrl = baseUrl;
+    }
+    /**
+     * Returns true if the WebSocket connection is currently open.
+     */
+    get isOpen() {
+        return this._isOpen;
+    }
+    /**
+     * Returns true if the client is currently attempting to establish a WebSocket connection.
+     */
+    get isConnecting() {
+        return this._isConnecting;
+    }
+    /**
+     * Establishes WebSocket connection based on the provided command.
+     * Disconnects any existing connection before starting the new one.
+     * @param command - The command defining the stream connection details.
+     * @returns An interface to interact with the active stream.
+     */
+    // Using generic types for the command
+    async connect(command) {
+        if (this._isConnecting || this._isOpen) {
+            this.logger.info("Disconnecting existing stream before starting new one.");
+            this.disconnect(); // Ensure clean state
+            // Add a small delay to allow disconnect process to settle if needed
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+        this.currentCommand = command; // Store command (cast needed)
+        const config = command.getConfig();
+        this.currentConfig = config; // Store config
+        this._isConnecting = true;
+        // Use override URL if set, otherwise use command's base URL
+        const baseUrl = this.overrideBaseUrl ?? command.getWebSocketBaseUrl();
+        const pathSegment = command.getWebSocketPathSegment(config); // Get path segment from command
+        this.logger.info(`Attempting to connect stream: ${baseUrl}${pathSegment}`);
+        try {
+            const urlParams = new URLSearchParams();
+            if ("getBearerToken" in this.authOptions && this.authOptions.getBearerToken) {
+                const token = await this.authOptions.getBearerToken();
+                if (!token)
+                    throw new Error("Failed to get bearer token");
+                urlParams.set("token", token);
+            }
+            else if ("apiKey" in this.authOptions && this.authOptions.apiKey && this.authOptions.apiKeyId) {
+                urlParams.set("api_key", this.authOptions.apiKey);
+                urlParams.set("api_key_id", this.authOptions.apiKeyId);
+            }
+            else {
+                throw new Error("Invalid authentication configuration.");
+            }
+            const streamUrl = `${baseUrl}${pathSegment}?${urlParams.toString()}`; // Construct URL from command parts
+            this.logger.debug(`Connecting to WebSocket URL: ${streamUrl}`);
+            this.webSocket = this.webSocketFactory(streamUrl);
+            this.setupEventHandlers(); // Sets up handlers that push to internalSubject
+            // Return the active stream interface
+            return {
+                output$: this.internalSubject.asObservable(),
+                send: (payload) => this.sendMessage(payload),
+                disconnect: () => this.disconnect(),
+            };
+        }
+        catch (error) {
+            this.logger.error(`Failed to initiate connection: ${error}`);
+            this._isConnecting = false;
+            this.currentCommand = null; // Clear command/config on failure
+            this.currentConfig = null;
+            // Rethrow or handle differently? For now, rethrow.
+            throw error; // Make connect promise reject on failure
+        }
+    }
+    /**
+     * Sets up the WebSocket event handlers (onopen, onmessage, onclose, onerror).
+     */
+    setupEventHandlers() {
+        this.webSocket.onopen = () => {
+            this._isOpen = true;
+            this._isConnecting = false;
+            // Use potentially overridden base URL in logging
+            const baseUrl = this.overrideBaseUrl ?? this.currentCommand?.getWebSocketBaseUrl();
+            const pathSegment = this.currentCommand?.getWebSocketPathSegment(this.currentConfig);
+            this.logger.info(`WebSocket connection opened: ${baseUrl}${pathSegment}`);
+            this.reconnectInterval = this.options.reconnectInterval;
+            this.reconnectAttempts = 0;
+        };
+        this.webSocket.onmessage = (event) => {
+            try {
+                let parsedData;
+                // Handle various data types from WebSocket
+                if (event.data instanceof ArrayBuffer) {
+                    parsedData = new TextDecoder().decode(event.data);
+                }
+                else if (Buffer.isBuffer(event.data)) {
+                    parsedData = event.data.toString();
+                }
+                else {
+                    parsedData = event.data;
+                }
+                const chunk = JSON.parse(parsedData); // Assume valid JSON structure
+                // Basic validation - check if it has a 'type' property
+                if (typeof chunk !== "object" || chunk === null || typeof chunk.type !== "string") {
+                    this.logger.warn(`Received invalid chunk format: ${parsedData}`);
+                    return; // Ignore invalid chunks
+                }
+                this.logger.debug(`Received chunk: ${chunk.type}`); // Log chunk type
+                this.internalSubject.next(chunk); // Push to internal subject
+            }
+            catch (error) {
+                this.logger.error(`Error processing received message: ${error}`);
+                // Optionally emit an error on the subject?
+                // this.internalSubject.error(new Error(`Failed to parse message: ${error.message}`));
+            }
+        };
+        this.webSocket.onclose = (event) => {
+            const wasOpen = this._isOpen;
+            this._isOpen = false;
+            this._isConnecting = false;
+            // Use potentially overridden base URL in logging
+            const baseUrl = this.overrideBaseUrl ?? this.currentCommand?.getWebSocketBaseUrl();
+            const pathSegment = this.currentCommand?.getWebSocketPathSegment(this.currentConfig);
+            this.logger.info(`WebSocket connection closed: ${baseUrl}${pathSegment} Code [${event.code}], Reason: ${event.reason || "No reason given"}. Was open: ${wasOpen}`);
+            if (wasOpen && event.code !== 1000 && this.currentCommand) { // Only reconnect if command is still set
+                this.attemptReconnect();
+            }
+            else {
+                this.logger.info(`Completing internal subject due to close event.`);
+                this.internalSubject.complete(); // Complete subject on final close
+                this.currentCommand = null; // Clear state
+                this.currentConfig = null;
+            }
+        };
+        this.webSocket.onerror = () => {
+            // Use potentially overridden base URL in logging
+            const baseUrl = this.overrideBaseUrl ?? this.currentCommand?.getWebSocketBaseUrl();
+            const pathSegment = this.currentCommand?.getWebSocketPathSegment(this.currentConfig);
+            this.logger.error(`WebSocket encountered an error for stream: ${baseUrl}${pathSegment}.`);
+            if (this.webSocket.readyState !== dntShim.WebSocket.CLOSED &&
+                this.webSocket.readyState !== dntShim.WebSocket.CLOSING) {
+                this.webSocket.close(1011, "WebSocket error");
+            }
+            // Error event usually followed by onclose, which handles completion/reconnect
+            // Emit error on subject *before* close handling potentially completes it
+            this.internalSubject.error(new Error("WebSocket encountered an error"));
+        };
+    }
+    /**
+     * Attempts to reconnect to the WebSocket server using exponential backoff.
+     * Requires `currentConfig` to be set.
+     */
+    attemptReconnect() {
+        if (!this.currentCommand || !this.currentConfig) {
+            this.logger.error("Cannot reconnect without current command/config.");
+            if (!this.internalSubject.closed)
+                this.internalSubject.complete();
+            return;
+        }
+        if (this._isConnecting) {
+            this.logger.debug("Reconnect attempt already in progress.");
+            return;
+        }
+        // Use potentially overridden base URL
+        const baseUrl = this.overrideBaseUrl ?? this.currentCommand.getWebSocketBaseUrl();
+        const pathSegment = this.currentCommand.getWebSocketPathSegment(this.currentConfig);
+        if (this.options.maxReconnects && this.reconnectAttempts >= this.options.maxReconnects) {
+            this.logger.error(`Max reconnect attempts (${this.reconnectAttempts}/${this.options.maxReconnects}) reached. Giving up: ${baseUrl}${pathSegment}`);
+            if (!this.internalSubject.closed)
+                this.internalSubject.complete();
+            this.currentCommand = null;
+            this.currentConfig = null;
+            return;
+        }
+        this.reconnectAttempts++;
+        this._isConnecting = true;
+        this.logger.info(`Attempting reconnection ${this.reconnectAttempts}${this.options.maxReconnects ? `/${this.options.maxReconnects}` : ""}
+         for ${baseUrl}${pathSegment} in ${this.reconnectInterval} ms...`);
+        setTimeout(async () => {
+            // Check if disconnect was called while waiting
+            if (!this.currentCommand || !this.currentConfig) {
+                this.logger.info("Reconnect cancelled as disconnect was called.");
+                this._isConnecting = false; // Ensure flag is reset
+                if (!this.internalSubject.closed)
+                    this.internalSubject.complete();
+                return;
+            }
+            // Directly attempt to establish connection *without* calling this.connect()
+            try {
+                const urlParams = new URLSearchParams();
+                // --- Reuse auth logic from connect() ---
+                if ("getBearerToken" in this.authOptions && this.authOptions.getBearerToken) {
+                    const token = await this.authOptions.getBearerToken();
+                    if (!token)
+                        throw new Error("Reconnect failed: Could not get bearer token");
+                    urlParams.set("token", token);
+                }
+                else if ("apiKey" in this.authOptions && this.authOptions.apiKey && this.authOptions.apiKeyId) {
+                    urlParams.set("api_key", this.authOptions.apiKey);
+                    urlParams.set("api_key_id", this.authOptions.apiKeyId);
+                }
+                else {
+                    throw new Error("Reconnect failed: Invalid authentication configuration.");
+                }
+                // --- End auth logic ---
+                // Use potentially overridden base URL for reconnect URL
+                const streamUrl = `${baseUrl}${pathSegment}?${urlParams.toString()}`;
+                this.logger.debug(`Reconnecting to WebSocket URL: ${streamUrl}`);
+                this.webSocket = this.webSocketFactory(streamUrl);
+                // Connecting flag will be reset in onopen/onerror/onclose
+                this.setupEventHandlers();
+            }
+            catch (error) {
+                this.logger.error(`Reconnect attempt connection failed: ${error}`);
+                this._isConnecting = false; // Reset connection flag on immediate error
+                // Error during reconnect setup, trigger another attempt after backoff
+                // We might get stuck here if auth always fails, consider adding specific error handling
+                this.reconnectInterval = Math.min(MAX_RECONNECT_INTERVAL, this.reconnectInterval * 2); // Apply backoff before retrying
+                this.attemptReconnect();
+            }
+        }, this.reconnectInterval);
+        // Apply backoff interval for the *next* potential reconnect attempt
+        this.reconnectInterval = Math.min(MAX_RECONNECT_INTERVAL, this.reconnectInterval * 2);
+    }
+    /**
+     * Sends a message to the currently connected WebSocket.
+     * @param message - The message object to send (e.g., { content: "user input" }).
+     */
+    sendMessage(payload) {
+        const openState = 1; // WebSocket.OPEN is typically 1
+        if (!this._isOpen || this.webSocket.readyState !== openState || !this.currentCommand) {
+            this.logger.warn("Cannot send message: WebSocket is not open or command not set.");
+            return false;
+        }
+        try {
+            // Use command's serializer or default to JSON.stringify
+            const serializer = this.currentCommand.serializeSendPayload ?? JSON.stringify;
+            const dataToSend = serializer(payload);
+            this.webSocket.send(dataToSend);
+            this.logger.debug(`Sent message: ${dataToSend}`);
+            return true;
+        }
+        catch (error) {
+            this.logger.error(`Failed to send message: ${error}`);
+            return false;
+        }
+    }
+    /**
+     * Closes the WebSocket connection gracefully.
+     */
+    disconnect() {
+        this.logger.info("Disconnect called by user.");
+        const commandToClear = this.currentCommand; // Store ref before clearing
+        this.currentCommand = null; // Prevent reconnects
+        this.currentConfig = null;
+        if (this.webSocket) {
+            if (this._isOpen || this._isConnecting) {
+                this.webSocket.close(1000, "Disconnected by user");
+            }
+            else {
+                this.logger.debug("WebSocket already closed or closing.");
+            }
+        }
+        else {
+            this.logger.debug("No WebSocket instance to disconnect.");
+        }
+        this._isOpen = false;
+        this._isConnecting = false;
+        // Complete the subject if it hasn't been completed by onclose
+        if (commandToClear && !this.internalSubject.closed) {
+            this.logger.info("Completing internal subject due to disconnect call.");
+            this.internalSubject.complete();
+        }
+    }
+    /**
+     * Implements the Disposable interface for clean resource management.
+     */
+    [Symbol.dispose]() {
+        this.disconnect();
+    }
+}

package/esm/common/websocket-command.d.ts

@@ -0,0 +1,54 @@
+import type { Observable } from "rxjs";
+import type { StreamChunk } from "../contracts/ai-agent-coordinator-stream.js";
+/**
+ * Interface for a command that configures a WebSocket stream connection.
+ * @template Config - The type of the configuration data needed to initiate the stream.
+ * @template SendPayload - The type of data that can be sent *to* the stream after connection.
+ */
+export interface WebSocketCommand<Config, SendPayload> {
+    /**
+     * Gets the configuration data needed to establish the connection.
+     */
+    getConfig(): Config;
+    /**
+     * Gets the base WebSocket URL (e.g., wss://server.api.flowcore.io).
+     * @returns The base WebSocket URL string.
+     */
+    getWebSocketBaseUrl(): string;
+    /**
+     * Gets the specific path segment for the WebSocket URL based on the config
+     * (e.g., /api/v1/stream/entity/{id}).
+     * @param config - The configuration object.
+     * @returns The path segment string.
+     */
+    getWebSocketPathSegment(config: Config): string;
+    /**
+     * Serializes the payload to be sent over the WebSocket.
+     * Default implementation might be JSON.stringify.
+     * @param payload - The payload object to send.
+     * @returns The serialized string representation.
+     */
+    serializeSendPayload?(payload: SendPayload): string;
+}
+/**
+ * Interface representing an active WebSocket stream connection.
+ * @template SendPayload - The type of data that can be sent to the stream.
+ */
+export interface ActiveStreamInterface<SendPayload> {
+    /**
+     * An Observable emitting the raw data chunks received from the WebSocket.
+     * Consumers should filter/map this observable based on the specific stream protocol.
+     */
+    output$: Observable<StreamChunk>;
+    /**
+     * Sends a payload to the WebSocket stream.
+     * @param payload - The data to send, conforming to the SendPayload type.
+     * @returns True if the message was queued to be sent, false otherwise (e.g., socket not open).
+     */
+    send(payload: SendPayload): boolean;
+    /**
+     * Disconnects the WebSocket stream gracefully.
+     */
+    disconnect(): void;
+}
+//# sourceMappingURL=websocket-command.d.ts.map

package/esm/common/websocket-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket-command.d.ts","sourceRoot":"","sources":["../../src/common/websocket-command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,MAAM,CAAA;AACtC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6CAA6C,CAAA;AAE9E;;;;GAIG;AACH,MAAM,WAAW,gBAAgB,CAAC,MAAM,EAAE,WAAW;IACnD;;OAEG;IACH,SAAS,IAAI,MAAM,CAAA;IAEnB;;;OAGG;IACH,mBAAmB,IAAI,MAAM,CAAA;IAE7B;;;;;OAKG;IACH,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAA;IAE/C;;;;;OAKG;IACH,oBAAoB,CAAC,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAAA;CACpD;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB,CAAC,WAAW;IAChD;;;OAGG;IACH,OAAO,EAAE,UAAU,CAAC,WAAW,CAAC,CAAA;IAEhC;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAA;IAEnC;;OAEG;IACH,UAAU,IAAI,IAAI,CAAA;CACnB"}

package/esm/common/websocket-command.js

@@ -0,0 +1 @@
+export {};