spearkit 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as discord_js from 'discord.js';
-import { APIEmbedField, APIEmbedFooter, APIEmbedAuthor, EmbedBuilder, Client, Channel, Guild, GuildMember, MessageManager, Message, Role, User, APIInteractionGuildMember, Awaitable, PermissionResolvable, RepliableInteraction, InteractionReplyOptions, InteractionResponse, APIApplicationCommandChannelOption, CommandInteractionOption, Attachment, ApplicationCommandOptionType, LocalizationMap, ChatInputCommandInteraction, APIApplicationCommandBasicOption, AutocompleteInteraction, JSONEncodable, APIModalInteractionResponseCallbackData, ModalComponentData, ModalBuilder, RESTPostAPIChatInputApplicationCommandsJSONBody, RESTPostAPIApplicationCommandsJSONBody, REST, RESTPutAPIApplicationCommandsResult, RESTPutAPIApplicationGuildCommandsResult, ClientEvents, ButtonInteraction, ChannelSelectMenuInteraction, StringSelectMenuInteraction, UserSelectMenuInteraction, RoleSelectMenuInteraction, MentionableSelectMenuInteraction, ModalSubmitInteraction, Interaction, MessagePayload, MessageReplyOptions, MessageCreateOptions, GatewayIntentBits, ClientOptions, RESTPostAPIContextMenuApplicationCommandsJSONBody, UserContextMenuCommandInteraction, MessageContextMenuCommandInteraction, BaseMessageOptions, InteractionUpdateOptions, ButtonBuilder, ButtonStyle, ComponentEmojiResolvable, ChannelSelectMenuBuilder, MentionableSelectMenuBuilder, TextInputStyle, RoleSelectMenuBuilder, StringSelectMenuBuilder, SelectMenuComponentOptionData, UserSelectMenuBuilder, ChannelType, MessageActionRowComponentBuilder, ActionRowBuilder } from 'discord.js';
+import { APIEmbedField, APIEmbedFooter, APIEmbedAuthor, EmbedBuilder, Client, Channel, Guild, GuildMember, MessageManager, Message, Role, User, APIInteractionGuildMember, Awaitable, PermissionResolvable, GuildBasedChannel, PermissionsString, RESTJSONErrorCodes, DiscordAPIError, HTTPError, MessageComponentInteraction, ComponentType, ModalSubmitInteraction, JSONEncodable, APIModalInteractionResponseCallbackData, ModalComponentData, ModalBuilder, TextBasedChannel, PartialGroupDMChannel, ChatInputCommandInteraction, UserContextMenuCommandInteraction, MessageContextMenuCommandInteraction, RepliableInteraction, InteractionReplyOptions, InteractionResponse, PermissionsBitField, APIApplicationCommandChannelOption, CommandInteractionOption, Attachment, ApplicationCommandOptionType, LocalizationMap, APIApplicationCommandBasicOption, AutocompleteInteraction, RESTPostAPIChatInputApplicationCommandsJSONBody, RESTPostAPIApplicationCommandsJSONBody, REST, RESTPutAPIApplicationCommandsResult, RESTPutAPIApplicationGuildCommandsResult, ClientEvents, ButtonInteraction, ChannelSelectMenuInteraction, StringSelectMenuInteraction, UserSelectMenuInteraction, RoleSelectMenuInteraction, MentionableSelectMenuInteraction, Interaction, MessagePayload, MessageReplyOptions, MessageCreateOptions, GatewayIntentBits, ClientOptions, RESTPostAPIContextMenuApplicationCommandsJSONBody, BaseMessageOptions, InteractionUpdateOptions, ButtonBuilder, ButtonStyle, ComponentEmojiResolvable, ChannelSelectMenuBuilder, MentionableSelectMenuBuilder, TextInputStyle, RoleSelectMenuBuilder, StringSelectMenuBuilder, SelectMenuComponentOptionData, UserSelectMenuBuilder, ChannelType, MessageActionRowComponentBuilder, ActionRowBuilder } from 'discord.js';
 export * from 'discord.js';
 
 /**
@@ -255,6 +255,34 @@ declare function parseDuration(input: string): number | null;
 declare function discordTimestamp(date: Date | number, style?: DiscordTimestampStyle): string;
 /** Short-hand for the relative Discord timestamp (`R` style). */
 declare function relativeTimestamp(date: Date | number): string;
+/** The hard cap Discord enforces on a single message's `content`. */
+declare const MESSAGE_CHARACTER_LIMIT = 2000;
+/**
+ * Truncate `text` to at most `max` characters, appending `suffix` (default `…`)
+ * when it had to cut. The result — suffix included — never exceeds `max`.
+ *
+ * @example
+ * ```ts
+ * truncate("a very long reason", 10); // → "a very lo…"
+ * ```
+ */
+declare function truncate(text: string, max: number, suffix?: string): string;
+/** Options for {@link chunkMessage}. */
+interface ChunkOptions {
+    /** Maximum characters per chunk. Default {@link MESSAGE_CHARACTER_LIMIT} (2000). */
+    max?: number;
+}
+/**
+ * Split `text` into chunks that each fit within Discord's per-message limit,
+ * breaking on line boundaries (and word boundaries for over-long lines) so you
+ * never silently lose the tail of a long reply.
+ *
+ * @example
+ * ```ts
+ * for (const part of chunkMessage(hugeLog)) await ctx.followUp(part);
+ * ```
+ */
+declare function chunkMessage(text: string, options?: ChunkOptions): string[];
 
 /**
  * Pluggable cache abstraction with TTL, counters and rate-limit primitives.
@@ -348,6 +376,96 @@ declare function lookup<K extends string, V>(table: Readonly<Record<K, V>>, reso
 /** Build a non-throwing lookup that returns `undefined` for missing keys. */
 declare function lookupOptional<K extends string, V>(table: Readonly<Record<K, V>>): (key: K) => V | undefined;
 
