folio_client 0.21.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8c16843f867a9647afa4265ac90ce5d853e3e4ed4bd543dd209913302e8fd1e
-  data.tar.gz: e9e6f447bd7a23b75e2b38ccfbb641d26880ab9c6db815a13f47bae0a6ef6788
+  metadata.gz: c7ff536f92f06403a2d47dd9ede2dab90d0f20d8b6ad52f9c2bd047dd7eb0650
+  data.tar.gz: 3ba0ff3343cbf79bfb383254d18f8cad2bd0c74b0251e4c76bf69b26d6d75ed4
 SHA512:
-  metadata.gz: caa83ad6b9dd3d56312791ca3d5917b86895c456067b8eabacc41e27a283bb6db5dfde2fb7137eb9eb4bf599851e875bdaaf29f32f0157682c27759d1df23845
-  data.tar.gz: d5ce53af19a71d1c32d89d3cfe566e0eec8f103655c1514644e639c3ff0200316ea559d2ecc2685309e4a393bf0889b8e3953358e8aaea5748681aec213a4990
+  metadata.gz: 6e5e9f3c4b84168f41b6afaacffebcaba29bc732ea338a3834a01621dec956e568d5863789da54b4df297bda2915e9119164c0fbf3e4de1c703fc5317df0c4fb
+  data.tar.gz: c9bde04bd107cb50213b2beb8019251dd1cf2452ce842f926420576202df65ee3d54ea1a665afb441ff5d47a367fab8230de0612d88767b73bc9454a35cd9218

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    folio_client (0.21.0)
+    folio_client (1.0.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/lib/folio_client/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class FolioClient
-  VERSION = '0.21.0'
+  VERSION = '1.0.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,48 @@ 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
+  # @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)
@@ -111,11 +114,14 @@ class FolioClient
     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
+  # @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
@@ -127,11 +133,15 @@ class FolioClient
     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
+  # @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
@@ -143,7 +153,8 @@ class FolioClient
     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 +166,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.0.0
 platform: ruby
 authors:
 - Peter Mangiafico