@fullstackcraftllc/floe 0.0.3 → 0.0.5

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

@@ -1,2 +1,450 @@
+import { NormalizedOption } from '../../types';
+/**
+ * Schwab option chain response
+ */
+interface SchwabOptionChainResponse {
+    symbol: string;
+    status: string;
+    underlying: {
+        symbol: string;
+        description: string;
+        change: number;
+        percentChange: number;
+        close: number;
+        quoteTime: number;
+        tradeTime: number;
+        bid: number;
+        ask: number;
+        last: number;
+        mark: number;
+        markChange: number;
+        markPercentChange: number;
+        bidSize: number;
+        askSize: number;
+        highPrice: number;
+        lowPrice: number;
+        openPrice: number;
+        totalVolume: number;
+        exchangeName: string;
+        fiftyTwoWeekHigh: number;
+        fiftyTwoWeekLow: number;
+        delayed: boolean;
+    };
+    strategy: string;
+    interval: number;
+    isDelayed: boolean;
+    isIndex: boolean;
+    interestRate: number;
+    underlyingPrice: number;
+    volatility: number;
+    daysToExpiration: number;
+    numberOfContracts: number;
+    assetMainType: string;
+    assetSubType: string;
+    isChainTruncated: boolean;
+    callExpDateMap: Record<string, Record<string, SchwabOptionContract[]>>;
+    putExpDateMap: Record<string, Record<string, SchwabOptionContract[]>>;
+}
+/**
+ * Schwab option contract from chain
+ */
+interface SchwabOptionContract {
+    putCall: 'CALL' | 'PUT';
+    symbol: string;
+    description: string;
+    exchangeName: string;
+    bid: number;
+    ask: number;
+    last: number;
+    mark: number;
+    bidSize: number;
+    askSize: number;
+    bidAskSize: string;
+    lastSize: number;
+    highPrice: number;
+    lowPrice: number;
+    openPrice: number;
+    closePrice: number;
+    totalVolume: number;
+    tradeDate: number | null;
+    tradeTimeInLong: number;
+    quoteTimeInLong: number;
+    netChange: number;
+    volatility: number;
+    delta: number;
+    gamma: number;
+    theta: number;
+    vega: number;
+    rho: number;
+    openInterest: number;
+    timeValue: number;
+    theoreticalOptionValue: number;
+    theoreticalVolatility: number;
+    optionDeliverablesList: unknown;
+    strikePrice: number;
+    expirationDate: string;
+    daysToExpiration: number;
+    expirationType: string;
+    lastTradingDay: number;
+    multiplier: number;
+    settlementType: string;
+    deliverableNote: string;
+    percentChange: number;
+    markChange: number;
+    markPercentChange: number;
+    intrinsicValue: number;
+    extrinsicValue: number;
+    optionRoot: string;
+    exerciseType: string;
+    high52Week: number;
+    low52Week: number;
+    nonStandard: boolean;
+    pennyPilot: boolean;
+    inTheMoney: boolean;
+    mini: boolean;
+}
+/**
+ * Aggressor side of a trade
+ */
+export type AggressorSide = 'buy' | 'sell' | 'unknown';
+/**
+ * Intraday trade information with aggressor classification
+ */
+export interface IntradayTrade {
+    /** OCC option symbol */
+    occSymbol: string;
+    /** Trade price */
+    price: number;
+    /** Trade size (number of contracts) */
+    size: number;
+    /** Bid at time of trade */
+    bid: number;
+    /** Ask at time of trade */
+    ask: number;
+    /** Aggressor side determined from price vs NBBO */
+    aggressorSide: AggressorSide;
+    /** Timestamp of the trade */
+    timestamp: number;
+    /** Estimated OI change */
+    estimatedOIChange: number;
+}
+/**
+ * Event types emitted by SchwabClient
+ */
+type SchwabClientEventType = 'tickerUpdate' | 'optionUpdate' | 'optionTrade' | 'connected' | 'disconnected' | 'error';
+/**
+ * Event listener callback type
+ */
+type SchwabEventListener<T> = (data: T) => void;
+/**
+ * SchwabClient handles real-time streaming connections to the Charles Schwab API
+ * via WebSockets.
+ *
+ * @remarks
+ * This client manages WebSocket connections to Schwab's streaming API,
+ * normalizes incoming quote and book data, and emits events for upstream
+ * consumption by the FloeClient.
+ *
+ * Authentication flow:
+ * 1. Use OAuth access token to call get_user_preferences endpoint
+ * 2. Extract streaming credentials (customerId, correlId, channel, functionId, socketUrl)
+ * 3. Connect to WebSocket and send ADMIN/LOGIN request with access token
+ * 4. Subscribe to LEVELONE_OPTIONS for quotes and OPTIONS_BOOK for order book
+ *
+ * @example
+ * ```typescript
+ * const client = new SchwabClient({
+ *   accessToken: 'your-oauth-access-token'
+ * });
+ *
+ * client.on('tickerUpdate', (ticker) => {
+ *   console.log(`${ticker.symbol}: ${ticker.spot}`);
+ * });
+ *
+ * await client.connect();
+ * client.subscribe(['SPY', 'SPY   240517C00500000']); // Equity and option
+ * ```
+ */
 export declare class SchwabClient {
+    /** Schwab OAuth access token */
+    private accessToken;
+    /** WebSocket connection */
+    private ws;
+    /** Connection state */
+    private connected;
+    /** Logged in state */
+    private loggedIn;
+    /** Streaming credentials */
+    private streamCustomerId;
+    private streamCorrelId;
+    private streamChannel;
+    private streamFunctionId;
+    private streamSocketUrl;
+    /** Request ID counter */
+    private requestId;
+    /** Currently subscribed symbols */
+    private subscribedSymbols;
+    /** Map from Schwab symbol to OCC symbol */
+    private schwabToOccMap;
+    /** Map from OCC symbol to Schwab symbol */
+    private occToSchwabMap;
+    /** Cached ticker data */
+    private tickerCache;
+    /** Cached option data */
+    private optionCache;
+    /** Base open interest from REST API */
+    private baseOpenInterest;
+    /** Cumulative estimated OI change from intraday trades */
+    private cumulativeOIChange;
+    /** History of intraday trades */
+    private intradayTrades;
+    /** Event listeners */
+    private eventListeners;
+    /** Reconnection attempt counter */
+    private reconnectAttempts;
+    /** Maximum reconnection attempts */
+    private readonly maxReconnectAttempts;
+    /** Reconnection delay in ms */
+    private readonly baseReconnectDelay;
+    /** Keepalive interval handle */
+    private keepaliveInterval;
+    /** Schwab API base URL */
+    private readonly apiBaseUrl;
+    /** Whether to log verbose debug information */
+    private readonly verbose;
+    /**
+     * Creates a new SchwabClient instance.
+     *
+     * @param options - Client configuration options
+     * @param options.accessToken - Schwab OAuth access token (required)
+     * @param options.verbose - Whether to log verbose debug information (default: false)
+     */
+    constructor(options: {
+        accessToken: string;
+        verbose?: boolean;
+    });
+    /**
+     * Establishes a streaming connection to Schwab.
+     *
+     * @returns Promise that resolves when connected and logged in
+     * @throws {Error} If credentials retrieval or WebSocket connection fails
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnects from the Schwab streaming API.
+     */
+    disconnect(): void;
+    /**
+     * Subscribes to real-time updates for the specified symbols.
+     *
+     * @param symbols - Array of ticker symbols and/or OCC option symbols
+     *
+     * @remarks
+     * For options, you can pass OCC format symbols (e.g., 'SPY240119C00500000')
+     * or Schwab format with spaces (e.g., 'SPY   240119C00500000').
+     * The client will handle conversion automatically.
+     */
+    subscribe(symbols: string[]): void;
+    /**
+     * Unsubscribes from real-time updates for the specified symbols.
+     *
+     * @param symbols - Array of symbols to unsubscribe from
+     */
+    unsubscribe(symbols: string[]): void;
+    /**
+     * Returns whether the client is currently connected.
+     */
+    isConnected(): boolean;
+    /**
+     * Fetches option chain from Schwab REST API.
+     * This provides the base open interest data.
+     *
+     * @param symbol - Underlying symbol (e.g., 'SPY')
+     * @param options - Optional parameters for filtering the chain
+     * @returns Promise resolving to the option chain response
+     */
+    fetchOptionChain(symbol: string, options?: {
+        contractType?: 'CALL' | 'PUT' | 'ALL';
+        strikeCount?: number;
+        includeUnderlyingQuote?: boolean;
+        fromDate?: string;
+        toDate?: string;
+    }): Promise<SchwabOptionChainResponse | null>;
+    /**
+     * Fetches open interest and other static data for subscribed options.
+     *
+     * @param occSymbols - Array of OCC option symbols to fetch data for
+     */
+    fetchOpenInterest(occSymbols: string[]): Promise<void>;
+    /**
+     * Returns cached option data for a symbol.
+     */
+    getOption(occSymbol: string): NormalizedOption | undefined;
+    /**
+     * Returns all cached options.
+     */
+    getAllOptions(): Map<string, NormalizedOption>;
+    /**
+     * Registers an event listener.
+     */
+    on<T>(event: SchwabClientEventType, listener: SchwabEventListener<T>): this;
+    /**
+     * Removes an event listener.
+     */
+    off<T>(event: SchwabClientEventType, listener: SchwabEventListener<T>): this;
+    /**
+     * Returns intraday trades for an option.
+     */
+    getIntradayTrades(occSymbol: string): IntradayTrade[];
+    /**
+     * Returns flow summary for an option.
+     */
+    getFlowSummary(occSymbol: string): {
+        buyVolume: number;
+        sellVolume: number;
+        unknownVolume: number;
+        netOIChange: number;
+        tradeCount: number;
+    };
+    /**
+     * Resets intraday tracking data.
+     */
+    resetIntradayData(occSymbols?: string[]): void;
+    /**
+     * Gets user preferences containing streaming info from Schwab.
+     */
+    private getUserPreferences;
+    /**
+     * Returns authorization headers for API calls.
+     */
+    private getAuthHeaders;
+    /**
+     * Connects to Schwab WebSocket.
+     */
+    private connectWebSocket;
+    /**
+     * Sends login request to Schwab streaming.
+     */
+    private sendLogin;
+    /**
+     * Sends logout request to Schwab streaming.
+     */
+    private sendLogout;
+    /**
+     * Subscribes to LEVELONE_EQUITIES service.
+     */
+    private subscribeLevelOneEquity;
+    /**
+     * Unsubscribes from LEVELONE_EQUITIES service.
+     */
+    private unsubscribeLevelOneEquity;
+    /**
+     * Subscribes to LEVELONE_OPTIONS service for level 1 option quotes.
+     */
+    private subscribeLevelOneOptions;
+    /**
+     * Unsubscribes from LEVELONE_OPTIONS service.
+     */
+    private unsubscribeLevelOneOptions;
+    /**
+     * Subscribes to OPTIONS_BOOK service for level 2 order book.
+     * This provides "live" open interest intraday.
+     */
+    private subscribeOptionsBook;
+    /**
+     * Unsubscribes from OPTIONS_BOOK service.
+     */
+    private unsubscribeOptionsBook;
+    /**
+     * Makes a streaming request object.
+     */
+    private makeRequest;
+    /**
+     * Handles incoming WebSocket messages.
+     */
+    private handleMessage;
+    /**
+     * Handles a response message (command acknowledgment).
+     */
+    private handleResponse;
+    /**
+     * Handles streaming data messages.
+     */
+    private handleDataMessage;
+    /**
+     * Handles LEVELONE_EQUITIES data.
+     */
+    private handleLevelOneEquity;
+    /**
+     * Handles LEVELONE_OPTIONS data.
+     */
+    private handleLevelOneOption;
+    /**
+     * Handles OPTIONS_BOOK data (level 2 order book).
+     * This provides depth of market which can indicate intraday activity.
+     */
+    private handleOptionsBook;
+    /**
+     * Records a trade and updates OI tracking.
+     */
+    private recordTrade;
+    /**
+     * Processes a contract from the option chain response.
+     */
+    private processChainContract;
+    /**
+     * Starts keepalive interval.
+     */
+    private startKeepalive;
+    /**
+     * Determines aggressor side from trade price vs NBBO.
+     */
+    private determineAggressorSide;
+    /**
+     * Calculates estimated OI change from trade.
+     */
+    private calculateOIChangeFromTrade;
+    /**
+     * Calculates live open interest.
+     */
+    private calculateLiveOpenInterest;
+    /**
+     * Converts Schwab option symbol to OCC format.
+     * Schwab format: "AAPL  240517C00170000" (6-char padded underlying)
+     */
+    private schwabToOcc;
+    /**
+     * Normalizes an OCC symbol to consistent format.
+     * Removes extra spaces, ensures proper formatting.
+     */
+    private normalizeOccSymbol;
+    /**
+     * Converts OCC symbol to Schwab format (space-padded).
+     */
+    private toSchwabOptionSymbol;
+    /**
+     * Checks if symbol is an option symbol.
+     */
+    private isOptionSymbol;
+    /**
+     * Attempts to reconnect with exponential backoff.
+     */
+    private attemptReconnect;
+    /**
+     * Sends a message to the WebSocket.
+     */
+    private sendMessage;
+    /**
+     * Emits an event to all listeners.
+     */
+    private emit;
+    /**
+     * Converts value to number, handling NaN and null.
+     */
+    private toNumber;
+    /**
+     * Sleep utility.
+     */
+    private sleep;
 }
+export {};