steam_api_client 0.9.0

data/lib/steam_api_client/client.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module SteamApiClient
+  # Main class to interact with the Steam Api.
+
+  # Before using this client, you need to configure the
+  # credentials through the 'SteamApiClient::Client.configure' method:
+  #
+  # ```ruby
+  # SteamApiClient::Client.configure do |config|
+  #   config.api_token = 'token-value'
+  # end
+  # ```
+  #
+  # All API calls take the form:
+  # http://api.steampowered.com/<interface name>/<method name>/<version>/?key=<api key>&format=<format>.
+  # Format can be any of:
+  #   json - The output will be returned in the JSON format
+  #   xml - Output is returned as an XML document
+  #   vdf - Output is returned as a VDF file.
+  # If you do not specify a format, your results will be returns in the JSON format.
+  #
+  # As we dive deeper into the implementation and find more endpoints to include in this
+  # gem, some changes were needed to support the storefront API which is what Steam's
+  # Big Picture Mode uses.
+  # All API calls take the form:
+  # https://store.steampowered.com/api/<method>?appids=1,2,3&filters=basic,recommendations
+  # For more information, vist: https://wiki.teamfortress.com/wiki/User:RJackson/StorefrontAPI
+  class Client
+    extend ::Dry::Configurable
+
+    BASE_ENDPOINT = "https://api.steampowered.com"
+    STOREFRONT_API_ENDPOINT = "https://store.steampowered.com/api/"
+    DEFAULT_TIMEOUT = 10
+    DEFAULT_CONNECT_TIMEOUT = 5
+
+    setting :api_token
+    # Maximum time, in seconds, for the whole request
+    setting :timeout, default: DEFAULT_TIMEOUT
+    # Maximum time, in seconds, to establish the connection
+    setting :connect_timeout, default: DEFAULT_CONNECT_TIMEOUT
+
+    attr_writer :api_token, :timeout, :connect_timeout
+
+    attr_reader \
+      :app_details,
+      :app_global_achievements,
+      :app_news,
+      :game_current_players,
+      :player_achievements,
+      :player_friends,
+      :player_game_stats,
+      :player_level,
+      :player_owned_games,
+      :player_recent_games,
+      :player_steamid,
+      :player_summaries
+
+    # Initialize the client
+    # @param [String] api_token - An existing api token.
+    # @param [Numeric] timeout - Request timeout in seconds. Defaults to the configured value.
+    # @param [Numeric] connect_timeout - Connection timeout in seconds. Defaults to the configured value.
+    # @return [SteamApiClient::Client] - A new class instance.
+    def initialize(api_token: nil, timeout: nil, connect_timeout: nil)
+      @api_token = api_token
+      @timeout = timeout
+      @connect_timeout = connect_timeout
+
+      @app_details ||= SteamApiClient::Requestors::AppDetails.new(self)
+      @app_global_achievements ||= SteamApiClient::Requestors::AppGlobalAchievements.new(self)
+      @app_news ||= SteamApiClient::Requestors::AppNews.new(self)
+      @game_current_players ||= SteamApiClient::Requestors::GameCurrentPlayers.new(self)
+      @player_achievements ||= SteamApiClient::Requestors::PlayerAchievements.new(self)
+      @player_friends ||= SteamApiClient::Requestors::PlayerFriends.new(self)
+      @player_game_stats ||= SteamApiClient::Requestors::PlayerGameStats.new(self)
+      @player_level ||= SteamApiClient::Requestors::PlayerLevel.new(self)
+      @player_owned_games ||= SteamApiClient::Requestors::PlayerOwnedGames.new(self)
+      @player_recent_games ||= SteamApiClient::Requestors::PlayerRecentGames.new(self)
+      @player_steamid ||= SteamApiClient::Requestors::PlayerSteamId.new(self)
+      @player_summaries ||= SteamApiClient::Requestors::PlayerSummaries.new(self)
+    end
+
+    # The token sent on authorized requests. Falls back to the value set
+    # through 'SteamApiClient::Client.configure' when none was given to the instance.
+    # @return [String, nil]
+    def api_token
+      @api_token || config.api_token
+    end
+
+    # @return [Numeric] the request timeout in seconds
+    def timeout
+      @timeout || config.timeout
+    end
+
+    # @return [Numeric] the connection timeout in seconds
+    def connect_timeout
+      @connect_timeout || config.connect_timeout
+    end
+
+    def config
+      self.class.config
+    end
+
+    def base_endpoint
+      BASE_ENDPOINT
+    end
+
+    def storefront_endpoint
+      STOREFRONT_API_ENDPOINT
+    end
+  end
+end

