Welcome to the ultimate Discord Bot Utilities package! 🥏 Boost your Discord bot development with ease, speed, and all-in-one features.

📑 Table of Contents

1. 🎯 Starter – Initialize your bot with commands, events, presence, and more.
2. ⚙️ Functions – Utilities like CreateRow, CreateBar, Wait, and GetUser.
3. ⚡ Commands & Events – Easy setup with cooldowns, permissions, logging, and anti-crash.
4. 🌐 Dashboard – Web-based control panel for managing your bot.

🎯 STARTER

The starter function is the ultimate initializer for your Discord bot 🤖. It handles everything from logging in, loading commands/events, setting the bot presence, anti-crash protection, logging commands usage, and even checking for library updates.

Features:

• 🛠️ One-line loader for both Slash & Prefix commands 🔩
• 📜 Comprehensive terminal info display (commands, events, bot stats) 📊
• 🧰 Event handler loader in one line 🎉
• ⚠️ Anti-crash system with automatic webhook reporting 📃
• 🔋 MongoDB connection support 📥
• 📑 Command logger for both Slash and Prefix commands 🧭
• 💡 Supports custom prefixes per guild and cooldowns ⏳
• 🔼 Automatic update checker for djs-builder 📦

💡 Tip: Any option you don’t want, just remove it 🗑️.

const { starter } = require("djs-builder");
const { Client, GatewayIntentBits } = require("discord.js");

const client = new Client({
  intents: Object.keys(GatewayIntentBits).map((a) => GatewayIntentBits[a]),
});

// Define starter options
const starterOptions = {
  bot: {
    token: "YOUR_BOT_TOKEN", // 🔑 Discord bot token
    ownerId: "YOUR_USER_ID", // 👤 Bot owner ID
  },
  terminal: true, // 🖥️ Show bot info in terminal

  Status: {
    status: "online", // ✅ Presence state: online, dnd, idle, offline
    activities: ["Game 1", "Game 2"], // 🎮 Multiple activities
    type: 0, // 🎭 Activity type: (0=PLAYING, 1=STREAMING, 2=LISTENING, 3=WATCHING)
    time: 60000, // ⏱️ Rotate activities every X ms
    url: "https://twitch.tv/example", // 🌐 Twitch URL (only required for streaming)
  },

  database: {
    url: "mongodb://localhost:27017", // 💾 MongoDB connection
  },

  anticrash: {
    url: "https://your.crash.webhook.url", // 🚨 Webhook for crash reports
    mention_id: "YOUR_USER_ID", // 📣 Optional: mention user on crash
  },

  // 🌐 Dashboard Configuration (Full docs at the end of this page)
  dashboard: {
    clientID: "YOUR_DISCORD_CLIENT_ID",        // 🔑 Discord Application Client ID
    clientSecret: "YOUR_DISCORD_CLIENT_SECRET", // 🔐 Discord Application Client Secret
    callbackURL: "http://localhost:3000/auth/discord/callback", // 🔗 OAuth2 Callback URL
    sessionSecret: "your-super-secret-key",    // 🔒 Session encryption secret
    port: 3000,                                 // 🌍 Dashboard port (default: 3000)
  },
};

// Start the bot
await starter(client, starterOptions);

📌 How Starter Works

1️⃣ Bot Login & Status

• Authenticates the bot using your token 🔑.
• Supports multiple rotating activities (e.g., Game 1 → Game 2 → …) ⏱️.
• Works with all Discord activity types: PLAYING, STREAMING, LISTENING, WATCHING 🎭.
• Twitch URL is supported for streaming mode 🌐.

2️⃣ Database Connection

• Connects automatically to MongoDB 💾.
• Useful for bots with persistent data storage.

3️⃣ Anticrash System

• Catches and logs:

  • unhandledRejection
  • uncaughtException
  • uncaughtExceptionMonitor
  • unhandledRejectionMonitor
  • warning ⚠️

• Sends error reports to a webhook 🚨.

• Optionally pings the owner 📣.

4️⃣ Terminal Info

• Displays colorful and structured information 🖥️:

  • Bot name, user, guild, and channel counts 📊.
  • Owner ID 👤.
  • Database connection status 💾.
  • Uptime ⏳.

• Powered by cli-table3 + chalk for a professional CLI look 🎨.

5️⃣ Auto Update Checker

• Monitors new versions of djs-builder automatically 🔄.
• Sends update notifications to the webhook 🎉.

6️⃣ Bot Files Information

• Access detailed stats about loaded files directly from the client:

  • Number of prefix commands ⚡.
  • Number of slash commands ⚔️.
  • Number of events 🎉.

• Available via client.files, useful for debugging or terminal display 🛠️.

7️⃣ Dashboard (Web Control Panel)

• Launches a modern web-based control panel for your bot 🌐.
• Supports Discord OAuth2 authentication 🔐.
• Manage servers, levels, giveaways, and blacklists from the browser 🎛️.

📖 Full Dashboard documentation available at the end of this page → 🌐 DASHBOARD

💡 Tips

• Flexible: Delete any section you don’t need (anticrash, database, etc.) 🗑️.
• Multi-Status: Add as many activities as you want and let them rotate 🎮.
• Safe by Default: Anticrash system ensures your bot won’t go down easily 🛡️.
• Always Up-to-Date: Automatic update checker keeps your bot running on the latest version ⬆️.
• Transparent: Quickly check how many files your bot has loaded anytime 📊.

⚙️ functions

• Easiest ✨ / Fastest ⚡ /Clear 🧵

Than the discord.js

🔵 CreateRow – Easily create Discord Action Rows with Buttons & Select Menus ✨

CreateRow is a powerful utility to build Discord Action Rows. It supports:

• Buttons ✅
• Select Menus 🎯 (string, role, user, channel)
• Advanced options like defaultValues and channelTypes.

📌 Example Usage:

const { CreateRow } = require("djs-builder");

const actionRow = new CreateRow([
  //// For each new row, use [] for buttons or {} for a select menu

  // 🔹 Row #1: Buttons
  [
    {
      id: "button1", // customId for the button
      style: 1, // Button styles: Primary(1), Secondary(2), Success(3), Danger(4), Link(5)
      label: "Primary Button", // Text shown on button
      emoji: "😃", // Emoji displayed
      disabled: false, // true = disabled
    },
    {
      id: "button2",
      style: 2,
      emoji: "🚀",
      disabled: true, // Button is disabled
    },
  ],

  // 🔹 Row #2: Select Menu
  {
    type: "string", // Options: "string" | "role" | "user" | "channel"
    options: {
      id: "menu1", // customId for the select menu
      placeholder: "Select an option",
      min: 1, // Minimum selection
      max: 2, // Maximum selection

      // 🔸 Data for string select only
      data: [
        {
          name: "Option 1",
          id: "opt1",
          about: "First option",
          icon: "🌟",
          default: true,
        },
        { name: "Option 2", id: "opt2", about: "Second option", icon: "🚀" },
        { name: "Option 3", id: "opt3", about: "Third option", icon: "🔗" },
      ],

      // 🔸 Map keys
      label: "name", // Which field is the label
      value: "id", // Which field is the value
      description: "about", // Description for each option
      emoji: "icon", // Emoji for each option

      // 🔸 Extra options
      disabled: false, // Disable the entire menu
      defaultValues: [
        // For role/user/channel menus
        { id: "123456789012345678", type: "user" }, // Pre-selected
      ],
      channelTypes: [0, 2], // Only for ChannelSelectMenu (0 = Text, 2 = Voice)
    },
  },
]);

