discord-sb.js 1.0.0

package/src/managers/RoleManager.js

@@ -0,0 +1,448 @@
+'use strict';
+
+const process = require('node:process');
+const { Collection } = require('@discordjs/collection');
+const CachedManager = require('./CachedManager');
+const { TypeError } = require('../errors');
+const { Role } = require('../structures/Role');
+const DataResolver = require('../util/DataResolver');
+const Permissions = require('../util/Permissions');
+const { resolveColor } = require('../util/Util');
+const Util = require('../util/Util');
+
+let cacheWarningEmitted = false;
+let deprecationEmittedForCreate = false;
+let deprecationEmittedForEdit = false;
+
+/**
+ * Manages API methods for roles and stores their cache.
+ * @extends {CachedManager}
+ */
+class RoleManager extends CachedManager {
+  constructor(guild, iterable) {
+    super(guild.client, Role, iterable);
+    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 guild belonging to this manager
+     * @type {Guild}
+     */
+    this.guild = guild;
+  }
+
+  /**
+   * The role cache of this manager
+   * @type {Collection<Snowflake, Role>}
+   * @name RoleManager#cache
+   */
+
+  _add(data, cache) {
+    return super._add(data, cache, { extras: [this.guild] });
+  }
+
+  /**
+   * Obtains a role from Discord, or the role cache if they're already available.
+   * @param {Snowflake} [id] The role's id
+   * @param {BaseFetchOptions} [options] Additional options for this fetch
+   * @returns {Promise<?Role|Collection<Snowflake, Role>>}
+   * @example
+   * // Fetch all roles from the guild
+   * message.guild.roles.fetch()
+   *   .then(roles => console.log(`There are ${roles.size} roles.`))
+   *   .catch(console.error);
+   * @example
+   * // Fetch a single role
+   * message.guild.roles.fetch('222078108977594368')
+   *   .then(role => console.log(`The role color is: ${role.colors.primaryColor}`))
+   *   .catch(console.error);
+   */
+  async fetch(id, { cache = true, force = false } = {}) {
+    if (id && !force) {
+      const existing = this.cache.get(id);
+      if (existing) return existing;
+    }
+
+    // We cannot fetch a single role, as of this commit's date, Discord API throws with 405
+    const data = await this.client.api.guilds(this.guild.id).roles.get();
+    const roles = new Collection();
+    for (const role of data) roles.set(role.id, this._add(role, cache));
+    return id ? roles.get(id) ?? null : roles;
+  }
+
+  /**
+   * Fetches the member counts for each role in the guild.
+   * @returns {Promise<Record<Snowflake, number>>}
+   */
+  async fetchMemberCounts() {
+    const data = await this.client.api.guilds(this.guild.id).roles('member-counts').get();
+
+    return data;
+  }
+
+  /**
+   * Fetches the member ids for a role in the guild.
+   * <info>This only returns 100 member ids</info>
+   * @param {RoleResolvable} role The role to fetch member ids for
+   * @returns {Promise<Snowflake[]>}
+   */
+  async fetchMemberIds(role) {
+    const id = this.resolveId(role);
+    if (!id) throw new TypeError('INVALID_TYPE', 'role', 'RoleResolvable');
+
+    const data = await this.client.api.guilds(this.guild.id).roles(id, 'member-ids').get();
+
+    return data;
+  }
+
+  /**
+   * Data that can be resolved to a Role object. This can be:
+   * * A Role
+   * * A Snowflake
+   * @typedef {Role|Snowflake} RoleResolvable
+   */
+
+  /**
+   * Resolves a {@link RoleResolvable} to a {@link Role} object.
+   * @method resolve
+   * @memberof RoleManager
+   * @instance
+   * @param {RoleResolvable} role The role resolvable to resolve
+   * @returns {?Role}
+   */
+
+  /**
+   * Resolves a {@link RoleResolvable} to a {@link Role} id.
+   * @method resolveId
+   * @memberof RoleManager
+   * @instance
+   * @param {RoleResolvable} role The role resolvable to resolve
+   * @returns {?Snowflake}
+   */
+
+  /**
+   * @typedef {Object} RoleColorsResolvable
+   * @property {ColorResolvable} primaryColor The primary color of the role
+   * @property {ColorResolvable} [secondaryColor] The secondary color of the role.
+   * This will make the role a gradient between the other provided colors
+   * @property {ColorResolvable} [tertiaryColor] The tertiary color of the role.
+   * When sending `tertiaryColor` the API enforces the role color to be a holographic style
+   * with values of `primaryColor = 11127295`, `secondaryColor = 16759788`, and `tertiaryColor = 16761760`.
+   * These values are available as a constant: `Constants.HolographicStyle`
+   */
+
+  /**
+   * Options used to create a new role.
+   * @typedef {Object} CreateRoleOptions
+   * @property {string} [name] The name of the new role
+   * @property {ColorResolvable} [color] The data to create the role with
+   * <warn>This property is deprecated. Use `colors` instead.</warn>
+   * @property {RoleColorsResolvable} [colors] The colors to create the role with
+   * @property {boolean} [hoist] Whether or not the new role should be hoisted
+   * @property {PermissionResolvable} [permissions] The permissions for the new role
+   * @property {number} [position] The position of the new role
+   * @property {boolean} [mentionable] Whether or not the new role should be mentionable
+   * @property {?(BufferResolvable|Base64Resolvable|EmojiResolvable)} [icon] The icon for the role
+   * <warn>The `EmojiResolvable` should belong to the same guild as the role.
+   * If not, pass the emoji's URL directly</warn>
+   * @property {?string} [unicodeEmoji] The unicode emoji for the role
+   * @property {string} [reason] The reason for creating this role
+   */
+
+  /**
+   * Creates a new role in the guild with given information.
+   * <warn>The position will silently reset to 1 if an invalid one is provided, or none.</warn>
+   * @param {CreateRoleOptions} [options] Options for creating the new role
+   * @returns {Promise<Role>}
+   * @example
+   * // Create a new role
+   * guild.roles.create()
+   *   .then(console.log)
+   *   .catch(console.error);
+   * @example
+   * // Create a new role with data and a reason
+   * guild.roles.create({
+   *   name: 'Super Cool Blue People',
+   *   colors: {
+   *     primaryColor: 'BLUE',
+   *   },
+   *   reason: 'we needed a role for Super Cool People',
+   * })
+   *   .then(console.log)
+   *   .catch(console.error);
+   * @example
+   * // Create a role with holographic colors
+   * guild.roles.create({
+   *   name: 'Holographic Role',
+   *   reason: 'Creating a role with holographic effect',
+   *   colors: {
+   *     primaryColor: Constants.HolographicStyles.PRIMARY,
+   *     secondaryColor: Constants.HolographicStyles.SECONDARY,
+   *     tertiaryColor: Constants.HolographicStyles.TERTIARY,
+   *   },
+   * })
+   *   .then(console.log)
+   *   .catch(console.error);
+   */
+  async create(options = {}) {
+    let { permissions, icon } = options;
+    const { name, color, hoist, position, mentionable, reason, unicodeEmoji } = options;
+
+    if (typeof permissions !== 'undefined') permissions = new Permissions(permissions);
+    if (icon) {
+      const guildEmojiURL = this.guild.emojis.resolve(icon)?.url;
+      icon = guildEmojiURL ? await DataResolver.resolveImage(guildEmojiURL) : await DataResolver.resolveImage(icon);
+      if (typeof icon !== 'string') icon = undefined;
+    }
+
+    let colors = options.colors && {
+      primary_color: resolveColor(options.colors.primaryColor),
+      secondary_color: options.colors.secondaryColor && resolveColor(options.colors.secondaryColor),
+      tertiary_color: options.colors.tertiaryColor && resolveColor(options.colors.tertiaryColor),
+    };
+
+    if (color !== undefined) {
+      if (!deprecationEmittedForCreate) {
+        process.emitWarning(`Passing "color" to RoleManager#create() is deprecated. Use "colors" instead.`);
+      }
+
+      deprecationEmittedForCreate = true;
+
+      colors = {
+        primary_color: resolveColor(color),
+        secondary_color: null,
+        tertiary_color: null,
+      };
+    }
+
+    const data = await this.client.api.guilds(this.guild.id).roles.post({
+      data: {
+        name,
+        colors,
+        hoist,
+        permissions,
+        mentionable,
+        icon,
+        unicode_emoji: unicodeEmoji,
+      },
+      reason,
+    });
+    const { role } = this.client.actions.GuildRoleCreate.handle({
+      guild_id: this.guild.id,
+      role: data,
+    });
+    if (position) return this.setPosition(role, position, { reason });
+    return role;
+  }
+
+  /**
+   * Edits a role of the guild.
+   * @param {RoleResolvable} role The role to edit
+   * @param {RoleData} data The new data for the role
+   * @param {string} [reason] Reason for editing this role
+   * @returns {Promise<Role>}
+   * @example
+   * // Edit a role
+   * guild.roles.edit('222079219327434752', { name: 'buddies' })
+   *   .then(updated => console.log(`Edited role name to ${updated.name}`))
+   *   .catch(console.error);
+   */
+  async edit(role, data, reason) {
+    role = this.resolve(role);
+    if (!role) throw new TypeError('INVALID_TYPE', 'role', 'RoleResolvable');
+
+    if (typeof data.position === 'number') await this.setPosition(role, data.position, { reason });
+
+    let icon = data.icon;
+    if (icon) {
+      const guildEmojiURL = this.guild.emojis.resolve(icon)?.url;
+      icon = guildEmojiURL ? await DataResolver.resolveImage(guildEmojiURL) : await DataResolver.resolveImage(icon);
+      if (typeof icon !== 'string') icon = undefined;
+    }
+
+    let colors = data.colors && {
+      primary_color: resolveColor(data.colors.primaryColor),
+      secondary_color: data.colors.secondaryColor && resolveColor(data.colors.secondaryColor),
+      tertiary_color: data.colors.tertiaryColor && resolveColor(data.colors.tertiaryColor),
+    };
+
+    if (data.color !== undefined) {
+      if (!deprecationEmittedForEdit) {
+        process.emitWarning(`Passing "color" to RoleManager#edit() is deprecated. Use "colors" instead.`);
+      }
+
+      deprecationEmittedForEdit = true;
+
+      colors = {
+        primary_color: resolveColor(data.color),
+        secondary_color: null,
+        tertiary_color: null,
+      };
+    }
+
+    const _data = {
+      name: data.name,
+      colors,
+      hoist: data.hoist,
+      permissions: typeof data.permissions === 'undefined' ? undefined : new Permissions(data.permissions),
+      mentionable: data.mentionable,
+      icon,
+      unicode_emoji: data.unicodeEmoji,
+    };
+
+    const d = await this.client.api.guilds(this.guild.id).roles(role.id).patch({ data: _data, reason });
+
+    const clone = role._clone();
+    clone._patch(d);
+    return clone;
+  }
+
+  /**
+   * Deletes a role.
+   * @param {RoleResolvable} role The role to delete
+   * @param {string} [reason] Reason for deleting the role
+   * @returns {Promise<void>}
+   * @example
+   * // Delete a role
+   * guild.roles.delete('222079219327434752', 'The role needed to go')
+   *   .then(() => console.log('Deleted the role.'))
+   *   .catch(console.error);
+   */
+  async delete(role, reason) {
+    const id = this.resolveId(role);
+    await this.client.api.guilds[this.guild.id].roles[id].delete({ reason });
+    this.client.actions.GuildRoleDelete.handle({ guild_id: this.guild.id, role_id: id });
+  }
+
+  /**
+   * Sets the new position of the role.
+   * @param {RoleResolvable} role The role to change the position of
+   * @param {number} position The new position for the role
+   * @param {SetRolePositionOptions} [options] Options for setting the position
+   * @returns {Promise<Role>}
+   * @example
+   * // Set the position of the role
+   * guild.roles.setPosition('222197033908436994', 1)
+   *   .then(updated => console.log(`Role position: ${updated.position}`))
+   *   .catch(console.error);
+   */
+  async setPosition(role, position, { relative, reason } = {}) {
+    role = this.resolve(role);
+    if (!role) throw new TypeError('INVALID_TYPE', 'role', 'RoleResolvable');
+    const updatedRoles = await Util.setPosition(
+      role,
+      position,
+      relative,
+      this.guild._sortedRoles(),
+      this.client.api.guilds(this.guild.id).roles,
+      reason,
+    );
+
+    this.client.actions.GuildRolesPositionUpdate.handle({
+      guild_id: this.guild.id,
+      roles: updatedRoles,
+    });
+    return role;
+  }
+
+  /**
+   * The data needed for updating a guild role's position
+   * @typedef {Object} GuildRolePosition
+   * @property {RoleResolvable} role The role's id
+   * @property {number} position The position to update
+   */
+
+  /**
+   * Batch-updates the guild's role positions
+   * @param {GuildRolePosition[]} rolePositions Role positions to update
+   * @returns {Promise<Guild>}
+   * @example
+   * guild.roles.setPositions([{ role: roleId, position: updatedRoleIndex }])
+   *  .then(guild => console.log(`Role positions updated for ${guild}`))
+   *  .catch(console.error);
+   */
+  async setPositions(rolePositions) {
+    // Make sure rolePositions are prepared for API
+    rolePositions = rolePositions.map(o => ({
+      id: this.resolveId(o.role),
+      position: o.position,
+    }));
+
+    // Call the API to update role positions
+    await this.client.api.guilds(this.guild.id).roles.patch({
+      data: rolePositions,
+    });
+    return this.client.actions.GuildRolesPositionUpdate.handle({
+      guild_id: this.guild.id,
+      roles: rolePositions,
+    }).guild;
+  }
+
+  /**
+   * Compares the positions of two roles.
+   * @param {RoleResolvable} role1 First role to compare
+   * @param {RoleResolvable} role2 Second role to compare
+   * @returns {number} Negative number if the first role's position is lower (second role's is higher),
+   * positive number if the first's is higher (second's is lower), 0 if equal
+   */
+  comparePositions(role1, role2) {
+    const resolvedRole1 = this.resolve(role1);
+    const resolvedRole2 = this.resolve(role2);
+    if (!resolvedRole1 || !resolvedRole2) throw new TypeError('INVALID_TYPE', 'role', 'Role nor a Snowflake');
+
+    const role1Position = resolvedRole1.position;
+    const role2Position = resolvedRole2.position;
+
+    if (role1Position === role2Position) {
+      return Number(BigInt(resolvedRole2.id) - BigInt(resolvedRole1.id));
+    }
+
+    return role1Position - role2Position;
+  }
+
+  /**
+   * Gets the managed role a user created when joining the guild, if any
+   * <info>Only ever available for bots</info>
+   * @param {UserResolvable} user The user to access the bot role for
+   * @returns {?Role}
+   */
+  botRoleFor(user) {
+    const userId = this.client.users.resolveId(user);
+    if (!userId) return null;
+    return this.cache.find(role => role.tags?.botId === userId) ?? null;
+  }
+
+  /**
+   * The `@everyone` role of the guild
+   * @type {Role}
+   * @readonly
+   */
+  get everyone() {
+    return this.cache.get(this.guild.id);
+  }
+
+  /**
+   * The premium subscriber role of the guild, if any
+   * @type {?Role}
+   * @readonly
+   */
+  get premiumSubscriberRole() {
+    return this.cache.find(role => role.tags?.premiumSubscriberRole) ?? null;
+  }
+
+  /**
+   * The role with the highest position in the cache
+   * @type {Role}
+   * @readonly
+   */
+  get highest() {
+    return this.cache.reduce((prev, role) => (role.comparePositionTo(prev) > 0 ? role : prev), this.cache.first());
+  }
+}
+
+module.exports = RoleManager;

