novaapp-sdk 1.1.0 → 1.3.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;
+    /** Slow-mode interval in seconds. `0` means disabled. */
+    slowMode: number;
+    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,22 @@ interface PollInteractionsOptions {
     limit?: number;
     since?: string;
 }
+interface CreateChannelOptions {
+    name: string;
+    type?: ChannelType;
+    topic?: string;
+    position?: number;
+    slowMode?: number;
+}
+interface EditChannelOptions {
+    name?: string;
+    topic?: string;
+    position?: number;
+    slowMode?: number;
+}
+interface FetchChannelsOptions {
+    type?: ChannelType;
+}
 /** A raw permission record stored for a specific scope (server, role, or channel). */
 interface BotPermissionRecord {
     id: string;
@@ -311,6 +380,29 @@ interface PermissionsQueryOptions {
     /** Narrow the scope to a specific role. */
     roleId?: string;
 }
+/** A direct message sent between the bot and a user. */
+interface DirectMessage {
+    id: string;
+    content: string;
+    /** The sender's user ID. */
+    fromId: string;
+    /** The recipient's user ID. */
+    toId: string;
+    editedAt: string | null;
+    createdAt: string;
+}
+/** Snapshot of a user's voice channel presence. */
+interface VoiceState {
+    userId: string;
+    channelId: string;
+    serverId: string;
+    /** Whether the user's microphone is muted. */
+    muted: boolean;
+    /** Whether the user's audio output is deafened. */
+    deafened: boolean;
+    /** ISO timestamp when the user joined the voice channel. */
+    joinedAt: string;
+}
 interface NovaClientOptions {
     /** Your bot token — starts with "nova_bot_" */
     token: string;
@@ -354,6 +446,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 +610,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 +673,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 +807,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,284 +1225,792 @@ declare class NovaInteraction {
     toJSON(): Interaction;
 }
 
-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: (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;
-    /** A member joined a server the bot is in. */
-    memberAdd: (data: BotEvent['data']) => void;
-    /** A member left a server the bot is in. */
-    memberRemove: (data: BotEvent['data']) => void;
-    /** A user started typing. */
-    typingStart: (data: BotEvent['data']) => void;
-}
 /**
- * The main Nova bot client.
+ * A rich wrapper around a raw `Message` with convenience methods.
  *
- * @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}`)
- * })
+ * Returned by `client.on('messageCreate', ...)` and from message fetch calls.
  *
- * client.on('interactionCreate', async (interaction) => {
- *   if (interaction.commandName === 'ping') {
- *     await client.interactions.respond(interaction.id, { content: 'Pong!' })
+ * @example
+ * client.on('messageCreate', async (msg) => {
+ *   if (msg.content.toLowerCase() === '!ping') {
+ *     await msg.reply('Pong! 🏓')
+ *     await msg.react('🏓')
  *   }
  * })
- *
- * 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;
-    private socket;
-    private readonly http;
-    private readonly options;
-    private readonly _commandHandlers;
-    private readonly _buttonHandlers;
-    private readonly _selectHandlers;
-    constructor(options: NovaClientOptions);
+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;
     /**
-     * Register a handler for a slash or prefix command by name.
-     * Automatically routes `interactionCreate` events whose `commandName` matches.
+     * Add a reaction to this message.
      *
      * @example
-     * client.command('ping', async (interaction) => {
-     *   await interaction.reply('Pong! 🏓')
-     * })
+     * await msg.react('👍')
+     * await msg.react('🎉')
      */
-    command(name: string, handler: (interaction: NovaInteraction) => unknown): this;
+    react(emoji: string): Promise<{
+        ok: true;
+    }>;
     /**
-     * Register a handler for a button by its `customId`.
+     * Remove the bot's reaction from this message.
      *
      * @example
-     * client.button('confirm_delete', async (interaction) => {
-     *   await interaction.replyEphemeral('Deleted.')
-     * })
+     * await msg.removeReaction('👍')
      */
-    button(customId: string, handler: (interaction: NovaInteraction) => unknown): this;
+    removeReaction(emoji: string): Promise<{
+        ok: true;
+    }>;
     /**
-     * Register a handler for a select menu by its `customId`.
+     * Reply to this message.
      *
      * @example
-     * client.selectMenu('colour_pick', async (interaction) => {
-     *   const chosen = interaction.values[0]
-     *   await interaction.reply(`You picked: ${chosen}`)
-     * })
+     * await msg.reply('Got it!')
+     * await msg.reply({ embed: new EmbedBuilder().setTitle('Result').toJSON() })
      */
-    selectMenu(customId: string, handler: (interaction: NovaInteraction) => unknown): this;
+    reply(options: string | Omit<SendMessageOptions, 'replyToId'>): Promise<NovaMessage>;
     /**
-     * Connect to the Nova WebSocket gateway.
-     * Resolves when the `ready` event is received.
+     * Edit this message.
+     * Only works if the bot is the author.
      *
      * @example
-     * await client.connect()
+     * await msg.edit('Updated content')
+     * await msg.edit({ content: 'Updated', embed: { title: 'New embed' } })
      */
-    connect(): Promise<void>;
+    edit(options: string | EditMessageOptions): Promise<NovaMessage>;
     /**
-     * Disconnect from the gateway and clean up.
+     * Delete this message.
+     * Only works if the bot is the author.
+     *
+     * @example
+     * await msg.delete()
      */
-    disconnect(): void;
+    delete(): Promise<{
+        ok: true;
+    }>;
     /**
-     * Send a message via the WebSocket gateway (lower latency than HTTP).
-     * Requires the `messages.write` scope.
+     * Pin this message in its channel.
      *
      * @example
-     * client.wsSend('channel-id', 'Hello from the gateway!')
+     * await msg.pin()
      */
-    wsSend(channelId: string, content: string): void;
+    pin(): Promise<{
+        ok: true;
+    }>;
     /**
-     * Start a typing indicator via WebSocket.
+     * Unpin this message.
+     *
+     * @example
+     * await msg.unpin()
      */
-    wsTypingStart(channelId: string): void;
+    unpin(): Promise<{
+        ok: true;
+    }>;
     /**
-     * Stop a typing indicator via WebSocket.
+     * Re-fetch the latest version of this message from the server.
+     *
+     * @example
+     * const fresh = await msg.fetch()
      */
-    wsTypingStop(channelId: string): void;
-    on<K extends keyof NovaClientEvents>(event: K, listener: NovaClientEvents[K]): this;
-    on(event: string | symbol, listener: (...args: unknown[]) => void): this;
-    once<K extends keyof NovaClientEvents>(event: K, listener: NovaClientEvents[K]): this;
-    once(event: string | symbol, listener: (...args: unknown[]) => void): this;
-    off<K extends keyof NovaClientEvents>(event: K, listener: NovaClientEvents[K]): this;
-    off(event: string | symbol, listener: (...args: unknown[]) => void): this;
-    emit<K extends keyof NovaClientEvents>(event: K, ...args: Parameters<NovaClientEvents[K]>): boolean;
-    emit(event: string | symbol, ...args: unknown[]): boolean;
+    fetch(): Promise<NovaMessage>;
+    /**
+     * Get a URL to this message (deep link).
+     */
+    get url(): string;
+    /**
+     * Return the raw message object.
+     */
+    toJSON(): Message;
+    toString(): string;
 }
 
 /**
- * Fluent builder for bot message embeds.
+ * A rich wrapper around a raw `Channel` with convenience methods.
+ *
+ * Returned by `client.fetchChannel()` and `client.fetchChannels()`.
  *
  * @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()
+ * const channel = await client.fetchChannel('channel-id')
  *
- * await client.messages.send(channelId, { embed })
+ * await channel.send('Hello from the bot!')
+ * await channel.edit({ topic: 'New topic' })
+ * const messages = await channel.fetchMessages({ limit: 20 })
  */
-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;
+declare class NovaChannel {
+    /** The channel's unique ID. */
+    readonly id: string;
+    /** The channel's name (without #). */
+    readonly name: string;
+    /** The channel type — `'TEXT'`, `'VOICE'`, `'ANNOUNCEMENT'`, `'FORUM'`, or `'STAGE'`. */
+    readonly type: ChannelType;
+    /** The ID of the server this channel belongs to. */
+    readonly serverId: string | null;
+    /** Optional topic / description text. */
+    readonly topic: string | null;
+    /** Sorting position (lower = higher in the list). */
+    readonly position: number;
+    /** Slow-mode interval in seconds (`0` = disabled). */
+    readonly slowMode: number;
+    /** When the channel was created. */
+    readonly createdAt: Date;
+    private readonly _channels;
+    private readonly _messages;
+    constructor(raw: Channel, channels: ChannelsAPI, messages: MessagesAPI);
+    /** `true` for text channels. */
+    isText(): boolean;
+    /** `true` for voice channels. */
+    isVoice(): boolean;
+    /** `true` for announcement channels. */
+    isAnnouncement(): boolean;
+    /** `true` for forum channels. */
+    isForum(): boolean;
+    /** `true` for stage channels. */
+    isStage(): boolean;
+    /** `true` if slow-mode is enabled on this channel. */
+    hasSlowMode(): boolean;
     /**
-     * Set the accent colour.
-     * @param color Hex string — e.g. `'#5865F2'` or `'5865F2'`
+     * Send a message to this channel.
+     * Accepts a plain string or a full options object.
+     *
+     * @example
+     * await channel.send('Hello!')
+     * await channel.send({ content: 'Hi', embed: { title: 'Stats' } })
      */
-    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;
+    send(options: string | SendMessageOptions): Promise<Message>;
     /**
-     * Add a timestamp to the footer line.
-     * @param date Defaults to `new Date()`.
+     * Fetch recent messages from this channel.
+     *
+     * @example
+     * const messages = await channel.fetchMessages({ limit: 50 })
      */
-    setTimestamp(date?: Date | number): this;
-    /** Author name + optional icon shown above the title. */
-    setAuthor(author: {
-        name: string;
-        iconUrl?: string;
-    }): this;
+    fetchMessages(options?: FetchMessagesOptions): Promise<Message[]>;
     /**
-     * Add a single field.
-     * @param inline Pass `true` to render this field side-by-side with adjacent inline fields.
+     * Fetch all pinned messages in this channel.
+     *
+     * @example
+     * const pins = await channel.fetchPins()
      */
-    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;
+    fetchPins(): Promise<Message[]>;
+    /**
+     * Start a typing indicator (shows "Bot is typing…" for ~5 seconds).
+     *
+     * @example
+     * await channel.startTyping()
+     */
+    startTyping(): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Edit this channel's properties.
+     * Requires the `channels.manage` scope.
+     *
+     * @example
+     * await channel.edit({ name: 'general-2', topic: 'The second general channel' })
+     */
+    edit(options: EditChannelOptions): Promise<NovaChannel>;
+    /**
+     * Delete this channel.
+     * Requires the `channels.manage` scope.
+     *
+     * @example
+     * await channel.delete()
+     */
+    delete(): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Returns the channel as a mention-style string: `#name`.
+     */
+    toString(): string;
+    /** Returns the raw channel data. */
+    toJSON(): Channel;
 }
 
-type ButtonStyle = 'primary' | 'secondary' | 'success' | 'danger' | 'link';
 /**
- * Fluent builder for button components.
+ * A rich wrapper around a raw `Member` with convenience methods.
+ *
+ * Returned by `client.fetchMember()` and `client.fetchMembers()`.
  *
  * @example
- * const row = new ActionRowBuilder()
- *   .addButton(
- *     new ButtonBuilder()
- *       .setCustomId('confirm')
- *       .setLabel('Confirm')
- *       .setStyle('success')
- *   )
- *   .addButton(
- *     new ButtonBuilder()
- *       .setCustomId('cancel')
- *       .setLabel('Cancel')
- *       .setStyle('danger')
- *   )
+ * const member = await client.fetchMember('server-id', 'user-id')
  *
- * await client.messages.send(channelId, { content: 'Are you sure?', components: row.toJSON() })
+ * if (member.isAdmin()) {
+ *   await member.dm('You have admin access.')
+ * } else {
+ *   await member.kick()
+ * }
  */
-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;
+declare class NovaMember {
+    /** The user's unique ID. */
+    readonly userId: string;
+    /** The server this membership belongs to. */
+    readonly serverId: string;
+    /** The user's username (login handle). */
+    readonly username: string;
+    /** The user's display name. */
+    readonly displayName: string;
+    /** URL of the user's avatar, or `null`. */
+    readonly avatar: string | null;
+    /** The member's server role — `'OWNER'`, `'ADMIN'`, or `'MEMBER'`. */
+    readonly role: 'OWNER' | 'ADMIN' | 'MEMBER';
+    /** The user's current presence status. */
+    readonly status: 'ONLINE' | 'IDLE' | 'DND' | 'OFFLINE';
+    /** `true` if this member is a bot account. */
+    readonly isBot: boolean;
+    /** When this user joined the server. */
+    readonly joinedAt: Date;
+    private readonly _members;
+    constructor(raw: Member, serverId: string, members: MembersAPI);
+    /** `true` if this member is the server owner. */
+    isOwner(): boolean;
+    /** `true` if this member is an admin or the server owner. */
+    isAdmin(): boolean;
+    /** `true` if this member is a regular (non-privileged) member. */
+    isRegularMember(): boolean;
+    /** `true` if the user is currently online. */
+    isOnline(): boolean;
+    /** `true` if the user is idle / away. */
+    isIdle(): boolean;
+    /** `true` if the user is set to Do Not Disturb. */
+    isDND(): boolean;
+    /** `true` if the user appears offline. */
+    isOffline(): boolean;
     /**
-     * Visual style:
-     * - `primary` — blurple / brand colour
-     * - `secondary` — grey
-     * - `success` — green
-     * - `danger` — red
-     * - `link` — grey, navigates to a URL instead of creating an interaction
+     * Kick this member from the server.
+     * Bots cannot kick owners or admins (throws 403).
+     *
+     * @example
+     * await member.kick()
      */
-    setStyle(style: ButtonStyle): this;
-    /** Emoji shown to the left of the label (unicode or custom e.g. `'👋'`). */
-    setEmoji(emoji: string): this;
+    kick(): Promise<{
+        ok: true;
+    }>;
     /**
-     * URL for `link` style buttons.
-     * Sets the style to `'link'` automatically.
+     * Ban this member from the server with an optional reason.
+     * Bots cannot ban owners or admins (throws 403).
+     *
+     * @example
+     * await member.ban('Repeated rule violations')
      */
-    setUrl(url: string): this;
-    /** Prevent users from clicking the button. */
-    setDisabled(disabled?: boolean): this;
-    toJSON(): MessageComponent;
+    ban(reason?: string): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Send this user a direct message.
+     * Requires the `messages.write` scope.
+     *
+     * @example
+     * await member.dm('Welcome to the server!')
+     * await member.dm({ content: 'Hello', embed: { title: 'Rules' } })
+     */
+    dm(options: string | Omit<SendMessageOptions, 'replyToId'>): Promise<Message>;
+    /**
+     * Assign a custom role to this member.
+     * Requires the `members.roles` scope.
+     *
+     * @example
+     * await member.addRole('role-id')
+     */
+    addRole(roleId: string): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Remove a custom role from this member.
+     * Requires the `members.roles` scope.
+     *
+     * @example
+     * await member.removeRole('role-id')
+     */
+    removeRole(roleId: string): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Returns a mention-style string: `@displayName`.
+     */
+    toString(): string;
+    /** Returns the raw member data. */
+    toJSON(): Member;
 }
 
-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;
+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;
+    /** A channel was created in a server. */
+    channelCreate: (channel: Channel) => void;
+    /** A channel was updated. */
+    channelUpdate: (channel: Channel) => void;
+    /** A channel was deleted. */
+    channelDelete: (data: {
+        id: string;
+        serverId: string;
+    }) => void;
+    /** A role was created in a server. */
+    roleCreate: (data: {
+        id: string;
+        name: string;
+        color: string | null;
+        serverId: string;
+        position: number;
+        hoist: boolean;
+        createdAt: string;
+    }) => void;
+    /** A role was deleted. */
+    roleDelete: (data: {
+        id: string;
+        serverId: string;
+    }) => void;
+    /** A user joined a voice channel. */
+    voiceJoin: (data: {
+        userId: string;
+        channelId: string;
+        serverId: string;
+    }) => void;
+    /** A user left a voice channel. */
+    voiceLeave: (data: {
+        userId: string;
+        channelId: string;
+        serverId: string;
+    }) => void;
+    /** A member was banned from a server. */
+    memberBanned: (data: {
+        userId: string;
+        serverId: string;
+        moderatorId: string | null;
+        reason: string | null;
+    }) => void;
+    /** A member was unbanned. */
+    memberUnbanned: (data: {
+        userId: string;
+        serverId: string;
+    }) => void;
+    /** A member's profile data was updated. */
+    memberUpdate: (data: {
+        userId: string;
+        serverId: string;
+    }) => void;
 }
 /**
- * Fluent builder for select-menu (dropdown) components.
+ * The main Nova bot client.
  *
  * @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' })
+ * import { NovaClient } from 'nova-bot-sdk'
  *
- * await client.messages.send(channelId, { content: 'Choose:', components: [menu.toJSON()] })
- */
-declare class SelectMenuBuilder {
-    private _customId;
-    private _placeholder?;
+ * 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;
+    private readonly _modalHandlers;
+    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;
+    /**
+     * Register a handler for a modal submission by its `customId`.
+     * Called automatically when the user submits a modal with that `customId`.
+     *
+     * @example
+     * client.modal('report_modal', async (interaction) => {
+     *   const reason = interaction.modalData.reason
+     *   await interaction.replyEphemeral(`Report received: ${reason}`)
+     * })
+     */
+    modal(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;
+    /**
+     * Fetch a single channel and return it as a rich `NovaChannel` wrapper.
+     *
+     * @example
+     * const channel = await client.fetchChannel('channel-id')
+     * await channel.send('Hello!')
+     */
+    fetchChannel(channelId: string): Promise<NovaChannel>;
+    /**
+     * Fetch all channels in a server and return them as `NovaChannel` wrappers.
+     *
+     * @example
+     * const channels = await client.fetchChannels('server-id')
+     * const textChannels = channels.filter(c => c.isText())
+     */
+    fetchChannels(serverId: string): Promise<NovaChannel[]>;
+    /**
+     * Fetch all members in a server and return them as `NovaMember` wrappers.
+     *
+     * @example
+     * const members = await client.fetchMembers('server-id')
+     * const bots = members.filter(m => m.isBot)
+     */
+    fetchMembers(serverId: string): Promise<NovaMember[]>;
+    /**
+     * Fetch a single member from a server and return them as a `NovaMember` wrapper.
+     * Throws if the user is not found in the server.
+     *
+     * @example
+     * const member = await client.fetchMember('server-id', 'user-id')
+     * await member.dm('Welcome!')
+     */
+    fetchMember(serverId: string, userId: string): Promise<NovaMember>;
+    /**
+     * Wait for a specific event to be emitted, optionally filtered.
+     * Rejects after `timeoutMs` (default 30 s) if the condition never fires.
+     *
+     * @example
+     * // Wait for any message in a specific channel
+     * const msg = await client.waitFor('messageCreate', m => m.channelId === channelId)
+     *
+     * // Wait for a button click with a timeout
+     * const i = await client.waitFor('interactionCreate', i => i.isButton(), 60_000)
+     */
+    waitFor<K extends keyof NovaClientEvents>(event: K, filter?: (...args: Parameters<NovaClientEvents[K]>) => boolean, timeoutMs?: number): Promise<Parameters<NovaClientEvents[K]>[0]>;
+    /**
+     * 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;
+    /**
+     * Stop a typing indicator via WebSocket.
+     */
+    wsTypingStop(channelId: string): void;
+    on<K extends keyof NovaClientEvents>(event: K, listener: NovaClientEvents[K]): this;
+    on(event: string | symbol, listener: (...args: unknown[]) => void): this;
+    once<K extends keyof NovaClientEvents>(event: K, listener: NovaClientEvents[K]): this;
+    once(event: string | symbol, listener: (...args: unknown[]) => void): this;
+    off<K extends keyof NovaClientEvents>(event: K, listener: NovaClientEvents[K]): this;
+    off(event: string | symbol, listener: (...args: unknown[]) => void): this;
+    emit<K extends keyof NovaClientEvents>(event: K, ...args: Parameters<NovaClientEvents[K]>): boolean;
+    emit(event: string | symbol, ...args: unknown[]): boolean;
+}
+
+/**
+ * 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. */
@@ -1173,92 +2028,829 @@ declare class SelectMenuBuilder {
     toJSON(): MessageComponent;
 }
 
-type ComponentBuilder = ButtonBuilder | SelectMenuBuilder | {
-    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;
+}
+
 /**
- * Groups buttons (and/or a select menu) into a single row of components.
+ * Per-user cooldown manager.
+ * Prevents commands from being spammed by individual users.
  *
  * @example
- * const row = new ActionRowBuilder()
- *   .addComponent(new ButtonBuilder().setCustomId('yes').setLabel('Yes').setStyle('success'))
- *   .addComponent(new ButtonBuilder().setCustomId('no').setLabel('No').setStyle('danger'))
+ * // Create once per command
+ * const cooldown = new Cooldown(5_000) // 5 second cooldown
  *
- * await interaction.reply({ content: 'Confirm?', components: row.toJSON() })
+ * 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 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;
+declare class Cooldown {
+    private readonly _durations;
+    private readonly _last;
+    private readonly _defaultMs;
     /**
-     * Serialise to a flat `MessageComponent[]` array — the format accepted by all API calls.
+     * @param durationMs - Default cooldown duration in milliseconds.
      */
-    toJSON(): MessageComponent[];
+    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;
 }
 
 /**
- * Fluent builder for a single slash command option (parameter).
- * Obtain one via the callback in `SlashCommandBuilder.addStringOption()` etc.
+ * 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 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;
+declare class Logger {
+    private readonly _prefix;
+    private _debug;
     /**
-     * Restrict the option to specific values.
-     * The picker will show these as autocomplete suggestions.
+     * @param name       - Name shown in square brackets before every message.
+     * @param enableDebug - When `false` (default), `.debug()` calls are silent.
      */
