Class: FolioClient

Inherits:
Object
  • Object
show all
Extended by:
Deprecation
Includes:
Singleton
Defined in:
lib/folio_client.rb,
lib/folio_client/users.rb,
lib/folio_client/version.rb,
lib/folio_client/inventory.rb,
lib/folio_client/job_status.rb,
lib/folio_client/data_import.rb,
lib/folio_client/authenticator.rb,
lib/folio_client/organizations.rb,
lib/folio_client/records_editor.rb,
lib/folio_client/source_storage.rb,
lib/folio_client/unexpected_response.rb

Overview

Client for interacting with the Folio API.

Defined Under Namespace

Classes: Authenticator, BadRequestError, Config, ConflictError, DataImport, Error, ForbiddenError, Inventory, JobStatus, MultipleResourcesFound, Organizations, RecordsEditor, ResourceNotFound, ServiceUnavailable, SourceStorage, UnauthorizedError, UnexpectedResponse, Users, ValidationError

Constant Summary collapse

VERSION = 
'1.2.0'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#config ⇒ FolioClient::Config?

Returns active runtime configuration.

Returns:



101
102
103
 
# File 'lib/folio_client.rb', line 101

def config
  @config
end

Class Method Details

.configure(url:, login_params:, tenant_id: nil, user_agent: nil, timeout: nil) ⇒ Class<FolioClient>

Configure the singleton FolioClient instance.

Examples:

FolioClient.configure(
  url: 'https://folio.example.edu',
  login_params: { username: 'svc-user', password: 'secret' },
  tenant_id: 'sul'
)

Parameters:

  • url (String) —

    Folio API base URL

  • login_params (Hash) —

    authentication payload (e.g., username, password)

  • tenant_id (String, nil) (defaults to: nil) —

    Folio tenant identifier

  • user_agent (String, nil) (defaults to: nil) —

    user agent string included on outbound requests

  • timeout (Integer) (defaults to: nil) —

    request timeout, in seconds

Returns:

  • (Class<FolioClient>) —

    the configured singleton class for chaining



79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/folio_client.rb', line 79

def configure(url:, login_params:, tenant_id: nil, user_agent: nil, timeout: nil)
  instance.config = Config.new(
    url: url,
    login_params: ,
    tenant_id: tenant_id,
    timeout: timeout || default_timeout,
    user_agent: user_agent || default_user_agent
  )

  self
end

Instance Method Details

#connection ⇒ Faraday::Connection

Build (or memoize) the base Faraday connection.

Returns:

  • (Faraday::Connection) —

    configured HTTP connection



187
188
189
190
191
192
193
194
195
196
 
# File 'lib/folio_client.rb', line 187

def connection
  @connection ||= Faraday.new(
    url: config.url,
    headers: config.headers,
    request: { timeout: config.timeout }
  ) do |faraday|
    faraday.use :cookie_jar, jar: cookie_jar
    faraday.adapter Faraday.default_adapter
  end
end

#cookie_jar ⇒ HTTP::CookieJar

Build (or memoize) the cookie jar used by Faraday to store authentication cookies.

Returns:

  • (HTTP::CookieJar) —

    cookie storage for session-aware requests



200
201
202
 
# File 'lib/folio_client.rb', line 200

def cookie_jar
  @cookie_jar ||= HTTP::CookieJar.new
end

#create_holdings ⇒ Object

Create a new holdings record.

Returns:

  • (Object) —

    delegated return value from Inventory#create_holdings

See Also:



249
250
251
 
# File 'lib/folio_client.rb', line 249

def create_holdings(...)
  inventory.create_holdings(...)
end

#data_import ⇒ Object

Run an inventory data import workflow.

Returns:

  • (Object) —

    delegated return value from DataImport#import

See Also:



277
278
279
 
# File 'lib/folio_client.rb', line 277

def data_import(...)
  data_import_service.import(...)
end

#default_timeout ⇒ Integer

Default HTTP timeout in seconds.

Returns:

  • (Integer) 


340
341
342
 
# File 'lib/folio_client.rb', line 340

def default_timeout
  180
end

#default_user_agent ⇒ String

Default user-agent string used for outbound requests.

Returns:

  • (String) 


347
348
349
 
