borrow_direct 1.1.0 → 1.2.0.pre1

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    Zjk4M2VkNzA1NWRmNjY5YmNkOTYyYTcyMmUxMzA5ZDkzZWQwNWU3OA==
-  data.tar.gz: !binary |-
-    ODVhYjgxMjhkZTA1MjhjYTNlOTE1OWEwN2Y5NDVlYmZmM2M3ZjQxOA==
+SHA1:
+  metadata.gz: f894588c25613d6e9423de67e272784e910b6c8a
+  data.tar.gz: f75996b16e159cf14fe0a7454447fd13bc8a1253
 SHA512:
-  metadata.gz: !binary |-
-    MTA0MTE0NWFjMTViZjgyMmU1MWI0MGQyZTdiYmNkY2RhNTkxNTE2OWY5ZGM3
-    ZjU2M2FhYzg3ODQzYmExNzViMTI0Y2UwYjQzYjJlYmNiYmYyMmI3NDBjYTIy
-    OWRiYzdiM2M5MGFjZDRmOTkxNWQ2ZWNhMjhkN2ZhYjQ4M2VmOTc=
-  data.tar.gz: !binary |-
-    YTA4NzMxODE4OTgzMDg2ZmZjN2I0NTE0MmM1NjZlOGQwZjRiMmJkNDhjMzg3
-    Yjc0ZTg3N2I5OWYwMjQwNGRkNDc1YzIxMjk4YmRmMjcxZjY4YWNjNGM0MzIx
-    ZmVhYjc2OGU5NGY0NzBjMWY2ZDdhODU5MzM3NDU0NzUyMjBjZDE=
+  metadata.gz: b21a6e68e0bd31b355da430b08b0ff0dea9e46bbb660ea8741c0b6a041045261b3f89ce426e0a2377b2a25aefb88edbc2f1056f9658f7d3dcdd3b0bc168899f0
+  data.tar.gz: 579a230114fb40f0661d25f02ba15be1d366ad1a7e534abe8e134f1aadf1e7c54c19fbe82710372e3783e047d708f520e38ec58776f11a54838907771a6aaa99

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+sudo: false
+rvm: 
+  - 2.2.3
+  - 1.9.3
+cache: bundler

data/Gemfile

@@ -2,3 +2,5 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in borrow_direct.gemspec
 gemspec
+
+# gem 'byebug', :platforms => [:mri_20, :mri_21, :mri_22]

data/README.md

@@ -14,6 +14,14 @@ May also work with other Relais D2D setups with configuration or changes, no ide
 Some configuration at boot, perhaps in a Rails initializer:
 
 ~~~ruby
+# REQUIRED: Set your BD api_key
+BorrowDirect::Defaults.api_key = "your bd api key"
+
+# Or, you likely have a different api key for production and
+# testing/dev, if in Rails this is one way to handle that:
+BorrowDirect::Defaults.api_key = Rails.env.production? ? "production_bd_api" : "dev_bd_api"
+  
+
 # Uses BD Test system by defualt, if you want to use production system instead
 BorrowDirect::Defaults.api_base = BorrowDirect::Defaults::PRODUCTION_API_BASE
 
@@ -71,13 +79,13 @@ BorrowDirect::RequestQuery.new(patron_barcode).requests("open")
 
 ### AuthID's
 
-For BD api that requires an AuthorizationID (RequestItem and RequestQuery), our ruby
-API still accepts a barcode. The ruby code will make a separate request to retrieve
-the AuthorizationID behind the scenes. 
+All BD API's will requires an AuthorizationID as of late summer/fall 2015. 
+Our ruby API still accepts a barcode/library symbol pair instead, with both values possibly
+coming from configured local deaults. The ruby code will make a separate request to retrieve
+the AuthorizationID behind the scenes, so it can use it. 
 
