kappa 0.1.5.pre → 0.2.0

data/lib/kappa/game.rb

@@ -1,17 +1,11 @@
-module Kappa
-  # @private
-  class GameBase
-    include IdEquality
-  end
-
-  # @private
-  class GameSuggestionBase
-    include IdEquality
-  end
-end
-
 module Kappa::V2
-  class Game < Kappa::GameBase
+  # Games are categories (e.g. League of Legends, Diablo 3) used by streams and channels.
+  # Games can be searched for by query.
+  # @see Games
+  class Game
+    include Kappa::IdEquality
+
+    # @private
     def initialize(hash)
       @channel_count = hash['channels']
       @viewer_count = hash['viewers']
@@ -24,16 +18,34 @@ module Kappa::V2
       @logo_images = Images.new(game['logo'])
     end
 
+    # @return [Fixnum] Unique Twitch ID.
     attr_reader :id
+
+    # @return [String] User-friendly game name.
     attr_reader :name
+
+    # @return [Fixnum] Unique game ID for GiantBomb.com. 
     attr_reader :giantbomb_id
+
+    # @return [Images] Set of images for the game's box art.
     attr_reader :box_images
+
+    # @return [Images] Set of images for the game's logo.
     attr_reader :logo_images
+
+    # @return [Fixnum] Total number of channels currently streaming this game on Twitch.
     attr_reader :channel_count
+
+    # @return [Fixnum] Total number of viewers across all channels currently watching this game on Twitch.
     attr_reader :viewer_count
   end
 
-  class GameSuggestion < Kappa::GameSuggestionBase
+  # A game suggestion returned by Twitch when searching for games via `Games.find`.
+  # @see Games.find
+  class GameSuggestion
+    include Kappa::IdEquality
+
+    # @private
     def initialize(hash)
       @id = hash['_id']
       @name = hash['name']
@@ -43,25 +55,50 @@ module Kappa::V2
       @logo_images = Images.new(hash['logo'])
     end
 
+    # @return [Fixnum] Unique Twitch ID.
     attr_reader :id
+
+    # @return [String] Game name.
     attr_reader :name
+
+    # @return [Fixnum] Unique game ID for GiantBomb.com. 
     attr_reader :giantbomb_id
+
+    # @return [Fixnum] Relative popularity metric. Higher number means more popular.
     attr_reader :popularity
+
+    # @return [Images] Set of images for the game's box art.
     attr_reader :box_images
+
+    # @return [Images] Set of images for the game's logo.
     attr_reader :logo_images
   end
 
+  # Query class used for finding top games or finding games by name.
+  # @see Game
+  # @see GameSuggestion
   class Games
     include Connection
 
-    #
-    # GET /games/top
-    # https://github.com/justintv/Twitch-API/blob/master/v2_resources/games.md#get-gamestop
-    #
-    def self.top(args = {})
+    # Get a list of games with the highest number of current viewers on Twitch.
+    # @example
+    #   Games.top
+    # @example
+    #   Games.top(:limit => 10)
+    # @param options [Hash] Filter criteria.
+    # @option options [Boolean] :hls (false) TODO
+    # @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 Game
+    # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/games.md#get-gamestop GET /games/top
+    # @return [Array<Game>] List of games sorted by number of current viewers on Twitch, most popular first.
+    def self.top(options = {})
       params = {}
 
-      limit = args[:limit]
+      # TODO: Support :offset.
+      # TODO: Support :hls.
+
+      limit = options[:limit]
       if limit && (limit < 100)
         params[:limit] = limit
       else
@@ -78,18 +115,38 @@ module Kappa::V2
       )
     end
     
-    #
-    # GET /search/games
-    # https://github.com/justintv/Twitch-API/blob/master/v2_resources/search.md#get-searchgames
-    #
-    def self.search(params = {})
-      live = params[:live] || false
-      name = params[:name]
+    # Get a list of games with names similar to the specified name.
+    # @example
+    #   Games.find(:name => 'diablo')
+    # @example
+    #   Games.find(:name => 'starcraft', :live => true)
+    # @param options [Hash] Search criteria.
+    # @option options [String] :name Game name search term. This can be a partial name, e.g. `"league"`.
+    # @option options [Boolean] :live (false) If `true`, only returns games that are currently live on at least one channel.
+    # @see GameSuggestion
+    # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/search.md#get-searchgames GET /search/games
+    # @raise [ArgumentError] If `:name` is not specified.
+    # @return [Array<GameSuggestion>] List of games matching the criteria.
+    def self.find(options)
+      raise ArgumentError if options.nil? || options[:name].nil?
+
+      name = options[:name]
+
+      params = {
+        :query => name,
+        :type => 'suggest'
+      }
+
+      if options[:live]
+        params.merge!(:live => true)
+      end
+
+      # TODO: Use connection#accumulate here.
 
       games = []
       ids = Set.new
 
-      json = connection.get('search/games', :query => name, :type => 'suggest', :live => live)
+      json = connection.get('search/games', params)
       all_games = json['games']
       all_games.each do |game_json|
         game = GameSuggestion.new(game_json)

