yt-andrewroth 0.25.5.1

data/lib/yt/models/description.rb

@@ -0,0 +1,58 @@
+require 'yt/models/url'
+
+module Yt
+  module Models
+    # Encapsulates information about the description of a resource, for
+    # instance a channel.
+    # @see https://developers.google.com/youtube/v3/docs/channels#resource
+    #
+    # The value has a maximum length of 1000 characters.
+    class Description < String
+      # @return [Boolean] whether the description includes a link to a video
+      # @example
+      #   description = Yt::Models::Description.new 'Link to video: youtube.com/watch?v=MESycYJytkU'
+      #   description.has_link_to_video? #=> true
+      #
+      # @todo add an option to match the link to a specific video
+      def has_link_to_video?
+        links.any?{|link| link.kind == :video}
+      end
+
+      # @return [Boolean] whether the description includes a link to a channel
+      # @example
+      #   description = Yt::Description.new 'Link to channel: youtube.com/fullscreen'
+      #   description.has_link_to_channel? #=> true
+      #
+      # @todo add an option to match the link to a specific channel
+      def has_link_to_channel?(options = {})
+        links.any?{|link| link.kind == :channel}
+      end
+
+      # @return [Boolean] whether the description includes a link to subscribe
+      # @example
+      #   description = Yt::Description.new 'Link to subscribe: youtube.com/subscription_center?add_user=fullscreen'
+      #   description.has_link_to_subscribe? #=> true
+      #
+      # @todo add an option to match the link to subscribe to a specific channel
+      def has_link_to_subscribe?(options = {})
+        links.any?{|link| link.kind == :subscription}
+      end
+
+      # @return [Boolean] whether the description includes a link to a playlist
+      # @example
+      #   description = Yt::Description.new 'Link to playlist: youtube.com/playlist?list=LLxO1tY8h1AhOz0T4ENwmpow'
+      #   description.has_link_to_playlist? #=> true
+      #
+      # @todo add an option to match the link to a specific playlist
+      def has_link_to_playlist?
+        links.any?{|link| link.kind == :playlist}
+      end
+
+    private
+
+      def links
+        @links ||= self.split(' ').map{|word| URL.new word}
+      end
+    end
+  end
+end

data/lib/yt/models/device_flow.rb

@@ -0,0 +1,16 @@
+require 'yt/models/base'
+
+module Yt
+  module Models
+    # @private
+    class DeviceFlow < Base
+      def initialize(options = {})
+        @data = options[:data]
+      end
+
+      has_attribute :device_code, camelize: false
+      has_attribute :user_code, camelize: false
+      has_attribute :verification_url, camelize: false
+    end
+  end
+end

data/lib/yt/models/file_detail.rb

@@ -0,0 +1,21 @@
+require 'yt/models/base'
+
+module Yt
+  module Models
+    # @private
+    # Encapsulates basic information about the video file itself,
+    # including the file name, size, type, and container.
+    # @see https://developers.google.com/youtube/v3/docs/videos#fileDetails
+    class FileDetail < Base
+      attr_reader :data
+
+      def initialize(options = {})
+        @data = options[:data] || {}
+      end
+
+      has_attribute :file_size, type: Integer
+      has_attribute :file_type
+      has_attribute :container
+    end
+  end
+end

data/lib/yt/models/id.rb

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

data/lib/yt/models/iterator.rb

@@ -0,0 +1,16 @@
+module Yt
+  module Models
+    # @private
+    # If we dropped support for Ruby 1.9.3, then we could simply use Enumerator
+    # which takes a `size` parameter in Ruby >= 2.
+    class Iterator < Enumerator
+      def initialize(size=nil, &block)
+        RUBY_VERSION < '2' ? super(&block) : super(size, &block)
+      end
+
+      def size
+        RUBY_VERSION < '2' ? count : super
+      end
+    end
+  end
+end

data/lib/yt/models/live_streaming_detail.rb

@@ -0,0 +1,23 @@
+require 'yt/models/base'
+
+module Yt
+  module Models
+    # @private
+    # Encapsulates information about a live video broadcast.
+    # The object will only be present in a video resource if the video is an
+    # upcoming, live, or completed live broadcast.
+    # @see https://developers.google.com/youtube/v3/docs/videos#resource
+    class LiveStreamingDetail < Base
+
+      def initialize(options = {})
+        @data = options[:data] || {}
+      end
+
+      has_attribute :actual_start_time, type: Time
+      has_attribute :actual_end_time, type: Time
+      has_attribute :scheduled_start_time, type: Time
+      has_attribute :scheduled_end_time, type: Time
+      has_attribute :concurrent_viewers, type: Integer
+    end
+  end
+end

