@seedcord/gateway 0.4.1 → 0.5.0

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import "reflect-metadata";
 import { WinstonConsoleSink, WinstonFileSink } from "@seedcord/logger/node";
 import { AutocompletableNames, AutocompleteRouteBrand, CacheFor, ChoiceValueOf, ComponentDefsBrand, ComponentKindBrand, ContextMenuKindBrand, ContextMenuLeaves, ContextMenuNamesBrand, EntryFor, FocusedField, GateFitsWith, HasComponentDefs, Initializeable, MatchArms, MenuCacheFor, NamesFor, PageCursor, SingleParams, SlashOptions as SlashOptions$1, SlashRouteBrand } from "@seedcord/core/internal";
-import { ArraySourceBase, AutocompleteOptions, BaseHandler as BaseHandler$1, BaseReplySender, Bus, CoreBase, CursorSourceBase, DispatchContext, Gate, GateContextBase, GateNoticeOptions, GuildPermissionsContext, ModalLike, Notice, PageSourceBase, PaginatorBase, PaginatorConfig, PermissionNoticeOverrides, PermissionScope, RepliableHandler as RepliableHandler$1, RequiredOf, ResolvedEmoji, SelectMenuKind, SlashRegistry, Subscriber as Subscriber$1, SubscriptionKey, WebhookLog as WebhookLog$1 } from "@seedcord/core";
+import { ArraySourceBase, AutocompleteOptions, BaseHandler as BaseHandler$1, BaseReplySender, Bus, CoreBase, CursorSourceBase, DispatchContext, Gate, GateContextBase, GateNoticeOptions, GuildPermissionsContext, InteractionKind, ModalLike, Notice, PageSourceBase, PaginatorBase, PaginatorConfig, PermissionNoticeOverrides, PermissionScope, RepliableHandler as RepliableHandler$1, RequiredOf, ResolvedEmoji, SlashRegistry, Subscriber as Subscriber$1, SubscriptionKey, WebhookLog as WebhookLog$1 } from "@seedcord/core";
 import { Logger } from "@seedcord/logger";
 import { APIInteractionGuildMember, APIModalInteractionResponseCallbackData, AnySelectMenuInteraction, ApplicationCommandOptionChoiceData, ApplicationCommandType, ApplicationEmoji, AutocompleteInteraction, BaseMessageOptions, BooleanCache, ButtonInteraction, ButtonStyle, CacheType, CacheTypeReducer, ChannelSelectMenuInteraction, ChatInputCommandInteraction, Client, ClientEvents, ClientOptions, CommandInteractionOption, ContextMenuCommandInteraction, Events, Guild, GuildEmoji, GuildMember, Interaction, MentionableSelectMenuInteraction, Message, MessageContextMenuCommandInteraction, ModalSubmitFields, ModalSubmitInteraction, Role, RoleSelectMenuInteraction, StringSelectMenuInteraction, TextChannel, User, UserContextMenuCommandInteraction, UserSelectMenuInteraction } from "discord.js";
 import { Plugin as Plugin$1, PluginLifecycleSpec, PluginOptions, PluginOptions as PluginOptions$1 } from "@seedcord/core/plugin";
