@adaptic/utils 0.0.978 → 0.0.980

package/dist/index.mjs

@@ -3799,6 +3799,419 @@ class AlpacaMarketDataAPI extends 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
@@ -4109,9 +4522,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;
         }
@@ -5595,392 +6019,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.
@@ -8507,19 +8545,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}`);
         }
     });
@@ -68384,5 +68440,5 @@ const adaptic = {
 };
 const adptc = adaptic;
 
-export { API_RETRY_CONFIGS, AVNewsArticleSchema, AVNewsResponseSchema, AdapticUtilsError, AlpacaAccountDetailsSchema, AlpacaApiError, AlpacaBarSchema, AlpacaClient, AlpacaCryptoBarsResponseSchema, AlpacaHistoricalBarsResponseSchema, AlpacaLatestBarsResponseSchema, AlpacaLatestQuotesResponseSchema, AlpacaLatestTradesResponseSchema, AlpacaMarketDataAPI, AlpacaNewsArticleSchema, AlpacaNewsResponseSchema, AlpacaOrderSchema, AlpacaOrdersArraySchema, AlpacaPortfolioHistoryResponseSchema, AlpacaPositionSchema, AlpacaPositionsArraySchema, AlpacaQuoteSchema, AlpacaTradeSchema, AlpacaTradingAPI, AlphaVantageError, AlphaVantageQuoteResponseSchema, AssetAllocationEngine, AuthenticationError, AutonomyMode, BTC_PAIRS, BarError, CryptoDataError, CryptoOrderError, DEFAULT_CACHE_OPTIONS, DEFAULT_TIMEOUTS, DEFAULT_TRADING_POLICY, DataFormatError, DecisionMemoryOutcome, DecisionOutcome, DecisionRecordStatus, HttpClientError, HttpServerError, KEEP_ALIVE_DEFAULTS, LlmProvider, MARKET_DATA_API, MassiveAggregatesResponseSchema, MassiveApiError, MassiveDailyOpenCloseSchema, MassiveErrorResponseSchema, MassiveGroupedDailyResponseSchema, MassiveLastTradeResponseSchema, MassiveTickerDetailsResponseSchema, MassiveTickerInfoSchema, MassiveTradeSchema as MassiveTradeZodSchema, MassiveTradesResponseSchema, NetworkError, NewsError, OptionStrategyError, OptionsDataError, OverlaySeverity, OverlayStatus, OverlayType, QuoteError, RateLimitError, RawMassivePriceDataSchema, StampedeProtectedCache, TRADING_API, TimeoutError, TokenBucketRateLimiter, TradeError, TrailingStopValidationError, USDC_PAIRS, USDT_PAIRS, USD_PAIRS, ValidationError, ValidationResponseError, WEBSOCKET_STREAMS, WebSocketError, account, adaptic, adptc, alpaca, analyzeBars, approximateImpliedVolatility, bracketOrders, buildOCCSymbol, buildOptionSymbol, buyCryptoNotional, buyToClose, buyToOpen, buyWithStopLoss, buyWithTrailingStop, calculateMoneyness, calculateOrderValue, calculatePeriodPerformance, calculatePutCallRatio, calculateTotalFilledValue, cancelAllCryptoOrders, cancelOCOOrder, cancelOTOOrder, cancelTrailingStop, cancelTrailingStopsForSymbol, checkTradingEligibility, clearClientCache, clock, closeAllOptionPositions, closeOptionPosition, createAlpacaClient, createAlpacaMarketDataAPI, createAlpacaTradingAPI, createBracketOrder, createButterflySpread, createClientFromEnv, createCoveredCall, createCryptoLimitOrder, createCryptoMarketOrder, createCryptoOrder, createCryptoStopLimitOrder, createCryptoStopOrder, createExecutorFromTradingAPI, createIronCondor$1 as createIronCondor, createIronCondor as createIronCondorAdvanced, createMultiLegOptionOrder, createOCOOrder, createOTOOrder, createOptionOrder, createPortfolioTrailingStops, createProtectiveBracket, createStampedeProtectedCache, createStraddle$1 as createStraddle, createStraddle as createStraddleAdvanced, createStrangle$1 as createStrangle, createStrangle as createStrangleAdvanced, createStreamManager, createTimeoutSignal, createTrailingStop, createVerticalSpread$1 as createVerticalSpread, createVerticalSpread as createVerticalSpreadAdvanced, entryWithPercentStopLoss, exerciseOption, extractGreeks, filterByExpiration, filterByStrike, filterByType, filterOrdersByDateRange, findATMOptions, findATMStrikes, findNearestExpiration, findOptionsByDelta, formatOrderForLog, formatOrderSummary, generateOptimalAllocation, getAccountConfiguration, getAccountDetails, getAccountSummary, getAgentPoolStatus, getAllOrders, getAlpacaCalendar, getAlpacaClock, getAverageDailyVolume, getBars, getBuyingPower, getCrypto24HourChange, getCryptoBars, getCryptoDailyPrices, getCryptoPairsByQuote, getCryptoPrice, getCryptoSnapshots, getCryptoSpread, getCryptoStreamUrl, getCryptoTrades, getCurrentPrice, getCurrentPrices, getDailyPrices, getDailyReturns, getDaysToExpiration, getDefaultRiskProfile, getEquityCurve, getExpirationDates, getFilledOrders, getGroupedOptionChain, getHistoricalOptionsBars, getHistoricalTrades, getIntradayPrices, getLatestBars, getLatestCryptoQuotes, getLatestCryptoTrades, getLatestNews, getLatestOptionsQuotes, getLatestOptionsTrades, getLatestQuote, getLatestQuotes, getLatestTrade, getLatestTrades, getLogger, getMarginInfo, getNews, getNewsForSymbols, getOCOOrderStatus, getOTOOrderStatus, getOpenCryptoOrders, getOpenOrders$1 as getOpenOrdersQuery, getOpenTrailingStops, getOptionChain, getOptionContract, getOptionContracts, getOptionSpread, getOptionsChain, getOptionsSnapshots, getOptionsStreamUrl, getOptionsTradingLevel, getOrderHistory, getOrdersBySymbol, getPDTStatus, getPopularCryptoPairs, getPortfolioHistory, getPreviousClose, getPriceRange, getSpread, getSpreads, getStockStreamUrl, getStrikePrices, getSupportedCryptoPairs, getSymbolSentiment, getTimeout, getTradeVolume, getTradingApiUrl, getTradingWebSocketUrl, getTrailingStopHWM, groupOrdersByStatus, groupOrdersBySymbol, hasActiveTrailingStop, hasGoodLiquidity as hasOptionLiquidity, hasGoodLiquidity$1 as hasStockLiquidity, hasSufficientVolume, httpAgent, httpsAgent, isContractTradable, isCryptoPair, isExpiringWithin, isMarginAccount, isOptionOrderCancelable, isOptionOrderTerminal, isOrderFillable, isOrderFilled, isOrderOpen, isOrderTerminal$1 as isOrderTerminalStatus, isSupportedCryptoPair, index$1 as legacyApi, limitBuyWithTakeProfit, ocoOrders, orderUtils, otoOrders, paginate, paginateAll, parseOCCSymbol, protectLongPosition, protectShortPosition, rateLimiters, resetLogger, rollOptionPosition, roundPriceForAlpaca$3 as roundPriceForAlpaca, roundPriceForAlpacaNumber, safeValidateResponse, searchNews, sellAllCrypto, sellCryptoNotional, sellToClose, sellToOpen, setLogger, shortWithStopLoss, sortOrdersByDate, index as tradingPolicy, trailingStops, updateAccountConfiguration, updateTrailingStop, validateAlpacaCredentials, validateAlphaVantageApiKey, validateMassiveApiKey$1 as validateMassiveApiKey, validateMultiLegOrder, validateResponse, verifyFetchKeepAlive, waitForOrderFill, withRetry, withTimeout };
+export { API_RETRY_CONFIGS, AVNewsArticleSchema, AVNewsResponseSchema, AdapticUtilsError, AlpacaAccountDetailsSchema, AlpacaApiError, AlpacaBarSchema, AlpacaClient, AlpacaCryptoBarsResponseSchema, AlpacaHistoricalBarsResponseSchema, AlpacaLatestBarsResponseSchema, AlpacaLatestQuotesResponseSchema, AlpacaLatestTradesResponseSchema, AlpacaMarketDataAPI, AlpacaNewsArticleSchema, AlpacaNewsResponseSchema, AlpacaOrderSchema, AlpacaOrdersArraySchema, AlpacaPortfolioHistoryResponseSchema, AlpacaPositionSchema, AlpacaPositionsArraySchema, AlpacaQuoteSchema, AlpacaTradeSchema, AlpacaTradingAPI, AlphaVantageError, AlphaVantageQuoteResponseSchema, AssetAllocationEngine, AuthenticationError, AutonomyMode, BTC_PAIRS, BarError, CryptoDataError, CryptoOrderError, DEFAULT_CACHE_OPTIONS, DEFAULT_TIMEOUTS, DEFAULT_TRADING_POLICY, DataFormatError, DecisionMemoryOutcome, DecisionOutcome, DecisionRecordStatus, HttpClientError, HttpServerError, KEEP_ALIVE_DEFAULTS, LlmProvider, MARKET_DATA_API, MassiveAggregatesResponseSchema, MassiveApiError, MassiveDailyOpenCloseSchema, MassiveErrorResponseSchema, MassiveGroupedDailyResponseSchema, MassiveLastTradeResponseSchema, MassiveTickerDetailsResponseSchema, MassiveTickerInfoSchema, MassiveTradeSchema as MassiveTradeZodSchema, MassiveTradesResponseSchema, NetworkError, NewsError, OptionStrategyError, OptionsDataError, OverlaySeverity, OverlayStatus, OverlayType, QuoteError, RateLimitError, RawMassivePriceDataSchema, StampedeProtectedCache, TRADING_API, TimeoutError, TokenBucketRateLimiter, TradeError, TrailingStopValidationError, USDC_PAIRS, USDT_PAIRS, USD_PAIRS, ValidationError, ValidationResponseError, WEBSOCKET_STREAMS, WebSocketError, account, adaptic, adptc, alpaca, analyzeBars, approximateImpliedVolatility, bracketOrders, buildOCCSymbol, buildOptionSymbol, buyCryptoNotional, buyToClose, buyToOpen, buyWithStopLoss, buyWithTrailingStop, calculateMoneyness, calculateOrderValue, calculatePeriodPerformance, calculatePutCallRatio, calculateTotalFilledValue, cancelAllCryptoOrders, cancelOCOOrder, cancelOTOOrder, cancelTrailingStop, cancelTrailingStopsForSymbol, checkTradingEligibility, clearClientCache, clock, closeAllOptionPositions, closeOptionPosition, createAlpacaClient, createAlpacaMarketDataAPI, createAlpacaTradingAPI, createBracketOrder, createButterflySpread, createClientFromEnv, createCoveredCall, createCryptoLimitOrder, createCryptoMarketOrder, createCryptoOrder, createCryptoStopLimitOrder, createCryptoStopOrder, createExecutorFromTradingAPI, createIronCondor$1 as createIronCondor, createIronCondor as createIronCondorAdvanced, createMultiLegOptionOrder, createOCOOrder, createOTOOrder, createOptionOrder, createPortfolioTrailingStops, createProtectiveBracket, createStampedeProtectedCache, createStraddle$1 as createStraddle, createStraddle as createStraddleAdvanced, createStrangle$1 as createStrangle, createStrangle as createStrangleAdvanced, createStreamManager, createTimeoutSignal, createTrailingStop, createVerticalSpread$1 as createVerticalSpread, createVerticalSpread as createVerticalSpreadAdvanced, entryWithPercentStopLoss, exerciseOption, extractGreeks, filterByExpiration, filterByStrike, filterByType, filterOrdersByDateRange, findATMOptions, findATMStrikes, findNearestExpiration, findOptionsByDelta, formatOrderForLog, formatOrderSummary, generateOptimalAllocation, getAccountConfiguration, getAccountDetails, getAccountSummary, getAgentPoolStatus, getAllOrders, getAlpacaCalendar, getAlpacaClock, getAverageDailyVolume, getBars, getBuyingPower, getCrypto24HourChange, getCryptoBars, getCryptoDailyPrices, getCryptoPairsByQuote, getCryptoPrice, getCryptoSnapshots, getCryptoSpread, getCryptoStreamUrl, getCryptoTrades, getCurrentPrice, getCurrentPrices, getDailyPrices, getDailyReturns, getDaysToExpiration, getDefaultRiskProfile, getEquityCurve, getExpirationDates, getFilledOrders, getGroupedOptionChain, getHistoricalOptionsBars, getHistoricalTrades, getIntradayPrices, getLatestBars, getLatestCryptoQuotes, getLatestCryptoTrades, getLatestNews, getLatestOptionsQuotes, getLatestOptionsTrades, getLatestQuote, getLatestQuotes, getLatestTrade, getLatestTrades, getLogger, getMarginInfo, getNews, getNewsForSymbols, getOCOOrderStatus, getOTOOrderStatus, getOpenCryptoOrders, getOpenOrders$1 as getOpenOrdersQuery, getOpenTrailingStops, getOptionChain, getOptionContract, getOptionContracts, getOptionSpread, getOptionsChain, getOptionsSnapshots, getOptionsStreamUrl, getOptionsTradingLevel, getOrderHistory, getOrdersBySymbol, getPDTStatus, getPopularCryptoPairs, getPortfolioHistory, getPreviousClose, getPriceRange, getSpread, getSpreads, getStockStreamUrl, getStrikePrices, getSupportedCryptoPairs, getSymbolSentiment, getTimeout, getTradeVolume, getTradingApiUrl, getTradingWebSocketUrl, getTrailingStopHWM, groupOrdersByStatus, groupOrdersBySymbol, hasActiveTrailingStop, hasGoodLiquidity as hasOptionLiquidity, hasGoodLiquidity$1 as hasStockLiquidity, hasSufficientVolume, httpAgent, httpsAgent, isContractTradable, isCryptoPair, isExpiringWithin, isMarginAccount, isOptionOrderCancelable, isOptionOrderTerminal, isOrderFillable, isOrderFilled, isOrderOpen, isOrderTerminal$1 as isOrderTerminalStatus, isSupportedCryptoPair, isTransientNetworkError, index$1 as legacyApi, limitBuyWithTakeProfit, ocoOrders, orderUtils, otoOrders, paginate, paginateAll, parseOCCSymbol, protectLongPosition, protectShortPosition, rateLimiters, resetLogger, rollOptionPosition, roundPriceForAlpaca$3 as roundPriceForAlpaca, roundPriceForAlpacaNumber, safeValidateResponse, searchNews, sellAllCrypto, sellCryptoNotional, sellToClose, sellToOpen, setLogger, shortWithStopLoss, sortOrdersByDate, index as tradingPolicy, trailingStops, updateAccountConfiguration, updateTrailingStop, validateAlpacaCredentials, validateAlphaVantageApiKey, validateMassiveApiKey$1 as validateMassiveApiKey, validateMultiLegOrder, validateResponse, verifyFetchKeepAlive, waitForOrderFill, withRetry, withTimeout };
 //# sourceMappingURL=index.mjs.map