officialfm 0.1.2 → 0.2.0

data/.gitignore

@@ -17,10 +17,5 @@ tmtags
 coverage
 rdoc
 pkg
-*.gem
-.yardopts
-.yardoc
-.bundle
-Gemfile.lock
 
 ## PROJECT::SPECIFIC

data/Gemfile

@@ -1,3 +1,9 @@
 source :rubygems
 
 gemspec
+
+group :test do
+  gem 'simplecov', '~> 0.6.0', :require => false
+  gem 'simplecov-gem-adapter', '~> 1.0.1', :require => false
+end
+

data/Gemfile.lock

@@ -0,0 +1,41 @@
+PATH
+  remote: .
+  specs:
+    officialfm (0.2.0)
+      faraday (~> 0.8.1)
+      faraday_middleware (~> 0.8.8)
+      hashie (~> 1.2)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    faraday (0.8.1)
+      multipart-post (~> 1.1)
+    faraday_middleware (0.8.8)
+      faraday (>= 0.7.4, < 0.9)
+    hashie (1.2.0)
+    jnunemaker-matchy (0.4.0)
+    multi_json (1.3.6)
+    multipart-post (1.1.5)
+    rake (0.9.2.2)
+    shoulda (2.11.3)
+    simplecov (0.6.0)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.5.3)
+    simplecov-gem-adapter (1.0.1)
+      simplecov
+    simplecov-html (0.5.3)
+    test-unit (2.5.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0)
+  jnunemaker-matchy (~> 0.4)
+  officialfm!
+  rake (~> 0.8)
+  shoulda (~> 2.11)
+  simplecov (~> 0.6.0)
+  simplecov-gem-adapter (~> 1.0.1)
+  test-unit (~> 2.1)

data/README.md

@@ -1,69 +1,201 @@
 # official.fm
 
