> ## Documentation Index
> Fetch the complete documentation index at: https://docs.collab-kit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Socket Types

> Types for WebSocket connection state and lifecycle events.

```typescript theme={null}
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(...)`.

```typescript theme={null}
type CollabKitRole = 'editor' | 'viewer';
```

## SocketClientEventMap

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

```typescript theme={null}
interface SocketClientEventMap {
  connected: void;
  disconnected: { code: number; reason: string };
  reconnecting: { attempt: number };
  reconnected: void;
  failed: void;
  authFailed: Error;
}
```

## SocketState

Possible connection states.

```typescript theme={null}
type SocketState =
  | 'connected'
  | 'connecting'
  | 'disconnected'
  | 'reconnected'
  | 'errored'
  | 'reconnecting'
  | 'reconnectFailure'
  | 'failed'
  | 'idle';
```

## SocketClientOptions

Options for the low-level socket client.

```typescript theme={null}
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.

```typescript theme={null}
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:

```typescript theme={null}
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.

```typescript theme={null}
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:

```typescript theme={null}
// 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 }
```