discord-self-lite 0.1.9 → 0.1.11

package/README.md

@@ -45,126 +45,17 @@ client.on("messageCreate", async (message) => {
 
 ## API Reference
 
-### Client
+The full API documentation is available in the [`docs/api/`](docs/api/README.md) directory. Here are the core classes:
 
-```javascript
-const { Client } = require("discord-self-lite");
-const client = new Client();
-```
-
-#### Methods
-
-- `client.login(token)` - Login with user token
-- `client.getChannel(channelId)` - Get cached channel
-- `client.fetchChannel(channelId)` - Fetch channel from API
-- `client.fetchMessage(channelId, messageId)` - Fetch specific message
-
-#### Properties
-
-- `client.user` - Current user object (available after ready event)
-- `client.guilds` - Map of cached guild instances
-- `client.channels` - Map of cached channel instances
-- `client.sessionId` - Session ID from Discord
-
-#### Events
-
-- `ready` - Fired when client is ready
-- `messageCreate` - Fired when a message is created
-
-### User
-
-#### Methods
-
-- `user.setStatus(status)` - Set user status ('online', 'idle', 'dnd', 'invisible')
-- `user.setPresence(presence)` - Set full presence data
-- `user.setActivity(activity)` - Set user activity
-
-#### Properties
-
-- `user.id` - User ID
-- `user.username` - Username
-- `user.discriminator` - Discriminator (4-digit number)
-- `user.avatar` - Avatar hash
-
-### Message
-
-#### Methods
-
-- `message.reply(content, options)` - Reply to the message
-- `message.react(emoji)` - React to the message
-- `message.clickButton(identifier)` - Click a button on the message
-  - `identifier` can be:
-    - `null` or omitted: clicks first button
-    - `number`: clicks button at index (0-based)
-    - `string`: clicks button with custom ID
-
-#### Properties
-
-- `message.content` - Message content
-- `message.author` - Message author
-- `message.channel` - Message channel
-- `message.guild` - Message guild (null for DMs)
-- `message.components` - Message components (buttons, etc.)
-
-### Channel
-
-#### Methods
-
-- `channel.send(content, options)` - Send a message to the channel
-- `channel.fetchMessages(options)` - Fetch messages from the channel
-
-#### Properties
-
-- `channel.id` - Channel ID
-- `channel.name` - Channel name
-- `channel.type` - Channel type
-
-### Guild
-
-#### Methods
-
-- `guild.getChannels()` - Get cached channels for this guild
-- `guild.fetchChannels()` - Fetch all channels for this guild from API
-- `guild.getChannel(channelId)` - Get a specific channel from cache
-- `guild.fetchChannel(channelId)` - Fetch a specific channel from API
-
-#### Properties
-
-- `guild.id` - Guild ID
-- `guild.name` - Guild name
-- `guild.icon` - Guild icon hash
-- `guild.ownerId` - Guild owner ID
-
-### WebhookClient
-
-Send messages to Discord webhooks with support for embeds and more.
-
-```javascript
-const { WebhookClient } = require("discord-self-lite");
-const webhook = new WebhookClient("YOUR_WEBHOOK_URL", {
-  username: "My Bot",
-  avatarURL: "https://example.com/avatar.png",
-});
-```
-
-#### Constructor
-
-- `new WebhookClient(url, options)` - Create a webhook client
-  - `url` - Discord webhook URL
-  - `options.username` - Default username for messages
-  - `options.avatarURL` - Default avatar URL for messages
-
-#### Methods
-
-- `webhook.send(content, options)` - Send a message (supports text, embeds, and objects)
-- `webhook.edit(messageId, content, options)` - Edit a message
-- `webhook.delete(messageId)` - Delete a message
-- `webhook.fetchMessage(messageId)` - Fetch a message
-
-#### Static Methods
+- **[`Client`](docs/api/Client.md)** - Main entry point, connection manager, and cache storage.
+- **[`User`](docs/api/User.md) & [`ClientUser`](docs/api/ClientUser.md)** - Represents Discord users and the logged-in selfbot.
+- **[`Message`](docs/api/Message.md)** - Represents text messages, supports replying, reacting, and clicking buttons.
+- **[`Channel`](docs/api/Channel.md)** - Represents Text, DM, or Voice channels to fetch or send messages.
+- **[`Guild`](docs/api/Guild.md) & [`GuildMember`](docs/api/GuildMember.md)** - Represents Discord servers and their members.
+- **[`WebhookClient`](docs/api/WebhookClient.md)** - Standalone client to send requests via webhooks.
+- **[`Permissions`](docs/api/Permissions.md) & [`BitField`](docs/api/BitField.md)** - Utility classes for resolving and checking Discord permissions.
 
-- `WebhookClient.createEmbed(data)` - Create an embed object
-- `WebhookClient.parseURL(url)` - Parse webhook URL to get ID and token
+_Check the [Complete API Reference](docs/api/README.md) for full properties, methods, and examples of each._
 
 ## Examples
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "discord-self-lite",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Lightweight Discord selfbot library",
   "keywords": [
     "discord",
@@ -32,8 +32,7 @@
     "test": "eslint . && prettier --check .",
     "format": "prettier --write .",
     "fix": "eslint . --fix && prettier --write .",
-    "docs": "echo \"📚 Documentation available at docs/README.md\"",
-    "docs:html": "jsdoc -c jsdoc.conf.json"
+    "docs": "echo \"📚 Documentation available at docs/README.md\""
   },
   "repository": {
     "type": "git",

package/src/classes/Channel.js

@@ -55,6 +55,7 @@ class Channel {
    */
   async send(payload) {
     const data = await this.rest.sendMessage(this.id, payload);
+    if (!data) return null;
     return new Message(this.client, data);
   }
 

package/src/classes/Client.js

@@ -49,7 +49,27 @@ class Client extends EventEmitter {
   async login(token) {
     this.token = token;
     this.rest = new RestManager(this.token, this.options.apiVersion || 9);
-    await this.connect();
+
+    return new Promise((resolve, reject) => {
+      const onReady = () => {
+        this.removeListener("error", onError);
+        resolve();
+      };
+
+      const onError = (msg) => {
+        this.removeListener("ready", onReady);
+        reject(new Error(msg));
+      };
+
+      this.once("ready", onReady);
+      this.once("error", onError);
+
+      this.connect().catch((err) => {
+        this.removeListener("ready", onReady);
+        this.removeListener("error", onError);
+        reject(err);
+      });
+    });
   }
 
   /**
@@ -99,39 +119,63 @@ class Client extends EventEmitter {
   }
 
   /**
-   * Get channel from cache, or create empty instance if not cached
+   * Get channel from cache
    * @param {string} id - The channel ID
-   * @returns {Channel} The channel instance
+   * @returns {Channel|null} The cached channel instance or null
    */
   getChannel(id) {
-    if (!this.channels.has(id)) {
-      this.channels.set(id, new Channel(this, this.rest, id));
-    }
-    return this.channels.get(id);
+    return this.channels.get(id) || null;
   }
 
   /**
-   * Get guild from cache, or create empty instance if not cached
+   * Resolve channel from cache or fetch from API
+   * @param {string} id - The channel ID
+   * @returns {Promise<Channel>} The resolved channel instance
+   */
+  async resolveChannel(id) {
+    const cached = this.getChannel(id);
+    if (cached) return cached;
+    return await this.fetchChannel(id);
+  }
+
+  /**
+   * Get guild from cache
    * @param {string} id - The guild ID
-   * @returns {Guild} The guild instance
+   * @returns {Guild|null} The cached guild instance or null
    */
   getGuild(id) {
-    if (!this.guilds.has(id)) {
-      this.guilds.set(id, new Guild(this, this.rest, id));
-    }
-    return this.guilds.get(id);
+    return this.guilds.get(id) || null;
   }
 
   /**
-   * Get user from cache, or create lightweight instance if not cached
+   * Resolve guild from cache or fetch from API
+   * @param {string} id - The guild ID
+   * @returns {Promise<Guild>} The resolved guild instance
+   */
+  async resolveGuild(id) {
+    const cached = this.getGuild(id);
+    if (cached) return cached;
+    return await this.fetchGuild(id);
+  }
+
+  /**
+   * Get user from cache
    * @param {string} id - The user ID
-   * @returns {User} The User instance
+   * @returns {User|null} The cached user instance or null
    */
   getUser(id) {
-    if (!this.users.has(id)) {
-      this.users.set(id, new User(this, { id }));
-    }
-    return this.users.get(id);
+    return this.users.get(id) || null;
+  }
+
+  /**
+   * Resolve user from cache or fetch from API
+   * @param {string} id - The user ID
+   * @returns {Promise<User>} The resolved user instance
+   */
+  async resolveUser(id) {
+    const cached = this.getUser(id);
+    if (cached) return cached;
+    return await this.fetchUser(id);
   }
 
   /**

package/src/classes/Guild.js

@@ -44,7 +44,7 @@ class Guild {
   /**
    * Get a channel from this guild (from cache)
    * @param {string} channelId - The channel ID
-   * @returns {Channel} The channel instance
+   * @returns {Channel|null} The cached channel instance or null
    */
   getChannel(channelId) {
     const channel = this.client.getChannel(channelId);

package/src/classes/Message.js

@@ -1,4 +1,3 @@
-const WebSocketError = require("./WebSocketError");
 const User = require("./User");
 
 /**
@@ -38,11 +37,12 @@ class Message {
     this.mentions = this.mentions || [];
     this.mentionRoles = this.mentionRoles || [];
     this.reactions = this.reactions || [];
+    this.url = `https://discord.com/channels/${this.guildId ? this.guildId : "@me"}/${this.channelId}/${this.id}`;
   }
 
   /**
    * Get the channel this message was sent in
-   * @returns {Channel} The channel instance
+   * @returns {Channel|null} The cached channel instance, or null if not cached
    */
   get channel() {
     return this.client.getChannel(this.channelId);
@@ -89,11 +89,12 @@ class Message {
    * @returns {Promise<object>} The sent reply message data
    */
   async reply(payload) {
+    const channel = await this.client.resolveChannel(this.channelId);
     const replyPayload =
       typeof payload === "string"
         ? { content: payload, message_reference: { message_id: this.id } }
         : { ...payload, message_reference: { message_id: this.id } };
-    return await this.channel.send(replyPayload);
+    return await channel.send(replyPayload);
   }
 
   /**
@@ -159,8 +160,8 @@ class Message {
     const messageFlags = this.data.flags || 0;
 
     if (!this.client.sessionId) {
-      throw new WebSocketError(
-        "No session ID available - client not properly connected",
+      throw new Error(
+        "No session ID available - client not properly connected (yet).",
       );
     }
 
@@ -196,21 +197,18 @@ class Message {
    * Returns the referenced `Message` instance or `null` if not available.
    */
   async fetchReference() {
-    const ref = this.messageReference || this.data?.message_reference;
+    const ref = this.data?.message_reference;
     if (!ref) return null;
 
     const messageId = ref.messageId || ref.message_id;
     const channelId = ref.channelId || ref.channel_id || this.channelId;
     if (!messageId || !channelId) return null;
 
-    // Try to get channel from cache or fetch from API
-    let channel = this.client.getChannel(channelId);
-    if (!channel) {
-      try {
-        channel = await this.client.fetchChannel(channelId);
-      } catch {
-        return null;
-      }
+    let channel;
+    try {
+      channel = await this.client.resolveChannel(channelId);
+    } catch {
+      return null;
     }
 
     try {

package/src/connection/rest/RestManager.js

@@ -74,7 +74,7 @@ class RestManager {
       });
 
       console.log(
-        `⏸️ Suspending route ${routeKey} for 2 minutes (pre-emptive)`,
+        `⏸️  Suspending route ${routeKey} for 2 minutes (pre-emptive)`,
       );
 
       // Clear queued requests for this route
@@ -192,7 +192,7 @@ class RestManager {
           });
 
           console.log(
-            `⏸️ Suspending route ${routeKey} for 2 minutes (queue processing)`,
+            `⏸️  Suspending route ${routeKey} for 2 minutes (queue processing)`,
           );
 
           // Clear remaining queued requests for this route
@@ -267,15 +267,14 @@ class RestManager {
               `⏳ Global rate limit set, waiting ${retryAfter + 2000}ms`,
             );
           } else {
-            // Immediately suspend the route for 2 minutes on first 429
-            const suspensionTime = 2 * 60 * 1000;
+            const suspensionTime = retryAfter + 500;
             this.suspendedRoutes.set(routeKey, {
               suspendedUntil: Date.now() + suspensionTime,
               reason: `429 response on attempt ${attempt + 1}`,
             });
 
             console.log(
-              `⏸️ Suspending route ${routeKey} for 2 minutes (429 response)`,
+              `⏸️  Suspending route ${routeKey} for ${suspensionTime}ms (429 response)`,
             );
 
             // Clear queue for this route
@@ -353,6 +352,15 @@ class RestManager {
 
         return await response.json();
       } catch (error) {
+        // Do not retry on Missing Permissions (50013)
+        if (
+          error.name === "DiscordAPIError" &&
+          error.fullError &&
+          error.fullError.code === 50013
+        ) {
+          throw error;
+        }
+
         if (attempt === maxRetries - 1) {
           throw error;
         }

package/src/connection/ws/WebSocket.js

@@ -4,8 +4,6 @@ const Message = require("../../classes/Message");
 const Guild = require("../../classes/Guild");
 const Channel = require("../../classes/Channel");
 const ClientUser = require("../../classes/ClientUser");
-const WebSocketError = require("../../classes/WebSocketError");
-
 class DiscordWebSocket extends EventEmitter {
   constructor(client, token, options = {}) {
     super();
@@ -31,7 +29,7 @@ class DiscordWebSocket extends EventEmitter {
     this.ws = new WebSocket(this.gatewayUrl);
 
     this.ws.on("open", () => {
-      console.log("WebSocket connected");
+      this.client.emit("debug", "WebSocket connected");
       this.client.emit("connected");
     });
 
@@ -40,23 +38,47 @@ class DiscordWebSocket extends EventEmitter {
     });
 
     this.ws.on("close", (code, reason) => {
-      console.log(`WebSocket closed: ${code} - ${reason}`);
+      this.client.emit("debug", `WebSocket closed: ${code} - ${reason}`);
       this.ready = false;
       if (this.heartbeatInterval) {
         clearInterval(this.heartbeatInterval);
         this.heartbeatInterval = null;
       }
       this.client.emit("disconnected", code, reason);
+      const terminalCodes = [4004, 4010, 4011, 4012, 4013, 4014];
+
+      if (terminalCodes.includes(code)) {
+        if (code === 4004) {
+          try {
+            if (this.ws) this.ws.terminate();
+          } catch {
+            /* ignore */
+          }
+          this.ws = null;
+          this.client.emit(
+            "error",
+            `Authentication failed (close code ${code}). Please check your token and try again.`,
+          );
+          return;
+        }
+
+        this.client.emit(
+          "debug",
+          `Terminal error received (${code}). Connection will not be restarted. (Reason: ${reason})`,
+        );
+        return;
+      }
+
       if (code !== 1000) {
-        // Not a clean close
         this.reconnect();
       }
     });
 
     this.ws.on("error", (error) => {
-      const wsError = new WebSocketError(`WebSocket error: ${error.message}`);
-      console.error(wsError);
-      this.client.emit("error", wsError);
+      this.client.emit(
+        "error",
+        `WebSocket error: ${error && error.message ? error.message : String(error)}`,
+      );
     });
   }
 
@@ -87,7 +109,7 @@ class DiscordWebSocket extends EventEmitter {
         this.handleDispatch(message);
         break;
       default:
-        console.log("Unhandled op:", message.op);
+        this.client.emit("debug", `Unhandled op: ${message.op}`);
     }
   }
 
@@ -185,9 +207,9 @@ class DiscordWebSocket extends EventEmitter {
         const member = new GuildMember(this.client, memberData, guild);
         guild._members.set(this.client.user.id, member);
       } catch (err) {
-        console.warn(
-          `Failed to fetch member for guild ${guild.id}:`,
-          err.message,
+        this.client.emit(
+          "debug",
+          `Failed to fetch member for guild ${guild.id}: ${err && err.message ? err.message : String(err)}`,
         );
       }
     }
@@ -197,16 +219,14 @@ class DiscordWebSocket extends EventEmitter {
 
   reconnect() {
     if (this.reconnectAttempts >= this.maxReconnectAttempts) {
-      const err = new WebSocketError("Max reconnect attempts reached");
-      console.error(err);
-      this.client.emit("error", err);
+      this.client.emit("error", "Max reconnect attempts reached");
       this.client.emit("maxReconnects");
       return;
     }
 
     this.reconnectAttempts++;
     const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts), 30000); // Exponential backoff
-    console.log(`Reconnecting in ${delay}ms...`);
+    this.client.emit("debug", `Reconnecting in ${delay}ms...`);
     setTimeout(() => {
       this.connect();
     }, delay);

package/src/classes/WebSocketError.js

@@ -1,18 +0,0 @@
-/**
- * Represents an error related to the WebSocket connection
- * @extends Error
- */
-class WebSocketError extends Error {
-  /**
-   * Create a new WebSocketError
-   * @param {string} message - The error message
-   * @param {number} [code] - The WebSocket close code
-   */
-  constructor(message, code) {
-    super(message);
-    this.name = "WebSocketError";
-    this.code = code;
-  }
-}
-
-module.exports = WebSocketError;