discord-sb.js 1.0.0

package/src/structures/OAuth2Guild.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const BaseGuild = require('./BaseGuild');
+const Permissions = require('../util/Permissions');
+
+/**
+ * A partial guild received when using {@link GuildManager#fetch} to fetch multiple guilds.
+ * @extends {BaseGuild}
+ */
+class OAuth2Guild extends BaseGuild {
+  constructor(client, data) {
+    super(client, data);
+
+    /**
+     * Whether the client user is the owner of the guild
+     * @type {boolean}
+     */
+    this.owner = data.owner;
+
+    /**
+     * The permissions that the client user has in this guild
+     * @type {Readonly<Permissions>}
+     */
+    this.permissions = new Permissions(BigInt(data.permissions)).freeze();
+  }
+}
+
+module.exports = OAuth2Guild;

package/src/structures/PermissionOverwrites.js

@@ -0,0 +1,198 @@
+'use strict';
+
+const Base = require('./Base');
+const { Role } = require('./Role');
+const { TypeError } = require('../errors');
+const { OverwriteTypes } = require('../util/Constants');
+const Permissions = require('../util/Permissions');
+
+/**
+ * Represents a permission overwrite for a role or member in a guild channel.
+ * @extends {Base}
+ */
+class PermissionOverwrites extends Base {
+  constructor(client, data, channel) {
+    super(client);
+
+    /**
+     * The GuildChannel this overwrite is for
+     * @name PermissionOverwrites#channel
+     * @type {GuildChannel}
+     * @readonly
+     */
+    Object.defineProperty(this, 'channel', { value: channel });
+
+    if (data) this._patch(data);
+  }
+
+  _patch(data) {
+    /**
+     * The overwrite's id, either a {@link User} or a {@link Role} id
+     * @type {Snowflake}
+     */
+    this.id = data.id;
+
+    if ('type' in data) {
+      /**
+       * The type of this overwrite
+       * @type {OverwriteType}
+       */
+      this.type = typeof data.type === 'number' ? OverwriteTypes[data.type] : data.type;
+    }
+
+    if ('deny' in data) {
+      /**
+       * The permissions that are denied for the user or role.
+       * @type {Readonly<Permissions>}
+       */
+      this.deny = new Permissions(BigInt(data.deny)).freeze();
+    }
+
+    if ('allow' in data) {
+      /**
+       * The permissions that are allowed for the user or role.
+       * @type {Readonly<Permissions>}
+       */
+      this.allow = new Permissions(BigInt(data.allow)).freeze();
+    }
+  }
+
+  /**
+   * Edits this Permission Overwrite.
+   * @param {PermissionOverwriteOptions} options The options for the update
+   * @param {string} [reason] Reason for creating/editing this overwrite
+   * @returns {Promise<PermissionOverwrites>}
+   * @example
+   * // Update permission overwrites
+   * permissionOverwrites.edit({
+   *   SEND_MESSAGES: false
+   * })
+   *   .then(channel => console.log(channel.permissionOverwrites.get(message.author.id)))
+   *   .catch(console.error);
+   */
+  async edit(options, reason) {
+    await this.channel.permissionOverwrites.upsert(this.id, options, { type: OverwriteTypes[this.type], reason }, this);
+    return this;
+  }
+
+  /**
+   * Deletes this Permission Overwrite.
+   * @param {string} [reason] Reason for deleting this overwrite
+   * @returns {Promise<PermissionOverwrites>}
+   */
+  async delete(reason) {
+    await this.channel.permissionOverwrites.delete(this.id, reason);
+    return this;
+  }
+
+  toJSON() {
+    return {
+      id: this.id,
+      type: OverwriteTypes[this.type],
+      allow: this.allow,
+      deny: this.deny,
+    };
+  }
+
+  /**
+   * An object mapping permission flags to `true` (enabled), `null` (unset) or `false` (disabled).
+   * ```js
+   * {
+   *  'SEND_MESSAGES': true,
+   *  'EMBED_LINKS': null,
+   *  'ATTACH_FILES': false,
+   * }
+   * ```
+   * @typedef {Object} PermissionOverwriteOptions
+   */
+
+  /**
+   * @typedef {Object} ResolvedOverwriteOptions
+   * @property {Permissions} allow The allowed permissions
+   * @property {Permissions} deny The denied permissions
+   */
+
+  /**
+   * Resolves bitfield permissions overwrites from an object.
+   * @param {PermissionOverwriteOptions} options The options for the update
+   * @param {ResolvedOverwriteOptions} initialPermissions The initial permissions
+   * @returns {ResolvedOverwriteOptions}
+   */
+  static resolveOverwriteOptions(options, { allow, deny } = {}) {
+    allow = new Permissions(allow);
+    deny = new Permissions(deny);
+
+    for (const [perm, value] of Object.entries(options)) {
+      if (value === true) {
+        allow.add(perm);
+        deny.remove(perm);
+      } else if (value === false) {
+        allow.remove(perm);
+        deny.add(perm);
+      } else if (value === null) {
+        allow.remove(perm);
+        deny.remove(perm);
+      }
+    }
+
+    return { allow, deny };
+  }
+
+  /**
+   * The raw data for a permission overwrite
+   * @typedef {Object} RawOverwriteData
+   * @property {Snowflake} id The id of the {@link Role} or {@link User} this overwrite belongs to
+   * @property {string} allow The permissions to allow
+   * @property {string} deny The permissions to deny
+   * @property {number} type The type of this OverwriteData
+   */
+
+  /**
+   * Data that can be resolved into {@link RawOverwriteData}. This can be:
+   * * PermissionOverwrites
+   * * OverwriteData
+   * @typedef {PermissionOverwrites|OverwriteData} OverwriteResolvable
+   */
+
+  /**
+   * Data that can be used for a permission overwrite
+   * @typedef {Object} OverwriteData
+   * @property {GuildMemberResolvable|RoleResolvable} id Member or role this overwrite is for
+   * @property {PermissionResolvable} [allow] The permissions to allow
+   * @property {PermissionResolvable} [deny] The permissions to deny
+   * @property {OverwriteType} [type] The type of this OverwriteData
+   */
+
+  /**
+   * Resolves an overwrite into {@link RawOverwriteData}.
+   * @param {OverwriteResolvable} overwrite The overwrite-like data to resolve
+   * @param {Guild} [guild] The guild to resolve from
+   * @returns {RawOverwriteData}
+   */
+  static resolve(overwrite, guild) {
+    if (overwrite instanceof this) return overwrite.toJSON();
+    if (typeof overwrite.id === 'string' && overwrite.type in OverwriteTypes) {
+      return {
+        id: overwrite.id,
+        type: OverwriteTypes[overwrite.type],
+        allow: Permissions.resolve(overwrite.allow ?? Permissions.defaultBit).toString(),
+        deny: Permissions.resolve(overwrite.deny ?? Permissions.defaultBit).toString(),
+      };
+    }
+
+    const userOrRole = guild.roles.resolve(overwrite.id) ?? guild.client.users.resolve(overwrite.id);
+    if (!userOrRole) {
+      throw new TypeError('INVALID_TYPE', 'parameter', 'cached User or Role');
+    }
+    const type = userOrRole instanceof Role ? OverwriteTypes.role : OverwriteTypes.member;
+
+    return {
+      id: userOrRole.id,
+      type,
+      allow: Permissions.resolve(overwrite.allow ?? Permissions.defaultBit).toString(),
+      deny: Permissions.resolve(overwrite.deny ?? Permissions.defaultBit).toString(),
+    };
+  }
+}
+
+module.exports = PermissionOverwrites;

