diff --git a/README.md b/README.md index 337666e..239f487 100644 --- a/README.md +++ b/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 diff --git a/package.json b/package.json index 6e019a9..ad7a4d9 100644 --- a/package.json +++ b/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" }, diff --git a/src/classes/Base.ts b/src/classes/Base.ts index 646fd46..d6e5976 100644 --- a/src/classes/Base.ts +++ b/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; diff --git a/src/classes/Player.ts b/src/classes/Player.ts index 71e9a50..e1ec2c4 100644 --- a/src/classes/Player.ts +++ b/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} + */ public async getFriends(raw?: boolean) { return this.client.players.getFriends(this.uuid, raw); } + /** + * Get the recently played games of this player. + * @returns {Promise} + */ public get recentlyPlayedGames() { return this.client.players.getRecentlyPlayedGames(this.uuid); } + /** + * Get the current status of the player. + * @returns {Promise} + */ public get status() { return this.client.players.getStatus(this.uuid); } + /** + * Get the ranked skywars data of the player. + * @returns {Promise} + */ public get rankedSkywarsData() { return this.client.players.getRankedSkywarsData(this.uuid); } diff --git a/src/classes/SkyBlockProfile.ts b/src/classes/SkyBlockProfile.ts index 89d1ef2..315edb8 100644 --- a/src/classes/SkyBlockProfile.ts +++ b/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; @@ -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; diff --git a/src/classes/Util.ts b/src/classes/Util.ts index dc490de..55dace9 100644 --- a/src/classes/Util.ts +++ b/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} + */ 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); diff --git a/src/index.ts b/src/index.ts index 41fd5cc..d076fc7 100644 --- a/src/index.ts +++ b/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'; diff --git a/src/lib/Client.ts b/src/lib/Client.ts index 1f2fa82..f5f9701 100644 --- a/src/lib/Client.ts +++ b/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'); diff --git a/src/managers/BaseManager.ts b/src/managers/BaseManager.ts index f5de40b..0ce0e10 100644 --- a/src/managers/BaseManager.ts +++ b/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; diff --git a/src/managers/OtherManager.ts b/src/managers/OtherManager.ts index 711cb85..0c39960 100644 --- a/src/managers/OtherManager.ts +++ b/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} + */ public async getActiveBoosters(): Promise { const { boosters, boosterState } = await this.client.api.boosters.get(); return { boosters, boosterState }; } + /** + * Get the current player counts. + * @returns {Promise} + */ public async getPlayerCount(): Promise { const { playerCount, games } = await this.client.api.counts.get(); return { playerCount, games }; } + /** + * Get the current leaderboards. + * @returns {Promise>} + */ public async getLeaderboard(): Promise> { const { leaderboards } = await this.client.api.leaderboards.get(); return leaderboards; } + /** + * Get the punishment statistics. + * @returns {Promise}} + */ public async getPunishmentStatistics(): Promise { const { watchdog_lastMinute, staff_rollingDaily, watchdog_total, watchdog_rollingDaily, staff_total } = await this.client.api.punishmentstats.get(); diff --git a/src/managers/PlayerManager.ts b/src/managers/PlayerManager.ts index 45cbdcf..9be9ce0 100644 --- a/src/managers/PlayerManager.ts +++ b/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} + */ public async fetch(nameOrUUID: string): Promise { 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} + */ public async getFriends(nameOrUUID: string, raw?: boolean): Promise { 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} + */ public async getRecentlyPlayedGames(nameOrUUID: string): Promise { 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} + */ public async getStatus(nameOrUUID: string): Promise { 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} + */ public async getRankedSkywarsData(nameOrUUID: string): Promise { 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} + */ public async getUUID(name: string) { return this.client.util.getUUID(name); } diff --git a/src/managers/ResourcesManager.ts b/src/managers/ResourcesManager.ts index 230eef0..858a533 100644 --- a/src/managers/ResourcesManager.ts +++ b/src/managers/ResourcesManager.ts @@ -10,41 +10,77 @@ import type { GetVanityCompanions } from '../typings'; +/** + * The manager for resource related endpoints. + * @extends {BaseManager} + */ export class ResourcesManager extends BaseManager { + /** + * The client that instantiated this manager. + * @type {Client} + */ public constructor(client: Client) { super(client); } + /** + * Get info regarding all the games on hypixel. + * @returns {Promise} + */ public async gameInfo(): Promise { const { lastUpdated, games } = await this.client.api.resources.games.get(); return { lastUpdated, games }; } + /** + * Get all the achievements. + * @returns {Promise} + */ public async getAchievements(): Promise { const { lastUpdated, achievements } = await this.client.api.resources.achievements.get(); return { lastUpdated, achievements }; } + /** + * Get all the challenges. + * @returns {Promise} + */ public async getChallenges(): Promise { const { lastUpdated, challenges } = await this.client.api.resources.challenges.get(); return { lastUpdated, challenges }; } + /** + * Get all the quests. + * @returns {Promise} + */ public async getQuests(): Promise { const { lastUpdated, quests } = await this.client.api.resources.quests.get(); return { lastUpdated, quests }; } + /** + * Get all the guild achievements. + * @returns {Promise} + */ public async getGuildAchievements(): Promise { const { lastUpdated, one_time, tiered } = await this.client.api.resources.guilds.achievements.get(); return { lastUpdated, one_time, tiered }; } + /** + * Get all the vanity pets. + * @returns {Promise} + */ public async getVanityPets(): Promise { const { lastUpdated, types, rarities } = await this.client.api.resources.vanity.pets.get(); return { lastUpdated, types, rarities }; } + /** + * Get all the vanity companions. + * @returns {Promise} + */ public async getVanityCompanions(): Promise { const { lastUpdated, types, rarities } = await this.client.api.resources.vanity.companions.get(); return { lastUpdated, types, rarities }; diff --git a/src/managers/SkyBlockManager.ts b/src/managers/SkyBlockManager.ts index aa9d441..4d83964 100644 --- a/src/managers/SkyBlockManager.ts +++ b/src/managers/SkyBlockManager.ts @@ -14,31 +14,60 @@ import type { import { RequestData } from '../lib/util'; import { SkyBlockProfile } from '../classes'; +/** + * The manager for skyblock related endpoints. + */ export class SkyBlockManager extends BaseManager { + /** + * The client that instantiated this. + * @type {Client} + */ public constructor(client: Client) { super(client); } + /** + * Get information regarding SkyBlock collections. + * @returns {Promise} + */ public async collections(): Promise { const { lastUpdated, version, collections } = await this.client.api.resources.skyblock.collections.get(); return { lastUpdated, version, collections }; } + /** + * Get information regarding SkyBlock skills. + * @returns {Promise} + */ public async skills(): Promise { const { lastUpdated, version, skills } = await this.client.api.resources.skyblock.skills.get(); return { lastUpdated, version, skills }; } + /** + * Get information regarding SkyBlock items. + * @returns {Promise} + */ public async items(): Promise { const { lastUpdated, items } = await this.client.api.resources.skyblock.items.get(); return { lastUpdated, items }; } + /** + * Get news from SkyBlock. + * @returns {Promise} + */ public async getNews(): Promise { const { items } = await this.client.api.skyblock.news.get(); return items; } + /** + * Request an auction, either by providing the auction uuid, the player uuid, or the profile uuid. + * @param {string} uuid: The uuid of the type provided. + * @param {GetAuctionType} type: The type of auction to request. + * @returns {Promise} + */ public async getAuction(uuid: string, type: GetAuctionType): Promise { const query: { uuid?: string; player?: string; profile?: string } = {}; @@ -54,22 +83,40 @@ export class SkyBlockManager extends BaseManager { return auctions; } + /** + * Get the active auctions + * @param {number} [pageNumber = 0]: The page of the auction. + * @returns {Promise} + */ public async getActiveAuctions(pageNumber = 0): Promise { const query = new RequestData({ query: { page: pageNumber } }); const { page, totalPages, totalAuctions, lastUpdated, auctions } = await this.client.api.skyblock.auctions.get(query); return { page, totalPages, totalAuctions, lastUpdated, auctions }; } + /** + * Get the auctions which ended in the last 60 seconds. + * @returns {Promise} + */ public async recentlyEndedAuctions(): Promise { const { lastUpdated, auctions } = await this.client.api.skyblock['auctions_ended'].get(); return { lastUpdated, auctions }; } + /** + * Returns the list of products along with their sell summary, buy summary and quick status. For more info, please read the [Hypixel API Documentation](https://api.hypixel.net/#tag/SkyBlock/paths/~1skyblock~1bazaar/get). + * @returns {Promise} + */ public async bazaar(): Promise { const { lastUpdated, products } = await this.client.api.skyblock.bazaar.get(); return { lastUpdated, products }; } + /** + * Get the SkyBlock profile by the name or the UUID. + * @param {string} nameOrUUID: The name or the UUID of the profile. + * @returns {Promise} + */ public async getProfile(nameOrUUID: string): Promise { const isUUID = this.client.util.isUUID(nameOrUUID); const uuid = isUUID ? nameOrUUID : await this.client.util.getUUID(nameOrUUID); diff --git a/typedoc.json b/typedoc.json new file mode 100644 index 0000000..6330ac0 --- /dev/null +++ b/typedoc.json @@ -0,0 +1,18 @@ +{ + "cleanOutputDir": true, + "emit": true, + "entryPoints": ["src/index.ts"], + "excludeExternals": false, + "hideGenerator": true, + "lightHighlightTheme": "github-light", + "darkHighlightTheme": "dracula", + "markedOptions": { + "gfm": true, + "mangle": false, + "smartypants": true + }, + "name": "hypixel.ts", + "out": "./docs/", + "readme": "./README.md", + "tsconfig": "./src/tsconfig.json" +} \ No newline at end of file diff --git a/yarn.lock b/yarn.lock index 86cd2a5..6ceaec4 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1947,7 +1947,7 @@ __metadata: languageName: node linkType: hard -"glob@npm:^7.1.3, glob@npm:^7.1.4": +"glob@npm:^7.1.3, glob@npm:^7.1.4, glob@npm:^7.2.0": version: 7.2.0 resolution: "glob@npm:7.2.0" dependencies: @@ -2129,6 +2129,7 @@ __metadata: petitio: ^1.4.0 prettier: ^2.5.1 tslib: ^2.3.1 + typedoc: ^0.22.10 typescript: ^4.5.4 vitest: ^0.0.141 languageName: unknown @@ -2371,6 +2372,13 @@ __metadata: languageName: node linkType: hard +"jsonc-parser@npm:^3.0.0": + version: 3.0.0 + resolution: "jsonc-parser@npm:3.0.0" + checksum: 1df2326f1f9688de30c70ff19c5b2a83ba3b89a1036160da79821d1361090775e9db502dc57a67c11b56e1186fc1ed70b887f25c5febf9a3ec4f91435836c99d + languageName: node + linkType: hard + "jsonfile@npm:^6.0.1": version: 6.1.0 resolution: "jsonfile@npm:6.1.0" @@ -2526,6 +2534,13 @@ __metadata: languageName: node linkType: hard +"lunr@npm:^2.3.9": + version: 2.3.9 + resolution: "lunr@npm:2.3.9" + checksum: 176719e24fcce7d3cf1baccce9dd5633cd8bdc1f41ebe6a180112e5ee99d80373fe2454f5d4624d437e5a8319698ca6837b9950566e15d2cae5f2a543a3db4b8 + languageName: node + linkType: hard + "make-error@npm:^1.1.1": version: 1.3.6 resolution: "make-error@npm:1.3.6" @@ -2571,6 +2586,15 @@ __metadata: languageName: node linkType: hard +"marked@npm:^3.0.8": + version: 3.0.8 + resolution: "marked@npm:3.0.8" + bin: + marked: bin/marked + checksum: 3cdeaa126bbeca5b1b8d2f91e9728018dcd63b250233f3607009a4d70bb6bd9df8c769f1bc52ce9856d1316c91c9dacb1d94d80696f76d094146b4fab126a4eb + languageName: node + linkType: hard + "meow@npm:^8.0.0": version: 8.1.2 resolution: "meow@npm:8.1.2" @@ -3355,6 +3379,17 @@ __metadata: languageName: node linkType: hard +"shiki@npm:^0.9.12": + version: 0.9.15 + resolution: "shiki@npm:0.9.15" + dependencies: + jsonc-parser: ^3.0.0 + vscode-oniguruma: ^1.6.1 + vscode-textmate: 5.2.0 + checksum: 58d1e3e106320252b67c63dc1269c4b834152e9c675a06a4565ec41db1c93aea2dd94e22640d7ec99334cb47cd41b914642d936577143b689ef2a0db7d938c13 + languageName: node + linkType: hard + "signal-exit@npm:^3.0.0, signal-exit@npm:^3.0.2, signal-exit@npm:^3.0.3": version: 3.0.6 resolution: "signal-exit@npm:3.0.6" @@ -3785,6 +3820,23 @@ __metadata: languageName: node linkType: hard +"typedoc@npm:^0.22.10": + version: 0.22.10 + resolution: "typedoc@npm:0.22.10" + dependencies: + glob: ^7.2.0 + lunr: ^2.3.9 + marked: ^3.0.8 + minimatch: ^3.0.4 + shiki: ^0.9.12 + peerDependencies: + typescript: 4.0.x || 4.1.x || 4.2.x || 4.3.x || 4.4.x || 4.5.x + bin: + typedoc: bin/typedoc + checksum: 404932ae8e62d1507209d50b635d9d5cefead344e7e84e2d21fc84741fb739e011dcffcf335d6d4e2a31fe45910757b27f11678f6ae5b89514d2f291fe41884e + languageName: node + linkType: hard + "typescript@npm:^4.4.3, typescript@npm:^4.5.4": version: 4.5.4 resolution: "typescript@npm:4.5.4" @@ -3932,6 +3984,20 @@ __metadata: languageName: node linkType: hard +"vscode-oniguruma@npm:^1.6.1": + version: 1.6.1 + resolution: "vscode-oniguruma@npm:1.6.1" + checksum: b019563a0d48b08c26b66c9f8729ed4ca2620b3b09c6957d5e622f0f104574bec48c7ba575bd157da40fb9a03c03495704894e3ed2d799d80a7180e3051b1f10 + languageName: node + linkType: hard + +"vscode-textmate@npm:5.2.0": + version: 5.2.0 + resolution: "vscode-textmate@npm:5.2.0" + checksum: 5449b42d451080f6f3649b66948f4b5ee4643c4e88cfe3558a3b31c84c78060cfdd288c4958c1690eaa5cd65d09992fa6b7c3bef9d4aa72b3651054a04624d20 + languageName: node + linkType: hard + "which@npm:^2.0.1, which@npm:^2.0.2": version: 2.0.2 resolution: "which@npm:2.0.2"