flowscale 1.0.17 → 1.0.18-beta.1

package/CLAUDE.md

@@ -0,0 +1,73 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+- **Build**: `npm run build` or `tsc` - Compiles TypeScript to JavaScript in `/dist`
+- **Test**: `echo "No tests yet"` - Currently no test framework is configured
+- **Publish Beta**: `npm run publish:beta` - Publishes to npm with beta tag
+- **Publish Latest**: `npm run publish:latest` - Publishes to npm as latest version
+
+## Architecture Overview
+
+This is a TypeScript SDK for interacting with the Flowscale ComfyUI API. The codebase is structured as follows:
+
+### Core Components
+
+- **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
+
+1. **Environment Detection**: Automatically detects Node.js vs browser environments
+2. **Security**: Multiple security modes including secure proxy mode for frontend usage and API key protection
+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
+
+### API Methods Structure
+
+All API methods follow this pattern:
+- Make HTTP requests using the internal `makeRequest` method
+- Return typed responses based on interfaces in `types.ts`
+- Handle authentication via X-API-KEY header
+- Support both individual operations and bulk operations where applicable
+
+### Configuration
+
+The SDK requires:
+- `apiKey`: Flowscale API key (optional in proxy mode)
+- `baseUrl`: API endpoint URL
+- 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
+
+- TypeScript compiler targets ES5 with CommonJS modules
+- Outputs declaration files for TypeScript consumers
+- Uses strict type checking
+- Builds to `dist/` directory
+
+## 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

package/README.md

@@ -4,20 +4,39 @@ A comprehensive SDK designed to simplify interaction with the FlowScale ComfyUI
 
 ---
 
-## ⚠️ Important Security Notice for Browser Usage
+## 🔒 Secure Frontend Usage (Recommended)
 
-When using this SDK in a browser environment, your API key will be exposed to end users. This is a significant security risk. We strongly recommend:
+For secure frontend usage, use **Proxy Mode** to keep your API key safe on the backend:
 
-1. Using this SDK in a Node.js backend environment
-2. Creating a proxy API that securely handles the API key server-side
+```javascript
+// ✅ SECURE: No API key exposed to frontend users
+const flowscale = new FlowscaleAPI({
+  baseUrl: 'https://your-backend-proxy.com', // Your secure backend proxy
+  proxyMode: true, // Enable proxy mode
+  customHeaders: {
+    'Authorization': 'Bearer jwt-token-here' // Use JWT tokens instead
+  }
+});
+```
+
+### Security Options:
 
-If you understand the risks and still need to use the SDK directly in the browser, you must explicitly acknowledge this by setting the `allowDangerouslyExposeApiKey` option:
+1. **🔒 Backend-Only (MOST SECURE)**: Use SDK only on backend, frontend makes simple API calls to your server
+2. **🔒 Proxy Mode**: Frontend SDK routes through your backend proxy (provides SDK convenience with security)
+3. **⚠️ Direct Mode**: API key is exposed in browser (only for development/demos)
+
+**Recommendation:** For production apps, use Backend-Only approach for maximum security and simplicity.
+
+## ⚠️ Direct Browser Usage Warning
+
+If you use the SDK directly in the browser with an API key, it will be exposed to end users. Only do this for development:
 
 ```javascript
+// ⚠️ WARNING: API key will be visible to users
 const flowscale = new FlowscaleAPI({
   apiKey: 'your-api-key',
   baseUrl: 'your-api-url',
-  allowDangerouslyExposeApiKey: false // Only set to true if you understand the security risks
+  allowDangerouslyExposeApiKey: true // Required acknowledgment
 });
 ```
 
@@ -240,14 +259,14 @@ console.log('Workflow Result:', result);
 ### 5 `executeWorkflowAsync(workflowId, data, groupId?, pollIntervalMs?, timeoutMs?)`
 
 **Description:**
