@imaentity/selfjs 4.0.1 → 4.1.0

package/docs.md

@@ -17,8 +17,6 @@ npm install @imaentity/selfjs
 const self = require("@imaentity/selfjs");
 ```
 
----
-
 # Constants
 
 ## `Status`
@@ -34,8 +32,6 @@ Status.CUSTOM_STATUS  // 4
 Status.COMPETING      // 5
 ```
 
----
-
 # Functions
 
 ## `validateToken(token)`
@@ -67,14 +63,10 @@ else
     console.log("Invalid token");
 ```
 
----
-
 ## `createToken(options)`
 
-Attempts to log into a Discord account using an email and password.
-
-If MFA is not enabled, the returned object contains the token immediately.
-
+Attempts to log into a Discord account using an email and password.  
+If MFA is not enabled, the returned object contains the token immediately.  
 If MFA is required, the returned object contains the available MFA methods and a `confirmMFA()` function.
 
 ### Parameters
@@ -136,15 +128,12 @@ if(!login.mfaRequired) {
 }
 ```
 
-> [!NOTE]
+> [!NOTE]  
 > SMS MFA is currently unsupported.
 
----
-
 ## `snowflakeToUTC(snowflake)`
 
-Converts a Discord snowflake into a UTC timestamp.
-
+Converts a Discord snowflake into a UTC timestamp.  
 The returned timestamp is in milliseconds since Unix epoch.
 
 ### Parameters
@@ -167,12 +156,9 @@ const timestamp = self.snowflakeToUTC("1329029486758592595");
 console.log(new Date(timestamp));
 ```
 
----
-
 ## `UTCToSnowflake(timestamp)`
 
-Converts a UTC timestamp into a Discord snowflake.
-
+Converts a UTC timestamp into a Discord snowflake.  
 The generated snowflake only contains the timestamp portion. Worker ID, process ID, and sequence values are zero.
 
 ### Parameters
@@ -195,8 +181,6 @@ const snowflake = self.UTCToSnowflake(Date.now());
 console.log(snowflake);
 ```
 
----
-
 # Client
 
 `Client` provides an interface for connecting to Discord and interacting with the account.