+/**
+ * A minimal async key-value store. Values must be JSON-serialisable. All
+ * backends share these semantics so you can develop against {@link MemoryStore}
+ * and ship with {@link JsonStore} (or your own) without code changes.
+ */
+interface KeyValueStore {
+    /** Resolve the value for `key`, or `undefined` if absent. */
+    get<T>(key: string): Promise<T | undefined>;
+    /** Store `value` under `key`, overwriting any previous value. */
+    set<T>(key: string, value: T): Promise<void>;
+    /** Whether `key` currently has a value. */
+    has(key: string): Promise<boolean>;
+    /** Remove `key`. Resolves `true` if it existed. */
+    delete(key: string): Promise<boolean>;
+    /** Every key currently stored. */
+    keys(): Promise<string[]>;
+    /** Remove every key. */
+    clear(): Promise<void>;
+}
+/**
+ * In-memory {@link KeyValueStore}. Values are deep-cloned on read and write so
+ * callers can't accidentally mutate stored state — matching what a persistent
+ * backend would do. Ideal for tests and ephemeral data.
+ */
+declare class MemoryStore implements KeyValueStore {
+    private readonly map;
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T): Promise<void>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    keys(): Promise<string[]>;
+    clear(): Promise<void>;
+}
+/**
+ * File-backed {@link KeyValueStore} persisting the whole map as one JSON object.
+ * Reads are served from an in-memory cache (loaded once, lazily); writes are
+ * serialised through a queue and committed atomically (temp file + rename) so a
+ * crash mid-write can never corrupt the file.
+ */
+declare class JsonStore implements KeyValueStore {
+    private readonly path;
+    private readonly cache;
+    private loading?;
+    private writeChain;
+    constructor(path: string);
+    private ensureLoaded;
+    private load;
+    /** Queue an atomic write of the current cache; serialised against prior writes. */
+    private persist;
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T): Promise<void>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    keys(): Promise<string[]>;
+    clear(): Promise<void>;
+}
+/**
+ * Wrap a store so every key is transparently prefixed with `${prefix}:`. Lets
+ * several features share one backing file without key collisions.
+ */
+declare function namespaced(store: KeyValueStore, prefix: string): KeyValueStore;
+/** A typed settings accessor returned by {@link createSettings}. */
+interface SettingsManager<T extends Record<string, unknown>> {
+    /** The defaults merged into every {@link get}. */
+    readonly defaults: T;
+    /** The underlying store. */
+    readonly store: KeyValueStore;
+    /** Read `id`'s settings, always fully populated from {@link defaults}. */
+    get(id: string): Promise<T>;
+    /** Shallow-merge `patch` into `id`'s stored settings and persist; returns the merged result. */
+    set(id: string, patch: Partial<T>): Promise<T>;
+    /** Restore `id` to defaults by removing its stored overrides. */
+    reset(id: string): Promise<void>;
+}
+/** Options for {@link createSettings}. */
+interface CreateSettingsOptions<T extends Record<string, unknown>> {
+    /** Backing store (e.g. `new JsonStore(path)`). */
+    store: KeyValueStore;
+    /** Default values applied to ids with no (or partial) stored settings. */
+    defaults: T;
+    /** Key prefix; lets one store hold several settings groups. Default `"settings"`. */
+    namespace?: string;
+}
+/**
+ * Build a typed, defaults-merged settings accessor over a {@link KeyValueStore}.
+ * `get` always returns a complete object (stored overrides on top of defaults),
+ * and `set` only persists the overrides — so widening `defaults` later is safe.
+ */
+declare function createSettings<T extends Record<string, unknown>>(options: CreateSettingsOptions<T>): SettingsManager<T>;
+
 /**
  * Declarative preconditions ("guards") that run before a command, component
  * or prefix-command handler. Replaces the role/permission/guild-only/owner
@@ -408,6 +526,345 @@ declare function requireBotPermissions(permission: PermissionResolvable, reason?
 /** Inline custom predicate; sugar so a one-off check still types as a Guard. */
 declare function guard<TCtx extends GuardContext = GuardContext>(predicate: Guard<TCtx>): Guard<TCtx>;
 
