folio_client 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2421b3de04e4754677703bb1012074d586cbce87bd90fe8b3341212ebeffae7
-  data.tar.gz: 54b49208c11498964a494c5c57c0c97ca3a47d71fddef9766ccf1ef4e0c404a2
+  metadata.gz: 3e45342fc554ea5de7c33e31a2bc41fd1b550cf1d60a52edd47b18f2c861846e
+  data.tar.gz: 13b0ddc4db0c2f73c31b2db26c48c9295ffa836e1e5e491b3308382d61021e72
 SHA512:
-  metadata.gz: 6fa88a92dcf548e03d69978c3600cadb33324106871ec1fcd86652e83af86aa14ed2bb3d60725cc74e6fd7291a8e4056b090d71061c04c24425d25a86310e158
-  data.tar.gz: 2094388e4e9c87abf1f09bdee68a05341358365940db25cde91e411e1f929ff1059a481089bde26c5b44398be824eb2300f1480d55ca431a07004fcbef26e0b6
+  metadata.gz: 5087d3b4a53111f8d442756e4ef4d7d5213c4232650fb46216c48aa877ea12c4bf5a2686ac90cbc575be3c1b7b271079357a00dd25a96f6cd7fc32a2738741f8
+  data.tar.gz: 1094cccbea7e0d3cfc5f0b602c78b1b1b85aa2374cd1f264dcdf569c3b7bd907153f5f9342ddc5ccc7a3a45e68e5462060f5c4452cbc1c2c5a87fd6f4bd903d8

data/.rubocop/custom.yml

@@ -1,5 +1,5 @@
 AllCops:
-  TargetRubyVersion: 3.1
+  TargetRubyVersion: 3.0
   DisplayCopNames: true
   SuggestExtensions: false
   Exclude:

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    folio_client (0.4.0)
+    folio_client (0.6.0)
       activesupport (>= 4.2, < 8)
       faraday
       zeitwerk

data/README.md

@@ -5,7 +5,7 @@
 
 # FolioClient
 
-FolioClient is a Ruby gem that acts as a client to the RESTful HTTP APIs provided by the Folio ILS API.
+FolioClient is a Ruby gem that acts as a client to the RESTful HTTP APIs provided by the Folio ILS API.  It requires ruby 3.0 or better.
 
 ## Installation
 
@@ -19,6 +19,8 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
+The gem should be configured first, and then you can either call API endpoints directly using GET or POST, or more commonly, use the helper methods provided, as described in the section below.
+
 ```ruby
 require 'folio_client'
 
@@ -29,7 +31,9 @@ client = FolioClient.configure(
     okapi_headers: { 'X-Okapi-Tenant': 'sul', 'User-Agent': 'FolioApiClient' }
 )
 
-response = client.get('/organizations/organizations')
+response = client.get('/organizations/organizations', {query_string_param: 'abcdef'})
+
+response = client.post('/some/post/endpoint', params_hash.to_json)
 ```
 
 Note that the settings will live in the consumer of this gem and would typically be used like this:
@@ -44,6 +48,30 @@ client = FolioClient.configure(
 )
 ```
 
+The client is smart enough to automatically request a new token if it detects the one it is using has expired.  If for some reason, you want to immediately request a new token, you can do this:
+
+```ruby
+client.config.token = FolioClient::Authenticator.token(client.config.login_params, client.connection)
+```
+
+## API Coverage
+
+FolioClient provides a number of methods to simplify connecting to the RESTful HTTP API of the Folio API. In this section we list all of the available methods, reflecting how much of the API the client covers.  Note that this assumes the client has already been configured, as described above.  See dor-services-app for an example of configuration and usage.
+
+```ruby
+# Lookup an instance hrid given a barcode
+# returns a string if found, nil if nothing found
+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
+client.fetch_marc_hash(instance_hrid: "a7927874")
+ => {"fields"=>
+  [{"003"=>"FOLIO"}....]
+  }
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/folio_client/inventory.rb

@@ -26,11 +26,11 @@ class FolioClient
 
     # @param hrid [String] folio instance HRID
     # @param status_id [String] uuid for an instance status code
