spearkit 0.3.1 → 0.4.0

package/dist/index.cjs

@@ -357,6 +357,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 {
@@ -451,6 +503,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 promises.readFile(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 promises.mkdir(path.dirname(this.path), { recursive: true });
+      const tmp = `${this.path}.${process.pid}.${Date.now()}.tmp`;
+      await promises.writeFile(tmp, body, "utf8");
+      await promises.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 };
 }
@@ -519,6 +695,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 discord_js.PermissionsBitField(required).toArray();
+  return held.missing(required);
+}
+function botMissingPermissions(channel, required) {
+  const me = channel.guild.members.me;
+  if (me === null) return new discord_js.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 discord_js.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: discord_js.RESTJSONErrorCodes.UnknownChannel,
+  // 10003
+  /** The targeted guild is gone or the bot was removed from it. */
+  UnknownGuild: discord_js.RESTJSONErrorCodes.UnknownGuild,
+  // 10004
+  /** The referenced member is not in the guild. */
+  UnknownMember: discord_js.RESTJSONErrorCodes.UnknownMember,
+  // 10007
+  /** The message was deleted (or never existed) before the action ran. */
+  UnknownMessage: discord_js.RESTJSONErrorCodes.UnknownMessage,
+  // 10008
+  /** The user could not be resolved. */
+  UnknownUser: discord_js.RESTJSONErrorCodes.UnknownUser,
+  // 10013
+  /** The interaction token expired (the classic 3-second-window failure). */
+  UnknownInteraction: discord_js.RESTJSONErrorCodes.UnknownInteraction,
+  // 10062
+  /** The bot lacks access to the resource entirely (not just one permission). */
+  MissingAccess: discord_js.RESTJSONErrorCodes.MissingAccess,
+  // 50001
+  /** Action attempted on a DM channel that does not support it. */
+  CannotExecuteActionOnDMChannel: discord_js.RESTJSONErrorCodes.CannotExecuteActionOnDMChannel,
+  // 50003
+  /** The target user has DMs closed or blocked the bot. */
+  CannotSendMessagesToThisUser: discord_js.RESTJSONErrorCodes.CannotSendMessagesToThisUser,
+  // 50007
+  /** The bot is missing one or more permissions required for the action. */
+  MissingPermissions: discord_js.RESTJSONErrorCodes.MissingPermissions,
+  // 50013
+  /** The request body failed Discord's validation. */
+  InvalidFormBodyOrContentType: discord_js.RESTJSONErrorCodes.InvalidFormBodyOrContentType,
+  // 50035
+  /** The interaction was already acknowledged elsewhere. */
+  InteractionHasAlreadyBeenAcknowledged: discord_js.RESTJSONErrorCodes.InteractionHasAlreadyBeenAcknowledged,
+  // 40060
+  /** The bot reached the maximum number of guilds it may join. */
+  MaximumNumberOfGuildsReached: discord_js.RESTJSONErrorCodes.MaximumNumberOfGuildsReached,
+  // 30001
+  /** Too many active reactions / pins / etc. of this kind. */
+  MaximumNumberOfReactionsReached: discord_js.RESTJSONErrorCodes.MaximumNumberOfReactionsReached
+  // 30010
+};
+function isDiscordError(error, code) {
+  if (!(error instanceof discord_js.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 discord_js.HTTPError;
+}
+function isRateLimitError(error) {
+  return error instanceof discord_js.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 discord_js.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: discord_js.MessageFlags.Ephemeral } : {}).catch(() => void 0);
+    }
+  }, config.delayMs);
+  if (typeof timer.unref === "function") timer.unref();
+  return () => clearTimeout(timer);
+}
 function withEphemeralFlag(flags) {
   if (flags == null) return discord_js.MessageFlags.Ephemeral;
   if (typeof flags === "number" || typeof flags === "bigint") {
@@ -615,6 +1063,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 discord_js.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;
@@ -779,6 +1259,7 @@ function userCommand(config) {
     name: config.name,
     cooldown,
     guards: config.guards,
+    autoDefer: normalizeAutoDefer(config.autoDefer),
     toJSON: () => baseJSON(config, discord_js.ApplicationCommandType.User),
     execute: async (interaction) => {
       await config.run(new UserContextMenuContext(interaction));
@@ -792,6 +1273,7 @@ function messageCommand(config) {
     name: config.name,
     cooldown,
     guards: config.guards,
+    autoDefer: normalizeAutoDefer(config.autoDefer),
     toJSON: () => baseJSON(config, discord_js.ApplicationCommandType.Message),
     execute: async (interaction) => {
       await config.run(new MessageContextMenuContext(interaction));
@@ -806,6 +1288,7 @@ var ContextMenuRegistry = class {
   defaultCooldown;
   defaultGuards = [];
   onUsage;
+  defaultAutoDefer;
   /** Register one or more context-menu commands. */
   add(...commands) {
     for (const command2 of commands) {
@@ -839,6 +1322,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;
@@ -882,6 +1370,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") {
@@ -917,15 +1407,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: discord_js.MessageFlags.Ephemeral
-          });
+        if (interaction.deferred) {
+          await interaction.editReply({ content });
+        } else if (interaction.replied) {
+          await interaction.followUp({ content, flags: discord_js.MessageFlags.Ephemeral });
+        } else {
+          await interaction.reply({ content, flags: discord_js.MessageFlags.Ephemeral });
         }
       } catch {
       }
+    } finally {
+      cancelAutoDefer?.();
     }
   }
 };
@@ -1861,7 +2355,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) {
@@ -1945,8 +2440,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) {
@@ -1955,14 +2450,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);
@@ -2310,6 +2815,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) {
@@ -2364,6 +2876,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;
@@ -2373,6 +2887,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() {
@@ -2452,7 +2967,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) {
@@ -2525,7 +3041,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 {
@@ -2536,6 +3053,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);
@@ -2582,6 +3100,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;
@@ -2621,6 +3144,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);
@@ -2654,6 +3179,8 @@ var CommandRegistry = class {
       } else {
         await this.defaultErrorReply(err, interaction);
       }
+    } finally {
+      cancelAutoDefer?.();
     }
   }
   /** Dispatch an autocomplete interaction to its command. */
