echowrap 0.0.1

data/lib/echowrap/client.rb

@@ -0,0 +1,80 @@
+require 'faraday'
+require 'multi_json'
+require 'echowrap/configurable'
+require 'echowrap/api/artist'
+require 'echowrap/api/playlist'
+require 'echowrap/api/sandbox'
+require 'echowrap/api/song'
+require 'echowrap/api/oauth'
+require 'echowrap/api/taste_profile'
+require 'echowrap/api/track'
+require 'simple_oauth'
+
+
+module Echowrap
+  class Client
+    include Echowrap::API::Artist
+    include Echowrap::API::Playlist
+    include Echowrap::API::Sandbox
+    include Echowrap::API::Song
+    include Echowrap::API::Oauth
+    include Echowrap::API::TasteProfile
+    include Echowrap::API::Track
+    include Echowrap::Configurable
+
+    # Initializes a new Client object
+    #
+    # @param options [Hash]
+    # @return [Echowrap::Client]
+    def initialize(options={})
+      Echowrap::Configurable.keys.each do |key|
+        instance_variable_set(:"@#{key}", options[key] || Echowrap.instance_variable_get(:"@#{key}"))
+      end
+    end
+
+    # Perform an HTTP GET request
+    def get(path, params={})
+      request(:get, path, params)
+    end
+
+    # Perform an HTTP POST request
+    def post(path, params={})
+      signature_params = params.values.any?{|value| value.respond_to?(:to_io)} ? {} : params
+      request(:post, path, params, signature_params)
+    end
+
+    private
+
+      def setup_authentication_parameters(method, path, params)
+        params = params.merge(:api_key => @api_key)
+        params = params.merge(oauth_parameters(method, path, params)) if params.delete(:oauth_request)
+        params
+      end
+
+      def request(method, path, params={}, signature_params=params)
+        params = setup_authentication_parameters(method, path, params)
+        connection.send(method.to_sym, path, params).env
+      rescue Faraday::Error::ClientError
+        raise Echowrap::Error::ClientError
+      rescue MultiJson::DecodeError
+        raise Echowrap::Error::DecodeError
+      end
+
+      # Returns a Faraday::Connection object
+      #
+      # @return [Faraday::Connection]
+      def connection
+        @connection ||= begin
+          connection_options = {:builder => @middleware}
+          connection_options[:ssl] = {:verify => true} if @endpoint[0..4] == 'https'
+          Faraday.new(@endpoint, @connection_options.merge(connection_options))
+        end
+      end
+
+      def oauth_parameters(method, path, params={})
+        uri = URI(@endpoint + path)
+        SimpleOAuth::Header.new(method, uri, params, credentials).signed_attributes
+      end
+
+  end
+end

data/lib/echowrap/configurable.rb

@@ -0,0 +1,84 @@
+require 'echowrap/default'
+require 'echowrap/error/configuration_error'
+require 'forwardable'
+
+module Echowrap
+  module Configurable
+    extend Forwardable
+    attr_writer :api_key, :consumer_key, :shared_secret
+    attr_accessor :endpoint, :connection_options, :middleware
+    def_delegator :options, :hash
+
+    class << self
+      def keys
+        @keys ||= [
+          :api_key,
+          :consumer_key,
+          :shared_secret,
+          :endpoint,
+          :connection_options,
+          :middleware,
+        ]
+      end
+    end
+
+    # Convenience method to allow configuration options to be set in a block
+    #
+    # @raise [Echowrap::Error::ConfigurationError] Error is raised when supplied
+    #   echonest credentials are not a String or Symbol.
+    def configure
+      yield self
+      validate_credential_type!
+      self
+    end
+
+    # @return [Boolean]
+    def credentials?
+      credentials.values.all?
+    end
+
+    def reset!
+      Echowrap::Configurable.keys.each do |key|
+        instance_variable_set(:"@#{key}", Echowrap::Default.options[key])
+      end
+      self
+    end
+
+    alias setup reset!
+
+  private
+    def application_only_auth?
+      true
+    end
+
+    # @return [Hash]
+    def credentials
+      {
+        :api_key => @api_key,
+        :consumer_key => @consumer_key,
+        :consumer_secret => @shared_secret,
+      }
+    end
+
+    # @return [Hash]
+    def options
+      Hash[Echowrap::Configurable.keys.map{|key| [key, instance_variable_get(:"@#{key}")]}]
+    end
+
+    # Ensures that all credentials set during configuration are of a
+    # valid type. Valid types are String and Symbol.
+    #
+    # @raise [Echowrap::Error::ConfigurationError] Error is raised when
+    #   supplied echonest credentials are not a String or Symbol.
+    def validate_credential_type!
+      credentials.each do |credential, value|
+        next if value.nil?
+
+        unless value.is_a?(String) || value.is_a?(Symbol)
+          raise(Error::ConfigurationError, "Invalid #{credential} specified: #{value} must be a string or symbol.")
+        end
+      end
+    end
+
+  end
+end