-Ruby wrapper for the [official.fm Simple API](http://official.fm/developers).
+Ruby wrapper for the [official.fm v2 API](http://official.fm/developers).
 
 ## Installation
 
-    sudo gem install officialfm
+    gem install officialfm
+
+Alternatively put this in you `Gemfile`, then run `bundle install`:
+
+```ruby
+gem 'officialfm'
+```
 
 ## Get your API key
 
-Be sure and get your API key: [http://official.fm/developers/manage](http://official.fm/developers/manage)
+Coming soon.
 
-## Usage
+You can also access the API without an API key, but with a lower rate limit.
 
-### Include the relevant files
+## Client instantiation and configuration
 
-    require 'rubygems'
-    require 'officialfm'
+Include the relevant files
 
-### Instantiate a client
-    
-    officialfm = OfficialFM::Client.new(:api_key => 'your_api_key')
+```ruby
+require 'officialfm'
+```
 
-#### Examples
+Instantiate a client
 
-    user = officialfm.user('chab')
-    puts user.name
+```ruby
+officialfm = OfficialFM::Client.new
+```
 
-    officialfm.tracks('Dare', {:limit => 10, :embed => false}).each |track| do
-      puts "#{track.name} by #{track.artist_string}"
-    end
-    
-For a complete example of web-app using Sinatra in conjunction with
-this gem, see [ofmtweet](https://github.com/nddrylliog/ofmtweet).
+With an API key:
 
-## Additions to the original API
+```ruby
+officialfm = OfficialFM::Client.new(api_key: 'your_api_key')
+```
 
-### playlist.running\_time
+You can also set a default configuration for all clients to use
 
-The original API has a `length` attribute in playlists, but unfortunately
-we can't use it from the Ruby side with Hashie, because it's already the number
-of fields of the hash (as I understand it).
+```ruby
+OfficialFM.configure do |c|
+  c.api_key = YOUR_API_KEY
+end
+```
 
-It can still be accessed with `playlist["length"]` but since it's not pretty,
-the gem allows you to access it like this:
+## Response format
 
-		puts "#{playlist.running_time}s of pure bliss"
+All methods return a
+[Hashie:Mash](http://rdoc.info/github/intridea/hashie/Hashie/Mash).  That means
+you can access the response fields via method-like accessors. For example:
 
-## Note on Patches/Pull Requests
+```ruby
+search_results = officialfm.tracks('Wiz Khalifa')
+track = search_results[3].track
+puts "#{track.title} by #{track.artist}"
+```
 
-* Fork the project.
-* Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a
-  future version unintentionally.
-* Commit, do not mess with rakefile, version, or history.
-  (if you want to have your own version, that is fine but
-   bump version in a commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
+## API response enhancements
 
-## Copyright
+The API wraps responses in a root element, e.g.:
+
+```json
+{
+  "track": {
+    "title": "Some track"
+    ...
+  }
+}
+```
+
+The responses given by methods in the gem don't have a root and expose the
+resource's properites directly instead (e.g. `officialfm.track('xxxx').title`).
+
+Search results are also unwrapped. For example, the raw response of a track
+search looks like:
+
+```json
+{
+  "page": 1,
+  "total_entries": 2,
+  "total_pages": 1,
+  "tracks" : [
+    {
+      "track": {
+         // track properties
+      }
+    },
+    {
+      "track": {
+         // track properites
+      }
+    }
+  ]
+}
+```
+
+The gem removes the roots of the search result items, so you can access an item
+directly through array access.
+
+```ruby
+track = officialfm.tracks('foo').tracks[0]
+puts track.duration
+```
+
+
+## Methods
+
+### Tracks
+Search for a track:
+
+```ruby
+officialfm.tracks('Nightcall')
+```
+
+Search results being paged, you can request a specific page with the page parameter.
+
+```ruby
+officialfm.tracks('Kids', page: 2)
+```
+
+Get info about a specific track:
+
+```ruby
+officialfm.track('1nnQ')
+```
+
+### Playlists
+
+Search for a playlist (again you can pass an optional `page` parameter to get a
+specific results page):
+
+```ruby
+officialfm.playlists('AWOLNATION')
+```
 
-Copyright (c) 2011 Amos Wenger.
+Get info about a specific playlist:
 
-This project is distributed under the New BSD License. See LICENSE for details.
+```ruby
+officialfm.playlist('CbqY')
+```
+
+Retrieve the tracks in a playlist:
+
+```ruby
+playlists = officialfm.playlists('AWOLNATION')
+
+# The tracks for the 3 playlist in the search results
+tracks = playlists[2].tracks
+```
+
+Note that the `tracks` method of a playlist object makes an extra request. If
+you know the playlist ID in advance, you can retrieve the tracks in just one
+request.
+
+```ruby
+officialfm.playlist_tracks('CbqY')
+```
+
+### Projects
+
+Search for a project (a project can be an artist or a collaboration between several artists)
+
+```ruby
+officialfm.projects('Mac Miller x Pharrell')
+```
+
+Similarly to playlists, you can get information about a specific project with
+
+```ruby
+officialfm.project('edB6')
+```
+
+Get a project's tracks or playlists when you know the project ID in advance.
+
+```ruby
+tracks = officialfm.project_tracks('edB6')
+playlists = officialfm.project_playlists('edB6')
+puts artist.tracks
+puts artist.playlists
+```
+
+Of course you can get the playlists and tracks in a project even if you don't know its ID:
+
+```ruby
+projects = officialfm.projects('Mac Miller')
+
+puts projects[0].name # => 'Mac Miller'
+puts projects[2].name # => 'Mac Miller x Pharrell'
+
+tracks = projects[2].tracks
+
+```
+
+
+## Copyright
 
-Based on [@pengwynn's Gowalla API wrapper](https://github.com/pengwynn/gowalla)
+Copyright (c) 2012 official.fm
 
-A huge load of thanks to pengwynn for releasing it open-source! It was wonderful
-to work from his extra-clean codebase.

data/Rakefile

@@ -1,5 +1,4 @@
 require 'rake'
-require "shoulda/tasks"
 require "rake/testtask"
 require 'bundler'
 

data/lib/officialfm/client.rb

@@ -1,83 +1,50 @@
-require 'forwardable'
-require 'faraday/request/officialfm_oauth'
-require 'officialfm/authentication'
 require 'officialfm/version'
 
 module OfficialFM
   class Client
-    extend Forwardable
 
-    include Users
     include Tracks
     include Playlists
-    include Authentication
-    
-    attr_reader :api_key, :api_secret
+    include Projects
 
-    def_delegators :web_server, :authorize_url, :access_token_url
+    attr_reader :api_key
 
     def initialize(options={})
       @api_key = options[:api_key] || OfficialFM.api_key
-      @api_secret = options[:api_secret] || OfficialFM.api_secret
-      @access_token = options[:access_token]
-      @access_secret = options[:access_secret]
-      # Note: Although the default of the API is to return XML, I think
-      # json is more appropriate in the Ruby world
-      
-      @format = options[:format] || :json
-      connection unless @access_token
+      connection(options)
     end
 
-    # GET request arguments for simple API calls
-    def simple_params (options = nil)
-      params = {
-        :key    => @api_key,
-        :format => @format,
-      }
-      if options
-          options.each { |key, value|
-            case key
-            when 'limit'
-              params['api_max_responses'] = value
-            when 'embed'
-              params['api_embed_codes'] = value
-            else
-              params[key] = value
-            end
-          }
-      end
-      params
-    end
 
-    # Raw HTTP connection, either Faraday::Connection
+    # Faraday::Connection used for all HTTP requests
     #
     # @return [Faraday::Connection]
-    def connection
-      params = 
-    
-      options = {
-        :url => api_url,
+    def connection(options={})
+      config = {
+        :url     => api_url,
         :headers => default_headers
-      }
-    
-      @connection ||= Faraday.new(options) do |builder|
-        builder.use Faraday::Request::OfficialFMOAuth, authentication if authenticated?
-        builder.use Faraday::Request::Multipart
-        builder.use Faraday::Request::UrlEncoded
-        
-        builder.use Faraday::Response::Mashify
-        builder.use Faraday::Response::ParseJson
+      }.merge(options)
+
+      @connection ||= Faraday.new(config) do |builder|
         builder.adapter Faraday.default_adapter
+
+        builder.request :url_encoded
+
+        builder.response :mashify
+        builder.response :json
       end
 
     end
-    
+
     # @private
     def default_headers
       headers = {
-        :accept =>  'application/json',
-        :user_agent => "officialfm ruby gem version #{OfficialFM::VERSION}"
+        'X-API-Version' => '2.0',
+        :accept         => 'application/json',
+        :user_agent     => "officialfm v2 ruby gem version #{OfficialFM::VERSION}"
       }
+      headers['X-API-KEY'] = @api_key if @api_key
+
+      headers
     end
 
     # Provides the URL for accessing the API
@@ -86,5 +53,42 @@ module OfficialFM
     def api_url
       "http://api.official.fm"
     end
+
+    private
+
+    # Returns the url for a resource.
+    #
+    #   - id: resource id or URL
+    #   - options: extra params. Supports 'parent' and 'child' options.
+    #
+    # resource_url('http://api.official.fm/playlists/2BHH', :child => :tracks)
+    # # => http://api.official.fm/playlists/2BHH/tracks
+    #
+    # resource_url('2BHH', { :parent => 'playlists', :child => 'tracks'})
+    # # => /playlists/2BHH/tracks
+    #
+    # Note: if you supply a full resource URL, the parent option is ignored.
+    #
+    def resource_url(id, options={})
+      raise "Resource id cannot be nil" unless id
+
+      parent = options.fetch(:parent, nil)
+      child  = options.fetch(:child, nil)
+
+      if id.start_with? 'http'
+        return [id, child].join '/'
+      end
+
+      url = [parent, id, child].join('/').chomp('/')
+      url = "/#{url}" unless url.start_with? '/'
+
+      url
+    end
+
+    def extend_response(response, mixin_module)
+      response.obj = self
+      response.extend(mixin_module)
+    end
+
   end
 end

data/lib/officialfm/playlists.rb

@@ -1,145 +1,49 @@
-require 'cgi'
-
 module OfficialFM
   module Playlists
-  
-    # Search for playlists
-    #
-    # @param [String] search_param: a search parameter (eg. name of the playlist)
-    # @param [Integer] limit (50) limit per page (optional)
-    # @return [Hashie::Mash] Playlist list
+
+    # Search for a playlist
     def playlists(search_param, options={})
-      response = connection.get do |req|
-        req.url "/search/playlists/#{CGI::escape(search_param)}", simple_params(options)
-      end
-      
-      response.body.map do |pl| improve(pl) end
-    end
-  
-    # Retrieve information about a specific playlist
-    #
-    # @param [String] track_id: id
-    # @param [Bool] embed (false) should embed codes be included in the response
-    # @return [Hashie::Mash] Playlist
-    def playlist(playlist_id, options={})
-      response = connection.get do |req|
-        req.url "/playlist/#{playlist_id}", simple_params(options)
-      end
-      improve(response.body[0])
-    end
-    
-    # Retrieve users that have voted for this playlist
-    #
-    # @param [String] playlist_id: id
-    # @param [Integer] limit (50) limit per page
-    # @return [Hashie::Mash] User list
-    def playlist_votes(playlist_id, options={})
-      response = connection.get do |req|
-        req.url "/playlist/#{playlist_id}/votes", simple_params(options)
+      response = connection.get '/playlists/search', options.merge(:q => search_param)
+
+      response.body.playlists.map! do |p|
+        # remove the unnecessary root
+        actual_playlist = p.playlist
+
+        extend_response(actual_playlist, PlaylistMethods)
+
+        actual_playlist
       end
+
       response.body
     end
-    
-    def improve(playlist)
-      # the length field is already used. Note: running_time is in seconds
-      playlist.running_time = playlist["length"]
-      playlist
-    end
-       
-    ####################################################################
-    ######################### Advanced API methods #####################
-    ####################################################################
 
-    # Update information of a given playlist
-    #
-    # @param [String] playlist_id: id
-    # @param [String] description (optional)
-    # @param [String] name (optional)
-    # @param [String] password (optional)
-    # @param [String] private (optional)
-    # @return [Hashie::Mash] Playlist
-    def update_playlist! (playlist_id, data = {})
-      check_auth :update_playlist
-    
-      response = connection.put do |req|
-        req.url "/playlist/update/#{playlist_id}", data
-        req.body = { :format => @format }
-      end
-      response
-    end
-    
-    # Upload a picture for a given playlist
-    #
-    # @param [String] playlist_id: id
-    # @param [String] path: path to a picture
-    # @param [String] mime: the mime-type of the picture (e.g. image/jpeg, image/png, etc.)
-    # @return [Hashie::Mash] Success or error message
-    def playlist_picture! (playlist_id, path, mime)
-      check_auth :playlist_picture
-    
-      response = connection.post  do |req|
-        req.url "/playlist/picture/#{playlist_id}"
-        req.body = { :file => Faraday::UploadIO.new(path, mime), :format => @format }
-      end
-      response
-    end
-    
-    # Remove a playlist
-    #
-    # @param [String] playlist_id: id
-    # @return [Hashie::Mash] Success or error message
-    def playlist_remove! (playlist_id)
-      check_auth :playlist_remove
-    
-      response = connection.delete  do |req|
-        req.url "/playlist/remove/#{playlist_id}"
-        req.body = { :format => @format }
-      end
-      response
-    end
-    
-    # Create a playlist
-    #
-    # @param [String] name: playlist name
-    # @param [String] track_id: first track id of the new playlist
-    # @return [Hashie::Mash] Playlist object
-    def playlist_create! (name, track_id)
-      check_auth :playlist_create
-    
-      response = connection.post  do |req|
-        req.url "/playlist/create"
-        req.body = { :format => @format, :name => name, :track_id => track_id }
-      end
-      response
+    # Retrieve information about a specific playlist
+    def playlist(id, options={})
+      url = resource_url(id, parent: 'playlists')
+
+      response = connection.get(url, options).body.playlist
+      extend_response(response, PlaylistMethods)
     end
-    
-    # Vote for a playlist
-    #
-    # @param [String] playlist_id: id
-    # @return [Hashie::Mash] Success or error message
-    def playlist_vote! (playlist_id)
-      check_auth :playlist_vote
-    
-      response = connection.post  do |req|
-        req.url "/playlist/vote/#{playlist_id}"
-        req.body = { :format => @format }
+
+    def playlist_tracks(id, options={})
+      url = resource_url(id, { parent: 'playlists', child: 'tracks' })
+
+      response = connection.get url, options
+
+      tracks = response.body.tracks.map do |t|
+        # remove the unnecessary root
+        t.track
       end
-      response
+
+      tracks
     end
-    
-    # Remote vote for a playlist
-    #
-    # @param [String] playlist_id: id
-    # @return [Hashie::Mash] Success or error message
-    def playlist_unvote! (playlist_id)
-      check_auth :playlist_unvote
-    
-      response = connection.post  do |req|
-        req.url "/playlist/unvote/#{playlist_id}"
-        req.body = { :format => @format }
+
+    module PlaylistMethods
+
+      def tracks
+        obj.playlist_tracks(self.src)
       end
-      response
     end
-    
+
   end
 end