turntabler 0.0.1

data/lib/turntabler/song.rb

@@ -0,0 +1,247 @@
+require 'turntabler/error'
+require 'turntabler/resource'
+require 'turntabler/user'
+require 'turntabler/vote'
+
+module Turntabler
+  # Represents a song that can be played on Turntable
+  class Song < Resource
+    # The title of the song
+    # @return [String]
+    attribute :title, :song
+
+    # The standard code id for this song
+    # @return [String]
+    attribute :isrc
+
+    # The name of the artist
+    # @return [String]
+    attribute :artist
+
+    # The name of the album this song is on
+    # @return [String]
+    attribute :album
+
+    # The type of music
+    # @return [String]
+    attribute :genre
+
+    # The label that produced the music
+    # @return [String]
+    attribute :label
+
+    # The URL for the cover art image
+    # @return [String]
+    attribute :cover_art_url, :coverart
+
+    # Number of seconds the song lasts
+    # @return [Fixnum]
+    attribute :length
+
+    # Whether this song can be snagged
+    # @return [Boolean]
+    attribute :snaggable
+    
+    # The source from which the song was uploaded
+    # @return [String]
+    attribute :source
+    
+    # The id of the song on the original source service
+    # @return [String]
+    attribute :source_id, :sourceid
+    
+    # The number of up votes this song has received.
+    # @note This is only available for the current song playing in a room
+    # @return [Fixnum]
+    attribute :up_votes_count, :upvotes, :load => false
+    
+    # The number of down votes this song has received.
+    # @note This is only available for the current song playing in a room
+    # @return [Fixnum]
+    attribute :down_votes_count, :downvotes, :load => false
+    
+    # The log of votes this song has received.  This will only include up votes
+    # or down votes that were previously up votes.
+    # @note This is only available for the current song playing in a room
+    # @return [Array<Vote>]
+    attribute :votes, :votelog, :load => false do |votes|
+      votes.each do |(user_id, direction)|
+        self.votes.delete_if {|vote| vote.user.id == user_id}
+        self.votes << Vote.new(client, :userid => user_id, :direction => direction)
+      end
+      self.votes
+    end
+    
+    # The percentage score for this song based on the number of votes
+    # @note This is only available for the current song playing in a room
+    # @return [Float]
+    attribute :score, :load => false
+    
+    # The DJ that played this song
+    # @note This is only available for the current song playing in a room
+    # @return [Turntabler::User]
+    attribute :played_by, :djid, :load => false do |value|
+      room? ? room.build_user(:_id => value) : User.new(client, :_id => value)
+    end
+
+    # @api private
+    def initialize(*)
+      @up_votes_count = 0
+      @down_votes_count = 0
+      @votes = []
+      @score = 0
+      super
+    end
+
+    # Loads the attributes for this song.  Attributes will automatically load
+    # when accessed, but this allows data to be forcefully loaded upfront.
+    # 
+    # @return [true]
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   song.load     # => true
+    #   song.title    # => "..."
+    def load
+      data = api('playlist.get_metadata', :playlist_name => 'default', :files => [id])
+      self.attributes = data['files'][id]
+      super
+    end
+
+    # Skips the song.
+    # 
+    # @return [true]
+    # @raise [Turntabler::Error] if the command fails
+    # @raise [Turntabler::Error] if the song is not playing in the current song
+    # @example
+    #   song.skip   # => true
+    def skip
+      assert_current_song
+      api('room.stop_song', :roomid => room.id, :section => room.section)
+      true
+    end
+
+    # Vote for the song.
+    # 
+    # @param [Symbol] direction The direction to vote the song (:up or :down)
+    # @return [true]
+    # @raise [Turntabler::Error] if the command fails
+    # @raise [Turntabler::Error] if the song is not playing in the current song
+    # @example
+    #   song.vote         # => true
+    #   song.vote(:down)  # => true
+    def vote(direction = :up)
+      assert_current_song
+      api('room.vote',
+        :roomid => room.id,
+        :section => room.section,
+        :val => direction,
+        :songid => id,
+        :vh => digest("#{room.id}#{direction}#{id}"),
+        :th => digest(rand),
+        :ph => digest(rand)
+      )
+      true
+    end
+
+    # Triggers the heart animation for the song.
+    # 
+    # @note This will not add the song to the user's playlist
+    # @return [true]
+    # @raise [Turntabler::Error] if the command fails
+    # @raise [Turntabler::Error] if the song is not playing in the current song
+    # @example
+    #   song.snag   # => true
+    def snag
+      assert_current_song
+      sh = digest(rand)
+      api('snag.add',
+        :djid => room.current_dj.id,
+        :songid => id,
+        :roomid => room.id,
+        :section => room.section,
+        :site => 'queue',
+        :location => 'board',
+        :in_queue => 'false',
+        :blocked => 'false',
+        :vh => digest([client.user.id, room.current_dj.id, id, room.id, 'queue', 'board', 'false', 'false', sh] * '/'),
+        :sh => sh,
+        :fh => digest(rand)
+      )
+      true
+    end
+    
+    # Adds the song to one of the user's playlists.
+    # 
+    # @param [Hash] options The options for where to add the song
+    # @option options [String] :playlist ("default") The playlist to enqueue the song in
+    # @option options [Fixnum] :index (0) The location in the playlist to insert the song
+    # @return [true]
+    # @raise [ArgumentError] if an invalid option is specified
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   song.enqueue(:index => 1)   # => true
+    def enqueue(options = {})
+      assert_valid_keys(options, :playlist, :index)
+      options = {:playlist => 'default', :index => 0}.merge(options)
+      playlist, index = client.user.playlist(options[:playlist]), options[:index]
+
+      api('playlist.add', :playlist_name => playlist.id, :song_dict => {:fileid => id}, :index => index)
+      playlist.songs.insert(index, self) if playlist.loaded?
+      true
+    end
+    
+    # Removes the song from the playlist at the given index.
+    # 
+    # @param [Hash] options The options for where to remove the song
+    # @option options [String] :playlist ("default") The playlist to dequeue the song from
+    # @return [true]
+    # @raise [ArgumentError] if an invalid option is specified
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   song.dequeue    # => true
+    def dequeue(options = {})
+      assert_valid_keys(options, :playlist)
+      options = {:playlist => 'default'}.merge(options)
+      playlist, index = index(options[:playlist])
+
+      api('playlist.remove', :playlist_name => playlist.id, :index => index)
+      playlist.songs.delete(self)
+      true
+    end
+
+    # Move a song from one location in the playlist to another.
+    # 
+    # @param [Fixnum] to_index The index to move the song to
+    # @param [Hash] options The options for where to remove the song
+    # @option options [String] :playlist ("default") The playlist to move the song within
+    # @return [true]
+    # @raise [ArgumentError] if an invalid option is specified
+    # @raise [Turntabler::Error] if the command fails
+    #   song.move(5)    # => true
+    def move(to_index, options = {})
+      assert_valid_keys(options, :playlist)
+      options = {:playlist => 'default'}.merge(options)
+      playlist, index = index(options[:playlist])
+
+      api('playlist.reorder', :playlist_name => playlist.id, :index_from => index, :index_to => to_index)
+      playlist.songs.insert(to_index, playlist.songs.delete(self))
+      true
+    end
+    
+    private
+    # Asserts that this is the song currently being played in the room the user
+    # is in.  Raises Turntabler::Error if this is not the case.
+    def assert_current_song
+      raise(Turntabler::Error, "Song \"#{id}\" is not currently playing") unless room.current_song == self
+    end
+    
+    # Gets the index of this song within the given playlist.  Raises Turntabler::Error
+    # if the song cannot be found in the playlist.
+    def index(playlist_id)
+      playlist = client.user.playlist(playlist_id)
+      index = playlist.songs.index(self)
+      raise(Turntabler::Error, "Song \"#{id}\" is not in playlist \"#{playlist.id}\"") unless index
+      return playlist, index
+    end
+  end
+end

