spearkit 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,849 @@
+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';
+export * from 'discord.js';
+
+/** 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>;
+    /** State-aware ephemeral error message. */
+    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.
+ */
+type Opt = CommandInteractionOption;
+type UserValue = NonNullable<Opt["user"]>;
+type ChannelValue = NonNullable<Opt["channel"]>;
+type RoleValue = NonNullable<Opt["role"]>;
+type MentionableValue = NonNullable<Opt["user" | "role" | "member"]>;
+type AttachmentValue = Attachment;
+/** The discord-allowed channel types for a channel option. */
+type AllowedChannelType = NonNullable<APIApplicationCommandChannelOption["channel_types"]>[number];
+/** The reader surface spearkit needs off a chat-input interaction. */
+type OptionReader = ChatInputCommandInteraction["options"];
+/** The closed set of values a slash option can resolve to. */
+type OptionValue = string | number | boolean | UserValue | ChannelValue | RoleValue | MentionableValue | AttachmentValue;
+/** A single choice for string/integer/number options. */
+interface OptionChoice<V extends string | number = string | number> {
+    readonly name: string;
+    readonly value: V;
+    readonly nameLocalizations?: LocalizationMap;
+}
+/** Provides autocomplete suggestions for an option as the user types. */
+type AutocompleteHandler<V extends string | number = string | number> = (ctx: AutocompleteContext) => Awaitable<OptionChoice<V>[]>;
+/**
+ * A fully-described slash command option. The two type parameters are phantom
+ * markers used purely for compile-time inference of the resolved value:
+ * - `TValue` is the type produced for the command handler.
+ * - `TRequired` controls nullability (`true` => value, `false` => `| undefined`).
+ */
+interface OptionDef<TValue extends OptionValue, TRequired extends boolean> {
+    readonly type: ApplicationCommandOptionType;
+    readonly description: string;
+    readonly required: TRequired;
+    readonly choices?: readonly OptionChoice[];
+    readonly minValue?: number;
+    readonly maxValue?: number;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly channelTypes?: readonly AllowedChannelType[];
+    readonly autocomplete?: AutocompleteHandler;
+    readonly nameLocalizations?: LocalizationMap;
+    readonly descriptionLocalizations?: LocalizationMap;
+    /** Phantom-only marker. Never populated at runtime. */
+    readonly __value?: TValue;
+}
+/** Any option definition, regardless of value/required type. */
+type AnyOptionDef = OptionDef<OptionValue, boolean>;
+/** A map of option name => definition. */
+type OptionMap = Record<string, AnyOptionDef>;
+/** Maps an {@link OptionDef} to the value passed into the command handler. */
+type ResolvedOption<O extends AnyOptionDef> = O extends OptionDef<infer V, infer Req> ? Req extends true ? V : V | undefined : never;
+/** Resolves a whole {@link OptionMap} into the handler's `options` object. */
+type ResolvedOptions<O extends OptionMap> = {
+    [K in keyof O]: ResolvedOption<O[K]>;
+};
+interface BaseConfig {
+    readonly description: string;
+    readonly required?: boolean;
+    readonly nameLocalizations?: LocalizationMap;
+    readonly descriptionLocalizations?: LocalizationMap;
+}
+type IsRequired<C extends BaseConfig> = C["required"] extends true ? true : false;
+interface StringConfig extends BaseConfig {
+    readonly choices?: readonly OptionChoice<string>[];
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly autocomplete?: AutocompleteHandler<string>;
+}
+interface NumericConfig extends BaseConfig {
+    readonly choices?: readonly OptionChoice<number>[];
+    readonly minValue?: number;
+    readonly maxValue?: number;
+    readonly autocomplete?: AutocompleteHandler<number>;
+}
+interface ChannelConfig extends BaseConfig {
+    readonly channelTypes?: readonly AllowedChannelType[];
+}
+type ChoiceValue<C, Fallback extends string | number> = C extends {
+    readonly choices: readonly {
+        value: infer V;
+    }[];
+} ? [V] extends [string | number] ? V : Fallback : Fallback;
+/**
+ * Type-safe slash command option builders.
+ *
+ * @example
+ * ```ts
+ * options: {
+ *   target: option.user({ description: "Who to greet", required: true }),
+ *   loud: option.boolean({ description: "Shout it" }),
+ * }
+ * ```
+ */
+declare const option: {
+    readonly string: <const C extends StringConfig>(config: C) => OptionDef<ChoiceValue<C, string>, IsRequired<C>>;
+    readonly integer: <const C extends NumericConfig>(config: C) => OptionDef<ChoiceValue<C, number>, IsRequired<C>>;
+    readonly number: <const C extends NumericConfig>(config: C) => OptionDef<ChoiceValue<C, number>, IsRequired<C>>;
+    readonly boolean: <const C extends BaseConfig>(config: C) => OptionDef<boolean, IsRequired<C>>;
+    readonly user: <const C extends BaseConfig>(config: C) => OptionDef<UserValue, IsRequired<C>>;
+    readonly channel: <const C extends ChannelConfig>(config: C) => OptionDef<ChannelValue, IsRequired<C>>;
+    readonly role: <const C extends BaseConfig>(config: C) => OptionDef<RoleValue, IsRequired<C>>;
+    readonly mentionable: <const C extends BaseConfig>(config: C) => OptionDef<MentionableValue, IsRequired<C>>;
+    readonly attachment: <const C extends BaseConfig>(config: C) => OptionDef<AttachmentValue, IsRequired<C>>;
+};
+/** Converts a spearkit option definition into the discord REST option payload. */
+declare function toAPIOption(name: string, def: AnyOptionDef): APIApplicationCommandBasicOption;
+/** Reads a resolved option value off a discord.js option resolver. */
+declare function readOption(resolver: OptionReader, name: string, def: AnyOptionDef): OptionValue | undefined;
+/** True if any option in the map declares an autocomplete handler. */
+declare function optionsHaveAutocomplete(options: OptionMap): boolean;
+
+/** Metadata shared by every kind of command. */
+interface CommonMeta {
+    /** Permissions a member must have by default to see/use the command. */
+    defaultMemberPermissions?: PermissionResolvable | null;
+    /** Mark the command NSFW (age-restricted). */
+    nsfw?: boolean;
+    /** Restrict invocation to guilds only. */
+    guildOnly?: boolean;
+    nameLocalizations?: LocalizationMap;
+    descriptionLocalizations?: LocalizationMap;
+}
+/** Configuration for a leaf (non-subcommand) slash command. */
+interface CommandConfig<O extends OptionMap, R> extends CommonMeta {
+    name: string;
+    description: string;
+    options?: O;
+    run: (ctx: CommandContext<O>) => Awaitable<R>;
+}
+/** Configuration for one subcommand. */
+interface SubcommandConfig<O extends OptionMap, R> {
+    description: string;
+    options?: O;
+    nameLocalizations?: LocalizationMap;
+    descriptionLocalizations?: LocalizationMap;
+    run: (ctx: CommandContext<O>) => Awaitable<R>;
+}
+/** A type-erased, ready-to-run subcommand created with {@link subcommand}. */
+interface Subcommand {
+    readonly kind: "subcommand";
+    readonly description: string;
+    readonly options: OptionMap;
+    readonly nameLocalizations?: LocalizationMap;
+    readonly descriptionLocalizations?: LocalizationMap;
+    readonly hasAutocomplete: boolean;
+    readonly execute: (interaction: ChatInputCommandInteraction) => Promise<void>;
+    readonly autocomplete: (interaction: AutocompleteInteraction) => Promise<void>;
+}
+/** Configuration for a subcommand group (a folder of subcommands). */
+interface SubcommandGroupConfig {
+    description: string;
+    subcommands: Record<string, Subcommand>;
+    nameLocalizations?: LocalizationMap;
+    descriptionLocalizations?: LocalizationMap;
+}
+/** A subcommand group created with {@link subcommandGroup}. */
+interface SubcommandGroup extends SubcommandGroupConfig {
+    readonly kind: "group";
+}
+/** Configuration for a command that contains subcommands and/or groups. */
+interface CommandGroupConfig extends CommonMeta {
+    name: string;
+    description: string;
+    subcommands?: Record<string, Subcommand>;
+    groups?: Record<string, SubcommandGroup>;
+}
+/** Everything {@link SlashCommand} needs, pre-built by the factories. */
+interface SlashCommandSpec {
+    name: string;
+    json: RESTPostAPIChatInputApplicationCommandsJSONBody;
+    hasAutocomplete: boolean;
+    executor: (interaction: ChatInputCommandInteraction) => Promise<void>;
+    autocompleter: (interaction: AutocompleteInteraction) => Promise<void>;
+}
+/**
+ * A registered slash command. Serialises itself for the discord REST API and
+ * executes its matching interactions. Construct via {@link command} or
+ * {@link commandGroup} rather than directly.
+ */
+declare class SlashCommand {
+    /** The top-level command name (used as the registry lookup key). */
+    readonly name: string;
+    /** Whether any option declares an autocomplete handler. */
+    readonly hasAutocomplete: boolean;
+    private readonly json;
+    private readonly executor;
+    private readonly autocompleter;
+    /** @internal */
+    constructor(spec: SlashCommandSpec);
+    /** Serialise to the discord REST chat-input command payload. */
+    toJSON(): RESTPostAPIChatInputApplicationCommandsJSONBody;
+    /** Execute the command for an incoming chat-input interaction. */
+    execute(interaction: ChatInputCommandInteraction): Promise<void>;
+    /** Execute autocomplete for the focused option. */
+    autocomplete(interaction: AutocompleteInteraction): Promise<void>;
+}
+/**
+ * Define a slash command with type-safe options and a co-located handler.
+ *
+ * @example
+ * ```ts
+ * export default command({
+ *   name: "echo",
+ *   description: "Repeat a message",
+ *   options: { msg: option.string({ description: "Text", required: true }) },
+ *   run: (ctx) => ctx.reply(ctx.options.msg),
+ * });
+ * ```
+ */
+declare function command<O extends OptionMap = Record<string, never>, R = void>(config: CommandConfig<O, R>): SlashCommand;
+/** Define a single subcommand with type-safe options and a handler. */
+declare function subcommand<O extends OptionMap = Record<string, never>, R = void>(config: SubcommandConfig<O, R>): Subcommand;
+/** Group several subcommands under a shared name. */
+declare function subcommandGroup(config: SubcommandGroupConfig): SubcommandGroup;
+/** Define a command that routes to subcommands and/or subcommand groups. */
+declare function commandGroup(config: CommandGroupConfig): SlashCommand;
+
+/** Error hook invoked when a command handler throws. */
+type CommandErrorHandler = (error: Error, interaction: ChatInputCommandInteraction) => Awaitable<void>;
+/** Options for pushing commands to discord. */
+interface DeployOptions {
+    /** Bot token. Falls back to the client token when omitted. */
+    token?: string;
+    /** Application (client) id. */
+    applicationId: string;
+    /** Deploy to a single guild (updates instantly) instead of globally. */
+    guildId?: string;
+    /** Reuse an existing REST instance instead of creating one. */
+    rest?: REST;
+}
+/** Result of a {@link CommandRegistry.deploy} call. */
+type DeployResult = RESTPutAPIApplicationCommandsResult | RESTPutAPIApplicationGuildCommandsResult;
+/** Holds every slash command and routes interactions to them. */
+declare class CommandRegistry {
+    private readonly commands;
+    private errorHandler?;
+    /** Register one or more commands. Later registrations override by name. */
+    add(...commands: SlashCommand[]): this;
+    /** Remove a command by name. */
+    remove(name: string): boolean;
+    /** Look up a command by name. */
+    get(name: string): SlashCommand | undefined;
+    /** All registered commands. */
+    all(): SlashCommand[];
+    /** All registered command names. */
+    get names(): string[];
+    /** Number of registered commands. */
+    get size(): number;
+    /** Set the handler used when a command throws. */
+    onError(handler: CommandErrorHandler): this;
+    /** Serialise every command to discord REST payloads. */
+    toJSON(): RESTPostAPIApplicationCommandsJSONBody[];
+    /** Dispatch an incoming chat-input interaction to its command. */
+    handle(interaction: ChatInputCommandInteraction): Promise<void>;
+    /** Dispatch an autocomplete interaction to its command. */
+    handleAutocomplete(interaction: AutocompleteInteraction): Promise<void>;
+    /**
+     * Push the registered commands to discord. Returns the API response.
+     *
+     * Guild deploys apply instantly and are ideal during development; global
+     * deploys can take up to an hour to propagate.
+     */
+    deploy(options: DeployOptions): Promise<DeployResult>;
+    private defaultErrorReply;
+}
+
+/** A typed handler for a discord.js client event. */
+type EventHandler<E extends keyof ClientEvents> = (...args: ClientEvents[E]) => Awaitable<void>;
+/** Object form accepted by {@link event}. */
+interface EventConfig<E extends keyof ClientEvents> {
+    name: E;
+    /** Run the handler at most once, then auto-detach. */
+    once?: boolean;
+    run: EventHandler<E>;
+}
+/**
+ * A type-erased, ready-to-attach event listener. Built by {@link event}; the
+ * concrete event type is captured in the closures so binding stays type-safe.
+ */
+interface EventDef {
+    readonly name: keyof ClientEvents;
+    readonly once: boolean;
+    /** Attach the listener to a client. */
+    attach(client: Client): void;
+    /** Remove the listener from a client it was attached to. */
+    detach(client: Client): void;
+}
+/**
+ * Define a discord.js event listener with a fully-typed handler. Thrown errors
+ * and rejected promises are routed to the client's `error` event instead of
+ * crashing the process.
+ *
+ * @example
+ * ```ts
+ * export default event("messageCreate", (message) => {
+ *   if (message.author.bot) return;
+ *   // message is fully typed as Message
+ * });
+ * ```
+ */
+declare function event<E extends keyof ClientEvents>(name: E, run: EventHandler<E>): EventDef;
+declare function event<E extends keyof ClientEvents>(config: EventConfig<E>): EventDef;
+/** Holds event listeners and attaches them to clients in bulk. */
+declare class EventRegistry {
+    private readonly events;
+    private readonly attached;
+    /** Register one or more event definitions. */
+    add(...defs: EventDef[]): this;
+    /** Number of registered listeners. */
+    get size(): number;
+    /** Attach every registered listener to the client. */
+    attachAll(client: Client): void;
+    /** Detach every registered listener from the client. */
+    detachAll(client: Client): void;
+}
+
+/**
+ * Typed custom-id codec.
+ *
+ * Patterns follow the grammar `namespace(:{param})*`, e.g. `"vote"` or
+ * `"vote:{choice}"` or `"page:{id}:{dir}"`. The `namespace` is the routing key;
+ * each `{param}` becomes a positional, percent-escaped value in the encoded id.
+ * Param names are recovered at the type level so handlers get a typed `params`
+ * object and `build()` requires exactly the right params.
+ */
+/** Names of the `{param}` placeholders inside a pattern. */
+type ParamNames<S extends string> = S extends `${string}{${infer Name}}${infer Rest}` ? Name | ParamNames<Rest> : never;
+/** The params object a pattern resolves to (every value is a string). */
+type Params<S extends string> = {
+    [K in ParamNames<S>]: string;
+};
+/** Arguments `build()` accepts: none when the pattern has no params. */
+type BuildArgs<S extends string> = [ParamNames<S>] extends [never] ? [] : [params: Params<S>];
+/** The discord custom-id length limit. */
+declare const MAX_CUSTOM_ID_LENGTH = 100;
+/** A compiled pattern: its routing namespace and ordered param names. */
+interface CompiledPattern {
+    readonly pattern: string;
+    readonly namespace: string;
+    readonly paramNames: readonly string[];
+}
+/** Compile and validate a custom-id pattern. Throws on malformed input. */
+declare function compilePattern(pattern: string): CompiledPattern;
+/** Build a concrete custom-id from a compiled pattern and its params. */
+declare function buildCustomId(compiled: CompiledPattern, params: Readonly<Record<string, string>>): string;
+/** The namespace + raw values parsed out of an incoming custom-id. */
+interface ParsedCustomId {
+    readonly namespace: string;
+    readonly values: readonly string[];
+}
+/** Parse an incoming custom-id into its namespace and decoded values. */
+declare function parseCustomId(customId: string): ParsedCustomId;
+/** Map ordered values onto their param names. */
+declare function paramsFromValues(paramNames: readonly string[], values: readonly string[]): Record<string, string>;
+
+type UpdateInput = string | InteractionUpdateOptions;
+/** The concrete message-component interaction types (button + every select). */
+type AnyComponentInteraction = ButtonInteraction | StringSelectMenuInteraction | UserSelectMenuInteraction | RoleSelectMenuInteraction | ChannelSelectMenuInteraction | MentionableSelectMenuInteraction;
+/**
+ * Base context for message-component interactions (buttons and selects).
+ * Adds the component-only `update`/`deferUpdate`/`showModal` helpers and the
+ * routed, typed {@link params}.
+ */
+declare class MessageComponentContext<P, I extends AnyComponentInteraction = AnyComponentInteraction> extends BaseContext<I> {
+    /** Params extracted from the custom-id pattern. */
+    readonly params: P;
+    constructor(interaction: I, 
+    /** Params extracted from the custom-id pattern. */
+    params: P);
+    /** The raw custom-id that triggered this interaction. */
+    get customId(): string;
+    /** The message the component lives on. */
+    get message(): discord_js.Message<boolean>;
+    /** Edit the message this component belongs to. */
+    update(input: UpdateInput): Promise<void>;
+    /** Acknowledge the interaction without editing the message yet. */
+    deferUpdate(): Promise<void>;
+    /** Open a modal in response to this component. */
+    showModal(modal: JSONEncodable<APIModalInteractionResponseCallbackData> | ModalComponentData | ModalBuilder): Promise<void>;
+}
+/** Context for a button click. */
+declare class ButtonContext<P = Record<string, never>> extends MessageComponentContext<P, ButtonInteraction> {
+}
+/** Context for a string select; exposes the chosen {@link values}. */
+declare class StringSelectContext<P = Record<string, never>> extends MessageComponentContext<P, StringSelectMenuInteraction> {
+    /** All selected values. */
+    get values(): string[];
+    /** The first selected value, or `undefined` if none. */
+    get value(): string | undefined;
+}
+/** Context for a user select; exposes selected ids, users and members. */
+declare class UserSelectContext<P = Record<string, never>> extends MessageComponentContext<P, UserSelectMenuInteraction> {
+    get values(): string[];
+    get users(): discord_js.Collection<string, discord_js.User>;
+    get members(): discord_js.Collection<string, discord_js.GuildMember | discord_js.APIGuildMember>;
+}
+/** Context for a role select. */
+declare class RoleSelectContext<P = Record<string, never>> extends MessageComponentContext<P, RoleSelectMenuInteraction> {
+    get values(): string[];
+    get roles(): discord_js.Collection<string, discord_js.Role | discord_js.APIRole>;
+}
+/** Context for a channel select. */
+declare class ChannelSelectContext<P = Record<string, never>> extends MessageComponentContext<P, ChannelSelectMenuInteraction> {
+    get values(): string[];
+    get channels(): discord_js.Collection<string, discord_js.Channel | discord_js.APIChannel>;
+}
+/** Context for a mentionable (user + role) select. */
+declare class MentionableSelectContext<P = Record<string, never>> extends MessageComponentContext<P, MentionableSelectMenuInteraction> {
+    get values(): string[];
+    get users(): discord_js.Collection<string, discord_js.User>;
+    get roles(): discord_js.Collection<string, discord_js.Role | discord_js.APIRole>;
+    get members(): discord_js.Collection<string, discord_js.GuildMember | discord_js.APIGuildMember>;
+}
+/**
+ * Context for a submitted modal. Exposes the routed {@link params} plus the
+ * resolved text-input {@link fields}, keyed by the field names you declared.
+ */
+declare class ModalContext<P, F extends string = string> extends BaseContext<ModalSubmitInteraction> {
+    readonly params: P;
+    /** Submitted values, keyed by the field names from your modal definition. */
+    readonly fields: Record<F, string>;
+    constructor(interaction: ModalSubmitInteraction, params: P, 
+    /** Submitted values, keyed by the field names from your modal definition. */
+    fields: Record<F, string>);
+    /** The raw custom-id that triggered this modal submission. */
+    get customId(): string;
+}
+
+/** 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}. */
+interface ButtonConfig<P extends string, R> {
+    /** Custom-id pattern, e.g. `"vote"` or `"vote:{choice}"`. */
+    id: P;
+    label?: string;
+    style?: ButtonStyleInput;
+    emoji?: ComponentEmojiResolvable;
+    disabled?: boolean;
+    run: (ctx: ButtonContext<Params<P>>) => Awaitable<R>;
+}
+/** A registrable button with a typed {@link build}. */
+interface Button<P extends string> extends ButtonRoute {
+    build(...args: BuildArgs<P>): ButtonBuilder;
+}
+/**
+ * Define an interactive button: its appearance, its custom-id pattern and its
+ * click handler, all in one place. Register it with `client.components.add`.
+ *
+ * @example
+ * ```ts
+ * const vote = button({
+ *   id: "vote:{choice}",
+ *   label: "Yes",
+ *   style: "Success",
+ *   run: (ctx) => ctx.reply(`You chose ${ctx.params.choice}`),
+ * });
+ * row(vote.build({ choice: "yes" }));
+ * ```
+ */
+declare function button<const P extends string, R = void>(config: ButtonConfig<P, R>): Button<P>;
+/** Config for a link button (no handler — just opens a URL). */
+interface LinkButtonConfig {
+    url: string;
+    label?: string;
+    emoji?: ComponentEmojiResolvable;
+    disabled?: boolean;
+}
+/** Build a link button. Link buttons have no custom-id and run no handler. */
+declare function linkButton(config: LinkButtonConfig): ButtonBuilder;
+interface SelectConfigBase {
+    placeholder?: string;
+    minValues?: number;
+    maxValues?: number;
+    disabled?: boolean;
+}
+/** Config for a string select created with {@link stringSelect}. */
+interface StringSelectConfig<P extends string, R> extends SelectConfigBase {
+    id: P;
+    options: readonly SelectMenuComponentOptionData[];
+    run: (ctx: StringSelectContext<Params<P>>) => Awaitable<R>;
+}
+/** A registrable string select with a typed {@link build}. */
+interface StringSelect<P extends string> extends StringSelectRoute {
+    build(...args: BuildArgs<P>): StringSelectMenuBuilder;
+}
+/** Define a string select menu, its custom-id pattern and its handler. */
+declare function stringSelect<const P extends string, R = void>(config: StringSelectConfig<P, R>): StringSelect<P>;
+/** Config shared by the entity-select builders (user/role/channel/mentionable). */
+interface EntitySelectConfig<P extends string> extends SelectConfigBase {
+    id: P;
+}
+/** A registrable user select. */
+interface UserSelect<P extends string> extends UserSelectRoute {
+    build(...args: BuildArgs<P>): UserSelectMenuBuilder;
+}
+/** Define a user select menu. */
+declare function userSelect<const P extends string, R = void>(config: EntitySelectConfig<P> & {
+    run: (ctx: UserSelectContext<Params<P>>) => Awaitable<R>;
+}): UserSelect<P>;
+/** A registrable role select. */
+interface RoleSelect<P extends string> extends RoleSelectRoute {
+    build(...args: BuildArgs<P>): RoleSelectMenuBuilder;
+}
+/** Define a role select menu. */
+declare function roleSelect<const P extends string, R = void>(config: EntitySelectConfig<P> & {
+    run: (ctx: RoleSelectContext<Params<P>>) => Awaitable<R>;
+}): RoleSelect<P>;
+/** A registrable channel select. */
+interface ChannelSelect<P extends string> extends ChannelSelectRoute {
+    build(...args: BuildArgs<P>): ChannelSelectMenuBuilder;
+}
+/** Define a channel select menu, optionally restricted to channel types. */
+declare function channelSelect<const P extends string, R = void>(config: EntitySelectConfig<P> & {
+    channelTypes?: readonly ChannelType[];
+    run: (ctx: ChannelSelectContext<Params<P>>) => Awaitable<R>;
+}): ChannelSelect<P>;
+/** A registrable mentionable select. */
+interface MentionableSelect<P extends string> extends MentionableSelectRoute {
+    build(...args: BuildArgs<P>): MentionableSelectMenuBuilder;
+}
+/** Define a mentionable (user + role) select menu. */
+declare function mentionableSelect<const P extends string, R = void>(config: EntitySelectConfig<P> & {
+    run: (ctx: MentionableSelectContext<Params<P>>) => Awaitable<R>;
+}): MentionableSelect<P>;
+/** Accepted text-input styles. */
+type TextInputStyleInput = "Short" | "Paragraph" | TextInputStyle;
+/** A resolved text-input field definition. */
+interface TextInputDef {
+    readonly label: string;
+    readonly style: TextInputStyle;
+    readonly placeholder?: string;
+    readonly required?: boolean;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly value?: string;
+}
+/** Define a single modal text-input field. */
+declare function textInput(config: {
+    label: string;
+    style?: TextInputStyleInput;
+    placeholder?: string;
+    required?: boolean;
+    minLength?: number;
+    maxLength?: number;
+    value?: string;
+}): TextInputDef;
+/** Config for a modal created with {@link modal}. */
+interface ModalConfig<P extends string, F extends Record<string, TextInputDef>, R> {
+    id: P;
+    title: string;
+    fields: F;
+    run: (ctx: ModalContext<Params<P>, keyof F & string>) => Awaitable<R>;
+}
+/** A registrable modal with a typed {@link build}. */
+interface Modal<P extends string> extends ModalRoute {
+    build(...args: BuildArgs<P>): ModalBuilder;
+}
+/**
+ * Define a modal: its title, its custom-id pattern, its text-input fields and
+ * a submit handler. The handler receives the submitted values keyed by field
+ * name in `ctx.fields`.
+ *
+ * @example
+ * ```ts
+ * const feedback = modal({
+ *   id: "feedback:{ticket}",
+ *   title: "Feedback",
+ *   fields: { comment: textInput({ label: "Comment", style: "Paragraph" }) },
+ *   run: (ctx) => ctx.reply(`Thanks! (${ctx.params.ticket}): ${ctx.fields.comment}`),
+ * });
+ * ```
+ */
+declare function modal<const P extends string, F extends Record<string, TextInputDef>, R = void>(config: ModalConfig<P, F, R>): Modal<P>;
+
+/**
+ * Wrap one or more component builders in an action row.
+ *
+ * A row holds up to five buttons, or exactly one select menu.
+ *
+ * @example
+ * ```ts
+ * const components = [row(yes.build(), no.build())];
+ * await channel.send({ content: "Vote:", components });
+ * ```
+ */
+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 };