@@ -229,8 +213,6 @@ const client = new self.Client({
 | `debugLogs`  | `Boolean` | `true`        | Enables SelfJS debug logging.           |
 | `intents`    | `Number`  | `null`        | Gateway intents, used for bot accounts. |
 
----
-
 # Properties
 
 ## `client.user`
@@ -243,8 +225,6 @@ console.log(client.user);
 
 This is populated after the `READY` event.
 
----
-
 ## `client.token`
 
 The token currently being used by the client.
@@ -253,8 +233,6 @@ The token currently being used by the client.
 console.log(client.token);
 ```
 
----
-
 ## `client.latency`
 
 The time between sending a heartbeat and receiving its acknowledgement.
@@ -265,8 +243,6 @@ console.log(client.latency);
 
 The value is in milliseconds.
 
----
-
 # Login
 
 ## `client.login(token)`
@@ -287,8 +263,6 @@ client.login(token);
 
 Once connected, events can be received using `client.on()`.
 
----
-
 # Events
 
 `Client` extends Node.js `EventEmitter`, so events can be listened to using `.on()`.
@@ -309,8 +283,6 @@ client.on("READY", data => {
 });
 ```
 
----
-
 ## `MESSAGE_CREATE`
 
 Emitted when a message is received.
@@ -350,8 +322,6 @@ client.on("MESSAGE_CREATE", message => {
 });
 ```
 
----
-
 ## `DISCONNECT`
 
 Emitted when the Gateway connection closes.
@@ -362,8 +332,6 @@ client.on("DISCONNECT", () => {
 });
 ```
 
----
-
 ## `INVALID_SESSION`
 
 Emitted when Discord invalidates the current session and it cannot be resumed.
@@ -374,8 +342,6 @@ client.on("INVALID_SESSION", () => {
 });
 ```
 
----
-
 # Messages
 
 ## `client.sendMessage(message)`
@@ -436,8 +402,6 @@ await client.sendMessage({
 });
 ```
 
----
-
 ## `client.editMessage(message)`
 
 Edits an existing message.
@@ -462,8 +426,6 @@ await client.editMessage({
 });
 ```
 
----
-
 ## `client.getMessages(options)`
 
 Gets recent messages from a channel.
@@ -493,8 +455,6 @@ const messages = await client.getMessages({
 });
 ```
 
----
-
 ## `client.ackMessage(message)`
 
 Acknowledges a message, removing its unread notification.
@@ -521,8 +481,6 @@ await client.ackMessage({
 });
 ```
 
----
-
 # Reactions
 
 ## `client.addReaction(options)`
@@ -547,8 +505,6 @@ await client.addReaction({
 });
 ```
 
----
-
 ## `client.removeReaction(options)`
 
 Removes the client's reaction from a message.
@@ -571,9 +527,25 @@ await client.removeReaction({
 });
 ```
 
----
+# Channels
 
-# Search
+## `client.getOpenChannels()`
+
+Gets the channels currently present in the account's DM list.  
+This can contain both direct messages and group DMs.
+
+### Returns
+
+```javascript
+Promise<Object>
+```
+
+### Example
+
+```javascript
+const channels = await client.getOpenChannels();
+console.log(channels);
+```
 
 ## `client.search(options)`
 
@@ -650,15 +622,16 @@ const results = await client.search({
 });
 ```
 
----
 
-# Channels
+## `client.createGroupDM(recipients)`
 
-## `client.getOpenChannels()`
+Creates a group DM with the specified users.
 
-Gets the channels currently present in the account's DM list.
+### Parameters
 
-This can contain both direct messages and group DMs.
+| Name         | Type            | Description                   |
+| ------------ | --------------- | ----------------------------- |
+| `recipients` | `Array<String>` | User IDs to add to the group. |
 
 ### Returns
 
@@ -666,14 +639,343 @@ This can contain both direct messages and group DMs.
 Promise<Object>
 ```
 
+The new channel object.
+
 ### Example
 
 ```javascript
-const channels = await client.getOpenChannels();
-console.log(channels);
+const group = await client.createGroupDM([
+    "123456789",
+    "987654321"
+]);
+
+console.log(group.id);
+```
+
+## `client.addToGroup(options)`
+
+Adds a user to a group DM. The logged-in account must be friends with the user.
+
+### Parameters
+
+| Name                 | Type     | Description          |
+| -------------------- | -------- | -------------------- |
+| `options.channel_id` | `String` | Group DM channel ID. |
+| `options.user_id`    | `String` | User ID to add.      |
+
+### Returns
+
+```javascript
+Promise<void>
+```
+
+### Example
+
+```javascript
+await client.addToGroup({
+    channel_id: "123456789",
+    user_id: "987654321"
+});
+```
+
+## `client.removeFromGroup(options)`
+
+Removes a user from a group DM. The logged-in account must own the group.
+
+### Parameters
+
+| Name                 | Type     | Description          |
+| -------------------- | -------- | -------------------- |
+| `options.channel_id` | `String` | Group DM channel ID. |
+| `options.user_id`    | `String` | User ID to remove.   |
+
+### Returns
+
+```javascript
+Promise<void>
+```
+
+### Example
+
+```javascript
+await client.removeFromGroup({
+    channel_id: "123456789",
+    user_id: "987654321"
+});
 ```
 
----
+## `client.transferGroup(options)`
+
+Transfers ownership of a group DM to another member.
+
+### Parameters
+
+| Name                 | Type     | Description                   |
+| -------------------- | -------- | ----------------------------- |
+| `options.channel_id` | `String` | Group DM channel ID.          |
+| `options.user_id`    | `String` | User ID to give ownership to. |
+
+### Returns
+
+```javascript
+Promise<Object>
+```
+
+The updated channel object.
+
+### Example
+
+```javascript
+const group = await client.transferGroup({
+    channel_id: "123456789",
+    user_id: "987654321"
+});
+
+console.log(group.owner_id);
+```
+
+## `client.leaveGroup(options)`
+
+Leaves a group DM.
+
+### Parameters
+
+| Name                 | Type      | Description                                        |
+| -------------------- | --------- | -------------------------------------------------- |
+| `options.channel_id` | `String`  | Group DM channel ID.                               |
+| `options.silent`     | `Boolean` | If `true`, does not notify the group of the leave. |
+
+### Returns
+
+```javascript
+Promise<Object>
+```
+
+### Example
+
+```javascript
+await client.leaveGroup({
+    channel_id: "123456789",
+    silent: true
+});
+```
+
+## `client.startTyping(channel_id)`
+
+Starts the typing indicator in a channel.  
+The indicator lasts for 10 seconds. Calling this again before it expires resets the timer. Sending a message clears the indicator.
+
+### Parameters
+
+| Name         | Type     | Description                    |
+| ------------ | -------- | ------------------------------ |
+| `channel_id` | `String` | Channel ID to start typing in. |
+
+### Returns
+
+```javascript
+Promise<void>
+```
+
+### Example
+
+```javascript
+await client.startTyping("123456789");
+```
+
+## `client.pinMessage(options)`
+
+Pins a message in a channel.
+
+### Parameters
+
+| Name                 | Type     | Description |
+| -------------------- | -------- | ----------- |
+| `options.channel_id` | `String` | Channel ID. |
+| `options.message_id` | `String` | Message ID. |
+
+### Returns
+
+```javascript
+Promise<void>
+```
+
+### Example
+
+```javascript
+await client.pinMessage({
+    channel_id: "123456789",
+    message_id: "987654321"
+});
+```
+
+## `client.unpinMessage(options)`
+
+Unpins a message from a channel.
+
+### Parameters
+
+| Name                 | Type     | Description |
+| -------------------- | -------- | ----------- |
+| `options.channel_id` | `String` | Channel ID. |
+| `options.message_id` | `String` | Message ID. |
+
+### Returns
+
+```javascript
+Promise<void>
+```
+
+### Example
+
+```javascript
+await client.unpinMessage({
+    channel_id: "123456789",
+    message_id: "987654321"
+});
+```
+
+## `client.getChannelObject(channel_id)`
+
+Gets the current channel object using its ID.  
+This works for DMs, group DMs, server text channels, and server voice channels.
+
+### Parameters
+
+| Name         | Type     | Description |
+| ------------ | -------- | ----------- |
+| `channel_id` | `String` | Channel ID. |
+
+### Returns
+
+```javascript
+Promise<Object>
+```
+
+The current channel object.
+
+### Example
+
+```javascript
+const channel = await client.getChannelObject("123456789");
+
+console.log(channel);
+```
+
+## `client.getDMChannel(user_id)`
+
+Gets the channel object for DMs with a certain user
+Getting the channel object also opens the channel in the active DM list
+
+### Parameters
+
+| Name      | Type     | Description |
+| --------- | -------- | ----------- |
+| `user_id` | `String` | User ID.    |
+
+### Returns
+
+```javascript
+Promise<Object>
+```
+
+The DM channel object.
+
+### Example
+
+```javascript
+const channel = await client.getDMChannel("123456789");
+
+console.log(channel);
+```
+
+## `client.closeDMChannel(user_id)`
+
+Closes and hides the DM channel for a certain user from the active list
+
+### Parameters
+
+| Name      | Type     | Description |
+| --------- | -------- | ----------- |
+| `user_id` | `String` | User ID.    |
+
+### Returns
+
+```javascript
+Promise<Object>
+```
+
+The DM channel object.
+
+### Example
+
+```javascript
+const channel = await client.getDMChannel("123456789");
+
+console.log(channel);
+```
+
+# Users
+
+## `client.getUserProfile(options)`
+
+Gets a user's profile.  
+The request succeeds if at least one of these is true:
+
+* The client shares a server with the user.
+* The client is friends with the user.
+* The user has sent a friend request to the client.
+* The user is a bot.
+
+### Parameters
+
+| Name                                | Type      | Description                                    |
+| ----------------------------------- | --------- | ---------------------------------------------- |
+| `options`                           | `Object`  | Profile request options.                       |
+| `options.user_id`                   | `String`  | ID of the user to get.                         |
+| `options.with_mutual_guilds`        | `Boolean` | Include mutual servers. Defaults to `true`.    |
+| `options.with_mutual_friends`       | `Boolean` | Include mutual friends.                        |
+| `options.with_mutual_friends_count` | `Boolean` | Include the number of mutual friends.          |
+| `options.guild_id`                  | `String`  | Get the user's server profile for this server. |
+
+### Returns
+
+```javascript
+Promise<Object>
+```
+
+The user's profile.
+
+If none of the access conditions are met, Discord returns a `404` error.
+
+### Example
+
+```javascript
+const profile = await client.getUserProfile({
+    user_id: "123456789"
+});
+
+console.log(profile);
+```
+
+### Example with mutual friends
+
+```javascript
+const profile = await client.getUserProfile({
+    user_id: "123456789",
+    with_mutual_friends: true,
+    with_mutual_friends_count: true
+});
+```
+
+### Example with a server profile
+
+```javascript
+const profile = await client.getUserProfile({
+    user_id: "123456789",
+    guild_id: "987654321"
+});
+```
 
 # Status
 
@@ -738,8 +1040,6 @@ client.setStatus({
 });
 ```
 
----
-
 # Authentication
 
 ## `client.logout()`
@@ -758,8 +1058,6 @@ Promise<Object>
 await client.logout();
 ```
 
----
-
 # Connection
 
 ## `client.disconnect(code)`
@@ -786,8 +1084,6 @@ Or with a specific close code:
 client.disconnect(1000);
 ```
 
----
-
 # Complete Example
 
 ```javascript
@@ -819,8 +1115,6 @@ client.on("DISCONNECT", () => {
 client.login(process.env.DISCORD_TOKEN);
 ```
 
----
-
 # Exported API
 
 SelfJS currently exports:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@imaentity/selfjs",
-    "version": "4.0.1",
+    "version": "4.1.0",
     "description": "Breaking Discord's TOS to bot user accounts.",
     "main": "self.js",
     "repository": {

package/self.js

@@ -2,7 +2,7 @@
  * @name SelfJS
  * @description Breaking Discord's TOS to bot user accounts.
  * @author Entity
- * @version 4.0.1
+ * @version 4.1
  */
 
 const EventEmitter = require("events");
@@ -576,7 +576,9 @@ class Client extends EventEmitter {
      * Gets the channels active in the DM list of the user, channels can be both DMs and group chats
      * @returns {Promise<Object>} The list of channels open in the user's DM list
      */
-    getOpenChannels() { return this.#GET({path: "/users/@me/channels"}); }
+    getOpenChannels() {
+        return this.#GET({path: "/users/@me/channels"});
+    }
 
     /**
      * Closes the current session and disconnects from discord
@@ -720,6 +722,152 @@ class Client extends EventEmitter {
             query: {limit: options.limit, before: options.before}
         });
     }
+
+	/**
+	 * Creates a group DM with certain members
+	 * @param {Array<String>} recipients A list of user ids to add to the created group
+	 * @returns {Promise<Object>} The new channel object after creation
+	 */
+	createGroupDM(recipients) {
+		return this.#POST({path: `/users/@me/channels`, body: {recipients}});
+	}
+
+	/**
+	 * Removes a user from a group dm if the logged in account owns the group
+	 * @param {Object} options Options specifying which user to remove and from what group
+	 * @param {String} options.channel_id The id of the group to remove the user from
+	 * @param {String} options.user_id The id of the user to be removed from the group
+	 * @returns {Promise<void>} No content returned on success
+	 */
+	removeFromGroup(options) {
+		return this.#DELETE({path: `/channels/${options.channel_id}/recipients/${options.user_id}`});
+	}
+
+	/**
+	 * Adds a user to a group dm if the logged in account is friends with the user
+	 * @param {Object} options Options specifying which user to add and to what group
+	 * @param {String} options.channel_id The id of the group to add the user to
+	 * @param {String} options.user_id The id of the user to be added to the group
+	 * @returns {Promise<void>} No content returned on success
+	 */
+	addToGroup(options) {
+		return this.#PUT({path: `/channels/${options.channel_id}/recipients/${options.user_id}`});
+	}
+
+	/**
+	 * Transfers ownership of a group to another user if that user is in the group
+	 * @param {Object} options Options specifying which user to give owner and in what group
+	 * @param {String} options.channel_id The id of the group to be transfered
+	 * @param {String} options.user_id The id of the user to given ownership of the group
+	 * @returns {Promise<Object>} The new channel object after the transfer
+	 */
+	transferGroup(options) {
+		return this.#PATCH({
+			path: `/channels/${options.channel_id}`,
+			body: {owner: options.user_id}
+		});
+	}
+
+	/**
+	 * Leaves a group while optionally not notifying members of that group
+	 * @param {Object} options Options specifying what group to leave and if the leave should notify
+	 * @param {String} options.channel_id The id of the group to leave
+	 * @param {Boolean} [options.silent] If true, the group will not receive a leave notification
+	 * @returns {Promise<Object>} The new channel object after the group has been left
+	 */
+	leaveGroup(options) {
+		return this.#DELETE({
+			path: `/channels/${options.channel_id}`,
+			query: {silent: options.silent}
+		});
+	}
+
+	/**
+	 * Shows the typing indicator for other users in a certain channel for 10 seconds
+	 * Calling this again before the indicator expires resets the timer, while sending a message clears the indicator
+	 * @param {String} channel_id The id of the channel to start typing in
+	 * @returns {Promise<void>} No content returned on success
+	 */
+	startTyping(channel_id) {
+		return this.#POST({path: `/channels/${channel_id}/typing`});
+	}
+
+	/**
+	 * Pins a message to a certain channel
+	 * @param {Object} options Specifies the message and channel to pin it in
+	 * @param {String} options.channel_id The id of the channel to pin the message in
+	 * @param {String} options.message_id The id of the message to pin in the channel
+	 * @returns {Promise<void>} No content returned on success
+	 */
+	pinMessage(options) {
+		return this.#PUT({path: `/api/v10/channels/${options.channel_id}/pins/${options.message_id}`});
+	}
+
+	/**
+	 * Unpins a message from a certain channel
+	 * @param {Object} options Specifies the message and channel to unpin it from
+	 * @param {String} options.channel_id The id of the channel to unpin the message from
+	 * @param {String} options.message_id The id of the message to unpin from the channel
+	 * @returns {Promise<void>} No content returned on success
+	 */
+	unpinMessage(options) {
+		return this.#DELETE({path: `/api/v10/channels/${options.channel_id}/pins/${options.message_id}`});
+	}
+
+    /**
+     * Gets the current representation of a channel via its id
+     * Channels can be DMs, group DMs, server text, or server voice channels
+     * @param {String} channel_id
+     * @returns {Promise<Object>} The current channel object
+     */
+    getChannelObject(channel_id) {
+        return this.#GET({path: `/channels/${channel_id}`});
+    }
+
+    /**
+     * Gets the channel object for DMs with a certain user
+     * Getting the channel object also opens the channel in the active DM list
+     * @param {String} user_id The id of the user to get the DM channel of
+     * @returns {Promise<Object>} The DM channel object
+     */
+    getDMChannel(user_id) {
+        return this.#POST({path: "/users/@me/channels", body: {recipients: [user_id]}});
+    }
+
+    /**
+     * Closes and hides the DM channel for a certain user from the active list
+     * @param {String} user_id The id of the user to close the DM channel of
+     * @returns {Promise<Object>} Returns the channel after closing on success
+     */
+    async closeDMChannel(user_id) {
+        const channel = await this.getDMChannel(user_id);
+        if(!("id" in channel)) return null;
+        return this.#DELETE({path: `/channels/${channel.id}`});
+    }
+
+    /**
+     * Get a user's profile if one of the following is true:
+     * The client shares a server with the user, is friends with the user
+     * The user sent a friend request to the client, or the user is a bot
+     * @param {Object} options The options specifying what the response should contain
+     * @param {String} options.user_id The id of the user to request the profile of
+     * @param {Boolean} [options.with_mutual_servers] If true or absent, include mutual servers in the response
+     * @param {Boolean} [options.with_mutual_friends] If true, include mutual friends in the response
+     * @param {Boolean} [options.with_mutual_friends_count] If true, include the number of mutual friends in the response
+     * @param {String} [options.guild_id] If present respond with the server profile for this guild
+     * @returns {Promise<Object>} The user's profile on success, 404 error if no conditions were met
+     */
+    getUserProfile(options) {
+        return this.#GET({
+            path: `/users/${options.user_id}/profile`,
+            query: {
+                guild_id: options.guild_id,
+                with_mutual_guilds: options.with_mutual_servers,
+                with_mutual_friends: options.with_mutual_friends,
+                with_mutual_friends_count: options.with_mutual_friends_count
+            }
+        });
+    }
 }
 
 module.exports = {