snarl

snarl !snarl
===================================

Simple chat bot (currently for Slack), extensible with plugins.

Despite his name, snarl is just a fuzzy and friendly goofball. He's been with
us for several years, since the beginning of the Coding
Soundtrack community. He's an awesome automaton that
helps us with a great many things, so be nice to him.

Avatar for snarl is by @yiyinglu, who designed
the original avatars for tuntable.fm.

If you'd like to test him out, join us on the Maki Slack, where snarl helps us develop the Maki Framework.

Quick Start

You'll need to create a Bot User for your Slack organization, generally found at
https://YOUR-TEAM-NAME.slack.com/services/new/bot. Once the integration is
added, you'll be given an API token: **place this token into
config/index.json**. For more help, Slack has [great documentation on bot
users][slack-bots].

1. Install via npm install snarl -g, or simply clone¹ this repository and run npm install as usual.
2. Modify config/index.json to contain your Slack token (see paragraph above).
3. Execute npm start in the source directory, or snarl if you installed globally.

That's it. You'll see snarl come online! If you install snarl globally via
npm install snarl -g, you can also simply type snarl at any time (for example,
inside of a screen or a tmux session) to run the bot.

1: if you want to make modifications, you should [fork it first][fork]!

[slack-bots]: https://api.slack.com/bot-users
[fork]: https://github.com/martindale/snarl/fork

Naming Your Bot

If you want to give snarl a different name, you can configure it via Slack (see
link above), or add a name property to config/index.json.

Plugins

snarl supports plugins. We've kept the default list short but fun. We'd love
to see even more contributions!

Plugins for snarl can add commands or other functionality. For example, the
included karma plugin lets snarl keep track of karma for various users.

$3

Plugins can be autoloaded from either a single file in
./plugins/plugin-name.js or an NPM module named snarl-plugin-name. To
autoload a plugin, add the plugin name to the plugins array in
config/index.json:

``json
{
"name": "snarl",
"plugins": ["erm", "karma"],
"store": "data/store",
"slack": {
"token": "some-token-xxxooooo",
},
}
`

...and simply call autoload():

`js
var Snarl = require('snarl');
var snarl = new Snarl();

// autoload plugins found in config/index.json
snarl.autoload();

// start snarl, as normal
snarl.start();
`

To use another plugin, simply require it, as follows:

`js
var Snarl = require('snarl');
var snarl = new Snarl();

// import the karma plugin
var karma = require('./plugins/karma');

// use the karma plugin we required above
snarl.use(karma);

// start snarl, as normal
snarl.start();
`

$3


The list of available plugins (via ./plugins/plugin-name) is as follows:

- karma, which keeps track of user karma, as incremented by @username++.
- facts, which provides !TopologyFacts (mathematical topology facts), !SmiffFacts (facts about Will Smith), and !InterstellaFacts (facts about Interstella 5555)
- meetups, which responds with a simple message telling your community about in-person meetups.
- erm, which transforms the text of a user message into ERMEGERD speech using martindale/erm.
- beer-lookup, which provides !brew to look up and describe a beer via BreweryDB.

$3

- snarl-eliza is a simple AI using
the ELIZA self-help chatbot created by Joseph Weizenbaum between 1964 and 1966.

$3

To write a snarl plugin, create a new NPM module that exports a map of triggers
your bot will respond to. You can use either a simple message string, or a
function that expects a callback:

`js
module.exports = {
'test': 'Hello, world'
};
`

For more complex functionality, use the callback feature:

`js
module.exports = {
'test': function(msg, done) {
// simulate an asynchronous task...
setTimeout(function() {
// error is first parameter, response is second
done(null, 'Your message was: ' + msg.text + '\nYour triggers were:' + msg.triggers);
}, 1000);
};
}
`

We ask that you publish your plugins via npm, name them snarl-yourplugin, and
add both the snarl and slack keywords to your package.json`.

Thanks! We hope you enjoy.