botr 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 639156f787f908de46a41659c4c8d6d970cda933
-  data.tar.gz: 622a75e74c4b9c3e9c57f00aec3cbe936a9d6d9d
+  metadata.gz: 0566390f9e32ca9a61ffeefb7530242bffed7a02
+  data.tar.gz: 99a2af2ac184d15fd438d8aa99cc45caacdcdd3f
 SHA512:
-  metadata.gz: 43266b552c296a6ef23f5fd0080d167c07459068695d517cd90778f6c27bf7c1dd45b179ca08496a072a0c38d445ea59a75d1d34197cf7eeb54f2975daf63a61
-  data.tar.gz: 91256d3345300acef4027cbfdf10f20ac5cd3e0c40651e5c916e92dbfe737f08d357aa1f486daed1fdca8579223f51d6f60c164ef5112ec866a9ff20cf9c523b
+  metadata.gz: 68a8d8d211fb8403bed97cbbbffe2ec1deab740e693f7cb6d171e7bf680be909541b5b81ed9312bcdf3dfb75ee3af33eaad1f0465196a80ab0a55dcbf7b3791f
+  data.tar.gz: fc9e5e878caad0e0555a59fc399b831e3692a051868334914f1f2818b5b79d20e0c3e4df8fafd544c6ba2ea4539e6a6196f1a53a738be30ff7988ab89b1b1cf0

data/lib/botr/accounts/account_usage.rb

@@ -0,0 +1 @@
+# call_class = "accounts/usage"

data/lib/botr/channels/channel.rb

@@ -1,14 +1,24 @@
 module BOTR
 
+	# The BOTR::Channel class contains calls for creating new channels, searching
+	# for channels, managing the channel properties (title, description etc.) and
+	# deleting channels.
 	class Channel < BOTR::Object
 
 		class << self
 
 			attr_reader :last_status
 
-			def show(key)
+			# Show all information about a channel.
+			#
+ 			# @param [String] channel_key key of the channel for which to show
+ 			# information
+ 			#
+ 			# @return [BOTR::Channel] a new object with the properties of the
+ 			#  channel referenced by the channel key
+			def show(channel_key)
 				json = get_request({:method => 'show',
-								    :channel_key => key})
+								    :channel_key => channel_key})
 				res = JSON.parse(json.body)
 
 				if json.status == 200
@@ -22,6 +32,27 @@ module BOTR
 
 			alias :find :show
 
+			# Return a list of channels, including their most interesting
+			# properties.
+			#
+ 			# @param [Hash] options search parameters
+ 			#
+ 			# @option options [String] types_filter specifies channel type by
+ 			#  which returned result should be filtered: "manual" or "dynamic"
+ 			# @option options [String] search case-insensitive search in the
+ 			#  author, channel_key, description, link, title fields and custom
+ 			#  fields
+ 			# @option options [String] order_by specifies parameters by which
+			#  returned result should be ordered; ":asc" and ":desc" can be
+			#  appended accordingly
+			# @option options [Integer] result_limit specifies maximum number of
+			#  channels to return; default is 50 and maximum result limit is 1000
+			# @option options [Integer] result_offset specifies how many channels
+			#  should be skipped at the beginning of the result set; default is
+			#  0
+ 			#
+ 			# @return [BOTR::Channel] a new object with the properties of the
+ 			#  channel referenced by the channel key
 			def list(**options)
 				json = get_request(options.merge(:method => 'list'))
 				res = JSON.parse(json.body)
@@ -69,6 +100,19 @@ module BOTR
 			end		
 		end
 
+		# Create a new (dynamic or manual) channel.
+		#
+		# @param [String] type type of the channel: "dynamic" or "manual"
+		# information
+		# @param [Hash] options channel parameters
+		#
+		# @option options [String] title title of the channel
+		# @option options [String] description description of the channel
+		# @option options [String] link user defined URL
+		# @option options [String] author author of the channel
+		#
+		# @return [BOTR::Channel] this object with the properties specified in
+		#  the options hash
 		def create(type, **options)
 			json = get_request(options.merge(:method => 'create',
 											 :type => type))
@@ -83,6 +127,32 @@ module BOTR
 			return self
 		end
 
