folio_client 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 51efd566f32da4e9349cde6c853d91b25db7db35be7f046e5cc8ae445470c25e
-  data.tar.gz: b244ae8d8d496baeb51c3e43834bc2f330fe04cbb943ad2e652efdfacbe0a6aa
+  metadata.gz: 726191de10d2f5974ac8294f2c4f93a75146631dd2c86200d2de53f9c72cd76f
+  data.tar.gz: 2ec95c6e87c4541fb1b2b7050c2bd84d5bd3a46f948b0b711b8f042f58ddf6e5
 SHA512:
-  metadata.gz: 16a20ff6ec80f84d828f773ff8c3b1eeeda67dd0472674134aa975a822b37d0d9f86c65ef3ccb03d26c800ffa3a001386d973a77c03ab8d1ef9aeda7dfd312f4
-  data.tar.gz: e34c0b895a3bfea9174a6836c0a5af28afd1de88743430ba3b2d75494ebe42675e8e1b7a9015823e1e065ba28ed6dbbea864111cf5dd05fc3f5f7b8daf3938b7
+  metadata.gz: ce0de774a34bbc7eda7a97d26e9ac12d49297a804994425045fe7a8b85017401f54dd11fd43952e4f75e799e232979475f3881eb6f9a211e6f4e32df48168424
+  data.tar.gz: eb31f66db330ab973060794cfcfb30471c02d21529c5242f62fc11a5d97542f1ce13587af5f8d6b2057d5b709951f9c49690725937e39f3d84236df144da3b73

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    folio_client (0.7.0)
+    folio_client (0.8.0)
       activesupport (>= 4.2, < 8)
       dry-monads
       faraday
@@ -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,7 +63,7 @@ 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)
@@ -84,7 +84,7 @@ GEM
     rubocop-performance (1.15.2)
       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)

data/README.md

@@ -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,25 @@
+# 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 records belongs
+    def initialize(client, instance_id:)
+      @client = client
+      @instance_id = instance_id
+    end
+
+    # @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

@@ -24,6 +24,33 @@ class FolioClient
       result.dig("hrid")
     end
 
+    # @param hrid [String] HRID to search by to fetch the external ID
+    # @return [String,nil] 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 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 looking up info about the record
+    # @param hrid [String] an HRID for looking up info about the 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] folio instance HRID
     # @param status_id [String] uuid for an instance status code
     # @raise [ResourceNotFound] if search by hrid returns 0 results

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/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.8.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.8.0
 platform: ruby
 authors:
 - Peter Mangiafico
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-03-07 00:00:00.000000000 Z
+date: 2023-03-17 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
@@ -219,7 +221,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: Interface for interacting with the Folio ILS API.