twitter-ads 0.3.4

data/lib/twitter-ads/audiences/tailored_audience.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  class TailoredAudience
+
+    include TwitterAds::DSL
+    include TwitterAds::Resource
+
+    attr_reader :account
+
+    property :id, read_only: true
+    property :created_at, type: :time, read_only: true
+    property :updated_at, type: :time, read_only: true
+    property :deleted, type: :bool, read_only: true
+
+    property :name
+    property :list_type
+
+    property :audience_size, read_only: true
+    property :audience_type, read_only: true
+    property :metadata, read_only: true
+    property :partner_source, read_only: true
+    property :reasons_not_targetable, read_only: true
+    property :targetable, type: :bool, read_only: true
+    property :targetable_types, read_only: true
+
+    RESOURCE_COLLECTION = '/0/accounts/%{account_id}/tailored_audiences'.freeze # @api private
+    RESOURCE = '/0/accounts/%{account_id}/tailored_audiences/%{id}'.freeze # @api private
+    RESOURCE_UPDATE = '/0/accounts/%{account_id}/tailored_audience_changes'.freeze # @api private
+    GLOBAL_OPT_OUT =
+      '/0/accounts/%{account_id}/tailored_audiences/global_opt_out'.freeze # @api private
+
+    LIST_TYPES = %w(
+      EMAIL
+      DEVICE_ID
+      TWITTER_ID
+      HANDLE
+      PHONE_NUMBER
+    ).freeze
+
+    OPERATIONS = %w(
+      ADD
+      REMOVE
+      REPLACE
+    ).freeze
+
+    def initialize(account)
+      @account = account
+      self
+    end
+
+    class << self
+
+      # Creates a new tailored audience.
+      #
+      # @example
+      #   audience = TailoredAudience.create(account, '/path/to/file', 'my list', 'EMAIL')
+      #
+      # @param account [Account] The account object instance.
+      # @param file_path [String] The path to the file to be uploaded.
+      # @param name [String] The tailored audience name.
+      # @param list_type [String] The tailored audience list type.
+      #
+      # @since 0.3.0
+      #
+      # @return [TailoredAudience] The newly created tailored audience instance.
+      def create(account, file_path, name, list_type)
+        upload = TwitterAds::TONUpload.new(account.client, file_path)
+
+        audience = new(account)
+        audience.send(:create_audience, name, list_type)
+
+        begin
+          audience.send(:update_audience, audience, upload.perform, list_type, 'ADD')
+          audience.reload!
+        rescue TwitterAds::ClientError => e
+          audience.delete!
+          raise e
+        end
+      end
+
+      # Updates the global opt-out list for the specified advertiser account.
+      #
+      # @example
+      #   TailoredAudience.opt_out(account, '/path/to/file', 'EMAIL')
+      #
+      # @param account [Account] The account object instance.
+      # @param file_path [String] The path to the file to be uploaded.
+      # @param list_type [String] The tailored audience list type.
+      #
+      # @since 0.3.0
+      #
+      # @return [Boolean] The result of the opt-out update.
+      def opt_out(account, file_path, list_type)
+        upload   = TwitterAds::TONUpload.new(account.client, file_path)
+        params   = { input_file_path: upload.perform, list_type: list_type }
+        resource = GLOBAL_OPT_OUT % { account_id: account.id }
+        Request.new(account.client, :put, resource, params: params).perform
+        true
+      end
+
+    end
+
+    # Updates the current tailored audience instance.
+    #
+    # @example
+    #   audience = account.tailored_audiences('xyz')
+    #   audience.update('/path/to/file', 'EMAIL', 'REPLACE')
+    #
+    # @param file_path [String] The path to the file to be uploaded.
+    # @param list_type [String] The tailored audience list type.
+    # @param operation [String] The update operation type (Default: 'ADD').
+    #
+    # @since 0.3.0
+    #
+    # @return [TailoredAudience] [description]
+    def update(file_path, list_type, operation = 'ADD')
+      upload = TwitterAds::TONUpload.new(account.client, file_path)
+      update_audience(self, upload.perform, list_type, operation)
+      reload!
+    end
+
+    # Deletes the current tailored audience instance.
+    #
+    # @example
+    #   audience.delete!
+    #
+    # Note: calls to this method are destructive and irreverisble.
+    #
+    # @since 0.3.0
+    #
+    # @return [self] Returns the tailored audience instance refreshed from the API.
+    def delete!
+      resource = RESOURCE % { account_id: account.id, id: id }
+      response = Request.new(account.client, :delete, resource).perform
+      from_response(response.body[:data])
+    end
+
+    # Returns the status of all changes for the current tailored audience instance.
+    #
+    # @example
+    #   audience.status
+    #
+    # @since 0.3.0
+    #
+    # @return [Hash] Returns a hash object representing the tailored audience status.
+    def status
+      return nil unless id
+      resource = RESOURCE_UPDATE % { account_id: account.id }
+      request = Request.new(account.client, :get, resource, params: to_params)
+      Cursor.new(nil, request).to_a.select { |change| change[:tailored_audience_id] == id }
+    end
+
+    private
+
+    def create_audience(name, list_type)
+      params = { name: name, list_type: list_type }
+      resource = RESOURCE_COLLECTION % { account_id: account.id }
+      response = Request.new(account.client, :post, resource, params: params).perform
+      from_response(response.body[:data])
+    end
+
+    def update_audience(audience, location, list_type, operation)
+      params = {
+        tailored_audience_id: audience.id,
+        input_file_path: location,
+        list_type: list_type,
+        operation: operation
+      }
+
+      resource = RESOURCE_UPDATE % { account_id: audience.account.id }
+      Request.new(audience.account.client, :post, resource, params: params).perform
+    end
+
+  end
+end

