JSDoc: Class: Client

new Client(transport, promiseProvideropt)

The Client class is the main entry point for sending JMAP requests to a remote server.
It uses a fluent API so that it's easy to chain calls. JMAP requests are sent using one of the getXXX methods that map to their equivalent in the JMAP specification. For instance, if you want to do a getAccounts request, you'll use the Client#getAccounts method.

Parameters:

Name	Type	Attributes	Default	Description
`transport`	Transport			The Transport instance used to send HTTP requests.
`promiseProvider`	PromiseProvider	<optional>	ES6PromiseProvider	The PromiseProvider implementation to use.

Source:

client/Client.js, line 30

Methods

authenticate(username, deviceName, continuationCallback) → {Promise}

Implement the 2-step JMAP authentication protocol.
This method abstract the two authentication steps:

query the JMAP server to get a continuation token
query the JMAP server with the continuation token (and password), to get the final accessToken.

Parameters:

Name	Type	Description
`username`	String	The username to authenticate with
`deviceName`	String	A unique device name
`continuationCallback`	function	A function that takes an AuthContinuation object as argument, and should return a promise, that will eventually resolve with an object denoting the chosen authentication method and the optional password (if method == password).

Source:

client/Client.js, line 143

Returns:

A Promise that will eventually be resovled with a AuthAccess object

Type: Promise

authExternal(username, deviceName, continuationCallback) → {Promise}

Implement the JMAP external authentication protocol.
This method abstract the two authentication steps:

query the JMAP server to get a continuation token
query the JMAP server with the continuation token, to get the final accessToken.

Between those two steps, a user provided function wil be called to handle the external authentication part.
This method returns a promise that will eventually be resovled with a AuthAccess object. It's the responsability of the caller to then set the AuthToken using for example:

client.withAuthenticationToken(authAccess.accessToken);

Parameters:

Name	Type	Description
`username`	String	The username of the user to authenticate.
`deviceName`	String	A unique device name
`continuationCallback`	function	A function that takes an AuthContinuation object as argument, and should return a promise, that will resolve once the external authentication is complete.

Source:

client/Client.js, line 221

Returns:

A Promise that will eventually be resovled with a AuthAccess object

Type: Promise

authPassword(username, password, deviceName) → {Promise}

Implement the JMAP password authentication protocol.
This method abstract the two authentication steps:

query the JMAP server to get a continuation token
query the JMAP server with the continuation token and the password, to get the final accessToken.

Parameters:

Name	Type	Description
`username`	String	The username of the user to authenticate
`password`	String	The password of the user to authenticate
`deviceName`	String	A unique device name

Source:

client/Client.js, line 241

Returns:

A Promise that will eventually be resovled with a AuthAccess object

Type: Promise

createMailbox(name, parentIdopt) → {Promise}

Creates a mailbox by sending a setMailboxes JMAP request.

Parameters:

Name	Type	Attributes	Default	Description
`name`	String			The name of the mailbox to create.
`parentId`	String	<optional>	null	The id of the parent of the mailbox to create.

Source:

client/Client.js, line 315

See:

http://jmap.io/spec.html#creating-mailboxes

Returns:

A Promise that eventually resolves to a Mailbox.

Type: Promise

destroyMailbox(id) → {Promise}

Destroy the Mailbox related to the given id on the server.
This will issue a Client#destroyMailboxes request under the hoods, passing [id] option.

Parameters:

Name	Type	Description
`id`	String	The id of the mailbox to destroy.

Source:

client/Client.js, line 372

Returns:

A Promise that eventually resolves to nothing if the Mailbox was destroyed successfully.

Type: Promise

destroyMailboxes(ids) → {Promise}

Destroy multiple Mailboxes specified to the given ids on the server.
This will issue a Client#setMailboxes JMAP request under the hoods, passing the correct options.

Parameters:

Name	Type	Description
`ids`	Array.<String>	An array IDs of the mailboxes to destroy. These IDs must be in the right order: Destroy X comes before destroy Y if X is a descendent of Y.

Source:

client/Client.js, line 388

See:

http://jmap.io/spec.html#destroying-mailboxes

Returns:

A Promise that eventually resolves to nothing if all Mailboxes were destroyed successfully. Otherwise, it rejects error message of the first notDestroyed mailbox.

Type: Promise

destroyMessage(id) → {Promise}

Destroy the Message related to the given id on the server.
This will issue a Client#setMessages JMAP request under the hoods, passing the correct options.

Parameters:

Name	Type	Description
`id`	String	The id of the object to destroy.

Source:

client/Client.js, line 530

See:

Client#setMessages

Returns:

A Promise that eventually resolves to nothing if the Message was destroyed successfully.

Type: Promise

destroyMessages(ids) → {Promise}

