Skip to content

README.md

Latest commit

 

History

History
341 lines (254 loc) · 8.64 KB

README.md

File metadata and controls

341 lines (254 loc) · 8.64 KB

🦜 Parrot Bot

A feature-rich Discord bot built with TypeScript, Discord.js v14, and Bun runtime. Designed for translation, role management, and server moderation.

Discord.js TypeScript Bun License

✨ Features

Feature Description
🌐 Translation Translate text via slash commands or context menu
🎭 Self-Roles Interactive role selection panel for members
🗣️ Language Roles Set target translation language via role buttons
🔗 URL Moderation Automatic URL detection and removal
🖼️ Avatar Fetcher Retrieve any user's profile picture by ID

📸 Preview

Context Menu Translation

Context Menu Demo

Role Selection Panel

Role Selection Demo

📁 Project Structure

Parrot-bot/
├── src/
│   ├── commands/
│   │   ├── context/          # Context menu commands
│   │   │   └── translate.ts
│   │   └── slash/            # Slash commands
│   │       ├── langpanel.ts
│   │       ├── ping.ts
│   │       ├── selfroles.ts
│   │       ├── translate.ts
│   │       └── userpfp.ts
│   ├── config/
│   │   └── env.ts            # Environment configuration
│   ├── constants/
│   │   ├── languages.ts      # Language codes & mappings
│   │   └── roles.ts          # Role configuration
│   ├── embeds/
│   │   └── translateEmbed.ts # Translation result embed
│   ├── events/
│   │   ├── interactionCreate.ts
│   │   └── messageCreate.ts
│   ├── handlers/
│   │   ├── langButtonHandler.ts
│   │   └── selfRolesHandler.ts
│   ├── services/
│   │   └── translateService.ts
│   ├── types/
│   │   ├── discord.d.ts      # Discord.js type extensions
│   │   └── index.ts          # Shared type definitions
│   ├── utils/
│   │   ├── arrays.ts
│   │   └── strings.ts
│   ├── main.ts               # Bot entry point
│   └── register.ts           # Command registration
├── .env                      # Environment variables (not committed)
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md

🚀 Getting Started

Prerequisites

  • Bun v1.0 or higher
  • Discord Bot Token (Create one here)
  • Node.js 18+ (for Discord.js compatibility)

Installation

1. Clone the repository

git clone https://github.com/your-username/parrot-bot.git
cd parrot-bot

2. Install dependencies

bun install

3. Configure environment variables

Create a .env file in the project root:

TOKEN=your_discord_bot_token
CLIENT_ID=your_application_client_id
GUILD_ID=your_development_server_id  # Optional: for guild-specific commands

4. Register commands

bun run register

5. Start the bot

bun run start

Development Mode

Run with hot reload:

bun run dev

📋 Commands

Slash Commands

Command Description Permission
/ping Check bot latency Everyone
/translate Translate text to a specified language Everyone
/stealpfp Get a user's profile picture by ID Everyone
/langpanel Post language role selection panel Administrator
/selfroles Post self-role selection panel Administrator

Context Menu Commands

Command Type Description
Translate (Target Role) Message Translate selected message based on your language role

🎮 Usage Guide

Translation

Slash Command:

/translate msg:Hello, how are you? langcode:ja

Context Menu:

  1. Right-click any message
  2. Navigate to Apps → Translate (Target Role)
  3. Translation uses your assigned language role (defaults to English)

Language Panel

Administrators can create a language selection panel:

/langpanel

Users click buttons to set their target translation language. Only one language role is active at a time.

Supported Languages:

  • 🇬🇧 English (en)
  • 🇹🇭 Thai (th)
  • 🇯🇵 Japanese (ja)
  • 🇵🇭 Filipino (fil)
  • 🇮🇩 Indonesian (id)
  • 🇪🇬 Arabic - Egyptian (ar-eg)
  • 🇬🇭 Akan (ak)
  • 🇬🇭 Ewe (ee)
  • 🇬🇭 Ga (gaa)
  • 🇬🇭 Dagbani (dag)

Self-Roles Panel

Administrators can create a role selection panel:

/selfroles
  • Users select roles from the dropdown menu
  • Press Submit to apply selected roles
  • Press Reset to clear selection
  • Developer role is auto-assigned when submitting

🛠️ Development

Adding a New Slash Command

Create a new file in src/commands/slash/:

import { SlashCommandBuilder } from "discord.js";
import type { Command } from "../../types";

export const command: Command = {
  data: new SlashCommandBuilder()
    .setName("example")
    .setDescription("An example command"),

  async execute(interaction) {
    await interaction.reply("Hello from example command!");
  },
};

Adding a Context Menu Command

Create a new file in src/commands/context/:

import {
  ApplicationCommandType,
  ContextMenuCommandBuilder,
  MessageFlags,
} from "discord.js";
import type { MessageContextMenuCommandInteraction } from "discord.js";
import type { Command } from "../../types";

export const command: Command<MessageContextMenuCommandInteraction> = {
  data: new ContextMenuCommandBuilder()
    .setName("Example Action")
    .setType(ApplicationCommandType.Message),

  async execute(interaction) {
    const message = interaction.targetMessage;
    
    await interaction.reply({
      content: `Message content: ${message.content}`,
      flags: MessageFlags.Ephemeral,
    });
  },
};

After Adding Commands

Register the new commands with Discord:

bun run register

Then restart the bot:

bun run start

📝 Scripts

Script Description
bun run start Start the bot
bun run dev Start with hot reload
bun run register Register commands to Discord
bun run test Run tests with Vitest
bun run lint Type-check with TypeScript

⚙️ Configuration

Environment Variables

Variable Required Description
TOKEN ✅ Discord bot token
CLIENT_ID ✅ Discord application ID
GUILD_ID ❌ Guild ID for dev commands (instant updates)

Role Configuration

Edit src/constants/roles.ts to customize:

  • EXCLUDED_ROLE_NAMES - Roles excluded from self-role selection
  • DEVELOPER_ROLE_NAME - Auto-assigned developer role name

Language Configuration

Edit src/constants/languages.ts to:

  • Add/remove supported languages in LANG_CODES
  • Map language codes to Google Translate codes in TRANSLATE_TARGET

🔧 Troubleshooting

Commands not appearing

  1. Ensure bun run register completed successfully
  2. Check bot has applications.commands scope
  3. Wait up to 1 hour for global commands (instant for guild commands)

Bot missing permissions

Ensure the bot role has:

  • Manage Roles - For role assignment features
  • Send Messages - For responding to commands
  • Manage Messages - For URL moderation

Translation not working

  • Google Translate API may rate-limit frequent requests
  • Check network connectivity
  • Verify the language code is valid

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m "Add: amazing feature")
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments