@wioex/stream-sdk/dist/types.d.ts

WebSocket streaming SDK for real-time WioEX market data

/**
 * WioEX Stream SDK - Type Definitions
 */
/**
 * Token fetch retry configuration
 */
export interface TokenFetchRetryConfig {
    /** Maximum number of retry attempts (default: 3) */
    maxAttempts?: number;
    /** Initial delay between retries in milliseconds (default: 1000) */
    delay?: number;
    /** Backoff strategy (default: 'exponential') */
    backoff?: 'linear' | 'exponential';
}
/**
 * Configuration options for WioexStreamClient
 */
export interface WioexStreamConfig {
    /** WioEX API key for authentication (Node.js only - backend) */
    apiKey?: string;
    /** Temporary token for secure authentication (recommended for browser) */
    token?: string;
    /** Token expiration time (Unix timestamp in seconds) */
    tokenExpiresAt?: number;
    /** Backend endpoint URL to fetch token (browser only) */
    tokenEndpoint?: string;
    /** Custom headers for token endpoint request */
    tokenFetchHeaders?: Record<string, string>;
    /** Token fetch retry configuration */
    tokenFetchRetry?: TokenFetchRetryConfig;
    /** Callback to get new token when current token is expiring */
    onTokenExpiring?: () => Promise<{
        token: string;
        expiresAt: number;
    }>;
    /** Automatically refresh token before expiry (default: true if onTokenExpiring provided) */
    autoRefreshToken?: boolean;
    /** Refresh token N milliseconds before expiry (default: 3600000 = 1 hour) */
    refreshBeforeExpiry?: number;
    /** Enable lazy connection on first subscribe (default: true) */
    lazyConnect?: boolean;
    /** Enable debug logging to console (default: false) */
    debug?: boolean;
    /** Maximum number of symbols to track (1-8) */
    maxSymbols?: number;
    /** Auto-reconnect on connection loss */
    autoReconnect?: boolean;
    /** Reconnection delay in milliseconds */
    reconnectDelay?: number;
    /** Maximum reconnection attempts (0 = infinite) */
    maxReconnectAttempts?: number;
    /** WebSocket URL (default: wss://stream.wioex.com/rs/i/{max}/websocket) */
    streamUrl?: string;
    /** Error reporting level: 'none' | 'minimal' | 'standard' | 'detailed' */
    errorReportingLevel?: ErrorReportingLevel;
    /** Error reporting endpoint URL */
    errorReportingUrl?: string;
    /** Include WebSocket message data in error reports */
    includeMessageData?: boolean;
    /** Include connection details in error reports */
    includeConnectionData?: boolean;
    /** Performance optimization options */
    performance?: {
        /** Throttle ticker events (ms, 0 = disabled, default: 16 for 60 FPS) */
        tickerThrottle?: number;
        /** Batch ticker updates instead of throttling */
        batchTickers?: boolean;
        /** Maximum ticker batch size */
        tickerBatchSize?: number;
        /** Error reporting batch size (default: 10) */
        errorBatchSize?: number;
        /** Error reporting flush interval in ms (default: 5000) */
        errorBatchInterval?: number;
        /** Enable error deduplication (default: true) */
        errorDeduplication?: boolean;
        /** Enable stats tracking (default: true, disable in production for 5-10% performance gain) */
        enableStats?: boolean;
        /** Use binary protocol (MessagePack) instead of JSON (default: false, opt-in for 50-60% speed boost) */
        useBinaryProtocol?: boolean;
    };
}
/**
 * Error reporting levels
 */
export type ErrorReportingLevel = 'none' | 'minimal' | 'standard' | 'detailed';
/**
 * Error context data
 */
export interface ErrorContext {
    /** Connection state when error occurred */
    connectionState?: ConnectionState;
    /** Last message received */
    lastMessage?: string;
    /** Message that triggered error */
    triggerMessage?: unknown;
    /** Subscribed stocks at time of error */
    subscribedStocks?: string[];
    /** Additional context information */
    [key: string]: unknown;
}
/**
 * Error report payload
 */
export interface ErrorReportPayload {
    /** SDK version */
    sdk_version: string;
    /** SDK type */
    sdk_type: 'stream';
    /** Category (always 'stream' for this SDK) */
    category: 'stream';
    /** Runtime environment */
    runtime: string;
    /** API key identification (hashed) */
    api_key_id: string;
    /** Error reporting level used */
    reporting_level: ErrorReportingLevel;
    /** Error information */
    error: {
        /** Error type/class */
        type: string;
        /** Error message */
        message: string;
        /** Error stack trace (if available) */
        stack?: string;
        /** Error code (if available) */
        code?: string;
    };
    /** Error context */
    context?: ErrorContext;
    /** Timestamp when error occurred */
    timestamp: number;
}
/**
 * Connection states
 */
export declare enum ConnectionState {
    DISCONNECTED = "disconnected",
    CONNECTING = "connecting",
    CONNECTED = "connected",
    REGISTERED = "registered",
    RECONNECTING = "reconnecting",
    FAILED = "failed"
}
/**
 * WebSocket message actions
 */
export type MessageAction = 'register' | 'subscribe' | 'unsubscribe' | 'ping' | 'pong';
/**
 * Register message
 */
export interface RegisterMessage {
    action: 'register';
    token: string;
}
/**
 * Subscribe message
 */
export interface SubscribeMessage {
    action: 'subscribe';
    stocks: string[];
}
/**
 * Unsubscribe message
 */
export interface UnsubscribeMessage {
    action: 'unsubscribe';
    stocks: string[];
}
/**
 * Ping message
 */
export interface PingMessage {
    action: 'ping';
}
/**
 * Subscribe to signals message
 */
