@julanzw/ttoolbox-discordjs-framework 1.0.1

package/dist/utils/PaginatedEmbed.class.d.ts

@@ -0,0 +1,25 @@
+import { ChatInputCommandInteraction } from 'discord.js';
+import { createButton } from './embeds.js';
+export type PaginatedEmbedOptions<T> = {
+    extraButtons?: ReturnType<typeof createButton>[];
+    timeout?: number;
+    onCustomButton?: (action: string, index: number, items: T[]) => Promise<{
+        handled: boolean;
+        newItems?: T[];
+        stopCollector?: boolean;
+    }>;
+};
+export declare class PaginatedEmbed<T> {
+    private interaction;
+    private buildEmbed;
+    private options?;
+    private index;
+    private items;
+    private collector?;
+    constructor(interaction: ChatInputCommandInteraction, items: T[], buildEmbed: (item: T, index: number, total: number) => any[], options?: PaginatedEmbedOptions<T> | undefined);
+    private buildButtons;
+    start(): Promise<void>;
+    stop(): void;
+    getCurrentIndex(): number;
+    getItems(): T[];
+}

package/dist/utils/PaginatedEmbed.class.js

@@ -0,0 +1,102 @@
+import { ComponentType, } from 'discord.js';
+import { InteractionError } from '../classes/InteractionError.class.js';
+import { createButtonsRow, createPaginationButtons, } from './embeds.js';
+import { safeReply } from './editAndReply.js';
+import { TIMES_MILISECONDS } from './miliseconds.js';
+export class PaginatedEmbed {
+    constructor(interaction, items, buildEmbed, options) {
+        this.interaction = interaction;
+        this.buildEmbed = buildEmbed;
+        this.options = options;
+        this.index = 0;
+        this.items = items;
+    }
+    buildButtons() {
+        const paginationButtons = createPaginationButtons(this.index, this.items.length);
+        const extraButtons = this.options?.extraButtons ?? [];
+        return [
+            createButtonsRow(extraButtons, {
+                buttons: paginationButtons,
+                location: 'embrace',
+            }),
+        ];
+    }
+    async start() {
+        await safeReply(this.interaction, '', false, this.buildEmbed(this.items[this.index], this.index, this.items.length), this.buildButtons());
+        const msg = await this.interaction.fetchReply();
+        this.collector = msg.createMessageComponentCollector({
+            componentType: ComponentType.Button,
+            time: this.options?.timeout ?? TIMES_MILISECONDS.MINUTE * 2,
+        });
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+        this.collector.on('collect', async (btnInteraction) => {
+            if (btnInteraction.user.id !== this.interaction.user.id) {
+                return await safeReply(btnInteraction, 'You cannot use this button.', true);
+            }
+            const action = btnInteraction.customId;
+            // Handle custom buttons first
+            if (this.options?.onCustomButton) {
+                const result = await this.options.onCustomButton(action, this.index, this.items);
+                if (result.handled) {
+                    if (result.newItems) {
+                        this.items = result.newItems;
+                        this.index = Math.min(this.index, this.items.length - 1);
+                        if (this.items.length === 0 || result.stopCollector) {
+                            this.stop();
+                            return;
+                        }
+                    }
+                    // Don't update for confirmation dialogs
+                    if (action !== 'delete') {
+                        await btnInteraction.update({
+                            embeds: this.buildEmbed(this.items[this.index], this.index, this.items.length),
+                            components: this.buildButtons(),
+                        });
+                    }
+                    return;
+                }
+            }
+            // Handle pagination
+            switch (action) {
+                case 'prev':
+                    this.index = Math.max(0, this.index - 1);
+                    break;
+                case 'next':
+                    this.index = Math.min(this.items.length - 1, this.index + 1);
+                    break;
+                default:
+                    return;
+            }
+            await btnInteraction.update({
+                embeds: this.buildEmbed(this.items[this.index], this.index, this.items.length),
+                components: this.buildButtons(),
+            });
+        });
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+        this.collector.on('end', async () => {
+            try {
+                await this.interaction.editReply({ components: [] });
+            }
+            catch (err) {
+                throw new InteractionError(
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+                `Failed to clear components: ${err.message}`, this.interaction.id, 'failed');
+            }
+        });
+    }
+    // Manually stop if needed
+    stop() {
+        if (this.collector) {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+            this.collector.stop();
+        }
+    }
+    // For custom logic
+    getCurrentIndex() {
+        return this.index;
+    }
+    // For custom logic
+    getItems() {
+        return this.items;
+    }
+}

package/dist/utils/TToolboxLogger.class.d.ts