data/lib/echowrap/default.rb

@@ -0,0 +1,88 @@
+require 'faraday'
+require 'faraday/request/multipart'
+require 'echowrap/configurable'
+require 'echowrap/error/client_error'
+require 'echowrap/error/server_error'
+require 'echowrap/request/multipart_with_file'
+require 'echowrap/response/parse_json'
+require 'echowrap/response/raise_error'
+ require 'echowrap/version'
+
+module Echowrap
+  module Default
+    ENDPOINT = 'http://developer.echonest.com' unless defined? Echowrap::Default::ENDPOINT
+    CONNECTION_OPTIONS = {
+      :headers => {
+        :accept => 'application/json',
+        :user_agent => "Echowrap Ruby Gem #{Echowrap::Version}",
+      },
+      :request => {
+        :open_timeout => 5,
+        :timeout => 10,
+        :params_encoder => Faraday::FlatParamsEncoder
+      },
+      :ssl => {
+        :verify => false
+      },
+    } unless defined? Echnoest::Default::CONNECTION_OPTIONS
+    IDENTITY_MAP = false unless defined? Echowrap::Default::IDENTITY_MAP
+    MIDDLEWARE = Faraday::RackBuilder.new do |builder|
+      # Convert file uploads to Faraday::UploadIO objects
+      builder.use Echowrap::Request::MultipartWithFile
+      # Checks for files in the payload
+      builder.use Faraday::Request::Multipart
+      # Convert request params to "www-form-urlencoded"
+      builder.use Faraday::Request::UrlEncoded
+      # Handle 4xx server responses
+      builder.use Echowrap::Response::RaiseError, Echowrap::Error::ClientError
+      # Parse JSON response bodies using MultiJson
+      builder.use Echowrap::Response::ParseJson
+      # Handle 5xx server responses
+      builder.use Echowrap::Response::RaiseError, Echowrap::Error::ServerError
+      # Set Faraday's HTTP adapter
+      builder.adapter Faraday.default_adapter
+    end unless defined? Echowrap::Default::MIDDLEWARE
+
+    class << self
+
+      # @return [Hash]
+      def options
+        Hash[Echowrap::Configurable.keys.map{|key| [key, send(key)]}]
+      end
+
+      # @return [String]
+      def api_key
+        ENV['ECHONEST_API_KEY']
+      end
+
+      # @return [String]
+      def consumer_key
+        ENV['ECHONEST_CONSUMER_KEY']
+      end
+
+      # @return [String]
+      def shared_secret
+        ENV['ECHONEST_SHARED_SECRET']
+      end
+
+      # @note This is configurable in case you want to use a Echowrap-compatible endpoint.
+      # @return [String]
+      def endpoint
+        ENDPOINT
+      end
+
+      def connection_options
+        CONNECTION_OPTIONS
+      end
+
+      # @note Faraday's middleware stack implementation is comparable to that of Rack middleware.  The order of middleware is important: the first middleware on the list wraps all others, while the last middleware is the innermost one.
+      # @see https://github.com/technoweenie/faraday#advanced-middleware-usage
+      # @see http://mislav.uniqpath.com/2011/07/faraday-advanced-http/
+      # @return [Faraday::RackBuilder]
+      def middleware
+        MIDDLEWARE
+      end
+
+    end
+  end
+end

data/lib/echowrap/doc_counts.rb

