yt-andrewroth 0.25.5.1

data/lib/yt/models/asset.rb

@@ -0,0 +1,111 @@
+require 'yt/models/base'
+require 'yt/models/asset_metadata'
+
+module Yt
+  module Models
+    # Provides methods to interact with YouTube ContentID assets.
+    # @see https://developers.google.com/youtube/partner/docs/v1/assets
+    class Asset < Base
+      attr_reader :auth
+
+      def initialize(options = {})
+        @data = options.fetch(:data, {})
+        @id = options[:id]
+        @auth = options[:auth]
+      end
+
+      def update(attributes = {})
+        underscore_keys! attributes
+        do_patch body: attributes
+        true
+      end
+
+      # @!attribute [r] ownership
+      #   @return [Yt::Models::Ownership] the asset’s ownership.
+      has_one :ownership
+      delegate :general_owners, :performance_owners, :synchronization_owners,
+        :mechanical_owners, to: :ownership
+
+      def metadata_mine
+        @metadata_mine ||= Yt::Models::AssetMetadata.new data: @data.fetch('metadataMine', {})
+      end
+
+      def metadata_effective
+        @metadata_effective ||= Yt::Models::AssetMetadata.new data: @data.fetch('metadataEffective', {})
+      end
+
+      # Soft-deletes the asset.
+      # @note YouTube API does not provide a +delete+ method for the Asset
+      #   resource, but only an +update+ method. Updating the +status+ of a
+      #   Asset to "inactive" can be considered a soft-deletion.
+      # @note Despite what the documentation says, YouTube API never returns
+      #   the status of an asset, so it’s impossible to update, although the
+      #   documentation says this should be the case. If YouTube ever fixes
+      #   the API, then the following code can be uncommented.
+      # @return [Boolean] whether the asset is inactive.
+      # def delete
+      #   body = {id: id, status: :inactive}
+      #   do_patch(body: body) {|data| @data = data}
+      #   inactive?
+      # end
+
+      # @return [String] the ID that YouTube assigns and uses to uniquely
+      #   identify the asset.
+      has_attribute :id
+
+      # Returns the asset’s type.
+      # @return [String] the asset’s type. This value determines the metadata
+      #   fields that you can set for the asset. In addition, certain API
+      #   functions may only be supported for specific types of assets. For
+      #   example, composition assets may have more complex ownership data than
+      #   other types of assets.
+      #   Possible values are: +'art_track_video'+, +'composition'+,
+      #   +'episode'+, +'general'+, +'movie'+, +'music_video'+, +'season'+,
+      #   +'show'+, +'sound_recording'+, +'video_game'+, +'web'+.
+      has_attribute :type
+
+      # @return [Array<Yt::Models::Tag>] the list of asset labels associated
+      #   with the asset. You can apply a label to multiple assets to group
+      #   them. You can use the labels as search filters to perform bulk updates,
+      #   to download reports, or to filter YouTube Analytics.
+      has_attribute :label
+
+# Status
+
+      # Returns the asset’s status.
+      # @return [String] the asset’s status. Possible values are: +'active'+,
+      #   +'inactive'+, +'pending'+.
+      # @note Despite what the documentation says, YouTube API never returns
+      #   the status of an asset, so it’s impossible to update, although the
+      #   documentation says this should be the case. If YouTube ever fixes
+      #   the API, then the following code can be uncommented.
+      # has_attribute :status
+      #
+      # # @return [Boolean] whether the asset is active.
+      # def active?
+      #   status == 'active'
+      # end
+      #
+      # # @return [Boolean] whether the asset is inactive.
+      # def inactive?
+      #   status == 'inactive'
+      # end
+      #
+      # # @return [Boolean] whether the asset is pending.
+      # def pending?
+      #   status == 'pending'
+      # end
+
+    private
+
+      # @see https://developers.google.com/youtube/partner/docs/v1/assets/patch
+      def patch_params
+        super.tap do |params|
+          params[:expected_response] = Net::HTTPOK
+          params[:path] = "/youtube/partner/v1/assets/#{@id}"
+          params[:params] = {on_behalf_of_content_owner: @auth.owner_name}
+        end
+      end
+    end
+  end
+end

