@julanzw/ttoolbox-discordjs-framework 1.0.1

package/dist/classes/ModalManager.class.js

@@ -0,0 +1,205 @@
+// core/utils/ModalManager.js
+import { ActionRowBuilder, TextInputBuilder, ModalBuilder, } from 'discord.js';
+/**
+ * Manages modal creation, registration, and submission handling.
+ *
+ * Provides a centralized way to create and track modals throughout the bot.
+ * Modals can be registered with their submission handlers and automatically
+ * cleaned up after use if marked as ephemeral.
+ *
+ * @example
+ * ```typescript
+ * const modalManager = new ModalManager();
+ *
+ * // Create and register a modal
+ * const modal = modalManager.buildAndRegister({
+ *   id: 'feedback-modal',
+ *   title: 'Submit Feedback',
+ *   ephemeral: true,
+ *   fields: [
+ *     {
+ *       customId: 'message',
+ *       name: 'Your Feedback',
+ *       style: TextInputStyle.Paragraph,
+ *       required: true,
+ *     }
+ *   ],
+ *   onSubmit: async (interaction) => {
+ *     const feedback = interaction.fields.getTextInputValue('message');
+ *     await interaction.reply('Thank you for your feedback!');
+ *   }
+ * });
+ *
+ * await interaction.showModal(modal);
+ * ```
+ */
+export class ModalManager {
+    constructor() {
+        this.modals = new Map();
+    }
+    /**
+     * Builds a Discord ModalBuilder and registers the modal for submission handling.
+     *
+     * Creates a modal with the specified fields and registers it so that when
+     * a user submits it, the onSubmit handler will be called.
+     *
+     * @param data - The modal configuration including fields and submission handler
+     * @returns A ModalBuilder ready to be shown to the user
+     *
+     * @example
+     * ```typescript
+     * const modal = modalManager.buildAndRegister({
+     *   id: 'edit-reminder',
+     *   title: 'Edit Reminder',
+     *   ephemeral: true,
+     *   fields: [
+     *     {
+     *       customId: 'message',
+     *       name: 'Reminder Message',
+     *       style: TextInputStyle.Short,
+     *       required: true,
+     *       value: existingMessage,
+     *     }
+     *   ],
+     *   onSubmit: async (interaction) => {
+     *     const newMessage = interaction.fields.getTextInputValue('message');
+     *     await updateReminder(id, newMessage);
+     *   }
+     * });
+     *
+     * await buttonInteraction.showModal(modal);
+     * ```
+     */
+    buildAndRegister(data) {
+        const modal = new ModalBuilder().setCustomId(data.id).setTitle(data.title);
+        for (const field of data.fields) {
+            const input = new TextInputBuilder()
+                .setCustomId(field.customId)
+                .setLabel(field.name)
+                .setStyle(field.style)
+                .setRequired(field.required ?? true);
+            if (field.placeholder)
+                input.setPlaceholder(field.placeholder);
+            if (field.minLength)
+                input.setMinLength(field.minLength);
+            if (field.maxLength)
+                input.setMaxLength(field.maxLength);
+            if (field.value)
+                input.setValue(field.value);
+            const row = new ActionRowBuilder().addComponents(input);
+            modal.addComponents(row);
+        }
+        this.modals.set(data.id, data);
+        return modal;
+    }
+    /**
+     * Retrieves a registered modal by its ID.
+     *
+     * Supports dynamic IDs - if the exact ID isn't found, attempts to match
+     * using the base ID (before the first colon). This allows for modals with
+     * dynamic suffixes like "edit-reminder:123".
+     *
+     * @param id - The modal ID to look up
+     * @returns The modal configuration, or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * // Register with base ID
+     * modalManager.buildAndRegister({ id: 'edit-reminder', ... });
+     *
+     * // Can retrieve with dynamic ID
+     * const modal = modalManager.get('edit-reminder:123'); // Works!
+     * ```
+     */
+    get(id) {
+        // Try exact match first
+        const modal = this.modals.get(id);
+        if (modal)
+            return modal;
+        // Try base ID (before colon) for dynamic IDs
+        const baseId = id.split(':')[0];
+        return this.modals.get(baseId);
+    }
+    /**
+     * Removes a modal from the registry.
+     *
+     * Useful for cleaning up ephemeral modals after they've been submitted,
+     * or for unregistering modals that are no longer needed.
+     *
+     * @param id - The modal ID to remove
+     * @returns true if the modal was removed, false if it didn't exist
+     *
+     * @example
+     * ```typescript
+     * // Clean up after submission
+     * await modalManager.handleSubmit(interaction);
+     * modalManager.remove(interaction.customId); // If ephemeral
+     * ```
+     */
+    remove(id) {
+        return this.modals.delete(id);
+    }
+    /**
+     * Handles a modal submission by calling the registered onSubmit handler.
+     *
+     * Looks up the modal by ID, calls its onSubmit handler, and automatically
+     * removes ephemeral modals from the registry after submission.
+     *
+     * @param interaction - The modal submit interaction
+     * @throws {Error} If no modal is found for the interaction's custom ID
+     *
+     * @example
+     * ```typescript
+     * // In your interaction handler
+     * client.on('interactionCreate', async (interaction) => {
+     *   if (interaction.isModalSubmit()) {
+     *     await modalManager.handleSubmit(interaction);
+     *   }
+     * });
+     * ```
+     */
+    async handleSubmit(interaction) {
+        const modal = this.get(interaction.customId);
+        if (!modal) {
+            throw new Error(`Modal not found: ${interaction.customId}`);
+        }
+        await modal.onSubmit(interaction);
+        // Clean up ephemeral modals
+        if (modal.ephemeral) {
+            this.remove(interaction.customId);
+        }
+    }
+    /**
+     * Checks if a modal with the given ID is registered.
+     *
+     * @param id - The modal ID to check
+     * @returns true if the modal exists in the registry
+     */
+    has(id) {
+        return this.modals.has(id) || this.modals.has(id.split(':')[0]);
+    }
+    /**
+     * Clears all registered modals from the registry.
+     *
+     * Useful for cleanup during bot shutdown or for testing.
+     */
+    clear() {
+        this.modals.clear();
+    }
+    /**
+     * Gets the total number of registered modals.
+     *
+     * @returns The count of modals in the registry
+     */
+    get size() {
+        return this.modals.size;
+    }
+    /**
+     * Gets all registered modal IDs.
+     *
+     * @returns Array of modal IDs currently in the registry
+     */
+    getModalIds() {
+        return Array.from(this.modals.keys());
+    }
+}

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

