Discord Bot Utils

A comprehensive utility package for Discord.js bots that provides advanced features and helpers to make bot development easier and more efficient.

Features

Preset Commands

• Ready-to-use moderation commands (kick, ban)
• Utility commands (ping, avatar, shortlink)
• Automatic permission handling
• Embedded responses
• Command usage tracking

Embed Utilities

• Basic, Error, Success, Warning, and Info embeds
• Custom embeds with full customization
• Server and User info embeds
• Loading embeds

Button Utilities

• Custom button creation
• Button rows and menus
• Confirmation buttons
• Poll buttons
• Link buttons
• Menu buttons

Pagination Utilities

• Standard pagination with navigation
• Custom page indicators
• Menu-based pagination
• Configurable timeouts and labels

Message Utilities

• Temporary messages
• Delayed message editing
• Progress bars
• Typing effects
• Countdown timers
• Reaction collectors

Tax Utilities

• Fixed and user-defined tax rate calculations
• Embed and message display options
• Customizable tax rate presets
• Automatic total calculation

Command Handler Utilities

• Permission validation
• Cooldown management
• Command usage tracking
• Command statistics
• Role hierarchy checking
• Role requirement validation

Installation

npm install @ZerroDevs/discord-bot-utils

Usage Examples

Embed Utilities

const { EmbedUtil } = require('@ZerroDevs/discord-bot-utils');

// Create different types of embeds
const successEmbed = EmbedUtil.createSuccessEmbed('Operation completed!');
const errorEmbed = EmbedUtil.createErrorEmbed('Something went wrong!');
const warningEmbed = EmbedUtil.createWarningEmbed('Please be careful!');
const infoEmbed = EmbedUtil.createInfoEmbed('Here is some information');
const loadingEmbed = EmbedUtil.createLoadingEmbed('Processing...');

// Create server/user info embeds
const serverEmbed = EmbedUtil.createServerInfoEmbed(guild);
const userEmbed = EmbedUtil.createUserInfoEmbed(member);

// Create custom embed
const customEmbed = EmbedUtil.createCustomEmbed({
	title: 'Custom Title',
	description: 'Custom Description',
	fields: [{ name: 'Field', value: 'Value', inline: true }],
	thumbnail: 'thumbnail_url',
	image: 'image_url',
	footer: { text: 'Footer text' },
	author: { name: 'Author name' }
});

Button Utilities

const { ButtonUtil } = require('@ZerroDevs/discord-bot-utils');

// Create confirmation buttons
const confirmRow = ButtonUtil.createConfirmationButtons();

// Create custom button
const button = ButtonUtil.createButton({
	label: 'Click me!',
	style: ButtonStyle.Primary,
	customId: 'custom',
	emoji: '👋'
});

// Create menu buttons
const menuRow = ButtonUtil.createMenuButtons([
	{ label: 'Option 1', customId: 'opt_1', emoji: '1️⃣' },
	{ label: 'Option 2', customId: 'opt_2', emoji: '2️⃣' }
]);

// Create poll buttons
const pollRow = ButtonUtil.createPollButtons(['Yes', 'No', 'Maybe']);

Message Utilities

const { MessageUtil } = require('@ZerroDevs/discord-bot-utils');

// Send temporary message
await MessageUtil.sendTemporaryMessage(channel, 'This will delete in 5 seconds');

// Create typing effect
await MessageUtil.createTypingEffect(channel, [
	'First message...',
	'Second message...',
	'Final message!'
], {
	interval: 2000,
	deleteAfter: true
});

// Create countdown
await MessageUtil.createCountdown(interaction, 60, {
	startMessage: 'Countdown started!',
	endMessage: 'Time\'s up!'
});

// Create progress bar
const progress = MessageUtil.createProgressBar(7, 10); // "ZerroDevs"

Tax Calculator

const { TaxUtil } = require('@ZerroDevs/discord-bot-utils');

// Calculate tax with fixed rate
const taxInfo = TaxUtil.calculateTax(1000, 15); // 15% tax rate

// Display as message
const messageResponse = TaxUtil.createTaxMessageResponse(taxInfo);

// Display as embed
const embedResponse = TaxUtil.createTaxEmbed(taxInfo);

// Using preset command with fixed rate
await PresetCommands.handleTax(interaction, { 
	userDefined: false, 
	fixedRate: 15 
});

// Using preset command with user-defined rate
await PresetCommands.handleTax(interaction, { 
	userDefined: true 
});

Moderation Utilities

• User timeout management
• Message bulk deletion with filters
• Channel slowmode control
• Duration parsing (1s, 1m, 1h, 1d)
• Permission validation

const { ModerationUtil } = require('@ZerroDevs/discord-bot-utils');

// Timeout a user
const success = await ModerationUtil.timeout(member, 3600, 'Breaking rules'); // 1 hour timeout

