folio_client 0.18.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42f8788a27374e443881099b77bfaa24961f0d38cd7577c36bc85005070a6981
-  data.tar.gz: 794a03e9de4d8bb2987efe8889653fdf2b3f043c518f200783310479a6fc02bf
+  metadata.gz: ef1f093f7eb2cfcd38d85fc547d702a9768235b9a4e24f061653225e207978a9
+  data.tar.gz: ffe4c65db99fda6d3cece47f00bb84d490794382342ec2b4be6d4d2ff97a4f1e
 SHA512:
-  metadata.gz: fab85671e97be76c1c39d0a4e30b5cf0fe48aaa6794b4d59e4f37b4197bd287e4aa7cf1433a2235205625980b86ce6c45d21790baa0734f1ae4a296d0cd62a45
-  data.tar.gz: bf7584bc2416dec88e566b8bfca6f0b69f8d1b6347621f24d8d41ac30ed06e5e503570b5678609847f420f40a4e2a400cd1aa3421beafb73358f2781a8e6e809
+  metadata.gz: 514d18193471517981408f5e1193cc13efa0640e3ad3176030aee72629a3b27b0f6ef9b5f9b36ca5197a9280180276d609a7ca0abddd56d5e9885bc6215f81dd
+  data.tar.gz: 885859bc1542aa0ceb2d7cf6c939851e2f9774db332f39c2d66b90773d8a6fea6278cf4267a969ece4e492e277deb51ca94337bf02d4395fb00c5a8da3692aa9

data/.rubocop.yml

@@ -1,12 +1,12 @@
-require:
+plugins:
   - rubocop-capybara
   - rubocop-factory_bot
+  - rubocop-rspec_rails
   - rubocop-performance
   - rubocop-rspec
-  - rubocop-rspec_rails
 
 AllCops:
-  TargetRubyVersion: 3.0
+  TargetRubyVersion: 3.4
   DisplayCopNames: true
   SuggestExtensions: false
   Exclude:
@@ -403,3 +403,91 @@ FactoryBot/ExcessiveCreateList: # new in 2.25
   Enabled: true
 Performance/StringBytesize: # new in 1.23
   Enabled: true
+
+Lint/ArrayLiteralInRegexp: # new in 1.71
+  Enabled: true
+Lint/CopDirectiveSyntax: # new in 1.72
+  Enabled: true
+Lint/RedundantTypeConversion: # new in 1.72
+  Enabled: true
+Lint/SuppressedExceptionInNumberConversion: # new in 1.72
+  Enabled: true
+Lint/UselessConstantScoping: # new in 1.72
+  Enabled: true
+Style/HashSlice: # new in 1.71
+  Enabled: true
+Style/RedundantFormat: # new in 1.72
+  Enabled: true
+Performance/ZipWithoutBlock: # new in 1.24
+  Enabled: true
+
+Lint/UselessDefaultValueArgument: # new in 1.76
+  Enabled: true
+Lint/UselessOr: # new in 1.76
+  Enabled: true
+Naming/PredicateMethod: # new in 1.76
+  Enabled: true
+Style/ComparableBetween: # new in 1.74
+  Enabled: true
+Style/EmptyStringInsideInterpolation: # new in 1.76
+  Enabled: true
+Style/HashFetchChain: # new in 1.75
+  Enabled: true
+Style/ItBlockParameter: # new in 1.75
+  Enabled: true
+Style/RedundantArrayFlatten: # new in 1.76
+  Enabled: true
+RSpec/IncludeExamples: # new in 3.6
+  Enabled: true
+Capybara/FindAllFirst: # new in 2.22
+  Enabled: true
+Capybara/NegationMatcherAfterVisit: # new in 2.22
+  Enabled: true
+Gemspec/AttributeAssignment: # new in 1.77
+  Enabled: true
+Layout/EmptyLinesAfterModuleInclusion: # new in 1.79
+  Enabled: true
+Style/ArrayIntersectWithSingleElement: # new in 1.81
+  Enabled: true
+Style/CollectionQuerying: # new in 1.77
+  Enabled: true
+Style/EmptyClassDefinition: # new in 1.84
+  Enabled: true
+Style/ModuleMemberExistenceCheck: # new in 1.82
+  Enabled: true
+Style/NegativeArrayIndex: # new in 1.84
+  Enabled: true
+Style/ReverseFind: # new in 1.84
+  Enabled: true
+RSpecRails/HttpStatusNameConsistency: # new in 2.32
+  Enabled: true
+RSpec/LeakyLocalVariable: # new in 3.8
+  Enabled: true
+RSpec/Output: # new in 3.9
+  Enabled: true
+Lint/DataDefineOverride: # new in 1.85
+  Enabled: true
+Lint/UnreachablePatternBranch: # new in 1.85
+  Enabled: true
+Style/FileOpen: # new in 1.85
+  Enabled: true
+Style/MapJoin: # new in 1.85
+  Enabled: true
+Style/OneClassPerFile: # new in 1.85
+  Enabled: true
+Style/PartitionInsteadOfDoubleSelect: # new in 1.85
+  Enabled: true
+Style/PredicateWithKind: # new in 1.85
+  Enabled: true
+Style/ReduceToHash: # new in 1.85
+  Enabled: true
+Style/RedundantMinMaxBy: # new in 1.85
+  Enabled: true
+Style/RedundantStructKeywordInit: # new in 1.85
+  Enabled: true
+Style/SelectByKind: # new in 1.85
+  Enabled: true
+Style/SelectByRange: # new in 1.85
+  Enabled: true
+Style/TallyMethod: # new in 1.85
+  Enabled: true

