@fullstackcraftllc/floe 0.0.4 → 0.0.6

package/README.md

@@ -4,7 +4,7 @@
 
 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.
 
-The same library that is used in Full Stack Craft's 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).
+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).
 
 ## Quick Start / Documentation / Examples
 
@@ -23,12 +23,15 @@ The same library that is used in Full Stack Craft's various fintech products inc
 
 ## Features
 
-- 🎯 **Black-Scholes Pricing** - Fast, accurate options pricing
-- 📊 **Greeks Calculations** - Delta, gamma, theta, vega, rho
-- 🔄 **Dealer Exposure Metrics** - GEX, VEX, and CEX exposures
-- 🔌 **Broker-Agnostic** - Normalize data from any broker
-- 💪 **Type-Safe** - Full TypeScript support
-- ⚡ **Zero Dependencies** - Lightweight and fast
+- **Black-Scholes Pricing** - Fast, accurate options pricing
+- **Greeks Calculations** - Delta, gamma, theta, vega, rho
+- **Dealer Exposure Metrics** - GEX, VEX, and CEX exposures
+- **Implied Volatility & Surfaces** - Calculate IV from market prices and build volatility surfaces
+- **Implied PDF** - Risk-neutral probability density functions
+- **Real-Time Data** - Stream normalized options data from multiple brokers
+- **Broker-Agnostic** - Normalize data from any broker
+- **Type-Safe** - Full TypeScript support
+- **Zero Dependencies** - Lightweight and fast
 
 ## Broker Support Roadmap
 
@@ -36,10 +39,11 @@ Due to the overwhelming variety of how broker APIs structure their data (and how
 
 | 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                        |
+| Tradier (via WebSocket) | ✅           | ✅     | ✅                            | ✅                           |  ✅                         |
+| Tastytrade (via WebSocket - DXLink Streamer)               |  ✅            |  ✅      |  ✅                             |  ✅                            |  ✅                         |
+| TradeStation (via HTTP Streaming)              |  ✅            |  ✅      |  ✅                             |  ✅                            |  ✅                         |
+| Schwab (via WebSocket)              |  ✅            |  ✅      |  ✅                             |  ✅                            |  ✅                         |
+| Interactive Brokers (via WebSocket)              |  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.
 

package/dist/client/FloeClient.d.ts

@@ -7,7 +7,11 @@ export declare enum Broker {
     /** Tradier brokerage API */
     TRADIER = "tradier",
     /** TastyTrade brokerage API (uses DxLink WebSocket) */
-    TASTYTRADE = "tastytrade"
+    TASTYTRADE = "tastytrade",
+    /** TradeStation brokerage API (uses HTTP streaming) */
+    TRADESTATION = "tradestation",
+    /** Charles Schwab brokerage API (uses WebSocket streaming) */
+    SCHWAB = "schwab"
 }
 /**
  * Event types emitted by the FloeClient.
@@ -75,30 +79,47 @@ export declare class FloeClient {
     private tradierClient;
     /** TastyTrade broker client instance */
     private tastyTradeClient;
+    /** TradeStation broker client instance */
+    private tradeStationClient;
+    /** Schwab broker client instance */
+    private schwabClient;
     /** Event listeners registry for the EventEmitter pattern */
     private eventListeners;
     /** Callback for ticker data changes (legacy callback pattern) */
     private tickerDataCallback;
     /** Callback for option data changes (legacy callback pattern) */
     private optionDataCallback;
+    /** Whether to log verbose debug information */
+    private readonly verbose;
     /**
      * Creates a new FloeClient instance.
      *
+     * @param options - Optional configuration options
+     * @param options.verbose - Whether to log verbose debug information for all broker clients (default: false).
+     *                         When enabled, logs critical debug info such as live open interest changes,
+     *                         connection events, and reconnection attempts.
+     *
      * @remarks
      * The client is created in a disconnected state. Call {@link connect} to
      * establish a connection to a broker before subscribing to data.
      *
      * @example
      * ```typescript
+     * // Create client with default settings
      * const client = new FloeClient();
+     *
+     * // Create client with verbose logging enabled
+     * const verboseClient = new FloeClient({ verbose: true });
      * ```
      */
-    constructor();
+    constructor(options?: {
+        verbose?: boolean;
+    });
     /**
      * Establishes a connection to a broker's API.
      *
      * @param broker - The broker to connect to (e.g., Broker.TRADIER)
-     * @param authKey - The API authentication key or token for the broker
+     * @param authToken - The API authentication token for the broker
      *
      * @throws {Error} Throws if the specified broker is not supported
      *
@@ -111,7 +132,7 @@ export declare class FloeClient {
      * await client.connect(Broker.TRADIER, 'your-tradier-api-key');
      * ```
      */
-    connect(broker: Broker, authKey: string): Promise<void>;
+    connect(broker: Broker, authToken: string): Promise<void>;
     /**
      * Disconnects from the current broker.
      *

package/dist/client/FloeClient.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FloeClient = exports.Broker = void 0;
 const TradierClient_1 = require("./brokers/TradierClient");
 const TastyTradeClient_1 = require("./brokers/TastyTradeClient");
+const TradeStationClient_1 = require("./brokers/TradeStationClient");
+const SchwabClient_1 = require("./brokers/SchwabClient");
 /**
  * Supported broker integrations for the FloeClient.
  * @enum {string}
@@ -13,6 +15,10 @@ var Broker;
     Broker["TRADIER"] = "tradier";
     /** TastyTrade brokerage API (uses DxLink WebSocket) */
     Broker["TASTYTRADE"] = "tastytrade";
+    /** TradeStation brokerage API (uses HTTP streaming) */
+    Broker["TRADESTATION"] = "tradestation";
+    /** Charles Schwab brokerage API (uses WebSocket streaming) */
+    Broker["SCHWAB"] = "schwab";
 })(Broker || (exports.Broker = Broker = {}));
 /**
  * FloeClient provides a unified, broker-agnostic interface for subscribing to
@@ -47,16 +53,25 @@ class FloeClient {
     /**
      * Creates a new FloeClient instance.
      *
+     * @param options - Optional configuration options
+     * @param options.verbose - Whether to log verbose debug information for all broker clients (default: false).
+     *                         When enabled, logs critical debug info such as live open interest changes,
+     *                         connection events, and reconnection attempts.
+     *
      * @remarks
      * The client is created in a disconnected state. Call {@link connect} to
      * establish a connection to a broker before subscribing to data.
      *
      * @example
      * ```typescript
+     * // Create client with default settings
      * const client = new FloeClient();
+     *
+     * // Create client with verbose logging enabled
+     * const verboseClient = new FloeClient({ verbose: true });
      * ```
      */