-If you already have an AuthorizationID, you can set it to avoid this, but at the moment
-we have no code to rescue from expired authorization ID's (and if we did, depending on
-how often they expire, it might be less efficient than simply requesting a new one)
+If you already have an AuthorizationID, you can set pass it in to re-use, and avoid
+the extra call, using #with_auth_id on any BD API request. 
 
 ~~~ruby
 response = BorrowDirect::FindItem.new(patron_barcode).find(:isbn => isbn)
@@ -86,6 +94,11 @@ auth_id  = response.auth_id
 BorrowDirect::RequestItem.new(patron_barcode).with_auth_id(auth_id).make_request(pickup_location, :isbn => isbn)
 ~~~
 
+If you pass in an expired or bad AID, we should raise a BorrowDirect::InvalidAidError.
+(Some unpredictability and inconsistency in remote system error messages may
+prevent us from catching and classing as an InvalidAidError, if you notice report
+and we'll try to fix or report upstream.)
+
 ### Generate a query into BorrowDirect
 
 Sometimes you may want to send the user to specific search results inside the standard BorrowDirect HTML interface. We include a helper class for generating such queries. 

data/bd_metrics/finditem_measure.rb

@@ -8,6 +8,13 @@ require 'borrow_direct'
 require 'borrow_direct/find_item'
 require 'date'
 
+if ENV["ENV"].upcase == "PRODUCTION"
+  BorrowDirect::Defaults.api_base = BorrowDirect::Defaults::PRODUCTION_API_BASE
+  puts "BD PRODUCTION: #{BorrowDirect::Defaults::PRODUCTION_API_BASE}"
+end
+
+BorrowDirect::Defaults.api_key = ENV['BD_API_KEY']
+
 key = "isbn"
 sourcefile = ARGV[0] || File.expand_path("../isbn-bd-test-200.txt", __FILE__)
 
@@ -19,7 +26,7 @@ timeout = 20
 # wait one to 7 minutes. 
 delay = 60..420
 
-puts "#{ENV['BD_LIBRARY_SYMBOL']}: #{key}: #{sourcefile}: #{Time.now.localtime}"
+puts "#{ENV['BD_LIBRARY_SYMBOL']}: #{key}: #{sourcefile}: #{Time.now.localtime}: Testing at #{BorrowDirect::Defaults.api_base}"
 
 identifiers = File.readlines(sourcefile)   #.shuffle
  

data/borrow_direct.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |spec|
   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.homepage      = "https://github.com/jrochkind/borrow_direct"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0")

data/lib/borrow_direct/authentication.rb

@@ -9,16 +9,23 @@ module BorrowDirect
   class Authentication < Request
     attr_reader :patron_barcode, :patron_library_symbol
 
-    @@api_path = "/portal-service/user/authentication/patron"
+    @@api_path = "/portal-service/user/authentication"
 
     # BorrowDirect::Authentication.new(barcode)
     # BorrowDirect::Authentication.new(barcode, library_symbol)
     def initialize(patron_barcode, 
-                   patron_library_symbol = Defaults.library_symbol)
+                   patron_library_symbol = Defaults.library_symbol,
+                   api_key = Defaults.api_key)
       super(@@api_path)
 
       @patron_barcode = patron_barcode
       @patron_library_symbol = patron_library_symbol
+
+      @api_key = api_key
+
+      unless @api_key
+        raise ArgumentError, "BorrowDirect::Authentication requires an api key as third paramter or set in BorrowDirect::Defaults.api_key"
+      end
     end
 
     # Returns raw Hash results of the Authentication request
@@ -34,8 +41,8 @@ module BorrowDirect
     def get_auth_id
       response = authentication_request
 
-      if response["Authentication"] && response["Authentication"]["AuthnUserInfo"] && response["Authentication"]["AuthnUserInfo"]["AId"]
-        return response["Authentication"]["AuthnUserInfo"]["AId"]
+      if response["AuthorizationId"]
+        return response["AuthorizationId"]
       else
         raise BorrowDirect::Error.new("Could not obtain AId from Authorization API call: #{response.inspect}")
       end
