@seedcord/core 0.9.4 → 0.11.0-next.0

package/dist/{cursor-BTU5bGoo.d.mts → index-Du71Xx69.d.mts}

@@ -1,9 +1,9 @@
-import { K as Notice, P as DispatchContext, U as MiddlewareKind, r as CoreBase } from "./phases-D_zQBXga.mjs";
+import { K as Notice, P as DispatchContext, U as MiddlewareKind, l as Subscriber, r as CoreBase, y as SubscriptionKey } from "./phases-FTM69J3a.mjs";
 import "reflect-metadata";
 import { CustomId, CustomIdField } from "@seedcord/custom-id";
 import { ActionRowBuilder, ButtonBuilder, ChannelSelectMenuBuilder, CheckboxBuilder, CheckboxGroupBuilder, CheckboxGroupOptionBuilder, ContainerBuilder, ContextMenuCommandBuilder, EmbedBuilder, FileBuilder, FileUploadBuilder, LabelBuilder, MediaGalleryBuilder, MentionableSelectMenuBuilder, ModalBuilder, RadioGroupBuilder, RadioGroupOptionBuilder, RoleSelectMenuBuilder, SectionBuilder, SeparatorBuilder, SlashCommandBuilder, SlashCommandSubcommandBuilder, SlashCommandSubcommandGroupBuilder, StringSelectMenuBuilder, StringSelectMenuOptionBuilder, TextDisplayBuilder, TextInputBuilder, UserSelectMenuBuilder } from "@discordjs/builders";
-import { APIMessageTopLevelComponent, ApplicationCommandType, ChannelType } from "discord-api-types/v10";
-import { ReplyResponse } from "@seedcord/types";
+import { APIApplicationCommand, APIMessageComponentEmoji, APIMessageTopLevelComponent, ApplicationCommandType, ChannelType, RESTPostAPIApplicationCommandsJSONBody, Snowflake } from "discord-api-types/v10";
+import { EventFrequency, ILogger, ReplyFile, ReplyResponse } from "@seedcord/types";
 import { Constructor, IsNever, LiteralUnion, NonEmptyTuple } from "type-fest";
 //#region src/registries/ContextMenuRegistry.d.ts
 /** The two context-menu command kinds Discord defines. */
@@ -260,6 +260,112 @@ declare function RegisterCommand(scope: 'global'): (ctor: CommandCtor) => void;
  */
 declare function RegisterCommand(scope: 'guild', guilds: GuildTarget[]): (ctor: CommandCtor) => void;
 //#endregion
+//#region src/commands/deployTarget.d.ts
+type DeployTarget = Exclude<CommandMeta, {
+  scope: 'config';
+}>;
+declare function resolveDeployTarget(meta: CommandMeta, configured: readonly string[], commandName: string): DeployTarget;
+//#endregion
+//#region src/commands/scopes.d.ts
+declare const GLOBAL_ID = "global";
+type ScopeId = LiteralUnion<typeof GLOBAL_ID, Snowflake>;
+declare function commandsRoute(applicationId: Snowflake, scope: ScopeId): `/${string}`;
+declare function globalFirst<ValueT>(scopes: Iterable<readonly [ScopeId, ValueT]>): (readonly [ScopeId, ValueT])[];
+declare function scopeIdsOf(target: DeployTarget): readonly ScopeId[];
+declare function skippedNote(skipped: readonly ScopeId[], guildLabel: (guildId: string) => string): string;
+//#endregion
+//#region src/commands/types.d.ts
+/** @internal */
+type CommandBuilder = SlashCommandBuilder | ContextMenuCommandBuilder;
+/** discord returns these from each scope's deploy, keyed by command id. @internal */
+type DeployResult = Map<ScopeId, Map<string, APIApplicationCommand>>;
+//#endregion
+//#region src/commands/linkCommands.d.ts
+interface CommandRef {
+  readonly name: string;
+  readonly type: ApplicationCommandType;
+}
+interface LinkedContextMenus {
+  readonly user: Record<string, ContextMenuInfo>;
+  readonly message: Record<string, ContextMenuInfo>;
+}
+interface LinkedCommands {
+  readonly commands: Record<string, CommandInfo>;
+  readonly contextMenus: LinkedContextMenus;
+  readonly multiGuild: CommandRef[];
+  readonly notInCode: CommandRef[];
+}
+interface CommandLike {
+  name: string;
+  type?: ApplicationCommandType | undefined;
+}
+declare function commandRefOf({ name, type }: CommandLike): CommandRef;
+declare function commandKey(command: CommandLike): string;
+declare function indexById(commands: readonly APIApplicationCommand[]): Map<string, APIApplicationCommand>;
+declare function linkCommands(deploy: DeployResult, all: readonly RESTPostAPIApplicationCommandsJSONBody[]): LinkedCommands;
+//#endregion
+//#region src/commands/CommandInjector.d.ts
+/** What {@link Commands} resolves to for one slash route. */
+interface CommandInfo {
+  /** The clickable `</config set:id>` mention. A route whose id did not resolve falls back to `/config set`. */
+  readonly mention: string;
+  /** The deployed command id. Absent when the command deployed to two or more guilds. */
+  readonly id?: string;
+  /** The full route, e.g. `config/set`. */
+  readonly route: string;
+  /** The route's own description, taken from the subcommand for a nested route. */
+  readonly description: string;
+}
+/** Each registered slash route mapped to its deployed command. */
+type InjectedCommandMap = { [K in keyof SlashRegistry]: CommandInfo; };
+/**
+ * The bot's deployed slash commands, keyed by {@link SlashRegistry}. A server bot fills these after
+ * each deploy. An edge bot fills them on its first request, from the ids `seedcord build` wrote into
+ * the worker.
+ *
+ * @throws A **SeedcordError** when you read a command before the bot fills it.
+ *
+ * @example
+ * ```ts
+ * import { Commands } from '@seedcord/gateway';
+ *
+ * await this.reply(`Try ${Commands['config/set'].mention}`);
+ *
+ * // a help listing
+ * const lines = Object.values(Commands).map((c) => `${c.mention} ${c.description}`);
+ * ```
+ */
+declare const Commands: InjectedCommandMap;
+/** What {@link ContextMenus} resolves to for one context-menu command. */
+interface ContextMenuInfo {
+  /** The deployed command id. Absent when the command deployed to two or more guilds. */
+  readonly id?: string;
+  /** The name shown in Discord's right-click menu. */
+  readonly name: string;
+  readonly kind: ContextMenuKind;
+}
+/** Deployed context-menu commands, split by kind because Discord scopes name uniqueness per command type. */
+interface InjectedContextMenuMap {
+  readonly user: { [K in keyof UserContextMenuRegistry]: ContextMenuInfo; };
+  readonly message: { [K in keyof MessageContextMenuRegistry]: ContextMenuInfo; };
+}
+/**
+ * The bot's deployed context-menu commands. A server bot fills these after each deploy. An edge bot
+ * fills them on its first request, from the ids `seedcord build` wrote into the worker.
+ *
+ * @throws A **SeedcordError** when you read a command before the bot fills it.
+ *
+ * @example
+ * ```ts
+ * import { ContextMenus } from '@seedcord/gateway';
+ *
+ * const id = ContextMenus.user['View Profile'].id;
+ * ```
+ */
+declare const ContextMenus: InjectedContextMenuMap;
+declare function installLinks({ commands, contextMenus }: Pick<LinkedCommands, 'commands' | 'contextMenus'>): void;
+declare function warnLinks(logger: ILogger, { multiGuild, notInCode }: Pick<LinkedCommands, 'multiGuild' | 'notInCode'>): void;
+//#endregion
 //#region src/decorators/brands.d.ts
 declare const SlashRouteBrand: unique symbol;
 declare const AutocompleteRouteBrand: unique symbol;
