nodeICHC

A node.js module to interact with the "I Can Haz Chat" API for the purpose of creating bots.

Dependencies

superagent - Run npm install superagent in console.

Usage

Including the module is simple. Just a single line is needed. Update the path to ICHC.js relative to your script.

var ICHC = require('./ICHC.js');

Creating a bot

Calling the ICHC function creates a new bot. It takes a single parameter of an object of configuration options:

* = optional

user - The username of your bot
apiKey - The API key for your account (Don't have an API key? get one!)
room - The room your bot will join
_pingInterval_* - How often your bot will poll the server in ms. Default: 2000 (2 seconds)
_pingTimeout_* - Number of failed pings before the bot is considered disconnected. Default: 30
_autoReconnect_* - Should the bot try to reconnect when disconnected? Default: true
_reconnectInterval_* - How often to attempt reconnects in ms. Default: 30000 (30 seconds)
_debug_* - Enables debug logging of all requests/repsonses from the server. Default: false

Here's an example:

var bot = ICHC({
    user: 'someusername',
    apiKey: 'someapikey',
    room: 'someroom'
});

Bot functions

These functions allow you to control your bot. All functions are chainable. All success/fail callback functions can use this as a reference to the bot.

* = optional

.connect(_success_, _fail_)** - Connects the bot to the room
- success* - Success callback function
- fail* - Fail callback function

bot.connect();

.send(message, _success_, _fail_)** - Sends a message or command to the room
- message - Message or command to send
- success* - Success callback function
- fail* - Fail callback function

bot.send('Hello world!');

.whisper(username, message, _success_, _fail_)** - Shortcut for /msg
- username - Username to whisper to
- message - Message to send
- success* - Success callback function
- fail* - Fail callback function

bot.whisper('SomeUser', 'Pssst! Hey you!');

.pm(username, message, _success_, _fail_)** - Shortcut for /privmsg
- username - Username to PM
- message - Message to send
- success* - Success callback function
- fail* - Fail callback function

bot.pm('SomeUser', 'Hello there!');

.on(eventType, eventHandler) - Binds an event handler to one or more events
- eventType - A string of one or more event types. For multiple events, seperate them by spaces
- eventHandler - Function to handle this event. The function should accept one parameter, which is an object of data about the event

// binding to a single event
bot.on('message', function(data){
    console.log('Chat message recieved from ' + data.username + ': ' + data.message);
});

// binding to multiple events
bot.on('message whisper pm', function(data){
    console.log('Some kind of message recieved from ' + data.username + ': ' + data.message);
});

.off(_eventType_, _eventHandler_)** - Unbinds an event handler to one or more events
- eventType* - A string of one or more event types. For multiple events, seperate them by spaces. If this parameter is left out, it will remove all event handlers from all events
- eventHandler* - A reference to a specific event handler function. If this parameter left out, it will remove all event handlers bound to the event type

// unbinding a single event
bot.off('message', someHandler);

// unbinding all 'message' events
bot.off('message');

// unbinding all events
bot.off();

Event types

Here is a list of all available event types for .on and .off with descriptions of the data they pass to the event handler function. All event handlers can use this as a reference to the bot.

All events have at least one data property eventType, which contains the name of the event type that was triggered.

connect - Fires when the bot connects to the room
- (no extra event data)
disconnect - Fires when the bot is disconnected from the room
- (no extra event data)
ping - Fires whenever a ping is made to the server
- (no extra event data)
message - Fires when a message is recieved in chat
- username - The username who sent the message
- message - The message body
- emote - A boolean value whether or not the message was an emote (/me)
whisper - Fires when the bot recieves a whisper
- username - The username who sent the whisper
- message - The message body
pm - Fires when the bot recieves a PM
- username - The username who sent the PM
- message - The message body
userJoin - Fires when a user joins the room
- username - The username who joined
userQuit - Fires when a user leaves the room
- username - The username who left
userKick - Fires when a user is kicked from the room
- username - The username who was kicked
- kickedBy - The username who kicked that user
userCamUp - Fires when a user cams up
- username - The username who cammed up
userCamDown - Fires when a user cams down
- username - The username who cammed down
send - Fires when the bot sends a message
- message - The message that was sent
error - Fires when an error occurs
- message - Message containing information about the error

nderscore / nodeICHC