Skip to content

API (outdated)

Jump to bottom
Daniel Bugl edited this page Aug 12, 2014 · 1 revision

Table of Contents

API

Client(stream)

Initialize a new IRC client with the given duplex stream.

write(str, fn)

Writes the raw line str to the stream and calls fn() when this chunk of data is flushed.

client.write('PRIVMSG #channel: Why hello there');

getUser(nick)

Get the [User object] representing the user by the given nick. If no n nick is given, the function will return the [User object] representing the client.

client.getUser('foo');

getChannel(name, network)

Get the [Channel object] representing the channel by the given name.

client.getChannel('#foo', 'testnetwork');

pass(pass, fn)

Sends the password pass to the server.

client.pass('topsecret');

nick(nick, fn)

Specify an irc nick for the user.

client.nick('maggin');

user(username, realname, fn)

Used at the beginning of connection to specify the username and realname of a new user.

client.user('maggin', 'maddin');

invite(name, channel, fn)

Send an invite to name, for a channel. name can either be a string or a [User object].

client.invite('maggin', '#dev');

send(target, msg, fn)

Send a msg to the target. target can either be a string, a [User object] or a [Channel object]. If the message exceeds the Length of 512 Chars, it will be splitted into Multiple Lines.

client.send('foo', 'Why hello there');
client.send('#foo', 'Why hello there');
client.send(client.getUser('foo'), 'Why hello there');
client.send(client.getChannel('#foo', 'testnetwork'), 'Why hello there');

notice(target, msg, fn)

Send a msg as a notice to the target. target can either be a string, a [User object] or a [Channel object]. If the message exceeds the Length of 512 Chars, it will be splitted into Multiple Lines.

client.notice('foo', 'Why hello there');
client.notice('#foo', 'Why hello there');
client.notice(client.getUser('foo'), 'Why hello there');
client.notice(client.getChannel('#foo', 'testnetwork'), 'Why hello there');

join(channels, fn)

Join channel(s). channels can either be a string, or an array.

client.join('#foo');
client.join(['#foo', '#bar']);

part(channels, msg, fn)

Leave channel(s) with optional msg. channels can either be a string, or an array.

client.part('#foo', 'So long');
client.part(['#foo', '#bar']);

topic(channel, topic, fn)

Change or view the Topic of channel. channel can either be a string or a [Channel object]. If the topic parameter is present, the topic for channel will be changed. If the topic parameter is an empty string, the topic for that channel will be removed.

client.topic('#foo', 'So long');
client.topic(client.getChannel('#foo', 'testnetwork'));

kick(channels, nicks, msg, fn)

Kick nick(s) from channel(s) with optional msg. channels can either be a string, or an array. nicks can either be a string, or an array.

client.kick('#foo', 'bar', 'So Long');
client.kick(['#foo', '#bar'], 'bar', 'So Long');
client.kick(['#foo', '#bar'], ['foo', 'bar'], 'So Long');

quit(msg, fn)

Disconnect from the server with optional msg.

client.quit('So Long');

oper(name, password, fn)

Used to obtain operator privileges. The combination of name and password are required to gain Operator privileges. Upon success, a 'mode' event will be emitted.

client.oper('foo', 'bar');

mode(target, flags, params, fn)

Used to set a user's mode or channel's mode for a user. target can either be a string, a [User object] or a [Channel object].

client.mode('#foo', '+o', 'bar');
client.mode(client.getChannel('#foo', 'testnetwork'), '+o', 'bar');

names(channel, fn)

Fetch names for channel and invoke fn(names).

channel can either be a string or a [Channel object].

See names for what names will look like.

use(fn)

Use the given plugin fn.

client.use(require('./plugins/foo')());

getServerInfo()

Returns the Info we recieved in the RPL_YOURHOST, RPL_CREATED & RPL_ISUPPORT messages as an object. The object might look something like this:

{
    "servername": 'irc.foo.bar',
    "version": 'InspIRCd-2.0',
    "created": [Date object],
    "supports": {
        "AWAYLEN": "200",
        "CASEMAPPING": "rfc1459",
        "CHANMODES": "beg,k,FJLfjl,ABMRScimnprstz"
        "CHARSET": "ascii"
        //[...]
    }
}

whois(target, fn, network)