@@ -0,0 +1,176 @@
+import { ILogger, LoggerOptions } from '../types/logger.js';
+/**
+ * Logger class for TToolbox framework with file and console logging capabilities.
+ *
+ * Provides timestamped logging with different severity levels and optional
+ * console output with color coding. Supports custom log levels and colors.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with defaults
+ * const logger = new TToolboxLogger();
+ * logger.info('Bot started', 'startup');
+ *
+ * // With custom log levels
+ * const logger = new TToolboxLogger({
+ *   customLevels: {
+ *     debug: '\x1b[35m' , // Magenta
+ *     success: color: '\x1b[32m', // Green
+ *   },
+ *   extendDefaultLevels: true
+ * });
+ *
+ * logger.log('Debug info', 'debug', 'system');
+ * logger.log('Operation succeeded', 'success', 'api', true);
+ * ```
+ */
+export declare class TToolboxLogger implements ILogger {
+    private logFilePath;
+    private levels;
+    private reset;
+    private static readonly DEFAULT_LEVELS;
+    /**
+     * Creates a new TToolboxLogger instance.
+     *
+     * @param optionsOrLogDir - Either a LoggerOptions object or a string path to the log directory
+     * @param logFileName - The name of the log file when using the string path signature (defaults to 'latest.log')
+     *
+     * @example
+     * ```typescript
+     * // Simple usage - defaults to ./logs/latest.log
+     * const logger = new TToolboxLogger();
+     *
+     * // Just custom directory
+     * const logger = new TToolboxLogger('./my-logs');
+     *
+     * // Custom directory and filename
+     * const logger = new TToolboxLogger('./logs', 'bot.log');
+     *
+     * // With options object
+     * const logger = new TToolboxLogger({
+     *   logDir: './logs',
+     *   logFileName: 'bot.log',
+     *   customLevels: {
+     *     debug: { color: '\x1b[35m' },
+     *   },
+     *   extendDefaultLevels: true
+     * });
+     * ```
+     */
+    constructor(optionsOrLogDir?: string | LoggerOptions, logFileName?: string);
+    /**
+     * Logs a message with timestamp, level, and scope.
+     *
+     * @param message - The message to log
+     * @param level - The severity level of the log (must match a configured level)
+     * @param scope - The scope or context of the log (e.g., 'database', 'api', 'command')
+     * @param logToConsole - Whether to also output to console with color coding (defaults to false)
+     *
+     * @throws {Error} If the specified level doesn't exist
+     *
+     * @example
+     * ```typescript
+     * logger.log('User joined', 'info', 'events');
+     * logger.log('Debug info', 'debug', 'system', true);
+     * logger.log('Critical error', 'error', 'database', true);
+     * ```
+     */
+    log(message: string, level: string, scope: string, logToConsole?: boolean): void;
+    /**
+     * Logs an info-level message.
+     *
+     * Convenience method for logging informational messages.
+     *
+     * @param message - The message to log
+     * @param scope - The scope or context of the log
+     * @param logToConsole - Whether to also output to console (defaults to false)
+     *
+     * @example
+     * ```typescript
+     * logger.info('Bot started successfully', 'startup', true);
+     * ```
+     */
+    info(message: string, scope: string, logToConsole?: boolean): void;
+    /**
+     * Logs a warning-level message.
+     *
+     * Convenience method for logging warning messages.
+     *
+     * @param message - The message to log
+     * @param scope - The scope or context of the log
+     * @param logToConsole - Whether to also output to console (defaults to false)
+     *
+     * @example
+     * ```typescript
+     * logger.warn('Rate limit approaching', 'api', true);
+     * ```
+     */
+    warn(message: string, scope: string, logToConsole?: boolean): void;
+    /**
+     * Logs an error-level message.
+     *
+     * Convenience method for logging error messages.
+     *
+     * @param message - The message to log
+     * @param scope - The scope or context of the log
+     * @param logToConsole - Whether to also output to console (defaults to true)
+     *
+     * @example
+     * ```typescript
+     * logger.error('Database connection failed', 'database', true);
+     * ```
+     */
+    error(message: string, scope: string, logToConsole?: boolean): void;
+    /**
+     * Gets all available log levels with their colors.
+     *
+     * @returns Record of log level names to their color
+     *
+     * @example
+     * ```typescript
+     * const levels = logger.getAvailableLevels();
+     * console.log(Object.keys(levels)); // ['info', 'warn', 'error', 'debug']
+     * ```
+     */
+    getAvailableLevels(): Record<string, string>;
+    /**
+     * Gets the path to the current log file.
+     *
+     * @returns The absolute path to the log file
+     *
+     * @example
+     * ```typescript
+     * console.log('Logging to:', logger.getLogFilePath());
+     * ```
+     */
+    getLogFilePath(): string;
+    /**
+     * Clears the current log file.
+     *
+     * Useful for rotating logs or starting fresh.
+     *
+     * @example
+     * ```typescript
+     * logger.clearLog();
+     * logger.info('Log cleared, starting fresh', 'system');
+     * ```
+     */
+    clearLog(): void;
+    /**
+     * Creates a new log file with a timestamp-based name and returns a new logger instance.
+     *
+     * Useful for log rotation - creates a new file while keeping the old one.
+     *
+     * @returns A new TToolboxLogger instance pointing to the new log file
+     *
+     * @example
+     * ```typescript
+     * // Rotate logs daily
+     * let logger = new TToolboxLogger('./logs');
+     *
+     * // Later, create a new log file
+     * logger = logger.rotate();
+     * ```
+     */
+    rotate(): TToolboxLogger;
+}

