seedcord 0.1.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,824 @@
+import { ClientOptions, Guild, User, Client, ChatInputCommandInteraction, ButtonInteraction, ModalSubmitInteraction, AutocompleteInteraction, AnySelectMenuInteraction, ContextMenuCommandInteraction, ClientEvents, Events, AutocompleteFocusedOption, SlashCommandBuilder, EmbedBuilder, ButtonBuilder, StringSelectMenuBuilder, StringSelectMenuOptionBuilder, UserSelectMenuBuilder, ChannelSelectMenuBuilder, MentionableSelectMenuBuilder, RoleSelectMenuBuilder, ModalBuilder, SlashCommandSubcommandBuilder, SlashCommandSubcommandGroupBuilder, ContextMenuCommandBuilder, ActionRowBuilder, TextInputBuilder, ColorResolvable, WebhookClient } from 'discord.js';
+import { Nullish, LifecycleTask, PhaseEvents, UnionToTuple, Tail, TypedConstructor, ConstructorFunction, IDocument } from '@seedcord/types';
+import { UUID } from 'crypto';
+import { EventEmitter } from 'node:events';
+import mongoose from 'mongoose';
+import { Envapter } from 'envapt';
+import * as fs from 'node:fs';
+
+/**
+ * Discord interaction hooks configuration
+ */
+interface InteractionsConfig {
+    /**
+     * Path for interaction hooks, such as slash commands and buttons.
+     */
+    path: string;
+}
+/**
+ * Discord event hooks configuration
+ */
+interface EventsConfig {
+    /**
+     * Path for event hooks.
+     */
+    path: string;
+}
+/**
+ * Discord command registry configuration
+ */
+interface CommandsConfig {
+    /**
+     * Path for command hooks.
+     */
+    path: string;
+}
+/**
+ * Discord hook hooks configuration
+ */
+interface HooksConfig {
+    /**
+     * Path for hook hooks.
+     */
+    path: string;
+}
+/**
+ * Discord bot configuration
+ */
+interface BotConfig {
+    interactions: InteractionsConfig;
+    events: EventsConfig;
+    commands: CommandsConfig;
+    /**
+     * Discord.js ClientOptions passed directly to the Client constructor
+     */
+    clientOptions: ClientOptions;
+    /**
+     * Optional emoji mappings for the bot
+     */
+    emojis?: Record<string, string>;
+}
+interface Config {
+    bot: BotConfig;
+    hooks: HooksConfig;
+}
+
+declare class Logger {
+    private logger;
+    private static readonly instances;
+    private static instance;
+    constructor(transportName: string);
+    private getFormatCustomizations;
+    private createConsoleTransport;
+    private initializeLogger;
+    error(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    info(msg: string, ...args: unknown[]): void;
+    http(msg: string, ...args: unknown[]): void;
+    verbose(msg: string, ...args: unknown[]): void;
+    debug(msg: string, ...args: unknown[]): void;
+    silly(msg: string, ...args: unknown[]): void;
+    static Error(prefix: string, msg: string, ...args: unknown[]): void;
+    static Info(prefix: string, msg: string, ...args: unknown[]): void;
+    static Warn(prefix: string, msg: string, ...args: unknown[]): void;
+    static Debug(prefix: string, msg: string, ...args: unknown[]): void;
+    static Silly(prefix: string, msg: string, ...args: unknown[]): void;
+}
+
+interface DefaultHooks {
+    unknownException: {
+        uuid: UUID;
+        error: Error;
+        guild: Nullish<Guild>;
+        user: Nullish<User>;
+    };
+}
+interface Hooks {
+}
+interface AllHooks extends DefaultHooks, Hooks {
+}
+type HookKeys = keyof AllHooks;
+type HookParams<KeyOfHooks extends HookKeys> = AllHooks[KeyOfHooks];
+
+declare class HookController extends Plugin {
+    protected core: Core;
+    readonly logger: Logger;
+    private isInitialized;
+    private readonly hookMap;
+    private readonly emitter;
+    constructor(core: Core);
+    init(): Promise<void>;
+    private loadHooks;
+    private registerHook;
+    private isHookHandler;
+    private attachHooks;
+    emit<KeyOfHooks extends HookKeys>(event: KeyOfHooks, data: AllHooks[KeyOfHooks]): boolean;
+}
+
+/**
+ * Abstract base class for coordinated lifecycle management (startup/shutdown)
+ */
+declare abstract class CoordinatedLifecycle<TPhase extends number> {
+    protected readonly phaseOrder: TPhase[];
+    protected readonly phaseEnum: Record<number, string>;
+    protected readonly logger: Logger;
+    protected readonly events: EventEmitter<[never]>;
+    protected readonly tasksMap: Map<TPhase, LifecycleTask[]>;
+    protected constructor(loggerName: string, phaseOrder: TPhase[], phaseEnum: Record<number, string>);
+    /**
+     * Add a task to a specific phase
+     */
+    addTask(phase: TPhase, taskName: string, task: () => Promise<void>, timeoutMs: number): void;
+    /**
+     * Remove a task by name from a specific phase
+     */
+    removeTask(phase: TPhase, taskName: string): boolean;
+    /**
+     * Run all tasks in a specific phase
+     */
+    protected runPhase(phase: TPhase): Promise<void>;
+    /**
+     * Run a single task with timeout
+     */
+    protected runTaskWithTimeout(phase: TPhase, task: LifecycleTask): Promise<void>;
+    /**
+     * Subscribe to lifecycle events
+     */
+    on(event: string, listener: (...args: unknown[]) => void): void;
+    /**
+     * Unsubscribe from lifecycle events
+     */
+    off(event: string, listener: (...args: unknown[]) => void): void;
+    protected emit(event: string, ...args: unknown[]): boolean;
+    protected abstract canAddTask(): boolean;
+    protected abstract canRemoveTask(): boolean;
+    protected abstract getTaskType(): string;
+    protected abstract executeTasksInPhase(phase: TPhase, tasks: LifecycleTask[]): Promise<PromiseSettledResult<void>[]>;
+}
+
+/**
+ * Shutdown phases for coordinated application shutdown.
+ */
+declare enum ShutdownPhase {
+    /** Stop accepting new requests/interactions */
+    StopAcceptingRequests = 1,
+    /** Stop background services (health checks, etc.) */
+    StopServices = 2,
+    /** Disconnect from external resources (database, APIs) */
+    ExternalResources = 3,
+    /** Disconnect from Discord */
+    DiscordCleanup = 4,
+    /** Final cleanup tasks */
+    FinalCleanup = 5
+}
+type CoordinatedShutdownEventKey = PhaseEvents<'shutdown', UnionToTuple<ShutdownPhase>>;
+interface ShutdownTask extends LifecycleTask {
+}
+declare class CoordinatedShutdown extends CoordinatedLifecycle<ShutdownPhase> {
+    private isShuttingDown;
+    private exitCode;
+    constructor();
+    protected canAddTask(): boolean;
+    protected canRemoveTask(): boolean;
+    protected getTaskType(): string;
+    protected executeTasksInPhase(phase: ShutdownPhase, tasks: LifecycleTask[]): Promise<PromiseSettledResult<void>[]>;
+    private registerSignalHandlers;
+    /**
+     * Add a task to a specific shutdown phase
+     */
+    addTask(phase: ShutdownPhase, taskName: string, task: () => Promise<void>, timeoutMs?: number): void;
+    /**
+     * Remove a task by name from a specific phase
+     */
+    removeTask(phase: ShutdownPhase, taskName: string): boolean;
+    /**
+     * Start the coordinated shutdown sequence
+     */
+    run(exitCode?: number): Promise<void>;
+    /**
+     * Subscribe to shutdown events
+     */
+    on(event: CoordinatedShutdownEventKey, listener: (...args: unknown[]) => void): void;
+    /**
+     * Unsubscribe from shutdown events
+     */
+    off(event: CoordinatedShutdownEventKey, listener: (...args: unknown[]) => void): void;
+}
+
+/**
+ * Startup phases for coordinated plugin initialization.
+ */
+declare enum StartupPhase {
+    /** Validate environment variables and config files */
+    Validation = 1,
+    /** Discover plugin constructors via decorators or registry */
+    Discovery = 2,
+    /** Register plugin metadata and declared dependencies */
+    Registration = 3,
+    /** Inject and validate plugin-specific configuration */
+    Configuration = 4,
+    /** Instantiate plugin classes with Core and arguments */
+    Instantiation = 5,
+    /** Activate plugins by calling their init/setup hooks */
+    Activation = 6,
+    /** Mark seedcord as ready and start handling interactions */
+    Ready = 7
+}
+type CoordinatedStartupEventKey = PhaseEvents<'startup', UnionToTuple<StartupPhase>>;
+interface StartupTask extends LifecycleTask {
+}
+declare class CoordinatedStartup extends CoordinatedLifecycle<StartupPhase> {
+    private isStartingUp;
+    private hasStarted;
+    constructor();
+    /**
+     * Add a task to a specific startup phase
+     */
+    addTask(phase: StartupPhase, taskName: string, task: () => Promise<void>, timeoutMs?: number): void;
+    protected canAddTask(): boolean;
+    protected canRemoveTask(): boolean;
+    protected getTaskType(): string;
+    protected executeTasksInPhase(phase: StartupPhase, tasks: LifecycleTask[]): Promise<PromiseSettledResult<void>[]>;
+    /**
+     * Start the coordinated startup sequence
+     */
+    run(): Promise<void>;
+    /**
+     * Subscribe to startup events
+     */
+    on(event: CoordinatedStartupEventKey, listener: (...args: unknown[]) => void): void;
+    /**
+     * Unsubscribe from startup events
+     */
+    off(event: CoordinatedStartupEventKey, listener: (...args: unknown[]) => void): void;
+    /**
+     * Check if startup has completed
+     */
+    get isReady(): boolean;
+    /**
+     * Check if startup is currently running
+     */
+    get isRunning(): boolean;
+}
+
+interface BaseCore {
+    readonly bot: Bot;
+    readonly hooks: HookController;
+    readonly shutdown: CoordinatedShutdown;
+    readonly startup: CoordinatedStartup;
+    readonly config: Config;
+    start(): Promise<this>;
+}
+interface Core extends BaseCore {
+}
+
+interface Initializeable {
+    init(): Promise<void>;
+}
+declare abstract class Plugin implements Initializeable {
+    protected pluggable: Core;
+    abstract logger: Logger;
+    constructor(pluggable: Core);
+    abstract init(): Promise<void>;
+}
+/** A plugin constructor can accept any tail of args after Core */
+type PluginCtor<TPlugin extends Plugin = Plugin> = new (core: Core, ...args: any[]) => TPlugin;
+/** Convenience: the argument list a given constructor expects */
+type PluginArgs<Ctor extends PluginCtor> = Tail<ConstructorParameters<Ctor>>;
+declare class Pluggable {
+    protected isInitialized: boolean;
+    protected readonly shutdown: CoordinatedShutdown;
+    protected readonly startup: CoordinatedStartup;
+    private static readonly PLUGIN_INIT_TIMEOUT_MS;
+    constructor(shutdown: CoordinatedShutdown, startup: CoordinatedStartup);
+    protected init(): Promise<this>;
+    attach<Key extends string, Ctor extends PluginCtor>(this: this, key: Key, Plugin: Ctor, startupPhase: StartupPhase, ...args: PluginArgs<Ctor>): this & Record<Key, InstanceType<Ctor>>;
+}
+
+declare class Bot extends Plugin {
+    protected core: Core;
+    readonly logger: Logger;
+    private isInitialized;
+    private readonly _client;
+    private readonly interactions;
+    private readonly events;
+    private readonly commands;
+    private readonly emojiInjector;
+    constructor(core: Core);
+    init(): Promise<void>;
+    stop(): Promise<void>;
+    private login;
+    private logout;
+    get client(): Client;
+}
+
+declare class Seedcord extends Pluggable implements Core {
+    readonly config: Config;
+    private static isInstantiated;
+    readonly shutdown: CoordinatedShutdown;
+    readonly startup: CoordinatedStartup;
+    readonly hooks: HookController;
+    readonly bot: Bot;
+    private readonly healthCheck;
+    constructor(config: Config);
+    private registerStartupTasks;
+    start(): Promise<this>;
+}
+interface Seedcord extends Core {
+}
+
+type ValidInteractionTypes = ChatInputCommandInteraction | ButtonInteraction | ModalSubmitInteraction | AutocompleteInteraction | AnySelectMenuInteraction | ContextMenuCommandInteraction;
+type ValidNonInteractionTypes = ClientEvents[Exclude<keyof ClientEvents, Events.InteractionCreate>];
+type ValidEventTypes = ValidInteractionTypes | ValidNonInteractionTypes;
+type Repliables = Exclude<ValidInteractionTypes, AutocompleteInteraction>;
+type RepliableInteractionHandler = InteractionHandler<Repliables> | InteractionMiddleware<Repliables>;
+interface Handler {
+    execute(): Promise<void>;
+}
+interface WithChecks {
+    runChecks(): Promise<void>;
+}
+interface HandlerWithChecks extends WithChecks, Handler {
+}
+declare abstract class BaseHandler<ValidEvent extends ValidEventTypes> implements Handler {
+    core: Core;
+    protected checkable: boolean;
+    protected break: boolean;
+    protected errored: boolean;
+    protected event: ValidEvent;
+    protected args: string[];
+    protected constructor(event: ValidEvent, core: Core, args?: string[]);
+    abstract execute(): Promise<void>;
+    hasChecks(): this is HandlerWithChecks;
+    hasErrors(): boolean;
+    setErrored(): void;
+    shouldBreak(): boolean;
+    getEvent(): ValidEvent;
+    /**
+     * Get the arguments passed from the customId
+     * For example, if customId is "accept:user123-guild456", args will be ["user123", "guild456"]
+     */
+    protected getArgs(): string[];
+    /**
+     * Get a specific argument by index
+     */
+    protected getArg(index: number): string | undefined;
+}
+/**
+ * All interactions with the bot including Handlers and what those hooks do or pass to other services should extend this class.
+ * This class implements ICheckable when the decorator Checkable is used on the class.
+ * @implements Handler
+ * @template Repliable - A type that extends one of the ValidEventTypes. Can add more types to the ValidEventTypes union type if needed.
+ */
+declare abstract class InteractionHandler<Repliable extends Repliables> extends BaseHandler<Repliable> implements Handler {
+    constructor(event: Repliable, core: Core, args?: string[]);
+}
+declare abstract class InteractionMiddleware<Repliable extends Repliables> extends BaseHandler<Repliable> implements Handler {
+    constructor(event: Repliable, core: Core, args?: string[]);
+}
+/**
+ * Autocomplete interactions handler - separate from repliable interactions
+ */
+declare abstract class AutocompleteHandler extends BaseHandler<AutocompleteInteraction> implements Handler {
+    protected readonly focused: AutocompleteFocusedOption;
+    constructor(event: AutocompleteInteraction, core: Core, args?: string[]);
+}
+/**
+ * All non-interaction events with the bot including Handlers and what those hooks do or pass to other services should extend this class.
+ * This class implements ICheckable when the decorator Checkable is used on the class.
+ * @implements Handler
+ * @template Repliable - A type that extends one of the ValidEventTypes. Can add more types to the ValidEventTypes union type if needed.
+ */
+declare abstract class EventHandler<Repliable extends keyof ClientEvents> extends BaseHandler<ClientEvents[Repliable]> implements Handler {
+    constructor(event: ClientEvents[Repliable], core: Core, args?: string[]);
+}
+type HandlerConstructor = TypedConstructor<typeof InteractionHandler | typeof AutocompleteHandler>;
+type MiddlewareConstructor = TypedConstructor<typeof InteractionMiddleware> & (new (event: Repliables, core: Core, args?: string[]) => InteractionMiddleware<Repliables>);
+type AutocompleteHandlerConstructor = TypedConstructor<typeof AutocompleteHandler> & (new (event: AutocompleteInteraction, core: Core, args?: string[]) => AutocompleteHandler);
+type EventHandlerConstructor = TypedConstructor<typeof EventHandler>;
+
+type HandlerCtor = new (...args: any[]) => Handler;
+declare function Checkable<TypeHandler extends HandlerCtor>(ctor: TypeHandler): TypeHandler;
+
+interface CatchableOptions {
+    log?: boolean;
+    forceFollowup?: boolean;
+}
+declare function Catchable(options?: CatchableOptions): (_target: RepliableInteractionHandler, _propertyKey: string, descriptor: TypedPropertyDescriptor<(...args: any[]) => Promise<void>>) => void;
+
+declare const BuilderTypes: {
+    command: typeof SlashCommandBuilder;
+    embed: typeof EmbedBuilder;
+    button: typeof ButtonBuilder;
+    menu_string: typeof StringSelectMenuBuilder;
+    menu_option_string: typeof StringSelectMenuOptionBuilder;
+    menu_user: typeof UserSelectMenuBuilder;
+    menu_channel: typeof ChannelSelectMenuBuilder;
+    menu_mentionable: typeof MentionableSelectMenuBuilder;
+    menu_role: typeof RoleSelectMenuBuilder;
+    modal: typeof ModalBuilder;
+    subcommand: typeof SlashCommandSubcommandBuilder;
+    group: typeof SlashCommandSubcommandGroupBuilder;
+    context_menu: typeof ContextMenuCommandBuilder;
+};
+declare const RowTypes: {
+    button: typeof ActionRowBuilder<ButtonBuilder>;
+    menu_string: typeof ActionRowBuilder<StringSelectMenuBuilder>;
+    menu_user: typeof ActionRowBuilder<UserSelectMenuBuilder>;
+    menu_channel: typeof ActionRowBuilder<ChannelSelectMenuBuilder>;
+    menu_mentionable: typeof ActionRowBuilder<MentionableSelectMenuBuilder>;
+    menu_role: typeof ActionRowBuilder<RoleSelectMenuBuilder>;
+    modal: typeof ActionRowBuilder<ModalActionRowComponentBuilder>;
+};
+declare const ModalTypes: {
+    text: typeof TextInputBuilder;
+};
+type BuilderType = keyof typeof BuilderTypes;
+type InstantiatedBuilder<BuilderKey extends BuilderType> = InstanceType<(typeof BuilderTypes)[BuilderKey]>;
+type ActionRowComponentType = keyof typeof RowTypes;
+type InstantiatedActionRow<RowKey extends ActionRowComponentType> = InstanceType<(typeof RowTypes)[RowKey]>;
+type ModalFieldTypes = keyof typeof ModalTypes;
+type InstantiatedModalField<ModalKey extends ModalFieldTypes> = InstanceType<(typeof ModalTypes)[ModalKey]>;
+declare abstract class BaseComponent<TComponent> {
+    private readonly _component;
+    protected constructor(ComponentClass: new () => TComponent);
+    /**
+     * @description Returns the configured component
+     * @note Do not use for mutating using setters.
+     * @see instance for mutating the component
+     * @usage `new SomeComponent().component`
+     */
+    abstract get component(): InstantiatedBuilder<BuilderType> | InstantiatedActionRow<ActionRowComponentType>;
+    /**
+     * @description Returns the instantiated component
+     * @note Use this for configuring the component using its instance setters.
+     * @usage `this.instance.someMethod()`
+     */
+    protected get instance(): TComponent;
+}
+declare abstract class BuilderComponent<BuilderKey extends BuilderType> extends BaseComponent<InstantiatedBuilder<BuilderKey>> {
+    protected constructor(type: BuilderKey);
+    get component(): InstantiatedBuilder<BuilderKey>;
+    buildCustomId(prefix: string, ...args: string[]): string;
+}
+declare abstract class RowComponent<RowKey extends ActionRowComponentType> extends BaseComponent<InstantiatedActionRow<RowKey>> {
+    protected constructor(type: RowKey);
+    get component(): InstantiatedActionRow<RowKey>;
+}
+declare abstract class ModalComponent<ModalKey extends ModalFieldTypes> extends BaseComponent<InstantiatedModalField<ModalKey>> {
+    protected constructor(type: ModalKey);
+    get component(): InstantiatedActionRow<'modal'>;
+}
+declare class BaseErrorEmbed extends BuilderComponent<'embed'> {
+    constructor();
+}
+declare abstract class CustomError extends Error {
+    message: string;
+    protected _emit: boolean;
+    readonly response: EmbedBuilder;
+    protected constructor(message: string);
+    get emit(): boolean;
+}
+type CustomErrorConstructor = new (message: string, ...args: any[]) => CustomError;
+
+declare const CommandMetadataKey: unique symbol;
+type CommandCtor = new (...args: any[]) => BuilderComponent<'command' | 'context_menu'>;
+interface GlobalMeta {
+    scope: 'global';
+}
+interface GuildMeta {
+    scope: 'guild';
+    guilds: string[];
+}
+type CommandMeta = GlobalMeta | GuildMeta;
+declare function RegisterCommand(scope: 'global'): (ctor: CommandCtor) => void;
+declare function RegisterCommand(scope: 'guild', guilds: string[]): (ctor: CommandCtor) => void;
+
+declare function EventCatchable(log?: boolean): (_target: EventHandler<keyof ClientEvents>, _prop: string, descriptor: TypedPropertyDescriptor<(...args: any[]) => Promise<void>>) => void;
+
+declare const EventMetadataKey: unique symbol;
+declare function RegisterEvent<KeyofEvents extends keyof ClientEvents>(eventName: KeyofEvents): (constructor: ConstructorFunction) => void;
+
+declare enum InteractionRoutes {
+    Slash = "interaction:slash",
+    Button = "interaction:button",
+    Modal = "interaction:modal",
+    StringMenu = "interaction:stringMenu",
+    UserMenu = "interaction:userMenu",
+    RoleMenu = "interaction:roleMenu",
+    ChannelMenu = "interaction:channelMenu",
+    MentionableMenu = "interaction:mentionableMenu",
+    MessageContextMenu = "interaction:messageContextMenu",
+    UserContextMenu = "interaction:userContextMenu",
+    Autocomplete = "interaction:autocomplete"
+}
+declare enum SelectMenuType {
+    String = "string",
+    User = "user",
+    Role = "role",
+    Channel = "channel",
+    Mentionable = "mentionable"
+}
+declare const InteractionMetadataKey: unique symbol;
+/**
+ * Decorator for slash command routes. The route can be:
+ *  - "profile"
+ *  - "settings/edit"
+ *  - "settings/advanced/edit"
+ *
+ * Pass an array of routes if the same handler should respond to multiple.
+ */
+declare function SlashRoute(routeOrRoutes: string | string[]): (constructor: ConstructorFunction) => void;
+/**
+ * Decorator for button routes. This should match a `customId` prefix.
+ * e.g., 'accept' or 'login'.
+ */
+declare function ButtonRoute(routeOrRoutes: string | string[]): (constructor: ConstructorFunction) => void;
+/**
+ * Decorator for modal routes. This should match a `customId` prefix.
+ */
+declare function ModalRoute(routeOrRoutes: string | string[]): (constructor: ConstructorFunction) => void;
+/**
+ * Decorator for context menu commands. This should match the command name.
+ * @param type - The type of context menu ('message' or 'user')
+ * @param routeOrRoutes - The command name(s) to route to this handler
+ */
+declare function ContextMenuRoute(type: 'message' | 'user', routeOrRoutes: string | string[]): (constructor: ConstructorFunction) => void;
+/**
+ * Decorator for autocomplete interactions. Supports routing by command and focused field.
+ * @param commandRoutes - Command name or subcommand paths
+ * @param focusedFields - Focused option names to handle
+ * @example @AutocompleteRoute('user', 'name') // Single command, single field
+ * @example @AutocompleteRoute(['user', 'profile'], ['name', 'bio']) // Multiple commands, multiple fields
+ */
+declare function AutocompleteRoute(commandRoutes: string | string[], focusedFields: string | string[]): (constructor: ConstructorFunction) => void;
+/**
+ * Decorator for select menu routes. This should match a `customId` prefix.
+ */
+declare function SelectMenuRoute(type: SelectMenuType, routeOrRoutes: string | string[]): (constructor: ConstructorFunction) => void;
+
+declare class HealthCheck extends Plugin {
+    private readonly core;
+    readonly logger: Logger;
+    private readonly port;
+    private readonly path;
+    private server?;
+    constructor(core: Core);
+    /**
+     * Starts the health check server.
+     * @returns Promise that resolves when the server is listening
+     */
+    init(): Promise<void>;
+    stop(): Promise<void>;
+}
+
+interface CooldownOptions {
+    cooldown?: number;
+    err?: new (msg: string, ...args: any[]) => Error;
+    message?: string;
+}
+/**
+ * Lightweight utility for per-key cooldowns
+ */
+declare class CooldownManager {
+    private readonly window;
+    private readonly Err;
+    private readonly msg;
+    private readonly map;
+    constructor(opts?: CooldownOptions);
+    /** Record usage without any checks. */
+    set(key: string): void;
+    /**
+     * Verify cooldown for `key`.\
+     * If active → throws the custom error.\
+     * If not active → updates timestamp and returns void.
+     */
+    check(key: string): void;
+    /** Returns true if the key is still cooling down (does not update timestamp). */
+    isActive(key: string): boolean;
+    /** Remove a key from the map (useful for manual resets). */
+    clear(key: string): void;
+}
+
+interface Services {
+}
+type ServiceKeys = keyof Services;
+
+interface MongoOptions {
+    servicesDir: string;
+    uri: string;
+    dbName: string;
+}
+declare class Mongo extends Plugin {
+    readonly core: Core;
+    private readonly options;
+    readonly logger: Logger;
+    private isInitialised;
+    private readonly uri;
+    /**
+     * Map of all loaded services.
+     * Keys come from `@DatabaseService('key')`
+     */
+    readonly services: Services;
+    constructor(core: Core, options: MongoOptions);
+    init(): Promise<void>;
+    stop(): Promise<void>;
+    private connect;
+    private disconnect;
+    private loadServices;
+    private isServiceClass;
+    _register<SKey extends keyof Services>(key: SKey, instance: Services[SKey]): void;
+}
+
+declare abstract class BaseService<Doc extends IDocument = IDocument> {
+    protected readonly db: Mongo;
+    protected readonly core: Core;
+    readonly model: mongoose.Model<Doc>;
+    constructor(db: Mongo, core: Core);
+}
+type BaseServiceConstructor = TypedConstructor<typeof BaseService>;
+
+declare function DBCatchable<TypeReturn>(errorMessage: string): (_target: unknown, _propertyKey: string, descriptor: TypedPropertyDescriptor<(...args: any[]) => Promise<TypeReturn>>) => void;
+
+declare const ModelMetadataKey: unique symbol;
+declare function DatabaseModel<TService extends ServiceKeys>(collection: TService): <SchemaObj extends Record<KeyOfSchema, mongoose.Schema>, KeyOfSchema extends keyof SchemaObj & (string | symbol)>(target: SchemaObj, propertyKey: KeyOfSchema) => void;
+
+declare const ServiceMetadataKey: unique symbol;
+declare function DatabaseService<TService extends ServiceKeys>(key: TService): <DatabaseCtor extends ConstructorFunction & {
+    prototype: BaseService;
+}>(ctor: DatabaseCtor) => void;
+
+/**
+ * Global configuration variables for the application. These ENV variables are reserved for the framework.
+ *
+ * Set them in your `.env` file to override the default.
+ */
+declare class Globals extends Envapter {
+    static readonly botToken: string;
+    static readonly healthCheckPort: number;
+    static readonly healthCheckPath: string;
+    static readonly shutdownIsEnabled: boolean;
+    static readonly unknownExceptionWebhookUrl: string;
+    /**
+     * The default color of the bot's embeds. Can simply override by `Globals.botColor =`
+     */
+    static botColor: ColorResolvable;
+}
+
+/**
+ * Rounds a number to a specified number of decimal places.
+ *
+ * @param num - The number to be rounded.
+ * @param decimalPlaces - The number of decimal places to round to.
+ * @returns The rounded number.
+ */
+declare function numberFixer(num: number, decimalPlaces: number): number;
+/**
+ * Takes two numbers and returns the percentage of the first number in the second number with two decimal places.
+ *
+ * @param num1 The first number.
+ * @param num2 The second number.
+ *
+ * @returns The percentage of the first number in the second number with two decimal places.
+ */
+declare function percentage(num1: number, num2: number): number;
+/**
+ * Generates an ASCII table from the provided data.
+ *
+ * @param data - The data to be displayed in the table.
+ * @returns The generated ASCII table as a string.
+ */
+declare function generateAsciiTable(data: string[][]): string;
+/**
+ * Returns the word with it's first letter capitalized and the rest in lowercase.
+ * @param word - The word to be formatted.
+ * @returns The formatted word.
+ */
+declare function formatWord(word: string): string;
+/**
+ * Function takes an array of strings or numbers and returns the number of characters in the longest string/number
+ * @param arr - The array of strings or numbers
+ */
+declare function longestStringLength(arr: (string | number)[]): number;
+/**
+ * Return current time in seconds
+ */
+declare function currentTime(): number;
+/**
+ * Returns the ordinal suffix for a given number.
+ *
+ * @param n - The number to get the ordinal for
+ * @returns The number with its ordinal suffix
+ *
+ * @example
+ * ordinal(1); // "1st"
+ * ordinal(22); // "22nd"
+ * ordinal(13); // "13th"
+ */
+declare function ordinal(n: number): string;
+/**
+ * Calculates the difference between two numbers and formats it as a string with a '+' prefix for positive differences.
+ *
+ * @param numBefore - The initial number value
+ * @param numAfter - The final number value
+ * @returns A string representing the difference, with a '+' sign for positive differences
+ *
+ * @example
+ * // Returns "+5"
+ * prettyDifference(10, 15);
+ *
+ * @example
+ * // Returns "-3"
+ * prettyDifference(10, 7);
+ */
+declare function prettyDifference(numBefore: number, numAfter: number): string;
+/**
+ * Determines if a directory entry is a TypeScript or JavaScript file.
+ *
+ * @param entry - The directory entry to check.
+ * @returns True if the entry is a file ending with .ts or .js.
+ */
+declare function isTsOrJsFile(entry: fs.Dirent): boolean;
+/**
+ * Recursively traverses through a directory, importing all .ts and .js files and applying a callback to each import.
+ *
+ * @param dir - The directory path to traverse.
+ * @param callback - A function that will be called for each imported module. It receives the full file path, the file's relative path, and the imported module as arguments.
+ * @returns A Promise that resolves when the traversal is complete.
+ */
+declare function traverseDirectory(dir: string, callback: (fullPath: string, relativePath: string, imported: Record<string, unknown>) => Promise<void> | void): Promise<void>;
+/**
+ * Throws a custom error with a formatted message and optional UUID.
+ *
+ * Wraps an unknown error in a {@link CustomError} subclass. If the error class
+ * is {@link DatabaseError}, a UUID is generated and passed to the constructor.
+ *
+ * @typeParam T - A constructor for a {@link CustomError} subclass
+ * @param error - The original error or value
+ * @param message - Custom message to include
+ * @param CustomError - Error class to instantiate and throw
+ * @throws Instance of the provided {@link CustomError} subclass
+ *
+ * @example
+ * try {
+ *   // risky code
+ * } catch (e) {
+ *   throwCustomError(e, "Something went wrong", MyCustomError);
+ * }
+ */
+declare function throwCustomError<Ctor extends CustomErrorConstructor>(error: unknown, message: string, customError: Ctor): never;
+/**
+ * Converts a camelCase or snake_case string into a human-readable format.
+ *
+ * This function inserts spaces before capital letters that follow lowercase
+ * letters, replaces underscores with spaces, and trims any extra whitespace.
+ *
+ * @param key - The string to be converted to a human-readable format
+ * @returns A prettified string with proper spacing
+ *
+ * @example
+ * prettify("camelCaseString") // returns "camel Case String"
+ * @example
+ * prettify("snake_case_string") // returns "snake case string"
+ */
+declare function prettify(key: string): string;
+/**
+ * Shuffles an array using the Fisher-Yates algorithm.
+ * This function creates a new array with the same elements in a random order,
+ * without modifying the original array.
+ *
+ * @template TArray - The type of elements in the array
+ * @param {TArray[]} items - The array to shuffle
+ * @returns {TArray[]} A new array with the same elements in a random order
+ *
+ * @example
+ * const numbers = [1, 2, 3, 4, 5];
+ * const shuffled = fyShuffle(numbers);
+ * // shuffled might be [3, 1, 5, 2, 4]
+ * // numbers is still [1, 2, 3, 4, 5]
+ */
+declare function fyShuffle<TArray>(items: TArray[]): TArray[];
+
+declare class HookEmitter {
+    private readonly emitter;
+    on<KeyOfHooks extends HookKeys>(event: KeyOfHooks, listener: (data: AllHooks[KeyOfHooks]) => void): this;
+    once<KeyOfHooks extends HookKeys>(event: KeyOfHooks, listener: (data: AllHooks[KeyOfHooks]) => void): this;
+    emit<KeyOfHooks extends HookKeys>(event: KeyOfHooks, data: AllHooks[KeyOfHooks]): boolean;
+}
+
+declare const HookMetadataKey: unique symbol;
+declare function RegisterHook<THook extends HookKeys>(hook: THook): (constructor: ConstructorFunction) => void;
+
+declare abstract class HookHandler<KeyOfHooks extends HookKeys> {
+    protected readonly data: AllHooks[KeyOfHooks];
+    protected readonly core: Core;
+    constructor(data: AllHooks[KeyOfHooks], core: Core);
+    abstract execute(): Promise<void>;
+}
+
+declare abstract class WebhookLog<KeyofHooks extends HookKeys> extends HookHandler<KeyofHooks> {
+    abstract webhook: WebhookClient;
+    constructor(data: AllHooks[KeyofHooks], core: Core);
+}
+
+export { type AllHooks, AutocompleteHandler, type AutocompleteHandlerConstructor, AutocompleteRoute, BaseErrorEmbed, BaseService, type BaseServiceConstructor, Bot, BuilderComponent, ButtonRoute, Catchable, Checkable, type CommandMeta, CommandMetadataKey, type Config, ContextMenuRoute, CooldownManager, type CooldownOptions, CoordinatedShutdown, CoordinatedStartup, type Core, CustomError, type CustomErrorConstructor, DBCatchable, DatabaseModel, DatabaseService, type DefaultHooks, EventCatchable, EventHandler, type EventHandlerConstructor, EventMetadataKey, Globals, type Handler, type HandlerConstructor, HealthCheck, HookController, HookEmitter, HookHandler, type HookKeys, HookMetadataKey, type HookParams, type Hooks, type Initializeable, InteractionHandler, InteractionMetadataKey, InteractionMiddleware, InteractionRoutes, Logger, type MiddlewareConstructor, ModalComponent, ModalRoute, ModelMetadataKey, Mongo, Pluggable, Plugin, type PluginArgs, type PluginCtor, RegisterCommand, RegisterEvent, RegisterHook, type RepliableInteractionHandler, type Repliables, RowComponent, Seedcord, SelectMenuRoute, SelectMenuType, type ServiceKeys, ServiceMetadataKey, type Services, ShutdownPhase, type ShutdownTask, SlashRoute, StartupPhase, type StartupTask, type ValidEventTypes, type ValidInteractionTypes, type ValidNonInteractionTypes, WebhookLog, type WithChecks, currentTime, formatWord, fyShuffle, generateAsciiTable, isTsOrJsFile, longestStringLength, numberFixer, ordinal, percentage, prettify, prettyDifference, throwCustomError, traverseDirectory };