@@ -312,7 +418,7 @@ interface InteractionMiddlewareMetadata {
  * }
  * ```
  *
- * @throws A **SeedcordTypeError** If `priority` is not a finite number.
+ * @throws A **SeedcordTypeError** when `priority` is not a finite number.
  */
 declare function RegisterInteractionMiddleware<const Kinds extends NonEmptyTuple<MiddlewareKind> = NonEmptyTuple<MiddlewareKind>>(options?: InteractionMiddlewareOptions<Kinds>): <TCtor extends AnyMiddlewareCtor>(ctor: AssertMiddlewareKinds<Kinds[number], TCtor>) => void;
 /** @internal */
@@ -740,6 +846,19 @@ declare function RequireBotPermissions(scope: PermissionScope, options?: Require
  */
 declare function RequireRole(roleId: string, options?: RequireRoleOptions): Gate<GateContextBase, 'RequireRole'>;
 //#endregion
+//#region src/miscellaneous/ResolvedEmoji.d.ts
+/**
+ * A resolved custom emoji. Renders as `<:name:id>` in message content, or `<a:name:id>` when animated,
+ * and passes straight to a builder's `setEmoji`.
+ */
+declare class ResolvedEmoji implements APIMessageComponentEmoji {
+  readonly name: string;
+  readonly id: string;
+  readonly animated: boolean;
+  constructor(name: string, id: string, animated?: boolean);
+  toString(): string;
+}
+//#endregion
 //#region src/inputs/AutocompleteOptions.d.ts
 type Row<Route extends keyof SlashRegistry> = SlashRegistry[Route]['options'];
 type EntryFor<Route extends keyof SlashRegistry, Name extends PropertyKey> = Route extends unknown ? Name extends keyof Row<Route> ? Row<Route>[Name] : never : never;
@@ -789,5 +908,133 @@ type PageCursor<Prefix extends string> = CustomId<Prefix, {
 /** Build the page cursor for a paginator. */
 declare function pageCursor<Prefix extends string>(prefix: Prefix): PageCursor<Prefix>;
 //#endregion
-export { RowType as $, serializeReply as A, AutocompleteRouteBrand as B, Gate as C, defineEffectGate as D, RequiredOf as E, AnyMiddlewareCtor as F, MiddlewareKindsBrand as G, ComponentKindBrand as H, InteractionMiddlewareMetadata as I, GuildTarget as J, SlashRouteBrand as K, InteractionMiddlewareOptions as L, EventDispatchResult as M, HandlerOutcome as N, defineGate as O, HandlerResult as P, BuilderType as Q, RegisterInteractionMiddleware as R, EffectGate as S, GuildPermissionsContext as T, ContextMenuKindBrand as U, ComponentDefsBrand as V, ContextMenuNamesBrand as W, BuilderComponent as X, RegisterCommand as Y, RowComponent as Z, pickNotice as _, AutocompleteOptions as a, SlashRouteEntry as at, JoinNames as b, FocusedField as c, MessageContextMenuRegistry as ct, RequirePermissionsOptions as d, CacheFor as et, RequireRole as f, GateNoticeOptions as g, PermissionScope as h, AutocompletableNames as i, SlashRegistry as it, DispatchResult as j, SerializedReply as k, RequireBotPermissions as l, NamesFor as lt, PermissionNames as m, PageCursor as n, RouteCache as nt, ChoiceValueOf as o, ContextMenuKind as ot, RequireRoleOptions as p, CommandMeta as q, pageCursor as r, SlashOption as rt, EntryFor as s, MenuCacheFor as st, PAGE_MAX as t, OptionKind as tt, RequirePermissions as u, UserContextMenuRegistry as ut, GateFitsWith as v, GateContextBase as w, TwoOrMore as x, IntersectRequired as y, interactionMiddlewareMetaOf as z };
-//# sourceMappingURL=cursor-BTU5bGoo.d.mts.map
+//#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;
+}
+/**
+ * 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() {
+ *   }
+ * }
+ * ```
+ * @example
+ * ```ts
+ * \@Subscribe('userJoin', { frequency: 'once' })
+ * // or
+ * \@Subscribe('userJoin')
+ * ```
+ */
+declare function Subscribe<TSubscriber extends SubscriptionKey>(subscriber: TSubscriber, options?: SubscribeOptions): <HandlerCtor extends Constructor<Subscriber<TSubscriber, CoreBase>>>(constructor: HandlerCtor) => void;
+//#endregion
+//#region src/subscribers/bases/WebhookSender.d.ts
+/** A file attached to a webhook report. */
+interface WebhookFile extends ReplyFile {
+  readonly description: string;
+}
+interface WebhookSendOptions {
+  flags: number;
+  username: string;
+  avatarUrl?: string | undefined;
+  components: readonly {
+    toJSON(): APIMessageTopLevelComponent;
+  }[];
+  files?: readonly WebhookFile[] | undefined;
+}
+declare class WebhookSender {
+  private readonly rest;
+  private readonly route;
+  constructor(url: string);
+  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}.
+ */
+interface WebhookReport {
+  /** Shown as the webhook message author. Defaults to the reporter's class name. */
+  username?: string;
+  /** Shown as the webhook message avatar. Defaults to the webhook's own. */
+  avatarUrl?: string;
+  components: readonly {
+    toJSON(): APIMessageTopLevelComponent;
+  }[];
+  files?: readonly WebhookFile[] | undefined;
+}
+/**
+ * Base class for subscribers that deliver their event to a Discord webhook.
+ *
+ * Declare the url's environment variable with `@WebhookUrl` and implement {@link report}. The base
+ * resolves the url, validates it, reuses one sender per url, and sends. Registration skips a reporter
+ * whose variable is unset and warns at boot.
+ *
+ * @typeParam KeyOfSubscribers - The subscription key this reporter receives
+ * @typeParam TCore - The transport's Core
+ */
+declare abstract class WebhookLog<KeyOfSubscribers extends SubscriptionKey, TCore extends CoreBase> extends Subscriber<KeyOfSubscribers, TCore> {
+  private static readonly senders;
+  /**
+   * Builds the message for one published event.
+   *
+   * @param suppressed - How many events were dropped since the last card
+   */
+  abstract report(suppressed: number): WebhookReport | Promise<WebhookReport>;
+  /**
+   * Events sharing this key collapse into one card per minute. Return `null` to send every event.
+   */
+  protected throttleKey(): string | null;
+  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;
+}
+//#endregion
+//#region src/subscribers/decorators/WebhookUrl.d.ts
+/**
+ * Declares the environment variable a {@link WebhookLog} reporter reads its webhook url from.
+ *
+ * An unset variable disables the reporter with a boot warning. A set but malformed value throws
+ * at boot.
+ *
+ * @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] };
+ *   }
+ * }
+ * ```
+ */
+declare function WebhookUrl(envKey: string): <HandlerCtor extends Constructor<WebhookLog<SubscriptionKey, CoreBase>>>(constructor: HandlerCtor) => void;
+//#endregion
+export { SlashRouteBrand as $, Gate as A, CacheFor as At, HandlerOutcome as B, UserContextMenuRegistry as Bt, GateNoticeOptions as C, CommandMeta as Ct, JoinNames as D, RowComponent as Dt, IntersectRequired as E, BuilderComponent as Et, defineGate as F, SlashRouteEntry as Ft, RegisterInteractionMiddleware as G, AnyMiddlewareCtor as H, SerializedReply as I, ContextMenuKind as It, ComponentDefsBrand as J, interactionMiddlewareMetaOf as K, serializeReply as L, MenuCacheFor as Lt, GuildPermissionsContext as M, RouteCache as Mt, RequiredOf as N, SlashOption as Nt, TwoOrMore as O, BuilderType as Ot, defineEffectGate as P, SlashRegistry as Pt, MiddlewareKindsBrand as Q, DispatchResult as R, MessageContextMenuRegistry as Rt, PermissionScope as S, resolveDeployTarget as St, GateFitsWith as T, RegisterCommand as Tt, InteractionMiddlewareMetadata as U, HandlerResult as V, InteractionMiddlewareOptions as W, ContextMenuKindBrand as X, ComponentKindBrand as Y, ContextMenuNamesBrand as Z, RequirePermissions as _, ScopeId as _t, Subscribe as a, InjectedContextMenuMap as at, RequireRoleOptions as b, scopeIdsOf as bt, PageCursor as c, CommandRef as ct, AutocompleteOptions as d, commandRefOf as dt, CommandInfo as et, ChoiceValueOf as f, indexById as ft, RequireBotPermissions as g, GLOBAL_ID as gt, ResolvedEmoji as h, DeployResult as ht, WebhookFile as i, InjectedCommandMap as it, GateContextBase as j, OptionKind as jt, EffectGate as k, RowType as kt, pageCursor as l, LinkedCommands as lt, FocusedField as m, CommandBuilder as mt, WebhookLog as n, ContextMenuInfo as nt, SubscribeOptions as o, installLinks as ot, EntryFor as p, linkCommands as pt, AutocompleteRouteBrand as q, WebhookReport as r, ContextMenus as rt, PAGE_MAX as s, warnLinks as st, WebhookUrl as t, Commands as tt, AutocompletableNames as u, commandKey as ut, RequirePermissionsOptions as v, commandsRoute as vt, pickNotice as w, GuildTarget as wt, PermissionNames as x, skippedNote as xt, RequireRole as y, globalFirst as yt, EventDispatchResult as z, NamesFor as zt };
+//# sourceMappingURL=index-Du71Xx69.d.mts.map

