channels

the fundamental abstraction of cyxth is the channel. it offers a uniform way to manage users, configure channels and listen for common events and that occur within channels. this guide takes you through how you can easily manage your channels and users in them across chat, calls and colab.

basically channels have users. users in channels have various permissions to perform various actions. when user perform an action it may trigger an event that is sent to all user in the channel according to the channels’s configuration. you will be seeing these concepts in every cyxth module.

lets take an example of joining a given channel by using the join(channel) action. this event will trigger the user:join event. depending on the channel configuration on who receives the join event. it will be sent to users who can receive the event. if the channel has a joinRequest config set to true. a channel admin has to approve the join request.

check our excellent channel api reference for more information and examples

user

a channel user contains an id, permission and channel local data. the user has to be an authorized user. channel local data contains small info of the user specific to the channel which can only be edited by the user.

interface ChannelUser {
 id: string;
 lData: string;
 mode: ChannelUserPermission;
}

permissions

users have 4 basic permission flags to access a resource (colab, chat or calls) in channel.

enum PERM {
 // can manage users and configure channel
 ADMIN = 4,
 // can write to channel
 EDITOR = 2,
 // can only view channel and recieve updates
 VIEWER = 1,
 // user has no access
 NO_ACCESS = 0
}

by default all users have edit and view permissions only unless configured other wise. There can only be one owner who is also the creator of the channel. the owner has the special permission to delete the channel.

channel admins can add users, remove users, moderate users and configure the channels. editors can modify a given resource for example, in calls they can send video and audio, in colab they can change the colab state and in chat they can send messages. viewers can only receive messages and view channel without editing the channel. no access means a user is blocked and can’t receive events nor view the channel info and users.

combining any of the flags gives you the flexibility to manage user actions in the channel efficiently i.e you can create custom permissions using the bitwise or | operation as shown below.

let admin = PERM.ADMIN | PERM.EDITOR | PERM.VIEWER;
// admin = 4 | 2 | 1 => 7
let default = PERM.EDITOR | PERM.VIEWER
// default = 2 | 1 => 3
let viewer = PERM.VIEWER // 1
let blocked = PERM.NO_ACCESS // 0

actions

users can perform various actions in a channel, this is a uniform interface for chat, calls and colab. these actions emit various events on the channel which are received by users in channel following the channel’s config. actions can also be configured to be taken by users with specific permissions. again check out the channel reference for a more indepth info.

create

create a new channel. using a channel id and optional channel configuration and initial users

create(
    id: string, 
    initialUsers?: ChannelUser[], 
    config?: ChannelConfig
): Promise<Status>;

emits cnl:create

info

get channel info

info(id: string): Promise<channelInfo>;

delete

delete a channel. only the owner or last admin can delete a channel

delete(id: string, reason: string): Promise<Status>;

emits cnl:del event

list

list channels. by default returns only channels user has joined. adding a publicOnly flag. returns all channels marked as discovarable

list(publicOnly?: boolean, pagination?: Pagination): Promise<ChannelInfo[]>;

join

join a channel

join(id: string): Promise<Status>;

emits user:join event

leave

leave a channel

leave(id: string): Promise<Status>;

emits user:left event

addUsers

add users to channel. this method will fail with NotExist if any of the users added are not registered or authorized users.

addUsers(id: string, users: ChannelUser | ChannelUser[]): Promise<Status>;

emits user:add event

delUsers

delete users disconnecting them from the given resource.

delUsers(id: string, users: string | string[], reason?: string): Promise<Status>;

emits user:del event.

getUsers

get channel users. in calls and colab will always return active users

getUsers(id: string, activeOnly?: boolean, pagination?: Pagination): Promise<Status>;

optionaly emits cnl:scan event.

moderate

moderate channel user i.e block user or make user an admin. this method will fail with NotExist if any of the users added are not registered or authorized users.

moderate(id: string, users: ChannelUser): Promise<Status>;

emits user:mod

configure

change the channel configuration

configure(id: string, config: ChannelConfig): Promise<Status>;

emits cnl:config

events

various channel actions also emit events. these events can be configured to be visible by users with specific permissions for examplecnl:config config can be set to be seen by only channel admins. or the user:left to allow users to leave privately. here is a high level overview, again check the api reference for each of these events

interface ChannelEventMap {
 'cnl:config': ChannelConfigEvent;
 'cnl:create': ChannelCreateEvent;
 'cnl:delete': ChannelDeleteEvent;
 'user:join': ChannelUpdateEvent;
 'user:left': ChannelUpdateEvent;
 'user:add': ChannelUpdateEvent;
 'user:del': ChannelUpdateEvent;
 'user:mod': ChannelUpdateEvent;
}

configuration

channel configuration

interface ChannelConfig {
 // for public listings
 public: boolean;
 // events and associated permissions
 eventMap: ChannelEventUserMap;
 // actions and associated permissions
 actionMap: ChannelActionMap;
 // join request
 joinRequest: boolean;
 // default permission
 defaultPermission: number;
}

summary

this channel actions, events and configuration cuts across all the cyxth modules. it should also be noted that various modules have their own unique events, configurations and actions. through out these series of guides we will be focusing on the specific resource actions, events and config, feel free to come back here for reference or the channel api reference.