flowscale 1.0.11 → 1.0.13

package/README.md

@@ -1,19 +1,323 @@
 # Flowscale Node.js SDK
 
-A Node.js SDK for interacting with the Flowscale platform without directly managing API requests. This library simplifies invoking workflows, retrieving outputs, and checking run statuses.
+A comprehensive Node.js SDK designed to simplify interaction with the FlowScale ComfyUI API. This library abstracts away the complexities of API calls, enabling you to effortlessly invoke workflows, retrieve outputs, manage workflow runs, and monitor system health.
+
+---
 
 ## Installation
 
+Install the Flowscale SDK by `npm`, `yarn`, `pnpm` or `bun`:
+
 ```bash
 npm install flowscale
 
+yarn add flowscale
+
+pnpm install flowscale
+
+bun install flowscale
+```
+
+---
+
+## Quick Start
+
+### Importing the SDK
+
+To get started, import the Flowscale SDK into your project:
+
+```javascript
+import { FlowscaleAPI } from 'flowscale';
+
+// Initialize the SDK
+const apiKey = process.env.FLOWSCALE_API_KEY;
+const apiUrl = process.env.FLOWSCALE_API_URL;
+
+if (!apiKey || !apiUrl) {
+  console.error('FLOWSCALE_API_KEY or FLOWSCALE_API_URL not set in .env');
+  process.exit(1);
+}
+
+const flowscale = new FlowscaleAPI(apiKey, apiUrl);
+```
+
+**Environment Variables:** Add the following to your `.env` file:
+
+```plaintext
+FLOWSCALE_API_KEY=your-api-key
+FLOWSCALE_API_URL=https://your-api-url.pod.flowscale.ai
+```
+
+---
+
+## SDK Methods
+
+Below is a detailed guide to the SDK methods, including descriptions, usage, and response formats.
+
+### 1. `checkHealth()`
+
+**Description:**
+Check the health status of the Flowscale platform, including the status of containers and services.
+
+**Usage:**
+```javascript
+const health = await flowscale.checkHealth();
+console.log('API Health:', health);
+```
+
+**Response Example:**
+```json
+{
+  "status": "success",
+  "data": [
+    {
+      "container": "container #1",
+      "status": "idle"
+    },
+    {
+      "container": "container #2",
+      "status": "running"
+    }
+  ]
+}
+```
+
+---
+
+### 2. `getQueue()`
+
+**Description:**
+Retrieve the current status of the workflow queue, including running and pending jobs.
+
+**Usage:**
+```javascript
+const queue = await flowscale.getQueue();
+console.log('Queue Details:', queue);
+```
+
+**Response Example:**
+```json
+{
+  "status": "success",
+  "data": [
+    {
+      "container": "container #1",
+      "queue": {
+        "queue_running": [
+          [
+            0,
+            "2a0babc4-acce-4521-9576-00fa0e6ecc91"
+          ]
+        ],
+        "queue_pending": [
+          [
+            1,
+            "5d60718a-7e89-4c64-b32d-0d1366b44e2a"
+          ]
+        ]
+      }
+    }
+  ]
+}
+```
+
+---
+
+### 3. `executeWorkflow(workflowId, data, groupId?)`
+
+**Description:**
+Trigger a workflow execution using its unique `workflowId`. Input data and an optional `groupId` can be provided for better organization and tracking.
+
+**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.
+
+**Usage:**
+```javascript
+const workflowId = "bncu0a1kipv";
+const groupId = "test_group";
+
+const inputs = {
+   "text_51536": "Prompt test",
+   "image_1234": { /* File or Blob of image */ },
+   "video_1239": { /* File or Blob of video */ }
+};
+
+const result = await flowscale.executeWorkflow(workflowId, inputs, groupId);
+console.log('Workflow Result:', result);
+```
+
+**Response Example:**
+```json
+{
+  "status": "success",
+  "data": {
+    "number": 0,
+    "node_errors": {},
+    "output_names": [
+      "filename_prefix_58358_5WWF7GQUYF"
+    ],
+    "run_id": "808f34d0-ef97-4b78-a00f-1268077ea6db"
+  }
+}
+```
+
+---
+
+### 4. `getOutput(filename)`
+
+**Description:**
+Fetch the output of a completed workflow using its `filename`. Outputs typically include downloadable files or results.
+
+**Parameters:**
+- `filename` *(string)*: The name of the output file.
+
+**Usage:**
+```javascript
+const output = await flowscale.getOutput('filename_prefix_58358_5WWF7GQUYF.png');
+console.log('Workflow Output:', output);
+```
+
+**Response Example:**
+```json
+{
+  "status": "success",
+  "data": {
+    "download_url": "https://runs.s3.amazonaws.com/generations/...",
+    "generation_status": "success"
+  }
+}
+```
+
+---
+
+### 5. `cancelRun(runId)`
+
+**Description:**
+Cancel a running workflow execution using its unique `runId`.
+
+**Parameters:**
+- `runId` *(string)*: The unique identifier of the running workflow.
+
+**Usage:**
+```javascript
+const result = await flowscale.cancelRun('808f34d0-ef97-4b78-a00f-1268077ea6db');
+console.log('Cancellation Result:', result);
+```
+
+**Response Example:**
+```json
+{
+  "status": "success",
+  "data": "Run cancelled successfully"
+}
+```
+
+---
+
+### 6. `getRun(runId)`
+
+**Description:**
+Retrieve detailed information about a specific workflow run.
+
+**Parameters:**
+- `runId` *(string)*: The unique identifier of the run.
+
+**Usage:**
+```javascript
+const runDetails = await flowscale.getRun('808f34d0-ef97-4b78-a00f-1268077ea6db');
+console.log('Run Details:', runDetails);
+```
+
+**Response Example:**
+```json
+{
+  "status": "success",
+  "data": {
+    "_id": "808f34d0-ef97-4b78-a00f-1268077ea6db",
+    "status": "completed",
+    "inputs": [
+      {
+        "path": "text_51536",
+        "value": "a man riding a bike"
+      }
+    ],
+    "outputs": [
+      {
+        "filename": "filename_prefix_58358_5WWF7GQUYF.png",
+        "url": "https://runs.s3.amazonaws.com/generations/..."
+      }
+    ]
+  }
+}
+```
+
+---
+
+### 7. `getRuns(groupId)`
+
+**Description:**
+Retrieve all workflow runs associated with a specific `groupId`. If no `groupId` is provided, all runs for the team are returned.
+
+**Parameters:**
+- `groupId` *(string, optional)*: The identifier for grouping runs.
+
+**Usage:**
+```javascript
+const runs = await flowscale.getRuns('test_group');
+console.log('Runs for Group:', runs);
+
+// Get all runs for the team
+const allRuns = await flowscale.getRuns();
+console.log('All Runs:', allRuns);
+```
+
+**Response Example:**
+```json
+{
+  "status": "success",
+  "data": {
+    "group_id": "test_group",
+    "count": 2,
+    "runs": [
+      {
+        "_id": "cc29a72d-75b9-4c7b-b991-ccaf2a04d6ea",
+        "status": "completed",
+        "outputs": [
+          {
+            "filename": "filename_prefix_58358_G3DRLIVVYP.png",
+            "url": "https://runs.s3.amazonaws.com/generations/..."
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## 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.
+
+---
+
+## Support
+
+For any questions or assistance, join the Flowscale community on **Discord** or refer to the [Flowscale Documentation](https://docs.flowscale.ai/).
 
-## Methods
+---
 
-- checkHealth(): Promise<HealthCheckResponse>
-- getQueue(): Promise<QueueResponse>
-- executeWorkflow(workflowId: string, data: WorkflowData, groupId?: string): Promise<ExecuteWorkflowResponse>
-- getOutput(filename: string): Promise<GetOutputResponse | null>
-- cancelRun(runId: string): Promise<CancelRunResponse>
-- getRun(runId: string): Promise<RunDetailResponse>
-- getRuns(groupId: string): Promise<RunListResponse>
+Simplify your workflow management with the Flowscale Node.js SDK. Happy coding!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowscale",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "description": "An NPM library for communicating with the Flowscale APIs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",