data/lib/yt/models/match_policy.rb

@@ -0,0 +1,34 @@
+require 'yt/models/base'
+
+module Yt
+  module Models
+    # Provides methods to interact with YouTube ContentID asset match policies,
+    # which YouTube applies to user-uploaded videos that match the asset.
+    # @see https://developers.google.com/youtube/partner/docs/v1/assetMatchPolicy
+    class MatchPolicy < Base
+      def initialize(options = {})
+        @asset_id = options[:asset_id]
+        @auth = options[:auth]
+      end
+
+      def update(attributes = {})
+        underscore_keys! attributes
+        do_patch body: attributes.slice(:policy_id)
+        true
+      end
+
+    private
+
+      # @return [Hash] the parameters to submit to YouTube to patch an asset
+      #   match policy.
+      # @see https://developers.google.com/youtube/partner/docs/v1/assetMatchPolicy/patch
+      def patch_params
+        super.tap do |params|
+          params[:path] = "/youtube/partner/v1/assets/#{@asset_id}/matchPolicy"
+          params[:params] = {on_behalf_of_content_owner: @auth.owner_name}
+          params[:expected_response] = Net::HTTPOK
+        end
+      end
+    end
+  end
+end

data/lib/yt/models/ownership.rb

@@ -0,0 +1,75 @@
+require 'yt/models/base'
+require 'yt/models/right_owner'
+
+module Yt
+  module Models
+    # Provides methods to interact with YouTube ContentID asset ownership,
+    # which provide ownership information for the specified asset.
+    # @see https://developers.google.com/youtube/partner/docs/v1/ownership
+    class Ownership < Base
+      def initialize(options = {})
+        @data = options[:data] || {}
+        @auth = options[:auth]
+        @asset_id = options[:asset_id]
+      end
+
+      def update(attributes = {})
+        underscore_keys! attributes
+        do_update body: attributes
+        true
+      end
+
+      # Assigns 100% of the general ownership of the asset to @auth.
+      def obtain!
+        update general: [{ratio: 100, owner: @auth.owner_name, type: :exclude}]
+      end
+
+      # Releases 100% of the general ownership of the asset from @auth.
+      def release!
+        update general: [{ratio: 0, owner: @auth.owner_name, type: :exclude}]
+      end
+
+      # @return [Array<RightOwner>] a list that identifies the owners of an
+      #   asset and the territories where each owner has ownership.
+      #   General  asset ownership is used for all types of assets and is the
+      #   only type  of ownership data that can be provided for assets that are
+      #   not compositions.
+      has_attribute :general_owners, from: :general do |data|
+        as_owners data
+      end
+
+      # @return [Array<RightOwner>] a list that identifies owners of the
+      #   performance rights for a composition asset.
+      has_attribute :performance_owners, from: :performance do |data|
+        as_owners data
+      end
+
+      # @return [Array<RightOwner>] a list that identifies owners of the
+      #   synchronization rights for a composition asset.
+      has_attribute :synchronization_owners, from: :synchronization do |data|
+        as_owners data
+      end
+
+      # @return [Array<RightOwner>] a list that identifies owners of the
+      #   mechanical rights for a composition asset.
+      has_attribute :mechanical_owners, from: :mechanical do |data|
+        as_owners data
+      end
+
+    private
+
+      # @see https://developers.google.com/youtube/partner/docs/v1/ownership/update
+      def update_params
+        super.tap do |params|
+          params[:expected_response] = Net::HTTPOK
+          params[:path] = "/youtube/partner/v1/assets/#{@asset_id}/ownership"
+          params[:params] = {on_behalf_of_content_owner: @auth.owner_name}
+        end
+      end
+
+      def as_owners(data)
+        (data || []).map{|owner_data| Yt::RightOwner.new data: owner_data}
+      end
+    end
+  end
+end

data/lib/yt/models/player.rb

@@ -0,0 +1,18 @@
+require 'yt/models/base'
+
+module Yt
+  module Models
+    # @private
+    # Encapsulates information about a video player.
+    # @see https://developers.google.com/youtube/v3/docs/videos#player
+    class Player < Base
+      attr_reader :data
+
+      def initialize(options = {})
+        @data = options[:data]
+      end
+
+      has_attribute :embed_html
+    end
+  end
+end