data/Gemfile

@@ -5,4 +5,4 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in folio_client.gemspec
 gemspec
 
-gem 'byebug'
+gem 'debug'

data/Gemfile.lock

@@ -1,160 +1,198 @@
 PATH
   remote: .
   specs:
-    folio_client (0.18.0)
+    folio_client (0.20.0)
       activesupport (>= 4.2)
       dry-monads
       faraday
       faraday-cookie_jar
       marc
+      ostruct
       zeitwerk
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (8.0.1)
+    activesupport (8.1.2)
       base64
-      benchmark (>= 0.3)
       bigdecimal
       concurrent-ruby (~> 1.0, >= 1.3.1)
       connection_pool (>= 2.2.5)
       drb
       i18n (>= 1.6, < 2)
+      json
       logger (>= 1.4.2)
       minitest (>= 5.1)
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
       uri (>= 0.13.1)
-    addressable (2.8.7)
-      public_suffix (>= 2.0.2, < 7.0)
-    ast (2.4.2)
-    base64 (0.2.0)
-    benchmark (0.4.0)
-    bigdecimal (3.1.9)
-    byebug (11.1.3)
-    concurrent-ruby (1.3.5)
-    connection_pool (2.5.0)
-    crack (1.0.0)
+    addressable (2.8.9)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (4.0.1)
+    concurrent-ruby (1.3.6)
+    connection_pool (3.0.2)
+    crack (1.0.1)
       bigdecimal
       rexml
-    diff-lcs (1.5.1)
+    date (3.5.1)
+    debug (1.11.1)
+      irb (~> 1.10)
+      reline (>= 0.3.8)
+    diff-lcs (1.6.2)
     docile (1.4.1)
     domain_name (0.6.20240107)
-    drb (2.2.1)
-    dry-core (1.1.0)
+    drb (2.2.3)
+    dry-core (1.2.0)
       concurrent-ruby (~> 1.0)
       logger
       zeitwerk (~> 2.6)
-    dry-monads (1.7.1)
+    dry-monads (1.9.0)
       concurrent-ruby (~> 1.0)
       dry-core (~> 1.1)
       zeitwerk (~> 2.6)
-    faraday (2.12.2)
+    erb (6.0.2)
+    faraday (2.14.1)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger
-    faraday-cookie_jar (0.0.7)
+    faraday-cookie_jar (0.0.8)
       faraday (>= 0.8.0)
-      http-cookie (~> 1.0.0)
-    faraday-net_http (3.4.0)
-      net-http (>= 0.5.0)
-    hashdiff (1.1.2)
-    http-cookie (1.0.8)
+      http-cookie (>= 1.0.0)
+    faraday-net_http (3.4.2)
+      net-http (~> 0.5)
+    hashdiff (1.2.1)
+    http-cookie (1.1.0)
       domain_name (~> 0.5)
-    i18n (1.14.7)
+    i18n (1.14.8)
       concurrent-ruby (~> 1.0)