+		# Configure or update the properties of a channel.
+		#
+		# @param [Hash] options channel parameters
+		#
+		# @option options [String] channel_key key of the channel which should
+		#  be configured or updated
+		# @option options [String] title title of the channel
+		# @option options [String] description description of the channel
+		# @option options [String] link user defined URL
+		# @option options [String] author author of the channel
+		# @option options [String] tags tags of the channel; restricts the
+		#  inclusion of videos to the channel to the videos tagged with the
+		#  specified tags
+		# @option options [String] tags_mode tags search mode for the dynamic
+		#  channel: "all" -- a video will only be added if it has all tags
+		#  specified in the tags parameter or "any" -- a video will be added if
+		#  it has at least one tag specified in the tags parameter
+		# @option options [String] sort_order specifies sorting order of the
+		#  videos in a dynamic channel: "date-asc", "date-desc", "title-asc",
+		#  "title-desc", "duration-asc", "duration-desc", "views-asc" or
+		#  "views-desc"
+		# @option options [Integer] videos_max maximum number of videos to
+		#  allow in a dynamic channel; default is 10
+		#
+		# @return [BOTR::Channel] this object with the properties specified in
+		#  the options hash
 		def update(**options)
 			json = put_request(options.merge(:channel_key => @key))
 			res = JSON.parse(json.body)
@@ -96,6 +166,9 @@ module BOTR
 			return self
 		end
 
+		# Delete a channel.
+		#
+		# @return [BOTR::Channel] this object with null properties
 		def delete
 			json = delete_request({:channel_key => @key})
 			res = JSON.parse(json.body)

data/lib/botr/channels/channel_thumbnail.rb

@@ -1,14 +1,23 @@
 module BOTR
 
+	# The BOTR::ChannelThumbnail class contains calls that can be used to upload
+	# a preview image for a channel. Channels don’t have a thumb by default.
 	class ChannelThumbnail < BOTR::Object
 
 		class << self
 
 			attr_reader :last_status
 
-			def show(key)
+			# Show channel thumbnails creation status.
+			#
+ 			# @param [String] channel_key key of the channel for which to show
+ 			#  thumbnails creation status
+ 			#
+ 			# @return [BOTR::ChannelThumbnail] a new object with the thumbnail
+ 			#  properties of the channel referenced by the channel key
+			def show(channel_key)
 				json = get_request({:method => 'show',
-								    :channel_key => key})
+								    :channel_key => channel_key})
 				res = JSON.parse(json.body)
 
 				if json.status == 200
@@ -44,6 +53,9 @@ module BOTR
 			raise ArgumentError, "You must specify a channel key." if @key.nil?
 		end
 
+		# Update a channel thumbnail by uploading an image.
+		#
+		# @return [BOTR::ChannelThumbnail] this object with an upload URL
 		def update
 			json = put_request({:channel_key => @key})
 			res = JSON.parse(json.body)

data/lib/botr/channels/channel_video.rb

@@ -1,14 +1,30 @@
 module BOTR
 
+	# The BOTR::ChannelVideo class contains calls for requesting channel videos
+	# in the dynamic playlist. For manual channels, these calls can also be used
+	# to add, change video position or remove video from the playlist.
 	class ChannelVideo < BOTR::Object
 
 		class << self
 
 			attr_reader :last_status
 
-			def show(key, **options)
+			# Show information for a video from the channel.
+			#
+ 			# @param [String] channel_key key of the channel to which the video
+ 			#  belongs
+ 			# @params [Hash] options channel video parameters
+ 			#
+ 			# @option options [String] video_key key of the video which
+ 			#  information to show
+ 			# @option options [Integer] position position of the video in the
+ 			#  channel for which to show information
+ 			#
+ 			# @return [BOTR::ChannelVideo] a new object with the properties of
+ 			#  the video referenced by the video key or the position
+			def show(channel_key, **options)
 				json = get_request(options.merge(:method => 'show',
-								    			 :channel_key => key))
+								    			 :channel_key => channel_key))
 				res = JSON.parse(json.body)
 
 				if json.status == 200
@@ -22,9 +38,22 @@ module BOTR
 
 			alias :find :show
 