-    constructor() {
+    constructor(options) {
         /** Currently connected broker, or null if not connected */
         this.currentBroker = null;
         /** List of ticker symbols currently subscribed to */
@@ -67,12 +82,17 @@ class FloeClient {
         this.tradierClient = null;
         /** TastyTrade broker client instance */
         this.tastyTradeClient = null;
+        /** TradeStation broker client instance */
+        this.tradeStationClient = null;
+        /** Schwab broker client instance */
+        this.schwabClient = null;
         /** Event listeners registry for the EventEmitter pattern */
         this.eventListeners = new Map();
         /** Callback for ticker data changes (legacy callback pattern) */
         this.tickerDataCallback = null;
         /** Callback for option data changes (legacy callback pattern) */
         this.optionDataCallback = null;
+        this.verbose = options?.verbose ?? false;
         // Initialize event listener maps for each event type
         this.eventListeners.set('tickerUpdate', new Set());
         this.eventListeners.set('optionUpdate', new Set());
@@ -84,7 +104,7 @@ class FloeClient {
      * Establishes a connection to a broker's API.
      *
      * @param broker - The broker to connect to (e.g., Broker.TRADIER)
-     * @param authKey - The API authentication key or token for the broker
+     * @param authToken - The API authentication token for the broker
      *
      * @throws {Error} Throws if the specified broker is not supported
      *
@@ -97,12 +117,12 @@ class FloeClient {
      * await client.connect(Broker.TRADIER, 'your-tradier-api-key');
      * ```
      */
-    async connect(broker, authKey) {
+    async connect(broker, authToken) {
         this.currentBroker = broker;
-        // Connection logic to the broker's API using the authKey
+        // Connection logic to the broker's API using the authToken
         switch (broker.toLowerCase()) {
             case Broker.TRADIER:
-                this.tradierClient = new TradierClient_1.TradierClient(authKey);
+                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);
@@ -120,9 +140,10 @@ class FloeClient {
                 await this.tradierClient.connect();
                 break;
             case Broker.TASTYTRADE:
-                // For TastyTrade, authKey is the session token
+                // For TastyTrade, authToken is the session token
                 this.tastyTradeClient = new TastyTradeClient_1.TastyTradeClient({
-                    sessionToken: authKey,
+                    sessionToken: authToken,
+                    verbose: this.verbose,
                 });
                 // Wire up TastyTradeClient events to FloeClient events
                 this.tastyTradeClient.on('tickerUpdate', (ticker) => {
@@ -140,6 +161,50 @@ class FloeClient {
                 // Connect to the streaming API
                 await this.tastyTradeClient.connect();
                 break;
+            case Broker.TRADESTATION:
+                // For TradeStation, authToken is the OAuth access token
+                this.tradeStationClient = new TradeStationClient_1.TradeStationClient({
+                    accessToken: authToken,
+                    verbose: this.verbose,
+                });
+                // Wire up TradeStationClient events to FloeClient events
+                this.tradeStationClient.on('tickerUpdate', (ticker) => {
+                    this.emit('tickerUpdate', ticker);
+                });
+                this.tradeStationClient.on('optionUpdate', (option) => {
+                    this.emit('optionUpdate', option);
+                });
+                this.tradeStationClient.on('error', (error) => {
+                    this.emit('error', error);
+                });
+                this.tradeStationClient.on('disconnected', () => {
+                    this.emit('disconnected', { broker, reason: 'HTTP stream disconnected' });
+                });
+                // Connect to the streaming API
+                await this.tradeStationClient.connect();
+                break;
+            case Broker.SCHWAB:
+                // For Schwab, authToken is the OAuth access token
+                this.schwabClient = new SchwabClient_1.SchwabClient({
+                    accessToken: authToken,
+                    verbose: this.verbose,
+                });
+                // Wire up SchwabClient events to FloeClient events
+                this.schwabClient.on('tickerUpdate', (ticker) => {
+                    this.emit('tickerUpdate', ticker);
+                });
+                this.schwabClient.on('optionUpdate', (option) => {
+                    this.emit('optionUpdate', option);
+                });
+                this.schwabClient.on('error', (error) => {
+                    this.emit('error', error);
+                });
+                this.schwabClient.on('disconnected', () => {
+                    this.emit('disconnected', { broker, reason: 'Schwab WebSocket disconnected' });
+                });
+                // Connect to the streaming API
+                await this.schwabClient.connect();
+                break;
             default:
                 throw new Error(`Unsupported broker: ${broker}`);
         }
@@ -165,6 +230,14 @@ class FloeClient {
             this.tastyTradeClient.disconnect();
             this.tastyTradeClient = null;
         }
+        if (this.tradeStationClient) {
+            this.tradeStationClient.disconnect();
+            this.tradeStationClient = null;
+        }
+        if (this.schwabClient) {
+            this.schwabClient.disconnect();
+            this.schwabClient = null;
+        }
         const broker = this.currentBroker;
         this.currentBroker = null;
         this.currentSubscribedTickers = [];
@@ -198,6 +271,12 @@ class FloeClient {
             case Broker.TASTYTRADE:
                 this.tastyTradeClient?.subscribe(tickers);
                 break;
+            case Broker.TRADESTATION:
+                this.tradeStationClient?.subscribe(tickers);
+                break;
+            case Broker.SCHWAB:
+                this.schwabClient?.subscribe(tickers);
+                break;
             default:
                 throw new Error(`Unsupported broker: ${this.currentBroker}`);
         }
@@ -235,6 +314,12 @@ class FloeClient {
             case Broker.TASTYTRADE:
                 this.tastyTradeClient?.subscribe(symbols);
                 break;
+            case Broker.TRADESTATION:
+                this.tradeStationClient?.subscribe(symbols);
+                break;
+            case Broker.SCHWAB:
+                this.schwabClient?.subscribe(symbols);
+                break;
             default:
                 throw new Error(`Unsupported broker: ${this.currentBroker}`);
         }
@@ -264,6 +349,12 @@ class FloeClient {
             case Broker.TASTYTRADE:
                 this.tastyTradeClient?.unsubscribe(tickers);
                 break;
+            case Broker.TRADESTATION:
+                this.tradeStationClient?.unsubscribe(tickers);
+                break;
+            case Broker.SCHWAB:
+                this.schwabClient?.unsubscribe(tickers);
+                break;
             default:
                 throw new Error(`Unsupported broker: ${this.currentBroker}`);
         }
@@ -293,6 +384,12 @@ class FloeClient {
             case Broker.TASTYTRADE:
                 this.tastyTradeClient?.unsubscribe(symbols);
                 break;
+            case Broker.TRADESTATION:
+                this.tradeStationClient?.unsubscribe(symbols);
+                break;
+            case Broker.SCHWAB:
+                this.schwabClient?.unsubscribe(symbols);
+                break;
             default:
                 throw new Error(`Unsupported broker: ${this.currentBroker}`);
         }
@@ -340,6 +437,13 @@ class FloeClient {
             case Broker.TASTYTRADE:
                 await this.tastyTradeClient?.fetchOpenInterest(symbolsToFetch);
                 break;
+            case Broker.TRADESTATION:
+                // TradeStation provides open interest via stream, no separate fetch needed
+                // OI is automatically populated when streaming option chains
+                break;
+            case Broker.SCHWAB:
+                await this.schwabClient?.fetchOpenInterest(symbolsToFetch);
+                break;
             default:
                 throw new Error(`Unsupported broker: ${this.currentBroker}`);
         }
@@ -362,6 +466,10 @@ class FloeClient {
                 return this.tradierClient?.getOption(occSymbol);
             case Broker.TASTYTRADE:
                 return this.tastyTradeClient?.getOption(occSymbol);
+            case Broker.TRADESTATION:
+                return this.tradeStationClient?.getOption(occSymbol);
+            case Broker.SCHWAB:
+                return this.schwabClient?.getOption(occSymbol);
             default:
                 return undefined;
         }
@@ -385,6 +493,10 @@ class FloeClient {
                 return this.tradierClient?.getAllOptions() ?? new Map();
             case Broker.TASTYTRADE:
                 return this.tastyTradeClient?.getAllOptions() ?? new Map();
+            case Broker.TRADESTATION:
+                return this.tradeStationClient?.getAllOptions() ?? new Map();
+            case Broker.SCHWAB:
+                return this.schwabClient?.getAllOptions() ?? new Map();
             default:
                 return new Map();
         }