Apply code review suggestions

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
   /**

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<DiscordAutoModerationRuleTriggerMetadata>
   /** 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<T> 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<DiscordAutoModerationRuleTriggerMetadata>
+  triggerMetadata?: Camelize<DiscordAutoModerationRuleTriggerMetadata>
   /** 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 */

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
 }
 

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

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

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
 }

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
 }

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
 }

packages/types/src/discordeno/lobby.ts

@@ -8,7 +8,14 @@ export interface CreateLobby {
   metadata?: Record<string, string> | 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<string, string> | 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
 }
 

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
 }

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<DiscordPollMedia>
+  question: Pick<Camelize<DiscordPollMedia>, 'text'>
   /** Each of the answers available in the poll, up to 10 */
   answers: Omit<Camelize<DiscordPollAnswer>, '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
 }
 

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
 }

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
 }
 

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<string, string>
+  nicks: Record<string, string>
 }

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 */