data/lib/yt/models/asset_metadata.rb

@@ -0,0 +1,38 @@
+require 'yt/models/base'
+
+module Yt
+  module Models
+    # The AssetMetadata object specifies the metadata for an asset.
+    # @see https://developers.google.com/youtube/partner/docs/v1/assets#metadataMine
+    class AssetMetadata < Base
+      def initialize(options = {})
+        @data = options[:data]
+      end
+
+      # @return [String] A unique value that you, the metadata provider,
+      #   use to identify an asset. The value could be a unique ID that
+      #   you created for the asset or a standard identifier, such as an
+      #   ISRC.
+      def custom_id
+        @data['customId']
+      end
+
+      # @return [String] The asset's title or name.
+      def title
+        @data['title']
+      end
+
+      # @return [String] A description of the asset. The description may be
+      #   displayed on YouTube or in CMS. 
+      def notes
+        @data['notes']
+      end
+
+      # @return [String] the ID that YouTube assigns and uses to uniquely
+      #   identify the asset.
+      def description
+        @data['description']
+      end
+    end
+  end
+end

data/lib/yt/models/asset_snippet.rb

@@ -0,0 +1,46 @@
+require 'yt/models/base'
+
+module Yt
+  module Models
+    # Provides methods to interact with YouTube ContentID assetSnippets.
+    # @see https://developers.google.com/youtube/partner/docs/v1/assetSearch
+    class AssetSnippet < Base
+      attr_reader :auth
+
+      def initialize(options = {})
+        @data = options.fetch(:data, {})
+        @auth = options[:auth]
+      end
+
+      # @return [String] the ID that YouTube assigns and uses to uniquely
+      #   identify the asset.
+      has_attribute :id
+
+      # Returns the asset’s type.
+      # @return [String] the asset’s type. This value determines the metadata
+      #   fields that you can set for the asset. In addition, certain API
+      #   functions may only be supported for specific types of assets. For
+      #   example, composition assets may have more complex ownership data than
+      #   other types of assets.
+      #   Possible values are: +'art_track_video'+, +'composition'+,
+      #   +'episode'+, +'general'+, +'movie'+, +'music_video'+, +'season'+,
+      #   +'show'+, +'sound_recording'+, +'video_game'+, +'web'+.
+      has_attribute :type
+
+      # @return [String] the title of this asset.
+      has_attribute :title
+
+      # @return [String] the Custom ID assigned by the content owner to
+      #   this asset.
+      has_attribute :custom_id
+
+      # @return [String] the ISRC (International Standard Recording Code)
+      #   for this asset.
+      has_attribute :isrc
+
+      # @return [String] the ISWC (International Standard Musical Work Code)
+      #   for this asset.
+      has_attribute :iswc
+    end
+  end
+end

data/lib/yt/models/authentication.rb

