borrow_direct 0.9.0

data/bd_metrics/oclc.txt

@@ -0,0 +1,167 @@
+10065659
+10586552
+1081684
+10904204
+1124917
+11803073
+11910543
+123077828
+123209896
+12748813
+1331857
+1379728
+1424222
+1434991
+1478791
+1480801
+14814735
+1536398
+1564931
+1565627
+1567377
+1586310
+1638942
+1639814
+16402936
+1643323
+1644869
+1645522
+1714985
+1751778
+1751795
+1752305
+1755507
+1763246
+1764190
+1765691
+1767509
+1779849
+18141357
+18654422
+190859513
+2033274
+20400968
+22167445
+2251554
+226114275
+2264017
+232115955
+232117723
+24072815
+2410175
+2445140
+2464767
+247189142
+2520764
+29874562
+2993219
+300267691
+30404911
+31042626
+31218891
+31949646
+3306860
+34085858
+34134679
+34601690
+36289392
+36491673
+36818836
+36950362
+37320198
+37939040
+38161063
+38309698
+38537165
+38589589
+38866515
+38871666
+38911795
+38912661
+38945637
+39003731
+3900884
+39148292
+39224682
+41070319
+41092744
+41407365
+41882904
+41973550
+41978558
+42635201
+4339970
+43437977
+43573821
+43829445
+44178619
+44519004
+44520978
+44685364
+44715152
+45267760
+45421405
+4652347
+46822658
+47075834
+47076058
+47377635
+47671164
+47727849
+47810818
+47815833
+48017624
+48151618
+48801390
+48880094
+48887313
+49286131
+49604992
+498003413
+49849538
+49920040
+50167015
+50245479
+50427037
+50732308
+50784557
+51244236
+51761890
+52616475
+54449599
+5461534
+55201024
+5520474
+55737776
+55803866
+57004362
+57378025
+60616144
+60620970
+60623349
+60624664
+60626878
+60627706
+60628611
+607405987
+61125729
+611639238
+61311169
+613617204
+61523343
+6291542
+6294105
+641269190
+6415579
+67618577
+696271299
+702602240
+762029593
+809393
+8287652
+830989328
+84844215
+85489765
+94139525
+9438862
+

data/borrow_direct.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'borrow_direct/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "borrow_direct"
+  spec.version       = BorrowDirect::VERSION
+  spec.authors       = ["Jonathan Rochkind"]
+  spec.email         = ["jonathan@dnil.net"]
+  spec.summary       = %q{Ruby tools for interacting with the Borrow Direct consortial services}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "httpclient", "~> 2.4"
+
+  #spec.add_development_dependency "bundler", ">= 1.6.2", "< 2"
+  spec.add_development_dependency "rake", "~> 10.0"
+
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "minitest-vcr", ">= 1.0.2", "< 2"
+  spec.add_development_dependency "vcr", "~> 2.9"
+  spec.add_development_dependency "webmock", "~> 1.11"
+
+end

data/lib/borrow_direct/authentication.rb

@@ -0,0 +1,55 @@
+require 'borrow_direct/request'
+
+module BorrowDirect
+
+  # The BD Authorization API
+  # http://borrowdirect.pbworks.com/w/file/83346673/Authorization%20Service.docx  
+  #
+  # For now, always calls with 'patron' type. 
+  class Authentication < Request
+    attr_reader :patron_barcode, :patron_library_symbol
+
+    @@api_path = "/portal-service/user/authentication/patron"
+
+    # BorrowDirect::Authentication.new(barcode)
+    # BorrowDirect::Authentication.new(barcode, library_symbol)
+    def initialize(patron_barcode, 
+                   patron_library_symbol = Defaults.library_symbol)
+      super(@@api_path)
+
+      @patron_barcode = patron_barcode
+      @patron_library_symbol = patron_library_symbol
+    end
+
+    # Returns raw Hash results of the Authentication request
+    # See also #get_auth_id
+    def authentication_request
+      self.request authentication_request_hash(self.patron_barcode, self.patron_library_symbol)
+    end
+
+    # Makes a request and returns the "AId" value which is used as input
+    # "AuthorizationId" in other API calls. 
+    #
+    # If one can't be obtained for some reason, will raise BorrowDirect::Error
+    def get_auth_id
+      response = authentication_request
+
+      if response["Authentication"] && response["Authentication"]["AuthnUserInfo"] && response["Authentication"]["AuthnUserInfo"]["AId"]
+        return response["Authentication"]["AuthnUserInfo"]["AId"]
+      else
+        raise BorrowDirect::Error.new("Could not obtain AId from Authorization API call: #{response.inspect}")
+      end
+    end
+
+    def authentication_request_hash(patron_barcode, library_symbol)
+      {
+        "AuthenticationInformation" => {
+          "LibrarySymbol" => library_symbol,
+          "PatronId" => patron_barcode
+        }
+      } 
+    end
+
+  end
+
+end

