steam_api_client 0.10.0 → 1.0.0

data/lib/steam_api_client/model/scalars.rb

@@ -0,0 +1,59 @@
+module SteamApiClient
+  module Model
+    # Conversions of the scalar types
+    module Scalars
+      TYPES = %i[integer float number string boolean].freeze
+      INTEGER = /\A-?\d+\z/
+      FLOAT = /\A-?\d+(\.\d+)?\z/
+
+      def self.method_for(type)
+        raise ArgumentError, "unknown type #{type.inspect}" unless TYPES.include?(type)
+
+        :"to_#{type}"
+      end
+
+      def self.to_integer(value)
+        return value if value.is_a?(::Integer)
+        return Integer(value, 10) if value.is_a?(::String) && value.match?(INTEGER)
+
+        invalid("an Integer", value)
+      end
+
+      def self.to_float(value)
+        return value.to_f if value.is_a?(::Integer) || value.is_a?(::Float)
+        return Float(value) if value.is_a?(::String) && value.match?(FLOAT)
+
+        invalid("a Float", value)
+      end
+
+      # Integer or Float, as Steam sends it (converting would truncate or change stats)
+      def self.to_number(value)
+        return value if value.is_a?(::Integer) || value.is_a?(::Float)
+        return to_integer(value) if value.is_a?(::String) && value.match?(INTEGER)
+
+        to_float(value)
+      rescue Error
+        invalid("a number", value)
+      end
+
+      def self.to_string(value)
+        return value if value.is_a?(::String)
+        return value.to_s if value.is_a?(::Numeric)
+
+        invalid("a String", value)
+      end
+
+      # Steam's flags are true/false or 1/0
+      def self.to_boolean(value)
+        return value if value == true || value == false
+        return value == 1 if value == 0 || value == 1
+
+        invalid("true or false", value)
+      end
+
+      def self.invalid(expected, value)
+        raise Error, "expected #{expected}, got #{value.class}"
+      end
+    end
+  end
+end

data/lib/steam_api_client/model.rb

@@ -0,0 +1,102 @@
+module SteamApiClient
+  # Builds the immutable Data classes the endpoints return, from Steam's JSON:
+  #
+  #   PlayerLevel = Model.define(
+  #     steam_id: [:integer, from: :steamid],
+  #     level: [:integer, from: %i[stats level], optional: true],
+  #     tags: [[:string], default: []]
+  #   )
+  #   PlayerLevel.from_json({steamid: "76561197960435530", stats: {level: 9}})
+  #
+  # Each field is `name: type` or `name: [type, options]`. The type is :integer, :float,
+  # :string, :boolean, :number (an Integer or a Float, as Steam sends it), another model,
+  # or [type] for a list. Options:
+  # - from: Steam's key (Steam's names have no separators, e.g. steamid), or a path of keys
+  # - optional: true when Steam may leave the key out. The field is then nil.
+  # - default: the value used when Steam leaves the key out or sends null (implies optional)
+  #
+  # Values are converted (Steam often sends numbers as strings), nil passes through (Steam
+  # sends null for values it doesn't have), and anything else raises Model::Error.
+  module Model
+    # Raised when Steam's JSON doesn't match a model. The message names the field
+    # but never the value, which could be personal data.
+    class Error < StandardError; end
+
+    # @param [Hash{Symbol => Object}] fields name => type, or name => [type, options]
+    # @yield the class body, like Data.define's block
+    # @return [Class] a Data class that also responds to .from_json
+    def self.define(**fields, &block)
+      fields = fields.to_h do |name, spec|
+        type, options = spec_parts(spec)
+        [name, Field.new(name, type, **options)]
+      end
+
+      Data.define(*fields.keys, &block).tap do |klass|
+        klass.instance_variable_set(:@fields, fields.freeze)
+        klass.extend(ClassMethods)
+        klass.include(InstanceMethods)
+      end
+    end
+
+    # `[type, {options}]`, or the bare type
+    def self.spec_parts(spec)
+      type, options = spec
+      (spec.is_a?(Array) && options.is_a?(Hash)) ? [type, options] : [spec, {}]
+    end
+    private_class_method :spec_parts
+
+    # Converts one JSON value to the given type
+    # @raise [Model::Error] if the value doesn't convert
+    def self.cast(type, value)
+      return if value.nil?
+
+      case type
+      when Array then cast_list(type.first, value)
+      when Class then cast_model(type, value)
+      else Scalars.public_send(Scalars.method_for(type), value)
+      end
+    end
+
+    def self.cast_list(type, value)
+      raise Error, "expected a list, got #{value.class}" unless value.is_a?(Array)
+
+      value.map { |item| cast(type, item) }
+    end
+    private_class_method :cast_list
+
+    # Steam sends an empty array instead of an object when there's nothing
+    # (e.g. an app's mac_requirements)
+    def self.cast_model(model, value)
+      (value == []) ? nil : model.from_json(value)
+    end
+    private_class_method :cast_model
+
+    # Turns models (and lists of them) into plain hashes
+    def self.to_plain(value)
+      case value
+      when Data then value.to_h
+      when Array then value.map { |item| to_plain(item) }
+      else value
+      end
+    end
+
+    # Added to every model class
+    module ClassMethods
+      # Builds the model from Steam's JSON (a Hash with symbol keys)
+      # @raise [Model::Error] if the JSON doesn't match the model
+      def from_json(json)
+        raise Error, "expected an object, got #{json.class}" unless json.is_a?(Hash)
+
+        new(**@fields.transform_values { |field| field.read(json) })
+      end
+    end
+
+    # Added to every model
+    module InstanceMethods
+      # @return [Hash] the fields, with nested models as hashes too
+      def to_h
+        super.transform_values { |value| Model.to_plain(value) }
+      end
+    end
+  end
+end

