@fullstackcraftllc/floe 0.0.3 → 0.0.4

package/README.md

@@ -30,6 +30,28 @@ The same library that is used in Full Stack Craft's various fintech products inc
 - 💪 **Type-Safe** - Full TypeScript support
 - ⚡ **Zero Dependencies** - Lightweight and fast
 
+## Broker Support Roadmap
+
+Due to the overwhelming variety of how broker APIs structure their data (and how they make it available), there is a wide variety of how much support we can provide out-of-the-box for different brokers, summarized in this table:
+
+| Broker                | Black-Scholes | Greeks | Open Interest Based Exposures | Options-Book Based Exposures | Implied PDF Calculations |
+|-----------------------|--------------|--------|-------------------------------|------------------------------|-------------------------|
+| Tradier (via WebSocket) | ✅           | ✅     | ✅                            | ✅                           | Coming soon                        |
+| Schwab (via WebSocket)              | Coming soon           | Coming soon     | Coming soon                            | Coming soon                           | Coming soon                        |
+| Tastytrade (via WebSocket - DXLink Streamer)               | Coming soon           | Coming soon     | Coming soon                            | Coming soon                           | Coming soon                        |
+| TradeStation (via HTTP Streaming)              | Coming soon           | Coming soon     | Coming soon                            | Coming soon                           | Coming soon                        |
+
+Ideally all aspects of `floe` will be available for all brokers, but this will take time to determine as we work through the various data structures and formats that each broker provides.
+
+## Unsupported Brokers
+
+The following brokers have no public API:
+
+- Fidelity
+- Robinhood
+
+If your broker is not listed above, you can still use `floe` by normalizing your broker's data structures to match the expected input types. With options, you can get quite far with `floe` just by having the market price for the underlying and each option. (From those alone you can back out the IV, greeks, and exposures.)
+
 ## Installation
 
 ```bash

package/dist/client/FloeClient.d.ts

@@ -5,7 +5,9 @@ import { NormalizedOption, NormalizedTicker } from "../types";
  */
 export declare enum Broker {
     /** Tradier brokerage API */
-    TRADIER = "tradier"
+    TRADIER = "tradier",
+    /** TastyTrade brokerage API (uses DxLink WebSocket) */
+    TASTYTRADE = "tastytrade"
 }
 /**
  * Event types emitted by the FloeClient.
@@ -69,12 +71,10 @@ export declare class FloeClient {
     private currentSubscribedTickers;
     /** List of option symbols (OCC format) currently subscribed to */
     private currentSubscribedOptions;
-    /** Cache of the latest normalized ticker data */
-    private normalizedTickers;
-    /** Cache of the latest normalized option data */
-    private normalizedOptions;
     /** Tradier broker client instance */
     private tradierClient;
+    /** TastyTrade broker client instance */
+    private tastyTradeClient;
     /** Event listeners registry for the EventEmitter pattern */
     private eventListeners;
     /** Callback for ticker data changes (legacy callback pattern) */

package/dist/client/FloeClient.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FloeClient = exports.Broker = void 0;
 const TradierClient_1 = require("./brokers/TradierClient");
+const TastyTradeClient_1 = require("./brokers/TastyTradeClient");
 /**
  * Supported broker integrations for the FloeClient.
  * @enum {string}
@@ -10,7 +11,8 @@ var Broker;
 (function (Broker) {
     /** Tradier brokerage API */
     Broker["TRADIER"] = "tradier";
-    // Future brokers can be added here
+    /** TastyTrade brokerage API (uses DxLink WebSocket) */
+    Broker["TASTYTRADE"] = "tastytrade";
 })(Broker || (exports.Broker = Broker = {}));
 /**
  * FloeClient provides a unified, broker-agnostic interface for subscribing to
@@ -61,12 +63,10 @@ class FloeClient {
         this.currentSubscribedTickers = [];
         /** List of option symbols (OCC format) currently subscribed to */
         this.currentSubscribedOptions = [];
-        /** Cache of the latest normalized ticker data */
-        this.normalizedTickers = [];
-        /** Cache of the latest normalized option data */
-        this.normalizedOptions = [];
         /** Tradier broker client instance */
         this.tradierClient = null;
+        /** TastyTrade broker client instance */
+        this.tastyTradeClient = null;
         /** Event listeners registry for the EventEmitter pattern */
         this.eventListeners = new Map();
         /** Callback for ticker data changes (legacy callback pattern) */
@@ -119,6 +119,27 @@ class FloeClient {
                 // Connect to the streaming API
                 await this.tradierClient.connect();
                 break;
+            case Broker.TASTYTRADE:
+                // For TastyTrade, authKey is the session token
+                this.tastyTradeClient = new TastyTradeClient_1.TastyTradeClient({
+                    sessionToken: authKey,
+                });
+                // Wire up TastyTradeClient events to FloeClient events
+                this.tastyTradeClient.on('tickerUpdate', (ticker) => {
+                    this.emit('tickerUpdate', ticker);
+                });
+                this.tastyTradeClient.on('optionUpdate', (option) => {
+                    this.emit('optionUpdate', option);
+                });
+                this.tastyTradeClient.on('error', (error) => {
+                    this.emit('error', error);
+                });
+                this.tastyTradeClient.on('disconnected', () => {
+                    this.emit('disconnected', { broker, reason: 'DxLink WebSocket disconnected' });
+                });
+                // Connect to the streaming API
+                await this.tastyTradeClient.connect();
+                break;
             default:
                 throw new Error(`Unsupported broker: ${broker}`);
         }
@@ -140,6 +161,10 @@ class FloeClient {
             this.tradierClient.disconnect();
             this.tradierClient = null;
         }
+        if (this.tastyTradeClient) {
+            this.tastyTradeClient.disconnect();
+            this.tastyTradeClient = null;
+        }
         const broker = this.currentBroker;
         this.currentBroker = null;
         this.currentSubscribedTickers = [];
@@ -170,6 +195,9 @@ class FloeClient {
             case Broker.TRADIER:
                 this.tradierClient?.subscribe(tickers);
                 break;
+            case Broker.TASTYTRADE:
+                this.tastyTradeClient?.subscribe(tickers);
+                break;
             default:
                 throw new Error(`Unsupported broker: ${this.currentBroker}`);
         }
@@ -204,6 +232,9 @@ class FloeClient {
             case Broker.TRADIER:
                 this.tradierClient?.subscribe(symbols);
                 break;
+            case Broker.TASTYTRADE:
+                this.tastyTradeClient?.subscribe(symbols);
+                break;
             default:
                 throw new Error(`Unsupported broker: ${this.currentBroker}`);
         }
@@ -230,6 +261,9 @@ class FloeClient {
             case Broker.TRADIER:
                 this.tradierClient?.unsubscribe(tickers);
                 break;
+            case Broker.TASTYTRADE:
+                this.tastyTradeClient?.unsubscribe(tickers);
+                break;
             default:
                 throw new Error(`Unsupported broker: ${this.currentBroker}`);
         }
@@ -256,6 +290,9 @@ class FloeClient {
             case Broker.TRADIER:
                 this.tradierClient?.unsubscribe(symbols);
                 break;
+            case Broker.TASTYTRADE:
+                this.tastyTradeClient?.unsubscribe(symbols);
+                break;
             default:
                 throw new Error(`Unsupported broker: ${this.currentBroker}`);
         }
@@ -300,6 +337,9 @@ class FloeClient {
             case Broker.TRADIER:
                 await this.tradierClient?.fetchOpenInterest(symbolsToFetch);
                 break;
+            case Broker.TASTYTRADE:
+                await this.tastyTradeClient?.fetchOpenInterest(symbolsToFetch);
+                break;
             default:
                 throw new Error(`Unsupported broker: ${this.currentBroker}`);
         }
@@ -320,6 +360,8 @@ class FloeClient {
         switch (this.currentBroker) {
             case Broker.TRADIER:
                 return this.tradierClient?.getOption(occSymbol);
+            case Broker.TASTYTRADE:
+                return this.tastyTradeClient?.getOption(occSymbol);
             default:
                 return undefined;
         }
@@ -341,6 +383,8 @@ class FloeClient {
         switch (this.currentBroker) {
             case Broker.TRADIER:
                 return this.tradierClient?.getAllOptions() ?? new Map();
+            case Broker.TASTYTRADE:
+                return this.tastyTradeClient?.getAllOptions() ?? new Map();
             default:
                 return new Map();
         }

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