steam_api_client 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 63721ffd174da8e4b24173f6507837633cf1930945bb2378228a04cced136099
-  data.tar.gz: 1f4d9e6348bff39b44d7c09289ce74083eebb74e620cbba9020efc1a413f9530
+  metadata.gz: 05561b6cbe30e78afaa9c6f67481698c938c95af7ad492b8296c88e07a2ef5bd
+  data.tar.gz: f14bb719c36232e629d71d80d9ba8bc3592c84855125deeb8cee9db965c3db3a
 SHA512:
-  metadata.gz: aa49878ef1061a3b417924c89a6a8453404a70db5e5287205c1c19b3427ac9c82028574fcbfbba58a739ae0549f73222c4e5246ddf65a93687ba0a7d05168e07
-  data.tar.gz: 65dd3ce130994fb54155f674347da656f61231c4b9025bcd84625540f19173c247a809a92a1eab223ae6daf2f5470b7e2c481a9778c7c1918189b1a9f447a5ba
+  metadata.gz: a8c5a13773d8f57a6bb124adaae1d3dc282026cda3ec066900fb461fdd23b773617f3953b46f8b9715d8881eb9833434ee2101e1044e9f9aafd14cfe3dcb5299
+  data.tar.gz: 3a7ff5be8ca4685d81203f58182c769297390803406ce97b9512572b2cbd1a5e31a1fe55665bc58be07426d47d5981b7d7deac889ad7777a668d782b3f42a0c2

data/CHANGELOG.md

@@ -6,6 +6,18 @@ 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
+
+- `app_schema`: the achievements and stats an app defines, with display names, descriptions, icons and the hidden flag (#105).
+
 ## [1.3.0] - 2026-11-02
 
 ### Added
@@ -216,7 +228,9 @@ 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.3.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
 [1.1.0]: https://github.com/jpechaves/steam_api/compare/v1.0.0...v1.1.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.
@@ -329,6 +356,28 @@ client.app_global_achievements.retrieve(appid: 440).first
 # => #<data SteamApiClient::GlobalAchievement name="TF_SCOUT_LONG_DISTANCE_RUNNER", percent=49.5>
 ```
 
+#### `app_schema`
+
+🔑 The achievements and stats an app defines, with display names, descriptions and icons in the requested language. `locale:` defaults to `"english"` (Steam's language names, e.g. `"portuguese"`). `nil` when the app has neither.
+
+```ruby
+schema = client.app_schema.retrieve(appid: 620)
+schema.game_name # => "Portal 2"
+schema.achievements.first
+# => #<data SteamApiClient::AppSchema::Achievement name="ACH.SURVIVE_CONTAINER_RIDE", display_name="Wake Up Call",
+#     description="Survive the manual override", hidden=false, icon="https://...jpg", icon_gray="https://..._BW.jpg", default_value=0>
+schema.stats.first # => #<data SteamApiClient::AppSchema::Stat name="PS3.SP.progress", display_name=nil, default_value=0>
+```
+
+Achievement `name`s are the API names `player_achievements` and `app_global_achievements` return, so the schema adds display names and icons to them:
+
+```ruby
+titles = schema.achievements.to_h { [_1.name, _1.display_name] }
+client.player_achievements.retrieve(appid: 620, steamid: id).achievements.select(&:achieved).map { titles[_1.api_name] }
+```
+
+Hidden achievements usually have no `description` (`nil`). `game_name` is often `""` or an internal name. An unknown app raises `Errors::HttpBadRequest`, and an unreleased one `Errors::HttpForbidden`.
+
 #### `game_current_players`
 
 The number of players in a game right now.
@@ -419,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

@@ -57,6 +57,17 @@ module SteamApiClient
         }
       ),
 
+      # The achievements and stats an app defines => AppSchema, or nil when it has none
+      # @see https://steamapi.xpaw.me/#ISteamUserStats/GetSchemaForGame
+      Endpoint.new(
+        :app_schema, "ISteamUserStats/GetSchemaForGame/v0002/", returns: AppSchema, at: %i[game],
+        params: {
+          appid: param.integer,
+          # Language of the display names and descriptions, e.g. "portuguese"
+          locale: param.string(as: :l, default: "english")
+        }
+      ),
+
       # The apps featured on the store's front page => Featured
       # @see https://wiki.teamfortress.com/wiki/User:RJackson/StorefrontAPI#featured
       Endpoint.new(
@@ -105,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/app_schema.rb

@@ -0,0 +1,37 @@
+module SteamApiClient
+  # Built first, then named under AppSchema below
+  achievement = Model.define(
+    # The API name, as in `player_achievements` and `app_global_achievements`
+    name: :string,
+    # In the requested language
+    display_name: [:string, from: :displayName],
+    # nil for most hidden achievements
+    description: [:string, optional: true],
+    # Hidden until unlocked
+    hidden: :boolean,
+    # Icon URLs, unlocked and locked
+    icon: [:string, optional: true],
+    icon_gray: [:string, from: :icongray, optional: true],
+    default_value: [:integer, from: :defaultvalue, optional: true]
+  )
+  stat = Model.define(
+    # A game-defined stat, as in `player_game_stats`
+    name: :string,
+    # Often the same as the name, or ""
+    display_name: [:string, from: :displayName, optional: true],
+    # Integer or Float, as Steam sends it
+    default_value: [:number, from: :defaultvalue, optional: true]
+  )
+
+  # The achievements and stats an app defines, from `app_schema`
+  # @see https://steamapi.xpaw.me/#ISteamUserStats/GetSchemaForGame
+  AppSchema = Model.define(
+    # Often "" or an internal name like "ValveTestApp260"
+    game_name: [:string, from: :gameName, optional: true],
+    game_version: [:string, from: :gameVersion, optional: true],
+    achievements: [[achievement], from: %i[availableGameStats achievements], default: []],
+    stats: [[stat], from: %i[availableGameStats stats], default: []]
+  )
+  AppSchema.const_set(:Achievement, achievement)
+  AppSchema.const_set(:Stat, stat)
+end

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.3.0"
+  VERSION = "1.5.0"
 end

data/lib/steam_api_client.rb

@@ -23,12 +23,15 @@ 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"
 require_relative "steam_api_client/models/player_game_stats"
 require_relative "steam_api_client/models/news_item"
 require_relative "steam_api_client/models/global_achievement"
+require_relative "steam_api_client/models/app_schema"
 require_relative "steam_api_client/models/app_details"
 require_relative "steam_api_client/models/package_details"
 require_relative "steam_api_client/models/app_dlc"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: steam_api_client
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.5.0
 platform: ruby
 authors:
 - João Pedro
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-11-02 00:00:00.000000000 Z
+date: 2026-11-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -55,6 +55,7 @@ files:
 - lib/steam_api_client/model/scalars.rb
 - lib/steam_api_client/models/app_details.rb
 - lib/steam_api_client/models/app_dlc.rb
+- lib/steam_api_client/models/app_schema.rb
 - lib/steam_api_client/models/featured.rb
 - lib/steam_api_client/models/featured_categories.rb
 - lib/steam_api_client/models/featured_item.rb
@@ -64,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