soundcloud 0.1.3b

data/README.md

@@ -0,0 +1,110 @@
+# Soundcloud API Wrapper
+## Description
+This is a thin wrapper around the Soundcloud API based of httparty.
+It is providing simple methods to handle authorization and to execute HTTP calls.
+
+## Requirements
+* httmultiparty
+* httparty
+* crack
+* multipart-upload
+* hashie
+
+## Installation
+    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
+  
+#### Do the 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
+    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
+
+#### Do the OAuth2 authorization code flow
+    sc = Soundcloud.new({
+      :client_id      => 'YOUR_CLIENT_ID',
+      :client_secret  => 'YOUR_CLIENT_SECRET',
+    })
+    
+    sc.authorize_url(:redirect_uri => uri)
+    # => "https://soundcloud.com/connect?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=http://host/redirect"
+    sc.exchange_code(:redirect_uri => uri, :code => 'CODE')
+
+#### Do the 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', {
+      :title        => 'a new track',
+      :asset_data   => File.new('track.mp3'),
+      :artwork_data => File.new('image.jpg')
+    })
+    
+    # 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 => 'http://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}")
+
+## Details
+#### Soundcloud.new(options={})
+Will store the passed options and call exchange_token in case options are passed that allow an exchange of tokens.
+
+#### Soundcloud#exchange_token(options={})
+Will store 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={})
+Will store the passed options and return an authorize url.
+The client_id and redirect_uri options need to present to generate the authorize url.
+
+#### Soundcloud#get, Soundcloud#post, Soundcloud#put, Soundcloud#delete, Soundcloud#head
+All available HTTP methods are exposed through these 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 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?
+These are accessor to the stored options.
+
+#### Error Handling
+In case a request was not successful a Soundcloud::ResponseError will be raise.
+The original HTTParty response is available through Soundcloud::ResponseError#response.

data/lib/soundcloud.rb

@@ -0,0 +1,123 @@
+gem 'httmultiparty'
+gem 'mash'
+require 'httmultiparty'
+require 'hashie'
+require 'uri'
+
+class Soundcloud
+  class ResponseError < HTTParty::ResponseError; end
+  include HTTMultiParty
+  headers 'Accept' => 'application/json'
+  
+  # TODO fix when api is ready for client_id
+  CLIENT_ID_PARAM_NAME  = :consumer_key
+  API_SUBHOST           = 'api'
+  AUTHORIZE_PATH        = '/connect'
+  TOKEN_PATH            = '/oauth2/token'
+  DEFAULT_OPTIONS       = {
+    :site => 'soundcloud.com'
+  }
+
+
+  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, query={}, options={}); handle_response { self.class.post   *construct_query_arguments(path, options.merge(:query => query)) } end
+  def put   (path, query={}, options={}); handle_response { self.class.put    *construct_query_arguments(path, options.merge(:query => query)) } 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 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={})
+    store_options(options)
+    "https://#{host}#{AUTHORIZE_PATH}?response_type=code&client_id=#{client_id}&redirect_uri=#{URI.escape redirect_uri}"
+  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 {
+      self.class.post("https://#{api_host}#{TOKEN_PATH}", :query => params)
+    }
+    @options.merge!(:access_token => response.access_token, :refresh_token => response.refresh_token)
+    response
+  end
+  
+private
+  def handle_response(refreshing_enabled=true, &block)
+    response = block.call
+    if response && !response.success?
+      if response.code == 401 && response["error"] == "invalid_grant" && refreshing_enabled
+        exchange_token
+        # TODO it should return the original
+        handle_response(false, &block)
+      else
+        raise ResponseError.new(response), "HTTP Status #{response.code}"
+      end
+    elsif response.is_a? Hash
+      HashResponseWrapper.new(response)
+    elsif response.is_a? Array
+      ArrayResponseWrapper.new(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={})
+    path = URI.parse(path_or_uri).path
+    scheme = use_ssl? ? 'https' : 'http'
+    options = options.dup
+    options[:query] ||= {}
+
+    if access_token
+      options[:query][:oauth_token] = access_token
+    else
+      options[:query][CLIENT_ID_PARAM_NAME] = client_id
+    end
+    [
+      "#{scheme}://#{api_host}#{path}",
+      options
+    ]
+  end
+end
+
+require 'soundcloud/array_response_wrapper'
+require 'soundcloud/hash_response_wrapper'
+

data/lib/soundcloud/array_response_wrapper.rb

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

data/lib/soundcloud/hash_response_wrapper.rb

@@ -0,0 +1,7 @@
+class Soundcloud::HashResponseWrapper < Hashie::Mash
+  attr_reader :response
+  def initialize(response)
+    super(response)
+    @response = response
+  end
+end

data/lib/soundcloud/version.rb

@@ -0,0 +1,3 @@
+class Soundcloud
+  VERSION = '0.1.3b'
+end

metadata

@@ -0,0 +1,146 @@
+--- !ruby/object:Gem::Specification 
+name: soundcloud
+version: !ruby/object:Gem::Version 
+  hash: 1452983230
+  prerelease: true
+  segments: 
+  - 0
+  - 1
+  - 3b
+  version: 0.1.3b
+platform: ruby
+authors: 
+- Johannes Wagener
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-01-26 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: httparty
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 5
+        segments: 
+        - 0
+        - 7
+        - 3
+        version: 0.7.3
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: httmultiparty
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 15
+        segments: 
+        - 0
+        - 2
+        version: "0.2"
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: hashie
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: fakeweb
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id005
+description: A simple Soundcloud API wrapper based of httparty, multipart-post, httmultiparty
+email: 
+- johannes@soundcloud.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/soundcloud/array_response_wrapper.rb
+- lib/soundcloud/hash_response_wrapper.rb
+- lib/soundcloud/version.rb
+- lib/soundcloud.rb
+- README.md
+has_rdoc: true
+homepage: http://dev.soundcloud.com
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 23
+      segments: 
+      - 1
+      - 3
+      - 6
+      version: 1.3.6
+requirements: []
+
+rubyforge_project: soundcloud
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: A simple Soundcloud API wrapper
+test_files: []
+