highrise.bot 1.0.3 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "highrise.bot",
-  "version": "1.0.3",
+  "version": "1.1.1",
   "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/Awaiter.js

@@ -1,200 +1,88 @@
 class AwaitClass {
     constructor(ws) {
-        if (!ws) {
-            throw new Error('ws instance is required');
-        }
+        if (!ws) throw new Error('ws instance is required');
         this.ws = ws;
-        this._pendingAwaiters = new Map();
+        this._pendingAwaiters = {
+            chat: new Map(),
+            whisper: new Map(),
+            direct: new Map(),
+            tip: new Map(),
+            movement: new Map()
+        };
     }
 
     chat(filter = () => true, timeout = 30000, maxToCollect = 1, uniqueUsers = false) {
-        if (!this._validateParameters('chat', filter, timeout, maxToCollect)) {
-            return Promise.resolve([]);
-        }
-
         return this._createAwaiter('chat', filter, timeout, maxToCollect, uniqueUsers);
     }
 
     whisper(filter = () => true, timeout = 30000, maxToCollect = 1, uniqueUsers = false) {
-        if (!this._validateParameters('whisper', filter, timeout, maxToCollect)) {
-            return Promise.resolve([]);
-        }
-        
         return this._createAwaiter('whisper', filter, timeout, maxToCollect, uniqueUsers);
     }
 
     direct(filter = () => true, timeout = 30000, maxToCollect = 1, uniqueUsers = false) {
-        if (!this._validateParameters('direct', filter, timeout, maxToCollect)) {
-            return Promise.resolve([]);
-        }
         return this._createAwaiter('direct', filter, timeout, maxToCollect, uniqueUsers);
     }
 
     tip(filter = () => true, timeout = 30000, maxToCollect = 1, uniqueUsers = false) {
-        if (!this._validateParameters('tip', filter, timeout, maxToCollect)) {
-            return Promise.resolve([]);
-        }
         return this._createAwaiter('tip', filter, timeout, maxToCollect, uniqueUsers);
     }
 
     movement(filter = () => true, timeout = 30000, maxToCollect = 1, uniqueUsers = false) {
-        if (!this._validateParameters('movement', filter, timeout, maxToCollect)) {
-            return Promise.resolve([]);
-        }
         return this._createAwaiter('movement', filter, timeout, maxToCollect, uniqueUsers);
     }
 
-    _validateParameters(method, filter, timeout, maxToCollect) {
-        try {
-            if (typeof filter !== 'function') {
-                throw new TypeError(`Filter must be a function`);
-            }
-
-            if (typeof timeout !== 'number') {
-                throw new TypeError(`Timeout must be a number`);
-            }
-
-            if (timeout < 0) {
-                throw new RangeError(`Timeout cannot be negative`);
-            }
-
-            if (typeof maxToCollect !== 'number') {
-                throw new TypeError(`maxToCollect must be a number`);
-            }
-
-            if (!Number.isInteger(maxToCollect)) {
-                throw new TypeError(`maxToCollect must be an integer`);
-            }
-
-            if (maxToCollect < 1) {
-                throw new RangeError(`maxToCollect must be at least 1`);
-            }
-            
-            if (maxToCollect > 1000) {
-                throw new RangeError(`maxToCollect cannot exceed 1000`);
-            }
-
-            if (!this.ws.isConnected || !this.ws.isConnected()) {
-                throw new Error(`WebSocket is not connected to Highrise`);
-            }
-
-            return true;
-
-        } catch (error) {
-            if (error instanceof TypeError) {
-                this.ws._logger.error(`await.${method}`, `TypeError: ${error.message}`, { timeout, maxToCollect }, error);
-            } else if (error instanceof RangeError) {
-                this.ws._logger.error(`await.${method}`, `RangeError: ${error.message}`, { timeout, maxToCollect }, error);
-            } else {
-                this.ws._logger.error(`await.${method}`, error.message, { timeout, maxToCollect }, error);
-            }
-            return false;
+    _createAwaiter(eventType, filter, timeout, maxToCollect, uniqueUsers) {
+        if (typeof filter !== 'function' || typeof timeout !== 'number' || timeout < 0 || 
+            !Number.isInteger(maxToCollect) || maxToCollect < 1 || maxToCollect > 1000) {
+            return Promise.resolve([]);
         }
-    }
 
-    _createAwaiter(eventType, filter, timeout, maxToCollect, uniqueUsers = false) {
-        return new Promise((resolve, reject) => {
+        return new Promise((resolve) => {
             const awaiterId = Symbol('awaiter');
             const collected = [];
-            const seenUsers = new Set();
-            let timeoutId;
+            const seenUsers = uniqueUsers ? new Set() : null;
 
             const cleanup = () => {
                 clearTimeout(timeoutId);
-                this._pendingAwaiters.delete(awaiterId);
+                this._pendingAwaiters[eventType].delete(awaiterId);
             };
 
             const awaiter = {
-                eventType,
                 filter,
                 maxToCollect,
                 collected,
-                uniqueUsers,
                 seenUsers,
                 resolve: (results) => {
                     cleanup();
                     resolve(results);
-                },
-                reject: (error) => {
-                    cleanup();
-                    reject(error);
                 }
             };
 
-            this._pendingAwaiters.set(awaiterId, awaiter);
+            this._pendingAwaiters[eventType].set(awaiterId, awaiter);
 
-            if (timeout > 0) {
-                timeoutId = setTimeout(() => {
-                    awaiter.resolve(collected);
-                }, timeout);
-            }
+            const timeoutId = timeout > 0 ? setTimeout(() => awaiter.resolve(collected), timeout) : null;
         });
     }
 
     _processEvent(eventType, ...eventArgs) {
-        for (const [awaiterId, awaiter] of this._pendingAwaiters) {
-            if (awaiter.eventType === eventType) {
-                try {
-                    this._validateEventArguments(eventType, eventArgs);
+        const awaiters = this._pendingAwaiters[eventType];
+        if (!awaiters) return;
 
-                    if (awaiter.uniqueUsers && eventArgs[0]?.id) {
-                        if (awaiter.seenUsers.has(eventArgs[0].id)) {
-                            continue;
-                        }
-                        awaiter.seenUsers.add(eventArgs[0].id);
-                    }
-
-                    if (awaiter.filter(...eventArgs)) {
-                        awaiter.collected.push(eventArgs);
+        for (const awaiter of awaiters.values()) {
+            try {
+                if (awaiter.seenUsers && eventArgs[0]?.id) {
+                    if (awaiter.seenUsers.has(eventArgs[0].id)) continue;
+                    awaiter.seenUsers.add(eventArgs[0].id);
+                }
 
-                        if (awaiter.collected.length >= awaiter.maxToCollect) {
-                            awaiter.resolve(awaiter.collected);
-                        }
+                if (awaiter.filter(...eventArgs)) {
+                    awaiter.collected.push(eventArgs);
+                    if (awaiter.collected.length >= awaiter.maxToCollect) {
+                        awaiter.resolve(awaiter.collected);
                     }
-                } catch (error) {
-                    this.ws._logger.error(`await.${eventType}`, `Filter error: ${error.message}`)
                 }
-            }
-        }
-    }
-
-    _validateEventArguments(eventType, eventArgs) {
-        const validators = {
-            chat: (args) => {
-                if (args.length !== 2) throw new TypeError('Chat event requires 2 arguments (user, message)');
-                if (!args[0] || typeof args[0].id !== 'string') throw new TypeError('Invalid user object in chat event');
-                if (typeof args[1] !== 'string') throw new TypeError('Invalid message in chat event');
-            },
-            whisper: (args) => {
-                if (args.length !== 2) throw new TypeError('Whisper event requires 2 arguments (user, message)');
-                if (!args[0] || typeof args[0].id !== 'string') throw new TypeError('Invalid user object in whisper event');
-                if (typeof args[1] !== 'string') throw new TypeError('Invalid message in whisper event');
-            },
-            direct: (args) => {
-                if (args.length !== 3) throw new TypeError('Direct event requires 3 arguments (user, message, conversation)');
-                if (!args[0] || typeof args[0].id !== 'string') throw new TypeError('Invalid user object in direct event');
-                if (typeof args[1] !== 'string') throw new TypeError('Invalid message in direct event');
-                if (!args[2] || typeof args[2].id !== 'string') throw new TypeError('Invalid conversation object in direct event');
-            },
-            tip: (args) => {
-                if (args.length !== 3) throw new TypeError('Tip event requires 3 arguments (sender, receiver, currency)');
-                if (!args[0] || typeof args[0].id !== 'string') throw new TypeError('Invalid sender in tip event');
-                if (!args[1] || typeof args[1].id !== 'string') throw new TypeError('Invalid receiver in tip event');
-                if (!args[2] || typeof args[2].amount !== 'number') throw new TypeError('Invalid currency in tip event');
-            },
-            movement: (args) => {
-                if (args.length !== 3) throw new TypeError('Movement event requires 3 arguments (user, position, anchor)');
-                if (!args[0] || typeof args[0].id !== 'string') throw new TypeError('Invalid user object in movement event');
-                if (!args[1] || typeof args[1].x !== 'number') throw new TypeError('Invalid position in movement event');
-                if (args[2] !== null && (!args[2] || typeof args[2].entity_id !== 'string')) throw new TypeError('Invalid anchor in movement event');
-            }
-        };
-
-        if (validators[eventType]) {
-            try {
-                validators[eventType](eventArgs);
             } catch (error) {
-                this.ws._logger.error(`await.${eventType}`, error.message)
+                // Filter error - continue to next awaiter
             }
         }
     }

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,391 @@
+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
+        }
+
+        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/src/classes/Managers/Networking/MessageHandler.js

@@ -17,6 +17,7 @@ class MessageHandler {
         setImmediate(() => {
             try {
                 const message = JSON.parse(data.toString());
+                
                 if (this.validateMessageStructure(message)) {
                     this._processMessage(message);
                 } else {

package/src/classes/Managers/RoleManager.js

@@ -37,7 +37,7 @@ class RolesManager {
             this._startWebApiSync();
             this._startAutoSave();
             this.initialized = true;
-            this.logger.success('RolesManager', '✅ Ready! Auto-syncing every 5 minutes.');
+            this.logger.success('RolesManager', 'Ready! Auto-syncing every 5 minutes.');
         } catch (error) {
             this.logger.error('RolesManager', 'Setup failed', error);
             this._createCustomRoles();
@@ -131,8 +131,8 @@ class RolesManager {
     }
 
     _startWebApiSync() {
-        this.syncWithWebApi()
-        setInterval(() => this.syncWithWebApi(), this.config.webapiSyncInterval);
+        // this.syncWithWebApi()
+        // setInterval(() => this.syncWithWebApi(), this.config.webapiSyncInterval);
     }
 
     createRole(roleName) {

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,36 @@ interface CooldownManagerStats {
     memoryUsage: CooldownMemoryUsage;
 }
 
+/**
+ * Context passed to command handlers containing user and additional data
+ */
+interface CommandContext {
+    user: User;
+    args?: string[];
+    message?: string;
+    conversation?: Conversation
+    /** Additional properties */
+    [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;
@@ -3265,7 +3363,7 @@ declare class AwaitClass {
      * );
      * ```
      */
-    movement(filter?: MovementFilter, timeout?: number, maxToCollect?: number, uniqueUsers?: boolean): Promise<[User, Position, AnchorPosition | null][] | []>;
+    movement(filter?: MovementFilter, timeout?: number, maxToCollect?: number, uniqueUsers?: boolean): Promise<[User, Position | null, AnchorPosition | null][] | []>;
 }
 
 declare class WebApi {
@@ -4511,7 +4609,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