From 43fd62141f3f537a3b049568f27b872e7b490ec6 Mon Sep 17 00:00:00 2001 From: Elitezen Date: Mon, 16 Oct 2023 22:15:27 -0400 Subject: [PATCH 1/3] Added missing documentation for certain functions and improved some of the existing documentation --- src/structs/Api.ts | 51 +++++++++++++++++++++++------------------- src/structs/Webhook.ts | 6 +++-- src/utils/ApiError.ts | 15 +++++++++++-- 3 files changed, 45 insertions(+), 27 deletions(-) diff --git a/src/structs/Api.ts b/src/structs/Api.ts index 90f7ba5..443bd58 100644 --- a/src/structs/Api.ts +++ b/src/structs/Api.ts @@ -16,7 +16,7 @@ import { } from "../typings"; /** - * Top.gg API Client for Posting stats or Fetching data + * Top.gg API Client for posting stats or fetching data * * @example * ```js @@ -86,7 +86,7 @@ export class Api extends EventEmitter { } /** - * Post bot stats to Top.gg + * Posts bot stats to Top.gg * * @example * ```js @@ -96,11 +96,12 @@ export class Api extends EventEmitter { * }); * ``` * - * @param {object} stats Stats object - * @param {number} stats.serverCount Server count - * @param {number} [stats.shardCount] Shard count + * @param {BotStats} stats Stats object + * @param {number} [stats.serverCount] The amount of servers the bot is in + * @param {number} [stats.shards] The amount of servers the bot is in per shard. + * @param {number} [stats.shardCount] The amount of shards a bot has * @param {number} [stats.shardId] Posting shard (useful for process sharding) - * @returns {BotStats} Passed object + * @returns {Promise} Passed object */ public async postStats(stats: BotStats): Promise { if (!stats?.serverCount) throw new Error("Missing Server Count"); @@ -131,7 +132,7 @@ export class Api extends EventEmitter { * ``` * * @param {Snowflake} id Bot ID - * @returns {BotStats} Stats of bot requested + * @returns {Promise} Stats of bot requested */ public async getStats(id: Snowflake): Promise { if (!id) throw new Error("ID missing"); @@ -152,7 +153,7 @@ export class Api extends EventEmitter { * ``` * * @param {Snowflake} id Bot ID - * @returns {BotInfo} Info for bot + * @returns {Promise} Info for bot */ public async getBot(id: Snowflake): Promise { if (!id) throw new Error("ID Missing"); @@ -160,7 +161,7 @@ export class Api extends EventEmitter { } /** - * Get user info + * Retrieves information about a particular user by their Discord user id. * * @example * ```js @@ -170,7 +171,7 @@ export class Api extends EventEmitter { * ``` * * @param {Snowflake} id User ID - * @returns {UserInfo} Info for user + * @returns {Promise} Info for user */ public async getUser(id: Snowflake): Promise { if (!id) throw new Error("ID Missing"); @@ -178,7 +179,7 @@ export class Api extends EventEmitter { } /** - * Get a list of bots + * Gets a list of bots that match a specific query. * * @example * ```js @@ -197,9 +198,9 @@ export class Api extends EventEmitter { * username: 'Shiro', * discriminator: '8764', * lib: 'discord.js', - * ...rest of bot object + * // ...rest of bot object * } - * ...other shiro knockoffs B) + * // ...other shiro knockoffs B) * ], * limit: 10, * offset: 0, @@ -221,14 +222,14 @@ export class Api extends EventEmitter { * id: '493716749342998541', * username: 'Mimu' * }, - * ... + * // ... * ], - * ... + * // ... * } * ``` * * @param {BotsQuery} query Bot Query - * @returns {BotsResponse} Return response + * @returns {Promise} Return response */ public async getBots(query?: BotsQuery): Promise { if (query) { @@ -243,7 +244,11 @@ export class Api extends EventEmitter { } /** - * Get users who've voted + * Gets the last 1000 voters for your bot + * + * If your bot receives more than 1000 votes monthly you cannot use this endpoints and must use webhooks and implement your own caching instead. + * + * This endpoint only returns unique votes, it does not include double votes (weekend votes). * * @example * ```js @@ -260,11 +265,11 @@ export class Api extends EventEmitter { * id: '395526710101278721', * avatar: '3d1477390b8d7c3cec717ac5c778f5f4' * } - * ...more + * // ...more * ] * ``` * - * @returns {ShortUser[]} Array of users who've voted + * @returns {Promise} Array of users who've voted */ public async getVotes(): Promise { if (!this.options.token) throw new Error("Missing token"); @@ -272,7 +277,7 @@ export class Api extends EventEmitter { } /** - * Get whether or not a user has voted in the last 12 hours + * Checking whether or not a user has voted for your bot in the last 12 hours. Safe to use even if you have over 1k monthly votes. * * @example * ```js @@ -281,7 +286,7 @@ export class Api extends EventEmitter { * ``` * * @param {Snowflake} id User ID - * @returns {boolean} Whether the user has voted in the last 12 hours + * @returns {Promise} Whether the user has voted in the last 12 hours */ public async hasVoted(id: Snowflake): Promise { if (!id) throw new Error("Missing ID"); @@ -299,9 +304,9 @@ export class Api extends EventEmitter { * // => true/false * ``` * - * @returns {boolean} Whether the multiplier is active + * @returns {Promise} Whether the multiplier is active */ public async isWeekend(): Promise { return this._request("GET", "/weekend").then((x) => x.is_weekend); } -} +} \ No newline at end of file diff --git a/src/structs/Webhook.ts b/src/structs/Webhook.ts index d257ce8..18acfc2 100644 --- a/src/structs/Webhook.ts +++ b/src/structs/Webhook.ts @@ -43,7 +43,9 @@ export class Webhook { /** * Create a new webhook client instance * - * @param authorization Webhook authorization to verify requests + * @param {string} authorization Webhook authorization to verify requests + * @param {WebhookOptions} options The webhook options + * @param {((error: Error) => void) | Promise} [options.error] Handles an error created by the function passed to Webhook.listener() */ constructor(private authorization?: string, options: WebhookOptions = {}) { this.options = { @@ -166,4 +168,4 @@ export class Webhook { next(); }; } -} +} \ No newline at end of file diff --git a/src/utils/ApiError.ts b/src/utils/ApiError.ts index b4df924..2ec946a 100644 --- a/src/utils/ApiError.ts +++ b/src/utils/ApiError.ts @@ -5,10 +5,21 @@ const tips = { 403: "You don't have access to this endpoint", }; -/** API Error */ +/** + * Represents a Top.gg API error + * @extends Error + */ export default class TopGGAPIError extends Error { /** Possible response from Request */ public response?: Dispatcher.ResponseData; + + /** + * Creates a Top.gg API error instance + * + * @param {number} code The error code + * @param {string} text The error text + * @param {Dispatcher.ResponseData} response + */ constructor(code: number, text: string, response: Dispatcher.ResponseData) { if (code in tips) { super(`${code} ${text} (${tips[code as keyof typeof tips]})`); @@ -17,4 +28,4 @@ export default class TopGGAPIError extends Error { } this.response = response; } -} +} \ No newline at end of file From e987e13a2aaeb59f723daf6e7759b429d692ebd6 Mon Sep 17 00:00:00 2001 From: Elitezen Date: Mon, 16 Oct 2023 22:23:38 -0400 Subject: [PATCH 2/3] Reworded error messages for Api function class --- src/structs/Api.ts | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/structs/Api.ts b/src/structs/Api.ts index 443bd58..46b8318 100644 --- a/src/structs/Api.ts +++ b/src/structs/Api.ts @@ -135,7 +135,7 @@ export class Api extends EventEmitter { * @returns {Promise} Stats of bot requested */ public async getStats(id: Snowflake): Promise { - if (!id) throw new Error("ID missing"); + if (!id) throw new Error("Missing parameter bot ID"); const result = await this._request("GET", `/bots/${id}/stats`); return { serverCount: result.server_count, @@ -156,7 +156,7 @@ export class Api extends EventEmitter { * @returns {Promise} Info for bot */ public async getBot(id: Snowflake): Promise { - if (!id) throw new Error("ID Missing"); + if (!id) throw new Error("Missing parameter bot ID"); return this._request("GET", `/bots/${id}`); } @@ -174,7 +174,7 @@ export class Api extends EventEmitter { * @returns {Promise} Info for user */ public async getUser(id: Snowflake): Promise { - if (!id) throw new Error("ID Missing"); + if (!id) throw new Error("Missing parameter user ID"); return this._request("GET", `/users/${id}`); } @@ -272,7 +272,7 @@ export class Api extends EventEmitter { * @returns {Promise} Array of users who've voted */ public async getVotes(): Promise { - if (!this.options.token) throw new Error("Missing token"); + if (!this.options.token) throw new Error("You must provide a token to the Top.gg API instance for this"); return this._request("GET", "/bots/votes"); } @@ -289,7 +289,7 @@ export class Api extends EventEmitter { * @returns {Promise} Whether the user has voted in the last 12 hours */ public async hasVoted(id: Snowflake): Promise { - if (!id) throw new Error("Missing ID"); + if (!id) throw new Error("Missing parameter user ID"); return this._request("GET", "/bots/check", { userId: id }).then( (x) => !!x.voted ); From f51507909dd415b690d77bb41f330db9789c00bf Mon Sep 17 00:00:00 2001 From: Elitezen Date: Mon, 17 Jun 2024 13:31:37 -0400 Subject: [PATCH 3/3] Reworded JSDOC typing description for Api.getUser() --- src/structs/Api.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/structs/Api.ts b/src/structs/Api.ts index 46b8318..30dddad 100644 --- a/src/structs/Api.ts +++ b/src/structs/Api.ts @@ -161,7 +161,7 @@ export class Api extends EventEmitter { } /** - * Retrieves information about a particular user by their Discord user id. + * Retrieves information about a particular user by their top.gg user ID. * * @example * ```js