API Integration

✨ 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:

hello-world-addon.js

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:

• discord:messageCreate — New message sent (key data: message)

• discord:messageUpdate — Message edited (key data: message, oldMessage)

• discord:messageDelete — Message deleted (key data: message)

• discord:guildMemberAdd — User joins server (key data: member)

• discord:guildMemberRemove — User leaves server (key data: member)

• discord:guildMemberUpdate — User roles/nickname changed (key data: oldMember, newMember)

• discord:voiceStateUpdate — Voice channel changes (key data: oldState, newState)

• discord:channelCreate — Channel created (key data: channel)

• discord:channelDelete — Channel deleted (key data: channel)

• discord:roleCreate — Role created (key data: role)

• discord:roleDelete — Role deleted (key data: role)

• discord:guildBanAdd — User banned (key data: ban)

• discord:guildBanRemove — User unbanned (key data: ban)

• discord:interactionCreate — Slash command/button used (key data: interaction)

• discord:ready — Bot started (key data: client)

Bot Business Logic Events

Ticket Events:

• ticket:created — New ticket opened (key data: ticket, user, ticketType, questions)

• ticket:closed — Ticket closed/resolved (key data: ticket, closedBy, closeReason, isAutoAlert)

• ticket:deleted — Ticket channel deleted (key data: ticket, deletedBy, channelName)

• ticket:claimed — Staff member claims ticket (key data: ticket, claimer)

• ticket:unclaimed — Staff member unclaims ticket (key data: ticket, previousClaimer)

• ticket:reviewed — User reviews service (key data: ticket, rating, feedback, reviewer)

Suggestion Events:

• suggestion:created — New suggestion submitted (key data: suggestion, author, text, message)

• suggestion:accepted — Suggestion approved by staff (key data: suggestion, acceptedBy, reason, originalAuthor)

• suggestion:denied — Suggestion rejected by staff (key data: suggestion, deniedBy, reason, originalAuthor)

Leveling Events:

• level:up — User gains XP and levels up (key data: user, newLevel, oldLevel, xpGained, userData)

Auto-Moderation Events:

• autoReact:triggered — Bot auto-reacts to keyword (key data: message, keyword, emoji, reaction)

• autoResponse:triggered — Bot sends auto-response (key data: message, trigger, responseType, responseContent)

• moderation:antiSpam — Anti-spam/mass mention triggered (key data: type, user, action, reason, duration)

Music Events:

• music:trackStart — Track starts playing (key data: track, requestedBy, queue)

• music:trackAdded — Track added to queue (key data: track, requestedBy, queue)

Giveaway Events:

• giveaway:created — New giveaway started (key data: giveaway, prize, winnerCount, hostedBy)

• giveaway:ended — Giveaway finished, winners selected (key data: giveaway, winners, prize, totalEntries)

Invite Events:

• invite:memberJoined — Member joins via tracked invite (key data: member, inviter, inviterInviteCount)

Moderation Events (Slash Commands):

• moderation:ban — A user is banned via slash command or audit log (key data: type, target, moderator, reason, guild, dmSent, method)

• moderation:unban — A previously banned user is unbanned (key data: type, targetUserId, moderator, reason, guild, method)

• moderation:kick — A member is removed from the server (key data: type, target, moderator, reason, guild, dmSent, method)

• moderation:warn — A moderator issues a warning (key data: type, target, moderator, reason, guild, warningCount, warning, method)

• moderation:unwarn — A warning is removed from a user (key data: type, target, moderator, removedWarning, warningId, guild, remainingWarnings, method)

• moderation:timeout — A user is muted/timed out (key data: type, subType, target, moderator, reason, duration, durationMs, endTime, guild, method)

• moderation:timeout_clear — Timeout or mute is lifted (key data: type, target, moderator, guild, wasMuted, method)

• moderation:tempban — A moderator applies a timed ban (key data: type, target, moderator, reason, duration, endTime, guild, dmSent, method)

• moderation:nickname_change — A moderator edits a user’s nickname (key data: type, target, moderator, oldNickname, newNickname, guild, method)

• moderation:purge — A moderator bulk deletes messages (key data: type, moderator, channel, guild, messageCount, purgeType, originalAmount, method)

Addon Lifecycle Events:

• addon:loaded — Addon loaded successfully (key data: name, path, type)

• addon:unloaded — Addon unloaded (key data: name, path)

• addon:registered — Addon registered with event system (key data: name, events)

---

🔧 Custom Events

Emit and listen for your own events:

custom-event.js

// 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:

context-object.js

{
    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:

high-priority-addon.js

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

Error Handling

Addons run independently:

error-handling.js

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:

mongoose-example.js

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:

conditional-event.js

'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)

legacy-addon.js

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

New Event API Format

new-addon-format.js

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

minimal-addon.js

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

---

💡 Practical Examples

Staff Notification System

staff-notifications.js

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

level-rewards.js

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

mod-logger.js

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()
                    }]
                });
            }
        }
    }
};