Inner-chess NPM

Inner-chess

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

Features:

Free game review

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 get user's friends~~ DONE
~~Add get user's achievements~~ DONE
Add fetching leader-boards

Add support for clubs

Add support for leagues

Add game fetching for variants

Bug fixes:

Fix unable to view some live games issue
~~Speed up achievements for players with large numbers of them~~ DONE

Simple usage:

const { Chess } = require("inner-chess");

let chess = new Chess();

chess.Search("some-user").then(async  users  =>{
	let user = users[0];

	let profile = await  chess.User(user.username);
	console.log(profile);

	let stats = await  chess.Stats(user.username);
	console.log(stats);
})

Documentation:

Uncredentialed endpoints:

Achievements(username)

Params:

username - string (The Chess.com username)

Description:

Gets a list of a user's achievements.

See Returns

Usage:

const { Chess } = require("inner-chess");

let chess = new Chess();

chess.Achievements('some-user', true).then(liveGames  => {
	console.log(liveGames);
})

DecodeMoves(moveList)

Params:

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

Description:

Decodes the moveList provided by chess.Game()

See Returns

Usage:

const { Chess } = require("inner-chess");

let chess = new Chess();

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

Game(gameId, type)

Params:

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

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

Description:

Gets information on a game from chess.Games()

See Returns

Usage:

const { Chess } = require("inner-chess");

let chess = new Chess();

chess.Games('some-user').then(async  games  => {
	let  chosenGame = games[0];

	let  game = await  chess.Game(chosenGame.id);
	console.log(game);
})

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 { Chess } = require("inner-chess");

let chess = new Chess();

chess.Games('some-user').then(games  => {
	console.log(games);
})

chess.Games('some-user', true).then(liveGames  => {
	console.log(liveGames);
})

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 { Chess } = require("inner-chess");

let chess = new Chess();

chess.Search('some-username').then(users  => {
	console.log(users);
})

Stats(username)

Params:

username - string (The Chess.com username)

Description:

Gets the specified user's standard chess statistics.

See Returns

Usage:

const { Chess } = require("inner-chess");

let chess = new Chess();

chess.Stats('some-user').then(stats  => {
	console.log(stats);
})

User(username)

Params:

username - string (The Chess.com username)

Description:

Gets the specified user's profile information.

See Returns

Usage:

const { Chess } = require("inner-chess");

let chess = new Chess();

chess.User('some-user').then(user  => {
	console.log(user);
})

Credentialed Endpoints:

An introduction.

Credentialed endpoints are different to the first section of this package. This is for two reasons:

They require credentials to access the data
There are technical differences between accessing each type of data

Rest assured, accessing credentialed data can be done.

However, it requires user authentication (email + password + username).

It is relatively simple to get credentialed endpoints working.

But before that, 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 { Chess } = require("inner-chess");

(async () => {
	//Initialise the variant manager
	let chess = new Chess()

	await chess.Init();
})()

There are two ways to provide the package with your email, username and password:

(Recommended) Make use of environment variables and set them as EMAIL, USERNAME and PASSWORD respectively. See here
Pass them to the Chess constructor directly:

const { Chess } = require("inner-chess");

(async () =>{
	//Initialise the variant manager
	let chess = new Chess('some-email', 'some-password', 'some-username');

	await chess.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).

Optionally you do not have to run chess.Init() as if a credentialed function is ran, it will automatically initialise it. However this adds time to the function call, so it is recommended that you initialise before the package is used.

Evaluate(moveList)

Params:

moveList - string (The Chess.com game moveList)

Description:

Gets the specified user's friends.

See Returns

Usage:

const { Chess } = require("inner-chess");

(async () => {
	//Initialise the variant manager
	let chess = new Chess('some-email', 'some-password', 'some-user')//Or use environment variables

	let games = await chess.Games("some-user");
	let game = await chess.Game(games[0].id);

	await chess.Init();

	let evaluation = await chess.Evaluate(game.game.moveList)
	console.log(evaluation);
})()

Friends(username)

Params:

username - string (The Chess.com username)

pages - integer (Number of pages of friends to get, defaults to Infinity)

avatarSize - integer (Size of returned friends' avatars, defaults to 64)

Description:

Gets the specified user's friends.

See Returns

Usage:

const { Chess } = require("inner-chess");

(async () => {
	//Initialise the variant manager
	let chess = new Chess('some-email', 'some-password', 'some-user')//Or use environment variables

	await chess.Init();

	let friends = await chess.Friends('some-user')
	console.log(friends);
})()

VariantStats(username)

Not to be confused with chess.Stats()

Params:

username - string (The Chess.com username)

Description:

Gets the specified user's variant stats.

See Returns

Usage:

const { Chess } = require("inner-chess");

(async () => {
	//Initialise the variant manager
	let chess = new Chess('some-email', 'some-password', 'some-user')//Or use environment variables

	await chess.Init();

	let stats = await chess.VariantStats('some-user')
	console.log(stats);
})()