Status-js-api NPM

status-js

Installation

npm install status-js-api

Alternatively, you can use yarn.

Usage

Requirements

This package requires geth, status-go, or murmur to be able to connect to Whisper v6.

Using `geth`

Use the following command and flags to start geth

$ geth --testnet --syncmode=light --ws --wsport=8546 --wsaddr=localhost --wsorigins=statusjs --rpc --maxpeers=25 --shh --shh.pow=0.002 --wsapi=web3,shh,admin

Also, due to the lack of nodes with Whisper enabled, you need to create a static-nodes.json file, that must be placed in a specific path (if using ropsten in a linux environment, ~/.ethereum/testnet/geth/static-nodes.json

Using `murmur`

$ murmur-client --ws --no-bridge

See murmur documentation for additional details.

Using `status-go`

$ /path/to/status-go/statusd

See status-go documentation for additional details.

API

constructor

Constructs a new status client object

new StatusJS();

// basic instantiation
const StatusJS = require('status-js-api');
const status = new StatusJS();

connect

Connect to a web3 whisper provider

status.connect(url, [privateKey]);

await status.connect("ws://localhost:8546", "0x1122...9900");

Arguments

url - an address of a valid http, websocket or ipc provider.
privateKey - private key of the user that will send / receive messages. It will be added to the whisper node. Default: random private key. Optional

connectToProvider

Connect to a custom web3 whisper provider

status.connectToProvider(provider, [privateKey]);

await status.connect(murmurClient.provider, "0x1122...9900");

Arguments

provider - Custom web3 provider
privateKey - private key of the user that will send / receive messages. It will be added to the whisper node. Default: random private key. Optional

isListening

Checks if the node is listening for peers.

status.isListening()

if (status.isListening()) {
  // Do something
}

joinChat

Joins a public channel

status.joinChat(channel);

await status.joinChat("#mytest");

Arguments

channel - public channel name.

onUserMessage

Process incoming private messages

status.onUserMessage(cb); // private messages

status.onUserMessage((err, data) => {
  if(err) 
    console.error(err);
  else
    console.dir(data); // message information
});

Arguments

cb - a callback that will be called, possibly with an error, when a message is received. If there is no error, the first argument will be null.

onChannelMessage

Process incoming public messages

status.onChannelMessage(channel, cb); // public messages

status.onChannelMessage("#mytest", (err, data) => {
  if(err) 
    console.error(err);
  else
    console.dir(data); // message information
});

Arguments

channel - public channel name.
cb - a callback that will be called, possibly with an error, when a message is received. If there is no error, the first argument will be null.

onMessage

Process both incoming public and private messages

status.onMessage(channel, cb); // public messages
status.onMessage(cb); // private messages

status.onMessage("#mytest", (err, data) => {
  if(err) 
    console.error(err);
  else
    console.dir(data); // message information
});

Arguments

channel - public channel name. Optional
cb - a callback that will be called, possibly with an error, when a message is received. If there is no error, the first argument will be null.

onChatRequest

Process incoming chat requests messages from other users

status.onChatRequest(cb);

status.onChatRequest((err, data) => {
  if(err) 
    console.error(err);
  else
    console.dir(data); 
    // message information
    // {
    //    displayName, // Display Name
    //    profilePic, // Base64 Profile picture
    //    username // Random username (Adjective1 Adjective2 Animal)
    // }
});

Arguments

cb - a callback that will be called, possibly with an error, when a chat request is received. If there is no error, the first argument will be null.

isSubscribedTo

Check if client has joined a channel

status.isSubscribedTo(channel);

if (status.isSubscribedTo("#mytest")) {
  // Do something
}

Arguments

channel - public channel name.

leaveChat

Leaves a public channel

status.leaveChat(channel);

status.leaveChat("#mytest");

Arguments

channel - public channel name.

sendGroupMessage

Send a message to a public channel

status.sendGroupMessage(channel, message, [cb]);

status.sendGroupMessage("#mytest", "Hello world!",  (err, data) => {
  if (err) {
    console.error(err);
    return;
  }

  // Do something  
});

Arguments

channel - public channel name.
msg - message to send
cb - a callback that will be called, possibly with an error, when a message is sent. If there is no error, the first argument will be null.

sendUserMessage

Send a message to a contact code

status.sendUserMessage(pubKey, message, [cb]);

status.sendUserMessage("0x1122...9900", "Hello world!",  (err, data) => {
  if (err) {
    console.error(err);
    return;
  }

  // Do something  
});

Arguments

pubKey - user public key
msg - message to send
cb - a callback that will be called, possibly with an error, when a message is sent. If there is no error, the first argument will be null.

TODO: Create documentation for sending messages

sendJsonMessage(destination, msg, cb)
sendMessage(destination, msg, cb)

getPublicKey

Returns a string with the public key

status.getPublicKey();

await status.getPublicKey(); // "0x1122...9900"

getUserName

Returns the random username for the public key

status.getUserName([pubKey]);

await status.getUserName(); // "Adjective1 Adjective2 Animal"
await status.getUserName("0x1122...9900");

Arguments

pubKey - public key to obtain the username. Default: generate username for the current user. Optional.

addContact

Add a contact by pubKey. (TODO: send contact request msg)

status.addContact(pubKey, [cb]);

status.addContact("0x1122...9900");

Arguments

pubKey - public key to add as a contact.
cb - a callback that will be called, possibly with an error, when the contact is added. If there is no error, the first argument will be null. Optional.

removeContact

Remove a contact by pubKey.

status.removeContact(pubKey);

status.removeContact("0x1122...9900");

Arguments

pubKey - public key to remove from known contacts.

mailservers.useMailserver

Use a specific mailserver to obtain old messages. Active mailservers from Status.im can be found here

status.mailservers.useMailserver(enode, [cb]);

const enode = "enode://0011...aabb@111.222.33.44:30303";
status.mailservers.useMailserver(enode, (err, res) => {
  if (err) {
    console.err("Error: " + err);
    return;
  }

  // Do something
});

Arguments

enode - Mailserver enode address.
cb - a callback that will be called, possibly with an error, when the mailserver is selected successfully. If there is no error, the first argument will be null. Optional.

mailservers.requestUserMessages

Once a mailserver is selected, request old private messages. Messages will be received in the onMessage or onUserMessage handler.

* mailservers.requestUserMessages(options, [cb])

const enode = "enode://0011...aabb@111.222.33.44:30303";
status.mailservers.useMailserver(enode, (err, res) => {
  if (err) {
    console.err("Error: " + err);
    return;
  }
  
  const from = parseInt((new Date()).getTime() / 1000 - 86400, 10);
  const to = parseInt((new Date()).getTime() / 1000, 10);
  
  // User messages
  status.mailservers.requestUserMessages({from, to}, (err, res) => { 
    if(err) 
      console.log(err); 

    // Do something
  });
});

Arguments

options - an object containing parameters .
cb - a callback that will be called, possibly with an error, when the old private messages are requested successfully. If there is no error, the first argument will be null. Optional.

Options

from - lower bound of time range as unix timestamp, default is 24 hours back from now.
to - upper bound of time range as unix timestamp, default is now
timeout - TODO: research this in status-go, default is 30
limit - TODO: research this in status-go, default is 0

mailservers.requestChannelMessages

Once a mailserver is selected, request old public messages for a channel. Messages will be received in the onMessage or onChannelMessage handler.

* mailservers.requestChannelMessages(channel, [cb])

const enode = "enode://0011...aabb@111.222.33.44:30303";
status.mailservers.useMailserver(enode, (err, res) => {
  if (err) {
    console.err("Error: " + err);
    return;
  }

  const from = parseInt((new Date()).getTime() / 1000 - 86400, 10);
  const to = parseInt((new Date()).getTime() / 1000, 10);

  // Channel messages
  status.mailservers.requestChannelMessages("mytest", {from, to}, (err, res) => { 
    if(err) 
      console.log(err); 

    // Do something
  });
});

Arguments

channel - channel name to obtain messages from. A 4 bytes hex topic can be used too.
options - an object containing parameters .
cb - a callback that will be called, possibly with an error, when the old private messages are requested successfully. If there is no error, the first argument will be null. Optional.

Options

from - lower bound of time range as unix timestamp, default is 24 hours back from now.
to - upper bound of time range as unix timestamp, default is now
timeout - TODO: research this in status-go, default is 30
limit - TODO: research this in status-go, default is 0

Development

Clone the repo via git:

$ git clone https://github.com/status-im/status-js.git

And then install the dependencies with yarn.

$ cd status-js
$ yarn

To develop:

$ yarn run start
$ yarn run lint

Contribution

Thank you for considering to help out with the source code! We welcome contributions from anyone on the internet, and are grateful for even the smallest of fixes!

If you'd like to contribute to status-js, please fork, fix, commit and send a pull request for the maintainers to review and merge into the main code base. If you wish to submit more complex changes though, please check up with the core devs first on #status-js channel to ensure those changes are in line with the general philosophy of the project and/or get some early feedback which can make both your efforts much lighter as well as our review and merge procedures quick and simple.