@seedcord/gateway 0.1.0-next.3 → 0.1.0-next.5

package/dist/index.d.mts

@@ -1,27 +1,46 @@
 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, CoreBase, DispatchContext, Gate, GateContextBase, GateNoticeOptions, GuildPermissionsContext, Notice, PageView, PermissionScope, RepliableHandler as RepliableHandler$1, RequiredOf, SelectMenuKind, SlashOptionRegistry } from "@seedcord/core";
+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 { 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 { UUID } from "node:crypto";
-import { EventMap, NoEvents, TypedEventEmitter } from "@seedcord/event-emitter";
-import { APIMessageTopLevelComponent } from "discord-api-types/v10";
-import { CoordinatedShutdown, CoordinatedStartup, ShutdownPhase, StartupPhase, StartupPhase as StartupPhase$1 } from "@seedcord/core/node";
+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 { SeedcordBrand, SeedcordInstance } from "@seedcord/types/internal";
-import { BotConfig, Config, DeferOpts, EmojiMap, HmrAware, HmrUpdateEvent, IRateLimiter, ReplyResponse, SendOpts, Tail, V2Component } 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";
-export * from "@seedcord/event-emitter";
-export * from "@seedcord/utils";
 export * from "@seedcord/rate-limiter";
+export * from "@seedcord/utils";
+export * from "@seedcord/event-emitter";
 export type * from "@seedcord/types";
 
-//#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>;
+//#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 {
+    /** Triggered when an event dispatch throws past the fault boundary. */
+    unhandledEventError: {
+      error: Error;
+    };
+    /** Triggered for every client event the bot receives, before its handlers run. */
+    anyEvent: { [Name in keyof ClientEvents]: {
+      name: Name;
+      args: ClientEvents[Name];
+    } }[keyof ClientEvents];
+    /** Triggered for every interaction the bot receives, before routing. */
+    anyInteraction: {
+      interaction: Interaction;
+    };
+  }
 }
 //#endregion
 //#region src/interfaces/Config.d.ts
@@ -56,250 +75,20 @@ interface GatewayBotConfig extends BotConfig {
  */
 interface GatewayConfig extends Config {
   bot: GatewayBotConfig;
-}
-//#endregion
-//#region src/interfaces/Plugin.d.ts
-interface Initializeable {
-  init(): Promise<void>;
-}
-/**
- * Base class for Seedcord plugins
- *
- * 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<TPluginEvents extends EventMap<TPluginEvents> = NoEvents> extends TypedEventEmitter<TPluginEvents> implements Initializeable, HmrAware {
-  protected pluggable: Core;
-  abstract logger: Logger;
-  name: string;
-  constructor(pluggable: Core);
-  /** @virtual */
-  abstract init(): Promise<void>;
+  /** The gateway websocket requires a persistent process, so `'server'` is the only value. */
+  runtime?: 'server';
   /**
-   * Reloads plugin state on an HMR update. The base implementation is a no-op, override it in your plugin.
-   * @virtual
+   * The health-check server. `false` disables it, `true` or omit for the defaults, an object
+   * configures it.
    */
-  onHmr(_event: HmrUpdateEvent): Promise<void>;
-  /**
-   * Registers critical file patterns that should trigger a full restart when changed in Dev HMR.
-   * @param patterns - Glob patterns relative to the project root
-   */
-  protected registerCriticalFiles(patterns: string[]): void;
-  /** @internal */
-  removeListener<TEventKey extends Extract<keyof TPluginEvents, string | symbol>>(event: TEventKey, listener: (...args: TPluginEvents[TEventKey]) => void): this;
-  /** @internal */
-  removeAllListeners(event?: Extract<keyof TPluginEvents, string | symbol>): this;
-}
-/**
- * Constructor type for plugins that can accept extra arguments after Core.
- *
- * @internal
- */
-type PluginCtor<TPlugin extends Plugin = Plugin> = new (core: Core, ...args: any[]) => TPlugin;
-/**
- * Extracts the argument types for a plugin constructor, excluding the Core parameter.
- *
- * @internal
- */
-type PluginArgs<Ctor extends PluginCtor> = Tail<ConstructorParameters<Ctor>>;
-/**
- * Base class for objects that can have plugins attached.
- *
- * Provides plugin attachment capabilities and lifecycle management. Plugins are attached during
- * configuration and initialized during startup. Not constructed directly, the host is a {@link Seedcord}.
- */
-declare class Pluggable<TPluggableEvents extends EventMap<TPluggableEvents> = NoEvents> extends TypedEventEmitter<TPluggableEvents> {
-  protected isInitialized: boolean;
-  protected readonly shutdown: CoordinatedShutdown;
-  protected readonly startup: CoordinatedStartup;
-  protected readonly plugins: Plugin[];
-  private static readonly PLUGIN_INIT_TIMEOUT_MS;
-  constructor(shutdown: CoordinatedShutdown, startup: CoordinatedStartup);
-  /** @internal */
-  protected init(): Promise<this>;
-  /**
-   * Attaches a plugin to this instance
-   *
-   * Plugins provide external functionality and are initialized during the specified startup phase.
-   * The plugin instance becomes available as a property in `core` wherever it's available.
-   *
-   * Make sure to augment the {@link Core} interface with the plugin type to ensure TypeScript recognizes it and provides intellisense.
-   *
-   * @typeParam Key - The property name for accessing the plugin
-   * @typeParam Ctor - The plugin constructor type
-   * @param key - Property name to access the plugin instance
-   * @param Plugin - Plugin constructor class
-   * @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 A **SeedcordError** When called after initialization or if key already exists
-   * @example
-   * ```typescript
-   * seedcord.attach('db', Mongo, StartupPhase.Configuration, { uri: 'mongodb://...', name: 'seedcord', dir: ... })
-   * ```
-   */
-  attach<Key extends string, Ctor extends PluginCtor>(this: this, key: Key, Plugin: Ctor, startupPhase: StartupPhase$1, ...args: PluginArgs<Ctor>): this & Record<Key, InstanceType<Ctor>>;
-  /** @internal */
-  removeListener<TEventKey extends Extract<keyof TPluggableEvents, string | symbol>>(event: TEventKey, listener: (...args: TPluggableEvents[TEventKey]) => void): this;
-  /** @internal */
-  removeAllListeners(event?: Extract<keyof TPluggableEvents, string | symbol>): this;
+  healthCheck?: HealthCheckOption;
 }
 //#endregion