package/dist/index.d.mts

@@ -1,7 +1,5 @@
-import { C as AckState, K as Notice, P as DispatchContext, U as MiddlewareKind, _ as ResponseSent, b as Subscriptions, f as DispatchOutcome, g as ResponseOutcome, h as ResponseFailed, i as Bus, l as Subscriber, m as ResponseAttempt, n as StartupPhase, p as FaultSource, r as CoreBase, t as ShutdownPhase, u as AttemptedWrite, v as SubscriptionData, x as ReplyTelemetry, y as SubscriptionKey, z as InteractionKind } from "./phases-D_zQBXga.mjs";
-import { $ as RowType, B as AutocompleteRouteBrand, C as Gate, D as defineEffectGate, E as RequiredOf, H as ComponentKindBrand, J as GuildTarget, K as SlashRouteBrand, L as InteractionMiddlewareOptions, M as EventDispatchResult, N as HandlerOutcome, O as defineGate, P as HandlerResult, Q as BuilderType, R as RegisterInteractionMiddleware, S as EffectGate, T as GuildPermissionsContext, U as ContextMenuKindBrand, V as ComponentDefsBrand, W as ContextMenuNamesBrand, X as BuilderComponent, Y as RegisterCommand, Z as RowComponent, a as AutocompleteOptions, b as JoinNames, ct as MessageContextMenuRegistry, d as RequirePermissionsOptions, f as RequireRole, g as GateNoticeOptions, h as PermissionScope, it as SlashRegistry, j as DispatchResult, k as SerializedReply, l as RequireBotPermissions, lt as NamesFor, n as PageCursor, ot as ContextMenuKind, p as RequireRoleOptions, u as RequirePermissions, ut as UserContextMenuRegistry, w as GateContextBase, x as TwoOrMore, y as IntersectRequired } from "./cursor-BTU5bGoo.mjs";
-import "./types-BG0BimVr.mjs";
-import { a as Subscribe, i as WebhookFile, n as WebhookLog, o as SubscribeOptions, r as WebhookReport, t as WebhookUrl } from "./index-B_-EjyvS.mjs";
+import { C as AckState, K as Notice, P as DispatchContext, U as MiddlewareKind, _ as ResponseSent, b as Subscriptions, f as DispatchOutcome, g as ResponseOutcome, h as ResponseFailed, i as Bus, l as Subscriber, m as ResponseAttempt, n as StartupPhase, p as FaultSource, r as CoreBase, t as ShutdownPhase, u as AttemptedWrite, v as SubscriptionData, x as ReplyTelemetry, y as SubscriptionKey, z as InteractionKind } from "./phases-FTM69J3a.mjs";
+import { $ as SlashRouteBrand, A as Gate, B as HandlerOutcome, Bt as UserContextMenuRegistry, C as GateNoticeOptions, D as JoinNames, Dt as RowComponent, E as IntersectRequired, Et as BuilderComponent, F as defineGate, G as RegisterInteractionMiddleware, I as SerializedReply, It as ContextMenuKind, J as ComponentDefsBrand, M as GuildPermissionsContext, N as RequiredOf, O as TwoOrMore, Ot as BuilderType, P as defineEffectGate, Pt as SlashRegistry, R as DispatchResult, Rt as MessageContextMenuRegistry, S as PermissionScope, Tt as RegisterCommand, V as HandlerResult, W as InteractionMiddlewareOptions, X as ContextMenuKindBrand, Y as ComponentKindBrand, Z as ContextMenuNamesBrand, _ as RequirePermissions, a as Subscribe, at as InjectedContextMenuMap, b as RequireRoleOptions, c as PageCursor, d as AutocompleteOptions, et as CommandInfo, g as RequireBotPermissions, h as ResolvedEmoji, i as WebhookFile, it as InjectedCommandMap, j as GateContextBase, k as EffectGate, kt as RowType, n as WebhookLog, nt as ContextMenuInfo, o as SubscribeOptions, q as AutocompleteRouteBrand, r as WebhookReport, rt as ContextMenus, t as WebhookUrl, tt as Commands, v as RequirePermissionsOptions, wt as GuildTarget, y as RequireRole, z as EventDispatchResult, zt as NamesFor } from "./index-Du71Xx69.mjs";
 import "reflect-metadata";
 import { AnyCustomId, AnyCustomId as AnyCustomId$1, CustomId, CustomIdField, CustomIdShape, DecodedParams, DecodedRoute, FieldOptions, decodeFor, prefixOf, setCustomIdErrors } from "@seedcord/custom-id";
 import { ActionRowBuilder, ButtonBuilder } from "@discordjs/builders";
