@velliajs/discord 1.0.0

package/src/structures/ApplicationRoleConnectionMetadata.js

@@ -0,0 +1,46 @@
+'use strict';
+
+/**
+ * Role connection metadata object for an application.
+ */
+class ApplicationRoleConnectionMetadata {
+  constructor(data) {
+    /**
+     * The name of this metadata field
+     * @type {string}
+     */
+    this.name = data.name;
+
+    /**
+     * The name localizations for this metadata field
+     * @type {?Object<Locale, string>}
+     */
+    this.nameLocalizations = data.name_localizations ?? null;
+
+    /**
+     * The description of this metadata field
+     * @type {string}
+     */
+    this.description = data.description;
+
+    /**
+     * The description localizations for this metadata field
+     * @type {?Object<Locale, string>}
+     */
+    this.descriptionLocalizations = data.description_localizations ?? null;
+
+    /**
+     * The dictionary key for this metadata field
+     * @type {string}
+     */
+    this.key = data.key;
+
+    /**
+     * The type of this metadata field
+     * @type {ApplicationRoleConnectionMetadataType}
+     */
+    this.type = data.type;
+  }
+}
+
+exports.ApplicationRoleConnectionMetadata = ApplicationRoleConnectionMetadata;

package/src/structures/Attachment.js

@@ -0,0 +1,140 @@
+'use strict';
+
+const { basename, flatten } = require('../util/Util');
+
+/**
+ * @typedef {Object} AttachmentPayload
+ * @property {?string} name The name of the attachment
+ * @property {Stream|BufferResolvable} attachment The attachment in this payload
+ * @property {?string} description The description of the attachment
+ */
+
+/**
+ * Represents an attachment
+ */
+class Attachment {
+  constructor(data) {
+    this.attachment = data.url;
+    /**
+     * The name of this attachment
+     * @type {string}
+     */
+    this.name = data.filename;
+    this._patch(data);
+  }
+
+  _patch(data) {
+    /**
+     * The attachment's id
+     * @type {Snowflake}
+     */
+    this.id = data.id;
+
+    if ('size' in data) {
+      /**
+       * The size of this attachment in bytes
+       * @type {number}
+       */
+      this.size = data.size;
+    }
+
+    if ('url' in data) {
+      /**
+       * The URL to this attachment
+       * @type {string}
+       */
+      this.url = data.url;
+    }
+
+    if ('proxy_url' in data) {
+      /**
+       * The Proxy URL to this attachment
+       * @type {string}
+       */
+      this.proxyURL = data.proxy_url;
+    }
+
+    if ('height' in data) {
+      /**
+       * The height of this attachment (if an image or video)
+       * @type {?number}
+       */
+      this.height = data.height;
+    } else {
+      this.height ??= null;
+    }
+
+    if ('width' in data) {
+      /**
+       * The width of this attachment (if an image or video)
+       * @type {?number}
+       */
+      this.width = data.width;
+    } else {
+      this.width ??= null;
+    }
+
+    if ('content_type' in data) {
+      /**
+       * The media type of this attachment
+       * @type {?string}
+       */
+      this.contentType = data.content_type;
+    } else {
+      this.contentType ??= null;
+    }
+
+    if ('description' in data) {
+      /**
+       * The description (alt text) of this attachment
+       * @type {?string}
+       */
+      this.description = data.description;
+    } else {
+      this.description ??= null;
+    }
+
+    /**
+     * Whether this attachment is ephemeral
+     * @type {boolean}
+     */
+    this.ephemeral = data.ephemeral ?? false;
+
+    if ('duration_secs' in data) {
+      /**
+       * The duration of this attachment in seconds
+       * <info>This will only be available if the attachment is an audio file.</info>
+       * @type {?number}
+       */
+      this.duration = data.duration_secs;
+    } else {
+      this.duration ??= null;
+    }
+
+    if ('waveform' in data) {
+      /**
+       * The base64 encoded byte array representing a sampled waveform
+       * <info>This will only be available if the attachment is an audio file.</info>
+       * @type {?string}
+       */
+      this.waveform = data.waveform;
+    } else {
+      this.waveform ??= null;
+    }
+  }
+
+  /**
+   * Whether or not this attachment has been marked as a spoiler
+   * @type {boolean}
+   * @readonly
+   */
+  get spoiler() {
+    return basename(this.url ?? this.name).startsWith('SPOILER_');
+  }
+
+  toJSON() {
+    return flatten(this);
+  }
+}
+
+module.exports = Attachment;