Destroy several Messages at once.
This will issue a Client#setMessages JMAP request under the hoods, passing the correct options.

Parameters:

Name	Type	Description
`ids`	Array.<String>	The list of ids of the messages to destroy.

Source:

client/Client.js, line 548

See:

Client#setMessages

Returns:

A Promise that resolves to a SetResponse, containing the result of the operation.

Type: Promise

getAccounts(optionsopt) → {Promise}

Sends a getAccounts JMAP request.

Parameters:

Name	Type	Attributes	Default	Description
`options`	Object	<optional>	null	The options to the getAccounts JMAP request.

Source:

client/Client.js, line 258

See:

http://jmap.io/spec.html#getaccounts

Returns:

A Promise that eventually resolves to an array of Account objects.

Type: Promise

getMailboxes(optionsopt) → {Promise}

Sends a getMailboxes JMAP request.

Parameters:

Name	Type	Attributes	Default	Description
`options`	Object	<optional>	null	The options to the getMailboxes JMAP request.

Source:

client/Client.js, line 288

See:

http://jmap.io/spec.html#getmailboxes

Returns:

A Promise that eventually resolves to an array of Mailbox objects.

Type: Promise

getMailboxWithRole(role, optionsopt) → {Promise}

Finds a Mailbox with the given role.
This will issue a getMailboxes JMAP request and search for the mailbox in the returned list.

Parameters:

Name	Type	Attributes	Default	Description
`role`	MailboxRole \| String			The desired mailbox role.
`options`	Object	<optional>	null	The options to the implicit getMailboxes JMAP request.

Source:

client/Client.js, line 417

See:

MailboxRole

Returns:

A Promise that eventually resolves to the Mailbox if found.

Type: Promise

getMessageList(optionsopt) → {Promise}

Sends a getMessageList JMAP request.

Parameters:

Name	Type	Attributes	Default	Description
`options`	Object	<optional>	null	The options to the getMessageList JMAP request.

Source:

client/Client.js, line 447

See:

http://jmap.io/spec.html#getmessagelist

Returns:

A Promise that eventually resolves to a MessageList object.

Type: Promise

getMessages(optionsopt) → {Promise}

Sends a getMessages JMAP request.

Parameters:

Name	Type	Attributes	Default	Description
`options`	Object	<optional>	null	The options to the getMessages JMAP request.

Source:

client/Client.js, line 473

See:

http://jmap.io/spec.html#getmessages

Returns:

A Promise that eventually resolves to an array of Message objects.

Type: Promise

getThreads(optionsopt) → {Promise}

Sends a getThreads JMAP request.

Parameters:

Name	Type	Attributes	Default	Description
`options`	Object	<optional>	null	The options to the getThreads JMAP request.

Source:

client/Client.js, line 460

See:

http://jmap.io/spec.html#getthreads

Returns:

A Promise that eventually resolves to an array of Thread objects.

Type: Promise

getVacationResponse(optionsopt) → {Promise}

Gets the singleton VacationResponse instance for a given account.
This will send a getVacationResponse request to the JMAP backend.

Parameters:

Name Type Attributes Description

options

Object

The options to the underlying getVacationResponse JMAP request.

Properties

Name	Type	Attributes	Default	Description
`accountId`	String	<optional>	null	The account ID to get the vacation response for. If `null`, the primary account is used.

Source:

client/Client.js, line 610

Returns:

A Promise that eventually resolves to the VacationResponse instance.

Type: Promise

moveMessage(id, mailboxIds) → {Promise}

Moves a Message to a different set of mailboxes.
This will issue a Client#setMessages JMAP request under the hoods, passing the correct options.

Parameters:

Name	Type	Description
`id`	String	The id of the Message to move.
`mailboxIds`	Array.<String>	The identifiers of the target mailboxes for the message.

Source:

client/Client.js, line 594

See:

Client#setMessages

Returns:

A Promise that eventually resolves to nothing if the message was moved successfully.

Type: Promise

saveAsDraft(message) → {Promise}

Save a message as draft by sending a setMessages JMAP request.
The mailboxIds and isDraft properties of the given message will be overridden by this method.

Parameters:

Name	Type	Description
`message`	OutboundMessage	The message to save.

Source:

client/Client.js, line 564

See:

http://jmap.io/spec.html#saving-a-draft

Returns:

A Promise that eventually resolves to a CreateMessageAck.

Type: Promise

send(message, outbox) → {Promise}

Sends a message by issuing a setMessages JMAP request.
The mailboxIds and isDraft properties of the given message will be overridden by this method.

Parameters:

Name	Type	Description
`message`	OutboundMessage	The message to send.
`outbox`	Mailbox	The Mailbox with role='outbox', if already available

Source:

client/Client.js, line 579

See:

http://jmap.io/spec.html#sending-messages

