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