backpack_tf 0.8.4 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a510923d8b4dc15e3532952f92bed00000910548
-  data.tar.gz: df6eb944365d8ebe1d718e7154a8fd0842b6719e
+  metadata.gz: 8673b991331c19d4f53c025859bce0ea112838c5
+  data.tar.gz: 34d35fa2c340a9e239c9525ff26e19768068dd41
 SHA512:
-  metadata.gz: 0c2fe92ebc9568cefdb9603a7a432c6e7fc43c1d7569d495af673830ac0e89fd581724cc85b0588420ed45f641bec9047a3db7fbc60f4093536f1e60bf04cabe
-  data.tar.gz: 5b1dad54cfb43f40b3b81a543b3674046ed70286dd1ea90c19649bb33682c1e3227d838db63335b29ac8d21a34464d8dd8fa4167e59ed1b1348b7936a38494df
+  metadata.gz: 12b37a2bf1e298ae661e00faa9f342be27f8e76dde8a853b767801e7b1c650eb45648fbe9de0c2d34246573ae8921500a90266bdcb2f6b3b8d49382b9cb01eae
+  data.tar.gz: 08bef1bcf70c9a98bd17f0bdcd23a3c1917816bdd297699b882e7d4d9d5e83160c7d8b6fb9372226eb8f775dedca208faecaba4fa13fde9c92d9bcea408c2b83

data/.gitignore

@@ -3,9 +3,7 @@
 
 .ruby-version
 *.gem
-Gemfile.lock
 
