itunes 0.3.0 → 0.4.0

data/.gitignore

@@ -0,0 +1,5 @@
+pkg/*
+Gemfile.lock
+coverage/*
+doc/*
+.yardoc

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format=nested
+--backtrace

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/README.md

@@ -1,43 +1,48 @@
-# iTunes
+iTunes
+======
+
 A Ruby wrapper around the iTunes API that lets you search for any sort of data that is available on the iTunes store.
 
-## Example Response
+Example Response
+----------------
 
     {
-      "artistId" : 954266,
-      "artistName" : "Green Day",
-      "artistViewUrl" : "http://itunes.apple.com/us/artist/green-day/id954266?uo=4",
-      "artworkUrl100" : "http://a1.phobos.apple.com/us/r1000/049/Features/1e/17/05/dj.rpihtiig.100x100-75.jpg",
-      "artworkUrl30" : "http://a1.phobos.apple.com/us/r1000/049/Features/1e/17/05/dj.rpihtiig.30x30-50.jpg",
-      "artworkUrl60" : "http://a1.phobos.apple.com/us/r1000/049/Features/1e/17/05/dj.rpihtiig.60x60-50.jpg",
-      "collectionCensoredName" : "Dookie",
-      "collectionExplicitness" : "explicit",
-      "collectionId" : 5132583,
-      "collectionName" : "Dookie",
-      "collectionPrice" : 9.99,
-      "collectionViewUrl" : "http://itunes.apple.com/us/album/she/id5132583?i=5132563&uo=4",
-      "contentAdvisoryRating" : null,
+      "artist_id" : 954266,
+      "artist_name" : "Green Day",
+      "artist_view_url" : "http://itunes.apple.com/us/artist/green-day/id954266?uo=4",
+      "artwork_url100" : "http://a1.phobos.apple.com/us/r1000/049/Features/1e/17/05/dj.rpihtiig.100x100-75.jpg",
+      "artwork_url30" : "http://a1.phobos.apple.com/us/r1000/049/Features/1e/17/05/dj.rpihtiig.30x30-50.jpg",
+      "artwork_url60" : "http://a1.phobos.apple.com/us/r1000/049/Features/1e/17/05/dj.rpihtiig.60x60-50.jpg",
+      "collection_censored_name" : "Dookie",
+      "collection_explicitness" : "explicit",
+      "collection_id" : 5132583,
+      "collection_name" : "Dookie",
+      "collection_price" : 9.99,
+      "collection_view_url" : "http://itunes.apple.com/us/album/she/id5132583?i=5132563&uo=4",
+      "content_advisory_rating" : null,
       "country" : "USA",
       "currency" : "USD",
-      "discCount" : 1,
-      "discNumber" : 1,
+      "disc_count" : 1,
+      "disc_number" : 1,
       "kind" : "song",
-      "previewUrl" : "http://a1.phobos.apple.com/us/r1000/027/Music/0e/86/7a/mzm.wchstext.aac.p.m4a",
-      "primaryGenreName" : "Alternative",
-      "releaseDate" : "2003-04-22 07:00:00 Etc/GMT",
-      "trackCensoredName" : "She",
-      "trackCount" : 15,
-      "trackExplicitness" : "notExplicit",
-      "trackId" : 5132563,
-      "trackName" : "She",
-      "trackNumber" : 8,
-      "trackPrice" : 1.29,
-      "trackTimeMillis" : 134293,
-      "trackViewUrl" : "http://itunes.apple.com/us/album/she/id5132583?i=5132563&uo=4",
-      "wrapperType" : "track"
+      "preview_url" : "http://a1.phobos.apple.com/us/r1000/027/Music/0e/86/7a/mzm.wchstext.aac.p.m4a",
+      "primary_genre_name" : "Alternative",
+      "release_date" : "2003-04-22 07:00:00 Etc/GMT",
+      "track_censored_name" : "She",
+      "track_count" : 15,
+      "track_explicitness" : "notExplicit",
+      "track_id" : 5132563,
+      "track_name" : "She",
+      "track_number" : 8,
+      "track_price" : 1.29,
+      "track_time_millis" : 134293,
+      "track_view_url" : "http://itunes.apple.com/us/album/she/id5132583?i=5132563&uo=4",
+      "wrapper_type" : "track"
     }
 
-## Available Methods
+Available Methods
+-----------------
+
    - movie
    - podcast
    - music
@@ -47,31 +52,38 @@ A Ruby wrapper around the iTunes API that lets you search for any sort of data t
    - tv_show
    - all
 
-## Using the iTunes gem
+Using the iTunes gem
+--------------------
 
     require 'itunes'
-    
-    >> itunes = ITunes.new
+
+    >> itunes = ITunes::Client.new
     >> songs = itunes.music('green day she')
-    => {"result_count" => 15, "results" => [...]}
-    >> songs['results'].each do |song|
-    >>   puts "#{song['trackName']} - #{song['artistName']} (#{song['collectionName']})"
+    => <#Hashie::Rash result_count=15 results=[...]>
+    >> songs.results.each do |song|
+    >>   puts "#{song.track_name} - #{song.artist_name} (#{song.collection_name})"
     >> end
     => She - Green Day (Dookie)
     => She - Green Day (Dookie)
     => She - Green Day (Dookie)
     => She - Green Day (Dookie)
     => She - Green Day (Dookie)
-    => ...
+
+Search directly from the class
+
     >> iron_man = ITunes.movie('iron man 2')
-    => {"result_count" => 1, "results" => [...]}
-    => ...
+    => <#Hashie::Rash result_count=1 results=[...]>
+
+Limit the results:
+
     >> foo_fighters = ITunes.music('foo fighters everlong', :limit => 1)
-    => {"result_count" => 1, "results" => [{ "trackName" => "Everlong", ... }]}
+    => <#Hashie::Rash result_count=1 results=[<#Hashie::Rash ...>]>
+
+What is Hashie::Rash?
 
-## Upcoming Features
+If you are familiar with Hashie, Rash is very similar to a Mash.  The primary difference is that Rash gives us ruby-friendly keys so instead of artistId, Rash converts that to artist_id.
 
-- A better DSL.
+Copyright
+---------
 
-## Copyright
 Copyright © 2010 Garrett Bjerkhoel. See [MIT-LICENSE](http://github.com/dewski/itunes/blob/master/MIT-LICENSE) for details.

data/Rakefile

@@ -0,0 +1,19 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+namespace :doc do
+  require 'yard'
+  YARD::Rake::YardocTask.new do |task|
+    task.files   = ['lib/**/*.rb']
+    task.options = [
+      '--protected',
+      '--output-dir', 'doc/yard',
+      '--markup', 'markdown',
+    ]
+  end
+end

