@ovencord/discord.js 14.16.3

package/src/managers/DataManager.ts

@@ -0,0 +1,38 @@
+
+import { DiscordjsError, ErrorCodes  } from '../errors/index.js';
+import { BaseManager  } from './BaseManager.js';
+
+/**
+ * Manages the API methods of a data model along with a collection of instances.
+ *
+ * @extends {BaseManager}
+ * @abstract
+ */
+export abstract class DataManager extends BaseManager {
+  public holds: any;
+
+  constructor(client: any, holds: any) {
+    super(client);
+    this.holds = holds;
+  }
+
+  get cache(): any {
+    throw new DiscordjsError(ErrorCodes.NotImplemented, 'get cache', this.constructor.name);
+  }
+
+  resolve(idOrInstance: any): any {
+    if (idOrInstance instanceof this.holds) return idOrInstance;
+    if (typeof idOrInstance === 'string') return this.cache.get(idOrInstance) ?? null;
+    return null;
+  }
+
+  resolveId(idOrInstance: any): any {
+    if (idOrInstance instanceof this.holds) return (idOrInstance as any).id;
+    if (typeof idOrInstance === 'string') return idOrInstance;
+    return null;
+  }
+
+  override valueOf(): any {
+    return this.cache;
+  }
+}

package/src/managers/EntitlementManager.ts

