spearkit 0.3.0 → 0.4.0

package/dist/index.js

@@ -1,8 +1,8 @@
-import { ButtonStyle, GatewayIntentBits, EmbedBuilder, MessageFlags, ApplicationCommandType, ComponentType, ActionRowBuilder, ButtonBuilder, ApplicationCommandOptionType, REST, Routes, StringSelectMenuBuilder, UserSelectMenuBuilder, RoleSelectMenuBuilder, ChannelSelectMenuBuilder, MentionableSelectMenuBuilder, ModalBuilder, Client, PermissionsBitField, InteractionContextType, TextInputStyle, TextInputBuilder } from 'discord.js';
+import { RESTJSONErrorCodes, ButtonStyle, GatewayIntentBits, EmbedBuilder, PermissionsBitField, DiscordAPIError, HTTPError, MessageFlags, ApplicationCommandType, ComponentType, ActionRowBuilder, ButtonBuilder, ApplicationCommandOptionType, REST, Routes, StringSelectMenuBuilder, UserSelectMenuBuilder, RoleSelectMenuBuilder, ChannelSelectMenuBuilder, MentionableSelectMenuBuilder, ModalBuilder, Client, InteractionContextType, TextInputStyle, TextInputBuilder } from 'discord.js';
 export * from 'discord.js';
 import { readFile, readFileSync } from 'fs';
 import { promisify } from 'util';
-import { mkdir, appendFile, readFile as readFile$1, readdir } from 'fs/promises';
+import { readFile as readFile$1, mkdir, writeFile, rename, appendFile, readdir } from 'fs/promises';
 import { dirname, join, extname } from 'path';
 import { pathToFileURL } from 'url';
 