Used to query for whois info of target and invoke fn(err, data). If fn is not given, the method will call the whois event.

See whois for what data will look like.

client.whois('foo');
client.whois('foo', function (err, data) {
    //process data.
});

Events

"away" (event)

Client will emit away when we recieve the RPL_AWAY message, which happens either when we sent a PRIVMSG to a client which is away, or when we query WHOIS information about particular user.

event.user is a [User object], representing the user who is away. event.message is the away message.

client.on('away', function (event) {
    console.log(event.user.getNick() + ' is away: ' + event.message);
});

"data" (parsed)

Client will emit data whenever we recieve a line from the server.

parsed is the parsed message as an object, containing prefix, command, params, trailing and the original string.

client.on('data', function (parsed) {
    /*
    Original Message:
    :hitchcock.freenode.net NOTICE * :*** Looking up your hostname...\r\n
    Parsed object:
    {
        "prefix": "hitchcock.freenode.net",
        "command": "NOTICE",
        "params": "*"
        "trailing": "*** Looking up your hostname..."
        "string": ":hitchcock.freenode.net NOTICE * :*** Looking up your hostname..."
    }
    */
});

"invite" (event)

Client will emit invite when we recieve the INVITE message, which happens when we invite someone or when we get invited.

event.channel is a [Channel object], representing the Channel where event.user got invited to. event.user is a [User object], representing the user who sent the invite. event.target is a [User object], representing the user who got invited.

client.on('invite', function (event) {
    console.log(event.target.getNick() + ' got invited to join ' + event.channel.getName());
});

"join" (event)

Client will emit join when we recieve the JOIN message, which happens when someone (possibly us) joins a channel.

event.user is a [User object], representing the user who joined event.channel. event.channel is a [Channel object], representing the Channel where event.user joined.

client.on('join', function (event) {
    console.log(event.user.getNick() + ' joined ' + event.channel.getName());
});

"kick" (event)

Client will emit kick when we recieve the KICK message, which happens when someone gets kicked out of a channel.

event.channel is a [Channel object], representing the Channel where someone got kicked. event.user is a [User object], representing the user who got kicked. event.by is a [User object], representing the user who kicked event.user. event.reason is either the comment, or the nick of event.user.

client.on('kick', function (event) {
    console.log(event.by.getNick() + ' kicked ' + event.user.getNick() + ' from ' + event.channel.getName() + '. Reason: ' + event.reason);
});

"mode" (event)

Client will emit mode when we recieve the MODE message, which happens when someone changes the mode of a user or a channel.

event.channel is either a [Channel object], representing the channel which the mode is being set on/in, or null when a user mode was changed. event.by is either a [User object], representing the user setting the mode, or a string if the mode was not changed by a user. event.argument is the nick of the user, if the mode is being set on a user, or null if there was no argument. event.adding is either true of false, depending on if the mode was set or removed. event.mode is the single character mode indentifier.

client.on('mode', function (event) {
    console.log('[' + event.channel.getName() + '] ' + event.by.getNick() + ' sets the mode ' + (event.adding ? '+' : '-') + event.mode + ' on ' + event.argument);
});

"motd" (motd)

Client will emit motd after we recieve the RPL_ENDOFMOTD or ERR_NOMOTD message, which happens when we connect to a server.

motd the the Message of the Day the server sent, as array, seperated by line. Starting with

foo.bar.net message of the day

and ending with

End of message of the day.

client.on('motd', function (motd) {
    motd.forEach(function (line) {
        console.log('[MOTD]' + motd);
    });
});

"names" (event)

Client will emit names after we recieve the RPL_ENDOFNAMES message, which happens after we joined a channel.

event.channel is a [Channel object] representing the channel. event.names is an object where the key is a nick, and the value an array of modes the user has in the channel.

event.names will look something like this:

{
    "foo": [],
    "bar": ['~', '@']
    "baz": ['@']
}

"nick" (event)

Client will emit nick after we recieve the NICK message, which happens when a user (propably us) changes his nick.

event.user is a [User object], representing the user who changed his nick. event.oldNick is the old nick of the user as a string.

client.on('nick', function (event) {
    console.log(event.oldNick + ' is now known as ' + event.user.getNick());
});

"notice" (event)

Client will emit notice after we recieve the NOTICE message, which happens when someone sent a notice to us, or to a channel.

