@velliajs/discord 1.0.0

package/src/managers/GuildTextThreadManager.js

@@ -0,0 +1,91 @@
+'use strict';
+
+const { ChannelType, Routes } = require('discord-api-types/v10');
+const ThreadManager = require('./ThreadManager');
+const { DiscordjsTypeError, ErrorCodes } = require('../errors');
+
+/**
+ * Manages API methods for {@link ThreadChannel} objects and stores their cache.
+ * @extends {ThreadManager}
+ */
+class GuildTextThreadManager extends ThreadManager {
+  /**
+   * The channel this Manager belongs to
+   * @name GuildTextThreadManager#channel
+   * @type {TextChannel|NewsChannel}
+   */
+
+  /**
+   * Options for creating a thread. <warn>Only one of `startMessage` or `type` can be defined.</warn>
+   * @typedef {StartThreadOptions} ThreadCreateOptions
+   * @property {MessageResolvable} [startMessage] The message to start a thread from.
+   * <warn>If this is defined, then the `type` of thread gets inferred automatically and cannot be changed.</warn>
+   * @property {ThreadChannelTypes} [type] The type of thread to create.
+   * Defaults to {@link ChannelType.PublicThread} if created in a {@link TextChannel}
+   * <warn>When creating threads in a {@link NewsChannel}, this is ignored and is always
+   * {@link ChannelType.AnnouncementThread}</warn>
+   * @property {boolean} [invitable] Whether non-moderators can add other non-moderators to the thread
+   * <info>Can only be set when type will be {@link ChannelType.PrivateThread}</info>
+   */
+
+  /**
+   * Creates a new thread in the channel.
+   * @param {ThreadCreateOptions} [options] Options to create a new thread
+   * @returns {Promise<ThreadChannel>}
+   * @example
+   * // Create a new public thread
+   * channel.threads
+   *   .create({
+   *     name: 'food-talk',
+   *     autoArchiveDuration: ThreadAutoArchiveDuration.OneHour,
+   *     reason: 'Needed a separate thread for food',
+   *   })
+   *   .then(threadChannel => console.log(threadChannel))
+   *   .catch(console.error);
+   * @example
+   * // Create a new private thread
+   * channel.threads
+   *   .create({
+   *      name: 'mod-talk',
+   *      autoArchiveDuration: ThreadAutoArchiveDuration.OneHour,
+   *      type: ChannelType.PrivateThread,
+   *      reason: 'Needed a separate thread for moderation',
+   *    })
+   *   .then(threadChannel => console.log(threadChannel))
+   *   .catch(console.error);
+   */
+  async create({
+    name,
+    autoArchiveDuration = this.channel.defaultAutoArchiveDuration,
+    startMessage,
+    type,
+    invitable,
+    reason,
+    rateLimitPerUser,
+  } = {}) {
+    let resolvedType =
+      this.channel.type === ChannelType.GuildAnnouncement ? ChannelType.AnnouncementThread : ChannelType.PublicThread;
+    let startMessageId;
+    if (startMessage) {
+      startMessageId = this.channel.messages.resolveId(startMessage);
+      if (!startMessageId) throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'startMessage', 'MessageResolvable');
+    } else if (this.channel.type !== ChannelType.GuildAnnouncement) {
+      resolvedType = type ?? resolvedType;
+    }
+
+    const data = await this.client.rest.post(Routes.threads(this.channel.id, startMessageId), {
+      body: {
+        name,
+        auto_archive_duration: autoArchiveDuration,
+        type: resolvedType,
+        invitable: resolvedType === ChannelType.PrivateThread ? invitable : undefined,
+        rate_limit_per_user: rateLimitPerUser,
+      },
+      reason,
+    });
+
+    return this.client.actions.ThreadCreate.handle(data).thread;
+  }
+}
+
+module.exports = GuildTextThreadManager;

package/src/managers/MessageManager.js

