yt 0.19.0 → 0.20.0

data/lib/yt/models/claim.rb

@@ -42,9 +42,6 @@ module Yt
 
 # Status
 
-      STATUSES = %q(active appealed disputed inactive pending potential
-        takedown unknown)
-
       # Returns the claim’s status.
       # @return [String] the claim’s status. Possible values are: +'active'+,
       #   +'appealed'+, +'disputed'+, +'inactive'+, +'pending'+, +'potential'+,
@@ -96,8 +93,6 @@ module Yt
 
 # Content Type
 
-      CONTENT_TYPES = %q(audio video audiovisual)
-
       # Returns the audiovisual portion of the claimed content.
       # @return [String] the audiovisual portion of the claimed content.
       #   Possible values are: +'audio'+, +'audiovisual'+, +'video'+.

data/lib/yt/models/content_owner_detail.rb

@@ -10,32 +10,8 @@ module Yt
         @data = options[:data] || {}
       end
 
-      # Returns the name of the content owner linked to the channel.
-      #
-      # This method requires {Resource#auth auth} to return an authenticated
-      # instance of {Yt::ContentOwner} that can administer the channel.
-      # @return [String] if the channel is partnered with a content owner,
-      #   the name of the content owner linked to the channel.
-      # @return [nil] if the channel is not partnered with a content owner.
-      # @return [nil] if {Resource#auth auth} is a content owner without
-      #   permissions to administer the channel.
-      # @raise [Yt::Errors::Forbidden] if {Resource#auth auth} does not
-      #   return an authenticated content owner.
       has_attribute :content_owner
-
-      # Returns the date and time of when the channel was linked to the content
-      # owner.
-      #
-      # This method requires {Resource#auth auth} to return an authenticated
-      # instance of {Yt::ContentOwner} that can administer the channel.
-      # @return [Time] if the channel is partnered with a content owner,
-      #   the date and time when the channel was linked with the content owner.
-      # @return [nil] if the channel is not partnered with a content owner.
-      # @return [nil] if {Resource#auth auth} is a content owner without
-      #   permissions to administer the channel.
-      # @raise [Yt::Errors::Forbidden] if {Resource#auth auth} does not
-      #   return an authenticated content owner.
-      has_attribute :linked_at, type: Time, from: :time_linked
+      has_attribute :time_linked, type: Time
     end
   end
 end

data/lib/yt/models/id.rb

@@ -1,5 +1,6 @@
 module Yt
   module Models
+    # @private
     # Encapsulates information about the ID that YouTube uses to uniquely
     # identify a resource.
     class Id < String

data/lib/yt/models/playlist.rb

@@ -5,70 +5,151 @@ module Yt
     # Provides methods to interact with YouTube playlists.
     # @see https://developers.google.com/youtube/v3/docs/playlists
     class Playlist < Resource
-      delegate :tags, :channel_id, :channel_title, to: :snippet
 
-      # @!attribute [r] playlist_items
-      #   @return [Yt::Collections::PlaylistItems] the playlist’s items.
-      has_many :playlist_items
+    ### SNIPPET ###
 
-      # @macro has_report
-      has_report :views
+      # @!attribute [r] title
+      # @return [String] the playlist’s title.
+      delegate :title, to: :snippet
 
-      # @macro has_report
-      has_report :playlist_starts
+      # @!attribute [r] description
+      # @return [String] the playlist’s description.
+      delegate :description, to: :snippet
 
-      # @macro has_report
-      has_report :average_time_in_playlist
+      # Returns the URL of the playlist’s thumbnail.
+      # @!method thumbnail_url(size = :default)
+      # @param [Symbol, String] size The size of the playlist’s thumbnail.
+      # @return [String] if +size+ is +default+, the URL of a 120x90px image.
+      # @return [String] if +size+ is +medium+, the URL of a 320x180px image.
+      # @return [String] if +size+ is +high+, the URL of a 480x360px image.
+      # @return [nil] if the +size+ is not +default+, +medium+ or +high+.
+      delegate :thumbnail_url, to: :snippet
 
