7digital 0.0.2 → 0.0.5

data/README.rdoc

@@ -1,9 +1,136 @@
-Ruby wrapper for 7digital API 
+=Ruby wrapper for 7digital API
+
+This is a ruby wrapper for the 7digital API.
+
+==About 7digital
+
+7digital.com is an online music store operating in over 16 countries and offering more than 11 million high quality DRM free MP3s (320kbps) from all major labels and wide range of idependent labels and distributors. 7digital API will give you access to the full catalogue including high quality album art, 30s preview clips for all tracks, commissions on sales, integrated purchasing and full length streaming. More details at http://developer.7digital.net
+
+==Installation
+
+	gem install 7digital
+
+==Quick start example
+
 
-Example usage:
 	require "sevendigital"
+	api_client = Sevendigital::Client.new(:oauth_consumer_key => "YOUR_KEY_HERE", :country => "GB")
+	an_artist = api_client.artist.search("radiohead").first
+	a_release = an_artist.releases(:page_size=>100).sort_by{|release| release.year}.last
+	puts "the latest #{an_artist.name} release is #{a_release.title} from #{a_release.year}"
+	puts "go and buy it at #{a_release.url} !"
+
+==Usage details
+
+===Initializing & configuring an API Client
+
+To use the wrapper and access the 7digital API you need a configured instance of Sevendigital::Client. Create one using the standard new method:
+
+	client = Sevendigital::Client.new
+
+This will get you an API client configured with default settings. At very least before making any API calls you will need to update the configuration with your own API key. You can adjust the client's configuration in several ways:
+
+1. In Rails app you can put _sevendigital.yml_ inside your app's config dir and this will be automatically picked up (for a template please see the examples directory)
+
+2. You can provide a custom location of configuration file when instantiating a client
+
+	client = Sevendigital::Client.new("dir/subdir/my_7d_configuration.yml")
+3. You can supply a hash of configuration settings when instantiating a client
+
+	client = Sevendigital::Client.new(:oauth_consumer_key => "YOUR_KEY_HERE", :country => "GB")
+4. You can update the configuration in block whilst instantiating a client
+
+	client = Sevendigital::Client.new { |config|
+		config.oauth_consumer_key => "YOUR_KEY_HERE"
+		config.verbose => true
+	}
+
+You  can also combine all of the above (if the same setting is specified multiple times the last one will be applied)
+An extreme example:
+
+	client = Sevendigital::Client.new("7digital_default_settings.yml", :oauth_consumer_key => "MY_OTHER_KEY") { |conf|
+		conf.country = "SE"
+		conf.oauth_consumer_key = "ACTUALLY_USE_THIS_KEY"
+	}
+
+===Using the client
+
+List of all available API methods and their return types
+
+----
+
+Provided by Sevendigital::ArtistManager :
+
+client.artist.*get_details*(artist_id, options={}) => Sevendigital::Artist
+
+client.artist.*get_releases*(artist_id, options={}) => [ Sevendigital::Release ]
+
+client.artist.*get_similar*(artist_id, options={}) => [ Sevendigital::Artist ]
+
+client.artist.*get_top_by_tag*(tags, options={}) => [ Sevendigital::Artist ]
+
+client.artist.*get_top_tracks*(artist_id, options={}) => [ Sevendigital::Track ]
+
+client.artist.*search*(query, options={}) => [ Sevendigital::Artist ]
+
+----
+
+Provided by Sevendigital::ReleaseManager :
+
+client.release.*get_details*(release_id, options = {})  => Sevendigital::Release
+
+client.release.*get_tracks*(release_id, options = {})  => [ Sevendigital::Track ]
+
+client.release.*get_chart*(options={}) => [ Sevendigital::ChartItem ]
+
+client.release.*get_by_date*(from_date = nil, to_date = nil, options = {}) => [ Sevendigital::Release ]
+
+client.release.*get_recommendations*(release_id, options = {}) => [ Sevendigital::Release ]
+
+client.release.*get_top_by_tag*(tags, options = {}) => [ Sevendigital::Release ]
+
+client.release.*search*(query, options={}) => [ Sevendigital::Release ]
+
+----
+
+client.track.*get_details*(id, options={}) => Sevendigital::Track
+
+client.track.*get_details_from_release*(track_id, release_id, options={}) => Sevendigital::Track
+
+client.track.*get_chart*(options={}) => [ Sevendigital::ChartItem ]
+
+client.track.*build_preview_url*(id, options={}) => String
+
+client.track.*search*(query, options={}) => [ Sevendigital::Track ]
+
+---
+
+client.basket.*get*(basket_id, options={}) => Sevendigital::Basket
+
+client.basket.*create*(options={}) => Sevendigital::Basket
+
+client.basket.*add_item*(basket_id, release_id, track_id=nil, options={}) => Sevendigital::Basket
+
+client.basket.*remove_item*(basket_id, item_id, options={}) => Sevendigital::Basket
+
+---
+
+client.oauth.*get_request_token* => OAuth::RequestToken
+
+client.oauth.*get_access_token*(request_token)  => OAuth::AccessToken
+
+---
+
+client.user.*login*(access_token) => Sevendigital::User
+
+client.user.*authenticate*(email, password) => Sevendigital::User
+
+client.user.*get_locker*(token, options={}) => Sevendgital::Locker
+
+client.user.*purchase*(release_id, track_id, price, token, options={}) => Sevendgital::Locker
+
+client.user.*get_stream_track_url*(release_id, track_id, token, options={}) => String
+
+client.user.*get_add_card_url*(return_url, token, options={}) => String
 
