flowforge-client 0.1.4 → 0.2.1

package/dist/index.d.mts

@@ -269,6 +269,27 @@ interface ClientOptions {
     apiKey?: string;
     /** Custom fetch implementation (for testing or custom environments) */
     fetch?: typeof fetch;
+    /**
+     * Request timeout in milliseconds.
+     * Requests will be aborted if they exceed this duration.
+     * Default: 30000 (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Retry configuration for failed requests.
+     */
+    retry?: {
+        /** Maximum number of retry attempts (default: 3) */
+        maxAttempts?: number;
+        /** Base delay in milliseconds for exponential backoff (default: 1000) */
+        baseDelay?: number;
+        /** Maximum delay in milliseconds (default: 30000) */
+        maxDelay?: number;
+        /** Whether to retry on timeout errors (default: true) */
+        retryOnTimeout?: boolean;
+        /** HTTP status codes that should trigger a retry (default: [429, 500, 502, 503, 504]) */
+        retryableStatuses?: number[];
+    };
 }
 
 /**
@@ -896,10 +917,15 @@ interface FlowForgeClient {
  * });
  * ```
  *
- * @example With API key
+ * @example With API key and timeout
  * ```ts
  * const ff = createClient('http://localhost:8000', {
- *   apiKey: process.env.FLOWFORGE_API_KEY  // ff_live_xxx
+ *   apiKey: process.env.FLOWFORGE_API_KEY,
+ *   timeout: 60000, // 60 seconds
+ *   retry: {
+ *     maxAttempts: 5,
+ *     baseDelay: 2000,
+ *   }
  * });
  * ```
  */

package/dist/index.d.ts

@@ -269,6 +269,27 @@ interface ClientOptions {
     apiKey?: string;
     /** Custom fetch implementation (for testing or custom environments) */
     fetch?: typeof fetch;
+    /**
+     * Request timeout in milliseconds.
+     * Requests will be aborted if they exceed this duration.
+     * Default: 30000 (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Retry configuration for failed requests.
+     */
+    retry?: {
+        /** Maximum number of retry attempts (default: 3) */
+        maxAttempts?: number;
+        /** Base delay in milliseconds for exponential backoff (default: 1000) */
+        baseDelay?: number;
+        /** Maximum delay in milliseconds (default: 30000) */
+        maxDelay?: number;
+        /** Whether to retry on timeout errors (default: true) */
+        retryOnTimeout?: boolean;
+        /** HTTP status codes that should trigger a retry (default: [429, 500, 502, 503, 504]) */
+        retryableStatuses?: number[];
+    };
 }
 
 /**
@@ -896,10 +917,15 @@ interface FlowForgeClient {
  * });
  * ```
  *
- * @example With API key
+ * @example With API key and timeout
  * ```ts
  * const ff = createClient('http://localhost:8000', {
- *   apiKey: process.env.FLOWFORGE_API_KEY  // ff_live_xxx
+ *   apiKey: process.env.FLOWFORGE_API_KEY,
+ *   timeout: 60000, // 60 seconds
+ *   retry: {
+ *     maxAttempts: 5,
+ *     baseDelay: 2000,
+ *   }
  * });
  * ```
  */

package/dist/index.js

@@ -733,22 +733,60 @@ var ApiKeysResource = class {
 };
 
 // src/client.ts
