@fullstackcraftllc/floe 0.0.8 → 0.0.9

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)
 
-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.
+Zero-dependency TypeScript functions for options flow: Black-Scholes, greeks, dealer exposures, implied PDFs, 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](https://fullstackcraft.com) 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.js

@@ -127,7 +127,7 @@ class FloeClient {
                 // No action needed for NONE broker; no-op
                 break;
             case Broker.TRADIER:
-                this.tradierClient = new TradierClient_1.TradierClient(authToken, { verbose: this.verbose });
+                this.tradierClient = new TradierClient_1.TradierClient({ authToken, verbose: this.verbose });
                 // Wire up TradierClient events to FloeClient events
                 this.tradierClient.on('tickerUpdate', (ticker) => {
                     this.emit('tickerUpdate', ticker);

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

@@ -0,0 +1,296 @@
+import { NormalizedOption, NormalizedTicker, OptionType } 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, -size for sell aggressor */
+    estimatedOIChange: number;
+}
+/**
+ * Flow summary statistics for an option
+ */
+export interface FlowSummary {
+    buyVolume: number;
+    sellVolume: number;
+    unknownVolume: number;
+    netOIChange: number;
+    tradeCount: number;
+}
+/**
+ * Event types emitted by broker clients
+ */
+export type BrokerClientEventType = 'tickerUpdate' | 'optionUpdate' | 'optionTrade' | 'connected' | 'disconnected' | 'error';
+/**
+ * Event listener callback type
+ */
+export type BrokerEventListener<T> = (data: T) => void;
+/**
+ * Regex pattern to identify OCC option symbols (compact format)
+ * Format: ROOT + YYMMDD + C/P + 8-digit strike
+ * Example: "AAPL240517C00170000"
+ */
+export declare const OCC_OPTION_PATTERN: RegExp;
+/**
+ * Regex pattern that also matches space-padded OCC symbols
+ * Example: "AAPL  240517C00170000"
+ */
+export declare const OCC_OPTION_PATTERN_WITH_SPACES: RegExp;
+/**
+ * Base configuration options shared by all broker clients
+ */
+export interface BaseBrokerClientOptions {
+    /** Whether to log verbose debug information */
+    verbose?: boolean;
+    /** Maximum reconnection attempts (default: 5) */
+    maxReconnectAttempts?: number;
+    /** Base reconnection delay in ms (default: 1000) */
+    baseReconnectDelay?: number;
+}
+/**
+ * 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.
+ */
+export declare abstract class BaseBrokerClient {
+    /** Cached ticker data */
+    protected tickerCache: Map<string, NormalizedTicker>;
+    /** Cached option data */
+    protected optionCache: Map<string, NormalizedOption>;
+    /** Base open interest from REST API - used as t=0 reference */
+    protected baseOpenInterest: Map<string, number>;
+    /** Cumulative estimated OI change from intraday trades */
+    protected cumulativeOIChange: Map<string, number>;
+    /** History of intraday trades with aggressor classification */
+    protected intradayTrades: Map<string, IntradayTrade[]>;
+    /** Event listeners */
+    protected eventListeners: Map<BrokerClientEventType, Set<BrokerEventListener<unknown>>>;
+    /** Currently subscribed symbols */
+    protected subscribedSymbols: Set<string>;
+    /** Reconnection attempt counter */
+    protected reconnectAttempts: number;
+    /** Maximum reconnection attempts */
+    protected readonly maxReconnectAttempts: number;
+    /** Reconnection delay in ms */
+    protected readonly baseReconnectDelay: number;
+    /** Whether to log verbose debug information */
+    protected readonly verbose: boolean;
+    /** Broker name for logging */
+    protected abstract readonly brokerName: string;
+    constructor(options?: BaseBrokerClientOptions);
+    /**
+     * Establishes a streaming connection to the broker.
+     * @returns Promise that resolves when connected
+     * @throws {Error} If connection fails
+     */
+    abstract connect(): Promise<void>;
+    /**
+     * Disconnects from the broker streaming API.
+     */
+    abstract disconnect(): void;
+    /**
+     * Subscribes to real-time updates for the specified symbols.
+     * @param symbols - Array of ticker symbols and/or OCC option symbols
+     */
+    abstract subscribe(symbols: string[]): void;
+    /**
+     * Unsubscribes from real-time updates for the specified symbols.
+     * @param symbols - Array of symbols to unsubscribe from
+     */
+    abstract unsubscribe(symbols: string[]): void;
+    /**
+     * Unsubscribes from all real-time updates.
+     */
+    abstract unsubscribeFromAll(): void;
+    /**
+     * Returns whether the client is currently connected.
+     */
+    abstract isConnected(): boolean;
+    /**
+     * Fetches open interest and other static data for the specified options.
+     * @param occSymbols - Array of OCC option symbols to fetch data for
+     */
+    abstract fetchOpenInterest(occSymbols: string[]): Promise<void>;
+    /**
+     * Returns cached option data for a symbol.
+     * @param occSymbol - OCC option symbol
+     */
+    getOption(occSymbol: string): NormalizedOption | undefined;
+    /**
+     * Returns all cached options.
+     */
+    getAllOptions(): Map<string, NormalizedOption>;
+    /**
+     * Returns cached ticker data for a symbol.
+     * @param symbol - Ticker symbol
+     */
+    getTicker(symbol: string): NormalizedTicker | undefined;
+    /**
+     * Returns all cached tickers.
+     */
+    getAllTickers(): Map<string, NormalizedTicker>;
+    /**
+     * Returns intraday trades for an option.
+     * @param occSymbol - OCC option symbol
+     */
+    getIntradayTrades(occSymbol: string): IntradayTrade[];
+    /**
+     * Returns flow summary statistics for an option.
+     * @param occSymbol - OCC option symbol
+     */
+    getFlowSummary(occSymbol: string): FlowSummary;
+    /**
+     * Resets intraday tracking data.
+     * @param occSymbols - Optional specific symbols to reset. If not provided, resets all.
+     */
+    resetIntradayData(occSymbols?: string[]): void;
+    /**
+     * Registers an event listener.
+     * @param event - Event type to listen for
+     * @param listener - Callback function
+     */
+    on<T>(event: BrokerClientEventType, listener: BrokerEventListener<T>): this;
+    /**
+     * Removes an event listener.
+     * @param event - Event type
+     * @param listener - Callback function to remove
+     */
+    off<T>(event: BrokerClientEventType, listener: BrokerEventListener<T>): this;
+    /**
+     * 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)
+     */
+    protected determineAggressorSide(tradePrice: number, bid: number, ask: number): AggressorSide;
+    /**
+     * 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
+     */
+    protected calculateOIChangeFromTrade(aggressorSide: AggressorSide, size: number): number;
+    /**
+     * Calculates the live (intraday) open interest estimate for an option.
+     *
+     * @param occSymbol - OCC option symbol
+     * @returns Live OI estimate = base OI + cumulative estimated changes
+     */
+    protected calculateLiveOpenInterest(occSymbol: string): number;
+    /**
+     * Records a trade and updates OI tracking.
+     */
+    protected recordTrade(occSymbol: string, price: number, size: number, bid: number, ask: number, timestamp: number, optionType?: OptionType): void;
+    /**
+     * Sets base open interest for a symbol.
+     */
+    protected setBaseOpenInterest(occSymbol: string, openInterest: number): void;
+    /**
+     * Emits an event to all registered listeners.
+     */
+    protected emit<T>(event: BrokerClientEventType, data: T): void;
+    /**
+     * Normalizes an OCC symbol to consistent format.
+     * Removes extra spaces, ensures proper formatting.
+     */
+    protected normalizeOccSymbol(symbol: string): string;
+    /**
+     * Checks if a symbol is an OCC option symbol.
+     */
+    protected isOptionSymbol(symbol: string): boolean;
+    /**
+     * Converts value to number, handling NaN and null.
+     */
+    protected toNumber(value: unknown): number;
+    /**
+     * Sleep utility for delays and reconnection backoff.
+     */
+    protected sleep(ms: number): Promise<void>;
+    /**
+     * Calculates reconnection delay with exponential backoff.
+     */
+    protected getReconnectDelay(): number;
+    /**
+     * Logs a message if verbose mode is enabled.
+     */
+    protected log(message: string): void;
+    /**
+     * Updates or creates a ticker from quote data (bid/ask update).
+     * @returns The updated ticker
+     */
+    protected updateTickerFromQuoteData(symbol: string, bid: number, bidSize: number, ask: number, askSize: number, timestamp: number): NormalizedTicker;
+    /**
+     * Updates or creates a ticker from trade data (last price/volume update).
+     * @returns The updated ticker
+     */
+    protected updateTickerFromTradeData(symbol: string, price: number, size: number, dayVolume: number | null, timestamp: number): NormalizedTicker;
+    /**
+     * Updates or creates an option from quote data (bid/ask update).
+     * @returns The updated option, or null if symbol cannot be parsed
+     */
+    protected updateOptionFromQuoteData(occSymbol: string, bid: number, bidSize: number, ask: number, askSize: number, timestamp: number, parseSymbolFn: (symbol: string) => {
+        symbol: string;
+        expiration: Date;
+        optionType: OptionType;
+        strike: number;
+    }): NormalizedOption | null;
+    /**
+     * Updates or creates an option from trade data, including OI tracking.
+     * @returns The updated option, or null if symbol cannot be parsed
+     */
+    protected updateOptionFromTradeData(occSymbol: string, price: number, size: number, dayVolume: number | null, timestamp: number, parseSymbolFn: (symbol: string) => {
+        symbol: string;
+        expiration: Date;
+        optionType: OptionType;
+        strike: number;
+    }): NormalizedOption | null;
+    /**
+     * 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
+     */
+    protected updateOptionFromTimesaleData(occSymbol: string, price: number, size: number, bid: number, ask: number, timestamp: number, parseSymbolFn: (symbol: string) => {
+        symbol: string;
+        expiration: Date;
+        optionType: OptionType;
+        strike: number;
+    }): NormalizedOption | null;
+}