data/lib/steam_api_client/errors/api_error.rb

@@ -0,0 +1,48 @@
+module SteamApiClient
+  module Errors
+    # Error class that wraps an Api request failed
+    #
+    class ApiError < ::StandardError
+      # Initializes a request API custom error
+      # @param [SteamApiClient::Response] Http response wrapper
+      # @return A new instance of ApiError
+      #
+      def initialize(response)
+        @http_status_code = response.status_code
+        @response = response
+        @request = response.request
+
+        super(build_description_message)
+      end
+
+      private
+
+      attr_accessor :http_status_code, :response
+
+      def build_description_message
+        <<~MESSAGE.split.join(" ")
+          A request failed with the following status code: #{http_status_code}
+          and body: #{response.body}
+        MESSAGE
+      end
+    end
+
+    # status_code: 400
+    class HttpBadRequest < ApiError; end
+
+    # status_code: 401
+    class HttpUnauthorized < ApiError; end
+
+    # status_code: 403
+    class HttpForbidden < ApiError; end
+
+    # status_code: 404
+    class HttpNotFound < ApiError; end
+
+    # status_code: 408
+    class HttpTimeout < ApiError; end
+
+    # status_code: 500
+    class HttpInternalServerError < ApiError; end
+  end
+end

data/lib/steam_api_client/errors/response_parse_error.rb

@@ -0,0 +1,19 @@
+module SteamApiClient
+  module Errors
+    # Raised when an API response can't be built into its response struct,
+    # e.g. the body isn't a JSON object or doesn't match the struct's schema.
+    # The underlying JSON or Dry::Struct error is available through #cause.
+    class ResponseParseError < ::StandardError
+      attr_reader :response
+
+      # @param [SteamApiClient::Response] response Http response wrapper
+      # @param [Class] response_struct The struct the response was built into
+      # @return A new instance of ResponseParseError
+      def initialize(response, response_struct)
+        @response = response
+
+        super("Unable to build #{response_struct} from the API response (status code: #{response.status_code})")
+      end
+    end
+  end
+end

data/lib/steam_api_client/errors/url_error.rb

@@ -0,0 +1,5 @@
+module SteamApiClient
+  module Errors
+    class EndpointKindNotSupported < ::StandardError; end
+  end
+end

data/lib/steam_api_client/failure_handler.rb

@@ -0,0 +1,46 @@
+module SteamApiClient
+  # Class that checks an Api response and raise the correct exception
+  class FailureHandler
+    include Singleton
+
+    # Perform the check
+    # @param [SteamApiClient::Response] the response received from the Api
+    # @return [NilClass] if response was successful
+    # @raise [SteamApiClient::Errors::ApiError] if response was a failure.
+    def call(response)
+      return unless response.fail?
+
+      raise_timedout(response) if response.timed_out?
+
+      raise_response_4xx(response) if (400..499).cover?(response.status_code)
+      raise_response_5xx(response) if (500..599).cover?(response.status_code)
+
+      raise_api_error(response)
+    end
+
+    private
+
+    def raise_timedout(response)
+      raise SteamApiClient::Errors::HttpTimeout, response
+    end
+
+    def raise_response_4xx(response)
+      case response.status_code
+      when 400 then raise SteamApiClient::Errors::HttpBadRequest, response
+      when 401 then raise SteamApiClient::Errors::HttpUnauthorized, response
+      when 403 then raise SteamApiClient::Errors::HttpForbidden, response
+      when 404 then raise SteamApiClient::Errors::HttpNotFound, response
+      end
+    end
+
+    def raise_response_5xx(response)
+      case response.status_code
+      when 500 then raise SteamApiClient::Errors::HttpInternalServerError, response
+      end
+    end
+
+    def raise_api_error(response)
+      raise SteamApiClient::Errors::ApiError, response
+    end
+  end
+end

