cyberdesk 2.2.7 → 2.2.9

package/dist/index.d.ts

@@ -30,13 +30,72 @@ export * from './client/types.gen';
 export * from './client/sdk.gen';
 export * from './client/client.gen';
 /**
- * Client options for configuring retry behavior and other settings
+ * Client options for configuring the SDK
  */
 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;
+    /** Retry configuration for transient failures (network errors, 5xx, 429, etc.). */
+    retry?: CyberdeskRetryOptions;
+    /** Idempotency configuration (auto-adds Idempotency-Key for write requests). */
+    idempotency?: CyberdeskIdempotencyOptions;
+}
+export interface CyberdeskRetryOptions {
+    /**
+     * Number of retries after the initial attempt.
+     * Total attempts = 1 + maxRetries.
+     *
+     * Default: 3
+     */
+    maxRetries?: number;
+    /**
+     * Per-attempt timeout in milliseconds.
+     *
+     * Default: 30000 (30s)
+     */
+    timeoutMs?: number;
+    /**
+     * Initial backoff delay in milliseconds (before exponential growth + jitter).
+     *
+     * Default: 250ms
+     */
+    minDelayMs?: number;
+    /**
+     * Maximum backoff delay in milliseconds.
+     *
+     * Default: 8000ms
+     */
+    maxDelayMs?: number;
+    /**
+     * Called before a retry is scheduled (useful for logging/metrics).
+     */
+    onRetry?: (info: {
+        attempt: number;
+        maxRetries: number;
+        delayMs: number;
+        reason: 'timeout' | 'network_error' | 'http_status';
+        status?: number;
+    }) => void;
+}
+export interface CyberdeskIdempotencyOptions {
+    /**
+     * Enable automatic idempotency keys for write requests (POST/PUT/PATCH/DELETE).
+     *
+     * Default: true
+     */
+    enabled?: boolean;
+    /**
+     * Header name to use.
+     *
+     * Default: 'Idempotency-Key'
+     */
+    headerName?: string;
+    /**
+     * Custom generator for idempotency keys.
+     *
+     * Default: crypto.randomUUID() (with fallback)
+     */
+    generateKey?: () => string;
 }
 /**
  * Create a Cyberdesk API client
@@ -44,7 +103,6 @@ export interface CyberdeskClientOptions {
  * @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
@@ -52,12 +110,6 @@ export interface CyberdeskClientOptions {
  * // 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, options?: CyberdeskClientOptions): {

package/dist/index.js

@@ -52,172 +52,196 @@ 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);
+// Import SDK methods from sdk.gen
+const sdk_gen_1 = require("./client/sdk.gen");
+// Export all generated types and methods for direct use
+__exportStar(require("./client/types.gen"), exports);
+__exportStar(require("./client/sdk.gen"), exports);
+__exportStar(require("./client/client.gen"), exports);
+// Configuration
+/** Default API base URL for Cyberdesk Cloud API */
+const DEFAULT_API_BASE_URL = "https://api.cyberdesk.io";
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
 }
