@seedcord/services 0.3.3 → 0.4.0

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { Envapter, Envapt } from 'envapt';
 import { format, transports, createLogger } from 'winston';
+import chalk2 from 'chalk';
 import { createServer } from 'http';
-import chalk from 'chalk';
 import { EventEmitter } from 'events';
 
 var __defProp = Object.defineProperty;
@@ -230,6 +230,232 @@ ${parts.join(" ")}`;
     logger.silly(msg, ...args);
   }
 };
+
+// src/CooldownManager.ts
+var CooldownManager = class {
+  static {
+    __name(this, "CooldownManager");
+  }
+  window;
+  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";
+  }
+  /**
+   * 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());
+  }
+  /**
+   * 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();
+    const last = this.map.get(key);
+    const remaining = this.window - (now - (last ?? 0));
+    if (Envapter.isDevelopment && remaining > 0) {
+      Logger.Debug("CooldownManager", `${key} - ${remaining}ms remaining`);
+    }
+    if (last !== void 0 && remaining > 0) {
+      throw new this.Err(this.msg, remaining);
+    }
+    this.map.set(key, now);
+  }
+  /**
+   * 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;
+  }
+  /**
+   * Removes a key from the cooldown map.
+   *
+   * @param key - The unique identifier to remove (useful for manual resets)
+   */
+  clear(key) {
+    this.map.delete(key);
+  }
+};
+
+// src/Errors/ErrorCodes.ts
+var SeedcordErrorCode = /* @__PURE__ */ (function(SeedcordErrorCode2) {
+  SeedcordErrorCode2[SeedcordErrorCode2["ConfigMissingDiscordToken"] = 1001] = "ConfigMissingDiscordToken";
+  SeedcordErrorCode2[SeedcordErrorCode2["ConfigUnknownExceptionWebhookMissing"] = 1002] = "ConfigUnknownExceptionWebhookMissing";
+  SeedcordErrorCode2[SeedcordErrorCode2["ConfigUnknownExceptionWebhookInvalid"] = 1003] = "ConfigUnknownExceptionWebhookInvalid";
+  SeedcordErrorCode2[SeedcordErrorCode2["LifecycleAddAfterCompletion"] = 1101] = "LifecycleAddAfterCompletion";
+  SeedcordErrorCode2[SeedcordErrorCode2["LifecycleAddDuringRun"] = 1102] = "LifecycleAddDuringRun";
+  SeedcordErrorCode2[SeedcordErrorCode2["LifecycleRemoveDuringRun"] = 1103] = "LifecycleRemoveDuringRun";
+  SeedcordErrorCode2[SeedcordErrorCode2["LifecycleUnknownPhase"] = 1104] = "LifecycleUnknownPhase";
+  SeedcordErrorCode2[SeedcordErrorCode2["LifecyclePhaseFailures"] = 1105] = "LifecyclePhaseFailures";
+  SeedcordErrorCode2[SeedcordErrorCode2["LifecycleTaskTimeout"] = 1106] = "LifecycleTaskTimeout";
+  SeedcordErrorCode2[SeedcordErrorCode2["CoreSingletonViolation"] = 1201] = "CoreSingletonViolation";
+  SeedcordErrorCode2[SeedcordErrorCode2["CorePluginAfterInit"] = 1202] = "CorePluginAfterInit";
+  SeedcordErrorCode2[SeedcordErrorCode2["CorePluginKeyExists"] = 1203] = "CorePluginKeyExists";
+  SeedcordErrorCode2[SeedcordErrorCode2["CoreClientUserUnavailable"] = 1204] = "CoreClientUserUnavailable";
+  SeedcordErrorCode2[SeedcordErrorCode2["CoreBotRoleMissing"] = 1205] = "CoreBotRoleMissing";
+  SeedcordErrorCode2[SeedcordErrorCode2["DecoratorInteractionEventFilter"] = 1301] = "DecoratorInteractionEventFilter";
+  SeedcordErrorCode2[SeedcordErrorCode2["DecoratorMethodNotFound"] = 1302] = "DecoratorMethodNotFound";
+  SeedcordErrorCode2[SeedcordErrorCode2["DecoratorCommandAlreadyRegistered"] = 1303] = "DecoratorCommandAlreadyRegistered";
+  SeedcordErrorCode2[SeedcordErrorCode2["DecoratorCommandGlobalWithGuilds"] = 1304] = "DecoratorCommandGlobalWithGuilds";
+  SeedcordErrorCode2[SeedcordErrorCode2["DecoratorCommandGuildWithoutGuilds"] = 1305] = "DecoratorCommandGuildWithoutGuilds";
+  SeedcordErrorCode2[SeedcordErrorCode2["DecoratorInvalidMiddlewarePriority"] = 1306] = "DecoratorInvalidMiddlewarePriority";
+  SeedcordErrorCode2[SeedcordErrorCode2["UtilHexInputType"] = 1401] = "UtilHexInputType";
+  SeedcordErrorCode2[SeedcordErrorCode2["UtilHexInvalid"] = 1402] = "UtilHexInvalid";
+  SeedcordErrorCode2[SeedcordErrorCode2["UtilInvalidSlashRouteArgument"] = 1403] = "UtilInvalidSlashRouteArgument";
+  SeedcordErrorCode2[SeedcordErrorCode2["PluginMongoServiceDecoratorMissing"] = 2101] = "PluginMongoServiceDecoratorMissing";
+  SeedcordErrorCode2[SeedcordErrorCode2["PluginMongoModelDecoratorMissing"] = 2102] = "PluginMongoModelDecoratorMissing";
+  SeedcordErrorCode2[SeedcordErrorCode2["PluginMongoConnectionFailed"] = 2103] = "PluginMongoConnectionFailed";
+  SeedcordErrorCode2[SeedcordErrorCode2["PluginKpgServiceDecoratorMissing"] = 2201] = "PluginKpgServiceDecoratorMissing";
+  SeedcordErrorCode2[SeedcordErrorCode2["PluginKpgServiceTableMissing"] = 2202] = "PluginKpgServiceTableMissing";
+  SeedcordErrorCode2[SeedcordErrorCode2["PluginKpgInvalidStepCount"] = 2203] = "PluginKpgInvalidStepCount";
+  SeedcordErrorCode2[SeedcordErrorCode2["PluginKpgUnknownDirection"] = 2204] = "PluginKpgUnknownDirection";
+  SeedcordErrorCode2[SeedcordErrorCode2["PluginKpgUnresolvedMigrationsPath"] = 2205] = "PluginKpgUnresolvedMigrationsPath";
+  SeedcordErrorCode2[SeedcordErrorCode2["PluginKpgNoMigrationFiles"] = 2206] = "PluginKpgNoMigrationFiles";
+  SeedcordErrorCode2[SeedcordErrorCode2["PluginKpgInvalidMigrationModule"] = 2207] = "PluginKpgInvalidMigrationModule";
+  SeedcordErrorCode2[SeedcordErrorCode2["PluginKpgNonErrorFailure"] = 2208] = "PluginKpgNonErrorFailure";
+  return SeedcordErrorCode2;
+})({});
+
+// src/Errors/ErrorMessages.ts
+var messages = {
+  [SeedcordErrorCode.ConfigMissingDiscordToken]: () => "Missing DISCORD_BOT_TOKEN environment variable.",
+  [SeedcordErrorCode.ConfigUnknownExceptionWebhookMissing]: () => "Missing UNKNOWN_EXCEPTION_WEBHOOK_URL environment variable.",
+  [SeedcordErrorCode.ConfigUnknownExceptionWebhookInvalid]: () => "Invalid UNKNOWN_EXCEPTION_WEBHOOK_URL value.",
+  [SeedcordErrorCode.LifecycleAddAfterCompletion]: () => "Cannot add tasks after startup sequence has already completed.",
+  [SeedcordErrorCode.LifecycleAddDuringRun]: () => "Cannot add tasks while startup sequence is in progress.",
+  [SeedcordErrorCode.LifecycleRemoveDuringRun]: () => "Cannot remove tasks while startup sequence is in progress.",
+  [SeedcordErrorCode.LifecycleUnknownPhase]: (phase) => `Unknown phase: ${String(phase)}.`,
+  [SeedcordErrorCode.LifecyclePhaseFailures]: (phase, failures) => `Phase ${phase} completed with ${failures} failed task${failures === 1 ? "" : "s"}.`,
+  [SeedcordErrorCode.LifecycleTaskTimeout]: (taskName, timeout) => `Task "${taskName}" timed out after ${timeout}ms.`,
+  [SeedcordErrorCode.CoreSingletonViolation]: () => "Seedcord can only be instantiated once. Use the existing instance instead.",
+  [SeedcordErrorCode.CorePluginAfterInit]: () => "Cannot attach a plugin after initialization.",
+  [SeedcordErrorCode.CorePluginKeyExists]: (key) => `Plugin with key "${key}" already exists.`,
+  [SeedcordErrorCode.CoreClientUserUnavailable]: () => "Client user is not available.",
+  [SeedcordErrorCode.CoreBotRoleMissing]: (guildId) => guildId ? `Bot role not found in guild ${guildId}.` : "Bot role not found in guild.",
+  [SeedcordErrorCode.DecoratorInteractionEventFilter]: () => "Interaction middleware cannot specify event filters.",
+  [SeedcordErrorCode.DecoratorMethodNotFound]: () => "Decorator could not locate the original method. Ensure the method exists before applying the decorator.",
+  [SeedcordErrorCode.DecoratorCommandAlreadyRegistered]: (commandName, existingScope, requestedScope) => `Command "${commandName}" is already registered as a "${existingScope}" command and cannot be re-registered as a "${requestedScope}" command.`,
+  [SeedcordErrorCode.DecoratorCommandGlobalWithGuilds]: () => 'RegisterCommand("global") cannot have guilds specified.',
+  [SeedcordErrorCode.DecoratorCommandGuildWithoutGuilds]: () => 'RegisterCommand("guild") requires a non-empty guilds array.',
+  [SeedcordErrorCode.DecoratorInvalidMiddlewarePriority]: () => "Middleware priority must be a finite number.",
+  [SeedcordErrorCode.UtilHexInputType]: () => "hexToNumber expects a string input.",
+  [SeedcordErrorCode.UtilHexInvalid]: () => "Invalid hex string.",
+  [SeedcordErrorCode.UtilInvalidSlashRouteArgument]: () => "Invalid argument passed to buildSlashRoute.",
+  [SeedcordErrorCode.PluginMongoServiceDecoratorMissing]: (className) => `Missing @RegisterMongoService on ${className}.`,
+  [SeedcordErrorCode.PluginMongoModelDecoratorMissing]: (className) => `Missing @RegisterMongoModel on ${className}.`,
+  [SeedcordErrorCode.PluginMongoConnectionFailed]: (databaseName) => databaseName ? `Could not connect to MongoDB (${databaseName}).` : "Could not connect to MongoDB.",
+  [SeedcordErrorCode.PluginKpgServiceDecoratorMissing]: (className) => `Missing @RegisterKpgService on ${className}.`,
+  [SeedcordErrorCode.PluginKpgServiceTableMissing]: (className) => `Missing table metadata for ${className}. Provide a table via @RegisterKpgService().`,
+  [SeedcordErrorCode.PluginKpgInvalidStepCount]: () => "Migration step count must be a non-negative integer.",
+  [SeedcordErrorCode.PluginKpgUnknownDirection]: (direction) => `Unknown migration direction: ${String(direction)}.`,
+  [SeedcordErrorCode.PluginKpgUnresolvedMigrationsPath]: (label) => `Unable to resolve migrations at path: ${label}.`,
+  [SeedcordErrorCode.PluginKpgNoMigrationFiles]: () => "No migration files provided.",
+  [SeedcordErrorCode.PluginKpgInvalidMigrationModule]: (filePath) => `Migration file ${filePath} must export async functions up and down.`,
+  [SeedcordErrorCode.PluginKpgNonErrorFailure]: (message) => `Migration failure: ${message}.`
+};
+function formatSeedcordErrorMessage(code, args) {
+  const formatter = messages[code];
+  const resolvedArgs = args ?? [];
+  return formatter(...resolvedArgs);
+}
+__name(formatSeedcordErrorMessage, "formatSeedcordErrorMessage");
+function resolveIdentifier(code) {
+  return SeedcordErrorCode[code];
+}
+__name(resolveIdentifier, "resolveIdentifier");
+function resolveMessage(code, args) {
+  return formatSeedcordErrorMessage(code, args);
+}
+__name(resolveMessage, "resolveMessage");
+function formatErrorName(name, _identifier, code) {
+  return `${chalk2.bold.red(name)}[${chalk2.gray(code)}]`;
+}
+__name(formatErrorName, "formatErrorName");
+var SeedcordError = class extends Error {
+  static {
+    __name(this, "SeedcordError");
+  }
+  code;
+  identifier;
+  constructor(code, args, options) {
+    const message = resolveMessage(code, args);
+    super(message, options);
+    this.code = code;
+    this.identifier = resolveIdentifier(code);
+    this.name = formatErrorName(new.target.name, this.identifier, this.code);
+    Object.setPrototypeOf(this, new.target.prototype);
+    if (typeof Error.captureStackTrace === "function") {
+      Error.captureStackTrace(this, new.target);
+    }
+  }
+};
+var SeedcordTypeError = class extends TypeError {
+  static {
+    __name(this, "SeedcordTypeError");
+  }
+  code;
+  identifier;
+  constructor(code, args, options) {
+    const message = resolveMessage(code, args);
+    super(message, options);
+    this.code = code;
+    this.identifier = resolveIdentifier(code);
+    this.name = formatErrorName(new.target.name, this.identifier, this.code);
+    Object.setPrototypeOf(this, new.target.prototype);
+    if (typeof Error.captureStackTrace === "function") {
+      Error.captureStackTrace(this, new.target);
+    }
+  }
+};
+var SeedcordRangeError = class extends RangeError {
+  static {
+    __name(this, "SeedcordRangeError");
+  }
+  code;
+  identifier;
+  constructor(code, args, options) {
+    const message = resolveMessage(code, args);
+    super(message, options);
+    this.code = code;
+    this.identifier = resolveIdentifier(code);
+    this.name = formatErrorName(new.target.name, this.identifier, this.code);
+    Object.setPrototypeOf(this, new.target.prototype);
+    if (typeof Error.captureStackTrace === "function") {
+      Error.captureStackTrace(this, new.target);
+    }
+  }
+};
+var SeedcordErrors = {
+  Error: SeedcordError,
+  TypeError: SeedcordTypeError,
+  RangeError: SeedcordRangeError
+};
+function isSeedcordError(error) {
+  return typeof error === "object" && error !== null && "code" in error && typeof error.code === "number" && "identifier" in error && typeof error.identifier === "string";
+}
+__name(isSeedcordError, "isSeedcordError");
 var CoordinatedLifecycle = class {
   static {
     __name(this, "CoordinatedLifecycle");
@@ -265,13 +491,17 @@ var CoordinatedLifecycle = class {
   addTask(phase, taskName, task, timeoutMs) {
     if (!this.canAddTask()) return;
     const tasks = this.tasksMap.get(phase);
-    if (!tasks) throw new Error(`Unknown phase: ${phase}`);
+    if (!tasks) {
+      throw new SeedcordError(SeedcordErrorCode.LifecycleUnknownPhase, [
+        phase
+      ]);
+    }
     tasks.push({
       name: taskName,
       task,
       timeout: timeoutMs
     });
-    this.logger.debug(`${chalk.italic("Added")} ${this.getTaskType()} task ${chalk.bold.cyan(taskName)} to phase ${chalk.bold.magenta(this.phaseEnum[phase])}`);
+    this.logger.debug(`${chalk2.italic("Added")} ${this.getTaskType()} task ${chalk2.bold.cyan(taskName)} to phase ${chalk2.bold.magenta(this.phaseEnum[phase])}`);
   }
   /**
    * Removes a lifecycle task from a specific phase.
@@ -289,7 +519,7 @@ var CoordinatedLifecycle = class {
     this.tasksMap.set(phase, filteredTasks);
     const removed = initialLength !== filteredTasks.length;
     if (removed) {
-      this.logger.debug(`${chalk.italic("Removed")} ${this.getTaskType()} task ${chalk.bold.cyan(taskName)} from phase ${chalk.bold.magenta(this.phaseEnum[phase])}`);
+      this.logger.debug(`${chalk2.italic("Removed")} ${this.getTaskType()} task ${chalk2.bold.cyan(taskName)} from phase ${chalk2.bold.magenta(this.phaseEnum[phase])}`);
     }
     return removed;
   }
@@ -299,18 +529,20 @@ var CoordinatedLifecycle = class {
   async runPhase(phase) {
     const tasks = this.tasksMap.get(phase) ?? [];
     if (tasks.length === 0) {
-      this.logger.warn(`No tasks to run in phase ${chalk.bold.magenta(this.phaseEnum[phase])}`);
+      this.logger.warn(`No tasks to run in phase ${chalk2.bold.magenta(this.phaseEnum[phase])}`);
       return;
     }
-    this.logger.info(`${chalk.bold.yellow("Running")} ${this.getTaskType()} phase ${chalk.bold.magenta(this.phaseEnum[phase])} with ${chalk.bold.cyan(tasks.length)} tasks`);
+    this.logger.info(`${chalk2.bold.yellow("Running")} ${this.getTaskType()} phase ${chalk2.bold.magenta(this.phaseEnum[phase])} with ${chalk2.bold.cyan(tasks.length)} tasks`);
     this.emit(`phase:${phase}:start`);
     const results = await this.executeTasksInPhase(phase, tasks);
     const failures = results.filter((r) => r.status === "rejected").length;
     if (failures > 0) {
-      const errorMessage = `Phase ${chalk.bold.magenta(this.phaseEnum[phase])} completed with ${chalk.bold.red(failures)} failed tasks`;
-      throw new Error(errorMessage);
+      throw new SeedcordError(SeedcordErrorCode.LifecyclePhaseFailures, [
+        chalk2.bold.magenta(this.phaseEnum[phase]),
+        failures
+      ]);
     } else {
-      this.logger.info(`Phase ${chalk.bold.magenta(this.phaseEnum[phase])} ${chalk.bold.green("completed successfully")}`);
+      this.logger.info(`Phase ${chalk2.bold.magenta(this.phaseEnum[phase])} ${chalk2.bold.green("completed successfully")}`);
     }
     this.emit(`phase:${phase}:complete`);
   }
@@ -318,19 +550,22 @@ var CoordinatedLifecycle = class {
    * Run a single task with timeout
    */
   async runTaskWithTimeout(phase, task) {
-    this.logger.info(`${chalk.italic("Starting")} task ${chalk.bold.cyan(task.name)} in phase ${chalk.bold.magenta(this.phaseEnum[phase])}`);
+    this.logger.info(`${chalk2.italic("Starting")} task ${chalk2.bold.cyan(task.name)} in phase ${chalk2.bold.magenta(this.phaseEnum[phase])}`);
     try {
       await Promise.race([
         task.task(),
         new Promise((_, reject) => {
           setTimeout(() => {
-            reject(new Error(`Task '${task.name}' timed out after ${task.timeout}ms`));
+            reject(new SeedcordError(SeedcordErrorCode.LifecycleTaskTimeout, [
+              task.name,
+              task.timeout
+            ]));
           }, task.timeout);
         })
       ]);
-      this.logger.info(`${chalk.italic("Completed")} task ${chalk.bold.cyan(task.name)} in phase ${chalk.bold.magenta(this.phaseEnum[phase])}`);
+      this.logger.info(`${chalk2.italic("Completed")} task ${chalk2.bold.cyan(task.name)} in phase ${chalk2.bold.magenta(this.phaseEnum[phase])}`);
     } catch (error) {
-      this.logger.error(`${chalk.italic("Failed")} task ${chalk.bold.cyan(task.name)} in phase ${chalk.bold.magenta(this.phaseEnum[phase])}:`, error);
+      this.logger.error(`${chalk2.italic("Failed")} task ${chalk2.bold.cyan(task.name)} in phase ${chalk2.bold.magenta(this.phaseEnum[phase])}:`, error);
       throw error;
     }
   }
@@ -418,11 +653,11 @@ var CoordinatedShutdown = class extends CoordinatedLifecycle {
   registerSignalHandlers() {
     if (!this.isShutdownEnabled) return;
     process.on("SIGTERM", () => {
-      this.logger.info(`Received ${chalk.yellow.bold("SIGTERM")} signal`);
+      this.logger.info(`Received ${chalk2.yellow.bold("SIGTERM")} signal`);
       void this.run(0);
     });
     process.on("SIGINT", () => {
-      this.logger.info(`Received ${chalk.yellow.bold("SIGINT")} signal`);
+      this.logger.info(`Received ${chalk2.yellow.bold("SIGINT")} signal`);
       void this.run(0);
     });
   }
@@ -469,19 +704,19 @@ var CoordinatedShutdown = class extends CoordinatedLifecycle {
     }
     this.isShuttingDown = true;
     this.exitCode = exitCode;
-    this.logger.info(`${chalk.bold.yellow("Starting")} coordinated shutdown with exit code ${chalk.bold.cyan(exitCode)}`);
+    this.logger.info(`${chalk2.bold.yellow("Starting")} coordinated shutdown with exit code ${chalk2.bold.cyan(exitCode)}`);
     this.emit("shutdown:start");
     try {
       for (const phase of PHASE_ORDER) {
         await this.runPhase(phase);
       }
-      this.logger.info(`${chalk.bold.green("Coordinated shutdown completed")} successfully`);
+      this.logger.info(`${chalk2.bold.green("Coordinated shutdown completed")} successfully`);
       this.emit("shutdown:complete");
     } catch (error) {
-      this.logger.error(`${chalk.bold.red("Coordinated shutdown failed")}`);
+      this.logger.error(`${chalk2.bold.red("Coordinated shutdown failed")}`);
       this.emit("shutdown:error", error);
     } finally {
-      this.logger.info(`${chalk.bold.red("Exiting")} process with code ${chalk.bold.cyan(this.exitCode)}`);
+      this.logger.info(`${chalk2.bold.red("Exiting")} process with code ${chalk2.bold.cyan(this.exitCode)}`);
       setTimeout(() => {
         process.exit(this.exitCode);
       }, LOG_FLUSH_DELAY_MS);
@@ -557,7 +792,7 @@ var HealthCheck = class {
       this.server.on("error", reject);
       this.server.once("listening", () => {
         const address = this.host ?? "localhost";
-        this.logger.info(`${chalk.green.bold("\u2713")} Health check server listening on ${chalk.cyan(`http://${address}:${this.port}${this.path}`)}`);
+        this.logger.info(`${chalk2.green.bold("\u2713")} Health check server listening on ${chalk2.cyan(`http://${address}:${this.port}${this.path}`)}`);
         resolve();
       });
       if (this.host) {
@@ -580,7 +815,7 @@ var HealthCheck = class {
       return new Promise((resolve) => {
         server.once("close", () => resolve());
         server.close(() => {
-          this.logger.info(chalk.bold.red("Health check server stopped"));
+          this.logger.info(chalk2.bold.red("Health check server stopped"));
         });
       });
     }
@@ -603,70 +838,136 @@ _ts_decorate2([
   Envapt("HEALTH_CHECK_HOST"),
   _ts_metadata2("design:type", Object)
 ], HealthCheck.prototype, "host", void 0);
-var CooldownManager = class {
+var StrictEventEmitter = class extends EventEmitter {
   static {
-    __name(this, "CooldownManager");
+    __name(this, "StrictEventEmitter");
   }
-  window;
-  Err;
-  msg;
-  map = /* @__PURE__ */ new Map();
   /**
-   * Creates a new CooldownManager instance.
+   * Registers a persistent listener with tuple-safe arguments for the given event.
    *
-   * @param opts - Configuration options for the cooldown behavior
+   * @param event - The event name to attach to
+   * @param listener - Callback operating on the typed argument tuple for the event
+   * @returns This emitter instance for chaining
    */
-  constructor(opts = {}) {
-    this.window = opts.cooldown ?? 1e3;
-    this.Err = opts.err ?? Error;
-    this.msg = opts.message ?? "Cooldown active";
+  on(event, listener) {
+    return super.on(event, listener);
   }
   /**
-   * Records usage timestamp for a key without any cooldown checks.
+   * Registers a one time listener that is removed after the first invocation.
    *
-   * @param key - The unique identifier for the cooldown entry
+   * @param event - The event name to attach to
+   * @param listener - Callback operating on the typed argument tuple for the event
+   * @returns This emitter instance for chaining
    */
-  set(key) {
-    this.map.set(key, Date.now());
+  once(event, listener) {
+    return super.once(event, listener);
   }
   /**
-   * Verifies cooldown status for a key and updates timestamp if not active.
+   * Removes a previously registered listener for the given event.
    *
-   * If the cooldown is still active, throws the configured error.
-   * If not active, updates the timestamp and returns successfully.
+   * @param event - The event name whose listener should be removed
+   * @param listener - Callback originally registered for the event
+   * @returns This emitter instance for chaining
+   */
+  off(event, listener) {
+    return super.off(event, listener);
+  }
+  /**
+   * Alias of {@link StrictEventEmitter.on} for compatibility with Node.js EventEmitter APIs.
    *
-   * @param key - The unique identifier to check cooldown for
-   * @throws An {@link Err} When the cooldown is still active for the given key
+   * @param event - The event name to attach to
+   * @param listener - Callback operating on the typed argument tuple for the event
+   * @returns This emitter instance for chaining
    */
-  check(key) {
-    const now = Date.now();
-    const last = this.map.get(key);
-    const remaining = this.window - (now - (last ?? 0));
-    if (Envapter.isDevelopment && remaining > 0) {
-      Logger.Debug("CooldownManager", `${key} - ${remaining}ms remaining`);
-    }
-    if (last !== void 0 && remaining > 0) {
-      throw new this.Err(this.msg, remaining);
-    }
-    this.map.set(key, now);
+  addListener(event, listener) {
+    return this.on(event, listener);
   }
   /**
-   * Checks if a key is currently cooling down without updating timestamp.
+   * Alias of {@link StrictEventEmitter.off} for compatibility with Node.js EventEmitter APIs.
    *
-   * @param key - The unique identifier to check
-   * @returns True if the key is still cooling down, false otherwise
+   * @param event - The event name whose listener should be removed
+   * @param listener - Callback originally registered for the event
+   * @returns This emitter instance for chaining
    */
-  isActive(key) {
-    const last = this.map.get(key);
-    return last !== void 0 && Date.now() - last < this.window;
+  removeListener(event, listener) {
+    return super.removeListener(event, listener);
   }
   /**
-   * Removes a key from the cooldown map.
+   * Emits an event with the strictly typed argument tuple for the event name.
    *
-   * @param key - The unique identifier to remove (useful for manual resets)
+   * @param event - The event name to emit
+   * @param args - Tuple payload for the event
+   * @returns True when the event had listeners, false otherwise
    */
-  clear(key) {
-    this.map.delete(key);
+  emit(event, ...args) {
+    return super.emit(event, ...args);
+  }
+  /**
+   * Retrieves the listener list for a given event with the correct tuple signature.
+   *
+   * @param event - The event name to inspect
+   * @returns Array of listeners registered for the event
+   */
+  listeners(event) {
+    return super.listeners(event);
+  }
+  /**
+   * Counts listeners for an event without widening the return type of {@link EventEmitter.listenerCount}.
+   *
+   * @param event - The event name to inspect
+   * @returns The total number of listeners registered for the event
+   */
+  listenerCountTyped(event) {
+    return super.listenerCount(event);
+  }
+  /**
+   * Returns the list of event names known to the emitter with the mapped key type.
+   *
+   * @returns Array of event keys supported by the emitter
+   */
+  eventNamesTyped() {
+    return super.eventNames();
+  }
+  /**
+   * Waits for an event to be emitted, resolving with the listener arguments tuple once triggered.
+   * Supports optional abort signals and timeouts for cancellation semantics.
+   *
+   * @param event - The event name to wait for
+   * @param opts - Optional abort signal or timeout in milliseconds
+   * @returns Promise resolving with the emitted argument tuple; rejects when aborted or timed out
+   */
+  waitFor(event, opts) {
+    return new Promise((resolve, reject) => {
+      const onEvent = /* @__PURE__ */ __name((...args) => {
+        cleanup();
+        resolve(args);
+      }, "onEvent");
+      const onAbort = /* @__PURE__ */ __name(() => {
+        cleanup();
+        reject(Object.assign(new Error("Aborted"), {
+          name: "AbortError"
+        }));
+      }, "onAbort");
+      let timeoutId = null;
+      const cleanup = /* @__PURE__ */ __name(() => {
+        this.off(event, onEvent);
+        opts?.signal?.removeEventListener("abort", onAbort);
+        if (timeoutId) clearTimeout(timeoutId);
+      }, "cleanup");
+      this.once(event, onEvent);
+      if (opts?.signal) {
+        if (opts.signal.aborted) return onAbort();
+        opts.signal.addEventListener("abort", onAbort, {
+          once: true
+        });
+      }
+      if (opts?.timeoutMs !== void 0) {
+        timeoutId = setTimeout(() => {
+          cleanup();
+          reject(new Error("Timed out"));
+        }, opts.timeoutMs);
+      }
+    });
   }
 };
 var StartupPhase = /* @__PURE__ */ (function(StartupPhase2) {
@@ -710,16 +1011,16 @@ var CoordinatedStartup = class extends CoordinatedLifecycle {
   }
   canAddTask() {
     if (this.hasStarted) {
-      throw new Error("Cannot add tasks after startup sequence has already completed");
+      throw new SeedcordError(SeedcordErrorCode.LifecycleAddAfterCompletion);
     }
     if (this.isStartingUp) {
-      throw new Error("Cannot add tasks while startup sequence is in progress");
+      throw new SeedcordError(SeedcordErrorCode.LifecycleAddDuringRun);
     }
     return true;
   }
   canRemoveTask() {
     if (this.isStartingUp) {
-      throw new Error("Cannot remove tasks while startup sequence is in progress");
+      throw new SeedcordError(SeedcordErrorCode.LifecycleRemoveDuringRun);
     }
     return true;
   }
@@ -769,15 +1070,15 @@ var CoordinatedStartup = class extends CoordinatedLifecycle {
       return;
     }
     this.isStartingUp = true;
-    this.logger.info(`${chalk.bold.green("Starting")} coordinated startup sequence`);
+    this.logger.info(`${chalk2.bold.green("Starting")} coordinated startup sequence`);
     this.emit("startup:start");
     try {
       for (const phase of PHASE_ORDER2) await this.runPhase(phase);
       this.hasStarted = true;
-      this.logger.info(`${chalk.bold.green("Coordinated startup completed")} successfully`);
+      this.logger.info(`${chalk2.bold.green("Coordinated startup completed")} successfully`);
       this.emit("startup:complete");
     } catch (error) {
-      this.logger.error(`${chalk.bold.red("Coordinated startup failed")}`);
+      this.logger.error(`${chalk2.bold.red("Coordinated startup failed")}`);
       this.emit("startup:error", error);
       throw error;
     } finally {
@@ -810,6 +1111,6 @@ var CoordinatedStartup = class extends CoordinatedLifecycle {
   }
 };
 
-export { CooldownManager, CoordinatedLifecycle, CoordinatedShutdown, CoordinatedStartup, HealthCheck, Logger, ShutdownPhase, StartupPhase };
+export { CooldownManager, CoordinatedLifecycle, CoordinatedShutdown, CoordinatedStartup, HealthCheck, Logger, SeedcordError, SeedcordErrorCode, SeedcordErrors, SeedcordRangeError, SeedcordTypeError, ShutdownPhase, StartupPhase, StrictEventEmitter, formatSeedcordErrorMessage, isSeedcordError, messages as seedcordErrorMessages };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map