📖 Explanation

🔹 Buttons

• id → customId for the button
• style → 1: Primary, 2: Secondary, 3: Success, 4: Danger, 5: Link
• label → Button text
• emoji → Displayed emoji
• disabled → true = button is unclickable

🔹 Select Menus

• type → "string" | "user" | "role" | "channel"

• id → customId for menu

• placeholder → Text shown before selection

• min / max → Min/Max selectable values

• data → Options array (for string select only)

  • label → Visible text
  • value → Internal value
  • description → Short description
  • emoji → Option emoji
  • default → Pre-selected option

• disabled → Disable menu completely

• defaultValues → Pre-selected user/role/channel options

• channelTypes → Restrict selectable channel types

🧾 CreateBar – Text-based Progress Bar for Discord ✨

CreateBar allows you to display a customizable progress bar with optional percentages and partial symbols. Perfect for showing progress, loading, or stats in messages.

📌 Basic Example:

const { CreateBar } = require("djs-builder");

const bar = new CreateBar(7, 10, {
  length: 20, // Total length of the bar
  fill: "💚", // Filled portion
  empty: "🖤", // Empty portion
  partialChar: "💛", // Partial fill
  showPercent: true, // Show percentage
  left: "❰", // Left bracket
  right: "❱", // Right bracket
});

console.log(bar);
// Output: ❰💚💚💚💚💚💚💚💛🖤🖤🖤🖤🖤🖤🖤🖤🖤🖤❱ 70%

📌 Another Example with different symbols:

console.log(
  CreateBar(3.7, 5, {
    fill: "🟦",
    empty: "⬛",
    partialChar: "🟨",
    length: 10,
    left: "❰",
    right: "❱",
    showPercent: true,
  })
);

// Output: ❰🟦🟦🟦🟨⬛⬛⬛⬛⬛⬛❱ 74%

📌 Minimalist example without percentage:

console.log(
  CreateBar(4, 8, {
    fill: "🔵",
    empty: "⚪",
    showPercent: false,
  })
);

// Output: 🔵🔵🔵🔵⚪⚪⚪⚪

📌 Fun Emoji example:

console.log(
  CreateBar(6, 10, {
    length: 12,
    fill: "🔥",
    empty: "❄️",
    partialChar: "🌟",
    showPercent: true,
    left: "«",
    right: "»",
  })
);

// Output: «🔥🔥🔥🔥🔥🔥🌟❄️❄️❄️❄️» 60%

🔹 Options Summary

• length → Total number of symbols
• fill → Symbol for filled portion
• empty → Symbol for empty portion
• partialChar → Symbol for partial fill (e.g., half-filled)
• showPercent → Show percentage at the end
• left / right → Brackets or edges for the bar

🔹 Notes

• Supports fractional values for partial fill
• Fully customizable with any emoji or character 🎨
• Great for progress, stats, experience bars, or loading indicators

⏰ Wait – Await messages, buttons, select menus or modals easily ✨

Wait is a replacement for traditional collectors. It supports:

• Awaiting messages 📝
• Awaiting interactions (buttons / select menus) 🎛️
• Awaiting modal submissions 📋
• Filtering by user and timeout

📌 Example Usage:

const { Wait } = require("djs-builder");

const response = await Wait({
  context: message, // Message or Interaction object
  userId: message.author.id, // Optional: filter by user
  type: "both", // "message" | "interaction" | "both"
  time: 30000, // Time in ms
  message_Wait: message, // Required if waiting for buttons/selects
});

if (!response) return console.log("⏱️ Timeout!");
console.log("✅ Collected:", response);

🔹 Options

• context → The message or interaction context
• userId → Only collect from this user (optional)
• type → "message" | "interaction" | "both"
• time → Timeout in milliseconds
• message_Wait → Message containing buttons/select menus (for interaction/both type)

🔹 Notes

• Supports automatic cleanup of collectors after completion
• Can return Message, Interaction, or ModalSubmitInteraction

👤 GetUser – Fetch a GuildMember easily from a message ✨

GetUser helps to detect a target member in multiple ways:

1. Mention (@User)
2. User ID (123456789012345678)
3. Reply to another message

📌 Example Usage:

const { GetUser } = require("djs-builder");

const data = await GetUser(message);

if (!data) return message.reply("❌ Could not find the user.");

const member = data.user; // GuildMember object
const args = data.args; // Remaining arguments
const reason = args.join(" ") || "No reason provided";

await member.ban({ reason });
message.reply(`🚫 ${member.user.tag} was banned for: ${reason}`);

🔹 Returns

{
  user: <GuildMember>,  // Targeted member
  args: [ "arg1", "arg2" ] // Remaining message arguments
}

🔹 Detection Methods

• Mention: !ban @Ahmed Spamming
• User ID: !ban 123456789012345678 Spamming
• Reply: Reply to user's message with !ban

🔹 Notes

• Automatically handles missing users
• Returns null if user not found
• Works in any text channel of the guild

The Logging System is a powerful feature that keeps track of almost everything happening inside your Discord server 🔍.
From messages 📝 to channels 📂, roles 🎭, invites 🔗, and even voice state changes 🎙️ – nothing goes unnoticed!

✨ Features

• 📝 Messages – Deleted & edited messages are logged with details.
• 📂 Channels – Creation, deletion, and updates are tracked.
• 🎭 Roles – Created, deleted, and updated roles, including member role changes.
• 🎙️ Voice State – Joins, leaves, and moves between channels.
• 🔗 Invites – Created invites & usage tracking.
• 😀 Emojis & Stickers – Added, removed, or updated.
• 🚨 Audit Log Integration – Fetches the executor (who did what).
• 🎨 Beautiful Embeds – Every log is shown in a clean, styled embed with timestamps.

⚙️ Setup Example

Using the log function is very simple ⚡.
Just place this code inside an event (like clientReady) to start logging:

const { log } = require("djs-builder");

module.exports = {
  name: "clientReady",
  async run(client) {
    await log(
      client,
      "GUILD_ID", // 🏠 Guild ID (server)
      "CHANNEL_ID" // 📢 Channel ID for logs
    );
  },
};

💡 How It Works

• ✅ Pass your Client, Guild ID, and Log Channel ID.
• 🔔 Instantly starts tracking events and sending them to the log channel.
• 🧰 No extra setup required – plug and play!

🏆 Level System – XP, Levels & Leaderboard

The Level System module lets you track user experience points (XP) in text 💬 and voice 🎙️, handle level-ups ⬆️, and display leaderboards 🏅. Perfect for gamifying your Discord server! 🎮✨

Note: To use this module, you MUST have DATABASE conection. | Note 2: You can get all data by requiring the Level module.

📦 Module Exports

const { addXP, UserLevel, leaderboard } = require("djs-builder");

• addXP(userId, guildId, options) → Adds XP for a user and handles level-ups 🎲.
• UserLevel(userId, guildId) → Fetch a user's XP and level 👤.
• leaderboard(guildId, type, limit) → Get top users 🏅.

🎲 addXP – Add Experience Points

Adds XP to a user and automatically handles level-ups.

const result = await addXP("USER_ID", "GUILD_ID", {
  type: "text", // "text" 💬 | "voice" 🎙️
  minXP: 5, // Minimum random XP 🟢
  maxXP: 15, // Maximum random XP 🔵
  amount_add: 10, // Optional: fixed XP 💎
  level_add: 1, // Optional: direct level boost ⬆️
});

console.log(result);
/* Example output:
{
  newLevel: 3,
  oldLevel: 2,
  totalXP: 250,
  leveledUp: true
}
*/

🧑‍🤝‍🧑 UserLevel – Fetch User Data

Fetch a user's text XP, voice XP, total XP, and current level.

const data = await UserLevel("USER_ID", "GUILD_ID");
console.log(data);
/* Example output:
{
  text: 120 💬,
  voice: 50 🎙️,
  totalXP: 170 ⭐,
  level: 2 ⬆️
}
*/

Returns default values if the user is not found.

🏅 Leaderboard – Top Users

Get a sorted list of users based on XP or level.

const topUsers = await leaderboard("GUILD_ID", "totalXP", 5);
console.log(topUsers);
/* Example output:
[
  { userId: "123", totalXP: 500, level: 5 },
  { userId: "456", totalXP: 400, level: 4 },
  ...
]
*/

Parameters:

• guildId → Server ID 🏠
• type → "totalXP", "text" 💬, "voice" 🎙️, or "level" ⬆️. Default = "totalXP"
• limit → Number of top users to return 🔢. Default = 10

⚡ Practical Example: messageCreate Event

const { addXP, UserLevel, leaderboard } = require("djs-builder");

module.exports = {
  name: "messageCreate",
  run: async (msg, client) => {
    if (msg.author.bot) return;

    // 🎲 Add XP on every message
    const result = await addXP(msg.author.id, msg.guild.id, {
      type: "text",
      minXP: 5,
      maxXP: 15,
    });

    // 🎉 Level-up notification
    if (result.leveledUp) {
      msg.channel.send(`🎊 ${msg.author} new level **${result.newLevel}** ⬆️`);
    }

    // 📊 Check your rank
    if (msg.content === "!rank") {
      const data = await UserLevel(msg.author.id, msg.guild.id);
      msg.reply(`📈 **level ** ${data.level} ⬆️ – **XP:** ${data.totalXP} ⭐`);
    }

    // 🏅 Display top users
    if (msg.content === "!top") {
      const lb = await leaderboard(msg.guild.id, "totalXP", 5);
      msg.reply(
        lb
          .map(
            (u, i) =>
              `#${i + 1} <@${u.userId}> – Lv.${u.level} ⬆️ (${u.totalXP} ⭐)`
          )
          .join("\n")
      );
    }
  },
};

💡 Notes & Tips

• 💬 Text XP – Add XP for messages automatically.
• 🎙️ Voice XP – Add XP for voice activity.
• ⬆️ Level Up – Trigger notifications when leveling up.
• 🏅 Leaderboard – Display the top users in server using embeds for better look.
• 🎮 Gamify your server easily with XP rewards, mini-games, and custom commands.

🎉 Giveaway System – All-in-One Contest Management 🏆✨

This module provides a robust and feature-rich suite of functions to effortlessly launch, monitor, manage, and conclude Giveaways on your Discord server. It fully supports both Reactions and Buttons for entry, featuring advanced controls like pausing, resuming, and rerolling winners. It is highly recommended to read the Important Notes section below. 🚨

Note: To use this module, you MUST have DATABASE conection. | Note 2: You can get all data by requiring the giveaway module.

📦 Module Exports

const {
  Gstart,
  Gcheck,
  Greroll,
  Glist,
  Gpause,
  Gresume,
  Gdelete,
  GaddUser,
  GremoveUser,
  GaddTime,
  GremoveTime,
  Gdata,
} = require("djs-builder");

🎬 Gstart – Launch a Brand New Giveaway! 🚀

This is the primary function to kick off a new giveaway. It handles creating the Discord message and persists all necessary data in the database (MongoDB). This function offers deep customization for embeds and entry methods. 🎨

⚙️ Essential Options:

• context: The Message or Interaction object that triggered the command.
• endTime: The duration until the giveaway ends (in milliseconds ⏱️).
• winers: The number of winners for the contest. 🏅
• channelId: The ID of the channel where the giveaway message will be posted. 📢
• embed / endEmbed: Options to fully customize the starting message and the final end message.
• reaction: To specify the entry method (button or reaction). 🖱️

⚡ Simple Usage Example (Basic Requirements Only):

This example provides a fast and minimalist way to start a giveaway with default embed colors, a simple title, and the default reaction entry type (if the reaction object is omitted or set to reaction).

const { Gstart } = require("djs-builder");

module.exports = {
  name: "gstart",
  description: "Starts a new simple giveaway.",
  run: async (client, message, args) => {
    // ⏰ Giveaway ends in 1 hour
    const oneHour = 60 * 60 * 1000;
    const channelId = message.channel.id;

    await Gstart({
      context: message,
      endTime: oneHour,
      winers: 1,
      channelId: channelId,

      embed: {
        title: "🎉 Simple Test Giveaway",
        description: "React to enter! Prize: Discord Nitro.",
      },
    });
    message.reply("🎉 Simple Giveaway started successfully!");
  },
};

💡 Tip: This example provides a fast and minimalist way to start a giveaway with the default reaction type (emoji reaction).

⚡ Full Customization Example (Demonstrating all options):

This example showcases all available configuration options for deep customization of the embeds and the button entry method.

const { Gstart } = require("djs-builder");
const { EmbedBuilder } = require("discord.js");

module.exports = {
  name: "gstart",
  description: "Starts a new highly-customized giveaway.",
  run: async (client, message, args) => {
    // ⏰ Giveaway ends in 48 hours
    const twoDays = Date.now() + (48 * 60 * 60 * 1000);
    const channelId = 'YOUR_GIVEAWAY_CHANNEL_ID'; // 📢 Target Channel

    await Gstart({
      context: message,
      endTime: twoDays,
      winers: 5, // 5 lucky winners! 🏆
      channelId: channelId,

      // 🎨 Customization for the STARTING EMBED
      embed: {

            custom: new EmbedBuilder().setTitle("Raw Embed"),// 💡 You can use 'custom' to pass a raw Discord.js EmbedBuilder JSON
            title: "🎉 **HUGE SERVER BOOST GIVEAWAY!**",
            description: "Click the button below to enter for a chance to win a free server boost!",
            color: "Blue", // Any valid Discord color
            image: "https://yourimage.com/banner.png", // image URL
            thumbnail: message.guild.iconURL(),
      },

      // 🛑 Customization for the ENDED EMBED
      endEmbed: {
            custom: new EmbedBuilder().setTitle("Raw Embed"),// 💡 You can use 'custom' to pass a raw Discord.js EmbedBuilder JSON
            title: "🛑 Giveaway Has Concluded!",
            description: "Congratulations to the winners! Check the message below.",
            color: "Green",
            // Eimage and Ethumbnail can also be set here
      },

      // 🖱️ Button Entry Method
      reaction: {
        type: "button", // Use 'reaction' for an emoji reaction
        emoji: "✅", // The emoji displayed on the button
        label: "Enter Giveaway!", // The text label
        style: 3, // Button style: Primary(1), Secondary(2), Success(3), Danger(4)
        id: "djs-builder-giveaway", // Custom ID for the button
      },

      // 🔒 Requirements (Optional)
      requirements: {
        requiredRoles: ["123456789012345678"], // 🛡️ User MUST have this role to join (Button Only)
      },
    });
    message.reply("🎉 Giveaway started successfully!");
  },
};

💡 Flexibility Tip: You can safely remove any option you do not wish to use (e.g., remove endEmbed entirely if you are happy with the default end message structure). 🗑️