-	sevendigital_client = Sevendigital::Client.new(:oauth_consumer_key => "YOUR_KEY_HERE", :country => "GB")
-	artist = sevendigital_client.artist.get_details(1)
-	puts artist.name
 

data/lib/sevendigital.rb

@@ -2,7 +2,6 @@
 module Sevendigital
 
   # :stopdoc:
-  VERSION = '0.0.1'
   LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
   PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
   # :startdoc:
@@ -45,8 +44,8 @@ module Sevendigital
 end  # module 7digital
 
 require 'peachy'
-require File.join( File.dirname( File.expand_path(__FILE__)), 'sevendigital', 'peachy_patch')
 Peachy.be_quiet
+require File.join( File.dirname( File.expand_path(__FILE__)), 'sevendigital', 'client_configuration')
 require File.join( File.dirname( File.expand_path(__FILE__)), 'sevendigital', 'management', 'manager')
 require File.join( File.dirname( File.expand_path(__FILE__)), 'sevendigital', 'digestion_tract', 'digestor')
 require File.join( File.dirname( File.expand_path(__FILE__)), 'sevendigital', 'model', 'sevendigital_object')

data/lib/sevendigital/api_operator.rb

@@ -1,32 +1,123 @@
 module Sevendigital
 
   require 'net/http'
-  
-  class ApiOperator
+  require 'net/https'
+  require 'oauth'
+  require 'uri'
+  require 'cgi'
+
+  #internal class used for translating ApiRequests into http calls
+  #deals with OAuth signing requests that require signature, making sure parameters are in correct format etc
+  class ApiOperator # :nodoc:
+
+  RESERVED_CHARACTERS = /[^a-zA-Z0-9\-\.\_\~]/
 
   def initialize(client)
     @client = client
   end
 
   def call_api(api_request)
-    api_response = make_http_request_and_digest(create_request_uri(api_request))
-    puts api_response if @client.very_verbose?
+    api_response = make_http_request_and_digest(api_request)
+    puts api_response.content.to_s if @client.very_verbose?
     api_response
   end
 
-  def make_http_request_and_digest(uri)
-    puts "ApiOperator: Calling #{uri}" if @client.verbose?
-    http_response = Net::HTTP.get_response(uri)
+  def get_request_uri(api_request)
+    api_request.signature_scheme = :query_string if api_request.requires_signature?
+    http_client, http_request = create_http_request(api_request)
+    path = http_request.instance_variable_get("@path")
+    host = http_client.instance_variable_get("@address")
+    port = http_client.instance_variable_get("@port")
+    scheme = port == 443 ? "https" : "http"
+    return "#{scheme}://#{host}#{path}"
+  end
+
+  def make_http_request_and_digest(api_request)
+      digest_http_response(make_http_request(api_request))
+  end
+
+  def make_http_request(api_request)
+
+    http_client, http_request = create_http_request(api_request)
+
+    http_client.set_debug_output($stdout) if @client.very_verbose?
+    log_request(http_request) if @client.verbose?
+
+    http_client.request(http_request)
+  end
+
+  def digest_http_response(http_response)
     api_response = @client.api_response_digestor.from_http_response(http_response)
