Skip to content

Latest commit

 

History

History
165 lines (147 loc) · 12.8 KB

README.md

File metadata and controls

165 lines (147 loc) · 12.8 KB
Raw

wschatapi

API для написания своих клиентов к чату https://chat.sinair.ru/

Установка

Для использования в nodejs:

npm install @iassasin/wschatapi ws

Для использования в браузере:

npm install @iassasin/wschatapi

Быстрый старт

const {WsChat, WsChatEvents} = require('@iassasin/wschatapi');

// в async функции:
let chat = new WsChat('wss://sinair.ru/ws/chat');
await chat.open();

chat.on(WsChatEvents.message, async (room, message) => {
	if (message.message === 'Пока') {
		room.sendMessage('Пока!');
		await chat.close();
	}
});

let room = await chat.joinRoom('#test');
room.sendMessage('/nick testbot');
room.sendMessage('Привет, я бот!');

Методы API

В API используются два класса, доступные пользователю:

  • WsChat - основной класс подключения и обработки событий;
  • Room - класс подключения к конкретной комнате, его нельзя инстанцировать вручную, но к нему появляется доступ после подключения к комнате.

Также доступны несколько перечислений, которые удобно применять при использовании API:

  • WsChatEvents - доступные для подписки события клиента чата;
  • MessageStyle - стиль сообщения в чате;
  • ErrorCode - код ошибки, которую можно получить в результате некоторых операций;
  • UserStatus - возможные статусы пользователя.

WsChat

Представляет собой набор управляющих методов и событий.

Большая часть методов возвращает Promise, который разрешается в момент успешного завершения операции, либо отклоняется с объектом ошибки. Если ошибка возникла не в результате вызова подобного метода, то она уходит обработчику события error.

Доступные методы:

  • new WsChat(address: string) - конструктор класса, address - адрес websocket-сервера чата, например wss://sinair.ru/ws/chat;
  • open(): Promise<void> - установить соединение с сервером;
  • close(): Promise<void> - закрыть соединение с сервером;
  • authByApiKey(key: string): Promise<PacketAuth> - выполнить авторизацию на сервере с помощью постоянного API-ключа (получается в профиле на сайте, рекомендуется для ботов);
  • authByLoginAndPassword(login: string, password: string): Promise<PacketAuth> - (более не поддерживается) выполнить авторизацию на сервере с помощью логина и пароля;
  • restoreConnection(token: string): Promise<PacketAuth> - восстанавливает соединение по токену, полученному ранее через другие методы аутентификации. При этом происходит автоматическое подключение ко всем комнатам прошлого соединения (придут события joinRoom как при подключении к комнате);
  • changeStatus(status: UserStatus): void - изменить свой статус. Допустимы только значения UserStatus.away и UserStatus.back;
  • joinRoom(target: string, options?: JoinOptions): Promise<Room> - присоединиться к комнате target. Также можно передать объект опций. Опции по-умолчанию следующие:
{
	autoLogin: false, //автоматически войти в комнату с ником, который использовался в ней ранее (для авторизованных пользователей)
	loadHistory: false, //загрузить последние 50+ сообщений в комнате
}
  • leaveRoom(target: string): Promise<string> - покинуть комнату target;
  • createRoom(target: string): Promise<string> - создать комнату с именем target;
  • removeRoom(target: string): Promise<string> - удалить свою комнату с именем target;
  • getRoomByTarget(target: string): Room - найти комнату с именем target в списке подключенных.

Доступные свойства:

  • rooms: Room[] - список комнат, к которым подключен клиент;
  • connected: boolean - возвращает true, если подключение к серверу установлено, иначе false.

События (WsChatEvents):

  • open - вызывается после подключения к серверу;
  • close - вызывается после отключения от сервера;
  • connectionError(error) - вызывается при возникновении ошибки подключения;
  • error(error) - вызывается для необработанных ошибок при работе с API чата;
  • message(room, msgobj) - вызывается, когда кто-то написал сообщение в комнату. msgobj - объект сообщения (будет описан ниже);
  • sysMessage(room, text) - вызывается при получении системного сообщения. Когда сообщение не относится ни к одной комнате, room принимает значение null;
  • userStatusChanged(room, userobj) - вызывается при изменении статуса пользователя в комнате; userobj - объект информации о пользователе (будет описан ниже);
  • joinRoom(room) - вызывается после подключения к комнате, если подключение было вызвано не методом chat.joinRoom(). Например, после восстановления соединения методом restoreConnection;
  • leaveRoom(target) - вызывается после исключения из комнаты; target - имя комнаты.

Room

Класс, предоставляющий набор методов для конкретной комнаты.

Методы:

  • sendMessage(text: string) - отправить сообщение в комнату;
  • changeStatus(status: UserStatus) - изменить свой статус. Допустимы только следующие значения UserStatus: away, back, typing, stop_typing;
  • getMemberById(memberId: number) - получить инфо пользователя по его id.

Свойства:

  • target: string - кодовое имя комнаты, например #chat;
  • members: UserObject[] - список подключенных к комнате пользователей;
  • memberId: number - собственный комнатный id в рамках текущего подключения к комнате;
  • memberNick: string - собственный ник в комнате.

UserStatus

Перечисление всех возможных статусов пользователей:

  • bad - если вы получили такой статус, что-то точно пошло не так;
  • offline - пользователь отключился;
  • online - пользователь онлайн;
  • away - пользователь отошел;
  • nick_change - пользователь изменил ник;
  • gender_change - пользователь сменил пол;
  • color_change - пользователь перекрасил ник;
  • back - пользователь вернулся (после статуса away);
  • typing - пользователь начал набирать сообщение;
  • stop_typing - пользователь перестал набирать сообщение;
  • orphan - пользователь потерял соединение с чатом, но еще может восстановить его.

MessageStyle

Перечисления для определения типа присланного сообщения:

  • message - обычное сообщение;
  • me - сообщение о себе в третьем лице;
  • event - сообщение от третьего лица;
  • offtop - оффтоп (в чате выделяются серым).

ErrorCode

Перечисление типа возникшей ошибки.

  • unknown - незивестная ошибка;
  • database_error - ошибка соединения с базой данных;
  • already_connected - вы уже подключены (например, к комнате);
  • not_found - при запросе что-то было не найдено (например, комната с таким именем);
  • access_denied - доступ запрещен;
  • invalid_target - неверно задано имя комнаты;
  • already_exists - что-то уже существует (например, комната с таким именем);
  • incorrect_loginpass - неверный логин/пароль (при авторизации);
  • user_banned - ваш пользователь или все анонимные пользователи заблокированы в комнате.

PackType

Перечисления типа пакета. Может использоваться при обработке ошибок.

  • error - сообщение об ошибке;
  • system - системное сообщение;
  • message - сообщение;
  • online_list - запрос список онлайна;
  • auth - запрос авторизации;
  • status - информация о пользователе;
  • join - запрос на подключение к комнате;
  • leave - запрос на отключение от комнаты;
  • create_room - запрос на создание комнаты;
  • remove_room - запрос на удаление комнаты;
  • ping - служебный пакет для проверки связи.

Объект сообщения (MessageObject)

  • id (string?) - необязательное поле. id сообщения, присутствует только у публичных сообщений (в лс отсутствует).
  • color (string) - цвет никнейма отправителя сообщения;
  • from (int) - внутрикомнатный ID отправителя сообщения;
  • from_login (string) - никнейм отправителя сообщения;
  • message (string) - текст сообщения;
  • style (MessageStyle) - тип сообщения;
  • target (string) - название комнаты, в которую было отправлено сообщение;
  • time (long) - время отправки сообщения в формате unixtime;
  • to (int) - внутрикомнатный ID получателя сообщения (0, если сообщение публичное).

Объект информации о пользователе (UserObject)

  • color (string) - цвет никнейма пользователя;
  • data (string) - данные события (например, при смене никнейма содержит старый никнейм пользователя);
  • girl (bool) - имеет ли пользователь имеет женский пол;
  • is_moder (bool) - является ли пользователь модератором комнаты;
  • is_owner (bool) - является ли пользователь создателем комнаты;
  • member_id (int) - внутрикомнатный ID пользователя;
  • name (string) - никнейм пользователя;
  • status (UserStatus) - статус пользователя (UserStatus);
  • user_id (int) - ID аккаунта пользователя (0, если пользователь не авторизирован);
  • last_seen_time (long) - время последнего присутствия пользователя (время перехода в статус away) в формате unixtime.