multi-guild support, error handling refactor, and command updates

Author: codebymitch

.env.example

@@ -6,6 +6,10 @@ CLIENT_ID=your_discord_client_id_here
 GUILD_ID=your_discord_guild_id_here
 OWNER_IDS=your_discord_id_here (optional)
 
+# Optional — enable slash commands in every server the bot is invited to.
+# Leave unset or false for single-server setup (recommended for most users).
+MULTI_GUILD=false
+
 # Bot Runtime Configuration
 NODE_ENV=production
 LOG_LEVEL=warn

README.md

@@ -182,6 +182,21 @@ docker pull ghcr.io/codebymitch/titanbot:main
    This gives clear startup/online status messages while keeping logs simple for non-technical operators.
    If port `3000` is busy, the bot tries the next available ports automatically (up to `PORT_RETRY_ATTEMPTS`).
 
+### Running in multiple servers (optional)
+
+Most users run TitanBot on a **single server** with `GUILD_ID` set (default tutorial setup). If you want slash commands to work in **every server** the bot is invited to, opt in with:
+
+```env
+MULTI_GUILD=true
+```
+
+Notes for multi-server mode:
+- `GUILD_ID` is not used for command registration when `MULTI_GUILD=true` (you can leave it set or remove it)
+- Global slash commands may take up to about an hour to propagate on first deploy
+- Each server still has **isolated** config, economy, tickets, leveling, and other data
+- In the [Discord Developer Portal](https://discord.com/developers/applications), ensure your bot is not restricted to a single guild if you plan to invite it elsewhere
+- Generate an OAuth2 invite URL from the [Discord Developer Portal](https://discord.com/developers/applications) (OAuth2 → URL Generator, scopes: `bot` and `applications.commands`)
+
 4. **Setup PostgreSQL Database** (Optional but recommended)
    ```bash
    # Create database and user

docker-compose.yml

@@ -8,6 +8,7 @@ services:
       - DISCORD_TOKEN=${DISCORD_TOKEN}
       - CLIENT_ID=${CLIENT_ID}
       - GUILD_ID=${GUILD_ID}
+      - MULTI_GUILD=${MULTI_GUILD:-false}
       - DATABASE_URL=postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}
       - PORT=3000
     depends_on:

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "titanbot-custom",
-  "version": "1.1.1",
+  "version": "2.1.0",
   "description": "Modular Ultimate Community Bot by Touchpoint Support",
   "main": "src/app.js",
   "type": "module",

package.json

@@ -12,6 +12,7 @@ import { logger, startupLog, shutdownLog } from './utils/logger.js';
 import { checkBirthdays } from './services/birthdayService.js';
 import { checkGiveaways } from './services/giveawayService.js';
 import { loadCommands, registerCommands as registerSlashCommands } from './handlers/commandLoader.js';
+import pkg from '../package.json' with { type: 'json' };
 
 class TitanBot extends Client {
   constructor() {
@@ -85,6 +86,11 @@ class TitanBot extends Client {
 
       startupLog('Registering slash commands...');
       await this.registerCommands();
+      if (this.config.bot.multiGuild) {
+        startupLog('Multi-guild mode enabled — slash commands registered globally');
+      } else if (this.config.bot.guildId) {
+        startupLog(`Single-guild mode — slash commands registered for guild ${this.config.bot.guildId}`);
+      }
       startupLog('Slash commands registration complete');
 
       const databaseMode = dbStatus.isDegraded
@@ -184,7 +190,7 @@ class TitanBot extends Client {
     app.get('/', (req, res) => {
       res.status(200).json({ 
         message: 'TitanBot System Online',
-        version: '2.0.0',
+        version: pkg.version,
         timestamp: new Date().toISOString()
       });
     });
@@ -303,7 +309,8 @@ class TitanBot extends Client {
 
   async registerCommands() {
     try {
-      await registerSlashCommands(this, this.config.bot.guildId);
+      const { clientId, guildId, multiGuild } = this.config.bot;
+      await registerSlashCommands(this, { clientId, guildId, multiGuild });
     } catch (error) {
       logger.error('Error registering commands:', error);
     }

src/app.js

@@ -1,5 +1,5 @@
 import { SlashCommandBuilder, MessageFlags, ChannelType } from 'discord.js';
-import { createEmbed, errorEmbed, successEmbed } from '../../utils/embeds.js';
+import { createEmbed, successEmbed } from '../../utils/embeds.js';
 import { logger } from '../../utils/logger.js';
 import { handleInteractionError } from '../../utils/errorHandler.js';
 
@@ -93,10 +93,7 @@ export default {
                 case 'setchannel':
                     return await birthdaySetchannel.execute(interaction, config, client);
                 default:
-                    return InteractionHelper.safeReply(interaction, {
-                        embeds: [errorEmbed('Error', 'Unknown subcommand')],
-                        flags: MessageFlags.Ephemeral
-                    });
+                    return await replyUserError(interaction, { type: ErrorTypes.UNKNOWN, message: 'Unknown subcommand' });
             }
         } catch (error) {
             logger.error('Birthday command execution failed', {

src/commands/Birthday/birthday.js

@@ -1,5 +1,5 @@
 import { SlashCommandBuilder, PermissionFlagsBits, PermissionsBitField, ChannelType, ActionRowBuilder, ButtonBuilder, ButtonStyle, EmbedBuilder, ModalBuilder, TextInputBuilder, TextInputStyle, ComponentType, LabelBuilder, RoleSelectMenuBuilder } from 'discord.js';
-import { createEmbed, errorEmbed, successEmbed } from '../../utils/embeds.js';
+import { createEmbed, successEmbed } from '../../utils/embeds.js';
 import { getColor } from '../../config/bot.js';
 import { logger } from '../../utils/logger.js';
 import { handleInteractionError, withErrorHandling, createError, ErrorTypes } from '../../utils/errorHandler.js';
@@ -103,10 +103,7 @@ export default {
 
     execute: withErrorHandling(async (interaction) => {
         if (!interaction.inGuild()) {
-            return InteractionHelper.safeReply(interaction, {
-                embeds: [errorEmbed('This command can only be used in a server.')],
-                flags: ["Ephemeral"],
-            });
+            return await replyUserError(interaction, { type: ErrorTypes.UNKNOWN, message: 'This command can only be used in a server.' });
         }
 
         const { options, guild, member } = interaction;
@@ -140,10 +137,7 @@ export default {
 async function handleSetup(interaction) {
 
     if (interaction.deferred || interaction.replied) {
-        return InteractionHelper.safeReply(interaction, {
-            embeds: [errorEmbed('This interaction has already been processed. Please try the command again.')],
-            flags: ["Ephemeral"],
-        });
+        return await replyUserError(interaction, { type: ErrorTypes.UNKNOWN, message: 'This interaction has already been processed. Please try the command again.' });
     }
 
     const modal = new ModalBuilder()
@@ -226,10 +220,7 @@ async function handleSetup(interaction) {
     const roleId = selectedRoles.first()?.id;
 
     if (!roleId) {
-        await submitted.reply({
-            embeds: [errorEmbed('No Role Selected', 'You must select a role for the application.')],
-            flags: ['Ephemeral'],
-        });
+        await replyUserError(submitted, { type: ErrorTypes.USER_INPUT, message: 'You must select a role for the application.' });
         return;
     }
 
@@ -241,19 +232,13 @@ async function handleSetup(interaction) {
 
     const role = await interaction.guild.roles.fetch(roleId).catch(() => null);
     if (!role) {
-        await submitted.reply({
-            embeds: [errorEmbed('Invalid Role', 'The selected role could not be found.')],
-            flags: ['Ephemeral'],
-        });
+        await replyUserError(submitted, { type: ErrorTypes.VALIDATION, message: 'The selected role could not be found.' });
         return;
     }
 
     const existingRoles = await getApplicationRoles(interaction.client, interaction.guild.id);
     if (existingRoles.some(r => r.roleId === roleId)) {
-        await submitted.reply({
-            embeds: [errorEmbed('Already Configured', `The role ${role} is already configured as an application.`)],
-            flags: ['Ephemeral'],
-        });
+        await replyUserError(submitted, { type: ErrorTypes.CONFIGURATION, message: 'The role ${role} is already configured as an application.' });
         return;
     }
 
@@ -294,19 +279,11 @@ async function handleReview(interaction) {
         appId,
     );
     if (!application) {
-        return InteractionHelper.safeEditReply(interaction, {
-            embeds: [errorEmbed('Application not found.')],
-            flags: ["Ephemeral"],
-        });
+        return await replyUserError(interaction, { type: ErrorTypes.USER_INPUT, message: 'Application not found.' });
     }
 
     if (application.status !== "pending") {
-        return InteractionHelper.safeEditReply(interaction, {
-            embeds: [
-                errorEmbed('This application has already been processed.'),
-            ],
-            flags: ["Ephemeral"],
-        });
+        return await replyUserError(interaction, { type: ErrorTypes.UNKNOWN, message: 'This application has already been processed.' });
     }
 
     const appEmbed = createEmbed({
@@ -483,10 +460,7 @@ async function handleReview(interaction) {
 
         } catch (error) {
             logger.error('Error reviewing application:', error);
-            await buttonInteraction.reply({
-                embeds: [errorEmbed('Error', 'An error occurred while reviewing the application.')],
-                flags: ["Ephemeral"],
-            });
+            await replyUserError(buttonInteraction, { type: ErrorTypes.UNKNOWN, message: 'An error occurred while reviewing the application.' });
         }
     });
 
@@ -568,15 +542,7 @@ async function handleList(interaction) {
 
             return InteractionHelper.safeEditReply(interaction, { embeds: [embed], flags: ["Ephemeral"] });
         } else {
-            return InteractionHelper.safeEditReply(interaction, {
-                embeds: [
-                    errorEmbed(
-                        "No applications found and no application roles configured.\n" +
-                        "Use `/app-admin roles add` to configure application roles first."
-                    ),
-                ],
-                flags: ["Ephemeral"],
-            });
+            return await replyUserError(interaction, { type: ErrorTypes.CONFIGURATION, message: '"No applications found and no application roles configured.\\n" +\n                        "Use `/app-admin roles add` to configure application roles first."' });
         }
     }
 
@@ -624,10 +590,7 @@ export async function handleApplicationReviewModal(interaction) {
     try {
         const application = await getApplication(interaction.client, interaction.guild.id, appId);
         if (!application) {
-            return InteractionHelper.safeReply(interaction, {
-                embeds: [errorEmbed('Application not found.')],
-                flags: ["Ephemeral"]
-            });
+            return await replyUserError(interaction, { type: ErrorTypes.USER_INPUT, message: 'Application not found.' });
         }
 
         const status = isApprove ? 'approved' : 'denied';
@@ -703,9 +666,6 @@ export async function handleApplicationReviewModal(interaction) {
 
     } catch (error) {
         logger.error('Error processing application review:', error);
-        await InteractionHelper.safeEditReply(interaction, {
-            embeds: [errorEmbed('An error occurred while processing the application.')],
-            flags: ["Ephemeral"]
-        });
+        await replyUserError(interaction, { type: ErrorTypes.UNKNOWN, message: 'An error occurred while processing the application.' });
     }
 }

src/commands/Community/app-admin.js

@@ -1,6 +1,6 @@
 import { getColor } from '../../config/bot.js';
 import { SlashCommandBuilder, ActionRowBuilder, ModalBuilder, TextInputBuilder, TextInputStyle } from 'discord.js';
-import { createEmbed, errorEmbed, successEmbed } from '../../utils/embeds.js';
+import { createEmbed, successEmbed } from '../../utils/embeds.js';
 import { logger } from '../../utils/logger.js';
 import { handleInteractionError, withErrorHandling, createError, ErrorTypes } from '../../utils/errorHandler.js';
 import ApplicationService from '../../services/applicationService.js';
@@ -72,10 +72,7 @@ export default {
 
     execute: withErrorHandling(async (interaction) => {
         if (!interaction.inGuild()) {
-            return InteractionHelper.safeReply(interaction, {
-                embeds: [errorEmbed('This command can only be used in a server.')],
-                flags: ["Ephemeral"],
-            });
+            return await replyUserError(interaction, { type: ErrorTypes.UNKNOWN, message: 'This command can only be used in a server.' });
         }
 
         const { options, guild, member } = interaction;
@@ -128,19 +125,13 @@ export async function handleApplicationModal(interaction) {
     const applicationRole = applicationRoles.find(appRole => appRole.roleId === roleId);
 
     if (!applicationRole) {
-        return InteractionHelper.safeEditReply(interaction, {
-            embeds: [errorEmbed('Application configuration not found.')],
-            flags: ["Ephemeral"]
-        });
+        return await replyUserError(interaction, { type: ErrorTypes.CONFIGURATION, message: 'Application configuration not found.' });
     }
 
     const role = interaction.guild.roles.cache.get(roleId);
 
     if (!role) {
-        return InteractionHelper.safeEditReply(interaction, {
-            embeds: [errorEmbed('Role not found.')],
-            flags: ["Ephemeral"]
-        });
+        return await replyUserError(interaction, { type: ErrorTypes.USER_INPUT, message: 'Role not found.' });
     }
 
     const answers = [];
@@ -236,9 +227,7 @@ async function handleList(interaction) {
         const applicationRoles = await getApplicationRoles(interaction.client, interaction.guild.id);
 
         if (applicationRoles.length === 0) {
-            return InteractionHelper.safeEditReply(interaction, {
-                embeds: [errorEmbed('No applications are currently available.')],
-            });
+            return await replyUserError(interaction, { type: ErrorTypes.USER_INPUT, message: 'No applications are currently available.' });
         }
 
         const embed = createEmbed({
@@ -288,15 +277,7 @@ async function handleSubmit(interaction, settings) {
     );
 
     if (!applicationRole) {
-        return InteractionHelper.safeEditReply(interaction, {
-            embeds: [
-                errorEmbed(
-                    "Application not found.",
-                    "Use `/apply list` to see available applications."
-                ),
-            ],
-            flags: ["Ephemeral"],
-        });
+        return await replyUserError(interaction, { type: ErrorTypes.USER_INPUT, message: 'Use `/apply list` to see available applications.' });
     }
 
     const userApps = await getUserApplications(
@@ -307,22 +288,12 @@ async function handleSubmit(interaction, settings) {
     const pendingApp = userApps.find((app) => app.status === "pending");
 
     if (pendingApp) {
-        return InteractionHelper.safeEditReply(interaction, {
-            embeds: [
-                errorEmbed(
-                    `You already have a pending application. Please wait for it to be reviewed.`,
-                ),
-            ],
-            flags: ["Ephemeral"],
-        });
+        return await replyUserError(interaction, { type: ErrorTypes.UNKNOWN, message: 'You already have a pending application. Please wait for it to be reviewed.' });
     }
 
     const role = interaction.guild.roles.cache.get(applicationRole.roleId);
     if (!role) {
-        return InteractionHelper.safeEditReply(interaction, {
-            embeds: [errorEmbed('The role for this application no longer exists.')],
-            flags: ["Ephemeral"]
-        });
+        return await replyUserError(interaction, { type: ErrorTypes.USER_INPUT, message: 'The role for this application no longer exists.' });
     }
 
     const modal = new ModalBuilder()
@@ -365,14 +336,7 @@ async function handleStatus(interaction) {
         );
 
         if (!application || application.userId !== interaction.user.id) {
-            return InteractionHelper.safeEditReply(interaction, {
-                embeds: [
-                    errorEmbed(
-                        "Application not found or you do not have permission to view it.",
-                    ),
-                ],
-                flags: ["Ephemeral"],
-            });
+            return await replyUserError(interaction, { type: ErrorTypes.PERMISSION, message: 'Application not found or you do not have permission to view it.' });
         }
 
         const submittedAt = application?.createdAt ? new Date(application.createdAt) : null;
@@ -397,12 +361,7 @@ async function handleStatus(interaction) {
         );
 
         if (applications.length === 0) {
-            return InteractionHelper.safeEditReply(interaction, {
-                embeds: [
-                    errorEmbed('You have not submitted any applications yet.'),
-                ],
-                flags: ["Ephemeral"],
-            });
+            return await replyUserError(interaction, { type: ErrorTypes.UNKNOWN, message: 'You have not submitted any applications yet.' });
         }
 
         const recentApplications = applications