novaapp-sdk 1.1.0 → 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;
@@ -278,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;
@@ -354,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 {
@@ -460,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 {
@@ -473,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 {
@@ -598,6 +786,144 @@ 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';
 /**
  * Fluent builder for a single text-input field inside a modal.
@@ -878,6 +1204,135 @@ declare class NovaInteraction {
     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;
@@ -897,21 +1352,50 @@ interface NovaClientEvents {
         message: string;
     }) => void;
     /** A new message was sent in a channel the bot can see. */
-    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. */
-    reactionAdd: (data: BotEvent['data']) => void;
-    /** A reaction was removed. */
-    reactionRemove: (data: BotEvent['data']) => void;
+    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: BotEvent['data']) => void;
+    memberAdd: (data: {
+        serverId: string;
+        userId: string;
+        username: string;
+    }) => void;
     /** A member left a server the bot is in. */
-    memberRemove: (data: BotEvent['data']) => void;
-    /** A user started typing. */
-    typingStart: (data: BotEvent['data']) => void;
+    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.
@@ -948,9 +1432,14 @@ declare class NovaClient extends EventEmitter {
     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;
@@ -992,6 +1481,33 @@ declare class NovaClient extends EventEmitter {
      * 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.
      */
@@ -1261,4 +1777,475 @@ declare class SlashCommandBuilder {
     toJSON(): SlashCommandDefinition;
 }
 
-export { ActionRowBuilder, type Attachment, type BotApplication, type BotEvent, type BotEventType, type BotModalDefinition, type BotModalField, type BotPermissionRecord, type BotUser, ButtonBuilder, type ButtonStyle, CommandsAPI, type ContextCommandDefinition, type EditMessageOptions, type Embed, EmbedBuilder, type EmbedField, type FetchMembersOptions, type FetchMessagesOptions, HttpClient, type Interaction, InteractionOptions, type InteractionType, InteractionsAPI, type Member, MembersAPI, type Message, type MessageComponent, MessagesAPI, ModalBuilder, NovaClient, type NovaClientEvents, type NovaClientOptions, NovaInteraction, type NovaServer, PermissionsAPI, type PermissionsQueryOptions, type PermissionsResult, type PollInteractionsOptions, type PrefixCommandDefinition, type Reaction, type RegisteredContextCommand, type RegisteredPrefixCommand, type RegisteredSlashCommand, type RespondInteractionOptions, SelectMenuBuilder, type SelectMenuOption, type SendMessageOptions, ServersAPI, SlashCommandBuilder, type SlashCommandDefinition, type SlashCommandOption, SlashCommandOptionBuilder, TextInputBuilder, type TextInputStyle };
+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 };