data/lib/borrow_direct/defaults.rb

@@ -0,0 +1,38 @@
+require 'borrow_direct'
+
+module BorrowDirect
+  # Some defaults for BD requests, including some you might def want to set
+  # at app boot, perhaps in a Rails initializer. 
+  #
+  # To use the production BD system instead of test system:
+  #      BorrowDirect::Defaults.api_base = BorrowDirect::Defaults::PRODUCTION_API_BASE
+  #
+  # To set your library's BD symbol as a default:
+  #      BorrowDirect::Defaults.library_symbol = "YOURSYMBOL"
+  #
+  # To set a default generic patron barcode to use for FindItem requests
+  #      BorrowDirect::Defaults.find_item_patron_barcode = "99999999999"
+  class Defaults
+    TEST_API_BASE         = "https://bdtest.relais-host.com/"
+    PRODUCTION_API_BASE   = "NOT_YET_AVAILABLE"
+
+    TEST_HTML_BASE        = "https://bdtest.relaisd2d.com/service-proxy?command=query"
+    PRODUCTION_HTML_BASE  = "https://borrow-direct.relaisd2d.com/service-proxy?command=query"
+    
+    class << self
+      attr_accessor :api_base, :partnership_id, :find_item_patron_barcode, :library_symbol
+      attr_accessor :html_base_url
+
+      # used for HTTPClient send, connection, AND receive timeouts, so
+      # theoretically could take 3x this, but unlikely, usually it's just
+      # receive that might timeout. In seconds. Default 30s.
+      attr_accessor :timeout    
+    end
+
+    self.api_base       = BorrowDirect::Defaults::TEST_API_BASE
+    self.partnership_id = "BD"
+    self.timeout        = 30
+    self.html_base_url  = TEST_HTML_BASE
+
+  end
+end

data/lib/borrow_direct/error.rb

@@ -0,0 +1,17 @@
+module BorrowDirect
+  class Error < StandardError
+    attr_reader :bd_code
+
+    def initialize(msg, bd_code = nil) 
+      @bd_code = bd_code
+      if @bd_code
+        msg = "#{@bd_code}: #{msg}"
+      end
+      super(msg)      
+    end
+    
+  end
+
+  class HttpError < Error ; end
+  class HttpTimeoutError < HttpError ; end
+end

data/lib/borrow_direct/find_item.rb

@@ -0,0 +1,149 @@
+require 'borrow_direct'
+require 'borrow_direct/request'
+
+module BorrowDirect
+  # The BorrowDirect FindItem service, for discovering item availability
+  # http://borrowdirect.pbworks.com/w/file/83346676/Find%20Item%20Service.docx
+  #
+  #     BorrowDirect::FindItem.new(patron_barcode).bd_requestability?(:isbn => isbn)
+  #     # or set BorrowDirect::Defaults.find_item_patron_barcode to make patron barcode
+  #     # optional and use a default patron barcode
+  #
+  # You can also use #find_item_request to get the raw BD response as a ruby hash
+  class FindItem < Request
+    attr_reader :patron_barcode, :patron_library_symbol
+
+    @@api_path = "/dws/item/available"
+    @@valid_search_types = %w{ISBN ISSN LCCN OCLC PHRASE}
+
+
+    def initialize(patron_barcode = Defaults.find_item_patron_barcode, 
+                   patron_library_symbol = Defaults.library_symbol)
+      super(@@api_path)
+
+      @patron_barcode        = patron_barcode
+      @patron_library_symbol = patron_library_symbol
+
+      # BD sometimes unpredictably returns this error when it means
+      # "no results", other times it doens't. We don't want to raise on it. 
+      self.expected_error_codes << "PUBFI002"
+    end
+
+    # need to send a key and value for a valid exact_search type
+    # type can be string or symbol, lowercase or uppercase. 
+    #
+    # Returns the actual complete BD response hash. You may want
+    # #bd_requestable? instead
+    #
+    #    finder.find_item_request(:isbn => "12345545456")
+    #
+    # You can request multiple values which BD will treat as an 'OR'/union -- sort
+    # of. BD does unpredictable things here, be careful. 
+    #
+    #     finder.find_item_request(:isbn => ["12345545456", "99999999"])
+    def find_item_request(options)
+      search_type, search_value = nil, nil
+      options.each_pair do |key, value|
+        if @@valid_search_types.include? key.to_s.upcase
+          if search_type || search_value
+            raise ArgumentError.new("Only one search criteria at a time is allowed: '#{options}'")
+          end
+
+          search_type, search_value = key, value
+        end
+      end
+      unless search_type && search_value
+        raise ArgumentError.new("Missing valid search type and value: '#{options}'")
+      end
+
+      request exact_search_request_hash(search_type, search_value)
+    end
+
+    # need to send a key and value for a valid exact_search type
+    # type can be string or symbol, lowercase or uppercase. 
+    #
+    # Returns a BorrowDirect::FindItem::Response object, from which you
+    # can find out requestability, list of pickup locations, etc. 
+    def find(options)
+      BorrowDirect::FindItem::Response.new find_item_request(options)
+    end
+
+    protected
+
+    # Produce BD request hash for exact search of type eg "ISBN"
+    # value can be a singel value, or an array of values. For array,
+    # BD will "OR" them. 
+    def exact_search_request_hash(type, value)
+      # turn it into an array if it's not one already
+      values = Array(value)
+
+      hash = {
+          "PartnershipId" => Defaults.partnership_id,
+          "Credentials" => {
+              "LibrarySymbol" => self.patron_library_symbol,
+              "Barcode" => self.patron_barcode
+          },
+          "ExactSearch" => []
+      }
+
+      values.each do |value|
+        hash["ExactSearch"] << {
+            "Type" => type.to_s.upcase,
+            "Value" => value
+        }
+      end
+    
+      return hash
+    end
+
+    class Response
+      include BorrowDirect::Util
+
+      attr_reader :response_hash
+      
+      def initialize(hash)
+        @response_hash = hash
+      end
+
+
+      # Returns true or false -- can the item actually be requested
+      # via BorrowDirect. 
+      #
+      #    finder.find(:isbn => "12345545456").requestable?
+      def requestable?
+        # Sometimes a PUBFI002 error code isn't really an error,
+        # but just means not available. 
+        if response_hash && response_hash["Error"] && (response_hash["Error"]["ErrorNumber"] == "PUBFI002")
+          return false
+        end
+
+       # Items that are available locally, and thus not requestable via BD, can
+       # only be found by looking at the RequestMessage, bah
+       h = response_hash["Item"]["RequestLink"]
+       if h && h["RequestMessage"] == "This item is available locally"
+         return false
+       end
+
+       return response_hash["Item"]["Available"].to_s == "true"
+      end
+
+      # Returns the AuthorizationID returned by FindItem API call,
+      # or nil if none is available. Nil _can_ be returned, for
+      # instance when BD returns a NotFound error instead of a good
+      # response. 
+      def auth_id
+        hash_key_path response_hash, "Item", "AuthorizationId"
+      end
+
+      # Can be nil in some cases if not requestable?
+      # if requestable?, should be an array of Strings. 
+      def pickup_locations
+        hash_key_path response_hash, "Item", "PickupLocations", "PickupLocation"
+      end
+
+
+    end
+
+
+  end
+end