+/**
+ * Permission and role-hierarchy preflight helpers for moderation-style actions.
+ *
+ * Two failures dominate moderation bots: doing work and *then* hitting a
+ * `Missing Permissions` (50013) error, and trying to ban/kick/timeout a member
+ * who is above the bot (or above the moderator) in the role list. Both are
+ * checkable up front. These helpers compute exactly what's missing so you can
+ * bail out with a clear message before touching the API.
+ *
+ * @example
+ * ```ts
+ * const missing = botMissingPermissions(ctx.channel, [PermissionFlagsBits.ManageMessages]);
+ * if (missing.length) return ctx.error(`I need: ${formatPermissions(missing)}`);
+ *
+ * const check = moderationCheck({ moderator: ctx.member, target, action: "ban" });
+ * if (!check.ok) return ctx.error(check.reason);
+ * await target.ban();
+ * ```
+ */
+
+/** A member or role whose permissions are being resolved in a channel. */
+type PermissionHolder = GuildMember | Role;
+/**
+ * Return the names of the `required` permissions that `who` does NOT have in
+ * `channel` (taking channel overwrites and Administrator into account). An empty
+ * array means every required permission is granted. When permissions can't be
+ * resolved (e.g. the member isn't cached) every required permission is reported
+ * missing.
+ */
+declare function missingPermissions(channel: GuildBasedChannel, who: PermissionHolder, required: PermissionResolvable): PermissionsString[];
+/**
+ * Like {@link missingPermissions} but for the bot's own member in `channel`.
+ * Resolves `channel.guild.members.me`; if that isn't available, every required
+ * permission is reported missing.
+ */
+declare function botMissingPermissions(channel: GuildBasedChannel, required: PermissionResolvable): PermissionsString[];
+/** Whether `who` has all of `required` in `channel`. */
+declare function hasPermissions(channel: GuildBasedChannel, who: PermissionHolder, required: PermissionResolvable): boolean;
+/**
+ * Compare two members by their highest role position. Returns a positive number
+ * when `a` is above `b`, negative when below, `0` when equal. This is the raw
+ * comparison Discord enforces for moderation actions.
+ */
+declare function compareRoles(a: GuildMember, b: GuildMember): number;
+/**
+ * Whether `actor` outranks `target` enough to act on them: not the same member,
+ * `target` isn't the guild owner, and `actor` is either the owner or holds a
+ * higher top role.
+ */
+declare function canActOn(actor: GuildMember, target: GuildMember): boolean;
+/** The result of a {@link moderationCheck}: pass, or fail with a reason. */
+type ModerationCheckResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Options for {@link moderationCheck}. */
+interface ModerationCheckOptions {
+    /** The member attempting the action. */
+    moderator: GuildMember;
+    /** The member the action targets. */
+    target: GuildMember;
+    /**
+     * The bot's own member. Defaults to `target.guild.members.me`. Pass `null` to
+     * skip the bot-hierarchy check (e.g. when the action doesn't need it).
+     */
+    me?: GuildMember | null;
+    /** Verb used in the failure messages, e.g. `"ban"`. Default `"moderate"`. */
+    action?: string;
+}
+/**
+ * Validate that both the moderator and the bot may act on `target`, returning a
+ * ready-to-show reason on the first failing rule. Checks, in order: acting on
+ * self, acting on the server owner, moderator role hierarchy, and bot role
+ * hierarchy.
+ */
+declare function moderationCheck(options: ModerationCheckOptions): ModerationCheckResult;
+/**
+ * Render permission flag names into a human, comma-separated string. Accepts a
+ * {@link PermissionsString} array (the output of {@link missingPermissions}) or
+ * anything {@link PermissionResolvable}.
+ *
+ * @example
+ * ```ts
+ * formatPermissions(botMissingPermissions(ctx.channel, [PermissionFlagsBits.BanMembers]));
+ * // → "Ban Members"
+ * ```
+ */
+declare function formatPermissions(permissions: PermissionResolvable): string;
+
+/**
+ * Discord API error helpers — turn opaque `DiscordAPIError` throws into
+ * something you can branch on and show to users.
+ *
+ * discord.js surfaces REST failures as {@link DiscordAPIError} with a numeric
+ * `code` (e.g. `10062` "Unknown interaction", `50013` "Missing permissions").
+ * Memorising those numbers is a chore, and `try/catch` blocks that re-throw
+ * everything turn small, recoverable failures (a deleted message, a closed DM)
+ * into crashes or scary stack traces. This module gives you named codes, a
+ * type-narrowing predicate, and a friendly, end-user-appropriate explanation.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await message.delete();
+ * } catch (err) {
+ *   if (isDiscordError(err, DiscordErrorCode.UnknownMessage)) return; // already gone
+ *   throw err;
+ * }
+ * ```
+ */
+
+/**
+ * The Discord JSON error codes spearkit cares about most, by readable name.
+ * This is a curated subset of discord.js' {@link RESTJSONErrorCodes} covering
+ * the failures bots actually hit and can recover from. Values are the numeric
+ * codes Discord returns on `DiscordAPIError.code`.
+ */
+declare const DiscordErrorCode: {
+    /** A referenced channel no longer exists or is invisible to the bot. */
+    readonly UnknownChannel: RESTJSONErrorCodes.UnknownChannel;
+    /** The targeted guild is gone or the bot was removed from it. */
+    readonly UnknownGuild: RESTJSONErrorCodes.UnknownGuild;
+    /** The referenced member is not in the guild. */
+    readonly UnknownMember: RESTJSONErrorCodes.UnknownMember;
+    /** The message was deleted (or never existed) before the action ran. */
+    readonly UnknownMessage: RESTJSONErrorCodes.UnknownMessage;
+    /** The user could not be resolved. */
+    readonly UnknownUser: RESTJSONErrorCodes.UnknownUser;
+    /** The interaction token expired (the classic 3-second-window failure). */
+    readonly UnknownInteraction: RESTJSONErrorCodes.UnknownInteraction;
+    /** The bot lacks access to the resource entirely (not just one permission). */
+    readonly MissingAccess: RESTJSONErrorCodes.MissingAccess;
+    /** Action attempted on a DM channel that does not support it. */
+    readonly CannotExecuteActionOnDMChannel: RESTJSONErrorCodes.CannotExecuteActionOnDMChannel;
+    /** The target user has DMs closed or blocked the bot. */
+    readonly CannotSendMessagesToThisUser: RESTJSONErrorCodes.CannotSendMessagesToThisUser;
+    /** The bot is missing one or more permissions required for the action. */
+    readonly MissingPermissions: RESTJSONErrorCodes.MissingPermissions;
+    /** The request body failed Discord's validation. */
+    readonly InvalidFormBodyOrContentType: RESTJSONErrorCodes.InvalidFormBodyOrContentType;
+    /** The interaction was already acknowledged elsewhere. */
+    readonly InteractionHasAlreadyBeenAcknowledged: RESTJSONErrorCodes.InteractionHasAlreadyBeenAcknowledged;
+    /** The bot reached the maximum number of guilds it may join. */
+    readonly MaximumNumberOfGuildsReached: RESTJSONErrorCodes.MaximumNumberOfGuildsReached;
+    /** Too many active reactions / pins / etc. of this kind. */
+    readonly MaximumNumberOfReactionsReached: RESTJSONErrorCodes.MaximumNumberOfReactionsReached;
+};
+/** A numeric Discord JSON error code value. */
+type DiscordErrorCodeValue = (typeof DiscordErrorCode)[keyof typeof DiscordErrorCode];
+/**
+ * Narrow an unknown thrown value to a {@link DiscordAPIError}. Pass a `code`
+ * (or several) to also assert the specific failure — ideal for "ignore this
+ * one error, re-throw the rest" recovery.
+ *
+ * @example
+ * ```ts
+ * if (isDiscordError(err, [DiscordErrorCode.UnknownMessage, DiscordErrorCode.UnknownChannel])) return;
+ * ```
+ */
+declare function isDiscordError(error: unknown, code?: number | string | readonly (number | string)[]): error is DiscordAPIError;
+/**
+ * Narrow to a transport-level {@link HTTPError} (timeouts, 5xx, aborted
+ * requests) — failures with an HTTP status but no Discord JSON code.
+ */
+declare function isHTTPError(error: unknown): error is HTTPError;
+/** Whether the thrown value is a Discord rate-limit (HTTP 429) response. */
+declare function isRateLimitError(error: unknown): boolean;
+/**
+ * Render an end-user-appropriate sentence for a Discord error, or `null` if the
+ * error isn't a recognised, explainable Discord failure (in which case you
+ * should fall back to a generic "something went wrong" message and log it).
+ *
+ * @example
+ * ```ts
+ * catch (err) { await ctx.error(explainDiscordError(err) ?? "Something went wrong."); }
+ * ```
+ */
+declare function explainDiscordError(error: unknown): string | null;
+
+/**
+ * Graceful shutdown — close the bot cleanly on `SIGINT`/`SIGTERM`.
+ *
+ * A `Ctrl-C` or a container stop sends a signal; if you don't handle it the
+ * process dies mid-flight, leaving the gateway connection, scheduler timers and
+ * any open handles to be reaped abruptly. {@link gracefulShutdown} runs an
+ * optional hook, calls `client.destroy()` (which also stops spearkit's
+ * scheduler), and exits — with a hard timeout so a wedged shutdown can't hang
+ * forever.
+ *
+ * @example
+ * ```ts
+ * gracefulShutdown(client, { onShutdown: () => db.close() });
+ * // or, on a SpearClient:
+ * client.enableGracefulShutdown({ onShutdown: () => db.close() });
+ * ```
+ */
+
+/** Anything with an async-or-sync `destroy()` — a discord.js `Client` qualifies. */
+interface Destroyable {
+    destroy(): Awaitable<void>;
+}
+/** Minimal logger shape used for shutdown progress (your `client.logger` fits). */
+interface ShutdownLogger {
+    info?(message: string): void;
+    error?(message: string, meta?: unknown): void;
+}
+/** Options for {@link gracefulShutdown}. */
+interface GracefulShutdownOptions {
+    /** Signals to listen for. Default `["SIGINT", "SIGTERM"]`. */
+    signals?: readonly NodeJS.Signals[];
+    /** Force-exit if shutdown takes longer than this many ms. Default `10000`. */
+    timeoutMs?: number;
+    /** Call `process.exit()` when done. Default `true`. Set `false` in tests. */
+    exit?: boolean;
+    /** Runs before `client.destroy()` — flush databases, close connections, etc. */
+    onShutdown?: (signal: NodeJS.Signals) => Awaitable<void>;
+    /** Optional progress logger. */
+    logger?: ShutdownLogger;
+}
+/**
+ * Wire signal handlers that gracefully tear `client` down once, then exit.
+ * Returns a disposer that removes the handlers (handy for tests/hot-reload).
+ */
+declare function gracefulShutdown(client: Destroyable, options?: GracefulShutdownOptions): () => void;
+
+/**
+ * Collector ergonomics — wait for a reply, a click, or a modal without the
+ * boilerplate (and footguns) of raw discord.js collectors.
+ *
+ * discord.js collectors are powerful but fiddly: you wire an event emitter, set
+ * a `time`, write a `filter`, remember that modal submissions can be dismissed
+ * (so they need their own timeout), and translate the "timed out" rejection into
+ * something your code can branch on. These helpers collapse the common cases to
+ * a single `await` that resolves to the result — or `null` on timeout.
+ *
+ * @example
+ * ```ts
+ * await ctx.reply("What's your favourite colour?");
+ * const reply = await ctx.awaitMessageFrom();          // same user, same channel
+ * if (reply === null) return ctx.followUp("Timed out.");
+ * await ctx.followUp(`Nice — ${reply.content}!`);
+ * ```
+ */
+
+/** Options for {@link awaitMessage}. */
+interface AwaitMessageOptions {
+    /** Only accept messages passing this predicate. */
+    filter?: (message: Message) => boolean;
+    /** How long to wait, in ms. Default `60000`. */
+    time?: number;
+}
+/**
+ * A text-based channel that can collect messages — every {@link TextBasedChannel}
+ * except `PartialGroupDMChannel` (which has no message manager).
+ */
+type CollectableChannel = Exclude<TextBasedChannel, PartialGroupDMChannel>;
+/**
+ * Wait for the next message in `channel` that matches `filter`, resolving to the
+ * `Message` or `null` if none arrives before `time` elapses.
+ */
+declare function awaitMessage(channel: CollectableChannel, options?: AwaitMessageOptions): Promise<Message | null>;
+/** Options for {@link awaitComponent}. */
+interface AwaitComponentOptions {
+    /** Only accept interactions passing this predicate. */
+    filter?: (interaction: MessageComponentInteraction) => boolean;
+    /** How long to wait, in ms. Default `60000`. */
+    time?: number;
+    /** Restrict to one component kind (e.g. `ComponentType.Button`). */
+    componentType?: ComponentType;
+}
+/**
+ * Wait for the next component interaction (button/select click) on `message`,
+ * resolving to it or `null` on timeout. Note: you must still acknowledge the
+ * returned interaction (`update`/`deferUpdate`/`reply`).
+ */
+declare function awaitComponent(message: Message, options?: AwaitComponentOptions): Promise<MessageComponentInteraction | null>;
+/** A modal in any of the forms discord.js' `showModal` accepts. */
+type ModalLike = JSONEncodable<APIModalInteractionResponseCallbackData> | ModalComponentData | ModalBuilder;
+/** Interactions that can open a modal and await its submission. */
+type ModalShowingInteraction = ChatInputCommandInteraction | MessageComponentInteraction | UserContextMenuCommandInteraction | MessageContextMenuCommandInteraction;
+/** Options for {@link showAndAwaitModal}. */
+interface AwaitModalOptions {
+    /** How long to wait for submission, in ms. Default `120000`. */
+    time?: number;
+    /** Extra predicate on the submitted modal (already scoped to this user + modal). */
+    filter?: (interaction: ModalSubmitInteraction) => boolean;
+}
+/**
+ * Show `modal` on `interaction`, then wait for its submission — scoped to the
+ * same user and the modal's own custom-id — resolving to the
+ * {@link ModalSubmitInteraction} or `null` if the user dismisses it / it times
+ * out. Sidesteps the "Unknown interaction after cancelling a modal" trap by
+ * always bounding the wait.
+ */
+declare function showAndAwaitModal(interaction: ModalShowingInteraction, modal: ModalLike, options?: AwaitModalOptions): Promise<ModalSubmitInteraction | null>;
+
+/**
+ * Auto-defer — the antidote to `DiscordAPIError[10062]: Unknown interaction`.
+ *
+ * An interaction token is only valid for 3 seconds before the *first* response.
+ * Any handler that awaits a database query, an HTTP call, or anything else slow
+ * blows past that window and the interaction dies. The fix is always the same:
+ * `deferReply()` early. Auto-defer does it for you — it arms a timer when the
+ * handler starts and, if the handler hasn't responded in time, defers
+ * automatically. Cancelled the instant your handler replies/defers itself.
+ *
+ * Enable per command (`command({ autoDefer: true })`) or globally
+ * (`new SpearClient({ autoDefer: true })`). With it on, respond via
+ * `ctx.send(...)` / `ctx.editReply(...)` rather than `ctx.reply(...)`, since the
+ * reply slot may already be taken by the auto-defer.
+ */
+
+/** How a handler opts into auto-defer: `true` for defaults, or fine-tuning. */
+type AutoDeferInput = boolean | {
+    ephemeral?: boolean;
+    delayMs?: number;
+};
+/** Resolved auto-defer settings. */
+interface AutoDeferConfig {
+    /** Defer as an ephemeral ("thinking…" hidden) response. */
+    ephemeral: boolean;
+    /** Delay before the safety defer fires, in ms. Kept under Discord's 3s window. */
+    delayMs: number;
+}
+/** Default safety margin: defer at 2s, leaving headroom before the 3s cutoff. */
+declare const DEFAULT_AUTO_DEFER_DELAY_MS = 2000;
+/** Normalise an {@link AutoDeferInput} (or `undefined`) into a config, or `undefined` when disabled. */
+declare function normalizeAutoDefer(input: AutoDeferInput | undefined): AutoDeferConfig | undefined;
+/** Interactions auto-defer supports (those answered with `deferReply`). */
+type AutoDeferrableInteraction = ChatInputCommandInteraction | UserContextMenuCommandInteraction | MessageContextMenuCommandInteraction;
+/**
+ * Arm a one-shot timer that calls `deferReply()` if the interaction is still
+ * un-acknowledged when it fires. Returns a cancel function — always call it
+ * once your handler settles (e.g. in a `finally`) to disarm the timer.
+ */
+declare function armAutoDefer(interaction: AutoDeferrableInteraction, config: AutoDeferConfig): () => void;
+
 /** Reply options with an ergonomic `ephemeral` shortcut (mapped to flags). */
 type ReplyData = InteractionReplyOptions & {
     ephemeral?: boolean;
@@ -456,6 +913,22 @@ declare abstract class BaseContext<I extends RepliableInteraction = RepliableInt
      * most handlers ever need.
      */
     send(input: ReplyInput): Promise<void>;
+    /** The bot's resolved permissions in the current channel. */
+    get botPermissions(): Readonly<PermissionsBitField>;
+    /**
+     * Permission flag names the BOT is missing in the current channel — empty when
+     * it has them all. Zero-fetch: reads the permissions Discord attached to the
+     * interaction. Use before an action that needs elevated permissions.
+     */
+    botMissing(required: PermissionResolvable): PermissionsString[];
+    /** Permission flag names the invoking USER is missing in the current channel. */
+    userMissing(required: PermissionResolvable): PermissionsString[];
+    /**
+     * Wait for the next message in this channel from `userId` (defaults to the
+     * invoking user), resolving to it or `null` on timeout. The "type your answer"
+     * flow without hand-rolling a collector.
+     */
+    awaitMessageFrom(userId?: string, options?: AwaitMessageOptions): Promise<Message | null>;
     /** Get the configured {@link Embeds} factory — `client.embeds` or the default. */
     protected getEmbeds(): Embeds;
     /** State-aware send of a red error embed. Defaults to ephemeral. */
@@ -801,6 +1274,11 @@ declare class CommandContext<O extends OptionMap = OptionMap> extends BaseContex
     get subcommand(): string | null;
     /** Present a modal to the user in response to this command. */
     showModal(modal: JSONEncodable<APIModalInteractionResponseCallbackData> | ModalComponentData | ModalBuilder): Promise<void>;
+    /**
+     * Show a modal and wait for the user to submit it, resolving to the submission
+     * or `null` if they dismiss it / it times out. Scoped to this user and modal.
+     */
+    awaitModal(modal: ModalLike, options?: AwaitModalOptions): Promise<ModalSubmitInteraction | null>;
 }
 /**
  * The handler argument for autocomplete requests. Provides the focused value
@@ -836,6 +1314,12 @@ interface CommonMeta {
     cooldown?: CooldownInput;
     /** Preconditions evaluated before the handler runs. */
     guards?: readonly Guard[];
