espn 0.1.3 → 0.2.0

data/lib/espn/error.rb

@@ -1,12 +1,24 @@
 module ESPN
 
-  # Custom error class for rescuing from all ESPN errors
+  # Public: Custom error class for rescuing from all ESPN errors
   class Error < StandardError; end
 
-  # 401 HTTP Status Code
+  # Public: 400 HTTP Status Code
+  class BadRequest < Error; end
+
+  # Public: 401 HTTP Status Code
   class Unauthorized < Error; end
 
-  # 404 HTTP Status Code
+  # Public: 403 HTTP Status Code
+  class Forbidden < Error; end
+
+  # Public: 404 HTTP Status Code
   class NotFound < Error; end
 
+  # Public: 500 HTTP Status Code
+  class InternalServerError < Error; end
+
+  # Public: 504 HTTP Status Code
+  class GatewayTimeout < Error; end
+
 end

data/lib/espn/helpers.rb

@@ -0,0 +1,39 @@
+module ESPN
+
+  # Public: Commonly used Helpers are defined in this module.
+  #
+  # Examples
+  #
+  #   class Client
+  #     include ESPN::Helpers
+  #   end
+  module Helpers
+
+    # Public: Determine if a given Object is blank? If it is a String, or anything
+    # that responds to :empty?, it will use that method. If it does not respond to
+    # :empty? it will check that the Object is not nil.
+    #
+    # object  - The Object to check for blank.
+    #
+    # Examples
+    #
+    #   blank?('')
+    #   # => true
+    #
+    #   blank?('foo')
+    #   # => false
+    #
+    #   blank?(nil)
+    #   # => true
+    #
+    #   blank?(Object.new)
+    #   # => false
+    #
+    # Returns a Boolean.
+    def blank?(object)
+      object.respond_to?(:empty?) ? object.empty? : !object
+    end
+
+  end
+
+end

data/lib/espn/mapper.rb

