@julanzw/ttoolbox-discordjs-framework 1.0.1

package/README.md

@@ -0,0 +1,77 @@
+# TToolbox Discord Framework
+
+A TypeScript-first Discord.js command framework with built-in handlers, logging, and utilities.
+
+I made this for my own bots, but feel free to use it yourself!
+
+## Features
+
+- **Class-based commands** - Clean, extensible command structure
+- **Permission system** - Built-in user/admin/owner permission levels
+- **Logger** - Flexible logging with custom levels and colors
+- **Pagination** - Easy paginated embeds with buttons
+- **Modal helpers** - Simplified modal management
+- **Error handling** - Built-in error handling and validation
+- **TypeScript** - Full type safety
+
+## Installation
+
+```bash
+npm install @julanzw/ttoolbox-discord-framework discord.js
+```
+
+## Quick Start
+
+```typescript
+import { Client, GatewayIntentBits } from 'discord.js';
+import { Command, CommandManager, TToolboxLogger } from '@julanzw/ttoolbox-discord-framework';
+
+const client = new Client({
+  intents: [GatewayIntentBits.Guilds]
+});
+
+const logger = new TToolboxLogger();
+const commandManager = new CommandManager();
+
+// Create a command
+class PingCommand extends Command {
+  name = 'ping';
+  description = 'Pong!';
+  guildOnly = false;
+  permissionLevel = 'user' as const;
+
+  protected async run(interaction) {
+    await interaction.reply('Pong!');
+  }
+}
+
+// Register commands
+commandManager
+  .setLogger(logger)
+  .register(new PingCommand());
+
+// Handle interactions
+client.on('interactionCreate', async (interaction) => {
+  if (interaction.isChatInputCommand()) {
+    await commandManager.executeCommand(
+      interaction.commandName,
+      interaction,
+      client
+    );
+  }
+});
+
+client.login(process.env.DISCORD_TOKEN);
+```
+
+## Documentation
+
+(hopefully soon)
+
+## License
+
+AGPL-3.0 - See [LICENSE](./LICENSE) for details
+
+## Contributing
+
+Issues and pull requests are welcome!

package/dist/classes/Command.class.d.ts

