highrise.bot 1.0.2 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "highrise.bot",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Unofficial JavaScript SDK for the Highrise platform. Feature-complete WebSocket client with TypeScript support, built for production environments.",
   "keywords": [
     "highrise.bot",

package/src/classes/Actions/Utils.js

@@ -1,7 +1,8 @@
 const RoleManager = require("highrise.bot/src/classes/Managers/RoleManager");
 const CooldownManager = require("highrise.bot/src/classes/Managers/CooldownManager");
 const DanceFloor = require("highrise.bot/src/classes/Managers/DanceFloorManagers");
-const { Logger } = require("highrise.bot/src/classes/Managers/Helpers/LoggerManager")
+const { Logger } = require("highrise.bot/src/classes/Managers/Helpers/LoggerManager");
+const CommandHandler = require("highrise.bot/src/classes/Handlers/CommandHandler");
 
 class Utils {
     constructor(bot, options) {
@@ -14,7 +15,7 @@ class Utils {
             dataDir: './Json/permissions',
             filename: 'roles.json',
             customRoles: options.customRoles || [],
-            
+
         });
     }
 
@@ -72,6 +73,10 @@ class Utils {
         return result;
     }
 
+    command(relativeDir, options = {}) {
+        return new CommandHandler(this.bot, relativeDir, options);
+    };
+
 }
 
 module.exports = Utils

package/src/classes/Handlers/CommandHandler.js

@@ -0,0 +1,396 @@
+const fsp = require('fs').promises
+const path = require('path')
+
+class CommandHandler {
+    constructor(bot, relativeDir, options = {}) {
+        this.options = {
+            autoLoad: options.autoLoad || true
+        }
+
+        this.bot = bot
+        this.logger = bot.utils.logger
+        this.dir = path.resolve(relativeDir);
+
+        this.commands = new Map() // name -> module
+        this.aliases = new Map() // alias -> commandName
+
+        this.preMiddlewares = new Map()
+        this.postMiddlewares = new Map()
+
+        this.errorHeader = `CommandHandler (${this.dir})`
+        this.handlerError = (...args) => this.logger.error(this.errorHeader, args)
+
+        if (this.options.autoLoad) this._initialize()
+    }
+
+    async _initialize() {
+        const files = await this._getFiles()
+        const modules = await this._loadModules(files)
+        const result = await this._registerCommands(modules)
+        this.logger.success(this.errorHeader, `initializing Commands | Success: ${result.success} - Failed: ${result.failed}`)
+    }
+
+    async _getFiles() {
+        try {
+            const files = await fsp.readdir(this.dir, {
+                recursive: true,
+                withFileTypes: true
+            });
+
+            return files
+                .filter(file => file.name.endsWith('.js'))
+        } catch (error) {
+            return this._handleGetFilesError(this.dir, error);
+        }
+    }
+
+    _handleGetFilesError(dir, error) {
+        if (error.code === 'ENOENT') {
+            this.logger.warn(`CommandHandler`, `Directory does not exist: ${dir}\n`);
+            return [];
+        } else if (error.code === 'EACCES') {
+            this.logger.warn(`CommandHandler`, `Access failed to directory: ${dir}\n`);
+            return [];
+        } else {
+            this.logger.error(`CommandHandler`, `Error reading directory: ${dir}`, error.message);
+            return []
+        }
+    }
+
+    async _loadModules(files) {
+        let modules = []
+
+        for (const file of files) {
+            const modulePath = path.join(file.parentPath, file.name);
+
+            if (require.cache[modulePath]) {
+                delete require.cache[modulePath];
+            }
+
+            try {
+                let module = require(modulePath)
+                Object.assign(module, {
+                    filePath: modulePath
+                })
+
+                modules.push(module)
+            } catch (error) {
+                const causePart = this._dissectSyntaxErrorStack(error)
+                const message = this._buildSyntaxErrorMessage(file, causePart)
+                this.logger.error(`CommandHandler - Loading Modules`, message)
+            }
+        }
+
+        return modules
+    }
+
+    _dissectSyntaxErrorStack(error) {
+        const stack = error.stack
+        const parts = stack.split('\n')
+        const causePart = parts.slice(0, 3).join('\n')
+        return causePart
+    }
+
+    _buildSyntaxErrorMessage(fileName, causePart) {
+        let message = `Error: Caught a syntax error in ${fileName}:\n`
+        message += `Cause:\n    ${causePart}`
+        return message
+    }
+
+    _buildValidationWarning(module, warns) {
+        let warningMessage = `Error Registering command "${module.filePath}":\n`
+        for (const warn of warns) {
+            warningMessage += warn.concat('\n')
+        }
+
+        this.logger.warn(`CommandHandler - Module Register`, warningMessage.trim())
+    }
+
+    _validateModule(module) {
+        let warn = []
+
+        if (typeof module !== 'object' || module === null) {
+            warn.push(`module must be an object`)
+            return warn;
+        }
+
+        if (('name' in module)) {
+            if (typeof module.name !== 'string' || module.name.length === 0) {
+                warn.push(`module.name must be a non-empty string`)
+            }
+        } else {
+            warn.push(`module.name is required`)
+        }
+
+        if ('description' in module) {
+            if (typeof module.description !== 'string' || module.description.length === 0) {
+                warn.push(`module.description must be a non-empty string`)
+            }
+        }
+
+        if (('roles' in module)) {
+            if (!Array.isArray(module.roles)) {
+                warn.push(`module.roles must be an array`)
+            } else if (!module.roles.every(role => typeof role === 'string' && role.length !== 0)) {
+                warn.push(`module.roles elements must be only non-empty strings`)
+            }
+        }
+
+        if (('execute' in module)) {
+            if (typeof module.execute !== 'function') {
+                warn.push(`module.execute must be a function`)
+            }
+        } else {
+            warn.push(`module.execute is required`)
+        }
+
+        if ('aliases' in module) {
+            if (!Array.isArray(module.aliases)) {
+                warn.push(`module.aliases must be an array`)
+            } else if (!module.aliases.every(alias => typeof alias === 'string' && alias.length !== 0)) {
+                warn.push(`module.aliases elements must be only non-empty strings`)
+            }
+        }
+
+        return warn;
+    }
+
+    _registerAliases(commandName, aliases) {
+        let success = 0
+        let failed = 0
+
+        for (const alias of aliases) {
+            const status = this._registerAlias(commandName, alias)
+            status ? success++ : failed++
+        }
+
+        return { success, failed }
+    }
+
+    _validateAlias(alias) {
+        if (this.aliases.has(alias)) {
+            const existingCommand = this.aliases.get(alias)
+            this.handlerError(`alias "${alias}" is already set to command "${existingCommand}"`)
+            return false
+        }
+
+        if (this.commands.has(alias)) {
+            this.handlerError(`alias "${alias}" conflicts with existing command name`)
+            return false
+        }
+
+        return true
+    }
+
+    _registerAlias(commandName, alias) {
+        const isValid = this._validateAlias(alias)
+        if (!isValid) return false
+
+        this.aliases.set(alias, commandName)
+        return true
+    }
+
+    async _registerCommands(modules) {
+        let success = 0
+        let failed = 0
+
+        for (const module of modules) {
+            const status = await this.registerCommand(module)
+            status ? success++ : failed++
+        }
+
+        return { success, failed }
+    }
+
+    async _unRegisterCommands(modules) {
+        let success = 0
+        let failed = 0
+
+        for (const module of modules) {
+            const status = this.unRegisterCommand(module.name)
+            status ? success++ : failed++
+        }
+
+        return { success, failed }
+    }
+
+    _getPreMiddlewares() {
+        return this.preMiddlewares.entries()
+    }
+
+    _getPostMiddlewares() {
+        return this.postMiddlewares.entries()
+    }
+
+    async _middlewareErrorHandler(middleware, bot, context, result = null) {
+        try {
+            const output = await middleware.fn(bot, context, result);
+            return output !== false;
+        } catch (error) {
+            this.logger.error(`${middleware.type} Middleware - ${middleware.name}`, error.message)
+            return false
+        }
+    }
+
+    async _runPreMiddleware(bot, context) {
+        const pres = this._getPreMiddlewares()
+        for (const [_, pre] of pres) {
+            const proceed = await this._middlewareErrorHandler(pre, bot, context)
+            if (!proceed) return false
+        }
+        return true;
+    }
+
+    async _runPostMiddleware(bot, context, result) {
+        const posts = this._getPostMiddlewares()
+        for (const [_, post] of posts) {
+            await this._middlewareErrorHandler(post, bot, context, result)
+        }
+    }
+
+    _validateMiddleware(name, fn) {
+        if (!name || typeof name !== 'string') {
+            this.handlerError(`name must be a non-empty string`)
+            return false
+        }
+
+        if (!fn || typeof fn !== 'function') {
+            this.handlerError(`fn must be a function`)
+            return false
+        }
+
+        return true
+    }
+
+    _validateContext(context) {
+        if (!('user' in context)) {
+            this.handlerError(`context.user must be provided.`)
+            return false
+        }
+
+        if (typeof context.user !== 'object') {
+            this.handlerError(`context.user must be an object.`)
+            return false
+        }
+
+        if (!('id' in context.user)) {
+            this.handlerError(`context.user.id must be provided.`)
+            return false
+        }
+
+        if (typeof context.user.id !== 'string' || context.user.id.trim() === '') {
+            this.handlerError(`context.user.id must be a non-empty string.`)
+            return false
+        }
+
+        if (!('username' in context.user)) {
+            this.handlerError(`context.user.username must be provided.`)
+            return false
+        }
+
+        if (typeof context.user.username !== 'string' || context.user.username.trim() === '') {
+            this.handlerError(`context.user.username must be a non-empty string.`)
+            return false
+        }
+
+        return true
+    }
+
+    _roleCheck(bot, user, module) {
+        const commandRoles = module.roles
+        if (!commandRoles) return true
+
+        return commandRoles.some(requiredRole => {
+            const hasRequiredRole = bot.utils.roles.hasRole(requiredRole, user.id)
+            return hasRequiredRole
+        })
+    }
+
+    async _executeCommand(user, module, context) {
+        const eligible = this._roleCheck(this.bot, user, module);
+        if (eligible) {
+            try {
+                const proceed = await this._runPreMiddleware(this.bot, context)
+                if (!proceed) return
+
+                const result = await module.execute(this.bot, context);
+                await this._runPostMiddleware(this.bot, context, result ?? { success: true });
+            } catch (error) {
+                this.logger.error(`Command ${module.filePath}`, error.message)
+            }
+        }
+    }
+
+    preMiddleware(name, fn) {
+        const status = this._validateMiddleware(name, fn)
+
+        if (!status) return
+
+        if (this.preMiddlewares.has(name)) {
+            this.logger.warn(`Pre middleware "${name}" already exists and will be overwritten`)
+        }
+
+        this.preMiddlewares.set(name, { name, fn, type: 'Pre' })
+    }
+
+    postMiddleware(name, fn) {
+        const status = this._validateMiddleware(name, fn)
+
+        if (!status) return
+
+        if (this.postMiddlewares.has(name)) {
+            this.logger.warn(`Post middleware "${name}" already exists and will be overwritten`)
+        }
+
+        this.postMiddlewares.set(name, { name, fn, type: 'Post' })
+    }
+
+    async registerCommand(module) {
+        const warns = this._validateModule(module)
+        if (warns.length > 0) {
+            this._buildValidationWarning(module, warns)
+            return false
+        }
+
+        const { name, aliases } = module
+
+        if (this.commands.has(name)) {
+            return false
+        }
+
+        if (aliases) this._registerAliases(name, aliases)
+
+        this.commands.set(name, module)
+        return true
+    }
+
+    async unRegisterCommand(commandName) {
+        if (!this.commands.has(commandName)) {
+            return false
+        }
+
+        const module = this.commands.get(commandName)
+
+        if (module.aliases) {
+            module.aliases.forEach(alias => this.aliases.delete(alias))
+        }
+
+        return this.commands.delete(commandName)
+    }
+
+
+    async handle(commandName, context = {}) {
+        if (!this._validateContext(context)) {
+            return;
+        }
+
+        const module = this.commands.get(commandName) ||
+            this.commands.get(this.aliases.get(commandName));
+
+        if (!module) return;
+
+        await this._executeCommand(context.user, module, context);
+    }
+}
+
+module.exports = CommandHandler

package/typings/index.d.ts

@@ -153,8 +153,76 @@ type TipFilter = (sender: Sender, receiver: Receiver, currency: Currency) => boo
  */
 type MovementFilter = (user: User, position: Position | null, anchor: AnchorPosition | null) => boolean;
 
+/**
+ * Function type for middleware that executes BEFORE command execution
+ * 
+ * Use cases:
+ * - Authentication/authorization checks (return false to deny access)
+ * - Input validation and sanitization
+ * - Rate limiting and cooldown enforcement
+ * - Logging access attempts
+ * - Setting up command prerequisites
+ * 
+ * Return values:
+ * - `true` or `undefined`: Command continues to execute normally
+ * - `false`: Command execution is halted immediately
+ * - Thrown errors: Caught by middleware handler, command execution halted
+ * 
+ * @param bot - Highrise bot instance for API interactions
+ * @param context - Command execution context containing user data and parameters
+ * @returns Boolean indicating whether to proceed with command execution
+ * 
+ * @example
+ * // Admin-only command protection
+ * preMiddleware('admin-check', async (bot, context) => {
+ *   const result = await bot.room.privilege.isModerator(context.user.id);
+ *   if (!result.success || !result.isModerator) {
+ *     await bot.whisper.send(context.user.id, 'Admin access required');
+ *     return false; // Block command execution
+ *   }
+ *   return true; // Allow command to run
+ * })
+ */
+type preMiddlewareFunction = (bot: Highrise, context: CommandContext) => boolean | void;
 
