feat: polls (#10185)

Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>

.github/ISSUE_TEMPLATE/01-package_bug_report.yml

@@ -123,6 +123,8 @@ body:
         - GuildScheduledEvents
         - AutoModerationConfiguration
         - AutoModerationExecution
+        - GuildMessagePolls
+        - DirectMessagePolls
       multiple: true
     validations:
       required: true

packages/core/src/api/index.ts

@@ -7,6 +7,7 @@ import { InteractionsAPI } from './interactions.js';
 import { InvitesAPI } from './invite.js';
 import { MonetizationAPI } from './monetization.js';
 import { OAuth2API } from './oauth2.js';
+import { PollAPI } from './poll.js';
 import { RoleConnectionsAPI } from './roleConnections.js';
 import { StageInstancesAPI } from './stageInstances.js';
 import { StickersAPI } from './sticker.js';
@@ -23,6 +24,7 @@ export * from './interactions.js';
 export * from './invite.js';
 export * from './monetization.js';
 export * from './oauth2.js';
+export * from './poll.js';
 export * from './roleConnections.js';
 export * from './stageInstances.js';
 export * from './sticker.js';
@@ -48,6 +50,8 @@ export class API {
 
 	public readonly oauth2: OAuth2API;
 
+	public readonly poll: PollAPI;
+
 	public readonly roleConnections: RoleConnectionsAPI;
 
 	public readonly stageInstances: StageInstancesAPI;
@@ -69,8 +73,9 @@ export class API {
 		this.guilds = new GuildsAPI(rest);
 		this.invites = new InvitesAPI(rest);
 		this.monetization = new MonetizationAPI(rest);
-		this.roleConnections = new RoleConnectionsAPI(rest);
 		this.oauth2 = new OAuth2API(rest);
+		this.poll = new PollAPI(rest);
+		this.roleConnections = new RoleConnectionsAPI(rest);
 		this.stageInstances = new StageInstancesAPI(rest);
 		this.stickers = new StickersAPI(rest);
 		this.threads = new ThreadsAPI(rest);

packages/core/src/api/poll.ts

@@ -0,0 +1,51 @@
+/* eslint-disable jsdoc/check-param-names */
+
+import { makeURLSearchParams, type RequestData, type REST } from '@discordjs/rest';
+import {
+	Routes,
+	type RESTGetAPIPollAnswerVotersQuery,
+	type RESTGetAPIPollAnswerVotersResult,
+	type RESTPostAPIPollExpireResult,
+	type Snowflake,
+} from 'discord-api-types/v10';
+
+export class PollAPI {
+	public constructor(private readonly rest: REST) {}
+
+	/**
+	 * Gets the list of users that voted for a specific answer in a poll
+	 *
+	 * @see {@link https://discord.com/developers/docs/resources/poll#get-answer-voters}
+	 * @param channelId - The id of the channel containing the message
+	 * @param messageId - The id of the message containing the poll
+	 * @param answerId - The id of the answer to get voters for
+	 * @param query - The query for getting the list of voters
+	 * @param options - The options for getting the list of voters
+	 */
+	public async getAnswerVoters(
+		channelId: Snowflake,
+		messageId: Snowflake,
+		answerId: number,
+		query: RESTGetAPIPollAnswerVotersQuery,
+		{ signal }: Pick<RequestData, 'signal'> = {},
+	) {
+		return this.rest.get(Routes.pollAnswerVoters(channelId, messageId, answerId), {
+			signal,
+			query: makeURLSearchParams(query),
+		}) as Promise<RESTGetAPIPollAnswerVotersResult>;
+	}
+
+	/**
+	 * Immediately expires (i.e. ends) a poll
+	 *
+	 * @see {@link https://discord.com/developers/docs/resources/poll#expire-poll}
+	 * @param channelId - The id of the channel containing the message
+	 * @param messageId - The id of the message containing the poll
+	 * @param options - The options for expiring the poll
+	 */
+	public async expirePoll(channelId: Snowflake, messageId: Snowflake, { signal }: Pick<RequestData, 'signal'> = {}) {
+		return this.rest.post(Routes.expirePoll(channelId, messageId), {
+			signal,
+		}) as Promise<RESTPostAPIPollExpireResult>;
+	}
+}

packages/core/src/client.ts

@@ -1,4 +1,4 @@
-import { setTimeout, clearTimeout } from 'node:timers';
+import { clearTimeout, setTimeout } from 'node:timers';
 import type { REST } from '@discordjs/rest';
 import { calculateShardId } from '@discordjs/util';
 import { WebSocketShardEvents } from '@discordjs/ws';
@@ -49,6 +49,7 @@ import {
 	type GatewayMessageCreateDispatchData,
 	type GatewayMessageDeleteBulkDispatchData,
 	type GatewayMessageDeleteDispatchData,
+	type GatewayMessagePollVoteDispatchData,
 	type GatewayMessageReactionAddDispatchData,
 	type GatewayMessageReactionRemoveAllDispatchData,
 	type GatewayMessageReactionRemoveDispatchData,
@@ -143,6 +144,8 @@ export interface MappedEvents {
 	[GatewayDispatchEvents.MessageCreate]: [WithIntrinsicProps<GatewayMessageCreateDispatchData>];
 	[GatewayDispatchEvents.MessageDelete]: [WithIntrinsicProps<GatewayMessageDeleteDispatchData>];
 	[GatewayDispatchEvents.MessageDeleteBulk]: [WithIntrinsicProps<GatewayMessageDeleteBulkDispatchData>];
+	[GatewayDispatchEvents.MessagePollVoteAdd]: [WithIntrinsicProps<GatewayMessagePollVoteDispatchData>];
+	[GatewayDispatchEvents.MessagePollVoteRemove]: [WithIntrinsicProps<GatewayMessagePollVoteDispatchData>];
 	[GatewayDispatchEvents.MessageReactionAdd]: [WithIntrinsicProps<GatewayMessageReactionAddDispatchData>];
 	[GatewayDispatchEvents.MessageReactionRemove]: [WithIntrinsicProps<GatewayMessageReactionRemoveDispatchData>];
 	[GatewayDispatchEvents.MessageReactionRemoveAll]: [WithIntrinsicProps<GatewayMessageReactionRemoveAllDispatchData>];
@@ -198,9 +201,8 @@ export class Client extends AsyncEventEmitter<MappedEvents> {
 
 		this.gateway.on(WebSocketShardEvents.Dispatch, ({ data: dispatch, shardId }) => {
 			this.emit(
-				// TODO: This comment will have to be moved down once the new Poll events are added to the `ManagerShardEventsMap`
-				// @ts-expect-error event props can't be resolved properly, but they are correct
 				dispatch.t,
+				// @ts-expect-error event props can't be resolved properly, but they are correct
 				this.wrapIntrinsicProps(dispatch.d, shardId),
 			);
 		});

packages/discord.js/src/client/actions/ActionsManager.js

@@ -54,6 +54,8 @@ class ActionsManager {
     this.register(require('./MessageCreate'));
     this.register(require('./MessageDelete'));
     this.register(require('./MessageDeleteBulk'));
+    this.register(require('./MessagePollVoteAdd'));
+    this.register(require('./MessagePollVoteRemove'));
     this.register(require('./MessageReactionAdd'));
     this.register(require('./MessageReactionRemove'));
     this.register(require('./MessageReactionRemoveAll'));

packages/discord.js/src/client/actions/MessagePollVoteAdd.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const Action = require('./Action');
+const Events = require('../../util/Events');
+
+class MessagePollVoteAddAction extends Action {
+  handle(data) {
+    const channel = this.getChannel(data);
+    if (!channel?.isTextBased()) return false;
+
+    const message = this.getMessage(data, channel);
+    if (!message) return false;
+
+    const { poll } = message;
+
+    const answer = poll.answers.get(data.answer_id);
+    if (!answer) return false;
+
+    answer.voteCount++;
+
+    /**
+     * Emitted whenever a user votes in a poll.
+     * @event Client#messagePollVoteAdd
+     * @param {PollAnswer} pollAnswer The answer that was voted on
+     * @param {Snowflake} userId The id of the user that voted
+     */
+    this.client.emit(Events.MessagePollVoteAdd, answer, data.user_id);
+
+    return { poll };
+  }
+}
+
+module.exports = MessagePollVoteAddAction;

packages/discord.js/src/client/actions/MessagePollVoteRemove.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const Action = require('./Action');
+const Events = require('../../util/Events');
+
+class MessagePollVoteRemoveAction extends Action {
+  handle(data) {
+    const channel = this.getChannel(data);
+    if (!channel?.isTextBased()) return false;
+
+    const message = this.getMessage(data, channel);
+    if (!message) return false;
+
+    const { poll } = message;
+
+    const answer = poll.answers.get(data.answer_id);
+    if (!answer) return false;
+
+    answer.voteCount--;
+
+    /**
+     * Emitted whenever a user removes their vote in a poll.
+     * @event Client#messagePollVoteRemove
+     * @param {PollAnswer} pollAnswer The answer where the vote was removed
+     * @param {Snowflake} userId The id of the user that removed their vote
+     */
+    this.client.emit(Events.MessagePollVoteRemove, answer, data.user_id);
+
+    return { poll };
+  }
+}
+
+module.exports = MessagePollVoteRemoveAction;

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

@@ -0,0 +1,5 @@
+'use strict';
+
+module.exports = (client, packet) => {
+  client.actions.MessagePollVoteAdd.handle(packet.d);
+};

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

@@ -0,0 +1,5 @@
+'use strict';
+
+module.exports = (client, packet) => {
+  client.actions.MessagePollVoteRemove.handle(packet.d);
+};

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

@@ -40,6 +40,8 @@ const handlers = Object.fromEntries([
   ['MESSAGE_CREATE', require('./MESSAGE_CREATE')],
   ['MESSAGE_DELETE', require('./MESSAGE_DELETE')],
   ['MESSAGE_DELETE_BULK', require('./MESSAGE_DELETE_BULK')],
+  ['MESSAGE_POLL_VOTE_ADD', require('./MESSAGE_POLL_VOTE_ADD')],
+  ['MESSAGE_POLL_VOTE_REMOVE', require('./MESSAGE_POLL_VOTE_REMOVE')],
   ['MESSAGE_REACTION_ADD', require('./MESSAGE_REACTION_ADD')],
   ['MESSAGE_REACTION_REMOVE', require('./MESSAGE_REACTION_REMOVE')],
   ['MESSAGE_REACTION_REMOVE_ALL', require('./MESSAGE_REACTION_REMOVE_ALL')],

packages/discord.js/src/errors/ErrorCodes.js

@@ -178,6 +178,8 @@
  * @property {'EntitlementCreateInvalidOwner'} EntitlementCreateInvalidOwner
 
  * @property {'BulkBanUsersOptionEmpty'} BulkBanUsersOptionEmpty
+
+ * @property {'PollAlreadyExpired'} PollAlreadyExpired
  */
 
 const keys = [
@@ -333,6 +335,8 @@ const keys = [
   'EntitlementCreateInvalidOwner',
 
   'BulkBanUsersOptionEmpty',
+
+  'PollAlreadyExpired',
 ];
 
 // JSDoc for IntelliSense purposes

packages/discord.js/src/errors/Messages.js

@@ -171,6 +171,8 @@ const Messages = {
     'You must provide either a guild or a user to create an entitlement, but not both',
 
   [DjsErrorCodes.BulkBanUsersOptionEmpty]: 'Option "users" array or collection is empty',
+
+  [DjsErrorCodes.PollAlreadyExpired]: 'This poll has already expired.',
 };
 
 module.exports = Messages;

packages/discord.js/src/index.js

@@ -168,6 +168,8 @@ exports.NewsChannel = require('./structures/NewsChannel');
 exports.OAuth2Guild = require('./structures/OAuth2Guild');
 exports.PartialGroupDMChannel = require('./structures/PartialGroupDMChannel');
 exports.PermissionOverwrites = require('./structures/PermissionOverwrites');
+exports.Poll = require('./structures/Poll').Poll;
+exports.PollAnswer = require('./structures/PollAnswer').PollAnswer;
 exports.Presence = require('./structures/Presence').Presence;
 exports.ReactionCollector = require('./structures/ReactionCollector');
 exports.ReactionEmoji = require('./structures/ReactionEmoji');

packages/discord.js/src/structures/Message.js

@@ -17,6 +17,7 @@ const Embed = require('./Embed');
 const InteractionCollector = require('./InteractionCollector');
 const Mentions = require('./MessageMentions');
 const MessagePayload = require('./MessagePayload');
+const { Poll } = require('./Poll.js');
 const ReactionCollector = require('./ReactionCollector');
 const { Sticker } = require('./Sticker');
 const { DiscordjsError, ErrorCodes } = require('../errors');
@@ -406,6 +407,16 @@ class Message extends Base {
     } else {
       this.interaction ??= null;
     }
+
+    if (data.poll) {
+      /**
+       * The poll that was sent with the message
+       * @type {?Poll}
+       */
+      this.poll = new Poll(this.client, data.poll, this);
+    } else {
+      this.poll ??= null;
+    }
   }
 
   /**

packages/discord.js/src/structures/MessagePayload.js

@@ -7,7 +7,7 @@ const ActionRowBuilder = require('./ActionRowBuilder');
 const { DiscordjsError, DiscordjsRangeError, ErrorCodes } = require('../errors');
 const { resolveFile } = require('../util/DataResolver');
 const MessageFlagsBitField = require('../util/MessageFlagsBitField');
-const { basename, verifyString } = require('../util/Util');
+const { basename, verifyString, resolvePartialEmoji } = require('../util/Util');
 
 const getBaseInteraction = lazy(() => require('./BaseInteraction'));
 
@@ -202,6 +202,21 @@ class MessagePayload {
       this.options.attachments = attachments;
     }
 
+    let poll;
+    if (this.options.poll) {
+      poll = {
+        question: {
+          text: this.options.poll.question.text,
+        },
+        answers: this.options.poll.answers.map(answer => ({
+          poll_media: { text: answer.text, emoji: resolvePartialEmoji(answer.emoji) },
+        })),
+        duration: this.options.poll.duration,
+        allow_multiselect: this.options.poll.allowMultiselect,
+        layout_type: this.options.poll.layoutType,
+      };
+    }
+
     this.body = {
       content,
       tts,
@@ -220,6 +235,7 @@ class MessagePayload {
       sticker_ids: this.options.stickers?.map(sticker => sticker.id ?? sticker),
       thread_name: threadName,
       applied_tags: appliedTags,
+      poll,
     };
     return this;
   }