package/src/structures/AttachmentBuilder.js

@@ -0,0 +1,116 @@
+'use strict';
+
+const { basename, flatten } = require('../util/Util');
+
+/**
+ * Represents an attachment builder
+ */
+class AttachmentBuilder {
+  /**
+   * @param {BufferResolvable|Stream} attachment The file
+   * @param {AttachmentData} [data] Extra data
+   */
+  constructor(attachment, data = {}) {
+    /**
+     * The file associated with this attachment.
+     * @type {BufferResolvable|Stream}
+     */
+    this.attachment = attachment;
+    /**
+     * The name of this attachment
+     * @type {?string}
+     */
+    this.name = data.name;
+    /**
+     * The description of the attachment
+     * @type {?string}
+     */
+    this.description = data.description;
+  }
+
+  /**
+   * Sets the description of this attachment.
+   * @param {string} description The description of the file
+   * @returns {AttachmentBuilder} This attachment
+   */
+  setDescription(description) {
+    this.description = description;
+    return this;
+  }
+
+  /**
+   * Sets the file of this attachment.
+   * @param {BufferResolvable|Stream} attachment The file
+   * @returns {AttachmentBuilder} This attachment
+   */
+  setFile(attachment) {
+    this.attachment = attachment;
+    return this;
+  }
+
+  /**
+   * Sets the name of this attachment.
+   * @param {string} name The name of the file
+   * @returns {AttachmentBuilder} This attachment
+   */
+  setName(name) {
+    this.name = name;
+    return this;
+  }
+
+  /**
+   * Sets whether this attachment is a spoiler
+   * @param {boolean} [spoiler=true] Whether the attachment should be marked as a spoiler
+   * @returns {AttachmentBuilder} This attachment
+   */
+  setSpoiler(spoiler = true) {
+    if (spoiler === this.spoiler) return this;
+
+    if (!spoiler) {
+      while (this.spoiler) {
+        this.name = this.name.slice('SPOILER_'.length);
+      }
+      return this;
+    }
+    this.name = `SPOILER_${this.name}`;
+    return this;
+  }
+
+  /**
+   * Whether or not this attachment has been marked as a spoiler
+   * @type {boolean}
+   * @readonly
+   */
+  get spoiler() {
+    return basename(this.name).startsWith('SPOILER_');
+  }
+
+  toJSON() {
+    return flatten(this);
+  }
+
+  /**
+   * Makes a new builder instance from a preexisting attachment structure.
+   * @param {AttachmentBuilder|Attachment|AttachmentPayload} other The builder to construct a new instance from
+   * @returns {AttachmentBuilder}
+   */
+  static from(other) {
+    return new AttachmentBuilder(other.attachment, {
+      name: other.name,
+      description: other.description,
+    });
+  }
+}
+
+module.exports = AttachmentBuilder;
+
+/**
+ * @external APIAttachment
+ * @see {@link https://discord.com/developers/docs/resources/channel#attachment-object}
+ */
+
+/**
+ * @typedef {Object} AttachmentData
+ * @property {string} [name] The name of the attachment
+ * @property {string} [description] The description of the attachment
+ */

package/src/structures/AutoModerationActionExecution.js

