@iamqc/cc-communication

CC WebSocket — WebSocket integration tools

Provides WebSocket communication between cc-session / cc-json-parser and frontend clients.

Project structure

src/
├── websocket-bridge.ts   # CCWebSocket (public API: start, stop, send, sendToClient)
├── websocket-server.ts   # IWebSocketServer interface + BunServerAdapter
├── client-registry.ts    # IClientRegistry interface + ClientRegistry
├── message-codec.ts      # IMessageCodec interface + MessageCodec
└── test/
    ├── usage-example.ts  # Usage examples
    └── test-client.html  # Browser test client

Architecture

CCWebSocket          ← public API
  ├── BunServerAdapter     (transport — Bun.serve)
  ├── ClientRegistry       (client state)
  └── MessageCodec         (JSON wire protocol)

Each module implements a focused interface — swappable without touching the rest.

Install

bun add cc-communication

Quick start

import { CCWebSocket } from 'cc-communication';

const ws = new CCWebSocket({ port: 3001 });

ws.setHandlers({
  onClientConnect: (clientId) => console.log('connected', clientId),
  onCustomMessage: (type, data, clientId) => {
    if (type === 'chat') {
      ws.sendToClient(clientId, { reply: `got: ${data.message}` }, 'chat_reply');
    }
  },
});

await ws.start();

// Broadcast to all clients
ws.send({ event: 'session_update' }, 'session');

API

CCWebSocket

Method	Description
start()	Start WebSocket server
stop()	Stop server and close all connections
send(data, type?)	Broadcast to all connected clients
sendToClient(clientId, data, type?)	Send to a specific client
getStatus()	Returns { isRunning, connectedClients, port, host }
setHandlers(handlers)	Update event handlers

Event handlers

ws.setHandlers({
  onClientConnect: (clientId) => {},
  onClientDisconnect: (clientId) => {},
  onMessage: (message) => {},       // all inbound messages
  onCustomMessage: (type, data, clientId) => {}, // by type
});

Client message shape

{
  type: string;
  data: any;
  timestamp: number;
  clientId: string;
}

Built-in protocol

Inbound type	Server response
ping	auto-replies pong
invalid JSON	replies error

Module interfaces

These are exported for testing and alternative adapters:

• IWebSocketServer — start(), stop(), isRunning — transport seam
• IClientRegistry — add(), remove(), get(), isConnected(), broadcast() — client state seam
• IMessageCodec — encode(), decode(), encodeConnected(), encodePong(), encodeError() — protocol seam

Test

bun run example          # start server
# Open src/test/test-client.html in browser