package/src/managers/SessionManager.js

@@ -0,0 +1,66 @@
+'use strict';
+
+const CachedManager = require('./CachedManager');
+const Session = require('../structures/Session');
+
+/**
+ * Manages API methods for users and stores their cache.
+ * @extends {CachedManager}
+ */
+class SessionManager extends CachedManager {
+  constructor(client, iterable) {
+    super(client, Session, iterable);
+
+    /**
+     * The current session ID hash of the client.
+     * @type {string}
+     */
+    this.currentSessionIdHash = null;
+  }
+  /**
+   * The cache of Sessions
+   * @type {Collection<string, Session>}
+   * @name SessionManager#cache
+   */
+
+  /**
+   * Fetch all sessions of the client.
+   * @returns {Promise<Collection<string, Session>>}
+   */
+  fetch() {
+    return this.client.api.auth.sessions.get().then(data => {
+      const allData = data.user_sessions;
+      this.cache.clear();
+      for (const session of allData) {
+        this._add(session, true, { id: session.id_hash });
+      }
+      return this.cache;
+    });
+  }
+
+  /**
+   * Logout all client (remote).
+   * @returns {Promise<void>}
+   */
+  logoutAllDevices() {
+    return this.client.api.auth.sessions.logout({
+      data: {
+        session_id_hashes: this.cache.map(session => session.id),
+      },
+    });
+  }
+
+  /**
+   * Get the current session of the client.
+   * You must call `fetch()` first to populate the cache.
+   * @type {?Session}
+   */
+  get currentSession() {
+    if (!this.currentSessionIdHash) {
+      return null;
+    }
+    return this.cache.get(this.currentSessionIdHash) || null;
+  }
+}
+
+module.exports = SessionManager;

