backpack_tf 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a80c2c34c6cd7c6ec419533195231f742faeb5f7
-  data.tar.gz: d434f3c196f776d1836072733f3422a9a4cfcf1e
+  metadata.gz: 5b3f89b16c6ef3907403d7a9caab7457e740bd02
+  data.tar.gz: e41e8dbf4ba4bc3db93a40197cac519e22d3b106
 SHA512:
-  metadata.gz: 5b9cf050101bec789981bdd69a88f14f828e98ec0e9e2a1c132d7c924c87ee265a8505d664ff9b777f7ecf1c5e199095c2cf922ed25b5b4db24b5e4b5d0d0ea6
-  data.tar.gz: 2cdf8ad385ebeaf324de8add2ce3456b35719879dd55aaa27a016b2f5ed7d443e3f88287a94719e106cb5221332d1123b141c1f95c4a8d5697144b5e378a19a1
+  metadata.gz: 29b1583190c592fcba721473e9800d1b9ed2d7b80a2d841917469513ef9db6e73a66ae3ac6c1e044718024f6e04f2192b1440d6da26234075c3a4deff332566e
+  data.tar.gz: 83f26e2dafd51d449cf205d6244a0575afe9e882a017dec8b8e86b88fb7ab30257c2d40d2ed6d983995c00fc63683ba7409eec4b0ea20f4a10527c966822cb39

data/.gitignore

