beniocord.js 2.0.9 → 2.1.0

package/Client.js

@@ -11,29 +11,40 @@ const Channel = require("./structures/Channel");
 const Emoji = require("./structures/Emoji");
 const { MessageEmbed, MessageAttachment } = require("./structures/Util");
 
-class ClientError extends Error {
-  constructor(message, code) {
-    super(message);
-    this.name = 'ClientError';
-    this.code = code;
-  }
-}
-
 let global = {
   token: "",
   apiUrl: "https://api-bots.beniocord.site"
 };
 
-/**
- * @fires Client#ready
- * @fires Client#messageCreate
- * @fires Client#messageDelete
- * @fires Client#messageEdit
- * @fires Client#error
- * @fires Client#disconnect
- * @fires Client#reconnect
- */
 class Client extends EventEmitter {
+  /**
+   * @fires Client#ready
+   * @fires Client#messageCreate
+   * @fires Client#messageDelete
+   * @fires Client#messageEdit
+   * @fires Client#error
+   * @fires Client#disconnect
+   * @fires Client#reconnect
+   * @fires Client#emojiCreate
+   * @fires Client#emojiDelete
+   * @fires Client#stickerCreate
+   * @fires Client#stickerDelete
+   * @fires Client#channelCreate
+   * @fires Client#channelDelete
+   * @fires Client#channelUpdate
+   * @fires Client#channelMemberAdd
+   * @fires Client#channelMemberRemove
+   * @fires Client#channelMemberUpdate
+   * @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
+   * @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' });
+   */
   constructor({ token }) {
     super();
 
@@ -141,6 +152,10 @@ class Client extends EventEmitter {
       await this._joinAllChannelRooms();
 
       this.isReady = true;
+
+      /**
+       * @event Client#ready
+       */
       this.emit("ready", this.user);
 
       return this.user;
@@ -216,7 +231,7 @@ class Client extends EventEmitter {
 
   /**
    * Fetches information about the bot user
-   * @param {boolean} force - Force fetch from API instead of cache
+   * @param {boolean} [force=false] - Force fetch from API instead of cache
    * @returns {Promise<User>} Bot user object
    */
   async fetchMe(force = false) {
@@ -240,7 +255,7 @@ class Client extends EventEmitter {
   /**
    * Fetches a user by ID
    * @param {string} id - User ID
-   * @param {boolean} force - Force fetch from API instead of cache
+   * @param {boolean} [force=false] - Force fetch from API instead of cache
    * @returns {Promise<User>} User object
    */
   async fetchUser(id, force = false) {
@@ -286,7 +301,7 @@ class Client extends EventEmitter {
   /**
    * Fetches a specific channel by ID
    * @param {string} id - Channel ID
-   * @param {boolean} force - Force fetch from API instead of cache
+   * @param {boolean} [force=false] - Force fetch from API instead of cache
    * @returns {Promise<Channel>} Channel object
    */
   async fetchChannel(id, force = false) {
@@ -708,7 +723,7 @@ class Client extends EventEmitter {
   /**
    * Fetches an emoji by ID
    * @param {string} id - Emoji ID
-   * @param {boolean} force - Force fetch from API instead of cache
+   * @param {boolean} [force=false] - Force fetch from API instead of cache
    * @returns {Promise<Emoji>} Emoji object
    */
   async fetchEmoji(id, force = false) {
@@ -760,7 +775,7 @@ class Client extends EventEmitter {
   /**
    * Fetches a sticker by ID
    * @param {string} id - Sticker ID
-   * @param {boolean} force - Force fetch from API instead of cache
+   * @param {boolean} [force=false] - Force fetch from API instead of cache
    * @returns {Promise<Object>} Sticker data
    */
   async fetchSticker(id, force = false) {
@@ -968,6 +983,9 @@ class Client extends EventEmitter {
   _setupSocketHandlers() {
     this._removeSocketHandlers();
 
+    /**
+     * @event Client#messageCreate
+     */
     this.socket.on('message:new', async (data) => {
       try {
         if (this._sentMessages.has(data.id)) {
@@ -983,31 +1001,49 @@ class Client extends EventEmitter {
       }
     });
 
+    /**
+     * @event Client#messageDelete
+     */
     this.socket.on('message:deleted', (data) => {
       const { messageId } = data;
       this._markMessageDeleted(messageId);
       this.emit('messageDelete', data);
     });
 
+    /**
+     * @event Client#messageEdit
+     */
     this.socket.on('message:edited', (data) => {
       const { messageId, content, editedAt } = data;
       this._updateMessageContent(messageId, content, editedAt);
       this.emit('messageEdit', data);
     });
 
+    /**
+     * @event Client#typingStart
+     */
     this.socket.on('typing:user-start', (data) => {
       this.emit('typingStart', data);
     });
 
+    /**
+     * @event Client#typingStop
+     */
     this.socket.on('typing:user-stop', (data) => {
       this.emit('typingStop', data);
     });
 
+    /**
+     * @event Client#userStatusUpdate
+     */
     this.socket.on('user:status-update', (data) => {
       this._updateUserStatus(data);
       this.emit('userStatusUpdate', data);
     });
 
+    /**
+     * @event Client#memberJoin
+     */
     this.socket.on('member:join', async (data) => {
       const member = await this.fetchUser(data.memberId).catch(() => null);
       const channel = this.cache.channels.get(data.channelId);
@@ -1017,6 +1053,9 @@ class Client extends EventEmitter {
       this.emit('memberJoin', { channel, member });
     });
 
+    /**
+     * @event Client#memberLeave
+     */
     this.socket.on('member:leave', async (data) => {
       const channel = this.cache.channels.get(data.channelId);
       const member = this.cache.users.get(data.memberId);
@@ -1032,16 +1071,25 @@ class Client extends EventEmitter {
       this.emit('memberLeave', { channel, member });
     });
 
+    /**
+     * @event Client#channelUpdate
+     */
     this.socket.on('channel:update', (data) => {
       this._updateChannel(data);
       this.emit('channelUpdate', data);
     });
 
+    /**
+     * @event Client#channelDelete
+     */
     this.socket.on('channel:delete', (data) => {
       this.cache.channels.delete(data.channelId);
       this.emit('channelDelete', data);
     });
 
+    /**
+     * @event Client#rateLimited
+     */
     this.socket.on('rate:limited', (data) => {
       this.emit('rateLimited', data);
     });
@@ -1389,6 +1437,19 @@ class Client extends EventEmitter {
   }
 }
 
+class ClientError extends Error {
+  /**
+   * @private
+   * @param {string} message - Error message
+   * @param {string} code - Error code
+  */
+  constructor(message, code) {
+    super(message);
+    this.name = 'ClientError';
+    this.code = code;
+  }
+}
+
 Client.MessageEmbed = MessageEmbed;
-Client.ClientError = ClientError;
+// Client.ClientError = ClientError;
 module.exports = Client;

package/package.json

@@ -5,7 +5,7 @@
     "socket.io-client": "^4.8.1"
   },
   "name": "beniocord.js",
-  "version": "2.0.9",
+  "version": "2.1.0",
   "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/Message.js

@@ -3,7 +3,32 @@ const Channel = require("./Channel");
 const { formatUrl } = require('../helpers/index');
 
 let client;
+
+/**
+ * Represents a message in a channel.
+ */
 class Message {
+  /**
+   * Creates a new Message instance.
+   * @param {Object} data - Raw message data.
+   * @param {string|number} data.id - The unique ID of the message.
+   * @param {string} data.content - The content of the message.
+   * @param {string} [data.message_type="text"] - The type of the message (text, file, etc.).
+   * @param {string} [data.file_url] - URL of the attached file.
+   * @param {string} [data.file_name] - Name of the attached file.
+   * @param {number} [data.file_size] - Size of the attached file in bytes.
+   * @param {Object} [data.user] - Author user data.
+   * @param {Object} [data.channel] - Channel data where the message was sent.
+   * @param {string|number} [data.reply_to] - ID of the message this is replying to.
+   * @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.
+   * @example
+   * // Creating a message instance
+   * const msg = new Message({ id: 1, content: "Hello!" }, client);
+   * 
+   */
   constructor(data, clientInstance) {
     this.id = data.id;
     this.content = data.content;
@@ -25,13 +50,21 @@ class Message {
       });
     }
 
-    // this.author = data.user ? new User(data.user, this) : null;
     this.author = data.user ? new User(data.user, clientInstance) : null;
     this.channel = data.channel ? new Channel(data.channel, clientInstance) : null;
-    // this.member = { user: this.author }
     client = clientInstance;
   }
 
+  /**
+   * Replies to this message.
+   * @param {string} content - Content of the reply.
+   * @param {Object} [opts={}] - Additional options for the reply.
+   * @returns {Promise<Message>} The sent reply message.
+   *
+   * @example
+   * // Replying to a message
+   * await msg.reply("Thanks for your message!");
+   */
   async reply(content, opts = {}) {
     return client.sendMessage(this.channel.id, content, {
       replyTo: this.id,
@@ -39,10 +72,27 @@ class Message {
     });
   }
 
+  /**
+   * Edits this message.
+   * @param {string} content - New content for the message.
+   * @returns {Promise<Message>} The edited message.
+   *
+   * @example
+   * // Editing a message
+   * await msg.edit("Updated content!");
+   */
   async edit(content) {
     return client.editMessage(this.id, content);
   }
 
+  /**
+   * Deletes this message.
+   * @returns {Promise<void>}
+   *
+   * @example
+   * // Deleting a message
+   * await msg.delete();
+   */
   async delete() {
     return client.deleteMessage(this.id);
   }

package/structures/User.js

@@ -1,6 +1,21 @@
-const { formatUrl } = require("../helpers");
-
+/**
+ * Represents a user.
+ */
 class User {
+  /**
+   * Creates a new User instance.
+   * @param {Object} data - Raw user data.
+   * @param {string|number} data.id - The unique ID of the user.
+   * @param {string} data.username - The username of the 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 {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).
+   */
   constructor(data, client) {
     this.id = data.id;
     this.username = data.username;
@@ -11,14 +26,12 @@ class User {
     this.isBot = data.is_bot;
     this.lastSeen = data.last_seen;
     this.createdAt = data.created_at;
-    // this.email = data.email;
-    // this.updatedAt = data.updated_at;
   }
 
-  // displayAvatarURL() {
-  //   return this.avatarUrl;
-  // }
-
+  /**
+   * Returns the avatar URL of the user.
+   * @returns {string} The avatar URL.
+   */
   avatarURL() {
     return this.avatarUrl;
   }

package/structures/Util.js

@@ -1,9 +1,4 @@
-/**
- * MessageEmbed - Criar embeds
- * @class
- */
 class MessageEmbed {
-    // Limites rigorosos (mesmo do backend)
     static LIMITS = {
         TITLE: 256,
         DESCRIPTION: 4096,
@@ -15,12 +10,43 @@ class MessageEmbed {
         URL_MAX: 2048
     };
 
-    // Regex para URLs válidas (HTTP/HTTPS apenas)
     static URL_REGEX = /^https?:\/\/(www\.)?[-a-zA-Z0-9@:%._\+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b([-a-zA-Z0-9()@:%_\+.~#?&//=]*)$/;
-
-    // Regex para cores hex
     static COLOR_REGEX = /^#[0-9A-Fa-f]{6}$/;
 
+    /**
+     * Creates a new MessageEmbed instance.
+     * 
+     * @param {Object} [data] - Initial embed data
+     * @param {string} data.color - Embed color in hex format (#RRGGBB)
+     * @param {Object} data.author - Author options
+     * @param {string} data.author.name - Author name
+     * @param {string} data.author.iconUrl - Author icon URL
+     * @param {string} data.author.url - Author URL
+     * @param {string} data.title - Embed title
+     * @param {string} data.url - Embed title URL
+     * @param {string} data.description - Embed description
+     * @param {Array<Object>} data.fields - Array of embed fields
+     * @param {string} data.thumbnail - Thumbnail image URL
+     * @param {string} data.image - Main image URL
+     * @param {Object} data.footer - Footer data
+     * @param {string} data.footer.text - Footer text
+     * @param {string} data.footer.iconUrl - Footer icon URL
+     * @param {Date|number|string} data.timestamp - Timestamp
+     * 
+     * @example
+     * const embed = new Client.MessageEmbed()
+     *   .setColor('#FF0000')
+     *   .setAuthor('Bot Name', 'https://example.com/icon.png')
+     *   .setTitle('Hello World')
+     *   .setURL('https://example.com')
+     *   .setDescription('This is a complete embed example.')
+     *   .addField('Field 1', 'Some value here')
+     *   .addField('Inline Field', 'Inline value', true)
+     *   .setThumbnail('https://example.com/thumb.png')
+     *   .setImage('https://example.com/image.png')
+     *   .setFooter('Footer text', 'https://example.com/footer.png')
+     *   .setTimestamp();
+     */
     constructor(data = {}) {
         this.color = null;
         this.author = null;
@@ -39,7 +65,7 @@ class MessageEmbed {
         if (data.title) this.setTitle(data.title);
         if (data.url) this.setURL(data.url);
         if (data.description) this.setDescription(data.description);
-        if (data.fields) data.fields.forEach(f => this.addField(f.name, f.value, f.inline));
+        if (data.fields) data.fields.forEach(f => this.addField(f.name, f.value, f?.inline));
         if (data.thumbnail) this.setThumbnail(data.thumbnail);
         if (data.image) this.setImage(data.image);
         if (data.footer) this.setFooter(data.footer.text, data.footer.iconUrl);
@@ -47,7 +73,11 @@ class MessageEmbed {
     }
 
     /**
-     * Valida se string não é vazia e não é JSON disfarçado
+     * Checks if a string is valid: non-empty, not disguised JSON, and optionally within a maximum length.
+     * @param {string} value - The string to validate.
+     * @param {number} [maxLength=null] - Optional maximum allowed length for the string.
+     * @returns {boolean} True if the string is valid.
+     * @throws {Error} Throws if the string is empty, too long, or contains JSON content.
      */
     static _isValidString(value, maxLength = null) {
         if (typeof value !== 'string') {
@@ -78,7 +108,10 @@ class MessageEmbed {
     }
 
     /**
-     * Valida URL
+     * Validates a URL string against allowed format and dangerous protocols.
+     * @param {string} url - The URL to validate.
+     * @returns {boolean} True if the URL is valid.
+     * @throws {Error} Throws if the URL is invalid, too long, or contains dangerous protocols.
      */
     static _isValidUrl(url) {
         if (typeof url !== 'string') {
@@ -104,7 +137,9 @@ class MessageEmbed {
     }
 
     /**
-     * Valida cor hex
+     * Sanitizes a string by removing dangerous or non-printable characters.
+     * @param {string} str - The string to sanitize.
+     * @returns {string} The sanitized string.
      */
     static _isValidColor(color) {
         if (typeof color !== 'string') return false;
@@ -121,8 +156,9 @@ class MessageEmbed {
     }
 
     /**
-     * Define a cor do embed
-     * @param {string|number} color - Cor em hexadecimal (#RRGGBB) ou número
+     * Sets the embed color.
+     *
+     * @param {string|number} color Hex color (#RRGGBB) or a numeric value
      * @returns {MessageEmbed}
      */
     setColor(color) {
@@ -135,7 +171,7 @@ class MessageEmbed {
         } else if (typeof color === 'string') {
             let hexColor = color.startsWith('#') ? color : `#${color}`;
             hexColor = hexColor.toUpperCase();
-            
+
             if (!MessageEmbed._isValidColor(hexColor)) {
                 throw new Error('Color must be a valid hex color (e.g., #FF0000 or FF0000)');
             }
@@ -147,16 +183,17 @@ class MessageEmbed {
     }
 
     /**
-     * Define o autor do embed
-     * @param {string} name - Nome do autor
-     * @param {string} iconUrl - URL do ícone (opcional)
-     * @param {string} url - URL do autor (opcional)
+     * Sets the embed author.
+     *
+     * @param {string} name Author name
+     * @param {string} [iconUrl] Author icon URL
+     * @param {string} [url] Author link URL
      * @returns {MessageEmbed}
      */
     setAuthor(name, iconUrl = null, url = null) {
         MessageEmbed._isValidString(name, MessageEmbed.LIMITS.AUTHOR_NAME);
-        
-        this.author = { 
+
+        this.author = {
             name: MessageEmbed._sanitizeString(name)
         };
 
@@ -174,8 +211,9 @@ class MessageEmbed {
     }
 
     /**
-     * Define o título do embed
-     * @param {string} title - Título do embed
+     * Sets the embed title.
+     *
+     * @param {string} title Title text
      * @returns {MessageEmbed}
      */
     setTitle(title) {
@@ -185,8 +223,9 @@ class MessageEmbed {
     }
 
     /**
-     * Define a URL do título
-     * @param {string} url - URL
+     * Sets the title URL.
+     *
+     * @param {string} url Valid HTTP/HTTPS URL
      * @returns {MessageEmbed}
      */
     setURL(url) {
@@ -196,8 +235,9 @@ class MessageEmbed {
     }
 
     /**
-     * Define a descrição do embed
-     * @param {string} description - Descrição
+     * Sets the embed description.
+     *
+     * @param {string} description Description text
      * @returns {MessageEmbed}
      */
     setDescription(description) {
@@ -207,10 +247,11 @@ class MessageEmbed {
     }
 
     /**
-     * Adiciona um campo ao embed
-     * @param {string} name - Nome do campo
-     * @param {string} value - Valor do campo
-     * @param {boolean} inline - Se o campo deve ser inline
+     * Adds a field to the embed.
+     *
+     * @param {string} name Field name
+     * @param {string} value Field value
+     * @param {boolean} [inline=false] Whether the field should be inline
      * @returns {MessageEmbed}
      */
     addField(name, value, inline = false) {
@@ -233,18 +274,19 @@ class MessageEmbed {
             throw new Error('Field inline must be a boolean');
         }
 
-        this.fields.push({ 
-            name: MessageEmbed._sanitizeString(name), 
-            value: MessageEmbed._sanitizeString(value), 
-            inline 
+        this.fields.push({
+            name: MessageEmbed._sanitizeString(name),
+            value: MessageEmbed._sanitizeString(value),
+            inline
         });
 
         return this;
     }
 
     /**
-     * Adiciona múltiplos campos ao embed
-     * @param {...Object} fields - Campos a serem adicionados
+     * Adds multiple fields at once.
+     *
+     * @param {...Object} fields Array of field objects
      * @returns {MessageEmbed}
      */
     addFields(...fields) {
@@ -264,8 +306,9 @@ class MessageEmbed {
     }
 
     /**
-     * Define a thumbnail do embed
-     * @param {string} url - URL da thumbnail
+     * Sets the thumbnail image.
+     *
+     * @param {string} url Thumbnail URL
      * @returns {MessageEmbed}
      */
     setThumbnail(url) {
@@ -275,8 +318,9 @@ class MessageEmbed {
     }
 
     /**
-     * Define a imagem do embed
-     * @param {string} url - URL da imagem
+     * Sets the main embed image.
+     *
+     * @param {string} url Image URL
      * @returns {MessageEmbed}
      */
     setImage(url) {
@@ -286,15 +330,16 @@ class MessageEmbed {
     }
 
     /**
-     * Define o footer do embed
-     * @param {string} text - Texto do footer
-     * @param {string} iconUrl - URL do ícone (opcional)
+     * Sets the embed footer.
+     *
+     * @param {string} text Footer text
+     * @param {string} [iconUrl] Footer icon URL
      * @returns {MessageEmbed}
      */
     setFooter(text, iconUrl = null) {
         MessageEmbed._isValidString(text, MessageEmbed.LIMITS.FOOTER_TEXT);
-        
-        this.footer = { 
+
+        this.footer = {
             text: MessageEmbed._sanitizeString(text)
         };
 
@@ -307,8 +352,9 @@ class MessageEmbed {
     }
 
     /**
-     * Define o timestamp do embed
-     * @param {Date|number|string} timestamp - Timestamp (Date, timestamp ou ISO string)
+     * Sets the embed timestamp.
+     *
+     * @param {Date|number|string} [timestamp] Date object, timestamp number or ISO string
      * @returns {MessageEmbed}
      */
     setTimestamp(timestamp = null) {
@@ -339,8 +385,9 @@ class MessageEmbed {
     }
 
     /**
-     * Converte o embed para JSON (formato esperado pela API)
-     * @returns {Object}
+     * Converts the embed into a JSON object compatible with the BenioCord API.
+     *
+     * @returns {Object} Embed JSON representation
      */
     toJSON() {
         // Valida antes de converter
@@ -363,7 +410,8 @@ class MessageEmbed {
     }
 
     /**
-     * Converte o embed para texto simples (fallback)
+     * Converts the embed into a plain-text fallback format.
+     *
      * @returns {string}
      */
     toText() {
@@ -396,9 +444,10 @@ class MessageEmbed {
     }
 
     /**
-     * Valida se o embed está correto e dentro dos limites
-     * @returns {boolean}
-     * @throws {Error}
+     * Validates the embed content and size limits.
+     *
+     * @throws {Error} If the embed contains invalid data
+     * @returns {boolean} Whether the embed is valid
      */
     validate() {
         // Pelo menos título ou descrição deve existir