@fullstackcraftllc/floe 0.0.4 → 0.0.6

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

@@ -135,16 +135,20 @@ export declare class TastyTradeClient {
     private readonly apiBaseUrl;
     /** Whether to use sandbox environment */
     private readonly sandbox;
+    /** Whether to log verbose debug information */
+    private readonly verbose;
     /**
      * 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)
+     * @param options.verbose - Whether to log verbose debug information (default: false)
      */
     constructor(options: {
         sessionToken: string;
         sandbox?: boolean;
+        verbose?: boolean;
     });
     /**
      * Creates a TastyTradeClient by logging in with username/password.

package/dist/client/brokers/TastyTradeClient.js

@@ -52,6 +52,7 @@ class TastyTradeClient {
      * @param options - Client configuration options
      * @param options.sessionToken - TastyTrade session token (required)
      * @param options.sandbox - Whether to use sandbox environment (default: false)
+     * @param options.verbose - Whether to log verbose debug information (default: false)
      */
     constructor(options) {
         /** DxLink API quote token */
@@ -98,6 +99,7 @@ class TastyTradeClient {
         this.keepaliveTimeoutSeconds = 60;
         this.sessionToken = options.sessionToken;
         this.sandbox = options.sandbox ?? false;
+        this.verbose = options.verbose ?? false;
         this.apiBaseUrl = this.sandbox
             ? 'https://api.cert.tastyworks.com'
             : 'https://api.tastyworks.com';
@@ -291,6 +293,9 @@ class TastyTradeClient {
                     // Store base OI
                     if (item['open-interest'] !== undefined) {
                         this.baseOpenInterest.set(occSymbol, item['open-interest']);
+                        if (this.verbose) {
+                            console.log(`[TastyTrade:OI] Base OI set for ${occSymbol}: ${item['open-interest']}`);
+                        }
                     }
                     if (!this.cumulativeOIChange.has(occSymbol)) {
                         this.cumulativeOIChange.set(occSymbol, 0);
@@ -694,6 +699,9 @@ class TastyTradeClient {
             this.authorized = true;
             this.startKeepalive();
             this.openFeedChannel();
+            if (this.verbose) {
+                console.log('[TastyTrade:DxLink] Authorized and connected');
+            }
             this.emit('connected', undefined);
             connectResolve?.();
         }
@@ -824,6 +832,9 @@ class TastyTradeClient {
             // Update base OI if not set
             if (!this.baseOpenInterest.has(symbol)) {
                 this.baseOpenInterest.set(symbol, openInterest);
+                if (this.verbose) {
+                    console.log(`[TastyTrade:OI] Base OI set from stream for ${symbol}: ${openInterest}`);
+                }
             }
         }
     }
@@ -936,6 +947,11 @@ class TastyTradeClient {
         const estimatedOIChange = this.calculateOIChangeFromTrade(aggressorSide, size, parsed.optionType);
         const currentChange = this.cumulativeOIChange.get(occSymbol) ?? 0;
         this.cumulativeOIChange.set(occSymbol, currentChange + estimatedOIChange);
+        if (this.verbose && estimatedOIChange !== 0) {
+            const baseOI = this.baseOpenInterest.get(occSymbol) ?? 0;
+            const newLiveOI = Math.max(0, baseOI + currentChange + estimatedOIChange);
+            console.log(`[TastyTrade:OI] ${occSymbol} trade: price=${price.toFixed(2)}, size=${size}, aggressor=${aggressorSide}, OI change=${estimatedOIChange > 0 ? '+' : ''}${estimatedOIChange}, liveOI=${newLiveOI} (base=${baseOI}, cumulative=${currentChange + estimatedOIChange})`);
+        }
         // Record trade
         const trade = {
             occSymbol,
@@ -1022,6 +1038,9 @@ class TastyTradeClient {
         }
         this.reconnectAttempts++;
         const delay = this.baseReconnectDelay * Math.pow(2, this.reconnectAttempts - 1);
+        if (this.verbose) {
+            console.log(`[TastyTrade:DxLink] Reconnection attempt ${this.reconnectAttempts}/${this.maxReconnectAttempts} in ${delay}ms`);
+        }
         await this.sleep(delay);
         try {
             await this.connect();

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 {};