bing_ads_ruby_sdk 0.0.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 19d9468ca04839a78af34cbe1e45cbde578a7f3c
-  data.tar.gz: 45a579ccf5d81cf82f9b8881f6cf1dd1bfeb4474
+  metadata.gz: 11c7e24cf05dfac01e506e24cb886fe6d7290ea3
+  data.tar.gz: 8877b5a30d082582c90777e8ced9d68d8ab2fcf9
 SHA512:
-  metadata.gz: ed3e275860eb7c4f1f5057185be411c3c0db8a8ad14a951d435bb56dbf2301baabc7494a9753a49d97f3a8ed08d3a45a10aa9d6442dcb324c340f8f75e7fda66
-  data.tar.gz: f0bec9ee6cf4c974a27f8c658ebf9ad2d90d3ac2c347097947c28652ebe2c91d6be2511cef68e8df8aea30b88826c3da95072c144820150a178b74a0de5635a1
+  metadata.gz: 3b974e4c75e62f5018b52e6b6158594c6186f5774d1b822934ed82cf94ab8cfd911c48abe8d1aa8cdfa2e987abc4b5f9842eba763036979124ea6546cd03c168
+  data.tar.gz: 0d5fd652d0107446ff4413ca14e4e5bcfc5872e06fee42d001b52deb79d0df474c702d479743e187fe3495458ef9b9e5ce035e0275b8aeadbcae432d9829e36f

data/.gitignore

@@ -7,6 +7,11 @@
 /pkg/
 /spec/reports/
 /tmp/
-
+/log/*
 # rspec failure tracking
 .rspec_status
+.token_*
+
+.byebug_history
+.env
+custom_setup.rb

data/.rspec

@@ -1,2 +1,4 @@
---format documentation
+--format progress
 --color
+--exclude-pattern '**/examples/**/*_spec.rb'
+--require spec_helper

data/Gemfile

@@ -2,6 +2,3 @@ source "https://rubygems.org"
 
 # Specify your gem's dependencies in bing_ads_ruby_sdk.gemspec
 gemspec
-
-# remove after/if merged
-gem 'lolsoap', git: 'https://github.com/effilab/lolsoap', branch: 'edge'

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2017 sami
+Copyright (c) 2017 Effilab
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,12 +1,8 @@
 # BingAdsRubySdk
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/bing_ads_ruby_sdk`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
-
 ## Installation
 
-Add this line to your application's Gemfile:
+Add the following to your application's Gemfile:
 
 ```ruby
 gem 'bing_ads_ruby_sdk'
@@ -20,19 +16,84 @@ Or install it yourself as:
 
     $ gem install bing_ads_ruby_sdk
 
-## Usage
+## Getting Started
+
+In order to use Bing's api you need to get your api credentials from bing. From there gem handles the oauth token generation.
+
+By default, there is only one store in the gem to store the oauth token. It's a file system based store. You can create one yourself to store credentials in a database or wherever you desire. The store class must implement `read` and `write(data)` instance methods.
+
+To get your token, run:
+```ruby
+rake bing_token:get[my_token.json,your_dev_token,your_bing_client_id]
+
+```
+
+
+Then to use the api:
+```ruby
+store = ::BingAdsRubySdk::OAuth2::FsStore.new('my_token.json')
+api = BingAdsRubySdk::Api.new(
+  oauth_store: store,
+  developer_token: 'your_dev_token',
+  client_id: 'your_bing_client_id'
+)
+api.customer_management.signup_customer(params)
+  filter: 'name',
+  top_n: 1
+)
+
+# once you have your bing customer and account ids:
+api.set_customer(customer_id: customer_id, account_id: account_id )
+
+api.campaign_management.get_campaigns_by_account_id(account_id: account_id)
+```
+
+You'll see services like `customer_management` implement some methods, but not all the ones available in the API.
+
+The methods implemented contain additional code to ease data manipulation but any endpoint can be reached using `call` on a service.
+
+```ruby
+@cm.call(:find_accounts_or_customers_info, filter: 'name', top_n: 1)
+# => { account_info_with_customer_data: { account_info_with_customer_data: [{ customer_id: "250364751", :
+
+# VS method dedicated to extract data
+
+@cm.find_accounts_or_customers_info(filter: 'name', top_n: 1)
+# => [{ customer_id: "250364731" ...
 
-TODO: Write usage instructions here
+```
+
+
+## Configure the gem
+```ruby
+BingAdsRubySdk.configure do |conf|
+  conf.log = true
+  conf.logger.level = Logger::DEBUG
+  conf.pretty_print_xml = true
+  # to filter sensitive data before logging
+  conf.filters = ["AuthenticationToken", "DeveloperToken"]
+end
+```
 
 ## Development
 