@@ -0,0 +1,259 @@
+'use strict';
+
+const { Collection } = require('@discordjs/collection');
+const { makeURLSearchParams } = require('@discordjs/rest');
+const { Routes } = require('discord-api-types/v10');
+const CachedManager = require('./CachedManager');
+const { DiscordjsTypeError, ErrorCodes } = require('../errors');
+const { Message } = require('../structures/Message');
+const MessagePayload = require('../structures/MessagePayload');
+const { resolvePartialEmoji } = require('../util/Util');
+
+/**
+ * Manages API methods for Messages and holds their cache.
+ * @extends {CachedManager}
+ */
+class MessageManager extends CachedManager {
+  constructor(channel, iterable) {
+    super(channel.client, Message, iterable);
+
+    /**
+     * The channel that the messages belong to
+     * @type {TextBasedChannels}
+     */
+    this.channel = channel;
+  }
+
+  /**
+   * The cache of Messages
+   * @type {Collection<Snowflake, Message>}
+   * @name MessageManager#cache
+   */
+
+  _add(data, cache) {
+    return super._add(data, cache);
+  }
+
+  /**
+   * Data that can be resolved to a Message object. This can be:
+   * * A Message
+   * * A Snowflake
+   * @typedef {Message|Snowflake} MessageResolvable
+   */
+
+  /**
+   * Options used to fetch a message.
+   * @typedef {BaseFetchOptions} FetchMessageOptions
+   * @property {MessageResolvable} message The message to fetch
+   */
+
+  /**
+   * Options used to fetch multiple messages.
+   * <info>The `before`, `after`, and `around` parameters are mutually exclusive.</info>
+   * @typedef {Object} FetchMessagesOptions
+   * @property {number} [limit] The maximum number of messages to return
+   * @property {Snowflake} [before] Consider only messages before this id
+   * @property {Snowflake} [after] Consider only messages after this id
+   * @property {Snowflake} [around] Consider only messages around this id
+   * @property {boolean} [cache] Whether to cache the fetched messages
+   */
+
+  /**
+   * Fetches message(s) from a channel.
+   * <info>The returned Collection does not contain reaction users of the messages if they were not cached.
+   * Those need to be fetched separately in such a case.</info>
+   * @param {MessageResolvable|FetchMessageOptions|FetchMessagesOptions} [options] Options for fetching message(s)
+   * @returns {Promise<Message|Collection<Snowflake, Message>>}
+   * @example
+   * // Fetch a message
+   * channel.messages.fetch('99539446449315840')
+   *   .then(message => console.log(message.content))
+   *   .catch(console.error);
+   * @example
+   * // Fetch a maximum of 10 messages without caching
+   * channel.messages.fetch({ limit: 10, cache: false })
+   *   .then(messages => console.log(`Received ${messages.size} messages`))
+   *   .catch(console.error);
+   * @example
+   * // Fetch a maximum of 10 messages without caching around a message id
+   * channel.messages.fetch({ limit: 10, cache: false, around: '99539446449315840' })
+   *   .then(messages => console.log(`Received ${messages.size} messages`))
+   *   .catch(console.error);
+   * @example
+   * // Fetch messages and filter by a user id
+   * channel.messages.fetch()
+   *   .then(messages => console.log(`${messages.filter(m => m.author.id === '84484653687267328').size} messages`))
+   *   .catch(console.error);
+   */
+  fetch(options) {
+    if (!options) return this._fetchMany();
+    const { message, cache, force } = options;
+    const resolvedMessage = this.resolveId(message ?? options);
+    if (resolvedMessage) return this._fetchSingle({ message: resolvedMessage, cache, force });
+    return this._fetchMany(options);
+  }
+
+  async _fetchSingle({ message, cache, force = false }) {
+    if (!force) {
+      const existing = this.cache.get(message);
+      if (existing && !existing.partial) return existing;
+    }
+
+    const data = await this.client.rest.get(Routes.channelMessage(this.channel.id, message));
+    return this._add(data, cache);
+  }
+
+  async _fetchMany(options = {}) {
+    const data = await this.client.rest.get(Routes.channelMessages(this.channel.id), {
+      query: makeURLSearchParams(options),
+    });
+
+    return data.reduce((_data, message) => _data.set(message.id, this._add(message, options.cache)), new Collection());
+  }
+
+  /**
+   * Fetches the pinned messages of this channel and returns a collection of them.
+   * <info>The returned Collection does not contain any reaction data of the messages.
+   * Those need to be fetched separately.</info>
+   * @param {boolean} [cache=true] Whether to cache the message(s)
+   * @returns {Promise<Collection<Snowflake, Message>>}
+   * @example
+   * // Get pinned messages
+   * channel.messages.fetchPinned()
+   *   .then(messages => console.log(`Received ${messages.size} messages`))
+   *   .catch(console.error);
+   */
+  async fetchPinned(cache = true) {
+    const data = await this.client.rest.get(Routes.channelPins(this.channel.id));
+    const messages = new Collection();
+    for (const message of data) messages.set(message.id, this._add(message, cache));
+    return messages;
+  }
+
+  /**
+   * Resolves a {@link MessageResolvable} to a {@link Message} object.
+   * @method resolve
+   * @memberof MessageManager
+   * @instance
+   * @param {MessageResolvable} message The message resolvable to resolve
+   * @returns {?Message}
+   */
+
+  /**
+   * Resolves a {@link MessageResolvable} to a {@link Message} id.
+   * @method resolveId
+   * @memberof MessageManager
+   * @instance
+   * @param {MessageResolvable} message The message resolvable to resolve
+   * @returns {?Snowflake}
+   */
+
+  /**
+   * Options that can be passed to edit a message.
+   * @typedef {BaseMessageOptions} MessageEditOptions
+   * @property {AttachmentPayload[]} [attachments] An array of attachments to keep,
+   * all attachments will be kept if omitted
+   * @property {MessageFlags} [flags] Which flags to set for the message
+   * <info>Only the {@link MessageFlags.SuppressEmbeds} flag can be modified.</info>
+   */
+
+  /**
+   * Edits a message, even if it's not cached.
+   * @param {MessageResolvable} message The message to edit
+   * @param {string|MessageEditOptions|MessagePayload} options The options to edit the message
+   * @returns {Promise<Message>}
+   */
+  async edit(message, options) {
+    const messageId = this.resolveId(message);
+    if (!messageId) throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'message', 'MessageResolvable');
+
+    const { body, files } = await (options instanceof MessagePayload
+      ? options
+      : MessagePayload.create(message instanceof Message ? message : this, options)
+    )
+      .resolveBody()
+      .resolveFiles();
+    const d = await this.client.rest.patch(Routes.channelMessage(this.channel.id, messageId), { body, files });
+
+    const existing = this.cache.get(messageId);
+    if (existing) {
+      const clone = existing._clone();
+      clone._patch(d);
+      return clone;
+    }
+    return this._add(d);
+  }
+
+  /**
+   * Publishes a message in an announcement channel to all channels following it, even if it's not cached.
+   * @param {MessageResolvable} message The message to publish
+   * @returns {Promise<Message>}
+   */
+  async crosspost(message) {
+    message = this.resolveId(message);
+    if (!message) throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'message', 'MessageResolvable');
+
+    const data = await this.client.rest.post(Routes.channelMessageCrosspost(this.channel.id, message));
+    return this.cache.get(data.id) ?? this._add(data);
+  }
+
+  /**
+   * Pins a message to the channel's pinned messages, even if it's not cached.
+   * @param {MessageResolvable} message The message to pin
+   * @param {string} [reason] Reason for pinning
+   * @returns {Promise<void>}
+   */
+  async pin(message, reason) {
+    message = this.resolveId(message);
+    if (!message) throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'message', 'MessageResolvable');
+
+    await this.client.rest.put(Routes.channelPin(this.channel.id, message), { reason });
+  }
+
+  /**
+   * Unpins a message from the channel's pinned messages, even if it's not cached.
+   * @param {MessageResolvable} message The message to unpin
+   * @param {string} [reason] Reason for unpinning
+   * @returns {Promise<void>}
+   */
+  async unpin(message, reason) {
+    message = this.resolveId(message);
+    if (!message) throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'message', 'MessageResolvable');
+
+    await this.client.rest.delete(Routes.channelPin(this.channel.id, message), { reason });
+  }
+
+  /**
+   * Adds a reaction to a message, even if it's not cached.
+   * @param {MessageResolvable} message The message to react to
+   * @param {EmojiIdentifierResolvable} emoji The emoji to react with
+   * @returns {Promise<void>}
+   */
+  async react(message, emoji) {
+    message = this.resolveId(message);
+    if (!message) throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'message', 'MessageResolvable');
+
+    emoji = resolvePartialEmoji(emoji);
+    if (!emoji) throw new DiscordjsTypeError(ErrorCodes.EmojiType, 'emoji', 'EmojiIdentifierResolvable');
+
+    const emojiId = emoji.id
+      ? `${emoji.animated ? 'a:' : ''}${emoji.name}:${emoji.id}`
+      : encodeURIComponent(emoji.name);
+
+    await this.client.rest.put(Routes.channelMessageOwnReaction(this.channel.id, message, emojiId));
+  }
+
+  /**
+   * Deletes a message, even if it's not cached.
+   * @param {MessageResolvable} message The message to delete
+   * @returns {Promise<void>}
+   */
+  async delete(message) {
+    message = this.resolveId(message);
+    if (!message) throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'message', 'MessageResolvable');
+
+    await this.client.rest.delete(Routes.channelMessage(this.channel.id, message));
+  }
+}
+
+module.exports = MessageManager;

