API Documentation

📖 API Documentation

Internal API reference for bot classes and methods.

---

🎯 Overview

This page documents the internal APIs used by the bot.

Note: This is not a REST API - these are internal JavaScript classes.

---

📚 Core Classes

StatusChecker

File: classes/StatusChecker.js

Purpose: Query Minecraft servers for status information

Methods

checkServer(ip, port, type)

Query a server for status.

Parameters:

• ip (string) - Server IP or hostname
• port (number) - Server port
• type (string) - 'java' or 'bedrock'

Returns: Promise<Object>

Response Object:

{
  online: true,
  players: {
    online: 5,
    max: 20
  },
  latency: 45,
  version: "1.20.4",
  motd: "My Server",
  icon: "base64_string" // Java only
}

Example:

const checker = new StatusChecker();
const status = await checker.checkServer('mc.hypixel.net', 25565, 'java');
console.log(`Players: ${status.players.online}/${status.players.max}`);

---

ConfigManager

File: classes/ConfigManager.js

Purpose: Manage bot configurations

Methods

loadGlobalConfig()

Load global configuration.

Returns: Object

Example:

const config = configManager.loadGlobalConfig();
console.log(`Language: ${config.language}`);

loadGuildConfig(guildId)

Load guild-specific configuration.

Parameters:

• guildId (string) - Discord guild ID

Returns: Object

saveGuildConfig(guildId, data)

Save guild configuration.

Parameters:

• guildId (string) - Discord guild ID
• data (Object) - Configuration data

Returns: boolean

Example:

const success = configManager.saveGuildConfig('123456789', {
  updateInterval: 60000,
  servers: [...]
});

---

EmbedBuilder

File: classes/EmbedBuilder.js

Purpose: Create Discord embeds

Methods

createStatusEmbed(server, status)

Create server status embed.

Parameters:

• server (Object) - Server configuration
• status (Object) - Server status data

Returns: EmbedBuilder

Example:

const embed = embedBuilder.createStatusEmbed(
  { name: 'My Server', ip: 'mc.example.com' },
  { online: true, players: { online: 10, max: 20 } }
);

await channel.send({ embeds: [embed] });

createErrorEmbed(message)

Create error message embed.

Parameters:

• message (string) - Error message

Returns: EmbedBuilder

---

MonitoringManager

File: classes/MonitoringManager.js

Purpose: Manage server monitoring

Methods

startMonitoring(guildId)

Start monitoring for a guild.

Parameters:

• guildId (string) - Discord guild ID

Returns: void

Example:

monitoringManager.startMonitoring('123456789');

stopMonitoring(guildId)

Stop monitoring for a guild.

Parameters:

• guildId (string) - Discord guild ID

Returns: void

updateServer(server)

Manually trigger server update.

Parameters:

• server (Object) - Server configuration

Returns: Promise<void>

---

PermissionManager

File: classes/PermissionManager.js

Purpose: Check permissions

Methods

hasPermission(member, type)

Check if member has permission.

Parameters:

• member (GuildMember) - Discord guild member
• type (string) - Permission type ('setup', 'admin')

Returns: boolean

Example:

if (permissionManager.hasPermission(interaction.member, 'setup')) {
  // User can use setup commands
}

checkBotPermissions(channel)

Check bot permissions in channel.

Parameters:

• channel (TextChannel) - Discord channel

Returns: Object

Response:

{
  viewChannel: true,
  sendMessages: true,
  embedLinks: true,
  attachFiles: true,
  readMessageHistory: true
}

---

MessageHandler

File: classes/MessageHandler.js

Purpose: Manage Discord messages

Methods

sendMessage(channel, content)

Send a message.

Parameters:

• channel (TextChannel) - Discord channel
• content (Object) - Message content

Returns: Promise<Message>

Example:

const message = await messageHandler.sendMessage(channel, {
  embeds: [embed]
});

updateMessage(messageId, content)

Update existing message.

Parameters:

• messageId (string) - Message ID
• content (Object) - New content

Returns: Promise<Message>

deleteMessage(messageId)

Delete a message.

Parameters:

• messageId (string) - Message ID

Returns: Promise<void>

---

🔧 Utility Functions

Logger

File: classes/Logger.js

Methods

info(message)

Log info message.

Example:

logger.info('Bot started successfully');

error(message, error)

Log error.

