seedcord 0.1.0-alpha.0 → 0.1.0-alpha.2

package/dist/index.cjs

@@ -63,9 +63,7 @@ var Globals = class extends envapt.Envapter {
   // Unknown Exception Webhook URL
   static unknownExceptionWebhookUrl;
   // Variables
-  /**
-  * The default color of the bot's embeds. Can simply override by `Globals.botColor =`
-  */
+  /** Default color for bot embeds - can be overridden by setting Globals.botColor */
   static botColor = this.isProduction ? "#fe565a" : "#3fa045";
 };
 _ts_decorate([
@@ -111,9 +109,9 @@ var BuilderTypes = {
   menu_mentionable: discord_js.MentionableSelectMenuBuilder,
   menu_role: discord_js.RoleSelectMenuBuilder,
   modal: discord_js.ModalBuilder,
+  context_menu: discord_js.ContextMenuCommandBuilder,
   subcommand: discord_js.SlashCommandSubcommandBuilder,
-  group: discord_js.SlashCommandSubcommandGroupBuilder,
-  context_menu: discord_js.ContextMenuCommandBuilder
+  group: discord_js.SlashCommandSubcommandGroupBuilder
 };
 var RowTypes = {
   button: discord_js.ActionRowBuilder,
@@ -137,9 +135,12 @@ var BaseComponent = class BaseComponent2 {
     this._component = new ComponentClass();
   }
   /**
-  * @description Returns the instantiated component
-  * @note Use this for configuring the component using its instance setters.
-  * @usage `this.instance.someMethod()`
+  * Gets the component instance for configuration
+  *
+  * Use this to access Discord.js builder methods like setTitle(), setDescription(), etc.
+  *
+  * @protected Use this in your component classes to configure the builder
+  * @example this.instance.setTitle('My Modal')
   */
   get instance() {
     return this._component;
@@ -160,6 +161,16 @@ var BuilderComponent = class extends BaseComponent {
   get component() {
     return this.instance;
   }
+  /**
+  * Builds a customId string for interactive components
+  *
+  * Creates customIds in the format "prefix:arg1-arg2-arg3" for buttons, modals, etc.
+  * Arguments are joined with hyphens and separated from prefix with a colon.
+  *
+  * @param prefix - The route prefix that handlers will match against
+  * @param args - Additional arguments to encode in the customId
+  * @returns Formatted customId string
+  */
   buildCustomId(prefix, ...args) {
     if (args.length === 0) return prefix;
     return `${prefix}:${args.join("-")}`;
@@ -181,6 +192,11 @@ var ModalRow = class ModalRow2 extends RowComponent {
   static {
     __name(this, "ModalRow");
   }
+  /**
+  * Creates a new modal action row with the specified component.
+  *
+  * @param component - The modal field component to wrap in an action row
+  */
   constructor(component) {
     super("modal");
     this.instance.addComponents(component);
@@ -202,6 +218,9 @@ var BaseErrorEmbed = class extends BuilderComponent {
   static {
     __name(this, "BaseErrorEmbed");
   }
+  /**
+  * Creates a new error embed with default configuration.
+  */
   constructor() {
     super("embed");
     this.instance.setTitle("Cannot Proceed");
@@ -218,27 +237,32 @@ var CustomError = class extends Error {
     super(message), this.message = message;
     Error.captureStackTrace(this, this.constructor);
   }
+  /**
+  * Whether this error should be emitted to logs
+  *
+  * Controls logging behavior. Errors with emit=true will always be logged,
+  * while emit=false errors may be suppressed in production.
+  *
+  * @returns True if the error should be logged
+  */
   get emit() {
     return this._emit;
   }
 };
 
 // src/bot/errors/Database.ts
-var DatabaseConnectionFailure = class extends CustomError {
-  static {
-    __name(this, "DatabaseConnectionFailure");
-  }
-  constructor(message = "Failed to connect to the database.") {
-    super(message);
-    this.response.setDescription("Failed to connect to the database.");
-  }
-};
 var DatabaseError = class extends CustomError {
   static {
     __name(this, "DatabaseError");
   }
   uuid;
   _emit = true;
+  /**
+  * Creates a new DatabaseError.
+  *
+  * @param message - The error message describing what went wrong
+  * @param uuid - A unique identifier for this specific error instance
+  */
   constructor(message, uuid) {
     super(message), this.uuid = uuid;
     this.name = "DatabaseError";
@@ -346,48 +370,125 @@ ${parts.join(" ")}`;
       transports: transportsArray
     });
   }
+  /**
+  * Logs an error message with optional additional data.
+  *
+  * @param msg - The error message to log
+  * @param args - Additional data to include in the log entry
+  */
   error(msg, ...args) {
     this.logger.error(msg, ...args);
   }
+  /**
+  * Logs a warning message with optional additional data.
+  *
+  * @param msg - The warning message to log
+  * @param args - Additional data to include in the log entry
+  */
   warn(msg, ...args) {
     this.logger.warn(msg, ...args);
   }
+  /**
+  * Logs an informational message with optional additional data.
+  *
+  * @param msg - The informational message to log
+  * @param args - Additional data to include in the log entry
+  */
   info(msg, ...args) {
     this.logger.info(msg, ...args);
   }
+  /**
+  * Logs an HTTP-related message with optional additional data.
+  *
+  * @param msg - The HTTP message to log
+  * @param args - Additional data to include in the log entry
+  */
   http(msg, ...args) {
     this.logger.http(msg, ...args);
   }
+  /**
+  * Logs a verbose message with optional additional data.
+  *
+  * @param msg - The verbose message to log
+  * @param args - Additional data to include in the log entry
+  */
   verbose(msg, ...args) {
     this.logger.verbose(msg, ...args);
   }
+  /**
+  * Logs a debug message with optional additional data.
+  *
+  * @param msg - The debug message to log
+  * @param args - Additional data to include in the log entry
+  */
   debug(msg, ...args) {
     this.logger.debug(msg, ...args);
   }
+  /**
+  * Logs a silly/trace level message with optional additional data.
+  *
+  * @param msg - The silly message to log
+  * @param args - Additional data to include in the log entry
+  */
   silly(msg, ...args) {
     this.logger.silly(msg, ...args);
   }
-  // eslint-disable-next-line @typescript-eslint/naming-convention
+  /**
+  * Static method to log an error message with a specific prefix.
+  * Creates or retrieves a logger instance for the given prefix.
+  *
+  * @param prefix - The logger prefix/label to use
+  * @param msg - The error message to log
+  * @param args - Additional data to include in the log entry
+  */
   static Error(prefix, msg, ...args) {
     const logger = this.instance(prefix);
     logger.error(msg, ...args);
   }
-  // eslint-disable-next-line @typescript-eslint/naming-convention
+  /**
+  * Static method to log an informational message with a specific prefix.
+  * Creates or retrieves a logger instance for the given prefix.
+  *
+  * @param prefix - The logger prefix/label to use
+  * @param msg - The informational message to log
+  * @param args - Additional data to include in the log entry
+  */
   static Info(prefix, msg, ...args) {
     const logger = this.instance(prefix);
     logger.info(msg, ...args);
   }
-  // eslint-disable-next-line @typescript-eslint/naming-convention
+  /**
+  * Static method to log a warning message with a specific prefix.
+  * Creates or retrieves a logger instance for the given prefix.
+  *
+  * @param prefix - The logger prefix/label to use
+  * @param msg - The warning message to log
+  * @param args - Additional data to include in the log entry
+  */
   static Warn(prefix, msg, ...args) {
     const logger = this.instance(prefix);
     logger.warn(msg, ...args);
   }
-  // eslint-disable-next-line @typescript-eslint/naming-convention
+  /**
+  * Static method to log a debug message with a specific prefix.
+  * Creates or retrieves a logger instance for the given prefix.
+  *
+  * @param prefix - The logger prefix/label to use
+  * @param msg - The debug message to log
+  * @param args - Additional data to include in the log entry
+  */
   static Debug(prefix, msg, ...args) {
     const logger = this.instance(prefix);
     logger.debug(msg, ...args);
   }
-  // eslint-disable-next-line @typescript-eslint/naming-convention
+  /**
+  * Static method to log a silly/trace level message with a specific prefix.
+  * Creates or retrieves a logger instance for the given prefix.
+  *
+  * @param prefix - The logger prefix/label to use
+  * @param msg - The silly message to log
+  * @param args - Additional data to include in the log entry
+  */
   static Silly(prefix, msg, ...args) {
     const logger = this.instance(prefix);
     logger.silly(msg, ...args);
@@ -498,17 +599,17 @@ async function traverseDirectory(dir, callback) {
   }
 }
 __name(traverseDirectory, "traverseDirectory");
-function throwCustomError(error, message, customError) {
+function throwCustomError(error, message, CustomError2) {
   const uuid = crypto.randomUUID();
   Logger.Error("Throwing Custom Error", error.name);
-  if (typeof customError === typeof DatabaseError) {
+  if (typeof CustomError2 === typeof DatabaseError) {
     const errorMessage = error instanceof Error ? error.message : message;
-    throw new customError(errorMessage, uuid);
+    throw new CustomError2(errorMessage, uuid);
   } else {
     if (error instanceof Error) {
-      throw new customError(`${message}: ${error.message ? error.message : error.toString()}`);
+      throw new CustomError2(`${message}: ${error.message ? error.message : error.toString()}`);
     } else {
-      throw new customError(message);
+      throw new CustomError2(message);
     }
   }
 }
@@ -647,14 +748,18 @@ var BaseHandler = class BaseHandler2 {
     return this.event;
   }
   /**
-  * Get the arguments passed from the customId
-  * For example, if customId is "accept:user123-guild456", args will be ["user123", "guild456"]
+  * Gets arguments parsed from interaction customId
+  *
+  * Arguments are extracted from customId using ":" and "-" separators.
+  * For customId "accept:user123-guild456", returns ["user123", "guild456"]
   */
   getArgs() {
     return this.args;
   }
   /**
-  * Get a specific argument by index
+  * Gets a specific argument by index from parsed customId
+  * @param index - Zero-based index of the argument to retrieve
+  * @returns The argument at the specified index, or undefined if not found
   */
   getArg(index) {
     return this.args[index];
@@ -680,6 +785,7 @@ var AutocompleteHandler = class extends BaseHandler {
   static {
     __name(this, "AutocompleteHandler");
   }
+  /** The currently focused autocomplete option (Based on what you set in \@AutocompleteRoute) */
   focused;
   constructor(event, core, args) {
     super(event, core, args);
@@ -886,11 +992,23 @@ var ErrorHandlingUtils = class {
     __name(this, "ErrorHandlingUtils");
   }
   static logger = new Logger("Errors");
-  static handleError(error, core, guild, user) {
+  /**
+  * Processes an error and extracts the standardized response, if available.
+  *
+  * Handles different error types (CustomError, DatabaseError) with appropriate
+  * logging, side effects, and user-facing error messages.
+  *
+  * @param error - The error to process
+  * @param core - The core framework instance
+  * @param guild - The guild where the error occurred (if any)
+  * @param user - The user who triggered the error (if any)
+  * @returns Object containing UUID and formatted error response embed
+  */
+  static extractErrorResponse(error, core, guild, user) {
     const uuid = crypto2__namespace.randomUUID();
     if (error instanceof CustomError) {
       if (error instanceof DatabaseError) {
-        core.hooks.emit("unknownException", {
+        core.effects.emit("unknownException", {
           uuid,
           error,
           guild,
@@ -906,7 +1024,7 @@ var ErrorHandlingUtils = class {
       };
     }
     this.logger.error(uuid, error);
-    core.hooks.emit("unknownException", {
+    core.effects.emit("unknownException", {
       uuid,
       error,
       guild,
@@ -945,7 +1063,7 @@ function Catchable(options) {
         if (!(error instanceof Error)) throw error;
         this.setErrored();
         if (log) console.error(error);
-        const { response } = ErrorHandlingUtils.handleError(error, this.core, interaction.guild, interaction.user);
+        const { response } = ErrorHandlingUtils.extractErrorResponse(error, this.core, interaction.guild, interaction.user);
         const res = {
           embeds: [
             response
@@ -1314,6 +1432,24 @@ var Pluggable = class _Pluggable {
     this.isInitialized = true;
     return this;
   }
+  /**
+  * Attaches a plugin to this instance
+  *
+  * Plugins provide external functionality and are initialized during the specified startup phase.
+  * The plugin instance becomes available as a property in `core` wherever it's available.
+  *
+  * Make sure to augment the {@link Core} interface with the plugin type to ensure TypeScript recognizes it and provides intellisense.
+  *
+  * @template Key - The property name for accessing the plugin
+  * @template Ctor - The plugin constructor type
+  * @param key - Property name to access the plugin instance
+  * @param Plugin - Plugin constructor class
+  * @param startupPhase - When during startup to initialize this plugin ({@link StartupPhase})
+  * @param args - Additional arguments to pass to the plugin constructor
+  * @returns This instance with the plugin attached as a typed property
+  * @throws An {@link Error} When called after initialization or if key already exists
+  * @example seedcord.attach('db', Mongo, StartupPhase.Configuration, { uri: 'mongodb://...' })
+  */
   attach(key, Plugin2, startupPhase, ...args) {
     if (this.isInitialized) throw new Error("Cannot attach a plugin after initialization.");
     if (this[key]) throw new Error(`Plugin with key "${key}" already exists.`);
@@ -1345,7 +1481,21 @@ var CoordinatedLifecycle = class {
     this.phaseOrder.forEach((phase) => this.tasksMap.set(phase, []));
   }
   /**
-  * Add a task to a specific phase
+  * Adds a lifecycle task to a specific phase.
+  *
+  * Tasks are executed in phase order during lifecycle operations.
+  * Each task has a timeout to prevent hanging operations.
+  *
+  * @param phase - The lifecycle phase to add the task to
+  * @param taskName - Unique name for the task (used for logging and removal)
+  * @param task - Async function to execute during the phase
+  * @param timeoutMs - Maximum time allowed for task execution in milliseconds
+  * @example
+  * ```typescript
+  * lifecycle.addTask(StartupPhase.Services, 'start-database', async () => {
+  *   await database.connect();
+  * }, 10000);
+  * ```
   */
   addTask(phase, taskName, task, timeoutMs) {
     if (!this.canAddTask()) return;
@@ -1359,7 +1509,11 @@ var CoordinatedLifecycle = class {
     this.logger.debug(`${chalk6__default.default.italic("Added")} ${this.getTaskType()} task ${chalk6__default.default.bold.cyan(taskName)} to phase ${chalk6__default.default.bold.magenta(this.phaseEnum[phase])}`);
   }
   /**
-  * Remove a task by name from a specific phase
+  * Removes a lifecycle task from a specific phase.
+  *
+  * @param phase - The lifecycle phase to remove the task from
+  * @param taskName - Name of the task to remove
+  * @returns True if the task was found and removed, false otherwise
   */
   removeTask(phase, taskName) {
     if (!this.canRemoveTask()) return false;
@@ -1493,19 +1647,40 @@ var CoordinatedShutdown = class extends CoordinatedLifecycle {
     });
   }
   /**
-  * Add a task to a specific shutdown phase
+  * Adds a task to a specific shutdown phase with timeout.
+  *
+  * @param phase - The shutdown phase from {@link ShutdownPhase}
+  * @param taskName - Unique identifier for the task
+  * @param task - Async function to execute
+  * @param timeoutMs - Task timeout in milliseconds (default: 5000)
   */
   addTask(phase, taskName, task, timeoutMs = 5e3) {
     super.addTask(phase, taskName, task, timeoutMs);
   }
   /**
-  * Remove a task by name from a specific phase
+  * Removes a task from a specific shutdown phase.
+  *
+  * @param phase - The shutdown phase to remove from
+  * @param taskName - Name of the task to remove
+  * @returns True if task was found and removed
   */
   removeTask(phase, taskName) {
     return super.removeTask(phase, taskName);
   }
   /**
-  * Start the coordinated shutdown sequence
+  * Executes the coordinated shutdown sequence.
+  *
+  * Runs all registered tasks across shutdown phases in reverse order.
+  * Tasks within each phase are executed in parallel for faster shutdown.
+  * Process exits with the specified code when complete.
+  *
+  * @param exitCode - Process exit code (default: 0)
+  * @returns Promise that resolves when shutdown is complete
+  * @example
+  * ```typescript
+  * shutdown.addTask(ShutdownPhase.Services, 'database', () => db.disconnect(), 5000);
+  * await shutdown.run(0); // Graceful shutdown
+  * ```
   */
   async run(exitCode = 0) {
     if (this.isShuttingDown) {
@@ -1559,6 +1734,10 @@ var Bot = class extends Plugin {
   events;
   commands;
   emojiInjector;
+  /**
+  * @param core - Seedcord core instance
+  * @internal
+  */
   constructor(core) {
     super(core), this.core = core;
     this._client = new discord_js.Client(core.config.bot.clientOptions);
@@ -1568,6 +1747,10 @@ var Bot = class extends Plugin {
     this.emojiInjector = new EmojiInjector(this.core);
     this.core.shutdown.addTask(ShutdownPhase.DiscordCleanup, "stop-bot", async () => await this.stop());
   }
+  /**
+  * Initializes Discord client and all controllers
+  * @internal
+  */
   async init() {
     if (this.isInitialized) {
       return;
@@ -1580,15 +1763,27 @@ var Bot = class extends Plugin {
     await this.commands.setCommands();
     await this.emojiInjector.init();
   }
+  /**
+  * Stops the bot and cleans up connections
+  * @internal
+  */
   async stop() {
     this._client.removeAllListeners();
     await this.logout();
   }
+  /**
+  * Logs the bot into Discord using the configured token
+  * @private
+  */
   async login() {
     await this._client.login(Globals.botToken);
     this.logger.info(`Logged in as ${chalk6__default.default.bold.magenta(this._client.user?.username)}!`);
     return this;
   }
+  /**
+  * Logs out and destroys the Discord client connection
+  * @private
+  */
   async logout() {
     await this._client.destroy();
     this.logger.info(chalk6__default.default.bold.red("Logged out of Discord!"));
@@ -1598,22 +1793,28 @@ var Bot = class extends Plugin {
   }
 };
 
-// src/hooks/decorators/RegisterHook.ts
-var HookMetadataKey = Symbol("hook:metadata");
-function RegisterHook(hook) {
+// src/effects/decorators/RegisterEffect.ts
+var EffectMetadataKey = Symbol("effect:metadata");
+function RegisterEffect(effect) {
   return function(constructor) {
-    Reflect.defineMetadata(HookMetadataKey, hook, constructor);
+    Reflect.defineMetadata(EffectMetadataKey, effect, constructor);
   };
 }
-__name(RegisterHook, "RegisterHook");
+__name(RegisterEffect, "RegisterEffect");
 
-// src/hooks/interfaces/HookHandler.ts
-var HookHandler = class {
+// src/effects/interfaces/EffectsHandler.ts
+var EffectsHandler = class {
   static {
-    __name(this, "HookHandler");
+    __name(this, "EffectsHandler");
   }
   data;
   core;
+  /**
+  * Creates a new effects handler instance.
+  *
+  * @param data - The effect event data
+  * @param core - The core framework instance
+  */
   constructor(data, core) {
     this.data = data;
     this.core = core;
@@ -1622,8 +1823,8 @@ var HookHandler = class {
   }
 };
 
-// src/hooks/interfaces/abstracts/WebhookLog.ts
-var WebhookLog = class extends HookHandler {
+// src/effects/interfaces/abstracts/WebhookLog.ts
+var WebhookLog = class extends EffectsHandler {
   static {
     __name(this, "WebhookLog");
   }
@@ -1632,7 +1833,7 @@ var WebhookLog = class extends HookHandler {
   }
 };
 
-// src/hooks/default/UnknownException.ts
+// src/effects/default/UnknownException.ts
 function _ts_decorate3(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -1658,7 +1859,7 @@ var UnknownException = class extends WebhookLog {
   }
 };
 UnknownException = _ts_decorate3([
-  RegisterHook("unknownException")
+  RegisterEffect("unknownException")
 ], UnknownException);
 var UnhandledErrorEmbed = class UnhandledErrorEmbed2 extends BuilderComponent {
   static {
@@ -1695,83 +1896,107 @@ var UnhandledErrorEmbed = class UnhandledErrorEmbed2 extends BuilderComponent {
     ]);
   }
 };
-var HookEmitter = class {
+var EffectsEmitter = class {
   static {
-    __name(this, "HookEmitter");
+    __name(this, "EffectsEmitter");
   }
   emitter = new events.EventEmitter();
+  /**
+  * Registers a listener for the specified side effect.
+  *
+  * @template KeyOfEffects - The side effect name type
+  * @param event - The side effect name to listen for
+  * @param listener - Function to call when the event is emitted
+  * @returns This EffectsEmitter instance for chaining
+  */
   on(event, listener) {
     this.emitter.on(event, listener);
     return this;
   }
+  /**
+  * Registers a one-time listener for the specified side effect.
+  *
+  * @template KeyOfEffects - The side effect name type
+  * @param event - The side effect name to listen for once
+  * @param listener - Function to call when the event is emitted
+  * @returns This EffectsEmitter instance for chaining
+  */
   once(event, listener) {
     this.emitter.once(event, listener);
     return this;
   }
+  /**
+  * Emits a side effect with the provided data.
+  *
+  * @template KeyOfEffects - The side effect name type
+  * @param event - The side effect name to emit
+  * @param data - The data to pass to registered listeners
+  * @returns True if the event had listeners, false otherwise
+  */
   emit(event, data) {
     return this.emitter.emit(event, data);
   }
 };
 
-// src/hooks/HookController.ts
-var HookController = class extends Plugin {
+// src/effects/EffectsRegistry.ts
+var EffectsRegistry = class extends Plugin {
   static {
-    __name(this, "HookController");
+    __name(this, "EffectsRegistry");
   }
   core;
-  logger = new Logger("Hooks");
+  logger = new Logger("Effects");
   isInitialized = false;
-  hookMap = /* @__PURE__ */ new Map();
-  emitter = new HookEmitter();
+  effectsMap = /* @__PURE__ */ new Map();
+  emitter = new EffectsEmitter();
   constructor(core) {
     super(core), this.core = core;
   }
   async init() {
     if (this.isInitialized) return;
     this.isInitialized = true;
-    const hooksDir = this.core.config.hooks.path;
-    this.logger.info(chalk6__default.default.bold(hooksDir));
-    this.registerHook("unknownException", UnknownException);
-    await this.loadHooks(hooksDir);
-    this.attachHooks();
-    const totalHooks = Array.from(this.hookMap.values()).reduce((acc, handlers) => acc + handlers.length, 0);
-    this.logger.info(`${chalk6__default.default.bold.green("Loaded")}: ${chalk6__default.default.bold.magenta(totalHooks)} hooks`);
-  }
-  async loadHooks(dir) {
+    const effectsDir = this.core.config.effects.path;
+    this.logger.info(chalk6__default.default.bold(effectsDir));
+    this.registerEffect("unknownException", UnknownException);
+    await this.loadEffects(effectsDir);
+    this.attachEffects();
+    const totalEffects = Array.from(this.effectsMap.values()).reduce((acc, handlers) => acc + handlers.length, 0);
+    this.logger.info(`${chalk6__default.default.bold.green("Loaded")}: ${chalk6__default.default.bold.magenta(totalEffects)} side effects`);
+  }
+  async loadEffects(dir) {
     await traverseDirectory(dir, (_fullPath, relativePath, imported) => {
       for (const exportName of Object.keys(imported)) {
         const val = imported[exportName];
-        if (this.isHookHandler(val)) {
-          const hookName = Reflect.getMetadata(HookMetadataKey, val);
-          if (hookName) {
-            this.registerHook(hookName, val);
+        if (this.isEffectHandler(val)) {
+          const effectName = Reflect.getMetadata(EffectMetadataKey, val);
+          if (effectName) {
+            this.registerEffect(effectName, val);
             this.logger.info(`${chalk6__default.default.italic("Registered")} ${chalk6__default.default.bold.yellow(val.name)} from ${chalk6__default.default.gray(relativePath)}`);
           }
         }
       }
     });
   }
-  registerHook(hookName, handler) {
-    let handlers = this.hookMap.get(hookName);
+  registerEffect(effectName, handler) {
+    let handlers = this.effectsMap.get(effectName);
     if (!handlers) {
       handlers = [];
-      this.hookMap.set(hookName, handlers);
+      this.effectsMap.set(effectName, handlers);
     }
     handlers.push(handler);
   }
-  isHookHandler(obj) {
+  isEffectHandler(obj) {
     if (typeof obj !== "function") return false;
-    return obj.prototype instanceof HookHandler;
+    return obj.prototype instanceof EffectsHandler;
   }
-  attachHooks() {
-    for (const [hookName, handlerCtors] of this.hookMap) {
-      this.emitter.on(hookName, (data) => {
+  attachEffects() {
+    for (const [effectName, handlerCtors] of this.effectsMap) {
+      this.emitter.on(effectName, (data) => {
         for (const HandlerCtor of handlerCtors) {
           try {
             const instance = new HandlerCtor(data, this.core);
             void instance.execute();
           } catch (err) {
-            this.logger.error(`Error in hook ${String(hookName)} handler ${HandlerCtor.name}:`, err);
+            this.logger.error(`Error in side effect ${String(effectName)} handler ${HandlerCtor.name}:`, err);
           }
         }
       });
@@ -1827,6 +2052,11 @@ var HealthCheck = class extends Plugin {
       });
     });
   }
+  /**
+  * Stops the health check server.
+  *
+  * @returns Promise that resolves when the server is closed
+  */
   stop() {
     return new Promise((shutdownResolve) => {
       this.server?.close(() => {
@@ -1865,7 +2095,12 @@ var CoordinatedStartup = class extends CoordinatedLifecycle {
     super("CoordinatedStartup", PHASE_ORDER2, StartupPhase);
   }
   /**
-  * Add a task to a specific startup phase
+  * Adds a task to a specific startup phase with timeout.
+  *
+  * @param phase - The startup phase from {@link StartupPhase}
+  * @param taskName - Unique identifier for the task
+  * @param task - Async function to execute
+  * @param timeoutMs - Task timeout in milliseconds (default: 10000)
   */
   addTask(phase, taskName, task, timeoutMs = 1e4) {
     super.addTask(phase, taskName, task, timeoutMs);
@@ -1902,7 +2137,20 @@ var CoordinatedStartup = class extends CoordinatedLifecycle {
     return results;
   }
   /**
-  * Start the coordinated startup sequence
+  * Executes the coordinated startup sequence.
+  *
+  * Runs all registered tasks across startup phases in the correct order.
+  * Each phase completes before the next phase begins. Tasks within a phase
+  * are executed sequentially to maintain predictable initialization.
+  *
+  * @returns Promise that resolves when startup is complete
+  * @throws An {@link Error} If startup fails or is called multiple times
+  * @example
+  * ```typescript
+  * const startup = new CoordinatedStartup();
+  * startup.addTask(StartupPhase.Services, 'database', () => db.connect(), 10000);
+  * await startup.run();
+  * ```
   */
   async run() {
     if (this.hasStarted) {
@@ -1962,11 +2210,22 @@ var Seedcord = class _Seedcord extends Pluggable {
   }
   config;
   static isInstantiated = false;
+  /** @see {@link CoordinatedShutdown} */
   shutdown;
+  /** @see {@link CoordinatedStartup} */
   startup;
-  hooks;
+  /** @see {@link EffectsRegistry} */
+  effects;
+  /** @see {@link Bot} */
   bot;
+  /** @see {@link HealthCheck} */
   healthCheck;
+  /**
+  * Creates a new Seedcord instance
+  *
+  * @param config - Bot configuration including paths and Discord client options
+  * @throws An {@link Error} When attempting to create multiple instances (singleton)
+  */
   constructor(config) {
     const shutdown = new CoordinatedShutdown();
     const startup = new CoordinatedStartup();
@@ -1977,16 +2236,20 @@ var Seedcord = class _Seedcord extends Pluggable {
       throw new Error("Seedcord can only be instantiated once. Use the existing instance instead.");
     }
     _Seedcord.isInstantiated = true;
-    this.hooks = new HookController(this);
+    this.effects = new EffectsRegistry(this);
     this.bot = new Bot(this);
     this.healthCheck = new HealthCheck(this);
     this.registerStartupTasks();
   }
+  /**
+  * Registers default startup tasks
+  * @internal
+  */
   registerStartupTasks() {
-    this.startup.addTask(StartupPhase.Configuration, "Hook Initialization", async () => {
-      this.hooks.logger.info(chalk6__default.default.bold("Initializing"));
-      await this.hooks.init();
-      this.hooks.logger.info(chalk6__default.default.bold("Initialized"));
+    this.startup.addTask(StartupPhase.Configuration, "Effect Initialization", async () => {
+      this.effects.logger.info(chalk6__default.default.bold("Initializing"));
+      await this.effects.init();
+      this.effects.logger.info(chalk6__default.default.bold("Initialized"));
     });
     this.startup.addTask(StartupPhase.Instantiation, "Bot Initialization", async () => {
       this.bot.logger.info(chalk6__default.default.bold("Initializing"));
@@ -1999,6 +2262,11 @@ var Seedcord = class _Seedcord extends Pluggable {
       this.healthCheck.logger.info(chalk6__default.default.bold("Initialized"));
     });
   }
+  /**
+  * Starts the bot and runs all initialization tasks
+  *
+  * @returns This Seedcord instance when fully initialized
+  */
   async start() {
     await super.init();
     return this;
@@ -2028,11 +2296,11 @@ function EventCatchable(log) {
           this.getEvent()
         ];
         const msg = eventArgs.find((x) => x instanceof discord_js.Message);
-        const result = ErrorHandlingUtils.handleError(err, this.core, msg?.guild ?? null, msg?.author ?? null);
+        const { response } = ErrorHandlingUtils.extractErrorResponse(err, this.core, msg?.guild ?? null, msg?.author ?? null);
         if (!msg) return;
         await msg.reply({
           embeds: [
-            result.response
+            response
           ],
           components: []
         });
@@ -2051,19 +2319,32 @@ var CooldownManager = class {
   Err;
   msg;
   map = /* @__PURE__ */ new Map();
+  /**
+  * Creates a new CooldownManager instance.
+  *
+  * @param opts - Configuration options for the cooldown behavior
+  */
   constructor(opts = {}) {
     this.window = opts.cooldown ?? 1e3;
     this.Err = opts.err ?? Error;
     this.msg = opts.message ?? "Cooldown active";
   }
-  /** Record usage without any checks. */
+  /**
+  * Records usage timestamp for a key without any cooldown checks.
+  *
+  * @param key - The unique identifier for the cooldown entry
+  */
   set(key) {
     this.map.set(key, Date.now());
   }
   /**
-  * Verify cooldown for `key`.\
-  * If active → throws the custom error.\
-  * If not active → updates timestamp and returns void.
+  * Verifies cooldown status for a key and updates timestamp if not active.
+  *
+  * If the cooldown is still active, throws the configured error.
+  * If not active, updates the timestamp and returns successfully.
+  *
+  * @param key - The unique identifier to check cooldown for
+  * @throws An {@link Err} When the cooldown is still active for the given key
   */
   check(key) {
     const now = Date.now();
@@ -2077,12 +2358,21 @@ var CooldownManager = class {
     }
     this.map.set(key, now);
   }
-  /** Returns true if the key is still cooling down (does not update timestamp). */
+  /**
+  * Checks if a key is currently cooling down without updating timestamp.
+  *
+  * @param key - The unique identifier to check
+  * @returns True if the key is still cooling down, false otherwise
+  */
   isActive(key) {
     const last = this.map.get(key);
     return last !== void 0 && Date.now() - last < this.window;
   }
-  /** Remove a key from the map (useful for manual resets). */
+  /**
+  * Removes a key from the cooldown map.
+  *
+  * @param key - The unique identifier to remove (useful for manual resets)
+  */
   clear(key) {
     this.map.delete(key);
   }
@@ -2164,7 +2454,9 @@ var Mongo = class extends Plugin {
         tls: true,
         ssl: true
       }
-    }).then((i) => this.logger.info(`Connected to MongoDB: ${chalk6__default.default.bold.magenta(i.connection.name)}`)).catch((err) => throwCustomError(err, "Could not connect to MongoDB", DatabaseConnectionFailure));
+    }).then((i) => this.logger.info(`Connected to MongoDB: ${chalk6__default.default.bold.magenta(i.connection.name)}`)).catch((err) => {
+      throw new Error(`Could not connect to MongoDB`, err);
+    });
   }
   async disconnect() {
     await mongoose2__default.default.disconnect().then(() => this.logger.info(chalk6__default.default.red.bold("Disconnected from MongoDB"))).catch((err) => this.logger.error(`Could not disconnect from MongoDB: ${err.message}`));
@@ -2230,15 +2522,15 @@ exports.CustomError = CustomError;
 exports.DBCatchable = DBCatchable;
 exports.DatabaseModel = DatabaseModel;
 exports.DatabaseService = DatabaseService;
+exports.EffectMetadataKey = EffectMetadataKey;
+exports.EffectsEmitter = EffectsEmitter;
+exports.EffectsHandler = EffectsHandler;
+exports.EffectsRegistry = EffectsRegistry;
 exports.EventCatchable = EventCatchable;
 exports.EventHandler = EventHandler;
 exports.EventMetadataKey = EventMetadataKey;
 exports.Globals = Globals;
 exports.HealthCheck = HealthCheck;
-exports.HookController = HookController;
-exports.HookEmitter = HookEmitter;
-exports.HookHandler = HookHandler;
-exports.HookMetadataKey = HookMetadataKey;
 exports.InteractionHandler = InteractionHandler;
 exports.InteractionMetadataKey = InteractionMetadataKey;
 exports.InteractionMiddleware = InteractionMiddleware;
@@ -2251,8 +2543,8 @@ exports.Mongo = Mongo;
 exports.Pluggable = Pluggable;
 exports.Plugin = Plugin;
 exports.RegisterCommand = RegisterCommand;
+exports.RegisterEffect = RegisterEffect;
 exports.RegisterEvent = RegisterEvent;
-exports.RegisterHook = RegisterHook;
 exports.RowComponent = RowComponent;
 exports.Seedcord = Seedcord;
 exports.SelectMenuRoute = SelectMenuRoute;