data/lib/steam_api_client/request.rb

@@ -0,0 +1,86 @@
+module SteamApiClient
+  class Request
+    def initialize(request_struct:, response_struct:, client:)
+      @failure_handler = SteamApiClient::FailureHandler.instance
+      @request_struct = request_struct
+      @response_struct = response_struct
+      @client = client
+
+      build_request
+    end
+
+    def run
+      freeze
+
+      raw_response = @raw_request.run
+
+      Response.new(raw_response: raw_response, response_struct: response_struct, request: self).tap do |response|
+        failure_handler.call(response)
+      end
+    end
+
+    private
+
+    attr_accessor :request_struct, :response_struct, :client, :raw_request, :failure_handler
+
+    def build_request
+      url = nil
+
+      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
+
+      @raw_request = ::Typhoeus::Request.new(url.to_s, build_options)
+    end
+
+    def build_base_url
+      url = URI.join(
+        client.base_endpoint,
+        request_struct.interface,
+        request_struct.path,
+        request_struct.version
+      )
+      url.query = query_params
+
+      url
+    end
+
+    def build_storefront_url
+      url = URI.join(
+        client.storefront_endpoint,
+        request_struct.path
+      )
+      url.query = query_params
+
+      url
+    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
+
+      URI.encode_www_form(all_params)
+    end
+
+    def build_options
+      {
+        method: request_struct.method,
+        headers: default_headers,
+        body: request_struct.body.to_json,
+        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
+      }
+    end
+
+    def default_headers
+      {"Content-Type" => "application/json"}
+    end
+  end
+end

data/lib/steam_api_client/requestors/app_details.rb

@@ -0,0 +1,27 @@
+module SteamApiClient
+  module Requestors
+    # Class that expose the necessary method(s) to get the details of an
+    # app in the Steam Storefront Api.
+    class AppDetails < Base
+      # Get on the Api the details of an app.
+      # @param [Integer] appid The Steam app id
+      # @param [Array<Integer>] filters The Steam to filter field values
+      # @param [String] country_code Country code for method to return appropriate currency values.
+      #   Defaults to 'US'.
+      # @param [String] locale Localized ISO 639-1 string.
+      #   Defaults to 'en'.
+      # @return [SteamApiClient::Structs::AppDetails::Details] instance with the app details.
+      #   When the app is unavailable, `response.success` is false and `response.data` is nil.
+      def retrieve(appid:, filters: [], country_code: "US", locale: "en")
+        build_request_and_run(
+          SteamApiClient::Structs::Requests::GetAppDetails,
+          SteamApiClient::Structs::AppDetails::Details,
+          appid: appid,
+          filters: filters,
+          cc: country_code,
+          l: locale
+        )
+      end
+    end
+  end
+end

data/lib/steam_api_client/requestors/app_global_achievements.rb

@@ -0,0 +1,19 @@
+module SteamApiClient
+  module Requestors
+    # Class that expose the necessary method(s) to get the global achievements
+    # of an app in the Steam Web Api.
+    class AppGlobalAchievements < Base
+      # Get on the Api all global achievements info of an App in the Steam.
+      # @param [Integer] gameid The Steam app id
+      # @return [SteamApiClient::Structs::AppGlobalAchievements] instance with the
+      #   player summary details.
+      def retrieve(gameid)
+        build_request_and_run(
+          SteamApiClient::Structs::Requests::GetAppGlobalAchievements,
+          SteamApiClient::Structs::AppGlobalAchievements,
+          gameid: gameid
+        )
+      end
+    end
+  end
+end

data/lib/steam_api_client/requestors/app_news.rb

@@ -0,0 +1,23 @@
+module SteamApiClient
+  module Requestors
+    # Class that expose the necessary method(s) to get the news of an
+    # app in the Steam Web Api.
+    class AppNews < Base
+      # Get on the Api one or more news of an App in the Steam.
+      # @param [Integer] appid The Steam app id
+      # @param [Integer] count The number of wanted news
+      # @param [Integer] maxlength The max length of the news content
+      # @return [SteamApiClient::Structs::AppNews] instance with the
+      #   player summary details.
+      def retrieve(appid, count, maxlength = 300)
+        build_request_and_run(
+          SteamApiClient::Structs::Requests::GetAppNews,
+          SteamApiClient::Structs::AppNews,
+          appid: appid,
+          count: count,
+          maxlength: maxlength
+        )
+      end
+    end
+  end
+end

data/lib/steam_api_client/requestors/base.rb

@@ -0,0 +1,32 @@
+module SteamApiClient
+  module Requestors
+    # Class responsible to expose the methods necessary to perform a request
+    # on the Steam Web Api.
+    # @abstract class for the Requestors
+    class Base
+      # Initialize the class
+      # @param [SteamApiClient::Client] the client object.
+      def initialize(client)
+        @client = client
+      end
+
+      protected
+
+      # Build an Request and executes it
+      def build_request_and_run(request_struct_class, response_struct_class, **params)
+        request_struct = request_struct_class.build_from_params(params)
+
+        response = build_request(request_struct, response_struct_class).run
+        response.result
+      end
+
+      attr_accessor :client
+
+      private
+
+      def build_request(request_struct, response_struct_class)
+        Request.new(request_struct: request_struct, response_struct: response_struct_class, client: client)
+      end
+    end
+  end
+end

data/lib/steam_api_client/requestors/game_current_players.rb

@@ -0,0 +1,19 @@
+module SteamApiClient
+  module Requestors
+    # Class that expose the necessary method(s) to get number of current players
+    # for a game in the Steam Web Api.
+    class GameCurrentPlayers < Base
+      # Get the number of current players for a game.
+      # @param [Integer] appid The Steam app id
+      # @return [SteamApiClient::Structs::GameCurrentPlayers] instance with the
+      #   game current players count.
+      def retrieve(appid)
+        build_request_and_run(
+          SteamApiClient::Structs::Requests::GetGameCurrentPlayers,
+          SteamApiClient::Structs::GameCurrentPlayers,
+          appid: appid
+        )
+      end
+    end
+  end
+end

data/lib/steam_api_client/requestors/player_achievements.rb

@@ -0,0 +1,21 @@
+module SteamApiClient
+  module Requestors
+    # Class that exposes the necessary method(s) to get the achievements of a
+    # player for a given app.
+    class PlayerAchievements < Base
+      # Returns a list of achievements for a user by app id.
+      # @param [Integer] appid The Steam app id
+      # @param [Integer] steamid The Steam user id
+      # @return [SteamApiClient::Structs::PlayerAchievements] instance with the
+      #   player summary details.
+      def retrieve(appid, steamid)
+        build_request_and_run(
+          SteamApiClient::Structs::Requests::GetPlayerAchievements,
+          SteamApiClient::Structs::PlayerAchievements,
+          appid: appid,
+          steamid: steamid
+        )
+      end
+    end
+  end
+end

data/lib/steam_api_client/requestors/player_friends.rb

