blurb 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f418adffdec8cb6dad94905f36907bbb783afc52
-  data.tar.gz: 275ea7f93bc0ca704db76c4476c10cd4ecc1ea8a
+  metadata.gz: 4daa2abcd906bc38246e020252bd4334f5079724
+  data.tar.gz: 9a6782e3f58651dbbf4d4f91fe1b2f1b43d64dd8
 SHA512:
-  metadata.gz: 5bb60ed1768e2c2bb618518741768fd31759b9a10cae29210ab7ab3c1a5f7ee9d8d05f0059f8d3cd139653b2f6789d8fcaade68fbc0d96f4e4a81a043c2b59b8
-  data.tar.gz: be5d2d3a75f03c76493b1ff560f5041a87fc3bb402566d5fa63d96ec9e5e7a4749354d34fbc145ed595abf7c3ab87fc3683aa63306da2f2bbb26cb2405ab20d3
+  metadata.gz: 413565b433b897c04ece25f6869e535e9c8c39bf9c3c632ce4832ea0863bbcf2d9b2b54ad6c1a87474b39959f2b188117bccb56efe25e9401edfa79c8785f240
+  data.tar.gz: 30d7f25c7b81150eda725fb1da9abbf4408a0fe5f7fa2acc8dee0a51537194ba3bbb92b16239f7503bdca4e7fa9f5964fa8fe3b5f14f091c16fa8a4f07e2f483

data/README.md

@@ -130,7 +130,26 @@ Blurb.test_env = true
 ## Usage
 
 All API calls have been setup as closely as possible to REST Resource calls.
-All you need to do is find the appropriate resource object and make a method call on it and Blurb will do the rest.
+All you need to do is instantiate a resource object and make a method call on it and Blurb will do the rest.
+
+For example, to use the keywords resource object:
+
+```ruby
+blurb_instance = Blurb::Keyword.new()
+```
+
+Optionally, you may pass in a set of account credentials to override the default API keys and tokens
+
+```ruby
+authorization_hash =  {
+  client_id: 'my_client_id',
+  profile_id: 'my_profile_id',
+  client_secret: 'client_secret',
+  refresh_token: 'refresh_token'
+}
+
+blurb_instance = Blurb::Keyword.new(authorization_hash)
+```
 
 In calls that require 'campaign_type' as a parameter, you must pass in either 'sp' for sponsored products or 'hsa' for sponsored brands (formerly known as headline search ads).  
 
@@ -145,32 +164,37 @@ Blurb::Profile.list()
 ```
 
 ### Campaigns
+
+```ruby
+campaign_instance = Blurb::Campaign.new
+```
+
 List campaigns
 
 ```ruby
-Blurb::Campaign.list(campaign_type)
+campaign_instance.list(campaign_type)
 ```
 or
 ```ruby
-Blurb::Campaign.list_extended(campaign_type)
+campaign_instance.list_extended(campaign_type)
 ```
 Note that the extended call returns the complete set of campaign fields (including serving status and other read-only fields), but is less efficient.
 
 Get a campaign
 
 ```ruby
-Blurb::Campaign.retrieve(campaign_id, campaign_type)
+campaign_instance.retrieve(campaign_id, campaign_type)
 ```
 or
 ```ruby
-Blurb::Campaign.retrieve_extended(campaign_id, campaign_type)
+campaign_instance.retrieve_extended(campaign_id, campaign_type)
 ```
 Note that the extended call returns the complete set of campaign fields (including serving status and other read-only fields), but is less efficient.
 
 Create a campaign
 
 ```ruby
