Kwil_messenger NPM

API for interacting with Kwil messenger nodes.

It is worth noting that all function inputs that ask for a private key are asking for parsed JWK of an RSA private key.

Installation:

npm i kwil_messenger

Initialization

When initializing, the two parameters are: node_url, and messenger_node_url. Defaults are https://kwil.ngrok.io and ws://kwilmessenger.ngrok.io (These urls may no longer be used by our team, so it is recommended to not use these). Make sure that the second input uses the websocket protocol (ws), and not https.

import KwilMessenger from 'kwil_messenger';

const messenger = new KwilMessenger('https://kwil.ngrok.io', 'ws://kwilmessenger.ngrok.io')

Connecting

Once establishing a websocket connection with a messenger node, you can send and receive messages. Functions that manage invites or chats are asynchronous, as they access regular nodes (which use a REST API instead of websockets). Once you have connected, you must notify the messenger node for which chats you want to be updated for. This can be done by passing an array of chat ID's to the messenger.greet() method.

const client = await messenger.connect()

await messenger.greet(['abc123', 'def456'])

Creating and Inviting to Chats

Chats can be created with the createChat method: createChat(chat_name, your_name, your_private_jwk). The chat_name parameter is not unique. Invites can be sent with the sendInvite method, and can be retrieved with the getInvites method. Parameters: sendInvite(chat_id, receiver, your_username, your_private_jwk). getInvites(your_username, your_private_jwk). The chat_id parameter is a unique chat identifier, and is NOT the same as a chat_name.

await messenger.createChat('My new super secret chat', 'brennanjl', privateKey)
await messenger.sendInvite('abc123', 'satoshi', 'brennanjl', privateKey)

const invites = await messenger.getInvites('satoshi', satoshiPrivateKey)
/*
returns:
[
    {
        data: {
            chatName: ...,
            chatID: ...,
            key: [Object]
        },
        from: ...,
        signature: ...,
        inviteID: ...
    }
]
*/

invites.forEach(invite => {
    let accept = //Some logic for determining whether or not to join
    if (accept) {
        await messenger.acceptInvite(invite, 'satoshi', satoshiPrivateKey)
    } else {
        //This removes the invites
        await messenger.deleteInvite(invite.inviteID, 'satoshi', satoshiPrivateKey)
    }
})

Getting data

The client object is used to send and receive data. In this example, we will get a chat's messages for a user. First, we will use the getChat method to get a user's chats. Then, we will add the event listener. Then, we will pass a chat to getMessages, after which the websocket will send us the data. getMessages has two optional parameters after the chat: the date cursor, and the query limit. The date cursor is just a javascript Date object that tells the messenger node where to start the message query (only messages made before this date will be queried). The limit is the maximum amount of messages to be returned. The maximum limit is 40.

All chats will be decrypted in the event listener using the decryptChats method.

let chats = await messenger.getChats('brennanjl', privateKey)
if (chats.valid) { 
    //getChats returns a valid field, which identifies if decryption was successful
    chats = chats.chats
} else {
    throw new Error('There was an error, decryption likely failed.')
}

let chat;
chats.forEach( _chat => {
    //Some logic to select a chat from the chat list
    ...
    chat = _chat
})

client.on('message', async function (_m) {
        _m = _m.toString()
        try {
            console.log(await messenger.decryptChats(JSON.parse(_m), chat.key))
        } catch(e) {
            //If decryption fails, then it is likely a server greeting and not a message update
            console.log(_m)
        }
    }
)

messenger.getMessages(chat, new Date, 20)
//The output from this is accessible in the event listener above

Sending Messages

Messages can be sent with the sendMessage method. Parameters: sendMessage(chat_id, message_text, your_username, your_private_jwk, chat_private_jwk)

messenger.sendMessage('abc123', 'My super secret message', 'brennanjl', privateKey, abc123PrivateKey)

Leaving Chats

Chats can be left with the clearChat() function. Parameters: clearChat(chat_id, your_username, your_private_jwk).

If you pass an empty string for chat_id, you will leave all chats.

await messenger.clearChat('abc123', 'brennanjl', privateKey)

Closing a connection

The backend will regularly check if there is a sudden disconnect. However, if you're done with the messaging, you can call the close() method to hang up the socket.