Skip to content

Latest commit

 

History

History
1705 lines (1190 loc) · 32.2 KB

API.md

File metadata and controls

1705 lines (1190 loc) · 32.2 KB

API Reference

Options

Client options are the object you provide when you create a new client instance:

const options = {/* available options are described below */};

const client = new Client(options);

option: authMethod

The auth method to use with a supplied username and password. Defaults to NickServ if omitted.

The authentication method to use.

  • NickServ - Non-standard nickserv authentication.
  • sasl - SASL PLAIN auth. Errors out if SASL fails.
  • saslThenNickServ - Try SASL PLAIN, but fallback to NickServ if it fails.
const client = new Client({
  nick: "user", // will be used as username
  password: "password",
});
const client = new Client({
  nick: "user",
  username: "SaslUser",
  password: "password",
  authMethod: "sasl",
});

option: bufferSize

Size of the buffer that receives data from server.

Default to 4096 bytes.

const client = new Client({
  bufferSize: 512,
});

option: channels

Channels to join on connect.

Joins #channel once registered:

const client = new Client({
  channels: [
    "#channel",
  ],
});

Joins #channel1 and #channel2 once registered:

const client = new Client({
  channels: [
    "#channel1",
    "#channel2",
  ],
});

Joins #channel with secret_key once registered:

const client = new Client({
  channels: [
    ["#channel", "secret_key"],
  ],
});

Joins #channel1 (without key) and #channel2 with secret_key once registered:

const client = new Client({
  channels: [
    "#channel1",
    ["#channel2", "channel_key"],
  ],
});

option: ctcpReplies

Replies to CTCP queries.

Default values set to:

const client = new Client({
  ctcpReplies: {
    clientinfo: true,
    ping: true,
    time: true,
    version: "deno-irc",
  },
});

Disables replies to CTCP PING and VERSION queries:

const client = new Client({
  ctcpReplies: {
    ping: false,
    version: false,
  },
});

Changes the version replied to CTCP VERSION:

const client = new Client({
  ctcpReplies: {
    version: "custom version name",
  },
});

option: floodDelay

Milliseconds to wait between dispatching private messages.

Defaults to 0 milliseconds (no delay).

const client = new Client({
  floodDelay: 2000,
});

option: joinOnInvite

Enables auto join on invite.

const client = new Client({
  joinOnInvite: true,
});

option: maxListeners

Number of maximum registrable listeners.

Primarily used to avoid memory leaks.

Default limit to 1000 listeners for each event.

const client = new Client({
  maxListeners: 100,
});

option: nick

The nick used to register the client to the server. Will be reused as username for auth if no username is supplied.

const client = new Client({
  nick: "Deno",
});

option: oper

Sets as operator on connect.

const client = new Client({
  oper: {
    user: "deno",
    pass: "secret",
  },
});

option: password

The password for the user account associated with the username field.

const client = new Client({
  password: "secret",
});

option: pingTimeout

Maximum timeout before to be disconnected from server.

Default to 30 seconds. false to disable.

const client = new Client({
  pingTimeout: 120,
});

option: realname

The realname used to register the client to the server.

const client = new Client({
  realname: "Deno IRC",
});

option: reconnect

Enables auto reconnect.

Takes a boolean or { attempts?: number, delay?: number, exponentialBackoff?: boolean }.

Default to false or { attempts: 10, delay: 5 } if set to true.

Tries to reconnect 10 times with a delay of 5 seconds between each attempt:

const client = new Client({
  reconnect: true,
});

Tries to reconnect 3 times with a delay of 10 seconds between each attempt:

const client = new Client({
  reconnect: {
    attempts: 3,
    delay: 10,
  },
});

Tries to reconnect 5 times with an initial delay of 3 seconds with an exponential backoff:

const client = new Client({
  reconnect: {
    attempts: 5,
    delay: 3,
    exponentialBackoff: true,
  },
});

option: resolveInvalidNames

Auto resolve invalid names (for nick and username).

const client = new Client({
  resolveInvalidNames: true,
});

option: serverPassword

