steam_api_client 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0b06cbf7dc49fbd605cab7c84469fd11a1bde80779469db95bbe30b5867701d
-  data.tar.gz: 5b32661f36c1ad7495760925e0348f5778933bd647f0f876b3bdbfdcc8a621df
+  metadata.gz: 05561b6cbe30e78afaa9c6f67481698c938c95af7ad492b8296c88e07a2ef5bd
+  data.tar.gz: f14bb719c36232e629d71d80d9ba8bc3592c84855125deeb8cee9db965c3db3a
 SHA512:
-  metadata.gz: 887564c19ec25082f2498e8f55c2c316b499abd4c19d3bf00ed97206f7c2028fa81e1266649470fd6f2966aa2c39f5f99d8f5726e406d0bd52dfaa787b269c63
-  data.tar.gz: '04545587357f1c91db0e6fa2fb4585c029f9b363aa09c55815d8222d12c39e79190d404a22c9bf38b4df86ed6f75c251d970165a96331519fec24a0dda57de86'
+  metadata.gz: a8c5a13773d8f57a6bb124adaae1d3dc282026cda3ec066900fb461fdd23b773617f3953b46f8b9715d8881eb9833434ee2101e1044e9f9aafd14cfe3dcb5299
+  data.tar.gz: 3a7ff5be8ca4685d81203f58182c769297390803406ce97b9512572b2cbd1a5e31a1fe55665bc58be07426d47d5981b7d7deac889ad7777a668d782b3f42a0c2

data/CHANGELOG.md

@@ -6,6 +6,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-11-04
+
+### Added
+
+- `player_bans` and `player_badges`: VAC, game, community and trade ban status of up to 100 players, and a player's badges and level progress (#106).
+
 ## [1.4.0] - 2026-11-04
 
 ### Added
@@ -222,7 +228,8 @@ The versions below were bumped in `version.rb` during development but **never pu
 
 - Initial gem skeleton.
 
-[Unreleased]: https://github.com/jpechaves/steam_api/compare/v1.4.0...HEAD
+[Unreleased]: https://github.com/jpechaves/steam_api/compare/v1.5.0...HEAD
+[1.5.0]: https://github.com/jpechaves/steam_api/compare/v1.4.0...v1.5.0
 [1.4.0]: https://github.com/jpechaves/steam_api/compare/v1.3.0...v1.4.0
 [1.3.0]: https://github.com/jpechaves/steam_api/compare/v1.2.0...v1.3.0
 [1.2.0]: https://github.com/jpechaves/steam_api/compare/v1.1.0...v1.2.0

data/docs/USAGE.md

@@ -191,6 +191,33 @@ stats.achievements.first # => #<data SteamApiClient::PlayerGameStats::Achievemen
 
 Stat values are Integers or Floats, as the game defines them. A private profile, or a game without stats, raises `Errors::HttpBadRequest`.
 
+#### `player_bans`
+
+🔑 The ban status of up to 100 players. Steam leaves out IDs it doesn't know, and silently ignores IDs after the 100th.
+
+```ruby
+client.player_bans.retrieve(steamids: [76561197960435530, 76561198000000001])
+# => [#<data SteamApiClient::PlayerBan steam_id=76561197960435530, community_banned=false, vac_banned=false, number_of_vac_bans=0,
+#      days_since_last_ban=0, number_of_game_bans=0, economy_ban="none">, ...]
+```
+
+`days_since_last_ban` counts from the last VAC or game ban (`0` when never banned). `number_of_game_bans` are bans set by game developers. `economy_ban` is the trade ban status: `"none"`, `"probation"` or `"banned"`.
+
+#### `player_badges`
+
+🔑 A player's badges and Steam level progress, or `nil` when the profile isn't public.
+
+```ruby
+progress = client.player_badges.retrieve(steamid: 76561198000000001)
+progress.player_level                 # => 157
+progress.player_xp_needed_to_level_up # => 1530
+progress.badges.first
+# => #<data SteamApiClient::PlayerBadges::Badge badge_id=13, level=1280, completion_time=1787785402, xp=1530, scarcity=251922,
+#     app_id=nil, community_item_id=nil, border_color=nil>
+```
+
+`scarcity` is how many players have the badge. Game (trading card) badges also have `app_id`, `community_item_id` and `border_color` (`1` for foil). Times are unix timestamps. An ID that isn't a valid SteamID raises `Errors::HttpBadRequest`.
+
 #### `player_wishlist`
 
 The apps on a player's wishlist. No key needed.
@@ -441,6 +468,6 @@ Don't retry other 4xx errors: they won't succeed on their own.
 
 - **Rate limits.** Steam's [Web API terms](https://steamcommunity.com/dev/apiterms) allow 100,000 calls per day per key. The Storefront API (`app_details`, `package_details`, `app_dlc`, `store_search`, `featured`, `featured_categories`) is rate limited per IP address, commonly reported at about 200 requests per 5 minutes. Both answer `429` when you go over. Cache what you can.
 - **The Storefront API is unofficial.** The Storefront endpoints use the API behind Steam's store and Big Picture mode. Valve doesn't document it, and its fields change without notice.