@@ -0,0 +1,142 @@
+module ESPN
+
+  # Public: A module that handles mapping to make the ESPN API a little easier
+  # to digest.
+  #
+  # Examples
+  #
+  #   class Client
+  #     include ESPN::Mapper
+  #   end
+  module Mapper
+
+    # Public: Map all common leagues to sports.
+    LEAGUE_MAP = {
+      baseball: %w(mlb college-baseball),
+      basketball: %w(nba wnba mens-college-basketball womens-college-basketball),
+      football: %w(nfl college-football),
+      golf: %w(eur lpga pga sga web),
+      hockey: %w(nhl mens-college-hockey womens-college-hockey),
+      mma: %w(affliction bamma bfc ifl k1 lfc m1 mfc pancrase pride ringside
+              sharkfights shooto shootobrazil shootojapan shoxc sfl strikeforce
+              tpf ufc wec),
+      racing: %w(irl sprint nationwide truck f1 nhra),
+      soccer: %w(arg.1 uefa.champions fifa.world aut.1 bel.1 den.1 fra.1 ger.1
+                 ned.1 ita.1 nor.1 por.1 esp.1 swe.1 sui.1 tur.1 usa.1 usa.w.1
+                 mex.1 eng.1 eng.2 eng.3 eng.4 eng.5 eng.fa eng.worthington
+                 eng.trophy eng.charity uefa.uefa sco.1 sco.2 sco.3 sco.4
+                 sco.tennents sco.cis sco.challenge uefa.intertoto fifa.friendly
+                 uefa.worldq uefa.euroq fifa.confederations
+                 conmebol.libertadores concacaf.gold fifa.wwc fifa.worldq
+                 fifa.worldq.afc fifa.worldq.caf fifa.worldq.concacaf
+                 fifa.worldq.conmebol fifa.worldq.ofc fifa.worldq.uefa friendly
+                 usa.open fifa.friendly.w fifa.olympics fifa.olympicsq fifa.wyc
+                 uefa.euro intercontinental caf.nations fifa.w.olympicsq
+                 fifa.w.algarve esp.copa_del_rey conmebol.america
+                 fifa.w.olympics bra.1 chi.1 fra.2 ger.2 gre.1 ita.2 ned.2
+                 rus.1 esp.2 wal.1 irl.1 fra.coupe_de_la_ligue
+                 fra.coupe_de_france esp.super_cup nir.1 usa.misl
+                 conmebol.sudamericana uefa.super_cup aus.1 col.1 uru.1 per.1
+                 par.1 usa.ncaa.1 usa.ncaa.w.1 fifa.cwc ecu.1 ven.1 bol.1
+                 arg.urba ger.dfb_pokal ita.coppa_italia ned.cup rsa.1 rsa.2
+                 jpn.1 afc.champions afc.cup slv.1 crc.1 afc.cupq hon.1 gua.1
+                 aff.championship conmebol.sudamericano_sub20
+                 concacaf.champions_cup uefa.euro_u21 fifa.world.u20
+                 usa.world_series concacaf.superliga fifa.world.u17 concacaf.u23
+                 usa.usl.1 arg.2 col.2 uefa.euro.u19 concacaf.champions bra.2
+                 uru.2 arg.4 par.2 ven.2 arg.5 per.2 mex.2 chi.2 arg.3
+                 mex.interliga uefa.europa ecu.2 global.world_football_challenge
+                 uefa.carling eng.w.1 ger.super_cup ita.super_cup rug.irb.world
+                 panam.m panam.w arg.copa),
+      tennis: %w(atp wta),
+      boxing: %w(),
+      olympics: %w(),
+      :'horse-racing' => %w()
+    }
+
+    # Public: Map a league to a sport.
+    #
+    # league - The league (String or Symbol) to map to a sport.
+    #
+    # Examples
+    #
+    #   map_league_to_sport(:nhl)
+    #   # => { league: 'nhl', sport: 'hockey' }
+    #   map_league_to_sport('mlb')
+    #   # => { league: 'mlb', sport: 'baseball' }
+    #   map_league_to_sport('some-random-league')
+    #   # => { league: 'some-random-league', sport: '' }
+    #
+    # Returns a Hash.
+    def map_league_to_sport(league)
+      result = { league: league.to_s, sport: nil }
+
+      LEAGUE_MAP.each do |sport, leagues|
+        if leagues.include? result[:league]
+          result[:sport] = sport.to_s
+          break
+        end
+      end
+
+      result
+    end
+
+    # Public: Determine if the value is a valid sport.
+    #
+    # test - The String or Symbol to test.
+    #
+    # Returns a Boolean.
+    def sport?(test)
+      LEAGUE_MAP.keys.include?(test.to_sym)
+    end
+
+    # Public: Determine if the test value is a valid league.
+    #
+    # test - The String or Symbol to test.
+    #
+    # Returns a Boolean.
+    def league?(test)
+      LEAGUE_MAP.values.flatten.include?(test.to_s)
+    end
+
+    # Public: Get league and sport from args array. If sport or league is passed
+    # in the opts hash, they will override any mappings from the args Array.
+    #
+    # args - The Array to extract the league and sport from.
+    # opts - The Hash that will override all mappings if possible.
+    #
+    # Examples
+    #
+    #   extract_sport_and_league([:mlb])
+    #   # => 'baseball', 'mlb'
+    #
+    #   extract_sport_and_league(['horse-racing'])
+    #   # => 'horse-racing', ''
+    #
+    #   extract_sport_and_league(['baseball', 'mlb'], sport: 'basketball')
+    #   # => 'basketball', 'mlb'
+    #
+    # Returns two Strings.
+    def extract_sport_and_league(args, opts={})
+      sport, league = opts[:sport], opts[:league]
+
+      if args.size == 1 && league?(args[0])
+        map = map_league_to_sport(args[0])
+        sport ||= map[:sport].to_s
+        league ||= map[:league].to_s
+      elsif args.size == 1 && sport?(args[0])
+        sport ||= args[0].to_s
+        league ||= ''
+      elsif !opts[:league].to_s.empty?
+        map = map_league_to_sport(opts[:league])
+        sport ||= map[:sport].to_s
+      else
+        sport ||= args[0].to_s || ''
+        league ||= args[1].to_s || ''
+      end
+
+      return sport, league
+    end
+
+  end
+end

data/lib/espn/request.rb

@@ -1,24 +1,54 @@
 require 'multi_json'
+require 'faraday_middleware'
+require 'faraday/response/raise_espn_error'
 
 module ESPN
