steam_api_client 0.10.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d0c5680dd7c5f04050858684ffdedba92a405af03105ff67d5ab5f83786a9be3
-  data.tar.gz: 18dace5a415dbae06ab33d22af1d8d2f89a692c18b33d0fde7632e9608860476
+  metadata.gz: d69cc1b3c7d853d973708c6ec1c4eacebb60122b0f338dbbec3eb0766ae63464
+  data.tar.gz: 4df0c047832658d3ecbc4505a0308682ab93121c834e44c9515cb63e5e8f17be
 SHA512:
-  metadata.gz: '008e3f030129225f200f25063f45bc1df84a0abc0aba381d1c2a919ef99f9cfebba87a908a14ebfc6652a0d9ea9dfdd76e8a7dc5299762df648b03423879dc07'
-  data.tar.gz: 886f409484facc5b94264c94a488e07d85bcf0514c84b81b9541f395da769d53d9407b8af83b2dc8cfcf45cb8bae81a5044a4d8542074c3940a3cec9ccfa2a71
+  metadata.gz: 14c25c60ca63dbc6eee90a07060b0a34d87a61c5d2808a9ac5b12aab5aeb1b2ca769e1f58b2dd638cbb32f4b00740dede05f83534105b80d39599fa9b47eec35
+  data.tar.gz: c36ccb50189c59e39be4420bc9419594457fa4383a614506b68770621df445d487a223fa4f7e2450ffd9dc7911a398b29dfb6967f8a8c13e791ff3779d5db9e1

data/CHANGELOG.md

