@fullstackcraftllc/floe 0.0.1 → 0.0.3

package/dist/client/FloeClient.d.ts

@@ -0,0 +1,411 @@
+import { NormalizedOption, NormalizedTicker } from "../types";
+/**
+ * Supported broker integrations for the FloeClient.
+ * @enum {string}
+ */
+export declare enum Broker {
+    /** Tradier brokerage API */
+    TRADIER = "tradier"
+}
+/**
+ * Event types emitted by the FloeClient.
+ * @remarks
+ * Used with the {@link FloeClient.on} and {@link FloeClient.off} methods for event-driven updates.
+ */
+type FloeEventType = 'tickerUpdate' | 'optionUpdate' | 'error' | 'connected' | 'disconnected';
+/**
+ * Event payload map for type-safe event handling.
+ */
+interface FloeEventMap {
+    tickerUpdate: NormalizedTicker;
+    optionUpdate: NormalizedOption;
+    error: Error;
+    connected: {
+        broker: Broker;
+    };
+    disconnected: {
+        broker: Broker;
+        reason?: string;
+    };
+}
+/**
+ * Listener function type for FloeClient events.
+ * @template T - The event type from FloeEventType
+ */
+type FloeEventListener<T extends FloeEventType> = (data: FloeEventMap[T]) => void;
+/**
+ * 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']);
+ * ```
+ */
+export declare class FloeClient {
+    /** Currently connected broker, or null if not connected */
+    private currentBroker;
+    /** List of ticker symbols currently subscribed to */
+    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;
+    /** 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;
+    /**
+     * 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();
+    /**
+     * 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');
+     * ```
+     */
+    connect(broker: Broker, authKey: string): Promise<void>;
+    /**
+     * Disconnects from the current broker.
+     *
+     * @remarks
+     * Closes the WebSocket connection and clears all subscriptions.
+     *
+     * @example
+     * ```typescript
+     * client.disconnect();
+     * ```
+     */
+    disconnect(): void;
+    /**
+     * 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: Array<string>): void;
+    /**
+     * 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: Array<string>): void;
+    /**
+     * 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: Array<string>): void;
+    /**
+     * 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: 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.
+     *
+     * @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<T extends FloeEventType>(event: T, listener: FloeEventListener<T>): 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<T extends FloeEventType>(event: T, listener: FloeEventListener<T>): 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<T extends FloeEventType>(event: T, listener: FloeEventListener<T>): this;
+    /**
+     * 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.
+     */
+    private emit;
+    /**
+     * 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: (data: NormalizedTicker) => void): void;
+    /**
+     * 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: (data: NormalizedOption) => void): void;
+    /**
+     * 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(): ReadonlyArray<string>;
+    /**
+     * 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(): ReadonlyArray<string>;
+    /**
+     * 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(): boolean;
+}
+export {};