@fullstackcraftllc/floe 0.0.8 → 0.0.9

package/dist/client/brokers/TradierClient.js

@@ -2,13 +2,7 @@
 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}$/;
+const BaseBrokerClient_1 = require("./BaseBrokerClient");
 /**
  * TradierClient handles real-time streaming connections to the Tradier API.
  *
@@ -19,7 +13,7 @@ const OCC_OPTION_PATTERN = /^.{1,6}\d{6}[CP]\d{8}$/;
  *
  * @example
  * ```typescript
- * const client = new TradierClient('your-api-key');
+ * const client = new TradierClient({ authToken: 'your-api-key' });
  *
  * client.on('tickerUpdate', (ticker) => {
  *   console.log(`${ticker.symbol}: ${ticker.spot}`);
@@ -29,63 +23,28 @@ const OCC_OPTION_PATTERN = /^.{1,6}\d{6}[CP]\d{8}$/;
  * client.subscribe(['QQQ', 'AAPL  240119C00500000']);
  * ```
  */
-class TradierClient {
+class TradierClient extends BaseBrokerClient_1.BaseBrokerClient {
     /**
      * Creates a new TradierClient instance.
      *
-     * @param authToken - Tradier API auth token
-     * @param options - Optional configuration options
+     * @param options - Client configuration options
+     * @param options.authToken - Tradier API auth token (required)
      * @param options.verbose - Whether to log verbose debug information (default: false)
      */
-    constructor(authToken, options) {
+    constructor(options) {
+        super(options);
+        this.brokerName = 'Tradier';
         /** 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.authToken = authToken;
-        this.verbose = options?.verbose ?? false;
-        // 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());
+        this.authToken = options.authToken;
     }
     // ==================== Public API ====================
     /**
@@ -317,49 +276,6 @@ class TradierClient {
         });
         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.
@@ -488,7 +404,7 @@ class TradierClient {
     handleQuoteEvent(event) {
         const { symbol } = event;
         const timestamp = parseInt(event.biddate, 10) || Date.now();
-        const isOption = this.isOptionSymbol(symbol);
+        const isOption = this.isTradierOptionSymbol(symbol);
         if (isOption) {
             this.updateOptionFromQuote(symbol, event, timestamp);
         }
@@ -502,7 +418,7 @@ class TradierClient {
     handleTradeEvent(event) {
         const { symbol } = event;
         const timestamp = parseInt(event.date, 10) || Date.now();
-        const isOption = this.isOptionSymbol(symbol);
+        const isOption = this.isTradierOptionSymbol(symbol);
         if (isOption) {
             this.updateOptionFromTrade(symbol, event, timestamp);
         }
@@ -517,7 +433,7 @@ class TradierClient {
     handleTimesaleEvent(event) {
         const { symbol } = event;
         const timestamp = parseInt(event.date, 10) || Date.now();
-        const isOption = this.isOptionSymbol(symbol);
+        const isOption = this.isTradierOptionSymbol(symbol);
         if (isOption) {
             this.updateOptionFromTimesale(symbol, event, timestamp);
         }
@@ -529,113 +445,29 @@ class TradierClient {
      * 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);
+        this.updateTickerFromQuoteData(symbol, event.bid, event.bidsz, event.ask, event.asksz, timestamp);
     }
     /**
      * 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);
+        this.updateTickerFromTradeData(symbol, last, 0, volume, timestamp);
     }
     /**
      * 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);
+        this.updateOptionFromQuoteData(occSymbol, event.bid, event.bidsz, event.ask, event.asksz, timestamp, occ_1.parseOCCSymbol);
     }
     /**
      * 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);
+        this.updateOptionFromTradeData(occSymbol, last, 0, volume, timestamp, occ_1.parseOCCSymbol);
     }
     /**
      * Updates ticker data from a timesale event.
@@ -664,253 +496,19 @@ class TradierClient {
     /**
      * 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);
-        if (this.verbose && estimatedOIChange !== 0) {
-            const baseOI = this.baseOpenInterest.get(occSymbol) ?? 0;
-            const newLiveOI = Math.max(0, baseOI + currentChange + estimatedOIChange);
-            console.log(`[Tradier:OI] ${occSymbol} trade: price=${last.toFixed(2)}, size=${size}, aggressor=${aggressorSide}, OI change=${estimatedOIChange > 0 ? '+' : ''}${estimatedOIChange}, liveOI=${newLiveOI} (base=${baseOI}, cumulative=${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);
-        }
+        this.updateOptionFromTimesaleData(occSymbol, last, size, bid, ask, timestamp, occ_1.parseOCCSymbol);
     }
     /**
      * 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));
+    isTradierOptionSymbol(symbol) {
+        return BaseBrokerClient_1.OCC_OPTION_PATTERN.test(symbol);
     }
 }
 exports.TradierClient = TradierClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fullstackcraftllc/floe",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "Production-ready options analytics toolkit. Normalize broker data structures and calculate Black-Scholes, Greeks, and exposures with a clean, type-safe API. Built for trading platforms and fintech applications.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",