@@ -6,6 +6,64 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [1.0.0] - 2026-10-24
+
+### Added
+
+- Gem metadata: a description, and links to the source code, changelog, bug tracker and documentation on the RubyGems page (#84).
+- Customize the Faraday connection (middleware, adapter options, test stubs) with a block: `Client.new { |faraday| ... }` per client, or `Client.configure { |c| c.connection { |faraday| ... } }` for every client (#85).
+- [docs/USAGE.md](docs/USAGE.md), shipped with the gem: every endpoint and what it returns, configuration, errors and retries, and Steam's limits. The README links to it (#83).
+- `retrieve_raw` on every endpoint returns Steam's JSON untouched (keys symbolized), for fields the results don't expose (#81).
+
+### Changed
+
+- **Breaking:** results are plain Ruby `Data` objects with snake_case fields, unwrapped from Steam's envelopes, and the gem no longer depends on dry-struct: its only dependency is Faraday (8 runtime gems instead of 18) (#81). `SteamApiClient::Structs::*` is removed. What each endpoint returns:
+
+  | Endpoint | Before | Now |
+  |---|---|---|
+  | `player_summaries` | `.response.players` | `[PlayerSummary]` (`steam_id`, `persona_name`, `avatar_full`, `country_code`, …) |
+  | `player_friends` | `.friendslist.friends` | `[Friend]` (`steam_id`, `relationship`, `friend_since`) |
+  | `player_owned_games` | `.response` (`game_count`, `games`) | `OwnedGames` (`game_count`, `games: [Game]`), `nil` for a private library |
+  | `player_recent_games` | `.response` (`total_count`, `games`) | `RecentGames` (`total_count`, `games: [Game]`), `nil` when not public |
+  | `player_achievements` | `.playerstats` (`steamID`, `gameName`, `achievements`, `success`) | `PlayerAchievements` (`steam_id`, `game_name`, `achievements` with `api_name`, `achieved` as true/false, `unlock_time`) |
+  | `player_game_stats` | `.playerstats` | `PlayerGameStats` (`steam_id`, `game_name`, `stats`, `achievements` with `achieved` as true/false) |
+  | `player_level` | `.response.player_level` | Integer, `nil` when not visible |
+  | `player_steamid` | `.response` (`steamid`, `success`, `message`) | Integer, `nil` when nothing matches |
+  | `game_current_players` | `.response.player_count` | Integer |
+  | `app_news` | `.appnews.newsitems` | `[NewsItem]` (`feed_label`, `feed_name`, `app_id`, …) |
+  | `app_global_achievements` | `.achievementpercentages.achievements` | `[GlobalAchievement]` (`name`, `percent`) |
+  | `app_details` | `Structs::AppDetails::Details` (`.response.success`, `.response.data`) | `AppDetails` (`app_id`, `name`, …; parts such as `AppDetails::Price`, `AppDetails::Package`), `nil` when the app is unavailable |
+
+  Other changes:
+  - Field names are snake_case: `steamid` → `steam_id`, `appid` → `app_id`, `personaname` → `persona_name`, `loccountrycode` → `country_code`, `packageid` → `package_id`, and so on. Fields that were already snake_case keep their names.
+  - `app_details`: `recommendations` is the review count (Steam's `recommendations.total`), and `movies` drop the legacy `webm` / `mp4` files, which Steam no longer sends. A `[]` sent instead of requirements reads as `nil`.
+  - Lists Steam leaves out are `[]`, and data a private profile hides is `nil`.
+  - `#to_h` returns nested hashes. Results compare by value and support pattern matching.
+  - `ResponseParseError#cause` is a `SteamApiClient::Model::Error` (instead of a `Dry::Struct::Error`). Its message names the field but never the value.
+- `Client.configure` / `Client.config` use a plain Ruby `SteamApiClient::Configuration` instead of dry-configurable, which the gem no longer depends on. The settings and their defaults are unchanged. New: `Client.reset_config!` restores the defaults (handy in specs), `config.to_h`, and `config.inspect` hides the token (#82).
+- Endpoints are declared as data: each is one `SteamApiClient::Endpoint` in `SteamApiClient::Endpoints::ALL`, and `client.<name>` returns a `SteamApiClient::Requestor` for it (#87). Every `retrieve` keeps its keyword arguments, defaults and results. Differences:
+  - Arguments are checked with Ruby's own messages (`missing keyword: :steamid`, `unknown keyword: :steam_id`), and invalid values raise `ArgumentError` naming the argument (e.g. `steamid must be an Integer, got "abc"`), instead of a `Dry::Struct::Error`. `nil` is rejected too (before, an empty value was sent to Steam). Numeric strings are still accepted for IDs.
+  - **Breaking (internal classes):** `SteamApiClient::Requestors::*`, `SteamApiClient::Structs::Requests::*` and `SteamApiClient::Errors::EndpointKindNotSupported` are removed, and `Request.new` takes `endpoint:, params:, client:`. Code that only uses `client.<endpoint>.retrieve` is unaffected.
+
+### Security
+
+- `Client`, `Request` and `Response` no longer show the API token in `inspect` (and `pp`), so consoles, logs and error trackers don't leak it. The token shows as `[REDACTED]`, the `key=` value in URLs too (#80).
+
+## [0.11.0] - 2026-10-23 [YANKED]
+
+> Yanked: the published gem was built after the 1.0 changes had merged, so it contained everything listed under 1.0.0, not only the change below. Use 1.0.0 (#100).
+
+### Added
+
+- `Client` `adapter` setting (`Client.configure { |c| c.adapter = ... }` or `Client.new(adapter:)`) to choose the Faraday adapter, `:net_http` by default (#35).
+
+### Changed
+
+- **Breaking:** the HTTP client is now [Faraday](https://github.com/lostisland/faraday) with its `Net::HTTP` adapter, replacing Typhoeus (#35). The gem no longer installs `typhoeus`, `ethon` or `ffi` (a compiled gem that needs libcurl). The public API (`Client`, every `retrieve`, the `Errors::*` classes) is unchanged, except:
+  - Connection failures (DNS, refused connection, TLS) raise the new `SteamApiClient::Errors::ConnectionError`. It is **not** an `ApiError`: before, they surfaced as a generic `ApiError` with status code `0`.
+  - `HttpTimeout` for a timed-out request has no HTTP response (`#response` is `nil`), and its message gives the timeouts. A real `408` response also raises `HttpTimeout`.
+  - Redirects aren't followed anymore. No Steam endpoint redirects (all were checked).
+
 ## [0.10.0] - 2026-10-23
 
 ### Added
@@ -36,13 +94,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
   | `app_global_achievements.retrieve(appid)` | `app_global_achievements.retrieve(appid: appid)` |
   | `game_current_players.retrieve(appid)` | `game_current_players.retrieve(appid: appid)` |
 
-### Fixed
-
-- `player_owned_games` failed on real public libraries: it required `playtime_windows_forever`, `playtime_mac_forever`, `playtime_linux_forever` and `rtime_last_played`, which Steam doesn't send. They're optional now, and `playtime_2weeks`, `has_community_visible_stats`, `has_leaderboards` and `content_descriptorids` are exposed (#70).
-- Responses with duplicate JSON keys parse the same on every `json` gem version, with the last value winning. json 3 rejects duplicate keys by default, which would have raised `ResponseParseError` (#19).
-
-### Changed
-
 - Allows `dry-configurable` 1.2 and newer (`~> 1.1` instead of `~> 1.1.0`, which only allowed 1.1.x) (#19).
 - **Breaking:** requires Ruby 3.3 or newer (#17). Ruby 3.0, 3.1 and 3.2 have reached end of life. CI now tests 3.3, 3.4 and 4.0.
 - **Breaking:** response structs now validate their declared types (#15). Integer, Float and String fields convert Steam's values (Steam often sends numbers as strings), and a value that can't be converted raises `SteamApiClient::Errors::ResponseParseError` instead of passing through unchanged. `null` values still come through as `nil`.
@@ -51,6 +102,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
   - Global achievement `percent` is now a Float (it held Steam's raw value, e.g. `"49.6"`).
 - The gem homepage and README links point to `github.com/jpechaves/steam_api` instead of the old `sosolidkk` account (#22).
 
+### Fixed
+
+- `player_owned_games` failed on real public libraries: it required `playtime_windows_forever`, `playtime_mac_forever`, `playtime_linux_forever` and `rtime_last_played`, which Steam doesn't send. They're optional now, and `playtime_2weeks`, `has_community_visible_stats`, `has_leaderboards` and `content_descriptorids` are exposed (#70).
+- Responses with duplicate JSON keys parse the same on every `json` gem version, with the last value winning. json 3 rejects duplicate keys by default, which would have raised `ResponseParseError` (#19).
+
 ## [0.9.1] - 2026-10-23
 
 ### Fixed
@@ -142,7 +198,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/v0.10.0...HEAD
+[Unreleased]: https://github.com/jpechaves/steam_api/compare/v1.0.0...HEAD
+[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
 [0.10.0]: https://github.com/jpechaves/steam_api/compare/v0.9.1...v0.10.0
 [0.9.1]: https://github.com/jpechaves/steam_api/compare/v0.9.0...v0.9.1
 [0.9.0]: https://github.com/jpechaves/steam_api/releases/tag/v0.9.0

data/README.md

@@ -4,10 +4,6 @@
   - [Features](#features)
   - [Installation](#installation)
   - [Usage](#usage)
-    - [Configuring the Client](#configuring-the-client)
-    - [Example Requests](#example-requests)
-      - [Get Player Summaries](#get-player-summaries)
-      - [Get App Details](#get-app-details)
   - [Development](#development)
     - [Requirements](#requirements)
     - [Initial Setup](#initial-setup)
@@ -16,7 +12,6 @@
     - [Code Quality](#code-quality)
     - [Releasing](#releasing)
   - [Contributing](#contributing)
-    - [How to Contribute](#how-to-contribute)
   - [License](#license)
   - [Code of Conduct](#code-of-conduct)
 
@@ -27,7 +22,7 @@
 
 > Previously developed as `steam_api`. It is not related to the [`steam_api`](https://rubygems.org/gems/steam_api) gem on RubyGems.
 
-A Ruby gem for interacting with the [Steam Web API](https://developer.valvesoftware.com/wiki/Steam_Web_API). This gem provides a structured and user-friendly way to fetch various types of data from Steam's API endpoints, such as game details, player information, and achievements.
+A Ruby gem for interacting with the [Steam Web API](https://developer.valvesoftware.com/wiki/Steam_Web_API). It returns plain Ruby objects (`Data`) with snake_case fields, such as game details, player information, and achievements, and its only dependency is Faraday.
 
 ## Features
 
@@ -65,48 +60,25 @@ require "steam_api_client"
 
 ## Usage
 
-### Configuring the Client
-
-```ruby
-SteamApiClient::Client.configure do |config|
-  config.api_token = "your-API-token-value"
-end
-```
-
-Alternatively, you can initialize the client directly:
-
-```ruby
-client = SteamApiClient::Client.new(api_token: "your-API-token-value")
-```
-
-Requests time out after 10 seconds (5 seconds to connect) and raise `SteamApiClient::Errors::HttpTimeout`. You can change this globally or per client, in seconds:
-
 ```ruby
 SteamApiClient::Client.configure do |config|
-  config.timeout = 30
-  config.connect_timeout = 2
+  config.api_token = ENV.fetch("STEAM_API_KEY") # https://steamcommunity.com/dev/apikey
 end
 
-client = SteamApiClient::Client.new(api_token: "your-API-token-value", timeout: 5)
-```
-
-### Example Requests
+client = SteamApiClient::Client.new
 
-#### Get Player Summaries
+player = client.player_summaries.retrieve(steamids: [76561197960435530]).first
+player.persona_name # => "Robin"
 
-```ruby
-client = SteamApiClient::Client.new(api_token: "your-API-token-value")
-client.player_summaries.retrieve(steamids: [76561198160009756])
+client.player_level.retrieve(steamid: player.steam_id)                  # => 32
+client.player_owned_games.retrieve(steamid: player.steam_id)            # => OwnedGames, or nil when private
+client.app_details.retrieve(appid: 440, filters: ["basic"]).name        # => "Team Fortress 2"
+client.game_current_players.retrieve(appid: 440)                        # => 88231
 ```
 
-#### Get App Details
+Results are immutable `Data` objects with snake_case fields (or Integers, or Arrays of them). HTTP errors raise `SteamApiClient::Errors::*` classes, e.g. `HttpTooManyRequests` with `#retry_after`.
 
-```ruby
-client = SteamApiClient::Client.new
-client.app_details.retrieve(appid: 1091500, filters: ["basic"])
-```
-
-For more examples, see the [Usage](#usage) section above.
+**See [docs/USAGE.md](docs/USAGE.md)** for every endpoint and what it returns, configuration (timeouts, adapter, Faraday middleware, logging without leaking the key), errors and retries, and Steam's limits.
 
 ## Development
 
@@ -168,15 +140,9 @@ $ bin/release --dry-run  # show what would happen without building, pushing or t
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at [GitHub Repository](https://github.com/jpechaves/steam_api). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Code of Conduct](https://github.com/jpechaves/steam_api/blob/main/CODE_OF_CONDUCT.md).
-
-### How to Contribute
+Bug reports, endpoint requests and pull requests are welcome on [GitHub](https://github.com/jpechaves/steam_api). Every change starts with an issue; see [CONTRIBUTING.md](CONTRIBUTING.md) for the setup, the checks and the CHANGELOG rules. Security problems go through [SECURITY.md](SECURITY.md), not public issues.
 
-1. Fork the repository.
-2. Create a new branch for your feature or bug fix.
-3. Write tests for your changes.
-4. Run the tests to ensure everything works.
-5. Submit a pull request.
+This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## License
 

data/docs/USAGE.md

@@ -0,0 +1,326 @@
+# Using steam_api_client
+
+- [Configuration](#configuration)
+- [Calling an endpoint](#calling-an-endpoint)
+- [Endpoints](#endpoints)
+  - [Players](#players): [`player_summaries`](#player_summaries), [`player_steamid`](#player_steamid), [`player_friends`](#player_friends), [`player_level`](#player_level), [`player_owned_games`](#player_owned_games), [`player_recent_games`](#player_recent_games), [`player_achievements`](#player_achievements), [`player_game_stats`](#player_game_stats)
+  - [Apps](#apps): [`app_details`](#app_details), [`app_news`](#app_news), [`app_global_achievements`](#app_global_achievements), [`game_current_players`](#game_current_players)
+- [Results](#results)
+- [Errors](#errors)
+- [Limits and caveats](#limits-and-caveats)
+
+The values in the examples are real-shaped, but illustrative: Steam's data changes all the time.
+
+## Configuration
+
+Most endpoints need a [Steam Web API key](https://steamcommunity.com/dev/apikey). Set it once for every client, or per client:
+
+```ruby
+SteamApiClient::Client.configure do |config|
+  config.api_token = ENV.fetch("STEAM_API_KEY")
+end
+
+client = SteamApiClient::Client.new                                   # uses the configured key
+client = SteamApiClient::Client.new(api_token: "another-key")         # overrides it
+```
+
+Calling an endpoint that needs a key without one raises `SteamApiClient::Errors::MissingApiToken` before anything is sent.
+
+| Setting | Default | Meaning |
+|---|---|---|
+| `api_token` | `nil` | Steam Web API key |
+| `timeout` | `10` | Seconds for the whole request |
+| `connect_timeout` | `5` | Seconds to open the connection |
+| `adapter` | `:net_http` | [Faraday adapter](https://lostisland.github.io/faraday/#/adapters/index); add its gem to your Gemfile |
+| `connection { \|faraday\| ... }` | none | Customizes the Faraday connection (middleware, adapter options) |
+
+Every setting can be given globally (`Client.configure`) or per client (`Client.new(timeout: 3)`, or a block for the connection). Per-client values win. `Client.reset_config!` restores the defaults, which is handy in specs.
+
+```ruby
+SteamApiClient::Client.configure do |config|
+  config.timeout = 30
+  config.connect_timeout = 2
+  config.adapter = :net_http_persistent # from the net-http-persistent adapter gem
+  config.connection { |faraday| faraday.request :instrumentation }
+end
+
+# The connection block runs after the adapter is set, so it can also replace it, with options
+client = SteamApiClient::Client.new do |faraday|
+  faraday.adapter :net_http_persistent, pool_size: 5
+end
+```
+
+> **Logging:** Steam only accepts the key in the query string, so a logger that prints request URLs prints your key. The gem keeps it out of its own `inspect` output (`api_token=[REDACTED]`), but a logging middleware needs a filter:
+>
+> ```ruby
+> client = SteamApiClient::Client.new do |faraday|
+>   faraday.response :logger, Rails.logger, headers: false do |logger|
+>     logger.filter(/(key=)[^&\s]+/, '\1[REDACTED]')
+>   end
+> end
+> ```
+
+In your own specs, Faraday's test adapter replaces the network:
+
+```ruby
+stubs = Faraday::Adapter::Test::Stubs.new do |stub|
+  stub.get("/IPlayerService/GetSteamLevel/v0001/") { [200, {}, '{"response":{"player_level":10}}'] }
+end
+client = SteamApiClient::Client.new(api_token: "test") { |faraday| faraday.adapter :test, stubs }
+client.player_level.retrieve(steamid: 76561197960435530) # => 10
+```
+
+## Calling an endpoint
+
+Every endpoint is a method on the client with a `retrieve` method that takes keyword arguments:
+
+```ruby
+client.player_level.retrieve(steamid: 76561197960435530) # => 32
+```
+
+- Missing or unknown arguments raise `ArgumentError` with Ruby's own messages (`missing keyword: :steamid`, `unknown keyword: :steam_id`).
+- Values are checked: IDs must be Integers (numeric strings like `"76561197960435530"` are accepted), lists must be Arrays. Anything else raises `ArgumentError`, e.g. `steamid must be an Integer, got "robin"`.
+- `retrieve_raw` takes the same arguments and returns Steam's JSON untouched (with symbol keys), for fields the gem doesn't expose:
+
+  ```ruby
+  client.player_level.retrieve_raw(steamid: 76561197960435530) # => {response: {player_level: 32}}
+  ```
+
+## Endpoints
+
+A 🔑 means the endpoint needs an API key.
+
+### Players
+
+#### `player_summaries`
+
+🔑 Profiles of up to 100 players. Steam leaves out IDs it doesn't know.
+
+```ruby
+players = client.player_summaries.retrieve(steamids: [76561197960435530, 76561197960287930])
+# => [#<data SteamApiClient::PlayerSummary steam_id=76561197960435530, persona_name="Robin", ...>, ...]
+
+player = players.first
+player.persona_name               # => "Robin"
+player.profile_url                # => "https://steamcommunity.com/id/robinwalker/"
+player.avatar_full                # => "https://avatars.steamstatic.com/..._full.jpg"
+player.persona_state              # => 0 (0 offline, 1 online, 2 busy, 3 away, 4 snooze, 5 looking to trade, 6 looking to play)
+player.community_visibility_state # => 3 (3 public, 1 not visible to you)
+player.country_code               # => "US", or nil when not public
+```
+
+`SteamApiClient::PlayerSummary` fields: `steam_id`, `persona_name`, `profile_url`, `avatar`, `avatar_medium`, `avatar_full`, `avatar_hash`, `persona_state`, `persona_state_flags`, `community_visibility_state`, `profile_state`, `last_logoff`, `comment_permission`, `real_name`, `time_created`, `country_code`, `primary_clan_id`. Everything after `community_visibility_state` is `nil` when the profile (or that part of it) isn't public. Times are unix timestamps.
+
+#### `player_steamid`
+
+🔑 The 64 bit SteamID a vanity URL (`steamcommunity.com/id/<vanityurl>`) resolves to, or `nil`.
+
+```ruby
+client.player_steamid.retrieve(vanityurl: "robinwalker")     # => 76561197960435530
+client.player_steamid.retrieve(vanityurl: "no-such-profile") # => nil
+```
+
+#### `player_friends`
+
+🔑 A player's friend list. `relationship:` is `"all"` (default) or `"friend"`.
+
+```ruby
+client.player_friends.retrieve(steamid: 76561197960435530)
+# => [#<data SteamApiClient::Friend steam_id=76561198000000002, relationship="friend", friend_since=1262304000>, ...]
+```
+
+A private friend list raises `Errors::HttpUnauthorized`.
+
+#### `player_level`
+
+🔑 A player's Steam level, or `nil` when the profile isn't visible.
+
+```ruby
+client.player_level.retrieve(steamid: 76561197960435530) # => 32
+```
+
+#### `player_owned_games`
+
+🔑 The games a player owns, or `nil` when the library isn't public. `include_appinfo: true` adds each game's name and icon, `include_played_free_games: true` adds free games the player has played (both default to `false`).
+
+```ruby
+library = client.player_owned_games.retrieve(steamid: 76561198000000001, include_appinfo: true)
+# => #<data SteamApiClient::OwnedGames game_count=375, games=[...]>
+
+library.games.first
+# => #<data SteamApiClient::Game app_id=440, name="Team Fortress 2", img_icon_url="f568912870a4684f9ec76277a1a404dda6bab213",
+#     playtime_forever=2090, playtime_2weeks=nil, has_community_visible_stats=true, has_leaderboards=true, ...>
+
+library.games.sum(&:playtime_forever) / 60 # hours played
+```
+
+`SteamApiClient::Game` fields: `app_id`, `name`, `img_icon_url`, `playtime_forever`, `playtime_2weeks`, `has_community_visible_stats`, `has_leaderboards`, `content_descriptor_ids`, `playtime_windows_forever`, `playtime_mac_forever`, `playtime_linux_forever`, `rtime_last_played`. Playtimes are in minutes. `playtime_2weeks` is only sent for games played recently, and Steam no longer sends the per-platform playtimes or `rtime_last_played` for most libraries.
+
+#### `player_recent_games`
+
+🔑 The games played in the last two weeks, or `nil` when not public. `count:` defaults to 5.
+
+```ruby
+recent = client.player_recent_games.retrieve(steamid: 76561198000000001, count: 3)
+# => #<data SteamApiClient::RecentGames total_count=1, games=[#<data SteamApiClient::Game app_id=2868840, name="Slay the Spire 2", playtime_2weeks=922, ...>]>
+```
+
+#### `player_achievements`
+
+🔑 A player's achievements in a game.
+
+```ruby
+stats = client.player_achievements.retrieve(appid: 440, steamid: 76561198000000001)
+stats.game_name # => "Team Fortress 2"
+stats.achievements.first
+# => #<data SteamApiClient::PlayerAchievements::Achievement api_name="TF_PLAY_GAME_EVERYCLASS", achieved=true, unlock_time=1262304000>
+stats.achievements.count(&:achieved) # => 95
+```
+
+`unlock_time` is a unix timestamp, `0` when locked. A private profile raises `Errors::HttpForbidden` (`Profile is not public`), and a game without stats `Errors::HttpBadRequest` (`Requested app has no stats`).
+
+#### `player_game_stats`
+
+🔑 A player's stats and unlocked achievements in a game.
+
+```ruby
+stats = client.player_game_stats.retrieve(appid: 440, steamid: 76561198000000001)
+stats.stats.first        # => #<data SteamApiClient::PlayerGameStats::Stat name="Scout.accum.iDamageDealt", value=26580>
+stats.achievements.first # => #<data SteamApiClient::PlayerGameStats::Achievement name="TF_PLAY_GAME_EVERYCLASS", achieved=true>
+```
+
+Stat values are Integers or Floats, as the game defines them. A private profile, or a game without stats, raises `Errors::HttpBadRequest`.
+
+### Apps
+
+#### `app_details`
+
+The store page of an app, from Steam's unofficial [Storefront API](https://wiki.teamfortress.com/wiki/User:RJackson/StorefrontAPI), or `nil` when the app is unavailable (unknown, removed, or not sold in that country). No key needed.
+
+- `filters:` limits the fields, e.g. `["basic", "price_overview", "platforms"]`. Every field when empty (default). Fields left out are `nil`.
+- `country_code:` (default `"US"`) sets the currency and the availability. `locale:` (default `"en"`) the language of the texts, e.g. `"portuguese"`.
+
+```ruby
+app = client.app_details.retrieve(appid: 1091500, filters: ["basic", "price_overview"], country_code: "BR", locale: "portuguese")
+app.name            # => "Cyberpunk 2077"
+app.price_overview  # => #<data SteamApiClient::AppDetails::Price currency="BRL", initial=19990, final=5997, discount_percent=70,
+                    #     initial_formatted="R$ 199,90", final_formatted="R$ 59,97">
+client.app_details.retrieve(appid: 440).platforms
+# => #<data SteamApiClient::AppDetails::Platforms windows=true, mac=false, linux=true>
+```
+
+`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`).
+
+#### `app_news`
+
+The latest news of an app. `count:` is required, `maxlength:` (default 300) shortens each item's contents.
+
+```ruby
+client.app_news.retrieve(appid: 440, count: 5).first
+# => #<data SteamApiClient::NewsItem gid="...", title="Team Fortress 2 Update Released", url="https://steamstore-a.akamaihd.net/news/externalpost/...",
+#     is_external_url=true, author="erics", contents="...", feed_label="Community Announcements", date=1792179520,
+#     feed_name="steam_community_announcements", feed_type=1, app_id=440, tags=["patchnotes"]>
+```
+
+#### `app_global_achievements`
+
+The share of players who unlocked each achievement of an app, in percent.
+
+```ruby
+client.app_global_achievements.retrieve(appid: 440).first
+# => #<data SteamApiClient::GlobalAchievement name="TF_SCOUT_LONG_DISTANCE_RUNNER", percent=49.5>
+```
+
+#### `game_current_players`
+
+The number of players in a game right now.
+
+```ruby
+client.game_current_players.retrieve(appid: 440) # => 88231
+```
+
+An unknown app raises `Errors::HttpNotFound`.
+
+## Results
+
+Results are immutable [`Data`](https://docs.ruby-lang.org/en/3.3/Data.html) objects, Integers, or Arrays of them:
+
+- They compare by value, are frozen, and work with pattern matching:
+
+  ```ruby
+  case client.player_summaries.retrieve(steamids: [id]).first
+  in {community_visibility_state: 3, persona_name:} then "#{persona_name} has a public profile"
+  in nil then "no such player"
+  else "private profile"
+  end
+  ```
+
+- `#to_h` returns a plain Hash, nested parts included (e.g. to serialize as JSON).
+- Lists Steam leaves out are `[]`. Data that isn't visible (private profiles, unavailable apps, unmatched vanity URLs) is `nil`.
+
+## Errors
+
+```
+StandardError
+├── SteamApiClient::Errors::ApiError                 # Steam answered with an HTTP error
+│   ├── HttpBadRequest            (400)
+│   ├── HttpUnauthorized          (401)
+│   ├── HttpForbidden             (403)
+│   ├── HttpNotFound              (404)
+│   ├── HttpTimeout               (408, or no answer within the timeouts)
+│   ├── HttpTooManyRequests       (429)  #retry_after
+│   ├── HttpInternalServerError   (500)
+│   ├── HttpBadGateway            (502)
+│   └── HttpServiceUnavailable    (503)  #retry_after
+├── SteamApiClient::Errors::ConnectionError          # Steam couldn't be reached: DNS, refused connection, TLS
+├── SteamApiClient::Errors::ResponseParseError       # the body isn't the JSON the endpoint returns
+└── SteamApiClient::Errors::MissingApiToken          # the endpoint needs a key and the client has none
+ArgumentError                                        # missing, unknown or invalid arguments
+```
+
+- Other HTTP error statuses raise a plain `ApiError`. Its message has the status code and Steam's body.
+- `ConnectionError` is **not** an `ApiError`, and has the adapter's error as `#cause`. A timed-out request is an `HttpTimeout` without a response.
+- `ResponseParseError#response` is the response, and `#cause` the JSON error or the `SteamApiClient::Model::Error` naming the field that didn't match.
+- None of the messages contain the API key.
+
+To rescue everything that comes from Steam or the network:
+
+```ruby
+rescue SteamApiClient::Errors::ApiError, SteamApiClient::Errors::ConnectionError, SteamApiClient::Errors::ResponseParseError
+```
+
+### Retrying
+
+`HttpTooManyRequests` and `HttpServiceUnavailable` expose `#retry_after`, the seconds from Steam's `Retry-After` header (`nil` when it sends none). For example:
+
+```ruby
+RETRYABLE = [
+  SteamApiClient::Errors::HttpTooManyRequests, SteamApiClient::Errors::HttpBadGateway,
+  SteamApiClient::Errors::HttpServiceUnavailable, SteamApiClient::Errors::HttpTimeout
+].freeze
+
+def with_retries(attempts: 3)
+  tries = 0
+  begin
+    yield
+  rescue *RETRYABLE => error
+    tries += 1
+    raise if tries >= attempts
+
+    sleep((error.respond_to?(:retry_after) && error.retry_after) || 2**tries)
+    retry
+  end
+end
+
+with_retries { client.game_current_players.retrieve(appid: 440) }
+```
+
+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.
+- **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` (`player_owned_games`, `player_recent_games`, `player_level`). `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.