-      # @macro has_report
-      has_report :views_per_playlist_start
+      # @!attribute [r] published_at
+      # @return [Time] the date and time that the playlist was created.
+      delegate :published_at, to: :snippet
+
+      # @!attribute [r] channel_id
+      # @return [String] the ID of the channel that the playlist belongs to.
+      delegate :channel_id, to: :snippet
+
+      # @!attribute [r] channel_title
+      # @return [String] the title of the channel that the playlist belongs to.
+      delegate :channel_title, to: :snippet
+
+      # @!attribute [r] tags
+      # @return [Array<String>] the list of tags attached to the playlist.
+      delegate :tags, to: :snippet
+
+    ### ACTIONS (UPLOAD, UPDATE, DELETE) ###
 
       # Deletes the playlist.
-      #
-      # This method requires {Resource#auth auth} to return an authenticated
-      # instance of {Yt::Account} with permissions to delete the playlist.
-      # @raise [Yt::Errors::Unauthorized] if {Resource#auth auth} does not
-      #   return an account with permissions to delete the playlist.
       # @return [Boolean] whether the playlist does not exist anymore.
+      # @raise [Yt::Errors::Unauthorized] if {Resource#auth auth} is not an
+      #   authenticated Yt::Account with permissions to delete the playlist.
       def delete(options = {})
         do_delete {@id = nil}
         !exists?
       end
 
-      def exists?
-        !@id.nil?
-      end
-
-      # Adds a video to the playlist
-      # Does not raise an error if the video cannot be added (e.g., unknown).
-      #
-      # This method requires {Resource#auth auth} to return an authenticated
-      # instance of {Yt::Account} with permissions to update the playlist.
-      # @raise [Yt::Errors::Unauthorized] if {Resource#auth auth} does not
-      #   return an account with permissions to update the playlist.
+      # Adds a video to the playlist.
+      # Unlike {#add_video!}, does not raise an error if video can’t be added.
+      # @param [String] video_id the video to add to the playlist.
+      # @param [Hash] options the options on how to add the video.
+      # @option options [Integer] :position where to add video in the playlist.
+      # @raise [Yt::Errors::Unauthorized] if {Resource#auth auth} is not an
+      #   authenticated Yt::Account with permissions to update the playlist.
       # @return [Yt::PlaylistItem] the item added to the playlist.
-      def add_video(video_id, attributes = {})
-        playlist_item_params = playlist_item_params(video_id, attributes)
+      def add_video(video_id, options = {})
+        playlist_item_params = playlist_item_params(video_id, options)
         playlist_items.insert playlist_item_params, ignore_errors: true
       end
 
-      def add_video!(video_id, attributes = {})
-        playlist_item_params = playlist_item_params(video_id, attributes)
+      # Adds a video to the playlist.
+      # Unlike {#add_video}, raises an error if video can’t be added.
+      # @param [String] video_id the video ID to add to the playlist.
+      # @param [Hash] options the options on how to add the video.
+      # @option options [Integer] :position where to add video in the playlist.
+      # @raise [Yt::Errors::RequestError] if video can’t be added.
+      # @raise [Yt::Errors::Unauthorized] if {Resource#auth auth} is not an
+      #   authenticated Yt::Account with permissions to update the playlist.
+      # @return [Yt::PlaylistItem] the item added to the playlist.
+      def add_video!(video_id, options = {})
+        playlist_item_params = playlist_item_params(video_id, options)
         playlist_items.insert playlist_item_params
       end
 
-      def add_videos(video_ids = [], attributes = {})
-        video_ids.map{|video_id| add_video video_id, attributes}
+      # Adds multiple videos to the playlist.
+      # Unlike {#add_videos!}, does not raise an error if videos can’t be added.
+      # @param [Array<String>] video_ids the video IDs to add to the playlist.
+      # @param [Hash] options the options on how to add the videos.
+      # @option options [Integer] :position where to add videos in the playlist.
+      # @raise [Yt::Errors::Unauthorized] if {Resource#auth auth} is not an
+      #   authenticated Yt::Account with permissions to update the playlist.
+      # @return [Array<Yt::PlaylistItem>] the items added to the playlist.
+      def add_videos(video_ids = [], options = {})
+        video_ids.map{|video_id| add_video video_id, options}
       end
 
-      def add_videos!(video_ids = [], attributes = {})
-        video_ids.map{|video_id| add_video! video_id, attributes}
+      # Adds multiple videos to the playlist.
+      # Unlike {#add_videos}, raises an error if videos can’t be added.
+      # @param [Array<String>] video_ids the video IDs to add to the playlist.
+      # @param [Hash] options the options on how to add the videos.
+      # @option options [Integer] :position where to add videos in the playlist.
+      # @raise [Yt::Errors::Unauthorized] if {Resource#auth auth} is not an
+      #   authenticated Yt::Account with permissions to update the playlist.
+      # @return [Array<Yt::PlaylistItem>] the items added to the playlist.
+      def add_videos!(video_ids = [], options = {})
+        video_ids.map{|video_id| add_video! video_id, options}
       end
 
