@seedcord/gateway 0.1.0-next.5 → 0.1.0

package/dist/index.d.mts

@@ -1,13 +1,12 @@
 import { AnyCustomId, AutocompletableNames, BaseReplySender, ChoiceValueOf, EntryFor, FocusedField, GateFitsWith, HasComponentDefs, MatchArms, ModalLike, PageCursor, SingleParams, SlashOptions as SlashOptions$1 } from "@seedcord/core/internal";
-import { AutocompleteOptions, BaseHandler, BuilderComponent, Bus, CoreBase, DispatchContext, Gate, GateContextBase, GateNoticeOptions, GuildPermissionsContext, Initializeable, Notice, PageView, PermissionScope, RepliableHandler as RepliableHandler$1, RequiredOf, SelectMenuKind, SlashOptionRegistry, Subscriber as Subscriber$1, SubscriptionKey, WebhookLog as WebhookLog$1 } from "@seedcord/core";
+import { ArraySource as ArraySource$1, AutocompleteOptions, BaseHandler, Bus, ContextMenuKind, CoreBase, CursorSource as CursorSource$1, DispatchContext, Gate, GateContextBase, GateNoticeOptions, GuildPermissionsContext, Initializeable, Notice, PaginatorBase, PaginatorConfig, PermissionNoticeOverrides, PermissionScope, RepliableHandler as RepliableHandler$1, RequiredOf, SelectMenuKind, SlashOptionRegistry, Subscriber as Subscriber$1, SubscriptionKey, WebhookLog as WebhookLog$1 } from "@seedcord/core";
 import { Logger } from "@seedcord/logger";
-import { ActionRowBuilder, ButtonBuilder, ContextMenuCommandBuilder, SlashCommandBuilder } from "@discordjs/builders";
-import { APIInteractionGuildMember, APIMessageComponentEmoji, APIModalInteractionResponseCallbackData, AnySelectMenuInteraction, ApplicationCommand, ApplicationCommandOptionChoiceData, ApplicationCommandType, ApplicationEmoji, AutocompleteInteraction, BooleanCache, ButtonInteraction, ButtonStyle, CacheType, CacheTypeReducer, ChannelSelectMenuInteraction, ChatInputCommandInteraction, Client, ClientEvents, ClientOptions, Collection, CommandInteractionOption, ContextMenuCommandInteraction, Events, Guild, GuildEmoji, GuildMember, Interaction, MentionableSelectMenuInteraction, Message, MessageContextMenuCommandInteraction, ModalSubmitInteraction, Role, RoleSelectMenuInteraction, Snowflake, StringSelectMenuInteraction, TextChannel, TextChannelResolvable, User, UserContextMenuCommandInteraction, UserSelectMenuInteraction } from "discord.js";
-import { Plugin as Plugin$1, PluginContext, PluginLifecycleSpec, PluginOptions, PluginOptions as PluginOptions$1 } from "@seedcord/core/plugin";
-import { CoordinatedShutdown, CoordinatedStartup, Pluggable, PluginCapabilities } from "@seedcord/core/node/internal";
+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, 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";
+import { CoordinatedShutdown, CoordinatedStartup, Pluggable } from "@seedcord/core/node/internal";
 import { SeedcordBrand, SeedcordInstance } from "@seedcord/types/internal";
+import { BotConfig, Config, DeferOpts, EmojiMap, EventFrequency, HealthCheckOption, HmrAware, HmrUpdateEvent, IRateLimiter, ReplyResponse, SendOpts, TypedOmit } from "@seedcord/types";
 import { REST } from "@discordjs/rest";
-import { BotConfig, Config, DeferOpts, EmojiMap, EventFrequency, HealthCheckOption, HmrAware, HmrUpdateEvent, IRateLimiter, ReplyResponse, SendOpts, TypedOmit, V2Component } from "@seedcord/types";
 export * from "@seedcord/errors";
 export * from "@seedcord/core";
 export * from "@seedcord/logger";
@@ -16,14 +15,6 @@ export * from "@seedcord/utils";
 export * from "@seedcord/event-emitter";
 export type * from "@seedcord/types";
 
