Add Search endpoint

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 * Your contribution here.
 * [#57](https://github.com/dblock/iex-ruby-client/pull/57): Update properties for chart api endpoint - [@brunjo](https://github.com/brunjo).
+* [#58](https://github.com/dblock/iex-ruby-client/pull/58): Add search endpoint - [@pmn4](https://github.com/pmn4).
 
 ### 1.1.0 (2019/07/08)
 

README.md

@@ -26,6 +26,7 @@ A Ruby client for the [The IEX Cloud API](https://iexcloud.io/docs/api/).
   - [Get Sector Performance](#get-sector-performance)
   - [Get Largest Trades](#get-largest-trades)
   - [Get a Quote for Crypto Currencies](#get-a-quote-for-crypto-currencies)
+  - [Search](#search)
 - [Configuration](#configuration)
 - [Errors](#errors)
   - [SymbolNotFound](#symbolnotfound)
@@ -369,6 +370,21 @@ crypto.high_dollar #'$3,590'
 
 See [#crypto](https://iexcloud.io/docs/api/#crypto) for detailed documentation or [crypto.rb](lib/iex/resources/crypto.rb) for returned fields.
 
+### Search
+
+Searches for companies*
+
+``` Ruby
+results = client.search('msft')
+
+results.first.company_name # 'Microsoft'
+```
+
+See [#search](https://iexcloud.io/docs/api/#search) for detailed documentation.
+
+* - IEX documentation suggests this endpoint will one day return more than just
+Companies.
+
 ## Configuration
 
 You can configure client options globally or directly with a `IEX::Api::Client` instance.

lib/iex/api.rb

@@ -10,6 +10,7 @@
 require_relative 'endpoints/ohlc'
 require_relative 'endpoints/price'
 require_relative 'endpoints/quote'
+require_relative 'endpoints/search'
 require_relative 'endpoints/sectors'
 require_relative 'endpoints/crypto'
 

lib/iex/api/client.rb

@@ -14,6 +14,7 @@ class Client
       include Endpoints::Ohlc
       include Endpoints::Price
       include Endpoints::Quote
+      include Endpoints::Search
       include Endpoints::Sectors
 
       include Cloud::Connection

lib/iex/endpoints/search.rb

@@ -0,0 +1,21 @@
+module IEX
+  module Endpoints
+    module Search
+      def search(fragment, options = {})
+        raise ArgumentError, 'Fragment is required' if fragment.blank?
+
+        get([
+          'search',
+          fragment
+        ].compact.join('/'), options).map do |data|
+          # Per the IEX documentation, any type of Resource could be returned
+          # this should become a case statement:
+          # https://iexcloud.io/docs/api/#search
+          IEX::Resources::Company.new(data)
+        end
+      rescue Faraday::ResourceNotFound => e
+        raise IEX::Errors::SearchNotFoundError.new(fragment, e.response[:body])
+      end
+    end
+  end
+end

lib/iex/errors.rb

@@ -1,3 +1,4 @@
+require_relative 'errors/search_not_found_error'
 require_relative 'errors/symbol_not_found_error'
 require_relative 'errors/client_error'
 require_relative 'errors/permission_denied_error'

lib/iex/errors/client_error.rb

@@ -1,6 +1,8 @@
+require_relative 'error'
+
 module IEX
   module Errors
-    class ClientError < StandardError
+    class ClientError < Error
       attr_reader :response
 
       def initialize(response)

lib/iex/errors/error.rb

@@ -0,0 +1,5 @@
+module IEX
+  module Errors
+    class Error < StandardError; end
+  end
+end

lib/iex/errors/search_not_found_error.rb

@@ -0,0 +1,16 @@
+require_relative 'error'
+
+module IEX
+  module Errors
+    class SearchNotFoundError < Error
+      attr_reader :response
+      attr_reader :fragment
+
+      def initialize(fragment, response)
+        @response = response
+        @fragment = fragment
+        super %(Fragment "#{fragment}" Not Found)
+      end
+    end
+  end
+end

lib/iex/errors/symbol_not_found_error.rb

@@ -1,8 +1,10 @@
+require_relative 'error'
+
 module IEX
   module Errors
-    class SymbolNotFoundError < StandardError
-      attr_reader :symbol
+    class SymbolNotFoundError < Error
       attr_reader :response
+      attr_reader :symbol
 
       def initialize(symbol, response)
         @response = response

spec/iex/endpoints/search_spec.rb

@@ -0,0 +1,34 @@
+require 'spec_helper'
+
+describe IEX::Endpoints::Search do
+  context '#search' do
+    # Search falls outside of the normal testing because it is not exactly
+    # RESTy. The search endpoint (eventually) can return any type of resource
+
+    include_context 'client'
+
+    before do
+      # search is not supported on the free tier, except in the sandbox. In
+      # order for VCR to record the response, we need the endpoint to work
+      client.endpoint = 'https://sandbox.iexapis.com/v1'
+      # using the documentation-provided token to use in the Sandbox
+      client.publishable_token = 'Tsk_341c973d296e4e18aa61dd63050ce235'
+    end
+
+    it 'searches for resources', vcr: { cassette_name: 'client/search/msft' } do
+      results = client.search('msft')
+      results.each do |result|
+        expect(result).to be_a(IEX::Resources::Company)
+      end
+    end
+
+    it 'handles missing search terms', vcr: { cassette_name: 'client/search/missing' } do
+      expect { client.search('') }
+        .to raise_error(ArgumentError, 'Fragment is required')
+    end
+
+    it 'handles unknown search terms', vcr: { cassette_name: 'client/search/unknown' } do
+      expect(client.search('unreconized-search-term')).to be_empty
+    end
+  end
+end