-      def delete_playlist_items(attrs = {})
-        playlist_items.delete_all attrs
+      # Deletes the playlist’s items matching all the given attributes.
+      # @return [Array<Boolean>] whether each playlist item matching the given
+      #   attributes was deleted.
+      # @raise [Yt::Errors::RequestError] if {Resource#auth auth} is not an
+      #   authenticated Yt::Account with permissions to update the playlist.
+      # @param [Hash] attributes the attributes to match the items by.
+      # @option attributes [<String, Regexp>] :title The item’s title.
+      #   Pass a String for perfect match or a Regexp for advanced match.
+      # @option attributes [<String, Regexp>] :description The item’s
+      #   description. Pass a String (perfect match) or a Regexp (advanced).
+      # @option attributes [String] :privacy_status The item’s privacy status.
+      # @option attributes [String] :video_id The item’s video ID.
+      def delete_playlist_items(attributes = {})
+        playlist_items.delete_all attributes
       end
 
+    ### ASSOCIATIONS ###
+
+      # @!attribute [r] playlist_items
+      #   @return [Yt::Collections::PlaylistItems] the playlist’s items.
+      has_many :playlist_items
+
+    ### ANALYTICS ###
+
+      # @macro report_by_playlist_dimensions
+      has_report :views
+
+      # @macro report_by_playlist_dimensions
+      has_report :estimated_minutes_watched
+
+      # @macro report_by_gender_and_age_group
+      has_report :viewer_percentage
+
+      # @macro report_by_day
+      has_report :average_view_duration
+
+      # @macro report_by_day
+      has_report :playlist_starts
+
+      # @macro report_by_day
+      has_report :average_time_in_playlist
+
+      # @macro report_by_day
+      has_report :views_per_playlist_start
+
+    ### PRIVATE API ###
+
       # @private
       # Tells `has_reports` to retrieve the reports from YouTube Analytics API
       # either as a Channel or as a Content Owner.
@@ -84,6 +165,11 @@ module Yt
         end
       end
 
+      # @private
+      def exists?
+        !@id.nil?
+      end
+
     private
 
       # @see https://developers.google.com/youtube/v3/docs/playlists/update

data/lib/yt/models/playlist_item.rb

@@ -5,30 +5,76 @@ module Yt
     # Provides methods to interact with YouTube playlist items.
     # @see https://developers.google.com/youtube/v3/docs/playlistItems
     class PlaylistItem < Resource
-      delegate :channel_id, :channel_title, :playlist_id, :video_id,
-        :video, to: :snippet
 
+    ### SNIPPET ###
+
+      # @!attribute [r] title
+      # @return [String] the item’s title.
+      delegate :title, to: :snippet
+
+      # @!attribute [r] description
+      # @return [String] the item’s description.
+      delegate :description, to: :snippet
+
+      # Returns the URL of the item’s thumbnail.
+      # @!method thumbnail_url(size = :default)
+      # @param [Symbol, String] size The size of the item’s thumbnail.
+      # @return [String] if +size+ is +default+, the URL of a 120x90px image.
+      # @return [String] if +size+ is +medium+, the URL of a 320x180px image.
+      # @return [String] if +size+ is +high+, the URL of a 480x360px image.
+      # @return [nil] if the +size+ is not +default+, +medium+ or +high+.
+      delegate :thumbnail_url, to: :snippet
+
+      # @!attribute [r] published_at
+      # @return [Time] the time that the item was added to the playlist.
+      delegate :published_at, to: :snippet
+
+      # @!attribute [r] channel_id
+      # @return [String] the ID of the channel that the item belongs to.
+      delegate :channel_id, to: :snippet
+
+      # @!attribute [r] channel_title
+      # @return [String] the title of the channel that the item belongs to.
+      delegate :channel_title, to: :snippet
+
+      # @!attribute [r] playlist_id
+      # @return [String] the ID of the playlist that the item is in.
+      delegate :playlist_id, to: :snippet
+
+      # @return [String] the ID of the video referred by the item.
+      def video_id
+        snippet.resource_id['videoId']
+      end
+
+      # @return [Integer] the order in which the item appears in a playlist.
+      #   The value is zero-based, so the first item has a position of 0.
+      def position
+        ensure_complete_snippet :position
+      end
+
+    ### ACTIONS (UPLOAD, UPDATE, DELETE) ###
+
+      # Deletes the playlist item.
+      # @return [Boolean] whether the playlist item does not exist anymore.
+      # @raise [Yt::Errors::Unauthorized] if {Resource#auth auth} is not an
+      #   authenticated Yt::Account with permissions to delete the item.
       def delete(options = {})
         do_delete {@id = nil}
         !exists?
       end
 
