Add content_owner.policies to list policies

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    yt (0.9.1)
+    yt (0.9.2)
       activesupport
 
 GEM

HISTORY.md

@@ -3,6 +3,7 @@ v0.9 - 2014/07/28
 
 * [breaking change] Rename rating.update to rating.set
 * Add content_owner.references to retrieve ContentID references
+* Add content_owner.policies to list ContentID policies
 
 
 v0.8 - 2014/07/18

README.md

@@ -41,7 +41,7 @@ To install on your system, run
 
 To use inside a bundled Ruby project, add this line to the Gemfile:
 
-    gem 'yt', '~> 0.9.1'
+    gem 'yt', '~> 0.9.2'
 
 Since the gem follows [Semantic Versioning](http://semver.org),
 indicating the full version in your Gemfile (~> *major*.*minor*.*patch*)
@@ -107,6 +107,7 @@ content_owner.claims.where(q: 'Fullscreen').count #=> 24
 content_owner.claims.first #=> #<Yt::Models::Claim @id=...>
 
 content_owner.references.where(asset_id: "ABCDEFG").first => #<Yt::Models::Reference @id=...>
+content_owner.policies.first => #<Yt::Models::Policy @id=...>
 ```
 
 *All the above methods require authentication (see below).*

lib/yt/collections/policies.rb

@@ -0,0 +1,37 @@
+require 'yt/collections/base'
+require 'yt/models/policy'
+
+module Yt
+  module Collections
+    # Provides methods to interact with a collection of Content ID policies.
+    #
+    # Resources with policies are: {Yt::Models::ContentOwner content owners}.
+    class Policies < Base
+
+    private
+
+      def new_item(data)
+        Yt::Policy.new data: data
+      end
+
+      # @return [Hash] the parameters to submit to YouTube to list policies
+      #   saved by the content owner.
+      # @see https://developers.google.com/youtube/partner/docs/v1/policies/list
+      def list_params
+
+        super.tap do |params|
+          params[:params] = policies_params
+          params[:path] = '/youtube/partner/v1/policies'
+        end
+      end
+
+      def policies_params
+        {onBehalfOfContentOwner: @parent.owner_name}.tap do |params|
+          (@extra_params ||= {}).each do |key, value|
+            params[key.to_s.camelize :lower] = value
+          end
+        end
+      end
+    end
+  end
+end

lib/yt/models/content_owner.rb

@@ -19,6 +19,10 @@ class ContentOwner < Account
       #   @return [Yt::Collection::References] the references administered by the content owner.
       has_many :references
 
+      # @!attribute [r] policies
+      #   @return [Yt::Collection::Policies] the policies saved by the content owner.
+      has_many :policies
+
       def initialize(options = {})
         super options
         @owner_name = options[:owner_name]

lib/yt/models/policy.rb

@@ -0,0 +1,44 @@
+require 'yt/models/base'
+require 'yt/models/policy_rule'
+
+module Yt
+  module Models
+    # Provides methods to interact with YouTube ContentID policies.
+    # A policy resource specifies rules that define a particular usage or
+    # match policy that a partner can associate with an asset or claim.
+    # @see https://developers.google.com/youtube/partner/docs/v1/policies
+    class Policy < Base
+      def initialize(options = {})
+        @data = options[:data]
+      end
+
+      # @return [String] the ID that YouTube assigns and uses to uniquely
+      #   identify the policy.
+      def id
+        @id ||= @data['id']
+      end
+
+      # @return [String] the policy’s name.
+      def name
+        @name ||= @data['name']
+      end
+
+      # @return [String] the policy’s description.
+      def description
+        @name ||= @data['description']
+      end
+
+      # @return [String] the time the policy was updated.
+      def time_updated
+        @time_updated ||= Time.parse @data['timeUpdated']
+      end
+
+      # @return [Array<PolicyRule>] a list of rules that specify the action
+      #   that YouTube should take and may optionally specify the conditions
+      #   under which that action is enforced.
+      def rules
+        @rules ||= @data['rules'].map{|rule| PolicyRule.new data: rule}
+      end
+    end
+  end
+end

lib/yt/models/policy_rule.rb

@@ -0,0 +1,133 @@
+require 'yt/models/base'
+
+module Yt
+  module Models
+    # Provides methods to interact with YouTube ContentID policy rules.
+    # Rules that specify the action that YouTube should take and may optionally
+    # specify the conditions under which that action is enforced.
+    # @see https://developers.google.com/youtube/partner/docs/v1/policies
+    class PolicyRule
+      def initialize(options = {})
+        @data = options[:data]
+      end
+
+      ACTIONS = %q(block monetize takedown track)
+
+      # Return the policy that YouTube should enforce if the rule’s conditions
+      # are all valid for an asset or for an attempt to view that asset on
+      # YouTube. Valid values for this property are: block, monetize, takedown,
+      # track.
+      # @return [String] the policy that YouTube should enforce.
+      def action
+        @action ||= @data['action']
+      end
+
+      # @return [Array] A list of additional actions that YouTube should take
+      #   if the conditions in the rule are met. Valid values for this property
+      #   are: review.
+      def subaction
+        @subaction ||= @data['subaction']
+      end
+
+      # Return the list of territories where the policy applies.
+      # Each territory is an ISO 3166 two-letter country code.
+      # YouTube determines whether the condition is satisfied based on the
+      # user’s location.
+      # @return [Array<String>] the territories where the policy applies.
+      # @example (with 'block' action) only block a video for U.S. users:
+      #   included_territories #=> ['us']
+      def included_territories
+        territories_type == 'include' ? territories : []
+      end
+
+      # Return the list of territories where the policy does not apply.
+      # Each territory is an ISO 3166 two-letter country code.
+      # YouTube determines whether the condition is satisfied based on the
+      # user’s location.
+      # @return [Array<String>] the territories where the policy does not apply.
+      # @example (with 'block' action) only allow U.S. users to view a video:
+      #   excluded_territories #=> ['us']
+      def excluded_territories
+        territories_type == 'exclude' ? territories : []
+      end
+
+      # @return [Array<Hash<Symbol, Float>>] the intervals of time the user-
+      #   or partner-uploaded content needs to match a reference file for the
+      #   rule to apply. :low is the minimum (inclusive) allowed value and
+      #   :high is the maximum (inclusive) allowed value for the rule to apply.
+      # @example videos that match the reference for 20 to 30 seconds:
+      #   match_duration #= [{low: 20.0, high: 30.0}]
+      def match_duration
+        @match_duration ||= match_duration_list.map{|r| low_and_high r}
+      end
+
+      # @return [Array<Hash<Symbol, Float>>] the intervals of percentages the
+      #   user- or partner-uploaded content needs to match a reference file for
+      #   the rule to apply. :low is the minimum (inclusive) allowed value and
+      #   :high is the maximum (inclusive) allowed value for the rule to apply.
+      # @example videos that match the reference for 40%~50% of their duration:
+      #   match_percent #= [{low: 40.0, high: 50.0}]
+      def match_percent
+        @match_percent ||= match_percent_list.map{|r| low_and_high r}
+      end
+
+      # @return [Array<Hash<Symbol, Float>>] the intervals of duration that the
+      #   reference must have for the rule to apply. :low is the minimum
+      #   (inclusive) allowed value, :high is the maximum (inclusive) allowed
+      #   value for the rule to apply.
+      # @example references that are between 20 and 30 seconds:
+      #   reference_duration #= [{low: 20.0, high: 30.0}]
+      def reference_duration
+        @reference_duration ||= reference_duration_list.map{|r| low_and_high r}
+      end
+
+      # @return [Array<Hash<Symbol, Float>>] the intervals of percentages the
+      #   reference file needs to match the user- or partner-uploaded content
+      #   for the rule to apply. :low is the minimum (inclusive) allowed value,
+      #   :high is the maximum (inclusive) allowed value for the rule to apply.
+      # @example videos that match either 0%~10% or 40%~50% of a reference:
+      #   reference_percent #= [{low: 0.0, high: 10.0}, {low: 40.0, high: 50.0}]
+      def reference_percent
+        @reference_percent ||= reference_percent_list.map{|r| low_and_high r}
+      end
+
+    private
+
+      def conditions
+        @conditions ||= @data.fetch 'conditions', {}
+      end
+
+      def territories_object
+        @territories_object ||= conditions.fetch 'requiredTerritories', {}
+      end
+
+      def territories_type
+        @territories_type ||= territories_object['type']
+      end
+
+      def territories
+        @territories ||= territories_object['territories']
+      end
+
+      def match_duration_list
+        @match_duration_list ||= conditions.fetch 'matchDuration', []
+      end
+
+      def match_percent_list
+        @match_percent_list ||= conditions.fetch 'matchPercent', []
+      end
+
+      def reference_duration_list
+        @reference_duration_list ||= conditions.fetch 'referenceDuration', []
+      end
+
+      def reference_percent_list
+        @reference_percent_list ||= conditions.fetch 'referencePercent', []
+      end
+
+      def low_and_high(range)
+        {low: range['low'], high: range['high']}
+      end
+    end
+  end
+end

lib/yt/version.rb

@@ -1,3 +1,3 @@
 module Yt
-  VERSION = '0.9.1'
+  VERSION = '0.9.2'
 end

spec/models/policy_rule_spec.rb

@@ -0,0 +1,63 @@
+require 'spec_helper'
+require 'yt/models/policy_rule'
+
+describe Yt::PolicyRule do
+  subject(:policy_rule) { Yt::PolicyRule.new data: data }
+
+  describe '#action' do
+    context 'given fetching a policy rule returns an action' do
+      let(:data) { {"action"=>"takedown"} }
+      it { expect(policy_rule.action).to eq 'takedown' }
+    end
+  end
+
+  describe '#subaction' do
+    context 'given fetching a policy rule returns a subaction' do
+      let(:data) { {"subaction"=>"review"} }
+      it { expect(policy_rule.subaction).to eq 'review' }
+    end
+  end
+
+  describe '#included_territories' do
+    context 'given fetching a policy rule returns included territories' do
+      let(:data) { {"conditions"=>{"requiredTerritories"=>{"type"=>"include", "territories"=>["US", "CA"]}}} }
+      let(:data) { {"conditions"=>{"requiredTerritories"=>{"type"=>"include", "territories"=>["US", "CA"]}}} }
+      it { expect(policy_rule.included_territories).to eq %w(US CA) }
+    end
+  end
+
+  describe '#excluded_territories' do
+    context 'given fetching a policy rule returns excluded territories' do
+      let(:data) { {"conditions"=>{"requiredTerritories"=>{"type"=>"exclude", "territories"=>["US", "CA"]}}} }
+      it { expect(policy_rule.excluded_territories).to eq %w(US CA) }
+    end
+  end
+
+  describe '#match_duration' do
+    context 'given fetching a policy rule returns a match duration list' do
+      let(:data) { {"conditions"=>{"matchDuration"=>[{"high"=>60.0}]}} }
+      it { expect(policy_rule.match_duration).to match_array [{low: nil, high: 60.0}] }
+    end
+  end
+
+  describe '#match_percent' do
+    context 'given fetching a policy rule returns a match percent list' do
+      let(:data) { {"conditions"=>{"matchPercent"=>[{"high"=>60.0}]}} }
+      it { expect(policy_rule.match_percent).to match_array [{low: nil, high: 60.0}] }
+    end
+  end
+
+  describe '#reference_duration' do
+    context 'given fetching a policy rule returns a reference duration list' do
+      let(:data) { {"conditions"=>{"referenceDuration"=>[{"low"=>60.0, "high"=>600.0}, {"low"=>20.0, "high"=>30.0}]}} }
+      it { expect(policy_rule.reference_duration).to match_array [{low: 60.0, high: 600.0}, {low: 20.0, high: 30.0}] }
+    end
+  end
+
+  describe '#reference_percent' do
+    context 'given fetching a policy rule returns a reference percent list' do
+      let(:data) { {"conditions"=>{"referencePercent"=>[{"low"=>60.0, "high"=>600.0}, {"low"=>20.0, "high"=>30.0}]}} }
+      it { expect(policy_rule.reference_percent).to match_array [{low: 60.0, high: 600.0}, {low: 20.0, high: 30.0}] }
+    end
+  end
+end

spec/models/policy_spec.rb

@@ -0,0 +1,41 @@
+require 'spec_helper'
+require 'yt/models/policy'
+
+describe Yt::Policy do
+  subject(:policy) { Yt::Policy.new data: data }
+
+  describe '#id' do
+    context 'given fetching a policy returns an id' do
+      let(:data) { {"id"=>"S123456789"} }
+      it { expect(policy.id).to eq 'S123456789' }
+    end
+  end
+
+  describe '#name' do
+    context 'given fetching a policy returns a name' do
+      let(:data) { {"name"=>"Block in all countries"} }
+      it { expect(policy.name).to eq 'Block in all countries' }
+    end
+  end
+
+  describe '#description' do
+    context 'given fetching a policy returns a description' do
+      let(:data) { {"description"=>"Block videos in every country"} }
+      it { expect(policy.description).to eq 'Block videos in every country' }
+    end
+  end
+
+  describe '#time_updated' do
+    context 'given fetching a policy returns a timeUpdated' do
+      let(:data) { {"timeUpdated"=>"1970-01-16T20:33:03.675Z"} }
+      it { expect(policy.time_updated.year).to be 1970 }
+    end
+  end
+
+  describe '#rules' do
+    context 'given fetching a policy returns rules' do
+      let(:data) { {"rules"=>[{"action"=>"track"},{"action"=>"track"}]} }
+      it { expect(policy.rules.size).to be 2 }
+    end
+  end
+end