soapy_bing 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 07b8f667808f19487bb63afecce80900cbdb0116
+  data.tar.gz: cef996017af61aa78230fba06560e3c89304c9a8
+SHA512:
+  metadata.gz: ff3885794184b39eae3827dba80d1b512342b80fa9ef34965c9e8c9477808fcc9196ab2a35262c150e3e4444cceba8d2c6fc3db268bfd1fd70c98e9b5fc60c9a
+  data.tar.gz: 2a81559fa1fe6f2d9db5201489d87b3749cf52542cdbeeee689c760b21c67d10de72fd70ac5622b4fb9022866f2b299b041d49499d5df26985a6aba3121cf445

data/.env

@@ -0,0 +1,6 @@
+export BING_ADS_OAUTH_CLIENT_ID='bing-ads-oauth-client-id'
+export BING_ADS_OAUTH_CLIENT_SECRET='bing-ads-oauth-client-secret'
+export BING_ADS_OAUTH_REFRESH_TOKEN='bing-ads-oauth-refresh-token'
+export BING_ADS_DEVELOPER_TOKEN='bing-ads-developer-token'
+export BING_ADS_ACCOUNT_ID='bing-ads-account-id'
+export BING_ADS_CUSTOMER_ID='bing-ads-customer-id'

data/.gitignore

@@ -0,0 +1,6 @@
+Gemfile.lock
+
+/coverage
+
+.env.local
+.env.development

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.ruby-version

@@ -0,0 +1 @@
+2.2.3

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rubocop-ci', github: 'ad2games/rubocop-ci'
+gem 'simplecov', require: false

data/README.md

