flowscale 1.1.0 → 1.3.0

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,118 @@
+name: 🐛 Bug Report
+description: Report a bug or unexpected behavior
+title: "[Bug]: "
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug! Please fill out the information below to help us reproduce and fix the issue.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear and concise description of what the bug is.
+      placeholder: Describe the bug...
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to Reproduce
+      description: Steps to reproduce the behavior
+      placeholder: |
+        1. Initialize SDK with...
+        2. Call method...
+        3. Observe error...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What should have happened?
+      placeholder: Expected behavior...
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened?
+      placeholder: Actual behavior...
+    validations:
+      required: true
+
+  - type: dropdown
+    id: environment
+    attributes:
+      label: Environment
+      description: Where are you running the SDK?
+      options:
+        - Node.js
+        - Browser
+        - Both
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: SDK Version
+      description: Which version of the Flowscale SDK are you using?
+      placeholder: "1.1.0"
+    validations:
+      required: true
+
+  - type: input
+    id: node-version
+    attributes:
+      label: Node.js Version (if applicable)
+      description: Output of `node --version`
+      placeholder: "v18.17.0"
+
+  - type: textarea
+    id: code
+    attributes:
+      label: Code Sample
+      description: Minimal code sample that reproduces the issue
+      render: javascript
+      placeholder: |
+        const flowscale = new FlowscaleAPI({
+          apiKey: 'your-key',
+          baseUrl: 'your-url'
+        });
+        
+        // Code that causes the bug
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Error Logs
+      description: Any relevant error messages or logs
+      render: text
+      placeholder: Paste error logs here...
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other context about the problem
+      placeholder: Additional context...
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      description: Please confirm the following
+      options:
+        - label: I have searched existing issues to avoid duplicates
+          required: true
+        - label: I have provided a minimal code sample
+          required: true
+        - label: I have included relevant error messages
+          required: true