data/lib/steam_api_client/models/app_details.rb

@@ -0,0 +1,118 @@
+module SteamApiClient
+  # The parts of AppDetails, built first, then named under it below
+  # (e.g. AppDetails::Category)
+  parts = {
+    Requirements: Model.define(
+      # HTML
+      minimum: [:string, optional: true],
+      recommended: [:string, optional: true]
+    ),
+    Price: Model.define(
+      currency: :string,
+      # In cents
+      initial: :integer,
+      final: :integer,
+      discount_percent: :integer,
+      initial_formatted: :string,
+      final_formatted: :string
+    ),
+    Package: Model.define(
+      package_id: [:integer, from: :packageid],
+      percent_savings_text: :string,
+      percent_savings: :integer,
+      option_text: :string,
+      option_description: :string,
+      can_get_free_license: :string,
+      is_free_license: :boolean,
+      price_in_cents_with_discount: :integer
+    ),
+    Platforms: Model.define(windows: :boolean, mac: :boolean, linux: :boolean),
+    Metacritic: Model.define(score: :integer, url: :string),
+    Category: Model.define(id: :integer, description: :string),
+    Genre: Model.define(id: :integer, description: :string),
+    Screenshot: Model.define(id: :integer, path_thumbnail: :string, path_full: :string),
+    Movie: Model.define(
+      id: :integer,
+      name: :string,
+      thumbnail: :string,
+      # Streaming manifests (MPEG-DASH and HLS)
+      dash_av1: [:string, optional: true],
+      dash_h264: [:string, optional: true],
+      hls_h264: [:string, optional: true],
+      highlight: :boolean
+    ),
+    HighlightedAchievement: Model.define(name: :string, path: :string),
+    ReleaseDate: Model.define(coming_soon: :boolean, date: :string),
+    SupportInfo: Model.define(url: :string, email: :string),
+    ContentDescriptors: Model.define(ids: [[:integer], default: []], notes: [:string, optional: true])
+  }
+  parts[:PackageGroup] = Model.define(
+    name: :string,
+    title: :string,
+    description: :string,
+    selection_text: :string,
+    save_text: :string,
+    display_type: :integer,
+    is_recurring_subscription: :string,
+    subs: [[parts[:Package]], default: []]
+  )
+  parts[:Achievements] = Model.define(
+    total: :integer,
+    highlighted: [[parts[:HighlightedAchievement]], default: []]
+  )
+
+  # An app's store page, from `app_details`. Every field is nil when Steam leaves
+  # it out (e.g. when it isn't in the requested filters).
+  # @see https://wiki.teamfortress.com/wiki/User:RJackson/StorefrontAPI#appdetails
+  AppDetails = Model.define(
+    app_id: [:integer, from: :steam_appid, optional: true],
+    # "game", "dlc", "demo", "music"...
+    type: [:string, optional: true],
+    name: [:string, optional: true],
+    required_age: [:integer, optional: true],
+    is_free: [:boolean, optional: true],
+    dlc: [[:integer], optional: true],
+    # HTML
+    detailed_description: [:string, optional: true],
+    about_the_game: [:string, optional: true],
+    short_description: [:string, optional: true],
+    supported_languages: [:string, optional: true],
+    header_image: [:string, optional: true],
+    website: [:string, optional: true],
+    pc_requirements: [parts[:Requirements], optional: true],
+    mac_requirements: [parts[:Requirements], optional: true],
+    linux_requirements: [parts[:Requirements], optional: true],
+    developers: [[:string], optional: true],
+    publishers: [[:string], optional: true],
+    # Not sent for free apps
+    price_overview: [parts[:Price], optional: true],
+    packages: [[:integer], optional: true],
+    package_groups: [[parts[:PackageGroup]], optional: true],
+    platforms: [parts[:Platforms], optional: true],
+    metacritic: [parts[:Metacritic], optional: true],
+    categories: [[parts[:Category]], optional: true],
+    genres: [[parts[:Genre]], optional: true],
+    screenshots: [[parts[:Screenshot]], optional: true],
+    movies: [[parts[:Movie]], optional: true],
+    # Number of user reviews
+    recommendations: [:integer, from: %i[recommendations total], optional: true],
+    achievements: [parts[:Achievements], optional: true],
+    release_date: [parts[:ReleaseDate], optional: true],
+    support_info: [parts[:SupportInfo], optional: true],
+    background: [:string, optional: true],
+    background_raw: [:string, optional: true],
+    content_descriptors: [parts[:ContentDescriptors], optional: true]
+  ) do
+    # Steam keys the response by app ID: {"570": {"success": true, "data": {...}}}.
+    # Returns the data, or nil when the app is unavailable (success: false).
+    # @param [Hash] json
+    # @return [Hash, nil]
+    def self.unwrap(json)
+      app_id, entry = json.first
+      return unless entry.is_a?(Hash) && entry[:success]
+
+      {steam_appid: app_id.to_s}.merge(entry.fetch(:data, {}))
+    end
+  end
+  parts.each { |name, model| AppDetails.const_set(name, model) }
+end

