borrow_direct 0.9.0

data/lib/borrow_direct/request.rb

@@ -0,0 +1,185 @@
+require 'json'
+require 'httpclient'
+require 'ostruct'
+
+require 'borrow_direct'
+
+module BorrowDirect
+  # Generic abstract BD request, put in a Hash request body, get
+  # back a Hash answer. 
+  #  
+  #    response_hash = Request.new("/path/to/endpoint").request(request_hash)
+  #
+  # Typically, clients will use various sub-classes of Request implementing
+  # calling of individual BD API's
+  # 
+  # ## AuthenticationID's
+  #
+  # Some API endpoints require an "AId"/"AuthencationID". BorrowDirect::Request
+  # provides some facilities for managing obtaining such (using Authentication API),
+  # usually will be used under the hood by Request subclasses. 
+  #
+  #     # fetch new auth ID using Authentication API, store it
+  #     # in self.auth_id
+  #     request.fetch_auth_id!(barcode, library_symbol)  
+  #
+  #     # return the existing value in self.auth_id, or if
+  #     # nil run fetch_auth_id! to fill it out. 
+  #     request.need_auth_id(barcode, library_symbol)
+  #     
+  #     request.auth_id # cached or nil
+  class Request
+    attr_writer :http_client
+    attr_accessor :timeout
+    attr_accessor :auth_id
+    # default :post, but can be set to :get, usually by a subclass
+    attr_accessor :http_method
+    attr_reader :last_request_uri, :last_request_json, :last_request_response, :last_request_time
+
+    # Usually an error code from the server will be turned into an exception. 
+    # But if there are error codes you expect (usually fixed in a subclass of Request),
+    # fill them in this array, and the responses will be returned anyway -- warning,
+    # REGARDLESS of HTTP response status code, as these are often non-200 but we want
+    # to catch em anyway. 
+    attr_accessor :expected_error_codes
+
+    def initialize(path)
+      @api_base = Defaults.api_base
+      @api_path = path
+
+      @api_uri = @api_base.chomp("/") + @api_path
+
+      @expected_error_codes = []
+
+      @timeout = Defaults.timeout
+      @http_method = :post
+    end
+
+    def request(hash)
+      http = http_client
+
+      
+      # Mostly for debugging, store these
+      @last_request_uri = @api_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
+      elsif self.http_method == :get
+        @last_request_query_params = hash
+        http_response = http.get @api_uri, hash, self.request_headers
+      else
+        raise ArgumentError.new("BorrowDirect::Request only understands http_method :get and :post, not `#{self.http_method}`")
+      end
+
+      @last_request_response = http_response
+      @last_request_time     = Time.now - start_time
+
+      response_hash = begin
+        JSON.parse(http_response.body)
+      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)      
+      elsif http_response.code != 200 && (! expected_error)
+        raise BorrowDirect::HttpError.new("HTTP Error: #{http_response.code}: #{http_response.body}")
+      elsif response_hash.nil?
+        raise BorrowDirect::Error.new("Could not parse expected JSON response: #{http_response.code} #{json_parse_exception}: #{http_response.body}")
+      end
+
+      
+
+      return response_hash
+    rescue HTTPClient::ReceiveTimeoutError => e
+      elapsed = Time.now - start_time
+      raise BorrowDirect::HttpTimeoutError.new("Timeout after #{elapsed}s connecting to BorrowDirect server at #{@api_base}")
+    end
+
+    def http_client
+      @http_client ||= make_http_client!
+    end
+
+    # For now, we can send same request headers for all requests. May have to
+    # make parameterized later. 
+    # Note SOME but not all BD API endpoints REQUIRE User-Agent and 
+    # Accept-Language (for no discernable reason)
+    #
+    # NOTE WELL: API sometimes requires User-Agent _not to change_ when using
+    # an AuthorizationID, or it will revoke your authorization. Need to use the
+    # same User-Agent when using an auth_id as you used when receiving it. 
+    def request_headers
+      { "Content-Type" => "application/json", 
+        "User-Agent" => "ruby borrow_direct gem #{BorrowDirect::VERSION} (HTTPClient #{HTTPClient::VERSION}) https://github.com/jrochkind/borrow_direct", 
+        "Accept-Language" => "en"
+      }
+    end
+
+    # Fetches new authID, stores it in self.auth_id, overwriting
+    # any previous value there. Will raise BorrowDirect::Error if no auth
+    # could be fetched. 
+    #
+    # returns auth_id too. 
+    def fetch_auth_id!(barcode, library_symbol)
+      auth = Authentication.new(barcode, library_symbol)
+      # use the same HTTPClient so we use the same HTTP connection, perhaps
+      # slightly more performance worth a shot. 
+      auth.http_client = http_client
+      self.auth_id = auth.get_auth_id
+    end
+
+    # Will use value in self.auth_id, or if nil will
+    # fetch a value with fetch_auth_id! and return that. 
+    def need_auth_id(barcode, library_symbol)
+      self.auth_id || fetch_auth_id!(barcode, library_symbol)
+    end
+
+    # Can be used to set an already existing AuthID to be used. 
+    # Beware, we have no facility for rescuing from escpired auth ids
+    # at the moment. 
+    def with_auth_id(aid)
+      self.auth_id = aid
+      return self
+    end
+
+
+
+
+    protected
+
+    def make_http_client!
+      http = HTTPClient.new
+      if self.timeout
+        http.send_timeout    = self.timeout
+        http.connect_timeout = self.timeout
+        http.receive_timeout    = self.timeout
+      end
+
+      return http
+    end
+
+    # returns an OpenStruct with #message and #number, 
+    # or nil if error info can not be extracted
+    def error_info(hash)      
+      if hash && (e = hash["Error"]) && (e["ErrorNumber"] || e["ErrorMessage"])
+        return OpenStruct.new(:number => e["ErrorNumber"], :message => e["ErrorMessage"])
+      end
+
+      # Or wait! Some API's have a totally different way of reporting errors, great!
+      if hash && (e = hash["Authentication"]) && e["Problem"] 
+        return OpenStruct.new(:number => e["Problem"]["Code"], :message => e["Problem"]["Message"])
+      end
+
+      return nil    
+    end
+  end
+end