package/src/managers/StageInstanceManager.js

@@ -0,0 +1,162 @@
+'use strict';
+
+const CachedManager = require('./CachedManager');
+const { TypeError, Error } = require('../errors');
+const { StageInstance } = require('../structures/StageInstance');
+const { PrivacyLevels } = require('../util/Constants');
+
+/**
+ * Manages API methods for {@link StageInstance} objects and holds their cache.
+ * @extends {CachedManager}
+ */
+class StageInstanceManager extends CachedManager {
+  constructor(guild, iterable) {
+    super(guild.client, StageInstance, iterable);
+
+    /**
+     * The guild this manager belongs to
+     * @type {Guild}
+     */
+    this.guild = guild;
+  }
+
+  /**
+   * The cache of this Manager
+   * @type {Collection<Snowflake, StageInstance>}
+   * @name StageInstanceManager#cache
+   */
+
+  /**
+   * Options used to create a stage instance.
+   * @typedef {Object} StageInstanceCreateOptions
+   * @property {string} topic The topic of the stage instance
+   * @property {PrivacyLevel|number} [privacyLevel] The privacy level of the stage instance
+   * @property {boolean} [sendStartNotification] Whether to notify `@everyone` that the stage instance has started
+   * @property {GuildScheduledEventResolvable} [guildScheduledEvent]
+   * The guild scheduled event associated with the stage instance
+   */
+
+  /**
+   * Data that can be resolved to a Stage Channel object. This can be:
+   * * A StageChannel
+   * * A Snowflake
+   * @typedef {StageChannel|Snowflake} StageChannelResolvable
+   */
+
+  /**
+   * Creates a new stage instance.
+   * @param {StageChannelResolvable} channel The stage channel to associate the created stage instance to
+   * @param {StageInstanceCreateOptions} options The options to create the stage instance
+   * @returns {Promise<StageInstance>}
+   * @example
+   * // Create a stage instance
+   * guild.stageInstances.create('1234567890123456789', {
+   *  topic: 'A very creative topic',
+   *  privacyLevel: 'GUILD_ONLY'
+   * })
+   *  .then(stageInstance => console.log(stageInstance))
+   *  .catch(console.error);
+   */
+  async create(channel, options) {
+    const channelId = this.guild.channels.resolveId(channel);
+    if (!channelId) throw new Error('STAGE_CHANNEL_RESOLVE');
+    if (typeof options !== 'object') throw new TypeError('INVALID_TYPE', 'options', 'object', true);
+    let { guildScheduledEvent, topic, privacyLevel, sendStartNotification } = options;
+
+    privacyLevel &&= typeof privacyLevel === 'number' ? privacyLevel : PrivacyLevels[privacyLevel];
+    const guildScheduledEventId = guildScheduledEvent && this.resolveId(guildScheduledEvent);
+
+    const data = await this.client.api['stage-instances'].post({
+      data: {
+        channel_id: channelId,
+        topic,
+        privacy_level: privacyLevel,
+        send_start_notification: sendStartNotification,
+        guild_scheduled_event_id: guildScheduledEventId,
+      },
+    });
+
+    return this._add(data);
+  }
+
+  /**
+   * Fetches the stage instance associated with a stage channel, if it exists.
+   * @param {StageChannelResolvable} channel The stage channel whose associated stage instance is to be fetched
+   * @param {BaseFetchOptions} [options] Additional options for this fetch
+   * @returns {Promise<StageInstance>}
+   * @example
+   * // Fetch a stage instance
+   * guild.stageInstances.fetch('1234567890123456789')
+   *  .then(stageInstance => console.log(stageInstance))
+   *  .catch(console.error);
+   */
+  async fetch(channel, { cache = true, force = false } = {}) {
+    const channelId = this.guild.channels.resolveId(channel);
+    if (!channelId) throw new Error('STAGE_CHANNEL_RESOLVE');
+
+    if (!force) {
+      const existing = this.cache.find(stageInstance => stageInstance.channelId === channelId);
+      if (existing) return existing;
+    }
+
+    const data = await this.client.api('stage-instances', channelId).get();
+    return this._add(data, cache);
+  }
+
+  /**
+   * Options used to edit an existing stage instance.
+   * @typedef {Object} StageInstanceEditOptions
+   * @property {string} [topic] The new topic of the stage instance
+   * @property {PrivacyLevel|number} [privacyLevel] The new privacy level of the stage instance
+   */
+
+  /**
+   * Edits an existing stage instance.
+   * @param {StageChannelResolvable} channel The stage channel whose associated stage instance is to be edited
+   * @param {StageInstanceEditOptions} options The options to edit the stage instance
+   * @returns {Promise<StageInstance>}
+   * @example
+   * // Edit a stage instance
+   * guild.stageInstances.edit('1234567890123456789', { topic: 'new topic' })
+   *  .then(stageInstance => console.log(stageInstance))
+   *  .catch(console.error);
+   */
+  async edit(channel, options) {
+    if (typeof options !== 'object') throw new TypeError('INVALID_TYPE', 'options', 'object', true);
+    const channelId = this.guild.channels.resolveId(channel);
+    if (!channelId) throw new Error('STAGE_CHANNEL_RESOLVE');
+
+    let { topic, privacyLevel } = options;
+
+    privacyLevel &&= typeof privacyLevel === 'number' ? privacyLevel : PrivacyLevels[privacyLevel];
+
+    const data = await this.client.api('stage-instances', channelId).patch({
+      data: {
+        topic,
+        privacy_level: privacyLevel,
+      },
+    });
+
+    if (this.cache.has(data.id)) {
+      const clone = this.cache.get(data.id)._clone();
+      clone._patch(data);
+      return clone;
+    }
+
+    return this._add(data);
+  }
+
+  /**
+   * Deletes an existing stage instance.
+   * @param {StageChannelResolvable} channel The stage channel whose associated stage instance is to be deleted
+   * @returns {Promise<void>}
+   */
+  async delete(channel) {
+    const channelId = this.guild.channels.resolveId(channel);
+    if (!channelId) throw new Error('STAGE_CHANNEL_RESOLVE');
+
+    await this.client.api('stage-instances', channelId).delete();
+  }
+}
+
+module.exports = StageInstanceManager;