-			def list(key, **options)
+			# Return list of videos in the channel.
+			#
+ 			# @param [String] channel_key key of the channel for which videos
+ 			#  should be listed
+ 			# @params [Hash] options channel video parameters
+ 			#
+ 			# @option options [Integer] result_limit specifies maximum number of
+ 			#  videos to return; default is 50 and maximum result limit is 1000.
+ 			# @option options [Integer] result_offset specifies how many videos
+ 			#  should be skipped at the beginning of the result set
+ 			#
+ 			# @return [Array] a list of video objects in the channel specified
+ 			#  by the channel key
+			def list(channel_key, **options)
 				json = get_request(options.merge(:method => 'list',
-												 :channel_key => key))
+												 :channel_key => channel_key))
 				res = JSON.parse(json.body)
 				
 				if json.status == 200
@@ -36,6 +65,19 @@ module BOTR
 				return results
 			end
 
+			# Move a video to a different position in a manual channel.
+			#
+ 			# @param [String] channel_key key of the channel which should be
+ 			#  updated
+ 			# @params [Hash] options channel video parameters
+ 			#
+ 			# @option options [String] position_from position in the channel
+ 			#  of the video which should be moved
+ 			# @option options [Integer] position_to position in the channel
+ 			#  of where the video which should be moved
+ 			#
+ 			# @return [BOTR::ChannelVideo] this object with the status of the
+ 			# 	move operation
 			def update(channel_key, **options)
 				json = put_request(options.merge(:channel_key => channel_key))
 				res = JSON.parse(json.body)
@@ -84,6 +126,19 @@ module BOTR
 			raise ArgumentError, "You must specify a video key." if @key.nil?
 		end
 
+		# Add a video to the playlist of a manual channel.
+		#
+		# @param [String] channel_key key of the channel to which the video
+		#  belongs
+		# @params [Hash] options channel video parameters
+		#
+		# @option options [String] video_key key of the video that should be
+		#  added to the channel
+		# @option options [Integer] position indicates where to insert the new
+		#  video; defaults to insertion at the end
+		#
+		# @return [BOTR::ChannelVideo] this object with the status of the add
+		#  operation
 		def create(channel_key, **options)
 			json = get_request(options.merge(:method => 'create',
 											 :channel_key => channel_key,
@@ -99,8 +154,21 @@ module BOTR
 			return self
 		end
 
-		def delete(channel_key)
-			json = delete_request({:channel_key => channel_key})
+		# Delete a video from the playlist of a manual channel.
+		#
+		# @param [String] channel_key key of the channel from which video should
+		#  be deleted
+		# @params [Hash] options channel video parameters
+		#
+		# @option options [String] video_key key of the video; all videos with
+		#  this key will be deleted from the channel
+		# @option options [Integer] position_to video position in the channel;
+		#  only video at this position will be deleted from the channel
+		#
+		# @return [BOTR::ChannelVideo] this object with the status of the delete
+		#  operation and all other parameters nulled
+		def delete(channel_key, **options)
+			json = delete_request(options.merge(:channel_key => channel_key))
 			res = JSON.parse(json.body)
 
 			if json.status == 200

data/lib/botr/channels/channel_view.rb

@@ -1,14 +1,42 @@
 module BOTR
 
+	# The BOTR::ChannelView class contains calls for requesting channel views
+	# statistics.
+	#
+	# A channel view is counted every time:
+	#
+	# The RSS feed of that channel is requested from the content server.
+	# A player from our content server containing a channel is embedded in a
+	# webpage.
 	class ChannelView < BOTR::Object
 
 		class << self
 
 			attr_reader :last_status
-
-			def show(key, **options)
+			
+			# Shows views statistics for a channel.
+			#
+ 			# @param [String] channel_key key of the channel for which to show
+ 			# information
+ 			# @param [Hash] options channel views parameters
+ 			#
+ 			# @option options [Integer] start_date Unix timestamp of date
+ 			#  from which channel views statistics should be start
+ 			# @option options [Integer] end_date Unix timestamp of date
+ 			#  on which channel views statistics should be end
+ 			# @option options [String] aggregate specifies if returned channel
+ 			#  views statistics should be aggregate: true or false
+ 			# @option options [String] group_days specifies if returned channel
+ 			#  views statistics should be grouped by year and month
+ 			# @option options [String] include_empty_days specifies if channel
+ 			#  views statistics should include days for which there is no
+ 			#  statistics available: true or false
+ 			#
+ 			# @return [BOTR::ChannelView] a new object with the view statistics
+ 			#  of the channel referenced by the channel key
+			def show(channel_key, **options)
 				json = get_request(options.merge(:method => 'show',
-								    			 :channel_key => key))
+								    			 :channel_key => channel_key))
 				res = JSON.parse(json.body)
 
 				if json.status == 200