data/lib/borrow_direct/generate_query.rb

@@ -0,0 +1,78 @@
+require 'cgi'
+
+module BorrowDirect
+  # Generate a "deep link" to query results in BD's native
+  # HTML interface. 
+  class GenerateQuery
+    attr_accessor :url_base
+
+    # Hash from our own API argument to BD field code
+    @@fields = {
+      :keyword  => "term",
+      :title    => "ti",
+      :author   => "au",
+      :subject  => "su",
+      :isbn     => "isbn",
+      :issn     => "issn"
+    }
+
+    def initialize(url_base = nil)
+      self.url_base = (url_base || BorrowDirect::Defaults.html_base_url)
+    end
+
+    # query_with(:title => "one two", :author => "three four")
+    # valid keys are those supported by BD HTML interface:
+    #     :title, :author, :isbn, :subject, :keyword, :isbn, :issn
+    #
+    # For now, the value is always searched as a phrase, and multiple
+    # fields are always 'and'd.  We may enhance/expand later. 
+    #
+    # Returns an un-escaped query, still needs to be put into a URL
+    def query_with(options)
+      clauses = []
+
+      options.each_pair do |field, value|
+        code = @@fields[field]
+
+        raise ArgumentError.new("Don't recognize field code `#{field}`") unless code
+
+        clauses << %Q{#{code}="#{escape_query_value value}"}
+      end
+
+      return clauses.join(" and ")
+    end
+
+    # Pass in :title, :author, :isbn, etc -- if we have an isbn or issn,
+    # we'll use that alone, otherwise we'll use title and author
+    def best_known_item_query_with(options)
+      if options[:isbn]
+        return query_with(options.dup.delete_if {|k| k != :isbn})
+      elsif options[:issn]
+        return query_with(options.dup.delete_if {|k| k != :issn})
+      else
+        return query_with options
+      end
+    end
+
+    def query_url_with(options)
+      query = query_with(options)
+
+      return self.url_base + '?' + "query=#{CGI.escape query}"
+    end
+
+    def best_known_item_query_url_with(options)
+      query = best_known_item_query_with(options)
+
+      return self.url_base + '?' + "query=#{CGI.escape query}"      
+    end
+
+    # We don't really know how to escape, for now
+    # we just remove double quotes and parens, and replace with spaces. 
+    # those seem to cause problems, and that seems to work. 
+    def escape_query_value(str)
+      str.gsub(/[")()]/, ' ')
+    end
+
+
+  end
+end