@@ -356,6 +356,58 @@ function discordTimestamp(date, style = "f") {
 function relativeTimestamp(date) {
   return discordTimestamp(date, "R");
 }
+var MESSAGE_CHARACTER_LIMIT = 2e3;
+function truncate(text, max, suffix = "\u2026") {
+  if (max <= 0) return "";
+  if (text.length <= max) return text;
+  if (suffix.length >= max) return suffix.slice(0, max);
+  return text.slice(0, max - suffix.length) + suffix;
+}
+function hardSplit(text, max) {
+  const out = [];
+  let rest = text;
+  while (rest.length > max) {
+    const space = rest.lastIndexOf(" ", max);
+    const cut = space > Math.floor(max / 2) ? space : max;
+    out.push(rest.slice(0, cut));
+    rest = rest.slice(cut).replace(/^ /, "");
+  }
+  if (rest.length > 0) out.push(rest);
+  return out;
+}
+function chunkMessage(text, options = {}) {
+  const max = options.max ?? MESSAGE_CHARACTER_LIMIT;
+  if (max <= 0) throw new RangeError("spearkit: chunkMessage max must be positive");
+  if (text.length === 0) return [];
+  if (text.length <= max) return [text];
+  const chunks = [];
+  let current = "";
+  const flush = () => {
+    if (current.length > 0) {
+      chunks.push(current);
+      current = "";
+    }
+  };
+  for (const line of text.split("\n")) {
+    if (line.length > max) {
+      flush();
+      const pieces = hardSplit(line, max);
+      for (let i = 0; i < pieces.length - 1; i++) chunks.push(pieces[i]);
+      current = pieces[pieces.length - 1];
+      continue;
+    }
+    const candidate = current.length > 0 ? `${current}
+${line}` : line;
+    if (candidate.length > max) {
+      flush();
+      current = line;
+    } else {
+      current = candidate;
+    }
+  }
+  flush();
+  return chunks;
+}
 
 // src/cache.ts
 var MemoryCache = class {
@@ -450,6 +502,130 @@ function lookup(table, resourceName = "key") {
 function lookupOptional(table) {
   return (key) => table[key];
 }
+function clone(value) {
+  if (value === void 0 || value === null) return value;
+  if (typeof structuredClone === "function") return structuredClone(value);
+  return JSON.parse(JSON.stringify(value));
+}
+var MemoryStore = class {
+  map = /* @__PURE__ */ new Map();
+  async get(key) {
+    return this.map.has(key) ? clone(this.map.get(key)) : void 0;
+  }
+  async set(key, value) {
+    this.map.set(key, clone(value));
+  }
+  async has(key) {
+    return this.map.has(key);
+  }
+  async delete(key) {
+    return this.map.delete(key);
+  }
+  async keys() {
+    return [...this.map.keys()];
+  }
+  async clear() {
+    this.map.clear();
+  }
+};
+var JsonStore = class {
+  constructor(path) {
+    this.path = path;
+  }
+  path;
+  cache = /* @__PURE__ */ new Map();
+  loading;
+  writeChain = Promise.resolve();
+  ensureLoaded() {
+    if (this.loading === void 0) this.loading = this.load();
+    return this.loading;
+  }
+  async load() {
+    try {
+      const raw = await readFile$1(this.path, "utf8");
+      const parsed = JSON.parse(raw);
+      for (const [key, value] of Object.entries(parsed)) this.cache.set(key, value);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+  /** Queue an atomic write of the current cache; serialised against prior writes. */
+  persist() {
+    this.writeChain = this.writeChain.then(async () => {
+      const body = JSON.stringify(Object.fromEntries(this.cache), null, 2);
+      await mkdir(dirname(this.path), { recursive: true });
+      const tmp = `${this.path}.${process.pid}.${Date.now()}.tmp`;
+      await writeFile(tmp, body, "utf8");
+      await rename(tmp, this.path);
+    });
+    return this.writeChain;
+  }
+  async get(key) {
+    await this.ensureLoaded();
+    return this.cache.has(key) ? clone(this.cache.get(key)) : void 0;
+  }
+  async set(key, value) {
+    await this.ensureLoaded();
+    this.cache.set(key, clone(value));
+    await this.persist();
+  }
+  async has(key) {
+    await this.ensureLoaded();
+    return this.cache.has(key);
+  }
+  async delete(key) {
+    await this.ensureLoaded();
+    const existed = this.cache.delete(key);
+    if (existed) await this.persist();
+    return existed;
+  }
+  async keys() {
+    await this.ensureLoaded();
+    return [...this.cache.keys()];
+  }
+  async clear() {
+    await this.ensureLoaded();
+    this.cache.clear();
+    await this.persist();
+  }
+};
+function namespaced(store, prefix) {
+  const tag = `${prefix}:`;
+  return {
+    get: (key) => store.get(tag + key),
+    set: (key, value) => store.set(tag + key, value),
+    has: (key) => store.has(tag + key),
+    delete: (key) => store.delete(tag + key),
+    async keys() {
+      return (await store.keys()).filter((k) => k.startsWith(tag)).map((k) => k.slice(tag.length));
+    },
+    async clear() {
+      for (const key of await this.keys()) await store.delete(tag + key);
+    }
+  };
+}
+function createSettings(options) {
+  const { store, defaults } = options;
+  const ns = options.namespace ?? "settings";
+  const keyFor2 = (id) => `${ns}:${id}`;
+  return {
+    defaults,
+    store,
+    async get(id) {
+      const stored = await store.get(keyFor2(id));
+      return { ...defaults, ...stored ?? {} };
+    },
+    async set(id, patch) {
+      const stored = await store.get(keyFor2(id)) ?? {};
+      const merged = { ...stored, ...patch };
+      await store.set(keyFor2(id), merged);
+      return { ...defaults, ...merged };
+    },
+    async reset(id) {
+      await store.delete(keyFor2(id));
+    }
+  };
+}
 function denied(reason) {
   return { allowed: false, reason };
 }
@@ -518,6 +694,278 @@ function requireBotPermissions(permission, reason = "I don't have permission to
 function guard(predicate) {
   return predicate;
 }
+function missingPermissions(channel, who, required) {
+  const held = channel.permissionsFor(who);
+  if (held === null) return new PermissionsBitField(required).toArray();
+  return held.missing(required);
+}
+function botMissingPermissions(channel, required) {
+  const me = channel.guild.members.me;
+  if (me === null) return new PermissionsBitField(required).toArray();
+  return missingPermissions(channel, me, required);
+}
+function hasPermissions(channel, who, required) {
+  return missingPermissions(channel, who, required).length === 0;
+}
+function compareRoles(a, b) {
+  return a.roles.highest.comparePositionTo(b.roles.highest);
+}
+function canActOn(actor, target) {
+  if (actor.id === target.id) return false;
+  if (target.id === target.guild.ownerId) return false;
+  if (actor.id === actor.guild.ownerId) return true;
+  return compareRoles(actor, target) > 0;
+}
+function moderationCheck(options) {
+  const { moderator, target } = options;
+  const action = options.action ?? "moderate";
+  const me = options.me === void 0 ? target.guild.members.me : options.me;
+  const name = target.user.username;
+  if (moderator.id === target.id) return { ok: false, reason: `You can't ${action} yourself.` };
+  if (target.id === target.guild.ownerId) {
+    return { ok: false, reason: `You can't ${action} the server owner.` };
+  }
+  if (moderator.id !== moderator.guild.ownerId && compareRoles(moderator, target) <= 0) {
+    return {
+      ok: false,
+      reason: `You can't ${action} **${name}** \u2014 their highest role is above or equal to yours.`
+    };
+  }
+  if (me !== null) {
+    if (me.id === target.id) return { ok: false, reason: `I can't ${action} myself.` };
+    if (me.id !== me.guild.ownerId && compareRoles(me, target) <= 0) {
+      return {
+        ok: false,
+        reason: `I can't ${action} **${name}** \u2014 move my role above theirs and try again.`
+      };
+    }
+  }
+  return { ok: true };
+}
+var PERMISSION_LABELS = {
+  CreateInstantInvite: "Create Invite",
+  KickMembers: "Kick Members",
+  BanMembers: "Ban Members",
+  Administrator: "Administrator",
+  ManageChannels: "Manage Channels",
+  ManageGuild: "Manage Server",
+  AddReactions: "Add Reactions",
+  ViewAuditLog: "View Audit Log",
+  PrioritySpeaker: "Priority Speaker",
+  Stream: "Video",
+  ViewChannel: "View Channel",
+  SendMessages: "Send Messages",
+  SendTTSMessages: "Send TTS Messages",
+  ManageMessages: "Manage Messages",
+  EmbedLinks: "Embed Links",
+  AttachFiles: "Attach Files",
+  ReadMessageHistory: "Read Message History",
+  MentionEveryone: "Mention Everyone",
+  UseExternalEmojis: "Use External Emojis",
+  ViewGuildInsights: "View Server Insights",
+  Connect: "Connect",
+  Speak: "Speak",
+  MuteMembers: "Mute Members",
+  DeafenMembers: "Deafen Members",
+  MoveMembers: "Move Members",
+  UseVAD: "Use Voice Activity",
+  ChangeNickname: "Change Nickname",
+  ManageNicknames: "Manage Nicknames",
+  ManageRoles: "Manage Roles",
+  ManageWebhooks: "Manage Webhooks",
+  ManageGuildExpressions: "Manage Expressions",
+  UseApplicationCommands: "Use Application Commands",
+  RequestToSpeak: "Request to Speak",
+  ManageEvents: "Manage Events",
+  ManageThreads: "Manage Threads",
+  CreatePublicThreads: "Create Public Threads",
+  CreatePrivateThreads: "Create Private Threads",
+  UseExternalStickers: "Use External Stickers",
+  SendMessagesInThreads: "Send Messages in Threads",
+  UseEmbeddedActivities: "Use Activities",
+  ModerateMembers: "Timeout Members"
+};
+function formatPermissions(permissions) {
+  const names = new PermissionsBitField(permissions).toArray();
+  if (names.length === 0) return "none";
+  return names.map((flag) => PERMISSION_LABELS[flag] ?? flag).join(", ");
+}
+var DiscordErrorCode = {
+  /** A referenced channel no longer exists or is invisible to the bot. */
+  UnknownChannel: RESTJSONErrorCodes.UnknownChannel,
+  // 10003
+  /** The targeted guild is gone or the bot was removed from it. */
+  UnknownGuild: RESTJSONErrorCodes.UnknownGuild,
+  // 10004
+  /** The referenced member is not in the guild. */
+  UnknownMember: RESTJSONErrorCodes.UnknownMember,
+  // 10007
+  /** The message was deleted (or never existed) before the action ran. */
+  UnknownMessage: RESTJSONErrorCodes.UnknownMessage,
+  // 10008
+  /** The user could not be resolved. */
+  UnknownUser: RESTJSONErrorCodes.UnknownUser,
+  // 10013
+  /** The interaction token expired (the classic 3-second-window failure). */
+  UnknownInteraction: RESTJSONErrorCodes.UnknownInteraction,
+  // 10062
+  /** The bot lacks access to the resource entirely (not just one permission). */
+  MissingAccess: RESTJSONErrorCodes.MissingAccess,
+  // 50001
+  /** Action attempted on a DM channel that does not support it. */
+  CannotExecuteActionOnDMChannel: RESTJSONErrorCodes.CannotExecuteActionOnDMChannel,
+  // 50003
+  /** The target user has DMs closed or blocked the bot. */
+  CannotSendMessagesToThisUser: RESTJSONErrorCodes.CannotSendMessagesToThisUser,
+  // 50007
+  /** The bot is missing one or more permissions required for the action. */
+  MissingPermissions: RESTJSONErrorCodes.MissingPermissions,
+  // 50013
+  /** The request body failed Discord's validation. */
+  InvalidFormBodyOrContentType: RESTJSONErrorCodes.InvalidFormBodyOrContentType,
+  // 50035
+  /** The interaction was already acknowledged elsewhere. */
+  InteractionHasAlreadyBeenAcknowledged: RESTJSONErrorCodes.InteractionHasAlreadyBeenAcknowledged,
+  // 40060
+  /** The bot reached the maximum number of guilds it may join. */
+  MaximumNumberOfGuildsReached: RESTJSONErrorCodes.MaximumNumberOfGuildsReached,
+  // 30001
+  /** Too many active reactions / pins / etc. of this kind. */
+  MaximumNumberOfReactionsReached: RESTJSONErrorCodes.MaximumNumberOfReactionsReached
+  // 30010
+};
+function isDiscordError(error, code) {
+  if (!(error instanceof DiscordAPIError)) return false;
+  if (code === void 0) return true;
+  const codes = Array.isArray(code) ? code : [code];
+  return codes.includes(error.code);
+}
+function isHTTPError(error) {
+  return error instanceof HTTPError;
+}
+function isRateLimitError(error) {
+  return error instanceof DiscordAPIError && error.status === 429;
+}
+var FRIENDLY = {
+  [DiscordErrorCode.UnknownChannel]: "That channel no longer exists.",
+  [DiscordErrorCode.UnknownMessage]: "That message no longer exists.",
+  [DiscordErrorCode.UnknownMember]: "That member isn't in this server.",
+  [DiscordErrorCode.UnknownUser]: "I couldn't find that user.",
+  [DiscordErrorCode.UnknownInteraction]: "This took too long and expired \u2014 please run it again.",
+  [DiscordErrorCode.InteractionHasAlreadyBeenAcknowledged]: "This took too long and expired \u2014 please run it again.",
+  [DiscordErrorCode.MissingAccess]: "I don't have access to do that here.",
+  [DiscordErrorCode.CannotSendMessagesToThisUser]: "I can't DM that user \u2014 they may have DMs disabled.",
+  [DiscordErrorCode.CannotExecuteActionOnDMChannel]: "That can't be done in a DM.",
+  [DiscordErrorCode.MissingPermissions]: "I'm missing the permissions needed to do that."
+};
+function explainDiscordError(error) {
+  if (isRateLimitError(error)) {
+    return "I'm being rate-limited right now \u2014 please try again in a moment.";
+  }
+  if (!(error instanceof DiscordAPIError)) return null;
+  if (typeof error.code === "number") {
+    const known = FRIENDLY[error.code];
+    if (known !== void 0) return known;
+  }
+  return null;
+}
+
+// src/shutdown.ts
+function gracefulShutdown(client, options = {}) {
+  const signals = options.signals ?? ["SIGINT", "SIGTERM"];
+  const timeoutMs = options.timeoutMs ?? 1e4;
+  const exit = options.exit ?? true;
+  let shuttingDown = false;
+  const handler = (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    options.logger?.info?.(`received ${signal}, shutting down`);
+    const force = setTimeout(() => {
+      options.logger?.error?.("shutdown timed out \u2014 forcing exit");
+      if (exit) process.exit(1);
+    }, timeoutMs);
+    if (typeof force.unref === "function") force.unref();
+    void (async () => {
+      try {
+        await options.onShutdown?.(signal);
+        await client.destroy();
+        clearTimeout(force);
+        options.logger?.info?.("shutdown complete");
+        if (exit) process.exit(0);
+      } catch (error) {
+        clearTimeout(force);
+        options.logger?.error?.("shutdown failed", error);
+        if (exit) process.exit(1);
+      }
+    })();
+  };
+  for (const signal of signals) process.on(signal, handler);
+  return () => {
+    for (const signal of signals) process.off(signal, handler);
+  };
+}
+
+// src/collectors.ts
+async function awaitMessage(channel, options = {}) {
+  const { filter, time = 6e4 } = options;
+  try {
+    const collected = await channel.awaitMessages({
+      filter,
+      max: 1,
+      time,
+      errors: ["time"]
+    });
+    return collected.first() ?? null;
+  } catch {
+    return null;
+  }
+}
+async function awaitComponent(message, options = {}) {
+  const { filter, time = 6e4, componentType } = options;
+  try {
+    return await message.awaitMessageComponent({
+      time,
+      filter: (interaction) => (componentType === void 0 || interaction.componentType === componentType) && (filter?.(interaction) ?? true)
+    });
+  } catch {
+    return null;
+  }
+}
+function resolveModalCustomId(modal2) {
+  const m = modal2;
+  return m.data?.custom_id ?? m.custom_id ?? m.customId;
+}
+async function showAndAwaitModal(interaction, modal2, options = {}) {
+  const customId = resolveModalCustomId(modal2);
+  await interaction.showModal(modal2);
+  const { time = 12e4, filter } = options;
+  try {
+    return await interaction.awaitModalSubmit({
+      time,
+      filter: (submitted) => submitted.user.id === interaction.user.id && (customId === void 0 || submitted.customId === customId) && (filter?.(submitted) ?? true)
+    });
+  } catch {
+    return null;
+  }
+}
+var DEFAULT_AUTO_DEFER_DELAY_MS = 2e3;
+function normalizeAutoDefer(input) {
+  if (input === void 0 || input === false) return void 0;
+  if (input === true) return { ephemeral: false, delayMs: DEFAULT_AUTO_DEFER_DELAY_MS };
+  return {
+    ephemeral: input.ephemeral ?? false,
+    delayMs: input.delayMs ?? DEFAULT_AUTO_DEFER_DELAY_MS
+  };
+}
+function armAutoDefer(interaction, config) {
+  const timer = setTimeout(() => {
+    if (!interaction.replied && !interaction.deferred) {
+      void interaction.deferReply(config.ephemeral ? { flags: MessageFlags.Ephemeral } : {}).catch(() => void 0);
+    }
+  }, config.delayMs);
+  if (typeof timer.unref === "function") timer.unref();
+  return () => clearTimeout(timer);
+}
 function withEphemeralFlag(flags) {
   if (flags == null) return MessageFlags.Ephemeral;
   if (typeof flags === "number" || typeof flags === "bigint") {
@@ -614,6 +1062,38 @@ var BaseContext = class {
       await this.reply(input);
     }
   }
+  /** The bot's resolved permissions in the current channel. */
+  get botPermissions() {
+    return this.interaction.appPermissions;
+  }
+  /**
+   * 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) {
+    return this.interaction.appPermissions.missing(required);
+  }
+  /** Permission flag names the invoking USER is missing in the current channel. */
+  userMissing(required) {
+    const held = this.interaction.memberPermissions;
+    if (held === null) return new PermissionsBitField(required).toArray();
+    return held.missing(required);
+  }
+  /**
+   * 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 = this.user.id, options = {}) {
+    const channel = this.interaction.channel;
+    if (channel === null || !("awaitMessages" in channel)) return Promise.resolve(null);
+    const extra = options.filter;
+    return awaitMessage(channel, {
+      time: options.time,
+      filter: (message) => message.author.id === userId && (extra?.(message) ?? true)
+    });
+  }
   /** Get the configured {@link Embeds} factory — `client.embeds` or the default. */
   getEmbeds() {
     return this.interaction.client.embeds ?? defaultEmbeds;
@@ -778,6 +1258,7 @@ function userCommand(config) {
     name: config.name,
     cooldown,
     guards: config.guards,
+    autoDefer: normalizeAutoDefer(config.autoDefer),
     toJSON: () => baseJSON(config, ApplicationCommandType.User),
     execute: async (interaction) => {
       await config.run(new UserContextMenuContext(interaction));
@@ -791,6 +1272,7 @@ function messageCommand(config) {
     name: config.name,
     cooldown,
     guards: config.guards,
+    autoDefer: normalizeAutoDefer(config.autoDefer),
     toJSON: () => baseJSON(config, ApplicationCommandType.Message),
     execute: async (interaction) => {
       await config.run(new MessageContextMenuContext(interaction));
@@ -805,6 +1287,7 @@ var ContextMenuRegistry = class {
   defaultCooldown;
   defaultGuards = [];
   onUsage;
+  defaultAutoDefer;
   /** Register one or more context-menu commands. */
   add(...commands) {
     for (const command2 of commands) {
@@ -838,6 +1321,11 @@ var ContextMenuRegistry = class {
     this.defaultGuards = guards;
     return this;
   }
+  /** Default auto-defer applied to menus that don't set their own. */
+  setAutoDefer(config) {
+    this.defaultAutoDefer = config;
+    return this;
+  }
   setUsageHook(hook) {
     this.onUsage = hook;
     return this;
@@ -881,6 +1369,8 @@ var ContextMenuRegistry = class {
         return;
       }
     }
+    const autoDefer = command2.autoDefer ?? this.defaultAutoDefer;
+    const cancelAutoDefer = autoDefer !== void 0 ? armAutoDefer(interaction, autoDefer) : void 0;
     const start = Date.now();
     try {
       if (command2.kind === "userMenu") {
@@ -916,15 +1406,19 @@ var ContextMenuRegistry = class {
         timestamp: /* @__PURE__ */ new Date()
       });
       interaction.client.emit("error", err);
+      const content = explainDiscordError(err) ?? "Something went wrong.";
       try {
-        if (!interaction.replied && !interaction.deferred) {
-          await interaction.reply({
-            content: "Something went wrong.",
-            flags: MessageFlags.Ephemeral
-          });
+        if (interaction.deferred) {
+          await interaction.editReply({ content });
+        } else if (interaction.replied) {
+          await interaction.followUp({ content, flags: MessageFlags.Ephemeral });
+        } else {
+          await interaction.reply({ content, flags: MessageFlags.Ephemeral });
         }
       } catch {
       }
+    } finally {
+      cancelAutoDefer?.();
     }
   }
 };
@@ -1860,7 +2354,8 @@ function resolveOptions(input) {
     prefixes: typeof prefix === "string" ? [prefix] : [...prefix],
     mention: options.mention ?? true,
     ignoreBots: options.ignoreBots ?? true,
-    caseInsensitive: options.caseInsensitive ?? true
+    caseInsensitive: options.caseInsensitive ?? true,
+    dynamic: options.dynamic
   };
 }
 function actorFromMessage(message) {
@@ -1944,8 +2439,8 @@ var PrefixRegistry = class {
     return [...this.commands.values()];
   }
   /** Strip a matching prefix (or bot mention) from `content`, or return `null`. */
-  stripPrefix(content, botId) {
-    for (const prefix of this.options.prefixes) {
+  stripPrefix(content, botId, prefixes) {
+    for (const prefix of prefixes) {
       if (prefix.length > 0 && content.startsWith(prefix)) return content.slice(prefix.length);
     }
     if (this.options.mention && botId !== void 0) {
@@ -1954,14 +2449,24 @@ var PrefixRegistry = class {
     }
     return null;
   }
+  /** Resolve the effective prefixes for a message: static plus any dynamic ones. */
+  async resolvePrefixes(message) {
+    if (this.options.dynamic === void 0) return this.options.prefixes;
+    const extra = await this.options.dynamic(message);
+    if (extra === null || extra === void 0) return this.options.prefixes;
+    const list = typeof extra === "string" ? [extra] : extra;
+    return [...this.options.prefixes, ...list];
+  }
   /**
    * 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.
    */
   async handle(message) {
-    if (this.options.prefixes.length === 0 && !this.options.mention) return false;
+    const hasMatcher = this.options.prefixes.length > 0 || this.options.mention || this.options.dynamic !== void 0;
+    if (!hasMatcher) return false;
     if (this.options.ignoreBots && message.author.bot) return false;
-    const stripped = this.stripPrefix(message.content, message.client.user?.id);
+    const prefixes = await this.resolvePrefixes(message);
+    const stripped = this.stripPrefix(message.content, message.client.user?.id, prefixes);
     if (stripped === null) return false;
     const trimmed = stripped.trimStart();
     const match = /^(\S+)\s*([\s\S]*)$/.exec(trimmed);
@@ -2309,6 +2814,13 @@ var CommandContext = class extends BaseContext {
   async showModal(modal2) {
     await this.interaction.showModal(modal2);
   }
+  /**
+   * 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(modal2, options) {
+    return showAndAwaitModal(this.interaction, modal2, options);
+  }
 };
 var AutocompleteContext = class {
   constructor(interaction) {
@@ -2363,6 +2875,8 @@ var SlashCommand = class {
   cooldown;
   /** Resolved guard list for this command, if any. */
   guards;
+  /** Resolved auto-defer configuration for this command, if any. */
+  autoDefer;
   /** @internal */
   constructor(spec) {
     this.name = spec.name;
@@ -2372,6 +2886,7 @@ var SlashCommand = class {
     this.autocompleter = spec.autocompleter;
     this.cooldown = spec.cooldown;
     this.guards = spec.guards;
+    this.autoDefer = spec.autoDefer;
   }
   /** Serialise to the discord REST chat-input command payload. */
   toJSON() {
@@ -2451,7 +2966,8 @@ function command(config) {
     executor,
     autocompleter: makeAutocompleter(options),
     cooldown: config.cooldown !== void 0 ? normalizeCooldown(config.cooldown) : void 0,
-    guards: config.guards
+    guards: config.guards,
+    autoDefer: normalizeAutoDefer(config.autoDefer)
   });
 }
 function subcommand(config) {
@@ -2524,7 +3040,8 @@ function commandGroup(config) {
     executor,
     autocompleter,
     cooldown: config.cooldown !== void 0 ? normalizeCooldown(config.cooldown) : void 0,
-    guards: config.guards
+    guards: config.guards,
+    autoDefer: normalizeAutoDefer(config.autoDefer)
   });
 }
 var CommandRegistry = class {
@@ -2535,6 +3052,7 @@ var CommandRegistry = class {
   defaultCooldown;
   defaultGuards = [];
   onUsage;
+  defaultAutoDefer;
   /** Register one or more commands. Later registrations override by name. */
   add(...commands) {
     for (const command2 of commands) this.commands.set(command2.name, command2);
@@ -2581,6 +3099,11 @@ var CommandRegistry = class {
     this.defaultGuards = guards;
     return this;
   }
+  /** Default auto-defer applied to commands that don't set their own. */
+  setAutoDefer(config) {
+    this.defaultAutoDefer = config;
+    return this;
+  }
   /** Attach a hook called after each successful command execution. */
   setUsageHook(hook) {
     this.onUsage = hook;
@@ -2620,6 +3143,8 @@ var CommandRegistry = class {
         return;
       }
     }
+    const autoDefer = command2.autoDefer ?? this.defaultAutoDefer;
+    const cancelAutoDefer = autoDefer !== void 0 ? armAutoDefer(interaction, autoDefer) : void 0;
     const start = Date.now();
     try {
       await command2.execute(interaction);
@@ -2653,6 +3178,8 @@ var CommandRegistry = class {
       } else {
         await this.defaultErrorReply(err, interaction);
       }
+    } finally {
+      cancelAutoDefer?.();
     }
   }
   /** Dispatch an autocomplete interaction to its command. */
@@ -2685,7 +3212,7 @@ var CommandRegistry = class {
   }
   async defaultErrorReply(error, interaction) {
     interaction.client.emit("error", error);
-    const content = "Something went wrong while running that command.";
+    const content = explainDiscordError(error) ?? "Something went wrong while running that command.";
     try {
       if (interaction.deferred) {
         await interaction.editReply({ content });
@@ -2901,6 +3428,13 @@ var MessageComponentContext = class extends BaseContext {
   async showModal(modal2) {
     await this.interaction.showModal(modal2);
   }
+  /**
+   * 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(modal2, options) {
+    return showAndAwaitModal(this.interaction, modal2, options);
+  }
 };
 var ButtonContext = class extends MessageComponentContext {
 };
@@ -3112,8 +3646,13 @@ var ComponentRegistry = class {
         await this.errorHandler(err, interaction);
       } else {
         interaction.client.emit("error", err);
-        if (!interaction.replied && !interaction.deferred) {
-          await interaction.reply({ content: "Something went wrong.", flags: MessageFlags.Ephemeral }).catch(() => void 0);
+        const content = explainDiscordError(err) ?? "Something went wrong.";
+        if (interaction.deferred) {
+          await interaction.editReply({ content }).catch(() => void 0);
+        } else if (interaction.replied) {
+          await interaction.followUp({ content, flags: MessageFlags.Ephemeral }).catch(() => void 0);
+        } else {
+          await interaction.reply({ content, flags: MessageFlags.Ephemeral }).catch(() => void 0);
         }
       }
     }
@@ -3415,17 +3954,20 @@ var SpearClient = class extends Client {
   contextMenus = new ContextMenuRegistry();
   envConfig;
   constructor(options = {}) {
-    const { intents, logger, dotenv, cooldown, prefix, usage, embeds, guards, ...rest } = options;
+    const { intents, logger, dotenv, cooldown, prefix, usage, embeds, guards, autoDefer, ...rest } = options;
     super({ ...rest, intents: intents ?? Intents.default });
     this.embeds = embeds instanceof Embeds ? embeds : new Embeds(embeds);
     this.envConfig = dotenv === false ? false : dotenv === void 0 || dotenv === true ? {} : dotenv;
     this.logger = logger instanceof Logger ? logger : new Logger(logger);
     const defaultCooldown = cooldown !== void 0 ? normalizeCooldown(cooldown) : void 0;
+    const defaultAutoDefer = normalizeAutoDefer(autoDefer);
     this.commands.setLogger(this.logger.child("commands"));
     this.commands.setCooldowns(this.cooldowns, defaultCooldown);
+    this.commands.setAutoDefer(defaultAutoDefer);
     this.components.setLogger(this.logger.child("components"));
     this.contextMenus.setLogger(this.logger.child("contextMenus"));
     this.contextMenus.setCooldowns(this.cooldowns, defaultCooldown);
+    this.contextMenus.setAutoDefer(defaultAutoDefer);
     this.prefix.setLogger(this.logger.child("prefix"));
     this.prefix.setCooldowns(this.cooldowns, defaultCooldown);
     if (prefix !== void 0) this.prefix.setOptions(prefix);
@@ -3559,6 +4101,21 @@ var SpearClient = class extends Client {
     this.scheduler.stop();
     await super.destroy();
   }
+  /**
+   * 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 = {}) {
+    const log = this.logger.child("shutdown");
+    return gracefulShutdown(this, {
+      logger: {
+        info: (message) => log.info(message),
+        error: (message, meta) => log.error(message, { error: toError(meta) })
+      },
+      ...options
+    });
+  }
   async route(interaction) {
     if (interaction.isChatInputCommand()) {
       await this.commands.handle(interaction);
@@ -3619,6 +4176,6 @@ function definePlugin(plugin) {
   return plugin;
 }
 
-export { AutocompleteContext, BaseContext, ButtonContext, ChannelSelectContext, CommandContext, CommandRegistry, ComponentRegistry, ContextMenuRegistry, CooldownManager, CronExpression, DEFAULT_EMBED_COLORS, DEFAULT_EMBED_ICONS, Embeds, EventRegistry, Intents, JsonFileUsageStore, KeyedLock, Logger, MAX_CUSTOM_ID_LENGTH, MemoryCache, MemoryUsageStore, MentionableSelectContext, MessageComponentContext, MessageContextMenuContext, ModalContext, PrefixArgsBuilder, PrefixContext, PrefixRegistry, RoleSelectContext, SlashCommand, SpearClient, StringSelectContext, TaskScheduler, UsageTracker, UserContextMenuContext, UserSelectContext, 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 { AutocompleteContext, BaseContext, ButtonContext, ChannelSelectContext, CommandContext, CommandRegistry, ComponentRegistry, ContextMenuRegistry, CooldownManager, CronExpression, DEFAULT_AUTO_DEFER_DELAY_MS, DEFAULT_EMBED_COLORS, DEFAULT_EMBED_ICONS, DiscordErrorCode, Embeds, EventRegistry, Intents, JsonFileUsageStore, JsonStore, KeyedLock, Logger, MAX_CUSTOM_ID_LENGTH, MESSAGE_CHARACTER_LIMIT, MemoryCache, MemoryStore, MemoryUsageStore, MentionableSelectContext, MessageComponentContext, MessageContextMenuContext, ModalContext, PrefixArgsBuilder, PrefixContext, PrefixRegistry, RoleSelectContext, SlashCommand, SpearClient, StringSelectContext, TaskScheduler, UsageTracker, UserContextMenuContext, UserSelectContext, 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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map