package/src/managers/PermissionOverwriteManager.js

@@ -0,0 +1,168 @@
+'use strict';
+
+const process = require('node:process');
+const { Collection } = require('@discordjs/collection');
+const { OverwriteType, Routes } = require('discord-api-types/v10');
+const CachedManager = require('./CachedManager');
+const { DiscordjsTypeError, ErrorCodes } = require('../errors');
+const PermissionOverwrites = require('../structures/PermissionOverwrites');
+const { Role } = require('../structures/Role');
+
+let cacheWarningEmitted = false;
+
+/**
+ * Manages API methods for guild channel permission overwrites and stores their cache.
+ * @extends {CachedManager}
+ */
+class PermissionOverwriteManager extends CachedManager {
+  constructor(channel, iterable) {
+    super(channel.client, PermissionOverwrites);
+    if (!cacheWarningEmitted && this._cache.constructor.name !== 'Collection') {
+      cacheWarningEmitted = true;
+      process.emitWarning(
+        `Overriding the cache handling for ${this.constructor.name} is unsupported and breaks functionality.`,
+        'UnsupportedCacheOverwriteWarning',
+      );
+    }
+
+    /**
+     * The channel of the permission overwrite this manager belongs to
+     * @type {GuildChannel}
+     */
+    this.channel = channel;
+
+    if (iterable) {
+      for (const item of iterable) {
+        this._add(item);
+      }
+    }
+  }
+
+  /**
+   * The cache of this Manager
+   * @type {Collection<Snowflake, PermissionOverwrites>}
+   * @name PermissionOverwriteManager#cache
+   */
+
+  _add(data, cache) {
+    return super._add(data, cache, { extras: [this.channel] });
+  }
+
+  /**
+   * Replaces the permission overwrites in this channel.
+   * @param {OverwriteResolvable[]|Collection<Snowflake, OverwriteResolvable>} overwrites
+   * Permission overwrites the channel gets updated with
+   * @param {string} [reason] Reason for updating the channel overwrites
+   * @returns {Promise<GuildChannel>}
+   * @example
+   * message.channel.permissionOverwrites.set([
+   *   {
+   *      id: message.author.id,
+   *      deny: [PermissionsFlagsBit.ViewChannel],
+   *   },
+   * ], 'Needed to change permissions');
+   */
+  set(overwrites, reason) {
+    if (!Array.isArray(overwrites) && !(overwrites instanceof Collection)) {
+      return Promise.reject(
+        new DiscordjsTypeError(
+          ErrorCodes.InvalidType,
+          'overwrites',
+          'Array or Collection of Permission Overwrites',
+          true,
+        ),
+      );
+    }
+    return this.channel.edit({ permissionOverwrites: overwrites, reason });
+  }
+
+  /**
+   * Extra information about the overwrite.
+   * @typedef {Object} GuildChannelOverwriteOptions
+   * @property {string} [reason] The reason for creating/editing this overwrite
+   * @property {OverwriteType} [type] The type of overwrite. Use this to bypass automatic resolution of `type`
+   * that results in an error for an uncached structure
+   */
+
+  /**
+   * Creates or edits permission overwrites for a user or role in this channel.
+   * @param {RoleResolvable|UserResolvable} userOrRole The user or role to update
+   * @param {PermissionOverwriteOptions} options The options for the update
+   * @param {GuildChannelOverwriteOptions} [overwriteOptions] The extra information for the update
+   * @param {PermissionOverwrites} [existing] The existing overwrites to merge with this update
+   * @returns {Promise<GuildChannel>}
+   * @private
+   */
+  async upsert(userOrRole, options, overwriteOptions = {}, existing) {
+    let userOrRoleId = this.channel.guild.roles.resolveId(userOrRole) ?? this.client.users.resolveId(userOrRole);
+    let { type, reason } = overwriteOptions;
+    if (typeof type !== 'number') {
+      userOrRole = this.channel.guild.roles.resolve(userOrRole) ?? this.client.users.resolve(userOrRole);
+      if (!userOrRole) throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'parameter', 'User nor a Role');
+      type = userOrRole instanceof Role ? OverwriteType.Role : OverwriteType.Member;
+    }
+
+    const { allow, deny } = PermissionOverwrites.resolveOverwriteOptions(options, existing);
+
+    await this.client.rest.put(Routes.channelPermission(this.channel.id, userOrRoleId), {
+      body: { id: userOrRoleId, type, allow, deny },
+      reason,
+    });
+    return this.channel;
+  }
+
+  /**
+   * Creates permission overwrites for a user or role in this channel, or replaces them if already present.
+   * @param {RoleResolvable|UserResolvable} userOrRole The user or role to update
+   * @param {PermissionOverwriteOptions} options The options for the update
+   * @param {GuildChannelOverwriteOptions} [overwriteOptions] The extra information for the update
+   * @returns {Promise<GuildChannel>}
+   * @example
+   * // Create or Replace permission overwrites for a message author
+   * message.channel.permissionOverwrites.create(message.author, {
+   *   SendMessages: false
+   * })
+   *   .then(channel => console.log(channel.permissionOverwrites.cache.get(message.author.id)))
+   *   .catch(console.error);
+   */
+  create(userOrRole, options, overwriteOptions) {
+    return this.upsert(userOrRole, options, overwriteOptions);
+  }
+
+  /**
+   * Edits permission overwrites for a user or role in this channel, or creates an entry if not already present.
+   * @param {RoleResolvable|UserResolvable} userOrRole The user or role to update
+   * @param {PermissionOverwriteOptions} options The options for the update
+   * @param {GuildChannelOverwriteOptions} [overwriteOptions] The extra information for the update
+   * @returns {Promise<GuildChannel>}
+   * @example
+   * // Edit or Create permission overwrites for a message author
+   * message.channel.permissionOverwrites.edit(message.author, {
+   *   SendMessages: false
+   * })
+   *   .then(channel => console.log(channel.permissionOverwrites.cache.get(message.author.id)))
+   *   .catch(console.error);
+   */
+  edit(userOrRole, options, overwriteOptions) {
+    const existing = this.cache.get(
+      this.channel.guild.roles.resolveId(userOrRole) ?? this.client.users.resolveId(userOrRole),
+    );
+    return this.upsert(userOrRole, options, overwriteOptions, existing);
+  }
+
+  /**
+   * Deletes permission overwrites for a user or role in this channel.
+   * @param {UserResolvable|RoleResolvable} userOrRole The user or role to delete
+   * @param {string} [reason] The reason for deleting the overwrite
+   * @returns {Promise<GuildChannel>}
+   */
+  async delete(userOrRole, reason) {
+    const userOrRoleId = this.channel.guild.roles.resolveId(userOrRole) ?? this.client.users.resolveId(userOrRole);
+    if (!userOrRoleId) throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'parameter', 'User nor a Role');
+
+    await this.client.rest.delete(Routes.channelPermission(this.channel.id, userOrRoleId), { reason });
+    return this.channel;
+  }
+}
+
+module.exports = PermissionOverwriteManager;

