ebay-ruby 0.2.0 → 0.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17b513ab5b0d12b5a396988acca1210f323333eb0f6108d5f1e3382542f4509d
-  data.tar.gz: 5dd731e4430e1e5975928c257d8254e9cadc0b750014c1adc362d34de6b83df1
+  metadata.gz: bbadae6120cf8748d6f33d847c9746199717facc4734db1d81719a37393886bc
+  data.tar.gz: d457466d75675c9fb698d9fa8feac2bb773d4a89be43f698ab22598bada96839
 SHA512:
-  metadata.gz: 4a6d11bf31a67a33674d8a8a6823ce48839931d12f3f2224a53faff81d0bb58cd266fda61532f33db8ea6ac2d9baadebe74363d4aace1370e0b25bcde0414540
-  data.tar.gz: fb5facaa0b53126fb343707dfc93fee0a9a49cf45e280a1d95f537e6967d0c833f528e997651c2d6eed3a11656a426b20786d08389141e09880f4d957658261e
+  metadata.gz: 98aea0105ee22960dece81289809e60048afbc5a68bd17bbf3ef2d54c6f0c139b5551b0f0e04293d49d471a2bd7d244d285f8fcc76a8f8b35eb5eaef05b6900c
+  data.tar.gz: 769e216aa765b9850aa3192e82668bc9a79bc69e47b34e54799ecb897b4bbbb38a3750d237a841ce3f3abc2556b9b0f77017801ea97229bb3521053f52354d7e

data/LICENSE

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) Hakan Ensari
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,16 +1,121 @@
 # ebay-ruby
 
