djs-builder 0.6.401 → 0.7.1

package/README.md

@@ -9,9 +9,10 @@ Boost your Discord bot development with ease, speed, and all-in-one features.
 
 ## 📑 Table of Contents
 
-1. 🎯 [Starter](#starter) – Initialize your bot with commands, events, presence, and more.
-2. ⚙️ [Functions](#function) – Utilities like CreateRow, CreateBar, Wait, and GetUser.
-3. ⚡ [Commands & Events](#commands--events) – Easy setup with cooldowns, permissions, logging, and anti-crash.
+1. 🎯 [Starter](#-starter) – Initialize your bot with commands, events, presence, and more.
+2. ⚙️ [Functions](#%EF%B8%8F-functions) – Utilities like CreateRow, CreateBar, Wait, and GetUser.
+3. ⚡ [Commands & Events](#-commands--events) – Easy setup with cooldowns, permissions, logging, and anti-crash.
+4. 🌐 [Dashboard](#-dashboard) – Web-based control panel for managing your bot.
 
 ---
 
@@ -69,6 +70,15 @@ const starterOptions = {
     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
@@ -130,6 +140,14 @@ await starter(client, starterOptions);
 
 - 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](#-dashboard)
+
 ---
 
 ### 💡 Tips
@@ -552,9 +570,7 @@ module.exports = {
 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**: You can get all data by requiring the **Level** module.
+> **Note**: To use this module, you **MUST** have **DATABASE** conection. | **Note 2**: You can get all data by requiring the **Level** module.
 
 ---
 
@@ -708,9 +724,7 @@ module.exports = {
 
 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**: You can get all data by requiring the **giveaway** module.
+> **Note**: To use this module, you **MUST** have **DATABASE** conection. | **Note 2**: You can get all data by requiring the **giveaway** module.
 
 ---
 
@@ -799,7 +813,7 @@ module.exports = {
   description: "Starts a new highly-customized giveaway.",
   run: async (client, message, args) => {
     // ⏰ Giveaway ends in 48 hours
-    const twoDays = 48 * 60 * 60 * 1000;
+    const twoDays = Date.now() + (48 * 60 * 60 * 1000);
     const channelId = 'YOUR_GIVEAWAY_CHANNEL_ID'; // 📢 Target Channel
 
     await Gstart({
@@ -811,17 +825,17 @@ module.exports = {
       // 🎨 Customization for the STARTING EMBED
       embed: {
 
-            custom: new EmbedBuilder().setTitle("Raw Embed").toJSON(),// 💡 You can use 'custom' to pass a raw Discord.js EmbedBuilder JSON
+            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: "https://yourimage.com/banner.png", // image URL
             thumbnail: message.guild.iconURL(),
       },
 
       // 🛑 Customization for the ENDED EMBED
       endEmbed: {
-            custom: new EmbedBuilder().setTitle("Raw Embed").toJSON(),// 💡 You can use 'custom' to pass a raw Discord.js EmbedBuilder JSON
+            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",
@@ -834,9 +848,13 @@ module.exports = {
         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: "giveaway", // Custom ID for the button
-
+        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!");
   },
@@ -867,6 +885,11 @@ This module requires specific setup steps to function correctly. Pay attention t
   - 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.
+
 </details>
 
 ---
@@ -1076,27 +1099,37 @@ module.exports = {
   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.user.id,
+        interaction.guild 
       );
 
-      if (result?.error === "❌ User Already Joined") {
-        // User already joined, offer a 'Leave' button dynamically
-        const row = await CreateRow([
-          [
-            {
-              label: "Leave Giveaway",
-              id: "djs-builder-giveaway-leave-" + interaction.message.id, // Dynamic ID
-              style: 4, // Danger Red
-            },
-          ],
-        ]);
+      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:
-            "⚠️ You have **already joined** this giveaway! You can **leave** by clicking the button below.",
-          components: row,
-          flags: 64, // Ephemeral reply
+            content: result.error,
+            flags: 64
         });
       }
 
@@ -1106,6 +1139,7 @@ module.exports = {
       });
     }
 
+
     // 2. Handle Leave Button Click (Dynamically Generated ID)
     if (
       interaction.customId &&
@@ -1208,8 +1242,9 @@ if (giveawayData) {
   "channelId": "876543210987654321", // 📢 Channel ID
   "messageId": "987654321098765432", // 💬 Message ID of the giveaway post
   "hoster": "112233445566778899", // 👤 User ID of the giveaway host
-  "winwesNumber": 1, // 🔢 Number of winners set
-  "winers": [], // 🏆 Array of user IDs who won (empty if not ended)
+"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
@@ -1223,7 +1258,7 @@ if (giveawayData) {
     "fields": [
       {
         "name": "🎉 Giveaway",
-        "value": "- Winer(s): 1\n- Time : <t:1730995200:R>\n- Hosted By : <@112233445566778899>",
+        "value": "- Winner(s): 1\n- Time : <t:1730995200:R>\n- Hosted By : <@112233445566778899>",
         "inline": true
       }
     ]
@@ -1499,6 +1534,7 @@ module.exports = {
         channelId: channel.id,
         winers: winnerCount,
         endTime: endTimeMs,
+        prize : prize,
         embed: {
           title: `🎉 ${prize} Giveaway!`,
           image: image,
@@ -1550,7 +1586,7 @@ module.exports = {
           content: `${title}\n\n${listContent}`,
         });
       } else if (listContent.length <= MAX_EMBED_LENGTH) {
-        // Output as an Embed (Over 2000, under 4096)
+        // Output as an Embed (Over 2000, under 4000)
         const embed = new EmbedBuilder()
           .setTitle(title.replace(/\*\*/g, ""))
           .setDescription(listContent)
@@ -1561,7 +1597,7 @@ module.exports = {
           embeds: [embed],
         });
       } else {
-        // Output as an attachment/JSON file (Over 4096 chars)
+        // 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` }
@@ -1768,10 +1804,13 @@ module.exports = {
 
 </details>
 
+---
+
 </details>
 
 ---
 
+
 <details>
 <summary>Blacklist System 🚫</summary>
 
@@ -1779,9 +1818,7 @@ module.exports = {
 
 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**: To use this module, you **MUST** have **DATABASE** connection.
-
-> **Note**: You can get all data by requiring the **Blacklist** module.
+> **Note 1**: To use this module, you **MUST** have **DATABASE** connection. | **Note 2**: You can get all data by requiring the **Blacklist** module.
 
 ---
 
@@ -1920,7 +1957,7 @@ module.exports = {
         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, 4096));
+            .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 {
@@ -1936,21 +1973,21 @@ module.exports = {
             const userEmbed = new EmbedBuilder()
             .setTitle("🚫 Blacklisted Users")
             .setColor("Red")
-            .setDescription(users.map(item => `• <@${item.id}> (\`${item.id}\`)`).join("\n").slice(0, 4096));
+            .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, 4096));
+            .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, 4096));
+            .setDescription(channels.map(item => `• <#${item.id}> (\`${item.id}\`)`).join("\n").slice(0, 4000));
             embeds.push(channelEmbed);
         }
         return interaction.reply({ embeds, flags : 64 });
@@ -2111,6 +2148,218 @@ execute: Function              // 🏃‍♂️ Alternative function to run the
 
 ---
 
+## 🌐 DASHBOARD
+
+The **Dashboard System** is a modern, lightweight web-based control panel for your Discord bot. It provides a beautiful interface to manage your bot, servers, levels, giveaways, and more! 🎛️🚀
+
+**Features:**
+
+- 🔐 **Discord OAuth2 Login** – Secure authentication with Discord.
+- 📊 **Bot Statistics** – View real-time bot stats (servers, users, commands, uptime).
+- 🏠 **Server Management** – Manage servers where you have admin permissions.
+- 📜 **Commands Viewer** – Browse all slash and prefix commands.
+- 🏆 **Level System Management** – View leaderboards, manage user XP and levels.
+- 🎉 **Giveaway Control** – Pause, resume, end, reroll, or delete giveaways.
+- 🚫 **Blacklist Management** – Add/remove users, roles, or channels from blacklist.
+- 🎨 **Modern UI** – Beautiful, responsive design with dark mode support.
+
+> **Note**: This module requires **express**, **express-session**, **passport**, and **passport-discord** packages. | **Note 2**: You must have a **DATABASE** connection for full functionality.
+
+> 💡 **Tip:** You can use Dashboard with the starter function (see [Starter](#starter)) or as a standalone function!
+
+---
+
+<details>
+<summary>Dashboard with Starter ⚙️</summary>
+
+When using with starter, simply add the `dashboard` option to your starter configuration:
+
+```js
+const { starter } = require("djs-builder");
+const { Client, GatewayIntentBits } = require("discord.js");
+
+const client = new Client({
+  intents: Object.keys(GatewayIntentBits).map((a) => GatewayIntentBits[a]),
+});
+
+const starterOptions = {
+  bot: {
+    token: "YOUR_BOT_TOKEN",
+    ownerId: "YOUR_USER_ID",
+  },
+  terminal: true,
+
+  // 🌐 Dashboard Configuration
+  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)
+  },
+
+  // ... other options (Status, database, anticrash, etc.)
+};
+
+await starter(client, starterOptions);
+```
+
+</details>
+
+---
+
+<details>
+<summary>Dashboard Standalone Usage 🔧</summary>
+
+You can use the Dashboard as a **standalone function** without the starter! This is useful if you already have your own bot setup or want more control.
+
+```js
+const { dashboard } = require("djs-builder");
+const { Client, GatewayIntentBits } = require("discord.js");
+
+const client = new Client({
+  intents: Object.keys(GatewayIntentBits).map((a) => GatewayIntentBits[a]),
+});
+
+// 🔑 Login your bot first
+client.login("YOUR_BOT_TOKEN");
+
+client.once("ready", () => {
+  console.log(`✅ Logged in as ${client.user.tag}`);
+
+  // 🌐 Start the Dashboard
+  dashboard(client, {
+    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)
+  });
+});
+```
+
+> 💡 **Tip:** When using standalone, make sure your bot is logged in before starting the dashboard!
+
+</details>
+
+---
+
+<details>
+<summary>Dashboard Routes & API 📡</summary>
+
+### 📌 Dashboard Routes
+
+| Route | Description |
+|-------|-------------|
+| `/` | 🏠 Homepage with bot stats |
+| `/login` | 🔐 Login page |
+| `/dashboard` | 📊 Server selection |
+| `/dashboard/:guildId` | 🏠 Server overview |
+| `/dashboard/:guildId/commands` | 📜 Commands list |
+| `/dashboard/:guildId/levels` | 🏆 Level leaderboard |
+| `/dashboard/:guildId/giveaways` | 🎉 Giveaway management |
+
+---
+
+### 📡 API Endpoints
+
+The dashboard exposes several API endpoints for dynamic data:
+
+```js
+// 📊 Get bot statistics
+GET /api/stats
+
+// 🏠 Get server statistics
+GET /api/:guildId/stats
+
+// 👤 Get user level data
+GET /api/:guildId/user/:userId
+
+// 🔍 Search members
+GET /api/:guildId/members/search?q=query
+
+// 🏆 Level management
+POST /api/:guildId/level/update   // Update user level
+POST /api/:guildId/level/add      // Add XP to user
+POST /api/:guildId/level/reset    // Reset user level
+
+// 🎉 Giveaway actions
+POST /api/:guildId/giveaway/pause
+POST /api/:guildId/giveaway/resume
+POST /api/:guildId/giveaway/end
+POST /api/:guildId/giveaway/reroll
+POST /api/:guildId/giveaway/delete
+
+// 🚫 Blacklist management
+POST /api/guild/:guildId/blacklist    // Add to blacklist
+DELETE /api/guild/:guildId/blacklist  // Remove from blacklist
+```
+
+</details>
+
+---
+
+<details>
+<summary>Dashboard Options 🔧</summary>
+
+### 🔧 Configuration Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `clientID` | `string` | ✅ | 🔑 Your Discord Application Client ID |
+| `clientSecret` | `string` | ✅ | 🔐 Your Discord Application Client Secret |
+| `callbackURL` | `string` | ✅ | 🔗 OAuth2 redirect URL (must match Discord settings) |
+| `sessionSecret` | `string` | ✅ | 🔒 Secret key for session encryption |
+| `port` | `number` | ❌ | 🌍 Port to run the dashboard (default: 3000) |
+
+---
+
+### 📁 View Templates
+
+The dashboard uses **EJS** templates located in the `views` folder:
+
+| File | Description |
+|------|-------------|
+| `index.ejs` | 🏠 Homepage |
+| `login.ejs` | 🔐 Login page |
+| `dashboard.ejs` | 📊 Server selection |
+| `guild.ejs` | 🏠 Server overview |
+| `commands.ejs` | 📜 Commands list |
+| `levels.ejs` | 🏆 Level management |
+| `giveaways.ejs` | 🎉 Giveaway management |
+| `404.ejs` | ❌ Not found page |
+
+</details>
+
+---
+
+<details>
+<summary>Discord Developer Portal Setup 🛠️</summary>
+
+### 🛠️ How to Get Client ID & Secret
+
+1. Go to [Discord Developer Portal](https://discord.com/developers/applications) 🌐
+2. Create a new application or select existing one 📱
+3. Go to **OAuth2** → **General** 🔐
+4. Copy the **Client ID** and **Client Secret** 📋
+5. Add your **Redirect URL** (e.g., `http://localhost:3000/auth/discord/callback`) ✅
+6. Make sure to add the URL to **Redirects** list 📝
+
+---
+
+### 💡 Tips & Notes
+
+- 🔒 **Keep secrets safe** – Never expose `clientSecret` or `sessionSecret` publicly.
+- 🌐 **Production URL** – Update `callbackURL` when deploying to production.
+- 🗄️ **Database Required** – Level and Giveaway features require MongoDB connection.
+- 🎨 **Customizable** – Edit EJS templates to customize the look and feel.
+- 🔄 **Real-time Stats** – Bot statistics update automatically.
+- 🛡️ **Secure** – Only admins can manage their servers.
+
+</details>
+
+---
+
 ## 💌 Support
 
 We welcome contributions! If you have any suggestions, bug reports, or feature requests, feel free to reach out to us on Discord.