folio_api_client 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1529c6d23ad243ce9503b24965a0afc4db6abd28a6cea7aae1000b42b5a19b0
-  data.tar.gz: 8da619e1c7614fe9bf46951af5ee6c086467ec90869d0f32ba9803584b65487a
+  metadata.gz: b95e817f47b4694776baae831bcad7784810d06e7533577f27f8bcf4ea216b06
+  data.tar.gz: 63291ad25685d7c4ba71dd2399104b8925241da84eca2483f8bd63b4567b4454
 SHA512:
-  metadata.gz: c6196344ec464f39dfdd0b44dbd269f3b949a630c7a41d449961a73091f494ad1d49edff1eb39d2f79b4d36ee0b9f6456257cb2ca645a4d8d1a4c8f0b3c50cd0
-  data.tar.gz: 064356b0fe0d418128ae36d101005229d3eb766f89a62456a6b024bedb5a9d748e42335177918985c34a2bef7ed4a0168c54f38b6bea58a5fd2ed3b0508e86f4
+  metadata.gz: '018541167173b30bbf0c938c10465888581fd87d8c64885fd59dfcc3ea4a2305e93d75533f55c752b7eb495ee2b72be7b8514246caffe7bdebbe56b18f5f44ee'
+  data.tar.gz: 7812af3dbf43c33aa37c490e8a0a084de82842b64bcdc86571c0eb9e713ad293884f7ff03098d26d15acd75bbcb4a73a89d7f2c2d4eee6e1f32eccf1233405bf

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2025 The Trustees of Columbia University in the City of New York
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -42,6 +42,20 @@ client.get(path, params)
 client.post(path, body, content_type: 'application/json'))
 client.put(path, body, content_type: 'application/json'))
 client.delete(path, body, content_type: 'application/json'))