@@ -0,0 +1,182 @@
+import { Collection  } from '@ovencord/collection';
+import { makeURLSearchParams  } from '@ovencord/rest';
+import { Routes, EntitlementOwnerType  } from 'discord-api-types/v10';
+import { ErrorCodes, DiscordjsTypeError  } from '../errors/index.js';
+import { Entitlement  } from '../structures/Entitlement.js';
+import { resolveSKUId  } from '../util/Util.js';
+import { CachedManager  } from './CachedManager.js';
+
+/**
+ * Manages API methods for entitlements and stores their cache.
+ *
+ * @extends {CachedManager}
+ */
+export class EntitlementManager extends CachedManager {
+  public client: any;
+  constructor(client, iterable) {
+    super(client, Entitlement, iterable);
+  }
+
+  /**
+   * The cache of this manager
+   *
+   * @type {Collection<Snowflake, Entitlement>}
+   * @name EntitlementManager#cache
+   */
+
+  /**
+   * Data that resolves to give an Entitlement object. This can be:
+   * - An Entitlement object
+   * - A Snowflake
+   *
+   * @typedef {Entitlement|Snowflake} EntitlementResolvable
+   */
+
+  /**
+   * Data that resolves to give a SKU object. This can be:
+   * - A SKU object
+   * - A Snowflake
+   *
+   * @typedef {SKU|Snowflake} SKUResolvable
+   */
+
+  /**
+   * Options used to fetch an entitlement
+   *
+   * @typedef {BaseFetchOptions} FetchEntitlementOptions
+   * @property {EntitlementResolvable} entitlement The entitlement to fetch
+   */
+
+  /**
+   * Options used to fetch entitlements
+   *
+   * @typedef {Object} FetchEntitlementsOptions
+   * @property {number} [limit] The maximum number of entitlements to fetch
+   * @property {GuildResolvable} [guild] The guild to fetch entitlements for
+   * @property {UserResolvable} [user] The user to fetch entitlements for
+   * @property {SKUResolvable[]} [skus] The SKUs to fetch entitlements for
+   * @property {boolean} [excludeEnded] Whether to exclude ended entitlements
+   * @property {boolean} [excludeDeleted] Whether to exclude deleted entitlements
+   * @property {boolean} [cache=true] Whether to cache the fetched entitlements
+   * @property {Snowflake} [before] Consider only entitlements before this entitlement id
+   * @property {Snowflake} [after] Consider only entitlements after this entitlement id
+   * <warn>If both `before` and `after` are provided, only `before` is respected</warn>
+   */
+
+  /**
+   * Fetches entitlements for this application
+   *
+   * @param {EntitlementResolvable|FetchEntitlementOptions|FetchEntitlementsOptions} [options]
+   * Options for fetching the entitlements
+   * @returns {Promise<Entitlement|Collection<Snowflake, Entitlement>>}
+   */
+  async fetch(options) {
+    if (!options) return this._fetchMany(options);
+    const { entitlement, cache, force } = options;
+    const resolvedEntitlement = this.resolveId(entitlement ?? options);
+
+    if (resolvedEntitlement) {
+      return this._fetchSingle({ entitlement: resolvedEntitlement, cache, force });
+    }
+
+    return this._fetchMany(options);
+  }
+
+  async _fetchSingle({ entitlement, cache, force = false }) {
+    if (!force) {
+      const existing = this.cache.get(entitlement);
+
+      if (existing) {
+        return existing;
+      }
+    }
+
+    const data = await this.client.rest.get(Routes.entitlement(this.client.application.id, entitlement));
+    return this._add(data, cache);
+  }
+
+  async _fetchMany({ limit, guild, user, skus, excludeEnded, excludeDeleted, cache, before, after } = {}) {
+    const query = makeURLSearchParams({
+      limit,
+      guild_id: guild && this.client.guilds.resolveId(guild),
+      user_id: user && this.client.users.resolveId(user),
+      sku_ids: skus?.map(sku => resolveSKUId(sku)).join(','),
+      exclude_ended: excludeEnded,
+      exclude_deleted: excludeDeleted,
+      before,
+      after,
+    });
+
+    const entitlements = await this.client.rest.get(Routes.entitlements(this.client.application.id), { query });
+
+    return entitlements.reduce(
+      (coll, entitlement) => coll.set(entitlement.id, this._add(entitlement, cache)),
+      new Collection(),
+    );
+  }
+
+  /**
+   * Options used to create a test entitlement
+   * <info>Either `guild` or `user` must be provided, but not both</info>
+   *
+   * @typedef {Object} EntitlementCreateOptions
+   * @property {SKUResolvable} sku The id of the SKU to create the entitlement for
+   * @property {GuildResolvable} [guild] The guild to create the entitlement for
+   * @property {UserResolvable} [user] The user to create the entitlement for
+   */
+
+  /**
+   * Creates a test entitlement
+   *
+   * @param {EntitlementCreateOptions} options Options for creating the test entitlement
+   * @returns {Promise<Entitlement>}
+   */
+  async createTest({ sku, guild, user }) {
+    const skuId = resolveSKUId(sku);
+    if (!skuId) throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'sku', 'SKUResolvable');
+
+    if ((guild && user) || (!guild && !user)) {
+      throw new DiscordjsTypeError(ErrorCodes.EntitlementCreateInvalidOwner);
+    }
+
+    const resolved = guild ? this.client.guilds.resolveId(guild) : this.client.users.resolveId(user);
+    if (!resolved) {
+      const name = guild ? 'guild' : 'user';
+      const type = guild ? 'GuildResolvable' : 'UserResolvable';
+      throw new DiscordjsTypeError(ErrorCodes.InvalidType, name, type);
+    }
+
+    const entitlement = await this.client.rest.post(Routes.entitlements(this.client.application.id), {
+      body: {
+        sku_id: skuId,
+        owner_id: resolved,
+        owner_type: guild ? EntitlementOwnerType.Guild : EntitlementOwnerType.User,
+      },
+    });
+    return new Entitlement(this.client, entitlement);
+  }
+
+  /**
+   * Deletes a test entitlement
+   *
+   * @param {EntitlementResolvable} entitlement The entitlement to delete
+   * @returns {Promise<void>}
+   */
+  async deleteTest(entitlement) {
+    const resolved = this.resolveId(entitlement);
+    if (!resolved) throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'entitlement', 'EntitlementResolvable');
+
+    await this.client.rest.delete(Routes.entitlement(this.client.application.id, resolved));
+  }
+
+  /**
+   * Marks an entitlement as consumed
+   * <info>Only available for One-Time Purchase consumable SKUs.</info>
+   *
+   * @param {Snowflake} entitlementId The id of the entitlement to consume
+   * @returns {Promise<void>}
+   */
+  async consume(entitlementId) {
+    await this.client.rest.post(Routes.consumeEntitlement(this.client.application.id, entitlementId));
+  }
+}

package/src/managers/GuildApplicationCommandManager.ts

@@ -0,0 +1,29 @@
+import { ApplicationCommandManager  } from './ApplicationCommandManager.js';
+import { ApplicationCommandPermissionsManager  } from './ApplicationCommandPermissionsManager.js';
+
+/**
+ * An extension for guild-specific application commands.
+ *
+ * @extends {ApplicationCommandManager}
+ */
+export class GuildApplicationCommandManager extends ApplicationCommandManager {
+  public guild: any;
+  public permissions: any;
+  constructor(guild, iterable) {
+    super(guild.client, iterable);
+
+    /**
+     * The guild that this manager belongs to
+     *
+     * @type {Guild}
+     */
+    this.guild = guild;
+
+    /**
+     * The manager for permissions of arbitrary commands on this guild
+     *
+     * @type {ApplicationCommandPermissionsManager}
+     */
+    this.permissions = new ApplicationCommandPermissionsManager(this);
+  }
+}