⚠️ Important Notes – Read Before Use! 🚨

This module requires specific setup steps to function correctly. Pay attention to the following crucial points:

• 1. The Gcheck Requirement (Monitor):

  • The Gcheck(client) function is responsible for monitoring and ending the giveaways once their time runs out.
  • Failure to call Gcheck(client) when your bot starts (e.g., in the clientReady event) will result in giveaways never ending automatically! 🛑

• 2. Button Entry vs. InteractionCreate:

  • If you set reaction.type to button in Gstart, the system will create the button but will NOT automatically register the participants.
  • You MUST manually implement a listener for the interactionCreate event and use the GaddUser function to register the user entry when the button is clicked. 🖱️
  • See the GaddUser section for a detailed code example.

• 3. Requirements (Roles):

  • The requiredRoles feature currently works ONLY with the Button entry method (reaction.type: "button").
  • When using GaddUser, you must pass the guild object as the third argument for the role check to work.

📆 Gcheck – Monitor and End Time-Expired Giveaways 🔎

This function runs periodically (every 10 seconds ⏱️) to check all active, non-paused giveaways. It automatically concludes contests that have passed their endTime. This function must be called once when the bot starts up. 🚀

⚡ Simple Example (in your clientReady event):

const { Gcheck } = require("djs-builder");

module.exports = {
  name: "clientReady",
  once: true,
  run: (client) => {
    console.log(`🤖 Bot is ready and monitoring giveaways...`);
    Gcheck(client); // 👈 Start the continuous check loop!
  },
};

🔄 Greroll – Redraw Winners for an Ended Contest 🎲

Used to redraw one or more new winners for a completed giveaway. It sends a new announcement message with the updated winners.

⚙️ Options:

• client: The Discord Client object. 🤖
• messageId: The Message ID of the giveaway post. 🆔

⚡ Simple Example:

const { Greroll } = require("djs-builder");

module.exports = {
  name: "reroll",
  description: "Redraws winners for an ended giveaway.",
  Permissions: ["MANAGE_MESSAGES"], // 🛡️ Permission check
  run: async (client, message, args) => {
    const id = args[0];
    if (!id)
      return message.reply(
        "❌ **Error:** Please provide the Giveaway Message ID."
      );
    const result = await Greroll(client, id);
    if (result?.error) {
      return message.reply(`⚠️ **Reroll Failed:** ${result.error}`);
    } else {
      message.reply(`✅ **Success!** Reroll initiated for giveaway \`${id}\`.`);
    }
  },
};

📜 Glist – Retrieve List of Giveaways 📋

Fetches a list of all saved giveaways based on their current status.

⚙️ Options:

• type: Can be ended, active, paused, or all. 🌐

⚡ Simple Example:

const { Glist } = require("djs-builder");

// Retrieve all currently active (non-paused, non-ended) giveaways
const activeGiveaways = await Glist("active");

if (activeGiveaways.length > 0) {
  console.log(`✅ Found ${activeGiveaways.length} Active Giveaways.`); // ... You can format and display this list to the user
} else {
  console.log("No active giveaways found.");
}

⏸️ Gpause & ▶️ Gresume – Stop and Continue Contests 🛑

Allows you to temporarily halt an ongoing giveaway, preserving the remaining time, and then resume it later. The message embed is automatically updated to reflect the pause/resume status.

⚙️ Options:

• client: The Discord Client object. 🤖
• messageId: The Message ID of the giveaway post. 🆔

⚡ Simple Example (for a management command):

const { Gpause, Gresume } = require("djs-builder");

module.exports = {
  name: "g_manage",
  description: "Pause or resume a giveaway.",
  devOnly: true, // 👑 Developer only access
  run: async (client, message, args) => {
    const [action, id] = args;
    if (!action || !id) return message.reply("⚠️ Missing action or ID.");

    if (action === "pause") {
      const result = await Gpause(client, id);
      if (result?.error) return message.reply(`❌ ${result.error}`);
      message.reply("⏸️ Giveaway successfully **paused**!");
    } else if (action === "resume") {
      const result = await Gresume(client, id);
      if (result?.error) return message.reply(`❌ ${result.error}`);
      message.reply("▶️ Giveaway successfully **resumed**!");
    }
  },
};

🗑️ Gdelete – Permanently Remove Giveaway Data 🗄️

Deletes the giveaway record entirely from the database. Note: This does not delete the Discord message itself, only the data.

⚙️ Options:

• messageId: The Message ID of the giveaway post. 🆔

⚡ Simple Example:

const { Gdelete } = require("djs-builder");

module.exports = {
  name: "gdelete",
  run: async (client, message, args) => {
    const messageId = args[0];
    const result = await Gdelete(messageId);
    if (result?.delete) {
      message.reply(
        `✅ **Success:** Giveaway data for \`${messageId}\` has been permanently deleted.`
      );
    } else {
      message.reply(
        `❌ **Error:** ${result?.error || "Could not delete giveaway data."}`
      );
    }
  },
};

➕ GaddUser & ➖ GremoveUser – Manual Participant Control 🧑‍🤝‍🧑

These functions allow you to manually add or remove user IDs from the participant list. This is crucial when setting the giveaway reaction type to button.

⚙️ Options:

• messageId: The Message ID of the giveaway. 🆔
• userId: The ID of the user to add/remove. 👤

💡 InteractionCreate Setup (for Button Entry) 🖱️

When using the button type, you MUST implement the following listener to handle join/leave actions dynamically.

⚡ Example Code for Dynamic Join/Leave in interactionCreate Event:

const { GaddUser, GremoveUser, CreateRow } = require("djs-builder");

module.exports = {
  name: "interactionCreate",
  run: async (interaction) => {
    // 1. Handle Join/Entry Button Click
    if (interaction.customId === "djs-builder-giveaway") {
      // ⚠️ Note: Pass 'interaction.guild' as the 3rd argument to enable Role Requirements check!
      const result = await GaddUser(
        interaction.message.id,
        interaction.user.id,
        interaction.guild 
      );

      if (result?.error) {
        // Handles both "User Already Joined" and "Missing Roles" errors
        if (result.error === "❌ User Already Joined") {
           // ... (Leave button logic)
           const row = await CreateRow([
            [
              {
                label: "Leave Giveaway",
                id: "djs-builder-giveaway-leave-" + interaction.message.id, // Dynamic ID
                style: 4, // Danger Red
              },
            ],
          ]);
          return interaction.reply({
            content: "⚠️ You have **already joined** this giveaway! You can **leave** by clicking the button below.",
            components: row,
            flags: 64, 
          });
        }
        
        // Show error (e.g. Missing Role)
        return interaction.reply({
            content: result.error,
            flags: 64
        });
      }

      await interaction.reply({
        content: "🎉 **Success!** Your entry has been registered!",
        flags: 64,
      });
    }


    // 2. Handle Leave Button Click (Dynamically Generated ID)
    if (
      interaction.customId &&
      interaction.customId.startsWith("djs-builder-giveaway-leave-")
    ) {
      const id = interaction.customId.split("-")[4]; // Extract message ID
      const result = await GremoveUser(id, interaction.user.id);

      // Note: The error message should ideally reflect the module's logic (User Not Joined)
      if (result?.error && result.error.includes("User Not Joined")) {
        return interaction.reply({
          content: "⚠️ You have **already left** this giveaway!",
          flags: 64,
        });
      }

      await interaction.reply({
        content: "🎉 **Success!** Your entry has been removed!",
        flags: 64,
      });
    }
  },
};

