ebay-ruby 0.3.3 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f75e5710d5dc86f3f0a83ec943b90ec3b5aa318be568163accba7ce326adb2a2
-  data.tar.gz: 223f627ad8321defd29a21fce8e1083eecb3b8447b5962d448ad51152d9b0dc1
+  metadata.gz: 0fd16f623556b875afb1ecb939fbd296ce5b476ba452dd6180fa52bac6085bc4
+  data.tar.gz: b4d55cba32a9a53878f649c3dbcd2d8ee0649fa381a312d809ab5c11b68a19ce
 SHA512:
-  metadata.gz: 197bc765789a721d8f678dbe0f5ed931c01743cff6699957d02a122ce6c61d73bab3046c6a15c5eb4c8ff4ebde04bd3690183fd41be8c512264393583121423b
-  data.tar.gz: 29bb107067f9802f8988eb4c08f991715c7de01b699694e3b38f762f61d65a562ca8c88fe9083c63e8668e6ab960e81de1b880427f582102fa3df2ca5174f3eb
+  metadata.gz: f672edffb9231c9a573adf8c1291bf267793c62be549b47b52c3457fac118218d10b1e1d3bc7a733dab0eb7ee3c7dd50beb59e2c331ca3fd2e98f177a784b498
+  data.tar.gz: f32cfa29cf7ec5fdc79683140debd33ee7830e5968e8aea489dbdb6dc34bb274859812a1a1f49a7e9557ccc6b1841b435172843948a8932d8d327c1a1f948a9f

data/README.md