data/lib/twitter-ads/campaign/app_list.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  class AppList
+
+    include TwitterAds::DSL
+    include TwitterAds::Resource
+
+    attr_reader :account
+
+    property :id, read_only: true
+    property :apps, read_only: true
+    property :name, read_only: true
+
+    RESOURCE_COLLECTION = '/0/accounts/%{account_id}/app_lists'.freeze # @api private
+    RESOURCE            = '/0/accounts/%{account_id}/app_lists/%{id}'.freeze # @api private
+
+    def initialize(account)
+      @account = account
+      self
+    end
+
+    # Creates a new App List
+    #
+    # @param name [String] The name for the app list to be created.
+    # @param ids [String] String or String Array of app IDs.
+    #
+    # @return [self] Returns the instance refreshed from the API
+    def create(name, *ids)
+      resource = self.class::RESOURCE_COLLECTION % { account_id: account.id }
+      params = to_params.merge!(app_store_identifiers: ids.join(','), name: name)
+      response = Request.new(account.client, :post, resource, params: params).perform
+      from_response(response.body[:data])
+    end
+
+    def apps
+      reload! if @id && !@apps
+      @apps
+    end
+  end
+end

data/lib/twitter-ads/campaign/campaign.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  class Campaign
+
+    include TwitterAds::DSL
+    include TwitterAds::Resource
+    include TwitterAds::Persistence
+
+    attr_reader :account
+
+    property :id, read_only: true
+    property :reasons_not_servable, read_only: true
+    property :servable, read_only: true
+    property :deleted, type: :bool, read_only: true
+    property :created_at, type: :time, read_only: true
+    property :updated_at, type: :time, read_only: true
+
+    property :name
+    property :funding_instrument_id
+    property :end_time, type: :time
+    property :start_time, type: :time
+    property :paused, type: :bool
+    property :currency
+    property :standard_delivery
+    property :daily_budget_amount_local_micro
+    property :total_budget_amount_local_micro
+
+    RESOURCE_COLLECTION = '/0/accounts/%{account_id}/campaigns'.freeze # @api private
+    RESOURCE_STATS      = '/0/stats/accounts/%{account_id}/campaigns'.freeze # @api private
+    RESOURCE            = '/0/accounts/%{account_id}/campaigns/%{id}'.freeze # @api private
+
+    def initialize(account)
+      @account = account
+      self
+    end
+
+  end
+end

