@fullstackcraftllc/floe 0.0.8 → 0.0.9

package/dist/client/brokers/BaseBrokerClient.js

@@ -0,0 +1,509 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseBrokerClient = exports.OCC_OPTION_PATTERN_WITH_SPACES = exports.OCC_OPTION_PATTERN = void 0;
+/**
+ * Regex pattern to identify OCC option symbols (compact format)
+ * Format: ROOT + YYMMDD + C/P + 8-digit strike
+ * Example: "AAPL240517C00170000"
+ */
+exports.OCC_OPTION_PATTERN = /^[A-Z]{1,6}\d{6}[CP]\d{8}$/;
+/**
+ * Regex pattern that also matches space-padded OCC symbols
+ * Example: "AAPL  240517C00170000"
+ */
+exports.OCC_OPTION_PATTERN_WITH_SPACES = /^.{1,6}\s*\d{6}[CP]\d{8}$/;
+/**
+ * Abstract base class for all broker streaming clients.
+ *
+ * @remarks
+ * This class provides shared state management, event handling, and utility methods
+ * that are common across all broker implementations. Subclasses implement the
+ * broker-specific connection, subscription, and data parsing logic.
+ *
+ * All broker clients normalize their data to `NormalizedOption` and `NormalizedTicker`
+ * formats, providing a consistent interface regardless of the underlying broker API.
+ */
+class BaseBrokerClient {
+    // ==================== Constructor ====================
+    constructor(options = {}) {
+        // ==================== Shared State ====================
+        /** Cached ticker data */
+        this.tickerCache = new Map();
+        /** Cached option data */
+        this.optionCache = new Map();
+        /** Base open interest from REST API - used as t=0 reference */
+        this.baseOpenInterest = new Map();
+        /** Cumulative estimated OI change from intraday trades */
+        this.cumulativeOIChange = new Map();
+        /** History of intraday trades with aggressor classification */
+        this.intradayTrades = new Map();
+        /** Event listeners */
+        this.eventListeners = new Map();
+        /** Currently subscribed symbols */
+        this.subscribedSymbols = new Set();
+        /** Reconnection attempt counter */
+        this.reconnectAttempts = 0;
+        this.verbose = options.verbose ?? false;
+        this.maxReconnectAttempts = options.maxReconnectAttempts ?? 5;
+        this.baseReconnectDelay = options.baseReconnectDelay ?? 1000;
+        // 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());
+    }
+    // ==================== Concrete Public Methods ====================
+    /**
+     * Returns cached option data for a symbol.
+     * @param occSymbol - OCC option symbol
+     */
+    getOption(occSymbol) {
+        return this.optionCache.get(this.normalizeOccSymbol(occSymbol));
+    }
+    /**
+     * Returns all cached options.
+     */
+    getAllOptions() {
+        return new Map(this.optionCache);
+    }
+    /**
+     * Returns cached ticker data for a symbol.
+     * @param symbol - Ticker symbol
+     */
+    getTicker(symbol) {
+        return this.tickerCache.get(symbol);
+    }
+    /**
+     * Returns all cached tickers.
+     */
+    getAllTickers() {
+        return new Map(this.tickerCache);
+    }
+    /**
+     * Returns intraday trades for an option.
+     * @param occSymbol - OCC option symbol
+     */
+    getIntradayTrades(occSymbol) {
+        return this.intradayTrades.get(this.normalizeOccSymbol(occSymbol)) ?? [];
+    }
+    /**
+     * Returns flow summary statistics for an option.
+     * @param occSymbol - OCC option symbol
+     */
+    getFlowSummary(occSymbol) {
+        const normalizedSymbol = this.normalizeOccSymbol(occSymbol);
+        const trades = this.intradayTrades.get(normalizedSymbol) ?? [];
+        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(normalizedSymbol) ?? 0,
+            tradeCount: trades.length,
+        };
+    }
+    /**
+     * Resets intraday tracking data.
+     * @param occSymbols - Optional specific symbols to reset. If not provided, resets all.
+     */
+    resetIntradayData(occSymbols) {
+        const symbolsToReset = occSymbols?.map(s => this.normalizeOccSymbol(s))
+            ?? Array.from(this.intradayTrades.keys());
+        for (const symbol of symbolsToReset) {
+            this.intradayTrades.delete(symbol);
+            this.cumulativeOIChange.set(symbol, 0);
+        }
+    }
+    /**
+     * 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;
+    }
+    // ==================== Protected Helpers ====================
+    /**
+     * 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) {
+        if (bid <= 0 || ask <= 0)
+            return 'unknown';
+        const spread = ask - bid;
+        const tolerance = spread > 0 ? spread * 0.001 : 0.001;
+        if (tradePrice >= ask - tolerance) {
+            return 'buy';
+        }
+        else if (tradePrice <= bid + tolerance) {
+            return 'sell';
+        }
+        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
+     * @returns Estimated OI change (positive = OI increase, negative = OI decrease)
+     *
+     * @remarks
+     * This uses a simplified heuristic:
+     * - Buy aggressor → typically opening new long positions → +OI
+     * - Sell aggressor → typically closing longs or opening shorts → -OI
+     * - Unknown → ambiguous, assume neutral impact
+     */
+    calculateOIChangeFromTrade(aggressorSide, size) {
+        if (aggressorSide === 'unknown')
+            return 0;
+        return aggressorSide === 'buy' ? size : -size;
+    }
+    /**
+     * Calculates the live (intraday) open interest estimate for an option.
+     *
+     * @param occSymbol - OCC option symbol
+     * @returns Live OI estimate = base OI + cumulative estimated changes
+     */
+    calculateLiveOpenInterest(occSymbol) {
+        const baseOI = this.baseOpenInterest.get(occSymbol) ?? 0;
+        const cumulativeChange = this.cumulativeOIChange.get(occSymbol) ?? 0;
+        return Math.max(0, baseOI + cumulativeChange);
+    }
+    /**
+     * Records a trade and updates OI tracking.
+     */
+    recordTrade(occSymbol, price, size, bid, ask, timestamp, optionType) {
+        const aggressorSide = this.determineAggressorSide(price, bid, ask);
+        const estimatedOIChange = this.calculateOIChangeFromTrade(aggressorSide, size);
+        const currentChange = this.cumulativeOIChange.get(occSymbol) ?? 0;
+        this.cumulativeOIChange.set(occSymbol, currentChange + estimatedOIChange);
+        if (this.verbose && estimatedOIChange !== 0) {
+            const baseOI = this.baseOpenInterest.get(occSymbol) ?? 0;
+            const newLiveOI = Math.max(0, baseOI + currentChange + estimatedOIChange);
+            console.log(`[${this.brokerName}:OI] ${occSymbol} trade: price=${price.toFixed(2)}, size=${size}, ` +
+                `aggressor=${aggressorSide}, OI change=${estimatedOIChange > 0 ? '+' : ''}${estimatedOIChange}, ` +
+                `liveOI=${newLiveOI} (base=${baseOI}, cumulative=${currentChange + estimatedOIChange})`);
+        }
+        const trade = {
+            occSymbol,
+            price,
+            size,
+            bid,
+            ask,
+            aggressorSide,
+            timestamp,
+            estimatedOIChange,
+        };
+        if (!this.intradayTrades.has(occSymbol)) {
+            this.intradayTrades.set(occSymbol, []);
+        }
+        this.intradayTrades.get(occSymbol).push(trade);
+        this.emit('optionTrade', trade);
+    }
+    /**
+     * Sets base open interest for a symbol.
+     */
+    setBaseOpenInterest(occSymbol, openInterest) {
+        if (openInterest > 0 && !this.baseOpenInterest.has(occSymbol)) {
+            this.baseOpenInterest.set(occSymbol, openInterest);
+            if (!this.cumulativeOIChange.has(occSymbol)) {
+                this.cumulativeOIChange.set(occSymbol, 0);
+            }
+            if (this.verbose) {
+                console.log(`[${this.brokerName}:OI] Base OI set for ${occSymbol}: ${openInterest}`);
+            }
+        }
+    }
+    /**
+     * 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) {
+                    console.error(`[${this.brokerName}] Event listener error:`, error);
+                }
+            });
+        }
+    }
+    /**
+     * Normalizes an OCC symbol to consistent format.
+     * Removes extra spaces, ensures proper formatting.
+     */
+    normalizeOccSymbol(symbol) {
+        const stripped = symbol.replace(/\s+/g, '');
+        const match = stripped.match(/^([A-Z]+)(\d{6})([CP])(\d{8})$/);
+        if (match) {
+            return `${match[1]}${match[2]}${match[3]}${match[4]}`;
+        }
+        return stripped;
+    }
+    /**
+     * Checks if a symbol is an OCC option symbol.
+     */
+    isOptionSymbol(symbol) {
+        const normalized = symbol.replace(/\s+/g, '');
+        return exports.OCC_OPTION_PATTERN.test(normalized) || /\d{6}[CP]\d{8}/.test(normalized);
+    }
+    /**
+     * Converts value to number, handling NaN and null.
+     */
+    toNumber(value) {
+        if (value === null || value === undefined)
+            return 0;
+        if (typeof value === 'number')
+            return isNaN(value) ? 0 : value;
+        if (typeof value === 'string') {
+            const num = parseFloat(value);
+            return isNaN(num) ? 0 : num;
+        }
+        return 0;
+    }
+    /**
+     * Sleep utility for delays and reconnection backoff.
+     */
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /**
+     * Calculates reconnection delay with exponential backoff.
+     */
+    getReconnectDelay() {
+        return this.baseReconnectDelay * Math.pow(2, this.reconnectAttempts - 1);
+    }
+    /**
+     * Logs a message if verbose mode is enabled.
+     */
+    log(message) {
+        if (this.verbose) {
+            console.log(`[${this.brokerName}] ${message}`);
+        }
+    }
+    // ==================== Common Update Helpers ====================
+    /**
+     * Updates or creates a ticker from quote data (bid/ask update).
+     * @returns The updated ticker
+     */
+    updateTickerFromQuoteData(symbol, bid, bidSize, ask, askSize, timestamp) {
+        const existing = this.tickerCache.get(symbol);
+        const ticker = {
+            symbol,
+            spot: bid > 0 && ask > 0 ? (bid + ask) / 2 : existing?.spot ?? 0,
+            bid,
+            bidSize,
+            ask,
+            askSize,
+            last: existing?.last ?? 0,
+            volume: existing?.volume ?? 0,
+            timestamp,
+        };
+        this.tickerCache.set(symbol, ticker);
+        this.emit('tickerUpdate', ticker);
+        return ticker;
+    }
+    /**
+     * Updates or creates a ticker from trade data (last price/volume update).
+     * @returns The updated ticker
+     */
+    updateTickerFromTradeData(symbol, price, size, dayVolume, timestamp) {
+        const existing = this.tickerCache.get(symbol);
+        const ticker = {
+            symbol,
+            spot: existing?.spot ?? price,
+            bid: existing?.bid ?? 0,
+            bidSize: existing?.bidSize ?? 0,
+            ask: existing?.ask ?? 0,
+            askSize: existing?.askSize ?? 0,
+            last: price,
+            volume: dayVolume !== null ? dayVolume : (existing?.volume ?? 0) + size,
+            timestamp,
+        };
+        this.tickerCache.set(symbol, ticker);
+        this.emit('tickerUpdate', ticker);
+        return ticker;
+    }
+    /**
+     * Updates or creates an option from quote data (bid/ask update).
+     * @returns The updated option, or null if symbol cannot be parsed
+     */
+    updateOptionFromQuoteData(occSymbol, bid, bidSize, ask, askSize, timestamp, parseSymbolFn) {
+        const existing = this.optionCache.get(occSymbol);
+        let parsed;
+        try {
+            parsed = parseSymbolFn(occSymbol);
+        }
+        catch {
+            if (!existing)
+                return null;
+            parsed = {
+                symbol: existing.underlying,
+                expiration: new Date(existing.expirationTimestamp),
+                optionType: existing.optionType,
+                strike: existing.strike,
+            };
+        }
+        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,
+            ask,
+            askSize,
+            mark: bid > 0 && ask > 0 ? (bid + ask) / 2 : existing?.mark ?? 0,
+            last: existing?.last ?? 0,
+            volume: existing?.volume ?? 0,
+            openInterest: existing?.openInterest ?? 0,
+            liveOpenInterest: this.calculateLiveOpenInterest(occSymbol),
+            impliedVolatility: existing?.impliedVolatility ?? 0,
+            timestamp,
+        };
+        this.optionCache.set(occSymbol, option);
+        this.emit('optionUpdate', option);
+        return option;
+    }
+    /**
+     * Updates or creates an option from trade data, including OI tracking.
+     * @returns The updated option, or null if symbol cannot be parsed
+     */
+    updateOptionFromTradeData(occSymbol, price, size, dayVolume, timestamp, parseSymbolFn) {
+        const existing = this.optionCache.get(occSymbol);
+        let parsed;
+        try {
+            parsed = parseSymbolFn(occSymbol);
+        }
+        catch {
+            if (!existing)
+                return null;
+            parsed = {
+                symbol: existing.underlying,
+                expiration: new Date(existing.expirationTimestamp),
+                optionType: existing.optionType,
+                strike: existing.strike,
+            };
+        }
+        const bid = existing?.bid ?? 0;
+        const ask = existing?.ask ?? 0;
+        // Record trade for OI tracking
+        this.recordTrade(occSymbol, price, size, bid, ask, timestamp, parsed.optionType);
+        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,
+            ask,
+            askSize: existing?.askSize ?? 0,
+            mark: bid > 0 && ask > 0 ? (bid + ask) / 2 : price,
+            last: price,
+            volume: dayVolume !== null ? dayVolume : (existing?.volume ?? 0) + size,
+            openInterest: existing?.openInterest ?? 0,
+            liveOpenInterest: this.calculateLiveOpenInterest(occSymbol),
+            impliedVolatility: existing?.impliedVolatility ?? 0,
+            timestamp,
+        };
+        this.optionCache.set(occSymbol, option);
+        this.emit('optionUpdate', option);
+        return option;
+    }
+    /**
+     * Updates or creates an option from timesale data (trade with bid/ask at time of sale).
+     * This is particularly useful for live OI tracking.
+     * @returns The updated option, or null if symbol cannot be parsed
+     */
+    updateOptionFromTimesaleData(occSymbol, price, size, bid, ask, timestamp, parseSymbolFn) {
+        const existing = this.optionCache.get(occSymbol);
+        let parsed;
+        try {
+            parsed = parseSymbolFn(occSymbol);
+        }
+        catch {
+            if (!existing)
+                return null;
+            parsed = {
+                symbol: existing.underlying,
+                expiration: new Date(existing.expirationTimestamp),
+                optionType: existing.optionType,
+                strike: existing.strike,
+            };
+        }
+        // Record trade for OI tracking (timesale has fresh bid/ask)
+        this.recordTrade(occSymbol, price, size, bid, ask, timestamp, parsed.optionType);
+        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,
+            ask,
+            askSize: existing?.askSize ?? 0,
+            mark: (bid + ask) / 2,
+            last: price,
+            volume: (existing?.volume ?? 0) + size,
+            openInterest: existing?.openInterest ?? 0,
+            liveOpenInterest: this.calculateLiveOpenInterest(occSymbol),
+            impliedVolatility: existing?.impliedVolatility ?? 0,
+            timestamp,
+        };
+        this.optionCache.set(occSymbol, option);
+        this.emit('optionUpdate', option);
+        return option;
+    }
+}
+exports.BaseBrokerClient = BaseBrokerClient;