@@ -22,6 +50,34 @@ module BOTR
 
 			alias :find :show
 
+			# List channel views statistics per channel or per day.
+			#
+ 			# @params [Hash] options stats parameters
+ 			#
+ 			# @option options [Integer] start_date Unix timestamp of date
+ 			#  from which channel views statistics should be start
+ 			# @option options [Integer] end_date Unix timestamp of date
+ 			#  on which channel views statistics should be end
+ 			# @option options [String] list_by specifies channel views statistics
+ 			#  listing type: "channel" or "day"
+ 			# @option options [String] order_by specifies parameters by which
+ 			#  returned result should be ordered; ":asc" and ":desc" can be
+			#  appended accordingly
+			# @option options [Integer] result_limit specifies maximum number
+			#  of channels to return: default is 50 and maximum result limit is
+			#  1000
+			# @option options [Integer] result_offset specifies how many channels
+			#  should be skipped at the beginning of the result set
+ 			# @option options [String] aggregate specifies if returned channel
+ 			#  views statistics should be aggregate: true or false
+ 			# @option options [String] group_days specifies if returned channel
+ 			#  views statistics should be grouped by year and month
+ 			# @option options [String] include_empty_days specifies if channel
+ 			#  views statistics should include days for which there is no
+ 			#  statistics available: true or false
+ 			#
+ 			# @return [Array] a list of objects with the statistics of the
+ 			#  all channels matching the given criteria
 			def list(**options)
 				json = get_request(options.merge(:method => 'list'))
 				res = JSON.parse(json.body)

data/lib/botr/version.rb

@@ -1,3 +1,3 @@
 module BOTR
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/botr/videos/video.rb

@@ -7,7 +7,6 @@ module BOTR
 	# A video object is a metadata container that actually contains multiple
 	# video files (conversions). It does _not_ reference the actual video file
 	# located on the content server.
-	#
 	class Video < BOTR::Object
 
 		class << self
@@ -44,10 +43,30 @@ module BOTR
 			#  with these tags (multiple tags should be comma-separated)
 			# @option options [String] tags_mode tags search mode: "all" -- a
 			#  video will only be listed if it has all tags specified in the
-			#  tags parameter or "any" -- A video will be listed if it has at
+			#  tags parameter or "any" -- a video will be listed if it has at
 			#  least one tag specified in the tags parameter
+			# @option options [String] search case-insensitive search in the
+			#  author, description, link, md5, tags, title and video_key fields
+			# @option options [String] mediatypes_filter list only videos with
+			#  the specified media types: "unknown", "audio", "video"
+			# @option options [String] statuses_filter list only videos with the
+			#  specified statuses: "created", "processing", "ready", "updating",
+			#  "failed"
+			# @option options [String] order_by specifies parameters by which
+			#  returned result should be ordered; ":asc" and ":desc" can be
+			#  appended accordingly
+			# @option options [Integer] start_date video creation date starting
+			#  from which videos list should be returned as a UNIX timestamp
+			# @option options [Integer] end_date video creation date until
+			#  (and including) which videos list should be returned as a UNIX
+			#  timestamp
+			# @option options [Integer] result_limit specifies maximum number of
+			#  videos to return; default is 50 and maximum result limit is 1000
+			# @option options [Integer] result_offset specifies how many videos
+			#  should be skipped at the beginning of the result set; default is
+			#  0
 			#
-			# @return [Array] a list of video object matching the search
+			# @return [Array] a list of video objects matching the search
 			#  criteria
 			def list(**options)
 				json = get_request(options.merge(:method => 'list'))
@@ -64,7 +83,7 @@ module BOTR
 
 			# Return a list of all videos.
 			#