@@ -0,0 +1,169 @@
+import { ChatInputCommandInteraction, Client, SlashCommandBuilder, SlashCommandSubcommandBuilder } from 'discord.js';
+import { PermissionLevel } from '../types/permission.js';
+import { ILogger } from '../types/logger.js';
+/**
+ * Abstract base class for Discord slash commands.
+ *
+ * Provides a structured way to create slash commands with built-in validation,
+ * error handling, and permission management. Child classes should extend this
+ * and implement the required abstract properties and the `run` method.
+ *
+ * @example
+ * ```typescript
+ * export class PingCommand extends Command {
+ *   name = 'ping';
+ *   description = 'Check bot latency';
+ *   guildOnly = false;
+ *   permissionLevel = 'user' as const;
+ *
+ *   protected async run(interaction: ChatInputCommandInteraction) {
+ *     await safeReply(interaction, `Pong! ${interaction.client.ws.ping}ms`);
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class Command {
+    /** The command name (used to invoke the command) */
+    abstract name: string;
+    /** A brief description of what the command does */
+    abstract description: string;
+    /** Whether this command can only be used in a guild (server) */
+    abstract guildOnly: boolean;
+    /** The minimum permission level required to use this command */
+    abstract permissionLevel: PermissionLevel;
+    /** Optional cooldown in milliseconds between command uses per user */
+    cooldown?: number;
+    /** Logger instance to use inside the command */
+    protected logger?: ILogger;
+    /**
+     * Validates whether the command can be executed in the current context.
+     *
+     * Checks if the command is being used in the correct context (guild vs DM)
+     * and calls additionalValidation for any custom validation logic.
+     *
+     * @param interaction - The command interaction to validate
+     * @returns Error message if validation fails, null if validation passes
+     * @protected
+     */
+    protected validate(interaction: ChatInputCommandInteraction): string | null;
+    /**
+     * Hook for additional custom validation logic.
+     *
+     * Override this method in child classes to add command-specific validation.
+     * For example, checking if a user has opted in/out, premium status, etc.
+     *
+     * @param interaction - The command interaction to validate
+     * @returns Error message if validation fails, null if validation passes
+     * @protected
+     *
+     * @example
+     * ```typescript
+     * protected additionalValidation(interaction: ChatInputCommandInteraction): string | null {
+     *   if (hasOptedOut(interaction.user.id)) {
+     *     return 'You have opted out of this feature.';
+     *   }
+     *   return null;
+     * }
+     * ```
+     */
+    protected additionalValidation(interaction: ChatInputCommandInteraction): string | null;
+    /**
+     * Safely executes a function with error handling and logging.
+     *
+     * Wraps the execution in a try-catch block, logs successful executions,
+     * and automatically handles errors by logging them and sending a user-friendly
+     * error message.
+     *
+     * @param commandName - The name of the command being executed
+     * @param interaction - The command interaction
+     * @param fn - The function to execute
+     * @private
+     */
+    private safeExecute;
+    /**
+     * Executes the command with validation and error handling.
+     *
+     * This is the main entry point when a command is invoked. It performs
+     * validation, then calls the `run` method if validation passes.
+     * Should not be overridden - override `run` instead.
+     *
+     * @param interaction - The command interaction
+     * @param client - The Discord client instance
+     */
+    execute(interaction: ChatInputCommandInteraction, client: Client): Promise<void>;
+    /**
+     * The main command logic - implement this in child classes.
+     *
+     * This method is called after all validation passes. Put your command's
+     * actual functionality here.
+     *
+     * @param interaction - The command interaction
+     * @param client - The Discord client instance
+     * @protected
+     *
+     * @example
+     * ```typescript
+     * protected async run(interaction: ChatInputCommandInteraction) {
+     *   const user = interaction.options.getUser('user', true);
+     *   await safeReply(interaction, `Hello, ${user.tag}!`);
+     * }
+     * ```
+     */
+    protected abstract run(interaction: ChatInputCommandInteraction, client: Client): Promise<void>;
+    /**
+     * Customize the slash command builder with options, choices, etc.
+     *
+     * Override this method to add options (string, integer, user, etc.) to your command.
+     * Works with both standalone commands and subcommands.
+     *
+     * @param builder - The slash command builder to customize
+     * @returns The customized builder
+     *
+     * @example
+     * ```typescript
+     * customize(builder: SlashCommandBuilder) {
+     *   return builder
+     *     .addStringOption(option =>
+     *       option
+     *         .setName('message')
+     *         .setDescription('The message to send')
+     *         .setRequired(true)
+     *     )
+     *     .addUserOption(option =>
+     *       option
+     *         .setName('user')
+     *         .setDescription('The user to mention')
+     *         .setRequired(false)
+     *     );
+     * }
+     * ```
+     */
+    customize?(builder: SlashCommandBuilder | SlashCommandSubcommandBuilder): SlashCommandBuilder | SlashCommandSubcommandBuilder;
+    /**
+     * Converts the command to Discord API JSON format for registration.
+     *
+     * This method builds the SlashCommandBuilder with the command's metadata
+     * (name, description, permissions) and any custom options, then returns
+     * the JSON representation needed for Discord's API.
+     *
+     * Called automatically by CommandManager when registering commands.
+     *
+     * @returns The command in Discord API JSON format
+     */
+    toJSON(): import("discord.js").RESTPostAPIChatInputApplicationCommandsJSONBody;
+    /**
+     * Sets the logger for this command.
+     *
+     * @param logger - Logger instance implementing ILogger interface
+     */
+    setLogger(logger: ILogger): void;
+    /**
+     * Log a message using the configured logger.
+     *
+     * @param message - The message to log
+     * @param level - The log level
+     * @param scope - The scope/context
+     * @param logToConsole - Whether to also log to console
+     */
+    protected log(message: string, level: string, scope: string, logToConsole?: boolean): void;
+}