@@ -43,10 +50,11 @@ module BorrowDirect
 
     def authentication_request_hash(patron_barcode, library_symbol)
       {
-        "AuthenticationInformation" => {
-          "LibrarySymbol" => library_symbol,
-          "PatronId" => patron_barcode
-        }
+        "ApiKey"        => @api_key,
+        "PartnershipId" => BorrowDirect::Defaults.partnership_id,
+        "UserGroup"     => "patron",
+        "LibrarySymbol" => library_symbol,
+        "PatronId"      => patron_barcode
       } 
     end
 

data/lib/borrow_direct/defaults.rb

@@ -13,7 +13,7 @@ module BorrowDirect
   # 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/"
+    TEST_API_BASE         = "https://rc.relais-host.com/"
     PRODUCTION_API_BASE   = "https://borrow-direct.relais-host.com/"
 
     TEST_HTML_BASE        = "https://bdtest.relaisd2d.com/service-proxy?command=query"
@@ -22,6 +22,7 @@ module BorrowDirect
     class << self
       attr_accessor :api_base, :partnership_id, :find_item_patron_barcode, :library_symbol
       attr_accessor :html_base_url
+      attr_accessor :api_key
 
       # used for HTTPClient send, connection, AND receive timeouts, so
       # theoretically could take 3x this, but unlikely, usually it's just
@@ -34,5 +35,7 @@ module BorrowDirect
     self.timeout        = 30
     self.html_base_url  = TEST_HTML_BASE
 
+    self.api_key        = nil
+
   end
 end

data/lib/borrow_direct/encryption.rb

@@ -0,0 +1,34 @@
+require 'openssl'
+require 'base64'
+
+module BorrowDirect
+  # Implements Relais' encryption protocol
+  # https://relais.atlassian.net/wiki/display/ILL/Encryption
+  #
+  # value = BorrowDirect::Encryption.new(public_key_string).encode_with_ts(api_key_or_other_data)
+  class Encryption
+    attr_reader :public_key_str
+
+    def initialize(a_public_key)
+      @public_key_str = a_public_key
+    end
+
+    # Will add on timestamp according to Relais protocol, encrypt,
+    # and Base64-encode, all per Relais protocol. 
+    def encode_with_ts(value)
+      # Not sure if this object is thread-safe, so we re-create
+      # each time. 
+
+      public_key = OpenSSL::PKey::RSA.new(self.public_key_str)
+
+      payload = "#{value}|#{self.now_timestamp}"
+
+      return Base64.encode64(public_key.public_encrypt(payload))
+    end
+
+    # Timestamp formatted how Relais wants it, in UTC
+    def now_timestamp
+      Time.now.getutc.strftime("%Y%m%d %H%M%S")
+    end
+  end
+end

data/lib/borrow_direct/error.rb

@@ -10,9 +10,15 @@ module BorrowDirect
       super(msg)      
     end
     
+    # Different services use different error codes for 'invalid aid'
+    # Not sure we can actually catch them all, but we'll try. 
+    def self.invalid_aid_code?(bd_code)
+      ["PUBFI003", "PUBRI002"].include?(bd_code)
+    end    
   end
 
   class HttpError < Error ; end
+
   class HttpTimeoutError < HttpError
     attr_reader :timeout
     def initialize(msg, timeout=nil)
@@ -20,4 +26,15 @@ module BorrowDirect
       super(msg)
     end
   end
+
+  class InvalidAidError < Error
+    attr_reader :aid
+    def initialize(msg, bd_code = nil, aid = nil)
+      msg += " (aid: #{aid})" if aid
+      super(msg, bd_code)
+      @aid = aid
+    end
+  end
+
+
 end

data/lib/borrow_direct/find_item.rb

@@ -1,5 +1,6 @@
 require 'borrow_direct'
 require 'borrow_direct/request'
+require 'borrow_direct/pickup_location'
 
 module BorrowDirect
   # The BorrowDirect FindItem service, for discovering item availability