-    addChoice(name: string, value: string | number): this;
-    /** Set all allowed choices at once. */
-    setChoices(choices: Array<{
-        name: string;
-        value: string | number;
-    }>): this;
-    toJSON(): SlashCommandOption;
+    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;
 }
+
 /**
- * Fluent builder for slash commands.
+ * Async cursor-based paginator for any list API.
+ *
+ * Pass a `fetchFn` that takes the current cursor and returns the next
+ * page of items plus the cursor to use for the next page (`null` = done).
  *
  * @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(),
- * ])
+ * // Paginate all messages in a channel
+ * const paginator = new Paginator(async (cursor) => {
+ *   const messages = await client.messages.fetch(channelId, { limit: 50, before: cursor ?? undefined })
+ *   return { items: messages, cursor: messages.at(-1)?.id ?? null }
+ * })
+ *
+ * // Lazy async iteration
+ * for await (const message of paginator) {
+ *   console.log(message.content)
+ * }
+ *
+ * // Or collect everything at once
+ * const all = await paginator.fetchAll()
  */
-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;
+declare class Paginator<T> {
+    private readonly fetchFn;
+    private _cursor;
+    private _done;
+    private _totalFetched;
+    constructor(fetchFn: (cursor: string | null) => Promise<{
+        items: T[];
+        cursor: string | null;
+    }>);
+    /** Whether all pages have been consumed. */
+    get done(): boolean;
+    /** Total number of items fetched so far (across all pages). */
+    get totalFetched(): number;
+    /**
+     * Fetch the next page of results.
+     * Returns an empty array when there are no more pages.
+     *
+     * @example
+     * const page1 = await paginator.fetchPage()
+     * const page2 = await paginator.fetchPage()
+     */
+    fetchPage(): Promise<T[]>;
+    /**
+     * Fetch **all** remaining pages and return a flat array.
+     *
+     * ⚠️ Use with caution on very large collections.
+     *
+     * @example
+     * const allMembers = await paginator.fetchAll()
+     */
+    fetchAll(): Promise<T[]>;
+    /**
+     * Fetch up to `n` items total (across however many pages are needed).
+     *
+     * @example
+     * const first100 = await paginator.fetchN(100)
+     */
+    fetchN(n: number): Promise<T[]>;
+    /**
+     * Async-iterate over every item, one page at a time.
+     *
+     * @example
+     * for await (const msg of paginator) {
+     *   process(msg)
+     * }
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<T>;
+    /**
+     * Reset the paginator so you can iterate from the beginning again.
+     *
+     * @example
+     * await paginator.fetchAll()
+     * paginator.reset()
+     * const againFirst = await paginator.fetchPage()
+     */
+    reset(): void;
+}
+
+/**
+ * All known Nova bot permission keys.
+ * Use these as string constants when calling `has()`, `grant()`, etc.
+ */
+declare const Permissions: {
+    /** Read messages in channels. */
+    readonly MESSAGES_READ: "messages.read";
+    /** Send messages in channels. */
+    readonly MESSAGES_WRITE: "messages.write";
+    /** Edit / delete any message (not just the bot's own). */
+    readonly MESSAGES_MANAGE: "messages.manage";
+    /** Create, edit and delete channels. */
+    readonly CHANNELS_MANAGE: "channels.manage";
+    /** Kick members from the server. */
+    readonly MEMBERS_KICK: "members.kick";
+    /** Ban and unban members from the server. */
+    readonly MEMBERS_BAN: "members.ban";
+    /** Assign and remove roles on members. */
+    readonly MEMBERS_ROLES: "members.roles";
+    /** Edit server settings. */
+    readonly SERVERS_MANAGE: "servers.manage";
+};
+type PermissionKey = (typeof Permissions)[keyof typeof Permissions];
+/**
+ * Utility class for working with Nova bot permission records.
+ *
+ * Unlike a Discord-style bitfield, Nova permissions are stored as a
+ * `Record<string, boolean>` map.  `PermissionsBitfield` wraps that
+ * map with readable helpers for checking, merging, and diffing.
+ *
+ * @example
+ * const perms = new PermissionsBitfield({
+ *   'messages.read':  true,
+ *   'messages.write': true,
+ * })
+ *
+ * perms.has('messages.read')          // true
+ * perms.has('channels.manage')        // false
+ * perms.hasAll('messages.read', 'messages.write')  // true
+ * perms.missing('messages.manage', 'members.kick') // ['messages.manage', 'members.kick']
+ * perms.toArray()                     // ['messages.read', 'messages.write']
+ */
+declare class PermissionsBitfield {
+    private readonly _perms;
+    constructor(perms?: Record<string, boolean>);
+    /**
+     * Returns `true` if the given permission is explicitly granted.
+     *
+     * @example
+     * if (!perms.has(Permissions.MESSAGES_WRITE)) {
+     *   throw new Error('Bot cannot write messages here.')
+     * }
+     */
+    has(permission: string): boolean;
+    /**
+     * Returns `true` if **all** listed permissions are granted.
+     *
+     * @example
+     * perms.hasAll('messages.read', 'messages.write') // true
+     */
+    hasAll(...permissions: string[]): boolean;
+    /**
+     * Returns `true` if **at least one** of the listed permissions is granted.
+     *
+     * @example
+     * perms.hasAny('channels.manage', 'servers.manage') // true if either is set
+     */
+    hasAny(...permissions: string[]): boolean;
+    /**
+     * Returns the list of permissions that are **not** granted.
+     *
+     * @example
+     * const missing = perms.missing('messages.write', 'members.kick')
+     * if (missing.length) throw new Error(`Missing: ${missing.join(', ')}`)
+     */
+    missing(...permissions: string[]): string[];
+    /**
+     * Return a **new** `PermissionsBitfield` with the given permission granted.
+     *
+     * @example
+     * const updated = perms.grant('channels.manage')
+     */
+    grant(...permissions: string[]): PermissionsBitfield;
+    /**
+     * Return a **new** `PermissionsBitfield` with the given permission denied.
+     *
+     * @example
+     * const restricted = perms.deny('members.kick')
+     */
+    deny(...permissions: string[]): PermissionsBitfield;
+    /**
+     * Merge another record or `PermissionsBitfield` on top of this one.
+     * The incoming values **override** any existing ones.
+     *
+     * @example
+     * const merged = serverPerms.merge(channelOverrides)
+     */
+    merge(other: Record<string, boolean> | PermissionsBitfield): PermissionsBitfield;
+    /**
+     * Returns an array of the permission keys that are **currently granted**.
+     *
+     * @example
+     * perms.toArray() // ['messages.read', 'messages.write']
+     */
+    toArray(): string[];
+    /**
+     * Returns the raw `Record<string, boolean>` map.
+     */
+    toRecord(): Record<string, boolean>;
+    /**
+     * Pretty-print the granted permissions.
+     *
+     * @example
+     * console.log(String(perms)) // 'PermissionsBitfield[messages.read, messages.write]'
+     */
+    toString(): string;
+    /** Create a `PermissionsBitfield` from an existing record. */
+    static from(perms: Record<string, boolean>): PermissionsBitfield;
+    /** A `PermissionsBitfield` with all known permissions granted. */
+    static readonly ALL: PermissionsBitfield;
+    /** A `PermissionsBitfield` with no permissions granted. */
+    static readonly NONE: PermissionsBitfield;
 }
 