package/src/structures/Poll.js

@@ -0,0 +1,108 @@
+'use strict';
+
+const { Collection } = require('@discordjs/collection');
+const Base = require('./Base');
+const { PollAnswer } = require('./PollAnswer');
+const { Error } = require('../errors');
+const { PollLayoutTypes } = require('../util/Constants');
+
+/**
+ * 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 });
+
+    /**
+     * The media for a poll's question
+     * @typedef {Object} PollQuestionMedia
+     * @property {string} text The text of this question
+     */
+
+    /**
+     * The media for this poll's question
+     * @type {PollQuestionMedia}
+     */
+    this.question = {
+      text: 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 = PollLayoutTypes[data.layout_type];
+
+    this._patch(data);
+  }
+
+  _patch(data) {
+    if (data.results) {
+      /**
+       * Whether this poll's results have been precisely counted
+       * @type {boolean}
+       */
+      this.resultsFinalized = data.results.is_finalized;
+
+      for (const answerResult of data.results.answer_counts) {
+        const answer = this.answers.get(answerResult.id);
+        answer?._patch(answerResult);
+      }
+    } else {
+      this.resultsFinalized ??= false;
+    }
+  }
+
+  /**
+   * The date when this poll expires
+   * @type {Date}
+   * @readonly
+   */
+  get expiresAt() {
+    return new Date(this.expiresTimestamp);
+  }
+
+  /**
+   * Ends this poll.
+   * @returns {Promise<Message>}
+   */
+  async end() {
+    if (Date.now() > this.expiresTimestamp) {
+      throw new Error('POLL_ALREADY_EXPIRED');
+    }
+    return this.message.channel.messages.endPoll(this.message.id);
+  }
+}
+
+module.exports = { Poll };

package/src/structures/PollAnswer.js

@@ -0,0 +1,88 @@
+'use strict';
+
+const Base = require('./Base');
+const { Emoji } = require('./Emoji');
+
+/**
+ * Represents an answer to a {@link Poll}
+ * @extends {Base}
+ */
+class PollAnswer extends Base {
+  constructor(client, data, poll) {
+    super(client);
+
+    /**
+     * The {@link Poll} this answer is part of
+     * @name PollAnswer#poll
+     * @type {Poll}
+     * @readonly
+     */
+    Object.defineProperty(this, 'poll', { value: poll });
+
+    /**
+     * The id of this answer
+     * @type {number}
+     */
+    this.id = data.answer_id;
+
+    /**
+     * The text of this answer
+     * @type {?string}
+     */
+    this.text = data.poll_media.text ?? null;
+
+    /**
+     * The raw emoji of this answer
+     * @name PollAnswer#_emoji
+     * @type {?APIPartialEmoji}
+     * @private
+     */
+    Object.defineProperty(this, '_emoji', { value: data.poll_media.emoji ?? null });
+
+    this._patch(data);
+  }
+
+  _patch(data) {
+    // This `count` field comes from `poll.results.answer_counts`
+    if ('count' in data) {
+      /**
+       * The amount of votes this answer has
+       * @type {number}
+       */
+      this.voteCount = data.count;
+    } else {
+      this.voteCount ??= 0;
+    }
+  }
+
+  /**
+   * The emoji of this answer
+   * @type {?(GuildEmoji|Emoji)}
+   */
+  get emoji() {
+    if (!this._emoji || (!this._emoji.id && !this._emoji.name)) return null;
+    return this.client.emojis.cache.get(this._emoji.id) ?? new Emoji(this.client, this._emoji);
+  }
+
+  /**
+   * @typedef {Object} FetchPollVotersOptions
+   * @property {number} [limit] The maximum number of voters to fetch
+   * @property {Snowflake} [after] The user id to fetch voters after
+   */
+
+  /**
+   * Fetches the users that voted for this answer
+   * @param {FetchPollVotersOptions} [options={}] The options for fetching voters
+   * @returns {Promise<Collection<Snowflake, User>>}
+   */
+  fetchVoters({ after, limit } = {}) {
+    return this.poll.message.channel.messages.fetchPollAnswerVoters({
+      messageId: this.poll.message.id,
+      answerId: this.id,
+      after,
+      limit,
+    });
+  }
+}
+
+module.exports = { PollAnswer };