@adaptic/utils 0.0.1005 → 0.0.1007

package/dist/index.mjs

@@ -2175,1436 +2175,1561 @@ function validateAlphaVantageApiKey(apiKey) {
     }
 }
 
+const DEFAULT_RETRY_CONFIG = {
+    maxRetries: 3,
+    baseDelayMs: 1000,
+    maxDelayMs: 30000,
+    retryableStatusCodes: [429, 500, 502, 503, 504],
+    retryOnNetworkError: true,
+};
 /**
- * Structured error type hierarchy for all API integrations
- *
- * This module provides a comprehensive error handling system for external API integrations,
- * including Alpaca, Massive, and AlphaVantage services.
+ * 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",
+]);
 /**
- * Base error class for all @adaptic/utils errors
- * Extends Error with additional context about service, error code, and retry capability
+ * Error constructor names / `error.name` values that indicate transient
+ * abort / timeout conditions.
  */
-class AdapticUtilsError extends Error {
-    code;
-    service;
-    isRetryable;
-    cause;
-    name;
-    constructor(message, code, service, isRetryable = false, cause) {
-        super(message);
-        this.code = code;
-        this.service = service;
-        this.isRetryable = isRetryable;
-        this.cause = cause;
-        this.name = this.constructor.name;
-        // Maintains proper stack trace for where error was thrown (only available on V8)
-        if (Error.captureStackTrace) {
-            Error.captureStackTrace(this, this.constructor);
-        }
-    }
-}
+const RETRYABLE_ERROR_NAMES = new Set([
+    "AbortError",
+    "TimeoutError",
+    "FetchError",
+    "RequestTimeoutError",
+    "ConnectTimeoutError",
+    "HeadersTimeoutError",
+    "BodyTimeoutError",
+]);
 /**
- * Alpaca API specific errors
- * Handles all errors from Alpaca trading and market data APIs
+ * Message-pattern fallback for libraries that discard error codes/names but
+ * preserve text (e.g., some Apollo/axios wrappers).
  */
-class AlpacaApiError extends AdapticUtilsError {
-    statusCode;
-    constructor(message, code, statusCode, cause) {
-        // Rate limit (429) and server errors (5xx) are retryable
-        const isRetryable = statusCode === 429 || (statusCode !== undefined && statusCode >= 500);
-        super(message, code, "alpaca", isRetryable, cause);
-        this.statusCode = statusCode;
-    }
-}
+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_/,
+];
 /**
- * Massive.com API specific errors
- * Handles all errors from Massive market data API
+ * 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.
  */
-class MassiveApiError extends AdapticUtilsError {
-    statusCode;
-    constructor(message, code, statusCode, cause) {
-        // Rate limit (429) and server errors (5xx) are retryable
-        const isRetryable = statusCode === 429 || (statusCode !== undefined && statusCode >= 500);
-        super(message, code, "massive", isRetryable, cause);
-        this.statusCode = statusCode;
+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;
 }
 /**
- * AlphaVantage API specific errors
- * Handles all errors from AlphaVantage financial data API
+ * 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
  */
-class AlphaVantageError extends AdapticUtilsError {
-    statusCode;
-    constructor(message, code, statusCode, cause) {
-        // Rate limit (429) and server errors (5xx) are retryable
-        const isRetryable = statusCode === 429 || (statusCode !== undefined && statusCode >= 500);
-        super(message, code, "alphavantage", isRetryable, cause);
-        this.statusCode = statusCode;
+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,
+            };
+        }
     }
-}
-/**
- * Network timeout errors
- * Used when API requests exceed configured timeout limits
- * Always retryable as timeouts are often transient
- */
-class TimeoutError extends AdapticUtilsError {
-    service;
-    timeoutMs;
-    constructor(message, service, timeoutMs, cause) {
-        super(message, "TIMEOUT", service, true, // Timeouts are always retryable
-        cause);
-        this.service = service;
-        this.timeoutMs = timeoutMs;
+    // 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,
+        };
     }
-}
-/**
- * Input validation errors
- * Used when function inputs fail validation checks
- * Never retryable as the inputs need to be corrected
- */
-class ValidationError extends AdapticUtilsError {
-    service;
-    invalidField;
-    constructor(message, service, invalidField, cause) {
-        super(message, "VALIDATION_ERROR", service, false, // Validation errors are never retryable
-        cause);
-        this.service = service;
-        this.invalidField = invalidField;
+    // 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,
+        };
     }
-}
-/**
- * Authentication and authorization errors
- * Used when API credentials are invalid, expired, or lack permissions
- * Never retryable as credentials need to be updated
- */
-class AuthenticationError extends AdapticUtilsError {
-    service;
-    statusCode;
-    constructor(message, service, statusCode, cause) {
-        super(message, "AUTH_ERROR", service, false, // Auth errors are never retryable
-        cause);
-        this.service = service;
-        this.statusCode = statusCode;
-    }
-}
-/**
- * HTTP client errors (4xx)
- * Used for client-side errors that are not authentication or validation related
- * Generally not retryable unless specific status codes indicate otherwise
- */
-class HttpClientError extends AdapticUtilsError {
-    service;
-    statusCode;
-    constructor(message, service, statusCode, cause) {
-        super(message, "CLIENT_ERROR", service, false, // Client errors are generally not retryable
-        cause);
-        this.service = service;
-        this.statusCode = statusCode;
-    }
-}
-/**
- * HTTP server errors (5xx)
- * Used for server-side errors from external APIs
- * Always retryable as server issues are often transient
- */
-class HttpServerError extends AdapticUtilsError {
-    service;
-    statusCode;
-    constructor(message, service, statusCode, cause) {
-        super(message, "SERVER_ERROR", service, true, // Server errors are always retryable
-        cause);
-        this.service = service;
-        this.statusCode = statusCode;
-    }
-}
-/**
- * Rate limit errors (429)
- * Used when API rate limits are exceeded
- * Always retryable, often with retry-after header information
- */
-class RateLimitError extends AdapticUtilsError {
-    service;
-    retryAfterMs;
-    constructor(message, service, retryAfterMs, cause) {
-        super(message, "RATE_LIMIT", service, true, // Rate limit errors are always retryable
-        cause);
-        this.service = service;
-        this.retryAfterMs = retryAfterMs;
-    }
-}
-/**
- * WebSocket connection errors
- * Used for WebSocket-specific connection and communication failures
- * Retryability depends on the specific error condition
- */
-class WebSocketError extends AdapticUtilsError {
-    service;
-    constructor(message, service, isRetryable = true, cause) {
-        super(message, "WEBSOCKET_ERROR", service, isRetryable, cause);
-        this.service = service;
-    }
-}
-/**
- * Network errors (connection failures, DNS issues, etc.)
- * Used for low-level network failures
- * Always retryable as network issues are often transient
- */
-class NetworkError extends AdapticUtilsError {
-    service;
-    constructor(message, service, cause) {
-        super(message, "NETWORK_ERROR", service, true, // Network errors are always retryable
-        cause);
-        this.service = service;
-    }
-}
-/**
- * Unsupported brokerage provider errors
- * Thrown when a broker operation is requested for a provider that has no
- * implemented integration (e.g. IBKR or COINBASE before their adapters land,
- * or an unrecognised provider string from an untyped caller).
- * Never retryable — the caller must route to a supported provider.
- */
-class UnsupportedBrokerError extends AdapticUtilsError {
-    provider;
-    constructor(
-    /** The provider that was requested but is not supported. */
-    provider, cause) {
-        super(`Brokerage provider "${provider}" is not supported. Supported providers: ALPACA`, "UNSUPPORTED_BROKER", "broker", false, // Unsupported providers are never retryable
-        cause);
-        this.provider = provider;
+    // 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,
+    };
 }
 /**
- * Data parsing and format errors
- * Used when API responses cannot be parsed or are in unexpected format
- * Not retryable as the data format issue needs investigation
+ * 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
  */
-class DataFormatError extends AdapticUtilsError {
-    service;
-    constructor(message, service, cause) {
-        super(message, "DATA_FORMAT_ERROR", service, false, // Data format errors are not retryable
-        cause);
-        this.service = service;
-    }
+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);
 }
-
 /**
- * Token bucket rate limiter for external API integrations
+ * Wraps an async function with retry logic and exponential backoff.
  *
- * Implements client-side rate limiting to prevent exceeding API quotas
- * and ensure fair usage of external services like Alpaca, Massive, and AlphaVantage.
+ * 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
- * import { rateLimiters } from '@adaptic/utils';
+ * // Basic usage with defaults
+ * const data = await withRetry(
+ *   async () => fetch('https://api.example.com/data'),
+ *   {},
+ *   'ExampleAPI.fetchData'
+ * );
  *
- * // Before making an API call
- * await rateLimiters.alpaca.acquire();
- * const result = await makeAlpacaApiCall();
+ * // 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'
+ * );
  * ```
  */
