ebay-ruby 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17b513ab5b0d12b5a396988acca1210f323333eb0f6108d5f1e3382542f4509d
-  data.tar.gz: 5dd731e4430e1e5975928c257d8254e9cadc0b750014c1adc362d34de6b83df1
+  metadata.gz: 18523b3ec4ff1f6d4bac8c6dbeb4d2570ece325e963ed4540aded51bcbef8be9
+  data.tar.gz: 4db3fedd2023ff5c49d0a6e1369188325d1e61b798dc77b63c1cd51ee9b3baa6
 SHA512:
-  metadata.gz: 4a6d11bf31a67a33674d8a8a6823ce48839931d12f3f2224a53faff81d0bb58cd266fda61532f33db8ea6ac2d9baadebe74363d4aace1370e0b25bcde0414540
-  data.tar.gz: fb5facaa0b53126fb343707dfc93fee0a9a49cf45e280a1d95f537e6967d0c833f528e997651c2d6eed3a11656a426b20786d08389141e09880f4d957658261e
+  metadata.gz: 5e6cf632c7006f51393878a5af01057e9cec95678ddc7e7565e528f4c015ec2a19a70e55b1ddd8f67e4a5f5e40e00e8e2c858811178faf214084f65f934bdcf3
+  data.tar.gz: 138a8d6fa3f982ed664cc4340ea9d47802fb4a4c8b3cc9dd5fcbfee050198c4916bda43521947831e78422bee8fd06f7db979e8934b998e7bfd153fb16151995

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,82 @@
 # 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)
+
+A Ruby wrapper to the [eBay APIs]
+
+## Usage
+
+### Buy APIs
+
+Retrieve purchasable items, check out, then track orders without visiting the eBay site.
+
+#### [Browse API]
+
+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.
+
+```ruby
+require 'ebay/browse'
+require 'ebay/oauth/client_credentials_grant'
+
+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')
+
+JSON.parse(response)
+```
+
+### Traditional Searching APIs
+
+Search eBay; build search and browse experiences.
+
+#### [Finding API]
+
+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.
 
 ```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.new
+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.
+
+#### [Shopping API]
+
+The eBay Shopping API makes it easy to search for things on eBay.
+
+```ruby
+require 'ebay/shopping'
+
+request = Ebay::Finding.new
+response = request.find_products('QueryKeywords' => 'tolkien')
+
+JSON.parse(response)
+```
+
+#### [Merchandising API]
+
+The Merchandising API provides item and product recommendations that can be used to cross-sell and up-sell eBay items to buyers.
+
+```ruby
+require 'ebay/merchandising'
+
+request = Ebay::Finding.new
+response = request.get_most_watched_items
+
+JSON.parse(response)
+```
+
+[eBay APIs]: https://developer.ebay.com/docs
+[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

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,167 @@
+# frozen_string_literal: true
+
+require 'http'
+
+require 'ebay/config'
+require 'ebay/sandboxable'
+
+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.
+  #
+  # @see https://developer.ebay.com/api-docs/buy/browse/overview.html
+  class Browse
+    include Sandboxable
+
+    SANDBOX_ENDPOINT = 'https://api.sandbox.ebay.com/buy/browse/v1'
+    PRODUCTION_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 [String] image the Base64 string of the 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')
+      body = JSON.dump(image: image)
+
+      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.update(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.update(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 = sandbox? ? SANDBOX_ENDPOINT : PRODUCTION_ENDPOINT
+      [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
+
+  # Stores 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,148 @@
-require 'ebay/request'
+# frozen_string_literal: true
+
+require 'http'
+
+require 'ebay/config'
+require 'ebay/sandboxable'
 
 module Ebay
-  class Finding < Request
-    host 'svcs.ebay.com'
-    path '/services/search/FindingService/v1'
-    headers 'X-EBAY-SOA-SECURITY-APPNAME' => Config.app_id
+  # The Finding API lets you search for and browse 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 Sandboxable
+
+    SANDBOX_ENDPOINT = 'https://svcs.sandbox.ebay.com/services/search/FindingService/v1'
+    PRODUCTION_ENDPOINT = 'https://svcs.ebay.com/services/search/FindingService/v1'
+
+    # @return [String, nil]
+    attr_reader :global_id
+
+    # @return [String, nil]
+    attr_reader :message_encoding
+
+    # @return [String, nil]
+    attr_reader :response_data_format
+
+    # @return [String]
+    attr_reader :security_appname
+
+    # @return [String, nil]
+    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: 'JSON',
+                   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.update('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.update('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 = {})
+      url = sandbox? ? SANDBOX_ENDPOINT : PRODUCTION_ENDPOINT
+      params = { 'GLOBAL-ID' => global_id,
+                 'MESSAGE-ENCODING' => message_encoding,
+                 'OPERATION-NAME' => operation,
+                 'REQUEST-DATA-FORMAT' => 'JSON',
+                 'RESPONSE-DATA-FORMAT' => response_data_format,
+                 'SECURITY-APPNAME' => security_appname,
+                 'SERVICE-VERSION' => service_version }.compact
+
+      HTTP.post(url, params: params, body: JSON.dump(payload))
+    end
   end
 end