bn 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2822afc6d969ba0f64f38060a6408eaa684b9ef8
+  data.tar.gz: 0d13387ecc63fdfa99d4ccdd8d4a061f614cdae1
+SHA512:
+  metadata.gz: 5d7f33cb1db092af1f8bd7add060a4424cbfa4e1b5990d37c7dc44e9d35f7ca6c3db8b16a36c627a69682378210774552c4fc551c2b66206e5f92c1f069a8b5d
+  data.tar.gz: 7424238727dd121b472b3e0c5d7b78a32a860bc44d2d24891c75ad5790eb585a588e914f4053043b9aeda41b7a890f376c8b779cfd59c5fb25d9d46854d1df60

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,22 @@
+PATH
+  remote: .
+  specs:
+    bn (0.0.1)
+      httpi (~> 2.4.1)
+      version (~> 1.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    httpi (2.4.1)
+      rack
+    rack (1.6.4)
+    rake (10.4.2)
+    version (1.0.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bn!
+  rake (~> 10.4.2)

data/README.md

@@ -0,0 +1,202 @@
+# BN
+
+BN is a [Battle.net](http://battle.net) API adapter and entity mapper.
+
+## Install
+
+### Bundler: `gem 'bn'`
+
+### RubyGems: `gem install bn`
+
+## Usage
+
+### Requiring
+
+You can require the whole library with
+
+```rb
+require "bn"
+```
+
+Or you can require individual files/groups of files with
+
+```rb
+require "bn/api/d3"
+require "bn/entity/d3"
+```
+
+### API
+
+**Mapping**
+
+The `BN::API::Mapper` will send an HTTP request, parse the JSON response body, and create a new instance of
+the entity associated with the API call.
+
+```rb
+require "bn/api/mapper"
+
+mapper = BN::API::Mapper.new(key: "00000000000000000000000000000000")
+
+p mapper.d3.profile(battle_tag: "Example#0000") #=> #<BN::Entity::D3::Profile:0x007fa2a10e29a0 @battle_tag="Example#0000" ...>
+```
+
+If called without arguments, the mapper will return a `BN::API::Mapping` instance, which associates API calls with
+`Entity` instances. It also holds the list of middleware which the API HTTP response will go through before returning:
+
+```rb
+require "bn/api/mapper"
+
+mapper = BN::API::Mapper.new(key: "00000000000000000000000000000000")
+mapping = mapper.d3.profile
+
+p mapping.api_class # => BN::API::D3
+p mapping.api_method # => :profile
+p mapping.middleware # => [BN::Middleware::HTTPResponse, BN::Middleware::KeyConverter, BN::Middleware::APIError, BN::Middleware::D3::Profile]
+
+mapping.execute(battle_tag: "Example#0000") #=> #<BN::Entity::D3::Profile:0x007fa2a10e29a0 @battle_tag="Example#0000" ...>
+```
+
+This would allow you to manipulate the middleware before executing.
+
+[Read more about middleware here.](#middleware)
+
+**HTTP**
+
+This simply sends an HTTP request to the API and returns it.  
+Useful for when you do not need entities or middleware.
+
+```rb
+require "bn/api/d3"
+
+api = BN::API::D3.new(key: "00000000000000000000000000000000")
+
+p api.profile(battle_tag: "Example#0000") #=> #<HTTPI::Response:0x007fa2a0d0a5d0 @code=301 ...>
+```
+
+### Entity
+
+An entity is a subclass of `BN::Entity::Base` for profiles, characters, items, and other game items.
+
+You can initialize entities with an object responding to `#to_h` or use attribute setters after initialization.
+
+```rb
+require "bn/entity/d3/hero"
+
+hero = BN::Entity::D3::Hero.new(name: "Gronc")
+hero.level = 70
+```
+
+Some entities also come with some helper methods for calculations:
+
+```rb
+hero.strength = 220
+
+# Calculate the damage per second based on hero attributes
+p hero.damage # => 12345
+```
+
+### Middleware
+
+Middleware converts data from one form to another, raising an error on failure.
+
+For example, the `BN::Middleware::HTTPResponse` accepts anything that responds to `#body` and attempts to parse
+the body as JSON. If the response body could not be parsed or the JSON API response returned an error, then an error
+will be raised.
+
+This is useful if you're not using `BN::API` to send HTTP requests to the Battle.net API.
+
+```rb
+require "net/http"
+require "uri"
+require "bn/middleware/http_response"
+
+uri = URI("https://us.api.battle.net/d3/profile/Example-0000")
+uri.query = URI.encode_www_form(apikey: "00000000000000000000000000000000", locale: "en_US")
+
+response = Net::HTTP.get_response(uri)
+data = BN::Middleware::HTTPResponse.execute(response)
+
+p data # => { battle_tag: "Example#0000" }
+```
+
+**Chaining**
+
+Middleware can be chained together if the result of one conforms to the requirements of another:
+
+```rb
+require "bn/api/d3"
+require "bn/middleware/http_response"
+require "bn/middleware/d3/profile"
+
+api = BN::API::D3.new(key: "00000000000000000000000000000000")
+
+response = api.profile(battle_tag: "Example#0000")
+
+data = BN::Middleware::HTTPResponse.execute(response)
+profile = BN::Middleware::D3::Profile.execute(data)
+
+p profile #=> #<BN::Entity::D3::Profile:0x007fa2a10e29a0 @battle_tag="Example#0000" ...>
+```
+
+To make chaining easier, there is a helper method on `BN::Middleware`:
+
+```rb
+require "bn/api/d3"
+require "bn/middleware"
+
+api = BN::API::D3.new(key: "00000000000000000000000000000000")
+
+response = api.profile(battle_tag: "Example#0000")
+
+data = BN::Middleware::HTTPResponse.execute(response)
+profile = BN::Middleware::D3::Profile.execute(data)
+profile = BN::Middleware.execute(data, BN::Middleware::HTTPResponse, BN::Middleware::D3::Profile)
+
+p profile #=> #<BN::Entity::D3::Profile:0x007fa2a10e29a0 @battle_tag="Example#0000" ...>
+```
+
+Middleware given can either be classes or instances. Usually subclassed from `BN::Middleware::Base`, but can be anything
+responding to `#execute`.
+
+**Subclassing**
+
+You can subclass `BN::Middleware::Base` to create your own transformations, such as manipulating JSON API responses
+or initializing your own profile/item/etc objects:
+
+```rb
+require "bn/middleware/base"
+
+class HeroMiddleware < BN::Middleware::Base
+  def execute(data)
+    hero_data = data[:heroes].first
+
+    Hero.new(data[:hero_data])
+  end
+end
+
+class Hero
+  def initialize(name)
+    @name = name
+  end
+
+  attr_reader :name
+end
+
+require "bn/api/d3"
+require "bn/middleware/http_response"
+
+api = BN::API::D3.new(key: "00000000000000000000000000000000")
+
+response = api.hero(battle_tag: "Example#0000", id: 1234)
+
+data = BN::Transform::HTTPResponse.execute(response)
+hero = HeroTransform.execute(data)
+
+p hero #=> #<Hero:0x007fa2a10e29a0 @name="Gronc">
+```
+
+## Copyright
+
+Copyright © 2015 Ryan Scott Lewis <ryan@rynet.us>.
+
+The MIT License (MIT) - See LICENSE for further details.

data/Rakefile

@@ -0,0 +1,14 @@
+require "pathname"
+require "rake/version_task"
+require "rubygems/package_task"
+
+gemspec = Pathname.glob(Pathname.new(__FILE__).join("..", "*.gemspec")).first
+$spec = Gem::Specification.load(gemspec.to_s)
+
+Gem::PackageTask.new($spec) do |task|
+  task.need_zip = false
+end
+
+Rake::VersionTask.new do |task|
+  task.with_git_tag = true
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/bn.gemspec

@@ -0,0 +1,23 @@
+require "pathname"
+
+Gem::Specification.new do |s|
+  # Variables
+  s.author      = "Ryan Scott Lewis"
+  s.email       = "ryan@rynet.us"
+  s.summary     = "A Battle.net API adapter and entity mapper."
+  s.license     = "MIT"
+
+  # Dependencies
+  s.add_dependency "version", "~> 1.0.0"
+  s.add_dependency "httpi", "~> 2.4.1"
+  s.add_development_dependency "rake", "~> 10.4.2"
+
+  # Pragmatically set variables
+  s.homepage      = "http://github.com/RyanScottLewis/#{s.name}"
+  s.version       = Pathname.glob("VERSION*").first.read rescue "0.0.0"
+  s.description   = s.summary
+  s.name          = Pathname.new(__FILE__).basename(".gemspec").to_s
+  s.require_paths = ["lib"]
+  s.files         = Dir["{{Rake,Gem}file{.lock,},README*,VERSION,LICENSE,*.gemspec,{lib,bin,examples,spec,test}/**/*}"]
+  s.test_files    = Dir["{examples,spec,test}/**/*"]
+end

data/lib/bn.rb

@@ -0,0 +1,9 @@
+require "version"
+
+# Battle.net adapter and entity mapper.
+module BN
+  is_versioned
+end
+
+require "bn/api"
+require "bn/middleware"

data/lib/bn/api.rb

@@ -0,0 +1,19 @@
+module BN
+  # The API requestors.
+  module API
+    # The valid regions for the API.
+    # Contains name, host, and valid locales for each region.
+    REGIONS = {
+      us:  { name: "US",              uri: "https://us.api.battle.net",    locales: %w(en_US es_MX pt_BR) },
+      eu:  { name: "Europe",          uri: "https://us.api.battle.net",    locales: %w(en_GB es_ES fr_FR ru_RU de_DE pt_PT it_IT) },
+      kr:  { name: "Korea",           uri: "https://kr.api.battle.net",    locales: %w(ko_KR) },
+      tw:  { name: "Taiwan",          uri: "https://tw.api.battle.net",    locales: %w(zh_TW) },
+      cn:  { name: "China",           uri: "https://api.battlenet.com.cn", locales: %w(zh_CN) },
+      sea: { name: "South East Asia", uri: "https://sea.api.battle.net",   locales: %w(en_US) }
+    }
+  end
+end
+
+require "bn/api/d3"
+require "bn/api/sc2"
+require "bn/api/wow"

data/lib/bn/api/base.rb

@@ -0,0 +1,78 @@
+require "httpi"
+require "bn/helpers/has_attributes"
+require "bn/error/api/invalid_key"
+require "bn/error/api/invalid_region"
+require "bn/error/api/invalid_locale"
+
+module BN
+  module API
+    # The base class for API requesters.
+    class Base
+      include Helpers::HasAttributes
+
+      def initialize(attributes={})
+        self.region = :us
+
+        super
+
+        raise Error::API::InvalidKey if @key.nil?
+      end
+
+      attribute(:key) { |value| validate_key(value) }
+
+      attribute(:region) { |value| validate_and_convert_region(value) }
+
+      attribute(:locale) { |value| validate_locale(value) }
+
+      protected
+
+      # Send an HTTP GET request.
+      #
+      # @param [#to_s] url
+      # @param [#to_h] query
+      # @return [HTTPI::Response]
+      def get(url, query={})
+        url = url.to_s.gsub(%r{^/}, "")
+        query = query.to_h
+
+        request = HTTPI::Request.new
+        request.url = "#{@region[:host]}/#{url}"
+        request.query = { apikey: @key, locale: @locale }.merge(query)
+
+        HTTPI.get(request)
+      end
+
+      def validate_key(value)
+        value = value.to_s.delete(" ")
+
+        raise Error::API::InvalidKey if value.empty?
+
+        value
+      end
+
+      def validate_and_convert_region(region_key)
+        region_key = region_key.to_sym
+
+        raise Error::API::InvalidRegion unless BN::API::REGIONS.keys.include?(region_key)
+
+        region = REGIONS[region_key]
+        @locale = region[:locales].first
+
+        region
+      end
+
+      def validate_locale(locale)
+        locale = locale.to_s.strip
+        locale = @region[:locales].first if locale.empty?
+
+        raise Error::API::InvalidLocale, region: @region unless @region[:locales].include?(locale)
+
+        locale
+      end
+
+      def sanitize_battle_tag(value)
+        value.to_s.delete(" ").gsub(/#/, "-")
+      end
+    end
+  end
+end

data/lib/bn/api/d3.rb

@@ -0,0 +1,44 @@
+require "bn/api/base"
+
+module BN
+  module API
+    # The the Diablo 3 API requester.
+    class D3 < Base
+      # Request a profile.
+      #
+      # @param [#to_h] options
+      # @option options [#to_s] :battle_tag The battle tag.
+      # @return [HTTPI::Response]
+      def profile(options={})
+        options = options.to_h
+
+        battle_tag = sanitize_battle_tag(options.delete(:battle_tag))
+
+        get("/d3/profile/#{battle_tag}", options)
+      end
+
+      # Request a hero.
+      #
+      # @param [#to_h] options
+      # @option options [#to_s] :battle_tag The battle tag.
+      # @option options [#to_s] :id The hero's ID.
+      # @return [HTTPI::Response]
+      def hero(options={})
+        options = options.to_h
+
+        battle_tag = sanitize_battle_tag(options.delete(:battle_tag))
+        id = sanitize_id(options.delete(:id))
+
+        get("/d3/profile/#{battle_tag}/hero/#{id}", options)
+      end
+
+      protected
+
+      def sanitize_id(id)
+        id = id.to_s.gsub(/[^0-9]/, "") unless id.is_a?(Integer)
+
+        id.to_i
+      end
+    end
+  end
+end

data/lib/bn/api/sc2.rb

@@ -0,0 +1,74 @@
+require "bn/api/base"
+
+module BN
+  module API
+    # The the StarCraft 3 API requester.
+    class SC3 < Base
+      # Request a profile.
+      #
+      # @param [#to_h] options
+      # @option options [#to_s] :id The ID of the profile.
+      # @option options [#to_s] :region The region of the profile.
+      # @option options [#to_s] :name The name of the profile
+      # @return [HTTPI::Response]
+      def profile(options={})
+        get(profile_uri(options))
+      end
+
+      # Request a profile's ladders.
+      #
+      # @param [#to_h] options
+      # @option options [#to_s] :id The ID of the profile.
+      # @option options [#to_s] :region The region of the profile.
+      # @option options [#to_s] :name The name of the profile
+      # @return [HTTPI::Response]
+      def ladders(options={})
+        get(profile_uri(options, "ladders"))
+      end
+
+      # Request a profile's matches.
+      #
+      # @param [#to_h] options
+      # @option options [#to_s] :id The ID of the profile.
+      # @option options [#to_s] :region The region of the profile.
+      # @option options [#to_s] :name The name of the profile
+      # @return [HTTPI::Response]
+      def matches(options={})
+        get(profile_uri(options, "matches"))
+      end
+
+      # Request a ladder.
+      #
+      # @param [#to_h] options
+      # @option options [#to_s] :id The ID of the ladder.
+      # @return [HTTPI::Response]
+      def ladder(options={})
+        options = options.to_h
+
+        get("/sc2/ladder/#{options[:id]}")
+      end
+
+      # Request achievements.
+      #
+      # @return [HTTPI::Response]
+      def achievements
+        get("/sc2/data/achievements")
+      end
+
+      # Request rewards.
+      #
+      # @return [HTTPI::Response]
+      def achievements
+        get("/sc2/data/rewards")
+      end
+
+      protected
+
+      def profile_uri(options, path=nil)
+        options = options.to_h
+
+        "/sc2/profile/#{options[:id]}/#{options[:region]}/#{options[:name]}#{"/#{path}" unless path.nil?}"
+      end
+    end
+  end
+end