ebay-ruby 0.2.0 → 0.3.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 17b513ab5b0d12b5a396988acca1210f323333eb0f6108d5f1e3382542f4509d
4
- data.tar.gz: 5dd731e4430e1e5975928c257d8254e9cadc0b750014c1adc362d34de6b83df1
3
+ metadata.gz: bbadae6120cf8748d6f33d847c9746199717facc4734db1d81719a37393886bc
4
+ data.tar.gz: d457466d75675c9fb698d9fa8feac2bb773d4a89be43f698ab22598bada96839
5
5
  SHA512:
6
- metadata.gz: 4a6d11bf31a67a33674d8a8a6823ce48839931d12f3f2224a53faff81d0bb58cd266fda61532f33db8ea6ac2d9baadebe74363d4aace1370e0b25bcde0414540
7
- data.tar.gz: fb5facaa0b53126fb343707dfc93fee0a9a49cf45e280a1d95f537e6967d0c833f528e997651c2d6eed3a11656a426b20786d08389141e09880f4d957658261e
6
+ metadata.gz: 98aea0105ee22960dece81289809e60048afbc5a68bd17bbf3ef2d54c6f0c139b5551b0f0e04293d49d471a2bd7d244d285f8fcc76a8f8b35eb5eaef05b6900c
7
+ data.tar.gz: 769e216aa765b9850aa3192e82668bc9a79bc69e47b34e54799ecb897b4bbbb38a3750d237a841ce3f3abc2556b9b0f77017801ea97229bb3521053f52354d7e
data/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ (The MIT License)
2
+
3
+ Copyright (c) Hakan Ensari
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining
6
+ a copy of this software and associated documentation files (the
7
+ "Software"), to deal in the Software without restriction, including
8
+ without limitation the rights to use, copy, modify, merge, publish,
9
+ distribute, sublicense, and/or sell copies of the Software, and to
10
+ permit persons to whom the Software is furnished to do so, subject to
11
+ the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be
14
+ included in all copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
19
+ IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
20
+ CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
21
+ TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
22
+ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
data/README.md CHANGED
@@ -1,16 +1,121 @@
1
1
  # ebay-ruby
2
2
 
