@fullstackcraftllc/floe 0.0.14 → 0.0.15

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)
 
-Zero-dependency TypeScript functions for options flow: Black-Scholes, greeks, IV surfaces, dealer exposures, implied PDFs, and more, 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, IV surfaces, dealer exposures, implied PDFs, and more, with a clean, type-safe API. Broker agnostic. Stream data from a variety of brokers with a uniform API. Built for use in trading platforms and fintech applications.
 
 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).
 

package/dist/client/FloeClient.d.ts

@@ -13,7 +13,9 @@ export declare enum Broker {
     /** TradeStation brokerage API (uses HTTP streaming) */
     TRADESTATION = "tradestation",
     /** Charles Schwab brokerage API (uses WebSocket streaming) */
-    SCHWAB = "schwab"
+    SCHWAB = "schwab",
+    /** Interactive Brokers Web API (OAuth) */
+    IBKR = "ibkr"
 }
 /**
  * Event types emitted by the FloeClient.
@@ -85,6 +87,8 @@ export declare class FloeClient {
     private tradeStationClient;
     /** Schwab broker client instance */
     private schwabClient;
+    /** Interactive Brokers broker client instance */
+    private ibkrClient;
     /** Event listeners registry for the EventEmitter pattern */
     private eventListeners;
     /** Callback for ticker data changes (legacy callback pattern) */

package/dist/client/FloeClient.js

@@ -5,6 +5,7 @@ const TradierClient_1 = require("./brokers/TradierClient");
 const TastyTradeClient_1 = require("./brokers/TastyTradeClient");
 const TradeStationClient_1 = require("./brokers/TradeStationClient");
 const SchwabClient_1 = require("./brokers/SchwabClient");
+const IBKRClient_1 = require("./brokers/IBKRClient");
 /**
  * Supported broker integrations for the FloeClient.
  * @enum {string}
@@ -21,6 +22,8 @@ var Broker;
     Broker["TRADESTATION"] = "tradestation";
     /** Charles Schwab brokerage API (uses WebSocket streaming) */
     Broker["SCHWAB"] = "schwab";
+    /** Interactive Brokers Web API (OAuth) */
+    Broker["IBKR"] = "ibkr";
 })(Broker || (exports.Broker = Broker = {}));
 /**
  * FloeClient provides a unified, broker-agnostic interface for subscribing to
@@ -88,6 +91,8 @@ class FloeClient {
         this.tradeStationClient = null;
         /** Schwab broker client instance */
         this.schwabClient = null;
+        /** Interactive Brokers broker client instance */
+        this.ibkrClient = null;
         /** Event listeners registry for the EventEmitter pattern */
         this.eventListeners = new Map();
         /** Callback for ticker data changes (legacy callback pattern) */
@@ -210,6 +215,29 @@ class FloeClient {
                 // Connect to the streaming API
                 await this.schwabClient.connect();
                 break;
+            case Broker.IBKR:
+                // For IBKR, authToken is the OAuth access token
+                this.ibkrClient = new IBKRClient_1.IBKRClient({
+                    baseUrl: 'https://api.ibkr.com/v1/api',
+                    accessToken: authToken,
+                    verbose: this.verbose,
+                });
+                // Wire up IBKRClient events to FloeClient events
+                this.ibkrClient.on('tickerUpdate', (ticker) => {
+                    this.emit('tickerUpdate', ticker);
+                });
+                this.ibkrClient.on('optionUpdate', (option) => {
+                    this.emit('optionUpdate', option);
+                });
+                this.ibkrClient.on('error', (error) => {
+                    this.emit('error', error);
+                });
+                this.ibkrClient.on('disconnected', () => {
+                    this.emit('disconnected', { broker, reason: 'IBKR WebSocket disconnected' });
+                });
+                // Connect to the streaming API
+                await this.ibkrClient.connect();
+                break;
             default:
                 throw new Error(`Unsupported broker: ${broker}`);
         }
@@ -243,6 +271,10 @@ class FloeClient {
             this.schwabClient.disconnect();
             this.schwabClient = null;
         }
+        if (this.ibkrClient) {
+            this.ibkrClient.disconnect();
+            this.ibkrClient = null;
+        }
         const broker = this.currentBroker;
         this.currentBroker = null;
         this.currentSubscribedTickers = [];
