@hieuxyz/rpc 1.1.0 → 1.2.0

package/README.md

@@ -1,10 +1,10 @@
 # @hieuxyz/rpc
 
 [![NPM Version](https://img.shields.io/npm/v/@hieuxyz/rpc.svg)](https://www.npmjs.com/package/@hieuxyz/rpc)
-[![License](https://img.shields.io/npm/l/@hieuxyz/rpc.svg)](https://github.com/hieuxyz/rpc/blob/main/LICENSE)
+[![License](https://img.shields.io/npm/l/@hieuxyz/rpc.svg)](https://github.com/hieuxyz00/hieuxyz_rpc/blob/master/LICENSE)
 [![Downloads](https://img.shields.io/npm/dt/@hieuxyz/rpc.svg)](https://www.npmjs.com/package/@hieuxyz/rpc)
 
-An easy-to-use Discord Rich Presence (RPC) library built for the Node.js environment using TypeScript. This library is designed to simplify the creation and management of custom RPC states for Discord user accounts.
+An easy-to-use and powerful Discord Rich Presence (RPC) library built for the Node.js environment using TypeScript. This library is designed to simplify the creation and management of custom RPC states for Discord user accounts.
 
 > [!WARNING]
 > **I don't take any responsibility for blocked Discord accounts that used this module.**
@@ -17,7 +17,6 @@ An easy-to-use Discord Rich Presence (RPC) library built for the Node.js environ
 
 -   **Flexible Builder Pattern:** Easily build your RPC state with intuitive chainable methods.
 -   **Easy to use:** The `Client` class abstracts away all the complex connection and setup logic, letting you get started with just a few lines of code.
--   **Auto Resume:** Built-in auto reconnect and session recovery mechanism in case of network failure, ensuring your RPC is always stable.
 
 ## Install
 
@@ -65,17 +64,21 @@ async function start() {
         .setName("Visual Studio Code")
         .setDetails("Developing a new library")
         .setState("Workspace: @hieuxyz/rpc")
-        .setPlatform('desktop') // 'desktop', 'xbox', 'ps5', etc.
+        .setPlatform('desktop')
         .setType(0) // 0: Playing
         .setTimestamps(Date.now())
         .setParty(1, 5)
         .setLargeImage("https://i.ibb.co/MDP0hfTM/typescript.png", "TypeScript")
-        .setSmallImage(new LocalImage(path.join(__dirname, 'vscode.png')), "VS Code");
+        .setSmallImage(new LocalImage(path.join(__dirname, 'vscode.png')), "VS Code")
+        .setButtons([
+            { label: 'View on GitHub', url: 'https://github.com/hieuxyz00/hieuxyz_rpc' },
+            { label: 'View on NPM', url: 'https://www.npmjs.com/package/@hieuxyz/rpc' }
+        ]);
 
     await client.rpc.build();
     logger.info("Initial RPC has been set!");
 
-    setTimeout(() => {
+    setTimeout(async () => {
         logger.info("Clearing RPC and resetting builder...");
         client.rpc.clear();
 
@@ -84,7 +87,7 @@ async function start() {
             .setDetails("Thinking about the next feature")
             .setLargeImage("mp:external/dZwPAoMNVxT5qYqecH3Mfgxv1RQEdtGBU8nAspOcAo4/https/c.tenor.com/fvuYGhI1vgUAAAAC/tenor.gif", "Coffee Time");
         
-        client.rpc.build();
+        await client.rpc.build();
         logger.info("A new RPC has been set after clearing.");
 
     }, 20000);
@@ -102,11 +105,32 @@ start().catch(err => {
 });
 ```
 
+## Advanced Usage
+
+### Client Spoofing
+
+You can make it appear as though you are using Discord from a different device (e.g., mobile) by providing the `properties` option during client initialization.
+
+```typescript
+import { Client } from '@hieuxyz/rpc';
+
+const client = new Client({
+    token: "YOUR_TOKEN",
+    properties: {
+        os: 'Android',
+        browser: 'Discord Android',
+        device: 'Android16',
+    }
+});
+
+// ...
+```
+
 ## Get Token ?
 
 - Based: [findByProps](https://discord.com/channels/603970300668805120/1085682686607249478/1085682686607249478)
 
-<strong>Run code (Discord Console - [Ctrl + Shift + I])</strong>
+**Run code (Discord Console - [Ctrl + Shift + I])**
 
 ```js
 window.webpackChunkdiscord_app.push([
@@ -140,16 +164,22 @@ This is the main starting point.
 -   `new Client(options)`: Create a new instance.
     -   `options.token` (required): Your Discord user token.
     -   `options.apiBaseUrl` (optional): Override the default image proxy service URL.
-    -   `options.alwaysReconnect` (optional): If `true`, the client will attempt to reconnect even after a normal close (e.g., from `client.close()` or a Discord-initiated close). Defaults to `false`.
+    -   `options.alwaysReconnect` (optional): If `true`, the client will attempt to reconnect even after a normal close. Defaults to `false`.
+    -   `options.properties` (optional): An object to spoof client properties (OS, browser, device).
+    -   `options.connectionTimeout` (optional): Timeout in milliseconds for the initial connection. Defaults to `30000`.
 -   `client.run()`: Start connecting to Discord Gateway.
 -   `client.rpc`: Access the instance of `HieuxyzRPC` to build the state.
 -   `client.close(force?: boolean)`: Closes the connection to the Discord Gateway.
-    -   `force` (optional, boolean): If set to `true`, the client will close permanently and will not attempt to reconnect, overriding the `alwaysReconnect` option. Defaults to `false`.
+    -   `force` (optional, boolean): If `true`, the client closes permanently and will not reconnect.
 
 ### Class `HieuxyzRPC`
 
 Main builder class for RPC.
 
+#### Getter Properties
+-   `.largeImageUrl`: Returns the resolved URL for the large image, or `null`.
+-   `.smallImageUrl`: Returns the resolved URL for the small image, or `null`.
+
 #### Setter Methods
 -   `.setName(string)`: Sets the activity name (first line).
 -   `.setDetails(string)`: Sets the activity details (second line).
@@ -158,33 +188,37 @@ Main builder class for RPC.
 -   `.setParty(current, max)`: Sets the party information.
 -   `.setLargeImage(RpcImage, text?)`: Sets the large image and its tooltip text.
 -   `.setSmallImage(RpcImage, text?)`: Sets the small image and its tooltip text.
--   `.setButtons(buttons[])`: Sets up to two clickable buttons.
+-   `.setButtons(buttons[])`: Sets up to two clickable buttons. Each button is an object `{ label: string, url: string }`.
+-   `.setSecrets({ join?, spectate?, match? })`: Sets secrets for game invites.
+-   `.setSyncId(string)`: Sets the sync ID, used for features like Spotify track syncing.
+-   `.setFlags(number)`: Sets activity flags (e.g., for instanced games). Use the `ActivityFlags` enum.
 -   `.setPlatform(platform)`: Sets the platform (`'desktop'`, `'xbox'`, etc.).
 -   `.setInstance(boolean)`: Marks the activity as a specific, joinable instance.
 -   `.setApplicationId(string)`: Sets a custom Application ID.
 -   `.setStatus('online' | ...)`: Sets the user's presence status.
 
 #### Clearer Methods
--   `.clearDetails()`: Removes the activity details.
--   `.clearState()`: Removes the activity state.
--   `.clearTimestamps()`: Removes the timestamps.
--   `.clearParty()`: Removes the party information.
--   `.clearLargeImage()`: Removes the large image and its text.
--   `.clearSmallImage()`: Removes the small image and its text.
+-   `.clearDetails()`: Removes activity details.
+-   `.clearState()`: Removes activity state.
+-   `.clearTimestamps()`: Removes timestamps.
+-   `.clearParty()`: Removes party information.
+-   `.clearLargeImage()`: Removes the large image and text.
+-   `.clearSmallImage()`: Removes the small image and text.
 -   `.clearButtons()`: Removes all buttons.
+-   `.clearSecrets()`: Removes all secrets.
 -   `.clearInstance()`: Removes the instance flag.
 
 #### Core Methods
 -   `.build()`: Builds and sends the presence payload to Discord.
--   `.updateRPC()`: Builds and sends an updated presence payload. (Alias for `build()`).
--   `.clear()`: Clears the entire Rich Presence from the user's profile and resets the builder to its default state.
+-   `.updateRPC()`: Alias for `build()`.
+-   `.clear()`: Clears the Rich Presence from the user's profile and resets the builder.
 
 ### Types of images
 
--   `new ExternalImage(url)`: Use image from an external URL (will be proxy).
+-   `new ExternalImage(url)`: Use an image from an external URL (will be proxied).
 -   `new LocalImage(filePath, fileName?)`: Upload a photo from your device.
--   `new RawImage(assetKey)`: Use an existing asset key directly.
--   `new DiscordImage(key)`: Use assets already on Discord.
+-   `new RawImage(assetKey)`: Use an existing asset key directly (e.g., `spotify:track_id`).
+-   `new DiscordImage(key)`: Use assets already on Discord (e.g., `mp:attachments/...`).
 
 ## Author
 

package/dist/hieuxyz/Client.d.ts

@@ -1,4 +1,6 @@
 import { HieuxyzRPC } from './rpc/HieuxyzRPC';
+import { ClientProperties } from './gateway/entities/identify';
+import { DiscordUser } from './gateway/entities/types';
 /**
  * Option to initialize Client.
  */
@@ -12,6 +14,16 @@ export interface ClientOptions {
      * Defaults to false.
      */
     alwaysReconnect?: boolean;
+    /**
+     * (Optional) Client properties to send to Discord gateway.
+     * Used for client spoofing (e.g., appearing as on mobile).
+     */
+    properties?: ClientProperties;
+    /**
+     * (Optional) The timeout in milliseconds for the initial gateway connection.
+     * Defaults to 30000 (30 seconds).
+     */
+    connectionTimeout?: number;
 }
 /**
  * The main Client class for interacting with Discord Rich Presence.
@@ -28,27 +40,40 @@ export interface ClientOptions {
 export declare class Client {
     /**
      * Provides access to RPC constructor methods.
-     * Use this property to set your Rich Presence state details.
+     * Use this to set your Rich Presence state details.
      */
     readonly rpc: HieuxyzRPC;
+    /**
+     * Information about the logged-in user.
+     * Populated after run() resolves.
+     */
+    user: DiscordUser | null;
     private readonly websocket;
     private readonly imageService;
     private readonly token;
     /**
      * Create a new Client instance.
-     * @param options - Options to configure the client.
+     * @param {ClientOptions} options - Options to configure the client.
      * @throws {Error} If no token is provided in the options.
      */
     constructor(options: ClientOptions);
+    /**
+     * Displays information about the library.
+     */
+    private printAbout;
     /**
      * Connect to Discord Gateway and prepare the client for RPC updates.
      * This method must be called before sending any Rich Presence updates.
-     * @returns {Promise<void>} A promise will be resolved when the client is ready.
+     * @returns {Promise<DiscordUser>} A promise will be resolved when the client is ready.
      */
-    run(): Promise<void>;
+    run(): Promise<DiscordUser>;
+    private formatters;
+    private formatFlags;
+    private printDynamicTree;
+    private logUserProfile;
     /**
      * Close the connection to Discord Gateway.
-     * @param {boolean} [force=false] - If true, the client will close permanently and will not attempt to reconnect,
+     * @param {boolean} [force=false] - If true, the client closes permanently and will not reconnect.
      * even if `alwaysReconnect` is enabled. Defaults to false.
      */
     close(force?: boolean): void;

package/dist/hieuxyz/Client.js

@@ -5,6 +5,7 @@ const DiscordWebSocket_1 = require("./gateway/DiscordWebSocket");
 const HieuxyzRPC_1 = require("./rpc/HieuxyzRPC");
 const ImageService_1 = require("./rpc/ImageService");
 const logger_1 = require("./utils/logger");
+const types_1 = require("./gateway/entities/types");
 /**
  * The main Client class for interacting with Discord Rich Presence.
  * This is the starting point for creating and managing your RPC state.
@@ -20,15 +21,20 @@ const logger_1 = require("./utils/logger");
 class Client {
     /**
      * Provides access to RPC constructor methods.
-     * Use this property to set your Rich Presence state details.
+     * Use this to set your Rich Presence state details.
      */
     rpc;
+    /**
+     * Information about the logged-in user.
+     * Populated after run() resolves.
+     */
+    user = null;
     websocket;
     imageService;
     token;
     /**
      * Create a new Client instance.
-     * @param options - Options to configure the client.
+     * @param {ClientOptions} options - Options to configure the client.
      * @throws {Error} If no token is provided in the options.
      */
     constructor(options) {
@@ -39,23 +45,158 @@ class Client {
         this.imageService = new ImageService_1.ImageService(options.apiBaseUrl);
         this.websocket = new DiscordWebSocket_1.DiscordWebSocket(this.token, {
             alwaysReconnect: options.alwaysReconnect ?? false,
+            properties: options.properties,
+            connectionTimeout: options.connectionTimeout,
         });
         this.rpc = new HieuxyzRPC_1.HieuxyzRPC(this.websocket, this.imageService);
+        this.printAbout();
+    }
+    /**
+     * Displays information about the library.
+     */
+    printAbout() {
+        const version = '1.2.0';
+        console.log(`
+  _     _                               
+ | |__ (_) ___ _   ___  ___   _ ______  
+ | '_ \\| |/ _ \\ | | \\ \\/ / | | |_  /  
+ | | | | |  __/ |_| |>  <| |_| |/ /   
+ |_| |_|_|\\___|\\__,_/_/\\_\\\\__, /___|  
+                          |___/       
+  @hieuxyz/rpc v${version}
+  A powerful Discord Rich Presence library.
+  Developed by: hieuxyz
+        `);
     }
     /**
      * Connect to Discord Gateway and prepare the client for RPC updates.
      * This method must be called before sending any Rich Presence updates.
-     * @returns {Promise<void>} A promise will be resolved when the client is ready.
+     * @returns {Promise<DiscordUser>} A promise will be resolved when the client is ready.
      */
     async run() {
         this.websocket.connect();
         logger_1.logger.info('Waiting for Discord session to be ready...');
-        await this.websocket.readyPromise;
+        const user = await this.websocket.readyPromise;
+        this.user = user;
+        this.logUserProfile(user);
         logger_1.logger.info('Client is ready to send Rich Presence updates.');
+        return user;
+    }
+    formatters = {
+        email: (val) => (val ? `\x1b[90m<Hidden>\x1b[0m` : 'null'),
+        phone: (val) => (val ? `\x1b[90m<Hidden>\x1b[0m` : 'null'),
+        avatar: (val, parent) => {
+            if (!val)
+                return 'null';
+            const ext = val.startsWith('a_') ? 'gif' : 'png';
+            const userId = parent?.id;
+            const url = userId ? `https://cdn.discordapp.com/avatars/${userId}/${val}.${ext}` : '';
+            return `"${val}" ${url ? `(\x1b[34m${url}\x1b[0m)` : ''}`;
+        },
+        banner: (val, parent) => {
+            if (!val)
+                return 'null';
+            const ext = val.startsWith('a_') ? 'gif' : 'png';
+            const userId = parent?.id;
+            const url = userId ? `https://cdn.discordapp.com/banners/${userId}/${val}.${ext}` : '';
+            return `"${val}" ${url ? `(\x1b[34m${url}\x1b[0m)` : ''}`;
+        },
+        asset: (val) => {
+            const url = `https://cdn.discordapp.com/avatar-decoration-presets/${val}.png`;
+            return `"${val}" (\x1b[34m${url}\x1b[0m)`;
+        },
+        accent_color: (val) => `${val} (\x1b[33m#${val.toString(16).padStart(6, '0').toUpperCase()}\x1b[0m)`,
+        banner_color: (val) => `\x1b[33m${val}\x1b[0m`,
+        expires_at: (val) => (val ? `${val} (${new Date(val).toLocaleString()})` : 'Never'),
+        premium_type: (val) => {
+            const map = { 0: 'None', 1: 'Classic', 2: 'Nitro', 3: 'Basic' };
+            return `${val} (\x1b[32m${map[val] || 'Unknown'}\x1b[0m)`;
+        },
+        flags: (val) => this.formatFlags(val),
+        public_flags: (val) => this.formatFlags(val),
+        purchased_flags: (val) => `\x1b[33m${val}\x1b[0m`,
+    };
+    formatFlags(flags) {
+        const flagNames = [];
+        if (flags & types_1.UserFlags.STAFF)
+            flagNames.push('Staff');
+        if (flags & types_1.UserFlags.PARTNER)
+            flagNames.push('Partner');
+        if (flags & types_1.UserFlags.HYPESQUAD)
+            flagNames.push('HypeSquad');
+        if (flags & types_1.UserFlags.BUG_HUNTER_LEVEL_1)
+            flagNames.push('BugHunter I');
+        if (flags & types_1.UserFlags.HYPESQUAD_ONLINE_HOUSE_1)
+            flagNames.push('Bravery');
+        if (flags & types_1.UserFlags.HYPESQUAD_ONLINE_HOUSE_2)
+            flagNames.push('Brilliance');
+        if (flags & types_1.UserFlags.HYPESQUAD_ONLINE_HOUSE_3)
+            flagNames.push('Balance');
+        if (flags & types_1.UserFlags.PREMIUM_EARLY_SUPPORTER)
+            flagNames.push('EarlySupporter');
+        if (flags & types_1.UserFlags.BUG_HUNTER_LEVEL_2)
+            flagNames.push('BugHunter II');
+        if (flags & types_1.UserFlags.VERIFIED_DEVELOPER)
+            flagNames.push('VerifiedDev');
+        if (flags & types_1.UserFlags.CERTIFIED_MODERATOR)
+            flagNames.push('CertifiedMod');
+        if (flags & types_1.UserFlags.ACTIVE_DEVELOPER)
+            flagNames.push('ActiveDev');
+        return `${flags} \x1b[36m[${flagNames.length > 0 ? flagNames.join(', ') : 'None'}]\x1b[0m`;
+    }
+    printDynamicTree(obj, prefix = '') {
+        const entries = Object.entries(obj);
+        entries.forEach(([key, value], index) => {
+            const isLastItem = index === entries.length - 1;
+            const connector = isLastItem ? '└── ' : '├── ';
+            const childPrefix = prefix + (isLastItem ? '    ' : '│   ');
+            let displayValue = '';
+            let isObject = false;
+            if (value === null) {
+                displayValue = '\x1b[90mnull\x1b[0m';
+            }
+            else if (typeof value === 'object' && !Array.isArray(value)) {
+                isObject = true;
+                console.log(`${prefix}${connector}\x1b[1m${key}\x1b[0m`);
+                this.printDynamicTree(value, childPrefix);
+            }
+            else if (Array.isArray(value)) {
+                if (value.length > 0 && typeof value[0] !== 'object') {
+                    displayValue = `[ ${value.join(', ')} ]`;
+                }
+                else {
+                    displayValue = `[Array(${value.length})]`;
+                }
+            }
+            else {
+                if (this.formatters[key]) {
+                    displayValue = this.formatters[key](value, obj);
+                }
+                else {
+                    if (typeof value === 'string')
+                        displayValue = `"\x1b[32m${value}\x1b[0m"`;
+                    else if (typeof value === 'boolean')
+                        displayValue = value ? '\x1b[32mtrue\x1b[0m' : '\x1b[31mfalse\x1b[0m';
+                    else if (typeof value === 'number')
+                        displayValue = `\x1b[33m${value}\x1b[0m`;
+                    else
+                        displayValue = String(value);
+                }
+            }
+            if (!isObject) {
+                console.log(`${prefix}${connector}${key}: ${displayValue}`);
+            }
+        });
+    }
+    logUserProfile(user) {
+        logger_1.logger.info('-> User Data:');
+        this.printDynamicTree(user);
+        /*logger.info('-> Raw JSON:');
+        console.log(JSON.stringify(user));*/
     }
     /**
      * Close the connection to Discord Gateway.
-     * @param {boolean} [force=false] - If true, the client will close permanently and will not attempt to reconnect,
+     * @param {boolean} [force=false] - If true, the client closes permanently and will not reconnect.
      * even if `alwaysReconnect` is enabled. Defaults to false.
      */
     close(force = false) {

package/dist/hieuxyz/gateway/DiscordWebSocket.d.ts

@@ -1,6 +1,9 @@
-import { PresenceUpdatePayload } from './entities/types';
+import { ClientProperties } from './entities/identify';
+import { PresenceUpdatePayload, DiscordUser } from './entities/types';
 interface DiscordWebSocketOptions {
     alwaysReconnect: boolean;
+    properties?: ClientProperties;
+    connectionTimeout?: number;
 }
 /**
  * Manage WebSocket connections to Discord Gateway.
@@ -17,16 +20,21 @@ export declare class DiscordWebSocket {
     private options;
     private isReconnecting;
     private permanentClose;
+    private connectTimeout;
     private resolveReady;
+    /**
+     * Current logged in user info.
+     */
+    user: DiscordUser | null;
     /**
      * A promise will be resolved when the Gateway connection is ready.
      * and received the READY event.
      */
-    readyPromise: Promise<void>;
+    readyPromise: Promise<DiscordUser>;
     /**
      * Create a DiscordWebSocket instance.
-     * @param token - Discord user token for authentication.
-     * @param options - Configuration options for the WebSocket client.
+     * @param {string} token - Discord user token for authentication.
+     * @param {DiscordWebSocketOptions} options - Configuration options for the WebSocket client.
      * @throws {Error} If the token is invalid.
      */
     constructor(token: string, options: DiscordWebSocketOptions);
@@ -37,6 +45,7 @@ export declare class DiscordWebSocket {
      * If there was a previous session, it will try to resume.
      */
     connect(): void;
+    private handleClose;
     private onMessage;
     private startHeartbeating;
     private sendHeartbeat;
@@ -44,13 +53,13 @@ export declare class DiscordWebSocket {
     private resume;
     /**
      * Send presence update payload to Gateway.
-     * @param presence - Payload update status to send.
+     * @param {PresenceUpdatePayload} presence - Payload update status to send.
      */
     sendActivity(presence: PresenceUpdatePayload): void;
     private sendJson;
     /**
      * Closes the WebSocket connection.
-     * @param force If true, prevents any automatic reconnection attempts.
+     * @param {boolean} force If true, prevents any automatic reconnection attempts.
      */
     close(force?: boolean): void;
     private cleanupHeartbeat;