jikstra/deltachat-node

node.js bindings for deltachat-core

deltachat-node

node.js bindings for deltachat-core

WORK IN PROGRESS The API can change at any time and will not follow semver versioning until v1.0.0 has been released.

deltachat-node primarily aims to offer two things:

• A high level JavaScript api with syntactic sugar
• A low level c binding api around deltachat-core

Note We've changed the underlying event mechanism to polling. This is a temporary solution to allow for compatibility with earlier node versions and current versions of electron at time of writing. Once electron has support for node v10.7.0 this will be removed and we will go back to using a push mechanism.

• Install
• Troubleshooting
• Usage
• API
• Events
• Developing
• Tests and Coverage
• Scripts
• License

Install

npm install deltachat-node

Troubleshooting

This modules builds on top of deltachat-core, which in turn has external dependencies.

If you get errors running npm install, you might need to install meson, ninja and libssl1.0-dev. Also, libetpan-dev and libsasl2-dev can't be installed globally.

On Linux (e.g. Debian Stretch):

sudo apt-get install python3-pip ninja-build libssl1.0-dev
sudo pip3 install meson
sudo apt-get remove libetpan-dev libsasl2-dev

Then try running npm install again.

Please see build instructions for additional information.

Usage

const DeltaChat = require('deltachat-node')
const dc = new DeltaChat()

dc.open(() => {
  const onReady = () => {
    const contactId = dc.createContact('homie', '[email protected]')
    const chatId = dc.createChatByContactId(contactId)
    dc.sendTextMessage(chatId, 'Hi!')
  }
  if (!dc.isConfigured()) {
    dc.once('ready', onReady)
    dc.configure({
      addr: '[email protected]',
      mail_pw: 'password'
    })
  } else {
    onReady()
  }
})

API

The high level JavaScript API is a collection of classes wrapping most context types provided by deltachat-core. Please see the class list for an overview of this.

• DeltaChat()
• class DeltaChat
• class Chat
• class ChatList
• class Contact
• class Lot
• class Message
• class MessageState
• class MessageType

dc = DeltaChat()

Creates a new DeltaChat instance.

Initializes the main context and sets up event handling. Call dc.open(cwd, cb) to start and dc.configure(opts, cb) if needed.

---

class DeltaChat

The DeltaChat class wraps a dc_context_t* and handles most operations, such as connecting to an IMAP server, sending messages with SMTP etc. It is through this instance you get references to the other class types following below.

dc.addAddressBook(addressBook)

Add a number of contacts. Corresponds to dc_add_address_book().

dc.addContactToChat(chatId, contactId)

Add a member to a group. Corresponds to dc_add_contact_to_chat().

dc.archiveChat(chatId, archive)

Archive or unarchive a chat. Corresponds to dc_archive_chat().

dc.blockContact(contactId, block)

Block or unblock a contact. Corresponds to dc_block_contact().

dc.checkPassword(password)

Check if the user is authorized by the given password in some way. Corresponds to dc_check_password().

dc.checkQrCode(qrCode)

Check a scanned QR code. Corresponds to dc_check_qr().

dc.close()

Stops the threads and closes down the DeltaChat instance.

dc.configure(options[, cb])

Configure and connect a context. Corresponds to dc_configure().

The options object takes the following properties:

• options.addr (string, required): Email address of the chat user.
• options.mail_server (string, optional): IMAP-server, guessed if left out.
• options.mail_port (string | integer, optional): IMAP-port, guessed if left out.
• options.mail_user (string, optional): IMAP-username, guessed if left out.
• options.mail_pw (string, required): IMAP-password of the chat user.
• options.send_server (string, optional): SMTP-server, guessed if left out.
• options.send_port (string | integer, optional): SMTP-port, guessed if left out.
• options.send_user (string, optional): SMTP-user, guessed if left out.
• options.send_pw (string, optional): SMTP-password, guessed if left out.
• options.server_flags (integer, optional): IMAP-/SMTP-flags as a combination of DC_LP flags, guessed if left out.
• options.displayname (string, optional): Own name to use when sending messages. MUAs are allowed to spread this way e.g. using CC, defaults to empty.
• options.selfstatus (string, optional): Own status to display e.g. in email footers, defaults to a standard text.
• options.e2ee_enabled (boolean, optional): Enable E2EE. Defaults to true.