const client = new Client({
  serverPassword: "password",
});

An optional server password that will be sent via the PASS command.

option: username

The username used to register the client to the server.

const client = new Client({
  username: "deno",
});

option: verbose

Prints informations to output.

Prints received and sent raw IRC messages:

const client = new Client({
  verbose: "raw",
});

Prints formatted events, commands and state changes:

const client = new Client({
  verbose: "formatted",
});

Uses a custom logger implementation:

const client = new Client({
  verbose: (payload) => {
    // use payload type for inference
    if (payload.type === "raw_input") {
      console.log(payload.msg);
    }
  }
});

Events

Events are simple messages which are emitted from the client instance.

They can be received by listening to their event names.

Client can subscribe to them using two distinct ways, client.on and client.once:

// The first allows to add a listener for a given event:
client.on("event_name", (eventPayload) => {});

// The second is used to add a one-time listener:
const eventPayload = await client.once("event_name");

// For both methods, you can subscribe to several events at the same time:
client.on(["event1", "event2", "event3"], (eventPayload) => {
  // but doing that requires to properly infer
  // the final type of the event payload.
});

Event payloads are the emitted objects of events and can contain source and params.

client.on("event_name", (msg) => {
  msg.source; // event payload source
  msg.params; // event payload params
});

Most of payloads contain source and provides information about the sender of the message.

If the source is provided, it always contains a name containing the server host or the nick name.

client.on("event_name", (msg) => {
  if (msg.source) {
    msg.source.name; // server host or nick name
  }
});

In case of source comes from user, it can also contain mask (if provided by the server):

client.on("event_name", (msg) => {
  if (msg.source?.mask) {
    msg.source.mask.user; // user name
    msg.source.mask.host; // user host
  }
});

Event payloads have a params object that contains parameters related to the event.

The shape of msg.params depends on the provided event name:

client.on("event_name", (msg) => {
  msg.params; // array of event parameters
});

See event details below to learn more about event params.

event: away_reply

User replies with an away message.

client.on("away_reply", (msg) => {
  msg.params.nick; // nick of the client who is away
  msg.params.text; // text of away message
});

event: connecting

Client is connecting to the server.

client.on("connecting", (remoteAddr) => {
  remoteAddr; // address of the server
});

event: connected

Client is connected to the server.

client.on("connected", (remoteAddr) => {
  remoteAddr; // address of the server
});

event: ctcp_action

User sends an action.

client.on("ctcp_action", (msg) => {
  msg.params.target; // target of the CTCP ACTION
  msg.params.text; // text of the CTCP ACTION
});

event: ctcp_clientinfo

User queries a CTCP CLIENTINFO to a target.

client.on("ctcp_clientinfo", (msg) => {
  msg.params.target; // target of the CTCP CLIENTINFO query
});

event: ctcp_clientinfo_reply

User replies to a CTCP CLIENTINFO.

client.on("ctcp_clientinfo_reply", (msg) => {
  msg.params.supported; // array of supported commands by the user
});

event: ctcp_time

User queries a CTCP TIME to a target.

client.on("ctcp_time", (msg) => {
  msg.params.target; // target of the CTCP TIME query
});

event: ctcp_time_reply

User replies to a CTCP TIME.

client.on("ctcp_time_reply", (msg) => {
  msg.params.time; // date time of the user
});

event: ctcp_ping

User pings the client.

client.on("ctcp_ping", (msg) => {
  msg.params.target; // target of the CTCP PING query
  msg.params.key; // key of the CTCP PING query
});

event: ctcp_ping_reply

User replies to the CTCP PING to the client.

client.on("ctcp_ping_reply", (msg) => {
  msg.params.key; // key of the CTCP PING repl
  msg.params.latency; // latency (in milliseconds)
});

event: ctcp_version

User queries a CTCP VERSION to a target.

client.on("ctcp_version", (msg) => {
  msg.params.target; // Target of the CTCP VERSION query
});

event: ctcp_version_reply

User replies to a CTCP VERSION.

client.on("ctcp_version_reply", (msg) => {
  msg.params.version; // client version of the user
});

