API Integration

Integrate your addons into core bot logic, unlocking a new level of power.

✨ Features

• Event-driven architecture — React to Discord and bot events

• Backward compatibility — Legacy addons still work

• Priority system — Control execution order of handlers

• Error isolation — One addon's error won't crash others

• Rich context — Access client, config, and language data

• Async support — Full Promise / async-await support

---

🚀 Quick Start

Example: HelloWorld Addon

A simple addon that responds to messages, welcomes new members, and reacts to tickets being created:

module.exports = {
    // Only 'name' is required!
    name: 'HelloWorld',
    
    // Everything else is optional (but recommended for clarity)
    // version: '1.0.0'
    // description: '...'
    // author: 'Your Name'
    
    events: {
        // Respond to messages
        'discord:messageCreate': async (eventData, context) => {
            const { message } = eventData;
            if (message.author.bot) return;
            
            if (message.content.toLowerCase() === '!hello') {
                await message.channel.send(`Hello ${message.author.username}! 👋`);
            }
        },
        
        // Welcome new members
        'discord:guildMemberAdd': async (eventData, context) => {
            const { member } = eventData;
            console.log(`New member joined: ${member.user.username}`);
            
            const channel = member.guild.channels.cache.find(
                ch => ch.name === 'welcome' || ch.name === 'general'
            );
            if (channel) {
                await channel.send(`Welcome ${member.user.username}! 🎉`);
            }
        },
        
        // React to tickets being created
        'ticket:created': async (eventData, context) => {
            const { ticket, user } = eventData;
            console.log(`Ticket #${ticket.ticketId} was created by ${user.username}`);
        }
    }
};

✅ With this addon

• Type !hello → Bot replies with a greeting

• New members join → Welcome message in #welcome or #general

• Ticket is created → Logged in console

---

📡 Event Reference

Discord Events

Listen to Discord.js events with the discord: prefix:

Event	What It Does	Key Data
discord:messageCreate	New message sent	message
discord:messageUpdate	Message edited	message, oldMessage
discord:messageDelete	Message deleted	message
discord:guildMemberAdd	User joins server	member
discord:guildMemberRemove	User leaves server	member
discord:guildMemberUpdate	User roles/nickname changed	oldMember, newMember
discord:voiceStateUpdate	Voice channel changes	oldState, newState
discord:channelCreate	Channel created	channel
discord:channelDelete	Channel deleted	channel
discord:roleCreate	Role created	role
discord:roleDelete	Role deleted	role
discord:guildBanAdd	User banned	ban
discord:guildBanRemove	User unbanned	ban
discord:interactionCreate	Slash command/button used	interaction
discord:ready	Bot started	client

Bot Business Logic Events

Ticket Events

Event	What It Does	Key Data
ticket:created	New ticket opened	ticket, user, ticketType, questions
ticket:closed	Ticket closed/resolved	ticket, closedBy, closeReason, isAutoAlert
ticket:deleted	Ticket channel deleted	ticket, deletedBy, channelName
ticket:claimed	Staff member claims ticket	ticket, claimer
ticket:unclaimed	Staff member unclaims ticket	ticket, previousClaimer
ticket:reviewed	User reviews service	ticket, rating, feedback, reviewer

Suggestion Events

Event	What It Does	Key Data
suggestion:created	New suggestion submitted	suggestion, author, text, message
suggestion:accepted	Suggestion approved by staff	suggestion, acceptedBy, reason, originalAuthor
suggestion:denied	Suggestion rejected by staff	suggestion, deniedBy, reason, originalAuthor

Leveling Events

Event	What It Does	Key Data
level:up	User gains XP and levels up	user, newLevel, oldLevel, xpGained, userData

Auto-Moderation Events

Event	What It Does	Key Data
autoReact:triggered	Bot auto-reacts to keyword	message, keyword, emoji, reaction
autoResponse:triggered	Bot sends auto-response	message, trigger, responseType, responseContent
moderation:antiSpam	Anti-spam/mass mention triggered	type, user, action, reason, duration

Music Events

Event	What It Does	Key Data
music:trackStart	Track starts playing	track, requestedBy, queue
music:trackAdded	Track added to queue	track, requestedBy, queue

Giveaway Events

Event	What It Does	Key Data
giveaway:created	New giveaway started	giveaway, prize, winnerCount, hostedBy
giveaway:ended	Giveaway finished, winners selected	giveaway, winners, prize, totalEntries

Invite Events

Event	What It Does	Key Data
invite:memberJoined	Member joins via tracked invite	member, inviter, inviterInviteCount

Moderation Events (Slash Commands)

moderation:ban	A user is banned via slash command or audit log	type, target, moderator, reason, guild, dmSent, method
moderation:unban	A previously banned user is unbanned	type, targetUserId, moderator, reason, guild, method
moderation:kick	A member is removed from the server	type, target, moderator, reason, guild, dmSent, method
moderation:warn	A moderator issues a warning	type, target, moderator, reason, guild, warningCount, warning, method
moderation:unwarn	A warning is removed from a user	type, target, moderator, removedWarning, warningId, guild, remainingWarnings, method
moderation:timeout	A user is muted/timed out	type, subType, target, moderator, reason, duration, durationMs, endTime, guild, method
moderation:timeout_clear	Timeout or mute is lifted	type, target, moderator, guild, wasMuted, method
moderation:tempban	A moderator applies a timed ban	type, target, moderator, reason, duration, endTime, guild, dmSent, method
moderation:nickname_change	A moderator edits a user’s nickname	type, target, moderator, oldNickname, newNickname, guild, method
moderation:purge	A moderator bulk deletes messages	type, moderator, channel, guild, messageCount, purgeType, originalAmount, method

