spearkit 0.2.0 → 0.3.0

package/dist/index.cjs

@@ -2,13 +2,1237 @@
 
 var discord_js = require('discord.js');
 var fs = require('fs');
-var path = require('path');
+var util = require('util');
 var promises = require('fs/promises');
+var path = require('path');
 var url = require('url');
 
 // src/index.ts
+var DEFAULT_EMBED_COLORS = {
+  error: 15747655,
+  success: 4437378,
+  info: 3447003,
+  warn: 16361509
+};
+var DEFAULT_EMBED_ICONS = {
+  error: "\u26D4",
+  success: "\u2705",
+  info: "\u2139\uFE0F",
+  warn: "\u26A0\uFE0F"
+};
+var Embeds = class {
+  /** The resolved colors for every preset. */
+  colors;
+  /** The resolved icons for every preset. */
+  icons;
+  constructor(options = {}) {
+    this.colors = { ...DEFAULT_EMBED_COLORS, ...options.colors };
+    this.icons = { ...DEFAULT_EMBED_ICONS, ...options.icons };
+  }
+  /** Red preset — something went wrong. */
+  error(input) {
+    return this.build("error", input);
+  }
+  /** Green preset — something succeeded. */
+  success(input) {
+    return this.build("success", input);
+  }
+  /** Blue preset — neutral information. */
+  info(input) {
+    return this.build("info", input);
+  }
+  /** Yellow preset — caution. */
+  warn(input) {
+    return this.build("warn", input);
+  }
+  /** Build an embed at a chosen level. */
+  build(level, input) {
+    const builder = new discord_js.EmbedBuilder().setColor(this.colors[level]);
+    const icon = this.icons[level];
+    const prefix = icon.length > 0 ? `${icon} ` : "";
+    if (typeof input === "string") {
+      builder.setDescription(`${prefix}${input}`);
+      return builder;
+    }
+    if (input.title !== void 0) builder.setTitle(input.title);
+    if (input.description !== void 0) {
+      builder.setDescription(`${prefix}${input.description}`);
+    }
+    if (input.fields !== void 0) builder.addFields(...input.fields);
+    if (input.footer !== void 0) builder.setFooter(input.footer);
+    if (input.author !== void 0) builder.setAuthor(input.author);
+    if (input.url !== void 0) builder.setURL(input.url);
+    if (input.timestamp !== void 0) {
+      builder.setTimestamp(
+        input.timestamp instanceof Date ? input.timestamp : new Date(input.timestamp)
+      );
+    }
+    if (input.thumbnail !== void 0) builder.setThumbnail(input.thumbnail.url);
+    if (input.image !== void 0) builder.setImage(input.image.url);
+    return builder;
+  }
+};
+var defaultEmbeds = new Embeds();
+
+// src/lock.ts
+var KeyedLock = class {
+  entries = /* @__PURE__ */ new Map();
+  defaultTtl;
+  sweepTimer;
+  constructor(options = {}) {
+    this.defaultTtl = options.ttl ?? 6e4;
+    const sweep = options.sweep ?? 15e3;
+    if (sweep > 0) {
+      this.sweepTimer = setInterval(() => this.sweep(), sweep);
+      if (typeof this.sweepTimer.unref === "function") this.sweepTimer.unref();
+    }
+  }
+  /** Try to acquire `key`. Returns a release function, or `null` if already held. */
+  tryAcquire(key, ttl = this.defaultTtl) {
+    const existing = this.entries.get(key);
+    if (existing !== void 0 && Date.now() - existing.createdAt < existing.ttl) {
+      return null;
+    }
+    this.entries.set(key, { createdAt: Date.now(), ttl });
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.entries.delete(key);
+    };
+  }
+  /** Whether `key` is currently held and not expired. */
+  isHeld(key) {
+    const entry = this.entries.get(key);
+    return entry !== void 0 && Date.now() - entry.createdAt < entry.ttl;
+  }
+  /**
+   * Run `fn` while holding `key`. If the key is already held, calls `onBusy`
+   * (or returns `undefined`) without ever calling `fn`. Always releases on
+   * return or throw.
+   */
+  async run(key, fn, options = {}) {
+    const release = this.tryAcquire(key, options.ttl ?? this.defaultTtl);
+    if (release === null) {
+      return options.onBusy !== void 0 ? await options.onBusy() : void 0;
+    }
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
+  }
+  /** Number of currently-tracked leases (including expired-but-unswept). */
+  get size() {
+    return this.entries.size;
+  }
+  /** Drop all known leases and stop the sweep timer. */
+  dispose() {
+    this.entries.clear();
+    if (this.sweepTimer !== void 0) clearInterval(this.sweepTimer);
+  }
+  /** Manually remove a single key without running anything. */
+  forget(key) {
+    return this.entries.delete(key);
+  }
+  sweep() {
+    const now = Date.now();
+    for (const [key, entry] of this.entries.entries()) {
+      if (now - entry.createdAt > entry.ttl) this.entries.delete(key);
+    }
+  }
+};
+
+// src/safe-fetch.ts
+var DEFAULT_TIMEOUT_MS = 5e3;
+async function withTimeout(promise, ms) {
+  let timer;
+  try {
+    const timeout = new Promise((resolve) => {
+      timer = setTimeout(() => resolve(null), ms);
+    });
+    return await Promise.race([promise.catch(() => null), timeout]);
+  } finally {
+    if (timer !== void 0) clearTimeout(timer);
+  }
+}
+async function fetchMember(guild, userId, options = {}) {
+  if (guild == null || userId == null || userId.length === 0) return null;
+  if (options.cache !== false && options.force !== true) {
+    const cached = guild.members.cache.get(userId);
+    if (cached !== void 0) return cached;
+  }
+  return withTimeout(
+    guild.members.fetch({ user: userId, force: options.force ?? false }),
+    options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  );
+}
+async function fetchChannel(client, channelId, options = {}) {
+  if (client == null || channelId == null || channelId.length === 0) return null;
+  if (options.cache !== false && options.force !== true) {
+    const cached = client.channels.cache.get(channelId);
+    if (cached !== void 0) return cached;
+  }
+  return withTimeout(
+    client.channels.fetch(channelId, { force: options.force ?? false }),
+    options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  );
+}
+async function fetchMessage(messages, messageId, options = {}) {
+  if (messages == null || messageId == null || messageId.length === 0) return null;
+  if (options.cache !== false && options.force !== true) {
+    const cached = messages.cache.get(messageId);
+    if (cached !== void 0) return cached;
+  }
+  return withTimeout(
+    messages.fetch({ message: messageId, force: options.force ?? false }),
+    options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  );
+}
+async function fetchUser(client, userId, options = {}) {
+  if (client == null || userId == null || userId.length === 0) return null;
+  if (options.cache !== false && options.force !== true) {
+    const cached = client.users.cache.get(userId);
+    if (cached !== void 0) return cached;
+  }
+  return withTimeout(
+    client.users.fetch(userId, { force: options.force ?? false }),
+    options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  );
+}
+async function fetchGuild(client, guildId, options = {}) {
+  if (client == null || guildId == null || guildId.length === 0) return null;
+  if (options.cache !== false && options.force !== true) {
+    const cached = client.guilds.cache.get(guildId);
+    if (cached !== void 0) return cached;
+  }
+  return withTimeout(
+    client.guilds.fetch({ guild: guildId, force: options.force ?? false }),
+    options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  );
+}
+async function fetchRole(guild, roleId, options = {}) {
+  if (guild == null || roleId == null || roleId.length === 0) return null;
+  if (options.cache !== false && options.force !== true) {
+    const cached = guild.roles.cache.get(roleId);
+    if (cached !== void 0) return cached;
+  }
+  return withTimeout(
+    guild.roles.fetch(roleId, { force: options.force ?? false }),
+    options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  );
+}
+async function safeTry(op) {
+  try {
+    return await op();
+  } catch {
+    return null;
+  }
+}
+async function withSafeTimeout(promise, timeoutMs) {
+  return withTimeout(promise, timeoutMs);
+}
+var safeFetch = {
+  member: fetchMember,
+  channel: fetchChannel,
+  message: fetchMessage,
+  user: fetchUser,
+  guild: fetchGuild,
+  role: fetchRole,
+  try: safeTry
+};
+
+// src/format.ts
+var EN = {
+  week: ["week", "weeks"],
+  day: ["day", "days"],
+  hour: ["hour", "hours"],
+  minute: ["minute", "minutes"],
+  second: ["second", "seconds"],
+  separator: " ",
+  zero: "0 seconds"
+};
+var TR = {
+  week: ["hafta", "hafta"],
+  day: ["g\xFCn", "g\xFCn"],
+  hour: ["saat", "saat"],
+  minute: ["dakika", "dakika"],
+  second: ["saniye", "saniye"],
+  separator: " ",
+  zero: "0 saniye"
+};
+var LABELS = {
+  en: EN,
+  "en-US": EN,
+  "en-GB": EN,
+  tr: TR,
+  "tr-TR": TR
+};
+var UNIT_MS = {
+  week: 7 * 864e5,
+  day: 864e5,
+  hour: 36e5,
+  minute: 6e4,
+  second: 1e3
+};
+var UNIT_ORDER = ["week", "day", "hour", "minute", "second"];
+function resolveLabels(locale) {
+  if (typeof locale === "object" && locale !== null) return locale;
+  if (locale === void 0) return EN;
+  return LABELS[locale] ?? LABELS[locale.split("-")[0] ?? ""] ?? EN;
+}
+function formatDuration(ms, options = {}) {
+  const labels = resolveLabels(options.locale);
+  if (!Number.isFinite(ms) || ms <= 0) return labels.zero;
+  const limit = options.largest ?? 2;
+  const units = options.units ?? UNIT_ORDER;
+  const parts = [];
+  let remaining = Math.floor(ms);
+  for (const unit of units) {
+    if (parts.length >= limit) break;
+    const size = UNIT_MS[unit];
+    if (remaining < size) continue;
+    const value = Math.floor(remaining / size);
+    remaining -= value * size;
+    const word = value === 1 ? labels[unit][0] : labels[unit][1];
+    parts.push(`${value} ${word}`);
+  }
+  return parts.length > 0 ? parts.join(labels.separator) : labels.zero;
+}
+var DURATION_PATTERN = /(\d+(?:\.\d+)?)\s*(milliseconds|millisecond|seconds|minutes|saniye|dakika|minute|second|weeks|hours|hafta|saat|week|hour|days|day|gün|gun|min|sec|ms|wk|hr|dk|m|s|h|d|w)/gi;
+var SHORT_TO_MS = {
+  ms: 1,
+  millisecond: 1,
+  milliseconds: 1,
+  s: 1e3,
+  sec: 1e3,
+  second: 1e3,
+  seconds: 1e3,
+  saniye: 1e3,
+  m: 6e4,
+  min: 6e4,
+  minute: 6e4,
+  minutes: 6e4,
+  dakika: 6e4,
+  dk: 6e4,
+  h: 36e5,
+  hr: 36e5,
+  hour: 36e5,
+  hours: 36e5,
+  saat: 36e5,
+  d: 864e5,
+  day: 864e5,
+  days: 864e5,
+  g\u00FCn: 864e5,
+  gun: 864e5,
+  w: 6048e5,
+  wk: 6048e5,
+  week: 6048e5,
+  weeks: 6048e5,
+  hafta: 6048e5
+};
+function parseDuration(input) {
+  const trimmed = input.trim().toLowerCase();
+  if (trimmed.length === 0) return null;
+  DURATION_PATTERN.lastIndex = 0;
+  let total = 0;
+  let matched = false;
+  for (; ; ) {
+    const match = DURATION_PATTERN.exec(trimmed);
+    if (match === null) break;
+    matched = true;
+    const value = Number(match[1]);
+    const unit = match[2] ?? "";
+    const ms = SHORT_TO_MS[unit];
+    if (ms !== void 0 && Number.isFinite(value)) total += value * ms;
+  }
+  return matched ? total : null;
+}
+function toEpochSeconds(date) {
+  return Math.floor((date instanceof Date ? date.getTime() : date) / 1e3);
+}
+function discordTimestamp(date, style = "f") {
+  return `<t:${toEpochSeconds(date)}:${style}>`;
+}
+function relativeTimestamp(date) {
+  return discordTimestamp(date, "R");
+}
+
+// src/cache.ts
+var MemoryCache = class {
+  store = /* @__PURE__ */ new Map();
+  /** Total number of stored (possibly expired) entries — primarily for tests. */
+  get size() {
+    return this.store.size;
+  }
+  async get(key) {
+    const entry = this.store.get(key);
+    if (entry === void 0) return void 0;
+    if (entry.expiresAt !== void 0 && entry.expiresAt <= Date.now()) {
+      this.store.delete(key);
+      return void 0;
+    }
+    return entry.value;
+  }
+  async set(key, value, options) {
+    const ttl = options?.ttl;
+    this.store.set(key, {
+      value,
+      expiresAt: ttl !== void 0 && ttl > 0 ? Date.now() + ttl : void 0
+    });
+  }
+  async delete(key) {
+    return this.store.delete(key);
+  }
+  async has(key) {
+    return await this.get(key) !== void 0;
+  }
+  async increment(key, delta = 1, options) {
+    const current = await this.get(key) ?? 0;
+    const next = current + delta;
+    const existing = this.store.get(key);
+    const ttl = options?.ttl;
+    if (ttl !== void 0 && ttl > 0) {
+      await this.set(key, next, { ttl });
+    } else if (existing?.expiresAt !== void 0) {
+      this.store.set(key, { value: next, expiresAt: existing.expiresAt });
+    } else {
+      await this.set(key, next);
+    }
+    return next;
+  }
+  async rateLimit(key, options) {
+    const now = Date.now();
+    const bucketKey = `__rl__:${key}`;
+    const entry = this.store.get(bucketKey);
+    const expired = entry === void 0 || entry.expiresAt === void 0 || entry.expiresAt <= now;
+    if (expired) {
+      const resetAt2 = now + options.windowMs;
+      this.store.set(bucketKey, { value: 1, expiresAt: resetAt2 });
+      return { allowed: true, remaining: Math.max(0, options.limit - 1), resetAt: resetAt2 };
+    }
+    const count = entry.value;
+    const resetAt = entry.expiresAt ?? now;
+    if (count >= options.limit) {
+      return { allowed: false, remaining: 0, resetAt };
+    }
+    this.store.set(bucketKey, { value: count + 1, expiresAt: resetAt });
+    return { allowed: true, remaining: Math.max(0, options.limit - count - 1), resetAt };
+  }
+  async clear() {
+    this.store.clear();
+  }
+};
+function createCache() {
+  return new MemoryCache();
+}
+var readFileAsync = util.promisify(fs.readFile);
+function loadConfig(options) {
+  const text = fs.readFileSync(options.file, options.encoding ?? "utf8");
+  const parser = options.parser ?? JSON.parse;
+  const parsed = parser(text);
+  return options.schema !== void 0 ? options.schema(parsed) : parsed;
+}
+async function loadConfigAsync(options) {
+  const text = await readFileAsync(options.file, options.encoding ?? "utf8");
+  const parser = options.parser ?? JSON.parse;
+  const parsed = parser(text);
+  return options.schema !== void 0 ? options.schema(parsed) : parsed;
+}
+function lookup(table, resourceName = "key") {
+  return (key) => {
+    const value = table[key];
+    if (value === void 0) {
+      throw new Error(`spearkit: ${resourceName} "${String(key)}" not found in config`);
+    }
+    return value;
+  };
+}
+function lookupOptional(table) {
+  return (key) => table[key];
+}
+function denied(reason) {
+  return { allowed: false, reason };
+}
+async function runGuards(ctx, guards) {
+  if (guards === void 0 || guards.length === 0) return { allowed: true };
+  for (const guard2 of guards) {
+    const result = await guard2(ctx);
+    if (result === true) continue;
+    if (result === false) return { allowed: false, reason: void 0 };
+    if (result.allowed === false) return { allowed: false, reason: result.reason };
+  }
+  return { allowed: true };
+}
+function guildOnly(reason = "This can only be used in a server.") {
+  return (ctx) => ctx.guildId !== null ? true : denied(reason);
+}
+function dmOnly(reason = "This can only be used in DMs.") {
+  return (ctx) => ctx.guildId === null ? true : denied(reason);
+}
+function memberRoleIds(member) {
+  if (member === null) return [];
+  const roles = member.roles;
+  if (Array.isArray(roles)) return roles;
+  return [...roles.cache.keys()];
+}
+function memberPermissionsBitField(member) {
+  if (member === null) return null;
+  const perms = member.permissions;
+  if (perms instanceof discord_js.PermissionsBitField) return perms;
+  if (typeof perms === "string") return new discord_js.PermissionsBitField(BigInt(perms));
+  return null;
+}
+function requireAnyRole(roleIds, reason = "You don't have permission to use this.") {
+  const set = new Set(roleIds);
+  return (ctx) => {
+    const ids = memberRoleIds(ctx.member);
+    return ids.some((id) => set.has(id)) ? true : denied(reason);
+  };
+}
+function requireAllRoles(roleIds, reason = "You're missing one of the required roles.") {
+  return (ctx) => {
+    const ids = new Set(memberRoleIds(ctx.member));
+    return roleIds.every((id) => ids.has(id)) ? true : denied(reason);
+  };
+}
+function requireOwner(ownerIds, reason = "This is owner-only.") {
+  const set = new Set(ownerIds);
+  return (ctx) => set.has(ctx.user.id) ? true : denied(reason);
+}
+function requireUserPermissions(permission, reason = "You don't have permission to use this.") {
+  return (ctx) => {
+    const bits = memberPermissionsBitField(ctx.member);
+    if (bits === null) return denied(reason);
+    return bits.has(permission) ? true : denied(reason);
+  };
+}
+function requireBotPermissions(permission, reason = "I don't have permission to do that here.") {
+  return async (ctx) => {
+    const guild = ctx.guild;
+    if (guild === null) return denied(reason);
+    const me = guild.members.me ?? await guild.members.fetchMe().catch(() => null);
+    if (me === null) return denied(reason);
+    return me.permissions.has(permission) ? true : denied(reason);
+  };
+}
+function guard(predicate) {
+  return predicate;
+}
+function withEphemeralFlag(flags) {
+  if (flags == null) return discord_js.MessageFlags.Ephemeral;
+  if (typeof flags === "number" || typeof flags === "bigint") {
+    return Number(flags) | discord_js.MessageFlags.Ephemeral;
+  }
+  if (Array.isArray(flags)) return [...flags, discord_js.MessageFlags.Ephemeral];
+  return [flags, discord_js.MessageFlags.Ephemeral];
+}
+function normalizeReply(input) {
+  if (typeof input === "string") return { content: input };
+  const { ephemeral, ...rest } = input;
+  if (ephemeral) return { ...rest, flags: withEphemeralFlag(rest.flags) };
+  return rest;
+}
+function normalizeEdit(input) {
+  if (typeof input === "string") return { content: input };
+  const { ephemeral: _ephemeral, flags: _flags, ...rest } = input;
+  return rest;
+}
+function asEphemeral(input) {
+  if (typeof input === "string") return { content: input, ephemeral: true };
+  return { ...input, ephemeral: true };
+}
+var BaseContext = class {
+  constructor(interaction) {
+    this.interaction = interaction;
+  }
+  interaction;
+  get client() {
+    return this.interaction.client;
+  }
+  get user() {
+    return this.interaction.user;
+  }
+  get member() {
+    return this.interaction.member;
+  }
+  get guild() {
+    return this.interaction.guild;
+  }
+  get guildId() {
+    return this.interaction.guildId;
+  }
+  get channel() {
+    return this.interaction.channel;
+  }
+  get channelId() {
+    return this.interaction.channelId;
+  }
+  get locale() {
+    return this.interaction.locale;
+  }
+  /** Whether the interaction is already deferred. */
+  get deferred() {
+    return this.interaction.deferred;
+  }
+  /** Whether the interaction already received an initial response. */
+  get replied() {
+    return this.interaction.replied;
+  }
+  /** Send the initial response to the interaction. */
+  reply(input) {
+    return this.interaction.reply(normalizeReply(input));
+  }
+  /** Reply, but always hidden to everyone except the invoking user. */
+  replyEphemeral(input) {
+    return this.reply(asEphemeral(input));
+  }
+  /** Acknowledge now and respond later via {@link editReply}. */
+  defer(options = {}) {
+    return this.interaction.deferReply(
+      options.ephemeral ? { flags: discord_js.MessageFlags.Ephemeral } : {}
+    );
+  }
+  /** Edit the original (or deferred) response. */
+  editReply(input) {
+    return this.interaction.editReply(normalizeEdit(input));
+  }
+  /** Add an additional message after the initial response. */
+  followUp(input) {
+    return this.interaction.followUp(normalizeReply(input));
+  }
+  /**
+   * State-aware send: replies, edits a deferred response, or follows up —
+   * whichever is valid given the current interaction state. The single method
+   * most handlers ever need.
+   */
+  async send(input) {
+    if (this.interaction.deferred) {
+      await this.editReply(input);
+    } else if (this.interaction.replied) {
+      await this.followUp(input);
+    } else {
+      await this.reply(input);
+    }
+  }
+  /** Get the configured {@link Embeds} factory — `client.embeds` or the default. */
+  getEmbeds() {
+    return this.interaction.client.embeds ?? defaultEmbeds;
+  }
+  /** State-aware send of a red error embed. Defaults to ephemeral. */
+  error(input, options = {}) {
+    return this.sendPreset("error", input, { ephemeral: options.ephemeral ?? true });
+  }
+  /** State-aware send of a green success embed. */
+  success(input, options = {}) {
+    return this.sendPreset("success", input, options);
+  }
+  /** State-aware send of a blue info embed. */
+  info(input, options = {}) {
+    return this.sendPreset("info", input, options);
+  }
+  /** State-aware send of a yellow warn embed. */
+  warn(input, options = {}) {
+    return this.sendPreset("warn", input, options);
+  }
+  /** Initial-reply variant of {@link error} (always `reply`, never `editReply`/`followUp`). */
+  replyError(input, options = {}) {
+    return this.replyPreset("error", input, { ephemeral: options.ephemeral ?? true });
+  }
+  /** Initial-reply variant of {@link success}. */
+  replySuccess(input, options = {}) {
+    return this.replyPreset("success", input, options);
+  }
+  /** Initial-reply variant of {@link info}. */
+  replyInfo(input, options = {}) {
+    return this.replyPreset("info", input, options);
+  }
+  /** Initial-reply variant of {@link warn}. */
+  replyWarn(input, options = {}) {
+    return this.replyPreset("warn", input, options);
+  }
+  sendPreset(level, input, options) {
+    const embed = this.getEmbeds().build(level, input);
+    return this.send({ embeds: [embed], ephemeral: options.ephemeral });
+  }
+  replyPreset(level, input, options) {
+    const embed = this.getEmbeds().build(level, input);
+    return this.reply({ embeds: [embed], ephemeral: options.ephemeral });
+  }
+};
+
+// src/cooldown.ts
+function normalizeCooldown(input) {
+  return typeof input === "number" ? { duration: input } : input;
+}
+function scopeKey(scope, actor) {
+  switch (scope) {
+    case "guild":
+      return `g:${actor.guildId ?? "dm"}`;
+    case "channel":
+      return `c:${actor.channelId ?? "dm"}`;
+    case "global":
+      return "global";
+    case "user":
+      return `u:${actor.userId}`;
+  }
+}
+function effectiveDuration(config, actor) {
+  if (config.exempt?.users?.includes(actor.userId) === true) return null;
+  if (config.exempt?.roles?.some((roleId) => actor.roleIds.includes(roleId)) === true) return null;
+  const userOverride = config.overrides?.users?.[actor.userId];
+  if (userOverride !== void 0) return userOverride;
+  const roleOverrides = config.overrides?.roles;
+  if (roleOverrides !== void 0) {
+    let best;
+    for (const roleId of actor.roleIds) {
+      const candidate = roleOverrides[roleId];
+      if (candidate !== void 0) best = best === void 0 ? candidate : Math.min(best, candidate);
+    }
+    if (best !== void 0) return best;
+  }
+  return config.duration;
+}
+function keyFor(bucket, config, actor) {
+  return `${bucket}|${scopeKey(config.scope ?? "user", actor)}`;
+}
+var CooldownManager = class {
+  hits = /* @__PURE__ */ new Map();
+  /** Number of tracked buckets. */
+  get size() {
+    return this.hits.size;
+  }
+  /**
+   * Check whether `actor` may use `bucket`, recording the use when allowed.
+   * Exempt actors and non-positive durations are always allowed (no record).
+   */
+  consume(bucket, input, actor, now = Date.now()) {
+    const config = normalizeCooldown(input);
+    const duration = effectiveDuration(config, actor);
+    if (duration === null || duration <= 0) return { allowed: true };
+    const key = keyFor(bucket, config, actor);
+    const last = this.hits.get(key);
+    if (last !== void 0 && now - last < duration) {
+      return { allowed: false, remaining: duration - (now - last) };
+    }
+    this.hits.set(key, now);
+    return { allowed: true };
+  }
+  /** Like {@link consume} but never records — a read-only check. */
+  peek(bucket, input, actor, now = Date.now()) {
+    const config = normalizeCooldown(input);
+    const duration = effectiveDuration(config, actor);
+    if (duration === null || duration <= 0) return { allowed: true };
+    const last = this.hits.get(keyFor(bucket, config, actor));
+    if (last !== void 0 && now - last < duration) {
+      return { allowed: false, remaining: duration - (now - last) };
+    }
+    return { allowed: true };
+  }
+  /** Clear a single actor's cooldown for a bucket. Returns whether one existed. */
+  reset(bucket, actor, scope = "user") {
+    return this.hits.delete(`${bucket}|${scopeKey(scope, actor)}`);
+  }
+  /** Drop every tracked cooldown. */
+  clear() {
+    this.hits.clear();
+  }
+};
+function formatCooldownMessage(config, remainingMs) {
+  if (typeof config.message === "function") return config.message(remainingMs);
+  if (typeof config.message === "string") return config.message;
+  const seconds = Math.max(1, Math.ceil(remainingMs / 1e3));
+  return `You're on cooldown \u2014 try again in ${seconds}s.`;
+}
+
+// src/context-menus.ts
+var UserContextMenuContext = class extends BaseContext {
+  /** The user the menu was invoked on. */
+  get targetUser() {
+    return this.interaction.targetUser;
+  }
+  /** The member version of the target, if available. */
+  get targetMember() {
+    return this.interaction.targetMember;
+  }
+};
+var MessageContextMenuContext = class extends BaseContext {
+  /** The message the menu was invoked on. */
+  get targetMessage() {
+    return this.interaction.targetMessage;
+  }
+};
+function baseJSON(meta, type) {
+  return {
+    type,
+    name: meta.name,
+    name_localizations: meta.nameLocalizations,
+    nsfw: meta.nsfw,
+    default_member_permissions: meta.defaultMemberPermissions == null ? meta.defaultMemberPermissions : new discord_js.PermissionsBitField(meta.defaultMemberPermissions).bitfield.toString(),
+    contexts: meta.guildOnly ? [discord_js.InteractionContextType.Guild] : void 0
+  };
+}
+function userCommand(config) {
+  const cooldown = config.cooldown !== void 0 ? normalizeCooldown(config.cooldown) : void 0;
+  return {
+    kind: "userMenu",
+    name: config.name,
+    cooldown,
+    guards: config.guards,
+    toJSON: () => baseJSON(config, discord_js.ApplicationCommandType.User),
+    execute: async (interaction) => {
+      await config.run(new UserContextMenuContext(interaction));
+    }
+  };
+}
+function messageCommand(config) {
+  const cooldown = config.cooldown !== void 0 ? normalizeCooldown(config.cooldown) : void 0;
+  return {
+    kind: "messageMenu",
+    name: config.name,
+    cooldown,
+    guards: config.guards,
+    toJSON: () => baseJSON(config, discord_js.ApplicationCommandType.Message),
+    execute: async (interaction) => {
+      await config.run(new MessageContextMenuContext(interaction));
+    }
+  };
+}
+var ContextMenuRegistry = class {
+  users = /* @__PURE__ */ new Map();
+  messages = /* @__PURE__ */ new Map();
+  logger;
+  cooldowns;
+  defaultCooldown;
+  defaultGuards = [];
+  onUsage;
+  /** Register one or more context-menu commands. */
+  add(...commands) {
+    for (const command2 of commands) {
+      if (command2.kind === "userMenu") this.users.set(command2.name, command2);
+      else this.messages.set(command2.name, command2);
+    }
+    return this;
+  }
+  /** Total number of registered context-menu commands. */
+  get size() {
+    return this.users.size + this.messages.size;
+  }
+  /** Every registered command, both kinds. */
+  all() {
+    return [...this.users.values(), ...this.messages.values()];
+  }
+  /** Serialise every command for the REST `applicationCommands` PUT body. */
+  toJSON() {
+    return this.all().map((c) => c.toJSON());
+  }
+  setLogger(logger) {
+    this.logger = logger;
+    return this;
+  }
+  setCooldowns(manager, defaultCooldown) {
+    this.cooldowns = manager;
+    this.defaultCooldown = defaultCooldown;
+    return this;
+  }
+  setDefaultGuards(guards) {
+    this.defaultGuards = guards;
+    return this;
+  }
+  setUsageHook(hook) {
+    this.onUsage = hook;
+    return this;
+  }
+  /** Dispatch a user-target interaction. */
+  async handleUser(interaction) {
+    const command2 = this.users.get(interaction.commandName);
+    if (command2 === void 0) return;
+    await this.dispatch(command2, interaction);
+  }
+  /** Dispatch a message-target interaction. */
+  async handleMessage(interaction) {
+    const command2 = this.messages.get(interaction.commandName);
+    if (command2 === void 0) return;
+    await this.dispatch(command2, interaction);
+  }
+  async dispatch(command2, interaction) {
+    this.logger?.debug("contextMenu", {
+      data: { kind: command2.kind, name: command2.name, user: interaction.user.id }
+    });
+    const cooldown = command2.cooldown ?? this.defaultCooldown;
+    if (cooldown !== void 0 && this.cooldowns !== void 0) {
+      const result = this.cooldowns.consume(
+        `${command2.kind}:${command2.name}`,
+        cooldown,
+        actorOf(interaction)
+      );
+      if (!result.allowed) {
+        await replyCooldown(interaction, cooldown, result.remaining);
+        return;
+      }
+    }
+    const guards = combineGuards(this.defaultGuards, command2.guards);
+    if (guards.length > 0) {
+      const guardResult = await runGuards(interaction, guards);
+      if (!guardResult.allowed) {
+        this.logger?.debug("contextMenu denied", {
+          data: { name: command2.name, user: interaction.user.id, reason: guardResult.reason ?? "" }
+        });
+        await replyDenied(interaction, guardResult.reason);
+        return;
+      }
+    }
+    const start = Date.now();
+    try {
+      if (command2.kind === "userMenu") {
+        await command2.execute(interaction);
+      } else {
+        await command2.execute(interaction);
+      }
+      this.onUsage?.({
+        type: "command",
+        name: command2.name,
+        detail: command2.kind,
+        outcome: "success",
+        durationMs: Date.now() - start,
+        userId: interaction.user.id,
+        userTag: interaction.user.tag,
+        guildId: interaction.guildId,
+        channelId: interaction.channelId,
+        timestamp: /* @__PURE__ */ new Date()
+      });
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.onUsage?.({
+        type: "command",
+        name: command2.name,
+        detail: command2.kind,
+        outcome: "error",
+        errorMessage: err.message,
+        durationMs: Date.now() - start,
+        userId: interaction.user.id,
+        userTag: interaction.user.tag,
+        guildId: interaction.guildId,
+        channelId: interaction.channelId,
+        timestamp: /* @__PURE__ */ new Date()
+      });
+      interaction.client.emit("error", err);
+      try {
+        if (!interaction.replied && !interaction.deferred) {
+          await interaction.reply({
+            content: "Something went wrong.",
+            flags: discord_js.MessageFlags.Ephemeral
+          });
+        }
+      } catch {
+      }
+    }
+  }
+};
+function combineGuards(defaults, own) {
+  if (own === void 0 || own.length === 0) return defaults;
+  if (defaults.length === 0) return own;
+  return [...defaults, ...own];
+}
+function actorOf(interaction) {
+  const member = interaction.member;
+  let roleIds = [];
+  if (member !== null) {
+    const roles = member.roles;
+    roleIds = Array.isArray(roles) ? roles : [...roles.cache.keys()];
+  }
+  return {
+    userId: interaction.user.id,
+    roleIds,
+    guildId: interaction.guildId,
+    channelId: interaction.channelId
+  };
+}
+function clientEmbeds(client) {
+  return client.embeds ?? defaultEmbeds;
+}
+async function replyCooldown(interaction, config, remaining) {
+  const content = formatCooldownMessage(config, remaining);
+  try {
+    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 {
+  }
+}
+async function replyDenied(interaction, reason) {
+  const embeds = clientEmbeds(interaction.client);
+  const text = reason ?? "You don't have permission to use this.";
+  try {
+    const payload = { embeds: [embeds.error(text)], flags: discord_js.MessageFlags.Ephemeral };
+    if (interaction.deferred) await interaction.editReply({ embeds: payload.embeds });
+    else if (interaction.replied) await interaction.followUp(payload);
+    else await interaction.reply(payload);
+  } catch {
+  }
+}
 
-// src/logger.ts
+// src/prefix-args.ts
+var SNOWFLAKE_RE = /^\d{15,21}$/;
+var USER_MENTION_RE = /^<@!?(\d{15,21})>$/;
+var CHANNEL_MENTION_RE = /^<#(\d{15,21})>$/;
+var ROLE_MENTION_RE = /^<@&(\d{15,21})>$/;
+function extractSnowflake(input) {
+  if (SNOWFLAKE_RE.test(input)) return input;
+  const m = USER_MENTION_RE.exec(input) ?? CHANNEL_MENTION_RE.exec(input) ?? ROLE_MENTION_RE.exec(input);
+  return m === null ? null : m[1] ?? null;
+}
+var PrefixArgsBuilder = class _PrefixArgsBuilder {
+  specs;
+  /** @internal */
+  constructor(specs = []) {
+    this.specs = specs;
+  }
+  /** A raw string token. */
+  string(name, options) {
+    return this.push({ name, kind: "string", required: options?.required ?? false, defaultValue: options?.default });
+  }
+  /** A whole integer. */
+  integer(name, options) {
+    return this.push({ name, kind: "integer", required: options?.required ?? false, defaultValue: options?.default });
+  }
+  /** A floating-point number. */
+  number(name, options) {
+    return this.push({ name, kind: "number", required: options?.required ?? false, defaultValue: options?.default });
+  }
+  /** A boolean (`true`/`yes`/`1`/`on` vs `false`/`no`/`0`/`off`). */
+  boolean(name, options) {
+    return this.push({ name, kind: "boolean", required: options?.required ?? false, defaultValue: options?.default });
+  }
+  /** A Discord snowflake id — accepts raw ids and `<@u>` / `<#c>` / `<@&r>` mentions. */
+  snowflake(name, options) {
+    return this.push({ name, kind: "snowflake", required: options?.required ?? false, defaultValue: options?.default });
+  }
+  /** A duration like `"1h30m"` or `"1 saat"` parsed to milliseconds. */
+  duration(name, options) {
+    return this.push({ name, kind: "duration", required: options?.required ?? false, defaultValue: options?.default });
+  }
+  /** The remainder of the message (everything after previous args). */
+  rest(name, options) {
+    return this.push({ name, kind: "rest", required: options?.required ?? false, defaultValue: options?.default });
+  }
+  push(spec) {
+    return new _PrefixArgsBuilder([...this.specs, spec]);
+  }
+  /** Compile this builder into a parser. */
+  compile() {
+    const specs = this.specs;
+    return {
+      specs,
+      parse(tokens, rest) {
+        const out = {};
+        let idx = 0;
+        for (let i = 0; i < specs.length; i++) {
+          const spec = specs[i];
+          if (spec.kind === "rest") {
+            const tail = idx === 0 ? rest : tokens.slice(idx).join(" ");
+            if (tail.length === 0) {
+              if (spec.required) return { ok: false, arg: spec.name, reason: `missing required argument "${spec.name}"` };
+              out[spec.name] = spec.defaultValue;
+            } else {
+              out[spec.name] = tail;
+            }
+            idx = tokens.length;
+            continue;
+          }
+          const token = tokens[idx];
+          if (token === void 0) {
+            if (spec.required) {
+              return { ok: false, arg: spec.name, reason: `missing required argument "${spec.name}"` };
+            }
+            out[spec.name] = spec.defaultValue;
+            continue;
+          }
+          const parsed = coerce(spec, token);
+          if (parsed.ok === false) return { ok: false, arg: spec.name, reason: parsed.reason };
+          out[spec.name] = parsed.value;
+          idx += 1;
+        }
+        return { ok: true, values: out };
+      }
+    };
+  }
+};
+function coerce(spec, token) {
+  switch (spec.kind) {
+    case "string":
+      return { ok: true, value: token };
+    case "integer": {
+      const n = Number(token);
+      if (!Number.isInteger(n)) return { ok: false, reason: `"${token}" is not an integer` };
+      return { ok: true, value: n };
+    }
+    case "number": {
+      const n = Number(token);
+      if (!Number.isFinite(n)) return { ok: false, reason: `"${token}" is not a number` };
+      return { ok: true, value: n };
+    }
+    case "boolean": {
+      const low = token.toLowerCase();
+      if (["true", "1", "yes", "on"].includes(low)) return { ok: true, value: true };
+      if (["false", "0", "no", "off"].includes(low)) return { ok: true, value: false };
+      return { ok: false, reason: `"${token}" is not a boolean` };
+    }
+    case "snowflake": {
+      const id = extractSnowflake(token);
+      if (id === null) return { ok: false, reason: `"${token}" is not a snowflake or mention` };
+      return { ok: true, value: id };
+    }
+    case "duration": {
+      const ms = parseDuration(token);
+      if (ms === null) return { ok: false, reason: `"${token}" is not a duration` };
+      return { ok: true, value: ms };
+    }
+    default:
+      return { ok: false, reason: `unknown arg kind for "${spec.name}"` };
+  }
+}
+function prefixArgs() {
+  return new PrefixArgsBuilder();
+}
+function normalisePayload(render) {
+  if (typeof render.setColor === "function" && typeof render.toJSON === "function") {
+    return { embeds: [render] };
+  }
+  if (Array.isArray(render)) {
+    return { embeds: render };
+  }
+  return render;
+}
+function controlsRow(page, pages, ns, controls, labels) {
+  const buttons = [];
+  if (controls === "first-prev-next-last") {
+    buttons.push(
+      new discord_js.ButtonBuilder().setCustomId(`${ns}:first`).setStyle(discord_js.ButtonStyle.Secondary).setLabel(labels.first).setDisabled(page === 0)
+    );
+  }
+  buttons.push(
+    new discord_js.ButtonBuilder().setCustomId(`${ns}:prev`).setStyle(discord_js.ButtonStyle.Primary).setLabel(labels.prev).setDisabled(page === 0),
+    new discord_js.ButtonBuilder().setCustomId(`${ns}:next`).setStyle(discord_js.ButtonStyle.Primary).setLabel(labels.next).setDisabled(page >= pages - 1)
+  );
+  if (controls === "first-prev-next-last") {
+    buttons.push(
+      new discord_js.ButtonBuilder().setCustomId(`${ns}:last`).setStyle(discord_js.ButtonStyle.Secondary).setLabel(labels.last).setDisabled(page >= pages - 1)
+    );
+  }
+  return new discord_js.ActionRowBuilder().addComponents(...buttons);
+}
+function resolveLabels2(input) {
+  return {
+    first: input?.first ?? "\xAB",
+    prev: input?.prev ?? "\u2039",
+    next: input?.next ?? "\u203A",
+    last: input?.last ?? "\xBB"
+  };
+}
+async function buildPaginatorPage(items, page, options) {
+  const pageSize = options.pageSize ?? 10;
+  const pages = Math.max(1, Math.ceil(items.length / pageSize));
+  const ns = options.namespace ?? "spk-page";
+  const controls = options.controls ?? "prev-next";
+  const labels = resolveLabels2(options.labels);
+  const slice = items.slice(page * pageSize, page * pageSize + pageSize);
+  const body = await options.render(slice, { page, pages });
+  const payload = normalisePayload(body);
+  const components = pages > 1 ? [controlsRow(page, pages, ns, controls, labels)] : [];
+  return { payload: { ...payload, components }, pages };
+}
+async function paginate(interaction, items, options) {
+  const pageSize = options.pageSize ?? 10;
+  const ns = options.namespace ?? "spk-page";
+  const controls = options.controls ?? "prev-next";
+  const labels = resolveLabels2(options.labels);
+  const allowedUser = options.user ?? interaction.user.id;
+  let page = 0;
+  const buildPage = async () => {
+    return buildPaginatorPage(items, page, { ...options, pageSize, namespace: ns, controls, labels });
+  };
+  const { payload: initial, pages } = await buildPage();
+  const sent = interaction.deferred ? await interaction.editReply(initial) : (await interaction.reply({
+    ...initial,
+    flags: options.ephemeral === true ? 64 : void 0
+  }), await interaction.fetchReply());
+  if (pages <= 1) return;
+  const collector = sent.createMessageComponentCollector({
+    componentType: discord_js.ComponentType.Button,
+    time: options.timeoutMs ?? 5 * 6e4,
+    filter: (i) => i.user.id === allowedUser && i.customId.startsWith(`${ns}:`)
+  });
+  collector.on("collect", async (button2) => {
+    const action = button2.customId.slice(ns.length + 1);
+    if (action === "first") page = 0;
+    else if (action === "prev") page = Math.max(0, page - 1);
+    else if (action === "next") page = Math.min(pages - 1, page + 1);
+    else if (action === "last") page = pages - 1;
+    const next = await buildPage();
+    await button2.update(next.payload).catch(() => void 0);
+  });
+  collector.on("end", async () => {
+    const disabledRow = controlsRow(page, pages, ns, controls, labels);
+    for (const c of disabledRow.components) c.setDisabled(true);
+    const { payload: final } = await buildPage();
+    await interaction.editReply({ ...final, components: [disabledRow] }).catch(() => void 0);
+  });
+}
+var STYLE_MAP = {
+  Primary: discord_js.ButtonStyle.Primary,
+  Secondary: discord_js.ButtonStyle.Secondary,
+  Success: discord_js.ButtonStyle.Success,
+  Danger: discord_js.ButtonStyle.Danger
+};
+function clientEmbeds2(client) {
+  return client.embeds ?? defaultEmbeds;
+}
+async function confirm(interaction, options) {
+  const ns = options.namespace ?? "spk-confirm";
+  const confirmLabel = options.confirm?.label ?? "Confirm";
+  const cancelLabel = options.cancel?.label ?? "Cancel";
+  const confirmStyle = STYLE_MAP[options.confirm?.style ?? "Success"];
+  const cancelStyle = STYLE_MAP[options.cancel?.style ?? "Secondary"];
+  const user = options.user ?? interaction.user.id;
+  const ephemeral = options.ephemeral !== false;
+  const embeds = clientEmbeds2(interaction.client);
+  const promptEmbed = embeds.info(
+    options.title !== void 0 ? { title: options.title, description: options.body } : options.body
+  );
+  const row2 = new discord_js.ActionRowBuilder().addComponents(
+    new discord_js.ButtonBuilder().setCustomId(`${ns}:yes`).setLabel(confirmLabel).setStyle(confirmStyle),
+    new discord_js.ButtonBuilder().setCustomId(`${ns}:no`).setLabel(cancelLabel).setStyle(cancelStyle)
+  );
+  const payload = { embeds: [promptEmbed], components: [row2] };
+  const sent = interaction.deferred ? await interaction.editReply(payload) : (await interaction.reply({
+    ...payload,
+    flags: ephemeral ? 64 : void 0
+  }), await interaction.fetchReply());
+  return new Promise((resolve) => {
+    const collector = sent.createMessageComponentCollector({
+      componentType: discord_js.ComponentType.Button,
+      time: options.timeoutMs ?? 3e4,
+      max: 1,
+      filter: (i) => i.user.id === user && i.customId.startsWith(`${ns}:`)
+    });
+    let outcome = null;
+    collector.on("collect", async (button2) => {
+      const action = button2.customId.slice(ns.length + 1);
+      outcome = {
+        confirmed: action === "yes",
+        reason: action === "yes" ? "confirm" : "cancel",
+        interaction: button2
+      };
+      await button2.deferUpdate().catch(() => void 0);
+    });
+    collector.on("end", async () => {
+      for (const c of row2.components) c.setDisabled(true);
+      await interaction.editReply({ embeds: [promptEmbed], components: [row2] }).catch(() => void 0);
+      resolve(outcome ?? { confirmed: false, reason: "timeout" });
+    });
+  });
+}
 var RANK = {
   debug: 10,
   info: 20,
@@ -31,6 +1255,71 @@ function consoleSink(entry) {
   write(line);
   if (entry.error !== void 0) write(entry.error.stack ?? String(entry.error));
 }
+function jsonlSink(path$1, options = {}) {
+  const min = options.minLevel ?? "debug";
+  let dirReady = false;
+  let chain = Promise.resolve();
+  return (entry) => {
+    if (RANK[entry.level] < RANK[min]) return;
+    const record = {
+      ...entry,
+      timestamp: entry.timestamp.toISOString(),
+      error: entry.error ? { name: entry.error.name, message: entry.error.message, stack: entry.error.stack } : void 0
+    };
+    const line = `${JSON.stringify(record)}
+`;
+    chain = chain.then(async () => {
+      try {
+        if (!dirReady) {
+          await promises.mkdir(path.dirname(path$1), { recursive: true });
+          dirReady = true;
+        }
+        await promises.appendFile(path$1, line, "utf8");
+      } catch {
+      }
+    });
+  };
+}
+function webhookSink(options) {
+  const min = options.minLevel ?? "warn";
+  return (entry) => {
+    if (RANK[entry.level] < RANK[min]) return;
+    const color = entry.level === "error" ? 15747655 : entry.level === "warn" ? 16361509 : 3447003;
+    const fields = [];
+    if (entry.scope !== void 0) fields.push({ name: "Scope", value: entry.scope, inline: true });
+    if (entry.data !== void 0) {
+      for (const [k, v] of Object.entries(entry.data)) {
+        fields.push({ name: k, value: formatValue(v).slice(0, 1e3), inline: true });
+      }
+    }
+    const desc = entry.error?.stack !== void 0 ? `${entry.message}
+\`\`\`
+${entry.error.stack.slice(0, 1800)}
+\`\`\`` : entry.message;
+    const body = {
+      username: options.username ?? "spearkit",
+      embeds: [
+        {
+          title: `[${entry.level.toUpperCase()}] ${entry.message.slice(0, 240)}`,
+          description: desc.slice(0, 4e3),
+          color,
+          timestamp: entry.timestamp.toISOString(),
+          fields: fields.slice(0, 25)
+        }
+      ]
+    };
+    void fetch(options.url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body)
+    }).catch(() => void 0);
+  };
+}
+function resolveTransports(options) {
+  if (options.transports !== void 0 && options.transports.length > 0) return options.transports;
+  if (options.sink !== void 0) return [options.sink];
+  return [consoleSink];
+}
 var Logger = class _Logger {
   state;
   /** The scope prefix applied to every entry, if any. */
@@ -38,7 +1327,7 @@ var Logger = class _Logger {
   constructor(options = {}) {
     this.state = {
       threshold: options.level ?? "info",
-      sink: options.sink ?? consoleSink
+      transports: resolveTransports(options)
     };
     this.scope = options.scope;
   }
@@ -51,6 +1340,16 @@ var Logger = class _Logger {
     this.state.threshold = level;
     return this;
   }
+  /** Replace the transport list for this logger and every child sharing its state. */
+  setTransports(transports) {
+    this.state.transports = transports;
+    return this;
+  }
+  /** Append a transport to the existing list. */
+  addTransport(sink) {
+    this.state.transports = [...this.state.transports, sink];
+    return this;
+  }
   /** Whether an entry of `level` would currently be emitted. */
   enabled(level) {
     return RANK[level] >= RANK[this.state.threshold];
@@ -65,14 +1364,20 @@ var Logger = class _Logger {
   /** Emit an entry at an explicit level. */
   log(level, message, options) {
     if (!this.enabled(level)) return;
-    this.state.sink({
+    const entry = {
       level,
       message,
       scope: this.scope,
       timestamp: /* @__PURE__ */ new Date(),
       error: options?.error,
       data: options?.data
-    });
+    };
+    for (const sink of this.state.transports) {
+      try {
+        sink(entry);
+      } catch {
+      }
+    }
   }
   /** Verbose diagnostics, off by default. */
   debug(message, options) {
@@ -165,98 +1470,14 @@ function envRequire(key) {
   if (value === void 0) {
     throw new Error(`spearkit: required environment variable "${key}" is missing or empty`);
   }
-  return value;
-}
-var env = {
-  string: envString,
-  number: envNumber,
-  boolean: envBoolean,
-  require: envRequire
-};
-
-// src/cooldown.ts
-function normalizeCooldown(input) {
-  return typeof input === "number" ? { duration: input } : input;
-}
-function scopeKey(scope, actor) {
-  switch (scope) {
-    case "guild":
-      return `g:${actor.guildId ?? "dm"}`;
-    case "channel":
-      return `c:${actor.channelId ?? "dm"}`;
-    case "global":
-      return "global";
-    case "user":
-      return `u:${actor.userId}`;
-  }
-}
-function effectiveDuration(config, actor) {
-  if (config.exempt?.users?.includes(actor.userId) === true) return null;
-  if (config.exempt?.roles?.some((roleId) => actor.roleIds.includes(roleId)) === true) return null;
-  const userOverride = config.overrides?.users?.[actor.userId];
-  if (userOverride !== void 0) return userOverride;
-  const roleOverrides = config.overrides?.roles;
-  if (roleOverrides !== void 0) {
-    let best;
-    for (const roleId of actor.roleIds) {
-      const candidate = roleOverrides[roleId];
-      if (candidate !== void 0) best = best === void 0 ? candidate : Math.min(best, candidate);
-    }
-    if (best !== void 0) return best;
-  }
-  return config.duration;
-}
-function keyFor(bucket, config, actor) {
-  return `${bucket}|${scopeKey(config.scope ?? "user", actor)}`;
-}
-var CooldownManager = class {
-  hits = /* @__PURE__ */ new Map();
-  /** Number of tracked buckets. */
-  get size() {
-    return this.hits.size;
-  }
-  /**
-   * Check whether `actor` may use `bucket`, recording the use when allowed.
-   * Exempt actors and non-positive durations are always allowed (no record).
-   */
-  consume(bucket, input, actor, now = Date.now()) {
-    const config = normalizeCooldown(input);
-    const duration = effectiveDuration(config, actor);
-    if (duration === null || duration <= 0) return { allowed: true };
-    const key = keyFor(bucket, config, actor);
-    const last = this.hits.get(key);
-    if (last !== void 0 && now - last < duration) {
-      return { allowed: false, remaining: duration - (now - last) };
-    }
-    this.hits.set(key, now);
-    return { allowed: true };
-  }
-  /** Like {@link consume} but never records — a read-only check. */
-  peek(bucket, input, actor, now = Date.now()) {
-    const config = normalizeCooldown(input);
-    const duration = effectiveDuration(config, actor);
-    if (duration === null || duration <= 0) return { allowed: true };
-    const last = this.hits.get(keyFor(bucket, config, actor));
-    if (last !== void 0 && now - last < duration) {
-      return { allowed: false, remaining: duration - (now - last) };
-    }
-    return { allowed: true };
-  }
-  /** Clear a single actor's cooldown for a bucket. Returns whether one existed. */
-  reset(bucket, actor, scope = "user") {
-    return this.hits.delete(`${bucket}|${scopeKey(scope, actor)}`);
-  }
-  /** Drop every tracked cooldown. */
-  clear() {
-    this.hits.clear();
-  }
-};
-function formatCooldownMessage(config, remainingMs) {
-  if (typeof config.message === "function") return config.message(remainingMs);
-  if (typeof config.message === "string") return config.message;
-  const seconds = Math.max(1, Math.ceil(remainingMs / 1e3));
-  return `You're on cooldown \u2014 try again in ${seconds}s.`;
+  return value;
 }
+var env = {
+  string: envString,
+  number: envNumber,
+  boolean: envBoolean,
+  require: envRequire
+};
 
 // src/scheduler.ts
 var ALIASES = {
@@ -349,7 +1570,7 @@ var CronExpression = class {
     const date = new Date(from.getTime());
     date.setSeconds(0, 0);
     date.setMinutes(date.getMinutes() + 1);
-    for (let guard = 0; guard < 1e5; guard++) {
+    for (let guard2 = 0; guard2 < 1e5; guard2++) {
       if (!this.months.has(date.getMonth() + 1)) {
         date.setMonth(date.getMonth() + 1, 1);
         date.setHours(0, 0, 0, 0);
@@ -399,6 +1620,7 @@ var TaskScheduler = class {
   running = false;
   client;
   logger;
+  reconcilers = [];
   /** Number of registered tasks. */
   get size() {
     return this.tasks.size;
@@ -429,12 +1651,93 @@ var TaskScheduler = class {
     this.cancel(name);
     return this.tasks.delete(name);
   }
+  /**
+   * Schedule a one-shot job: run `fn` once after `ms` milliseconds, then forget.
+   * Returns a cancel handle. Replaces hand-rolled `setTimeout` calls for things
+   * like "remind the moderator in 10 minutes if no claim happened".
+   */
+  delay(name, ms, fn) {
+    const key = `delay:${name}`;
+    this.cancel(key);
+    const timer = setTimeout(async () => {
+      this.timers.delete(key);
+      try {
+        await fn();
+      } catch (error) {
+        this.logger?.error(`delay "${name}" failed`, { error: toError(error) });
+      }
+    }, Math.max(0, ms));
+    if (typeof timer.unref === "function") timer.unref();
+    this.timers.set(key, timer);
+    return {
+      cancel: () => {
+        const had = this.timers.has(key);
+        this.cancel(key);
+        return had;
+      }
+    };
+  }
+  /**
+   * Schedule a series of follow-up fires from a single start point. Each
+   * delay is measured from "now"; the callback receives the index of the
+   * fire. Generalises the 10s/30s/60s retry pattern in real bots.
+   */
+  followUp(name, delays, fn) {
+    const keys = delays.map((_, i) => `followUp:${name}:${i}`);
+    for (const key of keys) this.cancel(key);
+    delays.forEach((delay, i) => {
+      const key = keys[i];
+      const timer = setTimeout(async () => {
+        this.timers.delete(key);
+        try {
+          await fn(i);
+        } catch (error) {
+          this.logger?.error(`followUp "${name}" fire ${i} failed`, { error: toError(error) });
+        }
+      }, Math.max(0, delay));
+      if (typeof timer.unref === "function") timer.unref();
+      this.timers.set(key, timer);
+    });
+    return {
+      cancel: () => {
+        let any = false;
+        for (const key of keys) {
+          if (this.timers.has(key)) any = true;
+          this.cancel(key);
+        }
+        return any;
+      }
+    };
+  }
+  /**
+   * Register a once-on-ready reconciler — runs the first time the scheduler
+   * starts (typically when the client becomes ready) and never again. Use
+   * for restart-recovery work like closing orphaned voice sessions or
+   * reapplying cached channel state.
+   */
+  reconcile(name, fn) {
+    if (this.running && this.client !== void 0) {
+      void this.runReconciler(name, fn, this.client);
+    } else {
+      this.reconcilers.push({ name, run: fn });
+    }
+  }
+  async runReconciler(name, run, client) {
+    this.logger?.debug("reconcile", { data: { name } });
+    try {
+      await run(client);
+    } catch (error) {
+      this.logger?.error(`reconciler "${name}" failed`, { error: toError(error) });
+    }
+  }
   /** Start every task. Safe to call once; later calls are ignored. */
   start(client) {
     if (this.running) return;
     this.client = client;
     this.running = true;
     for (const task2 of this.tasks.values()) this.begin(task2);
+    const pending = this.reconcilers.splice(0);
+    for (const { name, run } of pending) void this.runReconciler(name, run, client);
   }
   /** Stop the scheduler and cancel every pending timer. */
   stop() {
@@ -488,28 +1791,33 @@ var TaskScheduler = class {
 
 // src/prefix.ts
 function prefixCommand(config) {
+  const parser = config.args !== void 0 ? config.args(prefixArgs()).compile() : void 0;
   return {
     kind: "prefixCommand",
     name: config.name,
     aliases: config.aliases ?? [],
     description: config.description,
     cooldown: config.cooldown !== void 0 ? normalizeCooldown(config.cooldown) : void 0,
+    guards: config.guards,
+    parser,
     run: async (ctx) => {
       await config.run(ctx);
     }
   };
 }
 var PrefixContext = class {
-  constructor(message, commandName, args, rest) {
+  constructor(message, commandName, args, rest, options = {}) {
     this.message = message;
     this.commandName = commandName;
     this.args = args;
     this.rest = rest;
+    this.options = options;
   }
   message;
   commandName;
   args;
   rest;
+  options;
   get client() {
     return this.message.client;
   }
@@ -579,6 +1887,7 @@ var PrefixRegistry = class {
   cooldowns;
   defaultCooldown;
   errorHandler;
+  defaultGuards = [];
   onUsage;
   /** Configure prefixes and matching behaviour. */
   setOptions(input) {
@@ -601,6 +1910,11 @@ var PrefixRegistry = class {
     this.defaultCooldown = defaultCooldown;
     return this;
   }
+  /** Guards that run before every prefix command's own guards. */
+  setDefaultGuards(guards) {
+    this.defaultGuards = guards;
+    return this;
+  }
   /** Set the handler used when a prefix command throws. */
   onError(handler) {
     this.errorHandler = handler;
@@ -666,12 +1980,44 @@ var PrefixRegistry = class {
         return true;
       }
     }
+    const guards = combineGuards2(this.defaultGuards, command2.guards);
+    if (guards.length > 0) {
+      const guardCtx = guardContextFromMessage(message);
+      const guardResult = await runGuards(guardCtx, guards);
+      if (!guardResult.allowed) {
+        this.logger?.debug("prefix denied", {
+          data: {
+            command: command2.name,
+            user: message.author.id,
+            reason: guardResult.reason ?? ""
+          }
+        });
+        await replyDeniedMessage(message, guardResult.reason);
+        return true;
+      }
+    }
     const args = rest.length > 0 ? rest.split(/\s+/) : [];
+    let options = {};
+    if (command2.parser !== void 0) {
+      const parsed = command2.parser.parse(args, rest);
+      if (!parsed.ok) {
+        this.logger?.debug("prefix arg error", {
+          data: { command: command2.name, user: message.author.id, arg: parsed.arg, reason: parsed.reason }
+        });
+        const embeds = clientEmbeds3(message.client);
+        await message.reply({ embeds: [embeds.error(`Argument \`${parsed.arg}\`: ${parsed.reason}`)] }).catch(() => void 0);
+        return true;
+      }
+      options = parsed.values;
+    }
+    const start = Date.now();
     try {
-      await command2.run(new PrefixContext(message, name, args, rest));
+      await command2.run(new PrefixContext(message, name, args, rest, options));
       this.onUsage?.({
         type: "prefix",
         name: command2.name,
+        outcome: "success",
+        durationMs: Date.now() - start,
         userId: message.author.id,
         userTag: message.author.tag,
         guildId: message.guildId,
@@ -681,11 +2027,46 @@ var PrefixRegistry = class {
     } catch (error) {
       const err = toError(error);
       this.logger?.error(`prefix command "${command2.name}" failed`, { error: err });
+      this.onUsage?.({
+        type: "prefix",
+        name: command2.name,
+        outcome: "error",
+        errorMessage: err.message,
+        durationMs: Date.now() - start,
+        userId: message.author.id,
+        userTag: message.author.tag,
+        guildId: message.guildId,
+        channelId: message.channelId,
+        timestamp: /* @__PURE__ */ new Date()
+      });
       if (this.errorHandler !== void 0) await this.errorHandler(err, message);
     }
     return true;
   }
 };
+function combineGuards2(defaults, own) {
+  if (own === void 0 || own.length === 0) return defaults;
+  if (defaults.length === 0) return own;
+  return [...defaults, ...own];
+}
+function guardContextFromMessage(message) {
+  return {
+    client: message.client,
+    user: message.author,
+    member: message.member,
+    guild: message.guild,
+    guildId: message.guildId,
+    channelId: message.channelId
+  };
+}
+function clientEmbeds3(client) {
+  return client.embeds ?? defaultEmbeds;
+}
+async function replyDeniedMessage(message, reason) {
+  const embeds = clientEmbeds3(message.client);
+  const text = reason ?? "You don't have permission to use this.";
+  await message.reply({ embeds: [embeds.error(text)] }).catch(() => void 0);
+}
 var MemoryUsageStore = class {
   constructor(limit = Number.POSITIVE_INFINITY) {
     this.limit = limit;
@@ -800,107 +2181,6 @@ var UsageTracker = class {
     }
   }
 };
-function withEphemeralFlag(flags) {
-  if (flags == null) return discord_js.MessageFlags.Ephemeral;
-  if (typeof flags === "number" || typeof flags === "bigint") {
-    return Number(flags) | discord_js.MessageFlags.Ephemeral;
-  }
-  if (Array.isArray(flags)) return [...flags, discord_js.MessageFlags.Ephemeral];
-  return [flags, discord_js.MessageFlags.Ephemeral];
-}
-function normalizeReply(input) {
-  if (typeof input === "string") return { content: input };
-  const { ephemeral, ...rest } = input;
-  if (ephemeral) return { ...rest, flags: withEphemeralFlag(rest.flags) };
-  return rest;
-}
-function normalizeEdit(input) {
-  if (typeof input === "string") return { content: input };
-  const { ephemeral: _ephemeral, flags: _flags, ...rest } = input;
-  return rest;
-}
-function asEphemeral(input) {
-  if (typeof input === "string") return { content: input, ephemeral: true };
-  return { ...input, ephemeral: true };
-}
-var BaseContext = class {
-  constructor(interaction) {
-    this.interaction = interaction;
-  }
-  interaction;
-  get client() {
-    return this.interaction.client;
-  }
-  get user() {
-    return this.interaction.user;
-  }
-  get member() {
-    return this.interaction.member;
-  }
-  get guild() {
-    return this.interaction.guild;
-  }
-  get guildId() {
-    return this.interaction.guildId;
-  }
-  get channel() {
-    return this.interaction.channel;
-  }
-  get channelId() {
-    return this.interaction.channelId;
-  }
-  get locale() {
-    return this.interaction.locale;
-  }
-  /** Whether the interaction is already deferred. */
-  get deferred() {
-    return this.interaction.deferred;
-  }
-  /** Whether the interaction already received an initial response. */
-  get replied() {
-    return this.interaction.replied;
-  }
-  /** Send the initial response to the interaction. */
-  reply(input) {
-    return this.interaction.reply(normalizeReply(input));
-  }
-  /** Reply, but always hidden to everyone except the invoking user. */
-  replyEphemeral(input) {
-    return this.reply(asEphemeral(input));
-  }
-  /** Acknowledge now and respond later via {@link editReply}. */
-  defer(options = {}) {
-    return this.interaction.deferReply(
-      options.ephemeral ? { flags: discord_js.MessageFlags.Ephemeral } : {}
-    );
-  }
-  /** Edit the original (or deferred) response. */
-  editReply(input) {
-    return this.interaction.editReply(normalizeEdit(input));
-  }
-  /** Add an additional message after the initial response. */
-  followUp(input) {
-    return this.interaction.followUp(normalizeReply(input));
-  }
-  /**
-   * State-aware send: replies, edits a deferred response, or follows up —
-   * whichever is valid given the current interaction state. The single method
-   * most handlers ever need.
-   */
-  async send(input) {
-    if (this.interaction.deferred) {
-      await this.editReply(input);
-    } else if (this.interaction.replied) {
-      await this.followUp(input);
-    } else {
-      await this.reply(input);
-    }
-  }
-  /** State-aware ephemeral error message. */
-  error(message) {
-    return this.send(asEphemeral(message));
-  }
-};
 function makeOption(type, config) {
   return { type, ...config, required: config.required ?? false };
 }
@@ -1082,6 +2362,8 @@ var SlashCommand = class {
   autocompleter;
   /** Resolved cooldown configuration for this command, if any. */
   cooldown;
+  /** Resolved guard list for this command, if any. */
+  guards;
   /** @internal */
   constructor(spec) {
     this.name = spec.name;
@@ -1090,6 +2372,7 @@ var SlashCommand = class {
     this.executor = spec.executor;
     this.autocompleter = spec.autocompleter;
     this.cooldown = spec.cooldown;
+    this.guards = spec.guards;
   }
   /** Serialise to the discord REST chat-input command payload. */
   toJSON() {
@@ -1124,7 +2407,7 @@ function makeAutocompleter(options) {
     if (!interaction.responded) await ctx.respond(choices);
   };
 }
-function baseJSON(meta, options) {
+function baseJSON2(meta, options) {
   return {
     type: discord_js.ApplicationCommandType.ChatInput,
     name: meta.name,
@@ -1164,11 +2447,12 @@ function command(config) {
   };
   return new SlashCommand({
     name: config.name,
-    json: baseJSON(config, leafOptionsJSON(options)),
+    json: baseJSON2(config, leafOptionsJSON(options)),
     hasAutocomplete: optionsHaveAutocomplete(options),
     executor,
     autocompleter: makeAutocompleter(options),
-    cooldown: config.cooldown !== void 0 ? normalizeCooldown(config.cooldown) : void 0
+    cooldown: config.cooldown !== void 0 ? normalizeCooldown(config.cooldown) : void 0,
+    guards: config.guards
   });
 }
 function subcommand(config) {
@@ -1236,11 +2520,12 @@ function commandGroup(config) {
   };
   return new SlashCommand({
     name: config.name,
-    json: baseJSON(config, options),
+    json: baseJSON2(config, options),
     hasAutocomplete,
     executor,
     autocompleter,
-    cooldown: config.cooldown !== void 0 ? normalizeCooldown(config.cooldown) : void 0
+    cooldown: config.cooldown !== void 0 ? normalizeCooldown(config.cooldown) : void 0,
+    guards: config.guards
   });
 }
 var CommandRegistry = class {
@@ -1249,6 +2534,7 @@ var CommandRegistry = class {
   logger;
   cooldowns;
   defaultCooldown;
+  defaultGuards = [];
   onUsage;
   /** Register one or more commands. Later registrations override by name. */
   add(...commands) {
@@ -1291,6 +2577,11 @@ var CommandRegistry = class {
     this.defaultCooldown = defaultCooldown;
     return this;
   }
+  /** Guards that run before every command's own guards. */
+  setDefaultGuards(guards) {
+    this.defaultGuards = guards;
+    return this;
+  }
   /** Attach a hook called after each successful command execution. */
   setUsageHook(hook) {
     this.onUsage = hook;
@@ -1309,17 +2600,35 @@ var CommandRegistry = class {
     });
     const cooldown = command2.cooldown ?? this.defaultCooldown;
     if (cooldown !== void 0 && this.cooldowns !== void 0) {
-      const result = this.cooldowns.consume(command2.name, cooldown, actorOf(interaction));
+      const result = this.cooldowns.consume(command2.name, cooldown, actorOf2(interaction));
       if (!result.allowed) {
         await this.replyCooldown(interaction, cooldown, result.remaining);
         return;
       }
     }
+    const guards = combineGuards3(this.defaultGuards, command2.guards);
+    if (guards.length > 0) {
+      const guardResult = await runGuards(interaction, guards);
+      if (!guardResult.allowed) {
+        this.logger?.debug("command denied", {
+          data: {
+            command: command2.name,
+            user: interaction.user.id,
+            reason: guardResult.reason ?? ""
+          }
+        });
+        await this.replyDenied(interaction, guardResult.reason);
+        return;
+      }
+    }
+    const start = Date.now();
     try {
       await command2.execute(interaction);
       this.onUsage?.({
         type: "command",
         name: command2.name,
+        outcome: "success",
+        durationMs: Date.now() - start,
         userId: interaction.user.id,
         userTag: interaction.user.tag,
         guildId: interaction.guildId,
@@ -1328,6 +2637,18 @@ var CommandRegistry = class {
       });
     } catch (error) {
       const err = error instanceof Error ? error : new Error(String(error));
+      this.onUsage?.({
+        type: "command",
+        name: command2.name,
+        outcome: "error",
+        errorMessage: err.message,
+        durationMs: Date.now() - start,
+        userId: interaction.user.id,
+        userTag: interaction.user.tag,
+        guildId: interaction.guildId,
+        channelId: interaction.channelId,
+        timestamp: /* @__PURE__ */ new Date()
+      });
       if (this.errorHandler !== void 0) {
         await this.errorHandler(err, interaction);
       } else {
@@ -1389,8 +2710,28 @@ var CommandRegistry = class {
     } catch {
     }
   }
+  async replyDenied(interaction, reason) {
+    const embeds = clientEmbeds4(interaction.client);
+    const text = reason ?? "You don't have permission to use this.";
+    try {
+      const payload = { embeds: [embeds.error(text)], flags: discord_js.MessageFlags.Ephemeral };
+      if (interaction.deferred) await interaction.editReply({ embeds: payload.embeds });
+      else if (interaction.replied) await interaction.followUp(payload);
+      else await interaction.reply(payload);
+    } catch {
+    }
+  }
 };
-function actorOf(interaction) {
+function combineGuards3(defaults, own) {
+  if (own === void 0 || own.length === 0) return defaults;
+  if (defaults.length === 0) return own;
+  return [...defaults, ...own];
+}
+function clientEmbeds4(client) {
+  const host = client;
+  return host.embeds ?? defaultEmbeds;
+}
+function actorOf2(interaction) {
   const member = interaction.member;
   let roleIds = [];
   if (member !== null) {
@@ -1642,6 +2983,7 @@ var ComponentRegistry = class {
   errorHandler;
   logger;
   onUsage;
+  defaultGuards = [];
   /** Register one or more components. Later registrations override by namespace. */
   add(...defs) {
     for (const def of defs) {
@@ -1686,6 +3028,11 @@ var ComponentRegistry = class {
     this.onUsage = hook;
     return this;
   }
+  /** Guards that run before every component's own guards. */
+  setDefaultGuards(guards) {
+    this.defaultGuards = guards;
+    return this;
+  }
   /** Total number of registered components. */
   get size() {
     return this.buttons.size + this.stringSelects.size + this.userSelects.size + this.roleSelects.size + this.channelSelects.size + this.mentionableSelects.size + this.modals.size;
@@ -1721,13 +3068,27 @@ var ComponentRegistry = class {
   async exec(route, interaction) {
     if (route === void 0) return false;
     this.logger?.debug("component", { data: { customId: interaction.customId } });
+    const guards = combineGuards4(this.defaultGuards, route.guards);
+    if (guards.length > 0) {
+      const guardResult = await runGuards(interaction, guards);
+      if (!guardResult.allowed) {
+        this.logger?.debug("component denied", {
+          data: { customId: interaction.customId, reason: guardResult.reason ?? "" }
+        });
+        await replyDeniedComponent(interaction, guardResult.reason);
+        return true;
+      }
+    }
     const { values } = parseCustomId(interaction.customId);
     const params = paramsFromValues(route.paramNames, values);
+    const start = Date.now();
     try {
       await route.handle(interaction, params);
       this.onUsage?.({
         type: "component",
         name: route.namespace,
+        outcome: "success",
+        durationMs: Date.now() - start,
         userId: interaction.user.id,
         userTag: interaction.user.tag,
         guildId: interaction.guildId,
@@ -1736,6 +3097,18 @@ var ComponentRegistry = class {
       });
     } catch (error) {
       const err = toError3(error);
+      this.onUsage?.({
+        type: "component",
+        name: route.namespace,
+        outcome: "error",
+        errorMessage: err.message,
+        durationMs: Date.now() - start,
+        userId: interaction.user.id,
+        userTag: interaction.user.tag,
+        guildId: interaction.guildId,
+        channelId: interaction.channelId,
+        timestamp: /* @__PURE__ */ new Date()
+      });
       if (this.errorHandler !== void 0) {
         await this.errorHandler(err, interaction);
       } else {
@@ -1751,6 +3124,25 @@ var ComponentRegistry = class {
 function namespaceOf(customId) {
   return parseCustomId(customId).namespace;
 }
+function combineGuards4(defaults, own) {
+  if (own === void 0 || own.length === 0) return defaults;
+  if (defaults.length === 0) return own;
+  return [...defaults, ...own];
+}
+function clientEmbeds5(client) {
+  return client.embeds ?? defaultEmbeds;
+}
+async function replyDeniedComponent(interaction, reason) {
+  const embeds = clientEmbeds5(interaction.client);
+  const text = reason ?? "You don't have permission to use this.";
+  try {
+    const payload = { embeds: [embeds.error(text)], flags: discord_js.MessageFlags.Ephemeral };
+    if (interaction.deferred) await interaction.editReply({ embeds: payload.embeds });
+    else if (interaction.replied) await interaction.followUp(payload);
+    else await interaction.reply(payload);
+  } catch {
+  }
+}
 function resolveButtonStyle(input) {
   if (input === void 0) return discord_js.ButtonStyle.Secondary;
   return typeof input === "number" ? input : discord_js.ButtonStyle[input];
@@ -1762,6 +3154,7 @@ function button(config) {
     kind: "button",
     namespace: compiled.namespace,
     paramNames: compiled.paramNames,
+    guards: config.guards,
     async handle(interaction, params) {
       await config.run(new ButtonContext(interaction, params));
     },
@@ -1794,6 +3187,7 @@ function stringSelect(config) {
     kind: "stringSelect",
     namespace: compiled.namespace,
     paramNames: compiled.paramNames,
+    guards: config.guards,
     async handle(interaction, params) {
       await config.run(new StringSelectContext(interaction, params));
     },
@@ -1811,6 +3205,7 @@ function userSelect(config) {
     kind: "userSelect",
     namespace: compiled.namespace,
     paramNames: compiled.paramNames,
+    guards: config.guards,
     async handle(interaction, params) {
       await config.run(new UserSelectContext(interaction, params));
     },
@@ -1828,6 +3223,7 @@ function roleSelect(config) {
     kind: "roleSelect",
     namespace: compiled.namespace,
     paramNames: compiled.paramNames,
+    guards: config.guards,
     async handle(interaction, params) {
       await config.run(new RoleSelectContext(interaction, params));
     },
@@ -1845,6 +3241,7 @@ function channelSelect(config) {
     kind: "channelSelect",
     namespace: compiled.namespace,
     paramNames: compiled.paramNames,
+    guards: config.guards,
     async handle(interaction, params) {
       await config.run(new ChannelSelectContext(interaction, params));
     },
@@ -1863,6 +3260,7 @@ function mentionableSelect(config) {
     kind: "mentionableSelect",
     namespace: compiled.namespace,
     paramNames: compiled.paramNames,
+    guards: config.guards,
     async handle(interaction, params) {
       await config.run(new MentionableSelectContext(interaction, params));
     },
@@ -1905,6 +3303,7 @@ function modal(config) {
     kind: "modal",
     namespace: compiled.namespace,
     paramNames: compiled.paramNames,
+    guards: config.guards,
     async handle(interaction, params) {
       const fields = {};
       for (const key of fieldKeys) {
@@ -2011,40 +3410,54 @@ var SpearClient = class extends discord_js.Client {
   prefix = new PrefixRegistry();
   /** Usage tracker: records who used what to a store and/or a Discord channel. */
   usage = new UsageTracker();
+  /** Preset embed factory used by `ctx.error/success/info/warn` and available to your code. */
+  embeds;
+  /** User- and message-context-menu command registry. */
+  contextMenus = new ContextMenuRegistry();
   envConfig;
   constructor(options = {}) {
-    const { intents, logger, dotenv, cooldown, prefix, usage, ...rest } = options;
+    const { intents, logger, dotenv, cooldown, prefix, usage, embeds, guards, ...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);
-    this.commands.setLogger(this.logger.child("commands"));
     const defaultCooldown = cooldown !== void 0 ? normalizeCooldown(cooldown) : void 0;
+    this.commands.setLogger(this.logger.child("commands"));
     this.commands.setCooldowns(this.cooldowns, defaultCooldown);
     this.components.setLogger(this.logger.child("components"));
-    this.events.attachAll(this);
-    this.on("interactionCreate", (interaction) => this.route(interaction));
-    this.on("error", (error) => this.logger.error("client error", { error: toError(error) }));
-    this.scheduler.setLogger(this.logger.child("scheduler"));
-    this.once("clientReady", () => this.scheduler.start(this));
+    this.contextMenus.setLogger(this.logger.child("contextMenus"));
+    this.contextMenus.setCooldowns(this.cooldowns, defaultCooldown);
     this.prefix.setLogger(this.logger.child("prefix"));
     this.prefix.setCooldowns(this.cooldowns, defaultCooldown);
     if (prefix !== void 0) this.prefix.setOptions(prefix);
-    this.on("messageCreate", (message) => {
-      void this.prefix.handle(message);
-    });
+    this.scheduler.setLogger(this.logger.child("scheduler"));
+    if (guards !== void 0 && guards.length > 0) {
+      this.commands.setDefaultGuards(guards);
+      this.contextMenus.setDefaultGuards(guards);
+      this.components.setDefaultGuards(guards);
+      this.prefix.setDefaultGuards(guards);
+    }
     this.usage.setClient(this).setLogger(this.logger.child("usage"));
     if (usage !== void 0) {
       if (usage.store !== void 0) this.usage.setStore(usage.store);
       if (usage.channel !== void 0) this.usage.reportTo(usage.channel, usage.format);
       const onUsage = (event2) => this.usage.track(event2);
       this.commands.setUsageHook(onUsage);
+      this.contextMenus.setUsageHook(onUsage);
       this.components.setUsageHook(onUsage);
       this.prefix.setUsageHook(onUsage);
     }
+    this.events.attachAll(this);
+    this.on("interactionCreate", (interaction) => this.route(interaction));
+    this.on("error", (error) => this.logger.error("client error", { error: toError(error) }));
+    this.once("clientReady", () => this.scheduler.start(this));
+    this.on("messageCreate", (message) => {
+      void this.prefix.handle(message);
+    });
   }
   /**
-   * Register commands, events and components in one call. Each item is routed
-   * to the matching registry based on its kind.
+   * Register commands, events, components, scheduled tasks, prefix commands
+   * and context menus in one call. Each item is routed to its matching registry.
    */
   register(...items) {
     for (const item of items) {
@@ -2056,6 +3469,10 @@ var SpearClient = class extends discord_js.Client {
         this.scheduler.add(item);
       } else if (item.kind === "prefixCommand") {
         this.prefix.add(item);
+      } else if (item.kind === "userMenu") {
+        this.contextMenus.add(item);
+      } else if (item.kind === "messageMenu") {
+        this.contextMenus.add(item);
       } else {
         this.components.add(item);
       }
@@ -2090,8 +3507,9 @@ var SpearClient = class extends discord_js.Client {
     return this;
   }
   /**
-   * Push the registered slash commands to discord using the client's own
-   * authenticated REST connection. Call after the client is ready.
+   * Push the registered slash commands to Discord using the client's REST
+   * connection. Slash-only — use {@link deployAllCommands} to include context
+   * menus in the same request.
    */
   async deployCommands(options = {}) {
     const applicationId = this.application?.id ?? this.user?.id;
@@ -2100,14 +3518,36 @@ var SpearClient = class extends discord_js.Client {
     }
     return this.commands.deploy({ rest: this.rest, applicationId, guildId: options.guildId });
   }
-  async route(interaction) {
-    if (interaction.isChatInputCommand()) {
-      await this.commands.handle(interaction);
-    } else if (interaction.isAutocomplete()) {
-      await this.commands.handleAutocomplete(interaction);
-    } else {
-      await this.components.handle(interaction);
+  /**
+   * Deploy slash commands AND context menus together to Discord in a single
+   * PUT. Use this once you mix `userCommand` / `messageCommand` with `command`.
+   */
+  /**
+   * Deploy slash commands AND context menus together. Supports a `diff`
+   * strategy that fetches the remote set first and skips the PUT when
+   * nothing changed, and a `dryRun` flag that returns the body without
+   * touching Discord (perfect for CI deploy gates).
+   *
+   * @returns the API's DeployResult on PUT, or a skipped report when
+   * `dryRun: true` is set OR `strategy: "diff"` finds no changes.
+   */
+  async deployAllCommands(options = {}) {
+    const applicationId = options.applicationId ?? this.application?.id ?? this.user?.id;
+    if (applicationId == null) {
+      throw new Error("spearkit: deployAllCommands() must run after the client is ready");
+    }
+    const body = [...this.commands.toJSON(), ...this.contextMenus.toJSON()];
+    const route = options.guildId !== void 0 ? discord_js.Routes.applicationGuildCommands(applicationId, options.guildId) : discord_js.Routes.applicationCommands(applicationId);
+    if (options.dryRun === true) {
+      return { skipped: true, reason: "dry-run", body };
+    }
+    if (options.strategy === "diff") {
+      const remote = await this.rest.get(route);
+      if (commandsEqual(body, remote)) {
+        return { skipped: true, reason: "no-changes", body };
+      }
     }
+    return await this.rest.put(route, { body });
   }
   /** Define and register a scheduled task in one call. */
   schedule(config) {
@@ -2120,7 +3560,60 @@ var SpearClient = class extends discord_js.Client {
     this.scheduler.stop();
     await super.destroy();
   }
+  async route(interaction) {
+    if (interaction.isChatInputCommand()) {
+      await this.commands.handle(interaction);
+    } else if (interaction.isAutocomplete()) {
+      await this.commands.handleAutocomplete(interaction);
+    } else if (interaction.isUserContextMenuCommand()) {
+      await this.contextMenus.handleUser(interaction);
+    } else if (interaction.isMessageContextMenuCommand()) {
+      await this.contextMenus.handleMessage(interaction);
+    } else {
+      await this.components.handle(interaction);
+    }
+  }
 };
+function commandsEqual(local, remote) {
+  if (local.length !== remote.length) return false;
+  const lset = new Set(local.map(commandHash));
+  for (const r of remote) {
+    if (!lset.has(commandHash(r))) return false;
+  }
+  return true;
+}
+function commandHash(cmd) {
+  const c = cmd;
+  return JSON.stringify({
+    name: c.name,
+    type: c.type ?? 1,
+    description: c.description ?? "",
+    nsfw: c.nsfw === true,
+    default_member_permissions: c.default_member_permissions ?? null,
+    contexts: Array.isArray(c.contexts) ? [...c.contexts].sort((a, b) => a - b) : null,
+    options: normaliseOptions(c.options)
+  });
+}
+function normaliseOptions(options) {
+  if (!Array.isArray(options)) return [];
+  return options.map((o) => {
+    const opt = o;
+    return {
+      name: opt.name,
+      type: opt.type,
+      description: opt.description ?? "",
+      required: opt.required === true,
+      choices: Array.isArray(opt.choices) ? [...opt.choices].map((ch) => ({ name: ch.name, value: ch.value })).sort((a, b) => String(a.name).localeCompare(String(b.name))) : null,
+      options: normaliseOptions(opt.options),
+      channel_types: Array.isArray(opt.channel_types) ? [...opt.channel_types].sort((a, b) => a - b) : null,
+      min_value: opt.min_value ?? null,
+      max_value: opt.max_value ?? null,
+      min_length: opt.min_length ?? null,
+      max_length: opt.max_length ?? null,
+      autocomplete: opt.autocomplete === true
+    };
+  }).sort((a, b) => String(a.name).localeCompare(String(b.name)));
+}
 
 // src/plugin.ts
 function definePlugin(plugin) {
@@ -2134,17 +3627,25 @@ exports.ChannelSelectContext = ChannelSelectContext;
 exports.CommandContext = CommandContext;
 exports.CommandRegistry = CommandRegistry;
 exports.ComponentRegistry = ComponentRegistry;
+exports.ContextMenuRegistry = ContextMenuRegistry;
 exports.CooldownManager = CooldownManager;
 exports.CronExpression = CronExpression;
+exports.DEFAULT_EMBED_COLORS = DEFAULT_EMBED_COLORS;
+exports.DEFAULT_EMBED_ICONS = DEFAULT_EMBED_ICONS;
+exports.Embeds = Embeds;
 exports.EventRegistry = EventRegistry;
 exports.Intents = Intents;
 exports.JsonFileUsageStore = JsonFileUsageStore;
+exports.KeyedLock = KeyedLock;
 exports.Logger = Logger;
 exports.MAX_CUSTOM_ID_LENGTH = MAX_CUSTOM_ID_LENGTH;
+exports.MemoryCache = MemoryCache;
 exports.MemoryUsageStore = MemoryUsageStore;
 exports.MentionableSelectContext = MentionableSelectContext;
 exports.MessageComponentContext = MessageComponentContext;
+exports.MessageContextMenuContext = MessageContextMenuContext;
 exports.ModalContext = ModalContext;
+exports.PrefixArgsBuilder = PrefixArgsBuilder;
 exports.PrefixContext = PrefixContext;
 exports.PrefixRegistry = PrefixRegistry;
 exports.RoleSelectContext = RoleSelectContext;
@@ -2153,39 +3654,74 @@ exports.SpearClient = SpearClient;
 exports.StringSelectContext = StringSelectContext;
 exports.TaskScheduler = TaskScheduler;
 exports.UsageTracker = UsageTracker;
+exports.UserContextMenuContext = UserContextMenuContext;
 exports.UserSelectContext = UserSelectContext;
 exports.asEphemeral = asEphemeral;
 exports.buildCustomId = buildCustomId;
+exports.buildPaginatorPage = buildPaginatorPage;
 exports.button = button;
 exports.channelSelect = channelSelect;
 exports.collectModules = collectModules;
 exports.command = command;
 exports.commandGroup = commandGroup;
 exports.compilePattern = compilePattern;
+exports.confirm = confirm;
 exports.consoleSink = consoleSink;
+exports.createCache = createCache;
 exports.cron = cron;
+exports.defaultEmbeds = defaultEmbeds;
 exports.definePlugin = definePlugin;
+exports.denied = denied;
+exports.discordTimestamp = discordTimestamp;
+exports.dmOnly = dmOnly;
 exports.effectiveDuration = effectiveDuration;
 exports.env = env;
 exports.event = event;
+exports.fetchChannel = fetchChannel;
+exports.fetchGuild = fetchGuild;
+exports.fetchMember = fetchMember;
+exports.fetchMessage = fetchMessage;
+exports.fetchRole = fetchRole;
+exports.fetchUser = fetchUser;
 exports.formatCooldownMessage = formatCooldownMessage;
+exports.formatDuration = formatDuration;
 exports.formatUsage = formatUsage;
+exports.guard = guard;
+exports.guildOnly = guildOnly;
+exports.jsonlSink = jsonlSink;
 exports.linkButton = linkButton;
+exports.loadConfig = loadConfig;
+exports.loadConfigAsync = loadConfigAsync;
 exports.loadEnv = loadEnv;
 exports.loadInto = loadInto;
+exports.lookup = lookup;
+exports.lookupOptional = lookupOptional;
 exports.mentionableSelect = mentionableSelect;
+exports.messageCommand = messageCommand;
 exports.modal = modal;
 exports.normalizeCooldown = normalizeCooldown;
 exports.normalizeReply = normalizeReply;
 exports.option = option;
 exports.optionsHaveAutocomplete = optionsHaveAutocomplete;
+exports.paginate = paginate;
 exports.paramsFromValues = paramsFromValues;
 exports.parseCustomId = parseCustomId;
+exports.parseDuration = parseDuration;
 exports.parseEnv = parseEnv;
+exports.prefixArgs = prefixArgs;
 exports.prefixCommand = prefixCommand;
 exports.readOption = readOption;
+exports.relativeTimestamp = relativeTimestamp;
+exports.requireAllRoles = requireAllRoles;
+exports.requireAnyRole = requireAnyRole;
+exports.requireBotPermissions = requireBotPermissions;
+exports.requireOwner = requireOwner;
+exports.requireUserPermissions = requireUserPermissions;
 exports.roleSelect = roleSelect;
 exports.row = row;
+exports.runGuards = runGuards;
+exports.safeFetch = safeFetch;
+exports.safeTry = safeTry;
 exports.stringSelect = stringSelect;
 exports.subcommand = subcommand;
 exports.subcommandGroup = subcommandGroup;
@@ -2193,7 +3729,10 @@ exports.task = task;
 exports.textInput = textInput;
 exports.toAPIOption = toAPIOption;
 exports.toError = toError;
+exports.userCommand = userCommand;
 exports.userSelect = userSelect;
+exports.webhookSink = webhookSink;
+exports.withSafeTimeout = withSafeTimeout;
 Object.keys(discord_js).forEach(function (k) {
   if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
     enumerable: true,