kappa 0.3.0 → 0.4.0

data/lib/kappa/team.rb

@@ -1,13 +1,13 @@
 require 'time'
 
-module Kappa::V2
+module Twitch::V2
   # Teams are an organization of channels.
-  # @see .get Team.get
+  # @see Teams#get Teams#get
+  # @see Teams#all Teams#all
   # @see Teams
   # @see Channel
   class Team
-    include Connection
-    include Kappa::IdEquality
+    include Twitch::IdEquality
     
     # @private
     def initialize(hash)
@@ -23,74 +23,96 @@ module Kappa::V2
       @url = "http://www.twitch.tv/team/#{@name}"
     end
 
-    # Get a team by name.
-    # @param team_name [String] The name of the team to get.
-    # @return [Team] A valid `Team` object if the team exists, `nil` otherwise.
-    # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/teams.md#get-teamsteam GET /teams/:team
-    def self.get(team_name)
-      json = connection.get("teams/#{team_name}")
-      if json['status'] == 404
-        nil
-      else
-        new(json)
-      end
-    end
-
+    # @example
+    #   12
     # @return [Fixnum] Unique Twitch ID.
     attr_reader :id
 
+    # @example
+    #   "TeamLiquid is awesome. and esports. video games. \n\n"
     # @return [String] Info about the team. This is displayed on the team's page and can contain HTML.
     attr_reader :info
 
+    # @example
+    #   "http://static-cdn.jtvnw.net/jtv_user_pictures/team-eg-background_image-da36973b6d829ac6.png"
     # @return [String] URL for background image.
     attr_reader :background_url
 
+    # @example
+    #   "http://static-cdn.jtvnw.net/jtv_user_pictures/team-eg-banner_image-1ad9c4738f4698b1-640x125.png"
     # @return [String] URL for banner image.
     attr_reader :banner_url
 
+    # @example
+    #   "http://static-cdn.jtvnw.net/jtv_user_pictures/team-eg-team_logo_image-9107b874d4c3fc3b-300x300.jpeg"
     # @return [String] URL for the logo image.
     attr_reader :logo_url
 
+    # @example
+    #   "teamliquid"
+    # @see #display_name
     # @return [String] Unique Twitch name.
     attr_reader :name
 
+    # @example
+    #   "TeamLiquid"
+    # @see #name
     # @return [String] User-friendly display name. This name is used for the team's page title.
     attr_reader :display_name
 
+    # @example
+    #   2013-05-24 00:17:10 UTC
     # @return [Time] When the team was last updated (UTC).
     attr_reader :updated_at
 
+    # @example
+    #   2011-10-27 01:00:44 UTC
     # @return [Time] When the team was created (UTC).
     attr_reader :created_at
 
     # @example
-    #   "http://www.twitch.tv/team/root"
+    #   "http://www.twitch.tv/team/teamliquid"
     # @return [String] URL for the team's Twitch landing page.
     attr_reader :url
   end
 
-  # Query class used for finding all active teams.
+  # Query class for finding all active teams.
   # @see Team
   class Teams
-    include Connection
+    # @private
+    def initialize(query)
+      @query = query
+    end
+
+    # Get a team by name.
+    # @example
+    #   Twitch.teams.get('teamliquid')
+    # @param team_name [String] The name of the team to get.
+    # @return [Team] A valid `Team` object if the team exists, `nil` otherwise.
+    # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/teams.md#get-teamsteam GET /teams/:team
+    def get(team_name)
+      json = @query.connection.get("teams/#{team_name}")
+      if json['status'] == 404
+        nil
+      else
+        Team.new(json)
+      end
+    end
 
     # Get the list of all active teams.
     # @example
-    #   Teams.all
+    #   Twitch.teams.all
     # @example
-    #   Teams.all(:limit => 10)
+    #   Twitch.teams.all(:limit => 10)
     # @param options [Hash] Filter criteria.
     # @option options [Fixnum] :limit (none) Limit on the number of results returned.
     # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/teams.md#get-teams GET /teams
     # @return [Array<Team>] List of all active teams.
