@seedcord/gateway 0.7.4 → 0.8.0-next.0

package/README.md

@@ -10,36 +10,83 @@
   <a href="https://seedcord.org">Website</a> ·
   <a href="https://seedcord.org/guide">Guide</a> ·
   <a href="https://seedcord.org/docs">Reference</a> ·
-  <a href="https://discord.gg/DzFxY58WXf">Discord</a>
+  <a href="https://seedcord.org/chat/">Discord</a>
 </div>
 
 <br />
 
 <div align="center">
 
-[![npm](https://img.shields.io/npm/v/@seedcord/gateway?style=flat-square&logo=npm&logoColor=c8341f&label=&labelColor=1f1f1f&color=c8341f)](https://www.npmjs.com/package/@seedcord/gateway) [![node](https://img.shields.io/node/v/@seedcord/gateway?style=flat-square&label=node&labelColor=1f1f1f&color=4d7d33)](https://nodejs.org) [![license](https://img.shields.io/npm/l/@seedcord/gateway?style=flat-square&label=license&labelColor=1f1f1f&color=f8f6e8)](LICENSE)
+[![npm](https://img.shields.io/npm/v/@seedcord/gateway?style=flat-square&label=npm&labelColor=1f1f1f&color=c8341f)](https://www.npmjs.com/package/@seedcord/gateway) [![node](https://img.shields.io/node/v/@seedcord/gateway?style=flat-square&label=node&labelColor=1f1f1f&color=4d7d33)](https://nodejs.org) [![bun](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fseedcord%2Fseedcord%2Fnext%2Fpackages%2Fgateway%2Fpackage.json&query=%24.engines.bun&style=flat-square&label=bun&labelColor=1f1f1f&color=fbf0df)](https://bun.com) [![license](https://img.shields.io/npm/l/@seedcord/gateway?style=flat-square&label=license&labelColor=1f1f1f&color=f8f6e8)](LICENSE)
 
 </div>
 
 ## About
 
-`@seedcord/gateway` runs a seedcord bot over a websocket connection through the discord.js client, which also keeps the cache. A gateway connection carries message, member, voice, and reaction events. Discord never posts those to an interactions endpoint. Pick this transport when the bot reacts to any of them.
+`@seedcord/gateway` is the transport for a gateway bot. It holds a websocket connection to Discord through the discord.js client, which also keeps the cache. That connection carries message, member, voice, and reaction events, and Discord only sends those over a websocket. Pick this transport when your bot reacts to any of them.
 
-Until v1.0.0, minor versions can break.
+A bot that only answers commands and components can use [`@seedcord/http`](https://www.npmjs.com/package/@seedcord/http) instead, which keeps no connection open and also runs on Cloudflare Workers.
+
+seedcord is pre-1.0, so a minor version can break your bot. Each release's changelog says what changed and how to update.
 
 ## Installation
 
+`pnpm create seedcord` sets up a new bot. To add seedcord to an existing project:
+
 ```sh
-pnpm add @seedcord/gateway discord.js
+pnpm add @seedcord/gateway discord.js @discordjs/builders envapt
+pnpm add -D seedcord vite typescript
+```
+
+`discord.js`, `envapt`, and `typescript` are peer dependencies. `seedcord` is the CLI that runs the bot in dev and builds it.
+
+## Usage
+
+`bot.ts` creates the bot and tells it where your handlers are:
+
+```ts
+import { Seedcord } from '@seedcord/gateway';
+import { GatewayIntentBits } from 'discord.js';
+import { Converters, Envapter } from 'envapt';
+
+export default new Seedcord({
+    bot: {
+        clientOptions: { intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages] },
+        interactions: { path: './handlers' },
+        commands: {
+            path: './commands',
+            guilds: Envapter.getAs('TESTING_GUILD_IDS', Converters.array(), [])
+        },
+        events: { path: './events' }
+    },
+    subscribers: { path: null }
+});
+```
+
+Read your environment through [envapt](https://envapt.materwelon.dev), the way `TESTING_GUILD_IDS` is read above. seedcord loads your `.env` files into envapt, and reads `DISCORD_BOT_TOKEN` from it too. envapt also reads your shell's variables, while `process.env` misses everything in your `.env` files.
+
+A file in `events/` reacts to any discord.js client event. Its handler reads the same arguments discord.js passes to `client.on()`:
+
+```ts
+import { EventHandler, RegisterEvent } from '@seedcord/gateway';
+import { Events } from 'discord.js';
+
+@RegisterEvent([Events.MessageCreate])
+export class Mentioned extends EventHandler<Events.MessageCreate> {
+    public async execute(): Promise<void> {
+        const [message] = this.event;
+        if (message.mentions.users.has(message.client.user.id)) await message.reply('hey');
+    }
+}
 ```
 
-`discord.js`, `envapt`, and `typescript` are peer dependencies. `pnpm create seedcord` sets all of it up.
+Slash commands, components, checks, and plugins work the same way as on http. The [guide](https://seedcord.org/guide) covers them.
 
 ## What it adds over the core
 
-Everything in `@seedcord/core`, plus the parts that use a live connection:
+Everything in [`@seedcord/core`](https://www.npmjs.com/package/@seedcord/core), plus:
 
-- `Seedcord`, the class that connects and holds the discord.js client
-- event subscribers, through `Subscriber` and `WebhookLog`
-- `getConfirmation`, which waits on a button press and returns the answer
-- pagination sources bound to the gateway
+- `Seedcord`, which connects to Discord and holds the discord.js client
+- handlers that read discord.js objects, like a `ChatInputCommandInteraction`
+- event handlers for every discord.js client event, through `EventHandler` and `@RegisterEvent`
+- `getConfirmation`, which shows buttons and waits for the answer in one `await`

package/dist/index.d.mts

@@ -1,13 +1,13 @@
 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, MiddlewareKindsBrand, NamesFor, PageCursor, SingleParams, SlashOptions as SlashOptions$1, SlashRouteBrand } from "@seedcord/core/internal";
+import { AutocompletableNames, AutocompleteRouteBrand, CacheFor, ChoiceValueOf, CommandRegistry, ComponentDefsBrand, ComponentKindBrand, ContextMenuKindBrand, ContextMenuLeaves, ContextMenuNamesBrand, EntryFor, FixedScope, FocusedField, GateFitsWith, HasComponentDefs, Initializeable, MatchArms, MenuCacheFor, MiddlewareKindsBrand, NamesFor, PageCursor, SingleParams, SlashOptions as SlashOptions$1, SlashRouteBrand } from "@seedcord/core/internal";
 import { ArraySourceBase, AutocompleteOptions, BaseHandler as BaseHandler$1, BaseReplySender, Bus, CoreBase, CursorSourceBase, DispatchContext, DispatchOutcome, DispatchResult, EventDispatchResult, Gate, GateContextBase, GateNoticeOptions, GuildPermissionsContext, HandlerOutcome, InteractionKind, MiddlewareKind, 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";
-import { CoordinatedShutdown, CoordinatedStartup, Pluggable } from "@seedcord/core/node";
-import { CommandRegistry } from "@seedcord/core/node/internal";
+import { CoordinatedShutdown, CoordinatedStartup, ServerHost } from "@seedcord/core/node";
 import { HostAugmentTarget, HostVersion, SeedcordBrand, SeedcordInstance } from "@seedcord/types/internal";
+import { HmrModuleHandler } from "@seedcord/core/hmr";
 import { AnyCustomId } from "@seedcord/custom-id";
 import { BotConfig, Config, DeferOpts, EmojiMap, EventFrequency, HealthCheckOption, HmrAware, HmrUpdateEvent, IRateLimiter, ReplyResponse, SendOpts, TypedOmit } from "@seedcord/types";
 import { Constructor, IsUnion, NonEmptyTuple, Promisable } from "type-fest";
@@ -87,8 +87,6 @@ interface GatewayBotConfig extends BotConfig {
  */
 interface GatewayConfig extends Config {
   bot: GatewayBotConfig;
-  /** The gateway websocket requires a persistent process. */
-  runtime?: 'server';
   /**
    * The health-check server. `false` disables it, `true` or omit for the defaults, an object
    * configures it.
@@ -111,7 +109,6 @@ declare class EventDispatcher implements Initializeable, HmrAware {
   private readonly executedOnceHandlers;
   private readonly attachedEvents;
   private readonly inFlight;
-  private draining;
   private loading;
   private readonly loadedHandlers;
   private readonly loadedMiddlewares;
@@ -149,7 +146,6 @@ declare class InteractionDispatcher implements Initializeable, HmrAware {
   private readonly keysToIgnore;
   private readonly middlewares;
   private readonly inFlight;
-  private draining;
   private loading;
   private readonly loadedHandlers;
   private readonly loadedMiddlewares;
@@ -196,7 +192,6 @@ declare class InteractionDispatcher implements Initializeable, HmrAware {
 //#endregion
 //#region src/bot/Bot.d.ts
 declare const loggerSlot: unique symbol;
-declare const initSlot: unique symbol;
 declare const controllersSlot: unique symbol;
 interface Controllers {
   readonly interactions?: InteractionDispatcher | undefined;
@@ -208,7 +203,7 @@ interface Controllers {
  */
 declare class Bot implements HmrAware {
   #private;
-  readonly botToken: string;
+  get botToken(): string;
   /** @internal */
   readonly [loggerSlot]: Logger;
   /** @internal */
@@ -219,8 +214,6 @@ declare class Bot implements HmrAware {
   get [controllersSlot](): Controllers;
   /** @internal */
   get applicationId(): string;
-  /** @internal */
-  [initSlot](): Promise<void>;
   get client(): Client;
 }
 //#endregion
@@ -667,7 +660,7 @@ interface EventMiddlewareOptions<Events extends NonEmptyTuple<ValidNonInteractio
  * }
  * ```
  *
- * @throws A **SeedcordTypeError** If `priority` is not a finite number.
+ * @throws A **SeedcordTypeError** when `priority` is not a finite number.
  */
 export declare function RegisterEventMiddleware<const Events extends NonEmptyTuple<ValidNonInteractionKeys> = NonEmptyTuple<ValidNonInteractionKeys>>(options?: EventMiddlewareOptions<Events>): (ctor: Constructor<EventMiddleware<Events[number]>>) => void;
 //#endregion
@@ -733,7 +726,8 @@ export declare class GatewayEmoji<Source extends SavedEmojiType = SavedEmojiType
 type InjectedEmojiMap = { [K in keyof EmojiMap]: EmojiMap[K] extends 'guild' ? GatewayEmoji<GuildEmoji> : GatewayEmoji<ApplicationEmoji>; };
 /**
  * The bot's resolved emojis, keyed by {@link EmojiMap}. Filled by {@link EmojiInjector} during startup.
- * Throws if you read a key the injector did not fill.
+ *
+ * @throws A **SeedcordError** when you read a key the injector did not fill.
  */
 export declare const Emojis: InjectedEmojiMap;
 //#endregion
@@ -839,7 +833,8 @@ export interface HasPermsToAssignOptions {
  * 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.
+ * @throws A {@link Notice} when the check refuses.
+ * @throws A **SeedcordError** when the bot has no role in the guild's role cache.
  *
  * @example
  * ```ts
@@ -909,14 +904,14 @@ 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. A {@link ModalHandler} is
- * excluded at compile time.
+ * with an early return. A {@link ModalHandler} is excluded at compile time.
  *
  * @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.
  * @returns `true` if confirmed, `false` on cancel or timeout.
+ * @throws The send error when the prompt fails to send. The handler's fault boundary catches it.
  *
  * @example
  * ```ts
@@ -936,8 +931,7 @@ export declare function getConfirmation(handler: RepliableHandler<NonModalIntera
 /**
  * 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. A {@link ModalHandler} is
- * excluded at compile time.
+ * timeout resolves to `false`. A {@link ModalHandler} is excluded at compile time.
  *
  * @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
@@ -945,6 +939,7 @@ export declare function getConfirmation(handler: RepliableHandler<NonModalIntera
  * @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.
+ * @throws The send error when the prompt fails to send. The handler's fault boundary catches it.
  *
  * @remarks
  * The prompt is collected in-process, so it does not survive a bot restart. Without an outcome hook the
@@ -1293,11 +1288,11 @@ export declare abstract class AutocompleteHandler<Route extends keyof SlashRegis
    *
    * Provide one arm per autocompletable field across the registered commands, keyed by field name. Each
    * arm receives the focused partial value and a `respond` typed to that field's choice value. The
-   * arms must cover every autocompletable field, a missing field or an unknown key is a compile error. A
-   * focused field with no arm, only reachable from a stale-deployed command, throws at runtime.
+   * arms must cover every autocompletable field. A missing field or an unknown key is a compile error.
    *
    * @param arms - One handler per autocompletable field, keyed by field name.
    * @returns The result of the arm that ran.
+   * @throws A **SeedcordTypeError** with `MatchArmMissing` when the focused field has no arm. Only a stale-deployed command can send one.
    *
    * @example
    * ```ts
@@ -1348,10 +1343,11 @@ export declare abstract class ComponentHandler<Event extends ComponentInteractio
   /**
    * The decoded params of the single route this handler is registered for.
    *
-   * Reading this decodes `this.event.customId` once (cached after the first read) and throws
-   * `StaleCustomId` or `InvalidCustomId` when the wire no longer matches the current shape, which the
-   * controller boundary turns into a reply. On a handler registered for several routes this is
-   * `never`. Use {@link match} instead.
+   * Reading this decodes `this.event.customId` once and caches the result. On a handler registered
+   * for several routes this is `never`. Use {@link match} instead.
+   *
+   * @throws A **StaleCustomId** when the wire was encoded under an older shape. The controller boundary turns it into a reply.
+   * @throws An **InvalidCustomId** when the wire is corrupt. The controller boundary turns it into a reply.
    */
   protected get params(): SingleParams<Defs>;
   /**
@@ -1360,12 +1356,14 @@ export declare abstract class ComponentHandler<Event extends ComponentInteractio
    * handler `this.params` is `never`, leaving match as the only way to read the decoded params.
    *
    * Provide one arm per registered route, keyed by its prefix, and each arm receives that route's own
-   * decoded params. The arms cover every registered route prefix, checked at compile time, and a prefix
-   * unmatched at runtime throws `CustomIdMatchArmMissing`. Decoding runs before any arm, so a stale or
-   * corrupt wire throws before an arm body executes.
+   * decoded params. The compiler checks that the arms cover every registered route prefix. `match`
+   * decodes the wire before it runs an arm.
    *
    * @param arms - One callback per registered route, keyed by prefix.
    * @returns The result of the arm that ran.
+   * @throws A **SeedcordTypeError** with `MatchArmMissing` when the wire's prefix has no arm.
+   * @throws A **StaleCustomId** when the wire was encoded under an older shape.
+   * @throws An **InvalidCustomId** when the wire is corrupt.
    *
    * @example
    * ```ts
@@ -1703,6 +1701,10 @@ type GatewayPluginOptions = TypedOmit<PluginOptions$1, 'transport' | 'runtime'>
   transport?: 'gateway';
   runtime?: 'server';
 };
+declare const GATEWAY_SCOPE: {
+  readonly transport: "gateway";
+  readonly runtime: "server";
+};
 /**
  * Base class for a gateway plugin, binding `this.core` to the gateway {@link Core}.
  *
@@ -1714,14 +1716,21 @@ type GatewayPluginOptions = TypedOmit<PluginOptions$1, 'transport' | 'runtime'>
 export declare abstract class Plugin<Opts extends GatewayPluginOptions = {
   transport: 'gateway';
   runtime: 'server';
-}> extends Plugin$1<Opts, Core> {}
+}> extends Plugin$1<Opts, Core, keyof typeof GATEWAY_SCOPE> {
+  /** @internal */
+  protected static readonly [FixedScope]: {
+    readonly transport: "gateway";
+    readonly runtime: "server";
+  };
+}
 //#endregion
 //#region src/Seedcord.d.ts
 /**
  * The gateway bot host. Opens a discord.js gateway session, discovers handlers, and runs
  * coordinated startup and shutdown. Attach plugins with `attach()`.
  */
-export declare class Seedcord extends Pluggable<'gateway', 'server'> implements SeedcordInstance {
+export declare class Seedcord extends ServerHost<'gateway'> implements SeedcordInstance {
+  #private;
   readonly config: GatewayConfig;
   /** @internal */
   readonly [SeedcordBrand] = true;
@@ -1729,11 +1738,8 @@ export declare class Seedcord extends Pluggable<'gateway', 'server'> implements
   readonly [HostAugmentTarget] = "@seedcord/gateway";
   /** @internal */
   readonly [HostVersion]: string;
-  private readonly healthCheck?;
-  private readonly hmrManager;
   /** @see {@link Bus} */
   readonly bus: Bus;
-  private readonly subscribers;
   /** @see {@link Bot} */
   readonly bot: Bot;
   /** The discord.js client's REST client. Its token is set during the Login phase. */
@@ -1744,25 +1750,25 @@ export declare class Seedcord extends Pluggable<'gateway', 'server'> implements
   readonly rateLimiter: IRateLimiter;
   /**
    * @param config - Bot configuration including paths and Discord client options
-   * @throws A **SeedcordError** When attempting to create multiple instances (singleton)
+   * @throws A **SeedcordError** when another `Seedcord` exists in this process and has not shut down.
+   * @throws A **SeedcordError** when the running Node or Bun is older than the range in `engines`.
    */
   constructor(config: GatewayConfig);
   /** The bot's discord username, populated after login. */
   get username(): string | undefined;
-  protected static reset(host?: object): boolean;
-  private registerStartupTasks;
+  /** @internal */
+  protected openHealth(): Promise<void>;
   /**
    * Starts the bot and runs all initialization tasks
    *
    * @returns This Seedcord instance when initialized
    */
   start(): Promise<this>;
-  private registerHmrAwareModules;
 }
 //#endregion
 //#region src/version.d.ts
 /** Package version */
 export declare const version: string;
 //#endregion
-export { type CheckPermissionOptions, type ConfirmOptions, type Core, type DefaultConfirmOptions, type EventGateContext, type EventMiddlewareOptions, type EventSpec, type EventsConfig, type GateContext, type GatewayBotConfig, type GatewayConfig, type GatewayFile, type GatewayPluginOptions, type GatewayReplyResponse, type InjectedEmojiMap, type InteractionGateContext, type PageContext, type PageSource, type PluginLifecycleSpec, type PluginOptions, type RegisterEventOptions, type Repliables, type SentMessage, type SlashOptions, type ValidEventTypes, type ValidInteractionTypes, type ValidNonInteractionKeys, WinstonConsoleSink, WinstonFileSink };
+export { type CheckPermissionOptions, type ConfirmOptions, type Core, type DefaultConfirmOptions, type EventGateContext, type EventMiddlewareOptions, type EventSpec, type EventsConfig, type GateContext, type GatewayBotConfig, type GatewayConfig, type GatewayFile, type GatewayPluginOptions, type GatewayReplyResponse, HmrModuleHandler, type InjectedEmojiMap, type InteractionGateContext, type PageContext, type PageSource, type PluginLifecycleSpec, type PluginOptions, type RegisterEventOptions, type Repliables, type SentMessage, type SlashOptions, type ValidEventTypes, type ValidInteractionTypes, type ValidNonInteractionKeys, WinstonConsoleSink, WinstonFileSink };
 //# sourceMappingURL=index.d.mts.map