dc.continueKeyTransfer(messageId, setupCode, callback)

Continue the AutoCrypt key transfer on another device. Corresponds to dc_continue_key_transfer().

• messageId (string|integer, required) See deltachat api documentation
• setupCode (string, required) See deltachat api documentation
• callback (function, required) Called with an error if setup code is bad

dc.createChatByContactId(contactId)

Create a normal chat with a single user. Corresponds to dc_create_chat_by_contact_id().

dc.createChatByMessageId(messageId)

Create a normal chat or group chat by a message id. Corresponds to dc_create_chat_by_msg_id().

dc.createContact(name, addr)

Add a single contact as a result of an explicit user action. Corresponds to dc_create_contact().

dc.createUnverifiedGroupChat(chatName)

Create a new unverified group chat. Corresponds to dc_create_group_chat().

dc.createVerifiedGroupChat(chatName)

Create a new verified group chat. Corresponds to dc_create_group_chat().

dc.deleteChat(chatId)

Delete a chat. Corresponds to dc_delete_chat().

dc.deleteContact(contactId)

Delete a contact. Corresponds to dc_delete_contact().

dc.deleteMessages(messageIds)

Delete messages. Corresponds to dc_delete_msgs().

dc.forwardMessages(messageIds, chatId)

Forward messages to another chat. Corresponds to dc_forward_msgs().

dc.getBlobdir()

Get the blob directory. Corresponds to dc_get_blobdir().

dc.getBlockedCount()

Get the number of blocked contacts. Corresponds to dc_get_blocked_cnt().

dc.getBlockedContacts()

Get blocked contacts. Corresponds to dc_get_blocked_contacts().

dc.getChat(chatId)

Get Chat object by a chat id. Corresponds to dc_get_chat().

dc.getChatContacts(chatId)

Get contact ids belonging to a chat. Corresponds to dc_get_chat_contacts().

dc.getChatIdByContactId(contactId)

Check, if there is a normal chat with a given contact. Corresponds to dc_get_chat_id_by_contact_id().

dc.getChatMedia(chatId, msgType, orMsgType)

Returns all message ids of the given type in a chat. Corresponds to dc_get_chat_media().

dc.getStarredMessages()

Returns an array of starred messages.

dc.getChatMessages(chatId, flags, marker1before)

Get all message ids belonging to a chat. Corresponds to dc_get_chat_msgs().

dc.getChats(listFlags, queryStr, queryContactId)

Like dc.getChatList() but returns a JavaScript array of ids.

dc.getChatList(listFlags, queryStr, queryContactId)

Get a list of chats. Returns a ChatList object. Corresponds to dc_get_chatlist().

dc.getConfig(key, def)

Get a configuration option. Corresponds to dc_get_config().

dc.getConfigInt(key, def)

Get a configuration option. Corresponds to dc_get_config_int().

dc.getContact(contactId)

Get a single Contact object. Corresponds to dc_get_contact().

dc.getContactEncryptionInfo(contactId)

Get encryption info for a contact. Corresponds to dc_get_contact_encrinfo().

dc.getContacts(listFlags, query)

Return known and unblocked contacts. Corresponds to dc_get_contacts().

dc.getFreshMessageCount(chatId)

Get the number of fresh messages in a chat. Corresponds to dc_get_fresh_msg_cnt().

dc.getFreshMessages()

Returns the message ids of all fresh messages of any chat. Corresponds to dc_get_fresh_msgs().

dc.getInfo()

Get info about the context. Corresponds to dc_get_info().

dc.getMessage(messageId)

Get a single Message object. Corresponds to dc_get_msg().

dc.getMessageCount(chatId)

Get the total number of messages in a chat. Corresponds to dc_get_msg_cnt().

