adb-plugin-moderation 1.0.0

package/README.md

@@ -0,0 +1,110 @@
+# adb-plugin-moderation
+
+Core moderation commands for [Advanced Discord Bot](https://github.com/dead/Advanced-Discord-Bot).
+
+## What it does
+
+- **Actions**: ban, unban, kick, timeout, untimeout, warn
+- **Records**: case log, per-member warning history, moderator notes
+- **Queries**: case lookup, user history, modstats (monthly breakdown)
+- **Utilities**: purge messages, slowmode, lock/unlock channels
+- **Tickets**: setup category/role, open/close/add/remove users
+
+All actions create a numbered case and optionally post an embed to a log channel. Warnings can trigger automatic escalation (timeout → kick → ban) at configurable thresholds.
+
+## Requirements
+
+- Node.js 18+
+- Advanced Discord Bot with plugin loader
+- MongoDB (via ADB's mongoose connection)
+- Discord bot with these permissions:
+  - Ban Members
+  - Kick Members
+  - Moderate Members (timeout)
+  - Manage Messages (warn, purge, note)
+  - Manage Channels (slowmode, lock, ticket channels)
+  - Manage Guild (clearwarnings, modstats, ticket setup)
+
+## Installation
+
+Inside your bot directory:
+
+```bash
+npm install adb-plugin-moderation
+```
+
+Then add the plugin to your ADB config:
+
+```json
+{
+  "plugins": ["adb-plugin-moderation"]
+}
+```
+
+Restart the bot. The plugin registers slash commands on load — deploy them to Discord:
+
+```bash
+node deploy-commands.js
+```
+
+## Configuration
+
+Run `/ticket setup` in your server to configure tickets. All other settings go in the ADB plugin config UI or directly via the database.
+
+| Key | Default | Description |
+|---|---|---|
+| `log_channel_id` | null | Channel to post case embeds |
+| `ticket_category_id` | null | Category for ticket channels |
+| `ticket_support_role_id` | null | Role pinged when a ticket opens |
+| `ticket_log_channel_id` | null | Channel for ticket transcripts on close |
+| `dm_on_action` | true | DM users when actioned |
+| `warn_thresholds` | see below | Auto-escalation on warning count |
+
+### Default warn thresholds
+
+```json
+{
+  "3":  { "action": "timeout", "duration": "1h" },
+  "5":  { "action": "timeout", "duration": "24h" },
+  "7":  { "action": "kick" },
+  "10": { "action": "ban" }
+}
+```
+
+## Commands
+
+| Command | Permission | Description |
+|---|---|---|
+| `/ban` | Ban Members | Ban a user |
+| `/unban` | Ban Members | Unban by user ID |
+| `/kick` | Kick Members | Kick a member |
+| `/timeout` | Moderate Members | Timeout (1m–28d) |
+| `/untimeout` | Moderate Members | Remove timeout |
+| `/warn` | Manage Messages | Issue a warning |
+| `/warnings` | Manage Messages | View warnings for a user |
+| `/clearwarnings` | Manage Guild | Clear all warnings |
+| `/note` | Manage Messages | Add a private mod note |
+| `/purge` | Manage Messages | Bulk-delete messages |
+| `/slowmode` | Manage Channels | Set channel slowmode |
+| `/lock` | Manage Channels | Prevent @everyone from sending |
+| `/unlock` | Manage Channels | Restore @everyone send permission |
+| `/case` | Manage Messages | Look up a case by number |
+| `/history` | Manage Messages | View a user's case history |
+| `/modstats` | Manage Guild | View a moderator's monthly stats |
+| `/ticket setup` | Manage Guild | Configure the ticket system |
+| `/ticket open` | Everyone | Open a support ticket |
+| `/ticket close` | Manage Channels | Close and archive a ticket |
+| `/ticket add` | Manage Channels | Add a user to a ticket |
+| `/ticket remove` | Manage Channels | Remove a user from a ticket |
+
+## Testing
+
+```bash
+npm test
+```
+
+Runs the local harness — no Discord or MongoDB connection required.
+
+## License
+
+MIT

package/commands/ban.js

@@ -0,0 +1,90 @@
+"use strict";
+
+const { EmbedBuilder, PermissionFlagsBits } = require("discord.js");
+const { requirePerms } = require("../lib/permissions");
+const { dmActionUser } = require("../lib/dmUser");
+const { createCase, postCaseLog } = require("../lib/logCase");
+
+module.exports = {
+  data: {
+    name: "ban",
+    description: "Ban a member from the server",
+    options: [
+      { type: 6, name: "user", description: "The user to ban", required: true },
+      { type: 3, name: "reason", description: "Reason for the ban", required: false },
+      {
+        type: 4,
+        name: "days",
+        description: "Days of messages to delete (0-7)",
+        required: false,
+        min_value: 0,
+        max_value: 7,
+      },
+    ],
+  },
+
+  async execute(interaction, ctx) {
+    if (!requirePerms(interaction, PermissionFlagsBits.BanMembers)) return;
+
+    const targetUser = interaction.options.getUser("user");
+    const reason = interaction.options.getString("reason") || "No reason provided";
+    const days = interaction.options.getInteger("days") ?? 0;
+    const guildId = interaction.guild.id;
+
+    const CaseModel = ctx.models.Case;
+    const configData = (await ctx.db.getPluginConfig(guildId, "adb-plugin-moderation"))?.data || {};
+
+    let member;
+    try {
+      member = await interaction.guild.members.fetch(targetUser.id);
+    } catch {
+      // User not in guild — still attempt ban
+    }
+
+    if (member && !member.bannable) {
+      const embed = new EmbedBuilder()
+        .setColor(0xe74c3c)
+        .setDescription("I cannot ban that member (insufficient role hierarchy).");
+      return interaction.reply({ embeds: [embed], ephemeral: true });
+    }
+
+    if (configData.dm_on_action !== false) {
+      await dmActionUser(ctx.client, targetUser.id, {
+        action: "banned",
+        guildName: interaction.guild.name,
+        reason,
+      });
+    }
+
+    try {
+      await interaction.guild.members.ban(targetUser.id, {
+        reason,
+        deleteMessageSeconds: days * 86400,
+      });
+    } catch (err) {
+      const embed = new EmbedBuilder().setColor(0xe74c3c).setDescription(`Failed to ban: ${err.message}`);
+      return interaction.reply({ embeds: [embed], ephemeral: true });
+    }
+
+    const caseDoc = await createCase(CaseModel, {
+      guildId,
+      type: "ban",
+      targetId: targetUser.id,
+      moderatorId: interaction.user.id,
+      reason,
+    });
+
+    await postCaseLog(ctx, configData, caseDoc, targetUser, interaction.user);
+
+    const embed = new EmbedBuilder()
+      .setColor(0xe74c3c)
+      .setTitle(`Banned — Case #${caseDoc.caseNumber}`)
+      .addFields(
+        { name: "User", value: `${targetUser.tag} (${targetUser.id})`, inline: true },
+        { name: "Reason", value: reason }
+      )
+      .setTimestamp();
+
+    await interaction.reply({ embeds: [embed], ephemeral: true });
+  },
+};

package/commands/case.js

@@ -0,0 +1,63 @@
+"use strict";
+
+const { EmbedBuilder, PermissionFlagsBits } = require("discord.js");
+const { requirePerms } = require("../lib/permissions");
+
+const TYPE_COLORS = {
+  ban: 0xe74c3c,
+  unban: 0x2ecc71,
+  kick: 0xe67e22,
+  timeout: 0xf39c12,
+  untimeout: 0x3498db,
+  warn: 0xf1c40f,
+  note: 0x95a5a6,
+};
+
+module.exports = {
+  data: {
+    name: "case",
+    description: "Look up a moderation case by number",
+    options: [
+      { type: 4, name: "id", description: "Case number", required: true, min_value: 1 },
+    ],
+  },
+
+  async execute(interaction, ctx) {
+    if (!requirePerms(interaction, PermissionFlagsBits.ManageMessages)) return;
+
+    const caseNumber = interaction.options.getInteger("id");
+    const guildId = interaction.guild.id;
+    const CaseModel = ctx.models.Case;
+
+    const caseDoc = await CaseModel.findOne({ guildId, caseNumber }).lean();
+
+    if (!caseDoc) {
+      const embed = new EmbedBuilder()
+        .setColor(0xe74c3c)
+        .setDescription(`Case #${caseNumber} not found.`);
+      return interaction.reply({ embeds: [embed], ephemeral: true });
+    }
+
+    let targetUser = null;
+    let moderator = null;
+    try { targetUser = await ctx.client.users.fetch(caseDoc.targetUserId); } catch {}
+    try { moderator = await ctx.client.users.fetch(caseDoc.moderatorId); } catch {}
+
+    const color = TYPE_COLORS[caseDoc.type] || 0x99aab5;
+    const embed = new EmbedBuilder()
+      .setColor(color)
+      .setTitle(`Case #${caseDoc.caseNumber} — ${caseDoc.type.toUpperCase()}`)
+      .addFields(
+        { name: "Target", value: targetUser ? `${targetUser.tag} (${caseDoc.targetUserId})` : caseDoc.targetUserId, inline: true },
+        { name: "Moderator", value: moderator ? `${moderator.tag} (${caseDoc.moderatorId})` : caseDoc.moderatorId, inline: true },
+        { name: "Reason", value: caseDoc.reason || "No reason provided" }
+      )
+      .setTimestamp(caseDoc.createdAt);
+
+    if (caseDoc.duration) {
+      embed.addFields({ name: "Duration", value: caseDoc.duration, inline: true });
+    }
+
+    await interaction.reply({ embeds: [embed], ephemeral: true });
+  },
+};

package/commands/clearwarnings.js

@@ -0,0 +1,35 @@
+"use strict";
+
+const { EmbedBuilder, PermissionFlagsBits } = require("discord.js");
+const { requirePerms } = require("../lib/permissions");
+
+module.exports = {
+  data: {
+    name: "clearwarnings",
+    description: "Clear all warnings for a member",
+    options: [
+      { type: 6, name: "user", description: "The member to clear warnings for", required: true },
+    ],
+  },
+
+  async execute(interaction, ctx) {
+    if (!requirePerms(interaction, PermissionFlagsBits.ManageGuild)) return;
+
+    const targetUser = interaction.options.getUser("user");
+    const guildId = interaction.guild.id;
+    const CaseModel = ctx.models.Case;
+
+    const result = await CaseModel.deleteMany({ guildId, targetUserId: targetUser.id, type: "warn" });
+    await ctx.db.updateUserProfile(targetUser.id, guildId, { warnings: 0 });
+
+    const embed = new EmbedBuilder()
+      .setColor(0x2ecc71)
+      .setTitle("Warnings Cleared")
+      .setDescription(
+        `Cleared **${result.deletedCount}** warning(s) for **${targetUser.tag}**.`
+      )
+      .setTimestamp();
+
+    await interaction.reply({ embeds: [embed], ephemeral: true });
+  },
+};

package/commands/history.js

@@ -0,0 +1,46 @@
+"use strict";
+
+const { EmbedBuilder, PermissionFlagsBits } = require("discord.js");
+const { requirePerms } = require("../lib/permissions");
+
+module.exports = {
+  data: {
+    name: "history",
+    description: "View moderation history for a member",
+    options: [
+      { type: 6, name: "user", description: "The member to look up", required: true },
+    ],
+  },
+
+  async execute(interaction, ctx) {
+    if (!requirePerms(interaction, PermissionFlagsBits.ManageMessages)) return;
+
+    const targetUser = interaction.options.getUser("user");
+    const guildId = interaction.guild.id;
+    const CaseModel = ctx.models.Case;
+
+    const cases = await CaseModel.find({ guildId, targetUserId: targetUser.id })
+      .sort({ createdAt: -1 })
+      .limit(20)
+      .lean();
+
+    const embed = new EmbedBuilder()
+      .setColor(0x99aab5)
+      .setTitle(`History for ${targetUser.tag}`)
+      .setThumbnail(targetUser.displayAvatarURL())
+      .setDescription(
+        cases.length === 0
+          ? "No moderation history found."
+          : cases
+              .map(
+                (c) =>
+                  `**[#${c.caseNumber}] ${c.type.toUpperCase()}** — <t:${Math.floor(new Date(c.createdAt).getTime() / 1000)}:R>\n${c.reason}`
+              )
+              .join("\n\n")
+      )
+      .setFooter({ text: `Showing up to 20 most recent cases` })
+      .setTimestamp();
+
+    await interaction.reply({ embeds: [embed], ephemeral: true });
+  },
+};

package/commands/kick.js

@@ -0,0 +1,79 @@
+"use strict";
+
+const { EmbedBuilder, PermissionFlagsBits } = require("discord.js");
+const { requirePerms } = require("../lib/permissions");
+const { dmActionUser } = require("../lib/dmUser");
+const { createCase, postCaseLog } = require("../lib/logCase");
+
+module.exports = {
+  data: {
+    name: "kick",
+    description: "Kick a member from the server",
+    options: [
+      { type: 6, name: "user", description: "The member to kick", required: true },
+      { type: 3, name: "reason", description: "Reason for the kick", required: false },
+    ],
+  },
+
+  async execute(interaction, ctx) {
+    if (!requirePerms(interaction, PermissionFlagsBits.KickMembers)) return;
+
+    const targetUser = interaction.options.getUser("user");
+    const reason = interaction.options.getString("reason") || "No reason provided";
+    const guildId = interaction.guild.id;
+
+    const CaseModel = ctx.models.Case;
+    const configData = (await ctx.db.getPluginConfig(guildId, "adb-plugin-moderation"))?.data || {};
+
+    let member;
+    try {
+      member = await interaction.guild.members.fetch(targetUser.id);
+    } catch {
+      const embed = new EmbedBuilder().setColor(0xe74c3c).setDescription("That user is not in this server.");
+      return interaction.reply({ embeds: [embed], ephemeral: true });
+    }
+
+    if (!member.kickable) {
+      const embed = new EmbedBuilder()
+        .setColor(0xe74c3c)
+        .setDescription("I cannot kick that member (insufficient role hierarchy).");
+      return interaction.reply({ embeds: [embed], ephemeral: true });
+    }
+
+    if (configData.dm_on_action !== false) {
+      await dmActionUser(ctx.client, targetUser.id, {
+        action: "kicked",
+        guildName: interaction.guild.name,
+        reason,
+      });
+    }
+
+    try {
+      await member.kick(reason);
+    } catch (err) {
+      const embed = new EmbedBuilder().setColor(0xe74c3c).setDescription(`Failed to kick: ${err.message}`);
+      return interaction.reply({ embeds: [embed], ephemeral: true });
+    }
+
+    const caseDoc = await createCase(CaseModel, {
+      guildId,
+      type: "kick",
+      targetId: targetUser.id,
+      moderatorId: interaction.user.id,
+      reason,
+    });
+
+    await postCaseLog(ctx, configData, caseDoc, targetUser, interaction.user);
+
+    const embed = new EmbedBuilder()
+      .setColor(0xe67e22)
+      .setTitle(`Kicked — Case #${caseDoc.caseNumber}`)
+      .addFields(
+        { name: "User", value: `${targetUser.tag} (${targetUser.id})`, inline: true },
+        { name: "Reason", value: reason }
+      )
+      .setTimestamp();
+
+    await interaction.reply({ embeds: [embed], ephemeral: true });
+  },
+};

package/commands/lock.js

@@ -0,0 +1,36 @@
+"use strict";
+
+const { EmbedBuilder, PermissionFlagsBits } = require("discord.js");
+const { requirePerms } = require("../lib/permissions");
+
+module.exports = {
+  data: {
+    name: "lock",
+    description: "Lock a channel (prevent @everyone from sending messages)",
+    options: [
+      { type: 7, name: "channel", description: "Channel to lock (defaults to current)", required: false },
+    ],
+  },
+
+  async execute(interaction, ctx) {
+    if (!requirePerms(interaction, PermissionFlagsBits.ManageChannels)) return;
+
+    const target = interaction.options.getChannel("channel") || interaction.channel;
+
+    try {
+      await target.permissionOverwrites.edit(interaction.guild.roles.everyone, {
+        SendMessages: false,
+      });
+    } catch (err) {
+      const embed = new EmbedBuilder().setColor(0xe74c3c).setDescription(`Failed to lock channel: ${err.message}`);
+      return interaction.reply({ embeds: [embed], ephemeral: true });
+    }
+
+    const embed = new EmbedBuilder()
+      .setColor(0xe74c3c)
+      .setDescription(`${target} has been **locked**. Members can no longer send messages.`)
+      .setTimestamp();
+
+    await interaction.reply({ embeds: [embed], ephemeral: true });
+  },
+};

package/commands/modstats.js

@@ -0,0 +1,54 @@
+"use strict";
+
+const { EmbedBuilder, PermissionFlagsBits } = require("discord.js");
+const { requirePerms } = require("../lib/permissions");
+
+module.exports = {
+  data: {
+    name: "modstats",
+    description: "View moderation statistics for a moderator",
+    options: [
+      { type: 6, name: "mod", description: "Moderator to check (defaults to yourself)", required: false },
+    ],
+  },
+
+  async execute(interaction, ctx) {
+    if (!requirePerms(interaction, PermissionFlagsBits.ManageGuild)) return;
+
+    const modUser = interaction.options.getUser("mod") || interaction.user;
+    const guildId = interaction.guild.id;
+    const CaseModel = ctx.models.Case;
+
+    const startOfMonth = new Date();
+    startOfMonth.setDate(1);
+    startOfMonth.setHours(0, 0, 0, 0);
+
+    const types = ["ban", "unban", "kick", "timeout", "untimeout", "warn", "note"];
+
+    const counts = await Promise.all(
+      types.map((type) =>
+        CaseModel.countDocuments({
+          guildId,
+          moderatorId: modUser.id,
+          type,
+          createdAt: { $gte: startOfMonth },
+        })
+      )
+    );
+
+    const total = counts.reduce((a, b) => a + b, 0);
+
+    const embed = new EmbedBuilder()
+      .setColor(0x3498db)
+      .setTitle(`Mod Stats — ${modUser.tag}`)
+      .setThumbnail(modUser.displayAvatarURL())
+      .setDescription(`Actions taken since **<t:${Math.floor(startOfMonth.getTime() / 1000)}:D>**`)
+      .addFields(
+        types.map((type, i) => ({ name: type.toUpperCase(), value: String(counts[i]), inline: true }))
+      )
+      .addFields({ name: "Total (this month)", value: String(total), inline: false })
+      .setTimestamp();
+
+    await interaction.reply({ embeds: [embed], ephemeral: true });
+  },
+};

package/commands/note.js

@@ -0,0 +1,58 @@
+"use strict";
+
+const { EmbedBuilder, PermissionFlagsBits } = require("discord.js");
+const { requirePerms } = require("../lib/permissions");
+const { createCase, postCaseLog } = require("../lib/logCase");
+
+module.exports = {
+  data: {
+    name: "note",
+    description: "Add a moderator note to a member",
+    options: [
+      { type: 6, name: "user", description: "The member to add a note to", required: true },
+      { type: 3, name: "text", description: "The note content", required: true },
+    ],
+  },
+
+  async execute(interaction, ctx) {
+    if (!requirePerms(interaction, PermissionFlagsBits.ManageMessages)) return;
+
+    const targetUser = interaction.options.getUser("user");
+    const text = interaction.options.getString("text");
+    const guildId = interaction.guild.id;
+
+    const CaseModel = ctx.models.Case;
+    const NoteModel = ctx.models.Note;
+    const configData = (await ctx.db.getPluginConfig(guildId, "adb-plugin-moderation"))?.data || {};
+
+    // Save note document
+    const noteDoc = new NoteModel({
+      guildId,
+      userId: targetUser.id,
+      moderatorId: interaction.user.id,
+      note: text,
+    });
+    await noteDoc.save();
+
+    const caseDoc = await createCase(CaseModel, {
+      guildId,
+      type: "note",
+      targetId: targetUser.id,
+      moderatorId: interaction.user.id,
+      reason: text,
+    });
+
+    await postCaseLog(ctx, configData, caseDoc, targetUser, interaction.user);
+
+    const embed = new EmbedBuilder()
+      .setColor(0x95a5a6)
+      .setTitle(`Note Added — Case #${caseDoc.caseNumber}`)
+      .addFields(
+        { name: "User", value: `${targetUser.tag} (${targetUser.id})`, inline: true },
+        { name: "Note", value: text }
+      )
+      .setTimestamp();
+
+    await interaction.reply({ embeds: [embed], ephemeral: true });
+  },
+};

package/commands/purge.js

@@ -0,0 +1,68 @@
+"use strict";
+
+const { EmbedBuilder, PermissionFlagsBits } = require("discord.js");
+const { requirePerms } = require("../lib/permissions");
+
+module.exports = {
+  data: {
+    name: "purge",
+    description: "Bulk-delete messages from this channel",
+    options: [
+      {
+        type: 4,
+        name: "amount",
+        description: "Number of messages to delete (1-100)",
+        required: true,
+        min_value: 1,
+        max_value: 100,
+      },
+      { type: 6, name: "user", description: "Only delete messages from this user", required: false },
+    ],
+  },
+
+  async execute(interaction, ctx) {
+    if (!requirePerms(interaction, PermissionFlagsBits.ManageMessages)) return;
+
+    const amount = interaction.options.getInteger("amount");
+    const filterUser = interaction.options.getUser("user");
+    const channel = interaction.channel;
+
+    let messages;
+    try {
+      messages = await channel.messages.fetch({ limit: 100 });
+    } catch (err) {
+      const embed = new EmbedBuilder().setColor(0xe74c3c).setDescription(`Failed to fetch messages: ${err.message}`);
+      return interaction.reply({ embeds: [embed], ephemeral: true });
+    }
+
+    let filtered = [...messages.values()];
+
+    if (filterUser) {
+      filtered = filtered.filter((m) => m.author.id === filterUser.id);
+    }
+
+    // Take only the requested amount
+    filtered = filtered.slice(0, amount);
+
+    if (filtered.length === 0) {
+      const embed = new EmbedBuilder().setColor(0xf39c12).setDescription("No messages to delete.");
+      return interaction.reply({ embeds: [embed], ephemeral: true });
+    }
+
+    let deleted;
+    try {
+      // bulkDelete passes true to filter out messages older than 14 days
+      deleted = await channel.bulkDelete(filtered, true);
+    } catch (err) {
+      const embed = new EmbedBuilder().setColor(0xe74c3c).setDescription(`Failed to delete messages: ${err.message}`);
+      return interaction.reply({ embeds: [embed], ephemeral: true });
+    }
+
+    const embed = new EmbedBuilder()
+      .setColor(0x3498db)
+      .setDescription(`Deleted **${deleted.size}** message(s).${filterUser ? ` (filtered to ${filterUser.tag})` : ""}`)
+      .setTimestamp();
+
+    await interaction.reply({ embeds: [embed], ephemeral: true });
+  },
+};

package/commands/slowmode.js

@@ -0,0 +1,46 @@
+"use strict";
+
+const { EmbedBuilder, PermissionFlagsBits } = require("discord.js");
+const { requirePerms } = require("../lib/permissions");
+
+module.exports = {
+  data: {
+    name: "slowmode",
+    description: "Set slowmode for this channel (0 to disable)",
+    options: [
+      {
+        type: 4,
+        name: "seconds",
+        description: "Slowmode in seconds (0-21600)",
+        required: true,
+        min_value: 0,
+        max_value: 21600,
+      },
+    ],
+  },
+
+  async execute(interaction, ctx) {
+    if (!requirePerms(interaction, PermissionFlagsBits.ManageChannels)) return;
+
+    const seconds = interaction.options.getInteger("seconds");
+    const channel = interaction.channel;
+
+    try {
+      await channel.setRateLimitPerUser(seconds, `Slowmode set by ${interaction.user.tag}`);
+    } catch (err) {
+      const embed = new EmbedBuilder().setColor(0xe74c3c).setDescription(`Failed to set slowmode: ${err.message}`);
+      return interaction.reply({ embeds: [embed], ephemeral: true });
+    }
+
+    const embed = new EmbedBuilder()
+      .setColor(0x3498db)
+      .setDescription(
+        seconds === 0
+          ? "Slowmode **disabled** for this channel."
+          : `Slowmode set to **${seconds} second(s)** for this channel.`
+      )
+      .setTimestamp();
+
+    await interaction.reply({ embeds: [embed], ephemeral: true });
+  },
+};