data/itunes.gemspec

@@ -0,0 +1,43 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "itunes/version"
+
+Gem::Specification.new do |s|
+  s.name = "itunes"
+  s.version = ITunes::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors = ["Garrett Bjerkhoel"]
+  s.email = %q{me@garrettbjerkhoel.com}
+  s.homepage = %q{http://github.com/dewski/itunes}
+  s.summary = %q{iTunes API}
+
+  s.rubyforge_project = "itunes"
+
+  s.extra_rdoc_files = [
+    "MIT-LICENSE",
+     "README.md"
+  ]
+  s.rdoc_options = ["--charset=UTF-8"]
+
+  s.add_development_dependency('bundler', '~> 1.0')
+  s.add_development_dependency('rake', '~> 0.8')
+  s.add_development_dependency('rspec', '~> 2.5.0')
+  s.add_development_dependency('yard', '~> 0.6')
+  s.add_development_dependency('maruku', '~> 0.6')
+  s.add_development_dependency('simplecov', '~> 0.3')
+  s.add_development_dependency('webmock', '~> 1.6')
+  s.add_development_dependency('vcr', '~> 1.4.0')
+  s.add_development_dependency('json', '~> 1.5.1')
+
+  s.add_runtime_dependency('hashie', '~> 1.0.0')
+  s.add_runtime_dependency('rash', '~> 0.2.0')
+  s.add_runtime_dependency('faraday', '~> 0.5.4')
+  s.add_runtime_dependency('faraday_middleware', '~> 0.3.1')
+  s.add_runtime_dependency('multi_json', '~> 0.0.5')
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end
+

data/lib/faraday/rashify.rb

@@ -0,0 +1,30 @@
+require 'faraday'
+
+# @private
+module Faraday
+  # @private
+  class Response::Rashify < Response::Middleware
+    begin
+      require 'hashie'
+      require 'rash'
+    rescue LoadError, NameError => error
+      self.load_error = error
+    end
+
+    def self.register_on_complete(env)
+      env[:response].on_complete do |response|
+        response_body = response[:body]
+        if response_body.is_a?(Hash)
+          response[:body] = ::Hashie::Rash.new(response_body)
+        elsif response_body.is_a?(Array)
+          response[:body] = response_body.map{|item| item.is_a?(Hash) ? ::Hashie::Rash.new(item) : item}
+        end
+      end
+    end
+
+    def initialize(app)
+      super
+      @parser = nil
+    end
+  end
+end

data/lib/itunes.rb

@@ -1,73 +1,26 @@
-require 'httparty'
+require 'faraday_middleware'
+require 'faraday/rashify'
+require 'itunes/configuration'
+require 'itunes/client'
 
-class ITunes
-  include HTTParty
+module ITunes
+  extend Configuration
 
-  base_uri 'ax.phobos.apple.com.edgesuite.net/WebObjects/MZStoreServices.woa/wa/ws'
-  format :json
-  
-  attr_accessor :limit
-
-  def method_missing(name, *args)
-    methods = %q{movie podcast music music_video audiobook short_film tv_show all}
-
-    if methods.include?(name.to_s)
-      camelcase = name.to_s.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase }
-      camelcase[0] = camelcase[0].chr.downcase
-      
-      @limit = args[1].delete(:limit) unless args[1].nil? # will return nil if there is no limit
-
-      request(args.first, camelcase)
-    else
-      super(name, *args)
-    end
-  end
-  
-  def initialize(limit=nil)
-    @limit = limit
-  end
-  
-  # So you don't have to create an instance if you don't need to
-  def self.music(terms, opts=nil)
-    self.new.music(terms, opts)
-  end
-  
-  def self.podcast(terms, opts=nil)
-    self.new.podcast(terms, opts)
-  end
-  
-  def self.movie(terms, opts=nil)
-    self.new.movie(terms, opts)
+  # Alias for ITunes::Client.new
+  #
+  # @return [ITunes::Client]
+  def self.client(options={})
+    ITunes::Client.new(options)
   end