-A wrapper to the eBay APIs in Ruby
+[![Build](https://github.com/hakanensari/ebay-ruby/workflows/build/badge.svg)](https://github.com/hakanensari/ebay-ruby/actions)
+
+This library provides a wrapper to the [eBay APIs].
+
+## Getting started
+
+You can instantiate API requests using shorthand class methods defined on `Ebay`.
+
+```ruby
+Ebay.finding # returns a new Ebay::Finding instance
+```
+
+### Keys
+
+eBay APIs require [developer keys].
+
+You can provide these globally with the environment variables `EBAY_APP_ID`, `EBAY_DEV_ID`, and `EBAY_CERT_ID`.
+
+If you prefer not to use environment variables, you can provide your keys globally with:
+
+```ruby
+Ebay.configure do |config|
+  config.app_id = 'YOUR APP ID'
+  config.dev_id = 'YOUR DEV ID'
+  config.cert_id = 'YOUR CERT ID'
+end
+```
+
+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.
+
+Please note that each API names keys differently.
+
+```ruby
+request = Ebay.finding(security_appname: 'YOUR APP ID')
+```
+
+In the examples below, we will assume we are providing our keys with environment variables.
+
+### Parsing a response
+
+The eBay APIs return responses in XML or JSON format.
+
+You can override the default format of an API when instantiating the request.
+
+```ruby
+require '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)
+```
+
+## Usage
+
+### [Browse 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.
+
+```ruby
+require 'ebay/browse'
+require 'ebay/oauth/client_credentials_grant'
+
+access_token = Oauth::ClientCredentialsGrant.new.mint_access_token
+request = Ebay.browse(campaign_id: '123', country: 'US', zip: '19406',
+                      access_token: access_token)
+response = request.search(q: 'iphone')
+```
+
+### [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'
 
-finding = Ebay::Finding.new
-params = {
-  'GLOBAL-ID'      => 'EBAY-US',
-  'OPERATION-NAME' => 'findItemsByKeywords',
-  'keywords'       => 'minimalism'
-}
-parser = finding.get(query: params)
-parser.parse
+request = Ebay.finding
+response = request.find_items_by_keywords('iphone')
+```
+
+### [Merchandising API]
+
+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 = request.get_most_watched_items
 ```
+
+### [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')
+```
+
+## 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
+[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-ruby.rb

@@ -1 +1,3 @@
+# frozen_string_literal: true
+
 require 'ebay'

data/lib/ebay.rb

@@ -1,12 +1,6 @@
-require 'ebay/config'
+# frozen_string_literal: true
+
+require 'ebay/browse'
 require 'ebay/finding'
 require 'ebay/merchandising'
-require 'ebay/product'
-require 'ebay/product_metadata'
 require 'ebay/shopping'
-
-module Ebay
-  def self.configure
-    yield Config
-  end
-end

data/lib/ebay/browse.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+require 'ebay/config'
+require 'ebay/requestable'
+
+# Ruby wrapper to the eBay APIs
+module Ebay
+  # 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
+    include Requestable
+
+    self.endpoint = 'https://api.ebay.com/buy/browse/v1'
+
+    # @return [String]
+    attr_reader :campaign_id
+
+    # @return [String,nil]
+    attr_reader :reference_id
+
+    # @return [String,nil]
+    attr_reader :country
+
+    # @return [String,nil]
+    attr_reader :zip
+
+    # @return [String] the application access token
+    def access_token
+      @access_token ||= mint_access_token
+    end
+
+    # Returns a Browse API request instance
+    #
+    # @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)
+      @campaign_id = campaign_id
+      @reference_id = reference_id
+      @country = country
+      @zip = zip
+      @access_token = access_token
+    end
+
+    # Searches for eBay items by various query parameters and retrieves summaries of the item
+    #
+    # @param [Hash] params
+    # @return [HTTP::Response]
+    def search(params = {})
+      url = build_url('item_summary', 'search')
+      http.headers(build_headers).get(url, params: params)
+    end
+
+    # Searches for eBay items based on a image and retrieves their summaries
+    #
+    # @param [File] image
+    # @param [Hash] params
+    # @return [HTTP::Response]
+    def search_by_image(image, params = {})
+      url = build_url('item_summary', 'search_by_image')
+      headers = build_headers.update('CONTENT-TYPE' => 'application/json')
+      encoded_string = Base64.encode64(image.read)
+      body = JSON.dump(image: encoded_string)
+
+      http.headers(headers).post(url, params: params, body: body)
+    end
+
+    # Retrieves the details of a specific item
+    #
+    # @param [String] item_id
+    # @param [Hash] params
+    # @return [HTTP::Response]
+    def get_item(item_id, params = {})
+      url = build_url('item', item_id)
+      params = params.merge(item_id: item_id)
+
+      http.headers(build_headers).get(url, params: params)
+    end
+
+    # Retrieves the details of a specific item using its legacy item ID
+    #
+    # @param [String] legacy_item_id
+    # @param [Hash] params
+    # @return [HTTP::Response]
+    def get_item_by_legacy_id(legacy_item_id, params = {})
+      url = build_url('item', 'get_item_by_legacy_id')
+      params = params.merge(legacy_item_id: legacy_item_id)
+
+      http.headers(build_headers).get(url, params: params)
+    end
+
+    # Retrieves the details of the individual items in an item group
+    #
+    # @param [String] item_group_id
+    # @return [HTTP::Response]
+    def get_items_by_item_group(item_group_id)
+      url = build_url('item', 'get_items_by_item_group')
+      params = { item_group_id: item_group_id }
+
+      http.headers(build_headers).get(url, params: params)
+    end
+
+    # Retrieves the details of the individual items in an item group
+    #
+    # @param [String] item_id
+    # @param [String] marketplace_id
+    # @return [HTTP::Response]
+    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')
+      body = JSON.dump('compatibilityProperties' => compatibility_properties)
+
+      http.headers(headers).post(url, body: body)
+    end
+
+    def add_item
+      raise 'not implemented'
+    end
+
+    def get_shopping_cart
+      raise 'not implemented'
+    end
+
+    def remove_item
+      raise 'not implemented'
+    end
+
+    def update_quantity
+      raise 'not implemented'
+    end
+
+    private
+
+    def build_url(*resources, operation)
+      [endpoint, *resources, operation].join('/')
+    end
+
+    def build_headers
+      { 'AUTHORIZATION' => "Bearer #{access_token}",
+        '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(',')
+    end
+
+    def build_contextual_location
+      string = { 'country' => country, 'zip' => zip }.compact.map { |kv| kv.join('=') }.join(',')
+      CGI.escape(string) if string
+    end
+  end
+end

data/lib/ebay/config.rb

@@ -1,15 +1,40 @@
+# frozen_string_literal: true
+
+# Ruby wrapper to the eBay APIs
 module Ebay
+  # Configures credentials for accessing the eBay APIs
+  # @yield {Config}
+  def self.configure
+    yield Config
+  end
+
+  # Configures credentials for accessing the eBay APIs
   module Config
     class << self
-      %i(app_id dev_id cert_id).each do |method|
-        eval <<-DEF
-          attr_writer :#{method}
-
-          def #{method}
-            @#{method} || ENV['EBAY_#{method.upcase}']
-          end
-        DEF
+      # @!attribute [rw] app_id
+      # @return [String] unique identifier for the application
+      # @note This attribute defaults to the `EBAY_APP_ID` environment variable.
+      def app_id
+        @app_id ||= ENV['EBAY_APP_ID']
+      end
+
+      # @!attribute [rw] dev_id
+      # @return [String] unique identifier for the developer's account
+      # @note This attribute defaults to the `EBAY_DEV_ID` environment variable.
+      def dev_id
+        @dev_id ||= ENV['EBAY_DEV_ID']
+      end
+
+      # @!attribute [rw] cert_id
+      # @return [String] certificate that authenticates the application when
+      #   making API calls
+      # @note This attribute defaults to the `EBAY_CERT_ID` environment
+      #   variable.
+      def cert_id
+        @cert_id ||= ENV['EBAY_CERT_ID']
       end
+
+      attr_writer :app_id, :dev_id, :cert_id
     end
   end
 end

data/lib/ebay/finding.rb

@@ -1,9 +1,149 @@
-require 'ebay/request'
+# frozen_string_literal: true
 
+require 'ebay/config'
+require 'ebay/requestable'
+
+# Ruby wrapper to the eBay APIs
 module Ebay
-  class Finding < Request
-    host 'svcs.ebay.com'
-    path '/services/search/FindingService/v1'
-    headers 'X-EBAY-SOA-SECURITY-APPNAME' => Config.app_id
+  # 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
+  # @see https://developer.ebay.com/Devzone/finding/CallRef/index.html
+  class Finding
+    include Requestable
+
+    self.endpoint = 'https://svcs.ebay.com/services/search/FindingService/v1'
+
+    # @return [String]
+    attr_reader :global_id
+
+    # @return [String]
+    attr_reader :message_encoding
+
+    # @return [String]
+    attr_reader :response_data_format
+
+    # @return [String]
+    attr_reader :security_appname
+
+    # @return [String]
+    attr_reader :service_version
+
+    # Returns a Finding API request instance
+    #
+    # @see https://developer.ebay.com/Devzone/finding/Concepts/SiteIDToGlobalID.html
+    # @param [String] global_id
+    # @param [String] message_encoding
+    # @param [String] response_data_format
+    # @param [String] security_appname
+    # @param [String] service_version
+    def initialize(global_id: nil, message_encoding: nil,
+                   response_data_format: nil,
+                   security_appname: Config.app_id, service_version: nil)
+      @global_id = global_id
+      @message_encoding = message_encoding
+      @response_data_format = response_data_format
+      @security_appname = security_appname
+      @service_version = service_version
+    end
+
+    # Searches for items whose listings are completed
+    #
+    # @param [Hash] payload
+    # @return [HTTP::Response]
+    def find_completed_items(payload = {})
+      request('findCompletedItems', payload)
+    end
+
+    # Searches for items by category or keyword or both
+    #
+    # @param [Hash] payload
+    # @return [HTTP::Response]
+    def find_items_advanced(payload = {})
+      request('findItemsAdvanced', payload)
+    end
+
+    # Searches for items using specific eBay category ID numbers
+    #
+    # @param [Hash] payload
+    # @return [HTTP::Response]
+    def find_items_by_category(payload = {})
+      request('findItemsByCategory', payload)
+    end
+
+    # Searches for items by a keyword query
+    #
+    # @param [String] keywords
+    # @param [Hash] payload
+    # @return [HTTP::Response]
+    def find_items_by_keywords(keywords, payload = {})
+      payload = payload.merge('keywords' => keywords)
+      request('findItemsByKeywords', payload)
+    end
+
+    # Searches for items using specific eBay product values\
+    #
+    # @param [String] product_id
+    # @param [String] product_id_type
+    # @param [Hash] payload
+    # @return [HTTP::Response]
+    def find_items_by_product(product_id, product_id_type, payload = {})
+      payload = payload.merge('productId' => product_id,
+                              'productId.@type' => product_id_type)
+
+      request('findItemsByProduct', payload)
+    end
+
+    # Searches for items in the eBay store inventories
+    #
+    # @param [Hash] payload
+    # @return [HTTP::Response]
+    def find_items_in_ebay_stores(payload = {})
+      request('findItemsIneBayStores', payload)
+    end
+
+    # Retrieves category and/or aspect histogram information for an eBay
+    # category
+    #
+    # @param [String] category_id
+    # @return [HTTP::Response]
+    def get_histograms(category_id)
+      request('getHistograms', 'categoryId' => category_id)
+    end
+
+    # Retrieves commonly used words found in eBay titles, based on the words you
+    # supply
+    #
+    # @param [String] keywords
+    # @return [HTTP::Response]
+    def get_search_keywords_recommendation(keywords)
+      request('getSearchKeywordsRecommendation', 'keywords' => keywords)
+    end
+
+    # Returns the current version of the service
+    #
+    # @return [HTTP::Response]
+    def get_version
+      request('getVersion')
+    end
+
+    private
+
+    def request(operation, payload = {})
+      params = { 'GLOBAL-ID' => global_id,
+                 'MESSAGE-ENCODING' => message_encoding,
+                 'OPERATION-NAME' => operation,
+                 'RESPONSE-DATA-FORMAT' => response_data_format,
+                 'SECURITY-APPNAME' => security_appname,
+                 'SERVICE-VERSION' => service_version }.update(payload).compact
+
+      http.get(endpoint, params: params)
+    end
   end
 end