-    def self.all(options = {})
-      params = {}
-
-      return connection.accumulate(
+    def all(options = {})
+      return @query.connection.accumulate(
         :path => 'teams',
-        :params => params,
         :json => 'teams',
-        :class => Team,
+        :create => Team,
         :limit => options[:limit],
         :offset => options[:offset]
       )

data/lib/kappa/user.rb

@@ -1,19 +1,20 @@
 require 'cgi'
 require 'time'
 
-module Kappa::V2
+module Twitch::V2
   # These are members of the Twitch community who have a Twitch account. If broadcasting,
   # they can own a stream that they can broadcast on their channel. If mainly viewing,
   # they might follow or subscribe to channels.
-  # @see .get User.get
+  # @see Users#get Users#get
+  # @see Users
   # @see Channel
   # @see Stream
   class User
-    include Connection
-    include Kappa::IdEquality
+    include Twitch::IdEquality
 
     # @private
-    def initialize(hash)
+    def initialize(hash, query)
+      @query = query
       @id = hash['_id']
       @created_at = Time.parse(hash['created_at']).utc
       @display_name = hash['display_name']
@@ -23,26 +24,12 @@ module Kappa::V2
       @updated_at = Time.parse(hash['updated_at']).utc
     end
 
-    # Get a user by name.
-    # @param user_name [String] The name of the user to get. This is the same as the channel or stream name.
-    # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/users.md#get-usersuser GET /users/:user
-    # @return [User] A valid `User` object if the user exists, `nil` otherwise.
-    def self.get(user_name)
-      encoded_name = CGI.escape(user_name)
-      json = connection.get("users/#{encoded_name}")
-      if !json || json['status'] == 404
-        nil
-      else
-        new(json)
-      end
-    end
-
     # Get the `Channel` associated with this user.
     # @note This incurs an additional web request.
     # @return [Channel] The `Channel` associated with this user, or `nil` if this is a Justin.tv account.
-    # @see Channel.get
+    # @see Channel#get Channel#get
     def channel
-      Channel.get(@name)
+      @query.channels.get(@name)
     end
 
     # Get the live stream associated with this user.
@@ -50,7 +37,7 @@ module Kappa::V2
     # @return [Stream] Live stream object for this user, or `nil` if the user is not currently streaming.
     # @see #streaming?
     def stream
-      Stream.get(@name)
+      @query.streams.get(@name)
     end
 
     # Is this user currently streaming?
@@ -74,51 +61,87 @@ module Kappa::V2
     # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/follows.md#get-usersuserfollowschannels GET /users/:user/follows/channels
     # @return [Array<Channel>] List of channels the user is currently following.
     def following(options = {})
-      return connection.accumulate(
+      return @query.connection.accumulate(
         :path => "users/#{@name}/follows/channels",
         :json => 'follows',
         :sub_json => 'channel',
-        :class => Channel,
+        :create => -> hash { Channel.new(hash, @query) },
         :limit => options[:limit],
         :offset => options[:offset]
       )
     end
 
-    # @param channel [String, Channel] The name of the channel (or `Channel` object) to check.
+    # @param channel [String/Channel/User/Stream/#name] The name of the channel to check.
     # @return [Boolean] `true` if the user is following the channel, `false` otherwise.
     # @see #following
     # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/follows.md#get-usersuserfollowschannelstarget GET /users/:user/follows/:channels/:target
-    def following?(channel)
-      channel_name = case channel
-        when String
-          channel
-        when Channel
-          channel.name
+    def following?(target)
+      name = if target.respond_to?(:name)
+        target.name
+      else
+        target.to_s
       end
 
-      channel_name = CGI.escape(channel_name)
+      name = CGI.escape(name)
 
-      json = connection.get("users/#{@name}/follows/channels/#{channel_name}")
+      json = @query.connection.get("users/#{@name}/follows/channels/#{name}")
       status = json['status']
       return !status || (status != 404)
     end
 
+    # @example
+    #   23945610 
     # @return [Fixnum] Unique Twitch ID.
     attr_reader :id
 
+    # @example
+    #   2011-08-08 21:03:44 UTC
     # @return [Time] When the user account was created (UTC).
     attr_reader :created_at
 
+    # @example
+    #   2013-07-19 23:51:43 UTC
     # @return [Time] When the user account was last updated (UTC).
     attr_reader :updated_at
 
+    # @example
+    #   "LAGTVMaximusBlack"
     # @return [String] User-friendly display name.
     attr_reader :display_name
 
+    # @example
+    #   "http://static-cdn.jtvnw.net/jtv_user_pictures/lagtvmaximusblack-profile_image-4b77a2305f5d85c8-300x300.png"
     # @return [String] URL for the logo image.
     attr_reader :logo_url
 
+    # @example
+    #   "lagtvmaximusblack"
     # @return [String] Unique Twitch name.
     attr_reader :name
   end
+
+  # Query class for finding users.
+  # @see User
+  class Users
+    # @private
+    def initialize(query)
+      @query = query
+    end
+
+    # Get a user by name.
+    # @example
+    #   Twitch.users.get('totalbiscuit')
+    # @param user_name [String] The name of the user to get. This is the same as the channel or stream name.
+    # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/users.md#get-usersuser GET /users/:user
+    # @return [User] A valid `User` object if the user exists, `nil` otherwise.
+    def get(user_name)
+      encoded_name = CGI.escape(user_name)
+      json = @query.connection.get("users/#{encoded_name}")
+      if !json || json['status'] == 404
+        nil
+      else
+        User.new(json, @query)
+      end
+    end
+  end
 end

data/lib/kappa/version.rb

@@ -1,3 +1,3 @@
-module Kappa
-  VERSION = '0.3.0'
+module Twitch
+  VERSION = '0.4.0'
 end

data/lib/kappa/video.rb

@@ -1,12 +1,13 @@
 require 'cgi'
 require 'time'
 
-module Kappa::V2
+module Twitch::V2
   # @private
   class ChannelProxy
-    def initialize(name, display_name)
+    def initialize(name, display_name, query)
       @name = name
       @display_name = display_name
+      @query = query
     end
 
     attr_reader :name
@@ -15,22 +16,22 @@ module Kappa::V2
     include Proxy
 
     proxy {
-      Channel.get(@name)
+      @query.channels.get(@name)
     }
   end
 
   # Videos are broadcasts or highlights owned by a channel. Broadcasts are unedited
   # videos that are saved after a streaming session. Highlights are videos edited from
   # broadcasts by the channel's owner.
-  # @see .get Video.get
+  # @see Videos#get Videos#get
+  # @see Videos#top Videos#top
   # @see Videos
   # @see Channel
   class Video
-    include Connection
-    include Kappa::IdEquality
+    include Twitch::IdEquality
 
     # @private
-    def initialize(hash)
+    def initialize(hash, query)
       @id = hash['_id']
       @title = hash['title']
       @recorded_at = Time.parse(hash['recorded_at']).utc
@@ -40,48 +41,38 @@ module Kappa::V2
       @length = hash['length']
       @game_name = hash['game']
       @preview_url = hash['preview']
+      @embed_html = hash['embed']
 
       @channel = ChannelProxy.new(
         hash['channel']['name'],
-        hash['channel']['display_name']
+        hash['channel']['display_name'],
+        query
       )
     end
 
-    # Get a video by ID.
-    # @example
-    #   v = Video.get('a396294648')
-    #   v.title # => "DreamHack Open Stockholm 26-27 April"
-    # @param id [String] The ID of the video to get.
-    # @raise [ArgumentError] If `id` is `nil` or blank.
-    # @return [Video] A valid `Video` object if the video exists, `nil` otherwise.
-    def self.get(id)
-      raise ArgumentError if !id || id.strip.empty?
-
-      encoded_id = CGI.escape(id)
-      json = connection.get("videos/#{encoded_id}")
-      if !json || json['status'] == 404
-        nil
-      else
-        new(json)
-      end
-    end
-
     # @note This is a `String`, not a `Fixnum` like most other object IDs.
     # @example
-    #   v = Video.get('a396294648')
-    #   v.id # => "a396294648"
+    #   "a396294648"
     # @return [String] Unique Twitch ID for this video.
     attr_reader :id
 
+    # @example
+    #   "DreamHack Open Stockholm 26-27 April"
     # @return [String] Title of this video. This is seen on the video's page.
     attr_reader :title
 
+    # @example
+    #   2013-04-27 09:37:30 UTC
     # @return [Time] When this video was recorded (UTC).
     attr_reader :recorded_at
 
+    # @example
+    #   "http://www.twitch.tv/dreamhacktv/b/396294648"
     # @return [String] URL of this video on Twitch.
     attr_reader :url
 
+    # @example
+    #   81754
     # @return [Fixnum] The number of views this video has received all-time.
     attr_reader :view_count
 
@@ -89,41 +80,72 @@ module Kappa::V2
     attr_reader :description
 
     # @example
-    #   v.length # => 4205 (1 hour, 10 minutes, 5 seconds)
+    #   4205 # (1 hour, 10 minutes, 5 seconds)
     # @return [Fixnum] The length of this video (seconds).
     attr_reader :length
 
+    # @example
+    #   "StarCraft II: Heart of the Swarm"
     # @return [String] The name of the game played in this video.
     attr_reader :game_name
 
+    # @example
+    #   "http://static-cdn.jtvnw.net/jtv.thumbs/archive-396294648-320x240.jpg"
     # @return [String] URL of a preview screenshot taken from the video stream.
     attr_reader :preview_url
 
     # @return [Channel] The channel on which this video was originally streamed.
     attr_reader :channel
+
+    # @example
+    #   "<object data='http://www.twitch.tv/widgets/archive_embed_player.swf'>...</object>"
+    # @return [String] HTML code for embedding this video on a web page.
+    attr_reader :embed_html
   end
 
-  # Query class used for finding top videos.
+  # Query class for finding videos.
   # @see Video
   class Videos
-    include Connection
+    # @private
+    def initialize(query)
+      @query = query
+    end
+
+    # Get a video by ID.
+    # @example
+    #   Twitch.videos.get('a396294648')
+    # @param id [String] The ID of the video to get.
+    # @raise [ArgumentError] If `id` is `nil` or empty.
+    # @return [Video] A valid `Video` object if the video exists, `nil` otherwise.
+    def get(id)
+      raise ArgumentError, 'id' if !id || id.strip.empty?
+
+      encoded_id = CGI.escape(id)
+      json = @query.connection.get("videos/#{encoded_id}")
+      if !json || json['status'] == 404
+        nil
+      else
+        Video.new(json, @query)
+      end
+    end
 
     # Get the list of most popular videos based on view count.
     # @note The number of videos returned is potentially very large, so it's recommended that you specify a `:limit`.
     # @example
-    #   Videos.top
+    #   Twitch.videos.top
     # @example
-    #   Videos.top(:period => :month, :game => 'Super Meat Boy')
+    #   Twitch.videos.top(:period => :month, :game => 'Super Meat Boy')
     # @example
-    #   Videos.top(:period => :all, :limit => 10)
+    #   Twitch.videos.top(:period => :all, :limit => 10)
     # @param options [Hash] Filter criteria.
-    # @option options [Symbol] :period (:week) Return videos only in this time period. Supported values are `:week`, `:month`, `:all`.
+    # @option options [Symbol] :period (:week) Return videos only in this time period. Valid values are `:week`, `:month`, `:all`.
     # @option options [String] :game (nil) Return videos only for this game.
     # @option options [Fixnum] :limit (none) Limit on the number of results returned.
     # @option options [Fixnum] :offset (0) Offset into the result set to begin enumeration.
     # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/videos.md#get-videostop GET /videos/top
+    # @raise [ArgumentError] If `:period` is not one of `:week`, `:month`, or `:all`.
     # @return [Array<Video>] List of top videos.
-    def self.top(options = {})
+    def top(options = {})
       params = {}
 
       if options[:game]
@@ -137,11 +159,11 @@ module Kappa::V2
 
       params[:period] = period.to_s
 
-      return connection.accumulate(
+      return @query.connection.accumulate(
         :path => 'videos/top',
         :params => params,
         :json => 'videos',
-        :class => Video,
+        :create => -> hash { Video.new(hash, @query) },
         :limit => options[:limit],
         :offset => options[:offset]
       )