@@ -10,61 +8,6 @@ import { Logger } from "@seedcord/logger";
 import { ValidDuration } from "@seedcord/utils";
 import { DeferOpts, EpochMs, LoggerChannelId, RenderContext, ReplyResponse, SendOpts, TypedExtract, V2Component } from "@seedcord/types";
 import { Constructor, Promisable } from "type-fest";
-//#region src/commands/CommandInjector.d.ts
-/** What {@link Commands} resolves to for one slash route. */
-interface CommandInfo {
-  /** The clickable `</config set:id>` mention. A route whose id did not resolve falls back to `/config set`. */
-  readonly mention: string;
-  /** The deployed command id. Absent when the command deployed to two or more guilds. */
-  readonly id?: string;
-  /** The full route, e.g. `config/set`. */
-  readonly route: string;
-  /** The route's own description, taken from the subcommand for a nested route. */
-  readonly description: string;
-}
-/** Each registered slash route mapped to its deployed command. */
-type InjectedCommandMap = { [K in keyof SlashRegistry]: CommandInfo; };
-/**
- * The bot's deployed slash commands, keyed by {@link SlashRegistry}. Filled by
- * {@link CommandInjector} after each deploy, and a read before that throws.
- *
- * @example
- * ```ts
- * import { Commands } from '@seedcord/gateway';
- *
- * await this.reply(`Try ${Commands['config/set'].mention}`);
- *
- * // a help listing
- * const lines = Object.values(Commands).map((c) => `${c.mention} ${c.description}`);
- * ```
- */
-export declare const Commands: InjectedCommandMap;
-/** What {@link ContextMenus} resolves to for one context-menu command. */
-interface ContextMenuInfo {
-  /** The deployed command id. Absent when the command deployed to two or more guilds. */
-  readonly id?: string;
-  /** The name shown in Discord's right-click menu. */
-  readonly name: string;
-  readonly kind: ContextMenuKind;
-}
-/** Deployed context-menu commands, split by kind because Discord scopes name uniqueness per command type. */
-interface InjectedContextMenuMap {
-  readonly user: { [K in keyof UserContextMenuRegistry]: ContextMenuInfo; };
-  readonly message: { [K in keyof MessageContextMenuRegistry]: ContextMenuInfo; };
-}
-/**
- * The bot's deployed context-menu commands. Filled by {@link CommandInjector} after each deploy, and a read
- * before that throws.
- *
- * @example
- * ```ts
- * import { ContextMenus } from '@seedcord/gateway';
- *
- * const id = ContextMenus.user['View Profile'].id;
- * ```
- */
-export declare const ContextMenus: InjectedContextMenuMap;
-//#endregion
 //#region src/decorators/routes.d.ts
 type ComponentBrand = TypedExtract<InteractionKind, InteractionKind.Button | InteractionKind.Modal | InteractionKind.StringMenu | InteractionKind.UserMenu | InteractionKind.RoleMenu | InteractionKind.ChannelMenu | InteractionKind.MentionableMenu>;
 type AnyHandlerCtor = new (...args: never[]) => unknown;
