spearkit 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,7 +1,413 @@
 import * as discord_js from 'discord.js';
-import { RepliableInteraction, InteractionReplyOptions, InteractionResponse, Message, AutocompleteInteraction, ChatInputCommandInteraction, JSONEncodable, APIModalInteractionResponseCallbackData, ModalComponentData, ModalBuilder, APIApplicationCommandChannelOption, CommandInteractionOption, Attachment, ApplicationCommandOptionType, LocalizationMap, Awaitable, APIApplicationCommandBasicOption, PermissionResolvable, RESTPostAPIChatInputApplicationCommandsJSONBody, RESTPostAPIApplicationCommandsJSONBody, REST, RESTPutAPIApplicationCommandsResult, RESTPutAPIApplicationGuildCommandsResult, ClientEvents, Client, ButtonInteraction, StringSelectMenuInteraction, UserSelectMenuInteraction, RoleSelectMenuInteraction, ChannelSelectMenuInteraction, MentionableSelectMenuInteraction, InteractionUpdateOptions, ModalSubmitInteraction, Interaction, ButtonBuilder, ButtonStyle, ComponentEmojiResolvable, ChannelSelectMenuBuilder, MentionableSelectMenuBuilder, TextInputStyle, RoleSelectMenuBuilder, StringSelectMenuBuilder, SelectMenuComponentOptionData, UserSelectMenuBuilder, ChannelType, MessageActionRowComponentBuilder, ActionRowBuilder, GatewayIntentBits, ClientOptions } from 'discord.js';
+import { APIEmbedField, APIEmbedFooter, APIEmbedAuthor, EmbedBuilder, Client, Channel, Guild, GuildMember, MessageManager, Message, Role, User, APIInteractionGuildMember, Awaitable, PermissionResolvable, RepliableInteraction, InteractionReplyOptions, InteractionResponse, APIApplicationCommandChannelOption, CommandInteractionOption, Attachment, ApplicationCommandOptionType, LocalizationMap, ChatInputCommandInteraction, APIApplicationCommandBasicOption, AutocompleteInteraction, JSONEncodable, APIModalInteractionResponseCallbackData, ModalComponentData, ModalBuilder, RESTPostAPIChatInputApplicationCommandsJSONBody, RESTPostAPIApplicationCommandsJSONBody, REST, RESTPutAPIApplicationCommandsResult, RESTPutAPIApplicationGuildCommandsResult, ClientEvents, ButtonInteraction, ChannelSelectMenuInteraction, StringSelectMenuInteraction, UserSelectMenuInteraction, RoleSelectMenuInteraction, MentionableSelectMenuInteraction, ModalSubmitInteraction, Interaction, MessagePayload, MessageReplyOptions, MessageCreateOptions, GatewayIntentBits, ClientOptions, RESTPostAPIContextMenuApplicationCommandsJSONBody, UserContextMenuCommandInteraction, MessageContextMenuCommandInteraction, BaseMessageOptions, InteractionUpdateOptions, ButtonBuilder, ButtonStyle, ComponentEmojiResolvable, ChannelSelectMenuBuilder, MentionableSelectMenuBuilder, TextInputStyle, RoleSelectMenuBuilder, StringSelectMenuBuilder, SelectMenuComponentOptionData, UserSelectMenuBuilder, ChannelType, MessageActionRowComponentBuilder, ActionRowBuilder } from 'discord.js';
 export * from 'discord.js';
 
