folio_client 0.21.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8c16843f867a9647afa4265ac90ce5d853e3e4ed4bd543dd209913302e8fd1e
-  data.tar.gz: e9e6f447bd7a23b75e2b38ccfbb641d26880ab9c6db815a13f47bae0a6ef6788
+  metadata.gz: 38e080519e200ca466c29ce2aff8f3e1d9940a7d6f4ea0b5eb559e6a75b4b44c
+  data.tar.gz: a92ff5b5fa997ab8515cab2669914c4c283e323db39bb3c2ae2c3c1ee7a6aac4
 SHA512:
-  metadata.gz: caa83ad6b9dd3d56312791ca3d5917b86895c456067b8eabacc41e27a283bb6db5dfde2fb7137eb9eb4bf599851e875bdaaf29f32f0157682c27759d1df23845
-  data.tar.gz: d5ce53af19a71d1c32d89d3cfe566e0eec8f103655c1514644e639c3ff0200316ea559d2ecc2685309e4a393bf0889b8e3953358e8aaea5748681aec213a4990
+  metadata.gz: 27b02c487f0179288265f738c2ba674b7670e0f1a0859152ffff5a934b10a1bfdf6a1152b235126ce6e60a71584b333d5b19c8f792fc3aa3015bdbb1d810551e
+  data.tar.gz: 43b31dccad99d032255cd3376d281e558674baf69f6bb486cc118a621f0453dba652f969e610c931a7ddb0903ce6578c8bf455d37842aceafd91a4659fe1ea69

data/.rubocop.yml

@@ -22,6 +22,8 @@ RSpec/MultipleExpectations:
   Max: 3
 RSpec/ExampleLength:
   Max: 15
+RSpec/NestedGroups:
+  Enabled: false
 
 RSpec/BeEq: # new in 2.9.0
   Enabled: true

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    folio_client (0.21.0)
+    folio_client (1.1.0)
       activesupport (>= 4.2)
       deprecation
       dry-monads
@@ -66,7 +66,7 @@ GEM
     faraday-net_http (3.4.2)
       net-http (~> 0.5)
     hashdiff (1.2.1)
-    http-cookie (1.1.0)
+    http-cookie (1.1.4)
       domain_name (~> 0.5)
     i18n (1.14.8)
       concurrent-ruby (~> 1.0)
@@ -93,7 +93,7 @@ GEM
     nokogiri (1.19.2-x86_64-linux-gnu)
       racc (~> 1.4)
     ostruct (0.6.3)
-    parallel (1.28.0)
+    parallel (2.0.1)
     parser (3.3.11.1)
       ast (~> 2.4.1)
       racc
