folio_api_client 0.4.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9101df88d1bcae72de9607a5646631b5b4a3ecb2f281f4e81064ea47b1ee9b3
-  data.tar.gz: b9e838309973de0b1b66069bf2aa7c6a5c96f32f8a6b8d167a8cb9cc07d87626
+  metadata.gz: 4f56685abde3488956608b9a829b88079a22ed2dac7608ed792b1c6eafc2e662
+  data.tar.gz: 1fafd404369f0a3061c079e7922da6caea6735cb8b4a2e943512af815aaf3621
 SHA512:
-  metadata.gz: 5f087226a449dc37b26445d40f0d99fe752c6f9203123bc0d6aef87f050a5257c0c6b371ee7441905406454933ecb9d37df1c539a21a82f068d6ded468902663
-  data.tar.gz: e8d41ca37c67901d6db368509e72f1360bcd509e71a179aa6443defe544d145bcef7a2a56e0f1a40c16dae7ad1d914c0a3e1f36d9d6197470d08479883307e8b
+  metadata.gz: '09241496ff463b9c8f01a9b2a801698908d426cc30080ca72a81a2b09480a0ba8b116a7b1f2f6cad1ad13f53ae00872b202f3faff30d306ab18620ceaee40266'
+  data.tar.gz: 2a33854f99b12cbf278573a8e4ec3eed28474bb9b14a4ca9af8089905718952d2b804daf810006c8ecea6c9cb7d4620fec3ec5d9b7d00a9502bf5f1a87efda29

data/README.md

@@ -54,6 +54,9 @@ 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')
+client.find_source_marc_records(modified_since: '2025-01-01T00:00:00Z') { |marc_record_hash| }
+client.find_source_marc_records(with_965_value: '965abc') { |marc_record_hash| }
+client.find_source_marc_records(modified_since: '2025-01-01T00:00:00Z', with_965_value: '965abc') { |marc_record_hash| }
 
 # 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')

data/lib/folio_api_client/finders.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class FolioApiClient
-  module Finders
+  module Finders # rubocop:disable Metrics/ModuleLength
     def find_item_record(barcode:)
       item_search_results = self.get('/item-storage/items', { query: "barcode==#{barcode}", limit: 2 })['items']
       return nil if item_search_results.empty?
@@ -90,6 +90,52 @@ class FolioApiClient
       source_record_search_results['sourceRecords'].first
     end
 
+    # Retrieve and yield marc records, filtered by the given modified_since and with_965_value parameters.
+    # NOTE: This method skips staff-suppressed FOLIO records.
+    def find_source_marc_records(modified_since: nil, with_965_value: nil, &block) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+      # FOLIO does not allow an offset value higher than 9999, but this method needs to be able to retrieve
+      # result sets that have more than 9999 results, so we break big queries up into a bunch of smaller
+      # queries that split up the results based on the first character of the instance UUIDs.  The first character
+      # of a UUID is a hex character (0-9 or a-f), which means that we will perform 16 different searches
+      # (i.e. "all of the results that have instance ids that start with a", then "all of the results that have
+      # instance ids that start with b", and so on).
+
+      # Since we're splitting up the query into a bunch of different sub-queries, we need to do a
+      # non-prefix-filtered query first just to get the total number of results.
+      total_query = response = self.get(
+        'search/instances',
+        marc_records_query(modified_since: modified_since, with_965_value: with_965_value).merge({ limit: 0 })
+      )
+      total_records = total_query['totalRecords']
+
+      with_uuid_prefixes do |uuid_prefix|
+        query = marc_records_query(modified_since: modified_since, with_965_value: with_965_value,
+                                   uuid_prefix: uuid_prefix)
+        loop do
+          response = self.get('search/instances', query)
+          process_marc_for_instance(response['instances'], total_records, &block) if block
+          break if (query[:offset] + query[:limit]) >= response['totalRecords']
+
+          query[:offset] += query[:limit]
+        end
+      end
+    end
+
+    # UUIDs can start with
+    def with_uuid_prefixes(&block)
+      (('0'..'9').to_a + ('a'..'f').to_a).each(&block)
+    end
+
+    def process_marc_for_instance(instances, total_records, &block)
+      instances.each do |instance|
+        source_record = find_source_record(instance_record_id: instance['id'])
+        next if source_record.nil? # Occasionally, we find an instance record without a source record.  Skip these.
+
+        marc_content = source_record.dig('parsedRecord', 'content')
+        yield(marc_content, total_records) if marc_content && block
+      end
+    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
@@ -112,5 +158,34 @@ class FolioApiClient
       raise FolioApiClient::Exceptions::MissingQueryFieldError,
             'Missing query field.  Must supply a code.'
     end
+
+    def marc_records_query(modified_since: nil, with_965_value: nil, uuid_prefix: nil) # rubocop:disable Metrics/MethodLength,Metrics/CyclomaticComplexity
+      params = { limit: 100, offset: 0 }
+
+      if modified_since.nil? && with_965_value.nil?
+        raise FolioApiClient::Exceptions::MissingQueryFieldError,
+              'Missing query field.  Must supply either modified_since or with_965_value.'
+      end
+
+      if modified_since && !modified_since.match(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/)
+        raise ArgumentError,
+              %(Invalid format for modified_since argument. Must be a date string like "2025-10-03T16:49:00Z".)
+      end
+
+      query_parts = []
+      query_parts << "metadata.updatedDate>=\"#{modified_since}\"" if modified_since
+      query_parts << %(identifiers.value="#{with_965_value}") if with_965_value
+
+      # Only include non-staff-suppressed records because staff-suppressed records represent deleted records in FOLIO.
+      # Reminder: staff-suppressed records are NOT the same as discovery-suppressed records.  Discovery-suppressed
+      # records are ones that aren't displayed to the public, and we DO want to include discovery-suppressed records
+      # in the results returned by this query.
+      query_parts << 'staffSuppress==false'
+
+      query_parts << %(id="#{uuid_prefix}*") if uuid_prefix
+
+      params[:query] = query_parts.join(' and ')
+      params
+    end
   end
 end

data/lib/folio_api_client/version.rb

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

data/lib/folio_api_client.rb

@@ -55,6 +55,12 @@ class FolioApiClient
     # one time in responde to a 401 or 403.
     refresh_auth_token!
 
+    # Re-run block
+    yield
+  rescue Faraday::ConnectionFailed
+    # If we make too many rapid requests in a row, FOLIO sometimes disconnects.
+    # If this happens, we'll sleep for a little while and retry the request.
+    sleep 5
     # Re-run block
     yield
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: folio_api_client
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.5.0
 platform: ruby
 authors:
 - Eric O'Hanlon
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-25 00:00:00.000000000 Z
+date: 2025-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday