spearkit 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -1,135 +1,498 @@
 import * as discord_js from 'discord.js';
-import { RepliableInteraction, InteractionReplyOptions, InteractionResponse, Message, APIApplicationCommandChannelOption, CommandInteractionOption, Attachment, ApplicationCommandOptionType, LocalizationMap, Awaitable, ChatInputCommandInteraction, APIApplicationCommandBasicOption, AutocompleteInteraction, JSONEncodable, APIModalInteractionResponseCallbackData, ModalComponentData, ModalBuilder, PermissionResolvable, RESTPostAPIChatInputApplicationCommandsJSONBody, RESTPostAPIApplicationCommandsJSONBody, REST, RESTPutAPIApplicationCommandsResult, RESTPutAPIApplicationGuildCommandsResult, ClientEvents, Client, ButtonInteraction, ChannelSelectMenuInteraction, StringSelectMenuInteraction, UserSelectMenuInteraction, RoleSelectMenuInteraction, MentionableSelectMenuInteraction, ModalSubmitInteraction, Interaction, MessagePayload, MessageReplyOptions, MessageCreateOptions, GatewayIntentBits, ClientOptions, InteractionUpdateOptions, ButtonBuilder, ButtonStyle, ComponentEmojiResolvable, ChannelSelectMenuBuilder, MentionableSelectMenuBuilder, TextInputStyle, RoleSelectMenuBuilder, StringSelectMenuBuilder, SelectMenuComponentOptionData, UserSelectMenuBuilder, ChannelType, MessageActionRowComponentBuilder, ActionRowBuilder } from 'discord.js';
+import { APIEmbedField, APIEmbedFooter, APIEmbedAuthor, EmbedBuilder, Client, Channel, Guild, GuildMember, MessageManager, Message, Role, User, APIInteractionGuildMember, Awaitable, PermissionResolvable, 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';
 
 /**
- * A small, dependency-free structured logger used across spearkit so every
- * problem (command/component/event failures, gateway errors, your own code)
- * lands in one consistent, debuggable place.
+ * 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.
  *
- * It is intentionally tiny: levels, scopes, structured data and a pluggable
- * sink. No `any`/`unknown` leaks into your code — log metadata is constrained
- * to primitive {@link LogValue}s and an optional {@link Error}.
+ * @example
+ * ```ts
+ * const embeds = new Embeds({ colors: { success: 0x00ff88 } });
+ * await channel.send({ embeds: [embeds.success("Saved.")] });
+ * ```
  */
-/** 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;
-    /** Where entries go. Default {@link consoleSink}. */
-    sink?: 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;
+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;
+
 /**
- * A leveled, scoped logger. Create one directly or read `client.logger`.
- * {@link child} loggers share the parent's threshold and sink, so calling
- * {@link setLevel} on any of them affects the whole tree.
+ * 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 log = new Logger({ level: "debug" });
- * log.info("ready", { data: { shard: 0 } });
- * log.child("commands").error("handler failed", { error });
+ * const locks = new KeyedLock();
+ * const result = await locks.run(`ticket:${id}:claim`, async () => {
+ *   // …mutate ticket atomically…
+ *   return "ok";
+ * }, { onBusy: () => "busy" });
  * ```
  */
-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;
-    /** 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;
+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;
 }
-/** Coerce an unknown thrown value into an {@link Error}. */
-declare function toError(value: unknown): Error;
 
-/** 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.
+ * 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.
  *
- * @returns the parsed key/value pairs from the file.
+ * @example
+ * ```ts
+ * await safeTry(() => message.delete());
+ * ```
  */
-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;
+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[];
 }
 /**
- * Typed accessor over `process.env`.
+ * Format a millisecond duration into human-readable text.
  *
  * @example
  * ```ts
- * loadEnv();
- * const token = env.require("DISCORD_TOKEN");
- * const port = env.number("PORT", 3000);
- * const debug = env.boolean("DEBUG", false);
+ * 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 const env: EnvReader;
+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;
+};
+/** Either a plain string or full reply options. */
+type ReplyInput = string | ReplyData;
+/** Normalises spearkit reply input into a discord.js reply payload. */
+declare function normalizeReply(input: ReplyInput): InteractionReplyOptions;
+/** Marks an input as ephemeral, regardless of how it was passed. */
+declare function asEphemeral(input: ReplyInput): ReplyData;
+/**
+ * Ergonomic base wrapper shared by every interaction context (commands,
+ * buttons, selects, modals). Exposes the common actor/location accessors plus
+ * reply helpers that smooth over discord.js' state machine.
+ */
+declare abstract class BaseContext<I extends RepliableInteraction = RepliableInteraction> {
+    readonly interaction: I;
+    constructor(interaction: I);
+    get client(): I["client"];
+    get user(): discord_js.User;
+    get member(): discord_js.GuildMember | discord_js.APIInteractionGuildMember | null;
+    get guild(): discord_js.Guild | null;
+    get guildId(): string | null;
+    get channel(): discord_js.TextBasedChannel | null;
+    get channelId(): string | null;
+    get locale(): discord_js.Locale;
+    /** Whether the interaction is already deferred. */
+    get deferred(): boolean;
+    /** Whether the interaction already received an initial response. */
+    get replied(): boolean;
+    /** Send the initial response to the interaction. */
+    reply(input: ReplyInput): Promise<InteractionResponse<boolean>>;
+    /** Reply, but always hidden to everyone except the invoking user. */
+    replyEphemeral(input: ReplyInput): Promise<InteractionResponse<boolean>>;
+    /** Acknowledge now and respond later via {@link editReply}. */
+    defer(options?: {
+        ephemeral?: boolean;
+    }): Promise<InteractionResponse<boolean>>;
+    /** Edit the original (or deferred) response. */
+    editReply(input: ReplyInput): Promise<Message>;
+    /** Add an additional message after the initial response. */
+    followUp(input: ReplyInput): Promise<Message>;
+    /**
+     * State-aware send: replies, edits a deferred response, or follows up —
+     * whichever is valid given the current interaction state. The single method
+     * most handlers ever need.
+     */
+    send(input: ReplyInput): 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;
+}
 
 /**
  * Rate-limit commands per user, per role, per guild, per channel or globally.
@@ -214,57 +577,102 @@ declare class CooldownManager {
 /** Build the user-facing message for a blocked action. */
 declare function formatCooldownMessage(config: CooldownConfig, remainingMs: number): string;
 