@@ -0,0 +1,63 @@
+# SoapyBing
+[![Circle CI](https://circleci.com/gh/ad2games/soapy_bing.png?style=shield)](https://circleci.com/gh/ad2games/soapy_bing)
+
+Client library for [Bing Ads API](https://msdn.microsoft.com/en-us/library/bing-ads-overview)
+
+## Installation
+
+In your Gemfile
+
+```ruby
+gem 'soapy-bing', git: 'https://github.com/ad2games/soapy-bing'
+```
+
+## Usage Examples
+
+```ruby
+bing_ads = SoapyBing::Ads.new
+report = bing_ads.campaign_performance_report(
+  date_start: '2015-10-14',
+  date_end: '2015-10-14',
+
+  settings: {       # optional
+    columns: ['']   # see SoapyBing::Ads::Report::Base::DEFAULT_REPORT_SETTINGS[:columns]
+  }
+)
+report.rows # =>
+            #     [{
+            #       "HourOfDay"    => "0",
+            #       "CampaignName" => "My Campaign",
+            #       "Impressions"  => "100",
+            #       "Clicks"       => "47",
+            #       "Spend"        => "12.65"
+            #     }, {
+            #       ...
+            #     }]
+```
+
+## Authentication
+
+Authentication attributes could be passed explicitly when new instance of SoapyBing::Ads is created.
+Or they could be configured as Envronment variables.
+
+```ruby
+SoapyBing::Ads.new(
+  oauth: {                  # optional, could be configured via environment variables as
+    client_id: '',          # ENV['BING_ADS_OAUTH_CLIENT_ID']
+    client_secret: '',      # ENV['BING_ADS_OAUTH_CLIENT_SECRET']
+    refresh_token: ''       # ENV['BING_ADS_OAUTH_REFRESH_TOKEN']
+  },
+  account: {                # optional, could be configured via environment variables as
+    developer_token: '',    # ENV['BING_ADS_DEVELOPER_TOKEN']
+    account_id: '',         # ENV['BING_ADS_ACCOUNT_ID']
+    customer_id: ''         # ENV['BING_ADS_CUSTOMER_ID']
+  }
+)
+```
+
+## Links
+* MS Live Applications [https://account.live.com/developers/applications](https://account.live.com/developers/applications)
+* Bing Ads User Authentication with OAuth [https://msdn.microsoft.com/en-us/library/bing-ads-user-authentication-oauth-guide.aspx](https://msdn.microsoft.com/en-us/library/bing-ads-user-authentication-oauth-guide.aspx)
+* Getting Started With the Bing Ads API [https://msdn.microsoft.com/en-us/library/bing-ads-getting-started.aspx](https://msdn.microsoft.com/en-us/library/bing-ads-getting-started.aspx)
+* Bing Ads API Reference [https://msdn.microsoft.com/en-US/library/bing-ads-api-reference.aspx](https://msdn.microsoft.com/en-US/library/bing-ads-api-reference.aspx)
+* Reporting Service Reference [https://msdn.microsoft.com/en-US/library/bing-ads-reporting-service-reference](https://msdn.microsoft.com/en-US/library/bing-ads-reporting-service-reference)

data/Rakefile

@@ -0,0 +1,7 @@
+require 'rubygems'
+require 'bundler/setup'
+
+require 'bundler/gem_tasks'
+require 'rubocop-ci'
+
+Rake.add_rakelib 'lib/tasks'

data/circle.yml

@@ -0,0 +1,6 @@
+dependencies:
+  post:
+    - bundle update
+test:
+  pre:
+    - bundle exec rake rubocop

data/lib/soapy_bing/account.rb

@@ -0,0 +1,12 @@
+module SoapyBing
+  class Account
+    attr_reader :developer_token, :account_id, :customer_id
+
+    def initialize(account_options)
+      param_guard = ParamGuard.new(account_options, env_namespace: 'BING_ADS')
+      @developer_token = param_guard.require!(:developer_token)
+      @account_id = param_guard.require!(:account_id)
+      @customer_id = param_guard.require!(:customer_id)
+    end
+  end
+end

data/lib/soapy_bing/ads/reports/base.rb

@@ -0,0 +1,83 @@
+require 'ostruct'
+require 'open-uri'
+require 'zip'
+
+module SoapyBing
+  class Ads
+    module Reports
+      class Base
+        class UnknownParserError < StandardError; end
+        include Helpers::ClassName
+
+        DEFAULT_REPORT_SETTINGS = {
+          format:      'Csv',
+          language:    'English',
+          name:        'MyReport',
+          aggregation: 'HourOfDay',
+          columns:     %w(TimePeriod CampaignName Impressions Clicks Spend)
+        }.freeze
+
+        attr_reader :oauth_credentials, :account, :settings
+
+        def initialize(options)
+          @oauth_credentials = options.fetch(:oauth_credentials)
+          @account = options.fetch(:account)
+          @settings = OpenStruct.new(DEFAULT_REPORT_SETTINGS.merge(options.fetch(:settings, {})))
+        end
+
+        def rows
+          @rows ||= parser_class.new(report_body).rows
+        end
+
+        private
+
+        def parser_class
+          class_name = "#{settings.format.upcase}Parser".to_sym
+          fail UnknownParserError, class_name unless Parsers.constants.include?(class_name)
+          Parsers.const_get class_name
+        end
+
+        def download_url
+          @url ||=
+            Soap::Request::PollGenerateReportRequest
+              .new(context: poll_generate_report_context)
+              .perform
+              .payload
+        end
+
+        def poll_generate_report_context
+          {
+            account: account,
+            authentication_token: oauth_credentials.access_token,
+            request_id: request_id
+          }
+        end
+
+        def report_body
+          @report_body ||=
+            Zip::InputStream.open(OpenURI.open_uri(download_url)) do |archive_io|
+              file_io = archive_io.get_next_entry.get_input_stream
+              file_io.read
+            end
+        end
+
+        def request_id
+          @request_id ||=
+            Soap::Request::SubmitGenerateReportRequest
+              .new(context: submit_generate_report_context)
+              .perform
+              .payload
+        end
+
+        def submit_generate_report_context
+          {
+            account: account,
+            authentication_token: oauth_credentials.access_token,
+            settings: settings,
+            report_class: class_name
+          }
+        end
+      end
+    end
+  end
+end

data/lib/soapy_bing/ads/reports/campaign_performance_report.rb

@@ -0,0 +1,23 @@
+require 'date'
+
+module SoapyBing
+  class Ads
+    module Reports
+      class CampaignPerformanceReport < Base
+        attr_reader :date_range
+
+        def initialize(options)
+          super(options)
+          @date_range = Range.new(
+            Date.parse(options.fetch(:date_start)),
+            Date.parse(options.fetch(:date_end))
+          )
+        end
+
+        def submit_generate_report_context
+          super.merge(date_range: date_range)
+        end
+      end
+    end
+  end
+end

data/lib/soapy_bing/ads/reports/parsers/csv_parser.rb

@@ -0,0 +1,45 @@
+require 'csv'
+
+module SoapyBing
+  class Ads
+    module Reports
+      module Parsers
+        class CSVParser
+          class FormatError < StandardError; end
+
+          CSV_PAYLOAD_OFFSET_FRONT = 10 # First 10 csv lines are report metadata
+          CSV_PAYLOAD_OFFSET_BACK = 2 # Last 2 csv lines are Microsoft copyright
+
+          def initialize(raw)
+            @raw = raw
+          end
+
+          def rows
+            @rows ||= begin
+              header, *body = extract_csv_payload
+              fail FormatError if body.size != payload_rows_number
+              body.map { |row| header.zip(row).to_h }
+            end
+          end
+
+          private
+
+          attr_reader :raw
+
+          def extract_csv_payload
+            text = raw.dup
+            text.force_encoding(Encoding::UTF_8).encode! unless text.encoding == Encoding::UTF_8
+            text.sub!(/^\xEF\xBB\xBF/, '') # cleanup BOM
+
+            csv_rows = CSV.parse(text)
+            csv_rows[CSV_PAYLOAD_OFFSET_FRONT...-CSV_PAYLOAD_OFFSET_BACK]
+          end
+
+          def payload_rows_number
+            raw.match(/"Rows: (\d+)"/)[1].to_i
+          end
+        end
+      end
+    end
+  end
+end

data/lib/soapy_bing/ads/reports/parsers.rb

@@ -0,0 +1 @@
+require 'soapy_bing/ads/reports/parsers/csv_parser'

data/lib/soapy_bing/ads/reports.rb

@@ -0,0 +1,3 @@
+require 'soapy_bing/ads/reports/parsers'
+require 'soapy_bing/ads/reports/base'
+require 'soapy_bing/ads/reports/campaign_performance_report'

data/lib/soapy_bing/ads.rb

@@ -0,0 +1,22 @@
+require 'soapy_bing/ads/reports'
+
+module SoapyBing
+  class Ads
+    attr_reader :oauth_credentials, :account
+
+    def initialize(oauth: {}, account: {})
+      @oauth_credentials = OauthCredentials.new(oauth)
+      @account = Account.new(account)
+    end
+
+    def campaign_performance_report(date_start:, date_end:, settings: {})
+      Reports::CampaignPerformanceReport.new(
+        oauth_credentials: oauth_credentials,
+        account: account,
+        date_start: date_start,
+        date_end: date_end,
+        settings: settings
+      )
+    end
+  end
+end

data/lib/soapy_bing/helpers/class_name.rb

@@ -0,0 +1,9 @@
+module SoapyBing
+  module Helpers
+    module ClassName
+      def class_name
+        @class_name ||= self.class.name.demodulize
+      end
+    end
+  end
+end

data/lib/soapy_bing/helpers.rb

@@ -0,0 +1 @@
+require 'soapy_bing/helpers/class_name'

data/lib/soapy_bing/oauth_credentials.rb

@@ -0,0 +1,43 @@
+require 'httparty'
+
+module SoapyBing
+  class OauthCredentials
+    class TokenRefreshError < StandardError; end
+
+    TOKEN_URL = 'https://login.live.com/oauth20_token.srf'.freeze
+
+    attr_reader :client_id, :client_secret, :refresh_token, :token_url
+
+    def initialize(oauth_options = {})
+      param_guard = ParamGuard.new(oauth_options, env_namespace: 'BING_ADS_OAUTH')
+      @client_id = param_guard.require!(:client_id)
+      @client_secret = param_guard.require!(:client_secret)
+      @refresh_token = param_guard.require!(:refresh_token)
+      @token_url = oauth_options.fetch(:token_url, ENV['BING_ADS_OAUTH_TOKEN_URL'] || TOKEN_URL)
+    end
+
+    def access_token
+      @access_token ||= request_access_token
+    end
+
+    private
+
+    def request_access_token
+      resp = HTTParty.post(token_url, body: access_token_params)
+      if resp.code == 200
+        resp['access_token']
+      else
+        fail TokenRefreshError
+      end
+    end
+
+    def access_token_params
+      {
+        client_id: client_id,
+        client_secret: client_secret,
+        grant_type: 'refresh_token',
+        refresh_token: refresh_token
+      }
+    end
+  end
+end

data/lib/soapy_bing/param_guard.rb

@@ -0,0 +1,26 @@
+module SoapyBing
+  class ParamGuard
+    class ParamRequiredError < StandardError; end
+
+    def initialize(local_options, env_namespace: '')
+      @local_options = local_options
+      @env_namespace = env_namespace
+    end
+
+    def require!(name)
+      local_options.fetch(name, ENV[env_var_name(name)]) || fail(ParamRequiredError, err_msg(name))
+    end
+
+    private
+
+    attr_reader :local_options, :env_namespace
+
+    def err_msg(name)
+      "#{name} have to be passed explicitly or via ENV['#{env_var_name(name)}']"
+    end
+
+    def env_var_name(name)
+      (env_namespace.empty? ? name : "#{env_namespace}_#{name}").upcase.tr('-', '_')
+    end
+  end
+end

data/lib/soapy_bing/soap/request/base.rb

@@ -0,0 +1,37 @@
+require 'httparty'
+
+module SoapyBing
+  module Soap
+    module Request
+      class Base
+        include Helpers::ClassName
+
+        DEFAULT_HTTP_HEADERS = {
+          'Content-Type' => 'text/xml;charset=UTF-8'
+        }.freeze
+
+        attr_reader :context
+
+        def initialize(context:)
+          @context = context
+        end
+
+        def post(url, body: default_body, headers: default_headers)
+          HTTParty.post(url, body: body, headers: headers)
+        end
+
+        def default_body
+          TemplateRenderer.new(context).render(action_name.underscore)
+        end
+
+        def default_headers
+          DEFAULT_HTTP_HEADERS.merge('SOAPAction' => action_name)
+        end
+
+        def action_name
+          class_name.sub(/Request$/, '')
+        end
+      end
+    end
+  end
+end

data/lib/soapy_bing/soap/request/poll_generate_report_request.rb

@@ -0,0 +1,33 @@
+module SoapyBing
+  module Soap
+    module Request
+      class PollGenerateReportRequest < Base
+        class FailedStatusError < StandardError; end
+        class PendingStatusError < StandardError; end
+        class PollingTimeoutError < StandardError; end
+
+        API_BASE_URL = 'https://reporting.api.bingads.microsoft.com'.freeze
+        API_VERSION = 9
+        API_ENDPOINT =
+          "#{API_BASE_URL}/Api/Advertiser/Reporting/V#{API_VERSION}/ReportingService.svc".freeze
+
+        POLLING_TRIES = 40
+
+        def perform
+          Retryable.retryable(tries: POLLING_TRIES, on: PendingStatusError) { poll! }
+        rescue PendingStatusError
+          raise PollingTimeoutError
+        end
+
+        private
+
+        def poll!
+          response = Response::PollGenerateReportResponse.new(post(API_ENDPOINT))
+          fail PendingStatusError if response.pending?
+          fail FailedStatusError if response.error?
+          response
+        end
+      end
+    end
+  end
+end

data/lib/soapy_bing/soap/request/submit_generate_report_request.rb

@@ -0,0 +1,16 @@
+module SoapyBing
+  module Soap
+    module Request
+      class SubmitGenerateReportRequest < Base
+        API_BASE_URL = 'https://reporting.api.bingads.microsoft.com'.freeze
+        API_VERSION = 9
+        API_ENDPOINT =
+          "#{API_BASE_URL}/Api/Advertiser/Reporting/V#{API_VERSION}/ReportingService.svc".freeze
+
+        def perform
+          Response::SubmitGenerateReportResponse.new(post(API_ENDPOINT))
+        end
+      end
+    end
+  end
+end

data/lib/soapy_bing/soap/request.rb

@@ -0,0 +1,3 @@
+require 'soapy_bing/soap/request/base'
+require 'soapy_bing/soap/request/submit_generate_report_request'
+require 'soapy_bing/soap/request/poll_generate_report_request'

data/lib/soapy_bing/soap/response/base.rb

@@ -0,0 +1,16 @@
+module SoapyBing
+  module Soap
+    module Response
+      class Base
+        include Helpers::ClassName
+        include Payload
+
+        attr_reader :body
+
+        def initialize(body)
+          @body = body
+        end
+      end
+    end
+  end
+end

data/lib/soapy_bing/soap/response/payload.rb

@@ -0,0 +1,15 @@
+module SoapyBing
+  module Soap
+    module Response
+      module Payload
+        def payload
+          @payload ||= extract_payload
+        end
+
+        def extract_payload
+          fail NotImplementedError
+        end
+      end
+    end
+  end
+end

data/lib/soapy_bing/soap/response/poll_generate_report_response.rb

@@ -0,0 +1,13 @@
+module SoapyBing
+  module Soap
+    module Response
+      class PollGenerateReportResponse < Base
+        include ReportStatus
+
+        def extract_payload
+          report_status['ReportDownloadUrl']
+        end
+      end
+    end
+  end
+end

data/lib/soapy_bing/soap/response/report_status.rb

@@ -0,0 +1,33 @@
+module SoapyBing
+  module Soap
+    module Response
+      module ReportStatus
+        include Helpers::ClassName
+
+        def status
+          @status ||= extract_status
+        end
+
+        def extract_status
+          report_status['Status']
+        end
+
+        def report_status
+          body['Envelope']['Body'][class_name]['ReportRequestStatus']
+        end
+
+        def error?
+          status == 'Error'
+        end
+
+        def success?
+          status == 'Success'
+        end
+
+        def pending?
+          status == 'Pending'
+        end
+      end
+    end
+  end
+end

data/lib/soapy_bing/soap/response/submit_generate_report_response.rb

@@ -0,0 +1,11 @@
+module SoapyBing
+  module Soap
+    module Response
+      class SubmitGenerateReportResponse < Base
+        def extract_payload
+          body['Envelope']['Body'][class_name]['ReportRequestId']
+        end
+      end
+    end
+  end
+end

data/lib/soapy_bing/soap/response.rb

@@ -0,0 +1,5 @@
+require 'soapy_bing/soap/response/payload'
+require 'soapy_bing/soap/response/report_status'
+require 'soapy_bing/soap/response/base'
+require 'soapy_bing/soap/response/submit_generate_report_response'
+require 'soapy_bing/soap/response/poll_generate_report_response'

data/lib/soapy_bing/soap/template_renderer.rb

@@ -0,0 +1,21 @@
+require 'ostruct'
+require 'erubis'
+
+module SoapyBing
+  module Soap
+    class TemplateRenderer < OpenStruct
+      TEMPLATE_PATH = File.expand_path('../templates', __FILE__)
+
+      def render(template_name)
+        template_body = read(template_name)
+        Erubis::XmlEruby.new(template_body).result(binding)
+      end
+
+      private
+
+      def read(name)
+        File.read(File.join(TEMPLATE_PATH, "#{name}.erb.xml"))
+      end
+    end
+  end
+end

data/lib/soapy_bing/soap/templates/poll_generate_report.erb.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+              xmlns:tns="https://bingads.microsoft.com/Reporting/v9"
+              xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
+              xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
+    <env:Header>
+        <tns:CustomerAccountId><%= account.account_id %></tns:CustomerAccountId>
+        <tns:CustomerId><%= account.customer_id %></tns:CustomerId>
+        <tns:DeveloperToken><%= account.developer_token %></tns:DeveloperToken>
+        <tns:AuthenticationToken><%= authentication_token %></tns:AuthenticationToken>
+    </env:Header>
+    <env:Body>
+        <tns:PollGenerateReportRequest>
+            <tns:ReportRequestId xsi:nil="false"><%= request_id %></tns:ReportRequestId>
+        </tns:PollGenerateReportRequest>
+    </env:Body>
+</env:Envelope>