event: disconnected

Client has been disconnected from the server.

client.on("disconnected", (remoteAddr) => {
  remoteAddr; // address of the server
});

event: error

Client emits a fatal error.

client.on("error", (error) => {
  error.name; // name describing the error
  error.message; // message describing the error
  error.type; // type of the error
});

When an error is emitted, it will be thrown by default and causes a crash of the program.

To avoid the client from crashing, it is required to have at least one event listener for the "error" event name.

By listening to the "error" event, errors will no longer be thrown:

client.on("error", console.error);

Even better, you can handle them by checking error.type property:

client.on("error", (error) => {
  switch (error.type) {
    case "connect": {
      // errors while connecting
    }
    case "read": {
      // errors while receiving messages from server
    }
    case "write": {
      // errors while sending messages to server
    }
    case "close": {
      // errors while closing connection
    }
  }
});

This behavior is heavily inspired by the Node.js error handling.

An early crash prevents loosing useful informations when the client tries something without success.

event: error_reply

Server sends an error to the client.

client.on("error_reply", (msg) => {
  msg.params.args; // arguments of the error
  msg.params.text; // description of the error
});

event: invite

User invites the client to a channel.

client.on("invite", (msg) => {
  msg.params.nick; // nick who was invited
  msg.params.channel; // channel where the nick was invited
});

event: isupport

Server sends ISUPPORT parameter to the client.

Supported events:

  • isupport:usermodes
  • isupport:chanmodes
  • isupport:prefix
  • isupport:chantypes
client.on("isupport:chanmodes", (msg) => {
  msg.params.value; // value of the current ISUPPORT parameter
});

event: join

User joins a channel.

client.on("join", (msg) => {
  msg.params.channel; // channel joined by the user
});

event: kick

User kicks another user.

client.on("kick", (msg) => {
  msg.params.channel; // channel where the nick is kicked
  msg.params.nick; // nick who is kicked
  msg.params.comment; // optional comment of the kick
});

event: kill

User kills another user.

client.on("kill", (msg) => {
  msg.params.nick; // nick who is killed
  msg.params.comment; // comment of the kill
});

event: list_reply

Server sends all channel list.

client.on("list_reply", (msg) => {
  msg.params.channels; // the entire channel list

  for (const channel of msg.params.channels) {
    channel.name; // name of the channel
    channel.count; // client count
    channel.topic; // topic of this channel
  }
});

event: mode

Server changes a user mode or a channel mode.

client.on("mode", (msg) => {
  msg.params.target; // target of the MODE, can be either a channel or a nick
});

You can only listen for user modes or channel modes:

client.on("mode:user", (msg) => {/* only user modes */});

client.on("mode:channel", (msg) => {/* only channel modes */});

event: mode_reply

Server replies to a MODE query.

client.on("mode_reply", (msg) => {
  msg.params.target; // target of the MODE, can be either a channel or a nick
  msg.params.modes; // all the modes currently set
});

You can only listen for user mode replies or channel mode replies:

client.on("mode_reply:user", (msg) => {/* only user mode replies */});

client.on("mode_reply:channel", (msg) => {/* only channel mode replies */});

event: motd_reply

Server sends the message of the day.

client.on("motd_reply", (msg) => {
  msg.params.motd; // message of the day (MOTD)
});

event: myinfo

Server sends informations related to the server configuration.

client.on("myinfo", (msg) => {
  msg.params.server; // server informations
  msg.params.usermodes; // server user modes
  msg.params.chanmodes; // server channel modes
});

event: names_reply

Server sends the names list of a channel.

client.on("names_reply", (msg) => {
  msg.params.channel; // name of the channel
  msg.params.names; // nicknames joined to this channel
});

For a ready to use nicklist, see nicklist.

event: nick

User changes its nick.

client.on("nick", (msg) => {
  msg.params.nick; // new nick used by the user
});

event: nicklist

Server sends a updated nicklist of a channel.

client.on("nicklist", (msg) => {
  msg.params.channel; // name of the channel
  msg.params.nicklist; // nicknames joined to this channel

  for (const user of msg.params.nicklist) {
    user.prefix; // prefix of the user
    user.nick; // nick of the user
  }
});