@@ -10,6 +11,7 @@ module BorrowDirect
   #     # 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
 
@@ -24,7 +26,7 @@ module BorrowDirect
       @patron_barcode        = patron_barcode
       @patron_library_symbol = patron_library_symbol
 
-      # BD sometimes unpredictably returns this error when it means
+      # BD sometimes unpredictably returns one of these errors when it means
       # "no results", other times it doens't. We don't want to raise on it. 
       self.expected_error_codes << "PUBFI002"
     end
@@ -56,7 +58,7 @@ module BorrowDirect
         raise ArgumentError.new("Missing valid search type and value: '#{options}'")
       end
 
-      request exact_search_request_hash(search_type, search_value)
+      request exact_search_request_hash(search_type, search_value), need_auth_id(self.patron_barcode, self.patron_library_symbol)
     end
 
     # need to send a key and value for a valid exact_search type
@@ -65,7 +67,7 @@ module BorrowDirect
     # 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)
+      BorrowDirect::FindItem::Response.new find_item_request(options), self.auth_id
     end
 
     protected
@@ -79,10 +81,6 @@ module BorrowDirect
 
       hash = {
           "PartnershipId" => Defaults.partnership_id,
-          "Credentials" => {
-              "LibrarySymbol" => self.patron_library_symbol,
-              "Barcode" => self.patron_barcode
-          },
           "ExactSearch" => []
       }
 
@@ -101,8 +99,9 @@ module BorrowDirect
 
       attr_reader :response_hash
       
-      def initialize(hash)
+      def initialize(hash, auth_id)
         @response_hash = hash
+        @auth_id = auth_id
       end
 
 
@@ -123,7 +122,7 @@ module BorrowDirect
          return false
        end
 
-       return response_hash["Item"]["Available"].to_s == "true"
+       return response_hash["Available"].to_s == "true"
       end
 
       # BD thinks the item is locally available at patron's home library,
@@ -131,22 +130,37 @@ module BorrowDirect
       # Items that are available locally, and thus not requestable via BD, can
       # only be found by looking at the RequestMessage, bah       
       def locally_available?
-       h = response_hash["Item"]["RequestLink"]
-       return !! (h && h["RequestMessage"] == "This item is available locally")
+        h = response_hash["RequestLink"]
+        # Message seems to sometimes have period sometimes not. 
+        return !! (h && h["RequestMessage"] =~ /\AThis item is available locally\.?\Z/)
       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"
+        @auth_id
       end
 
       # Can be nil in some cases if not requestable?
       # if requestable?, should be an array of Strings. 
+      #
+      # This just returns BD location labels, see also #pickup_location_data to
+      # return labels and codes. 
       def pickup_locations
-        hash_key_path response_hash, "Item", "PickupLocations", "PickupLocation"
+        response_hash["PickupLocation"] && response_hash["PickupLocation"].collect {|h| h["PickupLocationDescription"] }
+      end
+
+      # Can be nil if not requestable, otherwise an array of BorrowDirect::PickupLocation
+      #
+      # See also #pickup_locations to return simply string location descriptions. 
+      # It's perhaps more careful code to use the codes too, as in this method,
+      # although Relais says just using labels and submitting them to RequestItem
+      # as a pickup location should work too. 
+      def pickup_location_data
+        unless defined? @pickup_location_data
+          @pickup_location_data = response_hash["PickupLocation"] && response_hash["PickupLocation"].collect do |hash|
+            BorrowDirect::PickupLocation.new(hash)
+          end
+        end
+        return @pickup_location_data
       end
 
 

data/lib/borrow_direct/pickup_location.rb

