twitter-ads 5.1.0 → 7.0.1

data/lib/twitter-ads/error.rb

@@ -59,18 +59,7 @@ module TwitterAds
 
   # Server Errors (5XX)
   class ServerError < Error; end
-
-  class ServiceUnavailable < ServerError
-    attr_reader :retry_after
-
-    def initialize(object)
-      super object
-      if object.headers['retry-after']
-        @retry_after = object.headers['retry-after']
-      end
-      self
-    end
-  end
+  class ServiceUnavailable < ServerError; end
 
   # Client Errors (4XX)
   class ClientError < Error; end
@@ -80,12 +69,13 @@ module TwitterAds
   class BadRequest < ClientError; end
 
   class RateLimit < ClientError
-    attr_reader :reset_at, :retry_after
+    attr_reader :reset_at
 
     def initialize(object)
       super object
-      @retry_after = object.headers['retry-after']
-      @reset_at = object.headers['rate_limit_reset']
+      header = object.headers.fetch('x-account-rate-limit-reset', nil) ||
+               object.headers.fetch('x-rate-limit-reset', nil)
+      @reset_at = header.first.to_i
       self
     end
   end

data/lib/twitter-ads/http/request.rb

@@ -71,18 +71,53 @@ module TwitterAds
       token    = OAuth::AccessToken.new(consumer, @client.access_token, @client.access_token_secret)
       request.oauth!(consumer.http, consumer, token)
 
+      handle_rate_limit = @client.options.fetch(:handle_rate_limit, false)
+      retry_max         = @client.options.fetch(:retry_max, 0)
+      retry_delay       = @client.options.fetch(:retry_delay, 1500)
+      retry_on_status   = @client.options.fetch(:retry_on_status, [500, 503])
+      retry_count       = 0
+      retry_after       = nil
+
       write_log(request) if @client.options[:trace]
-      response = consumer.http.request(request)
+      while retry_count <= retry_max
+        response = consumer.http.request(request)
+        status_code = response.code.to_i
+        break if status_code >= 200 && status_code < 300
+
+        if handle_rate_limit && retry_after.nil?
+          rate_limit_reset = response.fetch('x-account-rate-limit-reset', nil) ||
+                             response.fetch('x-rate-limit-reset', nil)
+          if status_code == 429
+            retry_after = rate_limit_reset.to_i - Time.now.to_i
+            @client.logger.warn('Request reached Rate Limit: resume in %d seconds' % retry_after)
+            sleep(retry_after + 5)
+            next
+          end
+        end
+
+        if retry_max.positive?
+          break unless retry_on_status.include?(status_code)
+          sleep(retry_delay / 1000)
+        end
+
+        retry_count += 1
+      end
       write_log(response) if @client.options[:trace]
 
       Response.new(response.code, response.each {}, response.body)
     end
 
+    def escape_params(input)
+      input.map do |key, value|
+        "#{CGI.escape key.to_s}=#{CGI.escape value.to_s}"
+      end.join('&')
+    end
+
     def http_request
       request_url = @resource
 
       if @options[:params] && !@options[:params].empty?
-        request_url += "?#{URI.encode_www_form(@options[:params])}"
+        request_url += "?#{escape_params(@options[:params])}"
       end
 
       request      = HTTP_METHOD[@method].new(request_url)

data/lib/twitter-ads/http/response.rb

@@ -9,9 +9,7 @@ module TwitterAds
     attr_reader :code,
                 :headers,
                 :raw_body,
-                :body,
-                :rate_limit_remaining,
-                :rate_limit_reset
+                :body
 
     # Creates a new Response object instance.
     #
@@ -37,16 +35,6 @@ module TwitterAds
         @body = raw_body
       end
 
-      if headers.key?('x-rate-limit-reset')
-        @rate_limit           = headers['x-rate-limit-limit'].first
-        @rate_limit_remaining = headers['x-rate-limit-remaining'].first
-        @rate_limit_reset     = headers['x-rate-limit-reset'].first.to_i
-      elsif headers.key?('x-cost-rate-limit-reset')
-        @rate_limit           = headers['x-cost-rate-limit-limit'].first
-        @rate_limit_remaining = headers['x-cost-rate-limit-remaining'].first
-        @rate_limit_reset     = Time.at(headers['x-cost-rate-limit-reset'].first.to_i)
-      end
-
       self
     end
 

data/lib/twitter-ads/resources/analytics.rb

@@ -5,15 +5,35 @@ require 'zlib'
 require 'open-uri'
 
 module TwitterAds
-  module Analytics
+  class Analytics
 