package/src/managers/GuildBanManager.ts

@@ -0,0 +1,221 @@
+import { Collection  } from '@ovencord/collection';
+import { makeURLSearchParams  } from '@ovencord/rest';
+import { Routes  } from 'discord-api-types/v10';
+import { DiscordjsTypeError, DiscordjsError, ErrorCodes  } from '../errors/index.js';
+import { GuildBan  } from '../structures/GuildBan.js';
+import { CachedManager  } from './CachedManager.js';
+
+/**
+ * Manages API methods for guild bans and stores their cache.
+ *
+ * @extends {CachedManager}
+ */
+export class GuildBanManager extends CachedManager {
+  public guild: any;
+  constructor(guild, iterable) {
+    super(guild.client, GuildBan, iterable);
+
+    /**
+     * The guild this Manager belongs to
+     *
+     * @type {Guild}
+     */
+    this.guild = guild;
+  }
+
+  /**
+   * The cache of this Manager
+   *
+   * @type {Collection<Snowflake, GuildBan>}
+   * @name GuildBanManager#cache
+   */
+
+  _add(data, cache) {
+    return super._add(data, cache, { id: data.user.id, extras: [this.guild] });
+  }
+
+  /**
+   * Data that resolves to give a GuildBan object. This can be:
+   * - A GuildBan object
+   * - A User resolvable
+   *
+   * @typedef {GuildBan|UserResolvable} GuildBanResolvable
+   */
+
+  /**
+   * Resolves a GuildBanResolvable to a GuildBan object.
+   *
+   * @param {GuildBanResolvable} ban The ban that is in the guild
+   * @returns {?GuildBan}
+   */
+  resolve(ban) {
+    return super.resolve(ban) ?? super.resolve(this.client.users.resolveId(ban));
+  }
+
+  /**
+   * Options used to fetch a single ban from a guild.
+   *
+   * @typedef {BaseFetchOptions} FetchBanOptions
+   * @property {UserResolvable} user The ban to fetch
+   */
+
+  /**
+   * Options used to fetch multiple bans from a guild.
+   *
+   * @typedef {Object} FetchBansOptions
+   * @property {number} [limit] The maximum number of bans to return
+   * @property {Snowflake} [before] Consider only bans before this id
+   * @property {Snowflake} [after] Consider only bans after this id
+   * @property {boolean} [cache] Whether to cache the fetched bans
+   */
+
+  /**
+   * Fetches ban(s) from Discord.
+   *
+   * @param {UserResolvable|FetchBanOptions|FetchBansOptions} [options] Options for fetching guild ban(s)
+   * @returns {Promise<GuildBan|Collection<Snowflake, GuildBan>>}
+   * @example
+   * // Fetch multiple bans from a guild
+   * guild.bans.fetch()
+   *   .then(console.log)
+   *   .catch(console.error);
+   * @example
+   * // Fetch a maximum of 5 bans from a guild without caching
+   * guild.bans.fetch({ limit: 5, cache: false })
+   *   .then(console.log)
+   *   .catch(console.error);
+   * @example
+   * // Fetch a single ban
+   * guild.bans.fetch('351871113346809860')
+   *   .then(console.log)
+   *   .catch(console.error);
+   * @example
+   * // Fetch a single ban without checking cache
+   * guild.bans.fetch({ user, force: true })
+   *   .then(console.log)
+   *   .catch(console.error)
+   * @example
+   * // Fetch a single ban without caching
+   * guild.bans.fetch({ user, cache: false })
+   *   .then(console.log)
+   *   .catch(console.error);
+   */
+  async fetch(options) {
+    if (!options) return this._fetchMany();
+    const { user, cache, force, limit, before, after } = options;
+    const resolvedUser = this.client.users.resolveId(user ?? options);
+    if (resolvedUser) return this._fetchSingle({ user: resolvedUser, cache, force });
+
+    if (!before && !after && !limit && cache === undefined) {
+      throw new DiscordjsError(ErrorCodes.FetchBanResolveId);
+    }
+
+    return this._fetchMany(options);
+  }
+
+  async _fetchSingle({ user, cache, force = false }) {
+    if (!force) {
+      const existing = this.cache.get(user);
+      if (existing && !existing.partial) return existing;
+    }
+
+    const data = await this.client.rest.get(Routes.guildBan(this.guild.id, user));
+    return this._add(data, cache);
+  }
+
+  async _fetchMany({ cache, ...apiOptions } = {}) {
+    const data = await this.client.rest.get(Routes.guildBans(this.guild.id), {
+      query: makeURLSearchParams(apiOptions),
+    });
+
+    return data.reduce((col, ban) => col.set(ban.user.id, this._add(ban, cache)), new Collection());
+  }
+
+  /**
+   * Options used to ban a user from a guild.
+   *
+   * @typedef {Object} BanOptions
+   * @property {number} [deleteMessageSeconds] Number of seconds of messages to delete,
+   * must be between 0 and 604800 (7 days), inclusive
+   * @property {string} [reason] The reason for the ban
+   */
+
+  /**
+   * Bans a user from the guild.
+   *
+   * @param {UserResolvable} user The user to ban
+   * @param {BanOptions} [options={}] Options for the ban
+   * @returns {Promise<void>}
+   * @example
+   * // Ban a user by id (or with a user/guild member object)
+   * await guild.bans.create('84484653687267328');
+   */
+  async create(user, options = {}) {
+    if (typeof options !== 'object') throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'options', 'object', true);
+    const id = this.client.users.resolveId(user);
+    if (!id) throw new DiscordjsError(ErrorCodes.BanResolveId, true);
+
+    await this.client.rest.put(Routes.guildBan(this.guild.id, id), {
+      body: {
+        delete_message_seconds: options.deleteMessageSeconds,
+      },
+      reason: options.reason,
+    });
+  }
+
+  /**
+   * Unbans a user from the guild.
+   *
+   * @param {UserResolvable} user The user to unban
+   * @param {string} [reason] Reason for unbanning user
+   * @returns {Promise<void>}
+   * @example
+   * // Unban a user by id (or with a user/guild member object)
+   * await guild.bans.remove('84484653687267328');
+   */
+  async remove(user, reason) {
+    const id = this.client.users.resolveId(user);
+    if (!id) throw new DiscordjsError(ErrorCodes.BanResolveId);
+    await this.client.rest.delete(Routes.guildBan(this.guild.id, id), { reason });
+  }
+
+  /**
+   * Result of bulk banning users from a guild.
+   *
+   * @typedef {Object} BulkBanResult
+   * @property {Snowflake[]} bannedUsers IDs of the banned users
+   * @property {Snowflake[]} failedUsers IDs of the users that could not be banned or were already banned
+   */
+
+  /**
+   * Bulk ban users from a guild, and optionally delete previous messages sent by them.
+   *
+   * @param {Collection<Snowflake, UserResolvable>|UserResolvable[]} users The users to ban
+   * @param {BanOptions} [options] The options for bulk banning users
+   * @returns {Promise<BulkBanResult>} Returns an object with `bannedUsers` key containing the IDs of the banned users
+   * and the key `failedUsers` with the IDs that could not be banned or were already banned.
+   * @example
+   * // Bulk ban users by ids (or with user/guild member objects) and delete all their messages from the past 7 days
+   * guild.bans.bulkCreate(['84484653687267328'], { deleteMessageSeconds: 7 * 24 * 60 * 60 })
+   *   .then(result => {
+   *     console.log(`Banned ${result.bannedUsers.length} users, failed to ban ${result.failedUsers.length} users.`)
+   *   })
+   *   .catch(console.error);
+   */
+  async bulkCreate(users, options = {}) {
+    if (!users || !(Array.isArray(users) || users instanceof Collection)) {
+      throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'users', 'Array or Collection of UserResolvable', true);
+    }
+
+    if (typeof options !== 'object') throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'options', 'object', true);
+
+    const userIds = users.map(user => this.client.users.resolveId(user));
+    if (userIds.length === 0) throw new DiscordjsError(ErrorCodes.BulkBanUsersOptionEmpty);
+
+    const result = await this.client.rest.post(Routes.guildBulkBan(this.guild.id), {
+      body: { delete_message_seconds: options.deleteMessageSeconds, user_ids: userIds },
+      reason: options.reason,
+    });
+    return { bannedUsers: result.banned_users, failedUsers: result.failed_users };
+  }
+}