Client

Client 

import Client from "https://designftw.github.io/chat-lib/src/Client.js";

The Client is the interface for interacting with the ChatServer.

Constructor

# new Client(host)

Client constructor.

Parameters:
Name Type Description
host string

see Client's host property
Source:
Fires:

Members

# account :Account|undefined

The logged in client account. Set in login and unset in logout.

Type:
Source:

# host :string

The host of the chat server. Includes the hostname and port. For example https://mozilla.org:4000. Read-only.

See https://developer.mozilla.org/en-US/docs/Web/API/URL/host

Type:
  • string
Source:

Methods

# addFriend(friendHandle, options) → {Promise.<any>}

Add a new friend to the friend list of the passed in handle.

Parameters:
Name Type Description
friendHandle string

the handle which is going to be added to ownAlias's friend list.
options Object
Properties
Name Type Attributes Description
ownHandle string <optional>

the handle adding a friend.
Source:
Returns:

a validation message.

Type
Promise.<any>

# createIdentity(options) → {Promise.<Identity>}

Create a new identity with the passed in handle and data.

Parameters:
Name Type Description
options Object
Properties
Name Type Attributes Description
handle string

the name of the new handle
data Object <optional>

the data to associate with the handle
Source:
Returns:

The Identity object that corresponds to the new handle

Type
Promise.<Identity>

# createPrivateData(options) → {Promise.<PrivateData>}

Create a new private data for the passed in entity, private to the passed in handle.

Parameters:
Name Type Description
options Object
Properties
Name Type Description
handle string

the handle which is creating the data.
entityId string

the id of the entity (Message, Alias, or Account) the data is attached to.
data Object

the data to attach to the entity associated with the passed in entityId, private to the handle associated with the passed in handle.
Source:
Returns:

the new private data.

Type
Promise.<PrivateData>

# deleteIdentity(handle) → {Promise.<any>}

Delete the identity associated with the passed in handle name.

Parameters:
Name Type Description
handle string

the handle to delete.
Source:
Returns:

A validation message.

Type
Promise.<any>

# deleteMessage(message, optionsopt) → {Promise.<any>}

Delete a message with the passed in messageId which was sent by the passed in handle.

Parameters:
Name Type Attributes Description
message Message | string

Message object or message id
options Object <optional>
Properties
Name Type Attributes Description
handle string <optional>

the handle which sent the message.
Source:
Returns:

a validation message.

Type
Promise.<any>

# deletePrivateData(options) → {Promise.<any>}

Delete the private data associated with the passed in handle and entity.

Parameters:
Name Type Description
options Object
Properties
Name Type Description
handle string

the handle associated with the data to delete.
entityId string

the id of the entity (Message, Alias, or Account) the data to delete is attached to.
Source:
Returns:

A validation message.

Type
Promise.<any>

# getFriends(handle) → {Promise.<Array.<Identity>>}

Get all the friends of the passed in handle.

Parameters:
Name Type Description
handle string

the handle whose friends will be retrieved.
Source:
Returns:

an array of handles. These are the passed in handle's friends.

Type
Promise.<Array.<Identity>>

# (async) getIdentities() → {Promise.<Array.<Identity>>}

Get all the handles for the currently logged in account.

Source:
Returns:

An array of Alias models.

Type
Promise.<Array.<Identity>>

# (async) getIdentity(handle) → {Promise.<Identity>}

Get an identity by its handle. If an Identity object is passed in, it will just be returned. This way this function can be used to normalize a handle | Identity object into an Identity object.

Parameters:
Name Type Description
handle string | Identity

the handle to get
Source:
Returns:

The Alias model associated with the passed in name

Type
Promise.<Identity>

# (async) getLoggedInAccount() → {Promise.<(Account|null)>}

Check if the user is currently logged in

Source:
Returns:

Returns the account if the user is logged in, otherwise returns undefined.

Type
Promise.<(Account|null)>

# getMessageById(messageId, options) → {Promise.<Message>}

Get a message object for a message id or Get a message which has the passed in messageId, and was sent or received by the passed in handle.

Note the currently logged in account must own the handle associated with the handle.

Parameters:
Name Type Description
messageId

The id of the message to get.
options Object
Properties
Name Type Attributes Description
handle string <optional>

the handle which sent or received the message, as an optional safeguard against race conditions.
Source:
Returns:

The model of the message with the associated id.

Type
Promise.<Message>

# (async) getMessages(options) → {Promise.<Array.<Message>>}

Get an array of all messages that match the provided filters (see below). Note that regardless of the filters provided, only messages the currently logged in account has access to will be returned.

Parameters:
Name Type Description
options Object
Properties
Name Type Attributes Default Description
from string | Identity | Array.<string> | Array.<Identity> <optional>

Sender(s) of the messages, either as handle(s) or Identity object(s)
to string | Identity | Array.<string> | Array.<Identity> <optional>

Recipient(s) of the messages, either as handle(s) or Identity object(s)
participants string | Identity | Array.<string> | Array.<Identity> <optional>

Senders OR recipient(s) of the messages, either as handle(s) or Identity object(s)
since Date <optional>

an optional date to limit the request by. only receive messages since this date.
match "any" | "all" | "exact" <optional>
 "any"

The policy to use when filtering messages by sender, recipient or participants.

  • "any" would return messages with any of the parties specified
  • "all" would return messages with all of the parties specified (but more are possible)
  • "exact" would return messages with the exact parties specified
exact boolean <optional>
 false

Deprecated. Please use match instead. Do we want to return messages that match the to and participants params exactly, or messages that contain at least one handle in each of these arrays? E.g. if we specify to: ["A", "B"], do we want messages sent to either A, or B, or both, or both plus some other people, or messages sent to exactly A and B?
Source:
Returns:

a list of messages which pass the filters.

Type
Promise.<Array.<Message>>

# getPrivateData(options) → {Promise.<PrivateData>}

Get the private data associated with the passed in handle and entity.

Parameters:
Name Type Description
options Object
Properties
Name Type Description
handle string

the handle associated with the data to get.
entityId string

the id of the entity (Message, Alias, or Account) the data to get is attached to.
Source:
Returns:

the private data associated with the passed in handle and entity.

Type
Promise.<PrivateData>

# groupMessagesByUniqueRecipients(messages) → {Array.<Array.<Message>>}

Given an array of Messages group the messages by unique groups of sender and recipient handles. For example if Alice sends Bob a message and Bob sends Alice a message both of those messages are in the same group since the set of sender and recipient handles contains {Alice, Bob} for each message.

Parameters:
Name Type Description
messages Array.<Message>

the messages to group by unique groups of senders and recipients.
Source:
Returns:

an array where each element is a set of messages with a unique set of senders and recipients.

Type
Array.<Array.<Message>>

# (async) login(email, password) → {Promise.<Account>}

Login to an existing account.

Parameters:
Name Type Description
email string

The email address associated with the account.
password string

The password associated with the account.
Source:
Returns:

Upon success returns the account which was logged in.

Type
Promise.<Account>

# (async) logout()

Logout of an existing account

Source:

# removeFriend(friendHandle, options) → {Promise.<any>}

Remove a friend from the friend list of the passed in handle.

Parameters:
Name Type Description
friendHandle string

the handle which is going to be removed from ownAlias's friend list.
options Object
Properties
Name Type Attributes Description
ownHandle string <optional>

the handle removing a friend.
Source:
Returns:

a validation message.

Type
Promise.<any>

# sendMessage(options) → {Promise.<Message>}

Send a message from the passed in handle to the passed in recipients with the passed in data.

Note the currently logged in account must own the handle associated with the handle.

Parameters:
Name Type Description
options Object
Properties
Name Type Description
from string | Identity

the sender, either a handle or Identity object
to string | Array.<string> | Identity | Array.<Identity>

One or more recipients of the message, either as handles or Identity objects
data Object

the data associated with the message.
Source:
Returns:

The model of the sent message.

Type
Promise.<Message>

# signup(handle, email, password) → {Promise.<{message: string}>}

Sign up for a new account with a single initial handle.

Parameters:
Name Type Description
handle string

The name of the initial handle if signup is successful.
email string

The email address associated with the account.
password string

The password associated with the account.
Source:
Returns:

A validation message

Type
Promise.<{message: string}>

# updateIdentity(handle, updates) → {Promise.<Identity>}

Update an existing identity.

Parameters:
Name Type Description
handle string

the handle to update.
updates Object

object containing the updates to the handle.

Properties
Name Type Attributes Description
data Object <optional>

the optional new data for the handle
Source:
Returns:

The Identity object that was updated

Type
Promise.<Identity>

# updateMessage(message, options) → {Promise.<Message>}

Update a message with the passed in message id which was sent by the passed in handle.

Parameters:
Name Type Description
message Message | string

Message object or message id
options Object
Properties
Name Type Attributes Description
handle string <optional>

the handle which sent the message.
data Object

the updated data associated with the message
Source:
Returns:

The Message object of the updated message.

Type
Promise.<Message>

# updatePrivateData(options) → {Promise.<PrivateData>}

Update the private data associated with the passed in handle and entity.

Parameters:
Name Type Description
options Object
Properties
Name Type Description
handle string

the handle associated with the data to update.
entityId string

the id of the entity (Message, Alias, or Account) the data to update is attached to.
newData Object

the new private data.
Source:
Returns:

the updated private data.

Type
Promise.<PrivateData>