-			# @note Same as calling list with no arguments given.
+			# @note Same as calling `list` with no arguments given.
 			def all
 				list({})
 			end
@@ -101,6 +120,25 @@ module BOTR
 			end		
 		end
 
+		# Create a new video by sending metadata and requesting an upload URL.
+		#
+		# @param [Hash] options video parameters
+		#
+		# @option options [String] title title of the video
+		# @option options [String] tags tags for the video; multiple tags should
+		#  be comma-separated
+		# @option options [String] description description of the video
+		# @option options [String] author author of the video
+		# @option options [Integer] date video creation date as UNIX timestamp
+		# @option options [String] link the URL of the web page where this video
+		#  is published
+		# @option options [String] download_url URL from where to fetch a video
+		#  file; only URLs with the http protocol are supported
+		# @option options [String] md5 video file MD5 message digest
+		# @option options [Integer] size video file size
+		#
+		# @return [BOTR::Video] this video object with the parameters specified in
+		#  the options hash and an upload link
 		def create(**options)
 			json = get_request(options.merge(:method => 'create'))
 			res = JSON.parse(json.body)
@@ -127,6 +165,25 @@ module BOTR
 			return self
 		end
 
+		# Update the properties of a video.
+		#
+		# @param [Hash] options video parameters
+		#
+		# @option options [String] title title of the video
+		# @option options [String] tags tags for the video; multiple tags should
+		#  be comma-separated
+		# @option options [String] description description of the video
+		# @option options [String] author author of the video
+		# @option options [Integer] date video creation date as UNIX timestamp
+		# @option options [String] link the URL of the web page where this video
+		#  is published
+		# @option options [String] download_url URL from where to fetch a video
+		#  file; only URLs with the http protocol are supported
+		# @option options [String] md5 video file MD5 message digest
+		# @option options [Integer] size video file size
+		#
+		# @return [BOTR::Video] this object with the properties of the
+		#  video referenced by the options hash
 		def update(**options)
 			json = put_request(options.merge(:video_key => @key))
 			res = JSON.parse(json.body)
@@ -140,6 +197,9 @@ module BOTR
 			return self
 		end
 
+		# Remove a video and all of its conversions from the server.
+		#
+		# @return [BOTR::Video] this object with null properties
 		def delete
 			json = delete_request({:video_key => @key})
 			res = JSON.parse(json.body)

data/lib/botr/videos/video_caption.rb

@@ -1,14 +1,22 @@
 module BOTR
 
+	# The BOTR::VideoCaption class contains calls for manipulating videos captions.
 	class VideoCaption < BOTR::Object
 
 		class << self
 
 			attr_reader :last_status
 
-			def show(key)
+			# Show video caption information.
+			#
+ 			# @param [String] caption_key key of the caption which information
+ 			#  to show
+ 			#
+ 			# @return [BOTR::VideoCaption] a new object with the properties of the
+ 			#  caption referenced by the caption_key
+			def show(video_key)
 				json = get_request({:method => 'show',
-								    :caption_key => key})
+								    :caption_key => video_key})
 				res = JSON.parse(json.body)
 
 				if json.status == 200
@@ -22,9 +30,31 @@ module BOTR
 
 			alias :find :show
 
-			def list(key, **options)
+			# Return a list of videos captions.
+			#
+			# @param [Hash] options search parameters
+			#
+			# @option options [String] video_key key of the video which captions
+			#  to list
+			# @option options [String] search case-insensitive search in the
+			#  caption key and label fields
+			# @option options [String] statuses_filter list only captions with
+			#  the specified statuses: "processing", "ready", "updating",
+			#  "failed", "deleted"
+			# @option options [String] order_by specifies parameters by which
+			#  returned result should be ordered; ":asc" and ":desc" can be
+			#  appended accordingly
+			# @option options [Integer] result_limit specifies maximum number of
+			#  captions to return; default is 50 and maximum result limit is 1000
+			# @option options [Integer] result_offset specifies how many captions
+			#  should be skipped at the beginning of the result set; default is
+			#  0
+			#
+			# @return [Array] a list of video caption objects matching the search
+			#  criteria
+			def list(video_key, **options)
 				json = get_request(options.merge(:method => 'list',
-												 :video_key => key))
+												 :video_key => video_key))
 				res = JSON.parse(json.body)
 				
 				if json.status == 200
