@wolfstar/http-framework 6.2.2 → 6.3.0-next-20261007181329

package/dist/esm/index.d.ts

@@ -11,6 +11,85 @@ import { JSONEncodable } from "@discordjs/util";
 import { webcrypto } from "node:crypto";
 import { ListenOptions as ListenOptions$1 } from "node:net";
 import { ChokidarOptions } from "chokidar";
+//#region src/lib/errors/UserError.d.ts
+/**
+ * The UserError class to be thrown and emitted by the pieces of the framework.
+ *
+ * @remarks
+ * This class is the root of every framework-thrown error, allowing consumers to distinguish
+ * errors that are meant to be shown to the user from unexpected, internal ones.
+ *
+ * When a command, an autocomplete handler, or an interaction handler throws a `UserError` (or any subclass), the
+ * client emits the matching `*Denied` event ({@link Events.ChatInputCommandDenied}, {@link Events.ContextMenuCommandDenied},
+ * {@link Events.AutocompleteDenied}, or {@link Events.InteractionHandlerDenied}) instead of the `*Error` one, so listeners
+ * can reply to the user without reporting an expected failure as a bug. Use {@link isUserError} to apply the same check.
+ *
+ * @property name This will be `'UserError'` and can be used to distinguish the type of error when any error gets thrown.
+ * @since 3.2.0
+ * @example
+ * ```typescript
+ * throw new UserError({
+ * 	identifier: Identifiers.ArgumentIntegerTooSmall,
+ * 	message: 'The number you provided is too small.',
+ * 	context: { received: 2, minimum: 3 }
+ * });
+ * ```
+ */
+export declare class UserError extends Error {
+  /**
+   * An identifier, useful to localize emitted errors.
+   * @since 3.2.0
+   */
+  readonly identifier: string;
+  /**
+   * User-provided context.
+   * @since 3.2.0
+   */
+  readonly context: unknown;
+  /**
+   * Constructs an UserError.
+   * @param options The UserError options
+   */
+  constructor(options: UserError.Options);
+  get name(): string;
+}
+export declare namespace UserError {
+  /**
+   * The options for {@link UserError}.
+   * @since 3.2.0
+   */
+  interface Options {
+    /**
+     * The identifier for this error.
+     * @since 3.2.0
+     */
+    identifier: string;
+    /**
+     * The message to be passed to the Error constructor.
+     * @since 3.2.0
+     */
+    message?: string;
+    /**
+     * The extra context to provide more information about this error.
+     * @since 3.2.0
+     * @default null
+     */
+    context?: unknown;
+  }
+}
+/**
+ * Checks whether a value is a {@link UserError}, which is how the client tells an expected failure from an unexpected
+ * one.
+ *
+ * @remarks `instanceof` is tried first. A bundle that inlines the framework, or a second installed copy of it, has its
+ * own `UserError` class that `instanceof` does not recognise, so any `Error` with a string `identifier` and a `context`
+ * property is accepted too.
+ * @param error The value to check.
+ * @returns Whether the value is a `UserError`.
+ * @since 6.3.0
+ */
+export declare function isUserError(error: unknown): error is UserError;
+//#endregion
 //#region src/lib/utils/internals.d.ts
 type Void = void;
 //#endregion