-/** Reply options with an ergonomic `ephemeral` shortcut (mapped to flags). */
-type ReplyData = InteractionReplyOptions & {
-    ephemeral?: boolean;
-};
-/** Either a plain string or full reply options. */
-type ReplyInput = string | ReplyData;
-/** Normalises spearkit reply input into a discord.js reply payload. */
-declare function normalizeReply(input: ReplyInput): InteractionReplyOptions;
-/** Marks an input as ephemeral, regardless of how it was passed. */
-declare function asEphemeral(input: ReplyInput): ReplyData;
+/** 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;
 /**
- * Ergonomic base wrapper shared by every interaction context (commands,
- * buttons, selects, modals). Exposes the common actor/location accessors plus
- * reply helpers that smooth over discord.js' state machine.
+ * 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 abstract class BaseContext<I extends RepliableInteraction = RepliableInteraction> {
-    readonly interaction: I;
-    constructor(interaction: I);
-    get client(): I["client"];
-    get user(): discord_js.User;
-    get member(): discord_js.GuildMember | discord_js.APIInteractionGuildMember | null;
-    get guild(): discord_js.Guild | null;
-    get guildId(): string | null;
-    get channel(): discord_js.TextBasedChannel | null;
-    get channelId(): string | null;
-    get locale(): discord_js.Locale;
-    /** Whether the interaction is already deferred. */
-    get deferred(): boolean;
-    /** Whether the interaction already received an initial response. */
-    get replied(): boolean;
-    /** Send the initial response to the interaction. */
-    reply(input: ReplyInput): Promise<InteractionResponse<boolean>>;
-    /** Reply, but always hidden to everyone except the invoking user. */
-    replyEphemeral(input: ReplyInput): Promise<InteractionResponse<boolean>>;
-    /** Acknowledge now and respond later via {@link editReply}. */
-    defer(options?: {
-        ephemeral?: boolean;
-    }): Promise<InteractionResponse<boolean>>;
-    /** Edit the original (or deferred) response. */
-    editReply(input: ReplyInput): Promise<Message>;
-    /** Add an additional message after the initial response. */
-    followUp(input: ReplyInput): Promise<Message>;
-    /**
-     * State-aware send: replies, edits a deferred response, or follows up —
-     * whichever is valid given the current interaction state. The single method
-     * most handlers ever need.
-     */
-    send(input: ReplyInput): Promise<void>;
-    /** State-aware ephemeral error message. */
-    error(message: string): Promise<void>;
+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
@@ -426,6 +834,8 @@ interface CommonMeta {
     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 {
@@ -479,6 +889,7 @@ interface SlashCommandSpec {
     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
@@ -495,6 +906,8 @@ declare class SlashCommand {
     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. */
@@ -525,88 +938,6 @@ declare function subcommandGroup(config: SubcommandGroupConfig): SubcommandGroup
 /** Define a command that routes to subcommands and/or subcommand groups. */
 declare function commandGroup(config: CommandGroupConfig): SlashCommand;
 
-/** What kind of interaction was used. */
-type UsageType = "command" | "prefix" | "component" | "event";
-/** 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;
-}
-/** 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;
-}
-
 /** Error hook invoked when a command handler throws. */
 type CommandErrorHandler = (error: Error, interaction: ChatInputCommandInteraction) => Awaitable<void>;
 /** Options for pushing commands to discord. */
@@ -629,6 +960,7 @@ declare class CommandRegistry {
     private logger?;
     private cooldowns?;
     private defaultCooldown?;
+    private defaultGuards;
     private onUsage?;
     /** Register one or more commands. Later registrations override by name. */
     add(...commands: SlashCommand[]): this;
@@ -648,6 +980,8 @@ declare class CommandRegistry {
     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. */
@@ -665,6 +999,7 @@ declare class CommandRegistry {
     deploy(options: DeployOptions): Promise<DeployResult>;
     private defaultErrorReply;
     private replyCooldown;
+    private replyDenied;
 }
 
 /** A typed handler for a discord.js client event. */
@@ -721,6 +1056,7 @@ declare class EventRegistry {
 interface RouteBase {
     readonly namespace: string;
     readonly paramNames: readonly string[];
+    readonly guards?: readonly Guard[];
 }
 /** Routing entry for a button. */
 interface ButtonRoute extends RouteBase {
@@ -777,6 +1113,7 @@ declare class ComponentRegistry {
     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. */
@@ -785,44 +1122,313 @@ declare class ComponentRegistry {
     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;
     /**
-     * Dispatch an interaction to its component handler. Returns `true` if a
-     * handler matched and ran, `false` otherwise.
+     * Dispatch an interaction to its component handler. Returns `true` if a
+     * handler matched and ran, `false` otherwise.
+     */
+    handle(interaction: Interaction): Promise<boolean>;
+    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".
      */
-    handle(interaction: Interaction): Promise<boolean>;
-    private exec;
+    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;
 }
 
-/**
- * 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 {
+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;
-    setup(client: SpearClient): Awaitable<void>;
+    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;
 }
-/** 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;
+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;
 }
 /**
- * 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.
+ * Build a typed argument schema for {@link prefixCommand}. Chain calls
+ * positionally — first token → first arg, second → second arg, etc.
  */
-declare function loadInto(client: SpearClient, dir: string, options?: LoadOptions): Promise<number>;
+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 {
@@ -836,7 +1442,7 @@ interface PrefixOptions {
     caseInsensitive?: boolean;
 }
 /** Configuration for a prefix command. */
-interface PrefixCommandConfig<R = void> {
+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. */
@@ -845,8 +1451,12 @@ interface PrefixCommandConfig<R = void> {
     description?: string;
     /** Rate-limit this command. A number is a duration in ms. */
     cooldown?: CooldownInput;
-    /** Handler invoked with a {@link PrefixContext}. */
-    run: (ctx: PrefixContext) => Awaitable<R>;
+    /** 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 {
@@ -855,12 +1465,14 @@ interface PrefixCommand {
     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<R = void>(config: PrefixCommandConfig<R>): PrefixCommand;
+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 {
+declare class PrefixContext<TArgs extends Record<string, unknown> = Record<string, never>> {
     /** The triggering message. */
     readonly message: Message;
     /** The matched command name (as typed). */
@@ -869,6 +1481,8 @@ declare class PrefixContext {
     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, 
@@ -877,13 +1491,15 @@ declare class PrefixContext {
     /** Whitespace-split arguments after the command name. */
     args: string[], 
     /** The raw text after the command name. */
-    rest: string);
+    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.PartialDMChannel | discord_js.PartialGroupDMChannel | discord_js.NewsChannel | discord_js.StageChannel | discord_js.TextChannel | discord_js.PublicThreadChannel<boolean> | discord_js.PrivateThreadChannel | discord_js.VoiceChannel;
+    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>;
@@ -901,6 +1517,7 @@ declare class PrefixRegistry {
     private cooldowns?;
     private defaultCooldown?;
     private errorHandler?;
+    private defaultGuards;
     private onUsage?;
     /** Configure prefixes and matching behaviour. */
     setOptions(input: string | readonly string[] | PrefixOptions): this;
@@ -910,6 +1527,8 @@ declare class PrefixRegistry {
     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). */
@@ -931,7 +1550,7 @@ declare class PrefixRegistry {
 }
 
 /** Anything that can be handed to {@link SpearClient.register}. */
-type Registerable = SlashCommand | EventDef | ComponentDef | ScheduledTask | PrefixCommand;
+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.
@@ -964,19 +1583,24 @@ interface SpearOptions {
     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 and
- * component registries plus interaction routing wired up automatically.
+ * 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.deployCommands({ guildId: "123" });
+ * await client.deployAllCommands({ guildId: "123" });
  * ```
  */
 declare class SpearClient extends Client {
@@ -996,11 +1620,15 @@ declare class SpearClient extends Client {
     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 and components in one call. Each item is routed
-     * to the matching registry based on its kind.
+     * Register commands, events, components, scheduled tasks, prefix commands
+     * and context menus in one call. Each item is routed to its matching registry.
      */
     register(...items: Registerable[]): this;
     /** Install one or more plugins, running each plugin's `setup`. */
@@ -1016,111 +1644,339 @@ declare class SpearClient extends Client {
      */
     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.
+     * 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>;
-    private route;
+    /**
+     * 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;
+}
 /**
- * Scheduled tasks: run work on a cron schedule or a fixed interval.
+ * 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.
  *
- * 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.
+ * 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";
+}
 /**
- * A parsed cron expression. Evaluates in the host's local time.
+ * 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
- * cron("*\u200b/5 * * * *").next();          // next 5-minute boundary
- * cron("@daily").next(new Date());           // next midnight
+ * 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.");
  * ```
  */
-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>;
+
+/** 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;
 }
-/** 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.
+ * 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 class TaskScheduler {
-    private readonly tasks;
-    private readonly timers;
-    private running;
-    private client?;
-    private logger?;
-    /** 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;
-    /** 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;
-}
+declare function confirm(interaction: RepliableInteraction, options: ConfirmOptions): Promise<ConfirmResult>;
 
 /**
  * Typed custom-id codec.
@@ -1244,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}. */
@@ -1280,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 {
@@ -1357,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}. */
@@ -1393,4 +2255,4 @@ declare function modal<const P extends string, F extends Record<string, TextInpu
  */
 declare function row<C extends MessageActionRowComponentBuilder>(...components: C[]): ActionRowBuilder<C>;
 
-export { type AllowedChannelType, type AnyComponentInteraction, type AnyOptionDef, AutocompleteContext, type AutocompleteHandler, BaseContext, type 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 CooldownActor, type CooldownConfig, type CooldownExemptions, type CooldownInput, CooldownManager, type CooldownOverrides, type CooldownResult, type CooldownScope, CronExpression, type DeployOptions, type DeployResult, type EntitySelectConfig, type EnvReader, type EventConfig, type EventDef, type EventHandler, EventRegistry, Intents, JsonFileUsageStore, type LinkButtonConfig, type LoadEnvOptions, type LoadOptions, type LogEntry, type LogLevel, type LogOptions, type LogSink, type LogThreshold, type LogValue, Logger, type LoggerOptions, MAX_CUSTOM_ID_LENGTH, MemoryUsageStore, 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 ParsedEnv, type PrefixCommand, type PrefixCommandConfig, PrefixContext, type PrefixErrorHandler, type PrefixOptions, PrefixRegistry, type Registerable, type ReplyData, type ReplyInput, type ResolvedOption, type ResolvedOptions, type RoleSelect, RoleSelectContext, type RoleSelectRoute, 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 UsageOptions, type UsageStore, UsageTracker, type UsageType, type UserSelect, UserSelectContext, type UserSelectRoute, asEphemeral, buildCustomId, button, channelSelect, collectModules, command, commandGroup, compilePattern, consoleSink, cron, definePlugin, effectiveDuration, env, event, formatCooldownMessage, formatUsage, linkButton, loadEnv, loadInto, mentionableSelect, modal, normalizeCooldown, normalizeReply, option, optionsHaveAutocomplete, paramsFromValues, parseCustomId, parseEnv, prefixCommand, readOption, roleSelect, row, stringSelect, subcommand, subcommandGroup, task, textInput, toAPIOption, toError, 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 };