Chess.com NPM | npm.io

Chess.com

A nodeJS package that utilises the internal API for chess.com, allowing for verbose live-updating information.

Features:

Search for a user
Fetch user's information
Fetch user's past games
Fetch user's live/ongoing games
Fetch user's variants stats
Fetch user's status

Benefits:

Supports variants
Information is updated real-time with the chess.com servers (as opposed to every x time frame with the public API)

TODO:

Additions:

Add fetching leader-boards
Add get user's friends
Add support for clubs
Add support for leagues
Add game fetching for variants

Bug fixes:

Fix unable to view some live games issue

Simple usage:

const { Standard } =  require("chesscom");

Standard.Search("Hikaru").then(async  users  =>{

let hikaru = users[0];

let profile =  await Standard.User(hikaru.username);

console.log(profile);

  

let stats =  await Standard.Stats(hikaru.username);

console.log(stats);

})

Documentation:

Standard:

DecodeMoves(moveList)

Params:

moveList - string (The string provided by Standard.Game()

Description:

Decodes the moveList provided by Standard.Game()

See Returns

Usage:

const { Standard } =  require("chesscom");

  

Standard.Games('some-user').then(async  games  => {

let chosenGame = games[0];

  

let game =  await Standard.Game(chosenGame.id);

let moves = Standard.DecodeMoves(game.game.moveList);

console.log(moves);

	/*
		[
			{ "from": "..", "to": ".."},
			...
		]
	*/
})

Game(gameId, type)

Params:

gameId - string/int (The ID provided by Standard.Games())

type - string (Can be one of Standard.GAMES)

Description:

Gets information on a game from Standard.Games()

See Returns

Usage:

const { Standard } =  require("chesscom");  

Standard.Games('some-user').then(async  games  => {
	let chosenGame = games[0];
	
	let game =  await Standard.Game(chosenGame.id);
	console.log(game);

	/*
		{
			{
				"game": {
					"id",
					"initialSetup",
					"plyCount",
					"startTime",
					"endTime",
					"colorOfWinner",
					...
				},
			"players": {
				...
			}
		}
	*/
})

Games(username, live)

Params:

username - string (The Chess.com username) live - boolean (Whether to look for user's live games. Can be used to get a user's status)

Description:

Gets a list of recent games played by user.

See Returns

See Returns - Live Games

Usage:

const { Standard } =  require("chesscom");  

Standard.Games('some-user').then(games  => {
	console.log(games);
	/*
		[
			{
				"id",
				"fen",
				"daysPerTurn",
				"moves",
				"user1Rating",
				"user2Rating",
				"user1Result",
				"user2Result",
				...
			},
			...
		]
	*/
})

Standard.Games('some-user').then(liveGames => {
	console.log(liveGames);
	/*
		{
			"id",
			"status",
			"statusAt",
			"updatedAt",
			"activity",
			"activityContext",
			...
	}
	*/
})

Search(username, live)

Params:

username - string (The Chess.com username)

Description:

Gets a list of users that match the username query.

See Returns

Usage:

const { Standard } =  require("chesscom");  

Standard.Search('some-username').then(users => {
	console.log(users);
	/*
		[
			{
				"uuid",
				"name",
				"fair_play_vetted_time",
				"id",
				"country_id",
				"avatar_url",
				"member_url",
				"last_login_date",
				"location",
				"username",
				...
			},
			...
		]
	*/
})

Stats(username)

Params:

username - string (The Chess.com username)

Description:

Gets the specified user's standard chess statistics.

See Returns

Usage:

const { Standard } =  require("chesscom");  

Standard.Stats('some-username').then(stats => {
	console.log(stats);
	/*
		{
			"stats": [
				{
					"key",
					"stats": {
						"rating",
						"highest_rating",
						"highest_rating_date",
						"rating_time_change_days",
						"rating_time_change_value",
						"total_game_count",
						"total_win_count",
						"total_loss_count",
						"total_draw_count",
						"avg_opponent_rating",
						"highest_opponent_rating",
						...
					},
				},
				...
			],
			...
		}
	*/
})

User(username)

Params:

username - string (The Chess.com username)

Description:

Gets the specified user's profile information.

See Returns

Usage:

const { Standard } =  require("chesscom");  

Standard.User('some-username').then(user => {
	console.log(user);
	/*
		{
			"avatarUrl",
			"bestRating",
			"bestRatingType",
			"chessTitle",
			"isEnabled",
			"isStaff",
			"isGuest",
			"countryId",
			"membership",
			...
		}
	*/
})

Variants:

An introduction.

Variants are different to the Standard section of this package. This is for two reasons: 1. They are completely different types of chess 2. There are technical differences between accessing each type of data

Rest assured, accessing variants data can be done. However, it requires user authentication (email + password + username). This is due to the fact that chess.com Variants make use of web sockets to load data, whereas the Standard versions make use of simple HTTP Get requests.

It is relatively simple to get variants working, I just would like to point out why the package requires your chess.com email, username and password. In fact, I recommend you to go through the package and check that your information is not stored or transferred in any way before providing it with any personal information. The only time your data is used is here, to log on and get your PHPSESSID cookie.

Initialisation:

Here is some boilerplate code for initialising the variant side of the package:

const { Variants } =  require("chesscom");

(async () =>{
	//Initialise the variant manager
	let VariantManager = new Variants()
	await VariantManager.Init();
})()

There are two ways to provide the package with your email, username and password: 1. (Recommended) Make use of environment variables and set them as EMAIL, USERNAME and PASSWORD respectively. 2. Pass them to the VariantManager.Init() function directly:

const { Variants } =  require("chesscom");

(async () =>{
	//Initialise the variant manager
	let VariantManager = new Variants('some_email', 'some_password', 'some_username')
	await VariantManager.Init();
})()

This may take some time to perform as it uses puppeteer, although it will only need to be performed once, or every few hours depending on how often the variant manager is used (It is all handled internally, so do not worry about re-initialising your Variant manager).

Stats(username)

Not to be confused with Standard.Stats()

Params:

username - string (The Chess.com username)

Description:

Gets the specified user's variant stats.

See Returns

Usage:

const { Variants } =  require("chesscom");

(async () =>{
	//Initialise the variant manager
	let VariantManager = new Variants('some_email', 'some_password', 'some_username')
	await VariantManager.Init();//Or use environment variables

	let stats = await VariantManager.Stats('Hikaru')
})()