@fullstackcraftllc/floe 0.0.2 → 0.0.4

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

@@ -0,0 +1,384 @@
+import { NormalizedOption } from '../../types';
+/**
+ * TastyTrade option chain item
+ */
+interface TastyTradeOptionChainItem {
+    symbol: string;
+    'instrument-type': string;
+    underlying: string;
+    strike: number;
+    'expiration-date': string;
+    'expiration-type': string;
+    'option-type': 'C' | 'P';
+    'root-symbol': string;
+    'streamer-symbol': string;
+    bid?: number;
+    ask?: number;
+    'bid-size'?: number;
+    'ask-size'?: number;
+    last?: number;
+    volume?: number;
+    'open-interest'?: number;
+    delta?: number;
+    gamma?: number;
+    theta?: number;
+    vega?: number;
+    'implied-volatility'?: number;
+}
+/**
+ * Aggressor side of a trade
+ */
+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 */
+    estimatedOIChange: number;
+}
+/**
+ * Event types emitted by TastyTradeClient
+ */
+type TastyTradeClientEventType = 'tickerUpdate' | 'optionUpdate' | 'optionTrade' | 'connected' | 'disconnected' | 'error';
+/**
+ * Event listener callback type
+ */
+type TastyTradeEventListener<T> = (data: T) => void;
+/**
+ * TastyTradeClient handles real-time streaming connections to the TastyTrade API
+ * via DxLink WebSockets.
+ *
+ * @remarks
+ * This client manages WebSocket connections to TastyTrade's DxLink streaming API,
+ * normalizes incoming quote and trade data, and emits events for upstream
+ * consumption by the FloeClient.
+ *
+ * Authentication flow:
+ * 1. Login to TastyTrade API to get session token (optional, can pass directly)
+ * 2. Use session token to get API quote token from /api-quote-tokens
+ * 3. Connect to DxLink WebSocket using the quote token
+ *
+ * @example
+ * ```typescript
+ * const client = new TastyTradeClient({
+ *   sessionToken: 'your-session-token'
+ * });
+ *
+ * client.on('tickerUpdate', (ticker) => {
+ *   console.log(`${ticker.symbol}: ${ticker.spot}`);
+ * });
+ *
+ * await client.connect();
+ * client.subscribe(['SPY', '.SPXW231215C4500']); // Equity and option
+ * ```
+ */
+export declare class TastyTradeClient {
+    /** TastyTrade session token */
+    private sessionToken;
+    /** DxLink API quote token */
+    private quoteToken;
+    /** DxLink WebSocket URL */
+    private dxLinkUrl;
+    /** WebSocket connection */
+    private ws;
+    /** Connection state */
+    private connected;
+    /** Authorization state */
+    private authorized;
+    /** Feed channel ID */
+    private feedChannelId;
+    /** Feed channel opened */
+    private feedChannelOpened;
+    /** Currently subscribed symbols */
+    private subscribedSymbols;
+    /** Map from streamer symbol to OCC symbol */
+    private streamerToOccMap;
+    /** Map from OCC symbol to streamer symbol */
+    private occToStreamerMap;
+    /** Cached ticker data */
+    private tickerCache;
+    /** Cached option data */
+    private optionCache;
+    /** Base open interest from REST API */
+    private baseOpenInterest;
+    /** Cumulative estimated OI change from intraday trades */
+    private cumulativeOIChange;
+    /** History of intraday trades */
+    private intradayTrades;
+    /** Event listeners */
+    private eventListeners;
+    /** Reconnection attempt counter */
+    private reconnectAttempts;
+    /** Maximum reconnection attempts */
+    private readonly maxReconnectAttempts;
+    /** Reconnection delay in ms */
+    private readonly baseReconnectDelay;
+    /** Keepalive interval handle */
+    private keepaliveInterval;
+    /** Keepalive timeout in seconds */
+    private readonly keepaliveTimeoutSeconds;
+    /** TastyTrade API base URL */
+    private readonly apiBaseUrl;
+    /** Whether to use sandbox environment */
+    private readonly sandbox;
+    /**
+     * Creates a new TastyTradeClient instance.
+     *
+     * @param options - Client configuration options
+     * @param options.sessionToken - TastyTrade session token (required)
+     * @param options.sandbox - Whether to use sandbox environment (default: false)
+     */
+    constructor(options: {
+        sessionToken: string;
+        sandbox?: boolean;
+    });
+    /**
+     * Creates a TastyTradeClient by logging in with username/password.
+     *
+     * @param username - TastyTrade username
+     * @param password - TastyTrade password
+     * @param options - Additional options
+     * @returns Promise resolving to configured TastyTradeClient
+     *
+     * @example
+     * ```typescript
+     * const client = await TastyTradeClient.fromCredentials(
+     *   'your-username',
+     *   'your-password'
+     * );
+     * await client.connect();
+     * ```
+     */
+    static fromCredentials(username: string, password: string, options?: {
+        sandbox?: boolean;
+        rememberMe?: boolean;
+    }): Promise<TastyTradeClient>;
+    /**
+     * Establishes a streaming connection to TastyTrade via DxLink.
+     *
+     * @returns Promise that resolves when connected and authorized
+     * @throws {Error} If token retrieval or WebSocket connection fails
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnects from the TastyTrade streaming API.
+     */
+    disconnect(): void;
+    /**
+     * Subscribes to real-time updates for the specified symbols.
+     *
+     * @param symbols - Array of ticker symbols and/or OCC option symbols
+     *
+     * @remarks
+     * For options, you can pass either:
+     * - OCC format symbols (e.g., 'SPY240119C00500000')
+     * - TastyTrade streamer symbols (e.g., '.SPXW240119C4500')
+     *
+     * The client will convert OCC symbols to streamer symbols automatically.
+     */
+    subscribe(symbols: string[]): void;
+    /**
+     * Unsubscribes from real-time updates for the specified symbols.
+     *
+     * @param symbols - Array of symbols to unsubscribe from
+     */
+    unsubscribe(symbols: string[]): void;
+    /**
+     * Returns whether the client is currently connected.
+     */
+    isConnected(): boolean;
+    /**
+     * Fetches options chain data from TastyTrade REST API.
+     *
+     * @param symbol - Underlying symbol (e.g., 'SPY')
+     * @returns Array of option chain items
+     */
+    fetchOptionsChain(symbol: string): Promise<TastyTradeOptionChainItem[]>;
+    /**
+     * Fetches open interest and other static data for subscribed options.
+     *
+     * @param occSymbols - Array of OCC option symbols to fetch data for
+     */
+    fetchOpenInterest(occSymbols: string[]): Promise<void>;
+    /**
+     * Returns cached option data for a symbol.
+     */
+    getOption(occSymbol: string): NormalizedOption | undefined;
+    /**
+     * Returns all cached options.
+     */
+    getAllOptions(): Map<string, NormalizedOption>;
+    /**
+     * Registers an event listener.
+     */
+    on<T>(event: TastyTradeClientEventType, listener: TastyTradeEventListener<T>): this;
+    /**
+     * Removes an event listener.
+     */
+    off<T>(event: TastyTradeClientEventType, listener: TastyTradeEventListener<T>): this;
+    /**
+     * Returns intraday trades for an option.
+     */
+    getIntradayTrades(occSymbol: string): IntradayTrade[];
+    /**
+     * Returns flow summary for an option.
+     */
+    getFlowSummary(occSymbol: string): {
+        buyVolume: number;
+        sellVolume: number;
+        unknownVolume: number;
+        netOIChange: number;
+        tradeCount: number;
+    };
+    /**
+     * Resets intraday tracking data.
+     */
+    resetIntradayData(occSymbols?: string[]): void;
+    /**
+     * Gets API quote token from TastyTrade.
+     */
+    private getQuoteToken;
+    /**
+     * Connects to DxLink WebSocket.
+     */
+    private connectWebSocket;
+    /**
+     * Sends SETUP message to DxLink.
+     */
+    private sendSetup;
+    /**
+     * Sends AUTH message to DxLink.
+     */
+    private sendAuth;
+    /**
+     * Opens a FEED channel.
+     */
+    private openFeedChannel;
+    /**
+     * Configures the feed channel with desired event fields.
+     */
+    private setupFeed;
+    /**
+     * Sends feed subscription message.
+     */
+    private sendFeedSubscription;
+    /**
+     * Gets streamer symbol from OCC or ticker symbol.
+     */
+    private getStreamerSymbol;
+    /**
+     * Converts streamer symbol back to OCC format.
+     */
+    private streamerSymbolToOCC;
+    /**
+     * Starts keepalive interval.
+     */
+    private startKeepalive;
+    /**
+     * Handles incoming WebSocket messages.
+     */
+    private handleMessage;
+    /**
+     * Handles AUTH_STATE message.
+     */
+    private handleAuthState;
+    /**
+     * Handles CHANNEL_OPENED message.
+     */
+    private handleChannelOpened;
+    /**
+     * Handles FEED_DATA message.
+     */
+    private handleFeedData;
+    /**
+     * Processes a single event from FEED_DATA.
+     */
+    private processEventData;
+    /**
+     * Handles Quote events.
+     */
+    private handleQuoteEvent;
+    /**
+     * Handles Trade events.
+     */
+    private handleTradeEvent;
+    /**
+     * Handles Greeks events.
+     */
+    private handleGreeksEvent;
+    /**
+     * Handles Summary events (includes open interest).
+     */
+    private handleSummaryEvent;
+    /**
+     * Updates ticker from Quote event.
+     */
+    private updateTickerFromQuote;
+    /**
+     * Updates ticker from Trade event.
+     */
+    private updateTickerFromTrade;
+    /**
+     * Updates option from Quote event.
+     */
+    private updateOptionFromQuote;
+    /**
+     * Updates option from Trade event.
+     */
+    private updateOptionFromTrade;
+    /**
+     * Determines aggressor side from trade price vs NBBO.
+     */
+    private determineAggressorSide;
+    /**
+     * Calculates estimated OI change from trade.
+     */
+    private calculateOIChangeFromTrade;
+    /**
+     * Calculates live open interest.
+     */
+    private calculateLiveOpenInterest;
+    /**
+     * Handles DxLink error messages.
+     */
+    private handleError;
+    /**
+     * Attempts to reconnect with exponential backoff.
+     */
+    private attemptReconnect;
+    /**
+     * Checks if symbol is an OCC option symbol.
+     */
+    private isOptionSymbol;
+    /**
+     * Sends a message to the WebSocket.
+     */
+    private sendMessage;
+    /**
+     * Emits an event to all listeners.
+     */
+    private emit;
+    /**
+     * Converts value to number, handling NaN and null.
+     */
+    private toNumber;
+    /**
+     * Sleep utility.
+     */
+    private sleep;
+}
+export {};