-interface User {
+/**
+ * Function type for middleware that executes AFTER command execution
+ * 
+ * Use cases:
+ * - Processing command results and responses
+ * - Logging successful command outcomes
+ * - Analytics and metrics collection
+ * - Cleanup operations
+ * - Audit trail maintenance
+ * - Error handling for command results
+ * 
+ * Return values:
+ * - Any value (`true`, `false`, `undefined`): No impact on execution flow
+ *   (post-middleware always runs after command completes)
+ * - Thrown errors: Caught by middleware handler, doesn't affect original command result
+ * 
+ * @param bot - Highrise bot instance for API interactions
+ * @param context - Command execution context containing user data and parameters
+ * @param result - Output returned by the executed command (may be undefined)
+ * @returns (Optional) No functional impact on execution flow
+ * 
+ * @example
+ * // Command usage analytics
+ * postMiddleware('analytics', async (bot, context, result) => {
+ *   // Log successful commands to channel
+ *   if (result?.success) {
+ *     await bot.channel.send([
+ *       'command-execution', 
+ *       context.commandName
+ *     ], JSON.stringify({
+ *       userId: context.user.id,
+ *       command: context.commandName,
+ *       timestamp: Date.now()
+ *     }));
+ *   }
+ * })
+ */
+type postMiddlewareFunction = (bot: Highrise, context: CommandContext, result?: any) => boolean | void;interface User {
     id: string;
     username: string;
 }
@@ -756,6 +824,34 @@ interface CooldownManagerStats {
     memoryUsage: CooldownMemoryUsage;
 }
 
+/**
+ * Context passed to command handlers containing user and additional data
+ */
+interface CommandContext {
+    user: User; // Using SDK's User type
+    args?: string[];
+    message?: string;
+    [key: string]: any;
+}
+
+/**
+ * Command module definition
+ */
+interface CommandModule {
+    /** Unique command name */
+    name: string;
+    /** Optional command description */
+    description?: string;
+    /** Required roles for command access */
+    roles?: string[];
+    /** Command execution function */
+    execute: (bot: Highrise, context: CommandContext) => Promise<any>;
+    /** Alternative names for the command */
+    aliases?: string[];
+    /** Additional properties */
+    [key: string]: any;
+}
+
 interface Job {
     id: string;
     interval: number;
@@ -4511,7 +4607,150 @@ declare class Logger {
     debug(method: string, message: string, data?: any): void;
 }
 
+
+
+/**
+ * Handles bot commands with support for modules, aliases, and middleware
+ */
+declare class CommandHandler {
+    /**
+     * Creates a new command handler
+     * @param bot - Highrise Bot instance
+     * @param relativeDir - Directory containing command modules
+     * @param options - Configuration options
+     */
+    constructor(
+        bot: Highrise,
+        relativeDir: string,
+        options?: {
+            /** Auto-load command modules on initialization (default: true) */
+            autoLoad?: boolean;
+        }
+    );
+
+    /**
+     * Handles a command execution
+     * @param commandName - Name or alias of the command to execute
+     * @param context - Execution context with user information
+     * @example
+     * const [command, ...args] = message.trim().split(/\s+/);
+     * let context = {
+     *   args: args,
+     *   user
+     * }
+     * 
+     * const roomCommand = bot.utils.command(`./src/commands/`)
+     *
+     * roomCommand.handle(command, context)
+     */
+    handle(commandName: string, context?: CommandContext): Promise<void>;
+
+    /**
+     * Registers middleware to run before command execution
+     * 
+     * Use cases:
+     * - Authentication/authorization checks (return false to deny access)
+     * - Input validation and sanitization
+     * - Rate limiting and cooldown enforcement
+     * - Logging access attempts
+     * - Setting up command prerequisites
+     * 
+     * Return values:
+     * - `true` or `undefined`: Command continues to execute normally
+     * - `false`: Command execution is halted immediately
+     * - Thrown errors: Caught by middleware handler, command execution halted
+     * 
+     * @param name - Middleware identifier for reference and debugging
+     * @param fn - Middleware function that receives bot instance and context
+     * @example
+     * const roomCommand = bot.utils.command(`./src/commands`)
+     * 
+     * roomCommand.preMiddleware('auth', async (bot, context) => {
+     *   if (!context.user.isAdmin) {
+     *     return false; // Prevent command execution
+     *   }
+     *   return true;
+     * });
+     */
+    preMiddleware(name: string, fn: preMiddlewareFunction): void;
+
+    /**
+     * Registers middleware to run after command execution
+     * 
+     * Use cases:
+     * - Processing command results and responses
+     * - Logging successful command outcomes
+     * - Analytics and metrics collection
+     * - Cleanup operations
+     * - Audit trail maintenance
+     * - Error handling for command results
+     * 
+     * Return values:
+     * - Any value (`true`, `false`, `undefined`): No impact on execution flow
+     *   (post-middleware always runs after command completes)
+     * - Thrown errors: Caught by middleware handler, doesn't affect original command result
+     * 
+     * @param name - Middleware identifier for reference and debugging
+     * @param fn - Middleware function that processes bot, context, and command result
+     *             The result parameter contains the output returned by the executed command
+     * @example
+     * const roomCommand = bot.utils.command(`./src/commands`)
+     * 
+     * roomCommand.postMiddleware('log', async (bot, context, result) => {
+     *   console.log(`Command executed: ${result?.success}`);
+     * });
+     */
+    postMiddleware(name: string, fn: postMiddlewareFunction): void;
+
+    /**
+     * Registers a command module
+     * @param module - Command configuration
+     * @returns Success status
+     * @example
+     * const success = handler.register({
+     *   name: 'ping',
+     *   description: 'Responds with pong',
+     *   execute: async (bot, ctx) => {
+     *     return { message: 'pong' };
+     *   }
+     * });
+     */
+    register(module: CommandModule): boolean;
+
+    /**
+     * Unregisters a command by name
+     * @param commandName - Name of command to remove
+     * @returns Success status
+     * @example
+     * const success = handler.unregister('ping');
+     */
+    unregister(commandName: string): boolean;
+}
+
+/**
+ * Function type for creating CommandHandler instances
+ */
+type CommandHandlerFactory = (
+    relativeDir: string,
+    options?: {
+        /** Auto-load command modules on initialization (default: true) */
+        autoLoad?: boolean;
+    }
+) => CommandHandler;
+
 declare class BotUtils {
+    /**
+     * Factory function to create CommandHandler instances
+     * @param relativeDir - Directory containing command modules
+     * @param options - Configuration options
+     * @returns New CommandHandler instance
+     * @example
+     * const command = bot.utils.command('./src/commands/room');
+     * await command.handle('help', { user: { id: '123', username: 'john' } });
+     */
+    command: CommandHandlerFactory;
+
+    // ... other properties remain the same ...
     /**
      * Logger instance for structured, color-coded logging throughout the application
      * Provides different log levels (SUCCESS, ERROR, WARN, INFO, DEBUG) with timestamps and method tracking