@@ -2,81 +2,126 @@
 
 [![Build](https://github.com/hakanensari/ebay-ruby/workflows/build/badge.svg)](https://github.com/hakanensari/ebay-ruby/actions)
 
-A Ruby wrapper to the [eBay APIs]
+This library provides a wrapper to the [eBay APIs].
 
-## Usage
+## Getting started
+
+You can instantiate API requests using shorthand class methods defined on `Ebay`.
+
+```ruby
+Ebay.finding # returns a new Ebay::Finding instance
+```
 
-### Buy APIs
+### Keys
 
-Retrieve purchasable items, check out, then track orders without visiting the eBay site.
+eBay APIs require [developer keys].
 
-#### [Browse API]
+You can provide these globally with the environment variables `EBAY_APP_ID`, `EBAY_DEV_ID`, and `EBAY_CERT_ID`.
 
-Using the Browse API, you can create a rich selection of items for your buyers to browse with keyword and category searches. You can also provides the ability to eBay members to add items and change the quantity of an item in their eBay shopping cart as well as view the contents of their eBay cart.
+If you prefer not to use environment variables, you can provide your keys globally with:
 
 ```ruby
-require 'ebay/browse'
-require 'ebay/oauth/client_credentials_grant'
+Ebay.configure do |config|
+  config.app_id = 'YOUR APP ID'
+  config.dev_id = 'YOUR DEV ID'
+  config.cert_id = 'YOUR CERT ID'
+end
+```
 
-access_token = Oauth::ClientCredentialsGrant.new.mint_access_token
-request = Ebay::Browse.new(campaign_id: '123',
-                           country: 'US',
-                           zip: '19406',
-                           access_token: access_token)
-response = @request.search(q: 'iphone')
+Finally, you can provide your keys individually to the request when instantiating it. This is what you will want to do if you are using multiple sets of credentials.
 
-JSON.parse(response)
+Please note that each API names keys differently.
+
+```ruby
+request = Ebay.finding(security_appname: 'YOUR APP ID')
 ```
 
-### Traditional Searching APIs
+In the examples below, we will assume we are providing our keys with environment variables.
 
-Search eBay; build search and browse experiences.
+### Parsing a response
 
-#### [Finding API]
+The eBay APIs return responses in XML or JSON format.
 
-The Finding API provides programmatic access to the next generation search capabilities on the eBay platform. It lets you search and browse for items listed on eBay and provides useful metadata to refine searches and enhance the search experience.
+You can override the default format of an API when instantiating the request.
 
 ```ruby
-require 'ebay/finding'
+require 'json'
 
-request = Ebay::Finding.new(response_data_format: 'JSON')
+### the Finding API returns XML by default
+request = Ebay.finding(response_data_format: 'JSON')
 response = request.find_items_by_keywords('iphone')
 
 JSON.parse(response)
 ```
 
-### Traditional Shopping/Buying APIs
-
-Retrieve public items and user data to create shopping and marketing applications.
+## Usage
+### [Browse API]
 
-#### [Shopping API]
+The Browse API allows your buyers to search eBay items by keyword and category. It also allows them to view and add items to their eBay shopping cart. The Browse API defaults to the eBay US marketplace but may be set during initialisation. The list of available marketplaces is [here](https://developer.ebay.com/api-docs/static/rest-request-components.html#marketpl).
 
-The eBay Shopping API makes it easy to search for things on eBay.
+**Note** The marketplace value needs to use an underscore between EBAY and the country code.  The Finding and Merchandising APIs use a hyphen.
 
 ```ruby
-require 'ebay/shopping'
+require 'ebay/browse'
+require 'ebay/oauth/client_credentials_grant'
 
-request = Ebay::Shopping.new(response_encoding: 'JSON')
-response = request.find_products('QueryKeywords' => 'tolkien')
+access_token = Oauth::ClientCredentialsGrant.new.mint_access_token
+request = Ebay.browse(campaign_id: '123', country: 'US', zip: '19406',
+                      access_token: access_token, market_id: 'EBAY_US')
+response = request.search(q: 'iphone')
+```
 
-JSON.parse(response)
+### [Finding API]
+
+The Finding API lets you search and browse for items listed on eBay and provides useful metadata to refine searches.
+
+```ruby
+require 'ebay/finding'
+
+request = Ebay.finding
+response = request.find_items_by_keywords('iphone')
 ```
 
-#### [Merchandising API]
+### [Merchandising API]
 
-The Merchandising API provides item and product recommendations that can be used to cross-sell and up-sell eBay items to buyers.
+The Merchandising API retrieves information about products or item listings on eBay to help you sell more merchandise to eBay buyers.
 
 ```ruby
 require 'ebay/merchandising'
 
-request = Ebay::Merchandising.new(response_data_format: 'JSON')
+request = Ebay::Merchandising.new
 response = request.get_most_watched_items
+```
 
-JSON.parse(response)
+### [Shopping API]
+
+The eBay Shopping API makes it easy to search for things on eBay.
+
+```ruby
+require 'ebay/shopping'
+
+request = Ebay::Shopping.new
+response = request.find_products('QueryKeywords' => 'tolkien')
+```
+
+### Market Place
+eBay has country bsaed marketplaces ( listed [here](https://developer.ebay.com/api-docs/static/rest-request-components.html#marketpl) ).  By default, the eBay gem queries the US Marketplace.  To change the marketplace, set the marketplace on the request object.
+
+**Note** For the Browse API, the marketplace value needs to use an underscore between EBAY and the country code (EBAY_AU).  The Finding and Merchandising APIs require a hyphen between EBAY and the country code ( EBAY-AU )
+
+## Development
+
+To write requests and responses to a logger, use the logging feature:
+
+```ruby
+require 'logger'
+
+request = request.use(logging: {logger: Logger.new(STDOUT)})
 ```
 
 [eBay APIs]: https://developer.ebay.com/docs
+[developer keys]: https://developer.ebay.com/my/keys
 [Browse API]: https://developer.ebay.com/api-docs/buy/browse/static/overview.html
 [Finding API]: https://developer.ebay.com/Devzone/finding/Concepts/FindingAPIGuide.html
-[Shopping API]: https://developer.ebay.com/Devzone/shopping/docs/Concepts/ShoppingAPIGuide.html
 [Merchandising API]: https://developer.ebay.com/Devzone/merchandising/docs/Concepts/merchandisingAPIGuide.html
+[Shopping API]: https://developer.ebay.com/Devzone/shopping/docs/Concepts/ShoppingAPIGuide.html

data/lib/ebay/browse.rb

@@ -5,11 +5,15 @@ require 'base64'
 require 'ebay/config'
 require 'ebay/requestable'
 
+# Ruby wrapper to the eBay APIs
 module Ebay
-  # Using the Browse API, you can create a rich selection of items for your
-  # buyers to browse with keyword and category searches. It also provides the
-  # ability to eBay members to add items and change the quantity of an item in
-  # their eBay shopping cart as well as view the contents of their eBay cart.
+  # Returns a {Ebay::Browse#initialize Browse API} instance
+  def self.browse(**params)
+    Browse.new(**params)
+  end
+
+  # The Browse API allows your buyers to search eBay items by keyword and category. It also allows them to view and add
+  # items to their eBay shopping cart.
   #
   # @see https://developer.ebay.com/api-docs/buy/browse/overview.html
   class Browse
@@ -17,6 +21,9 @@ module Ebay
 
     self.endpoint = 'https://api.ebay.com/buy/browse/v1'
 
+    # @return [String]
+    attr_reader :access_token
+
     # @return [String]
     attr_reader :campaign_id
 
@@ -29,27 +36,27 @@ module Ebay
     # @return [String,nil]
     attr_reader :zip
 
-    # @return [String] the application access token
-    def access_token
-      @access_token ||= mint_access_token
-    end
+    # @return [String,nil]
+    attr_reader :market_id
 
     # Returns a Browse API request instance
     #
+    # @param [String] access_token
     # @param [String] campaign_id
     # @param [String] reference_id
-    # @param [String] access_token
-    def initialize(campaign_id:, reference_id: nil, country: nil, zip: nil,
-                   access_token: nil)
+    # @param [String] country
+    # @param [String] zip
+    # @param [String] market_id
+    def initialize(access_token:, campaign_id:, reference_id: nil, country: nil, zip: nil, market_id: 'EBAY_US')
       @campaign_id = campaign_id
       @reference_id = reference_id
       @country = country
       @zip = zip
       @access_token = access_token
+      @market_id = market_id
     end
 
-    # Searches for eBay items by various query parameters and retrieves
-    # summaries of the item
+    # Searches for eBay items by various query parameters and retrieves summaries of the item
     #
     # @param [Hash] params
     # @return [HTTP::Response]
@@ -115,8 +122,7 @@ module Ebay
     def check_compatibility(item_id, marketplace_id, compatibility_properties)
       url = build_url('item', item_id, 'check_compatibility')
       headers = build_headers
-      headers.update('X-EBAY-C-MARKETPLACE-ID' => marketplace_id,
-                     'CONTENT-TYPE' => 'application/json')
+      headers.update('X-EBAY-C-MARKETPLACE-ID' => marketplace_id, 'CONTENT-TYPE' => 'application/json')
       body = JSON.dump('compatibilityProperties' => compatibility_properties)
 
       http.headers(headers).post(url, body: body)
@@ -146,20 +152,18 @@ module Ebay
 
     def build_headers
       { 'AUTHORIZATION' => "Bearer #{access_token}",
+        'X-EBAY-C-MARKETPLACE-ID' => market_id,
         'X-EBAY-C-ENDUSERCTX' => build_ebay_enduser_context }
     end
 
     def build_ebay_enduser_context
       { 'affiliateCampaignId' => campaign_id,
         'affiliateReferenceId' => reference_id,
-        'contextualLocation' => build_contextual_location }
-        .compact.map { |kv| kv.join('=') }.join(',')
+        'contextualLocation' => build_contextual_location }.compact.map { |kv| kv.join('=') }.join(',')
     end
 
     def build_contextual_location
-      string = { 'country' => country, 'zip' => zip }
-               .compact.map { |kv| kv.join('=') }.join(',')
-
+      string = { 'country' => country, 'zip' => zip }.compact.map { |kv| kv.join('=') }.join(',')
       CGI.escape(string) if string
     end
   end

data/lib/ebay/config.rb

@@ -8,7 +8,7 @@ module Ebay
     yield Config
   end
 
-  # Stores credentials for accessing the eBay APIs
+  # Configures credentials for accessing the eBay APIs
   module Config
     class << self
       # @!attribute [rw] app_id

data/lib/ebay/finding.rb

@@ -3,8 +3,14 @@
 require 'ebay/config'
 require 'ebay/requestable'
 
+# Ruby wrapper to the eBay APIs
 module Ebay
-  # The Finding API lets you search for and browse items listed on eBay and
+  # Returns a {Ebay::Finding#initialize Finding API} instance
+  def self.finding(**params)
+    Finding.new(**params)
+  end
+
+  # The Finding API lets you search and browse for items listed on eBay and
   # provides useful metadata to refine searches.
   #
   # @see https://developer.ebay.com/Devzone/finding/Concepts/MakingACall.html
@@ -137,7 +143,7 @@ module Ebay
                  'SECURITY-APPNAME' => security_appname,
                  'SERVICE-VERSION' => service_version }.update(payload).compact
 
-      http.get(endpoint, params: params)
+      http.headers(headers).get(endpoint, params: params)
     end
   end
 end

data/lib/ebay/merchandising.rb

@@ -3,7 +3,13 @@
 require 'ebay/config'
 require 'ebay/requestable'
 
+# Ruby wrapper to the eBay APIs
 module Ebay
+  # Returns a {Ebay::Merchandising#initialize Merchandising API} instance
+  def self.merchandising(**params)
+    Merchandising.new(**params)
+  end
+
   # Retrieves information about products or item listings on eBay to help you
   # sell more merchandise to eBay buyers
   #
@@ -84,7 +90,7 @@ module Ebay
                  'RESPONSE-DATA-FORMAT' => response_data_format,
                  'SERVICE-VERSION' => service_version }.compact
 
-      http.post(endpoint, params: params, body: JSON.dump(payload))
+      http.headers(headers).post(endpoint, params: params, body: JSON.dump(payload))
     end
   end
 end

data/lib/ebay/requestable.rb

@@ -18,6 +18,18 @@ module Ebay
     # @return [HTTP::Client]
     attr_writer :http
 
+    # @!attribute [r] headers
+    # @return [Hash]
+    attr_accessor :headers
+
+    # Sets the eBay Market
+    #
+    # @param [String]
+    def market_id=(market_id)
+      @headers ||= {}
+      @headers['X-EBAY-SOA-GLOBAL-ID'] = market_id
+    end
+
     # @!attribute [r] http
     # @return [HTTP::Client]
     def http
@@ -37,5 +49,33 @@ module Ebay
       @endpoint = endpoint.sub('ebay', 'sandbox.ebay')
       self
     end
+
+    # Flags request as persistent
+    #
+    # @param [Integer] timeout
+    # @return [self]
+    def persistent(timeout: 5)
+      self.http = http.persistent(endpoint, timeout: timeout)
+      self
+    end
+
+    # @!method use(*features)
+    #   Turns on {https://github.com/httprb/http HTTP} features
+    #
+    #   @param features
+    #   @return [self]
+    #
+    # @!method via(*proxy)
+    #   Makes a request through an HTTP proxy
+    #
+    #   @param [Array] proxy
+    #   @raise [HTTP::Request::Error] if HTTP proxy is invalid
+    #   @return [self]
+    %i[timeout via through use].each do |method_name|
+      define_method(method_name) do |*args, &block|
+        self.http = http.send(method_name, *args, &block)
+        self
+      end
+    end
   end
 end

data/lib/ebay/shopping.rb

@@ -3,7 +3,13 @@
 require 'ebay/config'
 require 'ebay/requestable'
 
+# Ruby wrapper to the eBay APIs
 module Ebay
+  # Returns a {Ebay::Shopping#initialize Shopping API} instance
+  def self.shopping(**params)
+    Shopping.new(**params)
+  end
+
   # The eBay Shopping API makes it easy to search for things on eBay.
   #
   # @see https://developer.ebay.com/Devzone/shopping/docs/Concepts/ShoppingAPI_FormatOverview.html
@@ -96,7 +102,7 @@ module Ebay
     #   @return [HTTP::Response]
     def get_item_status(*item_ids)
       payload = item_ids.last.is_a?(Hash) ? item_ids.pop : {}
-      payload = payload.merge('ItemID' => item_ids.join(','))
+      payload = payload.merge('ItemID' => item_ids.map(&:to_s))
       request('GetItemStatus', payload)
     end
 
@@ -108,7 +114,7 @@ module Ebay
     #   @return [HTTP::Response]
     def get_multiple_items(*item_ids)
       payload = item_ids.last.is_a?(Hash) ? item_ids.pop : {}
-      payload = payload.merge('ItemID' => item_ids.join(','))
+      payload = payload.merge('ItemID' => item_ids.map(&:to_s))
 
       request('GetMultipleItems', payload)
     end
@@ -157,7 +163,7 @@ module Ebay
                  'trackingid' => tracking_id,
                  'trackingpartnercode' => tracking_partner_code }.compact
 
-      http.post(endpoint, params: params, body: JSON.dump(payload))
+      http.headers(headers).post(endpoint, params: params, body: JSON.dump(payload))
     end
   end
 end

data/lib/ebay/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ebay
-  VERSION = '0.3.3'
+  VERSION = '0.4.1'
 end

metadata

@@ -1,29 +1,35 @@
 --- !ruby/object:Gem::Specification
 name: ebay-ruby
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.4.1
 platform: ruby
 authors:
 - Hakan Ensari
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-03-18 00:00:00.000000000 Z
+date: 2021-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6.0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -80,6 +86,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: vcr
   requirement: !ruby/object:Gem::Requirement
@@ -122,7 +156,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: 
+description:
 email:
 - me@hakanensari.com
 executables: []
@@ -145,7 +179,7 @@ homepage: https://github.com/hakanensari/ebay-ruby
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -153,15 +187,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.4'
+      version: '2.6'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
-signing_key: 
+rubygems_version: 3.2.22
+signing_key:
 specification_version: 4
 summary: Ruby wrapper to the eBay APIs
 test_files: []