@pnds/sdk 0.1.0

package/src/ws.ts

@@ -0,0 +1,250 @@
+import { WS_EVENTS } from './constants.js';
+import type { WsFrame, WsEventMap, WsTicketResponse } from './types.js';
+
+export type WsEventType = keyof WsEventMap;
+export type WsEventHandler<T extends WsEventType> = (data: WsEventMap[T], seq?: number) => void;
+
+export type WsConnectionState = 'connecting' | 'connected' | 'disconnected' | 'reconnecting';
+
+export interface PondWsOptions {
+  /** Async function that fetches a one-time WS ticket from the API. */
+  getTicket: () => Promise<WsTicketResponse>;
+  /** Fallback WS URL if getTicket response doesn't include ws_url. */
+  wsUrl?: string;
+  lastSeq?: number;
+  reconnect?: boolean;
+  reconnectInterval?: number;
+  maxReconnectInterval?: number;
+}
+
+export class PondWs {
+  private ws: WebSocket | null = null;
+  private options: PondWsOptions & { reconnect: boolean; reconnectInterval: number; maxReconnectInterval: number };
+  private listeners = new Map<string, Set<WsEventHandler<WsEventType>>>();
+  private stateListeners = new Set<(state: WsConnectionState) => void>();
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private reconnectAttempts = 0;
+  private lastSeq = 0;
+  private _state: WsConnectionState = 'disconnected';
+  private intentionalClose = false;
+
+  constructor(options: PondWsOptions) {
+    this.options = {
+      reconnect: true,
+      reconnectInterval: 1000,
+      maxReconnectInterval: 30000,
+      ...options,
+    };
+    this.lastSeq = options.lastSeq ?? 0;
+  }
+
+  get state(): WsConnectionState {
+    return this._state;
+  }
+
+  async connect() {
+    this.intentionalClose = false;
+    this.setState('connecting');
+
+    let ticket: WsTicketResponse;
+    try {
+      ticket = await this.options.getTicket();
+    } catch (err) {
+      console.error('Failed to get WS ticket:', err);
+      if (this.options.reconnect) {
+        this.scheduleReconnect();
+      } else {
+        this.setState('disconnected');
+      }
+      return;
+    }
+
+    const wsUrl = ticket.ws_url || this.options.wsUrl;
+    if (!wsUrl) {
+      console.error('No WS URL available');
+      this.setState('disconnected');
+      return;
+    }
+
+    const params = new URLSearchParams({ ticket: ticket.ticket });
+    if (this.lastSeq > 0) {
+      params.set('last_seq', String(this.lastSeq));
+    }
+
+    this.ws = new WebSocket(`${wsUrl}?${params.toString()}`);
+
+    this.ws.onopen = () => {
+      this.reconnectAttempts = 0;
+      this.setState('connected');
+    };
+
+    this.ws.onmessage = (event) => {
+      try {
+        const frame: WsFrame = JSON.parse(event.data as string);
+        this.handleFrame(frame);
+      } catch {
+        // ignore malformed frames
+      }
+    };
+
+    this.ws.onclose = () => {
+      this.stopHeartbeat();
+      if (this.intentionalClose) {
+        this.setState('disconnected');
+        return;
+      }
+      if (this.options.reconnect) {
+        this.scheduleReconnect();
+      } else {
+        this.setState('disconnected');
+      }
+    };
+
+    this.ws.onerror = () => {
+      // onclose will fire after this
+    };
+  }
+
+  disconnect() {
+    this.intentionalClose = true;
+    this.stopHeartbeat();
+    this.clearReconnect();
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+    this.setState('disconnected');
+  }
+
+  // ---- Client -> Server messages ----
+
+  /** Tell the server which chats the user is currently viewing (no auth implications). */
+  watch(chatIds: string[]) {
+    this.send({ type: WS_EVENTS.WATCH, data: { chat_ids: chatIds } });
+  }
+
+  sendTyping(chatId: string, action: 'start' | 'stop', threadRootId?: string) {
+    this.send({
+      type: WS_EVENTS.TYPING,
+      data: { chat_id: chatId, thread_root_id: threadRootId ?? null, action },
+    });
+  }
+
+  sendAck(messageId: string) {
+    this.send({ type: WS_EVENTS.ACK, data: { message_id: messageId } });
+  }
+
+  sendRead(chatId: string, lastReadId: string) {
+    this.send({ type: WS_EVENTS.READ, data: { chat_id: chatId, last_read_id: lastReadId } });
+  }
+
+  /** Send an agent heartbeat with telemetry data. */
+  sendAgentHeartbeat(sessionId: string, telemetry?: Record<string, unknown>) {
+    this.send({
+      type: WS_EVENTS.AGENT_HEARTBEAT,
+      data: { session_id: sessionId, telemetry },
+    });
+  }
+
+  sendEvent(type: string, data: unknown) {
+    this.send({ type, data });
+  }
+
+  // ---- Event listeners ----
+
+  on<T extends WsEventType>(event: T, handler: WsEventHandler<T>) {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(event, set);
+    }
+    set.add(handler as WsEventHandler<WsEventType>);
+    return () => {
+      set!.delete(handler as WsEventHandler<WsEventType>);
+    };
+  }
+
+  off<T extends WsEventType>(event: T, handler: WsEventHandler<T>) {
+    this.listeners.get(event)?.delete(handler as WsEventHandler<WsEventType>);
+  }
+
+  onStateChange(handler: (state: WsConnectionState) => void) {
+    this.stateListeners.add(handler);
+    return () => {
+      this.stateListeners.delete(handler);
+    };
+  }
+
+  // ---- Internal ----
+
+  private send(frame: { type: string; data: unknown }) {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(frame));
+    }
+  }
+
+  private handleFrame(frame: WsFrame) {
+    // Track seq for reconnection
+    if (frame.seq !== undefined) {
+      this.lastSeq = frame.seq;
+    }
+
+    // Handle hello — start heartbeat
+    if (frame.type === WS_EVENTS.HELLO) {
+      const interval = (frame.data as { heartbeat_interval: number }).heartbeat_interval;
+      this.startHeartbeat(interval);
+    }
+
+    // Dispatch to listeners
+    const handlers = this.listeners.get(frame.type);
+    if (handlers) {
+      for (const handler of handlers) {
+        handler(frame.data as WsEventMap[WsEventType], frame.seq);
+      }
+    }
+  }
+
+  private startHeartbeat(intervalSec: number) {
+    this.stopHeartbeat();
+    this.heartbeatTimer = setInterval(() => {
+      this.send({ type: WS_EVENTS.PING, data: { ts: Date.now() } });
+    }, intervalSec * 1000);
+  }
+
+  private stopHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+
+  private scheduleReconnect() {
+    this.setState('reconnecting');
+    this.clearReconnect();
+
+    const delay = Math.min(
+      this.options.reconnectInterval * Math.pow(2, this.reconnectAttempts),
+      this.options.maxReconnectInterval,
+    );
+    this.reconnectAttempts++;
+
+    this.reconnectTimer = setTimeout(() => {
+      this.connect();
+    }, delay);
+  }
+
+  private clearReconnect() {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+
+  private setState(state: WsConnectionState) {
+    this._state = state;
+    for (const listener of this.stateListeners) {
+      listener(state);
+    }
+  }
+}