# File 'lib/folio_client.rb', line 347

def default_user_agent
  "folio_client #{VERSION}"
end

#delete(path) {|Faraday::Response| ... } ⇒ Hash, ...

Note:

None of the current FolioClient services use this method, but it's provided primarily to accommodate work in folio-tasks

Send an authenticated DELETE request

Parameters:

  • path (String) —

    API path relative to configured url

Yields:

  • (Faraday::Response) —

    optional block to receive the raw Faraday::Response object

Returns:

  • (Hash, Array, nil) —

    parsed JSON body, or nil for empty body

Raises:



173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/folio_client.rb', line 173

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

#edit_marc_json ⇒ Object

Edit MARC-in-JSON records.

Returns:

  • (Object) —

    delegated return value from RecordsEditor#edit_marc_json

See Also:



291
292
293
 
# File 'lib/folio_client.rb', line 291

def edit_marc_json(...)
  records_editor.edit_marc_json(...)
end

#fetch_external_id ⇒ Object

Fetch the Folio external id for a matching record.

Returns:

  • (Object) —

    delegated return value from Inventory#fetch_external_id

See Also:



214
215
216
 
# File 'lib/folio_client.rb', line 214

def fetch_external_id(...)
  inventory.fetch_external_id(...)
end

#fetch_holdings ⇒ Object

Fetch holdings associated with a record.

Returns:

  • (Object) —

    delegated return value from Inventory#fetch_holdings

See Also:



235
236
237
 
# File 'lib/folio_client.rb', line 235

def fetch_holdings(...)
  inventory.fetch_holdings(...)
end

#fetch_hrid ⇒ Object

Fetch a Folio HRID by instance identifier or query context.

Returns:

  • (Object) —

    delegated return value from Inventory#fetch_hrid

See Also:



207
208
209
 
# File 'lib/folio_client.rb', line 207

def fetch_hrid(...)
  inventory.fetch_hrid(...)
end

#fetch_instance_info ⇒ Object

Fetch inventory instance details.

Returns:

  • (Object) —

    delegated return value from Inventory#fetch_instance_info

See Also:



221
222
223
 
# File 'lib/folio_client.rb', line 221

def fetch_instance_info(...)
  inventory.fetch_instance_info(...)
end

#fetch_location ⇒ Object

Fetch location details from inventory.

Returns:

  • (Object) —

    delegated return value from Inventory#fetch_location

See Also:



228
229
230
 
# File 'lib/folio_client.rb', line 228

def fetch_location(...)
  inventory.fetch_location(...)
end

#fetch_marc_hash ⇒ Object

Fetch MARC data as a Ruby hash.

Returns:

  • (Object) —

    delegated return value from SourceStorage#fetch_marc_hash

See Also:



256
257
258
 
# File 'lib/folio_client.rb', line 256

def fetch_marc_hash(...)
  source_storage.fetch_marc_hash(...)
end

#fetch_marc_xml ⇒ Object

Fetch MARC data as XML.

Returns:

  • (Object) —

    delegated return value from SourceStorage#fetch_marc_xml

See Also:



263
264
265
 
# File 'lib/folio_client.rb', line 263

def fetch_marc_xml(...)
  source_storage.fetch_marc_xml(...)
end

#force_token_refresh! ⇒ Object

Force a refresh of the current auth token.

Returns:

  • (Object) —

    return value from Authenticator.refresh_token!



333
334
335
 
# File 'lib/folio_client.rb', line 333

def force_token_refresh!
  Authenticator.refresh_token!
end

#get(path, params = {}) {|Faraday::Response| ... } ⇒ Hash, ...

Send an authenticated GET request.

Parameters:

  • path (String) —

    API path relative to configured url

  • params (Hash) (defaults to: {}) —

    query parameters

Yields:

  • (Faraday::Response) —

    optional block to receive the raw Faraday::Response object

Returns:

  • (Hash, Array, nil) —

    parsed JSON body, or nil for empty body

Raises:



109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/folio_client.rb', line 109

def get(path, params = {})
  response = with_token_refresh_when_unauthorized do
    connection.get(path, params)
  end

  UnexpectedResponse.call(response) unless response.success?

  yield response if block_given?

  JSON.parse(response.body) if response.body.present?
end