data/lib/yt/models/playlist.rb

@@ -0,0 +1,218 @@
+require 'yt/models/resource'
+
+module Yt
+  module Models
+    # Provides methods to interact with YouTube playlists.
+    # @see https://developers.google.com/youtube/v3/docs/playlists
+    class Playlist < Resource
+
+    ### SNIPPET ###
+
+      # @!attribute [r] title
+      #   @return [String] the playlist’s title.
+      delegate :title, to: :snippet
+
+      # @!attribute [r] description
+      #   @return [String] the playlist’s description.
+      delegate :description, to: :snippet
+
+      # @!method thumbnail_url(size = :default)
+      #   Returns the URL of the playlist’s thumbnail.
+      #   @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
+
+      # @!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.
+      # @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
+
+      # Updates the attributes of a playlist.
+      # @return [Boolean] whether the playlist was successfully updated.
+      # @raise [Yt::Errors::Unauthorized] if {Resource#auth auth} is not an
+      #   authenticated Yt::Account with permissions to update the playlist.
+      # @param [Hash] attributes the attributes to update.
+      # @option attributes [String] :title The new playlist’s title.
+      #   Cannot have more than 100 characters. Can include the characters
+      #   < and >, which are replaced to ‹ › in order to be accepted by YouTube.
+      # @option attributes [String] :description The new playlist’s description.
+      #   Cannot have more than 5000 bytes. Can include the characters
+      #   < and >, which are replaced to ‹ › in order to be accepted by YouTube.
+      # @option attributes [Array<String>] :tags The new playlist’s tags.
+      #   Cannot have more than 500 characters. Can include the characters
+      #   < and >, which are replaced to ‹ › in order to be accepted by YouTube.
+      # @option attributes [String] :privacy_status The new playlist’s privacy
+      #   status. Must be one of: private, unscheduled, public.
+      # @example Update title and description of a playlist.
+      #   playlist.update title: 'New title', description: 'New description'
+      # @example Update tags and status of a playlist.
+      #   playlist.update tags: ['new', 'tags'], privacy_status: 'public'
+      def update(attributes = {})
+        super
+      end
+
+      # 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, options = {})
+        playlist_item_params = playlist_item_params(video_id, options)
+        playlist_items.insert playlist_item_params, ignore_errors: true
+      end
+
+      # 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
+
+      # 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
+
+      # 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
+
+      # 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 reports
+
+      # @macro report_by_playlist_dimensions
+      has_report :views, Integer
+
+      # @macro report_by_playlist_dimensions
+      has_report :estimated_minutes_watched, Integer
+
+      # @macro report_by_gender_and_age_group
+      has_report :viewer_percentage, Float
+
+      # @macro report_by_day_and_state
+      has_report :average_view_duration, Integer
+
+      # @macro report_by_day_and_state
+      has_report :playlist_starts, Integer
+
+      # @macro report_by_day_and_state
+      has_report :average_time_in_playlist, Float
+
+      # @macro report_by_day_and_state
+      has_report :views_per_playlist_start, Float
+
+    ### PRIVATE API ###
+
+      # @private
+      # Tells `has_reports` to retrieve the reports from YouTube Analytics API
+      # either as a Channel or as a Content Owner.
+      # @see https://developers.google.com/youtube/analytics/v1/reports
+      def reports_params
+        {}.tap do |params|
+          if auth.owner_name
+            params[:ids] = "contentOwner==#{auth.owner_name}"
+          else
+            params[:ids] = "channel==#{channel_id}"
+          end
+          params[:filters] = "playlist==#{id};isCurated==1"
+        end
+      end
+
+      # @private
+      def exists?
+        !@id.nil?
+      end
+
+    private
+
+      # @see https://developers.google.com/youtube/v3/docs/playlists/update
+      def update_parts
+        keys = [:title, :description, :tags]
+        snippet = {keys: keys, required: true, sanitize_brackets: true}
+        status = {keys: [:privacy_status]}
+        {snippet: snippet, status: status}
+      end
+
+      # @todo: extend camelize to also camelize the nested hashes, so we
+      #   don’t have to write videoId
+      def playlist_item_params(video_id, params = {})
+        params.dup.tap do |params|
+          params[:resource_id] ||= {kind: 'youtube#video', videoId: video_id}
+        end
+      end
+    end
+  end
+end