rockstar 0.3.0

data/lib/rockstar/scrobble.rb

@@ -0,0 +1,67 @@
+# exception definitions
+class BadSessionError < StandardError; end
+class RequestFailedError < StandardError; end
+
+module Rockstar
+  class Scrobble
+    # you need to read last.fm/api/submissions#subs first!
+
+    attr_accessor :session_id, :submission_url, :artist, :track, :time,
+                  :source, :length, :album, :track_number, :mb_track_id, :rating
+    attr_reader :status
+
+    def initialize(args = {})
+      @session_id = args[:session_id] # from Rockstar::TokenAuth
+      @submission_url = args[:submission_url] # from Rockstar::TokenAuth (can change)
+      @artist = args[:artist] # track artist
+      @track = args[:track] # track name
+      @time = args[:time] # a Time object set to the time the track started playing
+      @source = args[:source] || 'P' # track source, see last.fm/api/submissions#subs
+      @length = args[:length].to_s || '' # track length in seconds
+      @album = args[:album] || '' # track album name (optional)
+      @track_number = args[:track_number] || '' # track number (optional)
+      @mb_track_id = args[:mb_track_id] || '' # MusicBrainz track ID (optional)
+      @rating = args[:rating] || '' # Rating for clip (optional L=Love, B=Ban (if source=L), S=Skip (if source=L))
+      
+      if [@session_id, @submission_url, @artist, @track].any?(&:blank?)
+        raise ArgumentError, 'Missing required argument'
+      elsif @time.class.to_s != 'Time'
+        raise ArgumentError, ":time must be a Time object"
+      elsif !['P','R','E','U'].include?(@source) # see last.fm/api/submissions#subs
+        raise ArgumentError, "Invalid source"
+      elsif @source == 'P' && @length.blank? # length is not optional if source is P
+        raise ArgumentError, 'Length must be set'
+      elsif !@length.blank? && @length.to_i <= 30 # see last.fm/api/submissions#subs
+        raise ArgumentError, 'Length must be greater than 30 seconds'
+      end
+
+      @connection = REST::Connection.new(@submission_url)
+    end
+
+    def submit!
+      query = { :s => @session_id,
+                'a[0]' => @artist,
+                't[0]' => @track,
+                'i[0]' => @time.utc.to_i,
+                'o[0]' => @source,
+                'r[0]' => @rating,
+                'l[0]' => @length,
+                'b[0]' => @album,
+                'n[0]' => @track_number,
+                'm[0]' => @mb_track_id }
+                
+      @status = @connection.post('', false, query)
+
+      case @status
+      when /OK/
+
+      when /BADSESSION/
+        raise BadSessionError # rerun Rockstar::SimpleAuth#handshake!
+      when /FAILED/
+        raise RequestFailedError, @status
+      else
+        raise RequestFailedError
+      end
+    end
+  end
+end

data/lib/rockstar/session.rb

@@ -0,0 +1,19 @@
+module Rockstar
+  class Session < Base
+    attr_accessor :username, :key, :subscriber
+
+    class << self
+      def new_from_xml(xml, doc=nil)
+        t       = Session.new()
+        t.username  = (xml).at(:name).inner_html
+        t.key   = (xml).at(:key).inner_html
+        t.subscriber   = (xml).at(:subscriber).inner_html
+        t
+      end
+    end
+  end
+end
+
+
+
+

data/lib/rockstar/simpleauth.rb

