ittf-pingpong
Version:
Unofficial API to retrieve player rankings and statistics from ITTF (International Table Tennis Federation) affiliated members and events.
91 lines (90 loc) • 5.33 kB
TypeScript
/// <reference path="./globals.d.ts" />
export declare class ittfPingPong {
private currentTop100RankingsUrl;
private currentRankingsApi;
private playerProfileUrl;
private allPlayersUrl;
private historicalRankingsUrl;
private allCountriesUrl;
private playerMatchesUrl;
private genderMap;
private ageMap;
private categoryMap;
private readonly keys;
static currentGender: readonly ["M", "W", "X"];
static currentCategory: readonly ["S", "D", "DI"];
static currentType: readonly ["YOU", "SEN"];
static isValidGender(value: any): value is typeof ittfPingPong.currentGender[number];
static isValidCategory(value: any): value is typeof ittfPingPong.currentCategory[number];
static isValidType(value: any): value is typeof ittfPingPong.currentType[number];
private isPositiveInteger;
private isAlphabetic;
private top100WTTFrontdoor;
private remainingRanksWTTApi;
/**
* Fetch the current rankings.
* @param {string} type - The type of rankings ('YOU' | 'SEN') All 3 youth competition types lumped together (U15, U18, U21), Seniors
* @param {string} gender - Gender ('M' | 'W' | 'X') Man, woman, mixed (doubles only)
* @param {string} category - Category ('S' | 'D' | 'DI') Singles, doubles ranking (pairs), doubles ranking (individual)
* @param {number | string} topN - Only positive integers (e.g., 1, 2, 3, ...) or 'all'. Defaults to 100.
* @param {number} requestDelay - Only positive integers. Defaults to 2000 (2 second delay)
*
* @returns {Promise<Rankings>}
*
* @throws {Error} if invalid inputs/invalid input combinations are used (gender 'X' can only be used with category 'D' & 'DI') or fetch/server errors occur
*
* @example
*
* // Valid :
* await currentRankings('SEN', 'M', 'S', 10);
* // output: Array of top 10 ranked senior male players in the singles category
* await currentRankings('YOU', 'W', 'D');
* // output: Array of top 100 ranked youth female players in the doubles category
*
*/
currentRankings(type: typeof ittfPingPong.currentType[number], gender: typeof ittfPingPong.currentGender[number], category: typeof ittfPingPong.currentCategory[number], topN?: number | 'all', requestDelay?: number): Promise<Rankings>;
/**
* Fetch the player's IttfId given their name.
* @param {object} searchName The name parameters, all mutually exclusive - you can only enter one of playerFullName, playerGivenName, or playerFamilyName.
* @param {FullName} [searchName.playerFullName] Player's family name and given name. Ensure that the family name is placed before the given name. (e.g. "FAN Zhendong", "CALDERANO Hugo")
* @param {GivenName} [searchName.playerGivenName] Player's given name(s) only.
* @param {FamilyName} [searchName.playerFamilyName] Player's family name.
*
* @returns {Promise<Array<PlayerId>>} Returns an Array containing PlayerID objects {IttfId : string, PlayerFamilyNameFirst : string}
* @throws {Error} When multiple search methods are used together or fetch/server errors occur.
*
* @example
*
* // Valid:
* playerIttfId({ playerFullName: 'FAN Zhendong' });
* // output: {IttfId:"121404", PlayerFamilyNameFirst: "FAN Zhendong"}
* playerIttfId({ playerFamilyName: 'Lebrun'});
* // output: [{IttfId:"132992", PlayerFamilyNameFirst:"LEBRUN Alexis"},{IttfId:"135977", PlayerGivenName:"LEBRUN Felix"}]
*
*
* // Invalid:
* playerIttfId({ fullName: 'FAN', givenName: 'Zhendong' });
* Input the full name with the family name, then the given name. (e.g. "FAN Zhendong", "LEBRUN Alexis")
*
*/
playerIttfId(searchName: FullName | GivenName | FamilyName): Promise<Array<PlayerId>>;
/**
* Fetch the player's yearly match totals.
* @param {object} searchMethod The search parameters, mutually exclusive - you can only enter one of playerFullName or playerIttfId.
* @param {PlayerFullName} [searchMethod.playerFullName] Player's family name and given name. Ensure that the family name is capitalized and placed before the given name. (e.g. "FAN Zhendong", "CALDERANO Hugo")
* @param {IttfId} [searchMethod.playerIttfId] 0-6 digit integer. (e.g. 121404 - FAN Zhendong)
* @param {boolean} [options.includeExtendedDetails] If set to true, provides full player profile details rather than the base properties. Default value false.
*
* @returns {Promise<Stats>} Returns a player Stats object {player : PlayerProfile | PlayerExtendedProfile, ranking : RankingHistory, stats : GameStatistics}
* @throws {Error} When multiple search methods are used together or fetch/server errors occur. Only input the playerFullName or the playerIttfId - not both.
*
* @example
* // Valid:
* playerProfile({ playerFullName: 'FAN Zhendong' });
* // output: {player: {IttfId:"121404", Org:"CHN", Gender:"M",...}, ranking: {LastPos:[{...}], BestPos:[{...},{...},...]}, stats: {total:{[...]}, indiv:{[...]}, doubles:{[...]}}}
* playerProfile({ playerIttfId: 121404});
* // output: {player: {IttfId:"121404", Org:"CHN", Gender:"M",...}, ranking: {LastPos:[{...}], BestPos:[{...},{...},...]}, stats: {total:{[...]}, indiv:{[...]}, doubles:{[...]}}}
*
*/
playerProfile(searchMethod: PlayerFullName | IttfId, options?: ProfileOptions): Promise<Stats>;
}