beniocord.js 2.1.0 → 2.1.1

package/Client.js

@@ -10,6 +10,7 @@ const User = require("./structures/User");
 const Channel = require("./structures/Channel");
 const Emoji = require("./structures/Emoji");
 const { MessageEmbed, MessageAttachment } = require("./structures/Util");
+const { formatUrl } = require("./helpers");
 
 let global = {
   token: "",
@@ -18,6 +19,23 @@ let global = {
 
 class Client extends EventEmitter {
   /**
+   * @typedef {Object} ClientEvents
+   * @property {User} ready - Fired when the client finishes connecting
+   * @property {Message} messageCreate - Fired when a new message is created
+   * @property {Message} messageUpdate - Fired when a message is updated
+   * @property {Message} messageDelete - Fired when a message is deleted
+   * @property {Channel} channelCreate - Fired when a new channel is created
+   * @property {Channel} channelDelete - Fired when a channel is deleted
+   * @property {Channel} channelUpdate - Fired when a channel is updated
+   * @property {{channel: Channel, member: User}} channelMemberAdd - Fired when a member joins a channel
+   * @property {{channel: Channel, member: User}} channelMemberRemove - Fired when a member leaves a channel
+   * @property {User} channelMemberUpdate - Fired when a member updates their info in a channel
+   * @property {Emoji} emojiCreate - Fired when a new emoji is created
+   * @property {Emoji} emojiDelete - Fired when an emoji is deleted
+   * @property {Error} error - Fired when an error occurs
+   * @property {void} disconnect - Fired when disconnected from the gateway
+   * @property {void} reconnect - Fired when reconnecting to the gateway
+   * 
    * @fires Client#ready
    * @fires Client#messageCreate
    * @fires Client#messageDelete
@@ -38,12 +56,13 @@ class Client extends EventEmitter {
    * @fires Client#typingStart
    * @fires Client#typingStop
    * @class Client
-   * @description Classe principal do BenioCord.js - Gerencia a comunicação com a API e eventos do bot
+   * @description The main class of BenioCord.js, responsible for managing API communication and bot events.
    * @param {Object} options - Opções de configuração do cliente
    * @param {string} options.token - Token do bot para autenticação
    * @example
-   * const { Client } = require('beniocord.js');
-   * const client = new Client({ token: 'YOUR_BOT_TOKEN' });
+   * const Beniocord = require('beniocord.js');
+   * const client = new Beniocord({ token: 'YOUR_BOT_TOKEN' });
+   * client.login();
    */
   constructor({ token }) {
     super();
@@ -61,6 +80,7 @@ class Client extends EventEmitter {
     this.isConnected = false;
     this.isReady = false;
     this.status = 'online';
+    this.version = require('./package.json').version;
 
     // Configuration options
     this.config = {
@@ -174,7 +194,8 @@ class Client extends EventEmitter {
   }
 
   /**
-   * Disconnects the bot from the server
+   * Kills the connection to the server
+   * @returns {void}
    */
   disconnect() {
     this._stopHeartbeat();
@@ -213,10 +234,14 @@ class Client extends EventEmitter {
   /**
    * Sets the bot's status
    * @param {string} status - Status: "online", "away", "dnd", "offline"
+   * @returns {Promise<Object>}
+   * @example
+   * client.setStatus("dnd").then((data) => {
+   *  console.log("Status updated:", data);
+   * });
    */
   async setStatus(status) {
     const validStatuses = ["online", "offline", "away", "dnd"];
-
     if (!validStatuses.includes(status)) {
       throw new ClientError(
         `Invalid status. Valid statuses are: ${validStatuses.join(", ")}`,
@@ -226,7 +251,14 @@ class Client extends EventEmitter {
 
     this._ensureConnected();
     this.status = status;
-    this.socket.emit('status:update', { status });
+
+    return new Promise((resolve) => {
+      this.socket.once('user:status-update', (data) => {
+        resolve(data);
+      });
+
+      this.socket.emit('status:update', { status });
+    });
   }
 
   /**
@@ -424,7 +456,7 @@ class Client extends EventEmitter {
    * Adds a member to a channel
    * @param {string} channelId - Channel ID
    * @param {string} userId - User ID to add
-   * @param {string} role - Member role (default: 'member')
+   * @param {string} [role] - Member role (default: 'member')
    * @returns {Promise<Object>} Response data
    */
   async addChannelMember(channelId, userId, role = 'member') {
@@ -680,9 +712,43 @@ class Client extends EventEmitter {
   async fetchMessage(channelId, messageId) {
     try {
       const res = await this._axios.get(`/api/channels/${channelId}/messages/${messageId}`);
-      return new Message(res.data, this);
+      const raw = res.data;
+
+      // --- USER ---
+      const userData = {
+        id: raw.user_id,
+        username: raw.username,
+        display_name: raw.display_name,
+        avatar_url: raw.avatar_url,
+        status: raw.status || 'online',
+        emblems: raw.emblems || [],
+        is_bot: raw.is_bot ?? false,
+        last_seen: raw.last_seen ?? raw.created_at,
+        created_at: raw.created_at,
+      };
+      const messageData = { ...raw, user: userData };
+
+      // Cria a mensagem
+      const message = new Message(messageData, this);
+
+      // Cache do author
+      if (message.author) this.cache.users.set(message.author.id, message.author);
+
+      // --- CHANNEL ---
+      if (!message.channel && raw.channel_id) {
+        // Tenta pegar da cache
+        let channel = this.cache.channels.get(raw.channel_id);
+        if (!channel) {
+          channel = await this.fetchChannel(raw.channel_id);
+        }
+        message.channel = channel;
+      }
+
+      return message;
     } catch (error) {
-      throw error instanceof ClientError ? error : new ClientError(error.message, "FETCH_MESSAGE_ERROR");
+      throw error instanceof ClientError
+        ? error
+        : new ClientError(error.message, "FETCH_MESSAGE_ERROR");
     }
   }
 
@@ -693,6 +759,7 @@ class Client extends EventEmitter {
   /**
    * Starts typing indicator in a channel
    * @param {string} channelId - Channel ID
+   * @returns {void}
    */
   startTyping(channelId) {
     try {
@@ -706,6 +773,7 @@ class Client extends EventEmitter {
   /**
    * Stops typing indicator in a channel
    * @param {string} channelId - Channel ID
+   * @returns {void}
    */
   stopTyping(channelId) {
     try {
@@ -746,13 +814,12 @@ class Client extends EventEmitter {
   /**
    * Fetches all available emojis
    * @param {Object} options - Fetch options
-   * @param {boolean} options.includeOthers - Include emojis from other users
    * @param {string} options.search - Search query
    * @returns {Promise<Emoji[]>} Array of emoji objects
    */
   async fetchAllEmojis(options = {}) {
     try {
-      const endpoint = options.includeOthers ? '/api/emojis/all' : '/api/emojis';
+      const endpoint = '/api/emojis/all';
       const params = {};
 
       if (options.search) {
@@ -760,7 +827,9 @@ class Client extends EventEmitter {
       }
 
       const res = await this._axios.get(endpoint, { params });
+
       const emojis = res.data.map(e => {
+        if (!e.user_id) e.user_id = this.user.id;
         const emoji = new Emoji(e);
         this.cache.emojis.set(emoji.id, emoji);
         return emoji;
@@ -768,7 +837,9 @@ class Client extends EventEmitter {
 
       return emojis;
     } catch (error) {
-      throw error instanceof ClientError ? error : new ClientError(error.message, "FETCH_EMOJIS_ERROR");
+      throw error instanceof ClientError
+        ? error
+        : new ClientError(error.message, "FETCH_EMOJIS_ERROR");
     }
   }
 
@@ -849,6 +920,7 @@ class Client extends EventEmitter {
 
   /**
    * Clears all cached data
+   * @returns {void}
    */
   clearCache() {
     this.cache.users.clear();
@@ -945,7 +1017,7 @@ class Client extends EventEmitter {
       });
 
       this.socket.on("reconnect_error", (error) => {
-        this.emit("reconnectError", error);
+        this.emit("error", error);
       });
 
       this.socket.on("reconnect_failed", () => {
@@ -1231,12 +1303,21 @@ class Client extends EventEmitter {
     const msg = new Message(data, this);
 
     if (!msg.author && data.user_id) {
-      msg.author = new User({
-        id: data.user_id,
-        username: data.username,
-        display_name: data.display_name,
-        avatar_url: data.avatar_url
-      }, this);
+      const cachedUser = this.cache.users.get(data.user_id);
+      if (cachedUser) {
+        cachedUser.username = data.username || cachedUser.username;
+        cachedUser.displayName = data.display_name || cachedUser.displayName;
+        cachedUser.avatarUrl = formatUrl(data.avatar_url) || cachedUser.avatarUrl;
+        msg.author = cachedUser;
+      } else {
+        msg.author = new User({
+          id: data.user_id,
+          username: data.username,
+          display_name: data.display_name,
+          avatar_url: data.avatar_url,
+        }, this);
+        this.cache.users.set(msg.author.id, msg.author);
+      }
     }
 
     if (!msg.channel && data.channel_id) {
@@ -1435,11 +1516,41 @@ class Client extends EventEmitter {
       throw new ClientError(`File upload error: ${error.message}`, 'UPLOAD_FAILED');
     }
   }
+
+  // ============================================================================
+  // EVENT EMITTER OVERRIDES
+  // ============================================================================
+
+  /**
+   * Attaches an event listener.
+   * @superInternal
+   * @template {keyof ClientEvents} K
+   * @param {K} event The event name.
+   * @param {(arg: ClientEvents[K]) => void} listener
+   * @returns {this}
+   */
+  on(event, listener) {
+    return super.on(event, listener);
+  }
+
+  /**
+   * Emits an event with typed arguments.
+   * @internal
+   * @template {keyof ClientEvents} K
+   * @param {K} event
+   * @param {ClientEvents[K]} payload
+   * @returns {this}
+   */
+  emit(event, payload) {
+    return super.emit(event, payload);
+  }
 }
 
+/**
+ * @internal
+ */
 class ClientError extends Error {
   /**
-   * @private
    * @param {string} message - Error message
    * @param {string} code - Error code
   */

package/README.md

@@ -1,29 +1,54 @@
-# Beniocord.js
+# Getting Started
 
-**Beniocord.js** is a Node.js library for creating bots easily, with basic moderation features, automatic responses, and event handling.
+## Introduction <span style="font-size:0.8em;">Intro</span>
 
-> ⚠️ This is an early version — meant to give you a starting point for building your bot.
+### Beniocord.js
+
+A powerful JavaScript library for building Beniocord bots with ease.
+
+[![npm version](https://img.shields.io/npm/v/beniocord.js?color=crimson&logo=npm&style=flat-square)](https://www.npmjs.com/package/beniocord.js)
+[![npm downloads](https://img.shields.io/npm/dt/beniocord.js?color=crimson&logo=npm&style=flat-square)](https://www.npmjs.com/package/beniocord.js)
+[![GitHub stars](https://img.shields.io/github/stars/Junior37534/beniocord.js?color=yellow&logo=github&style=flat-square)](https://github.com/Junior37534/beniocord.js)
+[![GitHub issues](https://img.shields.io/github/issues/Junior37534/beniocord.js?color=green&logo=github&style=flat-square)](https://github.com/Junior37534/beniocord.js/issues)
+[![Join Beniocord](https://img.shields.io/badge/Join-Beniocord-5865F2?style=flat-square&logoColor=white)](https://beniocord.site/register)
+
+---
+
+### About
+
+Beniocord.js is a powerful Node.js module that allows you to easily interact with the Beniocord API. It provides an intuitive and modern approach to bot development.
+
+### Features
+
+- 🚀 Easy to use and beginner-friendly
+- ⚡ Fast and efficient
+- 📦 Object-oriented design
+- 🔄 Promise-based architecture
+- 🎯 Full Beniocord API coverage
+- 💪 TypeScript support
+
+### Requirements
+
+- Node.js >= 18
+- NPM >= 9
 
 ---
 
 ## Installation
 
+Install via NPM:
+
 ```bash
 npm install beniocord.js
-```
-
-> Make sure you have Node.js >= 18 installed.
+````
 
 ---
 
-## Basic Example
+## Quick Example
 
 ```js
-const Client = require("beniocord.js");
-const { MessageEmbed } = Client;
-require('dotenv').config();
-
-const client = new Client({ token: process.env.BOT_TOKEN });
+const Beniocord = require("beniocord.js");
+const client = new Beniocord({ token: 'YOUR_BOT_TOKEN' });
 
 client.on("ready", () => {
   console.log("🤖 Bot connected!");
@@ -31,20 +56,21 @@ client.on("ready", () => {
 
 client.on("messageCreate", async (msg) => {
   if (msg.author?.id === client.user?.id) return;
-  if (!msg.content) return;
+  if (!msg.content.startsWith('!')) return;
 
-  if (msg.content.toLowerCase() === "!ping") {
-    await client.sendMessage(msg.channel.id, "🏓 Pong!");
-  }
-  
-  if (msg.content.toLowerCase() === "!embed") {
-    const embed = new MessageEmbed()
-      .setTitle("Hello from Beniocord!")
-      .setDescription("This is an example embed")
-      .setColor("#147bba")
-      .setFooter(msg.author.displayName, msg.author.avatarURL());
-    
-    await msg.reply(embed);
+  const comando = msg.content.slice('!'.length).split(' ')[0];
+  const args = msg.content.slice(comando.length + '!'.length + 1).trim().split(' ');
+
+  if (comando === "ping") {
+    const msgTimestamp = Date.now() - Date.parse(msg.createdAt);
+    const sent = await msg.channel.send("🏓 Pinging...");
+    const editTimestamp = Date.now() - Date.parse(sent.createdAt);
+
+    await sent.edit(
+        `🏓 **Pong!**\n` +
+        `📨 **Message → Bot:** ${msgTimestamp}ms\n` +
+        `✏️ **Send → Edit:** ${editTimestamp}ms`
+    );
   }
 });
 
@@ -53,24 +79,8 @@ client.login();
 
 ---
 
-## Features
-
-* **Basic events**: `messageCreate`, `messageEdit`, `messageDelete`, `memberJoin`, `memberLeave`, `presenceUpdate`, `channelUpdate`, and more.
-* **Basic moderation**: delete messages, edit messages, etc.
-* **Embeds support**: create rich messages with `MessageEmbed`.
-* **Event-driven**: easy to handle events in real-time.
-
----
-
-## Events
-
-```js
-client.on("messageCreate", msg => {...});
-client.on("memberJoin", data => {...});
-client.on("channelUpdate", data => {...});
-// and many more...
-```
-
-You can add custom events and interact with your bot in real-time.
+## Useful Links
 
----
+* [Official Website](https://beniocord.site)
+* [Documentation](https://docs.beniocord.site)
+* [Join Beniocord](https://beniocord.site/register)

package/package.json

@@ -5,7 +5,7 @@
     "socket.io-client": "^4.8.1"
   },
   "name": "beniocord.js",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "Uma biblioteca leve e intuitiva para integração com APIs de bots em plataformas de mensagens, como Discord. Facilita o envio de mensagens, gerenciamento de canais e interação com usuários, proporcionando uma experiência de desenvolvimento ágil e eficiente.",
   "main": "Client.js",
   "scripts": {

package/structures/Channel.js

@@ -3,7 +3,45 @@ const MessageCollector = require('./MessageCollector');
 const Collection = require('@discordjs/collection').Collection;
 
 let client;
+
+/**
+ * @internal
+ */
 class Channel {
+  /**
+   * Creates a new Channel instance.
+   * @param {Object} data - Raw channel data.
+   * @param {string|number} data.id - The unique ID of the channel.
+   * @param {string} data.name - The name of the channel.
+   * @param {string} [data.description] - The channel description.
+   * @param {string} [data.type="text"] - The type of the channel (text, voice, etc.).
+   * @param {string} [data.icon_url] - The URL of the channel icon.
+   * @param {string|number} data.created_by - ID of the channel owner.
+   * @param {boolean} [data.is_private=false] - Whether the channel is private.
+   * @param {boolean} [data.is_locked=false] - Whether the channel is locked.
+   * @param {number|string} [data.member_count=0] - Number of members in the channel.
+   * @param {string|Date} data.created_at - Creation timestamp.
+   * @param {string|Date} data.updated_at - Last update timestamp.
+   * @param {import('./Client')} clientInstance - The client instance.
+   * @returns {Channel} The created Channel instance.
+   * @example
+   * // msg.channel
+   * Channel {
+   *   id: 2,
+   *   name: 'Privado',
+   *   description: 'DM Privada para conversar secretas!\n',
+   *   type: 'text',
+   *   iconUrl: 'https://api.beniocord.site/uploads/1762899895145-938680330.gif',
+   *   ownerId: 1,
+   *   isPrivate: true,
+   *   isLocked: false,
+   *   memberCount: 8,
+   *   createdAt: '2025-09-21T15:28:43.610Z',
+   *   updatedAt: '2025-11-11T23:49:54.906Z',
+   *   members: Collection(0) [Map] { fetch: [AsyncFunction (anonymous)] },
+   *   messages: Collection(0) [Map] { fetch: [AsyncFunction (anonymous)] }
+   * }
+   */
   constructor(data, clientInstance) {
     client = clientInstance;
 
@@ -19,6 +57,10 @@ class Channel {
     this.createdAt = data.created_at;
     this.updatedAt = data.updated_at;
 
+    /**
+     * Cached members of the channel.
+     * @type {Collection<string, import('./User')>}
+     */
     this.members = new Collection();
     this.members.fetch = async () => {
       const members = await client.fetchChannelMembers(this.id);
@@ -29,6 +71,10 @@ class Channel {
       return this.members;
     };
 
+    /**
+     * Cached messages of the channel.
+     * @type {Collection<string, import('./Message')>}
+     */
     this.messages = new Collection();
     this.messages.fetch = async (id) => {
       if (client.fetchMessage) {
@@ -46,22 +92,40 @@ class Channel {
     });
   }
 
+  /**
+   * Sends a message to the channel.
+   * @param {string|Object} content - The content of the message.
+   * @param {Object} [opts] - Optional message options.
+   * @returns {Promise<import('./Message')>} The sent message.
+   */
   async send(content, opts = {}) {
     return client.sendMessage(this.id, content, opts);
   }
 
+  /**
+   * Starts typing indicator in the channel.
+   * @returns {Promise<void>}
+   */
   startTyping() {
     return client.startTyping(this.id);
   }
 
+  /**
+   * Stops typing indicator in the channel.
+   * @returns {Promise<void>}
+   */
   stopTyping() {
     return client.stopTyping(this.id);
   }
 
+  /**
+   * Creates a new message collector in this channel.
+   * @param {Object} [options={}] - Collector options.
+   * @returns {MessageCollector} The created message collector.
+   */
   createMessageCollector(options = {}) {
     return new MessageCollector(this, options, client);
   }
-
 }
 
 module.exports = Channel;

package/structures/Emoji.js

@@ -1,14 +1,59 @@
 const { formatUrl } = require("../helpers");
 
+/**
+ * @internal
+ */
 class Emoji {
+    /**
+     * Creates a new Emoji instance.
+     * @param {Object} data - Raw emoji data.
+     * @param {string|number} data.id - The unique ID of the emoji.
+     * @param {string|number} data.user_id - The ID of the user who uploaded the emoji.
+     * @param {string} data.name - The name of the emoji.
+     * @param {string} data.url - The URL of the emoji image.
+     * @param {string|number|Date} data.created_at - Timestamp when the emoji was created.
+     * @returns {Emoji} The created Emoji instance.
+     * @example 
+     * Emoji {
+     *   id: 1,
+     *   userId: 1,
+     *   name: 'shitcord',
+     *   url: 'https://api.beniocord.site/uploads/emojis/1758982533925-364594757.png',
+     *   createdAt: '2025-09-27T14:15:33.932Z'
+     * }
+     * 
+     */
     constructor(data) {
+        /**
+         * The unique ID of the emoji.
+         * @type {string|number}
+         */
         this.id = data.id;
+
+        /**
+         * The ID of the user who uploaded the emoji.
+         * @type {string|number}
+         */
         this.userId = data.user_id;
+
+        /**
+         * The name of the emoji.
+         * @type {string}
+         */
         this.name = data.name;
+
+        /**
+         * The URL of the emoji image.
+         * @type {string}
+         */
         this.url = formatUrl(data.url);
+
+        /**
+         * Timestamp when the emoji was created.
+         * @type {string|number|Date}
+         */
         this.createdAt = data.created_at;
-        this.updatedAt = data.updated_at;
     }
 }
 
-module.exports = Emoji;
+module.exports = Emoji;

package/structures/Message.js

@@ -5,7 +5,7 @@ const { formatUrl } = require('../helpers/index');
 let client;
 
 /**
- * Represents a message in a channel.
+ * @internal
  */
 class Message {
   /**
@@ -23,11 +23,48 @@ class Message {
    * @param {string|number} [data.sticker_id] - ID of a sticker attached to the message.
    * @param {string|number|Date} [data.edited_at] - Timestamp when the message was edited.
    * @param {string|number|Date} [data.created_at] - Timestamp when the message was created.
-   * @param {Object} clientInstance - The client instance to send/edit/delete messages.
+   * @param {Object} clientInstance - The client instance.
+   * @returns {Message} The created Message instance.
    * @example
-   * // Creating a message instance
-   * const msg = new Message({ id: 1, content: "Hello!" }, client);
-   * 
+   * Message {
+   *   id: 20711,
+   *   content: 'Hello World!',
+   *   messageType: 'text',
+   *   fileUrl: null,
+   *   fileName: null,
+   *   fileSize: null,
+   *   attachments: [],
+   *   replyTo: 20709,
+   *   stickerId: null,
+   *   editedAt: null,
+   *   createdAt: '2025-11-16T14:29:40.598Z',
+   *   author: User {
+   *     id: 1,
+   *     username: 'junior9244',
+   *     displayName: 'Junior',
+   *     avatarUrl: 'https://api.beniocord.site/uploads/avatars/1760736025811-629632107.png',
+   *     status: 'online',
+   *     emblems: [],
+   *     isBot: false,
+   *     lastSeen: '2025-11-16T14:29:40.598Z',
+   *     createdAt: '2025-11-16T14:29:40.598Z'
+   *   },
+   *   channel: Channel {
+   *     id: 2,
+   *     name: 'Privado',
+   *     description: 'DM Privada para conversar secretas!\n',
+   *     type: 'text',
+   *     iconUrl: 'https://api.beniocord.site/uploads/1762899895145-938680330.gif',
+   *     ownerId: 1,
+   *     isPrivate: true,
+   *     isLocked: false,
+   *     memberCount: 8,
+   *     createdAt: '2025-09-21T15:28:43.610Z',
+   *     updatedAt: '2025-11-11T23:49:54.906Z',
+   *     members: Collection(0) [Map] { fetch: [AsyncFunction (anonymous)] },
+   *     messages: Collection(0) [Map] { fetch: [AsyncFunction (anonymous)] }
+   *   }
+   * }
    */
   constructor(data, clientInstance) {
     this.id = data.id;

package/structures/MessageCollector.js

@@ -1,45 +1,68 @@
 const EventEmitter = require('events');
 
 class MessageCollector extends EventEmitter {
+  /**
+   * Creates a new MessageCollector.
+   *
+   * @param {Channel} channel - The channel to listen for messages.
+   * @param {Object} [options={}] - Options for the collector.
+   * @param {function(Message): boolean|Promise<boolean>} [options.filter] - Filter function to determine which messages are collected.
+   * @param {number} [options.time=60000] - Time in milliseconds before the collector stops automatically.
+   * @param {number} [options.max=Infinity] - Maximum number of messages to collect before stopping.
+   * @param {Client} client - The client instance to listen for events.
+   *
+   * @example
+   * const collector = new MessageCollector(channel, { filter: msg => msg.content.includes('hello'), time: 30000 }, client);
+   * collector.on('collect', msg => console.log(`Collected message: ${msg.content}`));
+   * collector.on('end', (collected, reason) => console.log(`Collector ended: ${reason}, collected ${collected.length} messages`));
+   */
   constructor(channel, options = {}, client) {
     super();
-    
+
     this.channel = channel;
     this.client = client;
-    // this.client = channel.client;
     this.filter = options.filter || (() => true);
     this.time = options.time || 60000;
     this.max = options.max || Infinity;
     this.collected = [];
     this.ended = false;
-    
+
     this._timeout = null;
     this._handleMessage = this._handleMessage.bind(this);
-    
+
     this._setup();
   }
-  
+
+  /**
+   * Initializes event listeners and timeout for automatic stop.
+   * @private
+   */
   _setup() {
     this.client.on('messageCreate', this._handleMessage);
-    
+
     if (this.time) {
       this._timeout = setTimeout(() => {
         this.stop('time');
       }, this.time);
     }
   }
-  
+
+  /**
+   * Internal handler for incoming messages.
+   * @param {Message} message - The message received.
+   * @private
+   */
   async _handleMessage(message) {
     if (this.ended) return;
     if (message.channel.id !== this.channel.id) return;
-    
+
     try {
       const filterResult = await this.filter(message);
       if (!filterResult) return;
-      
+
       this.collected.push(message);
       this.emit('collect', message);
-      
+
       if (this.collected.length >= this.max) {
         this.stop('limit');
       }
@@ -47,28 +70,40 @@ class MessageCollector extends EventEmitter {
       this.emit('error', error);
     }
   }
-  
-  stop(reason = 'user', ) {
+
+  /**
+   * Stops the collector manually or automatically.
+   *
+   * @param {string} [reason='user'] - Reason for stopping ('user', 'time', 'limit', etc.).
+   * @fires MessageCollector#end
+   */
+  stop(reason = 'user') {
     if (this.ended) return;
-    
+
     this.ended = true;
-    
+
     if (this._timeout) {
       clearTimeout(this._timeout);
       this._timeout = null;
     }
-    
+
     this.client.removeListener('messageCreate', this._handleMessage);
     this.emit('end', this.collected, reason);
   }
-  
+
+  /**
+   * Resets the timer for the collector.
+   *
+   * @param {Object} [options={}] - Options to override current timer.
+   * @param {number} [options.time] - New time in milliseconds to set.
+   */
   resetTimer(options = {}) {
     if (this._timeout) {
       clearTimeout(this._timeout);
     }
-    
+
     const time = options.time || this.time;
-    
+
     if (time) {
       this._timeout = setTimeout(() => {
         this.stop('time');
@@ -77,4 +112,23 @@ class MessageCollector extends EventEmitter {
   }
 }
 
-module.exports = MessageCollector;
+/**
+ * Emitted when a message is successfully collected.
+ * @event MessageCollector#collect
+ * @param {Message} message - The collected message.
+ */
+
+/**
+ * Emitted when the collector ends.
+ * @event MessageCollector#end
+ * @param {Message[]} collected - Array of collected messages.
+ * @param {string} reason - Reason the collector ended.
+ */
+
+/**
+ * Emitted when an error occurs inside the collector.
+ * @event MessageCollector#error
+ * @param {Error} error - The error encountered.
+ */
+
+module.exports = MessageCollector;

package/structures/User.js

@@ -1,5 +1,8 @@
+const { formatUrl } = require("../helpers");
+let client;
+
 /**
- * Represents a user.
+ * @internal
  */
 class User {
   /**
@@ -10,13 +13,28 @@ class User {
    * @param {string} data.display_name - The display name of the user.
    * @param {string} data.avatar_url - The URL of the user's avatar.
    * @param {string} [data.status='offline'] - The user's status.
-   * @param {Array<string>} [data.emblems=[]] - Array of user emblems.
+   * @param {Array<Object>} [data.emblems=[]] - Array of user emblems.
    * @param {boolean} data.is_bot - Whether the user is a bot.
    * @param {string|number|Date} data.last_seen - Last seen timestamp.
    * @param {string|number|Date} data.created_at - Account creation timestamp.
-   * @param {Object} client - The client instance (optional, internal use).
+   * @param {import('./Client')} clientInstance - The client instance.
+   * @returns {User} The created User instance.
+   * @example
+   * User {
+   *   id: 1,
+   *   username: 'junior9244',
+   *   displayName: 'Junior',
+   *   avatarUrl: 'https://api.beniocord.site/uploads/avatars/1760736025811-629632107.png',
+   *   status: 'online',
+   *   emblems: [ [Object], [Object] ],
+   *   isBot: false,
+   *   lastSeen: '2025-11-16T14:44:19.394Z',
+   *   createdAt: '2025-09-21T15:00:07.753Z'
+   * }
    */
-  constructor(data, client) {
+  constructor(data, clientInstance) {
+    client = clientInstance;
+
     this.id = data.id;
     this.username = data.username;
     this.displayName = data.display_name;
@@ -31,10 +49,26 @@ class User {
   /**
    * Returns the avatar URL of the user.
    * @returns {string} The avatar URL.
+   * @example
+   * https://api.beniocord.site/uploads/avatars/1760736025811-629632107.png
    */
   avatarURL() {
     return this.avatarUrl;
   }
+
+  /**
+   * Fetches or refreshes this user from the API.
+   * @param {boolean} [force=false] - Whether to force fetch even if cached.
+   * @returns {Promise<User>} The updated User instance.
+   * @example
+   * const freshUser = await user.fetch();
+   */
+  async fetch(force = false) {
+    if (!client) throw new Error("Client instance not available.");
+    const updatedUser = await client.fetchUser(this.id, force);
+    Object.assign(this, updatedUser);
+    return this;
+  }
 }
 
-module.exports = User;
+module.exports = User;

package/structures/Util.js

@@ -562,10 +562,21 @@ MessageEmbed.Colors = {
 };
 
 /**
- * MessageAttachment - Para anexos
  * @class
  */
 class MessageAttachment {
+    /**
+     * Creates a new MessageAttachment instance.
+     *
+     * @param {Buffer|Uint8Array|string} buffer - The data of the attachment. Can be a Buffer, Uint8Array, or base64 string.
+     * @param {string} name - The name of the attachment file (e.g., "image.png").
+     *
+     * @throws {Error} If the buffer is not provided.
+     * @throws {Error} If the name is not a valid string.
+     *
+     * @example
+     * const attachment = new MessageAttachment(fileBuffer, "photo.png");
+     */
     constructor(buffer, name) {
         if (!buffer) {
             throw new Error('Attachment buffer is required');