@@ -129,11 +129,11 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.7)
-    rubocop (1.86.0)
+    rubocop (1.86.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
-      parallel (~> 1.10)
+      parallel (>= 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
@@ -203,4 +203,4 @@ DEPENDENCIES
   webmock
 
 BUNDLED WITH
-  4.0.9
+  4.0.10

data/README.md

@@ -18,7 +18,7 @@ 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.
+The gem should be configured first, and then you can either call API endpoints directly using GET, POST, PUT, and DELETE. It may be more convenient to use the helper methods provided, as described in the section below, if your use case is already covered by what's been implemented already.
 
 ```ruby
 require 'folio_client'
@@ -34,6 +34,12 @@ client = FolioClient.configure(
 response = client.get('/organizations/organizations', {query_string_param: 'abcdef'})
 
 response = client.post('/some/post/endpoint', params_hash.to_json)
+
+# If you want direct access to the response object for your own handling, you can also
+# pass a block to the get, post, put, and delete methods:
+response = client.post('/some/post/endpoint', params_hash.to_json) do |resp|
+  # Do something with resp.status, resp.headers, resp.body, etc.
+end
 ```
 
 Note that the settings will live in the consumer of this gem and would typically be used like this:

data/lib/folio_client/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class FolioClient
-  VERSION = '0.21.0'
+  VERSION = '1.1.0'
 end

data/lib/folio_client.rb

@@ -11,45 +11,47 @@ require 'ostruct'
 require 'singleton'
 require 'zeitwerk'
 
-# Load the gem's internal dependencies: use Zeitwerk instead of needing to manually require classes
+# Autoload gem internals.
 Zeitwerk::Loader.for_gem.setup
 
-# Client for interacting with the Folio API
-# rubocop:disable Metrics/ClassLength
-class FolioClient
+# Client for interacting with the Folio API.
+class FolioClient # rubocop:disable Metrics/ClassLength
   include Singleton
 
-  # Base class for all FolioClient errors
+  # Base class for all FolioClient errors.
   class Error < StandardError; end
 
-  # Error raised by the Folio Auth API returns a 401 Unauthorized
+  # Raised when the Folio Auth API returns 401 Unauthorized.
   class UnauthorizedError < Error; end
 
-  # Error raised when the Folio API returns a 404 NotFound, or returns 0 results when one was expected
+  # Raised when the Folio API returns 404 Not Found, or when 0 results are
+  # returned where one was expected.
   class ResourceNotFound < Error; end
 
-  # Error raised when e.g. exactly one result was expected, but more than one was returned
+  # Raised when exactly one resource was expected but multiple were returned.
   class MultipleResourcesFound < Error; end
 
-  # Error raised when the Folio API returns a 403 Forbidden
+  # Raised when the Folio API returns 403 Forbidden.
   class ForbiddenError < Error; end
 
-  # Error raised when the Folio API returns a 500
+  # Raised when the Folio API returns 500-level availability errors.
   class ServiceUnavailable < Error; end
 
-  # Error raised when the Folio API returns a 422 Unprocessable Entity
+  # Raised when the Folio API returns 422 Unprocessable Entity.
   class ValidationError < Error; end
 
-  # Error raised when the Folio API returns a 409 Conflict
+  # Raised when the Folio API returns 409 Conflict.
   class ConflictError < Error; end
 
-  # Error raised when the Folio API returns a 400 Bad Request
+  # Raised when the Folio API returns 400 Bad Request.
   class BadRequestError < Error; end
 
   class << self
     extend Deprecation
 
     Config = Struct.new('Config', :url, :login_params, :timeout, :tenant_id, :user_agent) do
+      # Build default headers for Folio-bound requests.
+      # @return [Hash<Symbol,String>] default request headers
       def headers
         {
           accept: 'application/json, text/plain',
@@ -60,47 +62,49 @@ class FolioClient
       end
     end
 
-    # @param url [String] the folio API URL
-    # @param login_params [Hash] the folio client login params (username:, password:)
-    # @param tenant_id [String] the ID of the Folio tenant
-    # @param user_agent [String] the user agent string to send in API requests
-    # @param timeout [Integer] the timeout in seconds for API requests
-    # @param unsupported_kwargs [Hash] any additional keyword arguments that are not explicitly supported.
-    #   This is to allow for backward compatibility with previous versions of the client that accepted
-    #   additional configuration options, such as `okapi_headers`, without raising an error. The values
-    #   of any recognized keys in this hash will be used to set the corresponding configuration options,
-    #   and a deprecation warning will be issued for any keys present in this hash.
-    # @return [FolioClient] the configured Singleton class
-    def configure(url:, login_params:, tenant_id: nil, user_agent: default_user_agent, # rubocop:disable Metrics/ParameterLists
-                  timeout: default_timeout, **unsupported_kwargs)
-      Deprecation.warn(FolioClient, "Deprecated keywords: #{unsupported_kwargs.keys.sort.join(', ')}") if unsupported_kwargs.any?
-
+    # Configure the singleton FolioClient instance.
+    # @example
+    #   FolioClient.configure(
+    #     url: 'https://folio.example.edu',
+    #     login_params: { username: 'svc-user', password: 'secret' },
+    #     tenant_id: 'sul'
+    #   )
+    # @param url [String] Folio API base URL
+    # @param login_params [Hash] authentication payload (e.g., +username+, +password+)
+    # @param tenant_id [String, nil] Folio tenant identifier
+    # @param user_agent [String, nil] user agent string included on outbound requests
+    # @param timeout [Integer] request timeout, in seconds
+    # @return [Class<FolioClient>] the configured singleton class for chaining
+    def configure(url:, login_params:, tenant_id: nil, user_agent: nil, timeout: nil)
       instance.config = Config.new(
         url: url,
         login_params: login_params,
-        timeout: timeout,
-        tenant_id: tenant_id.presence || unsupported_kwargs.dig(:okapi_headers, :'X-Okapi-Tenant'),
-        user_agent: user_agent.presence || unsupported_kwargs.dig(:okapi_headers, :'User-Agent')
+        tenant_id: tenant_id,
+        timeout: timeout || default_timeout,
+        user_agent: user_agent || default_user_agent
       )
 
       self
     end
 
-    delegate :config, :connection, :cookie_jar, :create_holdings, :data_import, :default_timeout,
-             :default_user_agent, :edit_marc_json, :fetch_external_id, :fetch_holdings, :fetch_hrid,
-             :fetch_instance_info, :fetch_location, :fetch_marc_hash, :fetch_marc_xml,
-             :force_token_refresh!, :get, :has_instance_status?, :http_get_headers,
-             :http_post_and_put_headers, :interface_details, :job_profiles,
-             :organization_interfaces, :organizations, :update_holdings, :users, :user_details,
-             :post, :put, to: :instance
+    # The client is intended to be used as a singleton via {.configure}, but the
+    # instance methods are also available on the class itself for convenience.
+    # Instead of maintaining a giant list of delegations to the singleton
+    # instance, we can just delegate everything. This makes the client easier to
+    # extend with additional instance methods without needing to update the
+    # delegation list.
+    delegate_missing_to :instance
   end
 
+  # @return [FolioClient::Config, nil] active runtime configuration
   attr_accessor :config
 
-  # Send an authenticated get request
-  # @param path [String] the path to the Folio API request
-  # @param params [Hash] params to get to the API
-  # @return [Hash, nil] the parsed response body or nil
+  # Send an authenticated GET request.
+  # @param path [String] API path relative to configured +url+
+  # @param params [Hash] query parameters
+  # @return [Hash, Array, nil] parsed JSON body, or +nil+ for empty body
+  # @yield [Faraday::Response] optional block to receive the raw +Faraday::Response+ object
+  # @raise [FolioClient::Error] when Folio responds with an unexpected status
   def get(path, params = {})
     response = with_token_refresh_when_unauthorized do
       connection.get(path, params)
@@ -108,14 +112,20 @@ class FolioClient
 
     UnexpectedResponse.call(response) unless response.success?
 
+    yield response if block_given?
+
     JSON.parse(response.body) if response.body.present?
   end
 
-  # Send an authenticated post 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 post to the API as JSON
-  # @return [Hash, nil] the parsed response body or nil
+  # Send an authenticated POST request.
+  # If +content_type+ is +application/json+, +body+ is serialized with +to_json+.
+  # Otherwise +body+ is sent unchanged.
+  # @param path [String] API path relative to configured +url+
+  # @param body [Hash, String, nil] request payload
+  # @param content_type [String] MIME type of request body
+  # @return [Hash, Array, nil] parsed JSON body, or +nil+ for empty body
+  # @yield [Faraday::Response] optional block to receive the raw +Faraday::Response+ object
+  # @raise [FolioClient::Error] when Folio responds with an unexpected status
   def post(path, body = nil, content_type: 'application/json')
     req_body = content_type == 'application/json' ? body&.to_json : body
     response = with_token_refresh_when_unauthorized do
@@ -124,14 +134,21 @@ class FolioClient
 
     UnexpectedResponse.call(response) unless response.success?
 
+    yield response if block_given?
+
     JSON.parse(response.body) if response.body.present?
   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
-  # @return [Hash, nil] the parsed response body or nil
+  # Send an authenticated PUT request.
+  # If +content_type+ is +application/json+, +body+ is serialized with +to_json+.
+  # Otherwise +body+ is sent unchanged.
+  # @param path [String] API path relative to configured +url+
+  # @param body [Hash, String, nil] request payload
+  # @param content_type [String] MIME type of request body
+  # @param exception_args [Hash] supplemental context forwarded to +UnexpectedResponse+
+  # @return [Hash, Array, nil] parsed JSON body, or +nil+ for empty body
+  # @yield [Faraday::Response] optional block to receive the raw +Faraday::Response+ object
+  # @raise [FolioClient::Error] when Folio responds with an unexpected status
   def put(path, body = nil, content_type: 'application/json', **exception_args)
     req_body = content_type == 'application/json' ? body&.to_json : body
     response = with_token_refresh_when_unauthorized do
@@ -140,10 +157,32 @@ class FolioClient
 
     UnexpectedResponse.call(response, **exception_args) unless response.success?
 
+    yield response if block_given?
+
+    JSON.parse(response.body) if response.body.present?
+  end
+
+  # Send an authenticated DELETE request
+  # @note None of the current FolioClient services use this method, but it's provided
+  #   primarily to accommodate work in folio-tasks
+  # @param path [String] API path relative to configured +url+
+  # @return [Hash, Array, nil] parsed JSON body, or +nil+ for empty body
+  # @yield [Faraday::Response] optional block to receive the raw +Faraday::Response+ object
+  # @raise [FolioClient::Error] when Folio responds with an unexpected status
+  def delete(path)
+    response = with_token_refresh_when_unauthorized do
+      connection.delete(path)
+    end
+
+    UnexpectedResponse.call(response) unless response.success?
+
+    yield response if block_given?
+
     JSON.parse(response.body) if response.body.present?
   end
 
-  # the base connection to the Folio API
+  # Build (or memoize) the base Faraday connection.
+  # @return [Faraday::Connection] configured HTTP connection
   def connection
     @connection ||= Faraday.new(
       url: config.url,
@@ -155,174 +194,215 @@ class FolioClient
     end
   end
 
+  # Build (or memoize) the cookie jar used by Faraday to store authentication cookies.
+  # @return [HTTP::CookieJar] cookie storage for session-aware requests
   def cookie_jar
     @cookie_jar ||= HTTP::CookieJar.new
   end
 
-  # Public methods available on the FolioClient below
-
+  # Fetch a Folio HRID by instance identifier or query context.
   # @see Inventory#fetch_hrid
+  # @return [Object] delegated return value from +Inventory#fetch_hrid+
   def fetch_hrid(...)
-    Inventory
-      .new
-      .fetch_hrid(...)
+    inventory.fetch_hrid(...)
   end
 
+  # Fetch the Folio external id for a matching record.
   # @see Inventory#fetch_external_id
+  # @return [Object] delegated return value from +Inventory#fetch_external_id+
   def fetch_external_id(...)
-    Inventory
-      .new
-      .fetch_external_id(...)
+    inventory.fetch_external_id(...)
   end
 
+  # Fetch inventory instance details.
   # @see Inventory#fetch_instance_info
+  # @return [Object] delegated return value from +Inventory#fetch_instance_info+
   def fetch_instance_info(...)
-    Inventory
-      .new
-      .fetch_instance_info(...)
+    inventory.fetch_instance_info(...)
   end
 
+  # Fetch location details from inventory.
   # @see Inventory#fetch_location
+  # @return [Object] delegated return value from +Inventory#fetch_location+
   def fetch_location(...)
-    Inventory
-      .new
-      .fetch_location(...)
+    inventory.fetch_location(...)
   end
 
+  # Fetch holdings associated with a record.
   # @see Inventory#fetch_holdings
+  # @return [Object] delegated return value from +Inventory#fetch_holdings+
   def fetch_holdings(...)
-    Inventory
-      .new
-      .fetch_holdings(...)
+    inventory.fetch_holdings(...)
   end
 
+  # Update an existing holdings record.
   # @see Inventory#update_holdings
+  # @return [Object] delegated return value from +Inventory#update_holdings+
   def update_holdings(...)
-    Inventory
-      .new
-      .update_holdings(...)
+    inventory.update_holdings(...)
   end
 
+  # Create a new holdings record.
   # @see Inventory#create_holdings
+  # @return [Object] delegated return value from +Inventory#create_holdings+
   def create_holdings(...)
-    Inventory
-      .new
-      .create_holdings(...)
+    inventory.create_holdings(...)
   end
 
+  # Fetch MARC data as a Ruby hash.
   # @see SourceStorage#fetch_marc_hash
+  # @return [Object] delegated return value from +SourceStorage#fetch_marc_hash+
   def fetch_marc_hash(...)
-    SourceStorage
-      .new
-      .fetch_marc_hash(...)
+    source_storage.fetch_marc_hash(...)
   end
 
+  # Fetch MARC data as XML.
   # @see SourceStorage#fetch_marc_xml
+  # @return [Object] delegated return value from +SourceStorage#fetch_marc_xml+
   def fetch_marc_xml(...)
-    SourceStorage
-      .new
-      .fetch_marc_xml(...)
+    source_storage.fetch_marc_xml(...)
   end
 
+  # Determine whether an instance has the requested status.
   # @see Inventory#has_instance_status?
+  # @return [Boolean] delegated predicate result
   def has_instance_status?(...) # rubocop:disable Naming/PredicatePrefix
-    Inventory
-      .new
-      .has_instance_status?(...)
+    inventory.has_instance_status?(...)
   end
 
-  # @ see DataImport#import
+  # Run an inventory data import workflow.
+  # @see DataImport#import
+  # @return [Object] delegated return value from +DataImport#import+
   def data_import(...)
-    DataImport
-      .new
-      .import(...)
+    data_import_service.import(...)
   end
 
-  # @ see DataImport#job_profiles
+  # List available data-import job profiles.
+  # @see DataImport#job_profiles
+  # @return [Object] delegated return value from +DataImport#job_profiles+
   def job_profiles(...)
-    DataImport
-      .new
-      .job_profiles(...)
+    data_import_service.job_profiles(...)
   end
 
+  # Edit MARC-in-JSON records.
   # @see RecordsEditor#edit_marc_json
+  # @return [Object] delegated return value from +RecordsEditor#edit_marc_json+
   def edit_marc_json(...)
-    RecordsEditor
-      .new
-      .edit_marc_json(...)
+    records_editor.edit_marc_json(...)
   end
 
+  # List organizations.
   # @see Organizations#fetch_list
+  # @return [Object] delegated return value from +Organizations#fetch_list+
   def organizations(...)
-    Organizations
-      .new
-      .fetch_list(...)
+    organizations_service.fetch_list(...)
   end
 
+  # List interfaces for organizations.
   # @see Organizations#fetch_interface_list
+  # @return [Object] delegated return value from +Organizations#fetch_interface_list+
   def organization_interfaces(...)
-    Organizations
-      .new
-      .fetch_interface_list(...)
+    organizations_service.fetch_interface_list(...)
   end
 
+  # Fetch detailed interface information for an organization interface.
   # @see Organizations#fetch_interface_details
+  # @return [Object] delegated return value from +Organizations#fetch_interface_details+
   def interface_details(...)
-    Organizations
-      .new
-      .fetch_interface_details(...)
+    organizations_service.fetch_interface_details(...)
   end
 
+  # List users.
   # @see Users#fetch_list
+  # @return [Object] delegated return value from +Users#fetch_list+
   def users(...)
-    Users
-      .new
-      .fetch_list(...)
+    users_service.fetch_list(...)
   end
 
+  # Fetch details for a user.
   # @see Users#fetch_user_details
+  # @return [Object] delegated return value from +Users#fetch_user_details+
   def user_details(...)
-    Users
-      .new
-      .fetch_user_details(...)
+    users_service.fetch_user_details(...)
+  end
+
+  # Force a refresh of the current auth token.
+  #
+  # @return [Object] return value from +Authenticator.refresh_token!+
+  def force_token_refresh!
+    Authenticator.refresh_token!
   end
 
+  # Default HTTP timeout in seconds.
+  #
+  # @return [Integer]
   def default_timeout
     180
   end
 
+  # Default user-agent string used for outbound requests.
+  #
+  # @return [String]
   def default_user_agent
-    "folio_client #{FolioClient::VERSION}"
-  end
-
-  def force_token_refresh!
-    Authenticator.refresh_token!
+    "folio_client #{VERSION}"
   end
 
   private
 
-  # Wraps API operations to request new access token if expired.
-  # @yieldreturn response [Faraday::Response] the response to inspect
-  #
-  # @note You likely want to make sure you're wrapping a _single_ HTTP request in this
-  # method, because 1) all calls in the block will be retried from the top if there's
-  # an authN failure detected, and 2) only the response returned by the block will be
-  # inspected for authN failure.
-  # Related: consider that the client instance and its token will live across many
-  # invocations of the FolioClient methods once the client is configured by a consuming application,
-  # since this class is a Singleton.  Thus, a token may expire between any two calls (i.e. it
-  # isn't necessary for a set of operations to collectively take longer than the token lifetime for
-  # expiry to fall in the middle of that related set of HTTP calls).
+  STATUSES_REQUIRING_TOKEN_REFRESH = [401, 403].freeze
+  private_constant :STATUSES_REQUIRING_TOKEN_REFRESH
+
+  # Wrap API operations to refresh and retry when auth has expired.
+  # @yieldreturn [Faraday::Response] response from a single HTTP request
+  # @return [Faraday::Response] original or retried response
+  # @note Wrap one HTTP call per block. If auth fails, the entire block is retried.
+  #   Only the final response yielded by the block is inspected for auth failure.
+  # @note Because this class is a Singleton, its token can outlive many client calls.
+  #   Expiration can occur between any two invocations, even when those calls are
+  #   logically related from the caller's perspective.
   def with_token_refresh_when_unauthorized
     response = yield
 
-    # if unauthorized, token has likely expired. try to get a new token and then retry the same request(s).
-    if [401, 403].include?(response.status)
-      force_token_refresh!
-      response = yield
-    end
+    return response unless STATUSES_REQUIRING_TOKEN_REFRESH.include?(response.status)
+
+    force_token_refresh!
+
+    yield
+  end
+
+  # Build an inventory service object.
+  # @return [Inventory]
+  def inventory
+    Inventory.new
+  end
+
+  # Build a source-storage service object.
+  # @return [SourceStorage]
+  def source_storage
+    SourceStorage.new
+  end
+
+  # Build a data-import service object.
+  # @return [DataImport]
+  def data_import_service
+    DataImport.new
+  end
+
+  # Build a records-editor service object.
+  # @return [RecordsEditor]
+  def records_editor
+    RecordsEditor.new
+  end
+
+  # Build an organizations service object.
+  # @return [Organizations]
+  def organizations_service
+    Organizations.new
+  end
 
-    response
+  # Build a users service object.
+  # @return [Users]
+  def users_service
+    Users.new
   end
 end
-# rubocop:enable Metrics/ClassLength

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: folio_client
 version: !ruby/object:Gem::Version
-  version: 0.21.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Peter Mangiafico