-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 };
+/**
+ * Returns a promise that resolves after `ms` milliseconds.
+ * Useful in retry loops, cron tasks, and staged sends.
+ *
+ * @example
+ * await sleep(2_000) // wait 2 seconds
+ */
+declare function sleep(ms: number): Promise<void>;
+/**
+ * Wraps a promise with a timeout — rejects with an error if the original
+ * promise does not resolve within `ms` milliseconds.
+ *
+ * @example
+ * const result = await withTimeout(fetchData(), 5_000, 'fetchData took too long')
+ */
+declare function withTimeout<T>(promise: Promise<T>, ms: number, message?: string): Promise<T>;
+/**
+ * Format a duration in milliseconds to a compact human-readable string.
+ *
+ * @example
+ * formatDuration(0)          // '0s'
+ * formatDuration(90_000)     // '1m 30s'
+ * formatDuration(3_661_000)  // '1h 1m 1s'
+ * formatDuration(604_800_000) // '1w'
+ */
+declare function formatDuration(ms: number): string;
+/**
+ * Format a timestamp as a relative human-readable string from now.
+ * Accepts a `Date`, a Unix timestamp (ms), or an ISO date string.
+ *
+ * @example
+ * formatRelative(Date.now() - 5_000)    // 'just now'
+ * formatRelative(Date.now() - 90_000)   // '1 minute ago'
+ * formatRelative(Date.now() + 60_000)   // 'in 1 minute'
+ * formatRelative(Date.now() - 86_400_000) // 'yesterday'
+ */
+declare function formatRelative(timestamp: Date | number | string): string;
+/**
+ * Safely parse any timestamp (ISO string, Unix ms, or Date) to a `Date`.
+ * Returns `null` if the input is nullish or not parseable.
+ *
+ * @example
+ * parseTimestamp('2026-01-01T00:00:00.000Z') // Date
+ * parseTimestamp(null)                        // null
+ */
+declare function parseTimestamp(value: string | number | Date | null | undefined): Date | null;
+/**
+ * Returns the remaining time until a target date as an object with components.
+ * All values are `0` if the target is in the past.
+ *
+ * @example
+ * const { days, hours, minutes, seconds } = countdown(new Date('2027-01-01'))
+ * console.log(`${days}d ${hours}h ${minutes}m ${seconds}s remaining`)
+ */
+declare function countdown(target: Date | number | string): {
+    weeks: number;
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+    total: number;
+};
+
+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 DirectMessage, 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, NovaChannel, NovaClient, type NovaClientEvents, type NovaClientOptions, NovaInteraction, NovaMember, NovaMessage, type NovaServer, Paginator, type PermissionKey, Permissions, PermissionsAPI, PermissionsBitfield, 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, type VoiceState, countdown, formatDuration, formatRelative, parseTimestamp, sleep, withTimeout };