+var DEFAULT_TIMEOUT = 3e4;
+function anySignal(signals) {
+  const controller = new AbortController();
+  for (const signal of signals) {
+    if (signal.aborted) {
+      controller.abort(signal.reason);
+      return controller.signal;
+    }
+    signal.addEventListener(
+      "abort",
+      () => controller.abort(signal.reason),
+      { once: true }
+    );
+  }
+  return controller.signal;
+}
+var DEFAULT_RETRY = {
+  maxAttempts: 3,
+  baseDelay: 1e3,
+  maxDelay: 3e4,
+  retryOnTimeout: true,
+  retryableStatuses: [429, 500, 502, 503, 504]
+};
+function calculateBackoff(attempt, baseDelay, maxDelay) {
+  const exponentialDelay = baseDelay * Math.pow(2, attempt);
+  const jitter = 0.5 + Math.random();
+  return Math.min(exponentialDelay * jitter, maxDelay);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function createClient(baseUrl, options = {}) {
   const normalizedBaseUrl = baseUrl.replace(/\/$/, "");
   const fetchFn = options.fetch || globalThis.fetch;
-  async function request(method, path, body) {
+  const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+  const retryConfig = { ...DEFAULT_RETRY, ...options.retry };
+  async function executeRequest(method, path, body, signal) {
     const headers = {
       "Content-Type": "application/json"
     };
     if (options.apiKey) {
       headers["X-FlowForge-API-Key"] = options.apiKey;
     }
+    const timeoutController = new AbortController();
+    const timeoutId = setTimeout(() => timeoutController.abort(), timeout);
+    const combinedSignal = signal ? anySignal([signal, timeoutController.signal]) : timeoutController.signal;
     try {
       const response = await fetchFn(`${normalizedBaseUrl}/api/v1${path}`, {
         method,
         headers,
-        body: body ? JSON.stringify(body) : void 0
+        body: body ? JSON.stringify(body) : void 0,
+        signal: combinedSignal
       });
+      clearTimeout(timeoutId);
       if (!response.ok) {
         const errorBody = await response.json().catch(() => ({}));
         const error = {
@@ -763,6 +801,27 @@ function createClient(baseUrl, options = {}) {
       const data = await response.json();
       return { data, error: null };
     } catch (err) {
+      clearTimeout(timeoutId);
+      if (timeoutController.signal.aborted) {
+        const error2 = {
+          message: `Request timed out after ${timeout}ms`,
+          status: 0,
+          code: "TIMEOUT",
+          detail: { timeout },
+          name: "FlowForgeError"
+        };
+        return { data: null, error: error2 };
+      }
+      if (signal?.aborted) {
+        const error2 = {
+          message: "Request was cancelled",
+          status: 0,
+          code: "CANCELLED",
+          detail: err,
+          name: "FlowForgeError"
+        };
+        return { data: null, error: error2 };
+      }
       const error = {
         message: err instanceof Error ? err.message : "Network error",
         status: 0,
@@ -773,6 +832,46 @@ function createClient(baseUrl, options = {}) {
       return { data: null, error };
     }
   }
+  function isRetryable(error) {
+    if (error.code === "TIMEOUT" && retryConfig.retryOnTimeout) {
+      return true;
+    }
+    if (error.code === "NETWORK_ERROR") {
+      return true;
+    }
+    if (retryConfig.retryableStatuses.includes(error.status)) {
+      return true;
+    }
+    return false;
+  }
+  async function request(method, path, body) {
+    let lastError = null;
+    for (let attempt = 0; attempt < retryConfig.maxAttempts; attempt++) {
+      const result = await executeRequest(method, path, body);
+      if (result.data !== null) {
+        return result;
+      }
+      lastError = result.error;
+      if (!lastError || !isRetryable(lastError) || attempt === retryConfig.maxAttempts - 1) {
+        return result;
+      }
+      const delay = calculateBackoff(
+        attempt,
+        retryConfig.baseDelay,
+        retryConfig.maxDelay
+      );
+      await sleep(delay);
+    }
+    return {
+      data: null,
+      error: lastError || {
+        message: "Unknown error",
+        status: 0,
+        code: "UNKNOWN",
+        name: "FlowForgeError"
+      }
+    };
+  }
   return {
     events: new EventsResource(request),
     runs: new RunsResource(request),

package/dist/index.mjs

@@ -697,22 +697,60 @@ var ApiKeysResource = class {
 };
 
 // src/client.ts
+var DEFAULT_TIMEOUT = 3e4;
+function anySignal(signals) {
+  const controller = new AbortController();
+  for (const signal of signals) {
+    if (signal.aborted) {
+      controller.abort(signal.reason);
+      return controller.signal;
+    }
+    signal.addEventListener(
+      "abort",
+      () => controller.abort(signal.reason),
+      { once: true }
+    );
+  }
+  return controller.signal;
+}
+var DEFAULT_RETRY = {
+  maxAttempts: 3,
+  baseDelay: 1e3,
+  maxDelay: 3e4,
+  retryOnTimeout: true,
+  retryableStatuses: [429, 500, 502, 503, 504]
+};
+function calculateBackoff(attempt, baseDelay, maxDelay) {
+  const exponentialDelay = baseDelay * Math.pow(2, attempt);
+  const jitter = 0.5 + Math.random();
+  return Math.min(exponentialDelay * jitter, maxDelay);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function createClient(baseUrl, options = {}) {
   const normalizedBaseUrl = baseUrl.replace(/\/$/, "");
   const fetchFn = options.fetch || globalThis.fetch;
-  async function request(method, path, body) {
+  const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+  const retryConfig = { ...DEFAULT_RETRY, ...options.retry };
+  async function executeRequest(method, path, body, signal) {
     const headers = {
       "Content-Type": "application/json"
     };
     if (options.apiKey) {
       headers["X-FlowForge-API-Key"] = options.apiKey;
     }
+    const timeoutController = new AbortController();
+    const timeoutId = setTimeout(() => timeoutController.abort(), timeout);
+    const combinedSignal = signal ? anySignal([signal, timeoutController.signal]) : timeoutController.signal;
     try {
       const response = await fetchFn(`${normalizedBaseUrl}/api/v1${path}`, {
         method,
         headers,
-        body: body ? JSON.stringify(body) : void 0
+        body: body ? JSON.stringify(body) : void 0,
+        signal: combinedSignal
       });
+      clearTimeout(timeoutId);
       if (!response.ok) {
         const errorBody = await response.json().catch(() => ({}));
         const error = {
@@ -727,6 +765,27 @@ function createClient(baseUrl, options = {}) {
       const data = await response.json();
       return { data, error: null };
     } catch (err) {
+      clearTimeout(timeoutId);
+      if (timeoutController.signal.aborted) {
+        const error2 = {
+          message: `Request timed out after ${timeout}ms`,
+          status: 0,
+          code: "TIMEOUT",
+          detail: { timeout },
+          name: "FlowForgeError"
+        };
+        return { data: null, error: error2 };
+      }
+      if (signal?.aborted) {
+        const error2 = {
+          message: "Request was cancelled",
+          status: 0,
+          code: "CANCELLED",
+          detail: err,
+          name: "FlowForgeError"
+        };
+        return { data: null, error: error2 };
+      }
       const error = {
         message: err instanceof Error ? err.message : "Network error",
         status: 0,
@@ -737,6 +796,46 @@ function createClient(baseUrl, options = {}) {
       return { data: null, error };
     }
   }
+  function isRetryable(error) {
+    if (error.code === "TIMEOUT" && retryConfig.retryOnTimeout) {
+      return true;
+    }
+    if (error.code === "NETWORK_ERROR") {
+      return true;
+    }
+    if (retryConfig.retryableStatuses.includes(error.status)) {
+      return true;
+    }
+    return false;
+  }
+  async function request(method, path, body) {
+    let lastError = null;
+    for (let attempt = 0; attempt < retryConfig.maxAttempts; attempt++) {
+      const result = await executeRequest(method, path, body);
+      if (result.data !== null) {
+        return result;
+      }
+      lastError = result.error;
+      if (!lastError || !isRetryable(lastError) || attempt === retryConfig.maxAttempts - 1) {
+        return result;
+      }
+      const delay = calculateBackoff(
+        attempt,
+        retryConfig.baseDelay,
+        retryConfig.maxDelay
+      );
+      await sleep(delay);
+    }
+    return {
+      data: null,
+      error: lastError || {
+        message: "Unknown error",
+        status: 0,
+        code: "UNKNOWN",
+        name: "FlowForgeError"
+      }
+    };
+  }
   return {
     events: new EventsResource(request),
     runs: new RunsResource(request),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowforge-client",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "description": "TypeScript client for FlowForge workflow orchestration",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -24,12 +24,17 @@
   ],
   "license": "MIT",
   "devDependencies": {
+    "@vitest/coverage-v8": "^2.0.0",
     "tsup": "^8.0.0",
-    "typescript": "^5.3.0"
+    "typescript": "^5.3.0",
+    "vitest": "^2.0.0"
   },
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   }
 }