+
+# Other convenience methods:
+
+client.find_item_record(barcode: 'some-barcode')
+client.find_location_record(location_id: 'some-location-id')
+client.find_holdings_record(holdings_record_id: 'some-holdings-record-id')
+client.find_instance_record(instance_record_id: 'some-instance-record-id')
+client.find_instance_record(instance_record_hrid: 'some-instance-record-hrid')
+client.find_source_record(instance_record_id: 'some-instance-record-id')
+client.find_source_record(instance_record_hrid: 'some-instance-record-hrid')
+
+# Convert a FOLIO MARC source record to a marc gem MARC::Record object:
+source_record = client.find_source_record(instance_record_id: 'some-instance-record-id')
+marc_record = MARC::Record.new_from_hash(source_record['parsedRecord']['content'])
 ```
 
 See [https://dev.folio.org/reference/api/](https://dev.folio.org/reference/api/) for the full list of available FOLIO API endpoints.

data/lib/folio_api_client/exceptions.rb

@@ -4,5 +4,6 @@ class FolioApiClient
   module Exceptions
     class Error < StandardError; end
     class UnexpectedMultipleRecordsFoundError < Error; end
+    class MissingQueryFieldError < Error; end
   end
 end

data/lib/folio_api_client/finders.rb

@@ -11,28 +11,71 @@ class FolioApiClient
               'Only expected one item with this barcode, but found more than one.'
       end
 
-      item_record_id = item_search_results.first['id']
-      self.get("/item-storage/items/#{item_record_id}")
+      item_search_results.first
     end
 
     def find_location_record(location_id:)
       self.get("/locations/#{location_id}")
     end
 
+    def find_loan_type_record(loan_type_id:)
+      self.get("/loan-types/#{loan_type_id}")
+    end
+
     def find_holdings_record(holdings_record_id:)
       self.get("/holdings-storage/holdings/#{holdings_record_id}")
     end
 
-    def find_instance_record(instance_record_id:)
-      self.get("/instance-storage/instances/#{instance_record_id}")
+    def find_instance_record(instance_record_id: nil, instance_record_hrid: nil)
+      instance_search_results = self.get(
+        '/instance-storage/instances',
+        instance_record_query(instance_record_id: instance_record_id, instance_record_hrid: instance_record_hrid)
+      )['instances']
+      return nil if instance_search_results.empty?
+
+      if instance_search_results.length > 1
+        raise FolioApiClient::Exceptions::UnexpectedMultipleRecordsFoundError,
+              'Only expected one instance with this '\
+              "#{instance_record_id ? 'instance_record_id' : 'instance_record_hrid'}, "\
+              'but found more than one.'
+      end
+
+      instance_search_results.first
     end
 
-    def find_marc_record(instance_record_id:)
-      source_record_search_results = self.get('/source-storage/source-records', { instanceId: instance_record_id })
+    # Find a source record by its instance record id or instance record hrid.
+    # @return [Hash] A Source Record (which can hold data for a MARC record).
+    def find_source_record(instance_record_id: nil, instance_record_hrid: nil)
+      source_record_search_results = self.get(
+        '/source-storage/source-records',
+        source_record_query(instance_record_id: instance_record_id, instance_record_hrid: instance_record_hrid)
+      )
       return nil if source_record_search_results['totalRecords'].zero?
 
-      bib_record_marc_hash = source_record_search_results['sourceRecords'].first['parsedRecord']['content']
-      MARC::Record.new_from_hash(bib_record_marc_hash)
+      if source_record_search_results['totalRecords'] > 1
+        raise FolioApiClient::Exceptions::UnexpectedMultipleRecordsFoundError,
+              'Only expected one record with this '\
+              "#{instance_record_id ? 'instance_record_id' : 'instance_record_hrid'}, "\
+              'but found more than one.'
+      end
+
+      source_record_search_results['sourceRecords'].first
+    end
+
+    def source_record_query(instance_record_id: nil, instance_record_hrid: nil)
+      return { instanceId: instance_record_id } if instance_record_id
+      return { instanceHrid: instance_record_hrid } if instance_record_hrid
+
+      raise FolioApiClient::Exceptions::MissingQueryFieldError,
+            'Missing query field.  Must supply either an instance_record_id or instance_record_hrid.'
+    end
+
+    def instance_record_query(instance_record_id: nil, instance_record_hrid: nil)
+      return { query: "id==#{instance_record_id}", limit: 2 } if instance_record_id
+      return { query: "hrid==#{instance_record_hrid}", limit: 2 } if instance_record_hrid
+
+      raise FolioApiClient::Exceptions::MissingQueryFieldError,
+            'Missing query field.  Must supply either an instance_record_id or instance_record_hrid.'
     end
   end
 end

data/lib/folio_api_client/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class FolioApiClient
-  VERSION = '0.2.0'
+  VERSION = '0.4.0'
 end

data/lib/folio_api_client.rb

@@ -38,7 +38,7 @@ class FolioApiClient
   end
 
   def retrieve_new_auth_token
-    response = connection.post('/authn/login', { username: config.username, password: config.password }.to_json)
+    response = connection.post('/authn/login', JSON.generate({ username: config.username, password: config.password }))
     response_data = JSON.parse(response.body)
     response_data['okapiToken']
   end
@@ -68,12 +68,12 @@ class FolioApiClient
   end
 
   def exec_request_with_body(method, path, body = nil, content_type: 'application/json')
-    body = body.to_json if content_type == 'application/json' && !body.is_a?(String)
+    body = JSON.generate(body) if content_type == 'application/json' && !body.is_a?(String)
     response = with_token_refresh_attempt_when_unauthorized do
       connection.send(method, path, body, { 'x-okapi-token': config.token, 'content-type': content_type })
     end
 
-    response.body.nil? ? nil : JSON.parse(response.body)
+    response.body.nil? || response.body == '' ? nil : JSON.parse(response.body)
   end
 
   def post(path, body = nil, content_type: 'application/json')

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: folio_api_client
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Eric O'Hanlon
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-30 00:00:00.000000000 Z
+date: 2025-06-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -63,6 +63,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
+- LICENSE
 - README.md
 - Rakefile
 - lib/folio_api_client.rb
@@ -71,7 +72,8 @@ files:
 - lib/folio_api_client/finders.rb
 - lib/folio_api_client/version.rb
 homepage: https://www.github.com/cul/folio_api_client
-licenses: []
+licenses:
+- Apache-2.0
 metadata:
   homepage_uri: https://www.github.com/cul/folio_api_client
   source_code_uri: https://www.github.com/cul/folio_api_client