+    /**
+     * Auto-`deferReply()` if the handler hasn't responded within ~2s, preventing
+     * `Unknown interaction` (10062) on slow work. `true` for defaults, or
+     * `{ ephemeral, delayMs }`. With it on, respond via `ctx.send`/`ctx.editReply`.
+     */
+    autoDefer?: AutoDeferInput;
 }
 /** Configuration for a leaf (non-subcommand) slash command. */
 interface CommandConfig<O extends OptionMap, R> extends CommonMeta {
@@ -890,6 +1374,7 @@ interface SlashCommandSpec {
     autocompleter: (interaction: AutocompleteInteraction) => Promise<void>;
     cooldown?: CooldownConfig;
     guards?: readonly Guard[];
+    autoDefer?: AutoDeferConfig;
 }
 /**
  * A registered slash command. Serialises itself for the discord REST API and
@@ -908,6 +1393,8 @@ declare class SlashCommand {
     readonly cooldown?: CooldownConfig;
     /** Resolved guard list for this command, if any. */
     readonly guards?: readonly Guard[];
+    /** Resolved auto-defer configuration for this command, if any. */
+    readonly autoDefer?: AutoDeferConfig;
     /** @internal */
     constructor(spec: SlashCommandSpec);
     /** Serialise to the discord REST chat-input command payload. */
@@ -962,6 +1449,7 @@ declare class CommandRegistry {
     private defaultCooldown?;
     private defaultGuards;
     private onUsage?;
+    private defaultAutoDefer?;
     /** Register one or more commands. Later registrations override by name. */
     add(...commands: SlashCommand[]): this;
     /** Remove a command by name. */
@@ -982,6 +1470,8 @@ declare class CommandRegistry {
     setCooldowns(manager: CooldownManager, defaultCooldown?: CooldownConfig): this;
     /** Guards that run before every command's own guards. */
     setDefaultGuards(guards: readonly Guard[]): this;
+    /** Default auto-defer applied to commands that don't set their own. */
+    setAutoDefer(config?: AutoDeferConfig): this;
     /** Attach a hook called after each successful command execution. */
     setUsageHook(hook: (event: UsageEvent) => void): this;
     /** Serialise every command to discord REST payloads. */
@@ -1440,6 +1930,13 @@ interface PrefixOptions {
     ignoreBots?: boolean;
     /** Match command names case-insensitively. Default `true`. */
     caseInsensitive?: boolean;
+    /**
+     * Resolve extra prefix(es) per message — e.g. a custom per-guild prefix from a
+     * database or {@link createSettings}. Returned prefixes are tried in addition
+     * to any static `prefix`. Return `null`/`undefined` for none. Keep it fast
+     * (and cached): it runs on every candidate message.
+     */
+    dynamic?: (message: Message) => Awaitable<string | readonly string[] | null | undefined>;
 }
 /** Configuration for a prefix command. */
 interface PrefixCommandConfig<TArgs extends Record<string, unknown> = Record<string, never>, R = void> {
@@ -1542,6 +2039,8 @@ declare class PrefixRegistry {
     list(): PrefixCommand[];
     /** Strip a matching prefix (or bot mention) from `content`, or return `null`. */
     private stripPrefix;
+    /** Resolve the effective prefixes for a message: static plus any dynamic ones. */
+    private resolvePrefixes;
     /**
      * Parse and dispatch a message. Returns `true` when a command ran (or was
      * blocked by a cooldown), `false` when the message was not a prefix command.
@@ -1587,6 +2086,12 @@ interface SpearOptions {
     embeds?: Embeds | EmbedsOptions;
     /** Default guards (preconditions) applied before every command/component/prefix handler. */
     guards?: readonly Guard[];
+    /**
+     * Default auto-defer for every slash command and context menu (each handler
+     * may override). Prevents `Unknown interaction` (10062) on slow handlers by
+     * deferring automatically just before Discord's 3-second window closes.
+     */
+    autoDefer?: AutoDeferInput;
 }
 /** Options for {@link SpearClient}: discord.js options plus {@link SpearOptions}. `intents` may be omitted. */
 type SpearClientOptions = Partial<ClientOptions> & SpearOptions;
@@ -1679,6 +2184,12 @@ declare class SpearClient extends Client {
     schedule(config: TaskConfig): ScheduledTask;
     /** Stop the scheduler, then tear down the discord.js client. */
     destroy(): Promise<void>;
+    /**
+     * Close the bot cleanly on `SIGINT`/`SIGTERM`: run an optional hook, then
+     * `destroy()` (stopping the scheduler and gateway), then exit. Returns a
+     * disposer that removes the signal handlers. Logs progress via `client.logger`.
+     */
+    enableGracefulShutdown(options?: GracefulShutdownOptions): () => void;
     private route;
 }
 
@@ -1784,6 +2295,8 @@ interface ContextMenuMeta {
     nameLocalizations?: LocalizationMap;
     cooldown?: CooldownInput;
     guards?: readonly Guard[];
+    /** Auto-`deferReply()` if the handler is slow, preventing `Unknown interaction`. */
+    autoDefer?: AutoDeferInput;
 }
 /** Configuration for {@link userCommand}. */
 interface UserCommandConfig<R = void> extends ContextMenuMeta {
@@ -1800,6 +2313,7 @@ interface BaseContextMenuCommand {
     readonly name: string;
     readonly cooldown?: CooldownConfig;
     readonly guards?: readonly Guard[];
+    readonly autoDefer?: AutoDeferConfig;
     toJSON(): RESTPostAPIContextMenuApplicationCommandsJSONBody;
 }
 /** A user-target context-menu command. */
@@ -1839,6 +2353,7 @@ declare class ContextMenuRegistry {
     private defaultCooldown?;
     private defaultGuards;
     private onUsage?;
+    private defaultAutoDefer?;
     /** Register one or more context-menu commands. */
     add(...commands: readonly ContextMenuCommand[]): this;
     /** Total number of registered context-menu commands. */
@@ -1850,6 +2365,8 @@ declare class ContextMenuRegistry {
     setLogger(logger: Logger): this;
     setCooldowns(manager: CooldownManager, defaultCooldown?: CooldownConfig): this;
     setDefaultGuards(guards: readonly Guard[]): this;
+    /** Default auto-defer applied to menus that don't set their own. */
+    setAutoDefer(config?: AutoDeferConfig): this;
     setUsageHook(hook: (event: UsageEvent) => void): this;
     /** Dispatch a user-target interaction. */
     handleUser(interaction: UserContextMenuCommandInteraction): Promise<void>;
@@ -2041,6 +2558,11 @@ declare class MessageComponentContext<P, I extends AnyComponentInteraction = Any
     deferUpdate(): Promise<void>;
     /** Open a modal in response to this component. */
     showModal(modal: JSONEncodable<APIModalInteractionResponseCallbackData> | ModalComponentData | ModalBuilder): Promise<void>;
+    /**
+     * Show a modal and wait for the user to submit it, resolving to the submission
+     * or `null` if they dismiss it / it times out. Scoped to this user and modal.
+     */
+    awaitModal(modal: ModalLike, options?: AwaitModalOptions): Promise<ModalSubmitInteraction | null>;
 }
 /** Context for a button click. */
 declare class ButtonContext<P = Record<string, never>> extends MessageComponentContext<P, ButtonInteraction> {
@@ -2255,4 +2777,4 @@ declare function modal<const P extends string, F extends Record<string, TextInpu
  */
 declare function row<C extends MessageActionRowComponentBuilder>(...components: C[]): ActionRowBuilder<C>;
 
-export { type AllowedChannelType, type AnyComponentInteraction, type AnyOptionDef, AutocompleteContext, type AutocompleteHandler, BaseContext, type BaseContextMenuCommand, type BuildArgs, type Button, type ButtonConfig, ButtonContext, type ButtonRoute, type ButtonStyleInput, type CacheSetOptions, type CacheStore, type ChannelSelect, ChannelSelectContext, type ChannelSelectRoute, type CommandConfig, CommandContext, type CommandErrorHandler, type CommandGroupConfig, CommandRegistry, type CompiledPattern, type ComponentDef, type ComponentErrorHandler, ComponentRegistry, type ConfirmButtonOptions, type ConfirmButtonStyle, type ConfirmOptions, type ConfirmResult, type ContextMenuCommand, ContextMenuRegistry, type CooldownActor, type CooldownConfig, type CooldownExemptions, type CooldownInput, CooldownManager, type CooldownOverrides, type CooldownResult, type CooldownScope, CronExpression, DEFAULT_EMBED_COLORS, DEFAULT_EMBED_ICONS, type DeployOptions, type DeployResult, type DiscordTimestampStyle, type EmbedColors, type EmbedIcons, type EmbedLevel, type EmbedPresetInput, Embeds, type EmbedsOptions, type EntitySelectConfig, type EnvReader, type EventConfig, type EventDef, type EventHandler, EventRegistry, type FormatDurationOptions, type Guard, type GuardContext, type GuardResult, Intents, JsonFileUsageStore, KeyedLock, type KeyedLockOptions, type LinkButtonConfig, type LoadConfigOptions, type LoadEnvOptions, type LoadOptions, type LockRelease, type LogEntry, type LogLevel, type LogOptions, type LogSink, type LogThreshold, type LogValue, Logger, type LoggerOptions, MAX_CUSTOM_ID_LENGTH, MemoryCache, MemoryUsageStore, type MentionableSelect, MentionableSelectContext, type MentionableSelectRoute, type MessageCommandConfig, MessageComponentContext, type MessageContextMenu, MessageContextMenuContext, type Modal, type ModalConfig, ModalContext, type ModalRoute, type OptionChoice, type OptionDef, type OptionMap, type OptionValue, type PaginateOptions, type PaginateRender, type ParamNames, type Params, type ParsedCustomId, type ParsedEnv, type PrefixArgError, type PrefixArgSpec, PrefixArgsBuilder, type PrefixArgsOk, type PrefixArgsParser, type PrefixCommand, type PrefixCommandConfig, PrefixContext, type PrefixErrorHandler, type PrefixOptions, PrefixRegistry, type RateLimitResult, type Registerable, type ReplyData, type ReplyInput, type ResolvedOption, type ResolvedOptions, type RoleSelect, RoleSelectContext, type RoleSelectRoute, type RunGuardsResult, type SafeFetchOptions, type ScheduledTask, SlashCommand, SpearClient, type SpearClientOptions, type SpearOptions, type SpearPlugin, type StringSelect, type StringSelectConfig, StringSelectContext, type StringSelectRoute, type Subcommand, type SubcommandConfig, type SubcommandGroup, type SubcommandGroupConfig, type TaskConfig, TaskScheduler, type TextInputDef, type TextInputStyleInput, type UsageEvent, type UsageMetaValue, type UsageOptions, type UsageOutcome, type UsageStore, UsageTracker, type UsageType, type UserCommandConfig, type UserContextMenu, UserContextMenuContext, type UserSelect, UserSelectContext, type UserSelectRoute, asEphemeral, buildCustomId, buildPaginatorPage, button, channelSelect, collectModules, command, commandGroup, compilePattern, confirm, consoleSink, createCache, cron, defaultEmbeds, definePlugin, denied, discordTimestamp, dmOnly, effectiveDuration, env, event, fetchChannel, fetchGuild, fetchMember, fetchMessage, fetchRole, fetchUser, formatCooldownMessage, formatDuration, formatUsage, guard, guildOnly, jsonlSink, linkButton, loadConfig, loadConfigAsync, loadEnv, loadInto, lookup, lookupOptional, mentionableSelect, messageCommand, modal, normalizeCooldown, normalizeReply, option, optionsHaveAutocomplete, paginate, paramsFromValues, parseCustomId, parseDuration, parseEnv, prefixArgs, prefixCommand, readOption, relativeTimestamp, requireAllRoles, requireAnyRole, requireBotPermissions, requireOwner, requireUserPermissions, roleSelect, row, runGuards, safeFetch, safeTry, stringSelect, subcommand, subcommandGroup, task, textInput, toAPIOption, toError, userCommand, userSelect, webhookSink, withSafeTimeout };
+export { type AllowedChannelType, type AnyComponentInteraction, type AnyOptionDef, type AutoDeferConfig, type AutoDeferInput, type AutoDeferrableInteraction, AutocompleteContext, type AutocompleteHandler, type AwaitComponentOptions, type AwaitMessageOptions, type AwaitModalOptions, BaseContext, type BaseContextMenuCommand, type BuildArgs, type Button, type ButtonConfig, ButtonContext, type ButtonRoute, type ButtonStyleInput, type CacheSetOptions, type CacheStore, type ChannelSelect, ChannelSelectContext, type ChannelSelectRoute, type ChunkOptions, type CollectableChannel, type CommandConfig, CommandContext, type CommandErrorHandler, type CommandGroupConfig, CommandRegistry, type CompiledPattern, type ComponentDef, type ComponentErrorHandler, ComponentRegistry, type ConfirmButtonOptions, type ConfirmButtonStyle, type ConfirmOptions, type ConfirmResult, type ContextMenuCommand, ContextMenuRegistry, type CooldownActor, type CooldownConfig, type CooldownExemptions, type CooldownInput, CooldownManager, type CooldownOverrides, type CooldownResult, type CooldownScope, type CreateSettingsOptions, CronExpression, DEFAULT_AUTO_DEFER_DELAY_MS, DEFAULT_EMBED_COLORS, DEFAULT_EMBED_ICONS, type DeployOptions, type DeployResult, type Destroyable, DiscordErrorCode, type DiscordErrorCodeValue, type DiscordTimestampStyle, type EmbedColors, type EmbedIcons, type EmbedLevel, type EmbedPresetInput, Embeds, type EmbedsOptions, type EntitySelectConfig, type EnvReader, type EventConfig, type EventDef, type EventHandler, EventRegistry, type FormatDurationOptions, type GracefulShutdownOptions, type Guard, type GuardContext, type GuardResult, Intents, JsonFileUsageStore, JsonStore, type KeyValueStore, KeyedLock, type KeyedLockOptions, type LinkButtonConfig, type LoadConfigOptions, type LoadEnvOptions, type LoadOptions, type LockRelease, type LogEntry, type LogLevel, type LogOptions, type LogSink, type LogThreshold, type LogValue, Logger, type LoggerOptions, MAX_CUSTOM_ID_LENGTH, MESSAGE_CHARACTER_LIMIT, MemoryCache, MemoryStore, MemoryUsageStore, type MentionableSelect, MentionableSelectContext, type MentionableSelectRoute, type MessageCommandConfig, MessageComponentContext, type MessageContextMenu, MessageContextMenuContext, type Modal, type ModalConfig, ModalContext, type ModalLike, type ModalRoute, type ModalShowingInteraction, type ModerationCheckOptions, type ModerationCheckResult, type OptionChoice, type OptionDef, type OptionMap, type OptionValue, type PaginateOptions, type PaginateRender, type ParamNames, type Params, type ParsedCustomId, type ParsedEnv, type PermissionHolder, type PrefixArgError, type PrefixArgSpec, PrefixArgsBuilder, type PrefixArgsOk, type PrefixArgsParser, type PrefixCommand, type PrefixCommandConfig, PrefixContext, type PrefixErrorHandler, type PrefixOptions, PrefixRegistry, type RateLimitResult, type Registerable, type ReplyData, type ReplyInput, type ResolvedOption, type ResolvedOptions, type RoleSelect, RoleSelectContext, type RoleSelectRoute, type RunGuardsResult, type SafeFetchOptions, type ScheduledTask, type SettingsManager, type ShutdownLogger, SlashCommand, SpearClient, type SpearClientOptions, type SpearOptions, type SpearPlugin, type StringSelect, type StringSelectConfig, StringSelectContext, type StringSelectRoute, type Subcommand, type SubcommandConfig, type SubcommandGroup, type SubcommandGroupConfig, type TaskConfig, TaskScheduler, type TextInputDef, type TextInputStyleInput, type UsageEvent, type UsageMetaValue, type UsageOptions, type UsageOutcome, type UsageStore, UsageTracker, type UsageType, type UserCommandConfig, type UserContextMenu, UserContextMenuContext, type UserSelect, UserSelectContext, type UserSelectRoute, armAutoDefer, asEphemeral, awaitComponent, awaitMessage, botMissingPermissions, buildCustomId, buildPaginatorPage, button, canActOn, channelSelect, chunkMessage, collectModules, command, commandGroup, compareRoles, compilePattern, confirm, consoleSink, createCache, createSettings, cron, defaultEmbeds, definePlugin, denied, discordTimestamp, dmOnly, effectiveDuration, env, event, explainDiscordError, fetchChannel, fetchGuild, fetchMember, fetchMessage, fetchRole, fetchUser, formatCooldownMessage, formatDuration, formatPermissions, formatUsage, gracefulShutdown, guard, guildOnly, hasPermissions, isDiscordError, isHTTPError, isRateLimitError, jsonlSink, linkButton, loadConfig, loadConfigAsync, loadEnv, loadInto, lookup, lookupOptional, mentionableSelect, messageCommand, missingPermissions, modal, moderationCheck, namespaced, normalizeAutoDefer, normalizeCooldown, normalizeReply, option, optionsHaveAutocomplete, paginate, paramsFromValues, parseCustomId, parseDuration, parseEnv, prefixArgs, prefixCommand, readOption, relativeTimestamp, requireAllRoles, requireAnyRole, requireBotPermissions, requireOwner, requireUserPermissions, roleSelect, row, runGuards, safeFetch, safeTry, showAndAwaitModal, stringSelect, subcommand, subcommandGroup, task, textInput, toAPIOption, toError, truncate, userCommand, userSelect, webhookSink, withSafeTimeout };