+    include TwitterAds::DSL
+    include TwitterAds::Resource
     include TwitterAds::Enum
 
+    attr_reader :account
+
+    property :id, read_only: true
+    property :id_str, read_only: true
+    property :status, read_only: true
+    property :url, read_only: true
+    property :created_at, type: :time, read_only: true
+    property :expires_at, type: :time, read_only: true
+    property :updated_at, type: :time, read_only: true
+    property :start_time, type: :time, read_only: true
+    property :end_time, type: :time, read_only: true
+
+    property :entity, read_only: true
+    property :entity_ids, read_only: true
+    property :placement, read_only: true
+    property :granularity, read_only: true
+    property :metric_groups, read_only: true
+
     ANALYTICS_MAP = {
       'TwitterAds::Campaign' => Entity::CAMPAIGN,
       'TwitterAds::LineItem' => Entity::LINE_ITEM,
       'TwitterAds::OrganicTweet' => Entity::ORGANIC_TWEET,
-      'TwitterAds::Creative::PromotedAccount' => Entity::ACCOUNT,
+      'TwitterAds::Creative::PromotedAccount' => Entity::PROMOTED_ACCOUNT,
       'TwitterAds::Creative::PromotedTweet' => Entity::PROMOTED_TWEET,
       'TwitterAds::Creative::MediaCreative' => Entity::MEDIA_CREATIVE
     }.freeze
@@ -25,42 +45,38 @@ module TwitterAds
     RESOURCE_ACTIVE_ENTITIES  = "/#{TwitterAds::API_VERSION}/" +
                                 'stats/accounts/%{account_id}/active_entities' # @api private
 
-    def self.included(klass)
-      klass.send :include, InstanceMethods
-      klass.extend ClassMethods
+    def initialize(account)
+      @account = account
+      self
     end
 
-    module InstanceMethods
-
-      # Pulls a list of metrics for the current object instance.
-      #
-      # @example
-      #   metric_groups = [:promoted_tweet_timeline_clicks, :promoted_tweet_search_clicks]
-      #   object.stats(metrics)
-      #
-      # @param metric_groups [Array] A collection of metric groups to fetch.
-      # @param opts [Hash] An optional Hash of extended options.
-      # @option opts [Time] :start_time The starting time to use (default: 7 days ago).
-      # @option opts [Time] :end_time The end time to use (default: now).
-      # @option opts [Symbol] :granularity The granularity to use (default: :hour).
-      #
-      # @return [Array] The collection of stats requested.
-      #
-      # @see https://dev.twitter.com/ads/analytics/metrics-and-segmentation
-      # @since 1.0.0
-      def stats(metric_groups, opts = {})
-        self.class.stats(account, [id], metric_groups, opts)
-      end
-
+    # Pulls a list of metrics for the current object instance.
+    #
+    # @example
+    #   metric_groups = [MetricGroup::MOBILE_CONVERSION, MetricGroup::ENGAGEMENT]
+    #   object.stats(metrics)
+    #
+    # @param metric_groups [Array] A collection of metric groups to fetch.
+    # @param opts [Hash] An optional Hash of extended options.
+    # @option opts [Time] :start_time The starting time to use (default: 7 days ago).
+    # @option opts [Time] :end_time The end time to use (default: now).
+    # @option opts [Symbol] :granularity The granularity to use (default: :hour).
+    #
+    # @return [Array] The collection of stats requested.
+    #
+    # @see https://dev.twitter.com/ads/analytics/metrics-and-segmentation
+    # @since 1.0.0
+    def stats(metric_groups, opts = {})
+      self.class.stats(account, [id], metric_groups, opts)
     end
 
-    module ClassMethods
+    class << self
 
       # Pulls a list of metrics for a specified set of object IDs.
       #
       # @example
       #   ids = ['7o4em', 'oc9ce', '1c5lji']
-      #   metric_groups = [MetricGroups.MOBILE_CONVERSION, MetricGroups.ENGAGEMENT]
+      #   metric_groups = [MetricGroup::MOBILE_CONVERSION, MetricGroup::ENGAGEMENT]
       #   object.stats(account, ids, metric_groups)
       #
       # @param account [Account] The Account object instance.
@@ -70,7 +86,7 @@ module TwitterAds
       # @option opts [Time] :start_time The starting time to use (default: 7 days ago).
       # @option opts [Time] :end_time The end time to use (default: now).
       # @option opts [Symbol] :granularity The granularity to use (default: :hour).