-- **Private profiles.** What a player hides depends on their privacy settings. Depending on the endpoint, Steam answers with an error (`player_achievements`: 403, `player_game_stats`: 400, `player_friends`: 401) or with empty data, which the gem returns as `nil` or `[]` (`player_owned_games`, `player_recent_games`, `player_level`, `player_wishlist`, `player_wishlist_count`, `player_followed_games`). Steam answers the same way for an empty wishlist, so the wishlist endpoints can't tell the two apart. `player_summaries` still returns the public part of the profile.
+- **Private profiles.** What a player hides depends on their privacy settings. Depending on the endpoint, Steam answers with an error (`player_achievements`: 403, `player_game_stats`: 400, `player_friends`: 401) or with empty data, which the gem returns as `nil` or `[]` (`player_owned_games`, `player_recent_games`, `player_level`, `player_badges`, `player_wishlist`, `player_wishlist_count`, `player_followed_games`). Steam answers the same way for an empty wishlist, so the wishlist endpoints can't tell the two apart. `player_summaries` still returns the public part of the profile.
 - **The key is in the URL.** Steam requires `?key=...` in the query string. Treat logs of request URLs as secrets (see [Configuration](#configuration)), and [rotate your key](https://steamcommunity.com/dev/apikey) if it leaks.
 - **SteamIDs are 64 bit Integers** (e.g. `76561197960435530`). Use `player_steamid` to get one from a vanity URL.

data/lib/steam_api_client/endpoints.rb

@@ -116,6 +116,20 @@ module SteamApiClient
         params: {appid: param.integer, steamid: param.integer}
       ),
 
+      # A player's badges and Steam level progress => PlayerBadges, or nil when the profile isn't public
+      # @see https://steamapi.xpaw.me/#IPlayerService/GetBadges
+      Endpoint.new(
+        :player_badges, "IPlayerService/GetBadges/v1/", returns: PlayerBadges, at: %i[response],
+        params: {steamid: param.integer}
+      ),
+
+      # Ban status of up to 100 players => [PlayerBan] (unknown IDs are left out)
+      # @see https://steamapi.xpaw.me/#ISteamUser/GetPlayerBans
+      Endpoint.new(
+        :player_bans, "ISteamUser/GetPlayerBans/v1/", returns: [PlayerBan], at: %i[players],
+        params: {steamids: param.integer_list}
+      ),
+
       # The apps a player follows in the store => [Integer] app IDs ([] when not public)
       # @see https://steamapi.xpaw.me/#IStoreService/GetGamesFollowed
       Endpoint.new(

data/lib/steam_api_client/models/player_badges.rb

@@ -0,0 +1,29 @@
+module SteamApiClient
+  # Built first, then named PlayerBadges::Badge below
+  badge = Model.define(
+    badge_id: [:integer, from: :badgeid],
+    level: :integer,
+    # In unix time
+    completion_time: :integer,
+    xp: :integer,
+    # How many players have this badge
+    scarcity: :integer,
+    # Only for game badges (trading cards)
+    app_id: [:integer, from: :appid, optional: true],
+    community_item_id: [:integer, from: :communityitemid, optional: true],
+    # 1 for a foil badge
+    border_color: [:integer, optional: true]
+  )
+
+  # A player's badges and Steam level progress, from `player_badges`
+  # @see https://steamapi.xpaw.me/#IPlayerService/GetBadges
+  PlayerBadges = Model.define(
+    player_level: :integer,
+    player_xp: :integer,
+    # The XP where the current level starts, and what's left for the next one
+    player_xp_needed_current_level: :integer,
+    player_xp_needed_to_level_up: :integer,
+    badges: [[badge], default: []]
+  )
+  PlayerBadges.const_set(:Badge, badge)
+end

data/lib/steam_api_client/models/player_ban.rb

@@ -0,0 +1,17 @@
+module SteamApiClient
+  # A player's ban status, from `player_bans`. Steam names these keys in PascalCase.
+  # @see https://steamapi.xpaw.me/#ISteamUser/GetPlayerBans
+  PlayerBan = Model.define(
+    steam_id: [:integer, from: :SteamId],
+    # Banned from the Steam Community
+    community_banned: [:boolean, from: :CommunityBanned],
+    vac_banned: [:boolean, from: :VACBanned],
+    number_of_vac_bans: [:integer, from: :NumberOfVACBans],
+    # Days since the last VAC or game ban (0 when never banned)
+    days_since_last_ban: [:integer, from: :DaysSinceLastBan],
+    # Bans set by game developers
+    number_of_game_bans: [:integer, from: :NumberOfGameBans],
+    # Trade ban status: "none", "probation" or "banned"
+    economy_ban: [:string, from: :EconomyBan]
+  )
+end

data/lib/steam_api_client/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SteamApiClient
-  VERSION = "1.4.0"
+  VERSION = "1.5.0"
 end

data/lib/steam_api_client.rb

@@ -23,6 +23,8 @@ require_relative "steam_api_client/errors/missing_api_token"
 require_relative "steam_api_client/errors/response_parse_error"
 
 require_relative "steam_api_client/models/player_summary"
+require_relative "steam_api_client/models/player_ban"
+require_relative "steam_api_client/models/player_badges"
 require_relative "steam_api_client/models/friend"
 require_relative "steam_api_client/models/game"
 require_relative "steam_api_client/models/player_achievements"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: steam_api_client
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - João Pedro
@@ -65,6 +65,8 @@ files:
 - lib/steam_api_client/models/news_item.rb
 - lib/steam_api_client/models/package_details.rb
 - lib/steam_api_client/models/player_achievements.rb
+- lib/steam_api_client/models/player_badges.rb
+- lib/steam_api_client/models/player_ban.rb
 - lib/steam_api_client/models/player_game_stats.rb
 - lib/steam_api_client/models/player_summary.rb
 - lib/steam_api_client/models/store_search_result.rb