twitter-ads 0.3.4

data/lib/twitter-ads/error.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+
+  class Error < StandardError
+
+    attr_reader :code, :headers, :response, :details
+
+    def initialize(*args)
+      if args.size == 1 && args[0].respond_to?(:body) && args[0].respond_to?(:code)
+        @response = args[0]
+        @code     = args[0].code
+        @details  = args[0].body[:errors] if args[0].body.is_a?(Hash) && args[0].body[:errors]
+      elsif args.size == 3
+        @response = args[0]
+        @details  = args[1]
+        @code     = args[2]
+      end
+      self
+    end
+
+    def inspect
+      str = String.new("#<#{self.class.name}:0x#{object_id}")
+      str << " code=#{@code}" if @code
+      str << " details=\"#{@details}\"" if @details
+      str << '>'
+    end
+    alias to_s inspect
+
+    class << self
+
+      ERRORS = {
+        400 => 'TwitterAds::BadRequest',
+        401 => 'TwitterAds::NotAuthorized',
+        403 => 'TwitterAds::Forbidden',
+        404 => 'TwitterAds::NotFound',
+        429 => 'TwitterAds::RateLimit',
+        500 => 'TwitterAds::ServerError',
+        503 => 'TwitterAds::ServiceUnavailable'
+      }.freeze
+
+      # Returns an appropriately typed Error object based from an API response.
+      #
+      # @param object [Hash] The parsed JSON API response.
+      #
+      # @return [Error] The error object instance.
+      #
+      # @since 0.1.0
+      # @api private
+      def from_response(object)
+        return class_eval(ERRORS[object.code]).new(object) if ERRORS.key?(object.code)
+        new(object) # fallback, unknown error
+      end
+
+    end
+
+  end
+
+  # 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
+
+  # Client Errors (4XX)
+  class ClientError < Error; end
+  class NotAuthorized < ClientError; end
+  class Forbidden < ClientError; end
+  class NotFound < ClientError; end
+  class BadRequest < ClientError; end
+
+  class RateLimit < ClientError
+    attr_reader :reset_at, :retry_after
+
+    def initialize(object)
+      super object
+      @retry_after = object.headers['retry-after']
+      @reset_at = object.headers['rate_limit_reset']
+      self
+    end
+  end
+
+end

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

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+
+  # Generic container for API requests.
+  class Request
+
+    attr_reader :client, :method, :resource, :options
+
+    HTTP_METHOD = {
+      get:    Net::HTTP::Get,
+      post:   Net::HTTP::Post,
+      put:    Net::HTTP::Put,
+      delete: Net::HTTP::Delete
+    }.freeze
+
+    DEFAULT_DOMAIN = 'https://ads-api.twitter.com'.freeze
+    SANDBOX_DOMAIN = 'https://ads-api-sandbox.twitter.com'.freeze
+
+    private_constant :DEFAULT_DOMAIN, :SANDBOX_DOMAIN, :HTTP_METHOD
+
+    # Creates a new Request object instance.
+    #
+    # @example
+    #   request = Request.new(client, :get, '/0/accounts')
+    #
+    # @param client [Client] The Client object instance.
+    # @param method [Symbol] The HTTP method to be used.
+    # @param resource [String] The resource path for the request.
+    #
+    # @param opts [Hash] An optional Hash of extended options.
+    # @option opts [String] :domain Forced override for default domain to use for the request. This
+    #   value will also override :sandbox mode on the client.
+    #
+    # @since 0.1.0
+    #
+    # @return [Request] The Request object instance.
+    def initialize(client, method, resource, opts = {})
+      @client   = client
+      @method   = method
+      @resource = resource
+      @options  = opts
+      self
+    end
+
+    # Executes the current Request object.
+    #
+    # @example
+    #   request = Request.new(client, :get, '/0/accounts')
+    #   request.perform
+    #
+    # @since  0.1.0
+    #
+    # @return [Response] The Response object instance generated by the Request.
+    def perform
+      handle_error(oauth_request)
+    end
+
+    private
+
+    def domain
+      @domain ||= begin
+        @options[:domain] || (@client.options[:sandbox] ? SANDBOX_DOMAIN : DEFAULT_DOMAIN)
+      end
+    end
+
+    def oauth_request
+      request  = http_request
+      consumer = OAuth::Consumer.new(@client.consumer_key, @client.consumer_secret, site: domain)
+      token    = OAuth::AccessToken.new(consumer, @client.access_token, @client.access_token_secret)
+      request.oauth!(consumer.http, consumer, token)
+
+      write_log(request) if @client.options[:trace]
+      response = consumer.http.request(request)
+      write_log(response) if @client.options[:trace]
+
+      Response.new(response.code, response.each {}, response.body)
+    end
+
+    def http_request
+      request_url = @resource
+      if @options[:params] && !@options[:params].empty?
+        request_url += "?#{URI.encode_www_form(@options[:params])}"
+      end
+
+      request      = HTTP_METHOD[@method].new(request_url)
+      request.body = @options[:body] if @options[:body]
+
+      @options[:headers].each { |header, value| request[header] = value } if @options[:headers]
+      request['user-agent'] = user_agent
+
+      request
+    end
+
+    def user_agent
+      "twitter-ads version: #{TwitterAds::VERSION} " \
+      "platform: #{RUBY_ENGINE} #{RUBY_VERSION} (#{RUBY_PLATFORM})"
+    end
+
+    def write_log(object)
+      if object.respond_to?(:code)
+        @client.logger.info("Status: #{object.code} #{object.message}")
+      else
+        @client.logger.info("Send: #{object.method} #{domain}#{@resource} #{@options[:params]}")
+      end
+
+      object.each { |header| @client.logger.info("Header: #{header}: #{object[header]}") }
+
+      # suppresses body content for non-Ads API domains (eg. upload.twitter.com)
+      if object.body && !object.body.empty?
+        if @domain == SANDBOX_DOMAIN || @domain == DEFAULT_DOMAIN
+          @client.logger.info("Body: #{object.body}")
+        else
+          @client.logger.info('Body: **OMITTED**')
+        end
+      end
+    end
+
+    def handle_error(response)
+      raise TwitterAds::Error.from_response(response) unless response.code < 400
+      response
+    end
+
+  end
+
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+
+  # Generic container for API responses.
+  class Response
+
+    attr_reader :code,
+                :headers,
+                :raw_body,
+                :body,
+                :rate_limit_remaining,
+                :rate_limit_reset
+
+    # Creates a new Response object instance.
+    #
+    # @example
+    #   response = Response.new(code, headers, body)
+    #
+    # @param code [String] The HTTP status code.
+    # @param headers [Hash] A Hash object containing HTTP response headers.
+    # @param body [String] The response body.
+    #
+    # @since 0.1.0
+    #
+    # @return [Response] The Response object instance.
+    def initialize(code, headers, body)
+      @code     = code.to_i
+      @headers  = headers
+      @raw_body = body
+
+      # handle non-JSON responses
+      begin
+        @body = TwitterAds::Utils.symbolize!(MultiJson.load(body))
+      rescue MultiJson::ParseError
+        @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
+
+    # Returns an inspection string for the current Response instance.
+    #
+    # @example
+    #   response.inspect
+    #
+    # @since 0.1.0
+    #
+    # @return [String] The inspection string.
+    def inspect
+      "#<#{self.class.name}:0x#{object_id} code=\"#{@code}\" error=\"#{error?}\">"
+    end
+
+    # Helper method for determining if the current Response contains an error.
+    #
+    # @return [Boolean] True or false indicating if this Response contains an error.
+    def error?
+      @error ||= (@code >= 400 && @code <= 599)
+    end
+
+  end
+
+end

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

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+
+  # Specialized request class for TON API uploads.
+  class TONUpload
+
+    DEFAULT_DOMAIN   = 'https://ton.twitter.com'.freeze # @api private
+    DEFAULT_RESOURCE = '/1.1/ton/bucket/'.freeze # @api private
+    DEFAULT_BUCKET   = 'ta_partner'.freeze # @api private
+    DEFAULT_EXPIRE   = (Time.now + 10 * 24 * 60 * 60).httpdate # @api private
+    MIN_FILE_SIZE    = 1024 * 1024 * 1 # @api private
+
+    private_constant :DEFAULT_DOMAIN,
+                     :DEFAULT_BUCKET,
+                     :DEFAULT_EXPIRE,
+                     :DEFAULT_RESOURCE,
+                     :MIN_FILE_SIZE
+
+    # Creates a new TONUpload object instance.
+    #
+    # @example
+    #   request = TONUpload.new(client, '/path/to/file')
+    #
+    # @param client [Client] The Client object instance.
+    # @param file_path [String] The path to the file to be uploaded.
+    #
+    # @since 0.3.0
+    #
+    # @return [TONUpload] The TONUpload request instance.
+    def initialize(client, file_path, opts = {})
+      @file_path = File.expand_path(file_path)
+      unless File.exist?(file_path)
+        raise ArgumentError.new("Error! The specified file does not exist. (#{file_path})")
+      end
+
+      @file_size = File.size(@file_path)
+
+      @client    = client
+      @bucket    = opts.delete(:bucket) || DEFAULT_BUCKET
+      @options   = opts
+      self
+    end
+
+    # Executes the current TONUpload object.
+    #
+    # @example
+    #   request = TONUpload.new(client, '/path/to/file')
+    #   request.perform
+    #
+    # @since 0.3.0
+    #
+    # @return [String] The upload location provided by the TON API.
+    def perform
+      if @file_size < MIN_FILE_SIZE
+        resource = "#{DEFAULT_RESOURCE}#{@bucket}"
+        response = upload(resource, File.read(@file_path))
+        response.headers['location'][0]
+      else
+        response   = init_chunked_upload
+        chunk_size = response.headers['x-ton-min-chunk-size'][0].to_i
+        location   = response.headers['location'][0]
+
+        File.open(@file_path) do |file|
+          bytes_read = 0
+          while bytes = file.read(chunk_size)
+            bytes_start = bytes_read
+            bytes_read += bytes.size
+            upload_chunk(location, chunk_size, bytes, bytes_start, bytes_read)
+          end
+        end
+
+        location
+      end
+    end
+
+    # Returns an inspection string for the current object instance.
+    #
+    # @since 0.3.0
+    #
+    # @return [String] The object instance detail.
+    def inspect
+      "#<#{self.class.name}:0x#{object_id} bucket=\"#{@bucket}\" file=\"#{@file_path}\">"
+    end
+
+    private
+
+    # performs a single chunk upload
+    def upload(resource, bytes)
+      headers = {
+        'x-ton-expires'  => DEFAULT_EXPIRE,
+        'content-length' => @file_size,
+        'content-type'   => content_type
+      }
+      TwitterAds::Request.new(
+        @client, :post, resource, domain:  DEFAULT_DOMAIN, headers: headers, body: bytes).perform
+    end
+
+    # initialization for a multi-chunk upload
+    def init_chunked_upload
+      headers = {
+        'x-ton-content-type'   => content_type,
+        'x-ton-content-length' => @file_size,
+        'x-ton-expires'        => DEFAULT_EXPIRE,
+        'content-length'       => 0,
+        'content-type'         => content_type
+      }
+      resource = "#{DEFAULT_RESOURCE}#{@bucket}?resumable=true"
+      TwitterAds::Request.new(
+        @client, :post, resource, domain: DEFAULT_DOMAIN, headers: headers).perform
+    end
+
+    # uploads a single chunk of a multi-chunk upload
+    def upload_chunk(resource, chunk_size, bytes, bytes_start, bytes_read)
+      headers = {
+        'content-type'   => content_type,
+        'content-length' => [chunk_size, @file_size - bytes_read].min,
+        'content-range'  => "bytes #{bytes_start}-#{bytes_read - 1}/#{@file_size}"
+      }
+      TwitterAds::Request.new(
+        @client, :put, resource, domain: DEFAULT_DOMAIN, headers: headers, body: bytes).perform
+    end
+
+    def content_type
+      @content_type ||= begin
+        extension = File.extname(@file_path).downcase
+        if extension == '.csv'
+          'text/csv'
+        elsif extension == '.tsv'
+          'text/tab-separated-values'
+        else
+          'text/plain'
+        end
+      end
+    end
+
+  end
+
+end

