@hieuxyz/rpc 1.1.0 → 1.1.11

package/README.md

@@ -4,7 +4,7 @@
 [![License](https://img.shields.io/npm/l/@hieuxyz/rpc.svg)](https://github.com/hieuxyz/rpc/blob/main/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,5 @@
 import { HieuxyzRPC } from './rpc/HieuxyzRPC';
+import { ClientProperties } from './gateway/entities/identify';
 /**
  * Option to initialize Client.
  */
@@ -12,6 +13,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,7 +39,7 @@ 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;
     private readonly websocket;
@@ -36,7 +47,7 @@ export declare class Client {
     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);

package/dist/hieuxyz/Client.js

@@ -20,7 +20,7 @@ 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;
     websocket;
@@ -28,7 +28,7 @@ class Client {
     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,6 +39,8 @@ 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);
     }

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

@@ -1,6 +1,9 @@
+import { ClientProperties } from './entities/identify';
 import { PresenceUpdatePayload } from './entities/types';
 interface DiscordWebSocketOptions {
     alwaysReconnect: boolean;
+    properties?: ClientProperties;
+    connectionTimeout?: number;
 }
 /**
  * Manage WebSocket connections to Discord Gateway.
@@ -17,6 +20,7 @@ export declare class DiscordWebSocket {
     private options;
     private isReconnecting;
     private permanentClose;
+    private connectTimeout;
     private resolveReady;
     /**
      * A promise will be resolved when the Gateway connection is ready.
@@ -25,8 +29,8 @@ export declare class DiscordWebSocket {
     readyPromise: Promise<void>;
     /**
      * 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 +41,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 +49,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;

package/dist/hieuxyz/gateway/DiscordWebSocket.js

@@ -57,6 +57,7 @@ class DiscordWebSocket {
     options;
     isReconnecting = false;
     permanentClose = false;
+    connectTimeout = null;
     resolveReady = () => { };
     /**
      * A promise will be resolved when the Gateway connection is ready.
@@ -65,8 +66,8 @@ class DiscordWebSocket {
     readyPromise;
     /**
      * 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, options) {
@@ -74,7 +75,11 @@ class DiscordWebSocket {
             throw new Error('Invalid token provided.');
         }
         this.token = token;
-        this.options = options;
+        this.options = {
+            alwaysReconnect: options.alwaysReconnect ?? false,
+            properties: options.properties,
+            connectionTimeout: options.connectionTimeout ?? 30000,
+        };
         this.readyPromise = new Promise((resolve) => (this.resolveReady = resolve));
     }
     resetReadyPromise() {
@@ -99,39 +104,53 @@ class DiscordWebSocket {
         const url = this.resumeGatewayUrl || 'wss://gateway.discord.gg/?v=10&encoding=json';
         logger_1.logger.info(`Attempting to connect to ${url}...`);
         this.ws = new ws_1.default(url);
+        this.connectTimeout = setTimeout(() => {
+            logger_1.logger.error('Connection timed out. Terminating connection attempt.');
+            if (this.ws) {
+                this.ws.terminate();
+            }
+        }, this.options.connectionTimeout);
         this.ws.on('open', () => {
             logger_1.logger.info(`Successfully connected to Discord Gateway at ${url}.`);
             this.isReconnecting = false;
-        });
-        this.ws.on('message', this.onMessage.bind(this));
-        this.ws.on('close', (code, reason) => {
-            logger_1.logger.warn(`Connection closed: ${code} - ${reason.toString('utf-8')}`);
-            this.cleanupHeartbeat();
-            if (this.permanentClose) {
-                logger_1.logger.info('Connection permanently closed by client. Not reconnecting.');
-                return;
-            }
-            if (this.isReconnecting)
-                return;
-            if (this.shouldReconnect(code)) {
-                setTimeout(() => {
-                    const canResume = code !== 4004 && !!this.sessionId;
-                    if (!canResume) {
-                        this.sessionId = null;
-                        this.sequence = null;
-                        this.resumeGatewayUrl = null;
-                    }
-                    this.connect();
-                }, 500);
-            }
-            else {
-                logger_1.logger.info('Not attempting to reconnect based on close code and client options.');
+            if (this.connectTimeout) {
+                clearTimeout(this.connectTimeout);
+                this.connectTimeout = null;
             }
         });
+        this.ws.on('message', this.onMessage.bind(this));
+        this.ws.on('close', this.handleClose.bind(this));
         this.ws.on('error', (err) => {
-            logger_1.logger.error(`WebSocket Error: ${err.message}`);
+            if (err.message !== 'WebSocket was closed before the connection was established') {
+                logger_1.logger.error(`WebSocket Error: ${err.message}`);
+            }
         });
     }
+    handleClose(code, reason) {
+        logger_1.logger.warn(`Connection closed: ${code} - ${reason.toString('utf-8')}`);
+        this.cleanupHeartbeat();
+        if (this.connectTimeout) {
+            clearTimeout(this.connectTimeout);
+            this.connectTimeout = null;
+        }
+        this.isReconnecting = false;
+        if (code === 4004) {
+            this.sessionId = null;
+            this.sequence = null;
+            this.resumeGatewayUrl = null;
+        }
+        if (this.permanentClose) {
+            logger_1.logger.info('Connection permanently closed by client. Not reconnecting.');
+            return;
+        }
+        if (this.shouldReconnect(code)) {
+            logger_1.logger.info('Attempting to reconnect in 5 seconds...');
+            setTimeout(() => this.connect(), 5000);
+        }
+        else {
+            logger_1.logger.info('Not attempting to reconnect based on close code and client options.');
+        }
+    }
     onMessage(data, isBinary) {
         let decompressedData;
         if (isBinary) {
@@ -146,6 +165,10 @@ class DiscordWebSocket {
         }
         switch (payload.op) {
             case OpCode_1.OpCode.HELLO:
+                if (this.connectTimeout) {
+                    clearTimeout(this.connectTimeout);
+                    this.connectTimeout = null;
+                }
                 this.heartbeatIntervalValue = payload.d.heartbeat_interval;
                 logger_1.logger.info(`Received HELLO. Setting heartbeat interval to ${this.heartbeatIntervalValue}ms.`);
                 this.startHeartbeating();
@@ -211,7 +234,7 @@ class DiscordWebSocket {
         logger_1.logger.info(`Heartbeat sent with sequence ${this.sequence}.`);
     }
     identify() {
-        const identifyPayload = (0, identify_1.getIdentifyPayload)(this.token);
+        const identifyPayload = (0, identify_1.getIdentifyPayload)(this.token, this.options.properties);
         this.sendJson({ op: OpCode_1.OpCode.IDENTIFY, d: identifyPayload });
         logger_1.logger.info('Identify payload sent.');
     }
@@ -231,7 +254,7 @@ class DiscordWebSocket {
     }
     /**
      * Send presence update payload to Gateway.
-     * @param presence - Payload update status to send.
+     * @param {PresenceUpdatePayload} presence - Payload update status to send.
      */
     sendActivity(presence) {
         this.sendJson({ op: OpCode_1.OpCode.PRESENCE_UPDATE, d: presence });
@@ -247,7 +270,7 @@ class DiscordWebSocket {
     }
     /**
      * 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 = false) {
         if (force) {
@@ -257,9 +280,13 @@ class DiscordWebSocket {
         else {
             logger_1.logger.info('Closing connection manually...');
         }
-        this.isReconnecting = false;
         if (this.ws) {
-            this.ws.close(1000, 'Client initiated closure');
+            if (this.ws.readyState === ws_1.default.OPEN) {
+                this.ws.close(1000, 'Client initiated closure');
+            }
+            else {
+                this.ws.terminate();
+            }
         }
     }
     cleanupHeartbeat() {
@@ -269,7 +296,9 @@ class DiscordWebSocket {
         }
     }
     shouldReconnect(code) {
-        const fatalErrorCodes = [4010, 4011, 4013, 4014];
+        if (code === 1006)
+            return true;
+        const fatalErrorCodes = [4004, 4010, 4011, 4013, 4014];
         if (fatalErrorCodes.includes(code)) {
             logger_1.logger.error(`Fatal WebSocket error received (code: ${code}). Will not reconnect.`);
             return false;

package/dist/hieuxyz/gateway/entities/identify.d.ts

@@ -1,2 +1,13 @@
 import { IdentifyPayload } from './types';
-export declare function getIdentifyPayload(token: string): IdentifyPayload;
+/**
+ * @typedef {object} ClientProperties
+ * @property {string} [os] - The operating system. (e.g., 'Windows', 'Android')
+ * @property {string} [browser] - The browser or client. (e.g., 'Discord Client', 'Discord Android')
+ * @property {string} [device] - The device. (e.g., 'Android16')
+ */
+export interface ClientProperties {
+    os?: string;
+    browser?: string;
+    device?: string;
+}
+export declare function getIdentifyPayload(token: string, properties?: ClientProperties): IdentifyPayload;

package/dist/hieuxyz/gateway/entities/identify.js

@@ -1,16 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getIdentifyPayload = getIdentifyPayload;
-function getIdentifyPayload(token) {
+function getIdentifyPayload(token, properties) {
+    const defaultProperties = {
+        os: 'Windows',
+        browser: 'Discord Client',
+        device: 'hieuxyz©rpc',
+    };
     return {
         token: token,
         capabilities: 65,
         largeThreshold: 50,
-        properties: {
-            os: 'Windows',
-            browser: 'Discord Client',
-            device: 'hieuxyz©rpc',
-        },
+        properties: { ...defaultProperties, ...properties },
         compress: true,
     };
 }

package/dist/hieuxyz/gateway/entities/types.d.ts

@@ -15,15 +15,16 @@ export interface GatewayPayload {
     s?: number | null;
     t?: string | null;
 }
+export interface IdentifyProperties {
+    os: string;
+    browser: string;
+    device: string;
+}
 export interface IdentifyPayload {
     token: string;
     capabilities: number;
     largeThreshold: number;
-    properties: {
-        os: string;
-        browser: string;
-        device: string;
-    };
+    properties: IdentifyProperties;
     compress: boolean;
 }
 export interface Activity {
@@ -34,6 +35,8 @@ export interface Activity {
     state?: string;
     platform?: string;
     instance?: boolean;
+    flags?: number;
+    sync_id?: string;
     party?: {
         id?: string;
         size?: [number, number];
@@ -48,6 +51,11 @@ export interface Activity {
         small_image?: string;
         small_text?: string;
     };
+    secrets?: {
+        join?: string;
+        spectate?: string;
+        match?: string;
+    };
     buttons?: string[];
     metadata?: {
         button_urls?: string[];

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

@@ -2,10 +2,27 @@ import { DiscordWebSocket } from '../gateway/DiscordWebSocket';
 import { SettableActivityType } from '../gateway/entities/types';
 import { ImageService } from './ImageService';
 import { RpcImage } from './RpcImage';
+/**
+ * Flags for activities, used with `.setFlags()`.
+ * @enum {number}
+ */
+export declare enum ActivityFlags {
+    INSTANCE = 1,
+    JOIN = 2,
+    SPECTATE = 4,
+    JOIN_REQUEST = 8,
+    SYNC = 16,
+    PLAY = 32
+}
 interface RpcButton {
     label: string;
     url: string;
 }
+interface RpcSecrets {
+    join?: string;
+    spectate?: string;
+    match?: string;
+}
 export type DiscordPlatform = 'desktop' | 'android' | 'ios' | 'samsung' | 'xbox' | 'ps4' | 'ps5' | 'embedded';
 /**
  * Class built for creating and managing Discord Rich Presence states.
@@ -26,89 +43,120 @@ export declare class HieuxyzRPC {
     private resolvedAssetsCache;
     private renewalInterval;
     constructor(websocket: DiscordWebSocket, imageService: ImageService);
+    /**
+     * Returns the URL of the large image asset, if available.
+     * @type {string | null}
+     * @readonly
+     */
+    get largeImageUrl(): string | null;
+    /**
+     * Returns the URL of the small image asset, if available.
+     * @type {string | null}
+     * @readonly
+     */
+    get smallImageUrl(): string | null;
+    private _resolveAssetUrl;
     private _toRpcImage;
     private cleanupNulls;
     private sanitize;
     /**
      * Name the operation (first line of RPC).
-     * @param name - Name to display.
+     * @param {string} name - Name to display.
      * @returns {this}
      */
     setName(name: string): this;
     /**
      * Set details for the operation (second line of RPC).
-     * @param details - Details to display.
+     * @param {string} details - Details to display.
      * @returns {this}
      */
     setDetails(details: string): this;
     /**
      * Set the state for the operation (third line of the RPC).
-     * @param state - State to display.
+     * @param {string} state - State to display.
      * @returns {this}
      */
     setState(state: string): this;
     /**
      * Set the activity type.
-     * @param type - The type of activity (e.g. 0, 'playing', or ActivityType.Playing).
+     * @param {SettableActivityType} type - The type of activity (e.g. 0, 'playing', or ActivityType.Playing).
      * @returns {this}
      */
     setType(type: SettableActivityType): this;
     /**
      * Set a start and/or end timestamp for the activity.
-     * @param start - Unix timestamp (milliseconds) for start time.
-     * @param end - Unix timestamp (milliseconds) for the end time.
+     * @param {number} [start] - Unix timestamp (milliseconds) for start time.
+     * @param {number} [end] - Unix timestamp (milliseconds) for the end time.
      * @returns {this}
      */
     setTimestamps(start?: number, end?: number): this;
     /**
      * Set party information for the activity.
-     * @param currentSize - Current number of players.
-     * @param maxSize - Maximum number of players.
+     * @param {number} currentSize - Current number of players.
+     * @param {number} maxSize - Maximum number of players.
      * @returns {this}
      */
     setParty(currentSize: number, maxSize: number): this;
     /**
      * Set large image and its caption text.
-     * @param source - Image source (URL, asset key, or RpcImage object).
-     * @param text - Text displayed when hovering over image.
+     * @param {string | RpcImage} source - Image source (URL, asset key, or RpcImage object).
+     * @param {string} [text] - Text displayed when hovering over image.
      * @returns {this}
      */
     setLargeImage(source: string | RpcImage, text?: string): this;
     /**
      * Set the small image and its caption text.
-     * @param source - Image source (URL, asset key, or RpcImage object).
-     * @param text - Text displayed when hovering over image.
+     * @param {string | RpcImage} source - Image source (URL, asset key, or RpcImage object).
+     * @param {string} [text] - Text displayed when hovering over image.
      * @returns {this}
      */
     setSmallImage(source: string | RpcImage, text?: string): this;
     /**
      * Set clickable buttons for RPC (up to 2).
-     * @param buttons - An array of button objects.
+     * @param {RpcButton[]} buttons - An array of button objects, each with a `label` and `url`.
      * @returns {this}
      */
     setButtons(buttons: RpcButton[]): this;
+    /**
+     * Set secrets for joining, spectating, and matching games.
+     * @param {RpcSecrets} secrets - An object with join, spectate, and/or match secrets.
+     * @returns {this}
+     */
+    setSecrets(secrets: RpcSecrets): this;
+    /**
+     * Set the sync_id, typically used for Spotify track synchronization.
+     * @param {string} syncId - The synchronization ID.
+     * @returns {this}
+     */
+    setSyncId(syncId: string): this;
+    /**
+     * Set activity flags. Use the ActivityFlags enum for convenience.
+     * @param {number} flags - A number representing the bitwise flags.
+     * @returns {this}
+     */
+    setFlags(flags: number): this;
     /**
      * Set custom application ID for RPC.
-     * @param id - Discord app ID (must be an 18 or 19 digit number string).
+     * @param {string} id - Discord app ID (must be an 18 or 19 digit number string).
      * @throws {Error} If ID is invalid.
      * @returns {this}
      */
     setApplicationId(id: string): this;
     /**
      * Set the user's status (e.g. online, idle, dnd).
-     * @param status - Desired state.
+     * @param {'online' | 'dnd' | 'idle' | 'invisible' | 'offline'} status - Desired state.
      * @returns {this}
      */
     setStatus(status: 'online' | 'dnd' | 'idle' | 'invisible' | 'offline'): this;
     /**
      * Set the platform on which the activity is running.
-     * @param platform - Platform (e.g. 'desktop', 'xbox').
+     * @param {DiscordPlatform} platform - Platform (e.g. 'desktop', 'xbox').
      * @returns {this}
      */
     setPlatform(platform: DiscordPlatform): this;
     /**
      * Marks the activity as a joinable instance for the game.
-     * @param instance - Whether this activity is a specific instance.
+     * @param {boolean} instance - Whether this activity is a specific instance.
      * @returns {this}
      */
     setInstance(instance: boolean): this;
@@ -117,6 +165,7 @@ export declare class HieuxyzRPC {
     clearTimestamps(): this;
     clearParty(): this;
     clearButtons(): this;
+    clearSecrets(): this;
     clearInstance(): this;
     clearLargeImage(): this;
     clearSmallImage(): this;

package/dist/hieuxyz/rpc/HieuxyzRPC.js

@@ -1,9 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HieuxyzRPC = void 0;
+exports.HieuxyzRPC = exports.ActivityFlags = void 0;
 const types_1 = require("../gateway/entities/types");
 const RpcImage_1 = require("./RpcImage");
 const logger_1 = require("../utils/logger");
+/**
+ * Flags for activities, used with `.setFlags()`.
+ * @enum {number}
+ */
+var ActivityFlags;
+(function (ActivityFlags) {
+    ActivityFlags[ActivityFlags["INSTANCE"] = 1] = "INSTANCE";
+    ActivityFlags[ActivityFlags["JOIN"] = 2] = "JOIN";
+    ActivityFlags[ActivityFlags["SPECTATE"] = 4] = "SPECTATE";
+    ActivityFlags[ActivityFlags["JOIN_REQUEST"] = 8] = "JOIN_REQUEST";
+    ActivityFlags[ActivityFlags["SYNC"] = 16] = "SYNC";
+    ActivityFlags[ActivityFlags["PLAY"] = 32] = "PLAY";
+})(ActivityFlags || (exports.ActivityFlags = ActivityFlags = {}));
 /**
  * Class built for creating and managing Discord Rich Presence states.
  */
@@ -13,7 +26,7 @@ class HieuxyzRPC {
     activity = {};
     assets = {};
     status = 'online';
-    applicationId = '1416676323459469363'; // Default ID, can be changed
+    applicationId = '1416676323459469363';
     platform = 'desktop';
     /**
      * Cache for resolved image assets to avoid re-uploading or re-fetching.
@@ -27,6 +40,49 @@ class HieuxyzRPC {
         this.imageService = imageService;
         this.startBackgroundRenewal();
     }
+    /**
+     * Returns the URL of the large image asset, if available.
+     * @type {string | null}
+     * @readonly
+     */
+    get largeImageUrl() {
+        if (!this.assets.large_image)
+            return null;
+        const cacheKey = this.assets.large_image.getCacheKey();
+        const resolvedAsset = this.resolvedAssetsCache.get(cacheKey);
+        return resolvedAsset ? this._resolveAssetUrl(resolvedAsset) : null;
+    }
+    /**
+     * Returns the URL of the small image asset, if available.
+     * @type {string | null}
+     * @readonly
+     */
+    get smallImageUrl() {
+        if (!this.assets.small_image)
+            return null;
+        const cacheKey = this.assets.small_image.getCacheKey();
+        const resolvedAsset = this.resolvedAssetsCache.get(cacheKey);
+        return resolvedAsset ? this._resolveAssetUrl(resolvedAsset) : null;
+    }
+    _resolveAssetUrl(assetKey) {
+        if (assetKey.startsWith('mp:')) {
+            return `https://media.discordapp.net/${assetKey.substring(3)}`;
+        }
+        if (assetKey.startsWith('spotify:')) {
+            return `https://i.scdn.co/image/${assetKey.substring(8)}`;
+        }
+        if (assetKey.startsWith('youtube:')) {
+            return `https://i.ytimg.com/vi/${assetKey.substring(8)}/hqdefault.jpg`;
+        }
+        if (assetKey.startsWith('twitch:')) {
+            return `https://static-cdn.jtvnw.net/previews-ttv/live_user_${assetKey.substring(7)}.png`;
+        }
+        // For assets uploaded to a Discord application
+        if (this.applicationId && !assetKey.startsWith('http')) {
+            return `https://cdn.discordapp.com/app-assets/${this.applicationId}/${assetKey}.png`;
+        }
+        return null;
+    }
     _toRpcImage(source) {
         if (typeof source !== 'string') {
             return source;
@@ -60,7 +116,7 @@ class HieuxyzRPC {
     }
     /**
      * Name the operation (first line of RPC).
-     * @param name - Name to display.
+     * @param {string} name - Name to display.
      * @returns {this}
      */
     setName(name) {
@@ -69,7 +125,7 @@ class HieuxyzRPC {
     }
     /**
      * Set details for the operation (second line of RPC).
-     * @param details - Details to display.
+     * @param {string} details - Details to display.
      * @returns {this}
      */
     setDetails(details) {
@@ -78,7 +134,7 @@ class HieuxyzRPC {
     }
     /**
      * Set the state for the operation (third line of the RPC).
-     * @param state - State to display.
+     * @param {string} state - State to display.
      * @returns {this}
      */
     setState(state) {
@@ -87,7 +143,7 @@ class HieuxyzRPC {
     }
     /**
      * Set the activity type.
-     * @param type - The type of activity (e.g. 0, 'playing', or ActivityType.Playing).
+     * @param {SettableActivityType} type - The type of activity (e.g. 0, 'playing', or ActivityType.Playing).
      * @returns {this}
      */
     setType(type) {
@@ -109,8 +165,8 @@ class HieuxyzRPC {
     }
     /**
      * Set a start and/or end timestamp for the activity.
-     * @param start - Unix timestamp (milliseconds) for start time.
-     * @param end - Unix timestamp (milliseconds) for the end time.
+     * @param {number} [start] - Unix timestamp (milliseconds) for start time.
+     * @param {number} [end] - Unix timestamp (milliseconds) for the end time.
      * @returns {this}
      */
     setTimestamps(start, end) {
@@ -119,8 +175,8 @@ class HieuxyzRPC {
     }
     /**
      * Set party information for the activity.
-     * @param currentSize - Current number of players.
-     * @param maxSize - Maximum number of players.
+     * @param {number} currentSize - Current number of players.
+     * @param {number} maxSize - Maximum number of players.
      * @returns {this}
      */
     setParty(currentSize, maxSize) {
@@ -129,8 +185,8 @@ class HieuxyzRPC {
     }
     /**
      * Set large image and its caption text.
-     * @param source - Image source (URL, asset key, or RpcImage object).
-     * @param text - Text displayed when hovering over image.
+     * @param {string | RpcImage} source - Image source (URL, asset key, or RpcImage object).
+     * @param {string} [text] - Text displayed when hovering over image.
      * @returns {this}
      */
     setLargeImage(source, text) {
@@ -141,8 +197,8 @@ class HieuxyzRPC {
     }
     /**
      * Set the small image and its caption text.
-     * @param source - Image source (URL, asset key, or RpcImage object).
-     * @param text - Text displayed when hovering over image.
+     * @param {string | RpcImage} source - Image source (URL, asset key, or RpcImage object).
+     * @param {string} [text] - Text displayed when hovering over image.
      * @returns {this}
      */
     setSmallImage(source, text) {
@@ -153,7 +209,7 @@ class HieuxyzRPC {
     }
     /**
      * Set clickable buttons for RPC (up to 2).
-     * @param buttons - An array of button objects.
+     * @param {RpcButton[]} buttons - An array of button objects, each with a `label` and `url`.
      * @returns {this}
      */
     setButtons(buttons) {
@@ -162,9 +218,36 @@ class HieuxyzRPC {
         this.activity.metadata = { button_urls: validButtons.map((b) => b.url) };
         return this;
     }
+    /**
+     * Set secrets for joining, spectating, and matching games.
+     * @param {RpcSecrets} secrets - An object with join, spectate, and/or match secrets.
+     * @returns {this}
+     */
+    setSecrets(secrets) {
+        this.activity.secrets = secrets;
+        return this;
+    }
+    /**
+     * Set the sync_id, typically used for Spotify track synchronization.
+     * @param {string} syncId - The synchronization ID.
+     * @returns {this}
+     */
+    setSyncId(syncId) {
+        this.activity.sync_id = syncId;
+        return this;
+    }
+    /**
+     * Set activity flags. Use the ActivityFlags enum for convenience.
+     * @param {number} flags - A number representing the bitwise flags.
+     * @returns {this}
+     */
+    setFlags(flags) {
+        this.activity.flags = flags;
+        return this;
+    }
     /**
      * Set custom application ID for RPC.
-     * @param id - Discord app ID (must be an 18 or 19 digit number string).
+     * @param {string} id - Discord app ID (must be an 18 or 19 digit number string).
      * @throws {Error} If ID is invalid.
      * @returns {this}
      */
@@ -177,7 +260,7 @@ class HieuxyzRPC {
     }
     /**
      * Set the user's status (e.g. online, idle, dnd).
-     * @param status - Desired state.
+     * @param {'online' | 'dnd' | 'idle' | 'invisible' | 'offline'} status - Desired state.
      * @returns {this}
      */
     setStatus(status) {
@@ -186,7 +269,7 @@ class HieuxyzRPC {
     }
     /**
      * Set the platform on which the activity is running.
-     * @param platform - Platform (e.g. 'desktop', 'xbox').
+     * @param {DiscordPlatform} platform - Platform (e.g. 'desktop', 'xbox').
      * @returns {this}
      */
     setPlatform(platform) {
@@ -195,7 +278,7 @@ class HieuxyzRPC {
     }
     /**
      * Marks the activity as a joinable instance for the game.
-     * @param instance - Whether this activity is a specific instance.
+     * @param {boolean} instance - Whether this activity is a specific instance.
      * @returns {this}
      */
     setInstance(instance) {
@@ -223,6 +306,10 @@ class HieuxyzRPC {
         this.activity.metadata = undefined;
         return this;
     }
+    clearSecrets() {
+        this.activity.secrets = undefined;
+        return this;
+    }
     clearInstance() {
         this.activity.instance = undefined;
         return this;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hieuxyz/rpc",
-  "version": "1.1.0",
+  "version": "1.1.11",
   "description": "A Discord Rich Presence library for Node.js",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,6 +16,10 @@
     "lint:fix": "eslint \"src/**/*.ts\" --fix",
     "format": "prettier --write \"src/**/*.ts\" \"examples/**/*.ts\""
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hieuxyz00/hieuxyz_rpc.git"
+  },
   "keywords": [
     "discord",
     "rpc",
@@ -23,6 +27,10 @@
   ],
   "author": "hieuxyz",
   "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/hieuxyz00/hieuxyz_rpc/issues"
+  },
+  "homepage": "https://github.com/hieuxyz00/hieuxyz_rpc#readme",
   "dependencies": {
     "axios": "^1.12.2",
     "ws": "^8.18.3"