data/lib/twitter-ads/campaign/funding_instrument.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  class FundingInstrument
+
+    include TwitterAds::DSL
+    include TwitterAds::Resource
+
+    attr_reader :account
+
+    property :id, read_only: true
+    property :name, read_only: true
+    property :cancelled, read_only: true
+    property :credit_limit_local_micro, read_only: true
+    property :currency, read_only: true
+    property :description, read_only: true
+    property :funded_amount_local_micro, read_only: true
+    property :type, read_only: true
+    property :created_at, type: :time, read_only: true
+    property :updated_at, type: :time, read_only: true
+    property :deleted, type: :bool, read_only: true
+
+    RESOURCE_COLLECTION = '/0/accounts/%{account_id}/funding_instruments'.freeze # @api private
+    RESOURCE = '/0/accounts/%{account_id}/funding_instruments/%{id}'.freeze # @api private
+
+    def initialize(account)
+      @account = account
+      self
+    end
+
+  end
+end

data/lib/twitter-ads/campaign/line_item.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  class LineItem
+
+    include TwitterAds::DSL
+    include TwitterAds::Resource
+    include TwitterAds::Persistence
+    include TwitterAds::Analytics
+
+    attr_reader :account
+
+    property :id, read_only: true
+    property :deleted, type: :bool, read_only: true
+    property :created_at, type: :time, read_only: true
+    property :updated_at, type: :time, read_only: true
+
+    property :name
+    property :campaign_id
+    property :advertiser_domain
+    property :categories
+    property :charge_by
+    property :include_sentiment
+    property :objective
+    property :optimization
+    property :paused, type: :bool
+    property :primary_web_event_tag
+    property :product_type
+    property :placements
+    property :bid_unit
+    property :automatically_select_bid
+    property :bid_amount_local_micro
+    property :total_budget_amount_local_micro
+
+    RESOURCE_COLLECTION = '/0/accounts/%{account_id}/line_items'.freeze # @api private
+    RESOURCE_STATS      = '/0/stats/accounts/%{account_id}/line_items'.freeze # @api private
+    RESOURCE            = '/0/accounts/%{account_id}/line_items/%{id}'.freeze # @api private
+
+    def initialize(account)
+      @account = account
+      self
+    end
+
+    # Overload for CUSTOM objective deprecation warning.
+    # @private
+    def objective=(value)
+      if value == TwitterAds::Objective::CUSTOM
+        TwitterAds::Utils.deprecated('TwitterAds::Objective::CUSTOM')
+      end
+      @objective = value
+    end
+
+    class << self
+
+      # Helper method to return a list a valid placement combinations by Product.
+      #
+      # @example
+      #   LineItem.placements(Product::PROMOTED_TWEETS)
+      #
+      # @param product_type [Product] The enum value for the Product type being targeted.
+      #
+      # @return [Array] An array of valid placement combinations.
+      #
+      # @since 0.3.2
+      # @see https://dev.twitter.com/ads/reference/get/line_items/placements
+      def placements(client, product_type = nil)
+        resource = '/0/line_items/placements'
+        params   = { product_type: product_type } if product_type
+        response = TwitterAds::Request.new(client, :get, resource, params: params).perform
+        response.body[:data][0][:placements]
+      end
+
+    end
+
+    # Returns a collection of targeting criteria available to the current line item.
+    #
+    # @param id [String] The TargetingCriteria ID value.
+    # @param opts [Hash] A Hash of extended options.
+    # @option opts [Boolean] :with_deleted Indicates if deleted items should be included.
+    # @option opts [String] :sort_by The object param to sort the API response by.
+    #
+    # @since 0.3.1
+    #
+    # @return A Cursor or object instance.
+    def targeting_criteria(id = nil, opts = {})
+      id ? TargetingCriteria.load(account, id, opts) : TargetingCriteria.all(account, @id, opts)
+    end
+
+  end
+end

