seedcord 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -1,13 +1,60 @@
-import { CoordinatedShutdown, CoordinatedStartup, Logger, StartupPhase } from '@seedcord/services';
+import { SEEventMapLike, SENoEvents, StrictEventEmitter, CoordinatedShutdown, CoordinatedStartup, Logger, StartupPhase } from '@seedcord/services';
 export * from '@seedcord/services';
-import { ClientOptions, Guild, User, SlashCommandBuilder, ContextMenuCommandBuilder, Collection, Client, ChatInputCommandInteraction, ButtonInteraction, ModalSubmitInteraction, AutocompleteInteraction, AnySelectMenuInteraction, ContextMenuCommandInteraction, ClientEvents, Events, AutocompleteFocusedOption, SlashCommandSubcommandBuilder, SlashCommandSubcommandGroupBuilder, EmbedBuilder, ModalBuilder, LabelBuilder, TextInputBuilder, FileUploadBuilder, ButtonBuilder, StringSelectMenuBuilder, StringSelectMenuOptionBuilder, UserSelectMenuBuilder, ChannelSelectMenuBuilder, MentionableSelectMenuBuilder, RoleSelectMenuBuilder, ContainerBuilder, TextDisplayBuilder, FileBuilder, MediaGalleryBuilder, SectionBuilder, SeparatorBuilder, ActionRowBuilder, ColorResolvable, Interaction, Role, TextChannel, TextChannelResolvable, MessageActionRowComponentBuilder, Message, GuildMember, Snowflake, WebhookClient } from 'discord.js';
-import { Tail, Nullable, TypedConstructor, TypedExclude } from '@seedcord/types';
+import { ClientOptions, Guild, User, SlashCommandBuilder, ContextMenuCommandBuilder, Collection, ClientEvents, Interaction, Client, ChatInputCommandInteraction, ButtonInteraction, ModalSubmitInteraction, AutocompleteInteraction, AnySelectMenuInteraction, ContextMenuCommandInteraction, Events, AutocompleteFocusedOption, SlashCommandSubcommandBuilder, SlashCommandSubcommandGroupBuilder, EmbedBuilder, ModalBuilder, LabelBuilder, TextInputBuilder, FileUploadBuilder, ButtonBuilder, StringSelectMenuBuilder, StringSelectMenuOptionBuilder, UserSelectMenuBuilder, ChannelSelectMenuBuilder, MentionableSelectMenuBuilder, RoleSelectMenuBuilder, ContainerBuilder, TextDisplayBuilder, FileBuilder, MediaGalleryBuilder, SectionBuilder, SeparatorBuilder, ActionRowBuilder, ColorResolvable, MessageComponentType, ComponentType, MessageComponentInteraction, StringSelectMenuInteraction, UserSelectMenuInteraction, RoleSelectMenuInteraction, MentionableSelectMenuInteraction, ChannelSelectMenuInteraction, Role, TextChannel, TextChannelResolvable, MessageActionRowComponentBuilder, Message, GuildMember, Snowflake, WebhookClient } from 'discord.js';
+import { Tail, Nullable, TypedConstructor, TypedOmit, TypedExclude } from '@seedcord/types';
 export * from '@seedcord/types';
 import { UUID } from 'crypto';
-import { Constructor, RequireAtLeastOne } from 'type-fest';
+import { Constructor, Promisable, NonEmptyTuple, TupleOf, IntClosedRange, RequireAtLeastOne } from 'type-fest';
 import { UUID as UUID$1 } from 'node:crypto';
 export * from '@seedcord/utils';
 
+/**
+ * Emoji mapping interface. Augment this to add your project's emoji keys. Make sure to provide the same keys when configuring emojis in your bot config.
+ *
+ * @example
+ * ```ts
+ * declare module 'seedcord' {
+ *   interface EmojiMap {
+ *     ThumbsUp: string;
+ *     ThumbsDown: string;
+ *     Lol: string;
+ *     Kek: string;
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Or extend it directly
+ * declare module 'seedcord' {
+ *  export interface EmojiMap extends MyEmojiMap {}
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Then, import and use it anywhere in your app
+ * import { Emojis } from 'seedcord';
+ *
+ * console.log(Emojis.ThumbsUp); // '<:thumbsup:1872389747982323423>'
+ * ```
+ */
+interface EmojiMap {
+}
+/**
+ * Global emoji mappings object
+ *
+ * @see {@link EmojiMap}
+ */
+declare const Emojis: EmojiMap;
+declare class EmojiInjector {
+    private readonly core;
+    private readonly logger;
+    constructor(core: Core);
+    init(): Promise<void>;
+    private clearEmojis;
+}
+
 /**
  * Djs Interactions handlers
  *
@@ -17,7 +64,10 @@ interface InteractionsConfig {
      * Path to dir containing interaction handlers.
      */
     path: string;
-    ignoreCustomIds?: string[];
+    /**
+     * Optional array of custom IDs or regex patterns to ignore in interaction handling
+     */
+    ignoreCustomIds?: (string | RegExp)[];
     /**
      * Optional path to interaction middleware directory
      */
@@ -72,6 +122,9 @@ interface BotConfig {
      *
      * Value: The emoji identifier used in Discord
      *
+     * @see {@link EmojiMap}
+     * @see {@link Emojis}
+     *
      * @example
      * ```ts
      * // This map's values...
@@ -94,7 +147,7 @@ interface BotConfig {
      * };
      * ```
      */
-    emojis?: Record<string, string>;
+    emojis?: Partial<EmojiMap>;
     /**
      * Whether to show the error stack trace in the terminal in errors caught by the `@Catchable` decorator
      *
@@ -118,7 +171,7 @@ interface Initializeable {
  * Extend this class to create plugins that integrate with the Seedcord lifecycle.
  * Plugins have access to the core instance and must implement initialization logic.
  */
-declare abstract class Plugin implements Initializeable {
+declare abstract class Plugin<TPluginEvents extends SEEventMapLike<TPluginEvents> = SENoEvents> extends StrictEventEmitter<TPluginEvents> implements Initializeable {
     protected pluggable: Core;
     /** Logger instance for this plugin - must be implemented by subclasses */
     abstract logger: Logger;
@@ -145,7 +198,7 @@ type PluginArgs<Ctor extends PluginCtor> = Tail<ConstructorParameters<Ctor>>;
  * Provides plugin attachment capabilities and lifecycle management.
  * Plugins are attached during configuration and initialized during startup.
  */
-declare class Pluggable {
+declare class Pluggable<TPluggableEvents extends SEEventMapLike<TPluggableEvents> = SENoEvents> extends StrictEventEmitter<TPluggableEvents> {
     protected isInitialized: boolean;
     protected readonly shutdown: CoordinatedShutdown;
     protected readonly startup: CoordinatedStartup;
@@ -167,7 +220,7 @@ declare class Pluggable {
      * @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
+     * @throws A {@link SeedcordError} When called after initialization or if key already exists
      * @example
      * ```typescript
      * seedcord.attach('db', Mongo, StartupPhase.Configuration, { uri: 'mongodb://...', name: 'seedcord', dir: ... })
@@ -301,11 +354,22 @@ declare class CommandRegistry implements Initializeable {
     setCommands(): Promise<void>;
 }
 
+/**
+ * Bot event types
+ */
+interface BotEvents {
+    'error:unhandled:interaction': [error: Error];
+    'error:unhandled:event': [error: Error];
+    'any:event': {
+        [K in keyof ClientEvents]: [K, ...ClientEvents[K]];
+    }[keyof ClientEvents];
+    'any:interaction': [interaction: Interaction];
+}
 /**
  * Discord bot implementation that manages client and controllers
  * @internal - Accessed via core.bot, not directly instantiated by users
  */
-declare class Bot extends Plugin {
+declare class Bot extends Plugin<BotEvents> {
     protected core: Core;
     readonly botToken: string;
     readonly logger: Logger;
@@ -315,6 +379,7 @@ declare class Bot extends Plugin {
     private readonly events;
     readonly commands: CommandRegistry;
     private readonly emojiInjector;
+    readonly emojis: EmojiMap;
     constructor(core: Core);
     /**
      * Initializes Discord client and all controllers
@@ -335,6 +400,23 @@ declare class Bot extends Plugin {
      */
     private logout;
     get client(): Client;
+    /**
+     * Emits with correlation between a Discord event key and its exact arg tuple.
+     *
+     * @typeParam TKey - Discord event name
+     * @param event - Must be the literal `any:event`
+     * @param name - Concrete Discord event name
+     * @param args - Exact tuple for that Discord event
+     */
+    emit<TKey extends keyof ClientEvents>(event: 'any:event', name: TKey, ...args: ClientEvents[TKey]): boolean;
+    /**
+     * Fallback for other BotEvents keys.
+     *
+     * @typeParam TEventKey - Bot event key
+     * @param event - Bot event key
+     * @param args - Tuple payload for the key
+     */
+    emit<TEventKey extends keyof BotEvents>(event: TEventKey, ...args: BotEvents[TEventKey]): boolean;
 }
 
 /**
@@ -360,7 +442,7 @@ declare class Seedcord extends Pluggable implements Core {
      * 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)
+     * @throws An {@link SeedcordError} When attempting to create multiple instances (singleton)
      */
     constructor(config: Config);
     /**
@@ -378,14 +460,17 @@ declare class Seedcord extends Pluggable implements Core {
 
 /** All valid Discord.js interaction types that can be handled */
 type ValidInteractionTypes = ChatInputCommandInteraction | ButtonInteraction | ModalSubmitInteraction | AutocompleteInteraction | AnySelectMenuInteraction | ContextMenuCommandInteraction;
+type ValidNonInteractionKeys = Exclude<keyof ClientEvents, Events.InteractionCreate>;
 /** All valid Discord.js client events except interaction events */
-type ValidNonInteractionTypes = ClientEvents[Exclude<keyof ClientEvents, Events.InteractionCreate>];
+type ValidNonInteractionTypes = ClientEvents[ValidNonInteractionKeys];
 /** All event types that can be handled (interactions and client events) */
 type ValidEventTypes = ValidInteractionTypes | ValidNonInteractionTypes;
 /** Interaction types that can receive replies (excludes autocomplete) */
 type Repliables = Exclude<ValidInteractionTypes, AutocompleteInteraction>;
 /** Handler types that can reply to interactions */
 type RepliableInteractionHandler = InteractionHandler<Repliables> | InteractionMiddleware<Repliables>;
+/** Event handler types that can reply to events */
+type RepliableEventHandler = EventHandler<ValidNonInteractionKeys> | EventMiddleware<ValidNonInteractionKeys>;
 /** Base interface for event handlers */
 interface Handler {
     execute(): Promise<void>;
@@ -427,12 +512,17 @@ declare abstract class BaseHandler<ValidEvent extends ValidEventTypes> implement
     protected errored: boolean;
     protected event: ValidEvent;
     protected args: string[];
+    protected logger: Logger;
     protected constructor(event: ValidEvent, core: Core, args?: string[]);
     /**
      * Main handler logic - implement this method to define behavior
      * @virtual Override this method in your handler classes
      */
     abstract execute(): Promise<void>;
+    /**
+     * Populates the handler with necessary data before execution. Override this method in your handler classes to customize population logic. This method is called at the end of the constructor before all async operations.
+     */
+    protected populate(): void;
     hasChecks(): this is HandlerWithChecks;
     hasErrors(): boolean;
     setErrored(): void;
@@ -479,7 +569,7 @@ declare abstract class InteractionMiddleware<Repliable extends Repliables> exten
  *
  * Middleware runs before event handlers and can modify behavior or block execution.
  */
-declare abstract class EventMiddleware<EventName extends keyof ClientEvents> extends BaseHandler<ClientEvents[EventName]> implements Handler {
+declare abstract class EventMiddleware<EventName extends ValidNonInteractionKeys> extends BaseHandler<ClientEvents[EventName]> implements Handler {
     constructor(event: ClientEvents[EventName], core: Core, args?: string[]);
 }
 /**
@@ -501,7 +591,7 @@ declare abstract class AutocompleteHandler extends BaseHandler<AutocompleteInter
  *
  * @typeParam Repliable - The Discord event type this handler processes
  */
-declare abstract class EventHandler<Repliable extends keyof ClientEvents> extends BaseHandler<ClientEvents[Repliable]> implements Handler {
+declare abstract class EventHandler<Repliable extends ValidNonInteractionKeys> extends BaseHandler<ClientEvents[Repliable]> implements Handler {
     constructor(event: ClientEvents[Repliable], core: Core, args?: string[]);
 }
 /** Constructor type for interaction and autocomplete handlers */
@@ -511,7 +601,7 @@ type InteractionMiddlewareConstructor = TypedConstructor<typeof InteractionMiddl
 /** Constructor type for legacy interaction middleware */
 type MiddlewareConstructor = InteractionMiddlewareConstructor;
 /** Constructor type for event middleware */
-type EventMiddlewareConstructor = TypedConstructor<typeof EventMiddleware> & (new <EventName extends keyof ClientEvents>(event: ClientEvents[EventName], core: Core, args?: string[]) => EventMiddleware<EventName>);
+type EventMiddlewareConstructor = TypedConstructor<typeof EventMiddleware> & (new <EventName extends ValidNonInteractionKeys>(event: ClientEvents[EventName], core: Core, args?: string[]) => EventMiddleware<EventName>);
 /** Constructor type for autocomplete handlers */
 type AutocompleteHandlerConstructor = TypedConstructor<typeof AutocompleteHandler> & (new (event: AutocompleteInteraction, core: Core, args?: string[]) => AutocompleteHandler);
 /** Constructor type for Discord client event handlers */
@@ -830,7 +920,7 @@ declare function RegisterCommand(scope: 'guild', guilds: string[]): (ctor: Comma
  * }
  * ```
  */
-declare function EventCatchable(log?: boolean): (_target: EventHandler<keyof ClientEvents>, _prop: string, descriptor: TypedPropertyDescriptor<(...args: any[]) => Promise<void>>) => void;
+declare function EventCatchable(log?: boolean): (_target: RepliableEventHandler, _prop: string, descriptor: TypedPropertyDescriptor<(...args: any[]) => Promise<void>>) => void;
 
 /**
  * The frequency at which the event handler should be executed.
@@ -843,9 +933,9 @@ type EventFrequency = 'once' | 'on';
  * @internal
  */
 declare const EventMetadataKey: unique symbol;
-/** Options accepted by the `@RegisterEvent` decorator. */
+/** Options accepted by the event registration decorator. */
 interface RegisterEventOptions {
-    /** Frequency: `'once'` or `'on'`. Defaults to `'on'`. */
+    /** Frequency: 'once' or 'on'. Defaults to 'on'. */
     readonly frequency?: EventFrequency | undefined;
 }
 /**
@@ -853,24 +943,28 @@ interface RegisterEventOptions {
  *
  * @internal
  */
-interface RegisterEventMetadataEntry<KeyofEvents extends keyof ClientEvents> {
-    readonly event: KeyofEvents;
+interface RegisterEventMetadataEntry<EventKey extends keyof ClientEvents> {
+    readonly event: EventKey;
     readonly frequency: EventFrequency;
 }
+/** Tuple describing a single event and optional options. */
+type EventSpec<EventKey extends ValidNonInteractionKeys> = readonly [
+    event: EventKey,
+    options?: RegisterEventOptions
+];
 /**
- * Registers an event handler class with a one or multiple Discord.js event(s).
+ * Registers an event handler class with one or more Discord.js events.
  *
- * Associates the decorated class with the mentioned Discord client event(s) for automatic registration and execution when the event is emitted.
+ * Associates the decorated class with the provided Discord client events for automatic registration and execution when those events are emitted.
  *
- * You can use this decorator multiple times on the same class to register for different events with varying option settings.
+ * Supply any number of event tuples. Each tuple can include per event options.
  *
- * @typeParam KeyofEvents - The key of the Discord.js ClientEvents to register for
- * @param events - The Discord.js event name(s) to listen for
- * @param options - Options to configure the event handler registration.
+ * @typeParam EventKey - Union of Discord.js ClientEvents keys to register for
+ * @param defs - One or more tuples of [event, options]
  * @decorator
  * @example
- * ```typescript
- * \@RegisterEvent(Events.MessageCreate)
+ * ```ts
+ * \@RegisterEvent([Events.MessageCreate])
  * class MessageHandler extends EventHandler<Events.MessageCreate> {
  *   async execute() {
  *     // Handle message creation
@@ -879,8 +973,8 @@ interface RegisterEventMetadataEntry<KeyofEvents extends keyof ClientEvents> {
  * ```
  *
  * @example
- * ```typescript
- * \@RegisterEvent([Events.MessageCreate, Events.MessageUpdate])
+ * ```ts
+ * \@RegisterEvent([Events.MessageCreate], [Events.MessageUpdate])
  * class MessageHandler extends EventHandler<Events.MessageCreate | Events.MessageUpdate> {
  *   async execute() {
  *     // Handle message creation or update
@@ -890,15 +984,15 @@ interface RegisterEventMetadataEntry<KeyofEvents extends keyof ClientEvents> {
  *
  * @example
  * ```ts
- * \@RegisterEvent(Events.MessageCreate, { frequency: 'once' })
- * class OneTimeMessageHandler extends EventHandler<Events.MessageCreate> {
+ * \@RegisterEvent([Events.MessageCreate, { frequency: 'once' }], [Events.MessageUpdate])
+ * class OneTimeMessageHandler extends EventHandler<Events.MessageCreate | Events.MessageUpdate> {
  *   async execute() {
- *     // Handle only the first message creation
+ *     // Handle only the first message creation, and message update normally
  *   }
  * }
  * ```
  */
-declare function RegisterEvent<KeyofEvents extends keyof ClientEvents>(events: KeyofEvents | KeyofEvents[], options?: RegisterEventOptions): (constructor: Constructor<unknown>) => void;
+declare function RegisterEvent<const Defs extends readonly EventSpec<ValidNonInteractionKeys>[]>(...defs: Defs): <HandlerCtor extends Constructor<EventHandler<Defs[number][0]>>>(constructor: HandlerCtor) => void;
 
 /**
  * Enum defining interaction route types for decorators
@@ -966,7 +1060,7 @@ declare const InteractionMetadataKey: unique symbol;
  * }
  * ```
  */
-declare function SlashRoute(routeOrRoutes: string | string[]): (constructor: Constructor<unknown>) => void;
+declare function SlashRoute(routeOrRoutes: string | string[]): (constructor: Constructor<InteractionHandler<ChatInputCommandInteraction>>) => void;
 /**
  * Routes button interactions to handler classes
  *
@@ -977,7 +1071,7 @@ declare function SlashRoute(routeOrRoutes: string | string[]): (constructor: Con
  * @param routeOrRoutes - CustomId prefix(es) to handle
  * @decorator
  */
-declare function ButtonRoute(routeOrRoutes: string | string[]): (constructor: Constructor<unknown>) => void;
+declare function ButtonRoute(routeOrRoutes: string | string[]): (constructor: Constructor<InteractionHandler<ButtonInteraction>>) => void;
 /**
  * Routes modal submissions to handler classes
  *
@@ -986,7 +1080,7 @@ declare function ButtonRoute(routeOrRoutes: string | string[]): (constructor: Co
  * @param routeOrRoutes - CustomId prefix(es) to handle
  * @decorator
  */
-declare function ModalRoute(routeOrRoutes: string | string[]): (constructor: Constructor<unknown>) => void;
+declare function ModalRoute(routeOrRoutes: string | string[]): (constructor: Constructor<InteractionHandler<ModalSubmitInteraction>>) => void;
 /**
  * Routes context menu commands to handler classes
  *
@@ -994,7 +1088,7 @@ declare function ModalRoute(routeOrRoutes: string | string[]): (constructor: Con
  * @param routeOrRoutes - Command name(s) to handle
  * @decorator
  */
-declare function ContextMenuRoute(type: 'message' | 'user', routeOrRoutes: string | string[]): (constructor: Constructor<unknown>) => void;
+declare function ContextMenuRoute(type: 'message' | 'user', routeOrRoutes: string | string[]): (constructor: Constructor<InteractionHandler<ContextMenuCommandInteraction>>) => void;
 /**
  * Routes autocomplete interactions to handler classes
  *
@@ -1007,7 +1101,7 @@ declare function ContextMenuRoute(type: 'message' | 'user', routeOrRoutes: strin
  * @example \@AutocompleteRoute(['user', 'profile'], ['name', 'bio']) // Multiple commands, multiple fields
  * @decorator
  */
-declare function AutocompleteRoute(commandRoutes: string | string[], focusedFields: string | string[]): (constructor: Constructor<unknown>) => void;
+declare function AutocompleteRoute(commandRoutes: string | string[], focusedFields: string | string[]): (constructor: Constructor<AutocompleteHandler>) => void;
 /**
  * Routes select menu interactions to handler classes
  *
@@ -1026,7 +1120,7 @@ declare function AutocompleteRoute(commandRoutes: string | string[], focusedFiel
  * }
  * ```
  */
-declare function SelectMenuRoute(type: SelectMenuType, routeOrRoutes: string | string[]): (constructor: Constructor<unknown>) => void;
+declare function SelectMenuRoute(type: SelectMenuType, routeOrRoutes: string | string[]): (constructor: Constructor<InteractionHandler<AnySelectMenuInteraction>>) => void;
 
 /**
  * Middleware types supported by Seedcord
@@ -1043,12 +1137,14 @@ declare enum MiddlewareType {
 declare const MiddlewareMetadataKey: unique symbol;
 /**
  * Additional middleware registration options
+ *
+ * @typeParam MType - The type of middleware being registered
  */
-interface MiddlewareOptions {
+interface MiddlewareOptions<MType extends MiddlewareType> {
     /**
      * Restrict event middleware execution to specific Discord client events
      */
-    readonly events?: readonly (keyof ClientEvents)[];
+    readonly events?: MType extends MiddlewareType.Event ? readonly ValidNonInteractionKeys[] : never;
 }
 /**
  * Metadata stored for middleware registration
@@ -1065,7 +1161,7 @@ interface MiddlewareMetadata {
     /**
      * Optional list of Discord client events to target
      */
-    events?: readonly (keyof ClientEvents)[];
+    events?: readonly ValidNonInteractionKeys[];
 }
 /**
  * Decorator used to register middleware with priority ordering. The lower the priority number, the earlier it runs.
@@ -1083,10 +1179,197 @@ interface MiddlewareMetadata {
  * \@Middleware(MiddlewareType.Event, 10, { events: [Events.MessageCreate, Events.MessageUpdate] })
  * class MyEventMiddleware extends EventMiddleware {}
  * ```
- * @throws A {@link TypeError} If priority is not a finite number
- * @throws An {@link Error} If interaction middleware specifies event filters
+ * @throws A {@link SeedcordTypeError} If priority is not a finite number
+ * @throws A {@link SeedcordError} If interaction middleware specifies event filters
+ */
+declare function Middleware<MType extends MiddlewareType>(type: MType, priority?: number, options?: MiddlewareOptions<MType>): (ctor: Constructor<MType extends MiddlewareType.Interaction ? InteractionMiddleware<Repliables> : EventMiddleware<ValidNonInteractionKeys>>) => void;
+
+/**
+ * Context object supplied to Confirmable factory callbacks.
+ */
+interface ConfirmableContext {
+    /** Handler instance that owns the decorated method. */
+    handler: RepliableInteractionHandler;
+    /** Interaction that triggered the decorated handler. */
+    interaction: Repliables;
+    /** Resolved confirmation question shown to the user. */
+    question: string;
+}
+/**
+ * Factory helper that supports synchronous and asynchronous Confirmable values.
+ */
+type ConfirmableFactory<ConfirmableResult> = ConfirmableResult | ((ctx: ConfirmableContext) => Promisable<ConfirmableResult>);
+/**
+ * Utility type to extract the underlying component type from builder components.
+ *
+ * @internal
+ */
+type ExtractComponent<TComp> = TComp extends {
+    component: infer C;
+} ? C : never;
+/**
+ * Normalized container component structure used by Confirmable internals.
+ *
+ * @internal
+ */
+type ContainerLike = ExtractComponent<BuilderComponent<'container'>>;
+/**
+ * Normalized embed component structure used by Confirmable internals.
+ *
+ * Ensures the embed count remains within the Discord limit of 1..10.
+ *
+ * @internal
+ */
+type EmbedLike = TupleOf<IntClosedRange<1, 10>, ExtractComponent<BuilderComponent<'embed'>>>;
+/**
+ * Normalized action row structure for button components.
+ *
+ * @internal
+ */
+type RowLike = ExtractComponent<RowComponent<'button'>>;
+/**
+ * Response payload produced when using classic message component rows.
+ *
+ * @internal
+ */
+interface ClassicPayload {
+    components: readonly RowLike[];
+    embeds?: EmbedLike;
+    content?: string;
+    flags?: unknown;
+}
+/**
+ * Response payload produced when using the Component V2 container API.
+ *
+ * @internal
+ */
+interface ComponentsV2Payload {
+    flags: 'IsComponentsV2';
+    components: readonly ContainerLike[];
+}
+/**
+ * Payload variants that Confirmable may send back to the platform.
+ *
+ * @internal
+ */
+type ConfirmablePayload = ClassicPayload | ComponentsV2Payload;
+/**
+ * Information supplied to the optional onResolved callback.
+ */
+interface ConfirmableResolution extends ConfirmableContext {
+    /** Whether the user confirmed the action. */
+    confirmed: boolean;
+    /** Whether the confirmation UI timed out without a response. */
+    timedOut: boolean;
+    /** Interaction that resolved the decision, if any. */
+    button?: MessageComponentInteraction;
+}
+/**
+ * Maps a message component type to the corresponding interaction subtype.
+ *
+ * @internal
+ */
+type ComponentInteractionFor<TComponentType extends MessageComponentType> = TComponentType extends ComponentType.Button ? ButtonInteraction : TComponentType extends ComponentType.StringSelect ? StringSelectMenuInteraction : TComponentType extends ComponentType.UserSelect ? UserSelectMenuInteraction : TComponentType extends ComponentType.RoleSelect ? RoleSelectMenuInteraction : TComponentType extends ComponentType.MentionableSelect ? MentionableSelectMenuInteraction : TComponentType extends ComponentType.ChannelSelect ? ChannelSelectMenuInteraction : MessageComponentInteraction;
+/**
+ * Confirmable configuration shared across the classic and component V2 modes.
+ */
+interface ConfirmableSharedOptions<TComponentType extends MessageComponentType = ComponentType.Button> {
+    ephemeral?: boolean;
+    timeoutMs?: number;
+    componentType?: TComponentType;
+    onResolved?: (r: ConfirmableResolution) => Promisable<void>;
+    defer?: boolean;
+}
+/**
+ * Classic mode payload that allows omitting components when clearing the UI.
+ */
+type MaybeClearedClassic = TypedOmit<ClassicPayload, 'components'> & {
+    components?: readonly RowLike[];
+};
+/**
+ * Outcome UI factories used by classic message component rows.
+ */
+interface OutcomeUiClassic {
+    /** Factory invoked when the user cancels the prompt. */
+    onCancel: ConfirmableFactory<MaybeClearedClassic>;
+    /** Factory invoked when the prompt times out. */
+    onTimeout: ConfirmableFactory<MaybeClearedClassic>;
+    /** Factory invoked when the user confirms the prompt. */
+    onConfirm?: ConfirmableFactory<MaybeClearedClassic>;
+}
+/**
+ * Outcome UI factories used by the Component V2 container API.
+ */
+interface OutcomeUiV2 {
+    /** Factory invoked when the user cancels the prompt. */
+    onCancel: ConfirmableFactory<ComponentsV2Payload>;
+    /** Factory invoked when the prompt times out. */
+    onTimeout: ConfirmableFactory<ComponentsV2Payload>;
+    /** Factory invoked when the user confirms the prompt. */
+    onConfirm?: ConfirmableFactory<ComponentsV2Payload>;
+}
+/**
+ * Source definition that resolves a confirmation decision from a component interaction.
+ */
+interface ResolverSource<TComponentType extends MessageComponentType> {
+    /** Message component type expected by the resolver. */
+    componentType: TComponentType;
+    /** Resolves whether the user confirmed the prompt. */
+    resolveDecision: (i: ComponentInteractionFor<TComponentType>) => Promisable<boolean>;
+}
+/**
+ * Source definition that lists custom IDs for confirm and cancel actions.
+ */
+interface CustomIdSource {
+    /** Custom IDs that should resolve the confirmation as accepted. */
+    confirmCustomIds: readonly string[];
+    /** Optional custom IDs that should resolve the confirmation as rejected. */
+    cancelCustomIds?: readonly string[];
+}
+/**
+ * Configuration for Confirmable when using classic message component rows.
+ */
+type ConfirmableClassicOptions<TComponentType extends MessageComponentType = ComponentType.Button> = ConfirmableSharedOptions<TComponentType> & (ResolverSource<TComponentType> | CustomIdSource) & {
+    /** Prompt content or embed factory shown to the user. */
+    prompt: ConfirmableFactory<BuilderComponent<'embed'> | string>;
+    /** Action row factory producing confirm and cancel components. */
+    rows: ConfirmableFactory<NonEmptyTuple<RowLike>>;
+    container?: never;
+    /** Outcome UI factories applied once the decision is resolved. */
+    outcomeUi: OutcomeUiClassic;
+};
+/**
+ * Configuration for Confirmable when using the Component V2 container API.
+ */
+type ConfirmableComponentsV2Options<TComponentType extends MessageComponentType = ComponentType.Button> = ConfirmableSharedOptions<TComponentType> & (ResolverSource<TComponentType> | CustomIdSource) & {
+    /** Container factory that renders the confirmation UI. */
+    container: ConfirmableFactory<BuilderComponent<'container'>>;
+    prompt?: never;
+    rows?: never;
+    /** Outcome UI factories applied once the decision is resolved. */
+    outcomeUi: OutcomeUiV2;
+};
+/**
+ * Union of supported Confirmable configuration variants.
  */
-declare function Middleware(type: MiddlewareType, priority?: number, options?: MiddlewareOptions): ClassDecorator;
+type ConfirmableOptions<TComponentType extends MessageComponentType = ComponentType.Button> = ConfirmableClassicOptions<TComponentType> | ConfirmableComponentsV2Options<TComponentType>;
+/**
+ * Supported signature for the question argument passed to {@link Confirmable}.
+ */
+type QuestionInput = string | (() => Promise<string>);
+
+/**
+ * Wraps a repliable handler method with an interactive confirmation flow.
+ *
+ * Displays a prompt, waits for a follow-up component interaction, and conditionally executes the original method
+ * based on the user's decision. The decorator supports both classic action rows + embed/content and ComponentV2 containers.
+ *
+ * @typeParam TComp - Message component type that should resolve the confirmation.
+ * @param question - Static string or lazy factory that resolves the prompt question.
+ * @param options - Confirmation flow configuration.
+ * @decorator
+ */
+declare function Confirmable<TComponent extends MessageComponentType = ComponentType.Button>(question: QuestionInput, options: ConfirmableOptions<TComponent>): (_target: RepliableInteractionHandler, _propertyKey: string, descriptor: TypedPropertyDescriptor<(...args: unknown[]) => Promise<void>>) => TypedPropertyDescriptor<(...args: unknown[]) => Promise<void>>;
 
 /**
  * Manages Discord event handler registration and execution.
@@ -1333,13 +1616,6 @@ declare class UserNotFound extends CustomError {
     constructor(userArg: string);
 }
 
-declare class EmojiInjector {
-    private readonly core;
-    private readonly logger;
-    constructor(core: Core);
-    init(): Promise<void>;
-}
-
 /**
  * Fetches and validates a text channel.
  *
@@ -1523,7 +1799,7 @@ declare function fetchRole(clientOrGuild: Client | Guild, roleId: string): Promi
  * @param client - The Discord client instance
  * @param guild - The guild to get the bot's role from
  * @returns The bot's highest role in the guild
- * @throws An {@link Error} When the bot is not in the guild
+ * @throws A {@link SeedcordError} When the bot is not in the guild
  */
 declare function getBotRole(client: Client, guild: Guild): Role;
 
@@ -1735,7 +2011,7 @@ declare abstract class WebhookLog<KeyOfEffects extends EffectKeys> extends Effec
  *
  * Developers need to set the UNKNOWN_EXCEPTION_WEBHOOK_URL environment variable in their .env file otherwise this effect will throw an error during initialization.
  *
- * @throws Error if UNKNOWN_EXCEPTION_WEBHOOK_URL is not set or is invalid
+ * @throws A {@link SeedcordError} if UNKNOWN_EXCEPTION_WEBHOOK_URL is not set or is invalid
  */
 declare class UnknownException extends WebhookLog<'unknownException'> {
     private static readonly logger;
@@ -1745,4 +2021,4 @@ declare class UnknownException extends WebhookLog<'unknownException'> {
     private prepareMetadataFile;
 }
 
-export { type ActionRowComponentType, type AllEffects, type AtleastOneMessageComponent, AutocompleteHandler, type AutocompleteHandlerConstructor, AutocompleteRoute, BaseComponent, type BaseCore, BaseErrorEmbed, BaseHandler, Bot, type BotConfig, type BotPermissionScope, type BotPermissionScopeGroups, BuilderComponent, type BuilderType, BuilderTypes, ButtonRoute, CannotAssignBotRole, CannotSendEmbedsError, Catchable, type CatchableOptions, ChannelNotFoundError, ChannelNotTextChannel, Checkable, type CommandCtor, type CommandMeta, CommandMetadataKey, CommandRegistry, type CommandRouteString, type CommandScope, type CommandsConfig, type Config, ContextMenuRoute, type Core, CouldNotFindChannel, CustomError, type CustomErrorConstructor, DatabaseError, type DefaultEffects, type EffectKeys, EffectMetadataKey, type EffectParams, type Effects, type EffectsConfig, EffectsEmitter, EffectsHandler, EffectsRegistry, EmojiInjector, EventCatchable, EventController, EventHandler, type EventHandlerConstructor, EventMetadataKey, EventMiddleware, type EventMiddlewareConstructor, type EventsConfig, type ExtractedErrorResponse, GenericError, type GlobalMeta, type GuildMeta, type Handler, type HandlerConstructor, type HandlerCtor, type HandlerWithChecks, HasDangerousPermissions, type Initializeable, type InstantiatedActionRow, type InstantiatedBuilder, InteractionController, InteractionHandler, InteractionMetadataKey, InteractionMiddleware, type InteractionMiddlewareConstructor, InteractionRoutes, type InteractionsConfig, type MessageContent, Middleware, type MiddlewareConstructor, type MiddlewareMetadata, MiddlewareMetadataKey, type MiddlewareOptions, MiddlewareType, MissingPermissions, ModalRoute, PERM_GROUPS, PermissionNames, Pluggable, Plugin, type PluginArgs, type PluginCtor, RegisterCommand, RegisterEffect, type RegisterEffectMetadataEntry, type RegisterEffectOptions, RegisterEvent, type RegisterEventMetadataEntry, type RegisterEventOptions, type RepliableInteractionHandler, type Repliables, RoleDoesNotExist, RoleHigherThanMe, RowComponent, RowTypes, Seedcord, SelectMenuRoute, SelectMenuType, SlashRoute, UnhandledEvent, UnknownException, UserNotFound, UserNotInGuild, type ValidEventTypes, type ValidInteractionTypes, type ValidNonInteractionTypes, WebhookLog, type WithChecks, attemptSendDM, buildSlashRoute, checkBotPermissions, checkPermissions, extractErrorResponse, fetchGuildMember, fetchManyGuildMembers, fetchManyUsers, fetchRole, fetchText, fetchUser, getBotRole, hasPermsToAssign, sendInText, throwCustomError, updateMemberRoles };
+export { type ActionRowComponentType, type AllEffects, type AtleastOneMessageComponent, AutocompleteHandler, type AutocompleteHandlerConstructor, AutocompleteRoute, BaseComponent, type BaseCore, BaseErrorEmbed, BaseHandler, Bot, type BotConfig, type BotEvents, type BotPermissionScope, type BotPermissionScopeGroups, BuilderComponent, type BuilderType, BuilderTypes, ButtonRoute, CannotAssignBotRole, CannotSendEmbedsError, Catchable, type CatchableOptions, ChannelNotFoundError, ChannelNotTextChannel, Checkable, type ClassicPayload, type CommandCtor, type CommandMeta, CommandMetadataKey, CommandRegistry, type CommandRouteString, type CommandScope, type CommandsConfig, type ComponentInteractionFor, type ComponentsV2Payload, type Config, Confirmable, type ConfirmableClassicOptions, type ConfirmableComponentsV2Options, type ConfirmableContext, type ConfirmableFactory, type ConfirmableOptions, type ConfirmablePayload, type ConfirmableResolution, type ConfirmableSharedOptions, type ContainerLike, ContextMenuRoute, type Core, CouldNotFindChannel, CustomError, type CustomErrorConstructor, type CustomIdSource, DatabaseError, type DefaultEffects, type EffectKeys, EffectMetadataKey, type EffectParams, type Effects, type EffectsConfig, EffectsEmitter, EffectsHandler, EffectsRegistry, type EmbedLike, EmojiInjector, type EmojiMap, Emojis, EventCatchable, EventController, EventHandler, type EventHandlerConstructor, EventMetadataKey, EventMiddleware, type EventMiddlewareConstructor, type EventSpec, type EventsConfig, type ExtractComponent, type ExtractedErrorResponse, GenericError, type GlobalMeta, type GuildMeta, type Handler, type HandlerConstructor, type HandlerCtor, type HandlerWithChecks, HasDangerousPermissions, type Initializeable, type InstantiatedActionRow, type InstantiatedBuilder, InteractionController, InteractionHandler, InteractionMetadataKey, InteractionMiddleware, type InteractionMiddlewareConstructor, InteractionRoutes, type InteractionsConfig, type MaybeClearedClassic, type MessageContent, Middleware, type MiddlewareConstructor, type MiddlewareMetadata, MiddlewareMetadataKey, type MiddlewareOptions, MiddlewareType, MissingPermissions, ModalRoute, type OutcomeUiClassic, type OutcomeUiV2, PERM_GROUPS, PermissionNames, Pluggable, Plugin, type PluginArgs, type PluginCtor, type QuestionInput, RegisterCommand, RegisterEffect, type RegisterEffectMetadataEntry, type RegisterEffectOptions, RegisterEvent, type RegisterEventMetadataEntry, type RegisterEventOptions, type RepliableEventHandler, type RepliableInteractionHandler, type Repliables, type ResolverSource, RoleDoesNotExist, RoleHigherThanMe, RowComponent, type RowLike, RowTypes, Seedcord, SelectMenuRoute, SelectMenuType, SlashRoute, UnhandledEvent, UnknownException, UserNotFound, UserNotInGuild, type ValidEventTypes, type ValidInteractionTypes, type ValidNonInteractionKeys, type ValidNonInteractionTypes, WebhookLog, type WithChecks, attemptSendDM, buildSlashRoute, checkBotPermissions, checkPermissions, extractErrorResponse, fetchGuildMember, fetchManyGuildMembers, fetchManyUsers, fetchRole, fetchText, fetchUser, getBotRole, hasPermsToAssign, sendInText, throwCustomError, updateMemberRoles };