shuffler_fm 0.0.1

data/.gitignore

@@ -0,0 +1,21 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+.rvmrc
+.sublime
+config.yml
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+smoke
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1 @@
+-r ./spec/helper.rb -c -f documentation

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+script: bundle exec rake --verbose --trace
+matrix:
+  allow_failures:
+      - rvm: ruby-head
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - ruby-head

data/.yardopts

@@ -0,0 +1,2 @@
+--no-private --protected --markup markdown lib/**/*.rb - README.md LICENSE
+

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in shuffler_fm.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Miguel Guinada
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,121 @@
+# ShufflerFM [![Build Status](https://secure.travis-ci.org/mguinada/shuffler_fm.png?branch=master)](http://travis-ci.org/mguinada/shuffler_fm) [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/mguinada/shuffler_fm)
+
+[travis]: http://travis-ci.org/mguinada/shuffler_fm
+[codeclimate]: https://codeclimate.com/github/mguinada/shuffler_fm
+
+Ruby API wrapper for [shuffler.fm v1 API](http://developers.shuffler.fm/)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'shuffler_fm'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install shuffler_fm
+
+## Usage
+
+### Create an API instance
+```ruby
+
+require 'shuffler_fm'
+
+# Get and API key from http://shuffler.fm/developers
+api = ShufflerFM.api('YOUR-KEY')
+=> #<ShufflerFM::API:0x000000027fa2b8 @key="YOUR-KEY">
+```
+
+### Read track data
+```ruby
+
+# list tracks
+tracks = api.tracks
+=> [#<Hashie::Rash blog=#<Hashie::Rash about=\"\" channel_url=\"http://api.shuffler.fm/v1/channels/blog:963?api-key=YOUR-KEY\" genres=[\"indie\", \"folk\", \"singer-songwriter\"] id=963 images=[#<Hashie::Rash height=240 url=\"http://assets.shuffler.fm/feeds/963/argeheartedboy_large.jpg\" width=240>] permalink=\"largehearted-boy\" profiles=#<Hashie::Rash facebook=nil twitter=nil> ...
+
+# list operations are paginated
+tracks = api.tracks(page: 2)
+
+# request a particular track
+track = api.track(1134715)
+
+track.blog.title
+=> "Cover Freak"
+
+track.post.url
+=> "http://coverfreak.com/2012/09/23/satisfaction/"
+
+track.metadata.title
+=> "Satisfaction"
+
+track.metadata.artist.name
+=> "Bjork & PJ Harvey"
+```
+
+### Search for an artist
+```ruby
+api.search_artists('radiohead').map(&:name)
+=> ["Radiohead", "Radiohead at Lollapalooza 2008", "REM & Radiohead", "Radiohead 6. Permanent Daylight live", "Radiohead @ Optimus Alive'12", "I Can't Take The Hurt (Johnny Cash vs Tegan and Sarah and Radiohead)"]
+```
+
+### Read a channel's activity stream
+```ruby
+
+activity = []
+api.genre_channels('punk', 'rock').each do |act|
+  activity << "#{act.verb.capitalize} on #{act.actor.title} refering music track #{act.object.metadata.title}"
+end
+
+activity
+=> ["Post on The KEXP Blog refering music track Sunshine/Pretty Girls (Live on KEXP)",
+    "Post on PropertyOfZack refering music track Always Summer (Live Video)",
+    "Post on Nialler9 Music Blog refering music track Honningbarna (2012)",
+    "Post on This Is Fake DIY refering music track Coffin Song", ...
+```
+
+and more ...
+
+### Configuration
+```ruby
+
+ShufflerFM.configure do |config|
+  config.connection_timeout = 1 #seconds
+  config.read_timeout       = 5 #seconds
+  config.proxy              = { uri: 'http://192.168.1.1:8080', user: 'user1', password: 'passwd'}
+end
+
+#or
+
+api = ShufflerFM.api("your-api-key", connection_timeout: 1, read_timeout: 5, proxy: 'http://192.168.1.1:8080')
+```
+
+## Reference
+
+[shuffler_fm reference](http://rdoc.info/github/mguinada/shuffler_fm)
+
+## Contributing
+
+1. Fork it
+2. Create your topic branch (`git checkout -b my-topic-branch`)
+3. Add/change specs for your unimplemented feature or bug fix
+4. Make sure specs fail by running `bundle exec rake spec`. If not return to step 3
+5. Hack it
+6. Make sure specs pass (`bundle exec rake spec`). If not return to step 5
+7. Edit the documentation so it is coherent with your feature or fix. Run `bundle exec rake yard` to review
+8. Commit changes (`git commit -am 'Add some feature/fix'`) and push to the branch (`git push origin my-topic-branch`)
+9. Submit a pull request for your branch.
+
+## Influence
+
+This API wrapper design is strongly influenced by the [Ocktokit gem](https://github.com/pengwynn/octokit)
+
+## Copyright
+Copyright (c) 2012 Miguel Guinada
+[LICENSE][] for details.
+
+[license]: https://github.com/mguinada/shuffler_fm/blob/master/LICENSE

data/Rakefile

@@ -0,0 +1,37 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'yard'
+
+task :test =>    :spec
+task :default => :spec
+
+RSpec::Core::RakeTask.new do |task|
+  task.rspec_opts = ["-c", "-f documentation", "-r ./spec/helper.rb"]
+  task.pattern    = 'spec/**/*_spec.rb'
+end
+
+desc "Open an interactive session preloaded with this gem's code"
+task :console do
+  if gem_available?("pry")
+    sh "pry -I lib -r shuffler_fm.rb"
+  else
+    sh "irb -rubygems -I lib -r shuffler_fm.rb"
+  end
+end
+
+desc "Generate documentation"
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb']
+  t.options = ['--no-private', '--protected', '--markup', 'markdown']
+end
+
+#
+# Determins if a gem is available at the current runtime
+#
+def gem_available?(name)
+  Gem::Specification.find_by_name(name)
+rescue Gem::LoadError
+  false
+rescue
+  Gem.available?(name) #for backwards compatibility
+end

data/lib/shuffler_fm/api/artists.rb

@@ -0,0 +1,53 @@
+module ShufflerFM
+  class API
+    # Shuffler.fm API operations over artists
+    module Artists
+      # Requests a list of artists
+      #
+      # @param [Hash] options
+      # @option options [Integer] :page The page to request on paginated operation responses
+      #
+      # @return [Array] a list of artists
+      #
+      def artists(options = {})
+        get("/artists", :page => page(options))
+      end
+
+      # Requests a particular artist
+      #
+      # @param [Integer] id The artist id
+      #
+      # @return [Artist] the requested artist or nil if not found
+      #
+      def artist(id)
+        get("/artists/#{Integer(id)}")
+      rescue ShufflerFM::NotFound
+        nil
+      end
+
+      # Requests an artist's top blogs
+      #
+      # @param [Integer] id the artist id
+      # @param [Hash] options
+      # @option options [Integer] :page The page to request on paginated operation responses
+      #
+      # @return [Array] an array of results
+      #
+      def artist_blogs(id, options= {})
+        get("artists/#{Integer(id)}/blogs", :page => page(options))
+      end
+
+      # Search artists
+      #
+      # @param [String] q your query
+      # @param [Hash] options
+      # @option options [Integer] :page The page to request on paginated operation responses
+      #
+      # @return [Array] an array of results
+      #
+      def search_artists(q, options = {})
+        get("/artists?q=#{String(q)}", :page => page(options))
+      end
+    end
+  end
+end

data/lib/shuffler_fm/api/blogs.rb

@@ -0,0 +1,52 @@
+module ShufflerFM
+  class API
+    # Shuffler.fm API operations over blogs
+    module Blogs
+      # Requests a list of blogs
+      #
+      # @param [Hash] options
+      # @option options [Integer] :page The page to request on paginated operation responses
+      #
+      # @return [Array] a list of blogs
+      #
+      def blogs(options = {})
+        get("/blogs", :page => page(options))
+      end
+
+      # Requests a list of featured blogs
+      #
+      # @param [Hash] options
+      # @option options [Integer] :page The page to request on paginated operation responses
+      #
+      # @return [Array] a list of featured blogs
+      #
+      def featured_blogs(options = {})
+        get("/blogs", :page => page(options), :filter => 'featured')
+      end
+
+      # Requests a particular blog
+      #
+      # @param [Integer] id The blog id
+      #
+      # @return [Blog] the requested blog or nil if not found
+      #
+      def blog(id)
+        get("/blogs/#{Integer(id)}")
+      rescue ShufflerFM::NotFound
+        nil
+      end
+
+      # Search blogs
+      #
+      # @param [String] q your query
+      # @param [Hash] options
+      # @option options [Integer] :page The page to request on paginated operation responses
+      #
+      # @return [Array] an array of results
+      #
+      def search_blogs(q, options = {})
+        get("/blogs?q=#{String(q)}", :page => page(options))
+      end
+    end
+  end
+end

data/lib/shuffler_fm/api/channels.rb

@@ -0,0 +1,88 @@
+module ShufflerFM
+  class API
+    # Shuffler.fm API operations over channels
+    module Channels
+      # Reads the media channels activity stream
+      #
+      # @param [String] key The channel key.
+      #    Can be on of the following: mp3, youtube, vimeo, soundcloud or officialfm
+      # @param [Hash] options
+      # @option options [Integer] :page The page to request on paginated operation responses
+      #
+      # @return [Array] an array with the channel's activity stream
+      #
+      # @example
+      #   api.media_channels('youtube', page: 2)
+      #
+      def media_channels(key, options = {})
+        channel(:media, key, options)
+      end
+
+      # Reads the blog channels activity stream
+      #
+      # @param [String] key The channel key.
+      # @param [Hash] options
+      # @option options [Integer] :page The page to request on paginated operation responses
+      #
+      # @return [Array] an array with the channel's activity stream
+      #
+      # @example
+      #    api.blog_channels(21)
+      #
+      def blog_channels(key, options = {})
+        channel(:blog, key, options)
+      end
+
+      # Reads the artist channels activity stream
+      #
+      # @param key The channel key.
+      # @param [Hash] options
+      # @option options [Integer] :page The page to request on paginated operation responses
+      #
+      # @return [Array] an array with the channel's activity stream
+      #
+      # @example
+      #    api.artist_channels('Pixies', page: 1)
+      #
+      def artist_channels(key, options = {})
+        channel(:artist, key, options)
+      end
+
+      # Reads the genere channels activity stream.
+      #
+      # @param [Array] keys The channel keys.
+      #
+      # @return [Array] an array with the channel's activity stream
+      #
+      # @example
+      #    api.genre_channels('rock')
+      #    api.genre_channels('punk', 'rock', page: 2)
+      #
+      def genre_channels(*keys)
+        channel(:genre, *keys)
+      end
+
+      private
+      def channel(*args)
+        key, query, opts = process_args(args)
+        get((key == :genre ? "channels/" : "channels/#{key}:") << "#{String(query.join('+'))}", :page => page(opts))
+      rescue ShufflerFM::NotFound
+        []
+      end
+
+      def process_args(args)
+        channels = %w(genre media blog artist)
+
+        if !channels.include?(args.first.to_s)
+          raise ArgumentError, "channel key must be one of: #{channels.join(', ')} but is #{args.first}"
+        end
+
+        if (query = Array(args[1..-1])).nil?
+          raise ArgumentError, "query value(s) must be provided"
+        end
+
+        return args.first.to_sym, query, query.last.is_a?(Hash) ? query.pop : {}
+      end
+    end
+  end
+end

data/lib/shuffler_fm/api/charts.rb

@@ -0,0 +1,28 @@
+module ShufflerFM
+  class API
+    # Shuffler.fm API operations over charts
+    module Charts
+      # Lists popular tracks charts
+      #
+      # @param [Hash] options
+      # @option options [Integer] :page The page to request on paginated operation responses
+      #
+      # @return [Array] a list of tracks merged with chart metadata
+      #
+      def popular_charts(options = {})
+        get("/charts/popular", :page => page(options))
+      end
+
+      # Lists tracks that were recently added to the popular list
+      #
+      # @param [Hash] options
+      # @option options [Integer] :page The page to request on paginated operation responses
+      #
+      # @return [Array] a list of tracks merged with chart metadata
+      #
+      def popular_charts_newest(options = {})
+        get("/charts/new", :page => page(options))
+      end
+    end
+  end
+end

data/lib/shuffler_fm/api/genres.rb

@@ -0,0 +1,28 @@
+module ShufflerFM
+  class API
+    module Genres
+      # Requests a list of genres
+      #
+      # @param [Hash] options
+      # @option options [Integer] :page The page to request on paginated operation responses
+      #
+      # @return [Array] a list of genres
+      #
+      def genres(options = {})
+        get("/genres", :page => page(options))
+      end
+
+      # Requests a particular genre
+      #
+      # @param [Integer] id The genre id
+      #
+      # @return [Genre] the requested genre or nil if not found
+      #
+      def genre(id, options = {})
+        get("/genres/#{Integer(id)}", options)
+      rescue ShufflerFM::NotFound
+        nil
+      end
+    end
+  end
+end

data/lib/shuffler_fm/api/tracks.rb

@@ -0,0 +1,33 @@
+module ShufflerFM
+  class API
+    # Shuffler.fm API operations over tracks
+    module Tracks
+      # Requests a list of tracks
+      #
+      # @param [Hash] options
+      # @option options [Integer] :page The page to request on paginated operation responses
+      #
+      # @return [Array] a list of tracks
+      #
+      # @example
+      #   tracks = api.tracks #first page
+      #   #...
+      #   tracks = api.tracks(page: 2)
+      #
+      def tracks(options = {})
+        get("/tracks", :page => page(options))
+      end
+
+      # Requests a particular track
+      #
+      # @param [Integer] id The track id
+      # @return [Track] the requested track or nil if not found
+      #
+      def track(id)
+        get("/tracks/#{Integer(id)}")
+      rescue ShufflerFM::NotFound
+        nil
+      end
+    end
+  end
+end

data/lib/shuffler_fm/api.rb

@@ -0,0 +1,54 @@
+require 'shuffler_fm/http'
+require 'shuffler_fm/request'
+require 'shuffler_fm/errors'
+
+require 'shuffler_fm/api/blogs'
+require 'shuffler_fm/api/tracks'
+require 'shuffler_fm/api/artists'
+require 'shuffler_fm/api/channels'
+require 'shuffler_fm/api/charts'
+require 'shuffler_fm/api/genres'
+
+module ShufflerFM
+  class API
+    @base_uri = 'http://api.shuffler.fm/'
+    @version  = 'v1'
+
+    include ShufflerFM::HTTP
+    include ShufflerFM::Request
+
+    include ShufflerFM::API::Blogs
+    include ShufflerFM::API::Tracks
+    include ShufflerFM::API::Artists
+    include ShufflerFM::API::Channels
+    include ShufflerFM::API::Charts
+    include ShufflerFM::API::Genres
+
+    class << self
+      attr_reader :base_uri, :version
+    end
+
+    # @!attribute [rw] key
+    #   The API key
+    #
+    attr_reader :key
+
+    # Creates an API instance
+    #
+    # @param [String] key An api key provided by http://shuffler.fm
+    #
+    # @example get an API instance
+    #   api = ShufflerFM::API.new("your-api-key")
+    #   api.tracks # gets 1st page of the track list
+    #
+    def initialize(key)
+      raise ArgumentError, 'An API key must be provided' if key.nil?
+      @key = key
+    end
+
+    private
+    def page(options)
+      Integer(options.fetch(:page) { 1 })
+    end
+  end
+end

data/lib/shuffler_fm/configuration.rb

@@ -0,0 +1,44 @@
+require 'hashie'
+
+module ShufflerFM
+  # Configuration descriptor
+  class Configuration < Hashie::Dash
+    # @!attribute [rw] connection_timeout
+    #   The connection timeout in seconds. Defaults to 2.
+    #
+    property :connection_timeout, :required => true, :default => 2
+    # @!attribute [rw] read_timeout
+    #   The open/read timeout in seconds. Defaults to 5.
+    #
+    property :read_timeout, :required => true, :default => 5
+    # @!attribute [rw] proxy
+    #   The proxy. Is unset by default.
+    #
+    # @example
+    #   ShufflerFM.configure do |cfg|
+    #    cfg.proxy = 'http://192.168.1.1:8080'
+    #   end
+    #
+    #   #or with authentication
+    #
+    #   ShufflerFM.configure do |cfg|
+    #    cfg.proxy = { uri: 'http://192.168.1.1:8080',
+    #                  user: 'user',
+    #                  password: 'passwd' }
+    #   end
+    #
+    property :proxy, :default => nil
+
+    def initialize(cfg = {})
+      super(cfg)
+    end
+
+    # The current configuration as an hash
+    #
+    # @return [Hash]
+    #
+    def values
+      to_hash(:symbolize_keys => true)
+    end
+  end
+end

data/lib/shuffler_fm/errors.rb

@@ -0,0 +1,37 @@
+module ShufflerFM
+  # Root error class
+  class Error < StandardError; end
+
+  # Raised on the advent of a 400 HTTP status code
+  class BadRequest < Error; end
+
+  # Raised on the advent of a 401 HTTP status code
+  class Unauthorized < Error; end
+
+  # Raised on the advent of a 403 HTTP status code
+  class Forbidden < Error; end
+
+  # Raised on the advent of a 404 HTTP status code
+  class NotFound < Error; end
+
+  # Raised on the advent of a 406 HTTP status code
+  class NotAcceptable < Error; end
+
+  # Raised on the advent of a 422 HTTP status code
+  class UnprocessableEntity < Error; end
+
+  # Raised on the advent of a 429 HTTP status code
+  class TooManyRequests < Error; end
+
+  # Raised on the advent of a 500 HTTP status code
+  class InternalServerError < Error; end
+
+  # Raised on the advent of a 501 HTTP status code
+  class NotImplemented < Error; end
+
+  # Raised on the advent of a 502 HTTP status code
+  class BadGateway < Error; end
+
+  # Raised on the advent of a 503 HTTP status code
+  class ServiceUnavailable < Error; end
+end

data/lib/shuffler_fm/http.rb

@@ -0,0 +1,25 @@
+require 'faraday'
+require 'faraday_middleware'
+require 'shuffler_fm/middleware/error_handler'
+
+module ShufflerFM
+  # @private
+  module HTTP
+    private
+    def connection
+      options = {:url => ShufflerFM::API.base_uri,
+                 :params => {'api-key' => key}}.merge(ShufflerFM.configuration.values)
+
+      Faraday.new(options) do |builder|
+        builder.use FaradayMiddleware::Rashify
+        builder.use FaradayMiddleware::ParseJson
+
+        builder.use ShufflerFM::Middleware::ErrorHandler
+
+        builder.adapter Faraday.default_adapter
+      end
+    end
+
+    alias :http_connection :connection
+  end
+end