steam_api_client 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fff398c488310a8cd495c37bc213bc6b41645c21aef707a5b83a951c4ee7550e
-  data.tar.gz: '0191bdcd553d89bcf7f15cf247eb5aa2e6a616377e791a544ee8ccfefcdc9e7d'
+  metadata.gz: '09f9edc74aff7de3fa4975dca173fd7a3388ea4a732671b67db45e09de6a06e5'
+  data.tar.gz: 92bbc4d8b4214e32fb2c8d5e8e5a18a3e6844712b4cf916552f02a46a96ec82b
 SHA512:
-  metadata.gz: eee77c9968b4a7ba64330c7fde66690509e2f8c6e9ea77bacd16b7e61a097f6e4ac8daa4226d38c6c33fbf6ed2d753dbf4c5527d58951672a2d33d18c91d27d5
-  data.tar.gz: e9fae7d714e744f4131951f3c45f73f4e8e81725b01b61d7ed6a9fc365293fe94808b58a6e96be457904e89c64b4fd3d073d1a1616051c6b5354a76d01c62a1e
+  metadata.gz: 87a2e53bcd76c574b6f6389071a5156073ad893734ef79377fb34c48406f120652dd93e0a4d8f79b2bd54b5984c6415a5a55e618839ba330d7febb6415c76af8
+  data.tar.gz: 3ee3b3c3059e76060a40f63a14bfabd9881983f077f438c8ea90a239d6efeb89602cfed40c7022dfec6225b8b6578508f8821abecae7b4e7287ba0dd261fc60b

data/CHANGELOG.md