data/lib/twitter-ads/legacy.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+# legacy namespace support, to be removed in v1.0.0 (next major)
+TwitterAds::Objective = TwitterAds::Enum::Objective
+TwitterAds::Product = TwitterAds::Enum::Product
+TwitterAds::Placement = TwitterAds::Enum::Placement

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  module Analytics
+
+    CLASS_ID_MAP = {
+      'TwitterAds::LineItem'                => :line_item_ids,
+      'TwitterAds::OrganicTweet'            => :tweet_ids,
+      'TwitterAds::Tweet'                   => :tweet_ids,
+      'TwitterAds::Creative::PromotedTweet' => :promoted_tweet_ids
+    }.freeze # @api private
+
+    def self.included(klass)
+      klass.send :include, InstanceMethods
+      klass.extend ClassMethods
+    end
+
+    module InstanceMethods
+
+      # Pulls a list of metrics for the current object instance.
+      #
+      # @example
+      #   metrics = [:promoted_tweet_timeline_clicks, :promoted_tweet_search_clicks]
+      #   object.stats(metrics)
+      #
+      # @param metrics [Array] A collection of valid metrics to be fetched.
+      # @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).
+      # @option opts [Symbol] :segmentation_type The segmentation type to use (default: none).
+      #
+      # @return [Array] The collection of stats requested.
+      #
+      # @see https://dev.twitter.com/ads/analytics/metrics-and-segmentation
+      # @since 0.1.0
+      def stats(metrics, opts = {})
+        self.class.stats(account, [id], metrics, opts)
+      end
+
+    end
+
+    module ClassMethods
+
+      # Pulls a list of metrics for a specified set of object IDs.
+      #
+      # @example
+      #   ids = ['7o4em', 'oc9ce', '1c5lji']
+      #   metrics = [:promoted_tweet_timeline_clicks, :promoted_tweet_search_clicks]
+      #   object.stats(account, ids, metrics)
+      #
+      # @param account [Account] The Account object instance.
+      # @param ids [Array] A collection of object IDs being targeted.
+      # @param metrics [Array] A collection of valid metrics to be fetched.
+      # @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).
+      # @option opts [Symbol] :segmentation_type The segmentation type to use (default: none).
+      #
+      # @return [Array] The collection of stats requested.
+      #
+      # @see https://dev.twitter.com/ads/analytics/metrics-and-segmentation
+      # @since 0.1.0
+      def stats(account, ids, metrics, opts = {})
+        # set default metric values
+        end_time          = opts.fetch(:end_time, Time.now)
+        start_time        = opts.fetch(:start_time, end_time - 604_800) # 7 days ago
+        granularity       = opts.fetch(:granularity, :hour)
+        segmentation_type = opts.fetch(:segmentation_type, nil)
+
+        params = {
+          metrics: metrics.join(','),
+          start_time: TwitterAds::Utils.to_time(start_time, granularity),
+          end_time: TwitterAds::Utils.to_time(end_time, granularity),
+          granularity: granularity.to_s.upcase
+        }
+        params[:segmentation_type] = segmentation_type.to_s.upcase if segmentation_type
+        params[TwitterAds::Analytics::CLASS_ID_MAP[name]] = ids.join(',')
+
+        resource = self::RESOURCE_STATS % { account_id: account.id }
+        response = Request.new(account.client, :get, resource, params: params).perform
+        response.body[:data]
+      end
+
+    end
+
+  end
+end