Merge pull request #4 from FC5570/add-typedoc

feat: add typedoc, small changes

README.md

@@ -25,7 +25,7 @@ hypixel.ts is a [NodeJS](https://nodejs.org) module which allows you to interact
 
 **Node.js 14+ or newer is required**
 
-```sh-session
+```bash
 npm install hypixel.ts
 yarn add hypixel.ts
 pnpm add hypixel.ts

package.json

@@ -44,6 +44,7 @@
 		"husky": "^7.0.4",
 		"lint-staged": "^12.1.7",
 		"prettier": "^2.5.1",
+		"typedoc": "^0.22.10",
 		"typescript": "^4.5.4",
 		"vitest": "^0.0.141"
 	},

src/classes/Base.ts

@@ -1,6 +1,13 @@
 import type { Client } from '../lib/Client';
 
+/**
+ * The base class which other classes extend from.
+ */
 export class BaseClass {
+	/**
+	 * The client that instantiated this class.
+	 * @type {Client}
+	 */
 	public client: Client;
 	public constructor(client: Client) {
 		this.client = client;

src/classes/Player.ts

@@ -2,6 +2,10 @@ import { BaseClass } from './Base';
 import type { Client } from '../lib';
 import type { APIPlayer } from '../typings';
 
+/**
+ * Represents a Player class.
+ * @extends {BaseClass}
+ */
 export class Player extends BaseClass {
 	public _id?: string;
 	public uuid!: string;
@@ -67,18 +71,35 @@ export class Player extends BaseClass {
 		Object.assign(this, data);
 	}
 
+	/**
+	 * Get the friends of this player.
+	 * @param {boolean} [raw]: Whether to return the raw API data. Defaults to true.
+	 * @returns {Promise<import('../typings').GetPlayerFriendsRawResponse | Player[]>}
+	 */
 	public async getFriends(raw?: boolean) {
 		return this.client.players.getFriends(this.uuid, raw);
 	}
 
+	/**
+	 * Get the recently played games of this player.
+	 * @returns {Promise<import('../typings').GetRecentlyPlayedGamesResponse>}
+	 */
 	public get recentlyPlayedGames() {
 		return this.client.players.getRecentlyPlayedGames(this.uuid);
 	}
 
+	/**
+	 * Get the current status of the player.
+	 * @returns {Promise<import('../typings').GetStatusResponse>}
+	 */
 	public get status() {
 		return this.client.players.getStatus(this.uuid);
 	}
 
+	/**
+	 * Get the ranked skywars data of the player.
+	 * @returns {Promise<import('../typings').GetRankedSkywarsDataResponse>}
+	 */
 	public get rankedSkywarsData() {
 		return this.client.players.getRankedSkywarsData(this.uuid);
 	}

src/classes/SkyBlockProfile.ts

@@ -1,6 +1,5 @@
 import { BaseClass } from './Base';
 import type { Client } from '../lib';
-
 export interface APISkyBlockProfile {
 	profile_id: string;
 	members: Record<string, any>;
@@ -10,6 +9,10 @@ export interface APISkyBlockProfile {
 	game_mode: string;
 }
 
+/**
+ * Represents a SkyBlock profile.
+ * @extends {BaseClass}
+ */
 export class SkyBlockProfile extends BaseClass {
 	public profile_id!: string;
 	public members!: Record<string, any>;

src/classes/Util.ts

@@ -4,11 +4,19 @@ import { HypixelJSError } from '../errors';
 import type { Client } from '../lib';
 import type { GetUUIDResponse } from '../typings';
 
+/**
+ * Represents a Util class used for util methods.
+ */
 export class Util extends BaseClass {
 	public constructor(client: Client) {
 		super(client);
 	}
 
+	/**
+	 * Get the UUID of a player by providing their name.
+	 * @param {string} name: The name of the player
+	 * @returns {Promise<string>}
+	 */
 	public async getUUID(name: string) {
 		try {
 			const data = await petitio(`https://api.mojang.com/users/profiles/minecraft/${name}`).send();
@@ -22,6 +30,11 @@ export class Util extends BaseClass {
 		}
 	}
 
+	/**
+	 * Check whether the provided UUID is a valid UUID or not.
+	 * @param {string} uuid: The UUID to check
+	 * @returns {boolean}
+	 */
 	public isUUID(uuid: string) {
 		const regex = /^[0-9a-f]{32}$/i;
 		return regex.test(uuid);

src/index.ts

@@ -1 +1,5 @@
-export * from './lib/Client';
+export * from './lib';
+export * from './classes';
+export * from './managers';
+export * from './rest';
+export * from './typings';

src/lib/Client.ts

@@ -4,15 +4,56 @@ import { PlayerManager, SkyBlockManager, ResourcesManager, OtherManager } from '
 import { Util } from '../classes';
 
 export interface Client {
+	/**
+	 * The api key obtained from hypixel's `/api` command (in-game).
+	 */
 	apiKey: string;
+	/**
+	 * The rest manager used to make requests to the Hypixel API.
+	 * @type {RestManager}
+	 */
 	rest: RestManager;
+	/**
+	 * The player manager used to access player related methods.
+	 * @type {PlayerManager}
+	 */
 	players: PlayerManager;
+	/**
+	 * The SkyblockManager used to access skyblock related methods.
+	 * @type {SkyBlockManager}
+	 */
 	skyblock: SkyBlockManager;
+	/**
+	 * The ResourcesManager used to access the resource related methods.
+	 * @type {ResourcesManager}
+	 */
 	resources: ResourcesManager;
+	/**
+	 * The OtherManager used to access the other related methods.
+	 * @type {OtherManager}
+	 */
 	other: OtherManager;
+	/**
+	 * The Util class used to access the util related methods.
+	 * @type {Util}
+	 */
 	util: Util;
 }
 
+/**
+ * The client which is used to access the Hypixel API.
+ * 
+ * @example
+ * ```typescript
+ * import { Client } from '../src';
+
+const client = new Client('API_KEY');
+
+void client.players.fetch('armc').then((player) => {
+	console.log(player);
+});
+```
+ */
 export class Client {
 	public constructor(apiKey: string) {
 		if (!apiKey) throw new HypixelJSError('CLIENT_OPTIONS_MISSING', 'apiKey');

src/managers/BaseManager.ts

@@ -1,6 +1,14 @@
 import type { Client } from '../lib';
 
+/**
+ * The base manager which other managers extend from.
+ */
 export class BaseManager {
+	/**
+	 * The client that instantiated this manager.
+	 * @type {Client}
+	 * @readonly
+	 */
 	public client: Client;
 	public constructor(client: Client) {
 		this.client = client;

src/managers/OtherManager.ts

@@ -2,26 +2,50 @@ import { BaseManager } from './BaseManager';
 import type { Client } from '../lib';
 import type { GetActiveBoostersResponse, GetPlayerCountResponse, GetPunishmentStatisticsResponse } from '../typings';
 
+/**
+ * The manager for other API endpoints.
+ * @extends {BaseManager}
+ */
 export class OtherManager extends BaseManager {
+	/**
+	 * The client that instantiated this manager.
+	 * @type {Client}
+	 */
 	public constructor(client: Client) {
 		super(client);
 	}
 
+	/**
+	 * Get the active network boosters.
+	 * @returns {Promise<GetActiveBoostersResponse>}
+	 */
 	public async getActiveBoosters(): Promise<GetActiveBoostersResponse> {
 		const { boosters, boosterState } = await this.client.api.boosters.get();
 		return { boosters, boosterState };
 	}
 
+	/**
+	 * Get the current player counts.
+	 * @returns {Promise<GetPlayerCountResponse>}
+	 */
 	public async getPlayerCount(): Promise<GetPlayerCountResponse> {
 		const { playerCount, games } = await this.client.api.counts.get();
 		return { playerCount, games };
 	}
 
+	/**
+	 * Get the current leaderboards.
+	 * @returns {Promise<Record<any, any>>}
+	 */
 	public async getLeaderboard(): Promise<Record<any, any>> {
 		const { leaderboards } = await this.client.api.leaderboards.get();
 		return leaderboards;
 	}
 
+	/**
+	 * Get the punishment statistics.
+	 * @returns {Promise<GetPunishmentStatisticsResponse>}}
+	 */
 	public async getPunishmentStatistics(): Promise<GetPunishmentStatisticsResponse> {
 		const { watchdog_lastMinute, staff_rollingDaily, watchdog_total, watchdog_rollingDaily, staff_total } =
 			await this.client.api.punishmentstats.get();

src/managers/PlayerManager.ts

@@ -4,11 +4,24 @@ import { RequestData } from '../lib/util';
 import type { Client } from '../lib';
 import type { GetPlayerFriendsRawResponse, GetRecentlyPlayedGamesResponse, GetStatusResponse, GetRankedSkywarsDataResponse } from '../typings';
 
+/**
+ * The manager for player related API endpoints.
+ * @extends {BaseManager}
+ */
 export class PlayerManager extends BaseManager {
+	/**
+	 * The client that instantiated this manager.
+	 * @type {Client}
+	 */
 	public constructor(client: Client) {
 		super(client);
 	}
 
+	/**
+	 * Fetch a player by their name or UUID.
+	 * @param {string} nameOrUUID: The name or the UUID of the player.
+	 * @returns {Promise<Player>}
+	 */
 	public async fetch(nameOrUUID: string): Promise<Player> {
 		const isUUID = this.client.util.isUUID(nameOrUUID);
 		const uuid = isUUID ? nameOrUUID : await this.getUUID(nameOrUUID);
@@ -18,6 +31,12 @@ export class PlayerManager extends BaseManager {
 		return new Player(this.client, data.player);
 	}
 
+	/**
+	 * Get the friends of a player.
+	 * @param {string} nameOrUUID: The name or UUID of the player who's friends you want to get.
+	 * @param {boolean} raw: Whether to return the raw api results. Defaults to true because if `raw` is false, all the friends of the player will be fetched one by one, which might get you ratelimited depending on the amount of friends the player has.
+	 * @returns {Promise<GetPlayerFriendsRawResponse | Player[]>}
+	 */
 	public async getFriends(nameOrUUID: string, raw?: boolean): Promise<GetPlayerFriendsRawResponse | Player[]> {
 		const isUUID = this.client.util.isUUID(nameOrUUID);
 		const uuid = isUUID ? nameOrUUID : await this.getUUID(nameOrUUID);
@@ -38,6 +57,11 @@ export class PlayerManager extends BaseManager {
 		return friends?.records ?? [];
 	}
 
+	/**
+	 * Get the recently played games of a player.
+	 * @param {string} nameOrUUID: The name or UUID of the player who's recently played games you want to get.
+	 * @returns {Promise<GetRecentlyPlayedGamesResponse[]>}
+	 */
 	public async getRecentlyPlayedGames(nameOrUUID: string): Promise<GetRecentlyPlayedGamesResponse[]> {
 		const isUUID = this.client.util.isUUID(nameOrUUID);
 		const uuid = isUUID ? nameOrUUID : await this.getUUID(nameOrUUID);
@@ -47,6 +71,11 @@ export class PlayerManager extends BaseManager {
 		return games;
 	}
 
+	/**
+	 * Get the status of a player.
+	 * @param {string} nameOrUUID: The name or UUID of the player who's status you want to get.
+	 * @returns {Promise<GetStatusResponse>}
+	 */
 	public async getStatus(nameOrUUID: string): Promise<GetStatusResponse> {
 		const isUUID = this.client.util.isUUID(nameOrUUID);
 		const uuid = isUUID ? nameOrUUID : await this.getUUID(nameOrUUID);
@@ -56,6 +85,11 @@ export class PlayerManager extends BaseManager {
 		return session;
 	}
 
+	/**
+	 * Get ranked skywars data of a player.
+	 * @param {string} nameOrUUID: The name or UUID of the player who's ranked skywars data you want to get.
+	 * @returns {Promise<GetRankedSkywarsDataResponse>}
+	 */
 	public async getRankedSkywarsData(nameOrUUID: string): Promise<GetRankedSkywarsDataResponse> {
 		const isUUID = this.client.util.isUUID(nameOrUUID);
 		const uuid = isUUID ? nameOrUUID : await this.getUUID(nameOrUUID);
@@ -65,6 +99,11 @@ export class PlayerManager extends BaseManager {
 		return result;
 	}
 
+	/**
+	 * Get the UUID of a player by their name.
+	 * @param {string} name: The name of the player.
+	 * @returns {Promise<string>}
+	 */
 	public async getUUID(name: string) {
 		return this.client.util.getUUID(name);
 	}