@@ -67,6 +97,20 @@ module BOTR
 			end		
 		end
 
+		# Create a new video caption.
+		#
+		# @param [String] video_key key of the video for which caption should be
+		#  created
+		# @param [Hash] options caption parameters
+		#
+		# @option options [String] label caption label
+		# @option options [Integer] position indicates where to insert the new
+		# caption; default is to insert at the end of the list
+		# @option options [String] md5 caption file MD5 message digest
+		# @option options [Integer] size caption file size
+		#
+		# @return [BOTR::VideoCaption] this video caption object with the
+		#  parameters specified in the options hash and an upload link
 		def create(video_key, **options)
 			json = get_request(options.merge(:method => 'create',
 											 :video_key => video_key))
@@ -94,6 +138,16 @@ module BOTR
 			return self
 		end
 
+		# Update video caption.
+		#
+		# @param [Hash] options caption parameters
+		#
+		# @option options [String] label caption label
+		# @option options [Integer] position indicates where to insert the new
+		# caption; default is to insert at the end of the list
+		#
+		# @return [BOTR::VideoCaption] this video caption object with the
+		#  parameters specified in the options hash and an optional upload link
 		def update(**options)
 			json = put_request(options.merge(:caption_key => @key))
 			res = JSON.parse(json.body)
@@ -107,6 +161,9 @@ module BOTR
 			return self
 		end
 
+		# Delete a video caption.
+		#
+		# @return [BOTR::VideoCaption] this object with null properties
 		def delete
 			json = delete_request({:caption_key => @key})
 			res = JSON.parse(json.body)

data/lib/botr/videos/video_conversion.rb

@@ -1,14 +1,27 @@
 module BOTR
 
+	# The BOTR::VideoConversion class calls are used to create, search for and
+	# delete individual video files (conversions) inside a video object.
+	#
+	# A conversion is always created by applying a transcoding template to a
+	# video. A template contains information for the dimensions, bitrate and
+	# watermark of the resulting conversion.
 	class VideoConversion < BOTR::Object
 
 		class << self
 
 			attr_reader :last_status
 
-			def show(key)
+			# Show video conversion information.
+			#
+ 			# @param [String] conversion_key key of the conversion for which to
+ 			#  show information
+ 			#
+ 			# @return [BOTR::VideoConversion] a new object with the properties
+ 			#  of the conversion referenced by the conversion_key
+			def show(conversion_key)
 				json = get_request({:method => 'show',
-								    :conversion_key => key})
+								    :conversion_key => conversion_key})
 				res = JSON.parse(json.body)
 
 				if json.status == 200
@@ -22,9 +35,24 @@ module BOTR
 
 			alias :find :show
 
-			def list(key)
-				json = get_request({:method => 'list',
-									:video_key => key})
+			# List conversions for a given video.
+			#
+			# @param [String] video_key key of the video for which to list
+			# conversions
+			# @param [Hash] options result parameters
+			#
+			# @option options [Integer] result_limit specifies maximum number of
+			#  video conversions to return; default is 50 and maximum result
+			#  limit is 1000
+			# @option options [Integer] result_offset specifies how many video
+			#  conversions should be skipped at the beginning of the result set;
+			#  default is 0
+			#
+			# @return [Array] a list of video conversion objects for the given
+			#  video key
+			def list(key, **options)
+				json = get_request(options.merge(:method => 'list',
+												 :video_key => key))
 				res = JSON.parse(json.body)
 				
 				if json.status == 200
@@ -64,9 +92,18 @@ module BOTR
 				param = "@#{key.to_s}"
 				next unless methods.include? key.to_sym
 				instance_variable_set(param, val)
-			end		
+			end
 		end
 