data/lib/steam_api_client/models/friend.rb

@@ -0,0 +1,11 @@
+module SteamApiClient
+  # A friend in a player's friend list, from `player_friends`
+  # @see https://developer.valvesoftware.com/wiki/Steam_Web_API#GetFriendList_.28v0001.29
+  Friend = Model.define(
+    steam_id: [:integer, from: :steamid],
+    # "friend"
+    relationship: :string,
+    # When they became friends, in unix time
+    friend_since: [:integer, optional: true]
+  )
+end

data/lib/steam_api_client/models/game.rb

@@ -0,0 +1,35 @@
+module SteamApiClient
+  # A game in a player's library, from `player_owned_games` and `player_recent_games`.
+  # Playtimes are in minutes.
+  # @see https://developer.valvesoftware.com/wiki/Steam_Web_API#GetOwnedGames_.28v0001.29
+  Game = Model.define(
+    app_id: [:integer, from: :appid],
+    # Name and icon: only with include_appinfo: true (always sent for recent games)
+    name: [:string, optional: true],
+    img_icon_url: [:string, optional: true],
+    playtime_forever: :integer,
+    # Only sent when played in the last two weeks
+    playtime_2weeks: [:integer, optional: true],
+    has_community_visible_stats: [:boolean, optional: true],
+    has_leaderboards: [:boolean, optional: true],
+    content_descriptor_ids: [[:integer], from: :content_descriptorids, optional: true],
+    # Steam doesn't send these for most libraries anymore
+    playtime_windows_forever: [:integer, optional: true],
+    playtime_mac_forever: [:integer, optional: true],
+    playtime_linux_forever: [:integer, optional: true],
+    # Last time played, in unix time
+    rtime_last_played: [:integer, optional: true]
+  )
+
+  # A player's library, from `player_owned_games`
+  OwnedGames = Model.define(
+    game_count: [:integer, optional: true],
+    games: [[Game], default: []]
+  )
+
+  # The games a player played in the last two weeks, from `player_recent_games`
+  RecentGames = Model.define(
+    total_count: [:integer, optional: true],
+    games: [[Game], default: []]
+  )
+end

