From 7a0cea84b335eed05c613af9a0cadd2f3432cbce Mon Sep 17 00:00:00 2001 From: Fleny Date: Wed, 13 Aug 2025 11:14:37 +0200 Subject: [PATCH] Apply code review suggestions --- packages/types/src/discordeno/application.ts | 7 ++- .../types/src/discordeno/autoModeration.ts | 45 +++++++++++--- packages/types/src/discordeno/emoji.ts | 26 +++++++- packages/types/src/discordeno/entitlement.ts | 2 +- packages/types/src/discordeno/gateway.ts | 23 +++++-- .../src/discordeno/guildScheduledEvent.ts | 61 +++++++++++++++++-- .../types/src/discordeno/guildTemplate.ts | 30 +++++++-- packages/types/src/discordeno/invite.ts | 2 - packages/types/src/discordeno/lobby.ts | 18 +++++- packages/types/src/discordeno/permissions.ts | 7 ++- packages/types/src/discordeno/poll.ts | 8 ++- packages/types/src/discordeno/soundboard.ts | 24 ++++++-- packages/types/src/discordeno/sticker.ts | 11 +++- packages/types/src/discordeno/user.ts | 2 +- packages/types/src/discordeno/voice.ts | 2 +- 15 files changed, 220 insertions(+), 48 deletions(-) diff --git a/packages/types/src/discordeno/application.ts b/packages/types/src/discordeno/application.ts index 4ae85d993..ada5e1203 100644 --- a/packages/types/src/discordeno/application.ts +++ b/packages/types/src/discordeno/application.ts @@ -8,7 +8,6 @@ import type { } from '../discord/application.js' import type { DiscordWebhookEventType } from '../discord/webhookEvents.js' -// TODO: Do we want to move the "All parameters to this endpoint are optional" of this to the rest manager itself? /** https://discord.com/developers/docs/resources/application#edit-current-application-json-params */ export interface EditApplication { /** Default custom authorization URL for the app, if enabled */ @@ -25,7 +24,8 @@ export interface EditApplication { * App's public flags * * @remarks - * Only limited intent flags (`GATEWAY_PRESENCE_LIMITED`, `GATEWAY_GUILD_MEMBERS_LIMITED`, and `GATEWAY_MESSAGE_CONTENT_LIMITED`) can be updated via the API. + * Only limited intent flags ({@link ApplicationFlags.GatewayPresenceLimited | GatewayPresenceLimited}, {@link ApplicationFlags.GatewayGuildMembersLimited | GatewayGuildMembersLimited}, + * and {@link ApplicationFlags.GatewayMessageContentLimited | GatewayMessageContentLimited}) can be updated via the API. */ flags?: ApplicationFlags /** Icon for the app */ @@ -36,7 +36,8 @@ export interface EditApplication { * Interactions endpoint URL for the app * * @remarks - * To update an Interactions endpoint URL via the API, the URL must be valid + * To update an Interactions endpoint URL via the API, the URL must be valid according to the + * [Receiving an Interaction](https://discord.com/developers/docs/interactions/receiving-and-responding#receiving-an-interaction) documentation. */ interactionEndpointUrl?: string /** diff --git a/packages/types/src/discordeno/autoModeration.ts b/packages/types/src/discordeno/autoModeration.ts index a249ece7c..6994710cb 100644 --- a/packages/types/src/discordeno/autoModeration.ts +++ b/packages/types/src/discordeno/autoModeration.ts @@ -13,7 +13,13 @@ import type { BigString, Camelize } from '../shared.js' export interface DiscordenoAutoModerationAction { /** The type of action to take when a rule is triggered */ type: AutoModerationActionType - /** additional metadata needed during execution for this specific action type */ + /** + * Additional metadata needed during execution for this specific action type + * + * @remarks + * Can be omitted based on type. See the Associated Action Types column in [action metadata](https://discord.com/developers/docs/resources/auto-moderation#auto-moderation-action-object-action-metadata) + * to understand which type values require metadata to be set. + */ metadata?: DiscordenoAutoModerationActionMetadata } @@ -57,29 +63,48 @@ export interface CreateAutoModerationRuleOptions { eventType: AutoModerationEventTypes /** The type of trigger to use for the rule. */ triggerType: AutoModerationTriggerTypes - /** The metadata to use for the trigger. */ + /** + * The metadata to use for the trigger. + * + * @remarks + * Can be omitted based on triggerType. See the Associated Trigger Types column in [trigger metadata](https://discord.com/developers/docs/resources/auto-moderation#auto-moderation-rule-object-trigger-metadata) + * to understand which triggerType values require triggerMetadata to be set. + */ triggerMetadata: Camelize /** The actions that will trigger for this rule */ actions: DiscordenoAutoModerationAction[] - /** Whether the rule should be enabled, true by default. */ + /** + * Whether the rule should be enabled. + * + * @default false + */ enabled?: boolean - /** The role ids that should not be effected by the rule */ + /** + * The role ids that should not be effected by the rule. + * + * @remarks + * Maximum of 20. + */ exemptRoles?: BigString[] - /** The channel ids that should not be effected by the rule. */ + /** + * The channel ids that should not be effected by the rule. + * + * @remarks + * Maximum of 50. + */ exemptChannels?: BigString[] } -// TODO: Discord documents this as "All parameters for this endpoint are optional.", however we do have some partials and it is used with Partial in the rest manager /** https://discord.com/developers/docs/resources/auto-moderation#modify-auto-moderation-rule-json-params */ export interface EditAutoModerationRuleOptions { /** The name of the rule. */ - name: string + name?: string /** The type of event to trigger the rule on. */ - eventType: AutoModerationEventTypes + eventType?: AutoModerationEventTypes /** The metadata to use for the trigger. */ - triggerMetadata: Camelize + triggerMetadata?: Camelize /** The actions that will trigger for this rule */ - actions: DiscordenoAutoModerationAction[] + actions?: DiscordenoAutoModerationAction[] /** Whether the rule should be enabled. */ enabled?: boolean /** The role ids that should not be effected by the rule */ diff --git a/packages/types/src/discordeno/emoji.ts b/packages/types/src/discordeno/emoji.ts index 4b4cbba0f..ca0a5bb1a 100644 --- a/packages/types/src/discordeno/emoji.ts +++ b/packages/types/src/discordeno/emoji.ts @@ -6,10 +6,20 @@ import type { BigString } from '../shared.js' export interface CreateGuildEmoji { /** Name of the emoji */ name: string - /** The 128x128 emoji image. Emojis and animated emojis have a maximum file size of 256kb. Attempting to upload an emoji larger than this limit will fail and return 400 Bad Request and an error message, but not a JSON status code. If a URL is provided to the image parameter, Discordeno will automatically convert it to a base64 string internally. */ + /** + * The 128x128 emoji image. + * + * @remarks + * Image data is a [Data URI scheme](https://en.wikipedia.org/wiki/Data_URI_scheme) that supports JPG, GIF, and PNG formats. + * + * An example Data URI format is: `data:image/jpeg;base64,BASE64_ENCODED_JPEG_IMAGE_DATA`. + * Ensure you use the proper content type (image/jpeg, image/png, image/gif) that matches the image data being provided. + * + * Emojis and animated emojis have a maximum file size of 256kb. Attempting to upload an emoji larger than this limit will fail and return 400 Bad Request and an error message, but not a JSON status code. + */ image: string /** Roles allowed to use this emoji */ - roles?: BigString[] + roles: BigString[] } /** https://discord.com/developers/docs/resources/emoji#modify-guild-emoji */ @@ -24,7 +34,17 @@ export interface ModifyGuildEmoji { export interface CreateApplicationEmoji { /** Name of the emoji */ name: string - /** The 128x128 emoji image. Emojis and animated emojis have a maximum file size of 256kb. Attempting to upload an emoji larger than this limit will fail and return 400 Bad Request and an error message, but not a JSON status code. If a URL is provided to the image parameter, Discordeno will automatically convert it to a base64 string internally. */ + /** + * The 128x128 emoji image. + * + * @remarks + * Image data is a [Data URI scheme](https://en.wikipedia.org/wiki/Data_URI_scheme) that supports JPG, GIF, and PNG formats. + * + * An example Data URI format is: `data:image/jpeg;base64,BASE64_ENCODED_JPEG_IMAGE_DATA`. + * Ensure you use the proper content type (image/jpeg, image/png, image/gif) that matches the image data being provided. + * + * Emojis and animated emojis have a maximum file size of 256kb. Attempting to upload an emoji larger than this limit will fail and return 400 Bad Request and an error message, but not a JSON status code. + */ image: string } diff --git a/packages/types/src/discordeno/entitlement.ts b/packages/types/src/discordeno/entitlement.ts index 87b57e7cc..15e0ca735 100644 --- a/packages/types/src/discordeno/entitlement.ts +++ b/packages/types/src/discordeno/entitlement.ts @@ -2,7 +2,7 @@ import type { BigString } from '../shared.js' -/** https://discord.com/developers/docs/monetization/entitlements#list-entitlements-query-params */ +/** https://discord.com/developers/docs/resources/entitlement#list-entitlements-query-string-params */ export interface GetEntitlements { /** User ID to look up entitlements for */ userId?: BigString diff --git a/packages/types/src/discordeno/gateway.ts b/packages/types/src/discordeno/gateway.ts index 4d5d323e0..344f453a8 100644 --- a/packages/types/src/discordeno/gateway.ts +++ b/packages/types/src/discordeno/gateway.ts @@ -10,13 +10,28 @@ import type { BigString } from '../shared.js' export interface RequestGuildMembers { /** id of the guild to get members for */ guildId: BigString - /** String that username starts with, or an empty string to return all members */ + /** + * String that username starts with, or an empty string to return all members + * + * @remarks + * Required when userIds is not specified + */ query?: string - /** Maximum number of members to send matching the query; a limit of 0 can be used with an empty string query to return all members */ - limit: number + /** + * Maximum number of members to send matching the query; a limit of 0 can be used with an empty string query to return all members + * + * @remarks + * Required when query is specified + */ + limit?: number /** Used to specify if we want the presences of the matched members */ presences?: boolean - /** Used to specify which users you wish to fetch */ + /** + * Used to specify which users you wish to fetch + * + * @remarks + * Required when query is not specified + */ userIds?: BigString[] /** Nonce to identify the Guild Members Chunk response */ nonce?: string diff --git a/packages/types/src/discordeno/guildScheduledEvent.ts b/packages/types/src/discordeno/guildScheduledEvent.ts index dee822e85..821ac18d9 100644 --- a/packages/types/src/discordeno/guildScheduledEvent.ts +++ b/packages/types/src/discordeno/guildScheduledEvent.ts @@ -17,8 +17,19 @@ export interface GetScheduledEvents { /** https://discord.com/developers/docs/resources/guild-scheduled-event#create-guild-scheduled-event-json-params */ export interface CreateScheduledEvent { - /** the channel id of the scheduled event. */ + /** + * the channel id of the scheduled event. + * + * @remarks + * Optional for events with entityType: {@link ScheduledEventEntityType.External | ScheduledEventEntityType.External} + */ channelId?: BigString + /** + * the entity metadata of the scheduled event + * + * @remarks + * Required for events with entityType: {@link ScheduledEventEntityType.External | ScheduledEventEntityType.External} + */ entityMetadata?: DiscordScheduledEventEntityMetadata /** the name of the scheduled event */ name: string @@ -26,7 +37,12 @@ export interface CreateScheduledEvent { privacyLevel?: ScheduledEventPrivacyLevel /** the time the scheduled event will start */ scheduledStartTime: string - /** the time the scheduled event will end if it does end. Required for events with `entityType: ScheduledEventEntityType.External` */ + /** + * the time the scheduled event will end if it does end. + * + * @remarks + * Required for events with entityType: {@link ScheduledEventEntityType.External | ScheduledEventEntityType.External} + */ scheduledEndTime?: string /** the description of the scheduled event */ description: string @@ -40,15 +56,32 @@ export interface CreateScheduledEvent { /** https://discord.com/developers/docs/resources/guild-scheduled-event#modify-guild-scheduled-event-json-params */ export interface EditScheduledEvent { - /** the channel id of the scheduled event. null if switching to external event. */ + /** + * the channel id of the scheduled event. + * + * @remarks + * if updating entityType to {@link ScheduledEventEntityType.External | ScheduledEventEntityType.External}, channelId is required and must be set to null + */ channelId: BigString | null + /** + * the entity metadata of the scheduled event + * + * @remarks + * if updating entityType to {@link ScheduledEventEntityType.External | ScheduledEventEntityType.External}, entityData with a location field must be provided + */ + entityMetadata: DiscordScheduledEventEntityMetadata /** the name of the scheduled event */ name: string /** the privacy level of the scheduled event */ privacyLevel: ScheduledEventPrivacyLevel /** the time the scheduled event will start */ scheduledStartTime: string - /** the time the scheduled event will end if it does end. */ + /** + * the time the scheduled event will end if it does end. + * + * @remarks + * if updating entityType to {@link ScheduledEventEntityType.External | ScheduledEventEntityType.External}, scheduledEndTime must be provided + */ scheduledEndTime?: string /** the description of the scheduled event */ description?: string @@ -67,8 +100,24 @@ export interface GetScheduledEventUsers { limit?: number /** whether to also have member objects provided, defaults to false */ withMember?: boolean - /** consider only users before given user id */ + /** + * consider only users before given user id + * + * @remarks + * Provide a user id to before for pagination. Users will always be returned in ascending order by userId. + * If both before and after are provided, only before is respected. + * + * Fetching users in-between before and after is not supported. + */ before?: BigString - /** consider only users after given user id. If both before and after are provided, only before is respected. Fetching users in-between before and after is not supported. */ + /** + * consider only users after given user id + * + * @remarks + * Provide a user id to after for pagination. Users will always be returned in ascending order by userId. + * If both before and after are provided, only before is respected. + * + * Fetching users in-between before and after is not supported. + */ after?: BigString } diff --git a/packages/types/src/discordeno/guildTemplate.ts b/packages/types/src/discordeno/guildTemplate.ts index c9db4b120..f3db0f1ba 100644 --- a/packages/types/src/discordeno/guildTemplate.ts +++ b/packages/types/src/discordeno/guildTemplate.ts @@ -2,16 +2,36 @@ /** https://discord.com/developers/docs/resources/guild-template#create-guild-template-json-params */ export interface CreateTemplate { - /** Name which the template should have */ + /** + * Name of the template + * + * @remarks + * 1-100 characters + */ name: string - /** Description of the template */ - description?: string + /** + * Description for the template + * + * @remarks + * 0-120 characters + */ + description?: string | null } /** https://discord.com/developers/docs/resources/guild-template#modify-guild-template-json-params */ export interface ModifyGuildTemplate { - /** Name of the template (1-100 characters) */ + /** + * Name of the template + * + * @remarks + * 1-100 characters + */ name?: string - /** Description of the template (0-120 characters) */ + /** + * Description for the template + * + * @remark + * 0-120 characters + */ description?: string | null } diff --git a/packages/types/src/discordeno/invite.ts b/packages/types/src/discordeno/invite.ts index 89977bcf6..60423e1df 100644 --- a/packages/types/src/discordeno/invite.ts +++ b/packages/types/src/discordeno/invite.ts @@ -6,8 +6,6 @@ import type { BigString } from '../shared.js' export interface GetInvite { /** Whether the invite should contain approximate member counts */ withCounts?: boolean - /** Whether the invite should contain the expiration date */ - withExpiration?: boolean /** the guild scheduled event to include with the invite */ scheduledEventId?: BigString } diff --git a/packages/types/src/discordeno/lobby.ts b/packages/types/src/discordeno/lobby.ts index 82e6de242..8104f3785 100644 --- a/packages/types/src/discordeno/lobby.ts +++ b/packages/types/src/discordeno/lobby.ts @@ -8,7 +8,14 @@ export interface CreateLobby { metadata?: Record | null /** Optional array of up to 25 users to be added to the lobby */ members?: CreateLobbyMember[] - /** Seconds to wait before shutting down a lobby after it becomes idle. Value can be between 5 and 604800 (7 days). */ + /** + * Seconds to wait before shutting down a lobby after it becomes idle. + * + * @remarks + * Value can be between 5 and 604800 (7 days). + * + * @see {@link https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1LobbyHandle.html#a04cebab69ab0e7fb930346a14a87e843 | LobbyHandle} for more details on this behavior. + */ idleTimeoutSeconds?: number } @@ -28,7 +35,14 @@ export interface ModifyLobby { metadata?: Record | null /** Optional array of up to 25 users to replace the lobby members with. If provided, lobby members not in this list will be removed from the lobby. */ members?: CreateLobbyMember[] - /** Seconds to wait before shutting down a lobby after it becomes idle. Value can be between 5 and 604800 (7 days). */ + /** + * Seconds to wait before shutting down a lobby after it becomes idle. + * + * @remarks + * Value can be between 5 and 604800 (7 days). + * + * @see {@link https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1LobbyHandle.html#a04cebab69ab0e7fb930346a14a87e843 | LobbyHandle} for more details on this behavior. + */ idleTimeoutSeconds?: number } diff --git a/packages/types/src/discordeno/permissions.ts b/packages/types/src/discordeno/permissions.ts index 3cffc54e1..5b97cd4cc 100644 --- a/packages/types/src/discordeno/permissions.ts +++ b/packages/types/src/discordeno/permissions.ts @@ -6,6 +6,11 @@ export interface GuildRoleColors { primaryColor: number /** The secondary color for the role, this will make the role a gradient between the other provided colors */ secondaryColor?: number - /** The tertiary color for the role, this will turn the gradient into a holographic style */ + /** + * The tertiary color for the role, this will turn the gradient into a holographic style + * + * @remarks + * When sending tertiaryColor, the API enforces the role color to be a holographic style with values of: primaryColor = 11127295, secondaryColor = 16759788, and tertiaryColor = 16761760 + */ tertiaryColor?: number } diff --git a/packages/types/src/discordeno/poll.ts b/packages/types/src/discordeno/poll.ts index d8a9e2780..5e72a902b 100644 --- a/packages/types/src/discordeno/poll.ts +++ b/packages/types/src/discordeno/poll.ts @@ -6,7 +6,7 @@ import type { BigString, Camelize } from '../shared.js' /** https://discord.com/developers/docs/resources/poll#poll-create-request-object */ export interface CreatePoll { /** The question of the poll. Only `text` is supported. */ - question: Camelize + question: Pick, 'text'> /** Each of the answers available in the poll, up to 10 */ answers: Omit, 'answerId'>[] /** @@ -24,7 +24,11 @@ export interface CreatePoll { * @default false */ allowMultiselect: boolean - /** The layout type of the poll */ + /** + * The layout type of the poll + * + * @default DiscordPollLayoutType.Default + */ layoutType?: DiscordPollLayoutType } diff --git a/packages/types/src/discordeno/soundboard.ts b/packages/types/src/discordeno/soundboard.ts index e6af517a9..040b24b69 100644 --- a/packages/types/src/discordeno/soundboard.ts +++ b/packages/types/src/discordeno/soundboard.ts @@ -26,12 +26,24 @@ export interface CreateGuildSoundboardSound { /** https://canary.discord.com/developers/docs/resources/soundboard#modify-guild-soundboard-sound-json-params */ export interface ModifyGuildSoundboardSound { - /** Name of the soundboard sound (2-32 characters) */ - name: string - /** The volume of the soundboard sound, from 0 to 1, defaults to 1 */ - volume: number | null + /** + * Name of the soundboard sound + * + * @remarks + * 2-32 characters + */ + name?: string + /** + * The volume of the soundboard sound + * + * @remarks + * The value is from 0 to 1 + * + * @default 1 + */ + volume?: number | null /** The id of the custom emoji for the soundboard sound */ - emojiId: BigString | null + emojiId?: BigString | null /** The unicode character of a standard emoji for the soundboard sound */ - emojiName: string | null + emojiName?: string | null } diff --git a/packages/types/src/discordeno/sticker.ts b/packages/types/src/discordeno/sticker.ts index d04dff607..201c2b79b 100644 --- a/packages/types/src/discordeno/sticker.ts +++ b/packages/types/src/discordeno/sticker.ts @@ -10,7 +10,16 @@ export interface CreateGuildStickerOptions { description: string /** Autocomplete/suggestion tags for the sticker (max 200 characters) */ tags: string - /** The sticker file to upload, must be a PNG, APNG, or Lottie JSON file, max 512 KB */ + /** + * The sticker file to upload, must be a PNG, APNG, or Lottie JSON file + * + * @remarks + * max 512 KB. + * + * Lottie stickers can only be uploaded on guilds that have either the VERIFIED and/or the PARTNERED [guild feature](https://discord.com/developers/docs/resources/guild#guild-object-guild-features). + * + * Uploaded stickers are constrained to 5 seconds in length for animated stickers, and 320 x 320 pixels. + */ file: FileContent } diff --git a/packages/types/src/discordeno/user.ts b/packages/types/src/discordeno/user.ts index cd8773e45..9602128ae 100644 --- a/packages/types/src/discordeno/user.ts +++ b/packages/types/src/discordeno/user.ts @@ -19,5 +19,5 @@ export interface GetGroupDmOptions { /** Access tokens of users that have granted your app the `gdm.join` scope */ accessTokens: string[] /** A mapping of user ids to their respective nicknames */ - nicks?: Record + nicks: Record } diff --git a/packages/types/src/discordeno/voice.ts b/packages/types/src/discordeno/voice.ts index 18ee0424f..7d829c3ea 100644 --- a/packages/types/src/discordeno/voice.ts +++ b/packages/types/src/discordeno/voice.ts @@ -5,7 +5,7 @@ import type { BigString } from '../shared.js' /** https://discord.com/developers/docs/resources/voice#modify-current-user-voice-state-json-params */ export interface EditOwnVoiceState { /** The id of the channel the user is currently in */ - channelId: BigString + channelId?: BigString /** Toggles the user's suppress state */ suppress?: boolean /** Sets the user's request to speak */