➕ GaddTime & ➖ GremoveTime – Adjust the End Time 🕰️

Allows you to extend or shorten the duration of an active giveaway.

⚙️ Options:

• messageId: The Message ID of the giveaway. 🆔
• client: The Discord Client object. 🤖
• time: The amount of time (in milliseconds ⏳) to add or remove.

⚡ Simple Example (Extending the Giveaway):

const { GaddTime } = require("djs-builder");

// Extend the contest by 30 minutes (1,800,000 MS)
const halfHour = 30 * 60 * 1000;
const result = await GaddTime(messageId, client, halfHour);

if (result?.error) {
  console.log(`Error adding time: ${result.error}`);
} else {
  console.log("Time successfully added!");
}

📊 Gdata – Retrieve Giveaway Data 💾

Fetches all saved data for a specific giveaway message.

⚙️ Options:

• messageId: The Message ID of the giveaway. 🆔

⚡ Simple Example:

const { Gdata } = require("djs-builder");

const giveawayData = await Gdata(messageId);

if (giveawayData) {
  console.log(`Giveaway hosted by: <@${giveawayData.hoster}>`);
  console.log(`Current status: ${giveawayData.ended ? "Ended" : "Active"}`);
} else {
  console.log("No data found for this message ID.");
}

📊 Gdata(messageId) – Returned Object Structure

• Returns an object like:

{
  "_id": "651234567890abcdef12345678", // 🔑 MongoDB unique ID
  "ended": false, // 💡 Current status of the giveaway
  "guildId": "123456789012345678", // 🏠 Server ID
  "channelId": "876543210987654321", // 📢 Channel ID
  "messageId": "987654321098765432", // 💬 Message ID of the giveaway post
  "hoster": "112233445566778899", // 👤 User ID of the giveaway host
"prize" : "code" // 🎁 prize
  "winnerCount": 1, // 🔢 Number of winners set
  "winners": [], // 🏆 Array of user IDs who won (empty if not ended)
  "paused": false, // ⏸️ True if the giveaway is paused
  "pausedTime": [], // ⏱️ Array of saved remaining times (used for resume)
  "endTime": "1730995200000", // 📅 Timestamp (MS) of when the giveaway should end
  "endType": "Time End", // 📝 How the giveaway ended (e.g., Time End, Reroll: 1 time(s))
  "reaction": "button", // 🖱️ Entry method: "reaction" or "button"
  "users": ["111111111111111111", "222222222222222222"], // 🧑‍🤝‍🧑 Array of user IDs who entered (used for button type)
  "endEmbed": {
    "title": "🛑 Giveaway Has Concluded!",
    "description": "Congratulations to the winners!",
    "color": 3066993, // Green color code
    "fields": [
      {
        "name": "🎉 Giveaway",
        "value": "- Winner(s): 1\n- Time : <t:1730995200:R>\n- Hosted By : <@112233445566778899>",
        "inline": true
      }
    ]
  },
  "__v": 0 // 🌐 Mongoose version key (internal)
}

💡 General Code Example – The All-in-One /giveaway Command 🛠️

This complete example demonstrates how to integrate all functions of the Giveaway System into a single Discord Slash Command, /giveaway, using subcommands for clean management.

const {
  Gstart,
  Greroll,
  Glist,
  Gpause,
  Gresume,
  Gdelete,
  GaddUser,
  GremoveUser,
  GaddTime,
  GremoveTime,
  Gdata,
} = require("djs-builder");
const {
  SlashCommandBuilder,
  EmbedBuilder,
  AttachmentBuilder,
  PermissionFlagsBits,
} = require("discord.js");
const ms = require("ms");