-    json (2.9.1)
-    language_server-protocol (3.17.0.4)
-    logger (1.6.6)
-    marc (1.3.0)
+    io-console (0.8.2)
+    irb (1.17.0)
+      pp (>= 0.6.0)
+      prism (>= 1.3.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.19.1)
+    json-schema (6.2.0)
+      addressable (~> 2.8)
+      bigdecimal (>= 3.1, < 5)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    marc (1.4.0)
       nokogiri (~> 1.0)
       rexml
-    minitest (5.25.4)
-    net-http (0.6.0)
-      uri
-    nokogiri (1.18.2-arm64-darwin)
-      racc (~> 1.4)
-    nokogiri (1.18.2-x86_64-darwin)
+    mcp (0.8.0)
+      json-schema (>= 4.1)
+    minitest (6.0.2)
+      drb (~> 2.0)
+      prism (~> 1.5)
+    net-http (0.9.1)
+      uri (>= 0.11.1)
+    nokogiri (1.19.1-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.18.2-x86_64-linux-gnu)
+    nokogiri (1.19.1-x86_64-linux-gnu)
       racc (~> 1.4)
-    parallel (1.26.3)
-    parser (3.3.7.1)
+    ostruct (0.6.3)
+    parallel (1.27.0)
+    parser (3.3.10.2)
       ast (~> 2.4.1)
       racc
-    public_suffix (6.0.1)
+    pp (0.6.3)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.9.0)
+    psych (5.3.1)
+      date
+      stringio
+    public_suffix (7.0.5)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.2.1)
-    regexp_parser (2.10.0)
-    rexml (3.4.0)
-    rspec (3.13.0)
+    rake (13.3.1)
+    rdoc (7.2.0)
+      erb
+      psych (>= 4.0.0)
+      tsort
+    regexp_parser (2.11.3)
+    reline (0.6.3)
+      io-console (~> 0.5)
+    rexml (3.4.4)
+    rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.3)
+    rspec-core (3.13.6)
       rspec-support (~> 3.13.0)
-    rspec-expectations (3.13.3)
+    rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.2)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.2)
-    rubocop (1.71.2)
+    rspec-support (3.13.7)
+    rubocop (1.85.1)
       json (~> 2.3)
