A simple bot framework for Slack written in ES2016+.
ghee is actively in development and breaking changes may occur until release 1.0
Via npm
$ npm install ghee
Via git clone
$ npm clone [email protected]: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)
- .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 commandfrom
: an object containing the user that issued the commandchannel
: 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.
It started off as the basis for ghebot, a bot to assist in monitor and alerting for GitHub Enterprise. ghee is now the underlying framework for ghebot. Also, it's clear to use and smooth as butter.