event: notice

Server or user notifies a target.

client.on("notice", (msg) => {
  msg.params.target; // target of the NOTICE, can be either a channel or a nick
  msg.params.text; // text of the NOTICE
});

You can only listen for channel notices or private notices:

client.on("notice:channel", (msg) => {/* only channel notices */});

client.on("notice:private", (msg) => {/* only private notices */});

event: part

User leaves a channel.

client.on("part", (msg) => {
  msg.params.channel; // channel left by the user
  msg.params.comment; // optional comment of the PART
});

event: ping

Server pings the client.

client.on("ping", (msg) => {
  msg.params.keys; // keys of the PING
});

event: pong

Server replies to PING to the client.

client.on("pong", (msg) => {
  msg.params.daemon; // daemon of the PONG
  msg.params.key; // key of the PONG
  msg.params.latency; // latency (in milliseconds)
});

event: privmsg

User sends a message to a channel or client.

client.on("privmsg", (msg) => {
  msg.params.target; // target of the PRIVMSG, can be either a channel or a nick
  msg.params.text; // text of the PRIVMSG
});

You can only listen for channel messages or private messages:

client.on("privmsg:channel", (msg) => {/* only channel messages */});

client.on("privmsg:private", (msg) => {/* only private messages */});

event: quit

User leaves the server.

client.on("quit", (msg) => {
  msg.params.comment; // optional comment of the QUIT
});

event: raw

Client sends a raw message.

client.on("raw", (raw) => {
  raw.source; // origin of the raw message
  raw.command; // raw command
  raw.params; // raw parameters
});

You can target any raw commands with "raw:*" pattern:

client.on("raw:join", (msg) => {
  // JOIN message
});

// similar to
client.on("raw", (msg) => {
  if (msg.command === "join") {
    // JOIN message
  }
});

event: raw_ctcp

Raw CTCP Query

User sends a CTCP to a target.

Supported query events:

client.on("raw_ctcp:ping", (msg) => {
  msg.params.supported; // name of the CTCP command
});

Raw CTCP Reply

User replies to a CTCP.

Supported reply events:

client.on("raw_ctcp:ping_reply", (msg) => {
  msg.params.supported; // name of the CTCP command
});

event: reconnecting

Client tries to reconnect to the server.

client.on("reconnecting", (remoteAddr) => {
  remoteAddr; // address of the server
});

event: register

Server confirms that the client has been registered.

This event is useful to ensures that client connection is ready to receive commands.

client.on("register", (msg) => {
  msg.params.nick; // nick who is registered
  msg.params.text; // text of the RPL_WELCOME
});

event: topic

User changes the topic of a channel.

client.on("topic", (msg) => {
  msg.params.channel; // channel where the topic is set
  msg.params.topic; // new topic of the channel
});

event: topic_reply

Server replies with the topic of a channel.

client.on("topic_reply", (msg) => {
  msg.params.channel; // channel where the topic is set
  msg.params.topic; // new topic of the channel
});

event: topic_who_time_reply

Server replies with the topic informations of a channel.

client.on("topic_who_time_reply", (msg) => {
  msg.params.channel; // channel where the topic is set
  msg.params.who; // user who set the topic
  msg.params.time; // date time of the topic
});

event: whois_reply

Server replies to a WHOIS command.

client.on("whois_reply", (msg) => {
  msg.params.nick; // nick
  msg.params.host; // hostname
  msg.params.username; // user name
  msg.params.realname; // real name
  msg.params.channels; // channels joined
  msg.params.idle; // idle time
  msg.params.server; // server where the user is connected
  msg.params.serverinfo; // informations of the connected server
  msg.params.operator; // optional user operator message
  msg.params.away; // optional away message
});

Commands

Commands are the way to send messages to the server.

They can be sent by just calling them.

command: action

Sends an action message text to a target.

action(target: string, text: string): void

client.action("#channel", "says hello");

client.action("someone", "says hello");

command: away