+coverage/
 spec/fixtures/*yml
 spec/other-library-examples
-
-scratch/

data/.rspec

@@ -0,0 +1,2 @@
+--order=random
+--no-fail-fast

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+ - "2.2.3"

data/Gemfile

@@ -1,8 +1,10 @@
 source 'https://rubygems.org'
 
-gem 'httparty'
+gem 'httparty', '~> 0.13.5'
 
 group :test do
-  gem 'rspec'
-  gem 'webmock'
+  gem 'rspec', '~> 3.3.0'
+  gem 'webmock', '~> 1.21.0'
+  gem 'simplecov', '~> 0.11.1', require: false
+  gem 'rake', '~> 10.4.2', require: false
 end

data/Gemfile.lock

@@ -0,0 +1,49 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.3.8)
+    crack (0.4.2)
+      safe_yaml (~> 1.0.0)
+    diff-lcs (1.2.5)
+    docile (1.1.5)
+    httparty (0.13.5)
+      json (~> 1.8)
+      multi_xml (>= 0.5.2)
+    json (1.8.3)
+    multi_xml (0.5.5)
+    rake (10.4.2)
+    rspec (3.3.0)
+      rspec-core (~> 3.3.0)
+      rspec-expectations (~> 3.3.0)
+      rspec-mocks (~> 3.3.0)
+    rspec-core (3.3.2)
+      rspec-support (~> 3.3.0)
+    rspec-expectations (3.3.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.3.0)
+    rspec-mocks (3.3.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.3.0)
+    rspec-support (3.3.0)
+    safe_yaml (1.0.4)
+    simplecov (0.11.1)
+      docile (~> 1.1.0)
+      json (~> 1.8)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.0)
+    webmock (1.21.0)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  httparty (~> 0.13.5)
+  rake (~> 10.4.2)
+  rspec (~> 3.3.0)
+  simplecov (~> 0.11.1)
+  webmock (~> 1.21.0)
+
+BUNDLED WITH
+   1.10.6

data/README.md

@@ -0,0 +1,144 @@
+# backpack_tf
+
+[![Build Status](https://travis-ci.org/NerdDiffer/backpack_tf.svg?branch=master)](https://travis-ci.org/NerdDiffer/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.
+
+### Contributing
+
+If you are interested in contributing, please see any open
+[issues](https://github.com/NerdDiffer/backpack_tf/issues), let me know, and
+branch off of the `development` branch.
+
+### Installation
+
+###### from the command line
+
+`$ gem install backpack_tf`
+
+###### from your Gemfile
+
+`gem 'backpack_tf'`
+
+### Usage & Examples
+
+[Register an API key](http://backpack.tf/developer), pass it in to the client.
+
+``` ruby
+#
+# create a new Client object
+#
+bp = BackpackTF::Client.new(<your_api_key>)
+
+#
+# fetch some data
+#
+prices = bp.fetch(:prices)
+price_history = bp.fetch(:price_history, { item: item_name_or_defindex })
+market_prices = bp.fetch(:market_prices)
+currencies = bp.fetch(:currencies)
+special_items = bp.fetch(:special_items)
+users = bp.fetch(:users, { steamids: [array,of,64,bit,steam,ids] })
+listings = bp.fetch(:user_listings, { steamid: 64_bit_steam_id })
+
+#
+# assign fetched data to the corresponding module
+#
+BackpackTF::Price.response = prices
+BackpackTF::PriceHistory.response = price_history
+BackpackTF::MarketPrices.response = market_prices
+BackpackTF::Currency.response = currencies
+BackpackTF::SpecialItem.response = special_items
+BackpackTF::User.response = users
+BackpackTF::UserListing.response = listings
+```
+
+## Interfaces & Responses
+
+#### IGetPrices
+
+* Get pricing data for all priced items
+* [official doc](http://backpack.tf/api/prices)
+
+Information on any particular item, (ie: 'Eviction Notice'), is captured in an
+instance of `BackpackTF::Price::Item`. Furthermore, there may be several prices
+for the same item. For example, an Eviction Notice with the Unique quality has a
+different price than an Eviction Notice with the Strange quality.
+
+Each price is an instance of `BackpackTF::Price::ItemPrice`, and is stored in
+the `@prices` hash of that item.
+
+##### A visual representation of this hierarchy
+
+* `BackpackTF::Price` module
+  * `@items` hash of `BackpackTF::Price::Response`.
+    * `BackpackTF::Price::Item` object (ie: 'Beast From Below')
+    * `BackpackTF::Price::Item` object (ie: 'Taunt: Rock, Paper Scissors')
+    * `BackpackTF::Price::Item` object (ie: 'Eviction Notice')
+      * `@prices` hash of a `BackpackTF::Price::Item` object
+        * `BackpackTF::Price::ItemPrice` object (ie: price of a Unique item)
+        * `BackpackTF::Price::ItemPrice` object (ie: price of a Vintage item)
+        * `BackpackTF::Price::ItemPrice` object (ie: price of a Strange item)
+
+#### IGetPriceHistory
+
+* Get price history for an item
+* [official doc](http://backpack.tf/api/pricehistory)
+
+You must pass in the item name or its `defindex` number as value on the `name`
+key when accessing this interface. IE:
+
+* `client.fetch(:price_history, item: 829)` or
+* `client.fetch(:price_history, item: 'War Pig')`
+
+If you pass in a string as the `item`, then it must match the `item_name`
+property (not the `name` property) as per its definition in the schema. For more
+information, see the
+[TF2 Wiki page on item schema](https://wiki.teamfortress.com/wiki/Item_schema).
+
+You can optionally pass the client `quality`, `tradable`, `craftable` or
+`priceindex` keys. See the
+[official doc](http://backpack.tf/api/pricehistory) for more info.
+
+#### IGetMarketPrices
+
+* Get Steam Community Market price information
+* [official doc](http://backpack.tf/api/market)
+
+#### IGetCurrencies
+
+* Get internal currency data
+* [official doc](http://backpack.tf/api/currencies)
+
+There are currently 4 currencies available through the API.
+Each one is an instance of `BackpackTF::Currency` and is held in the
+`@currencies` hash of the `BackpackTF::Currency::Response` class.
+
+#### IGetSpecialItems
+
+* Get internal backpack.tf item placeholders
+* [official doc](http://backpack.tf/api/special)
+
+This is for items that only exist on backpack.tf. They are not real game items,
+but you will see them returned in a call to `IGetSpecialItems`.
+
+#### IGetUsers
+
+* Get profile info for a list of 64-bit Steam IDs.
+* Does not require an API key
+* [official doc](http://backpack.tf/api/users)
+
+Get some basic information for a list of backpack.tf users. It's basically the
+info that you'd see on their profile page.
+You can request several users at once by sending an array.
+
+#### IGetUserListings
+
+* Get classified listings for a given user
+* [official doc](http://backpack.tf/api/classifieds)
+
+Request all classified listings for one user.
+You must pass in the 64-bit `steamid`.

data/Rakefile

@@ -0,0 +1,7 @@
+begin
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new(:spec)
+  task :default => :spec
+rescue LoadError
+  puts 'no rspec available!'
+end

data/backpack_tf.gemspec

@@ -2,7 +2,7 @@ require_relative './lib/backpack_tf/version.rb'
 
 Gem::Specification.new do |s|
   s.name          = 'backpack_tf'
-  s.date          = '2015-08-09'
+  s.date          = '2016-02-06'
   s.summary       = 'a wrapper for the backpack.tf API'
   s.author        = 'Rafael Espinoza'
   s.email         = 'rafael@rafaelespinoza.com'
@@ -13,7 +13,7 @@ Gem::Specification.new do |s|
   s.require_paths = ['lib']
   s.files         = `git ls-files`.split("\n")
   s.version       = BackpackTF::VERSION
-  s.required_ruby_version = '>=1.9.3'
+  s.required_ruby_version = '>= 2.0.0'
 
   s.add_runtime_dependency 'httparty',    '~>0.13.5'
 

data/lib/backpack_tf/client.rb

@@ -1,118 +1,95 @@
 module BackpackTF
-
+  # Access all BackpackTF APIs through here
   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, :prices, :price
-        version = 4
-        interface_url = "/#{Price.interface}/v#{version}/?"
-      when :get_currencies, :currencies, :currency
-        version = 1
-        interface_url = "/#{Currency.interface}/v#{version}/?"
-      when :get_special_items, :special_items, :special_item, :specialitem
-        version = 1
-        interface_url = "/#{SpecialItem.interface}/v#{version}/?"
-      when :get_users, :users, :user
-        version = 3
-        interface_url = "/#{User.interface}/v#{version}/?"
-      when :get_user_listings, :user_listings, :user_listing, :userlisting
-        version = 1
-        interface_url = "/#{UserListing.interface}/v#{version}/?"
-      else
-        raise ArgumentError, 'pass in valid action as a Symbol object'
-      end
-  
-      base_uri + interface_url + extract_query_string(query_options)
+    # @param key [String] Your backpack.tf API key
+    # @return [Client] a new Client object
+    def initialize(key)
+      @key = check_key(key)
+      httparty_settings
     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 fetch interface, query_options = {}
+    # @param interface [Symbol] API name to fetch, in singular, snake-case.
+    #   For example:
+    #   `:currencies`, `:market_prices`, `:prices`, `:price_history`,
+    #   `:special_items`, `:users`, `:user_listings`
+    # @param query_options [Hash] Additional query string key-value pairs
+    # @return [Hash] Parsed JSON response from an API, starting from the
+    #   'response' key.
+    def fetch(interface, query_options = {})
       get_data(interface, query_options)['response']
     end
 
-    def update class_to_update, data_to_update
-      send_update_to_master_hash(class_to_update, data_to_update)
-      refresh_class_hash(class_to_update)
-    end
-  
     private
-  
-    def send_update_to_master_hash class_to_update, data_to_update
-      Response.responses( { class_to_update.to_sym => data_to_update } )
-    end
-
-    def refresh_class_hash class_to_update
-      class_to_update.response
-    end
 
-    def get_data action, query_options = {}
+    def get_data(action, query_options = {})
       handle_timeouts do
-        url = self.class.build_url_via(action, query_options)
+        url = build_url_via(action, query_options)
         self.class.get(url)
       end
     end
 
     # 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
+    # - if it cannot connect to server, then it raises Net::OpenTimeout
+    # - if it cannot read response from server, then it raises Net::ReadTimeout
     def handle_timeouts
-      begin
-        yield
-      rescue Net::OpenTimeout, Net::ReadTimeout
-        {}
+      yield
+    rescue Net::OpenTimeout, Net::ReadTimeout
+      {}
+    end
+
+    def httparty_settings
+      self.class.base_uri('http://backpack.tf/api')
+      self.class.default_timeout(5)
+      self.class.default_params(key: @key)
+    end
+
+    def check_key(key = nil)
+      # This should not matter when running tests.
+      warn('--- WARNING: your key is nil ---') if key.nil?
+
+      if key.class == String && (key.length != 24 || key[/\H/])
+        msg = 'The key should be a hexadecimal number, 24-digits long'
+        fail ArgumentError, msg
+      else
+        key
       end
     end
 
-  end
+    def build_url_via(action, query_options = {})
+      base_uri = self.class.base_uri
+      interface_url_fragment = select_interface_url_fragment(action)
+      base_uri + interface_url_fragment + extract_query_string(query_options)
+    end
+
+    def extract_query_string(options = {})
+      options.each_pair.map do |key, val|
+        if val.class == Array
+          "#{key}=#{val.join(',')}"
+        else
+          "#{key}=#{val}"
+        end
+      end.join('&')
+    end
 
+    def select_interface_url_fragment(action)
+      case action
+      when :currencies
+        Currency::Interface.url_name_and_version
+      when :market_prices
+        MarketPrice::Interface.url_name_and_version
+      when :prices
+        Price::Interface.url_name_and_version
+      when :price_history
+        PriceHistory::Interface.url_name_and_version
+      when :special_items
+        SpecialItem::Interface.url_name_and_version
+      when :users
+        User::Interface.url_name_and_version
+      when :user_listings
+        UserListing::Interface.url_name_and_version
+      end
+    end
+  end
 end

data/lib/backpack_tf/currency/interface.rb

@@ -0,0 +1,9 @@
+module BackpackTF
+  class Currency
+    # Access the IGetCurrencies interface
+    class Interface < BackpackTF::Interface
+      @name = :IGetCurrencies
+      @version = 1
+    end
+  end
+end

data/lib/backpack_tf/currency/response.rb

@@ -0,0 +1,24 @@
+module BackpackTF
+  class Currency
+    # Process reponses from IGetCurrencies
+    class Response < BackpackTF::Response
+      @response = nil
+      @currencies = nil
+
+      def self.currencies
+        hash = @response['currencies'].each_with_object({}) do |(name, attr), h|
+          h[name] = BackpackTF::Currency.new(name, attr)
+        end
+        @currencies = hash
+      end
+
+      def self.name
+        @name = @response['name']
+      end
+
+      def self.url
+        @url = @response['url']
+      end
+    end
+  end
+end

data/lib/backpack_tf/currency.rb

@@ -1,31 +1,10 @@
-module BackpackTF
-
-  # ruby representations of a JSON response to
-  # `IGetCurrencies`['response']
-  class Currency < Response
-
-    ###########################
-    #     Class Methods
-    ###########################
-
-    INTERFACE = :IGetCurrencies
-    @interface = INTERFACE
-    @response = nil
-    @@currencies = nil
-
-    def self.response
-      @response = superclass.responses[to_sym]
-    end
+require 'backpack_tf/currency/interface'
+require 'backpack_tf/currency/response'
 
-    def self.currencies
-      return @response if @response.nil?
-      @@currencies = response[:currencies]
-      hash_keys_to_sym(@@currencies)
-    end
-
-    ###########################
-    #     Instance Methods
-    ###########################
+module BackpackTF
+  # Ruby representations of a JSON response to IGetCurrencies
+  class Currency
+    include Helpers
 
     # @return [Fixnum] the quality index of the currency
     attr_reader :quality
@@ -35,35 +14,33 @@ module BackpackTF
     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
+    # @return [Fixnum] 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
+    # @return [Symbol] currency's craftability (:Craftable or :Non-Craftable)
     attr_reader :craftable
-    # @return [Symbol] either :Tradable or :Non-Tradable to signify currency's tradability
+    # @return [Symbol] currency's tradability (:Tradable or :Non-Tradable)
     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] 
+    # @return [Fixnum] Not sure what this attribute means!
     attr_reader :blanket
 
-    def initialize name, attr
-      attr = check_attr_keys(attr)
+    # @param name [String] name of currency
+    # @param attr [Hash] attributes for Currency object
+    # @return [Currency] a new Currency object
+    def initialize(name, attr)
+      processed_attr = hash_keys_to_sym(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]
+      @quality    = processed_attr[:quality]
+      @priceindex = processed_attr[:priceindex]
+      @single     = processed_attr[:single]
+      @plural     = processed_attr[:plural]
+      @round      = processed_attr[:round]
+      @craftable  = processed_attr[:craftable].to_sym
+      @tradable   = processed_attr[:tradable].to_sym
+      @defindex   = processed_attr[:defindex]
+      @blanket    = processed_attr[:blanket]
     end
-
   end
-
 end

data/lib/backpack_tf/helpers.rb

@@ -0,0 +1,29 @@
+module BackpackTF
+  # Common methods for objects & response-based classes
+  module Helpers
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Accessors/shortcuts for reaching the associated Response class from
+    # within a base namespace class.
+    module ClassMethods
+      def response=(new_data)
+        self::Response.response = new_data
+      end
+
+      def response
+        self::Response.response
+      end
+    end
+
+    private
+
+    def hash_keys_to_sym(hash)
+      hash.each_with_object({}) do |(key, val), new_hash|
+        key = key.to_sym if key.class == String
+        new_hash[key] = val
+      end
+    end
+  end
+end

data/lib/backpack_tf/interface.rb

@@ -0,0 +1,29 @@
+module BackpackTF
+  # Base class for accessing a BackpackTF API
+  class Interface
+    class << self
+      attr_reader :format, :callback, :appid, :name, :version
+    end
+
+    @format   = 'json'
+    @callback = nil
+    @appid    = '440'
+
+    # @param options [Hash]
+    # @option options [String] :format The format desired. Defaults to 'json'.
+    # @option options [String] :callback JSONP format only, used for function
+    #   call. Defaults to `nil`.
+    # @option options [String] :appid The ID of the game. Defaults to '440'.
+    # @return [Hash] default options
+    def self.defaults(options = {})
+      @format   = options[:format]   || 'json'
+      @callback = options[:callback] || nil
+      @appid    = options[:appid]    || '440'
+    end
+
+    # @return [String] URL fragment, ie: `/IGetPrices/v4/?`
+    def self.url_name_and_version
+      "/#{name}/v#{version}/?"
+    end
+  end
+end

data/lib/backpack_tf/market_price/interface.rb

@@ -0,0 +1,9 @@
+module BackpackTF
+  class MarketPrice
+    # Access the IGetMarketPrices interface
+    class Interface < BackpackTF::Interface
+      @name = :IGetMarketPrices
+      @version = 1
+    end
+  end
+end

data/lib/backpack_tf/market_price/response.rb

@@ -0,0 +1,15 @@
+module BackpackTF
+  class MarketPrice
+    # Process reponses from IGetMarketPrices
+    class Response < BackpackTF::Response
+      @response = nil
+      @items = {}
+
+      def self.items
+        @items = @response['items'].each_with_object({}) do |(name, attr), acc|
+          acc[name] = BackpackTF::MarketPrice.new(name, attr)
+        end
+      end
+    end
+  end
+end