Add support for Tailored Audience Permissions (#202)

* Add support for Tailored Audience Permissions

* bump version

examples/audience_permissions.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+# Copyright (C) 2019 Twitter, Inc.
+
+require 'digest'
+require 'twitter-ads'
+include TwitterAds::Enum
+
+CONSUMER_KEY        = 'your consumer key'
+CONSUMER_SECRET     = 'your consumer secret'
+ACCESS_TOKEN        = 'user access token'
+ACCESS_TOKEN_SECRET = 'user access token secret'
+ADS_ACCOUNT         = 'ads account id'
+
+# initialize the twitter ads api client
+client = TwitterAds::Client.new(
+  CONSUMER_KEY,
+  CONSUMER_SECRET,
+  ACCESS_TOKEN,
+  ACCESS_TOKEN_SECRET
+)
+
+# load up the account instance
+account = client.accounts(ADS_ACCOUNT)
+
+tailored_audience_id = '36n4f'
+
+# fetch all permissions
+permissions = TwitterAds::TailoredAudiencePermission.all(account, tailored_audience_id)
+
+permissions.each { |data|
+  p data.id
+  p data.permission_level
+  p data.granted_account_id
+}
+
+# create instance
+permission = TwitterAds::TailoredAudiencePermission.new(account)
+
+# set required params
+permission.tailored_audience_id = tailored_audience_id
+permission.granted_account_id = '18ce54uvbwu'
+permission.permission_level = PermissionLevel::READ_ONLY
+
+# set permission
+response = permission.save
+
+# delete permission
+permission.id = response.id
+permission.delete!

lib/twitter-ads/audiences/tailored_audience.rb

@@ -138,4 +138,99 @@ def users(params)
     end
 
   end
+
+  class TailoredAudiencePermission
+
+    include TwitterAds::DSL
+    include TwitterAds::Resource
+
+    attr_reader :account
+
+    # read-only
+    property :created_at, type: :time, read_only: true
+    property :updated_at, type: :time, read_only: true
+    property :deleted, type: :bool, read_only: true
+
+    property :id
+    property :tailored_audience_id
+    property :granted_account_id
+    property :permission_level
+
+    RESOURCE_COLLECTION  = "/#{TwitterAds::API_VERSION}/" \
+                           'accounts/%{account_id}/tailored_audiences/' \
+                           '%{tailored_audience_id}/permissions' # @api private
+    RESOURCE             = "/#{TwitterAds::API_VERSION}/" \
+                           'accounts/%{account_id}/tailored_audiences/' \
+                           '%{tailored_audience_id}/permissions/%{id}' # @api private
+
+    def initialize(account)
+      @account = account
+      self
+    end
+
+    class << self
+
+      # Retrieve details for some or
+      # all permissions associated with the specified tailored audience.
+      #
+      # @exapmle
+      #   permissions = TailoredAudiencePermission.all(account, '36n4f')
+      #
+      # @param account [Account] The account object instance.
+      # @param tailored_audience_id [String] The tailored audience id.
+      #
+      # @since 5.2.0
+      #
+      # @return [TailoredAudiencePermission] The tailored audience permission instance.
+      def all(account, tailored_audience_id, opts = {})
+        params = {}.merge!(opts)
+        resource = RESOURCE_COLLECTION % {
+          account_id: account.id,
+          tailored_audience_id: tailored_audience_id
+        }
+        request = Request.new(account.client, :get, resource, params: params)
+        Cursor.new(self, request, init_with: [account])
+      end
+
+    end
+
+    # Saves or updates the current object instance
+    # depending on the presence of `object.tailored_audience_id`.
+    #
+    # @exapmle
+    #   object.save
+    #
+    # @since 5.2.0
+    #
+    # @return [self] Returns the instance refreshed from the API.
+    def save
+      resource = RESOURCE_COLLECTION % {
+        account_id: account.id,
+        tailored_audience_id: tailored_audience_id
+      }
+      params = to_params
+      response = Request.new(account.client, :post, resource, params: params).perform
+      from_response(response.body[:data])
+    end
+
+    # Deletes the current or specified tailored audience permission.
+    #
+    # @example
+    #   object.delete!
+    #
+    # Note: calls to this method are destructive and irreverisble.
+    #
+    # @since 5.2.0
+    #
+    # @return [self] Returns the instance refreshed from the API.
+    def delete!
+      resource = RESOURCE % {
+        account_id: account.id,
+        tailored_audience_id: tailored_audience_id,
+        id: @id
+      }
+      response = Request.new(account.client, :delete, resource).perform
+      from_response(response.body[:data])
+    end
+  end
 end

lib/twitter-ads/version.rb

@@ -2,5 +2,5 @@
 # Copyright (C) 2019 Twitter, Inc.
 
 module TwitterAds
-  VERSION = '5.1.0'
+  VERSION = '5.2.0'
 end