@@ -2686,7 +3213,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 });
@@ -2902,6 +3429,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 {
 };
@@ -3113,8 +3647,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: discord_js.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: discord_js.MessageFlags.Ephemeral }).catch(() => void 0);
+        } else {
+          await interaction.reply({ content, flags: discord_js.MessageFlags.Ephemeral }).catch(() => void 0);
         }
       }
     }
@@ -3416,17 +3955,20 @@ var SpearClient = class extends discord_js.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);
@@ -3560,6 +4102,21 @@ var SpearClient = class extends discord_js.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);
@@ -3630,16 +4187,21 @@ exports.ComponentRegistry = ComponentRegistry;
 exports.ContextMenuRegistry = ContextMenuRegistry;
 exports.CooldownManager = CooldownManager;
 exports.CronExpression = CronExpression;
+exports.DEFAULT_AUTO_DEFER_DELAY_MS = DEFAULT_AUTO_DEFER_DELAY_MS;
 exports.DEFAULT_EMBED_COLORS = DEFAULT_EMBED_COLORS;
 exports.DEFAULT_EMBED_ICONS = DEFAULT_EMBED_ICONS;
+exports.DiscordErrorCode = DiscordErrorCode;
 exports.Embeds = Embeds;
 exports.EventRegistry = EventRegistry;
 exports.Intents = Intents;
 exports.JsonFileUsageStore = JsonFileUsageStore;
+exports.JsonStore = JsonStore;
 exports.KeyedLock = KeyedLock;
 exports.Logger = Logger;
 exports.MAX_CUSTOM_ID_LENGTH = MAX_CUSTOM_ID_LENGTH;
+exports.MESSAGE_CHARACTER_LIMIT = MESSAGE_CHARACTER_LIMIT;
 exports.MemoryCache = MemoryCache;