-    # @raise [FolioClient::UnexpectedResponse::ResourceNotFound] if search by hrid returns 0 results
+    # @raise [ResourceNotFound] if search by 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}"})
-      raise FolioClient::UnexpectedResponse::ResourceNotFound, "No matching instance found for #{hrid}" if instance["totalRecords"] == 0
+      raise ResourceNotFound, "No matching instance found for #{hrid}" if instance["totalRecords"] == 0
 
       instance_status_id = instance.dig("instances", 0, "statusId")
 

data/lib/folio_client/source_storage.rb

@@ -17,8 +17,8 @@ class FolioClient
       response_hash = client.get("/source-storage/source-records", {instanceHrid: instance_hrid})
 
       record_count = response_hash["totalRecords"]
-      raise FolioClient::UnexpectedResponse::ResourceNotFound, "No records found for #{instance_hrid}" if record_count.zero?
-      raise FolioClient::UnexpectedResponse::MultipleResourcesFound, "Expected 1 record for #{instance_hrid}, but found #{record_count}" if record_count > 1
+      raise ResourceNotFound, "No records found for #{instance_hrid}" if record_count.zero?
+      raise MultipleResourcesFound, "Expected 1 record for #{instance_hrid}, but found #{record_count}" if record_count > 1
 
       response_hash["sourceRecords"].first["parsedRecord"]["content"]
     end

data/lib/folio_client/token_wrapper.rb

@@ -5,7 +5,7 @@ class FolioClient
   class TokenWrapper
     def self.refresh(config, connection)
       yield
-    rescue UnexpectedResponse::UnauthorizedError
+    rescue UnauthorizedError
       config.token = Authenticator.token(config.login_params, connection)
       yield
     end

data/lib/folio_client/unexpected_response.rb

@@ -3,24 +3,6 @@
 class FolioClient
   # Handles unexpected responses when communicating with Folio
   class UnexpectedResponse
-    # Base class for all FolioClient errors
-    class FolioClientError < StandardError; end
-
-    # Error raised by the Folio Auth API returns a 422 Unauthorized
-    class UnauthorizedError < FolioClientError; end
-
-    # Error raised when the Folio API returns a 404 NotFound, or returns 0 results when one was expected
-    class ResourceNotFound < FolioClientError; end
-
-    # Error raised when e.g. exactly one result was expected, but more than one was returned
-    class MultipleResourcesFound < FolioClientError; end
-
-    # Error raised when the Folio API returns a 403 Forbidden
-    class ForbiddenError < FolioClientError; end
-
-    # Error raised when the Folio API returns a 500
-    class ServiceUnavailable < FolioClientError; end
-
     # @param [Faraday::Response] response
     def self.call(response)
       case response.status

data/lib/folio_client/version.rb

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

data/lib/folio_client.rb

@@ -13,6 +13,24 @@ Zeitwerk::Loader.for_gem.setup
 class FolioClient
   include Singleton
 
+  # Base class for all FolioClient errors
+  class Error < StandardError; end
+
+  # Error raised by the Folio Auth API returns a 422 Unauthorized
+  class UnauthorizedError < Error; end
+
+  # Error raised when the Folio API returns a 404 NotFound, or returns 0 results when one was expected
+  class ResourceNotFound < Error; end
+
+  # Error raised when e.g. exactly one result was expected, but more than one was returned
+  class MultipleResourcesFound < Error; end
+
+  # Error raised when the Folio API returns a 403 Forbidden
+  class ForbiddenError < Error; end
+
+  # Error raised when the Folio API returns a 500
+  class ServiceUnavailable < Error; end
+
   DEFAULT_HEADERS = {
     accept: "application/json, text/plain",
     content_type: "application/json"
@@ -23,7 +41,7 @@ class FolioClient
     # @param login_params [Hash] the folio client login params (username:, password:)
     # @param okapi_headers [Hash] the okapi specific headers to add (X-Okapi-Tenant:, User-Agent:)
     def configure(url:, login_params:, okapi_headers:)
-      instance.config = OpenStruct.new(url:, login_params:, okapi_headers:, token: nil)
+      instance.config = OpenStruct.new(url: url, login_params: login_params, okapi_headers: okapi_headers, token: nil)
 
       instance.config.token = Authenticator.token(login_params, connection)
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: folio_client
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Peter Mangiafico
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-02-27 00:00:00.000000000 Z
+date: 2023-02-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -189,7 +189,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+rubygems_version: 3.4.5
 signing_key:
 specification_version: 4
 summary: Interface for interacting with the Folio ILS API.