package/dist/utils/TToolboxLogger.class.js

@@ -0,0 +1,252 @@
+/* eslint-disable no-inline-comments */
+import path from 'path';
+import fs from 'fs';
+import { formatDateToYYYYMMDDHHMMSS } from './formatting.js';
+/**
+ * Logger class for TToolbox framework with file and console logging capabilities.
+ *
+ * Provides timestamped logging with different severity levels and optional
+ * console output with color coding. Supports custom log levels and colors.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with defaults
+ * const logger = new TToolboxLogger();
+ * logger.info('Bot started', 'startup');
+ *
+ * // With custom log levels
+ * const logger = new TToolboxLogger({
+ *   customLevels: {
+ *     debug: '\x1b[35m' , // Magenta
+ *     success: color: '\x1b[32m', // Green
+ *   },
+ *   extendDefaultLevels: true
+ * });
+ *
+ * logger.log('Debug info', 'debug', 'system');
+ * logger.log('Operation succeeded', 'success', 'api', true);
+ * ```
+ */
+export class TToolboxLogger {
+    /**
+     * Creates a new TToolboxLogger instance.
+     *
+     * @param optionsOrLogDir - Either a LoggerOptions object or a string path to the log directory
+     * @param logFileName - The name of the log file when using the string path signature (defaults to 'latest.log')
+     *
+     * @example
+     * ```typescript
+     * // Simple usage - defaults to ./logs/latest.log
+     * const logger = new TToolboxLogger();
+     *
+     * // Just custom directory
+     * const logger = new TToolboxLogger('./my-logs');
+     *
+     * // Custom directory and filename
+     * const logger = new TToolboxLogger('./logs', 'bot.log');
+     *
+     * // With options object
+     * const logger = new TToolboxLogger({
+     *   logDir: './logs',
+     *   logFileName: 'bot.log',
+     *   customLevels: {
+     *     debug: { color: '\x1b[35m' },
+     *   },
+     *   extendDefaultLevels: true
+     * });
+     * ```
+     */
+    constructor(optionsOrLogDir, logFileName = 'latest.log') {
+        this.reset = '\x1b[0m';
+        let options;
+        if (typeof optionsOrLogDir === 'string') {
+            // Basic signature: new TToolboxLogger('./logs', 'file.log')
+            options = {
+                logDir: optionsOrLogDir,
+                logFileName: logFileName,
+            };
+        }
+        else if (optionsOrLogDir) {
+            // Advanced signature: new TToolboxLogger({ logDir: './logs', ... })
+            options = optionsOrLogDir;
+        }
+        else {
+            // No arguments: new TToolboxLogger()
+            options = {};
+        }
+        const { logDir = './logs', logFileName: fileName = logFileName, customLevels = {}, extendDefaultLevels = true, } = options;
+        // Set up log levels
+        if (extendDefaultLevels) {
+            this.levels = { ...TToolboxLogger.DEFAULT_LEVELS, ...customLevels };
+        }
+        else {
+            this.levels =
+                Object.keys(customLevels).length > 0
+                    ? customLevels
+                    : TToolboxLogger.DEFAULT_LEVELS;
+        }
+        // Resolve log directory
+        const resolvedLogDir = path.isAbsolute(logDir)
+            ? logDir
+            : path.resolve(process.cwd(), logDir);
+        if (!fs.existsSync(resolvedLogDir)) {
+            fs.mkdirSync(resolvedLogDir, { recursive: true });
+        }
+        this.logFilePath = path.join(resolvedLogDir, fileName);
+    }
+    /**
+     * Logs a message with timestamp, level, and scope.
+     *
+     * @param message - The message to log
+     * @param level - The severity level of the log (must match a configured level)
+     * @param scope - The scope or context of the log (e.g., 'database', 'api', 'command')
+     * @param logToConsole - Whether to also output to console with color coding (defaults to false)
+     *
+     * @throws {Error} If the specified level doesn't exist
+     *
+     * @example
+     * ```typescript
+     * logger.log('User joined', 'info', 'events');
+     * logger.log('Debug info', 'debug', 'system', true);
+     * logger.log('Critical error', 'error', 'database', true);
+     * ```
+     */
+    log(message, level, scope, logToConsole = false) {
+        const color = this.levels[level];
+        if (!color) {
+            throw new Error(`Unknown log level: "${level}". Available levels: ${Object.keys(this.levels).join(', ')}`);
+        }
+        const logMessage = `[${formatDateToYYYYMMDDHHMMSS(new Date())}] [${level.toUpperCase()}] [${scope}] ${message}\n`;
+        // Write to file
+        fs.appendFileSync(this.logFilePath, logMessage, 'utf8');
+        // Optionally log to console with colors
+        if (logToConsole) {
+            console.log(`${color}${logMessage.trim()}${this.reset}`);
+        }
+    }
+    /**
+     * Logs an info-level message.
+     *
+     * Convenience method for logging informational messages.
+     *
+     * @param message - The message to log
+     * @param scope - The scope or context of the log
+     * @param logToConsole - Whether to also output to console (defaults to false)
+     *
+     * @example
+     * ```typescript
+     * logger.info('Bot started successfully', 'startup', true);
+     * ```
+     */
+    info(message, scope, logToConsole = false) {
+        this.log(message, 'info', scope, logToConsole);
+    }
+    /**
+     * Logs a warning-level message.
+     *
+     * Convenience method for logging warning messages.
+     *
+     * @param message - The message to log
+     * @param scope - The scope or context of the log
+     * @param logToConsole - Whether to also output to console (defaults to false)
+     *
+     * @example
+     * ```typescript
+     * logger.warn('Rate limit approaching', 'api', true);
+     * ```
+     */
+    warn(message, scope, logToConsole = false) {
+        this.log(message, 'warn', scope, logToConsole);
+    }
+    /**
+     * Logs an error-level message.
+     *
+     * Convenience method for logging error messages.
+     *
+     * @param message - The message to log
+     * @param scope - The scope or context of the log
+     * @param logToConsole - Whether to also output to console (defaults to true)
+     *
+     * @example
+     * ```typescript
+     * logger.error('Database connection failed', 'database', true);
+     * ```
+     */
+    error(message, scope, logToConsole = true) {
+        this.log(message, 'error', scope, logToConsole);
+    }
+    /**
+     * Gets all available log levels with their colors.
+     *
+     * @returns Record of log level names to their color
+     *
+     * @example
+     * ```typescript
+     * const levels = logger.getAvailableLevels();
+     * console.log(Object.keys(levels)); // ['info', 'warn', 'error', 'debug']
+     * ```
+     */
+    getAvailableLevels() {
+        return this.levels;
+    }
+    /**
+     * Gets the path to the current log file.
+     *
+     * @returns The absolute path to the log file
+     *
+     * @example
+     * ```typescript
+     * console.log('Logging to:', logger.getLogFilePath());
+     * ```
+     */
+    getLogFilePath() {
+        return this.logFilePath;
+    }
+    /**
+     * Clears the current log file.
+     *
+     * Useful for rotating logs or starting fresh.
+     *
+     * @example
+     * ```typescript
+     * logger.clearLog();
+     * logger.info('Log cleared, starting fresh', 'system');
+     * ```
+     */
+    clearLog() {
+        fs.writeFileSync(this.logFilePath, '', 'utf8');
+    }
+    /**
+     * Creates a new log file with a timestamp-based name and returns a new logger instance.
+     *
+     * Useful for log rotation - creates a new file while keeping the old one.
+     *
+     * @returns A new TToolboxLogger instance pointing to the new log file
+     *
+     * @example
+     * ```typescript
+     * // Rotate logs daily
+     * let logger = new TToolboxLogger('./logs');
+     *
+     * // Later, create a new log file
+     * logger = logger.rotate();
+     * ```
+     */
+    rotate() {
+        const timestamp = formatDateToYYYYMMDDHHMMSS(new Date());
+        const logDir = path.dirname(this.logFilePath);
+        const newFileName = `log-${timestamp}.log`;
+        return new TToolboxLogger({
+            logDir,
+            logFileName: newFileName,
+            customLevels: this.levels,
+            extendDefaultLevels: false,
+        });
+    }
+}
+// Default log levels
+TToolboxLogger.DEFAULT_LEVELS = {
+    info: '\x1b[36m', // Cyan
+    warn: '\x1b[33m', //  Yellow
+    error: '\x1b[31m', // Red
+};

