@fullstackcraftllc/floe 0.0.2 → 0.0.4

package/README.md

@@ -2,7 +2,7 @@
 
 ![npm](https://img.shields.io/npm/v/@fullstackcraftllc/floe?style=flat-square) ![License](https://img.shields.io/npm/l/@fullstackcraftllc/floe?style=flat-square) ![TypeScript](https://img.shields.io/badge/TypeScript-4.9-blue?style=flat-square&logo=typescript)
 
-Browser-only TypeScript functions for calculating Black-Scholes, Greeks, and dealer exposures with a clean, type-safe API. Built for use in trading platforms and fintech applications.
+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).
 
@@ -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) */
@@ -200,6 +200,65 @@ export declare class FloeClient {
      * ```
      */
     unsubscribeFromOptions(symbols: Array<string>): void;
+    /**
+     * Fetches open interest and initial option data via REST API.
+     *
+     * @param symbols - Array of option symbols in OCC format to fetch data for.
+     *                  If not provided, fetches data for all currently subscribed options.
+     * @returns Promise that resolves when all data has been fetched
+     *
+     * @throws {Error} Throws if no broker connection has been established
+     *
+     * @remarks
+     * Open interest is not available via streaming and must be fetched via REST API.
+     * This method should be called after subscribing to options to populate
+     * open interest, volume, and initial bid/ask values.
+     *
+     * The fetched data is automatically merged into the option cache and
+     * emitted via 'optionUpdate' events.
+     *
+     * @example
+     * ```typescript
+     * // Subscribe to options
+     * client.subscribeToOptions(optionSymbols);
+     *
+     * // Fetch open interest data
+     * await client.fetchOpenInterest();
+     *
+     * // Options now have open interest populated
+     * client.on('optionUpdate', (option) => {
+     *     console.log(`${option.occSymbol}: OI=${option.openInterest}`);
+     * });
+     * ```
+     */
+    fetchOpenInterest(symbols?: string[]): Promise<void>;
+    /**
+     * Returns cached option data for a specific symbol.
+     *
+     * @param occSymbol - OCC option symbol
+     * @returns Cached option data, or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const option = client.getOption('QQQ250117C00530000');
+     * console.log(`Open Interest: ${option?.openInterest}`);
+     * ```
+     */
+    getOption(occSymbol: string): NormalizedOption | undefined;
+    /**
+     * Returns all cached options.
+     *
+     * @returns Map of OCC symbols to option data
+     *
+     * @example
+     * ```typescript
+     * const allOptions = client.getAllOptions();
+     * for (const [symbol, option] of allOptions) {
+     *     console.log(`${symbol}: OI=${option.openInterest}`);
+     * }
+     * ```
+     */
+    getAllOptions(): Map<string, NormalizedOption>;
     /**
      * Registers an event listener for the specified event type.
      *

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,10 +290,105 @@ 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}`);
+        }
+    }
+    /**
+     * Fetches open interest and initial option data via REST API.
+     *
+     * @param symbols - Array of option symbols in OCC format to fetch data for.
+     *                  If not provided, fetches data for all currently subscribed options.
+     * @returns Promise that resolves when all data has been fetched
+     *
+     * @throws {Error} Throws if no broker connection has been established
+     *
+     * @remarks
+     * Open interest is not available via streaming and must be fetched via REST API.
+     * This method should be called after subscribing to options to populate
+     * open interest, volume, and initial bid/ask values.
+     *
+     * The fetched data is automatically merged into the option cache and
+     * emitted via 'optionUpdate' events.
+     *
+     * @example
+     * ```typescript
+     * // Subscribe to options
+     * client.subscribeToOptions(optionSymbols);
+     *
+     * // Fetch open interest data
+     * await client.fetchOpenInterest();
+     *
+     * // Options now have open interest populated
+     * client.on('optionUpdate', (option) => {
+     *     console.log(`${option.occSymbol}: OI=${option.openInterest}`);
+     * });
+     * ```
+     */
+    async fetchOpenInterest(symbols) {
+        const symbolsToFetch = symbols ?? this.currentSubscribedOptions;
+        if (symbolsToFetch.length === 0) {
+            return;
+        }
+        switch (this.currentBroker) {
+            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}`);
         }
     }
+    /**
+     * Returns cached option data for a specific symbol.
+     *
+     * @param occSymbol - OCC option symbol
+     * @returns Cached option data, or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const option = client.getOption('QQQ250117C00530000');
+     * console.log(`Open Interest: ${option?.openInterest}`);
+     * ```
+     */
+    getOption(occSymbol) {
+        switch (this.currentBroker) {
+            case Broker.TRADIER:
+                return this.tradierClient?.getOption(occSymbol);
+            case Broker.TASTYTRADE:
+                return this.tastyTradeClient?.getOption(occSymbol);
+            default:
+                return undefined;
+        }
+    }
+    /**
+     * Returns all cached options.
+     *
+     * @returns Map of OCC symbols to option data
+     *
+     * @example
+     * ```typescript
+     * const allOptions = client.getAllOptions();
+     * for (const [symbol, option] of allOptions) {
+     *     console.log(`${symbol}: OI=${option.openInterest}`);
+     * }
+     * ```
+     */
+    getAllOptions() {
+        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();
+        }
+    }
     // ==================== Event Emitter Pattern ====================
     /**
      * Registers an event listener for the specified event type.

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

@@ -0,0 +1,2 @@
+export declare class SchwabClient {
+}

package/dist/client/brokers/SchwabClient.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchwabClient = void 0;
+class SchwabClient {
+}
+exports.SchwabClient = SchwabClient;