@fullstackcraftllc/floe 0.0.2 → 0.0.3

package/README.md

@@ -2,7 +2,7 @@
 
 ![npm](https://img.shields.io/npm/v/@fullstackcraftllc/floe?style=flat-square) ![License](https://img.shields.io/npm/l/@fullstackcraftllc/floe?style=flat-square) ![TypeScript](https://img.shields.io/badge/TypeScript-4.9-blue?style=flat-square&logo=typescript)
 
-Browser-only TypeScript functions for calculating Black-Scholes, Greeks, and dealer exposures with a clean, type-safe API. Built for use in trading platforms and fintech applications.
+Zero-dependency TypeScript functions for options flow: Black-Scholes, Greeks, and dealer exposures, and more, with a clean, type-safe API. Built for use in trading platforms and fintech applications.
 
 The same library that is used in Full Stack Craft's various fintech products including [The Wheel Screener](https://wheelscreener.com), [LEAPS Screener](https://leapsscreener.com), [Option Screener](https://option-screener.com), [AMT JOY](https://amtjoy.com), and [VannaCharm](https://vannacharm.com).
 

package/dist/client/FloeClient.d.ts

@@ -200,6 +200,65 @@ export declare class FloeClient {
      * ```
      */
     unsubscribeFromOptions(symbols: Array<string>): void;
+    /**
+     * Fetches open interest and initial option data via REST API.
+     *
+     * @param symbols - Array of option symbols in OCC format to fetch data for.
+     *                  If not provided, fetches data for all currently subscribed options.
+     * @returns Promise that resolves when all data has been fetched
+     *
+     * @throws {Error} Throws if no broker connection has been established
+     *
+     * @remarks
+     * Open interest is not available via streaming and must be fetched via REST API.
+     * This method should be called after subscribing to options to populate
+     * open interest, volume, and initial bid/ask values.
+     *
+     * The fetched data is automatically merged into the option cache and
+     * emitted via 'optionUpdate' events.
+     *
+     * @example
+     * ```typescript
+     * // Subscribe to options
+     * client.subscribeToOptions(optionSymbols);
+     *
+     * // Fetch open interest data
+     * await client.fetchOpenInterest();
+     *
+     * // Options now have open interest populated
+     * client.on('optionUpdate', (option) => {
+     *     console.log(`${option.occSymbol}: OI=${option.openInterest}`);
+     * });
+     * ```
+     */
+    fetchOpenInterest(symbols?: string[]): Promise<void>;
+    /**
+     * Returns cached option data for a specific symbol.
+     *
+     * @param occSymbol - OCC option symbol
+     * @returns Cached option data, or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const option = client.getOption('QQQ250117C00530000');
+     * console.log(`Open Interest: ${option?.openInterest}`);
+     * ```
+     */
+    getOption(occSymbol: string): NormalizedOption | undefined;
+    /**
+     * Returns all cached options.
+     *
+     * @returns Map of OCC symbols to option data
+     *
+     * @example
+     * ```typescript
+     * const allOptions = client.getAllOptions();
+     * for (const [symbol, option] of allOptions) {
+     *     console.log(`${symbol}: OI=${option.openInterest}`);
+     * }
+     * ```
+     */
+    getAllOptions(): Map<string, NormalizedOption>;
     /**
      * Registers an event listener for the specified event type.
      *

package/dist/client/FloeClient.js

@@ -260,6 +260,91 @@ class FloeClient {
                 throw new Error(`Unsupported broker: ${this.currentBroker}`);
         }
     }
+    /**
+     * Fetches open interest and initial option data via REST API.
+     *
+     * @param symbols - Array of option symbols in OCC format to fetch data for.
+     *                  If not provided, fetches data for all currently subscribed options.
+     * @returns Promise that resolves when all data has been fetched
+     *
+     * @throws {Error} Throws if no broker connection has been established
+     *
+     * @remarks
+     * Open interest is not available via streaming and must be fetched via REST API.
+     * This method should be called after subscribing to options to populate
+     * open interest, volume, and initial bid/ask values.
+     *
+     * The fetched data is automatically merged into the option cache and
+     * emitted via 'optionUpdate' events.
+     *
+     * @example
+     * ```typescript
+     * // Subscribe to options
+     * client.subscribeToOptions(optionSymbols);
+     *
+     * // Fetch open interest data
+     * await client.fetchOpenInterest();
+     *
+     * // Options now have open interest populated
+     * client.on('optionUpdate', (option) => {
+     *     console.log(`${option.occSymbol}: OI=${option.openInterest}`);
+     * });
+     * ```
+     */
+    async fetchOpenInterest(symbols) {
+        const symbolsToFetch = symbols ?? this.currentSubscribedOptions;
+        if (symbolsToFetch.length === 0) {
+            return;
+        }
+        switch (this.currentBroker) {
+            case Broker.TRADIER:
+                await this.tradierClient?.fetchOpenInterest(symbolsToFetch);
+                break;
+            default:
+                throw new Error(`Unsupported broker: ${this.currentBroker}`);
+        }
+    }
+    /**
+     * Returns cached option data for a specific symbol.
+     *
+     * @param occSymbol - OCC option symbol
+     * @returns Cached option data, or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const option = client.getOption('QQQ250117C00530000');
+     * console.log(`Open Interest: ${option?.openInterest}`);
+     * ```
+     */
+    getOption(occSymbol) {
+        switch (this.currentBroker) {
+            case Broker.TRADIER:
+                return this.tradierClient?.getOption(occSymbol);
+            default:
+                return undefined;
+        }
+    }
+    /**
+     * Returns all cached options.
+     *
+     * @returns Map of OCC symbols to option data
+     *
+     * @example
+     * ```typescript
+     * const allOptions = client.getAllOptions();
+     * for (const [symbol, option] of allOptions) {
+     *     console.log(`${symbol}: OI=${option.openInterest}`);
+     * }
+     * ```
+     */
+    getAllOptions() {
+        switch (this.currentBroker) {
+            case Broker.TRADIER:
+                return this.tradierClient?.getAllOptions() ?? new Map();
+            default:
+                return new Map();
+        }
+    }
     // ==================== Event Emitter Pattern ====================
     /**
      * Registers an event listener for the specified event type.

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

@@ -0,0 +1,2 @@
+export declare class SchwabClient {
+}

package/dist/client/brokers/SchwabClient.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchwabClient = void 0;
+class SchwabClient {
+}
+exports.SchwabClient = SchwabClient;

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.
      */

package/dist/client/brokers/TradierClient.js

@@ -48,6 +48,21 @@ class TradierClient {
         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 */
@@ -64,6 +79,7 @@ class TradierClient {
         // 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());
@@ -138,6 +154,165 @@ class TradierClient {
     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.
      *
@@ -256,6 +431,10 @@ class TradierClient {
             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
@@ -289,6 +468,21 @@ class TradierClient {
             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.
      */
@@ -401,6 +595,247 @@ class TradierClient {
         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.
      */

package/dist/index.d.ts

@@ -14,4 +14,5 @@ export { buildOCCSymbol, parseOCCSymbol, generateStrikesAroundSpot, generateOCCS
 export type { OCCSymbolParams, ParsedOCCSymbol, StrikeGenerationParams, } from './utils/occ';
 export { FloeClient, Broker } from './client/FloeClient';
 export { TradierClient } from './client/brokers/TradierClient';
+export type { AggressorSide, IntradayTrade } from './client/brokers/TradierClient';
 export { genericAdapter, schwabAdapter, ibkrAdapter, tdaAdapter, brokerAdapters, getAdapter, createOptionChain, } from './adapters';

package/dist/utils/occ.d.ts

@@ -48,7 +48,7 @@ export interface StrikeGenerationParams {
     /** Number of strikes below spot to include */
     strikesBelow?: number;
     /** Strike increment (e.g., 1 for $1 increments, 5 for $5) */
-    strikeIncrement?: number;
+    strikeIncrementInDollars?: number;
 }
 /**
  * Builds an OCC-formatted option symbol.

package/dist/utils/occ.js

@@ -48,7 +48,8 @@ function buildOCCSymbol(params) {
         ? symbol.toUpperCase().padEnd(6, ' ')
         : symbol.toUpperCase();
     // Format expiration date as YYMMDD
-    const expirationDate = typeof expiration === 'string' ? new Date(expiration) : expiration;
+    // Use UTC methods to avoid timezone shifts when parsing ISO date strings
+    const expirationDate = typeof expiration === 'string' ? new Date(expiration + 'T12:00:00') : expiration;
     const year = expirationDate.getFullYear().toString().slice(-2);
     const month = (expirationDate.getMonth() + 1).toString().padStart(2, '0');
     const day = expirationDate.getDate().toString().padStart(2, '0');
@@ -100,11 +101,11 @@ function parseOCCSymbol(occSymbol) {
     if (symbol.length === 0) {
         throw new Error(`Invalid OCC symbol: no ticker found in ${occSymbol}`);
     }
-    // Parse date
+    // Parse date - use noon to avoid timezone edge cases
     const year = 2000 + parseInt(dateString.slice(0, 2), 10);
     const month = parseInt(dateString.slice(2, 4), 10) - 1; // 0-indexed
     const day = parseInt(dateString.slice(4, 6), 10);
-    const expiration = new Date(year, month, day);
+    const expiration = new Date(year, month, day, 12, 0, 0);
     // Validate date
     if (isNaN(expiration.getTime())) {
         throw new Error(`Invalid date in OCC symbol: ${dateString}`);
@@ -133,7 +134,7 @@ function parseOCCSymbol(occSymbol) {
  * ```
  */
 function generateStrikesAroundSpot(params) {
-    const { spot, strikesAbove = 10, strikesBelow = 10, strikeIncrement = 1 } = params;
+    const { spot, strikesAbove = 10, strikesBelow = 10, strikeIncrementInDollars: strikeIncrement = 1 } = params;
     // Find the nearest strike at or below spot
     const baseStrike = Math.floor(spot / strikeIncrement) * strikeIncrement;
     const strikes = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fullstackcraftllc/floe",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "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",