@ovencord/discord.js 14.16.3

package/src/managers/StageInstanceManager.ts

@@ -0,0 +1,166 @@
+import { Routes  } from 'discord-api-types/v10';
+import { DiscordjsTypeError, DiscordjsError, ErrorCodes  } from '../errors/index.js';
+import { StageInstance  } from '../structures/StageInstance.js';
+import { CachedManager  } from './CachedManager.js';
+
+/**
+ * Manages API methods for {@link StageInstance} objects and holds their cache.
+ *
+ * @extends {CachedManager}
+ */
+export class StageInstanceManager extends CachedManager {
+  public guild: any;
+  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 {StageInstancePrivacyLevel} [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: GuildPrivacyLevel.GuildOnly
+   * })
+   *  .then(stageInstance => console.log(stageInstance))
+   *  .catch(console.error);
+   */
+  async create(channel, options) {
+    const channelId = this.guild.channels.resolveId(channel);
+    if (!channelId) throw new DiscordjsError(ErrorCodes.StageChannelResolve);
+    if (typeof options !== 'object') throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'options', 'object', true);
+    const { guildScheduledEvent, topic, privacyLevel, sendStartNotification } = options;
+
+    const guildScheduledEventId = guildScheduledEvent && this.resolveId(guildScheduledEvent);
+
+    const data = await this.client.rest.post(Routes.stageInstances(), {
+      body: {
+        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 DiscordjsError(ErrorCodes.StageChannelResolve);
+
+    if (!force) {
+      const existing = this.cache.find(stageInstance => stageInstance.channelId === channelId);
+      if (existing) return existing;
+    }
+
+    const data = await this.client.rest.get(Routes.stageInstance(channelId));
+    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 {StageInstancePrivacyLevel} [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 DiscordjsTypeError(ErrorCodes.InvalidType, 'options', 'object', true);
+    const channelId = this.guild.channels.resolveId(channel);
+    if (!channelId) throw new DiscordjsError(ErrorCodes.StageChannelResolve);
+
+    const { topic, privacyLevel } = options;
+
+    const data = await this.client.rest.patch(Routes.stageInstance(channelId), {
+      body: {
+        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 DiscordjsError(ErrorCodes.StageChannelResolve);
+
+    await this.client.rest.delete(Routes.stageInstance(channelId));
+  }
+}

package/src/managers/SubscriptionManager.ts

@@ -0,0 +1,83 @@
+import { Collection  } from '@ovencord/collection';
+import { makeURLSearchParams  } from '@ovencord/rest';
+import { Routes  } from 'discord-api-types/v10';
+import { DiscordjsTypeError, ErrorCodes  } from '../errors/index.js';
+import { Subscription  } from '../structures/Subscription.js';
+import { resolveSKUId  } from '../util/Util.js';
+import { CachedManager  } from './CachedManager.js';
+
+/**
+ * Manages API methods for subscriptions and stores their cache.
+ *
+ * @extends {CachedManager}
+ */
+export class SubscriptionManager extends CachedManager {
+  public client: any;
+  constructor(client, iterable) {
+    super(client, Subscription, iterable);
+  }
+
+  /**
+   * The cache of this manager
+   *
+   * @type {Collection<Snowflake, Subscription>}
+   * @name SubscriptionManager#cache
+   */
+
+  /**
+   * Options used to fetch a subscription
+   *
+   * @typedef {BaseFetchOptions} FetchSubscriptionOptions
+   * @property {SKUResolvable} sku The SKU to fetch the subscription for
+   * @property {Snowflake} subscriptionId The id of the subscription to fetch
+   */
+
+  /**
+   * Options used to fetch subscriptions
+   *
+   * @typedef {Object} FetchSubscriptionsOptions
+   * @property {Snowflake} [after] Consider only subscriptions after this subscription id
+   * @property {Snowflake} [before] Consider only subscriptions before this subscription id
+   * @property {number} [limit] The maximum number of subscriptions to fetch
+   * @property {SKUResolvable} sku The SKU to fetch subscriptions for
+   * @property {UserResolvable} user The user to fetch entitlements for
+   * <warn>If both `before` and `after` are provided, only `before` is respected</warn>
+   */
+
+  /**
+   * Fetches subscriptions for this application
+   *
+   * @param {FetchSubscriptionOptions|FetchSubscriptionsOptions} [options={}] Options for fetching the subscriptions
+   * @returns {Promise<Subscription|Collection<Snowflake, Subscription>>}
+   */
+  async fetch(options = {}) {
+    if (typeof options !== 'object') throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'options', 'object', true);
+
+    const { after, before, cache, limit, sku, subscriptionId, user } = options;
+
+    const skuId = resolveSKUId(sku);
+
+    if (!skuId) throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'sku', 'SKUResolvable');
+
+    if (subscriptionId) {
+      const subscription = await this.client.rest.get(Routes.skuSubscription(skuId, subscriptionId));
+
+      return this._add(subscription, cache);
+    }
+
+    const query = makeURLSearchParams({
+      limit,
+      user_id: this.client.users.resolveId(user) ?? undefined,
+      sku_id: skuId,
+      before,
+      after,
+    });
+
+    const subscriptions = await this.client.rest.get(Routes.skuSubscriptions(skuId), { query });
+
+    return subscriptions.reduce(
+      (coll, subscription) => coll.set(subscription.id, this._add(subscription, cache)),
+      new Collection(),
+    );
+  }
+}

package/src/managers/ThreadManager.ts

@@ -0,0 +1,210 @@
+import { Collection  } from '@ovencord/collection';
+import { makeURLSearchParams  } from '@ovencord/rest';
+import { Routes  } from 'discord-api-types/v10';
+import { DiscordjsTypeError, ErrorCodes  } from '../errors/index.js';
+import { ThreadChannel  } from '../structures/ThreadChannel.js';
+import { MakeCacheOverrideSymbol  } from '../util/Symbols.js';
+import { CachedManager  } from './CachedManager.js';
+
+/**
+ * Manages API methods for thread-based channels and stores their cache.
+ *
+ * @extends {CachedManager}
+ */
+export class ThreadManager extends CachedManager {
+  public channel: any;
+  static [MakeCacheOverrideSymbol] = ThreadManager;
+
+  constructor(channel, iterable) {
+    super(channel.client, ThreadChannel, iterable);
+
+    /**
+     * The channel this Manager belongs to
+     *
+     * @type {TextChannel|AnnouncementChannel|ForumChannel|MediaChannel}
+     */
+    this.channel = channel;
+  }
+
+  /**
+   * Data that can be resolved to a Thread Channel object. This can be:
+   * - A ThreadChannel object
+   * - A Snowflake
+   *
+   * @typedef {ThreadChannel|Snowflake} ThreadChannelResolvable
+   */
+
+  /**
+   * The cache of this Manager
+   *
+   * @type {Collection<Snowflake, ThreadChannel>}
+   * @name ThreadManager#cache
+   */
+
+  _add(thread) {
+    const existing = this.cache.get(thread.id);
+    if (existing) return existing;
+    this.cache.set(thread.id, thread);
+    return thread;
+  }
+
+  /**
+   * Resolves a {@link ThreadChannelResolvable} to a {@link ThreadChannel} object.
+   *
+   * @method resolve
+   * @memberof ThreadManager
+   * @instance
+   * @param {ThreadChannelResolvable} thread The ThreadChannel resolvable to resolve
+   * @returns {?ThreadChannel}
+   */
+
+  /**
+   * Resolves a {@link ThreadChannelResolvable} to a {@link ThreadChannel} id.
+   *
+   * @method resolveId
+   * @memberof ThreadManager
+   * @instance
+   * @param {ThreadChannelResolvable} thread The ThreadChannel resolvable to resolve
+   * @returns {?Snowflake}
+   */
+
+  /**
+   * Options for fetching multiple threads.
+   *
+   * @typedef {Object} FetchThreadsOptions
+   * @property {FetchArchivedThreadOptions} [archived] Options used to fetch archived threads
+   */
+
+  /**
+   * Obtains a thread from Discord, or the channel cache if it's already available.
+   *
+   * @param {ThreadChannelResolvable|FetchThreadsOptions} [options] The options to fetch threads. If it is a
+   * ThreadChannelResolvable then the specified thread will be fetched. Fetches all active threads if `undefined`
+   * @param {BaseFetchOptions} [cacheOptions] Additional options for this fetch. <warn>The `force` field gets ignored
+   * if `options` is not a {@link ThreadChannelResolvable}</warn>
+   * @returns {Promise<?(ThreadChannel|FetchedThreads|FetchedThreadsMore)>}
+   * {@link FetchedThreads} if active & {@link FetchedThreadsMore} if archived.
+   * @example
+   * // Fetch a thread by its id
+   * channel.threads.fetch('831955138126104859')
+   *   .then(channel => console.log(channel.name))
+   *   .catch(console.error);
+   */
+  async fetch(options, { cache, force } = {}) {
+    if (!options) return this.fetchActive(cache);
+    const channel = this.client.channels.resolveId(options);
+    if (channel) {
+      const threadChannel = await this.client.channels.fetch(channel, { cache, force });
+      if (threadChannel.parentId !== this.channel.id) throw new DiscordjsTypeError(ErrorCodes.NotAThreadOfParent);
+      return threadChannel;
+    }
+
+    if (options.archived) {
+      return this.fetchArchived(options.archived, cache);
+    }
+
+    return this.fetchActive(cache);
+  }
+
+  /**
+   * Data that can be resolved to a Date object. This can be:
+   * - A Date object
+   * - A number representing a timestamp
+   * - An {@link https://en.wikipedia.org/wiki/ISO_8601 ISO 8601} string
+   *
+   * @typedef {Date|number|string} DateResolvable
+   */
+
+  /**
+   * The options used to fetch archived threads.
+   *
+   * @typedef {Object} FetchArchivedThreadOptions
+   * @property {string} [type='public'] The type of threads to fetch (`public` or `private`)
+   * @property {boolean} [fetchAll=false] Whether to fetch **all** archived threads when `type` is `private`
+   * <info>This property requires the {@link PermissionFlagsBits.ManageThreads} permission if `true`.</info>
+   * @property {DateResolvable|ThreadChannelResolvable} [before] Only return threads that were archived before this Date
+   * or Snowflake
+   * <warn>Must be a {@link ThreadChannelResolvable} when `type` is `private` and `fetchAll` is `false`.</warn>
+   * @property {number} [limit] Maximum number of threads to return
+   */
+
+  /**
+   * Data returned from fetching multiple threads.
+   *
+   * @typedef {FetchedThreads} FetchedThreadsMore
+   * @property {?boolean} hasMore Whether there are potentially additional threads that require a subsequent call
+   */
+
+  /**
+   * Obtains a set of archived threads from Discord.
+   * <info>This method requires the {@link PermissionFlagsBits.ReadMessageHistory} permission
+   * in the parent channel.</info>
+   *
+   * @param {FetchArchivedThreadOptions} [options] The options to fetch archived threads
+   * @param {boolean} [cache=true] Whether to cache the new thread objects if they aren't already
+   * @returns {Promise<FetchedThreadsMore>}
+   */
+  async fetchArchived({ type = 'public', fetchAll = false, before, limit } = {}, cache = true) {
+    let path = Routes.channelThreads(this.channel.id, type);
+    if (type === 'private' && !fetchAll) {
+      path = Routes.channelJoinedArchivedThreads(this.channel.id);
+    }
+
+    let timestamp;
+    let id;
+    const query = makeURLSearchParams({ limit });
+    if (before !== undefined) {
+      if (before instanceof ThreadChannel || /^\d{17,19}$/.test(String(before))) {
+        id = this.resolveId(before);
+        timestamp = this.resolve(before)?.archivedAt?.toISOString();
+        const toUse = type === 'private' && !fetchAll ? id : timestamp;
+        if (toUse) {
+          query.set('before', toUse);
+        }
+      } else {
+        try {
+          timestamp = new Date(before).toISOString();
+          if (type === 'public' || fetchAll) {
+            query.set('before', timestamp);
+          }
+        } catch {
+          throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'before', 'DateResolvable or ThreadChannelResolvable');
+        }
+      }
+    }
+
+    const raw = await this.client.rest.get(path, { query });
+    return this.constructor._mapThreads(raw, this.client, { parent: this.channel, cache });
+  }
+
+  /**
+   * Obtains all active threads in the channel.
+   *
+   * @param {boolean} [cache=true] Whether to cache the fetched data
+   * @returns {Promise<FetchedThreads>}
+   */
+  async fetchActive(cache = true) {
+    const data = await this.channel.guild.channels.rawFetchGuildActiveThreads();
+    return this.constructor._mapThreads(data, this.client, { parent: this.channel, cache });
+  }
+
+  static _mapThreads(rawThreads, client, { parent, guild, cache }) {
+    const threads = rawThreads.threads.reduce((coll, raw) => {
+      const thread = client.channels._add(raw, guild ?? parent?.guild, { cache });
+      if (parent && thread.parentId !== parent.id) return coll;
+      return coll.set(thread.id, thread);
+    }, new Collection());
+
+    // Discord sends the thread id as id in this object
+    const threadMembers = rawThreads.members.reduce((coll, raw) => {
+      const thread = threads.get(raw.id);
+      return thread ? coll.set(raw.user_id, thread.members._add(raw)) : coll;
+    }, new Collection());
+
+    const response = { threads, members: threadMembers };
+
+    // The GET `/guilds/{guild.id}/threads/active` route does not return `has_more`.
+    if ('has_more' in rawThreads) response.hasMore = rawThreads.has_more;
+    return response;
+  }
+}

package/src/managers/ThreadMemberManager.ts

@@ -0,0 +1,194 @@
+import { Collection  } from '@ovencord/collection';
+import { makeURLSearchParams  } from '@ovencord/rest';
+import { Routes  } from 'discord-api-types/v10';
+import { DiscordjsTypeError, ErrorCodes  } from '../errors/index.js';
+import { ThreadMember  } from '../structures/ThreadMember.js';
+import { CachedManager  } from './CachedManager.js';
+
+/**
+ * Manages API methods for GuildMembers and stores their cache.
+ *
+ * @extends {CachedManager}
+ */
+export class ThreadMemberManager extends CachedManager {
+  public thread: any;
+  constructor(thread, iterable) {
+    super(thread.client, ThreadMember, iterable);
+
+    /**
+     * The thread this manager belongs to
+     *
+     * @type {ThreadChannel}
+     */
+    this.thread = thread;
+  }
+
+  /**
+   * The cache of this Manager
+   *
+   * @type {Collection<Snowflake, ThreadMember>}
+   * @name ThreadMemberManager#cache
+   */
+
+  _add(data, cache = true) {
+    const existing = this.cache.get(data.user_id);
+    if (cache) existing?._patch(data, { cache });
+    if (existing) return existing;
+
+    const member = new ThreadMember(this.thread, data, { cache });
+    if (cache) this.cache.set(data.user_id, member);
+    return member;
+  }
+
+  /**
+   * Fetches the client user as a ThreadMember of the thread.
+   *
+   * @param {BaseFetchOptions} [options] The options for fetching the member
+   * @returns {Promise<ThreadMember>}
+   */
+  async fetchMe(options) {
+    return this.fetch({ ...options, member: this.client.user.id });
+  }
+
+  /**
+   * The client user as a ThreadMember of this ThreadChannel
+   *
+   * @type {?ThreadMember}
+   * @readonly
+   */
+  get me() {
+    return this.cache.get(this.client.user.id) ?? null;
+  }
+
+  /**
+   * Data that resolves to give a ThreadMember object. This can be:
+   * - A ThreadMember object
+   * - A User resolvable
+   *
+   * @typedef {ThreadMember|UserResolvable} ThreadMemberResolvable
+   */
+
+  /**
+   * Resolves a {@link ThreadMemberResolvable} to a {@link ThreadMember} object.
+   *
+   * @param {ThreadMemberResolvable} member The user that is part of the thread
+   * @returns {?GuildMember}
+   */
+  resolve(member) {
+    const memberResolvable = super.resolve(member);
+    if (memberResolvable) return memberResolvable;
+    const userId = this.client.users.resolveId(member);
+    if (userId) return super.cache.get(userId) ?? null;
+    return null;
+  }
+
+  /**
+   * Resolves a {@link ThreadMemberResolvable} to a {@link ThreadMember} id string.
+   *
+   * @param {ThreadMemberResolvable} member The user that is part of the guild
+   * @returns {?Snowflake}
+   */
+  resolveId(member) {
+    const memberResolvable = super.resolveId(member);
+    if (memberResolvable) return memberResolvable;
+    const userResolvable = this.client.users.resolveId(member);
+    return this.cache.has(userResolvable) ? userResolvable : null;
+  }
+
+  /**
+   * Adds a member to the thread.
+   *
+   * @param {UserResolvable|'@me'} member The member to add
+   * @returns {Promise<Snowflake>}
+   */
+  async add(member) {
+    const id = member === '@me' ? member : this.client.users.resolveId(member);
+    if (!id) throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'member', 'UserResolvable');
+    await this.client.rest.put(Routes.threadMembers(this.thread.id, id));
+    return id;
+  }
+
+  /**
+   * Remove a user from the thread.
+   *
+   * @param {UserResolvable|'@me'} member The member to remove
+   * @returns {Promise<Snowflake>}
+   */
+  async remove(member) {
+    const id = member === '@me' ? member : this.client.users.resolveId(member);
+    if (!id) throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'member', 'UserResolvable');
+    await this.client.rest.delete(Routes.threadMembers(this.thread.id, id));
+    return id;
+  }
+
+  /**
+   * Options used to fetch a thread member.
+   *
+   * @typedef {BaseFetchOptions} FetchThreadMemberOptions
+   * @property {ThreadMemberResolvable} member The thread member to fetch
+   * @property {boolean} [withMember] Whether to also return the guild member associated with this thread member
+   */
+
+  /**
+   * Options used to fetch multiple thread members with guild member data.
+   * <info>With `withMember` set to `true`, pagination is enabled.</info>
+   *
+   * @typedef {Object} FetchThreadMembersWithGuildMemberDataOptions
+   * @property {true} withMember Whether to also return the guild member data
+   * @property {Snowflake} [after] Consider only thread members after this id
+   * @property {number} [limit] The maximum number of thread members to return
+   * @property {boolean} [cache] Whether to cache the fetched thread members and guild members
+   */
+
+  /**
+   * Options used to fetch multiple thread members without guild member data.
+   *
+   * @typedef {Object} FetchThreadMembersWithoutGuildMemberDataOptions
+   * @property {false} [withMember] Whether to also return the guild member data
+   * @property {boolean} [cache] Whether to cache the fetched thread members
+   */
+
+  /**
+   * Options used to fetch multiple thread members.
+   *
+   * @typedef {FetchThreadMembersWithGuildMemberDataOptions|
+   * FetchThreadMembersWithoutGuildMemberDataOptions} FetchThreadMembersOptions
+   */
+
+  /**
+   * Fetches thread member(s) from Discord.
+   * <info>This method requires the {@link GatewayIntentBits.GuildMembers} privileged gateway intent.</info>
+   *
+   * @param {ThreadMemberResolvable|FetchThreadMemberOptions|FetchThreadMembersOptions} [options]
+   * Options for fetching thread member(s)
+   * @returns {Promise<ThreadMember|Collection<Snowflake, ThreadMember>>}
+   */
+  async fetch(options) {
+    if (!options) return this._fetchMany();
+    const { member, withMember, cache, force } = options;
+    const resolvedMember = this.resolveId(member ?? options);
+    if (resolvedMember) return this._fetchSingle({ member: resolvedMember, withMember, cache, force });
+    return this._fetchMany(options);
+  }
+
+  async _fetchSingle({ member, withMember, cache, force = false }) {
+    if (!force) {
+      const existing = this.cache.get(member);
+      if (existing) return existing;
+    }
+
+    const data = await this.client.rest.get(Routes.threadMembers(this.thread.id, member), {
+      query: makeURLSearchParams({ with_member: withMember }),
+    });
+
+    return this._add(data, cache);
+  }
+
+  async _fetchMany({ withMember, after, limit, cache } = {}) {
+    const data = await this.client.rest.get(Routes.threadMembers(this.thread.id), {
+      query: makeURLSearchParams({ with_member: withMember, after, limit }),
+    });
+
+    return data.reduce((col, member) => col.set(member.user_id, this._add(member, cache)), new Collection());
+  }
+}