-      # @option opts [Symbol] :placement The placement of entity (default: ALL_ON_TWITTER).
+      # @option opts [String] :placement The placement of entity (default: ALL_ON_TWITTER).
       #
       # @return [Array] The collection of stats requested.
       #
@@ -108,7 +124,7 @@ module TwitterAds
       #
       # @example
       #   ids = ['7o4em', 'oc9ce', '1c5lji']
-      #   metric_groups = [MetricGroups.MOBILE_CONVERSION, MetricGroups.ENGAGEMENT]
+      #   metric_groups = [MetricGroup::MOBILE_CONVERSION, MetricGroup::ENGAGEMENT]
       #   object.create_async_job(account, ids, metric_groups)
       #
       # @param account [Account] The Account object instance.
@@ -118,16 +134,17 @@ module TwitterAds
       # @option opts [Time] :start_time The starting time to use (default: 7 days ago).
       # @option opts [Time] :end_time The end time to use (default: now).
       # @option opts [Symbol] :granularity The granularity to use (default: :hour).
-      # @option opts [Symbol] :placement The placement of entity (default: ALL_ON_TWITTER).
-      # @option opts [Symbol] :segmentation_type The segmentation type to use (default: none).
+      # @option opts [String] :placement The placement of entity (default: ALL_ON_TWITTER).
+      # @option opts [String] :segmentation_type The segmentation type to use (default: none).
       #
       # @return The response of creating job
       #
       # @see https://dev.twitter.com/ads/analytics/metrics-and-segmentation
-      # @sync 1.0.0
+      # @since 1.0.0
 
       def create_async_job(account, ids, metric_groups, opts = {})
         # set default metric values
+        entity            = opts.fetch(:entity, name)
         end_time          = opts.fetch(:end_time, (Time.now - Time.now.sec - (60 * Time.now.min)))
         start_time        = opts.fetch(:start_time, end_time - 604_800) # 7 days ago
         granularity       = opts.fetch(:granularity, :hour)
@@ -143,7 +160,7 @@ module TwitterAds
           start_time: TwitterAds::Utils.to_time(start_time, granularity, start_utc_offset),
           end_time: TwitterAds::Utils.to_time(end_time, granularity, end_utc_offset),
           granularity: granularity.to_s.upcase,
-          entity: ANALYTICS_MAP[name],
+          entity: ANALYTICS_MAP[entity],
           placement: placement,
           country: country,
           platform: platform
@@ -153,19 +170,18 @@ module TwitterAds
         params['entity_ids'] = ids.join(',')
 
         resource = self::RESOURCE_ASYNC_STATS % { account_id: account.id }
-        puts 'my resource is ' + resource
         response = Request.new(account.client, :post, resource, params: params).perform
-        response.body[:data]
+        TwitterAds::Analytics.new(account).from_response(response.body[:data], response.headers)
       end
 
       # Check async job status.
       # GET /#{TwitterAds::API_VERSION}/stats/jobs/accounts/:account_id
       #
       # @example
-      #   TwitterAds::LineItem.check_async_job_status(account, job_id: '1357343438724431305')
+      #   TwitterAds::LineItem.check_async_job_status(account, job_ids: ['1357343438724431305'])
       #
       # @param account [Account] The Account object instance.
-      # @option opts [String] :job_id The starting time to use (default: 7 days ago).
+      # @option opts [Array] :job_ids A collection of job IDs to fetch.
       #
       # @return A cursor of job statuses
 
@@ -173,18 +189,18 @@ module TwitterAds
         # set default values
         job_ids = opts.fetch(:job_ids, nil)
         params = {}
-        params[:job_ids] = Array.wrap(job_ids).join(',') if job_ids
+        params[:job_ids] = job_ids.join(',') if job_ids
 
         resource = self::RESOURCE_ASYNC_STATS % { account_id: account.id }
         request = Request.new(account.client, :get, resource, params: params)
-        Cursor.new(nil, request, init_with: [account])
+        Cursor.new(TwitterAds::Analytics, request, init_with: [account])
       end
 
       # Fetch async job data for a completed job.
       # Raises HTTP 404 exception, otherwise retries up to 5 times with exponential backoff.
       #
       # @example
-      #   response_data = TwitterAds::LineItem.fetch_async_job_data(account, file_url)
+      #   response_data = TwitterAds::LineItem.fetch_async_job_data(account, data_url)
       #
       # @param data_url [String] The URL from the successful completion of an async job.
       #
@@ -209,21 +225,57 @@ module TwitterAds
         end
       end
 