@@ -282,6 +314,9 @@ class FloeClient {
             case Broker.SCHWAB:
                 this.schwabClient?.subscribe(tickers);
                 break;
+            case Broker.IBKR:
+                this.ibkrClient?.subscribe(tickers);
+                break;
             default:
                 throw new Error(`Unsupported broker: ${this.currentBroker}`);
         }
@@ -325,6 +360,9 @@ class FloeClient {
             case Broker.SCHWAB:
                 this.schwabClient?.subscribe(symbols);
                 break;
+            case Broker.IBKR:
+                this.ibkrClient?.subscribe(symbols);
+                break;
             default:
                 throw new Error(`Unsupported broker: ${this.currentBroker}`);
         }
@@ -360,6 +398,9 @@ class FloeClient {
             case Broker.SCHWAB:
                 this.schwabClient?.unsubscribe(tickers);
                 break;
+            case Broker.IBKR:
+                this.ibkrClient?.unsubscribe(tickers);
+                break;
             default:
                 throw new Error(`Unsupported broker: ${this.currentBroker}`);
         }
@@ -395,6 +436,9 @@ class FloeClient {
             case Broker.SCHWAB:
                 this.schwabClient?.unsubscribe(symbols);
                 break;
+            case Broker.IBKR:
+                this.ibkrClient?.unsubscribe(symbols);
+                break;
             default:
                 throw new Error(`Unsupported broker: ${this.currentBroker}`);
         }
@@ -429,6 +473,9 @@ class FloeClient {
             case Broker.SCHWAB:
                 this.schwabClient?.unsubscribeFromAll();
                 break;
+            case Broker.IBKR:
+                this.ibkrClient?.unsubscribeFromAll();
+                break;
             default:
                 throw new Error(`Unsupported broker: ${this.currentBroker}`);
         }
@@ -483,6 +530,9 @@ class FloeClient {
             case Broker.SCHWAB:
                 await this.schwabClient?.fetchOpenInterest(symbolsToFetch);
                 break;
+            case Broker.IBKR:
+                await this.ibkrClient?.fetchOpenInterest(symbolsToFetch);
+                break;
             default:
                 throw new Error(`Unsupported broker: ${this.currentBroker}`);
         }
@@ -509,6 +559,8 @@ class FloeClient {
                 return this.tradeStationClient?.getOption(occSymbol);
             case Broker.SCHWAB:
                 return this.schwabClient?.getOption(occSymbol);
+            case Broker.IBKR:
+                return this.ibkrClient?.getOption(occSymbol);
             default:
                 return undefined;
         }
@@ -536,6 +588,8 @@ class FloeClient {
                 return this.tradeStationClient?.getAllOptions() ?? new Map();
             case Broker.SCHWAB:
                 return this.schwabClient?.getAllOptions() ?? new Map();
+            case Broker.IBKR:
+                return this.ibkrClient?.getAllOptions() ?? new Map();
             default:
                 return new Map();
         }

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