@@ -0,0 +1,8 @@
+require 'echowrap/base'
+
+module Echowrap
+  class DocCounts < Echowrap::Base
+    attr_reader :audio, :biographies, :blogs, :images, :news, :reviews, :songs, :video
+
+  end
+end

data/lib/echowrap/echonest_id.rb

@@ -0,0 +1,8 @@
+require 'echowrap/base'
+
+module Echowrap
+  class EchonestId < Echowrap::Base
+    attr_reader :foreign_id, :id
+
+  end
+end

data/lib/echowrap/error/bad_gateway.rb

@@ -0,0 +1,11 @@
+require 'echowrap/error/server_error'
+
+module Echowrap
+  class Error
+    # Raised when Echowrap returns the HTTP status code 502
+    class BadGateway < Echowrap::Error::ServerError
+      HTTP_STATUS_CODE = 502
+      MESSAGE = "Echowrap is down or being upgraded."
+    end
+  end
+end

data/lib/echowrap/error/bad_request.rb

@@ -0,0 +1,10 @@
+require 'echowrap/error/client_error'
+
+module Echowrap
+  class Error
+    # Raised when Echowrap returns the HTTP status code 400
+    class BadRequest < Echowrap::Error::ClientError
+      HTTP_STATUS_CODE = 400
+    end
+  end
+end

data/lib/echowrap/error/client_error.rb

@@ -0,0 +1,35 @@
+require 'echowrap/error'
+
+module Echowrap
+  class Error
+    # Raised when Echowrap returns a 4xx HTTP status code or there's an error in Faraday
+    class ClientError < Echowrap::Error
+
+      # Create a new error from an HTTP environment
+      #
+      # @param response [Hash]
+      # @return [Echowrap::Error]
+      def self.from_response(response={})
+        new(parse_error(response[:body]), response[:response_headers])
+      end
+
+    private
+
+      def self.parse_error(body)
+        if body.nil?
+          ''
+        elsif body[:error]
+          body[:error]
+        elsif body[:errors]
+          first = Array(body[:errors]).first
+          if first.is_a?(Hash)
+            first[:message].chomp
+          else
+            first.chomp
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/echowrap/error/configuration_error.rb

@@ -0,0 +1,8 @@
+require 'echowrap/error'
+
+module Echowrap
+  class Error
+    class ConfigurationError < ::ArgumentError
+    end
+  end
+end

data/lib/echowrap/error/forbidden.rb

@@ -0,0 +1,10 @@
+require 'echowrap/error/client_error'
+
+module Echowrap
+  class Error
+    # Raised when Echowrap returns the HTTP status code 403
+    class Forbidden < Echowrap::Error::ClientError
+      HTTP_STATUS_CODE = 403
+    end
+  end
+end

data/lib/echowrap/error/gateway_timeout.rb

@@ -0,0 +1,11 @@
+require 'echowrap/error/server_error'
+
+module Echowrap
+  class Error
+    # Raised when Echowrap returns the HTTP status code 504
+    class GatewayTimeout < Echowrap::Error::ServerError
+      HTTP_STATUS_CODE = 504
+      MESSAGE = "The Echowrap servers are up, but the request couldn't be serviced due to some failure within our stack. Try again later."
+    end
+  end
+end

data/lib/echowrap/error/internal_server_error.rb

@@ -0,0 +1,11 @@
+require 'echowrap/error/server_error'
+
+module Echowrap
+  class Error
+    # Raised when Echowrap returns the HTTP status code 500
+    class InternalServerError < Echowrap::Error::ServerError
+      HTTP_STATUS_CODE = 500
+      MESSAGE = "Something is technically wrong."
+    end
+  end
+end

data/lib/echowrap/error/not_acceptable.rb

@@ -0,0 +1,10 @@
+require 'echowrap/error/client_error'
+
+module Echowrap
+  class Error
+    # Raised when Echowrap returns the HTTP status code 406
+    class NotAcceptable < Echowrap::Error::ClientError
+      HTTP_STATUS_CODE = 406
+    end
+  end
+end

data/lib/echowrap/error/not_found.rb

@@ -0,0 +1,10 @@
+require 'echowrap/error/client_error'
+
+module Echowrap
+  class Error
+    # Raised when Echowrap returns the HTTP status code 404
+    class NotFound < Echowrap::Error::ClientError
+      HTTP_STATUS_CODE = 404
+    end
+  end
+end

