@fullstackcraftllc/floe 0.0.1 → 0.0.2

package/dist/client/FloeClient.js

@@ -0,0 +1,465 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FloeClient = exports.Broker = void 0;
+const TradierClient_1 = require("./brokers/TradierClient");
+/**
+ * Supported broker integrations for the FloeClient.
+ * @enum {string}
+ */
+var Broker;
+(function (Broker) {
+    /** Tradier brokerage API */
+    Broker["TRADIER"] = "tradier";
+    // Future brokers can be added here
+})(Broker || (exports.Broker = Broker = {}));
+/**
+ * FloeClient provides a unified, broker-agnostic interface for subscribing to
+ * real-time market data including stock tickers and options.
+ *
+ * @remarks
+ * The client normalizes data from various brokers into a consistent format,
+ * allowing consumers to switch brokers without changing their application code.
+ *
+ * @example
+ * ```typescript
+ * const client = new FloeClient();
+ *
+ * // Connect to a broker
+ * client.connect(Broker.TRADIER, 'your-api-key');
+ *
+ * // Subscribe to updates using the event emitter pattern
+ * client.on('tickerUpdate', (ticker) => {
+ *     console.log(`${ticker.symbol}: ${ticker.price}`);
+ * });
+ *
+ * // Or use the callback pattern
+ * client.onTickerDataChange((ticker) => {
+ *     console.log(`${ticker.symbol}: ${ticker.price}`);
+ * });
+ *
+ * // Subscribe to specific tickers
+ * client.subscribeToTickers(['AAPL', 'GOOGL', 'MSFT']);
+ * ```
+ */
+class FloeClient {
+    /**
+     * Creates a new FloeClient instance.
+     *
+     * @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
+     * const client = new FloeClient();
+     * ```
+     */
+    constructor() {
+        /** Currently connected broker, or null if not connected */
+        this.currentBroker = null;
+        /** List of ticker symbols currently subscribed to */
+        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;
+        /** 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;
+        // Initialize event listener maps for each event type
+        this.eventListeners.set('tickerUpdate', new Set());
+        this.eventListeners.set('optionUpdate', new Set());
+        this.eventListeners.set('error', new Set());
+        this.eventListeners.set('connected', new Set());
+        this.eventListeners.set('disconnected', new Set());
+    }
+    /**
+     * 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
+     *
+     * @throws {Error} Throws if the specified broker is not supported
+     *
+     * @remarks
+     * Must be called before subscribing to any market data. Only one broker
+     * connection is active at a time; calling connect again will switch brokers.
+     *
+     * @example
+     * ```typescript
+     * await client.connect(Broker.TRADIER, 'your-tradier-api-key');
+     * ```
+     */
+    async connect(broker, authKey) {
+        this.currentBroker = broker;
+        // Connection logic to the broker's API using the authKey
+        switch (broker.toLowerCase()) {
+            case Broker.TRADIER:
+                this.tradierClient = new TradierClient_1.TradierClient(authKey);
+                // Wire up TradierClient events to FloeClient events
+                this.tradierClient.on('tickerUpdate', (ticker) => {
+                    this.emit('tickerUpdate', ticker);
+                });
+                this.tradierClient.on('optionUpdate', (option) => {
+                    this.emit('optionUpdate', option);
+                });
+                this.tradierClient.on('error', (error) => {
+                    this.emit('error', error);
+                });
+                this.tradierClient.on('disconnected', () => {
+                    this.emit('disconnected', { broker, reason: 'WebSocket disconnected' });
+                });
+                // Connect to the streaming API
+                await this.tradierClient.connect();
+                break;
+            default:
+                throw new Error(`Unsupported broker: ${broker}`);
+        }
+        this.emit('connected', { broker });
+    }
+    /**
+     * Disconnects from the current broker.
+     *
+     * @remarks
+     * Closes the WebSocket connection and clears all subscriptions.
+     *
+     * @example
+     * ```typescript
+     * client.disconnect();
+     * ```
+     */
+    disconnect() {
+        if (this.tradierClient) {
+            this.tradierClient.disconnect();
+            this.tradierClient = null;
+        }
+        const broker = this.currentBroker;
+        this.currentBroker = null;
+        this.currentSubscribedTickers = [];
+        this.currentSubscribedOptions = [];
+        if (broker) {
+            this.emit('disconnected', { broker, reason: 'Client disconnect' });
+        }
+    }
+    /**
+     * Subscribes to real-time updates for the specified stock ticker symbols.
+     *
+     * @param tickers - Array of ticker symbols to subscribe to (e.g., ['AAPL', 'GOOGL'])
+     *
+     * @throws {Error} Throws if no broker connection has been established
+     *
+     * @remarks
+     * Ticker updates will be delivered via the 'tickerUpdate' event or through
+     * the callback registered with {@link onTickerDataChange}.
+     *
+     * @example
+     * ```typescript
+     * client.subscribeToTickers(['AAPL', 'GOOGL', 'MSFT']);
+     * ```
+     */
+    subscribeToTickers(tickers) {
+        this.currentSubscribedTickers.push(...tickers);
+        switch (this.currentBroker) {
+            case Broker.TRADIER:
+                this.tradierClient?.subscribe(tickers);
+                break;
+            default:
+                throw new Error(`Unsupported broker: ${this.currentBroker}`);
+        }
+    }
+    /**
+     * Subscribes to real-time updates for the specified option contracts.
+     *
+     * @param symbols - Array of option symbols in OCC format
+     *                  (e.g., ['AAPL230120C00150000'] for AAPL $150 Call expiring Jan 20, 2023)
+     *
+     * @throws {Error} Throws if no broker connection has been established
+     *
+     * @remarks
+     * Option symbols must be in the standard OCC (Options Clearing Corporation) format:
+     * - Root symbol (up to 6 characters, left-padded)
+     * - Expiration date (YYMMDD)
+     * - Option type (C for call, P for put)
+     * - Strike price (8 digits, price × 1000, left-padded with zeros)
+     *
+     * Option updates will be delivered via the 'optionUpdate' event or through
+     * the callback registered with {@link onOptionDataChange}.
+     *
+     * @example
+     * ```typescript
+     * // Subscribe to AAPL $150 Call expiring Jan 20, 2023
+     * client.subscribeToOptions(['AAPL230120C00150000']);
+     * ```
+     */
+    subscribeToOptions(symbols) {
+        this.currentSubscribedOptions.push(...symbols);
+        switch (this.currentBroker) {
+            case Broker.TRADIER:
+                this.tradierClient?.subscribe(symbols);
+                break;
+            default:
+                throw new Error(`Unsupported broker: ${this.currentBroker}`);
+        }
+    }
+    /**
+     * Unsubscribes from real-time updates for the specified stock ticker symbols.
+     *
+     * @param tickers - Array of ticker symbols to unsubscribe from
+     *
+     * @throws {Error} Throws if no broker connection has been established
+     *
+     * @remarks
+     * After unsubscribing, no further updates will be received for these tickers.
+     * Has no effect if the specified tickers were not previously subscribed.
+     *
+     * @example
+     * ```typescript
+     * client.unsubscribeFromTickers(['AAPL', 'GOOGL']);
+     * ```
+     */
+    unsubscribeFromTickers(tickers) {
+        this.currentSubscribedTickers = this.currentSubscribedTickers.filter(ticker => !tickers.includes(ticker));
+        switch (this.currentBroker) {
+            case Broker.TRADIER:
+                this.tradierClient?.unsubscribe(tickers);
+                break;
+            default:
+                throw new Error(`Unsupported broker: ${this.currentBroker}`);
+        }
+    }
+    /**
+     * Unsubscribes from real-time updates for the specified option contracts.
+     *
+     * @param symbols - Array of option symbols in OCC format to unsubscribe from
+     *
+     * @throws {Error} Throws if no broker connection has been established
+     *
+     * @remarks
+     * After unsubscribing, no further updates will be received for these options.
+     * Has no effect if the specified options were not previously subscribed.
+     *
+     * @example
+     * ```typescript
+     * client.unsubscribeFromOptions(['AAPL230120C00150000']);
+     * ```
+     */
+    unsubscribeFromOptions(symbols) {
+        this.currentSubscribedOptions = this.currentSubscribedOptions.filter(symbol => !symbols.includes(symbol));
+        switch (this.currentBroker) {
+            case Broker.TRADIER:
+                this.tradierClient?.unsubscribe(symbols);
+                break;
+            default:
+                throw new Error(`Unsupported broker: ${this.currentBroker}`);
+        }
+    }
+    // ==================== Event Emitter Pattern ====================
+    /**
+     * Registers an event listener for the specified event type.
+     *
+     * @template T - The event type
+     * @param event - The event type to listen for
+     * @param listener - The callback function to invoke when the event occurs
+     * @returns The FloeClient instance for method chaining
+     *
+     * @remarks
+     * Multiple listeners can be registered for the same event type.
+     * Use {@link off} to remove a listener when it's no longer needed.
+     *
+     * @example
+     * ```typescript
+     * client
+     *     .on('tickerUpdate', (ticker) => console.log(ticker))
+     *     .on('error', (error) => console.error(error));
+     * ```
+     */
+    on(event, listener) {
+        const listeners = this.eventListeners.get(event);
+        if (listeners) {
+            listeners.add(listener);
+        }
+        return this;
+    }
+    /**
+     * Removes an event listener for the specified event type.
+     *
+     * @template T - The event type
+     * @param event - The event type to stop listening for
+     * @param listener - The callback function to remove
+     * @returns The FloeClient instance for method chaining
+     *
+     * @remarks
+     * The listener must be the exact same function reference that was passed to {@link on}.
+     *
+     * @example
+     * ```typescript
+     * const handler = (ticker) => console.log(ticker);
+     * client.on('tickerUpdate', handler);
+     * // Later...
+     * client.off('tickerUpdate', handler);
+     * ```
+     */
+    off(event, listener) {
+        const listeners = this.eventListeners.get(event);
+        if (listeners) {
+            listeners.delete(listener);
+        }
+        return this;
+    }
+    /**
+     * Registers a one-time event listener that automatically removes itself after firing.
+     *
+     * @template T - The event type
+     * @param event - The event type to listen for
+     * @param listener - The callback function to invoke once when the event occurs
+     * @returns The FloeClient instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * client.once('connected', ({ broker }) => {
+     *     console.log(`Connected to ${broker}`);
+     * });
+     * ```
+     */
+    once(event, listener) {
+        const onceWrapper = ((data) => {
+            this.off(event, onceWrapper);
+            listener(data);
+        });
+        return this.on(event, onceWrapper);
+    }
+    /**
+     * Emits an event to all registered listeners.
+     *
+     * @template T - The event type
+     * @param event - The event type to emit
+     * @param data - The event payload
+     *
+     * @internal
+     * @remarks
+     * This method is used internally to dispatch events. It also triggers
+     * legacy callback handlers for backwards compatibility.
+     */
+    emit(event, data) {
+        const listeners = this.eventListeners.get(event);
+        if (listeners) {
+            listeners.forEach(listener => {
+                try {
+                    listener(data);
+                }
+                catch (error) {
+                    // Emit error event if a listener throws (but avoid infinite loops)
+                    if (event !== 'error') {
+                        this.emit('error', error instanceof Error ? error : new Error(String(error)));
+                    }
+                }
+            });
+        }
+        // Also trigger legacy callbacks for backwards compatibility
+        if (event === 'tickerUpdate' && this.tickerDataCallback) {
+            this.tickerDataCallback(data);
+        }
+        if (event === 'optionUpdate' && this.optionDataCallback) {
+            this.optionDataCallback(data);
+        }
+    }
+    // ==================== Callback Pattern (Legacy) ====================
+    /**
+     * Registers a callback to be invoked whenever ticker data is updated.
+     *
+     * @param callback - Function to call with the updated ticker data
+     *
+     * @deprecated Prefer using {@link on}('tickerUpdate', callback) for new code.
+     *             The event emitter pattern supports multiple listeners and provides
+     *             better lifecycle management.
+     *
+     * @remarks
+     * Only one callback can be registered at a time. Calling this method again
+     * will replace the previous callback. For multiple listeners, use {@link on}.
+     *
+     * @example
+     * ```typescript
+     * client.onTickerDataChange((ticker) => {
+     *     console.log(`${ticker.symbol} updated: ${ticker.price}`);
+     * });
+     * ```
+     */
+    onTickerDataChange(callback) {
+        this.tickerDataCallback = callback;
+    }
+    /**
+     * Registers a callback to be invoked whenever option data is updated.
+     *
+     * @param callback - Function to call with the updated option data
+     *
+     * @deprecated Prefer using {@link on}('optionUpdate', callback) for new code.
+     *             The event emitter pattern supports multiple listeners and provides
+     *             better lifecycle management.
+     *
+     * @remarks
+     * Only one callback can be registered at a time. Calling this method again
+     * will replace the previous callback. For multiple listeners, use {@link on}.
+     *
+     * @example
+     * ```typescript
+     * client.onOptionDataChange((option) => {
+     *     console.log(`${option.symbol} bid: ${option.bid}, ask: ${option.ask}`);
+     * });
+     * ```
+     */
+    onOptionDataChange(callback) {
+        this.optionDataCallback = callback;
+    }
+    // ==================== Utility Methods ====================
+    /**
+     * Returns the list of currently subscribed ticker symbols.
+     *
+     * @returns Array of ticker symbols currently subscribed to
+     *
+     * @example
+     * ```typescript
+     * const tickers = client.getSubscribedTickers();
+     * console.log(`Subscribed to: ${tickers.join(', ')}`);
+     * ```
+     */
+    getSubscribedTickers() {
+        return [...this.currentSubscribedTickers];
+    }
+    /**
+     * Returns the list of currently subscribed option symbols.
+     *
+     * @returns Array of option symbols (OCC format) currently subscribed to
+     *
+     * @example
+     * ```typescript
+     * const options = client.getSubscribedOptions();
+     * console.log(`Subscribed to ${options.length} options`);
+     * ```
+     */
+    getSubscribedOptions() {
+        return [...this.currentSubscribedOptions];
+    }
+    /**
+     * Returns whether the client is currently connected to a broker.
+     *
+     * @returns True if connected to a broker, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (client.isConnected()) {
+     *     client.subscribeToTickers(['AAPL']);
+     * }
+     * ```
+     */
+    isConnected() {
+        return this.currentBroker !== null;
+    }
+}
+exports.FloeClient = FloeClient;

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

@@ -0,0 +1,161 @@
+/**
+ * Event types emitted by TradierClient
+ */
+type TradierClientEventType = 'tickerUpdate' | 'optionUpdate' | 'connected' | 'disconnected' | 'error';
+/**
+ * Event listener callback type
+ */
+type TradierEventListener<T> = (data: T) => void;
+/**
+ * TradierClient handles real-time streaming connections to the Tradier API.
+ *
+ * @remarks
+ * This client manages WebSocket connections to Tradier's streaming API,
+ * normalizes incoming quote and trade data, and emits events for upstream
+ * consumption by the FloeClient.
+ *
+ * @example
+ * ```typescript
+ * const client = new TradierClient('your-api-key');
+ *
+ * client.on('tickerUpdate', (ticker) => {
+ *   console.log(`${ticker.symbol}: ${ticker.spot}`);
+ * });
+ *
+ * await client.connect();
+ * client.subscribe(['QQQ', 'AAPL  240119C00500000']);
+ * ```
+ */
+export declare class TradierClient {
+    /** Tradier API authentication token */
+    private authKey;
+    /** Current streaming session */
+    private streamSession;
+    /** WebSocket connection */
+    private ws;
+    /** Connection state */
+    private connected;
+    /** Currently subscribed symbols (tickers and options) */
+    private subscribedSymbols;
+    /** Cached ticker data (for merging quote and trade events) */
+    private tickerCache;
+    /** Cached option data (for merging quote and trade events) */
+    private optionCache;
+    /** Event listeners */
+    private eventListeners;
+    /** Reconnection attempt counter */
+    private reconnectAttempts;
+    /** Maximum reconnection attempts */
+    private readonly maxReconnectAttempts;
+    /** Reconnection delay in ms (doubles with each attempt) */
+    private readonly baseReconnectDelay;
+    /** Tradier API base URL */
+    private readonly apiBaseUrl;
+    /** Tradier WebSocket URL */
+    private readonly wsUrl;
+    /**
+     * Creates a new TradierClient instance.
+     *
+     * @param authKey - Tradier API access token
+     */
+    constructor(authKey: string);
+    /**
+     * Establishes a streaming connection to Tradier.
+     *
+     * @returns Promise that resolves when connected
+     * @throws {Error} If session creation or WebSocket connection fails
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnects from the Tradier streaming 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[]): void;
+    /**
+     * Unsubscribes from real-time updates for the specified symbols.
+     *
+     * @param symbols - Array of symbols to unsubscribe from
+     *
+     * @remarks
+     * Note: Tradier's streaming API doesn't support unsubscription for individual
+     * symbols. This method removes them from local tracking. To fully unsubscribe,
+     * you would need to disconnect and reconnect with the new symbol list.
+     */
+    unsubscribe(symbols: string[]): void;
+    /**
+     * Returns whether the client is currently connected.
+     */
+    isConnected(): boolean;
+    /**
+     * Registers an event listener.
+     *
+     * @param event - Event type to listen for
+     * @param listener - Callback function
+     */
+    on<T>(event: TradierClientEventType, listener: TradierEventListener<T>): this;
+    /**
+     * Removes an event listener.
+     *
+     * @param event - Event type
+     * @param listener - Callback function to remove
+     */
+    off<T>(event: TradierClientEventType, listener: TradierEventListener<T>): this;
+    /**
+     * Creates a streaming session with Tradier API.
+     */
+    private createStreamSession;
+    /**
+     * Connects to the Tradier WebSocket.
+     */
+    private connectWebSocket;
+    /**
+     * Attempts to reconnect with exponential backoff.
+     */
+    private attemptReconnect;
+    /**
+     * Handles incoming WebSocket messages.
+     */
+    private handleMessage;
+    /**
+     * Handles quote events (bid/ask updates).
+     */
+    private handleQuoteEvent;
+    /**
+     * Handles trade events (last price/volume updates).
+     */
+    private handleTradeEvent;
+    /**
+     * Updates ticker data from a quote event.
+     */
+    private updateTickerFromQuote;
+    /**
+     * Updates ticker data from a trade event.
+     */
+    private updateTickerFromTrade;
+    /**
+     * Updates option data from a quote event.
+     */
+    private updateOptionFromQuote;
+    /**
+     * Updates option data from a trade event.
+     */
+    private updateOptionFromTrade;
+    /**
+     * Checks if a symbol is an OCC option symbol.
+     */
+    private isOptionSymbol;
+    /**
+     * Emits an event to all registered listeners.
+     */
+    private emit;
+    /**
+     * Simple sleep utility.
+     */
+    private sleep;
+}
+export {};