data/lib/kappa/images.rb

@@ -1,5 +1,7 @@
 module Kappa::V2
+  # A group of URLs pointing to variously-sized versions of the same image.
   class Images
+    # @private
     def initialize(hash)
       @large_url = hash['large']
       @medium_url = hash['medium']
@@ -7,13 +9,28 @@ module Kappa::V2
       @template_url = hash['template']
     end
 
+    # Get a URL pointing to an image with a specific size.
+    # @param width [Fixnum] Desired width of the image.
+    # @param height [Fixnum] Desired height of the image.
+    # @return [String] URL pointing to the image with the specified size.
     def url(width, height)
       @template_url.gsub('{width}', width.to_s).gsub('{height}', height.to_s)
     end
 
+    # TODO: Add documentation notes about rough sizes for small, medium, large images.
+
+    # @return [String] URL for the large-sized version of this image.
     attr_reader :large_url
+
+    # @return [String] URL for the medium-sized version of this image.
     attr_reader :medium_url
+
+    # @return [String] URL for the small-sized version of this image.
     attr_reader :small_url
+
+    # @note You shouldn't need to use this property directly. See #url for getting a formatted URL instead.
+    # @return [String] Template image URL with placeholders for width and height.
+    # @see #url
     attr_reader :template_url
   end
 end

data/lib/kappa/stream.rb

@@ -1,24 +1,15 @@
-module Kappa
-  # @private
-  class StreamBase
-    include IdEquality
-
-    def self.get(stream_name)
-      json = connection.get("streams/#{stream_name}")
-      stream = json['stream']
-      if json['status'] == 404 || !stream
-        nil
-      else
-        new(stream)
-      end
-    end
-  end
-end
+require 'cgi'
 
 module Kappa::V2
-  class Stream < Kappa::StreamBase
+  # Streams are video broadcasts that are currently live. They belong to a user and are part of a channel.
+  # @see .get Stream.get
+  # @see Streams
+  # @see Channel
+  class Stream
     include Connection
+    include Kappa::IdEquality
 
+    # @private
     def initialize(hash)
       @id = hash['_id']
       @broadcaster = hash['broadcaster']
@@ -29,45 +20,106 @@ module Kappa::V2
       @channel = Channel.new(hash['channel'])
     end
 
+    # Get a live stream by name.
+    # @example
+    #   s = Stream.get('lagtvmaximusblack')
+    #   s.nil?          # => false (stream is live)
+    #   s.game_name     # => "StarCraft II: Heart of the Swarm"
+    #   s.viewer_count  # => 2403
+    # @example
+    #   s = Strearm.get('destiny')
+    #   s.nil?          # => true (stream is offline)
+    # @param stream_name [String] The name of the stream to get. This is the same as the channel or user name.
+    # @see Streams.find
+    # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/streams.md#get-streamschannel GET /streams/:channel
+    # @return [Stream] A valid `Stream` object if the stream exists and is currently live, `nil` otherwise.
+    def self.get(stream_name)
+      encoded_name = CGI.escape(stream_name)
+      json = connection.get("streams/#{encoded_name}")
+      stream = json['stream']
+      if json['status'] == 404 || !stream
+        nil
+      else
+        new(stream)
+      end
+    end
+
+    # @return [Fixnum] Unique Twitch ID.
     attr_reader :id
+
+    # @example
+    #   "fme", "xsplit", "obs"
+    # @return [String] The broadcasting software used for this stream.
     attr_reader :broadcaster
+    
+    # @return [String] The name of the game currently being streamed.
     attr_reader :game_name
+
+    # @return [String] The unique Twitch name for this stream.
     attr_reader :name
+
+    # @return [Fixnum] The number of viewers currently watching the stream.
     attr_reader :viewer_count
+
+    # @return [String] URL of a preview screenshot taken from the video stream.
     attr_reader :preview_url
+
+    # @note This does not incur any web requests.
+    # @return [Channel] The `Channel` associated with this stream.
     attr_reader :channel
   end
 
+  # Query class used for finding featured streams or streams meeting certain criteria.
+  # @see Stream
   class Streams
     include Connection
 
+    # @private
+    # Private until implemented
     def self.all
+      # TODO
     end
 
