From 24703f13dd3c73d8d9a07b4bea68a33ce3f1dbb1 Mon Sep 17 00:00:00 2001 From: Fleny Date: Sat, 26 Apr 2025 08:31:01 +0200 Subject: [PATCH] fix(types)!: Remove incorrect, reorder and fixes in channel (#4151) * Remove incorrect, reorder and fixes in channel - Updated comments to be more clear - Remove `Channel.newly_created`, doesn't seem to exist in the api docs - Fix nullability for some fields - Remove DiscordActiveThreads, DiscordArchivedThreads and DiscordListActiveThreads as they don't seem to match anything in the api * Add back DiscordListActiveThreads but under Guild and fix type errors * Update packages/types/src/discord/channel.ts Co-authored-by: LTS (Link) * Revert newly_created removal * Apply suggestions from code review Co-authored-by: LTS (Link) --------- Co-authored-by: LTS (Link) --- packages/bot/src/helpers.ts | 8 +- packages/rest/src/types.ts | 16 +-- packages/types/src/discord/channel.ts | 166 +++++++++++++++++--------- packages/types/src/discord/guild.ts | 10 +- 4 files changed, 132 insertions(+), 68 deletions(-) diff --git a/packages/bot/src/helpers.ts b/packages/bot/src/helpers.ts index 837b48c78..6822689bb 100644 --- a/packages/bot/src/helpers.ts +++ b/packages/bot/src/helpers.ts @@ -35,7 +35,6 @@ import type { DiscordApplicationCommandPermissions, DiscordApplicationRoleConnection, DiscordApplicationRoleConnectionMetadata, - DiscordArchivedThreads, DiscordAuditLog, DiscordBan, DiscordConnection, @@ -46,6 +45,7 @@ import type { DiscordGuildWidgetSettings, DiscordInvite, DiscordInviteMetadata, + DiscordListArchivedThreads, DiscordMessage, DiscordModifyGuildWelcomeScreen, DiscordPrunedCount, @@ -1018,10 +1018,10 @@ export type BotHelpers Promise getOriginalInteractionResponse: (token: string) => Promise> getPinnedMessages: (channelId: BigString) => Promise[]> - getPrivateArchivedThreads: (channelId: BigString, options?: ListArchivedThreads) => Promise> - getPrivateJoinedArchivedThreads: (channelId: BigString, options?: ListArchivedThreads) => Promise> + getPrivateArchivedThreads: (channelId: BigString, options?: ListArchivedThreads) => Promise> + getPrivateJoinedArchivedThreads: (channelId: BigString, options?: ListArchivedThreads) => Promise> getPruneCount: (guildId: BigString, options?: GetGuildPruneCountQuery) => Promise> - getPublicArchivedThreads: (channelId: BigString, options?: ListArchivedThreads) => Promise> + getPublicArchivedThreads: (channelId: BigString, options?: ListArchivedThreads) => Promise> getRoles: (guildId: BigString) => Promise[]> getRole: (guildId: BigString, roleId: BigString) => Promise> getScheduledEvent: ( diff --git a/packages/rest/src/types.ts b/packages/rest/src/types.ts index 9174e74a8..d3a37f5bd 100644 --- a/packages/rest/src/types.ts +++ b/packages/rest/src/types.ts @@ -31,14 +31,12 @@ import type { CreateWebhook, DeleteWebhookMessageOptions, DiscordAccessTokenResponse, - DiscordActiveThreads, DiscordActivityInstance, DiscordApplication, DiscordApplicationCommand, DiscordApplicationCommandPermissions, DiscordApplicationRoleConnection, DiscordApplicationRoleConnectionMetadata, - DiscordArchivedThreads, DiscordAuditLog, DiscordAutoModerationRule, DiscordBan, @@ -62,6 +60,8 @@ import type { DiscordInteractionCallbackResponse, DiscordInvite, DiscordInviteMetadata, + DiscordListActiveThreads, + DiscordListArchivedThreads, DiscordLobby, DiscordLobbyMember, DiscordMember, @@ -1573,7 +1573,7 @@ export interface RestManager { * Gets the list of all active threads for a guild. * * @param guildId - The ID of the guild to get the threads of. - * @returns An instance of {@link DiscordActiveThreads}. + * @returns An instance of {@link DiscordListActiveThreads}. * * @remarks * Returns both public and private threads. @@ -1582,7 +1582,7 @@ export interface RestManager { * * @see {@link https://discord.com/developers/docs/resources/guild#list-active-guild-threads} */ - getActiveThreads: (guildId: BigString) => Promise> + getActiveThreads: (guildId: BigString) => Promise> /** Get the applications info */ getApplicationInfo: () => Promise> /** @@ -2116,7 +2116,7 @@ export interface RestManager { * * @param channelId - The ID of the channel to get the archived threads for. * @param options - The parameters for the fetching of threads. - * @returns An instance of {@link DiscordArchivedThreads}. + * @returns An instance of {@link DiscordListArchivedThreads}. * * @remarks * Requires the `READ_MESSAGE_HISTORY` permission. @@ -2128,7 +2128,7 @@ export interface RestManager { * * @see {@link https://discord.com/developers/docs/resources/channel#list-private-archived-threads} */ - getPrivateArchivedThreads: (channelId: BigString, options?: ListArchivedThreads) => Promise> + getPrivateArchivedThreads: (channelId: BigString, options?: ListArchivedThreads) => Promise> /** * Gets the list of private archived threads the bot is a member of for a channel. * @@ -2145,7 +2145,7 @@ export interface RestManager { * * @see {@link https://discord.com/developers/docs/resources/channel#list-joined-private-archived-threads} */ - getPrivateJoinedArchivedThreads: (channelId: BigString, options?: ListArchivedThreads) => Promise> + getPrivateJoinedArchivedThreads: (channelId: BigString, options?: ListArchivedThreads) => Promise> /** * Gets the number of members that would be kicked from a guild during pruning. * @@ -2176,7 +2176,7 @@ export interface RestManager { * * @see {@link https://discord.com/developers/docs/resources/channel#list-public-archived-threads} */ - getPublicArchivedThreads: (channelId: BigString, options?: ListArchivedThreads) => Promise> + getPublicArchivedThreads: (channelId: BigString, options?: ListArchivedThreads) => Promise> /** * Gets the list of roles for a guild. * diff --git a/packages/types/src/discord/channel.ts b/packages/types/src/discord/channel.ts index 03c1f906c..96ded3b60 100644 --- a/packages/types/src/discord/channel.ts +++ b/packages/types/src/discord/channel.ts @@ -11,45 +11,84 @@ export interface DiscordChannel { id: string /** The type of channel */ type: ChannelTypes - /** The id of the guild */ + /** + * The id of the guild + * + * @remarks + * May be missing for some channel object received over gateway guild dispatches + */ guild_id?: string - /** Sorting position of the channel (channels with the same position are sorted by id) */ + /** + * Sorting position of the channel + * + * @remarks + * Channels with the same position are sorted by id + */ position?: number /** Explicit permission overwrites for members and roles */ permission_overwrites?: DiscordOverwrite[] /** The name of the channel (1-100 characters) */ name?: string - /** The channel topic (0-4096 characters for GUILD_FORUM channels, 0-1024 characters for all others) */ + /** + * The channel topic + * + * @remarks + * The limit is max of 4096 characters for GUILD_FORUM channels and a max of 1024 characters for all others channel types + */ topic?: string | null /** Whether the channel is nsfw */ nsfw?: boolean - /** The id of the last message sent in this channel (may not point to an existing or valid message) */ + /** The id of the last message sent in this channel (may not point to an existing or valid message or thread) */ last_message_id?: string | null /** The bitrate (in bits) of the voice or stage channel */ bitrate?: number /** The user limit of the voice or stage channel */ user_limit?: number - /** Amount of seconds a user has to wait before sending another message (0-21600); bots, as well as users with the permission `manage_messages` or `manage_channel`, are unaffected */ + /** + * Amount of seconds a user has to wait before sending another message (0-21600) + * + * @remarks + * Bots, as well as users with the permission `manage_messages` or `manage_channel`, are unaffected + * `rate_limit_per_user` also applies to thread creation. Users can send one message and create one thread during each `rate_limit_per_user` interval. + */ rate_limit_per_user?: number /** the recipients of the DM */ recipients?: DiscordUser[] /** icon hash of the group DM */ icon?: string - /** Id of the creator of the thread */ + /** Id of the creator of the group DM or the thread */ owner_id?: string /** Application id of the group DM creator if it is bot-created */ application_id?: string /** For group DM channels: whether the channel is managed by an application via the `gdm.join` OAuth2 scope. */ managed?: boolean - /** For guild channels: Id of the parent category for a channel (each parent category can contain up to 50 channels), for threads: id of the text channel this thread was created */ + /** + * Id of the parent channel. + * + * @remarks + * For a guild channel this will reference a category ID, each category can contain up to 50 channels. + * + * For threads this will reference the text channel the thread was created in. + */ parent_id?: string | null - /** When the last pinned message was pinned. This may be null in events such as GUILD_CREATE when a message is not pinned. */ + /** + * When the last pinned message was pinned. + * + * @remarks + * This may be null in events such as GUILD_CREATE when a message is not pinned. + */ last_pin_timestamp?: string | null /** Voice region id for the voice or stage channel, automatic when set to null */ rtc_region?: string | null /** The camera video quality mode of the voice channel, 1 when not present */ video_quality_mode?: VideoQualityModes - /** An approximate count of messages in a thread, stops counting at 50 */ + /** + + * An approximate count of messages in a thread, does not include deleted messages or the initial message + * + * @remarks + * For threads created before July 1, 2022, the message count is inaccurate when it's greater than 50. + */ message_count?: number /** An approximate count of users in a thread, stops counting at 50 */ member_count?: number @@ -57,27 +96,49 @@ export interface DiscordChannel { thread_metadata?: DiscordThreadMetadata /** Thread member object for the current user, if they have joined the thread, only included on certain API endpoints */ member?: DiscordThreadMember - /** Default duration for newly created threads, in minutes, to automatically archive the thread after recent activity, can be set to: 60, 1440, 4320, 10080 */ + /** + * Default duration for newly created threads, in minutes, to automatically archive the thread after recent activity. + * + * @remarks + * Can be set to: 60, 1440, 4320, 10080 + */ default_auto_archive_duration?: number - /** computed permissions for the invoking user in the channel, including overwrites, only included when part of the resolved data received on a slash command interaction. This does not include implicit permissions, which may need to be checked separately. */ + /** + * Computed permissions for the invoking user in the channel. + * + * @remarks + * The computed permissions include channel overwrites but does not include implicit permissions, those need to be checked separatly. + * + * Only presented when part of `resolved` data received from a slash command interaction. + */ permissions?: string /** The flags of the channel */ flags?: ChannelFlags /** number of messages ever sent in a thread, it's similar to `message_count` on message creation, but will not decrement the number when a message is deleted */ total_message_sent?: number - /** The set of tags that can be used in a GUILD_FORUM channel */ + /** The set of tags that can be used in a GUILD_FORUM or GUILD_MEDIA channel */ available_tags?: DiscordForumTag[] - /** The IDs of the set of tags that have been applied to a thread in a GUILD_FORUM channel */ + /** The IDs of the set of tags that have been applied to a thread in a GUILD_FORUM or GUILD_MEDIA channel */ applied_tags?: string[] - /** the emoji to show in the add reaction button on a thread in a GUILD_FORUM channel */ + /** the emoji to show in the add reaction button on a thread in a GUILD_FORUM or GUILD_MEDIA channel */ default_reaction_emoji?: DiscordDefaultReactionEmoji | null - /** the initial rate_limit_per_user to set on newly created threads in a channel. this field is copied to the thread at creation time and does not live update. */ + /** + * The initial `rate_limit_per_user` to set on newly created threads in a channel. + * + * @remarks + * This field is copied to the thread at creation time and does not live update. + */ default_thread_rate_limit_per_user?: number /** the default sort order type used to order posts in GUILD_FORUM channels. Defaults to null, which indicates a preferred sort order hasn't been set by a channel admin */ default_sort_order?: SortOrderTypes | null /** the default forum layout view used to display posts in `GUILD_FORUM` channels. Defaults to `0`, which indicates a layout view has not been set by a channel admin */ default_forum_layout?: ForumLayout - /** When a thread is created this will be true on that channel payload for the thread. */ + /** + * When a thread is created this will be true on that channel payload for the thread. + * + * @remarks + * This will only exists on Thread Create gateway events. + */ newly_created?: boolean } @@ -180,42 +241,54 @@ export interface DiscordThreadMetadata { archived: boolean /** Duration in minutes to automatically archive the thread after recent activity */ auto_archive_duration: 60 | 1440 | 4320 | 10080 + /** Timestamp when the thread's archive status was last changed, used for calculating recent activity */ + archive_timestamp: string /** When a thread is locked, only users with `MANAGE_THREADS` can unarchive it */ locked: boolean /** whether non-moderators can add other non-moderators to a thread; only available on private threads */ invitable?: boolean - /** Timestamp when the thread's archive status was last changed, used for calculating recent activity */ - archive_timestamp: string /** Timestamp when the thread was created; only populated for threads created after 2022-01-09 */ create_timestamp?: string | null } /** https://discord.com/developers/docs/resources/channel#thread-member-object-thread-member-structure */ export interface DiscordThreadMember { - /** Any user-thread settings, currently only used for notifications */ - flags: number - /** The id of the thread */ + /** + * The id of the thread + * + * @remarks + * This value is omtted when sent from a `GUILD_CREATE` event + */ id: string - /** The id of the user */ + /** + * The id of the user + * + * @remarks + * This value is omtted when sent from a `GUILD_CREATE` event + */ user_id: string /** The time the current user last joined the thread */ join_timestamp: string - /** The member object of the user */ + /** Any user-thread settings, currently only used for notifications */ + flags: number + /** + * The member object of the user + * + * @remarks + * This value is omtted when sent from a `GUILD_CREATE` event + * + * Only present when `with_member` is true when calling the List Thread Members and Get Thread Member endpoints, + */ member?: DiscordMember } /** https://discord.com/developers/docs/resources/channel#thread-member-object-thread-member-structure, the first asterisk */ -export interface DiscordThreadMemberGuildCreate { - /** Any user-thread settings, currently only used for notifications */ - flags: number - /** The time the current user last joined the thread */ - join_timestamp: string -} +export interface DiscordThreadMemberGuildCreate extends Omit {} /** https://discord.com/developers/docs/resources/channel#default-reaction-object-default-reaction-structure */ export interface DiscordDefaultReactionEmoji { /** The id of a guild's custom emoji */ - emoji_id: string + emoji_id: string | null /** The unicode character of the emoji */ emoji_name: string | null } @@ -228,9 +301,9 @@ export interface DiscordForumTag { name: string /** Whether this tag can only be added to or removed from threads by a member with the MANAGE_THREADS permission */ moderated: boolean - /** The id of a guild's custom emoji At most one of emoji_id and emoji_name may be set. */ - emoji_id: string - /** The unicode character of the emoji */ + /** The id of a guild's custom emoji. At most one of emoji_id and emoji_name may be set. */ + emoji_id: string | null + /** The unicode character of the emoji. At most one of emoji_id and emoji_name may be set. */ emoji_name: string | null } @@ -345,33 +418,16 @@ export interface DiscordCreateForumPostWithMessage { applied_tags?: string[] } -/** https://discord.com/developers/docs/resources/channel#list-public-archived-threads-response-body */ -// TODO: this should be ArchivedThreads, not Active -export interface DiscordActiveThreads { - threads: DiscordChannel[] - members: DiscordThreadMember[] -} - -/** https://discord.com/developers/docs/resources/channel#list-public-archived-threads-response-body */ -export type DiscordArchivedThreads = DiscordActiveThreads & { - // TODO: this should be has_more, not hasMore - hasMore: boolean -} - -// TODO: What does this type exactly match to? The API doesn't seem to have a list ACTIVE threads, only list archived threads -export interface DiscordListActiveThreads { - /** The active threads */ - threads: DiscordChannel[] - /** A thread member object for each returned thread the current user has joined */ - members: DiscordThreadMember[] -} - /** * https://discord.com/developers/docs/resources/channel#list-public-archived-threads * https://discord.com/developers/docs/resources/channel#list-private-archived-threads * https://discord.com/developers/docs/resources/channel#list-joined-private-archived-threads */ -export interface DiscordListArchivedThreads extends DiscordListActiveThreads { +export interface DiscordListArchivedThreads { + /** The archived threads */ + threads: DiscordChannel[] + /** A thread member object for each returned thread the current user */ + members: DiscordThreadMember[] /** Whether there are potentially additional threads that could be returned on a subsequent call */ has_more: boolean } diff --git a/packages/types/src/discord/guild.ts b/packages/types/src/discord/guild.ts index 8dbe9546b..5cadd2168 100644 --- a/packages/types/src/discord/guild.ts +++ b/packages/types/src/discord/guild.ts @@ -1,6 +1,6 @@ /** Types for: https://discord.com/developers/docs/resources/guild */ -import type { ChannelTypes, DiscordChannel, DiscordOverwrite, SortOrderTypes } from './channel.js' +import type { ChannelTypes, DiscordChannel, DiscordOverwrite, DiscordThreadMember, SortOrderTypes } from './channel.js' import type { DiscordEmoji } from './emoji.js' import type { DiscordPresenceUpdate } from './gateway.js' import type { OAuth2Scope } from './oauth2.js' @@ -672,6 +672,14 @@ export interface DiscordModifyGuildChannelPositions { parent_id?: string | null } +/** https://discord.com/developers/docs/resources/guild#list-active-guild-threads-response-body */ +export interface DiscordListActiveThreads { + /** The active threads */ + threads: DiscordChannel[] + /** A thread member object for each returned thread the current user has joined */ + members: DiscordThreadMember[] +} + /** https://discord.com/developers/docs/resources/guild#bulk-guild-ban-bulk-ban-response */ export interface DiscordBulkBan { /** list of user ids, that were successfully banned */