-/**
- * 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);
+function defaultGenerateIdempotencyKey() {
+    // Browser + modern Node runtimes
+    const anyCrypto = globalThis.crypto;
+    if (anyCrypto && typeof anyCrypto.randomUUID === 'function') {
+        return anyCrypto.randomUUID();
     }
-    // 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;
+    // Fallback: not a UUID but sufficiently unique for idempotency keys
+    return `${Date.now()}-${Math.random().toString(16).slice(2)}-${Math.random().toString(16).slice(2)}`;
 }
-/**
- * Parse Retry-After header value to milliseconds
- */
-function parseRetryAfter(response) {
-    const retryAfter = response.headers.get('Retry-After');
+function parseRetryAfterMs(retryAfter) {
     if (!retryAfter)
-        return undefined;
-    // Try parsing as seconds (integer)
-    const seconds = parseInt(retryAfter, 10);
-    if (!isNaN(seconds)) {
+        return null;
+    const trimmed = retryAfter.trim();
+    if (!trimmed)
+        return null;
+    // Seconds
+    if (/^\d+$/.test(trimmed)) {
+        const seconds = Number(trimmed);
+        if (!Number.isFinite(seconds) || seconds < 0)
+            return null;
         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;
+    // HTTP date
+    const dateMs = Date.parse(trimmed);
+    if (Number.isNaN(dateMs))
+        return null;
+    const delta = dateMs - Date.now();
+    return delta > 0 ? delta : 0;
 }
-/**
- * Sleep for a specified duration
- */
-function sleep(ms) {
-    return new Promise(resolve => setTimeout(resolve, ms));
+function isWriteMethod(method) {
+    const m = method.toUpperCase();
+    return m === 'POST' || m === 'PUT' || m === 'PATCH' || m === 'DELETE';
 }
-/**
- * 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);
+function isRetryableStatus(status, response) {
+    var _a;
+    // Standard transient statuses
+    if (status === 408 || status === 429 || status === 500 || status === 502 || status === 503 || status === 504) {
+        return true;
+    }
+    // Special-case: idempotency in progress (API returns 409 + Retry-After + Idempotency-Status)
+    if (status === 409 && response) {
+        const idemStatus = (_a = response.headers.get('Idempotency-Status')) === null || _a === void 0 ? void 0 : _a.toLowerCase();
+        if (idemStatus === 'in_progress')
+            return true;
+    }
+    return false;
+}
+function createRetryingFetch(baseFetch, opts) {
+    return (input, init) => __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d, _e;
+        const retry = opts.retry;
+        const idempotency = opts.idempotency;
+        const baseMethod = ((_a = init === null || init === void 0 ? void 0 : init.method) !== null && _a !== void 0 ? _a : (input instanceof Request ? input.method : 'GET')).toUpperCase();
+        const shouldAddIdempotency = idempotency.enabled && isWriteMethod(baseMethod);
+        // Build merged headers once, and reuse across attempts
+        const headers = new Headers();
+        if (input instanceof Request) {
+            input.headers.forEach((v, k) => headers.set(k, v));
+        }
+        if (init === null || init === void 0 ? void 0 : init.headers) {
+            new Headers(init.headers).forEach((v, k) => headers.set(k, v));
+        }
+        let idempotencyKey = null;
+        if (shouldAddIdempotency) {
+            const headerName = idempotency.headerName || 'Idempotency-Key';
+            if (!headers.has(headerName)) {
+                idempotencyKey = idempotency.generateKey();
+                headers.set(headerName, idempotencyKey);
+            }
+        }
+        // If we cannot ensure idempotency for a write request, do not retry by default (unsafe).
+        const writeRequestWithoutIdempotency = isWriteMethod(baseMethod) && !(idempotencyKey || headers.has(idempotency.headerName || 'Idempotency-Key'));
+        const maxRetries = Math.max(0, retry.maxRetries);
+        const totalAttempts = 1 + maxRetries;
+        let lastError;
+        for (let attempt = 0; attempt < totalAttempts; attempt++) {
+            // Per-attempt timeout
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), retry.timeoutMs);
+            // Respect caller-provided AbortSignal, if any
+            const parentSignal = (_b = init === null || init === void 0 ? void 0 : init.signal) !== null && _b !== void 0 ? _b : (input instanceof Request ? input.signal : undefined);
+            if (parentSignal) {
+                if (parentSignal.aborted) {
+                    clearTimeout(timeout);
+                    throw new DOMException('The operation was aborted.', 'AbortError');
                 }
-                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);
+                const onAbort = () => controller.abort();
+                parentSignal.addEventListener('abort', onAbort, { once: true });
+                // Best-effort cleanup handled below when fetch resolves/rejects
+            }
+            try {
+                // Use a fresh Request object each attempt when possible (avoids body reuse issues).
+                const attemptInput = input instanceof Request ? input.clone() : input;
+                const attemptInit = Object.assign(Object.assign({}, init), { method: baseMethod, headers, signal: controller.signal });
+                const response = yield baseFetch(attemptInput, attemptInit);
+                clearTimeout(timeout);
+                if (!isRetryableStatus(response.status, response) || attempt === maxRetries) {
+                    return response;
                 }
+                if (writeRequestWithoutIdempotency) {
+                    return response;
+                }
+                const retryAfterMs = parseRetryAfterMs(response.headers.get('Retry-After'));
+                const expBackoff = Math.min(retry.maxDelayMs, retry.minDelayMs * Math.pow(2, attempt));
+                const jittered = Math.floor(Math.random() * expBackoff);
+                const delayMs = Math.max(0, Math.min(retry.maxDelayMs, retryAfterMs !== null && retryAfterMs !== void 0 ? retryAfterMs : jittered));
+                (_c = retry.onRetry) === null || _c === void 0 ? void 0 : _c.call(retry, {
+                    attempt,
+                    maxRetries,
+                    delayMs,
+                    reason: 'http_status',
+                    status: response.status,
+                });
+                yield sleep(delayMs);
+                continue;
             }
-            // This should never be reached, but TypeScript needs it
-            if (lastResponse) {
-                return lastResponse;
+            catch (err) {
+                clearTimeout(timeout);
+                // If caller aborted, don't retry
+                const isAbort = (err instanceof DOMException && err.name === 'AbortError') ||
+                    (typeof err === 'object' && err !== null && err.name === 'AbortError');
+                if (isAbort) {
+                    // If our timeout triggered, we can retry; if caller aborted, we should not.
+                    const callerAborted = (parentSignal === null || parentSignal === void 0 ? void 0 : parentSignal.aborted) === true;
+                    if (callerAborted || attempt === maxRetries || writeRequestWithoutIdempotency) {
+                        throw err;
+                    }
+                    const expBackoff = Math.min(retry.maxDelayMs, retry.minDelayMs * Math.pow(2, attempt));
+                    const delayMs = Math.floor(Math.random() * expBackoff);
+                    (_d = retry.onRetry) === null || _d === void 0 ? void 0 : _d.call(retry, { attempt, maxRetries, delayMs, reason: 'timeout' });
+                    yield sleep(delayMs);
+                    lastError = err;
+                    continue;
+                }
+                if (attempt === maxRetries || writeRequestWithoutIdempotency) {
+                    throw err;
+                }
+                const expBackoff = Math.min(retry.maxDelayMs, retry.minDelayMs * Math.pow(2, attempt));
+                const delayMs = Math.floor(Math.random() * expBackoff);
+                (_e = retry.onRetry) === null || _e === void 0 ? void 0 : _e.call(retry, { attempt, maxRetries, delayMs, reason: 'network_error' });
+                yield sleep(delayMs);
+                lastError = err;
+                continue;
             }
-            throw lastError;
-        });
-    };
+        }
+        // Should be unreachable; keep TypeScript happy
+        throw lastError !== null && lastError !== void 0 ? lastError : new Error('Request failed');
+    });
 }
-// Import SDK methods from sdk.gen
-const sdk_gen_1 = require("./client/sdk.gen");
-// Export all generated types and methods for direct use
-__exportStar(require("./client/types.gen"), exports);
-__exportStar(require("./client/sdk.gen"), exports);
-__exportStar(require("./client/client.gen"), exports);
-// Configuration
-/** Default API base URL for Cyberdesk Cloud API */
-const DEFAULT_API_BASE_URL = "https://api.cyberdesk.io";
 /**
- * Create a configured HTTP client with authentication and automatic retries
+ * Create a configured HTTP client with authentication
  *
  * @internal
  * @param apiKey - Your Cyberdesk API key
  * @param baseUrl - API base URL
  * @param options - Client configuration options
- * @returns Configured HTTP client with retry logic
+ * @returns Configured HTTP client
  */
 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);
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
+    const { fetch: customFetch } = options;
+    const baseFetch = customFetch !== null && customFetch !== void 0 ? customFetch : fetch;
+    const retryOptions = {
+        maxRetries: (_b = (_a = options.retry) === null || _a === void 0 ? void 0 : _a.maxRetries) !== null && _b !== void 0 ? _b : 3,
+        timeoutMs: (_d = (_c = options.retry) === null || _c === void 0 ? void 0 : _c.timeoutMs) !== null && _d !== void 0 ? _d : 30000,
+        minDelayMs: (_f = (_e = options.retry) === null || _e === void 0 ? void 0 : _e.minDelayMs) !== null && _f !== void 0 ? _f : 250,
+        maxDelayMs: (_h = (_g = options.retry) === null || _g === void 0 ? void 0 : _g.maxDelayMs) !== null && _h !== void 0 ? _h : 8000,
+        onRetry: (_j = options.retry) === null || _j === void 0 ? void 0 : _j.onRetry,
+    };
+    const idempotencyOptions = {
+        enabled: (_l = (_k = options.idempotency) === null || _k === void 0 ? void 0 : _k.enabled) !== null && _l !== void 0 ? _l : true,
+        headerName: (_o = (_m = options.idempotency) === null || _m === void 0 ? void 0 : _m.headerName) !== null && _o !== void 0 ? _o : 'Idempotency-Key',
+        generateKey: (_q = (_p = options.idempotency) === null || _p === void 0 ? void 0 : _p.generateKey) !== null && _q !== void 0 ? _q : defaultGenerateIdempotencyKey,
+    };
+    const wrappedFetch = createRetryingFetch(baseFetch, {
+        retry: retryOptions,
+        idempotency: idempotencyOptions,
+    });
     return (0, client_fetch_1.createClient)({
         baseUrl,
         headers: {
@@ -225,7 +249,7 @@ function createApiClient(apiKey, baseUrl = DEFAULT_API_BASE_URL, options = {}) {
             'Authorization': `Bearer ${apiKey}`,
             'Connection': 'keep-alive',
         },
-        fetch: fetchWithRetry,
+        fetch: wrappedFetch,
     });
 }
 // Helpers
@@ -240,7 +264,6 @@ 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
@@ -248,12 +271,6 @@ function toIsoUtc(value) {
  * // 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, options) {

package/package.json

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