-    raise Sevendigital::SevendigitalError, "#{api_response.error_code} - #{api_response.error_message}" if !api_response.ok?
+    raise Sevendigital::SevendigitalError.new(api_response.error_code, api_response.error_message), "#{api_response.error_code} - #{api_response.error_message}" if !api_response.ok?
     api_response
   end
 
+  def create_http_request(api_request)
+    http_client, http_request = create_standard_http_request(api_request)
+    if (api_request.requires_signature?) then
+      oauth_sign_request(http_client, http_request, api_request)
+    else
+    end
+    return http_client, http_request
+  end
+
+  def oauth_sign_request(http_client, http_request, api_request)
+    http_request.oauth!( \
+    http_client, \
+      @client.oauth_consumer, \
+      api_request.token, \
+      {:scheme => api_request.signature_scheme}
+    )
+    return http_request
+  end
+
+  def create_standard_http_request(api_request)
+    request_uri = create_request_uri(api_request)
+    http_client = Net::HTTP.new(request_uri.host, request_uri.port)
+
+    request_uri.query += '&oauth_consumer_key=' + @client.configuration.oauth_consumer_key unless api_request.requires_signature?
+
+    http_request = new_http_request(request_uri.request_uri, api_request.http_method)
+
+    ensure_secure_connection(http_client) if api_request.requires_secure_connection?
+    add_form_parameters(http_request, api_request)
+
+    return http_client, http_request
+  end
+
+  def ensure_secure_connection(http_client)
+    http_client.use_ssl = true
+    http_client.verify_mode = OpenSSL::SSL::VERIFY_NONE
+  end
+
   def create_request_uri(api_request)
-    api_request.ensure_country_is_set(@client.country)
-    params = api_request.parameters.collect{ |a,v| "&#{a}=#{v}" }.join
-    URI.parse("http://#{@client.configuration.api_url}/#{@client.configuration.api_version}/#{api_request.api_method}"+
-              "?oauth_consumer_key=#{@client.configuration.oauth_consumer_key}#{params}")
+    host, version = @client.api_host_and_version(api_request.api_service)
+    path = "/#{version}/#{api_request.api_method}"
+    query = api_request.parameters.map{ |k,v| "#{escape(k)}=#{escape(v)}" }.join("&")
+    if api_request.requires_secure_connection? then
+      URI::HTTPS.build(:host => host, :path => path, :query =>query)
+    else
+      URI::HTTP.build(:host => host, :path => path, :query =>query)
+    end
+  end
+
+  def escape(value)
+    URI::escape(value.to_s, RESERVED_CHARACTERS)
+    rescue ArgumentError
+      URI::escape(value.to_s.force_encoding(Encoding::UTF_8), RESERVED_CHARACTERS)
+  end
+
+  def new_http_request(request_uri, http_method)
+    request_type = Kernel.const_get("Net").const_get("HTTP").const_get(http_method.to_s.capitalize)
+    request_type.new(request_uri, {"user-agent" => @client.user_agent_info})
+  end
+
+  def add_form_parameters(http_request, api_request)
+    http_request.set_form_data(api_request.form_parameters)
+  end
+
+  def log_request(request)
+    puts "ApiOperator: Calling #{request.inspect}"
   end
 
 end

data/lib/sevendigital/api_operator_cached.rb

@@ -1,6 +1,10 @@
 module Sevendigital
 
-class ApiOperatorCached < ApiOperator
+#Cached version of ApiOperator
+#If response for an API request is already in cache and
+#and it hasn't expired returns the cached response is returned instead of making an API call
+#otherwise uses methods inherited from ApiOperator to make an HTTP call to the API
+class ApiOperatorCached < ApiOperator # :nodoc:
 
   def initialize(client, cache)
     @cache = cache
@@ -8,16 +12,18 @@ class ApiOperatorCached < ApiOperator
   end
 
   def call_api(api_request)
-    uri = create_request_uri(api_request)
-    api_response = @cache.get(uri.to_s)
-    puts "ApiOperatorCached: Got from cache #{uri}" if api_response if @client.verbose?
-    if (!api_response) then
-      api_response = make_http_request_and_digest(uri)
-      @cache.set(uri.to_s, api_response)
+    request_cache_key = create_request_uri(api_request)
+    api_response = @cache.get(request_cache_key.to_s) if !api_request.requires_signature?
+    puts "ApiOperatorCached: Got from cache #{request_cache_key}" if @client.verbose? && api_response
+    puts "but the response is out of date" if @client.verbose? && api_response && api_response.out_of_date?
+    if (!api_response || api_response.out_of_date?) then
+      api_response = make_http_request_and_digest(api_request)
+      @cache.set(request_cache_key.to_s, api_response) if !api_request.requires_signature?
     end
-    puts api_response if @client.very_verbose?    
+    p api_response if @client.very_verbose?
     api_response
   end
+
 end
 
 end

data/lib/sevendigital/api_request.rb

@@ -1,24 +1,65 @@
 module Sevendigital
 
-class ApiRequest
+#Abstraction of a HTTP API request, ApiOperator uses this ApiRequest to build a real HTTP requests
+class ApiRequest # :nodoc:
 
-  attr_reader :api_method, :parameters
+  attr_reader :api_method, :parameters, :signed
+  attr_accessor :token, :api_service, :http_method
+  attr_accessor :signature_scheme
+  attr_writer :form_parameters
 
-  def initialize(api_method, parameters, options = {})
+  def initialize(api_method, parameters, options={})
     @api_method = api_method
-    @parameters = comb_parameters(options.merge(parameters))
+    @parameters = parameters
+    @signature_scheme = :header
+    @http_method = :GET
+    comb_parameters(parameters)
+    @form_parameters = Hash.new
+  end
+
+  def form_parameters
+    comb_parameters(@form_parameters)
+  end
+
+  def requires_signature?
+    @signed == true
+  end
+
+  def require_signature
+    @signed = true
+  end
+
+  def requires_secure_connection?
+    @secure == true
+  end
+
+  def require_secure_connection
+    @secure = true
   end
 
   def comb_parameters(parameters)
-    page_size = parameters[:page_size] || parameters[:per_page]
-    parameters[:pageSize] ||= page_size if page_size
-    return parameters
+    comb_parameter(parameters, :pageSize, [:page_size, :per_page])
+    comb_parameter(parameters, :shopId, :shop_id)
+    comb_parameter(parameters, :imageSize, :image_size)
+    remove_empty_parameters(parameters)
+    parameters
   end
 
-  def ensure_country_is_set(country)
-    @parameters[:country] ||= country
+  def comb_parameter(parameters, correct_name, alternative_names)
+    param_value = nil
+    alternative_names = [alternative_names] unless alternative_names.is_a?(Array)
+    alternative_names.each do |alternative_name|
+      param_value ||= parameters[alternative_name]
+      parameters.delete(alternative_name)
+    end
+    parameters[correct_name] ||= param_value if param_value
   end
 
+  def remove_empty_parameters(parameters)
+    parameters.delete_if { |key, value| value.nil? }
+  end
+
+
 end
 
 end

data/lib/sevendigital/client.rb

@@ -1,108 +1,82 @@
-require 'ostruct'
-require 'yaml'
-
-
 module Sevendigital
 
-  DEFAULT_CONFIGURATION = {
-      :api_url =>  "api.7digital.com",
-      :api_version => "1.2"
-    }
-
   class Client
 
-  def load_configuration_from_yml(file_name, environment=nil)
-    plain_settings = YAML.load_file(file_name)
-    if (plain_settings["common"] || (environment && plain_settings[environment])) then
-      environment_settings = plain_settings["common"] || {}
-      environment_settings.update(plain_settings[environment]) if environment
-      environment_settings
-    else
-      plain_settings
-    end
-  end
-
-  def load_configurations(configuration)
-    
-    default_settings = Sevendigital::DEFAULT_CONFIGURATION
+  COMMON_REQUEST_PARAMETERS = [:shop_id, :country, :page, :page_size, :image_size]
 
-    if (configuration.kind_of? String) then
-      yml_configuration_file = configuration
-    else
-      yml_configuration_file ="#{RAILS_ROOT}/config/sevendigital.yml" if defined?(RAILS_ROOT)
-      explicit_settings = configuration if configuration.kind_of? Hash
-      explicit_settings = configuration.marshal_dump if configuration.kind_of? OpenStruct
+    def initialize(*args)
+      @configuration = Sevendigital::ClientConfiguration.new(*args)
+      yield @configuration if block_given?
+      @api_operator = hire_api_operator
     end
 
