fix: minor bug fixes, typings and docs update (#73)

CHANGELOG.md

@@ -22,13 +22,3 @@ This new version is a complete TypeScript rewrite to convert everything from pla
 -   Internal Caching Options ([#53](https://github.com/clashperk/clashofclans.js/issues/53)) ([984451d](https://github.com/clashperk/clashofclans.js/commit/30ea3240c11866008d0dae514468c0fdbb34ffd0))
 -   Additional Properties for Player Units ([#65](https://github.com/clashperk/clashofclans.js/pull/65)) ([aa1696](https://github.com/clashperk/clashofclans.js/commit/aa1696243d96d4fed0250b4282c60522a6482343))
 
-### Links
-
--   Documentation
-    https://clashofclans.js.org/docs
-
--   Guide
-    https://clashofclans.js.org/guide
-
--   Updating to v2.0.0
-    https://clashofclans.js.org/docs/updating-to-v2

src/client/Client.ts

@@ -18,6 +18,7 @@ import {
 	RankedClan,
 	RankedPlayer,
 	Label,
+	SeasonRankedPlayer,
 	GoldPassSeason,
 	ClanWarLeagueGroup
 } from '../struct';
@@ -73,13 +74,13 @@ export class Client extends EventEmitter {
 	}
 
 	/** Search all clans by name and/or filtering the results using various criteria. */
-	public async getClans(options: ClanSearchOptions) {
-		const { data } = await this.rest.getClans(options);
+	public async getClans(query: ClanSearchOptions, options?: OverrideOptions) {
+		const { data } = await this.rest.getClans(query, options);
 		// @ts-expect-error
 		return data.items.map((clan) => new Clan(this, clan));
 	}
 
-	/** Get information about a clan. */
+	/** Get info about a clan. */
 	public async getClan(clanTag: string, options?: OverrideOptions) {
 		const { data } = await this.rest.getClan(clanTag, options);
 		return new Clan(this, data);
@@ -189,7 +190,7 @@ export class Client extends EventEmitter {
 		}
 	}
 
-	/** Get information about clan war league. */
+	/** Get info about clan war league. */
 	public async getClanWarLeagueGroup(clanTag: string, options?: OverrideOptions) {
 		const { data } = await this.rest.getClanWarLeagueGroup(clanTag, options);
 		return new ClanWarLeagueGroup(this, data);
@@ -205,7 +206,7 @@ export class Client extends EventEmitter {
 		return new ClanWar(this, data, { warTag: args.warTag, clanTag: args.clanTag, maxAge });
 	}
 
-	/** Get information about a player by tag. */
+	/** Get info about a player by tag. */
 	public async getPlayer(playerTag: string, options?: OverrideOptions) {
 		const { data } = await this.rest.getPlayer(playerTag, options);
 		return new Player(this, data);
@@ -232,8 +233,7 @@ export class Client extends EventEmitter {
 	/** Get Legend League season rankings by season Id. */
 	public async getSeasonRankings(seasonId: string, options?: SearchOptions) {
 		const { data } = await this.rest.getSeasonRankings(LEGEND_LEAGUE_ID, seasonId, options);
-		// @ts-expect-error
-		return data.items.map((entry) => new RankedPlayer(entry));
+		return data.items.map((entry) => new SeasonRankedPlayer(this, entry));
 	}
 
 	/** Get list of Clan War Leagues. */
@@ -248,25 +248,41 @@ export class Client extends EventEmitter {
 		return data.items.map((entry) => new Location(entry));
 	}
 
-	/** Get clan rankings for a specific location. */
+	/**
+	 * Get clan rankings for a specific location.
+	 *
+	 * For global ranking, use `global` as `locationId`.
+	 */
 	public async getClanRanks(locationId: number | 'global', options?: SearchOptions) {
 		const { data } = await this.rest.getClanRanks(locationId, options);
 		return data.items.map((entry) => new RankedClan(entry));
 	}
 
-	/** Get player rankings for a specific location. */
+	/**
+	 * Get player rankings for a specific location.
+	 *
+	 * For global ranking, use `global` as `locationId`.
+	 */
 	public async getPlayerRanks(locationId: number | 'global', options?: SearchOptions) {
 		const { data } = await this.rest.getPlayerRanks(locationId, options);
 		return data.items.map((entry) => new RankedPlayer(this, entry));
 	}
 
-	/** Get clan versus rankings for a specific location. */
+	/**
+	 * Get clan versus rankings for a specific location.
+	 *
+	 * For global ranking, use `global` as `locationId`.
+	 */
 	public async getVersusClanRanks(locationId: number | 'global', options?: SearchOptions) {
 		const { data } = await this.rest.getVersusClanRanks(locationId, options);
 		return data.items.map((entry) => new RankedClan(entry));
 	}
 
-	/** Get player versus rankings for a specific location. */
+	/**
+	 * Get player versus rankings for a specific location.
+	 *
+	 * For global ranking, use `global` as `locationId`.
+	 */
 	public async getVersusPlayerRanks(locationId: number | 'global', options?: SearchOptions) {
 		const { data } = await this.rest.getVersusPlayerRanks(locationId, options);
 		return data.items.map((entry) => new RankedPlayer(this, entry));

src/rest/HTTPError.ts

@@ -10,23 +10,28 @@ const messages: { [key: string]: string } = {
 
 const reasons: { [key: string]: string } = {
 	503: 'serviceUnavailable',
-	429: 'tooManyRequests',
+	429: 'requestThrottled',
 	400: 'badRequest',
-	403: 'forbidden',
-	500: 'unknownError',
+	403: 'accessDenied',
+	500: 'unknownException',
 	404: 'notFound',
 	504: 'requestAborted'
 };
 
 /** Represents an HTTP Error. */
 export class HTTPError extends Error {
-	/** The message of this error. */
+	/** The message of this errored request. */
 	public message: string;
 
 	/** The HTTP method of this request. */
 	public method: string;
 
-	/** The reason of this error. */
+	/**
+	 * The reason of this errored request.
+	 *
+	 * Expected values are `notFound`, `notInWar`, `accessDenied`, `accessDenied.invalidIp`, `privateWarLog`,
+	 * `badRequest`, `requestThrottled`, `serviceUnavailable`, `requestAborted` and `unknownException`.
+	 */
 	public reason: string;
 
 	/** The HTTP status code of this request. */

src/rest/RESTManager.ts

@@ -36,12 +36,11 @@ export class RESTManager {
 	}
 
 	/** Search all clans by name and/or filtering the results using various criteria. */
-	public getClans(options: ClanSearchOptions) {
-		const query = Util.queryString(options);
-		return this.handler.request<APIClanList>(`/clans?${query}`);
+	public getClans(query: ClanSearchOptions, options?: OverrideOptions) {
+		return this.handler.request<APIClanList>(`/clans?${Util.queryString(query)}`, options);
 	}
 
-	/** Get information about a clan. */
+	/** Get info about a clan. */
 	public getClan(clanTag: string, options?: OverrideOptions) {
 		return this.handler.request<APIClan>(`/clans/${Util.encodeTag(clanTag)}`, options);
 	}
@@ -63,7 +62,7 @@ export class RESTManager {
 		return this.handler.request<APIClanWar>(`/clans/${Util.encodeTag(clanTag)}/currentwar`, options);
 	}
 
-	/** Get information about clan war league. */
+	/** Get info about clan war league. */
 	public getClanWarLeagueGroup(clanTag: string, options?: OverrideOptions) {
 		return this.handler.request<APIClanWarLeagueGroup>(`/clans/${Util.encodeTag(clanTag)}/currentwar/leaguegroup`, options);
 	}
@@ -73,7 +72,7 @@ export class RESTManager {
 		return this.handler.request<APIClanWar>(`/clanwarleagues/wars/${Util.encodeTag(warTag)}`, options);
 	}
 
-	/** Get information about a player by tag. */
+	/** Get info about a player by tag. */
 	public getPlayer(playerTag: string, options?: OverrideOptions) {
 		return this.handler.request<APIPlayer>(`/players/${Util.encodeTag(playerTag)}`, options);
 	}

src/struct/Clan.ts

@@ -105,7 +105,7 @@ export class Clan {
 		this.members = data.memberList?.map((mem) => new ClanMember(this.client, mem)) ?? []; // eslint-disable-line
 	}
 
-	/** Get {@link Player} information for every Player in the clan. */
+	/** Get {@link Player} info for every Player in the clan. */
 	public async fetchMembers(options?: OverrideOptions) {
 		return (await Promise.allSettled(this.members.map((m) => this.client.getPlayer(m.tag, { ...options, ignoreRateLimit: true }))))
 			.filter((res) => res.status === 'fulfilled')

src/struct/ClanWarLeagueGroup.ts

@@ -48,7 +48,7 @@ export class ClanWarLeagueClan {
 		this.members = data.members.map((mem) => new ClanWarLeagueClanMember(mem));
 	}
 
-	/** Get {@link Player} information for every members that are in the CWL group. */
+	/** Get {@link Player} info for every members that are in the CWL group. */
 	public async fetchMembers(options?: OverrideOptions) {
 		return (await Promise.allSettled(this.members.map((m) => this.client.getPlayer(m.tag, { ...options, ignoreRateLimit: true }))))
 			.filter((res) => res.status === 'fulfilled')

src/struct/PlayerClan.ts

@@ -3,24 +3,28 @@ import { Client } from '../client/Client';
 import { APIPlayerClan } from '../types';
 import { Badge } from './Badge';
 
-/** Represents a player's clan. */
+/** Represents a Player's clan. */
 export class PlayerClan {
 	/** Name of the clan. */
 	public name: string;
 
 	/** Tag of the clan. */
 	public tag: string;
 
-	/** Level of this clan. */
-	public level: number;
+	/**
+	 * Level of this clan.
+	 *
+	 * This property is not available for ranked player's clan.
+	 */
+	public level: number | null;
 
 	/** Badge of this clan. */
 	public badge: Badge;
 
 	public constructor(private readonly _client: Client, data: APIPlayerClan) {
 		this.name = data.name;
 		this.tag = data.tag;
-		this.level = data.clanLevel;
+		this.level = data.clanLevel ?? null; // eslint-disable-line
 		this.badge = new Badge(data.badgeUrls);
 	}
 

src/struct/Ranking.ts

@@ -6,7 +6,46 @@ import { Location } from './Location';
 import { League } from './League';
 import { Badge } from './Badge';
 
-/** Represents the player of leader-board ranking. */
+/** Represents the Player of seasonal legend league leader-board ranking. */
+export class SeasonRankedPlayer {
+	/** The player's name. */
+	public name: string;
+
+	/** The player's tag. */
+	public tag: string;
+
+	/** The player's experience level. */
+	public expLevel: number;
+
+	/** The player's trophy count. */
+	public trophies: number;
+
+	/** The player's attack wins. */
+	public attackWins: number;
+
+	/** The player's defense wins. */
+	public defenseWins: number;
+
+	/** The player's rank in the clan leader-board. */
+	public rank: number;
+
+	/** The player's clan. */
+	public clan: PlayerClan | null;
+
+	public constructor(client: Client, data: Omit<APIPlayerRanking, 'league'>) {
+		this.name = data.name;
+		this.tag = data.tag;
+		this.rank = data.rank;
+		this.expLevel = data.expLevel;
+		this.trophies = data.trophies;
+		this.attackWins = data.attackWins;
+		this.defenseWins = data.defenseWins;
+		// @ts-expect-error
+		this.clan = data.clan ? new PlayerClan(client, data.clan) : null;
+	}
+}
+
+/** Represents the Player of location based leader-board ranking. */
 export class RankedPlayer {
 	/** The player's name. */
 	public name: string;
@@ -35,11 +74,11 @@ export class RankedPlayer {
 	/** The player's rank in the clan leader-board. */
 	public rank: number;
 
-	/** The player's rank before the last leader-board change. */
-	public previousRank: number;
+	/** The player's rank before the last leader-board change. If retrieving info for legend league season, this will be `null`.  */
+	public previousRank: number | null;
 
 	/** The player's clan. */
-	public clan: PlayerClan;
+	public clan: PlayerClan | null;
 
 	/** The player's league. If retrieving info for versus leader-boards, this will be `null`. */
 	public league!: League | null;
@@ -59,14 +98,15 @@ export class RankedPlayer {
 		// @ts-expect-error
 		this.versusBattleWins = data.versusBattleWins ?? null;
 		this.rank = data.rank;
-		this.previousRank = data.previousRank;
-		this.clan = new PlayerClan(client, data.clan);
+		this.previousRank = data.previousRank ?? null; // eslint-disable-line
+		// @ts-expect-error
+		this.clan = data.clan ? new PlayerClan(client, data.clan) : null;
 		// @ts-expect-error
 		this.league = data.trophies ? new League(data.league ?? UNRANKED_LEAGUE_DATA) : null; // eslint-disable-line
 	}
 }
 
-/** Represents the clan of leader-board ranking. */
+/** Represents the Clan of location based leader-board ranking. */
 export class RankedClan {
 	/** The clan's name. */
 	public name: string;

src/types/index.ts

@@ -306,7 +306,7 @@ export interface APIPlayerRanking {
 	defenseWins: number;
 	rank: number;
 	previousRank: number;
-	clan: APIPlayerClan;
+	clan?: Omit<APIPlayerClan, 'clanLevel'>;
 	league: APILeague;
 }
 
@@ -342,7 +342,7 @@ export interface APIPlayerVersusRanking {
 	versusBattleWins: number;
 	rank: number;
 	previousRank: number;
-	clan: APIPlayerClan;
+	clan?: APIPlayerClan;
 }
 
 // *************** LEAGUES *************** //