@@ -0,0 +1,116 @@
+'use strict';
+
+const { _transformAPIAutoModerationAction } = require('../util/Transformers');
+
+/**
+ * Represents the structure of an executed action when an {@link AutoModerationRule} is triggered.
+ */
+class AutoModerationActionExecution {
+  constructor(data, guild) {
+    /**
+     * The guild where this action was executed from.
+     * @type {Guild}
+     */
+    this.guild = guild;
+
+    /**
+     * The action that was executed.
+     * @type {AutoModerationAction}
+     */
+    this.action = _transformAPIAutoModerationAction(data.action);
+
+    /**
+     * The id of the auto moderation rule this action belongs to.
+     * @type {Snowflake}
+     */
+    this.ruleId = data.rule_id;
+
+    /**
+     * The trigger type of the auto moderation rule which was triggered.
+     * @type {AutoModerationRuleTriggerType}
+     */
+    this.ruleTriggerType = data.rule_trigger_type;
+
+    /**
+     * The id of the user that triggered this action.
+     * @type {Snowflake}
+     */
+    this.userId = data.user_id;
+
+    /**
+     * The id of the channel where this action was triggered from.
+     * @type {?Snowflake}
+     */
+    this.channelId = data.channel_id ?? null;
+
+    /**
+     * The id of the message that triggered this action.
+     * <info>This will not be present if the message was blocked or the content was not part of any message.</info>
+     * @type {?Snowflake}
+     */
+    this.messageId = data.message_id ?? null;
+
+    /**
+     * The id of any system auto moderation messages posted as a result of this action.
+     * @type {?Snowflake}
+     */
+    this.alertSystemMessageId = data.alert_system_message_id ?? null;
+
+    /**
+     * The content that triggered this action.
+     * <info>This property requires the {@link GatewayIntentBits.MessageContent} privileged gateway intent.</info>
+     * @type {string}
+     */
+    this.content = data.content;
+
+    /**
+     * The word or phrase configured in the rule that triggered this action.
+     * @type {?string}
+     */
+    this.matchedKeyword = data.matched_keyword ?? null;
+
+    /**
+     * The substring in content that triggered this action.
+     * @type {?string}
+     */
+    this.matchedContent = data.matched_content ?? null;
+  }
+
+  /**
+   * The auto moderation rule this action belongs to.
+   * @type {?AutoModerationRule}
+   * @readonly
+   */
+  get autoModerationRule() {
+    return this.guild.autoModerationRules.cache.get(this.ruleId) ?? null;
+  }
+
+  /**
+   * The channel where this action was triggered from.
+   * @type {?TextBasedChannel}
+   * @readonly
+   */
+  get channel() {
+    return this.guild.channels.cache.get(this.channelId) ?? null;
+  }
+
+  /**
+   * The user that triggered this action.
+   * @type {?User}
+   * @readonly
+   */
+  get user() {
+    return this.guild.client.users.cache.get(this.userId) ?? null;
+  }
+
+  /**
+   * The guild member that triggered this action.
+   * @type {?GuildMember}
+   * @readonly
+   */
+  get member() {
+    return this.guild.members.cache.get(this.userId) ?? null;
+  }
+}
+
+module.exports = AutoModerationActionExecution;

package/src/structures/AutoModerationRule.js