package/dist/classes/Command.class.js

@@ -0,0 +1,156 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { SlashCommandBuilder, } from 'discord.js';
+import { safeReply } from '../utils/editAndReply.js';
+import { getPermissionsForLevel } from '../utils/permissions.js';
+import { checkCooldown } from '../utils/cooldown.js';
+import { formatDuration } from '../utils/formatting.js';
+/**
+ * Abstract base class for Discord slash commands.
+ *
+ * Provides a structured way to create slash commands with built-in validation,
+ * error handling, and permission management. Child classes should extend this
+ * and implement the required abstract properties and the `run` method.
+ *
+ * @example
+ * ```typescript
+ * export class PingCommand extends Command {
+ *   name = 'ping';
+ *   description = 'Check bot latency';
+ *   guildOnly = false;
+ *   permissionLevel = 'user' as const;
+ *
+ *   protected async run(interaction: ChatInputCommandInteraction) {
+ *     await safeReply(interaction, `Pong! ${interaction.client.ws.ping}ms`);
+ *   }
+ * }
+ * ```
+ */
+export class Command {
+    /**
+     * Validates whether the command can be executed in the current context.
+     *
+     * Checks if the command is being used in the correct context (guild vs DM)
+     * and calls additionalValidation for any custom validation logic.
+     *
+     * @param interaction - The command interaction to validate
+     * @returns Error message if validation fails, null if validation passes
+     * @protected
+     */
+    validate(interaction) {
+        if (this.guildOnly && !interaction.guildId) {
+            return 'This command can only be used in a server.';
+        }
+        const secondsRemaining = checkCooldown(this.name, this.cooldown, interaction.user.id);
+        if (secondsRemaining > 0) {
+            return `You need to wait ${formatDuration(secondsRemaining)} before using this command again.`;
+        }
+        return this.additionalValidation(interaction);
+    }
+    /**
+     * Hook for additional custom validation logic.
+     *
+     * Override this method in child classes to add command-specific validation.
+     * For example, checking if a user has opted in/out, premium status, etc.
+     *
+     * @param interaction - The command interaction to validate
+     * @returns Error message if validation fails, null if validation passes
+     * @protected
+     *
+     * @example
+     * ```typescript
+     * protected additionalValidation(interaction: ChatInputCommandInteraction): string | null {
+     *   if (hasOptedOut(interaction.user.id)) {
+     *     return 'You have opted out of this feature.';
+     *   }
+     *   return null;
+     * }
+     * ```
+     */
+    additionalValidation(interaction) {
+        return null;
+    }
+    /**
+     * Safely executes a function with error handling and logging.
+     *
+     * Wraps the execution in a try-catch block, logs successful executions,
+     * and automatically handles errors by logging them and sending a user-friendly
+     * error message.
+     *
+     * @param commandName - The name of the command being executed
+     * @param interaction - The command interaction
+     * @param fn - The function to execute
+     * @private
+     */
+    async safeExecute(commandName, interaction, fn) {
+        const scope = `${commandName}_EXECUTION`;
+        try {
+            await fn();
+            const subcommandName = interaction.options.getSubcommand(false);
+            this.logger?.log(`${commandName} ${subcommandName ? `(${subcommandName}) ` : ``}command executed`, 'info', scope);
+        }
+        catch (err) {
+            this.logger?.log(
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+            `An Error occurred: ${err.message ?? err}`, 'error', scope, true);
+            return await safeReply(interaction, 'An unexpected error occurred.');
+        }
+    }
+    /**
+     * Executes the command with validation and error handling.
+     *
+     * This is the main entry point when a command is invoked. It performs
+     * validation, then calls the `run` method if validation passes.
+     * Should not be overridden - override `run` instead.
+     *
+     * @param interaction - The command interaction
+     * @param client - The Discord client instance
+     */
+    async execute(interaction, client) {
+        await this.safeExecute(this.name, interaction, async () => {
+            const error = this.validate(interaction);
+            if (error)
+                return await safeReply(interaction, error, true);
+            await this.run(interaction, client);
+        });
+    }
+    /**
+     * Converts the command to Discord API JSON format for registration.
+     *
+     * This method builds the SlashCommandBuilder with the command's metadata
+     * (name, description, permissions) and any custom options, then returns
+     * the JSON representation needed for Discord's API.
+     *
+     * Called automatically by CommandManager when registering commands.
+     *
+     * @returns The command in Discord API JSON format
+     */
+    toJSON() {
+        const builder = new SlashCommandBuilder()
+            .setName(this.name)
+            .setDescription(this.description)
+            .setDefaultMemberPermissions(getPermissionsForLevel(this.permissionLevel));
+        if (this.customize) {
+            this.customize(builder);
+        }
+        return builder.toJSON();
+    }
+    /**
+     * Sets the logger for this command.
+     *
+     * @param logger - Logger instance implementing ILogger interface
+     */
+    setLogger(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Log a message using the configured logger.
+     *
+     * @param message - The message to log
+     * @param level - The log level
+     * @param scope - The scope/context
+     * @param logToConsole - Whether to also log to console
+     */
+    log(message, level, scope, logToConsole = false) {
+        this.logger?.log(message, level, scope, logToConsole);
+    }
+}

package/dist/classes/CommandManager.class.d.ts

@@ -0,0 +1,69 @@
+import { ChatInputCommandInteraction, Client, RESTPostAPIChatInputApplicationCommandsJSONBody } from 'discord.js';
+import { ILogger } from '../types/logger.js';
+import { Command } from './Command.class.js';
+import { SubcommandGroup } from './SubcommandGroup.class.js';
+export declare class CommandManager {
+    private commands;
+    protected logger?: ILogger;
+    /**
+     * Register a single command or subcommand group
+     */
+    register(command: Command | SubcommandGroup): this;
+    /**
+     * Register multiple commands at once
+     */
+    registerMultiple(commands: Array<Command | SubcommandGroup>): this;
+    /**
+     * Get a specific command by name
+     */
+    get(name: string): Command | SubcommandGroup | undefined;
+    /**
+     * Get all registered commands
+     */
+    getAll(): Array<Command | SubcommandGroup>;
+    /**
+     * Get all commands sorted alphabetically by name
+     */
+    getAllSorted(): Array<Command | SubcommandGroup>;
+    /**
+     * Convert all commands to Discord JSON format for registration
+     */
+    toDiscordJSON(): RESTPostAPIChatInputApplicationCommandsJSONBody[];
+    /**
+     * Generate paginated help pages for display in help command
+     * Returns a 2D array where each inner array is a page of command descriptions
+     *
+     * @param commandsPerPage - How many regular commands to show per page (default: 10)
+     * @returns 2D array of command info for pagination
+     */
+    getHelpPages(commandsPerPage?: number): Array<Array<{
+        name: string;
+        value: string;
+    }>>;
+    /**
+     * Execute a command by name
+     * This is called from your interaction handler
+     */
+    executeCommand(commandName: string, interaction: ChatInputCommandInteraction, client: Client): Promise<void>;
+    /**
+     * Get total number of registered commands
+     */
+    get size(): number;
+    /**
+     * Check if a command exists
+     */
+    has(name: string): boolean;
+    /**
+     * Remove a command (useful for hot-reloading in dev)
+     */
+    unregister(name: string): boolean;
+    /**
+     * Clear all commands
+     */
+    clear(): void;
+    /**
+     * Get command names as an array
+     */
+    getCommandNames(): string[];
+    setLogger(logger: ILogger): this;
+}

package/dist/classes/CommandManager.class.js

@@ -0,0 +1,149 @@
+import { SubcommandGroup } from './SubcommandGroup.class.js';
+export class CommandManager {
+    constructor() {
+        this.commands = new Map();
+    }
+    /**
+     * Register a single command or subcommand group
+     */
+    register(command) {
+        if (this.logger) {
+            command.setLogger(this.logger);
+        }
+        this.commands.set(command.name, command);
+        return this;
+    }
+    /**
+     * Register multiple commands at once
+     */
+    registerMultiple(commands) {
+        commands.forEach((cmd) => this.register(cmd));
+        return this;
+    }
+    /**
+     * Get a specific command by name
+     */
+    get(name) {
+        return this.commands.get(name);
+    }
+    /**
+     * Get all registered commands
+     */
+    getAll() {
+        return Array.from(this.commands.values());
+    }
+    /**
+     * Get all commands sorted alphabetically by name
+     */
+    getAllSorted() {
+        return this.getAll().sort((a, b) => a.name.localeCompare(b.name));
+    }
+    /**
+     * Convert all commands to Discord JSON format for registration
+     */
+    toDiscordJSON() {
+        return this.getAll().map((cmd) => {
+            if (process.env.ENV === 'dev') {
+                console.log(`Registering: ${cmd.name}`);
+            }
+            return cmd.toJSON();
+        });
+    }
+    /**
+     * Generate paginated help pages for display in help command
+     * Returns a 2D array where each inner array is a page of command descriptions
+     *
+     * @param commandsPerPage - How many regular commands to show per page (default: 10)
+     * @returns 2D array of command info for pagination
+     */
+    getHelpPages(commandsPerPage = 5) {
+        const subcommandPages = [];
+        const otherCommands = [];
+        for (const command of this.getAllSorted()) {
+            if (command instanceof SubcommandGroup) {
+                // Each subcommand group gets its own page
+                const page = [
+                    {
+                        name: `─── ${command.name.toUpperCase()} ───`,
+                        value: command.description || 'No description.',
+                    },
+                    ...command.getSubcommandList().map((sub) => ({
+                        name: `› ${sub.name}`,
+                        value: sub.description,
+                    })),
+                ];
+                subcommandPages.push(page);
+            }
+            else {
+                // Regular commands are grouped together
+                // Add a header when starting a new page
+                if (otherCommands.length % commandsPerPage === 0) {
+                    otherCommands.push({
+                        name: `─── OTHER ───`,
+                        value: 'Other commands',
+                    });
+                }
+                otherCommands.push({
+                    name: `› ${command.name}`,
+                    value: command.description,
+                });
+            }
+        }
+        // Combine subcommand pages first, then regular command pages
+        const allPages = [...subcommandPages];
+        // Split regular commands into pages
+        while (otherCommands.length) {
+            allPages.push(otherCommands.splice(0, commandsPerPage));
+        }
+        return allPages;
+    }
+    /**
+     * Execute a command by name
+     * This is called from your interaction handler
+     */
+    async executeCommand(commandName, interaction, client) {
+        const command = this.get(commandName);
+        if (!command) {
+            throw new Error(`Command not found: ${commandName}`);
+        }
+        await command.execute(interaction, client);
+    }
+    /**
+     * Get total number of registered commands
+     */
+    get size() {
+        return this.commands.size;
+    }
+    /**
+     * Check if a command exists
+     */
+    has(name) {
+        return this.commands.has(name);
+    }
+    /**
+     * Remove a command (useful for hot-reloading in dev)
+     */
+    unregister(name) {
+        return this.commands.delete(name);
+    }
+    /**
+     * Clear all commands
+     */
+    clear() {
+        this.commands.clear();
+    }
+    /**
+     * Get command names as an array
+     */
+    getCommandNames() {
+        return Array.from(this.commands.keys());
+    }
+    setLogger(logger) {
+        this.logger = logger;
+        // Inject logger into all already-registered commands
+        for (const command of this.commands.values()) {
+            command.setLogger(logger);
+        }
+        return this;
+    }
+}