@k256/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 K256
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# @k256/sdk
+
+Official TypeScript SDK for [K256](https://k256.xyz) - the fastest Solana swap aggregator.
+
+## Installation
+
+```bash
+npm install @k256/sdk
+# or
+yarn add @k256/sdk
+# or
+pnpm add @k256/sdk
+```
+
+## Quick Start
+
+```typescript
+import { K256WebSocketClient } from '@k256/sdk';
+
+const client = new K256WebSocketClient({
+  apiKey: 'your-api-key',
+  mode: 'binary', // 'binary' (default, fastest) or 'json' (debugging)
+  
+  // Message callbacks
+  onPoolUpdate: (update) => console.log('Pool:', update.data.poolAddress),
+  onPriorityFees: (fees) => console.log('Fees:', fees.data.recommended),
+  onBlockhash: (bh) => console.log('Blockhash:', bh.data.blockhash),
+  
+  // Connection callbacks
+  onConnect: () => console.log('Connected'),
+  onDisconnect: (code, reason) => console.log(`Disconnected: ${code}`),
+  onError: (error) => console.error('Error:', error.message),
+});
+
+// Connect and subscribe
+await client.connect();
+client.subscribe({
+  channels: ['pools', 'priority_fees', 'blockhash'],
+  protocols: ['Raydium AMM', 'Orca Whirlpool'], // Optional filter
+});
+
+// Streaming quotes
+client.subscribeQuote({
+  inputMint: 'So11111111111111111111111111111111111111112',  // SOL
+  outputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
+  amount: 1_000_000_000, // 1 SOL in lamports
+  slippageBps: 50,
+  refreshIntervalMs: 1000,
+});
+
+// Graceful disconnect
+client.disconnect();
+```
+
+## Features
+
+- **Binary Protocol**: Direct decoding of K2's high-performance bincode format
+- **Automatic Reconnection**: Exponential backoff with configurable limits  
+- **Ping/Pong Keepalive**: Automatic connection health monitoring
+- **Heartbeat Tracking**: Server status and connection stats
+- **Type-Safe Events**: Full TypeScript types for all message types
+- **RFC 6455 Close Codes**: Proper WebSocket close code handling
+
+## Message Types
+
+| Type | Description |
+|------|-------------|
+| `pool_update` | DEX pool state change |
+| `priority_fees` | Fee estimates (~400ms updates) |
+| `blockhash` | Latest blockhash (~400ms updates) |
+| `quote` | Streaming quote update |
+| `subscribed` | Subscription confirmed |
+| `heartbeat` | Connection stats |
+| `error` | Server error message |
+
+## Connection States
+
+```typescript
+type ConnectionState = 
+  | 'disconnected'    // Not connected
+  | 'connecting'      // Initial connection in progress
+  | 'connected'       // Active connection
+  | 'reconnecting'    // Auto-reconnecting after disconnect
+  | 'closed';         // Explicitly closed, won't reconnect
+```
+
+## Error Handling
+
+```typescript
+import { K256WebSocketError } from '@k256/sdk';
+
+client.onError = (error: K256WebSocketError) => {
+  console.error(`[${error.code}] ${error.message}`);
+  
+  if (error.isAuthError) {
+    // Invalid API key - don't retry
+  }
+  
+  if (error.isRecoverable) {
+    // Will auto-reconnect
+  }
+};
+```
+
+## Low-Level Decoder
+
+For advanced usage, you can use the decoder directly:
+
+```typescript
+import { decodeMessage, decodePoolUpdateBatch, MessageType } from '@k256/sdk/ws';
+
+const ws = new WebSocket('wss://gateway.k256.xyz/v1/ws?apiKey=...');
+ws.binaryType = 'arraybuffer';
+
+ws.onmessage = (event) => {
+  if (event.data instanceof ArrayBuffer) {
+    const message = decodeMessage(event.data);
+    
+    // Handle batched pool updates
+    if (message && new DataView(event.data).getUint8(0) === MessageType.PoolUpdateBatch) {
+      const updates = decodePoolUpdateBatch(event.data.slice(1));
+      for (const update of updates) {
+        console.log(update.data.poolAddress);
+      }
+    }
+  }
+};
+```
+
+## Configuration
+
+```typescript
+interface K256WebSocketClientConfig {
+  apiKey: string;
+  url?: string;              // Default: wss://gateway.k256.xyz/v1/ws
+  mode?: 'binary' | 'json';  // Default: 'binary'
+  
+  // Reconnection
+  autoReconnect?: boolean;        // Default: true
+  reconnectDelayMs?: number;      // Default: 1000
+  maxReconnectDelayMs?: number;   // Default: 30000
+  maxReconnectAttempts?: number;  // Default: Infinity
+  
+  // Keepalive
+  pingIntervalMs?: number;        // Default: 30000
+  pongTimeoutMs?: number;         // Default: 10000
+  heartbeatTimeoutMs?: number;    // Default: 15000
+}
+```
+
+## Links
+
+- [K256 Website](https://k256.xyz)
+- [API Documentation](https://docs.k256.xyz)
+- [GitHub](https://github.com/k256-xyz)
+
+## License
+
+MIT