data/lib/turntabler/sticker.rb

@@ -0,0 +1,48 @@
+require 'turntabler/resource'
+
+module Turntabler
+  # Represents a virtual sticker that can be placed on a user
+  class Sticker < Resource
+    # Allow the id to be set via the "sticker_id" attribute
+    # @return [String]
+    attribute :id, :sticker_id
+
+    # The human-readable name for the sticker
+    # @return [String]
+    attribute :name
+
+    # A longer explanation for the sticker
+    # @return [String]
+    attribute :description
+
+    # The type of sticker (such as "laptop_sticker")
+    # @return [String]
+    attribute :category
+
+    # How much it costs to purchase this sticker for use
+    # @return [Fixnum]
+    attribute :price
+
+    # Whether this sticker can be used ("active")
+    # @return [String]
+    attribute :state
+
+    # The uri for the sticker
+    # @return [String]
+    attribute :path
+
+    # Sets the current user's stickers.
+    # 
+    # @param [Fixnum] top The y-coordinate of the sticker
+    # @param [Fixnum] left The x-coordinate of the sticker
+    # @param [Fixnum] angle The degree at which the sticker is angled
+    # @return [true]
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   sticker.place(126, 78, -23)   # => true
+    def place(top, left, angle)
+      api('sticker.place', :placement => [:sticker_id => id, :top => top, :left => left, :angle => angle], :is_dj => client.user.dj?, :roomid => room.id, :section => room.section)
+      true
+    end
+  end
+end

