PluginAPI

The API is subject of change as the bot is being updated.

Accessing the API

// Gets the irc object from global.
var irc = global.irc;

API calls

irc.config

This is the container for the config file. Base bot configuration is stored here. To see all the values inside of irc.config see the configuration wiki page.

// Outputs the bot's nick.
console.log(irc.config.nick);
// Outputs the server's address.
console.log(irc.config.address);

irc.users

This is the container for the users.json file. All information about the users should be stored here. To see all the values inside of irc.users see the configuration wiki page.

// A failsafe for when the user 'nick' does not exist in the users.
/* WARNING: If this does not exist and the user does not exist in the users,
 * the bot will throw an exception when you access it's values! */
if (typeof irc.users['nick'] === 'undefined') {
  irc.users['nick'] = {};
}

// Outputs the foobar value of the user 'nick'. Checks if the value exists.
if (typeof irc.users['nick'] === 'undefined') {
  console.log('The value foobar does not exist for nick.');
} else {
  console.log(irc.users['nick'].foobar);
}

irc.debug

Boolean value saying if debug output is wanted. For example, in the bot core, incoming and outgoing messages are considered debug information.

if (irc.debug) console.log(debug); // Only output debug if wanted, Good!
console.log(debug); // Always output debug, Bad!

irc.check_level(nick, level, callback)

Gets if the user with the nick is marked as having the specified level in the users configuration. The method also checks if the user is logged in to the server to ensure that it is the real user and not someone pretending to be him/her.

// Checks if the user foobar has admin rights.
irc.check_level('foobar', 'admin', function (is_admin) {
  if (is_admin) {
    // foobar has admin rights.
  } else {
    // foobar does not have admin rights.
  }
});

irc.is_admin(nick, callback)

It is advised to use irc.check_level(nick, 'admin', callback) instead as removing this function is discussed in issue #19.
Gets if the user with the nick is marked as admin in the users configuration. The method also checks if the user is logged in to the server to ensure that it is the real user and not someone pretending to be him/her.

// Checks if the user foobar has admin rights.
irc.is_admin('foobar', function (is_admin) {
  if (is_admin) {
    // foobar has admin rights.
  } else {
    // foobar does not have admin rights.
  }
});

irc.is_owner(nick, callback)

It is advised to use irc.check_level(nick, 'owner', callback) instead as removing this function is discussed in issue #19.
Gets if the user with the nick is marked as owner in the users configuration. The method also checks if the user is logged in to the server to ensure that it is the real user and not someone pretending to be him/her.

// Checks if the user foobar has owner rights.
irc.is_owner('foobar', function (is_owner) {
  if (is_owner) {
    // foobar has owner rights.
  } else {
    // foobar does not have owner rights.
  }
});

irc.privmsg(target, msg)

Sends a message to the target. Can be used for sending to both channels or other users.

// Sends a message saying 'Hello world!' to the channel #foo.
irc.privmsg('#foo', 'Hello world!');

irc.act(options, callback)

This method is used to send raw messages. It sends a message off to the server including the information given in the options parameter. The callback function is called when the data is written out.

// Sends a message to the server saying that the bot want to join #channel.
irc.act({action: 'JOIN', params: ['#channel']}, function () {
  // This code will be executed when the data is sent.
});

irc.join(channel, callback)

Sends a JOIN message to the server.

// Joins the channel '#channel'.
irc.join('#channel', function () {
  // This code will be executed when the data is sent.
});

irc.part(channel, msg, callback)

Sends a PART message to the server to including the leave message.

// Leaves the channel '#channel' with the message 'Foo Bar...'.
irc.part('#channel', 'Foo Bar...', function () {
  // This code will be executed when the data is sent.
});

irc.nick(nick, callback)

Sends a NICK message to the server to change the bot's nick.

// Changes the nick of bot to 'foobar'.
irc.nick('foobar', function () {
  // This code will be executed when the data is sent.
});

irc.user(user, mode, realName, callback)

Sends a USER message to the server to change bot's username, mode and real name.

// Changes the username of bot to 'foobar', mode to '8' and real name to 'Foo Bar'.
irc.nick('foobar', '8', 'Foo Bar', function () {
  // This code will be executed when the data is sent.
});

irc.quit(msg, callback)

Sends a QUIT message to the server containing the given quit message.

// Quits with the quit message 'rm -rf /'.
irc.quit('rm -rf /', function () {
  // This code will be executed when the data is sent.
});

Internal API

These variables or functions do not require or should not have interaction with from the plugins themselves.

irc.auth_levels
Plugins do not need to directly interact with the authentication levels values. The authentication level array is used to determine the different authentication levels. It includes admin, owner in the master.

irc.command_char
Plugins do not need to directly interact with the command character value. The command character is the character the bot expects commands to begin with.

irc.emitter
Plugins do not need to directly interact with the emitter. The emitter is used for handling incoming messages.

irc.splitcmd(data)
Plugins do not need to directly interact with this function. The function parses the message data into an action, which is then given to the plugins' handlers.

irc._socket
Plugins should not directly interact with the socket. The socket is used for the basic connection to the server.

irc.plugins
Plugins should not directly interact with the plugins array. The array contains all the plugins loaded.