@fullstackcraftllc/floe 0.0.3 → 0.0.5

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

@@ -0,0 +1,361 @@
+import { NormalizedOption, NormalizedTicker } from '../../types';
+/**
+ * TradeStation symbol details response
+ */
+interface TradeStationSymbolDetails {
+    Symbols: Array<{
+        Symbol: string;
+        Description?: string;
+        Exchange?: string;
+        Currency?: string;
+        PointValue?: number;
+        AssetType?: string;
+        FutureType?: string;
+        ExpirationDate?: string;
+        StrikePrice?: number;
+        OptionType?: string;
+        Root?: string;
+        Underlying?: string;
+    }>;
+    Errors: Array<{
+        Symbol: string;
+        Error: string;
+    }>;
+}
+/**
+ * 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 TradeStationClient
+ */
+type TradeStationClientEventType = 'tickerUpdate' | 'optionUpdate' | 'optionTrade' | 'connected' | 'disconnected' | 'error';
+/**
+ * Event listener callback type
+ */
+type TradeStationEventListener<T> = (data: T) => void;
+/**
+ * TradeStationClient handles real-time streaming connections to the TradeStation API
+ * via HTTP chunked transfer encoding.
+ *
+ * @remarks
+ * This client manages HTTP streaming connections to TradeStation's market data API,
+ * normalizes incoming quote data, and emits events for upstream consumption by
+ * the FloeClient.
+ *
+ * TradeStation uses HTTP streaming (chunked transfer encoding) instead of WebSockets.
+ * Each stream is a long-lived HTTP connection that returns JSON objects separated
+ * by newlines.
+ *
+ * @example
+ * ```typescript
+ * const client = new TradeStationClient({
+ *   accessToken: 'your-oauth-access-token'
+ * });
+ *
+ * client.on('tickerUpdate', (ticker) => {
+ *   console.log(`${ticker.symbol}: ${ticker.spot}`);
+ * });
+ *
+ * await client.connect();
+ * client.subscribe(['MSFT', 'AAPL']);
+ * ```
+ */
+export declare class TradeStationClient {
+    /** TradeStation OAuth access token */
+    private accessToken;
+    /** Connection state */
+    private connected;
+    /** Currently subscribed ticker symbols */
+    private subscribedTickers;
+    /** Currently subscribed option symbols */
+    private subscribedOptions;
+    /** Active AbortControllers for streams */
+    private activeStreams;
+    /** 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;
+    /** TradeStation API base URL */
+    private readonly apiBaseUrl;
+    /** Whether to use simulation environment */
+    private readonly simulation;
+    /** Refresh token for token refresh */
+    private refreshToken;
+    /** Token refresh callback */
+    private onTokenRefresh;
+    /** Whether to log verbose debug information */
+    private readonly verbose;
+    /**
+     * Creates a new TradeStationClient instance.
+     *
+     * @param options - Client configuration options
+     * @param options.accessToken - TradeStation OAuth access token (required)
+     * @param options.refreshToken - OAuth refresh token for automatic token renewal
+     * @param options.simulation - Whether to use simulation environment (default: false)
+     * @param options.onTokenRefresh - Callback when token is refreshed
+     * @param options.verbose - Whether to log verbose debug information (default: false)
+     */
+    constructor(options: {
+        accessToken: string;
+        refreshToken?: string;
+        simulation?: boolean;
+        onTokenRefresh?: (newToken: string) => void;
+        verbose?: boolean;
+    });
+    /**
+     * Establishes connection state for TradeStation streaming.
+     *
+     * @returns Promise that resolves when ready to stream
+     * @throws {Error} If token validation fails
+     *
+     * @remarks
+     * Unlike WebSocket-based clients, TradeStation uses HTTP streaming.
+     * This method validates the access token by making a test API call.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnects from all TradeStation streaming APIs.
+     */
+    disconnect(): void;
+    /**
+     * Subscribes to real-time updates for the specified symbols.
+     *
+     * @param symbols - Array of ticker symbols and/or option symbols
+     *
+     * @remarks
+     * TradeStation uses different streaming endpoints for equities and options.
+     * This method automatically routes symbols to the appropriate endpoint.
+     *
+     * Option symbols can be in either:
+     * - TradeStation format: "MSFT 220916C305"
+     * - OCC format: "MSFT220916C00305000"
+     */
+    subscribe(symbols: string[]): void;
+    /**
+     * Unsubscribes from real-time updates for the specified symbols.
+     *
+     * @param symbols - Array of symbols to unsubscribe from
+     *
+     * @remarks
+     * For TradeStation, unsubscribing requires stopping the stream and
+     * restarting with the remaining symbols.
+     */
+    unsubscribe(symbols: string[]): void;
+    /**
+     * Returns whether the client is currently connected.
+     */
+    isConnected(): boolean;
+    /**
+     * Fetches quote snapshots for the specified symbols.
+     *
+     * @param symbols - Array of symbols (max 100)
+     * @returns Array of normalized tickers
+     */
+    fetchQuotes(symbols: string[]): Promise<NormalizedTicker[]>;
+    /**
+     * Fetches option expirations for an underlying symbol.
+     *
+     * @param underlying - Underlying symbol (e.g., 'AAPL')
+     * @returns Array of expiration dates
+     */
+    fetchOptionExpirations(underlying: string): Promise<string[]>;
+    /**
+     * Streams option chain data for an underlying symbol.
+     *
+     * @param underlying - Underlying symbol (e.g., 'AAPL')
+     * @param options - Stream options
+     * @returns Promise that resolves when stream is established
+     */
+    streamOptionChain(underlying: string, options?: {
+        expiration?: string;
+        strikeProximity?: number;
+        enableGreeks?: boolean;
+        optionType?: 'All' | 'Call' | 'Put';
+    }): Promise<void>;
+    /**
+     * Fetches symbol details for the specified symbols.
+     *
+     * @param symbols - Array of symbols (max 50)
+     * @returns Symbol details response
+     */
+    fetchSymbolDetails(symbols: string[]): Promise<TradeStationSymbolDetails>;
+    /**
+     * Returns cached option data for a symbol.
+     */
+    getOption(occSymbol: string): NormalizedOption | undefined;
+    /**
+     * Returns all cached options.
+     */
+    getAllOptions(): Map<string, NormalizedOption>;
+    /**
+     * Returns cached ticker data for a symbol.
+     */
+    getTicker(symbol: string): NormalizedTicker | undefined;
+    /**
+     * Returns all cached tickers.
+     */
+    getAllTickers(): Map<string, NormalizedTicker>;
+    /**
+     * Registers an event listener.
+     */
+    on<T>(event: TradeStationClientEventType, listener: TradeStationEventListener<T>): this;
+    /**
+     * Removes an event listener.
+     */
+    off<T>(event: TradeStationClientEventType, listener: TradeStationEventListener<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;
+    /**
+     * Updates the access token (for token refresh scenarios).
+     */
+    updateAccessToken(newToken: string): void;
+    /**
+     * Gets authorization headers for API requests.
+     */
+    private getAuthHeaders;
+    /**
+     * Gets headers for streaming requests.
+     */
+    private getStreamHeaders;
+    /**
+     * Starts a quote stream for ticker symbols.
+     */
+    private startQuoteStream;
+    /**
+     * Starts an option quote stream.
+     */
+    private startOptionQuoteStream;
+    /**
+     * Starts an HTTP streaming connection.
+     */
+    private startHttpStream;
+    /**
+     * Processes an HTTP chunked stream.
+     */
+    private processStream;
+    /**
+     * Handles stream end/disconnect.
+     */
+    private handleStreamEnd;
+    /**
+     * Stops a stream by ID.
+     */
+    private stopStream;
+    /**
+     * Handles incoming quote stream data.
+     */
+    private handleQuoteData;
+    /**
+     * Handles incoming option quote stream data.
+     */
+    private handleOptionQuoteData;
+    /**
+     * Handles option chain stream data.
+     */
+    private handleOptionChainData;
+    /**
+     * Handles GoAway stream status - server is terminating stream.
+     */
+    private handleStreamGoAway;
+    /**
+     * Normalizes TradeStation quote to NormalizedTicker.
+     */
+    private normalizeQuote;
+    /**
+     * Normalizes TradeStation option quote to NormalizedOption.
+     */
+    private normalizeOptionQuote;
+    /**
+     * Converts TradeStation option symbol to OCC format.
+     * TradeStation format: "MSFT 220916C305" or "MSFT 220916C305.00"
+     * OCC format: "MSFT220916C00305000"
+     */
+    private toOCCSymbol;
+    /**
+     * Converts OCC symbol to TradeStation format.
+     * OCC format: "MSFT220916C00305000"
+     * TradeStation format: "MSFT 220916C305"
+     */
+    private toTradeStationOptionSymbol;
+    /**
+     * Determines aggressor side from trade price vs NBBO.
+     */
+    private determineAggressorSide;
+    /**
+     * Calculates estimated OI change from trade.
+     */
+    private calculateOIChangeFromTrade;
+    /**
+     * Calculates live open interest.
+     */
+    private calculateLiveOpenInterest;
+    /**
+     * Checks if a symbol is an option symbol.
+     */
+    private isOptionSymbol;
+    /**
+     * Parses a numeric string value.
+     */
+    private parseNumber;
+    /**
+     * Emits an event to all listeners.
+     */
+    private emit;
+    /**
+     * Sleep utility.
+     */
+    private sleep;
+}
+export {};