@@ -0,0 +1,127 @@
+import { ChatInputCommandInteraction, Client, RESTPostAPIChatInputApplicationCommandsJSONBody } from 'discord.js';
+import { ILogger } from '../types/logger.js';
+import { Command } from './Command.class.js';
+/**
+ * Abstract base class for Discord slash command groups with subcommands.
+ *
+ * Use this when you have multiple related commands that should be grouped together
+ * under a single parent command.
+ *
+ * For example, `/birthday set` and `/birthday calendar`
+ * would both be subcommands of a `BirthdayCommands` subcommand group.
+ *
+ * @example
+ * ```typescript
+ * export class BirthdayCommands extends SubcommandGroup {
+ *   name = 'birthday';
+ *   description = 'All commands related to birthdays';
+ *
+ *   protected subcommands = new Map<string, Command>([
+ *     ['set', new SetBirthdayCommand()],
+ *     ['calendar', new CalendarCommand()],
+ *   ]);
+ * }
+ * ```
+ */
+export declare abstract class SubcommandGroup {
+    /** The parent command name (e.g., 'birthday' for `/birthday set`) */
+    abstract name: string;
+    /** A brief description of the command group */
+    abstract description: string;
+    /** Map of subcommand names to Command instances */
+    protected abstract subcommands: Map<string, Command>;
+    /** The logger instance used in the subcommand group */
+    protected logger?: ILogger;
+    /**
+     * 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 parent command
+     * @param scope - The logging scope for this execution
+     * @param interaction - The command interaction
+     * @param fn - The function to execute
+     * @private
+     */
+    private safeExecute;
+    /**
+     * Executes the appropriate subcommand based on the user's interaction.
+     *
+     * This method:
+     * 1. Determines which subcommand was invoked
+     * 2. Looks up the corresponding Command instance
+     * 3. Executes the subcommand with error handling
+     *
+     * Called automatically by the CommandManager when this command group is invoked.
+     *
+     * @param interaction - The command interaction
+     * @param client - The Discord client instance
+     * @throws {Error} If the subcommand name doesn't exist in the subcommands map
+     *
+     * @example
+     * When a user runs `/birthday set`, this method:
+     * - Gets "set" from interaction.options.getSubcommand()
+     * - Looks up the SetBirthdayCommand in the subcommands map
+     * - Calls SetBirthdayCommand.execute()
+     */
+    execute(interaction: ChatInputCommandInteraction, client: Client): Promise<void>;
+    /**
+     * Converts the command group to Discord API JSON format for registration.
+     *
+     * This method:
+     * 1. Creates a SlashCommandBuilder with the group's name and description
+     * 2. Adds each subcommand from the subcommands map
+     * 3. Applies any custom options from each subcommand's `customize` method
+     * 4. Returns the JSON representation needed for Discord's API
+     *
+     * Called automatically by CommandManager when registering commands.
+     *
+     * @returns The command group in Discord API JSON format
+     *
+     * @example
+     * For a birthday command group with "set" and "calendar" subcommands,
+     * this creates the structure for:
+     * - `/birthday set <options>`
+     * - `/birthday calendar`
+     */
+    toJSON(): RESTPostAPIChatInputApplicationCommandsJSONBody;
+    /**
+     * Gets a list of all subcommands with their names and descriptions.
+     *
+     * Useful for generating help text or documentation about available subcommands.
+     * Used by CommandManager's `getHelpPages` method to display subcommands in the help command.
+     *
+     * @returns Array of objects containing subcommand names and descriptions
+     *
+     * @example
+     * ```typescript
+     * const subcommands = birthdayCommands.getSubcommandList();
+     * // Returns:
+     * // [
+     * //   { name: 'set', description: 'Set your birthday' },
+     * //   { name: 'calendar', description: 'View birthday calendar' }
+     * // ]
+     * ```
+     */
+    getSubcommandList(): Array<{
+        name: string;
+        description: string;
+    }>;
+    /**
+     * Sets the logger for this subcommand group.
+     *
+     * @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/SubcommandGroup.class.js

@@ -0,0 +1,156 @@
+import { SlashCommandBuilder, } from 'discord.js';
+import { safeReply } from '../utils/editAndReply.js';
+/**
+ * Abstract base class for Discord slash command groups with subcommands.
+ *
+ * Use this when you have multiple related commands that should be grouped together
+ * under a single parent command.
+ *
+ * For example, `/birthday set` and `/birthday calendar`
+ * would both be subcommands of a `BirthdayCommands` subcommand group.
+ *
+ * @example
+ * ```typescript
+ * export class BirthdayCommands extends SubcommandGroup {
+ *   name = 'birthday';
+ *   description = 'All commands related to birthdays';
+ *
+ *   protected subcommands = new Map<string, Command>([
+ *     ['set', new SetBirthdayCommand()],
+ *     ['calendar', new CalendarCommand()],
+ *   ]);
+ * }
+ * ```
+ */
+export class SubcommandGroup {
+    /**
+     * 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 parent command
+     * @param scope - The logging scope for this execution
+     * @param interaction - The command interaction
+     * @param fn - The function to execute
+     * @private
+     */
+    async safeExecute(commandName, scope, interaction, fn) {
+        try {
+            await fn();
+            const subcommandName = interaction.options.getSubcommand(false);
+            this.logger?.log(`${commandName} ${subcommandName ? `(${subcommandName}) ` : ``}command executed`, 'info', scope);
+        }
+        catch (err) {
+            this.logger?.log('An Error occured' + err, 'error', scope, true);
+            return await safeReply(interaction, 'An unexpected error occurred.');
+        }
+    }
+    /**
+     * Executes the appropriate subcommand based on the user's interaction.
+     *
+     * This method:
+     * 1. Determines which subcommand was invoked
+     * 2. Looks up the corresponding Command instance
+     * 3. Executes the subcommand with error handling
+     *
+     * Called automatically by the CommandManager when this command group is invoked.
+     *
+     * @param interaction - The command interaction
+     * @param client - The Discord client instance
+     * @throws {Error} If the subcommand name doesn't exist in the subcommands map
+     *
+     * @example
+     * When a user runs `/birthday set`, this method:
+     * - Gets "set" from interaction.options.getSubcommand()
+     * - Looks up the SetBirthdayCommand in the subcommands map
+     * - Calls SetBirthdayCommand.execute()
+     */
+    async execute(interaction, client) {
+        const subcommandName = interaction.options.getSubcommand();
+        const subcommand = this.subcommands.get(subcommandName);
+        if (!subcommand) {
+            throw new Error(`Unknown subcommand: ${subcommandName}`);
+        }
+        const scope = `${subcommand.name}_EXECUTION`;
+        await this.safeExecute(this.name, scope, interaction, () => subcommand.execute(interaction, client));
+    }
+    /**
+     * Converts the command group to Discord API JSON format for registration.
+     *
+     * This method:
+     * 1. Creates a SlashCommandBuilder with the group's name and description
+     * 2. Adds each subcommand from the subcommands map
+     * 3. Applies any custom options from each subcommand's `customize` method
+     * 4. Returns the JSON representation needed for Discord's API
+     *
+     * Called automatically by CommandManager when registering commands.
+     *
+     * @returns The command group in Discord API JSON format
+     *
+     * @example
+     * For a birthday command group with "set" and "calendar" subcommands,
+     * this creates the structure for:
+     * - `/birthday set <options>`
+     * - `/birthday calendar`
+     */
+    toJSON() {
+        const builder = new SlashCommandBuilder()
+            .setName(this.name)
+            .setDescription(this.description);
+        for (const cmd of this.subcommands.values()) {
+            builder.addSubcommand((sc) => {
+                sc.setName(cmd.name).setDescription(cmd.description);
+                if (cmd.customize) {
+                    cmd.customize(sc);
+                }
+                return sc;
+            });
+        }
+        return builder.toJSON();
+    }
+    /**
+     * Gets a list of all subcommands with their names and descriptions.
+     *
+     * Useful for generating help text or documentation about available subcommands.
+     * Used by CommandManager's `getHelpPages` method to display subcommands in the help command.
+     *
+     * @returns Array of objects containing subcommand names and descriptions
+     *
+     * @example
+     * ```typescript
+     * const subcommands = birthdayCommands.getSubcommandList();
+     * // Returns:
+     * // [
+     * //   { name: 'set', description: 'Set your birthday' },
+     * //   { name: 'calendar', description: 'View birthday calendar' }
+     * // ]
+     * ```
+     */
+    getSubcommandList() {
+        return Array.from(this.subcommands.values()).map((sub) => ({
+            name: sub.name,
+            description: sub.description,
+        }));
+    }
+    /**
+     * Sets the logger for this subcommand group.
+     *
+     * @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/index.d.ts

@@ -0,0 +1,18 @@
+export { Command } from './classes/Command.class.js';
+export { SubcommandGroup } from './classes/SubcommandGroup.class.js';
+export { CommandManager } from './classes/CommandManager.class.js';
+export { DiscordHandler } from './classes/DiscordHandler.class.js';
+export { ModalManager } from './classes/ModalManager.class.js';
+export { PaginatedEmbed } from './utils/PaginatedEmbed.class.js';
+export type { PermissionLevel } from './types/permission.js';
+export type { Modal, ModalField } from './types/modal.js';
+export type { ButtonType } from './types/button.js';
+export type { ILogger } from './types/logger.js';
+export { getPermissionsForLevel } from './utils/permissions.js';
+export { embedBuilder, createButton, createButtonsRow, createPaginationButtons, } from './utils/embeds.js';
+export { stringOption, integerOption, booleanOption, userOption, channelOption, roleOption, } from './utils/slashCommandOptions.js';
+export { safeReply, safeEdit } from './utils/editAndReply.js';
+export { formatDuration, formatDateToString, formatDateToYYYYMMDDHHMMSS, formatDateToDDMMYYYY, getDaySuffix, capitalizeFirst, } from './utils/formatting.js';
+export { TIMES_MILISECONDS } from './utils/miliseconds.js';
+export { TToolboxLogger } from './utils/TToolboxLogger.class.js';
+export { InteractionError } from './classes/InteractionError.class.js';

package/dist/index.js

@@ -0,0 +1,17 @@
+// Classes
+export { Command } from './classes/Command.class.js';
+export { SubcommandGroup } from './classes/SubcommandGroup.class.js';
+export { CommandManager } from './classes/CommandManager.class.js';
+export { DiscordHandler } from './classes/DiscordHandler.class.js';
+export { ModalManager } from './classes/ModalManager.class.js';
+export { PaginatedEmbed } from './utils/PaginatedEmbed.class.js';
+// Utilities
+export { getPermissionsForLevel } from './utils/permissions.js';
+export { embedBuilder, createButton, createButtonsRow, createPaginationButtons, } from './utils/embeds.js';
+export { stringOption, integerOption, booleanOption, userOption, channelOption, roleOption, } from './utils/slashCommandOptions.js';
+export { safeReply, safeEdit } from './utils/editAndReply.js';
+export { formatDuration, formatDateToString, formatDateToYYYYMMDDHHMMSS, formatDateToDDMMYYYY, getDaySuffix, capitalizeFirst, } from './utils/formatting.js';
+export { TIMES_MILISECONDS } from './utils/miliseconds.js';
+export { TToolboxLogger } from './utils/TToolboxLogger.class.js';
+// Errors
+export { InteractionError } from './classes/InteractionError.class.js';

package/dist/types/button.d.ts

@@ -0,0 +1,2 @@
+export type ButtonType = 'prev' | 'next' | 'edit' | 'delete';
+export type PaginationButtonLocation = 'embrace' | 'start' | 'end';

package/dist/types/button.js

@@ -0,0 +1 @@
+export {};

package/dist/types/channel.d.ts

@@ -0,0 +1,2 @@
+import { ChannelType } from 'discord.js';
+export type AllowedChannelTypeChannelOption = ChannelType.GuildText | ChannelType.GuildVoice | ChannelType.GuildCategory | ChannelType.GuildAnnouncement | ChannelType.AnnouncementThread | ChannelType.PublicThread | ChannelType.PrivateThread | ChannelType.GuildStageVoice | ChannelType.GuildForum | ChannelType.GuildMedia;

package/dist/types/channel.js

@@ -0,0 +1 @@
+export {};

package/dist/types/logger.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Configuration options for TToolboxLogger.
+ */
+export type LoggerOptions = {
+    /** Directory where log files should be stored */
+    logDir?: string;
+    /** Name of the log file */
+    logFileName?: string;
+    /** Custom log levels to use instead of defaults */
+    customLevels?: Record<string, string>;
+    /** Whether to extend default levels or replace them entirely */
+    extendDefaultLevels?: boolean;
+};
+/**
+ * Logger interface for TToolbox framework.
+ *
+ * Allows any logger implementation to be used with the framework,
+ * as long as it provides these core methods.
+ *
+ * @example
+ * ```typescript
+ * const customLogger: ILogger = {
+ *   log: (msg, level, scope, console) => myCustomLog(msg),
+ *   info: (msg, scope, console) => console.log(msg),
+ *   warn: (msg, scope, console) => console.warn(msg),
+ *   error: (msg, scope, console) => console.error(msg),
+ * };
+ *
+ * commandManager.setLogger(customLogger);
+ * ```
+ */
+export interface ILogger {
+    log(message: string, level: string, scope: string, logToConsole?: boolean): void;
+    info(message: string, scope: string, logToConsole?: boolean): void;
+    warn(message: string, scope: string, logToConsole?: boolean): void;
+    error(message: string, scope: string, logToConsole?: boolean): void;
+}

package/dist/types/logger.js

@@ -0,0 +1 @@
+export {};

package/dist/types/modal.d.ts

@@ -0,0 +1,77 @@
+import { TextInputStyle, ModalSubmitInteraction } from 'discord.js';
+/**
+ * Represents a single input field within a Discord modal.
+ */
+export type ModalField = {
+    /**
+     * The label text shown above the input field.
+     */
+    name: string;
+    /**
+     * The type of input to display.
+     * Use {@link TextInputStyle.Short} for a single-line field
+     * or {@link TextInputStyle.Paragraph} for a multi-line field.
+     */
+    style: TextInputStyle;
+    /**
+     * Unique identifier for this field within the modal.
+     * Used to retrieve the value in the `onSubmit` handler.
+     */
+    customId: string;
+    /**
+     * Optional placeholder text shown when the field is empty.
+     */
+    placeholder?: string;
+    /**
+     * Whether this field is required to be filled out.
+     * Defaults to `true`.
+     */
+    required?: boolean;
+    /**
+     * Minimum number of characters the input must contain.
+     */
+    minLength?: number;
+    /**
+     * Maximum number of characters the input can contain.
+     */
+    maxLength?: number;
+    /**
+     * Pre-filled value shown in the input field when the modal opens.
+     */
+    value?: string;
+};
+/**
+ * Represents a Discord modal dialog configuration.
+ */
+export type Modal = {
+    /**
+     * The custom ID of the modal, used to match submissions.
+     *
+     * When using dynamic IDs (e.g., `edit-reminder:123`), the ModalManager
+     * will match based on the base ID before the colon.
+     */
+    id: string;
+    /**
+     * Indicates whether this modal is **ephemeral** — meaning it's tied to specific
+     * context or data from its creation (e.g., a user, reminder ID, or other state).
+     *
+     * When `true`, the modal is automatically removed from the registry after
+     * submission to prevent reuse or context leakage. This is typically used for
+     * one-shot modals whose handlers depend on creation-time data.
+     */
+    ephemeral: boolean;
+    /**
+     * The title displayed at the top of the modal window.
+     */
+    title: string;
+    /**
+     * The input fields displayed within the modal.
+     */
+    fields: ModalField[];
+    /**
+     * Handler function called when the modal is submitted.
+     * Provides the `ModalSubmitInteraction` to access input values
+     * and reply to the user.
+     */
+    onSubmit: (interaction: ModalSubmitInteraction) => Promise<any>;
+};

package/dist/types/modal.js

@@ -0,0 +1 @@
+export {};

package/dist/types/permission.d.ts

@@ -0,0 +1,2 @@
+import { PermissionFlagsBits } from 'discord.js';
+export type PermissionLevel = 'admin' | 'owner' | 'disabled' | 'user' | null | undefined | bigint | number | (keyof typeof PermissionFlagsBits)[];

package/dist/types/permission.js

@@ -0,0 +1 @@
+export {};