steam_api_client 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09f9edc74aff7de3fa4975dca173fd7a3388ea4a732671b67db45e09de6a06e5'
-  data.tar.gz: 92bbc4d8b4214e32fb2c8d5e8e5a18a3e6844712b4cf916552f02a46a96ec82b
+  metadata.gz: c0b06cbf7dc49fbd605cab7c84469fd11a1bde80779469db95bbe30b5867701d
+  data.tar.gz: 5b32661f36c1ad7495760925e0348f5778933bd647f0f876b3bdbfdcc8a621df
 SHA512:
-  metadata.gz: 87a2e53bcd76c574b6f6389071a5156073ad893734ef79377fb34c48406f120652dd93e0a4d8f79b2bd54b5984c6415a5a55e618839ba330d7febb6415c76af8
-  data.tar.gz: 3ee3b3c3059e76060a40f63a14bfabd9881983f077f438c8ea90a239d6efeb89602cfed40c7022dfec6225b8b6578508f8821abecae7b4e7287ba0dd261fc60b
+  metadata.gz: 887564c19ec25082f2498e8f55c2c316b499abd4c19d3bf00ed97206f7c2028fa81e1266649470fd6f2966aa2c39f5f99d8f5726e406d0bd52dfaa787b269c63
+  data.tar.gz: '04545587357f1c91db0e6fa2fb4585c029f9b363aa09c55815d8222d12c39e79190d404a22c9bf38b4df86ed6f75c251d970165a96331519fec24a0dda57de86'

data/CHANGELOG.md

@@ -6,6 +6,18 @@ 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
+
+- `featured` and `featured_categories` from the Storefront API: the apps on the store's front page, and its specials, top sellers, new releases and upcoming apps. No API key needed (#108).
+
 ## [1.2.0] - 2026-11-02
 
 ### Added
@@ -210,7 +222,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.2.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
 [1.0.0]: https://github.com/jpechaves/steam_api/compare/v0.10.0...v1.0.0

data/docs/USAGE.md

@@ -281,6 +281,34 @@ client.store_search.retrieve(term: "portal").first
 
 `price` is `nil` for free apps, `metascore` when the app has no Metacritic score. No match is `[]`.
 
+#### `featured`
+
+The apps featured on the store's front page, per platform. Storefront API, no key needed. Takes `country_code:` and `locale:`.
+
+```ruby
+featured = client.featured.retrieve(country_code: "DE", locale: "german")
+featured.featured_win.first
+# => #<data SteamApiClient::FeaturedItem id=3447280, type=0, name="Fantasy World Manager", discounted=true, discount_percent=10,
+#     original_price=1499, final_price=1349, currency="EUR", discount_expiration=1794416432, ...>
+```
+
+`SteamApiClient::Featured` fields: `large_capsules`, `featured_win`, `featured_mac`, `featured_linux` (each a list of `FeaturedItem`, `[]` when empty), `layout`.
+
+`SteamApiClient::FeaturedItem` fields: `id`, `type` (`0` for apps), `name`, `discounted`, `discount_percent`, `original_price` and `final_price` (in cents; `original_price` is `nil` for free apps), `currency`, `discount_expiration` (unix time, `nil` when not discounted), `large_capsule_image`, `small_capsule_image`, `header_image`, `windows_available`, `mac_available`, `linux_available`, `streaming_video_available`, `controller_support`.
+
+#### `featured_categories`
+
+The store front page's lists: specials, upcoming apps, top sellers and new releases. Storefront API, no key needed. Takes `country_code:` and `locale:`.
+
+```ruby
+lists = client.featured_categories.retrieve
+lists.specials
+# => #<data SteamApiClient::FeaturedCategories::Category id="cat_specials", name="Specials", items=[#<data SteamApiClient::FeaturedItem ...>, ...]>
+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_news`
 
 The latest news of an app. `count:` is required, `maxlength:` (default 300) shortens each item's contents.
@@ -301,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.
@@ -389,7 +439,7 @@ Don't retry other 4xx errors: they won't succeed on their own.
 
 ## Limits and caveats
 