@@ -366,7 +445,7 @@ export declare class CommandStoreRouter {
    * @param interaction - The interaction object.
    * @returns The command associated with the interaction, or null if not found.
    */
-  get(interaction: APIApplicationCommandInteraction): Command<import("@sapphire/pieces").PieceOptions> | null;
+  get(interaction: APIApplicationCommandInteraction): Command<Command.Options> | null;
   /**
    * Gets the chat input command with the specified name.
    *
@@ -1578,6 +1657,389 @@ export declare class CommandRouter<Options extends Command.Options = Command.Opt
   routeContextMenuInteraction(data: APIContextMenuInteractionData): string | null;
 }
 //#endregion
+//#region src/lib/structures/InteractionHandler.d.ts
+export declare abstract class InteractionHandler<Options extends InteractionHandler.Options = InteractionHandler.Options> extends Piece$1<Options, 'interaction-handlers'> {
+  constructor(context: InteractionHandler.LoaderContext, options?: Options);
+  abstract run(interaction: InteractionHandler.Interaction, customIdValue: unknown): Awaited<unknown>;
+}
+export declare namespace InteractionHandler {
+  type ButtonInteraction = Interactions.MessageComponentButton;
+  type SelectMenuInteraction = Interactions.MessageComponentSelectMenu;
+  type ModalInteraction = Interactions.ModalSubmit;
+  type MessageComponentInteraction = Interactions.MessageComponent;
+  type ContextMenuInteraction = Interactions.ContextMenuCommand;
+  type ApplicationCommandInteraction = Interactions.ApplicationCommand;
+  type Interaction = Interactions.MessageComponent;
+  type InteractionData = Interaction['data'];
+  /** @deprecated Use {@linkcode LoaderContext} instead. */
+  type Context = LoaderContext;
+  type LoaderContext = Piece$1.LoaderContext<'interaction-handlers'>;
+  type JSON = Piece$1.JSON;
+  type LocationJSON = Piece$1.LocationJSON;
+  interface Options extends Piece$1.Options {
+    /**
+     * The checks to run, in order, before the handler, after the global preconditions. An entry is the name of a
+     * `Precondition` piece (which needs an `interactionHandlerRun` method to apply), that name with a `context`, a
+     * function, or an array of entries (see `Command.Options.preconditions`). The first denial stops the interaction: the handler is not run and the error is
+     * emitted as `interactionHandlerDenied`.
+     *
+     * @since 6.3.0
+     * @default []
+     */
+    preconditions?: PreconditionArrayResolvable<PreconditionFunction<Interaction, InteractionHandler>>;
+  }
+}
+//#endregion
+//#region src/lib/errors/PreconditionError.d.ts
+/**
+ * Errors thrown by preconditions, that is, any check that runs before a command or an interaction
+ * handler is executed, such as the guild restrictions applied by
+ * {@link RestrictGuildIds}.
+ *
+ * @remarks Being a {@link UserError}, it is emitted as a `*Denied` event when thrown from a command, an autocomplete
+ * handler, or an interaction handler, and not as `commandError`. The framework has no precondition store: the
+ * decorators of `@wolfstar/decorators` are what throws it.
+ *
+ * @property name This will be `'PreconditionError'` and can be used to distinguish the type of error when any error gets thrown.
+ * @since 3.2.0
+ * @example
+ * ```typescript
+ * throw new PreconditionError({
+ * 	precondition: 'GuildIds',
+ * 	identifier: Identifiers.PreconditionGuildIds,
+ * 	message: 'This command can only be used in specific guilds.',
+ * 	context: { guildIds: ['737141877803057244'] }
+ * });
+ * ```
+ */
+export declare class PreconditionError extends UserError {
+  /**
+   * The name of the precondition that caused the error.
+   * @since 3.2.0
+   */
+  readonly precondition: string;
+  constructor(options: PreconditionError.Options);
+  get name(): string;
+}
+export declare namespace PreconditionError {
+  /**
+   * The options for {@link PreconditionError}.
+   * @since 3.2.0
+   */
+  interface Options extends Omit<UserError.Options, 'identifier'> {
+    /**
+     * The name of the precondition that caused the error.
+     * @since 3.2.0
+     */
+    precondition: string;
+    /**
+     * The identifier.
+     * @since 3.2.0
+     * @default precondition
+     */
+    identifier?: string;
+  }
+}
+//#endregion
+//#region src/lib/structures/Precondition.d.ts
+/**
+ * A check that runs before a command method does, loaded from the `preconditions` directory into the
+ * `preconditions` store.
+ *
+ * @remarks A precondition with a `position` is global: it runs, in ascending order of `position`, before the
+ * preconditions of every chat input and context menu command, and of every autocomplete and interaction handler that
+ * it has a method for. Any other one runs only for the commands that list its
+ * name in the `preconditions` option. The method it needs depends on the command, and a precondition that is asked to
+ * run for a kind of command it has no method for denies the command with
+ * {@linkcode Identifiers.PreconditionMissingChatInputHandler} or
+ * {@linkcode Identifiers.PreconditionMissingContextMenuHandler}.
+ * @since 6.3.0
+ * @example
+ * ```typescript
+ * import { Precondition } from '@wolfstar/http-framework';
+ *
+ * export class UserPrecondition extends Precondition {
+ * 	public override chatInputRun(interaction: Precondition.ChatInputInteraction) {
+ * 		return interaction.user.id === process.env.OWNER_ID ? this.ok() : this.error({ message: 'Only the owner can use this command.' });
+ * 	}
+ * }
+ * ```
+ */
+export declare class Precondition<Options extends Precondition.Options = Precondition.Options> extends Piece$1<Options, 'preconditions'> {
+  /**
+   * The position of the precondition in the list of global preconditions, or `null` when it is not global.
+   * @since 6.3.0
+   */
+  readonly position: number | null;
+  constructor(context: Precondition.LoaderContext, options?: Options);
+  /**
+   * Checks a chat input command.
+   *
+   * @param interaction The interaction of the command.
+   * @param command The command that is about to run.
+   * @param context The context of the check: the `context` given in the `preconditions` option of the command.
+   */
+  chatInputRun?(interaction: Precondition.ChatInputInteraction, command: Command, context: Precondition.Context): Precondition.Result;
+  /**
+   * Checks a user or message context menu command.
+   *
+   * @param interaction The interaction of the command.
+   * @param command The command that is about to run.
+   * @param context The context of the check: the `context` given in the `preconditions` option of the command.
+   */
+  contextMenuRun?(interaction: Precondition.ContextMenuInteraction, command: Command, context: Precondition.Context): Precondition.Result;
+  /**
+   * Checks the autocomplete of a command. Unlike `chatInputRun` and `contextMenuRun`, a precondition without this
+   * method is skipped, not denied, so a check written for the commands does not break their autocomplete.
+   *
+   * @param interaction The autocomplete interaction.
+   * @param command The command whose autocomplete is about to run.
+   * @param context The context of the check: the `context` given in the `preconditions` option of the command.
+   * @since 6.3.0
+   */
+  autocompleteRun?(interaction: Precondition.AutocompleteInteraction, command: Command, context: Precondition.Context): Precondition.Result;
+  /**
+   * Checks an interaction handler (a button, a select menu, or a modal). A precondition without this method is
+   * skipped, not denied.
+   *
+   * @param interaction The interaction of the component or modal.
+   * @param handler The interaction handler that is about to run.
+   * @param context The context of the check: the `context` given in the `preconditions` option of the handler.
+   * @since 6.3.0
+   */
+  interactionHandlerRun?(interaction: Precondition.InteractionHandlerInteraction, handler: InteractionHandler, context: Precondition.Context): Precondition.Result;
+  /**
+   * Lets the command run.
+   * @since 6.3.0
+   */
+  ok(): Precondition.Result;
+  /**
+   * Denies the command with a {@link PreconditionError} whose `precondition` is the name of this piece.
+   *
+   * @param options The message, identifier and context of the error.
+   * @since 6.3.0
+   */
+  error(options?: Omit<PreconditionError.Options, 'precondition'>): Precondition.Result;
+}
+/**
+ * A {@link Precondition} that has to implement the check for every kind of command.
+ *
+ * @since 6.3.0
+ */
+export declare abstract class AllFlowsPrecondition extends Precondition {
+  abstract chatInputRun(interaction: Precondition.ChatInputInteraction, command: Command, context: Precondition.Context): Precondition.Result;
+  abstract contextMenuRun(interaction: Precondition.ContextMenuInteraction, command: Command, context: Precondition.Context): Precondition.Result;
+}
+export interface PreconditionOptions extends Piece$1.Options {
+  /**
+   * The position of the precondition in the list of global preconditions. When it is `null`, the precondition is not
+   * global and only runs for the commands that list it.
+   * @since 6.3.0
+   * @default null
+   */
+  position?: number | null;
+}
+export declare namespace Precondition {
+  type Options = PreconditionOptions;
+  type LoaderContext = Piece$1.LoaderContext<'preconditions'>;
+  type Context = PreconditionContext;
+  type Result = PreconditionResult;
+  type ChatInputInteraction = Command.ChatInputInteraction;
+  type ContextMenuInteraction = Command.ContextMenuInteraction;
+  type AutocompleteInteraction = Command.AutocompleteInteraction;
+  type InteractionHandlerInteraction = InteractionHandler.Interaction;
+}
+export declare namespace AllFlowsPrecondition {
+  type Options = PreconditionOptions;
+  type LoaderContext = Piece$1.LoaderContext<'preconditions'>;
+  type Context = PreconditionContext;
+  type Result = PreconditionResult;
+}
+//#endregion
+//#region src/lib/utils/preconditions.d.ts
+/**
+ * What a precondition returns: `Result.ok()` to let the command run, or a `Result.err(error)` with a
+ * {@link UserError} (usually a `PreconditionError`) to deny it.
+ *
+ * @since 6.3.0
+ */
+export type PreconditionResult = Awaitable<Result<unknown, UserError>>;
+/**
+ * The data a precondition is given besides the interaction and the command.
+ *
+ * @since 6.3.0
+ */
+export type PreconditionContext = Record<PropertyKey, unknown>;
+/**
+ * What a precondition is run for, which decides the method it is asked for: `chatInputRun`, `contextMenuRun`,
+ * `autocompleteRun`, or `interactionHandlerRun`.
+ *
+ * @remarks A piece with no method for a chat input or context menu command denies it. For `autocomplete` and
+ * `interactionHandler` it is skipped instead, since a check written for the commands says nothing about their
+ * autocomplete or about the components of the bot.
+ * @since 6.3.0
+ */
+export type PreconditionKind = 'chatInput' | 'contextMenu' | 'autocomplete' | 'interactionHandler';
+/**
+ * The piece a precondition guards: the command, or the interaction handler.
+ *
+ * @since 6.3.0
+ */
+export type PreconditionTarget = Command | InteractionHandler;
+/**
+ * The interactions a precondition can be run for.
+ *
+ * @since 6.3.0
+ */
+export type PreconditionInteraction = Command.ApplicationCommandInteraction | Command.AutocompleteInteraction | InteractionHandler.Interaction;
+/**
+ * A precondition written as a function, for a check that does not need a piece of its own. In the `preconditions` option
+ * of a command it is used for chat input and context menu commands, not for their autocomplete. In the option of an
+ * interaction handler it is used for the handler.
+ *
+ * @since 6.3.0
+ * @example
+ * ```typescript
+ * import { err, ok } from '@sapphire/result';
+ * import { Command, PreconditionError, type PreconditionFunction } from '@wolfstar/http-framework';
+ *
+ * const OwnerOnly: PreconditionFunction = (interaction) =>
+ * 	interaction.user.id === process.env.OWNER_ID
+ * 		? ok()
+ * 		: err(new PreconditionError({ precondition: 'OwnerOnly', message: 'Only the owner can use this command.' }));
+ *
+ * export class UserCommand extends Command {
+ * 	public constructor(context: Command.LoaderContext, options: Command.Options) {
+ * 		super(context, { ...options, preconditions: [OwnerOnly] });
+ * 	}
+ * }
+ * ```
+ */
+export type PreconditionFunction<Interaction = Command.ApplicationCommandInteraction, Target = Command> = (interaction: Interaction, target: Target) => PreconditionResult;
+/**
+ * The name of a {@link Precondition} piece, with the context to give it.
+ *
+ * @since 6.3.0
+ */
+export interface PreconditionDetails {
+  /**
+   * The name of the precondition in the `preconditions` store.
+   * @since 6.3.0
+   */
+  name: string;
+  /**
+   * The context to give to the precondition.
+   * @since 6.3.0
+   * @default {}
+   */
+  context?: PreconditionContext;
+}
+/**
+ * An entry of the `preconditions` option of a command: the name of a {@link Precondition} piece, that name with a
+ * context, or a {@link PreconditionFunction}.
+ *
+ * @since 6.3.0
+ */
+export type PreconditionResolvable<Function = PreconditionFunction> = string | PreconditionDetails | Function;
+/**
+ * How the entries of an array of preconditions are run.
+ *
+ * @since 6.3.0
+ */
+export declare enum PreconditionRunMode {
+  /**
+   * The entries are run one after the other. This is the default, and it stops as soon as the result is known.
+   * @since 6.3.0
+   */
+  Sequential = 0,
+  /**
+   * Every entry is started at once and awaited with `Promise.all`, then the results are read. It is faster when the
+   * checks are slow, but none of them is skipped once another one has settled the result.
+   * @since 6.3.0
+   */
+  Parallel = 1
+}
+/**
+ * How the results of the entries of an array of preconditions are combined.
+ *
+ * @since 6.3.0
+ */
+export declare enum PreconditionRunCondition {
+  /**
+   * Every entry has to pass: the first `Err` is the result.
+   * @since 6.3.0
+   */
+  And = 0,
+  /**
+   * One entry has to pass: the first `Ok` is the result, and when none does, the last `Err`.
+   * @since 6.3.0
+   */
+  Or = 1
+}
+/**
+ * An array of preconditions with the {@link PreconditionRunMode} to run it with.
+ *
+ * @since 6.3.0
+ */
+export interface PreconditionArrayDetails<Function = PreconditionFunction> {
+  /**
+   * The entries of the array.
+   * @since 6.3.0
+   */
+  entries: readonly PreconditionEntryResolvable<Function>[];
+  /**
+   * The mode to run the array and the arrays nested in it with.
+   * @since 6.3.0
+   */
+  mode: PreconditionRunMode;
+}
+/**
+ * An array of preconditions: a list of entries, or a list with a {@link PreconditionRunMode}.
+ *
+ * @since 6.3.0
+ */
+export type PreconditionArrayResolvable<Function = PreconditionFunction> = readonly PreconditionEntryResolvable<Function>[] | PreconditionArrayDetails<Function>;
+/**
+ * An entry of an array of preconditions: a single precondition, or a nested array.
+ *
+ * @since 6.3.0
+ */
+export type PreconditionEntryResolvable<Function = PreconditionFunction> = PreconditionResolvable<Function> | PreconditionArrayResolvable<Function>;
+/**
+ * Runs a {@link Precondition} piece for the given kind of interaction.
+ *
+ * @param precondition The precondition to run.
+ * @param kind What is being run.
+ * @param interaction The interaction being handled.
+ * @param target The command or interaction handler being run.
+ * @param context The context of the check.
+ * @returns The result of the precondition. A chat input or context menu command is denied when the piece has no method
+ * for it, an autocomplete or an interaction handler is let through.
+ * @since 6.3.0
+ */
+export declare function runPrecondition(precondition: Precondition, kind: PreconditionKind, interaction: PreconditionInteraction, target: PreconditionTarget, context?: PreconditionContext): PreconditionResult;
+/**
+ * Runs the preconditions of a command or an interaction handler: first the global ones of the `preconditions` store,
+ * then the entries of its `preconditions` option, stopping at the first denial.
+ *
+ * @remarks
+ * - The `preconditions` option is an array that runs with {@link PreconditionRunCondition.And}: every entry has to pass.
+ *   An array nested in it runs with `Or`, one nested in that with `And` again, and so on, so
+ *   `['Connect', ['Moderator', ['DJ', 'SongAuthor']]]` is `Connect && (Moderator || (DJ && SongAuthor))`.
+ * - The {@link PreconditionRunMode} is `Sequential`, or the `mode` of the array written as `{ entries, mode }`, which the
+ *   arrays nested in it inherit.
+ * - An entry that names a precondition missing from the store denies the interaction with
+ *   {@linkcode Identifiers.PreconditionUnavailable}.
+ * - An entry that does not apply to the interaction, such as a function for an autocomplete or a piece with no method for
+ *   it, is left out of the result. An array in which no entry applies is left out as well.
+ * @param target The command or interaction handler being run.
+ * @param kind What is being run.
+ * @param interaction The interaction being handled.
+ * @returns The first `Err`, or `Result.ok()` when every precondition lets it run.
+ * @since 6.3.0
+ */
+export declare function runPreconditions(target: PreconditionTarget, kind: PreconditionKind, interaction: PreconditionInteraction): Promise<Result<unknown, UserError>>;
+//#endregion
 //#region src/lib/structures/Command.d.ts
 /**
  * The options a command receives, by the full path of the command (`'ping'`, `'stickyroles add'`,
@@ -1691,29 +2153,20 @@ export declare namespace Command {
   type LoaderContext = Piece$1.LoaderContext<'commands'>;
   type JSON = Piece$1.JSON;
   type LocationJSON = Piece$1.LocationJSON;
-  type Options = Piece$1.Options;
-}
-//#endregion
-//#region src/lib/structures/InteractionHandler.d.ts
-export declare abstract class InteractionHandler<Options extends InteractionHandler.Options = InteractionHandler.Options> extends Piece$1<Options, 'interaction-handlers'> {
-  constructor(context: InteractionHandler.LoaderContext, options?: Options);
-  abstract run(interaction: InteractionHandler.Interaction, customIdValue: unknown): Awaited<unknown>;
-}
-export declare namespace InteractionHandler {
-  type ButtonInteraction = Interactions.MessageComponentButton;
-  type SelectMenuInteraction = Interactions.MessageComponentSelectMenu;
-  type ModalInteraction = Interactions.ModalSubmit;
-  type MessageComponentInteraction = Interactions.MessageComponent;
-  type ContextMenuInteraction = Interactions.ContextMenuCommand;
-  type ApplicationCommandInteraction = Interactions.ApplicationCommand;
-  type Interaction = Interactions.MessageComponent;
-  type InteractionData = Interaction['data'];
-  /** @deprecated Use {@linkcode LoaderContext} instead. */
-  type Context = LoaderContext;
-  type LoaderContext = Piece$1.LoaderContext<'interaction-handlers'>;
-  type JSON = Piece$1.JSON;
-  type LocationJSON = Piece$1.LocationJSON;
-  type Options = Piece$1.Options;
+  interface Options extends Piece$1.Options {
+    /**
+     * The checks to run, in order, before a chat input or context menu method of the command, after the global
+     * preconditions. An entry is the name of a `Precondition` piece, that name with a `context`, a function, or an
+     * array of entries: the list is an `And`, a nested array an `Or`, and one nested in that an `And` again. The list
+     * can also be `{ entries, mode }` to run in parallel. The first denial stops the command: the method is not run
+     * and the error is emitted as `chatInputCommandDenied` or `contextMenuCommandDenied`. The autocomplete of the
+     * command only runs the pieces named here that have an `autocompleteRun` method, not the functions.
+     *
+     * @since 6.3.0
+     * @default []
+     */
+    preconditions?: PreconditionArrayResolvable;
+  }
 }
 //#endregion
 //#region src/lib/types/Enums.d.ts