+		# Create a new conversion of a video.
+		#
+		# @param [String] video_key key of the video for which conversion should
+		#  be created
+		# @param [String] template_key key of the conversion template that
+		#  should be used for this conversion.
+		#
+		# @return [BOTR::VideoConversion] this object with the properties
+		#  of the conversion referenced by the template_key
 		def create(video_key, template_key)
 			json = get_request({:method => 'create',
 								:video_key => video_key,
@@ -82,6 +119,9 @@ module BOTR
 			return self
 		end
 
+		# Delete a video conversion from the CDN.
+		#
+		# @return [BOTR::VideoConversion] this object with null properties
 		def delete
 			json = delete_request({:conversion_key => @key})
 			res = JSON.parse(json.body)

data/lib/botr/videos/video_engagement.rb

@@ -1,5 +1,15 @@
 module BOTR
 
+	# The BOTR::VideoEngagement class contains calls for for displaying video
+	# engagement data.
+	# 
+	# Engagement analytics allow you to track which sections of a video are
+	# being watched by users. These analytics are useful for determining:
+	# 
+	# Drop off rates: Many users might drop off at a certain point in the video.
+	# Editing that section might increase engagement.
+	# Replay rates: Many users might replay a certain section in the video.
+	# This might be a location to target ads against.
 	class VideoEngagement < BOTR::Object
 
 		class << self
@@ -10,9 +20,16 @@ module BOTR
 				"videos/engagement"
 			end
 
-			def show(key)
+			# Displays engagement analytics for a single video.
+			#
+ 			# @param [String] video_key the key of the video to display
+ 			# engagement analytics for
+ 			#
+ 			# @return [BOTR::VideoEngagement] a new object with the engagement
+ 			#  analytics of the video referenced by the video key
+			def show(video_key)
 				json = get_request({:method => 'show',
-								    :video_key => key})
+								    :video_key => video_key})
 				res = JSON.parse(json.body)
 
 				if json.status == 200

data/lib/botr/videos/video_tag.rb

@@ -1,11 +1,32 @@
 module BOTR
 
+	# The BOTR::VideoTag class contains calls for manipulating video tags.
+	#
+	# Tags are essentially labels that can be used for the classification of
+	# videos.
 	class VideoTag < BOTR::Object
 
 		class << self
 
 			attr_reader :last_status
 
+			# Return a list of video tags.
+			#
+			# @param [Hash] options search parameters
+			#
+			# @option options [String] search case-insensitive search in the
+			#  name tag field
+			# @option options [String] order_by specifies parameters by which
+			#  returned result should be ordered; ":asc" and ":desc" can be
+			#  appended accordingly
+			# @option options [Integer] result_limit specifies maximum number of
+			#  tags to return; default is 50 and maximum result limit is 1000
+			# @option options [Integer] result_offset specifies how many tags
+			#  should be skipped at the beginning of the result set; default is
+			#  0
+			#
+			# @return [Array] a list of tag objects matching the search
+			#  criteria
 			def list(**options)
 				json = get_request(options.merge(:method => 'list'))
 				res = JSON.parse(json.body)

data/lib/botr/videos/video_thumbnail.rb

@@ -1,14 +1,23 @@
 module BOTR
 
+	# The BOTR::VideoThumbnail class contains calls for managing the preview
+	# image of a video.
 	class VideoThumbnail < BOTR::Object
 
 		class << self
 
 			attr_reader :last_status
 
-			def show(key)
+			# Show video thumbnails creation status.
+			#
+ 			# @param [String] video_key key of the video for which to show
+ 			#  thumbnails creation status
+ 			#
+ 			# @return [BOTR::VideoThumbnail] a new object with the thumbnail status of
+ 			#  the video referenced by the video key
+			def show(video_key)
 				json = get_request({:method => 'show',
-								    :video_key => key})
+								    :video_key => video_key})
 				res = JSON.parse(json.body)
 
 				if json.status == 200
@@ -43,6 +52,24 @@ module BOTR
 			end		
 		end
 
+		# Update a video’s thumbnail by either setting a frame from the video or
+		# uploading an image.
+		#
+		# @param [Hash] options video parameters
+		#
+		# @option options [Float] position video frame position in seconds from
+		#  which thumbnail should be generated; seconds can be given as a whole
+		#  number (e.g: 7) or with the fractions (e.g.: 7.42)
+		# @option options [String] tags tags for the video; multiple tags should
+		#  be comma-separated
+		# @option options [Integer] thumbnail_index index of the image in the
+		#  thumbnail strip to use as a video thumbnail; thumbnail index starts
+		#  from 1
+		# @option options [String] md5 thumbnail file MD5 message digest
+		# @option options [Integer] size thumbnail file size
+		#
+		# @return [BOTR::VideoThumbnail] this video thumbnail object with an
+		# optional upload link
 		def update(**options)
 			json = put_request(options.merge(:video_key => @key))
 			res = JSON.parse(json.body)

