Skip to content
Newer
Older
100644 172 lines (98 sloc) 7.36 KB
dbe272b @AvianFlu [docs] Updated readme for v0.1.0.
AvianFlu authored Oct 5, 2011
1 # kohai - pluggable irc bot for managing real-time data events
2
3 *I am Kohai, semi-useful communications-facilitating pseudointelligence!*
4
5
6 [http://twitter.com/NodeKohai](http://twitter.com/NodeKohai)
7
8 ##v0.1.0 - Overview
9
10 Kohai is a communications-facilitating pseudointelligence (sometimes called a 'bot') used for managing real-time data events. Kohai makes use of the [Hook.io](http://github.com/hookio/hook.io) framework to separate its I/O concerns and provide for greater extensibility and interoperability with new and different sources of real-time data.
11
12 Kohai, out of the box, is a set of four hooks:
5ea30d5 @AvianFlu [docs] Format edit to ReadMe.md
AvianFlu authored Oct 6, 2011
13
14 - Hook.io-IRC, for IRC connectivity
15 - Hook.io-Twitter, for Twitter API access
16 - Hook.io-Mailer, for sending support emails
17 - Kohai itself, containing the bot's core, IRC command logic, and hook.io event bindings
dbe272b @AvianFlu [docs] Updated readme for v0.1.0.
AvianFlu authored Oct 6, 2011
18
19 ## Installation
20
21 git clone git://github.com/nodejitsu/kohai.git
22 cd kohai
23 npm install
24 node bin/kohai
25
26
27 `kohai` will now start up and connect to its default channels on irc.freenode.net.
28
29 ## Got Ideas? Got Issues?
30
31 Check out our [Issue Tracker](https://github.com/nodejitsu/kohai/issues), we have a lot of open issues being worked on. Feel free to add feature requests as well.
32
33 ## Configuration
34
35 All `kohai` configuration settings are stored in a `config.json` file. `kohai` ships with a `config.json` file that contains the proper structure and default values for `kohai`'s configuration. The IRC connection data provided by default is valid, but the Twitter and Bit.ly credentials provided are not. If these services are desired, valid credentials will need to be obtained before they are used. HTTP 401 errors being returned from the Twitter API are an indication of bad credentials.
36
37 While kohai is running, users with administrative access may send private messages to kohai to alter configuration data on the fly. This is described in more detail [below](#config)
38
39 Please note that unlike most `kohai` commands, the !config command is only available when messaging `kohai` directly, rather than when sending a message to a channel `kohai` is in.
40
41 ## Setting up Twitter
42
43 By default, the `config.json` will not contain any Twitter API keys. You'll need to setup:
44
45 `auth.twitter.consumer_key`
46
47 `auth.twitter.consumer_secret`
48
49 `auth.twitter.access_token_key`
50
51 `auth.twitter.access_token_secret`
52
53 [Here is a link with further information on getting these keys from Twitter](https://dev.twitter.com/apps/new)
54
55 ### Tracking keywords on Twitter
56
57 `track` - array of keywords to search for on Twitter
58
59 "track" : [
60 "#nodejs", "node.js", "@nodejitsu", "@nodekohai", "nodejitsu", "#nodejitsu", "#nodeconf", "#jsconf", "dnode"
61 ]
62
63 The Twitter Streaming API can take a variety of parameters, including specific user IDs to follow and bounded location boxes for tracking tweets from specific geographic areas. Please see Twitter's extensive API documentation for more information.
64
65 ###Dynamic Twitter Rate-Limiting
66
67 `kohai` has been designed to get its Twitter feed out of the way when an active conversation starts up in a joined channel, and keeps a rolling average of messages per second to achieve this.
68
69 In addition to the rate-limiting, `kohai` also implements a Levenshtein-based similar tweet filter - each new incoming tweet is checked against recent tweets, and any tweet closer than the filter distance will be suppressed. This means a big reduction in spam from retweets and bots! The exact filtering level can be adjusted:
70
71 !config set twitFilter <number>
72
73 The default is 25; values between 10 and 40 are recommended for ordinary spam filtering purposes.
74
75 ## Simple role-based access control
76
77 Kohai's configuration file contains an object called `access` with three arrays: `admin`, `employee`, and `friend`. These are the three possible levels of access, in descending order. On an incoming IRC message, the user's nickname (and, optionally, their ident status with nickserv) is checked against these lists - without matching a name from the proper access level, the trigger command will not be executed.
78
79 ### Adding Users to the whitelist by IRC handle
80
81 While `kohai` is running, an administrator can add any desired user to any level of the whitelist.
82
83 !config add access:admin AvianFlu
84 !config add access:employee leetcoder5
85
86 <a name="config"></a>
87 ### Notable Administrator IRC Triggers
88
89 /msg kohai !config <add|rm|set|get|save> <path:in:config> <value to set or add>
90
91 Allows for alteration of `kohai`'s configuration data on the fly. Due to the verbosity of many responses, configuration is conducted via private messages to `kohai`. Options will take effect immediately, but `config save` is required to persist `kohai`'s settings to disk. For example:
92
93 !config add access:friend someguy
94 !config get access:friend
95 !config save
96
97 Would add "someguy" to the admin whitelist, show the whitelist to the user the command came from, and save the new config to disk.
98
99 !op/!deop/!voice/!devoice/!ban/!unban <user>
100
101 Perform the associated IRC action - again, `kohai` must be an op. Please note that `!ban` also kicks the banned user.
102
103 !join/!part <channel>
104
105 Joins or leaves the specified IRC channel.
106
107 !gtfo
108
109 Tells `kohai` to shutdown
110
111 ### Employee-level commands
112
113 !kick <user>
114
115 Kicks the specified user from the current channel.
116
117 !stfu <user> <mute length in seconds>
118
119 Temporarily mutes a user (IRC mode +q). Requires `kohai` to be an op in the specified channel.
120
121 ### Friend-level commands
122
123 !tweet <message>
124
125 Tweets message from configured Twitter account
126
127 !insult <user>
128
129 Insults a user with one of several random insults
130
131 ### Commands with no access control
132
133 !help
134
135 Displays a list of available help topics.
136
137 ## Extending Kohai
138
139 ### Adding commands
140
141 Every time `kohai` starts, `lib/plugins` will be read, and `require()` will be called on every `.js` file found there. To add a command that only exports one function:
142
143 var mycommand = module.exports = function (data, command) {
144 if (!data.friend) {
145 // Check if the message came from a user with a proper access level.
146 return false;
147 }
148 // From here, all properties of the kohai object can be accessed.
149 this.emit('sendMsg', { dest: data.to, msg: 'Hi everybody!' });
150 }
151
152 If you'd rather export multiple commands from the same file, this is supported as well - but note that the command will be `!methodName`, rather than the name of the file/object.
153
154 If multiple methods of the same name are attempted to be loaded as commands, only the first will be loaded. If the file in question throws when it is required, it will similarly be skipped.
155
156 ### Adding event listeners for other Hook.io hooks
157
158 Kohai will also read all the `.js` files in `lib/listeners` on startup - rather than loading the functions to be run in the future, however, they will just be run once on startup to add the event listeners in question.
159
160 var init = module.exports = function () {
161 var self = this;
162 self.on('*::eventName', function (data, callback) {
163 // Do something with data
164 return callback(null); // This is an over-the-wire callback.
165 });
166 }
167
168 Once again, access to the main `kohai` object is preserved, and if multiple methods are exported, each method will be run.
169
170 ##Contributors:
171
172 ### Charles McConnell, Marak Squires, Bradley Meck, Jacob Chapel, samsonjs, slickplaid, micrypt, and others
Something went wrong with that request. Please try again.