@@ -0,0 +1,324 @@
+import { BaseBrokerClient, BaseBrokerClientOptions, AggressorSide, IntradayTrade, FlowSummary, BrokerClientEventType, BrokerEventListener } from './BaseBrokerClient';
+export { AggressorSide, IntradayTrade, FlowSummary };
+export type IBKRClientEventType = BrokerClientEventType;
+export type IBKREventListener<T> = BrokerEventListener<T>;
+/**
+ * IBKR market data field tags for snapshot and streaming requests
+ */
+export declare const IBKR_FIELD_TAGS: {
+    readonly LAST_PRICE: "31";
+    readonly BID_PRICE: "84";
+    readonly BID_SIZE: "85";
+    readonly ASK_PRICE: "86";
+    readonly ASK_SIZE: "88";
+    readonly VOLUME: "7059";
+    readonly VOLUME_LONG: "7762";
+    readonly OPEN_INTEREST: "7089";
+    readonly IMPLIED_VOLATILITY: "7283";
+    readonly IMPLIED_VOLATILITY_PERCENT: "7284";
+    readonly DELTA: "7308";
+    readonly GAMMA: "7309";
+    readonly THETA: "7310";
+    readonly VEGA: "7311";
+    readonly LAST_SIZE: "32";
+    readonly LAST_TIMESTAMP: "7295";
+    readonly OPEN: "7296";
+    readonly HIGH: "7297";
+    readonly LOW: "7298";
+    readonly CLOSE: "7299";
+    readonly CHANGE: "82";
+    readonly CHANGE_PERCENT: "83";
+    readonly UNDERLYING_CONID: "6457";
+    readonly CONTRACT_DESC: "6509";
+    readonly MARK: "7219";
+};
+/**
+ * IBKR contract information returned from search endpoints
+ */
+export interface IBKRContract {
+    conid: number;
+    symbol: string;
+    secType: string;
+    exchange: string;
+    listingExchange: string | null;
+    right?: 'C' | 'P';
+    strike?: number;
+    currency: string;
+    maturityDate?: string;
+    multiplier?: string;
+    tradingClass?: string;
+    validExchanges?: string;
+    desc1?: string;
+    desc2?: string;
+}
+/**
+ * IBKR security definition search response
+ */
+export interface IBKRSecDefSearchResult {
+    conid: string;
+    companyHeader?: string;
+    companyName: string;
+    symbol: string;
+    description: string;
+    sections: Array<{
+        secType: string;
+        months?: string;
+        exchange?: string;
+    }>;
+}
+/**
+ * IBKR market data snapshot response
+ */
+export interface IBKRMarketDataSnapshot {
+    conid: number;
+    conidEx: string;
+    _updated?: number;
+    server_id?: string;
+    [key: string]: string | number | undefined;
+}
+/**
+ * IBKR option chain info from REST API
+ */
+interface IBKROptionInfo {
+    conid: number;
+    symbol: string;
+    secType: string;
+    exchange: string;
+    right: 'C' | 'P';
+    strike: number;
+    currency: string;
+    maturityDate: string;
+    multiplier: string;
+    tradingClass: string;
+    desc1: string;
+    desc2: string;
+}
+/**
+ * IBKR client configuration options
+ */
+export interface IBKRClientOptions extends BaseBrokerClientOptions {
+    /**
+     * Base URL for the IBKR API
+     * For Client Portal Gateway: 'https://localhost:5000/v1/api'
+     * For OAuth/Direct: 'https://api.ibkr.com/v1/api'
+     */
+    baseUrl: string;
+    /**
+     * OAuth access token (if using OAuth authentication)
+     */
+    accessToken?: string;
+    /**
+     * Account ID for trading operations
+     */
+    accountId?: string;
+    /**
+     * Whether to skip SSL certificate validation (for local gateway)
+     * @default false
+     */
+    rejectUnauthorized?: boolean;
+}
+/**
+ * IBKRClient handles real-time streaming connections to the Interactive Brokers Web API.
+ *
+ * @remarks
+ * This client manages WebSocket connections to IBKR's streaming API,
+ * normalizes incoming quote and trade data, and emits events for upstream
+ * consumption by the FloeClient.
+ *
+ * IBKR uses contract IDs (conids) to identify instruments. This client maintains
+ * a mapping between OCC option symbols and IBKR conids for seamless integration.
+ *
+ * @example
+ * ```typescript
+ * // Using Client Portal Gateway (local)
+ * const client = new IBKRClient({
+ *   baseUrl: 'https://localhost:5000/v1/api',
+ *   rejectUnauthorized: false
+ * });
+ *
+ * // Using OAuth (direct API)
+ * const client = new IBKRClient({
+ *   baseUrl: 'https://api.ibkr.com/v1/api',
+ *   accessToken: 'your-oauth-token'
+ * });
+ *
+ * client.on('tickerUpdate', (ticker) => {
+ *   console.log(`${ticker.symbol}: ${ticker.spot}`);
+ * });
+ *
+ * await client.connect();
+ * client.subscribe(['QQQ', 'AAPL240119C00500000']);
+ * ```
+ */
+export declare class IBKRClient extends BaseBrokerClient {
+    protected readonly brokerName = "IBKR";
+    /** Base URL for REST API calls */
+    private readonly baseUrl;
+    /** OAuth access token */
+    private accessToken?;
+    /** Account ID for trading */
+    private accountId?;
+    /** Whether to reject unauthorized SSL certificates */
+    private readonly rejectUnauthorized;
+    /** WebSocket connection */
+    private ws;
+    /** Connection state */
+    private connected;
+    /**
+     * Mapping from OCC symbol to IBKR conid
+     * This is populated as options are discovered/subscribed
+     */
+    private occToConid;
+    /**
+     * Mapping from IBKR conid to OCC symbol (reverse lookup)
+     */
+    private conidToOcc;
+    /**
+     * Mapping from ticker symbol to IBKR conid (for underlyings)
+     */
+    private symbolToConid;
+    /**
+     * Mapping from conid to ticker symbol (reverse lookup for underlyings)
+     */
+    private conidToSymbol;
+    /**
+     * Set of conids that have been "primed" for market data
+     * (IBKR requires a pre-flight request before streaming)
+     */
+    private primedConids;
+    /**
+     * Creates a new IBKRClient instance.
+     *
+     * @param options - Client configuration options
+     */
+    constructor(options: IBKRClientOptions);
+    /**
+     * Establishes a connection to IBKR.
+     *
+     * @returns Promise that resolves when connected
+     * @throws {Error} If connection fails
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnects from the IBKR API.
+     */
+    disconnect(): void;
+    /**
+     * Subscribes to real-time updates for the specified symbols.
+     *
+     * @param symbols - Array of ticker symbols and/or OCC option symbols
+     */
+    subscribe(symbols: string[]): Promise<void>;
+    /**
+     * Unsubscribes from real-time updates for the specified symbols.
+     *
+     * @param symbols - Array of symbols to unsubscribe from
+     */
+    unsubscribe(symbols: string[]): void;
+    /**
+     * Unsubscribes from all symbols.
+     */
+    unsubscribeFromAll(): void;
+    /**
+     * Returns whether the client is currently connected.
+     */
+    isConnected(): boolean;
+    /**
+     * Fetches open interest and other static data for subscribed options via REST API.
+     *
+     * @param occSymbols - Array of OCC option symbols to fetch data for
+     * @returns Promise that resolves when all data is fetched
+     */
+    fetchOpenInterest(occSymbols: string[]): Promise<void>;
+    /**
+     * Fetches options chain data for a given underlying.
+     *
+     * @param underlying - Underlying symbol (e.g., 'QQQ')
+     * @param expiration - Expiration date in YYYY-MM-DD format
+     * @returns Array of option contract info
+     */
+    fetchOptionsChain(underlying: string, expiration: string): Promise<IBKROptionInfo[]>;
+    /**
+     * Resolves an OCC option symbol to an IBKR conid.
+     *
+     * @param occSymbol - OCC option symbol
+     * @returns The IBKR conid, or null if not found
+     */
+    resolveOptionConid(occSymbol: string): Promise<number | null>;
+    /**
+     * Resolves an underlying symbol to an IBKR conid.
+     *
+     * @param symbol - Ticker symbol
+     * @returns The IBKR conid, or null if not found
+     */
+    resolveUnderlyingConid(symbol: string): Promise<number | null>;
+    /**
+     * Validates the brokerage session with IBKR.
+     */
+    private validateSession;
+    /**
+     * Connects to the IBKR WebSocket for streaming data.
+     */
+    private connectWebSocket;
+    /**
+     * Handles incoming WebSocket messages.
+     */
+    private handleWebSocketMessage;
+    /**
+     * Handles streaming market data messages.
+     */
+    private handleMarketDataMessage;
+    /**
+     * Updates option data from a WebSocket message.
+     */
+    private updateOptionFromWSMessage;
+    /**
+     * Updates ticker data from a WebSocket message.
+     */
+    private updateTickerFromWSMessage;
+    /**
+     * Processes an option snapshot response.
+     */
+    private processOptionSnapshot;
+    /**
+     * Sends a subscription message for a conid.
+     */
+    private subscribeToConid;
+    /**
+     * Sends an unsubscription message for a conid.
+     */
+    private unsubscribeFromConid;
+    /**
+     * Primes market data for the given symbols.
+     * IBKR requires a "pre-flight" snapshot request before streaming works.
+     */
+    private primeMarketData;
+    /**
+     * Primes market data for specific conids.
+     */
+    private primeMarketDataByConids;
+    /**
+     * Fetches market data snapshots for given conids.
+     */
+    private fetchMarketDataSnapshots;
+    /**
+     * Resolves conids for both ticker symbols and OCC option symbols.
+     */
+    private resolveConids;
+    /**
+     * Gets the conid for a symbol (either option or underlying).
+     */
+    private getConidForSymbol;
+    /**
+     * Converts an IBKR option info to OCC symbol format.
+     */
+    private ibkrOptionToOCC;
+    /**
+     * Makes an authenticated request to the IBKR API.
+     */
+    private makeRequest;
+    /**
+     * Attempts to reconnect with exponential backoff.
+     */
+    private attemptReconnect;
+}