# bot-discordbot

Discord bot built with `discord.js`, `distube`, and `TypeScript` for discord servers.

---

## ⚡ Quick Start

```bash
git clone https://github.com/totalo-dev/botdiscord.git
cd botdiscord
npm install
```

Create `.env` in the root:
```env
DISCORD_TOKEN=your_token_here
```

Enable in [Discord Developer Portal](https://discord.com/developers/applications) → Bot → Privileged Gateway Intents:
- ✅ **MESSAGE CONTENT INTENT**
- ✅ **SERVER MEMBERS INTENT**

```bash
npm run dev       # development
npm run build && npm start  # production
```

> Full setup guide below ↓

---

## Installation

### 1. Clone the repository

```bash
git clone https://github.com/totalo-dev/botdiscord.git
cd botdiscord
```

### 2. Install dependencies

```bash
npm install
```

### 3. Create the `.env` file

Create a `.env` file in the root of the project with the following content:

```env
DISCORD_TOKEN=your_token_here
```

> The bot token is obtained from the Discord Developer Portal: [https://discord.com/developers/applications](https://discord.com/developers/applications)

---

### 4. Configure Discord Privileged Intents

The bot requires **2 mandatory Gateway Intents** to be enabled in the Discord Developer Portal.

Go to [https://discord.com/developers/applications](https://discord.com/developers/applications) → select your application → **Bot** → scroll to **Privileged Gateway Intents** and enable:

| Intent | Required for |
| ------ | ------------ |
| **MESSAGE CONTENT INTENT** | Reading message content to process prefix commands (`<command`). Without this, the bot starts but never responds to any command. |
| **SERVER MEMBERS INTENT** | `guildMemberAdd` (auto-role), `guildMemberRemove` (member log), and accurate member counts in `<serverinfo`. Without this, these features are completely non-functional. |
| **PRESENCE INTENT** | Not required — can be left disabled. |

> ⚠️ **Both MESSAGE CONTENT and SERVER MEMBERS intents are mandatory.** The bot will connect to Discord without them but will be completely unresponsive.

---

### 5. Invite scopes and slash commands

When adding the bot to a server, the OAuth2 invite must include both scopes:

| Scope | Required for |
| ----- | ------------ |
| `bot` | Bot connection, permissions, messages, moderation, voice, and events |
| `applications.commands` | Slash commands (`/command`) |

Slash commands are registered automatically when the bot starts. They are currently registered globally through Discord, so new or changed commands can take a while to appear in servers.

Most commands are available both as prefix commands (`<command`) and slash commands (`/command`). At the moment, `memberlog`, `welcome`, and `poll` are prefix-only.

---

### 6. (Optional) YouTube cookies

To avoid YouTube blocking issues in production, create a `cookies.json` file in the root of the project with your YouTube account cookies.

Use `cookies.example.json` as a reference for the correct format.

> Never commit `cookies.json` (already included in `.gitignore`).
> Use a dedicated Google account — never your personal account.

---

### 7. Start the bot

**Development mode:**

```bash
npm run dev
```

**Production mode:**

```bash
npm run build
npm start
```

---

## Automatically created files

| File                        | Created when                   |
| --------------------------- | ------------------------------ |
| `data/xp.json`              | First user gains XP            |
| `data/reminders.json`       | First reminder is set          |
| `data/blockedChannels.json` | First channel is blocked       |
| `data/autoRoles.json`       | First auto-role is set         |
| `data/memberLog.json`       | First member log is configured |
| `data/welcome.json`         | First welcome is configured    |

---

## Project structure

```
botdiscord/
├── src/
│   ├── commands/
│   ├── config/
│   ├── events/
│   ├── services/
│   ├── utils/
│   └── index.ts
├── data/
├── .env
├── cookies.json          (optional)
├── cookies.example.json
├── tsconfig.json
└── package.json
```

---

## Features

### Slash commands
- All commands support both prefix (`<comando`) and slash commands (`/comando`)
- Slash commands are registered globally on startup
- Slash commands respect the same cooldowns, admin-only restrictions and channel blocking as prefix commands

### XP & Rank system
- Users automatically gain XP (15–25) by sending messages, with a 60s cooldown per user
- XP formula to level up: `100 × level²`
- On level up, the bot sends a congratulations DM to the user
- Persistent across restarts (`data/xp.json`)

### Reminders
- Users can set DM reminders with a time and message
- Supports `s`, `m`, `h`, `d` time formats — maximum 7 days
- Reminders persist across restarts and fire immediately if missed (`data/reminders.json`)

### Auto-role
- Automatically assigns a configured role to every new member that joins
- Configured per server by admins
- Persistent across restarts (`data/autoRoles.json`)

### Member log
- Logs member departures to a configured text channel
- Shows username, ID, join date, roles held, and remaining member count
- Can be enabled/disabled per server by admins — no cache is accumulated when disabled
- Persistent across restarts (`data/memberLog.json`)

### Welcome messages
- Sends a customizable welcome message when a new member joins
- Configured per server by admins via `<welcome #channel [message]`
- Supports `{user}` and `{server}` placeholders in the message
- Can be enabled/disabled independently — no cache when disabled
- Persistent across restarts (`data/welcome.json`)

### Channel blocking
- Admins can block specific channels so the bot ignores non-admin commands there
- Admins are always exempt and can use all commands in blocked channels
- Persistent across restarts (`data/blockedChannels.json`)

---

## Available commands

Commands listed below use the prefix form. All commands are also available as slash commands (`/ping`, `/play`, `/rank`, etc.).

### General

| Command              | Alias            | Cooldown | Description       |
| -------------------- | ---------------- | -------- | ----------------- |
| `<ping`              | `<p`             | 3s       | Check bot latency |
| `<help`              | `<h`, `<ajuda`   | 5s       | List all commands |
| `<avatar [@user]`    | `<av`            | 5s       | Show user avatar  |
| `<userinfo [@user]`  | `<ui`, `<user`   | 5s       | User info         |
| `<serverinfo`        | `<si`, `<server` | 5s       | Server info       |

---

### Voice 🔒

| Command           | Alias           | Cooldown | Description         |
| ----------------- | --------------- | -------- | ------------------- |
| `<enter {name}`   | `<e`, `<join`   | 1s       | Join voice channel  |
| `<getout`         | `<go`, `<leave` | 1s       | Leave voice channel |

---

### Music

| Command             | Alias         | Cooldown | Description          |
| ------------------- | ------------- | -------- | -------------------- |
| `<play {name/url}`  | `<pl`         | 3s       | Play YouTube music   |
| `<pause`            | `<pa`         | 3s       | Pause music          |
| `<resume`           | `<re`         | 3s       | Resume music         |
| `<skip`             | `<sk`, `<s`   | 3s       | Skip current song    |
| `<stop`             | `<st`         | 3s       | Stop and clear queue |
| `<loop`             | `<l`          | 3s       | Toggle loop mode     |
| `<queue`            | `<q`, `<fila` | 5s       | Show queue           |
| `<nowplaying`       | `<np`         | 5s       | Current song info    |

---

### Moderation 🔒

| Command                | Alias        | Cooldown | Description                          |
| ---------------------- | ------------ | -------- | ------------------------------------ |
| `<ban @user [reason]`  | `<b`         | 1s       | Ban a member                         |
| `<unban {id} [reason]` | `<ub`        | 1s       | Remove a ban by user ID              |
| `<clear {1-100}`       | `<cl`        | 1s       | Delete messages                      |
| `<blockchat`           | `<bc`        | 1s       | Block current channel for the bot    |
| `<blockchat off`       | —            | —        | Unblock current channel              |
| `<blockchat list`      | —            | —        | List all blocked channels            |
| `<autorole @role`      | `<ar`        | 1s       | Set auto-role for new members        |
| `<autorole off`        | —            | —        | Remove auto-role                     |
| `<autorole`            | —            | —        | Show current auto-role               |
| `<memberlog #channel`  | `<ml`        | 1s       | Enable member leave log in a channel |
| `<memberlog off`       | —            | —        | Disable member log                   |
| `<memberlog`           | —            | —        | Show current member log status       |
| `<welcome #channel`    | `<wc`        | 1s       | Enable welcome messages              |
| `<welcome off`         | —            | —        | Disable welcome messages             |
| `<welcome`             | —            | —        | Show current welcome config          |

---

### Rank & XP

| Command           | Alias       | Cooldown | Description       |
| ----------------- | ----------- | -------- | ----------------- |
| `<rank`           | `<r`, `<xp` | 10s      | Your level and XP |
| `<rank [@user]`   | —           | —        | Another user's profile |
| `<rank top`       | —           | —        | Server top 10     |

---

### Utility

| Command                  | Alias              | Cooldown | Description        |
| ------------------------ | ------------------ | -------- | ------------------ |
| `<remind {time} {msg}`   | `<rm`, `<lembrete` | 30s      | DM reminder        |
| `<coinflip`              | `<cf`, `<moeda`    | 3s       | Flip a coin        |
| `<poll {question}`       | `<votacao`, `<voto` | 10s      | Create a poll      |
| `<botinfo`               | `<bi`, `<info`     | 10s      | Bot technical info |
| `<donate`                | `<d`, `<apoiar`    | 10s      | Support the bot    |

> 🔒 Admin-only commands require the **Administrator** permission.

---

## Additional resources

- 📄 [VPS deployment guide](docs/guia-para-subir-em-vps.pdf)

---

## Main dependencies

| Package | Purpose |
| ------- | ------- |
| `discord.js` | Discord API client |
| `distube` | Music playback engine |
| `@distube/youtube` | YouTube plugin for DisTube |
| `@discordjs/voice` | Voice channel connections |
| `ffmpeg-static` | Bundled FFmpeg binary |
| `dotenv` | Environment variable loader |
| `typescript` | TypeScript compiler |
| `ts-node-dev` | Development runner with hot reload |

---

© 2026 Totalo — All rights reserved.