channels

introduction

using cyxth you can creat simple one to one channels,many to many group channels, few to many broadcast channels and everything in between. cyxth gives you options to manage and limit channel features and users. cyxth does not offer channel discovery but there is an option to make channels public so they can be fetched using channels.list() with listPublicOnly option set to true.

all operations here are in the channels namespace i.e channels.create();

create

to create a channel use

channels.create(channel: NewChannel): Status

for example to create a channel hello one could use this.

cyxth.channels
	.create({
		id: 'hello',
		name: 'hello',
		metadata: {
			logo: 'channel_avatar.png'
		},
		users: ['id1', 'id2', 'id3', '...']
	})
	.then((status) => {
		console.log(status);
	})
	.catch((err) => {
		// handle error
	});

join or leave

To join a given channel use the channels.join() function providing the channel id. this may fail if user is blocked or users are not allowed to join the channel.

channels.join(channelId: string): Promise<{id:string}>

Similary to leave a channel.

channels.leave(channelId: string): Promise<{id:string}>

listing

To get channels for the active user use the channels.list() method. for simple channel discovery add the listPublicOnly option alongside pagination.

channels.list(pagination?: Pagination, listPublicOnly = false): Promise<{ channels: Channel[] }>

for example

cyxth.channels
	.list()
	.then((channels) => {
		console.log(channels);
	})
	.catch((err) => {
		//handle error
	});

To get more channel information such as metadata,avatar,name and more use channels.get()

channels.get(channelId: string): Promise<Channel | undefined>

members management

to get all members in a channel use channels.getMembers().

channels.getMembers(channelId: string): Promise<ChannelUser[]>

to add members use channel.addMembers(). this will fail if any of the members in a list provided does not exist, this method requires admin privilages in channel.

channels.addMembers(channelId: string, userIds: string | string[]): Status

similary to remove members use channel.removeMembers(). this method requires admin privilages in channel.

channels.removeMembers(channelId: string, userIds: string | string[]): Status

moderation

Channel moderation requires admin privilages in given channels. to moderate users use channels.moderate()

channels.moderate(channelId: string, moderation: Moderation): Status

for example to block 3 users

cyxth.channels.moderate('channel_id', {
	mode: 'block',
	users: ['alice', 'bob', 'cyx']
});

message history

to get activity and messages in a channel use channels.getMessages() function

getMessages(
	start: Date | string,
	limit: number = 50,
	channels: undefined | string | string[] = undefined,
	direction: 'reverse' | 'forward' = 'forward'
): Promise<{ [key: string]: Message[] }>

examples

// using an id only
cyxth.channnels
	.getMessages('7085164563653595136')
	.then((messages) => {
		console.log(messages);
	})
	.catch((err) => console.error(err));

// using id and limit, 150 is max at once
cyxth.channnels
	.getMessages('7085164563653595136', 150)
	.then((messages) => {
		console.log(messages);
	})
	.catch((err) => console.error(err));

// use date instead
let date = new Date();
cyxth.channnels
	.getMessages(date)
	.then((messages) => {
		console.log(messages);
	})
	.catch((err) => console.error(err));

This is particulary useful when combined with offline mode. where users can get updates of messages when they were offline or disconnected.

update and delete

you can also update and delete channels using channels.update() and channels.delete() functions respectively. these operations can only be carried out by channel creator or admin in channel.

update

.update(channel: Channel): Status

delete

.delete(channelId: string): Status

events

all activities carried out in any given channel are reported by listening on the activity event these notifies users when they’ve been added to a channel, blocked, made admins … etc. activity can be configured for a given channel or instance wide

cyxth.on('activity', (activity: Activity) => {
	// do sth
});

to get messages in a channel

cyxth.on('message', (message: Message) => {
	// do sth
});

types

auto generated types related to channels

export declare class Channels {
	create(channel: NewChannel): Status;

	get(channelId: string): Promise<Channel | undefined>;

	delete(channelId: string): Status;

	update(channel: Channel): Status;

	join(channelId: string): Promise<{
		id: string;
	}>;

	leave(channelId: string): Promise<{
		id: string;
	}>;

	getMembers(channelId: string): Promise<ChannelUser[]>;

	addMembers(channelId: string, userIds: string | string[]): Status;

	removeMembers(channelId: string, userIds: string | string[]): Status;

	moderate(channelId: string, moderation: Moderation): Status;

	getMessages(
		start: Date | string,
		limit?: number,
		channels?: undefined | string | string[],
		direction?: 'reverse' | 'forward'
	): Promise<{
		[key: string]: Message[];
	}>;

	list(
		pagination?: Pagination,
		listPublicOnly?: boolean
	): Promise<{
		channels: Channel[];
	}>;
}

type ModerationType = 'block' | 'unblock' | 'make_admin' | 'revoke_admin';

interface Moderation {
	mode: ModerationType;
	users: string | string[];
}

interface Channel {
	id: string;
	name: string;
	metadata: {
		logo?: string;
		about?: string;
	};
}

interface NewChannel extends Channel {
	users?: string[];
}

interface Pagination {
	starting_after: string;
	limit: number;
}

interface ChannelUser {
	id: string;
	name: string;
	mode: number;
}

type Status = Promise<{
	status: number;
}>;

interface Message {
	userId: string;
	channelId: string;
	messageId: string;
	content: MessageContent;
	timestamp: Date;
	type: 'activity' | 'message' | 'private';
	activity?: ChannelActivity;
}

interface ChannelActivity {
	event: 'join' | 'leave' | 'create' | string;
	scope: 'channel' | string;
	sender: string;
	data?: any;
}

interface MessageContent {
	text?: string;
	media?: any;
	meta?: string;
}