berkeley_library-location 2.0.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af0453d4f60ad7276b64c48937b36cc76d250eb2a41ff23914f30d7c35edbf85
-  data.tar.gz: 2cb9fb72635d239f6b6726f4278b555913b9f209dddb43dbeb03072b495de3d1
+  metadata.gz: dcdd92dafd937a6dabe9cf2104e84311ae590d2db023b80c9c6fb06d0a1f3b40
+  data.tar.gz: fc15382505d0611b660cdca1e5575b780ca00a0a13cb65cf5dec1d3c2a07a501
 SHA512:
-  metadata.gz: 5a9dc82778e93207bc4f23e328b1699f4cb58abed4b7deda70cb8ec713b4c47a95d36be19fdab962b591df78c15182af841d111ef941a6d8ab2436b6587109fe
-  data.tar.gz: f6f78720f85d04530e656940d5dcaa1056cfd086de7ca280253d4a3d6aeca22a98236ad6ba2dc6666c4b3b6e765bd1e0cf3842dc69104e7b30eaa50685a69e9e
+  metadata.gz: e7f912cc954ceaf098cd7711cffc6016c0cfa945d7b63eb46e1a6c546d321962df4e76abb8e21ee8d57153590cacc7996f4d6ad4a90ae2f40fe91b46467b2e98
+  data.tar.gz: b8096c7cdc373ac6d79f0b966c2cfce33c959cc562c8b0d002ee1265ba6c0fb38eda81fb46ef8fff9accf6e033cef5b1b7e952bc96926b06eb3198235452d540

data/CHANGES.md

@@ -1,3 +1,16 @@
+# 4.0.0 (2025-01-08)
+
+- Update from Worldcat API v1 to API v2
+- Changed some of the tests from mocks to use VCR
+
+# 3.0.0 (2023-10-10)
+
+- Support duplicate OCLC numbers
+
+# 2.0.0 (2023-06-06)
+
+- Rename from "holdings" to "location"
+
 # 2.0.0 (2023-06-06)
 
 - Rename from "holdings" to "location"

data/README.md