dc.getMessageInfo(messageId)

Get an informational text for a single message. Corresponds to dc_get_msg_info().

dc.getNextMediaMessage(messageId)

Get next message of the same type. Corresponds to dc_get_next_media().

dc.getPreviousMediaMessage(messageId)

Get previous message of the same type. Corresponds to dc_get_next_media().

dc.getSecurejoinQrCode(groupChatId)

Get QR code text that will offer a secure-join verification. Corresponds to dc_get_securejoin_qr().

dc.importExport(what, param1, param2)

Import/export things. Corresponds to dc_imex().

dc.importExportHasBackup(dirName)

Check if there is a backup file. Corresponds to dc_imex_has_backup().

dc.initiateKeyTransfer(callback)

Initiate Autocrypt setup transfer. Corresponds to dc_initiate_key_transfer().

• callback (function, required) Called with an error as first argument (or null) and the setup code as second argument if no error occured.

dc.isConfigured()

Check if the context is already configured. Corresponds to dc_is_configured().

dc.isContactInChat(chatId, contactId)

Check if a given contact id is a member of a group chat. Corresponds to dc_is_contact_in_chat().

dc.isOpen()

Check if the context database is open. Corresponds to dc_is_open(). Returns true if open, otherwise false.

dc.joinSecurejoin(qrCode)

Join an out-of-band-verification initiated on another device with dc.getSecurejoinQrCode(). Corresponds to dc_join_securejoin().

dc.markNoticedChat(chatId)

Mark all messages in a chat as noticed. Corresponds to dc_marknoticed_chat().

dc.markNoticedAllChats()

Same as dc.markNoticedChat() but for all chats. Corresponds to dc_marknoticed_all_chats().

dc.markNoticedContact(contactId)

Mark all messages sent by the given contact as noticed. Corresponds to dc_marknoticed_contact().

dc.markSeenMessages(messageIds)

Mark a message as seen, updates the IMAP state and sends MDNs. Corresponds to dc_markseen_msgs().

dc.messageNew()

Create a new Message object. Corresponds to dc_msg_new().

dc.open([cwd], callback)

Opens the underlying database.

• cwd (string, optional) Path to working directory, defaults to current working directory.
• callback (function, required) Called with an error if the database could not be opened.

dc.removeContactFromChat(chatId, contactId)

Remove a member from a group. Corresponds to dc_remove_contact_from_chat().

dc.searchMessages(chatId, query)

Search messages containing the given query string. Corresponds to dc_search_msgs().

dc.sendAudioMessage(chatId, file, fileMime, duration, author, trackName)

Send an audio file to a chat. Corresponds to dc_send_audio_msg().

dc.sendFileMessage(chatId, file, fileMime)

Send a document to a chat. Corresponds to dc_send_file_msg().

dc.sendImageMessage(chatId, file, fileMime, width, height)

Send an image to a chat. Corresponds to dc_send_image_msg().

dc.sendMessage(chatId, msg)

Send a message of any type to a chat. Corresponds to dc_send_msg().

dc.sendTextMessage(chatId, text)

Send a text message to a chat. Corresponds to dc_send_text_msg().

dc.sendVcardMessage(chatId, contactId)

Send foreign contact data to a chat. Corresponds to dc_send_vcard_msg().

dc.sendVideoMessage(chatId, file, fileMime, width, height, duration)

Send a video to a chat. Corresponds to dc_send_video_msg().

dc.sendVoiceMessage(chatId, file, fileMime, duration)

Send a voice message to a chat. Corresponds to dc_send_voice_msg().

dc.setChatName(chatId, name)

Set group name. Corresponds to dc_set_chat_name().

dc.setChatProfileImage(chatId, image)

Set group profile image. Corresponds to dc_set_chat_profile_image().

dc.setConfig(key, value)

Configure the context. Corresponds to dc_set_config().

dc.setConfigInt(key, value)

Configure the context. Corresponds to dc_set_config_int().

dc.setOffline(offline)