-      language_server-protocol (>= 3.17.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      mcp (~> 0.6)
       parallel (~> 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.38.0, < 2.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.38.0)
-      parser (>= 3.3.1.0)
-    rubocop-capybara (2.21.0)
-      rubocop (~> 1.41)
-    rubocop-factory_bot (2.26.1)
-      rubocop (~> 1.61)
-    rubocop-performance (1.23.1)
-      rubocop (>= 1.48.1, < 2.0)
-      rubocop-ast (>= 1.31.1, < 2.0)
-    rubocop-rspec (3.4.0)
-      rubocop (~> 1.61)
-    rubocop-rspec_rails (2.30.0)
-      rubocop (~> 1.61)
-      rubocop-rspec (~> 3, >= 3.0.1)
+    rubocop-ast (1.49.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-capybara (2.22.1)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.72, >= 1.72.1)
+    rubocop-factory_bot (2.28.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.72, >= 1.72.1)
+    rubocop-performance (1.26.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+    rubocop-rspec (3.9.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.81)
+    rubocop-rspec_rails (2.32.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.72, >= 1.72.1)
+      rubocop-rspec (~> 3.5)
     ruby-progressbar (1.13.0)
     securerandom (0.4.1)
     simplecov (0.22.0)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
-    simplecov-html (0.13.1)
+    simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
+    stringio (3.2.0)
+    tsort (0.2.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    unicode-display_width (3.1.4)
-      unicode-emoji (~> 4.0, >= 4.0.4)
-    unicode-emoji (4.0.4)
-    uri (1.0.2)
-    webmock (3.25.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    uri (1.1.1)
+    webmock (3.26.1)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
-    zeitwerk (2.7.1)
+    zeitwerk (2.7.5)
 
 PLATFORMS
   arm64-darwin-23
-  x86_64-darwin-19
-  x86_64-darwin-20
-  x86_64-darwin-21
-  x86_64-darwin-22
+  arm64-darwin-24
+  arm64-darwin-25
   x86_64-linux
 
 DEPENDENCIES
-  byebug
+  debug
   folio_client!
   rake (~> 13.0)
   rspec (~> 3.0)
@@ -168,4 +206,4 @@ DEPENDENCIES
   webmock
 
 BUNDLED WITH
-   2.4.13
+  4.0.7

data/README.md

@@ -25,10 +25,10 @@ require 'folio_client'
 
 # this will configure the client and request an access token
 client = FolioClient.configure(
-    url: 'https://okapi-dev.stanford.edu',
-    login_params: { username: 'xxx', password: 'yyy' },
-    okapi_headers: { 'X-Okapi-Tenant': 'sul', 'User-Agent': 'FolioApiClient' }
-)
+           url: 'https://okapi-dev.stanford.edu',
+           login_params: { username: 'xxx', password: 'yyy' },
+           okapi_headers: { 'X-Okapi-Tenant': 'sul', 'User-Agent': 'FolioApiClient' }
+         )
 
 response = client.get('/organizations/organizations', {query_string_param: 'abcdef'})
 
@@ -44,7 +44,6 @@ client = FolioClient.configure(
     url: Settings.okapi.url,
     login_params: Settings.okapi.login_params,
     okapi_headers: Settings.okapi.headers,
-    legacy_auth: true # consumers should leave set to true (default) until /login-with-expiry endpoint enabled in Poppy
 )
 ```
 
@@ -164,6 +163,86 @@ client.user_details(id: 'bbbadd51-c2f1-4107-a54d-52b39087725c')
 => {"username"=>"testing",
     "id"=>"bbbadd51-c2f1-4107-a54d-52b39087725c",
     "externalSystemId"=>"00324439", ... # same response as above, but for single user
+
+# Get location details by UUID (useful for checking campusId when creating holdings)
+# see https://s3.amazonaws.com/foliodocs/api/mod-inventory-storage/p/location.html#locations__id__get
+client.fetch_location(location_id: 'd9cd0bed-1b49-4b5e-a7bd-064b8d177231')
+=> {"id"=>"d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
+    "name"=>"Miller General Stacks",
+    "code"=>"UA/CB/LC/GS",
+    "isActive"=>true,
+    "description"=>"The very general stacks of Miller",
+    "discoveryDisplayName"=>"Miller General",
+    "institutionId"=>"4b2a3d97-01c3-4ef3-98a5-ae4e853429b4",
+    "campusId"=>"b595d838-b1d5-409e-86ac-af3b41bde0be",
+    "libraryId"=>"e2889f93-92f2-4937-b944-5452a575367e",
+    "details"=>{"a"=>"b", "foo"=>"bar"},
+    "primaryServicePoint"=>"79faacf1-4ba4-42c7-8b2a-566b259e4641",
+    "servicePointIds"=>["79faacf1-4ba4-42c7-8b2a-566b259e4641"]}
+
+# Get holdings records for an instance by HRID (useful for checking permanentLocationId and discoverySuppress)
+# see https://github.com/folio-org/mod-search#search-api
+client.fetch_holdings(hrid: 'in00000000067')
+=> [{"id"=>"7f89e96c-478c-4ca2-bb85-0a1c5b0c6f3e",
+     "instanceId"=>"5108040a-65bc-40ed-bd50-265958301ce4",
+     "permanentLocationId"=>"d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
+     "discoverySuppress"=>false,
+     "hrid"=>"ho00000000010",
+     "holdingsTypeId"=>"03c9c400-b9e3-4a07-ac0e-05ab470233ed",
+     "callNumber"=>"ABC 123"},
+    {"id"=>"8a89e96c-478c-4ca2-bb85-0a1c5b0c6f3f",
+     "instanceId"=>"5108040a-65bc-40ed-bd50-265958301ce4",
+     "permanentLocationId"=>"b595d838-b1d5-409e-86ac-af3b41bde0be",
+     "discoverySuppress"=>true,
+     "hrid"=>"ho00000000011",
+     "holdingsTypeId"=>"03c9c400-b9e3-4a07-ac0e-05ab470233ed",
+     "callNumber"=>"DEF 456"}]
+
+# Update a holdings record for an instance HRID
+holdings_record = 
+  { 'id' => '7f89e96c-478c-4ca2-bb85-0a1c5b0c6f3e',
+    '_version' => 1,
+    'sourceId' => 'f32d531e-df79-46b3-8932-cdd35f7a2264',
+    'hrid' => 'ah1994253_1',
+    'holdingsTypeId' => '5684e4a3-9279-4463-b6ee-20ae21bbec07',
+    'instanceId' => '54ec1f1a-d039-5a39-95f2-71df00061664',
+    'permanentLocationId' => '4573e824-9273-4f13-972f-cff7bf504217',
+    'effectiveLocationId' => '4573e824-9273-4f13-972f-cff7bf504217',
+    'discoverySuppress' => false }
+client.update_holdings(holdings_id: '7f89e96c-478c-4ca2-bb85-0a1c5b0c6f3e', holdings_record:)
+
+#Create a holdings record
+holdings_record =
+  { "instance_id" => "f1b301ce-f5d2-53b5-85eb-e4452bb5a591",
+    "permanent_location_id" => '1b14e21c-8d47-45c7-bc49-456a0086422b',
+    "source_id" => "f32d531e-df79-46b3-8932-cdd35f7a2264",
+    "holdings_type_id" => "996f93e2-5b5e-4cf2-9168-33ced1f95eed",
+    "discovery_suppress" => false }
+client.create_holdings(holdings_record:)
+=> {
+    "id" => "c65bb9dc-ebca-41fc-9c50-0d39085c1987",
+    "_version" => 1,
+    "sourceId" => "f32d531e-df79-46b3-8932-cdd35f7a2264",
+    "hrid" => "ho00000927052",
+    "holdingsTypeId" => "996f93e2-5b5e-4cf2-9168-33ced1f95eed",
+    "formerIds" => [],
+    "instanceId" => "54ec1f1a-d039-5a39-95f2-71df00061664",
+    "permanentLocationId" => "1b14e21c-8d47-45c7-bc49-456a0086422b",
+    "effectiveLocationId" => "1b14e21c-8d47-45c7-bc49-456a0086422b",
+    "electronicAccess" => [],
+    "administrativeNotes" => [],
+    "notes" => [],
+    "holdingsStatements" => [],
+    "holdingsStatementsForIndexes" => [],
+    "holdingsStatementsForSupplements" => [],
+    "discoverySuppress" => false,
+    "statisticalCodeIds" => [],
+    "metadata" =>
+    {"createdDate" => "2026-03-12T18:58:03.576+00:00",
+    "createdByUserId" => "709fdac6-d3f3-5784-8839-fe36ad6ed0b3",
+    "updatedDate" => "2026-03-12T18:58:03.576+00:00",
+    "updatedByUserId" => "709fdac6-d3f3-5784-8839-fe36ad6ed0b3"}
+    }
 ```
 
 ## Development

data/folio_client.gemspec

@@ -13,7 +13,7 @@ Gem::Specification.new do |spec|
   spec.summary = 'Interface for interacting with the Folio ILS API.'
   spec.description = 'This provides API interaction with the Folio ILS API'
   spec.homepage = 'https://github.com/sul-dlss/folio_client'
-  spec.required_ruby_version = '>= 3.0.0'
+  spec.required_ruby_version = '>= 3.4'
 
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = 'https://github.com/sul-dlss/folio_client'
@@ -36,6 +36,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'faraday'
   spec.add_dependency 'faraday-cookie_jar'
   spec.add_dependency 'marc'
+  spec.add_dependency 'ostruct'
   spec.add_dependency 'zeitwerk'
 
   spec.add_development_dependency 'rake', '~> 13.0'

data/lib/folio_client/authenticator.rb

@@ -8,29 +8,26 @@ class FolioClient
     end
 
     # Request an access_token
-    def token # rubocop:disable Metrics/AbcSize
+    def token
       response = FolioClient.connection.post(login_endpoint, FolioClient.config.login_params.to_json)
 
       UnexpectedResponse.call(response) unless response.success?
 
-      # remove legacy_auth once new tokens enabled on Poppy
-      if FolioClient.config.legacy_auth
-        JSON.parse(response.body)['okapiToken']
-      else
-        access_cookie = FolioClient.cookie_jar.cookies.find { |cookie| cookie.name == 'folioAccessToken' }
+      access_cookie = FolioClient.cookie_jar.cookies.find { |cookie| cookie.name == 'folioAccessToken' }
 
-        raise StandardError, "Problem with folioAccessToken cookie: #{response.headers}, #{response.body}" unless access_cookie
+      # NOTE: The client typically delegates raising exceptions (based on HTTP
+      #       responses) to the UnexpectedResponse class, but this call in
+      #       Authenticator is a one-off, unlike any other in the app, so we
+      #       allow it to customize its exception handling.
+      raise UnauthorizedError, "Problem with folioAccessToken cookie: #{response.headers}, #{response.body}" unless access_cookie
 
-        access_cookie.value
-      end
+      access_cookie.value
     end
 
     private
 
     def login_endpoint
-      return '/authn/login-with-expiry' unless FolioClient.config.legacy_auth
-
-      '/authn/login'
+      '/authn/login-with-expiry'
     end
   end
 end

data/lib/folio_client/inventory.rb

@@ -25,7 +25,7 @@ class FolioClient
     def fetch_external_id(hrid:)
       instance_response = client.get('/search/instances', { query: "hrid==#{hrid}" })
       record_count = instance_response['totalRecords']
-      raise ResourceNotFound, "No matching instance found for #{hrid}" if (instance_response['totalRecords']).zero?
+      raise ResourceNotFound, "No matching instance found for #{hrid}" if instance_response['totalRecords'].zero?
       raise MultipleResourcesFound, "Expected 1 record for #{hrid}, but found #{record_count}" if record_count > 1
 
       instance_response.dig('instances', 0, 'id')
@@ -50,10 +50,10 @@ class FolioClient
     # @param status_id [String] uuid for an instance status code
     # @return true if instance status matches the uuid param, false otherwise
     # @raise [ResourceNotFound] if search by instance HRID returns 0 results
-    def has_instance_status?(hrid:, status_id:) # rubocop:disable Naming/PredicateName
+    def has_instance_status?(hrid:, status_id:) # rubocop:disable Naming/PredicatePrefix
       # get the instance record and its statusId
       instance = client.get('/inventory/instances', { query: "hrid==#{hrid}" })
-      raise ResourceNotFound, "No matching instance found for #{hrid}" if (instance['totalRecords']).zero?
+      raise ResourceNotFound, "No matching instance found for #{hrid}" if instance['totalRecords'].zero?
 
       instance_status_id = instance.dig('instances', 0, 'statusId')
 
@@ -64,6 +64,54 @@ class FolioClient
       false
     end
 
+    # Get location details by UUID
+    # @param location_id [String] UUID of the location
+    # @return [Hash] location data including campusId and other location information
+    # @raise [ResourceNotFound] if location with the given UUID is not found
+    def fetch_location(location_id:)
+      client.get("/locations/#{location_id}")
+    end
+
+    # Get holdings records for an instance by HRID
+    # @see https://s3.amazonaws.com/foliodocs/api/mod-inventory-storage/p/inventory-view.html
+    # @param hrid [String] instance HRID
+    # @return [Array<Hash>] array of holdings records with permanentLocationId, _version, discoverySuppress, and other fields
+    def fetch_holdings(hrid:)
+      instance_uuid = fetch_external_id(hrid: hrid)
+      instance_response = client.get('/inventory-view/instances', { query: "id==#{instance_uuid}" })
+
+      instance_response.dig('instances', 0, 'holdingsRecords') || []
+    end
+
+    # Put an updated holdings record
+    # @see https://s3.amazonaws.com/foliodocs/api/mod-inventory/p/inventory.html#inventory_holdings__holdingsid__put
+    # @param holdings_id [String] UUID of the holdings record to update
+    # @param holdings_record [Hash] holdings record
+    # @raise [ResourceNotFound] if holdings record with the given UUID is not found
+    # @raise [BadRequestError] may occur if the update includes invalid fields or values
+    # @raise [UnexpectedResponse] if the API returns some other error response
+    def update_holdings(holdings_id:, holdings_record:)
+      client.put("/inventory/holdings/#{holdings_id}", holdings_record, exception_subject: "holdings record with ID #{holdings_id}")
+    end
+
+    # Post a new holdings record
+    # @param holdings_record [Hash] holdings record
+    # @return [Hash] the created holdings record, including its id and other fields
+    # @see https://s3.amazonaws.com/foliodocs/api/mod-inventory-storage/p/holdings-storage.html#holdings_storage_holdings_post
+    def create_holdings(holdings_record:)
+      required = %w[instance_id permanent_location_id source_id holdings_type_id]
+      missing = required.select { |field| !holdings_record.key?(field) || holdings_record[field].blank? }
+      raise ArgumentError, "Missing required fields: #{missing.join(', ')}" if missing.any?
+
+      client.post('/holdings-storage/holdings', {
+                    instanceId: holdings_record['instance_id'],
+                    permanentLocationId: holdings_record['permanent_location_id'],
+                    sourceId: holdings_record['source_id'],
+                    holdingsTypeId: holdings_record['holdings_type_id'],
+                    discoverySuppress: false
+                  })
+    end
+
     private
 
     def client

data/lib/folio_client/job_status.rb

@@ -98,6 +98,10 @@ class FolioClient
     def check_not_found(result, index, max_checks)
       return unless result.failure? && result.failure == :not_found && index > max_checks
 
+      # NOTE: The client typically delegates raising exceptions (based on HTTP
+      #       responses) to the UnexpectedResponse class, but the interaction in
+      #       JobStatus is more complex due to waits/loops, so we allow this
+      #       class to do some of its own exception handling.
       raise ResourceNotFound,
             "Job #{job_execution_id} not found after #{index} retries. The data import job may still have completed."
     end

data/lib/folio_client/source_storage.rb

@@ -21,7 +21,7 @@ class FolioClient
               "Expected 1 record for #{instance_hrid}, but found #{record_count}"
       end
 
-      response_hash['sourceRecords'].first['parsedRecord']['content']
+      response_hash.dig('sourceRecords', 0, 'parsedRecord', 'content')
     end
 
     # get marc bib data as MARCXML from folio given an instance HRID
@@ -30,9 +30,7 @@ class FolioClient
     # @return [String] MARCXML string
     # @raise [ResourceNotFound]
     # @raise [MultipleResourcesFound]
-    # rubocop:disable Metrics/MethodLength
-    # rubocop:disable Metrics/AbcSize
-    def fetch_marc_xml(instance_hrid: nil, barcode: nil)
+    def fetch_marc_xml(instance_hrid: nil, barcode: nil) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       if barcode.nil? && instance_hrid.nil?
         raise ArgumentError,
               'Either a barcode or a Folio instance HRID must be provided'
@@ -62,8 +60,6 @@ class FolioClient
       updated_marc.fields << MARC::ControlField.new('003', 'FOLIO')
       updated_marc.to_xml.to_s
     end
-    # rubocop:enable Metrics/MethodLength
-    # rubocop:enable Metrics/AbcSize
 
     private
 

data/lib/folio_client/unexpected_response.rb

@@ -4,16 +4,18 @@ class FolioClient
   # Handles unexpected responses when communicating with Folio
   class UnexpectedResponse
     # @param [Faraday::Response] response
-    # rubocop:disable Metrics/MethodLength
-    # rubocop:disable Metrics/AbcSize
-    def self.call(response)
+    def self.call(response, **kwargs) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+      subject = kwargs.fetch(:exception_subject, 'resource')
+
       case response.status
+      when 400
+        raise BadRequestError, "Bad request for #{subject}: #{response.body}"
       when 401
         raise UnauthorizedError, "There was a problem with the access token: #{response.body}"
       when 403
         raise ForbiddenError, "The operation requires privileges which the client does not have: #{response.body}"
       when 404
-        raise ResourceNotFound, "Endpoint not found or resource does not exist: #{response.body}"
+        raise ResourceNotFound, "Endpoint not found or #{subject} does not exist: #{response.body}"
       when 409
         raise ConflictError, "Resource cannot be updated: #{response.body}"
       when 422
@@ -21,10 +23,8 @@ class FolioClient
       when 500
         raise ServiceUnavailable, "The remote server returned an internal server error: #{response.body}"
       else
-        raise StandardError, "Unexpected response: #{response.status} #{response.body}"
+        raise Error, "Unexpected response: #{response.status} #{response.body}"
       end
     end
   end
-  # rubocop:enable Metrics/MethodLength
-  # rubocop:enable Metrics/AbcSize
 end

data/lib/folio_client/version.rb

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

data/lib/folio_client.rb

@@ -41,6 +41,9 @@ class FolioClient
   # Error raised when the Folio API returns a 409 Conflict
   class ConflictError < Error; end
 
+  # Error raised when the Folio API returns a 400 Bad Request
+  class BadRequestError < Error; end
+
   DEFAULT_HEADERS = {
     accept: 'application/json, text/plain',
     content_type: 'application/json'
@@ -50,9 +53,8 @@ class FolioClient
     # @param url [String] the folio API URL
     # @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:)
-    # @param legacy_auth [Boolean] true to use legacy /login rather than Poppy /login-with-expiry endpoint
     # @return [FolioClient] the configured Singleton class
-    def configure(url:, login_params:, okapi_headers:, timeout: default_timeout, legacy_auth: true)
+    def configure(url:, login_params:, okapi_headers:, timeout: default_timeout, **)
       # rubocop:disable Style/OpenStructUse
       instance.config = OpenStruct.new(
         # For the initial token, use a dummy value to avoid hitting any APIs
@@ -69,20 +71,19 @@ class FolioClient
         url: url,
         login_params: login_params,
         okapi_headers: okapi_headers,
-        timeout: timeout,
-        legacy_auth: legacy_auth # default true until we have new token endpoint enabled in Poppy
+        timeout: timeout
       )
       # rubocop:enable Style/OpenStructUse
 
       self
     end
 
-    delegate :config, :connection, :cookie_jar, :data_import, :default_timeout,
-             :edit_marc_json, :fetch_external_id, :fetch_hrid,
-             :fetch_instance_info, :fetch_marc_hash, :fetch_marc_xml,
+    delegate :config, :connection, :cookie_jar, :create_holdings, :data_import, :default_timeout,
+             :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, :users,
+             :job_profiles, :organization_interfaces, :organizations, :update_holdings, :users,
              :user_details, :post, :put, to: :instance
   end
 
@@ -91,6 +92,7 @@ class FolioClient
   # 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
   def get(path, params = {})
     response = with_token_refresh_when_unauthorized do
       connection.get(path, params, { 'x-okapi-token': config.token })
@@ -98,16 +100,14 @@ class FolioClient
 
     UnexpectedResponse.call(response) unless response.success?
 
-    return nil if response.body.blank?
-
-    JSON.parse(response.body)
+    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
-  # rubocop:disable Metrics/MethodLength
+  # @return [Hash, nil] the parsed response body or nil
   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
@@ -120,18 +120,15 @@ class FolioClient
 
     UnexpectedResponse.call(response) unless response.success?
 
-    return nil if response.body.blank?
-
-    JSON.parse(response.body)
+    JSON.parse(response.body) if response.body.present?
   end
-  # rubocop:enable Metrics/MethodLength
 
   # 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
-  # rubocop:disable Metrics/MethodLength
-  def put(path, body = nil, content_type: 'application/json')
+  # @return [Hash, nil] the parsed response body or nil
+  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
       req_headers = {
@@ -141,13 +138,10 @@ class FolioClient
       connection.put(path, req_body, req_headers)
     end
 
-    UnexpectedResponse.call(response) unless response.success?
-
-    return nil if response.body.blank?
+    UnexpectedResponse.call(response, **exception_args) unless response.success?
 
-    JSON.parse(response.body)
+    JSON.parse(response.body) if response.body.present?
   end
-  # rubocop:enable Metrics/MethodLength
 
   # the base connection to the Folio API
   def connection
@@ -188,6 +182,34 @@ class FolioClient
       .fetch_instance_info(...)
   end
 
+  # @see Inventory#fetch_location
+  def fetch_location(...)
+    Inventory
+      .new
+      .fetch_location(...)
+  end
+
+  # @see Inventory#fetch_holdings
+  def fetch_holdings(...)
+    Inventory
+      .new
+      .fetch_holdings(...)
+  end
+
+  # @see Inventory#update_holdings
+  def update_holdings(...)
+    Inventory
+      .new
+      .update_holdings(...)
+  end
+
+  # @see Inventory#create_holdings
+  def create_holdings(...)
+    Inventory
+      .new
+      .create_holdings(...)
+  end
+
   # @see SourceStorage#fetch_marc_hash
   def fetch_marc_hash(...)
     SourceStorage
@@ -203,7 +225,7 @@ class FolioClient
   end
 
   # @see Inventory#has_instance_status?
-  def has_instance_status?(...) # rubocop:disable Naming/PredicateName
+  def has_instance_status?(...) # rubocop:disable Naming/PredicatePrefix
     Inventory
       .new
       .has_instance_status?(...)

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: folio_client
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.20.0
 platform: ruby
 authors:
 - Peter Mangiafico
 bindir: exe
 cert_chain: []
-date: 2025-02-18 00:00:00.000000000 Z
+date: 2026-03-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -79,6 +79,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -274,14 +288,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.3
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Interface for interacting with the Folio ILS API.
 test_files: []