Socket Types - CollabKit

import type {
  CollabKitRole,
  SocketClientEventMap,
  SocketState,
  SocketClientOptions,
  SocketMessageResponseMap,
  InferResponseData,
} from '@collab-kit/utils';

CollabKitRole

Session-scoped role chosen at join time or changed with client.updateRole(...).

type CollabKitRole = 'editor' | 'viewer';

SocketClientEventMap

Event map for client.socket.on() listeners.

interface SocketClientEventMap {
  connected: void;
  disconnected: { code: number; reason: string };
  reconnecting: { attempt: number };
  reconnected: void;
  failed: void;
  authFailed: Error;
}

SocketState

Possible connection states.

type SocketState =
  | 'connected'
  | 'connecting'
  | 'disconnected'
  | 'reconnected'
  | 'errored'
  | 'reconnecting'
  | 'reconnectFailure'
  | 'failed'
  | 'idle';

SocketClientOptions

Options for the low-level socket client.

interface SocketClientOptions {
  url: string;
  authToken: string;
  reconnection?: {
    enabled: boolean;
    maxAttempts: number;
    initialDelay: number;
    maxDelay: number;
    backoffFactor: number;
  };
}

SocketMessageResponseMap

Maps each client request MessageType to the data shape of its corresponding server response. Used by sendMessagePromise to infer the response type from the request type at compile time.

Note: CollabKitUser objects in WebSocket responses have token, room_id, and created_at stripped for payload efficiency and security. These fields are only present in REST API responses.

interface SocketMessageResponseMap {
  [MessageType.UPDATE_USER]: { user: CollabKitUser };
  [MessageType.DELETE_USER]: { user: CollabKitUser };
  [MessageType.GET_USER]: { user: CollabKitUser };
  [MessageType.GET_USERS]: { users: CollabKitUser[] };
  [MessageType.JOIN_ROOM]: {
    room: CollabKitRoom;
    currentUser: CollabKitUser;
    activeUsers: CollabKitUser[];
    role: CollabKitRole;
  };
  [MessageType.UPDATE_ROLE]: { role: CollabKitRole };
  [MessageType.GET_ROOM]: { room: CollabKitRoom; users: CollabKitUser[] };
  [MessageType.BROADCAST_MESSAGE]: BroadcastPayload;
  [MessageType.STORE_GET]: { key: string; value: Record<string, any> | null };
  [MessageType.STORE_GET_ALL]: { entries: Array<{ key: string; value: Record<string, any> }> };
  [MessageType.STORE_SET]: { key: string; value: Record<string, any> };
  [MessageType.STORE_UPDATE]: { key: string; value: Record<string, any> };
  [MessageType.STORE_DELETE]: { key: string };
  [MessageType.COMMENT_ADD]: { comment: CollabKitComment };
  [MessageType.COMMENT_DELETE]: { commentId: string };
  [MessageType.COMMENT_GET_ALL]: { comments: CollabKitComment[] };
  // ... and more for reactions, tags, CRDT, follow/unfollow
}

Broadcast Message Types

The server sends batched broadcast messages to connected clients when editors become active or inactive:

interface UserJoinedBatchBroadcast {
  type: MessageType.USER_JOINED_BATCH;   // 'userJoinedBatch'
  data: { users: CollabKitUser[] };
}

interface UserLeftBatchBroadcast {
  type: MessageType.USER_LEFT_BATCH;     // 'userLeftBatch'
  data: { users: CollabKitUser[] };
}

Join and leave events are batched over a short window to reduce message volume under high concurrency. Viewer joins/leaves are not broadcast. The client SDK handles these transparently and emits individual userJoined / userLeft events per active editor.

InferResponseData

Helper type that infers the response data type for a given client message. Falls back to Record<string, any> for unrecognised message types.

type InferResponseData<T extends SocketClientMessage> =
  T extends { type: infer M extends keyof SocketMessageResponseMap }
    ? SocketMessageResponseMap[M]
    : Record<string, any>;

This enables type-safe responses from sendMessagePromise without manual casts:

// The response data type is automatically inferred from the message type
const response = await socket.sendMessagePromise({
  type: MessageType.COMMENT_ADD,
  text: 'Hello',
});
// response.data is typed as { comment: CollabKitComment }

​CollabKitRole

​SocketClientEventMap

​SocketState

​SocketClientOptions

​SocketMessageResponseMap

​Broadcast Message Types

​InferResponseData