wavespeed 0.2.1 → 0.2.3

package/README.md

@@ -18,6 +18,10 @@
 
 ---
 
+## Introduction
+
+**WaveSpeedAI** JavaScript/TypeScript SDK — Official JS/TS SDK for **WaveSpeedAI** inference platform. This library offers a clean, unified, and high-performance API for your applications.
+
 ## Installation
 
 ```bash
@@ -109,6 +113,22 @@ const url = await wavespeed.upload("/path/to/image.png");
 console.log(url);
 ```
 
+### Getting Task ID and Debug Information
+
+If you need access to the task ID for logging, tracking, or debugging, use `runNoThrow()` instead of `run()`. This method returns detailed information and does not throw exceptions:
+
+```javascript
+const result = await client.runNoThrow(model, input);
+
+if (result.outputs) {
+  console.log("Success:", result.outputs);
+  console.log("Task ID:", result.detail.taskId);  // For tracking/debugging
+} else {
+  console.log("Failed:", result.detail.error);
+  console.log("Task ID:", result.detail.taskId);  // Still available on failure
+}
+```
+
 ## Running Tests
 
 ```bash

package/dist/api/client.d.ts

@@ -10,6 +10,23 @@ export interface RunOptions {
     enableSyncMode?: boolean;
     maxRetries?: number;
 }
+/**
+ * Detail information for runNoThrow result.
+ */
+export interface RunDetail {
+    taskId: string;
+    status: 'completed' | 'failed';
+    model: string;
+    error?: string;
+    createdAt?: string;
+}
+/**
+ * Result interface for runNoThrow method.
+ */
+export interface RunNoThrowResult {
+    outputs: any[] | null;
+    detail: RunDetail;
+}
 /**
  * WaveSpeed API client.
  *
@@ -132,6 +149,38 @@ export declare class Client {
      *     Error: If the prediction times out.
      */
     run(model: string, input?: Record<string, any>, options?: RunOptions): Promise<Record<string, any>>;
+    /**
+     * Run a model and wait for the output (no-throw version).
+     *
+     * This method is similar to run() but does not throw exceptions.
+     * Instead, it returns a result object with outputs (null on failure) and detail information.
+     * The detail object always contains the taskId, which is useful for debugging and tracking.
+     *
+     * Args:
+     *     model: Model identifier (e.g., "wavespeed-ai/flux-dev").
+     *     input: Input parameters for the model.
+     *     options.timeout: Maximum time to wait for completion (undefined = no timeout).
+     *     options.pollInterval: Interval between status checks in seconds.
+     *     options.enableSyncMode: If true, use synchronous mode (single request).
+     *     options.maxRetries: Maximum task-level retries (overrides client setting).
+     *
+     * Returns:
+     *     Object containing:
+     *       - outputs: Array of model outputs (null if failed)
+     *       - detail: Object with taskId, status, error (if any), and other metadata
+     *
+     * Example:
+     *     const result = await client.runNoThrow("wavespeed-ai/z-image/turbo", { prompt: "Cat" });
+     *
+     *     if (result.outputs) {
+     *       console.log("Success:", result.outputs);
+     *       console.log("Task ID:", result.detail.taskId);
+     *     } else {
+     *       console.log("Failed:", result.detail.error);
+     *       console.log("Task ID:", result.detail.taskId);
+     *     }
+     */
+    runNoThrow(model: string, input?: Record<string, any>, options?: RunOptions): Promise<RunNoThrowResult>;
     /**
      * Upload a file to WaveSpeed.
      *

package/dist/api/client.js

@@ -319,6 +319,131 @@ class Client {
         }
         throw new Error(`All ${taskRetries + 1} attempts failed`);
     }
+    /**
+     * Run a model and wait for the output (no-throw version).
+     *
+     * This method is similar to run() but does not throw exceptions.
+     * Instead, it returns a result object with outputs (null on failure) and detail information.
+     * The detail object always contains the taskId, which is useful for debugging and tracking.
+     *
+     * Args:
+     *     model: Model identifier (e.g., "wavespeed-ai/flux-dev").
+     *     input: Input parameters for the model.
+     *     options.timeout: Maximum time to wait for completion (undefined = no timeout).
+     *     options.pollInterval: Interval between status checks in seconds.
+     *     options.enableSyncMode: If true, use synchronous mode (single request).
+     *     options.maxRetries: Maximum task-level retries (overrides client setting).
+     *
+     * Returns:
+     *     Object containing:
+     *       - outputs: Array of model outputs (null if failed)
+     *       - detail: Object with taskId, status, error (if any), and other metadata
+     *
+     * Example:
+     *     const result = await client.runNoThrow("wavespeed-ai/z-image/turbo", { prompt: "Cat" });
+     *
+     *     if (result.outputs) {
+     *       console.log("Success:", result.outputs);
+     *       console.log("Task ID:", result.detail.taskId);
+     *     } else {
+     *       console.log("Failed:", result.detail.error);
+     *       console.log("Task ID:", result.detail.taskId);
+     *     }
+     */
+    async runNoThrow(model, input, options) {
+        var _a, _b, _c, _d, _e;
+        const taskRetries = (_a = options === null || options === void 0 ? void 0 : options.maxRetries) !== null && _a !== void 0 ? _a : this.maxRetries;
+        const timeout = (_b = options === null || options === void 0 ? void 0 : options.timeout) !== null && _b !== void 0 ? _b : this.timeout;
+        const pollInterval = (_c = options === null || options === void 0 ? void 0 : options.pollInterval) !== null && _c !== void 0 ? _c : 1.0;
+        const enableSyncMode = (_d = options === null || options === void 0 ? void 0 : options.enableSyncMode) !== null && _d !== void 0 ? _d : false;
+        for (let attempt = 0; attempt <= taskRetries; attempt++) {
+            try {
+                const [requestId, syncResult] = await this._submit(model, input, enableSyncMode, timeout);
+                if (enableSyncMode) {
+                    // In sync mode, extract outputs from the result
+                    const data = (syncResult === null || syncResult === void 0 ? void 0 : syncResult.data) || {};
+                    const status = data.status;
+                    const taskId = data.id || 'unknown';
+                    if (status !== 'completed') {
+                        const error = data.error || 'Unknown error';
+                        return {
+                            outputs: null,
+                            detail: {
+                                taskId,
+                                status: 'failed',
+                                model,
+                                error,
+                                createdAt: data.created_at
+                            }
+                        };
+                    }
+                    return {
+                        outputs: data.outputs || [],
+                        detail: {
+                            taskId,
+                            status: 'completed',
+                            model,
+                            createdAt: data.created_at
+                        }
+                    };
+                }
+                if (requestId) {
+                    const result = await this._wait(requestId, timeout, pollInterval);
+                    return {
+                        outputs: result.outputs,
+                        detail: {
+                            taskId: requestId,
+                            status: 'completed',
+                            model
+                        }
+                    };
+                }
+                // Should not reach here
+                return {
+                    outputs: null,
+                    detail: {
+                        taskId: 'unknown',
+                        status: 'failed',
+                        model,
+                        error: 'Invalid response from _submit'
+                    }
+                };
+            }
+            catch (error) {
+                const isRetryable = this._isRetryableError(error);
+                // If not retryable or last attempt, return error result
+                if (!isRetryable || attempt >= taskRetries) {
+                    // Try to extract taskId from error message
+                    const taskIdMatch = (_e = error.message) === null || _e === void 0 ? void 0 : _e.match(/task_id: ([a-f0-9-]+)/);
+                    const taskId = taskIdMatch ? taskIdMatch[1] : 'unknown';
+                    return {
+                        outputs: null,
+                        detail: {
+                            taskId,
+                            status: 'failed',
+                            model,
+                            error: error.message || String(error)
+                        }
+                    };
+                }
+                // Retry
+                console.log(`Task attempt ${attempt + 1}/${taskRetries + 1} failed: ${error}`);
+                const delay = this.retryInterval * (attempt + 1) * 1000;
+                console.log(`Retrying in ${delay}ms...`);
+                await new Promise((resolve) => setTimeout(resolve, delay));
+            }
+        }
+        // Should not reach here, but just in case
+        return {
+            outputs: null,
+            detail: {
+                taskId: 'unknown',
+                status: 'failed',
+                model,
+                error: `All ${taskRetries + 1} attempts failed`
+            }
+        };
+    }
     /**
      * Upload a file to WaveSpeed.
      *

package/dist/api/index.d.ts

@@ -18,9 +18,9 @@
  *     console.log(url);
  */
 import { Client } from './client';
-import type { RunOptions } from './client';
+import type { RunOptions, RunDetail, RunNoThrowResult } from './client';
 export { Client };
-export type { RunOptions };
+export type { RunOptions, RunDetail, RunNoThrowResult };
 /**
  * Run a model and wait for the output.
  *

package/dist/index.d.ts

@@ -16,7 +16,7 @@
 import { version } from './version';
 import './config';
 import { Client, run, upload } from './api';
-import type { RunOptions } from './api/client';
+import type { RunOptions, RunDetail, RunNoThrowResult } from './api/client';
 export { version, Client, run, upload };
-export type { RunOptions };
+export type { RunOptions, RunDetail, RunNoThrowResult };
 export default Client;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wavespeed",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "WaveSpeed Client SDK for Wavespeed API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",