-Execute a workflow and automatically wait for the result by polling the output. This is a convenience method that combines `executeWorkflow` and `getOutput` with automatic polling.
+Execute a workflow and automatically wait for all outputs by polling. This is a convenience method that combines `executeWorkflow` and `getOutput` with automatic polling for all workflow outputs.
 
 **Parameters:**
 - `workflowId` *(string)*: The unique ID of the workflow.
 - `data` *(object)*: Input parameters for the workflow.
 - `groupId` *(string, optional)*: A custom identifier for grouping runs.
-- `pollIntervalMs` *(number, optional)*: Polling interval in milliseconds (default: 1000).
-- `timeoutMs` *(number, optional)*: Maximum time to wait for results in milliseconds (default: 300000 - 5 minutes).
+- `pollIntervalMs` *(number, optional)*: Polling interval in milliseconds (default: 2000).
+- `timeoutMs` *(number, optional)*: Maximum time to wait for results in milliseconds (default: 600000 - 10 minutes).
 
 **Usage:**
 ```javascript
@@ -273,10 +292,18 @@ try {
 ```json
 {
   "status": "success",
-  "data": {
-    "download_url": "https://runs.s3.amazonaws.com/generations/...",
-    "generation_status": "success"
-  }
+  "data": [
+    {
+      "filename": "output_image_1.png",
+      "download_url": "https://runs.s3.amazonaws.com/generations/...", 
+      "generation_status": "success"
+    },
+    {
+      "filename": "output_image_2.png",
+      "download_url": "https://runs.s3.amazonaws.com/generations/...",
+      "generation_status": "success"
+    }
+  ]
 }
 ```
 
@@ -421,47 +448,6 @@ console.log('All Runs:', allRuns);
 - Always store sensitive information such as API keys in environment variables.
 - Use `.env` files and libraries like `dotenv` for easy environment management.
 
-### Logging Configuration
-The SDK includes configurable logging to help with debugging and monitoring. By default, logging is enabled with the 'info' level.
-
-#### Configuration Options
-```javascript
-const flowscale = new FlowscaleAPI({
-  apiKey: 'your-api-key',
-  baseUrl: 'https://your-api-url.pod.flowscale.ai',
-  enableLogging: true,        // Enable/disable logging (default: true)
-  logLevel: 'info'           // Set log level: 'debug', 'info', 'warn', 'error' (default: 'info')
-});
-```
-
-#### Dynamic Logging Control
-You can also change logging settings after initialization:
-
-```javascript
-// Enable debug logging
-flowscale.setLoggingConfig(true, 'debug');
-
-// Disable logging completely
-flowscale.setLoggingConfig(false);
-
-// Check current logging configuration
-const loggingConfig = flowscale.getLoggingConfig();
-console.log(loggingConfig); // { enabled: true, level: 'debug' }
-```
-
-#### Log Levels
-- **debug**: Most verbose, includes detailed operation information
-- **info**: General information about operations (default)
-- **warn**: Warning messages for potential issues
-- **error**: Only error messages
-
-#### Log Format
-All logs are prefixed with timestamp and level:
-```
-[Flowscale INFO] 2025-06-03T10:30:45.123Z: WebSocket connection established
-[Flowscale DEBUG] 2025-06-03T10:30:46.456Z: Polling workflow output: {...}
-```
-
 ### Error Handling
 - Wrap API calls in try-catch blocks to handle errors gracefully.
 - Log errors for debugging and improve resilience.
@@ -583,12 +569,100 @@ See `examples/websocket-example.html` for a complete browser example with a user
 #### 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:
+**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
 ```
 
