Event Handlers

Documentation for automatic event handlers in the LuaBeans - Community Manager Discord bot.

Overview

The bot automatically handles Discord events to keep the web panel in sync with Discord. These events run automatically and require no user interaction.

Event Handlers

guildMemberAdd

Fired when a new member joins the Discord server.

Handler: bot/events/guildMemberAdd/00-syncUser.js

What it does:

1. Creates or updates user record in database

2. Syncs Discord roles to department memberships

3. Assigns LEO ranks based on Discord role mapping

4. Updates RBAC permissions cache

Configuration: None required - runs automatically

When it runs: Immediately when member joins

Logging: Logs to console with user information

---

guildMemberUpdate

Fired when a member's information is updated (roles changed, nickname changed, etc.).

Handler: bot/events/guildMemberUpdate/00-syncUser.js

What it does:

1. Updates user record in database

2. Syncs updated Discord roles to department memberships

3. Updates LEO rank assignments based on role changes

4. Refreshes RBAC permissions cache

Configuration: None required - runs automatically

When it runs: When member roles or information changes

Logging: Logs role changes to console

Common Triggers:

• Discord role added to member

• Discord role removed from member

• Member nickname changed

• Member avatar changed

---

messageCreate

Fired when a message is created in a Discord channel.

Handler: bot/events/messageCreate/00-tebexPurchase.js

What it does:

1. Checks if message is from Tebex bot

2. Parses purchase information from message

3. Creates purchase record in database

4. Links purchase to user (if identified)

5. Processes for garage redemption workflow

Configuration:

• TEBEX_BOT_ID - Tebex bot's Discord ID

• TEBEX_ALLOWED_CHANNEL_IDS - Channels to monitor for purchases

• TEBEX_DEBUG - Enable debug logging

When it runs: When message is posted in monitored channels

Use Case: Automatic garage slot assignment for Tebex purchases

Notes:

• Only processes messages from Tebex bot

• Only monitors configured channels

• Requires Tebex bot integration setup

---

interactionCreate

Fired when an interaction is created (slash command, button, etc.).

Handler: bot/events/interactionCreate/00-autocomplete.js

What it does:

1. Handles autocomplete for slash commands

2. Provides department suggestions

3. Provides user suggestions

Configuration: None required - runs automatically

When it runs: When user types slash command with autocomplete options

Use Case: Command autocomplete functionality

---

ready

Fired when bot is ready and connected to Discord.

Handler: bot/events/ready/00-startup.js

What it does:

1. Logs bot startup information

2. Registers commands (if needed)

3. Initializes bot state

4. Verifies database connection

Configuration: None required - runs automatically

When it runs: On bot startup

Logging: Logs bot readiness to console

Example Output:

[LuaBeans - Community Manager Bot] ready
[LuaBeans - Community Manager Bot] Connected to Discord
[LuaBeans - Community Manager Bot] Commands registered

Event Configuration

Enabling/Disabling Events

Events are enabled by default. To disable an event:

1. Remove or rename the event file in bot/events/

2. Or modify the event handler to return early

Note: Disabling critical events (like guildMemberAdd and guildMemberUpdate) will prevent automatic role syncing.

Event Order

Events are processed in this order:

1. ready - Bot initialization

2. guildMemberAdd - New member handling

3. guildMemberUpdate - Member update handling

4. messageCreate - Message processing

5. interactionCreate - Command handling

Rate Limiting

The bot automatically handles Discord API rate limits:

• Retries failed requests automatically

• Logs rate limit warnings

• Respects rate limit headers

• Queues requests when rate limited

Rate Limit Logging:

[LuaBeans - Community Manager Bot] rate limited: {
  route: '/guilds/{guild.id}/members/{user.id}',
  method: 'PATCH',
  timeToReset: 5000,
  global: false
}

Troubleshooting Events

Events Not Firing

Issue: Events aren't running

Solutions:

1. Check bot is online (green dot)

2. Verify required intents are enabled (Members Intent)

3. Check console for errors

4. Verify event files exist in bot/events/

5. Check bot has required permissions

Role Sync Not Working

Issue: Discord roles not syncing to web panel

Solutions:

1. Check guildMemberUpdate event is running

2. Verify bot has permission to read members

3. Check Members Intent is enabled

4. Verify DISCORD_GUILD_ID is correct

5. Manually trigger sync: /syncme command

Tebex Events Not Processing

Issue: Purchase messages not being processed

Solutions:

1. Verify TEBEX_BOT_ID is correct

2. Check TEBEX_ALLOWED_CHANNEL_IDS includes target channel

3. Verify Tebex bot is posting messages

4. Check message format matches expected pattern

5. Enable TEBEX_DEBUG=true for detailed logging

Database Errors in Events

Issue: Events fail with database errors

Solutions:

1. Verify database connection is working

2. Check database credentials in .env

3. Verify database is running

4. Check database logs for errors

5. Ensure tables exist (run schema if needed)

Event Logging

All events log to console. In production, redirect logs to files:

node bot/index.js >> /var/log/luabeans/bot.log 2>&1

Log Levels

• Info: Normal event processing

• Warn: Rate limiting, non-critical issues

• Error: Failed event processing, critical errors

Log Format

[LuaBeans - Community Manager Bot] [EventName] [Action]: [Details]

Examples:

[LuaBeans - Community Manager Bot] [guildMemberAdd] Syncing user: User#1234
[LuaBeans - Community Manager Bot] [guildMemberUpdate] Updated roles for User#1234
[LuaBeans - Community Manager Bot] [messageCreate] Processing Tebex purchase

Best Practices

1. Monitor Event Logs - Check logs regularly for errors

2. Handle Rate Limits - Bot handles automatically, but monitor for excessive limits

3. Verify Permissions - Ensure bot has required permissions for events

4. Test Events - Test events after bot updates

5. Database Health - Ensure database is healthy for event processing

Related Documentation

• Bot Setup - Installing and configuring the bot

• Bot Commands - Available commands

• Bot Permissions - Required permissions