package/src/managers/PresenceManager.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const CachedManager = require('./CachedManager');
+const { Presence } = require('../structures/Presence');
+
+/**
+ * Manages API methods for Presences and holds their cache.
+ * @extends {CachedManager}
+ */
+class PresenceManager extends CachedManager {
+  constructor(client, iterable) {
+    super(client, Presence, iterable);
+  }
+
+  /**
+   * The cache of Presences
+   * @type {Collection<Snowflake, Presence>}
+   * @name PresenceManager#cache
+   */
+
+  _add(data, cache) {
+    return super._add(data, cache, { id: data.user.id });
+  }
+
+  /**
+   * Data that can be resolved to a Presence object. This can be:
+   * * A Presence
+   * * A UserResolvable
+   * * A Snowflake
+   * @typedef {Presence|UserResolvable|Snowflake} PresenceResolvable
+   */
+
+  /**
+   * Resolves a {@link PresenceResolvable} to a {@link Presence} object.
+   * @param {PresenceResolvable} presence The presence resolvable to resolve
+   * @returns {?Presence}
+   */
+  resolve(presence) {
+    const presenceResolvable = super.resolve(presence);
+    if (presenceResolvable) return presenceResolvable;
+    const UserResolvable = this.client.users.resolveId(presence);
+    return super.resolve(UserResolvable);
+  }
+
+  /**
+   * Resolves a {@link PresenceResolvable} to a {@link Presence} id.
+   * @param {PresenceResolvable} presence The presence resolvable to resolve
+   * @returns {?Snowflake}
+   */
+  resolveId(presence) {
+    const presenceResolvable = super.resolveId(presence);
+    if (presenceResolvable) return presenceResolvable;
+    const userResolvable = this.client.users.resolveId(presence);
+    return this.cache.has(userResolvable) ? userResolvable : null;
+  }
+}
+
+module.exports = PresenceManager;