@@ -1761,19 +2214,29 @@ export declare enum Events {
   CommandNameMissing = "commandNameMissing",
   CommandNameUnknown = "commandNameUnknown",
   CommandMethodUnknown = "commandMethodUnknown",
+  PreChatInputCommandRun = "preChatInputCommandRun",
+  PreContextMenuCommandRun = "preContextMenuCommandRun",
+  ChatInputCommandAccepted = "chatInputCommandAccepted",
+  ContextMenuCommandAccepted = "contextMenuCommandAccepted",
   CommandRun = "commandRun",
   CommandSuccess = "commandSuccess",
   CommandError = "commandError",
+  ChatInputCommandDenied = "chatInputCommandDenied",
+  ContextMenuCommandDenied = "contextMenuCommandDenied",
   CommandFinish = "commandFinish",
+  AutocompleteAccepted = "autocompleteAccepted",
   AutocompleteRun = "autocompleteRun",
   AutocompleteSuccess = "autocompleteSuccess",
   AutocompleteError = "autocompleteError",
+  AutocompleteDenied = "autocompleteDenied",
   AutocompleteFinish = "autocompleteFinish",
   InteractionHandlerNameInvalid = "interactionHandlerNameInvalid",
   InteractionHandlerNameUnknown = "interactionHandlerNameUnknown",
+  InteractionHandlerAccepted = "interactionHandlerAccepted",
   InteractionHandlerRun = "interactionHandlerRun",
   InteractionHandlerSuccess = "interactionHandlerSuccess",
   InteractionHandlerError = "interactionHandlerError",
+  InteractionHandlerDenied = "interactionHandlerDenied",
   InteractionHandlerFinish = "interactionHandlerFinish",
   HmrStart = "hmrStart",
   HmrStop = "hmrStop",
@@ -1800,19 +2263,98 @@ export interface ClientEvents {
   commandNameMissing: [interaction: APIApplicationCommandAutocompleteInteraction, response: ServerResponse];
   commandNameUnknown: [interaction: APIApplicationCommandInteraction | APIApplicationCommandAutocompleteInteraction, response: ServerResponse];
   commandMethodUnknown: [context: ClientEventCommandContext];
+  /**
+   * Emitted for a chat input command before its preconditions run, then followed by either
+   * {@link ClientEvents.chatInputCommandDenied} or {@link ClientEvents.chatInputCommandAccepted}.
+   *
+   * @since 6.3.0
+   */
+  preChatInputCommandRun: [context: ClientEventCommandContext];
+  /**
+   * Emitted for a user or message context menu command before its preconditions run, then followed by either
+   * {@link ClientEvents.contextMenuCommandDenied} or {@link ClientEvents.contextMenuCommandAccepted}.
+   *
+   * @since 6.3.0
+   */
+  preContextMenuCommandRun: [context: ClientEventCommandContext];
+  /**
+   * Emitted when a chat input command passes every precondition, right before {@link ClientEvents.commandRun}.
+   *
+   * @since 6.3.0
+   */
+  chatInputCommandAccepted: [context: ClientEventCommandContext];
+  /**
+   * Emitted when a context menu command passes every precondition, right before {@link ClientEvents.commandRun}.
+   *
+   * @since 6.3.0
+   */
+  contextMenuCommandAccepted: [context: ClientEventCommandContext];
+  /**
+   * Emitted right before the method of a command runs. Since 6.3.0 that is after its preconditions passed, so a
+   * denied command does not emit it.
+   */
   commandRun: [context: ClientEventCommandContext];
   commandSuccess: [context: ClientEventCommandContext, value: unknown];
+  /**
+   * Emitted when a command throws something that is not a {@link UserError}. A {@link UserError} is emitted as
+   * {@link ClientEvents.chatInputCommandDenied} or {@link ClientEvents.contextMenuCommandDenied} instead.
+   *
+   * @remarks Since 6.3.0 a thrown {@link UserError} (such as the `PreconditionError` of `@wolfstar/decorators`) no
+   * longer reaches this event.
+   */
   commandError: [error: unknown, context: ClientEventCommandContext];
+  /**
+   * Emitted when a chat input command throws a {@link UserError}, an expected failure that is meant to be shown to the
+   * user. The `error` event is still emitted, and the HTTP response is produced as for any other thrown error
+   * (`httpReplyOnError`).
+   *
+   * @since 6.3.0
+   */
+  chatInputCommandDenied: [error: UserError, context: ClientEventCommandContext];
+  /**
+   * Emitted when a user or message context menu command throws a {@link UserError}. See
+   * {@link ClientEvents.chatInputCommandDenied}.
+   *
+   * @since 6.3.0
+   */
+  contextMenuCommandDenied: [error: UserError, context: ClientEventCommandContext];
   commandFinish: [context: ClientEventCommandContext];
+  /**
+   * Emitted when an autocomplete interaction passes every precondition, right before
+   * {@link ClientEvents.autocompleteRun}.
+   *
+   * @since 6.3.0
+   */
+  autocompleteAccepted: [context: ClientEventAutocompleteContext];
   autocompleteRun: [context: ClientEventAutocompleteContext];
   autocompleteSuccess: [context: ClientEventAutocompleteContext, value: unknown];
   autocompleteError: [error: unknown, context: ClientEventAutocompleteContext];
+  /**
+   * Emitted when an autocomplete handler throws a {@link UserError}, instead of {@link ClientEvents.autocompleteError}.
+   *
+   * @since 6.3.0
+   */
+  autocompleteDenied: [error: UserError, context: ClientEventAutocompleteContext];
   autocompleteFinish: [context: ClientEventAutocompleteContext];
   interactionHandlerNameInvalid: [interaction: APIMessageComponentInteraction | APIModalSubmitInteraction, response: ServerResponse];
   interactionHandlerNameUnknown: [interaction: APIMessageComponentInteraction | APIModalSubmitInteraction, response: ServerResponse];
+  /**
+   * Emitted when an interaction handler passes every precondition, right before
+   * {@link ClientEvents.interactionHandlerRun}.
+   *
+   * @since 6.3.0
+   */
+  interactionHandlerAccepted: [context: ClientEventInteractionHandlerContext];
   interactionHandlerRun: [context: ClientEventInteractionHandlerContext];
   interactionHandlerSuccess: [context: ClientEventInteractionHandlerContext, value: unknown];
   interactionHandlerError: [error: unknown, context: ClientEventInteractionHandlerContext];
+  /**
+   * Emitted when an interaction handler throws a {@link UserError}, instead of
+   * {@link ClientEvents.interactionHandlerError}.
+   *
+   * @since 6.3.0
+   */
+  interactionHandlerDenied: [error: UserError, context: ClientEventInteractionHandlerContext];
   interactionHandlerFinish: [context: ClientEventInteractionHandlerContext];
   /**
    * Emitted when the Hot Module Reloader starts watching, with the list of watched store paths.
@@ -2158,6 +2700,7 @@ export declare class PluginManager {
 //#endregion
 //#region src/lib/structures/InteractionHandlerStore.d.ts
 export declare class InteractionHandlerStore extends Store$1<InteractionHandler, 'interaction-handlers'> {
+  #private;
   constructor();
   runHandler(response: ServerResponse, interaction: APIMessageComponentInteraction | APIModalSubmitInteraction): Promise<ServerResponse>;
 }
@@ -2195,6 +2738,27 @@ export declare class ListenerStore extends Store$1<Listener, 'listeners'> {
   constructor();
 }
 //#endregion
+//#region src/lib/structures/PreconditionStore.d.ts
+export declare class PreconditionStore extends Store$1<Precondition, 'preconditions'> {
+  #private;
+  constructor();
+  /**
+   * Runs the global preconditions, the ones with a `position`, in ascending order of it, stopping at the first one
+   * that denies the interaction.
+   *
+   * @since 6.3.0
+   * @param kind What is being run.
+   * @param interaction The interaction being handled.
+   * @param target The command or interaction handler being run.
+   * @param context The context of the checks.
+   * @returns The first `Err`, or `Result.ok()` when every global precondition lets the command run.
+   */
+  run(kind: PreconditionKind, interaction: PreconditionInteraction, target: PreconditionTarget, context?: PreconditionContext): Promise<Result<unknown, UserError>>;
+  set(key: string, value: Precondition): this;
+  delete(key: string): boolean;
+  clear(): void;
+}
+//#endregion
 //#region src/lib/utils/logger/ILogger.d.ts
 /**
  * The available log levels, ordered from the most verbose to the least. A {@link ILogger} only writes the entries
@@ -2485,6 +3049,7 @@ declare module '@sapphire/pieces' {
     commands: CommandStore;
     'interaction-handlers': InteractionHandlerStore;
     listeners: ListenerStore;
+    preconditions: PreconditionStore;
   }
   interface Container {
     client: Client;
@@ -2879,72 +3444,14 @@ export declare class StringIdParser implements IIdParser {
   run(customId: string): IdParserRead | null;
 }
 //#endregion
-//#region src/lib/errors/UserError.d.ts
-/**
- * The UserError class to be thrown and emitted by the pieces of the framework.
- *
- * @remarks
- * This class is the root of every framework-thrown error, allowing consumers to distinguish
- * errors that are meant to be shown to the user from unexpected, internal ones.
- *
- * @property name This will be `'UserError'` and can be used to distinguish the type of error when any error gets thrown.
- * @since 3.2.0
- * @example
- * ```typescript
- * throw new UserError({
- * 	identifier: Identifiers.ArgumentIntegerTooSmall,
- * 	message: 'The number you provided is too small.',
- * 	context: { received: 2, minimum: 3 }
- * });
- * ```
- */
-export declare class UserError extends Error {
-  /**
-   * An identifier, useful to localize emitted errors.
-   * @since 3.2.0
-   */
-  readonly identifier: string;
-  /**
-   * User-provided context.
-   * @since 3.2.0
-   */
-  readonly context: unknown;
-  /**
-   * Constructs an UserError.
-   * @param options The UserError options
-   */
-  constructor(options: UserError.Options);
-  get name(): string;
-}
-export declare namespace UserError {
-  /**
-   * The options for {@link UserError}.
-   * @since 3.2.0
-   */
-  interface Options {
-    /**
-     * The identifier for this error.
-     * @since 3.2.0
-     */
-    identifier: string;
-    /**
-     * The message to be passed to the Error constructor.
-     * @since 3.2.0
-     */
-    message?: string;
-    /**
-     * The extra context to provide more information about this error.
-     * @since 3.2.0
-     * @default null
-     */
-    context?: unknown;
-  }
-}
-//#endregion
 //#region src/lib/errors/ArgumentError.d.ts
 /**
  * Errors thrown while resolving the options (arguments) of an interaction.
  *
+ * @remarks The framework never throws this error by itself: Discord validates the type and the bounds of the options
+ * before sending the interaction. It is meant to be thrown from a command that rejects a value, and, being a
+ * {@link UserError}, it is emitted as a `*Denied` event.
+ *
  * @property name This will be `'ArgumentError'` and can be used to distinguish the type of error when any error gets thrown.
  * @since 3.2.0
  * @example
@@ -3085,6 +3592,8 @@ export declare enum Identifiers {
   PreconditionClientPermissionsNoPermissions = "preconditionClientPermissionsNoPermissions",
   PreconditionCooldown = "preconditionCooldown",
   PreconditionGuildIds = "preconditionGuildIds",
+  PreconditionMissingChatInputHandler = "preconditionMissingChatInputHandler",
+  PreconditionMissingContextMenuHandler = "preconditionMissingContextMenuHandler",
   PreconditionNSFW = "preconditionNsfw",
   PreconditionRunIn = "preconditionRunIn",
   PreconditionUnavailable = "preconditionUnavailable",
@@ -3096,53 +3605,6 @@ export declare enum Identifiers {
   ChatInputRouterSubcommandLinkInvalid = "chatInputRouterSubcommandLinkInvalid"
 }
 //#endregion
-//#region src/lib/errors/PreconditionError.d.ts
-/**
- * Errors thrown by preconditions, that is, any check that runs before a command or an interaction
- * handler is executed, such as the guild restrictions applied by
- * {@link RestrictGuildIds}.
- *
- * @property name This will be `'PreconditionError'` and can be used to distinguish the type of error when any error gets thrown.
- * @since 3.2.0
- * @example
- * ```typescript
- * throw new PreconditionError({
- * 	precondition: 'GuildIds',
- * 	identifier: Identifiers.PreconditionGuildIds,
- * 	message: 'This command can only be used in specific guilds.',
- * 	context: { guildIds: ['737141877803057244'] }
- * });
- * ```
- */
-export declare class PreconditionError extends UserError {
-  /**
-   * The name of the precondition that caused the error.
-   * @since 3.2.0
-   */
-  readonly precondition: string;
-  constructor(options: PreconditionError.Options);
-  get name(): string;
-}
-export declare namespace PreconditionError {
-  /**
-   * The options for {@link PreconditionError}.
-   * @since 3.2.0
-   */
-  interface Options extends Omit<UserError.Options, 'identifier'> {
-    /**
-     * The name of the precondition that caused the error.
-     * @since 3.2.0
-     */
-    precondition: string;
-    /**
-     * The identifier.
-     * @since 3.2.0
-     * @default precondition
-     */
-    identifier?: string;
-  }
-}
-//#endregion
 //#region src/lib/structures/CommandLoaderStrategy.d.ts
 /**
  * Represents a strategy for loading and unloading commands.
@@ -3158,7 +3620,7 @@ export declare class CommandLoaderStrategy extends LoaderStrategy<Command> {
    * @param piece - The command being loaded.
    * @returns The loaded command.
    */
-  onLoad(store: CommandStore, piece: Command): Command<import("@sapphire/pieces").PieceOptions>;
+  onLoad(store: CommandStore, piece: Command): Command<Command.Options>;
   /**
    * Called when a command is unloaded.
    *
@@ -3171,7 +3633,7 @@ export declare class CommandLoaderStrategy extends LoaderStrategy<Command> {
    * @param piece - The command being unloaded.
    * @returns The unloaded command.
    */
-  onUnload(store: CommandStore, piece: Command): Command<import("@sapphire/pieces").PieceOptions>;
+  onUnload(store: CommandStore, piece: Command): Command<Command.Options>;
 }
 //#endregion
 //#region src/lib/structures/ListenerLoaderStrategy.d.ts