@@ -0,0 +1,32 @@
+module BorrowDirect
+  # Returned from FindItem::Response.pickup_locations , contains
+  # a #code and a #description .  #to_a returns a handy duple
+  # suitable for passing to Rails options_for_select
+  class PickupLocation
+    attr_reader :response_hash
+    def initialize(bd_hash)
+      if bd_hash["PickupLocationCode"].empty? || bd_hash["PickupLocationDescription"].empty?
+        raise ArgumentError, "PickupLocation requires a hash with PickupLocationCode and PickupLocationDescription, not `#{bd_hash}`"
+      end
+
+      @response_hash = bd_hash
+    end
+
+    def code
+      @response_hash["PickupLocationCode"]
+    end
+
+    def description
+      @response_hash["PickupLocationDescription"]
+    end
+
+    def to_h
+      self.response_hash
+    end
+
+    # Handy for passing to Rails options_for_select
+    def to_a
+      [self.description, self.code]
+    end
+  end
+end

data/lib/borrow_direct/request.rb

@@ -55,22 +55,29 @@ module BorrowDirect
       @http_method = :post
     end
 
-    def request(hash)
+    # First param is request hash, will be query param for GET or JSON body for POST
+    # Second param is optional AuthenticationID used by BD system -- if given,
+    # will be added to URI as "?aid=$AID", even for POST. Yep, that's Relais
+    # documented protocol eg https://relais.atlassian.net/wiki/display/ILL/Find+Item
+    def request(hash, aid = nil)
       http = http_client
-
       
-      # Mostly for debugging, store these
-      @last_request_uri = @api_uri
+      uri = @api_uri
+      if aid
+        uri += "?aid=#{CGI.escape aid}"
+      end
 
+      # Mostly for debugging, store these
+      @last_request_uri = uri
 
       start_time = Time.now
 
       if self.http_method == :post
         @last_request_json = json_request = JSON.generate(hash)        
-        http_response = http.post @api_uri, json_request, self.request_headers
+        http_response = http.post uri, json_request, self.request_headers
       elsif self.http_method == :get
         @last_request_query_params = hash
-        http_response = http.get @api_uri, hash, self.request_headers
+        http_response = http.get uri, hash, self.request_headers
       else
         raise ArgumentError.new("BorrowDirect::Request only understands http_method :get and :post, not `#{self.http_method}`")
       end
@@ -83,14 +90,18 @@ module BorrowDirect
       rescue JSON::ParserError => json_parse_exception
         nil
       end
-      
+
       # will be nil if we have none
       einfo = error_info(response_hash)
       expected_error = (einfo && self.expected_error_codes.include?(einfo.number))
 
 
       if einfo && (! expected_error)
-        raise BorrowDirect::Error.new(einfo.message, einfo.number)      
+        if BorrowDirect::Error.invalid_aid_code?(einfo.number)
+          raise BorrowDirect::InvalidAidError.new(einfo.message, einfo.number, aid)
+        else
+          raise BorrowDirect::Error.new(einfo.message, einfo.number)      
+        end
       elsif http_response.code != 200 && (! expected_error)
         raise BorrowDirect::HttpError.new("HTTP Error: #{http_response.code}: #{http_response.body}")
       elsif response_hash.nil?
@@ -179,6 +190,17 @@ module BorrowDirect
         return OpenStruct.new(:number => e["Problem"]["Code"], :message => e["Problem"]["Message"])
       end
 
+      # And one more for Auth errors! With no error number, hooray. 
+      if hash && (e = hash["AuthorizationState"]) && e["State"] == "failed"
+        return OpenStruct.new(:number => nil, :message => "AuthorizationState: State: failed")
+      end
+
+      # And yet another way!
+      if hash && (e = hash["Problem"])
+        # Code/Message appear unpredictably at different keys? 
+        return OpenStruct.new(:number => e["ErrorCode"] || e["Code"], :message => e["ErrorMessage"] || e["Message"])
+      end
+
       return nil    
     end
   end

data/lib/borrow_direct/request_item.rb

@@ -22,9 +22,10 @@ module BorrowDirect
       @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 << "PUBRI004"    
