ES2016+ Slack Bot Framework
npm install gheeA simple bot framework for Slack written in ES2016+.
Via npm
$ npm install ghee
Via git clone
$ npm clone git@github.com:elliottcarlson/ghee && cd ghee
$ npm install
ghee is a framework for writing bots, and does not run on it's own. For pre-made
bots, please see the Samples section.
If you want to quickly create your first ghee bot, it is recommended to use
ghee-boilerplate as it
will provide you with everything you need to quickly get a bot up and running.
ghee comes with a helper function that is intended on being used as a decorator.
To use the @ghee decorator, you will need
babel-preset-es2015,
babel-preset-es2017 and
babel-plugin-transform-decorators-legacy.
The ghee-boilerplate
provides all the files and references needed to quickly get setup to create
your own bot.
The ghee helper function will either register the method being decorated
directly, or can be passed a parameter to register as the string to respond to.
An special parameter of * will cause that method to receive all content and
acts as a catch-all method.
A straight-forward bot that will respond to .hello and .goodbye messages in
Slack would look like:
import { Ghee, ghee } from 'ghee';
class Bot extends Ghee {
constructor() {
super(YOUR_SLACK_API_TOKEN);
}
@ghee
hello() {
return 'Hello!';
}
@ghee('goodbye')
other_method() {
return 'Goodbye!';
}
}
If you don't want to use decorators, and want to stick with babel-preset-es2015,
you can still use ghee.
The same sample as above, but without a decorator:
import { Ghee, ghee } from 'ghee';
class Bot extends Ghee {
constructor() {
super(YOUR_SLACK_API_TOKEN);
ghee(this, 'hello');
ghee(this, 'goodbye');
}
hello() {
return 'Hello';
}
goodbye() {
return 'Goodbye!';
}
}
ghee abstracts the background comminucation with Slacks RTM and Web API's. By
extending the Ghee base class, your Bot will perform all of the connection and
routing of requests behind the scenes.
By registering specific methods via the ghee helper (either as a decorator, or
directly), ghee will register that methods name as a command that it can respond
to.
Your bot will respond to various styles of sending commands. In any room that
the bot has been invited to, or via private message, you will be able to trigger
a command call using the following syntaxes:
* @-mention _command_ _(optional parameters)_
* @bot-name _command_ _(optional parameters)_
* bot-name: _command_ _(optional parameters)_
* prefix _command_ _(optional parameters)_
If the _command_ has been registered via the ghee helper, then the method will
be called with the following parameters:
* params: an array of individual words that were entered after the _command_
* from: an object containing the user that issued the _command_
* channel: an object containing the channel the _command_ was issued in (can indicate direct message as well)
* msg: an object containing the raw message that was received from Slack
Please see the wiki for a more
in-depth usage guide.
_command_'s can respond in various ways. In the above examples, we simply return
a string - this tells ghee to respond to the command by sending the returned
string back to the source - i.e. if it were in a channel, it would respond
there, if the request was via direct message, it would respond there. Besides
returning a string, ghee can also accept the following return types:
* Attachment: An attachment is a seperate class that is available with ghee -
attachments allow you to include additional content with a post, and add
styling and fields. For more information on Slack attachments, see their
documentation.
* Promise: When a Promise is returned, ghee will act accordingly, and wait for
a resolve or reject message to come through. The content of the resolve/reject
message should be a string or an attachment that it can process accordingly.
Please see the wiki for more
information on Attachments and Promises.
Why not? _it's clear to use and smooth as butter_.