data/lib/botr/videos/video_view.rb

@@ -1,14 +1,43 @@
 module BOTR
 
+	# The BOTR::VideoView class contains calls for requesting video views
+	# statistics.
+	#
+	# A video view is counted every time:
+	# 
+	# The video starts playing in one of your players.
+	# The video starts downloading from our content server.
+	# When a user scrubs through the video in a player or restarts the video, no
+	# additional view is counted.
 	class VideoView < BOTR::Object
 
 		class << self
 
 			attr_reader :last_status
 
-			def show(key, **options)
+			# Shows views statistics for a video.
+			#
+ 			# @param [String] video_key key of the video for which to show views
+ 			#  statistics
+ 			# @params [Hash] options stats parameters
+ 			#
+ 			# @option options [Integer] start_date Unix timestamp of date
+ 			#  from which videos views statistics should be start
+ 			# @option options [Integer] end_date Unix timestamp of date
+ 			#  on which videos views statistics should be end
+ 			# @option options [String] aggregate specifies if returned video
+ 			#  views statistics should be aggregate: true or false
+ 			# @option options [String] group_days specifies if returned video
+ 			#  views statistics should be grouped by year and month
+ 			# @option options [String] include_empty_days specifies if video
+ 			#  views statistics should include days for which there is no
+ 			#  statistics available: true or false
+ 			#
+ 			# @return [BOTR::VideoView] a new object with the statistics for the
+ 			#  video referenced by the video_key
+			def show(video_key, **options)
 				json = get_request(options.merge(:method => 'show',
-								    			 :video_key => key))
+								    			 :video_key => video_key))
 				res = JSON.parse(json.body)
 
 				if json.status == 200
@@ -22,6 +51,38 @@ module BOTR
 
 			alias :find :show
 
+			# List views statistics for a video.
+			#
+ 			# @params [Hash] options stats parameters
+ 			#
+ 			# @option options [Integer] start_date Unix timestamp of date
+ 			#  from which video views statistics should be start
+ 			# @option options [Integer] end_date Unix timestamp of date
+ 			#  on which video views statistics should be end
+ 			# @option options [String] list_by specifies video views statistics
+ 			#  listing type: "video" or "day"
+ 			# @option options [String] order_by specifies parameters by which
+ 			#  returned result should be ordered; ":asc" and ":desc" can be
+			#  appended accordingly
+			# @option options [String] search case-insensitive search in the
+			#  author, description, link, md5, tags, title, video_key fields and
+			#  custom fields
+			# @option options [Integer] result_limit specifies maximum number
+			#  of videos to return: default is 50 and maximum result limit is 1000
+			# @option options [Integer] result_offset specifies how many videos
+			#  should be skipped at the beginning of the result set
+ 			# @option options [String] aggregate specifies if returned video
+ 			#  views statistics should be aggregate: true or false
+ 			# @option options [String] group_days specifies if returned video
+ 			#  views statistics should be grouped by year and month
+ 			# @option options [String] include_empty_days specifies if video
+ 			#  views statistics should include days for which there is no
+ 			#  statistics available: true or false
+ 			# @option options [String] statuses_filter list only videos with the
+ 			#  specified statuses: "active", "deleted"
+ 			#
+ 			# @return [Array] a list of objects with the statistics of the
+ 			#  all videos matching the search criteria
 			def list(**options)
 				json = get_request(options.merge(:method => 'list'))
 				res = JSON.parse(json.body)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: botr
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - bertrandk
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-08-11 00:00:00.000000000 Z
+date: 2013-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -85,6 +85,7 @@ files:
 - botr.watchr
 - certs/cacert.pem
 - lib/botr.rb
+- lib/botr/accounts/account_usage.rb
 - lib/botr/api/api.rb
 - lib/botr/api/authentication.rb
 - lib/botr/channels/channel.rb