To be marked as being away.

away(text?: string): void

client.away("I'm busy");

client.away(); // to be no longer marked as being away

command: back

To be no longer marked as being away.

Same as client.away().

back(): void

client.back(); // to be no longer marked as being away

command: ban

Sets ban mask on channel.

Shortcut for mode.

ban(channel: string, mask: string, ...masks: string[]): void

client.ban("#channel", "nick!user@host");

client.ban(
  "#channel",
  "nick1!user@host",
  "nick2!user@host",
  "nick3!user@host",
);

command: cap

Sends a capability.

cap: (command: AnyCapabilityCommand, ...params: string[]) => void

client.cap("REQ", "capability");

command: clientinfo

Queries the supported CTCP commands of a target.

clientinfo(target: string): void

client.clientinfo("#channel");

command: connect

Connects to a server using a hostname and an optional port.

Default port to 6667.

If tls=true, attempts to connect using a TLS connection.

Resolves when connected.

async connect(hostname: string, port: number, tls?: boolean): Promise<Deno.Conn | null>

client.connect("host", 6667);

client.connect("host", 7000, true); // with TLS

command: ctcp

Sends a CTCP message to a target with a command and a param.

ctcp(target: string, command: AnyRawCtcpCommand, param?: string): void

client.ctcp("#channel", "TIME");

client.ctcp("#channel", "ACTION", "param");

For easier use, see also other CTCP-derived methods:

  • action
  • clientinfo
  • ping
  • time
  • version

command: dehalfop

Takes half-operator from nick on channel.

Shortcut for mode.

dehalfop(channel: string, nick: string, ...nicks: string[]): void

client.dehalfop("#channel", "nick");

client.dehalfop("#channel", "nick1", "nick2", "nick3");

command: devoice

Takes voice from nick on channel.

Shortcut for mode.

devoice(channel: string, nick: string, ...nicks: string[]): void

client.devoice("#channel", "nick");

client.devoice("#channel", "nick1", "nick2", "nick3");

command: deop

Takes operator from nick on channel.

Shortcut for mode.

deop(channel: string, nick: string, ...nicks: string[]): void

client.deop("#channel", "nick");

client.deop("#channel", "nick1", "nick2", "nick3");

command: disconnect

Disconnects from the server.

disconnect(): void

client.disconnect();

command: halfop

Gives half-operator to nick on channel.

Shortcut for mode.

halfop(channel: string, nick: string, ...nicks: string[]): void

client.halfop("#channel", "nick");

client.halfop("#channel", "nick1", "nick2", "nick3");

command: invite

Invites a nick to a channel.

invite(nick: string, channel: string): void

client.invite("someone", "#channel");

command: join

Joins channels with optional keys.

join(...params: ChannelDescriptions): void

client.join("#channel");

client.join(["#channel", "key"]);

client.join("#channel1", "#channel2");

client.join("#channel1", ["#channel2", "key2"]);

client.join(["#channel1", "key1"], "#channel2");

client.join(["#channel1", "key1"], ["#channel2", "key2"]);

client.join(["#channel1", "key1"], "#channel2", ["#channel3", "key3"]);

command: kick

Kicks a nick from a channel with an optional comment.

kick(channel: string, nick: string, comment?: string): void

client.kick("#channel", "someone");

client.kick("#channel", "someone", "Boom!");

command: kill

Kills a nick from the server with a comment.

kill(nick: string, comment: string): void

client.kill("someone", "Boom!");

command: list

Gets the list channels and their topics.

Replies with list_reply event when ended.

list(channels?: string | string[], server?: string): void

client.list();

client.list("#chan");

client.list("#chan", "host");

client.list(["#chan1", "#chan2"]);

client.list(["#chan1", "#chan2"], "host");

command: me

me(target: string, text: string): void

Sends an action message text to a target.

Alias of action.

client.me("#channel", "says hello");

client.me("someone", "says hello");

command: mode

Manages modes.

mode(target: string, modes?: string, ...args: string[]): void

Gets Modes:

client.mode("nick");

client.mode("#channel");

Sets Modes:

client.mode("nick", "+w");

client.mode("#chan", "e");

client.mode("#chan", "+v", "nick");

client.mode("#chan", "+iko", "secret", "nick");

command: motd

Gets the message of the day (MOTD) of the server.

Replies with motd_reply event when ended.

motd(): void

client.motd();

command: msg

Sends a message text to a target.

Alias of privmsg.

msg(target: string, text: string): void

client.msg("#channel", "Hello world");

client.msg("someone", "Hello world");

command: names

Gets the nicknames joined to a channel and their prefixes.

names(channels: string | string[]): void

client.names("#channel");

client.names(["#channel1", "#channel2"]);

command: nick

Sets the nick of the client (once connected).

nick(nick: string): void

client.nick("new_nick");

command: notice

Notifies a target with a text.

notice(target: string, text: string): void

client.notice("#channel", "Hello world");

client.notice("someone", "Hello world");

command: on

Adds a listener for the eventName.

on(eventName: T | T[], listener: Listener<InferredPayload<TEvents, T>>): () => void

client.on("event_name", (eventPayload) => {});

command: once

Adds a one-time listener for the eventName.

once(eventName: T | T[], listener: Listener<InferredPayload<TEvents, T>>): void

once(eventName: T | T[]): Promise<InferredPayload<TEvents, T>>

const eventPayload = await client.once("event_name");

command: op

Gives operator to nick on channel.

Shortcut for mode.

op(channel: string, nick: string, ...nicks: string[]): void

client.op("#channel", "nick");

client.op("#channel", "nick1", "nick2", "nick3");

command: oper

Sets the client as operator with a user and a password.

oper(user: string, password: string): void

client.oper("user", "pass");

command: part

Leaves the channel with an optional comment.

part(channel: string, comment?: string): void

client.part("#channel");

client.part("#channel", "Goodbye!");

command: pass

Sets the password of the server.

Registration only.

pass(password: string): void

client.pass("password");

command: ping

Pings the server or a given client target.

ping(target?: string): void

Pings the server:

client.ping();

Pings (CTCP) all clients from "#channel":

client.ping("#channel");

Pings (CTCP) a client "nick":

client.ping("nick");

command: privmsg

Sends a message text to a target.

privmsg(target: string, text: string): void

client.privmsg("#channel", "Hello world");

client.privmsg("someone", "Hello world");

command: quit

Leaves the server with an optional comment.

Resolves after closing link.

quit(comment?: string): Promise<void>

client.quit();

client.quit("Goodbye!");

command: send

Sends a raw message to the server.

Resolves with the raw message sent to the server, or null if nothing has been sent.

async send(command: AnyRawCommand, ...params: (string | undefined)[]): Promise<string | null>

client.quit();

client.quit("Goodbye!");

command: time

Queries the date time of a target.

time(target?: string): void

client.time();

client.time("#channel");

command: topic

Manages the topic of a channel.

topic(channel: string, topic?: string): void

Gets the topic of a channel:

client.topic("#channel");

Changes the topic of a channel:

client.topic("#channel", "New topic for #channel");

command: unban

Unsets ban mask on channel.

Shortcut for mode.

unban(channel: string, mask: string, ...masks: string[]): void

client.unban("#channel", "nick!user@host");

client.unban(
  "#channel",
  "nick1!user@host",
  "nick2!user@host",
  "nick3!user@host",
);

command: user

Sets the username and the realname.

Registration only.

user(username: string, realname: string): void

client.user("username", "real name");

command: version

Queries the client version of a target.

Queries the server if target is not provided.

version(target?: string): void

client.version();

client.version("someone");

command: voice

Gives voice to nick on channel.

Shortcut for mode.

voice(channel: string, nick: string, ...nicks: string[]): void

client.voice("#channel", "nick");

client.voice("#channel", "nick1", "nick2", "nick3");

command: whois

Gets the WHOIS informations of a nick:

whois(nick: string): void

client.whois("someone");

Gets the WHOIS informations of a nick for a given server:

whois(server: string, nick: string): void

client.whois("serverhost", "someone");