#has_instance_status? ⇒ Boolean

Determine whether an instance has the requested status.

Returns:

  • (Boolean) —

    delegated predicate result

See Also:



270
271
272
 
# File 'lib/folio_client.rb', line 270

def has_instance_status?(...) # rubocop:disable Naming/PredicatePrefix
  inventory.has_instance_status?(...)
end

#interface_details ⇒ Object

Fetch detailed interface information for an organization interface.

Returns:

  • (Object) —

    delegated return value from Organizations#fetch_interface_details

See Also:



312
313
314
 
# File 'lib/folio_client.rb', line 312

def interface_details(...)
  organizations_service.fetch_interface_details(...)
end

#job_profiles ⇒ Object

List available data-import job profiles.

Returns:

  • (Object) —

    delegated return value from DataImport#job_profiles

See Also:



284
285
286
 
# File 'lib/folio_client.rb', line 284

def job_profiles(...)
  data_import_service.job_profiles(...)
end

#organization_interfaces ⇒ Object

List interfaces for organizations.

Returns:

  • (Object) —

    delegated return value from Organizations#fetch_interface_list

See Also:



305
306
307
 
# File 'lib/folio_client.rb', line 305

def organization_interfaces(...)
  organizations_service.fetch_interface_list(...)
end

#organizations ⇒ Object

List organizations.

Returns:

  • (Object) —

    delegated return value from Organizations#fetch_list

See Also:



298
299
300
 
# File 'lib/folio_client.rb', line 298

def organizations(...)
  organizations_service.fetch_list(...)
end

#post(path, body = nil, content_type: 'application/json') {|Faraday::Response| ... } ⇒ Hash, ...

Send an authenticated POST request. If content_type is application/json, body is serialized with to_json. Otherwise body is sent unchanged.

Parameters:

  • path (String) —

    API path relative to configured url

  • body (Hash, String, nil) (defaults to: nil) —

    request payload

  • content_type (String) (defaults to: 'application/json') —

    MIME type of request body

Yields:

  • (Faraday::Response) —

    optional block to receive the raw Faraday::Response object

Returns:

  • (Hash, Array, nil) —

    parsed JSON body, or nil for empty body

Raises:



130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/folio_client.rb', line 130

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
    connection.post(path, req_body, { content_type: content_type })
  end

  UnexpectedResponse.call(response) unless response.success?

  yield response if block_given?

  JSON.parse(response.body) if response.body.present?
end

#put(path, body = nil, content_type: 'application/json', **exception_args) {|Faraday::Response| ... } ⇒ Hash, ...

Send an authenticated PUT request. If content_type is application/json, body is serialized with to_json. Otherwise body is sent unchanged.

Parameters:

  • path (String) —

    API path relative to configured url

  • body (Hash, String, nil) (defaults to: nil) —

    request payload

  • content_type (String) (defaults to: 'application/json') —

    MIME type of request body

  • exception_args (Hash) —

    supplemental context forwarded to UnexpectedResponse

Yields:

  • (Faraday::Response) —

    optional block to receive the raw Faraday::Response object

Returns:

  • (Hash, Array, nil) —

    parsed JSON body, or nil for empty body

Raises:



153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/folio_client.rb', line 153

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
    connection.put(path, req_body, { content_type: content_type })
  end

  UnexpectedResponse.call(response, **exception_args) unless response.success?

  yield response if block_given?

  JSON.parse(response.body) if response.body.present?
end

#update_holdings ⇒ Object

Update an existing holdings record.

Returns:

  • (Object) —

    delegated return value from Inventory#update_holdings

See Also:



242
243
244
 
# File 'lib/folio_client.rb', line 242

def update_holdings(...)
  inventory.update_holdings(...)
end

#user_details ⇒ Object

Fetch details for a user.

Returns:

  • (Object) —

    delegated return value from Users#fetch_user_details

See Also:



326
327
328
 
# File 'lib/folio_client.rb', line 326

def user_details(...)
  users_service.fetch_user_details(...)
end

#users ⇒ Object

List users.

Returns:

  • (Object) —

    delegated return value from Users#fetch_list

See Also:



319
320
321
 
# File 'lib/folio_client.rb', line 319

def users(...)
  users_service.fetch_list(...)
end