-- **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`) 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.
+- **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.
 - **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.

data/lib/steam_api_client/endpoints.rb

@@ -57,6 +57,37 @@ 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(
+        :featured, "featured/", api: :store, key: false, returns: Featured,
+        params: {
+          country_code: param.string(as: :cc, default: "US"),
+          locale: param.string(as: :l, default: "en")
+        }
+      ),
+
+      # The store front page's specials, top sellers, new releases and upcoming apps => FeaturedCategories
+      # @see https://wiki.teamfortress.com/wiki/User:RJackson/StorefrontAPI#featuredcategories
+      Endpoint.new(
+        :featured_categories, "featuredcategories/", api: :store, key: false, returns: FeaturedCategories,
+        params: {
+          country_code: param.string(as: :cc, default: "US"),
+          locale: param.string(as: :l, default: "en")
+        }
+      ),
+
       # Number of players currently in a game => Integer
       # @see https://wiki.teamfortress.com/wiki/WebAPI/GetNumberOfCurrentPlayers
       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/featured.rb

@@ -0,0 +1,12 @@
+module SteamApiClient
+  # The apps featured on the store's front page, from `featured`
+  # @see https://wiki.teamfortress.com/wiki/User:RJackson/StorefrontAPI#featured
+  Featured = Model.define(
+    large_capsules: [[FeaturedItem], default: []],
+    featured_win: [[FeaturedItem], default: []],
+    featured_mac: [[FeaturedItem], default: []],
+    featured_linux: [[FeaturedItem], default: []],
+    # The front page's layout, e.g. "defcon1"
+    layout: [:string, optional: true]
+  )
+end

data/lib/steam_api_client/models/featured_categories.rb

@@ -0,0 +1,21 @@
+module SteamApiClient
+  # Built first, then named FeaturedCategories::Category below
+  category = Model.define(
+    # e.g. "cat_specials"
+    id: :string,
+    name: :string,
+    items: [[FeaturedItem], default: []]
+  )
+
+  # The store front page's lists, from `featured_categories`. The spotlights,
+  # daily deal, genres and trailers Steam also sends vary in shape, so they're
+  # left to `retrieve_raw`.
+  # @see https://wiki.teamfortress.com/wiki/User:RJackson/StorefrontAPI#featuredcategories
+  FeaturedCategories = Model.define(
+    specials: [category, optional: true],
+    coming_soon: [category, optional: true],
+    top_sellers: [category, optional: true],
+    new_releases: [category, optional: true]
+  )
+  FeaturedCategories.const_set(:Category, category)
+end

data/lib/steam_api_client/models/featured_item.rb

@@ -0,0 +1,28 @@
+module SteamApiClient
+  # An app on the store's front page, from `featured` and `featured_categories`.
+  # Every field but the ID is nil when Steam leaves it out.
+  # @see https://wiki.teamfortress.com/wiki/User:RJackson/StorefrontAPI#featured
+  FeaturedItem = Model.define(
+    id: :integer,
+    # 0 for apps
+    type: [:integer, optional: true],
+    name: [:string, optional: true],
+    discounted: [:boolean, optional: true],
+    discount_percent: [:integer, optional: true],
+    # In cents. nil for free apps.
+    original_price: [:integer, optional: true],
+    final_price: [:integer, optional: true],
+    currency: [:string, optional: true],
+    # When the discount ends, in unix time. nil when not discounted.
+    discount_expiration: [:integer, optional: true],
+    large_capsule_image: [:string, optional: true],
+    small_capsule_image: [:string, optional: true],
+    header_image: [:string, optional: true],
+    windows_available: [:boolean, optional: true],
+    mac_available: [:boolean, optional: true],
+    linux_available: [:boolean, optional: true],
+    streaming_video_available: [:boolean, from: :streamingvideo_available, optional: true],
+    # "full", "partial", or nil
+    controller_support: [:string, optional: true]
+  )
+end

data/lib/steam_api_client/version.rb

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

data/lib/steam_api_client.rb

@@ -29,10 +29,14 @@ 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"
 require_relative "steam_api_client/models/store_search_result"
+require_relative "steam_api_client/models/featured_item"
+require_relative "steam_api_client/models/featured"
+require_relative "steam_api_client/models/featured_categories"
 require_relative "steam_api_client/models/wishlist_item"
 
 require_relative "steam_api_client/endpoints"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: steam_api_client
 version: !ruby/object:Gem::Version
-  version: 1.2.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,10 @@ 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
 - lib/steam_api_client/models/friend.rb
 - lib/steam_api_client/models/game.rb
 - lib/steam_api_client/models/global_achievement.rb