@@ -4,3 +4,14 @@
 [![Gem Version](https://img.shields.io/gem/v/berkeley_library-location.svg)](https://github.com/BerkeleyLibrary/location/releases)
 
 Miscellaneous location-related utilities for the UC Berkeley Library.
+
+Updated to Worldcat API Version 2:
+https://developer.api.oclc.org/wcv2#/Member%20General%20Holdings/find-bib-holdings
+
+
+NOTE: For new and updated tests we've implemented the use of VCR to handle API mocks. Therefore in order to run tests, you'll need to have your API Key and Secret set as environment variables:
+LIT_WORLDCAT_API_KEY
+LIT_WORLDCAT_API_SECRET
+
+Once the cassettes are created you can force a re-recording of cassettes by adding the following ENV:
+RE_RECORD_VCR="true"

data/lib/berkeley_library/location/module_info.rb

@@ -2,12 +2,12 @@ module BerkeleyLibrary
   module Location
     module ModuleInfo
       NAME = 'berkeley_library-location'.freeze
-      AUTHOR = 'David Moles'.freeze
-      AUTHOR_EMAIL = 'dmoles@berkeley.edu'.freeze
+      AUTHOR = 'UC Berkeley Library IT'.freeze
+      AUTHOR_EMAIL = 'libdevelopers@lists.berkeley.edu'.freeze
       SUMMARY = 'Locaton-related utilities for the UC Berkeley Library'.freeze
       DESCRIPTION = 'A collection of location-related utilities for the UC Berkeley Library'.freeze
       LICENSE = 'MIT'.freeze
-      VERSION = '2.0.0'.freeze
+      VERSION = '4.0.0'.freeze
       HOMEPAGE = 'https://github.com/BerkeleyLibrary/location'.freeze
     end
   end

data/lib/berkeley_library/location/world_cat/config.rb

@@ -6,22 +6,30 @@ module BerkeleyLibrary
       module Config
         include BerkeleyLibrary::Util::URIs
 
-        # The environment variable from which to read the WorldCat API key.
+        # The environment variable from which to read the WorldCat API key and secret.
         ENV_WORLDCAT_API_KEY = 'LIT_WORLDCAT_API_KEY'.freeze
+        ENV_WORLDCAT_API_SECRET = 'LIT_WORLDCAT_API_SECRET'.freeze
 
         # The environment variable from which to read the WorldCat base URL.
         ENV_WORLDCAT_BASE_URL = 'LIT_WORLDCAT_BASE_URL'.freeze
 
+        # The environment variable from which to read the OCLC Token URL.
+        ENV_OCLC_TOKEN_URL = 'LIT_OCLC_TOKEN_URL'.freeze
+
         # The default WorldCat base URL, if ENV_WORLDCAT_BASE_URL is not set.
-        DEFAULT_WORLDCAT_BASE_URL = 'https://www.worldcat.org/webservices/'.freeze
+        # DEFAULT_WORLDCAT_BASE_URL = 'https://www.worldcat.org/webservices/'.freeze
+        DEFAULT_WORLDCAT_BASE_URL = 'https://americas.discovery.api.oclc.org/worldcat/search/v2/'.freeze
+
+        # The default OCLC Token URL, if ENV_OCLC_TOKEN_URL is not set.
+        DEFAULT_OCLC_TOKEN_URL = 'https://oauth.oclc.org/token'.freeze
 
         class << self
           include Config
         end
 
-        # Sets the WorldCat API key.
+        # Sets the WorldCat API key and secret
         # @param value [String] the API key.
-        attr_writer :api_key
+        attr_writer :api_key, :api_secret
 
         # Gets the WorldCat API key.
         # @return [String, nil] the WorldCat API key, or `nil` if not set.
@@ -29,14 +37,27 @@ module BerkeleyLibrary
           @api_key ||= default_worldcat_api_key
         end
 
+        # Sets the WorldCat API secret.
+        def api_secret
+          @api_secret ||= default_worldcat_api_secret
+        end
+
         def base_uri
           @base_uri ||= default_worldcat_base_uri
         end
 
+        def token_uri
+          @token_uri ||= default_oclc_token_uri
+        end
+
         def base_uri=(value)
           @base_uri = uri_or_nil(value)
         end
 
+        def token_uri=(value)
+          @token_uri = uri_or_nil(value)
+        end
+
         private
 
         def reset!
@@ -47,14 +68,26 @@ module BerkeleyLibrary
           ENV[ENV_WORLDCAT_API_KEY] || rails_worldcat_api_key
         end
 
+        def default_worldcat_api_secret
+          ENV[ENV_WORLDCAT_API_SECRET] || rails_worldcat_api_secret
+        end
+
         def default_worldcat_base_uri
           uri_or_nil(default_worldcat_base_url)
         end
 
+        def default_oclc_token_uri
+          uri_or_nil(default_oclc_token_url)
+        end
+
         def default_worldcat_base_url
           ENV[ENV_WORLDCAT_BASE_URL] || rails_worldcat_base_url || DEFAULT_WORLDCAT_BASE_URL
         end
 
+        def default_oclc_token_url
+          ENV[ENV_OCLC_TOKEN_URL] || rails_oclc_token_url || DEFAULT_OCLC_TOKEN_URL
+        end
+
         def rails_worldcat_base_url
           return unless (rails_config = self.rails_config)
           return unless rails_config.respond_to?(:worldcat_base_url)
@@ -62,6 +95,13 @@ module BerkeleyLibrary
           rails_config.worldcat_base_url
         end
 
+        def rails_oclc_token_url
+          return unless (rails_config = self.rails_config)
+          return unless rails_config.respond_to?(:oclc_token_url)
+
+          rails_config.oclc_token_url
+        end
+
         def rails_worldcat_api_key
           return unless (rails_config = self.rails_config)
           return unless rails_config.respond_to?(:worldcat_api_key)
@@ -69,6 +109,13 @@ module BerkeleyLibrary
           rails_config.worldcat_api_key
         end
 
+        def rails_worldcat_api_secret
+          return unless (rails_config = self.rails_config)
+          return unless rails_config.respond_to?(:worldcat_api_secret)
+
+          rails_config.worldcat_api_secret
+        end
+
         def rails_config
           return unless defined?(Rails)
           return unless (app = Rails.application)

data/lib/berkeley_library/location/world_cat/libraries_request.rb

@@ -1,55 +1,65 @@
 require 'nokogiri'
+require 'json'
+require 'jsonpath'
 require 'berkeley_library/util'
 require 'berkeley_library/location/oclc_number'
 require 'berkeley_library/location/world_cat/symbols'
+require 'berkeley_library/location/world_cat/oclc_auth'
 
 module BerkeleyLibrary
   module Location
     module WorldCat
-      # @see https://developer.api.oclc.org/wcv1#/Holdings
+      # @see https://developer.api.oclc.org/wcv2#/Member%20General%20Holdings/find-bib-holdings
       class LibrariesRequest
         include BerkeleyLibrary::Util
 
-        XPATH_INST_ID_VALS = '/holdings/holding/institutionIdentifier/value'.freeze
+        JPATH_INST_ID_VALS = '$.briefRecords[*].institutionHolding.briefHoldings[*].oclcSymbol'.freeze
 
         attr_reader :oclc_number, :symbols
 
         def initialize(oclc_number, symbols: Symbols::ALL)
+          @oclc_token = OCLCAuth.instance
           @oclc_number = OCLCNumber.ensure_oclc_number!(oclc_number)
           @symbols = Symbols.ensure_valid!(symbols)
         end
 
         def uri
-          @uri ||= URIs.append(libraries_base_uri, URIs.path_escape(oclc_number))
+          @uri ||= URIs.append(libraries_base_uri)
         end
 
-        # TODO: Check that this works w/more than 10 results
-        #       See https://developer.api.oclc.org/wcv1#/Holdings
         def params
           @params ||= {
-            'oclcsymbol' => symbols.join(','),
-            'servicelevel' => 'full',
-            'frbrGrouping' => 'off',
-            'wskey' => Config.api_key
+            'oclcNumber' => oclc_number,
+            'heldBySymbol' => symbols.join(',')
+          }
+        end
+
+        def headers
+          @headers ||= {
+            'Authorization' => "Bearer #{oclc_token.access_token}"
           }
         end
 
         def execute
-          response_body = URIs.get(uri, params:, log: false)
-          inst_symbols = inst_symbols_from(response_body)
-          inst_symbols.select { |sym| symbols.include?(sym) } # just in case
+          response_body = URIs.get(uri, params:, headers:, log: false)
+          inst_symbols_from(response_body)
         end
 
         private
 
+        # OCLC changed to a token-based authentication system
+        # separating auth from request
+        def oclc_token
+          @oclc_token ||= OCLCAuth.new
+        end
+
         def libraries_base_uri
-          URIs.append(Config.base_uri, 'catalog', 'content', 'libraries')
+          URIs.append(Config.base_uri, 'bibs-holdings')
         end
 
-        def inst_symbols_from(xml)
-          xml_doc = Nokogiri::XML(xml)
-          id_vals = xml_doc.xpath(XPATH_INST_ID_VALS)
-          id_vals.filter_map { |value| value.text.strip }
+        def inst_symbols_from(json)
+          path = JsonPath.new(JPATH_INST_ID_VALS)
+          path.on(json)
         end
       end
     end

data/lib/berkeley_library/location/world_cat/oclc_auth.rb

@@ -0,0 +1,65 @@
+require 'json'
+require 'singleton'
+
+module BerkeleyLibrary
+  module Location
+    module WorldCat
+      class OCLCAuth
+        include Singleton
+
+        attr_accessor :token
+
+        def initialize
+          # rubocop:disable Lint/DisjunctiveAssignmentInConstructor
+          @token ||= fetch_token
+          # rubocop:enable Lint/DisjunctiveAssignmentInConstructor:
+        end
+
+        def fetch_token
+          url = oclc_token_url
+
+          http = Net::HTTP.new(url.host, url.port)
+          http.use_ssl = url.scheme == 'https'
+
+          request = Net::HTTP::Post.new(url.request_uri)
+          request.basic_auth(Config.api_key, Config.api_secret)
+          request['Accept'] = 'application/json'
+          response = http.request(request)
+
+          JSON.parse(response.body, symbolize_names: true)
+        end
+
+        # def token
+        #   @token = get_token if token_expired?
+        #   @token
+        # end
+
+        def oclc_token_url
+          URI.parse("#{Config.token_uri}?#{URI.encode_www_form(token_params)}")
+        end
+
+        # Before every request check if the token is expired (OCLC tokens expire after 20 minutes)
+        def access_token
+          @token = token if token_expired?
+          @token[:access_token]
+        end
+
+        private
+
+        def token_params
+          {
+            grant_type: 'client_credentials',
+            scope: 'wcapi:view_institution_holdings'
+          }
+        end
+
+        def token_expired?
+          return true if @token.nil? || @token[:expires_at].nil?
+
+          Time.parse(@token[:expires_at]) <= Time.now
+        end
+
+      end
+    end
+  end
+end

data/lib/berkeley_library/location/xlsx_writer.rb

@@ -30,9 +30,11 @@ module BerkeleyLibrary
       end
 
       def <<(result)
-        r_index = row_index_for(result.oclc_number)
-        write_wc_cols(r_index, result) if rlf || uc
-        write_ht_cols(r_index, result) if hathi_trust
+        r_indices = row_indices_for(result.oclc_number)
+        r_indices.each do |idx|
+          write_wc_cols(idx, result) if rlf || uc
+          write_ht_cols(idx, result) if hathi_trust
+        end
       end
 
       private
@@ -57,8 +59,8 @@ module BerkeleyLibrary
         ht_col_index if hathi_trust
       end
 
-      def row_index_for(oclc_number)
-        row_index = row_index_by_oclc_number[oclc_number]
+      def row_indices_for(oclc_number)
+        row_index = row_indices_by_oclc_number[oclc_number]
         return row_index if row_index
 
         raise ArgumentError, "Unknown OCLC number: #{oclc_number}"
@@ -121,18 +123,15 @@ module BerkeleyLibrary
         @ht_err_col_index ||= ss.ensure_column!(COL_HATHI_TRUST_ERROR)
       end
 
-      def row_index_by_oclc_number
+      def row_indices_by_oclc_number
         # Start at 1 to skip header row
-        @row_index_by_oclc_number ||= (1...ss.row_count).each_with_object({}) do |r_index, r_indices|
+        @row_indices_by_oclc_number ||= (1...ss.row_count).each_with_object({}) do |r_index, r_indices|
           oclc_number_raw = ss.value_at(r_index, oclc_col_index)
           next unless oclc_number_raw
 
           oclc_number = oclc_number_raw.to_s
-          if r_indices.key?(oclc_number)
-            logger.warn("Skipping duplicate OCLC number #{oclc_number} in row #{r_index}")
-          else
-            r_indices[oclc_number] = r_index
-          end
+          r_indices[oclc_number] ||= []
+          r_indices[oclc_number] << r_index
         end
       end
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: berkeley_library-location
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 4.0.0
 platform: ruby
 authors:
-- David Moles
+- UC Berkeley Library IT
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-06-07 00:00:00.000000000 Z
+date: 2025-01-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: berkeley_library-logging
@@ -44,6 +44,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.1.9
+- !ruby/object:Gem::Dependency
+  name: jsonpath
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.8
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.8
 - !ruby/object:Gem::Dependency
   name: marcel
   requirement: !ruby/object:Gem::Requirement
@@ -218,14 +232,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.17.0
+        version: 1.7.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.17.0
+        version: 1.7.1
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -240,6 +254,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
@@ -255,7 +283,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.12'
 description: A collection of location-related utilities for the UC Berkeley Library
-email: dmoles@berkeley.edu
+email: libdevelopers@lists.berkeley.edu
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -276,6 +304,7 @@ files:
 - lib/berkeley_library/location/world_cat.rb
 - lib/berkeley_library/location/world_cat/config.rb
 - lib/berkeley_library/location/world_cat/libraries_request.rb
+- lib/berkeley_library/location/world_cat/oclc_auth.rb
 - lib/berkeley_library/location/world_cat/symbols.rb
 - lib/berkeley_library/location/xlsx_reader.rb
 - lib/berkeley_library/location/xlsx_writer.rb
@@ -306,7 +335,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.25
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: Locaton-related utilities for the UC Berkeley Library