@k256/sdk 0.1.0

package/dist/ws/index.d.cts

@@ -0,0 +1,516 @@
+/**
+ * WebSocket message types and interfaces
+ *
+ * Message type constants MUST match the K2 server values.
+ * See: https://github.com/k256-xyz for protocol documentation
+ */
+/**
+ * WebSocket message type constants
+ *
+ * These are the byte prefixes used in the binary protocol.
+ * All SDKs across all languages MUST use these exact values.
+ */
+declare const MessageType: {
+    /** Single pool state update (bincode) */
+    readonly PoolUpdate: 1;
+    /** Subscribe request (JSON) - Client → Server */
+    readonly Subscribe: 2;
+    /** Subscription confirmed (JSON) - Server → Client */
+    readonly Subscribed: 3;
+    /** Unsubscribe all - Client → Server */
+    readonly Unsubscribe: 4;
+    /** Priority fee update (bincode) */
+    readonly PriorityFees: 5;
+    /** Recent blockhash (bincode) */
+    readonly Blockhash: 6;
+    /** Streaming quote update (bincode) */
+    readonly Quote: 7;
+    /** Quote subscription confirmed (JSON) */
+    readonly QuoteSubscribed: 8;
+    /** Subscribe to quote stream (JSON) - Client → Server */
+    readonly SubscribeQuote: 9;
+    /** Unsubscribe from quote (JSON) - Client → Server */
+    readonly UnsubscribeQuote: 10;
+    /** Ping keepalive - Client → Server */
+    readonly Ping: 11;
+    /** Pong response (bincode u64 timestamp) */
+    readonly Pong: 12;
+    /** Connection heartbeat with stats (JSON) */
+    readonly Heartbeat: 13;
+    /** Batched pool updates for high throughput */
+    readonly PoolUpdateBatch: 14;
+    /** Error message (UTF-8 string) */
+    readonly Error: 255;
+};
+type MessageTypeValue = typeof MessageType[keyof typeof MessageType];
+/**
+ * Decoded pool update from binary message
+ */
+interface PoolUpdateMessage {
+    type: 'pool_update';
+    data: {
+        sequence: number;
+        slot: number;
+        writeVersion: number;
+        protocol: string;
+        poolAddress: string;
+        tokenMints: string[];
+        tokenBalances: string[];
+        tokenDecimals: number[];
+        isValid: boolean;
+        bestBid?: {
+            price: string;
+            size: string;
+        };
+        bestAsk?: {
+            price: string;
+            size: string;
+        };
+    };
+}
+/**
+ * Decoded priority fees from binary message
+ *
+ * All fields from K2 PriorityFeesWire
+ */
+interface PriorityFeesMessage {
+    type: 'priority_fees';
+    data: {
+        slot: number;
+        timestampMs: number;
+        /** Recommended priority fee in micro-lamports */
+        recommended: number;
+        /** Fee state: 0=low, 1=normal, 2=high, 3=extreme */
+        state: number;
+        /** True if data is stale (no recent samples) */
+        isStale: boolean;
+        swapP50: number;
+        swapP75: number;
+        swapP90: number;
+        swapP99: number;
+        /** Number of samples used for swap percentiles */
+        swapSamples: number;
+        landingP50Fee: number;
+        landingP75Fee: number;
+        landingP90Fee: number;
+        landingP99Fee: number;
+        top10Fee: number;
+        top25Fee: number;
+        spikeDetected: boolean;
+        spikeFee: number;
+    };
+}
+/**
+ * Decoded blockhash from binary message
+ */
+interface BlockhashMessage {
+    type: 'blockhash';
+    data: {
+        slot: number;
+        timestampMs: number;
+        blockhash: string;
+        blockHeight: number;
+        lastValidBlockHeight: number;
+        isStale: boolean;
+    };
+}
+/**
+ * Decoded quote from binary message
+ */
+interface QuoteMessage {
+    type: 'quote';
+    data: {
+        topicId: string;
+        timestampMs: number;
+        sequence: number;
+        inputMint: string;
+        outputMint: string;
+        inAmount: string;
+        outAmount: string;
+        priceImpactBps: number;
+        contextSlot: number;
+        algorithm: string;
+        isImprovement: boolean;
+        isCached: boolean;
+        isStale: boolean;
+        routePlan: unknown | null;
+    };
+}
+/**
+ * Decoded heartbeat from JSON message
+ */
+interface HeartbeatMessage {
+    type: 'heartbeat';
+    data: {
+        timestampMs: number;
+        uptimeSecs: number;
+        messagesSent: number;
+        poolUpdatesSent: number;
+        messagesDropped: number;
+        poolUpdatesEnabled: boolean;
+        subscribedChannels: string[];
+        serverSequence: number;
+    };
+}
+/**
+ * Subscription confirmed message
+ */
+interface SubscribedMessage {
+    type: 'subscribed';
+    data: {
+        channelCount: number;
+        channels: string[];
+        poolCount: number;
+        tokenPairCount: number;
+        protocolCount: number;
+        poolUpdatesEnabled: boolean;
+        timestampMs: number;
+        summary: string;
+        format?: 'binary' | 'json';
+    };
+}
+/**
+ * Quote subscription confirmed message
+ */
+interface QuoteSubscribedMessage {
+    type: 'quote_subscribed';
+    data: {
+        topicId: string;
+        inputMint: string;
+        outputMint: string;
+        amount: string;
+        slippageBps: number;
+        refreshIntervalMs: number;
+        timestampMs: number;
+    };
+}
+/**
+ * Error message from server
+ */
+interface ErrorMessage {
+    type: 'error';
+    data: {
+        message: string;
+    };
+}
+/**
+ * Pong response message
+ */
+interface PongMessage {
+    type: 'pong';
+    data: {
+        timestampMs: number;
+    };
+}
+/**
+ * Union of all decoded message types
+ */
+type DecodedMessage = PoolUpdateMessage | PriorityFeesMessage | BlockhashMessage | QuoteMessage | HeartbeatMessage | SubscribedMessage | QuoteSubscribedMessage | ErrorMessage | PongMessage;
+
+/**
+ * K256 WebSocket Client
+ *
+ * Production-grade WebSocket client with:
+ * - Automatic reconnection with exponential backoff
+ * - Binary and JSON mode support
+ * - Ping/pong keepalive
+ * - Heartbeat monitoring
+ * - Full error handling with RFC 6455 close codes
+ * - Type-safe event emitters
+ *
+ * @example
+ * ```typescript
+ * const client = new K256WebSocketClient({
+ *   apiKey: 'your-api-key',
+ *   mode: 'binary', // or 'json'
+ *   onPoolUpdate: (update) => console.log(update),
+ *   onError: (error) => console.error(error),
+ * });
+ *
+ * await client.connect();
+ * client.subscribe({ channels: ['pools', 'priority_fees'] });
+ * ```
+ */
+
+/**
+ * RFC 6455 WebSocket Close Codes
+ * @see https://www.rfc-editor.org/rfc/rfc6455#section-7.4.1
+ */
+declare const CloseCode: {
+    /** 1000: Normal closure - connection completed successfully */
+    readonly NORMAL: 1000;
+    /** 1001: Going away - server/client shutting down. Client: reconnect immediately */
+    readonly GOING_AWAY: 1001;
+    /** 1002: Protocol error - invalid frame format. Client: fix client code */
+    readonly PROTOCOL_ERROR: 1002;
+    /** 1003: Unsupported data - message type not supported */
+    readonly UNSUPPORTED_DATA: 1003;
+    /** 1005: No status received (reserved, not sent over wire) */
+    readonly NO_STATUS: 1005;
+    /** 1006: Abnormal closure - connection dropped without close frame */
+    readonly ABNORMAL: 1006;
+    /** 1007: Invalid payload - malformed UTF-8 or data. Client: fix message format */
+    readonly INVALID_PAYLOAD: 1007;
+    /** 1008: Policy violation - rate limit exceeded, auth failed. Client: check credentials/limits */
+    readonly POLICY_VIOLATION: 1008;
+    /** 1009: Message too big - message exceeds size limits */
+    readonly MESSAGE_TOO_BIG: 1009;
+    /** 1010: Missing extension - required extension not negotiated */
+    readonly MISSING_EXTENSION: 1010;
+    /** 1011: Internal error - unexpected server error. Client: retry with backoff */
+    readonly INTERNAL_ERROR: 1011;
+    /** 1012: Service restart - server is restarting. Client: reconnect after brief delay */
+    readonly SERVICE_RESTART: 1012;
+    /** 1013: Try again later - server overloaded. Client: retry with backoff */
+    readonly TRY_AGAIN_LATER: 1013;
+    /** 1014: Bad gateway - upstream connection failed */
+    readonly BAD_GATEWAY: 1014;
+    /** 1015: TLS handshake failed (reserved, not sent over wire) */
+    readonly TLS_HANDSHAKE: 1015;
+};
+type CloseCodeValue = typeof CloseCode[keyof typeof CloseCode];
+/**
+ * Connection state
+ */
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'closed';
+/**
+ * Subscribe request options
+ */
+interface SubscribeOptions {
+    /** Channels to subscribe to: 'pools', 'priority_fees', 'blockhash' */
+    channels: string[];
+    /** Pool address filters (optional) */
+    pools?: string[];
+    /** Protocol filters (optional): 'Raydium AMM', 'Orca Whirlpool', etc. */
+    protocols?: string[];
+    /** Token pair filters (optional): [['mint1', 'mint2'], ...] */
+    tokenPairs?: string[][];
+}
+/**
+ * Quote subscription options
+ */
+interface SubscribeQuoteOptions {
+    /** Input token mint address */
+    inputMint: string;
+    /** Output token mint address */
+    outputMint: string;
+    /** Amount in base units (lamports/smallest unit) */
+    amount: number | string;
+    /** Slippage tolerance in basis points */
+    slippageBps: number;
+    /** How often to refresh the quote (ms) */
+    refreshIntervalMs?: number;
+}
+/**
+ * WebSocket client configuration
+ */
+interface K256WebSocketClientConfig {
+    /** API key for authentication */
+    apiKey: string;
+    /** Gateway URL (default: wss://gateway.k256.xyz/v1/ws) */
+    url?: string;
+    /** Message format: 'binary' (default, efficient) or 'json' (debugging) */
+    mode?: 'binary' | 'json';
+    /** Enable automatic reconnection (default: true) */
+    autoReconnect?: boolean;
+    /** Initial reconnect delay in ms (default: 1000) */
+    reconnectDelayMs?: number;
+    /** Max reconnect delay in ms (default: 30000) */
+    maxReconnectDelayMs?: number;
+    /** Max reconnect attempts (default: Infinity) */
+    maxReconnectAttempts?: number;
+    /** Ping interval in ms (default: 30000) */
+    pingIntervalMs?: number;
+    /** Pong timeout in ms - disconnect if no pong (default: 10000) */
+    pongTimeoutMs?: number;
+    /** Heartbeat timeout in ms - warn if no heartbeat (default: 15000) */
+    heartbeatTimeoutMs?: number;
+    /** Called when connection state changes */
+    onStateChange?: (state: ConnectionState, prevState: ConnectionState) => void;
+    /** Called on successful connection */
+    onConnect?: () => void;
+    /** Called on disconnection */
+    onDisconnect?: (code: number, reason: string, wasClean: boolean) => void;
+    /** Called on reconnection attempt */
+    onReconnecting?: (attempt: number, delayMs: number) => void;
+    /** Called on any error */
+    onError?: (error: K256WebSocketError) => void;
+    /** Called on subscription confirmed */
+    onSubscribed?: (data: DecodedMessage & {
+        type: 'subscribed';
+    }) => void;
+    /** Called on pool update */
+    onPoolUpdate?: (update: PoolUpdateMessage) => void;
+    /** Called on batched pool updates (for efficiency) */
+    onPoolUpdateBatch?: (updates: PoolUpdateMessage[]) => void;
+    /** Called on priority fees update */
+    onPriorityFees?: (data: DecodedMessage & {
+        type: 'priority_fees';
+    }) => void;
+    /** Called on blockhash update */
+    onBlockhash?: (data: DecodedMessage & {
+        type: 'blockhash';
+    }) => void;
+    /** Called on quote update */
+    onQuote?: (data: DecodedMessage & {
+        type: 'quote';
+    }) => void;
+    /** Called on quote subscription confirmed */
+    onQuoteSubscribed?: (data: DecodedMessage & {
+        type: 'quote_subscribed';
+    }) => void;
+    /** Called on heartbeat */
+    onHeartbeat?: (data: DecodedMessage & {
+        type: 'heartbeat';
+    }) => void;
+    /** Called on pong response (with round-trip latency) */
+    onPong?: (latencyMs: number) => void;
+    /** Called on any message (raw) */
+    onMessage?: (message: DecodedMessage) => void;
+    /** Called on raw binary message (for debugging) */
+    onRawMessage?: (data: ArrayBuffer | string) => void;
+}
+/**
+ * Error types for K256 WebSocket
+ */
+type K256ErrorCode = 'CONNECTION_FAILED' | 'CONNECTION_LOST' | 'PROTOCOL_ERROR' | 'AUTH_FAILED' | 'RATE_LIMITED' | 'SERVER_ERROR' | 'PING_TIMEOUT' | 'HEARTBEAT_TIMEOUT' | 'INVALID_MESSAGE' | 'RECONNECT_FAILED';
+/**
+ * WebSocket error with context
+ */
+declare class K256WebSocketError extends Error {
+    readonly code: K256ErrorCode;
+    readonly closeCode?: number | undefined;
+    readonly closeReason?: string | undefined;
+    readonly cause?: unknown | undefined;
+    constructor(code: K256ErrorCode, message: string, closeCode?: number | undefined, closeReason?: string | undefined, cause?: unknown | undefined);
+    /** Check if error is recoverable (should trigger reconnect) */
+    get isRecoverable(): boolean;
+    /** Check if error is an auth failure */
+    get isAuthError(): boolean;
+}
+/**
+ * Production-grade K256 WebSocket Client
+ */
+declare class K256WebSocketClient {
+    private ws;
+    private config;
+    private _state;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private pingTimer;
+    private pongTimer;
+    private heartbeatTimer;
+    private lastPingTime;
+    private lastHeartbeatTime;
+    private pendingSubscription;
+    private pendingQuoteSubscription;
+    private isIntentionallyClosed;
+    /** Current connection state */
+    get state(): ConnectionState;
+    /** Whether currently connected */
+    get isConnected(): boolean;
+    /** Time since last heartbeat (ms) or null if no heartbeat received */
+    get timeSinceHeartbeat(): number | null;
+    /** Current reconnect attempt number */
+    get currentReconnectAttempt(): number;
+    constructor(config: K256WebSocketClientConfig);
+    /**
+     * Connect to the WebSocket server
+     * @returns Promise that resolves when connected
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the WebSocket server
+     * @param code - Close code (default: 1000 NORMAL)
+     * @param reason - Close reason
+     */
+    disconnect(code?: number, reason?: string): void;
+    /**
+     * Subscribe to channels
+     */
+    subscribe(options: SubscribeOptions): void;
+    /**
+     * Subscribe to a quote stream
+     */
+    subscribeQuote(options: SubscribeQuoteOptions): void;
+    /**
+     * Unsubscribe from a quote stream
+     * @param topicId - Topic ID from quote_subscribed response
+     */
+    unsubscribeQuote(topicId: string): void;
+    /**
+     * Unsubscribe from all channels
+     */
+    unsubscribe(): void;
+    /**
+     * Send a ping to measure latency
+     */
+    ping(): void;
+    private doConnect;
+    private handleMessage;
+    private sendSubscription;
+    private sendQuoteSubscription;
+    private setState;
+    private handleError;
+    private cleanup;
+    private startPingInterval;
+    private startPongTimeout;
+    private clearPongTimeout;
+    private startHeartbeatTimeout;
+    private resetHeartbeatTimeout;
+    private shouldReconnect;
+    private scheduleReconnect;
+    private getCloseReason;
+    private getErrorCodeFromClose;
+}
+
+/**
+ * Binary message decoder for K256 WebSocket protocol
+ *
+ * Decodes binary messages from K2 server into typed JavaScript objects.
+ * Supports both single messages and batched pool updates.
+ *
+ * Wire format: [1 byte MessageType][N bytes Payload]
+ */
+
+/**
+ * Decode a binary WebSocket message from K2
+ *
+ * @param data - Raw binary data from WebSocket
+ * @returns Decoded message or null if unrecognized type
+ *
+ * @example
+ * ```typescript
+ * ws.onmessage = (event) => {
+ *   if (event.data instanceof ArrayBuffer) {
+ *     const message = decodeMessage(event.data);
+ *     if (message?.type === 'pool_update') {
+ *       console.log(message.data.poolAddress);
+ *     }
+ *   }
+ * };
+ * ```
+ */
+declare function decodeMessage(data: ArrayBuffer): DecodedMessage | null;
+/**
+ * Decode a batch of pool updates
+ *
+ * Use this when you need to process all updates in a batch.
+ * For high-throughput scenarios, batches can contain 50-200 updates.
+ *
+ * @param data - Raw payload (without the 0x0E type prefix)
+ * @returns Array of decoded pool updates
+ *
+ * @example
+ * ```typescript
+ * if (msgType === MessageType.PoolUpdateBatch) {
+ *   const updates = decodePoolUpdateBatch(payload);
+ *   for (const update of updates) {
+ *     console.log(update.data.poolAddress);
+ *   }
+ * }
+ * ```
+ */
+declare function decodePoolUpdateBatch(payload: ArrayBuffer): PoolUpdateMessage[];
+
+export { type BlockhashMessage, CloseCode, type CloseCodeValue, type ConnectionState, type DecodedMessage, type ErrorMessage, type HeartbeatMessage, type K256ErrorCode, K256WebSocketClient, type K256WebSocketClientConfig, K256WebSocketError, MessageType, type MessageTypeValue, type PongMessage, type PoolUpdateMessage, type PriorityFeesMessage, type QuoteMessage, type QuoteSubscribedMessage, type SubscribeOptions, type SubscribeQuoteOptions, type SubscribedMessage, decodeMessage, decodePoolUpdateBatch };