@@ -0,0 +1,62 @@
+require 'digest/md5'
+
+# exception definitions
+class BadAuthError < StandardError; end
+class BannedError < StandardError; end
+class BadTimeError < StandardError; end
+module Rockstar
+  AUTH_URL = 'http://post.audioscrobbler.com'
+  AUTH_VER = '1.2.1'
+  
+  # This class is deprecated. Please use TokenAuth instead.
+  class SimpleAuth
+    # you should read last.fm/api/submissions#handshake
+
+    attr_accessor :user, :password, :client_id, :client_ver
+    attr_reader :status, :session_id, :now_playing_url, :submission_url
+
+    def initialize(args = {})
+      warn "[DEPRECATION] This class is deprecated. Please use TokenAuth instead!"
+      
+      @user = args[:user] # last.fm username
+      @password = args[:password] # last.fm password
+      @client_id = 'rbs' # Client ID assigned by last.fm; Don't change this!
+      @client_ver = Rockstar::Version
+
+      raise ArgumentError, 'Missing required argument' if @user.blank? || @password.blank?
+
+      @connection = REST::Connection.new(AUTH_URL)
+    end
+
+    def handshake!
+      password_hash = Digest::MD5.hexdigest(@password)
+      timestamp = Time.now.to_i.to_s
+      token = Digest::MD5.hexdigest(password_hash + timestamp)
+
+      query = { :hs => 'true',
+                :p => AUTH_VER,
+                :c => @client_id,
+                :v => @client_ver,
+                :u => @user,
+                :t => timestamp,
+                :a => token }
+      result = @connection.get('/', false, query)
+
+      @status = result.split(/\n/)[0]
+      case @status
+      when /OK/
+        @session_id, @now_playing_url, @submission_url = result.split(/\n/)[1,3]
+      when /BANNED/
+        raise BannedError # something is wrong with the gem, check for an update
+      when /BADAUTH/
+        raise BadAuthError # invalid user/password
+      when /FAILED/
+        raise RequestFailedError, @status
+      when /BADTIME/
+        raise BadTimeError # system time is way off
+      else
+        raise RequestFailedError
+      end  
+    end
+  end
+end

data/lib/rockstar/tag.rb

@@ -0,0 +1,100 @@
+# Below is code samples for how to find the top albums and tracks for a tag.
+# 
+#   tag = Rockstar::Tag.new('country')
+# 
+#   puts 'Top Albums'
+#   tag.top_albums.each { |a| puts "(#{a.count}) #{a.name} by #{a.artist}" }
+# 
+#   puts
+# 
+#   puts 'Top Tracks'
+#   tag.top_tracks.each { |t| puts "(#{t.count}) #{t.name} by #{t.artist}" }
+#   
+# Which would output something similar to:
+# 
+#   Top Albums
+#   (29) American IV: The Man Comes Around by Johnny Cash
+#   (14) Folks Pop In at the Waterhouse by Various Artists
+#   (13) Hapless by Flowers From The Man Who Shot Your Cousin
+#   (9) Taking The Long Way by Dixie Chicks
+#   (8) Unchained by Johnny Cash
+#   (8) American III: Solitary Man by Johnny Cash
+#   (8) Wide Open Spaces by Dixie Chicks
+#   (7) It's Now or Later by Tangled Star
+#   (7) Greatest Hits by Hank Williams
+#   (7) American Recordings by Johnny Cash
+#   (6) Forgotten Landscape by theNoLifeKing
+#   (6) At Folsom Prison by Johnny Cash
+#   (6) Fox Confessor Brings the Flood by Neko Case
+#   (6) Murder by Johnny Cash
+#   (5) Gloom by theNoLifeKing
+#   (5) Set This Circus Down by Tim McGraw
+#   (5) Blacklisted by Neko Case
+#   (5) Breathe by Faith Hill
+#   (5) Unearthed (disc 4: My Mother's Hymn Book) by Johnny Cash
+#   (4) Home by Dixie Chicks
+# 
+#   Top Tracks
+#   (221) Hurt by Johnny Cash
+#   (152) I Walk the Line by Johnny Cash
+#   (147) Ring of Fire by Johnny Cash
+#   (125) Folsom Prison Blues by Johnny Cash
+#   (77) The Man Comes Around by Johnny Cash
+#   (67) Personal Jesus by Johnny Cash
+#   (65) Not Ready To Make Nice by Dixie Chicks
+#   (63) Before He Cheats by Carrie Underwood
+#   (62) Give My Love to Rose by Johnny Cash
+#   (49) Jackson by Johnny Cash
+#   (49) What Hurts The Most by Rascal Flatts
+#   (48) Big River by Johnny Cash
+#   (46) Man in Black by Johnny Cash
+#   (46) Jolene by Dolly Parton
+#   (46) Friends in Low Places by Garth Brooks
+#   (46) One by Johnny Cash
+#   (44) Cocaine Blues by Johnny Cash
+#   (41) Get Rhythm by Johnny Cash
+#   (41) I Still Miss Someone by Johnny Cash
+#   (40) The Devil Went Down to Georgia by Charlie Daniels Band
+module Rockstar
+  class Tag < Base
+    attr_accessor :name, :count, :url
+    
+    class << self
+      def new_from_xml(xml, doc=nil)
+        name    = (xml).at(:name).inner_html
+        t       = Tag.new(name)
+        t.count = (xml).at(:count).inner_html
+        t.url   = Base.fix_url((xml).at(:url).inner_html)
+        t
+      end
+      
+      def top_tags
+        doc = fetch_and_parse("tag.getTopTags")
+        @top_tags = (doc/"toptags/tag").collect do |tag|
+          t       = Tag.new((tag/'name').inner_html)
+          t.count = (tag/'count').inner_html
+          t.url   = Base.fix_url((tag/'url').inner_html)
+          t
+        end
+      end
+    end
+    
+    def initialize(name)
+      raise ArgumentError, "Name is required" if name.blank?
+      @name = name
+    end
+    
+    
+    def top_artists(force=false)
+      get_instance("tag.getTopArtists", :top_artists, :artist, {:tag => @name}, force)
+    end
+    
+    def top_albums(force=false)
+      get_instance("tag.getTopAlbums", :top_albums, :album, {:tag => @name}, force)
+    end
+
+    def top_tracks(force=false)
+      get_instance("tag.getTopTracks", :top_tracks, :track, {:tag => @name}, force)
+    end
+  end
+end