+/**
+ * Preset embeds — `error`, `success`, `info`, `warn` — with consistent colors
+ * and icons so every reply in your bot looks the same. The client owns one as
+ * `client.embeds` and the context preset methods (`ctx.success(...)` etc.) use
+ * it; you can also call `embeds.error(...)` directly to build an embed for
+ * `channel.send({ embeds: [...] })`.
+ */
+
+/** Color in `0xRRGGBB` form for each preset level. */
+interface EmbedColors {
+    error: number;
+    success: number;
+    info: number;
+    warn: number;
+}
+/** Icon glyph prepended to the description of each preset. Pass `""` to drop. */
+interface EmbedIcons {
+    error: string;
+    success: string;
+    info: string;
+    warn: string;
+}
+/** Construction options for {@link Embeds}. Missing fields fall back to defaults. */
+interface EmbedsOptions {
+    /** Per-level color overrides. */
+    colors?: Partial<EmbedColors>;
+    /** Per-level icon overrides; pass `""` to drop the prefix for a level. */
+    icons?: Partial<EmbedIcons>;
+}
+/** Shape accepted by every preset: a plain string or a structured body. */
+type EmbedPresetInput = string | {
+    title?: string;
+    description?: string;
+    fields?: readonly APIEmbedField[];
+    footer?: APIEmbedFooter;
+    author?: APIEmbedAuthor;
+    url?: string;
+    timestamp?: Date | number | string;
+    thumbnail?: {
+        url: string;
+    };
+    image?: {
+        url: string;
+    };
+};
+/** One of the four built-in preset levels. */
+type EmbedLevel = "error" | "success" | "info" | "warn";
+/** Discord-ish defaults: red / green / blue / yellow + ⛔ ✅ ℹ️ ⚠️. */
+declare const DEFAULT_EMBED_COLORS: EmbedColors;
+/** Default icons: warning / check / info / triangle. */
+declare const DEFAULT_EMBED_ICONS: EmbedIcons;
+/**
+ * Builds preset embeds with consistent colors and icons.
+ *
+ * @example
+ * ```ts
+ * const embeds = new Embeds({ colors: { success: 0x00ff88 } });
+ * await channel.send({ embeds: [embeds.success("Saved.")] });
+ * ```
+ */
+declare class Embeds {
+    /** The resolved colors for every preset. */
+    readonly colors: EmbedColors;
+    /** The resolved icons for every preset. */
+    readonly icons: EmbedIcons;
+    constructor(options?: EmbedsOptions);
+    /** Red preset — something went wrong. */
+    error(input: EmbedPresetInput): EmbedBuilder;
+    /** Green preset — something succeeded. */
+    success(input: EmbedPresetInput): EmbedBuilder;
+    /** Blue preset — neutral information. */
+    info(input: EmbedPresetInput): EmbedBuilder;
+    /** Yellow preset — caution. */
+    warn(input: EmbedPresetInput): EmbedBuilder;
+    /** Build an embed at a chosen level. */
+    build(level: EmbedLevel, input: EmbedPresetInput): EmbedBuilder;
+}
+/** The shared default factory — used by contexts when the client has none. */
+declare const defaultEmbeds: Embeds;
+
+/**
+ * Keyed in-memory async lock (mutex) with TTL.
+ *
+ * Prevents two handlers from mutating the same resource concurrently — e.g.
+ * the same ticket id being claimed twice, or a user opening a ticket while
+ * another button click is still creating one. Hold leases are auto-expired so
+ * a forgotten `release()` cannot deadlock the process forever.
+ */
+/** Construction options for {@link KeyedLock}. */
+interface KeyedLockOptions {
+    /** Maximum lifetime (ms) of a held lock before it auto-expires. Default `60_000`. */
+    ttl?: number;
+    /** Sweep interval (ms) for expired-but-not-released locks. `0` disables sweeping. */
+    sweep?: number;
+}
+/** Release a previously-acquired lease. Idempotent — safe to call multiple times. */
+type LockRelease = () => void;
+/**
+ * Acquire, release and run-while-locked operations keyed on an arbitrary string.
+ *
+ * @example
+ * ```ts
+ * const locks = new KeyedLock();
+ * const result = await locks.run(`ticket:${id}:claim`, async () => {
+ *   // …mutate ticket atomically…
+ *   return "ok";
+ * }, { onBusy: () => "busy" });
+ * ```
+ */
+declare class KeyedLock {
+    private readonly entries;
+    private readonly defaultTtl;
+    private readonly sweepTimer?;
+    constructor(options?: KeyedLockOptions);
+    /** Try to acquire `key`. Returns a release function, or `null` if already held. */
+    tryAcquire(key: string, ttl?: number): LockRelease | null;
+    /** Whether `key` is currently held and not expired. */
+    isHeld(key: string): boolean;
+    /**
+     * 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.
+     */
+    run<T>(key: string, fn: () => Promise<T> | T, options?: {
+        ttl?: number;
+        onBusy?: () => Promise<T> | T;
+    }): Promise<T | undefined>;
+    /** Number of currently-tracked leases (including expired-but-unswept). */
+    get size(): number;
+    /** Drop all known leases and stop the sweep timer. */
+    dispose(): void;
+    /** Manually remove a single key without running anything. */
+    forget(key: string): boolean;
+    private sweep;
+}
+
+/**
+ * Cache-first, timeout-bounded fetch helpers that resolve to `T | null` instead
+ * of throwing. They replace the `.catch(() => null)` pattern repeated 30+ times
+ * in production bots (member/channel/message/user/guild/role lookups that may
+ * 404, rate-limit, or block startup if awaited indefinitely).
+ */
+
+/** Shared options for every safe-fetch helper. */
+interface SafeFetchOptions {
+    /** Use the cache when present and not `force`. Default `true`. */
+    cache?: boolean;
+    /** Bypass the cache and force a REST hit. Default `false`. */
+    force?: boolean;
+    /** Resolve to `null` if Discord takes longer than this (ms). Default `5000`. */
+    timeoutMs?: number;
+}
+/** Resolve a guild member with a cache-hit fast path. Returns `null` on failure. */
+declare function fetchMember(guild: Guild | null | undefined, userId: string | null | undefined, options?: SafeFetchOptions): Promise<GuildMember | null>;
+/** Resolve a channel by id from the client. Returns `null` on failure. */
+declare function fetchChannel(client: Client | null | undefined, channelId: string | null | undefined, options?: SafeFetchOptions): Promise<Channel | null>;
+/** Resolve a message id in a given channel's messages manager. */
+declare function fetchMessage(messages: MessageManager | null | undefined, messageId: string | null | undefined, options?: SafeFetchOptions): Promise<Message | null>;
+/** Resolve a user by id from the client. Returns `null` on failure. */
+declare function fetchUser(client: Client | null | undefined, userId: string | null | undefined, options?: SafeFetchOptions): Promise<User | null>;
+/** Resolve a guild by id from the client. Returns `null` on failure. */
+declare function fetchGuild(client: Client | null | undefined, guildId: string | null | undefined, options?: SafeFetchOptions): Promise<Guild | null>;
+/** Resolve a role id from a guild's roles manager. Returns `null` on failure. */
+declare function fetchRole(guild: Guild | null | undefined, roleId: string | null | undefined, options?: SafeFetchOptions): Promise<Role | null>;
+/**
+ * Wrap an arbitrary best-effort operation so a failure resolves to `null`
+ * instead of throwing. Useful for sends/deletes whose outcome is non-critical.
+ *
+ * @example
+ * ```ts
+ * await safeTry(() => message.delete());
+ * ```
+ */
+declare function safeTry<T>(op: () => Promise<T> | T): Promise<T | null>;
+/** Time-bound an arbitrary promise; resolves to `null` on timeout or rejection. */
+declare function withSafeTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T | null>;
+/** Cache-first, timeout-bounded fetch helpers grouped for ergonomic imports. */
+declare const safeFetch: {
+    readonly member: typeof fetchMember;
+    readonly channel: typeof fetchChannel;
+    readonly message: typeof fetchMessage;
+    readonly user: typeof fetchUser;
+    readonly guild: typeof fetchGuild;
+    readonly role: typeof fetchRole;
+    readonly try: typeof safeTry;
+};
+
+/**
+ * Locale-aware duration formatter, duration parser and Discord timestamp
+ * helpers. Replaces the dozens of inline `Math.floor(s/86400)`/`X gün Y saat`
+ * and `<t:${secs}:R>` snippets in production bots, including the duplicate
+ * `formatTimeInTurkish`-style helpers duplicated across many bot command files.
+ */
+/** Discord timestamp style: `t/T/d/D/f/F/R`. */
+type DiscordTimestampStyle = "t" | "T" | "d" | "D" | "f" | "F" | "R";
+type DurationUnit = "week" | "day" | "hour" | "minute" | "second";
+interface UnitLabels {
+    week: [string, string];
+    day: [string, string];
+    hour: [string, string];
+    minute: [string, string];
+    second: [string, string];
+    separator: string;
+    zero: string;
+}
+/** Options for {@link formatDuration}. */
+interface FormatDurationOptions {
+    /** Locale label set: `"en"`, `"en-US"`, `"tr"`, `"tr-TR"`, or a custom set. */
+    locale?: string | UnitLabels;
+    /** How many non-zero units to keep. Default `2`. Pass `Infinity` to keep all. */
+    largest?: number;
+    /** Subset of units to consider (in order: week → second). */
+    units?: readonly DurationUnit[];
+}
+/**
+ * Format a millisecond duration into human-readable text.
+ *
+ * @example
+ * ```ts
+ * formatDuration(3_725_000);                         // "1 hour 2 minutes"
+ * formatDuration(3_725_000, { locale: "tr" });       // "1 saat 2 dakika"
+ * formatDuration(86_400_000 * 9, { largest: 3 });    // "1 week 2 days"
+ * ```
+ */
+declare function formatDuration(ms: number, options?: FormatDurationOptions): string;
+/**
+ * Parse a human duration like `"1h30m"`, `"2 days"`, `"1 saat 30 dakika"` or
+ * `"5000ms"` into milliseconds. Returns `null` if nothing parseable was found.
+ *
+ * @example
+ * ```ts
+ * parseDuration("1h30m");      // 5_400_000
+ * parseDuration("1 saat");     // 3_600_000
+ * parseDuration("oops");       // null
+ * ```
+ */
+declare function parseDuration(input: string): number | null;
+/**
+ * Render a Discord-flavoured timestamp tag (`<t:1234:R>`).
+ *
+ * Styles: `t` short time, `T` long time, `d` short date, `D` long date,
+ * `f` short date/time (default), `F` long date/time, `R` relative.
+ *
+ * @example
+ * ```ts
+ * discordTimestamp(date);                  // <t:1234:f>
+ * discordTimestamp(date, "R");              // <t:1234:R>
+ * discordTimestamp(Date.now() + 60_000, "R"); // <t:..:R>
+ * ```
+ */
+declare function discordTimestamp(date: Date | number, style?: DiscordTimestampStyle): string;
+/** Short-hand for the relative Discord timestamp (`R` style). */
+declare function relativeTimestamp(date: Date | number): string;
+
+/**
+ * Pluggable cache abstraction with TTL, counters and rate-limit primitives.
+ *
+ * The {@link CacheStore} interface lets you swap a {@link MemoryCache} for any
+ * external backend (Redis, Memcached, your DB) without changing call sites —
+ * production bots commonly start with memory and graduate to Redis as load
+ * grows. Counters and fixed-window rate limits live on the same surface so the
+ * three patterns repeated in real bots (TTL cache, daily counter, per-user
+ * rate limit) share one API.
+ */
+/** Result of a fixed-window {@link CacheStore.rateLimit} hit. */
+interface RateLimitResult {
+    /** `true` if this hit was within the window's budget. */
+    allowed: boolean;
+    /** Remaining hits in the current window (`0` once `allowed` is false). */
+    remaining: number;
+    /** Epoch ms at which the current window resets. */
+    resetAt: number;
+}
+/** Options accepted by every write helper. */
+interface CacheSetOptions {
+    /** Time-to-live in milliseconds. `undefined` means never expire. */
+    ttl?: number;
+}
+/** A swappable cache backend. All operations are async to allow remote stores. */
+interface CacheStore {
+    /** Read a previously set value, or `undefined` if missing/expired. */
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    /** Write a value, optionally with a TTL in ms. */
+    set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void>;
+    /** Remove a key. Resolves to `true` if it existed. */
+    delete(key: string): Promise<boolean>;
+    /** Whether a non-expired key is present. */
+    has(key: string): Promise<boolean>;
+    /** Atomically increment a numeric counter. Returns the new value. */
+    increment(key: string, delta?: number, options?: CacheSetOptions): Promise<number>;
+    /** Fixed-window rate limit hit. Atomic per key. */
+    rateLimit(key: string, options: {
+        limit: number;
+        windowMs: number;
+    }): Promise<RateLimitResult>;
+    /** Drop every entry. */
+    clear(): Promise<void>;
+}
+/** In-memory implementation of {@link CacheStore}. Lazy TTL expiration. */
+declare class MemoryCache implements CacheStore {
+    private readonly store;
+    /** Total number of stored (possibly expired) entries — primarily for tests. */
+    get size(): number;
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    has(key: string): Promise<boolean>;
+    increment(key: string, delta?: number, options?: CacheSetOptions): Promise<number>;
+    rateLimit(key: string, options: {
+        limit: number;
+        windowMs: number;
+    }): Promise<RateLimitResult>;
+    clear(): Promise<void>;
+}
+/** Convenience factory: returns a default in-memory {@link CacheStore}. */
+declare function createCache(): CacheStore;
+
+/** Options accepted by {@link loadConfig} / {@link loadConfigAsync}. */
+interface LoadConfigOptions<T> {
+    /** Absolute or cwd-relative path to the config file. */
+    file: string;
+    /** Custom parser. Default `JSON.parse`. Pass `JSON5.parse` (etc.) for other formats. */
+    parser?: (text: string) => unknown;
+    /** Validation function — receives the parsed value, returns the typed config. */
+    schema?: (value: unknown) => T;
+    /** File encoding. Default `"utf8"`. */
+    encoding?: BufferEncoding;
+}
+/** Synchronously read + parse + (optionally) validate a config file. */
+declare function loadConfig<T = unknown>(options: LoadConfigOptions<T>): T;
+/** Asynchronous variant of {@link loadConfig}. */
+declare function loadConfigAsync<T = unknown>(options: LoadConfigOptions<T>): Promise<T>;
+/**
+ * Build a typed lookup over a `Record<key, value>` table. Throws on missing
+ * keys so config typos surface at startup, not at use.
+ *
+ * @example
+ * ```ts
+ * const roles = lookup(config.roles, "role");
+ * const modId = roles("moderator"); // string; throws if "moderator" is absent
+ * ```
+ */
+declare function lookup<K extends string, V>(table: Readonly<Record<K, V>>, resourceName?: string): (key: K) => V;
+/** Build a non-throwing lookup that returns `undefined` for missing keys. */
+declare function lookupOptional<K extends string, V>(table: Readonly<Record<K, V>>): (key: K) => V | undefined;
+
+/**
+ * Declarative preconditions ("guards") that run before a command, component
+ * or prefix-command handler. Replaces the role/permission/guild-only/owner
+ * checks repeated 127+ times across production bots — `member.roles.cache.some(...)`,
+ * `member.permissions.has(...)`, `if (!message.guild) return`, ownership and
+ * target-hierarchy checks — with a composable predicate pipeline.
+ *
+ * Attach guards on a command (`command({ guards: [...] })`), on a component
+ * (`button({ guards: [...] })`), on a prefix command, or once on the client
+ * for everything (`new SpearClient({ guards: [...] })`). On denial, spearkit
+ * replies with an ephemeral error embed and skips the handler.
+ */
+
+/**
+ * Minimal context a guard reads. Every spearkit handler (slash/prefix/component
+ * /modal) already exposes these — guards work uniformly across all of them.
+ */
+interface GuardContext {
+    readonly client: Client;
+    readonly user: User;
+    readonly member: GuildMember | APIInteractionGuildMember | null;
+    readonly guild: Guild | null;
+    readonly guildId: string | null;
+    readonly channelId: string | null;
+}
+/** A guard's outcome. `true` = pass; `false`/`{ allowed: false, reason? }` = deny. */
+type GuardResult = boolean | {
+    allowed: false;
+    reason?: string;
+};
+/** A precondition evaluated before a handler runs. */
+type Guard<TCtx extends GuardContext = GuardContext> = (ctx: TCtx) => Awaitable<GuardResult>;
+/** Sugar: build a denial result with an explanation. */
+declare function denied(reason?: string): GuardResult;
+/** The resolved outcome of running a list of guards. */
+type RunGuardsResult = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string | undefined;
+};
+/** Run guards in order, short-circuiting on the first denial. */
+declare function runGuards<TCtx extends GuardContext>(ctx: TCtx, guards: readonly Guard<TCtx>[] | undefined): Promise<RunGuardsResult>;
+/** Require the interaction/message to come from inside a guild. */
+declare function guildOnly(reason?: string): Guard;
+/** Require the interaction/message to come from a DM. */
+declare function dmOnly(reason?: string): Guard;
+/** Require the invoking member to hold ANY of these role ids. */
+declare function requireAnyRole(roleIds: readonly string[], reason?: string): Guard;
+/** Require the invoking member to hold EVERY one of these role ids. */
+declare function requireAllRoles(roleIds: readonly string[], reason?: string): Guard;
+/** Require the invoking user to be one of `ownerIds` ("bot owners"). */
+declare function requireOwner(ownerIds: readonly string[], reason?: string): Guard;
+/** Require the invoking member to hold a Discord permission flag. */
+declare function requireUserPermissions(permission: PermissionResolvable, reason?: string): Guard;
+/** Require the BOT's own member to hold a Discord permission flag. */
+declare function requireBotPermissions(permission: PermissionResolvable, reason?: string): Guard;
+/** Inline custom predicate; sugar so a one-off check still types as a Guard. */
+declare function guard<TCtx extends GuardContext = GuardContext>(predicate: Guard<TCtx>): Guard<TCtx>;
+
 /** Reply options with an ergonomic `ephemeral` shortcut (mapped to flags). */
 type ReplyData = InteractionReplyOptions & {
     ephemeral?: boolean;
@@ -50,45 +456,223 @@ declare abstract class BaseContext<I extends RepliableInteraction = RepliableInt
      * most handlers ever need.
      */
     send(input: ReplyInput): Promise<void>;
-    /** State-aware ephemeral error message. */
-    error(message: string): Promise<void>;
+    /** Get the configured {@link Embeds} factory — `client.embeds` or the default. */
+    protected getEmbeds(): Embeds;
+    /** State-aware send of a red error embed. Defaults to ephemeral. */
+    error(input: EmbedPresetInput, options?: {
+        ephemeral?: boolean;
+    }): Promise<void>;
+    /** State-aware send of a green success embed. */
+    success(input: EmbedPresetInput, options?: {
+        ephemeral?: boolean;
+    }): Promise<void>;
+    /** State-aware send of a blue info embed. */
+    info(input: EmbedPresetInput, options?: {
+        ephemeral?: boolean;
+    }): Promise<void>;
+    /** State-aware send of a yellow warn embed. */
+    warn(input: EmbedPresetInput, options?: {
+        ephemeral?: boolean;
+    }): Promise<void>;
+    /** Initial-reply variant of {@link error} (always `reply`, never `editReply`/`followUp`). */
+    replyError(input: EmbedPresetInput, options?: {
+        ephemeral?: boolean;
+    }): Promise<InteractionResponse<boolean>>;
+    /** Initial-reply variant of {@link success}. */
+    replySuccess(input: EmbedPresetInput, options?: {
+        ephemeral?: boolean;
+    }): Promise<InteractionResponse<boolean>>;
+    /** Initial-reply variant of {@link info}. */
+    replyInfo(input: EmbedPresetInput, options?: {
+        ephemeral?: boolean;
+    }): Promise<InteractionResponse<boolean>>;
+    /** Initial-reply variant of {@link warn}. */
+    replyWarn(input: EmbedPresetInput, options?: {
+        ephemeral?: boolean;
+    }): Promise<InteractionResponse<boolean>>;
+    private sendPreset;
+    private replyPreset;
 }
 
 /**
- * The handler argument for a slash command. Wraps the discord.js interaction
- * and exposes the resolved, fully-typed {@link options}.
+ * Rate-limit commands per user, per role, per guild, per channel or globally.
+ *
+ * A cooldown is described by a {@link CooldownConfig}: a base `duration`, the
+ * `scope` it is keyed on, an `exempt` set (users/roles that never wait) and
+ * per-user / per-role `overrides` (different durations for specific ids). Set a
+ * default on the client (applies to every command) and/or per command.
  */
