novaapp-sdk 1.0.10 → 1.2.0

package/dist/index.d.mts

@@ -60,6 +60,59 @@ interface Member {
         isBot: boolean;
     };
 }
+type ChannelType = 'TEXT' | 'VOICE' | 'ANNOUNCEMENT' | 'FORUM' | 'STAGE';
+interface Channel {
+    id: string;
+    name: string;
+    type: ChannelType;
+    serverId: string | null;
+    topic: string | null;
+    position: number;
+    isNsfw: boolean;
+    slowMode: number | null;
+    createdAt: string;
+}
+interface Role {
+    id: string;
+    name: string;
+    color: string | null;
+    position: number;
+    serverId: string;
+    hoist: boolean;
+    permissions: Record<string, boolean>;
+    createdAt: string;
+}
+interface BanEntry {
+    userId: string;
+    username: string;
+    displayName: string;
+    avatar: string | null;
+    reason: string | null;
+    bannedAt: string;
+    moderatorId: string | null;
+}
+interface Invite {
+    code: string;
+    serverId: string;
+    creatorId: string;
+    uses: number;
+    maxUses: number | null;
+    expiresAt: string | null;
+    createdAt: string;
+}
+/** A message with all reaction data fetched. */
+interface ReactionDetail {
+    emoji: string;
+    count: number;
+    users: Array<{
+        id: string;
+        username: string;
+        displayName: string;
+        avatar: string | null;
+    }>;
+}
+/** Bot status that can be set via `client.setStatus()`. */
+type BotStatus = 'ONLINE' | 'IDLE' | 'DND' | 'OFFLINE';
 interface Attachment {
     id: string;
     url: string;
@@ -80,25 +133,35 @@ interface EmbedField {
 interface Embed {
     title?: string;
     description?: string;
+    /** Makes the title a clickable link. */
     url?: string;
-    color?: number;
+    /** Hex colour string — e.g. `'#5865F2'`. */
+    color?: string;
     thumbnail?: string;
     image?: string;
     footer?: string;
     fields?: EmbedField[];
     timestamp?: string;
+    author?: {
+        name: string;
+        iconUrl?: string;
+    };
 }
 interface MessageComponent {
     type: 'button' | 'select';
-    customId: string;
+    customId?: string;
     label?: string;
-    style?: 'primary' | 'secondary' | 'success' | 'danger';
+    style?: 'primary' | 'secondary' | 'success' | 'danger' | 'link';
+    emoji?: string;
+    url?: string;
     placeholder?: string;
     options?: Array<{
         label: string;
         value: string;
         description?: string;
     }>;
+    minValues?: number;
+    maxValues?: number;
     disabled?: boolean;
 }
 interface Message {
@@ -268,6 +331,24 @@ interface PollInteractionsOptions {
     limit?: number;
     since?: string;
 }
+interface CreateChannelOptions {
+    name: string;
+    type?: ChannelType;
+    topic?: string;
+    position?: number;
+    isNsfw?: boolean;
+    slowMode?: number;
+}
+interface EditChannelOptions {
+    name?: string;
+    topic?: string;
+    position?: number;
+    isNsfw?: boolean;
+    slowMode?: number;
+}
+interface FetchChannelsOptions {
+    type?: ChannelType;
+}
 /** A raw permission record stored for a specific scope (server, role, or channel). */
 interface BotPermissionRecord {
     id: string;
@@ -306,41 +387,10 @@ interface NovaClientOptions {
     token: string;
     /**
      * Base URL of the Nova server.
-     * @default "https://api.nova.chat"
+     * @default "https://novachatapp.com"
      */
     baseUrl?: string;
 }
-interface NovaClientEvents {
-    /** Fired when the bot successfully connects and is identified. */
-    ready: (bot: BotApplication) => void;
-    /** Fired for every bot:event from the gateway. */
-    event: (event: BotEvent) => void;
-    /** Fired when an interaction is created (slash command, button, etc.). */
-    interactionCreate: (interaction: Interaction) => void;
-    /** Fired when the gateway connection is lost. */
-    disconnect: (reason: string) => void;
-    /** Fired on gateway/API errors. */
-    error: (err: {
-        code: number;
-        message: string;
-    }) => void;
-    /** A message was sent in a channel the bot is in. */
-    messageCreate: (data: BotEvent['data']) => void;
-    /** A message was edited. */
-    messageUpdate: (data: BotEvent['data']) => void;
-    /** A message was deleted. */
-    messageDelete: (data: BotEvent['data']) => void;
-    /** A reaction was added to a message. */
-    reactionAdd: (data: BotEvent['data']) => void;
-    /** A reaction was removed from a message. */
-    reactionRemove: (data: BotEvent['data']) => void;
-    /** A user joined a server the bot is in. */
-    memberAdd: (data: BotEvent['data']) => void;
-    /** A user left a server the bot is in. */
-    memberRemove: (data: BotEvent['data']) => void;
-    /** A user started typing. */
-    typingStart: (data: BotEvent['data']) => void;
-}
 
 declare class MessagesAPI {
     private readonly http;
@@ -375,6 +425,64 @@ declare class MessagesAPI {
     typing(channelId: string): Promise<{
         ok: true;
     }>;
+    /**
+     * Fetch a single message by ID.
+     *
+     * @example
+     * const msg = await client.messages.fetchOne('message-id')
+     */
+    fetchOne(messageId: string): Promise<Message>;
+    /**
+     * Pin a message in its channel.
+     * The bot must have the `messages.manage` scope.
+     *
+     * @example
+     * await client.messages.pin('message-id')
+     */
+    pin(messageId: string): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Unpin a message.
+     *
+     * @example
+     * await client.messages.unpin('message-id')
+     */
+    unpin(messageId: string): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Fetch all pinned messages in a channel.
+     *
+     * @example
+     * const pins = await client.messages.fetchPinned('channel-id')
+     */
+    fetchPinned(channelId: string): Promise<Message[]>;
+    /**
+     * Add a reaction to a message.
+     *
+     * @example
+     * await client.messages.addReaction('message-id', '👍')
+     */
+    addReaction(messageId: string, emoji: string): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Remove the bot's reaction from a message.
+     *
+     * @example
+     * await client.messages.removeReaction('message-id', '👍')
+     */
+    removeReaction(messageId: string, emoji: string): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Fetch all reactions on a message.
+     *
+     * @example
+     * const reactions = await client.messages.fetchReactions('message-id')
+     */
+    fetchReactions(messageId: string): Promise<ReactionDetail[]>;
 }
 
 declare class CommandsAPI {
@@ -481,6 +589,56 @@ declare class MembersAPI {
     ban(serverId: string, userId: string, reason?: string): Promise<{
         ok: true;
     }>;
+    /**
+     * Unban a previously banned user.
+     * Requires the `members.ban` scope.
+     *
+     * @example
+     * await client.members.unban('server-id', 'user-id')
+     */
+    unban(serverId: string, userId: string): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Fetch the ban list for a server.
+     * Requires the `members.ban` scope.
+     *
+     * @example
+     * const bans = await client.members.listBans('server-id')
+     * for (const ban of bans) {
+     *   console.log(`${ban.username} — ${ban.reason ?? 'No reason'}`)
+     * }
+     */
+    listBans(serverId: string): Promise<BanEntry[]>;
+    /**
+     * Send a direct message to a user (DM).
+     * Requires the `messages.write` scope.
+     *
+     * @example
+     * await client.members.dm('user-id', { content: 'Hello!' })
+     * await client.members.dm('user-id', 'Hello from the bot!')
+     */
+    dm(userId: string, options: string | Omit<SendMessageOptions, 'replyToId'>): Promise<Message>;
+    /**
+     * Add a role to a member.
+     * Requires the `members.roles` scope.
+     *
+     * @example
+     * await client.members.addRole('server-id', 'user-id', 'role-id')
+     */
+    addRole(serverId: string, userId: string, roleId: string): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Remove a role from a member.
+     * Requires the `members.roles` scope.
+     *
+     * @example
+     * await client.members.removeRole('server-id', 'user-id', 'role-id')
+     */
+    removeRole(serverId: string, userId: string, roleId: string): Promise<{
+        ok: true;
+    }>;
 }
 
 declare class ServersAPI {
@@ -494,6 +652,15 @@ declare class ServersAPI {
      * console.log(`Bot is in ${servers.length} servers`)
      */
     list(): Promise<NovaServer[]>;
+    /**
+     * Fetch all roles in a server.
+     * Results are sorted by position (lowest first).
+     *
+     * @example
+     * const roles = await client.servers.listRoles('server-id')
+     * const adminRole = roles.find(r => r.name === 'Admin')
+     */
+    listRoles(serverId: string): Promise<Role[]>;
 }
 
 declare class InteractionsAPI {
@@ -619,67 +786,742 @@ declare class PermissionsAPI {
     get(options: PermissionsQueryOptions): Promise<PermissionsResult>;
 }
 
+declare class ChannelsAPI {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Fetch all channels in a server the bot is a member of.
+     *
+     * @example
+     * const channels = await client.channels.list('server-id')
+     * const textChannels = channels.filter(c => c.type === 'TEXT')
+     */
+    list(serverId: string): Promise<Channel[]>;
+    /**
+     * Fetch a single channel by ID.
+     *
+     * @example
+     * const channel = await client.channels.fetch('channel-id')
+     * console.log(channel.name, channel.type)
+     */
+    fetch(channelId: string): Promise<Channel>;
+    /**
+     * Create a new channel in a server.
+     * Requires the `channels.manage` scope.
+     *
+     * @example
+     * const channel = await client.channels.create('server-id', {
+     *   name: 'announcements',
+     *   type: 'ANNOUNCEMENT',
+     *   topic: 'Official announcements only',
+     * })
+     */
+    create(serverId: string, options: CreateChannelOptions): Promise<Channel>;
+    /**
+     * Edit an existing channel.
+     * Requires the `channels.manage` scope.
+     *
+     * @example
+     * await client.channels.edit('channel-id', { topic: 'New topic!' })
+     */
+    edit(channelId: string, options: EditChannelOptions): Promise<Channel>;
+    /**
+     * Delete a channel.
+     * Requires the `channels.manage` scope.
+     *
+     * @example
+     * await client.channels.delete('channel-id')
+     */
+    delete(channelId: string): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Fetch messages from a channel.
+     *
+     * @example
+     * const messages = await client.channels.fetchMessages('channel-id', { limit: 50 })
+     */
+    fetchMessages(channelId: string, options?: FetchMessagesOptions): Promise<Message[]>;
+    /**
+     * Fetch all pinned messages in a channel.
+     *
+     * @example
+     * const pins = await client.channels.fetchPins('channel-id')
+     */
+    fetchPins(channelId: string): Promise<Message[]>;
+    /**
+     * Send a typing indicator in a channel.
+     * Displayed to users for ~5 seconds.
+     *
+     * @example
+     * await client.channels.startTyping('channel-id')
+     */
+    startTyping(channelId: string): Promise<{
+        ok: true;
+    }>;
+}
+
+declare class ReactionsAPI {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Add a reaction to a message.
+     * Use a plain emoji character or a custom emoji ID.
+     *
+     * @example
+     * await client.reactions.add('message-id', '👍')
+     * await client.reactions.add('message-id', '🎉')
+     */
+    add(messageId: string, emoji: string): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Remove the bot's reaction from a message.
+     *
+     * @example
+     * await client.reactions.remove('message-id', '👍')
+     */
+    remove(messageId: string, emoji: string): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Remove all reactions from a message.
+     * Requires the `messages.manage` scope.
+     *
+     * @example
+     * await client.reactions.removeAll('message-id')
+     */
+    removeAll(messageId: string): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Remove all reactions of a specific emoji from a message.
+     * Requires the `messages.manage` scope.
+     *
+     * @example
+     * await client.reactions.removeEmoji('message-id', '👍')
+     */
+    removeEmoji(messageId: string, emoji: string): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Fetch all reactions on a message, broken down by emoji.
+     *
+     * @example
+     * const reactions = await client.reactions.fetch('message-id')
+     * for (const r of reactions) {
+     *   console.log(`${r.emoji} — ${r.count} reactions from ${r.users.map(u => u.username).join(', ')}`)
+     * }
+     */
+    fetch(messageId: string): Promise<ReactionDetail[]>;
+    /**
+     * Fetch reactions for a specific emoji on a message.
+     *
+     * @example
+     * const detail = await client.reactions.fetchEmoji('message-id', '👍')
+     * console.log(`${detail.count} thumbs ups`)
+     */
+    fetchEmoji(messageId: string, emoji: string): Promise<ReactionDetail>;
+}
+
+type TextInputStyle = 'short' | 'paragraph';
 /**
- * The main Nova bot client.
+ * Fluent builder for a single text-input field inside a modal.
  *
  * @example
- * import { NovaClient } from 'nova-bot-sdk'
+ * new TextInputBuilder()
+ *   .setCustomId('reason')
+ *   .setLabel('Reason')
+ *   .setStyle('paragraph')
+ *   .setPlaceholder('Describe the issue in detail…')
+ *   .setRequired(true)
+ *   .setMaxLength(1000)
+ */
+declare class TextInputBuilder {
+    private _data;
+    /** Unique ID for this field — the key in `interaction.modalData` on submit. */
+    setCustomId(customId: string): this;
+    /** Label shown above the input inside the modal. */
+    setLabel(label: string): this;
+    /**
+     * Input style:
+     * - `'short'` — single-line text input
+     * - `'paragraph'` — multi-line textarea
+     */
+    setStyle(style: TextInputStyle): this;
+    /** Greyed-out hint text shown when the field is empty. */
+    setPlaceholder(placeholder: string): this;
+    /** Whether the user must fill in this field before submitting. */
+    setRequired(required?: boolean): this;
+    /** Minimum number of characters required. */
+    setMinLength(min: number): this;
+    /** Maximum number of characters allowed. */
+    setMaxLength(max: number): this;
+    /** Pre-filled default value. */
+    setValue(value: string): this;
+    toJSON(): BotModalField;
+}
+
+type FieldLike = TextInputBuilder | BotModalField;
+/**
+ * Fluent builder for bot modal dialogs.
  *
- * const client = new NovaClient({ token: 'nova_bot_...' })
+ * @example
+ * const modal = new ModalBuilder()
+ *   .setTitle('Submit a report')
+ *   .setCustomId('report_modal')
+ *   .addField(
+ *     new TextInputBuilder()
+ *       .setCustomId('reason')
+ *       .setLabel('Reason')
+ *       .setStyle('paragraph')
+ *       .setRequired(true)
+ *       .setMaxLength(1000)
+ *   )
+ *   .addField(
+ *     new TextInputBuilder()
+ *       .setCustomId('proof')
+ *       .setLabel('Evidence (optional URL)')
+ *       .setStyle('short')
+ *   )
  *
- * client.on('ready', (bot) => {
- *   console.log(`Logged in as ${bot.botUser.username}`)
+ * const submitted = await interaction.openModal(modal)
+ * if (submitted) {
+ *   const reason = submitted.modalData.reason
+ * }
+ */
+declare class ModalBuilder {
+    private _title;
+    private _customId;
+    private readonly _fields;
+    /** Title shown at the top of the modal dialog. */
+    setTitle(title: string): this;
+    /** Custom ID passed back with the `MODAL_SUBMIT` interaction. */
+    setCustomId(customId: string): this;
+    /** Add a single text-input field. */
+    addField(field: FieldLike): this;
+    /** Add multiple fields at once. */
+    addFields(...fields: FieldLike[]): this;
+    toJSON(): BotModalDefinition;
+}
+
+/**
+ * Typed accessor for slash- and prefix-command options.
+ * Available via `interaction.options`.
+ *
+ * @example
+ * client.command('ban', async (interaction) => {
+ *   const userId = interaction.options.getString('user', true)
+ *   const reason = interaction.options.getString('reason') ?? 'No reason given'
  * })
+ */
+declare class InteractionOptions {
+    private readonly _map;
+    constructor(data: unknown);
+    /** Whether this option was supplied by the user. */
+    has(name: string): boolean;
+    /** @overload Required — never returns `null`. */
+    getString(name: string, required: true): string;
+    /** @overload Optional — returns `null` when not supplied. */
+    getString(name: string, required?: false): string | null;
+    /** @overload Required — never returns `null`. */
+    getInteger(name: string, required: true): number;
+    /** @overload Optional — returns `null` when not supplied. */
+    getInteger(name: string, required?: false): number | null;
+    /** @overload Required — never returns `null`. */
+    getNumber(name: string, required: true): number;
+    /** @overload Optional — returns `null` when not supplied. */
+    getNumber(name: string, required?: false): number | null;
+    /** Returns `true` or `false`, or `null` if not supplied. */
+    getBoolean(name: string): boolean | null;
+    /**
+     * Returns the mentioned **user ID** string (type `USER` option).
+     * @overload Required.
+     */
+    getUser(name: string, required: true): string;
+    getUser(name: string, required?: false): string | null;
+    /**
+     * Returns the mentioned **channel ID** string (type `CHANNEL` option).
+     * @overload Required.
+     */
+    getChannel(name: string, required: true): string;
+    getChannel(name: string, required?: false): string | null;
+    /**
+     * Returns the mentioned **role ID** string (type `ROLE` option).
+     * @overload Required.
+     */
+    getRole(name: string, required: true): string;
+    getRole(name: string, required?: false): string | null;
+}
+/**
+ * Rich wrapper around a raw bot interaction.
+ * Returned by `interactionCreate`, `client.command()`, `client.button()`, `client.selectMenu()`.
  *
+ * @example
  * client.on('interactionCreate', async (interaction) => {
- *   if (interaction.commandName === 'ping') {
- *     await client.interactions.respond(interaction.id, { content: 'Pong!' })
+ *   if (interaction.isSlashCommand() && interaction.commandName === 'ping') {
+ *     await interaction.reply('Pong! 🏓')
  *   }
  * })
  *
- * await client.connect()
+ * // Or use built-in routing:
+ * client.command('ping', async (interaction) => {
+ *   await interaction.reply('Pong! 🏓')
+ * })
  */
-declare class NovaClient extends EventEmitter {
-    /** The authenticated bot application. Available after `ready` fires. */
-    botUser: BotApplication | null;
-    /** Send, edit, delete and fetch messages. */
-    readonly messages: MessagesAPI;
-    /** Register and manage slash, prefix, and context menu commands. */
-    readonly commands: CommandsAPI;
-    /** List, kick and ban server members. */
-    readonly members: MembersAPI;
-    /** List servers the bot is a member of. */
-    readonly servers: ServersAPI;
-    /** Acknowledge and respond to interactions. */
-    readonly interactions: InteractionsAPI;
-    /** Query the bot's effective permissions within a server, channel, or role scope. */
-    readonly permissions: PermissionsAPI;
-    private socket;
-    private readonly http;
-    private readonly options;
-    constructor(options: NovaClientOptions);
+declare class NovaInteraction {
+    private readonly _raw;
+    private readonly _api;
+    /** Unique interaction ID. */
+    readonly id: string;
+    /** Interaction type. Use type guards (`.isSlashCommand()` etc.) for narrowing. */
+    readonly type: InteractionType;
+    /** Command name — set for `SLASH_COMMAND` and `PREFIX_COMMAND` interactions. */
+    readonly commandName: string | null;
+    /** Component custom ID — set for `BUTTON_CLICK`, `SELECT_MENU`, and `MODAL_SUBMIT` interactions. */
+    readonly customId: string | null;
+    /** ID of the user who triggered this interaction. */
+    readonly userId: string;
+    /** ID of the channel where this interaction occurred. */
+    readonly channelId: string;
+    /** ID of the server where this interaction occurred (`null` in DMs). */
+    readonly serverId: string | null;
+    /** ID of the message that contained the button/select component (if any). */
+    readonly triggerMsgId: string | null;
+    /** Selected option values for `SELECT_MENU` interactions. */
+    readonly values: string[];
     /**
-     * Connect to the Nova WebSocket gateway.
-     * Resolves when the `ready` event is received.
+     * Field values submitted in a `MODAL_SUBMIT` interaction.
+     * Keys are the `customId`s of the `TextInputBuilder` fields.
      *
      * @example
-     * await client.connect()
+     * const reason = interaction.modalData.reason
      */
-    connect(): Promise<void>;
+    readonly modalData: Record<string, string>;
+    /** ISO timestamp of when the interaction was created. */
+    readonly createdAt: string;
     /**
-     * Disconnect from the gateway and clean up.
+     * Typed accessor for slash/prefix command options.
+     *
+     * @example
+     * const userId = interaction.options.getUser('user', true)
+     * const reason = interaction.options.getString('reason') ?? 'No reason given'
      */
-    disconnect(): void;
+    readonly options: InteractionOptions;
+    constructor(_raw: Interaction, _api: InteractionsAPI);
+    /** `true` when triggered by a `/slash` command. */
+    isSlashCommand(): boolean;
+    /** `true` when triggered by a `!prefix` command. */
+    isPrefixCommand(): boolean;
+    /** `true` for both slash and prefix commands. */
+    isCommand(): boolean;
+    /** `true` when a button component was clicked. */
+    isButton(): boolean;
+    /** `true` when a select-menu option was chosen. */
+    isSelectMenu(): boolean;
+    /** `true` when the user submitted a modal form. */
+    isModalSubmit(): boolean;
+    /** `true` during autocomplete suggestion requests. */
+    isAutocomplete(): boolean;
+    /** `true` when triggered via a context-menu command. */
+    isContextMenu(): boolean;
     /**
-     * Send a message via the WebSocket gateway (lower latency than HTTP).
-     * Requires the `messages.write` scope.
+     * Respond with a message.
+     * Accepts a plain string or a full options object.
      *
      * @example
-     * client.wsSend('channel-id', 'Hello from the gateway!')
+     * await interaction.reply('Pong! 🏓')
+     * await interaction.reply({ content: 'Done!', ephemeral: true })
+     * await interaction.reply({ embed: new EmbedBuilder().setTitle('Stats').toJSON() })
      */
-    wsSend(channelId: string, content: string): void;
-    /**
-     * Start a typing indicator via WebSocket.
+    reply(options: RespondInteractionOptions | string): Promise<Message | {
+        ok: true;
+        ephemeral: true;
+    }>;
+    /**
+     * Respond with a message **only visible to the user** who triggered the interaction.
+     *
+     * @example
+     * await interaction.replyEphemeral('Only you can see this!')
+     */
+    replyEphemeral(options: string | Omit<RespondInteractionOptions, 'ephemeral'>): Promise<{
+        ok: true;
+        ephemeral: true;
+    }>;
+    /**
+     * Acknowledge the interaction without sending a response yet.
+     * Shows a loading indicator to the user.
+     * Follow up with `interaction.editReply()` when you're done.
+     *
+     * @example
+     * await interaction.defer()
+     * const data = await fetchSomeSlow()
+     * await interaction.editReply({ content: `Result: ${data}` })
+     */
+    defer(): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Edit the previous reply (e.g. after `defer()`).
+     *
+     * @example
+     * await interaction.defer()
+     * await interaction.editReply(`Done — processed ${count} items.`)
+     */
+    editReply(options: RespondInteractionOptions | string): Promise<Message | {
+        ok: true;
+        ephemeral: true;
+    }>;
+    /**
+     * Open a **modal dialog** and return the user's submission as a new `NovaInteraction`.
+     * Returns `null` if the user closes the modal or the timeout expires (default: 5 min).
+     *
+     * **This is the recommended way to open modals.**
+     *
+     * @example
+     * const submitted = await interaction.openModal(
+     *   new ModalBuilder()
+     *     .setTitle('Submit a report')
+     *     .setCustomId('report_modal')
+     *     .addField(
+     *       new TextInputBuilder()
+     *         .setCustomId('reason')
+     *         .setLabel('Reason')
+     *         .setStyle('paragraph')
+     *         .setRequired(true)
+     *     )
+     * )
+     *
+     * if (!submitted) return // user dismissed or timed out
+     *
+     * const reason = submitted.modalData.reason
+     * await submitted.replyEphemeral(`Report received: ${reason}`)
+     */
+    openModal(modal: ModalBuilder | BotModalDefinition, options?: {
+        timeout?: number;
+    }): Promise<NovaInteraction | null>;
+    /** Returns the raw interaction data from the gateway. */
+    toJSON(): Interaction;
+}
+
+/**
+ * A rich wrapper around a raw `Message` with convenience methods.
+ *
+ * Returned by `client.on('messageCreate', ...)` and from message fetch calls.
+ *
+ * @example
+ * client.on('messageCreate', async (msg) => {
+ *   if (msg.content.toLowerCase() === '!ping') {
+ *     await msg.reply('Pong! 🏓')
+ *     await msg.react('🏓')
+ *   }
+ * })
+ */
+declare class NovaMessage {
+    /** The raw message ID. */
+    readonly id: string;
+    /** The message text content. */
+    readonly content: string;
+    /** The channel this message was sent in. */
+    readonly channelId: string;
+    /** The author of the message. */
+    readonly author: Message['author'];
+    /** Embed attached to this message, if any. */
+    readonly embed: Embed | null;
+    /** Interactive components (buttons, selects) attached to this message. */
+    readonly components: MessageComponent[];
+    /** The message this is replying to, if any. */
+    readonly replyToId: string | null;
+    /** Uploaded file attachments. */
+    readonly attachments: Attachment[];
+    /** Reactions on this message. */
+    readonly reactions: Reaction[];
+    /** When the message was sent. */
+    readonly createdAt: Date;
+    /** When the message was last edited, or `null`. */
+    readonly editedAt: Date | null;
+    private readonly _messages;
+    private readonly _reactions;
+    constructor(raw: Message, messages: MessagesAPI, reactions: ReactionsAPI);
+    /** Returns true if the message was sent by a bot. */
+    isFromBot(): boolean;
+    /** Returns true if the message has an embed. */
+    hasEmbed(): boolean;
+    /** Returns true if the message has interactive components. */
+    hasComponents(): boolean;
+    /** Returns true if the message has been edited. */
+    isEdited(): boolean;
+    /**
+     * Add a reaction to this message.
+     *
+     * @example
+     * await msg.react('👍')
+     * await msg.react('🎉')
+     */
+    react(emoji: string): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Remove the bot's reaction from this message.
+     *
+     * @example
+     * await msg.removeReaction('👍')
+     */
+    removeReaction(emoji: string): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Reply to this message.
+     *
+     * @example
+     * await msg.reply('Got it!')
+     * await msg.reply({ embed: new EmbedBuilder().setTitle('Result').toJSON() })
+     */
+    reply(options: string | Omit<SendMessageOptions, 'replyToId'>): Promise<NovaMessage>;
+    /**
+     * Edit this message.
+     * Only works if the bot is the author.
+     *
+     * @example
+     * await msg.edit('Updated content')
+     * await msg.edit({ content: 'Updated', embed: { title: 'New embed' } })
+     */
+    edit(options: string | EditMessageOptions): Promise<NovaMessage>;
+    /**
+     * Delete this message.
+     * Only works if the bot is the author.
+     *
+     * @example
+     * await msg.delete()
+     */
+    delete(): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Pin this message in its channel.
+     *
+     * @example
+     * await msg.pin()
+     */
+    pin(): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Unpin this message.
+     *
+     * @example
+     * await msg.unpin()
+     */
+    unpin(): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Re-fetch the latest version of this message from the server.
+     *
+     * @example
+     * const fresh = await msg.fetch()
+     */
+    fetch(): Promise<NovaMessage>;
+    /**
+     * Get a URL to this message (deep link).
+     */
+    get url(): string;
+    /**
+     * Return the raw message object.
+     */
+    toJSON(): Message;
+    toString(): string;
+}
+
+interface NovaClientEvents {
+    /** Fired when the bot connects and is identified by the gateway. */
+    ready: (bot: BotApplication) => void;
+    /** Fired for every raw `bot:event` from the gateway. */
+    event: (event: BotEvent) => void;
+    /**
+     * Fired when an interaction is received (slash command, button click, etc.).
+     * Use `client.command()`, `client.button()`, or `client.selectMenu()` for
+     * convenient routing instead of handling everything here.
+     */
+    interactionCreate: (interaction: NovaInteraction) => void;
+    /** Fired when the WebSocket connection drops. */
+    disconnect: (reason: string) => void;
+    /** Fired on gateway / API errors. */
+    error: (err: Error | {
+        code: number;
+        message: string;
+    }) => void;
+    /** A new message was sent in a channel the bot can see. */
+    messageCreate: (message: NovaMessage) => void;
+    /** A message was edited. Returns the updated message. */
+    messageUpdate: (message: NovaMessage) => void;
+    /** A message was deleted. Returns partial data. */
+    messageDelete: (data: {
+        id: string;
+        channelId: string;
+    }) => void;
+    /** A reaction was added to a message. */
+    reactionAdd: (data: {
+        messageId: string;
+        channelId: string;
+        userId: string;
+        emoji: string;
+    }) => void;
+    /** A reaction was removed from a message. */
+    reactionRemove: (data: {
+        messageId: string;
+        channelId: string;
+        userId: string;
+        emoji: string;
+    }) => void;
+    /** A member joined a server the bot is in. */
+    memberAdd: (data: {
+        serverId: string;
+        userId: string;
+        username: string;
+    }) => void;
+    /** A member left a server the bot is in. */
+    memberRemove: (data: {
+        serverId: string;
+        userId: string;
+    }) => void;
+    /** A user started typing in a channel. */
+    typingStart: (data: {
+        channelId: string;
+        userId: string;
+    }) => void;
+    /** A message was pinned. */
+    messagePinned: (data: {
+        messageId: string;
+        channelId: string;
+        pinnedBy: string;
+    }) => void;
+}
+/**
+ * The main Nova bot client.
+ *
+ * @example
+ * import { NovaClient } from 'nova-bot-sdk'
+ *
+ * const client = new NovaClient({ token: 'nova_bot_...' })
+ *
+ * client.on('ready', (bot) => {
+ *   console.log(`Logged in as ${bot.botUser.username}`)
+ * })
+ *
+ * client.on('interactionCreate', async (interaction) => {
+ *   if (interaction.commandName === 'ping') {
+ *     await client.interactions.respond(interaction.id, { content: 'Pong!' })
+ *   }
+ * })
+ *
+ * await client.connect()
+ */
+declare class NovaClient extends EventEmitter {
+    /** The authenticated bot application. Available after `ready` fires. */
+    botUser: BotApplication | null;
+    /** Send, edit, delete and fetch messages. */
+    readonly messages: MessagesAPI;
+    /** Register and manage slash, prefix, and context menu commands. */
+    readonly commands: CommandsAPI;
+    /** List, kick and ban server members. */
+    readonly members: MembersAPI;
+    /** List servers the bot is a member of. */
+    readonly servers: ServersAPI;
+    /** Acknowledge and respond to interactions. */
+    readonly interactions: InteractionsAPI;
+    /** Query the bot's effective permissions within a server, channel, or role scope. */
+    readonly permissions: PermissionsAPI;
+    /** Create, edit, and delete channels; fetch pins and messages. */
+    readonly channels: ChannelsAPI;
+    /** Add, remove and fetch reactions on messages. */
+    readonly reactions: ReactionsAPI;
+    private socket;
+    private readonly http;
+    private readonly options;
+    private _cronTimers;
+    private readonly _commandHandlers;
+    private readonly _buttonHandlers;
+    private readonly _selectHandlers;
+    constructor(options: NovaClientOptions);
+    /**
+     * Register a handler for a slash or prefix command by name.
+     * Automatically routes `interactionCreate` events whose `commandName` matches.
+     *
+     * @example
+     * client.command('ping', async (interaction) => {
+     *   await interaction.reply('Pong! 🏓')
+     * })
+     */
+    command(name: string, handler: (interaction: NovaInteraction) => unknown): this;
+    /**
+     * Register a handler for a button by its `customId`.
+     *
+     * @example
+     * client.button('confirm_delete', async (interaction) => {
+     *   await interaction.replyEphemeral('Deleted.')
+     * })
+     */
+    button(customId: string, handler: (interaction: NovaInteraction) => unknown): this;
+    /**
+     * Register a handler for a select menu by its `customId`.
+     *
+     * @example
+     * client.selectMenu('colour_pick', async (interaction) => {
+     *   const chosen = interaction.values[0]
+     *   await interaction.reply(`You picked: ${chosen}`)
+     * })
+     */
+    selectMenu(customId: string, handler: (interaction: NovaInteraction) => unknown): this;
+    /**
+     * Connect to the Nova WebSocket gateway.
+     * Resolves when the `ready` event is received.
+     *
+     * @example
+     * await client.connect()
+     */
+    connect(): Promise<void>;
+    /**
+     * Register a recurring task that fires at a set interval.
+     * All cron tasks are automatically cancelled on `disconnect()`.
+     *
+     * @param intervalMs - How often to run the task (in milliseconds).
+     * @param fn         - Async or sync function to call on each tick.
+     * @returns A cancel function — call it to stop this specific task.
+     *
+     * @example
+     * // Check for new announcements every 30 seconds
+     * client.cron(30_000, async () => {
+     *   const messages = await client.messages.fetch(channelId, { limit: 5 })
+     *   // do something...
+     * })
+     */
+    cron(intervalMs: number, fn: () => unknown): () => void;
+    /**
+     * Set the bot's presence status.
+     * Broadcasts to all servers the bot is in via WebSocket.
+     *
+     * @example
+     * client.setStatus('DND')     // Do Not Disturb
+     * client.setStatus('IDLE')    // Away
+     * client.setStatus('OFFLINE') // Appear offline
+     * client.setStatus('ONLINE')  // Back online
+     */
+    setStatus(status: BotStatus): void;
+    /**
+     * Disconnect from the gateway and clean up.
+     */
+    disconnect(): void;
+    /**
+     * Send a message via the WebSocket gateway (lower latency than HTTP).
+     * Requires the `messages.write` scope.
+     *
+     * @example
+     * client.wsSend('channel-id', 'Hello from the gateway!')
+     */
+    wsSend(channelId: string, content: string): void;
+    /**
+     * Start a typing indicator via WebSocket.
      */
     wsTypingStart(channelId: string): void;
     /**
@@ -696,4 +1538,714 @@ declare class NovaClient extends EventEmitter {
     emit(event: string | symbol, ...args: unknown[]): boolean;
 }
 
-export { type Attachment, type BotApplication, type BotEvent, type BotEventType, type BotModalDefinition, type BotModalField, type BotPermissionRecord, type BotUser, CommandsAPI, type ContextCommandDefinition, type EditMessageOptions, type Embed, type EmbedField, type FetchMembersOptions, type FetchMessagesOptions, HttpClient, type Interaction, type InteractionType, InteractionsAPI, type Member, MembersAPI, type Message, type MessageComponent, MessagesAPI, NovaClient, type NovaClientEvents, type NovaClientOptions, type NovaServer, PermissionsAPI, type PermissionsQueryOptions, type PermissionsResult, type PollInteractionsOptions, type PrefixCommandDefinition, type Reaction, type RegisteredContextCommand, type RegisteredPrefixCommand, type RegisteredSlashCommand, type RespondInteractionOptions, type SendMessageOptions, ServersAPI, type SlashCommandDefinition, type SlashCommandOption };
+/**
+ * Fluent builder for bot message embeds.
+ *
+ * @example
+ * const embed = new EmbedBuilder()
+ *   .setTitle('Server Stats')
+ *   .setDescription('Here are the latest numbers.')
+ *   .setColor('#5865F2')
+ *   .addField('Members', '1 234', true)
+ *   .addField('Messages today', '567', true)
+ *   .setFooter('Nova Bot')
+ *   .setTimestamp()
+ *
+ * await client.messages.send(channelId, { embed })
+ */
+declare class EmbedBuilder {
+    private readonly _data;
+    /** Set the embed title (shown in bold at the top). */
+    setTitle(title: string): this;
+    /** Set the main description text (supports markdown). */
+    setDescription(description: string): this;
+    /**
+     * Set the accent colour.
+     * @param color Hex string — e.g. `'#5865F2'` or `'5865F2'`
+     */
+    setColor(color: string): this;
+    /** Make the title a clickable hyperlink. */
+    setUrl(url: string): this;
+    /** Small image shown in the top-right corner. */
+    setThumbnail(url: string): this;
+    /** Large image shown below the fields. */
+    setImage(url: string): this;
+    /** Footer text shown at the very bottom of the embed. */
+    setFooter(text: string): this;
+    /**
+     * Add a timestamp to the footer line.
+     * @param date Defaults to `new Date()`.
+     */
+    setTimestamp(date?: Date | number): this;
+    /** Author name + optional icon shown above the title. */
+    setAuthor(author: {
+        name: string;
+        iconUrl?: string;
+    }): this;
+    /**
+     * Add a single field.
+     * @param inline Pass `true` to render this field side-by-side with adjacent inline fields.
+     */
+    addField(name: string, value: string, inline?: boolean): this;
+    /** Add multiple fields at once. */
+    addFields(...fields: EmbedField[]): this;
+    /** Replace all fields. */
+    setFields(fields: EmbedField[]): this;
+    /** Serialise to a plain `Embed` object you can pass to any API call. */
+    toJSON(): Embed;
+}
+
+type ButtonStyle = 'primary' | 'secondary' | 'success' | 'danger' | 'link';
+/**
+ * Fluent builder for button components.
+ *
+ * @example
+ * const row = new ActionRowBuilder()
+ *   .addButton(
+ *     new ButtonBuilder()
+ *       .setCustomId('confirm')
+ *       .setLabel('Confirm')
+ *       .setStyle('success')
+ *   )
+ *   .addButton(
+ *     new ButtonBuilder()
+ *       .setCustomId('cancel')
+ *       .setLabel('Cancel')
+ *       .setStyle('danger')
+ *   )
+ *
+ * await client.messages.send(channelId, { content: 'Are you sure?', components: row.toJSON() })
+ */
+declare class ButtonBuilder {
+    private _customId;
+    private _label;
+    private _style;
+    private _disabled;
+    private _emoji?;
+    private _url?;
+    /** Custom ID returned in the `BUTTON_CLICK` interaction. Not required for `link` style buttons. */
+    setCustomId(customId: string): this;
+    /** Text displayed on the button. */
+    setLabel(label: string): this;
+    /**
+     * Visual style:
+     * - `primary` — blurple / brand colour
+     * - `secondary` — grey
+     * - `success` — green
+     * - `danger` — red
+     * - `link` — grey, navigates to a URL instead of creating an interaction
+     */
+    setStyle(style: ButtonStyle): this;
+    /** Emoji shown to the left of the label (unicode or custom e.g. `'👋'`). */
+    setEmoji(emoji: string): this;
+    /**
+     * URL for `link` style buttons.
+     * Sets the style to `'link'` automatically.
+     */
+    setUrl(url: string): this;
+    /** Prevent users from clicking the button. */
+    setDisabled(disabled?: boolean): this;
+    toJSON(): MessageComponent;
+}
+
+interface SelectMenuOption {
+    /** Visible label shown to the user. */
+    label: string;
+    /** Value returned in the interaction's `values` array. */
+    value: string;
+    /** Optional description shown below the label. */
+    description?: string;
+}
+/**
+ * Fluent builder for select-menu (dropdown) components.
+ *
+ * @example
+ * const menu = new SelectMenuBuilder()
+ *   .setCustomId('colour_pick')
+ *   .setPlaceholder('Pick a colour…')
+ *   .addOption({ label: 'Red',   value: 'red' })
+ *   .addOption({ label: 'Green', value: 'green' })
+ *   .addOption({ label: 'Blue',  value: 'blue' })
+ *
+ * await client.messages.send(channelId, { content: 'Choose:', components: [menu.toJSON()] })
+ */
+declare class SelectMenuBuilder {
+    private _customId;
+    private _placeholder?;
+    private _disabled;
+    private readonly _options;
+    /** Custom ID returned in the `SELECT_MENU` interaction. */
+    setCustomId(customId: string): this;
+    /** Greyed-out hint shown when nothing is selected. */
+    setPlaceholder(placeholder: string): this;
+    /** Prevent users from interacting with the menu. */
+    setDisabled(disabled?: boolean): this;
+    /** Add a single option. */
+    addOption(option: SelectMenuOption): this;
+    /** Add multiple options at once. */
+    addOptions(...options: SelectMenuOption[]): this;
+    /** Replace all options. */
+    setOptions(options: SelectMenuOption[]): this;
+    toJSON(): MessageComponent;
+}
+
+type ComponentBuilder = ButtonBuilder | SelectMenuBuilder | {
+    toJSON(): MessageComponent;
+};
+/**
+ * Groups buttons (and/or a select menu) into a single row of components.
+ *
+ * @example
+ * const row = new ActionRowBuilder()
+ *   .addComponent(new ButtonBuilder().setCustomId('yes').setLabel('Yes').setStyle('success'))
+ *   .addComponent(new ButtonBuilder().setCustomId('no').setLabel('No').setStyle('danger'))
+ *
+ * await interaction.reply({ content: 'Confirm?', components: row.toJSON() })
+ */
+declare class ActionRowBuilder {
+    private readonly _components;
+    /** Add a single component (button or select menu). */
+    addComponent(component: ComponentBuilder): this;
+    /** Add multiple components at once. */
+    addComponents(...components: ComponentBuilder[]): this;
+    /**
+     * Serialise to a flat `MessageComponent[]` array — the format accepted by all API calls.
+     */
+    toJSON(): MessageComponent[];
+}
+
+/**
+ * Fluent builder for a single slash command option (parameter).
+ * Obtain one via the callback in `SlashCommandBuilder.addStringOption()` etc.
+ */
+declare class SlashCommandOptionBuilder {
+    private _data;
+    constructor(type: SlashCommandOption['type']);
+    /** Internal option name (lowercase, no spaces). Shown after `/command ` in the client UI. */
+    setName(name: string): this;
+    /** Short human-readable description shown in the command picker. */
+    setDescription(description: string): this;
+    /** Whether users must supply this option before sending the command. */
+    setRequired(required?: boolean): this;
+    /**
+     * Restrict the option to specific values.
+     * The picker will show these as autocomplete suggestions.
+     */
+    addChoice(name: string, value: string | number): this;
+    /** Set all allowed choices at once. */
+    setChoices(choices: Array<{
+        name: string;
+        value: string | number;
+    }>): this;
+    toJSON(): SlashCommandOption;
+}
+/**
+ * Fluent builder for slash commands.
+ *
+ * @example
+ * await client.commands.setSlash([
+ *   new SlashCommandBuilder()
+ *     .setName('ban')
+ *     .setDescription('Ban a member from this server')
+ *     .addUserOption((opt) =>
+ *       opt.setName('user').setDescription('Who to ban').setRequired(true)
+ *     )
+ *     .addStringOption((opt) =>
+ *       opt.setName('reason').setDescription('Reason for the ban')
+ *     )
+ *     .toJSON(),
+ * ])
+ */
+declare class SlashCommandBuilder {
+    private _data;
+    /** Command name — lowercase, no spaces (e.g. `'ban'`, `'server-info'`). */
+    setName(name: string): this;
+    /** Short description shown in the command picker UI. */
+    setDescription(description: string): this;
+    /** Add a text (string) option. */
+    addStringOption(fn: (opt: SlashCommandOptionBuilder) => SlashCommandOptionBuilder): this;
+    /** Add an integer (whole number) option. */
+    addIntegerOption(fn: (opt: SlashCommandOptionBuilder) => SlashCommandOptionBuilder): this;
+    /** Add a boolean (true/false) option. */
+    addBooleanOption(fn: (opt: SlashCommandOptionBuilder) => SlashCommandOptionBuilder): this;
+    /** Add a user-mention option (returns a user ID string). */
+    addUserOption(fn: (opt: SlashCommandOptionBuilder) => SlashCommandOptionBuilder): this;
+    /** Add a channel-mention option (returns a channel ID string). */
+    addChannelOption(fn: (opt: SlashCommandOptionBuilder) => SlashCommandOptionBuilder): this;
+    /** Add a role-mention option (returns a role ID string). */
+    addRoleOption(fn: (opt: SlashCommandOptionBuilder) => SlashCommandOptionBuilder): this;
+    toJSON(): SlashCommandDefinition;
+}
+
+interface PollOption {
+    label: string;
+    emoji?: string;
+    value?: string;
+}
+interface PollDefinition {
+    question: string;
+    options: PollOption[];
+    allowMultiple?: boolean;
+    duration?: number | null;
+    anonymous?: boolean;
+}
+/**
+ * Fluent builder for creating polls.
+ *
+ * @example
+ * const poll = new PollBuilder()
+ *   .setQuestion('What is your favourite colour?')
+ *   .addOption({ label: 'Red', emoji: '🔴' })
+ *   .addOption({ label: 'Green', emoji: '🟢' })
+ *   .addOption({ label: 'Blue', emoji: '🔵' })
+ *   .setDuration(60 * 60 * 24) // 24 hours in seconds
+ *   .toJSON()
+ *
+ * await client.messages.send(channelId, { poll })
+ */
+declare class PollBuilder {
+    private _question;
+    private _options;
+    private _allowMultiple;
+    private _duration;
+    private _anonymous;
+    /**
+     * Set the poll question.
+     *
+     * @example
+     * builder.setQuestion('Best programming language?')
+     */
+    setQuestion(question: string): this;
+    /**
+     * Add a single answer option.
+     *
+     * @example
+     * builder.addOption({ label: 'TypeScript', emoji: '🔷' })
+     */
+    addOption(option: PollOption): this;
+    /**
+     * Add multiple answer options at once.
+     *
+     * @example
+     * builder.addOptions([
+     *   { label: 'Yes', emoji: '✅' },
+     *   { label: 'No', emoji: '❌' },
+     * ])
+     */
+    addOptions(options: PollOption[]): this;
+    /**
+     * Allow users to select more than one option.
+     * Default: `false` (single choice).
+     */
+    setAllowMultiple(yes?: boolean): this;
+    /**
+     * Set the poll duration in **seconds**. Pass `null` to make it permanent.
+     *
+     * @example
+     * builder.setDuration(60 * 60 * 24) // expires in 24 hours
+     * builder.setDuration(null)          // no expiry
+     */
+    setDuration(seconds: number | null): this;
+    /**
+     * Hide which users voted for which option.
+     * Default: `false` (votes are public).
+     */
+    setAnonymous(yes?: boolean): this;
+    /** Build the poll definition object. */
+    toJSON(): PollDefinition;
+}
+
+/**
+ * Fluent builder for composing messages.
+ * Replaces passing raw option objects everywhere.
+ *
+ * @example
+ * const msg = new MessageBuilder()
+ *   .setContent('Here are your stats:')
+ *   .setEmbed(
+ *     new EmbedBuilder()
+ *       .setTitle('📊 Stats')
+ *       .addField('Messages', '1 234', true)
+ *       .addField('Reactions', '567', true)
+ *       .setColor('#5865F2')
+ *   )
+ *   .addRow(
+ *     new ActionRowBuilder()
+ *       .addComponent(new ButtonBuilder().setLabel('Refresh').setCustomId('refresh').setStyle('primary'))
+ *   )
+ *   .toJSON()
+ *
+ * await client.messages.send(channelId, msg)
+ */
+declare class MessageBuilder {
+    private _content;
+    private _embed;
+    private _components;
+    private _replyToId;
+    private _poll;
+    /**
+     * Set the text content of the message.
+     *
+     * @example
+     * builder.setContent('Hello world!')
+     */
+    setContent(content: string): this;
+    /**
+     * Attach an embed. Accepts an `EmbedBuilder` or raw `Embed` object.
+     *
+     * @example
+     * builder.setEmbed(new EmbedBuilder().setTitle('Result'))
+     * builder.setEmbed({ title: 'Result', color: '#57F287' })
+     */
+    setEmbed(embed: EmbedBuilder | Embed): this;
+    /**
+     * Remove any embed from this message.
+     */
+    clearEmbed(): this;
+    /**
+     * Add an `ActionRowBuilder` (or raw component array) as a component row.
+     *
+     * @example
+     * builder.addRow(
+     *   new ActionRowBuilder().addComponent(btn1).addComponent(btn2)
+     * )
+     */
+    addRow(row: ActionRowBuilder | MessageComponent[]): this;
+    /**
+     * Replace all existing component rows.
+     */
+    setComponents(components: MessageComponent[]): this;
+    /**
+     * Set the message this is replying to.
+     *
+     * @example
+     * builder.setReplyTo(message.id)
+     */
+    setReplyTo(messageId: string): this;
+    /**
+     * Attach a poll to the message.
+     * Accepts a `PollBuilder` or raw `PollDefinition`.
+     *
+     * @example
+     * builder.setPoll(
+     *   new PollBuilder()
+     *     .setQuestion('Favourite language?')
+     *     .addOptions([{ label: 'TypeScript' }, { label: 'Python' }])
+     * )
+     */
+    setPoll(poll: {
+        toJSON: () => PollDefinition;
+    } | PollDefinition): this;
+    /**
+     * Build the message options object, ready to pass to `client.messages.send()`.
+     *
+     * @throws if neither `content` nor `embed` nor `poll` is set.
+     */
+    toJSON(): SendMessageOptions & {
+        poll?: PollDefinition;
+    };
+}
+
+/**
+ * A supercharged Map with extra utility methods.
+ * Used throughout the SDK for caches (messages, channels, members, etc.)
+ *
+ * Inspired by discord.js Collection — but with proper generics and async support.
+ *
+ * @example
+ * const col = new Collection<string, User>()
+ * col.set('u1', { id: 'u1', name: 'Alice' })
+ * col.set('u2', { id: 'u2', name: 'Bob' })
+ *
+ * col.first()           // { id: 'u1', name: 'Alice' }
+ * col.find(u => u.name === 'Bob')  // { id: 'u2', name: 'Bob' }
+ * col.map(u => u.name)  // ['Alice', 'Bob']
+ */
+declare class Collection<K, V> extends Map<K, V> {
+    /**
+     * The first value stored (insertion order), or `undefined` if empty.
+     */
+    first(): V | undefined;
+    /**
+     * The first `n` values stored (insertion order).
+     */
+    firstN(n: number): V[];
+    /**
+     * The last value stored, or `undefined` if empty.
+     */
+    last(): V | undefined;
+    /**
+     * The last `n` values stored (insertion order).
+     */
+    lastN(n: number): V[];
+    /**
+     * Returns a random value from the collection, or `undefined` if empty.
+     */
+    random(): V | undefined;
+    /**
+     * Find the first value that passes the predicate.
+     *
+     * @example
+     * const bot = members.find(m => m.user.isBot)
+     */
+    find(fn: (value: V, key: K, col: this) => boolean): V | undefined;
+    /**
+     * Find the key of the first value that passes the predicate.
+     */
+    findKey(fn: (value: V, key: K, col: this) => boolean): K | undefined;
+    /**
+     * Returns `true` if at least one value satisfies the predicate.
+     */
+    some(fn: (value: V, key: K, col: this) => boolean): boolean;
+    /**
+     * Returns `true` if every value satisfies the predicate.
+     */
+    every(fn: (value: V, key: K, col: this) => boolean): boolean;
+    /**
+     * Filter to a new Collection containing only values that pass the predicate.
+     *
+     * @example
+     * const admins = members.filter(m => m.role === 'ADMIN')
+     */
+    filter(fn: (value: V, key: K, col: this) => boolean): Collection<K, V>;
+    /**
+     * Map each value to a new array.
+     *
+     * @example
+     * const names = members.map(m => m.user.username)
+     */
+    map<T>(fn: (value: V, key: K, col: this) => T): T[];
+    /**
+     * Map to a new Collection with transformed values.
+     *
+     * @example
+     * const names = channels.mapValues(c => c.name.toUpperCase())
+     */
+    mapValues<T>(fn: (value: V, key: K, col: this) => T): Collection<K, T>;
+    /**
+     * Reduce the collection to a single value.
+     *
+     * @example
+     * const totalReactions = messages.reduce((sum, m) => sum + m.reactions.length, 0)
+     */
+    reduce<T>(fn: (accumulator: T, value: V, key: K, col: this) => T, initial: T): T;
+    /**
+     * Returns values as an array (insertion order).
+     */
+    toArray(): V[];
+    /**
+     * Returns keys as an array (insertion order).
+     */
+    keyArray(): K[];
+    /**
+     * Sort and return a new Collection.
+     * Callback works like `Array.prototype.sort`.
+     *
+     * @example
+     * const sorted = channels.sort((a, b) => a.position - b.position)
+     */
+    sort(fn?: (a: V, b: V, ak: K, bk: K) => number): Collection<K, V>;
+    /**
+     * Split into two Collections based on a predicate.
+     * Returns `[passing, failing]`.
+     *
+     * @example
+     * const [bots, humans] = members.partition(m => m.user.isBot)
+     */
+    partition(fn: (value: V, key: K, col: this) => boolean): [Collection<K, V>, Collection<K, V>];
+    /**
+     * Merge this collection with one or more others.
+     * Later collections overwrite duplicate keys.
+     */
+    merge(...others: ReadonlyMap<K, V>[]): Collection<K, V>;
+    /**
+     * Serialize to a plain `Record` (requires string keys).
+     */
+    toJSON(): Record<string, V>;
+    toString(): string;
+}
+
+/**
+ * Per-user cooldown manager.
+ * Prevents commands from being spammed by individual users.
+ *
+ * @example
+ * // Create once per command
+ * const cooldown = new Cooldown(5_000) // 5 second cooldown
+ *
+ * client.command('daily', async (interaction) => {
+ *   const remaining = cooldown.check(interaction.userId)
+ *   if (remaining > 0) {
+ *     return interaction.replyEphemeral(
+ *       `⏳ Wait **${Cooldown.format(remaining)}** before using this command again.`
+ *     )
+ *   }
+ *   cooldown.use(interaction.userId)
+ *   await interaction.reply('🎁 Daily reward collected!')
+ * })
+ */
+declare class Cooldown {
+    private readonly _durations;
+    private readonly _last;
+    private readonly _defaultMs;
+    /**
+     * @param durationMs - Default cooldown duration in milliseconds.
+     */
+    constructor(durationMs: number);
+    /**
+     * Check remaining cooldown for a user.
+     * Returns `0` if they are not on cooldown (free to proceed),
+     * or the **milliseconds remaining** if they are on cooldown.
+     *
+     * @example
+     * const ms = cooldown.check(userId)
+     * if (ms > 0) return interaction.replyEphemeral(`Wait ${Cooldown.format(ms)}!`)
+     */
+    check(userId: string): number;
+    /**
+     * Mark a user as having just used the command, starting their cooldown.
+     * Optionally override the cooldown duration for this specific user.
+     *
+     * @example
+     * cooldown.use(userId)          // uses default duration
+     * cooldown.use(userId, 10_000)  // 10 second cooldown for this use
+     */
+    use(userId: string, durationMs?: number): void;
+    /**
+     * Immediately reset (clear) the cooldown for a user.
+     *
+     * @example
+     * cooldown.reset(userId) // user can use the command again immediately
+     */
+    reset(userId: string): void;
+    /**
+     * Reset all active cooldowns.
+     */
+    resetAll(): void;
+    /**
+     * Returns a list of all users currently on cooldown.
+     *
+     * @example
+     * const active = cooldown.activeCooldowns()
+     * // [{ userId: 'abc', remainingMs: 3200 }, ...]
+     */
+    activeCooldowns(): Array<{
+        userId: string;
+        remainingMs: number;
+    }>;
+    /**
+     * Format milliseconds into a human-readable string.
+     *
+     * @example
+     * Cooldown.format(3_600_000) // '1h 0m 0s'
+     * Cooldown.format(90_000)    // '1m 30s'
+     * Cooldown.format(4_000)     // '4s'
+     */
+    static format(ms: number): string;
+}
+/**
+ * Manages multiple named cooldowns in one place.
+ * Ideal when you have many commands each with their own cooldown.
+ *
+ * @example
+ * const cooldowns = new CooldownManager()
+ *
+ * client.command('ping', async (interaction) => {
+ *   const remaining = cooldowns.check('ping', interaction.userId, 3_000)
+ *   if (remaining > 0) return interaction.replyEphemeral(`Wait ${Cooldown.format(remaining)}!`)
+ *   await interaction.reply('Pong!')
+ * })
+ */
+declare class CooldownManager {
+    private readonly _map;
+    /**
+     * Get or create a named cooldown.
+     */
+    get(name: string, durationMs?: number): Cooldown;
+    /**
+     * Check a named cooldown for a user.
+     * Creates the cooldown if it doesn't exist yet.
+     * Returns `0` if free, or remaining ms if on cooldown.
+     *
+     * @example
+     * const ms = cooldowns.check('ban', userId, 30_000)
+     */
+    check(name: string, userId: string, durationMs?: number): number;
+    /**
+     * Mark a user as having used a named command.
+     *
+     * @example
+     * cooldowns.use('ban', userId, 30_000)
+     */
+    use(name: string, userId: string, durationMs?: number): void;
+    /**
+     * Reset a user's cooldown on a named command.
+     */
+    reset(name: string, userId: string): void;
+    /**
+     * Reset all cooldowns for all commands.
+     */
+    resetAll(): void;
+}
+
+/**
+ * Coloured, timestamped logger for Nova bots.
+ * Prefix every log with a consistent `[BotName]` tag.
+ *
+ * @example
+ * const log = new Logger('MyBot')
+ * log.info('Ready!')            // [MyBot] [INFO] Ready!
+ * log.warn('Rate limited')      // [MyBot] [WARN] Rate limited
+ * log.error('DB timed out')     // [MyBot] [ERROR] DB timed out
+ * log.debug('Payload:', data)   // [MyBot] [DEBUG] Payload: { ... }
+ * log.success('Command registered') // [MyBot] [OK] Command registered
+ * log.command('ping', userId)   // [MyBot] [CMD] ping ← userId
+ * log.event('messageCreate')    // [MyBot] [EVT] messageCreate
+ */
+declare class Logger {
+    private readonly _prefix;
+    private _debug;
+    /**
+     * @param name       - Name shown in square brackets before every message.
+     * @param enableDebug - When `false` (default), `.debug()` calls are silent.
+     */
+    constructor(name: string, enableDebug?: boolean);
+    /** Enable or disable debug output at runtime. */
+    setDebug(enabled: boolean): this;
+    private _timestamp;
+    private _fmt;
+    /** General info message. */
+    info(...args: unknown[]): void;
+    /** Warning — something unexpected but non-fatal. */
+    warn(...args: unknown[]): void;
+    /** Error — something went wrong. */
+    error(...args: unknown[]): void;
+    /** Success / positive confirmation. */
+    success(...args: unknown[]): void;
+    /** Debug — only printed when `enableDebug` is true. */
+    debug(...args: unknown[]): void;
+    /**
+     * Log an incoming command interaction.
+     *
+     * @example
+     * log.command('ping', interaction.userId)
+     * // [MyBot] [CMD] /ping ← user:abc123
+     */
+    command(name: string, userId: string): void;
+    /**
+     * Log a gateway event.
+     *
+     * @example
+     * log.event('messageCreate')
+     */
+    event(type: string, extra?: string): void;
+    /**
+     * Log that a command handler threw an error.
+     *
+     * @example
+     * log.commandError('ban', err)
+     */
+    commandError(name: string, err: unknown): void;
+}
+
+export { ActionRowBuilder, type Attachment, type BanEntry, type BotApplication, type BotEvent, type BotEventType, type BotModalDefinition, type BotModalField, type BotPermissionRecord, type BotStatus, type BotUser, ButtonBuilder, type ButtonStyle, type Channel, type ChannelType, ChannelsAPI, Collection, CommandsAPI, type ContextCommandDefinition, Cooldown, CooldownManager, type CreateChannelOptions, type EditChannelOptions, type EditMessageOptions, type Embed, EmbedBuilder, type EmbedField, type FetchChannelsOptions, type FetchMembersOptions, type FetchMessagesOptions, HttpClient, type Interaction, InteractionOptions, type InteractionType, InteractionsAPI, type Invite, Logger, type Member, MembersAPI, type Message, MessageBuilder, type MessageComponent, MessagesAPI, ModalBuilder, NovaClient, type NovaClientEvents, type NovaClientOptions, NovaInteraction, NovaMessage, type NovaServer, PermissionsAPI, type PermissionsQueryOptions, type PermissionsResult, PollBuilder, type PollDefinition, type PollInteractionsOptions, type PollOption, type PrefixCommandDefinition, type Reaction, type ReactionDetail, ReactionsAPI, type RegisteredContextCommand, type RegisteredPrefixCommand, type RegisteredSlashCommand, type RespondInteractionOptions, type Role, SelectMenuBuilder, type SelectMenuOption, type SendMessageOptions, ServersAPI, SlashCommandBuilder, type SlashCommandDefinition, type SlashCommandOption, SlashCommandOptionBuilder, TextInputBuilder, type TextInputStyle };