folio_client 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 51efd566f32da4e9349cde6c853d91b25db7db35be7f046e5cc8ae445470c25e
-  data.tar.gz: b244ae8d8d496baeb51c3e43834bc2f330fe04cbb943ad2e652efdfacbe0a6aa
+  metadata.gz: f400cbad25cc1f7a7a4af985a510c597af5dea7b18cf636d5e6cb8196b4ef059
+  data.tar.gz: 26d9485bebd8780fafe498b15827575703316c229ed8c35e361aee3246ee70fd
 SHA512:
-  metadata.gz: 16a20ff6ec80f84d828f773ff8c3b1eeeda67dd0472674134aa975a822b37d0d9f86c65ef3ccb03d26c800ffa3a001386d973a77c03ab8d1ef9aeda7dfd312f4
-  data.tar.gz: e34c0b895a3bfea9174a6836c0a5af28afd1de88743430ba3b2d75494ebe42675e8e1b7a9015823e1e065ba28ed6dbbea864111cf5dd05fc3f5f7b8daf3938b7
+  metadata.gz: 472ca9f6c928aa3353b8f928cce63030329e62a7c26655700aaaef6c835e777f58d0771c8b58d8bfd50ee59a7c2c1724063246884ab529556b7cd92ee2065dfd
+  data.tar.gz: 2add95c0f3492db0c80f1770c40576d7bbac019a31674a9b0124a47706b065e1b02e67735519dddc2cf4f832216d453ddb3126906a4c89f4d4eac1f59c70fd6d

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    folio_client (0.7.0)
+    folio_client (0.9.0)
       activesupport (>= 4.2, < 8)
       dry-monads
       faraday
@@ -11,7 +11,7 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (7.0.4.2)
+    activesupport (7.0.4.3)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
@@ -47,7 +47,7 @@ GEM
       unf
     minitest (5.18.0)
     parallel (1.22.1)
-    parser (3.2.1.0)
+    parser (3.2.1.1)
       ast (~> 2.4.1)
     public_suffix (5.0.1)
     rainbow (3.1.1)
@@ -63,28 +63,28 @@ GEM
     rspec-expectations (3.12.2)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
-    rspec-mocks (3.12.3)
+    rspec-mocks (3.12.4)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
     rspec-support (3.12.0)
-    rubocop (1.44.1)
+    rubocop (1.48.1)
       json (~> 2.3)
       parallel (~> 1.10)
       parser (>= 3.2.0.0)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.24.1, < 2.0)
+      rubocop-ast (>= 1.26.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 3.0)
     rubocop-ast (1.27.0)
       parser (>= 3.2.1.0)
     rubocop-capybara (2.17.1)
       rubocop (~> 1.41)
-    rubocop-performance (1.15.2)
+    rubocop-performance (1.16.0)
       rubocop (>= 1.7.0, < 2.0)
       rubocop-ast (>= 0.4.0)
-    rubocop-rspec (2.18.1)
+    rubocop-rspec (2.19.0)
       rubocop (~> 1.33)
       rubocop-capybara (~> 2.17)
     ruby-progressbar (1.13.0)
@@ -96,10 +96,10 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.12.3)
     simplecov_json_formatter (0.1.4)
-    standard (1.24.3)
+    standard (1.25.2)
       language_server-protocol (~> 3.17.0.2)