Returns:

A Promise that eventually resolves to a CreateMessageAck.

Type: Promise

setMailboxes(optionsopt) → {Promise}

Sends a setMailboxes JMAP request.

Parameters:

Name	Type	Attributes	Default	Description
`options`	Object	<optional>	null	The options to the setMailboxes JMAP request.

Source:

client/Client.js, line 301

See:

http://jmap.io/spec.html#setmailboxes

Returns:

A Promise that eventually resolves to a Mailbox object.

Type: Promise

setMessages(optionsopt) → {Promise}

Sends a setMessages JMAP request.

Parameters:

Name	Type	Attributes	Default	Description
`options`	Object	<optional>	null	The options to the setMessages JMAP request.

Source:

client/Client.js, line 486

See:

http://jmap.io/spec.html#setmessages

Returns:

A Promise that eventually resolves to a SetResponse object.

Type: Promise

setVacationResponse(vacationResponse, optionsopt) → {Promise}

Sets the singleton VacationResponse instance for a given account.
This will send a setVacationResponse request to the JMAP backend.

Parameters:

Name Type Attributes Description

vacationResponse

VacationResponse

The VacationResponse instance to set

options

Object

The options to the underlying setVacationResponse JMAP request.

Properties

Name	Type	Attributes	Default	Description
`accountId`	String	<optional>	null	The account ID to set the vacation response for. If `null`, the primary account is used.

Source:

client/Client.js, line 624

Returns:

A Promise that eventually resolves to nothing upon success.

Type: Promise

updateMailbox(id, options) → {Promise}

Updates properties of a Mailbox.
This will issue a Client#setMailboxes JMAP request under the hoods, passing the correct options.

Parameters:

Name	Type	Description
`id`	String	The id of the Mailbox to update.
`options`	Object	The options of the target mailbox to be updated.

Source:

client/Client.js, line 349

See:

http://jmap.io/spec.html#updating-mailboxes

Returns:

A Promise that eventually resolves to nothing if the mailbox was updated successfully.

Type: Promise

updateMessage(id, options) → {Promise}

Updates properties of a Message.
This will issue a Client#setMessages JMAP request under the hoods, passing the correct options.

Parameters:

Name Type Description

id

String

The id of the Message to update.

options

Object

The options of the target message to be updated.

Properties

Name	Type	Description
`mailboxIds`	Array.<String>	The identifiers of the new mailboxes for the message.
`isFlagged`	Boolean	This corresponds whether the message is flagged or not
`isUnread`	Boolean	This corresponds whether the message has been yet read or not
`isAnswered`	Boolean	This corresponds whether the message has been yet replied or not

Source:

client/Client.js, line 505

See:

http://jmap.io/spec.html#updating-messages

Returns:

A Promise that eventually resolves to nothing if the message was updated successfully.

Type: Promise

withAPIUrl(url) → {Client}

Sets the API URL of the target JMAP server. All JMAP requests will be sent to this URL.

The URL will be exposed as the apiUrl property afterwards.

Parameters:

Name	Type	Description
`url`	String	The API URL of the JMAP server.

Source:

client/Client.js, line 80

Returns:

This Client instance.

Type: Client

withAuthAccess(access) → {Client}

Initializes the client with an AuthAccess model from an authentication response.

The individual properties of the AuthAccess object will be copied into client properties.

Parameters:

Name	Type	Description
`access`	AuthAccess \| Object	The response object from an authenticate process.

Source:

client/Client.js, line 110

Returns:

This Client instance.

Type: Client

withAuthenticationToken(token, schemeopt) → {Client}

Registers an authentication token, obtained by an external mechanism from the target JMAP server.
This token will then be used as the Authorization header, as per http://jmap.io/spec.html#authenticating-http-requests.

The token will be exposed as the authToken property afterwards.

Parameters:

Name	Type	Attributes	Description
`token`	String		The authentication token to use in JMAP requests.
`scheme`	String	<optional>	The authentication scheme according to RFC 7235

Source:

client/Client.js, line 64

Returns:

This Client instance.

Type: Client

withAuthenticationUrl(url) → {Client}

Registers an authentication URL, that will be used as the endpoint to send authentication requests to the server.

The URL will be exposed as the authenticationUrl property afterwards.

Parameters:

Name	Type	Description
`url`	String	The authentication url to use in JMAP requests.

Source:

client/Client.js, line 47

Returns:

This Client instance.

Type: Client

withDownloadUrl(url) → {Client}

Sets the download URL, i.e.: the URL used to download attachments to Messages.

The URL will be exposed as the downloadUrl property afterwards.

Parameters:

Name	Type	Description
`url`	String	The download URL of the JMAP server.

Source:

client/Client.js, line 95

Returns:

This Client instance.

Type: Client