+      # BD sometimes unpredictably returns one of these errors when it means
+      # "no results", other times it doesn't. We don't want to raise on it. 
+      self.expected_error_codes << "PUBRI004"
+      self.expected_error_codes << "PUBRI003"
     end
 
     # need to send a key and value for a valid exact_search type
@@ -34,6 +35,11 @@ module BorrowDirect
     # PickupLocation to BD, which it seems to accept, not sure what it
     # does with it. 
     #
+    # pickup_location can be a BorrowDirect::PickupLocation object,
+    # or a string. If a string, BD recommends it be a CODE returned
+    # from FindItem, rather than DESCRIPTION as in the past, but we
+    # think description still works? 
+    #
     # Returns the actual complete BD response hash. You may want
     # #make_request instead
     #
@@ -55,7 +61,11 @@ module BorrowDirect
         raise ArgumentError.new("Missing valid search type and value: '#{options}'")
       end
 
-      request exact_search_request_hash(pickup_location, search_type, search_value)
+      if pickup_location.kind_of?(BorrowDirect::PickupLocation)
+        pickup_location = pickup_location.code
+      end
+
+      request exact_search_request_hash(pickup_location, search_type, search_value), need_auth_id(self.patron_barcode, self.patron_library_symbol)
     end
 
     # Pass in a BD exact search and pickup location eg
@@ -91,14 +101,12 @@ module BorrowDirect
     protected
 
     def extract_request_number(resp)
-      return (resp["Request"] && resp["Request"]["RequestNumber"])
+      return resp["RequestNumber"]
     end
 
     def exact_search_request_hash(pickup_location, type, value)
       hash = {
           "PartnershipId" => Defaults.partnership_id,
-          "AuthorizationId" => need_auth_id(self.patron_barcode, self.patron_library_symbol),
-          "PickupLocation" => pickup_location,
           "ExactSearch" => [
               {
                   "Type" => type.to_s.upcase,

data/lib/borrow_direct/request_query.rb

@@ -55,7 +55,16 @@ module BorrowDirect
         "fullRecord"  => (full_record ? "1" : "0")
       }
 
-      request query_params
+      response = request query_params
+
+      # RequestQuery sometimes returns odd 200 OK response with
+      # AuthFailed, at least as of 29 Sep 2015. Catch it and
+      # raise it properly. 
+      if response["AuthorizationState"] && response["AuthorizationState"]["State"] == false
+        raise BorrowDirect::InvalidAidError.new("API returned AuthorizationState.State == false", nil, response["AuthorizationState"]["AuthorizationId"])
+      end
+
+      return response
     end
 
     # Returns an array of BorrowDirect::RequestQuery::Item
@@ -68,7 +77,7 @@ module BorrowDirect
 
       results = []
 
-      response["QueryResult"]["MyRequestRecords"].each do |item_hash|        
+      response["MyRequestRecords"].each do |item_hash|        
         results << BorrowDirect::RequestQuery::Item.new(item_hash)
       end
 
@@ -89,11 +98,16 @@ module BorrowDirect
         # basic record values
         @request_number = hash["RequestNumber"]
         @title          = hash["Title"]
-        @date_submitted = DateTime.iso8601 hash["ISO8601DateSubmitted"]
+        if hash["ISO8601DateSubmitted"]
+          @date_submitted = DateTime.iso8601 hash["ISO8601DateSubmitted"]
+        end
         @allow_renew    = hash["AllowRenew"]
         @allow_cancel   = hash["AllowCancel"]
         @request_status = hash["RequestStatus"]
-        @request_status_date = DateTime.iso8601 hash["ISO8601RequestStatusDate"]
+
+        if hash["ISO8601RequestStatusDate"]
+          @request_status_date = DateTime.iso8601 hash["ISO8601RequestStatusDate"]
+        end
 
         # full record values
         @publicaition_type  = hash["PublicationType"]

data/lib/borrow_direct/version.rb

@@ -1,3 +1,3 @@
 module BorrowDirect
-  VERSION = "1.1.0"
+  VERSION = "1.2.0.pre1"
 end