ebsco-eds 0.0.1.pre

data/lib/ebsco/eds/results.rb

@@ -0,0 +1,375 @@
+require 'ebsco/eds/record'
+require 'yaml'
+
+module EBSCO
+
+  module EDS
+
+    # Search Results
+    class Results
+
+      # Raw results as Hash
+      attr_reader :results
+      # Array of EBSCO::EDS::Record results
+      attr_reader :records
+      # Array of EBSCO::EDS::Record Research Starters
+      attr_reader :research_starters
+      # Array of EBSCO::EDS::Record Exact Publication Matches
+      attr_reader :publication_match
+
+      # Lookup table of databases that have their labels suppressed in the response.
+      DBS = YAML::load_file(File.join(__dir__, 'settings.yml'))['databases']
+
+      # Creates search results from the \EDS API search response. It includes information about the results and a list
+      # of Record items.
+      def initialize(search_results)
+  
+        @results = search_results
+
+        # convert all results to a list of records
+        @records = []
+        if stat_total_hits > 0
+          @results['SearchResult']['Data']['Records'].each { |record| @records.push(EBSCO::EDS::Record.new(record)) }
+        end
+  
+        # create a special list of research starter records
+        @research_starters = []
+        _related_records = @results.fetch('SearchResult',{}).fetch('RelatedContent',{}).fetch('RelatedRecords',{})
+        if _related_records.count > 0
+          _related_records.each do |related_item|
+            if related_item['Type'] == 'rs'
+              rs_entries = related_item.fetch('Records',{})
+              if rs_entries.count > 0
+                rs_entries.each do |rs_record|
+                  @research_starters.push(EBSCO::EDS::Record.new(rs_record))
+                end
+              end
+            end
+          end
+        end
+  
+        # create a special list of exact match publications
+        @publication_match = []
+        _related_publications = @results.fetch('SearchResult',{}).fetch('RelatedContent',{}).fetch('RelatedPublications',{})
+        if _related_publications.count > 0
+          _related_publications.each do |related_item|
+            if related_item['Type'] == 'emp'
+              _publication_matches = related_item.fetch('PublicationRecords',{})
+              if _publication_matches.count > 0
+                _publication_matches.each do |publication_record|
+                  @publication_match.push(EBSCO::EDS::Record.new(publication_record))
+                end
+              end
+            end
+          end
+        end
+  
+      end
+
+      # returns solr search response format
+      def to_solr
+
+        solr_start = (page_number-1) * results_per_page
+        hl_hash = {}
+        solr_docs = []
+
+        if stat_total_hits > 0
+          @records.each { |record|
+
+            # todo: add solr hl.tag.pre and hl.tag.post to retrieval criteria
+            if retrieval_criteria.fetch('Highlight',{}) == 'y'
+              hl_title = record.title.gsub('&lt;highlight&gt;', '<em>').gsub('&lt;/highlight&gt;', '</em>')
+              hl_hash.update({ record.database_id + '-' + record.accession_number => { 'title_display' => [hl_title]} })
+              #hl_hash.merge title_hl
+            end
+
+            solr_docs.push(record.to_hash)
+          }
+        end
+
+        # solr response
+        {
+            'responseHeader' => {
+              'status' => 0,
+              'QTime' => stat_total_time,
+              'params' => {
+                  'q' => search_terms.join(' '),
+                  'wt' => 'ruby',
+                  'start' => solr_start,
+                  'rows' => results_per_page,
+                  'facet' => true,
+                  'f.subject_topic_facet.facet.limit' => 21,
+                  'f.language_facet.facet.limit' => 11,
+
+              }
+            },
+            'response' => {
+               'numFound' => stat_total_hits.to_i,
+               'start' => solr_start,
+               'docs' => solr_docs
+            },
+            'highlighting' => hl_hash,
+            'facet_counts' =>
+                {
+                    'facet_fields' => {
+                        'format' => solr_facets('SourceType'),
+                        'language_facet' => solr_facets('Language'),
+                        'subject_topic_facet' => solr_facets('SubjectEDS')
+                    }
+                }
+        }
+
+      end
+
+      # Total number of results found.
+      def stat_total_hits
+        _hits = @results.fetch('SearchResult',{}).fetch('Statistics',{}).fetch('TotalHits',{})
+        _hits == {} ? 0 : _hits
+      end
+
+      # Time it took to complete the search in milliseconds.
+      def stat_total_time
+        @results['SearchResult']['Statistics']['TotalSearchTime']
+      end
+
+      # Search criteria used in the search
+      # Returns a hash.
+      # ==== Example
+      #   {
+      #      "Queries"=>[{"BooleanOperator"=>"AND", "Term"=>"earthquakes"}],
+      #      "SearchMode"=>"all",
+      #      "IncludeFacets"=>"y",
+      #      "Expanders"=>["fulltext", "thesaurus", "relatedsubjects"],
+      #      "Sort"=>"relevance",
+      #      "RelatedContent"=>["rs"],
+      #      "AutoSuggest"=>"n"
+      #    }
+      def search_criteria
+        @results['SearchRequest']['SearchCriteria']
+      end
+
+      # Search criteria actions applied.
+      # Returns a hash.
+      # ==== Example
+      #   {
+      #      "QueriesWithAction"=>[{"Query"=>{"BooleanOperator"=>"AND", "Term"=>"earthquakes"}, "RemoveAction"=>"removequery(1)"}],
+      #      "ExpandersWithAction"=>[{"Id"=>"fulltext", "RemoveAction"=>"removeexpander(fulltext)"}]
+      #   }
+      def search_criteria_with_actions
+        @results['SearchRequest']['SearchCriteriaWithActions']
+      end
+
+      # Retrieval criteria that was applied to the search. Returns a hash.
+      # ==== Example
+      #   {"View"=>"brief", "ResultsPerPage"=>20, "PageNumber"=>1, "Highlight"=>"y"}
+      def retrieval_criteria
+        @results['SearchRequest']['RetrievalCriteria']
+      end
+  
+      # Queries used to produce the results. Returns an array of query hashes.
+      # ==== Example
+      #    [{"BooleanOperator"=>"AND", "Term"=>"volcano"}]
+      def search_queries
+        @results['SearchRequest']['SearchCriteria']['Queries']
+      end
+
+      # Current page number for the results. Returns an integer.
+      def page_number
+        @results['SearchRequest']['RetrievalCriteria']['PageNumber'] || 1
+      end
+
+      # Results per page. Returns an integer.
+      def results_per_page
+        @results['SearchRequest']['RetrievalCriteria']['ResultsPerPage'] || 20
+      end
+
+      # List of facets applied to the search.
+      # ==== Example
+      #   [{
+      #      "FacetValue"=>{"Id"=>"SubjectGeographic", "Value"=>"massachusetts"},
+      #      "RemoveAction"=>"removefacetfiltervalue(1,SubjectGeographic:massachusetts)"
+      #    }]
+      def applied_facets
+        af = []
+        applied_facets_section = @results['SearchRequest'].fetch('SearchCriteriaWithActions',{}).fetch('FacetFiltersWithAction',{})
+        applied_facets_section.each do |applied_facets|
+          applied_facets.fetch('FacetValuesWithAction',{}).each do |applied_facet|
+            af.push(applied_facet)
+          end
+        end
+        af
+      end
+
+      # List of limiters applied to the search.
+      # ==== Example
+      #   [{
+      #      "Id"=>"LA99",
+      #      "LimiterValuesWithAction"=>[{"Value"=>"French", "RemoveAction"=>"removelimitervalue(LA99:French)"}],
+      #      "RemoveAction"=>"removelimiter(LA99)"
+      #   }]
+      def applied_limiters
+        af = []
+        applied_limters_section = @results['SearchRequest'].fetch('SearchCriteriaWithActions',{}).fetch('LimitersWithAction',{})
+        applied_limters_section.each do |applied_limter|
+          af.push(applied_limter)
+        end
+        af
+      end
+
+      # Expanders applied to the search.
+      # ==== Example
+      #   [
+      #      {"Id"=>"fulltext", "RemoveAction"=>"removeexpander(fulltext)"},
+      #      {"Id"=>"thesaurus", "RemoveAction"=>"removeexpander(thesaurus)"},
+      #      {"Id"=>"relatedsubjects", "RemoveAction"=>"removeexpander(relatedsubjects)"}
+      #    ]
+      def applied_expanders
+        af = []
+        applied_expanders_section = @results['SearchRequest'].fetch('SearchCriteriaWithActions',{}).fetch('ExpandersWithAction',{})
+        applied_expanders_section.each do |applied_explander|
+          af.push(applied_explander)
+        end
+        af
+      end
+
+      # Publications search was limited to.
+      # ==== Example
+      #   [
+      #      ["Id", "eric"],
+      #      ["RemoveAction", "removepublication(eric)"]
+      #   ]
+      def applied_publications
+        retval = []
+        applied_publications_section = @results['SearchRequest'].fetch('SearchCriteriaWithActions',{}).fetch('PublicationWithAction',{})
+        applied_publications_section.each do |item|
+          retval.push(item)
+        end
+        retval
+      end
+
+      # Provides a list of databases searched and the number of hits found in each one.
+      # ==== Example
+      #   [
+      #      {:id=>"nlebk", :hits=>0, :label=>"eBook Collection (EBSCOhost)"},
+      #      {:id=>"e000xna", :hits=>30833, :label=>"eBook Academic Collection (EBSCOhost)"},
+      #      {:id=>"edsart", :hits=>8246, :label=>"ARTstor Digital Library"},
+      #      {:id=>"e700xna", :hits=>6701, :label=>"eBook Public Library Collection (EBSCOhost)"},
+      #      {:id=>"cat02060a", :hits=>3464, :label=>"EDS Demo Catalog – US - U of Georgia"},
+      #      {:id=>"ers", :hits=>1329, :label=>"Research Starters"},
+      #      {:id=>"asn", :hits=>136406, :label=>"Academic Search Ultimate"}
+      #    ]
+      def database_stats
+        databases = []
+        databases_facet = @results['SearchResult']['Statistics']['Databases']
+        databases_facet.each do |database|
+          if DBS.key?(database['Id'].upcase)
+            db_label = DBS[database['Id'].upcase];
+          else
+            db_label = database['Label']
+          end
+          databases.push({id: database['Id'], hits: database['Hits'], label: db_label})
+        end
+        databases
+      end
+
+      # Provides a list of facets for the search results.
+      # ==== Example
+      #   [
+      #      {
+      #        :id=>"SourceType",
+      #        :label=>"Source Type",
+      #        :values=>[
+      #          {
+      #             :value=>"Academic Journals",
+      #             :hitcount=>147,
+      #             :action=>"addfacetfilter(SourceType:Academic Journals)"
+      #          },
+      #          {
+      #             :value=>"News",
+      #             :hitcount=>111,
+      #             :action=>"addfacetfilter(SourceType:News)"
+      #           },
+      #
+      #       ...
+      #
+      #      }
+      #    ]
+      def facets (facet_provided_id = 'all')
+        facets_hash = []
+        available_facets = @results.fetch('SearchResult',{}).fetch('AvailableFacets',{})
+        available_facets.each do |available_facet|
+          if available_facet['Id'] == facet_provided_id || facet_provided_id == 'all'
+            facet_label = available_facet['Label']
+            facet_id = available_facet['Id']
+            facet_values = []
+            available_facet['AvailableFacetValues'].each do |available_facet_value|
+              facet_value = available_facet_value['Value']
+              facet_count = available_facet_value['Count']
+              facet_action = available_facet_value['AddAction']
+              facet_values.push({value: facet_value, hitcount: facet_count, action: facet_action})
+            end
+            facets_hash.push(id: facet_id, label: facet_label, values: facet_values)
+          end
+        end
+        facets_hash
+      end
+
+      def solr_facets (facet_provided_id = 'all')
+        facet_values = []
+        available_facets = @results.fetch('SearchResult',{}).fetch('AvailableFacets',{})
+        available_facets.each do |available_facet|
+          if available_facet['Id'] == facet_provided_id || facet_provided_id == 'all'
+            available_facet['AvailableFacetValues'].each do |available_facet_value|
+              facet_value = available_facet_value['Value']
+              facet_count = available_facet_value['Count']
+              facet_values.push(facet_value, facet_count)
+            end
+          end
+        end
+        facet_values
+      end
+
+      # Returns a hash of the date range available for the search.
+      # ==== Example
+      #   {:mindate=>"1501-01", :maxdate=>"2018-04", :minyear=>"1501", :maxyear=>"2018"}
+      def date_range
+        mindate = @results['SearchResult']['AvailableCriteria']['DateRange']['MinDate']
+        maxdate = @results['SearchResult']['AvailableCriteria']['DateRange']['MaxDate']
+        minyear = mindate[0..3]
+        maxyear = maxdate[0..3]
+        {mindate: mindate, maxdate: maxdate, minyear:minyear, maxyear:maxyear}
+      end
+
+      # Provides alternative search terms to correct spelling, etc.
+      # ==== Example
+      #   results = session.simple_search('earthquak')
+      #   results.did_you_mean
+      #   => "earthquake"
+      def did_you_mean
+        dym_suggestions = @results.fetch('SearchResult', {}).fetch('AutoSuggestedTerms',{})
+        dym_suggestions.each do |term|
+          return term
+        end
+        nil
+      end
+
+      # Returns a simple list of the search terms used. Boolean operators are not indicated.
+      # ==== Example
+      #   ["earthquakes", "california"]
+      def search_terms
+        terms = []
+        queries = @results.fetch('SearchRequest',{}).fetch('SearchCriteriaWithActions',{}).fetch('QueriesWithAction',{})
+        unless queries.nil?
+          queries.each do |query|
+            query['Query']['Term'].split.each do |word|
+              terms.push(word)
+            end
+          end
+        end
+        terms
+      end
+  
+    end
+
+  end
+end

