@fullstackcraftllc/floe 0.0.1 → 0.0.3

package/dist/client/brokers/TradierClient.d.ts

@@ -0,0 +1,393 @@
+import { NormalizedOption } from '../../types';
+/**
+ * Aggressor side of a trade - determined by comparing trade price to NBBO
+ */
+export type AggressorSide = 'buy' | 'sell' | 'unknown';
+/**
+ * Intraday trade information with aggressor classification
+ */
+export interface IntradayTrade {
+    /** OCC option symbol */
+    occSymbol: string;
+    /** Trade price */
+    price: number;
+    /** Trade size (number of contracts) */
+    size: number;
+    /** Bid at time of trade */
+    bid: number;
+    /** Ask at time of trade */
+    ask: number;
+    /** Aggressor side determined from price vs NBBO */
+    aggressorSide: AggressorSide;
+    /** Timestamp of the trade */
+    timestamp: number;
+    /** Estimated OI change: +size for buy aggressor (new longs), -size for sell aggressor (closing longs/new shorts) */
+    estimatedOIChange: number;
+}
+/**
+ * Tradier option chain item from REST API
+ * GET /v1/markets/options/chains
+ */
+interface TradierOptionChainItem {
+    symbol: string;
+    description: string;
+    exch: string;
+    type: string;
+    last: number | null;
+    change: number | null;
+    volume: number;
+    open: number | null;
+    high: number | null;
+    low: number | null;
+    close: number | null;
+    bid: number;
+    ask: number;
+    underlying: string;
+    strike: number;
+    change_percentage: number | null;
+    average_volume: number;
+    last_volume: number;
+    trade_date: number;
+    prevclose: number | null;
+    week_52_high: number;
+    week_52_low: number;
+    bidsize: number;
+    bidexch: string;
+    bid_date: number;
+    asksize: number;
+    askexch: string;
+    ask_date: number;
+    open_interest: number;
+    contract_size: number;
+    expiration_date: string;
+    expiration_type: string;
+    option_type: 'call' | 'put';
+    root_symbol: string;
+    greeks?: {
+        delta: number;
+        gamma: number;
+        theta: number;
+        vega: number;
+        rho: number;
+        phi: number;
+        bid_iv: number;
+        mid_iv: number;
+        ask_iv: number;
+        smv_vol: number;
+        updated_at: string;
+    };
+}
+/**
+ * Event types emitted by TradierClient
+ */
+type TradierClientEventType = 'tickerUpdate' | 'optionUpdate' | 'optionTrade' | 'connected' | 'disconnected' | 'error';
+/**
+ * Event listener callback type
+ */
+type TradierEventListener<T> = (data: T) => void;
+/**
+ * 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']);
+ * ```
+ */
+export declare class TradierClient {
+    /** Tradier API authentication token */
+    private authKey;
+    /** Current streaming session */
+    private streamSession;
+    /** WebSocket connection */
+    private ws;
+    /** Connection state */
+    private connected;
+    /** Currently subscribed symbols (tickers and options) */
+    private subscribedSymbols;
+    /** Cached ticker data (for merging quote and trade events) */
+    private tickerCache;
+    /** Cached option data (for merging quote and trade events) */
+    private optionCache;
+    /**
+     * 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
+     */
+    private baseOpenInterest;
+    /**
+     * Cumulative estimated OI change from intraday trades
+     * Key: OCC symbol, Value: net estimated change (positive = more contracts opened)
+     */
+    private cumulativeOIChange;
+    /**
+     * History of intraday trades with aggressor classification
+     * Key: OCC symbol, Value: array of trades
+     */
+    private intradayTrades;
+    /** Event listeners */
+    private eventListeners;
+    /** Reconnection attempt counter */
+    private reconnectAttempts;
+    /** Maximum reconnection attempts */
+    private readonly maxReconnectAttempts;
+    /** Reconnection delay in ms (doubles with each attempt) */
+    private readonly baseReconnectDelay;
+    /** Tradier API base URL */
+    private readonly apiBaseUrl;
+    /** Tradier WebSocket URL */
+    private readonly wsUrl;
+    /**
+     * Creates a new TradierClient instance.
+     *
+     * @param authKey - Tradier API access token
+     */
+    constructor(authKey: string);
+    /**
+     * Establishes a streaming connection to Tradier.
+     *
+     * @returns Promise that resolves when connected
+     * @throws {Error} If session creation or WebSocket connection fails
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnects from the Tradier streaming API.
+     */
+    disconnect(): void;
+    /**
+     * Subscribes to real-time updates for the specified symbols.
+     *
+     * @param symbols - Array of ticker symbols and/or OCC option symbols
+     */
+    subscribe(symbols: string[]): void;
+    /**
+     * 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: string[]): void;
+    /**
+     * Returns whether the client is currently connected.
+     */
+    isConnected(): boolean;
+    /**
+     * 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
+     */
+    fetchOptionsChain(symbol: string, expiration: string, greeks?: boolean): Promise<TradierOptionChainItem[]>;
+    /**
+     * 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.
+     */
+    fetchOpenInterest(occSymbols: string[]): Promise<void>;
+    /**
+     * Returns the cached option data for a symbol.
+     *
+     * @param occSymbol - OCC option symbol
+     * @returns Cached option data or undefined
+     */
+    getOption(occSymbol: string): NormalizedOption | undefined;
+    /**
+     * Returns all cached options.
+     *
+     * @returns Map of OCC symbols to option data
+     */
+    getAllOptions(): Map<string, NormalizedOption>;
+    /**
+     * Registers an event listener.
+     *
+     * @param event - Event type to listen for
+     * @param listener - Callback function
+     */
+    on<T>(event: TradierClientEventType, listener: TradierEventListener<T>): this;
+    /**
+     * Removes an event listener.
+     *
+     * @param event - Event type
+     * @param listener - Callback function to remove
+     */
+    off<T>(event: TradierClientEventType, listener: TradierEventListener<T>): this;
+    /**
+     * Creates a streaming session with Tradier API.
+     */
+    private createStreamSession;
+    /**
+     * Connects to the Tradier WebSocket.
+     */
+    private connectWebSocket;
+    /**
+     * Attempts to reconnect with exponential backoff.
+     */
+    private attemptReconnect;
+    /**
+     * Handles incoming WebSocket messages.
+     */
+    private handleMessage;
+    /**
+     * Handles quote events (bid/ask updates).
+     */
+    private handleQuoteEvent;
+    /**
+     * Handles trade events (last price/volume updates).
+     */
+    private handleTradeEvent;
+    /**
+     * Handles timesale events (trade with bid/ask at time of sale).
+     * This is particularly useful for options where quote events may be sparse.
+     */
+    private handleTimesaleEvent;
+    /**
+     * Updates ticker data from a quote event.
+     */
+    private updateTickerFromQuote;
+    /**
+     * Updates ticker data from a trade event.
+     */
+    private updateTickerFromTrade;
+    /**
+     * Updates option data from a quote event.
+     */
+    private updateOptionFromQuote;
+    /**
+     * Updates option data from a trade event.
+     */
+    private updateOptionFromTrade;
+    /**
+     * Updates ticker data from a timesale event.
+     * Timesale events include bid/ask at the time of the trade.
+     */
+    private updateTickerFromTimesale;
+    /**
+     * 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
+     */
+    private updateOptionFromTimesale;
+    /**
+     * 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)
+     */
+    private determineAggressorSide;
+    /**
+     * 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.
+     */
+    private calculateOIChangeFromTrade;
+    /**
+     * 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.
+     */
+    private calculateLiveOpenInterest;
+    /**
+     * 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: string): IntradayTrade[];
+    /**
+     * 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: string): {
+        buyVolume: number;
+        sellVolume: number;
+        unknownVolume: number;
+        netOIChange: number;
+        tradeCount: number;
+    };
+    /**
+     * 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?: string[]): void;
+    /**
+     * Checks if a symbol is an OCC option symbol.
+     */
+    private isOptionSymbol;
+    /**
+     * Emits an event to all registered listeners.
+     */
+    private emit;
+    /**
+     * Simple sleep utility.
+     */
+    private sleep;
+}
+export {};