@@ -0,0 +1,21 @@
+module SteamApiClient
+  module Requestors
+    # Class that expose the necessary method(s) to get an User
+    # friend list in the Steam Web Api.
+    class PlayerFriends < Base
+      # Get an User complete friend list, if public.
+      # @param [Integer] steamid The Steam user id
+      # @param [String] relationship Relationship filter. Possibles values: 'all', 'friend'.
+      # @return [SteamApiClient::Structs::PlayerFriends] instance with the
+      #   player friends list.
+      def retrieve(steamid, relationship = "all")
+        build_request_and_run(
+          SteamApiClient::Structs::Requests::GetPlayerFriends,
+          SteamApiClient::Structs::PlayerFriends,
+          steamid: steamid,
+          relationship: relationship
+        )
+      end
+    end
+  end
+end

data/lib/steam_api_client/requestors/player_game_stats.rb

@@ -0,0 +1,21 @@
+module SteamApiClient
+  module Requestors
+    # Class that exposes the necessary method(s) to get the stats of a
+    # player for a given game/appid.
+    class PlayerGameStats < Base
+      # Returns a list of stats for a user for a given game/appid.
+      # @param [Integer] appid The Steam app id
+      # @param [Integer] steamid The Steam user id
+      # @return [SteamApiClient::Structs::PlayerGameStats] instance with the
+      #   player summary details.
+      def retrieve(appid, steamid)
+        build_request_and_run(
+          SteamApiClient::Structs::Requests::GetPlayerGameStats,
+          SteamApiClient::Structs::PlayerGameStats,
+          appid: appid,
+          steamid: steamid
+        )
+      end
+    end
+  end
+end

data/lib/steam_api_client/requestors/player_level.rb

@@ -0,0 +1,18 @@
+module SteamApiClient
+  module Requestors
+    # Class that exposes the necessary method(s) to get level of an user.
+    class PlayerLevel < Base
+      # Returns the user current level on Steam.
+      # @param [Integer] steamid The Steam user id
+      # @return [SteamApiClient::Structs::PlayerLevel] instance with the
+      #   player level.
+      def retrieve(steamid)
+        build_request_and_run(
+          SteamApiClient::Structs::Requests::GetPlayerLevel,
+          SteamApiClient::Structs::PlayerLevel,
+          steamid: steamid
+        )
+      end
+    end
+  end
+end

data/lib/steam_api_client/requestors/player_owned_games.rb

@@ -0,0 +1,23 @@
+module SteamApiClient
+  module Requestors
+    # Class that exposes the necessary method(s) to get a list of
+    # the player owned games, if public.
+    class PlayerOwnedGames < Base
+      # Returns a list of all games owned by the user.
+      # @param [Integer] steamid The Steam user id
+      # @param [Boolean] include_appinfo Flag to include all game related information
+      # @param [Boolean] include_played_free_games Flag to include free games
+      # @return [SteamApiClient::Structs::PlayerOwnedGames] instance with the
+      #   player owned games details.
+      def retrieve(steamid, include_appinfo: false, include_played_free_games: false)
+        build_request_and_run(
+          SteamApiClient::Structs::Requests::GetPlayerOwnedGames,
+          SteamApiClient::Structs::PlayerOwnedGames,
+          steamid: steamid,
+          include_appinfo: include_appinfo,
+          include_played_free_games: include_played_free_games
+        )
+      end
+    end
+  end
+end

data/lib/steam_api_client/requestors/player_recent_games.rb

@@ -0,0 +1,21 @@
+module SteamApiClient
+  module Requestors
+    # Class that exposes the necessary method(s) to get a list of
+    # recently played games for a user.
+    class PlayerRecentGames < Base
+      # Returns a list of recently played games for a user.
+      # @param [Integer] steamid - The Steam user id
+      # @param [Integer] count - The number of games that should return
+      # @return [SteamApiClient::Structs::PlayerRecentGames] instance with the
+      #   player summary details.
+      def retrieve(steamid, count = 5)
+        build_request_and_run(
+          SteamApiClient::Structs::Requests::GetPlayerRecentGames,
+          SteamApiClient::Structs::PlayerRecentGames,
+          steamid: steamid,
+          count: count
+        )
+      end
+    end
+  end
+end

