steam_api_client 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 63721ffd174da8e4b24173f6507837633cf1930945bb2378228a04cced136099
-  data.tar.gz: 1f4d9e6348bff39b44d7c09289ce74083eebb74e620cbba9020efc1a413f9530
+  metadata.gz: c0b06cbf7dc49fbd605cab7c84469fd11a1bde80779469db95bbe30b5867701d
+  data.tar.gz: 5b32661f36c1ad7495760925e0348f5778933bd647f0f876b3bdbfdcc8a621df
 SHA512:
-  metadata.gz: aa49878ef1061a3b417924c89a6a8453404a70db5e5287205c1c19b3427ac9c82028574fcbfbba58a739ae0549f73222c4e5246ddf65a93687ba0a7d05168e07
-  data.tar.gz: 65dd3ce130994fb54155f674347da656f61231c4b9025bcd84625540f19173c247a809a92a1eab223ae6daf2f5470b7e2c481a9778c7c1918189b1a9f447a5ba
+  metadata.gz: 887564c19ec25082f2498e8f55c2c316b499abd4c19d3bf00ed97206f7c2028fa81e1266649470fd6f2966aa2c39f5f99d8f5726e406d0bd52dfaa787b269c63
+  data.tar.gz: '04545587357f1c91db0e6fa2fb4585c029f9b363aa09c55815d8222d12c39e79190d404a22c9bf38b4df86ed6f75c251d970165a96331519fec24a0dda57de86'

data/CHANGELOG.md

@@ -6,6 +6,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [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 +222,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.3.0...HEAD
+[Unreleased]: https://github.com/jpechaves/steam_api/compare/v1.4.0...HEAD
+[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

@@ -329,6 +329,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.

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(

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/version.rb

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

data/lib/steam_api_client.rb

@@ -29,6 +29,7 @@ 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.4.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