module.exports = {
  data: new SlashCommandBuilder()
    .setName("giveaway")
    .setDescription("Comprehensive giveaway system management")
    .setDefaultMemberPermissions(PermissionFlagsBits.ManageGuild)

    // 🎬 /giveaway start
    .addSubcommand((subcommand) =>
      subcommand
        .setName("start")
        .setDescription("Starts a new giveaway")
        .addStringOption((option) =>
          option
            .setName("prize")
            .setDescription("The prize for the winner(s)")
            .setRequired(true)
        )
        .addStringOption((option) =>
          option
            .setName("time")
            .setDescription("Duration (e.g., 1h, 30m, 7d)")
            .setRequired(true)
        )
        .addStringOption((option) =>
          option
            .setName("winner")
            .setDescription("Number of winners (e.g., 1, 3)")
            .setRequired(true)
        )
        .addChannelOption((option) =>
          option
            .setName("channel")
            .setDescription("The channel to post the giveaway in")
        )
        .addStringOption((option) =>
          option
            .setName("description")
            .setDescription("Custom description for the giveaway embed")
        )
        .addStringOption((option) =>
          option
            .setName("image")
            .setDescription("Image URL for the embed banner")
        )
        .addStringOption((option) =>
          option
            .setName("thumbnail")
            .setDescription("Thumbnail URL for the embed")
        )
    )

    // 🔄 Management Commands: /giveaway reroll, pause, resume, delete, data
    .addSubcommand((subcommand) =>
      subcommand
        .setName("reroll")
        .setDescription("Redraw winners for an ended giveaway")
        .addStringOption((option) =>
          option
            .setName("id")
            .setDescription("Giveaway message ID")
            .setRequired(true)
        )
    )
    .addSubcommand((subcommand) =>
      subcommand
        .setName("pause")
        .setDescription("Pause an active giveaway")
        .addStringOption((option) =>
          option
            .setName("id")
            .setDescription("Giveaway message ID")
            .setRequired(true)
        )
    )
    .addSubcommand((subcommand) =>
      subcommand
        .setName("resume")
        .setDescription("Resume a paused giveaway")
        .addStringOption((option) =>
          option
            .setName("id")
            .setDescription("Giveaway message ID")
            .setRequired(true)
        )
    )
    .addSubcommand((subcommand) =>
      subcommand
        .setName("delete")
        .setDescription("Delete a giveaway's data")
        .addStringOption((option) =>
          option
            .setName("id")
            .setDescription("Giveaway message ID")
            .setRequired(true)
        )
    )
    .addSubcommand((subcommand) =>
      subcommand
        .setName("data")
        .setDescription("Get raw data for a giveaway")
        .addStringOption((option) =>
          option
            .setName("id")
            .setDescription("Giveaway message ID")
            .setRequired(true)
        )
    )

    // 🧑‍🤝‍🧑 User Entry Management: /giveaway adduser, removeuser
    .addSubcommand((subcommand) =>
      subcommand
        .setName("adduser")
        .setDescription("Manually add user to giveaway (button entry only)")
        .addStringOption((option) =>
          option
            .setName("id")
            .setDescription("Giveaway message ID")
            .setRequired(true)
        )
        .addUserOption((option) =>
          option.setName("user").setDescription("User to add").setRequired(true)
        )
    )
    .addSubcommand((subcommand) =>
      subcommand
        .setName("removeuser")
        .setDescription(
          "Manually remove user from giveaway (button entry only)"
        )
        .addStringOption((option) =>
          option
            .setName("id")
            .setDescription("Giveaway message ID")
            .setRequired(true)
        )
        .addUserOption((option) =>
          option
            .setName("user")
            .setDescription("User to remove")
            .setRequired(true)
        )
    )

    // ⏱️ Time Modification: /giveaway addtime, removetime
    .addSubcommand((subcommand) =>
      subcommand
        .setName("addtime")
        .setDescription("Add time to an active giveaway")
        .addStringOption((option) =>
          option
            .setName("id")
            .setDescription("Giveaway message ID")
            .setRequired(true)
        )
        .addStringOption((option) =>
          option
            .setName("time")
            .setDescription("Time to add (e.g., 30m, 1h)")
            .setRequired(true)
        )
    )
    .addSubcommand((subcommand) =>
      subcommand
        .setName("removetime")
        .setDescription("Remove time from an active giveaway")
        .addStringOption((option) =>
          option
            .setName("id")
            .setDescription("Giveaway message ID")
            .setRequired(true)
        )
        .addStringOption((option) =>
          option
            .setName("time")
            .setDescription("Time to remove (e.g., 10m)")
            .setRequired(true)
        )
    )
    // 📜 giveaways list
    .addSubcommand((subcommand) =>
      subcommand
        .setName("list")
        .setDescription("List giveaways")
        .addStringOption((option) =>
          option
            .setName("type")
            .setDescription("Type of giveaways to list")
            .setRequired(true)
            .addChoices(
              { name: "Ended", value: "ended" },
              { name: "Active", value: "active" },
              { name: "Paused", value: "paused" },
              { name: "All", value: "all" }
            )
        )
    ),

  // ⚙️ Command Execution
  run: async (interaction, client) => {
    await interaction.deferReply({ flags: 64 }); // Acknowledge command immediately

    const command = interaction.options.getSubcommand();
    const id = interaction.options.getString("id");

    if (command === "start") {
      // 🚀 START LOGIC
      const channel =
        interaction.options.getChannel("channel") || interaction.channel;
      const description = interaction.options.getString("description");
      const image = interaction.options.getString("image");
      const thumbnail = interaction.options.getString("thumbnail");
      const timeString = interaction.options.getString("time");
      const winnerCount = parseInt(interaction.options.getString("winner"));
      const prize = interaction.options.getString("prize");

      const durationMs = ms(timeString);
      const endTimeMs = Date.now() + durationMs;

      if (!durationMs) {
        return interaction.editReply(
          "❌ **Error:** Invalid time format provided (e.g., 1h, 30m)."
        );
      }
      if (isNaN(winnerCount) || winnerCount < 1) {
        return interaction.editReply(
          "❌ **Error:** Winner count must be a number greater than 0."
        );
      }

      const giveaway = await Gstart({
        context: interaction,
        channelId: channel.id,
        winers: winnerCount,
        endTime: endTimeMs,
        prize : prize,
        embed: {
          title: `🎉 ${prize} Giveaway!`,
          image: image,
          thumbnail: thumbnail,
          description: description,
        },
        reaction: {
          type: "button",
          label: "Enter Giveaway",
          style: 1,
          emoji: "🎉",
        },
      });

      if (giveaway?.error) {
        return interaction.editReply(`❌ **Error:** ${giveaway.error}`);
      }

      return interaction.editReply(
        `✅ **Success!** Giveaway for **${prize}** has been started in ${channel}!`
      );
    } else if (command === "list") {
      // 📜 LIST LOGIC
      const type = interaction.options.getString("type");
      const giveaways = await Glist(type);
      const MAX_EMBED_LENGTH = 4000;
      const MAX_MESSAGE_LENGTH = 2000;

      if (!giveaways || giveaways.length === 0) {
        return interaction.editReply(`❌ No **${type}** giveaways found.`);
      }

      const listContent = giveaways
        .map(
          (g, i) =>
            `**#${i + 1}** | ID: \`${g.messageId}\` | Hoster: <@${
              g.hoster
            }> | End: <t:${Math.floor(g.endTime / 1000)}:R>`
        )
        .join("\n");

      const title = `📜 **${type.toUpperCase()} Giveaways:** (${
        giveaways.length
      } found)`;

      if (listContent.length <= MAX_MESSAGE_LENGTH) {
        // Output as a simple message (Under 2000 chars)
        return interaction.editReply({
          content: `${title}\n\n${listContent}`,
        });
      } else if (listContent.length <= MAX_EMBED_LENGTH) {
        // Output as an Embed (Over 2000, under 4000)
        const embed = new EmbedBuilder()
          .setTitle(title.replace(/\*\*/g, ""))
          .setDescription(listContent)
          .setColor("Blue");

        return interaction.editReply({
          content: `Too many results for a single message, displaying via Embed.`,
          embeds: [embed],
        });
      } else {
        // Output as an attachment/JSON file (Over 4000 chars)
        const jsonFile = new AttachmentBuilder(
          Buffer.from(JSON.stringify(giveaways, null, 2)),
          { name: `${type}_giveaways_list.json` }
        );

        return interaction.editReply({
          content: `⚠️ **Warning:** The list is too long! Sending ${giveaways.length} results in a JSON file.`,
          files: [jsonFile],
        });
      }
    } else if (command === "pause") {
      // ⏸️ PAUSE LOGIC
      const result = await Gpause(client, id);
      if (result?.error)
        return interaction.editReply(`❌ **Error:** ${result.error}`);
      return interaction.editReply(
        `⏸️ Giveaway \`${id}\` paused successfully!`
      );
    } else if (command === "resume") {
      // ▶️ RESUME LOGIC
      const result = await Gresume(client, id);
      if (result?.error)
        return interaction.editReply(`❌ **Error:** ${result.error}`);
      return interaction.editReply(
        `▶️ Giveaway \`${id}\` resumed successfully!`
      );
    } else if (command === "reroll") {
      // 🔄 REROLL LOGIC
      const result = await Greroll(client, id);
      if (result?.error)
        return interaction.editReply(`❌ **Error:** ${result.error}`);
      return interaction.editReply(
        `🔄 Reroll command sent for giveaway \`${id}\`! Check the channel for the new winner.`
      );
    } else if (command === "delete") {
      // 🗑️ DELETE LOGIC
      const result = await Gdelete(id);
      if (result?.error)
        return interaction.editReply(`❌ **Error:** ${result.error}`);
      return interaction.editReply(
        `🗑️ Giveaway data for \`${id}\` deleted successfully!`
      );

      // ➕ USER MANAGEMENT LOGIC
    } else if (command === "adduser") {
      const user = interaction.options.getUser("user");
      const result = await GaddUser(id, user.id);
      if (result?.error)
        return interaction.editReply(`❌ **Error:** ${result.error}`);
      return interaction.editReply(
        `➕ User **${user.tag}** added to giveaway \`${id}\`.`
      );
    } else if (command === "removeuser") {
      // ➖ REMOVE USER LOGIC
      const user = interaction.options.getUser("user");
      const result = await GremoveUser(id, user.id);
      if (result?.error)
        return interaction.editReply(`❌ **Error:** ${result.error}`);
      return interaction.editReply(
        `➖ User **${user.tag}** removed from giveaway \`${id}\`.`
      );

      // ⏳ TIME MANAGEMENT LOGIC
    } else if (command === "addtime") {
      const timeString = interaction.options.getString("time");
      const timeMs = ms(timeString);

      if (!timeMs) {
        return interaction.editReply(
          "❌ **Error:** Invalid time format provided (e.g., 1h, 30m)."
        );
      }

      const result = await GaddTime(id, client, timeMs);
      if (result?.error)
        return interaction.editReply(`❌ **Error:** ${result.error}`);
      return interaction.editReply(
        `⏱️ Added ${timeString} to giveaway \`${id}\`.`
      );
    } else if (command === "removetime") {
      // ⏪ REMOVE TIME LOGIC
      const timeString = interaction.options.getString("time");
      const timeMs = ms(timeString);

      if (!timeMs) {
        return interaction.editReply(
          "❌ **Error:** Invalid time format provided (e.g., 1h, 30m)."
        );
      }

      const result = await GremoveTime(id, client, timeMs);
      if (result?.error)
        return interaction.editReply(`❌ **Error:** ${result.error}`);
      return interaction.editReply(
        `⏱️ Removed ${timeString} from giveaway \`${id}\`.`
      );

      // 📊 DATA LOGIC
    } else if (command === "data") {
      const id = interaction.options.getString("id");
      console.log(id);
      const data = await Gdata(id);
      if (data?.error)
        return interaction.editReply(`❌ **Error:** ${data.error}`);

      const giveawayEmbed = new EmbedBuilder()
        .setTitle(`📊 Giveaway Data: ${id}`)
        .setColor(data.ended ? 0xff0000 : data.paused ? 0xffc0cb : 0x00ff00)
        .setDescription(
          `**Jump to Message 🔗 ** : ${
            data.messageId
              ? `https://discord.com/channels/${data.guildId}/${data.channelId}/${data.messageId}`
              : "N/A"
          }`
        );

      giveawayEmbed.addFields(
        {
          name: "✨ Status",
          value: data.ended
            ? "ENDED 🛑"
            : data.paused
            ? "PAUSED ⏸️"
            : "ACTIVE ✅",
          inline: true,
        },
        {
          name: "🏆 Winners",
          value: data.winwesNumber.toString(),
          inline: true,
        },
        {
          name: "🙋‍♂️ Hoster",
          value: `<@${data.hoster}>`,
          inline: true,
        },

        {
          name: "⏳ Ends In",
          value: `<t:${Math.floor(data.endTime / 1000)}:R>`,
          inline: true,
        },
        {
          name: "🎟️ Entries",
          value:
            data.reaction === "button"
              ? data.users.length.toString()
              : "N/A (Reaction Type)",
          inline: true,
        },
        {
          name: "🖱️ Entry Type",
          value: data.reaction.toUpperCase(),
          inline: true,
        }
      );

      if (data.ended && data.winers.length > 0) {
        giveawayEmbed.addFields({
          name: "🏅 Past Winners",
          value: data.winers.map((u) => `<@${u}>`).join(", ") || "N/A",
          inline: false,
        });
      }

      return interaction.editReply({
        embeds: [giveawayEmbed],
        content: `Data retrieved for giveaway \`${id}\`.`,
      });
    }
  },
};