data/lib/steam_api_client/requestors/player_steamid.rb

@@ -0,0 +1,19 @@
+module SteamApiClient
+  module Requestors
+    # Class that exposes the necessary method(s) to get The 64 bit Steam ID
+    # the vanity URL resolves to.
+    class PlayerSteamId < Base
+      # Returns the 64 bit Steam ID the vanity URL resolves to.
+      # @param [String] vanityurl - The Steam user short url
+      # @return [SteamApiClient::Structs::PlayerSteamId] instance with the
+      #   player SteamId.
+      def retrieve(vanityurl)
+        build_request_and_run(
+          SteamApiClient::Structs::Requests::GetPlayerSteamId,
+          SteamApiClient::Structs::PlayerSteamId,
+          vanityurl: vanityurl
+        )
+      end
+    end
+  end
+end

data/lib/steam_api_client/requestors/player_summaries.rb

@@ -0,0 +1,19 @@
+module SteamApiClient
+  module Requestors
+    # Class that expose the necessary method(s) to get the summary of a
+    # player profile in the Steam Web Api.
+    class PlayerSummaries < Base
+      # Get on the Api the summary of a player profile.
+      # @param [Array<Integer>] steamids - The Steam order's id
+      # @return [SteamApiClient::Structs::PlayerSummaries] instance with the
+      #   player summary details.
+      def retrieve(steamids)
+        build_request_and_run(
+          SteamApiClient::Structs::Requests::GetPlayerSummaries,
+          SteamApiClient::Structs::PlayerSummaries,
+          steamids: steamids
+        )
+      end
+    end
+  end
+end

data/lib/steam_api_client/response.rb

@@ -0,0 +1,64 @@
+require "forwardable"
+
+module SteamApiClient
+  # Wraps the raw response received from the Api
+  class Response
+    extend Forwardable
+
+    def_delegators :@raw_response, :timed_out?, :success?, :body
+    attr_accessor :request
+
+    # Initialize a new instance
+    # @param [Typhoeus::Response] raw_response
+    # @param [SteamApiClient::Structs::Base] response_struct The struct necessary to
+    #   build the response received from Api
+    # @param [SteamApiClient::Request] request The wrapper Request class
+    def initialize(raw_response:, response_struct:, request:)
+      @raw_response = raw_response
+      @response_struct = response_struct
+      @request = request
+    end
+
+    # Check if the request was successful or not
+    # @return [Boolean]
+    def fail?
+      !success?
+    end
+
+    # Returns the HTTP status code
+    # @return [Integer]
+    def status_code
+      raw_response.code
+    end
+
+    # Parses the response's json body as a Hash. If the response body isn't a json
+    # returns an empty hash
+    # @return [Hash]
+    def to_h
+      parse_body
+    rescue JSON::ParserError
+      {}
+    end
+
+    # Parses the response's json body and build the expected struct
+    # @return [SteamApiClient::Structs::Base]
+    # @raise [SteamApiClient::Errors::ResponseParseError] if the body isn't a JSON object
+    #   or doesn't match the response struct
+    def result
+      json_response = parse_body
+      raise TypeError, "expected a JSON object, got #{json_response.class}" unless json_response.is_a?(Hash)
+
+      response_struct.build_from_response(json_response)
+    rescue JSON::ParserError, TypeError, Dry::Struct::Error
+      raise Errors::ResponseParseError.new(self, response_struct)
+    end
+
+    private
+
+    attr_accessor :raw_response, :response_struct
+
+    def parse_body
+      ::JSON.parse(raw_response.body.to_s, symbolize_names: true)
+    end
+  end
+end