novaapp-sdk 1.1.0 → 1.3.0

package/dist/index.js

@@ -22,22 +22,42 @@ var index_exports = {};
 __export(index_exports, {
   ActionRowBuilder: () => ActionRowBuilder,
   ButtonBuilder: () => ButtonBuilder,
+  ChannelsAPI: () => ChannelsAPI,
+  Collection: () => Collection,
   CommandsAPI: () => CommandsAPI,
+  Cooldown: () => Cooldown,
+  CooldownManager: () => CooldownManager,
   EmbedBuilder: () => EmbedBuilder,
   HttpClient: () => HttpClient,
   InteractionOptions: () => InteractionOptions,
   InteractionsAPI: () => InteractionsAPI,
+  Logger: () => Logger,
   MembersAPI: () => MembersAPI,
+  MessageBuilder: () => MessageBuilder,
   MessagesAPI: () => MessagesAPI,
   ModalBuilder: () => ModalBuilder,
+  NovaChannel: () => NovaChannel,
   NovaClient: () => NovaClient,
   NovaInteraction: () => NovaInteraction,
+  NovaMember: () => NovaMember,
+  NovaMessage: () => NovaMessage,
+  Paginator: () => Paginator,
+  Permissions: () => Permissions,
   PermissionsAPI: () => PermissionsAPI,
+  PermissionsBitfield: () => PermissionsBitfield,
+  PollBuilder: () => PollBuilder,
+  ReactionsAPI: () => ReactionsAPI,
   SelectMenuBuilder: () => SelectMenuBuilder,
   ServersAPI: () => ServersAPI,
   SlashCommandBuilder: () => SlashCommandBuilder,
   SlashCommandOptionBuilder: () => SlashCommandOptionBuilder,
-  TextInputBuilder: () => TextInputBuilder
+  TextInputBuilder: () => TextInputBuilder,
+  countdown: () => countdown,
+  formatDuration: () => formatDuration,
+  formatRelative: () => formatRelative,
+  parseTimestamp: () => parseTimestamp,
+  sleep: () => sleep,
+  withTimeout: () => withTimeout
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -135,6 +155,70 @@ var MessagesAPI = class {
   typing(channelId) {
     return this.http.post(`/channels/${channelId}/typing`);
   }
+  /**
+   * Fetch a single message by ID.
+   *
+   * @example
+   * const msg = await client.messages.fetchOne('message-id')
+   */
+  fetchOne(messageId) {
+    return this.http.get(`/messages/${messageId}`);
+  }
+  /**
+   * Pin a message in its channel.
+   * The bot must have the `messages.manage` scope.
+   *
+   * @example
+   * await client.messages.pin('message-id')
+   */
+  pin(messageId) {
+    return this.http.post(`/messages/${messageId}/pin`);
+  }
+  /**
+   * Unpin a message.
+   *
+   * @example
+   * await client.messages.unpin('message-id')
+   */
+  unpin(messageId) {
+    return this.http.delete(`/messages/${messageId}/pin`);
+  }
+  /**
+   * Fetch all pinned messages in a channel.
+   *
+   * @example
+   * const pins = await client.messages.fetchPinned('channel-id')
+   */
+  fetchPinned(channelId) {
+    return this.http.get(`/channels/${channelId}/pins`);
+  }
+  /**
+   * Add a reaction to a message.
+   *
+   * @example
+   * await client.messages.addReaction('message-id', '👍')
+   */
+  addReaction(messageId, emoji) {
+    return this.http.post(`/messages/${messageId}/reactions/${encodeURIComponent(emoji)}`);
+  }
+  /**
+   * Remove the bot's reaction from a message.
+   *
+   * @example
+   * await client.messages.removeReaction('message-id', '👍')
+   */
+  removeReaction(messageId, emoji) {
+    return this.http.delete(`/messages/${messageId}/reactions/${encodeURIComponent(emoji)}`);
+  }
+  /**
+   * Fetch all reactions on a message.
+   *
+   * @example
+   * const reactions = await client.messages.fetchReactions('message-id')
+   */
+  fetchReactions(messageId) {
+    return this.http.get(`/messages/${messageId}/reactions`);
+  }
 };
 
 // src/api/commands.ts
@@ -262,6 +346,61 @@ var MembersAPI = class {
   ban(serverId, userId, reason) {
     return this.http.post(`/servers/${serverId}/members/${userId}/ban`, { reason });
   }
+  /**
+   * Unban a previously banned user.
+   * Requires the `members.ban` scope.
+   *
+   * @example
+   * await client.members.unban('server-id', 'user-id')
+   */
+  unban(serverId, userId) {
+    return this.http.delete(`/servers/${serverId}/bans/${userId}`);
+  }
+  /**
+   * 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) {
+    return this.http.get(`/servers/${serverId}/bans`);
+  }
+  /**
+   * 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, options) {
+    const body = typeof options === "string" ? { content: options } : options;
+    return this.http.post(`/users/${userId}/dm`, body);
+  }
+  /**
+   * Add a role to a member.
+   * Requires the `members.roles` scope.
+   *
+   * @example
+   * await client.members.addRole('server-id', 'user-id', 'role-id')
+   */
+  addRole(serverId, userId, roleId) {
+    return this.http.post(`/servers/${serverId}/members/${userId}/roles/${roleId}`);
+  }
+  /**
+   * Remove a role from a member.
+   * Requires the `members.roles` scope.
+   *
+   * @example
+   * await client.members.removeRole('server-id', 'user-id', 'role-id')
+   */
+  removeRole(serverId, userId, roleId) {
+    return this.http.delete(`/servers/${serverId}/members/${userId}/roles/${roleId}`);
+  }
 };
 
 // src/api/servers.ts
@@ -279,6 +418,17 @@ var ServersAPI = class {
   list() {
     return this.http.get("/servers");
   }
+  /**
+   * 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) {
+    return this.http.get(`/servers/${serverId}/roles`);
+  }
 };
 
 // src/api/interactions.ts
@@ -445,6 +595,172 @@ var PermissionsAPI = class {
   }
 };
 
+// src/api/channels.ts
+var ChannelsAPI = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * 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) {
+    return this.http.get(`/servers/${serverId}/channels`);
+  }
+  /**
+   * Fetch a single channel by ID.
+   *
+   * @example
+   * const channel = await client.channels.fetch('channel-id')
+   * console.log(channel.name, channel.type)
+   */
+  fetch(channelId) {
+    return this.http.get(`/channels/${channelId}`);
+  }
+  /**
+   * 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, options) {
+    return this.http.post(`/servers/${serverId}/channels`, options);
+  }
+  /**
+   * Edit an existing channel.
+   * Requires the `channels.manage` scope.
+   *
+   * @example
+   * await client.channels.edit('channel-id', { topic: 'New topic!' })
+   */
+  edit(channelId, options) {
+    return this.http.patch(`/channels/${channelId}`, options);
+  }
+  /**
+   * Delete a channel.
+   * Requires the `channels.manage` scope.
+   *
+   * @example
+   * await client.channels.delete('channel-id')
+   */
+  delete(channelId) {
+    return this.http.delete(`/channels/${channelId}`);
+  }
+  /**
+   * Fetch messages from a channel.
+   *
+   * @example
+   * const messages = await client.channels.fetchMessages('channel-id', { limit: 50 })
+   */
+  fetchMessages(channelId, options = {}) {
+    const params = new URLSearchParams();
+    if (options.limit) params.set("limit", String(options.limit));
+    if (options.before) params.set("before", options.before);
+    const qs = params.toString();
+    return this.http.get(`/channels/${channelId}/messages${qs ? `?${qs}` : ""}`);
+  }
+  /**
+   * Fetch all pinned messages in a channel.
+   *
+   * @example
+   * const pins = await client.channels.fetchPins('channel-id')
+   */
+  fetchPins(channelId) {
+    return this.http.get(`/channels/${channelId}/pins`);
+  }
+  /**
+   * Send a typing indicator in a channel.
+   * Displayed to users for ~5 seconds.
+   *
+   * @example
+   * await client.channels.startTyping('channel-id')
+   */
+  startTyping(channelId) {
+    return this.http.post(`/channels/${channelId}/typing`);
+  }
+};
+
+// src/api/reactions.ts
+var ReactionsAPI = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * 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, emoji) {
+    const encoded = encodeURIComponent(emoji);
+    return this.http.post(`/messages/${messageId}/reactions/${encoded}`);
+  }
+  /**
+   * Remove the bot's reaction from a message.
+   *
+   * @example
+   * await client.reactions.remove('message-id', '👍')
+   */
+  remove(messageId, emoji) {
+    const encoded = encodeURIComponent(emoji);
+    return this.http.delete(`/messages/${messageId}/reactions/${encoded}`);
+  }
+  /**
+   * Remove all reactions from a message.
+   * Requires the `messages.manage` scope.
+   *
+   * @example
+   * await client.reactions.removeAll('message-id')
+   */
+  removeAll(messageId) {
+    return this.http.delete(`/messages/${messageId}/reactions`);
+  }
+  /**
+   * Remove all reactions of a specific emoji from a message.
+   * Requires the `messages.manage` scope.
+   *
+   * @example
+   * await client.reactions.removeEmoji('message-id', '👍')
+   */
+  removeEmoji(messageId, emoji) {
+    const encoded = encodeURIComponent(emoji);
+    return this.http.delete(`/messages/${messageId}/reactions/${encoded}/all`);
+  }
+  /**
+   * 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) {
+    return this.http.get(`/messages/${messageId}/reactions`);
+  }
+  /**
+   * 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, emoji) {
+    const encoded = encodeURIComponent(emoji);
+    return this.http.get(`/messages/${messageId}/reactions/${encoded}`);
+  }
+};
+
 // src/structures/NovaInteraction.ts
 var InteractionOptions = class {
   constructor(data) {
@@ -624,651 +940,2143 @@ var NovaInteraction = class _NovaInteraction {
   }
 };
 
-// src/client.ts
-var EVENT_MAP = {
-  "message.created": "messageCreate",
-  "message.edited": "messageUpdate",
-  "message.deleted": "messageDelete",
-  "message.reaction_added": "reactionAdd",
-  "message.reaction_removed": "reactionRemove",
-  "user.joined_server": "memberAdd",
-  "user.left_server": "memberRemove",
-  "user.started_typing": "typingStart"
-};
-var NovaClient = class extends import_node_events.EventEmitter {
-  constructor(options) {
-    super();
-    /** The authenticated bot application. Available after `ready` fires. */
-    this.botUser = null;
-    this.socket = null;
-    // ── Command / component routing ───────────────────────────────────────────────────
-    this._commandHandlers = /* @__PURE__ */ new Map();
-    this._buttonHandlers = /* @__PURE__ */ new Map();
-    this._selectHandlers = /* @__PURE__ */ new Map();
-    if (!options.token) {
-      throw new Error("[nova-bot-sdk] A bot token is required.");
-    }
-    if (!options.token.startsWith("nova_bot_")) {
-      console.warn('[nova-bot-sdk] Warning: token does not start with "nova_bot_". Are you sure this is a bot token?');
-    }
-    this.options = {
-      token: options.token,
-      baseUrl: options.baseUrl ?? "https://novachatapp.com"
-    };
-    this.http = new HttpClient(this.options.baseUrl, this.options.token);
-    this.messages = new MessagesAPI(this.http);
-    this.commands = new CommandsAPI(this.http);
-    this.members = new MembersAPI(this.http);
-    this.servers = new ServersAPI(this.http);
-    this.interactions = new InteractionsAPI(this.http, this);
-    this.permissions = new PermissionsAPI(this.http);
-    this.on("error", () => {
-    });
-    const cleanup = () => this.disconnect();
-    process.once("beforeExit", cleanup);
-    process.once("SIGINT", () => {
-      cleanup();
-      process.exit(0);
-    });
-    process.once("SIGTERM", () => {
-      cleanup();
-      process.exit(0);
-    });
+// src/structures/NovaMessage.ts
+var NovaMessage = class _NovaMessage {
+  constructor(raw, messages, reactions) {
+    this.id = raw.id;
+    this.content = raw.content;
+    this.channelId = raw.channelId;
+    this.author = raw.author;
+    this.embed = raw.embed ?? null;
+    this.components = raw.components ?? [];
+    this.replyToId = raw.replyToId ?? null;
+    this.attachments = raw.attachments ?? [];
+    this.reactions = raw.reactions ?? [];
+    this.createdAt = new Date(raw.createdAt);
+    this.editedAt = raw.editedAt ? new Date(raw.editedAt) : null;
+    this._messages = messages;
+    this._reactions = reactions;
+  }
+  // ─── Type guards ─────────────────────────────────────────────────────────────
+  /** Returns true if the message was sent by a bot. */
+  isFromBot() {
+    return this.author.isBot === true;
+  }
+  /** Returns true if the message has an embed. */
+  hasEmbed() {
+    return this.embed !== null;
+  }
+  /** Returns true if the message has interactive components. */
+  hasComponents() {
+    return this.components.length > 0;
+  }
+  /** Returns true if the message has been edited. */
+  isEdited() {
+    return this.editedAt !== null;
+  }
+  // ─── Reactions ────────────────────────────────────────────────────────────────
+  /**
+   * Add a reaction to this message.
+   *
+   * @example
+   * await msg.react('👍')
+   * await msg.react('🎉')
+   */
+  react(emoji) {
+    return this._reactions.add(this.id, emoji);
   }
   /**
-   * Register a handler for a slash or prefix command by name.
-   * Automatically routes `interactionCreate` events whose `commandName` matches.
+   * Remove the bot's reaction from this message.
    *
    * @example
-   * client.command('ping', async (interaction) => {
-   *   await interaction.reply('Pong! 🏓')
-   * })
+   * await msg.removeReaction('👍')
    */
-  command(name, handler) {
-    this._commandHandlers.set(name, handler);
-    return this;
+  removeReaction(emoji) {
+    return this._reactions.remove(this.id, emoji);
   }
+  // ─── Messaging ────────────────────────────────────────────────────────────────
   /**
-   * Register a handler for a button by its `customId`.
+   * Reply to this message.
    *
    * @example
-   * client.button('confirm_delete', async (interaction) => {
-   *   await interaction.replyEphemeral('Deleted.')
-   * })
+   * await msg.reply('Got it!')
+   * await msg.reply({ embed: new EmbedBuilder().setTitle('Result').toJSON() })
    */
-  button(customId, handler) {
-    this._buttonHandlers.set(customId, handler);
-    return this;
+  reply(options) {
+    const opts = typeof options === "string" ? { content: options, replyToId: this.id } : { ...options, replyToId: this.id };
+    return this._messages.send(this.channelId, opts).then((raw) => new _NovaMessage(raw, this._messages, this._reactions));
   }
   /**
-   * Register a handler for a select menu by its `customId`.
+   * Edit this message.
+   * Only works if the bot is the author.
    *
    * @example
-   * client.selectMenu('colour_pick', async (interaction) => {
-   *   const chosen = interaction.values[0]
-   *   await interaction.reply(`You picked: ${chosen}`)
-   * })
+   * await msg.edit('Updated content')
+   * await msg.edit({ content: 'Updated', embed: { title: 'New embed' } })
    */
-  selectMenu(customId, handler) {
-    this._selectHandlers.set(customId, handler);
-    return this;
+  edit(options) {
+    const opts = typeof options === "string" ? { content: options } : options;
+    return this._messages.edit(this.id, opts).then((raw) => new _NovaMessage(raw, this._messages, this._reactions));
   }
   /**
-   * Connect to the Nova WebSocket gateway.
-   * Resolves when the `ready` event is received.
+   * Delete this message.
+   * Only works if the bot is the author.
    *
    * @example
-   * await client.connect()
+   * await msg.delete()
    */
-  connect() {
-    return new Promise((resolve, reject) => {
-      const gatewayUrl = this.options.baseUrl.replace(/\/$/, "") + "/bot-gateway";
-      this.socket = (0, import_socket.io)(gatewayUrl, {
-        path: "/socket.io",
-        transports: ["websocket"],
-        auth: { botToken: this.options.token },
-        reconnection: true,
-        reconnectionAttempts: Infinity,
-        reconnectionDelay: 1e3,
-        reconnectionDelayMax: 3e4
-      });
-      const onConnectError = (err) => {
-        this.socket?.disconnect();
-        this.socket = null;
-        reject(new Error(`[nova-bot-sdk] Gateway connection failed: ${err.message}`));
-      };
-      this.socket.once("connect_error", onConnectError);
-      this.socket.once("bot:ready", (data) => {
-        this.socket.off("connect_error", onConnectError);
-        this.botUser = {
-          ...data.bot,
-          scopes: data.scopes,
-          // Flatten botUser fields for convenience so bot.username works
-          username: data.bot.botUser?.username ?? data.bot.name,
-          displayName: data.bot.botUser?.displayName ?? data.bot.name
-        };
-        this.emit("ready", this.botUser);
-        resolve();
-      });
-      this.socket.on("interaction:created", (raw) => {
-        const interaction = new NovaInteraction(raw, this.interactions);
-        this.emit("interactionCreate", interaction);
-        const run = (h) => {
-          if (h) Promise.resolve(h(interaction)).catch((e) => this.emit("error", e));
-        };
-        if (interaction.isCommand() && interaction.commandName) {
-          run(this._commandHandlers.get(interaction.commandName));
-        } else if (interaction.isButton() && interaction.customId) {
-          run(this._buttonHandlers.get(interaction.customId));
-        } else if (interaction.isSelectMenu() && interaction.customId) {
-          run(this._selectHandlers.get(interaction.customId));
-        }
-      });
-      this.socket.on("bot:event", (event) => {
-        this.emit("event", event);
-        const shorthand = EVENT_MAP[event.type];
-        if (shorthand) {
-          this.emit(shorthand, event.data);
-        }
-      });
-      this.socket.on("bot:error", (err) => {
-        this.emit("error", err);
-      });
-      this.socket.on("disconnect", (reason) => {
-        this.emit("disconnect", reason);
-      });
-    });
+  delete() {
+    return this._messages.delete(this.id);
   }
   /**
-   * Disconnect from the gateway and clean up.
+   * Pin this message in its channel.
+   *
+   * @example
+   * await msg.pin()
    */
-  disconnect() {
-    if (this.socket) {
-      const sock = this.socket;
-      this.socket = null;
-      try {
-        sock.io.reconnection(false);
-      } catch {
-      }
-      try {
-        sock.io?.engine?.socket?.terminate?.();
-      } catch {
-      }
-      try {
-        sock.io?.engine?.socket?.destroy?.();
-      } catch {
-      }
-      try {
-        sock.io?.engine?.close?.();
-      } catch {
-      }
-      try {
-        sock.disconnect();
-      } catch {
-      }
-    }
+  pin() {
+    return this._messages.pin(this.id);
   }
   /**
-   * Send a message via the WebSocket gateway (lower latency than HTTP).
-   * Requires the `messages.write` scope.
+   * Unpin this message.
    *
    * @example
-   * client.wsSend('channel-id', 'Hello from the gateway!')
+   * await msg.unpin()
    */
-  wsSend(channelId, content) {
-    if (!this.socket?.connected) {
-      throw new Error("[nova-bot-sdk] Not connected. Call client.connect() first.");
-    }
-    this.socket.emit("bot:message:send", { channelId, content });
+  unpin() {
+    return this._messages.unpin(this.id);
   }
   /**
-   * Start a typing indicator via WebSocket.
+   * Re-fetch the latest version of this message from the server.
+   *
+   * @example
+   * const fresh = await msg.fetch()
    */
-  wsTypingStart(channelId) {
-    this.socket?.emit("bot:typing:start", { channelId });
+  async fetch() {
+    const raw = await this._messages.fetchOne(this.id);
+    return new _NovaMessage(raw, this._messages, this._reactions);
   }
   /**
-   * Stop a typing indicator via WebSocket.
+   * Get a URL to this message (deep link).
    */
-  wsTypingStop(channelId) {
-    this.socket?.emit("bot:typing:stop", { channelId });
-  }
-  on(event, listener) {
-    return super.on(event, listener);
-  }
-  once(event, listener) {
-    return super.once(event, listener);
+  get url() {
+    return `/channels/${this.channelId}/messages/${this.id}`;
   }
-  off(event, listener) {
-    return super.off(event, listener);
+  /**
+   * Return the raw message object.
+   */
+  toJSON() {
+    return {
+      id: this.id,
+      content: this.content,
+      channelId: this.channelId,
+      author: this.author,
+      embed: this.embed,
+      components: this.components,
+      replyToId: this.replyToId,
+      attachments: this.attachments,
+      reactions: this.reactions,
+      createdAt: this.createdAt.toISOString(),
+      editedAt: this.editedAt?.toISOString() ?? null
+    };
   }
-  emit(event, ...args) {
-    return super.emit(event, ...args);
+  toString() {
+    return `NovaMessage(${this.id}): ${this.content.slice(0, 50)}${this.content.length > 50 ? "\u2026" : ""}`;
   }
 };
 
-// src/builders/EmbedBuilder.ts
-var EmbedBuilder = class {
-  constructor() {
-    this._data = {};
-  }
-  /** Set the embed title (shown in bold at the top). */
-  setTitle(title) {
-    this._data.title = title;
-    return this;
-  }
-  /** Set the main description text (supports markdown). */
-  setDescription(description) {
-    this._data.description = description;
-    return this;
-  }
+// src/structures/NovaChannel.ts
+var NovaChannel = class _NovaChannel {
+  constructor(raw, channels, messages) {
+    this.id = raw.id;
+    this.name = raw.name;
+    this.type = raw.type;
+    this.serverId = raw.serverId;
+    this.topic = raw.topic;
+    this.position = raw.position;
+    this.slowMode = raw.slowMode ?? 0;
+    this.createdAt = new Date(raw.createdAt);
+    this._channels = channels;
+    this._messages = messages;
+  }
+  // ─── Type guards ────────────────────────────────────────────────────────────
+  /** `true` for text channels. */
+  isText() {
+    return this.type === "TEXT";
+  }
+  /** `true` for voice channels. */
+  isVoice() {
+    return this.type === "VOICE";
+  }
+  /** `true` for announcement channels. */
+  isAnnouncement() {
+    return this.type === "ANNOUNCEMENT";
+  }
+  /** `true` for forum channels. */
+  isForum() {
+    return this.type === "FORUM";
+  }
+  /** `true` for stage channels. */
+  isStage() {
+    return this.type === "STAGE";
+  }
+  /** `true` if slow-mode is enabled on this channel. */
+  hasSlowMode() {
+    return this.slowMode > 0;
+  }
+  // ─── Messaging ──────────────────────────────────────────────────────────────
   /**
-   * 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) {
-    this._data.color = color.startsWith("#") ? color : `#${color}`;
-    return this;
-  }
-  /** Make the title a clickable hyperlink. */
-  setUrl(url) {
-    this._data.url = url;
-    return this;
-  }
-  /** Small image shown in the top-right corner. */
-  setThumbnail(url) {
-    this._data.thumbnail = url;
-    return this;
-  }
-  /** Large image shown below the fields. */
-  setImage(url) {
-    this._data.image = url;
-    return this;
+  send(options) {
+    const body = typeof options === "string" ? { content: options } : options;
+    return this._messages.send(this.id, body);
   }
-  /** Footer text shown at the very bottom of the embed. */
-  setFooter(text) {
-    this._data.footer = text;
-    return this;
+  /**
+   * Fetch recent messages from this channel.
+   *
+   * @example
+   * const messages = await channel.fetchMessages({ limit: 50 })
+   */
+  fetchMessages(options = {}) {
+    return this._channels.fetchMessages(this.id, options);
   }
   /**
-   * Add a timestamp to the footer line.
-   * @param date Defaults to `new Date()`.
+   * Fetch all pinned messages in this channel.
+   *
+   * @example
+   * const pins = await channel.fetchPins()
    */
-  setTimestamp(date) {
-    const d = date instanceof Date ? date : date != null ? new Date(date) : /* @__PURE__ */ new Date();
-    this._data.timestamp = d.toISOString();
-    return this;
+  fetchPins() {
+    return this._channels.fetchPins(this.id);
   }
-  /** Author name + optional icon shown above the title. */
-  setAuthor(author) {
-    this._data.author = author;
-    return this;
+  /**
+   * Start a typing indicator (shows "Bot is typing…" for ~5 seconds).
+   *
+   * @example
+   * await channel.startTyping()
+   */
+  startTyping() {
+    return this._channels.startTyping(this.id);
   }
+  // ─── Management ─────────────────────────────────────────────────────────────
   /**
-   * Add a single field.
-   * @param inline Pass `true` to render this field side-by-side with adjacent inline fields.
+   * Edit this channel's properties.
+   * Requires the `channels.manage` scope.
+   *
+   * @example
+   * await channel.edit({ name: 'general-2', topic: 'The second general channel' })
    */
-  addField(name, value, inline) {
-    if (!this._data.fields) this._data.fields = [];
-    this._data.fields.push({ name, value, inline });
-    return this;
+  async edit(options) {
+    const raw = await this._channels.edit(this.id, options);
+    return new _NovaChannel(raw, this._channels, this._messages);
   }
-  /** Add multiple fields at once. */
-  addFields(...fields) {
-    if (!this._data.fields) this._data.fields = [];
-    this._data.fields.push(...fields);
-    return this;
+  /**
+   * Delete this channel.
+   * Requires the `channels.manage` scope.
+   *
+   * @example
+   * await channel.delete()
+   */
+  delete() {
+    return this._channels.delete(this.id);
   }
-  /** Replace all fields. */
-  setFields(fields) {
-    this._data.fields = [...fields];
-    return this;
+  // ─── Serialisation ──────────────────────────────────────────────────────────
+  /**
+   * Returns the channel as a mention-style string: `#name`.
+   */
+  toString() {
+    return `#${this.name}`;
   }
-  /** Serialise to a plain `Embed` object you can pass to any API call. */
+  /** Returns the raw channel data. */
   toJSON() {
     return {
-      ...this._data,
-      fields: this._data.fields ? [...this._data.fields] : void 0
+      id: this.id,
+      name: this.name,
+      type: this.type,
+      serverId: this.serverId,
+      topic: this.topic,
+      position: this.position,
+      slowMode: this.slowMode,
+      createdAt: this.createdAt.toISOString()
     };
   }
 };
 
-// src/builders/ButtonBuilder.ts
-var ButtonBuilder = class {
-  constructor() {
-    this._customId = "";
-    this._label = "";
-    this._style = "primary";
-    this._disabled = false;
-  }
-  /** Custom ID returned in the `BUTTON_CLICK` interaction. Not required for `link` style buttons. */
-  setCustomId(customId) {
-    this._customId = customId;
-    return this;
+// src/structures/NovaMember.ts
+var NovaMember = class {
+  constructor(raw, serverId, members) {
+    this.userId = raw.user.id;
+    this.serverId = serverId;
+    this.username = raw.user.username;
+    this.displayName = raw.user.displayName;
+    this.avatar = raw.user.avatar;
+    this.role = raw.role;
+    this.status = raw.user.status;
+    this.isBot = raw.user.isBot;
+    this.joinedAt = new Date(raw.joinedAt);
+    this._members = members;
+  }
+  // ─── Type guards ────────────────────────────────────────────────────────────
+  /** `true` if this member is the server owner. */
+  isOwner() {
+    return this.role === "OWNER";
+  }
+  /** `true` if this member is an admin or the server owner. */
+  isAdmin() {
+    return this.role === "ADMIN" || this.role === "OWNER";
+  }
+  /** `true` if this member is a regular (non-privileged) member. */
+  isRegularMember() {
+    return this.role === "MEMBER";
+  }
+  /** `true` if the user is currently online. */
+  isOnline() {
+    return this.status === "ONLINE";
+  }
+  /** `true` if the user is idle / away. */
+  isIdle() {
+    return this.status === "IDLE";
+  }
+  /** `true` if the user is set to Do Not Disturb. */
+  isDND() {
+    return this.status === "DND";
+  }
+  /** `true` if the user appears offline. */
+  isOffline() {
+    return this.status === "OFFLINE";
+  }
+  // ─── Actions ────────────────────────────────────────────────────────────────
+  /**
+   * Kick this member from the server.
+   * Bots cannot kick owners or admins (throws 403).
+   *
+   * @example
+   * await member.kick()
+   */
+  kick() {
+    return this._members.kick(this.serverId, this.userId);
   }
-  /** Text displayed on the button. */
-  setLabel(label) {
-    this._label = label;
-    return this;
+  /**
+   * 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')
+   */
+  ban(reason) {
+    return this._members.ban(this.serverId, this.userId, reason);
   }
   /**
-   * Visual style:
-   * - `primary` — blurple / brand colour
-   * - `secondary` — grey
-   * - `success` — green
-   * - `danger` — red
-   * - `link` — grey, navigates to a URL instead of creating an interaction
+   * 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' } })
    */
-  setStyle(style) {
-    this._style = style;
-    return this;
+  dm(options) {
+    return this._members.dm(this.userId, options);
   }
-  /** Emoji shown to the left of the label (unicode or custom e.g. `'👋'`). */
-  setEmoji(emoji) {
-    this._emoji = emoji;
-    return this;
+  /**
+   * Assign a custom role to this member.
+   * Requires the `members.roles` scope.
+   *
+   * @example
+   * await member.addRole('role-id')
+   */
+  addRole(roleId) {
+    return this._members.addRole(this.serverId, this.userId, roleId);
   }
   /**
-   * URL for `link` style buttons.
-   * Sets the style to `'link'` automatically.
+   * Remove a custom role from this member.
+   * Requires the `members.roles` scope.
+   *
+   * @example
+   * await member.removeRole('role-id')
    */
-  setUrl(url) {
-    this._url = url;
-    this._style = "link";
-    return this;
+  removeRole(roleId) {
+    return this._members.removeRole(this.serverId, this.userId, roleId);
   }
-  /** Prevent users from clicking the button. */
-  setDisabled(disabled = true) {
-    this._disabled = disabled;
-    return this;
+  // ─── Serialisation ──────────────────────────────────────────────────────────
+  /**
+   * Returns a mention-style string: `@displayName`.
+   */
+  toString() {
+    return `@${this.displayName}`;
   }
+  /** Returns the raw member data. */
   toJSON() {
     return {
-      type: "button",
-      customId: this._customId,
-      label: this._label || void 0,
-      style: this._style,
-      emoji: this._emoji,
-      url: this._url,
-      disabled: this._disabled || void 0
+      role: this.role,
+      joinedAt: this.joinedAt.toISOString(),
+      user: {
+        id: this.userId,
+        username: this.username,
+        displayName: this.displayName,
+        avatar: this.avatar,
+        status: this.status,
+        isBot: this.isBot
+      }
     };
   }
 };
 
-// src/builders/SelectMenuBuilder.ts
-var SelectMenuBuilder = class {
-  constructor() {
-    this._customId = "";
-    this._disabled = false;
-    this._options = [];
-  }
-  /** Custom ID returned in the `SELECT_MENU` interaction. */
-  setCustomId(customId) {
-    this._customId = customId;
-    return this;
-  }
-  /** Greyed-out hint shown when nothing is selected. */
-  setPlaceholder(placeholder) {
-    this._placeholder = placeholder;
-    return this;
-  }
+// src/client.ts
+var NovaClient = class extends import_node_events.EventEmitter {
+  constructor(options) {
+    super();
+    /** The authenticated bot application. Available after `ready` fires. */
+    this.botUser = null;
+    this.socket = null;
+    this._cronTimers = [];
+    // ── Command / component routing ───────────────────────────────────────────────────
+    this._commandHandlers = /* @__PURE__ */ new Map();
+    this._buttonHandlers = /* @__PURE__ */ new Map();
+    this._selectHandlers = /* @__PURE__ */ new Map();
+    this._modalHandlers = /* @__PURE__ */ new Map();
+    if (!options.token) {
+      throw new Error("[nova-bot-sdk] A bot token is required.");
+    }
+    if (!options.token.startsWith("nova_bot_")) {
+      console.warn('[nova-bot-sdk] Warning: token does not start with "nova_bot_". Are you sure this is a bot token?');
+    }
+    this.options = {
+      token: options.token,
+      baseUrl: options.baseUrl ?? "https://novachatapp.com"
+    };
+    this.http = new HttpClient(this.options.baseUrl, this.options.token);
+    this.messages = new MessagesAPI(this.http);
+    this.commands = new CommandsAPI(this.http);
+    this.members = new MembersAPI(this.http);
+    this.servers = new ServersAPI(this.http);
+    this.interactions = new InteractionsAPI(this.http, this);
+    this.permissions = new PermissionsAPI(this.http);
+    this.channels = new ChannelsAPI(this.http);
+    this.reactions = new ReactionsAPI(this.http);
+    this.on("error", () => {
+    });
+    const cleanup = () => this.disconnect();
+    process.once("beforeExit", cleanup);
+    process.once("SIGINT", () => {
+      cleanup();
+      process.exit(0);
+    });
+    process.once("SIGTERM", () => {
+      cleanup();
+      process.exit(0);
+    });
+  }
+  /**
+   * 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, handler) {
+    this._commandHandlers.set(name, handler);
+    return this;
+  }
+  /**
+   * Register a handler for a button by its `customId`.
+   *
+   * @example
+   * client.button('confirm_delete', async (interaction) => {
+   *   await interaction.replyEphemeral('Deleted.')
+   * })
+   */
+  button(customId, handler) {
+    this._buttonHandlers.set(customId, handler);
+    return 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, handler) {
+    this._selectHandlers.set(customId, handler);
+    return 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, handler) {
+    this._modalHandlers.set(customId, handler);
+    return this;
+  }
+  /**
+   * Connect to the Nova WebSocket gateway.
+   * Resolves when the `ready` event is received.
+   *
+   * @example
+   * await client.connect()
+   */
+  connect() {
+    return new Promise((resolve, reject) => {
+      const gatewayUrl = this.options.baseUrl.replace(/\/$/, "") + "/bot-gateway";
+      this.socket = (0, import_socket.io)(gatewayUrl, {
+        path: "/socket.io",
+        transports: ["websocket"],
+        auth: { botToken: this.options.token },
+        reconnection: true,
+        reconnectionAttempts: Infinity,
+        reconnectionDelay: 1e3,
+        reconnectionDelayMax: 3e4
+      });
+      const onConnectError = (err) => {
+        this.socket?.disconnect();
+        this.socket = null;
+        reject(new Error(`[nova-bot-sdk] Gateway connection failed: ${err.message}`));
+      };
+      this.socket.once("connect_error", onConnectError);
+      this.socket.once("bot:ready", (data) => {
+        this.socket.off("connect_error", onConnectError);
+        this.botUser = {
+          ...data.bot,
+          scopes: data.scopes,
+          // Flatten botUser fields for convenience so bot.username works
+          username: data.bot.botUser?.username ?? data.bot.name,
+          displayName: data.bot.botUser?.displayName ?? data.bot.name
+        };
+        this.emit("ready", this.botUser);
+        resolve();
+      });
+      this.socket.on("interaction:created", (raw) => {
+        const interaction = new NovaInteraction(raw, this.interactions);
+        this.emit("interactionCreate", interaction);
+        const run = (h) => {
+          if (h) Promise.resolve(h(interaction)).catch((e) => this.emit("error", e));
+        };
+        if (interaction.isCommand() && interaction.commandName) {
+          run(this._commandHandlers.get(interaction.commandName));
+        } else if (interaction.isButton() && interaction.customId) {
+          run(this._buttonHandlers.get(interaction.customId));
+        } else if (interaction.isSelectMenu() && interaction.customId) {
+          run(this._selectHandlers.get(interaction.customId));
+        } else if (interaction.isModalSubmit() && interaction.customId) {
+          run(this._modalHandlers.get(interaction.customId));
+        }
+      });
+      this.socket.on("bot:event", (event) => {
+        this.emit("event", event);
+        switch (event.type) {
+          case "message.created":
+          case "message.edited": {
+            const raw = event.data;
+            const wrapped = new NovaMessage(raw, this.messages, this.reactions);
+            if (event.type === "message.created") this.emit("messageCreate", wrapped);
+            else this.emit("messageUpdate", wrapped);
+            break;
+          }
+          case "message.deleted":
+            this.emit("messageDelete", event.data);
+            break;
+          case "message.reaction_added":
+            this.emit("reactionAdd", event.data);
+            break;
+          case "message.reaction_removed":
+            this.emit("reactionRemove", event.data);
+            break;
+          case "user.joined_server":
+            this.emit("memberAdd", event.data);
+            break;
+          case "user.left_server":
+            this.emit("memberRemove", event.data);
+            break;
+          case "user.started_typing":
+            this.emit("typingStart", event.data);
+            break;
+          case "message.pinned":
+            this.emit("messagePinned", event.data);
+            break;
+          case "channel.created":
+            this.emit("channelCreate", event.data);
+            break;
+          case "channel.updated":
+            this.emit("channelUpdate", event.data);
+            break;
+          case "channel.deleted":
+            this.emit("channelDelete", event.data);
+            break;
+          case "role.created":
+            this.emit("roleCreate", event.data);
+            break;
+          case "role.deleted":
+            this.emit("roleDelete", event.data);
+            break;
+          case "user.voice_joined":
+            this.emit("voiceJoin", event.data);
+            break;
+          case "user.voice_left":
+            this.emit("voiceLeave", event.data);
+            break;
+          case "user.banned":
+            this.emit("memberBanned", event.data);
+            break;
+          case "user.unbanned":
+            this.emit("memberUnbanned", event.data);
+            break;
+          case "user.updated_profile":
+            this.emit("memberUpdate", event.data);
+            break;
+        }
+      });
+      this.socket.on("bot:error", (err) => {
+        this.emit("error", err);
+      });
+      this.socket.on("disconnect", (reason) => {
+        this.emit("disconnect", reason);
+      });
+    });
+  }
+  /**
+   * 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, fn) {
+    const id = setInterval(() => {
+      try {
+        const result = fn();
+        if (result && typeof result.catch === "function") {
+          ;
+          result.catch((e) => this.emit("error", e));
+        }
+      } catch (e) {
+        this.emit("error", e);
+      }
+    }, intervalMs);
+    this._cronTimers.push(id);
+    return () => {
+      clearInterval(id);
+      this._cronTimers = this._cronTimers.filter((t) => t !== id);
+    };
+  }
+  /**
+   * 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) {
+    this.socket?.emit("bot:status", { status });
+  }
+  // ─── Rich-wrapper helpers ────────────────────────────────────────────────────
+  /**
+   * Fetch a single channel and return it as a rich `NovaChannel` wrapper.
+   *
+   * @example
+   * const channel = await client.fetchChannel('channel-id')
+   * await channel.send('Hello!')
+   */
+  async fetchChannel(channelId) {
+    const raw = await this.channels.fetch(channelId);
+    return new NovaChannel(raw, this.channels, this.messages);
+  }
+  /**
+   * 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())
+   */
+  async fetchChannels(serverId) {
+    const list = await this.channels.list(serverId);
+    return list.map((raw) => new NovaChannel(raw, this.channels, this.messages));
+  }
+  /**
+   * 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)
+   */
+  async fetchMembers(serverId) {
+    const list = await this.members.list(serverId);
+    return list.map((raw) => new NovaMember(raw, serverId, this.members));
+  }
+  /**
+   * 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!')
+   */
+  async fetchMember(serverId, userId) {
+    const list = await this.members.list(serverId);
+    const raw = list.find((m) => m.user.id === userId);
+    if (!raw) throw new Error(`[nova-bot-sdk] Member ${userId} not found in server ${serverId}`);
+    return new NovaMember(raw, serverId, this.members);
+  }
+  // ─── Event fence ──────────────────────────────────────────────────────────────
+  /**
+   * 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(event, filter, timeoutMs = 3e4) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.off(event, handler);
+        reject(new Error(`[nova-bot-sdk] waitFor('${String(event)}') timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      const handler = (...args) => {
+        const arg = args[0];
+        if (!filter || filter(arg)) {
+          clearTimeout(timer);
+          this.off(event, handler);
+          resolve(arg);
+        }
+      };
+      this.on(event, handler);
+    });
+  }
+  /**
+   * Disconnect from the gateway and clean up.
+   */
+  disconnect() {
+    for (const id of this._cronTimers) clearInterval(id);
+    this._cronTimers = [];
+    if (this.socket) {
+      const sock = this.socket;
+      this.socket = null;
+      try {
+        sock.io.reconnection(false);
+      } catch {
+      }
+      try {
+        sock.io?.engine?.socket?.terminate?.();
+      } catch {
+      }
+      try {
+        sock.io?.engine?.socket?.destroy?.();
+      } catch {
+      }
+      try {
+        sock.io?.engine?.close?.();
+      } catch {
+      }
+      try {
+        sock.disconnect();
+      } catch {
+      }
+    }
+  }
+  /**
+   * 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, content) {
+    if (!this.socket?.connected) {
+      throw new Error("[nova-bot-sdk] Not connected. Call client.connect() first.");
+    }
+    this.socket.emit("bot:message:send", { channelId, content });
+  }
+  /**
+   * Start a typing indicator via WebSocket.
+   */
+  wsTypingStart(channelId) {
+    this.socket?.emit("bot:typing:start", { channelId });
+  }
+  /**
+   * Stop a typing indicator via WebSocket.
+   */
+  wsTypingStop(channelId) {
+    this.socket?.emit("bot:typing:stop", { channelId });
+  }
+  on(event, listener) {
+    return super.on(event, listener);
+  }
+  once(event, listener) {
+    return super.once(event, listener);
+  }
+  off(event, listener) {
+    return super.off(event, listener);
+  }
+  emit(event, ...args) {
+    return super.emit(event, ...args);
+  }
+};
+
+// src/builders/EmbedBuilder.ts
+var EmbedBuilder = class {
+  constructor() {
+    this._data = {};
+  }
+  /** Set the embed title (shown in bold at the top). */
+  setTitle(title) {
+    this._data.title = title;
+    return this;
+  }
+  /** Set the main description text (supports markdown). */
+  setDescription(description) {
+    this._data.description = description;
+    return this;
+  }
+  /**
+   * Set the accent colour.
+   * @param color Hex string — e.g. `'#5865F2'` or `'5865F2'`
+   */
+  setColor(color) {
+    this._data.color = color.startsWith("#") ? color : `#${color}`;
+    return this;
+  }
+  /** Make the title a clickable hyperlink. */
+  setUrl(url) {
+    this._data.url = url;
+    return this;
+  }
+  /** Small image shown in the top-right corner. */
+  setThumbnail(url) {
+    this._data.thumbnail = url;
+    return this;
+  }
+  /** Large image shown below the fields. */
+  setImage(url) {
+    this._data.image = url;
+    return this;
+  }
+  /** Footer text shown at the very bottom of the embed. */
+  setFooter(text) {
+    this._data.footer = text;
+    return this;
+  }
+  /**
+   * Add a timestamp to the footer line.
+   * @param date Defaults to `new Date()`.
+   */
+  setTimestamp(date) {
+    const d = date instanceof Date ? date : date != null ? new Date(date) : /* @__PURE__ */ new Date();
+    this._data.timestamp = d.toISOString();
+    return this;
+  }
+  /** Author name + optional icon shown above the title. */
+  setAuthor(author) {
+    this._data.author = author;
+    return this;
+  }
+  /**
+   * Add a single field.
+   * @param inline Pass `true` to render this field side-by-side with adjacent inline fields.
+   */
+  addField(name, value, inline) {
+    if (!this._data.fields) this._data.fields = [];
+    this._data.fields.push({ name, value, inline });
+    return this;
+  }
+  /** Add multiple fields at once. */
+  addFields(...fields) {
+    if (!this._data.fields) this._data.fields = [];
+    this._data.fields.push(...fields);
+    return this;
+  }
+  /** Replace all fields. */
+  setFields(fields) {
+    this._data.fields = [...fields];
+    return this;
+  }
+  /** Serialise to a plain `Embed` object you can pass to any API call. */
+  toJSON() {
+    return {
+      ...this._data,
+      fields: this._data.fields ? [...this._data.fields] : void 0
+    };
+  }
+};
+
+// src/builders/ButtonBuilder.ts
+var ButtonBuilder = class {
+  constructor() {
+    this._customId = "";
+    this._label = "";
+    this._style = "primary";
+    this._disabled = false;
+  }
+  /** Custom ID returned in the `BUTTON_CLICK` interaction. Not required for `link` style buttons. */
+  setCustomId(customId) {
+    this._customId = customId;
+    return this;
+  }
+  /** Text displayed on the button. */
+  setLabel(label) {
+    this._label = label;
+    return 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) {
+    this._style = style;
+    return this;
+  }
+  /** Emoji shown to the left of the label (unicode or custom e.g. `'👋'`). */
+  setEmoji(emoji) {
+    this._emoji = emoji;
+    return this;
+  }
+  /**
+   * URL for `link` style buttons.
+   * Sets the style to `'link'` automatically.
+   */
+  setUrl(url) {
+    this._url = url;
+    this._style = "link";
+    return this;
+  }
+  /** Prevent users from clicking the button. */
+  setDisabled(disabled = true) {
+    this._disabled = disabled;
+    return this;
+  }
+  toJSON() {
+    return {
+      type: "button",
+      customId: this._customId,
+      label: this._label || void 0,
+      style: this._style,
+      emoji: this._emoji,
+      url: this._url,
+      disabled: this._disabled || void 0
+    };
+  }
+};
+
+// src/builders/SelectMenuBuilder.ts
+var SelectMenuBuilder = class {
+  constructor() {
+    this._customId = "";
+    this._disabled = false;
+    this._options = [];
+  }
+  /** Custom ID returned in the `SELECT_MENU` interaction. */
+  setCustomId(customId) {
+    this._customId = customId;
+    return this;
+  }
+  /** Greyed-out hint shown when nothing is selected. */
+  setPlaceholder(placeholder) {
+    this._placeholder = placeholder;
+    return this;
+  }
   /** Prevent users from interacting with the menu. */
   setDisabled(disabled = true) {
     this._disabled = disabled;
     return this;
   }
-  /** Add a single option. */
+  /** Add a single option. */
+  addOption(option) {
+    this._options.push(option);
+    return this;
+  }
+  /** Add multiple options at once. */
+  addOptions(...options) {
+    this._options.push(...options);
+    return this;
+  }
+  /** Replace all options. */
+  setOptions(options) {
+    this._options.splice(0, this._options.length, ...options);
+    return this;
+  }
+  toJSON() {
+    return {
+      type: "select",
+      customId: this._customId,
+      placeholder: this._placeholder,
+      disabled: this._disabled || void 0,
+      options: [...this._options]
+    };
+  }
+};
+
+// src/builders/ActionRowBuilder.ts
+var ActionRowBuilder = class {
+  constructor() {
+    this._components = [];
+  }
+  /** Add a single component (button or select menu). */
+  addComponent(component) {
+    this._components.push(component);
+    return this;
+  }
+  /** Add multiple components at once. */
+  addComponents(...components) {
+    this._components.push(...components);
+    return this;
+  }
+  /**
+   * Serialise to a flat `MessageComponent[]` array — the format accepted by all API calls.
+   */
+  toJSON() {
+    return this._components.map((c) => c.toJSON());
+  }
+};
+
+// src/builders/ModalBuilder.ts
+var ModalBuilder = class {
+  constructor() {
+    this._title = "";
+    this._customId = "";
+    this._fields = [];
+  }
+  /** Title shown at the top of the modal dialog. */
+  setTitle(title) {
+    this._title = title;
+    return this;
+  }
+  /** Custom ID passed back with the `MODAL_SUBMIT` interaction. */
+  setCustomId(customId) {
+    this._customId = customId;
+    return this;
+  }
+  /** Add a single text-input field. */
+  addField(field) {
+    this._fields.push("toJSON" in field ? field.toJSON() : field);
+    return this;
+  }
+  /** Add multiple fields at once. */
+  addFields(...fields) {
+    for (const f of fields) this.addField(f);
+    return this;
+  }
+  toJSON() {
+    if (!this._title) throw new Error("ModalBuilder: title is required \u2014 call .setTitle()");
+    if (!this._customId) throw new Error("ModalBuilder: customId is required \u2014 call .setCustomId()");
+    if (this._fields.length === 0) throw new Error("ModalBuilder: at least one field is required \u2014 call .addField()");
+    return { title: this._title, customId: this._customId, fields: [...this._fields] };
+  }
+};
+
+// src/builders/TextInputBuilder.ts
+var TextInputBuilder = class {
+  constructor() {
+    this._data = {
+      customId: "",
+      label: "",
+      type: "short"
+    };
+  }
+  /** Unique ID for this field — the key in `interaction.modalData` on submit. */
+  setCustomId(customId) {
+    this._data.customId = customId;
+    return this;
+  }
+  /** Label shown above the input inside the modal. */
+  setLabel(label) {
+    this._data.label = label;
+    return this;
+  }
+  /**
+   * Input style:
+   * - `'short'` — single-line text input
+   * - `'paragraph'` — multi-line textarea
+   */
+  setStyle(style) {
+    this._data.type = style;
+    return this;
+  }
+  /** Greyed-out hint text shown when the field is empty. */
+  setPlaceholder(placeholder) {
+    this._data.placeholder = placeholder;
+    return this;
+  }
+  /** Whether the user must fill in this field before submitting. */
+  setRequired(required = true) {
+    this._data.required = required;
+    return this;
+  }
+  /** Minimum number of characters required. */
+  setMinLength(min) {
+    this._data.minLength = min;
+    return this;
+  }
+  /** Maximum number of characters allowed. */
+  setMaxLength(max) {
+    this._data.maxLength = max;
+    return this;
+  }
+  /** Pre-filled default value. */
+  setValue(value) {
+    this._data.value = value;
+    return this;
+  }
+  toJSON() {
+    return { ...this._data };
+  }
+};
+
+// src/builders/SlashCommandBuilder.ts
+var SlashCommandOptionBuilder = class {
+  constructor(type) {
+    this._data = { name: "", description: "", type };
+  }
+  /** Internal option name (lowercase, no spaces). Shown after `/command ` in the client UI. */
+  setName(name) {
+    this._data.name = name;
+    return this;
+  }
+  /** Short human-readable description shown in the command picker. */
+  setDescription(description) {
+    this._data.description = description;
+    return this;
+  }
+  /** Whether users must supply this option before sending the command. */
+  setRequired(required = true) {
+    this._data.required = required;
+    return this;
+  }
+  /**
+   * Restrict the option to specific values.
+   * The picker will show these as autocomplete suggestions.
+   */
+  addChoice(name, value) {
+    if (!this._data.choices) this._data.choices = [];
+    this._data.choices.push({ name, value });
+    return this;
+  }
+  /** Set all allowed choices at once. */
+  setChoices(choices) {
+    this._data.choices = [...choices];
+    return this;
+  }
+  toJSON() {
+    return { ...this._data };
+  }
+};
+var SlashCommandBuilder = class {
+  constructor() {
+    this._data = {
+      name: "",
+      description: "",
+      options: []
+    };
+  }
+  /** Command name — lowercase, no spaces (e.g. `'ban'`, `'server-info'`). */
+  setName(name) {
+    this._data.name = name;
+    return this;
+  }
+  /** Short description shown in the command picker UI. */
+  setDescription(description) {
+    this._data.description = description;
+    return this;
+  }
+  /** Add a text (string) option. */
+  addStringOption(fn) {
+    this._data.options.push(fn(new SlashCommandOptionBuilder("STRING")).toJSON());
+    return this;
+  }
+  /** Add an integer (whole number) option. */
+  addIntegerOption(fn) {
+    this._data.options.push(fn(new SlashCommandOptionBuilder("INTEGER")).toJSON());
+    return this;
+  }
+  /** Add a boolean (true/false) option. */
+  addBooleanOption(fn) {
+    this._data.options.push(fn(new SlashCommandOptionBuilder("BOOLEAN")).toJSON());
+    return this;
+  }
+  /** Add a user-mention option (returns a user ID string). */
+  addUserOption(fn) {
+    this._data.options.push(fn(new SlashCommandOptionBuilder("USER")).toJSON());
+    return this;
+  }
+  /** Add a channel-mention option (returns a channel ID string). */
+  addChannelOption(fn) {
+    this._data.options.push(fn(new SlashCommandOptionBuilder("CHANNEL")).toJSON());
+    return this;
+  }
+  /** Add a role-mention option (returns a role ID string). */
+  addRoleOption(fn) {
+    this._data.options.push(fn(new SlashCommandOptionBuilder("ROLE")).toJSON());
+    return this;
+  }
+  toJSON() {
+    if (!this._data.name) throw new Error("SlashCommandBuilder: name is required \u2014 call .setName()");
+    if (!this._data.description) throw new Error("SlashCommandBuilder: description is required \u2014 call .setDescription()");
+    return { ...this._data, options: [...this._data.options ?? []] };
+  }
+};
+
+// src/builders/PollBuilder.ts
+var PollBuilder = class {
+  constructor() {
+    this._question = "";
+    this._options = [];
+    this._allowMultiple = false;
+    this._duration = null;
+    this._anonymous = false;
+  }
+  /**
+   * Set the poll question.
+   *
+   * @example
+   * builder.setQuestion('Best programming language?')
+   */
+  setQuestion(question) {
+    this._question = question;
+    return this;
+  }
+  /**
+   * Add a single answer option.
+   *
+   * @example
+   * builder.addOption({ label: 'TypeScript', emoji: '🔷' })
+   */
   addOption(option) {
+    if (this._options.length >= 10) throw new Error("Polls can have at most 10 options");
     this._options.push(option);
     return this;
   }
-  /** Add multiple options at once. */
-  addOptions(...options) {
-    this._options.push(...options);
+  /**
+   * Add multiple answer options at once.
+   *
+   * @example
+   * builder.addOptions([
+   *   { label: 'Yes', emoji: '✅' },
+   *   { label: 'No', emoji: '❌' },
+   * ])
+   */
+  addOptions(options) {
+    for (const o of options) this.addOption(o);
     return this;
   }
-  /** Replace all options. */
-  setOptions(options) {
-    this._options.splice(0, this._options.length, ...options);
+  /**
+   * Allow users to select more than one option.
+   * Default: `false` (single choice).
+   */
+  setAllowMultiple(yes = true) {
+    this._allowMultiple = yes;
+    return 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) {
+    this._duration = seconds;
+    return this;
+  }
+  /**
+   * Hide which users voted for which option.
+   * Default: `false` (votes are public).
+   */
+  setAnonymous(yes = true) {
+    this._anonymous = yes;
     return this;
   }
+  /** Build the poll definition object. */
   toJSON() {
+    if (!this._question.trim()) throw new Error("PollBuilder: question is required");
+    if (this._options.length < 2) throw new Error("PollBuilder: at least 2 options are required");
     return {
-      type: "select",
-      customId: this._customId,
-      placeholder: this._placeholder,
-      disabled: this._disabled || void 0,
-      options: [...this._options]
+      question: this._question,
+      options: this._options,
+      allowMultiple: this._allowMultiple,
+      duration: this._duration,
+      anonymous: this._anonymous
     };
   }
 };
 
-// src/builders/ActionRowBuilder.ts
-var ActionRowBuilder = class {
+// src/builders/MessageBuilder.ts
+var MessageBuilder = class {
   constructor() {
     this._components = [];
   }
-  /** Add a single component (button or select menu). */
-  addComponent(component) {
-    this._components.push(component);
+  /**
+   * Set the text content of the message.
+   *
+   * @example
+   * builder.setContent('Hello world!')
+   */
+  setContent(content) {
+    this._content = content;
     return this;
   }
-  /** Add multiple components at once. */
-  addComponents(...components) {
+  /**
+   * 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) {
+    this._embed = "toJSON" in embed && typeof embed.toJSON === "function" ? embed.toJSON() : embed;
+    return this;
+  }
+  /**
+   * Remove any embed from this message.
+   */
+  clearEmbed() {
+    this._embed = void 0;
+    return this;
+  }
+  /**
+   * Add an `ActionRowBuilder` (or raw component array) as a component row.
+   *
+   * @example
+   * builder.addRow(
+   *   new ActionRowBuilder().addComponent(btn1).addComponent(btn2)
+   * )
+   */
+  addRow(row) {
+    const components = Array.isArray(row) ? row : row.toJSON();
     this._components.push(...components);
     return this;
   }
   /**
-   * Serialise to a flat `MessageComponent[]` array — the format accepted by all API calls.
+   * Replace all existing component rows.
+   */
+  setComponents(components) {
+    this._components = components;
+    return this;
+  }
+  /**
+   * Set the message this is replying to.
+   *
+   * @example
+   * builder.setReplyTo(message.id)
+   */
+  setReplyTo(messageId) {
+    this._replyToId = messageId;
+    return 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) {
+    this._poll = "toJSON" in poll && typeof poll.toJSON === "function" ? poll.toJSON() : poll;
+    return this;
+  }
+  /**
+   * Build the message options object, ready to pass to `client.messages.send()`.
+   *
+   * @throws if neither `content` nor `embed` nor `poll` is set.
+   */
+  toJSON() {
+    if (!this._content && !this._embed && !this._poll) {
+      throw new Error("MessageBuilder: message must have content, an embed, or a poll");
+    }
+    return {
+      ...this._content !== void 0 ? { content: this._content } : {},
+      ...this._embed !== void 0 ? { embed: this._embed } : {},
+      ...this._components.length > 0 ? { components: this._components } : {},
+      ...this._replyToId !== void 0 ? { replyToId: this._replyToId } : {},
+      ...this._poll !== void 0 ? { poll: this._poll } : {}
+    };
+  }
+};
+
+// src/utils/Collection.ts
+var Collection = class _Collection extends Map {
+  /**
+   * The first value stored (insertion order), or `undefined` if empty.
+   */
+  first() {
+    return this.values().next().value;
+  }
+  /**
+   * The first `n` values stored (insertion order).
+   */
+  firstN(n) {
+    const result = [];
+    for (const v of this.values()) {
+      if (result.length >= n) break;
+      result.push(v);
+    }
+    return result;
+  }
+  /**
+   * The last value stored, or `undefined` if empty.
+   */
+  last() {
+    let last;
+    for (const v of this.values()) last = v;
+    return last;
+  }
+  /**
+   * The last `n` values stored (insertion order).
+   */
+  lastN(n) {
+    return this.toArray().slice(-n);
+  }
+  /**
+   * Returns a random value from the collection, or `undefined` if empty.
+   */
+  random() {
+    const arr = this.toArray();
+    return arr[Math.floor(Math.random() * arr.length)];
+  }
+  /**
+   * Find the first value that passes the predicate.
+   *
+   * @example
+   * const bot = members.find(m => m.user.isBot)
+   */
+  find(fn) {
+    for (const [k, v] of this) {
+      if (fn(v, k, this)) return v;
+    }
+    return void 0;
+  }
+  /**
+   * Find the key of the first value that passes the predicate.
+   */
+  findKey(fn) {
+    for (const [k, v] of this) {
+      if (fn(v, k, this)) return k;
+    }
+    return void 0;
+  }
+  /**
+   * Returns `true` if at least one value satisfies the predicate.
+   */
+  some(fn) {
+    for (const [k, v] of this) {
+      if (fn(v, k, this)) return true;
+    }
+    return false;
+  }
+  /**
+   * Returns `true` if every value satisfies the predicate.
+   */
+  every(fn) {
+    for (const [k, v] of this) {
+      if (!fn(v, k, this)) return false;
+    }
+    return true;
+  }
+  /**
+   * Filter to a new Collection containing only values that pass the predicate.
+   *
+   * @example
+   * const admins = members.filter(m => m.role === 'ADMIN')
+   */
+  filter(fn) {
+    const result = new _Collection();
+    for (const [k, v] of this) {
+      if (fn(v, k, this)) result.set(k, v);
+    }
+    return result;
+  }
+  /**
+   * Map each value to a new array.
+   *
+   * @example
+   * const names = members.map(m => m.user.username)
+   */
+  map(fn) {
+    const result = [];
+    for (const [k, v] of this) result.push(fn(v, k, this));
+    return result;
+  }
+  /**
+   * Map to a new Collection with transformed values.
+   *
+   * @example
+   * const names = channels.mapValues(c => c.name.toUpperCase())
+   */
+  mapValues(fn) {
+    const result = new _Collection();
+    for (const [k, v] of this) result.set(k, fn(v, k, this));
+    return result;
+  }
+  /**
+   * Reduce the collection to a single value.
+   *
+   * @example
+   * const totalReactions = messages.reduce((sum, m) => sum + m.reactions.length, 0)
+   */
+  reduce(fn, initial) {
+    let acc = initial;
+    for (const [k, v] of this) acc = fn(acc, v, k, this);
+    return acc;
+  }
+  /**
+   * Returns values as an array (insertion order).
+   */
+  toArray() {
+    return [...this.values()];
+  }
+  /**
+   * Returns keys as an array (insertion order).
+   */
+  keyArray() {
+    return [...this.keys()];
+  }
+  /**
+   * 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) {
+    const entries = [...this.entries()].sort(
+      ([ak, av], [bk, bv]) => fn ? fn(av, bv, ak, bk) : 0
+    );
+    return new _Collection(entries);
+  }
+  /**
+   * Split into two Collections based on a predicate.
+   * Returns `[passing, failing]`.
+   *
+   * @example
+   * const [bots, humans] = members.partition(m => m.user.isBot)
+   */
+  partition(fn) {
+    const pass = new _Collection();
+    const fail = new _Collection();
+    for (const [k, v] of this) {
+      if (fn(v, k, this)) pass.set(k, v);
+      else fail.set(k, v);
+    }
+    return [pass, fail];
+  }
+  /**
+   * Merge this collection with one or more others.
+   * Later collections overwrite duplicate keys.
+   */
+  merge(...others) {
+    const result = new _Collection(this);
+    for (const other of others) {
+      for (const [k, v] of other) result.set(k, v);
+    }
+    return result;
+  }
+  /**
+   * Serialize to a plain `Record` (requires string keys).
+   */
+  toJSON() {
+    const obj = {};
+    for (const [k, v] of this) obj[String(k)] = v;
+    return obj;
+  }
+  toString() {
+    return `Collection(${this.size})`;
+  }
+};
+
+// src/utils/Cooldown.ts
+var Cooldown = class {
+  /**
+   * @param durationMs - Default cooldown duration in milliseconds.
+   */
+  constructor(durationMs) {
+    this._durations = /* @__PURE__ */ new Map();
+    this._last = /* @__PURE__ */ new Map();
+    this._defaultMs = durationMs;
+  }
+  /**
+   * 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) {
+    const last = this._last.get(userId);
+    if (last === void 0) return 0;
+    const duration = this._durations.get(userId) ?? this._defaultMs;
+    const remaining = duration - (Date.now() - last);
+    return remaining > 0 ? remaining : 0;
+  }
+  /**
+   * 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, durationMs) {
+    this._last.set(userId, Date.now());
+    if (durationMs !== void 0) this._durations.set(userId, durationMs);
+  }
+  /**
+   * Immediately reset (clear) the cooldown for a user.
+   *
+   * @example
+   * cooldown.reset(userId) // user can use the command again immediately
+   */
+  reset(userId) {
+    this._last.delete(userId);
+    this._durations.delete(userId);
+  }
+  /**
+   * Reset all active cooldowns.
+   */
+  resetAll() {
+    this._last.clear();
+    this._durations.clear();
+  }
+  /**
+   * Returns a list of all users currently on cooldown.
+   *
+   * @example
+   * const active = cooldown.activeCooldowns()
+   * // [{ userId: 'abc', remainingMs: 3200 }, ...]
+   */
+  activeCooldowns() {
+    const result = [];
+    for (const [userId] of this._last) {
+      const ms = this.check(userId);
+      if (ms > 0) result.push({ userId, remainingMs: ms });
+    }
+    return result;
+  }
+  /**
+   * 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'
    */
-  toJSON() {
-    return this._components.map((c) => c.toJSON());
+  static format(ms) {
+    const totalSecs = Math.ceil(ms / 1e3);
+    const hours = Math.floor(totalSecs / 3600);
+    const mins = Math.floor(totalSecs % 3600 / 60);
+    const secs = totalSecs % 60;
+    if (hours > 0) return `${hours}h ${mins}m ${secs}s`;
+    if (mins > 0) return `${mins}m ${secs}s`;
+    return `${secs}s`;
   }
 };
-
-// src/builders/ModalBuilder.ts
-var ModalBuilder = class {
+var CooldownManager = class {
   constructor() {
-    this._title = "";
-    this._customId = "";
-    this._fields = [];
+    this._map = /* @__PURE__ */ new Map();
   }
-  /** Title shown at the top of the modal dialog. */
-  setTitle(title) {
-    this._title = title;
-    return this;
+  /**
+   * Get or create a named cooldown.
+   */
+  get(name, durationMs = 3e3) {
+    if (!this._map.has(name)) this._map.set(name, new Cooldown(durationMs));
+    return this._map.get(name);
   }
-  /** Custom ID passed back with the `MODAL_SUBMIT` interaction. */
-  setCustomId(customId) {
-    this._customId = customId;
-    return this;
+  /**
+   * 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, userId, durationMs = 3e3) {
+    return this.get(name, durationMs).check(userId);
   }
-  /** Add a single text-input field. */
-  addField(field) {
-    this._fields.push("toJSON" in field ? field.toJSON() : field);
-    return this;
+  /**
+   * Mark a user as having used a named command.
+   *
+   * @example
+   * cooldowns.use('ban', userId, 30_000)
+   */
+  use(name, userId, durationMs) {
+    this.get(name, durationMs).use(userId, durationMs);
   }
-  /** Add multiple fields at once. */
-  addFields(...fields) {
-    for (const f of fields) this.addField(f);
-    return this;
+  /**
+   * Reset a user's cooldown on a named command.
+   */
+  reset(name, userId) {
+    this._map.get(name)?.reset(userId);
   }
-  toJSON() {
-    if (!this._title) throw new Error("ModalBuilder: title is required \u2014 call .setTitle()");
-    if (!this._customId) throw new Error("ModalBuilder: customId is required \u2014 call .setCustomId()");
-    if (this._fields.length === 0) throw new Error("ModalBuilder: at least one field is required \u2014 call .addField()");
-    return { title: this._title, customId: this._customId, fields: [...this._fields] };
+  /**
+   * Reset all cooldowns for all commands.
+   */
+  resetAll() {
+    for (const c of this._map.values()) c.resetAll();
   }
 };
 
-// src/builders/TextInputBuilder.ts
-var TextInputBuilder = class {
-  constructor() {
-    this._data = {
-      customId: "",
-      label: "",
-      type: "short"
-    };
+// src/utils/Logger.ts
+var Logger = class {
+  /**
+   * @param name       - Name shown in square brackets before every message.
+   * @param enableDebug - When `false` (default), `.debug()` calls are silent.
+   */
+  constructor(name, enableDebug = false) {
+    this._prefix = name;
+    this._debug = enableDebug;
   }
-  /** Unique ID for this field — the key in `interaction.modalData` on submit. */
-  setCustomId(customId) {
-    this._data.customId = customId;
+  /** Enable or disable debug output at runtime. */
+  setDebug(enabled) {
+    this._debug = enabled;
     return this;
   }
-  /** Label shown above the input inside the modal. */
-  setLabel(label) {
-    this._data.label = label;
-    return this;
+  _timestamp() {
+    return (/* @__PURE__ */ new Date()).toISOString().replace("T", " ").slice(0, 19);
   }
-  /**
-   * Input style:
-   * - `'short'` — single-line text input
-   * - `'paragraph'` — multi-line textarea
-   */
-  setStyle(style) {
-    this._data.type = style;
-    return this;
+  _fmt(level, color, ...args) {
+    const ts = this._timestamp();
+    const tag = `\x1B[90m${ts}\x1B[0m ${color}[${level}]\x1B[0m \x1B[36m[${this._prefix}]\x1B[0m`;
+    return `${tag} ${args.map((a) => typeof a === "object" ? JSON.stringify(a, null, 2) : String(a)).join(" ")}`;
   }
-  /** Greyed-out hint text shown when the field is empty. */
-  setPlaceholder(placeholder) {
-    this._data.placeholder = placeholder;
-    return this;
+  /** General info message. */
+  info(...args) {
+    console.log(this._fmt("INFO ", "\x1B[34m", ...args));
   }
-  /** Whether the user must fill in this field before submitting. */
-  setRequired(required = true) {
-    this._data.required = required;
-    return this;
+  /** Warning — something unexpected but non-fatal. */
+  warn(...args) {
+    console.warn(this._fmt("WARN ", "\x1B[33m", ...args));
   }
-  /** Minimum number of characters required. */
-  setMinLength(min) {
-    this._data.minLength = min;
-    return this;
+  /** Error — something went wrong. */
+  error(...args) {
+    console.error(this._fmt("ERROR", "\x1B[31m", ...args));
   }
-  /** Maximum number of characters allowed. */
-  setMaxLength(max) {
-    this._data.maxLength = max;
-    return this;
+  /** Success / positive confirmation. */
+  success(...args) {
+    console.log(this._fmt("OK   ", "\x1B[32m", ...args));
   }
-  /** Pre-filled default value. */
-  setValue(value) {
-    this._data.value = value;
-    return this;
+  /** Debug — only printed when `enableDebug` is true. */
+  debug(...args) {
+    if (this._debug) console.log(this._fmt("DEBUG", "\x1B[35m", ...args));
   }
-  toJSON() {
-    return { ...this._data };
+  /**
+   * Log an incoming command interaction.
+   *
+   * @example
+   * log.command('ping', interaction.userId)
+   * // [MyBot] [CMD] /ping ← user:abc123
+   */
+  command(name, userId) {
+    console.log(this._fmt("CMD  ", "\x1B[36m", `/${name} \x1B[90m\u2190 user:${userId}`));
+  }
+  /**
+   * Log a gateway event.
+   *
+   * @example
+   * log.event('messageCreate')
+   */
+  event(type, extra = "") {
+    console.log(this._fmt("EVT  ", "\x1B[35m", type + (extra ? ` \x1B[90m${extra}` : "")));
+  }
+  /**
+   * Log that a command handler threw an error.
+   *
+   * @example
+   * log.commandError('ban', err)
+   */
+  commandError(name, err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(this._fmt("ERROR", "\x1B[31m", `${name} threw: ${msg}`));
+    if (err instanceof Error && err.stack) {
+      console.error("\x1B[90m" + err.stack + "\x1B[0m");
+    }
   }
 };
 
-// src/builders/SlashCommandBuilder.ts
-var SlashCommandOptionBuilder = class {
-  constructor(type) {
-    this._data = { name: "", description: "", type };
-  }
-  /** Internal option name (lowercase, no spaces). Shown after `/command ` in the client UI. */
-  setName(name) {
-    this._data.name = name;
-    return this;
+// src/utils/Paginator.ts
+var Paginator = class {
+  constructor(fetchFn) {
+    this.fetchFn = fetchFn;
+    this._cursor = null;
+    this._done = false;
+    this._totalFetched = 0;
+  }
+  /** Whether all pages have been consumed. */
+  get done() {
+    return this._done;
+  }
+  /** Total number of items fetched so far (across all pages). */
+  get totalFetched() {
+    return this._totalFetched;
   }
-  /** Short human-readable description shown in the command picker. */
-  setDescription(description) {
-    this._data.description = description;
-    return this;
+  /**
+   * 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()
+   */
+  async fetchPage() {
+    if (this._done) return [];
+    const { items, cursor } = await this.fetchFn(this._cursor);
+    this._totalFetched += items.length;
+    this._cursor = cursor;
+    if (!cursor || items.length === 0) this._done = true;
+    return items;
   }
-  /** Whether users must supply this option before sending the command. */
-  setRequired(required = true) {
-    this._data.required = required;
-    return this;
+  /**
+   * Fetch **all** remaining pages and return a flat array.
+   *
+   * ⚠️ Use with caution on very large collections.
+   *
+   * @example
+   * const allMembers = await paginator.fetchAll()
+   */
+  async fetchAll() {
+    const all = [];
+    while (!this._done) {
+      const page = await this.fetchPage();
+      all.push(...page);
+    }
+    return all;
   }
   /**
-   * Restrict the option to specific values.
-   * The picker will show these as autocomplete suggestions.
+   * Fetch up to `n` items total (across however many pages are needed).
+   *
+   * @example
+   * const first100 = await paginator.fetchN(100)
    */
-  addChoice(name, value) {
-    if (!this._data.choices) this._data.choices = [];
-    this._data.choices.push({ name, value });
-    return this;
+  async fetchN(n) {
+    const result = [];
+    while (!this._done && result.length < n) {
+      const page = await this.fetchPage();
+      result.push(...page.slice(0, n - result.length));
+    }
+    return result;
   }
-  /** Set all allowed choices at once. */
-  setChoices(choices) {
-    this._data.choices = [...choices];
-    return this;
+  /**
+   * Async-iterate over every item, one page at a time.
+   *
+   * @example
+   * for await (const msg of paginator) {
+   *   process(msg)
+   * }
+   */
+  async *[Symbol.asyncIterator]() {
+    while (!this._done) {
+      const page = await this.fetchPage();
+      for (const item of page) yield item;
+    }
   }
-  toJSON() {
-    return { ...this._data };
+  /**
+   * Reset the paginator so you can iterate from the beginning again.
+   *
+   * @example
+   * await paginator.fetchAll()
+   * paginator.reset()
+   * const againFirst = await paginator.fetchPage()
+   */
+  reset() {
+    this._cursor = null;
+    this._done = false;
+    this._totalFetched = 0;
   }
 };
-var SlashCommandBuilder = class {
-  constructor() {
-    this._data = {
-      name: "",
-      description: "",
-      options: []
-    };
+
+// src/utils/PermissionsBitfield.ts
+var Permissions = {
+  /** Read messages in channels. */
+  MESSAGES_READ: "messages.read",
+  /** Send messages in channels. */
+  MESSAGES_WRITE: "messages.write",
+  /** Edit / delete any message (not just the bot's own). */
+  MESSAGES_MANAGE: "messages.manage",
+  /** Create, edit and delete channels. */
+  CHANNELS_MANAGE: "channels.manage",
+  /** Kick members from the server. */
+  MEMBERS_KICK: "members.kick",
+  /** Ban and unban members from the server. */
+  MEMBERS_BAN: "members.ban",
+  /** Assign and remove roles on members. */
+  MEMBERS_ROLES: "members.roles",
+  /** Edit server settings. */
+  SERVERS_MANAGE: "servers.manage"
+};
+var _PermissionsBitfield = class _PermissionsBitfield {
+  constructor(perms = {}) {
+    this._perms = { ...perms };
   }
-  /** Command name — lowercase, no spaces (e.g. `'ban'`, `'server-info'`). */
-  setName(name) {
-    this._data.name = name;
-    return this;
+  // ─── Checking ──────────────────────────────────────────────────────────────
+  /**
+   * 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) {
+    return this._perms[permission] === true;
   }
-  /** Short description shown in the command picker UI. */
-  setDescription(description) {
-    this._data.description = description;
-    return this;
+  /**
+   * Returns `true` if **all** listed permissions are granted.
+   *
+   * @example
+   * perms.hasAll('messages.read', 'messages.write') // true
+   */
+  hasAll(...permissions) {
+    return permissions.every((p) => this.has(p));
   }
-  /** Add a text (string) option. */
-  addStringOption(fn) {
-    this._data.options.push(fn(new SlashCommandOptionBuilder("STRING")).toJSON());
-    return this;
+  /**
+   * 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) {
+    return permissions.some((p) => this.has(p));
   }
-  /** Add an integer (whole number) option. */
-  addIntegerOption(fn) {
-    this._data.options.push(fn(new SlashCommandOptionBuilder("INTEGER")).toJSON());
-    return this;
+  /**
+   * 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) {
+    return permissions.filter((p) => !this.has(p));
   }
-  /** Add a boolean (true/false) option. */
-  addBooleanOption(fn) {
-    this._data.options.push(fn(new SlashCommandOptionBuilder("BOOLEAN")).toJSON());
-    return this;
+  // ─── Building ──────────────────────────────────────────────────────────────
+  /**
+   * Return a **new** `PermissionsBitfield` with the given permission granted.
+   *
+   * @example
+   * const updated = perms.grant('channels.manage')
+   */
+  grant(...permissions) {
+    const next = { ...this._perms };
+    for (const p of permissions) next[p] = true;
+    return new _PermissionsBitfield(next);
   }
-  /** Add a user-mention option (returns a user ID string). */
-  addUserOption(fn) {
-    this._data.options.push(fn(new SlashCommandOptionBuilder("USER")).toJSON());
-    return this;
+  /**
+   * Return a **new** `PermissionsBitfield` with the given permission denied.
+   *
+   * @example
+   * const restricted = perms.deny('members.kick')
+   */
+  deny(...permissions) {
+    const next = { ...this._perms };
+    for (const p of permissions) next[p] = false;
+    return new _PermissionsBitfield(next);
   }
-  /** Add a channel-mention option (returns a channel ID string). */
-  addChannelOption(fn) {
-    this._data.options.push(fn(new SlashCommandOptionBuilder("CHANNEL")).toJSON());
-    return this;
+  /**
+   * 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) {
+    const otherRecord = other instanceof _PermissionsBitfield ? other.toRecord() : other;
+    return new _PermissionsBitfield({ ...this._perms, ...otherRecord });
   }
-  /** Add a role-mention option (returns a role ID string). */
-  addRoleOption(fn) {
-    this._data.options.push(fn(new SlashCommandOptionBuilder("ROLE")).toJSON());
-    return this;
+  // ─── Inspection ────────────────────────────────────────────────────────────
+  /**
+   * Returns an array of the permission keys that are **currently granted**.
+   *
+   * @example
+   * perms.toArray() // ['messages.read', 'messages.write']
+   */
+  toArray() {
+    return Object.entries(this._perms).filter(([, v]) => v).map(([k]) => k);
   }
-  toJSON() {
-    if (!this._data.name) throw new Error("SlashCommandBuilder: name is required \u2014 call .setName()");
-    if (!this._data.description) throw new Error("SlashCommandBuilder: description is required \u2014 call .setDescription()");
-    return { ...this._data, options: [...this._data.options ?? []] };
+  /**
+   * Returns the raw `Record<string, boolean>` map.
+   */
+  toRecord() {
+    return { ...this._perms };
+  }
+  /**
+   * Pretty-print the granted permissions.
+   *
+   * @example
+   * console.log(String(perms)) // 'PermissionsBitfield[messages.read, messages.write]'
+   */
+  toString() {
+    const granted = this.toArray();
+    return granted.length > 0 ? `PermissionsBitfield[${granted.join(", ")}]` : "PermissionsBitfield[none]";
+  }
+  // ─── Static helpers ─────────────────────────────────────────────────────────
+  /** Create a `PermissionsBitfield` from an existing record. */
+  static from(perms) {
+    return new _PermissionsBitfield(perms);
   }
 };
+/** A `PermissionsBitfield` with all known permissions granted. */
+_PermissionsBitfield.ALL = new _PermissionsBitfield({
+  [Permissions.MESSAGES_READ]: true,
+  [Permissions.MESSAGES_WRITE]: true,
+  [Permissions.MESSAGES_MANAGE]: true,
+  [Permissions.CHANNELS_MANAGE]: true,
+  [Permissions.MEMBERS_KICK]: true,
+  [Permissions.MEMBERS_BAN]: true,
+  [Permissions.MEMBERS_ROLES]: true,
+  [Permissions.SERVERS_MANAGE]: true
+});
+/** A `PermissionsBitfield` with no permissions granted. */
+_PermissionsBitfield.NONE = new _PermissionsBitfield({});
+var PermissionsBitfield = _PermissionsBitfield;
+
+// src/utils/time.ts
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function withTimeout(promise, ms, message) {
+  return new Promise((resolve, reject) => {
+    const id = setTimeout(() => {
+      reject(new Error(message ?? `[nova-bot-sdk] Operation timed out after ${ms}ms`));
+    }, ms);
+    promise.then(
+      (v) => {
+        clearTimeout(id);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(id);
+        reject(e);
+      }
+    );
+  });
+}
+var SECOND = 1e3;
+var MINUTE = 60 * SECOND;
+var HOUR = 60 * MINUTE;
+var DAY = 24 * HOUR;
+var WEEK = 7 * DAY;
+function formatDuration(ms) {
+  if (ms < SECOND) return "0s";
+  const weeks = Math.floor(ms / WEEK);
+  const days = Math.floor(ms % WEEK / DAY);
+  const hours = Math.floor(ms % DAY / HOUR);
+  const minutes = Math.floor(ms % HOUR / MINUTE);
+  const seconds = Math.floor(ms % MINUTE / SECOND);
+  const parts = [];
+  if (weeks) parts.push(`${weeks}w`);
+  if (days) parts.push(`${days}d`);
+  if (hours) parts.push(`${hours}h`);
+  if (minutes) parts.push(`${minutes}m`);
+  if (seconds) parts.push(`${seconds}s`);
+  return parts.join(" ");
+}
+function formatRelative(timestamp) {
+  const ts = timestamp instanceof Date ? timestamp.getTime() : typeof timestamp === "string" ? new Date(timestamp).getTime() : timestamp;
+  const diff = Date.now() - ts;
+  const abs = Math.abs(diff);
+  const past = diff > 0;
+  const fmt = (n, unit) => past ? `${n} ${unit}${n !== 1 ? "s" : ""} ago` : `in ${n} ${unit}${n !== 1 ? "s" : ""}`;
+  if (abs < 5e3) return "just now";
+  if (abs < MINUTE) return fmt(Math.round(abs / SECOND), "second");
+  if (abs < 2 * MINUTE) return past ? "a minute ago" : "in a minute";
+  if (abs < HOUR) return fmt(Math.round(abs / MINUTE), "minute");
+  if (abs < 2 * HOUR) return past ? "an hour ago" : "in an hour";
+  if (abs < DAY) return fmt(Math.round(abs / HOUR), "hour");
+  if (abs < 2 * DAY) return past ? "yesterday" : "tomorrow";
+  if (abs < WEEK) return fmt(Math.round(abs / DAY), "day");
+  if (abs < 4 * WEEK) return fmt(Math.round(abs / WEEK), "week");
+  return new Date(ts).toLocaleDateString(void 0, { year: "numeric", month: "short", day: "numeric" });
+}
+function parseTimestamp(value) {
+  if (value == null) return null;
+  if (value instanceof Date) return isNaN(value.getTime()) ? null : value;
+  const d = new Date(value);
+  return isNaN(d.getTime()) ? null : d;
+}
+function countdown(target) {
+  const targetMs = target instanceof Date ? target.getTime() : typeof target === "string" ? new Date(target).getTime() : target;
+  const total = Math.max(0, targetMs - Date.now());
+  return {
+    total,
+    weeks: Math.floor(total / WEEK),
+    days: Math.floor(total % WEEK / DAY),
+    hours: Math.floor(total % DAY / HOUR),
+    minutes: Math.floor(total % HOUR / MINUTE),
+    seconds: Math.floor(total % MINUTE / SECOND)
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ActionRowBuilder,
   ButtonBuilder,
+  ChannelsAPI,
+  Collection,
   CommandsAPI,
+  Cooldown,
+  CooldownManager,
   EmbedBuilder,
   HttpClient,
   InteractionOptions,
   InteractionsAPI,
+  Logger,
   MembersAPI,
+  MessageBuilder,
   MessagesAPI,
   ModalBuilder,
+  NovaChannel,
   NovaClient,
   NovaInteraction,
+  NovaMember,
+  NovaMessage,
+  Paginator,
+  Permissions,
   PermissionsAPI,
+  PermissionsBitfield,
+  PollBuilder,
+  ReactionsAPI,
   SelectMenuBuilder,
   ServersAPI,
   SlashCommandBuilder,
   SlashCommandOptionBuilder,
-  TextInputBuilder
+  TextInputBuilder,
+  countdown,
+  formatDuration,
+  formatRelative,
+  parseTimestamp,
+  sleep,
+  withTimeout
 });