# twitter_v3 — discord moderation bot

a discord.js v14 bot base using traditional prefix commands (no slash commands) and structured winston logging.

---

## features

- prefix command system — commands triggered by a configurable prefix (default `!`)
- auto-loading — commands and events are loaded automatically from their folders
- aliases — each command can define one or more aliases
- winston logging — coloured console output + rolling log files (`logs/combined.log`, `logs/error.log`)
- global error handling — unhandled rejections and uncaught exceptions are caught and logged

---

## project structure

```
src/
├── index.js               # entry point — creates the client, loads handlers
├── commands/
│   ├── help.js            # !help — lists commands or shows command detail
│   └── ping.js            # !ping — latency check
├── events/
│   ├── ready.js           # fires once when the bot is online
│   └── messageCreate.js   # parses every message for prefix commands
├── handlers/
│   ├── commandHandler.js  # reads src/commands/ and registers commands
│   └── eventHandler.js    # reads src/events/ and registers discord events
└── utils/
  └── logger.js          # winston logger instance
logs/                      # created automatically at runtime (git-ignored)
```

---

## setup

### 1. clone & install dependencies

```bash
git clone https://github.com/yhqe/twitter_v3.git
cd twitter_v3
npm install
```

### 2. configure environment variables

```bash
cp .env.example .env
```

open `.env` and fill in:

| variable    | required | description                                          |
|-------------|----------|------------------------------------------------------|
| `BOT_TOKEN` | yes      | your bot token from the discord developer portal     |
| `PREFIX`    | no       | command prefix (default: `!`)                        |
| `GUILD_ID`  | no       | test server id (handy for dev stuff)                 |

### 3. enable the message content intent

go to your application in the [discord developer portal](https://discord.com/developers/applications), open **bot → privileged gateway intents**, and enable **message content intent**. you need this for prefix commands.

### 4. start the bot

```bash
# production
npm start

# development (auto-restarts on file changes, node.js 18+)
npm run dev
```

---

## adding commands

create a file in `src/commands/`. the handler will load it automatically on next start.

```js
'use strict';

module.exports = {
  name: 'example',           // primary command name (also used as the key)
  description: 'An example command.',
  aliases: ['ex'],           // optional aliases
  usage: 'example <text>',   // shown in !help example

  async execute(client, message, args) {
  await message.reply(`You said: ${args.join(' ')}`);
  },
};
```

## adding events

create a file in `src/events/`. set `once: true` if it should fire only once (e.g. `ready`).

```js
'use strict';

const { Events } = require('discord.js');

module.exports = {
  name: Events.GuildMemberAdd,

  async execute(client, member) {
  console.log(`${member.user.tag} joined ${member.guild.name}`);
  },
};
```

---

## logging

log files are written to the `logs/` directory (git-ignored). the log level defaults to `info` and can be overridden with the `LOG_LEVEL` environment variable (e.g. `LOG_LEVEL=debug npm start`).