feat(api): enhance friends API with persona state and game info

Author: Armaldio

client.d.ts

@@ -79,9 +79,29 @@ export declare namespace cloud {
   }
 }
 export declare namespace friends {
+  export const enum PersonaState {
+    Offline = 0,
+    Online = 1,
+    Busy = 2,
+    Away = 3,
+    Snooze = 4,
+    LookingToTrade = 5,
+    LookingToPlay = 6,
+    Invisible = 7
+  }
+  export interface FriendGameInfo {
+    gameId: bigint
+    gameIp: string
+    gamePort: number
+    queryPort: number
+    lobbyId: bigint
+  }
   export interface Friend {
     steamId: bigint
     name: string
+    nickname?: string
+    state: PersonaState
+    gamePlayed?: FriendGameInfo
   }
   export const enum FriendFlags {
     None = 0,
@@ -98,33 +118,28 @@ export declare namespace friends {
    * Get an array of friends matching the provided flags.
    *
    * @param flags - The flags to filter friends by.
-   * @returns An array of friend objects containing steamId and name.
+   * @returns An array of friend objects containing steamId, name, nickname, state and gamePlayed.
    *
    * @example
    * ```js
    * const friends = client.friends.getFriends(client.friends.FriendFlags.Immediate)
    * console.log(friends)
-   * // Output:
-   * // [
-   * //   { steamId: 76561197985341433n, name: 'MaD_SpY' },
-   * //   { steamId: 76561198034399293n, name: 'BladeSmith' },
-   * // ]
    * ```
    */
   export function getFriends(flags: number): Array<Friend>
   /**
-   * Get the persona name of a friend.
+   * Get the name of a friend.
    *
    * @param steam_id64 - The Steam ID of the friend.
    * @returns The name of the friend.
    *
    * @example
    * ```js
-   * const name = client.friends.getFriendPersonaName(76561197985341433n)
-   * console.log(name) // 'MaD_SpY'
+   * const name = client.friends.getFriendName(76561197985341433n)
+   * console.log(name)
    * ```
    */
-  export function getFriendPersonaName(steamId64: bigint): string
+  export function getFriendName(steamId64: bigint): string
 }
 export declare namespace input {
   export const enum InputType {

src/api/friends.rs

@@ -5,10 +5,34 @@ pub mod friends {
     use napi::bindgen_prelude::BigInt;
     use steamworks::SteamId;
 
+    #[napi]
+    pub enum PersonaState {
+        Offline = 0,
+        Online = 1,
+        Busy = 2,
+        Away = 3,
+        Snooze = 4,
+        LookingToTrade = 5,
+        LookingToPlay = 6,
+        Invisible = 7,
+    }
+
+    #[napi(object)]
+    pub struct FriendGameInfo {
+        pub game_id: BigInt,
+        pub game_ip: String,
+        pub game_port: u32,
+        pub query_port: u32,
+        pub lobby_id: BigInt,
+    }
+
     #[napi(object)]
     pub struct Friend {
         pub steam_id: BigInt,
         pub name: String,
+        pub nickname: Option<String>,
+        pub state: PersonaState,
+        pub game_played: Option<FriendGameInfo>,
     }
 
     #[napi]
@@ -27,17 +51,12 @@ pub mod friends {
     /// Get an array of friends matching the provided flags.
     ///
     /// @param flags - The flags to filter friends by.
-    /// @returns An array of friend objects containing steamId and name.
+    /// @returns An array of friend objects containing steamId, name, nickname, state and gamePlayed.
     ///
     /// @example
     /// ```js
     /// const friends = client.friends.getFriends(client.friends.FriendFlags.Immediate)
     /// console.log(friends)
-    /// // Output:
-    /// // [
-    /// //   { steamId: 76561197985341433n, name: 'XXX' },
-    /// //   { steamId: 76561198034399293n, name: 'YYY' },
-    /// // ]
     /// ```
     #[napi]
     pub fn get_friends(flags: i32) -> Vec<Friend> {
@@ -50,11 +69,28 @@ pub mod friends {
             .map(|f| Friend {
                 steam_id: BigInt::from(f.id().raw()),
                 name: f.name(),
+                nickname: f.nick_name(),
+                state: match f.state() {
+                    steamworks::FriendState::Offline => PersonaState::Offline,
+                    steamworks::FriendState::Online => PersonaState::Online,
+                    steamworks::FriendState::Busy => PersonaState::Busy,
+                    steamworks::FriendState::Away => PersonaState::Away,
+                    steamworks::FriendState::Snooze => PersonaState::Snooze,
+                    steamworks::FriendState::LookingToTrade => PersonaState::LookingToTrade,
+                    steamworks::FriendState::LookingToPlay => PersonaState::LookingToPlay,
+                },
+                game_played: f.game_played().map(|g| FriendGameInfo {
+                    game_id: BigInt::from(g.game.raw()),
+                    game_ip: g.game_address.to_string(),
+                    game_port: g.game_port as u32,
+                    query_port: g.query_port as u32,
+                    lobby_id: BigInt::from(g.lobby.raw()),
+                }),
             })
             .collect()
     }
 
-    /// Get the persona name of a friend.
+    /// Get the name of a friend.
     ///
     /// @param steam_id64 - The Steam ID of the friend.
     /// @returns The name of the friend.

test/friends.js

@@ -5,32 +5,60 @@ try {
     const friends = client.friends
 
     console.log('Testing Friends API...')
-    
+
     // Test FriendFlags existence
     if (!friends.FriendFlags) {
         throw new Error('FriendFlags is missing')
     }
     console.log('✓ FriendFlags found')
 
+
+    // Test PersonaState existence
+    if (!friends.PersonaState) {
+        throw new Error('PersonaState is missing')
+    }
+    console.log('✓ PersonaState found')
+
     // Test getFriends
     const friendList = friends.getFriends(friends.FriendFlags.Immediate)
     console.log(`✓ getFriends returned ${friendList.length} friends`)
 
     if (friendList.length > 0) {
         const firstFriend = friendList[0]
-        
+
         // Test Friend object structure
         if (typeof firstFriend.steamId !== 'bigint' || typeof firstFriend.name !== 'string') {
             throw new Error('Invalid Friend object structure')
         }
+
+        if (typeof firstFriend.state !== 'number') {
+            throw new Error('New Friend object property (state) is invalid or missing')
+        }
+
+        // nickname is optional
+        if (firstFriend.nickname !== undefined && firstFriend.nickname !== null) {
+            if (typeof firstFriend.nickname !== 'string') {
+                throw new Error('Invalid nickname type')
+            }
+            console.log(`✓ Friend has a nickname: ${firstFriend.nickname}`)
+        }
+
+        // gamePlayed is optional
+        if (firstFriend.gamePlayed !== undefined && firstFriend.gamePlayed !== null) {
+            if (typeof firstFriend.gamePlayed.gameId !== 'bigint' || typeof firstFriend.gamePlayed.gameIp !== 'string') {
+                throw new Error('Invalid FriendGameInfo structure in gamePlayed')
+            }
+            console.log('✓ Friend is in-game, gamePlayed structure is valid')
+        }
+
         console.log('✓ Friend object structure is valid')
 
-        // Test getFriendPersonaName
-        const personaName = friends.getFriendPersonaName(firstFriend.steamId)
-        if (personaName !== firstFriend.name) {
-            throw new Error(`Persona name mismatch: expected ${firstFriend.name}, got ${personaName}`)
+        // Test getFriendName
+        const name = friends.getFriendName(firstFriend.steamId)
+        if (name !== firstFriend.name) {
+            throw new Error(`Name mismatch: expected ${firstFriend.name}, got ${name}`)
         }
-        console.log(`✓ getFriendPersonaName returned correct name: ${personaName}`)
+        console.log(`✓ getFriendName returned correct name: ${name}`)
     } else {
         console.log('! No friends found to test individual properties, but getFriends call succeeded.')
     }