From b4afcf8236b0fb4979deab0a097656292c59d50b Mon Sep 17 00:00:00 2001 From: Rodry <38259440+ImRodry@users.noreply.github.com> Date: Thu, 5 Aug 2021 20:34:06 +0100 Subject: [PATCH] docs: general cleanup and improvements (#6299) Co-authored-by: DaStormer <40336269+DaStormer@users.noreply.github.com> Co-authored-by: Sugden <28943913+NotSugden@users.noreply.github.com> Co-authored-by: SpaceEEC --- src/client/Client.js | 5 ++ src/client/websocket/WebSocketManager.js | 2 +- .../websocket/handlers/GUILD_MEMBERS_CHUNK.js | 14 ++-- .../ApplicationCommandPermissionsManager.js | 2 +- src/managers/GuildBanManager.js | 4 +- src/managers/GuildManager.js | 2 +- src/managers/GuildMemberManager.js | 14 ++-- src/managers/GuildStickerManager.js | 11 ++- src/managers/MessageManager.js | 4 +- src/managers/ThreadManager.js | 2 +- src/sharding/ShardClientUtil.js | 4 +- src/sharding/ShardingManager.js | 11 +-- src/structures/BaseMessageComponent.js | 3 +- src/structures/ClientUser.js | 16 ++--- src/structures/Guild.js | 19 +++--- src/structures/GuildAuditLogs.js | 3 +- src/structures/GuildBan.js | 3 +- src/structures/InteractionCollector.js | 6 +- src/structures/Invite.js | 1 + src/structures/Message.js | 6 +- src/structures/MessageEmbed.js | 7 +- src/structures/MessageMentions.js | 6 +- src/structures/MessagePayload.js | 12 ++-- src/structures/MessageReaction.js | 2 +- src/structures/PermissionOverwrites.js | 6 +- src/structures/Presence.js | 22 ++++-- src/structures/Team.js | 2 +- src/structures/ThreadChannel.js | 3 +- src/structures/VoiceState.js | 2 +- src/structures/interfaces/Application.js | 4 +- src/util/ApplicationFlags.js | 7 +- src/util/BitField.js | 2 +- src/util/Constants.js | 41 +++++++++-- src/util/LimitedCollection.js | 8 +-- src/util/Permissions.js | 4 +- src/util/SnowflakeUtil.js | 9 +-- src/util/SystemChannelFlags.js | 1 + typings/enums.d.ts | 1 + typings/index.d.ts | 68 +++++++++++-------- 39 files changed, 203 insertions(+), 136 deletions(-) diff --git a/src/client/Client.js b/src/client/Client.js index 04526c1217dd..3996c39bc86b 100644 --- a/src/client/Client.js +++ b/src/client/Client.js @@ -610,3 +610,8 @@ module.exports = Client; * @event Client#debug * @param {string} info The debug information */ + +/** + * @external Collection + * @see {@link https://discord.js.org/#/docs/collection/master/class/Collection} + */ diff --git a/src/client/websocket/WebSocketManager.js b/src/client/websocket/WebSocketManager.js index 60c10078946c..8f679f6a946c 100644 --- a/src/client/websocket/WebSocketManager.js +++ b/src/client/websocket/WebSocketManager.js @@ -175,7 +175,7 @@ class WebSocketManager extends EventEmitter { * Emitted when a shard turns ready. * @event Client#shardReady * @param {number} id The shard id that turned ready - * @param {?Set} unavailableGuilds Set of unavailable guild ids, if any + * @param {?Set} unavailableGuilds Set of unavailable guild ids, if any */ this.client.emit(Events.SHARD_READY, shard.id, unavailableGuilds); diff --git a/src/client/websocket/handlers/GUILD_MEMBERS_CHUNK.js b/src/client/websocket/handlers/GUILD_MEMBERS_CHUNK.js index 48cddea4f9ee..f9ac7f9f6e9d 100644 --- a/src/client/websocket/handlers/GUILD_MEMBERS_CHUNK.js +++ b/src/client/websocket/handlers/GUILD_MEMBERS_CHUNK.js @@ -12,15 +12,21 @@ module.exports = (client, { d: data }) => { if (data.presences) { for (const presence of data.presences) guild.presences._add(Object.assign(presence, { guild })); } + + /** + * Represents the properties of a guild members chunk + * @typedef {Object} GuildMembersChunk + * @property {number} index Index of the received chunk + * @property {number} count Number of chunks the client should receive + * @property {?string} nonce Nonce for this chunk + */ + /** * Emitted whenever a chunk of guild members is received (all members come from the same guild). * @event Client#guildMembersChunk * @param {Collection} members The members in the chunk * @param {Guild} guild The guild related to the member chunk - * @param {Object} chunk Properties of the received chunk - * @param {number} chunk.index Index of the received chunk - * @param {number} chunk.count Number of chunks the client should receive - * @param {?string} chunk.nonce Nonce for this chunk + * @param {GuildMembersChunk} chunk Properties of the received chunk */ client.emit(Events.GUILD_MEMBERS_CHUNK, members, guild, { count: data.chunk_count, diff --git a/src/managers/ApplicationCommandPermissionsManager.js b/src/managers/ApplicationCommandPermissionsManager.js index 4f9a4b8c0b8a..b5b39680caf3 100644 --- a/src/managers/ApplicationCommandPermissionsManager.js +++ b/src/managers/ApplicationCommandPermissionsManager.js @@ -124,7 +124,7 @@ class ApplicationCommandPermissionsManager extends BaseManager { * @typedef {BaseApplicationCommandPermissionsOptions} SetApplicationCommandPermissionsOptions * @param {ApplicationCommandPermissionData[]} [permissions] The new permissions for the command * @param {GuildApplicationCommandPermissionData[]} [fullPermissions] The new permissions for all commands - * in a guild When this parameter is set, permissions and command are ignored + * in a guild When this parameter is set, `permissions` and `command` are ignored */ /** diff --git a/src/managers/GuildBanManager.js b/src/managers/GuildBanManager.js index 5bed33d7da75..f2b67ea4de65 100644 --- a/src/managers/GuildBanManager.js +++ b/src/managers/GuildBanManager.js @@ -62,7 +62,7 @@ class GuildBanManager extends CachedManager { /** * Fetches ban(s) from Discord. * @param {UserResolvable|FetchBanOptions|FetchBansOptions} [options] Options for fetching guild ban(s) - * @returns {Promise|Promise>} + * @returns {Promise>} * @example * // Fetch all bans from a guild * guild.bans.fetch() @@ -135,7 +135,7 @@ class GuildBanManager extends CachedManager { * @example * // Ban a user by id (or with a user/guild member object) * guild.bans.create('84484653687267328') - * .then(user => console.log(`Banned ${user.username ?? user.id ?? user} from ${guild.name}`)) + * .then(banInfo => console.log(`Banned ${banInfo.user?.tag ?? banInfo.tag ?? banInfo}`)) * .catch(console.error); */ async create(user, options = { days: 0 }) { diff --git a/src/managers/GuildManager.js b/src/managers/GuildManager.js index f8d79d65d6f7..25f56b91a4ab 100644 --- a/src/managers/GuildManager.js +++ b/src/managers/GuildManager.js @@ -72,7 +72,7 @@ class GuildManager extends CachedManager { /** * Partial overwrite data. * @typedef {Object} PartialOverwriteData - * @property {Snowflake|number} id The {@link Role} or {@link User} id for this overwrite + * @property {Snowflake|number} id The id of the {@link Role} or {@link User} this overwrite belongs to * @property {string} [type] The type of this overwrite * @property {PermissionResolvable} [allow] The permissions to allow * @property {PermissionResolvable} [deny] The permissions to deny diff --git a/src/managers/GuildMemberManager.js b/src/managers/GuildMemberManager.js index d5c7292e97c7..57dc10551c45 100644 --- a/src/managers/GuildMemberManager.js +++ b/src/managers/GuildMemberManager.js @@ -139,7 +139,7 @@ class GuildMemberManager extends CachedManager { * @param {UserResolvable|FetchMemberOptions|FetchMembersOptions} [options] If a UserResolvable, the user to fetch. * If undefined, fetches all members. * If a query, it limits the results to users with similar usernames. - * @returns {Promise|Promise>} + * @returns {Promise>} * @example * // Fetch all members from a guild * guild.members.fetch() @@ -248,6 +248,8 @@ class GuildMemberManager extends CachedManager { /** * Options used for pruning guild members. + * It's recommended to set {@link GuildPruneMembersOptions#count options.count} + * to `false` for large guilds. * @typedef {Object} GuildPruneMembersOptions * @property {number} [days=7] Number of days of inactivity required to kick * @property {boolean} [dry=false] Get the number of users that will be kicked, without actually kicking them @@ -258,7 +260,6 @@ class GuildMemberManager extends CachedManager { /** * Prunes members from the guild based on how long they have been inactive. - * It's recommended to set `options.count` to `false` for large guilds. * @param {GuildPruneMembersOptions} [options] Options for pruning * @returns {Promise} The number of members that were/will be kicked * @example @@ -315,7 +316,7 @@ class GuildMemberManager extends CachedManager { * @example * // Kick a user by id (or with a user/guild member object) * guild.members.kick('84484653687267328') - * .then(user => console.log(`Kicked ${user.username ?? user.id ?? user} from ${guild.name}`)) + * .then(banInfo => console.log(`Kicked ${banInfo.user?.tag ?? banInfo.tag ?? banInfo}`)) * .catch(console.error); */ async kick(user, reason) { @@ -338,7 +339,7 @@ class GuildMemberManager extends CachedManager { * @example * // Ban a user by id (or with a user/guild member object) * guild.members.ban('84484653687267328') - * .then(user => console.log(`Banned ${user.username ?? user.id ?? user} from ${guild.name}`)) + * .then(kickInfo => console.log(`Banned ${kickInfo.user?.tag ?? kickInfo.tag ?? kickInfo}`)) * .catch(console.error); */ ban(user, options = { days: 0 }) { @@ -346,11 +347,10 @@ class GuildMemberManager extends CachedManager { } /** - * Unbans a user from the guild. + * Unbans a user from the guild. Internally calls the {@link GuildBanManager#remove} method. * @param {UserResolvable} user The user to unban * @param {string} [reason] Reason for unbanning user - * @returns {Promise} - * Internally calls the GuildBanManager#remove method. + * @returns {Promise} The user that was unbanned * @example * // Unban a user by id (or with a user/guild member object) * guild.members.unban('84484653687267328') diff --git a/src/managers/GuildStickerManager.js b/src/managers/GuildStickerManager.js index c3cf22a92f2a..361a5f752717 100644 --- a/src/managers/GuildStickerManager.js +++ b/src/managers/GuildStickerManager.js @@ -31,14 +31,19 @@ class GuildStickerManager extends CachedManager { return super._add(data, cache, { extras: [this.guild] }); } + /** + * Options for creating a guild sticker. + * @typedef {Object} GuildStickerCreateOptions + * @param {?string} [description] The description for the sticker + * @param {string} [reason] Reason for creating the sticker + */ + /** * Creates a new custom sticker in the guild. * @param {BufferResolvable|Stream|FileOptions|MessageAttachment} file The file for the sticker * @param {string} name The name for the sticker * @param {string} tags The Discord name of a unicode emoji representing the sticker's expression - * @param {Object} [options] Options - * @param {?string} [options.description] The description for the sticker - * @param {string} [options.reason] Reason for creating the sticker + * @param {GuildStickerCreateOptions} [options] Options * @returns {Promise} The created sticker * @example * // Create a new sticker from a url diff --git a/src/managers/MessageManager.js b/src/managers/MessageManager.js index 40759da0e4b1..5fd5a054eeaa 100644 --- a/src/managers/MessageManager.js +++ b/src/managers/MessageManager.js @@ -47,7 +47,7 @@ class MessageManager extends CachedManager { * Those need to be fetched separately in such a case. * @param {Snowflake|ChannelLogsQueryOptions} [message] The id of the message to fetch, or query parameters. * @param {BaseFetchOptions} [options] Additional options for this fetch - * @returns {Promise|Promise>} + * @returns {Promise>} * @example * // Get message * channel.messages.fetch('99539446449315840') @@ -165,7 +165,7 @@ class MessageManager extends CachedManager { } /** - * Unins a message from the channel's pinned messages, even if it's not cached. + * Unpins a message from the channel's pinned messages, even if it's not cached. * @param {MessageResolvable} message The message to unpin * @returns {Promise} */ diff --git a/src/managers/ThreadManager.js b/src/managers/ThreadManager.js index 315a00bac78b..d744fef06e31 100644 --- a/src/managers/ThreadManager.js +++ b/src/managers/ThreadManager.js @@ -144,7 +144,7 @@ class ThreadManager extends CachedManager { * @param {ThreadChannelResolvable|FetchThreadsOptions} [options] The options to fetch threads. If it is a * ThreadChannelResolvable then the specified thread will be fetched. Fetches all active threads if `undefined` * @param {BaseFetchOptions} [cacheOptions] Additional options for this fetch. The `force` field gets ignored - * if `options` is not a ThreadChannelResolvable + * if `options` is not a {@link ThreadChannelResolvable} * @returns {Promise} * @example * // Fetch a thread by its id diff --git a/src/sharding/ShardClientUtil.js b/src/sharding/ShardClientUtil.js index f04a66e49b89..e7181efcde6d 100644 --- a/src/sharding/ShardClientUtil.js +++ b/src/sharding/ShardClientUtil.js @@ -100,7 +100,7 @@ class ShardClientUtil { * Fetches a client property value of each shard, or a given shard. * @param {string} prop Name of the client property to get, using periods for nesting * @param {number} [shard] Shard to fetch property from, all if undefined - * @returns {Promise<*>|Promise>} + * @returns {Promise<*|Array<*>>} * @example * client.shard.fetchClientValues('guilds.cache.size') * .then(results => console.log(`${results.reduce((prev, val) => prev + val, 0)} total guilds`)) @@ -130,7 +130,7 @@ class ShardClientUtil { * Evaluates a script or function on all shards, or a given shard, in the context of the {@link Client}s. * @param {Function} script JavaScript to run on each shard * @param {BroadcastEvalOptions} [options={}] The options for the broadcast - * @returns {Promise<*>|Promise>} Results of the script execution + * @returns {Promise<*|Array<*>>} Results of the script execution * @example * client.shard.broadcastEval(client => client.guilds.cache.size) * .then(results => console.log(`${results.reduce((prev, val) => prev + val, 0)} total guilds`)) diff --git a/src/sharding/ShardingManager.js b/src/sharding/ShardingManager.js index 44bd41875922..062b8aaa8736 100644 --- a/src/sharding/ShardingManager.js +++ b/src/sharding/ShardingManager.js @@ -19,8 +19,9 @@ const Util = require('../util/Util'); */ class ShardingManager extends EventEmitter { /** - * The mode to spawn shards with for a {@link ShardingManager}. Either "process" to use child processes, or - * "worker" to use [Worker threads](https://nodejs.org/api/worker_threads.html). + * The mode to spawn shards with for a {@link ShardingManager}. Can be either one of: + * * 'process' to use child processes + * * 'worker' to use [Worker threads](https://nodejs.org/api/worker_threads.html) * @typedef {string} ShardingManagerMode */ @@ -242,7 +243,7 @@ class ShardingManager extends EventEmitter { * Evaluates a script on all shards, or a given shard, in the context of the {@link Client}s. * @param {Function} script JavaScript to run on each shard * @param {BroadcastEvalOptions} [options={}] The options for the broadcast - * @returns {Promise<*>|Promise>} Results of the script execution + * @returns {Promise<*|Array<*>>} Results of the script execution */ broadcastEval(script, options = {}) { if (typeof script !== 'function') return Promise.reject(new TypeError('SHARDING_INVALID_EVAL_BROADCAST')); @@ -253,7 +254,7 @@ class ShardingManager extends EventEmitter { * Fetches a client property value of each shard, or a given shard. * @param {string} prop Name of the client property to get, using periods for nesting * @param {number} [shard] Shard to fetch property from, all if undefined - * @returns {Promise<*>|Promise>} + * @returns {Promise<*|Array<*>>} * @example * manager.fetchClientValues('guilds.cache.size') * .then(results => console.log(`${results.reduce((prev, val) => prev + val, 0)} total guilds`)) @@ -268,7 +269,7 @@ class ShardingManager extends EventEmitter { * @param {string} method Method name to run on each shard * @param {Array<*>} args Arguments to pass through to the method call * @param {number} [shard] Shard to run on, all if undefined - * @returns {Promise<*>|Promise>} Results of the method execution + * @returns {Promise<*|Array<*>>} Results of the method execution * @private */ _performOnShards(method, args, shard) { diff --git a/src/structures/BaseMessageComponent.js b/src/structures/BaseMessageComponent.js index b7b50034e0f3..e658eda235b4 100644 --- a/src/structures/BaseMessageComponent.js +++ b/src/structures/BaseMessageComponent.js @@ -23,11 +23,12 @@ class BaseMessageComponent { */ /** - * Components that can be sent in a message. This can be: + * Components that can be sent in a message. These can be: * * MessageActionRow * * MessageButton * * MessageSelectMenu * @typedef {MessageActionRow|MessageButton|MessageSelectMenu} MessageComponent + * @see {@link https://discord.com/developers/docs/interactions/message-components#component-object-component-types} */ /** diff --git a/src/structures/ClientUser.js b/src/structures/ClientUser.js index cbf9be392203..fba1494df8d8 100644 --- a/src/structures/ClientUser.js +++ b/src/structures/ClientUser.js @@ -41,11 +41,16 @@ class ClientUser extends User { return this.client.presence; } + /** + * Data used to edit the logged in client + * @typdef {Object} ClientUserEditData + * @property {string} [username] The new username + * @property {BufferResolvable|Base64Resolvable} [avatar] The new avatar + */ + /** * Edits the logged in client. - * @param {APIModifyClientData} data The new data - * @param {string} [data.username] The new username - * @param {BufferResolvable|Base64Resolvable} [data.avatar] The new avatar + * @param {ClientUserEditData} data The new data */ async edit(data) { const newData = await this.client.api.users('@me').patch({ data }); @@ -172,8 +177,3 @@ class ClientUser extends User { } module.exports = ClientUser; - -/** - * @external APIModifyClientData - * @see {@link https://discord.com/developers/docs/resources/user#modify-current-user-json-params} - */ diff --git a/src/structures/Guild.js b/src/structures/Guild.js index 7b33352f7cc5..88e3a55309a5 100644 --- a/src/structures/Guild.js +++ b/src/structures/Guild.js @@ -37,7 +37,7 @@ const Util = require('../util/Util'); /** * Represents a guild (or a server) on Discord. * It's recommended to see if a guild is available before performing operations or reading data from it. You can - * check this with `guild.available`. + * check this with {@link Guild#available}. * @extends {AnonymousGuild} */ class Guild extends AnonymousGuild { @@ -172,21 +172,21 @@ class Guild extends AnonymousGuild { * * FEATURABLE * * INVITE_SPLASH * * MEMBER_VERIFICATION_GATE_ENABLED - * * MONETIZATION_ENABLED - * * MORE_STICKERS * * NEWS * * PARTNERED * * PREVIEW_ENABLED - * * PRIVATE_THREADS - * * RELAY_ENABLED - * * SEVEN_DAY_THREAD_ARCHIVE - * * THREE_DAY_THREAD_ARCHIVE - * * TICKETED_EVENTS_ENABLED * * VANITY_URL * * VERIFIED * * VIP_REGIONS * * WELCOME_SCREEN_ENABLED + * * TICKETED_EVENTS_ENABLED + * * MONETIZATION_ENABLED + * * MORE_STICKERS + * * THREE_DAY_THREAD_ARCHIVE + * * SEVEN_DAY_THREAD_ARCHIVE + * * PRIVATE_THREADS * @typedef {string} Features + * @see {@link https://discord.com/developers/docs/resources/guild#guild-object-guild-features} */ /** @@ -337,7 +337,8 @@ class Guild extends AnonymousGuild { /** * The preferred locale of the guild, defaults to `en-US` - * @type {string} + * @type {?string} + * @see {@link https://discord.com/developers/docs/dispatch/field-values#predefined-field-values-accepted-locales} */ this.preferredLocale = data.preferred_locale; diff --git a/src/structures/GuildAuditLogs.js b/src/structures/GuildAuditLogs.js index c600c2931fdd..c3876ea262e5 100644 --- a/src/structures/GuildAuditLogs.js +++ b/src/structures/GuildAuditLogs.js @@ -11,7 +11,7 @@ const SnowflakeUtil = require('../util/SnowflakeUtil'); const Util = require('../util/Util'); /** - * The target type of an entry, e.g. `GUILD`. Here are the available types: + * The target type of an entry. Here are the available types: * * GUILD * * CHANNEL * * USER @@ -97,6 +97,7 @@ const Targets = { * * THREAD_UPDATE: 111 * * THREAD_DELETE: 112 * @typedef {?(number|string)} AuditLogAction + * @see {@link https://discord.com/developers/docs/resources/audit-log#audit-log-entry-object-audit-log-events} */ /** diff --git a/src/structures/GuildBan.js b/src/structures/GuildBan.js index 0f06f75fa0ae..d3cdc6e2509b 100644 --- a/src/structures/GuildBan.js +++ b/src/structures/GuildBan.js @@ -41,8 +41,7 @@ class GuildBan extends Base { } /** - * Whether this GuildBan is a partial - * If the reason is not provided the value is null + * Whether this GuildBan is partial. If the reason is not provided the value is null * @type {boolean} * @readonly */ diff --git a/src/structures/InteractionCollector.js b/src/structures/InteractionCollector.js index 824474d7e9b1..9155355e4ec8 100644 --- a/src/structures/InteractionCollector.js +++ b/src/structures/InteractionCollector.js @@ -19,8 +19,8 @@ const { InteractionTypes, MessageComponentTypes } = require('../util/Constants') /** * Collects interactions. - * Will automatically stop if the message (`'messageDelete'`), - * channel (`'channelDelete'`), or guild (`'guildDelete'`) are deleted. + * Will automatically stop if the message ({@link Client#messageDelete messageDelete}), + * channel ({@link Client#channelDelete channelDelete}), or guild ({@link Client#guildDelete guildDelete}) is deleted. * @extends {Collector} */ class InteractionCollector extends Collector { @@ -76,7 +76,7 @@ class InteractionCollector extends Collector { /** * The users which have interacted to this collector - * @type {Collection} + * @type {Collection} */ this.users = new Collection(); diff --git a/src/structures/Invite.js b/src/structures/Invite.js index 04868284e3a8..d89f75de8ae5 100644 --- a/src/structures/Invite.js +++ b/src/structures/Invite.js @@ -97,6 +97,7 @@ class Invite extends Base { * * 1: STREAM * * 2: EMBEDDED_APPLICATION * @typedef {number} TargetType + * @see {@link https://discord.com/developers/docs/resources/invite#invite-object-invite-target-types} */ /** diff --git a/src/structures/Message.js b/src/structures/Message.js index 71f62654a0e1..1cf4f44683df 100644 --- a/src/structures/Message.js +++ b/src/structures/Message.js @@ -284,9 +284,9 @@ class Message extends Base { /** * Reference data sent in a message that contains ids identifying the referenced message * @typedef {Object} MessageReference - * @property {string} channelId The channel's id the message was referenced - * @property {?string} guildId The guild's id the message was referenced - * @property {?string} messageId The message's id that was referenced + * @property {Snowflake} channelId The channel's id the message was referenced + * @property {?Snowflake} guildId The guild's id the message was referenced + * @property {?Snowflake} messageId The message's id that was referenced */ if ('message_reference' in data || !partial) { diff --git a/src/structures/MessageEmbed.js b/src/structures/MessageEmbed.js index d335248fbd24..534223666ddf 100644 --- a/src/structures/MessageEmbed.js +++ b/src/structures/MessageEmbed.js @@ -44,13 +44,14 @@ class MessageEmbed { setup(data, skipValidation) { /** * The type of this embed, either: - * * `rich` - a rich embed + * * `rich` - a generic embed rendered from embed attributes * * `image` - an image embed * * `video` - a video embed - * * `gifv` - a gifv embed + * * `gifv` - an animated gif image embed rendered as a video embed * * `article` - an article embed * * `link` - a link embed * @type {string} + * @see {@link https://discord.com/developers/docs/resources/channel#embed-object-embed-types} * @deprecated */ this.type = data.type ?? 'rich'; @@ -430,7 +431,7 @@ class MessageEmbed { } /** - * Normalizes field input and resolves strings. + * Normalizes field input and verifies strings. * @param {string} name The name of the field * @param {string} value The value of the field * @param {boolean} [inline=false] Set the field to display inline diff --git a/src/structures/MessageMentions.js b/src/structures/MessageMentions.js index 1a68def1b238..67aef97e1145 100644 --- a/src/structures/MessageMentions.js +++ b/src/structures/MessageMentions.js @@ -96,9 +96,9 @@ class MessageMentions { /** * Crossposted channel data. * @typedef {Object} CrosspostedChannel - * @property {string} channelId The mentioned channel's id - * @property {string} guildId The id of the guild that has the channel - * @property {string} type The channel's type + * @property {Snowflake} channelId The mentioned channel's id + * @property {Snowflake} guildId The id of the guild that has the channel + * @property {ChannelType} type The channel's type * @property {string} name The channel's name */ diff --git a/src/structures/MessagePayload.js b/src/structures/MessagePayload.js index 8a91dc2f4817..f3e9671c15fe 100644 --- a/src/structures/MessagePayload.js +++ b/src/structures/MessagePayload.js @@ -49,7 +49,7 @@ class MessagePayload { } /** - * Whether or not the target is a webhook + * Whether or not the target is a {@link Webhook} or a {@link WebhookClient} * @type {boolean} * @readonly */ @@ -60,7 +60,7 @@ class MessagePayload { } /** - * Whether or not the target is a user + * Whether or not the target is a {@link User} * @type {boolean} * @readonly */ @@ -71,7 +71,7 @@ class MessagePayload { } /** - * Whether or not the target is a message + * Whether or not the target is a {@link Message} * @type {boolean} * @readonly */ @@ -81,7 +81,7 @@ class MessagePayload { } /** - * Wether or not the target is a message manager + * Wether or not the target is a {@link MessageManager} * @type {boolean} * @readonly */ @@ -91,7 +91,7 @@ class MessagePayload { } /** - * Whether or not the target is an interaction + * Whether or not the target is an {@link Interaction} or an {@link InteractionWebhook} * @type {boolean} * @readonly */ @@ -242,7 +242,7 @@ class MessagePayload { } /** - * Creates a `MessagePayload` from user-level arguments. + * Creates a {@link MessagePayload} from user-level arguments. * @param {MessageTarget} target Target to send to * @param {string|MessageOptions|WebhookMessageOptions} options Options or content to use * @param {MessageOptions|WebhookMessageOptions} [extra={}] - Extra options to add onto specified options diff --git a/src/structures/MessageReaction.js b/src/structures/MessageReaction.js index a6d532823b82..8e5f77c3046b 100644 --- a/src/structures/MessageReaction.js +++ b/src/structures/MessageReaction.js @@ -71,7 +71,7 @@ class MessageReaction { } /** - * The emoji of this reaction, either an GuildEmoji object for known custom emojis, or a ReactionEmoji + * The emoji of this reaction. Either a {@link GuildEmoji} object for known custom emojis, or a {@link ReactionEmoji} * object which has fewer properties. Whatever the prototype of the emoji, it will still have * `name`, `id`, `identifier` and `toString()` * @type {GuildEmoji|ReactionEmoji} diff --git a/src/structures/PermissionOverwrites.js b/src/structures/PermissionOverwrites.js index d810b42da862..edb00db40ca0 100644 --- a/src/structures/PermissionOverwrites.js +++ b/src/structures/PermissionOverwrites.js @@ -135,14 +135,16 @@ class PermissionOverwrites extends Base { /** * The raw data for a permission overwrite * @typedef {Object} RawOverwriteData - * @property {Snowflake} id The id of the overwrite + * @property {Snowflake} id The id of the {@link Role} or {@link User} this overwrite belongs to * @property {string} allow The permissions to allow * @property {string} deny The permissions to deny * @property {number} type The type of this OverwriteData */ /** - * Data that can be resolved into {@link RawOverwriteData} + * Data that can be resolved into {@link RawOverwriteData}. This can be: + * * PermissionOverwrites + * * OverwriteData * @typedef {PermissionOverwrites|OverwriteData} OverwriteResolvable */ diff --git a/src/structures/Presence.js b/src/structures/Presence.js index 424cba2b653e..47a549636ace 100644 --- a/src/structures/Presence.js +++ b/src/structures/Presence.js @@ -187,11 +187,16 @@ class Activity { this.applicationId = data.application_id ?? null; /** - * Timestamps for the activity - * @type {?Object} + * Represents timestamps of an activity + * @typedef {Object} ActivityTimestamps * @property {?Date} start When the activity started * @property {?Date} end When the activity will end */ + + /** + * Timestamps for the activity + * @type {?ActivityTimestamps} + */ this.timestamps = data.timestamps ? { start: data.timestamps.start ? new Date(Number(data.timestamps.start)) : null, @@ -212,11 +217,16 @@ class Activity { this.platform = data.platform ?? null; /** - * Party of the activity - * @type {?Object} + * Represents a party of an activity + * @typedef {Object} ActivityParty * @property {?string} id The party's id * @property {number[]} size Size of the party as `[current, max]` */ + + /** + * Party of the activity + * @type {?ActivityParty} + */ this.party = data.party ?? null; /** @@ -330,7 +340,7 @@ class RichPresenceAssets { /** * Gets the URL of the small image asset * @param {StaticImageURLOptions} [options] Options for the image url - * @returns {?string} The small image URL + * @returns {?string} */ smallImageURL({ format, size } = {}) { return ( @@ -345,7 +355,7 @@ class RichPresenceAssets { /** * Gets the URL of the large image asset * @param {StaticImageURLOptions} [options] Options for the image url - * @returns {?string} The large image URL + * @returns {?string} */ largeImageURL({ format, size } = {}) { if (!this.largeImage) return null; diff --git a/src/structures/Team.js b/src/structures/Team.js index 9207478a07e8..5ac80f7b2744 100644 --- a/src/structures/Team.js +++ b/src/structures/Team.js @@ -82,7 +82,7 @@ class Team extends Base { /** * A link to the teams's icon. * @param {StaticImageURLOptions} [options={}] Options for the Image URL - * @returns {?string} URL to the icon + * @returns {?string} */ iconURL({ format, size } = {}) { if (!this.icon) return null; diff --git a/src/structures/ThreadChannel.js b/src/structures/ThreadChannel.js index f31af56b9af0..c7c7b30f4565 100644 --- a/src/structures/ThreadChannel.js +++ b/src/structures/ThreadChannel.js @@ -237,7 +237,8 @@ class ThreadChannel extends Channel { } /** - * Fetches the owner of this thread + * Fetches the owner of this thread. If the thread member object isn't needed, + * use {@link ThreadChannel#ownerId} instead. * @param {FetchOwnerOptions} [options] The options for fetching the member * @returns {Promise} */ diff --git a/src/structures/VoiceState.js b/src/structures/VoiceState.js index 6cca99404c80..0dc8668b313c 100644 --- a/src/structures/VoiceState.js +++ b/src/structures/VoiceState.js @@ -58,7 +58,7 @@ class VoiceState extends Base { */ this.sessionId = data.session_id ?? null; /** - * Whether this member is streaming using "Go Live" + * Whether this member is streaming using "Screen Share" * @type {boolean} */ this.streaming = data.self_stream ?? false; diff --git a/src/structures/interfaces/Application.js b/src/structures/interfaces/Application.js index 2dad85da9b0d..29a1d5b5f5f3 100644 --- a/src/structures/interfaces/Application.js +++ b/src/structures/interfaces/Application.js @@ -63,7 +63,7 @@ class Application extends Base { /** * A link to the application's icon. * @param {StaticImageURLOptions} [options={}] Options for the Image URL - * @returns {?string} URL to the icon + * @returns {?string} */ iconURL({ format, size } = {}) { if (!this.icon) return null; @@ -73,7 +73,7 @@ class Application extends Base { /** * A link to this application's cover image. * @param {StaticImageURLOptions} [options={}] Options for the Image URL - * @returns {?string} URL to the cover image + * @returns {?string} */ coverURL({ format, size } = {}) { if (!this.cover) return null; diff --git a/src/util/ApplicationFlags.js b/src/util/ApplicationFlags.js index f610e384bae1..c764f590291c 100644 --- a/src/util/ApplicationFlags.js +++ b/src/util/ApplicationFlags.js @@ -23,9 +23,6 @@ class ApplicationFlags extends BitField {} /** * Numeric application flags. All available properties: - * * `MANAGED_EMOJI` - * * `GROUP_DM_CREATE` - * * `RPC_HAS_CONNECTED` * * `GATEWAY_PRESENCE` * * `GATEWAY_PRESENCE_LIMITED` * * `GATEWAY_GUILD_MEMBERS` @@ -33,11 +30,9 @@ class ApplicationFlags extends BitField {} * * `VERIFICATION_PENDING_GUILD_LIMIT` * * `EMBEDDED` * @type {Object} + * @see {@link https://discord.com/developers/docs/resources/application#application-object-application-flags} */ ApplicationFlags.FLAGS = { - MANAGED_EMOJI: 1 << 2, - GROUP_DM_CREATE: 1 << 4, - RPC_HAS_CONNECTED: 1 << 11, GATEWAY_PRESENCE: 1 << 12, GATEWAY_PRESENCE_LIMITED: 1 << 13, GATEWAY_GUILD_MEMBERS: 1 << 14, diff --git a/src/util/BitField.js b/src/util/BitField.js index 889dbf27e517..75ae7eff4f9b 100644 --- a/src/util/BitField.js +++ b/src/util/BitField.js @@ -57,7 +57,7 @@ class BitField { /** * Freezes these bits, making them immutable. - * @returns {Readonly} These bits + * @returns {Readonly} */ freeze() { return Object.freeze(this); diff --git a/src/util/Constants.js b/src/util/Constants.js index 90d802c9d413..9cc854cacb92 100644 --- a/src/util/Constants.js +++ b/src/util/Constants.js @@ -34,15 +34,15 @@ function makeImageUrl(root, { format = 'webp', size } = {}) { /** * Options for static Image URLs. * @typedef {Object} StaticImageURLOptions - * @property {string} [format] One of `webp`, `png`, `jpg`, `jpeg`, `gif`. If no format is provided, - * defaults to `webp` + * @property {string} [format='webp'] One of `webp`, `png`, `jpg`, `jpeg`. * @property {number} [size] One of `16`, `32`, `64`, `128`, `256`, `512`, `1024`, `2048`, `4096` */ +// https://discord.com/developers/docs/reference#image-formatting-cdn-endpoints exports.Endpoints = { CDN(root) { return { - Emoji: (emojiId, format = 'png') => `${root}/emojis/${emojiId}.${format}`, + Emoji: (emojiId, format = 'webp') => `${root}/emojis/${emojiId}.${format}`, Asset: name => `${root}/assets/${name}`, DefaultAvatar: discriminator => `${root}/embed/avatars/${discriminator}.png`, Avatar: (userId, hash, format = 'webp', size, dynamic = false) => { @@ -262,6 +262,7 @@ exports.PartialTypes = keyMirror(['USER', 'CHANNEL', 'GUILD_MEMBER', 'MESSAGE', * * STAGE_INSTANCE_DELETE * * GUILD_STICKERS_UPDATE * @typedef {string} WSEventType + * @see {@link https://discord.com/developers/docs/topics/gateway#commands-and-events-gateway-events} */ exports.WSEvents = keyMirror([ 'READY', @@ -332,6 +333,7 @@ exports.WSEvents = keyMirror([ * * `gdm.join`: allows joining the user to a group dm * * `webhook.incoming`: generates a webhook to a channel * @typedef {string} InviteScope + * @see {@link https://discord.com/developers/docs/topics/oauth2#shared-resources-oauth2-scopes} */ exports.InviteScopes = [ 'applications.builds.read', @@ -356,7 +358,7 @@ exports.InviteScopes = [ * * CALL * * CHANNEL_NAME_CHANGE * * CHANNEL_ICON_CHANGE - * * PINS_ADD + * * CHANNEL_PINNED_MESSAGE * * GUILD_MEMBER_JOIN * * USER_PREMIUM_GUILD_SUBSCRIPTION * * USER_PREMIUM_GUILD_SUBSCRIPTION_TIER_1 @@ -373,6 +375,7 @@ exports.InviteScopes = [ * * THREAD_STARTER_MESSAGE * * GUILD_INVITE_REMINDER * @typedef {string} MessageType + * @see {@link https://discord.com/developers/docs/resources/channel#message-object-message-types} */ exports.MessageTypes = [ 'DEFAULT', @@ -381,7 +384,7 @@ exports.MessageTypes = [ 'CALL', 'CHANNEL_NAME_CHANGE', 'CHANNEL_ICON_CHANGE', - 'PINS_ADD', + 'CHANNEL_PINNED_MESSAGE', 'GUILD_MEMBER_JOIN', 'USER_PREMIUM_GUILD_SUBSCRIPTION', 'USER_PREMIUM_GUILD_SUBSCRIPTION_TIER_1', @@ -413,7 +416,7 @@ exports.SystemMessageTypes = exports.MessageTypes.filter( /** * Bots cannot set a `CUSTOM` activity type, it is only for custom statuses received from users - * The type of an activity of a users presence, e.g. `PLAYING`. Here are the available types: + * The type of an activity of a user's presence. Here are the available types: * * PLAYING * * STREAMING * * LISTENING @@ -421,6 +424,7 @@ exports.SystemMessageTypes = exports.MessageTypes.filter( * * CUSTOM * * COMPETING * @typedef {string} ActivityType + * @see {@link https://discord.com/developers/docs/game-sdk/activities#data-models-activitytype-enum} */ exports.ActivityTypes = createEnum(['PLAYING', 'STREAMING', 'LISTENING', 'WATCHING', 'CUSTOM', 'COMPETING']); @@ -439,6 +443,7 @@ exports.ActivityTypes = createEnum(['PLAYING', 'STREAMING', 'LISTENING', 'WATCHI * * `GUILD_STAGE_VOICE` - a guild stage voice channel * * `UNKNOWN` - a generic channel of unknown type, could be Channel or GuildChannel * @typedef {string} ChannelType + * @see {@link https://discord.com/developers/docs/resources/channel#channel-object-channel-types} */ exports.ChannelTypes = createEnum([ 'GUILD_TEXT', @@ -545,6 +550,7 @@ exports.Colors = { * * MEMBERS_WITHOUT_ROLES * * ALL_MEMBERS * @typedef {string} ExplicitContentFilterLevel + * @see {@link https://discord.com/developers/docs/resources/guild#guild-object-explicit-content-filter-level} */ exports.ExplicitContentFilterLevels = createEnum(['DISABLED', 'MEMBERS_WITHOUT_ROLES', 'ALL_MEMBERS']); @@ -556,6 +562,7 @@ exports.ExplicitContentFilterLevels = createEnum(['DISABLED', 'MEMBERS_WITHOUT_R * * HIGH * * VERY_HIGH * @typedef {string} VerificationLevel + * @see {@link https://discord.com/developers/docs/resources/guild#guild-object-verification-level} */ exports.VerificationLevels = createEnum(['NONE', 'LOW', 'MEDIUM', 'HIGH', 'VERY_HIGH']); @@ -685,6 +692,7 @@ exports.VerificationLevels = createEnum(['NONE', 'LOW', 'MEDIUM', 'HIGH', 'VERY_ * * MAXIMUM_ACTIVE_THREADS * * MAXIMUM_ACTIVE_ANNOUCEMENT_THREAD * @typedef {string} APIError + * @see {@link https://discord.com/developers/docs/topics/opcodes-and-status-codes#json-json-error-codes} */ exports.APIErrors = { UNKNOWN_ACCOUNT: 10001, @@ -827,6 +835,7 @@ exports.APIErrors = { * * ALL_MESSAGES * * ONLY_MENTIONS * @typedef {string} DefaultMessageNotificationLevel + * @see {@link https://discord.com/developers/docs/resources/guild#guild-object-default-message-notification-level} */ exports.DefaultMessageNotificationLevels = createEnum(['ALL_MESSAGES', 'ONLY_MENTIONS']); @@ -835,6 +844,7 @@ exports.DefaultMessageNotificationLevels = createEnum(['ALL_MESSAGES', 'ONLY_MEN * * INVITED * * ACCEPTED * @typedef {string} MembershipState + * @see {@link https://discord.com/developers/docs/topics/teams#data-models-membership-state-enum} */ exports.MembershipStates = createEnum([null, 'INVITED', 'ACCEPTED']); @@ -842,15 +852,18 @@ exports.MembershipStates = createEnum([null, 'INVITED', 'ACCEPTED']); * The value set for a webhook's type: * * Incoming * * Channel Follower + * * Application * @typedef {string} WebhookType + * @see {@link https://discord.com/developers/docs/resources/webhook#webhook-object-webhook-types} */ -exports.WebhookTypes = createEnum([null, 'Incoming', 'Channel Follower']); +exports.WebhookTypes = createEnum([null, 'Incoming', 'Channel Follower', 'Application']); /** * The value set for a sticker's type: * * STANDARD * * GUILD * @typedef {string} StickerType + * @see {@link https://discord.com/developers/docs/resources/sticker#sticker-object-sticker-types} */ exports.StickerTypes = createEnum([null, 'STANDARD', 'GUILD']); @@ -860,6 +873,7 @@ exports.StickerTypes = createEnum([null, 'STANDARD', 'GUILD']); * * APNG * * LOTTIE * @typedef {string} StickerFormatType + * @see {@link https://discord.com/developers/docs/resources/sticker#sticker-object-sticker-format-types} */ exports.StickerFormatTypes = createEnum([null, 'PNG', 'APNG', 'LOTTIE']); @@ -868,9 +882,11 @@ exports.StickerFormatTypes = createEnum([null, 'PNG', 'APNG', 'LOTTIE']); * * role * * member * @typedef {string} OverwriteType + * @see {@link https://discord.com/developers/docs/resources/channel#overwrite-object-overwrite-structure} */ exports.OverwriteTypes = createEnum(['role', 'member']); +/* eslint-disable max-len */ /** * The type of an {@link ApplicationCommandOption} object: * * SUB_COMMAND @@ -884,6 +900,7 @@ exports.OverwriteTypes = createEnum(['role', 'member']); * * MENTIONABLE * * NUMBER * @typedef {string} ApplicationCommandOptionType + * @see {@link https://discord.com/developers/docs/interactions/slash-commands#application-command-object-application-command-option-type} */ exports.ApplicationCommandOptionTypes = createEnum([ null, @@ -904,6 +921,7 @@ exports.ApplicationCommandOptionTypes = createEnum([ * * ROLE * * USER * @typedef {string} ApplicationCommandPermissionType + * @see {@link https://discord.com/developers/docs/interactions/slash-commands#application-command-permissions-object-application-command-permission-type} */ exports.ApplicationCommandPermissionTypes = createEnum([null, 'ROLE', 'USER']); @@ -913,6 +931,7 @@ exports.ApplicationCommandPermissionTypes = createEnum([null, 'ROLE', 'USER']); * * APPLICATION_COMMAND * * MESSAGE_COMPONENT * @typedef {string} InteractionType + * @see {@link https://discord.com/developers/docs/interactions/slash-commands#interaction-object-interaction-request-type} */ exports.InteractionTypes = createEnum([null, 'PING', 'APPLICATION_COMMAND', 'MESSAGE_COMPONENT']); @@ -924,6 +943,7 @@ exports.InteractionTypes = createEnum([null, 'PING', 'APPLICATION_COMMAND', 'MES * * DEFERRED_MESSAGE_UPDATE * * UPDATE_MESSAGE * @typedef {string} InteractionResponseType + * @see {@link https://discord.com/developers/docs/interactions/slash-commands#interaction-response-object-interaction-callback-type} */ exports.InteractionResponseTypes = createEnum([ null, @@ -935,6 +955,7 @@ exports.InteractionResponseTypes = createEnum([ 'DEFERRED_MESSAGE_UPDATE', 'UPDATE_MESSAGE', ]); +/* eslint-enable max-len */ /** * The type of a message component @@ -942,6 +963,7 @@ exports.InteractionResponseTypes = createEnum([ * * BUTTON * * SELECT_MENU * @typedef {string} MessageComponentType + * @see {@link https://discord.com/developers/docs/interactions/message-components#component-object-component-types} */ exports.MessageComponentTypes = createEnum([null, 'ACTION_ROW', 'BUTTON', 'SELECT_MENU']); @@ -953,6 +975,7 @@ exports.MessageComponentTypes = createEnum([null, 'ACTION_ROW', 'BUTTON', 'SELEC * * DANGER * * LINK * @typedef {string} MessageButtonStyle + * @see {@link https://discord.com/developers/docs/interactions/message-components#button-object-button-styles} */ exports.MessageButtonStyles = createEnum([null, 'PRIMARY', 'SECONDARY', 'SUCCESS', 'DANGER', 'LINK']); @@ -961,6 +984,7 @@ exports.MessageButtonStyles = createEnum([null, 'PRIMARY', 'SECONDARY', 'SUCCESS * * NONE * * ELEVATED * @typedef {string} MFALevel + * @see {@link https://discord.com/developers/docs/resources/guild#guild-object-mfa-level} */ exports.MFALevels = createEnum(['NONE', 'ELEVATED']); @@ -971,6 +995,7 @@ exports.MFALevels = createEnum(['NONE', 'ELEVATED']); * * SAFE * * AGE_RESTRICTED * @typedef {string} NSFWLevel + * @see {@link https://discord.com/developers/docs/resources/guild#guild-object-guild-nsfw-level} */ exports.NSFWLevels = createEnum(['DEFAULT', 'EXPLICIT', 'SAFE', 'AGE_RESTRICTED']); @@ -979,6 +1004,7 @@ exports.NSFWLevels = createEnum(['DEFAULT', 'EXPLICIT', 'SAFE', 'AGE_RESTRICTED' * * PUBLIC * * GUILD_ONLY * @typedef {string} PrivacyLevel + * @see {@link https://discord.com/developers/docs/resources/stage-instance#stage-instance-object-privacy-level} */ exports.PrivacyLevels = createEnum([null, 'PUBLIC', 'GUILD_ONLY']); @@ -989,6 +1015,7 @@ exports.PrivacyLevels = createEnum([null, 'PUBLIC', 'GUILD_ONLY']); * * TIER_2 * * TIER_3 * @typedef {string} PremiumTier + * @see {@link https://discord.com/developers/docs/resources/guild#guild-object-premium-tier} */ exports.PremiumTiers = createEnum(['NONE', 'TIER_1', 'TIER_2', 'TIER_3']); diff --git a/src/util/LimitedCollection.js b/src/util/LimitedCollection.js index f2266b2e30bc..f8ed977bac21 100644 --- a/src/util/LimitedCollection.js +++ b/src/util/LimitedCollection.js @@ -100,11 +100,11 @@ class LimitedCollection extends Collection { /** * Options for generating a filter function based on lifetime * @typedef {Object} LifetimeFilterOptions - * @property {number} [lifetime=14400] How long an entry should stay in the collection before it is considered - * sweepable. - * @property {Function} [getComparisonTimestamp=`e => e.createdTimestamp`] A function that takes an entry, key, + * @property {number} [lifetime=14400] How long, in seconds, an entry should stay in the collection + * before it is considered sweepable. + * @property {Function} [getComparisonTimestamp=e => e?.createdTimestamp] A function that takes an entry, key, * and the collection and returns a timestamp to compare against in order to determine the lifetime of the entry. - * @property {Function} [excludeFromSweep=`() => false`] A function that takes an entry, key, and the collection + * @property {Function} [excludeFromSweep=() => false] A function that takes an entry, key, and the collection * and returns a boolean, `true` when the entry should not be checked for sweepability. */ diff --git a/src/util/Permissions.js b/src/util/Permissions.js index fceb0527591d..5ce6cc1ace95 100644 --- a/src/util/Permissions.js +++ b/src/util/Permissions.js @@ -57,10 +57,10 @@ class Permissions extends BitField { /** * Numeric permission flags. All available properties: - * * `ADMINISTRATOR` (implicitly has *all* permissions, and bypasses all channel overwrites) * * `CREATE_INSTANT_INVITE` (create invitations to the guild) * * `KICK_MEMBERS` * * `BAN_MEMBERS` + * * `ADMINISTRATOR` (implicitly has *all* permissions, and bypasses all channel overwrites) * * `MANAGE_CHANNELS` (edit and reorder channels) * * `MANAGE_GUILD` (edit the guild information, region, etc.) * * `ADD_REACTIONS` (add new reactions to messages) @@ -95,7 +95,7 @@ class Permissions extends BitField { * * `USE_PRIVATE_THREADS` * * `USE_EXTERNAL_STICKERS` (use stickers from different guilds) * @type {Object} - * @see {@link https://discord.com/developers/docs/topics/permissions} + * @see {@link https://discord.com/developers/docs/topics/permissions#permissions-bitwise-permission-flags} */ Permissions.FLAGS = { CREATE_INSTANT_INVITE: 1n << 0n, diff --git a/src/util/SnowflakeUtil.js b/src/util/SnowflakeUtil.js index 656c5f3dd048..3321e770b914 100644 --- a/src/util/SnowflakeUtil.js +++ b/src/util/SnowflakeUtil.js @@ -11,10 +11,11 @@ let INCREMENT = 0; */ class SnowflakeUtil extends null { /** - * A Twitter snowflake, except the epoch is 2015-01-01T00:00:00.000Z - * ``` - * If we have a snowflake '266241948824764416' we can represent it as binary: + * A {@link https://developer.twitter.com/en/docs/twitter-ids Twitter snowflake}, + * except the epoch is 2015-01-01T00:00:00.000Z. * + * If we have a snowflake '266241948824764416' we can represent it as binary: + * ``` * 64 22 17 12 0 * 000000111011000111100001101001000101000000 00001 00000 000000000000 * number of ms since Discord epoch worker pid increment @@ -56,7 +57,7 @@ class SnowflakeUtil extends null { /** * Deconstructs a Discord snowflake. * @param {Snowflake} snowflake Snowflake to deconstruct - * @returns {DeconstructedSnowflake} Deconstructed snowflake + * @returns {DeconstructedSnowflake} */ static deconstruct(snowflake) { const BINARY = Util.idToBinary(snowflake).toString(2).padStart(64, '0'); diff --git a/src/util/SystemChannelFlags.js b/src/util/SystemChannelFlags.js index c4d16a6de843..2979ac024963 100644 --- a/src/util/SystemChannelFlags.js +++ b/src/util/SystemChannelFlags.js @@ -38,6 +38,7 @@ class SystemChannelFlags extends BitField {} * * `SUPPRESS_PREMIUM_SUBSCRIPTIONS` (Suppress server boost notifications) * * `SUPPRESS_GUILD_REMINDER_NOTIFICATIONS` (Suppress server setup tips) * @type {Object} + * @see {@link https://discord.com/developers/docs/resources/guild#guild-object-system-channel-flags} */ SystemChannelFlags.FLAGS = { SUPPRESS_JOIN_NOTIFICATIONS: 1 << 0, diff --git a/typings/enums.d.ts b/typings/enums.d.ts index df1891db5ad0..58938da25a68 100644 --- a/typings/enums.d.ts +++ b/typings/enums.d.ts @@ -143,4 +143,5 @@ export enum VerificationLevels { export enum WebhookTypes { Incoming = 1, 'Channel Follower' = 2, + Application = 3, } diff --git a/typings/index.d.ts b/typings/index.d.ts index bd9fd5ff6b98..fe684b6bd9fc 100644 --- a/typings/index.d.ts +++ b/typings/index.d.ts @@ -647,7 +647,7 @@ export class Guild extends AnonymousGuild { public members: GuildMemberManager; public mfaLevel: MFALevel; public ownerId: Snowflake; - public preferredLocale: string; + public preferredLocale?: string; public premiumSubscriptionCount: number | null; public premiumTier: PremiumTier; public presences: PresenceManager; @@ -2141,22 +2141,32 @@ export const Constants: { CDN: (root: string) => { Asset: (name: string) => string; DefaultAvatar: (id: Snowflake | number) => string; - Emoji: (emojiId: Snowflake, format: 'png' | 'gif') => string; - Avatar: ( + Emoji: (emojiId: Snowflake, format: DynamicImageFormat) => string; + Avatar: (userId: Snowflake, hash: string, format: DynamicImageFormat, size: AllowedImageSize) => string; + Banner: (guildId: Snowflake | number, hash: string, format: AllowedImageFormat, size: AllowedImageSize) => string; + Icon: (userId: Snowflake | number, hash: string, format: DynamicImageFormat, size: AllowedImageSize) => string; + AppIcon: (userId: Snowflake | number, hash: string, format: AllowedImageFormat, size: AllowedImageSize) => string; + AppAsset: ( userId: Snowflake | number, hash: string, - format: 'default' | AllowedImageFormat, - size: number, + format: AllowedImageFormat, + size: AllowedImageSize, + ) => string; + StickerPackBanner: (bannerId: Snowflake, format: AllowedImageFormat, size: AllowedImageSize) => string; + GDMIcon: (userId: Snowflake | number, hash: string, format: AllowedImageFormat, size: AllowedImageSize) => string; + Splash: (guildId: Snowflake | number, hash: string, format: AllowedImageFormat, size: AllowedImageSize) => string; + DiscoverySplash: ( + guildId: Snowflake | number, + hash: string, + format: AllowedImageFormat, + size: AllowedImageSize, + ) => string; + TeamIcon: ( + teamId: Snowflake | number, + hash: string, + format: AllowedImageFormat, + size: AllowedImageSize, ) => string; - Banner: (guildId: Snowflake | number, hash: string, format: AllowedImageFormat, size: number) => string; - Icon: (userId: Snowflake | number, hash: string, format: 'default' | AllowedImageFormat, size: number) => string; - AppIcon: (userId: Snowflake | number, hash: string, format: AllowedImageFormat, size: number) => string; - AppAsset: (userId: Snowflake | number, hash: string, format: AllowedImageFormat, size: number) => string; - StickerPackBanner: (bannerId: Snowflake, format: AllowedImageFormat, size: number) => string; - GDMIcon: (userId: Snowflake | number, hash: string, format: AllowedImageFormat, size: number) => string; - Splash: (guildId: Snowflake | number, hash: string, format: AllowedImageFormat, size: number) => string; - DiscoverySplash: (guildId: Snowflake | number, hash: string, format: AllowedImageFormat, size: number) => string; - TeamIcon: (teamId: Snowflake | number, hash: string, format: AllowedImageFormat, size: number) => string; Sticker: (stickerId: Snowflake, stickerFormat: StickerFormatType) => string; }; }; @@ -2693,7 +2703,9 @@ export interface AddGuildMemberOptions { fetchWhenExisting?: boolean; } -export type AllowedImageFormat = 'webp' | 'png' | 'jpg' | 'jpeg' | 'gif'; +export type AllowedImageFormat = 'webp' | 'png' | 'jpg' | 'jpeg'; + +export type AllowedImageSize = 16 | 32 | 64 | 128 | 256 | 512 | 1024 | 2048 | 4096; export type AllowedPartial = User | Channel | GuildMember | Message | MessageReaction; @@ -2885,9 +2897,6 @@ export type ApplicationCommandPermissionType = keyof typeof ApplicationCommandPe export type ApplicationCommandResolvable = ApplicationCommand | Snowflake; export type ApplicationFlagsString = - | 'MANAGED_EMOJI' - | 'GROUP_DM_CREATE' - | 'RPC_HAS_CONNECTED' | 'GATEWAY_PRESENCE' | 'GATEWAY_PRESENCE_LIMITED' | 'GATEWAY_GUILD_MEMBERS' @@ -3384,6 +3393,8 @@ export interface DeconstructedSnowflake { export type DefaultMessageNotificationLevel = keyof typeof DefaultMessageNotificationLevels; +export type DynamicImageFormat = AllowedImageFormat | 'gif'; + export interface EditGuildTemplateOptions { name?: string; description?: string; @@ -3699,20 +3710,19 @@ export type GuildFeatures = | 'FEATURABLE' | 'INVITE_SPLASH' | 'MEMBER_VERIFICATION_GATE_ENABLED' - | 'MONETIZATION_ENABLED' - | 'MORE_STICKERS' | 'NEWS' | 'PARTNERED' | 'PREVIEW_ENABLED' - | 'PRIVATE_THREADS' - | 'RELAY_ENABLED' - | 'SEVEN_DAY_THREAD_ARCHIVE' - | 'THREE_DAY_THREAD_ARCHIVE' - | 'TICKETED_EVENTS_ENABLED' | 'VANITY_URL' | 'VERIFIED' | 'VIP_REGIONS' - | 'WELCOME_SCREEN_ENABLED'; + | 'WELCOME_SCREEN_ENABLED' + | 'TICKETED_EVENTS_ENABLED' + | 'MONETIZATION_ENABLED' + | 'MORE_STICKERS' + | 'THREE_DAY_THREAD_ARCHIVE' + | 'SEVEN_DAY_THREAD_ARCHIVE' + | 'PRIVATE_THREADS'; export interface GuildMemberEditData { nick?: string | null; @@ -3772,8 +3782,6 @@ export interface HTTPOptions { headers?: Record; } -export type ImageSize = 16 | 32 | 64 | 128 | 256 | 512 | 1024 | 2048 | 4096; - export interface ImageURLOptions extends StaticImageURLOptions { dynamic?: boolean; } @@ -4114,7 +4122,7 @@ export type MessageType = | 'CALL' | 'CHANNEL_NAME_CHANGE' | 'CHANNEL_ICON_CHANGE' - | 'PINS_ADD' + | 'CHANNEL_PINNED_MESSAGE' | 'GUILD_MEMBER_JOIN' | 'USER_PREMIUM_GUILD_SUBSCRIPTION' | 'USER_PREMIUM_GUILD_SUBSCRIPTION_TIER_1' @@ -4370,7 +4378,7 @@ export interface SplitOptions { export interface StaticImageURLOptions { format?: AllowedImageFormat; - size?: ImageSize; + size?: AllowedImageSize; } export type StageInstanceResolvable = StageInstance | Snowflake;