spearkit 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,7 +1,219 @@
 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 { 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';
 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.
+ *
+ * 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}.
+ */
+/** 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;
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const log = new Logger({ level: "debug" });
+ * 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;
+    /** 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;
+
+/** 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;
+
+/**
+ * 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.
+ */
+/** 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;
+};
+/**
+ * Resolve the cooldown an actor should serve. `null` means exempt (no
+ * cooldown). Otherwise a duration in milliseconds (which may be `0`).
+ */
+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;
+
 /** Reply options with an ergonomic `ephemeral` shortcut (mapped to flags). */
 type ReplyData = InteractionReplyOptions & {
     ephemeral?: boolean;
@@ -54,42 +266,6 @@ declare abstract class BaseContext<I extends RepliableInteraction = RepliableInt
     error(message: string): Promise<void>;
 }
 
-/**
- * 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>;
-}
-
 /**
  * Resolved runtime value types, derived directly from discord.js' option
  * resolver so spearkit stays exactly in lockstep with the underlying getters.
@@ -202,6 +378,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 +424,8 @@ interface CommonMeta {
     guildOnly?: boolean;
     nameLocalizations?: LocalizationMap;
     descriptionLocalizations?: LocalizationMap;
+    /** Rate-limit this command. A number is a duration in ms; see {@link CooldownConfig}. */
+    cooldown?: CooldownInput;
 }
 /** Configuration for a leaf (non-subcommand) slash command. */
 interface CommandConfig<O extends OptionMap, R> extends CommonMeta {
@@ -264,6 +478,7 @@ interface SlashCommandSpec {
     hasAutocomplete: boolean;
     executor: (interaction: ChatInputCommandInteraction) => Promise<void>;
     autocompleter: (interaction: AutocompleteInteraction) => Promise<void>;
+    cooldown?: CooldownConfig;
 }
 /**
  * A registered slash command. Serialises itself for the discord REST API and
@@ -278,6 +493,8 @@ declare class SlashCommand {
     private readonly json;
     private readonly executor;
     private readonly autocompleter;
+    /** Resolved cooldown configuration for this command, if any. */
+    readonly cooldown?: CooldownConfig;
     /** @internal */
     constructor(spec: SlashCommandSpec);
     /** Serialise to the discord REST chat-input command payload. */
@@ -308,6 +525,88 @@ 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. */
@@ -327,6 +626,10 @@ type DeployResult = RESTPutAPIApplicationCommandsResult | RESTPutAPIApplicationG
 declare class CommandRegistry {
     private readonly commands;
     private errorHandler?;
+    private logger?;
+    private cooldowns?;
+    private defaultCooldown?;
+    private onUsage?;
     /** Register one or more commands. Later registrations override by name. */
     add(...commands: SlashCommand[]): this;
     /** Remove a command by name. */
@@ -341,6 +644,12 @@ 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;
+    /** 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 +664,7 @@ declare class CommandRegistry {
      */
     deploy(options: DeployOptions): Promise<DeployResult>;
     private defaultErrorReply;
+    private replyCooldown;
 }
 
 /** A typed handler for a discord.js client event. */
@@ -407,6 +717,411 @@ declare class EventRegistry {
     detachAll(client: Client): void;
 }
 
+/** 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 string select. */
+interface StringSelectRoute extends RouteBase {
+    readonly kind: "stringSelect";
+    handle(interaction: StringSelectMenuInteraction, params: Record<string, string>): Promise<void>;
+}
+/** Routing entry for a user select. */
+interface UserSelectRoute extends RouteBase {
+    readonly kind: "userSelect";
+    handle(interaction: UserSelectMenuInteraction, params: Record<string, string>): Promise<void>;
+}
+/** Routing entry for a role select. */
+interface RoleSelectRoute extends RouteBase {
+    readonly kind: "roleSelect";
+    handle(interaction: RoleSelectMenuInteraction, params: Record<string, string>): Promise<void>;
+}
+/** Routing entry for a channel select. */
+interface ChannelSelectRoute extends RouteBase {
+    readonly kind: "channelSelect";
+    handle(interaction: ChannelSelectMenuInteraction, params: Record<string, string>): Promise<void>;
+}
+/** Routing entry for a mentionable select. */
+interface MentionableSelectRoute extends RouteBase {
+    readonly kind: "mentionableSelect";
+    handle(interaction: MentionableSelectMenuInteraction, params: Record<string, string>): Promise<void>;
+}
+/** Routing entry for a modal submission. */
+interface ModalRoute extends RouteBase {
+    readonly kind: "modal";
+    handle(interaction: ModalSubmitInteraction, params: Record<string, string>): Promise<void>;
+}
+/** Any registrable component routing entry. */
+type ComponentDef = ButtonRoute | StringSelectRoute | UserSelectRoute | RoleSelectRoute | ChannelSelectRoute | MentionableSelectRoute | ModalRoute;
+/** Error hook invoked when a component handler throws. */
+type ComponentErrorHandler = (error: Error, interaction: RepliableInteraction) => Awaitable<void>;
+/**
+ * Routes button, select and modal interactions to the handlers registered for
+ * their custom-id namespace. Decodes the custom-id, extracts typed params, and
+ * invokes the matching handler.
+ */
+declare class ComponentRegistry {
+    private readonly buttons;
+    private readonly stringSelects;
+    private readonly userSelects;
+    private readonly roleSelects;
+    private readonly channelSelects;
+    private readonly mentionableSelects;
+    private readonly modals;
+    private errorHandler?;
+    private logger?;
+    private onUsage?;
+    /** 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;
+    /** 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.
+     */
+    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>;
+
+/** 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<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;
+    /** Handler invoked with a {@link PrefixContext}. */
+    run: (ctx: PrefixContext) => 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 run: (ctx: PrefixContext) => Promise<void>;
+}
+/** Define a prefix command. */
+declare function prefixCommand<R = void>(config: PrefixCommandConfig<R>): PrefixCommand;
+/** The handler argument for a prefix command: the message plus parsed args. */
+declare class PrefixContext {
+    /** 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;
+    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);
+    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 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 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;
+    /** 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;
+/**
+ * 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;
+}
+/** 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.
+ *
+ * @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;
+    /** 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;
+    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(...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;
+    /** 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>;
+}
+
+/**
+ * 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?;
+    /** 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;
+}
+
 /**
  * Typed custom-id codec.
  *
@@ -519,78 +1234,6 @@ declare class ModalContext<P, F extends string = string> extends BaseContext<Mod
     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 string select. */
-interface StringSelectRoute extends RouteBase {
-    readonly kind: "stringSelect";
-    handle(interaction: StringSelectMenuInteraction, params: Record<string, string>): Promise<void>;
-}
-/** Routing entry for a user select. */
-interface UserSelectRoute extends RouteBase {
-    readonly kind: "userSelect";
-    handle(interaction: UserSelectMenuInteraction, params: Record<string, string>): Promise<void>;
-}
-/** Routing entry for a role select. */
-interface RoleSelectRoute extends RouteBase {
-    readonly kind: "roleSelect";
-    handle(interaction: RoleSelectMenuInteraction, params: Record<string, string>): Promise<void>;
-}
-/** Routing entry for a channel select. */
-interface ChannelSelectRoute extends RouteBase {
-    readonly kind: "channelSelect";
-    handle(interaction: ChannelSelectMenuInteraction, params: Record<string, string>): Promise<void>;
-}
-/** Routing entry for a mentionable select. */
-interface MentionableSelectRoute extends RouteBase {
-    readonly kind: "mentionableSelect";
-    handle(interaction: MentionableSelectMenuInteraction, params: Record<string, string>): Promise<void>;
-}
-/** Routing entry for a modal submission. */
-interface ModalRoute extends RouteBase {
-    readonly kind: "modal";
-    handle(interaction: ModalSubmitInteraction, params: Record<string, string>): Promise<void>;
-}
-/** Any registrable component routing entry. */
-type ComponentDef = ButtonRoute | StringSelectRoute | UserSelectRoute | RoleSelectRoute | ChannelSelectRoute | MentionableSelectRoute | ModalRoute;
-/** Error hook invoked when a component handler throws. */
-type ComponentErrorHandler = (error: Error, interaction: RepliableInteraction) => Awaitable<void>;
-/**
- * Routes button, select and modal interactions to the handlers registered for
- * their custom-id namespace. Decodes the custom-id, extracts typed params, and
- * invokes the matching handler.
- */
-declare class ComponentRegistry {
-    private readonly buttons;
-    private readonly stringSelects;
-    private readonly userSelects;
-    private readonly roleSelects;
-    private readonly channelSelects;
-    private readonly mentionableSelects;
-    private readonly modals;
-    private errorHandler?;
-    /** 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;
-    /** 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.
-     */
-    handle(interaction: Interaction): Promise<boolean>;
-    private exec;
-}
-
 /** 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}. */
@@ -750,100 +1393,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 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 };