data/lib/turntabler/sticker_placement.rb

@@ -0,0 +1,25 @@
+require 'turntabler/resource'
+require 'turntabler/sticker'
+
+module Turntabler
+  # Represents a sticker that's been placed on a user's laptop
+  class StickerPlacement < Resource
+    # The sticker that's been placed
+    # @return [Turntabler::Sticker]
+    attribute :sticker, :sticker_id do |value|
+      Sticker.new(client, :_id => value)
+    end
+
+    # The y-coordinate for the sticker
+    # @return [Fixnum]
+    attribute :top
+
+    # The x-coordinate for the sticker
+    # @return [Fixnum]
+    attribute :left
+
+    # The degree at which the sticker is tilted
+    # @return [Fixnum]
+    attribute :angle
+  end
+end

data/lib/turntabler/user.rb

@@ -0,0 +1,274 @@
+require 'turntabler/resource'
+require 'turntabler/avatar'
+require 'turntabler/message'
+require 'turntabler/sticker_placement'
+
+module Turntabler
+  # Represents an unauthorized user on Turntable
+  class User < Resource
+    # Allow the id to be set via the "userid" attribute
+    # @return [String]
+    attribute :id, :userid, :load => false
+
+    # The DJ name for this user
+    # @return [String]
+    attribute :name, :name, :username
+
+    # The name of the laptop the DJ uses
+    # @return [String]
+    attribute :laptop_name, :laptop
+
+    # The version # for the laptop
+    # @return [String]
+    attribute :laptop_version
+
+    # The total number of points accumulated all-time
+    # @return [Fixnum]
+    attribute :points
+
+    # The access control determining what is authorized
+    # @return [Fixnum]
+    attribute :acl
+
+    # The number of fans this user has
+    # @return [Fixnum]
+    attribute :fans_count, :fans
+
+    # The user's unique identifier on Facebook (only available if the user is
+    # connected to the authorized user through Facebook)
+    # @return [String]
+    attribute :facebook_url, :facebook
+    
+    # The user's unique identifier on Twitter (only available if the user is
+    # connected to the authorized user through Twitter)
+    # @return [String]
+    attribute :twitter_id, :twitter, :twitterid_lower
+
+    # The user's personal website
+    # @return [String]
+    attribute :website
+
+    # A brief description about the user
+    # @return [String]
+    attribute :about
+
+    # The user's favorite artists
+    # @return [String]
+    attribute :top_artists, :topartists
+
+    # Whether on Turntable the user likes to hang out
+    # @return [String]
+    attribute :hangout
+
+    # The user's currently active avatar
+    # @return [Turntabler::Avatar]
+    attribute :avatar, :avatarid do |value|
+      Avatar.new(client, :_id => value)
+    end
+
+    # The placements of stickers on the user's laptop
+    # @return [Array<Turntabler::StickerPlacement>]
+    attribute :sticker_placements, :placements do |placements|
+      placements.map {|attrs| StickerPlacement.new(client, attrs)}
+    end
+
+    # Loads the attributes for this user.  Attributes will automatically load
+    # when accessed, but this allows data to be forcefully loaded upfront.
+    # 
+    # @return [true]
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   user.load         # => true
+    #   user.laptop_name  # => "chrome"
+    def load
+      data = api('user.get_profile', :userid => id)
+      self.attributes = data
+      super
+    end
+    
+    # Gets the availability status for this user.
+    # 
+    # @return [String] "available" / "unavailable"
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   user.presence   # => "available"
+    def presence
+      data = api('presence.get', :uid => id)
+      data['presence']['status']
+    end
+
+    # Gets the stickers that are currently placed on the user.
+    # 
+    # @param [Boolean] reload Whether to forcefully reload the user's list of sticker placements
+    # @return [Array<Turntabler::StickerPlacement>]
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   user.sticker_placements   # => [#<Turntabler::StickerPlacement ...>, ...]
+    def sticker_placements(reload = false)
+      self.attributes = api('sticker.get_placements', :userid => id) if reload || !@sticker_placements
+      @sticker_placements
+    end
+
+    # Marks the current user as a fan of this user.
+    # 
+    # @return [true]
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   user.become_fan   # => true
+    def become_fan
+      api('user.become_fan', :djid => id)
+      true
+    end
+
+    # Marks the current user no longer as a fan of this user.
+    # 
+    # @return [true]
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   user.unfan    # => true
+    def unfan
+      api('user.remove_fan', :djid => id)
+      true
+    end
+
+    # Sends a private message to this user.
+    # 
+    # @return [true]
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   user.say("Hey what's up?")    # => true
+    def say(content)
+      api('pm.send', :receiverid => id, :text => content)
+      true
+    end
+
+    # Gets the private conversation history with this user.
+    # 
+    # @return [Array<Turntabler::Message>]
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   user.messages   # => [#<Turntabler::Message ...>, ...]
+    def messages
+      data = api('pm.history', :receiverid => id)
+      data['history'].map {|attrs| Message.new(client, attrs)}
+    end
+
+    # Is the user currently a listener in the room?
+    # 
+    # @return [Boolean] +true+ if the user is a listener, otherwise +false+
+    # @example
+    #   user.listener?    # => false
+    def listener?
+      !room.listener(id).nil?
+    end
+
+    # Is the user currently DJing in the room?
+    # 
+    # @return [Boolean] +true+ if the user is a dj, otherwise +false+
+    # @example
+    #   user.dj?    # => false
+    def dj?
+      !room.dj(id).nil?
+    end
+
+    # Stops the user from DJing.
+    # 
+    # @return [true]
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   user.remove_as_dj   # => true
+    def remove_as_dj
+      api('room.rem_dj', :roomid => room.id, :section => room.section, :djid => id)
+      true
+    end
+
+    # Is the user currently a moderator for the room?
+    # 
+    # @return [Boolean] +true+ if the user is a moderator, otherwise +false+
+    # @example
+    #   user.moderator?   # => false
+    def moderator?
+      !room.moderator(id).nil?
+    end
+
+    # Adds the user as a moderator in the current room.
+    # 
+    #   user.add_as_moderator   # => true
+    def add_as_moderator
+      api('room.add_moderator', :roomid => room.id, :section => room.section, :target_userid => id)
+      true
+    end
+
+    # Removes the user from being a moderator in the current room.
+    # 
+    # @return [true]
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   user.remove_as_moderator    # => true
+    def remove_as_moderator
+      api('room.rem_moderator', :roomid => room.id, :section => room.section, :target_userid => id)
+      true
+    end
+
+    # Gets the location of the user.
+    # 
+    # @note This will make the current user a fan of this user
+    # @param [Boolean] all_info Whether full detailed information should be provided about the room and user
+    # @return [Array<Turntabler::Room>]
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   user.stalk    # => #<Turntabler::User ...>
+    def stalk(all_info = false)
+      become_fan unless client.user.fan_of.include?(self)
+      client.rooms.with_friends.detect do |room|
+        room.listener(id)
+      end
+    end
+
+    # Blocks this user from being able to send private messages.
+    # 
+    # @return [true]
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   user.block    # => true
+    def block
+      api('block.add', :blockedid => id)
+      true
+    end
+
+    # Unblocks this user from being able to send private messages.
+    # 
+    # @return [true]
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   user.unblock    # => true
+    def unblock
+      api('block.remove', :blockedid => id)
+      true
+    end
+
+    # Boots the user for the specified reason.
+    # 
+    # @param [String] reason The reason why the user is being booted
+    # @return [true]
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   user.boot('Broke rules')    # => true
+    def boot(reason = '')
+      api('room.boot_user', :roomid => room.id, :section => room.section, :target_userid => id, :reason => reason)
+      true
+    end
+
+    # Reports abuse by a user.
+    # 
+    # @param [String] reason The reason the user is being reported
+    # @return [true]
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   user.report('Verbal abuse ...')  # => true
+    def report(reason = '')
+      api('room.report_user', :roomid => room.id, :section => room.section, :reported => id, :reason => reason)
+      true
+    end
+  end
+end

data/lib/turntabler/version.rb

@@ -0,0 +1,9 @@
+module Turntabler
+  # The current version of the library
+  module Version
+    MAJOR = 0
+    MINOR = 0
+    PATCH = 1
+    STRING = [MAJOR, MINOR, PATCH].join(".")
+  end
+end

data/lib/turntabler/vote.rb

@@ -0,0 +1,19 @@
+require 'turntabler/resource'
+require 'turntabler/user'
+
+module Turntabler
+  # Represents a vote that was made within a room
+  class Vote < Resource
+    # The user who cast the vote
+    # @return [Turntabler::User]
+    attribute :user, :userid do |value|
+      room? ? room.build_user(:_id => value) : User.new(client, :_id => value)
+    end
+
+    # Whether the user voted +:up+ or +:down+
+    # @return [Symbol]
+    attribute :direction do |value|
+      value.to_sym
+    end
+  end
+end