+
+  # Public: Make the request magic happen. This module gets included and only
+  # exposes one method to the public interface: #get.
+  #
+  # Examples
+  #
+  #   class Client
+  #     include ESPN::Request
+  #   end
   module Request
-    def get(path, options={})
-      request(:get, path, options)
+
+    # Public: Make an HTTP GET Request to the path, passing the opts as params
+    # in the query.
+    #
+    # pattern - A String to build a URL from.
+    # opts    - A Hash to send as query parameters (default: {}).
+    #
+    # Returns a String.
+    def get(pattern, opts={})
+      path = build_url(pattern, opts)
+      request(:get, path, opts)
     end
 
     private
 
-    def request(method, path, options)
+    # Internal: Use the Faraday::Connection from lib/espn/connection.rb and
+    # make the HTTP Request to the path.
+    #
+    # method  - A Symbol specifying the HTTP method to use.
+    # path    - The URL to send the request to.
+    # opts    - The Hash options to send as query parameters.
+    #
+    # Returns a String.
+    def request(method, path, opts)
 
       # TODO: Decide if I want to delete these or not. There is probably
       # a better way to do this, if so, by filtering them out.
-      %w( sport league method section team_id headline_id category_id clip_id
-          athlete_id event_id note_id podcast_id recording_id ).each do |k|
-        options.delete(k.to_sym)
+      %w(
+        sport league method section id team_id headline_id category_id
+        clip_id athlete_id event_id note_id podcast_id recording_id
+      ).each do |k|
+        opts.delete(k.to_sym)
       end
 
       response = connection.send(method) do |request|
-        request.url(path, options)
+        request.url(path, opts)
         request.options[:timeout] = timeout
         request.options[:open_timeout] = open_timeout
       end
@@ -26,5 +56,54 @@ module ESPN
       response.body
     end
 
+    # Internal: Build a new instance of Faraday with some default options and
+    # return it.
+    #
+    # Returns a Faraday::Connection.
+    def connection
+      options = { proxy: proxy, ssl: { verify: false }, url: api_url }
+      options.merge!(params: { apikey: api_key }) if authed?
+
+      connection = Faraday.new(options) do |builder|
+        builder.use Faraday::Response::RaiseESPNError
+        builder.use FaradayMiddleware::Mashify
+        builder.use FaradayMiddleware::ParseJson
+        builder.adapter adapter
+      end
+
+      connection
+    end
+
+    # Internal: Takes a pattern and a Hash of fragments and constructs a url.
+    # If the fragments include a league but not a sport, the league will be
+    # deleted from the Hash so it does not get sent along.
+    #
+    # pattern   - The pattern to match fragments against.
+    # fragments - The Array of fragments to apply to the pattern.
+    #
+    # Returns a String.
+    def build_url(pattern, fragments)
+
+      # Only allow league if sport is passed in.
+      fragments.delete(:league) if fragments[:sport].to_s.empty?
+
+      # Remove the /headlines section if fragments does not include a :method.
+      # This is due to the HEADLINES API being a little strange.
+      unless fragments.include? :method
+        pattern.gsub!('headlines', '')
+      end
+
+      template = URITemplate.new(:colon, pattern)
+      url = template.expand(fragments)
+
+      # Remove duplicate slashes (if any)
+      url = url.gsub(/\/{2,}/,'/')
+
+      # Remove trailing slash (if any)
+      url = url.gsub(/\/+$/, '')
+
+      url
+    end
+
   end
 end

data/lib/espn/version.rb

@@ -1,6 +1,6 @@
 module ESPN
 
   # Public: The version of the ESPN gem.
-  VERSION = '0.1.3'.freeze
+  VERSION = '0.2.0'.freeze
 
 end

data/lib/faraday/response/raise_espn_error.rb

@@ -1,28 +1,50 @@
 require 'faraday'
 require 'multi_json'
 
-# @api private
+# Internal: Faraday module that the response error middleware is added to.
 module Faraday
+
+  # Internal: Faraday Middleware that deals with errors coming back from the API.
+  #
+  # Examples
+  #
+  #   conn = Faraday.new({}) do |builder|
+  #     builder.use Faraday::Response::RaiseESPNError
+  #   end
   class Response::RaiseESPNError < Response::Middleware