-declare class CommandContext<O extends OptionMap = OptionMap> extends BaseContext<ChatInputCommandInteraction> {
-    /** Resolved option values, typed from the command's `options` map. */
-    readonly options: ResolvedOptions<O>;
-    constructor(interaction: ChatInputCommandInteraction, 
-    /** Resolved option values, typed from the command's `options` map. */
-    options: ResolvedOptions<O>);
-    get commandName(): string;
-    /** The invoked subcommand name, if any. */
-    get subcommand(): string | null;
-    /** Present a modal to the user in response to this command. */
-    showModal(modal: JSONEncodable<APIModalInteractionResponseCallbackData> | ModalComponentData | ModalBuilder): Promise<void>;
+/** What a cooldown is bucketed against. Default `"user"`. */
+type CooldownScope = "user" | "guild" | "channel" | "global";
+/** Users and roles that bypass a cooldown entirely. */
+interface CooldownExemptions {
+    /** User ids that never wait. */
+    users?: readonly string[];
+    /** Role ids whose members never wait. */
+    roles?: readonly string[];
+}
+/** Per-user and per-role duration overrides (milliseconds; `0` disables). */
+interface CooldownOverrides {
+    /** `userId -> duration ms`. */
+    users?: Readonly<Record<string, number>>;
+    /** `roleId -> duration ms`. The most lenient matching role wins. */
+    roles?: Readonly<Record<string, number>>;
 }
+/** Full cooldown description. */
+interface CooldownConfig {
+    /** Base cooldown in milliseconds. */
+    duration: number;
+    /** What the cooldown is keyed on. Default `"user"`. */
+    scope?: CooldownScope;
+    /** Users/roles that bypass the cooldown. */
+    exempt?: CooldownExemptions;
+    /** Per-user / per-role duration overrides. */
+    overrides?: CooldownOverrides;
+    /** Message shown when blocked. A function receives the remaining ms. */
+    message?: string | ((remainingMs: number) => string);
+}
+/** A `CooldownConfig`, or a bare duration in milliseconds. */
+type CooldownInput = number | CooldownConfig;
+/** Normalise a {@link CooldownInput} to a full {@link CooldownConfig}. */
+declare function normalizeCooldown(input: CooldownInput): CooldownConfig;
+/** The actor a cooldown is evaluated for. */
+interface CooldownActor {
+    userId: string;
+    roleIds: readonly string[];
+    guildId: string | null;
+    channelId: string | null;
+}
+/** Whether an action is allowed now, and if not, how long remains. */
+type CooldownResult = {
+    allowed: true;
+} | {
+    allowed: false;
+    remaining: number;
+};
 /**
- * The handler argument for autocomplete requests. Provides the focused value
- * and a typed {@link respond} helper.
+ * Resolve the cooldown an actor should serve. `null` means exempt (no
+ * cooldown). Otherwise a duration in milliseconds (which may be `0`).
  */
-declare class AutocompleteContext {
-    readonly interaction: AutocompleteInteraction;
-    constructor(interaction: AutocompleteInteraction);
-    get client(): discord_js.Client<true>;
-    get user(): discord_js.User;
-    get guild(): discord_js.Guild | null;
-    get guildId(): string | null;
-    get commandName(): string;
-    /** Name of the option currently being completed. */
-    get focusedName(): string;
-    /** Current partial value typed by the user. */
-    get value(): string;
-    /** Send autocomplete suggestions (capped at the discord limit of 25). */
-    respond(choices: OptionChoice<string | number>[]): Promise<void>;
+declare function effectiveDuration(config: CooldownConfig, actor: CooldownActor): number | null;
+/**
+ * Tracks last-use timestamps and decides whether an action is allowed.
+ * Stateful but dependency-free; one instance is shared on `client.cooldowns`.
+ */
+declare class CooldownManager {
+    private readonly hits;
+    /** Number of tracked buckets. */
+    get size(): number;
+    /**
+     * Check whether `actor` may use `bucket`, recording the use when allowed.
+     * Exempt actors and non-positive durations are always allowed (no record).
+     */
+    consume(bucket: string, input: CooldownInput, actor: CooldownActor, now?: number): CooldownResult;
+    /** Like {@link consume} but never records — a read-only check. */
+    peek(bucket: string, input: CooldownInput, actor: CooldownActor, now?: number): CooldownResult;
+    /** Clear a single actor's cooldown for a bucket. Returns whether one existed. */
+    reset(bucket: string, actor: CooldownActor, scope?: CooldownScope): boolean;
+    /** Drop every tracked cooldown. */
+    clear(): void;
+}
+/** Build the user-facing message for a blocked action. */
+declare function formatCooldownMessage(config: CooldownConfig, remainingMs: number): string;
+
+/** Severity of a log entry, lowest to highest. */
+type LogLevel = "debug" | "info" | "warn" | "error";
+/** A minimum severity to emit, or `"silent"` to suppress everything. */
+type LogThreshold = LogLevel | "silent";
+/** A primitive metadata value attached to a log entry. */
+type LogValue = string | number | boolean | bigint | null | undefined;
+/** Extra context passed alongside a log message. */
+interface LogOptions {
+    /** An error to attach; the default sink renders its stack. */
+    error?: Error;
+    /** Structured key/value metadata. */
+    data?: Record<string, LogValue>;
+}
+/** A fully-resolved record handed to a {@link LogSink}. */
+interface LogEntry {
+    readonly level: LogLevel;
+    readonly message: string;
+    readonly scope?: string;
+    readonly timestamp: Date;
+    readonly error?: Error;
+    readonly data?: Readonly<Record<string, LogValue>>;
+}
+/** Receives every entry at or above the configured threshold. */
+type LogSink = (entry: LogEntry) => void;
+/** Construction options for a {@link Logger}. */
+interface LoggerOptions {
+    /** Minimum level to emit. Default `"info"`. */
+    level?: LogThreshold;
+    /** Single transport — shorthand for `transports: [sink]`. */
+    sink?: LogSink;
+    /** Multiple transports. If set, takes precedence over `sink`. */
+    transports?: readonly LogSink[];
+    /** A scope prefix for every entry (e.g. `"commands"`). */
+    scope?: string;
+}
+/** Default sink: human-readable lines to the console (stderr for warn/error). */
+declare function consoleSink(entry: LogEntry): void;
+/**
+ * JSON-lines sink: appends one JSON object per entry to `path`. Fire-and-forget;
+ * filesystem errors are swallowed so logging never crashes the bot.
+ */
+declare function jsonlSink(path: string, options?: {
+    minLevel?: LogLevel;
+}): LogSink;
+/**
+ * Discord-webhook sink: POSTs an embed to a webhook URL for entries at or
+ * above `minLevel` (default `"warn"`). Useful for sending errors to a private
+ * `#bot-errors` channel.
+ */
+declare function webhookSink(options: {
+    url: string;
+    minLevel?: LogLevel;
+    username?: string;
+}): LogSink;
+/**
+ * A leveled, scoped logger. Create one directly or read `client.logger`.
+ * {@link child} loggers share the parent's threshold and transports, so calling
+ * {@link setLevel} on any of them affects the whole tree.
+ *
+ * @example
+ * ```ts
+ * const log = new Logger({ level: "debug", transports: [consoleSink, jsonlSink("./logs/bot.jsonl")] });
+ * log.info("ready", { data: { shard: 0 } });
+ * log.child("commands").error("handler failed", { error });
+ * ```
+ */
+declare class Logger {
+    private state;
+    /** The scope prefix applied to every entry, if any. */
+    readonly scope?: string;
+    constructor(options?: LoggerOptions);
+    /** The current minimum threshold. */
+    get level(): LogThreshold;
+    /** Change the threshold for this logger and every child sharing its state. */
+    setLevel(level: LogThreshold): this;
+    /** Replace the transport list for this logger and every child sharing its state. */
+    setTransports(transports: readonly LogSink[]): this;
+    /** Append a transport to the existing list. */
+    addTransport(sink: LogSink): this;
+    /** Whether an entry of `level` would currently be emitted. */
+    enabled(level: LogLevel): boolean;
+    /** A child logger with an extra scope segment, sharing this logger's state. */
+    child(scope: string): Logger;
+    /** Emit an entry at an explicit level. */
+    log(level: LogLevel, message: string, options?: LogOptions): void;
+    /** Verbose diagnostics, off by default. */
+    debug(message: string, options?: LogOptions): void;
+    /** Normal operational messages. */
+    info(message: string, options?: LogOptions): void;
+    /** Recoverable problems worth attention. */
+    warn(message: string, options?: LogOptions): void;
+    /** Failures. Attach the cause via `{ error }`. */
+    error(message: string, options?: LogOptions): void;
 }
+/** Coerce an unknown thrown value into an {@link Error}. */
+declare function toError(value: unknown): Error;
 
 /**
  * Resolved runtime value types, derived directly from discord.js' option
@@ -202,6 +786,42 @@ declare function readOption(resolver: OptionReader, name: string, def: AnyOption
 /** True if any option in the map declares an autocomplete handler. */
 declare function optionsHaveAutocomplete(options: OptionMap): boolean;
 
+/**
+ * The handler argument for a slash command. Wraps the discord.js interaction
+ * and exposes the resolved, fully-typed {@link options}.
+ */
+declare class CommandContext<O extends OptionMap = OptionMap> extends BaseContext<ChatInputCommandInteraction> {
+    /** Resolved option values, typed from the command's `options` map. */
+    readonly options: ResolvedOptions<O>;
+    constructor(interaction: ChatInputCommandInteraction, 
+    /** Resolved option values, typed from the command's `options` map. */
+    options: ResolvedOptions<O>);
+    get commandName(): string;
+    /** The invoked subcommand name, if any. */
+    get subcommand(): string | null;
+    /** Present a modal to the user in response to this command. */
+    showModal(modal: JSONEncodable<APIModalInteractionResponseCallbackData> | ModalComponentData | ModalBuilder): Promise<void>;
+}
+/**
+ * The handler argument for autocomplete requests. Provides the focused value
+ * and a typed {@link respond} helper.
+ */
+declare class AutocompleteContext {
+    readonly interaction: AutocompleteInteraction;
+    constructor(interaction: AutocompleteInteraction);
+    get client(): discord_js.Client<true>;
+    get user(): discord_js.User;
+    get guild(): discord_js.Guild | null;
+    get guildId(): string | null;
+    get commandName(): string;
+    /** Name of the option currently being completed. */
+    get focusedName(): string;
+    /** Current partial value typed by the user. */
+    get value(): string;
+    /** Send autocomplete suggestions (capped at the discord limit of 25). */
+    respond(choices: OptionChoice<string | number>[]): Promise<void>;
+}
+
 /** Metadata shared by every kind of command. */
 interface CommonMeta {
     /** Permissions a member must have by default to see/use the command. */
@@ -212,6 +832,10 @@ interface CommonMeta {
     guildOnly?: boolean;
     nameLocalizations?: LocalizationMap;
     descriptionLocalizations?: LocalizationMap;
+    /** Rate-limit this command. A number is a duration in ms; see {@link CooldownConfig}. */
+    cooldown?: CooldownInput;
+    /** Preconditions evaluated before the handler runs. */
+    guards?: readonly Guard[];
 }
 /** Configuration for a leaf (non-subcommand) slash command. */
 interface CommandConfig<O extends OptionMap, R> extends CommonMeta {
@@ -264,6 +888,8 @@ interface SlashCommandSpec {
     hasAutocomplete: boolean;
     executor: (interaction: ChatInputCommandInteraction) => Promise<void>;
     autocompleter: (interaction: AutocompleteInteraction) => Promise<void>;
+    cooldown?: CooldownConfig;
+    guards?: readonly Guard[];
 }
 /**
  * A registered slash command. Serialises itself for the discord REST API and
@@ -278,6 +904,10 @@ declare class SlashCommand {
     private readonly json;
     private readonly executor;
     private readonly autocompleter;
+    /** Resolved cooldown configuration for this command, if any. */
+    readonly cooldown?: CooldownConfig;
+    /** Resolved guard list for this command, if any. */
+    readonly guards?: readonly Guard[];
     /** @internal */
     constructor(spec: SlashCommandSpec);
     /** Serialise to the discord REST chat-input command payload. */
@@ -327,6 +957,11 @@ type DeployResult = RESTPutAPIApplicationCommandsResult | RESTPutAPIApplicationG
 declare class CommandRegistry {
     private readonly commands;
     private errorHandler?;
+    private logger?;
+    private cooldowns?;
+    private defaultCooldown?;
+    private defaultGuards;
+    private onUsage?;
     /** Register one or more commands. Later registrations override by name. */
     add(...commands: SlashCommand[]): this;
     /** Remove a command by name. */
@@ -341,6 +976,14 @@ declare class CommandRegistry {
     get size(): number;
     /** Set the handler used when a command throws. */
     onError(handler: CommandErrorHandler): this;
+    /** Attach a logger used for dispatch tracing (debug level). */
+    setLogger(logger: Logger): this;
+    /** Wire a shared cooldown manager and an optional default cooldown for every command. */
+    setCooldowns(manager: CooldownManager, defaultCooldown?: CooldownConfig): this;
+    /** Guards that run before every command's own guards. */
+    setDefaultGuards(guards: readonly Guard[]): this;
+    /** Attach a hook called after each successful command execution. */
+    setUsageHook(hook: (event: UsageEvent) => void): this;
     /** Serialise every command to discord REST payloads. */
     toJSON(): RESTPostAPIApplicationCommandsJSONBody[];
     /** Dispatch an incoming chat-input interaction to its command. */
@@ -355,6 +998,8 @@ declare class CommandRegistry {
      */
     deploy(options: DeployOptions): Promise<DeployResult>;
     private defaultErrorReply;
+    private replyCooldown;
+    private replyDenied;
 }
 
 /** A typed handler for a discord.js client event. */
@@ -407,127 +1052,16 @@ declare class EventRegistry {
     detachAll(client: Client): void;
 }
 
-/**
- * Typed custom-id codec.
- *
- * Patterns follow the grammar `namespace(:{param})*`, e.g. `"vote"` or
- * `"vote:{choice}"` or `"page:{id}:{dir}"`. The `namespace` is the routing key;
- * each `{param}` becomes a positional, percent-escaped value in the encoded id.
- * Param names are recovered at the type level so handlers get a typed `params`
- * object and `build()` requires exactly the right params.
- */
-/** Names of the `{param}` placeholders inside a pattern. */
-type ParamNames<S extends string> = S extends `${string}{${infer Name}}${infer Rest}` ? Name | ParamNames<Rest> : never;
-/** The params object a pattern resolves to (every value is a string). */
-type Params<S extends string> = {
-    [K in ParamNames<S>]: string;
-};
-/** Arguments `build()` accepts: none when the pattern has no params. */
-type BuildArgs<S extends string> = [ParamNames<S>] extends [never] ? [] : [params: Params<S>];
-/** The discord custom-id length limit. */
-declare const MAX_CUSTOM_ID_LENGTH = 100;
-/** A compiled pattern: its routing namespace and ordered param names. */
-interface CompiledPattern {
-    readonly pattern: string;
+/** Shared shape of every routed component. */
+interface RouteBase {
     readonly namespace: string;
     readonly paramNames: readonly string[];
+    readonly guards?: readonly Guard[];
 }
-/** Compile and validate a custom-id pattern. Throws on malformed input. */
-declare function compilePattern(pattern: string): CompiledPattern;
-/** Build a concrete custom-id from a compiled pattern and its params. */
-declare function buildCustomId(compiled: CompiledPattern, params: Readonly<Record<string, string>>): string;
-/** The namespace + raw values parsed out of an incoming custom-id. */
-interface ParsedCustomId {
-    readonly namespace: string;
-    readonly values: readonly string[];
-}
-/** Parse an incoming custom-id into its namespace and decoded values. */
-declare function parseCustomId(customId: string): ParsedCustomId;
-/** Map ordered values onto their param names. */
-declare function paramsFromValues(paramNames: readonly string[], values: readonly string[]): Record<string, string>;
-
-type UpdateInput = string | InteractionUpdateOptions;
-/** The concrete message-component interaction types (button + every select). */
-type AnyComponentInteraction = ButtonInteraction | StringSelectMenuInteraction | UserSelectMenuInteraction | RoleSelectMenuInteraction | ChannelSelectMenuInteraction | MentionableSelectMenuInteraction;
-/**
- * Base context for message-component interactions (buttons and selects).
- * Adds the component-only `update`/`deferUpdate`/`showModal` helpers and the
- * routed, typed {@link params}.
- */
-declare class MessageComponentContext<P, I extends AnyComponentInteraction = AnyComponentInteraction> extends BaseContext<I> {
-    /** Params extracted from the custom-id pattern. */
-    readonly params: P;
-    constructor(interaction: I, 
-    /** Params extracted from the custom-id pattern. */
-    params: P);
-    /** The raw custom-id that triggered this interaction. */
-    get customId(): string;
-    /** The message the component lives on. */
-    get message(): discord_js.Message<boolean>;
-    /** Edit the message this component belongs to. */
-    update(input: UpdateInput): Promise<void>;
-    /** Acknowledge the interaction without editing the message yet. */
-    deferUpdate(): Promise<void>;
-    /** Open a modal in response to this component. */
-    showModal(modal: JSONEncodable<APIModalInteractionResponseCallbackData> | ModalComponentData | ModalBuilder): Promise<void>;
-}
-/** Context for a button click. */
-declare class ButtonContext<P = Record<string, never>> extends MessageComponentContext<P, ButtonInteraction> {
-}
-/** Context for a string select; exposes the chosen {@link values}. */
-declare class StringSelectContext<P = Record<string, never>> extends MessageComponentContext<P, StringSelectMenuInteraction> {
-    /** All selected values. */
-    get values(): string[];
-    /** The first selected value, or `undefined` if none. */
-    get value(): string | undefined;
-}
-/** Context for a user select; exposes selected ids, users and members. */
-declare class UserSelectContext<P = Record<string, never>> extends MessageComponentContext<P, UserSelectMenuInteraction> {
-    get values(): string[];
-    get users(): discord_js.Collection<string, discord_js.User>;
-    get members(): discord_js.Collection<string, discord_js.GuildMember | discord_js.APIGuildMember>;
-}
-/** Context for a role select. */
-declare class RoleSelectContext<P = Record<string, never>> extends MessageComponentContext<P, RoleSelectMenuInteraction> {
-    get values(): string[];
-    get roles(): discord_js.Collection<string, discord_js.Role | discord_js.APIRole>;
-}
-/** Context for a channel select. */
-declare class ChannelSelectContext<P = Record<string, never>> extends MessageComponentContext<P, ChannelSelectMenuInteraction> {
-    get values(): string[];
-    get channels(): discord_js.Collection<string, discord_js.Channel | discord_js.APIChannel>;
-}
-/** Context for a mentionable (user + role) select. */
-declare class MentionableSelectContext<P = Record<string, never>> extends MessageComponentContext<P, MentionableSelectMenuInteraction> {
-    get values(): string[];
-    get users(): discord_js.Collection<string, discord_js.User>;
-    get roles(): discord_js.Collection<string, discord_js.Role | discord_js.APIRole>;
-    get members(): discord_js.Collection<string, discord_js.GuildMember | discord_js.APIGuildMember>;
-}
-/**
- * Context for a submitted modal. Exposes the routed {@link params} plus the
- * resolved text-input {@link fields}, keyed by the field names you declared.
- */
-declare class ModalContext<P, F extends string = string> extends BaseContext<ModalSubmitInteraction> {
-    readonly params: P;
-    /** Submitted values, keyed by the field names from your modal definition. */
-    readonly fields: Record<F, string>;
-    constructor(interaction: ModalSubmitInteraction, params: P, 
-    /** Submitted values, keyed by the field names from your modal definition. */
-    fields: Record<F, string>);
-    /** The raw custom-id that triggered this modal submission. */
-    get customId(): string;
-}
-
-/** Shared shape of every routed component. */
-interface RouteBase {
-    readonly namespace: string;
-    readonly paramNames: readonly string[];
-}
-/** Routing entry for a button. */
-interface ButtonRoute extends RouteBase {
-    readonly kind: "button";
-    handle(interaction: ButtonInteraction, params: Record<string, string>): Promise<void>;
+/** Routing entry for a button. */
+interface ButtonRoute extends RouteBase {
+    readonly kind: "button";
+    handle(interaction: ButtonInteraction, params: Record<string, string>): Promise<void>;
 }
 /** Routing entry for a string select. */
 interface StringSelectRoute extends RouteBase {
@@ -577,10 +1111,19 @@ declare class ComponentRegistry {
     private readonly mentionableSelects;
     private readonly modals;
     private errorHandler?;
+    private logger?;
+    private onUsage?;
+    private defaultGuards;
     /** Register one or more components. Later registrations override by namespace. */
     add(...defs: ComponentDef[]): this;
     /** Set the handler used when a component throws. */
     onError(handler: ComponentErrorHandler): this;
+    /** Attach a logger used for dispatch tracing (debug level). */
+    setLogger(logger: Logger): this;
+    /** Attach a hook called after each successful component handler run. */
+    setUsageHook(hook: (event: UsageEvent) => void): this;
+    /** Guards that run before every component's own guards. */
+    setDefaultGuards(guards: readonly Guard[]): this;
     /** Total number of registered components. */
     get size(): number;
     /**
@@ -591,6 +1134,962 @@ declare class ComponentRegistry {
     private exec;
 }
 
+/**
+ * A spearkit plugin: a named, reusable bundle of commands, events and components.
+ * Its {@link setup} runs once when added to a client via `client.use(plugin)`.
+ */
+interface SpearPlugin {
+    readonly name: string;
+    setup(client: SpearClient): Awaitable<void>;
+}
+/** Identity helper that gives a plugin object its type and editor hints. */
+declare function definePlugin(plugin: SpearPlugin): SpearPlugin;
+
+/** Options for the directory loader. */
+interface LoadOptions {
+    /** File extensions to import. Default: `.js`, `.mjs`, `.cjs`. */
+    extensions?: readonly string[];
+    /** Recurse into subdirectories. Default: `true`. */
+    recursive?: boolean;
+}
+/**
+ * Recursively import a directory and collect every spearkit-registrable export
+ * (commands, events, components) found in default or named exports.
+ */
+declare function collectModules(dir: string, options?: LoadOptions): Promise<Registerable[]>;
+/**
+ * Load a directory and register everything it exports into the client.
+ * Returns the number of items registered.
+ */
+declare function loadInto(client: SpearClient, dir: string, options?: LoadOptions): Promise<number>;
+
+/** The flat key/value map parsed from a `.env` file. */
+type ParsedEnv = Record<string, string>;
+/** Options for {@link loadEnv}. */
+interface LoadEnvOptions {
+    /** File to read. Default `.env` in the current working directory. */
+    path?: string;
+    /** Overwrite variables already present in `process.env`. Default `false`. */
+    override?: boolean;
+}
+/** Parse `.env`-formatted text into a flat object. Does not touch `process.env`. */
+declare function parseEnv(content: string): ParsedEnv;
+/**
+ * Read a `.env` file and merge it into `process.env`. Existing variables win
+ * unless `override` is set. Missing files are ignored (returns `{}`), so it is
+ * safe to call unconditionally.
+ *
+ * @returns the parsed key/value pairs from the file.
+ */
+declare function loadEnv(options?: LoadEnvOptions): ParsedEnv;
+/** Typed, ergonomic reader over `process.env`. */
+interface EnvReader {
+    /** A string value (empty strings count as missing), or `undefined`/`fallback`. */
+    string(key: string): string | undefined;
+    string(key: string, fallback: string): string;
+    /** A numeric value, or `undefined`/`fallback` when missing or non-numeric. */
+    number(key: string): number | undefined;
+    number(key: string, fallback: number): number;
+    /** A boolean (`true/1/yes/on` vs `false/0/no/off`), or `undefined`/`fallback`. */
+    boolean(key: string): boolean | undefined;
+    boolean(key: string, fallback: boolean): boolean;
+    /** A string value, throwing if the variable is missing or empty. */
+    require(key: string): string;
+}
+/**
+ * Typed accessor over `process.env`.
+ *
+ * @example
+ * ```ts
+ * loadEnv();
+ * const token = env.require("DISCORD_TOKEN");
+ * const port = env.number("PORT", 3000);
+ * const debug = env.boolean("DEBUG", false);
+ * ```
+ */
+declare const env: EnvReader;
+
+/**
+ * Scheduled tasks: run work on a cron schedule or a fixed interval.
+ *
+ * Dependency-free. Includes a standard 5-field cron parser (`*`, ranges,
+ * lists, steps, `@daily` style aliases) evaluated in local time, plus a
+ * {@link TaskScheduler} that the client starts on ready and stops on destroy.
+ */
+
+/**
+ * A parsed cron expression. Evaluates in the host's local time.
+ *
+ * @example
+ * ```ts
+ * cron("*\u200b/5 * * * *").next();          // next 5-minute boundary
+ * cron("@daily").next(new Date());           // next midnight
+ * ```
+ */
+declare class CronExpression {
+    /** The original expression string. */
+    readonly source: string;
+    private readonly minutes;
+    private readonly hours;
+    private readonly daysOfMonth;
+    private readonly months;
+    private readonly daysOfWeek;
+    private readonly domRestricted;
+    private readonly dowRestricted;
+    constructor(expression: string);
+    private dayMatches;
+    /** The next time strictly after `from` (default now) that matches. */
+    next(from?: Date): Date;
+}
+/** Compile a cron expression. Throws on malformed input. */
+declare function cron(expression: string): CronExpression;
+/** Configuration for a scheduled task. Provide exactly one of `cron`/`interval`. */
+interface TaskConfig {
+    /** Unique task name. */
+    name: string;
+    /** A cron expression (local time). */
+    cron?: string;
+    /** A fixed interval in milliseconds. */
+    interval?: number;
+    /** Also run once immediately when the scheduler starts. Default `false`. */
+    runOnStart?: boolean;
+    /** The work to perform. */
+    run: (client: SpearClient) => Awaitable<void>;
+}
+/** A compiled, registrable scheduled task. Build it with {@link task}. */
+interface ScheduledTask {
+    readonly kind: "task";
+    readonly name: string;
+    readonly interval?: number;
+    readonly cron?: CronExpression;
+    readonly runOnStart: boolean;
+    readonly run: (client: SpearClient) => Awaitable<void>;
+}
+/** Define a scheduled task. Throws if neither `cron` nor `interval` is given. */
+declare function task(config: TaskConfig): ScheduledTask;
+/**
+ * Runs {@link ScheduledTask}s. The client owns one as `client.scheduler`,
+ * starts it on `clientReady` and stops it on `destroy`. Tasks added while
+ * running are scheduled immediately.
+ */
+declare class TaskScheduler {
+    private readonly tasks;
+    private readonly timers;
+    private running;
+    private client?;
+    private logger?;
+    private readonly reconcilers;
+    /** Number of registered tasks. */
+    get size(): number;
+    /** Whether the scheduler is currently running. */
+    get active(): boolean;
+    /** Every registered task. */
+    list(): ScheduledTask[];
+    /** Attach a logger for task error reporting. */
+    setLogger(logger: Logger): this;
+    /** Register one or more tasks. If already running, they are scheduled now. */
+    add(...tasks: ScheduledTask[]): this;
+    /** Remove a task and cancel its timer. */
+    remove(name: string): boolean;
+    /**
+     * 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: string, ms: number, fn: () => Awaitable<void>): {
+        cancel: () => boolean;
+    };
+    /**
+     * 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: string, delays: readonly number[], fn: (index: number) => Awaitable<void>): {
+        cancel: () => boolean;
+    };
+    /**
+     * 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: string, fn: (client: SpearClient) => Awaitable<void>): void;
+    private runReconciler;
+    /** Start every task. Safe to call once; later calls are ignored. */
+    start(client: SpearClient): void;
+    /** Stop the scheduler and cancel every pending timer. */
+    stop(): void;
+    private cancel;
+    private begin;
+    private delayFor;
+    private scheduleNext;
+    private arm;
+    private runTask;
+}
+
+type Resolved = {
+    string: string;
+    integer: number;
+    number: number;
+    boolean: boolean;
+    snowflake: string;
+    duration: number;
+    rest: string;
+};
+/** A single argument's runtime spec; recorded by {@link PrefixArgsBuilder}. */
+interface PrefixArgSpec {
+    readonly name: string;
+    readonly kind: keyof Resolved;
+    readonly required: boolean;
+    readonly defaultValue?: string | number | boolean;
+}
+/** A failed parse, returned by {@link PrefixArgsParser.parse}. */
+interface PrefixArgError {
+    readonly ok: false;
+    readonly arg: string;
+    readonly reason: string;
+}
+/** A successful parse, returned by {@link PrefixArgsParser.parse}. */
+interface PrefixArgsOk<T> {
+    readonly ok: true;
+    readonly values: T;
+}
+/** The compiled parser produced by {@link PrefixArgsBuilder.compile}. */
+interface PrefixArgsParser<T> {
+    readonly specs: readonly PrefixArgSpec[];
+    parse(tokens: readonly string[], rest: string): PrefixArgsOk<T> | PrefixArgError;
+}
+type AddField<TShape, K extends string, T, Req extends boolean> = Req extends true ? TShape & {
+    [P in K]: T;
+} : TShape & {
+    [P in K]?: T;
+};
+interface BaseOpts {
+    /** Mark the arg required. Default `false`. */
+    required?: boolean;
+}
+interface StringOpts extends BaseOpts {
+    minLength?: number;
+    maxLength?: number;
+    /** Default value when the token is missing. Makes the arg effectively optional. */
+    default?: string;
+}
+interface NumericOpts extends BaseOpts {
+    minValue?: number;
+    maxValue?: number;
+    default?: number;
+}
+interface BooleanOpts extends BaseOpts {
+    default?: boolean;
+}
+interface RestOpts extends BaseOpts {
+    default?: string;
+}
+/**
+ * Build a typed argument schema for {@link prefixCommand}. Chain calls
+ * positionally — first token → first arg, second → second arg, etc.
+ */
+declare class PrefixArgsBuilder<TShape extends Record<string, unknown> = {}> {
+    private readonly specs;
+    /** @internal */
+    constructor(specs?: readonly PrefixArgSpec[]);
+    /** A raw string token. */
+    string<K extends string, Req extends boolean = false>(name: K, options?: StringOpts & {
+        required?: Req;
+    }): PrefixArgsBuilder<AddField<TShape, K, string, Req>>;
+    /** A whole integer. */
+    integer<K extends string, Req extends boolean = false>(name: K, options?: NumericOpts & {
+        required?: Req;
+    }): PrefixArgsBuilder<AddField<TShape, K, number, Req>>;
+    /** A floating-point number. */
+    number<K extends string, Req extends boolean = false>(name: K, options?: NumericOpts & {
+        required?: Req;
+    }): PrefixArgsBuilder<AddField<TShape, K, number, Req>>;
+    /** A boolean (`true`/`yes`/`1`/`on` vs `false`/`no`/`0`/`off`). */
+    boolean<K extends string, Req extends boolean = false>(name: K, options?: BooleanOpts & {
+        required?: Req;
+    }): PrefixArgsBuilder<AddField<TShape, K, boolean, Req>>;
+    /** A Discord snowflake id — accepts raw ids and `<@u>` / `<#c>` / `<@&r>` mentions. */
+    snowflake<K extends string, Req extends boolean = false>(name: K, options?: BaseOpts & {
+        required?: Req;
+        default?: string;
+    }): PrefixArgsBuilder<AddField<TShape, K, string, Req>>;
+    /** A duration like `"1h30m"` or `"1 saat"` parsed to milliseconds. */
+    duration<K extends string, Req extends boolean = false>(name: K, options?: BaseOpts & {
+        required?: Req;
+        default?: number;
+    }): PrefixArgsBuilder<AddField<TShape, K, number, Req>>;
+    /** The remainder of the message (everything after previous args). */
+    rest<K extends string, Req extends boolean = false>(name: K, options?: RestOpts & {
+        required?: Req;
+    }): PrefixArgsBuilder<AddField<TShape, K, string, Req>>;
+    private push;
+    /** Compile this builder into a parser. */
+    compile(): PrefixArgsParser<TShape>;
+}
+/** Start a fresh args builder. Pass to `prefixCommand({ args })`. */
+declare function prefixArgs(): PrefixArgsBuilder<{}>;
+
+/** Options controlling how prefix messages are recognised. */
+interface PrefixOptions {
+    /** One or more command prefixes (e.g. `"!"` or `["!", "?"]`). */
+    prefix?: string | readonly string[];
+    /** Also accept a leading bot mention as a prefix. Default `true`. */
+    mention?: boolean;
+    /** Ignore messages authored by bots. Default `true`. */
+    ignoreBots?: boolean;
+    /** Match command names case-insensitively. Default `true`. */
+    caseInsensitive?: boolean;
+}
+/** Configuration for a prefix command. */
+interface PrefixCommandConfig<TArgs extends Record<string, unknown> = Record<string, never>, R = void> {
+    /** Primary command name (the word after the prefix). */
+    name: string;
+    /** Alternative names that also trigger the command. */
+    aliases?: readonly string[];
+    /** Human description (for your own help command). */
+    description?: string;
+    /** Rate-limit this command. A number is a duration in ms. */
+    cooldown?: CooldownInput;
+    /** Preconditions evaluated before the handler runs. */
+    guards?: readonly Guard[];
+    /** Typed argument schema; `ctx.options` will be shaped from this. */
+    args?: (builder: PrefixArgsBuilder<{}>) => PrefixArgsBuilder<TArgs>;
+    /** Handler invoked with a {@link PrefixContext} typed by `args`. */
+    run: (ctx: PrefixContext<TArgs>) => Awaitable<R>;
+}
+/** A registrable prefix command. Build it with {@link prefixCommand}. */
+interface PrefixCommand {
+    readonly kind: "prefixCommand";
+    readonly name: string;
+    readonly aliases: readonly string[];
+    readonly description?: string;
+    readonly cooldown?: CooldownConfig;
+    readonly guards?: readonly Guard[];
+    readonly parser?: PrefixArgsParser<Record<string, unknown>>;
+    readonly run: (ctx: PrefixContext) => Promise<void>;
+}
+/** Define a prefix command. */
+declare function prefixCommand<TArgs extends Record<string, unknown> = Record<string, never>, R = void>(config: PrefixCommandConfig<TArgs, R>): PrefixCommand;
+/** The handler argument for a prefix command: the message plus parsed args. */
+declare class PrefixContext<TArgs extends Record<string, unknown> = Record<string, never>> {
+    /** The triggering message. */
+    readonly message: Message;
+    /** The matched command name (as typed). */
+    readonly commandName: string;
+    /** Whitespace-split arguments after the command name. */
+    readonly args: string[];
+    /** The raw text after the command name. */
+    readonly rest: string;
+    /** Typed parsed arguments from `args` schema, or `{}` if none. */
+    readonly options: TArgs;
+    constructor(
+    /** The triggering message. */
+    message: Message, 
+    /** The matched command name (as typed). */
+    commandName: string, 
+    /** Whitespace-split arguments after the command name. */
+    args: string[], 
+    /** The raw text after the command name. */
+    rest: string, 
+    /** Typed parsed arguments from `args` schema, or `{}` if none. */
+    options?: TArgs);
+    get client(): Message["client"];
+    get author(): discord_js.User;
+    get member(): discord_js.GuildMember | null;
+    get guild(): discord_js.Guild | null;
+    get guildId(): string | null;
+    get channel(): discord_js.DMChannel | discord_js.PrivateThreadChannel | discord_js.PartialDMChannel | discord_js.PartialGroupDMChannel | discord_js.NewsChannel | discord_js.StageChannel | discord_js.TextChannel | discord_js.PublicThreadChannel<boolean> | discord_js.VoiceChannel;
+    get channelId(): string;
+    /** Reply to the triggering message. */
+    reply(content: string | MessagePayload | MessageReplyOptions): Promise<Message>;
+    /** Send a message to the same channel (no reply reference). */
+    send(content: string | MessagePayload | MessageCreateOptions): Promise<Message | undefined>;
+}
+/** Error hook invoked when a prefix command handler throws. */
+type PrefixErrorHandler = (error: Error, message: Message) => Awaitable<void>;
+/** Holds prefix commands and dispatches matching messages to them. */
+declare class PrefixRegistry {
+    private readonly commands;
+    private readonly lookup;
+    private options;
+    private logger?;
+    private cooldowns?;
+    private defaultCooldown?;
+    private errorHandler?;
+    private defaultGuards;
+    private onUsage?;
+    /** Configure prefixes and matching behaviour. */
+    setOptions(input: string | readonly string[] | PrefixOptions): this;
+    /** Attach a logger for dispatch tracing and error reporting. */
+    setLogger(logger: Logger): this;
+    /** Attach a hook called after each successful prefix command run. */
+    setUsageHook(hook: (event: UsageEvent) => void): this;
+    /** Share a cooldown manager and an optional default cooldown. */
+    setCooldowns(manager: CooldownManager, defaultCooldown?: CooldownConfig): this;
+    /** Guards that run before every prefix command's own guards. */
+    setDefaultGuards(guards: readonly Guard[]): this;
+    /** Set the handler used when a prefix command throws. */
+    onError(handler: PrefixErrorHandler): this;
+    /** Register one or more prefix commands (and their aliases). */
+    add(...commands: PrefixCommand[]): this;
+    private index;
+    /** Look up a command by name or alias. */
+    get(nameOrAlias: string): PrefixCommand | undefined;
+    /** Number of registered commands (excluding aliases). */
+    get size(): number;
+    /** Every registered command. */
+    list(): PrefixCommand[];
+    /** Strip a matching prefix (or bot mention) from `content`, or return `null`. */
+    private stripPrefix;
+    /**
+     * 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.
+     */
+    handle(message: Message): Promise<boolean>;
+}
+
+/** Anything that can be handed to {@link SpearClient.register}. */
+type Registerable = SlashCommand | EventDef | ComponentDef | ScheduledTask | PrefixCommand | ContextMenuCommand;
+/**
+ * Ready-made intent presets. Pass one to {@link SpearClient} as `intents`.
+ * `all` includes privileged intents — enable them in the developer portal.
+ */
+declare const Intents: {
+    /** No intents. */
+    readonly none: GatewayIntentBits[];
+    /** Just `Guilds` — enough for slash commands and interactions. */
+    readonly default: readonly [GatewayIntentBits.Guilds];
+    /** Guild + member gateway data. */
+    readonly guilds: readonly [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMembers];
+    /** Read message content (privileged) alongside guild messages. */
+    readonly messages: readonly [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent];
+    /** Every intent, including privileged ones. */
+    readonly all: GatewayIntentBits[];
+};
+/** spearkit-specific client options layered on top of discord.js {@link ClientOptions}. */
+interface SpearOptions {
+    /** A {@link Logger} instance, or options to build one. Exposed as `client.logger`. */
+    logger?: Logger | LoggerOptions;
+    /**
+     * Auto-load a `.env` file into `process.env` on {@link SpearClient.start}.
+     * `true` (default) loads `.env` from the cwd; pass {@link LoadEnvOptions} for
+     * a custom path or override behaviour, or `false` to disable.
+     */
+    dotenv?: boolean | LoadEnvOptions;
+    /** A default cooldown applied to every command. A command's own cooldown overrides it. */
+    cooldown?: CooldownInput;
+    /** Enable prefix (text) commands. A string/array sets prefixes; an object configures matching. */
+    prefix?: string | readonly string[] | PrefixOptions;
+    /** Track command/component/prefix usage to a store and/or a Discord channel. */
+    usage?: UsageOptions;
+    /** Default {@link Embeds} factory for preset replies. Pass an instance or options. */
+    embeds?: Embeds | EmbedsOptions;
+    /** Default guards (preconditions) applied before every command/component/prefix handler. */
+    guards?: readonly Guard[];
+}
+/** Options for {@link SpearClient}: discord.js options plus {@link SpearOptions}. `intents` may be omitted. */
+type SpearClientOptions = Partial<ClientOptions> & SpearOptions;
+/**
+ * A discord.js {@link Client} with batteries included: command, event,
+ * component, prefix-command, scheduler and context-menu registries plus
+ * interaction routing wired up automatically.
+ *
+ * @example
+ * ```ts
+ * const client = new SpearClient({ intents: Intents.default });
+ * client.register(ping, onReady, voteButton);
+ * await client.start(process.env.TOKEN);
+ * await client.deployAllCommands({ guildId: "123" });
+ * ```
+ */
+declare class SpearClient extends Client {
+    /** Slash command registry and dispatcher. */
+    readonly commands: CommandRegistry;
+    /** Event listener registry. */
+    readonly events: EventRegistry;
+    /** Button / select / modal registry and router. */
+    readonly components: ComponentRegistry;
+    /** Structured logger shared across spearkit and available to your code. */
+    readonly logger: Logger;
+    /** Shared cooldown manager used by command dispatch; also usable directly. */
+    readonly cooldowns: CooldownManager;
+    /** Cron/interval task scheduler; started on ready and stopped on destroy. */
+    readonly scheduler: TaskScheduler;
+    /** Prefix (text) command registry, dispatched from `messageCreate`. */
+    readonly prefix: PrefixRegistry;
+    /** Usage tracker: records who used what to a store and/or a Discord channel. */
+    readonly usage: UsageTracker;
+    /** Preset embed factory used by `ctx.error/success/info/warn` and available to your code. */
+    readonly embeds: Embeds;
+    /** User- and message-context-menu command registry. */
+    readonly contextMenus: ContextMenuRegistry;
+    private readonly envConfig;
+    constructor(options?: SpearClientOptions);
+    /**
+     * Register commands, events, components, scheduled tasks, prefix commands
+     * and context menus in one call. Each item is routed to its matching registry.
+     */
+    register(...items: Registerable[]): this;
+    /** Install one or more plugins, running each plugin's `setup`. */
+    use(...plugins: SpearPlugin[]): Promise<this>;
+    /**
+     * Recursively load a directory and register every command, event and
+     * component it exports. Returns the number of items registered.
+     */
+    load(dir: string, options?: LoadOptions): Promise<number>;
+    /**
+     * Log in. Falls back to the `DISCORD_TOKEN` environment variable when no
+     * token is passed.
+     */
+    start(token?: string): Promise<this>;
+    /**
+     * 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.
+     */
+    deployCommands(options?: {
+        guildId?: string;
+    }): Promise<DeployResult>;
+    /**
+     * 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.
+     */
+    deployAllCommands(options?: {
+        guildId?: string;
+        dryRun?: boolean;
+        strategy?: "always" | "diff";
+        /** Override the application id (default reads from the ready client). */
+        applicationId?: string;
+    }): Promise<DeployResult | {
+        skipped: true;
+        reason: "dry-run" | "no-changes";
+        body: readonly unknown[];
+    }>;
+    /** Define and register a scheduled task in one call. */
+    schedule(config: TaskConfig): ScheduledTask;
+    /** Stop the scheduler, then tear down the discord.js client. */
+    destroy(): Promise<void>;
+    private route;
+}
+
+/** What kind of interaction was used. */
+type UsageType = "command" | "prefix" | "component" | "event";
+/** Outcome of a tracked use — `"success"` if the handler returned without throwing. */
+type UsageOutcome = "success" | "error";
+/** A primitive metadata value attached to a usage event. */
+type UsageMetaValue = string | number | boolean | null;
+/** A single recorded use. */
+interface UsageEvent {
+    readonly type: UsageType;
+    /** Command/component name (or event name). */
+    readonly name: string;
+    readonly userId?: string;
+    readonly userTag?: string;
+    readonly guildId?: string | null;
+    readonly channelId?: string | null;
+    /** Free-form extra detail. */
+    readonly detail?: string;
+    readonly timestamp: Date;
+    /** Outcome of the handler — `"success"` or `"error"`. */
+    readonly outcome?: UsageOutcome;
+    /** Wall-clock duration of the handler in milliseconds. */
+    readonly durationMs?: number;
+    /** Snapshot of the typed options the handler ran with. */
+    readonly options?: Readonly<Record<string, UsageMetaValue>>;
+    /** Error message if `outcome === "error"`. */
+    readonly errorMessage?: string;
+}
+/** A pluggable persistence backend for {@link UsageEvent}s. */
+interface UsageStore {
+    /** Persist one event. */
+    record(event: UsageEvent): Awaitable<void>;
+    /** Read every persisted event. */
+    all(): Awaitable<readonly UsageEvent[]>;
+}
+/** In-memory store; great for tests and dashboards. Optionally capped. */
+declare class MemoryUsageStore implements UsageStore {
+    private readonly limit;
+    private readonly events;
+    constructor(limit?: number);
+    record(event: UsageEvent): void;
+    all(): readonly UsageEvent[];
+    /** Total recorded events. */
+    get size(): number;
+    /** Events recorded for a given user id. */
+    byUser(userId: string): UsageEvent[];
+    /** Forget everything. */
+    clear(): void;
+}
+/**
+ * File-backed store using newline-delimited JSON (`.jsonl`). Appends one line
+ * per event — durable, human-inspectable, and dependency-free.
+ */
+declare class JsonFileUsageStore implements UsageStore {
+    private readonly path;
+    constructor(path: string);
+    record(event: UsageEvent): Promise<void>;
+    all(): Promise<readonly UsageEvent[]>;
+}
+/** Default one-line rendering of a usage event for a Discord channel. */
+declare function formatUsage(event: UsageEvent): string;
+/** Client-level usage configuration (the `usage` option). */
+interface UsageOptions {
+    /** Persist events to this store (a database). */
+    store?: UsageStore;
+    /** Mirror events into this Discord channel id. */
+    channel?: string;
+    /** Custom channel-line formatter. */
+    format?: (event: UsageEvent) => string;
+}
+/**
+ * Routes each {@link UsageEvent} to a store and/or a Discord channel. The
+ * client owns one as `client.usage`. Tracking is fire-and-forget: a slow store
+ * or channel never blocks command handling, and failures are logged.
+ */
+declare class UsageTracker {
+    /** The configured store, if any. Directly queryable. */
+    store?: UsageStore;
+    private reporter?;
+    private client?;
+    private logger?;
+    /** Whether anything will happen on {@link track}. */
+    get enabled(): boolean;
+    /** @internal Used by the client to resolve report channels. */
+    setClient(client: SpearClient): this;
+    setLogger(logger: Logger): this;
+    /** Persist events to a store (a database). */
+    setStore(store: UsageStore): this;
+    /** Mirror events into a Discord channel. */
+    reportTo(channelId: string, format?: (event: UsageEvent) => string): this;
+    /** Record a use. Returns immediately; storing/reporting happen in the background. */
+    track(event: UsageEvent): void;
+    private run;
+}
+
+/** Metadata accepted by both context-menu kinds. */
+interface ContextMenuMeta {
+    defaultMemberPermissions?: PermissionResolvable | null;
+    nsfw?: boolean;
+    guildOnly?: boolean;
+    nameLocalizations?: LocalizationMap;
+    cooldown?: CooldownInput;
+    guards?: readonly Guard[];
+}
+/** Configuration for {@link userCommand}. */
+interface UserCommandConfig<R = void> extends ContextMenuMeta {
+    name: string;
+    run: (ctx: UserContextMenuContext) => Awaitable<R>;
+}
+/** Configuration for {@link messageCommand}. */
+interface MessageCommandConfig<R = void> extends ContextMenuMeta {
+    name: string;
+    run: (ctx: MessageContextMenuContext) => Awaitable<R>;
+}
+/** Common shape for any context-menu command (user or message). */
+interface BaseContextMenuCommand {
+    readonly name: string;
+    readonly cooldown?: CooldownConfig;
+    readonly guards?: readonly Guard[];
+    toJSON(): RESTPostAPIContextMenuApplicationCommandsJSONBody;
+}
+/** A user-target context-menu command. */
+interface UserContextMenu extends BaseContextMenuCommand {
+    readonly kind: "userMenu";
+    execute(interaction: UserContextMenuCommandInteraction): Promise<void>;
+}
+/** A message-target context-menu command. */
+interface MessageContextMenu extends BaseContextMenuCommand {
+    readonly kind: "messageMenu";
+    execute(interaction: MessageContextMenuCommandInteraction): Promise<void>;
+}
+/** A registered context-menu command — discriminated by `kind`. */
+type ContextMenuCommand = UserContextMenu | MessageContextMenu;
+/** Handler context for a user-target context menu. */
+declare class UserContextMenuContext extends BaseContext<UserContextMenuCommandInteraction> {
+    /** The user the menu was invoked on. */
+    get targetUser(): discord_js.User;
+    /** The member version of the target, if available. */
+    get targetMember(): discord_js.GuildMember | discord_js.APIInteractionGuildMember | null;
+}
+/** Handler context for a message-target context menu. */
+declare class MessageContextMenuContext extends BaseContext<MessageContextMenuCommandInteraction> {
+    /** The message the menu was invoked on. */
+    get targetMessage(): discord_js.Message<boolean>;
+}
+/** Define a user-target ("Apps → user") context-menu command. */
+declare function userCommand<R = void>(config: UserCommandConfig<R>): UserContextMenu;
+/** Define a message-target ("Apps → message") context-menu command. */
+declare function messageCommand<R = void>(config: MessageCommandConfig<R>): MessageContextMenu;
+/** Holds context-menu commands and routes incoming interactions to them. */
+declare class ContextMenuRegistry {
+    private readonly users;
+    private readonly messages;
+    private logger?;
+    private cooldowns?;
+    private defaultCooldown?;
+    private defaultGuards;
+    private onUsage?;
+    /** Register one or more context-menu commands. */
+    add(...commands: readonly ContextMenuCommand[]): this;
+    /** Total number of registered context-menu commands. */
+    get size(): number;
+    /** Every registered command, both kinds. */
+    all(): ContextMenuCommand[];
+    /** Serialise every command for the REST `applicationCommands` PUT body. */
+    toJSON(): RESTPostAPIContextMenuApplicationCommandsJSONBody[];
+    setLogger(logger: Logger): this;
+    setCooldowns(manager: CooldownManager, defaultCooldown?: CooldownConfig): this;
+    setDefaultGuards(guards: readonly Guard[]): this;
+    setUsageHook(hook: (event: UsageEvent) => void): this;
+    /** Dispatch a user-target interaction. */
+    handleUser(interaction: UserContextMenuCommandInteraction): Promise<void>;
+    /** Dispatch a message-target interaction. */
+    handleMessage(interaction: MessageContextMenuCommandInteraction): Promise<void>;
+    private dispatch;
+}
+
+/**
+ * Paginated embed replies driven by buttons.
+ *
+ * Real bots reimplement the same {page state, prev/next buttons, user-only
+ * filter, disable-on-timeout} dance per command. {@link paginate} handles it:
+ * pass an item list and a render function, and you get an interactive,
+ * timeout-aware paginator in one call. {@link buildPaginatorPage} exposes the
+ * same logic without the collector, for tests or custom flows.
+ */
+
+/** Result of {@link PaginateOptions.render}: a builder OR a full message payload. */
+type PaginateRender = EmbedBuilder | readonly EmbedBuilder[] | BaseMessageOptions;
+/** Options for {@link paginate} / {@link buildPaginatorPage}. */
+interface PaginateOptions<T> {
+    /** Items per page. Default `10`. */
+    pageSize?: number;
+    /** Build the body for one page. */
+    render: (slice: readonly T[], state: {
+        page: number;
+        pages: number;
+    }) => PaginateRender | Promise<PaginateRender>;
+    /** When set, only this user id can click. Defaults to the invoker. */
+    user?: string;
+    /** Time (ms) before buttons are disabled. Default `5 * 60_000`. */
+    timeoutMs?: number;
+    /** Custom-id prefix to avoid clashes with other components. Default `"spk-page"`. */
+    namespace?: string;
+    /** Make the initial reply ephemeral. Default `false`. */
+    ephemeral?: boolean;
+    /** Button labels. Defaults: `‹` Prev / `›` Next / `«` First / `»` Last. */
+    labels?: {
+        first?: string;
+        prev?: string;
+        next?: string;
+        last?: string;
+    };
+    /** Which buttons to show. Default `"prev-next"`. */
+    controls?: "prev-next" | "first-prev-next-last";
+}
+/**
+ * Build the payload for a single paginator page (embeds + button row), without
+ * any interaction or collector wiring. Useful for tests, web previews and
+ * custom UIs that want spearkit's slicing/controls but their own send path.
+ */
+declare function buildPaginatorPage<T>(items: readonly T[], page: number, options: PaginateOptions<T>): Promise<{
+    payload: BaseMessageOptions;
+    pages: number;
+}>;
+/**
+ * Send an item list across paginated, button-controlled embeds.
+ *
+ * The first page is replied to {@link interaction} (or `editReply`d when
+ * already deferred), then a button-component collector handles prev/next
+ * clicks until the timeout fires — at which point the buttons are disabled.
+ */
+declare function paginate<T>(interaction: RepliableInteraction, items: readonly T[], options: PaginateOptions<T>): Promise<void>;
+
+/**
+ * Yes/no confirmation prompts: a one-line API for the "are you sure?" flow
+ * Yes/no confirmation prompts: a one-line API for the "are you sure?" flow
+ * that bots reimplement every time (reaction-based, button-based, or modal).
+ *
+ * @example
+ * ```ts
+ * const ok = await confirm(interaction, {
+ *   body: `Reset **${role.name}** for **${members}** members?`,
+ *   confirm: { label: "Reset", style: "Danger" },
+ *   cancel:  { label: "Cancel" },
+ *   timeoutMs: 30_000,
+ * });
+ * if (!ok.confirmed) return ctx.error("Cancelled.");
+ * ```
+ */
+
+/** Visual style for a confirm/cancel button. */
+type ConfirmButtonStyle = "Primary" | "Secondary" | "Success" | "Danger";
+/** One of the two buttons. */
+interface ConfirmButtonOptions {
+    /** Visible label. */
+    label?: string;
+    /** Visual style. */
+    style?: ConfirmButtonStyle;
+}
+/** Options for {@link confirm}. */
+interface ConfirmOptions {
+    /** Embed title. */
+    title?: string;
+    /** Embed body. */
+    body: string;
+    /** Confirm button config. Defaults: label `"Confirm"`, style `"Success"`. */
+    confirm?: ConfirmButtonOptions;
+    /** Cancel button config. Defaults: label `"Cancel"`, style `"Secondary"`. */
+    cancel?: ConfirmButtonOptions;
+    /** Only this user id can click. Defaults to the invoker. */
+    user?: string;
+    /** Time (ms) before the prompt times out as cancelled. Default `30_000`. */
+    timeoutMs?: number;
+    /** Make the prompt ephemeral. Default `true`. */
+    ephemeral?: boolean;
+    /** Custom-id prefix to avoid clashes. Default `"spk-confirm"`. */
+    namespace?: string;
+}
+/** Result of {@link confirm}. */
+interface ConfirmResult {
+    /** Whether the user confirmed (clicked the confirm button before timeout). */
+    confirmed: boolean;
+    /** How the prompt ended. */
+    reason: "confirm" | "cancel" | "timeout";
+    /** The triggering button interaction when `reason !== "timeout"`. */
+    interaction?: ButtonInteraction;
+}
+/**
+ * Show a yes/no confirmation prompt and wait for the user's choice.
+ *
+ * Resolves once a button is clicked or the timeout fires. The clicked button
+ * is automatically acknowledged via `deferUpdate`, and the original message's
+ * buttons are disabled. Returns `{ confirmed, reason, interaction? }`.
+ */
+declare function confirm(interaction: RepliableInteraction, options: ConfirmOptions): Promise<ConfirmResult>;
+
+/**
+ * Typed custom-id codec.
+ *
+ * Patterns follow the grammar `namespace(:{param})*`, e.g. `"vote"` or
+ * `"vote:{choice}"` or `"page:{id}:{dir}"`. The `namespace` is the routing key;
+ * each `{param}` becomes a positional, percent-escaped value in the encoded id.
+ * Param names are recovered at the type level so handlers get a typed `params`
+ * object and `build()` requires exactly the right params.
+ */
+/** Names of the `{param}` placeholders inside a pattern. */
+type ParamNames<S extends string> = S extends `${string}{${infer Name}}${infer Rest}` ? Name | ParamNames<Rest> : never;
+/** The params object a pattern resolves to (every value is a string). */
+type Params<S extends string> = {
+    [K in ParamNames<S>]: string;
+};
+/** Arguments `build()` accepts: none when the pattern has no params. */
+type BuildArgs<S extends string> = [ParamNames<S>] extends [never] ? [] : [params: Params<S>];
+/** The discord custom-id length limit. */
+declare const MAX_CUSTOM_ID_LENGTH = 100;
+/** A compiled pattern: its routing namespace and ordered param names. */
+interface CompiledPattern {
+    readonly pattern: string;
+    readonly namespace: string;
+    readonly paramNames: readonly string[];
+}
+/** Compile and validate a custom-id pattern. Throws on malformed input. */
+declare function compilePattern(pattern: string): CompiledPattern;
+/** Build a concrete custom-id from a compiled pattern and its params. */
+declare function buildCustomId(compiled: CompiledPattern, params: Readonly<Record<string, string>>): string;
+/** The namespace + raw values parsed out of an incoming custom-id. */
+interface ParsedCustomId {
+    readonly namespace: string;
+    readonly values: readonly string[];
+}
+/** Parse an incoming custom-id into its namespace and decoded values. */
+declare function parseCustomId(customId: string): ParsedCustomId;
+/** Map ordered values onto their param names. */
+declare function paramsFromValues(paramNames: readonly string[], values: readonly string[]): Record<string, string>;
+
+type UpdateInput = string | InteractionUpdateOptions;
+/** The concrete message-component interaction types (button + every select). */
+type AnyComponentInteraction = ButtonInteraction | StringSelectMenuInteraction | UserSelectMenuInteraction | RoleSelectMenuInteraction | ChannelSelectMenuInteraction | MentionableSelectMenuInteraction;
+/**
+ * Base context for message-component interactions (buttons and selects).
+ * Adds the component-only `update`/`deferUpdate`/`showModal` helpers and the
+ * routed, typed {@link params}.
+ */
+declare class MessageComponentContext<P, I extends AnyComponentInteraction = AnyComponentInteraction> extends BaseContext<I> {
+    /** Params extracted from the custom-id pattern. */
+    readonly params: P;
+    constructor(interaction: I, 
+    /** Params extracted from the custom-id pattern. */
+    params: P);
+    /** The raw custom-id that triggered this interaction. */
+    get customId(): string;
+    /** The message the component lives on. */
+    get message(): discord_js.Message<boolean>;
+    /** Edit the message this component belongs to. */
+    update(input: UpdateInput): Promise<void>;
+    /** Acknowledge the interaction without editing the message yet. */
+    deferUpdate(): Promise<void>;
+    /** Open a modal in response to this component. */
+    showModal(modal: JSONEncodable<APIModalInteractionResponseCallbackData> | ModalComponentData | ModalBuilder): Promise<void>;
+}
+/** Context for a button click. */
+declare class ButtonContext<P = Record<string, never>> extends MessageComponentContext<P, ButtonInteraction> {
+}
+/** Context for a string select; exposes the chosen {@link values}. */
+declare class StringSelectContext<P = Record<string, never>> extends MessageComponentContext<P, StringSelectMenuInteraction> {
+    /** All selected values. */
+    get values(): string[];
+    /** The first selected value, or `undefined` if none. */
+    get value(): string | undefined;
+}
+/** Context for a user select; exposes selected ids, users and members. */
+declare class UserSelectContext<P = Record<string, never>> extends MessageComponentContext<P, UserSelectMenuInteraction> {
+    get values(): string[];
+    get users(): discord_js.Collection<string, discord_js.User>;
+    get members(): discord_js.Collection<string, discord_js.GuildMember | discord_js.APIGuildMember>;
+}
+/** Context for a role select. */
+declare class RoleSelectContext<P = Record<string, never>> extends MessageComponentContext<P, RoleSelectMenuInteraction> {
+    get values(): string[];
+    get roles(): discord_js.Collection<string, discord_js.Role | discord_js.APIRole>;
+}
+/** Context for a channel select. */
+declare class ChannelSelectContext<P = Record<string, never>> extends MessageComponentContext<P, ChannelSelectMenuInteraction> {
+    get values(): string[];
+    get channels(): discord_js.Collection<string, discord_js.Channel | discord_js.APIChannel>;
+}
+/** Context for a mentionable (user + role) select. */
+declare class MentionableSelectContext<P = Record<string, never>> extends MessageComponentContext<P, MentionableSelectMenuInteraction> {
+    get values(): string[];
+    get users(): discord_js.Collection<string, discord_js.User>;
+    get roles(): discord_js.Collection<string, discord_js.Role | discord_js.APIRole>;
+    get members(): discord_js.Collection<string, discord_js.GuildMember | discord_js.APIGuildMember>;
+}
+/**
+ * Context for a submitted modal. Exposes the routed {@link params} plus the
+ * resolved text-input {@link fields}, keyed by the field names you declared.
+ */
+declare class ModalContext<P, F extends string = string> extends BaseContext<ModalSubmitInteraction> {
+    readonly params: P;
+    /** Submitted values, keyed by the field names from your modal definition. */
+    readonly fields: Record<F, string>;
+    constructor(interaction: ModalSubmitInteraction, params: P, 
+    /** Submitted values, keyed by the field names from your modal definition. */
+    fields: Record<F, string>);
+    /** The raw custom-id that triggered this modal submission. */
+    get customId(): string;
+}
+
 /** Accepted button styles for an interactive (custom-id) button. */
 type ButtonStyleInput = "Primary" | "Secondary" | "Success" | "Danger" | ButtonStyle.Primary | ButtonStyle.Secondary | ButtonStyle.Success | ButtonStyle.Danger;
 /** Config for an interactive button created with {@link button}. */
@@ -601,6 +2100,8 @@ interface ButtonConfig<P extends string, R> {
     style?: ButtonStyleInput;
     emoji?: ComponentEmojiResolvable;
     disabled?: boolean;
+    /** Preconditions evaluated before the handler runs. */
+    guards?: readonly Guard[];
     run: (ctx: ButtonContext<Params<P>>) => Awaitable<R>;
 }
 /** A registrable button with a typed {@link build}. */
@@ -637,6 +2138,8 @@ interface SelectConfigBase {
     minValues?: number;
     maxValues?: number;
     disabled?: boolean;
+    /** Preconditions evaluated before the handler runs. */
+    guards?: readonly Guard[];
 }
 /** Config for a string select created with {@link stringSelect}. */
 interface StringSelectConfig<P extends string, R> extends SelectConfigBase {
@@ -714,6 +2217,8 @@ interface ModalConfig<P extends string, F extends Record<string, TextInputDef>,
     id: P;
     title: string;
     fields: F;
+    /** Preconditions evaluated before the handler runs. */
+    guards?: readonly Guard[];
     run: (ctx: ModalContext<Params<P>, keyof F & string>) => Awaitable<R>;
 }
 /** A registrable modal with a typed {@link build}. */
@@ -750,100 +2255,4 @@ declare function modal<const P extends string, F extends Record<string, TextInpu
  */
 declare function row<C extends MessageActionRowComponentBuilder>(...components: C[]): ActionRowBuilder<C>;
 
-/**
- * A spearkit plugin: a named, reusable bundle of commands, events and components.
- * Its {@link setup} runs once when added to a client via `client.use(plugin)`.
- */
-interface SpearPlugin {
-    readonly name: string;
-    setup(client: SpearClient): Awaitable<void>;
-}
-/** Identity helper that gives a plugin object its type and editor hints. */
-declare function definePlugin(plugin: SpearPlugin): SpearPlugin;
-
-/** Options for the directory loader. */
-interface LoadOptions {
-    /** File extensions to import. Default: `.js`, `.mjs`, `.cjs`. */
-    extensions?: readonly string[];
-    /** Recurse into subdirectories. Default: `true`. */
-    recursive?: boolean;
-}
-/**
- * Recursively import a directory and collect every spearkit-registrable export
- * (commands, events, components) found in default or named exports.
- */
-declare function collectModules(dir: string, options?: LoadOptions): Promise<Registerable[]>;
-/**
- * Load a directory and register everything it exports into the client.
- * Returns the number of items registered.
- */
-declare function loadInto(client: SpearClient, dir: string, options?: LoadOptions): Promise<number>;
-
-/** Anything that can be handed to {@link SpearClient.register}. */
-type Registerable = SlashCommand | EventDef | ComponentDef;
-/**
- * Ready-made intent presets. Pass one to {@link SpearClient} as `intents`.
- * `all` includes privileged intents — enable them in the developer portal.
- */
-declare const Intents: {
-    /** No intents. */
-    readonly none: GatewayIntentBits[];
-    /** Just `Guilds` — enough for slash commands and interactions. */
-    readonly default: readonly [GatewayIntentBits.Guilds];
-    /** Guild + member gateway data. */
-    readonly guilds: readonly [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMembers];
-    /** Read message content (privileged) alongside guild messages. */
-    readonly messages: readonly [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent];
-    /** Every intent, including privileged ones. */
-    readonly all: GatewayIntentBits[];
-};
-/** Options for {@link SpearClient}. Identical to discord.js but `intents` may be omitted. */
-type SpearClientOptions = Partial<ClientOptions>;
-/**
- * A discord.js {@link Client} with batteries included: command, event and
- * component registries plus interaction routing wired up automatically.
- *
- * @example
- * ```ts
- * const client = new SpearClient({ intents: Intents.default });
- * client.register(ping, onReady, voteButton);
- * await client.start(process.env.TOKEN);
- * await client.deployCommands({ guildId: "123" });
- * ```
- */
-declare class SpearClient extends Client {
-    /** Slash command registry and dispatcher. */
-    readonly commands: CommandRegistry;
-    /** Event listener registry. */
-    readonly events: EventRegistry;
-    /** Button / select / modal registry and router. */
-    readonly components: ComponentRegistry;
-    constructor(options?: SpearClientOptions);
-    /**
-     * Register commands, events and components in one call. Each item is routed
-     * to the matching registry based on its kind.
-     */
-    register(...items: Registerable[]): this;
-    /** Install one or more plugins, running each plugin's `setup`. */
-    use(...plugins: SpearPlugin[]): Promise<this>;
-    /**
-     * Recursively load a directory and register every command, event and
-     * component it exports. Returns the number of items registered.
-     */
-    load(dir: string, options?: LoadOptions): Promise<number>;
-    /**
-     * Log in. Falls back to the `DISCORD_TOKEN` environment variable when no
-     * token is passed.
-     */
-    start(token?: string): Promise<this>;
-    /**
-     * Push the registered slash commands to discord using the client's own
-     * authenticated REST connection. Call after the client is ready.
-     */
-    deployCommands(options?: {
-        guildId?: string;
-    }): Promise<DeployResult>;
-    private route;
-}
-
-export { type AllowedChannelType, type AnyComponentInteraction, type AnyOptionDef, AutocompleteContext, type AutocompleteHandler, BaseContext, type BuildArgs, type Button, type ButtonConfig, ButtonContext, type ButtonRoute, type ButtonStyleInput, type ChannelSelect, ChannelSelectContext, type ChannelSelectRoute, type CommandConfig, CommandContext, type CommandErrorHandler, type CommandGroupConfig, CommandRegistry, type CompiledPattern, type ComponentDef, type ComponentErrorHandler, ComponentRegistry, type DeployOptions, type DeployResult, type EntitySelectConfig, type EventConfig, type EventDef, type EventHandler, EventRegistry, Intents, type LinkButtonConfig, type LoadOptions, MAX_CUSTOM_ID_LENGTH, type MentionableSelect, MentionableSelectContext, type MentionableSelectRoute, MessageComponentContext, type Modal, type ModalConfig, ModalContext, type ModalRoute, type OptionChoice, type OptionDef, type OptionMap, type OptionValue, type ParamNames, type Params, type ParsedCustomId, type Registerable, type ReplyData, type ReplyInput, type ResolvedOption, type ResolvedOptions, type RoleSelect, RoleSelectContext, type RoleSelectRoute, SlashCommand, SpearClient, type SpearClientOptions, type SpearPlugin, type StringSelect, type StringSelectConfig, StringSelectContext, type StringSelectRoute, type Subcommand, type SubcommandConfig, type SubcommandGroup, type SubcommandGroupConfig, type TextInputDef, type TextInputStyleInput, type UserSelect, UserSelectContext, type UserSelectRoute, asEphemeral, buildCustomId, button, channelSelect, collectModules, command, commandGroup, compilePattern, definePlugin, event, linkButton, loadInto, mentionableSelect, modal, normalizeReply, option, optionsHaveAutocomplete, paramsFromValues, parseCustomId, readOption, roleSelect, row, stringSelect, subcommand, subcommandGroup, textInput, toAPIOption, userSelect };
+export { type AllowedChannelType, type AnyComponentInteraction, type AnyOptionDef, AutocompleteContext, type AutocompleteHandler, BaseContext, type BaseContextMenuCommand, type BuildArgs, type Button, type ButtonConfig, ButtonContext, type ButtonRoute, type ButtonStyleInput, type CacheSetOptions, type CacheStore, type ChannelSelect, ChannelSelectContext, type ChannelSelectRoute, type CommandConfig, CommandContext, type CommandErrorHandler, type CommandGroupConfig, CommandRegistry, type CompiledPattern, type ComponentDef, type ComponentErrorHandler, ComponentRegistry, type ConfirmButtonOptions, type ConfirmButtonStyle, type ConfirmOptions, type ConfirmResult, type ContextMenuCommand, ContextMenuRegistry, type CooldownActor, type CooldownConfig, type CooldownExemptions, type CooldownInput, CooldownManager, type CooldownOverrides, type CooldownResult, type CooldownScope, CronExpression, DEFAULT_EMBED_COLORS, DEFAULT_EMBED_ICONS, type DeployOptions, type DeployResult, type DiscordTimestampStyle, type EmbedColors, type EmbedIcons, type EmbedLevel, type EmbedPresetInput, Embeds, type EmbedsOptions, type EntitySelectConfig, type EnvReader, type EventConfig, type EventDef, type EventHandler, EventRegistry, type FormatDurationOptions, type Guard, type GuardContext, type GuardResult, Intents, JsonFileUsageStore, KeyedLock, type KeyedLockOptions, type LinkButtonConfig, type LoadConfigOptions, type LoadEnvOptions, type LoadOptions, type LockRelease, type LogEntry, type LogLevel, type LogOptions, type LogSink, type LogThreshold, type LogValue, Logger, type LoggerOptions, MAX_CUSTOM_ID_LENGTH, MemoryCache, MemoryUsageStore, type MentionableSelect, MentionableSelectContext, type MentionableSelectRoute, type MessageCommandConfig, MessageComponentContext, type MessageContextMenu, MessageContextMenuContext, type Modal, type ModalConfig, ModalContext, type ModalRoute, type OptionChoice, type OptionDef, type OptionMap, type OptionValue, type PaginateOptions, type PaginateRender, type ParamNames, type Params, type ParsedCustomId, type ParsedEnv, type PrefixArgError, type PrefixArgSpec, PrefixArgsBuilder, type PrefixArgsOk, type PrefixArgsParser, type PrefixCommand, type PrefixCommandConfig, PrefixContext, type PrefixErrorHandler, type PrefixOptions, PrefixRegistry, type RateLimitResult, type Registerable, type ReplyData, type ReplyInput, type ResolvedOption, type ResolvedOptions, type RoleSelect, RoleSelectContext, type RoleSelectRoute, type RunGuardsResult, type SafeFetchOptions, type ScheduledTask, SlashCommand, SpearClient, type SpearClientOptions, type SpearOptions, type SpearPlugin, type StringSelect, type StringSelectConfig, StringSelectContext, type StringSelectRoute, type Subcommand, type SubcommandConfig, type SubcommandGroup, type SubcommandGroupConfig, type TaskConfig, TaskScheduler, type TextInputDef, type TextInputStyleInput, type UsageEvent, type UsageMetaValue, type UsageOptions, type UsageOutcome, type UsageStore, UsageTracker, type UsageType, type UserCommandConfig, type UserContextMenu, UserContextMenuContext, type UserSelect, UserSelectContext, type UserSelectRoute, asEphemeral, buildCustomId, buildPaginatorPage, button, channelSelect, collectModules, command, commandGroup, compilePattern, confirm, consoleSink, createCache, cron, defaultEmbeds, definePlugin, denied, discordTimestamp, dmOnly, effectiveDuration, env, event, fetchChannel, fetchGuild, fetchMember, fetchMessage, fetchRole, fetchUser, formatCooldownMessage, formatDuration, formatUsage, guard, guildOnly, jsonlSink, linkButton, loadConfig, loadConfigAsync, loadEnv, loadInto, lookup, lookupOptional, mentionableSelect, messageCommand, modal, normalizeCooldown, normalizeReply, option, optionsHaveAutocomplete, paginate, paramsFromValues, parseCustomId, parseDuration, parseEnv, prefixArgs, prefixCommand, readOption, relativeTimestamp, requireAllRoles, requireAnyRole, requireBotPermissions, requireOwner, requireUserPermissions, roleSelect, row, runGuards, safeFetch, safeTry, stringSelect, subcommand, subcommandGroup, task, textInput, toAPIOption, toError, userCommand, userSelect, webhookSink, withSafeTimeout };