-  
-  def self.music_video(terms, opts=nil)
-    self.new.music_video(terms, opts)
-  end
-  
-  def self.audiobook(terms, opts=nil)
-    self.new.audiobook(terms, opts)
-  end
-  
-  def self.short_film(terms, opts=nil)
-    self.new.short_film(terms, opts)
-  end
-  
-  def self.tv_show(terms, opts=nil)
-    self.new.tv_show(terms, opts)
-  end
-  
-  def self.all(terms, opts=nil)
-    self.new.all(terms, opts)
+
+  # Delegate to ITunes::Client
+  def self.method_missing(method, *args, &block)
+    return super unless client.respond_to?(method)
+    client.send(method, *args, &block)
   end
 
-  private
-    def request(term, media='all')
-      raise ArgumentError, 'you need to search for something, provide a term.' if term.nil?
-      
-      # 
-      query = { :term => term, :media => media }
-      query.merge!({ :limit => @limit }) unless @limit.nil? or @limit == 0
-      
-      self.class.get('Search', { :query => query })
-    end
+  # Delegate to ITunes::Client
+  def self.respond_to?(method)
+    return client.respond_to?(method) || super
+  end
 end

data/lib/itunes/client.rb

@@ -0,0 +1,26 @@
+require File.expand_path('../request', __FILE__)
+
+module ITunes
+  class Client
+
+    # @private
+    attr_accessor *Configuration::VALID_OPTIONS_KEYS
+
+    # Creates a new Client
+    def initialize(options={})
+      options = ITunes.options.merge(options)
+      Configuration::VALID_OPTIONS_KEYS.each do |key|
+        send("#{key}=", options[key])
+      end
+    end
+
+    Dir[File.expand_path('../client/*.rb', __FILE__)].each{|f| require f}
+
+    alias :api_endpoint :endpoint
+
+    include Request
+    include Search
+    include Lookup
+
+  end
+end

