@alpha-arcade/sdk 0.3.1 → 0.4.1

package/README.md

@@ -337,6 +337,150 @@ for (const m of rewardMarkets) {
 
 ---
 
+### WebSocket Streams
+
+Real-time data streams via WebSocket. No API key or auth required. Replaces polling with push-based updates.
+
+The SDK connects to the public platform websocket at `wss://wss.platform.alphaarcade.com`. The first
+subscription is sent in the connection query string, and any later subscribe or unsubscribe calls use the
+server's control-message envelope:
+
+```json
+{
+  "id": "request-id",
+  "method": "SUBSCRIBE",
+  "params": [
+    { "stream": "get-orderbook", "slug": "will-btc-hit-100k" }
+  ]
+}
+```
+
+Supported public streams:
+
+- `get-live-markets`
+- `get-market` with `slug`
+- `get-orderbook` with `slug`
+- `get-wallet-orders` with `wallet`
+
+```typescript
+import { AlphaWebSocket } from '@alpha-arcade/sdk';
+
+// Node.js 22+ and browsers — native WebSocket, nothing extra needed
+const ws = new AlphaWebSocket();
+
+// Node.js < 22 — install `ws` and pass it in:
+// npm install ws
+import WebSocket from 'ws';
+const ws = new AlphaWebSocket({ WebSocket });
+
+// Subscribe to orderbook updates (~5s snapshots)
+const unsub = ws.subscribeOrderbook('will-btc-hit-100k', (event) => {
+  console.log('Orderbook:', event.orderbook);
+});
+
+// Unsubscribe when done
+unsub();
+
+// Close the connection
+ws.close();
+```
+
+#### `subscribeLiveMarkets(callback)`
+
+Receive incremental diffs whenever market probabilities change.
+
+```typescript
+ws.subscribeLiveMarkets((event) => {
+  console.log('Markets changed at', event.ts, event);
+});
+```
+
+#### `subscribeMarket(slug, callback)`
+
+Receive change events for a single market. Uses the market **slug** (not `marketAppId`) — see note on `subscribeOrderbook` below.
+
+```typescript
+ws.subscribeMarket('will-btc-hit-100k', (event) => {
+  console.log('Market update:', event);
+});
+```
+
+#### `subscribeOrderbook(slug, callback)`
+
+Receive full orderbook snapshots on every change (~5s interval). Replaces on-chain polling.
+
+**Note:** The WebSocket API uses market **slugs** (URL-friendly names like `"will-btc-hit-100k"`), not `marketAppId` numbers. You can get a market's slug from the `slug` field on `Market` objects returned by `getLiveMarkets()` or `getMarket()`.
+
+```typescript
+ws.subscribeOrderbook('will-btc-hit-100k', (event) => {
+  // Top-level bids/asks use decimal prices (cents)
+  // Nested yes/no use raw microunit prices with escrowAppId and owner
+  for (const [appId, book] of Object.entries(event.orderbook)) {
+    console.log(`App ${appId}: spread=${book.spread}`);
+    console.log('  Bids:', book.bids);
+    console.log('  Yes bids:', book.yes.bids);
+  }
+});
+```
+
+#### `subscribeWalletOrders(wallet, callback)`
+
+Receive updates when orders for a wallet are created or modified.
+
+```typescript
+ws.subscribeWalletOrders('MMU6X...', (event) => {
+  console.log('Wallet orders changed:', event);
+});
+```
+
+#### Unsubscribing
+
+Each `subscribe*` method returns an unsubscribe function. Call it to stop receiving events for that stream:
+
+```typescript
+const unsub = ws.subscribeOrderbook('my-market', (event) => { /* ... */ });
+
+// Later, stop listening
+unsub();
+```
+
+#### Control Methods
+
+```typescript
+// List active subscriptions on this connection
+const subs = await ws.listSubscriptions();
+
+// Query server properties (`heartbeat` or `limits`)
+const props = await ws.getProperty('heartbeat');
+```
+
+#### Configuration
+
+```typescript
+import WebSocket from 'ws'; // Only needed on Node.js < 22
+
+const ws = new AlphaWebSocket({
+  WebSocket,                                  // Pass `ws` on Node.js < 22 (not needed in browsers or Node 22+)
+  url: 'wss://custom-endpoint.example.com',   // Override default URL
+  reconnect: true,                            // Auto-reconnect (default: true)
+  maxReconnectAttempts: 10,                   // Give up after 10 retries (default: Infinity)
+  heartbeatIntervalMs: 60_000,                // Ping interval in ms (default: 60000)
+});
+```
+
+#### Connection Details
+
+| Setting | Value |
+|---------|-------|
+| Heartbeat | 60s (auto-handled) |
+| Idle timeout | 180s |
+| Rate limit | 5 messages/sec/connection |
+| Reconnect | Exponential backoff (1s → 30s max) |
+
+The client automatically responds to server pings, sends keepalive pings, and reconnects with exponential backoff on unexpected disconnects. All active subscriptions are restored after reconnect.
+
+---
+
 ### Utility Functions
 
 These are exported for advanced users:

package/dist/index.cjs

@@ -2125,6 +2125,7 @@ var calculateMatchingOrders = (orderbook, isBuying, isYes, quantity, price, slip
 
 // src/constants.ts
 var DEFAULT_API_BASE_URL = "https://platform.alphaarcade.com/api";
+var DEFAULT_WSS_BASE_URL = "wss://wss.platform.alphaarcade.com";
 var DEFAULT_MARKET_CREATOR_ADDRESS = "5P5Y6HTWUNG2E3VXBQDZN3ENZD3JPAIR5PKT3LOYJAPAUKOLFD6KANYTRY";
 
 // src/modules/orderbook.ts
@@ -3366,9 +3367,275 @@ var AlphaClient = class {
   }
 };
 
+// src/websocket.ts
+var WS_OPEN = 1;
+var resolveWebSocket = (provided) => {
+  if (provided) return provided;
+  if (typeof globalThis !== "undefined" && globalThis.WebSocket) {
+    return globalThis.WebSocket;
+  }
+  throw new Error(
+    'No WebSocket implementation found. On Node.js < 22, install the "ws" package and pass it: new AlphaWebSocket({ WebSocket: require("ws") })'
+  );
+};
+var AlphaWebSocket = class {
+  url;
+  reconnectEnabled;
+  maxReconnectAttempts;
+  heartbeatIntervalMs;
+  WebSocketImpl;
+  ws = null;
+  subscriptions = /* @__PURE__ */ new Map();
+  pendingRequests = /* @__PURE__ */ new Map();
+  heartbeatTimer = null;
+  reconnectTimer = null;
+  reconnectAttempts = 0;
+  intentionallyClosed = false;
+  connectPromise = null;
+  constructor(config) {
+    this.url = config?.url ?? DEFAULT_WSS_BASE_URL;
+    this.reconnectEnabled = config?.reconnect ?? true;
+    this.maxReconnectAttempts = config?.maxReconnectAttempts ?? Infinity;
+    this.heartbeatIntervalMs = config?.heartbeatIntervalMs ?? 6e4;
+    this.WebSocketImpl = resolveWebSocket(config?.WebSocket);
+  }
+  /** Whether the WebSocket is currently open and connected */
+  get connected() {
+    return this.ws?.readyState === WS_OPEN;
+  }
+  // ============================================
+  // Subscribe Methods
+  // ============================================
+  /**
+   * Subscribe to live market probability updates (incremental diffs).
+   * @returns An unsubscribe function
+   */
+  subscribeLiveMarkets(callback) {
+    return this.subscribe("get-live-markets", {}, "markets_changed", callback);
+  }
+  /**
+   * Subscribe to change events for a single market.
+   * @param slug - The market slug
+   * @returns An unsubscribe function
+   */
+  subscribeMarket(slug, callback) {
+    return this.subscribe("get-market", { slug }, "market_changed", callback);
+  }
+  /**
+   * Subscribe to full orderbook snapshots (~5s interval on changes).
+   * @param slug - The market slug
+   * @returns An unsubscribe function
+   */
+  subscribeOrderbook(slug, callback) {
+    return this.subscribe("get-orderbook", { slug }, "orderbook_changed", callback);
+  }
+  /**
+   * Subscribe to wallet order updates.
+   * @param wallet - The wallet address
+   * @returns An unsubscribe function
+   */
+  subscribeWalletOrders(wallet, callback) {
+    return this.subscribe("get-wallet-orders", { wallet }, "wallet_orders_changed", callback);
+  }
+  // ============================================
+  // Control Methods
+  // ============================================
+  /** Query the server for the list of active subscriptions on this connection */
+  listSubscriptions() {
+    return this.sendRequest({ method: "LIST_SUBSCRIPTIONS" });
+  }
+  /** Query a server property (e.g. "heartbeat", "limits") */
+  getProperty(property) {
+    return this.sendRequest({ method: "GET_PROPERTY", params: [property] });
+  }
+  // ============================================
+  // Lifecycle
+  // ============================================
+  /** Open the WebSocket connection. Called automatically on first subscribe. */
+  connect() {
+    if (this.connectPromise) return this.connectPromise;
+    this.connectPromise = this.doConnect();
+    return this.connectPromise;
+  }
+  /** Close the connection and clean up all resources */
+  close() {
+    this.intentionallyClosed = true;
+    this.clearTimers();
+    this.subscriptions.clear();
+    for (const [, req] of this.pendingRequests) {
+      clearTimeout(req.timer);
+      req.reject(new Error("WebSocket closed"));
+    }
+    this.pendingRequests.clear();
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+    this.connectPromise = null;
+  }
+  // ============================================
+  // Internal
+  // ============================================
+  buildStreamKey(stream, params) {
+    const parts = [stream, ...Object.entries(params).sort().map(([k, v]) => `${k}=${v}`)];
+    return parts.join("&");
+  }
+  buildQueryString() {
+    const subs = [...this.subscriptions.values()];
+    if (subs.length === 0) return "";
+    const first = subs[0];
+    const params = new URLSearchParams({ stream: first.stream, ...first.params });
+    return "?" + params.toString();
+  }
+  subscribe(stream, params, eventType, callback) {
+    const key = this.buildStreamKey(stream, params);
+    this.subscriptions.set(key, { stream, params, callback, eventType });
+    if (this.connected) {
+      this.sendSubscribe(stream, params);
+    } else {
+      this.connect();
+    }
+    return () => {
+      this.subscriptions.delete(key);
+      if (this.connected) {
+        this.sendUnsubscribe(stream, params);
+      }
+    };
+  }
+  async doConnect() {
+    this.intentionallyClosed = false;
+    return new Promise((resolve, reject) => {
+      const qs = this.buildQueryString();
+      const ws = new this.WebSocketImpl(this.url + qs);
+      ws.onopen = () => {
+        this.ws = ws;
+        this.reconnectAttempts = 0;
+        this.startHeartbeat();
+        const subs = [...this.subscriptions.values()];
+        for (const sub of subs.slice(1)) {
+          this.sendSubscribe(sub.stream, sub.params);
+        }
+        resolve();
+      };
+      ws.onmessage = (event) => {
+        this.handleMessage(event.data);
+      };
+      ws.onclose = () => {
+        this.ws = null;
+        this.connectPromise = null;
+        this.stopHeartbeat();
+        if (!this.intentionallyClosed) {
+          this.scheduleReconnect();
+        }
+      };
+      ws.onerror = (err) => {
+        if (!this.ws) {
+          reject(new Error("WebSocket connection failed"));
+        }
+      };
+    });
+  }
+  handleMessage(raw) {
+    let msg;
+    try {
+      msg = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    if (msg.type === "ping") {
+      this.send({ method: "PONG" });
+      return;
+    }
+    const responseId = typeof msg.id === "string" ? msg.id : typeof msg.requestId === "string" ? msg.requestId : null;
+    if (responseId && this.pendingRequests.has(responseId)) {
+      const req = this.pendingRequests.get(responseId);
+      this.pendingRequests.delete(responseId);
+      clearTimeout(req.timer);
+      req.resolve(msg);
+      return;
+    }
+    const eventType = msg.type;
+    if (!eventType) return;
+    for (const sub of this.subscriptions.values()) {
+      if (sub.eventType === eventType) {
+        try {
+          sub.callback(msg);
+        } catch {
+        }
+      }
+    }
+  }
+  sendSubscribe(stream, params) {
+    this.send({ method: "SUBSCRIBE", params: [{ stream, ...params }] });
+  }
+  sendUnsubscribe(stream, params) {
+    this.send({ method: "UNSUBSCRIBE", params: [{ stream, ...params }] });
+  }
+  sendRequest(payload, timeoutMs = 1e4) {
+    const requestId = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingRequests.delete(requestId);
+        reject(new Error("Request timed out"));
+      }, timeoutMs);
+      this.pendingRequests.set(requestId, { resolve, reject, timer });
+      if (!this.connected) {
+        this.connect().then(() => {
+          this.send({ ...payload, id: requestId });
+        }).catch(reject);
+      } else {
+        this.send({ ...payload, id: requestId });
+      }
+    });
+  }
+  send(data) {
+    if (this.ws?.readyState === WS_OPEN) {
+      this.ws.send(JSON.stringify(data));
+    }
+  }
+  // ============================================
+  // Heartbeat
+  // ============================================
+  startHeartbeat() {
+    this.stopHeartbeat();
+    this.heartbeatTimer = setInterval(() => {
+      this.send({ method: "PING" });
+    }, this.heartbeatIntervalMs);
+  }
+  stopHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+  // ============================================
+  // Reconnect
+  // ============================================
+  scheduleReconnect() {
+    if (!this.reconnectEnabled) return;
+    if (this.reconnectAttempts >= this.maxReconnectAttempts) return;
+    const delay = Math.min(1e3 * 2 ** this.reconnectAttempts, 3e4);
+    this.reconnectAttempts++;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect().catch(() => {
+      });
+    }, delay);
+  }
+  clearTimers() {
+    this.stopHeartbeat();
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+};
+
 exports.AlphaClient = AlphaClient;
+exports.AlphaWebSocket = AlphaWebSocket;
 exports.DEFAULT_API_BASE_URL = DEFAULT_API_BASE_URL;
 exports.DEFAULT_MARKET_CREATOR_ADDRESS = DEFAULT_MARKET_CREATOR_ADDRESS;
+exports.DEFAULT_WSS_BASE_URL = DEFAULT_WSS_BASE_URL;
 exports.calculateFee = calculateFee;
 exports.calculateFeeFromTotal = calculateFeeFromTotal;
 exports.calculateMatchingOrders = calculateMatchingOrders;