@hieuxyz/rpc 1.1.0 → 1.2.0

package/dist/hieuxyz/gateway/DiscordWebSocket.js

@@ -57,7 +57,12 @@ class DiscordWebSocket {
     options;
     isReconnecting = false;
     permanentClose = false;
+    connectTimeout = null;
     resolveReady = () => { };
+    /**
+     * Current logged in user info.
+     */
+    user = null;
     /**
      * A promise will be resolved when the Gateway connection is ready.
      * and received the READY event.
@@ -65,8 +70,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 +79,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 +108,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 +169,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();
@@ -160,12 +187,15 @@ class DiscordWebSocket {
                 if (payload.t === 'READY') {
                     this.sessionId = payload.d.session_id;
                     this.resumeGatewayUrl = payload.d.resume_gateway_url + '/?v=10&encoding=json';
+                    this.user = payload.d.user;
                     logger_1.logger.info(`Session READY. Session ID: ${this.sessionId}. Resume URL set.`);
-                    this.resolveReady();
+                    this.resolveReady(this.user);
                 }
                 else if (payload.t === 'RESUMED') {
                     logger_1.logger.info('The session has been successfully resumed.');
-                    this.resolveReady();
+                    if (this.user) {
+                        this.resolveReady(this.user);
+                    }
                 }
                 break;
             case OpCode_1.OpCode.HEARTBEAT_ACK:
@@ -211,7 +241,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 +261,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 +277,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 +287,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 +303,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,17 +15,100 @@ 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 declare enum UserFlags {
+    STAFF = 1,
+    PARTNER = 2,
+    HYPESQUAD = 4,
+    BUG_HUNTER_LEVEL_1 = 8,
+    HYPESQUAD_ONLINE_HOUSE_1 = 64,// Bravery
+    HYPESQUAD_ONLINE_HOUSE_2 = 128,// Brilliance
+    HYPESQUAD_ONLINE_HOUSE_3 = 256,// Balance
+    PREMIUM_EARLY_SUPPORTER = 512,
+    TEAM_PSEUDO_USER = 1024,
+    BUG_HUNTER_LEVEL_2 = 16384,
+    VERIFIED_BOT = 65536,
+    VERIFIED_DEVELOPER = 131072,
+    CERTIFIED_MODERATOR = 262144,
+    BOT_HTTP_INTERACTIONS = 524288,
+    ACTIVE_DEVELOPER = 4194304
+}
+export interface DiscordUser {
+    id: string;
+    username: string;
+    discriminator: string;
+    global_name?: string | null;
+    avatar?: string | null;
+    bot?: boolean;
+    system?: boolean;
+    mfa_enabled?: boolean;
+    banner?: string | null;
+    accent_color?: number | null;
+    locale?: string;
+    verified?: boolean;
+    email?: string | null;
+    flags?: number;
+    premium_type?: number;
+    public_flags?: number;
+    bio?: string;
+    phone?: string | null;
+    nsfw_allowed?: boolean;
+    pronouns?: string;
+    mobile?: boolean;
+    desktop?: boolean;
+    clan?: {
+        tag: string;
+        identity_guild_id: string;
+        badge: string;
+        identity_enabled?: boolean;
+    } | null;
+    primary_guild?: {
+        tag: string;
+        identity_guild_id: string;
+        badge: string;
+        identity_enabled?: boolean;
+    } | null;
+    purchased_flags?: number;
+    premium_usage_flags?: number;
+    premium?: boolean;
+    premium_state?: {
+        premium_subscription_type?: number;
+        premium_subscription_group_role?: number;
+        premium_source?: number;
+    } | null;
+    avatar_decoration_data?: {
+        asset: string;
+        sku_id: string;
+        expires_at: number | null;
+    } | null;
+    collectibles?: {
+        nameplate?: {
+            asset: string;
+            label: string;
+            sku_id: string;
+            palette?: string;
+            expires_at?: number | null;
+        };
+    } | null;
+    display_name_styles?: {
+        font_id?: number;
+        effect_id?: number;
+        colors?: number[];
+    } | null;
+    banner_color?: string | null;
+    age_verification_status?: number;
+}
 export interface Activity {
     name: string;
     type: number;
@@ -34,6 +117,8 @@ export interface Activity {
     state?: string;
     platform?: string;
     instance?: boolean;
+    flags?: number;
+    sync_id?: string;
     party?: {
         id?: string;
         size?: [number, number];
@@ -48,6 +133,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/gateway/entities/types.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ActivityType = void 0;
+exports.UserFlags = exports.ActivityType = void 0;
 var ActivityType;
 (function (ActivityType) {
     ActivityType[ActivityType["Playing"] = 0] = "Playing";
@@ -10,3 +10,21 @@ var ActivityType;
     ActivityType[ActivityType["Custom"] = 4] = "Custom";
     ActivityType[ActivityType["Competing"] = 5] = "Competing";
 })(ActivityType || (exports.ActivityType = ActivityType = {}));
+var UserFlags;
+(function (UserFlags) {
+    UserFlags[UserFlags["STAFF"] = 1] = "STAFF";
+    UserFlags[UserFlags["PARTNER"] = 2] = "PARTNER";
+    UserFlags[UserFlags["HYPESQUAD"] = 4] = "HYPESQUAD";
+    UserFlags[UserFlags["BUG_HUNTER_LEVEL_1"] = 8] = "BUG_HUNTER_LEVEL_1";
+    UserFlags[UserFlags["HYPESQUAD_ONLINE_HOUSE_1"] = 64] = "HYPESQUAD_ONLINE_HOUSE_1";
+    UserFlags[UserFlags["HYPESQUAD_ONLINE_HOUSE_2"] = 128] = "HYPESQUAD_ONLINE_HOUSE_2";
+    UserFlags[UserFlags["HYPESQUAD_ONLINE_HOUSE_3"] = 256] = "HYPESQUAD_ONLINE_HOUSE_3";
+    UserFlags[UserFlags["PREMIUM_EARLY_SUPPORTER"] = 512] = "PREMIUM_EARLY_SUPPORTER";
+    UserFlags[UserFlags["TEAM_PSEUDO_USER"] = 1024] = "TEAM_PSEUDO_USER";
+    UserFlags[UserFlags["BUG_HUNTER_LEVEL_2"] = 16384] = "BUG_HUNTER_LEVEL_2";
+    UserFlags[UserFlags["VERIFIED_BOT"] = 65536] = "VERIFIED_BOT";
+    UserFlags[UserFlags["VERIFIED_DEVELOPER"] = 131072] = "VERIFIED_DEVELOPER";
+    UserFlags[UserFlags["CERTIFIED_MODERATOR"] = 262144] = "CERTIFIED_MODERATOR";
+    UserFlags[UserFlags["BOT_HTTP_INTERACTIONS"] = 524288] = "BOT_HTTP_INTERACTIONS";
+    UserFlags[UserFlags["ACTIVE_DEVELOPER"] = 4194304] = "ACTIVE_DEVELOPER";
+})(UserFlags || (exports.UserFlags = UserFlags = {}));

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.
@@ -25,90 +42,126 @@ export declare class HieuxyzRPC {
      */
     private resolvedAssetsCache;
     private renewalInterval;
+    /**
+     * Cache for Application Assets (Bot Assets).
+     * Map<ApplicationID, Map<AssetName, AssetID>>
+     */
+    private applicationAssetsCache;
     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, Asset Name 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, Asset Name 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 +170,7 @@ export declare class HieuxyzRPC {
     clearTimestamps(): this;
     clearParty(): this;
     clearButtons(): this;
+    clearSecrets(): this;
     clearInstance(): this;
     clearLargeImage(): this;
     clearSmallImage(): this;
@@ -127,6 +181,10 @@ export declare class HieuxyzRPC {
      * Stops the background process that checks for asset renewal.
      */
     stopBackgroundRenewal(): void;
+    /**
+     * Ensure assets are fetched for the current application ID.
+     */
+    private ensureAppAssetsLoaded;
     private resolveImage;
     private buildActivity;
     /**