flowscale 1.2.0 → 1.3.1

package/CHANGELOG.md

@@ -9,10 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### ✨ Added
 - `executeWorkflowAsync` now supports an options object with `onIntermediateResponse` callback to emit intermediate polling updates.
+- Added `subscribeRunEvents(runId, options)` to consume run events via SSE (`/api/v1/runs/{run_id}/events`).
 
 ### 🔄 Changed
 - `executeWorkflowAsync` still accepts the legacy boolean as the 6th parameter for backward compatibility.
 - `GetOutputResponse` and `RunDetail` types now include optional progress-related fields returned by the API.
+- Removed WebSocket APIs from the JavaScript SDK (`connectWebSocket`, `disconnectWebSocket`, `sendWebSocketMessage`, `isWebSocketConnected`) and removed related examples.
 
 ## [1.1.0] - 2025-01-29
 

package/CLAUDE.md

@@ -18,13 +18,11 @@ This is a TypeScript SDK for interacting with the Flowscale ComfyUI API. The cod
 - **FlowscaleAPI Class** (`src/index.ts`): The main SDK class that provides all API methods
   - Uses Axios for HTTP requests with built-in retry logic and timeout handling
   - Supports both Node.js and browser environments with security warnings for browser usage
-  - Includes WebSocket support for real-time communication (browser only)
   - Has configurable logging with different levels (debug, info, warn, error)
 
 - **Type Definitions** (`src/types.ts`): Comprehensive TypeScript interfaces for:
   - API responses (HealthCheckResponse, WorkflowResponse, etc.)
   - Configuration options (FlowscaleConfig)
-  - WebSocket-related types (WebSocketOptions, WebSocketMessage)
 
 ### Key Features
 
@@ -33,8 +31,7 @@ This is a TypeScript SDK for interacting with the Flowscale ComfyUI API. The cod
 3. **Input Validation**: Comprehensive validation for all required parameters with helpful error messages
 4. **File Upload Support**: Handles FormData for file uploads in workflow execution
 5. **Async Workflow Execution**: `executeWorkflowAsync` method polls for all outputs and waits for completion automatically
-6. **WebSocket Integration**: Real-time updates for workflow status (supports both browser and Node.js with WebSocket polyfill) with proper memory management
-7. **Error Handling**: Consistent error handling with retry logic for timeouts and 504 errors
+6. **Error Handling**: Consistent error handling with retry logic for timeouts and 504 errors
 
 ### API Methods Structure
 
@@ -52,7 +49,6 @@ The SDK requires:
 - Optional: timeout, retry settings
 - Optional: `proxyMode` - Enable secure frontend usage without exposing API key
 - Optional: `customHeaders` - For JWT tokens, session cookies, etc.
-- Optional: `WebSocketImpl` - For Node.js environments, pass the 'ws' WebSocket constructor to enable WebSocket functionality
 
 ### Build Configuration
 
@@ -64,10 +60,9 @@ The SDK requires:
 ## Important Notes
 
 - No test framework is currently configured
-- WebSocket functionality works in both browser and Node.js environments (Node.js requires passing `WebSocketImpl: require('ws')`)
 - **Security**: Supports both direct API key usage and secure proxy mode for frontend applications
 - **Proxy Mode**: Enables secure frontend usage by routing requests through a backend proxy that holds the API key
 - All file uploads are handled through FormData with support for File/Blob objects
 - The SDK has built-in retry logic for network timeouts and gateway errors
 - Comprehensive input validation prevents common configuration errors
-- Dynamic header management supports JWT token refresh and session management
+- Dynamic header management supports JWT token refresh and session management

package/Makefile

@@ -24,13 +24,6 @@ ifndef VERSION
 endif
 	npm deprecate flowscale@$(VERSION) "This version is deprecated. Please upgrade to a newer version."
 
-# Run the WebSocket examples
-run-browser-example:
-	@echo "Open examples/websocket-example.html in your browser"
-
-run-node-example:
-	node examples/node-websocket-example.js
-
 # Complete release process
 release: build version publish
 
@@ -47,6 +40,4 @@ help:
 	@echo "  make release           - Complete release process (build, version, publish)"
 	@echo "  make release-beta      - Complete beta release process (build, version, publish-beta)"
 	@echo "  make deprecate VERSION=x.x.x - Deprecate a specific version"
-	@echo "  make run-browser-example - Instructions for running browser WebSocket example"
-	@echo "  make run-node-example   - Run Node.js WebSocket example"
-	@echo "  make help              - Show this help message"
+	@echo "  make help              - Show this help message"

package/README.md

@@ -501,156 +501,71 @@ console.log('All Runs:', allRuns);
 
 ---
 