-    environment = defined?(RAILS_ENV) ? RAILS_ENV  : nil
-    yml_settings = load_configuration_from_yml(yml_configuration_file, environment) if yml_configuration_file
-  
-    settings = default_settings
-    settings.update(yml_settings) if yml_settings
-    settings.update(explicit_settings) if explicit_settings
-
-    return OpenStruct.new(settings)
-  end
-
-  #Code here
-
-    def initialize(configuration=nil, api_operator=nil)
-      @configuration = load_configurations(configuration)
-      @api_operator = api_operator || hire_api_operator
+    def default_parameters
+      params = {}
+      COMMON_REQUEST_PARAMETERS.each do |param|
+        value = @configuration.send(param)
+        params[param] = value if value
+      end
+      params
     end
   
     def hire_api_operator
        @configuration.cache ? ApiOperatorCached.new(self, @configuration.cache) : ApiOperator.new(self)
     end
 
-    def artist
-      @artist_manager ||= ArtistManager.new(self) 
+    def user_agent_info
+      app_info = @configuration.app_name ? "/#{@configuration.app_name}" : nil
+      app_info += " #{@configuration.app_version}" if app_info && @configuration.app_version
+      "#{Sevendigital::NAME} Gem #{Sevendigital::VERSION}#{app_info}"
     end
 
-    def artist_digestor
-      @artist_digestor ||= ArtistDigestor.new(self)
-    end
-    
-    def release
-      @release_manager ||= ReleaseManager.new(self)
+    def create_api_request(api_method, parameters, options = {})
+      parameters = options.merge(parameters)
+      parameters = add_default_parameters(parameters)
+      ApiRequest.new(api_method, parameters)
     end
 
-    def release_digestor
-      @release_digestor ||= ReleaseDigestor.new(self)
+    def make_api_request(api_method, parameters, options = {})
+      api_request = create_api_request(api_method, parameters, options)
+      operator.call_api(api_request)
     end
 
-    def label_digestor
-      @label_digestor ||= LabelDigestor.new(self)
-    end
+    def make_signed_api_request(api_method, parameters, options = {}, token = nil)
+      api_request = create_api_request(api_method, parameters, options)
+      api_request.require_signature
+      api_request.require_secure_connection
+      api_request.token = token
 
-    def format_digestor
-      @format_digestor ||= FormatDigestor.new(self)
-    end
-    
-    def price_digestor
-      @price_digestor ||= PriceDigestor.new(self)
+      operator.call_api(api_request)
     end
 
-    def pager_digestor
-      @pager_digestor ||= PagerDigestor.new(self)
+    def add_default_parameters(parameters)
+      params = parameters
+      default_parameters.each do |name, value|
+        params[name] ||= value
+      end
+      params
     end
 
-    def track
-      @track_manager ||= TrackManager.new(self)
+    def api_host_and_version(api_service=nil)
+       service = api_service && !api_service.to_s.empty? ? "#{api_service}_" : ""
+       return configuration.send("#{service}api_url".to_sym), configuration.send("#{service}api_version".to_sym)
     end
 
-    def track_digestor
-      @track_digestor ||= TrackDigestor.new(self)
-    end
+    def oauth_consumer
+      host, version = api_host_and_version(:account)
 
-    def api_response_digestor
-      @api_response_digestor ||= ApiResponseDigestor.new(self)
-    end
-    
-    def chart_item_digestor
-      @chart_item_digestor ||= ChartItemDigestor.new(self)
+      consumer_options = {
+        :authorize_path     => "https://#{host}/#{version}/oauth/authorise",
+        :http_method   => :get
+      }
+
+      @oauth_consumer ||= OAuth::Consumer.new( \
+              @configuration.oauth_consumer_key, \
+              @configuration.oauth_consumer_secret, \
+              consumer_options \
+      )
     end
-    
+
     def configuration
       return @configuration
     end
@@ -111,14 +85,6 @@ module Sevendigital
       @api_operator
     end
 
-    def country
-      @country || @configuration.country
-    end
-
-    def country=(country_code)
-      @country = country_code
-    end
-
     def verbose?
       !(@verbose || @configuration.verbose).nil?
     end
@@ -127,10 +93,6 @@ module Sevendigital
       verbose? && (@verbose || @configuration.verbose).to_s == "very_verbose"
     end
 
-    def verbose=(verbosity)
-      @verbose = verbosity
-    end
-
   end
 
 end