cyberdesk 2.2.4 → 2.2.6

package/dist/index.d.ts

@@ -29,20 +29,38 @@ import { type MachineResponse, type MachinePoolUpdate, type PoolResponse, type P
 export * from './client/types.gen';
 export * from './client/sdk.gen';
 export * from './client/client.gen';
+/**
+ * Client options for configuring retry behavior and other settings
+ */
+export interface CyberdeskClientOptions {
+    /** Maximum number of retry attempts (default: 2, meaning 3 total attempts) */
+    maxRetries?: number;
+    /** Custom fetch implementation (for testing or advanced use cases) */
+    fetch?: typeof fetch;
+}
 /**
  * Create a Cyberdesk API client
  *
  * @param apiKey - Your Cyberdesk API key
  * @param baseUrl - Optional API base URL (defaults to https://api.cyberdesk.io)
+ * @param options - Optional client configuration
+ * @param options.maxRetries - Maximum retry attempts for failed requests (default: 2)
  * @returns Configured client with all API endpoints
  *
  * @example
  * ```typescript
+ * // Basic usage
  * const client = createCyberdeskClient('your-api-key');
  * const machines = await client.machines.list();
+ *
+ * // With custom retry configuration
+ * const client = createCyberdeskClient('your-api-key', undefined, { maxRetries: 3 });
+ *
+ * // Disable retries
+ * const client = createCyberdeskClient('your-api-key', undefined, { maxRetries: 0 });
  * ```
  */
-export declare function createCyberdeskClient(apiKey: string, baseUrl?: string): {
+export declare function createCyberdeskClient(apiKey: string, baseUrl?: string, options?: CyberdeskClientOptions): {
     machines: {
         /**
          * List machines with optional filtering

package/dist/index.js

@@ -52,6 +52,150 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createCyberdeskClient = createCyberdeskClient;
 const client_fetch_1 = require("@hey-api/client-fetch");
+// ============================================================================
+// Retry Configuration (Stripe SDK-style)
+// ============================================================================
+/** Default number of retry attempts (2 retries = 3 total attempts, like Stripe) */
+const DEFAULT_MAX_RETRIES = 2;
+/** Initial retry delay in milliseconds */
+const INITIAL_RETRY_DELAY_MS = 500;
+/** Maximum retry delay in milliseconds */
+const MAX_RETRY_DELAY_MS = 5000;
+/** HTTP status codes that should trigger a retry */
+const RETRYABLE_STATUS_CODES = new Set([
+    408, // Request Timeout
+    409, // Conflict (can be retried with idempotency)
+    429, // Too Many Requests
+    500, // Internal Server Error
+    502, // Bad Gateway
+    503, // Service Unavailable
+    504, // Gateway Timeout
+]);
+/**
+ * Determines if an error is a retryable network error
+ *
+ * Note: AbortError (from AbortController.abort()) is NOT retried because:
+ * - It indicates intentional cancellation by the caller
+ * - The abort signal remains aborted, so retries would fail immediately
+ * - Retrying would waste attempts and delay error propagation
+ */
+function isNetworkError(error) {
+    // AbortError means intentional cancellation - don't retry
+    if (error instanceof DOMException && error.name === 'AbortError') {
+        return false;
+    }
+    if (error instanceof TypeError) {
+        const message = error.message.toLowerCase();
+        return (message.includes('fetch') ||
+            message.includes('network') ||
+            message.includes('failed') ||
+            message.includes('timeout'));
+    }
+    return false;
+}
+/**
+ * Determines if a response status code should trigger a retry
+ */
+function shouldRetryResponse(response) {
+    return RETRYABLE_STATUS_CODES.has(response.status);
+}
+/**
+ * Calculate delay for exponential backoff with full jitter (Stripe-style)
+ *
+ * Formula: min(cap, random(0, base * 2^attempt))
+ * This provides better distribution than adding jitter to exponential backoff
+ */
+function calculateRetryDelay(attempt, retryAfterMs) {
+    if (retryAfterMs && retryAfterMs > 0) {
+        // Respect server's Retry-After header, but cap it
+        return Math.min(retryAfterMs, MAX_RETRY_DELAY_MS);
+    }
+    // Full jitter exponential backoff
+    const exponentialDelay = INITIAL_RETRY_DELAY_MS * Math.pow(2, attempt);
+    const maxDelay = Math.min(exponentialDelay, MAX_RETRY_DELAY_MS);
+    return Math.random() * maxDelay;
+}
+/**
+ * Parse Retry-After header value to milliseconds
+ */
+function parseRetryAfter(response) {
+    const retryAfter = response.headers.get('Retry-After');
+    if (!retryAfter)
+        return undefined;
+    // Try parsing as seconds (integer)
+    const seconds = parseInt(retryAfter, 10);
+    if (!isNaN(seconds)) {
+        return seconds * 1000;
+    }
+    // Try parsing as HTTP date
+    const date = Date.parse(retryAfter);
+    if (!isNaN(date)) {
+        return Math.max(0, date - Date.now());
+    }
+    return undefined;
+}
+/**
+ * Sleep for a specified duration
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Creates a fetch wrapper with automatic retry logic
+ *
+ * Implements Stripe-style retry behavior:
+ * - Retries on network errors (connection failures, timeouts)
+ * - Retries on 5xx server errors and 429 (rate limit)
+ * - Does NOT retry on 4xx client errors (except 408, 409, 429)
+ * - Uses exponential backoff with full jitter
+ * - Respects Retry-After headers
+ */
+function createRetryFetch(maxRetries = DEFAULT_MAX_RETRIES) {
+    return function retryFetch(input, init) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let lastError;
+            let lastResponse;
+            for (let attempt = 0; attempt <= maxRetries; attempt++) {
+                try {
+                    // Use globalThis.fetch directly bound to avoid "Illegal invocation"
+                    const response = yield globalThis.fetch(input, init);
+                    // Success - return immediately
+                    if (!shouldRetryResponse(response)) {
+                        return response;
+                    }
+                    // Store response for potential retry
+                    lastResponse = response;
+                    // Don't retry on last attempt
+                    if (attempt === maxRetries) {
+                        return response;
+                    }
+                    // Calculate delay with Retry-After header support
+                    const retryAfterMs = parseRetryAfter(response);
+                    const delay = calculateRetryDelay(attempt, retryAfterMs);
+                    yield sleep(delay);
+                }
+                catch (error) {
+                    lastError = error;
+                    // Only retry on network errors
+                    if (!isNetworkError(error)) {
+                        throw error;
+                    }
+                    // Don't retry on last attempt
+                    if (attempt === maxRetries) {
+                        throw error;
+                    }
+                    const delay = calculateRetryDelay(attempt);
+                    yield sleep(delay);
+                }
+            }
+            // This should never be reached, but TypeScript needs it
+            if (lastResponse) {
+                return lastResponse;
+            }
+            throw lastError;
+        });
+    };
+}
 // Import SDK methods from sdk.gen
 const sdk_gen_1 = require("./client/sdk.gen");
 // Export all generated types and methods for direct use
@@ -62,14 +206,18 @@ __exportStar(require("./client/client.gen"), exports);
 /** Default API base URL for Cyberdesk Cloud API */
 const DEFAULT_API_BASE_URL = "https://api.cyberdesk.io";
 /**
- * Create a configured HTTP client with authentication
+ * Create a configured HTTP client with authentication and automatic retries
  *
  * @internal
  * @param apiKey - Your Cyberdesk API key
  * @param baseUrl - API base URL
- * @returns Configured HTTP client
+ * @param options - Client configuration options
+ * @returns Configured HTTP client with retry logic
  */
-function createApiClient(apiKey, baseUrl = DEFAULT_API_BASE_URL) {
+function createApiClient(apiKey, baseUrl = DEFAULT_API_BASE_URL, options = {}) {
+    const { maxRetries = DEFAULT_MAX_RETRIES, fetch: customFetch } = options;
+    // Use custom fetch if provided, otherwise create retry-enabled fetch
+    const fetchWithRetry = customFetch !== null && customFetch !== void 0 ? customFetch : createRetryFetch(maxRetries);
     return (0, client_fetch_1.createClient)({
         baseUrl,
         headers: {
@@ -77,6 +225,7 @@ function createApiClient(apiKey, baseUrl = DEFAULT_API_BASE_URL) {
             'Authorization': `Bearer ${apiKey}`,
             'Connection': 'keep-alive',
         },
+        fetch: fetchWithRetry,
     });
 }
 // Helpers
@@ -90,16 +239,25 @@ function toIsoUtc(value) {
  *
  * @param apiKey - Your Cyberdesk API key
  * @param baseUrl - Optional API base URL (defaults to https://api.cyberdesk.io)
+ * @param options - Optional client configuration
+ * @param options.maxRetries - Maximum retry attempts for failed requests (default: 2)
  * @returns Configured client with all API endpoints
  *
  * @example
  * ```typescript
+ * // Basic usage
  * const client = createCyberdeskClient('your-api-key');
  * const machines = await client.machines.list();
+ *
+ * // With custom retry configuration
+ * const client = createCyberdeskClient('your-api-key', undefined, { maxRetries: 3 });
+ *
+ * // Disable retries
+ * const client = createCyberdeskClient('your-api-key', undefined, { maxRetries: 0 });
  * ```
  */
-function createCyberdeskClient(apiKey, baseUrl) {
-    const client = createApiClient(apiKey, baseUrl);
+function createCyberdeskClient(apiKey, baseUrl, options) {
+    const client = createApiClient(apiKey, baseUrl, options);
     return {
         // Machine endpoints
         machines: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cyberdesk",
-  "version": "2.2.4",
+  "version": "2.2.6",
   "description": "The official TypeScript SDK for Cyberdesk",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",