MapleBot

MapleBot is a simple XMPP bot built with nodejs. Its built using a number of configurable tasks. Each task binds a set of commands to the bot. When the bot encounters a command it knows. The connected function is run. MapleBot makes a great bot to use on company jabber networks, and can easily be trained to do things like send reminders or get the weather.

Dependencies

You can install all of Maplebot's dependencies using npm.

npm install .

This will install all the dependencies. You can make sure things worked by running the tests:

npm test

Configuration

Included in the source is a sample configuration file, fill out the configuration values to get MapleBot running. Some of the most important configuration options are:

• username The login name MapleBot should use when joining the jabber service.
• password The password to use.
• room The room you want the bot to join.
• nick The nickname the bot should use.
• tasks The tasks the bot should bind.

Creating Tasks

Tasks in MapleBot are where you build the commands and features you want MapleBot to have. Each task binds a number of commands to the bot. When the bot receives a message in the group chat that starts with the command value, it dispatches the remainder of the message to the bound function. There is a built in task base to help facilitate building tasks. Each task is expected to have a bindCommands method that accepts an object that commands are inserted into. See the provided QueueManager or Weather tasks for how to build a simple task.

Configuring tasks

When defining tasks in your configuration file you can also pass in any additional configuration data for those tasks.

// in config.json
module.exports = {
    tasks: {
        'CodeReview': {
            module: './code-review',
            autoPairTime: '10:30:00'
        }
    }
};

When using an object for a task definition, you must include the module key. It has to point at the file containing the task you want to use. All other keys + values will be passed to the tasks's constructor as the second parameter. The first is the bot the task is bound to.

Creating responses

Responses can be created in a few different formats, each with different features:

• Plain text These are directly output to the group chat.
• Objects Simple object responses allow you to respond with both a subject and a body, and other properties. Useful for bot tasks that need to set the topic.
• Promises There is a simple built-in promise object in the task module. Promises are ideal for tasks that require additional asynchronous work to be done. By resolving the promise, the response will be delivered.

A response using a promise would look like:

var task = require('./lib/task');

function doSomething() {
    var promise = new task.Promise();
    doSomethingAsync(promise);
    return promise;
}

An object response could look like:

var response = {
    body: 'I am message text',
    subject: 'I will be set as the group chat topic in most clients.'
};

You can use object responses with both synchronous responses, as well as promises. When using object responses you can direct the message to specific rooms for multi-room bots, by setting the room property. The room property lets you reply directly to people from a groupchat room. You can also change set the type key to specify whether or not you want to send a 'direct' or 'groupchat' type of message.

Built in Tasks

There are a few built-in tasks, that do a few things I need on a day to day basis:

• QueueManager - manages queues of things to do.
• Weather - Query google's weather api to get local forecasts.
• Help - Display help text about all the other tasks. Called with !help
• CodeReview - Helps do random pair ups for daily code reviews.

Running MapleBot

After setting up the configuration file, you can start the bot using

node bot.js

Calling commands

You call bot commands by sending the group chat a message starting with one of the bound command keywords. For example, if you were using the Weather task, you could send:

!weather toronto,ontario

to the group chat. This will cause MapleBot to query the google weather api and reply with the result. Whenever a task command is called, it will be supplied one argument, a request. This request contains a number of properties that you can use:

• room The room the message came from.
• from The person who sent the message.
• body The message body text.
• type Whether the the message was a direct or groupchat message.

The requests can also be treated as a string, and appended into other text. If a response doesn't contain a room the request's room will be used.