walletpair-sdk 1.0.0

package/src/ws-transport.test.ts

@@ -0,0 +1,231 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { WebSocketTransport } from './ws-transport.js';
+
+// Mock WebSocket for Node.js environment
+class MockWebSocket {
+  static instances: MockWebSocket[] = [];
+
+  url: string;
+  protocols: string[];
+  readyState = 0; // CONNECTING
+  onopen: (() => void) | null = null;
+  onmessage: ((event: { data: string }) => void) | null = null;
+  onclose: (() => void) | null = null;
+  onerror: (() => void) | null = null;
+  sentMessages: string[] = [];
+
+  constructor(url: string, protocols?: string[]) {
+    this.url = url;
+    this.protocols = protocols ?? [];
+    MockWebSocket.instances.push(this);
+  }
+
+  send(data: string) {
+    this.sentMessages.push(data);
+  }
+
+  close() {
+    this.readyState = 3; // CLOSED
+    this.onclose?.();
+  }
+
+  // Test helpers
+  simulateOpen() {
+    this.readyState = 1; // OPEN
+    this.onopen?.();
+  }
+
+  simulateMessage(data: string) {
+    this.onmessage?.({ data });
+  }
+
+  simulateClose() {
+    this.readyState = 3;
+    this.onclose?.();
+  }
+
+  simulateError() {
+    this.onerror?.();
+  }
+}
+
+describe('WebSocketTransport', () => {
+  let originalWebSocket: typeof globalThis.WebSocket;
+
+  beforeEach(() => {
+    MockWebSocket.instances = [];
+    originalWebSocket = globalThis.WebSocket;
+    (globalThis as any).WebSocket = MockWebSocket;
+  });
+
+  afterEach(() => {
+    globalThis.WebSocket = originalWebSocket;
+  });
+
+  it('starts disconnected', () => {
+    const t = new WebSocketTransport('ws://localhost:8080/v1');
+    expect(t.state).toBe('disconnected');
+  });
+
+  it('accepts string URL constructor', () => {
+    const t = new WebSocketTransport('ws://localhost:8080/v1');
+    expect(t.state).toBe('disconnected');
+  });
+
+  it('accepts options object constructor', () => {
+    const t = new WebSocketTransport({ url: 'ws://localhost:8080/v1', protocols: ['custom'] });
+    expect(t.state).toBe('disconnected');
+  });
+
+  describe('connect', () => {
+    it('resolves on successful connection', async () => {
+      const t = new WebSocketTransport('ws://localhost:8080/v1');
+
+      const connectPromise = t.connect();
+
+      // Simulate WebSocket open
+      const ws = MockWebSocket.instances[0]!;
+      expect(ws.url).toBe('ws://localhost:8080/v1');
+      expect(ws.protocols).toEqual(['walletpair.v1']);
+
+      ws.simulateOpen();
+
+      await connectPromise;
+      expect(t.state).toBe('connected');
+    });
+
+    it('rejects on connection failure', async () => {
+      const t = new WebSocketTransport('ws://localhost:8080/v1');
+
+      const connectPromise = t.connect();
+
+      const ws = MockWebSocket.instances[0]!;
+      ws.simulateError();
+      ws.simulateClose();
+
+      await expect(connectPromise).rejects.toThrow('WebSocket connection failed');
+      expect(t.state).toBe('disconnected');
+    });
+
+    it('calls onOpen handler on successful connection', async () => {
+      const t = new WebSocketTransport('ws://localhost:8080/v1');
+      const openHandler = vi.fn();
+      t.onOpen(openHandler);
+
+      const promise = t.connect();
+      MockWebSocket.instances[0]!.simulateOpen();
+      await promise;
+
+      expect(openHandler).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('send', () => {
+    it('sends JSON-serialized message', async () => {
+      const t = new WebSocketTransport('ws://localhost:8080/v1');
+      const promise = t.connect();
+      MockWebSocket.instances[0]!.simulateOpen();
+      await promise;
+
+      const msg = { v: 1, t: 'ping', ch: 'abc', ts: 123 } as any;
+      t.send(msg);
+
+      const ws = MockWebSocket.instances[0]!;
+      expect(ws.sentMessages).toHaveLength(1);
+      expect(JSON.parse(ws.sentMessages[0]!)).toEqual(msg);
+    });
+
+    it('does nothing when not connected', () => {
+      const t = new WebSocketTransport('ws://localhost:8080/v1');
+      // Not connected, should not throw
+      t.send({ v: 1, t: 'ping', ch: 'abc', ts: 123 } as any);
+    });
+  });
+
+  describe('receive', () => {
+    it('calls message handler on incoming messages', async () => {
+      const t = new WebSocketTransport('ws://localhost:8080/v1');
+      const handler = vi.fn();
+      t.onMessage(handler);
+
+      const promise = t.connect();
+      MockWebSocket.instances[0]!.simulateOpen();
+      await promise;
+
+      const msg = { v: 1, t: 'ready', ch: 'abc', state: 'waiting' };
+      MockWebSocket.instances[0]!.simulateMessage(JSON.stringify(msg));
+
+      expect(handler).toHaveBeenCalledWith(msg);
+    });
+
+    it('ignores malformed JSON', async () => {
+      const t = new WebSocketTransport('ws://localhost:8080/v1');
+      const handler = vi.fn();
+      t.onMessage(handler);
+
+      const promise = t.connect();
+      MockWebSocket.instances[0]!.simulateOpen();
+      await promise;
+
+      MockWebSocket.instances[0]!.simulateMessage('not json');
+      expect(handler).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('disconnect', () => {
+    it('transitions to disconnected', async () => {
+      const t = new WebSocketTransport('ws://localhost:8080/v1');
+      const promise = t.connect();
+      MockWebSocket.instances[0]!.simulateOpen();
+      await promise;
+
+      t.disconnect();
+      expect(t.state).toBe('disconnected');
+    });
+
+    it('does not call close handler on intentional disconnect', async () => {
+      const t = new WebSocketTransport('ws://localhost:8080/v1');
+      const closeHandler = vi.fn();
+      t.onClose(closeHandler);
+
+      const promise = t.connect();
+      MockWebSocket.instances[0]!.simulateOpen();
+      await promise;
+
+      t.disconnect();
+      expect(closeHandler).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('unexpected close', () => {
+    it('calls close handler on unexpected transport close', async () => {
+      const t = new WebSocketTransport('ws://localhost:8080/v1');
+      const closeHandler = vi.fn();
+      t.onClose(closeHandler);
+
+      const promise = t.connect();
+      MockWebSocket.instances[0]!.simulateOpen();
+      await promise;
+
+      // Simulate unexpected close (e.g., network drop)
+      MockWebSocket.instances[0]!.simulateClose();
+
+      expect(closeHandler).toHaveBeenCalledTimes(1);
+      expect(t.state).toBe('disconnected');
+    });
+  });
+
+  describe('setUrl', () => {
+    it('updates the URL for next connection', async () => {
+      const t = new WebSocketTransport('ws://localhost:8080/v1');
+      t.setUrl('ws://other:9090/v1');
+
+      const promise = t.connect();
+      const ws = MockWebSocket.instances[0]!;
+      expect(ws.url).toBe('ws://other:9090/v1');
+
+      ws.simulateOpen();
+      await promise;
+    });
+  });
+});

package/src/ws-transport.ts

@@ -0,0 +1,92 @@
+/**
+ * WebSocket transport for WalletPair protocol.
+ *
+ * Works in browsers, Node.js 22+, Deno, Bun — anything with a global WebSocket.
+ */
+
+import type { Transport, TransportState, ProtocolMessage } from './types.js';
+
+export interface WebSocketTransportOptions {
+  url: string;
+  protocols?: string[];
+}
+
+export class WebSocketTransport implements Transport {
+  state: TransportState = 'disconnected';
+
+  private ws: WebSocket | null = null;
+  private url: string;
+  private protocols: string[];
+
+  private messageHandler: ((msg: ProtocolMessage) => void) | null = null;
+  private closeHandler: (() => void) | null = null;
+  private openHandler: (() => void) | null = null;
+
+  constructor(options: WebSocketTransportOptions | string) {
+    if (typeof options === 'string') {
+      this.url = options;
+      this.protocols = ['walletpair.v1'];
+    } else {
+      this.url = options.url;
+      this.protocols = options.protocols ?? ['walletpair.v1'];
+    }
+  }
+
+  onMessage(handler: (msg: ProtocolMessage) => void): void { this.messageHandler = handler; }
+  onClose(handler: () => void): void { this.closeHandler = handler; }
+  onOpen(handler: () => void): void { this.openHandler = handler; }
+
+  /** Update the relay URL (useful for reconnect to a different relay). */
+  setUrl(url: string): void {
+    this.url = url;
+  }
+
+  connect(): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      this.state = 'connecting';
+      const ws = new WebSocket(this.url, this.protocols);
+
+      ws.onopen = () => {
+        this.state = 'connected';
+        this.ws = ws;
+        this.openHandler?.();
+        resolve();
+      };
+
+      ws.onmessage = (event: MessageEvent) => {
+        if (this.messageHandler) {
+          try { this.messageHandler(JSON.parse(event.data as string)); } catch { /* bad json */ }
+        }
+      };
+
+      ws.onclose = () => {
+        const wasConnected = this.state === 'connected';
+        this.state = 'disconnected';
+        this.ws = null;
+        if (wasConnected) {
+          this.closeHandler?.();
+        } else {
+          reject(new Error('WebSocket connection failed'));
+        }
+      };
+
+      ws.onerror = () => {
+        // onclose will fire after onerror, which handles the reject
+      };
+    });
+  }
+
+  send(msg: ProtocolMessage): void {
+    if (!this.ws || this.state !== 'connected') return;
+    this.ws.send(JSON.stringify(msg));
+  }
+
+  disconnect(): void {
+    if (this.ws) {
+      this.ws.onclose = null;
+      this.ws.close();
+      this.ws = null;
+    }
+    this.state = 'disconnected';
+  }
+}