-      def exists?
-        !@id.nil?
+    ### ASSOCIATIONS ###
+
+      # @return [Yt::Models::Video] the video referred by the item.
+      def video
+        @video ||= Video.new id: video_id, auth: @auth if video_id
       end
 
-      # Returns the position of the item in the playlist.
-      # Since YouTube API does not return the position on PlaylistItem#create,
-      # the memoized @snippet is erased if the video was instantiated like that,
-      # so that the full snippet (with position) is loaded, rather than the
-      # partial one.
-      # @see https://developers.google.com/youtube/v3/docs/playlistItems
-      # @return [Integer] the order in which the item appears in a playlist.
-      def position
-        unless snippet.position || snippet.complete? || @auth.nil?
-          @snippet = nil
-        end
-        snippet.position
+    ### PRIVATE API ###
+
+      # @private
+      def exists?
+        !@id.nil?
       end
 
     private

data/lib/yt/models/reference.rb

@@ -81,10 +81,6 @@ module Yt
 
 # Status
 
-      STATUSES = %q(activating active checking computing_fingerprint deleted
-        duplicate_on_hold inactive live_streaming_processing
-        urgent_reference_processing)
-
       # @return [String] the reference’s status. Possible values are:
       #   +'activating'+, +'active'+, +'checking'+, +'computing_fingerprint'+,
       #   +'deleted'+, +'duplicate_on_hold'+, +'inactive'+,
@@ -141,8 +137,6 @@ module Yt
 
 # Content Type
 
-      CONTENT_TYPES = %q(audio video audiovisual)
-
       # Returns the audiovisual portion of the referenced content.
       # @return [String] the audiovisual portion of the referenced content.
       #   Possible values are: +'audio'+, +'audiovisual'+, +'video'+.

data/lib/yt/models/resource.rb

@@ -71,6 +71,17 @@ module Yt
 
     private
 
+      # Since YouTube API only returns tags on Videos#list, the memoized
+      # `@snippet` is erased if the video was instantiated through Video#search
+      # (e.g., by calling account.videos or channel.videos), so that the full
+      # snippet (with tags and category) is loaded, rather than the partial one.
+      def ensure_complete_snippet(attribute)
+        unless snippet.public_send(attribute).present? || snippet.complete?
+          @snippet = nil
+        end
+        snippet.public_send attribute
+      end
+
       # TODO: instead of having Video, Playlist etc override this method,
       #       they should define *what* can be updated in their own *update*
       #       method.

data/lib/yt/models/snippet.rb

@@ -2,11 +2,7 @@ require 'yt/models/description'
 
 module Yt
   module Models
-    # Contains basic information about the resource. The details of the snippet
-    # are different for the different types of resources.
-    #
-    # Resources with a
-    # snippet are: channels, playlists, playlist items and videos.
+    # Provides methods to interact with the snippet YouTube resources.
     # @see https://developers.google.com/youtube/v3/docs/channels#resource
     # @see https://developers.google.com/youtube/v3/docs/videos#resource
     # @see https://developers.google.com/youtube/v3/docs/playlists#resource
@@ -19,102 +15,21 @@ module Yt
         @auth = options[:auth]
       end
 
-      # @return [String] if the resource is a channel, the channel’s title.
-      # @return [String] if the resource is a playlist, the playlist’s title.
-      # @return [String] if the resource is a playlist item, the item’s title.
       has_attribute :title, default: ''