+exports.MemoryStore = MemoryStore;
 exports.MemoryUsageStore = MemoryUsageStore;
 exports.MentionableSelectContext = MentionableSelectContext;
 exports.MessageComponentContext = MessageComponentContext;
@@ -3656,18 +4218,26 @@ exports.TaskScheduler = TaskScheduler;
 exports.UsageTracker = UsageTracker;
 exports.UserContextMenuContext = UserContextMenuContext;
 exports.UserSelectContext = UserSelectContext;
+exports.armAutoDefer = armAutoDefer;
 exports.asEphemeral = asEphemeral;
+exports.awaitComponent = awaitComponent;
+exports.awaitMessage = awaitMessage;
+exports.botMissingPermissions = botMissingPermissions;
 exports.buildCustomId = buildCustomId;
 exports.buildPaginatorPage = buildPaginatorPage;
 exports.button = button;
+exports.canActOn = canActOn;
 exports.channelSelect = channelSelect;
+exports.chunkMessage = chunkMessage;
 exports.collectModules = collectModules;
 exports.command = command;
 exports.commandGroup = commandGroup;
+exports.compareRoles = compareRoles;
 exports.compilePattern = compilePattern;
 exports.confirm = confirm;
 exports.consoleSink = consoleSink;
 exports.createCache = createCache;
+exports.createSettings = createSettings;
 exports.cron = cron;
 exports.defaultEmbeds = defaultEmbeds;
 exports.definePlugin = definePlugin;
@@ -3677,6 +4247,7 @@ exports.dmOnly = dmOnly;
 exports.effectiveDuration = effectiveDuration;
 exports.env = env;
 exports.event = event;
+exports.explainDiscordError = explainDiscordError;
 exports.fetchChannel = fetchChannel;
 exports.fetchGuild = fetchGuild;
 exports.fetchMember = fetchMember;
@@ -3685,9 +4256,15 @@ exports.fetchRole = fetchRole;
 exports.fetchUser = fetchUser;
 exports.formatCooldownMessage = formatCooldownMessage;
 exports.formatDuration = formatDuration;
+exports.formatPermissions = formatPermissions;
 exports.formatUsage = formatUsage;
+exports.gracefulShutdown = gracefulShutdown;
 exports.guard = guard;
 exports.guildOnly = guildOnly;
+exports.hasPermissions = hasPermissions;
+exports.isDiscordError = isDiscordError;
+exports.isHTTPError = isHTTPError;
+exports.isRateLimitError = isRateLimitError;
 exports.jsonlSink = jsonlSink;
 exports.linkButton = linkButton;
 exports.loadConfig = loadConfig;
@@ -3698,7 +4275,11 @@ exports.lookup = lookup;
 exports.lookupOptional = lookupOptional;
 exports.mentionableSelect = mentionableSelect;
 exports.messageCommand = messageCommand;
+exports.missingPermissions = missingPermissions;
 exports.modal = modal;
+exports.moderationCheck = moderationCheck;
+exports.namespaced = namespaced;
+exports.normalizeAutoDefer = normalizeAutoDefer;
 exports.normalizeCooldown = normalizeCooldown;
 exports.normalizeReply = normalizeReply;
 exports.option = option;
@@ -3722,6 +4303,7 @@ exports.row = row;
 exports.runGuards = runGuards;
 exports.safeFetch = safeFetch;
 exports.safeTry = safeTry;
+exports.showAndAwaitModal = showAndAwaitModal;
 exports.stringSelect = stringSelect;
 exports.subcommand = subcommand;
 exports.subcommandGroup = subcommandGroup;
@@ -3729,6 +4311,7 @@ exports.task = task;
 exports.textInput = textInput;
 exports.toAPIOption = toAPIOption;
 exports.toError = toError;
+exports.truncate = truncate;
 exports.userCommand = userCommand;
 exports.userSelect = userSelect;
 exports.webhookSink = webhookSink;