@@ -0,0 +1,284 @@
+'use strict';
+
+const { Collection } = require('@discordjs/collection');
+const Base = require('./Base');
+const { _transformAPIAutoModerationAction } = require('../util/Transformers');
+
+/**
+ * Represents an auto moderation rule.
+ * @extends {Base}
+ */
+class AutoModerationRule extends Base {
+  constructor(client, data, guild) {
+    super(client);
+
+    /**
+     * The id of this auto moderation rule.
+     * @type {Snowflake}
+     */
+    this.id = data.id;
+
+    /**
+     * The guild this auto moderation rule is for.
+     * @type {Guild}
+     */
+    this.guild = guild;
+
+    /**
+     * The user that created this auto moderation rule.
+     * @type {Snowflake}
+     */
+    this.creatorId = data.creator_id;
+
+    /**
+     * The trigger type of this auto moderation rule.
+     * @type {AutoModerationRuleTriggerType}
+     */
+    this.triggerType = data.trigger_type;
+
+    this._patch(data);
+  }
+
+  _patch(data) {
+    if ('name' in data) {
+      /**
+       * The name of this auto moderation rule.
+       * @type {string}
+       */
+      this.name = data.name;
+    }
+
+    if ('event_type' in data) {
+      /**
+       * The event type of this auto moderation rule.
+       * @type {AutoModerationRuleEventType}
+       */
+      this.eventType = data.event_type;
+    }
+
+    if ('trigger_metadata' in data) {
+      /**
+       * Additional data used to determine whether an auto moderation rule should be triggered.
+       * @typedef {Object} AutoModerationTriggerMetadata
+       * @property {string[]} keywordFilter The substrings that will be searched for in the content
+       * @property {string[]} regexPatterns The regular expression patterns which will be matched against the content
+       * <info>Only Rust-flavored regular expressions are supported.</info>
+       * @property {AutoModerationRuleKeywordPresetType[]} presets
+       * The internally pre-defined wordsets which will be searched for in the content
+       * @property {string[]} allowList The substrings that will be exempt from triggering
+       * {@link AutoModerationRuleTriggerType.Keyword} and {@link AutoModerationRuleTriggerType.KeywordPreset}
+       * @property {?number} mentionTotalLimit The total number of role & user mentions allowed per message
+       * @property {boolean} mentionRaidProtectionEnabled Whether mention raid protection is enabled
+       */
+
+      /**
+       * The trigger metadata of the rule.
+       * @type {AutoModerationTriggerMetadata}
+       */
+      this.triggerMetadata = {
+        keywordFilter: data.trigger_metadata.keyword_filter ?? [],
+        regexPatterns: data.trigger_metadata.regex_patterns ?? [],
+        presets: data.trigger_metadata.presets ?? [],
+        allowList: data.trigger_metadata.allow_list ?? [],
+        mentionTotalLimit: data.trigger_metadata.mention_total_limit ?? null,
+        mentionRaidProtectionEnabled: data.trigger_metadata.mention_raid_protection_enabled ?? false,
+      };
+    }
+
+    if ('actions' in data) {
+      /**
+       * An object containing information about an auto moderation rule action.
+       * @typedef {Object} AutoModerationAction
+       * @property {AutoModerationActionType} type The type of this auto moderation rule action
+       * @property {AutoModerationActionMetadata} metadata Additional metadata needed during execution
+       */
+
+      /**
+       * Additional data used when an auto moderation rule is executed.
+       * @typedef {Object} AutoModerationActionMetadata
+       * @property {?Snowflake} channelId The id of the channel to which content will be logged
+       * @property {?number} durationSeconds The timeout duration in seconds
+       * @property {?string} customMessage The custom message that is shown whenever a message is blocked
+       */
+
+      /**
+       * The actions of this auto moderation rule.
+       * @type {AutoModerationAction[]}
+       */
+      this.actions = data.actions.map(action => _transformAPIAutoModerationAction(action));
+    }
+
+    if ('enabled' in data) {
+      /**
+       * Whether this auto moderation rule is enabled.
+       * @type {boolean}
+       */
+      this.enabled = data.enabled;
+    }
+
+    if ('exempt_roles' in data) {
+      /**
+       * The roles exempt by this auto moderation rule.
+       * @type {Collection<Snowflake, Role>}
+       */
+      this.exemptRoles = new Collection(
+        data.exempt_roles.map(exemptRole => [exemptRole, this.guild.roles.cache.get(exemptRole)]),
+      );
+    }
+
+    if ('exempt_channels' in data) {
+      /**
+       * The channels exempt by this auto moderation rule.
+       * @type {Collection<Snowflake, GuildChannel|ThreadChannel>}
+       */
+      this.exemptChannels = new Collection(
+        data.exempt_channels.map(exemptChannel => [exemptChannel, this.guild.channels.cache.get(exemptChannel)]),
+      );
+    }
+  }
+
+  /**
+   * Edits this auto moderation rule.
+   * @param {AutoModerationRuleEditOptions} options Options for editing this auto moderation rule
+   * @returns {Promise<AutoModerationRule>}
+   */
+  edit(options) {
+    return this.guild.autoModerationRules.edit(this.id, options);
+  }
+
+  /**
+   * Deletes this auto moderation rule.
+   * @param {string} [reason] The reason for deleting this auto moderation rule
+   * @returns {Promise<void>}
+   */
+  delete(reason) {
+    return this.guild.autoModerationRules.delete(this.id, reason);
+  }
+
+  /**
+   * Sets the name for this auto moderation rule.
+   * @param {string} name The name of this auto moderation rule
+   * @param {string} [reason] The reason for changing the name of this auto moderation rule
+   * @returns {Promise<AutoModerationRule>}
+   */
+  setName(name, reason) {
+    return this.edit({ name, reason });
+  }
+
+  /**
+   * Sets the event type for this auto moderation rule.
+   * @param {AutoModerationRuleEventType} eventType The event type of this auto moderation rule
+   * @param {string} [reason] The reason for changing the event type of this auto moderation rule
+   * @returns {Promise<AutoModerationRule>}
+   */
+  setEventType(eventType, reason) {
+    return this.edit({ eventType, reason });
+  }
+
+  /**
+   * Sets the keyword filter for this auto moderation rule.
+   * @param {string[]} keywordFilter The keyword filter of this auto moderation rule
+   * @param {string} [reason] The reason for changing the keyword filter of this auto moderation rule
+   * @returns {Promise<AutoModerationRule>}
+   */
+  setKeywordFilter(keywordFilter, reason) {
+    return this.edit({ triggerMetadata: { ...this.triggerMetadata, keywordFilter }, reason });
+  }
+
+  /**
+   * Sets the regular expression patterns for this auto moderation rule.
+   * @param {string[]} regexPatterns The regular expression patterns of this auto moderation rule
+   * <info>Only Rust-flavored regular expressions are supported.</info>
+   * @param {string} [reason] The reason for changing the regular expression patterns of this auto moderation rule
+   * @returns {Promise<AutoModerationRule>}
+   */
+  setRegexPatterns(regexPatterns, reason) {
+    return this.edit({ triggerMetadata: { ...this.triggerMetadata, regexPatterns }, reason });
+  }
+
+  /**
+   * Sets the presets for this auto moderation rule.
+   * @param {AutoModerationRuleKeywordPresetType[]} presets The presets of this auto moderation rule
+   * @param {string} [reason] The reason for changing the presets of this auto moderation rule
+   * @returns {Promise<AutoModerationRule>}
+   */
+  setPresets(presets, reason) {
+    return this.edit({ triggerMetadata: { ...this.triggerMetadata, presets }, reason });
+  }
+
+  /**
+   * Sets the allow list for this auto moderation rule.
+   * @param {string[]} allowList The substrings that will be exempt from triggering
+   * {@link AutoModerationRuleTriggerType.Keyword} and {@link AutoModerationRuleTriggerType.KeywordPreset}
+   * @param {string} [reason] The reason for changing the allow list of this auto moderation rule
+   * @returns {Promise<AutoModerationRule>}
+   */
+  setAllowList(allowList, reason) {
+    return this.edit({ triggerMetadata: { ...this.triggerMetadata, allowList }, reason });
+  }
+
+  /**
+   * Sets the mention total limit for this auto moderation rule.
+   * @param {number} mentionTotalLimit The total number of unique role and user mentions allowed per message
+   * @param {string} [reason] The reason for changing the mention total limit of this auto moderation rule
+   * @returns {Promise<AutoModerationRule>}
+   */
+  setMentionTotalLimit(mentionTotalLimit, reason) {
+    return this.edit({ triggerMetadata: { ...this.triggerMetadata, mentionTotalLimit }, reason });
+  }
+
+  /**
+   * Sets whether to enable mention raid protection for this auto moderation rule.
+   * @param {boolean} mentionRaidProtectionEnabled
+   * Whether to enable mention raid protection for this auto moderation rule
+   * @param {string} [reason] The reason for changing the mention raid protection of this auto moderation rule
+   * @returns {Promise<AutoModerationRule>}
+   */
+  setMentionRaidProtectionEnabled(mentionRaidProtectionEnabled, reason) {
+    return this.edit({ triggerMetadata: { ...this.triggerMetadata, mentionRaidProtectionEnabled }, reason });
+  }
+
+  /**
+   * Sets the actions for this auto moderation rule.
+   * @param {AutoModerationActionOptions[]} actions The actions of this auto moderation rule
+   * @param {string} [reason] The reason for changing the actions of this auto moderation rule
+   * @returns {Promise<AutoModerationRule>}
+   */
+  setActions(actions, reason) {
+    return this.edit({ actions, reason });
+  }
+
+  /**
+   * Sets whether this auto moderation rule should be enabled.
+   * @param {boolean} [enabled=true] Whether to enable this auto moderation rule
+   * @param {string} [reason] The reason for enabling or disabling this auto moderation rule
+   * @returns {Promise<AutoModerationRule>}
+   */
+  setEnabled(enabled = true, reason) {
+    return this.edit({ enabled, reason });
+  }
+
+  /**
+   * Sets the exempt roles for this auto moderation rule.
+   * @param {Collection<Snowflake, Role>|RoleResolvable[]} [exemptRoles]
+   * The roles that should not be affected by the auto moderation rule
+   * @param {string} [reason] The reason for changing the exempt roles of this auto moderation rule
+   * @returns {Promise<AutoModerationRule>}
+   */
+  setExemptRoles(exemptRoles, reason) {
+    return this.edit({ exemptRoles, reason });
+  }
+
+  /**
+   * Sets the exempt channels for this auto moderation rule.
+   * @param {Collection<Snowflake, GuildChannel|ThreadChannel>|GuildChannelResolvable[]} [exemptChannels]
+   * The channels that should not be affected by the auto moderation rule
+   * @param {string} [reason] The reason for changing the exempt channels of this auto moderation rule
+   * @returns {Promise<AutoModerationRule>}
+   */
+  setExemptChannels(exemptChannels, reason) {
+    return this.edit({ exemptChannels, reason });
+  }
+}
+
+module.exports = AutoModerationRule;