@hieuxyz/rpc 1.2.1 → 1.2.3

package/README.md

@@ -15,6 +15,7 @@ An easy-to-use and powerful Discord Rich Presence (RPC) library built for the No
 
 ## Outstanding features
 
+-   **Multi-RPC Support:** Display multiple activities simultaneously (e.g., Playing a game AND Listening to music) on a single client connection.
 -   **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.
 
@@ -105,6 +106,31 @@ start().catch(err => {
 });
 ```
 
+## Multi-RPC Usage
+
+You can display multiple statuses at once (Discord limits how these are shown, but the data is sent).
+
+```typescript
+// Configure the default RPC
+client.rpc
+    .setName("Visual Studio Code")
+    .setState("Coding...")
+    .setType(0); // Playing
+
+// Create a second RPC instance
+const musicRpc = client.createRPC();
+musicRpc
+    .setName("Spotify")
+    .setDetails("Listening to music")
+    .setApplicationId('12345678901234567') // A different ID is needed than the one already in use
+    .setType(2); // Listening
+
+await client.rpc.build();
+
+// To remove a specific RPC later and free memory:
+// client.removeRPC(musicRpc);
+```
+
 ## Advanced Usage
 
 ### Client Spoofing
@@ -169,8 +195,8 @@ This is the main starting point.
     -   `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.createRPC()`: Create a new separate RPC instance (Multi-RPC).
 -   `client.close(force?: boolean)`: Closes the connection to the Discord Gateway.
-    -   `force` (optional, boolean): If `true`, the client closes permanently and will not reconnect.
 
 ### Class `HieuxyzRPC`
 
@@ -179,23 +205,26 @@ 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`.
+-   `.currentStatus`: Returns the current status string (e.g. 'online').
 
 #### Setter Methods
 -   `.setName(string)`: Sets the activity name (first line).
 -   `.setDetails(string)`: Sets the activity details (second line).
 -   `.setState(string)`: Sets the activity state (third line).
--   `.setTimestamps(start?, end?)`: Sets the start and/or end times.
--   `.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.
+-   `.setStatus('online' | 'dnd' | 'idle' | 'invisible' | 'offline')`: Sets the user's presence status.
+-   `.setType(ActivityType | string | number)`: Sets the activity type (Playing, Listening, etc.).
+-   `.setTimestamps(start?, end?)`: Sets the start and/or end times (ms).
+-   `.setParty(current, max, id?)`: Sets the party information.
+-   `.setLargeImage(RpcImage | string, text?)`: Sets the large image and its tooltip text.
+-   `.setSmallImage(RpcImage | string, text?)`: Sets the small image and its tooltip text.
 -   `.setButtons(buttons[])`: Sets up to two clickable buttons. Each button is an object `{ label: string, url: string }`.
+-   `.addButton(label, url)`: Adds a single button (max 2).
 -   `.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.).