data/lib/echowrap/error/server_error.rb

@@ -0,0 +1,28 @@
+require 'echowrap/error'
+
+module Echowrap
+  class Error
+    # Raised when Echowrap returns a 5xx HTTP status code
+    class ServerError < Echowrap::Error
+      MESSAGE = "Server Error"
+
+      # Create a new error from an HTTP environment
+      #
+      # @param response [Hash]
+      # @return [Echowrap::Error]
+      def self.from_response(response={})
+        new(nil, response[:response_headers])
+      end
+
+      # Initializes a new ServerError object
+      #
+      # @param message [String]
+      # @param response_headers [Hash]
+      # @return [Echowrap::Error::ServerError]
+      def initialize(message=nil, response_headers={})
+        super((message || self.class.const_get(:MESSAGE)), response_headers)
+      end
+
+    end
+  end
+end

data/lib/echowrap/error/service_unavailable.rb

@@ -0,0 +1,11 @@
+require 'echowrap/error/server_error'
+
+module Echowrap
+  class Error
+    # Raised when Echowrap returns the HTTP status code 503
+    class ServiceUnavailable < Echowrap::Error::ServerError
+      HTTP_STATUS_CODE = 503
+      MESSAGE = "(__-){ Echowrap is over capacity."
+    end
+  end
+end

data/lib/echowrap/error/too_many_requests.rb

@@ -0,0 +1,12 @@
+require 'echowrap/error/client_error'
+
+module Echowrap
+  class Error
+    # Raised when Echowrap returns the HTTP status code 429
+    class TooManyRequests < Echowrap::Error::ClientError
+      HTTP_STATUS_CODE = 429
+    end
+    EnhanceYourCalm = TooManyRequests
+    RateLimited = TooManyRequests
+  end
+end

data/lib/echowrap/error/unauthorized.rb

@@ -0,0 +1,10 @@
+require 'echowrap/error/client_error'
+
+module Echowrap
+  class Error
+    # Raised when Echowrap returns the HTTP status code 401
+    class Unauthorized < Echowrap::Error::ClientError
+      HTTP_STATUS_CODE = 401
+    end
+  end
+end

data/lib/echowrap/error/unprocessable_entity.rb

@@ -0,0 +1,10 @@
+require 'echowrap/error/client_error'
+
+module Echowrap
+  class Error
+    # Raised when Echowrap returns the HTTP status code 404
+    class UnprocessableEntity < Echowrap::Error::ClientError
+      HTTP_STATUS_CODE = 422
+    end
+  end
+end

data/lib/echowrap/error.rb

@@ -0,0 +1,32 @@
+module Echowrap
+  # Custom error class for rescuing from all Echowrap errors
+  class Error < StandardError
+    attr_reader :rate_limit, :wrapped_exception
+
+    # @return [Hash]
+    def self.errors
+      @errors ||= Hash[descendants.map{|klass| [klass.const_get(:HTTP_STATUS_CODE), klass]}]
+    end
+
+    # @return [Array]
+    def self.descendants
+      ObjectSpace.each_object(::Class).select{|klass| klass < self}
+    end
+
+    # Initializes a new Error object
+    #
+    # @param exception [Exception, String]
+    # @param response_headers [Hash]
+    # @return [Echowrap::Error]
+    def initialize(exception=$!, response_headers={})
+      @rate_limit = Echowrap::RateLimit.new(response_headers)
+      @wrapped_exception = exception
+      exception.respond_to?(:backtrace) ? super(exception.message) : super(exception.to_s)
+    end
+
+    def backtrace
+      @wrapped_exception.respond_to?(:backtrace) ? @wrapped_exception.backtrace : super
+    end
+
+  end
+end

data/lib/echowrap/familiarity.rb

@@ -0,0 +1,8 @@
+require 'echowrap/base'
+
+module Echowrap
+  class Familiarity < Echowrap::Base
+    attr_reader :familiarity, :id, :name
+  end
+end
+

data/lib/echowrap/feed.rb