📝 Final Improvements and Notes: ✨🚀

• 1. Time Parsing via ms: ⏰⏳

  • for time inputs (e.g., 1h, 30m) to be correctly converted into milliseconds.

• 2. List Command Robustness: 📜🛡️

  • The list command logic handles large result sets automatically to avoid the Discord 2000-character limit error:
    • Under 2000 characters: Sent as a direct, formatted message.
    • Between 2000 and 4000 characters: Sent inside an EmbedBuilder.
    • Over 4000 characters: Sent as a JSON attachment, preventing API errors.

• 3. Function Call Integrity: ⚙️✅

  • The client object is correctly passed to GaddTime and GremoveTime (id, client, timeMs), meeting the module's requirements for management functions.

• 4. Enhanced User Experience (UX): 🎯🌟

  • The channel option uses .addChannelOption() for a native Discord selector.
  • Validation is included for winnerCount and time formats. 🚫

• 5. Private and Immediate Feedback: 🔒💬

  • Uses interaction.deferReply({ flags: 64 }) (ephemeral/private) and interaction.editReply() for fast, clean, and non-intrusive status updates.

🚫 Blacklist System – Restrict Access to Commands

The Blacklist System allows you to block specific users, roles, or channels from using your bot's commands. This is useful for moderation and preventing abuse.

Note 1: To use this module, you MUST have DATABASE connection. | Note 2: You can get all data by requiring the Blacklist module.

📦 Module Exports

const {
  isBlacklisted,
  addToBlacklist,
  removeFromBlacklist,
  getBlacklist,
  Blacklist,
} = require("djs-builder");

• isBlacklisted(guildId, type, id) → Check if a target is blacklisted 🔍.
• addToBlacklist(guildId, type, id) → Add a target to the blacklist ➕.
• removeFromBlacklist(guildId, type, id) → Remove a target from the blacklist ➖.
• getBlacklist(guildId, type) → Get all blacklisted items (optionally filtered by type) 📜.
• Blacklist → The Mongoose model for direct DB access 💾.

🔍 isBlacklisted – Check Status

Checks if a user, role, or channel is blacklisted.

const isBlocked = await isBlacklisted("GUILD_ID", "user", "USER_ID");
if (isBlocked) {
  console.log("User is blacklisted! 🚫");
}

➕ addToBlacklist – Block a Target

Adds a user, role, or channel to the blacklist.

await addToBlacklist("GUILD_ID", "channel", "CHANNEL_ID");
console.log("Channel blacklisted successfully! 🔒");

➖ removeFromBlacklist – Unblock a Target

Removes a user, role, or channel from the blacklist.

await removeFromBlacklist("GUILD_ID", "role", "ROLE_ID");
console.log("Role unblacklisted! 🔓");

📜 getBlacklist – List Blacklisted Items

Returns an array of blacklisted items for a guild. You can optionally filter by type (user, role, channel).

Parameters:

• guildId (String): The ID of the guild.
• type (String, optional): The type to filter by (user, role, channel).

Example:

// Get all blacklisted items
const allBlacklisted = await getBlacklist("GUILD_ID");
console.log(allBlacklisted);

// Get only blacklisted users
const blacklistedUsers = await getBlacklist("GUILD_ID", "user");
console.log(blacklistedUsers);
/*
Output:
[
  { guild: 'GUILD_ID', type: 'user', id: 'USER_ID_1', ... },
  { guild: 'GUILD_ID', type: 'user', id: 'USER_ID_2', ... }
]
*/

⚡ Practical Example: Blacklist Command

You can create a slash command to manage the blacklist easily.

const { addToBlacklist, removeFromBlacklist, isBlacklisted, getBlacklist } = require("djs-builder");
const { SlashCommandBuilder, PermissionFlagsBits, EmbedBuilder } = require("discord.js");