-**Note:** WebSocket functionality is natively available only in browser environments. For Node.js, you need to use a WebSocket library like `ws`.
+```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
+});
+
+// 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)
+});
+```
+
+---
+
+## 🔒 Advanced Security Features
+
+### Proxy Mode Configuration
+
+```javascript
+const flowscale = new FlowscaleAPI({
+  baseUrl: 'https://your-backend-proxy.com',
+  proxyMode: true,
+  customHeaders: {
+    'Authorization': 'Bearer your-jwt-token',
+    'X-User-ID': 'user123'  // Additional custom headers
+  }
+});
+```
+
+### Dynamic Header Management
+
+```javascript
+// Update JWT token without recreating SDK instance
+flowscale.updateCustomHeaders({
+  'Authorization': 'Bearer new-jwt-token'
+});
+
+// Get current headers
+const headers = flowscale.getCustomHeaders();
+
+// Clear all custom headers
+flowscale.clearCustomHeaders();
+```
+
+### Architecture Options
+
+#### Option 1: Backend-Only (Recommended)
+```javascript
+// Backend - Use Flowscale SDK
+const flowscale = new FlowscaleAPI({
+  apiKey: process.env.FLOWSCALE_API_KEY,
+  baseUrl: process.env.FLOWSCALE_API_URL
+});
+
+app.post('/api/workflows/execute', async (req, res) => {
+  const result = await flowscale.executeWorkflowAsync(req.body.workflowId, req.body.data);
+  res.json(result);  
+});
+
+// Frontend - Simple API calls
+const result = await fetch('/api/workflows/execute', {
+  method: 'POST',
+  headers: { 'Authorization': 'Bearer ' + token },
+  body: JSON.stringify({ workflowId, data })
+});
+```
+
+#### Option 2: Proxy Mode (SDK Convenience)
+```javascript
+// Backend - SDK + Proxy endpoints
+const flowscale = new FlowscaleAPI({
+  apiKey: process.env.FLOWSCALE_API_KEY,
+  baseUrl: process.env.FLOWSCALE_API_URL
+});
+
+// Frontend - SDK through proxy
+const flowscale = new FlowscaleAPI({
+  baseUrl: 'https://your-backend.com',
+  proxyMode: true,
+  customHeaders: { 'Authorization': 'Bearer jwt-token' }
+});
+```
+
+See `examples/secure-frontend-example.html` and `examples/backend-proxy-example.js` for complete implementation examples.
 
 ---
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { HealthCheckResponse, QueueResponse, ExecuteWorkflowResponse, GetOutputResponse, RunDetailResponse, RunListResponse, CancelRunResponse, FlowscaleConfig, WorkflowResponse, WebSocketOptions } from './types';
+import { HealthCheckResponse, QueueResponse, ExecuteWorkflowResponse, GetOutputResponse, GetAllOutputsResponse, RunDetailResponse, RunListResponse, CancelRunResponse, FlowscaleConfig, WorkflowResponse, WebSocketOptions } from './types';
 export declare class FlowscaleAPI {
     private apiKey;
     private baseUrl;
@@ -9,6 +9,10 @@ export declare class FlowscaleAPI {
     private ws;
     private wsConnected;
     private reconnectAttempts;
+    private reconnectTimeout;
+    private WebSocketImpl;
+    private proxyMode;
+    private customHeaders;
     constructor(config: FlowscaleConfig);
     /**
      * Checks the health status of all ComfyUI instances within the specified cluster.
@@ -32,7 +36,7 @@ export declare class FlowscaleAPI {
         [key: string]: any;
     }, groupId?: string): Promise<ExecuteWorkflowResponse>;
     /**
-     * Executes a workflow and waits for the output by polling.
+     * Executes a workflow and waits for all outputs by polling.
      * @param workflowId - The ID of the workflow to execute.
      * @param data - Form data including text fields and file uploads.
      * @param groupId - Optional group ID.
@@ -41,7 +45,7 @@ export declare class FlowscaleAPI {
      */
     executeWorkflowAsync(workflowId: string, data: {
         [key: string]: any;
-    }, groupId?: string, pollIntervalMs?: number, timeoutMs?: number): Promise<GetOutputResponse>;
+    }, groupId?: string, pollIntervalMs?: number, timeoutMs?: number): Promise<GetAllOutputsResponse>;
     /**
      * Retrieves the output of a specific run by providing the filename.
      * @param filename - The filename of the output to retrieve.
@@ -99,9 +103,28 @@ export declare class FlowscaleAPI {
      * @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
+     */
+    updateCustomHeaders(headers: {
+        [key: string]: string;
+    }): void;
+    /**
+     * Clears all custom headers
+     */
+    clearCustomHeaders(): void;
+    /**
+     * Gets current custom headers
+     * @returns Copy of current custom headers
+     */
+    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';