-    #
-    # GET /streams
-    # https://github.com/justintv/Twitch-API/blob/master/v2_resources/streams.md
-    # :game (single, string), :channel (string array), :limit (int), :offset (int), :embeddable (bool), :hls (bool)
-    # TODO: Support Kappa::Vx::Game object for the :game param.
-    # TODO: Support Kappa::Vx::Channel object for the :channel param.
-    #
-    def self.where(args)
-      check = args.dup
+    # Get a list of streams for a specific game, for a set of channels, or by other criteria.
+    # @example
+    #   Streams.find(:game => 'League of Legends', :limit => 50)
+    # @example
+    #   Streams.find(:channel => ['fgtvlive', 'incontroltv', 'destiny'])
+    # @example
+    #   Streams.find(:game => 'Diablo III', :channel => ['nl_kripp', 'protech'])
+    # @param options [Hash] Search criteria.
+    # @option options [String/Game] :game Only return streams currently streaming the specified game.
+    # @option options [Array<String/Channel>] :channel Only return streams for these channels.
+    #   If a channel is not currently streaming, it is omitted. You must specify an array of channels
+    #   or channel names. If you want to find the stream for a single channel, see {Stream.get}.
+    # @option options [Boolean] :embeddable TODO
+    # @option options [Boolean] :hls TODO
+    # @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 Stream.get
+    # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/streams.md#get-streams GET /streams
+    # @raise [ArgumentError] If `options` does not specify a search criteria (`:game`, `:channel`, `:embeddable`, or `:hls`).
+    # @return [Array<Stream>] List of streams matching the specified criteria.
+    def self.find(options)
+      check = options.dup
       check.delete(:limit)
       check.delete(:offset)
       raise ArgumentError if check.empty?
 
+      # TODO: Support Kappa::Vx::Game object for the :game param.
+      # TODO: Support Kappa::Vx::Channel object for the :channel param.
+
       params = {}
 
-      if args[:channel]
-        params[:channel] = args[:channel].join(',')
+      if options[:channel]
+        params[:channel] = options[:channel].join(',')
       end
 
-      if args[:game]
-        params[:game] = args[:game]
+      if options[:game]
+        params[:game] = options[:game]
       end
 
-      limit = args[:limit]
+      limit = options[:limit]
       if limit && (limit < 100)
         params[:limit] = limit
       else
@@ -84,14 +136,25 @@ module Kappa::V2
       )
     end
 
-    #
-    # GET /streams/featured
-    # https://github.com/justintv/Twitch-API/blob/master/v2_resources/streams.md#get-streamsfeatured
-    #
-    def self.featured(args = {})
+    # Get the list of currently featured (promoted) streams. This includes the list of streams shown on the Twitch homepage.
+    # @note There is no guarantee of how many streams are featured at any given time.
+    # @example
+    #   Streams.featured
+    # @example
+    #   Streams.featured(:limit => 5)
+    # @param options [Hash] Filter criteria.
+    # @option options [Boolean] :hls (false) TODO
+    # @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/streams.md#get-streamsfeatured GET /streams/featured
+    # @return [Array<Stream>] List of currently featured streams.
+    def self.featured(options = {})
       params = {}
 
-      limit = args[:limit]
+      # TODO: Support :offset param
+      # TODO: Support :hls param
+
+      limit = options[:limit]
       if limit && (limit < 100)
         params[:limit] = limit
       else

data/lib/kappa/team.rb

@@ -1,27 +1,13 @@
-module Kappa
-  # @private
-  class TeamBase
-    include IdEquality
-
-    #
-    # GET /teams/:team
-    # https://github.com/justintv/Twitch-API/blob/master/v2_resources/teams.md#get-teamsteam
-    #
-    def self.get(team_name)
-      json = connection.get("teams/#{team_name}")
-      if json['status'] == 404
-        nil
-      else
-        new(json)
-      end
-    end
-  end
-end
-
 module Kappa::V2
-  class Team < Kappa::TeamBase
+  # Teams are an organization of channels.
+  # @see .get Team.get
+  # @see Teams
+  # @see Channel
+  class Team
     include Connection
+    include Kappa::IdEquality
     
+    # @private
     def initialize(hash)
       @id = hash['_id']
       @info = hash['info']
@@ -34,28 +20,66 @@ module Kappa::V2
       @created_at = DateTime.parse(hash['created_at'])
     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
+
+    # @return [Fixnum] Unique Twitch ID.
     attr_reader :id
+
+    # @return [String] Info about the team. This is displayed on the team's page and can contain HTML.
     attr_reader :info
+
+    # @return [String] URL for background image.
     attr_reader :background_url
+
+    # @return [String] URL for banner image.
     attr_reader :banner_url
+
+    # @return [String] URL for the logo image.
     attr_reader :logo_url
+
+    # @return [String] Unique Twitch name.
     attr_reader :name
+
+    # @return [String] User-friendly display name. This name is used for the team's page title.
     attr_reader :display_name
+
+    # @return [DateTime] When the team was last updated.
     attr_reader :updated_at
+
+    # @return [DateTime] When the team was created.
     attr_reader :created_at
   end
 
+  # Query class used for finding all active teams.
+  # @see Team
   class Teams
     include Connection
 
-    #
-    # GET /teams
-    # https://github.com/justintv/Twitch-API/blob/master/v2_resources/teams.md#get-teams
-    #
-    def self.all(args = {})
+    # Get the list of all active teams.
+    # @example
+    #   Teams.all
+    # @example
+    #   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 = {})
+      # TODO: Is offset supported?
       params = {}
 
-      limit = args[:limit]
+      limit = options[:limit]
       if limit && (limit < 100)
         params[:limit] = limit
       else