package/dist/utils/cooldown.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Checks whether a user can run a given command considering its cooldown.
+ *
+ * If the command has no cooldown, it is always allowed.
+ * If the user is on cooldown, returns how long they still need to wait.
+ *
+ * This function also automatically cleans up expired cooldowns.
+ *
+ * @param command The command being checked.
+ * @param userId The ID of the user executing the command.
+ * @returns A CooldownResult with `allowed` and optional `remaining` time.
+ */
+export declare function checkCooldown(commandName: string, commandCooldown: number | undefined, userId: string): number;

package/dist/utils/cooldown.js

@@ -0,0 +1,43 @@
+/**
+ * A tracker with the command name as key and a map as value.
+ *
+ * Within the value map the userId is used as the key and the timestamp (in ms)
+ * when the command can be used again as the value.
+ *
+ * So `Map<commandName, Map<userId, canBeUsedAgainAt>>`.
+ */
+const tracker = new Map();
+/**
+ * Checks whether a user can run a given command considering its cooldown.
+ *
+ * If the command has no cooldown, it is always allowed.
+ * If the user is on cooldown, returns how long they still need to wait.
+ *
+ * This function also automatically cleans up expired cooldowns.
+ *
+ * @param command The command being checked.
+ * @param userId The ID of the user executing the command.
+ * @returns A CooldownResult with `allowed` and optional `remaining` time.
+ */
+export function checkCooldown(commandName, commandCooldown, userId) {
+    if (!commandCooldown)
+        return 0;
+    const now = Date.now();
+    let cooldownMap = tracker.get(commandName);
+    if (!cooldownMap) {
+        cooldownMap = new Map();
+        tracker.set(commandName, cooldownMap);
+    }
+    // Clean up expired entries
+    for (const [id, expiry] of cooldownMap) {
+        if (expiry <= now) {
+            cooldownMap.delete(id);
+        }
+    }
+    const canBeUsedAgainAt = cooldownMap.get(userId);
+    if (canBeUsedAgainAt && now < canBeUsedAgainAt) {
+        return canBeUsedAgainAt - now;
+    }
+    cooldownMap.set(userId, now + commandCooldown);
+    return 0;
+}

package/dist/utils/editAndReply.d.ts

@@ -0,0 +1,37 @@
+import Stream from 'stream';
+import { ActionRowBuilder, APIAttachment, Attachment, AttachmentBuilder, AttachmentPayload, BufferResolvable, ButtonInteraction, ChannelSelectMenuInteraction, ChatInputCommandInteraction, EmbedBuilder, JSONEncodable, Message, ModalSubmitInteraction, StringSelectMenuInteraction } from 'discord.js';
+/**
+ * Safely replies to an interaction, handling deferred/replied states.
+ *
+ * @param interaction - The interaction to reply to
+ * @param content - The message content
+ * @param ephemeral - Whether the reply should be ephemeral
+ * @param embeds - Optional embeds to include
+ * @param components - Optional components to include
+ * @param files - Optional files to attach
+ * @returns The message that was sent
+ * @throws {InteractionError} If the interaction is too old or fails
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await safeReply(interaction, 'Hello!', true);
+ * } catch (err) {
+ *   if (err instanceof InteractionError && err.reason === 'expired') {
+ *     this.logger?.warn('Interaction expired', 'command');
+ *   }
+ * }
+ * ```
+ */
+export declare function safeReply(interaction: ChatInputCommandInteraction | ButtonInteraction | ModalSubmitInteraction | ChannelSelectMenuInteraction | StringSelectMenuInteraction, content: string, ephemeral?: boolean, embeds?: EmbedBuilder[], components?: ActionRowBuilder<any>[], files?: (BufferResolvable | Stream | JSONEncodable<APIAttachment> | Attachment | AttachmentBuilder | AttachmentPayload)[]): Promise<Message>;
+/**
+ * Safely edits an interaction reply.
+ *
+ * @param interaction - The interaction to edit
+ * @param content - The new message content
+ * @param embeds - Optional embeds to include
+ * @param components - Optional components to include
+ * @returns The edited message
+ * @throws {InteractionError} If the interaction is too old or fails
+ */
+export declare function safeEdit(interaction: ChatInputCommandInteraction | ButtonInteraction | ModalSubmitInteraction | ChannelSelectMenuInteraction | StringSelectMenuInteraction, content: string, embeds?: EmbedBuilder[], components?: ActionRowBuilder<any>[]): Promise<Message>;