custom-discord-bot/README.md

A powerful, customizable Discord bot framework with embeds, cooldowns, aliases, middleware, function commands, and real-time stats — built with OceanicJS.

# Custom Discord Bot 🤖  

✅ **Free to use!**  
⚡ A powerful, feature-rich **Discord bot framework** built with Oceanic.js. Create bots in minutes with **embeds, cooldowns, aliases, function commands, middleware, real-time stats**, and more!

![NPM Version](https://img.shields.io/npm/v/custom-discord-bot?color=blue&style=flat-square)  
![Downloads](https://img.shields.io/npm/dt/custom-discord-bot?color=green&style=flat-square)  
![License](https://img.shields.io/npm/l/custom-discord-bot?style=flat-square)  

---

## 🆕 What's New in v3.0.0  

🔥 **Embed Support** – Send rich embed messages as command responses  
🔥 **Cooldown System** – Prevent command spam with configurable cooldowns  
🔥 **Command Aliases** – Multiple triggers for the same command  
🔥 **Function Commands** – Execute custom logic with `(message, args) => {}`  
🔥 **Middleware** – Intercept and filter messages before command processing  
🔥 **Dynamic Placeholders** – Use `{user}`, `{server}`, `{args}`, `{uptime}` in responses  
🔥 **Runtime Commands** – Add/remove commands while bot is running  
🔥 **Event System** – Listen to `ready`, `message`, `commandUsed`, `error`, `disconnect`  
🔥 **Bot Stats** – Track uptime, command usage, and more  
🔥 **Class-based API** – New `DiscordBot` class with full control  
🔥 **100% Backwards Compatible** – `startBot()` still works!  

---

## 📦 Installation  

```sh
npm install custom-discord-bot
```

---

## 🚀 Quick Start (Simple)  

```js
const { startBot } = require("custom-discord-bot");

startBot({
  token: "YOUR_DISCORD_BOT_TOKEN",
  prefix: "!",
  status: "online",
  statusMessage: "Listening to commands! 🎧",
  statusType: 2,
  cooldown: 3, // 3 second cooldown between commands
  commands: {
    "ping": "Pong! 🏓",
    "hello": "Hello {user}! Welcome to **{server}**! 👋",
    "say": "You said: {args}",
    "uptime": "🕐 Bot uptime: {uptime}",
  },
  aliases: {
    "p": "ping",
    "hi": "hello",
  }
});
```

---

## 🏗️ Advanced Usage (Class API)  

```js
const { DiscordBot } = require("custom-discord-bot");

const bot = new DiscordBot({
  token: "YOUR_DISCORD_BOT_TOKEN",
  prefix: "!",
  cooldown: 5,
  logCommands: true,
  commands: {
    "ping": "Pong! 🏓",
    
    // 🔥 Embed response
    "info": DiscordBot.createEmbed({
      title: "Bot Information",
      description: "I'm a powerful custom bot!",
      color: 0xff6b6b,
      fields: [
        { name: "Version", value: "3.0.0", inline: true },
        { name: "Library", value: "Oceanic.js", inline: true },
      ],
      footer: "Made with ❤️",
    }),

    // 🔥 Function command with custom logic
    "roll": (message, args) => {
      const max = parseInt(args[0]) || 6;
      const result = Math.floor(Math.random() * max) + 1;
      message.channel.createMessage({ content: `🎲 You rolled a **${result}**!` });
    },

    // 🔥 Function command with async
    "userinfo": async (message, args) => {
      const user = message.author;
      const embed = DiscordBot.createEmbed({
        title: `${user.username}'s Info`,
        thumbnail: user.avatarURL(),
        fields: [
          { name: "ID", value: user.id, inline: true },
          { name: "Created", value: new Date(user.createdAt).toLocaleDateString(), inline: true },
        ],
        color: 0x5865f2,
      });
      message.channel.createMessage({ embeds: [embed] });
    },
  },
  aliases: {
    "dice": "roll",
    "me": "userinfo",
  },
});

// 📡 Event listeners
bot.on("ready", (client) => {
  console.log(`Connected to ${client.guilds.size} servers!`);
});

bot.on("commandUsed", ({ command, user, args }) => {
  console.log(`📊 ${user} used !${command} with args: [${args}]`);
});

bot.on("error", (err) => {
  console.error("Bot error:", err.message);
});

// 🚀 Start the bot
bot.start();

// ➕ Add commands at runtime
setTimeout(() => {
  bot.addCommand("late", "I was added after the bot started! ⏰", ["delayed"]);
}, 5000);
```

---

## 📌 Configuration Options  

| Option | Type | Default | Description |
|---|---|---|---|
| `token` | string | *Required* | Your Discord bot token |
| `prefix` | string | `"!"` | Command prefix |
| `status` | string | `"online"` | Bot status (`online`, `dnd`, `idle`) |
| `statusMessage` | string | `""` | Custom status message |
| `statusType` | number | `0` | Activity type (0: Playing, 1: Streaming, 2: Listening, 3: Watching) |
| `avatarUrl` | string | `""` | Bot avatar URL |
| `username` | string | `""` | Bot username |
| `commands` | object | `{}` | Commands `{ "cmd": "response" \| embedObj \| function }` |
| `aliases` | object | `{}` | Aliases `{ "alias": "originalCommand" }` |
| `cooldown` | number | `0` | Cooldown per user per command in seconds |
| `onReady` | function | `null` | Callback when bot is ready |
| `onMessage` | function | `null` | Message middleware (return `false` to block) |
| `onError` | function | `null` | Custom error handler |
| `autoReconnect` | boolean | `true` | Auto-reconnect on disconnect |
| `logCommands` | boolean | `true` | Log command usage to console |

---

## 🧩 Response Types  

### String Response (with placeholders)
```js
"Hello {user}! Welcome to {server}!"
```
Available: `{user}`, `{server}`, `{args}`, `{uptime}`

### Embed Response
```js
DiscordBot.createEmbed({
  title: "My Embed",
  description: "Rich embed content",
  color: 0xff0000,
  fields: [{ name: "Field", value: "Value", inline: true }],
  footer: "Footer text",
  thumbnail: "https://example.com/image.png",
  image: "https://example.com/banner.png",
})
```

### Function Response
```js
(message, args) => {
  message.channel.createMessage({ content: `You said: ${args.join(" ")}` });
}
```

---

## 📊 Bot Stats  

```js
const stats = bot.getStats();
console.log(stats);
// { uptime: "2h 15m 30s", totalCommands: 142, commandBreakdown: { ping: 50, hello: 92 }, ... }
```

---

## 🛠️ Contributing  
Pull requests are welcome! Fork the repo, create a branch, and submit a PR. 🚀  

---

## 📜 License  
This project is licensed under the **MIT License**.  

---

## 🌟 Support & Contact  
- **GitHub Issues:** [Report Bugs or Request Features](https://github.com/utkuberkaykoc/custom-discord-bot/issues)  
- **Give a Star:** ⭐ If you love this package, show some support!  

🚀 **Now go build something awesome!** 🎮✨