3
- A wrapper to the eBay APIs in Ruby
3
+ [![Build](https://github.com/hakanensari/ebay-ruby/workflows/build/badge.svg)](https://github.com/hakanensari/ebay-ruby/actions)
4
+
5
+ This library provides a wrapper to the [eBay APIs].
6
+
7
+ ## Getting started
8
+
9
+ You can instantiate API requests using shorthand class methods defined on `Ebay`.
10
+
11
+ ```ruby
12
+ Ebay.finding # returns a new Ebay::Finding instance
13
+ ```
14
+
15
+ ### Keys
16
+
17
+ eBay APIs require [developer keys].
18
+
19
+ You can provide these globally with the environment variables `EBAY_APP_ID`, `EBAY_DEV_ID`, and `EBAY_CERT_ID`.
20
+
21
+ If you prefer not to use environment variables, you can provide your keys globally with:
22
+
23
+ ```ruby
24
+ Ebay.configure do |config|
25
+ config.app_id = 'YOUR APP ID'
26
+ config.dev_id = 'YOUR DEV ID'
27
+ config.cert_id = 'YOUR CERT ID'
28
+ end
29
+ ```
30
+
31
+ 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.
32
+
33
+ Please note that each API names keys differently.
34
+
35
+ ```ruby
36
+ request = Ebay.finding(security_appname: 'YOUR APP ID')
37
+ ```
38
+
39
+ In the examples below, we will assume we are providing our keys with environment variables.
40
+
41
+ ### Parsing a response
42
+
43
+ The eBay APIs return responses in XML or JSON format.
44
+
45
+ You can override the default format of an API when instantiating the request.
46
+
47
+ ```ruby
48
+ require 'json'
49
+
50
+ # the Finding API returns XML by default
51
+ request = Ebay.finding(response_data_format: 'JSON')
52
+ response = request.find_items_by_keywords('iphone')
53
+
54
+ JSON.parse(response)
55
+ ```
56
+
57
+ ## Usage
58
+
59
+ ### [Browse API]
60
+
61
+ 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.
62
+
63
+ ```ruby
64
+ require 'ebay/browse'
65
+ require 'ebay/oauth/client_credentials_grant'
66
+
67
+ access_token = Oauth::ClientCredentialsGrant.new.mint_access_token
68
+ request = Ebay.browse(campaign_id: '123', country: 'US', zip: '19406',
69
+ access_token: access_token)
70
+ response = request.search(q: 'iphone')
71
+ ```
72
+
73
+ ### [Finding API]
74
+
75
+ The Finding API lets you search and browse for items listed on eBay and provides useful metadata to refine searches.
4
76
 
5
77
  ```ruby
6
78
  require 'ebay/finding'
7
79
 
8
- finding = Ebay::Finding.new
9
- params = {
10
- 'GLOBAL-ID' => 'EBAY-US',
11
- 'OPERATION-NAME' => 'findItemsByKeywords',
12
- 'keywords' => 'minimalism'
13
- }
14
- parser = finding.get(query: params)
15
- parser.parse
80
+ request = Ebay.finding
81
+ response = request.find_items_by_keywords('iphone')
82
+ ```
83
+
84
+ ### [Merchandising API]
85
+
86
+ The Merchandising API retrieves information about products or item listings on eBay to help you sell more merchandise to eBay buyers.
87
+
88
+ ```ruby
89
+ require 'ebay/merchandising'
90
+
91
+ request = Ebay::Merchandising.new
92
+ response = request.get_most_watched_items
16
93
  ```
94
+
95
+ ### [Shopping API]
96
+
97
+ The eBay Shopping API makes it easy to search for things on eBay.
98
+
99
+ ```ruby
100
+ require 'ebay/shopping'
101
+
102
+ request = Ebay::Shopping.new
103
+ response = request.find_products('QueryKeywords' => 'tolkien')
104
+ ```
105
+
106
+ ## Development
107
+
108
+ To write requests and responses to a logger, use the logging feature:
109
+
110
+ ```ruby
111
+ require 'logger'
112
+
113
+ request = request.use(logging: {logger: Logger.new(STDOUT)})
114
+ ```
115
+
116
+ [eBay APIs]: https://developer.ebay.com/docs
117
+ [developer keys]: https://developer.ebay.com/my/keys
118
+ [Browse API]: https://developer.ebay.com/api-docs/buy/browse/static/overview.html
119
+ [Finding API]: https://developer.ebay.com/Devzone/finding/Concepts/FindingAPIGuide.html
120
+ [Merchandising API]: https://developer.ebay.com/Devzone/merchandising/docs/Concepts/merchandisingAPIGuide.html
121
+ [Shopping API]: https://developer.ebay.com/Devzone/shopping/docs/Concepts/ShoppingAPIGuide.html
data/lib/ebay-ruby.rb CHANGED
@@ -1 +1,3 @@
1
+ # frozen_string_literal: true
2
+
1
3
  require 'ebay'
data/lib/ebay.rb CHANGED
@@ -1,12 +1,6 @@
1
- require 'ebay/config'
1
+ # frozen_string_literal: true
2
+
3
+ require 'ebay/browse'
2
4
  require 'ebay/finding'
3
5
  require 'ebay/merchandising'
4
- require 'ebay/product'
5
- require 'ebay/product_metadata'
6
6
  require 'ebay/shopping'
7
-
8
- module Ebay
9
- def self.configure
10
- yield Config
11
- end
12
- end
@@ -0,0 +1,164 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'base64'
4
+
5
+ require 'ebay/config'
6
+ require 'ebay/requestable'
7
+
8
+ # Ruby wrapper to the eBay APIs
9
+ module Ebay
10
+ # Returns a {Ebay::Browse#initialize Browse API} instance
11
+ def self.browse(**params)
12
+ Browse.new(**params)
13
+ end
14
+
15
+ # The Browse API allows your buyers to search eBay items by keyword and category. It also allows them to view and add
16
+ # items to their eBay shopping cart.
17
+ #
18
+ # @see https://developer.ebay.com/api-docs/buy/browse/overview.html
19
+ class Browse
20
+ include Requestable
21
+
22
+ self.endpoint = 'https://api.ebay.com/buy/browse/v1'
23
+
24
+ # @return [String]
25
+ attr_reader :campaign_id
26
+
27
+ # @return [String,nil]
28
+ attr_reader :reference_id
29
+
30
+ # @return [String,nil]
31
+ attr_reader :country
32
+
33
+ # @return [String,nil]
34
+ attr_reader :zip
35
+
36
+ # @return [String] the application access token
37
+ def access_token
38
+ @access_token ||= mint_access_token
39
+ end
40
+
41
+ # Returns a Browse API request instance
42
+ #
43
+ # @param [String] campaign_id
44
+ # @param [String] reference_id
45
+ # @param [String] access_token
46
+ def initialize(campaign_id:, reference_id: nil, country: nil, zip: nil, access_token: nil)
47
+ @campaign_id = campaign_id
48
+ @reference_id = reference_id
49
+ @country = country
50
+ @zip = zip
51
+ @access_token = access_token
52
+ end
53
+
54
+ # Searches for eBay items by various query parameters and retrieves summaries of the item
55
+ #
56
+ # @param [Hash] params
57
+ # @return [HTTP::Response]
58
+ def search(params = {})
59
+ url = build_url('item_summary', 'search')
60
+ http.headers(build_headers).get(url, params: params)
61
+ end
62
+
63
+ # Searches for eBay items based on a image and retrieves their summaries
64
+ #
65
+ # @param [File] image
66
+ # @param [Hash] params
67
+ # @return [HTTP::Response]
68
+ def search_by_image(image, params = {})
69
+ url = build_url('item_summary', 'search_by_image')
70
+ headers = build_headers.update('CONTENT-TYPE' => 'application/json')
71
+ encoded_string = Base64.encode64(image.read)
72
+ body = JSON.dump(image: encoded_string)
73
+
74
+ http.headers(headers).post(url, params: params, body: body)
75
+ end
76
+
77
+ # Retrieves the details of a specific item
78
+ #
79
+ # @param [String] item_id
80
+ # @param [Hash] params
81
+ # @return [HTTP::Response]
82
+ def get_item(item_id, params = {})
83
+ url = build_url('item', item_id)
84
+ params = params.merge(item_id: item_id)
85
+
86
+ http.headers(build_headers).get(url, params: params)
87
+ end
88
+
89
+ # Retrieves the details of a specific item using its legacy item ID
90
+ #
91
+ # @param [String] legacy_item_id
92
+ # @param [Hash] params
93
+ # @return [HTTP::Response]
94
+ def get_item_by_legacy_id(legacy_item_id, params = {})
95
+ url = build_url('item', 'get_item_by_legacy_id')
96
+ params = params.merge(legacy_item_id: legacy_item_id)
97
+
98
+ http.headers(build_headers).get(url, params: params)
99
+ end
100
+
101
+ # Retrieves the details of the individual items in an item group
102
+ #
103
+ # @param [String] item_group_id
104
+ # @return [HTTP::Response]
105
+ def get_items_by_item_group(item_group_id)
106
+ url = build_url('item', 'get_items_by_item_group')
107
+ params = { item_group_id: item_group_id }
108
+
109
+ http.headers(build_headers).get(url, params: params)
110
+ end
111
+
112
+ # Retrieves the details of the individual items in an item group
113
+ #
114
+ # @param [String] item_id
115
+ # @param [String] marketplace_id
116
+ # @return [HTTP::Response]
117
+ def check_compatibility(item_id, marketplace_id, compatibility_properties)
118
+ url = build_url('item', item_id, 'check_compatibility')
119
+ headers = build_headers
120
+ headers.update('X-EBAY-C-MARKETPLACE-ID' => marketplace_id, 'CONTENT-TYPE' => 'application/json')
121
+ body = JSON.dump('compatibilityProperties' => compatibility_properties)
122
+
123
+ http.headers(headers).post(url, body: body)
124
+ end
125
+
126
+ def add_item
127
+ raise 'not implemented'
128
+ end
129
+
130
+ def get_shopping_cart
131
+ raise 'not implemented'
132
+ end
133
+
134
+ def remove_item
135
+ raise 'not implemented'
136
+ end
137
+
138
+ def update_quantity
139
+ raise 'not implemented'
140
+ end
141
+
142
+ private
143
+
144
+ def build_url(*resources, operation)
145
+ [endpoint, *resources, operation].join('/')
146
+ end
147
+
148
+ def build_headers
149
+ { 'AUTHORIZATION' => "Bearer #{access_token}",
150
+ 'X-EBAY-C-ENDUSERCTX' => build_ebay_enduser_context }
151
+ end
152
+
153
+ def build_ebay_enduser_context
154
+ { 'affiliateCampaignId' => campaign_id,
155
+ 'affiliateReferenceId' => reference_id,
156
+ 'contextualLocation' => build_contextual_location }.compact.map { |kv| kv.join('=') }.join(',')
157
+ end
158
+
159
+ def build_contextual_location
160
+ string = { 'country' => country, 'zip' => zip }.compact.map { |kv| kv.join('=') }.join(',')
161
+ CGI.escape(string) if string
162
+ end
163
+ end
164
+ end
data/lib/ebay/config.rb CHANGED
@@ -1,15 +1,40 @@
1
+ # frozen_string_literal: true
2
+
3
+ # Ruby wrapper to the eBay APIs
1
4
  module Ebay
5
+ # Configures credentials for accessing the eBay APIs
6
+ # @yield {Config}
7
+ def self.configure
8
+ yield Config
9
+ end
10
+
11
+ # Configures credentials for accessing the eBay APIs
2
12
  module Config
3
13
  class << self
4
- %i(app_id dev_id cert_id).each do |method|
5
- eval <<-DEF
6
- attr_writer :#{method}
7
-
8
- def #{method}
9
- @#{method} || ENV['EBAY_#{method.upcase}']
10
- end
11
- DEF
14
+ # @!attribute [rw] app_id
15
+ # @return [String] unique identifier for the application
16
+ # @note This attribute defaults to the `EBAY_APP_ID` environment variable.
17
+ def app_id
18
+ @app_id ||= ENV['EBAY_APP_ID']
19
+ end
20
+
21
+ # @!attribute [rw] dev_id
22
+ # @return [String] unique identifier for the developer's account
23
+ # @note This attribute defaults to the `EBAY_DEV_ID` environment variable.
24
+ def dev_id
25
+ @dev_id ||= ENV['EBAY_DEV_ID']
26
+ end
27
+
28
+ # @!attribute [rw] cert_id
29
+ # @return [String] certificate that authenticates the application when
30
+ # making API calls
31
+ # @note This attribute defaults to the `EBAY_CERT_ID` environment
32
+ # variable.
33
+ def cert_id
34
+ @cert_id ||= ENV['EBAY_CERT_ID']
12
35
  end
36
+
37
+ attr_writer :app_id, :dev_id, :cert_id
13
38
  end
14
39
  end
15
40
  end
data/lib/ebay/finding.rb CHANGED
@@ -1,9 +1,149 @@
1
- require 'ebay/request'
1
+ # frozen_string_literal: true
2
2
 
3
+ require 'ebay/config'
4
+ require 'ebay/requestable'
5
+
6
+ # Ruby wrapper to the eBay APIs
3
7
  module Ebay
4
- class Finding < Request
5
- host 'svcs.ebay.com'
6
- path '/services/search/FindingService/v1'
7
- headers 'X-EBAY-SOA-SECURITY-APPNAME' => Config.app_id
8
+ # Returns a {Ebay::Finding#initialize Finding API} instance
9
+ def self.finding(**params)
10
+ Finding.new(**params)
11
+ end
12
+
13
+ # The Finding API lets you search and browse for items listed on eBay and
14
+ # provides useful metadata to refine searches.
15
+ #
16
+ # @see https://developer.ebay.com/Devzone/finding/Concepts/MakingACall.html
17
+ # @see https://developer.ebay.com/Devzone/finding/CallRef/index.html
18
+ class Finding
19
+ include Requestable
20
+
21
+ self.endpoint = 'https://svcs.ebay.com/services/search/FindingService/v1'
22
+
23
+ # @return [String]
24
+ attr_reader :global_id
25
+
26
+ # @return [String]
27
+ attr_reader :message_encoding
28
+
29
+ # @return [String]
30
+ attr_reader :response_data_format
31
+
32
+ # @return [String]
33
+ attr_reader :security_appname
34
+
35
+ # @return [String]
36
+ attr_reader :service_version
37
+
38
+ # Returns a Finding API request instance
39
+ #
40
+ # @see https://developer.ebay.com/Devzone/finding/Concepts/SiteIDToGlobalID.html
41
+ # @param [String] global_id
42
+ # @param [String] message_encoding
43
+ # @param [String] response_data_format
44
+ # @param [String] security_appname
45
+ # @param [String] service_version
46
+ def initialize(global_id: nil, message_encoding: nil,
47
+ response_data_format: nil,
48
+ security_appname: Config.app_id, service_version: nil)
49
+ @global_id = global_id
50
+ @message_encoding = message_encoding
51
+ @response_data_format = response_data_format
52
+ @security_appname = security_appname
53
+ @service_version = service_version
54
+ end
55
+
56
+ # Searches for items whose listings are completed
57
+ #
58
+ # @param [Hash] payload
59
+ # @return [HTTP::Response]
60
+ def find_completed_items(payload = {})
61
+ request('findCompletedItems', payload)
62
+ end
63
+
64
+ # Searches for items by category or keyword or both
65
+ #
66
+ # @param [Hash] payload
67
+ # @return [HTTP::Response]
68
+ def find_items_advanced(payload = {})
69
+ request('findItemsAdvanced', payload)
70
+ end
71
+
72
+ # Searches for items using specific eBay category ID numbers
73
+ #
74
+ # @param [Hash] payload
75
+ # @return [HTTP::Response]
76
+ def find_items_by_category(payload = {})
77
+ request('findItemsByCategory', payload)
78
+ end
79
+
80
+ # Searches for items by a keyword query
81
+ #
82
+ # @param [String] keywords
83
+ # @param [Hash] payload
84
+ # @return [HTTP::Response]
85
+ def find_items_by_keywords(keywords, payload = {})
86
+ payload = payload.merge('keywords' => keywords)
87
+ request('findItemsByKeywords', payload)
88
+ end
89
+
90
+ # Searches for items using specific eBay product values\
91
+ #
92
+ # @param [String] product_id
93
+ # @param [String] product_id_type
94
+ # @param [Hash] payload
95
+ # @return [HTTP::Response]
96
+ def find_items_by_product(product_id, product_id_type, payload = {})
97
+ payload = payload.merge('productId' => product_id,
98
+ 'productId.@type' => product_id_type)
99
+
100
+ request('findItemsByProduct', payload)
101
+ end
102
+
103
+ # Searches for items in the eBay store inventories
104
+ #
105
+ # @param [Hash] payload
106
+ # @return [HTTP::Response]
107
+ def find_items_in_ebay_stores(payload = {})
108
+ request('findItemsIneBayStores', payload)
109
+ end
110
+
111
+ # Retrieves category and/or aspect histogram information for an eBay
112
+ # category
113
+ #
114
+ # @param [String] category_id
115
+ # @return [HTTP::Response]
116
+ def get_histograms(category_id)
117
+ request('getHistograms', 'categoryId' => category_id)
118
+ end
119
+
120
+ # Retrieves commonly used words found in eBay titles, based on the words you
121
+ # supply
122
+ #
123
+ # @param [String] keywords
124
+ # @return [HTTP::Response]
125
+ def get_search_keywords_recommendation(keywords)
126
+ request('getSearchKeywordsRecommendation', 'keywords' => keywords)
127
+ end
128
+
129
+ # Returns the current version of the service
130
+ #
131
+ # @return [HTTP::Response]
132
+ def get_version
133
+ request('getVersion')
134
+ end
135
+
136
+ private
137
+
138
+ def request(operation, payload = {})
139
+ params = { 'GLOBAL-ID' => global_id,
140
+ 'MESSAGE-ENCODING' => message_encoding,
141
+ 'OPERATION-NAME' => operation,
142
+ 'RESPONSE-DATA-FORMAT' => response_data_format,
143
+ 'SECURITY-APPNAME' => security_appname,
144
+ 'SERVICE-VERSION' => service_version }.update(payload).compact
145
+
146
+ http.get(endpoint, params: params)
147
+ end
8
148
  end
9
149
  end