data/lib/steam_api_client/models/global_achievement.rb

@@ -0,0 +1,10 @@
+module SteamApiClient
+  # The share of players who unlocked an achievement, from `app_global_achievements`
+  # @see https://developer.valvesoftware.com/wiki/Steam_Web_API#GetGlobalAchievementPercentagesForApp_.28v0002.29
+  GlobalAchievement = Model.define(
+    # The achievement's API name
+    name: :string,
+    # Percentage of players, e.g. 49.6
+    percent: :float
+  )
+end

data/lib/steam_api_client/models/news_item.rb

@@ -0,0 +1,20 @@
+module SteamApiClient
+  # A news item of an app, from `app_news`
+  # @see https://developer.valvesoftware.com/wiki/Steam_Web_API#GetNewsForApp_.28v0002.29
+  NewsItem = Model.define(
+    gid: :string,
+    title: :string,
+    url: :string,
+    is_external_url: :boolean,
+    author: :string,
+    # Shortened to the requested maxlength
+    contents: :string,
+    feed_label: [:string, from: :feedlabel],
+    # Publication date, in unix time
+    date: :integer,
+    feed_name: [:string, from: :feedname],
+    feed_type: :integer,
+    app_id: [:integer, from: :appid],
+    tags: [[:string], optional: true]
+  )
+end

data/lib/steam_api_client/models/player_achievements.rb

@@ -0,0 +1,19 @@
+module SteamApiClient
+  # Built first, then named PlayerAchievements::Achievement below
+  achievement = Model.define(
+    # The achievement's API name, e.g. "TF_PLAY_GAME_EVERYCLASS"
+    api_name: [:string, from: :apiname],
+    achieved: :boolean,
+    # When it was unlocked, in unix time (0 when locked, or unknown)
+    unlock_time: [:integer, from: :unlocktime, optional: true]
+  )
+
+  # A player's achievements in a game, from `player_achievements`
+  # @see https://developer.valvesoftware.com/wiki/Steam_Web_API#GetPlayerAchievements_.28v0001.29
+  PlayerAchievements = Model.define(
+    steam_id: [:integer, from: :steamID, optional: true],
+    game_name: [:string, from: :gameName, optional: true],
+    achievements: [[achievement], default: []]
+  )
+  PlayerAchievements.const_set(:Achievement, achievement)
+end

data/lib/steam_api_client/models/player_game_stats.rb

@@ -0,0 +1,25 @@
+module SteamApiClient
+  # Built first, then named under PlayerGameStats below
+  stat = Model.define(
+    # A game-defined stat, e.g. "Scout.accum.iDamageDealt"
+    name: :string,
+    # Integer or Float, as Steam sends it
+    value: :number
+  )
+  achievement = Model.define(
+    # The achievement's API name, e.g. "TF_PLAY_GAME_EVERYCLASS"
+    name: :string,
+    achieved: :boolean
+  )
+
+  # A player's stats and unlocked achievements in a game, from `player_game_stats`
+  # @see https://developer.valvesoftware.com/wiki/Steam_Web_API#GetUserStatsForGame_.28v0002.29
+  PlayerGameStats = Model.define(
+    steam_id: [:integer, from: :steamID, optional: true],
+    game_name: [:string, from: :gameName, optional: true],
+    stats: [[stat], default: []],
+    achievements: [[achievement], default: []]
+  )
+  PlayerGameStats.const_set(:Stat, stat)
+  PlayerGameStats.const_set(:Achievement, achievement)
+end

data/lib/steam_api_client/models/player_summary.rb

@@ -0,0 +1,37 @@
+module SteamApiClient
+  # A player's public profile, from `player_summaries`. The optional fields are
+  # nil when the profile (or that part of it) isn't public.
+  # @see https://developer.valvesoftware.com/wiki/Steam_Web_API#GetPlayerSummaries_.28v0002.29
+  PlayerSummary = Model.define(
+    # 64 bit SteamID
+    steam_id: [:integer, from: :steamid],
+    # Display name
+    persona_name: [:string, from: :personaname],
+    profile_url: [:string, from: :profileurl],
+    # 32x32, 64x64 and 184x184 avatar URLs (Steam's "?" avatar when none is set)
+    avatar: :string,
+    avatar_medium: [:string, from: :avatarmedium],
+    avatar_full: [:string, from: :avatarfull],
+    # Hash used in the avatar URLs
+    avatar_hash: [:string, from: :avatarhash, optional: true],
+    # 0 offline, 1 online, 2 busy, 3 away, 4 snooze, 5 looking to trade, 6 looking to play.
+    # Always 0 for private profiles.
+    persona_state: [:integer, from: :personastate],
+    persona_state_flags: [:integer, from: :personastateflags, optional: true],
+    # 1 private (not visible to you), 3 public
+    community_visibility_state: [:integer, from: :communityvisibilitystate],
+    # 1 when the player has set up a community profile
+    profile_state: [:integer, from: :profilestate, optional: true],
+    # Last time online, in unix time
+    last_logoff: [:integer, from: :lastlogoff, optional: true],
+    # 1 when the profile allows public comments
+    comment_permission: [:integer, from: :commentpermission, optional: true],
+    real_name: [:string, from: :realname, optional: true],
+    # Account creation, in unix time
+    time_created: [:integer, from: :timecreated, optional: true],
+    # ISO 3166 country code
+    country_code: [:string, from: :loccountrycode, optional: true],
+    # The player's primary group (a group SteamID)
+    primary_clan_id: [:integer, from: :primaryclanid, optional: true]
+  )
+end

data/lib/steam_api_client/request.rb

@@ -1,93 +1,87 @@
 module SteamApiClient
+  # One call to an endpoint: builds the URL from the arguments and sends it
+  # through the client's Faraday connection
   class Request
-    def initialize(request_struct:, response_struct:, client:)
+    # The API token in a request URL's query string
+    API_KEY_PARAM = /(?<=[?&]key=)[^&]*/
+
+    # @param [SteamApiClient::Endpoint] endpoint
+    # @param [Hash] params the keyword arguments given to #retrieve
+    # @param [SteamApiClient::Client] client
+    # @raise [ArgumentError] on missing, unknown or invalid params
+    # @raise [SteamApiClient::Errors::MissingApiToken] if the endpoint needs a token and the client has none
+    def initialize(endpoint:, params:, client:)
       @failure_handler = SteamApiClient::FailureHandler.instance
-      @request_struct = request_struct
-      @response_struct = response_struct
+      @endpoint = endpoint
       @client = client
 
+      query = endpoint.query(params)
       ensure_api_token!
-      build_request
+      @url = build_url(query)
     end
 
     def run
       freeze
 
-      raw_response = @raw_request.run
+      raw_response = perform
 
-      Response.new(raw_response: raw_response, response_struct: response_struct, request: self).tap do |response|
+      Response.new(raw_response: raw_response, endpoint: endpoint, request: self).tap do |response|
         failure_handler.call(response)
       end
     end
 
-    private
-
-    attr_accessor :request_struct, :response_struct, :client, :raw_request, :failure_handler
-
-    def ensure_api_token!
-      return unless request_struct.needs_authorization?
-      return unless client.api_token.to_s.empty?
-
-      raise SteamApiClient::Errors::MissingApiToken
+    # Shows the method and the URL, with the API token redacted
+    # @return [String]
+    def inspect
+      "#<#{self.class.name} GET #{url.sub(API_KEY_PARAM, "[REDACTED]")}>"
     end
 
-    def build_request
-      url = nil
+    private
 
-      case request_struct.endpoint_kind
-      when :base_endpoint then url = build_base_url
-      when :storefront_endpoint then url = build_storefront_url
-      else raise SteamApiClient::Errors::EndpointKindNotSupported
-      end
+    attr_reader :endpoint, :client, :url, :failure_handler
 