@@ -0,0 +1,83 @@
+module Yt
+  module Models
+    # Provides methods to authenticate with YouTube (and Google) API.
+    # @see https://developers.google.com/accounts/docs/OAuth2
+    class Authentication
+
+      # Before your application can access private data using a Google API,
+      # it must obtain an access token that grants access to that API.
+      #
+      # A single access token can grant varying degrees of access to multiple
+      # APIs. A variable parameter called scope controls the set of resources
+      # and operations that an access token permits.
+      #
+      # After an application obtains an access token, it sends the token to a
+      # Google API in an HTTP authorization header.
+      #
+      # Access tokens are valid only for the set of operations and resources
+      # described in the scope of the token request. For example, if an access
+      # token is issued for the Google+ API, it does not grant access to the
+      # Google Contacts API.
+      #
+      # @return [String] the OAuth2 Google access token.
+      attr_reader :access_token
+
+      # Access tokens have limited lifetimes. If your application needs access
+      # to a Google API beyond the lifetime of a single access token, it can
+      # obtain a refresh token. A refresh token allows your application to
+      # obtain new access tokens.
+      #
+      # Save refresh tokens in secure long-term storage and continue to
+      # use them as long as they remain valid. Limits apply to the number of
+      # refresh tokens that are issued per client-user combination, and per
+      # user across all clients, and these limits are different. If your
+      # application requests enough refresh tokens to go over one of the
+      # limits, older refresh tokens stop working.
+      #
+      # There is currently a 25-token limit per Google user account.
+      # If a user account has 25 valid tokens, the next authentication request
+      # succeeds, but quietly invalidates the oldest outstanding token without
+      # any user-visible warning.
+      #
+      # @return [String] the OAuth2 Google refresh token.
+      attr_reader :refresh_token
+
+      # Access tokens have limited lifetimes. If your application needs access
+      # to a Google API beyond the lifetime of a single access token, it can
+      # obtain a refresh token.
+      #
+      # A refresh token allows your application to
+      # obtain new access tokens.
+      #
+      # @return [Time] the time when access token no longer works.
+      attr_reader :expires_at
+
+      def initialize(data = {})
+        @access_token = data['access_token']
+        @refresh_token = data['refresh_token']
+        @error = data['error']
+        @expires_at = expiration_date data.slice('expires_at', 'expires_in')
+      end
+
+      # @return [Boolean] whether the access token has expired.
+      def expired?
+        @expires_at && @expires_at.past?
+      end
+
+      # @return [Boolean] whether the device auth is pending
+      def pending?
+        @error == 'authorization_pending'
+      end
+
+    private
+
+      def expiration_date(options = {})
+        if options['expires_in']
+          Time.now + options['expires_in'].seconds
+        else
+          Time.parse options['expires_at'] rescue nil
+        end
+      end
+    end
+  end
+end

data/lib/yt/models/base.rb

@@ -0,0 +1,32 @@
+require 'yt/actions/delete'
+require 'yt/actions/update'
+require 'yt/actions/patch'
+
+require 'yt/associations/has_attribute'
+require 'yt/associations/has_authentication'
+require 'yt/associations/has_many'
+require 'yt/associations/has_one'
+require 'yt/associations/has_reports'
+
+require 'yt/errors/request_error'
+
+module Yt
+  module Models
+    # @private
+    class Base
+      include Actions::Delete
+      include Actions::Update
+      include Actions::Patch
+
+      include Associations::HasAttribute
+      extend Associations::HasReports
+      extend Associations::HasOne
+      extend Associations::HasMany
+      extend Associations::HasAuthentication
+    end
+  end
+
+  # By including Models in the main namespace, models can be initialized with
+  # the shorter notation Yt::Video.new, rather than Yt::Models::Video.new.
+  include Models
+end

data/lib/yt/models/channel.rb