data/lib/borrow_direct/request_item.rb

@@ -0,0 +1,119 @@
+require 'borrow_direct'
+require 'borrow_direct/request'
+
+module BorrowDirect
+  # The BorrowDirect RequestItem service, for placing a request
+  # http://borrowdirect.pbworks.com/w/file/86126056/RequestItem.docx
+  #
+  # You can also use #find_item_request to get the raw BD response as a ruby hash
+  class RequestItem < Request
+    attr_reader :patron_barcode, :patron_library_symbol
+    attr_reader :authorization_id
+
+    @@api_path = "/dws/item/add"
+    @@valid_search_types = %w{ISBN ISSN LCCN OCLC Control }
+
+
+    
+    def initialize(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 << "PUBRI004"    
+    end
+
+    # need to send a key and value for a valid exact_search type
+    # type can be string or symbol, lowercase or uppercase. 
+    #
+    # Also a pickup_location -- can pass in nil, and we'll send no
+    # PickupLocation to BD, which it seems to accept, not sure what it
+    # does with it. 
+    #
+    # Returns the actual complete BD response hash. You may want
+    # #make_request instead
+    #
+    #    finder.request_item_request(pickup_location, :isbn => "12345545456")
+    #    finder.request_item_request(pickup_location, :lccn => "12345545456")
+    #    finder.request_item_request(pickup_location, :oclc => "12345545456")
+    def request_item_request(pickup_location, 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(pickup_location, search_type, search_value)
+    end
+
+    # Pass in a BD exact search and pickup location eg
+    #     make_request(pickup_location, :isbn => isbn)
+    #
+    # Pass in nil for pickup_location if... not sure exactly what
+    # BD will do, but it does allow it. 
+    #
+    # Returns the BD RequestNumber, or nil if a request could
+    # not be made
+    #
+    # See also make_request! to raise if request can not be made
+    def make_request(pickup_location, options)
+      resp = request_item_request(pickup_location, options)
+
+      return extract_request_number(resp)
+    end
+
+    # Like make_request, but will raise a BorrowDirect::Error if
+    # item can't be requested. 
+    def make_request!(pickup_location, options)
+      resp = request_item_request(pickup_location, options)
+
+      number = extract_request_number(resp)
+
+      if number.nil?
+        raise BorrowDirect::Error.new("Can not request for: #{options.inspect}: #{resp.inspect}")
+      end
+
+      return number
+    end
+
+    protected
+
+    def extract_request_number(resp)
+      return (resp["Request"] && resp["Request"]["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,
+                  "Value" => value
+              }
+          ]
+      }
+
+      if pickup_location
+        hash["PickupLocation"] = pickup_location
+      end
+
+      return hash
+    end
+
+
+  end
+end

data/lib/borrow_direct/request_query.rb

@@ -0,0 +1,124 @@
+require 'borrow_direct'
+require 'date'
+
+module BorrowDirect
+  # Info from Relais/BD on type and status:
+  #
+  # valid 'type' values for requests:
+  #
+  #  xdays: Retrieve requests submitted within the last xdays (for example, one would include two parameters: type=xdays&xdays=7 to retrieve requests submitted within the last 7 days)
+  #  all: Retrieve all request submitted by the user
+  #  open: Retrieve all open requests i.e. requests which haven't been fulfilled yet.
+  #  allposttoweb: BD doesn't use the post-to-web application; you can ignore this.
+  #  unopenedposttoweb: You can safely ignore this.
+  #  onloan: Retrieve requests which are on loan
+  #
+  # possible RequestStatus values in results:
+  #
+  #  ENTERED: Request has been entered and yet to be processed.
+  #  IN_PROCESS: Request is being processed.
+  #  CANCELLED: Request has been cancelled.
+  #  UNFILLED: Request can't be filled.
+  #  SHIPPED: Item has been shipped.
+  #  ARTICLE_SENT: A scanned document or an electronic document has been sent (It doesn't apply to BD)
+  #  ON_LOAN: Request is on loan.
+  #  OVERDUE: Item is over due.
+  #  COMPLETE: Item has been returned and request is completed.
+  #  UNKNOWN: You should never see this; this indicates there is probably an inconsistency with the record somewhere. You probably want to flag and report this. 
+  class RequestQuery < Request
+    attr_reader :patron_barcode, :patron_library_symbol
+
+    @@api_path = "/portal-service/request/query/my"   
+
+    # I'm not exactly sure what these mean either. 
+    @@query_types = %w{xdays all open allposttoweb unopenedposttoweb onloan}
+
+
+    def initialize(patron_barcode,
+                   patron_library_symbol = Defaults.library_symbol)
+      super(@@api_path)
+
+      @patron_barcode        = patron_barcode
+      @patron_library_symbol = patron_library_symbol
+      self.http_method = :get
+    end
+
+    # Returns raw BD response as a hash. 
+    # * type defaults to 'all', but can be BD values of xdays, all
+    #   open, allposttoweb, unopenedposttoweb, onloan. 
+    #   xdays not really supported yet, cause no way to pass an xdays param yet
+    # * full_record can be true or false, defaults to false. 
+    def request_query_request(type = "all", full_record = false)
+      query_params = {
+        "aid"         => need_auth_id(patron_barcode, patron_library_symbol),
+        "type"        => type.to_s,
+        "fullRecord"  => (full_record ? "1" : "0")
+      }
+
+      request query_params
+    end
+
+    # Returns an array of BorrowDirect::RequestQuery::Item
+    # * type defaults to 'all', but can be BD values of xdays, all
+    #   open, allposttoweb, unopenedposttoweb, onloan. 
+    #   xdays not really supported yet, cause no way to pass an xdays param yet
+    # * full_record can be true or false, defaults to false. 
+    def requests(*args)
+      response = request_query_request(*args)
+
+      results = []
+
+      response["QueryResult"]["MyRequestRecords"].each do |item_hash|        
+        results << BorrowDirect::RequestQuery::Item.new(item_hash)
+      end
+
+      return results
+    end
+
+    class Item
+      # fullRecord == 0 values
+      attr_reader :request_number, :title, :date_submitted, :allow_renew, 
+                  :allow_cancel, :request_status, :request_status_date
+      # fullRecord == 1 values, not all are applicable for BorrowDirect,
+      # and many may be nil. 
+      attr_reader :publication_type, :publication_date, :publication_place, 
+                  :volume, :issue, :edition, :issn, :issn2, :isbn, :isbn2,
+                  :ismn, :pages_requested, :delivery_date
+
+      def initialize(hash)
+        # basic record values
+        @request_number = hash["RequestNumber"]
+        @title          = hash["Title"]
+        @date_submitted = DateTime.iso8601 hash["ISO8601DateSubmitted"]
+        @allow_renew    = hash["AllowRenew"]
+        @allow_cancel   = hash["AllowCancel"]
+        @request_status = hash["RequestStatus"]
+        @request_status_date = DateTime.iso8601 hash["ISO8601RequestStatusDate"]
+
+        # full record values
+        @publicaition_type  = hash["PublicationType"]
+        @publication_date   = hash["PublicationDate"] # BD just gives us a string
+        @publication_place  = hash["PublicationPlace"]
+        @volume             = hash["Volume"]
+        @issue              = hash["Issue"]
+        @edition            = hash["Edition"]
+        @issn               = hash["Issn"]
+        @issn2              = hash["Issn2"]
+        @isbn               = hash["Isbn"]
+        @isbn2              = hash["Isbn2"]
+        @ismn               = hash["Ismn"]
+        @pages_requested    = hash["PagesRequested"]
+        if hash["ISO8601DeliveryDate"]
+          @delivery_date      = DateTime.iso8601 hash["ISO8601DeliveryDate"]
+        end
+      end
+    end
+
+  end
+
+
+
+
+
+
+end

data/lib/borrow_direct/util.rb

@@ -0,0 +1,18 @@
+module BorrowDirect
+  module Util
+    # A utility method that lets you access a nested hash, 
+    # returning nil if any intermediate hashes are unavailable. 
+    def hash_key_path(hash, *path)
+      result = nil
+
+      path.each do |key|
+        return nil unless hash.respond_to? :"[]"
+        result = hash = hash[key]
+      end
+
+      return result
+    end
+    module_function :hash_key_path
+
+  end
+end

data/lib/borrow_direct/version.rb

@@ -0,0 +1,3 @@
+module BorrowDirect
+  VERSION = "0.9.0"
+end

data/lib/borrow_direct.rb

@@ -0,0 +1,19 @@
+require "borrow_direct/version"
+
+require 'borrow_direct/defaults'
+require 'borrow_direct/error'
+require 'borrow_direct/util'
+
+require 'borrow_direct/authentication'
+
+require 'borrow_direct/request'
+require 'borrow_direct/find_item'
+require 'borrow_direct/request_item'
+require 'borrow_direct/request_query'
+
+require 'borrow_direct/generate_query'
+
+
+module BorrowDirect
+
+end

data/test/authentication_test.rb

@@ -0,0 +1,79 @@
+require 'test_helper'
+require 'json'
+require 'httpclient'
+
+
+describe "Authentication", :vcr => {:tag => :bd_auth} do
+  describe "raw request to verify HTTP api" do
+    it "works" do
+      uri = BorrowDirect::Defaults.api_base.chomp("/") + "/portal-service/user/authentication/patron"
+
+
+      request_hash = {
+        "AuthenticationInformation" => {
+          "LibrarySymbol" => VCRFilter[:bd_library_symbol],
+          "PatronId" => VCRFilter[:bd_patron]
+        }
+      } 
+
+      http = HTTPClient.new
+      response = http.post uri, JSON.generate(request_hash), {"Content-Type" => "application/json", "User-Agent" => "ruby borrow_direct gem (#{BorrowDirect::VERSION}) https://github.com/jrochkind/borrow_direct", "Accept-Language" => "en"}
+
+      assert_equal 200, response.code
+      assert_present response.body
+
+      response_hash = JSON.parse response.body
+
+      assert_present response_hash
+
+      assert_present response_hash["Authentication"]["AuthnUserInfo"]["AId"]
+    end
+  end
+
+  it "Makes a request succesfully" do
+    bd = BorrowDirect::Authentication.new(VCRFilter[:bd_patron] , VCRFilter[:bd_library_symbol])
+    response = bd.authentication_request
+
+    assert_present response
+    assert_present response["Authentication"]["AuthnUserInfo"]["AId"]
+  end
+
+  it "Raises for bad library symbol" do
+    bd = BorrowDirect::Authentication.new(VCRFilter[:bd_patron] , "BAD_SYMBOL")
+    assert_raises(BorrowDirect::Error) do
+      bd.authentication_request
+    end
+  end
+
+  it "Raises for bad patron barcode" do
+    bd = BorrowDirect::Authentication.new("BAD_BARCODE", VCRFilter[:bd_library_symbol])
+    assert_raises(BorrowDirect::Error) do
+      bd.authentication_request
+    end
+  end
+
+  describe "get_auth_id" do
+    it "returns an auth_id for a good request" do
+      bd = BorrowDirect::Authentication.new(VCRFilter[:bd_patron] , VCRFilter[:bd_library_symbol])
+      assert_present bd.get_auth_id
+    end
+
+    it "raises for a bad library symbol" do
+      bd = BorrowDirect::Authentication.new(VCRFilter[:bd_patron] , "BAD_SYMBOL")
+      assert_raises(BorrowDirect::Error) do
+        bd.get_auth_id
+      end
+    end
+
+    it "raises for a bad patron barcode" do
+      bd = BorrowDirect::Authentication.new("BAD_BARCODE", VCRFilter[:bd_library_symbol])
+      assert_raises(BorrowDirect::Error) do
+        bd.get_auth_id
+      end
+    end
+
+  end
+
+
+
+end