export interface SubscribeSignalsMessage {
    action: 'subscribe-signals';
    symbols: string[];
}
/**
 * Unsubscribe from signals message
 */
export interface UnsubscribeSignalsMessage {
    action: 'unsubscribe-signals';
    symbols: string[];
}
/**
 * Outgoing WebSocket messages
 */
export type OutgoingMessage = RegisterMessage | SubscribeMessage | UnsubscribeMessage | PingMessage | SubscribeSignalsMessage | UnsubscribeSignalsMessage;
/**
 * Registration response
 */
export interface RegistrationResponse {
    status: 'success' | 'error';
    type: 'registered';
    message: string;
}
/**
 * Subscription response
 */
export interface SubscriptionResponse {
    status: 'success' | 'error';
    type: 'subscribed' | 'unsubscribed';
    message: string;
    stocks?: string[];
}
/**
 * Ticker data from WioEX
 */
export interface TickerData {
    ticket: string;
    last: string;
    open: string;
    high: string;
    low: string;
    volume: string;
    bid: string;
    ask: string;
    change: string;
    changePercent: string;
    timestamp: number;
}
/**
 * Ticker update message (v2 - Streamlined format)
 */
export interface TickerUpdateMessage {
    type: 'ticker';
    data: TickerData;
}
/**
 * Signal type
 */
export type SignalType = 'BUY' | 'SELL' | 'HOLD' | 'STRONG_BUY' | 'STRONG_SELL';
/**
 * Signal timeframe
 */
export type SignalTimeframe = '5m' | '15m' | '1h' | '4h' | '1d' | '1w' | '1M';
/**
 * Signal data
 */
export interface SignalData {
    symbol: string;
    signalType: SignalType;
    entryPrice: number;
    targetPrice: number | null;
    stopLoss: number | null;
    confidence: number;
    reason: string | null;
    timeframe: SignalTimeframe;
    source: string;
    createdAt: string;
    expiresAt: string | null;
}
/**
 * Signal message
 */
export interface SignalMessage {
    type: 'signal';
    data: SignalData;
}
/**
 * Signal trigger type
 */
export type SignalTriggerType = 'entry' | 'target' | 'stop_loss' | 'expired';
/**
 * Signal triggered data
 */
export interface SignalTriggeredData {
    symbol: string;
    signalType: SignalType;
    triggerType: SignalTriggerType;
    triggeredPrice: number;
    triggeredAt: string;
    entryPrice: number;
    targetPrice: number | null;
    stopLoss: number | null;
}
/**
 * Signal triggered message
 */
export interface SignalTriggeredMessage {
    type: 'signal-triggered';
    data: SignalTriggeredData;
}
/**
 * Signal subscription response
 */
export interface SignalSubscriptionResponse {
    type: 'signalSubscribed';
    status: 'success' | 'error';
    message: string;
    symbols?: string[];
}
/**
 * Signal unsubscription response
 */
export interface SignalUnsubscriptionResponse {
    type: 'signalUnsubscribed';
    status: 'success' | 'error';
    message: string;
}
/**
 * Error message
 */
export interface ErrorMessage {
    status: 'error';
    type: string;
    message: string;
    code?: string;
}
/**
 * Incoming WebSocket messages
 */
export type IncomingMessage = RegistrationResponse | SubscriptionResponse | TickerUpdateMessage | SignalMessage | SignalTriggeredMessage | SignalSubscriptionResponse | SignalUnsubscriptionResponse | ErrorMessage;
/**
 * Event types
 */
export interface WioexStreamEvents {
    /** Connection established */
    connected: () => void;
    /** Client registered successfully */
    registered: (data: RegistrationResponse) => void;
    /** Subscribed to stocks */
    subscribed: (stocks: string[]) => void;
    /** Unsubscribed from stocks */
    unsubscribed: (stocks: string[]) => void;
    /** Ticker data update */
    ticker: (data: TickerData) => void;
    /** New trading signal received */
    signal: (data: SignalData) => void;
    /** Trading signal triggered (entry/target/stop-loss) */
    signalTriggered: (data: SignalTriggeredData) => void;
    /** Successfully subscribed to signals */
    signalSubscribed: (symbols: string[]) => void;
    /** Successfully unsubscribed from signals */
    signalUnsubscribed: (symbols: string[]) => void;
    /** Signal subscription error */
    signalError: (error: Error) => void;
    /** Connection error */
    error: (error: Error) => void;
    /** Connection closed */
    disconnected: (code: number, reason: string) => void;
    /** Reconnecting attempt */
    reconnecting: (attempt: number) => void;
    /** Connection state changed */
    stateChange: (state: ConnectionState) => void;
    /** Token fetch started */
    tokenFetchStarted: (source: 'endpoint' | 'api') => void;
    /** Token fetch succeeded */
    tokenFetchSucceeded: (data: {
        token: string;
        expiresAt: number;
        source: 'endpoint' | 'api';
    }) => void;
    /** Token fetch failed (will retry if configured) */
    tokenFetchFailed: (error: Error, attempt: number, willRetry: boolean) => void;
    /** Token is expiring and will be refreshed */
    tokenExpiring: (data: {
        currentToken: string;
        expiresAt: number;
    }) => void;
    /** Token has been successfully refreshed */
    tokenRefreshed: (data: {
        token: string;
        expiresAt: number;
    }) => void;
    /** Token refresh failed */
    tokenRefreshFailed: (error: Error) => void;
}
/**
 * Client statistics
 */
export interface ClientStats {
    connectedAt: number | null;
    reconnectAttempts: number;
    messagesReceived: number;
    messagesSent: number;
    tickersReceived: number;
    subscribedStocks: string[];
    state: ConnectionState;
}
//# sourceMappingURL=types.d.ts.map