feat: polls

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,49 @@
+/* eslint-disable jsdoc/check-param-names */
+
+import { makeURLSearchParams, type RequestData, type REST } from '@discordjs/rest';
+import type { Snowflake } from 'discord-api-types/v10';
+
+type RESTGetAPIPollAnswerVotersQuery = any;
+type RESTGetAPIPollAnswerVotersResult = any;
+type RESTPostAPIPollExpireResult = any;
+
+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(`/channels/${channelId}/polls/${messageId}/answers/${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(`/channels/${channelId}/polls/${messageId}/expire`, {
+			signal,
+		}) as Promise<RESTPostAPIPollExpireResult>;
+	}
+}

packages/core/src/client.ts

@@ -92,6 +92,8 @@ export interface WithIntrinsicProps<Data> extends IntrinsicProps {
 	data: Data;
 }
 
+type GatewayMessagePollVoteData = any;
+
 export interface MappedEvents {
 	[GatewayDispatchEvents.ApplicationCommandPermissionsUpdate]: [
 		WithIntrinsicProps<GatewayApplicationCommandPermissionsUpdateDispatchData>,
@@ -143,6 +145,8 @@ export interface MappedEvents {
 	[GatewayDispatchEvents.MessageCreate]: [WithIntrinsicProps<GatewayMessageCreateDispatchData>];
 	[GatewayDispatchEvents.MessageDelete]: [WithIntrinsicProps<GatewayMessageDeleteDispatchData>];
 	[GatewayDispatchEvents.MessageDeleteBulk]: [WithIntrinsicProps<GatewayMessageDeleteBulkDispatchData>];
+	['MESSAGE_POLL_VOTE_ADD']: [WithIntrinsicProps<GatewayMessagePollVoteData>];
+	['MESSAGE_POLL_VOTE_REMOVE']: [WithIntrinsicProps<GatewayMessagePollVoteData>];
 	[GatewayDispatchEvents.MessageReactionAdd]: [WithIntrinsicProps<GatewayMessageReactionAddDispatchData>];
 	[GatewayDispatchEvents.MessageReactionRemove]: [WithIntrinsicProps<GatewayMessageReactionRemoveDispatchData>];
 	[GatewayDispatchEvents.MessageReactionRemoveAll]: [WithIntrinsicProps<GatewayMessageReactionRemoveAllDispatchData>];

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,34 @@
+'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) {
+      console.log('???');
+      return false;
+    }
+
+    /**
+     * 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,34 @@
+'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) {
+      console.log('???');
+      return false;
+    }
+
+    /**
+     * 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

@@ -176,6 +176,8 @@
  * @property {'SweepFilterReturn'} SweepFilterReturn
 
  * @property {'EntitlementCreateInvalidOwner'} EntitlementCreateInvalidOwner
+
+ * @property {'PollAlreadyExpired'} PollAlreadyExpired
  */
 
 const keys = [
@@ -329,6 +331,8 @@ const keys = [
   'GuildForumMessageRequired',
 
   'EntitlementCreateInvalidOwner',
+
+  'PollAlreadyExpired',
 ];
 
 // JSDoc for IntelliSense purposes

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

@@ -169,6 +169,8 @@ const Messages = {
 
   [DjsErrorCodes.EntitlementCreateInvalidOwner]:
     'You must provide either a guild or a user to create an entitlement, but not both',
+
+  [DjsErrorCodes.PollAlreadyExpired]: 'This poll has already expired.',
 };
 
 module.exports = Messages;

packages/discord.js/src/index.js

@@ -168,6 +168,9 @@ 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.PollAnswerResult = require('./structures/PollAnswerResult').PollAnswerResult;
 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/Poll.js

@@ -0,0 +1,113 @@
+'use strict';
+
+const { Collection } = require('@discordjs/collection');
+const Base = require('./Base');
+const { PollAnswer } = require('./PollAnswer');
+const { PollAnswerResult } = require('./PollAnswerResult');
+const { DiscordjsError } = require('../errors/DJSError');
+const { ErrorCodes } = require('../errors/index');
+
+/**
+ * Represents a Poll
+ * @extends {Base}
+ */
+class Poll extends Base {
+  constructor(client, data, message) {
+    super(client);
+
+    /**
+     * The message that started this poll
+     * @name Poll#message
+     * @type {Message}
+     * @readonly
+     */
+
+    Object.defineProperty(this, 'message', { value: message });
+
+    this._patch(data);
+  }
+
+  _patch(data) {
+    /**
+     * The question text of this poll
+     * @type {string}
+     */
+    this.question = data.question.text;
+
+    /**
+     * The answers of this poll
+     * @type {Collection<number, PollAnswer>}
+     */
+    this.answers = data.answers.reduce(
+      (acc, answer) => acc.set(answer.answer_id, new PollAnswer(this.client, answer, this)),
+      new Collection(),
+    );
+
+    /**
+     * The timestamp when this poll expires
+     * @type {number}
+     */
+    this.expiresTimestamp = Date.parse(data.expiry);
+
+    /**
+     * Whether this poll allows multiple answers
+     * @type {boolean}
+     */
+    this.allowMultiselect = data.allow_multiselect;
+
+    /**
+     * The layout type of this poll
+     * @type {PollLayoutType}
+     */
+    this.layoutType = data.layout_type;
+
+    if (data.results) {
+      /**
+       * @typedef {Object} PollResults
+       * @property {Collection<number, PollAnswerResult>} answerCounts The counts of each answer
+       * @property {boolean} isFinalized Whether the results are finalized
+       */
+
+      /**
+       * The results of this poll
+       * @type {?PollResults}
+       */
+      this.results = {
+        answerCounts: data.results.answer_counts.reduce(
+          (acc, result) => acc.set(result.id, new PollAnswerResult(result)),
+          new Collection(),
+        ),
+        isFinalized: data.results.is_finalized,
+      };
+    } else {
+      this.results = null;
+    }
+  }
+
+  /**
+   * The date when this poll expires
+   * @type {Date}
+   * @readonly
+   */
+  get expiresAt() {
+    return new Date(this.expiresTimestamp);
+  }
+
+  /**
+   * End this poll
+   * @returns {Promise<Message>}
+   */
+  async end() {
+    if (Date.now() > this.expiresTimestamp) {
+      throw new DiscordjsError(ErrorCodes.PollAlreadyExpired);
+    }
+
+    const message = await this.client.rest.post(`/channels/${this.message.channel.id}/poll/${this.message.id}/expire`);
+
+    this.message._patch(message);
+
+    return this.message;
+  }
+}
+
+exports.Poll = Poll;