@adaptic/utils 0.0.979 → 0.0.980

package/dist/index.cjs

@@ -3801,6 +3801,419 @@ class AlpacaMarketDataAPI extends require$$0$1.EventEmitter {
 // Export the singleton instance
 const marketDataAPI = AlpacaMarketDataAPI.getInstance();
 
+const DEFAULT_RETRY_CONFIG = {
+    maxRetries: 3,
+    baseDelayMs: 1000,
+    maxDelayMs: 30000,
+    retryableStatusCodes: [429, 500, 502, 503, 504],
+    retryOnNetworkError: true,
+};
+/**
+ * Node.js / undici / system error codes that represent transient network
+ * conditions. Present on `error.code` for net/http/dns/undici errors.
+ */
+const RETRYABLE_ERROR_CODES = new Set([
+    "ETIMEDOUT",
+    "ESOCKETTIMEDOUT",
+    "ECONNRESET",
+    "ECONNREFUSED",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "EAI_AGAIN",
+    "EPIPE",
+    "ECONNABORTED",
+    "ENOTFOUND",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_BODY_TIMEOUT",
+    "UND_ERR_SOCKET",
+    "UND_ERR_CLOSED",
+    "UND_ERR_REQ_CONTENT_LENGTH_MISMATCH",
+]);
+/**
+ * Error constructor names / `error.name` values that indicate transient
+ * abort / timeout conditions.
+ */
+const RETRYABLE_ERROR_NAMES = new Set([
+    "AbortError",
+    "TimeoutError",
+    "FetchError",
+    "RequestTimeoutError",
+    "ConnectTimeoutError",
+    "HeadersTimeoutError",
+    "BodyTimeoutError",
+]);
+/**
+ * Message-pattern fallback for libraries that discard error codes/names but
+ * preserve text (e.g., some Apollo/axios wrappers).
+ */
+const RETRYABLE_MESSAGE_PATTERNS = [
+    /aborted/i,
+    /timeout/i,
+    /timed out/i,
+    /network error/i,
+    /socket hang up/i,
+    /connection (reset|refused|closed)/i,
+    /ECONNRESET/,
+    /ETIMEDOUT/,
+    /ECONNREFUSED/,
+    /EAI_AGAIN/,
+    /UND_ERR_/,
+];
+/**
+ * Walks the `error.cause` chain (capped to avoid cycles) and tests whether
+ * any link along the chain looks like a transient network error. Modern APIs
+ * (undici, fetch, Apollo Client 3.8+) wrap the root network failure as a
+ * `.cause`, so the surface `Error` may report a generic message while the
+ * actionable signal lives one or more levels deeper.
+ *
+ * Exported for use by downstream consumers (engine services, per-call catch
+ * blocks, application-level loggers) that need to demote recoverable
+ * transient errors from ERROR to WARN. Aligns the whole stack on a single
+ * canonical classifier so MassiveAPI, AlpacaAPI, and application-layer
+ * retry handlers all treat the same network blips identically.
+ */
+function isTransientNetworkError(error) {
+    const MAX_CAUSE_DEPTH = 6;
+    let current = error;
+    for (let depth = 0; depth < MAX_CAUSE_DEPTH && current; depth++) {
+        if (current instanceof Error || typeof current === "object") {
+            const err = current;
+            if (typeof err.name === "string" && RETRYABLE_ERROR_NAMES.has(err.name)) {
+                return true;
+            }
+            if (typeof err.code === "string" && RETRYABLE_ERROR_CODES.has(err.code)) {
+                return true;
+            }
+            if (typeof err.message === "string") {
+                for (const pattern of RETRYABLE_MESSAGE_PATTERNS) {
+                    if (pattern.test(err.message)) {
+                        return true;
+                    }
+                }
+            }
+            current = err.cause;
+        }
+        else {
+            break;
+        }
+    }
+    return false;
+}
+/**
+ * Analyzes an error and determines if it's retryable.
+ * @param error - The error to analyze
+ * @param response - Optional Response object for HTTP errors
+ * @param config - Retry configuration
+ * @returns Structured error details
+ */
+function analyzeError(error, response, config) {
+    // Handle Response objects with error status codes
+    if (response && !response.ok) {
+        const status = response.status;
+        // Rate limit errors - always retryable
+        if (status === 429) {
+            const retryAfterHeader = response.headers.get("Retry-After");
+            const retryAfter = retryAfterHeader
+                ? parseInt(retryAfterHeader, 10) * 1000
+                : undefined;
+            return {
+                type: "RATE_LIMIT",
+                reason: "Rate limit exceeded",
+                status,
+                retryAfter,
+                isRetryable: true,
+            };
+        }
+        // Authentication errors - never retry
+        if (status === 401 || status === 403) {
+            return {
+                type: "AUTH_ERROR",
+                reason: status === 401
+                    ? "Authentication failed - invalid credentials"
+                    : "Access forbidden - insufficient permissions",
+                status,
+                isRetryable: false,
+            };
+        }
+        // Server errors - check if in retryable list
+        if (status >= 500 && status < 600) {
+            return {
+                type: "SERVER_ERROR",
+                reason: `Server error (${status})`,
+                status,
+                isRetryable: config.retryableStatusCodes.includes(status),
+            };
+        }
+        // Other client errors - never retry
+        if (status >= 400 && status < 500) {
+            return {
+                type: "CLIENT_ERROR",
+                reason: `Client error (${status})`,
+                status,
+                isRetryable: false,
+            };
+        }
+    }
+    // Handle network errors (TypeError from fetch API)
+    if (error instanceof TypeError && error.message.includes("fetch")) {
+        return {
+            type: "NETWORK_ERROR",
+            reason: "Network connectivity issue",
+            status: null,
+            isRetryable: config.retryOnNetworkError,
+        };
+    }
+    // Handle transient network conditions: AbortError, TimeoutError,
+    // Node/undici error codes (ETIMEDOUT, ECONNRESET, UND_ERR_*), and
+    // wrapped failures exposed via error.cause. This catches the broad class
+    // of infrastructure flakes that the TypeError-only check above misses.
+    if (isTransientNetworkError(error)) {
+        const reason = error instanceof Error ? error.message : "Transient network error";
+        return {
+            type: "NETWORK_ERROR",
+            reason,
+            status: null,
+            isRetryable: config.retryOnNetworkError,
+        };
+    }
+    // Handle error objects with messages
+    if (error instanceof Error) {
+        // Parse error messages that might contain status information
+        if (error.message.includes("429") || error.message.includes("RATE_LIMIT")) {
+            const match = error.message.match(/RATE_LIMIT: 429:(\d+)/);
+            const retryAfter = match ? parseInt(match[1], 10) : undefined;
+            return {
+                type: "RATE_LIMIT",
+                reason: "Rate limit exceeded",
+                status: 429,
+                retryAfter,
+                isRetryable: true,
+            };
+        }
+        if (error.message.includes("401") ||
+            error.message.includes("403") ||
+            error.message.includes("AUTH_ERROR")) {
+            const status = error.message.includes("401") ? 401 : 403;
+            return {
+                type: "AUTH_ERROR",
+                reason: `Authentication error (${status})`,
+                status,
+                isRetryable: false,
+            };
+        }
+        if (error.message.includes("SERVER_ERROR") ||
+            error.message.match(/50[0-9]/)) {
+            const statusMatch = error.message.match(/50[0-9]/);
+            const status = statusMatch ? parseInt(statusMatch[0], 10) : 500;
+            return {
+                type: "SERVER_ERROR",
+                reason: `Server error (${status})`,
+                status,
+                isRetryable: config.retryableStatusCodes.includes(status),
+            };
+        }
+        if (error.message.includes("network") ||
+            error.message.includes("NETWORK_ERROR")) {
+            return {
+                type: "NETWORK_ERROR",
+                reason: error.message,
+                status: null,
+                isRetryable: config.retryOnNetworkError,
+            };
+        }
+    }
+    // Unknown error - not retryable by default for safety
+    return {
+        type: "UNKNOWN",
+        reason: error instanceof Error ? error.message : String(error),
+        status: null,
+        isRetryable: false,
+    };
+}
+/**
+ * Calculates the delay before the next retry attempt using exponential backoff with jitter.
+ * @param attempt - Current attempt number (1-indexed)
+ * @param baseDelay - Base delay in milliseconds
+ * @param maxDelay - Maximum delay in milliseconds
+ * @returns Delay in milliseconds
+ */
+function calculateBackoff(attempt, baseDelay, maxDelay) {
+    // Exponential backoff: baseDelay * 2^(attempt-1)
+    const exponentialDelay = baseDelay * Math.pow(2, attempt - 1);
+    // Cap at maxDelay
+    const cappedDelay = Math.min(exponentialDelay, maxDelay);
+    // Add jitter (random value between 0% and 25% of the delay)
+    const jitter = Math.random() * cappedDelay * 0.25;
+    return Math.floor(cappedDelay + jitter);
+}
+/**
+ * Wraps an async function with retry logic and exponential backoff.
+ *
+ * This utility handles transient errors in external API calls by automatically retrying
+ * failed requests with intelligent backoff strategies. It respects rate limit headers,
+ * fails fast on non-retryable errors, and provides detailed logging.
+ *
+ * @template T - The return type of the wrapped function
+ * @param fn - The async function to wrap with retry logic
+ * @param config - Retry configuration (merged with defaults)
+ * @param label - A descriptive label for logging (e.g., 'Massive.fetchTickerInfo')
+ * @returns A promise that resolves to the function's return value
+ * @throws The last error encountered if all retries are exhausted
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with defaults
+ * const data = await withRetry(
+ *   async () => fetch('https://api.example.com/data'),
+ *   {},
+ *   'ExampleAPI.fetchData'
+ * );
+ *
+ * // Custom configuration for rate-limited API
+ * const result = await withRetry(
+ *   async () => alphaVantageAPI.getQuote(symbol),
+ *   {
+ *     maxRetries: 5,
+ *     baseDelayMs: 5000,
+ *     maxDelayMs: 60000,
+ *     onRetry: (attempt, error) => {
+ *       getLogger().info(`Retry ${attempt} after error:`, error);
+ *     }
+ *   },
+ *   'AlphaVantage.getQuote'
+ * );
+ * ```
+ */
+async function withRetry(fn, config = {}, label = "unknown") {
+    const fullConfig = { ...DEFAULT_RETRY_CONFIG, ...config };
+    let lastError;
+    for (let attempt = 1; attempt <= fullConfig.maxRetries; attempt++) {
+        try {
+            const result = await fn();
+            // If we succeeded after retries, log it
+            if (attempt > 1) {
+                getLogger().info(`[${label}] Succeeded on attempt ${attempt}/${fullConfig.maxRetries}`);
+            }
+            return result;
+        }
+        catch (error) {
+            lastError = error;
+            // If this is the last attempt, throw the error.
+            // Transient network classes (undici/fetch timeouts, ECONNRESET,
+            // AbortError, etc.) are self-healing at the upstream retry layer —
+            // the caller re-invokes on the next refresh/poll tick. Logging them
+            // at ERROR produces alert noise that does not represent actionable
+            // failures. Demote the transient class to WARN with a recovery hint;
+            // reserve ERROR for non-transient final failures (auth, schema,
+            // contract violations, unknown classes).
+            if (attempt === fullConfig.maxRetries) {
+                const isTransient = isTransientNetworkError(error);
+                const logMeta = {
+                    error: error instanceof Error ? error.message : String(error),
+                    attempts: fullConfig.maxRetries,
+                    timestamp: new Date().toISOString(),
+                    ...(isTransient
+                        ? {
+                            transient: true,
+                            recoveryHint: "Upstream caller should retry on next cycle",
+                        }
+                        : {}),
+                };
+                if (isTransient) {
+                    getLogger().warn(`[${label}] Failed after ${fullConfig.maxRetries} attempts (transient)`, logMeta);
+                }
+                else {
+                    getLogger().error(`[${label}] Failed after ${fullConfig.maxRetries} attempts`, logMeta);
+                }
+                throw error;
+            }
+            // Analyze the error to determine if we should retry
+            const response = error instanceof Response ? error : null;
+            const errorDetails = analyzeError(error, response, fullConfig);
+            // If error is not retryable, fail immediately
+            if (!errorDetails.isRetryable) {
+                getLogger().error(`[${label}] Non-retryable error (${errorDetails.type})`, {
+                    reason: errorDetails.reason,
+                    status: errorDetails.status,
+                    timestamp: new Date().toISOString(),
+                });
+                throw error;
+            }
+            // Calculate delay for next retry
+            let delayMs;
+            if (errorDetails.type === "RATE_LIMIT" && errorDetails.retryAfter) {
+                // Use Retry-After header if available
+                delayMs = errorDetails.retryAfter;
+            }
+            else if (errorDetails.type === "RATE_LIMIT") {
+                // For rate limits without Retry-After, use a longer minimum delay
+                delayMs = Math.max(calculateBackoff(attempt, fullConfig.baseDelayMs, fullConfig.maxDelayMs), 5000);
+            }
+            else {
+                // Standard exponential backoff with jitter
+                delayMs = calculateBackoff(attempt, fullConfig.baseDelayMs, fullConfig.maxDelayMs);
+            }
+            // Log the retry attempt
+            getLogger().warn(`[${label}] Attempt ${attempt}/${fullConfig.maxRetries} failed: ${errorDetails.reason}. Retrying in ${delayMs}ms...`, {
+                attemptNumber: attempt,
+                totalRetries: fullConfig.maxRetries,
+                errorType: errorDetails.type,
+                httpStatus: errorDetails.status,
+                retryDelay: delayMs,
+                timestamp: new Date().toISOString(),
+            });
+            // Call the optional retry callback
+            if (fullConfig.onRetry) {
+                fullConfig.onRetry(attempt, error);
+            }
+            // Wait before retrying
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+    }
+    // This should never be reached due to the throw in the last attempt,
+    // but TypeScript needs this to satisfy the return type
+    throw lastError;
+}
+/**
+ * API-specific retry configurations for different external services.
+ * These configurations are tuned based on each API's rate limits and characteristics.
+ */
+const API_RETRY_CONFIGS = {
+    /** Massive.com API - 5 requests/second rate limit */
+    MASSIVE: {
+        maxRetries: 3,
+        baseDelayMs: 1000,
+        maxDelayMs: 30000,
+        retryableStatusCodes: [429, 500, 502, 503, 504],
+        retryOnNetworkError: true,
+    },
+    /** Alpha Vantage API - 5 requests/minute rate limit (more strict) */
+    ALPHA_VANTAGE: {
+        maxRetries: 5,
+        baseDelayMs: 5000,
+        maxDelayMs: 60000,
+        retryableStatusCodes: [429, 500, 502, 503, 504],
+        retryOnNetworkError: true,
+    },
+    /** Alpaca API - generally reliable, shorter retry window */
+    ALPACA: {
+        maxRetries: 3,
+        baseDelayMs: 1000,
+        maxDelayMs: 30000,
+        retryableStatusCodes: [429, 500, 502, 503, 504],
+        retryOnNetworkError: true,
+    },
+    /** Generic crypto API configuration */
+    CRYPTO: {
+        maxRetries: 3,
+        baseDelayMs: 1000,
+        maxDelayMs: 30000,
+        retryableStatusCodes: [429, 500, 502, 503, 504],
+        retryOnNetworkError: true,
+    },
+};
+
 const limitPriceSlippagePercent100 = 0.1; // 0.1%
 /**
 Websocket example
@@ -4111,9 +4524,20 @@ class AlpacaTradingAPI {
         }
         catch (err) {
             const error = err;
+            const isTransient = isTransientNetworkError(err);
+            // Transient fetch failures (timeouts, connection resets, undici
+            // aborts) are recoverable at the caller's next cycle; log at WARN
+            // and annotate for observability filters. Non-transient errors
+            // (4xx/auth/schema) stay at ERROR for operator attention.
             this.log(`Error in makeRequest: ${error.message}. Url: ${url}`, {
                 source: "AlpacaAPI",
-                type: "error",
+                type: isTransient ? "warn" : "error",
+                metadata: isTransient
+                    ? {
+                        transient: true,
+                        recoveryHint: "Upstream caller should retry on next cycle",
+                    }
+                    : undefined,
             });
             throw error;
         }
@@ -5597,392 +6021,6 @@ async function createLimitOrder(auth, params = {
     });
 }
 
-const DEFAULT_RETRY_CONFIG = {
-    maxRetries: 3,
-    baseDelayMs: 1000,
-    maxDelayMs: 30000,
-    retryableStatusCodes: [429, 500, 502, 503, 504],
-    retryOnNetworkError: true,
-};
-/**
- * Node.js / undici / system error codes that represent transient network
- * conditions. Present on `error.code` for net/http/dns/undici errors.
- */
-const RETRYABLE_ERROR_CODES = new Set([
-    "ETIMEDOUT",
-    "ESOCKETTIMEDOUT",
-    "ECONNRESET",
-    "ECONNREFUSED",
-    "EHOSTUNREACH",
-    "ENETUNREACH",
-    "EAI_AGAIN",
-    "EPIPE",
-    "ECONNABORTED",
-    "ENOTFOUND",
-    "UND_ERR_CONNECT_TIMEOUT",
-    "UND_ERR_HEADERS_TIMEOUT",
-    "UND_ERR_BODY_TIMEOUT",
-    "UND_ERR_SOCKET",
-    "UND_ERR_CLOSED",
-    "UND_ERR_REQ_CONTENT_LENGTH_MISMATCH",
-]);
-/**
- * Error constructor names / `error.name` values that indicate transient
- * abort / timeout conditions.
- */
-const RETRYABLE_ERROR_NAMES = new Set([
-    "AbortError",
-    "TimeoutError",
-    "FetchError",
-    "RequestTimeoutError",
-    "ConnectTimeoutError",
-    "HeadersTimeoutError",
-    "BodyTimeoutError",
-]);
-/**
- * Message-pattern fallback for libraries that discard error codes/names but
- * preserve text (e.g., some Apollo/axios wrappers).
- */
-const RETRYABLE_MESSAGE_PATTERNS = [
-    /aborted/i,
-    /timeout/i,
-    /timed out/i,
-    /network error/i,
-    /socket hang up/i,
-    /connection (reset|refused|closed)/i,
-    /ECONNRESET/,
-    /ETIMEDOUT/,
-    /ECONNREFUSED/,
-    /EAI_AGAIN/,
-    /UND_ERR_/,
-];
-/**
- * Walks the `error.cause` chain (capped to avoid cycles) and tests whether
- * any link along the chain looks like a transient network error. Modern APIs
- * (undici, fetch, Apollo Client 3.8+) wrap the root network failure as a
- * `.cause`, so the surface `Error` may report a generic message while the
- * actionable signal lives one or more levels deeper.
- */
-function isTransientNetworkError(error) {
-    const MAX_CAUSE_DEPTH = 6;
-    let current = error;
-    for (let depth = 0; depth < MAX_CAUSE_DEPTH && current; depth++) {
-        if (current instanceof Error || typeof current === "object") {
-            const err = current;
-            if (typeof err.name === "string" && RETRYABLE_ERROR_NAMES.has(err.name)) {
-                return true;
-            }
-            if (typeof err.code === "string" && RETRYABLE_ERROR_CODES.has(err.code)) {
-                return true;
-            }
-            if (typeof err.message === "string") {
-                for (const pattern of RETRYABLE_MESSAGE_PATTERNS) {
-                    if (pattern.test(err.message)) {
-                        return true;
-                    }
-                }
-            }
-            current = err.cause;
-        }
-        else {
-            break;
-        }
-    }
-    return false;
-}
-/**
- * Analyzes an error and determines if it's retryable.
- * @param error - The error to analyze
- * @param response - Optional Response object for HTTP errors
- * @param config - Retry configuration
- * @returns Structured error details
- */
-function analyzeError(error, response, config) {
-    // Handle Response objects with error status codes
-    if (response && !response.ok) {
-        const status = response.status;
-        // Rate limit errors - always retryable
-        if (status === 429) {
-            const retryAfterHeader = response.headers.get("Retry-After");
-            const retryAfter = retryAfterHeader
-                ? parseInt(retryAfterHeader, 10) * 1000
-                : undefined;
-            return {
-                type: "RATE_LIMIT",
-                reason: "Rate limit exceeded",
-                status,
-                retryAfter,
-                isRetryable: true,
-            };
-        }
-        // Authentication errors - never retry
-        if (status === 401 || status === 403) {
-            return {
-                type: "AUTH_ERROR",
-                reason: status === 401
-                    ? "Authentication failed - invalid credentials"
-                    : "Access forbidden - insufficient permissions",
-                status,
-                isRetryable: false,
-            };
-        }
-        // Server errors - check if in retryable list
-        if (status >= 500 && status < 600) {
-            return {
-                type: "SERVER_ERROR",
-                reason: `Server error (${status})`,
-                status,
-                isRetryable: config.retryableStatusCodes.includes(status),
-            };
-        }
-        // Other client errors - never retry
-        if (status >= 400 && status < 500) {
-            return {
-                type: "CLIENT_ERROR",
-                reason: `Client error (${status})`,
-                status,
-                isRetryable: false,
-            };
-        }
-    }
-    // Handle network errors (TypeError from fetch API)
-    if (error instanceof TypeError && error.message.includes("fetch")) {
-        return {
-            type: "NETWORK_ERROR",
-            reason: "Network connectivity issue",
-            status: null,
-            isRetryable: config.retryOnNetworkError,
-        };
-    }
-    // Handle transient network conditions: AbortError, TimeoutError,
-    // Node/undici error codes (ETIMEDOUT, ECONNRESET, UND_ERR_*), and
-    // wrapped failures exposed via error.cause. This catches the broad class
-    // of infrastructure flakes that the TypeError-only check above misses.
-    if (isTransientNetworkError(error)) {
-        const reason = error instanceof Error ? error.message : "Transient network error";
-        return {
-            type: "NETWORK_ERROR",
-            reason,
-            status: null,
-            isRetryable: config.retryOnNetworkError,
-        };
-    }
-    // Handle error objects with messages
-    if (error instanceof Error) {
-        // Parse error messages that might contain status information
-        if (error.message.includes("429") || error.message.includes("RATE_LIMIT")) {
-            const match = error.message.match(/RATE_LIMIT: 429:(\d+)/);
-            const retryAfter = match ? parseInt(match[1], 10) : undefined;
-            return {
-                type: "RATE_LIMIT",
-                reason: "Rate limit exceeded",
-                status: 429,
-                retryAfter,
-                isRetryable: true,
-            };
-        }
-        if (error.message.includes("401") ||
-            error.message.includes("403") ||
-            error.message.includes("AUTH_ERROR")) {
-            const status = error.message.includes("401") ? 401 : 403;
-            return {
-                type: "AUTH_ERROR",
-                reason: `Authentication error (${status})`,
-                status,
-                isRetryable: false,
-            };
-        }
-        if (error.message.includes("SERVER_ERROR") ||
-            error.message.match(/50[0-9]/)) {
-            const statusMatch = error.message.match(/50[0-9]/);
-            const status = statusMatch ? parseInt(statusMatch[0], 10) : 500;
-            return {
-                type: "SERVER_ERROR",
-                reason: `Server error (${status})`,
-                status,
-                isRetryable: config.retryableStatusCodes.includes(status),
-            };
-        }
-        if (error.message.includes("network") ||
-            error.message.includes("NETWORK_ERROR")) {
-            return {
-                type: "NETWORK_ERROR",
-                reason: error.message,
-                status: null,
-                isRetryable: config.retryOnNetworkError,
-            };
-        }
-    }
-    // Unknown error - not retryable by default for safety
-    return {
-        type: "UNKNOWN",
-        reason: error instanceof Error ? error.message : String(error),
-        status: null,
-        isRetryable: false,
-    };
-}
-/**
- * Calculates the delay before the next retry attempt using exponential backoff with jitter.
- * @param attempt - Current attempt number (1-indexed)
- * @param baseDelay - Base delay in milliseconds
- * @param maxDelay - Maximum delay in milliseconds
- * @returns Delay in milliseconds
- */
-function calculateBackoff(attempt, baseDelay, maxDelay) {
-    // Exponential backoff: baseDelay * 2^(attempt-1)
-    const exponentialDelay = baseDelay * Math.pow(2, attempt - 1);
-    // Cap at maxDelay
-    const cappedDelay = Math.min(exponentialDelay, maxDelay);
-    // Add jitter (random value between 0% and 25% of the delay)
-    const jitter = Math.random() * cappedDelay * 0.25;
-    return Math.floor(cappedDelay + jitter);
-}
-/**
- * Wraps an async function with retry logic and exponential backoff.
- *
- * This utility handles transient errors in external API calls by automatically retrying
- * failed requests with intelligent backoff strategies. It respects rate limit headers,
- * fails fast on non-retryable errors, and provides detailed logging.
- *
- * @template T - The return type of the wrapped function
- * @param fn - The async function to wrap with retry logic
- * @param config - Retry configuration (merged with defaults)
- * @param label - A descriptive label for logging (e.g., 'Massive.fetchTickerInfo')
- * @returns A promise that resolves to the function's return value
- * @throws The last error encountered if all retries are exhausted
- *
- * @example
- * ```typescript
- * // Basic usage with defaults
- * const data = await withRetry(
- *   async () => fetch('https://api.example.com/data'),
- *   {},
- *   'ExampleAPI.fetchData'
- * );
- *
- * // Custom configuration for rate-limited API
- * const result = await withRetry(
- *   async () => alphaVantageAPI.getQuote(symbol),
- *   {
- *     maxRetries: 5,
- *     baseDelayMs: 5000,
- *     maxDelayMs: 60000,
- *     onRetry: (attempt, error) => {
- *       getLogger().info(`Retry ${attempt} after error:`, error);
- *     }
- *   },
- *   'AlphaVantage.getQuote'
- * );
- * ```
- */
-async function withRetry(fn, config = {}, label = "unknown") {
-    const fullConfig = { ...DEFAULT_RETRY_CONFIG, ...config };
-    let lastError;
-    for (let attempt = 1; attempt <= fullConfig.maxRetries; attempt++) {
-        try {
-            const result = await fn();
-            // If we succeeded after retries, log it
-            if (attempt > 1) {
-                getLogger().info(`[${label}] Succeeded on attempt ${attempt}/${fullConfig.maxRetries}`);
-            }
-            return result;
-        }
-        catch (error) {
-            lastError = error;
-            // If this is the last attempt, throw the error
-            if (attempt === fullConfig.maxRetries) {
-                getLogger().error(`[${label}] Failed after ${fullConfig.maxRetries} attempts`, {
-                    error: error instanceof Error ? error.message : String(error),
-                    timestamp: new Date().toISOString(),
-                });
-                throw error;
-            }
-            // Analyze the error to determine if we should retry
-            const response = error instanceof Response ? error : null;
-            const errorDetails = analyzeError(error, response, fullConfig);
-            // If error is not retryable, fail immediately
-            if (!errorDetails.isRetryable) {
-                getLogger().error(`[${label}] Non-retryable error (${errorDetails.type})`, {
-                    reason: errorDetails.reason,
-                    status: errorDetails.status,
-                    timestamp: new Date().toISOString(),
-                });
-                throw error;
-            }
-            // Calculate delay for next retry
-            let delayMs;
-            if (errorDetails.type === "RATE_LIMIT" && errorDetails.retryAfter) {
-                // Use Retry-After header if available
-                delayMs = errorDetails.retryAfter;
-            }
-            else if (errorDetails.type === "RATE_LIMIT") {
-                // For rate limits without Retry-After, use a longer minimum delay
-                delayMs = Math.max(calculateBackoff(attempt, fullConfig.baseDelayMs, fullConfig.maxDelayMs), 5000);
-            }
-            else {
-                // Standard exponential backoff with jitter
-                delayMs = calculateBackoff(attempt, fullConfig.baseDelayMs, fullConfig.maxDelayMs);
-            }
-            // Log the retry attempt
-            getLogger().warn(`[${label}] Attempt ${attempt}/${fullConfig.maxRetries} failed: ${errorDetails.reason}. Retrying in ${delayMs}ms...`, {
-                attemptNumber: attempt,
-                totalRetries: fullConfig.maxRetries,
-                errorType: errorDetails.type,
-                httpStatus: errorDetails.status,
-                retryDelay: delayMs,
-                timestamp: new Date().toISOString(),
-            });
-            // Call the optional retry callback
-            if (fullConfig.onRetry) {
-                fullConfig.onRetry(attempt, error);
-            }
-            // Wait before retrying
-            await new Promise((resolve) => setTimeout(resolve, delayMs));
-        }
-    }
-    // This should never be reached due to the throw in the last attempt,
-    // but TypeScript needs this to satisfy the return type
-    throw lastError;
-}
-/**
- * API-specific retry configurations for different external services.
- * These configurations are tuned based on each API's rate limits and characteristics.
- */
-const API_RETRY_CONFIGS = {
-    /** Massive.com API - 5 requests/second rate limit */
-    MASSIVE: {
-        maxRetries: 3,
-        baseDelayMs: 1000,
-        maxDelayMs: 30000,
-        retryableStatusCodes: [429, 500, 502, 503, 504],
-        retryOnNetworkError: true,
-    },
-    /** Alpha Vantage API - 5 requests/minute rate limit (more strict) */
-    ALPHA_VANTAGE: {
-        maxRetries: 5,
-        baseDelayMs: 5000,
-        maxDelayMs: 60000,
-        retryableStatusCodes: [429, 500, 502, 503, 504],
-        retryOnNetworkError: true,
-    },
-    /** Alpaca API - generally reliable, shorter retry window */
-    ALPACA: {
-        maxRetries: 3,
-        baseDelayMs: 1000,
-        maxDelayMs: 30000,
-        retryableStatusCodes: [429, 500, 502, 503, 504],
-        retryOnNetworkError: true,
-    },
-    /** Generic crypto API configuration */
-    CRYPTO: {
-        maxRetries: 3,
-        baseDelayMs: 1000,
-        maxDelayMs: 30000,
-        retryableStatusCodes: [429, 500, 502, 503, 504],
-        retryOnNetworkError: true,
-    },
-};
-
 // Utility function for debug logging
 /**
  * Debug logging utility that respects environment debug flags.
@@ -8509,19 +8547,37 @@ const fetchPrices = async (params, options) => {
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
             const contextualMessage = `Error fetching price data for ${ticker}`;
-            getLogger().error(`${contextualMessage}: ${errorMessage}`, {
+            const isTransient = isTransientNetworkError(error);
+            const errorType = error instanceof Error && error.message.includes("AUTH_ERROR")
+                ? "AUTH_ERROR"
+                : error instanceof Error && error.message.includes("RATE_LIMIT")
+                    ? "RATE_LIMIT"
+                    : isTransient
+                        ? "NETWORK_ERROR"
+                        : "UNKNOWN";
+            // Transient network failures (undici timeouts, socket resets, DNS
+            // blips) are recoverable at the caller's next cycle — demote to
+            // WARN to avoid alert noise. Non-transient classes (auth, rate
+            // limits that have exhausted retries, unknown schema errors) stay
+            // at ERROR because they require operator attention.
+            const logMeta = {
                 ticker,
-                errorType: error instanceof Error && error.message.includes("AUTH_ERROR")
-                    ? "AUTH_ERROR"
-                    : error instanceof Error && error.message.includes("RATE_LIMIT")
-                        ? "RATE_LIMIT"
-                        : error instanceof Error &&
-                            error.message.includes("NETWORK_ERROR")
-                            ? "NETWORK_ERROR"
-                            : "UNKNOWN",
+                errorType,
                 source: "MassiveAPI.fetchPrices",
                 timestamp: new Date().toISOString(),
-            });
+                ...(isTransient
+                    ? {
+                        transient: true,
+                        recoveryHint: "Upstream caller should retry on next cycle",
+                    }
+                    : {}),
+            };
+            if (isTransient) {
+                getLogger().warn(`${contextualMessage}: ${errorMessage}`, logMeta);
+            }
+            else {
+                getLogger().error(`${contextualMessage}: ${errorMessage}`, logMeta);
+            }
             throw new Error(`${contextualMessage}: ${errorMessage}`);
         }
     });
@@ -68626,6 +68682,7 @@ exports.isOrderFilled = isOrderFilled;
 exports.isOrderOpen = isOrderOpen;
 exports.isOrderTerminalStatus = isOrderTerminal$1;
 exports.isSupportedCryptoPair = isSupportedCryptoPair;
+exports.isTransientNetworkError = isTransientNetworkError;
 exports.legacyApi = index$1;
 exports.limitBuyWithTakeProfit = limitBuyWithTakeProfit;
 exports.ocoOrders = ocoOrders;