Room

The Room module in ZDK primarily handles user entry and exits from rooms. Acting as a foundational layer, it can be enhanced with additional modules to bring in diverse functionalities specific to the room’s purpose. Users have the flexibility to choose which modules to integrate based on their needs. For instance:

• Incorporating the Chats module will empower users to exchange text messages within the room.
• Integrating the Conference module allows participants to engage in video calls while in the room.

For those looking to maximize their room capabilities, both modules can be used concurrently, offering a comprehensive communication experience that encompasses messaging and video conferencing.

• core
• user
• websocket
• conference (Optional)

Initialization

const room = new createRoom({
 webSocketModule: webSocket,
 userModule: user,
 config: {
   host: 'room.dev.zu.casa'
 }
});

Actions

joinRoom

(token: string) => Promise<void>

It gives the client the possibility to join to selected room and connect to media server. Joining room affects following data: status and members.

• token - a short-lived, server-issued token created on request that encodes the user’s permissions for the specific room they’re joining.

Returns a promise that resolves once the user entered the room.

• ActionCallError - Can not perform this action (joinRoom) while module is not connected with WebSocket.
• ActionCallError - Invalid token.
• ActionCallError - Expired token.
• ActionCallError - You’ve already joined a room
• other error types may occur, the list will be expanded during development

leaveRoom

() => void

Removes user from the room. It automatically clears the state of the room e.g. by removing all room members or setting roomModule status to disconnected.

• ActionCallError - Can not perform this action (leaveRoom) while module is not connected with WebSocket
• ActionCallError - Can not perform this action (leaveRoom) because you are not in any room.
• other error types may occur, the list will be expanded during development

sendCustomRoomPacket

(name: string, data: { [key: string]: string }) => Promise<void>

Description Sends custom packet to server. The packet will be broadcast to all users in the room (including the sender).

• name - name of the custom room packet. You can name it so that later it will be easier to distinguish between different types of custom packets.
• data - any data that you want tp transport by custom packet.

Returns a promise that resolves when request is successfully sent - after that the packet will be sent to each member in the room.

• ActionCallError - Can not perform this action (sendCustomRoomPacket) while module is not connected with WebSocket.
• ActionCallError - Can not perform this action (sendCustomRoomPacket) because you did not join any room.
• other error types may occur, the list will be expanded during development

kickMember

(userId: string, reason?: string) => Promise<void>

Description Kicks the targeted user from the current room.

• userId - id of the targeted user
• reason - cause for removing someone from a room

Returns a promise that resolves when request is successfully sent.

• ActionCallError - Can not perform this action (kickMember) while module is not connected with WebSocket.
• ActionCallError - Can not perform this action (kickMember) because you did not join any room.
• ActionCallError - Can not perform this action (kickMember) on yourself.
• other error types may occur, the list will be expanded during development

blockMember

(userId: string, duration: bigint, reason?: string) => Promise<void>

Description Blocks the targeted user, establishing a restriction that prevents the user from entering the current room, and if the user is currently in the room, they will be kicked out immediately. Parameters

• userId - id of the targeted user
• duration - time in minutes the block remains active; 0 implies a permanent block
• reason - cause for blocking user

Returns a promise that resolves when request is successfully sent.

• ActionCallError - Can not perform this action (blockMember) while module is not connected with WebSocket.
• ActionCallError - Can not perform this action (blockMember) because you did not join any room.
• ActionCallError - Can not perform this action (blockMember) on yourself.
• other error types may occur, the list will be expanded during development

unblockMember

(userId: string) => Promise<void>

Description Removes the block on the targeted user, allowing entry to the room again. If the user was removed, they can now rejoin. Parameters

• userId - id of the targeted user

Returns a promise that resolves when request is successfully sent.

• ActionCallError - Can not perform this action (unblockMember) while module is not connected with WebSocket.
• ActionCallError - Can not perform this action (unblockMember) because you did not join any room.
• ActionCallError - Can not perform this action (unblockMember) on yourself.
• ActionCallError - Can not perform this action (unblockMember) on member which is not blocked.
• other error types may occur, the list will be expanded during development

Data (Getters)

status

Getter output type: 'disconnected' | 'connecting' | 'connected' | 'reloading'

• disconnected - not connected to any room
• connecting - trying to connect to selected room
• connected - connected and data about the room and its members are available - ready to room UI
• reloading - because of connection lost, the room state can be temporarily desynchronized, this state appear after we are trying to synchronize all the data again. You can still show the user the whole room UI based on old data, but you can inform him that we are ‘reloading’ it and soon user will be fully connected.

chatId

Getter output type: string | undefined

Gives access to chatId associated with the room.
If the client did not enter any room, undefined will be returned.

roomId

Getter output type: string | undefined

Gives access to roomId of the current room.
If the client did not enter any room, undefined will be returned.

members

Getter output type: Member[]

Gives access to list of members in the room.
If the client did not enter any room, empty list will be returned.

membersAmount

Getter output type: number

Gives access to a number that represents the amount of users in the room.
If the client did not enter any room, 0 will be returned.

membersIds

Getter output type: string[]

Gives access to list of ids of users that are in the room.
If the client did not enter any room, empty list will be returned.

blockedMembersIds

Getter output type: string[]

Provides a list of user ids with restricted room access.
If the client did not enter any room, empty list will be returned.

capacity

Getter output type: bigint | undefined

The “capacity” getter indicates the maximum number of users allowed in a room.
It returns a numerical value (bigint) or is undefined if no specific limit is set.

isRoomSyncing

Getter output type: boolean

This value give you information if some of the data are incorrect in the state, and we are fixing it. The state might be inaccurate at the moment for example a missing member. It happens after connecting or reloading. When fetching room state will be interrupted by a websocket packet. If it is true you can show in UI a status that says that state is syncing or do nothing.
If the client did not enter any room, false will be returned.

Events

The module provides the following ListenerCreator:

onUserEntered

{member: Member}

The method sets up a function that will be called whenever a user enters the room which we are in.

onUserLeft

{member: Member}

The method sets up a function that will be called whenever a user leaves the room which we are in.

onCustomRoomPacket

{ userId: string, name: string, data: { [key: string]: string; } }

The method sets up a function that will be called whenever a user from the room (which we are in) send the custom room packet.

onUserKicked

{ userId: string, roomId: string, reason: string}

The method sets up a function that will be called whenever any user from the room (including you) is kicked from the room.

Types

Member

export interface Member {
  /**
   * Represents the unique identifier for this member.
   */
  id: string;
  /**
   * Represents the unique identifier of the user associated with this member.
   */
  userId: string;
  /**
   * Represents the unique identifier of the room in which this member exists.
   */
  roomId: string;
  /**
   * Represents a collection of key-value pairs providing additional context or information about this member.
   */
  metadata: {
    [key: string]: string;
  };
  /**
   * Represents the timestamp indicating when this member was created or added to the room.
   */
  createTime: bigint;
  /**
   * Represents the timestamp of the last update associated with this member.
   */
  updateTime: bigint;
}