package/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,117 @@
+name: ✨ Feature Request
+description: Suggest a new feature or enhancement
+title: "[Feature]: "
+labels: ["enhancement", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a new feature! Please provide as much detail as possible.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Statement
+      description: What problem does this feature solve?
+      placeholder: I'm frustrated when...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: What would you like to see added or changed?
+      placeholder: I would like to see...
+    validations:
+      required: true
+
+  - type: dropdown
+    id: category
+    attributes:
+      label: Feature Category
+      description: What type of feature is this?
+      options:
+        - API Method
+        - Developer Experience
+        - Performance
+        - Security
+        - Documentation
+        - TypeScript Types
+        - WebSocket Support
+        - Error Handling
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Use Case
+      description: Describe your specific use case for this feature
+      placeholder: I need this feature because...
+    validations:
+      required: true
+
+  - type: textarea
+    id: api-design
+    attributes:
+      label: Proposed API Design (if applicable)
+      description: How would you like the API to work?
+      render: javascript
+      placeholder: |
+        // Example API design
+        const result = await flowscale.newMethod({
+          param1: 'value1',
+          param2: 'value2'
+        });
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: What alternatives have you considered?
+      placeholder: I have considered...
+
+  - type: dropdown
+    id: priority
+    attributes:
+      label: Priority
+      description: How important is this feature to you?
+      options:
+        - Low - Nice to have
+        - Medium - Would improve my workflow
+        - High - Blocking my use case
+        - Critical - Can't use SDK without this
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: implementation
+    attributes:
+      label: Implementation
+      description: Are you willing to help implement this feature?
+      options:
+        - label: I'm willing to submit a pull request for this feature
+        - label: I can help with testing
+        - label: I can help with documentation
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other context, screenshots, or examples
+      placeholder: Additional context...
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      description: Please confirm the following
+      options:
+        - label: I have searched existing issues to avoid duplicates
+          required: true
+        - label: This feature would benefit the broader community
+          required: true
+        - label: I have provided a clear use case
+          required: true

package/.github/ISSUE_TEMPLATE/question.yml

@@ -0,0 +1,99 @@
+name: ❓ Question
+description: Ask a question about the SDK
+title: "[Question]: "
+labels: ["question", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Have a question about the Flowscale SDK? We're here to help!
+
+  - type: textarea
+    id: question
+    attributes:
+      label: Question
+      description: What would you like to know?
+      placeholder: How do I...?
+    validations:
+      required: true
+
+  - type: dropdown
+    id: category
+    attributes:
+      label: Question Category
+      description: What area is your question about?
+      options:
+        - Getting Started
+        - API Usage
+        - Authentication
+        - WebSocket
+        - Error Handling
+        - TypeScript
+        - Browser Usage
+        - Node.js Usage
+        - Security
+        - Performance
+        - Migration
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Context
+      description: What are you trying to accomplish?
+      placeholder: I'm trying to...
+
+  - type: textarea
+    id: attempted
+    attributes:
+      label: What Have You Tried?
+      description: What solutions have you already attempted?
+      placeholder: I have tried...
+
+  - type: textarea
+    id: code
+    attributes:
+      label: Code Sample (if applicable)
+      description: Share any relevant code
+      render: javascript
+      placeholder: |
+        const flowscale = new FlowscaleAPI({
+          // Your code here
+        });
+
+  - type: input
+    id: version
+    attributes:
+      label: SDK Version
+      description: Which version are you using?
+      placeholder: "1.1.0"
+
+  - type: dropdown
+    id: environment
+    attributes:
+      label: Environment
+      description: Where are you running the SDK?
+      options:
+        - Node.js
+        - Browser
+        - Both
+        - Not sure
+
+  - type: checkboxes
+    id: resources
+    attributes:
+      label: Documentation
+      description: Have you checked these resources?
+      options:
+        - label: I have read the README
+        - label: I have checked the examples
+        - label: I have searched existing issues
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other details that might help?
+      placeholder: Additional context...

package/.github/pull_request_template.md

@@ -0,0 +1,130 @@
+# Pull Request
+
+## 📝 Description
+
+Brief description of what this PR does and why.
+
+Fixes #(issue_number) <!-- Link to related issue -->
+
+## 🔧 Type of Change
+
+- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
+- [ ] ✨ New feature (non-breaking change which adds functionality)
+- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] 📚 Documentation update
+- [ ] 🔨 Refactoring (no functional changes)
+- [ ] ⚡ Performance improvement
+- [ ] 🧪 Test coverage improvement
+
+## 🧪 Testing
+
+Describe the tests you ran and how to reproduce them:
+
+- [ ] Unit tests pass
+- [ ] Integration tests pass
+- [ ] Manual testing completed
+- [ ] Browser testing (if applicable)
+- [ ] Node.js testing (if applicable)
+
+**Test Configuration:**
+- Node.js version: 
+- Browser (if applicable): 
+- Operating System: 
+
+## 📋 Changes Made
+
+List the main changes:
+
+- Change 1
+- Change 2
+- Change 3
+
+## 🔄 Breaking Changes
+
+If this introduces breaking changes, describe:
+
+1. **What breaks:** 
+2. **Migration path:** 
+3. **Deprecation timeline:** 
+
+## 📚 Documentation
+
+- [ ] Documentation has been updated
+- [ ] README updated (if needed)
+- [ ] CHANGELOG.md updated
+- [ ] Type definitions updated
+- [ ] Examples updated (if needed)
+
+## 🔍 Code Quality
+
+- [ ] Code follows the project's coding standards
+- [ ] Self-review of the code completed
+- [ ] Code is commented where necessary
+- [ ] No console logs or debugging code left
+- [ ] Variables and functions have meaningful names
+
+## ⚡ Performance
+
+- [ ] No performance regressions introduced
+- [ ] Performance improvements documented (if applicable)
+
+## 🔒 Security
+
+- [ ] No sensitive information exposed
+- [ ] Input validation added where necessary
+- [ ] Security implications considered
+
+## 📱 Compatibility
+
+- [ ] Backward compatibility maintained
+- [ ] Forward compatibility considered
+- [ ] Cross-platform compatibility verified
+
+## 📦 Dependencies
+
+- [ ] No unnecessary dependencies added
+- [ ] Dependencies are up to date
+- [ ] License compatibility checked
+
+## 🎯 Review Focus
+
+Please pay special attention to:
+
+- Area 1 to review carefully
+- Area 2 to review carefully
+- Any specific concerns
+
+## 📸 Screenshots (if applicable)
+
+Add screenshots or GIFs to demonstrate changes:
+
+## 🚀 Deployment
+
+- [ ] Changes can be deployed safely
+- [ ] Database migrations included (if applicable)
+- [ ] Environment variables documented (if applicable)
+
+## ✅ Final Checklist
+
+- [ ] I have performed a self-review of my code
+- [ ] I have commented my code where necessary
+- [ ] I have made corresponding changes to the documentation
+- [ ] My changes generate no new warnings
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] New and existing unit tests pass locally with my changes
+- [ ] Any dependent changes have been merged and published
+
+## 🤝 Reviewer Guidelines
+
+When reviewing this PR, please check:
+
+- [ ] Code quality and style
+- [ ] Test coverage
+- [ ] Documentation completeness
+- [ ] Breaking change handling
+- [ ] Security implications
+- [ ] Performance impact
+
+## 💬 Additional Notes
+
+Add any additional notes, concerns, or context here.

package/CHANGELOG.md