-      rubocop (= 1.44.1)
-      rubocop-performance (= 1.15.2)
+      rubocop (= 1.48.1)
+      rubocop-performance (= 1.16.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
     unf (0.1.4)

data/README.md

@@ -65,13 +65,13 @@ client.fetch_hrid(barcode: "12345")
  => "a7927874"
 
 # Request a MARC record given an instance hrid
-# returns a hash if found; raises FolioClient::UnexpectedResponse::ResourceNotFound if instance_hrid not found
+# returns a hash if found; raises FolioClient::ResourceNotFound if instance_hrid not found
 client.fetch_marc_hash(instance_hrid: "a7927874")
  => {"fields"=>
   [{"003"=>"FOLIO"}....]
   }
 
-# Import a MARC record
+# Import a MARC record into FOLIO
 data_importer = client.data_import(marc: my_marc, job_profile_id: '4ba4f4ab', job_profile_name: 'ETDs')
 # If called too quickly, might get Failure(:not_found)
 data_importer.status
@@ -80,6 +80,17 @@ data_importer.wait_until_complete
  => Success()
 data_importer.instance_hrid
  => Success("in00000000010")
+
+# Create a Holdings record
+holdings_client = client.holdings(instance_id: "99a6d818-d523-42f3-9844-81cf3187dbad")
+holdings_client.create(permanent_location_id: "1b14e21c-8d47-45c7-bc49-456a0086422b", holdings_type_id: "996f93e2-5b5e-4cf2-9168-33ced1f95eed")
+ => {
+    "id" => "581f6289-001f-49d1-bab7-035f4d878cbd",
+    "_version" => 1,
+    "hrid" => "ho00000000065",
+    "holdingsTypeId" => "996f93e2-5b5e-4cf2-9168-33ced1f95eed"
+    ...
+ }
 ```
 
 ## Development

data/lib/folio_client/holdings.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class FolioClient
+  # Manage holdings records in the Folio inventory
+  class Holdings
+    attr_accessor :client, :instance_id
+
+    # @param client [FolioClient] the configured client
+    # @param instance_id [String] the UUID of the instance to which the holdings record belongs
+    def initialize(client, instance_id:)
+      @client = client
+      @instance_id = instance_id
+    end
+
+    # create a holdings record for the instance
+    # @param permanent_location_id [String] the UUID of the permanent location
+    # @param holdings_type_id [String] the UUID of the holdings type
+    def create(holdings_type_id:, permanent_location_id:)
+      client.post("/holdings-storage/holdings", {
+        instanceId: instance_id,
+        permanentLocationId: permanent_location_id,
+        holdingsTypeId: holdings_type_id
+      })
+    end
+  end
+end

data/lib/folio_client/inventory.rb

@@ -10,8 +10,9 @@ class FolioClient
       @client = client
     end
 
-    # @param barcode [String] barcode to search by to fetch the HRID
-    # @return [String,nil] HRID if present, otherwise nil.
+    # get instance HRID from barcode
+    # @param barcode [String] barcode
+    # @return [String,nil] instance HRID if present, otherwise nil.
     def fetch_hrid(barcode:)
       # find the instance UUID for this barcode
       instance = client.get("/search/instances", {query: "items.barcode==#{barcode}"})
@@ -24,9 +25,38 @@ class FolioClient
       result.dig("hrid")
     end
 
-    # @param hrid [String] folio instance HRID
+    # get instance external ID from HRID
+    # @param hrid [String] instance HRID
+    # @return [String,nil] instance external ID if present, otherwise nil.
+    # @raise [ResourceNotFound, MultipleResourcesFound] if search does not return exactly 1 result
+    def fetch_external_id(hrid:)
+      instance_response = client.get("/search/instances", {query: "hrid==#{hrid}"})
+      record_count = instance_response["totalRecords"]
+      raise ResourceNotFound, "No matching instance found for #{hrid}" if instance_response["totalRecords"] == 0
+      raise MultipleResourcesFound, "Expected 1 record for #{hrid}, but found #{record_count}" if record_count > 1
+
+      instance_response.dig("instances", 0, "id")
+    end
+
+    # Retrieve basic information about a instance record.  Example usage: get the external ID and _version for update using
+    #  optimistic locking when the HRID is available: `fetch_instance_info(hrid: 'a1234').slice('id', '_version')`
+    #  (or vice versa if the external ID is available).
+    # @param external_id [String] an external ID for the desired instance record
+    # @param hrid [String] an instance HRID for the desired instance record
+    # @return [Hash] information about the record.
+    # @raise [ArgumentError] if the caller does not provide exactly one of external_id or hrid
+    def fetch_instance_info(external_id: nil, hrid: nil)
+      raise ArgumentError, "must pass exactly one of external_id or HRID" unless external_id.present? || hrid.present?
+      raise ArgumentError, "must pass exactly one of external_id or HRID" if external_id.present? && hrid.present?
+
+      external_id ||= fetch_external_id(hrid: hrid)
+      client.get("/inventory/instances/#{external_id}")
+    end
+
+    # @param hrid [String] instance HRID
     # @param status_id [String] uuid for an instance status code
-    # @raise [ResourceNotFound] if search by hrid returns 0 results
+    # @return true if instance status matches the uuid param, false otherwise
+    # @raise [ResourceNotFound] if search by instance HRID returns 0 results
     def has_instance_status?(hrid:, status_id:)
       # get the instance record and its statusId
       instance = client.get("/inventory/instances", {query: "hrid==#{hrid}"})

data/lib/folio_client/job_status.rb

@@ -87,7 +87,7 @@ class FolioClient
     def check_not_found(result, index)
       return unless result.failure? && result.failure == :not_found && index > 2
 
-      raise ResourceNotFound, "Job not found"
+      raise ResourceNotFound, "Job #{job_execution_id} not found after #{index} retries"
     end
   end
 end

data/lib/folio_client/records_editor.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+class FolioClient
+  class RecordsEditor
+    attr_accessor :client
+
+    # @param client [FolioClient] the configured client
+    def initialize(client)
+      @client = client
+    end
+
+    # Given an HRID, retrieves the associated MARC JSON, yields it to the caller as a hash,
+    # and attempts to re-save it, using optimistic locking to prevent accidental overwrite,
+    # in case another user or process has updated the record in the time between retrieval and
+    # attempted save.
+    # @param hrid [String] the HRID of the MARC record to be edited and saved
+    # @yieldparam record_json [Hash] a hash representation of the MARC JSON for the
+    #  HRID; the updated hash will be saved when control is returned from the block.
+    # @note in limited manual testing, optimistic locking behaved like so when two edit attempts collided:
+    #   * One updating client would eventually raise a timeout.  This updating client would actually write successfully, and version the record.
+    #   * The other updating client would raise a StandardError, with a message like 'duplicate key value violates unique constraint \"idx_records_matched_id_gen\"'.
+    #     This client would fail to write.
+    #   * As opposed to the expected behavior of the "winner" getting a 200 ok response, and the "loser" getting a 409 conflict response.
+    # @todo If this is a problem in practice, see if it's possible to have Folio respond in a more standard way; or, workaround with error handling.
+    def edit_marc_json(hrid:)
+      instance_info = client.fetch_instance_info(hrid: hrid)
+
+      version = instance_info["_version"]
+      external_id = instance_info["id"]
+
+      record_json = client.get("/records-editor/records", {externalId: external_id})
+
+      parsed_record_id = record_json["parsedRecordId"]
+      record_json["relatedRecordVersion"] = version # setting this field on the JSON we send back is what will allow optimistic locking to catch stale updates
+
+      yield record_json
+
+      client.put("/records-editor/records/#{parsed_record_id}", record_json)
+    end
+  end
+end

data/lib/folio_client/source_storage.rb

@@ -10,6 +10,7 @@ class FolioClient
       @client = client
     end
 
+    # get marc bib data from folio given an instance HRID
     # @param instance_hrid [String] the key to use for MARC lookup
     # @return [Hash] hash representation of the MARC. should be usable by MARC::Record.new_from_hash (from ruby-marc gem)
     # @raises NotFound, MultipleRecordsForIdentifier

data/lib/folio_client/unexpected_response.rb

@@ -13,7 +13,7 @@ class FolioClient
       when 404
         raise ResourceNotFound, "Endpoint not found or resource does not exist: #{response.body}"
       when 422
-        raise UnauthorizedError, "There was a problem fetching the access token: #{response.body} "
+        raise ValidationError, "There was a validation problem with the request: #{response.body} "
       when 500
         raise ServiceUnavailable, "The remote server returned an internal server error."
       else

data/lib/folio_client/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class FolioClient
-  VERSION = "0.7.0"
+  VERSION = "0.9.0"
 end

data/lib/folio_client.rb

@@ -17,7 +17,7 @@ class FolioClient
   # Base class for all FolioClient errors
   class Error < StandardError; end
 
-  # Error raised by the Folio Auth API returns a 422 Unauthorized
+  # Error raised by the Folio Auth API returns a 401 Unauthorized
   class UnauthorizedError < Error; end
 
   # Error raised when the Folio API returns a 404 NotFound, or returns 0 results when one was expected
@@ -32,6 +32,9 @@ class FolioClient
   # Error raised when the Folio API returns a 500
   class ServiceUnavailable < Error; end
 
+  # Error raised when the Folio API returns a 422 Unprocessable Entity
+  class ValidationError < Error; end
+
   DEFAULT_HEADERS = {
     accept: "application/json, text/plain",
     content_type: "application/json"
@@ -49,8 +52,8 @@ class FolioClient
       self
     end
 
-    delegate :config, :connection, :get, :post, to: :instance
-    delegate :fetch_hrid, :fetch_marc_hash, :has_instance_status?, :data_import, to: :instance
+    delegate :config, :connection, :get, :post, :put, to: :instance
+    delegate :fetch_hrid, :fetch_external_id, :fetch_instance_info, :fetch_marc_hash, :has_instance_status?, :data_import, :holdings, :edit_marc_json, to: :instance
   end
 
   attr_accessor :config
@@ -91,6 +94,27 @@ class FolioClient
     JSON.parse(response.body)
   end
 
+  # Send an authenticated put request
+  # If the body is JSON, it will be automatically serialized
+  # @param path [String] the path to the Folio API request
+  # @param body [Object] body to put to the API as JSON
+  def put(path, body = nil, content_type: "application/json")
+    req_body = (content_type == "application/json") ? body&.to_json : body
+    response = TokenWrapper.refresh(config, connection) do
+      req_headers = {
+        "x-okapi-token": config.token,
+        "content-type": content_type
+      }
+      connection.put(path, req_body, req_headers)
+    end
+
+    UnexpectedResponse.call(response) unless response.success?
+
+    return nil if response.body.blank?
+
+    JSON.parse(response.body)
+  end
+
   # the base connection to the Folio API
   def connection
     @connection ||= Faraday.new(
@@ -106,6 +130,18 @@ class FolioClient
       .fetch_hrid(...)
   end
 
+  def fetch_external_id(...)
+    Inventory
+      .new(self)
+      .fetch_external_id(...)
+  end
+
+  def fetch_instance_info(...)
+    Inventory
+      .new(self)
+      .fetch_instance_info(...)
+  end
+
   def fetch_marc_hash(...)
     SourceStorage
       .new(self)
@@ -123,4 +159,15 @@ class FolioClient
       .new(self)
       .import(...)
   end
+
+  def holdings(...)
+    Holdings
+      .new(self, ...)
+  end
+
+  def edit_marc_json(...)
+    RecordsEditor
+      .new(self)
+      .edit_marc_json(...)
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: folio_client
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Peter Mangiafico
-autorequire:
+autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-03-07 00:00:00.000000000 Z
+date: 2023-03-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -191,8 +191,10 @@ files:
 - lib/folio_client.rb
 - lib/folio_client/authenticator.rb
 - lib/folio_client/data_import.rb
+- lib/folio_client/holdings.rb
 - lib/folio_client/inventory.rb
 - lib/folio_client/job_status.rb
+- lib/folio_client/records_editor.rb
 - lib/folio_client/source_storage.rb
 - lib/folio_client/token_wrapper.rb
 - lib/folio_client/unexpected_response.rb
@@ -204,7 +206,7 @@ metadata:
   source_code_uri: https://github.com/sul-dlss/folio_client
   changelog_uri: https://github.com/sul-dlss/folio_client/releases
   rubygems_mfa_required: 'true'
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -219,8 +221,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
-signing_key:
+rubygems_version: 3.3.7
+signing_key: 
 specification_version: 4
 summary: Interface for interacting with the Folio ILS API.
 test_files: []