Let the DeltaChat instance know that the application is offline/online.

dc.setTextDraft(chatId, text)

Save a draft for a chat in the database. Corresponds to dc_set_text_draft().

dc.starMessages(messageIds, star)

Star/unstar messages. Corresponds to dc_star_msgs().

---

class Chat

An object representing a single chat in memory.

chat.getArchived()

Get archived state. Corresponds to dc_chat_get_archived().

chat.getDraftTimestamp()

Get timestamp of the draft. Corresponds to dc_chat_get_draft_timestamp().

chat.getId()

Get chat id. Corresponds to dc_chat_get_id().

chat.getName()

Get name of a chat. Corresponds to dc_chat_get_name().

chat.getProfileImage()

Get the chat's profile image. Corresponds to dc_chat_get_profile_image().

chat.getSubtitle()

Get a subtitle for a chat. Corresponds to dc_chat_get_subtitle().

chat.getTextDraft()

Get draft for a chat, if any. Corresponds to dc_chat_get_text_draft().

chat.getType()

Get chat type. Corresponds to dc_chat_get_type().

chat.isSelfTalk()

Check if a chat is a self talk. Corresponds to dc_chat_is_self_talk().

chat.isUnpromoted()

Check if a chat is still unpromoted. Corresponds to dc_chat_is_unpromoted().

chat.isVerified()

Check if a chat is verified. Corresponds to dc_chat_is_verified().

chat.toJson()

Returns the object state as a JavaScript serializable object.

---

class ChatList

An object representing a single chatlist in memory.

list.getChatId(index)

Get a single chat id of a chatlist. Corresponds to dc_chatlist_get_chat_id().

list.getCount()

Get the number of chats in a chatlist. Corresponds to dc_chatlist_get_cnt().

list.getMessageId(index)

Get a single message id of a chatlist. Corresponds to dc_chatlist_get_msg_id().

list.getSummary(index, chat)

Get a summary for a chatlist index. Returns a Lot object. Corresponds to dc_chatlist_get_summary().

---

class Contact

An object representing a single contact in memory.

contact.getAddress()

Get email address. Corresponds to dc_contact_().

contact.getDisplayName()

Get display name. Corresponds to dc_contact_get_display_name().

contact.getFirstName()

Get the part of the name before the first space. Corresponds to dc_contact_get_first_name().

contact.getId()

Get the id of the contact. Corresponds to dc_contact_get_id().

contact.getName()

Get the name of the contact. Corresponds to dc_contact_get_name().

contact.getNameAndAddress()

Get a summary of name and address. Corresponds to dc_contact_get_name_n_addr().

contact.isBlocked()

Check if a contact is blocked. Corresponds to dc_contact_is_blocked().

contact.isVerified()

Check if a contact is verified. Corresponds to dc_contact_is_verified().

contact.toJson()

Returns the object state as a JavaScript serializable object.

---

class Lot

An object containing a set of values in memory.

lot.getId()

Get the associated id. Corresponds to dc_lot_get_id().

lot.getState()

Get the associated state. Corresponds to dc_lot_get_state().

lot.getText1()

Get first string. Corresponds to dc_lot_get_text1().

lot.getText1Meaning()

Get the meaning of the first string. Corresponds to dc_lot_get_text1_meaning().

lot.getText2()

Get the second string. Corresponds to dc_lot_get_text2().

lot.getTimestamp()

Get the associated timestamp. Corresponds to dc_lot_get_timestamp().

lot.toJson()

Returns the object state as a JavaScript serializable object.

---

class Message

An object representing a single message in memory.

message.getChatId()

Get the id of the chat the message belongs to. Corresponds to dc_msg_get_chat_id().

message.getDuration()

Get duration of audio of video. Corresponds to dc_msg_get_duration().

message.getFile()

Find out full path, file name and extension of the file associated with a message. Corresponds to dc_msg_get_file().

message.getFilebytes()

Get the size of the file. Corresponds to dc_msg_get_filebytes().

message.getFilemime()