data/lib/ebsco/eds/session.rb

@@ -0,0 +1,624 @@
+require 'ebsco/eds/version'
+require 'ebsco/eds/info'
+require 'ebsco/eds/results'
+require 'faraday'
+require 'faraday_middleware'
+require 'logger'
+require 'json'
+
+module EBSCO
+
+  module EDS
+
+    # Sessions are used to query and retrieve information from the EDS API.
+    class Session
+
+      # Contains search Info available in the session profile. Includes the sort options, search fields, limiters and expanders available to the profile.
+      attr_accessor :info
+      # Contains the search Options sent as part of each request to the EDS API such as limiters, expanders, search modes, sort order, etc.
+      attr_accessor :search_options
+      # The authentication token. This is passed along in the x-authenticationToken HTTP header.
+      attr_accessor :auth_token # :nodoc:
+      # The session token. This is passed along in the x-sessionToken HTTP header.
+      attr_accessor :session_token # :nodoc:
+
+      # Creates a new session.
+      #
+      # This can be done in one of two ways:
+      #
+      # === 1. Environment variables
+      # * +EDS_AUTH+ - authentication method: 'ip' or 'user'
+      # * +EDS_PROFILE+ - profile ID for the EDS API
+      # * +EDS_USER+ - user id attached to the profile
+      # * +EDS_PASS+ - user password
+      # * +EDS_GUEST+ - allow guest access: 'y' or 'n'
+      # * +EDS_ORG+ - name of your institution or company
+      #
+      # ==== Example
+      # Once you have environment variables set, simply create a session like this:
+      #   session = EBSCO::EDS::Session.new
+      #
+      # ===  2. \Options
+      # * +:auth+
+      # * +:profile+
+      # * +:user+
+      # * +:pass+
+      # * +:guest+
+      # * +:org+
+      #
+      # ==== Example
+      #   session = EBSCO::EDS::Session.new {
+      #     :auth => 'user',
+      #     :profile => 'edsapi',
+      #     :user => 'joe'
+      #     :pass => 'secret',
+      #     :guest => false,
+      #     :org => 'Acme University'
+      #   }
+      def initialize(options = {})
+
+        @auth_token = ''
+        @session_token = ''
+
+        if options.has_key? :user
+          @user = options[:user]
+        elsif ENV.has_key? 'EDS_USER'
+          @user = ENV['EDS_USER']
+        end
+
+        if options.has_key? :pass
+          @pass = options[:pass]
+        elsif ENV.has_key? 'EDS_PASS'
+          @pass = ENV['EDS_PASS']
+        end
+
+        if options.has_key? :profile
+          @profile = options[:profile]
+        elsif ENV.has_key? 'EDS_PROFILE'
+          @profile = ENV['EDS_PROFILE']
+        end
+        raise EBSCO::EDS::InvalidParameter, 'Session must specify a valid api profile.' if blank?(@profile)
+
+        if options.has_key? :guest
+          @guest = options[:guest] ? 'y' : 'n'
+        elsif ENV.has_key? 'EDS_GUEST'
+          @guest = ENV['EDS_GUEST']
+        end
+
+        if options.has_key? :org
+          @org = options[:org]
+        elsif ENV.has_key? 'EDS_ORG'
+          @org = ENV['EDS_ORG']
+        end
+
+        if options.has_key? :auth
+          @auth_type = options[:auth]
+        elsif ENV.has_key? 'EDS_AUTH'
+          @auth_type = ENV['EDS_AUTH']
+        else
+          @auth_type = 'user'
+        end
+
+        @max_retries = MAX_ATTEMPTS
+        @auth_token = create_auth_token
+        @session_token = create_session_token
+        @info = EBSCO::EDS::Info.new(do_request(:get, path: INFO_URL))
+        @current_page = 0
+        @search_options = nil
+
+      end
+
+      # :category: Search & Retrieve Methods
+      # Performs a search.
+      #
+      # Returns search Results.
+      #
+      # ==== \Options
+      #
+      # * +:query+ - Required. The search terms. Format: {booleanOperator},{fieldCode}:{term}. Example: SU:Hiking
+      # * +:mode+ - Search mode to be used. Either: all (default), any, bool, smart
+      # * +:results_per_page+ - The number of records retrieved with the search results (between 1-100, default is 20).
+      # * +:page+ - Starting page number for the result set returned from a search (if results per page = 10, and page number = 3 , this implies: I am expecting 10 records starting at page 3).
+      # * +:sort+ - The sort order for the search results. Either: relevance (default), oldest, newest
+      # * +:highlight+ - Specifies whether or not the search term is highlighted using <highlight /> tags. Either true or false.
+      # * +:include_facets+ - Specifies whether or not the search term is highlighted using <highlight /> tags. Either true (default) or false.
+      # * +:facet_filters+ - Facets to apply to the search. Facets are used to refine previous search results. Format: \{filterID},{facetID}:{value}[,{facetID}:{value}]* Example: 1,SubjectEDS:food,SubjectEDS:fiction
+      # * +:view+ - Specifies the amount of data to return with the response. Either 'title': title only; 'brief' (default): Title + Source, Subjects; 'detailed': Brief + full abstract
+      # * +:actions+ - Actions to take on the existing query specification. Example: addfacetfilter(SubjectGeographic:massachusetts)
+      # * +:limiters+ - Criteria to limit the search results by. Example: LA99:English,French,German
+      # * +:expanders+ - Expanders that can be applied to the search. Either: thesaurus, fulltext, relatedsubjects
+      # * +:publication_id+ - Publication to search within.
+      # * +:related_content+ - Comma separated list of related content types to return with the search results. Either 'rs' (Research Starters) or 'emp' (Exact Publication Match)
+      # * +:auto_suggest+ - Specifies whether or not to return search suggestions along with the search results. Either true or false (default).
+      #
+      # ==== Examples
+      #
+      #   results = session.search({query: 'abraham lincoln', results_per_page: 5, related_content: ['rs','emp']})
+      #   results = session.search({query: 'volcano', results_per_page: 1, publication_id: 'eric', include_facets: false})
+      def search(options = {}, add_actions = false)
+
+        # create/recreate the search options if nil or not passing actions
+        if @search_options.nil? || !add_actions
+          @search_options = EBSCO::EDS::Options.new(options, @info)
+        end
+        #puts JSON.pretty_generate(@search_options)
+        _response = do_request(:post, path: SEARCH_URL, payload: @search_options)
+        @search_results = EBSCO::EDS::Results.new(_response)
+        @current_page = @search_results.page_number
+        @search_results
+      end
+
+      # :category: Search & Retrieve Methods
+      # Performs a simple search. All other search options assume default values.
+      #
+      # Returns search Results.
+      #
+      # ==== Attributes
+      #
+      # * +query+ - the search query.
+      #
+      # ==== Examples
+      #
+      #   results = session.simple_search('volcanoes')
+      #
+      def simple_search(query)
+        search({:query => query})
+      end
+
+      # :category: Search & Retrieve Methods
+      # Returns a Record based a particular result based on a database ID and accession number.
+      #
+      # ==== Attributes
+      #
+      # * +:dbid+ - The database ID (required).
+      # * +:an+ - The accession number (required).
+      # * +highlight+ - Comma separated list of terms to highlight in the data records (optional).
+      # * +ebook+ - Preferred format to return ebook content in. Either ebook-pdf (default) or ebook-pdf.
+      #
+      # ==== Examples
+      #   record = session.retrieve({dbid: 'asn', an: '108974507'})
+      #
+      def retrieve(dbid:, an:, highlight: nil, ebook: 'ebook-pdf')
+        payload = {:DbId => dbid, :An => an, :HighlightTerms => highlight, :EbookPreferredFormat =>  ebook}
+        retrieve_response = do_request(:post, path: RETRIEVE_URL, payload: payload)
+        EBSCO::EDS::Record.new(retrieve_response)
+      end
+
+      # :category: Search & Retrieve Methods
+      # Invalidates the session token. End Session should be called when you know a user has logged out.
+      def end
+        # todo: catch when there is no valid session?
+        do_request(:post, path: END_SESSION_URL, payload: {:SessionToken => @session_token})
+        connection.headers['x-sessionToken'] = ''
+        @session_token = ''
+      end
+
+      # :category: Search & Retrieve Methods
+      # Clear all specified query expressions, facet filters, limiters and expanders, and set the page number back to 1.
+      # Returns search Results.
+      def clear_search
+        add_actions 'ClearSearch()'
+      end
+
+      # :category: Search & Retrieve Methods
+      # Clears all queries and facet filters, and set the page number back to 1; limiters and expanders are not modified.
+      # Returns search Results.
+      def clear_queries
+        add_actions 'ClearQueries()'
+      end
+
+      # :category: Search & Retrieve Methods
+      # Add a query to the search request. When a query is added, it will be assigned an ordinal, which will be exposed
+      # in the search response message. It also removes any specified facet filters and sets the page number to 1.
+      # Returns search Results.
+      # ==== Examples
+      #   results = session.add_query('AND,California')
+      def add_query(query)
+        add_actions "AddQuery(#{query})"
+      end
+
+      # :category: Search & Retrieve Methods
+      # Removes query from the currently specified search. It also removes any specified facet filters and sets the
+      # page number to 1.
+      # Returns search Results.
+      # ==== Examples
+      #   results = session.remove_query(1)
+      def remove_query(query_id)
+        add_actions "removequery(#{query_id})"
+      end
+
+      # :category: Search & Retrieve Methods
+      # Add actions to an existing search session
+      # Returns search Results.
+      # ==== Examples
+      #   results = session.add_actions('addfacetfilter(SubjectGeographic:massachusetts)')
+      def add_actions(actions)
+        # todo: create search options if nil?
+        search(@search_options.add_actions(actions, @info), true)
+      end
+
+      # :category: Setter Methods
+      # Sets the sort for the search. The available sorts for the specified databases can be obtained from the session’s
+      # info attribute. Sets the page number back to 1.
+      # Returns search Results.
+      # ==== Examples
+      #   results = session.set_sort('newest')
+      def set_sort(val)
+        add_actions "SetSort(#{val})"
+      end
+
+      # :category: Setter Methods
+      # Sets the search mode. The available search modes are returned from the info method.
+      # Returns search Results.
+      # ==== Examples
+      #   results = session.set_search_mode('bool')
+      def set_search_mode(mode)
+        add_actions "SetSearchMode(#{mode})"
+      end
+
+      # :category: Setter Methods
+      # Specifies the view parameter. The view representes the amount of data to return with the search.
+      # Returns search Results.
+      # ==== Examples
+      #   results = session.set_view('detailed')
+      def set_view(view)
+        add_actions "SetView(#{view})"
+      end
+
+      # :category: Setter Methods
+      # Sets whether or not to turn highlighting on or off (y|n).
+      # Returns search Results.
+      # ==== Examples
+      #   results = session.set_highlight('n')
+      def set_highlight(val)
+        add_actions "SetHighlight(#{val})"
+      end
+
+      # :category: Setter Methods
+      # Sets the page size on the search request.
+      # Returns search Results.
+      # ==== Examples
+      #   results = session.results_per_page(50)
+      def results_per_page(num)
+        add_actions "SetResultsPerPage(#{num})"
+      end
+
+      # :category: Setter Methods
+      # A related content type to additionally search for and include with the search results.
+      # Returns search Results.
+      # ==== Examples
+      #   results = session.include_related_content('rs')
+      def include_related_content(val)
+        add_actions "includerelatedcontent(#{val})"
+      end
+
+      # :category: Setter Methods
+      # Specify to include facets in the results or not. Either 'y' or 'n'.
+      # Returns search Results.
+      # ==== Examples
+      #   results = session.set_include_facets('n')
+      def set_include_facets(val)
+        add_actions "SetIncludeFacets(#{val})"
+      end
+
+      # --
+      # ====================================================================================
+      # PAGINATION
+      # ====================================================================================
+      # ++
+
+      # :category: Pagination Methods
+      # Get the next page of results.
+      # Returns search Results.
+      def next_page
+        page = @current_page + 1
+        get_page(page)
+      end
+
+      # :category: Pagination Methods
+      # Get the previous page of results.
+      # Returns search Results.
+      def prev_page
+        get_page([1, @current_page - 1].sort.last)
+      end
+
+      # :category: Pagination Methods
+      # Get a specified page of results
+      # Returns search Results.
+      def get_page(page = 1)
+        add_actions "GoToPage(#{page})"
+      end
+
+      # :category: Pagination Methods
+      # Increments the current results page number by the value specified. If the current page was 5 and the specified value
+      # was 2, the page number would be set to 7.
+      # Returns search Results.
+      def move_page(num)
+        add_actions "MovePage(#{num})"
+      end
+
+      # :category: Pagination Methods
+      # Get the first page of results.
+      # Returns search Results.
+      def reset_page
+        add_actions 'ResetPaging()'
+      end
+
+      # --
+      # ====================================================================================
+      # FACETS
+      # ====================================================================================
+      # ++
+
+      # :category: Facet Methods
+      # Removes all specified facet filters. Sets the page number back to 1.
+      # Returns search Results.
+      def clear_facets
+        add_actions 'ClearFacetFilters()'
+      end
+
+      # :category: Facet Methods
+      # Adds a facet filter to the search request. Sets the page number back to 1.
+      # Returns search Results.
+      # ==== Examples
+      #   results = session.add_facet('Publisher', 'wiley-blackwell')
+      #   results = session.add_facet('SubjectEDS', 'water quality')
+      #
+      def add_facet(facet_id, facet_val)
+        add_actions "AddFacetFilter(#{facet_id}:#{facet_val})"
+      end
+
+      # :category: Facet Methods
+      # Removes a specified facet filter id. Sets the page number back to 1.
+      # Returns search Results.
+      # ==== Examples
+      #   results = session.remove_facet(45)
+      def remove_facet(group_id)
+        add_actions "RemoveFacetFilter(#{group_id})"
+      end
+
+      # :category: Facet Methods
+      # Removes a specific facet filter value from a group. Sets the page number back to 1.
+      # Returns search Results.
+      # ==== Examples
+      #   results = session.remove_facet_value(2, 'DE', 'Psychology')
+      def remove_facet_value(group_id, facet_id, facet_val)
+        add_actions "RemoveFacetFilterValue(#{group_id},#{facet_id}:#{facet_val})"
+      end
+
+      # --
+      # ====================================================================================
+      # LIMITERS
+      # ====================================================================================
+      # ++
+
+      # :category: Limiter Methods
+      # Clears all currently specified limiters and sets the page number back to 1.
+      # Returns search Results.
+      def clear_limiters
+        add_actions 'ClearLimiters()'
+      end
+
+      # :category: Limiter Methods
+      # Adds a limiter to the currently defined search and sets the page number back to 1.
+      # Returns search Results.
+      # ==== Examples
+      #   results = session.add_limiter('FT','y')
+      def add_limiter(id, val)
+        add_actions "AddLimiter(#{id}:#{val})"
+      end
+
+      # :category: Limiter Methods
+      # Removes the specified limiter and sets the page number back to 1.
+      # Returns search Results.
+      # ==== Examples
+      #   results = session.remove_limiter('FT')
+      def remove_limiter(id)
+        add_actions "RemoveLimiter(#{id})"
+      end
+
+      # :category: Limiter Methods
+      # Removes a specified limiter value and sets the page number back to 1.
+      # Returns search Results.
+      # ==== Examples
+      #   results = session.remove_limiter_value('LA99','French')
+      def remove_limiter_value(id, val)
+        add_actions "RemoveLimiterValue(#{id}:#{val})"
+      end
+
+      # --
+      # ====================================================================================
+      # EXPANDERS
+      # ====================================================================================
+      # ++
+
+      # :category: Expander Methods
+      # Removes all specified expanders and sets the page number back to 1.
+      # Returns search Results.
+      def clear_expanders
+        add_actions 'ClearExpanders()'
+      end
+
+      # :category: Expander Methods
+      # Adds expanders and sets the page number back to 1. Multiple expanders should be comma separated.
+      # Returns search Results.
+      # ==== Examples
+      #   results = session.add_expander('thesaurus,fulltext')
+      def add_expander(val)
+        add_actions "AddExpander(#{val})"
+      end
+
+      # :category: Expander Methods
+      # Removes a specified expander. Sets the page number to 1.
+      # Returns search Results.
+      # ==== Examples
+      #   results = session.remove_expander('fulltext')
+      def remove_expander(val)
+        add_actions "RemoveExpander(#{val})"
+      end
+
+      # --
+      # ====================================================================================
+      # PUBLICATION (this is only used for profiles configured for publication searching)
+      # ====================================================================================
+      # ++
+
+      # :category: Publication Methods
+      # Specifies a publication to search within. Sets the pages number back to 1.
+      # Returns search Results.
+      # ==== Examples
+      #   results = session.add_publication('eric')
+      def add_publication(pub_id)
+        add_actions "AddPublication(#{pub_id})"
+      end
+
+      # :category: Publication Methods
+      # Removes a publication from the search. Sets the page number back to 1.
+      # Returns search Results.
+      def remove_publication(pub_id)
+        add_actions "RemovePublication(#{pub_id})"
+      end
+
+      # :category: Publication Methods
+      # Removes all publications from the search. Sets the page number back to 1.
+      # Returns search Results.
+      def remove_all_publications
+        add_actions 'RemovePublication()'
+      end
+
+      # --
+      # ====================================================================================
+      # INTERNAL METHODS
+      # ====================================================================================
+      # ++
+
+      def do_request(method, path:, payload: nil, attempt: 0) # :nodoc:
+
+        if attempt > MAX_ATTEMPTS
+          raise EBSCO::EDS::ApiError, 'EBSCO API error: Multiple attempts to perform request failed.'
+        end
+
+        begin
+          resp = connection.send(method) do |req|
+            case method
+              when :get
+                req.url path
+              when :post
+                req.url path
+                unless payload.nil?
+                  req.body = JSON.generate(payload)
+                end
+              else
+                raise EBSCO::EDS::ApiError, "EBSCO API error: Method #{method} not supported for endpoint #{path}"
+            end
+          end
+          resp.body
+        rescue Exception => e
+          if e.respond_to? 'fault'
+            error_code = e.fault[:error_body]['ErrorNumber'] || e.fault[:error_body]['ErrorCode']
+            if not error_code.nil?
+              case error_code
+                # session token missing
+                when '108', '109'
+                  @session_token = create_session_token
+                  do_request(method, path: path, payload: payload, attempt: attempt+1)
+                # auth token invalid
+                when '104', '107'
+                  @auth_token = nil
+                  @auth_token = create_auth_token
+                  do_request(method, path: path, payload: payload, attempt: attempt+1)
+                else
+                  raise e
+              end
+            end
+          else
+            raise e
+          end
+        end
+      end
+
+      # --
+      # attempts to query profile capabilities
+      # dummy search just to get the list of available databases
+      # ++
+      def get_available_databases # :nodoc:
+        search({query: 'supercalifragilisticexpialidocious-supercalifragilisticexpialidocious',
+                results_per_page: 1,
+                mode: 'all',
+                include_facets: false}).database_stats
+      end
+
+      # :category: Profile Settings Methods
+      # Get a list of all available database IDs.
+      # Returns Array of IDs.
+      def get_available_database_ids
+        get_available_databases.map{|item| item[:id]}
+      end
+
+      # :category: Profile Settings Methods
+      # Determine if a database ID is available in the profile.
+      # Returns Boolean.
+      def dbid_in_profile(dbid)
+        get_available_database_ids.include? dbid
+      end
+
+      # :category: Profile Settings Methods
+      # Determine if publication matching is available in the profile.
+      # Returns Boolean.
+      def publication_match_in_profile
+        @info.available_related_content_types.include? 'emp'
+      end
+
+      # :category: Profile Settings Methods
+      # Determine if research starters are available in the profile.
+      # Returns Boolean.
+      def research_starters_match_in_profile
+        @info.available_related_content_types.include? 'rs'
+      end
+
+      private
+
+      def connection
+        Faraday.new(url: EDS_API_BASE) do |faraday|
+          faraday.headers['Content-Type'] = 'application/json;charset=UTF-8'
+          faraday.headers['Accept'] = 'application/json'
+          faraday.headers['x-sessionToken'] = @session_token ? @session_token : ''
+          faraday.headers['x-authenticationToken'] = @auth_token ? @auth_token : ''
+          faraday.headers['User-Agent'] = USER_AGENT
+          faraday.request :url_encoded
+          faraday.use FaradayMiddleware::RaiseHttpException
+          faraday.response :json, :content_type => /\bjson$/
+          #faraday.response :logger, Logger.new(LOG)
+          faraday.adapter Faraday.default_adapter
+        end
+      end
+
+      def create_auth_token
+        if blank?(@auth_token)
+          # ip auth
+          if (blank?(@user) && blank?(@pass)) || @auth_type.casecmp('ip') == 0
+            _response = do_request(:post, path: IP_AUTH_URL)
+            @auth_token = _response['AuthToken']
+          # user auth
+          else
+            _response = do_request(:post, path: UID_AUTH_URL, payload: {:UserId => @user, :Password => @pass})
+            @auth_token = _response['AuthToken']
+          end
+        end
+        @auth_token
+      end
+
+      def create_session_token
+        _response = do_request(:post, path: CREATE_SESSION_URL, payload: {:Profile => @profile, :Guest => @guest})
+        @session_token = _response['SessionToken']
+      end
+
+      # helper methods
+      def blank?(var)
+        var.nil? || var.respond_to?(:length) && var.length == 0
+      end
+
+    end
+
+  end
+end