module.exports = {
  data: new SlashCommandBuilder()
    .setName("blacklist")
    .setDescription("Manage the blacklist")
    .setDefaultMemberPermissions(PermissionFlagsBits.Administrator)
    .addSubcommand(sub =>
      sub.setName("add").setDescription("Add to blacklist")
        .addUserOption(opt => opt.setName("user").setDescription("User to blacklist"))
        .addRoleOption(opt => opt.setName("role").setDescription("Role to blacklist"))
        .addChannelOption(opt => opt.setName("channel").setDescription("Channel to blacklist"))
    )
    .addSubcommand(sub =>
      sub.setName("remove").setDescription("Remove from blacklist")
        .addUserOption(opt => opt.setName("user").setDescription("User to remove"))
        .addRoleOption(opt => opt.setName("role").setDescription("Role to remove"))
        .addChannelOption(opt => opt.setName("channel").setDescription("Channel to remove"))
    )
    .addSubcommand(sub =>
      sub.setName("check").setDescription("Check if a target is blacklisted")
        .addUserOption(opt => opt.setName("user").setDescription("User to check"))
        .addRoleOption(opt => opt.setName("role").setDescription("Role to check"))
        .addChannelOption(opt => opt.setName("channel").setDescription("Channel to check"))
    )
    .addSubcommand(sub =>
      sub.setName("list").setDescription("List all blacklisted items")
        .addStringOption(opt => opt.setName("type").setDescription("Filter by type").addChoices({ name: "User", value: "user" }, { name: "Role", value: "role" }, { name: "Channel", value: "channel" } , { name: "All", value: "all" }))
    ),
  async run(interaction) {
    const sub = interaction.options.getSubcommand();
    const user = interaction.options.getUser("user");
    const role = interaction.options.getRole("role");
    const channel = interaction.options.getChannel("channel");
    const guildId = interaction.guild.id;

    if (sub === "list") {
        const type = interaction.options.getString("type");
        if (type !== "all") {
        const list = await getBlacklist(guildId, type);

        if (!list.length) return interaction.reply({ content: "✅ No blacklisted items found.", flags : 64 });

        const embed = new EmbedBuilder()
            .setTitle("🚫 Blacklist")
            .setColor("Red")
            .setDescription(list.map(item => `• **${item.type.toUpperCase()}**: <${item.type === 'channel' ? '#' : item.type === 'role' ? '@&' : '@'}${item.id}> (\`${item.id}\`)`).join("\n").slice(0, 4000));

        return interaction.reply({ embeds: [embed], flags : 64 });
        } else {
        const list = await getBlacklist(guildId);
        if (!list.length) return interaction.reply({ content: "✅ No blacklisted items found.", flags : 64 });

        const embeds = [];
        const roles = list.filter(i => i.type === "role");
        const users = list.filter(i => i.type === "user");
        const channels = list.filter(i => i.type === "channel");

        if (users.length) {
            const userEmbed = new EmbedBuilder()
            .setTitle("🚫 Blacklisted Users")
            .setColor("Red")
            .setDescription(users.map(item => `• <@${item.id}> (\`${item.id}\`)`).join("\n").slice(0, 4000));
            embeds.push(userEmbed);
        }
        if( roles.length) {
            const roleEmbed = new EmbedBuilder()
            .setTitle("🚫 Blacklisted Roles")
            .setColor("Red")
            .setDescription(roles.map(item => `• <@&${item.id}> (\`${item.id}\`)`).join("\n").slice(0, 4000));
            embeds.push(roleEmbed);
        }
        if( channels.length) {
            const channelEmbed = new EmbedBuilder()
            .setTitle("🚫 Blacklisted Channels")
            .setColor("Red")
            .setDescription(channels.map(item => `• <#${item.id}> (\`${item.id}\`)`).join("\n").slice(0, 4000));
            embeds.push(channelEmbed);
        }
        return interaction.reply({ embeds, flags : 64 });
    }
  }
  
    if (!user && !role && !channel) {
      return interaction.reply({ content: "⚠️ You must provide at least one option (User, Role, or Channel).", flags : 64 });
    }
    const target = user || role || channel;
    const type = user ? "user" : role ? "role" : "channel";
    const id = target.id;

    if (sub === "add") {
      const success = await addToBlacklist(guildId, type, id);
      if (success) interaction.reply(`✅ Added **${type}** ${target} to blacklist.`);
      else interaction.reply(`⚠️ **${type}** ${target} is already blacklisted.`);
    } else if (sub === "remove") {
      const success = await removeFromBlacklist(guildId, type, id);
      if (success) interaction.reply(`✅ Removed **${type}** ${target} from blacklist.`);
      else interaction.reply(`⚠️ **${type}** ${target} is not blacklisted.`);
    } else if (sub === "check") {
      const isBlocked = await isBlacklisted(guildId, type, id);
      if (isBlocked) interaction.reply(`🚫 **${type}** ${target} is currently **blacklisted**.`);
      else interaction.reply(`✅ **${type}** ${target} is **not** blacklisted.`);
    }
  }
};

🔄 Hot Reloading – Update your bot without restarting!

djs-builder allows you to reload your commands and events instantly while the bot is running. This is perfect for rapid development and fixing bugs on the fly.

📌 Features

• Prefix Commands: Reloads all prefix commands from disk.
• Slash Commands: Reloads slash command logic (internal cache).
• Events: Reloads event listeners (removes old ones, adds new ones).
• All: Reloads everything at once.

📌 Example Usage (Slash Command)

const { reload } = require("djs-builder");
const { SlashCommandBuilder } = require("discord.js");

module.exports = {
  data: new SlashCommandBuilder()
    .setName("reload")
    .setDescription("Reload bot commands/events")
    .addStringOption((option) =>
      option
        .setName("type")
        .setDescription("What to reload?")
        .setRequired(true)
        .addChoices(
          { name: "Prefix Commands", value: "prefix" },
          { name: "Slash Commands", value: "slash" },
          { name: "Events", value: "events" },
          { name: "All", value: "all" }
        )
    ),
  async run(interaction, client) {
    const type = interaction.options.getString("type");

    try {
      await interaction.deferReply();
      await reload(client, type);
      await interaction.editReply(`✅ Successfully reloaded **${type}**! 🚀`);
    } catch (error) {
      console.error(error);
      await interaction.editReply(
        "❌ Failed to reload. Check console for errors."
      );
    }
  },
};

💡 Notes

• Slash Commands: Reloading only updates the code execution. If you change the command name, description, or options, you still need to restart the bot to update Discord's API.
• Events: Old event listeners are automatically removed before adding new ones to prevent duplicates.

⚡ Commands & Events

💡 Commands & Events made easy! With djs-builder, handling commands and events is smooth, fast, and fully customizable. You get built-in features like:

• ⚠️ Anti-crash protection – your bot won’t crash unexpectedly.
• ⏳ Cooldowns – prevent spam and control usage.
• 🛡️ Permissions & owner/dev only checks – secure your commands.
• ⚡ Fast Use & custom prefixes – run commands easily across guilds.
• 📝 Logging – track every command usage for prefix or slash.

Below are all the available properties you can use for your commands and events:

⚡ COMMAND OPTIONS (Prefix & Slash)

name: 'string',                // 🏷️ Command name (required)
aliases: ['string'],           // 🔁 Alternative names (Prefix only)
description: 'string',         // ✍️ Short description of the command
cooldown: 5,                   // ⏳ Cooldown in seconds before reusing the command
Permissions: ['ADMINISTRATOR'],// 🛡️ Required permissions to execute the command
ownerOnly: true,               // 👑 Only server owner can use this command
devOnly: true,                 // 🛠️ Only bot developer can use this command
guildOnly: true,               // 🏠 Command works only in servers
dmOnly: true,                  // ✉️ Command works only in DMs
fastUse: true,                 // ⚡ Allow command to be executed without prefix (Prefix only)
Blacklist: true,               // 🚫 Check if user/role/channel is blacklisted
run: Function,                 // 🏃‍♂️ Main function to run the command
execute: Function,             // 🏃‍♂️ Alternative function to run the command

⚡ EVENT OPTIONS

name: 'string',                // 🏷️ Event name (e.g., messageCreate, guildMemberAdd)
once: true,                    // 🎯 If true, the event will be executed only once
run: Function,                 // 🏃‍♂️ Function to run when the event triggers
execute: Function              // 🏃‍♂️ Alternative function to run the event

💡 Tip: Use these properties to fully control command behavior, access, and event handling.

🌐 DASHBOARD

The Dashboard System is a modern,