ebay-api-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 282125c3f9f1addb39262ff57f5d817264dee5d8e39e00b22ede983299424ae5
+  data.tar.gz: 8cfabcedcccfd2ee3c83a1fb0437e2059119b11676249df6c233b972f2ea596d
+SHA512:
+  metadata.gz: c1a0b61cbaa0cba58e3b2abc036f7e378f46663a8daaf528ec730a42198bd675ccd265a26482993cd868b2d16aa1d0507a9a13d3c89eb408df52ae10c18fb6d9
+  data.tar.gz: 516284188e67e58bdbb7b6ab430d6903bac9c2075398a061a1a8342d9075d1d9d1aa5a7892f1b59a568891ff3401c32be0497b518250f68f4ba7fc6b865b6e46

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-03-26
+
+### Added
+
+- Initial release
+- OAuth 2.0 Client Credentials authentication with token caching
+- Browse API: search, get_item, get_items_by_item_group, search_by_image
+- Finding API: findItemsByKeywords, findCompletedItems, findItemsAdvanced, findItemsByCategory
+- Taxonomy API: get_default_category_tree_id, get_category_tree, get_category_subtree
+- Sandbox mode support
+- Full RSpec test suite with WebMock

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eduardo Souza
+
+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

@@ -0,0 +1,162 @@
+# ebay-api-ruby
+
+A modern Ruby gem for the eBay REST APIs. Supports the Browse API, Finding API, and Taxonomy API with OAuth 2.0 authentication.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ebay-api-ruby'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself:
+
+```bash
+gem install ebay-api-ruby
+```
+
+## Configuration
+
+```ruby
+require 'ebay'
+
+Ebay.configure do |config|
+  config.client_id = ENV['EBAY_CLIENT_ID']
+  config.client_secret = ENV['EBAY_CLIENT_SECRET']
+  config.app_id = ENV['EBAY_APP_ID']           # Optional, defaults to client_id for Finding API
+  config.marketplace_id = 'EBAY_US'             # Default
+  config.timeout = 30                            # Default
+end
+```
+
+### Sandbox Mode
+
+```ruby
+Ebay.configure do |config|
+  config.client_id = ENV['EBAY_SANDBOX_CLIENT_ID']
+  config.client_secret = ENV['EBAY_SANDBOX_CLIENT_SECRET']
+  config.sandbox!
+end
+```
+
+## Usage
+
+### Browse API
+
+Search for items, get item details, and search by image.
+
+```ruby
+browse = Ebay::Browse.new
+
+# Search items
+results = browse.search(q: "vintage rolex", limit: 10)
+results['itemSummaries'].each do |item|
+  puts "#{item['title']} - #{item['price']['value']} #{item['price']['currency']}"
+end
+
+# Get a specific item
+item = browse.get_item("v1|123456789|0")
+
+# Get items by group
+items = browse.get_items_by_item_group("group123")
+
+# Search by image
+results = browse.search_by_image(Base64.encode64(File.read("watch.jpg")))
+```
+
+### Finding API
+
+Search active and completed/sold listings. Uses the legacy Finding Service (no OAuth required, just app_id).
+
+```ruby
+finding = Ebay::Finding.new
+
+# Search by keywords
+results = finding.find_items_by_keywords("macbook pro m3")
+
+# Find completed/sold items (great for price history)
+sold = finding.find_completed_items("pokemon base set charizard")
+
+# Advanced search with filters
+results = finding.find_items_advanced(keywords: "nike jordan", categoryId: "93427")
+
+# Search by category
+results = finding.find_items_by_category("9355")
+```
+
+### Taxonomy API
+
+Get category trees and browse category hierarchies.
+
+```ruby
+taxonomy = Ebay::Taxonomy.new
+
+# Get default category tree ID for a marketplace
+tree_info = taxonomy.get_default_category_tree_id("EBAY_US")
+tree_id = tree_info['categoryTreeId']
+
+# Get the full category tree
+tree = taxonomy.get_category_tree(tree_id)
+
+# Get a subtree
+subtree = taxonomy.get_category_subtree(tree_id, "9355")
+```
+
+### Authentication
+
+The gem handles OAuth 2.0 Client Credentials authentication automatically. Tokens are cached and refreshed when expired.
+
+```ruby
+client = Ebay.client
+
+# Manual authentication (usually not needed)
+client.authenticate!
+
+# Direct API calls
+result = client.get("/buy/browse/v1/item_summary/search", q: "test")
+result = client.post("/some/endpoint", { data: "value" })
+```
+
+## Error Handling
+
+```ruby
+begin
+  browse.search(q: "test")
+rescue Ebay::AuthenticationError => e
+  puts "Auth failed: #{e.message}"
+rescue Ebay::NotFoundError => e
+  puts "Not found: #{e.message} (#{e.status_code})"
+rescue Ebay::RateLimitError => e
+  puts "Rate limited. Retry after: #{e.retry_after}"
+rescue Ebay::ValidationError => e
+  puts "Validation error: #{e.errors}"
+rescue Ebay::APIError => e
+  puts "API error: #{e.message} (#{e.status_code})"
+rescue Ebay::ConfigurationError => e
+  puts "Config error: #{e.message}"
+end
+```
+
+## Development
+
+```bash
+git clone https://github.com/esouza/ebay-api-ruby.git
+cd ebay-api-ruby
+bundle install
+bundle exec rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/esouza/ebay-api-ruby. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/lib/ebay/base.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Ebay
+  class Base
+    attr_reader :client
+
+    def initialize(client = nil)
+      @client = client || Ebay.client
+    end
+  end
+end

data/lib/ebay/browse.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module Ebay
+  class Browse < Base
+    def search(q:, **params)
+      client.get("/buy/browse/v1/item_summary/search", { q: q }.merge(params))
+    end
+
+    def get_item(item_id)
+      client.get("/buy/browse/v1/item/#{URI.encode_www_form_component(item_id)}")
+    end
+
+    def get_items_by_item_group(item_group_id)
+      client.get("/buy/browse/v1/item/get_items_by_item_group", item_group_id: item_group_id)
+    end
+
+    def search_by_image(image_base64, **params)
+      client.post("/buy/browse/v1/item_summary/search_by_image", { image: image_base64 }.merge(params))
+    end
+  end
+end

data/lib/ebay/client.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Ebay
+  class Client
+    include HTTParty
+
+    attr_reader :configuration
+
+    def initialize(configuration = nil)
+      @configuration = configuration || Ebay.configuration
+      @access_token = nil
+      @token_expires_at = nil
+      validate_configuration!
+    end
+
+    def authenticate!
+      credentials = Base64.strict_encode64("#{configuration.client_id}:#{configuration.client_secret}")
+
+      response = self.class.post(
+        "#{configuration.base_url}/identity/v1/oauth2/token",
+        headers: {
+          'Authorization' => "Basic #{credentials}",
+          'Content-Type' => 'application/x-www-form-urlencoded'
+        },
+        body: "grant_type=client_credentials&scope=https://api.ebay.com/oauth/api_scope",
+        timeout: configuration.timeout
+      )
+
+      case response.code
+      when 200
+        data = response.parsed_response
+        @access_token = data['access_token']
+        @token_expires_at = Time.now + (data['expires_in'] || 7200).to_i - 60
+        @access_token
+      else
+        raise AuthenticationError, "OAuth token request failed: #{response.body}"
+      end
+    end
+
+    def get(path, params = {})
+      request(:get, path, query: params)
+    end
+
+    def post(path, data = {})
+      request(:post, path, body: data.to_json)
+    end
+
+    private
+
+    def validate_configuration!
+      raise ConfigurationError unless configuration&.valid?
+    end
+
+    def ensure_authenticated!
+      if @access_token.nil? || @token_expires_at.nil? || Time.now >= @token_expires_at
+        authenticate!
+      end
+    end
+
+    def request(method, path, options = {})
+      ensure_authenticated!
+
+      url = "#{configuration.base_url}#{path}"
+      request_options = {
+        headers: default_headers,
+        timeout: configuration.timeout
+      }
+
+      if options[:query] && !options[:query].empty?
+        request_options[:query] = options[:query]
+      end
+
+      if options[:body]
+        request_options[:body] = options[:body]
+      end
+
+      response = self.class.send(method, url, request_options)
+      handle_response(response)
+    end
+
+    def default_headers
+      {
+        'Authorization' => "Bearer #{@access_token}",
+        'Content-Type' => 'application/json',
+        'Accept' => 'application/json'
+      }
+    end
+
+    def handle_response(response)
+      case response.code
+      when 200, 201, 202, 204
+        response.parsed_response
+      when 401
+        raise AuthenticationError, "Authentication failed: #{response.body}"
+      when 404
+        raise NotFoundError.new("Resource not found", response.code, response.body)
+      when 429
+        retry_after = response.headers['retry-after']
+        raise RateLimitError.new("Rate limit exceeded", response.code, response.body, retry_after)
+      when 400, 422
+        parsed = response.parsed_response || {}
+        errors = parsed['errors'] || parsed['message'] || {}
+        raise ValidationError.new(
+          parsed['message'] || 'Validation failed',
+          response.code,
+          response.body,
+          errors
+        )
+      when 500..599
+        raise APIError.new("Server error", response.code, response.body)
+      else
+        raise APIError.new("Unexpected response", response.code, response.body)
+      end
+    end
+  end
+end

data/lib/ebay/configuration.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Ebay
+  class Configuration
+    attr_accessor :client_id, :client_secret, :app_id,
+                  :base_url, :sandbox, :timeout, :marketplace_id
+
+    def initialize
+      @base_url = "https://api.ebay.com"
+      @sandbox = false
+      @timeout = 30
+      @marketplace_id = "EBAY_US"
+    end
+
+    def sandbox!
+      @sandbox = true
+      @base_url = "https://api.sandbox.ebay.com"
+      self
+    end
+
+    def valid?
+      !client_id.nil? && !client_id.empty? &&
+        !client_secret.nil? && !client_secret.empty?
+    end
+
+    def finding_url
+      sandbox ? "https://svcs.sandbox.ebay.com/services/search/FindingService/v1" : "https://svcs.ebay.com/services/search/FindingService/v1"
+    end
+  end
+end

data/lib/ebay/errors.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Ebay
+  class Error < StandardError; end
+
+  class ConfigurationError < Error
+    def initialize(message = "Missing required configuration: client_id and client_secret")
+      super(message)
+    end
+  end
+
+  class AuthenticationError < Error
+    def initialize(message = "Authentication failed")
+      super(message)
+    end
+  end
+
+  class APIError < Error
+    attr_reader :status_code, :response_body
+
+    def initialize(message, status_code = nil, response_body = nil)
+      super(message)
+      @status_code = status_code
+      @response_body = response_body
+    end
+  end
+
+  class ValidationError < APIError
+    attr_reader :errors
+
+    def initialize(message, status_code = nil, response_body = nil, errors = {})
+      super(message, status_code, response_body)
+      @errors = errors
+    end
+  end
+
+  class NotFoundError < APIError
+    def initialize(message = "Resource not found", status_code = 404, response_body = nil)
+      super(message, status_code, response_body)
+    end
+  end
+
+  class RateLimitError < APIError
+    attr_reader :retry_after
+
+    def initialize(message = "Rate limit exceeded", status_code = 429, response_body = nil, retry_after = nil)
+      super(message, status_code, response_body)
+      @retry_after = retry_after
+    end
+  end
+end

data/lib/ebay/finding.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Ebay
+  class Finding < Base
+    def find_items_by_keywords(keywords, **params)
+      finding_request("findItemsByKeywords", { keywords: keywords }.merge(params))
+    end
+
+    def find_completed_items(keywords, **params)
+      finding_request("findCompletedItems", { keywords: keywords }.merge(params))
+    end
+
+    def find_items_advanced(**params)
+      finding_request("findItemsAdvanced", params)
+    end
+
+    def find_items_by_category(category_id, **params)
+      finding_request("findItemsByCategory", { categoryId: category_id }.merge(params))
+    end
+
+    private
+
+    def finding_request(operation, params)
+      url = client.configuration.finding_url
+      query = {
+        "OPERATION-NAME" => operation,
+        "SERVICE-VERSION" => "1.0.0",
+        "SECURITY-APPNAME" => client.configuration.app_id || client.configuration.client_id,
+        "RESPONSE-DATA-FORMAT" => "JSON",
+        "REST-PAYLOAD" => ""
+      }.merge(params)
+
+      response = HTTParty.get(url, query: query, timeout: client.configuration.timeout)
+      handle_finding_response(response, operation)
+    end
+
+    def handle_finding_response(response, operation)
+      return response.parsed_response unless response.code >= 400
+      raise APIError.new("Finding API error", response.code, response.body)
+    end
+  end
+end

data/lib/ebay/taxonomy.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Ebay
+  class Taxonomy < Base
+    def get_default_category_tree_id(marketplace_id = nil)
+      mid = marketplace_id || client.configuration.marketplace_id
+      client.get("/commerce/taxonomy/v1/get_default_category_tree_id", marketplace_id: mid)
+    end
+
+    def get_category_tree(category_tree_id)
+      client.get("/commerce/taxonomy/v1/category_tree/#{category_tree_id}")
+    end
+
+    def get_category_subtree(category_tree_id, category_id)
+      client.get("/commerce/taxonomy/v1/category_tree/#{category_tree_id}/get_category_subtree", category_id: category_id)
+    end
+  end
+end

data/lib/ebay/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Ebay
+  VERSION = "0.1.0"
+end

data/lib/ebay.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'httparty'
+require 'json'
+require 'base64'
+
+require_relative 'ebay/version'
+require_relative 'ebay/errors'
+require_relative 'ebay/configuration'
+require_relative 'ebay/client'
+require_relative 'ebay/base'
+require_relative 'ebay/browse'
+require_relative 'ebay/finding'
+require_relative 'ebay/taxonomy'
+
+module Ebay
+  class << self
+    attr_accessor :configuration
+
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration) if block_given?
+    end
+
+    def client
+      @client ||= Client.new(configuration)
+    end
+
+    def reset!
+      @client = nil
+      @configuration = nil
+    end
+  end
+end

data/spec/ebay/browse_spec.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+RSpec.describe Ebay::Browse do
+  let(:client) { Ebay.client }
+  let(:browse) { described_class.new(client) }
+
+  before { stub_oauth_token }
+
+  describe "#search" do
+    it "searches items by keyword" do
+      stub_request(:get, "https://api.ebay.com/buy/browse/v1/item_summary/search")
+        .with(query: hash_including(q: "iphone"))
+        .to_return(status: 200, body: '{"itemSummaries": []}', headers: { 'Content-Type' => 'application/json' })
+
+      result = browse.search(q: "iphone")
+      expect(result).to eq("itemSummaries" => [])
+    end
+
+    it "passes additional params" do
+      stub_request(:get, "https://api.ebay.com/buy/browse/v1/item_summary/search")
+        .with(query: hash_including(q: "iphone", limit: "10"))
+        .to_return(status: 200, body: '{"itemSummaries": []}', headers: { 'Content-Type' => 'application/json' })
+
+      browse.search(q: "iphone", limit: "10")
+      expect(WebMock).to have_requested(:get, "https://api.ebay.com/buy/browse/v1/item_summary/search")
+        .with(query: hash_including(q: "iphone", limit: "10"))
+    end
+  end
+
+  describe "#get_item" do
+    it "retrieves a single item" do
+      stub_request(:get, "https://api.ebay.com/buy/browse/v1/item/v1%7C123%7C0")
+        .to_return(status: 200, body: '{"itemId": "v1|123|0"}', headers: { 'Content-Type' => 'application/json' })
+
+      result = browse.get_item("v1|123|0")
+      expect(result).to eq("itemId" => "v1|123|0")
+    end
+  end
+
+  describe "#get_items_by_item_group" do
+    it "retrieves items by group" do
+      stub_request(:get, "https://api.ebay.com/buy/browse/v1/item/get_items_by_item_group")
+        .with(query: { item_group_id: "group123" })
+        .to_return(status: 200, body: '{"items": []}', headers: { 'Content-Type' => 'application/json' })
+
+      result = browse.get_items_by_item_group("group123")
+      expect(result).to eq("items" => [])
+    end
+  end
+
+  describe "#search_by_image" do
+    it "searches by image" do
+      stub_request(:post, "https://api.ebay.com/buy/browse/v1/item_summary/search_by_image")
+        .to_return(status: 200, body: '{"itemSummaries": []}', headers: { 'Content-Type' => 'application/json' })
+
+      result = browse.search_by_image("base64data")
+      expect(result).to eq("itemSummaries" => [])
+    end
+  end
+end

data/spec/ebay/client_spec.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+RSpec.describe Ebay::Client do
+  let(:client) { Ebay.client }
+
+  describe "#initialize" do
+    it "raises ConfigurationError without valid config" do
+      Ebay.reset!
+      Ebay.configure { |c| c.client_id = nil }
+      expect { Ebay.client }.to raise_error(Ebay::ConfigurationError)
+    end
+  end
+
+  describe "#authenticate!" do
+    it "obtains an access token" do
+      stub_oauth_token
+      token = client.authenticate!
+      expect(token).to eq("test_token")
+    end
+
+    it "sends correct authorization header" do
+      stub_oauth_token
+      client.authenticate!
+
+      expected_credentials = Base64.strict_encode64("test_client_id:test_client_secret")
+      expect(WebMock).to have_requested(:post, "https://api.ebay.com/identity/v1/oauth2/token")
+        .with(headers: { 'Authorization' => "Basic #{expected_credentials}" })
+    end
+
+    it "raises AuthenticationError on failure" do
+      stub_request(:post, "https://api.ebay.com/identity/v1/oauth2/token")
+        .to_return(status: 401, body: "Unauthorized")
+
+      expect { client.authenticate! }.to raise_error(Ebay::AuthenticationError)
+    end
+  end
+
+  describe "#get" do
+    before { stub_oauth_token }
+
+    it "makes authenticated GET requests" do
+      stub_request(:get, "https://api.ebay.com/test")
+        .to_return(status: 200, body: '{"result": "ok"}', headers: { 'Content-Type' => 'application/json' })
+
+      result = client.get("/test")
+      expect(result).to eq("result" => "ok")
+    end
+
+    it "passes query params" do
+      stub_request(:get, "https://api.ebay.com/test?q=shoes")
+        .to_return(status: 200, body: '{}', headers: { 'Content-Type' => 'application/json' })
+
+      client.get("/test", q: "shoes")
+      expect(WebMock).to have_requested(:get, "https://api.ebay.com/test").with(query: { q: "shoes" })
+    end
+
+    it "auto-authenticates before request" do
+      stub_request(:get, "https://api.ebay.com/test")
+        .to_return(status: 200, body: '{}', headers: { 'Content-Type' => 'application/json' })
+
+      client.get("/test")
+      expect(WebMock).to have_requested(:post, "https://api.ebay.com/identity/v1/oauth2/token").once
+    end
+  end
+
+  describe "#post" do
+    before { stub_oauth_token }
+
+    it "makes authenticated POST requests" do
+      stub_request(:post, "https://api.ebay.com/test")
+        .to_return(status: 200, body: '{"created": true}', headers: { 'Content-Type' => 'application/json' })
+
+      result = client.post("/test", { name: "item" })
+      expect(result).to eq("created" => true)
+    end
+  end
+
+  describe "error handling" do
+    before { stub_oauth_token }
+
+    it "raises NotFoundError on 404" do
+      stub_request(:get, "https://api.ebay.com/test")
+        .to_return(status: 404, body: "Not Found")
+
+      expect { client.get("/test") }.to raise_error(Ebay::NotFoundError)
+    end
+
+    it "raises RateLimitError on 429" do
+      stub_request(:get, "https://api.ebay.com/test")
+        .to_return(status: 429, body: "Too Many Requests", headers: { 'retry-after' => '60' })
+
+      expect { client.get("/test") }.to raise_error(Ebay::RateLimitError) do |error|
+        expect(error.retry_after).to eq('60')
+      end
+    end
+
+    it "raises ValidationError on 400" do
+      stub_request(:get, "https://api.ebay.com/test")
+        .to_return(status: 400, body: '{"message": "Bad Request"}', headers: { 'Content-Type' => 'application/json' })
+
+      expect { client.get("/test") }.to raise_error(Ebay::ValidationError)
+    end
+
+    it "raises APIError on 500" do
+      stub_request(:get, "https://api.ebay.com/test")
+        .to_return(status: 500, body: "Internal Server Error")
+
+      expect { client.get("/test") }.to raise_error(Ebay::APIError)
+    end
+  end
+
+  describe "token caching" do
+    it "reuses token for multiple requests" do
+      stub_oauth_token
+
+      stub_request(:get, "https://api.ebay.com/test")
+        .to_return(status: 200, body: '{}', headers: { 'Content-Type' => 'application/json' })
+
+      client.get("/test")
+      client.get("/test")
+
+      expect(WebMock).to have_requested(:post, "https://api.ebay.com/identity/v1/oauth2/token").once
+    end
+  end
+end

data/spec/ebay/configuration_spec.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+RSpec.describe Ebay::Configuration do
+  subject(:config) { described_class.new }
+
+  describe "#initialize" do
+    it "sets default base_url" do
+      expect(config.base_url).to eq("https://api.ebay.com")
+    end
+
+    it "sets default sandbox to false" do
+      expect(config.sandbox).to be false
+    end
+
+    it "sets default timeout to 30" do
+      expect(config.timeout).to eq(30)
+    end
+
+    it "sets default marketplace_id" do
+      expect(config.marketplace_id).to eq("EBAY_US")
+    end
+  end
+
+  describe "#sandbox!" do
+    it "enables sandbox mode" do
+      config.sandbox!
+      expect(config.sandbox).to be true
+    end
+
+    it "changes base_url to sandbox" do
+      config.sandbox!
+      expect(config.base_url).to eq("https://api.sandbox.ebay.com")
+    end
+
+    it "returns self for chaining" do
+      expect(config.sandbox!).to eq(config)
+    end
+  end
+
+  describe "#valid?" do
+    it "returns false when client_id is nil" do
+      config.client_secret = "secret"
+      expect(config.valid?).to be false
+    end
+
+    it "returns false when client_secret is nil" do
+      config.client_id = "id"
+      expect(config.valid?).to be false
+    end
+
+    it "returns false when client_id is empty" do
+      config.client_id = ""
+      config.client_secret = "secret"
+      expect(config.valid?).to be false
+    end
+
+    it "returns true when both are set" do
+      config.client_id = "id"
+      config.client_secret = "secret"
+      expect(config.valid?).to be true
+    end
+  end
+
+  describe "#finding_url" do
+    it "returns production URL by default" do
+      expect(config.finding_url).to eq("https://svcs.ebay.com/services/search/FindingService/v1")
+    end
+
+    it "returns sandbox URL when sandbox enabled" do
+      config.sandbox!
+      expect(config.finding_url).to eq("https://svcs.sandbox.ebay.com/services/search/FindingService/v1")
+    end
+  end
+end

data/spec/ebay/finding_spec.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+RSpec.describe Ebay::Finding do
+  let(:client) { Ebay.client }
+  let(:finding) { described_class.new(client) }
+  let(:finding_url) { "https://svcs.ebay.com/services/search/FindingService/v1" }
+
+  before do
+    stub_oauth_token
+  end
+
+  describe "#find_items_by_keywords" do
+    it "searches by keywords" do
+      stub_request(:get, finding_url)
+        .with(query: hash_including("OPERATION-NAME" => "findItemsByKeywords", "keywords" => "laptop"))
+        .to_return(status: 200, body: '{"findItemsByKeywordsResponse": []}', headers: { 'Content-Type' => 'application/json' })
+
+      result = finding.find_items_by_keywords("laptop")
+      expect(result).to eq("findItemsByKeywordsResponse" => [])
+    end
+
+    it "includes correct service params" do
+      stub_request(:get, finding_url)
+        .with(query: hash_including(
+          "OPERATION-NAME" => "findItemsByKeywords",
+          "SERVICE-VERSION" => "1.0.0",
+          "SECURITY-APPNAME" => "test_app_id",
+          "RESPONSE-DATA-FORMAT" => "JSON"
+        ))
+        .to_return(status: 200, body: '{}', headers: { 'Content-Type' => 'application/json' })
+
+      finding.find_items_by_keywords("test")
+    end
+  end
+
+  describe "#find_completed_items" do
+    it "searches completed/sold items" do
+      stub_request(:get, finding_url)
+        .with(query: hash_including("OPERATION-NAME" => "findCompletedItems", "keywords" => "vintage watch"))
+        .to_return(status: 200, body: '{"findCompletedItemsResponse": []}', headers: { 'Content-Type' => 'application/json' })
+
+      result = finding.find_completed_items("vintage watch")
+      expect(result).to eq("findCompletedItemsResponse" => [])
+    end
+  end
+
+  describe "#find_items_advanced" do
+    it "performs advanced search" do
+      stub_request(:get, finding_url)
+        .with(query: hash_including("OPERATION-NAME" => "findItemsAdvanced"))
+        .to_return(status: 200, body: '{"findItemsAdvancedResponse": []}', headers: { 'Content-Type' => 'application/json' })
+
+      result = finding.find_items_advanced(keywords: "shoes", categoryId: "3034")
+      expect(result).to eq("findItemsAdvancedResponse" => [])
+    end
+  end
+
+  describe "#find_items_by_category" do
+    it "searches by category" do
+      stub_request(:get, finding_url)
+        .with(query: hash_including("OPERATION-NAME" => "findItemsByCategory", "categoryId" => "9355"))
+        .to_return(status: 200, body: '{"findItemsByCategoryResponse": []}', headers: { 'Content-Type' => 'application/json' })
+
+      result = finding.find_items_by_category("9355")
+      expect(result).to eq("findItemsByCategoryResponse" => [])
+    end
+  end
+
+  describe "error handling" do
+    it "raises APIError on failure" do
+      stub_request(:get, finding_url)
+        .with(query: hash_including("OPERATION-NAME" => "findItemsByKeywords"))
+        .to_return(status: 500, body: "Server Error")
+
+      expect { finding.find_items_by_keywords("test") }.to raise_error(Ebay::APIError)
+    end
+  end
+end

data/spec/ebay/taxonomy_spec.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+RSpec.describe Ebay::Taxonomy do
+  let(:client) { Ebay.client }
+  let(:taxonomy) { described_class.new(client) }
+
+  before { stub_oauth_token }
+
+  describe "#get_default_category_tree_id" do
+    it "returns default category tree id" do
+      stub_request(:get, "https://api.ebay.com/commerce/taxonomy/v1/get_default_category_tree_id")
+        .with(query: { marketplace_id: "EBAY_US" })
+        .to_return(status: 200, body: '{"categoryTreeId": "0", "categoryTreeVersion": "119"}', headers: { 'Content-Type' => 'application/json' })
+
+      result = taxonomy.get_default_category_tree_id
+      expect(result).to eq("categoryTreeId" => "0", "categoryTreeVersion" => "119")
+    end
+
+    it "accepts custom marketplace_id" do
+      stub_request(:get, "https://api.ebay.com/commerce/taxonomy/v1/get_default_category_tree_id")
+        .with(query: { marketplace_id: "EBAY_GB" })
+        .to_return(status: 200, body: '{"categoryTreeId": "3"}', headers: { 'Content-Type' => 'application/json' })
+
+      result = taxonomy.get_default_category_tree_id("EBAY_GB")
+      expect(result).to eq("categoryTreeId" => "3")
+    end
+  end
+
+  describe "#get_category_tree" do
+    it "returns category tree" do
+      stub_request(:get, "https://api.ebay.com/commerce/taxonomy/v1/category_tree/0")
+        .to_return(status: 200, body: '{"categoryTreeId": "0", "rootCategoryNode": {}}', headers: { 'Content-Type' => 'application/json' })
+
+      result = taxonomy.get_category_tree("0")
+      expect(result).to include("categoryTreeId" => "0")
+    end
+  end
+
+  describe "#get_category_subtree" do
+    it "returns category subtree" do
+      stub_request(:get, "https://api.ebay.com/commerce/taxonomy/v1/category_tree/0/get_category_subtree")
+        .with(query: { category_id: "9355" })
+        .to_return(status: 200, body: '{"categorySubtreeNode": {}}', headers: { 'Content-Type' => 'application/json' })
+
+      result = taxonomy.get_category_subtree("0", "9355")
+      expect(result).to eq("categorySubtreeNode" => {})
+    end
+  end
+end

data/spec/examples.txt

@@ -0,0 +1,43 @@
+example_id                               | status | run_time        |
+---------------------------------------- | ------ | --------------- |
+./spec/ebay/browse_spec.rb[1:1:1]        | passed | 0.00076 seconds |
+./spec/ebay/browse_spec.rb[1:1:2]        | passed | 0.00193 seconds |
+./spec/ebay/browse_spec.rb[1:2:1]        | passed | 0.00051 seconds |
+./spec/ebay/browse_spec.rb[1:3:1]        | passed | 0.00054 seconds |
+./spec/ebay/browse_spec.rb[1:4:1]        | passed | 0.00048 seconds |
+./spec/ebay/client_spec.rb[1:1:1]        | passed | 0.00004 seconds |
+./spec/ebay/client_spec.rb[1:2:1]        | passed | 0.00022 seconds |
+./spec/ebay/client_spec.rb[1:2:2]        | passed | 0.00031 seconds |
+./spec/ebay/client_spec.rb[1:2:3]        | passed | 0.00026 seconds |
+./spec/ebay/client_spec.rb[1:3:1]        | passed | 0.00041 seconds |
+./spec/ebay/client_spec.rb[1:3:2]        | passed | 0.00065 seconds |
+./spec/ebay/client_spec.rb[1:3:3]        | passed | 0.00039 seconds |
+./spec/ebay/client_spec.rb[1:4:1]        | passed | 0.00065 seconds |
+./spec/ebay/client_spec.rb[1:5:1]        | passed | 0.00044 seconds |
+./spec/ebay/client_spec.rb[1:5:2]        | passed | 0.00052 seconds |
+./spec/ebay/client_spec.rb[1:5:3]        | passed | 0.00059 seconds |
+./spec/ebay/client_spec.rb[1:5:4]        | passed | 0.00047 seconds |
+./spec/ebay/client_spec.rb[1:6:1]        | passed | 0.00057 seconds |
+./spec/ebay/configuration_spec.rb[1:1:1] | passed | 0.00003 seconds |
+./spec/ebay/configuration_spec.rb[1:1:2] | passed | 0.00004 seconds |
+./spec/ebay/configuration_spec.rb[1:1:3] | passed | 0.00003 seconds |
+./spec/ebay/configuration_spec.rb[1:1:4] | passed | 0.00003 seconds |
+./spec/ebay/configuration_spec.rb[1:2:1] | passed | 0.00046 seconds |
+./spec/ebay/configuration_spec.rb[1:2:2] | passed | 0.00005 seconds |
+./spec/ebay/configuration_spec.rb[1:2:3] | passed | 0.00004 seconds |
+./spec/ebay/configuration_spec.rb[1:3:1] | passed | 0.00004 seconds |
+./spec/ebay/configuration_spec.rb[1:3:2] | passed | 0.00003 seconds |
+./spec/ebay/configuration_spec.rb[1:3:3] | passed | 0.00005 seconds |
+./spec/ebay/configuration_spec.rb[1:3:4] | passed | 0.00005 seconds |
+./spec/ebay/configuration_spec.rb[1:4:1] | passed | 0.00003 seconds |
+./spec/ebay/configuration_spec.rb[1:4:2] | passed | 0.00003 seconds |
+./spec/ebay/finding_spec.rb[1:1:1]       | passed | 0.00134 seconds |
+./spec/ebay/finding_spec.rb[1:1:2]       | passed | 0.02238 seconds |
+./spec/ebay/finding_spec.rb[1:2:1]       | passed | 0.00057 seconds |
+./spec/ebay/finding_spec.rb[1:3:1]       | passed | 0.00077 seconds |
+./spec/ebay/finding_spec.rb[1:4:1]       | passed | 0.00048 seconds |
+./spec/ebay/finding_spec.rb[1:5:1]       | passed | 0.00125 seconds |
+./spec/ebay/taxonomy_spec.rb[1:1:1]      | passed | 0.0007 seconds  |
+./spec/ebay/taxonomy_spec.rb[1:1:2]      | passed | 0.00056 seconds |
+./spec/ebay/taxonomy_spec.rb[1:2:1]      | passed | 0.00212 seconds |
+./spec/ebay/taxonomy_spec.rb[1:3:1]      | passed | 0.0006 seconds  |

data/spec/spec_helper.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "ebay"
+require "webmock/rspec"
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+  config.filter_run_when_matching :focus
+  config.example_status_persistence_file_path = "spec/examples.txt"
+  config.disable_monkey_patching!
+  config.warnings = true
+
+  if config.files_to_run.one?
+    config.default_formatter = "doc"
+  end
+
+  config.order = :random
+  Kernel.srand config.seed
+
+  config.before(:each) do
+    WebMock.disable_net_connect!
+    Ebay.reset!
+    Ebay.configure do |c|
+      c.client_id = "test_client_id"
+      c.client_secret = "test_client_secret"
+      c.app_id = "test_app_id"
+    end
+  end
+
+  config.after(:each) do
+    WebMock.reset!
+  end
+end
+
+def stub_oauth_token
+  stub_request(:post, "https://api.ebay.com/identity/v1/oauth2/token")
+    .to_return(
+      status: 200,
+      headers: { 'Content-Type' => 'application/json' },
+      body: {
+        access_token: "test_token",
+        expires_in: 7200,
+        token_type: "Application Access Token"
+      }.to_json
+    )
+end

metadata

@@ -0,0 +1,192 @@
+--- !ruby/object:Gem::Specification
+name: ebay-api-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Eduardo Souza
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+description: Ruby gem for integrating with eBay REST APIs. Supports Browse API, Finding
+  API, and Taxonomy API with OAuth 2.0 authentication.
+email:
+- eduardo@eduardosouza.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/ebay.rb
+- lib/ebay/base.rb
+- lib/ebay/browse.rb
+- lib/ebay/client.rb
+- lib/ebay/configuration.rb
+- lib/ebay/errors.rb
+- lib/ebay/finding.rb
+- lib/ebay/taxonomy.rb
+- lib/ebay/version.rb
+- spec/ebay/browse_spec.rb
+- spec/ebay/client_spec.rb
+- spec/ebay/configuration_spec.rb
+- spec/ebay/finding_spec.rb
+- spec/ebay/taxonomy_spec.rb
+- spec/examples.txt
+- spec/spec_helper.rb
+homepage: https://github.com/esouza/ebay-api-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/esouza/ebay-api-ruby
+  source_code_uri: https://github.com/esouza/ebay-api-ruby
+  changelog_uri: https://github.com/esouza/ebay-api-ruby/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.21
+signing_key:
+specification_version: 4
+summary: Ruby gem for the eBay REST APIs
+test_files: []