data/lib/twitter-ads/campaign/promotable_user.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  class PromotableUser
+
+    include TwitterAds::DSL
+    include TwitterAds::Resource
+
+    attr_reader :account
+
+    property :id, read_only: true
+    property :promotable_user_type, read_only: true
+    property :user_id, read_only: true
+    property :created_at, type: :time, read_only: true
+    property :updated_at, type: :time, read_only: true
+    property :deleted, type: :bool, read_only: true
+
+    RESOURCE_COLLECTION = '/0/accounts/%{account_id}/promotable_users'.freeze # @api private
+    RESOURCE            = '/0/accounts/%{account_id}/promotable_users/%{id}'.freeze # @api private
+
+    def initialize(account)
+      @account = account
+      self
+    end
+
+  end
+end

data/lib/twitter-ads/campaign/targeting_criteria.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  class TargetingCriteria
+
+    include TwitterAds::DSL
+    include TwitterAds::Persistence
+    include TwitterAds::Resource::InstanceMethods
+
+    attr_reader :account
+
+    property :id, read_only: true
+    property :name, read_only: true
+    property :localized_name, read_only: true
+    property :created_at, type: :time, read_only: true
+    property :updated_at, type: :time, read_only: true
+    property :deleted, type: :bool, read_only: true
+
+    property :line_item_id
+    property :targeting_type
+    property :targeting_value
+    property :tailored_audience_expansion, type: :bool
+    property :tailored_audience_type
+
+    RESOURCE_COLLECTION = '/0/accounts/%{account_id}/targeting_criteria'.freeze # @api private
+    RESOURCE            = '/0/accounts/%{account_id}/targeting_criteria/%{id}'.freeze # @api private
+
+    def initialize(account)
+      @account = account
+      self
+    end
+
+    class << self
+
+      # Returns a Cursor instance for a given resource.
+      #
+      # @param account [Account] The Account object instance.
+      # @param line_item_id [String] The line item ID string.
+      # @param opts [Hash] An optional Hash of extended options.
+      # @option opts [Boolean] :with_deleted Indicates if deleted items should be included.
+      # @option opts [String] :sort_by The object param to sort the API response by.
+      #
+      # @return [Cursor] A Cusor object ready to iterate through the API response.
+      #
+      # @since 0.3.1
+      # @see Cursor
+      # @see https://dev.twitter.com/ads/basics/sorting Sorting
+      def all(account, line_item_id, opts = {})
+        params = { line_item_id: line_item_id }.merge!(opts)
+        resource = RESOURCE_COLLECTION % { account_id: account.id }
+        request = Request.new(account.client, :get, resource, params: params)
+        Cursor.new(self, request, init_with: [account])
+      end
+
+      # Returns an object instance for a given resource.
+      #
+      # @param account [Account] The Account object instance.
+      # @param id [String] The ID of the specific object to be loaded.
+      # @param opts [Hash] An optional Hash of extended options.
+      # @option opts [Boolean] :with_deleted Indicates if deleted items should be included.
+      # @option opts [String] :sort_by The object param to sort the API response by.
+      #
+      # @return [self] The object instance for the specified resource.
+      #
+      # @since 0.3.1
+      def load(account, id, opts = {})
+        params   = { with_deleted: true }.merge!(opts)
+        resource = RESOURCE % { account_id: account.id, id: id }
+        response = Request.new(account.client, :get, resource, params: params).perform
+        new(account).from_response(response.body[:data])
+      end
+
+    end
+
+  end
+end