data/lib/rockstar/tokenauth.rb

@@ -0,0 +1,84 @@
+require 'digest/md5'
+
+# exception definitions
+class BadAuthError < StandardError; end
+class BannedError < StandardError; end
+class BadTimeError < StandardError; end
+module Rockstar
+  
+  # = Token Authentification
+  #
+  # There are 2 ways to get an auth token : 
+  # 
+  # = Desktop-App
+  # 1. Get a new token to request authorisation:
+  #     token = Rockstar::Auth.new.token
+  # 2. Open a webbrowser with http://www.last.fm/api/auth/?api_key=xxxxxxxxxxx&token=xxxxxxxx
+  # 3. Wait for the User to confirm that he accepted your request. 
+  # 4. Continue with "Get the session token"
+  #
+  # = Web-App
+  # 1. Redirect the user to http://www.last.fm/api/auth/?api_key={YOUR_API_KEY}&amp;cb={YOUR_RETURN_URL}
+  # 2. If the user accepts, lastfm will redirect to YOUR_RETURN_URL?token=TOKEN
+  #     token = params[:token]
+  # 3. Continue with "Get the session token"
+  #
+  # = Get the session token
+  # 1. Use the previous token and call 
+  #     new Rockstar::Auth.new.session(token) 
+  # 2. Store the session.key and session.username returned. The session.key will not
+  #    expire. It is save to store it into your database.
+  # 3. Use this session.key as token to authentificate with this class :
+  #     auth = Rockstar::TokenAuth.new({:username => 'chunky', :token => 'bacon'})
+  #     auth.handshake!
+  # 
+  class TokenAuth
+    # you should read last.fm/api/submissions#handshake
+
+    attr_accessor :user, :token, :client_id, :client_ver
+    attr_reader :status, :session_id, :now_playing_url, :submission_url
+
+    def initialize(args = {})
+      @user = args[:username] # last.fm user
+      @token = args[:token] # last.fm token
+      @client_id = 'rbs' # Client ID assigned by last.fm; Don't change this!
+      @client_ver = Rockstar::Version
+
+      raise ArgumentError, 'Missing required argument' if @user.blank? || @token.blank?
+      
+      @connection = REST::Connection.new(Rockstar::AUTH_URL)
+    end
+
+    def handshake!
+      timestamp = Time.now.to_i.to_s
+      auth = Digest::MD5.hexdigest("#{Rockstar.lastfm_api_secret}#{timestamp}")
+
+      query = { :hs => 'true',
+                :p => AUTH_VER,
+                :c => @client_id,
+                :v => @client_ver,
+                :u => @user,
+                :t => timestamp,
+                :a => auth,
+                :api_key=>Rockstar.lastfm_api_key,
+                :sk => @token }
+      result = @connection.get('/', true, query)
+
+      @status = result.split(/\n/)[0]
+      case @status
+      when /OK/
+        @session_id, @now_playing_url, @submission_url = result.split(/\n/)[1,3]
+      when /BANNED/
+        raise BannedError # something is wrong with the gem, check for an update
+      when /BADAUTH/
+        raise BadAuthError # invalid user/password
+      when /FAILED/
+        raise RequestFailedError, @status
+      when /BADTIME/
+        raise BadTimeError # system time is way off
+      else
+        raise RequestFailedError
+      end  
+    end
+  end
+end