-//#region src/subscribers/types/Subscriptions.d.ts
-/**
- * Where a reported fault came from.
- */
-type FaultSource = InteractionFaultSource | EventFaultSource;
-/**
- * A fault that came from a discord interaction, JSON-safe for a webhook payload.
- */
-interface InteractionFaultSource {
-  kind: 'interaction';
-  interactionKind: 'slash' | 'context-menu' | 'button' | 'select' | 'modal';
-  /** Slash or context-menu command name, null for component and modal interactions. */
-  command: string | null;
-  /** Component or modal customId, null for slash and context-menu interactions. */
-  customId: string | null;
-  userId: string;
-  /** Guild the interaction came from, null in DMs. */
-  guildId: string | null;
-  /** Channel the interaction came from, null when unavailable. */
-  channelId: string | null;
-  interactionId: string;
-  /** The raw interaction, made JSON-safe at serialization with filterCirculars. */
-  raw: unknown;
-}
-/**
- * A fault that came from a client event, JSON-safe for a webhook payload. The actor, guild, and channel
- * are best-effort, derived from the event args, so each is nullable. The raw args carry the full detail.
- */
-interface EventFaultSource {
-  kind: 'event';
-  eventName: string;
-  handler: string;
-  userId: string | null;
-  /** Null outside a guild. */
-  guildId: string | null;
-  channelId: string | null;
-  /** The raw event args, made JSON-safe at serialization with filterCirculars. */
-  raw: unknown;
-}
-interface DefaultSubscriptions {
-  /** Triggered when an unhandled exception (a raw non-Notice throw) occurs */
-  unknownException: {
-    uuid: UUID;
-    error: Error;
-    guild?: {
-      id: string;
-      name: string;
-    } | undefined;
-    user?: {
-      id: string;
-      username: string;
-    } | undefined;
-    metadata?: unknown;
-  };
-  /** Triggered when a reported Notice (`report: true`) is caught */
-  handledException: {
-    denial: Notice;
-    uuid: UUID;
-    source: FaultSource;
-  };
-}
-/**
- * Custom subscribers defined by the application. Augment it via declaration merging to type your
- * own subscriber payloads.
- *
- * @example
- * ```typescript
- * declare module '@seedcord/gateway' {
- *   interface Subscriptions {
- *     'userJoin': { userId: string; guildId: string };
- *     'levelUp': { userId: string; level: number };
- *   }
- * }
- * ```
- */
-interface Subscriptions {}
-interface AllSubscriptions extends DefaultSubscriptions, Subscriptions {}
-/** All subscriber event names available to publish and augment. */
-type SubscriptionKey = keyof AllSubscriptions;
-/**
- * The payload type for a subscriber event.
- *
- * @typeParam KeyOfSubscribers - The subscriber event name
- */
-type SubscriptionData<KeyOfSubscribers extends SubscriptionKey> = AllSubscriptions[KeyOfSubscribers];
-type SubscriptionTuples = { [K in SubscriptionKey]: [AllSubscriptions[K]] };
-//#endregion
-//#region src/subscribers/Bus.d.ts
-/**
- * Registers and dispatches subscribers. Subscribers load from the configured directories and run
- * on a programmatic or framework-event publish. Accessed via `core.bus`. Do not construct it directly.
- */
-declare class Bus extends Plugin<SubscriptionTuples> {
-  protected core: Core;
-  readonly logger: Logger;
-  /** @internal */
-  readonly name = "Subscribers";
-  private isInitialized;
-  private readonly subscribersMap;
-  private readonly executedOnceHandlers;
-  private readonly webhookProbes;
-  private readonly hmrHandler?;
-  constructor(core: Core);
-  private getArtifacts;
-  /** @internal */
-  init(): Promise<void>;
-  /** @internal Exposed for tests. */
-  verifyWebhooks(): Promise<void>;
-  /** @internal */
-  onHmr(event: HmrUpdateEvent): Promise<void>;
-  private loadSubscribers;
-  private registerSubscriber;
-  private unregisterSubscriber;
-  private isSubscriber;
-  /**
-   * Publishes an event to its subscribers and native listeners.
-   *
-   * Fire-and-forget, so subscriber handlers run asynchronously and this returns before they
-   * complete, and callers must not assume side effects have landed. Errors thrown by a subscriber
-   * are caught and logged, never surfaced here. A `'once'` subscriber is marked as executed when
-   * it starts (even if it throws), so it never runs twice.
-   *
-   * @param event - The subscription key to publish
-   * @param data - Payload passed to each subscriber
-   * @returns Whether the underlying emitter had native listeners for the event
-   */
-  publish<KeyOfSubscribers extends SubscriptionKey>(event: KeyOfSubscribers, data: AllSubscriptions[KeyOfSubscribers]): boolean;
-  private processSubscriber;
-}
-//#endregion
-//#region src/interfaces/Core.d.ts
-/**
- * Main interface for Seedcord core functionality
- *
- * This interface can be augmented via declaration merging to add
- * type-safe plugin definitions when using `this.core#` in handlers.
- *
- * Only add classes that extend {@link Plugin} to this
- *
- * @example
- * ```typescript
- * declare module '@seedcord/gateway' {
- *   interface Core {
- *     db: Mongo;
- *   }
- * }
- * ```
- * */
-interface Core extends CoreBase, SeedcordInstance {
-  readonly shutdown: CoordinatedShutdown;
-  readonly startup: CoordinatedStartup;
-  readonly bot: Bot;
-  readonly bus: Bus;
-  readonly config: GatewayConfig;
-  start(): Promise<this>;
+//#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
@@ -317,7 +106,6 @@ interface DeployResult {
 declare class CommandRegistry implements Initializeable, HmrAware {
   private readonly core;
   private readonly onDeployed?;
-  readonly name = "Commands";
   private readonly logger;
   private isInitialised;
   readonly globalCommands: (SlashCommandBuilder | ContextMenuCommandBuilder)[];
@@ -374,26 +162,9 @@ declare const Emojis: InjectedEmojiMap;
 //#endregion
 //#region src/bot/Bot.d.ts
 /**
- * Types of events emitted by the {@link Core.bot} instance.
- */
-interface BotEvents {
-  /** Emitted when an unhandled interaction error occurs */
-  'error:unhandled:interaction': [error: Error];
-  /** Emitted when an unhandled event error occurs */
-  'error:unhandled:event': [error: Error];
-  /** Emitted for any event */
-  'any:event': { [K in keyof ClientEvents]: [K, ...ClientEvents[K]] }[keyof ClientEvents];
-  /** Emitted for any interaction */
-  'any:interaction': [interaction: Interaction];
-  /** @internal */
-  ready: [];
-}
-/**
- * Discord bot implementation that manages client and controllers
- *
- * Don't instantiate this class directly. Use `core.bot` instead.
+ * The Discord client and its controllers. Access it through `core.bot`.
  */
-declare class Bot extends Plugin<BotEvents> {
+declare class Bot implements Initializeable, HmrAware {
   readonly botToken: string;
   /** @internal */
   readonly logger: Logger;
@@ -401,47 +172,49 @@ declare class Bot extends Plugin<BotEvents> {
   private readonly _client;
   private readonly interactions?;
   private readonly events?;
-  readonly commands?: CommandRegistry;
   private readonly emojiInjector;
+  readonly commands?: CommandRegistry;
   readonly emojis: InjectedEmojiMap;
   readonly mentions: InjectedMentionMap;
-  /** @internal For use in dev mode */
+  /** @internal */
   onHmr(event: HmrUpdateEvent): Promise<void>;
   /** @internal */
   constructor(core: Core);
-  /**
-   * Initializes Discord client and all controllers
-   * @internal
-   */
+  private registerShutdownTasks;
+  private stopAccepting;
+  private drain;
+  /** @internal */
   init(): Promise<void>;
-  /**
-   * Stops the bot and cleans up connections
-   * @internal
-   */
+  /** @internal */
   stop(): Promise<void>;
-  /**
-   * Logs the bot into Discord using the configured token
-   */
   private login;
-  /**
-   * Logs out and destroys the Discord client connection
-   */
   private logout;
   get client(): Client;
-  /**
-   * Emits a Discord event with its argument tuple. The overloads enforce the key/args correlation
-   * at compile time only; at runtime this forwards straight to the underlying EventEmitter.
-   *
-   * @internal
-   */
-  emit<TKey extends keyof ClientEvents>(event: 'any:event', name: TKey, ...args: ClientEvents[TKey]): boolean;
-  /** @internal */
-  emit<TEventKey extends keyof BotEvents>(event: TEventKey, ...args: BotEvents[TEventKey]): boolean;
-  /** @internal */
-  emitSafe<TKey extends keyof ClientEvents>(event: 'any:event', name: TKey, ...args: ClientEvents[TKey]): boolean;
-  /** @internal */
-  emitSafe<TEventKey extends keyof BotEvents>(event: TEventKey, ...args: BotEvents[TEventKey]): boolean;
-  protected onListenerError(error: unknown, event: string | symbol): void;
+}
+//#endregion
+//#region src/interfaces/Core.d.ts
+/**
+ * Main interface for Seedcord core functionality
+ *
+ * This interface can be augmented via declaration merging to add
+ * type-safe plugin definitions when using `this.core#` in handlers.
+ *
+ * Only add classes that extend {@link Plugin} to this
+ *
+ * @example
+ * ```typescript
+ * declare module '@seedcord/gateway' {
+ *   interface Core {
+ *     db: Mongoose;
+ *   }
+ * }
+ * ```
+ * */
+interface Core extends CoreBase {
+  readonly shutdown: Pick<CoordinatedShutdown, 'addTask'>;
+  readonly startup: Pick<CoordinatedStartup, 'addTask'>;
+  readonly bot: Bot;
+  readonly config: GatewayConfig;
 }
 //#endregion
 //#region src/handlers/interactionTypes.d.ts
@@ -659,7 +432,7 @@ type EventMatchArms<Names extends ValidNonInteractionKeys, Ret> = { [Name in Nam
  * }
  * ```
  */
-declare abstract class EventHandler<Names extends ValidNonInteractionKeys> extends BaseHandler$1<ClientEvents[Names]> {
+declare abstract class EventHandler<in out Names extends ValidNonInteractionKeys> extends BaseHandler$1<ClientEvents[Names]> {
   private readonly firedEvent;
   constructor(event: ClientEvents[Names], core: Core, eventName?: Names);
   protected readonly event: SingleEventPayload<Names>;
@@ -715,12 +488,6 @@ declare abstract class EventMiddleware<in out EventName extends ValidNonInteract
   protected get eventName(): EventName;
 }
 //#endregion
-//#region src/miscellaneous/types.d.ts
-/**
- * The frequency at which the event handler should be executed.
- */
-type EventFrequency = 'once' | 'on';
-//#endregion
 //#region src/bot/decorators/Events.d.ts
 /** Options accepted by the event registration decorator. */
 interface RegisterEventOptions {
@@ -871,7 +638,7 @@ type SentMessage = Message;
  */
 declare class ReplySender extends BaseReplySender<SentMessage> {
   private readonly interaction;
-  constructor(interaction: Repliables, routeId: string);
+  constructor(interaction: Repliables, routeId: string, bus?: Bus);
   protected writeReply(response: ReplyResponse | string, opts?: SendOpts): Promise<SentMessage | undefined>;
   protected writeDefer(opts?: DeferOpts): Promise<void>;
   protected writeDeferUpdate(): Promise<void>;
@@ -904,7 +671,7 @@ declare class ReplySender extends BaseReplySender<SentMessage> {
 declare abstract class RepliableHandler<Event extends Repliables> extends RepliableHandler$1<Event, Core, SentMessage, ReplySender> {
   /** @internal */
   getEvent(): Event;
-  protected buildSender(event: Event, _core: Core, routeId: string): ReplySender;
+  protected buildSender(event: Event, core: Core, routeId: string): ReplySender;
 }
 //#endregion
 //#region src/handlers/interaction/InteractionHandler.d.ts
@@ -1348,7 +1115,7 @@ interface MiddlewareOptions<MType extends MiddlewareType, Events extends readonl
  * Interaction middleware cannot specify event filters.
  *
  * @param type - Middleware kind from {@link MiddlewareType}
- * @param priority - Ordering value where lower runs earlier. {@default `0`}
+ * @param priority - Ordering value where lower runs earlier. {@default `0` }
  * @param options - Additional registration options
  *
  * @decorator
@@ -1971,179 +1738,52 @@ declare class Paginator<Item, const Prefix extends string> {
   readonly Handler: PaginatorHandlerCtor<Prefix>;
   private readonly config;
   constructor(config: PaginatorConfig<Item, Prefix>);
-  /** Render page 0 and send it, picking reply or followUp from the interaction's state. */
-  start(interaction: Repliables, core?: Core): 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/subscribers/Subscriber.d.ts
-/**
- * Abstract base class for handling application subscribers.
- *
- * Provides type-safe access to subscribers data and the core framework instance.
- * Extend this class to create custom subscriber handlers.
- *
- * @typeParam KeyOfSubscribers - The specific subscriber type this handler processes
- */
-declare abstract class Subscriber<KeyOfSubscribers extends SubscriptionKey> {
-  protected readonly data: AllSubscriptions[KeyOfSubscribers];
-  protected readonly core: Core;
-  protected readonly logger: Logger;
   /**
-   * Instantiates the subscriber with event data and core.
+   * Render page 0 and send it through the handler's sender, picking reply or followUp from its ack state.
    *
-   * @param data - The subscriber event data
-   * @param core - The core framework instance
+   * @param handler - The handler starting the paginator, normally `this`.
    */
-  constructor(data: AllSubscriptions[KeyOfSubscribers], core: Core);
-  /**
-   * Executes the subscriber handler logic.
-   */
-  abstract execute(): Promise<void>;
-}
-//#endregion
-//#region src/subscribers/decorators/Subscribe.d.ts
-/**
- * Options accepted by the `@Subscribe` decorator.
- */
-interface SubscribeOptions {
-  /**
-   * Frequency: `'once'` or `'on'`.
-   *
-   * @defaultValue `'on'`
-   */
-  readonly frequency?: EventFrequency | undefined;
+  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>;
 }
-/**
- * Registers a subscriber handler class with a specific subscriber event.
- *
- * Associates the decorated class with a subscriber event type for automatic
- * registration and execution when the subscriber is emitted.
- *
- * @typeParam TSubscriber - The subscriber event name to register for
- * @param subscriber - The subscriber event name to register for
- * @param options - Options to configure the subscriber handler registration.
- * @decorator
- * @example
- * ```typescript
- * \@Subscribe('userJoin')
- * class WelcomeHandler extends Subscriber<'userJoin'> {
- *   async execute() {
- *     // Handle user join event
- *   }
- * }
- * ```
- * @example
- * ```ts
- * \@Subscribe('userJoin', { frequency: 'once' })
- * // or
- * \@Subscribe('userJoin')
- * ```
- */
-declare function Subscribe<TSubscriber extends SubscriptionKey>(subscriber: TSubscriber, options?: SubscribeOptions): <HandlerCtor extends Constructor<Subscriber<TSubscriber>>>(constructor: HandlerCtor) => void;
 //#endregion
-//#region src/subscribers/bases/WebhookSender.d.ts
+//#region src/subscribers/index.d.ts
 /**
- * A file attached to a webhook report.
- */
-interface WebhookFile {
-  name: string;
-  description: string;
-  data: Buffer;
-}
-/**
- * The payload {@link WebhookSender.send} posts.
- */
-interface WebhookSendOptions {
-  flags: number;
-  username: string;
-  components: readonly {
-    toJSON(): APIMessageTopLevelComponent;
-  }[];
-  files?: readonly WebhookFile[] | undefined;
-}
-/**
- * Sends component messages to a Discord webhook through `@discordjs/rest`.
+ * Base class for a gateway subscriber, binding `this.core` to the gateway {@link Core}.
  *
- * @throws A `SeedcordError` when the url does not carry a webhook id and token.
- */
-declare class WebhookSender {
-  private readonly rest;
-  private readonly route;
-  constructor(url: string);
-  /**
-   * Fetches the webhook object, sending no message. Returns `missing` on a 404 or 401 from
-   * Discord and `unreachable` on any other failure.
-   */
-  verify(): Promise<'ok' | 'missing' | 'unreachable'>;
-  send(options: WebhookSendOptions): Promise<void>;
-}
-//#endregion
-//#region src/subscribers/bases/WebhookLog.d.ts
-/**
- * The content a reporter returns from {@link WebhookLog.report}.
+ * @typeParam KeyOfSubscribers - The subscription key this handler receives
  */
-interface WebhookReport {
-  /** Shown as the webhook message author. Defaults to the reporter's class name. */
-  username?: string;
-  components: readonly {
-    toJSON(): APIMessageTopLevelComponent;
-  }[];
-  files?: readonly WebhookFile[] | undefined;
-}
+declare abstract class Subscriber<KeyOfSubscribers extends SubscriptionKey> extends Subscriber$1<KeyOfSubscribers, Core> {}
 /**
- * Base class for subscribers that deliver their event to a Discord webhook.
- *
- * Declare the url's environment variable with `@WebhookUrl` and implement {@link report}. Url
- * resolution, validation, sender reuse, and sending run in the base. When the variable is unset
- * the reporter is skipped at registration with a boot warning.
+ * Base class for a gateway subscriber that delivers its event to a Discord webhook, binding
+ * `this.core` to the gateway {@link Core}.
  *
  * @typeParam KeyOfSubscribers - The subscription key this reporter receives
  */
-declare abstract class WebhookLog<KeyOfSubscribers extends SubscriptionKey> extends Subscriber<KeyOfSubscribers> {
-  private static readonly senders;
-  /** Builds the message for one published event. */
-  abstract report(): WebhookReport | Promise<WebhookReport>;
-  execute(): Promise<void>;
-  /** @internal */
-  static senderFor(url: string): WebhookSender;
-  /** @internal */
-  static envKeyOf(ctor: NewableFunction): string;
-  /** @internal Returns null when the env var is unset, throws when set but malformed. */
-  static urlOf(envKey: string): string | null;
-}
+declare abstract class WebhookLog<KeyOfSubscribers extends SubscriptionKey> extends WebhookLog$1<KeyOfSubscribers, Core> {}
 //#endregion
-//#region src/subscribers/decorators/WebhookUrl.d.ts
+//#region src/plugin.d.ts
+/** The options a gateway plugin declares, narrowed to the transports this base serves. */
+type GatewayPluginOptions = TypedOmit<PluginOptions$1, 'transport'> & {
+  transport?: 'gateway' | 'any';
+};
 /**
- * Declares the environment variable a {@link WebhookLog} reporter reads its webhook url from.
+ * Base class for a gateway plugin, binding `this.core` to the gateway {@link Core}.
  *
- * An unset variable disables the reporter with a boot warning. A set but malformed value throws
- * at boot.
+ * A plugin that runs on either transport extends the base from `@seedcord/core/plugin`, whose
+ * `this.core` carries the shared members only.
  *
- * @param envKey - The environment variable name holding the webhook url
- * @decorator
- * @example
- * ```ts
- * \@Subscribe('memberBanned')
- * \@WebhookUrl('BAN_LOG_WEBHOOK_URL')
- * class BanLog extends WebhookLog<'memberBanned'> {
- *   report() {
- *     return { components: [new BanCard(this.data).component] };
- *   }
- * }
- * ```
+ * @typeParam Opts - The transport, runtime, and capabilities the plugin declares.
  */
-declare function WebhookUrl(envKey: string): <HandlerCtor extends Constructor<WebhookLog<SubscriptionKey>>>(constructor: HandlerCtor) => void;
+declare abstract class Plugin<Opts extends GatewayPluginOptions = {}> extends Plugin$1<Opts, Core> {}
 //#endregion
 //#region src/Seedcord.d.ts
 /**
- * Main Seedcord bot framework class
- *
- * Primary entry point for creating Discord bots with Seedcord.
- * Manages component lifecycle and provides plugin support.
+ * The gateway bot host. Opens a discord.js gateway session, discovers handlers, and runs
+ * coordinated startup and shutdown. Attach plugins with `attach()`.
  */
-declare class Seedcord extends Pluggable implements Core {
+declare class Seedcord extends Pluggable<'gateway', 'server'> implements Core, SeedcordInstance {
   readonly config: GatewayConfig;
   /** @internal */
   readonly [SeedcordBrand] = true;
@@ -2151,34 +1791,29 @@ declare class Seedcord extends Pluggable implements Core {
   readonly augmentTarget = "@seedcord/gateway";
   /** @internal */
   readonly version: string;
-  private static isInstantiated;
-  private readonly healthCheck;
+  private readonly healthCheck?;
   private readonly hmrManager;
-  /** @see {@link CoordinatedShutdown} */
-  readonly shutdown: CoordinatedShutdown;
-  /** @see {@link CoordinatedStartup} */
-  readonly startup: CoordinatedStartup;
   /** @see {@link Bus} */
   readonly bus: Bus;
+  private readonly subscribers;
   /** @see {@link Bot} */
   readonly bot: Bot;
   /** @see {@link IRateLimiter} */
   readonly rateLimiter: IRateLimiter;
   /**
-   * Creates a new Seedcord instance
-   *
    * @param config - Bot configuration including paths and Discord client options
    * @throws A **SeedcordError** When attempting to create multiple instances (singleton)
    */
   constructor(config: GatewayConfig);
   /** The bot's discord username, populated after login. */
   get username(): string | undefined;
-  private static reset;
+  protected pluginCapabilities(): PluginCapabilities;
+  protected static reset(): void;
   private registerStartupTasks;
   /**
    * Starts the bot and runs all initialization tasks
    *
-   * @returns This Seedcord instance when fully initialized
+   * @returns This Seedcord instance when initialized
    */
   start(): Promise<this>;
   private registerHmrAwareModules;
@@ -2188,5 +1823,5 @@ declare class Seedcord extends Pluggable implements Core {
 /** Package version */
 declare const version: string;
 //#endregion
-export { ArraySource, AssignRoleNoticeOverrides, AutocompleteHandler, type BotEvents, ButtonHandler, type CheckPermissionOptions, CommandMentions, type ConfirmOptions, ContextMenuHandler, type Core, CursorSource, type DefaultConfirmOptions, Emojis, type EventGateContext, EventHandler, EventMiddleware, type EventSpec, type EventsConfig, type FaultSource, FetchUserOptions, type GateContext, Gated, type GatewayBotConfig, type GatewayConfig, HasPermsToAssignOptions, IgnoreBots, type Initializeable, type InjectedEmojiMap, type InjectedMentionMap, type InteractionGateContext, InteractionHandler, InteractionMiddleware, Middleware, type MiddlewareOptions, MiddlewareType, ModalHandler, Nsfw, Paginator, type PaginatorControls, type PermissionErrorNoticeOverrides, Pluggable, Plugin, type PluginArgs, type PluginCtor, RegisterEvent, type RegisterEventOptions, RepliableHandler, type Repliables, Seedcord, SelectMenuHandler, ShutdownPhase, SlashHandler, type SlashOptions, StartupPhase, Subscribe, type SubscribeOptions, Subscriber, type SubscriptionData, type SubscriptionKey, type Subscriptions, type ValidEventTypes, type ValidInteractionTypes, type ValidNonInteractionKeys, type WebhookFile, WebhookLog, type WebhookReport, WebhookUrl, checkBotPermissions, checkPermissions, fetchGuildMember, fetchManyGuildMembers, fetchManyUsers, fetchRole, fetchText, fetchUser, getBotRole, getConfirmation, hasPermsToAssign, updateMemberRoles, version };
+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 };
 //# sourceMappingURL=index.d.mts.map