-/** Number of milliseconds in one second, used for token-refill timing math. */
-const MS_PER_SECOND$1 = 1000;
-/**
- * Minimum delay (ms) for a scheduled queue wake-up. Guards against a `0`/`NaN`
- * delay when the token deficit rounds down, ensuring the timer always makes
- * forward progress rather than busy-looping on the event loop.
- */
-const MIN_WAKE_DELAY_MS = 1;
-/**
- * Number of whole tokens required to release a single queued request. The token
- * bucket consumes exactly one token per admitted request.
- */
-const TOKENS_PER_REQUEST = 1;
-/**
- * Token bucket rate limiter implementation
- *
- * Uses the token bucket algorithm to control the rate of API requests.
- * Tokens are consumed on each request and refilled at a constant rate.
- * Requests that exceed the available tokens are queued and processed
- * when tokens become available.
- */
-class TokenBucketRateLimiter {
-    config;
-    tokens;
-    lastRefill;
-    queue = [];
-    timeoutMs;
-    processingQueue = false;
-    /**
-     * Single pending timer that wakes the limiter to refill tokens and drain the
-     * queue. Without this, a queued request would only be released by a
-     * subsequent {@link acquire} call and would otherwise stall until its own
-     * timeout fired. `null` means no wake-up is currently scheduled.
-     */
-    wakeTimer = null;
-    /**
-     * Creates a new rate limiter instance
-     *
-     * @param config - Rate limiter configuration
-     *
-     * @example
-     * ```typescript
-     * // Alpaca: 200 requests per minute
-     * const alpacaLimiter = new TokenBucketRateLimiter({
-     *   maxTokens: 200,
-     *   refillRate: 200 / 60, // ~3.33 per second
-     *   label: 'alpaca',
-     *   timeoutMs: 60000
-     * });
-     * ```
-     */
-    constructor(config) {
-        this.config = config;
-        this.tokens = config.maxTokens;
-        this.lastRefill = Date.now();
-        this.timeoutMs = config.timeoutMs ?? 60000; // Default 60 second timeout
-    }
-    /**
-     * Acquires a token for making an API request
-     *
-     * If a token is available, it is consumed immediately.
-     * If no tokens are available, the request is queued and will resolve
-     * when a token becomes available or reject if it times out.
-     *
-     * @throws {RateLimitError} If the request times out waiting for a token
-     *
-     * @example
-     * ```typescript
-     * try {
-     *   await limiter.acquire();
-     *   // Make API call
-     * } catch (error) {
-     *   if (error instanceof RateLimitError) {
-     *     // Handle rate limit timeout
-     *   }
-     * }
-     * ```
-     */
-    async acquire() {
-        const logger = getLogger();
-        this.refill();
-        if (this.tokens > 0) {
-            this.tokens--;
-            logger.debug(`Rate limit token acquired for ${this.config.label}`, {
-                remainingTokens: this.tokens,
-                queueLength: this.queue.length,
-            });
-            return;
+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;
         }
-        // No tokens available, queue the request
-        logger.debug(`Rate limit reached for ${this.config.label}, queuing request`, {
-            queueLength: this.queue.length,
-        });
-        return new Promise((resolve, reject) => {
-            const timeoutHandle = setTimeout(() => {
-                // Remove from queue on timeout
-                const index = this.queue.findIndex((req) => req.timeoutHandle === timeoutHandle);
-                if (index !== -1) {
-                    this.queue.splice(index, 1);
+        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);
                 }
-                const error = new RateLimitError(`Rate limit timeout for ${this.config.label} after ${this.timeoutMs}ms`, this.config.label, undefined);
-                logger.warn(`Rate limit timeout for ${this.config.label}`, {
-                    queueLength: this.queue.length,
-                    timeoutMs: this.timeoutMs,
+                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(),
                 });
-                reject(error);
-            }, this.timeoutMs);
-            this.queue.push({ resolve, reject, timeoutHandle });
-            // Ensure the queue is actively drained even if no further acquire() calls
-            // arrive: schedule a wake-up to refill tokens and release this request.
-            this.scheduleQueueWake();
-        });
-    }
-    /**
-     * Schedules a single wake-up timer that refills tokens and drains the queue.
-     *
-     * The delay is the time required to accrue the tokens still needed to release
-     * the next queued request at the configured refill rate. Only one timer is
-     * ever outstanding (guarded by {@link wakeTimer}); the timer is `unref`'d so
-     * it never keeps the Node.js process alive on its own. When it fires it
-     * refills, drains what it can, and re-arms itself if work remains.
-     */
-    scheduleQueueWake() {
-        // A wake-up is already pending, or there is nothing to wake for.
-        if (this.wakeTimer !== null || this.queue.length === 0) {
-            return;
-        }
-        const tokensNeeded = Math.max(0, TOKENS_PER_REQUEST - this.tokens);
-        const deficitMs = Math.max(MIN_WAKE_DELAY_MS, Math.ceil((tokensNeeded / this.config.refillRate) * MS_PER_SECOND$1));
-        const timer = setTimeout(() => {
-            this.wakeTimer = null;
-            // refill() drains the queue via processQueue(); if requests remain
-            // afterwards, processQueue() re-arms the wake-up.
-            this.refill();
-        }, deficitMs);
-        // Do not let a pending rate-limiter wake-up keep the process alive.
-        if (typeof timer.unref === "function") {
-            timer.unref();
+                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.wakeTimer = timer;
     }
-    /**
-     * Clears any pending wake-up timer.
-     */
-    clearWakeTimer() {
-        if (this.wakeTimer !== null) {
-            clearTimeout(this.wakeTimer);
-            this.wakeTimer = null;
+    // 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,
+    },
+};
+
+/**
+ * Structured error type hierarchy for all API integrations
+ *
+ * This module provides a comprehensive error handling system for external API integrations,
+ * including Alpaca, Massive, and AlphaVantage services.
+ */
+/**
+ * Base error class for all @adaptic/utils errors
+ * Extends Error with additional context about service, error code, and retry capability
+ */
+class AdapticUtilsError extends Error {
+    code;
+    service;
+    isRetryable;
+    cause;
+    name;
+    constructor(message, code, service, isRetryable = false, cause) {
+        super(message);
+        this.code = code;
+        this.service = service;
+        this.isRetryable = isRetryable;
+        this.cause = cause;
+        this.name = this.constructor.name;
+        // Maintains proper stack trace for where error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
         }
     }
-    /**
-     * Refills tokens based on elapsed time and processes queued requests
-     *
-     * Tokens are refilled at the configured rate up to the maximum capacity.
-     * If tokens are available after refilling, queued requests are processed.
-     */
-    refill() {
-        const now = Date.now();
-        const elapsed = (now - this.lastRefill) / 1000; // Convert to seconds
-        const tokensToAdd = elapsed * this.config.refillRate;
-        this.tokens = Math.min(this.config.maxTokens, this.tokens + tokensToAdd);
-        this.lastRefill = now;
-        // Process queued requests if we have tokens
-        this.processQueue();
-    }
-    /**
-     * Processes queued requests when tokens are available
-     *
-     * Prevents concurrent queue processing to ensure FIFO order.
-     */
-    processQueue() {
-        // Prevent concurrent queue processing
-        if (this.processingQueue) {
-            return;
-        }
-        this.processingQueue = true;
-        const logger = getLogger();
-        try {
-            while (this.queue.length > 0 && this.tokens > 0) {
-                this.tokens--;
-                const next = this.queue.shift();
-                if (next) {
-                    clearTimeout(next.timeoutHandle);
-                    next.resolve();
-                    logger.debug(`Processed queued request for ${this.config.label}`, {
-                        remainingTokens: this.tokens,
-                        remainingQueue: this.queue.length,
-                    });
-                }
-            }
-        }
-        finally {
-            this.processingQueue = false;
-        }
-        // Keep the wake-up state consistent with the queue: if requests are still
-        // waiting (tokens ran out mid-drain), ensure a wake-up is armed; otherwise
-        // release any pending timer so it cannot fire needlessly.
-        if (this.queue.length > 0) {
-            this.scheduleQueueWake();
-        }
-        else {
-            this.clearWakeTimer();
-        }
+}
+/**
+ * Alpaca API specific errors
+ * Handles all errors from Alpaca trading and market data APIs
+ */
+class AlpacaApiError extends AdapticUtilsError {
+    statusCode;
+    constructor(message, code, statusCode, cause) {
+        // Rate limit (429) and server errors (5xx) are retryable
+        const isRetryable = statusCode === 429 || (statusCode !== undefined && statusCode >= 500);
+        super(message, code, "alpaca", isRetryable, cause);
+        this.statusCode = statusCode;
     }
-    /**
-     * Gets the current number of available tokens
-     *
-     * @returns Number of tokens currently available
-     */
-    getAvailableTokens() {
-        this.refill();
-        return Math.floor(this.tokens);
+}
+/**
+ * Massive.com API specific errors
+ * Handles all errors from Massive market data API
+ */
+class MassiveApiError extends AdapticUtilsError {
+    statusCode;
+    constructor(message, code, statusCode, cause) {
+        // Rate limit (429) and server errors (5xx) are retryable
+        const isRetryable = statusCode === 429 || (statusCode !== undefined && statusCode >= 500);
+        super(message, code, "massive", isRetryable, cause);
+        this.statusCode = statusCode;
     }
-    /**
-     * Gets the current queue length
-     *
-     * @returns Number of requests waiting for tokens
-     */
-    getQueueLength() {
-        return this.queue.length;
+}
+/**
+ * AlphaVantage API specific errors
+ * Handles all errors from AlphaVantage financial data API
+ */
+class AlphaVantageError extends AdapticUtilsError {
+    statusCode;
+    constructor(message, code, statusCode, cause) {
+        // Rate limit (429) and server errors (5xx) are retryable
+        const isRetryable = statusCode === 429 || (statusCode !== undefined && statusCode >= 500);
+        super(message, code, "alphavantage", isRetryable, cause);
+        this.statusCode = statusCode;
     }
-    /**
-     * Clears all queued requests and resets the token bucket
-     *
-     * All queued requests will be rejected with a RateLimitError.
-     * Useful for cleanup or when changing rate limit configurations.
-     */
-    reset() {
-        const logger = getLogger();
-        // Reject all queued requests
-        for (const request of this.queue) {
-            clearTimeout(request.timeoutHandle);
-            request.reject(new RateLimitError(`Rate limiter reset for ${this.config.label}`, this.config.label, undefined));
-        }
-        this.clearWakeTimer();
-        this.queue = [];
-        this.tokens = this.config.maxTokens;
-        this.lastRefill = Date.now();
-        this.processingQueue = false;
-        logger.info(`Rate limiter reset for ${this.config.label}`, {
-            maxTokens: this.config.maxTokens,
-        });
+}
+/**
+ * Network timeout errors
+ * Used when API requests exceed configured timeout limits
+ * Always retryable as timeouts are often transient
+ */
+class TimeoutError extends AdapticUtilsError {
+    service;
+    timeoutMs;
+    constructor(message, service, timeoutMs, cause) {
+        super(message, "TIMEOUT", service, true, // Timeouts are always retryable
+        cause);
+        this.service = service;
+        this.timeoutMs = timeoutMs;
     }
 }
 /**
- * Pre-configured rate limiters for common external APIs
- *
- * These limiters are configured based on the documented rate limits
- * for each service. Adjust the configurations if you have different
- * tier access or if limits change.
- *
- * @example
- * ```typescript
- * import { rateLimiters } from '@adaptic/utils';
- *
- * // Use before making API calls
- * await rateLimiters.alpaca.acquire();
- * await rateLimiters.massive.acquire();
- * await rateLimiters.alphaVantage.acquire();
- * ```
+ * Input validation errors
+ * Used when function inputs fail validation checks
+ * Never retryable as the inputs need to be corrected
  */
-const rateLimiters = {
-    /**
-     * Alpaca API rate limiter
-     *
-     * Configured for 1000 requests per minute (paid tier).
-     * The token bucket allows burst up to maxTokens, then refills at the steady rate.
-     * See: https://alpaca.markets/docs/api-references/trading-api/#rate-limit
-     */
-    alpaca: new TokenBucketRateLimiter({
-        maxTokens: 1000,
-        refillRate: 1000 / 60, // 1000 requests per 60 seconds (~16.67/sec)
-        label: "alpaca",
-        timeoutMs: 60000,
-    }),
-    /**
-     * Massive.com API rate limiter
-     *
-     * Configured generously for paid unlimited tier. The bucket exists only as a
-     * safety net against runaway loops — the 1000 token burst and 500/sec refill
-     * should never be hit under normal operation. If the paid plan truly has no
-     * hard limit, this just prevents accidental self-DDoS.
-     */
-    massive: new TokenBucketRateLimiter({
-        maxTokens: 1000,
-        refillRate: 500, // 500 tokens/sec refill — effectively unlimited for paid tier
-        label: "massive",
-        timeoutMs: 30000,
-    }),
-    /**
-     * AlphaVantage API rate limiter
-     *
-     * Configured for 5 requests per minute (free tier).
-     * For premium tier (75/min), create a custom limiter:
-     *
-     * @example
-     * ```typescript
-     * const premiumAV = new TokenBucketRateLimiter({
-     *   maxTokens: 75,
-     *   refillRate: 75 / 60,
-     *   label: 'alphaVantage-premium',
-     *   timeoutMs: 60000,
-     * });
-     * ```
-     *
-     * See: https://www.alphavantage.co/premium/
-     */
-    alphaVantage: new TokenBucketRateLimiter({
-        maxTokens: 5,
-        refillRate: 5 / 60, // 5 requests per 60 seconds (~0.083/sec)
-        label: "alphaVantage",
-        timeoutMs: 60000,
-    }),
-};
-
-const log$l = (message, options = { type: "info" }) => {
-    log$m(message, { ...options, source: "AlpacaMarketDataAPI" });
-};
-// Default settings for market data API
-const DEFAULT_ADJUSTMENT = "all";
-// Data feed tier. SIP is full US-market-consolidated feed (requires a paid
-// Alpaca market-data subscription). IEX is the free tier — single-exchange,
-// delayed. Engine deploys running on IEX-only accounts hit chronic HTTP 403
-// ("subscription does not permit querying recent SIP data") at ~100/min when
-// this defaulted to "sip", which saturated Railway's per-replica log ingest
-// and hid steady-state signal. The ALPACA_MARKET_DATA_FEED env var overrides
-// the default. Fall back to "iex" so the free tier is safe by default; LIVE
-// deployments with SIP entitlements set ALPACA_MARKET_DATA_FEED=sip in their
-// environment to restore full data access. Per-call overrides (the optional
-// `feed` argument on getOptions*/getLatestBars/etc.) still win.
-const DEFAULT_FEED$1 = (process.env.ALPACA_MARKET_DATA_FEED || "iex");
-const DEFAULT_CURRENCY$1 = "USD";
+class ValidationError extends AdapticUtilsError {
+    service;
+    invalidField;
+    constructor(message, service, invalidField, cause) {
+        super(message, "VALIDATION_ERROR", service, false, // Validation errors are never retryable
+        cause);
+        this.service = service;
+        this.invalidField = invalidField;
+    }
+}
 /**
- * Singleton class for interacting with Alpaca Market Data API
- * Provides methods for fetching historical bars, latest bars, last trades, latest trades, latest quotes, and latest quote for a single symbol
+ * Authentication and authorization errors
+ * Used when API credentials are invalid, expired, or lack permissions
+ * Never retryable as credentials need to be updated
  */
-class AlpacaMarketDataAPI extends EventEmitter {
-    static instance;
-    headers;
-    dataURL;
-    apiURL;
-    v1beta1url;
-    /** Whether API credentials are valid and available. False during build time when env vars are missing. */
-    credentialsValid = false;
-    stockStreamUrl = getStockStreamUrl("PRODUCTION"); // production values
-    optionStreamUrl = getOptionsStreamUrl("PRODUCTION"); // production values
-    cryptoStreamUrl = getCryptoStreamUrl("PRODUCTION"); // production values
-    stockWs = null;
-    optionWs = null;
-    cryptoWs = null;
-    stockSubscriptions = {
-        trades: [],
-        quotes: [],
-        bars: [],
-    };
-    optionSubscriptions = {
-        trades: [],
-        quotes: [],
-        bars: [],
-    };
-    cryptoSubscriptions = {
-        trades: [],
-        quotes: [],
-        bars: [],
-    };
-    reconnectAttempts = {};
-    reconnectTimers = {};
-    /**
-     * Wall-clock timestamp of the most recent Alpaca app-level error code
-     * 406 ("connection limit exceeded") received on each stream. Used by
-     * {@link scheduleReconnect} to apply a long backoff with jitter rather
-     * than the normal sub-second exponential ramp — without this, hitting
-     * Alpaca's account-wide concurrent-connection cap (typical for blue/green
-     * deploy rollovers where the old pod's WS slots haven't been released
-     * yet) produced a 10-attempt retry storm that compounded the slot
-     * pressure and consumed the per-account connection quota across the
-     * organisation.
-     *
-     * Cleared once the long-backoff retry is scheduled so that subsequent
-     * normal failures fall back to the standard sub-second exponential.
-     *
-     * @see CONNECTION_LIMIT_BACKOFF_MS / CONNECTION_LIMIT_BACKOFF_JITTER_MS
-     */
-    lastConnectionLimitAt = {};
+class AuthenticationError extends AdapticUtilsError {
+    service;
+    statusCode;
+    constructor(message, service, statusCode, cause) {
+        super(message, "AUTH_ERROR", service, false, // Auth errors are never retryable
+        cause);
+        this.service = service;
+        this.statusCode = statusCode;
+    }
+}
+/**
+ * HTTP client errors (4xx)
+ * Used for client-side errors that are not authentication or validation related
+ * Generally not retryable unless specific status codes indicate otherwise
+ */
+class HttpClientError extends AdapticUtilsError {
+    service;
+    statusCode;
+    constructor(message, service, statusCode, cause) {
+        super(message, "CLIENT_ERROR", service, false, // Client errors are generally not retryable
+        cause);
+        this.service = service;
+        this.statusCode = statusCode;
+    }
+}
+/**
+ * HTTP server errors (5xx)
+ * Used for server-side errors from external APIs
+ * Always retryable as server issues are often transient
+ */
+class HttpServerError extends AdapticUtilsError {
+    service;
+    statusCode;
+    constructor(message, service, statusCode, cause) {
+        super(message, "SERVER_ERROR", service, true, // Server errors are always retryable
+        cause);
+        this.service = service;
+        this.statusCode = statusCode;
+    }
+}
+/**
+ * Rate limit errors (429)
+ * Used when API rate limits are exceeded
+ * Always retryable, often with retry-after header information
+ */
+class RateLimitError extends AdapticUtilsError {
+    service;
+    retryAfterMs;
+    constructor(message, service, retryAfterMs, cause) {
+        super(message, "RATE_LIMIT", service, true, // Rate limit errors are always retryable
+        cause);
+        this.service = service;
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+/**
+ * WebSocket connection errors
+ * Used for WebSocket-specific connection and communication failures
+ * Retryability depends on the specific error condition
+ */
+class WebSocketError extends AdapticUtilsError {
+    service;
+    constructor(message, service, isRetryable = true, cause) {
+        super(message, "WEBSOCKET_ERROR", service, isRetryable, cause);
+        this.service = service;
+    }
+}
+/**
+ * Network errors (connection failures, DNS issues, etc.)
+ * Used for low-level network failures
+ * Always retryable as network issues are often transient
+ */
+class NetworkError extends AdapticUtilsError {
+    service;
+    constructor(message, service, cause) {
+        super(message, "NETWORK_ERROR", service, true, // Network errors are always retryable
+        cause);
+        this.service = service;
+    }
+}
+/**
+ * Unsupported brokerage provider errors
+ * Thrown when a broker operation is requested for a provider that has no
+ * implemented integration (e.g. IBKR or COINBASE before their adapters land,
+ * or an unrecognised provider string from an untyped caller).
+ * Never retryable — the caller must route to a supported provider.
+ */
+class UnsupportedBrokerError extends AdapticUtilsError {
+    provider;
+    constructor(
+    /** The provider that was requested but is not supported. */
+    provider, cause) {
+        super(`Brokerage provider "${provider}" is not supported. Supported providers: ALPACA`, "UNSUPPORTED_BROKER", "broker", false, // Unsupported providers are never retryable
+        cause);
+        this.provider = provider;
+    }
+}
+/**
+ * Data parsing and format errors
+ * Used when API responses cannot be parsed or are in unexpected format
+ * Not retryable as the data format issue needs investigation
+ */
+class DataFormatError extends AdapticUtilsError {
+    service;
+    constructor(message, service, cause) {
+        super(message, "DATA_FORMAT_ERROR", service, false, // Data format errors are not retryable
+        cause);
+        this.service = service;
+    }
+}
+
+/**
+ * Token bucket rate limiter for external API integrations
+ *
+ * Implements client-side rate limiting to prevent exceeding API quotas
+ * and ensure fair usage of external services like Alpaca, Massive, and AlphaVantage.
+ *
+ * @example
+ * ```typescript
+ * import { rateLimiters } from '@adaptic/utils';
+ *
+ * // Before making an API call
+ * await rateLimiters.alpaca.acquire();
+ * const result = await makeAlpacaApiCall();
+ * ```
+ */
+/** Number of milliseconds in one second, used for token-refill timing math. */
+const MS_PER_SECOND$1 = 1000;
+/**
+ * Minimum delay (ms) for a scheduled queue wake-up. Guards against a `0`/`NaN`
+ * delay when the token deficit rounds down, ensuring the timer always makes
+ * forward progress rather than busy-looping on the event loop.
+ */
+const MIN_WAKE_DELAY_MS = 1;
+/**
+ * Number of whole tokens required to release a single queued request. The token
+ * bucket consumes exactly one token per admitted request.
+ */
+const TOKENS_PER_REQUEST = 1;
+/**
+ * Token bucket rate limiter implementation
+ *
+ * Uses the token bucket algorithm to control the rate of API requests.
+ * Tokens are consumed on each request and refilled at a constant rate.
+ * Requests that exceed the available tokens are queued and processed
+ * when tokens become available.
+ */
+class TokenBucketRateLimiter {
+    config;
+    tokens;
+    lastRefill;
+    queue = [];
+    timeoutMs;
+    processingQueue = false;
     /**
-     * Five-minute base backoff after Alpaca's app-level 406. Long enough
-     * for Alpaca's server-side cleanup to release stale slots in typical
-     * rollover scenarios; short enough that an operator doesn't need to
-     * intervene. Mirrors the equivalent MassiveClient
-     * `MAX_CONNECTIONS_RETRY_DELAY_MS` (engine v1.0.59) so both providers
-     * behave identically under the same failure mode.
+     * Single pending timer that wakes the limiter to refill tokens and drain the
+     * queue. Without this, a queued request would only be released by a
+     * subsequent {@link acquire} call and would otherwise stall until its own
+     * timeout fired. `null` means no wake-up is currently scheduled.
      */
-    CONNECTION_LIMIT_BACKOFF_MS = 5 * 60_000;
+    wakeTimer = null;
     /**
-     * ±30 s of uniform jitter on the connection-limit backoff. Prevents
-     * a thundering-herd retry when all three streams (stock / option /
-     * crypto) hit 406 simultaneously during a deploy rollover — without
-     * jitter they'd all retry at the same wall-clock instant and could
-     * re-trip the account cap together.
+     * Creates a new rate limiter instance
+     *
+     * @param config - Rate limiter configuration
+     *
+     * @example
+     * ```typescript
+     * // Alpaca: 200 requests per minute
+     * const alpacaLimiter = new TokenBucketRateLimiter({
+     *   maxTokens: 200,
+     *   refillRate: 200 / 60, // ~3.33 per second
+     *   label: 'alpaca',
+     *   timeoutMs: 60000
+     * });
+     * ```
      */
-    CONNECTION_LIMIT_BACKOFF_JITTER_MS = 30_000;
+    constructor(config) {
+        this.config = config;
+        this.tokens = config.maxTokens;
+        this.lastRefill = Date.now();
+        this.timeoutMs = config.timeoutMs ?? 60000; // Default 60 second timeout
+    }
     /**
-     * Recency window within which a 406 is considered "still applicable"
-     * to a subsequent reconnect-schedule call. The 406 message handler
-     * stamps {@link lastConnectionLimitAt} and the `close` handler fires
-     * shortly afterwards (sub-second typically) — the window is wide
-     * enough to absorb scheduling delays without false-positives.
+     * Acquires a token for making an API request
+     *
+     * If a token is available, it is consumed immediately.
+     * If no tokens are available, the request is queued and will resolve
+     * when a token becomes available or reject if it times out.
+     *
+     * @throws {RateLimitError} If the request times out waiting for a token
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await limiter.acquire();
+     *   // Make API call
+     * } catch (error) {
+     *   if (error instanceof RateLimitError) {
+     *     // Handle rate limit timeout
+     *   }
+     * }
+     * ```
      */
-    CONNECTION_LIMIT_RECENCY_MS = 30_000;
-    setMode(mode = "production") {
-        if (mode === "sandbox") {
-            // sandbox mode
-            this.stockStreamUrl = WEBSOCKET_STREAMS.STOCKS.PRODUCTION; // sandbox uses production for stocks
-            this.optionStreamUrl = getOptionsStreamUrl("SANDBOX");
-            this.cryptoStreamUrl = getCryptoStreamUrl("SANDBOX");
-        }
-        else if (mode === "test") {
-            // test mode, can only use ticker FAKEPACA
-            this.stockStreamUrl = getStockStreamUrl("TEST");
-            this.optionStreamUrl = getOptionsStreamUrl("PRODUCTION"); // there's no test mode for options
-            this.cryptoStreamUrl = getCryptoStreamUrl("PRODUCTION"); // there's no test mode for crypto
-        }
-        else {
-            // production
-            this.stockStreamUrl = getStockStreamUrl("PRODUCTION");
-            this.optionStreamUrl = getOptionsStreamUrl("PRODUCTION");
-            this.cryptoStreamUrl = getCryptoStreamUrl("PRODUCTION");
+    async acquire() {
+        const logger = getLogger();
+        this.refill();
+        if (this.tokens > 0) {
+            this.tokens--;
+            logger.debug(`Rate limit token acquired for ${this.config.label}`, {
+                remainingTokens: this.tokens,
+                queueLength: this.queue.length,
+            });
+            return;
         }
+        // No tokens available, queue the request
+        logger.debug(`Rate limit reached for ${this.config.label}, queuing request`, {
+            queueLength: this.queue.length,
+        });
+        return new Promise((resolve, reject) => {
+            const timeoutHandle = setTimeout(() => {
+                // Remove from queue on timeout
+                const index = this.queue.findIndex((req) => req.timeoutHandle === timeoutHandle);
+                if (index !== -1) {
+                    this.queue.splice(index, 1);
+                }
+                const error = new RateLimitError(`Rate limit timeout for ${this.config.label} after ${this.timeoutMs}ms`, this.config.label, undefined);
+                logger.warn(`Rate limit timeout for ${this.config.label}`, {
+                    queueLength: this.queue.length,
+                    timeoutMs: this.timeoutMs,
+                });
+                reject(error);
+            }, this.timeoutMs);
+            this.queue.push({ resolve, reject, timeoutHandle });
+            // Ensure the queue is actively drained even if no further acquire() calls
+            // arrive: schedule a wake-up to refill tokens and release this request.
+            this.scheduleQueueWake();
+        });
     }
-    getMode() {
-        if (this.stockStreamUrl.includes("sandbox")) {
-            return "sandbox";
-        }
-        else if (this.stockStreamUrl.includes("test")) {
-            return "test";
+    /**
+     * Schedules a single wake-up timer that refills tokens and drains the queue.
+     *
+     * The delay is the time required to accrue the tokens still needed to release
+     * the next queued request at the configured refill rate. Only one timer is
+     * ever outstanding (guarded by {@link wakeTimer}); the timer is `unref`'d so
+     * it never keeps the Node.js process alive on its own. When it fires it
+     * refills, drains what it can, and re-arms itself if work remains.
+     */
+    scheduleQueueWake() {
+        // A wake-up is already pending, or there is nothing to wake for.
+        if (this.wakeTimer !== null || this.queue.length === 0) {
+            return;
         }
-        else {
-            return "production";
+        const tokensNeeded = Math.max(0, TOKENS_PER_REQUEST - this.tokens);
+        const deficitMs = Math.max(MIN_WAKE_DELAY_MS, Math.ceil((tokensNeeded / this.config.refillRate) * MS_PER_SECOND$1));
+        const timer = setTimeout(() => {
+            this.wakeTimer = null;
+            // refill() drains the queue via processQueue(); if requests remain
+            // afterwards, processQueue() re-arms the wake-up.
+            this.refill();
+        }, deficitMs);
+        // Do not let a pending rate-limiter wake-up keep the process alive.
+        if (typeof timer.unref === "function") {
+            timer.unref();
         }
+        this.wakeTimer = timer;
     }
-    constructor() {
-        super();
-        // Validate credentials from environment variables before initializing
-        // Use throwOnMissing: false to allow initialization during build time
-        // when env vars are not available. Features will be unavailable until
-        // credentials are provided at runtime.
-        const apiKey = process.env.ALPACA_API_KEY || "";
-        const apiSecret = process.env.ALPACA_API_SECRET || process.env.ALPACA_SECRET_KEY || "";
-        this.credentialsValid = validateAlpacaCredentials({
-            apiKey,
-            apiSecret,
-            isPaper: process.env.ALPACA_ACCOUNT_TYPE === "PAPER",
-        }, { throwOnMissing: false });
-        this.dataURL = MARKET_DATA_API.STOCKS;
-        this.apiURL =
-            process.env.ALPACA_ACCOUNT_TYPE === "PAPER"
-                ? getTradingApiUrl("PAPER")
-                : getTradingApiUrl("LIVE"); // used by some, e.g. getAssets
-        this.v1beta1url = MARKET_DATA_API.OPTIONS; // used for options endpoints
-        this.setMode("production"); // sets stockStreamUrl and optionStreamUrl
-        this.headers = {
-            "APCA-API-KEY-ID": apiKey,
-            "APCA-API-SECRET-KEY": apiSecret,
-            "Content-Type": "application/json",
-        };
-    }
-    static getInstance() {
-        if (!AlpacaMarketDataAPI.instance) {
-            AlpacaMarketDataAPI.instance = new AlpacaMarketDataAPI();
+    /**
+     * Clears any pending wake-up timer.
+     */
+    clearWakeTimer() {
+        if (this.wakeTimer !== null) {
+            clearTimeout(this.wakeTimer);
+            this.wakeTimer = null;
         }
-        return AlpacaMarketDataAPI.instance;
-    }
-    on(event, listener) {
-        return super.on(event, listener);
     }
-    emit(event, ...args) {
-        return super.emit(event, ...args);
+    /**
+     * Refills tokens based on elapsed time and processes queued requests
+     *
+     * Tokens are refilled at the configured rate up to the maximum capacity.
+     * If tokens are available after refilling, queued requests are processed.
+     */
+    refill() {
+        const now = Date.now();
+        const elapsed = (now - this.lastRefill) / 1000; // Convert to seconds
+        const tokensToAdd = elapsed * this.config.refillRate;
+        this.tokens = Math.min(this.config.maxTokens, this.tokens + tokensToAdd);
+        this.lastRefill = now;
+        // Process queued requests if we have tokens
+        this.processQueue();
     }
-    connect(streamType) {
-        let url;
-        if (streamType === "stock") {
-            url = this.stockStreamUrl;
-        }
-        else if (streamType === "option") {
-            url = this.optionStreamUrl;
-        }
-        else {
-            url = this.cryptoStreamUrl;
-        }
-        const apiKey = process.env.ALPACA_API_KEY || "";
-        const apiSecret = process.env.ALPACA_API_SECRET || process.env.ALPACA_SECRET_KEY || "";
-        if (!apiKey || !apiSecret) {
-            log$l(`Cannot connect ${streamType} stream: missing Alpaca credentials (ALPACA_API_KEY=${apiKey ? "set" : "MISSING"}, ALPACA_API_SECRET/ALPACA_SECRET_KEY=${apiSecret ? "set" : "MISSING"})`, { type: "error" });
+    /**
+     * Processes queued requests when tokens are available
+     *
+     * Prevents concurrent queue processing to ensure FIFO order.
+     */
+    processQueue() {
+        // Prevent concurrent queue processing
+        if (this.processingQueue) {
             return;
         }
-        const ws = new WebSocket(url);
-        if (streamType === "stock") {
-            this.stockWs = ws;
+        this.processingQueue = true;
+        const logger = getLogger();
+        try {
+            while (this.queue.length > 0 && this.tokens > 0) {
+                this.tokens--;
+                const next = this.queue.shift();
+                if (next) {
+                    clearTimeout(next.timeoutHandle);
+                    next.resolve();
+                    logger.debug(`Processed queued request for ${this.config.label}`, {
+                        remainingTokens: this.tokens,
+                        remainingQueue: this.queue.length,
+                    });
+                }
+            }
         }
-        else if (streamType === "option") {
-            this.optionWs = ws;
+        finally {
+            this.processingQueue = false;
+        }
+        // Keep the wake-up state consistent with the queue: if requests are still
+        // waiting (tokens ran out mid-drain), ensure a wake-up is armed; otherwise
+        // release any pending timer so it cannot fire needlessly.
+        if (this.queue.length > 0) {
+            this.scheduleQueueWake();
         }
         else {
-            this.cryptoWs = ws;
+            this.clearWakeTimer();
         }
-        ws.on("open", () => {
-            log$l(`${streamType} stream connected`, { type: "info" });
-            const authMessage = {
-                action: "auth",
-                key: apiKey,
-                secret: apiSecret,
-            };
-            ws.send(JSON.stringify(authMessage));
-        });
-        ws.on("message", (data) => {
-            const rawData = data.toString();
-            let messages;
-            try {
-                messages = JSON.parse(rawData);
-            }
-            catch (e) {
-                log$l(`${streamType} stream received invalid JSON: ${rawData.substring(0, 200)}`, { type: "error" });
-                return;
-            }
-            for (const message of messages) {
-                if (message.T === "success" && message.msg === "authenticated") {
-                    log$l(`${streamType} stream authenticated`, { type: "info" });
-                    this.reconnectAttempts[streamType] = 0;
-                    this.sendSubscription(streamType);
-                }
-                else if (message.T === "success" && message.msg === "connected") {
-                    log$l(`${streamType} stream connected message received`, {
-                        type: "debug",
-                    });
-                }
-                else if (message.T === "subscription") {
-                    log$l(`${streamType} subscription confirmed: trades=${message.trades?.length || 0}, quotes=${message.quotes?.length || 0}, bars=${message.bars?.length || 0}`, { type: "info" });
-                }
-                else if (message.T === "error") {
-                    log$l(`${streamType} stream error: ${message.msg} (code: ${message.code}, raw: ${JSON.stringify(message)})`, { type: "error" });
-                    // Alpaca code 406: "connection limit exceeded" — account-wide
-                    // concurrent-WS cap reached. The Alpaca server will close the
-                    // socket immediately after this frame, which would normally
-                    // trigger our standard sub-second exponential reconnect chain
-                    // (1 s, 2 s, 4 s, 8 s, 16 s, 30 s × 5) — exactly the wrong
-                    // behaviour against a rate-limit response. Stamp the recency
-                    // marker so {@link scheduleReconnect} switches to the
-                    // 5-minute jittered backoff instead.
-                    if (typeof message.code === "number" &&
-                        message.code === 406) {
-                        this.lastConnectionLimitAt[streamType] = Date.now();
-                    }
-                }
-                else if (message.S) {
-                    super.emit(`${streamType}-${message.T}`, message);
-                    super.emit(`${streamType}-data`, message);
-                }
-                else {
-                    log$l(`${streamType} received unknown message type: ${JSON.stringify(message)}`, { type: "debug" });
-                }
-            }
-        });
-        ws.on("close", (code) => {
-            log$l(`${streamType} stream disconnected (code: ${code})`, {
-                type: "warn",
-            });
-            if (streamType === "stock") {
-                this.stockWs = null;
-            }
-            else if (streamType === "option") {
-                this.optionWs = null;
-            }
-            else {
-                this.cryptoWs = null;
-            }
-            // Reconnect with exponential backoff (unless intentionally closed with code 1000)
-            if (code !== 1000) {
-                this.scheduleReconnect(streamType);
-            }
-        });
-        ws.on("error", (error) => {
-            log$l(`${streamType} stream error: ${error.message}`, { type: "error" });
-        });
     }
-    scheduleReconnect(streamType) {
-        // 406-recovery fast path. When the most recent close was preceded
-        // by an Alpaca app-level 406 ("connection limit exceeded"), the
-        // standard sub-second exponential ramp is exactly wrong — it
-        // hammers the rate-limit endpoint and prolongs the slot pressure.
-        // Use a 5-minute jittered backoff instead and reset the normal
-        // attempt counter so we don't fall off the end of maxAttempts
-        // and permanently give up on a transient rollover blip.
-        const connectionLimitAt = this.lastConnectionLimitAt[streamType];
-        const isRecentConnectionLimit = typeof connectionLimitAt === "number" &&
-            Date.now() - connectionLimitAt <= this.CONNECTION_LIMIT_RECENCY_MS;
-        if (isRecentConnectionLimit) {
-            const jitter = Math.floor((Math.random() - 0.5) *
-                2 *
-                this.CONNECTION_LIMIT_BACKOFF_JITTER_MS);
-            const delayMs = this.CONNECTION_LIMIT_BACKOFF_MS + jitter;
-            // Reset normal attempt counter so the next 406 retry doesn't
-            // inherit a stale exponential cap.
-            this.reconnectAttempts[streamType] = 0;
-            // Consume the recency marker — subsequent reconnects fall back
-            // to the standard exponential path unless a new 406 arrives.
-            delete this.lastConnectionLimitAt[streamType];
-            log$l(`${streamType} stream: Alpaca 406 connection-limit recovery — backing off ${Math.round(delayMs / 1000)}s before retry to allow account-wide slot release`, { type: "warn" });
-            if (this.reconnectTimers[streamType]) {
-                clearTimeout(this.reconnectTimers[streamType]);
-            }
-            this.reconnectTimers[streamType] = setTimeout(() => {
-                log$l(`${streamType} stream: attempting reconnect after 406-recovery backoff`, { type: "info" });
-                this.connect(streamType);
-            }, delayMs);
-            return;
-        }
-        const attempts = this.reconnectAttempts[streamType] ?? 0;
-        const maxAttempts = 10;
-        if (attempts >= maxAttempts) {
-            log$l(`${streamType} stream: max reconnect attempts (${maxAttempts}) reached, giving up`, { type: "error" });
-            return;
-        }
-        // Exponential backoff: 1s, 2s, 4s, 8s, 16s, 30s (capped)
-        const delayMs = Math.min(1000 * Math.pow(2, attempts), 30000);
-        this.reconnectAttempts[streamType] = attempts + 1;
-        log$l(`${streamType} stream: scheduling reconnect attempt ${attempts + 1}/${maxAttempts} in ${delayMs}ms`, { type: "info" });
-        // Clear any existing reconnect timer for this stream
-        if (this.reconnectTimers[streamType]) {
-            clearTimeout(this.reconnectTimers[streamType]);
-        }
-        this.reconnectTimers[streamType] = setTimeout(() => {
-            log$l(`${streamType} stream: reconnecting (attempt ${attempts + 1}/${maxAttempts})`, { type: "info" });
-            this.connect(streamType);
-        }, delayMs);
+    /**
+     * Gets the current number of available tokens
+     *
+     * @returns Number of tokens currently available
+     */
+    getAvailableTokens() {
+        this.refill();
+        return Math.floor(this.tokens);
     }
-    sendSubscription(streamType) {
-        let ws;
-        let subscriptions;
-        if (streamType === "stock") {
-            ws = this.stockWs;
-            subscriptions = this.stockSubscriptions;
-        }
-        else if (streamType === "option") {
-            ws = this.optionWs;
-            subscriptions = this.optionSubscriptions;
-        }
-        else {
-            ws = this.cryptoWs;
-            subscriptions = this.cryptoSubscriptions;
+    /**
+     * Gets the current queue length
+     *
+     * @returns Number of requests waiting for tokens
+     */
+    getQueueLength() {
+        return this.queue.length;
+    }
+    /**
+     * Clears all queued requests and resets the token bucket
+     *
+     * All queued requests will be rejected with a RateLimitError.
+     * Useful for cleanup or when changing rate limit configurations.
+     */
+    reset() {
+        const logger = getLogger();
+        // Reject all queued requests
+        for (const request of this.queue) {
+            clearTimeout(request.timeoutHandle);
+            request.reject(new RateLimitError(`Rate limiter reset for ${this.config.label}`, this.config.label, undefined));
         }
-        log$l(`sendSubscription called for ${streamType} (wsReady=${ws?.readyState === WebSocket.OPEN}, trades=${subscriptions.trades?.length || 0}, quotes=${subscriptions.quotes?.length || 0}, bars=${subscriptions.bars?.length || 0})`, {
-            type: "debug",
+        this.clearWakeTimer();
+        this.queue = [];
+        this.tokens = this.config.maxTokens;
+        this.lastRefill = Date.now();
+        this.processingQueue = false;
+        logger.info(`Rate limiter reset for ${this.config.label}`, {
+            maxTokens: this.config.maxTokens,
         });
-        if (ws && ws.readyState === WebSocket.OPEN) {
-            const subMessagePayload = {};
-            if (subscriptions.trades.length > 0) {
-                subMessagePayload.trades = subscriptions.trades;
-            }
-            if (subscriptions.quotes.length > 0) {
-                subMessagePayload.quotes = subscriptions.quotes;
-            }
-            if (subscriptions.bars.length > 0) {
-                subMessagePayload.bars = subscriptions.bars;
-            }
-            if (Object.keys(subMessagePayload).length > 0) {
-                const subMessage = {
-                    action: "subscribe",
-                    ...subMessagePayload,
-                };
-                const messageJson = JSON.stringify(subMessage);
-                log$l(`Sending ${streamType} subscription: ${messageJson}`, {
-                    type: "info",
-                });
-                ws.send(messageJson);
-            }
-            else {
-                log$l(`No ${streamType} subscriptions to send (all arrays empty)`, {
-                    type: "debug",
-                });
-            }
+    }
+}
+/**
+ * Pre-configured rate limiters for common external APIs
+ *
+ * These limiters are configured based on the documented rate limits
+ * for each service. Adjust the configurations if you have different
+ * tier access or if limits change.
+ *
+ * @example
+ * ```typescript
+ * import { rateLimiters } from '@adaptic/utils';
+ *
+ * // Use before making API calls
+ * await rateLimiters.alpaca.acquire();
+ * await rateLimiters.massive.acquire();
+ * await rateLimiters.alphaVantage.acquire();
+ * ```
+ */
+const rateLimiters = {
+    /**
+     * Alpaca API rate limiter
+     *
+     * Configured for 1000 requests per minute (paid tier).
+     * The token bucket allows burst up to maxTokens, then refills at the steady rate.
+     * See: https://alpaca.markets/docs/api-references/trading-api/#rate-limit
+     */
+    alpaca: new TokenBucketRateLimiter({
+        maxTokens: 1000,
+        refillRate: 1000 / 60, // 1000 requests per 60 seconds (~16.67/sec)
+        label: "alpaca",
+        timeoutMs: 60000,
+    }),
+    /**
+     * Massive.com API rate limiter
+     *
+     * Configured generously for paid unlimited tier. The bucket exists only as a
+     * safety net against runaway loops — the 1000 token burst and 500/sec refill
+     * should never be hit under normal operation. If the paid plan truly has no
+     * hard limit, this just prevents accidental self-DDoS.
+     */
+    massive: new TokenBucketRateLimiter({
+        maxTokens: 1000,
+        refillRate: 500, // 500 tokens/sec refill — effectively unlimited for paid tier
+        label: "massive",
+        timeoutMs: 30000,
+    }),
+    /**
+     * AlphaVantage API rate limiter
+     *
+     * Configured for 5 requests per minute (free tier).
+     * For premium tier (75/min), create a custom limiter:
+     *
+     * @example
+     * ```typescript
+     * const premiumAV = new TokenBucketRateLimiter({
+     *   maxTokens: 75,
+     *   refillRate: 75 / 60,
+     *   label: 'alphaVantage-premium',
+     *   timeoutMs: 60000,
+     * });
+     * ```
+     *
+     * See: https://www.alphavantage.co/premium/
+     */
+    alphaVantage: new TokenBucketRateLimiter({
+        maxTokens: 5,
+        refillRate: 5 / 60, // 5 requests per 60 seconds (~0.083/sec)
+        label: "alphaVantage",
+        timeoutMs: 60000,
+    }),
+};
+
+/**
+ * Bounded retry for TRANSIENT network faults on Alpaca market-data reads.
+ *
+ * 2026-07-30: the engine logged 637 `TypeError: fetch failed` / `read
+ * ECONNRESET` errors against `/v2/stocks/bars` in a single session (~4 per
+ * minute). Every OTHER Alpaca/Massive client in this package already routes
+ * transient faults through {@link isTransientNetworkError} — this client was
+ * the one that never adopted it, so a single reset socket killed the whole
+ * read. Those failures surface in the engine's market-tape prompt context and
+ * its intraday direction/path resolvers, so the decision model judged with a
+ * blind tape: raw confidence collapsed from a 0.677 median to a degenerate
+ * ~0.504 band, the entire distribution fell below the 0.55 admission floor,
+ * and live participation went to near zero.
+ *
+ * `ECONNRESET` on a keep-alive pool is the classic idle-socket race — the
+ * server closes a pooled connection while the client dispatches onto it. It
+ * is transient by construction and safe to retry on an idempotent GET.
+ */
+const TRANSIENT_NETWORK_RETRY_ATTEMPTS = 3;
+/** Base backoff (ms); doubled per attempt with full jitter. */
+const TRANSIENT_NETWORK_RETRY_BASE_MS = 120;
+/** Full-jitter backoff so concurrent fan-out retries do not resonate. */
+function transientRetryDelayMs(attempt) {
+    const ceiling = TRANSIENT_NETWORK_RETRY_BASE_MS * 2 ** attempt;
+    return Math.floor(Math.random() * ceiling);
+}
+const log$l = (message, options = { type: "info" }) => {
+    log$m(message, { ...options, source: "AlpacaMarketDataAPI" });
+};
+// Default settings for market data API
+const DEFAULT_ADJUSTMENT = "all";
+// Data feed tier. SIP is full US-market-consolidated feed (requires a paid
+// Alpaca market-data subscription). IEX is the free tier — single-exchange,
+// delayed. Engine deploys running on IEX-only accounts hit chronic HTTP 403
+// ("subscription does not permit querying recent SIP data") at ~100/min when
+// this defaulted to "sip", which saturated Railway's per-replica log ingest
+// and hid steady-state signal. The ALPACA_MARKET_DATA_FEED env var overrides
+// the default. Fall back to "iex" so the free tier is safe by default; LIVE
+// deployments with SIP entitlements set ALPACA_MARKET_DATA_FEED=sip in their
+// environment to restore full data access. Per-call overrides (the optional
+// `feed` argument on getOptions*/getLatestBars/etc.) still win.
+const DEFAULT_FEED$1 = (process.env.ALPACA_MARKET_DATA_FEED || "iex");
+const DEFAULT_CURRENCY$1 = "USD";
+/**
+ * Singleton class for interacting with Alpaca Market Data API
+ * Provides methods for fetching historical bars, latest bars, last trades, latest trades, latest quotes, and latest quote for a single symbol
+ */
+class AlpacaMarketDataAPI extends EventEmitter {
+    static instance;
+    headers;
+    dataURL;
+    apiURL;
+    v1beta1url;
+    /** Whether API credentials are valid and available. False during build time when env vars are missing. */
+    credentialsValid = false;
+    stockStreamUrl = getStockStreamUrl("PRODUCTION"); // production values
+    optionStreamUrl = getOptionsStreamUrl("PRODUCTION"); // production values
+    cryptoStreamUrl = getCryptoStreamUrl("PRODUCTION"); // production values
+    stockWs = null;
+    optionWs = null;
+    cryptoWs = null;
+    stockSubscriptions = {
+        trades: [],
+        quotes: [],
+        bars: [],
+    };
+    optionSubscriptions = {
+        trades: [],
+        quotes: [],
+        bars: [],
+    };
+    cryptoSubscriptions = {
+        trades: [],
+        quotes: [],
+        bars: [],
+    };
+    reconnectAttempts = {};
+    reconnectTimers = {};
+    /**
+     * Wall-clock timestamp of the most recent Alpaca app-level error code
+     * 406 ("connection limit exceeded") received on each stream. Used by
+     * {@link scheduleReconnect} to apply a long backoff with jitter rather
+     * than the normal sub-second exponential ramp — without this, hitting
+     * Alpaca's account-wide concurrent-connection cap (typical for blue/green
+     * deploy rollovers where the old pod's WS slots haven't been released
+     * yet) produced a 10-attempt retry storm that compounded the slot
+     * pressure and consumed the per-account connection quota across the
+     * organisation.
+     *
+     * Cleared once the long-backoff retry is scheduled so that subsequent
+     * normal failures fall back to the standard sub-second exponential.
+     *
+     * @see CONNECTION_LIMIT_BACKOFF_MS / CONNECTION_LIMIT_BACKOFF_JITTER_MS
+     */
+    lastConnectionLimitAt = {};
+    /**
+     * Five-minute base backoff after Alpaca's app-level 406. Long enough
+     * for Alpaca's server-side cleanup to release stale slots in typical
+     * rollover scenarios; short enough that an operator doesn't need to
+     * intervene. Mirrors the equivalent MassiveClient
+     * `MAX_CONNECTIONS_RETRY_DELAY_MS` (engine v1.0.59) so both providers
+     * behave identically under the same failure mode.
+     */
+    CONNECTION_LIMIT_BACKOFF_MS = 5 * 60_000;
+    /**
+     * ±30 s of uniform jitter on the connection-limit backoff. Prevents
+     * a thundering-herd retry when all three streams (stock / option /
+     * crypto) hit 406 simultaneously during a deploy rollover — without
+     * jitter they'd all retry at the same wall-clock instant and could
+     * re-trip the account cap together.
+     */
+    CONNECTION_LIMIT_BACKOFF_JITTER_MS = 30_000;
+    /**
+     * Recency window within which a 406 is considered "still applicable"
+     * to a subsequent reconnect-schedule call. The 406 message handler
+     * stamps {@link lastConnectionLimitAt} and the `close` handler fires
+     * shortly afterwards (sub-second typically) — the window is wide
+     * enough to absorb scheduling delays without false-positives.
+     */
+    CONNECTION_LIMIT_RECENCY_MS = 30_000;
+    setMode(mode = "production") {
+        if (mode === "sandbox") {
+            // sandbox mode
+            this.stockStreamUrl = WEBSOCKET_STREAMS.STOCKS.PRODUCTION; // sandbox uses production for stocks
+            this.optionStreamUrl = getOptionsStreamUrl("SANDBOX");
+            this.cryptoStreamUrl = getCryptoStreamUrl("SANDBOX");
         }
-        else if (ws && ws.readyState === WebSocket.CONNECTING) {
-            // WebSocket is still establishing. Subscriptions are already persisted
-            // in `subscriptions` and will be dispatched automatically by the
-            // auth-success handler once the stream authenticates. This is the
-            // expected transient state during startup / reconnect — not a failure.
-            const queuedTotal = (subscriptions.trades?.length || 0) +
-                (subscriptions.quotes?.length || 0) +
-                (subscriptions.bars?.length || 0);
-            log$l(`${streamType} subscription queued (${queuedTotal} channel entries); will dispatch after WebSocket authenticates`, { type: "debug" });
+        else if (mode === "test") {
+            // test mode, can only use ticker FAKEPACA
+            this.stockStreamUrl = getStockStreamUrl("TEST");
+            this.optionStreamUrl = getOptionsStreamUrl("PRODUCTION"); // there's no test mode for options
+            this.cryptoStreamUrl = getCryptoStreamUrl("PRODUCTION"); // there's no test mode for crypto
         }
         else {
-            const stateLabel = ws === null
-                ? "null"
-                : ws.readyState === WebSocket.CLOSING
-                    ? "CLOSING"
-                    : ws.readyState === WebSocket.CLOSED
-                        ? "CLOSED"
-                        : `unknown(${ws.readyState})`;
-            log$l(`Cannot send ${streamType} subscription: WebSocket in ${stateLabel} state`, { type: "warn" });
+            // production
+            this.stockStreamUrl = getStockStreamUrl("PRODUCTION");
+            this.optionStreamUrl = getOptionsStreamUrl("PRODUCTION");
+            this.cryptoStreamUrl = getCryptoStreamUrl("PRODUCTION");
         }
     }
-    connectStockStream() {
-        if (!this.stockWs) {
-            this.connect("stock");
+    getMode() {
+        if (this.stockStreamUrl.includes("sandbox")) {
+            return "sandbox";
         }
-    }
-    connectOptionStream() {
-        if (!this.optionWs) {
-            this.connect("option");
+        else if (this.stockStreamUrl.includes("test")) {
+            return "test";
         }
-    }
-    connectCryptoStream() {
-        if (!this.cryptoWs) {
-            this.connect("crypto");
+        else {
+            return "production";
         }
     }
-    disconnectStockStream() {
-        if (this.stockWs) {
-            this.stockWs.close();
-        }
+    constructor() {
+        super();
+        // Validate credentials from environment variables before initializing
+        // Use throwOnMissing: false to allow initialization during build time
+        // when env vars are not available. Features will be unavailable until
+        // credentials are provided at runtime.
+        const apiKey = process.env.ALPACA_API_KEY || "";
+        const apiSecret = process.env.ALPACA_API_SECRET || process.env.ALPACA_SECRET_KEY || "";
+        this.credentialsValid = validateAlpacaCredentials({
+            apiKey,
+            apiSecret,
+            isPaper: process.env.ALPACA_ACCOUNT_TYPE === "PAPER",
+        }, { throwOnMissing: false });
+        this.dataURL = MARKET_DATA_API.STOCKS;
+        this.apiURL =
+            process.env.ALPACA_ACCOUNT_TYPE === "PAPER"
+                ? getTradingApiUrl("PAPER")
+                : getTradingApiUrl("LIVE"); // used by some, e.g. getAssets
+        this.v1beta1url = MARKET_DATA_API.OPTIONS; // used for options endpoints
+        this.setMode("production"); // sets stockStreamUrl and optionStreamUrl
+        this.headers = {
+            "APCA-API-KEY-ID": apiKey,
+            "APCA-API-SECRET-KEY": apiSecret,
+            "Content-Type": "application/json",
+        };
     }
-    disconnectOptionStream() {
-        if (this.optionWs) {
-            this.optionWs.close();
+    static getInstance() {
+        if (!AlpacaMarketDataAPI.instance) {
+            AlpacaMarketDataAPI.instance = new AlpacaMarketDataAPI();
         }
+        return AlpacaMarketDataAPI.instance;
     }
-    disconnectCryptoStream() {
-        if (this.cryptoWs) {
-            this.cryptoWs.close();
-        }
+    on(event, listener) {
+        return super.on(event, listener);
     }
-    /**
-     * Check if a specific stream is connected
-     * @param streamType - The type of stream to check
-     * @returns True if the stream is connected
-     */
-    isStreamConnected(streamType) {
-        if (streamType === "stock") {
-            return (this.stockWs !== null && this.stockWs.readyState === WebSocket.OPEN);
-        }
-        else if (streamType === "option") {
-            return (this.optionWs !== null && this.optionWs.readyState === WebSocket.OPEN);
-        }
-        else {
-            return (this.cryptoWs !== null && this.cryptoWs.readyState === WebSocket.OPEN);
-        }
+    emit(event, ...args) {
+        return super.emit(event, ...args);
     }
-    subscribe(streamType, subscriptions) {
-        let currentSubscriptions;
+    connect(streamType) {
+        let url;
         if (streamType === "stock") {
-            currentSubscriptions = this.stockSubscriptions;
+            url = this.stockStreamUrl;
         }
         else if (streamType === "option") {
-            currentSubscriptions = this.optionSubscriptions;
+            url = this.optionStreamUrl;
         }
         else {
-            currentSubscriptions = this.cryptoSubscriptions;
-        }
-        Object.entries(subscriptions).forEach(([key, value]) => {
-            if (value) {
-                currentSubscriptions[key] = [
-                    ...new Set([...(currentSubscriptions[key] || []), ...value]),
-                ];
-            }
-        });
-        this.sendSubscription(streamType);
-    }
-    unsubscribe(streamType, subscriptions) {
-        let currentSubscriptions;
-        if (streamType === "stock") {
-            currentSubscriptions = this.stockSubscriptions;
-        }
-        else if (streamType === "option") {
-            currentSubscriptions = this.optionSubscriptions;
+            url = this.cryptoStreamUrl;
         }
-        else {
-            currentSubscriptions = this.cryptoSubscriptions;
+        const apiKey = process.env.ALPACA_API_KEY || "";
+        const apiSecret = process.env.ALPACA_API_SECRET || process.env.ALPACA_SECRET_KEY || "";
+        if (!apiKey || !apiSecret) {
+            log$l(`Cannot connect ${streamType} stream: missing Alpaca credentials (ALPACA_API_KEY=${apiKey ? "set" : "MISSING"}, ALPACA_API_SECRET/ALPACA_SECRET_KEY=${apiSecret ? "set" : "MISSING"})`, { type: "error" });
+            return;
         }
-        Object.entries(subscriptions).forEach(([key, value]) => {
-            if (value) {
-                currentSubscriptions[key] = (currentSubscriptions[key] || []).filter((s) => !value.includes(s));
-            }
-        });
-        const unsubMessage = {
-            action: "unsubscribe",
-            ...subscriptions,
-        };
-        let ws;
+        const ws = new WebSocket(url);
         if (streamType === "stock") {
-            ws = this.stockWs;
+            this.stockWs = ws;
         }
         else if (streamType === "option") {
-            ws = this.optionWs;
+            this.optionWs = ws;
         }
         else {
-            ws = this.cryptoWs;
-        }
-        if (ws && ws.readyState === WebSocket.OPEN) {
-            ws.send(JSON.stringify(unsubMessage));
-        }
-    }
-    async makeRequest(endpoint, method = "GET", params, baseUrlName = "data") {
-        const baseUrl = baseUrlName === "data"
-            ? this.dataURL
-            : baseUrlName === "api"
-                ? this.apiURL
-                : this.v1beta1url;
-        const url = new URL(`${baseUrl}${endpoint}`);
-        try {
-            if (params) {
-                Object.entries(params).forEach(([key, value]) => {
-                    if (Array.isArray(value)) {
-                        url.searchParams.append(key, value.join(","));
-                    }
-                    else if (value !== undefined && value !== null) {
-                        url.searchParams.append(key, value.toString());
-                    }
-                });
-            }
-            // Gate all Alpaca market-data calls through the shared 1000/min token
-            // bucket so concurrent callers (bar fetches, quotes, options, snapshots)
-            // can't overrun Alpaca's server-side rate limit. Prior to this, parallel
-            // historical-bar fan-out produced ~125 server-side 429s per minute.
-            await rateLimiters.alpaca.acquire();
-            const response = await fetch(url.toString(), {
-                method,
-                headers: this.headers,
-                signal: createTimeoutSignal(DEFAULT_TIMEOUTS.ALPACA_API),
-            });
-            if (!response.ok) {
-                const errorText = await response.text();
-                log$l(`Market Data API error (${response.status}): ${errorText}`, {
-                    type: "error",
-                });
-                throw new Error(`Market Data API error (${response.status}): ${errorText}`);
-            }
-            const data = await response.json();
-            return data;
-        }
-        catch (err) {
-            const error = err;
-            log$l(`Error in makeRequest: ${error.message}. Endpoint: ${endpoint}. Url: ${url.toString()}`, { type: "error" });
-            if (error instanceof TypeError) {
-                log$l(`Network error details: ${error.stack}`, { type: "error" });
-            }
-            throw error;
+            this.cryptoWs = ws;
         }
-    }
-    /**
-     * Get historical OHLCV bars for specified symbols, including pre-market and post-market data
-     * Automatically handles pagination to fetch all available data
-     * @param params Parameters for historical bars request
-     * @returns Historical bars data with all pages combined
-     */
-    async getHistoricalBars(params) {
-        const symbols = params.symbols;
-        const symbolsStr = symbols.join(",");
-        const allBars = {};
-        let pageToken = null;
-        let hasMorePages = true;
-        let totalBarsCount = 0;
-        let pageCount = 0;
-        let currency = "";
-        // Initialize bar arrays for each symbol
-        symbols.forEach((symbol) => {
-            allBars[symbol] = [];
-        });
-        log$l(`Starting historical bars fetch for ${symbolsStr} (${params.timeframe}, ${params.start || "no start"} to ${params.end || "no end"})`, {
-            type: "info",
-        });
-        while (hasMorePages) {
-            pageCount++;
-            const requestParams = {
-                ...params,
-                adjustment: DEFAULT_ADJUSTMENT,
-                feed: DEFAULT_FEED$1,
-                ...(pageToken && { page_token: pageToken }),
+        ws.on("open", () => {
+            log$l(`${streamType} stream connected`, { type: "info" });
+            const authMessage = {
+                action: "auth",
+                key: apiKey,
+                secret: apiSecret,
             };
-            const response = await this.makeRequest("/stocks/bars", "GET", requestParams);
-            if (!response.bars) {
-                log$l(`No bars data found in response for ${symbolsStr}`, {
-                    type: "warn",
-                });
-                break;
+            ws.send(JSON.stringify(authMessage));
+        });
+        ws.on("message", (data) => {
+            const rawData = data.toString();
+            let messages;
+            try {
+                messages = JSON.parse(rawData);
             }
-            // Track currency from first response
-            if (!currency) {
-                currency = response.currency;
+            catch (e) {
+                log$l(`${streamType} stream received invalid JSON: ${rawData.substring(0, 200)}`, { type: "error" });
+                return;
             }
-            // Combine bars for each symbol
-            let pageBarsCount = 0;
-            let earliestTimestamp = null;
-            let latestTimestamp = null;
-            Object.entries(response.bars).forEach(([symbol, bars]) => {
-                if (bars && bars.length > 0) {
-                    allBars[symbol] = [...allBars[symbol], ...bars];
-                    pageBarsCount += bars.length;
-                    // Track date range for this page
-                    bars.forEach((bar) => {
-                        const barDate = new Date(bar.t);
-                        if (!earliestTimestamp || barDate < earliestTimestamp) {
-                            earliestTimestamp = barDate;
-                        }
-                        if (!latestTimestamp || barDate > latestTimestamp) {
-                            latestTimestamp = barDate;
-                        }
+            for (const message of messages) {
+                if (message.T === "success" && message.msg === "authenticated") {
+                    log$l(`${streamType} stream authenticated`, { type: "info" });
+                    this.reconnectAttempts[streamType] = 0;
+                    this.sendSubscription(streamType);
+                }
+                else if (message.T === "success" && message.msg === "connected") {
+                    log$l(`${streamType} stream connected message received`, {
+                        type: "debug",
                     });
                 }
-            });
-            totalBarsCount += pageBarsCount;
-            pageToken = response.next_page_token || null;
-            hasMorePages = !!pageToken;
-            // Enhanced logging with date range and progress info
-            const dateRangeStr = earliestTimestamp && latestTimestamp
-                ? `${earliestTimestamp.toLocaleDateString("en-US", { timeZone: "America/New_York" })} to ${latestTimestamp.toLocaleDateString("en-US", { timeZone: "America/New_York" })}`
-                : "unknown range";
-            log$l(`Page ${pageCount}: Fetched ${pageBarsCount.toLocaleString()} bars (total: ${totalBarsCount.toLocaleString()}) for ${symbolsStr}, date range: ${dateRangeStr}${hasMorePages ? ", more pages available" : ", complete"}`, {
-                type: "info",
-            });
-            // Prevent infinite loops
-            if (pageCount > 1000) {
-                log$l(`Stopping pagination after ${pageCount} pages to prevent infinite loop`, { type: "warn" });
-                break;
+                else if (message.T === "subscription") {
+                    log$l(`${streamType} subscription confirmed: trades=${message.trades?.length || 0}, quotes=${message.quotes?.length || 0}, bars=${message.bars?.length || 0}`, { type: "info" });
+                }
+                else if (message.T === "error") {
+                    log$l(`${streamType} stream error: ${message.msg} (code: ${message.code}, raw: ${JSON.stringify(message)})`, { type: "error" });
+                    // Alpaca code 406: "connection limit exceeded" — account-wide
+                    // concurrent-WS cap reached. The Alpaca server will close the
+                    // socket immediately after this frame, which would normally
+                    // trigger our standard sub-second exponential reconnect chain
+                    // (1 s, 2 s, 4 s, 8 s, 16 s, 30 s × 5) — exactly the wrong
+                    // behaviour against a rate-limit response. Stamp the recency
+                    // marker so {@link scheduleReconnect} switches to the
+                    // 5-minute jittered backoff instead.
+                    if (typeof message.code === "number" &&
+                        message.code === 406) {
+                        this.lastConnectionLimitAt[streamType] = Date.now();
+                    }
+                }
+                else if (message.S) {
+                    super.emit(`${streamType}-${message.T}`, message);
+                    super.emit(`${streamType}-data`, message);
+                }
+                else {
+                    log$l(`${streamType} received unknown message type: ${JSON.stringify(message)}`, { type: "debug" });
+                }
             }
-        }
-        // Final summary
-        const symbolCounts = Object.entries(allBars)
-            .map(([symbol, bars]) => `${symbol}: ${bars.length}`)
-            .join(", ");
-        log$l(`Historical bars fetch complete: ${totalBarsCount.toLocaleString()} total bars across ${pageCount} pages (${symbolCounts})`, {
-            type: "info",
-        });
-        return {
-            bars: allBars,
-            next_page_token: null, // Always null since we fetch all pages
-            currency: currency || DEFAULT_CURRENCY$1,
-        };
-    }
-    /**
-     * Get the most recent minute bar for requested symbols
-     * @param symbols Array of stock symbols to query
-     * @param currency Optional currency in ISO 4217 format
-     * @returns Latest bar data for each symbol
-     
-     */
-    async getLatestBars(symbols, currency) {
-        return this.makeRequest("/stocks/bars/latest", "GET", {
-            symbols,
-            feed: DEFAULT_FEED$1,
-            currency: currency || DEFAULT_CURRENCY$1,
-        });
-    }
-    /**
-     * Get the last trade for a single symbol
-     * @param symbol The stock symbol to query
-     * @returns Last trade details including price, size, exchange, and conditions
-     */
-    async getLastTrade(symbol) {
-        return this.makeRequest(`/v1/last/stocks/${symbol}`, "GET");
-    }
-    /**
-     * Get the most recent trades for requested symbols
-     * @param symbols Array of stock symbols to query
-     * @param feed Optional data source (sip/iex/delayed_sip)
-     * @param currency Optional currency in ISO 4217 format
-     * @returns Latest trade data for each symbol
-     
-     */
-    async getLatestTrades(symbols, feed, currency) {
-        return this.makeRequest("/stocks/trades/latest", "GET", {
-            symbols,
-            feed: feed || DEFAULT_FEED$1,
-            currency: currency || DEFAULT_CURRENCY$1,
         });
-    }
-    /**
-     * Get the most recent quotes for requested symbols
-     * @param symbols Array of stock symbols to query
-     * @param feed Optional data source (sip/iex/delayed_sip)
-     * @param currency Optional currency in ISO 4217 format
-     * @returns Latest quote data for each symbol
-     */
-    async getLatestQuotes(symbols, feed, currency) {
-        // Return empty response if symbols array is empty to avoid API error
-        if (!symbols || symbols.length === 0) {
-            log$l("No symbols provided to getLatestQuotes, returning empty response", {
+        ws.on("close", (code) => {
+            log$l(`${streamType} stream disconnected (code: ${code})`, {
                 type: "warn",
             });
-            return {
-                quotes: {},
-                currency: currency || DEFAULT_CURRENCY$1,
-            };
-        }
-        return this.makeRequest("/stocks/quotes/latest", "GET", {
-            symbols,
-            feed: feed || DEFAULT_FEED$1,
-            currency: currency || DEFAULT_CURRENCY$1,
+            if (streamType === "stock") {
+                this.stockWs = null;
+            }
+            else if (streamType === "option") {
+                this.optionWs = null;
+            }
+            else {
+                this.cryptoWs = null;
+            }
+            // Reconnect with exponential backoff (unless intentionally closed with code 1000)
+            if (code !== 1000) {
+                this.scheduleReconnect(streamType);
+            }
         });
-    }
-    /**
-     * Get the latest quote for a single symbol
-     * @param symbol The stock symbol to query
-     * @param feed Optional data source (sip/iex/delayed_sip)
-     * @param currency Optional currency in ISO 4217 format
-     * @returns Latest quote data with symbol and currency information
-     */
-    async getLatestQuote(symbol, feed, currency) {
-        return this.makeRequest(`/stocks/${symbol}/quotes/latest`, "GET", {
-            feed: feed || DEFAULT_FEED$1,
-            currency,
+        ws.on("error", (error) => {
+            log$l(`${streamType} stream error: ${error.message}`, { type: "error" });
         });
     }
-    /**
-     * Get the previous day's closing price for a symbol
-     * @param symbol The stock symbol to query
-     * @param referenceDate Optional reference date to get the previous close for
-     * @returns Previous day's closing price data
-     */
-    async getPreviousClose(symbol, referenceDate) {
-        const date = referenceDate || new Date();
-        const prevMarketDate = getLastFullTradingDate(date);
-        // Alpaca bars use inclusive-start, exclusive-end (t >= start AND t < end).
-        // When start === end the range is empty and zero bars are returned.
-        // Set end to the next calendar day to capture exactly one daily bar.
-        const endDate = new Date(prevMarketDate.date);
-        endDate.setDate(endDate.getDate() + 1);
-        const response = await this.getHistoricalBars({
-            symbols: [symbol],
-            timeframe: "1Day",
-            start: prevMarketDate.date.toISOString(),
-            end: endDate.toISOString(),
-            limit: 1,
+    scheduleReconnect(streamType) {
+        // 406-recovery fast path. When the most recent close was preceded
+        // by an Alpaca app-level 406 ("connection limit exceeded"), the
+        // standard sub-second exponential ramp is exactly wrong — it
+        // hammers the rate-limit endpoint and prolongs the slot pressure.
+        // Use a 5-minute jittered backoff instead and reset the normal
+        // attempt counter so we don't fall off the end of maxAttempts
+        // and permanently give up on a transient rollover blip.
+        const connectionLimitAt = this.lastConnectionLimitAt[streamType];
+        const isRecentConnectionLimit = typeof connectionLimitAt === "number" &&
+            Date.now() - connectionLimitAt <= this.CONNECTION_LIMIT_RECENCY_MS;
+        if (isRecentConnectionLimit) {
+            const jitter = Math.floor((Math.random() - 0.5) *
+                2 *
+                this.CONNECTION_LIMIT_BACKOFF_JITTER_MS);
+            const delayMs = this.CONNECTION_LIMIT_BACKOFF_MS + jitter;
+            // Reset normal attempt counter so the next 406 retry doesn't
+            // inherit a stale exponential cap.
+            this.reconnectAttempts[streamType] = 0;
+            // Consume the recency marker — subsequent reconnects fall back
+            // to the standard exponential path unless a new 406 arrives.
+            delete this.lastConnectionLimitAt[streamType];
+            log$l(`${streamType} stream: Alpaca 406 connection-limit recovery — backing off ${Math.round(delayMs / 1000)}s before retry to allow account-wide slot release`, { type: "warn" });
+            if (this.reconnectTimers[streamType]) {
+                clearTimeout(this.reconnectTimers[streamType]);
+            }
+            this.reconnectTimers[streamType] = setTimeout(() => {
+                log$l(`${streamType} stream: attempting reconnect after 406-recovery backoff`, { type: "info" });
+                this.connect(streamType);
+            }, delayMs);
+            return;
+        }
+        const attempts = this.reconnectAttempts[streamType] ?? 0;
+        const maxAttempts = 10;
+        if (attempts >= maxAttempts) {
+            log$l(`${streamType} stream: max reconnect attempts (${maxAttempts}) reached, giving up`, { type: "error" });
+            return;
+        }
+        // Exponential backoff: 1s, 2s, 4s, 8s, 16s, 30s (capped)
+        const delayMs = Math.min(1000 * Math.pow(2, attempts), 30000);
+        this.reconnectAttempts[streamType] = attempts + 1;
+        log$l(`${streamType} stream: scheduling reconnect attempt ${attempts + 1}/${maxAttempts} in ${delayMs}ms`, { type: "info" });
+        // Clear any existing reconnect timer for this stream
+        if (this.reconnectTimers[streamType]) {
+            clearTimeout(this.reconnectTimers[streamType]);
+        }
+        this.reconnectTimers[streamType] = setTimeout(() => {
+            log$l(`${streamType} stream: reconnecting (attempt ${attempts + 1}/${maxAttempts})`, { type: "info" });
+            this.connect(streamType);
+        }, delayMs);
+    }
+    sendSubscription(streamType) {
+        let ws;
+        let subscriptions;
+        if (streamType === "stock") {
+            ws = this.stockWs;
+            subscriptions = this.stockSubscriptions;
+        }
+        else if (streamType === "option") {
+            ws = this.optionWs;
+            subscriptions = this.optionSubscriptions;
+        }
+        else {
+            ws = this.cryptoWs;
+            subscriptions = this.cryptoSubscriptions;
+        }
+        log$l(`sendSubscription called for ${streamType} (wsReady=${ws?.readyState === WebSocket.OPEN}, trades=${subscriptions.trades?.length || 0}, quotes=${subscriptions.quotes?.length || 0}, bars=${subscriptions.bars?.length || 0})`, {
+            type: "debug",
         });
-        if (!response.bars[symbol] || response.bars[symbol].length === 0) {
-            log$l(`No previous close data available for ${symbol}`, {
-                type: "error",
-                symbol,
-            });
-            return null;
+        if (ws && ws.readyState === WebSocket.OPEN) {
+            const subMessagePayload = {};
+            if (subscriptions.trades.length > 0) {
+                subMessagePayload.trades = subscriptions.trades;
+            }
+            if (subscriptions.quotes.length > 0) {
+                subMessagePayload.quotes = subscriptions.quotes;
+            }
+            if (subscriptions.bars.length > 0) {
+                subMessagePayload.bars = subscriptions.bars;
+            }
+            if (Object.keys(subMessagePayload).length > 0) {
+                const subMessage = {
+                    action: "subscribe",
+                    ...subMessagePayload,
+                };
+                const messageJson = JSON.stringify(subMessage);
+                log$l(`Sending ${streamType} subscription: ${messageJson}`, {
+                    type: "info",
+                });
+                ws.send(messageJson);
+            }
+            else {
+                log$l(`No ${streamType} subscriptions to send (all arrays empty)`, {
+                    type: "debug",
+                });
+            }
+        }
+        else if (ws && ws.readyState === WebSocket.CONNECTING) {
+            // WebSocket is still establishing. Subscriptions are already persisted
+            // in `subscriptions` and will be dispatched automatically by the
+            // auth-success handler once the stream authenticates. This is the
+            // expected transient state during startup / reconnect — not a failure.
+            const queuedTotal = (subscriptions.trades?.length || 0) +
+                (subscriptions.quotes?.length || 0) +
+                (subscriptions.bars?.length || 0);
+            log$l(`${streamType} subscription queued (${queuedTotal} channel entries); will dispatch after WebSocket authenticates`, { type: "debug" });
+        }
+        else {
+            const stateLabel = ws === null
+                ? "null"
+                : ws.readyState === WebSocket.CLOSING
+                    ? "CLOSING"
+                    : ws.readyState === WebSocket.CLOSED
+                        ? "CLOSED"
+                        : `unknown(${ws.readyState})`;
+            log$l(`Cannot send ${streamType} subscription: WebSocket in ${stateLabel} state`, { type: "warn" });
         }
-        return response.bars[symbol][0];
     }
-    /**
-     * Get hourly price data for a symbol
-     * @param symbol The stock symbol to query
-     * @param start Start time in milliseconds
-     * @param end End time in milliseconds
-     * @returns Array of hourly price bars
-     */
-    async getHourlyPrices(symbol, start, end) {
-        const response = await this.getHistoricalBars({
-            symbols: [symbol],
-            timeframe: "1Hour",
-            start: new Date(start).toISOString(),
-            end: new Date(end).toISOString(),
-            limit: 96, // Last 96 hours (4 days)
-        });
-        return response.bars[symbol] || [];
+    connectStockStream() {
+        if (!this.stockWs) {
+            this.connect("stock");
+        }
     }
-    /**
-     * Get half-hourly price data for a symbol
-     * @param symbol The stock symbol to query
-     * @param start Start time in milliseconds
-     * @param end End time in milliseconds
-     * @returns Array of half-hourly price bars
-     */
-    async getHalfHourlyPrices(symbol, start, end) {
-        const response = await this.getHistoricalBars({
-            symbols: [symbol],
-            timeframe: "30Min",
-            start: new Date(start).toISOString(),
-            end: new Date(end).toISOString(),
-            limit: 16 * 2 * 4, // last 4 days, 16 hours per day, 2 bars per hour
-        });
-        return response.bars[symbol] || [];
+    connectOptionStream() {
+        if (!this.optionWs) {
+            this.connect("option");
+        }
     }
-    /**
-     * Get daily price data for a symbol
-     * @param symbol The stock symbol to query
-     * @param start Start time in milliseconds
-     * @param end End time in milliseconds
-     * @returns Array of daily price bars
-     */
-    async getDailyPrices(symbol, start, end) {
-        const response = await this.getHistoricalBars({
-            symbols: [symbol],
-            timeframe: "1Day",
-            start: new Date(start).toISOString(),
-            end: new Date(end).toISOString(),
-            limit: 100, // Last 100 days
-        });
-        return response.bars[symbol] || [];
+    connectCryptoStream() {
+        if (!this.cryptoWs) {
+            this.connect("crypto");
+        }
     }
-    /**
-     * Get intraday price data for a symbol
-     * @param symbol The stock symbol to query
-     * @param minutePeriod Minutes per bar (1, 5, 15, etc.)
-     * @param start Start time in milliseconds
-     * @param end End time in milliseconds
-     * @returns Array of intraday price bars
-     */
-    async getIntradayPrices(symbol, minutePeriod, start, end) {
-        const timeframe = `${minutePeriod}Min`;
-        const response = await this.getHistoricalBars({
-            symbols: [symbol],
-            timeframe,
-            start: new Date(start).toISOString(),
-            end: new Date(end).toISOString(),
-        });
-        return response.bars[symbol] || [];
+    disconnectStockStream() {
+        if (this.stockWs) {
+            this.stockWs.close();
+        }
     }
-    /**
-     * Analyzes an array of price bars and returns a summary string
-     * @param bars Array of price bars to analyze
-     * @returns A string summarizing the price data
-     */
-    static analyzeBars(bars) {
-        if (!bars || bars.length === 0) {
-            return "No price data available";
+    disconnectOptionStream() {
+        if (this.optionWs) {
+            this.optionWs.close();
         }
-        const firstBar = bars[0];
-        const lastBar = bars[bars.length - 1];
-        const priceChange = lastBar.c - firstBar.o;
-        const percentChange = (priceChange / firstBar.o) * 100;
-        const volumeChange = lastBar.v - firstBar.v;
-        const percentVolumeChange = (volumeChange / firstBar.v) * 100;
-        const high = Math.max(...bars.map((bar) => bar.h));
-        const low = Math.min(...bars.map((bar) => bar.l));
-        const totalVolume = bars.reduce((sum, bar) => sum + bar.v, 0);
-        const avgVolume = totalVolume / bars.length;
-        return (`Price: $${firstBar.o.toFixed(2)} -> $${lastBar.c.toFixed(2)} (${percentChange.toFixed(2)}%), ` +
-            `Volume: ${firstBar.v.toLocaleString()} -> ${lastBar.v.toLocaleString()} (${percentVolumeChange.toFixed(2)}%), ` +
-            `High: $${high.toFixed(2)}, Low: $${low.toFixed(2)}, ` +
-            `Avg Volume: ${avgVolume.toLocaleString()}`);
     }
-    /**
-     * Get all assets available for trade and data consumption from Alpaca
-     * @param params Optional query params: status (e.g. 'active'), asset_class (e.g. 'us_equity', 'crypto')
-     * @returns Array of AlpacaAsset objects
-     * @see https://docs.alpaca.markets/reference/get-v2-assets-1
-     */
-    async getAssets(params) {
-        // Endpoint: GET /v2/assets
-        return this.makeRequest("/assets", "GET", params, "api"); // use apiURL
+    disconnectCryptoStream() {
+        if (this.cryptoWs) {
+            this.cryptoWs.close();
+        }
     }
     /**
-     * Get a single asset by symbol or asset_id
-     * @param symbolOrAssetId Symbol or asset_id
-     * @returns AlpacaAsset object
-     * @see https://docs.alpaca.markets/reference/get-v2-assets-symbol_or_asset_id
+     * Check if a specific stream is connected
+     * @param streamType - The type of stream to check
+     * @returns True if the stream is connected
      */
-    async getAsset(symbolOrAssetId) {
-        // Endpoint: GET /v2/assets/{symbol_or_asset_id}
-        return this.makeRequest(`/assets/${encodeURIComponent(symbolOrAssetId)}`, "GET", undefined, "api");
+    isStreamConnected(streamType) {
+        if (streamType === "stock") {
+            return (this.stockWs !== null && this.stockWs.readyState === WebSocket.OPEN);
+        }
+        else if (streamType === "option") {
+            return (this.optionWs !== null && this.optionWs.readyState === WebSocket.OPEN);
+        }
+        else {
+            return (this.cryptoWs !== null && this.cryptoWs.readyState === WebSocket.OPEN);
+        }
     }
-    // ===== OPTIONS MARKET DATA METHODS =====
-    /**
-     * Get options chain for an underlying symbol
-     * Provides the latest trade, latest quote, and greeks for each contract symbol of the underlying symbol
-     * @param params Options chain request parameters
-     * @returns Options chain data with snapshots for each contract
-     * @see https://docs.alpaca.markets/reference/optionchain
-     */
-    async getOptionsChain(params) {
-        const { underlying_symbol, ...queryParams } = params;
-        return this.makeRequest(`/options/snapshots/${encodeURIComponent(underlying_symbol)}`, "GET", queryParams, "v1beta1");
+    subscribe(streamType, subscriptions) {
+        let currentSubscriptions;
+        if (streamType === "stock") {
+            currentSubscriptions = this.stockSubscriptions;
+        }
+        else if (streamType === "option") {
+            currentSubscriptions = this.optionSubscriptions;
+        }
+        else {
+            currentSubscriptions = this.cryptoSubscriptions;
+        }
+        Object.entries(subscriptions).forEach(([key, value]) => {
+            if (value) {
+                currentSubscriptions[key] = [
+                    ...new Set([...(currentSubscriptions[key] || []), ...value]),
+                ];
+            }
+        });
+        this.sendSubscription(streamType);
     }
-    /**
-     * Get the most recent trades for requested option contract symbols
-     * @param params Latest options trades request parameters
-     * @returns Latest trade data for each option contract symbol
-     
-     * @see https://docs.alpaca.markets/reference/optionlatesttrades
-     */
-    async getLatestOptionsTrades(params) {
-        // Remove limit and page_token as they're not supported by this endpoint
-        const { limit: _limit, page_token: _page_token, ...requestParams } = params;
-        return this.makeRequest("/options/trades/latest", "GET", requestParams, "v1beta1");
+    unsubscribe(streamType, subscriptions) {
+        let currentSubscriptions;
+        if (streamType === "stock") {
+            currentSubscriptions = this.stockSubscriptions;
+        }
+        else if (streamType === "option") {
+            currentSubscriptions = this.optionSubscriptions;
+        }
+        else {
+            currentSubscriptions = this.cryptoSubscriptions;
+        }
+        Object.entries(subscriptions).forEach(([key, value]) => {
+            if (value) {
+                currentSubscriptions[key] = (currentSubscriptions[key] || []).filter((s) => !value.includes(s));
+            }
+        });
+        const unsubMessage = {
+            action: "unsubscribe",
+            ...subscriptions,
+        };
+        let ws;
+        if (streamType === "stock") {
+            ws = this.stockWs;
+        }
+        else if (streamType === "option") {
+            ws = this.optionWs;
+        }
+        else {
+            ws = this.cryptoWs;
+        }
+        if (ws && ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify(unsubMessage));
+        }
     }
-    /**
-     * Get the most recent quotes for requested option contract symbols
-     * @param params Latest options quotes request parameters
-     * @returns Latest quote data for each option contract symbol
-     
-     * @see https://docs.alpaca.markets/reference/optionlatestquotes
-     */
-    async getLatestOptionsQuotes(params) {
-        // Remove limit and page_token as they're not supported by this endpoint
-        const { limit: _limit, page_token: _page_token, ...requestParams } = params;
-        return this.makeRequest("/options/quotes/latest", "GET", requestParams, "v1beta1");
+    async makeRequest(endpoint, method = "GET", params, baseUrlName = "data") {
+        const baseUrl = baseUrlName === "data"
+            ? this.dataURL
+            : baseUrlName === "api"
+                ? this.apiURL
+                : this.v1beta1url;
+        const url = new URL(`${baseUrl}${endpoint}`);
+        try {
+            if (params) {
+                Object.entries(params).forEach(([key, value]) => {
+                    if (Array.isArray(value)) {
+                        url.searchParams.append(key, value.join(","));
+                    }
+                    else if (value !== undefined && value !== null) {
+                        url.searchParams.append(key, value.toString());
+                    }
+                });
+            }
+            // Gate all Alpaca market-data calls through the shared 1000/min token
+            // bucket so concurrent callers (bar fetches, quotes, options, snapshots)
+            // can't overrun Alpaca's server-side rate limit. Prior to this, parallel
+            // historical-bar fan-out produced ~125 server-side 429s per minute.
+            await rateLimiters.alpaca.acquire();
+            // Retry ONLY transient connection faults, and only on GET (every
+            // market-data read here is idempotent). A non-2xx response is a real
+            // answer from Alpaca and is never retried — that path still throws on
+            // the first attempt exactly as before.
+            let response;
+            let lastNetworkError;
+            for (let attempt = 0; attempt < TRANSIENT_NETWORK_RETRY_ATTEMPTS; attempt += 1) {
+                try {
+                    response = await fetch(url.toString(), {
+                        method,
+                        headers: this.headers,
+                        signal: createTimeoutSignal(DEFAULT_TIMEOUTS.ALPACA_API),
+                    });
+                    break;
+                }
+                catch (networkErr) {
+                    lastNetworkError = networkErr;
+                    const retryable = method === "GET" &&
+                        isTransientNetworkError(networkErr) &&
+                        attempt < TRANSIENT_NETWORK_RETRY_ATTEMPTS - 1;
+                    if (!retryable) {
+                        throw networkErr;
+                    }
+                    const delayMs = transientRetryDelayMs(attempt);
+                    log$l(`Transient network fault on ${endpoint} (attempt ${attempt + 1}/${TRANSIENT_NETWORK_RETRY_ATTEMPTS}); retrying in ${delayMs}ms`, { type: "warn" });
+                    await new Promise((resolve) => setTimeout(resolve, delayMs));
+                    // Re-acquire the rate-limit token so a retry storm cannot overrun
+                    // Alpaca's server-side limit.
+                    await rateLimiters.alpaca.acquire();
+                }
+            }
+            if (!response) {
+                throw lastNetworkError instanceof Error
+                    ? lastNetworkError
+                    : new Error(`Market Data API request failed for ${endpoint}`);
+            }
+            if (!response.ok) {
+                const errorText = await response.text();
+                log$l(`Market Data API error (${response.status}): ${errorText}`, {
+                    type: "error",
+                });
+                throw new Error(`Market Data API error (${response.status}): ${errorText}`);
+            }
+            const data = await response.json();
+            return data;
+        }
+        catch (err) {
+            const error = err;
+            log$l(`Error in makeRequest: ${error.message}. Endpoint: ${endpoint}. Url: ${url.toString()}`, { type: "error" });
+            if (error instanceof TypeError) {
+                log$l(`Network error details: ${error.stack}`, { type: "error" });
+            }
+            throw error;
+        }
     }
     /**
-     * Get historical OHLCV bars for option contract symbols
+     * Get historical OHLCV bars for specified symbols, including pre-market and post-market data
      * Automatically handles pagination to fetch all available data
-     * @param params Historical options bars request parameters
-     * @returns Historical bar data for each option contract symbol with all pages combined
-     
-     * @see https://docs.alpaca.markets/reference/optionbars
+     * @param params Parameters for historical bars request
+     * @returns Historical bars data with all pages combined
      */
-    async getHistoricalOptionsBars(params) {
+    async getHistoricalBars(params) {
         const symbols = params.symbols;
         const symbolsStr = symbols.join(",");
         const allBars = {};
@@ -3612,26 +3737,33 @@ class AlpacaMarketDataAPI extends EventEmitter {
         let hasMorePages = true;
         let totalBarsCount = 0;
         let pageCount = 0;
+        let currency = "";
         // Initialize bar arrays for each symbol
         symbols.forEach((symbol) => {
             allBars[symbol] = [];
         });
-        log$l(`Starting historical options bars fetch for ${symbolsStr} (${params.timeframe}, ${params.start || "no start"} to ${params.end || "no end"})`, {
+        log$l(`Starting historical bars fetch for ${symbolsStr} (${params.timeframe}, ${params.start || "no start"} to ${params.end || "no end"})`, {
             type: "info",
         });
         while (hasMorePages) {
             pageCount++;
             const requestParams = {
                 ...params,
+                adjustment: DEFAULT_ADJUSTMENT,
+                feed: DEFAULT_FEED$1,
                 ...(pageToken && { page_token: pageToken }),
             };
-            const response = await this.makeRequest("/options/bars", "GET", requestParams, "v1beta1");
+            const response = await this.makeRequest("/stocks/bars", "GET", requestParams);
             if (!response.bars) {
-                log$l(`No options bars data found in response for ${symbolsStr}`, {
+                log$l(`No bars data found in response for ${symbolsStr}`, {
                     type: "warn",
                 });
                 break;
             }
+            // Track currency from first response
+            if (!currency) {
+                currency = response.currency;
+            }
             // Combine bars for each symbol
             let pageBarsCount = 0;
             let earliestTimestamp = null;
@@ -3659,12 +3791,12 @@ class AlpacaMarketDataAPI extends EventEmitter {
             const dateRangeStr = earliestTimestamp && latestTimestamp
                 ? `${earliestTimestamp.toLocaleDateString("en-US", { timeZone: "America/New_York" })} to ${latestTimestamp.toLocaleDateString("en-US", { timeZone: "America/New_York" })}`
                 : "unknown range";
-            log$l(`Page ${pageCount}: Fetched ${pageBarsCount.toLocaleString()} option bars (total: ${totalBarsCount.toLocaleString()}) for ${symbolsStr}, date range: ${dateRangeStr}${hasMorePages ? ", more pages available" : ", complete"}`, {
+            log$l(`Page ${pageCount}: Fetched ${pageBarsCount.toLocaleString()} bars (total: ${totalBarsCount.toLocaleString()}) for ${symbolsStr}, date range: ${dateRangeStr}${hasMorePages ? ", more pages available" : ", complete"}`, {
                 type: "info",
             });
             // Prevent infinite loops
             if (pageCount > 1000) {
-                log$l(`Stopping options bars pagination after ${pageCount} pages to prevent infinite loop`, { type: "warn" });
+                log$l(`Stopping pagination after ${pageCount} pages to prevent infinite loop`, { type: "warn" });
                 break;
             }
         }
@@ -3672,711 +3804,636 @@ class AlpacaMarketDataAPI extends EventEmitter {
         const symbolCounts = Object.entries(allBars)
             .map(([symbol, bars]) => `${symbol}: ${bars.length}`)
             .join(", ");
-        log$l(`Historical options bars fetch complete: ${totalBarsCount.toLocaleString()} total bars across ${pageCount} pages (${symbolCounts})`, {
+        log$l(`Historical bars fetch complete: ${totalBarsCount.toLocaleString()} total bars across ${pageCount} pages (${symbolCounts})`, {
             type: "info",
         });
         return {
             bars: allBars,
-            next_page_token: undefined, // Always undefined since we fetch all pages
+            next_page_token: null, // Always null since we fetch all pages
+            currency: currency || DEFAULT_CURRENCY$1,
         };
     }
     /**
-     * Get historical trades for option contract symbols
-     * Automatically handles pagination to fetch all available data
-     * @param params Historical options trades request parameters
-     * @returns Historical trade data for each option contract symbol with all pages combined
+     * Get the most recent minute bar for requested symbols
+     * @param symbols Array of stock symbols to query
+     * @param currency Optional currency in ISO 4217 format
+     * @returns Latest bar data for each symbol
      
-     * @see https://docs.alpaca.markets/reference/optiontrades
      */
-    async getHistoricalOptionsTrades(params) {
-        const symbols = params.symbols;
-        const symbolsStr = symbols.join(",");
-        const allTrades = {};
-        let pageToken = null;
-        let hasMorePages = true;
-        let totalTradesCount = 0;
-        let pageCount = 0;
-        // Initialize trades arrays for each symbol
-        symbols.forEach((symbol) => {
-            allTrades[symbol] = [];
+    async getLatestBars(symbols, currency) {
+        return this.makeRequest("/stocks/bars/latest", "GET", {
+            symbols,
+            feed: DEFAULT_FEED$1,
+            currency: currency || DEFAULT_CURRENCY$1,
         });
-        log$l(`Starting historical options trades fetch for ${symbolsStr} (${params.start || "no start"} to ${params.end || "no end"})`, {
-            type: "info",
+    }
+    /**
+     * Get the last trade for a single symbol
+     * @param symbol The stock symbol to query
+     * @returns Last trade details including price, size, exchange, and conditions
+     */
+    async getLastTrade(symbol) {
+        return this.makeRequest(`/v1/last/stocks/${symbol}`, "GET");
+    }
+    /**
+     * Get the most recent trades for requested symbols
+     * @param symbols Array of stock symbols to query
+     * @param feed Optional data source (sip/iex/delayed_sip)
+     * @param currency Optional currency in ISO 4217 format
+     * @returns Latest trade data for each symbol
+     
+     */
+    async getLatestTrades(symbols, feed, currency) {
+        return this.makeRequest("/stocks/trades/latest", "GET", {
+            symbols,
+            feed: feed || DEFAULT_FEED$1,
+            currency: currency || DEFAULT_CURRENCY$1,
         });
-        while (hasMorePages) {
-            pageCount++;
-            const requestParams = {
-                ...params,
-                ...(pageToken && { page_token: pageToken }),
-            };
-            const response = await this.makeRequest("/options/trades", "GET", requestParams, "v1beta1");
-            if (!response.trades) {
-                log$l(`No options trades data found in response for ${symbolsStr}`, {
-                    type: "warn",
-                });
-                break;
-            }
-            // Combine trades for each symbol
-            let pageTradesCount = 0;
-            let earliestTimestamp = null;
-            let latestTimestamp = null;
-            Object.entries(response.trades).forEach(([symbol, trades]) => {
-                if (trades && trades.length > 0) {
-                    allTrades[symbol] = [...allTrades[symbol], ...trades];
-                    pageTradesCount += trades.length;
-                    // Track date range for this page
-                    trades.forEach((trade) => {
-                        const tradeDate = new Date(trade.t);
-                        if (!earliestTimestamp || tradeDate < earliestTimestamp) {
-                            earliestTimestamp = tradeDate;
-                        }
-                        if (!latestTimestamp || tradeDate > latestTimestamp) {
-                            latestTimestamp = tradeDate;
-                        }
-                    });
-                }
+    }
+    /**
+     * Get the most recent quotes for requested symbols
+     * @param symbols Array of stock symbols to query
+     * @param feed Optional data source (sip/iex/delayed_sip)
+     * @param currency Optional currency in ISO 4217 format
+     * @returns Latest quote data for each symbol
+     */
+    async getLatestQuotes(symbols, feed, currency) {
+        // Return empty response if symbols array is empty to avoid API error
+        if (!symbols || symbols.length === 0) {
+            log$l("No symbols provided to getLatestQuotes, returning empty response", {
+                type: "warn",
             });
-            totalTradesCount += pageTradesCount;
-            pageToken = response.next_page_token || null;
-            hasMorePages = !!pageToken;
-            // Enhanced logging with date range and progress info
-            const dateRangeStr = earliestTimestamp && latestTimestamp
-                ? `${earliestTimestamp.toLocaleDateString("en-US", { timeZone: "America/New_York" })} to ${latestTimestamp.toLocaleDateString("en-US", { timeZone: "America/New_York" })}`
-                : "unknown range";
-            log$l(`Page ${pageCount}: Fetched ${pageTradesCount.toLocaleString()} option trades (total: ${totalTradesCount.toLocaleString()}) for ${symbolsStr}, date range: ${dateRangeStr}${hasMorePages ? ", more pages available" : ", complete"}`, {
-                type: "info",
+            return {
+                quotes: {},
+                currency: currency || DEFAULT_CURRENCY$1,
+            };
+        }
+        return this.makeRequest("/stocks/quotes/latest", "GET", {
+            symbols,
+            feed: feed || DEFAULT_FEED$1,
+            currency: currency || DEFAULT_CURRENCY$1,
+        });
+    }
+    /**
+     * Get the latest quote for a single symbol
+     * @param symbol The stock symbol to query
+     * @param feed Optional data source (sip/iex/delayed_sip)
+     * @param currency Optional currency in ISO 4217 format
+     * @returns Latest quote data with symbol and currency information
+     */
+    async getLatestQuote(symbol, feed, currency) {
+        return this.makeRequest(`/stocks/${symbol}/quotes/latest`, "GET", {
+            feed: feed || DEFAULT_FEED$1,
+            currency,
+        });
+    }
+    /**
+     * Get the previous day's closing price for a symbol
+     * @param symbol The stock symbol to query
+     * @param referenceDate Optional reference date to get the previous close for
+     * @returns Previous day's closing price data
+     */
+    async getPreviousClose(symbol, referenceDate) {
+        const date = referenceDate || new Date();
+        const prevMarketDate = getLastFullTradingDate(date);
+        // Alpaca bars use inclusive-start, exclusive-end (t >= start AND t < end).
+        // When start === end the range is empty and zero bars are returned.
+        // Set end to the next calendar day to capture exactly one daily bar.
+        const endDate = new Date(prevMarketDate.date);
+        endDate.setDate(endDate.getDate() + 1);
+        const response = await this.getHistoricalBars({
+            symbols: [symbol],
+            timeframe: "1Day",
+            start: prevMarketDate.date.toISOString(),
+            end: endDate.toISOString(),
+            limit: 1,
+        });
+        if (!response.bars[symbol] || response.bars[symbol].length === 0) {
+            log$l(`No previous close data available for ${symbol}`, {
+                type: "error",
+                symbol,
             });
-            // Prevent infinite loops
-            if (pageCount > 1000) {
-                log$l(`Stopping options trades pagination after ${pageCount} pages to prevent infinite loop`, { type: "warn" });
-                break;
-            }
+            return null;
         }
-        // Final summary
-        const symbolCounts = Object.entries(allTrades)
-            .map(([symbol, trades]) => `${symbol}: ${trades.length}`)
-            .join(", ");
-        log$l(`Historical options trades fetch complete: ${totalTradesCount.toLocaleString()} total trades across ${pageCount} pages (${symbolCounts})`, {
-            type: "info",
+        return response.bars[symbol][0];
+    }
+    /**
+     * Get hourly price data for a symbol
+     * @param symbol The stock symbol to query
+     * @param start Start time in milliseconds
+     * @param end End time in milliseconds
+     * @returns Array of hourly price bars
+     */
+    async getHourlyPrices(symbol, start, end) {
+        const response = await this.getHistoricalBars({
+            symbols: [symbol],
+            timeframe: "1Hour",
+            start: new Date(start).toISOString(),
+            end: new Date(end).toISOString(),
+            limit: 96, // Last 96 hours (4 days)
         });
-        return {
-            trades: allTrades,
-            next_page_token: undefined, // Always undefined since we fetch all pages
-        };
+        return response.bars[symbol] || [];
     }
     /**
-     * Get snapshots for option contract symbols
-     * Provides latest trade, latest quote, and greeks for each contract symbol
-     * @param params Options snapshots request parameters
-     * @returns Snapshot data for each option contract symbol
-     
-     * @see https://docs.alpaca.markets/reference/optionsnapshots
+     * Get half-hourly price data for a symbol
+     * @param symbol The stock symbol to query
+     * @param start Start time in milliseconds
+     * @param end End time in milliseconds
+     * @returns Array of half-hourly price bars
      */
-    async getOptionsSnapshot(params) {
-        // Remove limit and page_token as they may not be supported by this endpoint
-        const { limit: _limit, page_token: _page_token, ...requestParams } = params;
-        return this.makeRequest("/options/snapshots", "GET", requestParams, "v1beta1");
+    async getHalfHourlyPrices(symbol, start, end) {
+        const response = await this.getHistoricalBars({
+            symbols: [symbol],
+            timeframe: "30Min",
+            start: new Date(start).toISOString(),
+            end: new Date(end).toISOString(),
+            limit: 16 * 2 * 4, // last 4 days, 16 hours per day, 2 bars per hour
+        });
+        return response.bars[symbol] || [];
     }
     /**
-     * Get condition codes for options trades or quotes
-     * Returns the mapping between condition codes and their descriptions
-     * @param tickType The type of tick data ('trade' or 'quote')
-     * @returns Mapping of condition codes to descriptions
-     
-     * @see https://docs.alpaca.markets/reference/optionmetaconditions
+     * Get daily price data for a symbol
+     * @param symbol The stock symbol to query
+     * @param start Start time in milliseconds
+     * @param end End time in milliseconds
+     * @returns Array of daily price bars
      */
-    async getOptionsConditionCodes(tickType) {
-        return this.makeRequest(`/options/meta/conditions/${tickType}`, "GET", undefined, "v1beta1");
+    async getDailyPrices(symbol, start, end) {
+        const response = await this.getHistoricalBars({
+            symbols: [symbol],
+            timeframe: "1Day",
+            start: new Date(start).toISOString(),
+            end: new Date(end).toISOString(),
+            limit: 100, // Last 100 days
+        });
+        return response.bars[symbol] || [];
     }
     /**
-     * Get exchange codes for options
-     * Returns the mapping between option exchange codes and exchange names
-     * @returns Mapping of exchange codes to exchange names
-     
-     * @see https://docs.alpaca.markets/reference/optionmetaexchanges
+     * Get intraday price data for a symbol
+     * @param symbol The stock symbol to query
+     * @param minutePeriod Minutes per bar (1, 5, 15, etc.)
+     * @param start Start time in milliseconds
+     * @param end End time in milliseconds
+     * @returns Array of intraday price bars
      */
-    async getOptionsExchangeCodes() {
-        return this.makeRequest("/options/meta/exchanges", "GET", undefined, "v1beta1");
+    async getIntradayPrices(symbol, minutePeriod, start, end) {
+        const timeframe = `${minutePeriod}Min`;
+        const response = await this.getHistoricalBars({
+            symbols: [symbol],
+            timeframe,
+            start: new Date(start).toISOString(),
+            end: new Date(end).toISOString(),
+        });
+        return response.bars[symbol] || [];
     }
     /**
-     * Analyzes an array of option bars and returns a summary string
-     * @param bars Array of option bars to analyze
-     * @returns A string summarizing the option price data
+     * Analyzes an array of price bars and returns a summary string
+     * @param bars Array of price bars to analyze
+     * @returns A string summarizing the price data
      */
-    static analyzeOptionBars(bars) {
+    static analyzeBars(bars) {
         if (!bars || bars.length === 0) {
-            return "No option price data available";
+            return "No price data available";
         }
         const firstBar = bars[0];
         const lastBar = bars[bars.length - 1];
         const priceChange = lastBar.c - firstBar.o;
         const percentChange = (priceChange / firstBar.o) * 100;
         const volumeChange = lastBar.v - firstBar.v;
-        const percentVolumeChange = firstBar.v > 0 ? (volumeChange / firstBar.v) * 100 : 0;
+        const percentVolumeChange = (volumeChange / firstBar.v) * 100;
         const high = Math.max(...bars.map((bar) => bar.h));
         const low = Math.min(...bars.map((bar) => bar.l));
         const totalVolume = bars.reduce((sum, bar) => sum + bar.v, 0);
         const avgVolume = totalVolume / bars.length;
-        return (`Option Price: $${firstBar.o.toFixed(2)} -> $${lastBar.c.toFixed(2)} (${percentChange.toFixed(2)}%), ` +
+        return (`Price: $${firstBar.o.toFixed(2)} -> $${lastBar.c.toFixed(2)} (${percentChange.toFixed(2)}%), ` +
             `Volume: ${firstBar.v.toLocaleString()} -> ${lastBar.v.toLocaleString()} (${percentVolumeChange.toFixed(2)}%), ` +
             `High: $${high.toFixed(2)}, Low: $${low.toFixed(2)}, ` +
             `Avg Volume: ${avgVolume.toLocaleString()}`);
     }
     /**
-     * Formats option greeks for display
-     * @param greeks Option greeks object
-     * @returns Formatted string with greek values
+     * Get all assets available for trade and data consumption from Alpaca
+     * @param params Optional query params: status (e.g. 'active'), asset_class (e.g. 'us_equity', 'crypto')
+     * @returns Array of AlpacaAsset objects
+     * @see https://docs.alpaca.markets/reference/get-v2-assets-1
      */
-    static formatOptionGreeks(greeks) {
-        if (!greeks) {
-            return "No greeks data available";
-        }
-        const parts = [];
-        if (greeks.delta !== undefined)
-            parts.push(`Delta: ${greeks.delta.toFixed(4)}`);
-        if (greeks.gamma !== undefined)
-            parts.push(`Gamma: ${greeks.gamma.toFixed(4)}`);
-        if (greeks.theta !== undefined)
-            parts.push(`Theta: ${greeks.theta.toFixed(4)}`);
-        if (greeks.vega !== undefined)
-            parts.push(`Vega: ${greeks.vega.toFixed(4)}`);
-        if (greeks.rho !== undefined)
-            parts.push(`Rho: ${greeks.rho.toFixed(4)}`);
-        return parts.length > 0 ? parts.join(", ") : "No greeks data available";
+    async getAssets(params) {
+        // Endpoint: GET /v2/assets
+        return this.makeRequest("/assets", "GET", params, "api"); // use apiURL
     }
     /**
-     * Interprets condition codes using the provided condition codes mapping
-     * @param conditionCodes Array of condition codes from trade or quote
-     * @param conditionCodesMap Mapping of condition codes to descriptions
-     * @returns Formatted string with condition descriptions
+     * Get a single asset by symbol or asset_id
+     * @param symbolOrAssetId Symbol or asset_id
+     * @returns AlpacaAsset object
+     * @see https://docs.alpaca.markets/reference/get-v2-assets-symbol_or_asset_id
      */
-    static interpretConditionCodes(conditionCodes, conditionCodesMap) {
-        if (!conditionCodes || conditionCodes.length === 0) {
-            return "No conditions";
-        }
-        const descriptions = conditionCodes
-            .map((code) => conditionCodesMap[code] || `Unknown (${code})`)
-            .filter((desc) => desc !== undefined);
-        return descriptions.length > 0
-            ? descriptions.join(", ")
-            : "No condition descriptions available";
+    async getAsset(symbolOrAssetId) {
+        // Endpoint: GET /v2/assets/{symbol_or_asset_id}
+        return this.makeRequest(`/assets/${encodeURIComponent(symbolOrAssetId)}`, "GET", undefined, "api");
     }
+    // ===== OPTIONS MARKET DATA METHODS =====
     /**
-     * Gets the exchange name from exchange code using the provided exchange codes mapping
-     * @param exchangeCode Exchange code from trade or quote
-     * @param exchangeCodesMap Mapping of exchange codes to names
-     * @returns Exchange name or formatted unknown exchange
+     * Get options chain for an underlying symbol
+     * Provides the latest trade, latest quote, and greeks for each contract symbol of the underlying symbol
+     * @param params Options chain request parameters
+     * @returns Options chain data with snapshots for each contract
+     * @see https://docs.alpaca.markets/reference/optionchain
      */
-    static getExchangeName(exchangeCode, exchangeCodesMap) {
-        return (exchangeCodesMap[exchangeCode] || `Unknown Exchange (${exchangeCode})`);
+    async getOptionsChain(params) {
+        const { underlying_symbol, ...queryParams } = params;
+        return this.makeRequest(`/options/snapshots/${encodeURIComponent(underlying_symbol)}`, "GET", queryParams, "v1beta1");
     }
     /**
-     * Fetches news articles from Alpaca API for a symbol, paginating through all results.
-     * @param symbol The symbol to fetch news for (e.g., 'AAPL')
-     * @param params Optional parameters: start, end, limit, sort, include_content
-     * @returns Array of SimpleNews articles
+     * Get the most recent trades for requested option contract symbols
+     * @param params Latest options trades request parameters
+     * @returns Latest trade data for each option contract symbol
+     
+     * @see https://docs.alpaca.markets/reference/optionlatesttrades
      */
-    async fetchNews(symbol, params) {
-        const defaultParams = {
-            start: new Date(Date.now() - 24 * 60 * 60 * 1000),
-            end: new Date(),
-            limit: 10,
-            sort: "desc",
-            include_content: true,
-        };
-        const mergedParams = { ...defaultParams, ...params };
-        let newsArticles = [];
+    async getLatestOptionsTrades(params) {
+        // Remove limit and page_token as they're not supported by this endpoint
+        const { limit: _limit, page_token: _page_token, ...requestParams } = params;
+        return this.makeRequest("/options/trades/latest", "GET", requestParams, "v1beta1");
+    }
+    /**
+     * Get the most recent quotes for requested option contract symbols
+     * @param params Latest options quotes request parameters
+     * @returns Latest quote data for each option contract symbol
+     
+     * @see https://docs.alpaca.markets/reference/optionlatestquotes
+     */
+    async getLatestOptionsQuotes(params) {
+        // Remove limit and page_token as they're not supported by this endpoint
+        const { limit: _limit, page_token: _page_token, ...requestParams } = params;
+        return this.makeRequest("/options/quotes/latest", "GET", requestParams, "v1beta1");
+    }
+    /**
+     * Get historical OHLCV bars for option contract symbols
+     * Automatically handles pagination to fetch all available data
+     * @param params Historical options bars request parameters
+     * @returns Historical bar data for each option contract symbol with all pages combined
+     
+     * @see https://docs.alpaca.markets/reference/optionbars
+     */
+    async getHistoricalOptionsBars(params) {
+        const symbols = params.symbols;
+        const symbolsStr = symbols.join(",");
+        const allBars = {};
         let pageToken = null;
         let hasMorePages = true;
-        let fetchedCount = 0;
-        const maxLimit = mergedParams.limit;
-        // Utility to clean content
-        function cleanContent(content) {
-            if (!content)
-                return undefined;
-            // Remove excessive whitespace, newlines, and trim
-            return content.replace(/\s+/g, " ").trim();
-        }
-        while (hasMorePages) {
-            const queryParams = new URLSearchParams({
-                ...(mergedParams.start && {
-                    start: new Date(mergedParams.start).toISOString(),
-                }),
-                ...(mergedParams.end && {
-                    end: new Date(mergedParams.end).toISOString(),
-                }),
-                ...(symbol && { symbols: symbol }),
-                ...(mergedParams.limit && {
-                    limit: Math.min(50, maxLimit - fetchedCount).toString(),
-                }),
-                ...(mergedParams.sort && { sort: mergedParams.sort }),
-                ...(mergedParams.include_content !== undefined
-                    ? { include_content: mergedParams.include_content.toString() }
-                    : {}),
+        let totalBarsCount = 0;
+        let pageCount = 0;
+        // Initialize bar arrays for each symbol
+        symbols.forEach((symbol) => {
+            allBars[symbol] = [];
+        });
+        log$l(`Starting historical options bars fetch for ${symbolsStr} (${params.timeframe}, ${params.start || "no start"} to ${params.end || "no end"})`, {
+            type: "info",
+        });
+        while (hasMorePages) {
+            pageCount++;
+            const requestParams = {
+                ...params,
                 ...(pageToken && { page_token: pageToken }),
-            });
-            const url = `${this.v1beta1url}/news?${queryParams}`;
-            log$l(`Fetching news from: ${url}`, { type: "debug", symbol });
-            const response = await fetch(url, {
-                method: "GET",
-                headers: this.headers,
-            });
-            if (!response.ok) {
-                const errorText = await response.text();
-                log$l(`Alpaca news API error (${response.status}): ${errorText}`, {
-                    type: "error",
-                    symbol,
-                });
-                throw new Error(`Alpaca news API error (${response.status}): ${errorText}`);
-            }
-            const data = await response.json();
-            if (!data.news || !Array.isArray(data.news)) {
-                log$l(`No news data found in Alpaca response for ${symbol}`, {
+            };
+            const response = await this.makeRequest("/options/bars", "GET", requestParams, "v1beta1");
+            if (!response.bars) {
+                log$l(`No options bars data found in response for ${symbolsStr}`, {
                     type: "warn",
-                    symbol,
                 });
                 break;
             }
-            const transformedNews = data.news.map((article) => ({
-                symbols: article.symbols,
-                title: article.headline,
-                summary: cleanContent(article.summary) ?? "",
-                content: article.content ? cleanContent(article.content) : undefined,
-                url: article.url,
-                source: article.source,
-                author: article.author,
-                date: article.updated_at || article.created_at,
-                updatedDate: article.updated_at || article.created_at,
-                sentiment: 0,
-            }));
-            newsArticles = newsArticles.concat(transformedNews);
-            fetchedCount = newsArticles.length;
-            pageToken = data.next_page_token || null;
-            hasMorePages = !!pageToken && (!maxLimit || fetchedCount < maxLimit);
-            log$l(`Fetched ${transformedNews.length} news articles (total: ${fetchedCount}) for ${symbol}. More pages: ${hasMorePages}`, { type: "debug", symbol });
-            if (maxLimit && fetchedCount >= maxLimit) {
-                newsArticles = newsArticles.slice(0, maxLimit);
-                break;
-            }
-        }
-        return newsArticles;
-    }
-}
-// 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;
-                    }
+            // Combine bars for each symbol
+            let pageBarsCount = 0;
+            let earliestTimestamp = null;
+            let latestTimestamp = null;
+            Object.entries(response.bars).forEach(([symbol, bars]) => {
+                if (bars && bars.length > 0) {
+                    allBars[symbol] = [...allBars[symbol], ...bars];
+                    pageBarsCount += bars.length;
+                    // Track date range for this page
+                    bars.forEach((bar) => {
+                        const barDate = new Date(bar.t);
+                        if (!earliestTimestamp || barDate < earliestTimestamp) {
+                            earliestTimestamp = barDate;
+                        }
+                        if (!latestTimestamp || barDate > latestTimestamp) {
+                            latestTimestamp = barDate;
+                        }
+                    });
                 }
+            });
+            totalBarsCount += pageBarsCount;
+            pageToken = response.next_page_token || null;
+            hasMorePages = !!pageToken;
+            // Enhanced logging with date range and progress info
+            const dateRangeStr = earliestTimestamp && latestTimestamp
+                ? `${earliestTimestamp.toLocaleDateString("en-US", { timeZone: "America/New_York" })} to ${latestTimestamp.toLocaleDateString("en-US", { timeZone: "America/New_York" })}`
+                : "unknown range";
+            log$l(`Page ${pageCount}: Fetched ${pageBarsCount.toLocaleString()} option bars (total: ${totalBarsCount.toLocaleString()}) for ${symbolsStr}, date range: ${dateRangeStr}${hasMorePages ? ", more pages available" : ", complete"}`, {
+                type: "info",
+            });
+            // Prevent infinite loops
+            if (pageCount > 1000) {
+                log$l(`Stopping options bars pagination after ${pageCount} pages to prevent infinite loop`, { type: "warn" });
+                break;
             }
-            current = err.cause;
-        }
-        else {
-            break;
         }
+        // Final summary
+        const symbolCounts = Object.entries(allBars)
+            .map(([symbol, bars]) => `${symbol}: ${bars.length}`)
+            .join(", ");
+        log$l(`Historical options bars fetch complete: ${totalBarsCount.toLocaleString()} total bars across ${pageCount} pages (${symbolCounts})`, {
+            type: "info",
+        });
+        return {
+            bars: allBars,
+            next_page_token: undefined, // Always undefined since we fetch all pages
+        };
     }
-    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,
+    /**
+     * Get historical trades for option contract symbols
+     * Automatically handles pagination to fetch all available data
+     * @param params Historical options trades request parameters
+     * @returns Historical trade data for each option contract symbol with all pages combined
+     
+     * @see https://docs.alpaca.markets/reference/optiontrades
+     */
+    async getHistoricalOptionsTrades(params) {
+        const symbols = params.symbols;
+        const symbolsStr = symbols.join(",");
+        const allTrades = {};
+        let pageToken = null;
+        let hasMorePages = true;
+        let totalTradesCount = 0;
+        let pageCount = 0;
+        // Initialize trades arrays for each symbol
+        symbols.forEach((symbol) => {
+            allTrades[symbol] = [];
+        });
+        log$l(`Starting historical options trades fetch for ${symbolsStr} (${params.start || "no start"} to ${params.end || "no end"})`, {
+            type: "info",
+        });
+        while (hasMorePages) {
+            pageCount++;
+            const requestParams = {
+                ...params,
+                ...(pageToken && { page_token: pageToken }),
             };
+            const response = await this.makeRequest("/options/trades", "GET", requestParams, "v1beta1");
+            if (!response.trades) {
+                log$l(`No options trades data found in response for ${symbolsStr}`, {
+                    type: "warn",
+                });
+                break;
+            }
+            // Combine trades for each symbol
+            let pageTradesCount = 0;
+            let earliestTimestamp = null;
+            let latestTimestamp = null;
+            Object.entries(response.trades).forEach(([symbol, trades]) => {
+                if (trades && trades.length > 0) {
+                    allTrades[symbol] = [...allTrades[symbol], ...trades];
+                    pageTradesCount += trades.length;
+                    // Track date range for this page
+                    trades.forEach((trade) => {
+                        const tradeDate = new Date(trade.t);
+                        if (!earliestTimestamp || tradeDate < earliestTimestamp) {
+                            earliestTimestamp = tradeDate;
+                        }
+                        if (!latestTimestamp || tradeDate > latestTimestamp) {
+                            latestTimestamp = tradeDate;
+                        }
+                    });
+                }
+            });
+            totalTradesCount += pageTradesCount;
+            pageToken = response.next_page_token || null;
+            hasMorePages = !!pageToken;
+            // Enhanced logging with date range and progress info
+            const dateRangeStr = earliestTimestamp && latestTimestamp
+                ? `${earliestTimestamp.toLocaleDateString("en-US", { timeZone: "America/New_York" })} to ${latestTimestamp.toLocaleDateString("en-US", { timeZone: "America/New_York" })}`
+                : "unknown range";
+            log$l(`Page ${pageCount}: Fetched ${pageTradesCount.toLocaleString()} option trades (total: ${totalTradesCount.toLocaleString()}) for ${symbolsStr}, date range: ${dateRangeStr}${hasMorePages ? ", more pages available" : ", complete"}`, {
+                type: "info",
+            });
+            // Prevent infinite loops
+            if (pageCount > 1000) {
+                log$l(`Stopping options trades pagination after ${pageCount} pages to prevent infinite loop`, { type: "warn" });
+                break;
+            }
         }
-    }
-    // Handle network errors (TypeError from fetch API)
-    if (error instanceof TypeError && error.message.includes("fetch")) {
+        // Final summary
+        const symbolCounts = Object.entries(allTrades)
+            .map(([symbol, trades]) => `${symbol}: ${trades.length}`)
+            .join(", ");
+        log$l(`Historical options trades fetch complete: ${totalTradesCount.toLocaleString()} total trades across ${pageCount} pages (${symbolCounts})`, {
+            type: "info",
+        });
         return {
-            type: "NETWORK_ERROR",
-            reason: "Network connectivity issue",
-            status: null,
-            isRetryable: config.retryOnNetworkError,
+            trades: allTrades,
+            next_page_token: undefined, // Always undefined since we fetch all pages
         };
     }
-    // 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,
-        };
+    /**
+     * Get snapshots for option contract symbols
+     * Provides latest trade, latest quote, and greeks for each contract symbol
+     * @param params Options snapshots request parameters
+     * @returns Snapshot data for each option contract symbol
+     
+     * @see https://docs.alpaca.markets/reference/optionsnapshots
+     */
+    async getOptionsSnapshot(params) {
+        // Remove limit and page_token as they may not be supported by this endpoint
+        const { limit: _limit, page_token: _page_token, ...requestParams } = params;
+        return this.makeRequest("/options/snapshots", "GET", requestParams, "v1beta1");
     }
-    // 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,
-            };
-        }
+    /**
+     * Get condition codes for options trades or quotes
+     * Returns the mapping between condition codes and their descriptions
+     * @param tickType The type of tick data ('trade' or 'quote')
+     * @returns Mapping of condition codes to descriptions
+     
+     * @see https://docs.alpaca.markets/reference/optionmetaconditions
+     */
+    async getOptionsConditionCodes(tickType) {
+        return this.makeRequest(`/options/meta/conditions/${tickType}`, "GET", undefined, "v1beta1");
     }
-    // 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;
+    /**
+     * Get exchange codes for options
+     * Returns the mapping between option exchange codes and exchange names
+     * @returns Mapping of exchange codes to exchange names
+     
+     * @see https://docs.alpaca.markets/reference/optionmetaexchanges
+     */
+    async getOptionsExchangeCodes() {
+        return this.makeRequest("/options/meta/exchanges", "GET", undefined, "v1beta1");
+    }
+    /**
+     * Analyzes an array of option bars and returns a summary string
+     * @param bars Array of option bars to analyze
+     * @returns A string summarizing the option price data
+     */
+    static analyzeOptionBars(bars) {
+        if (!bars || bars.length === 0) {
+            return "No option price data available";
+        }
+        const firstBar = bars[0];
+        const lastBar = bars[bars.length - 1];
+        const priceChange = lastBar.c - firstBar.o;
+        const percentChange = (priceChange / firstBar.o) * 100;
+        const volumeChange = lastBar.v - firstBar.v;
+        const percentVolumeChange = firstBar.v > 0 ? (volumeChange / firstBar.v) * 100 : 0;
+        const high = Math.max(...bars.map((bar) => bar.h));
+        const low = Math.min(...bars.map((bar) => bar.l));
+        const totalVolume = bars.reduce((sum, bar) => sum + bar.v, 0);
+        const avgVolume = totalVolume / bars.length;
+        return (`Option Price: $${firstBar.o.toFixed(2)} -> $${lastBar.c.toFixed(2)} (${percentChange.toFixed(2)}%), ` +
+            `Volume: ${firstBar.v.toLocaleString()} -> ${lastBar.v.toLocaleString()} (${percentVolumeChange.toFixed(2)}%), ` +
+            `High: $${high.toFixed(2)}, Low: $${low.toFixed(2)}, ` +
+            `Avg Volume: ${avgVolume.toLocaleString()}`);
+    }
+    /**
+     * Formats option greeks for display
+     * @param greeks Option greeks object
+     * @returns Formatted string with greek values
+     */
+    static formatOptionGreeks(greeks) {
+        if (!greeks) {
+            return "No greeks data available";
         }
-        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(),
+        const parts = [];
+        if (greeks.delta !== undefined)
+            parts.push(`Delta: ${greeks.delta.toFixed(4)}`);
+        if (greeks.gamma !== undefined)
+            parts.push(`Gamma: ${greeks.gamma.toFixed(4)}`);
+        if (greeks.theta !== undefined)
+            parts.push(`Theta: ${greeks.theta.toFixed(4)}`);
+        if (greeks.vega !== undefined)
+            parts.push(`Vega: ${greeks.vega.toFixed(4)}`);
+        if (greeks.rho !== undefined)
+            parts.push(`Rho: ${greeks.rho.toFixed(4)}`);
+        return parts.length > 0 ? parts.join(", ") : "No greeks data available";
+    }
+    /**
+     * Interprets condition codes using the provided condition codes mapping
+     * @param conditionCodes Array of condition codes from trade or quote
+     * @param conditionCodesMap Mapping of condition codes to descriptions
+     * @returns Formatted string with condition descriptions
+     */
+    static interpretConditionCodes(conditionCodes, conditionCodesMap) {
+        if (!conditionCodes || conditionCodes.length === 0) {
+            return "No conditions";
+        }
+        const descriptions = conditionCodes
+            .map((code) => conditionCodesMap[code] || `Unknown (${code})`)
+            .filter((desc) => desc !== undefined);
+        return descriptions.length > 0
+            ? descriptions.join(", ")
+            : "No condition descriptions available";
+    }
+    /**
+     * Gets the exchange name from exchange code using the provided exchange codes mapping
+     * @param exchangeCode Exchange code from trade or quote
+     * @param exchangeCodesMap Mapping of exchange codes to names
+     * @returns Exchange name or formatted unknown exchange
+     */
+    static getExchangeName(exchangeCode, exchangeCodesMap) {
+        return (exchangeCodesMap[exchangeCode] || `Unknown Exchange (${exchangeCode})`);
+    }
+    /**
+     * Fetches news articles from Alpaca API for a symbol, paginating through all results.
+     * @param symbol The symbol to fetch news for (e.g., 'AAPL')
+     * @param params Optional parameters: start, end, limit, sort, include_content
+     * @returns Array of SimpleNews articles
+     */
+    async fetchNews(symbol, params) {
+        const defaultParams = {
+            start: new Date(Date.now() - 24 * 60 * 60 * 1000),
+            end: new Date(),
+            limit: 10,
+            sort: "desc",
+            include_content: true,
+        };
+        const mergedParams = { ...defaultParams, ...params };
+        let newsArticles = [];
+        let pageToken = null;
+        let hasMorePages = true;
+        let fetchedCount = 0;
+        const maxLimit = mergedParams.limit;
+        // Utility to clean content
+        function cleanContent(content) {
+            if (!content)
+                return undefined;
+            // Remove excessive whitespace, newlines, and trim
+            return content.replace(/\s+/g, " ").trim();
+        }
+        while (hasMorePages) {
+            const queryParams = new URLSearchParams({
+                ...(mergedParams.start && {
+                    start: new Date(mergedParams.start).toISOString(),
+                }),
+                ...(mergedParams.end && {
+                    end: new Date(mergedParams.end).toISOString(),
+                }),
+                ...(symbol && { symbols: symbol }),
+                ...(mergedParams.limit && {
+                    limit: Math.min(50, maxLimit - fetchedCount).toString(),
+                }),
+                ...(mergedParams.sort && { sort: mergedParams.sort }),
+                ...(mergedParams.include_content !== undefined
+                    ? { include_content: mergedParams.include_content.toString() }
+                    : {}),
+                ...(pageToken && { page_token: pageToken }),
+            });
+            const url = `${this.v1beta1url}/news?${queryParams}`;
+            log$l(`Fetching news from: ${url}`, { type: "debug", symbol });
+            const response = await fetch(url, {
+                method: "GET",
+                headers: this.headers,
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                log$l(`Alpaca news API error (${response.status}): ${errorText}`, {
+                    type: "error",
+                    symbol,
                 });
-                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);
+                throw new Error(`Alpaca news API error (${response.status}): ${errorText}`);
             }
-            else {
-                // Standard exponential backoff with jitter
-                delayMs = calculateBackoff(attempt, fullConfig.baseDelayMs, fullConfig.maxDelayMs);
+            const data = await response.json();
+            if (!data.news || !Array.isArray(data.news)) {
+                log$l(`No news data found in Alpaca response for ${symbol}`, {
+                    type: "warn",
+                    symbol,
+                });
+                break;
             }
-            // 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);
+            const transformedNews = data.news.map((article) => ({
+                symbols: article.symbols,
+                title: article.headline,
+                summary: cleanContent(article.summary) ?? "",
+                content: article.content ? cleanContent(article.content) : undefined,
+                url: article.url,
+                source: article.source,
+                author: article.author,
+                date: article.updated_at || article.created_at,
+                updatedDate: article.updated_at || article.created_at,
+                sentiment: 0,
+            }));
+            newsArticles = newsArticles.concat(transformedNews);
+            fetchedCount = newsArticles.length;
+            pageToken = data.next_page_token || null;
+            hasMorePages = !!pageToken && (!maxLimit || fetchedCount < maxLimit);
+            log$l(`Fetched ${transformedNews.length} news articles (total: ${fetchedCount}) for ${symbol}. More pages: ${hasMorePages}`, { type: "debug", symbol });
+            if (maxLimit && fetchedCount >= maxLimit) {
+                newsArticles = newsArticles.slice(0, maxLimit);
+                break;
             }
-            // Wait before retrying
-            await new Promise((resolve) => setTimeout(resolve, delayMs));
         }
+        return newsArticles;
     }
-    // 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,
-    },
-};
+// Export the singleton instance
+const marketDataAPI = AlpacaMarketDataAPI.getInstance();
 
 const limitPriceSlippagePercent100 = 0.1; // 0.1%
 /**