feat: Voice Channel Effect Send (#10318)

* feat: Voice Channel Send Effects (#9288)

* feat: add soundboard fields

* chore: address TODO

* docs: volume is a closed interval

* types: use `GatewayVoiceChannelEffectSendDispatchData`

* refactor: prefer getting from cache

* fix: correctly access cache

Co-authored-by: Danial Raza <danialrazafb@gmail.com>

---------

Co-authored-by: Danial Raza <danialrazafb@gmail.com>

packages/discord.js/src/client/websocket/handlers/VOICE_CHANNEL_EFFECT_SEND.js

@@ -0,0 +1,16 @@
+'use strict';
+
+const VoiceChannelEffect = require('../../../structures/VoiceChannelEffect');
+const Events = require('../../../util/Events');
+
+module.exports = (client, { d: data }) => {
+  const guild = client.guilds.cache.get(data.guild_id);
+  if (!guild) return;
+
+  /**
+   * Emmited when someone sends an effect, such as an emoji reaction, in a voice channel the client is connected to.
+   * @event Client#voiceChannelEffectSend
+   * @param {VoiceChannelEffect} voiceChannelEffect The sent voice channel effect
+   */
+  client.emit(Events.VoiceChannelEffectSend, new VoiceChannelEffect(data, guild));
+};

packages/discord.js/src/client/websocket/handlers/index.js

@@ -61,6 +61,7 @@ const handlers = Object.fromEntries([
   ['THREAD_UPDATE', require('./THREAD_UPDATE')],
   ['TYPING_START', require('./TYPING_START')],
   ['USER_UPDATE', require('./USER_UPDATE')],
+  ['VOICE_CHANNEL_EFFECT_SEND', require('./VOICE_CHANNEL_EFFECT_SEND')],
   ['VOICE_SERVER_UPDATE', require('./VOICE_SERVER_UPDATE')],
   ['VOICE_STATE_UPDATE', require('./VOICE_STATE_UPDATE')],
   ['WEBHOOKS_UPDATE', require('./WEBHOOKS_UPDATE')],

packages/discord.js/src/index.js

@@ -215,6 +215,7 @@ exports.ThreadOnlyChannel = require('./structures/ThreadOnlyChannel');
 exports.Typing = require('./structures/Typing');
 exports.User = require('./structures/User');
 exports.UserContextMenuCommandInteraction = require('./structures/UserContextMenuCommandInteraction');
+exports.VoiceChannelEffect = require('./structures/VoiceChannelEffect');
 exports.VoiceChannel = require('./structures/VoiceChannel');
 exports.VoiceRegion = require('./structures/VoiceRegion');
 exports.VoiceState = require('./structures/VoiceState');

packages/discord.js/src/structures/VoiceChannelEffect.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const { Emoji } = require('./Emoji');
+
+/**
+ * Represents an effect used in a {@link VoiceChannel}.
+ */
+class VoiceChannelEffect {
+  constructor(data, guild) {
+    /**
+     * The guild where the effect was sent from.
+     * @type {Guild}
+     */
+    this.guild = guild;
+
+    /**
+     * The id of the channel the effect was sent in.
+     * @type {Snowflake}
+     */
+    this.channelId = data.channel_id;
+
+    /**
+     * The id of the user that sent the effect.
+     * @type {Snowflake}
+     */
+    this.userId = data.user_id;
+
+    /**
+     * The emoji of the effect.
+     * @type {?Emoji}
+     */
+    this.emoji = data.emoji ? new Emoji(guild.client, data.emoji) : null;
+
+    /**
+     * The animation type of the effect.
+     * @type {?VoiceChannelEffectSendAnimationType}
+     */
+    this.animationType = data.animation_type ?? null;
+
+    /**
+     * The animation id of the effect.
+     * @type {?number}
+     */
+    this.animationId = data.animation_id ?? null;
+
+    /**
+     * The id of the soundboard sound for soundboard effects.
+     * @type {?(Snowflake|number)}
+     */
+    this.soundId = data.sound_id ?? null;
+
+    /**
+     * The volume of the soundboard sound [0-1] for soundboard effects.
+     * @type {?number}
+     */
+    this.soundVolume = data.sound_volume ?? null;
+  }
+
+  /**
+   * The channel the effect was sent in.
+   * @type {?VoiceChannel}
+   * @readonly
+   */
+  get channel() {
+    return this.guild.channels.cache.get(this.channelId) ?? null;
+  }
+}
+
+module.exports = VoiceChannelEffect;

packages/discord.js/src/util/APITypes.js

@@ -585,6 +585,11 @@
  * @see {@link https://discord-api-types.dev/api/discord-api-types-v10/enum/VideoQualityMode}
  */
 
+/**
+ * @external VoiceChannelEffectSendAnimationType
+ * @see {@link https://discord-api-types.dev/api/discord-api-types-v10/enum/VoiceChannelEffectSendAnimationType}
+ */
+
 /**
  * @external WebhookType
  * @see {@link https://discord-api-types.dev/api/discord-api-types-v10/enum/WebhookType}

packages/discord.js/src/util/Events.js

@@ -77,6 +77,7 @@
  * @property {string} ThreadUpdate threadUpdate
  * @property {string} TypingStart typingStart
  * @property {string} UserUpdate userUpdate
+ * @property {string} VoiceChannelEffectSend voiceChannelEffectSend
  * @property {string} VoiceServerUpdate voiceServerUpdate
  * @property {string} VoiceStateUpdate voiceStateUpdate
  * @property {string} Warn warn
@@ -165,6 +166,7 @@ module.exports = {
   ThreadUpdate: 'threadUpdate',
   TypingStart: 'typingStart',
   UserUpdate: 'userUpdate',
+  VoiceChannelEffectSend: 'voiceChannelEffectSend',
   VoiceServerUpdate: 'voiceServerUpdate',
   VoiceStateUpdate: 'voiceStateUpdate',
   Warn: 'warn',

packages/discord.js/typings/index.d.ts

@@ -189,6 +189,8 @@ import {
   GuildScheduledEventRecurrenceRuleWeekday,
   GuildScheduledEventRecurrenceRuleMonth,
   GuildScheduledEventRecurrenceRuleFrequency,
+  VoiceChannelEffectSendAnimationType,
+  GatewayVoiceChannelEffectSendDispatchData,
 } from 'discord-api-types/v10';
 import { ChildProcess } from 'node:child_process';
 import { EventEmitter } from 'node:events';
@@ -3662,6 +3664,19 @@ export class VoiceChannel extends BaseGuildVoiceChannel {
   public type: ChannelType.GuildVoice;
 }
 
+export class VoiceChannelEffect {
+  private constructor(data: GatewayVoiceChannelEffectSendDispatchData, guild: Guild);
+  public guild: Guild;
+  public channelId: Snowflake;
+  public userId: Snowflake;
+  public emoji: Emoji | null;
+  public animationType: VoiceChannelEffectSendAnimationType | null;
+  public animationId: number | null;
+  public soundId: Snowflake | number | null;
+  public soundVolume: number | null;
+  public get channel(): VoiceChannel | null;
+}
+
 export class VoiceRegion {
   private constructor(data: RawVoiceRegionData);
   public custom: boolean;
@@ -5419,6 +5434,7 @@ export interface ClientEvents {
   threadUpdate: [oldThread: AnyThreadChannel, newThread: AnyThreadChannel];
   typingStart: [typing: Typing];
   userUpdate: [oldUser: User | PartialUser, newUser: User];
+  voiceChannelEffectSend: [voiceChannelEffect: VoiceChannelEffect];
   voiceStateUpdate: [oldState: VoiceState, newState: VoiceState];
   /** @deprecated Use {@link ClientEvents.webhooksUpdate} instead. */
   webhookUpdate: ClientEvents['webhooksUpdate'];
@@ -5630,6 +5646,7 @@ export enum Events {
   ThreadMembersUpdate = 'threadMembersUpdate',
   UserUpdate = 'userUpdate',
   PresenceUpdate = 'presenceUpdate',
+  VoiceChannelEffectSend = 'voiceChannelEffectSend',
   VoiceServerUpdate = 'voiceServerUpdate',
   VoiceStateUpdate = 'voiceStateUpdate',
   TypingStart = 'typingStart',