data/lib/rockstar/track.rb

@@ -0,0 +1,103 @@
+# Below is an example of how to get the top fans for a track.
+# 
+#   track = Rockstar::Track.new('Carrie Underwood', 'Before He Cheats')
+#   puts 'Fans'
+#   puts "=" * 4
+#   track.fans.each { |u| puts u.username }
+#   
+# Which would output something like:
+# 
+#   track = Rockstar::Track.new('Carrie Underwood', 'Before He Cheats')
+#   puts 'Fans'
+#   puts "=" * 4
+#   track.fans.each { |u| puts "(#{u.weight}) #{u.username}" }
+# 
+#   Fans
+#   ====
+#   (69163) PimpinRose
+#   (7225) selene204
+#   (7000) CelestiaLegends
+#   (6817) muehllr
+#   (5387) Mudley
+#   (5368) ilovejohnny1984
+#   (5232) MeganIAD
+#   (5132) Veric
+#   (5097) aeVnar
+#   (3390) kristaaan
+#   (3239) kelseaowns
+#   (2780) syndication
+#   (2735) mkumm
+#   (2706) Kimmybeebee
+#   (2648) skorpcroze
+#   (2549) mistergreg
+#   (2449) mlmjcace
+#   (2302) tiNEey
+#   (2169) ajsbabiegirl
+module Rockstar
+  class Track < Base
+    attr_accessor :artist, :artist_mbid, :name, :mbid, :playcount, :rank, :url
+    attr_accessor :streamable, :album, :album_mbid, :date, :date_uts
+    
+    # only seems to be used on top tracks for tag
+    attr_accessor :count, :thumbnail, :image, :images
+    
+    # for weekly top tracks
+    attr_accessor :chartposition
+    
+    class << self
+      def new_from_xml(xml, doc=nil)
+        artist          = (xml).at(:artist)['name']               if (xml).at(:artist) && !(xml).at(:artist)['name'].nil?
+        artist          = (xml).at(:artist).at(:name).inner_html  if artist.nil? && (xml).at(:artist) && (xml).at(:artist).at(:name)
+        artist          = (xml).at(:artist).inner_html            if artist.nil? && (xml).at(:artist)
+        artist          = doc.root['artist']                      if artist.nil? && doc.root['artist']
+        name            = (xml).at(:name).inner_html              if (xml).at(:name)
+        name            = xml['name']                             if name.nil? && xml['name']
+        t               = Track.new(artist, name)
+        t.artist_mbid   = (xml).at(:artist)['mbid']               if (xml).at(:artist) && (xml).at(:artist)['mbid']
+        t.artist_mbid   = (xml).at(:artist).at(:mbid).inner_html  if t.artist_mbid.nil? && (xml).at(:artist) && (xml).at(:artist).at(:mbid)
+        t.mbid          = (xml).at(:mbid).inner_html              if (xml).at(:mbid)
+        t.playcount     = (xml).at(:playcount).inner_html         if (xml).at(:playcount)
+        t.chartposition = t.rank = xml['rank']                    if xml['rank']
+        t.url           = Base.fix_url((xml).at(:url).inner_html) if (xml).at(:url)
+        t.streamable    = (xml).at(:track)['streamable']          if (xml).at(:track) && (xml).at(:track)['streamable']
+        t.streamable    = (xml).at(:streamable).inner_html == '1' ? 'yes' : 'no' if t.streamable.nil? && (xml).at(:streamable)
+        
+        t.count         = xml['count']                            if xml['count']
+        t.album         = (xml).at(:album).inner_html             if (xml).at(:album)
+        t.album_mbid    = (xml).at(:album)['mbid']                if (xml).at(:album) && (xml).at(:album)['mbid']
+        t.date          = Time.parse((xml).at(:date).inner_html)  if (xml).at(:date)
+        t.date_uts      = (xml).at(:date)['uts']                  if (xml).at(:date) && (xml).at(:date)['uts']
+        
+        t.images = {}
+        (xml/'image').each {|image|
+          t.images[image['size']] = image.inner_html
+        }
+        
+        t.thumbnail = t.images['small']
+        t.image     = t.images['medium']
+        t
+      end
+    end
+    
+    def initialize(artist, name)
+      raise ArgumentError, "Artist is required" if artist.blank?
+      raise ArgumentError, "Name is required" if name.blank?
+      @artist = artist
+      @name = name
+    end
+        
+    def fans(force=false)
+      get_instance("track.getTopFans", :fans, :user, {:track => @name, :artist => @artist}, force)
+    end
+    
+    def tags(force=false)
+      get_instance("track.getTopTags", :tags, :tag, {:track => @name, :artist => @artist}, force)
+    end
+    
+    # The session_key is returned by auth.session.key
+    def love(session_key)
+      doc = Hpricot::XML(self.class.connection.post("track.love", true, {:track => @name, :artist => @artist, :sk => session_key}))
+      doc.at("lfm")["status"]
+    end
+  end
+end

