soundcloud 0.3.1 → 0.3.2

data/README.md

@@ -1,155 +1,170 @@
-# Soundcloud API Wrapper
-## Description
-The Soundcloud gem is a thin wrapper for the Soundcloud API based off of the httparty gem.
-It provides simple methods to handle authorization and to execute HTTP calls.
+# SoundCloud API Wrapper
+
+[![Build Status](https://travis-ci.org/soundcloud/soundcloud-ruby.png?branch=master)](https://travis-ci.org/soundcloud/soundcloud-ruby)
 
-## Requirements
-* httmultiparty
-* httparty
-* crack
-* multipart-upload
-* hashie
+## Description
+The official SoundCloud API wrapper. It provides simple methods to handle
+authorization and to execute HTTP calls.
 
 ## Installation
-    gem install soundcloud
+```sh
+gem install soundcloud
+```
 
 ## Examples
 #### Print links of the 10 hottest tracks
-    # register a client with YOUR_CLIENT_ID as client_id_
-    client = Soundcloud.new(:client_id => YOUR_CLIENT_ID)
-    # get 10 hottest tracks
-    tracks = client.get('/tracks', :limit => 10, :order => 'hotness')
-    # print each link
-    tracks.each do |track|
-      puts track.permalink_url
-    end
-  
+```ruby
+# register a client with YOUR_CLIENT_ID as client_id_
+client = SoundCloud.new(:client_id => YOUR_CLIENT_ID)
+# get 10 hottest tracks
+tracks = client.get('/tracks', :limit => 10, :order => 'hotness')
+# print each link
+tracks.each do |track|
+  puts track.permalink_url
+end
+```
+
 #### OAuth2 user credentials flow and print the username of the authenticated user
-    # register a new client, which will exchange the username, password for an access_token
-    # NOTE: the SoundCloud API Docs advise not to use the user credentials flow in a web app.
-    # In any case, never store the password of a user.
-    client = Soundcloud.new({
-      :client_id      => YOUR_CLIENT_ID,
-      :client_secret  => YOUR_CLIENT_SECRET,
-      :username       => 'some@email.com',
-      :password       => 'userpass'
-    })
-    
-    # print logged in username
-    puts client.get('/me').username
+```ruby
+# register a new client, which will exchange the username, password for an access_token
+# NOTE: the SoundCloud API Docs advise not to use the user credentials flow in a web app.
+# In any case, never store the password of a user.
+client = SoundCloud.new({
+  :client_id     => YOUR_CLIENT_ID,
+  :client_secret => YOUR_CLIENT_SECRET,
+  :username      => 'some@email.com',
+  :password      => 'userpass'
+})
+
+# print logged in username
+puts client.get('/me').username
+```
 
 #### OAuth2 authorization code flow
-    client = Soundcloud.new({
-      :client_id      => YOUR_CLIENT_ID,
-      :client_secret  => YOUR_CLIENT_SECRET,
-      :redirect_uri  => YOUR_REDIRECT_URI,
-    })
-    
-    redirect client.authorize_url()
-    # the user should be redirected to "https://soundcloud.com/connect?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=YOUR_REDIRECT_URI"
-    # after granting access he will be redirected back to YOUR_REDIRECT_URI
-    # in your respective handler you can build an exchange token from the transmitted code
-    client.exchange_token(:code => params[:code])
+```ruby
+client = SoundCloud.new({
+  :client_id     => YOUR_CLIENT_ID,
+  :client_secret => YOUR_CLIENT_SECRET,
+  :redirect_uri  => YOUR_REDIRECT_URI,
+})
+
+redirect client.authorize_url()
+# the user should be redirected to "https://soundcloud.com/connect?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=YOUR_REDIRECT_URI"
+# after granting access he will be redirected back to YOUR_REDIRECT_URI
+# in your respective handler you can build an exchange token from the transmitted code
+client.exchange_token(:code => params[:code])
+```
 
 #### OAuth2 refresh token flow, upload a track and print its link
-    # register a new client which will exchange an existing refresh_token for an access_token
-    client = Soundcloud.new({
-      :client_id      => YOUR_CLIENT_ID,
-      :client_secret  => YOUR_CLIENT_SECRET,
-      :refresh_token  => SOME_REFRESH_TOKEN
-    })
-    
-    # upload a new track with track.mp3 as audio and image.jpg as artwork
-    track = client.post('/tracks', :track => {
-      :title        => 'a new track',
-      :asset_data   => File.new('audio.mp3')
-    })
-    
-    # print new tracks link
-    puts track.permalink_url
+```ruby
+# register a new client which will exchange an existing refresh_token for an access_token
+client = SoundCloud.new({
+  :client_id     => YOUR_CLIENT_ID,
+  :client_secret => YOUR_CLIENT_SECRET,
+  :refresh_token => SOME_REFRESH_TOKEN
+})
+
+# upload a new track with track.mp3 as audio and image.jpg as artwork
+track = client.post('/tracks', :track => {
+  :title      => 'a new track',
+  :asset_data => File.new('audio.mp3')
+})
+
+# print new tracks link
+puts track.permalink_url
+```
 
 #### Resolve a track url and print its id
-     # register the client
-     client = Soundcloud.new(:client_id => YOUR_CLIENT_ID)
-     
-     # call the resolve endpoint with a track url
-     track = client.get('/resolve', :url => "http://soundcloud.com/forss/flickermood")
-     
-     # print the track id
-     puts track.id
-
-#### Register a client for http://sandbox-soundcloud.com with an existing access_token and start following a user
-    # register a client for http://sandbox-soundcloud.com with existing access_token
-    client = Soundcloud.new(:site => 'sandbox-soundcloud.com', :access_token => SOME_ACCESS_TOKEN)
-    
-    # create a new following
-    user_id_to_follow = 123
-    client.put("/me/followings/#{user_id_to_follow}")
+```ruby
+# register the client
+client = SoundCloud.new(:client_id => YOUR_CLIENT_ID)
+
+# call the resolve endpoint with a track url
+track = client.get('/resolve', :url => "http://soundcloud.com/forss/flickermood")
+
+# print the track id
+puts track.id
+```
 
 ### Initializing a client with an access token and updating the users profile description
-    # initializing a client with an access token
-    client = Soundcloud.new(:access_token => SOME_ACCESS_TOKEN)
-    
-    # updating the users profile description
-    client.put("/me", :user => {:description => "a new description"})
-
-
-### Add a track to a playlist / set 
-    client = Soundcloud.new(:access_token => "A_VALID_TOKEN")
-    
-    # get my last playlist
-    playlist = client.get("/me/playlists").first
-    
-    # get ids of contained tracks
-    track_ids = playlist.tracks.map(&:id) # => [22448500, 21928809] 
-    
-    # adding a new track 21778201
-    track_ids << 21778201 # => [22448500, 21928809, 21778201]
-    
-    # map array of ids to array of track objects:
-    tracks = track_ids.map { |id| {:id => id} } # => [{:id=>22448500}, {:id=>21928809}, {:id=>21778201}]
-    
-    # send update/put request to playlist
-    playlist = client.put(playlist.uri, :playlist => {
-      :tracks => tracks
-    })
-    
-    # print the list of track ids of the updated playlist:
-    p playlist.tracks.map(&:id)
+```ruby
+# initializing a client with an access token
+client = SoundCloud.new(:access_token => SOME_ACCESS_TOKEN)
+
+# updating the users profile description
+client.put("/me", :user => {:description => "a new description"})
+```
+
+### Add a track to a playlist / set
+```ruby
+client = SoundCloud.new(:access_token => "A_VALID_TOKEN")
+
+# get my last playlist
+playlist = client.get("/me/playlists").first
+
+# get ids of contained tracks
+track_ids = playlist.tracks.map(&:id) # => [22448500, 21928809]
+
+# adding a new track 21778201
+track_ids << 21778201 # => [22448500, 21928809, 21778201]
+
+# map array of ids to array of track objects:
+tracks = track_ids.map{|id| {:id => id}} # => [{:id=>22448500}, {:id=>21928809}, {:id=>21778201}]
+
+# send update/put request to playlist
+playlist = client.put(playlist.uri, :playlist => {
+  :tracks => tracks
+})
+
+# print the list of track ids of the updated playlist:
+p playlist.tracks.map(&:id)
+```
 
 ## Interface
-#### Soundcloud.new(options={})
-Stores the passed options and call exchange_token in case options are passed that allow an exchange of tokens.
-
-#### Soundcloud#exchange_token(options={})
-Stores the passed options and try to exchange tokens if no access_token is present and:
-- refresh_token, client_id and client_secret is present.
-- client_id, client_secret, username, password is present
-- client_id, client_secret, redirect_uri, code is present
-
-#### Soundcloud#authorize_url(options={})
-Stores the passed options except for ``state`` and ``display`` and return an authorize url.
-The ``client_id`` and ``redirect_uri`` options need to present to generate the authorize url.
-The ``state`` and ``display`` options can be used to set the parameters accordingly in the authorize url.
-
-#### Soundcloud#get, Soundcloud#post, Soundcloud#put, Soundcloud#delete, Soundcloud#head
-These methods expose all available HTTP methods. They all share the signature (path_or_uri, query={}, options={}).
-The query hash will be merged with the options hash and passed to httparty. Depending on if the client is authorized it will either add the client_id or the access_token as a query parameter.
-In case an access_token is expired and a refresh_token, client_id and client_secret is present it will try to refresh the access_token and retry the call.
-The response is either a Hashie::Mash or an array of Hashie::Mashs. The mashs expose all resource attributes as methods and the original response through #response.
-
-#### Soundcloud#client_id, client_secret, access_token, refresh_token, use_ssl?
+#### SoundCloud.new(options={})
+Stores the passed options and call exchange_token in case options are passed
+that allow an exchange of tokens.
+
+#### SoundCloud#exchange_token(options={})
+Stores the passed options and try to exchange tokens if no access_token is
+present and:
+
+* `refresh_token`, `client_id` and `client_secret` is present.
+* `client_id`, `client_secret`, `username`, and `password` is present
+* `client_id`, `client_secret`, `redirect_uri`, and `code` is present
+
+#### SoundCloud#authorize_url(options={})
+Stores the passed options except for `state` and `display` and return an
+authorize url. The `client_id` and `redirect_uri` options need to present to
+generate the authorize url. The `state` and `display` options can be used to
+set the parameters accordingly in the authorize url.
+
+#### SoundCloud#get, SoundCloud#post, SoundCloud#put, SoundCloud#delete, SoundCloud#head
+These methods expose all available HTTP methods. They all share the signature
+`(path_or_uri, query={}, options={})`. The query hash will be merged with the
+options hash and passed to httparty. Depending on if the client is authorized
+it will either add the client_id or the access_token as a query parameter. In
+case an access_token is expired and a `refresh_token`, `client_id` and
+`client_secret` is present it will try to refresh the `access_token` and retry
+the call. The response is either a Hashie::Mash or an array of Hashie::Mashes.
+The mashes expose all resource attributes as methods and the original response
+through `HashResponseWrapper#response`.
+
+#### SoundCloud#client_id, client_secret, access_token, refresh_token, use_ssl?
 These methods are accessors for the stored options.
 
-### Soundcloud#on_exchange_token
-A Proc passed to on_exchange_token will be called each time a token was successfully exchanged or refreshed
+#### SoundCloud#on_exchange_token
+A Proc passed to on_exchange_token will be called each time a token was
+successfully exchanged or refreshed
 
-### Soundcloud#expires_at
-Returns a date based on the expires_in attribute returned from a token exchange.
+#### SoundCloud#expires_at
+Returns a date based on the `expires_in` attribute returned from a token
+exchange.
 
-### Soundcloud#expired?
-Will return true or false depending on if expires_at is in the past.
+#### SoundCloud#expired?
+Will return true or false depending on if `expires_at` is in the past.
 
 #### Error Handling
-In case a request was not successful a Soundcloud::ResponseError will be raised.
-The original HTTParty response is available through Soundcloud::ResponseError#response.
+In case a request was not successful a SoundCloud::ResponseError will be
+raised. The original HTTParty response is available through
+`SoundCloud::ResponseError#response`.

data/lib/soundcloud.rb

@@ -1,217 +1,31 @@
-require 'httmultiparty'
 require 'hashie'
+require 'httmultiparty'
 require 'uri'
-require 'soundcloud/version'
-
-class Soundcloud
-  class ResponseError < HTTParty::ResponseError
-    def message
-      error = response.parsed_response['error'] || response.parsed_response['errors']['error']
-      "HTTP status: #{StatusCodes.interpret_status(response.code)} Error: #{error}"
-    rescue
-      "HTTP status: #{StatusCodes.interpret_status(response.code)}"
-    end
-
-    module StatusCodes
-      STATUS_CODES = {
-        100 => "Continue",
-        101 => "Switching Protocols",
-        102 => "Processing",
-
-        200 => "OK",
-        201 => "Created",
-        202 => "Accepted",
-        203 => "Non-Authoritative Information",
-        204 => "No Content",
-        205 => "Reset Content",
-        206 => "Partial Content",
-        207 => "Multi-Status",
-        226 => "IM Used",
-
-        300 => "Multiple Choices",
-        301 => "Moved Permanently",
-        302 => "Found",
-        303 => "See Other",
-        304 => "Not Modified",
-        305 => "Use Proxy",
-        307 => "Temporary Redirect",
-
-        400 => "Bad Request",
-        401 => "Unauthorized",
-        402 => "Payment Required",
-        403 => "Forbidden",
-        404 => "Not Found",
-        405 => "Method Not Allowed",
-        406 => "Not Acceptable",
-        407 => "Proxy Authentication Required",
-        408 => "Request Timeout",
-        409 => "Conflict",
-        410 => "Gone",
-        411 => "Length Required",
-        412 => "Precondition Failed",
-        413 => "Request Entity Too Large",
-        414 => "Request-URI Too Long",
-        415 => "Unsupported Media Type",
-        416 => "Requested Range Not Satisfiable",
-        417 => "Expectation Failed",
-        422 => "Unprocessable Entity",
-        423 => "Locked",
-        424 => "Failed Dependency",
-        426 => "Upgrade Required",
-
-        500 => "Internal Server Error",
-        501 => "Not Implemented",
-        502 => "Bad Gateway",
-        503 => "Service Unavailable",
-        504 => "Gateway Timeout",
-        505 => "HTTP Version Not Supported",
-        507 => "Insufficient Storage",
-        510 => "Not Extended"
-      }
-
-      def self.interpret_status(status)
-        "#{status} #{STATUS_CODES[status.to_i]}".strip
-      end
-    end
-  end
-
-  class UnauthorizedResponseError < ResponseError; end
-  USER_AGENT            = "SoundCloud Ruby Wrapper #{VERSION}"
-
-  include HTTMultiParty
-  CLIENT_ID_PARAM_NAME  = :client_id
-  API_SUBHOST           = 'api'
-  AUTHORIZE_PATH        = '/connect'
-  TOKEN_PATH            = '/oauth2/token'
-  DEFAULT_OPTIONS       = {
-    :site              => 'soundcloud.com',
-    :on_exchange_token => lambda {}
-  }
-
-  attr_accessor :options
-  headers({"User-Agent" => USER_AGENT})
-
-  def initialize(options={})
-    store_options(options)
-    if access_token.nil? && (options_for_refresh_flow_present? ||
-                             options_for_credentials_flow_present? || options_for_code_flow_present?)
-      exchange_token
-    end
-
-    raise ArgumentError, "At least a client_id or an access_token must be present" if client_id.nil? && access_token.nil?
-  end
-
-  def get   (path, query={}, options={}); handle_response { self.class.get(    *construct_query_arguments(path, options.merge(:query => query)) ) } end
-  def post  (path, body={},  options={}); handle_response { self.class.post(   *construct_query_arguments(path, options.merge(:body  => body), :body) ) } end
-  def put   (path, body={},  options={}); handle_response { self.class.put(    *construct_query_arguments(path, options.merge(:body  => body), :body) ) } end
-  def delete(path, query={}, options={}); handle_response { self.class.delete( *construct_query_arguments(path, options.merge(:query => query)) ) } end
-  def head  (path, query={}, options={}); handle_response { self.class.head(   *construct_query_arguments(path, options.merge(:query => query)) ) } end
-
-  # accessors for options
-  def client_id;      @options[:client_id];     end
-  def client_secret;  @options[:client_secret]; end
-  def access_token;   @options[:access_token];  end
-  def refresh_token;  @options[:refresh_token]; end
-  def redirect_uri;   @options[:redirect_uri];  end
-  def expires_at;     @options[:expires_at];    end
 
-  def expired?
-    (expires_at.nil? || expires_at < Time.now)
-  end
-
-  def use_ssl?;
-    !! @options[:use_ssl?] || access_token
-  end
-
-  def site; @options[:site]; end
-
-  def host; site; end
-  def api_host; [API_SUBHOST, host].join('.'); end
-
-  def authorize_url(options={})
-    additional_params = [:display, :state, :scope].map do |param_name|
-      value = options.delete(param_name)
-      "#{param_name}=#{CGI.escape value}" unless value.nil?
-    end.compact.join("&")
-
-    store_options(options)
-    "https://#{host}#{AUTHORIZE_PATH}?response_type=code_and_token&client_id=#{client_id}&redirect_uri=#{URI.escape redirect_uri}&#{additional_params}"
-  end
+require 'soundcloud/array_response_wrapper'
+require 'soundcloud/client'
+require 'soundcloud/hash_response_wrapper'
+require 'soundcloud/response_error'
+require 'soundcloud/version'
 
-  def exchange_token(options={})
-    store_options(options)
-    raise ArgumentError, 'client_id and client_secret is required to retrieve an access_token' if client_id.nil? || client_secret.nil?
-    client_params = {:client_id => client_id, :client_secret => client_secret}
-    params = if options_for_refresh_flow_present?
-      {:grant_type => 'refresh_token',      :refresh_token => refresh_token}
-    elsif options_for_credentials_flow_present?
-      {:grant_type => 'password',           :username      => @options[:username],     :password => @options[:password]}
-    elsif options_for_code_flow_present?
-      {:grant_type => 'authorization_code', :redirect_uri  => @options[:redirect_uri], :code => @options[:code]}
-    end
-    params.merge!(client_params)
-    response = handle_response(false) {
-      self.class.post("https://#{api_host}#{TOKEN_PATH}", :query => params)
-    }
-    @options.merge!(:access_token => response.access_token, :refresh_token => response.refresh_token)
-    @options[:expires_at] = Time.now + response.expires_in if response.expires_in
-    @options[:on_exchange_token].call(*[(self if @options[:on_exchange_token].arity == 1)].compact)
-    response
-  end
+module SoundCloud
 
-  def on_exchange_token(&block)
-    store_options(:on_exchange_token => block)
+  def new(options={})
+    Client.new(options)
   end
+  module_function :new
 
-private
-  def handle_response(refreshing_enabled=true, &block)
-    response = block.call
-    if response && !response.success?
-      if response.code == 401 && refreshing_enabled && options_for_refresh_flow_present?
-        exchange_token
-        # TODO it should return the original
-        handle_response(false, &block)
-      else
-        raise ResponseError.new(response)
-      end
-    elsif response.is_a? Hash
-      HashResponseWrapper.new(response)
-    elsif response.is_a? Array
-      ArrayResponseWrapper.new(response)
-    elsif response && response.success?
-      response
-    end
+  def method_missing(method_name, *args, &block)
+    return super unless respond_to_missing?(method_name)
+    Client.send(method_name, *args, &block)
   end
+  module_function :method_missing
 
-  def options_for_refresh_flow_present?;     !! @options[:refresh_token]; end
-  def options_for_credentials_flow_present?; !! @options[:username] && @options[:password]; end
-  def options_for_code_flow_present?;        !! @options[:code] && @options[:redirect_uri]; end
-
-  def store_options(options={})
-    @options ||= DEFAULT_OPTIONS.dup
-    @options.merge! options
+  def respond_to_missing?(method_name, include_private=false)
+    Client.respond_to?(method_name, include_private)
   end
+  module_function :respond_to_missing?
 
-
-  def construct_query_arguments(path_or_uri, options={}, body_or_query=:query)
-    uri = URI.parse(path_or_uri)
-    path = uri.path
-
-    scheme = use_ssl? ? 'https' : 'http'
-    options = options.dup
-    options[body_or_query] ||= {}
-    options[body_or_query][:format] = "json"
-    if access_token
-      options[body_or_query][:oauth_token] = access_token
-    else
-      options[body_or_query][CLIENT_ID_PARAM_NAME] = client_id
-    end
-    [
-      "#{scheme}://#{api_host}#{path}#{uri.query ? "?#{uri.query}" : ""}",
-      options
-    ]
-  end
 end
 
-require 'soundcloud/array_response_wrapper'
-require 'soundcloud/hash_response_wrapper'
+Soundcloud = SoundCloud

data/lib/soundcloud/array_response_wrapper.rb

@@ -1,8 +1,12 @@
-class Soundcloud::ArrayResponseWrapper < Array
-  attr_reader :response
-  def initialize(response=[])
-    mashes = response.map { |o| Hashie::Mash.new(o) }
-    self.replace(mashes)
-    @response = response
+module SoundCloud
+  class ArrayResponseWrapper < Array
+    attr_reader :response
+    def initialize(response=[])
+      @response = response
+      mashes = response.map do |object|
+        Hashie::Mash.new(object)
+      end
+      replace(mashes)
+    end
   end
-end
+end

data/lib/soundcloud/client.rb

@@ -0,0 +1,199 @@
+module SoundCloud
+  class Client
+    include HTTMultiParty
+    USER_AGENT            = "SoundCloud Ruby Wrapper #{VERSION}"
+    CLIENT_ID_PARAM_NAME  = :client_id
+    API_SUBHOST           = 'api'
+    AUTHORIZE_PATH        = '/connect'
+    TOKEN_PATH            = '/oauth2/token'
+    DEFAULT_OPTIONS       = {
+      :site              => 'soundcloud.com',
+      :on_exchange_token => lambda {}
+    }
+
+    attr_accessor :options
+    headers({"User-Agent" => USER_AGENT})
+
+    def initialize(options={})
+      store_options(options)
+      if access_token.nil? && (options_for_refresh_flow_present? || options_for_credentials_flow_present? || options_for_code_flow_present?)
+        exchange_token
+      end
+      raise ArgumentError, "At least a client_id or an access_token must be present" if client_id.nil? && access_token.nil?
+    end
+
+    def get(path, query={}, options={})
+      handle_response {
+        self.class.get(*construct_query_arguments(path, options.merge(:query => query)))
+      }
+    end
+
+    def post(path, body={},  options={})
+      handle_response {
+        self.class.post(*construct_query_arguments(path, options.merge(:body => body), :body))
+      }
+    end
+
+    def put(path, body={},  options={})
+      handle_response {
+        self.class.put(*construct_query_arguments(path, options.merge(:body => body), :body))
+      }
+    end
+
+    def delete(path, query={}, options={})
+      handle_response {
+        self.class.delete(*construct_query_arguments(path, options.merge(:query => query)))
+      }
+    end
+
+    def head(path, query={}, options={})
+      handle_response {
+        self.class.head(*construct_query_arguments(path, options.merge(:query => query)))
+      }
+    end
+
+    # accessors for options
+    def client_id
+      @options[:client_id]
+    end
+
+    def client_secret
+      @options[:client_secret]
+    end
+
+    def access_token
+      @options[:access_token]
+    end
+
+    def refresh_token
+      @options[:refresh_token]
+    end
+
+    def redirect_uri
+      @options[:redirect_uri]
+    end
+
+    def expires_at
+      @options[:expires_at]
+    end
+
+    def expired?
+      (expires_at.nil? || expires_at < Time.now)
+    end
+
+    def use_ssl?
+      !!(@options[:use_ssl?] || access_token)
+    end
+
+    def site
+      @options[:site]
+    end
+    alias host site
+
+    def api_host
+      [API_SUBHOST, host].join('.')
+    end
+
+    def authorize_url(options={})
+      additional_params = [:display, :state, :scope].map do |param_name|
+        value = options.delete(param_name)
+        "#{param_name}=#{CGI.escape value}" unless value.nil?
+      end.compact.join("&")
+      store_options(options)
+      "https://#{host}#{AUTHORIZE_PATH}?response_type=code_and_token&client_id=#{client_id}&redirect_uri=#{URI.escape(redirect_uri)}&#{additional_params}"
+    end
+
+    def exchange_token(options={})
+      store_options(options)
+      raise ArgumentError, 'client_id and client_secret is required to retrieve an access_token' if client_id.nil? || client_secret.nil?
+      client_params = {:client_id => client_id, :client_secret => client_secret}
+      params = if options_for_refresh_flow_present?
+        {
+          :grant_type => 'refresh_token',
+          :refresh_token => refresh_token,
+        }
+      elsif options_for_credentials_flow_present?
+        {
+          :grant_type => 'password',
+          :username => @options[:username],
+          :password => @options[:password],
+        }
+      elsif options_for_code_flow_present?
+        {
+          :grant_type => 'authorization_code',
+          :redirect_uri => @options[:redirect_uri],
+          :code => @options[:code],
+        }
+      end
+      params.merge!(client_params)
+      response = handle_response(false) {
+        self.class.post("https://#{api_host}#{TOKEN_PATH}", :query => params)
+      }
+      @options.merge!(:access_token => response.access_token, :refresh_token => response.refresh_token)
+      @options[:expires_at] = Time.now + response.expires_in if response.expires_in
+      @options[:on_exchange_token].call(*[(self if @options[:on_exchange_token].arity == 1)].compact)
+      response
+    end
+
+    def on_exchange_token(&block)
+      store_options(:on_exchange_token => block)
+    end
+
+  private
+
+    def handle_response(refreshing_enabled=true, &block)
+      response = block.call
+      if response && !response.success?
+        if response.code == 401 && refreshing_enabled && options_for_refresh_flow_present?
+          exchange_token
+          # TODO it should return the original
+          handle_response(false, &block)
+        else
+          raise ResponseError.new(response)
+        end
+      elsif response.is_a?(Hash)
+        HashResponseWrapper.new(response)
+      elsif response.is_a?(Array)
+        ArrayResponseWrapper.new(response)
+      elsif response && response.success?
+        response
+      end
+    end
+
+    def options_for_refresh_flow_present?
+      !!@options[:refresh_token]
+    end
+
+    def options_for_credentials_flow_present?
+      !!(@options[:username] && @options[:password])
+    end
+
+    def options_for_code_flow_present?
+      !!(@options[:code] && @options[:redirect_uri])
+    end
+
+    def store_options(options={})
+      @options ||= DEFAULT_OPTIONS.dup
+      @options.merge!(options)
+    end
+
+    def construct_query_arguments(path_or_uri, options={}, body_or_query=:query)
+      uri = URI.parse(path_or_uri)
+      path = uri.path
+      scheme = use_ssl? ? 'https' : 'http'
+      options = options.dup
+      options[body_or_query] ||= {}
+      options[body_or_query][:format] = "json"
+      if access_token
+        options[body_or_query][:oauth_token] = access_token
+      else
+        options[body_or_query][CLIENT_ID_PARAM_NAME] = client_id
+      end
+      [
+        "#{scheme}://#{api_host}#{path}#{uri.query ? "?#{uri.query}" : ""}",
+        options
+      ]
+    end
+
+  end
+end

data/lib/soundcloud/hash_response_wrapper.rb

@@ -1,7 +1,9 @@
-class Soundcloud::HashResponseWrapper < Hashie::Mash
-  attr_reader :response
-  def initialize(response=nil, *args)
-    super(response, *args)
-    @response = response
+module SoundCloud
+  class HashResponseWrapper < Hashie::Mash
+    attr_reader :response
+    def initialize(response=nil, *args)
+      @response = response
+      super(response, *args)
+    end
   end
 end

data/lib/soundcloud/response_error.rb

@@ -0,0 +1,44 @@
+module SoundCloud
+  class ResponseError < HTTParty::ResponseError
+    STATUS_CODES = {
+      400 => "Bad Request",
+      401 => "Unauthorized",
+      402 => "Payment Required",
+      403 => "Forbidden",
+      404 => "Not Found",
+      405 => "Method Not Allowed",
+      406 => "Not Acceptable",
+      407 => "Proxy Authentication Required",
+      408 => "Request Timeout",
+      409 => "Conflict",
+      410 => "Gone",
+      411 => "Length Required",
+      412 => "Precondition Failed",
+      413 => "Request Entity Too Large",
+      414 => "Request-URI Too Long",
+      415 => "Unsupported Media Type",
+      416 => "Requested Range Not Satisfiable",
+      417 => "Expectation Failed",
+      422 => "Unprocessable Entity",
+      423 => "Locked",
+      424 => "Failed Dependency",
+      426 => "Upgrade Required",
+      500 => "Internal Server Error",
+      501 => "Not Implemented",
+      502 => "Bad Gateway",
+      503 => "Service Unavailable",
+      504 => "Gateway Timeout",
+      505 => "HTTP Version Not Supported",
+      507 => "Insufficient Storage",
+      510 => "Not Extended"
+    }
+
+    def message
+      error = response.parsed_response['error'] || response.parsed_response['errors']['error']
+      "HTTP status: #{response.code} #{STATUS_CODES[response.code]} Error: #{error}"
+    rescue
+      "HTTP status: #{response.code} #{STATUS_CODES[response.code]}"
+    end
+
+  end
+end

data/lib/soundcloud/version.rb

@@ -1,3 +1,3 @@
-class Soundcloud
-  VERSION = '0.3.1'
+module SoundCloud
+  VERSION = '0.3.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: soundcloud
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,64 +9,48 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-04 00:00:00.000000000 Z
+date: 2013-08-19 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: httparty
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: 0.7.3
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: 0.7.3
 - !ruby/object:Gem::Dependency
   name: httmultiparty
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: 0.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: 0.3.0
 - !ruby/object:Gem::Dependency
   name: hashie
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: bundler
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 2.5.0
+        version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -74,24 +58,9 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 2.5.0
-- !ruby/object:Gem::Dependency
-  name: fakeweb
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-description: A simple Soundcloud API wrapper based of httparty, multipart-post, httmultiparty
+        version: '1.0'
+description: The official SoundCloud API wrapper. It provides simple methods to handle
+  authorization and to execute HTTP calls.
 email:
 - johannes@soundcloud.com
 executables: []
@@ -99,7 +68,9 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/soundcloud/array_response_wrapper.rb
+- lib/soundcloud/client.rb
 - lib/soundcloud/hash_response_wrapper.rb
+- lib/soundcloud/response_error.rb
 - lib/soundcloud/version.rb
 - lib/soundcloud.rb
 - README.md
@@ -120,11 +91,12 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
-      version: 1.3.6
+      version: 1.3.5
 requirements: []
-rubyforge_project: soundcloud
-rubygems_version: 1.8.24
+rubyforge_project: 
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
-summary: A simple Soundcloud API wrapper
+summary: The official SoundCloud API wrapper.
 test_files: []
+has_rdoc: