kappa 0.1.5.pre → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/lib/kappa/game.rb CHANGED
@@ -1,17 +1,11 @@
1
- module Kappa
2
- # @private
3
- class GameBase
4
- include IdEquality
5
- end
6
-
7
- # @private
8
- class GameSuggestionBase
9
- include IdEquality
10
- end
11
- end
12
-
13
1
  module Kappa::V2
14
- class Game < Kappa::GameBase
2
+ # Games are categories (e.g. League of Legends, Diablo 3) used by streams and channels.
3
+ # Games can be searched for by query.
4
+ # @see Games
5
+ class Game
6
+ include Kappa::IdEquality
7
+
8
+ # @private
15
9
  def initialize(hash)
16
10
  @channel_count = hash['channels']
17
11
  @viewer_count = hash['viewers']
@@ -24,16 +18,34 @@ module Kappa::V2
24
18
  @logo_images = Images.new(game['logo'])
25
19
  end
26
20
 
21
+ # @return [Fixnum] Unique Twitch ID.
27
22
  attr_reader :id
23
+
24
+ # @return [String] User-friendly game name.
28
25
  attr_reader :name
26
+
27
+ # @return [Fixnum] Unique game ID for GiantBomb.com.
29
28
  attr_reader :giantbomb_id
29
+
30
+ # @return [Images] Set of images for the game's box art.
30
31
  attr_reader :box_images
32
+
33
+ # @return [Images] Set of images for the game's logo.
31
34
  attr_reader :logo_images
35
+
36
+ # @return [Fixnum] Total number of channels currently streaming this game on Twitch.
32
37
  attr_reader :channel_count
38
+
39
+ # @return [Fixnum] Total number of viewers across all channels currently watching this game on Twitch.
33
40
  attr_reader :viewer_count
34
41
  end
35
42
 
36
- class GameSuggestion < Kappa::GameSuggestionBase
43
+ # A game suggestion returned by Twitch when searching for games via `Games.find`.
44
+ # @see Games.find
45
+ class GameSuggestion
46
+ include Kappa::IdEquality
47
+
48
+ # @private
37
49
  def initialize(hash)
38
50
  @id = hash['_id']
39
51
  @name = hash['name']
@@ -43,25 +55,50 @@ module Kappa::V2
43
55
  @logo_images = Images.new(hash['logo'])
44
56
  end
45
57
 
58
+ # @return [Fixnum] Unique Twitch ID.
46
59
  attr_reader :id
60
+
61
+ # @return [String] Game name.
47
62
  attr_reader :name
63
+
64
+ # @return [Fixnum] Unique game ID for GiantBomb.com.
48
65
  attr_reader :giantbomb_id
66
+
67
+ # @return [Fixnum] Relative popularity metric. Higher number means more popular.
49
68
  attr_reader :popularity
69
+
70
+ # @return [Images] Set of images for the game's box art.
50
71
  attr_reader :box_images
72
+
73
+ # @return [Images] Set of images for the game's logo.
51
74
  attr_reader :logo_images
52
75
  end
53
76
 
77
+ # Query class used for finding top games or finding games by name.
78
+ # @see Game
79
+ # @see GameSuggestion
54
80
  class Games
55
81
  include Connection
56
82
 
57
- #
58
- # GET /games/top
59
- # https://github.com/justintv/Twitch-API/blob/master/v2_resources/games.md#get-gamestop
60
- #
61
- def self.top(args = {})
83
+ # Get a list of games with the highest number of current viewers on Twitch.
84
+ # @example
85
+ # Games.top
86
+ # @example
87
+ # Games.top(:limit => 10)
88
+ # @param options [Hash] Filter criteria.
89
+ # @option options [Boolean] :hls (false) TODO
90
+ # @option options [Fixnum] :limit (none) Limit on the number of results returned.
91
+ # @option options [Fixnum] :offset (0) Offset into the result set to begin enumeration.
92
+ # @see Game
93
+ # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/games.md#get-gamestop GET /games/top
94
+ # @return [Array<Game>] List of games sorted by number of current viewers on Twitch, most popular first.
95
+ def self.top(options = {})
62
96
  params = {}
63
97
 
64
- limit = args[:limit]
98
+ # TODO: Support :offset.
99
+ # TODO: Support :hls.
100
+
101
+ limit = options[:limit]
65
102
  if limit && (limit < 100)
66
103
  params[:limit] = limit
67
104
  else
@@ -78,18 +115,38 @@ module Kappa::V2
78
115
  )
79
116
  end
80
117
 
81
- #
82
- # GET /search/games
83
- # https://github.com/justintv/Twitch-API/blob/master/v2_resources/search.md#get-searchgames
84
- #
85
- def self.search(params = {})
86
- live = params[:live] || false
87
- name = params[:name]
118
+ # Get a list of games with names similar to the specified name.
119
+ # @example
120
+ # Games.find(:name => 'diablo')
121
+ # @example
122
+ # Games.find(:name => 'starcraft', :live => true)
123
+ # @param options [Hash] Search criteria.
124
+ # @option options [String] :name Game name search term. This can be a partial name, e.g. `"league"`.
125
+ # @option options [Boolean] :live (false) If `true`, only returns games that are currently live on at least one channel.
126
+ # @see GameSuggestion
127
+ # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/search.md#get-searchgames GET /search/games
128
+ # @raise [ArgumentError] If `:name` is not specified.
129
+ # @return [Array<GameSuggestion>] List of games matching the criteria.
130
+ def self.find(options)
131
+ raise ArgumentError if options.nil? || options[:name].nil?
132
+
133
+ name = options[:name]
134
+
135
+ params = {
136
+ :query => name,
137
+ :type => 'suggest'
138
+ }
139
+
140
+ if options[:live]
141
+ params.merge!(:live => true)
142
+ end
143
+
144
+ # TODO: Use connection#accumulate here.
88
145
 
89
146
  games = []
90
147
  ids = Set.new
91
148
 
92
- json = connection.get('search/games', :query => name, :type => 'suggest', :live => live)
149
+ json = connection.get('search/games', params)
93
150
  all_games = json['games']
94
151
  all_games.each do |game_json|
95
152
  game = GameSuggestion.new(game_json)
data/lib/kappa/images.rb CHANGED
@@ -1,5 +1,7 @@
1
1
  module Kappa::V2
2
+ # A group of URLs pointing to variously-sized versions of the same image.
2
3
  class Images
4
+ # @private
3
5
  def initialize(hash)
4
6
  @large_url = hash['large']
5
7
  @medium_url = hash['medium']
@@ -7,13 +9,28 @@ module Kappa::V2
7
9
  @template_url = hash['template']
8
10
  end
9
11
 
12
+ # Get a URL pointing to an image with a specific size.
13
+ # @param width [Fixnum] Desired width of the image.
14
+ # @param height [Fixnum] Desired height of the image.
15
+ # @return [String] URL pointing to the image with the specified size.
10
16
  def url(width, height)
11
17
  @template_url.gsub('{width}', width.to_s).gsub('{height}', height.to_s)
12
18
  end
13
19
 
20
+ # TODO: Add documentation notes about rough sizes for small, medium, large images.
21
+
22
+ # @return [String] URL for the large-sized version of this image.
14
23
  attr_reader :large_url
24
+
25
+ # @return [String] URL for the medium-sized version of this image.
15
26
  attr_reader :medium_url
27
+
28
+ # @return [String] URL for the small-sized version of this image.
16
29
  attr_reader :small_url
30
+
31
+ # @note You shouldn't need to use this property directly. See #url for getting a formatted URL instead.
32
+ # @return [String] Template image URL with placeholders for width and height.
33
+ # @see #url
17
34
  attr_reader :template_url
18
35
  end
19
36
  end
data/lib/kappa/stream.rb CHANGED
@@ -1,24 +1,15 @@
1
- module Kappa
2
- # @private
3
- class StreamBase
4
- include IdEquality
5
-
6
- def self.get(stream_name)
7
- json = connection.get("streams/#{stream_name}")
8
- stream = json['stream']
9
- if json['status'] == 404 || !stream
10
- nil
11
- else
12
- new(stream)
13
- end
14
- end
15
- end
16
- end
1
+ require 'cgi'
17
2
 
18
3
  module Kappa::V2
19
- class Stream < Kappa::StreamBase
4
+ # Streams are video broadcasts that are currently live. They belong to a user and are part of a channel.
5
+ # @see .get Stream.get
6
+ # @see Streams
7
+ # @see Channel
8
+ class Stream
20
9
  include Connection
10
+ include Kappa::IdEquality
21
11
 
12
+ # @private
22
13
  def initialize(hash)
23
14
  @id = hash['_id']
24
15
  @broadcaster = hash['broadcaster']
@@ -29,45 +20,106 @@ module Kappa::V2
29
20
  @channel = Channel.new(hash['channel'])
30
21
  end
31
22
 
23
+ # Get a live stream by name.
24
+ # @example
25
+ # s = Stream.get('lagtvmaximusblack')
26
+ # s.nil? # => false (stream is live)
27
+ # s.game_name # => "StarCraft II: Heart of the Swarm"
28
+ # s.viewer_count # => 2403
29
+ # @example
30
+ # s = Strearm.get('destiny')
31
+ # s.nil? # => true (stream is offline)
32
+ # @param stream_name [String] The name of the stream to get. This is the same as the channel or user name.
33
+ # @see Streams.find
34
+ # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/streams.md#get-streamschannel GET /streams/:channel
35
+ # @return [Stream] A valid `Stream` object if the stream exists and is currently live, `nil` otherwise.
36
+ def self.get(stream_name)
37
+ encoded_name = CGI.escape(stream_name)
38
+ json = connection.get("streams/#{encoded_name}")
39
+ stream = json['stream']
40
+ if json['status'] == 404 || !stream
41
+ nil
42
+ else
43
+ new(stream)
44
+ end
45
+ end
46
+
47
+ # @return [Fixnum] Unique Twitch ID.
32
48
  attr_reader :id
49
+
50
+ # @example
51
+ # "fme", "xsplit", "obs"
52
+ # @return [String] The broadcasting software used for this stream.
33
53
  attr_reader :broadcaster
54
+
55
+ # @return [String] The name of the game currently being streamed.
34
56
  attr_reader :game_name
57
+
58
+ # @return [String] The unique Twitch name for this stream.
35
59
  attr_reader :name
60
+
61
+ # @return [Fixnum] The number of viewers currently watching the stream.
36
62
  attr_reader :viewer_count
63
+
64
+ # @return [String] URL of a preview screenshot taken from the video stream.
37
65
  attr_reader :preview_url
66
+
67
+ # @note This does not incur any web requests.
68
+ # @return [Channel] The `Channel` associated with this stream.
38
69
  attr_reader :channel
39
70
  end
40
71
 
72
+ # Query class used for finding featured streams or streams meeting certain criteria.
73
+ # @see Stream
41
74
  class Streams
42
75
  include Connection
43
76
 
77
+ # @private
78
+ # Private until implemented
44
79
  def self.all
80
+ # TODO
45
81
  end
46
82
 
47
- #
48
- # GET /streams
49
- # https://github.com/justintv/Twitch-API/blob/master/v2_resources/streams.md
50
- # :game (single, string), :channel (string array), :limit (int), :offset (int), :embeddable (bool), :hls (bool)
51
- # TODO: Support Kappa::Vx::Game object for the :game param.
52
- # TODO: Support Kappa::Vx::Channel object for the :channel param.
53
- #
54
- def self.where(args)
55
- check = args.dup
83
+ # Get a list of streams for a specific game, for a set of channels, or by other criteria.
84
+ # @example
85
+ # Streams.find(:game => 'League of Legends', :limit => 50)
86
+ # @example
87
+ # Streams.find(:channel => ['fgtvlive', 'incontroltv', 'destiny'])
88
+ # @example
89
+ # Streams.find(:game => 'Diablo III', :channel => ['nl_kripp', 'protech'])
90
+ # @param options [Hash] Search criteria.
91
+ # @option options [String/Game] :game Only return streams currently streaming the specified game.
92
+ # @option options [Array<String/Channel>] :channel Only return streams for these channels.
93
+ # If a channel is not currently streaming, it is omitted. You must specify an array of channels
94
+ # or channel names. If you want to find the stream for a single channel, see {Stream.get}.
95
+ # @option options [Boolean] :embeddable TODO
96
+ # @option options [Boolean] :hls TODO
97
+ # @option options [Fixnum] :limit (none) Limit on the number of results returned.
98
+ # @option options [Fixnum] :offset (0) Offset into the result set to begin enumeration.
99
+ # @see Stream.get
100
+ # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/streams.md#get-streams GET /streams
101
+ # @raise [ArgumentError] If `options` does not specify a search criteria (`:game`, `:channel`, `:embeddable`, or `:hls`).
102
+ # @return [Array<Stream>] List of streams matching the specified criteria.
103
+ def self.find(options)
104
+ check = options.dup
56
105
  check.delete(:limit)
57
106
  check.delete(:offset)
58
107
  raise ArgumentError if check.empty?
59
108
 
109
+ # TODO: Support Kappa::Vx::Game object for the :game param.
110
+ # TODO: Support Kappa::Vx::Channel object for the :channel param.
111
+
60
112
  params = {}
61
113
 
62
- if args[:channel]
63
- params[:channel] = args[:channel].join(',')
114
+ if options[:channel]
115
+ params[:channel] = options[:channel].join(',')
64
116
  end
65
117
 
66
- if args[:game]
67
- params[:game] = args[:game]
118
+ if options[:game]
119
+ params[:game] = options[:game]
68
120
  end
69
121
 
70
- limit = args[:limit]
122
+ limit = options[:limit]
71
123
  if limit && (limit < 100)
72
124
  params[:limit] = limit
73
125
  else
@@ -84,14 +136,25 @@ module Kappa::V2
84
136
  )
85
137
  end
86
138
 
87
- #
88
- # GET /streams/featured
89
- # https://github.com/justintv/Twitch-API/blob/master/v2_resources/streams.md#get-streamsfeatured
90
- #
91
- def self.featured(args = {})
139
+ # Get the list of currently featured (promoted) streams. This includes the list of streams shown on the Twitch homepage.
140
+ # @note There is no guarantee of how many streams are featured at any given time.
141
+ # @example
142
+ # Streams.featured
143
+ # @example
144
+ # Streams.featured(:limit => 5)
145
+ # @param options [Hash] Filter criteria.
146
+ # @option options [Boolean] :hls (false) TODO
147
+ # @option options [Fixnum] :limit (none) Limit on the number of results returned.
148
+ # @option options [Fixnum] :offset (0) Offset into the result set to begin enumeration.
149
+ # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/streams.md#get-streamsfeatured GET /streams/featured
150
+ # @return [Array<Stream>] List of currently featured streams.
151
+ def self.featured(options = {})
92
152
  params = {}
93
153
 
94
- limit = args[:limit]
154
+ # TODO: Support :offset param
155
+ # TODO: Support :hls param
156
+
157
+ limit = options[:limit]
95
158
  if limit && (limit < 100)
96
159
  params[:limit] = limit
97
160
  else
data/lib/kappa/team.rb CHANGED
@@ -1,27 +1,13 @@
1
- module Kappa
2
- # @private
3
- class TeamBase
4
- include IdEquality
5
-
6
- #
7
- # GET /teams/:team
8
- # https://github.com/justintv/Twitch-API/blob/master/v2_resources/teams.md#get-teamsteam
9
- #
10
- def self.get(team_name)
11
- json = connection.get("teams/#{team_name}")
12
- if json['status'] == 404
13
- nil
14
- else
15
- new(json)
16
- end
17
- end
18
- end
19
- end
20
-
21
1
  module Kappa::V2
22
- class Team < Kappa::TeamBase
2
+ # Teams are an organization of channels.
3
+ # @see .get Team.get
4
+ # @see Teams
5
+ # @see Channel
6
+ class Team
23
7
  include Connection
8
+ include Kappa::IdEquality
24
9
 
10
+ # @private
25
11
  def initialize(hash)
26
12
  @id = hash['_id']
27
13
  @info = hash['info']
@@ -34,28 +20,66 @@ module Kappa::V2
34
20
  @created_at = DateTime.parse(hash['created_at'])
35
21
  end
36
22
 
23
+ # Get a team by name.
24
+ # @param team_name [String] The name of the team to get.
25
+ # @return [Team] A valid `Team` object if the team exists, `nil` otherwise.
26
+ # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/teams.md#get-teamsteam GET /teams/:team
27
+ def self.get(team_name)
28
+ json = connection.get("teams/#{team_name}")
29
+ if json['status'] == 404
30
+ nil
31
+ else
32
+ new(json)
33
+ end
34
+ end
35
+
36
+ # @return [Fixnum] Unique Twitch ID.
37
37
  attr_reader :id
38
+
39
+ # @return [String] Info about the team. This is displayed on the team's page and can contain HTML.
38
40
  attr_reader :info
41
+
42
+ # @return [String] URL for background image.
39
43
  attr_reader :background_url
44
+
45
+ # @return [String] URL for banner image.
40
46
  attr_reader :banner_url
47
+
48
+ # @return [String] URL for the logo image.
41
49
  attr_reader :logo_url
50
+
51
+ # @return [String] Unique Twitch name.
42
52
  attr_reader :name
53
+
54
+ # @return [String] User-friendly display name. This name is used for the team's page title.
43
55
  attr_reader :display_name
56
+
57
+ # @return [DateTime] When the team was last updated.
44
58
  attr_reader :updated_at
59
+
60
+ # @return [DateTime] When the team was created.
45
61
  attr_reader :created_at
46
62
  end
47
63
 
64
+ # Query class used for finding all active teams.
65
+ # @see Team
48
66
  class Teams
49
67
  include Connection
50
68
 
51
- #
52
- # GET /teams
53
- # https://github.com/justintv/Twitch-API/blob/master/v2_resources/teams.md#get-teams
54
- #
55
- def self.all(args = {})
69
+ # Get the list of all active teams.
70
+ # @example
71
+ # Teams.all
72
+ # @example
73
+ # Teams.all(:limit => 10)
74
+ # @param options [Hash] Filter criteria.
75
+ # @option options [Fixnum] :limit (none) Limit on the number of results returned.
76
+ # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/teams.md#get-teams GET /teams
77
+ # @return [Array<Team>] List of all active teams.
78
+ def self.all(options = {})
79
+ # TODO: Is offset supported?
56
80
  params = {}
57
81
 
58
- limit = args[:limit]
82
+ limit = options[:limit]
59
83
  if limit && (limit < 100)
60
84
  params[:limit] = limit
61
85
  else