borrow_direct 0.9.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MTNmMzNjZTU2NWY3NzJlMThhZmQ0ODExZTZmN2YwNGE2MzJmMDBhOQ==
+  data.tar.gz: !binary |-
+    NjUxMGE4MTE5YjY3OTcyYTEzOTkzYmRiN2ExYmFiZGQzY2EwZmJmOA==
+SHA512:
+  metadata.gz: !binary |-
+    YzBmODM3YzUxODBhMTY1ZmI5MTljZWE5N2Q5ODA3YWMzMGQyZWVjNzcwZDA4
+    NDYzZGZkMDI2ZjYzYjVhNDI2MmYyYzJmOGZkMmYwNDg2NjFlYzFiMzQ2YzRm
+    ZGE3MzE2MzU0MTdmMGFhODQ1NTI2ZTQ1NGZlYjdkMTdmMmFjNmM=
+  data.tar.gz: !binary |-
+    NmZmMzcwZWJiMDEyNGZiZjg2ODYwZjRiYThjNjhhZWNkNmYzNGQ0YTI1MmVm
+    YmUwOTI2MGI0OTYzZjQ1YjgxMjI0Mzk1OTcxY2I1NTc5MWJjN2QyZTJiYjg2
+    Yzk4NGJmNzBhMmJiOTc2YmM1MTVkOGY2YmFiNWY4MzVhY2YyMzg=

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in borrow_direct.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Jonathan Rochkind
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,183 @@
+[![Build Status](https://travis-ci.org/jrochkind/borrow_direct.svg)](https://travis-ci.org/jrochkind/borrow_direct)
+
+# BorrowDirect
+
+EXPERIMENTAL WORK IN PROGRESS, MAY HAVE UNSTABLE API
+
+Ruby tools for programmatic access to BorrowDirect consortial system, powered by Relais D2D software. 
+
+Using API as well as deep-linking to search results and possibly other stuff. 
+
+May also work with other Relais D2D setups with configuration or changes, no idea. 
+
+## Usage
+
+Some configuration at boot, perhaps in a Rails initializer:
+
+~~~ruby
+# Uses BD Test system by defualt, if you want to use production system instead
+BorrowDirect::Defaults.api_base = BorrowDirect::Defaults::PRODUCTION_API_BASE
+
+# Set a default BD LibrarySymbol for your library
+BorrowDirect::Defaults.library_symbol = "YOURSYMBOL"
+
+# If you want to do FindItem requests with a default generic patron
+# barcode
+BorrowDirect::Defaults.find_item_patron_barcode = "9999999"
+
+# BorrowDirect can take an awful long time to respond sometimes. 
+# How long are you willing to wait? (Seconds, default 30)
+BorrowDirect::Defaults.timeout = 10
+~~~
+
+Then you can do things. 
+
+### Find an item's requestability (FindItem api)
+
+~~~ruby
+# with default generic patron set in config find_item_patron_barcode
+response = BorrowDirect::FindItem.new.find?(:isbn => "1212121212")
+# Returns a BorrowDirect::FindItem::Response
+response.requestable?  
+response.pickup_locations
+
+# Or with specific patron, with default library symbol
+BorrowDirect::FindItem.new(patron_barcode).find(:isbn => "121212").requestable?
+~~~
+
+
+### Make a request (RequestItem api)
+~~~ruby
+request_number = BorrowDirect::RequestItem.new(patron_barcode).make_request(pickup_location, :isbn => "1212121212")
+# Will return request number, or nil if couldn't be requested. 
+# Or, use make_request! (with exclamation point) to raise if
+# can't be requested. 
+~~~
+
+### Get patron's current requests (RequestQuery api)
+
+~~~ruby
+items = BorrowDirect::RequestQuery.new(patron_barcode).requests
+# Returns an array of BorrowDirect::RequestQuery::Item
+items.each do |item|
+   item.request_number
+   item.title 
+   item.date_submitted # a ruby DateTime
+   item.request_status
+end
+
+# Or use a BD 'type' argument
+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. 
+
+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)
+
+~~~ruby
+response = BorrowDirect::FindItem.new(patron_barcode).find(:isbn => isbn)
+auth_id  = response.auth_id
+
+BorrowDirect::RequestItem.new(patron_barcode).with_auth_id(auth_id).make_request(pickup_location, :isbn => isbn)
+~~~
+
+### 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. 
+
+This helper class currently assumes you run a front-end "redirect" script to authenticate your users and send them to BorrowDirect, and depends on that. You will need to ensure your script also takes any`query=X` URL query parameter sent to it, and includes this in the auth redirect to BorrowDirect. 
+
+~~~ruby
+BorrowDirect::Defaults.html_base_url = "https://university.edu/borrow_direct_auth_redirector"
+
+# Generate a link to search results:
+BorrowDirect::GenerateQuery.new.query_url_with(:isbn => "1234435445")
+
+# Multiple fields can be included, their values will be treated
+# as phrase searches, and boolean AND'd together. All the fields
+# from the BorrowDirect "advanced search" are supported
+BorrowDirect::GenerateQuery.new.query_url_with(
+    :author => "John Smith", 
+    :title => "Some Book",
+    :keyword => "stuff",
+    :subject => "medicine",
+    :isbn => "1234435445")
+~~~
+
+Sometimes you want to generate a search for a specific known item, and use
+an ISBN if available, otherwise an author/title search. That is one of our
+own main use cases for these deep links. The `#best_known_item_query_url_with`
+method is available to automatically use ISBN if available, otherwise author/title. 
+
+The GenerateQuery class can be enhanced if there is demand; to allow more
+flexible searches (instead of always phrase searches with boolean AND); to or allow
+sending barcode directly to BD instead of relying on a local authenticating redirect
+script. 
+
+
+
+### Errors
+
+In error conditions, a BorrowDirect::Error may be thrown -- including request timeouts when
+BD is taking too long to respond. You can set timeout value with default config, or
+for each api object.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'borrow_direct'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install borrow_direct
+
+## Running tests
+
+Test coverage is with Minitest::Spec -- if more convenient, you can use Minitest::Unit
+style instead. But we do not use rspec; and we use Minispec assertion style (assert_x) not
+expectation style please (not x.must_).
+
+Run tests with 
+*`rake test`
+* or a specific test file with `ruby -Ilib:test ./test/some_test.rb`
+
+Tests are recorded with the [VCR](https://github.com/vcr/vcr) gem, 
+so tests can be re-run without actually contacting BorrowDirect server, it uses
+the recorded transactions. 
+
+To re-run tests with live HTTP connections to BD
+* delete all or some of the cassettes in `./test/vcr_cassettes`
+* set shell ENV variables `BD_LIBRARY_SYMBOL` and `BD_PATRON` to values
+  that will be used for testing, and re-recording cassettes
+* There are some constants at the top of the testing file that identify
+  ISBN's expected to have certain characteristics (like being requestable, or not).
+  If those characteristics are not true for your library, you may need to reset
+  those constants to values that meet expected conditions. 
+
+Your barcode and library symbol credentials are not stored in the VCR cassettes,
+they are filtered out. 
+
+The tests are run against the BD test system, but the email address associated
+with the `BD_PATRON` will likely still get multiple emails generated to it as a result
+of testing. 
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/borrow_direct/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+
+Rake::TestTask.new do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+end
+
+task :default => [:test]

data/bd_metrics/finditem_measure.rb

@@ -0,0 +1,61 @@
+#!/usr/bin/env ruby
+
+# ruby -Ilib:test ./bd_metrics/finditem_measure.rb
+
+require 'borrow_direct'
+require 'borrow_direct/find_item'
+
+key        = ARGV[0] || "isbn"
+sourcefile = ARGV[1] || File.expand_path("../#{key}.txt", __FILE__)
+
+puts "#{key}: #{sourcefile}"
+
+identifiers = File.readlines(sourcefile).shuffle
+
+puts "  #{identifiers.count} total input identifiers"
+
+times = []
+errors = []
+finder = BorrowDirect::FindItem.new(ENV["BD_FINDITEM_PATRON"], ENV["BD_LIBRARY_SYMBOL"])
+
+
+at_exit do
+  puts "\n\nERRORS: "
+  errors.each do |arr|
+    puts arr.inspect
+  end
+end
+
+i = 0
+identifiers.each do |id|
+  id = id.chomp
+  i = i + 1
+
+  start = Time.now
+
+  begin
+    finder.find_item_request(key => id)
+  rescue BorrowDirect::Error => e
+    errors << [key, id, e]
+  end
+  elapsed = Time.now - start
+
+  times << elapsed
+  times.sort!
+
+  if i % 10 == 0
+    min       = times[0]
+    tenth     = times[(times.count / 10) - 1]
+    median    = times[(times.count / 2) - 1]
+    seventyfifth = times[(times.count - (times.count / 4)) - 1]
+    ninetieth = times[(times.count - (times.count / 10)) - 1]
+    ninetyninth = times[(times.count - (times.count / 100)) - 1]
+
+    max       = times[times.count - 1]
+
+    puts "i==#{i}; min: #{min}; 10th %ile: #{tenth}; median: #{median}; 75th %ile: #{seventyfifth}; 90th %ile: #{ninetieth}; 99th %ile: #{ninetyninth}; max: #{max}"
+    puts "    errors: #{errors.count}"
+  end
+
+end
+