Constructor
The main object for interacting with the FICS server. Creates a new connection and handles all command processing. The client is an instance of EventEmitter that will forward all events from the raw socket, less the data event. This is useful for reconnecting in the event of a socket timeout.
var FICSClient = require("fics");
var fics = new FICSClient();
Public
An overridden on function that attaches handlers to the internal socket, except in the case of the data event.
Returns a FICSClient
(Returns this
for chaining.)
Public
Clears keep alive timeout, then removes all listeners from and ends the connection to the FICS server.
Public
A readable stream of all data from the socket connection to the FICS server. This should only be used for debugging and logging.
Returns a stream.Readable
(A stream of the raw data from socket)
Public
Logs in a user based on the provided data. Empty data will log the user in as a guest.
The returned promise will fail if there is a failure logging in.
Parameters:
Returns a Promise
(promise that will resolve with the user login information)
Public
Returns a promise that will notify with any shouts or tells that are received. This promise does not resolve automatically; the caller is expected to discard it.
Notifications appear in the following format:
{ type: {string} [it|shout|tell]
, user: {string} usernameOfSender
, message: {string} messageBody
, channel: {string} [channelIfTellToChannel] }
Returns a Promise
(Will notify as new messages are received.)
Public
Returns a promise that will resolve with a hash of channel data in the format of:
[{ number: {string} channelNumber
, name: {string} channelName
}
, ...
]
Returns a Promise
(The promise to be resolved with channel data)
Public
Retrieve a list of channels to which the logged in user is currently subscribed, returned as an array of strings representing the channel numbers
[ {string} channelNumber, ... ]
Returns a Promise
(A promise to be resolved)
Public
Adds the channel to the user's channel list.
Parameters:
Returns a Promise
(A promise that will be resolved with true
if the channel was successfully added or false
if it was already in the user's channel list)
Public
Removes the channel from the user's channel list.
Parameters:
Returns a Promise
(A promise that will be resolved with true
if the channel was successfully removed or false
if it was not in the user's channel list)
Public
Broadcast a message to a user or a channel.
Parameters:
recipient can be a number or a string.
(The channel number or username)
message must be a string.
(The message to send)
Returns a Promise
(A promise that will be resolved with true
if the message is successfully sent and false
otherwise.)
Public
Broadcast a message globally to all users listening to shouts.
Parameters:
message must be a string.
(The message to send)
it is optional and must be a boolean.
(Whether to broadcast as an it
message, a special kind of shout. Defaults to false
.)
Returns a Promise
(A promise that will be resolved with true
if the message is successfully sent and false
otherwise.)
Public
Returns a promise that will be resolved with users in the following format.
[{ name: {string} userName
, rating: {string} userRating
, status: {string} userStatus
, codes: {array} server
}
,...
]
Returns a Promise
(To be resolved with user data.)
Public
Returns a promise that will resolved with an array of data about current games on the server in the format:
[{ number: {string} gameNumber
, white: { name: {string} userName, rating: {string} userRating: time: {string} timeRemaining }
, black: { name: {string} userName, rating: {string} userRating: time: {string} timeRemaining }
, move: { color: {string} colorToMove, number: {string} moveNumber }
}
, ...
]
Currently does not capture games being examined and, e.g. lectures by LectureBot, so the length of the list is shorter than the length returned by the server.
Returns a Promise
(The promise to be resolved with game data)
Public
Observe a game currently in progress. The promise is notified of three events: the initial data for the game, updates as the game progresses, and any messages that are sent during the game.
{ white: { name: {string} userName, rating: {string} userRating }
, black: { name: {string} userName, rating: {string} userRating }
, rated: {boolean} isRated
, type: {string} gameType
, time: { initial: {string} clockInitial
, increment: {string} clockIncrement
} }
{ position: {string} fenPosition
, current: { color: {string} currentMoveColor
, move: {string} currentMoveNumber
}
, time: { white: {string} whiteTimeInSeconds
, black: {string} blackTimeInSeconds
}
, move: { verbose: {string} verboseLastMove
, algebraic: {string} algebraicLastMove
} }
{ user: {string} userName
, message: {string} messageText
, type: {string} kibitzOrWhisper }
{ result: {string} gameResult }
The promise will resolve after the game has been removed from the user's
oberservation list, either by being closed or by manually unobserve
ing it.
Parameters:
Returns a Promise
(A promise that will notify with game updates)
Public
Returns a promise to be resolved with the moves for a given game. The structure of the moves is an array of tuple arrays, e.g.
[ [{string} whiteMove, {string} blackMove]
, ...
, [{string} whitheMove]
]
Parameters:
Returns a Promise
(A promise that will return with the moves of the game)
Public
Get a list of all the observers currently watching a game.
Parameters:
Returns a Promise
(A promise that will return with the current observers)
Public
Send a message to all observers and players of a game.
Parameters:
gameNumber can be a string or a number.
(Number of the game)
message must be a string.
(The message to be broadcast)
Returns a Promise
(Resolved after message is sent.)
Public
Send a message to all observers of a game.
Parameters:
gameNumber can be a string or a number.
(Number of the game)
message must be a string.
(The message to be broadcast)
Returns a Promise
(Resolved after message is sent.)
Public
Stop observing a game.
Parameters:
Returns a Promise
(A promise that will resolve with true
if the game was removed from the observation list or false
if it was not in the observation list)
Public
Get an objecting representing all the games currently awaiting players.
The games will be presented in the following format:
[{ number: {string} gameNumber
, user: { name: {string} userName, rating: {string} userRating }
, time: { initial: {string} clockInitial, increment: {string} clockIncrement }
, rated: {boolean} isRated
, type: {string} gameType
, range: {string} allowedRatingRange
}
, ...
]
Returns a Promise
(A promise that will resolve with the structure of games.)
Private
Call the uptime
command every 59 minutes to keep the connection to the
server alive and prevent being kicked due to inactivity (espeically useful
when observing games)
Private
Creates a deffered object that processes raw data from the socket and notifies any promises created therefrom with each line of data.
This function also handles the joining of lines into logical lines before notifying the promise, i.e. combining output that spans over multiple lines.
Returns a Deferred
(A deferred object wrapping socket data output)
Private
Creates a new promise and then feeds each line of input to the provided callback. This allows a command to process the stream line-by-line until it determines that the promise can be discarded.
Parameters:
callback must be a function.
(A callback that will be attached to the promise)
doRemovePrompt is optional and must be a boolean.
(Whether or not to remove the FICS prompt when found at the beginning of a line)
Returns a Deferred
(The promise with attached callback)
Private
Sends a commands to the FICS server and receive output line by line. If no callback is provided, the command will execute and the returned promise will be resolved immediately.
Parameters:
command must be a string.
(The text of the command)
callback is optional and must be a function.
(An optional callback function to process lines)
Returns a Deferred
(The deferred object to be resolved)
Private
Issues a command, but enqueues it if another blocking command is already running, thus preventing issues with collisions in regular expressions. Other commands will continue to run uninterrupted.
Parameters:
command must be a string.
(The text of the command)
A must be a function.
(callback function to process lines)
Returns a Deferred
(The deferred object that needs to be resolved before the next command will be run.)
Private
sends a message with the approriate encoding and termination character
Parameters:
export the class
Private
Takes a position string like returned by FICS and transforms it into a FEN.
e.g.
from:
--Q----- -p---pkp p-----p- ----q--- P-p----- -----r-P ---R--PK --------
to:
2Q5/1p3pkp/p5p1/4q3/P1p5/5r1P/3R2PK/8
Parameters:
Returns a string
(A FEN string)
FICS
A promise-based library for interacting with the Free Internet Chess Server