+      # Retrieve details about which entities' analytics metrics
+      # have changed in a given time period.
+      #
+      # @example
+      #   time = Time.now
+      #   utc_offset = '+09:00'
+      #   start_time = time - (60 * 60 * 24) # -1 day
+      #   end_time = time
+      #   active_entities = TwitterAds::LineItem.active_entities(
+      #     account,
+      #     line_item_ids: %w(exrfs),
+      #     start_time: start_time,
+      #     end_time:   end_time,
+      #     utc_offset: utc_offset,
+      #     granularity: :day)
+      #
+      # @param account [Account] The Account object instance.
+      # @param entity [String] The entity type to retrieve data for.
+      # @param start_time [Time] Scopes the retrieved data to the specified start time.
+      # @param end_time [Time] Scopes the retrieved data to the specified end time.
+      # @option opts [Array] :campaign_ids A collection of IDs to be fetched.
+      # @option opts [Array] :funding_instrument_ids A collection of IDs to be fetched.
+      # @option opts [Array] :line_item_ids A collection of IDs to be fetched.
+      #
+      # @return A list of entity details.
+      #
+      # @see https://developer.twitter.com/en/docs/ads/analytics/api-reference/active-entities
+
       def active_entities(account, start_time:, end_time:, **opts)
-        entity_type = name
+        entity            = opts.fetch(:entity, name)
         granularity       = opts.fetch(:granularity, nil)
         start_utc_offset  = opts[:start_utc_offset] || opts[:utc_offset]
         end_utc_offset    = opts[:end_utc_offset] || opts[:utc_offset]
 
-        if entity_type == 'OrganicTweet'
-          raise "'OrganicTweet' not support with 'active_entities'"
+        if entity == 'OrganicTweet'
+          raise "'OrganicTweet' is not supported with 'active_entities'"
         end
 
         params = {
-          entity: ANALYTICS_MAP[entity_type],
+          entity: ANALYTICS_MAP[entity],
           start_time: TwitterAds::Utils.to_time(start_time, granularity, start_utc_offset),
           end_time: TwitterAds::Utils.to_time(end_time, granularity, end_utc_offset)
-        }.merge!(opts)
+        }
+
+        opts.each { |k, v|
+          params[k] = if v.instance_of?(Array)
+                        v.join(',')
+                      else
+                        v
+                      end
+        }
 
         resource = self::RESOURCE_ACTIVE_ENTITIES % { account_id: account.id }
         response = Request.new(account.client, :get, resource, params: params).perform

data/lib/twitter-ads/resources/dsl.rb

@@ -20,7 +20,14 @@ module TwitterAds
       # @return [self] A fully hydrated instance of the current class.
       #
       # @since 0.1.0
-      def from_response(object)
+      def from_response(object, headers = nil)
+        if !headers.nil?
+          TwitterAds::Utils.extract_response_headers(headers).each { |key, value|
+            singleton_class.class_eval { attr_accessor key }
+            instance_variable_set("@#{key}", value)
+          }
+        end
+
         self.class.properties.each do |name, type|
           value = nil
           if type == :time && object[name] && !object[name].empty?

data/lib/twitter-ads/restapi.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+# Copyright (C) 2019 Twitter, Inc.
+
+module TwitterRestApi
+  class UserIdLookup
+    include TwitterAds::DSL
+    include TwitterAds::Resource
+
+    attr_reader :account
+
+    property :id, read_only: true
+    property :id_str, read_only: true
+    property :screen_name, read_only: true
+
+    DOMAIN = 'https://api.twitter.com'
+    RESOURCE = '/1.1/users/show.json'
+
+    def self.load(account, opts = {})
+      response = TwitterAds::Request.new(
+        account.client,
+        :get,
+        RESOURCE,
+        params: opts,
+        domain: DOMAIN
+      ).perform
+      new.from_response(response.body, response.headers)
+    end
+  end
+end

data/lib/twitter-ads/settings/tax.rb

@@ -41,12 +41,24 @@ module TwitterAds
     property :to_delete, type: :bool
 
     RESOURCE = "/#{TwitterAds::API_VERSION}/" \
-               'accounts/%{account_id}/user_settings/%{id}' # @api private
+               'accounts/%{account_id}/tax_settings' # @api private
 
     def initialize(account)
       @account = account
       self
     end
 
+    def self.load(account)
+      resource = RESOURCE % { account_id: account.id }
+      response = Request.new(account.client, :get, resource).perform
+      new(account).from_response(response.body[:data])
+    end
+
+    def save
+      resource = RESOURCE % { account_id: account.id }
+      params = to_params
+      response = Request.new(account.client, :put, resource, params: params).perform
+      from_response(response.body[:data])
+    end
   end
 end