From ccc70131f187f10927074590e8632a0e6815a6f3 Mon Sep 17 00:00:00 2001 From: Androz2091 Date: Mon, 23 Dec 2019 15:02:18 +0100 Subject: [PATCH] docs: Add the documentation --- .gitignore | 1 + .jsdoc.json | 32 +++++++++ README.md | 52 ++++++--------- index.d.ts | 6 +- index.js | 181 ++++++++++++++++++++++++++++++++++++++++++++++++--- package.json | 9 ++- 6 files changed, 237 insertions(+), 44 deletions(-) create mode 100644 .jsdoc.json diff --git a/.gitignore b/.gitignore index 9ebe4f1..678169f 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ node_modules bot.js package-lock.json .DS_Store +docs/* \ No newline at end of file diff --git a/.jsdoc.json b/.jsdoc.json new file mode 100644 index 0000000..460ee4b --- /dev/null +++ b/.jsdoc.json @@ -0,0 +1,32 @@ +{ + "tags": { + "allowUnknownTags": true, + "dictionaries": ["jsdoc"] + }, + "source": { + "include": ["index.js", "package.json", "README.md"], + "includePattern": ".js$", + "excludePattern": "(node_modules/|docs)" + }, + "plugins": [ + "plugins/markdown" + ], + "templates": { + "cleverLinks": false, + "monospaceLinks": true, + "useLongnameInNav": false, + "showInheritedInNav": true, + "default": { + "outputSourceFiles": false, + "includeDate": false + } + }, + "opts": { + "destination": "./docs/", + "encoding": "utf8", + "private": true, + "recurse": true, + "template": "./node_modules/minami", + "sort": false + } +} \ No newline at end of file diff --git a/README.md b/README.md index b90b158..d9952ed 100644 --- a/README.md +++ b/README.md @@ -12,13 +12,9 @@ To install this module type the following command in your console: npm i discord-anti-spam ``` -## Support Server - -Join our [Support Server](https://discord.gg/KQgDfGr) where we help you with issues regarding the module. +## Documentation -## Bug Reports - -If you have any bugs or trouble setting the module up, feel free to open an issue on [Github](https://github.com/Michael-J-Scofield/discord-anti-spam) +You can see the package documentation [**here**](https://discord-anti-spam.js.org). ## Example @@ -27,42 +23,36 @@ Example of a basic bot handling spam messages using this module. ```js const Discord = require('discord.js'); const client = new Discord.Client(); -const DiscordAntiSpam = require('discord-anti-spam'); -const AntiSpam = new DiscordAntiSpam({ +const AntiSpam = require('discord-anti-spam'); +const antiSpam = new AntiSpam({ warnThreshold: 3, // Amount of messages sent in a row that will cause a warning. + kickThreshold: 7, // Amount of messages sent in a row that will cause a ban. banThreshold: 7, // Amount of messages sent in a row that will cause a ban. maxInterval: 2000, // Amount of time (in milliseconds) in which messages are considered spam. warnMessage: '{@user}, Please stop spamming.', // Message that will be sent in chat upon warning a user. - banMessage: '**{user_tag}** has been banned for spamming.', // Message that will be sent in chat upon banning a user. + banMessage: '**{user_tag}** has been kicked for spamming.', // Message that will be sent in chat upon banning a user. + anMessage: '**{user_tag}** has been banned for spamming.', // Message that will be sent in chat upon banning a user. maxDuplicatesWarning: 7, // Amount of duplicate messages that trigger a warning. - maxDuplicatesBan: 15, // Amount of duplicate messages that trigger a ban. - deleteMessagesAfterBanForPastDays: 1, // Days of messages that get deleted upon banning a user. - exemptPermissions: [ - 'MANAGE_MESSAGES', - 'ADMINISTRATOR', - 'MANAGE_GUILD', - 'BAN_MEMBERS' - ], // Bypass users with any of these permissions. + maxDuplicatesKick: 10, // Amount of duplicate messages that trigger a warning. + maxDuplicatesBan: 12, // Amount of duplicate messages that trigger a warning. + exemptPermissions: [ 'ADMINISTRATOR'], // Bypass users with any of these permissions. ignoreBots: true, // Ignore bot messages. - verbose: false, // Extended Logs from module. + verbose: true, // Extended Logs from module. ignoredUsers: [], // Array of User IDs that get ignored. - ignoredRoles: [], // Array of Role IDs or names that are ignored. - ignoredGuilds: [], // Array of Guild IDs that are ignored. - ignoredChannels: [] // Array of channels IDs that are ignored. + // And many more options... See the documentation. }); -AntiSpam.on('warnAdd', member => console.log(`${member.user.tag} has been warned.`)); -AntiSpam.on('kickAdd', member => console.log(`${member.user.tag} has been kicked.`)); -AntiSpam.on('banAdd', member => console.log(`${member.user.tag} has been banned.`)); -AntiSpam.on('dataReset', () => console.log('Module cache has been cleared.')); -AntiSpam.on('spamThresholdBan', - (member, duplicate) => console.log(`${member.user.tag} Has reached the ban threshold for spamming!`) -); client.on('ready', () => console.log(`Logged in as ${client.user.tag}.`)); -client.on('message', msg => { - AntiSpam.message(msg); -}); +client.on('message', antiSpam.message); client.login('YOUR_SUPER_SECRET_TOKEN'); ``` + +## Support Server + +Join our [Support Server](https://discord.gg/KQgDfGr) where we help you with issues regarding the module. + +## Bug Reports + +If you have any bugs or trouble setting the module up, feel free to open an issue on [Github](https://github.com/Michael-J-Scofield/discord-anti-spam) \ No newline at end of file diff --git a/index.d.ts b/index.d.ts index 677911c..7ef8af3 100644 --- a/index.d.ts +++ b/index.d.ts @@ -12,7 +12,9 @@ import { Role } from 'discord.js'; declare module 'discord-anti-spam' { - export = class AntiSpam extends EventEmitter { + const _default: AntiSpam; + export default _default; + class AntiSpam extends EventEmitter { constructor(options?: AntiSpamOptions); public options: AntiSpamOptions; public data: AntiSpamData; @@ -36,7 +38,7 @@ declare module 'discord-anti-spam' { type: 'ban' | 'kick' ) => any ): this; - }; + } type AntiSpamData = { messageCache: { diff --git a/index.js b/index.js index 0b5639f..231a606 100644 --- a/index.js +++ b/index.js @@ -1,18 +1,54 @@ if (Number(process.version.split('.')[0].match(/[0-9]+/)) < 10) throw new Error('Node 10.0.0 or higher is required. Update Node on your system.'); -const { RichEmbed } = require('discord.js'); +const { RichEmbed, GuildMember, Message } = require('discord.js'); const { EventEmitter } = require('events'); -const defaultOptions = { + +/** + * Options for AntiSpam instance + * + * @typedef {Object} AntiSpamOptions + * + * @property {number} [warnThreshold=3] Amount of messages sent in a row that will cause a warning. + * @property {number} [kickThreshold=5] Amount of messages sent in a row that will cause a kick. + * @property {number} [warnThreshold=7] Amount of messages sent in a row that will cause a ban. + * + * @property {number} [maxInterval=2000] Amount of time (ms) in which messages are considered spam. + * + * @property {string|RichEmbed} [warnMessage='{@user}, Please stop spamming.'] Message that will be sent in chat upon warning a user. + * @property {string|RichEmbed} [kickMessage='**{user_tag}** has been kicked for spamming.'] Message that will be sent in chat upon kicking a user. + * @property {string|RichEmbed} [banMessage='**{user_tag}** has been banned for spamming.'] Message that will be sent in chat upon banning a user. + * + * @property {number} [maxDuplicatesWarning=7] Amount of duplicate messages that trigger a warning. + * @property {number} [maxDuplicatesKick=10] Amount of duplicate messages that trigger a kick. + * @property {number} [maxDuplicatesBan=10] Amount of duplicate messages that trigger a ban. + * + * @property {number} [deleteMessagesAfterBanForPastDays=1] Amount of days in which old messages will be deleted. (1-7) + * + * @property {Array} [exemptPermissions=[]] Bypass users with at least one of these permissions + * @property {boolean} [ignoreBots=true] Whether bot messages are ignored + * @property {boolean} [verbose=false] Extended Logs from module (recommended) + * + * @property {Array|function} [ignoredUsers=[]] Array of string user IDs that are ignored + * @property {Array|function} [ignoredRoles=[]] Array of string role IDs or role name that are ignored + * @property {Array|function} [ignoredGuilds=[]] Array of string Guild IDs that are ignored + * @property {Array|function} [ignoredChannels=[]] Array of string channels IDs that are ignored + * + * @property {boolean} [warnEnabled=true] If false, the bot won't warn users + * @property {boolean} [kickEnabled=true] If false, the bot won't kick users + * @property {boolean} [banEnabled=true] If false, the bot won't ban users + * + */ +const clientOptions = { warnThreshold: 3, - banThreshold: 5, kickThreshold: 5, + banThreshold: 7, maxInterval: 2000, warnMessage: '{@user}, Please stop spamming.', - banMessage: '**{user_tag}** has been banned for spamming.', kickMessage: '**{user_tag}** has been kicked for spamming.', + banMessage: '**{user_tag}** has been banned for spamming.', maxDuplicatesWarning: 7, - maxDuplicatesBan: 10, maxDuplicatesKick: 10, + maxDuplicatesBan: 10, deleteMessagesAfterBanForPastDays: 1, exemptPermissions: [], ignoreBots: true, @@ -25,16 +61,56 @@ const defaultOptions = { kickEnabled: true, banEnabled: true }; + +/** + * Cache data for the Anti Spam instance. + * @typedef {object} AntiSpamData + * + * @property {Array} messageCache Array which contains the message cache + * @property {Array} users Array which contains the dates on which each user's message was sent + * + * @property {Array} warnedUsers Array of warned users + * @property {Array} kickedUsers Array of kicked users + * @property {Array} bannedUsers Array of banned users + * + */ + +/** + * Anti Spam instance. + * + * @param {AntiSpamOptions} [options] Client options. + * + * @property {AntiSpamData} data Anti Spam cache data. + * + * @example + * const antiSpam = new AntiSpam({ + * warnThreshold: 3, // Amount of messages sent in a row that will cause a warning. + * banThreshold: 7, // Amount of messages sent in a row that will cause a ban. + * maxInterval: 2000, // Amount of time (in ms) in which messages are cosidered spam. + * warnMessage: "{@user}, Please stop spamming.", // Message will be sent in chat upon warning. + * banMessage: "**{user_tag}** has been banned for spamming.", // Message will be sent in chat upon banning. + * maxDuplicatesWarning: 7, // Amount of same messages sent that will be considered as duplicates that will cause a warning. + * maxDuplicatesBan: 15, // Amount of same messages sent that will be considered as duplicates that will cause a ban. + * deleteMessagesAfterBanForPastDays: 1, // Amount of days in which old messages will be deleted. (1-7) + * exemptPermissions: ["MANAGE_MESSAGES", "ADMINISTRATOR", "MANAGE_GUILD", "BAN_MEMBERS"], // Bypass users with at least one of these permissions + * ignoreBots: true, // Ignore bot messages. + * verbose: false, // Extended Logs from module. + * ignoredUsers: [], // Array of string user IDs that are ignored. + * ignoredRoles: [], // Array of string role IDs or role name that are ignored. + * ignoredGuilds: [], // Array of string Guild IDs that are ignored. + * ignoredChannels: [] // Array of string channels IDs that are ignored. + * }); + */ class AntiSpam extends EventEmitter { constructor(options = {}) { super(); - for (const key in defaultOptions) { + for (const key in clientOptions) { if ( !options.hasOwnProperty(key) || typeof options[key] === 'undefined' || options[key] === null ) - options[key] = defaultOptions[key]; + options[key] = clientOptions[key]; } this.options = options; this.data = { @@ -46,6 +122,18 @@ class AntiSpam extends EventEmitter { }; } + /** + * Checks a message. + * + * @param {Message} message The message to check. + * + * @returns {boolean} Whether the message has triggered a threshold. + * + * @example + * client.on('message', (msg) => { + * antiSpam.message(msg); + * }); + */ async message(message) { if ( message.channel.type === 'dm' || @@ -222,16 +310,91 @@ class AntiSpam extends EventEmitter { return false; } + /** + * Resets the cache data of the Anti Spam instance. + * @private + * + * @returns {AntiSpamData} The cache that was just cleared. + * + * @example + * antiSpam.resetData().then((data) => { + * console.log("Cleared a total of "+data.messageCache+" cached messages."); + * }); + */ resetData() { + let data = this.data; this.data.messageCache = []; this.data.bannedUsers = []; this.data.kickedUsers = []; this.data.warnedUsers = []; this.data.users = []; - return this.data; + return data; } } +/** + * Emitted when a member is warned. + * @event AntiSpam#warnAdd + * + * @param {GuildMember} member The warned member. + * + * @example + * antiSpam.on("warnAdd", (member) => console.log(`${member.user.tag} has been warned.`)); + */ + +/** + * Emitted when a member is kicked. + * @event AntiSpam#kickAdd + * + * @param {GuildMember} member The kicked member. + * + * @example + * antiSpam.on("kickAdd", (member) => console.log(`${member.user.tag} has been kicked.`)); + */ + +/** + * Emitted when a member is banned. + * @event AntiSpam#banAdd + * + * @param {GuildMember} member The banned member. + * + * @example + * antiSpam.on("banAdd", (member) => console.log(`${member.user.tag} has been banned.`)); + */ + +/** + * Emitted when a member reaches the warn threshold. + * @event AntiSpam#spamThresholdWarn + * + * @param {GuildMember} member The member who reached the warn threshold. + * @param {boolean} duplicate Whether the member reached the warn threshold by spamming the same message. + * + * @example + * antiSpam.on("spamThresholdWarn", (member) => console.log(`${member.user.tag} has reached the warn threshold.`)); + */ + +/** + * Emitted when a member reaches the kick threshold. + * @event AntiSpam#spamThresholdKick + * + * @param {GuildMember} member The member who reached the kick threshold. + * @param {boolean} duplicate Whether the member reached the kick threshold by spamming the same message. + * + * @example + * antiSpam.on("spamThresholdKick", (member) => console.log(`${member.user.tag} has reached the kick threshold.`)); + */ + +/** + * Emitted when a member reaches the ban threshold. + * @event AntiSpam#spamThresholdBan + * + * @param {GuildMember} member The member who reached the ban threshold. + * @param {boolean} duplicate Whether the member reached the ban threshold by spamming the same message. + * + * @example + * antiSpam.on("spamThresholdBan", (member) => console.log(`${member.user.tag} has reached the ban threshold.`)); + */ + module.exports = AntiSpam; /** @@ -252,4 +415,4 @@ function format(string, message) { if (embed.footer && embed.footer.text) embed.footer.text = format(embed.footer.text, message); if (embed.author && embed.author.name) embed.author.name = format(embed.author.name, message); return embed; -} +} \ No newline at end of file diff --git a/package.json b/package.json index c270455..9d432b5 100644 --- a/package.json +++ b/package.json @@ -1,10 +1,11 @@ { "name": "discord-anti-spam", - "version": "2.1.1", + "version": "2.2.1", "description": "An easy to setup package that help you integration of anti-spam feature in your discord bot.", "main": "index.js", "scripts": { - "test": "echo \"Error: no test specified\" && exit 1" + "test": "echo \"Error: no test specified\" && exit 1", + "generate-docs": "node_modules/.bin/jsdoc --configure .jsdoc.json --verbose" }, "keywords": [ "discord", @@ -29,5 +30,9 @@ "license": "MIT", "dependencies": { "discord.js": "^11.5.1" + }, + "devDependencies": { + "jsdoc": "^3.6.3", + "minami": "^1.2.3" } }