data/lib/rockstar/user.rb

@@ -0,0 +1,194 @@
+# Probably the most common use of this lib would be to get your most recent tracks or your top tracks. Below are some code samples.
+#   user = Rockstar::User.new('jnunemaker')
+# 
+#   puts "#{user.username}'s Recent Tracks"
+#   puts "=" * (user.username.length + 16)
+#   user.recent_tracks.each { |t| puts t.name }
+# 
+#   puts
+#   puts
+# 
+#   puts "#{user.username}'s Top Tracks"
+#   puts "=" * (user.username.length + 13)
+#   user.top_tracks.each { |t| puts "(#{t.playcount}) #{t.name}" }
+#   
+# Which would output something like:
+#
+#   jnunemaker's Recent Tracks
+#   ==========================
+#   Everything You Want
+#   You're a God
+#   Bitter Sweet Symphony [Original Version]
+#   Lord I Guess I'll Never Know
+#   Country Song
+#   Bitter Sweet Symphony (Radio Edit)
+# 
+# 
+#   jnunemaker's Top Tracks
+#   =======================
+#   (62) Probably Wouldn't Be This Way
+#   (55) Not Ready To Make Nice
+#   (45) Easy Silence
+#   (43) Song 2
+#   (40) Everybody Knows
+#   (39) Before He Cheats
+#   (39) Something's Gotta Give
+#   (38) Hips Don't Lie (featuring Wyclef Jean)
+#   (37) Unwritten
+#   (37) Move Along
+#   (37) Dance, Dance
+#   (36) We Belong Together
+#   (36) Jesus, Take the Wheel
+#   (36) Black Horse and the Cherry Tree (radio version)
+#   (35) Photograph
+#   (35) You're Beautiful
+#   (35) Walk Away
+#   (34) Stickwitu
+module Rockstar  
+  class User < Base
+    # attributes needed to initialize
+    attr_reader :username
+    
+    # profile attributes
+    attr_accessor :id, :cluster, :url, :realname, :mbox_sha1sum, :registered
+    attr_accessor :registered_unixtime, :age, :gender, :country, :playcount, :avatar, :realname, :images
+
+    # neighbor attributes
+    attr_accessor :match
+    
+    # track fans attributes
+    attr_accessor :weight
+    
+    class << self
+      def new_from_xml(xml, doc=nil)
+        u        = User.new((xml).at(:name).inner_html)
+        u.url    = Base.fix_url((xml).at(:url).inner_html)    if (xml).at(:url)
+        
+        u.images = {}
+        (xml/'image').each {|image|
+          u.images[image['size']] = image.inner_html
+        }
+        
+        u.avatar = u.images['small']
+        
+        u.weight = (xml).at(:weight).inner_html if (xml).at(:weight)
+        u.match  = (xml).at(:match).inner_html  if (xml).at(:match)
+        u.realname= (xml).at(:realname).inner_html    if (xml).at(:realname)
+        u
+      end
+      
+      def find(*args)
+        options = {:include_profile => false}
+        options.merge!(args.pop) if args.last.is_a?(Hash)
+        users = args.flatten.inject([]) { |users, u| users << User.new(u, options); users }
+        users.length == 1 ? users.pop : users
+      end
+    end
+    
+    def initialize(username, o={})
+      options = {:include_profile => false}.merge(o)
+      raise ArgumentError if username.blank?
+      @username = username
+      load_profile() if options[:include_profile]
+    end
+    
+    def current_events(format=:ics)
+      warn "[DEPRECATION] `current_events` is deprecated. The current api doesn't offer ics/ical formatted data."
+    end
+    
+    def friends_events(format=:ics)
+      warn "[DEPRECATION] `friends_events` is deprecated. The current api doesn't offer ics/ical formatted data."
+    end
+    
+    def recommended_events(format=:ics)
+      warn "[DEPRECATION] `recommended_events` is deprecated. The current api doesn't offer ics/ical formatted data."
+    end
+    
+    def load_profile
+      doc                  = self.class.fetch_and_parse("user.getInfo", {:user => @username})
+      @id                  = (doc).at(:id).inner_html
+      @url                 = Base.fix_url((doc).at(:url).inner_html)
+      @realname            = (doc).at(:realname).inner_html
+      @registered          = (doc).at(:registered).inner_html
+      @registered_unixtime = (doc).at(:registered)['unixtime']
+      @age                 = (doc).at(:age).inner_html
+      @gender              = (doc).at(:gender).inner_html
+      @country             = (doc).at(:country).inner_html
+      @playcount           = (doc).at(:playcount).inner_html
+      
+      @images = {}
+      (doc/'image').each {|image|
+        @images[image['size']] = image.inner_html
+      }
+      
+      @avatar              = @images["small"]
+    end
+    
+    def top_artists(force=false)
+      get_instance("user.getTopArtists", :top_artists, :artist, {:user => @username}, force)
+    end
+    
+    def top_albums(force=false)
+      get_instance("user.getTopAlbums", :top_albums, :album, {:user => @username}, force)
+    end
+    
+    def top_tracks(force=false)
+      get_instance("user.getTopTracks", :top_tracks, :track, {:user => @username}, force)
+    end
+    
+    def top_tags(force=false)
+      get_instance("user.getTopTags", :top_tags, :tag, {:user => @username}, force)
+    end
+    
+    def friends(force=false)
+      get_instance("user.getFriends", :friends, :user, {:user => @username}, force)
+    end
+    
+    def neighbours(force=false)
+      get_instance("user.getNeighbours", :neighbours, :user, {:user => @username}, force)
+    end
+    
+    def recent_tracks(force=false)
+      get_instance("user.getRecentTracks", :recent_tracks, :track, {:user => @username}, force)
+    end
+    
+    def recent_banned_tracks(force=false)
+      warn "[DEPRECATION] `recent_banned_tracks` is deprecated. The current api doesn't offer this function"
+      []
+    end
+    
+    def recent_loved_tracks(force=false)
+      get_instance("user.getLovedTracks", :recent_loved_tracks, :track, {:user => @username}, force)
+    end
+    
+    def recommendations(force=false)
+      warn "[DEPRECATION] `recommendations` is deprecated. Please use recommended_artists"
+      []
+    end
+
+    # The session_key is returned by auth.session.key
+    def recommended_artists(session_key, force=false)
+      get_instance("user.getRecommendedArtists", :recommendations, :artist, {:user => @username, :sk => session_key}, force)
+    end
+    
+    def charts(force=false)
+      get_instance("user.getWeeklyChartList", :charts, :chart, {:user => @username}, force)
+    end
+    
+    def weekly_artist_chart(from=nil, to=nil)
+      doc = self.class.fetch_and_parse("user.getWeeklyArtistChart", {:user => @username, :from => from, :to => to})
+      (doc/:artist).inject([]) { |elements, el| elements << Artist.new_from_xml(el); elements }
+    end
+    
+    def weekly_album_chart(from=nil, to=nil)
+      doc = self.class.fetch_and_parse("user.getWeeklyAlbumChart", {:user => @username, :from => from, :to => to})
+      (doc/:album).inject([]) { |elements, el| elements << Album.new_from_xml(el); elements }
+    end
+    
+    def weekly_track_chart(from=nil, to=nil)
+      doc = self.class.fetch_and_parse("user.getWeeklyTrackChart", {:user => @username, :from => from, :to => to})
+      (doc/:track).inject([]) { |elements, el| elements << Track.new_from_xml(el); elements }
+    end
+    
+  end
+end