Get mime type of the file. Corresponds to dc_msg_get_filemime().

message.getFilename()

Get base file name without path. Corresponds to dc_msg_get_filename().

message.getFromId()

Get the id of the contact that wrote the message. Corresponds to dc_msg_get_from_id().

message.getHeight()

Get height of image or video. Corresponds to dc_msg_get_height().

message.getId()

Get the id of the message. Corresponds to dc_msg_get_id().

message.getMediainfo()

Get real author and title. Returns a Lot object. Corresponds to dc_msg_get_mediainfo().

message.getSetupcodebegin()

Get first characters of the setup code. Corresponds to dc_msg_get_setupcodebegin().

message.getShowpadlock()

Check if a padlock should be shown beside the message. Corresponds to dc_msg_get_showpadlock().

message.getState()

Get the state of the message. Returns a MessageState object. Corresponds to dc_msg_get_state().

message.getSummary(chat)

Get a summary of a message. Returns a Lot object. Corresponds to dc_msg_get_summary().

message.getSummarytext(approxCharacters)

Get a message summary as a single line of text. Corresponds to dc_msg_get_summarytext().

message.getText()

Get the text of the message. Corresponds to dc_msg_get_text().

message.getTimestamp()

Get message sending time. Corresponds to dc_msg_get_timestamp().

message.getType()

Get the type of the message. Returns a MessageType object. Corresponds to dc_msg_get_type().

message.getWidth()

Get the width of image or video. Corresponds to dc_msg_get_width().

message.isDeadDrop()

Check if the message belongs to the virtual dead drop chat.

message.isForwarded()

Check if the message is a forwarded message. Corresponds to dc_msg_is_forwarded().

message.isIncreation()

Check if a message is still in creation. Corresponds to dc_msg_is_increation().

message.isInfo()

Check if the message is an informational message, created by the device or by another user. Corresponds to dc_msg_is_info().

message.isSent()

Check if a message was sent successfully. Corresponds to dc_msg_is_sent().

message.isSetupmessage()

Check if the message is an Autocrypt setup message. Corresponds to dc_msg_is_setupmessage().

message.isStarred()

Check if a message is starred. Corresponds to dc_msg_is_starred().

message.latefilingMediasize(width, height, duration)

Late filing information to a message. Corresponds to dc_msg_latefiling_mediasize().

message.setDimension(width, height)

Set the dimensions associated with a message. Corresponds to dc_msg_set_dimension().

message.setDuration(duration)

Set the duration assocated with the message object. Corresponds to dc_msg_set_duration().

message.setFile(file, mime)

Set the file assocated with the message object. Corresponds to dc_msg_set_file().

message.setMediainfo(author, trackName)

Set the media information assocated with the message object. Corresponds to dc_msg_set_mediainfo().

message.setText(text)

Set the test of a message object. Corresponds to dc_msg_set_text().

message.setType(type)

Set the type of a message object. Corresponds to dc_msg_set_type().

message.toJson()

Returns the object state as a JavaScript serializable object.

---

class MessageState

An object representing a Message state.

state.isUndefined()

Message state is DC_STATE_UNDEFINED.

state.isFresh()

Message state is DC_STATE_IN_FRESH.

state.isNoticed()

Message state is DC_STATE_IN_NOTICED.

state.isSeen()

Message state is DC_STATE_IN_SEEN.

state.isPending()

Message state is DC_STATE_OUT_PENDING.

state.isFailed()

Message state is DC_STATE_OUT_FAILED.

state.isDelivered()

Message state is DC_STATE_OUT_DELIVERED.

state.isReceived()

Message state is DC_STATE_OUT_MDN_RCVD.

state.state

Internal state property.

---

class MessageType

An object representing a Message type.

type.isUndefined()

Message type is DC_MSG_UNDEFINED.

type.isText()

Message type is DC_MSG_TEXT.

type.isImage()

Message type has DC_MSG_IMAGE bits set.

type.isGif()

Message type is DC_MSG_GIF.

type.isAudio()

Message type has DC_MSG_AUDIO bits set.

type.isVoice()

Message type is DC_MSG_VOICE.

type.isVideo()

Message type has DC_MSG_VIDEO bits set.

type.isFile()

Message type is DC_MSG_FILE.

type.type

Internal type property.

Events

DeltaChat is an EventEmitter and emits the following events.

Event	Description	Arguments
ready	DeltaChat is ready	-
DC_EVENT_INFO	Info string	(info)
DC_EVENT_SMTP_CONNECTED	Info string	(info)
DC_EVENT_IMAP_CONNECTED	Info string	(info)
DC_EVENT_SMTP_MESSAGE_SENT	Info string	(info)
DC_EVENT_WARNING	Warning string	(warning)
DC_EVENT_ERROR	Error string	(code, error)
DC_EVENT_MSGS_CHANGED	Messages or chats changed	(chatId, msgId)
DC_EVENT_INCOMING_MSG	There is a fresh message	(chatId, msgId)
DC_EVENT_MSG_DELIVERED	Message was sent successfully	(chatId, msgId)
DC_EVENT_MSG_FAILED	Message could not be sent	(chatId, msgId)
DC_EVENT_MSG_READ	Message read by the receiver	(chatId, msgId)
DC_EVENT_CHAT_MODIFIED	Chat modified	(chatId)
DC_EVENT_CONTACTS_CHANGED	Contact changed	(contactId)
DC_EVENT_CONFIGURE_PROGRESS	Configuration progress	(progress)
DC_EVENT_IMEX_PROGRESS	Import/export progress	(progress)
DC_EVENT_FILE_COPIED	A file has been copied	(fileName)
DC_EVENT_IMEX_FILE_WRITTEN	A file has been exported	(fileName)
DC_EVENT_SECUREJOIN_INVITER_PROGRESS	Progress of a secure-join handshake	(contactId, progress)
DC_EVENT_SECUREJOIN_JOINER_PROGRESS	Progress of a secure-join handshake	(contactId, progress)
ALL	All events from deltachat-core	(event, data1, data2)

Developing

If you're cloning this repository in order to hack on it, you need to setup deltachat-core dependencies correctly, before doing npm install.

The following commands should be enough to get started.

git clone https://github.com/deltachat/deltachat-node.git
cd deltachat-node
npm run submodule
npm install

Tests and Coverage

To run the tests you need docker installed. To start the Greenmail test server run npm run start-test-server. Once the server is running you can run the tests with npm test. To stop the server run npm run stop-test-server.

Running npm test ends with showing a code coverage report, which is produced by nyc.

The coverage report from nyc in the console is rather limited. To get a more detailed coverage report you can run npm run coverage-html-report. This will produce a html report from the nyc data and display it in a browser on your local machine.

On Travis the coverage report is also passed to coveralls.

Scripts

We have the following scripts for building, testing and coverage:

• npm test Runs dependency-check, standard and then the tests in test/index.js.
• npm install After dependencies are installed, runs script/rebuild-all.js which recompiles all the native code from scratch.
• npm run coverage Creates a coverage report and passes it to coveralls. Only done by Travis.
• npm run coverage-html-report Generates a html report from the coverage data and opens it in a browser on the local machine.
• npm run dependency-check Makes sure all dependencies and devDependencies specified in package.json are used and that no dependency is missing.
• npm run generate-constants Generates constants.js based on the deltachat-core/deltachat.h header file.
• npm run start-test-server Starts the Greenmail test server.
• npm run stop-test-server Stops the Greenmail test server.
• npm run submodule Updates the git submodule in deltachat-core/.
• npm run rebuild Recompiles the native code in src/ and builds a new deltachat.node addon.

By default npm install will build in Release mode and will be as silent as possible. Use --debug flag to build in Debug mode and --verbose for more verbose output, e.g. to build in Debug mode with full verbosity, do:

npm install --debug --verbose

License

Licensed under the GPLv3, see LICENSE file for details.

Copyright © 2018 Delta Chat contributors.