data/lib/itunes/client/lookup.rb

@@ -0,0 +1,21 @@
+module ITunes
+  module Lookup
+
+    ID_TYPES =  { :amg_artist => 'amgArtistId', :id => 'id', :amg_album => 'amgAlbumId', :upc => 'upc' }
+
+    # Performs a lookup request based on iTunes IDs, UPCs/ EANs, and All Music Guide (AMG) IDs
+    # @param [String] id
+    # @option options [Symbol] :id_type used to specify the option type being passed, valid types are: id, upc, amg_artist, amg_album
+    # @raise [ArgumentError] If an invalid id_type is specified in options
+    def lookup(id, options={})
+      id = id.split(',') if id.kind_of?(String)
+      id_type = options.delete(:id_type) || :id
+
+      raise ArgumentError, 'invalid id_type.' unless ID_TYPES.keys.include?(id_type.to_sym)
+
+      options.merge!({ ID_TYPES[id_type.to_sym] => id.join(',') })
+      request('Lookup', options)
+    end
+
+  end
+end

data/lib/itunes/client/search.rb

@@ -0,0 +1,81 @@
+module ITunes
+  module Search
+
+    # Performs a music search
+    # @param [String] term The search term
+    # @option options [Symbol]
+    def music(term, options={})
+      search(term, 'music', options)
+    end
+
+    # Performs a movie search
+    # @param [String] term The search term
+    # @option options [Symbol]
+    def movie(term, options={})
+      search(term, 'movie', options)
+    end
+
+    # Performs a podcast search
+    # @param [String] term The search term
+    # @option options [Symbol]
+    def podcast(term, options={})
+      search(term, 'podcast', options)
+    end
+
+    # Performs a music video search
+    # @param [String] term The search term
+    # @option options [Symbol]
+    def music_video(term, options={})
+      search(term, 'musicVideo', options)
+    end
+
+    # Performs an audiobook search
+    # @param [String] term The search term
+    # @option options [Symbol]
+    def audiobook(term, options={})
+      search(term, 'audiobook', options)
+    end
+
+    # Performs a short film search
+    # @param [String] term The search term
+    # @option options [Symbol]
+    def short_film(term, options={})
+      search(term, 'shortFilm', options)
+    end
+
+    # Performs a tv show search
+    # @param [String] term The search term
+    # @option options [Symbol]
+    def tv_show(term, options={})
+      search(term, 'tvShow', options)
+    end
+
+    # Performs a search on all itunes content
+    # @param [String] term The search term
+    # @option options [Symbol]
+    def all(term, options={})
+      search(term, 'all', options)
+    end
+
+    private
+
+      def search(term, media='all', options={})
+        raise ArgumentError, 'you need to search for something, provide a term.' if term.nil? || term.length == 0
+
+        params = { :term => term, :media => media }
+        if options.has_key?(:limit)
+          params.merge!(:limit => options.delete(:limit))
+        elsif limit
+          params.merge!({ :limit => limit })
+        end
+        params.delete(:limit) if params[:limit] && params[:limit] == 0
+        params.merge!(options)
+
+        # clear empty key/value pairs
+        params.reject! { |key, value| value.nil? }
+
+        request('Search', params)
+      end
+
+  end
+end