@@ -319,10 +262,11 @@ interface ModalLike {
   toJSON(): APIModalInteractionResponseCallbackData;
 }
 /**
- * Tracks acknowledgement state and throws a translated `SeedcordError` on an illegal verb before any
- * transport call. Every verb runs the legality check, calls the transport's wire writer, then updates
- * the state and the ack trace. Each transport binds `TMessage` to its own created-message type and
- * supplies the writers.
+ * Tracks acknowledgement state. Every verb runs the legality check, calls the transport's wire writer,
+ * then updates the state and the ack trace. Each transport binds `TMessage` to its own created-message
+ * type and supplies the writers.
+ *
+ * @throws A **SeedcordError** when you call a verb the current ack state doesn't allow. It throws before any transport call.
  */
 export declare abstract class BaseReplySender<TMessage extends {
   id: string;
@@ -586,14 +530,16 @@ interface CooldownOptions {
 }
 /**
  * Allows `limit` uses per window, scoped by `per`. A number `duration` is **seconds**, and a string is
- * a duration like `30m` or `24h`. An unparseable string throws a **SeedcordTypeError** at construction. The
- * slot is charged in commit, only after the whole gate set passes, so a later refusal never burns the cooldown.
+ * a duration like `30m` or `24h`. The slot is charged in commit, only after the whole gate set passes,
+ * so a later refusal never burns the cooldown.
  * That split also means two requests racing the same key can both pass before either charges the slot.
  * The key combines the handler's route with the window settings, keeping two different handlers on separate
  * windows. Reword the refusal with {@link CooldownOptions.message} or replace it with {@link CooldownOptions.notice}.
  *
- * @param duration - A number is seconds, and a string is a duration like `30m` or `24h`. An unparseable string throws a **SeedcordTypeError**.
+ * @param duration - A number is seconds, and a string is a duration like `30m` or `24h`.
  * @param options - Sets the scope with `per`, the uses per window with `limit`, and the refusal text with `message` or `notice`.
+ * @throws A **SeedcordTypeError** when `duration` is a string that doesn't parse.
+ * @throws A **SeedcordRangeError** when `duration` is zero or negative.
  *
  * @see the `@Gated` decorator from your transport package
  * @see {@link IRateLimiter}
@@ -654,7 +600,7 @@ interface PermissionAssertion extends PermissionNoticeOverrides {
  * The caller computes `permissions`, gateway off a discord.js role, member, or channel, and HTTP off the
  * bitfield the interaction payload carries.
  *
- * @throws A {@link Notice} listing the missing or present permissions.
+ * @throws A {@link Notice} when the check refuses. It lists the missing or present permissions.
  *
  * @example
  * ```ts
@@ -802,19 +748,6 @@ export declare class Silence extends Error {
   constructor(reason?: string | undefined);
 }
 //#endregion
-//#region src/miscellaneous/ResolvedEmoji.d.ts
-/**
- * A resolved custom emoji. Renders as `<:name:id>` in message content, or `<a:name:id>` when animated,
- * and passes straight to a builder's `setEmoji`.
- */
-export declare class ResolvedEmoji implements APIMessageComponentEmoji {
-  readonly name: string;
-  readonly id: string;
-  readonly animated: boolean;
-  constructor(name: string, id: string, animated?: boolean);
-  toString(): string;
-}
-//#endregion
 //#region src/pagination/PageView.d.ts
 /**
  * One rendered page of a paginated list.
@@ -838,7 +771,7 @@ interface PageView<Item> {
  * @param page - The requested zero-based page, clamped into `[0, totalPages - 1]`.
  * @param perPage - The page size. Must be a positive integer.
  * @returns The sliced {@link PageView}, with `totalPages` always known.
- * @throws SeedcordRangeError when `perPage` is not a positive integer.
+ * @throws A **SeedcordRangeError** when `perPage` is not a positive integer.
  */
 export declare function paginate<Item>(items: readonly Item[], page: number, perPage: number): PageView<Item>;
 //#endregion
@@ -860,8 +793,10 @@ interface PaginatorControls {
    */
   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.
+   * Assemble an action row of the chosen controls, in order.
+   *
+   * @throws A **SeedcordRangeError** when `keys` is empty or holds more than five controls.
+   * @throws A **SeedcordTypeError** when `keys` holds the same control twice.
    */
   row(...keys: ControlKey[]): ActionRowBuilder<ButtonBuilder>;
 }
@@ -964,5 +899,5 @@ export declare abstract class PaginatorBase<Item, Prefix extends string, Ctx> {
 /** Package version */
 export declare const version: string;
 //#endregion
-export { type AnyCustomId, type AttemptedWrite, type AutocompleteOptions, BuilderComponent, type BuilderType, Bus, type CommandInfo, type ContextMenuInfo, type ControlCosmetics, type ControlKey, type CooldownOptions, type CoreBase, CustomId, type CustomIdField, type CustomIdShape, type DecodedParams, type DecodedRoute, DispatchContext, type DispatchOutcome, type DispatchResult, type EffectGate, type EventDispatchResult, type FaultSource, type FieldOptions, type Gate, type GateContextBase, type GateNoticeOptions, type GuildPermissionsContext, type GuildTarget, type HandlerOutcome, type HandlerResult, type InjectedCommandMap, type InjectedContextMenuMap, InteractionKind, type InteractionMiddlewareOptions, type ItemRender, type MessageContextMenuRegistry, type MiddlewareKind, type ModalLike, Notice, type PageRender, type PageSourceBase, type PageView, type PaginatorConfig, type PaginatorControls, type PermissionAssertion, type PermissionNoticeOverrides, type PermissionScope, RegisterCommand, RegisterInteractionMiddleware, RequireBotPermissions, RequirePermissions, type RequirePermissionsOptions, RequireRole, type RequireRoleOptions, type RequiredOf, type ResponseAttempt, type ResponseFailed, type ResponseOutcome, type ResponseSent, RowComponent, type RowType, ShutdownPhase, type SlashRegistry, StartupPhase, Subscribe, type SubscribeOptions, Subscriber, type SubscriptionData, type SubscriptionKey, type Subscriptions, type UserContextMenuRegistry, type WebhookFile, WebhookLog, type WebhookReport, WebhookUrl, decodeFor, defineEffectGate, defineGate, prefixOf, setCustomIdErrors };
+export { type AnyCustomId, type AttemptedWrite, type AutocompleteOptions, BuilderComponent, type BuilderType, Bus, type CommandInfo, Commands, type ContextMenuInfo, ContextMenus, type ControlCosmetics, type ControlKey, type CooldownOptions, type CoreBase, CustomId, type CustomIdField, type CustomIdShape, type DecodedParams, type DecodedRoute, DispatchContext, type DispatchOutcome, type DispatchResult, type EffectGate, type EventDispatchResult, type FaultSource, type FieldOptions, type Gate, type GateContextBase, type GateNoticeOptions, type GuildPermissionsContext, type GuildTarget, type HandlerOutcome, type HandlerResult, type InjectedCommandMap, type InjectedContextMenuMap, InteractionKind, type InteractionMiddlewareOptions, type ItemRender, type MessageContextMenuRegistry, type MiddlewareKind, type ModalLike, Notice, type PageRender, type PageSourceBase, type PageView, type PaginatorConfig, type PaginatorControls, type PermissionAssertion, type PermissionNoticeOverrides, type PermissionScope, RegisterCommand, RegisterInteractionMiddleware, RequireBotPermissions, RequirePermissions, type RequirePermissionsOptions, RequireRole, type RequireRoleOptions, type RequiredOf, ResolvedEmoji, type ResponseAttempt, type ResponseFailed, type ResponseOutcome, type ResponseSent, RowComponent, type RowType, ShutdownPhase, type SlashRegistry, StartupPhase, Subscribe, type SubscribeOptions, Subscriber, type SubscriptionData, type SubscriptionKey, type Subscriptions, type UserContextMenuRegistry, type WebhookFile, WebhookLog, type WebhookReport, WebhookUrl, decodeFor, defineEffectGate, defineGate, prefixOf, setCustomIdErrors };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -1,6 +1,4 @@
-import { A as translateSerializationError, B as contextMenuRouteOf, C as NotInDm, D as defineEffectGate, E as OnCooldown, F as checkAckLegality, H as storeComponentRoute, I as sendTarget, K as NoticeCard, L as RegisterInteractionMiddleware, M as publishResponse, O as defineGate, P as AckTrace, S as NotAllowed, T as NotOwner, U as storeInteractionRoute, a as RequirePermissions, c as hasAll, d as pickNotice, h as runCheck, i as RequireBotPermissions, j as attemptWrite, k as serializeReply, l as missingNames, m as rollbackCommits, n as pageCursor, o as RequireRole, p as markCommits, q as Notice, r as Silence, t as PAGE_MAX, u as presentNames, v as HasDangerousPermissions, w as NotInGuild, x as NeedsAny, y as MissingPermissions } from "./cursor-CgNBnJfu.mjs";
-import { A as BuilderComponent, b as InteractionKind, d as WebhookLog, f as Subscriber, j as RowComponent, l as WebhookUrl, t as Bus, u as Subscribe } from "./Bus-BxPa-Uvp.mjs";
-import { a as ContextMenus, i as Commands, n as RegisterCommand } from "./subscribers-xGy7a7xR.mjs";
+import { $ as RegisterInteractionMiddleware, A as rollbackCommits, B as NotInGuild, D as pickNotice, E as presentNames, F as MissingPermissions, G as serializeReply, H as OnCooldown, Ht as Notice, J as publishResponse, K as translateSerializationError, L as NeedsAny, Lt as NoticeCard, P as HasDangerousPermissions, Q as sendTarget, R as NotAllowed, Rt as BuilderComponent, S as RequireRole, T as missingNames, U as defineEffectGate, V as NotOwner, W as defineGate, X as AckTrace, Z as checkAckLegality, _ as pageCursor, b as RequireBotPermissions, bt as Commands, ct as RegisterCommand, d as WebhookLog, f as Subscriber, g as PAGE_MAX, it as storeInteractionRoute, j as runCheck, k as markCommits, l as WebhookUrl, pt as InteractionKind, q as attemptWrite, rt as storeComponentRoute, t as Bus, tt as contextMenuRouteOf, u as Subscribe, v as ResolvedEmoji, w as hasAll, x as RequirePermissions, xt as ContextMenus, y as Silence, z as NotInDm, zt as RowComponent } from "./subscribers-Ce3SWy23.mjs";
 import { n as StartupPhase, t as ShutdownPhase } from "./phases-BauKJOTT.mjs";
 import "reflect-metadata";
 import { CustomId, decodeFor, prefixOf, setCustomIdErrors, setCustomIdErrors as setCustomIdErrors$1 } from "@seedcord/custom-id";
@@ -314,7 +312,7 @@ var DispatchContext = class {
 	/**
 	* Read a key that must be present, with `undefined` stripped from the result.
 	*
-	* @throws A **SeedcordError** If nothing set the key on this dispatch.
+	* @throws A **SeedcordError** when nothing set the key on this dispatch.
 	*/
 	require(key) {
 		const value = this.state[key];
@@ -396,10 +394,11 @@ var RepliableHandler = class extends BaseHandler {
 //#endregion
 //#region src/reply/BaseReplySender.ts
 /**
-* Tracks acknowledgement state and throws a translated `SeedcordError` on an illegal verb before any
-* transport call. Every verb runs the legality check, calls the transport's wire writer, then updates
-* the state and the ack trace. Each transport binds `TMessage` to its own created-message type and
-* supplies the writers.
+* Tracks acknowledgement state. Every verb runs the legality check, calls the transport's wire writer,
+* then updates the state and the ack trace. Each transport binds `TMessage` to its own created-message
+* type and supplies the writers.
+*
+* @throws A **SeedcordError** when you call a verb the current ack state doesn't allow. It throws before any transport call.
 */
 var BaseReplySender = class {
 	telemetry;
@@ -741,14 +740,16 @@ function scopeValue(ctx, per) {
 }
 /**
 * Allows `limit` uses per window, scoped by `per`. A number `duration` is **seconds**, and a string is
-* a duration like `30m` or `24h`. An unparseable string throws a **SeedcordTypeError** at construction. The
-* slot is charged in commit, only after the whole gate set passes, so a later refusal never burns the cooldown.
+* a duration like `30m` or `24h`. The slot is charged in commit, only after the whole gate set passes,
+* so a later refusal never burns the cooldown.
 * That split also means two requests racing the same key can both pass before either charges the slot.
 * The key combines the handler's route with the window settings, keeping two different handlers on separate
 * windows. Reword the refusal with {@link CooldownOptions.message} or replace it with {@link CooldownOptions.notice}.
 *
-* @param duration - A number is seconds, and a string is a duration like `30m` or `24h`. An unparseable string throws a **SeedcordTypeError**.
+* @param duration - A number is seconds, and a string is a duration like `30m` or `24h`.
 * @param options - Sets the scope with `per`, the uses per window with `limit`, and the refusal text with `message` or `notice`.
+* @throws A **SeedcordTypeError** when `duration` is a string that doesn't parse.
+* @throws A **SeedcordRangeError** when `duration` is zero or negative.
 *
 * @see the `@Gated` decorator from your transport package
 * @see {@link IRateLimiter}
@@ -791,7 +792,7 @@ function Cooldown(duration, options) {
 		if (parsed === null) throw new SeedcordTypeError(SeedcordErrorCode.GateInvalidCooldownDuration, [duration]);
 		windowMs = parsed;
 	}
-	if (windowMs <= 0) throw new SeedcordTypeError(SeedcordErrorCode.GateInvalidCooldownDuration, [String(duration)]);
+	if (windowMs <= 0) throw new SeedcordRangeError(SeedcordErrorCode.GateInvalidCooldownDuration, [String(duration)]);
 	const per = options?.per ?? "user";
 	const window = options?.limit === void 0 ? { windowMs } : {
 		windowMs,
@@ -818,7 +819,7 @@ function Cooldown(duration, options) {
 * The caller computes `permissions`, gateway off a discord.js role, member, or channel, and HTTP off the
 * bitfield the interaction payload carries.
 *
-* @throws A {@link Notice} listing the missing or present permissions.
+* @throws A {@link Notice} when the check refuses. It lists the missing or present permissions.
 *
 * @example
 * ```ts
@@ -917,26 +918,6 @@ function mergeRoles(current, add, remove) {
 	return [...new Set(current).union(new Set(add)).difference(new Set(remove))];
 }
 
-//#endregion
-//#region src/miscellaneous/ResolvedEmoji.ts
-/**
-* A resolved custom emoji. Renders as `<:name:id>` in message content, or `<a:name:id>` when animated,
-* and passes straight to a builder's `setEmoji`.
-*/
-var ResolvedEmoji = class {
-	name;
-	id;
-	animated;
-	constructor(name, id, animated = false) {
-		this.name = name;
-		this.id = id;
-		this.animated = animated;
-	}
-	toString() {
-		return `<${this.animated ? "a" : ""}:${this.name}:${this.id}>`;
-	}
-};
-
 //#endregion
 //#region src/pagination/paginate.ts
 /**
@@ -946,7 +927,7 @@ var ResolvedEmoji = class {
 * @param page - The requested zero-based page, clamped into `[0, totalPages - 1]`.
 * @param perPage - The page size. Must be a positive integer.
 * @returns The sliced {@link PageView}, with `totalPages` always known.
-* @throws SeedcordRangeError when `perPage` is not a positive integer.
+* @throws A **SeedcordRangeError** when `perPage` is not a positive integer.
 */
 function paginate(items, page, perPage) {
 	if (!Number.isSafeInteger(perPage) || perPage <= 0) throw new SeedcordRangeError(SeedcordErrorCode.PaginationInvalidPerPage, [perPage]);
@@ -1020,8 +1001,7 @@ var Controls = class {
 		};
 	}
 	row(...keys) {
-		if (keys.length === 0) throw new SeedcordRangeError(SeedcordErrorCode.PaginationEmptyControls);
-		if (keys.length > MAX_BUTTONS_PER_ROW) throw new SeedcordRangeError(SeedcordErrorCode.PaginationTooManyControls, [keys.length]);
+		if (keys.length === 0 || keys.length > MAX_BUTTONS_PER_ROW) throw new SeedcordRangeError(SeedcordErrorCode.PaginationControlCount, [keys.length, MAX_BUTTONS_PER_ROW]);
 		const seen = /* @__PURE__ */ new Set();
 		for (const key of keys) {
 			if (seen.has(key)) throw new SeedcordTypeError(SeedcordErrorCode.PaginationDuplicateControls, [key]);
@@ -1169,7 +1149,7 @@ var CursorSourceBase = class {
 //#endregion
 //#region src/index.ts
 /** Package version */
-const version = "0.9.4";
+const version = "0.11.0-next.0";
 
 //#endregion
 export { ArraySourceBase, AutocompleteRoute, BaseHandler, BaseReplySender, BuilderComponent, Bus, ButtonRoute, ChannelMenuRoute, Commands, ContextMenus, Cooldown, CursorSourceBase, CustomId, DispatchContext, DmOnly, Fault, GuildOnly, InteractionKind, MentionableMenuRoute, MessageContextMenuRoute, ModalRoute, Notice, OwnerOnly, PaginatorBase, RegisterCommand, RegisterInteractionMiddleware, RepliableHandler, RequireBotPermissions, RequirePermissions, RequireRole, ResolvedEmoji, RoleMenuRoute, RowComponent, ShutdownPhase, Silence, SlashRoute, StartupPhase, StringMenuRoute, Subscribe, Subscriber, UserContextMenuRoute, UserMenuRoute, WebhookLog, WebhookUrl, and, assertPermissions, decodeFor, defineEffectGate, defineGate, mergeRoles, or, paginate, prefixOf, setCustomIdErrors, version };