@@ -0,0 +1,163 @@
+# Changelog
+
+All notable changes to the Flowscale JavaScript SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### ✨ 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
+
+### 🎉 Major Features
+- **Backward Compatibility**: Added smart detection for `executeWorkflowAsync` response format
+- **Deprecation System**: Implemented comprehensive deprecation warnings with migration guidance
+- **Enhanced Multi-Output Support**: Improved handling of workflows with multiple outputs
+
+### ✨ Added
+- New `returnAllOutputs` parameter in `executeWorkflowAsync` for explicit format control
+- `LegacyGetOutputResponse` type with deprecation warnings in API responses
+- `DeprecationWarning` interface for structured deprecation notices
+- Method overloads for better TypeScript support
+- Console warnings for deprecated usage patterns
+- Migration guide in README with clear examples
+
+### 🔄 Changed
+- `executeWorkflowAsync` now auto-detects single vs multiple outputs
+- Single output workflows return legacy format with deprecation notice
+- Multiple output workflows return new array format
+- Enhanced error messages with better context
+
+### 🗓️ Deprecated
+- Legacy single output format in `executeWorkflowAsync` (removal: September 1st, 2025)
+- Will be completely removed in v2.0.0
+
+### 📚 Documentation
+- Updated README with migration guide
+- Added backward compatibility examples
+- Enhanced method documentation with deprecation notices
+
+### 🔧 Technical
+- Improved TypeScript type definitions
+- Better error handling and validation
+- Enhanced logging system
+
+## [1.0.18-beta.2] - 2025-01-29
+
+### 🚨 Breaking Changes
+- `executeWorkflowAsync` response format changed to array (FIXED in v1.1.0)
+
+### ✨ Added
+- Multi-output support in `executeWorkflowAsync`
+- `GetAllOutputsResponse` type for multiple outputs
+- Enhanced polling logic for multiple outputs
+
+### 🐛 Fixed
+- Improved error handling in workflow execution
+- Better timeout handling
+
+### ⚠️ Issues
+- **Backward compatibility broken** - users should upgrade to v1.1.0
+
+## [1.0.17] - 2024-12-XX
+
+### ✨ Added
+- Enhanced security features
+- Proxy mode support for secure frontend usage
+- JWT authentication example
+- Improved WebSocket handling
+- Configurable logging levels
+
+### 🔧 Changed
+- Updated workflow execution error handling
+- Enhanced response types
+- Better input validation
+
+### 🐛 Fixed
+- WebSocket connection stability
+- Error message clarity
+- Authentication flow improvements
+
+## [1.0.16] - 2024-11-XX
+
+### ✨ Added
+- WebSocket support for real-time updates
+- Browser and Node.js environment detection
+- Enhanced file upload handling
+- Better retry logic for failed requests
+
+### 🔧 Changed
+- Improved API error handling
+- Better timeout management
+- Enhanced type definitions
+
+## Previous Versions
+
+### [1.0.15] and earlier
+- Initial releases
+- Basic API functionality
+- Core workflow execution
+- File upload support
+- Authentication handling
+
+---
+
+## Migration Guides
+
+### From 1.0.x to 1.1.0
+
+**No breaking changes** - all existing code continues to work.
+
+#### If you see deprecation warnings:
+
+**Old code** (still works):
+```javascript
+const result = await flowscale.executeWorkflowAsync(workflowId, data);
+console.log(result.data.download_url); // Single output
+```
+
+**New code** (recommended):
+```javascript
+const result = await flowscale.executeWorkflowAsync(workflowId, data, groupId, 2000, 600000, true);
+result.data.forEach(output => {
+  console.log(output.download_url); // Multiple outputs
+});
+```
+
+#### Handling both formats:
+```javascript
+const result = await flowscale.executeWorkflowAsync(workflowId, data);
+
+if (Array.isArray(result.data)) {
+  // New format - multiple outputs
+  result.data.forEach(output => console.log(output.download_url));
+} else {
+  // Legacy format - single output
+  console.log(result.data.download_url);
+}
+```
+
+### Future Migration (v2.0.0 - September 1st, 2025)
+
+In v2.0.0, the legacy format will be completely removed:
+- `executeWorkflowAsync` will always return array format
+- `returnAllOutputs` parameter will be removed
+- `LegacyGetOutputResponse` type will be removed
+
+---
+
+## Support
+
+- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/FlowScale-AI/flowscale-js-sdk/issues)
+- 💬 **Discussions**: [GitHub Discussions](https://github.com/FlowScale-AI/flowscale-js-sdk/discussions)
+- 🔒 **Security**: [Security Policy](SECURITY.md)
+- 🤝 **Contributing**: [Contributing Guide](CONTRIBUTING.md)

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