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.1.0'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#config ⇒ FolioClient::Config?

Returns active runtime configuration.

Returns:



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

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



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

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



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

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



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

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:



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

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:



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

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

#default_timeout ⇒ Integer

Default HTTP timeout in seconds.

Returns:

  • (Integer) 


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

def default_timeout
  180
end

#default_user_agent ⇒ String

Default user-agent string used for outbound requests.

Returns:

  • (String) 


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

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:



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

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:



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

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:



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

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:



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

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:



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

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:



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

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:



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

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:



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

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:



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

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!



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

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:



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

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:



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

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:



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

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:



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

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:



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

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

#organizations ⇒ Object

List organizations.

Returns:

  • (Object) —

    delegated return value from Organizations#fetch_list

See Also:



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

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:



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

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:



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

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:



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

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:



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

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

#users ⇒ Object

List users.

Returns:

  • (Object) —

    delegated return value from Users#fetch_list

See Also:



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

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