@fullstackcraftllc/floe 0.0.1 → 0.0.3

package/dist/client/brokers/TradierClient.js

@@ -0,0 +1,869 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TradierClient = void 0;
+const occ_1 = require("../../utils/occ");
+/**
+ * Regex pattern to identify OCC option symbols
+ * Matches both compact format (e.g., AAPL230120C00150000) and
+ * padded format (e.g., 'AAPL  230120C00150000')
+ * Pattern: 1-6 char root + YYMMDD + C/P + 8-digit strike
+ */
+const OCC_OPTION_PATTERN = /^.{1,6}\d{6}[CP]\d{8}$/;
+/**
+ * TradierClient handles real-time streaming connections to the Tradier API.
+ *
+ * @remarks
+ * This client manages WebSocket connections to Tradier's streaming API,
+ * normalizes incoming quote and trade data, and emits events for upstream
+ * consumption by the FloeClient.
+ *
+ * @example
+ * ```typescript
+ * const client = new TradierClient('your-api-key');
+ *
+ * client.on('tickerUpdate', (ticker) => {
+ *   console.log(`${ticker.symbol}: ${ticker.spot}`);
+ * });
+ *
+ * await client.connect();
+ * client.subscribe(['QQQ', 'AAPL  240119C00500000']);
+ * ```
+ */
+class TradierClient {
+    /**
+     * Creates a new TradierClient instance.
+     *
+     * @param authKey - Tradier API access token
+     */
+    constructor(authKey) {
+        /** Current streaming session */
+        this.streamSession = null;
+        /** WebSocket connection */
+        this.ws = null;
+        /** Connection state */
+        this.connected = false;
+        /** Currently subscribed symbols (tickers and options) */
+        this.subscribedSymbols = new Set();
+        /** Cached ticker data (for merging quote and trade events) */
+        this.tickerCache = new Map();
+        /** Cached option data (for merging quote and trade events) */
+        this.optionCache = new Map();
+        /**
+         * Base open interest from REST API - used as t=0 reference for live OI calculation
+         * Key: OCC symbol, Value: open interest at start of day / time of fetch
+         */
+        this.baseOpenInterest = new Map();
+        /**
+         * Cumulative estimated OI change from intraday trades
+         * Key: OCC symbol, Value: net estimated change (positive = more contracts opened)
+         */
+        this.cumulativeOIChange = new Map();
+        /**
+         * History of intraday trades with aggressor classification
+         * Key: OCC symbol, Value: array of trades
+         */
+        this.intradayTrades = new Map();
+        /** Event listeners */
+        this.eventListeners = new Map();
+        /** Reconnection attempt counter */
+        this.reconnectAttempts = 0;
+        /** Maximum reconnection attempts */
+        this.maxReconnectAttempts = 5;
+        /** Reconnection delay in ms (doubles with each attempt) */
+        this.baseReconnectDelay = 1000;
+        /** Tradier API base URL */
+        this.apiBaseUrl = 'https://api.tradier.com/v1';
+        /** Tradier WebSocket URL */
+        this.wsUrl = 'wss://ws.tradier.com/v1/markets/events';
+        this.authKey = authKey;
+        // Initialize event listener maps
+        this.eventListeners.set('tickerUpdate', new Set());
+        this.eventListeners.set('optionUpdate', new Set());
+        this.eventListeners.set('optionTrade', new Set());
+        this.eventListeners.set('connected', new Set());
+        this.eventListeners.set('disconnected', new Set());
+        this.eventListeners.set('error', new Set());
+    }
+    // ==================== Public API ====================
+    /**
+     * Establishes a streaming connection to Tradier.
+     *
+     * @returns Promise that resolves when connected
+     * @throws {Error} If session creation or WebSocket connection fails
+     */
+    async connect() {
+        // Create streaming session
+        const session = await this.createStreamSession();
+        if (!session) {
+            throw new Error('Failed to create Tradier streaming session');
+        }
+        this.streamSession = session;
+        // Connect WebSocket
+        await this.connectWebSocket();
+    }
+    /**
+     * Disconnects from the Tradier streaming API.
+     */
+    disconnect() {
+        if (this.ws) {
+            this.ws.close(1000, 'Client disconnect');
+            this.ws = null;
+        }
+        this.connected = false;
+        this.streamSession = null;
+        this.subscribedSymbols.clear();
+    }
+    /**
+     * Subscribes to real-time updates for the specified symbols.
+     *
+     * @param symbols - Array of ticker symbols and/or OCC option symbols
+     */
+    subscribe(symbols) {
+        if (!this.connected || !this.ws || !this.streamSession) {
+            // Queue symbols for subscription when connected
+            symbols.forEach(s => this.subscribedSymbols.add(s));
+            return;
+        }
+        // Add to tracked symbols
+        symbols.forEach(s => this.subscribedSymbols.add(s));
+        // Send subscription message
+        const payload = {
+            sessionid: this.streamSession.sessionid,
+            symbols: symbols,
+        };
+        this.ws.send(JSON.stringify(payload));
+    }
+    /**
+     * Unsubscribes from real-time updates for the specified symbols.
+     *
+     * @param symbols - Array of symbols to unsubscribe from
+     *
+     * @remarks
+     * Note: Tradier's streaming API doesn't support unsubscription for individual
+     * symbols. This method removes them from local tracking. To fully unsubscribe,
+     * you would need to disconnect and reconnect with the new symbol list.
+     */
+    unsubscribe(symbols) {
+        symbols.forEach(s => this.subscribedSymbols.delete(s));
+        // Note: Tradier doesn't support selective unsubscribe
+        // Would need to reconnect with new symbol list for full effect
+    }
+    /**
+     * Returns whether the client is currently connected.
+     */
+    isConnected() {
+        return this.connected;
+    }
+    /**
+     * Fetches options chain data from Tradier REST API.
+     *
+     * @param symbol - Underlying symbol (e.g., 'QQQ')
+     * @param expiration - Expiration date in YYYY-MM-DD format
+     * @param greeks - Whether to include Greeks data (default: true)
+     * @returns Array of option chain items, or empty array on failure
+     */
+    async fetchOptionsChain(symbol, expiration, greeks = true) {
+        try {
+            const params = new URLSearchParams({
+                symbol,
+                expiration,
+                greeks: String(greeks),
+            });
+            const url = `${this.apiBaseUrl}/markets/options/chains?${params.toString()}`;
+            const response = await fetch(url, {
+                method: 'GET',
+                headers: {
+                    'Authorization': `Bearer ${this.authKey}`,
+                    'Accept': 'application/json',
+                },
+            });
+            // log raw response for debugging
+            const rawResponse = await response.clone().text();
+            console.log('Raw options chain response:', rawResponse);
+            if (!response.ok) {
+                this.emit('error', new Error(`Failed to fetch options chain: ${response.statusText}`));
+                return [];
+            }
+            const data = await response.json();
+            if (!data.options || !data.options.option) {
+                return [];
+            }
+            // Handle case where API returns single object instead of array
+            const options = Array.isArray(data.options.option)
+                ? data.options.option
+                : [data.options.option];
+            return options;
+        }
+        catch (error) {
+            this.emit('error', error instanceof Error ? error : new Error(String(error)));
+            return [];
+        }
+    }
+    /**
+     * Fetches open interest and other static data for subscribed options via REST API.
+     * Call this after subscribing to options to populate open interest.
+     *
+     * @param occSymbols - Array of OCC option symbols to fetch data for
+     * @returns Promise that resolves when all data is fetched
+     *
+     * @remarks
+     * Open interest is only available via the REST API, not streaming.
+     * This method groups options by underlying and expiration to minimize API calls.
+     */
+    async fetchOpenInterest(occSymbols) {
+        // Group symbols by underlying and expiration to minimize API calls
+        const groups = new Map();
+        for (const occSymbol of occSymbols) {
+            try {
+                const parsed = (0, occ_1.parseOCCSymbol)(occSymbol);
+                const key = `${parsed.symbol}:${parsed.expiration.toISOString().split('T')[0]}`;
+                if (!groups.has(key)) {
+                    groups.set(key, new Set());
+                }
+                groups.get(key).add(occSymbol);
+            }
+            catch {
+                // Skip invalid OCC symbols
+                continue;
+            }
+        }
+        // Fetch chains for each underlying/expiration combination
+        const fetchPromises = Array.from(groups.entries()).map(async ([key, symbols]) => {
+            const [underlying, expiration] = key.split(':');
+            const chain = await this.fetchOptionsChain(underlying, expiration);
+            // Update cache with open interest data
+            for (const item of chain) {
+                // Tradier returns symbols in the same format we use (compact OCC)
+                if (symbols.has(item.symbol)) {
+                    // Store base open interest for live OI calculation (t=0 reference)
+                    this.baseOpenInterest.set(item.symbol, item.open_interest);
+                    // Initialize cumulative OI change if not already set
+                    if (!this.cumulativeOIChange.has(item.symbol)) {
+                        this.cumulativeOIChange.set(item.symbol, 0);
+                    }
+                    const existing = this.optionCache.get(item.symbol);
+                    if (existing) {
+                        // Update existing cache entry with REST data
+                        existing.openInterest = item.open_interest;
+                        existing.liveOpenInterest = this.calculateLiveOpenInterest(item.symbol);
+                        existing.volume = item.volume;
+                        existing.impliedVolatility = item.greeks?.mid_iv ?? existing.impliedVolatility;
+                        // Also update bid/ask if not yet populated
+                        if (existing.bid === 0 && item.bid > 0) {
+                            existing.bid = item.bid;
+                            existing.bidSize = item.bidsize;
+                        }
+                        if (existing.ask === 0 && item.ask > 0) {
+                            existing.ask = item.ask;
+                            existing.askSize = item.asksize;
+                        }
+                        if (existing.last === 0 && item.last !== null) {
+                            existing.last = item.last;
+                        }
+                        if (existing.mark === 0) {
+                            existing.mark = (item.bid + item.ask) / 2;
+                        }
+                        this.optionCache.set(item.symbol, existing);
+                        this.emit('optionUpdate', existing);
+                    }
+                    else {
+                        // Create new cache entry from REST data
+                        const parsedSymbol = (0, occ_1.parseOCCSymbol)(item.symbol);
+                        const option = {
+                            occSymbol: item.symbol,
+                            underlying: item.underlying,
+                            strike: item.strike,
+                            expiration: item.expiration_date,
+                            expirationTimestamp: parsedSymbol.expiration.getTime(),
+                            optionType: item.option_type,
+                            bid: item.bid,
+                            bidSize: item.bidsize,
+                            ask: item.ask,
+                            askSize: item.asksize,
+                            mark: (item.bid + item.ask) / 2,
+                            last: item.last ?? 0,
+                            volume: item.volume,
+                            openInterest: item.open_interest,
+                            liveOpenInterest: this.calculateLiveOpenInterest(item.symbol),
+                            impliedVolatility: item.greeks?.mid_iv ?? 0,
+                            timestamp: Date.now(),
+                        };
+                        this.optionCache.set(item.symbol, option);
+                        this.emit('optionUpdate', option);
+                    }
+                }
+            }
+        });
+        await Promise.all(fetchPromises);
+    }
+    /**
+     * Returns the cached option data for a symbol.
+     *
+     * @param occSymbol - OCC option symbol
+     * @returns Cached option data or undefined
+     */
+    getOption(occSymbol) {
+        return this.optionCache.get(occSymbol);
+    }
+    /**
+     * Returns all cached options.
+     *
+     * @returns Map of OCC symbols to option data
+     */
+    getAllOptions() {
+        return new Map(this.optionCache);
+    }
+    /**
+     * Registers an event listener.
+     *
+     * @param event - Event type to listen for
+     * @param listener - Callback function
+     */
+    on(event, listener) {
+        const listeners = this.eventListeners.get(event);
+        if (listeners) {
+            listeners.add(listener);
+        }
+        return this;
+    }
+    /**
+     * Removes an event listener.
+     *
+     * @param event - Event type
+     * @param listener - Callback function to remove
+     */
+    off(event, listener) {
+        const listeners = this.eventListeners.get(event);
+        if (listeners) {
+            listeners.delete(listener);
+        }
+        return this;
+    }
+    // ==================== Private Methods ====================
+    /**
+     * Creates a streaming session with Tradier API.
+     */
+    async createStreamSession() {
+        try {
+            const response = await fetch(`${this.apiBaseUrl}/markets/events/session`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${this.authKey}`,
+                    'Accept': 'application/json',
+                },
+            });
+            if (!response.ok) {
+                this.emit('error', new Error(`Failed to create stream session: ${response.statusText}`));
+                return null;
+            }
+            const data = await response.json();
+            return data.stream;
+        }
+        catch (error) {
+            this.emit('error', error instanceof Error ? error : new Error(String(error)));
+            return null;
+        }
+    }
+    /**
+     * Connects to the Tradier WebSocket.
+     */
+    connectWebSocket() {
+        return new Promise((resolve, reject) => {
+            this.ws = new WebSocket(this.wsUrl);
+            this.ws.onopen = () => {
+                this.connected = true;
+                this.reconnectAttempts = 0;
+                this.emit('connected', undefined);
+                // Subscribe to any queued symbols
+                if (this.subscribedSymbols.size > 0 && this.streamSession) {
+                    const payload = {
+                        sessionid: this.streamSession.sessionid,
+                        symbols: Array.from(this.subscribedSymbols),
+                    };
+                    this.ws.send(JSON.stringify(payload));
+                }
+                resolve();
+            };
+            this.ws.onmessage = (event) => {
+                this.handleMessage(event.data);
+            };
+            this.ws.onclose = (event) => {
+                this.connected = false;
+                this.emit('disconnected', { reason: event.reason });
+                // Attempt reconnection if not a clean close
+                if (event.code !== 1000) {
+                    this.attemptReconnect();
+                }
+            };
+            this.ws.onerror = (error) => {
+                this.emit('error', new Error('WebSocket error'));
+                reject(error);
+            };
+        });
+    }
+    /**
+     * Attempts to reconnect with exponential backoff.
+     */
+    async attemptReconnect() {
+        if (this.reconnectAttempts >= this.maxReconnectAttempts) {
+            this.emit('error', new Error('Max reconnection attempts reached'));
+            return;
+        }
+        this.reconnectAttempts++;
+        const delay = this.baseReconnectDelay * Math.pow(2, this.reconnectAttempts - 1);
+        await this.sleep(delay);
+        try {
+            await this.connect();
+        }
+        catch {
+            // Reconnect attempt failed, will try again via onclose
+        }
+    }
+    /**
+     * Handles incoming WebSocket messages.
+     */
+    handleMessage(data) {
+        try {
+            const event = JSON.parse(data);
+            if (event.type === 'quote') {
+                this.handleQuoteEvent(event);
+            }
+            else if (event.type === 'trade') {
+                this.handleTradeEvent(event);
+            }
+            else if (event.type === 'timesale') {
+                this.handleTimesaleEvent(event);
+            }
+            // 'summary' events don't have data we need for NormalizedTicker/Option
+        }
+        catch (error) {
+            // Ignore parse errors for heartbeat/status messages
+        }
+    }
+    /**
+     * Handles quote events (bid/ask updates).
+     */
+    handleQuoteEvent(event) {
+        const { symbol } = event;
+        const timestamp = parseInt(event.biddate, 10) || Date.now();
+        const isOption = this.isOptionSymbol(symbol);
+        if (isOption) {
+            this.updateOptionFromQuote(symbol, event, timestamp);
+        }
+        else {
+            this.updateTickerFromQuote(symbol, event, timestamp);
+        }
+    }
+    /**
+     * Handles trade events (last price/volume updates).
+     */
+    handleTradeEvent(event) {
+        const { symbol } = event;
+        const timestamp = parseInt(event.date, 10) || Date.now();
+        const isOption = this.isOptionSymbol(symbol);
+        if (isOption) {
+            this.updateOptionFromTrade(symbol, event, timestamp);
+        }
+        else {
+            this.updateTickerFromTrade(symbol, event, timestamp);
+        }
+    }
+    /**
+     * Handles timesale events (trade with bid/ask at time of sale).
+     * This is particularly useful for options where quote events may be sparse.
+     */
+    handleTimesaleEvent(event) {
+        const { symbol } = event;
+        const timestamp = parseInt(event.date, 10) || Date.now();
+        const isOption = this.isOptionSymbol(symbol);
+        if (isOption) {
+            this.updateOptionFromTimesale(symbol, event, timestamp);
+        }
+        else {
+            this.updateTickerFromTimesale(symbol, event, timestamp);
+        }
+    }
+    /**
+     * Updates ticker data from a quote event.
+     */
+    updateTickerFromQuote(symbol, event, timestamp) {
+        const existing = this.tickerCache.get(symbol);
+        const ticker = {
+            symbol,
+            spot: (event.bid + event.ask) / 2,
+            bid: event.bid,
+            bidSize: event.bidsz,
+            ask: event.ask,
+            askSize: event.asksz,
+            last: existing?.last ?? 0,
+            volume: existing?.volume ?? 0,
+            timestamp,
+        };
+        this.tickerCache.set(symbol, ticker);
+        this.emit('tickerUpdate', ticker);
+    }
+    /**
+     * Updates ticker data from a trade event.
+     */
+    updateTickerFromTrade(symbol, event, timestamp) {
+        const existing = this.tickerCache.get(symbol);
+        const last = parseFloat(event.last);
+        const volume = parseInt(event.cvol, 10);
+        const ticker = {
+            symbol,
+            spot: existing?.spot ?? last,
+            bid: existing?.bid ?? 0,
+            bidSize: existing?.bidSize ?? 0,
+            ask: existing?.ask ?? 0,
+            askSize: existing?.askSize ?? 0,
+            last,
+            volume,
+            timestamp,
+        };
+        this.tickerCache.set(symbol, ticker);
+        this.emit('tickerUpdate', ticker);
+    }
+    /**
+     * Updates option data from a quote event.
+     */
+    updateOptionFromQuote(occSymbol, event, timestamp) {
+        const existing = this.optionCache.get(occSymbol);
+        // Parse OCC symbol to extract option details
+        let parsed;
+        try {
+            parsed = (0, occ_1.parseOCCSymbol)(occSymbol);
+        }
+        catch {
+            // Invalid OCC symbol, skip
+            return;
+        }
+        const option = {
+            occSymbol,
+            underlying: parsed.symbol,
+            strike: parsed.strike,
+            expiration: parsed.expiration.toISOString().split('T')[0],
+            expirationTimestamp: parsed.expiration.getTime(),
+            optionType: parsed.optionType,
+            bid: event.bid,
+            bidSize: event.bidsz,
+            ask: event.ask,
+            askSize: event.asksz,
+            mark: (event.bid + event.ask) / 2,
+            last: existing?.last ?? 0,
+            volume: existing?.volume ?? 0,
+            openInterest: existing?.openInterest ?? 0,
+            impliedVolatility: existing?.impliedVolatility ?? 0,
+            timestamp,
+        };
+        this.optionCache.set(occSymbol, option);
+        this.emit('optionUpdate', option);
+    }
+    /**
+     * Updates option data from a trade event.
+     */
+    updateOptionFromTrade(occSymbol, event, timestamp) {
+        const existing = this.optionCache.get(occSymbol);
+        // Parse OCC symbol to extract option details
+        let parsed;
+        try {
+            parsed = (0, occ_1.parseOCCSymbol)(occSymbol);
+        }
+        catch {
+            // Invalid OCC symbol, skip
+            return;
+        }
+        const last = parseFloat(event.last);
+        const volume = parseInt(event.cvol, 10);
+        const option = {
+            occSymbol,
+            underlying: parsed.symbol,
+            strike: parsed.strike,
+            expiration: parsed.expiration.toISOString().split('T')[0],
+            expirationTimestamp: parsed.expiration.getTime(),
+            optionType: parsed.optionType,
+            bid: existing?.bid ?? 0,
+            bidSize: existing?.bidSize ?? 0,
+            ask: existing?.ask ?? 0,
+            askSize: existing?.askSize ?? 0,
+            mark: existing?.mark ?? last,
+            last,
+            volume,
+            openInterest: existing?.openInterest ?? 0,
+            impliedVolatility: existing?.impliedVolatility ?? 0,
+            timestamp,
+        };
+        this.optionCache.set(occSymbol, option);
+        this.emit('optionUpdate', option);
+    }
+    /**
+     * Updates ticker data from a timesale event.
+     * Timesale events include bid/ask at the time of the trade.
+     */
+    updateTickerFromTimesale(symbol, event, timestamp) {
+        const existing = this.tickerCache.get(symbol);
+        const bid = parseFloat(event.bid);
+        const ask = parseFloat(event.ask);
+        const last = parseFloat(event.last);
+        const size = parseInt(event.size, 10);
+        const ticker = {
+            symbol,
+            spot: (bid + ask) / 2,
+            bid,
+            bidSize: existing?.bidSize ?? 0, // timesale doesn't include bid/ask size
+            ask,
+            askSize: existing?.askSize ?? 0,
+            last,
+            volume: (existing?.volume ?? 0) + size, // Accumulate volume
+            timestamp,
+        };
+        this.tickerCache.set(symbol, ticker);
+        this.emit('tickerUpdate', ticker);
+    }
+    /**
+     * Updates option data from a timesale event.
+     * Timesale events include bid/ask at the time of the trade, enabling aggressor side detection.
+     *
+     * This is the primary method for calculating live open interest:
+     * - Aggressor side is determined by comparing trade price to NBBO
+     * - Buy aggressor (lifting ask) typically indicates new long positions → OI increases
+     * - Sell aggressor (hitting bid) typically indicates closing longs or new shorts → OI decreases
+     */
+    updateOptionFromTimesale(occSymbol, event, timestamp) {
+        const existing = this.optionCache.get(occSymbol);
+        // Parse OCC symbol to extract option details
+        let parsed;
+        try {
+            parsed = (0, occ_1.parseOCCSymbol)(occSymbol);
+        }
+        catch {
+            // Invalid OCC symbol, skip
+            return;
+        }
+        const bid = parseFloat(event.bid);
+        const ask = parseFloat(event.ask);
+        const last = parseFloat(event.last);
+        const size = parseInt(event.size, 10);
+        // Determine aggressor side by comparing trade price to NBBO
+        const aggressorSide = this.determineAggressorSide(last, bid, ask);
+        // Calculate estimated OI change based on aggressor side
+        // Buy aggressor (lifting the offer) → typically opening new long positions → +OI
+        // Sell aggressor (hitting the bid) → typically closing longs or opening shorts → -OI
+        const estimatedOIChange = this.calculateOIChangeFromTrade(aggressorSide, size, parsed.optionType);
+        // Update cumulative OI change
+        const currentChange = this.cumulativeOIChange.get(occSymbol) ?? 0;
+        this.cumulativeOIChange.set(occSymbol, currentChange + estimatedOIChange);
+        // Record the trade for analysis
+        const trade = {
+            occSymbol,
+            price: last,
+            size,
+            bid,
+            ask,
+            aggressorSide,
+            timestamp,
+            estimatedOIChange,
+        };
+        if (!this.intradayTrades.has(occSymbol)) {
+            this.intradayTrades.set(occSymbol, []);
+        }
+        this.intradayTrades.get(occSymbol).push(trade);
+        // Emit trade event with aggressor info
+        this.emit('optionTrade', trade);
+        const option = {
+            occSymbol,
+            underlying: parsed.symbol,
+            strike: parsed.strike,
+            expiration: parsed.expiration.toISOString().split('T')[0],
+            expirationTimestamp: parsed.expiration.getTime(),
+            optionType: parsed.optionType,
+            bid,
+            bidSize: existing?.bidSize ?? 0, // timesale doesn't include bid/ask size
+            ask,
+            askSize: existing?.askSize ?? 0,
+            mark: (bid + ask) / 2,
+            last,
+            volume: (existing?.volume ?? 0) + size, // Accumulate volume
+            openInterest: existing?.openInterest ?? 0,
+            liveOpenInterest: this.calculateLiveOpenInterest(occSymbol),
+            impliedVolatility: existing?.impliedVolatility ?? 0,
+            timestamp,
+        };
+        this.optionCache.set(occSymbol, option);
+        this.emit('optionUpdate', option);
+    }
+    /**
+     * Determines the aggressor side of a trade by comparing trade price to NBBO.
+     *
+     * @param tradePrice - The executed trade price
+     * @param bid - The bid price at time of trade
+     * @param ask - The ask price at time of trade
+     * @returns The aggressor side: 'buy' if lifting offer, 'sell' if hitting bid, 'unknown' if mid
+     *
+     * @remarks
+     * The aggressor is the party that initiated the trade by crossing the spread:
+     * - Buy aggressor: Buyer lifts the offer (trades at or above ask) → bullish intent
+     * - Sell aggressor: Seller hits the bid (trades at or below bid) → bearish intent
+     * - Unknown: Trade occurred mid-market (could be internalized, crossed, or negotiated)
+     */
+    determineAggressorSide(tradePrice, bid, ask) {
+        // Use a small tolerance for floating point comparison (0.1% of spread)
+        const spread = ask - bid;
+        const tolerance = spread > 0 ? spread * 0.001 : 0.001;
+        if (tradePrice >= ask - tolerance) {
+            // Trade at or above ask → buyer lifted the offer
+            return 'buy';
+        }
+        else if (tradePrice <= bid + tolerance) {
+            // Trade at or below bid → seller hit the bid
+            return 'sell';
+        }
+        else {
+            // Trade mid-market - could be either side or internalized
+            return 'unknown';
+        }
+    }
+    /**
+     * Calculates the estimated open interest change from a single trade.
+     *
+     * @param aggressorSide - The aggressor side of the trade
+     * @param size - Number of contracts traded
+     * @param optionType - Whether this is a call or put
+     * @returns Estimated OI change (positive = OI increase, negative = OI decrease)
+     *
+     * @remarks
+     * This uses a simplified heuristic based on typical market behavior:
+     *
+     * For CALLS:
+     * - Buy aggressor (lifting offer) → typically bullish, opening new longs → +OI
+     * - Sell aggressor (hitting bid) → typically closing longs or bearish new shorts → -OI
+     *
+     * For PUTS:
+     * - Buy aggressor (lifting offer) → typically bearish/hedging, opening new longs → +OI
+     * - Sell aggressor (hitting bid) → typically closing longs → -OI
+     *
+     * Note: This is an estimate. Without knowing if trades are opening or closing,
+     * we use aggressor side as a proxy. SpotGamma and similar providers use
+     * more sophisticated models that may incorporate position sizing, strike
+     * selection patterns, and other heuristics.
+     */
+    calculateOIChangeFromTrade(aggressorSide, size, optionType) {
+        if (aggressorSide === 'unknown') {
+            // Mid-market trades are ambiguous - assume neutral impact on OI
+            return 0;
+        }
+        // Simple heuristic: buy aggressor = new positions opening, sell aggressor = positions closing
+        // This applies to both calls and puts since we're measuring contract count, not direction
+        if (aggressorSide === 'buy') {
+            return size; // New positions opening
+        }
+        else {
+            return -size; // Positions closing
+        }
+    }
+    /**
+     * Calculates the live (intraday) open interest estimate for an option.
+     *
+     * @param occSymbol - OCC option symbol
+     * @returns Live OI estimate = base OI + cumulative estimated changes
+     *
+     * @remarks
+     * Live Open Interest = Base OI (from REST at t=0) + Cumulative OI Changes (from trades)
+     *
+     * This provides a real-time estimate of open interest that updates throughout
+     * the trading day as trades occur. The accuracy depends on:
+     * 1. The accuracy of aggressor side detection
+     * 2. The assumption that aggressors are typically opening new positions
+     *
+     * The official OI is only updated overnight by the OCC clearing house,
+     * so this estimate fills the gap during trading hours.
+     */
+    calculateLiveOpenInterest(occSymbol) {
+        const baseOI = this.baseOpenInterest.get(occSymbol) ?? 0;
+        const cumulativeChange = this.cumulativeOIChange.get(occSymbol) ?? 0;
+        // Live OI cannot go negative
+        return Math.max(0, baseOI + cumulativeChange);
+    }
+    /**
+     * Returns the intraday trades for an option with aggressor classification.
+     *
+     * @param occSymbol - OCC option symbol
+     * @returns Array of intraday trades, or empty array if none
+     */
+    getIntradayTrades(occSymbol) {
+        return this.intradayTrades.get(occSymbol) ?? [];
+    }
+    /**
+     * Returns summary statistics for intraday option flow.
+     *
+     * @param occSymbol - OCC option symbol
+     * @returns Object with buy/sell volume, net OI change, and trade count
+     */
+    getFlowSummary(occSymbol) {
+        const trades = this.intradayTrades.get(occSymbol) ?? [];
+        let buyVolume = 0;
+        let sellVolume = 0;
+        let unknownVolume = 0;
+        for (const trade of trades) {
+            switch (trade.aggressorSide) {
+                case 'buy':
+                    buyVolume += trade.size;
+                    break;
+                case 'sell':
+                    sellVolume += trade.size;
+                    break;
+                case 'unknown':
+                    unknownVolume += trade.size;
+                    break;
+            }
+        }
+        return {
+            buyVolume,
+            sellVolume,
+            unknownVolume,
+            netOIChange: this.cumulativeOIChange.get(occSymbol) ?? 0,
+            tradeCount: trades.length,
+        };
+    }
+    /**
+     * Resets intraday tracking data. Call this at market open or when re-fetching base OI.
+     *
+     * @param occSymbols - Optional specific symbols to reset. If not provided, resets all.
+     */
+    resetIntradayData(occSymbols) {
+        const symbolsToReset = occSymbols ?? Array.from(this.intradayTrades.keys());
+        for (const symbol of symbolsToReset) {
+            this.intradayTrades.delete(symbol);
+            this.cumulativeOIChange.set(symbol, 0);
+        }
+    }
+    /**
+     * Checks if a symbol is an OCC option symbol.
+     */
+    isOptionSymbol(symbol) {
+        return OCC_OPTION_PATTERN.test(symbol);
+    }
+    /**
+     * Emits an event to all registered listeners.
+     */
+    emit(event, data) {
+        const listeners = this.eventListeners.get(event);
+        if (listeners) {
+            listeners.forEach(listener => {
+                try {
+                    listener(data);
+                }
+                catch (error) {
+                    // Don't let listener errors break the stream
+                    console.error('Event listener error:', error);
+                }
+            });
+        }
+    }
+    /**
+     * Simple sleep utility.
+     */
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}
+exports.TradierClient = TradierClient;