@fullstackcraftllc/floe 0.0.2 → 0.0.4

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

@@ -1,7 +1,86 @@
+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' | 'connected' | 'disconnected' | 'error';
+type TradierClientEventType = 'tickerUpdate' | 'optionUpdate' | 'optionTrade' | 'connected' | 'disconnected' | 'error';
 /**
  * Event listener callback type
  */
@@ -41,6 +120,21 @@ export declare class TradierClient {
     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 */
@@ -91,6 +185,40 @@ export declare class TradierClient {
      * 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.
      *
@@ -129,6 +257,11 @@ export declare class TradierClient {
      * 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.
      */
@@ -145,6 +278,105 @@ export declare class TradierClient {
      * 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.
      */