Addon Lifecycle Events

Event	What It Does	Key Data
addon:loaded	Addon loaded successfully	name, path, type
addon:unloaded	Addon unloaded	name, path
addon:registered	Addon registered with event system	name, events

---

🔧 Custom Events

Emit and listen for your own events:

// Emit
global.addonLoader.getEventManager().emitSafe('my-addon:custom-event', {
    data: 'some data',
    user,
    guild
});

// Listen
events: {
    'my-addon:custom-event': async (eventData, context) => {
        const { data, user, guild } = eventData;
        // Handle custom event
    }
}

---

🧰 Context Object

Every handler receives:

{
    client: Client,       // Discord.js client
    config: Object,       // Bot config
    lang: Object,         // Language config
    eventName: String,    // Current event
    timestamp: Date,      // Emitted at
    guild: Guild|null,    // Guild if available
    user: User|null       // User if available
}

---

⚙️ Advanced Features

Priority System

Control execution order:

module.exports = {
    name: 'HighPriority',
    priority: 100, // Higher runs first
    events: { /* ... */ }
};

Error Handling

Addons run independently:

events: {
    'discord:messageCreate': async (eventData, context) => {
        try {
            // your logic
        } catch (err) {
            console.error('Error in my addon:', err);
            // Won't crash other addons
        }
    }
}

Database Integration

Use Mongoose inside addons:

const mongoose = require('mongoose');

const mySchema = new mongoose.Schema({
    guildId: String,
    data: String
});

const MyModel = mongoose.model('MyData', mySchema);

// Use in events
await MyModel.findOneAndUpdate(
    { guildId: guild.id },
    { data: 'updated' },
    { upsert: true }
);

Conditional Event Handling

Run logic only in certain channels/users:

'discord:messageCreate': async (eventData, context) => {
    const { message } = eventData;
    
    // Only in specific channels
    if (!['general', 'bot-commands'].includes(message.channel.name)) return;
    
    // Only non-bots
    if (message.author.bot) return;
    
    // Your logic here
}

---

🔄 Migration from Legacy Addons

Legacy Format (still works)

module.exports = {
    run: async (client) => {
        client.on('messageCreate', async message => {
            if (message.content === '!hello') {
                await message.channel.send('Hello!');
            }
        });
    }
};

New Event API Format

module.exports = {
    name: 'MyAddon',
    version: '1.0.0',
    events: {
        'discord:messageCreate': async (eventData, context) => {
            const { message } = eventData;
            if (message.content === '!hello') {
                await message.channel.send('Hello!');
            }
        }
    },
    
    // Optional: Keep initialization logic
    run: async (client, eventManager) => {
        console.log('Addon initialized!');
    }
};

Key Differences

• Legacy → run function, no name property

• New → name required, uses events

• New format benefits: event-driven API, hot reloading, enable/disable, error isolation, priorities

---

📋 Requirements Summary

Absolutely Required

• name (string) — Unique addon identifier

Required (pick one)

• events (object) — Event handlers

• run (function) — Init function

Optional (defaults)

• version → '1.0.0'

• description → ''

• author → 'Unknown'

• priority → 0

• permissions → []

• dependencies → []

Minimal Working Addon

module.exports = {
    name: 'Minimal',
    events: {
        'discord:messageCreate': async (eventData, context) => {
            // Your code here
        }
    }
};

---

💡 Practical Examples

Staff Notification System

module.exports = {
    name: 'StaffNotifications',
    events: {
        'ticket:created': async ({ ticket, user, ticketType }) => {
            const staffChannel = ticket.guild.channels.cache.find(ch => ch.name === 'staff-alerts');
            if (staffChannel) {
                await staffChannel.send(`🎫 New ${ticketType.Name} ticket #${ticket.ticketId} by ${user.username}`);
            }
        },
        
        'suggestion:created': async ({ suggestion, author, text }) => {
            const staffChannel = suggestion.guild.channels.cache.find(ch => ch.name === 'suggestions');
            if (staffChannel) {
                const message = await staffChannel.send(`💡 New suggestion: "${text}" by ${author.username}`);
                await message.react('👍');
                await message.react('👎');
            }
        }
    }
};

Level Rewards System

module.exports = {
    name: 'LevelRewards',
    events: {
        'level:up': async ({ user, newLevel, guild }) => {
            const member = guild.members.cache.get(user.id);
            
            // Milestone rewards
            if (newLevel === 10) {
                const role = guild.roles.cache.find(r => r.name === 'Active Member');
                if (role) await member.roles.add(role);
            }
            
            if (newLevel === 50) {
                const role = guild.roles.cache.find(r => r.name === 'Veteran');
                if (role) await member.roles.add(role);
            }
            
            // Celebrate big milestones
            if (newLevel % 25 === 0) {
                const channel = guild.channels.cache.find(ch => ch.name === 'general');
                if (channel) {
                    await channel.send(`🎉 ${user.username} reached level ${newLevel}! Amazing! 🎉`);
                }
            }
        }
    }
};

Auto-Moderation Logger

module.exports = {
    name: 'ModLogger',
    events: {
        'moderation:antiSpam': async ({ type, user, action, reason, guild }) => {
            const logChannel = guild.channels.cache.find(ch => ch.name === 'mod-logs');
            if (logChannel) {
                await logChannel.send({
                    embeds: [{
                        title: '🛡️ Auto-Moderation',
                        description: `**User:** ${user.username}\n**Type:** ${type}\n**Action:** ${action}\n**Reason:** ${reason}`,
                        color: 0xff6b6b,
                        timestamp: new Date()
                    }]
                });
            }
        }
    }
};