-## Best Practices
-
-### Environment Configuration
-- Always store sensitive information such as API keys in environment variables.
-- Use `.env` files and libraries like `dotenv` for easy environment management.
-
-### Error Handling
-- Wrap API calls in try-catch blocks to handle errors gracefully.
-- Log errors for debugging and improve resilience.
-
-### Testing and Debugging
-- Test workflows in a development environment before deploying to production.
-- Validate inputs to ensure they match the workflow requirements.
-
----
-
-## WebSocket API
-
-The Flowscale SDK provides WebSocket functionality to enable real-time communication with the Flowscale API. This is particularly useful for receiving updates about workflow execution status and other events in real-time.
-
-### 1. `connectWebSocket(options)`
+### 10. `subscribeRunEvents(runId, options?)`
 
 **Description:**
-Establishes a WebSocket connection to the Flowscale API.
+Subscribe to run-level events over SSE using the new `/api/v1/runs/{run_id}/events` endpoint.
 
 **Parameters:**
-- `options` *(object, optional)*: Configuration options for the WebSocket connection.
-  - `onOpen` *(function, optional)*: Callback function executed when the connection opens.
-  - `onClose` *(function, optional)*: Callback function executed when the connection closes.
-  - `onError` *(function, optional)*: Callback function executed when an error occurs.
-  - `onMessage` *(function, optional)*: Callback function executed when a message is received.
-  - `reconnect` *(boolean, optional)*: Whether to attempt reconnection if the connection is lost. Default: `true`.
-  - `reconnectInterval` *(number, optional)*: Milliseconds to wait before attempting to reconnect. Default: `5000`.
-  - `maxReconnectAttempts` *(number, optional)*: Maximum number of reconnection attempts. Default: `5`.
+- `runId` *(string)*: The run ID to stream events for.
+- `options` *(object, optional)*:
+  - `fromSeq` *(number, optional)*: Replay from this sequence number.
+  - `signal` *(AbortSignal, optional)*: External abort signal.
+  - `onOpen` *(function, optional)*: Called when stream response opens.
+  - `onEvent` *(function, optional)*: Called for each parsed SSE event payload.
+  - `onError` *(function, optional)*: Called on stream errors.
+  - `onClose` *(function, optional)*: Called when stream closes.
+
+**Returns:**
+- `{ close, done }`
+  - `close()` aborts the SSE stream.
+  - `done` is a promise that resolves when stream ends.
 
 **Usage:**
 ```javascript
-// Connect to WebSocket and set up event handlers
-const disconnect = flowscale.connectWebSocket({
-  onOpen: () => {
-    console.log('WebSocket connected!');
+const stream = flowscale.subscribeRunEvents(runId, {
+  fromSeq: 0,
+  onEvent: (event) => {
+    console.log('Run event:', event.id, event.data);
   },
-  onMessage: (message) => {
-    console.log('Received message:', message);
-    // Handle different message types
-    if (message.type === 'run_status_update') {
-      console.log('Run status updated:', message.data);
-    }
+  onError: (error) => {
+    console.error('Run event stream error:', error);
   },
-  onClose: (event) => {
-    console.log('WebSocket closed:', event.code, event.reason);
+  onClose: () => {
+    console.log('Run event stream closed');
   },
-  onError: (error) => {
-    console.error('WebSocket error:', error);
-  }
 });
 
-// Later, to disconnect:
-disconnect();
-```
-
-### 2. `disconnectWebSocket()`
-
-**Description:**
-Closes the WebSocket connection if it is open.
+// Optional: stop manually
+// stream.close();
 
-**Usage:**
-```javascript
-flowscale.disconnectWebSocket();
-console.log('WebSocket disconnected');
+await stream.done;
 ```
 
-### 3. `sendWebSocketMessage(message)`
-
-**Description:**
-Sends a message through the WebSocket connection.
-
-**Parameters:**
-- `message` *(any)*: The message to send. Objects will be automatically stringified.
-
-**Returns:**
-- *(boolean)*: `true` if the message was sent successfully, `false` otherwise.
-
-**Usage:**
+**Node.js < 18 note:** pass a custom `fetchImpl` in SDK config for SSE support.
 ```javascript
-const success = flowscale.sendWebSocketMessage({
-  type: 'client_event',
-  data: {
-    action: 'subscribe',
-    runId: '808f34d0-ef97-4b78-a00f-1268077ea6db'
-  }
+const flowscale = new FlowscaleAPI({
+  apiKey,
+  baseUrl,
+  fetchImpl: fetch // e.g. from undici/node-fetch polyfill
 });
-
-if (success) {
-  console.log('Message sent successfully');
-} else {
-  console.error('Failed to send message');
-}
-```
-
-### 4. `isWebSocketConnected()`
-
-**Description:**
-Checks if the WebSocket connection is currently open.
-
-**Returns:**
-- *(boolean)*: `true` if the WebSocket is connected, `false` otherwise.
-
-**Usage:**
-```javascript
-if (flowscale.isWebSocketConnected()) {
-  console.log('WebSocket is connected');
-} else {
-  console.log('WebSocket is not connected');
-}
 ```
 
-### WebSocket Examples
-
-The SDK includes example implementations for both browser and Node.js environments:
-
-#### Browser Example
-See `examples/websocket-example.html` for a complete browser example with a user interface.
-
-#### Node.js Example
-Node.js requires a custom WebSocket implementation since the WebSocket API is not built-in. See `examples/node-websocket-example.js` for an example using the 'ws' library.
+---
 
-**Note:** To use WebSockets in Node.js, you'll need to install the 'ws' package and pass it to the SDK:
-```bash
-npm install ws
-```
+## Best Practices
 
-```javascript
-const WebSocket = require('ws');
-const flowscale = new FlowscaleAPI({
-  apiKey: 'your-api-key',
-  baseUrl: 'https://your-api-url.pod.flowscale.ai',
-  WebSocketImpl: WebSocket // Pass the WebSocket implementation for Node.js
-});
+### Environment Configuration
+- Always store sensitive information such as API keys in environment variables.
+- Use `.env` files and libraries like `dotenv` for easy environment management.
 
-// Now you can use WebSocket methods directly in Node.js!
-const disconnect = flowscale.connectWebSocket({
-  onOpen: () => console.log('Connected!'),
-  onMessage: (message) => console.log('Message:', message),
-  onClose: (event) => console.log('Closed:', event),
-  onError: (error) => console.error('Error:', error)
-});
-```
+### Error Handling
+- Wrap API calls in try-catch blocks to handle errors gracefully.
+- Log errors for debugging and improve resilience.
 
----
+### Testing and Debugging
+- Test workflows in a development environment before deploying to production.
+- Validate inputs to ensure they match the workflow requirements.
 
 ## 🔒 Advanced Security Features
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { HealthCheckResponse, QueueResponse, ExecuteWorkflowResponse, GetOutputResponse, GetAllOutputsResponse, LegacyGetOutputResponse, RunDetailResponse, RunListResponse, CancelRunResponse, ExecuteWorkflowAsyncOptions, FlowscaleConfig, WorkflowResponse, WebSocketOptions } from './types';
+import { HealthCheckResponse, QueueResponse, ExecuteWorkflowResponse, GetOutputResponse, GetAllOutputsResponse, LegacyGetOutputResponse, RunDetailResponse, RunListResponse, CancelRunResponse, ExecuteWorkflowAsyncOptions, RunEventsSSEConnection, RunEventsSSEOptions, FlowscaleConfig, WorkflowResponse } from './types';
 export declare class FlowscaleAPI {
     private apiKey;
     private baseUrl;
@@ -6,13 +6,9 @@ export declare class FlowscaleAPI {
     private isNode;
     private maxRetries;
     private retryDelay;
-    private ws;
-    private wsConnected;
-    private reconnectAttempts;
-    private reconnectTimeout;
-    private WebSocketImpl;
     private proxyMode;
     private customHeaders;
+    private fetchImpl;
     constructor(config: FlowscaleConfig);
     /**
      * Checks the health status of all ComfyUI instances within the specified cluster.
@@ -68,10 +64,25 @@ export declare class FlowscaleAPI {
      * @param groupId - The group ID to filter runs.
      */
     getRuns(groupId?: string): Promise<RunListResponse>;
+    /**
+     * Subscribes to run events from the SSE endpoint.
+     * @param runId - The run ID to stream events for.
+     * @param options - SSE subscription options and callbacks.
+     * @returns Connection handle with `close()` and `done` promise.
+     */
+    subscribeRunEvents(runId: string, options?: RunEventsSSEOptions): RunEventsSSEConnection;
     private resolveExecuteWorkflowAsyncOptions;
     private emitExecuteWorkflowAsyncIntermediateResponse;
     private formatUnknownError;
     private sleep;
+    private normalizeGetOutputResponse;
+    private resolveGlobalFetch;
+    private consumeRunEventsStream;
+    private safeReadResponseText;
+    private consumeRunEventsSnapshotResponse;
+    private consumeSSEReadableStream;
+    private parseSSEEventId;
+    private invokeRunEventsCallback;
     /**
      * Helper method to append data to FormData.
      */
@@ -92,22 +103,6 @@ export declare class FlowscaleAPI {
      * Makes API request with retry capability for browser environments
      */
     private makeRequest;
-    /**
-     * Connects to the WebSocket API endpoint and sets up event handlers.
-     * @param options - Configuration options for the WebSocket connection
-     * @returns A function that can be called to disconnect the WebSocket
-     */
-    connectWebSocket(options?: WebSocketOptions): () => void;
-    /**
-     * Disconnects the WebSocket connection if it exists.
-     */
-    disconnectWebSocket(): void;
-    /**
-     * Sends a message through the WebSocket connection.
-     * @param message - The message to send
-     * @returns Whether the message was sent successfully
-     */
-    sendWebSocketMessage(message: any): boolean;
     /**
      * Updates custom headers for authentication (useful for refreshing JWT tokens)
      * @param headers - Object containing header key-value pairs
@@ -126,10 +121,5 @@ export declare class FlowscaleAPI {
     getCustomHeaders(): {
         [key: string]: string;
     };
-    /**
-     * Checks if the WebSocket connection is currently open.
-     * @returns True if the WebSocket is connected, false otherwise
-     */
-    isWebSocketConnected(): boolean;
 }
 export * from './types';