Merge branch 'master' into 62-update-steamserver-requires-admin

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-SteamFriendList.ps1

@@ -1,39 +1,30 @@
 function Get-SteamFriendList {
     <#
     .SYNOPSIS
-    Returns the friend list of any Steam user.
+    Fetches the friend list of tje specified Steam user.
 
     .DESCRIPTION
-    Retrieves the friend list of a Steam user whose profile visibility is set to "Public".
+    This cmdlet fetches the friend list of a Steam user using the provided SteamID64. It retrieves data only from public profiles.
 
     .PARAMETER SteamID64
-    Specifies the 64-bit Steam ID of the user whose friend list will be retrieved.
+    The 64-bit Steam ID of the user whose friend list is to be fetched.
 
     .PARAMETER Relationship
-    Specifies the relationship type to filter the friend list. Possible values are 'all' or 'friend'. Default is 'friend'.
-
-    .PARAMETER OutputFormat
-    Specifies the format of the output. Options are 'json' (default), 'xml', or 'vdf'.
+    The relationship type used to filter the friend list. The possible values are 'all' or 'friend'. The default is 'friend'.
 
     .EXAMPLE
     Get-SteamFriendList -SteamID64 76561197960435530
-
-    Retrieves the friend list of the specified user.
-
-    .EXAMPLE
-    Get-SteamFriendList -SteamID64 76561197960435530 -OutputFormat xml
-
-    Retrieves the friend list of the specified user and outputs it in XML format.
+    This example fetches the friend list of the user with the specified SteamID64.
 
     .INPUTS
     System.Int64
 
     .OUTPUTS
-    Returns a string formatted as JSON, XML, or VDF representing the user's friend list.
-    The friend list contains the following properties:
-    - steamid: 64-bit Steam ID of the friend.
-    - relationship: Relationship qualifier.
-    - friend_since: Unix timestamp of when the relationship was established.
+    Outputs a string formatted as JSON, XML, or VDF representing the user's friend list.
+    The friend list includes the following properties:
+    - steamid: The friend's 64-bit Steam ID.
+    - relationship: The qualifier of the relationship.
+    - friend_since: The Unix timestamp indicating when the relationship was established.
 
     .NOTES
     Author: Frederik Hjorslev Nylander
@@ -52,22 +43,38 @@
         [Parameter(Mandatory = $false,
             HelpMessage = 'Specifies the relationship type to filter the friend list. Possible values are "all" or "friend". Default is "friend".')]
         [ValidateSet('all', 'friend')]
-        [string]$Relationship = 'friend',
-
-        [Parameter(Mandatory = $false,
-            HelpMessage = 'Specifies the format of the output. Options are "json" (default), "xml", or "vdf".')]
-        [ValidateSet('json', 'xml', 'vdf')]
-        [string]$OutputFormat = 'json'
+        [string]$Relationship = 'friend'
     )
 
     begin {
         Write-Verbose -Message "[BEGIN  ] Starting: $($MyInvocation.MyCommand)"
     }
 
     process {
-        $Request = Invoke-WebRequest -Uri "https://api.steampowered.com/ISteamUser/GetFriendList/v1/?key=$(Get-SteamAPIKey)&steamid=$SteamID64&relationship=$Relationship&format=$OutputFormat" -UseBasicParsing
-
-        Write-Output -InputObject $Request.Content
+        $Request = Invoke-RestMethod -Uri 'https://api.steampowered.com/ISteamUser/GetFriendList/v1/' -UseBasicParsing -ErrorAction SilentlyContinue -Body @{
+            key          = Get-SteamAPIKey
+            steamid      = $SteamID64
+            relationship = $Relationship
+        }
+
+        if ($Request) {
+            foreach ($Item in $Request.friendslist.friends) {
+                [PSCustomObject]@{
+                    SteamID64    = [int64]$Item.steamid
+                    Relationship = $Item.relationship
+                    FriendSince  = ((Get-Date "01.01.1970") + ([System.TimeSpan]::FromSeconds($Item.friend_since))).ToString("yyyy-MM-dd HH:mm:ss")
+                }
+            }
+        } elseif ($null -eq $Request) {
+            $Exception = [Exception]::new("No friend list found for $SteamID64. This might be because the profile is private.")
+            $ErrorRecord = [System.Management.Automation.ErrorRecord]::new(
+                $Exception,
+                'NoFriendsListFound',
+                [System.Management.Automation.ErrorCategory]::ObjectNotFound,
+                $Request
+            )
+            $PSCmdlet.WriteError($ErrorRecord)
+        }
     } # Process
 
     end {

SteamPS/Public/API/Get-SteamNews.ps1

@@ -1,50 +1,54 @@
 function Get-SteamNews {
     <#
     .SYNOPSIS
-    Returns the latest news of a game specified by its AppID.
+    Fetches the latest news for a game using its AppID.
 
     .DESCRIPTION
-    Returns the latest news of a game specified by its AppID.
+    Fetches the latest news for a game using its AppID from the Steam API.
 
     .PARAMETER AppID
-    AppID of the game you want the news of.
+    The AppID of the game for which the news is to be fetched.
 
     .PARAMETER Count
-    How many news entries you want to get returned.
+    The number of news entries to fetch. By default, it fetches all news entries.
 
     .PARAMETER MaxLength
-    Maximum length of each news entry.
-
-    .PARAMETER OutputFormat
-    Format of the output. Options are json (default), xml or vdf.
+    The maximum length for each news entry. Entries longer than this will be truncated. By default, there is no truncation.
 
     .EXAMPLE
     Get-SteamNews -AppID 440
 
-    Lists number of news that are available for the AppID.
+    This example fetches all available news entries for the game with AppID 440.
 
     .EXAMPLE
     Get-SteamNews -AppID 440 -Count 1
 
-    Retrieves 1 (the latest) news item for the AppID 440.
-
-    .INPUTS
-    int64
+    This example fetches the most recent news entry for the game with AppID 440.
 
-    .OUTPUTS
-    Returns a string that is either formatted as json, xml or vdf.
+    .EXAMPLE
+    Get-SteamNews -AppID 440 -MaxLength 100
 
-    An appnews object containing:
+    This example fetches all available news entries for the game with AppID 440 and truncates the news content to 100 characters.
 
-    appid, the AppID of the game you want news of
+    .INPUTS
+    System.Int32
 
-    newsitems, an array of news item information:
-    - An ID, title and url.
-    - A shortened excerpt of the contents (to maxlength characters), terminated by "..." if longer than maxlength.
-    - A comma-separated string of labels and UNIX timestamp.
+    .OUTPUTS
+    Outputs an object containing:
+    - GID: The ID of the news item.
+    - Title: The title of the news item.
+    - Url: The URL of the news item.
+    - IsExternalUrl: A boolean indicating if the URL is external.
+    - Author: The author of the news item.
+    - Contents: The content of the news item.
+    - FeedLabel: The label of the news feed.
+    - Date: The date and time when the news item was published.
+    - FeedName: The name of the news feed.
+    - FeedType: The type of the news feed.
+    - AppID: The AppID of the game associated with the news item.
 
     .NOTES
-    Author: Frederik Hjorslelv Nylander
+    Author: Frederik Hjorslev Nylander
 
     .LINK
     https://hjorslev.github.io/SteamPS/Get-SteamNews.html
@@ -53,31 +57,63 @@
     [CmdletBinding()]
     param (
         [Parameter(Mandatory = $true,
-            HelpMessage = 'AppID of the game you want the news of.')]
+            HelpMessage = 'Specifies the AppID of the game for which you want to retrieve news.')]
         [int]$AppID,
 
         [Parameter(Mandatory = $false,
-            HelpMessage = 'How many news entries you want to get returned.')]
+            HelpMessage = 'Specifies the number of news entries to retrieve.')]
         [int]$Count,
 
         [Parameter(Mandatory = $false,
-            HelpMessage = 'Maximum length of each news entry.')]
-        [int]$MaxLength,
-
-        [Parameter(Mandatory = $false,
-            HelpMessage = 'Format of the output. Options are json (default), xml or vdf.')]
-        [ValidateSet('json', 'xml', 'vdf')]
-        [string]$OutputFormat = 'json'
+            HelpMessage = 'Specifies the maximum length of each news entry.')]
+        [int]$MaxLength
     )
 
+
     begin {
         Write-Verbose -Message "[BEGIN  ] Starting: $($MyInvocation.MyCommand)"
     }
 
     process {
-        $Request = Invoke-WebRequest -Uri "http://api.steampowered.com/ISteamNews/GetNewsForApp/v0002/?appid=$AppID&count=$Count&maxlength=$MaxLength&format=$OutputFormat" -UseBasicParsing
-
-        Write-Output -InputObject $Request.Content
+        # TODO: When only supporting pwsh use null coalescing operator (??)
+        # to handle the case when $Count or $MaxLength is not defined
+        $Body = @{
+            appid = $AppID
+        }
+        if ($Count) {
+            $Body.Add('count', $Count)
+        }
+        if ($MaxLength) {
+            $Body.Add('maxlength', $MaxLength)
+        }
+        $Request = Invoke-RestMethod -Uri 'http://api.steampowered.com/ISteamNews/GetNewsForApp/v0002/' -UseBasicParsing -Body $Body
+
+        if ($Request) {
+            foreach ($Item in $Request.appnews.newsitems) {
+                [PSCustomObject]@{
+                    GID           = [int64]$Item.gid
+                    Title         = $Item.title
+                    Url           = $Item.url
+                    IsExternalUrl = [bool]$Item.is_external_url
+                    Author        = $Item.author
+                    Contents      = $Item.contents
+                    FeedLabel     = $Item.feedlabel
+                    Date          = ((Get-Date "01.01.1970") + ([System.TimeSpan]::FromSeconds($Item.date))).ToString("yyyy-MM-dd HH:mm:ss")
+                    FeedName      = $Item.feedname
+                    FeedType      = $Item.feed_type
+                    AppID         = $Item.appid
+                }
+            }
+        } elseif ($null -eq $Request) {
+            $Exception = [Exception]::new("No news found for $AppID.")
+            $ErrorRecord = [System.Management.Automation.ErrorRecord]::new(
+                $Exception,
+                'NoNewsFound',
+                [System.Management.Automation.ErrorCategory]::ObjectNotFound,
+                $Request
+            )
+            $PSCmdlet.WriteError($ErrorRecord)
+        }
     } # Process
 
     end {

SteamPS/Public/API/Get-SteamPlayerBan.ps1

@@ -1,34 +1,32 @@
 function Get-SteamPlayerBan {
     <#
-    .SYNOPSIS
-    Returns Community, VAC, and Economy ban statuses for given players.
+.SYNOPSIS
+    Fetches ban information for Steam players.
 
     .DESCRIPTION
-    Returns Community, VAC, and Economy ban statuses for given players.
+    This cmdlet fetches ban information for Steam players. The information includes whether the players are banned from the Steam Community, have VAC bans, the number of VAC bans, days since the last ban, number of game bans, and economy ban status.
 
     .PARAMETER SteamID64
-    Comma-delimited list of 64 bit Steam IDs to return player ban information for.
-
-    .PARAMETER OutputFormat
-    Format of the output. Options are json (default), xml or vdf.
+    Specifies one or more 64-bit Steam IDs for which to fetch ban information. Enter the Steam IDs as a comma-separated list.
 
     .EXAMPLE
-    Get-SteamPlayerBan -SteamID64 76561197960435530, 76561197960434622
+    Get-SteamPlayerBan -SteamID64 76561197960435530,76561197960434622
+
+    This example fetches ban 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 objects with the following properties:
 
-    players: List of player ban objects for each 64 bit ID requested
-    - SteamId (string) The player's 64 bit ID.
-    - CommunityBanned (bool) Indicates whether or not the player is banned from Steam Community.
-    - VACBanned (bool) Indicates whether or not the player has VAC bans on record.
-    - NumberOfVACBans (int) Number of VAC bans on record.
-    - DaysSinceLastBan (int) Number of days since the last ban.
-    - NumberOfGameBans (int) Number of bans in games, this includes CS:GO Overwatch bans.
-    - EconomyBan (string) The player's ban status in the economy. If the player has no bans on record the string will be "none", if the player is on probation it will say "probation", etc.
+    - SteamID64: The player's 64-bit ID.
+    - CommunityBanned: A boolean indicating whether the player is banned from the Steam Community.
+    - VACBanned: A boolean indicating whether the player has VAC bans on record.
+    - NumberOfVACBans: The number of VAC bans on record.
+    - DaysSinceLastBan: The number of days since the last ban.
+    - NumberOfGameBans: The number of bans in games, including CS:GO Overwatch bans.
+    - EconomyBan: The player's ban status in the economy. If the player has no bans on record, the string will be "none". If the player is on probation, it will say "probation", etc.
 
     .NOTES
     Author: Frederik Hjorslev Nylander
@@ -42,22 +40,41 @@
         [Parameter(Mandatory = $true,
             HelpMessage = '64 bit Steam ID to return player bans 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/GetPlayerBans/v1/?format=$OutputFormat&key=$(Get-SteamAPIKey)&steamids=$($SteamID64 -join ',')" -UseBasicParsing
+        $Request = Invoke-RestMethod -Uri 'https://api.steampowered.com/ISteamUser/GetPlayerBans/v1/' -UseBasicParsing -Body @{
+            key      = Get-SteamAPIKey
+            steamids = ($SteamID64 -join ',')
+        }
 
-        Write-Output -InputObject $Request.Content
+        if (-not [string]::IsNullOrEmpty($Request.players.SteamId)) {
+            foreach ($Item in $Request.players) {
+                [PSCustomObject]@{
+                    SteamID64        = [int64]$Item.SteamId
+                    CommunityBanned  = $Item.CommunityBanned
+                    VACBanned        = $Item.VACBanned
+                    NumberOfVACBans  = $Item.NumberOfVACBans
+                    DaysSinceLastBan = $Item.DaysSinceLastBan
+                    NumberOfGameBans = $Item.NumberOfGameBans
+                    EconomyBan       = $Item.EconomyBan
+                }
+            }
+        } elseif ([string]::IsNullOrEmpty($Request.players)) {
+            $Exception = [Exception]::new("SteamID $SteamID64 couldn't be found.")
+            $ErrorRecord = [System.Management.Automation.ErrorRecord]::new(
+                $Exception,
+                'PlayerNotFound',
+                [System.Management.Automation.ErrorCategory]::ObjectNotFound,
+                $Request
+            )
+            $PSCmdlet.WriteError($ErrorRecord)
+        }
     } # Process
 
     end {