@@ -0,0 +1,302 @@
+require 'yt/models/resource'
+
+module Yt
+  module Models
+    # Provides methods to interact with YouTube channels.
+    # @see https://developers.google.com/youtube/v3/docs/channels
+    class Channel < Resource
+
+    ### SNIPPET ###
+
+      # @!attribute [r] title
+      #   @return [String] the channel’s title.
+      delegate :title, to: :snippet
+
+      # @!attribute [r] description
+      #   @return [String] the channel’s description.
+      delegate :description, to: :snippet
+
+      # @!method thumbnail_url(size = :default)
+      #   Returns the URL of the channel’s thumbnail.
+      #   @param [Symbol, String] size The size of the channel’s thumbnail.
+      #   @return [String] if +size+ is +default+, the URL of a 88x88px image.
+      #   @return [String] if +size+ is +medium+, the URL of a 240x240px image.
+      #   @return [String] if +size+ is +high+, the URL of a 800x800px 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 channel was created.
+      delegate :published_at, to: :snippet
+
+    ### SUBSCRIPTION ###
+
+      has_one :subscription
+
+      # @return [Boolean] whether the account is subscribed to the channel.
+      # @raise [Yt::Errors::Unauthorized] if {Resource#auth auth} is not an
+      #   authenticated Yt::Account.
+      def subscribed?
+        sleep [(@subscriptions_updated_at || Time.now) - Time.now, 0].max
+        subscription.exists?
+      rescue Errors::NoItems
+        false
+      end
+
+      # Subscribes the authenticated account to the channel.
+      # Unlike {#subscribe!}, does not raise an error if already subscribed.
+      # @raise [Yt::Errors::Unauthorized] if {Resource#auth auth} is not an
+      #   authenticated Yt::Account.
+      def subscribe
+        subscriptions.insert(ignore_errors: true).tap do |subscription|
+          throttle_subscriptions
+          @subscription = subscription
+        end
+      end
+
+      # Subscribes the authenticated account to the channel.
+      # Unlike {#subscribe}, raises an error if already subscribed.
+      # @raise [Yt::Errors::RequestError] if already subscribed.
+      # @raise [Yt::Errors::Unauthorized] if {Resource#auth auth} is not an
+      #   authenticated Yt::Account.
+      def subscribe!
+        subscriptions.insert.tap do |subscription|
+          throttle_subscriptions
+          @subscription = subscription
+        end
+      end
+
+      # Unsubscribes the authenticated account from the channel.
+      # Unlike {#unsubscribe!}, does not raise an error if already unsubscribed.
+      # @raise [Yt::Errors::Unauthorized] if {Resource#auth auth} is not an
+      #   authenticated Yt::Account.
+      def unsubscribe
+        unsubscribe! if subscribed?
+      end
+
+      # Unsubscribes the authenticated account from the channel.
+      # Unlike {#unsubscribe}, raises an error if already unsubscribed.
+      #
+      # @raise [Yt::Errors::RequestError] if already unsubscribed.
+      # @raise [Yt::Errors::Unauthorized] if {Resource#auth auth} is not an
+      #   authenticated Yt::Account.
+      def unsubscribe!
+        subscription.delete.tap{ throttle_subscriptions }
+      end
+
+    ### ASSOCIATIONS ###
+
+      # @!attribute [r] videos
+      #   @return [Yt::Collections::Videos] the channel’s videos.
+      has_many :videos
+
+      # @!attribute [r] playlists
+      #   @return [Yt::Collections::Playlists] the channel’s playlists.
+      has_many :playlists
+
+      # @!attribute [r] related_playlists
+      #   @return [Yt::Collections::Playlists] the playlists associated with the
+      #     channel, such as the playlist of uploaded or liked videos.
+      #   @see https://developers.google.com/youtube/v3/docs/channels#contentDetails.relatedPlaylists
+      has_many :related_playlists
+
+      # @!attribute [r] subscribed_channels
+      #   @return [Yt::Collections::SubscribedChannels] the channels that this
+      #     channel is subscribed to.
+      #   @raise [Yt::Errors::Forbidden] if the owner of the channel has
+      #     explicitly select the option to keep all subscriptions private.
+      has_many :subscribed_channels
+
+    ### ANALYTICS ###
+
+      # @macro reports
+
+      # @macro report_by_channel_dimensions
+      has_report :views, Integer
+
+      # @macro report_by_day
+      has_report :uniques, Integer
+
+      # @macro report_by_channel_dimensions
+      has_report :estimated_minutes_watched, Integer
+
+      # @macro report_by_gender_and_age_group
+      has_report :viewer_percentage, Float
+
+      # @macro report_by_day_and_country
+      has_report :comments, Integer
+
+      # @macro report_by_day_and_country
+      has_report :likes, Integer
+
+      # @macro report_by_day_and_country
+      has_report :dislikes, Integer
+
+      # @macro report_by_day_and_country
+      has_report :shares, Integer
+
+      # @macro report_by_day_and_country
+      has_report :subscribers_gained, Integer
+
+      # @macro report_by_day_and_country
+      has_report :subscribers_lost, Integer
+
+      # @macro report_by_day_and_country
+      has_report :favorites_added, Integer
+
+      # @macro report_by_day_and_country
+      has_report :favorites_removed, Integer
+
+      # @macro report_by_day_and_state
+      has_report :average_view_duration, Integer
+
+      # @macro report_by_day_and_state
+      has_report :average_view_percentage, Float
+
+      # @macro report_by_day_and_state
+      has_report :annotation_clicks, Integer
+
+      # @macro report_by_day_and_state
+      has_report :annotation_click_through_rate, Float
+
+      # @macro report_by_day_and_state
+      has_report :annotation_close_rate, Float
+
+      # @macro report_by_day_and_country
+      has_report :earnings, Float
+
+      # @macro report_by_day_and_country
+      has_report :impressions, Integer
+
+      # @macro report_by_day_and_country
+      has_report :monetized_playbacks, Integer
+
+      # @macro report_by_day_and_country
+      has_report :playback_based_cpm, Float
+
+    ### STATISTICS ###
+
+      has_one :statistics_set
+
+      # @!attribute [r] view_count
+      #   @return [Integer] the number of times the channel has been viewed.
+      delegate :view_count, to: :statistics_set
+
+      # @!attribute [r] comment_count
+      #   @return [Integer] the number of comments for the channel.
+      delegate :comment_count, to: :statistics_set
+
+      # @!attribute [r] video_count
+      #   @return [Integer] the number of videos uploaded to the channel.
+      delegate :video_count, to: :statistics_set
+
+      # @!attribute [r] subscriber_count
+      #   @return [Integer] the number of subscriber the channel has.
+      delegate :subscriber_count, to: :statistics_set
+
+      # @return [Boolean] whether the number of subscribers is publicly visible.
+      def subscriber_count_visible?
+        statistics_set.hidden_subscriber_count == false
+      end
+
+    ### CONTENT OWNER DETAILS ###
+
+      has_one :content_owner_detail
+
+      # @!attribute [r] content_owner
+      #   The name of the content owner linked to the channel.
+      #   @return [String] if the channel is partnered, its content owner’s name.
+      #   @return [nil] if the channel is not partnered or 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.
+      delegate :content_owner, to: :content_owner_detail
+
+      # Returns the time the channel was partnered to a content owner.
+      # @return [Time] if the channel is partnered, the time when it was linked
+      #   to its content owner.
+      # @return [nil] if the channel is not partnered or 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.
+      def linked_at
+        content_owner_detail.time_linked
+      end
+
+    ### ACTIONS (UPLOAD, UPDATE, DELETE) ###
+
+      # Deletes the channel’s playlists matching all the given attributes.
+      # @return [Array<Boolean>] whether each playlist 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 channel.
+      # @param [Hash] attributes the attributes to match the playlists by.
+      # @option attributes [<String, Regexp>] :title The playlist’s title.
+      #   Pass a String for perfect match or a Regexp for advanced match.
+      # @option attributes [<String, Regexp>] :description The playlist’s
+      #   description. Pass a String (perfect match) or a Regexp (advanced).
+      # @option attributes [Array<String>] :tags The playlist’s tags.
+      #   All tags must match exactly.
+      # @option attributes [String] :privacy_status The playlist’s privacy
+      #   status.
+      def delete_playlists(attributes = {})
+        playlists.delete_all attributes
+      end
+
+    ### PRIVATE API ###
+
+      # @private
+      # Override Resource's new to set statistics as well
+      # if the response includes them
+      def initialize(options = {})
+        super options
+        if options[:statistics]
+          @statistics_set = StatisticsSet.new data: options[:statistics]
+        end
+        if options[:content_owner_details]
+          @content_owner_detail = ContentOwnerDetail.new data: options[:content_owner_details]
+        end
+      end
+
+      # @private
+      # Tells `has_many :videos` that channel.videos should return all the
+      # videos publicly available on the channel.
+      def videos_params
+        {channel_id: id}
+      end
+
+      # @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}"
+            params[:filters] = "channel==#{id}"
+          else
+            params[:ids] = "channel==#{id}"
+          end
+        end
+      end
+
+      # @private
+      # Tells `has_one :content_owner_detail` to retrieve the content owner
+      # detail as the Content Owner, it the channel was authorized with one.
+      # If it was not, the call will fail, since YouTube only allows content
+      # owners to check who is the content owner of a channel.
+      def content_owner_details_params
+        {on_behalf_of_content_owner: auth.owner_name || auth.id}
+      end
+
+      # @private
+      # @note Google API must have some caching layer by which if we try to
+      # delete a subscription that we just created, we encounter an error.
+      # To overcome this, if we have just updated the subscription, we must
+      # wait some time before requesting it again.
+      def throttle_subscriptions(seconds = 10)
+        @subscriptions_updated_at = Time.now + seconds
+      end
+    end
+  end
+end