7digital 0.0.5 → 0.0.6

data/README.rdoc

@@ -1,136 +1,136 @@
-=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
-
-
-	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
-
-
+=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
+
+
+	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
+
+

data/lib/sevendigital.rb

@@ -1,53 +1,53 @@
-
-module Sevendigital
-
-  # :stopdoc:
-  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
-  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
-  # :startdoc:
-
-  # Returns the version string for the library.
-  #
-  def self.version
-    VERSION
-  end
-
-  # Returns the library path for the module. If any arguments are given,
-  # they will be joined to the end of the libray path using
-  # <tt>File.join</tt>.
-  #
-  def self.libpath( *args )
-    args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
-  end
-
-  # Returns the lpath for the module. If any arguments are given,
-  # they will be joined to the end of the path using
-  # <tt>File.join</tt>.
-  #
-  def self.path( *args )
-    args.empty? ? PATH : ::File.join(PATH, args.flatten)
-  end
-
-  # Utility method used to require all files ending in .rb that lie in the
-  # directory below this file that has the same name as the filename passed
-  # in. Optionally, a specific _directory_ name can be passed in such that
-  # the _filename_ does not have to be equivalent to the directory.
-  #
-  def self.require_all_libs_relative_to( fname, dir = nil )
-    dir ||= ::File.basename(fname, '.*')
-    search_me = ::File.expand_path(
-        ::File.join(::File.dirname(fname), dir, '**', '*.rb'))
-
-    Dir.glob(search_me).sort.each {|rb| require rb }
-  end
-
-end  # module 7digital
-
-require 'peachy'
-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')
-Sevendigital.require_all_libs_relative_to(__FILE__)
-
+
+module Sevendigital
+
+  # :stopdoc:
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+  # :startdoc:
+
+  # Returns the version string for the library.
+  #
+  def self.version
+    VERSION
+  end
+
+  # Returns the library path for the module. If any arguments are given,
+  # they will be joined to the end of the libray path using
+  # <tt>File.join</tt>.
+  #
+  def self.libpath( *args )
+    args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
+  end
+
+  # Returns the lpath for the module. If any arguments are given,
+  # they will be joined to the end of the path using
+  # <tt>File.join</tt>.
+  #
+  def self.path( *args )
+    args.empty? ? PATH : ::File.join(PATH, args.flatten)
+  end
+
+  # Utility method used to require all files ending in .rb that lie in the
+  # directory below this file that has the same name as the filename passed
+  # in. Optionally, a specific _directory_ name can be passed in such that
+  # the _filename_ does not have to be equivalent to the directory.
+  #
+  def self.require_all_libs_relative_to( fname, dir = nil )
+    dir ||= ::File.basename(fname, '.*')
+    search_me = ::File.expand_path(
+        ::File.join(::File.dirname(fname), dir, '**', '*.rb'))
+
+    Dir.glob(search_me).sort.each {|rb| require rb }
+  end
+
+end  # module 7digital
+
+require 'peachy'
+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')
+Sevendigital.require_all_libs_relative_to(__FILE__)
+

data/lib/sevendigital/api_operator.rb

@@ -1,125 +1,131 @@
-module Sevendigital
-
-  require 'net/http'
-  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(api_request)
-    puts api_response.content.to_s if @client.very_verbose?
-    api_response
-  end
-
-  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.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)
-    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
-
+module Sevendigital
+
+  require 'net/http'
+  require 'net/https'
+  require 'oauth'
+  require 'uri'
+  require 'cgi'
+
+  #@private
+  #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(api_request)
+    puts api_response.content.to_s if @client.very_verbose?
+    api_response
+  end
+
+  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.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)
+
+    if !api_request.requires_signature? then
+      request_uri.query ||= ""
+      request_uri.query += "&oauth_consumer_key=#{@client.configuration.oauth_consumer_key}"
+    end
+
+    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)
+    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("&")
+    query = nil if query == ""
+    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 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.body = api_request.form_parameters.map {|k, v| "#{escape(k)}=#{escape(v)}" }.flatten.join('&')
+    http_request.content_type = 'application/x-www-form-urlencoded'
+  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 log_request(request)
+    puts "ApiOperator calling #{request.inspect}" if @client.verbose?
+  end
+
+end
+
 end