steam_web_api 0.0.1

data/README.md

@@ -0,0 +1,356 @@
+# SteamWebApi
+
+[![Build Status](https://api.travis-ci.org/Olgagr/steam-web-api.svg?branch=master)](https://api.travis-ci.org/Olgagr/steam-web-api.svg?branch=master) [![Code Climate](https://codeclimate.com/github/Olgagr/steam-web-api/badges/gpa.svg)](https://codeclimate.com/github/Olgagr/steam-web-api) [![Test Coverage](https://codeclimate.com/github/Olgagr/steam-web-api/badges/coverage.svg)](https://codeclimate.com/github/Olgagr/steam-web-api)
+
+This is a gem that makes trivial interacting with the Steam Web API. It supports all methods listed here: https://developer.valvesoftware.com/wiki/Steam_Web_API and [one more](#get-list-of-all-games).
+
+## Supported Ruby version
+
+Gem supports Ruby: 2.0, 2.1, 2.2
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'steam_web_api', git: 'https://github.com/Olgagr/steam-web-api.git'
+```
+
+And then execute:
+
+    $ bundle
+
+## Usage
+
+### Configuration
+
+Some Steam Web API methods return publicly accessible data and do not require authorization when called. Other methods may require clients to register for an API key and pass that in using the key parameter. There are also methods that return sensitive data or perform a protected action and require special access permissions. To retrieve API key for your application, you'll need log in to your Steam account and fill [this form](http://steamcommunity.com/dev/apikey)
+
+When you have your API key, you can configure the gem:
+
+```ruby
+# for Rails, you can put this code in initializer: config/initializers/steam_web_api.rb
+SteamWebApi.configure do |config|
+	config.api_key = 'your api key'
+end
+```
+
+This is better not to include API key as plain text in you repository. For better solution, please check [dotenv gem](https://github.com/bkeepers/dotenv).
+
+### Player
+
+#### Get list of owned games
+(https://developer.valvesoftware.com/wiki/Steam_Web_API#GetOwnedGames_.28v0001.29). To make this API call, you need to have API key for your app and steam identifier of the Steam user.
+
+```ruby
+# player_steam_id - this is a Steam identifier for user
+player = SteamWebApi::Player(player_steam_id)
+data = player.owned_games
+data.count # how many games user posses (integer)
+data.games # list of user's games
+data.success # boolean value indicates if response was succesful
+
+# game datails
+game = data.games.first
+game['appid'] # identifier for game (integer)
+game['playtime_forever'] # total playtime for game (integer)
+
+# additional options
+# 1. include_played_free_games - include free games in results
+# 2. include_appinfo - include game name and logo information in the output. The default is to return appids only.
+data = player.owned_games(include_played_free_games: true, include_appinfo: true)
+
+# if include_appinfo is set to true
+game = data.games.first
+game['name'] # game's name
+game['playtime_2weeks'] # total number of minutes played in the last 2 weeks
+game['img_icon_url'] # filename of game's icon
+game['img_logo_url'] # filename of game logo
+game['has_community_visible_stats'] # indicates there is a stats page with achievements or other game stats available for this game
+```
+
+#### Get user stats for game
+(https://developer.valvesoftware.com/wiki/Steam_Web_API#GetUserStatsForGame_.28v0002.29). To make this API call, you need to have API key for your app and steam identifier of the Steam user.
+
+```ruby
+player = SteamWebApi::Player(player_steam_id)
+data = player.stats_for_game(game_id)
+
+data.steam_id # user steam identifier
+data.game_name # game name
+data.achievements # list of achievements
+data.stats # list of stats
+data.success # boolean value indicates if response was succesful. If false, probably the game doesn't have stats and Steam returns 400 status
+
+achievement = data.achievements.first
+achievement['name'] # achievement identifier
+achievement['achieved'] # integer (0 or 1)
+
+stat = data.stats.first
+stat['name']
+stat['value'] # integer
+```
+
+#### Get user achievements for game
+(https://developer.valvesoftware.com/wiki/Steam_Web_API#GetPlayerAchievements_.28v0001.29). To make this API call, you need to have API key for your app and steam identifier of the Steam user.
+
+```ruby
+player = SteamWebApi::Player(player_steam_id)
+data = player.achievements(game_id)
+
+data.steam_id # user steam identifier
+data.game_name # game name
+data.achievements # list of achievements
+data.success # boolean value indicates if response was succesful. If false, probably the game doesn't have stats and Steam returns 400 status
+
+achievement = data.achievements.first
+achievement['apiname'] # achievement name
+achievement['achieved'] # integer (0 or 1)
+
+# additional options
+# 1. l - Language. If specified, it will return language data (name, description) for the requested language.
+data = player.achievements(game_id, l: 'en')
+achievement = data.achievements.first
+achievement['name'] # achievement name
+achievement['description'] # achievement description
+```
+
+#### Get accounts summaries for list of players
+(https://developer.valvesoftware.com/wiki/Steam_Web_API#GetPlayerSummaries_.28v0002.29). To make this API call, you need to have API key for your app and steam identifier of the Steam user.
+
+```ruby
+data = SteamWebApi::Player.summary(player.steam_id, player_2.steam_id)
+data.players # list of account summeries
+data.success # boolean value indicates if response was succesful
+
+first_player = data.players.first
+first_player['steamid']
+first_player['communityvisibilitystate']
+first_player['profilestate']
+first_player['personaname']
+first_player['lastlogoff']
+first_player['profileurl']
+first_player['avatar']
+first_player['avatarmedium']
+first_player['avatarfull']
+first_player['personastate']
+first_player['realname']
+first_player['primaryclanid']
+first_player['timecreated']
+first_player['personastateflags']
+first_player['gameextrainfo']
+first_player['gameid']
+first_player['loccountrycode']
+first_player['locstatecode']
+first_player['loccityid']
+```
+
+#### Get account summary for single player
+(https://developer.valvesoftware.com/wiki/Steam_Web_API#GetPlayerSummaries_.28v0002.29). This is just more convinient method to get account summary if you already have player instance. To make this API call, you need to have API key for your app and steam identifier of the Steam user.
+
+```ruby
+player = SteamWebApi::Player.new(steam_id)
+data = player.summary
+data.profile # account summery
+data.success # boolean value indicates if response was succesful
+
+data.profile['steamid']
+data.profile['communityvisibilitystate']
+data.profile['profilestate']
+data.profile['personaname']
+data.profile['lastlogoff']
+data.profile['profileurl']
+data.profile['avatar']
+data.profile['avatarmedium']
+data.profile['avatarfull']
+data.profile['personastate']
+data.profile['realname']
+data.profile['primaryclanid']
+data.profile['timecreated']
+data.profile['personastateflags']
+data.profile['gameextrainfo']
+data.profile['gameid']
+data.profile['loccountrycode']
+data.profile['locstatecode']
+data.profile['loccityid']
+```
+
+#### Get player friends list 
+(https://developer.valvesoftware.com/wiki/Steam_Web_API#GetFriendList_.28v0001.29). To make this API call, you need to have API key for your app and steam identifier of the Steam user.
+
+```ruby
+player = SteamWebApi::Player.new(steam_id)
+data = player.friends
+data.friends # list of friends
+data.success # boolean value indicates if response was succesful
+
+friend = data.friends.first
+friend['steamid']
+friend['relationship']
+friend['friend_since'] # integer
+
+# additional options
+# relationship: all/friend. Default is 'all'
+player.friends('friend')
+```
+
+**Get list of recently played games** (https://developer.valvesoftware.com/wiki/Steam_Web_API#GetRecentlyPlayedGames_.28v0001.29). To make this API call, you need to have API key for your app and steam identifier of the Steam user.
+
+```ruby
+player = SteamWebApi::Player.new(steam_id)
+data = player.recently_played_games
+data.games # list of games
+data.total_count
+data.success # boolean value indicates if response was succesful
+
+game = data.games.first
+game['appid']
+game['name']
+game['playtime_2weeks'] # integer, number of minutes
+game['playtime_forever'] # integer, number of minutes
+game['img_icon_url']
+game['img_logo_url']
+
+# additional options
+# count: it limits returned number of games. It's nil by default
+player.recently_played_games(2)
+```
+
+**Check if player is playing shared game** (https://developer.valvesoftware.com/wiki/Steam_Web_API#IsPlayingSharedGame_.28v0001.29). To make this API call, you need to have API key for your app and steam identifier of the Steam user.
+
+```ruby
+player = SteamWebApi::Player.new(steam_id)
+data = player.playing_shared_game(game_id)
+data.lender_steamid # string, steam id of game owner
+data.success  # boolean value indicates if response was succesful
+```
+
+#### Get list of bans for list of players
+(https://developer.valvesoftware.com/wiki/Steam_Web_API#GetPlayerBans_.28v1.29). To make this API call, you need to have API key.
+
+```ruby
+data = SteamWebApi::Player.bans(player_1.steam_id, player_2.steam_id)
+data.players # list of bans info for given players
+data.success # boolean value indicates if response was succesful
+
+bans = data.players.first
+bans['SteamId']
+bans['CommunityBanned'] # boolean
+bans['VACBanned'] # boolean
+bans['NumberOfVACBans'] # integer
+bans['DaysSinceLastBan'] # integer
+bans['EconomyBan'] # string, for example 'none'
+```
+
+#### Get list of bans for single player
+(https://developer.valvesoftware.com/wiki/Steam_Web_API#GetPlayerBans_.28v1.29). This is just more convinient method to get player bans if you already have player instance. To make this API call, you need to have API key.
+
+```ruby
+player = SteamWebApi::Player.new(steam_id)
+data = player.bans
+data.success # boolean value indicates if response was succesful
+data.bans['SteamId']
+data.bans['CommunityBanned'] # boolean
+data.bans['VACBanned'] # boolean
+data.bans['NumberOfVACBans'] # integer
+data.bans['DaysSinceLastBan'] # integer
+data.bans['EconomyBan'] # string, for example 'none'
+```
+
+
+
+### Game
+
+#### Get list of all games 
+This end-point is not described in official documentation.
+
+```ruby
+data = SteamWebApi::Game.all
+data.games
+data.success # boolean value indicates if response was succesful
+
+game = data.games.first
+game['appid'] # game id
+game['name']
+```
+
+#### Get game schema 
+(https://developer.valvesoftware.com/wiki/Steam_Web_API#GetSchemaForGame_.28v2.29). To make this API call, you need to have API key for your app.
+
+```ruby
+game = SteamWebApi::Game(game_id)
+schema = game.schema
+
+schema.name # game name 
+schema.version # game version
+schema.achievements # lists of achievements
+schema.stats # list of stats
+schema.success # boolean value indicates if response was succesful
+
+achievement = schema.achievements.first
+achievement['name']
+achievement['defaultvalue']
+achievement['displayName']
+achievement['hidden'] # integer
+achievement['description']
+achievement['icon']
+achievement['icongray']
+
+stats = schema.stats.first
+stats['name']
+stats['defaultvalue']
+stats['displayName']
+```
+
+#### Get list of global game achievements in percentage
+(https://developer.valvesoftware.com/wiki/Steam_Web_API#GetGlobalAchievementPercentagesForApp_.28v0002.29)
+
+```ruby
+game = SteamWebApi::Game(game_id)
+data = game.achievement_percentages
+
+data.achievements # list of achievements
+data.success # boolean value indicates if response was succesful
+
+achievement = data.achievements.first
+achievement['name']
+achievement['percent']
+```
+
+#### Get list of news
+(https://developer.valvesoftware.com/wiki/Steam_Web_API#GetNewsForApp_.28v0002.29)
+
+```ruby
+game = SteamWebApi::Game(game_id)
+news = game.news
+
+news.app_id # game id
+news.news_items # news list
+news.success # boolean value indicates if response was succesful
+
+first_news = news.news_items.first
+first_news['gid'] # string
+first_news['title']
+first_news['url']
+first_news['is_external_url']
+first_news['author']
+first_news['contents']
+first_news['feedlabel']
+first_news['date']
+first_news['feedname']
+
+# additional options
+# 1. count - default 3, how many news should be retured
+# 2. max_length - default 300, how many characters news content should contain
+data = game.news(count: 10, max_length: 1000)
+```
+
+
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/steam_web_api/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+
+task :console do
+	exec 'irb -r steam_web_api -I ./lib'
+end
+

data/lib/steam_web_api/base.rb

@@ -0,0 +1,39 @@
+require "faraday"
+
+module SteamWebApi
+
+	class Base
+
+		BASE_URI = 'http://api.steampowered.com'
+
+		attr_accessor :response
+
+		class << self
+			
+			def build_response(response, main_key)
+				if response.status == 200
+					parsed_response = JSON.parse(response.body)[main_key]
+					OpenStruct.new yield(parsed_response).merge!(success: true)
+				else
+					OpenStruct.new(success: false)
+				end
+			end
+
+		end
+
+		def get(path, search_params={})
+			Faraday.get("#{BASE_URI}#{path}", search_params.merge!(format: :json))
+		end
+
+		def parse_response
+			JSON.parse(response.body)
+		end
+
+		def build_response(main_key, &block)
+			self.class.build_response(response, main_key, &block)
+		end
+
+	end
+
+	
+end

data/lib/steam_web_api/configuration.rb

@@ -0,0 +1,9 @@
+module SteamWebApi
+
+	class Configuration
+		
+		attr_accessor :api_key
+
+	end
+	
+end

data/lib/steam_web_api/game.rb

@@ -0,0 +1,37 @@
+module SteamWebApi
+
+	class Game < Base
+
+		attr_reader :game_id
+
+		def initialize(game_id)
+			@game_id = game_id	
+		end
+		
+		class << self
+
+			def all
+				response = Faraday.get('http://api.steampowered.com/ISteamApps/GetAppList/v0002/')
+				build_response(response, 'applist') { |data| { games: data['apps'] } }	
+			end
+
+		end
+
+		def schema
+			@response = get('/ISteamUserStats/GetSchemaForGame/v2', appid: game_id, key: SteamWebApi.config.api_key)
+			build_response('game') { |data| { name: data['gameName'], version: data['gameVersion'], achievements: data['availableGameStats']['achievements'], stats: data['availableGameStats']['stats'] } }
+		end
+
+		def achievement_percentages
+			@response = get('/ISteamUserStats/GetGlobalAchievementPercentagesForApp/v0002', gameid: game_id)
+			build_response('achievementpercentages') { |data| { achievements: data['achievements'] } }
+		end
+
+		def news(count: 3, max_length: 300)
+			@response = get('/ISteamNews/GetNewsForApp/v0002', appid: game_id, count: count, maxlength: max_length)
+			build_response('appnews') { |data|{ app_id: data['appid'], news_items: data['newsitems'] } }
+		end
+
+	end
+	
+end

data/lib/steam_web_api/player.rb

@@ -0,0 +1,108 @@
+module SteamWebApi
+
+	class Player < Base
+
+		attr_accessor :steam_id
+
+		def initialize(steam_id)
+			@steam_id = steam_id
+		end
+
+		class << self
+
+			def summary(*ids)
+				response = Faraday.get('http://api.steampowered.com/ISteamUser/GetPlayerSummaries/v0002', options(ids))
+				build_response(response, 'response') { |data| { players: data['players'] } }
+			end
+
+			def bans(*ids)
+				response = Faraday.get('http://api.steampowered.com/ISteamUser/GetPlayerBans/v1', options(ids))
+				build_response(response, 'players') { |data| { players: data } }
+			end
+
+			private
+
+			def options(*ids)
+				{ key: SteamWebApi.config.api_key, steamids: ids.join(',') }
+			end
+
+		end
+
+		def owned_games(options={})
+			@response = get('/IPlayerService/GetOwnedGames/v0001', owned_games_options(options))
+			build_response('response') { |data| { count: data['game_count'], games: data['games'] } }
+		end
+
+		def stats_for_game(app_id)
+			@response = get('/ISteamUserStats/GetUserStatsForGame/v0002', stats_for_game_options(app_id))
+			build_response('playerstats') { |data| { steam_id: data['steamID'], game_name: data['gameName'], achievements: data['achievements'], stats: data['stats'] } }
+		end
+
+		def achievements(app_id, options={})
+			@response = get('/ISteamUserStats/GetPlayerAchievements/v0001', achievements_options(app_id, options))
+			build_response('playerstats') { |data| { steam_id: data['steamID'], game_name: data['gameName'], achievements: data['achievements'] } }
+		end
+
+		def summary
+			data = self.class.summary(steam_id)
+			get_first_data(data) { |data| { profile: data.players.first } }
+		end
+
+		def friends(relationship='all')
+			@response = get('/ISteamUser/GetFriendList/v0001', friends_list_options(relationship))
+			build_response('friendslist') { |data| { friends: data['friends'] } }
+		end
+
+		def recently_played_games(count=nil)
+			@response = get('/IPlayerService/GetRecentlyPlayedGames/v0001', recent_games_options(count))
+			build_response('response') { |data| { games: data['games'], total_count: data['total_count'] } }
+		end
+
+		def playing_shared_game(app_id)
+			@response = get('/IPlayerService/IsPlayingSharedGame/v0001', shared_game_options(app_id))
+			build_response('response') { |data| { lender_steamid: data['lender_steamid'] } }
+		end
+
+		def bans
+			data = self.class.bans(steam_id)
+			get_first_data(data) { |data| { bans: data.players.first } }
+		end
+
+		private
+
+		def get_first_data(data)
+			if data.success && data.players.size > 0
+				OpenStruct.new yield(data).merge!(success: true)
+			else
+				OpenStruct.new(success: false)
+			end
+		end
+
+		def owned_games_options(options)
+			options.each { |k, v| options[k] = v ? 1 : 0 }
+			{ key: SteamWebApi.config.api_key, steamid: steam_id }.merge!(options)
+		end
+
+		def stats_for_game_options(game_id)
+			{ appid: game_id, key: SteamWebApi.config.api_key, steamid: steam_id }
+		end
+
+		def achievements_options(game_id, options)
+			{ appid: game_id, key: SteamWebApi.config.api_key, steamid: steam_id }.merge!(options)
+		end
+
+		def friends_list_options(relationship)
+			{ key: SteamWebApi.config.api_key, steamid: steam_id, relationship: relationship }
+		end
+
+		def recent_games_options(count)
+			{ key: SteamWebApi.config.api_key, steamid: steam_id, count: count }	
+		end
+
+		def shared_game_options(app_id)
+			{ key: SteamWebApi.config.api_key, steamid: steam_id, appid_playing: app_id }
+		end
+		
+	end
+	
+end

data/lib/steam_web_api/version.rb

@@ -0,0 +1,3 @@
+module SteamWebApi
+  VERSION = "0.0.1"
+end

data/lib/steam_web_api.rb

@@ -0,0 +1,29 @@
+require "json"
+require "steam_web_api/version"
+require "steam_web_api/configuration"
+require "steam_web_api/base"
+require "steam_web_api/player"
+require "steam_web_api/game"
+
+begin
+	require "byebug"
+rescue LoadError
+end
+
+module SteamWebApi
+  
+	class << self
+
+		attr_writer :config
+
+		def config
+			@configuration ||= SteamWebApi::Configuration.new
+		end
+
+		def configure
+			yield config
+		end
+
+	end
+
+end