novaapp-sdk 1.1.0 → 1.2.0

package/dist/index.js

@@ -22,17 +22,26 @@ 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,
   NovaClient: () => NovaClient,
   NovaInteraction: () => NovaInteraction,
+  NovaMessage: () => NovaMessage,
   PermissionsAPI: () => PermissionsAPI,
+  PollBuilder: () => PollBuilder,
+  ReactionsAPI: () => ReactionsAPI,
   SelectMenuBuilder: () => SelectMenuBuilder,
   ServersAPI: () => ServersAPI,
   SlashCommandBuilder: () => SlashCommandBuilder,
@@ -135,6 +144,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 +335,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 +407,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 +584,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,23 +929,159 @@ 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"
+// 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);
+  }
+  /**
+   * Remove the bot's reaction from this message.
+   *
+   * @example
+   * await msg.removeReaction('👍')
+   */
+  removeReaction(emoji) {
+    return this._reactions.remove(this.id, emoji);
+  }
+  // ─── Messaging ────────────────────────────────────────────────────────────────
+  /**
+   * Reply to this message.
+   *
+   * @example
+   * await msg.reply('Got it!')
+   * await msg.reply({ embed: new EmbedBuilder().setTitle('Result').toJSON() })
+   */
+  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));
+  }
+  /**
+   * Edit this message.
+   * Only works if the bot is the author.
+   *
+   * @example
+   * await msg.edit('Updated content')
+   * await msg.edit({ content: 'Updated', embed: { title: 'New embed' } })
+   */
+  edit(options) {
+    const opts = typeof options === "string" ? { content: options } : options;
+    return this._messages.edit(this.id, opts).then((raw) => new _NovaMessage(raw, this._messages, this._reactions));
+  }
+  /**
+   * Delete this message.
+   * Only works if the bot is the author.
+   *
+   * @example
+   * await msg.delete()
+   */
+  delete() {
+    return this._messages.delete(this.id);
+  }
+  /**
+   * Pin this message in its channel.
+   *
+   * @example
+   * await msg.pin()
+   */
+  pin() {
+    return this._messages.pin(this.id);
+  }
+  /**
+   * Unpin this message.
+   *
+   * @example
+   * await msg.unpin()
+   */
+  unpin() {
+    return this._messages.unpin(this.id);
+  }
+  /**
+   * Re-fetch the latest version of this message from the server.
+   *
+   * @example
+   * const fresh = await msg.fetch()
+   */
+  async fetch() {
+    const raw = await this._messages.fetchOne(this.id);
+    return new _NovaMessage(raw, this._messages, this._reactions);
+  }
+  /**
+   * Get a URL to this message (deep link).
+   */
+  get url() {
+    return `/channels/${this.channelId}/messages/${this.id}`;
+  }
+  /**
+   * 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
+    };
+  }
+  toString() {
+    return `NovaMessage(${this.id}): ${this.content.slice(0, 50)}${this.content.length > 50 ? "\u2026" : ""}`;
+  }
 };
+
+// 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();
@@ -662,6 +1103,8 @@ var NovaClient = class extends import_node_events.EventEmitter {
     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();
@@ -766,9 +1209,36 @@ var NovaClient = class extends import_node_events.EventEmitter {
       });
       this.socket.on("bot:event", (event) => {
         this.emit("event", event);
-        const shorthand = EVENT_MAP[event.type];
-        if (shorthand) {
-          this.emit(shorthand, event.data);
+        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;
         }
       });
       this.socket.on("bot:error", (err) => {
@@ -779,10 +1249,58 @@ var NovaClient = class extends import_node_events.EventEmitter {
       });
     });
   }
+  /**
+   * 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 });
+  }
   /**
    * 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;
@@ -1251,21 +1769,611 @@ var SlashCommandBuilder = class {
     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 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;
+  }
+  /**
+   * 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 {
+      question: this._question,
+      options: this._options,
+      allowMultiple: this._allowMultiple,
+      duration: this._duration,
+      anonymous: this._anonymous
+    };
+  }
+};
+
+// src/builders/MessageBuilder.ts
+var MessageBuilder = class {
+  constructor() {
+    this._components = [];
+  }
+  /**
+   * Set the text content of the message.
+   *
+   * @example
+   * builder.setContent('Hello world!')
+   */
+  setContent(content) {
+    this._content = content;
+    return 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) {
+    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;
+  }
+  /**
+   * 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'
+   */
+  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`;
+  }
+};
+var CooldownManager = class {
+  constructor() {
+    this._map = /* @__PURE__ */ new Map();
+  }
+  /**
+   * 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);
+  }
+  /**
+   * 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);
+  }
+  /**
+   * 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);
+  }
+  /**
+   * Reset a user's cooldown on a named command.
+   */
+  reset(name, userId) {
+    this._map.get(name)?.reset(userId);
+  }
+  /**
+   * Reset all cooldowns for all commands.
+   */
+  resetAll() {
+    for (const c of this._map.values()) c.resetAll();
+  }
+};
+
+// 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;
+  }
+  /** Enable or disable debug output at runtime. */
+  setDebug(enabled) {
+    this._debug = enabled;
+    return this;
+  }
+  _timestamp() {
+    return (/* @__PURE__ */ new Date()).toISOString().replace("T", " ").slice(0, 19);
+  }
+  _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(" ")}`;
+  }
+  /** General info message. */
+  info(...args) {
+    console.log(this._fmt("INFO ", "\x1B[34m", ...args));
+  }
+  /** Warning — something unexpected but non-fatal. */
+  warn(...args) {
+    console.warn(this._fmt("WARN ", "\x1B[33m", ...args));
+  }
+  /** Error — something went wrong. */
+  error(...args) {
+    console.error(this._fmt("ERROR", "\x1B[31m", ...args));
+  }
+  /** Success / positive confirmation. */
+  success(...args) {
+    console.log(this._fmt("OK   ", "\x1B[32m", ...args));
+  }
+  /** Debug — only printed when `enableDebug` is true. */
+  debug(...args) {
+    if (this._debug) console.log(this._fmt("DEBUG", "\x1B[35m", ...args));
+  }
+  /**
+   * 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");
+    }
+  }
+};
 // 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,
   NovaClient,
   NovaInteraction,
+  NovaMessage,
   PermissionsAPI,
+  PollBuilder,
+  ReactionsAPI,
   SelectMenuBuilder,
   ServersAPI,
   SlashCommandBuilder,