steam_api_client 1.4.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0b06cbf7dc49fbd605cab7c84469fd11a1bde80779469db95bbe30b5867701d
-  data.tar.gz: 5b32661f36c1ad7495760925e0348f5778933bd647f0f876b3bdbfdcc8a621df
+  metadata.gz: 410a0d3b36b83ac8888323849214253b0d0ba26501d1218ad7f48176eb8dd2af
+  data.tar.gz: 89f42dc5315420c9cbe41b3bb5b0eb1c511c1ca6c7133d7305c4ec700e1a6f31
 SHA512:
-  metadata.gz: 887564c19ec25082f2498e8f55c2c316b499abd4c19d3bf00ed97206f7c2028fa81e1266649470fd6f2966aa2c39f5f99d8f5726e406d0bd52dfaa787b269c63
-  data.tar.gz: '04545587357f1c91db0e6fa2fb4585c029f9b363aa09c55815d8222d12c39e79190d404a22c9bf38b4df86ed6f75c251d970165a96331519fec24a0dda57de86'
+  metadata.gz: ddff8c5f6b2a3b2e4faf56dccf572dd659517125b0f29a2c224b2eafb782319218c956a1b3cb2c131c988382da58eb05125c84a7bf80eb5de891d8a768cfe8fb
+  data.tar.gz: 34bd9e558c5d1a29453e02dfd76c709876765b2c1958744d5cdac985045e7b04c09cbc7c51d1706fe81df0d1ab54d2fdbaf4d411335ad2038ae86236b6a0da5e

data/CHANGELOG.md

@@ -6,6 +6,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [1.6.0] - 2026-11-04
+
+### Added
+
+- `app_list`: the apps in the store, a page at a time (up to 50,000 per call), filtered by type or by last change (#109).
+
+## [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 +234,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.4.0...HEAD
+[Unreleased]: https://github.com/jpechaves/steam_api/compare/v1.6.0...HEAD
+[1.6.0]: https://github.com/jpechaves/steam_api/compare/v1.5.0...v1.6.0
+[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.
@@ -309,6 +336,36 @@ lists.top_sellers.items.map(&:name)
 
 `SteamApiClient::FeaturedCategories` fields: `specials`, `coming_soon`, `top_sellers`, `new_releases`, each a `FeaturedCategories::Category` (`id`, `name` in the requested language, `items`: `FeaturedItem`), or `nil` when Steam leaves the list out. Steam also sends the spotlights, the daily deal, genres and trailers, whose shapes vary: use `retrieve_raw` for those.
 
+#### `app_list`
+
+🔑 One page of the apps in the store, in app ID order. It's the way to find an app's ID by name across the whole catalog (`store_search` returns at most 10 results). `nil` when there's nothing: past the last page, or no app changed since `if_modified_since`.
+
+- `include_games:` (default `true`), `include_dlc:`, `include_software:`, `include_videos:`, `include_hardware:` (default `false`) pick the types.
+- `max_results:` is the page size, 10,000 by default, up to 50,000.
+- `last_appid:` starts after that app: pass the previous page's `last_app_id` to get the next page.
+- `if_modified_since:` (unix time) only returns apps changed since then.
+
+```ruby
+page = client.app_list.retrieve(max_results: 5)
+# => #<data SteamApiClient::AppList apps=[#<data SteamApiClient::AppList::App app_id=10, name="Counter-Strike",
+#     last_modified=1745368572, price_change_number=39636801>, ...], have_more_results=true, last_app_id=50>
+
+# Every game, a page at a time (about 200,000 in 4 calls)
+apps = []
+last_appid = 0
+loop do
+  page = client.app_list.retrieve(last_appid: last_appid, max_results: 50_000)
+  break unless page
+
+  apps.concat(page.apps)
+  break unless page.have_more_results
+
+  last_appid = page.last_app_id
+end
+```
+
+On the last page Steam leaves out `have_more_results` (so `false`) and `last_app_id` (`nil`).
+
 #### `app_news`
 
 The latest news of an app. `count:` is required, `maxlength:` (default 300) shortens each item's contents.
@@ -441,6 +498,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

@@ -44,6 +44,26 @@ module SteamApiClient
         params: {appid: param.integer(as: :gameid)}
       ),
 
+      # One page of the apps in the store, by app ID => AppList, or nil when there's nothing
+      # (past the last page, or nothing modified since if_modified_since)
+      # @see https://steamapi.xpaw.me/#IStoreService/GetAppList
+      Endpoint.new(
+        :app_list, "IStoreService/GetAppList/v1/", returns: AppList, at: %i[response],
+        params: {
+          include_games: param.boolean(default: true),
+          include_dlc: param.boolean(default: false),
+          include_software: param.boolean(default: false),
+          include_videos: param.boolean(default: false),
+          include_hardware: param.boolean(default: false),
+          # Only apps changed since then, in unix time (0 for all)
+          if_modified_since: param.integer(default: 0),
+          # The previous page's last_app_id (0 for the first page)
+          last_appid: param.integer(default: 0),
+          # Apps per page, up to 50,000
+          max_results: param.integer(default: 10_000)
+        }
+      ),
+
       # Latest news of an app => [NewsItem]
       # @see https://developer.valvesoftware.com/wiki/Steam_Web_API#GetNewsForApp_.28v0002.29
       Endpoint.new(
@@ -116,6 +136,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_list.rb

@@ -0,0 +1,22 @@
+module SteamApiClient
+  # Built first, then named AppList::App below
+  app = Model.define(
+    app_id: [:integer, from: :appid],
+    name: :string,
+    # In unix time
+    last_modified: [:integer, optional: true],
+    # Changes whenever the app's price changes
+    price_change_number: [:integer, optional: true]
+  )
+
+  # One page of the apps in the store, from `app_list`
+  # @see https://steamapi.xpaw.me/#IStoreService/GetAppList
+  AppList = Model.define(
+    apps: [[app], default: []],
+    # Steam leaves these out on the last page
+    have_more_results: [:boolean, default: false],
+    # Pass as `last_appid:` to get the next page
+    last_app_id: [:integer, from: :last_appid, optional: true]
+  )
+  AppList.const_set(:App, app)
+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.4.0"
+  VERSION = "1.6.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"
@@ -30,6 +32,7 @@ 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_list"
 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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: steam_api_client
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.6.0
 platform: ruby
 authors:
 - João Pedro
@@ -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_list.rb
 - lib/steam_api_client/models/app_schema.rb
 - lib/steam_api_client/models/featured.rb
 - lib/steam_api_client/models/featured_categories.rb
@@ -65,6 +66,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