-
-      # @return [Yt::Models::Description] if the resource is a channel, the
-      #   channel’s description. Has a maximum of 1000 characters.
-      # @return [Yt::Models::Description] if the resource is a playlist, the
-      #   playlist’s description.
-      # @return [Yt::Models::Description] if the resource is a playlist item,
-      #   the item’s description.
-      has_attribute :description, default: '' do |description_text|
-        Description.new description_text
-      end
-
-      # @return [Time] if the resource is a channel, the date and time that the
-      #  channel was created.
-      # @return [Time] if the resource is a playlist, the date and time that
-      #   the playlist was created.
-      # @return [Time] if the resource is a playlist item, the date and time
-      #   that the item was added to the playlist.
+      has_attribute(:description, default: '') {|text| Description.new text}
       has_attribute :published_at, type: Time
-
-      # @param [Symbol, String] size The size of the thumbnail to retrieve.
-      # @return [String] if the resource is a channel and +size+ is +default+,
-      #   the URL of an 88x88px image.
-      # @return [String] if the resource is a playlist or a playlist item and
-      #   +size+ is +default+, the URL of an 120x90px image.
-      # @return [String] if the resource is a channel and +size+ is +medium+,
-      #   the URL of an 240x240px image.
-      # @return [String] if the resource is a playlist or a playlist item and
-      #   +size+ is +medium+, the URL of an 320x180px image.
-      # @return [String] if the resource is a channel and +size+ is +high+,
-      #   the URL of an 800x800px image.
-      # @return [String] if the resource is a playlist or a playlist item and
-      #   +size+ is +high+, the URL of an 480x360px image.
-      # @return [nil] if the +size+ is not +default+, +medium+ or +high+.
-      def thumbnail_url(size = :default)
-        thumbnails.fetch(size.to_s, {})['url']
-      end
-
-      # @return [String] if the resource is a playlist, the ID that YouTube
-      #   uses to uniquely identify the channel that the playlist belongs to.
-      # @return [String] if the resource is a playlist item, the ID that YouTube
-      #   uses to uniquely identify the channel that the playlist belongs to.
-      # @return [nil] if the resource is a channel.
       has_attribute :channel_id
-
-      # @return [String] if the resource is a playlist, the title of the
-      #   channel that the playlist belongs to.
-      # @return [String] if the resource is a playlist item, the title of the
-      #   channel that the playlist item belongs to.
-      # @return [nil] if the resource is a channel.
       has_attribute :channel_title
-
-      # @return [Array<Yt::Models::Tag>] if the resource is a channel, an
-      #   empty array.
-      # @return [Array<Yt::Models::Tag>] if the resource is a playlist, the
-      #   list of keyword tags associated with the playlist.
-      # @return [Array<Yt::Models::Tag>] if the resource is a playlist item,
-      #   an empty array.
       has_attribute :tags, default: []
-
       has_attribute :category_id
-
-      BROADCAST_TYPES = %q(live none upcoming)
-
       has_attribute :live_broadcast_content
-
-      # @return [String] if the resource is a playlist item, the ID that
-      #   YouTube uses to uniquely identify the playlist that the item is in.
-      # @return [nil] if the resource is a channel.
-      # @return [nil] if the resource is a playlist.
       has_attribute :playlist_id
-
-      # @return [Integer] if the resource is a playlist item, the order in
-      #   which the item appears in a playlist. The value is zero-based, so the
-      #   first item has a position of 0, the second item of 1, and so forth.
-      # @return [nil] if the resource is a channel.
-      # @return [nil] if the resource is a playlist.
       has_attribute :position, type: Integer
+      has_attribute :resource_id, default: {}
+      has_attribute :thumbnails, default: {}
 
-      # @return [String] if the resource is a playlist item, the ID of the
-      #   video the playlist item represents in the playlist.
-      # @return [nil] if the resource is a channel.
-      # @return [nil] if the resource is a playlist.
-      def video_id
-        resource_id['videoId']
-      end
-
-      # @return [Yt::Models::Video] the video the playlist item represents in
-      #   the playlist.
-      # @return [nil] if the resource is a channel.
-      # @return [nil] if the resource is a playlist.
-      def video
-        @video ||= Video.new id: video_id, auth: @auth if video_id
+      def thumbnail_url(size = :default)
+        thumbnails.fetch(size.to_s, {})['url']
       end
 
       # Returns whether YouTube API includes all attributes in this snippet.
@@ -129,11 +44,6 @@ module Yt
       def complete?
         @complete ||= data.fetch :complete, true
       end
-
-    private
-
-      has_attribute :thumbnails, default: {}
-      has_attribute :resource_id, default: {}
     end
   end
 end