steam_api_client 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09f9edc74aff7de3fa4975dca173fd7a3388ea4a732671b67db45e09de6a06e5'
-  data.tar.gz: 92bbc4d8b4214e32fb2c8d5e8e5a18a3e6844712b4cf916552f02a46a96ec82b
+  metadata.gz: 63721ffd174da8e4b24173f6507837633cf1930945bb2378228a04cced136099
+  data.tar.gz: 1f4d9e6348bff39b44d7c09289ce74083eebb74e620cbba9020efc1a413f9530
 SHA512:
-  metadata.gz: 87a2e53bcd76c574b6f6389071a5156073ad893734ef79377fb34c48406f120652dd93e0a4d8f79b2bd54b5984c6415a5a55e618839ba330d7febb6415c76af8
-  data.tar.gz: 3ee3b3c3059e76060a40f63a14bfabd9881983f077f438c8ea90a239d6efeb89602cfed40c7022dfec6225b8b6578508f8821abecae7b4e7287ba0dd261fc60b
+  metadata.gz: aa49878ef1061a3b417924c89a6a8453404a70db5e5287205c1c19b3427ac9c82028574fcbfbba58a739ae0549f73222c4e5246ddf65a93687ba0a7d05168e07
+  data.tar.gz: 65dd3ce130994fb54155f674347da656f61231c4b9025bcd84625540f19173c247a809a92a1eab223ae6daf2f5470b7e2c481a9778c7c1918189b1a9f447a5ba

data/CHANGELOG.md

@@ -6,6 +6,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [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 +216,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.2.0...HEAD
+[Unreleased]: https://github.com/jpechaves/steam_api/compare/v1.3.0...HEAD
+[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.
@@ -389,7 +417,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,26 @@ module SteamApiClient
         }
       ),
 
+      # 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/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.3.0"
 end

data/lib/steam_api_client.rb

@@ -33,6 +33,9 @@ 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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: steam_api_client
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - João Pedro
@@ -55,6 +55,9 @@ 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/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