Example:

logger.error('Failed to query server', error);

debug(message)

Log debug message.

Example:

logger.debug('Processing interaction');

---

🎨 Data Structures

Server Configuration

{
  id: "unique-id",
  name: "My Server",
  ip: "mc.example.com",
  port: 25565,
  type: "java", // or "bedrock"
  channelId: "123456789",
  messageId: "987654321" // optional
}

Guild Configuration

{
  guildId: "123456789",
  language: "en",
  updateInterval: 60000,
  setupRole: "123456789", // optional
  servers: [
    // Server configurations
  ]
}

Status Response

{
  online: true,
  players: {
    online: 10,
    max: 20,
    list: ["Player1", "Player2"] // optional
  },
  version: "1.20.4",
  latency: 45,
  motd: {
    raw: "§aWelcome!",
    clean: "Welcome!",
    html: "<span style='color:green'>Welcome!</span>"
  },
  icon: "data:image/png;base64,..." // Java only
}

---

🔄 Event Handling

Discord Events

The bot handles these events:

ready

client.on('ready', () => {
  console.log('Bot is ready!');
});

interactionCreate

client.on('interactionCreate', async (interaction) => {
  if (interaction.isCommand()) {
    // Handle command
  }
  if (interaction.isButton()) {
    // Handle button
  }
});

guildCreate

client.on('guildCreate', (guild) => {
  // Bot joined new server
});

guildDelete

client.on('guildDelete', (guild) => {
  // Bot removed from server
});

---

🔌 Integration Examples

Basic Bot Setup

const { Client, GatewayIntentBits } = require('discord.js');
const ConfigManager = require('./classes/ConfigManager');
const StatusChecker = require('./classes/StatusChecker');

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages
  ]
});

const configManager = new ConfigManager();
const statusChecker = new StatusChecker();

client.on('ready', () => {
  console.log('Bot ready!');
});

client.login(config.token);

Query Server

async function checkMyServer() {
  try {
    const status = await statusChecker.checkServer(
      'mc.hypixel.net',
      25565,
      'java'
    );
    
    if (status.online) {
      console.log(`Server online: ${status.players.online} players`);
    } else {
      console.log('Server offline');
    }
  } catch (error) {
    console.error('Failed to check server:', error);
  }
}

Create Status Embed

const embed = embedBuilder.createStatusEmbed(
  {
    name: 'My Server',
    ip: 'mc.example.com',
    port: 25565
  },
  {
    online: true,
    players: { online: 15, max: 20 },
    latency: 45,
    version: '1.20.4'
  }
);

await channel.send({ embeds: [embed] });

---

🔒 Error Handling

Standard Error Format

{
  code: 'ERROR_CODE',
  message: 'Human readable message',
  details: {
    // Additional error details
  }
}

Common Error Codes

• TOKEN_INVALID - Invalid bot token
• SERVER_OFFLINE - Minecraft server offline
• SERVER_TIMEOUT - Query timeout
• PERMISSION_DENIED - Missing permissions
• CONFIG_INVALID - Invalid configuration
• NETWORK_ERROR - Network connectivity issue

Error Handling Example

try {
  const status = await statusChecker.checkServer(ip, port, type);
} catch (error) {
  if (error.code === 'SERVER_TIMEOUT') {
    console.log('Server took too long to respond');
  } else if (error.code === 'SERVER_OFFLINE') {
    console.log('Server is offline');
  } else {
    console.error('Unexpected error:', error);
  }
}

---

📝 Best Practices

Always Handle Errors

// ❌ Bad
const status = await statusChecker.checkServer(ip, port, type);

// ✅ Good
try {
  const status = await statusChecker.checkServer(ip, port, type);
  // Use status
} catch (error) {
  logger.error('Failed to check server:', error);
  // Handle error
}

Validate Input

// ✅ Good
if (!ip || typeof ip !== 'string') {
  throw new Error('Invalid IP address');
}

if (port < 1 || port > 65535) {
  throw new Error('Invalid port number');
}

Use Proper Logging

// ✅ Good
logger.info(`Checking server: ${ip}:${port}`);
logger.debug(`Server type: ${type}`);
logger.error('Query failed:', error);

---

🔗 Related Pages

• Project Structure - Code organization
• Development Setup - Dev environment
• Contributing Code - Contribution guidelines

---

← Back to Home