package/src/managers/ReactionManager.js

@@ -0,0 +1,68 @@
+'use strict';
+
+const { Routes } = require('discord-api-types/v10');
+const CachedManager = require('./CachedManager');
+const MessageReaction = require('../structures/MessageReaction');
+
+/**
+ * Manages API methods for reactions and holds their cache.
+ * @extends {CachedManager}
+ */
+class ReactionManager extends CachedManager {
+  constructor(message, iterable) {
+    super(message.client, MessageReaction, iterable);
+
+    /**
+     * The message that this manager belongs to
+     * @type {Message}
+     */
+    this.message = message;
+  }
+
+  _add(data, cache) {
+    return super._add(data, cache, { id: data.emoji.id ?? data.emoji.name, extras: [this.message] });
+  }
+
+  /**
+   * The reaction cache of this manager
+   * @type {Collection<string|Snowflake, MessageReaction>}
+   * @name ReactionManager#cache
+   */
+
+  /**
+   * Data that can be resolved to a MessageReaction object. This can be:
+   * * A MessageReaction
+   * * A Snowflake
+   * * The Unicode representation of an emoji
+   * @typedef {MessageReaction|Snowflake} MessageReactionResolvable
+   */
+
+  /**
+   * Resolves a {@link MessageReactionResolvable} to a {@link MessageReaction} object.
+   * @method resolve
+   * @memberof ReactionManager
+   * @instance
+   * @param {MessageReactionResolvable} reaction The MessageReaction to resolve
+   * @returns {?MessageReaction}
+   */
+
+  /**
+   * Resolves a {@link MessageReactionResolvable} to a {@link MessageReaction} id.
+   * @method resolveId
+   * @memberof ReactionManager
+   * @instance
+   * @param {MessageReactionResolvable} reaction The MessageReaction to resolve
+   * @returns {?Snowflake}
+   */
+
+  /**
+   * Removes all reactions from a message.
+   * @returns {Promise<Message>}
+   */
+  async removeAll() {
+    await this.client.rest.delete(Routes.channelMessageAllReactions(this.message.channelId, this.message.id));
+    return this.message;
+  }
+}
+
+module.exports = ReactionManager;