+### Updating to a new Bing API version
+Bing regularly releases new versions of the API and removes support for old versions.
+When you want to support a new version of the API, here are some of the things that
+need to be changed:
+* Go to https://docs.microsoft.com/en-us/bingads/guides/migration-guide to see what has changed
+* Set the default SDK version in lib/bing_ads_ruby_sdk/version.rb
+
+### Specs
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push git
+commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/bing_ads_ruby_sdk.
+Bug reports and pull requests are welcome on GitHub at https://github.com/Effilab/bing_ads_ruby_sdk.
 
 ## License
 

data/Rakefile

@@ -1,5 +1,7 @@
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
+require './lib/bing_ads_ruby_sdk'
+import 'tasks/bing_ads_ruby_sdk.rake'
 
 RSpec::Core::RakeTask.new(:spec)
 

data/bin/setup

@@ -3,6 +3,4 @@ set -euo pipefail
 IFS=$'\n\t'
 set -vx
 
-bundle install
-
-# Do any other automated setup that you need to do here
+bundle install

data/bing_ads_ruby_sdk.gemspec

@@ -5,37 +5,32 @@ require 'bing_ads_ruby_sdk/version'
 
 Gem::Specification.new do |spec|
   spec.name          = 'bing_ads_ruby_sdk'
+  spec.required_ruby_version = '>= 2.0'
+
   spec.version       = BingAdsRubySdk::VERSION
-  spec.authors       = ["Effilab", "Sami Ben-yahia"]
-  spec.email         = %w[contact@effilab-local.com]
+  spec.authors       = %w[Effilab developers]
+  spec.email         = %w[developers@effilab-local.com]
 
   spec.summary       = 'Bing Ads Ruby SDK'
-  spec.description   = 'The Bing Ads Ruby Software Development Kit (SDK) ' \
-    'enhances the experience of developing Bing Ads applications with the ' \
-    'Ruby programming language'
-  spec.homepage      = 'https://github.com/effilab/bing_ads_ruby_sdk'
+  spec.description   = 'Bing Ads Api Wrapper'
+  spec.homepage      = 'https://github.com/Effilab/bing_ads_ruby_sdk'
   spec.license       = 'MIT'
 
-  if spec.respond_to?(:metadata)
-    spec.metadata['allowed_push_host'] = "https://rubygems.org"
-  else
-    raise 'RubyGems 2.0 or newer is required to protect against ' \
-      'public gem pushes.'
-  end
-
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
   end
-  spec.bindir        = 'exe'
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = %w[lib]
 
-  spec.add_dependency 'signet', '~> 0.7'
-  spec.add_dependency 'lolsoap', '~> 0.8'
+  spec.add_runtime_dependency 'signet', '~> 0.8.1'
+  spec.add_runtime_dependency 'excon', '>= 0.62.0'
+  spec.add_runtime_dependency 'lolsoap', '>=0.9.0'
 
-  spec.add_development_dependency 'bundler', '~> 1.15'
-  spec.add_development_dependency 'rake', '~> 12.0'
-  spec.add_development_dependency 'yard', '~> 0.9'
-  spec.add_development_dependency 'rspec', '~> 3.6'
-  spec.add_development_dependency 'simplecov', '~> 0.14'
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'dotenv'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'yard'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'byebug'
+  spec.add_development_dependency 'awesome_print'
 end

data/changelog.md

@@ -0,0 +1,19 @@
+## V1.0.0 Release
+The main reasons of the refactoring were to:
+
+- add convenient methods returning structured data
+
+- remove metaprogramming
+
+- remove the dependency on an unmerged and unmaintained branch of the lolsoap gem
+
+
+Alongside these key points, we now have:
+
+- filtred logs
+
+- split concerns
+
+- strong specs suite
+
+- a customizable configuration

data/lib/bing_ads_ruby_sdk.rb

@@ -1,5 +1,34 @@
-require "bing_ads_ruby_sdk/version"
+# frozen_string_literal: true
+require 'time'
+require 'lolsoap'
+
+require 'bing_ads_ruby_sdk/version'
+require 'bing_ads_ruby_sdk/configuration'
+require 'bing_ads_ruby_sdk/api'
+require 'bing_ads_ruby_sdk/string_utils'
 
 module BingAdsRubySdk
-  # Your code goes here...
-end
+  def self.config
+    @configuration ||= BingAdsRubySdk::Configuration.new
+  end
+
+  def self.configure
+    yield(config)
+  end
+
+  def self.log(level, *args, &block)
+    return unless config.log
+    config.logger.send(level, *args, &block)
+  end
+
+  def self.root_path
+    ROOT_PATH
+  end
+
+  def self.type_key
+    TYPE_KEY
+  end
+
+  TYPE_KEY = '@type'
+  ROOT_PATH = File.join(__dir__,'..')
+end