// Clear messages with filters
const deleted = await ModerationUtil.clearMessages(channel, 100, {
    user: targetUser,
    contains: 'spam'
});

// Set channel slowmode
await ModerationUtil.setSlowmode(channel, 30); // 30 seconds

// Parse duration string
const seconds = ModerationUtil.parseDuration('1h'); // Returns 3600

// Check moderation permissions
const canModerate = ModerationUtil.validateModPermissions(member, 'MODERATE_MEMBERS');

Available Moderation Commands:

• /timeout <user> <duration> [reason] - Timeout a user with duration (1s, 1m, 1h, 1d)
• /clear <amount> [user] [contains] - Delete messages with optional filters
• /slowmode <duration> - Set channel slowmode with duration format

Interaction Utilities

• Role information and statistics
• Interactive poll creation
• Dynamic poll updates
• Vote tracking and management
• Button-based interactions

const { InteractionUtil } = require('@ZerroDevs/discord-bot-utils');

// Get role information
const roleInfo = await InteractionUtil.getRoleInfo(role);
const embed = InteractionUtil.createRoleInfoEmbed(roleInfo);

// Create an interactive poll
const poll = InteractionUtil.createPoll('What\'s your favorite color?', [
	'Red', 'Blue', 'Green'
]);
const message = await channel.send({
	embeds: [poll.embed],
	components: poll.components
});

// Update poll results
const updatedPoll = InteractionUtil.updatePollResults(interaction, votesMap);
await message.edit({
	embeds: [updatedPoll.embed],
	components: updatedPoll.components
});

Available Interaction Commands:

• /roleinfo <role> - Display detailed role information and statistics
• /poll <question> [options] - Create an interactive poll with up to 10 options (comma-separated)

Command Handler

const { CommandHandler } = require('@ZerroDevs/discord-bot-utils');

// Check permissions
const hasPermission = CommandHandler.validatePermissions(member, ['BAN_MEMBERS']);

// Handle cooldowns
const cooldownTime = CommandHandler.checkCooldown(userId, 'commandName', 10);

// Track usage
const usageCount = CommandHandler.trackCommandUsage(userId, 'commandName');

// Get command stats
const stats = CommandHandler.getCommandStats('commandName');

// Check role hierarchy
const canModerate = CommandHandler.checkPermissionHierarchy(moderator, target);

// Check roles
const hasRole = CommandHandler.hasRequiredRole(member, roleId);
const hasAnyRole = CommandHandler.hasAnyRole(member, roleIds);
const hasAllRoles = CommandHandler.hasAllRoles(member, roleIds);

Logging System

• Comprehensive error tracking and handling
• Multiple log levels (info, warning, error, debug)
• File-based logging with automatic cleanup
• Discord webhook integration
• Command execution logging
• Global error catching
• Custom event logging

const { LoggerUtil } = require('@ZerroDevs/discord-bot-utils');

// Initialize logger
await LoggerUtil.initialize({
	logDirectory: 'logs',
	webhookUrl: 'your-webhook-url',
	errorWebhookUrl: 'your-error-webhook-url',
	maxLogAge: 7 // days
});

// Log different levels
await LoggerUtil.log('info', 'Operation successful');
await LoggerUtil.log('warning', 'Resource running low');
await LoggerUtil.error(error, { context: 'additional info' });

// Wrap commands with logging
const wrappedCommand = LoggerUtil.createCommandLogger(async (interaction) => {
	// Your command logic here
});

// Automatic file cleanup
// Logs older than maxLogAge days are automatically removed

Preset Commands

const { PresetCommands } = require('@ZerroDevs/discord-bot-utils');

// Get all preset command definitions
const presetCommands = PresetCommands.getPresetCommands();

// In your interaction handler:
client.on('interactionCreate', async interaction => {
	if (!interaction.isCommand()) return;

	switch(interaction.commandName) {
		case 'ping':
			await PresetCommands.handlePing(interaction);
			break;
		case 'avatar':
			await PresetCommands.handleAvatar(interaction);
			break;
		case 'kick':
			await PresetCommands.handleKick(interaction);
			break;
		case 'ban':
			await PresetCommands.handleBan(interaction);
			break;
		case 'shortlink':
			await PresetCommands.handleShortLink(interaction);
			break;
	}
});

Available Preset Commands:

• /ping - Check bot latency
• /avatar [user] - Get user avatar (optional user mention)
• /kick <user> [reason] - Kick a member with optional reason
• /ban <user> [reason] [days] - Ban a user with optional reason and message deletion days
• /shortlink <url> - Create a shortened URL using TinyURL
• /tax-fixed <amount> [display] - Calculate tax with fixed rate (15%)
• /tax-custom <amount> <tax_rate> [display] - Calculate tax with custom rate

Example Bot

Check the examples directory for a complete example bot showcasing all features.

License

MIT