@@ -127,17 +127,7 @@ declare class InteractionDispatcher implements Initializeable, HmrAware {
   protected core: Core;
   private readonly logger;
   private isInitialized;
-  private readonly slashMap;
-  private readonly buttonMap;
-  private readonly modalMap;
-  private readonly stringSelectMap;
-  private readonly userSelectMap;
-  private readonly roleSelectMap;
-  private readonly channelSelectMap;
-  private readonly mentionableSelectMap;
-  private readonly messageContextMenuMap;
-  private readonly userContextMenuMap;
-  private readonly autocompleteMap;
+  private readonly maps;
   private readonly handlerFiles;
   private readonly keysToIgnore;
   private readonly middlewares;
@@ -147,7 +137,6 @@ declare class InteractionDispatcher implements Initializeable, HmrAware {
   private readonly loadedHandlers;
   private readonly loadedMiddlewares;
   private readonly hmrHandler?;
-  private readonly routeTypes;
   constructor(core: Core);
   warnUnhandledRoutes(commandLeaves: Iterable<string>): void;
   warnUnhandledContextMenuRoutes(leaves: ContextMenuLeaves): void;
@@ -618,8 +607,8 @@ declare class ReplySender extends BaseReplySender<SentMessage, GatewayFile> {
  * Shared base the repliable interaction handlers extend.
  *
  * Not a public entry point. Extend {@link SlashHandler}, {@link ButtonHandler}, {@link ModalHandler},
- * {@link SelectMenuHandler}, or {@link ContextMenuHandler} instead. This class binds the core reply base
- * to the gateway sender.
+ * {@link ContextMenuHandler}, or one of the select menu bases instead. This class binds the core
+ * reply base to the gateway sender.
  *
  * @typeParam Event - The repliable interaction type this handler processes
  */
@@ -634,8 +623,8 @@ declare abstract class RepliableHandler<Event extends Repliables> extends Replia
  * Shared base the typed interaction handlers extend.
  *
  * Not a public entry point. Extend {@link SlashHandler}, {@link ButtonHandler}, {@link ModalHandler},
- * or {@link SelectMenuHandler} instead. This class adds `showModal` on top of the reply members those bases
- * share.
+ * or one of the select menu bases instead. This class adds `showModal` on top of the reply members
+ * those bases share.
  *
  * @typeParam Repliable - The interaction type this handler processes
  */
@@ -745,7 +734,7 @@ interface Ungateable {
   readonly [UngateableBrand]: true;
 }
 type ProvidedContext<TCtor extends AnyHandlerCtor> = InstanceType<TCtor> extends InteractionHandler<infer Repliable> ? InteractionGateContext<Repliable> : InstanceType<TCtor> extends EventHandler<infer Names> ? EventGateContext<Names> : Ungateable;
-type KindName<Ctx> = Ctx extends Ungateable ? 'autocomplete' : Ctx extends InteractionGateContext<infer R> ? R extends ChatInputCommandInteraction ? 'Slash' : R extends MessageContextMenuCommandInteraction ? 'MessageMenu' : R extends UserContextMenuCommandInteraction ? 'UserMenu' : R extends StringSelectMenuInteraction ? 'StringSelect' : R extends UserSelectMenuInteraction ? 'UserSelect' : R extends RoleSelectMenuInteraction ? 'RoleSelect' : R extends ChannelSelectMenuInteraction ? 'ChannelSelect' : R extends MentionableSelectMenuInteraction ? 'MentionableSelect' : R extends ButtonInteraction ? 'Button' : R extends ModalSubmitInteraction ? 'Modal' : 'an interaction' : Ctx extends EventGateContext<infer N> ? `${N & string} event` : 'an agnostic';
+type KindName<Ctx> = Ctx extends Ungateable ? 'autocomplete' : Ctx extends InteractionGateContext<infer R> ? R extends ChatInputCommandInteraction ? 'Slash' : R extends MessageContextMenuCommandInteraction ? 'MessageContextMenu' : R extends UserContextMenuCommandInteraction ? 'UserContextMenu' : R extends StringSelectMenuInteraction ? 'StringMenu' : R extends UserSelectMenuInteraction ? 'UserMenu' : R extends RoleSelectMenuInteraction ? 'RoleMenu' : R extends ChannelSelectMenuInteraction ? 'ChannelMenu' : R extends MentionableSelectMenuInteraction ? 'MentionableMenu' : R extends ButtonInteraction ? 'Button' : R extends ModalSubmitInteraction ? 'Modal' : 'an interaction' : Ctx extends EventGateContext<infer N> ? `${N & string} event` : 'an agnostic';
 type FitAll<TCtor extends AnyHandlerCtor, Gates extends readonly Gate<GateContextBase>[]> = { [Index in keyof Gates]: GateFitsWith<ProvidedContext<TCtor>, KindName<ProvidedContext<TCtor>>, Gates[Index], KindName<RequiredOf<Gates[Index]>>>; };
 //#endregion
 //#region src/bot/decorators/Gated.d.ts
@@ -1073,8 +1062,8 @@ type ComponentInteraction = ButtonInteraction | ModalSubmitInteraction | AnySele
 /**
  * Shared base the customId-routed component handlers extend.
  *
- * Not a public entry point. Extend {@link ButtonHandler}, {@link SelectMenuHandler}, or {@link ModalHandler}
- * instead. This class defines the customId decode and the route matching those bases share.
+ * Not a public entry point. Extend {@link ButtonHandler}, {@link ModalHandler}, or one of the select menu
+ * bases instead. This class defines the customId decode and the route matching those bases share.
  *
  * @typeParam Event - The component interaction type this handler processes
  * @typeParam Defs - The customId route definitions registered on the concrete handler
@@ -1151,7 +1140,7 @@ declare abstract class ComponentHandler<Event extends ComponentInteraction, Defs
  */
 declare abstract class ButtonHandler<Defs extends readonly AnyCustomId[], Cache extends CacheType = 'cached'> extends ComponentHandler<ButtonInteraction<Cache>, Defs> {
   /** @internal */
-  readonly [ComponentKindBrand]?: 'button';
+  readonly [ComponentKindBrand]?: InteractionKind.Button;
 }
 //#endregion
 //#region src/handlers/interaction/components/ModalHandler.d.ts
@@ -1180,7 +1169,7 @@ declare abstract class ButtonHandler<Defs extends readonly AnyCustomId[], Cache
  */
 declare abstract class ModalHandler<Defs extends readonly AnyCustomId[], Cache extends CacheType = 'cached'> extends ComponentHandler<ModalSubmitInteraction<Cache>, Defs> {
   /** @internal */
-  readonly [ComponentKindBrand]?: 'modal';
+  readonly [ComponentKindBrand]?: InteractionKind.Modal;
   /** The fields this modal submitted, read by custom id. */
   protected get fields(): ModalSubmitFields<Cache>;
   /** Rewrite the message this modal was opened from. Throws when a command opened the modal. */
@@ -1191,27 +1180,58 @@ declare abstract class ModalHandler<Defs extends readonly AnyCustomId[], Cache e
 }
 //#endregion
 //#region src/handlers/interaction/components/SelectMenuHandler.d.ts
-type SelectKey = 'values' | 'users' | 'members' | 'roles' | 'channels';
-type EventMember<Kind extends SelectMenuKind, Cache extends CacheType, Key extends SelectKey> = Key extends keyof SelectMenuInteractionFor<Kind, Cache> ? SelectMenuInteractionFor<Kind, Cache>[Key] : never;
-type SelectMenuInteractionFor<SelectMenu extends SelectMenuKind, Cache extends CacheType = CacheType> = SelectMenu extends SelectMenuKind.String ? StringSelectMenuInteraction<Cache> : SelectMenu extends SelectMenuKind.User ? UserSelectMenuInteraction<Cache> : SelectMenu extends SelectMenuKind.Role ? RoleSelectMenuInteraction<Cache> : SelectMenu extends SelectMenuKind.Channel ? ChannelSelectMenuInteraction<Cache> : SelectMenu extends SelectMenuKind.Mentionable ? MentionableSelectMenuInteraction<Cache> : never;
 /**
- * Base class for a select menu handler.
+ * Shared base the select menu handlers extend.
  *
- * Pass the select kind first and the customId definitions second, the same order as `@SelectMenuRoute`.
- * Read the picked ids from `this.values`. The kind decides which of `this.users`, `this.members`,
- * `this.roles`, and `this.channels` this handler carries. The rest are `never`.
+ * Not a public entry point. Extend {@link StringMenuHandler}, {@link UserMenuHandler},
+ * {@link RoleMenuHandler}, {@link ChannelMenuHandler}, or {@link MentionableMenuHandler} instead. This
+ * class defines the `values` getter those bases share.
  *
- * Read `this.params` for a single route or `this.match` for several. Reply through the handler members, or
- * rewrite the source message with `this.update`.
+ * @typeParam Event - The select menu interaction type this handler processes
+ * @typeParam Defs - The customId route definitions registered on the concrete handler
+ */
+declare abstract class SelectMenuHandler<Event extends AnySelectMenuInteraction, Defs extends readonly AnyCustomId[]> extends ComponentHandler<Event, Defs> {
+  /** The values this select picked. On every kind but the string menu they are snowflake ids. */
+  protected get values(): string[];
+}
+/**
+ * Base class for a string select menu handler.
+ *
+ * Register the customId definitions with `@StringMenuRoute`, list the same ones in the generic, then read
+ * the chosen option values from `this.values`. Read `this.params` for a single route or `this.match` for
+ * several. Reply through the handler members, or rewrite the source message with `this.update`.
+ *
+ * @typeParam Defs - The customId definitions this handler decodes, e.g. `[typeof TopicsId]`.
+ * @typeParam Cache - The interaction cache state, `'cached'` by default.
+ *
+ * @example
+ * ```ts
+ * \@StringMenuRoute(TopicsId)
+ * class Topics extends StringMenuHandler<[typeof TopicsId]> {
+ *     async execute() {
+ *         const { userId } = this.params;
+ *         await this.update(`<@${userId}> now follows ${this.values.join(', ')}`);
+ *     }
+ * }
+ * ```
+ */
+declare abstract class StringMenuHandler<Defs extends readonly AnyCustomId[], Cache extends CacheType = 'cached'> extends SelectMenuHandler<StringSelectMenuInteraction<Cache>, Defs> {
+  /** @internal */
+  readonly [ComponentKindBrand]?: InteractionKind.StringMenu;
+}
+/**
+ * Base class for a user select menu handler.
+ *
+ * Beside `this.values` this handler declares `this.users` and `this.members`. Register the customId
+ * definitions with `@UserMenuRoute` and list the same ones in the generic.
  *
- * @typeParam Kind - The select kind from {@link SelectMenuKind}, e.g. `SelectMenuKind.User`.
  * @typeParam Defs - The customId definitions this handler decodes, e.g. `[typeof AssignId]`.
  * @typeParam Cache - The interaction cache state, `'cached'` by default.
  *
  * @example
  * ```ts
- * \@SelectMenuRoute(SelectMenuKind.User, AssignId)
- * class AssignSelect extends SelectMenuHandler<SelectMenuKind.User, [typeof AssignId]> {
+ * \@UserMenuRoute(AssignId)
+ * class Assign extends UserMenuHandler<[typeof AssignId]> {
  *     async execute() {
  *         const { roleId } = this.params;
  *         await this.reply(`assigning ${this.users.size} member(s) to <@&${roleId}>`);
@@ -1219,20 +1239,92 @@ type SelectMenuInteractionFor<SelectMenu extends SelectMenuKind, Cache extends C
  * }
  * ```
  */
-declare abstract class SelectMenuHandler<Kind extends SelectMenuKind, Defs extends readonly AnyCustomId[], Cache extends CacheType = 'cached'> extends ComponentHandler<SelectMenuInteractionFor<Kind, Cache>, Defs> {
+declare abstract class UserMenuHandler<Defs extends readonly AnyCustomId[], Cache extends CacheType = 'cached'> extends SelectMenuHandler<UserSelectMenuInteraction<Cache>, Defs> {
   /** @internal */
-  readonly [ComponentKindBrand]?: Kind;
-  private eventMember;
-  /** The ids this select picked. */
-  protected get values(): string[];
+  readonly [ComponentKindBrand]?: InteractionKind.UserMenu;
   /** The users this select picked. */
-  protected get users(): EventMember<Kind, Cache, 'users'>;
+  protected get users(): UserSelectMenuInteraction<Cache>['users'];
   /** The guild members behind the picked users. Discord resolves these only inside a guild. */
-  protected get members(): EventMember<Kind, Cache, 'members'>;
+  protected get members(): UserSelectMenuInteraction<Cache>['members'];
+}
+/**
+ * Base class for a role select menu handler.
+ *
+ * Beside `this.values` this handler declares `this.roles`. Register the customId definitions with
+ * `@RoleMenuRoute` and list the same ones in the generic.
+ *
+ * @typeParam Defs - The customId definitions this handler decodes, e.g. `[typeof GrantId]`.
+ * @typeParam Cache - The interaction cache state, `'cached'` by default.
+ *
+ * @example
+ * ```ts
+ * \@RoleMenuRoute(GrantId)
+ * class Grant extends RoleMenuHandler<[typeof GrantId]> {
+ *     async execute() {
+ *         await this.update(`granting ${this.roles.size} role(s)`);
+ *     }
+ * }
+ * ```
+ */
+declare abstract class RoleMenuHandler<Defs extends readonly AnyCustomId[], Cache extends CacheType = 'cached'> extends SelectMenuHandler<RoleSelectMenuInteraction<Cache>, Defs> {
+  /** @internal */
+  readonly [ComponentKindBrand]?: InteractionKind.RoleMenu;
   /** The roles this select picked. */
-  protected get roles(): EventMember<Kind, Cache, 'roles'>;
+  protected get roles(): RoleSelectMenuInteraction<Cache>['roles'];
+}
+/**
+ * Base class for a channel select menu handler.
+ *
+ * Beside `this.values` this handler declares `this.channels`. Register the customId definitions with
+ * `@ChannelMenuRoute` and list the same ones in the generic.
+ *
+ * @typeParam Defs - The customId definitions this handler decodes, e.g. `[typeof LogTargetId]`.
+ * @typeParam Cache - The interaction cache state, `'cached'` by default.
+ *
+ * @example
+ * ```ts
+ * \@ChannelMenuRoute(LogTargetId)
+ * class LogTarget extends ChannelMenuHandler<[typeof LogTargetId]> {
+ *     async execute() {
+ *         await this.update(`logging to ${this.channels.size} channel(s)`);
+ *     }
+ * }
+ * ```
+ */
+declare abstract class ChannelMenuHandler<Defs extends readonly AnyCustomId[], Cache extends CacheType = 'cached'> extends SelectMenuHandler<ChannelSelectMenuInteraction<Cache>, Defs> {
+  /** @internal */
+  readonly [ComponentKindBrand]?: InteractionKind.ChannelMenu;
   /** The channels this select picked. */
-  protected get channels(): EventMember<Kind, Cache, 'channels'>;
+  protected get channels(): ChannelSelectMenuInteraction<Cache>['channels'];
+}
+/**
+ * Base class for a mentionable select menu handler.
+ *
+ * A mentionable menu accepts users and roles together. `this.users`, `this.members`, and `this.roles`
+ * can each come back empty.
+ *
+ * @typeParam Defs - The customId definitions this handler decodes, e.g. `[typeof InviteId]`.
+ * @typeParam Cache - The interaction cache state, `'cached'` by default.
+ *
+ * @example
+ * ```ts
+ * \@MentionableMenuRoute(InviteId)
+ * class Invite extends MentionableMenuHandler<[typeof InviteId]> {
+ *     async execute() {
+ *         await this.update(`inviting ${this.users.size} user(s) and ${this.roles.size} role(s)`);
+ *     }
+ * }
+ * ```
+ */
+declare abstract class MentionableMenuHandler<Defs extends readonly AnyCustomId[], Cache extends CacheType = 'cached'> extends SelectMenuHandler<MentionableSelectMenuInteraction<Cache>, Defs> {
+  /** @internal */
+  readonly [ComponentKindBrand]?: InteractionKind.MentionableMenu;
+  /** The users this select picked. */
+  protected get users(): MentionableSelectMenuInteraction<Cache>['users'];
+  /** The guild members behind the picked users. Discord resolves these only inside a guild. */
+  protected get members(): MentionableSelectMenuInteraction<Cache>['members'];
+  /** The roles this select picked. */
+  protected get roles(): MentionableSelectMenuInteraction<Cache>['roles'];
 }
 //#endregion
 //#region src/bot/decorators/Middlewares.d.ts
@@ -1764,5 +1856,5 @@ declare class Seedcord extends Pluggable<'gateway', 'server'> implements Core, S
 /** Package version */
 declare const version: string;
 //#endregion
-export { ArraySource, AssignRoleNoticeOverrides, AutocompleteHandler, BaseHandler, ButtonHandler, type CheckPermissionOptions, ComponentHandler, type ConfirmOptions, type Core, CursorSource, type DefaultConfirmOptions, Emojis, type EventGateContext, EventHandler, EventMiddleware, type EventSpec, type EventsConfig, type GateContext, Gated, type GatewayBotConfig, type GatewayConfig, GatewayEmoji, type GatewayFile, type GatewayPluginOptions, type GatewayReplyResponse, HasPermsToAssignOptions, IgnoreBots, type InjectedEmojiMap, type InteractionGateContext, InteractionHandler, InteractionMiddleware, MessageContextMenuHandler, Middleware, type MiddlewareOptions, MiddlewareType, ModalHandler, Nsfw, type PageContext, type PageSource, Paginator, Plugin, type PluginLifecycleSpec, type PluginOptions, RegisterEvent, type RegisterEventOptions, RepliableHandler, type Repliables, ReplySender, Seedcord, SelectMenuHandler, type SentMessage, SlashHandler, type SlashOptions, Subscriber, UserContextMenuHandler, type ValidEventTypes, type ValidInteractionTypes, type ValidNonInteractionKeys, WebhookLog, WinstonConsoleSink, WinstonFileSink, checkBotPermissions, checkPermissions, getConfirmation, hasPermsToAssign, version };
+export { ArraySource, AssignRoleNoticeOverrides, AutocompleteHandler, BaseHandler, ButtonHandler, ChannelMenuHandler, type CheckPermissionOptions, ComponentHandler, type ConfirmOptions, type Core, CursorSource, type DefaultConfirmOptions, Emojis, type EventGateContext, EventHandler, EventMiddleware, type EventSpec, type EventsConfig, type GateContext, Gated, type GatewayBotConfig, type GatewayConfig, GatewayEmoji, type GatewayFile, type GatewayPluginOptions, type GatewayReplyResponse, HasPermsToAssignOptions, IgnoreBots, type InjectedEmojiMap, type InteractionGateContext, InteractionHandler, InteractionMiddleware, MentionableMenuHandler, MessageContextMenuHandler, Middleware, type MiddlewareOptions, MiddlewareType, ModalHandler, Nsfw, type PageContext, type PageSource, Paginator, Plugin, type PluginLifecycleSpec, type PluginOptions, RegisterEvent, type RegisterEventOptions, RepliableHandler, type Repliables, ReplySender, RoleMenuHandler, Seedcord, SelectMenuHandler, type SentMessage, SlashHandler, type SlashOptions, StringMenuHandler, Subscriber, UserContextMenuHandler, UserMenuHandler, type ValidEventTypes, type ValidInteractionTypes, type ValidNonInteractionKeys, WebhookLog, WinstonConsoleSink, WinstonFileSink, checkBotPermissions, checkPermissions, getConfirmation, hasPermsToAssign, version };
 //# sourceMappingURL=index.d.mts.map