data/lib/bing_ads_ruby_sdk/api.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "bing_ads_ruby_sdk/header"
+require "bing_ads_ruby_sdk/soap_client"
+require "bing_ads_ruby_sdk/services/base"
+require "bing_ads_ruby_sdk/services/ad_insight"
+require "bing_ads_ruby_sdk/services/bulk"
+require "bing_ads_ruby_sdk/services/campaign_management"
+require "bing_ads_ruby_sdk/services/customer_billing"
+require "bing_ads_ruby_sdk/services/customer_management"
+require "bing_ads_ruby_sdk/services/reporting"
+require "bing_ads_ruby_sdk/oauth2/authorization_handler"
+require "bing_ads_ruby_sdk/errors/errors"
+require "bing_ads_ruby_sdk/errors/error_handler"
+
+module BingAdsRubySdk
+  class Api
+    attr_reader :header
+
+    # @param version [Symbol] API version, used to choose WSDL configuration version
+    # @param environment [Symbol]
+    # @option environment [Symbol] :production Use the production WSDL configuration
+    # @option environment [Symbol] :sandbox Use the sandbox WSDL configuration
+    # @param developer_token
+    # @param client_id
+    def initialize(version: DEFAULT_SDK_VERSION,
+                   environment: :production,
+                   developer_token:,
+                   client_id:,
+                   oauth_store:)
+      @version = version
+      @environment = environment
+      @header = Header.new(
+        developer_token: developer_token,
+        client_id: client_id,
+        store: oauth_store
+      )
+    end
+
+    def ad_insight
+      build_service(BingAdsRubySdk::Services::AdInsight)
+    end
+
+    def bulk
+      build_service(BingAdsRubySdk::Services::Bulk)
+    end
+
+    def campaign_management
+      build_service(BingAdsRubySdk::Services::CampaignManagement)
+    end
+
+    def customer_billing
+      build_service(BingAdsRubySdk::Services::CustomerBilling)
+    end
+
+    def customer_management
+      build_service(BingAdsRubySdk::Services::CustomerManagement)
+    end
+
+    def reporting
+      build_service(BingAdsRubySdk::Services::Reporting)
+    end
+
+    def set_customer(account_id:, customer_id:)
+      header.set_customer(account_id: account_id, customer_id: customer_id)
+    end
+
+    private
+
+    def build_service(klass)
+      klass.new(
+        BingAdsRubySdk::SoapClient.new(
+          version: @version,
+          environment: @environment,
+          header: header,
+          service_name: klass.service
+        )
+      )
+    end
+  end
+end

data/lib/bing_ads_ruby_sdk/augmented_parser.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module BingAdsRubySdk
+  class AugmentedParser
+
+    def initialize(wsdl_file_path)
+      @lolsoap_parser = LolSoap::WSDLParser.parse(File.read(wsdl_file_path))
+      @concrete_abstract_mapping = {}
+    end
+
+    def call
+      add_subtypes_to_definitions
+
+      [lolsoap_parser, concrete_abstract_mapping]
+    end
+
+    private
+
+    attr_reader :lolsoap_parser, :concrete_abstract_mapping
+
+    # adds subtypes to existing definitions.
+    # for instance, the wsdl specifies AdExtensionAssociation are accepted for AddAdExtension
+    # but there is no way to specify the type we want
+    # the goal is to:
+    # - validate properly the attributes
+    # - ensure the attributes are properly formatted when xml is created
+    # - ensure we inject proper type to the xml
+    def add_subtypes_to_definitions
+      # to augment all types definitions
+      lolsoap_parser.types.each_value do |content|
+        add_subtypes(content[:elements])
+      end
+      # we have to augment operations because some Requests are abstract, for instance:
+      # ReportRequest which can be AccountPerformanceReportRequest etc...
+      lolsoap_parser.operations.each_value do |content|
+        content[:input][:body].each do |full_name|
+          add_subtypes(lolsoap_parser.elements[full_name][:type][:elements])
+        end
+      end
+      @grouped_subtypes = nil # we can reset this as its not needed anymore
+    end
+
+    def add_subtypes(content)
+      content.keys.each do |base|
+        grouped_subtypes.fetch(base, []).each do |sub_type|
+          elem = lolsoap_parser.elements[sub_type.id]
+          elem[:base_type_name] = base
+          content[sub_type.name] = elem
+        end
+      end
+    end
+
+    def grouped_subtypes
+      @grouped_subtypes ||= begin
+        grouped_types = {}
+        # types are defined there: https://github.com/loco2/lolsoap/blob/master/lib/lolsoap/wsdl_parser.rb#L305
+        lolsoap_parser.each_node('xs:complexType[not(@abstract="true")]') do |node, schema|
+          type = ::LolSoap::WSDLParser::Type.new(lolsoap_parser, schema, node)
+          if type.base_type # it has a base_type, its a subtype
+            base_type = extract_base_type(type.base_type)
+            concrete_abstract_mapping[type.name] = base_type.name
+            grouped_types[base_type.name] ||= []
+            grouped_types[base_type.name].push(type)
+          end
+        end
+        grouped_types
+      end
+    end
+
+    # we want the real base: sometimes there are many layers of inheritance
+    def extract_base_type(type)
+      if type.base_type
+        extract_base_type(type.base_type)
+      else
+        type
+      end
+    end
+  end
+end