+
+    # Internal: Hook into the complete callback for the client. When the result
+    # comes back, if it is a status code that we want to raise an error for, we
+    # will do that.
+    #
+    # Raises ESPN::Unauthorized, ESPN::Forbidden and ESPN::Notfound.
+    # Returns nothing.
     def on_complete(response)
-      case response[:status].to_i
+      return if response[:body].nil?
+
+      case response[:body][:code].to_i
+      when 400
+        raise ESPN::BadRequest, error_message(response)
       when 401
         raise ESPN::Unauthorized, error_message(response)
+      when 403
+        raise ESPN::Forbidden, error_message(response)
       when 404
         raise ESPN::NotFound, error_message(response)
+      when 500
+        raise ESPN::InternalServerError, error_message(response)
+      when 504
+        raise ESPN::GatewayTimeout, error_message(response)
       end
     end
 
+    # Internal: Parse the response and return a human friendly String
+    # representing the error that we received.
+    #
+    # Returns a String.
     def error_message(response)
-      message = if (body = response[:body]) && !body.empty?
-        if body.is_a?(String)
-          body = MultiJson.load(body, :symbolize_keys => true)
-        end
-        ": #{body[:error] || body[:message] || ''}"
-      else
-        ''
-      end
-      "#{response[:method].to_s.upcase} #{response[:url].to_s}: #{response[:status]}#{message}"
+      "#{response[:method].to_s.upcase} #{response[:url].to_s}: #{response[:body][:status]} - #{response[:body][:message]}"
     end
   end
+
 end

data/spec/espn/arguments_spec.rb

@@ -0,0 +1,76 @@
+require 'spec_helper'
+
+describe ESPN::Arguments do
+  before do
+    @arguments = ESPN::Arguments.new([])
+  end
+
+  it 'should have an options reader' do
+    @arguments.respond_to?(:options).should be_true
+  end
+
+  it 'should not have an options writer' do
+    @arguments.respond_to?(:options=).should be_false
+  end
+
+  it 'should default options to an empty hash' do
+    @arguments.options.delete(:sport)
+    @arguments.options.delete(:league)
+    @arguments.options.should eq({})
+  end
+
+  it 'should extract options' do
+    @arguments = ESPN::Arguments.new([{ foo: 'bar' }])
+    @arguments.options.delete(:sport)
+    @arguments.options.delete(:league)
+    @arguments.options.should eq({foo: 'bar'})
+  end
+
+  it 'should extract sport' do
+    @arguments = ESPN::Arguments.new([:baseball])
+    @arguments.options[:sport].should eq('baseball')
+  end
+
+  it 'should extract league mapped to a sport' do
+    @arguments = ESPN::Arguments.new([:mlb])
+    @arguments.options.should eq({sport: 'baseball', league: 'mlb'})
+  end
+
+  it 'should extract sport and league' do
+    @arguments = ESPN::Arguments.new([:football, :mlb])
+    @arguments.options.should eq({sport: 'football', league: 'mlb'})
+  end
+
+  context 'when passing default values' do
+    it 'should set default values' do
+      @arguments = ESPN::Arguments.new([{sport: 'baseball'}], league: 'mlb')
+      @arguments.options.should eq({sport: 'baseball', league: 'mlb'})
+    end
+
+    it 'should not override non-nil values' do
+      @arguments = ESPN::Arguments.new([{sport: 'baseball'}], sport: 'football')
+      @arguments.options[:sport].should eq('baseball')
+    end
+  end
+
+  context 'when passing required fields' do
+    it 'should raise an exception if the field is blank' do
+      expect {
+        ESPN::Arguments.new([], {}, [:league])
+      }.to raise_error(ArgumentError, 'You must supply a valid league.')
+    end
+
+    it 'should not raise an exception if the field is not blank' do
+      expect {
+        ESPN::Arguments.new([:mlb], {}, [:league])
+      }.not_to raise_error(ArgumentError)
+    end
+
+    it 'should accept a string' do
+      expect {
+        ESPN::Arguments.new([:mlb], {}, ['league'])
+      }.not_to raise_error(ArgumentError)
+    end
+  end
+
+end