@@ -0,0 +1,10 @@
+*.sw*
+*dump.rdb
+
+*.gem
+Gemfile.lock
+
+spec/fixtures/*yml
+spec/other-library-examples
+
+scratch/

data/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+gem 'httparty'
+
+group :test do
+  gem 'rspec'
+  gem 'webmock'
+end

data/Gemfile.lock

@@ -0,0 +1,41 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.3.8)
+    crack (0.4.2)
+      safe_yaml (~> 1.0.0)
+    diff-lcs (1.2.5)
+    httparty (0.13.3)
+      json (~> 1.8)
+      multi_xml (>= 0.5.2)
+    json (1.8.2)
+    multi_xml (0.5.5)
+    redis (3.2.1)
+    rspec (3.2.0)
+      rspec-core (~> 3.2.0)
+      rspec-expectations (~> 3.2.0)
+      rspec-mocks (~> 3.2.0)
+    rspec-core (3.2.3)
+      rspec-support (~> 3.2.0)
+    rspec-expectations (3.2.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.2.0)
+    rspec-mocks (3.2.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.2.0)
+    rspec-support (3.2.2)
+    safe_yaml (1.0.4)
+    vcr (2.9.3)
+    webmock (1.21.0)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  httparty
+  redis
+  rspec
+  vcr
+  webmock

data/TODO.md

@@ -0,0 +1,15 @@
+##TODO list
+
+#####testing:
+* a mock backpack.tf service
+* stubs & archived cache data
+
+#####documentation:
+* better documentation on all classes, modules, methods, attributes, etc
+* support for YARD or RDOC
+
+#####caching:
+* options to cache data and force a refresh
+
+#####formats:
+* the API outputs 3 formats: JSON (default), JSONP and VDF. Currently, the gem supports JSON input only. Support for JSONP & VDF is needed.

data/backpack_tf.gemspec

@@ -0,0 +1,19 @@
+Gem::Specification.new do |s|
+  s.name          = 'backpack_tf'
+  s.version       = '0.2.1'
+  s.date          = '2015-05-01'
+  s.summary       = 'a wrapper for the backpack.tf API'
+  s.author        = 'Rafael Espinoza'
+  s.email         = 'rafael@rafaelespinoza.com'
+  s.homepage      = 'https://github.com/NerdDiffer/backpack_tf'
+  s.license       = 'MIT'
+  s.description   = s.summary
+
+  s.require_paths = ['lib']
+  s.files         = `git ls-files`.split("\n")
+
+  s.add_runtime_dependency 'httparty',    '~>0.13',   '>=0.13.3'
+
+  s.add_development_dependency 'rspec',   '~>3.2',    '>=3.2.0'
+  s.add_development_dependency 'webmock', '~>1.21',   '>=1.21.0'
+end

data/lib/backpack_tf/client.rb

@@ -0,0 +1,102 @@
+module BackpackTF
+
+  class Client
+
+    include HTTParty
+  
+    ###########################
+    #     Class Methods
+    ###########################
+
+    # store your API key as an environment variable
+    # `export <env_var>='<your api key>'`
+    @@env_var = 'BPTF_API_KEY'
+    def self.env_var; @@env_var; end
+  
+    def self.api_key key = nil
+      default = key || ENV[@@env_var]
+  
+      if default.nil?
+        msg = "Assign your API key to an environment variable.\n"
+        msg << "ex: `export #{@@env_var}=value`"
+        raise KeyError, msg
+      elsif default.class == String && (default.length != 24 || !!default[/\H/])
+        msg = "The key should be a hexadecimal number, 24-digits long"
+        raise ArgumentError, msg
+      else
+        default
+      end
+    end
+  
+    base_uri 'http://backpack.tf/api'
+    default_timeout 5
+    default_params(:key => api_key)
+  
+    def self.build_url_via action, query_options = {}
+      case action
+      when :get_prices
+        version = 4
+        interface_url = "/#{Prices.interface}/v#{version}/?"
+      when :get_currencies
+        version = 1
+        interface_url = "/#{Currencies.interface}/v#{version}/?"
+      when :get_special_items
+        version = 1
+        interface_url = "/IGetSpecialItems/v#{version}/?"
+      when :get_users
+        version = 3
+        interface_url = "/IGetUsers/v#{version}/?"
+      when :get_user_listings
+        version = 1
+        interface_url = "/IGetUserListings/v#{version}/?"
+      else
+        raise ArgumentError, 'pass in valid action as a Symbol object'
+      end
+  
+      base_uri + interface_url + extract_query_string(query_options)
+    end
+
+    def self.extract_query_string options = {}
+      options.each_pair.map do |key, val|
+        unless val.class == Array
+          "#{key}=#{val}"
+        else
+          "#{key}=#{val.join(',')}"
+        end
+      end.join('&')
+    end
+
+    ###########################
+    #     Instance Methods
+    ###########################
+    attr_reader :db
+  
+    def initialize
+      @db = nil 
+    end
+  
+    def get_data action, query_options = {}
+      handle_timeouts do
+        url = self.class.build_url_via(action, query_options)
+        self.class.get(url)#['response']
+      end
+    end
+  
+    private
+  
+    # HTTParty raises an errors after time limit defined by ::default_timeout
+    # * if it cannot connect to server, then it raises Net::OpenTimeout
+    # * if it cannot read response from server, then it raises Net::ReadTimeout
+    # if one of those happen, then an empty hash is returned
+    def handle_timeouts
+      begin
+        yield
+      rescue Net::OpenTimeout, Net::ReadTimeout
+        {}
+      end
+    end
+  
+
+  end
+
+end

data/lib/backpack_tf/currencies.rb

@@ -0,0 +1,62 @@
+module BackpackTF
+
+  # ruby representations of a JSON response to
+  # `IGetCurrencies`['response']
+  class Currencies
+
+    ###########################
+    #     Class Methods
+    ###########################
+
+    include BackpackTF::Response
+
+    @interface = :IGetCurrencies
+
+    def self.currencies
+      @@currencies = hash_keys_to_sym(@response[:currencies])
+    end
+
+    ###########################
+    #     Instance Methods
+    ###########################
+
+    # @return [Fixnum] the quality index of the currency
+    attr_reader :quality
+    # @return [Fixnum] the internal priceindex of the currency
+    attr_reader :priceindex
+    # @return [String] the single form of noun that is used in the suffix
+    attr_reader :single
+    # @return [String] the plural form of noun that is used in the suffix
+    attr_reader :plural
+    # @return [Fixnum] the number of decimal places the price should be rounded to
+    attr_reader :round
+    # @return [Symbol] either :Craftable or :Non-Craftable to signify currency's craftability
+    attr_reader :craftable
+    # @return [Symbol] either :Tradable or :Non-Tradable to signify currency's tradability
+    attr_reader :tradable
+    # @return [Fixnum] the definition index of the currency
+    attr_reader :defindex
+    # TODO: what does the :blanket attribute mean?
+    # it is set to 0 by default. However, it is set to 1 for :hat.
+    # :hat also has an extra property & value :blanket_name => 'Random Craft Hat'
+    # @return [Fixnum] 
+    attr_reader :blanket
+
+    def initialize name, attr
+      attr = check_attr_keys(attr)
+
+      @name       = name.to_s
+      @quality    = attr[:quality]
+      @priceindex = attr[:priceindex]
+      @single     = attr[:single]
+      @plural     = attr[:plural]
+      @round      = attr[:round]
+      @craftable  = attr[:craftable].to_sym
+      @tradable   = attr[:tradable].to_sym
+      @defindex   = attr[:defindex]
+      @blanket    = attr[:blanket]
+    end
+
+  end
+
+end

data/lib/backpack_tf/item.rb

@@ -0,0 +1,19 @@
+module BackpackTF
+
+  class Item
+
+    # @return [String] the name of item
+    attr_reader :item_name
+    # @return [Fixnum] the index on which you can link this item to Team Fortress 2's Item Schema
+    attr_reader :defindex
+    # @return [Hash<Fixnum, ItemPrice>] a hash object
+    attr_reader :prices
+
+    def initialize item_name, attr
+      @item_name = item_name
+      @defindex = attr['defindex'][0]
+      @prices = nil
+    end
+
+  end
+end

data/lib/backpack_tf/item_price.rb

@@ -0,0 +1,63 @@
+module BackpackTF
+
+  class ItemPrice
+
+    attr_reader :quality, :tradability, :craftability, :priceindex,
+      :currency, :value, :value_high, :value_raw, :value_high_raw,
+      :last_update, :difference
+
+    def initialize
+    end
+
+    # mapping official API quality integers to quality names
+    # https://wiki.teamfortress.com/wiki/WebAPI/GetSchema#Result_Data
+    @@qualities = [
+      'Normal',
+      'Genuine',
+      nil,
+      'Vintage',
+      nil,
+      'Unusual',
+      'Unique',
+      'Community',
+      'Valve',
+      'Self-Made',
+      nil,
+      'Strange',
+      nil,
+      'Haunted',
+      "Collector's"
+    ]
+
+    @@tradabilities = [:Tradable, :Untradable]
+    @@craftabilities = [:Craftable, :Uncraftable]
+    
+    # returns JSON data for the item
+    # does not return data for items with a special particle effect
+    def self.get_item_price quality, item_name
+      item = find_item_by_name(item_name)
+      ind = @@qualities.find_index(quality)
+
+      prefix = item['prices'][ind.to_s]['Tradable']
+      if prefix.nil?
+        raise(ArgumentError, "The item, #{quality} #{item_name}, is not Tradable")
+      end
+      prefix = prefix['Craftable']
+      if prefix.nil?
+        raise(ArgumentError, "The item, #{quality} #{item_name}, is not Craftable")
+      end
+
+      # oddly, there are cases (such as the "Lugermorph"), where the 
+      # type of the object at this point in the JSON data (saved to the `prefix` variable) 
+      # is a Hash object rather than an Array object.
+      # That makes the PriceIndex key a String, "0", rather than a Fixnum, 0.
+      if prefix[0].nil?
+        prefix[0.to_s] 
+      else
+        prefix[0]
+      end
+    end
+
+  end
+
+end

data/lib/backpack_tf/prices.rb

@@ -0,0 +1,70 @@
+module BackpackTF
+
+  # ruby representations of a JSON response to
+  # `IGetPrices`['response']
+  class Prices
+
+    include BackpackTF::Response
+
+    @interface = :IGetPrices
+
+    def self.items
+      @@items = @response[:items]
+    end
+
+    def self.defindex_to_item_name defindex
+      items = get_items_hash
+      keys = items.keys#.shuffle
+
+      i = 0
+      while i < keys.length
+        current_defindex = items[keys[i]]['defindex']
+        if(current_defindex[0] == defindex)
+          return keys[i]
+        end
+        i += 1
+      end
+      raise KeyError, "item with a defindex of #{defindex} was not found"
+    end
+
+    def self.get_name_of_random_item
+      items = get_items_hash
+      items.keys.sample
+    end
+
+    # returns JSON representation of pricing for the item
+    def self.find_item_by_name item_name
+      items = get_items_hash
+      if items[item_name].nil?
+        raise KeyError, "item with the name #{item_name} was not found"
+      else
+        items[item_name]
+      end
+    end
+
+    # @param [String] item_name, the item name (according to item_name of item's schema)
+    # @param [Symbol] type, checking to see if item is of this type
+    # @return [Boolean] `true` if the item is the type
+    def self.is_item_of_type? item_name, type = :weapon
+      item = find_item_by_name(item_name)
+      defindex = item['defindex'][0]
+      tf2_item = Trade.tf2_item_schema.items[defindex]
+
+      case type
+      when :cosmetic
+        tf2_item[:item_class] == 'tf_wearable'
+      else
+        tf2_item[:item_slot] == 'primary' ||
+          tf2_item[:item_slot] == 'secondary' ||
+          tf2_item[:item_slot] == 'melee'
+      end
+    end
+
+    def initialize
+      msg = "This class is meant to receive the JSON response from the #{self.class.interface} interface. It holds a Hash array of prices of items, but not is meant to be instantiated. See the Item class if you are interested in an item. However, information on items should be stored in the @items property of #{self.class}"
+      raise RuntimeError, msg
+    end
+
+  end
+
+end

data/lib/backpack_tf/response.rb

@@ -0,0 +1,59 @@
+module BackpackTF
+  module Response
+
+    def self.included(other)
+      puts "#{self} included in (#{other})"
+      other.extend(ClassMethods)
+      super
+    end
+
+    module ClassMethods
+
+      @response = nil
+      def interface; @interface; end
+
+      def response force_update = false
+        # if force is true, set value of @response to results of ::fetch
+        # otherwise, use a `nil guard` to return @response
+        #   if the value is already set, then it returns value of @response
+        #   if the value is not set, then it runs ::fetch
+        force_update ?
+          @response = fetch :
+          @response ||= fetch
+      end
+
+      def fetch client_stuff
+        @response = hash_keys_to_sym(client_stuff)
+      end
+
+      # checks the data type of the keys of a Hash object
+      # if the key is a String, then changes it to a Symbol
+      # otherwise, leaves it as is
+      def hash_keys_to_sym hash
+        hash.each_pair.inject({}) do |new_hash, (key, val)|
+          unless key.class == String
+            new_hash[key] = val
+          else
+            new_hash[key.to_sym] = val
+          end
+          new_hash
+        end
+      end
+    end
+
+    ############################
+    # PRIVATE INSTANCE METHODS
+    ############################
+    private
+    def check_attr_keys attr
+      raise TypeError, 'pass in a Hash object' unless attr.class == Hash 
+
+      unless attr.keys.all? { |k| k.class == String }
+        raise TypeError, 'all keys must be String object'
+      end
+
+      self.class.hash_keys_to_sym(attr)
+    end
+
+  end
+end

data/lib/backpack_tf.rb

@@ -0,0 +1,15 @@
+require 'httparty'
+require 'byebug'
+
+# namespace for classes & modules inside of the wrapper for the BackpackTF API
+module BackpackTF
+
+end
+
+# IMPORTANT! require the Response module before any other class or module
+require 'backpack_tf/response'
+require 'backpack_tf/client'
+require 'backpack_tf/currencies'
+require 'backpack_tf/item'
+require 'backpack_tf/item_price'
+require 'backpack_tf/prices'

data/readme.md

@@ -0,0 +1,56 @@
+#backpack_tf
+Backpack.tf is a website for the in-game economies of Team Fortress 2 and Dota 2. This gem is a wrapper for the backpack.tf [API](http://backpack.tf/api). The goal is to capture the results and turn them into Ruby objects for use in your application.
+
+It is in the very early stages of development. See the [TODO](TODO.md) list if you are interested in contributing.
+
+###Installation
+Install it as a gem:  
+`gem install backpack_tf`  
+
+Or add it to your project's Gemfile:  
+`gem 'backpack_tf'`
+
+###Usage
+* [Register an API key](http://backpack.tf/api). You'll need to log in with your Steam account if you haven't already done so.  
+* Assign your key to an environment variable through your terminal:  
+  `export BPTF_API_KEY='SECRET_KEY'`
+* Load the gem into your project:  
+  `require 'backpack_tf'`
+
+##Interfaces
+
+####IGetPrices
+* Get pricing data for all priced items
+* [official doc](http://backpack.tf/api/prices)
+
+API responses from this interfaces are captured in the `Prices` class. The `Prices` class is not meant to be instantiated. One of the class attributes is `@@items`, a Hash object. Information on any particular item, ie: 'Kritzkrieg', is captured in an instance of the `Item` class. Furthermore, there may be several prices for the same item, ie: a Kritzkrieg with the Unique quality has a different price than a Kritzkrieg with a Vintage quality.  Each price is an instance of the `ItemPrice` class, and is stored in the `@prices` hash of that item.
+
+######a visual
+* `Prices` class
+  * `@@items` hash of `Price` class.
+    * `Item` object (ie: 'Beast From Below')
+    * `Item` object (ie: 'Taunt: Rock, Paper Scissors')
+    * `Item` object (ie: 'Kritzkrieg')
+      * `@prices` hash of an `Item` object
+        * `ItemPrices` object (ie: price for Unique Kritzkrieg)
+        * `ItemPrices` object (ie: price for Collector's Kritzkrieg)
+        * `ItemPrices` object (ie: price for Vintage Kritzkrieg)
+
+####IGetCurrencies
+* Get internal currency data for a given game
+* [official doc](http://backpack.tf/api/currencies)
+
+API responses from this interface are captured in the `Currencies` class. Similar the `Prices` class, it has a set of class methods, and attributes to describe the API response. Unlike, the `Prices` class, this one can be instantiated. There are currently 4 currencies available through the API. Each one is an instance of `Currencies` and is held in the `@@currencies` hash of the `Currencies` class.
+
+####IGetSpecialItems *(not yet implemented)*
+* Get internal backpack.tf item placeholders for a given game.
+* [official doc](http://backpack.tf/api/special)
+
+####IGetUsers *(not yet implemented)*
+* Get profile info for a list of 64-bit Steam IDs.
+* Does not require an API key
+* [official doc](http://backpack.tf/api/users)
+
+####IGetUserListings *(not yet implemented)*
+  * Get classified listings for a given user
+  * [official doc](http://backpack.tf/api/classifieds)

data/spec/backpack_tf/client_spec.rb

@@ -0,0 +1,75 @@
+require 'spec_helper'
+
+module BackpackTF
+  describe 'Client' do
+    context 'The Client class' do
+  
+      it 'has these default options' do
+        ans = { base_uri: 'http://backpack.tf/api', timeout: 5 }
+        ans[:default_params] = { key: ENV[Client.env_var] }
+        expect(Client.default_options).to eq ans
+      end
+
+      describe '::api_key' do
+        it 'Raises ArgumentError, if key is not a hexadecimal string' do
+          fake_key = 'abcdefghijklmnopqrstuvwx'
+          expect{Client.api_key(fake_key)}.to raise_error ArgumentError
+        end
+        it 'Raises ArgumentError, if key is not 24 digits long' do
+          fake_key = 'abcdef0987654321'
+          expect{Client.api_key(fake_key)}.to raise_error ArgumentError
+        end
+        it 'lets an otherwise theoretically-valid key, pass through' do
+          key = generate_fake_api_key
+          expect(Client.api_key(key)).to eq key
+        end
+      end
+
+      describe '::extract_query_string' do
+        it 'produces a query parameter string' do
+          opts = {:key => Client.api_key, :appid => 440, :format => 'json', :compress => 1, :raw => 2}
+          ans = "key=#{Client.api_key}&appid=440&format=json&compress=1&raw=2"
+          expect(Client.extract_query_string(opts)).to eq ans
+        end
+      end
+
+      describe '::build_url_via' do
+        it 'returns correct destination url when asking for pricing data' do
+          opts = {:key => Client.api_key, :compress => 1}
+          expect(Client.build_url_via(:get_prices, opts)).to eq "http://backpack.tf/api/IGetPrices/v4/?key=#{Client.api_key}&compress=1"
+        end
+        it 'raises an error when asking for any unexpected interface' do
+          expect{Client.build_url_via(:foo)}.to raise_error ArgumentError
+        end
+      end  
+    end
+  
+    context 'Instances of Client' do
+      let(:bp) { Client.new }
+
+      describe '#get_data' do
+
+        it 'returns results from archived json file' do
+          stub_http_response_with('currencies.json')
+          opts = { :key => Client.api_key, :compress => 1, :appid => 440 }
+          currencies = bp.get_data(:get_currencies, opts)
+
+          expect(currencies['response']).to have_key('success')
+          expect(currencies['response']).to have_key('currencies')
+          expect(currencies['response']).to have_key('name')
+          expect(currencies['response']).to have_key('url')
+          expect(currencies['response']).to have_key('current_time')
+        end
+
+        it 'client requests are returned as ruby Hash objects' do
+          stub_http_response_with('prices.json')
+          opts = {:app_id => 440, :compress => 1}
+          expect(bp.get_data(:get_prices, opts)).to be_instance_of Hash
+        end
+
+      end
+
+
+    end
+  end
+end