djs-builder 0.6.31 → 0.6.33

package/README.md

@@ -541,6 +541,164 @@ module.exports = {
 
 ---
 
+<details>
+
+<summary> Level System 🏆 </summary>
+
+---
+
+## 🏆 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! 🎮✨
+
+---
+
+### 📦 Module Exports
+
+```js
+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**.
+
+```js
+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**.
+
+```js
+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.
+
+```js
+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
+
+```js
+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.
+
+---
+
+</details>
+
+---
+
 ## ⚡ Commands & Events
 
 ---

package/function/level.js

@@ -0,0 +1,76 @@
+const { Schema, model } = require("mongoose");
+
+const levelSchema = new Schema({
+  userId: String,
+  guildId: String,
+  text: { type: Number, default: 0 },
+  voice: { type: Number, default: 0 },
+  totalXP: { type: Number, default: 0 },
+  level: { type: Number, default: 0 },
+});
+
+const Level = model("Level", levelSchema);
+
+function randomXP(min, max) {
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+async function addXP(userId, guildId, options = {}) {
+  let data = await Level.findOne({ userId, guildId });
+  if (!data) {
+    data = new Level({ userId, guildId });
+  }
+
+  const oldLevel = data.level || 0;
+  let leveledUp = false;
+
+  ////////////////////////////////! 🎲 XP
+  const xpToAdd =
+    options.amount_add ?? randomXP(options.minXP || 5, options.maxXP || 12);
+
+  data[options.type || "text"] += xpToAdd;
+  data.totalXP += xpToAdd;
+
+  ////////////////////////////////! 🎯 Level boost
+  if (options.level_add) {
+    data.level += options.level_add;
+    leveledUp = true;
+  }
+
+  ////////////////////////////////! check level ✅
+  const needed = (data.level + 1) * 100;
+  if (data.totalXP >= needed) {
+    data.level++;
+    leveledUp = true;
+  }
+
+  await data.save();
+
+  return {
+    newLevel: data.level,
+    oldLevel,
+    totalXP: data.totalXP,
+    leveledUp,
+  };
+}
+
+////////////////////////////////! user data 🧑‍🤝‍🧑
+async function UserLevel(userId, guildId) {
+  return (
+    (await Level.findOne({ userId, guildId })) || {
+      text: 0,
+      voice: 0,
+      totalXP: 0,
+      level: 0,
+    }
+  );
+}
+
+////////////////////////////////! 🏆 اtop
+async function leaderboard(guildId, type = "totalXP", limit = 10) {
+  return await Level.find({ guildId })
+    .sort({ [type]: -1 })
+    .limit(limit);
+}
+
+module.exports = { addXP, UserLevel, leaderboard };

package/handler/helper.js

@@ -89,7 +89,7 @@ async function terminalInfo(client, options, data) {
     [rowColors[4]("Prefix Commands"), rowColors[4](data.prefix)],
     [rowColors[5]("Slash Commands"), rowColors[5](data.slash)],
     [rowColors[6]("Total Commands"), rowColors[6](data.slash + data.prefix)],
-    [rowColors[7]("Events"), rowColors[7](data.event)],
+    [rowColors[7]("Events"), rowColors[7](data.events)],
     [rowColors[8]("Started At"), rowColors[8](new Date().toLocaleString())]
   );
 

package/handler/starter.js

@@ -9,7 +9,7 @@ const {
 let termenal = {
   prefix: 0,
   slash: 0,
-  event: 0,
+  events: 0,
 };
 
 async function starter(client, options) {
@@ -144,7 +144,7 @@ async function starter(client, options) {
         });
       }
 
-      termenal.event++;
+      termenal.events++;
     }
   }
 
@@ -351,6 +351,7 @@ client.on("messageCreate", async (message) => {
 }
 
 const { Wait, CreateBar, CreateRow, GetUser } = require("../function/function");
+const { addXP, UserLevel, leaderboard } = require("../function/level");
 const { log } = require("../function/log");
 
-module.exports = { starter, log, Wait, CreateBar, CreateRow, GetUser };
+module.exports = { starter, log, Wait, CreateBar, CreateRow, GetUser, addXP, UserLevel, leaderboard };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "djs-builder",
-  "version": "0.6.31",
-  "note": "🎉 Package Update! 🥏\n- Add option `disabled` to the selectMenu options \nNew features added:\n- `GetUser`: Easily fetch a user from **ID**, **mention**, or even from a **reply**.\n\n🛠 Fixes:\n- Minor bugs fixed\n- Improved stability and error handling\n- Custom prefix : add custom prefix for etch server\n\n🔗 Learn more on [NPM](https://www.npmjs.com/package/djs-builder)",
+  "version": "0.6.33",
+  "note": "🎉 Package Update! 🥏\n- Add Level System 🏆 \n\n- 🛠 Fixes:\n- Minor bugs fixed\n- Improved stability and error handling\n- Custom prefix : add custom prefix for etch server\n\n🔗 Learn more on [NPM](https://www.npmjs.com/package/djs-builder)",
   "description": "🎉 Package Update! 🥏",
   "main": "handler/starter.js",
   "dependencies": {