-      @raw_request = ::Typhoeus::Request.new(url.to_s, build_options)
+    # Sends the request through the client's Faraday connection, turning
+    # Faraday's network errors into the gem's errors (the original is #cause).
+    # Every Steam endpoint is a GET, with its params in the query string.
+    def perform
+      client.connection.run_request(:get, url, nil, nil) do |request|
+        request_options.each { |option, value| request.options.public_send(:"#{option}=", value) }
+      end
+    rescue ::Faraday::TimeoutError
+      raise_timeout
+    rescue ::Faraday::ConnectionFailed => error
+      # Faraday reports a connect timeout (Net::OpenTimeout) as ConnectionFailed
+      raise_timeout if error.wrapped_exception.is_a?(::Timeout::Error)
+      raise SteamApiClient::Errors::ConnectionError, "Could not connect to Steam: #{error.message}"
+    rescue ::Faraday::SSLError => error
+      raise SteamApiClient::Errors::ConnectionError, "Could not connect to Steam: #{error.message}"
     end
 
-    def build_base_url
-      url = URI.join(
-        client.base_endpoint,
-        request_struct.interface,
-        request_struct.path,
-        request_struct.version
+    def raise_timeout
+      raise SteamApiClient::Errors::HttpTimeout.new(
+        nil, "The request to Steam timed out (timeout: #{client.timeout}s, connect_timeout: #{client.connect_timeout}s)"
       )
-      url.query = query_params
-
-      url
     end
 
-    def build_storefront_url
-      url = URI.join(
-        client.storefront_endpoint,
-        request_struct.path
-      )
-      url.query = query_params
-
-      url
+    def request_options
+      {timeout: client.timeout, open_timeout: client.connect_timeout}
     end
 
-    def query_params
-      all_params = {}.tap do |params|
-        params[:key] = client.api_token if request_struct.needs_authorization?
-        params.merge!(request_struct.query_params)
-      end
+    def ensure_api_token!
+      return unless endpoint.key?
+      return unless client.api_token.to_s.empty?
 
-      URI.encode_www_form(all_params)
+      raise SteamApiClient::Errors::MissingApiToken
     end
 
-    def build_options
-      options = {
-        method: request_struct.method,
-        headers: {},
-        followlocation: true,
-        timeout_ms: (client.timeout * 1000).to_i,
-        connecttimeout_ms: (client.connect_timeout * 1000).to_i,
-        # Required for sub-second timeouts and safe use of timeouts across threads
-        nosignal: true
-      }
-      # GET requests (every Steam endpoint so far) carry their params in the query string
-      return options if request_struct.method == :get
+    # The API key goes first, then the endpoint's params
+    def build_url(query)
+      query = {key: client.api_token}.merge(query) if endpoint.key?
+      base = (endpoint.api == :store) ? client.storefront_endpoint : client.base_endpoint
 
-      options.merge(headers: {"Content-Type" => "application/json"}, body: request_struct.body.to_json)
+      url = URI.join(base, endpoint.path)
+      url.query = URI.encode_www_form(query)
+      url.to_s
     end
   end
 end

data/lib/steam_api_client/requestor.rb

@@ -0,0 +1,42 @@
+module SteamApiClient
+  # What the client exposes for each endpoint, e.g. `client.player_level`
+  class Requestor
+    attr_reader :endpoint
+
+    # @param [SteamApiClient::Client] client
+    # @param [SteamApiClient::Endpoint] endpoint
+    def initialize(client, endpoint)
+      @client = client
+      @endpoint = endpoint
+    end
+
+    # Calls the endpoint. The keyword arguments are the endpoint's params
+    # (see SteamApiClient::Endpoints).
+    # @return [Data, Array, Integer, nil] the endpoint's result
+    # @raise [ArgumentError] on missing, unknown or invalid arguments
+    def retrieve(**params)
+      run(params).result
+    end
+
+    # Calls the endpoint and returns Steam's JSON untouched (keys symbolized), e.g.
+    # for fields the result doesn't have
+    # @return [Hash]
+    def retrieve_raw(**params)
+      run(params).json
+    end
+
+    # Keeps the client (and its token) out of the output
+    # @return [String]
+    def inspect
+      "#<#{self.class.name} #{endpoint.name} #{endpoint.path}>"
+    end
+
+    private
+
+    attr_reader :client
+
+    def run(params)
+      Request.new(endpoint: endpoint, params: params, client: client).run
+    end
+  end
+end