+-   `.setPlatform(platform)`: Sets the platform (`'desktop'`, `'android'`, `'ios'`, `'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 activity details.
@@ -212,14 +241,17 @@ Main builder class for RPC.
 -   `.build()`: Builds and sends the presence payload to Discord.
 -   `.updateRPC()`: Alias for `build()`.
 -   `.clear()`: Clears the Rich Presence from the user's profile and resets the builder.
+-   `.clearCache()`: Clears the internal asset cache.
+-   `.destroy()`: Destroys the RPC instance and stops background tasks.
 
 ### Types of images
 
 -   `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 (e.g., `spotify:track_id`).
+-   `new RawImage(assetKey)`: Use an existing asset key directly.
 -   `new DiscordImage(key)`: Use assets already on Discord (e.g., `mp:attachments/...`).
 -   `new ApplicationImage(name)`: Use an asset name from your Discord Application (requires .setApplicationId()).
+
 ## Author
 
 Developed by **hieuxyz**.

package/dist/hieuxyz/Client.d.ts

@@ -39,10 +39,14 @@ export interface ClientOptions {
  */
 export declare class Client {
     /**
-     * Provides access to RPC constructor methods.
-     * Use this to set your Rich Presence state details.
+     * The default RPC instance.
+     * Use this to set your main Rich Presence state details.
      */
     readonly rpc: HieuxyzRPC;
+    /**
+     * List of all RPC instances managed by this client.
+     */
+    private rpcs;
     /**
      * Information about the logged-in user.
      * Populated after run() resolves.
@@ -57,6 +61,22 @@ export declare class Client {
      * @throws {Error} If no token is provided in the options.
      */
     constructor(options: ClientOptions);
+    /**
+     * Create a new RPC instance.
+     * Use this if you want to display multiple activities simultaneously (Multi-RPC).
+     * @returns {HieuxyzRPC} A new RPC builder instance.
+     */
+    createRPC(): HieuxyzRPC;
+    /**
+     * Removes an RPC instance and cleans up its resources.
+     * @param {HieuxyzRPC} rpcInstance The RPC instance to remove.
+     */
+    removeRPC(rpcInstance: HieuxyzRPC): void;
+    /**
+     * Aggregates activities from all RPC instances and sends them to Discord.
+     * Uses Promise.all for parallel asset resolution.
+     */
+    private sendAllActivities;
     /**
      * Displays information about the library.
      */

package/dist/hieuxyz/Client.js

@@ -20,10 +20,14 @@ const types_1 = require("./gateway/entities/types");
  */
 class Client {
     /**
-     * Provides access to RPC constructor methods.
-     * Use this to set your Rich Presence state details.
+     * The default RPC instance.
+     * Use this to set your main Rich Presence state details.
      */
     rpc;
+    /**
+     * List of all RPC instances managed by this client.
+     */
+    rpcs = [];
     /**
      * Information about the logged-in user.
      * Populated after run() resolves.
@@ -48,14 +52,59 @@ class Client {
             properties: options.properties,
             connectionTimeout: options.connectionTimeout,
         });
-        this.rpc = new HieuxyzRPC_1.HieuxyzRPC(this.websocket, this.imageService);
+        this.rpc = this.createRPC();
         this.printAbout();
     }
+    /**
+     * Create a new RPC instance.
+     * Use this if you want to display multiple activities simultaneously (Multi-RPC).
+     * @returns {HieuxyzRPC} A new RPC builder instance.
+     */
+    createRPC() {
+        const newRpc = new HieuxyzRPC_1.HieuxyzRPC(this.imageService, async () => {
+            await this.sendAllActivities();
+        });
+        this.rpcs.push(newRpc);
+        return newRpc;
+    }
+    /**
+     * Removes an RPC instance and cleans up its resources.
+     * @param {HieuxyzRPC} rpcInstance The RPC instance to remove.
+     */
+    removeRPC(rpcInstance) {
+        const index = this.rpcs.indexOf(rpcInstance);
+        if (index > -1) {
+            rpcInstance.destroy();
+            this.rpcs.splice(index, 1);
+            this.sendAllActivities();
+        }
+    }
+    /**
+     * Aggregates activities from all RPC instances and sends them to Discord.
+     * Uses Promise.all for parallel asset resolution.
+     */
+    async sendAllActivities() {
+        const potentialActivities = await Promise.all(this.rpcs.map((rpc) => rpc.buildActivity()));
+        const activities = potentialActivities.filter((a) => a !== null);
+        let status = 'online';
+        for (let i = this.rpcs.length - 1; i >= 0; i--) {
+            if (this.rpcs[i].currentStatus) {
+                status = this.rpcs[i].currentStatus;
+                break;
+            }
+        }
+        this.websocket.sendActivity({
+            since: 0,
+            activities: activities,
+            status: status,
+            afk: true,
+        });
+    }
     /**
      * Displays information about the library.
      */
     printAbout() {
-        const version = '1.2.01';
+        const version = '1.2.3';
         console.log(`
   _     _                               
  | |__ (_) ___ _   ___  ___   _ ______  
@@ -200,7 +249,7 @@ class Client {
      * even if `alwaysReconnect` is enabled. Defaults to false.
      */
     close(force = false) {
-        this.rpc.stopBackgroundRenewal();
+        this.rpcs.forEach((rpc) => rpc.destroy());
         this.websocket.close(force);
     }
 }

package/dist/hieuxyz/rpc/HieuxyzRPC.d.ts

@@ -1,5 +1,4 @@
-import { DiscordWebSocket } from '../gateway/DiscordWebSocket';
-import { SettableActivityType } from '../gateway/entities/types';
+import { Activity, SettableActivityType } from '../gateway/entities/types';
 import { ImageService } from './ImageService';
 import { RpcImage } from './RpcImage';
 /**
@@ -24,12 +23,13 @@ interface RpcSecrets {
     match?: string;
 }
 export type DiscordPlatform = 'desktop' | 'android' | 'ios' | 'samsung' | 'xbox' | 'ps4' | 'ps5' | 'embedded';
+type UpdateCallback = () => Promise<void>;
 /**
  * Class built for creating and managing Discord Rich Presence states.
  */
 export declare class HieuxyzRPC {
-    private websocket;
     private imageService;
+    private onUpdate;
     private activity;
     private assets;
     private status;
@@ -41,13 +41,17 @@ export declare class HieuxyzRPC {
      * Value: The resolved asset key (e.g., "mp:attachments/...").
      */
     private resolvedAssetsCache;
+    /**
+     * Maximum number of items in cache to prevent memory leaks/bloat over long runtime.
+     */
+    private readonly MAX_CACHE_SIZE;
     private renewalInterval;
     /**
      * Cache for Application Assets (Bot Assets).
      * Map<ApplicationID, Map<AssetName, AssetID>>
      */
     private applicationAssetsCache;
-    constructor(websocket: DiscordWebSocket, imageService: ImageService);
+    constructor(imageService: ImageService, onUpdate: UpdateCallback);
     /**
      * Returns the URL of the large image asset, if available.
      * @type {string | null}
@@ -99,9 +103,10 @@ export declare class HieuxyzRPC {
      * Set party information for the activity.
      * @param {number} currentSize - Current number of players.
      * @param {number} maxSize - Maximum number of players.
+     * @param {string} [id] - Optional custom party ID. Defaults to 'hieuxyz'.
      * @returns {this}
      */
-    setParty(currentSize: number, maxSize: number): this;
+    setParty(currentSize: number, maxSize: number, id?: string): this;
     /**
      * Set large image and its caption text.
      * @param {string | RpcImage} source - Image source (URL, asset key, Asset Name or RpcImage object).
@@ -116,8 +121,16 @@ export declare class HieuxyzRPC {
      * @returns {this}
      */
     setSmallImage(source: string | RpcImage, text?: string): this;
+    /**
+     * Add a single button to the activity.
+     * @param {string} label - The text displayed on the button.
+     * @param {string} url - The URL opened when the button is clicked.
+     * @returns {this}
+     */
+    addButton(label: string, url: string): this;
     /**
      * Set clickable buttons for RPC (up to 2).
+     * This will overwrite any existing buttons.
      * @param {RpcButton[]} buttons - An array of button objects, each with a `label` and `url`.
      * @returns {this}
      */
@@ -186,9 +199,14 @@ export declare class HieuxyzRPC {
      */
     private ensureAppAssetsLoaded;
     private resolveImage;
-    private buildActivity;
     /**
-     * Build the final Rich Presence payload and send it to Discord.
+     * Publicly accessible method to build the Activity object.
+     * Used by Client to aggregate activities from multiple RPC instances.
+     * @returns {Promise<Activity | null>} The constructed activity or null if empty.
+     */
+    buildActivity(): Promise<Activity | null>;
+    /**
+     * Build the final Rich Presence payload and notify the Client to send it to Discord.
      * @returns {Promise<void>}
      */
     build(): Promise<void>;
@@ -199,11 +217,21 @@ export declare class HieuxyzRPC {
      */
     updateRPC(): Promise<void>;
     /**
-     * Clears the current Rich Presence from Discord and resets the builder state.
-     * This sends an empty activity payload to Discord and then resets all configured
-     * options (name, details, images, etc.) to their default values, allowing you
-     * to build a new presence from scratch.
+     * Clears the current Rich Presence from the user's profile and resets the builder.
      */
     clear(): void;
+    /**
+     * Manually clear the asset cache to free memory.
+     */
+    clearCache(): void;
+    /**
+     * Permanently destroy this RPC instance.
+     * Stops renewal timers and clears memory.
+     */
+    destroy(): void;
+    /**
+     * Get the current status set for this RPC instance.
+     */
+    get currentStatus(): "online" | "dnd" | "idle" | "invisible" | "offline";
 }
 export {};

package/dist/hieuxyz/rpc/HieuxyzRPC.js

@@ -21,8 +21,8 @@ var ActivityFlags;
  * Class built for creating and managing Discord Rich Presence states.
  */
 class HieuxyzRPC {
-    websocket;
     imageService;
+    onUpdate;
     activity = {};
     assets = {};
     status = 'online';
@@ -34,15 +34,19 @@ class HieuxyzRPC {
      * Value: The resolved asset key (e.g., "mp:attachments/...").
      */
     resolvedAssetsCache = new Map();
+    /**
+     * Maximum number of items in cache to prevent memory leaks/bloat over long runtime.
+     */
+    MAX_CACHE_SIZE = 50;
     renewalInterval = null;
     /**
      * Cache for Application Assets (Bot Assets).
      * Map<ApplicationID, Map<AssetName, AssetID>>
      */
     applicationAssetsCache = new Map();
-    constructor(websocket, imageService) {
-        this.websocket = websocket;
+    constructor(imageService, onUpdate) {
         this.imageService = imageService;
+        this.onUpdate = onUpdate;
         this.startBackgroundRenewal();
     }
     /**
@@ -184,10 +188,11 @@ class HieuxyzRPC {
      * Set party information for the activity.
      * @param {number} currentSize - Current number of players.
      * @param {number} maxSize - Maximum number of players.
+     * @param {string} [id] - Optional custom party ID. Defaults to 'hieuxyz'.
      * @returns {this}
      */
-    setParty(currentSize, maxSize) {
-        this.activity.party = { id: 'hieuxyz', size: [currentSize, maxSize] };
+    setParty(currentSize, maxSize, id = 'hieuxyz') {
+        this.activity.party = { id: id, size: [currentSize, maxSize] };
         return this;
     }
     /**
@@ -214,8 +219,33 @@ class HieuxyzRPC {
             this.assets.small_text = this.sanitize(text);
         return this;
     }
+    /**
+     * Add a single button to the activity.
+     * @param {string} label - The text displayed on the button.
+     * @param {string} url - The URL opened when the button is clicked.
+     * @returns {this}
+     */
+    addButton(label, url) {
+        if (!this.activity.buttons) {
+            this.activity.buttons = [];
+        }
+        if (!this.activity.metadata) {
+            this.activity.metadata = { button_urls: [] };
+        }
+        if (!this.activity.metadata.button_urls) {
+            this.activity.metadata.button_urls = [];
+        }
+        if (this.activity.buttons.length >= 2) {
+            logger_1.logger.warn('Cannot add more than 2 buttons. Button ignored.');
+            return this;
+        }
+        this.activity.buttons.push(this.sanitize(label, 32));
+        this.activity.metadata.button_urls.push(url);
+        return this;
+    }
     /**
      * Set clickable buttons for RPC (up to 2).
+     * This will overwrite any existing buttons.
      * @param {RpcButton[]} buttons - An array of button objects, each with a `label` and `url`.
      * @returns {this}
      */
@@ -350,7 +380,7 @@ class HieuxyzRPC {
     async renewAssetIfNeeded(cacheKey, assetKey) {
         const expiryTimeMs = this.getExpiryTime(assetKey);
         if (expiryTimeMs && expiryTimeMs < Date.now() + 3600000) {
-            logger_1.logger.info(`Asset ${cacheKey} is expiring soon. Renewing...`);
+            // logger.info(`Asset ${cacheKey} is expiring soon. Renewing...`);
             const assetId = assetKey.split('mp:attachments/')[1];
             const newAsset = await this.imageService.renewImage(assetId);
             if (newAsset) {
@@ -366,7 +396,7 @@ class HieuxyzRPC {
             clearInterval(this.renewalInterval);
         }
         this.renewalInterval = setInterval(async () => {
-            logger_1.logger.info('Running background asset renewal check...');
+            // logger.info('Running background asset renewal check...');
             for (const [cacheKey, assetKey] of this.resolvedAssetsCache.entries()) {
                 await this.renewAssetIfNeeded(cacheKey, assetKey);
             }
@@ -379,7 +409,7 @@ class HieuxyzRPC {
         if (this.renewalInterval) {
             clearInterval(this.renewalInterval);
             this.renewalInterval = null;
-            logger_1.logger.info('Stopped background asset renewal process.');
+            // logger.info('Stopped background asset renewal process.');
         }
     }
     /**
@@ -412,6 +442,12 @@ class HieuxyzRPC {
             }
             return assetId;
         }
+        if (this.resolvedAssetsCache.size >= this.MAX_CACHE_SIZE && !this.resolvedAssetsCache.has(cacheKey)) {
+            const oldestKey = this.resolvedAssetsCache.keys().next().value;
+            if (oldestKey) {
+                this.resolvedAssetsCache.delete(oldestKey);
+            }
+        }
         const cachedAsset = this.resolvedAssetsCache.get(cacheKey);
         if (cachedAsset) {
             return await this.renewAssetIfNeeded(cacheKey, cachedAsset);
@@ -425,7 +461,15 @@ class HieuxyzRPC {
         }
         return resolvedAsset;
     }
+    /**
+     * Publicly accessible method to build the Activity object.
+     * Used by Client to aggregate activities from multiple RPC instances.
+     * @returns {Promise<Activity | null>} The constructed activity or null if empty.
+     */
     async buildActivity() {
+        if (Object.keys(this.activity).length === 0 && !this.assets.large_image && !this.assets.small_image) {
+            return null;
+        }
         const large_image = await this.resolveImage(this.assets.large_image);
         const small_image = await this.resolveImage(this.assets.small_image);
         const finalAssets = {
@@ -449,18 +493,11 @@ class HieuxyzRPC {
         return this.cleanupNulls(finalActivity);
     }
     /**
-     * Build the final Rich Presence payload and send it to Discord.
+     * Build the final Rich Presence payload and notify the Client to send it to Discord.
      * @returns {Promise<void>}
      */
     async build() {
-        const activity = await this.buildActivity();
-        const presencePayload = {
-            since: 0,
-            activities: [activity],
-            status: this.status,
-            afk: true,
-        };
-        this.websocket.sendActivity(presencePayload);
+        await this.onUpdate();
     }
     /**
      * Sends an update to an existing RPC.
@@ -471,25 +508,39 @@ class HieuxyzRPC {
         await this.build();
     }
     /**
-     * Clears the current Rich Presence from Discord and resets the builder state.
-     * This sends an empty activity payload to Discord and then resets all configured
-     * options (name, details, images, etc.) to their default values, allowing you
-     * to build a new presence from scratch.
+     * Clears the current Rich Presence from the user's profile and resets the builder.
      */
     clear() {
-        const clearPayload = {
-            since: 0,
-            activities: [],
-            status: this.status,
-            afk: true,
-        };
-        this.websocket.sendActivity(clearPayload);
-        logger_1.logger.info('Rich Presence cleared from Discord.');
         this.activity = {};
         this.assets = {};
         this.applicationId = '1416676323459469363'; // Reset to default
         this.platform = 'desktop'; // Reset to default
-        logger_1.logger.info('RPC builder has been reset to its initial state.');
+        logger_1.logger.info('RPC instance cleared.');
+        this.onUpdate();
+    }
+    /**
+     * Manually clear the asset cache to free memory.
+     */
+    clearCache() {
+        this.resolvedAssetsCache.clear();
+        this.applicationAssetsCache.clear();
+        logger_1.logger.info('RPC Asset cache has been cleared.');
+    }
+    /**
+     * Permanently destroy this RPC instance.
+     * Stops renewal timers and clears memory.
+     */
+    destroy() {
+        this.stopBackgroundRenewal();
+        this.clearCache();
+        this.activity = {};
+        this.assets = {};
+    }
+    /**
+     * Get the current status set for this RPC instance.
+     */
+    get currentStatus() {
+        return this.status;
     }
 }
 exports.HieuxyzRPC = HieuxyzRPC;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hieuxyz/rpc",
-  "version": "1.2.01",
+  "version": "1.2.3",
   "description": "A Discord Rich Presence library for Node.js",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,8 +10,15 @@
     "LICENSE"
   ],
   "scripts": {
+    "tsx": "tsx",
+    "esbuild": "esbuild",
+    "check": "tsc --noEmit",
+    "dev": "tsx --env-file=.env examples/main.ts",
+    "dev:ts": "node -r ts-node/register --env-file=.env examples/main.ts",
     "build": "tsc",
-    "dev": "node -r ts-node/register --env-file=.env examples/main.ts",
+    "build:es": "esbuild src/index.ts --bundle --platform=node --minify --outfile=dist/index.ts",
+    "build:ex": "esbuild examples/main.ts --bundle --platform=node --minify --outfile=dist/main.js",
+    "start:ex": "node --env-file=.env dist/main.js",
     "lint": "eslint \"src/**/*.ts\" --report-unused-disable-directives --max-warnings 0",
     "lint:fix": "eslint \"src/**/*.ts\" --fix",
     "format": "prettier --write \"src/**/*.ts\" \"examples/**/*.ts\""
@@ -38,11 +45,13 @@
   "devDependencies": {
     "@types/node": "^25.0.3",
     "@types/ws": "^8.18.1",
+    "esbuild": "^0.27.2",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",
     "prettier": "^3.7.4",
     "ts-node": "^10.9.2",
+    "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.51.0"
   }