-Blurb::Campaign.create(campaign_type, {
+campaign_instance.create(campaign_type, {
   "name" => "test",
   "state" => "enabled",
   "dailyBudget" => 10,
@@ -181,11 +205,70 @@ Blurb::Campaign.create(campaign_type, {
 
 Note: Sponsored Brands cannot be created through the Amazon Advertising API and must be added through the user interface.  The create call only works for Sponsored Products.
 
+### Keywords
+
+```ruby
+keyword_instance = Blurb::Keyword.new
+```
+
+List keywords
+
+```ruby
+keyword_instance.list(campaign_type)
+```
+or
+```ruby
+keyword_instance.list_extended(campaign_type)
+```
+
+Get a keyword
+
+```ruby
+keyword_instance.retrieve(campaign_id, campaign_type)
+```
+or
+```ruby
+keyword_instance.retrieve_extended(campaign_id, campaign_type)
+```
+
+Create a keyword
+
+```ruby
+keyword_instance.create(campaign_type, {
+  "campaignId" => "1234",
+  "adGroupId" => "5678",
+  "keywordText" => 'keyword',
+  "matchType" => 'broad',
+  "state" => "enabled"
+  "bid" => 0.1
+})
+```
+
+Bulk update keywords
+
+```ruby
+updates = [
+  {
+    "keywordId" => "1234",
+    "bid" => 0.1
+  },
+  {
+    "keywordId" => "2345",
+    "bid" => 0.3
+  }
+]
+keyword_instance.update(campaign_type, updates)
+```
+
 ### Reports
+```ruby
+report_instance = Blurb::Report.new
+```
+
 Request a report
 
 ```ruby
-payload_response = Blurb::Report.create({
+payload_response = report_instance.create({
   "campaignType" => Blurb::Report::SPONSORED_PRODUCTS,
   "recordType" => Blurb::Report::KEYWORDS,
   "reportDate" => (Time.now - 2592000).strftime('%Y%m%d'),
@@ -215,20 +298,24 @@ Blurb::Report::SPONSORED_BRANDS
 Check report status
 
 ```ruby
-Blurb::Report.status(report_id)
+report_instance.status(report_id)
 ```
 
 Download report file content
 
 ```ruby
-Blurb::Report.download(report_location_url)
+report_instance.download(report_location_url)
 ```
 
 ### Snapshots
+```ruby
+snapshot_instance = Blurb::Snapshot.new
+```
+
 Request a snapshot
 
 ```ruby
-payload_response = Blurb::Snapshot.create({
+payload_response = snapshot_instance.create({
   "recordType" => Blurb::Snapshot::KEYWORDS,
   "campaignType" => Blurb::Snapshot::SPONSORED_PRODUCTS,
   "stateFilter" => "enabled,paused,archived"
@@ -257,20 +344,24 @@ Blurb::Report::SPONSORED_BRANDS
 Check snapshot status
 
 ```ruby
-Blurb::Snapshot.status(snapshot_id)
+snapshot_instance.status(snapshot_id)
 ```
 
 Download snapshot file content
 
 ```ruby
-Blurb::Snapshot.download(snapshot_location_url)
+snapshot_instance.download(snapshot_location_url)
 ```
 
 ### Suggested Keywords
+```ruby
+suggested_keyword_instance = Blurb::SuggestedKeyword.new
+```
+
 Suggestions by ASIN
 
 ```ruby
-Blurb::SuggestedKeyword.asin_suggestions({
+suggested_keyword_instance.asin_suggestions({
   "asinValue" => "B0006HUJJO"
 })
 ```
@@ -278,7 +369,7 @@ Blurb::SuggestedKeyword.asin_suggestions({
 Suggestions for a list of ASIN's
 
 ```ruby
-Blurb::SuggestedKeyword.bulk_asin_suggestions({
+suggested_keyword_instance.bulk_asin_suggestions({
   "asins" => ["B0006HUJJO","B0042SWOHI"]
 })
 ```

data/lib/blurb.rb

@@ -10,6 +10,8 @@ require "blurb/profile"
 require "blurb/report"
 require "blurb/snapshot"
 require "blurb/suggested_keyword"
+require "blurb/keyword"
+require "blurb/ad_group"
 
 module Blurb
 

data/lib/blurb/ad_group.rb

@@ -0,0 +1,40 @@
+module Blurb
+  class AdGroup < BaseResource
+
+    URL_PARAMS = ['startIndex', 'campaignType', 'count', 'matchTypeFilter', 'name', 'state', 'campaignIdFilter', 'adGroupIdFilter']
+
+    def retrieve(keyword_id, campaign_type)
+      raise ArgumentError.new("adGroups interface is only supported for Sponsored Products") unless campaign_type == SPONSORED_PRODUCTS
+      get_request("/v2/#{campaign_type}/adGroups/#{keyword_id}")
+    end
+
+    def retrieve_extended(keyword_id, campaign_type)
+      raise ArgumentError.new("adGroups interface is only supported for Sponsored Products") unless campaign_type == SPONSORED_PRODUCTS
+      get_request("/v2/#{campaign_type}/adGroups/extended/#{keyword_id}")
+    end
+
+    def list(campaign_type, params = {}, opts = {})
+      raise ArgumentError.new("adGroups interface is only supported for Sponsored Products") unless campaign_type == SPONSORED_PRODUCTS
+      get_request("/v2/#{campaign_type}/adGroups?#{setup_url_params(params, URL_PARAMS)}")
+    end
+
+    def list_extended(campaign_type, params = {}, opts = {})
+      raise ArgumentError.new("adGroups interface is only supported for Sponsored Products") unless campaign_type == SPONSORED_PRODUCTS
+      get_request("/v2/#{campaign_type}/adGroups/extended?#{setup_url_params(params, URL_PARAMS)}")
+    end
+
+    def create(campaign_type, params = {}, opts = {})
+      # required argument checks
+      if !params["name"] && !params["targetingType"] && !params["state"] && !params["dailyBudget"] && !params["startDate"]
+        raise ArgumentError.new("params hash must contain name, targetingType, state, dailyBudget and startDate")
+      end
+      raise ArgumentError.new("Only sponsored product adGroups can be created through the api.  Sponsored Brands adGroups must be created through the user interface") unless campaign_type == SPONSORED_PRODUCTS
+
+      post_request("/v2/#{campaign_type}/adGroups", [params])
+    end
+
+    def delete(keyword_id)
+      delete_request("/v2/adGroups/#{keyword_id}")
+    end
+  end
+end

data/lib/blurb/base_resource.rb

@@ -7,6 +7,9 @@ module Blurb
     TEST_API_URL = "https://advertising-api-test.amazon.com"
     EU_API_URL = "https://advertising-api-eu.amazon.com"
 
+    SPONSORED_PRODUCTS = "sp"
+    SPONSORED_BRANDS = "hsa"
+
     def initialize(account=Blurb.default_account)
       @client_secret = account[:client_secret]
       @client_id = account[:client_id]
@@ -83,25 +86,13 @@ module Blurb
     end
 
     def get_request(api_path, opts = {})
-      access_token = retrieve_token()
-
       url = "#{active_api_url}#{api_path}"
       url = api_path if opts[:full_path]
 
-      headers_hash = {
-        "Authorization" => "Bearer #{access_token['access_token']}",
-        "Content-Type" => "application/json",
-        "Amazon-Advertising-API-Scope" => @profile_id,
-        "Amazon-Advertising-API-ClientId" => @client_id
-      }
-
-      headers_hash["Content-Encoding"] = "gzip" if opts[:gzip]
-      # headers_hash.delete("Authorization") if opts[:no_token]
-
       request_config = {
           method: :get,
           url: url,
-          headers: headers_hash,
+          headers: headers_hash(opts),
           max_redirects: 0
         }
 
@@ -109,33 +100,28 @@ module Blurb
     end
 
     def post_request(api_path, payload)
-      access_token = retrieve_token()
-
       request_config = {
           method: :post,
           url: "#{active_api_url}#{api_path}",
           payload: payload.to_json,
-          headers: {
-            "Authorization" => "Bearer #{access_token['access_token']}",
-            "Content-Type" => "application/json",
-            "Amazon-Advertising-API-Scope" => @profile_id.to_i,
-            "Amazon-Advertising-API-ClientId" => @client_id
-          }
+          headers: headers_hash
         }
 
       return make_request(request_config)
     end
 
-    def delete_request(api_path)
-      access_token = retrieve_token()
+    def put_request(api_path, payload)
+      request_config = {
+          method: :put,
+          url: "#{active_api_url}#{api_path}",
+          payload: payload.to_json,
+          headers: headers_hash
+        }
 
-      headers_hash = {
-        "Authorization" => "Bearer #{access_token['access_token']}",
-        "Content-Type" => "application/json",
-        "Amazon-Advertising-API-Scope" => @profile_id,
-        "Amazon-Advertising-API-ClientId" => @client_id
-      }
+      return make_request(request_config)
+    end
 
+    def delete_request(api_path)
       request_config = {
           method: :delete,
           url: "#{active_api_url}#{api_path}",
@@ -162,5 +148,25 @@ module Blurb
       response = JSON.parse(resp) if resp
       return response
     end
+
+    def headers_hash(opts = {})
+      access_token = retrieve_token()
+
+      headers_hash = {
+        "Authorization" => "Bearer #{access_token['access_token']}",
+        "Content-Type" => "application/json",
+        "Amazon-Advertising-API-Scope" => @profile_id,
+        "Amazon-Advertising-API-ClientId" => @client_id
+      }
+
+      headers_hash["Content-Encoding"] = "gzip" if opts[:gzip]
+
+      return headers_hash
+    end
+
+    def setup_url_params(params, whitelist)
+      whitelisted_params = params.select { |k,v| whitelist.include?(k) }
+      return URI.encode_www_form(whitelisted_params)
+    end
   end
 end

data/lib/blurb/campaign.rb

@@ -1,7 +1,7 @@
 module Blurb
   class Campaign < BaseResource
-    SPONSORED_PRODUCTS = "sp"
-    SPONSORED_BRANDS = "hsa"
+
+    URL_PARAMS = ['count', 'stateFilter', 'startIndex', 'name', 'campaignIdFilter']
 
     def retrieve(campaign_id, campaign_type)
       get_request("/v2/#{campaign_type}/campaigns/#{campaign_id}")
@@ -13,12 +13,12 @@ module Blurb
     end
 
     def list(campaign_type, params = {}, opts = {})
-      get_request("/v2/#{campaign_type}/campaigns?#{setup_url_params(params)}")
+      get_request("/v2/#{campaign_type}/campaigns?#{setup_url_params(params, URL_PARAMS)}")
     end
 
     def list_extended(campaign_type, params = {}, opts = {})
       raise ArgumentError.new("Extended campaigns interface is only supported for Sponsored Products") unless campaign_type == SPONSORED_PRODUCTS
-      get_request("/v2/#{campaign_type}/campaigns/extended?#{setup_url_params(params)}")
+      get_request("/v2/#{campaign_type}/campaigns/extended?#{setup_url_params(params, URL_PARAMS)}")
     end
 
     def create(campaign_type, params = {}, opts = {})
@@ -34,34 +34,5 @@ module Blurb
     def delete(campaign_id)
       delete_request("/v2/campaigns/#{campaign_id}")
     end
-
-    private
-
-    def setup_url_params(params)
-      url_params = ""
-      url_params = "startIndex=#{params['startIndex']}" if params['startIndex']
-
-      if params['count']
-        url_params += "&" if url_params.size > 0
-        url_params += "count=#{params['count']}"
-      end
-
-      if params['stateFilter']
-        url_params += "&" if url_params.size > 0
-        url_params += "stateFilter=#{params['stateFilter']}"
-      end
-
-      if params['name']
-        url_params += "&" if url_params.size > 0
-        url_params += "name=#{params['name']}"
-      end
-
-      if params['campaignIdFilter']
-        url_params += "&" if url_params.size > 0
-        url_params += "campaignIdFilter=#{params['campaignIdFilter']}"
-      end
-
-      return url_params
-    end
   end
 end

data/lib/blurb/keyword.rb

@@ -0,0 +1,51 @@
+module Blurb
+  class Keyword < BaseResource
+    URL_PARAMS = ['startIndex', 'count', 'matchTypeFilter', 'keywordText', 'state', 'campaignIdFilter', 'adGroupIdFilter']
+
+    def retrieve(keyword_id, campaign_type)
+      get_request("/v2/#{campaign_type}/keywords/#{keyword_id}")
+    end
+
+    def retrieve_extended(keyword_id, campaign_type)
+      raise ArgumentError.new("Extended keywords interface is only supported for Sponsored Products") unless campaign_type == SPONSORED_PRODUCTS
+      get_request("/v2/#{campaign_type}/keywords/extended/#{keyword_id}")
+    end
+
+    def list(campaign_type, params = {}, opts = {})
+      get_request("/v2/#{campaign_type}/keywords?#{setup_url_params(params, URL_PARAMS)}")
+    end
+
+    def list_extended(campaign_type, params = {}, opts = {})
+      raise ArgumentError.new("Extended keywords interface is only supported for Sponsored Products") unless campaign_type == SPONSORED_PRODUCTS
+      get_request("/v2/#{campaign_type}/keywords/extended?#{setup_url_params(params, URL_PARAMS)}")
+    end
+
+    def update(campaign_type, payload, opts = {})
+      raise ArgumentError.new("Extended keywords interface is only supported for Sponsored Products") unless campaign_type == SPONSORED_PRODUCTS
+      payload = [payload] unless payload.class == Array
+
+      # The Amazon Advertising API only accepts bulk changes of up to 1000 keywords
+      results = []
+      payloads = payload.each_slice(1000).to_a
+      payloads.each do |p|
+        results << put_request("/v2/#{campaign_type}/keywords", p)
+      end
+
+      return results.flatten
+    end
+
+    def create(campaign_type, params = {}, opts = {})
+      # required argument checks
+      if !params["campaignId"] && !params["adGroupId"] && !params["keywordText"] && !params["matchType"] && !params["state"]
+        raise ArgumentError.new("params hash must contain campaignId, adGroupId, keywordText, matchType and state")
+      end
+      raise ArgumentError.new("Only sponsored product keywords can be created through the api.  Sponsored Brands keywords must be created through the user interface") unless campaign_type == SPONSORED_PRODUCTS
+
+      post_request("/v2/#{campaign_type}/keywords", [params])
+    end
+
+    def delete(keyword_id)
+      delete_request("/v2/keywords/#{keyword_id}")
+    end
+  end
+end

data/lib/blurb/report.rb

@@ -6,8 +6,6 @@ module Blurb
     PRODUCT_ADS = "productAds"
     ASINS = "asins"
     TARGETS = "targets"
-    SPONSORED_PRODUCTS = "sp"
-    SPONSORED_BRANDS = "hsa"
 
     def create(params = {}, opts = {})
       # required argument checks

data/lib/blurb/snapshot.rb

@@ -7,8 +7,6 @@ module Blurb
     CAMPAIGN_NEGATIVE_KEYWORDS = "campaignNegativeKeywords"
     PRODUCT_ADS = "productAds"
     TARGETS = "targets"
-    SPONSORED_PRODUCTS = "sp"
-    SPONSORED_BRANDS = "hsa"
 
     def create(params = {}, opts = {})
       # required argument checks

data/lib/blurb/suggested_keyword.rb

@@ -1,24 +1,26 @@
 module Blurb
   class SuggestedKeyword < BaseResource
+    URL_PARAMS = ['maxNumSuggestions', 'adStateFilter', 'suggestBids']
+
     def ad_group_suggestions(params = {}, opts = {})
       # required argument checks
       raise ArgumentError.new("params hash must contain an adGroupId") unless params["adGroupId"]
 
-      get_request("/v2/adGroups/#{params["adGroupId"]}/suggested/keywords?#{setup_url_params(params)}")
+      get_request("/v2/adGroups/#{params["adGroupId"]}/suggested/keywords?#{setup_url_params(params, URL_PARAMS)}")
     end
 
     def ad_group_extended_suggestions(params = {}, opts = {})
       # required argument checks
       raise ArgumentError.new("params hash must contain an adGroupId") unless params["adGroupId"]
 
-      get_request("/v2/adGroups/#{params["adGroupId"]}/suggested/keywords/extended?#{setup_url_params(params)}")
+      get_request("/v2/adGroups/#{params["adGroupId"]}/suggested/keywords/extended?#{setup_url_params(params, URL_PARAMS)}")
     end
 
     def asin_suggestions(params = {}, opts = {})
       # required argument checks
       raise ArgumentError.new("params hash must contain an asinValue") unless params["asinValue"]
 
-      get_request("/v2/asins/#{params["asinValue"]}/suggested/keywords?#{setup_url_params(params)}")
+      get_request("/v2/asins/#{params["asinValue"]}/suggested/keywords?#{setup_url_params(params, URL_PARAMS)}")
     end
 
     def bulk_asin_suggestions(params = {}, opts = {})
@@ -33,24 +35,5 @@ module Blurb
         "maxNumSuggestions" => maxNumSuggestions
       })
     end
-
-    private
-
-    def setup_url_params(params)
-      url_params = ""
-      url_params = "maxNumSuggestions=#{params['maxNumSuggestions']}" if params['maxNumSuggestions']
-
-      if params['adStateFilter']
-        url_params += "&" if url_params.size > 0
-        url_params += "adStateFilter=#{params['adStateFilter']}"
-      end
-
-      if params['suggestBids']
-        url_params += "&" if url_params.size > 0
-        url_params += "suggestBids=#{params['suggestBids']}"
-      end
-
-      return url_params
-    end
   end
 end

data/lib/blurb/version.rb

@@ -1,3 +1,3 @@
 module Blurb
-  VERSION = "0.3.0".freeze
+  VERSION = "0.3.1".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: blurb
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - dlbunker
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-03-21 00:00:00.000000000 Z
+date: 2019-04-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -115,9 +115,11 @@ files:
 - bin/setup
 - blurb.gemspec
 - lib/blurb.rb
+- lib/blurb/ad_group.rb
 - lib/blurb/base_resource.rb
 - lib/blurb/bid_recommendation.rb
 - lib/blurb/campaign.rb
+- lib/blurb/keyword.rb
 - lib/blurb/profile.rb
 - lib/blurb/report.rb
 - lib/blurb/snapshot.rb