@@ -6,6 +6,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-11-02
+
+### Added
+
+- `package_details`, `app_dlc` and `store_search` from the Storefront API: a package's apps and price, an app's DLC, and a search of the store by name. No API key needed (#107).
+
 ## [1.1.0] - 2026-11-02
 
 ### Added
@@ -204,7 +210,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.1.0...HEAD
+[Unreleased]: https://github.com/jpechaves/steam_api/compare/v1.2.0...HEAD
+[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
 [0.11.0]: https://github.com/jpechaves/steam_api/compare/v0.10.0...v0.11.0

data/docs/USAGE.md

@@ -238,6 +238,49 @@ client.app_details.retrieve(appid: 440).platforms
 
 `SteamApiClient::AppDetails` fields: `app_id`, `type`, `name`, `required_age`, `is_free`, `dlc`, `detailed_description`, `about_the_game`, `short_description`, `supported_languages`, `header_image`, `website`, `pc_requirements` / `mac_requirements` / `linux_requirements` (`AppDetails::Requirements`: `minimum`, `recommended`, as HTML), `developers`, `publishers`, `price_overview` (`AppDetails::Price`, in cents; `nil` for free apps), `packages`, `package_groups` (`AppDetails::PackageGroup` with `subs`: `AppDetails::Package`), `platforms`, `metacritic` (`score`, `url`), `categories` and `genres` (`id`, `description`), `screenshots`, `movies` (`AppDetails::Movie` with DASH and HLS streams), `recommendations` (the number of user reviews), `achievements` (`total`, `highlighted`), `release_date` (`coming_soon`, `date`), `support_info` (`url`, `email`), `background`, `background_raw`, `content_descriptors` (`ids`, `notes`).
 
+#### `package_details`
+
+A package (a bundle, or a "sub" such as an edition or a license) in the store, or `nil` when it's unavailable. Storefront API, no key needed. Takes one `packageid:` (Steam rejects several at once), and `country_code:` / `locale:` like `app_details`. Package IDs are in `app_details`' `packages` and `package_groups`.
+
+```ruby
+package = client.package_details.retrieve(packageid: 469)
+package.name   # => "The Orange Box"
+package.apps   # => [#<data SteamApiClient::PackageDetails::App id=220, name="Half-Life 2">, ...]
+package.price  # => #<data SteamApiClient::PackageDetails::Price currency="USD", initial=1999, final=1999, discount_percent=0, individual=1998>
+```
+
+`SteamApiClient::PackageDetails` fields: `package_id`, `name`, `page_content` (HTML), `purchase_text`, `page_image`, `header_image`, `small_logo`, `apps` (`id`, `name`), `price` (in cents; `individual` is what the apps cost on their own; `nil` for free packages), `platforms` and `release_date` (as in `AppDetails`), `controller` (`full_gamepad`). An invalid ID such as `0` raises `Errors::HttpBadRequest`.
+
+#### `app_dlc`
+
+An app's DLC, or `nil` when the app is unknown. Storefront API, no key needed. Takes `appid:`, `country_code:` and `locale:`.
+
+```ruby
+result = client.app_dlc.retrieve(appid: 292030)
+result.name # => "The Witcher 3: Wild Hunt — Remastered"
+result.dlc.last
+# => #<data SteamApiClient::AppDlc::Dlc id=1229320, name="The Witcher 3: Wild Hunt — Remastered Soundtrack", header_image="https://...",
+#     price_overview=#<data SteamApiClient::AppDlc::Price currency="USD", initial=1099, final=1099, discount_percent=0>,
+#     platforms=#<data SteamApiClient::AppDetails::Platforms windows=true, mac=true, linux=true>,
+#     release_date=#<data SteamApiClient::AppDlc::ReleaseDates steam=1581374766, mac=1581374752, linux=1581374752>, controller_support="full">
+```
+
+`price_overview` is `nil` for free DLC and DLC not sold on its own. `release_date` has a unix time per platform (`steam`, `mac`, `linux`), each `nil` when Steam doesn't know it. Steam sometimes adds milliseconds, and the time is then a Float.
+
+#### `store_search`
+
+Apps in the store matching a search term, at most 10 (Steam's limit, with no paging). Storefront API, no key needed. Takes `term:`, `country_code:` and `locale:`.
+
+```ruby
+client.store_search.retrieve(term: "portal").first
+# => #<data SteamApiClient::StoreSearchResult id=620, type="app", name="Portal 2",
+#     price=#<data SteamApiClient::StoreSearchResult::Price currency="USD", initial=999, final=999>, tiny_image="https://...",
+#     metascore=95, platforms=#<data SteamApiClient::AppDetails::Platforms windows=true, mac=false, linux=true>,
+#     streaming_video=false, controller_support="full">
+```
+
+`price` is `nil` for free apps, `metascore` when the app has no Metacritic score. No match is `[]`.
+
 #### `app_news`
 
 The latest news of an app. `count:` is required, `maxlength:` (default 300) shortens each item's contents.
@@ -346,8 +389,8 @@ 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`) 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.** `app_details` uses the API behind Steam's store and Big Picture mode. Valve doesn't document it, and its fields change without notice.
+- **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.
+- **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.
 - **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

@@ -26,6 +26,16 @@ module SteamApiClient
         }
       ),
 
+      # An app's DLC => AppDlc, or nil when the app is unknown
+      Endpoint.new(
+        :app_dlc, "dlcforapp/", api: :store, key: false, returns: AppDlc, at: AppDlc.method(:unwrap),
+        params: {
+          appid: param.integer,
+          country_code: param.string(as: :cc, default: "US"),
+          locale: param.string(as: :l, default: "en")
+        }
+      ),
+
       # Global achievement unlock percentages of an app => [GlobalAchievement]
       # @see https://developer.valvesoftware.com/wiki/Steam_Web_API#GetGlobalAchievementPercentagesForApp_.28v0002.29
       Endpoint.new(
@@ -55,6 +65,19 @@ module SteamApiClient
         params: {appid: param.integer}
       ),
 
+      # Details of a package (a bundle or a sub) in the store => PackageDetails, or nil when unavailable
+      # @see https://wiki.teamfortress.com/wiki/User:RJackson/StorefrontAPI#packagedetails
+      Endpoint.new(
+        :package_details, "packagedetails/", api: :store, key: false, returns: PackageDetails,
+        at: PackageDetails.method(:unwrap),
+        params: {
+          # Steam rejects several IDs at once
+          packageid: param.integer(as: :packageids),
+          country_code: param.string(as: :cc, default: "US"),
+          locale: param.string(as: :l, default: "en")
+        }
+      ),
+
       # A player's achievements in an app => PlayerAchievements
       # @see https://developer.valvesoftware.com/wiki/Steam_Web_API#GetPlayerAchievements_.28v0001.29
       Endpoint.new(
@@ -137,6 +160,17 @@ module SteamApiClient
       Endpoint.new(
         :player_wishlist_count, "IWishlistService/GetWishlistItemCount/v1/", key: false, returns: :integer, at: %i[response count],
         params: {steamid: param.integer}
+      ),
+
+      # Apps in the store matching a search term => [StoreSearchResult] (at most 10)
+      Endpoint.new(
+        :store_search, "storesearch/", api: :store, key: false, returns: [StoreSearchResult],
+        at: StoreSearchResult.method(:unwrap),
+        params: {
+          term: param.string,
+          country_code: param.string(as: :cc, default: "US"),
+          locale: param.string(as: :l, default: "en")
+        }
       )
     ].to_h { |endpoint| [endpoint.name, endpoint] }.freeze
   end

data/lib/steam_api_client/models/app_details.rb

@@ -105,13 +105,15 @@ module SteamApiClient
   ) do
     # Steam keys the response by app ID: {"570": {"success": true, "data": {...}}}.
     # Returns the data, or nil when the app is unavailable (success: false).
+    # The Storefront's other details endpoints (packagedetails) answer the same way.
     # @param [Hash] json
+    # @param [Symbol] id_key the key the ID is added under
     # @return [Hash, nil]
-    def self.unwrap(json)
-      app_id, entry = json.first
+    def self.unwrap(json, id_key: :steam_appid)
+      id, entry = json.first
       return unless entry.is_a?(Hash) && entry[:success]
 
-      {steam_appid: app_id.to_s}.merge(entry.fetch(:data, {}))
+      {id_key => id.to_s}.merge(entry.fetch(:data, {}))
     end
   end
   parts.each { |name, model| AppDetails.const_set(name, model) }

data/lib/steam_api_client/models/app_dlc.rb

@@ -0,0 +1,44 @@
+module SteamApiClient
+  # The parts of AppDlc, built first, then named under it below (e.g. AppDlc::Dlc)
+  parts = {
+    Price: Model.define(
+      currency: :string,
+      # In cents
+      initial: :integer,
+      final: :integer,
+      discount_percent: :integer
+    ),
+    # Unix times, per platform. Steam sometimes adds milliseconds, which makes them Floats.
+    ReleaseDates: Model.define(
+      steam: [:number, optional: true],
+      mac: [:number, optional: true],
+      linux: [:number, optional: true]
+    )
+  }
+  parts[:Dlc] = Model.define(
+    id: :integer,
+    name: :string,
+    header_image: [:string, optional: true],
+    # Not sent for free DLC, or DLC not sold on its own
+    price_overview: [parts[:Price], optional: true],
+    platforms: [AppDetails::Platforms, optional: true],
+    release_date: [parts[:ReleaseDates], optional: true],
+    # "full", "partial", or nil
+    controller_support: [:string, optional: true]
+  )
+
+  # An app's DLC, from `app_dlc`
+  AppDlc = Model.define(
+    app_id: [:integer, from: :appid],
+    name: :string,
+    dlc: [[parts[:Dlc]], default: []]
+  ) do
+    # Steam answers {"status": 2} for an unknown app
+    # @param [Hash] json
+    # @return [Hash, nil] the JSON, or nil when the app is unknown
+    def self.unwrap(json)
+      json if json[:status] == 1
+    end
+  end
+  parts.each { |name, model| AppDlc.const_set(name, model) }
+end

data/lib/steam_api_client/models/package_details.rb

@@ -0,0 +1,45 @@
+module SteamApiClient
+  # The parts of PackageDetails, built first, then named under it below
+  # (e.g. PackageDetails::App)
+  parts = {
+    App: Model.define(id: :integer, name: :string),
+    Price: Model.define(
+      currency: :string,
+      # In cents
+      initial: :integer,
+      final: :integer,
+      discount_percent: :integer,
+      # The sum of the apps' own prices, in cents (0 when they aren't sold separately)
+      individual: [:integer, optional: true]
+    ),
+    Controller: Model.define(full_gamepad: :boolean)
+  }
+
+  # A package (a bundle or a sub) in the store, from `package_details`. Every
+  # field is nil when Steam leaves it out.
+  # @see https://wiki.teamfortress.com/wiki/User:RJackson/StorefrontAPI#packagedetails
+  PackageDetails = Model.define(
+    package_id: [:integer, from: :packageid],
+    name: [:string, optional: true],
+    # HTML
+    page_content: [:string, optional: true],
+    purchase_text: [:string, optional: true],
+    page_image: [:string, optional: true],
+    header_image: [:string, optional: true],
+    small_logo: [:string, optional: true],
+    apps: [[parts[:App]], default: []],
+    # Not sent for free packages
+    price: [parts[:Price], optional: true],
+    platforms: [AppDetails::Platforms, optional: true],
+    controller: [parts[:Controller], optional: true],
+    release_date: [AppDetails::ReleaseDate, optional: true]
+  ) do
+    # The package's data, or nil when it's unavailable (see AppDetails.unwrap)
+    # @param [Hash] json
+    # @return [Hash, nil]
+    def self.unwrap(json)
+      AppDetails.unwrap(json, id_key: :packageid)
+    end
+  end
+  parts.each { |name, model| PackageDetails.const_set(name, model) }
+end

data/lib/steam_api_client/models/store_search_result.rb

@@ -0,0 +1,34 @@
+module SteamApiClient
+  # Built first, then named StoreSearchResult::Price below
+  price = Model.define(
+    currency: :string,
+    # In cents
+    initial: :integer,
+    final: :integer
+  )
+
+  # One result of a store search, from `store_search`
+  StoreSearchResult = Model.define(
+    id: :integer,
+    # "app"
+    type: :string,
+    name: :string,
+    # Not sent for free apps
+    price: [price, optional: true],
+    tiny_image: [:string, optional: true],
+    # nil when the app has no Metacritic score
+    metascore: [:integer, optional: true],
+    platforms: [AppDetails::Platforms, optional: true],
+    streaming_video: [:boolean, from: :streamingvideo, optional: true],
+    # "full", "partial", or nil
+    controller_support: [:string, optional: true]
+  ) do
+    # The results. Steam sends "" as the metascore of apps without one.
+    # @param [Hash] json
+    # @return [Array<Hash>, nil]
+    def self.unwrap(json)
+      json[:items]&.map { |item| (item[:metascore] == "") ? item.merge(metascore: nil) : item }
+    end
+  end
+  StoreSearchResult.const_set(:Price, price)
+end

data/lib/steam_api_client/version.rb

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

data/lib/steam_api_client.rb

@@ -30,6 +30,9 @@ 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_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/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.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - João Pedro
@@ -54,13 +54,16 @@ files:
 - lib/steam_api_client/model/field.rb
 - 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/friend.rb
 - lib/steam_api_client/models/game.rb
 - lib/steam_api_client/models/global_achievement.rb
 - 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_game_stats.rb
 - lib/steam_api_client/models/player_summary.rb
+- lib/steam_api_client/models/store_search_result.rb
 - lib/steam_api_client/models/wishlist_item.rb
 - lib/steam_api_client/request.rb
 - lib/steam_api_client/requestor.rb