@@ -0,0 +1,14 @@
+require 'echowrap/base'
+
+module Echowrap
+  class Feed < Echowrap::Base
+    attr_reader :name, :url, :date_posted, :date_found, :id, :summary, :type
+    
+    # @return [Array]
+    def references
+      @references ||= map_collection(Echowrap::Reference, :references)
+    end
+  end
+end
+
+

data/lib/echowrap/foreign_id.rb

@@ -0,0 +1,10 @@
+require 'echowrap/base'
+
+module Echowrap
+  class ForeignId < Echowrap::Base
+    attr_reader :catalog, :foreign_id
+
+  end
+end
+
+

data/lib/echowrap/genre.rb

@@ -0,0 +1,8 @@
+require 'echowrap/base'
+
+module Echowrap
+  class Genre < Echowrap::Base
+    attr_reader :name
+    
+  end
+end

data/lib/echowrap/hotttnesss.rb

@@ -0,0 +1,8 @@
+require 'echowrap/base'
+
+module Echowrap
+  class Hotttnesss < Echowrap::Base
+    attr_reader :hotttnesss, :id, :name
+  end
+end
+

data/lib/echowrap/image.rb

@@ -0,0 +1,15 @@
+require 'echowrap/base'
+
+module Echowrap
+  class Image < Echowrap::Base
+    attr_reader :url
+
+    # @return [Echowrap::License]
+    def license
+      @license ||= Echowrap::License.new(@attrs[:license])
+    end
+
+  end
+end
+
+  

data/lib/echowrap/item.rb

@@ -0,0 +1,95 @@
+require 'echowrap/base'
+
+module Echowrap
+  class Item < Echowrap::Base
+    attr_reader :artist_familiarity, :artist_hotttnesss, :artist_id, :artist_name, 
+                :date_added, :foreign_id, :last_modified, :play_count, :song_hotttnesss, 
+                :song_id, :song_name, :song_type
+
+    # @return [Echowrap::ArtistLocation]
+    def artist_location
+      @artist_location ||= Echowrap::Location.new(@attrs[:artist_location])
+    end
+
+    # @return [Echowrap::AudioSummary]
+    def audio_summary
+      @audio_summary ||= Echowrap::AudioSummary.new(@attrs[:audio_summary])
+    end
+
+    # @return [Array]
+    def biographies
+      @biographies ||= map_collection(Echowrap::Biography, :biographies)
+    end
+
+    # @return [Array]
+    def blogs
+      @blogs ||= map_collection(Echowrap::Blog, :blogs)
+    end
+
+    # @return [Echowrap::DocCounts]
+    def doc_counts
+      @doc_counts ||= Echowrap::DocCounts.new(@attrs[:doc_counts])
+    end
+
+    # @return [Array]
+    def foreign_ids
+      @foreign_ids ||= map_collection(Echowrap::ForeignId, :foreign_ids)
+    end
+
+    # @return [Array]
+    def images
+      @images ||= map_collection(Echowrap::Image, :images)
+    end
+
+    # @return [Echowrap::Location]
+    def location
+      @location ||= Echowrap::Location.new(@attrs[:artist_location])
+    end
+
+    # @return [Array]
+    def news
+      @news ||= map_collection(Echowrap::NewsArticle, :news)
+    end
+    
+    # @return [Echowrap::ItemRequest]
+    def request
+      @request ||= Echowrap::ItemRequest.new(@attrs[:request])
+    end
+
+    # @return [Array]
+    def reviews
+      @reviews ||= map_collection(Echowrap::Review, :reviews)
+    end
+
+    # @return [Array]
+    def songs
+      @songs ||= map_collection(Echowrap::Song, :songs)
+    end
+
+    # @return [Array]
+    def terms
+      @terms ||= map_collection(Echowrap::Term, :terms)
+    end
+
+    # @return [Array]
+    def tracks
+      @tracks ||= map_collection(Echowrap::Track, :tracks)
+    end
+
+    # @return [Echowrap::Urls]
+    def urls
+      @urls ||= Echowrap::Urls.new(@attrs[:urls])
+    end
+
+    # @return [Array]
+    def video
+      @video ||= map_collection(Echowrap::Video, :video)
+    end
+
+    # @return [Array]
+    def years_active
+      @years_active ||= map_collection(Echowrap::YearsActive, :years_active)
+    end
+    
+  end
+end