-//#region src/plugin-capabilities.d.ts
-declare module '@seedcord/core' {
-  interface PluginCapabilityTypes {
-    client: Client;
-    rest: REST;
-  }
-}
-//#endregion
 //#region src/subscriptions.d.ts
 declare module '@seedcord/core/internal' {
   interface DefaultSubscriptions {
@@ -84,82 +75,6 @@ interface GatewayConfig extends Config {
   healthCheck?: HealthCheckOption;
 }
 //#endregion
-//#region src/bot/utilities/miscellaneous/contextMenuLeaves.d.ts
-/** The registered context-menu command names, split by kind, deduplicated. @internal */
-interface ContextMenuLeaves {
-  readonly user: Set<string>;
-  readonly message: Set<string>;
-}
-//#endregion
-//#region src/bot/controllers/CommandRegistry.d.ts
-/** The command collections Discord returns from each scope's deploy, keyed by command id. */
-interface DeployResult {
-  global: Collection<Snowflake, ApplicationCommand>;
-  guilds: Collection<Snowflake, Collection<Snowflake, ApplicationCommand>>;
-}
-/**
- * Manages Discord application command registration and deployment.
- *
- * Scans command directories, builds command structures, and registers both global and guild-scoped commands
- * to Discord's API. Accessed via `core.bot.commands`. Do not construct it directly.
- */
-declare class CommandRegistry implements Initializeable, HmrAware {
-  private readonly core;
-  private readonly onDeployed?;
-  private readonly logger;
-  private isInitialised;
-  readonly globalCommands: (SlashCommandBuilder | ContextMenuCommandBuilder)[];
-  readonly guildCommands: Collection<string, (SlashCommandBuilder | ContextMenuCommandBuilder)[]>;
-  private readonly ctorToCommand;
-  private loading;
-  private readonly loadedCommands;
-  private readonly hmrHandler?;
-  private readonly pendingEvents;
-  constructor(core: Core, onDeployed?: ((result: DeployResult) => void) | undefined);
-  private getArtifacts;
-  /** @internal */
-  init(): Promise<void>;
-  private reportLoad;
-  /** @internal */
-  refresh(shouldRefresh?: boolean): Promise<void>;
-  /** @internal */
-  onHmr(event: HmrUpdateEvent): Promise<void>;
-  private loadCommands;
-  private isCommandClass;
-  private registerCommand;
-  private unregisterCommand;
-  /** @internal */
-  setCommands(): Promise<DeployResult>;
-  /** The deduplicated slash route keys across every global and guild command. @internal */
-  routeLeaves(): Set<string>;
-  /** The registered context-menu command names, split by kind, across every global and guild command. @internal */
-  contextMenuLeaves(): ContextMenuLeaves;
-}
-//#endregion
-//#region src/bot/injectors/CommandMentionInjector.d.ts
-/** Each registered slash route mapped to its mention string. */
-type InjectedMentionMap = { [K in keyof SlashOptionRegistry]: string };
-/**
- * Ready-to-send command mention strings, keyed by {@link SlashOptionRegistry}.
- *
- * A value is a clickable `</name:id>` when the command's id resolved from the deploy, otherwise the plain
- * `/name` text. Populated by {@link CommandMentionInjector} after each deploy.
- */
-declare const CommandMentions: InjectedMentionMap;
-//#endregion
-//#region src/bot/injectors/EmojiInjector.d.ts
-/**
- * The global {@link Emojis} accessor type. Each key resolves to its precise class, `GuildEmoji` for a `'guild'`
- * tag and `ApplicationEmoji` for an `'application'` tag, the tags `seedcord codegen` writes into {@link EmojiMap}.
- */
-type InjectedEmojiMap = { [K in keyof EmojiMap]: EmojiMap[K] extends 'guild' ? GuildEmoji : ApplicationEmoji };
-/**
- * Global emoji mappings object
- *
- * @see {@link EmojiMap}
- */
-declare const Emojis: InjectedEmojiMap;
-//#endregion
 //#region src/bot/Bot.d.ts
 /**
  * The Discord client and its controllers. Access it through `core.bot`.
@@ -173,13 +88,12 @@ declare class Bot implements Initializeable, HmrAware {
   private readonly interactions?;
   private readonly events?;
   private readonly emojiInjector;
-  readonly commands?: CommandRegistry;
-  readonly emojis: InjectedEmojiMap;
-  readonly mentions: InjectedMentionMap;
+  private readonly commandRegistry?;
   /** @internal */
   onHmr(event: HmrUpdateEvent): Promise<void>;
   /** @internal */
   constructor(core: Core);
+  private applicationId;
   private registerShutdownTasks;
   private stopAccepting;
   private drain;
@@ -217,6 +131,28 @@ interface Core extends CoreBase {
   readonly config: GatewayConfig;
 }
 //#endregion
+//#region src/interfaces/ReplyResponse.d.ts
+/**
+ * Every file form discord.js accepts in a message's `files` field: `AttachmentBuilder`, `Attachment`, a
+ * `Buffer`, a node `Stream`, a path or URL string, and an `{ attachment, name }` payload.
+ */
+type GatewayFile = NonNullable<BaseMessageOptions['files']>[number];
+/**
+ * A reply that may attach files in any form discord.js accepts, on top of the portable `ReplyFile`. The
+ * reply verbs already take this, so name it only to type a variable or a helper's return. A `Notice`
+ * render or a paginator page returns the plain `ReplyResponse`, which takes a `ReplyFile` alone.
+ *
+ * @example
+ * ```ts
+ * // any discord.js file form
+ * await this.reply({
+ *     components: [container],
+ *     files: [new AttachmentBuilder(createReadStream('./report.pdf'), { name: 'report.pdf' })]
+ * });
+ * ```
+ */
+type GatewayReplyResponse = ReplyResponse<GatewayFile>;
+//#endregion
 //#region src/handlers/interactionTypes.d.ts
 type ValidInteractionTypes = ChatInputCommandInteraction | ButtonInteraction | ModalSubmitInteraction | AutocompleteInteraction | AnySelectMenuInteraction | ContextMenuCommandInteraction;
 type ValidNonInteractionKeys = Exclude<keyof ClientEvents, Events.InteractionCreate>;
@@ -636,16 +572,16 @@ type SentMessage = Message;
  * Writes interaction responses through the discord.js interaction. Construction is internal to the repliable
  * handler bases and the dispatcher.
  */
-declare class ReplySender extends BaseReplySender<SentMessage> {
+declare class ReplySender extends BaseReplySender<SentMessage, GatewayFile> {
   private readonly interaction;
   constructor(interaction: Repliables, routeId: string, bus?: Bus);
-  protected writeReply(response: ReplyResponse | string, opts?: SendOpts): Promise<SentMessage | undefined>;
+  protected writeReply(response: GatewayReplyResponse | string, opts?: SendOpts): Promise<SentMessage | undefined>;
   protected writeDefer(opts?: DeferOpts): Promise<void>;
   protected writeDeferUpdate(): Promise<void>;
-  protected writeUpdate(response: ReplyResponse | string): Promise<SentMessage | undefined>;
-  protected writeFollowUp(response: ReplyResponse | string, opts?: SendOpts): Promise<SentMessage>;
-  protected writeEditOriginal(response: ReplyResponse | string): Promise<SentMessage>;
-  protected writeEditTarget(targetId: string, response: ReplyResponse | string): Promise<SentMessage>;
+  protected writeUpdate(response: GatewayReplyResponse | string): Promise<SentMessage | undefined>;
+  protected writeFollowUp(response: GatewayReplyResponse | string, opts?: SendOpts): Promise<SentMessage>;
+  protected writeEditOriginal(response: GatewayReplyResponse | string): Promise<SentMessage>;
+  protected writeEditTarget(targetId: string, response: GatewayReplyResponse | string): Promise<SentMessage>;
   protected writeDeleteOriginal(): Promise<void>;
   protected writeDeleteTarget(targetId: string): Promise<void>;
   protected writeModal(data: APIModalInteractionResponseCallbackData): Promise<void>;
@@ -668,7 +604,7 @@ declare class ReplySender extends BaseReplySender<SentMessage> {
  *
  * @typeParam Event - The repliable interaction type this handler processes
  */
-declare abstract class RepliableHandler<Event extends Repliables> extends RepliableHandler$1<Event, Core, SentMessage, ReplySender> {
+declare abstract class RepliableHandler<Event extends Repliables> extends RepliableHandler$1<Event, Core, SentMessage, GatewayFile, ReplySender> {
   /** @internal */
   getEvent(): Event;
   protected buildSender(event: Event, core: Core, routeId: string): ReplySender;
@@ -836,7 +772,6 @@ declare abstract class SlashHandler<Route extends keyof SlashOptionRegistry, Cac
 }
 //#endregion
 //#region src/handlers/interaction/ContextMenuHandler.d.ts
-type ContextMenuKind = ApplicationCommandType.User | ApplicationCommandType.Message;
 type InteractionFor<Kind extends ContextMenuKind, Cache extends CacheType> = Kind extends ApplicationCommandType.User ? UserContextMenuCommandInteraction<Cache> : MessageContextMenuCommandInteraction<Cache>;
 type TargetFor<Kind extends ContextMenuKind, Cache extends CacheType> = Kind extends ApplicationCommandType.User ? User : Message<BooleanCache<Cache>>;
 type TargetMemberFor<Kind extends ContextMenuKind, Cache extends CacheType> = Kind extends ApplicationCommandType.User ? CacheTypeReducer<Cache, GuildMember, APIInteractionGuildMember> | null : never;
@@ -959,7 +894,7 @@ declare abstract class ComponentHandler<Event extends ComponentInteraction, Defs
   /** @internal */
   readonly __componentDefs?: Defs;
   /** Rewrite the source message this component interaction came from. */
-  protected update(response: ReplyResponse | string): Promise<SentMessage>;
+  protected update(response: GatewayReplyResponse | string): Promise<SentMessage>;
   /** Acknowledge the component without changing the source message. */
   protected deferUpdate(): Promise<void>;
   private decoded?;
@@ -1057,6 +992,11 @@ 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 __component?: 'modal';
+  /** Rewrite the message this modal was opened from. Throws when a command opened the modal. */
+  protected update(response: GatewayReplyResponse | string): Promise<SentMessage>;
+  /** Acknowledge the submit without changing the source message. Throws when a command opened the modal. */
+  protected deferUpdate(): Promise<void>;
+  private ensureSourceMessage;
 }
 //#endregion
 //#region src/handlers/interaction/components/SelectMenuHandler.d.ts
@@ -1175,182 +1115,100 @@ declare const IgnoreBots: import("@seedcord/core").Gate<EventGateContext<ValidNo
  */
 declare function Nsfw(options?: GateNoticeOptions): Gate<InteractionGateContext<NonModalInteraction>, 'Nsfw'>;
 //#endregion
-//#region src/bot/utilities/channels/fetchText.d.ts
+//#region src/bot/injectors/EmojiInjector.d.ts
 /**
- * Fetches and validates a text channel. Refuses when the channel doesn't exist or isn't a text channel.
- *
- * @param client - The Discord client instance
- * @param channelId - Channel ID or TextChannel instance
- * @returns Promise resolving to the text channel
+ * The global {@link Emojis} accessor type. Each key resolves to its precise class, `GuildEmoji` for a `'guild'`
+ * tag and `ApplicationEmoji` for an `'application'` tag, the tags `seedcord codegen` writes into {@link EmojiMap}.
  */
-declare function fetchText(client: Client, channelId: TextChannelResolvable): Promise<TextChannel>;
-//#endregion
-//#region src/bot/utilities/permissions/checkPermissions.d.ts
+type InjectedEmojiMap = { [K in keyof EmojiMap]: EmojiMap[K] extends 'guild' ? GuildEmoji : ApplicationEmoji };
 /**
- * Optional custom error constructors for {@link CheckPermissionOptions}.
+ * The bot's resolved emojis, keyed by {@link EmojiMap}. Filled by {@link EmojiInjector} during startup.
+ * A read before that throws.
  */
-interface PermissionErrorNoticeOverrides {
-  missingNotice?: new (message: string | undefined, subject: string, missingPerms: readonly string[]) => Notice;
-  dangerousNotice?: new (message: string | undefined, subject: string, dangerousPerms: readonly string[]) => Notice;
-}
+declare const Emojis: InjectedEmojiMap;
+//#endregion
+//#region src/bot/utilities/permissions/checkBotPermissions.d.ts
 /**
- * Options for {@link checkPermissions}.
+ * Checks the bot's own permissions in a {@link Guild} or {@link TextChannel}. Refuses when a permission in
+ * `scope` is missing, or with `inverse` when one is present. When the bot member is uncached, the refusal
+ * reports every permission in `scope` as missing.
  *
- * @see {@link PermissionErrorNoticeOverrides}
+ * @example
+ * ```ts
+ * import { PermissionFlagsBits } from 'discord.js';
+ * import { checkBotPermissions } from '@seedcord/gateway';
+ *
+ * checkBotPermissions(textChannel, [PermissionFlagsBits.SendMessages, PermissionFlagsBits.ViewChannel]);
+ * ```
  */
-interface CheckPermissionOptions extends PermissionErrorNoticeOverrides {
-  /** Role or member whose permissions will be checked */
+declare function checkBotPermissions(target: Guild | TextChannel, scope: PermissionScope, inverse?: boolean, errors?: PermissionNoticeOverrides): void;
+//#endregion
+//#region src/bot/utilities/permissions/checkPermissions.d.ts
+/** Options for {@link checkPermissions}. */
+interface CheckPermissionOptions extends PermissionNoticeOverrides {
+  /** The role or member to check. */
   for: Role | GuildMember;
-  /** Context where permissions apply */
+  /** A guild reads the base bits from roles, a text channel reads the overwrite-resolved set. */
   in: Guild | TextChannel;
-  /** Permission bits to validate */
+  /** The permission flag bits to check. */
   scope: PermissionScope;
-  /** When true, ensure target does NOT have the given permissions */
+  /** Refuse when the target holds a scope bit. */
   inverse?: boolean;
 }
 /**
- * Checks permissions for a {@link Role} or a {@link GuildMember} in a {@link Guild}. Refuses when a
- * permission in `scope` is missing, or with `inverse` when one is present.
- *
- * @param target - Role or member to check
- * @param ctx - Guild context
- * @param scope - Permission bits to validate
- * @param inverse - Whether to ensure absence of the given permissions
- * @param errors - Optional custom error constructors
- *
+ * Checks a {@link Role} or a {@link GuildMember} against the base permission bits in a {@link Guild},
+ * before channel overwrites. Refuses when a permission in `scope` is missing, or with `inverse` when one
+ * is present.
  *
  * @example
  * ```ts
  * import { PermissionFlagsBits } from 'discord.js';
  * import { checkPermissions } from '@seedcord/gateway';
  *
- * // Check if a role has ManageMessages and KickMembers permissions in a guild
- * checkPermissions(role, guild, [
- *   PermissionFlagsBits.ManageMessages,
- *   PermissionFlagsBits.KickMembers
- * ]);
+ * checkPermissions(role, guild, [PermissionFlagsBits.ManageMessages, PermissionFlagsBits.KickMembers]);
  * ```
  *
  * @example
  * ```ts
- * import { PermissionFlagsBits } from 'discord.js';
- * import { checkPermissions } from '@seedcord/gateway';
- *
- * // Ensure a member does NOT have Administrator permission in a guild and show custom errors
- * checkPermissions(member, guild, [
- *   PermissionFlagsBits.Administrator
- * ], true, {
- *   missing: CustomMissingPermissionsError,
- *   dangerous: CustomDangerousPermissionsError
+ * // refuse when the member holds Administrator, and replace the refusal
+ * checkPermissions(member, guild, [PermissionFlagsBits.Administrator], true, {
+ *   dangerousNotice: CustomDangerousNotice
  * });
  * ```
  */
-declare function checkPermissions(target: Role | GuildMember, ctx: Guild, scope: PermissionScope, inverse?: boolean, errors?: PermissionErrorNoticeOverrides): void;
+declare function checkPermissions(target: Role | GuildMember, ctx: Guild, scope: PermissionScope, inverse?: boolean, errors?: PermissionNoticeOverrides): void;
 /**
- * Checks permissions for a {@link Role} or a {@link GuildMember} in a {@link TextChannel}. Refuses when a
- * permission in `scope` is missing, or with `inverse` when one is present.
- *
- * @param target - Role or member to check
- * @param ctx - Channel context
- * @param scope - Permission bits to validate
- * @param inverse - Whether to ensure absence of the given permissions
- * @param errors - Optional custom error constructors
- *
+ * Checks a {@link Role} or a {@link GuildMember} against the overwrite-resolved set in a
+ * {@link TextChannel}. Refuses when a permission in `scope` is missing, or with `inverse` when one is
+ * present.
  *
  * @example
  * ```ts
  * import { PermissionFlagsBits } from 'discord.js';
  * import { checkPermissions } from '@seedcord/gateway';
  *
- * // Check if a role has SendMessages and ViewChannel permissions in a text channel
- * checkPermissions(role, textChannel, [
- *   PermissionFlagsBits.SendMessages,
- *   PermissionFlagsBits.ViewChannel
- * ]);
- * ```
- *
- * @example
- * ```ts
- * import { PermissionFlagsBits } from 'discord.js';
- * import { checkPermissions } from '@seedcord/gateway';
- *
- * // Ensure a member does NOT have ManageChannels permission in a text channel and show custom errors
- * checkPermissions(member, textChannel, [
- *   PermissionFlagsBits.ManageChannels
- * ], true, {
- *   missing: CustomMissingPermissionsError,
- *   dangerous: CustomDangerousPermissionsError
- * });
+ * checkPermissions(role, textChannel, [PermissionFlagsBits.SendMessages, PermissionFlagsBits.ViewChannel]);
  * ```
  */
-declare function checkPermissions(target: Role | GuildMember, ctx: TextChannel, scope: PermissionScope, inverse?: boolean, errors?: PermissionErrorNoticeOverrides): void;
+declare function checkPermissions(target: Role | GuildMember, ctx: TextChannel, scope: PermissionScope, inverse?: boolean, errors?: PermissionNoticeOverrides): void;
 /**
- * Checks permissions using an options object. Refuses when a permission in {@link CheckPermissionOptions.scope} is missing,
- * or with `options.inverse` when one is present.
- *
- * @param options - Complete options for the check
- *
+ * Checks permissions with an options object. Refuses when a permission in
+ * {@link CheckPermissionOptions.scope} is missing, or with `options.inverse` when one is present.
  *
  * @example
  * ```ts
  * import { PermissionFlagsBits } from 'discord.js';
  * import { checkPermissions } from '@seedcord/gateway';
  *
- * // Check permissions using an options object
  * checkPermissions({
  *   for: member,
  *   in: textChannel,
- *   scope: [
- *     PermissionFlagsBits.SendMessages,
- *     PermissionFlagsBits.ViewChannel
- *   ]
- * });
- * ```
- *
- * @example
- * ```ts
- * import { PermissionFlagsBits } from 'discord.js';
- * import { checkPermissions } from '@seedcord/gateway';
- *
- * // Ensure a role does NOT have BanMembers permission in a guild using an options object
- * checkPermissions({
- *   for: role,
- *   in: guild,
- *   scope: [
- *     PermissionFlagsBits.BanMembers
- *   ],
- *   inverse: true,
- *   missing: CustomMissingPermissionsError,
- *   dangerous: CustomDangerousPermissionsError
+ *   scope: [PermissionFlagsBits.SendMessages, PermissionFlagsBits.ViewChannel]
  * });
  * ```
  */
 declare function checkPermissions(options: CheckPermissionOptions): void;
 //#endregion
-//#region src/bot/utilities/permissions/checkBotPermissions.d.ts
-/**
- * Checks if the bot has required permissions in a {@link Guild} or {@link TextChannel}. Refuses when a
- * required permission is missing.
- *
- * @param target - Guild or text channel to check in
- * @param scope - Permission bits to validate
- * @param inverse - Whether to check for absence of the given permissions
- * @param errors - Optional custom error constructors
- *
- * @example
- * ```ts
- * import { PermissionFlagsBits } from 'discord.js';
- * import { checkBotPermissions } from '@seedcord/gateway';
- *
- * // Check if the bot has SendMessages and ViewChannel permissions in a text channel
- * checkBotPermissions(textChannel, [
- *   PermissionFlagsBits.SendMessages,
- *   PermissionFlagsBits.ViewChannel
- * ]);
- * ```
- */
-declare function checkBotPermissions(target: Guild | TextChannel, scope: PermissionScope, inverse?: boolean, errors?: PermissionErrorNoticeOverrides): void;
-//#endregion
 //#region src/bot/utilities/permissions/hasPermsToAssign.d.ts
 /**
  * Optional custom error constructors for {@link HasPermsToAssignOptions}.
@@ -1368,9 +1226,10 @@ interface HasPermsToAssignOptions {
   noticeOverrides?: AssignRoleNoticeOverrides;
 }
 /**
- * Validates if the bot can assign a target role. Refuses when the target role is above the bot's, is managed, or the bot lacks Manage Roles.
+ * Validates that the bot can assign a target role. Refuses when the target role is above the bot's, is managed, or the bot lacks Manage Roles.
  *
  * @param roleOrOptions - Target role or complete options for the check
+ * @throws A `Notice` on refusal, or a `SeedcordError` when the bot has no role in the guild's role cache.
  *
  * @example
  * ```ts
@@ -1392,86 +1251,6 @@ interface HasPermsToAssignOptions {
  */
 declare function hasPermsToAssign(roleOrOptions: Role | HasPermsToAssignOptions): void;
 //#endregion
-//#region src/bot/utilities/roles/fetchRole.d.ts
-/**
- * Fetches a role by ID from a client or guild. Refuses when the role doesn't exist.
- *
- * @param clientOrGuild - Discord client or guild instance
- * @param roleId - The role ID to fetch
- * @returns Promise resolving to the role
- */
-declare function fetchRole(clientOrGuild: Client | Guild, roleId: string): Promise<Role>;
-//#endregion
-//#region src/bot/utilities/roles/getBotRole.d.ts
-/**
- * Gets the bot's managed role in a guild.
- *
- * @param guild - The guild to get the bot role from
- * @returns The bot's managed role in the guild
- * @throws A **SeedcordError** if the client user is unavailable or if the bot role is missing
- */
-declare function getBotRole(guild: Guild): Role;
-//#endregion
-//#region src/bot/utilities/users/fetchGuildMember.d.ts
-/**
- * Fetches a guild member by user ID. Refuses when the user is not in the guild.
- *
- * @param guild - The guild to fetch the member from
- * @param userId - The Discord user ID
- * @returns Promise resolving to the guild member
- */
-declare function fetchGuildMember(guild: Guild, userId: string): Promise<GuildMember>;
-//#endregion
-//#region src/bot/utilities/users/fetchManyGuildMembers.d.ts
-/**
- * Fetches multiple guild members by user IDs.
- *
- * @param guild - The guild to fetch members from
- * @param userIds - Array of Discord user IDs
- * @returns Promise resolving to array of successfully fetched members
- */
-declare function fetchManyGuildMembers(guild: Guild, userIds: string[]): Promise<GuildMember[]>;
-//#endregion
-//#region src/bot/utilities/users/fetchUser.d.ts
-/**
- * Options for {@link fetchUser}.
- */
-interface FetchUserOptions {
-  /** Notice shown when the user does not exist, defaulting to the standard user-not-found notice. */
-  throwAs?: new (userArg: string) => Notice;
-}
-/**
- * Fetches a Discord user by ID. Refuses when the user doesn't exist, with `options.throwAs` or the default.
- *
- * @param client - The Discord client instance
- * @param userId - The Discord user ID
- * @param options - Optional overrides, including the {@link FetchUserOptions.throwAs} notice
- * @returns Promise resolving to the user
- */
-declare function fetchUser(client: Client, userId: string, options?: FetchUserOptions): Promise<User>;
-//#endregion
-//#region src/bot/utilities/users/fetchManyUsers.d.ts
-/**
- * Fetches multiple Discord users by IDs.
- *
- * @param client - The Discord client instance
- * @param userIds - Array of Discord user IDs
- * @param options - Optional overrides threaded to each {@link fetchUser} call
- * @returns Promise resolving to array of successfully fetched users
- */
-declare function fetchManyUsers(client: Client, userIds: string[], options?: FetchUserOptions): Promise<User[]>;
-//#endregion
-//#region src/bot/utilities/users/updateMemberRoles.d.ts
-/**
- * Updates a guild member's roles by adding and removing specified roles.
- *
- * @param rolesToAdd - Array of role IDs to add to the member
- * @param rolesToRemove - Array of role IDs to remove from the member
- * @param member - The guild member to update
- * @returns Promise that resolves when roles are updated
- */
-declare function updateMemberRoles(rolesToAdd: Snowflake[], rolesToRemove: Snowflake[], member: GuildMember): Promise<void>;
-//#endregion
 //#region src/bot/confirm/getConfirmation.d.ts
 type Outcome = ReplyResponse | (() => Promisable<ReplyResponse>);
 /** Options shared by both confirmation forms. */
@@ -1520,10 +1299,10 @@ interface DefaultConfirmOptions extends ConfirmOptions {
 /**
  * Shows a confirm/cancel prompt with built-in Confirm and Cancel buttons and resolves to `true` only if the
  * invoking user clicks confirm. A cancel click or a timeout resolves to `false`. Gate the action behind it
- * with an early return. A failed prompt send throws into the fault boundary. Not usable from a
- * {@link ModalHandler}, the `interaction` parameter excludes a modal submit at compile time.
+ * with an early return. A failed prompt send throws into the fault boundary. A {@link ModalHandler} is
+ * excluded at compile time.
  *
- * @param interaction - The repliable interaction to prompt on, `this.event` inside a non-modal handler.
+ * @param handler - The handler to prompt from, `this` inside a non-modal handler.
  * @param prompt - The message shown above the Confirm and Cancel buttons.
  * @param options - Ephemeral flag, timeout, the built-in buttons' labels and style, and the optional
  *   `onConfirm`/`onCancel`/`onTimeout` outcome replies that edit the prompt in place.
@@ -1537,29 +1316,29 @@ interface DefaultConfirmOptions extends ConfirmOptions {
  * class BanHandler extends SlashHandler<'ban'> {
  *     async execute() {
  *         const target = this.options.getUser('target', true);
- *         if (!(await getConfirmation(this.event, `Ban ${target.tag}? This cannot be undone.`))) return;
+ *         if (!(await getConfirmation(this, `Ban ${target.tag}? This cannot be undone.`))) return;
  *         await this.event.guild?.members.ban(target.id);
  *     }
  * }
  * ```
  */
-declare function getConfirmation(interaction: NonModalInteraction, prompt: string, options?: DefaultConfirmOptions): Promise<boolean>;
+declare function getConfirmation(handler: RepliableHandler<NonModalInteraction>, prompt: string, options?: DefaultConfirmOptions): Promise<boolean>;
 /**
  * Shows a confirm/cancel prompt you build yourself and resolves to `true` only if the invoking user clicks
  * confirm. The factory receives the two minted button ids. Set them on your own buttons. A cancel click or a
- * timeout resolves to `false`. A failed prompt send throws into the fault boundary. Not usable from a
- * {@link ModalHandler}.
+ * timeout resolves to `false`. A failed prompt send throws into the fault boundary. A {@link ModalHandler} is
+ * excluded at compile time.
  *
- * @param interaction - The repliable interaction to prompt on, `this.event` inside a non-modal handler.
+ * @param handler - The handler to prompt from, `this` inside a non-modal handler.
  * @param prompt - A factory given the minted `{ confirm, cancel }` ids that returns the reply to show. Build
- *   it with the kit `BuilderComponent`/`RowComponent` wrappers, not raw discord.js builders.
+ *   it with the `BuilderComponent` and `RowComponent` wrappers.
  * @param options - Ephemeral flag, timeout, and the optional `onConfirm`/`onCancel`/`onTimeout` outcome
  *   replies that edit the prompt in place.
  * @returns `true` if confirmed, `false` on cancel or timeout.
  *
  * @remarks
- * The prompt is collected in-process, so it does not survive a bot restart. Without an outcome hook, deliver
- * a result after confirming with a fresh `interaction.followUp(...)`, the prompt is already gone.
+ * The prompt is collected in-process, so it does not survive a bot restart. Without an outcome hook the
+ * prompt is gone once the user confirms, so deliver the result with a fresh `this.followUp(...)`.
  *
  * @example
  * ```ts
@@ -1589,14 +1368,14 @@ declare function getConfirmation(interaction: NonModalInteraction, prompt: strin
  *
  * const target = this.options.getUser('target', true);
  * const confirmed = await getConfirmation(
- *     this.event,
+ *     this,
  *     (ids) => ({ components: [new BanPrompt(`Ban ${target.tag}?`).component, new ConfirmRow(ids).component] }),
  *     { onConfirm: { components: [new BanPrompt(`Banned ${target.tag}.`).component] } }
  * );
  * if (!confirmed) return;
  * ```
  */
-declare function getConfirmation(interaction: NonModalInteraction, prompt: (ids: {
+declare function getConfirmation(handler: RepliableHandler<NonModalInteraction>, prompt: (ids: {
   confirm: string;
   cancel: string;
 }) => Promisable<ReplyResponse>, options?: ConfirmOptions): Promise<boolean>;
@@ -1612,103 +1391,11 @@ interface PageContext {
   user: User;
   /** The guild, or `null` in a DM. */
   guild: Guild | null;
-  /** The framework core, passed only when a source requires framework services. */
-  core?: Core;
-}
-//#endregion
-//#region src/pagination/controls.d.ts
-/** The five built-in nav controls. */
-type ControlKey = 'first' | 'prev' | 'indicator' | 'next' | 'last';
-type CustomIdStyle = ButtonStyle.Primary | ButtonStyle.Secondary | ButtonStyle.Success | ButtonStyle.Danger;
-/** Cosmetic overrides for a control button. `style` excludes Link and Premium, which would un-route it. */
-interface ControlCosmetics {
-  label?: string;
-  style?: CustomIdStyle;
-  emoji?: APIMessageComponentEmoji;
-}
-/** The controls passed to `render`. Each accessor returns a fresh builder stamped with its target page. */
-interface PaginatorControls {
-  /**
-   * A fresh `ButtonBuilder` for one control, already stamped with its target page and disabled-at-bounds
-   * state. Call only cosmetic setters on it, a `setCustomId` or `setStyle(Link)` un-routes it.
-   */
-  button(key: ControlKey, cosmetics?: ControlCosmetics): ButtonBuilder;
-  /**
-   * Assemble an action row of the chosen controls, in order. Throws on an empty set, more than five
-   * controls, or a duplicate.
-   */
-  row(...keys: ControlKey[]): ActionRowBuilder<ButtonBuilder>;
-}
-//#endregion
-//#region src/pagination/render.d.ts
-/** What `renderItem` returns for one item, a text line or a section. */
-type ItemRender<Item> = (item: Item, index: number) => string | BuilderComponent<'section'>;
-/** What the V2 reply can be built from. Each arm is normalized into a {@link ReplyResponse}. */
-type Renderable = string | V2Component[] | ReplyResponse;
-/** A full-page render override, handed the page data and the controls factory. */
-type PageRender<Item> = (view: PageView<Item>, controls: PaginatorControls) => Renderable;
-//#endregion
-//#region src/pagination/sources.d.ts
-/**
- * The one method a paginator calls on a source, once per click. Implement it to supply a custom source.
- *
- * @typeParam Item - The item type the source pages over.
- */
-interface PageSource<Item> {
-  page(ctx: PageContext, n: number): Promise<PageView<Item>>;
-}
-/**
- * A source for a bounded list you can load whole. It loads the full list on every click, then slices the
- * page via {@link paginate}, so the real total is known (a real last button, "Page X of Y"). Cache inside
- * your loader if the load is expensive.
- *
- * @typeParam Item - The item type, inferred from the loader's return.
- */
-declare class ArraySource<Item> implements PageSource<Item> {
-  private readonly load;
-  private readonly perPage;
-  constructor(load: (ctx: PageContext) => Promisable<readonly Item[]>, opts?: {
-    perPage?: number;
-  });
-  page(ctx: PageContext, n: number): Promise<PageView<Item>>;
-}
-/**
- * A source for a large or unknown-length set you fetch one page at a time (SQL LIMIT/OFFSET, a paged API).
- * The fetcher receives the page index and the page size and reports whether a next page exists. A cursor
- * source has no cheap total, so `totalPages` is undefined, the last button is omitted, and the indicator
- * reads "Page X".
- *
- * @typeParam Item - The item type, inferred from the fetcher's slice.
- */
-declare class CursorSource<Item> implements PageSource<Item> {
-  private readonly fetch;
-  private readonly perPage;
-  constructor(fetch: (ctx: PageContext, page: number, perPage: number) => Promisable<{
-    items: readonly Item[];
-    hasNext: boolean;
-  }>, opts?: {
-    perPage?: number;
-  });
-  page(ctx: PageContext, n: number): Promise<PageView<Item>>;
+  /** The framework core. */
+  core: Core;
 }
 //#endregion
 //#region src/pagination/Paginator.d.ts
-interface PaginatorConfig<Item, Prefix extends string> {
-  /** The route prefix used to build the page cursor on the nav buttons. */
-  prefix: Prefix;
-  /** Where the page data comes from. */
-  source: PageSource<Item>;
-  /** Render one item, `index` is its absolute position across pages. Ignored when `render` is set. */
-  renderItem?: ItemRender<Item>;
-  /** Take over the whole page tree. Receives the page data and the controls factory. */
-  render?: PageRender<Item>;
-  /**
-   * Whether the first page is ephemeral.
-   *
-   * @defaultValue `false`
-   */
-  ephemeral?: boolean;
-}
 type PaginatorHandlerCtor<Prefix extends string> = new (event: ButtonInteraction<'cached'>, core: Core) => ButtonHandler<[PageCursor<Prefix>]> & {
   execute(): Promise<void>;
 };
@@ -1731,23 +1418,38 @@ type PaginatorHandlerCtor<Prefix extends string> = new (event: ButtonInteraction
  * export class BansNav extends Bans.Handler {}
  * ```
  */
-declare class Paginator<Item, const Prefix extends string> {
-  /** The page cursor, pass it to your `@ButtonRoute`. */
-  readonly cursor: PageCursor<Prefix>;
+declare class Paginator<Item, const Prefix extends string> extends PaginatorBase<Item, Prefix, PageContext> {
   /** The nav handler base. Extend it with an empty body and decorate it, `@ButtonRoute(p.cursor)`. */
   readonly Handler: PaginatorHandlerCtor<Prefix>;
-  private readonly config;
-  constructor(config: PaginatorConfig<Item, Prefix>);
+  constructor(config: PaginatorConfig<Item, Prefix, PageContext>);
   /**
-   * Render page 0 and send it through the handler's sender, picking reply or followUp from its ack state.
+   * Render page 0 and send it through the handler's sender, which picks reply, edit, or followUp from its
+   * ack state.
    *
    * @param handler - The handler starting the paginator, normally `this`.
    */
   start(handler: RepliableHandler<Repliables>): Promise<Message>;
-  /** Render a page as a {@link ReplyResponse}. To post it elsewhere, add `flags: MessageFlags.IsComponentsV2`. */
-  page(ctx: PageContext, n: number): Promise<ReplyResponse>;
 }
 //#endregion
+//#region src/pagination/sources.d.ts
+/**
+ * A source for a bounded list you can load whole. It loads the full list on every click, then slices the
+ * page, so the real total is known (a real last button, "Page X of Y"). Cache inside your loader if the
+ * load is expensive.
+ *
+ * @typeParam Item - The item type, inferred from the loader's return.
+ */
+declare class ArraySource<Item> extends ArraySource$1<Item, PageContext> {}
+/**
+ * A source for a large or unknown-length set you fetch one page at a time (SQL LIMIT/OFFSET, a paged API).
+ * The fetcher receives the page index and the page size and reports whether a next page exists. A cursor
+ * source has no cheap total, so `totalPages` is undefined, the last button is omitted, and the indicator
+ * reads "Page X".
+ *
+ * @typeParam Item - The item type, inferred from the fetcher's slice.
+ */
+declare class CursorSource<Item> extends CursorSource$1<Item, PageContext> {}
+//#endregion
 //#region src/subscribers/index.d.ts
 /**
  * Base class for a gateway subscriber, binding `this.core` to the gateway {@link Core}.
@@ -1772,9 +1474,9 @@ type GatewayPluginOptions = TypedOmit<PluginOptions$1, 'transport'> & {
  * Base class for a gateway plugin, binding `this.core` to the gateway {@link Core}.
  *
  * A plugin that runs on either transport extends the base from `@seedcord/core/plugin`, whose
- * `this.core` carries the shared members only.
+ * `this.core` is typed to the shared members only.
  *
- * @typeParam Opts - The transport, runtime, and capabilities the plugin declares.
+ * @typeParam Opts - The transport and runtime the plugin declares.
  */
 declare abstract class Plugin<Opts extends GatewayPluginOptions = {}> extends Plugin$1<Opts, Core> {}
 //#endregion
@@ -1798,6 +1500,8 @@ declare class Seedcord extends Pluggable<'gateway', 'server'> implements Core, S
   private readonly subscribers;
   /** @see {@link Bot} */
   readonly bot: Bot;
+  /** The discord.js client's REST client. Its token is set during the Login phase. */
+  readonly rest: REST;
   /** @see {@link IRateLimiter} */
   readonly rateLimiter: IRateLimiter;
   /**
@@ -1807,7 +1511,6 @@ declare class Seedcord extends Pluggable<'gateway', 'server'> implements Core, S
   constructor(config: GatewayConfig);
   /** The bot's discord username, populated after login. */
   get username(): string | undefined;
-  protected pluginCapabilities(): PluginCapabilities;
   protected static reset(): void;
   private registerStartupTasks;
   /**
@@ -1823,5 +1526,5 @@ declare class Seedcord extends Pluggable<'gateway', 'server'> implements Core, S
 /** Package version */
 declare const version: string;
 //#endregion
-export { ArraySource, AssignRoleNoticeOverrides, AutocompleteHandler, ButtonHandler, type CheckPermissionOptions, CommandMentions, type ConfirmOptions, ContextMenuHandler, type Core, CursorSource, type DefaultConfirmOptions, Emojis, type EventGateContext, EventHandler, EventMiddleware, type EventSpec, type EventsConfig, FetchUserOptions, type GateContext, Gated, type GatewayBotConfig, type GatewayConfig, type GatewayPluginOptions, HasPermsToAssignOptions, IgnoreBots, type InjectedEmojiMap, type InjectedMentionMap, type InteractionGateContext, InteractionHandler, InteractionMiddleware, Middleware, type MiddlewareOptions, MiddlewareType, ModalHandler, Nsfw, Paginator, type PaginatorControls, type PermissionErrorNoticeOverrides, Plugin, type PluginContext, type PluginLifecycleSpec, type PluginOptions, RegisterEvent, type RegisterEventOptions, RepliableHandler, type Repliables, Seedcord, SelectMenuHandler, SlashHandler, type SlashOptions, Subscriber, type ValidEventTypes, type ValidInteractionTypes, type ValidNonInteractionKeys, WebhookLog, checkBotPermissions, checkPermissions, fetchGuildMember, fetchManyGuildMembers, fetchManyUsers, fetchRole, fetchText, fetchUser, getBotRole, getConfirmation, hasPermsToAssign, updateMemberRoles, version };
+export { ArraySource, AssignRoleNoticeOverrides, AutocompleteHandler, ButtonHandler, type CheckPermissionOptions, type ConfirmOptions, ContextMenuHandler, type Core, CursorSource, type DefaultConfirmOptions, Emojis, type EventGateContext, EventHandler, EventMiddleware, type EventSpec, type EventsConfig, type GateContext, Gated, type GatewayBotConfig, type GatewayConfig, type GatewayFile, type GatewayPluginOptions, type GatewayReplyResponse, HasPermsToAssignOptions, IgnoreBots, type InjectedEmojiMap, type InteractionGateContext, InteractionHandler, InteractionMiddleware, Middleware, type MiddlewareOptions, MiddlewareType, ModalHandler, Nsfw, type PageContext, Paginator, Plugin, type PluginLifecycleSpec, type PluginOptions, RegisterEvent, type RegisterEventOptions, RepliableHandler, type Repliables, Seedcord, SelectMenuHandler, SlashHandler, type SlashOptions, Subscriber, type ValidEventTypes, type ValidInteractionTypes, type ValidNonInteractionKeys, WebhookLog, checkBotPermissions, checkPermissions, getConfirmation, hasPermsToAssign, version };
 //# sourceMappingURL=index.d.mts.map