event.from is either a [User object], representing the user who sent the notice, or a string if its not sent by a user (e.g the server). event.to is the recipient of the notice as a string. event.message is the message.

client.on('notice', function (event) {
    console.log(event.from + ' => ' event.to + ': ' + event.message);
});

"part" (event)

Client will emit part after we recieve the PART message, which happens when someone leave one or multiple channels.

event.user is a [User object], representing the user who left the channel. event.channels is an array of [Channel object] with the the channels the user left. event.message is the message the user sent when leaving the channels.

client.on('part', function (event) {
    console.log(event.user.getNick() + ' left ' + event.channels.join(', ') + '. Message: ' + event.message);
});

"ping"

Client will emit ping after we recieve the PING message, which happens at regular intervals if no other activity detected coming from a connection.

Please note that the PONG reply is sent automatically.

client.on('ping', function () {
    console.log('PONG \o/');
});

"message" (event)

Client will emit message after we recieve the PRIVMSG message which is sent to a channel.

event.channel is a [Channel object], representing the channel which recieved the message. event.user is a [User object], representing the user who sent the message. event.message is the message the user sent. event.isAction is either true if the message was sent as an ACTION, or false if not.

client.on('message', function (event) {
    if (event.isAction) {
        console.log('[' + event.channel.getName() '] * ' + event.user.getNick() + ' ' + event.message);
    } else {
        console.log('[' + event.channel.getName() '] ' + event.user.getNick() + ': ' + event.message);
    }
});

"privatemessage" (event)

Client will emit privatemessage after we recieve the PRIVMSG message which is sent to us.

event.user is a [User object], representing the user who sent the message. event.message is the message the user sent. event.isAction is either true if the message was sent as an ACTION, or false if not.

client.on('privatemessage', function (event) {
    if (event.isAction) {
        console.log('[PM] * ' + event.user.getNick() + ' ' + event.message);
    } else {
        console.log('[PM] ' + event.user.getNick() + ': ' + event.message);
    }
});

"quit" (event)

Client will emit quit after we recieve the QUIT message, which happens when someone leaves the server.

event.user is a [User object], representing the user who quit. event.message is the message the user sent when leaving the server.

client.on('quit', function (event) {
    console.log(event.user.getNick() + ' left the Server: ' + event.message);
});

"topic" (event)

Client will emit topic after we recieve the RPL_TOPIC message (which is sent after we join a channel), or after the topic got manually changed.

event.channel is a [Channel object], representing the channel. event.user is a [User object], representing the user who changed/set the topic. event.topic is the topic that was set as a string. event.time is a [Date object] of the time the topic was changed. event.changed is either true if the topic got changed, or false if we recieved the topic after we joined a channel.

client.on('topic', function (event) {
    console.log('Topic for ' + event.channel.getName() + ' is: ' + event.topic);
    console.log('Topic for ' + event.channel.getName() + ' set by ' + event.user.getNick() + ' (' + event.time + ')');
});

"welcome" (event)

Client will emit welcome after we recieve the initial RPL_WELCOME message.

event.nick is a string with the nick we use. event.message is the welcome message the server sent to us.

client.on('welcome', function (event) {
    console.log('Welcome, ' + event.nick + '! ' + event.message);
});

"welcome" (event)

Client will emit welcome after we recieve the initial RPL_WELCOME message.

event.nick is a string with the nick we use. event.message is the welcome message the server sent to us.

client.on('welcome', function (event) {
    console.log('Welcome, ' + event.nick + '! ' + event.message);
});

"whois" (err, data)

Client will emit whois after we recieve the final RPL_ENDOFWHOIS, ERR_NEEDMOREPARAMS, ERR_NOSUCHSERVER, or ERR_NOSUCHNICK message. The data depends on the information the server sent to us.

event.nick is a string with the nick we use. event.message is the welcome message the server sent to us.

client.on('whois', function (err, data) {
    //err === null || err === 'No such nick/channel' || err === 'No such server' || err === 'Not enough parameters'
    //data = [Object object]
});

data might look like this:

{
    "nick": "foo",
    "username": "bar",
    "hostname": "some.host",
    "realname": "baz",
    "channels": {
        "#foo": [],
        "#bar": ['~', '@'],
        "&baz": ['%']
    },
    "server": "some.irc.server",
    "serverInfo": "Server Info",
    "idle": 1076,
    "signon": [Date object],
    "oper": true,
    "account": "foo",
    "registered": true,
    "secure": true
}

User(nick, client)

Represents a User by the given nick. Please use client.getUser('some_nick') to get a User object, and not new User('some_nick', client). Please note that most of these information is recieved through parsing the whois event data. Coffea itself won't whois automatically, so you have to do it yourself in order to get these information.

toString()

Returns the User as a string with the format nick!username@hostname.

console.log(user.toString());
//some_nick!user_name@host.com

console.log(user);
//some_nick!user_name@host.com

getNick()

Get the Nickname of the User.

console.log(user.getNick());
//some_nick

getUsername()

Get the Username of the User.

console.log(user.getUsername());
//user_name

getRealname()

Get the Real name of the User.

console.log(user.getRealname());
//Some Name

getHostname()

Get the Host of the User.

console.log(user.getHostname());
//some.host.com

getChannels()

Get a List of Channels the user is currently in, with possible modes.

console.log(user.getChannels());
//{'#foo': ['~'], '#bar': []}

getServer()

Get the Server the User is connected to.

console.log(user.getServer());
//some.server.net

getServerInfo()

Get the Info message of the Server the user is connected to.

console.log(user.getServerInfo());
//Lorem Ipsum

getAway()

Get the Away message of the user, or null if the User is not away.

console.log(user.getAway());
//null

getAccount()

Get the Account the User is registered to, or null if the User is not registered/logged in.

console.log(user.getAccount());
//foo

isRegistered()

Returns true if the User is Registered, false if not.

console.log(user.isRegistered());
//true

isUsingSecureConnection()

Returns true if the User is Connected using SSL, false if not.

console.log(user.isUsingSecureConnection());
//true

getIdle()

Get the Users idle time in seconds.

console.log(user.getIdle());
//123

getSignonTime()

Get The Signon time as Date object.

console.log(user.getSignonTime().getTime());
//1396293728439

isOper()

Returns true if the User is an IRC operator, false if not.

console.log(user.isOper());
//false

notice(msg)

Sends a notice msg to the user.

user.notice('Why hello there');

say(msg)

Sends a message msg to the user.

user.say('Why hello there');

whois(fn)

Used to query for whois info of the user and invoke fn(err, data).

See whois for what data will look like.

user.whois(function (err, data) {
    //process data.
});

Channel(name, client)

Represents a Channel by the given name. Please use client.getChannel('#foo') to get a Channel object, and not new Channel('#foo', client).

toString()

Returns the Channel name.

console.log(channel.toString());
//#foo

getName()

Returns the Channel name.

console.log(channel.getName());
//#foo

getTopic()

Returns the Channel topic as object, containing the Topic itself, a User object representing the User who set the Topic, and a Date object representing the time the topic was set.

console.log(channel.getTopic());
//{
//    "topic": "The Channel topix goes here",
//    "user": [User object],
//    "time": [Date object]
//}

getNames()

Returns a List of Nicks that are currently in the channel, with possible modes.

console.log(channel.getName());
//{'foo': ['~'], 'bar': ['%'], 'baz': []}

userHasMode(user, mode)

Returns true if user has the usermode mode in the channel, false if otherwise. user can either be a string or a [User object].

console.log(channel.userHasMode('foo', '~'));
//false

isUserInChannel(user)

Returns true if user is in the channel, false if otherwise. user can either be a string or a [User object].

console.log(channel.isUserInChannel('foo'));
//false

notice(msg)

Sends a notice msg to the channel.

channel.notice('Why hello there');

say(msg)

Sends a message msg to the channel.

channel.say('Why hello there');

reply(user, msg)

Sends a reply msg to a user into the channel. user can either be a string or a [User object].

channel.reply('foo', 'Why hello there');
//foo: Why hello there

kick(user, reason)

Kicks user out of the channel with the given reason. user can either be a string or a [User object].

channel.kick('foo', 'Get out!');

ban(mask)

Sets the mode +b for mask in the channel.

channel.ban('foo!bar@baz.com');

unban(mask)

Sets the mode -b for mask in the channel.

channel.unban('foo!bar@baz.com');

Clone this wiki locally