Rework Get-SteamPlayerSummary (#80)

* refactor cmdlet + test cases

* typo

* fix json

* cast dates as datetime

* revert

* fix missing curly bracket

* fix test

* comment based help

SteamPS/Enum/Enum.ps1

@@ -1,4 +1,4 @@
-enum ServerType {
+enum ServerType {
     Dedicated = 0x64    #d
     NonDedicated = 0x6C #l
     SourceTV = 0x70     #p
@@ -18,6 +18,20 @@ enum Visibility {
     Private = 1
 }
 
+enum PersonaState {
+    Offline = 0
+    Online = 1
+    Busy = 2
+    Away = 3
+    Snooze = 4
+    LookingToTrade = 5
+}
+enum CommunityVisibilityState {
+    Private = 1
+    FriendsOnly = 2
+    Public = 3
+}
+
 if ($PSVersionTable.PSVersion.Major -le 5 -and $PSVersionTable.PSVersion.Minor -le 1) {
     Write-Warning -Message "The support for Windows PowerShell (v5) will be deprecated in the next major version of SteamPS. Please ensure your system supports PowerShell 7."
 }

SteamPS/Public/API/Get-SteamPlayerSummary.ps1

@@ -1,34 +1,30 @@
 function Get-SteamPlayerSummary {
     <#
     .SYNOPSIS
-    Returns basic profile information for a list of 64-bit Steam IDs.
+    Fetches basic profile information for a list of 64-bit Steam IDs.
 
     .DESCRIPTION
-    Returns basic profile information for a list of 64-bit Steam IDs.
+    Fetches basic profile information for a list of 64-bit Steam IDs.
 
     .PARAMETER SteamID64
-    Comma-delimited list of 64 bit Steam IDs to return profile information for.
-    Up to 100 Steam IDs can be requested.
-
-    .PARAMETER OutputFormat
-    Format of the output. Options are json (default), xml or vdf.
+    Specifies a comma-separated list of 64-bit Steam IDs to fetch profile information for. Up to 100 Steam IDs can be requested.
 
     .EXAMPLE
     Get-SteamPlayerSummary -SteamID64 76561197960435530, 76561197960434622
 
+    This example fetches profile information for the players with the specified Steam IDs.
+
     .INPUTS
-    Array of int64.
+    int64[]: Specifies an array of 64-bit integers representing Steam IDs.
 
     .OUTPUTS
-    Returns a string that is either formatted as json, xml or vdf.
+    Returns a custom object with the properties listed below.
 
-    Some data associated with a Steam account may be hidden if the user has their
-    profile visibility set to "Friends Only" or "Private". In that case, only
-    public data will be returned.
+    Some data associated with a Steam account may be hidden if the user has their profile visibility set to "Friends Only" or "Private". In that case, only public data will be returned.
 
     Public Data
-    - steamid: 64bit SteamID of the user
-    - personaname: The player's persona name (display name)
+    - steamid: 64-bit SteamID of the user.
+    - personaname: The player's persona name (display name).
     - profileurl: The full URL of the player's Steam Community profile.
     - avatar: The full URL of the player's 32x32px avatar. If the user hasn't configured an avatar, this will be the default ? avatar.
     - avatarmedium: The full URL of the player's 64x64px avatar. If the user hasn't configured an avatar, this will be the default ? avatar.
@@ -63,23 +59,57 @@
         [Parameter(Mandatory = $true,
             HelpMessage = '64 bit Steam ID to return player summary for.',
             ValueFromPipelineByPropertyName = $true)]
-        [int64[]]$SteamID64,
-
-        [Parameter(Mandatory = $false,
-            HelpMessage = 'Format of the output. Options are json (default), xml or vdf.')]
-        [ValidateSet('json', 'xml', 'vdf')]
-        [string]$OutputFormat = 'json'
+        [int64[]]$SteamID64
     )
 
     begin {
         Write-Verbose -Message "[BEGIN  ] Starting: $($MyInvocation.MyCommand)"
     }
 
     process {
-        $Request = Invoke-WebRequest -Uri "https://api.steampowered.com/ISteamUser/GetPlayerSummaries/v2/?format=$OutputFormat&key=$(Get-SteamAPIKey)&steamids=$($SteamID64 -join ',')" -UseBasicParsing
-
-        Write-Output -InputObject $Request.Content
-    }
+        $Request = Invoke-RestMethod -Uri 'https://api.steampowered.com/ISteamUser/GetPlayerSummaries/v2' -UseBasicParsing -Body @{
+            key      = Get-SteamAPIKey
+            steamids = ($SteamID64 -join ',')
+        }
+
+        if ($Request.response.players) {
+            foreach ($Item in $Request.response.players) {
+                [PSCustomObject]@{
+                    SteamID64                = $Item.steamid
+                    PersonaName              = $Item.personaname
+                    ProfileUrl               = $Item.profileurl
+                    Avatar                   = $Item.avatar
+                    AvatarMedium             = $Item.avatarmedium
+                    AvatarFull               = $Item.avatarfull
+                    AvatarHash               = $Item.avatarhash
+                    PersonaState             = [PersonaState]$Item.personastate
+                    CommunityVisibilityState = [CommunityVisibilityState]$Item.communityvisibilitystate
+                    ProfileState             = $Item.profilestate
+                    LastLogOff               = ((Get-Date "01.01.1970") + ([System.TimeSpan]::FromSeconds($Item.lastlogoff))).ToString("yyyy-MM-dd HH:mm:ss")
+                    CommentPermission        = $Item.commentpermission
+                    RealName                 = $Item.realname
+                    PrimaryClanID            = $Item.primaryclanid
+                    TimeCreated              = ((Get-Date "01.01.1970") + ([System.TimeSpan]::FromSeconds($Item.timecreated))).ToString("yyyy-MM-dd HH:mm:ss")
+                    AppID                   = $Item.gameid
+                    GameServerIP             = [ipaddress]$Item.gameserverip
+                    GameExtraInfo            = $Item.gameextrainfo
+                    PersonaStateFlags        = $Item.personastateflags
+                    LocCountryCode           = $Item.loccountrycode
+                    LocStateCode             = $Item.locstatecode
+                    LocCityID                = $Item.loccityid
+                }
+            }
+        } elseif ($Request.response.players.Length -eq 0) {
+            $Exception = [Exception]::new("SteamID $SteamID64 couldn't be found.")
+            $ErrorRecord = [System.Management.Automation.ErrorRecord]::new(
+                $Exception,
+                'NoPlayerFound',
+                [System.Management.Automation.ErrorCategory]::ObjectNotFound,
+                $Request
+            )
+            $PSCmdlet.WriteError($ErrorRecord)
+        }
+    } # Process
 
     end {
         Write-Verbose -Message "[END    ] Ending: $($MyInvocation.MyCommand)"

Tests/Unit/Public/Get-SteamPlayerSummary.Tests.ps1

@@ -0,0 +1,68 @@
+Describe 'Get-SteamPlayerSummary Tests' -Tag 'Unit' {
+    BeforeAll {
+        . $SteamPSModulePath\Private\API\Get-SteamAPIKey.ps1
+        Mock -CommandName Get-SteamAPIKey -ModuleName SteamPS -MockWith {
+            return $true
+        }
+    }
+
+    Context 'With a valid SteamID64' {
+        BeforeAll {
+            Mock -CommandName Invoke-RestMethod -ModuleName SteamPS -MockWith {
+                return '{
+                    "response": {
+                        "players": [
+                            {
+                                "steamid": "12345678901234567",
+                                "communityvisibilitystate": 3,
+                                "profilestate": 1,
+                                "personaname": "TestUser",
+                                "commentpermission": 1,
+                                "profileurl": "https://steamcommunity.com/id/testuser/",
+                                "avatar": "https://example.com/avatar.jpg",
+                                "avatarmedium": "https://example.com/avatar_medium.jpg",
+                                "avatarfull": "https://example.com/avatar_full.jpg",
+                                "avatarhash": "abcdef123456",
+                                "lastlogoff": 1712083677,
+                                "personastate": 1,
+                                "realname": "John Doe",
+                                "primaryclanid": "987654321098765432",
+                                "timecreated": 1577836800,
+                                "gameid": 16900,
+                                "gameserverip": "1.2.3.4",
+                                "gameextrainfo": "Test Game",
+                                "personastateflags": 0,
+                                "loccountrycode": "US",
+                                "locstatecode": "CA",
+                                "loccityid": 54321
+                            }
+                        ]
+                    }
+                }' | ConvertFrom-Json
+            }
+        }
+
+        It 'Should return player summary' {
+            $PlayerSummary = Get-SteamPlayerSummary -SteamID64 12345678901234567
+            $PlayerSummary.SteamID64 | Should -Be '12345678901234567'
+            $PlayerSummary.PersonaState | Should -BeExactly 'Online'
+            $PlayerSummary.CommunityVisibilityState | Should -BeExactly 'Public'
+            $PlayerSummary.LastLogOff | Should -BeExactly '2024-04-02 18:47:57'
+            $PlayerSummary.TimeCreated | Should -BeExactly '2020-01-01 00:00:00'
+            $PlayerSummary.GameServerIP | Should -BeExactly '1.2.3.4'
+            $PlayerSummary.GameServerIP | Should -BeOfType ipaddress
+        }
+    }
+
+    Context 'With an invalid SteamID64' {
+        BeforeAll {
+            Mock -CommandName Invoke-RestMethod -ModuleName SteamPS -MockWith {
+                return '{"response":{"players":[]}}' | ConvertFrom-Json
+            }
+        }
+
+        It 'Should throw an error' {
+            { Get-SteamPlayerSummary -SteamID64 1234567890 -ErrorAction Stop } | Should -Throw "SteamID 1234567890 couldn't be found."
+        }
+    }
+}