archivesspace-client 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36e35f2fa7f6812ba7b022de156325d3d3b24080a2e2d6c4ccb0dc4b62b4d6b0
-  data.tar.gz: cf534f96a24a1937664e40265f726f0329fe225168f651aa8126ec4605faf730
+  metadata.gz: 324a811c6e310286a30371cda14266b61f11570373aa20baf61b1f54b8e3c8d3
+  data.tar.gz: 319354d94ec1fb765a8a811f2ff8273c21342f40fa8e3a5e3c122b4b9af85b92
 SHA512:
-  metadata.gz: 9cfb21a793b424ae322f83942b31b398aabf1036b65fee18c1e50bf8b532200ffb232bc87ef017f81ab14f9bb2fc0b5b1f552a42cd7afe62fd1c256ef7c8be8f
-  data.tar.gz: 3944440ea66c0cd262a94661380f8bd49bf11edf20d55ca17bfb13fe89fcb6e039039802bc86895cc4228eabf8413aada0c3d8efb5f1f8c1d59e2b79aab1d1b7
+  metadata.gz: 1ecd05a580e11e19fd50db9b0f0d4ede6ff816d36d8789d50420a1d1275bf9247c5172b932f3ad9627e96655ce27f919d35e6737816650541615cf5efea22c95
+  data.tar.gz: 679be0bac6c9a81b685ed233e457d98670e00f834946f57d7ed46091bfd83040c0ee12d0e196bddd00a9bfb88fefc8b0c06170dfd294652b4322b958bfdac4df

data/.github/workflows/ci.yml

@@ -3,15 +3,20 @@ on: [pull_request]
 
 jobs:
   tests:
-    name: Tests
+    name: Tests (Ruby ${{ matrix.ruby }})
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.4", "4.0"]
     steps:
       - name: Checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup Ruby and install gems
         uses: ruby/setup-ruby@v1
         with:
+          ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
 
       - name: Lint

data/.github/workflows/publish.yml

@@ -18,7 +18,6 @@ jobs:
         uses: ruby/setup-ruby@v1
         with:
           bundler-cache: true
-          ruby-version: 3.2.2
           rubygems: latest
 
       - name: Release Gem

data/.ruby-version

@@ -1 +1 @@
-3.2.2
+4.0.1

data/README.md

@@ -1,7 +1,28 @@
-# Archivesspace Client
+# ArchivesSpace Client
 
 Interact with ArchivesSpace via the API.
 
+<!-- TOC start (generated with https://github.com/derlin/bitdowntoc) -->
+
+* [Installation](#installation)
+* [Usage](#usage)
+  * [Configuring a client](#configuring-a-client)
+    * [Default configuration](#default-configuration)
+    * [Custom configuration, on the fly](#custom-configuration-on-the-fly)
+    * [Custom configuration, stored for use with CLI or console](#custom-configuration-stored-for-use-with-cli-or-console)
+  * [Making basic requests](#making-basic-requests)
+  * [Setting a repository context](#setting-a-repository-context)
+* [Templates](#templates)
+* [CLI](#cli)
+* [Console usage](#console-usage)
+* [Development](#development)
+* [Publishing](#publishing)
+* [Changelog](#changelog)
+* [Contributing](#contributing)
+* [License](#license)
+
+<!-- TOC end -->
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -26,7 +47,9 @@ gem install archivesspace-client
 
 See the examples directory for a range of use cases.
 
-**Default configuration**
+### Configuring a client
+
+#### Default configuration
 
 Create client with default settings (`localhost:8089`, `admin`, `admin`):
 
@@ -34,12 +57,11 @@ Create client with default settings (`localhost:8089`, `admin`, `admin`):
 client = ArchivesSpace::Client.new.login
 ```
 
-**Custom configuration**
+#### Custom configuration
 
 ```ruby
 config = ArchivesSpace::Configuration.new({
-  base_uri: "https://archives.university.edu/api",
-  base_repo: "",
+  base_uri: "https://archives.university.edu/staff/api",
   username: "admin",
   password: "123456",
   page_size: 50,
@@ -51,7 +73,32 @@ config = ArchivesSpace::Configuration.new({
 client = ArchivesSpace::Client.new(config).login
 ```
 
-**Making basic requests**
+#### Custom configuration, stored for use with CLI or console
+
+Create a file containing JSON config data like:
+
+```json
+{
+  "base_uri": "http://localhost:4567",
+  "username": "admin",
+  "password": "myverysecurepassword",
+  "page_size": 50,
+  "throttle": 0,
+  "timeout": 60,
+  "verify_ssl": false,
+  "debug": true
+}
+```
+
+The CLI and console commands will, by default, look for this stored config at `~/.asclientrc`,
+
+However, you may also set a custom location for the file by setting an ASCLIENT_CFG environment variable. This is handy if you prefer to use [XDG Base Directory Specification](https://xdgbasedirectoryspecification.com/), or have other opinions about where such config should live:
+
+```bash
+export ASCLIENT_CFG="$HOME/.config/archivesspace/client.json"
+```
+
+### Making basic requests
 
 The client responds to the standard request methods:
 
@@ -77,18 +124,46 @@ user = client.users.find { |user| user["username"] == "jdoe" }
 See `pagination.rb` for endpoints that support record type methods such as
 `client.digital_objects` etc.
 
-**Setting a repository context**
+### Setting a repository context
 
 Use the `repository` method to add a repository scope to requests (this is optional).
 
+Instead of doing:
+
 ```ruby
-client.repository(2)
-client.get('digital_objects', query: {page: 1}) # instead of "repositories/2/digital_objects" etc.
+client.get('repositories/2/digital_objects', query: {page: 1})
+```
+
+You can do:
+
+```ruby
+client.repository(2) do
+  client.get('digital_objects', query: {page: 1})
+end
+
+# now back in the global scope
+```
+
+Scopes restore the previous context on exit (even if the block raises) and can
+be nested:
+
+```ruby
+client.repository(2) do
+  client.repository(3) do
+    client.resources  # scoped to repo 3
+  end
+  client.resources    # back to repo 2
+end
+
+# now back in the global scope
+```
+
+You can also set the scope persistently (without a block) and clear it later:
 
-# to reset
-client.repository(nil)
-# or
-client.use_global_repository
+```ruby
+client.repository(2)
+client.resources
+client.use_global_repository  # or: client.repository(nil)
 ```
 
 ## Templates
@@ -124,26 +199,40 @@ To view available templates use: `ArchivesSpace::Template.list`
 
 ## CLI
 
-Create an `~/.asclientrc` file with a json version of the client configuration:
+Create a stored custom configuration to be used with the CLI as described above.
 
-```json
-{
-  "base_uri": "https://archives.university.edu/api",
-  "base_repo": "",
-  "username": "admin",
-  "password": "123456",
-  "page_size": 50,
-  "throttle": 0,
-  "timeout": 60,
-  "verify_ssl": false
-}
+If you installed this client as a gem via the `gem install archivesspace-client` command, you should be able to use the `asclient` command directly.
+
+If entering `asclient` in your terminal returns an error, you will need to use the CLI from within this repository:
+
+```bash
+cd path/to/archivesspace-client
+./exe/asclient
 ```
 
-Run commands:
+The `asclient` command is self-documenting and will show you information about the currently supported commands.
+
+To get more detailed usage info on a command:
 
 ```bash
-# when using locally via the repo prefix commands with ./exe/ i.e. ./exe/asclient -v
-asclient -v
+asclient exec -h
+```
+
+## Console usage
+
+Loading this application in console allows you to play around with its functionality interactively.
+
+Create a stored custom configuration to be used with the console as described above. Then:
+
+```bash
+cd path/to/archivesspace-client
+./bin/console
+```
+
+An IRB session opens. Entering the following should give you the backend version of the ArchivesSpace instance your stored custom config points to:
+
+```ruby
+@client.backend_version
 ```
 
 ## Development
@@ -169,9 +258,26 @@ bundle exec rake
 When an updated version (`lib/archivesspace/client/version.rb`) is merged into the
 main/master branch a new release will be built and published.
 
+## Changelog
+
+### 0.5.0
+
+Breaking changes:
+
+* Removed the `base_repo` configuration option. Use `client.repository(id)` to
+  scope requests to a repository instead, either persistently or with a
+  block that auto-restores the previous scope.
+* `client.repository(id)` with a block now saves and restores the previous
+  context (including when nested or when the block raises), instead of always
+  resetting to the global scope.
+* Login failure now raises `ArchivesSpace::AuthenticationError` (was
+  `ConnectionError`). `ConnectionError` has been removed.
+* `Client.new` raises `ArchivesSpace::ConfigurationError` (was `RuntimeError`)
+  when given a non-`Configuration` argument.
+
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/lyrasis/archivesspace-client.
+Bug reports and pull requests are welcome on GitHub at <https://github.com/lyrasis/archivesspace-client>.
 
 ## License
 

data/archivesspace-client.gemspec

@@ -23,15 +23,14 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "capybara_discoball", "~> 0.1.0"
   spec.add_development_dependency "json_spec", "~> 1.1", ">= 1.1.5"
   spec.add_development_dependency "rake", "~> 13.0"
-  spec.add_development_dependency "rspec", "3.6.0"
-  spec.add_development_dependency "rubocop", "1.56"
-  spec.add_development_dependency "standard", "1.31.0"
-  spec.add_development_dependency "vcr", "6.2.0"
-  spec.add_development_dependency "webmock", "3.19.1"
+  spec.add_development_dependency "rspec", "~> 3.13"
+  spec.add_development_dependency "rubocop", "~> 1.72"
+  spec.add_development_dependency "standard", "~> 1.44"
+  spec.add_development_dependency "vcr", "~> 6.3"
+  spec.add_development_dependency "webmock", "~> 3.24"
 
   spec.add_dependency "dry-cli", "~> 0.7"
   spec.add_dependency "httparty", "~> 0.14"
   spec.add_dependency "json", "~> 2.0"
-  spec.add_dependency "nokogiri", "~> 1.10"
-  spec.add_dependency "jbuilder", "~> 2.11.5"
+  spec.add_dependency "jbuilder", "~> 2.12"
 end

data/bin/console

@@ -5,15 +5,7 @@ require "bundler/setup"
 require "archivesspace/client"
 
 config = ArchivesSpace::Configuration.new(
-  {
-    base_uri: "https://test.archivesspace.org/staff/api",
-    base_repo: "",
-    username: "admin",
-    password: "admin",
-    page_size: 50,
-    throttle: 0,
-    verify_ssl: false
-  }
+  ArchivesSpace::Client::CLI.find_config
 )
 @client = ArchivesSpace::Client.new(config).login
 

data/examples/export.rb

@@ -1,14 +1,13 @@
 # frozen_string_literal: true
 
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
-require "awesome_print"
 require "archivesspace/client"
+require "nokogiri"
 
 # official sandbox
 config = ArchivesSpace::Configuration.new(
   {
     base_uri: "https://test.archivesspace.org/staff/api",
-    base_repo: "",
     username: "admin",
     password: "admin",
     page_size: 50,
@@ -19,17 +18,18 @@ config = ArchivesSpace::Configuration.new(
 
 client = ArchivesSpace::Client.new(config).login
 client.config.throttle = 0.5
-client.config.base_repo = "repositories/2"
 
 begin
-  # date -d '2021-02-01 00:00:00' +'%s' # 1612166400
-  client.resources(query: {modified_since: "1612166400"}).each do |resource|
-    # for now we are just printing ...
-    # but you would actually write to a zip file or whatever
-    id = resource["uri"].split("/")[-1]
-    opts = {include_unpublished: false}
-    response = client.get("resource_descriptions/#{id}.xml", opts)
-    puts Nokogiri::XML(response.body).to_xml
+  client.repository 2 do
+    # date -d '2021-02-01 00:00:00' +'%s' # 1612166400
+    client.resources(query: {modified_since: "1612166400"}).each do |resource|
+      # for now we are just printing ...
+      # but you would actually write to a zip file or whatever
+      id = resource["uri"].split("/")[-1]
+      opts = {include_unpublished: false}
+      response = client.get("resource_descriptions/#{id}.xml", opts)
+      puts Nokogiri::XML(response.body).to_xml
+    end
   end
 rescue ArchivesSpace::RequestError => e
   puts e.message

data/examples/password_reset.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
-require "awesome_print"
 require "archivesspace/client"
 
 username = "admin"

data/examples/repo_and_user.rb

@@ -1,14 +1,12 @@
 # frozen_string_literal: true
 
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
-require "awesome_print"
 require "archivesspace/client"
 
 # official sandbox
 config = ArchivesSpace::Configuration.new(
   {
-    base_uri: "https://sandbox.archivesspace.org/api",
-    base_repo: "",
+    base_uri: "https://sandbox.archivesspace.org/staff/api",
     username: "admin",
     password: "admin",
     page_size: 50,
@@ -19,7 +17,7 @@ config = ArchivesSpace::Configuration.new(
 
 client = ArchivesSpace::Client.new(config).login
 
-ap ArchivesSpace::Template.list # view available templates
+puts ArchivesSpace::Template.list # view available templates
 
 repo_data = {
   repo_code: "XYZ",
@@ -40,20 +38,20 @@ begin
   response = client.post("/repositories/with_agent", repository)
   if response.result.success?
     repository = client.repositories.find { |r| r["repo_code"] == "XYZ" }
-    ap repository
-    ap client.delete(repository["uri"])
+    puts repository
+    puts client.delete(repository["uri"])
   else
-    ap response.parsed
+    puts response.parsed
   end
 
   user = ArchivesSpace::Template.process("user.json.erb", user_data)
   response = client.post("users", user, {password: user_password})
   if response.result.success?
     user = client.users.find { |r| r["username"] == "lmessi" }
-    ap user
-    ap client.delete user["uri"]
+    puts user
+    puts client.delete(user["uri"]).inspect
   else
-    ap response.parsed
+    puts response.parsed
   end
 rescue ArchivesSpace::RequestError => e
   puts e.message

data/examples/templates.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
-require "awesome_print"
 require "archivesspace/client"
 
 puts ArchivesSpace::Template.list

data/examples/test_connection.rb

@@ -1,14 +1,12 @@
 # frozen_string_literal: true
 
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
-require "awesome_print"
 require "archivesspace/client"
 
 # official sandbox
 config = ArchivesSpace::Configuration.new(
   {
-    base_uri: "https://sandbox.archivesspace.org/api",
-    base_repo: "",
+    base_uri: "https://test.archivesspace.org/staff/api",
     username: "admin",
     password: "admin",
     page_size: 50,
@@ -18,4 +16,16 @@ config = ArchivesSpace::Configuration.new(
 )
 
 client = ArchivesSpace::Client.new(config).login
+
+# globally scoped
 puts client.get("version").body
+puts client.get("repositories").body
+puts client.all("users").map { |u| u["username"] }.to_a
+
+# repo scoped
+client.repository 2 do
+  puts client.get("accessions", query: {page: 1}).parsed["results"].map { |a| a["uri"] }.to_a
+end
+
+# globally scoped, full path arg
+puts client.get("repositories/2/resources", query: {all_ids: true}).body

data/examples/update_feed.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "archivesspace/client"
+
+config = ArchivesSpace::Configuration.new(
+  {
+    base_uri: "https://test.archivesspace.org/staff/api",
+    username: "admin",
+    password: "admin",
+    page_size: 50,
+    throttle: 0,
+    verify_ssl: false
+  }
+)
+
+client = ArchivesSpace::Client.new(config).login
+response = client.get("update-feed")
+last_sequence = response.parsed[0]["sequence"] # get initial sequence value
+
+# This is an example only, would also need to handle session/token expiration
+loop do
+  puts "Using sequence: #{last_sequence}"
+  begin
+    response = client.get("update-feed", query: {last_sequence: last_sequence})
+    if response.result.success?
+      last_sequence = response.parsed.last["sequence"]
+      # do something with the response
+      puts response.parsed.to_json
+    end
+  rescue Net::ReadTimeout
+    # this is ok if no updates are made within the last 60 seconds
+    # (well, as defined by the timeout in client/AppConfig)
+  rescue => e
+    # some other kind of error occurred
+    puts e.message
+    break # or handle it in some other way
+  end
+end

data/examples/user_groups.rb

@@ -1,14 +1,12 @@
 # frozen_string_literal: true
 
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
-require "awesome_print"
 require "archivesspace/client"
 
 # official sandbox
 config = ArchivesSpace::Configuration.new(
   {
-    base_uri: "https://sandbox.archivesspace.org/api",
-    base_repo: "",
+    base_uri: "https://sandbox.archivesspace.org/staff/api",
     username: "admin",
     password: "admin",
     page_size: 50,
@@ -19,26 +17,23 @@ config = ArchivesSpace::Configuration.new(
 
 client = ArchivesSpace::Client.new(config).login
 
-user_data = {
+user_data = ArchivesSpace::Template.process("user.json.erb", {
   username: "bde",
   name: "BDE",
   is_admin: false
-}
+})
 
-client.post(
-  "users",
-  ArchivesSpace::Template.process("user.json.erb", user_data),
-  {password: "123456"}
-)
+client.post("users", user_data, {password: "123456"})
 
 users_with_roles = {
   "bde" => ["repository-basic-data-entry"]
 }
 
 begin
-  client.config.base_repo = "repositories/2"
-  results = client.group_user_assignment users_with_roles
-  ap results.map(&:parsed)
+  client.repository 2 do
+    results = client.group_user_assignment users_with_roles
+    puts results.map(&:parsed)
+  end
 rescue ArchivesSpace::RequestError => e
   puts e.message
 end

data/lib/archivesspace/client/client.rb

@@ -4,15 +4,20 @@ module ArchivesSpace
   class Client
     include Pagination
     include Task
+
     attr_accessor :token
-    attr_reader :config
+    attr_reader :config, :context
 
     NAME = "ArchivesSpaceClient"
+    TOKEN = "X-ArchivesSpace-Session"
 
     def initialize(config = Configuration.new)
-      raise "Invalid configuration object" unless config.is_a? ArchivesSpace::Configuration
+      unless config.is_a? ArchivesSpace::Configuration
+        raise ConfigurationError, "expected ArchivesSpace::Configuration, got #{config.class}"
+      end
 
       @config = config
+      @context = nil
       @token = nil
     end
 
@@ -38,31 +43,36 @@ module ArchivesSpace
 
     # Scoping requests
     def repository(id)
-      if id.nil?
-        use_global_repository
-        return
-      end
+      return use_global_repository if id.nil?
 
       begin
         Integer(id)
-      rescue
+      rescue ArgumentError, TypeError
         raise RepositoryIdError, "Invalid Repository id: #{id}"
       end
 
-      @config.base_repo = "repositories/#{id}"
+      new_context = "repositories/#{id}"
+      return @context = new_context unless block_given?
+
+      previous = @context
+      @context = new_context
+      begin
+        yield
+      ensure
+        @context = previous
+      end
     end
 
     def use_global_repository
-      @config.base_repo = ""
+      @context = nil
     end
 
     private
 
     def request(method, path, options = {})
       sleep config.throttle
-      options[:headers] = {"X-ArchivesSpace-Session" => token} if token
-      result = Request.new(config, method, path, options).execute
-      Response.new result
+      options[:headers] = {TOKEN => token} if token
+      Request.new(context, config, method, path, options).execute
     end
   end
 end

data/lib/archivesspace/client/configuration.rb

@@ -2,27 +2,25 @@
 
 module ArchivesSpace
   class Configuration
-    def defaults
-      {
-        base_uri: "http://localhost:8089",
-        base_repo: "",
-        debug: false,
-        username: "admin",
-        password: "admin",
-        page_size: 50,
-        throttle: 0,
-        verify_ssl: true,
-        timeout: 60
-      }
-    end
+    attr_accessor :base_uri, :debug, :username, :password,
+      :page_size, :throttle, :timeout, :verify_ssl
+
+    DEFAULTS = {
+      base_uri: "http://localhost:8089",
+      debug: false,
+      username: "admin",
+      password: "admin",
+      page_size: 50,
+      throttle: 0,
+      timeout: 60,
+      verify_ssl: true
+    }.freeze
 
     def initialize(settings = {})
-      settings = defaults.merge(settings)
-      settings.each do |property, value|
-        next unless defaults.key?(property)
+      DEFAULTS.merge(settings).each do |property, value|
+        next unless DEFAULTS.key?(property)
 
-        instance_variable_set(:"@#{property}", value)
-        self.class.send(:attr_accessor, property)
+        send(:"#{property}=", value)
       end
     end
   end

data/lib/archivesspace/client/pagination.rb

@@ -33,6 +33,7 @@ module ArchivesSpace
         loop do
           options[:query] ||= {}
           options[:query][:page] = page
+          options[:query][:page_size] ||= config.page_size
           result = get(path, options)
           results = []
 

data/lib/archivesspace/client/request.rb

@@ -3,44 +3,32 @@
 module ArchivesSpace
   class Request
     include HTTParty
+
     attr_reader :config, :headers, :method, :path, :options
 
-    def default_headers(method = :get)
-      headers = {
-        delete: {},
-        get: {},
-        post: {
-          "Content-Type" => "application/json",
-          "Content-Length" => "nnnn"
-        },
-        put: {
-          "Content-Type" => "application/json",
-          "Content-Length" => "nnnn"
-        }
-      }
-      headers[method]
-    end
+    DEFAULT_HEADERS = {"Content-Type" => "application/json"}.freeze
 
-    def initialize(config, method = "GET", path = "", options = {})
+    def initialize(context, config, method = "GET", path = "", options = {})
       @config = config
+
       @method = method.downcase.to_sym
       @path = path.gsub(%r{^/+}, "")
+
       @options = options
-      @options[:headers] =
-        options[:headers] ? default_headers(@method).merge(options[:headers]) : default_headers(@method)
+
+      @options[:headers] = DEFAULT_HEADERS.merge(@options.fetch(:headers, {}))
       @options[:headers]["User-Agent"] = "#{Client::NAME}/#{Client::VERSION}"
+
       @options[:verify] = config.verify_ssl
       @options[:timeout] = config.timeout
       @options[:query] = {} unless options.key? :query
 
       self.class.debug_output($stdout) if @config.debug
-
-      base_uri = config.base_repo&.length&.positive? ? File.join(config.base_uri, config.base_repo) : config.base_uri
-      self.class.base_uri base_uri
+      self.class.base_uri context ? "#{config.base_uri}/#{context}" : config.base_uri
     end
 
     def execute
-      self.class.send method, "/#{path}", options
+      Response.new(self.class.send(method, "/#{path}", options))
     end
   end
 end

data/lib/archivesspace/client/task.rb

@@ -3,10 +3,6 @@
 module ArchivesSpace
   # Perform specific API tasks
   module Task
-    # def batch_import(payload, params = {})
-    #   # TODO: create "batch_import", payload, params
-    # end
-
     def group_user_assignment(users_with_roles)
       updated = []
       groups.each do |group|
@@ -29,7 +25,7 @@ module ArchivesSpace
 
         next unless update
 
-        response = post("/groups/#{uri_to_id(group["uri"])}", group.to_json)
+        response = post("/groups/#{uri_to_id(group["uri"])}", group)
         updated << response
       end
       updated
@@ -38,29 +34,29 @@ module ArchivesSpace
     def login
       username = config.username
       password = config.password
-      base_repo = config.base_repo
-      use_global_repository # ensure we're in the global scope to login
-      result = request("POST", "/users/#{username}/login", {query: {password: password}})
-      unless result.parsed["session"]
-        raise ConnectionError, "API client login failed as user [#{username}], check username and password are correct"
-      end
 
-      config.base_repo = base_repo # reset repo as set by the cfg
-      @token = result.parsed["session"]
-      self
+      previous_context = @context
+      @context = nil
+      begin
+        result = request("POST", "/users/#{username}/login", {query: {password: password}})
+        unless result.parsed["session"]
+          raise AuthenticationError, "Login failed as user [#{username}] (status #{result.status_code}); check username and password"
+        end
+
+        @token = result.parsed["session"]
+        self
+      ensure
+        @context = previous_context
+      end
     end
 
     def password_reset(username, password)
       user = all("users").find { |u| u["username"] == username }
-      raise RequestError, user.status unless user
+      raise RequestError, "User not found: #{username}" unless user
 
-      post(user["uri"], user.to_json, {password: password})
+      post(user["uri"], user, {password: password})
     end
 
-    # def search(params)
-    #   # TODO: get "search", params
-    # end
-
     private
 
     def uri_to_id(uri)

data/lib/archivesspace/client/template.rb

@@ -7,7 +7,7 @@ module ArchivesSpace
     end
 
     def self.process(template, data)
-      processor = File.extname(template).delete(".").camelize
+      processor = File.extname(template).delete(".").capitalize
       processor = Object.const_get("ArchivesSpace::Template::#{processor}")
       processor.new(template, data).process
     end
@@ -50,7 +50,7 @@ module ArchivesSpace
       def process
         t = ERB.new(read_template)
         r = t.result(binding).squeeze("\n")
-        JSON.parse(r).to_json
+        JSON.parse(r)
       end
     end
 
@@ -60,9 +60,9 @@ module ArchivesSpace
       end
 
       def process
-        ::Jbuilder.encode do |json|
+        ::Jbuilder.new do |json|
           eval(read_template, binding) # standard:disable Security/Eval
-        end
+        end.attributes!
       end
     end
   end

data/lib/archivesspace/client/version.rb

@@ -2,6 +2,6 @@
 
 module ArchivesSpace
   class Client
-    VERSION = "0.4.1"
+    VERSION = "0.5.0"
   end
 end

data/lib/archivesspace/client.rb

@@ -3,7 +3,6 @@
 require "dry/cli"
 require "httparty"
 require "json"
-require "nokogiri"
 require "jbuilder"
 
 # mixins required first
@@ -23,13 +22,11 @@ require "archivesspace/client/cli/version"
 require "archivesspace/client/cli" # load the registry last
 
 module ArchivesSpace
-  class ConnectionError < RuntimeError; end
+  class AuthenticationError < StandardError; end
 
-  class ContextError < RuntimeError; end
+  class ConfigurationError < StandardError; end
 
-  class RepositoryIdError < RuntimeError; end
+  class RepositoryIdError < StandardError; end
 
-  class ParamsError < RuntimeError; end
-
-  class RequestError < RuntimeError; end
+  class RequestError < StandardError; end
 end

data/spec/archivesspace/client_spec.rb

@@ -11,7 +11,7 @@ describe ArchivesSpace::Client do
     end
 
     it "will raise an error if supplied configuration is of invalid type" do
-      expect { ArchivesSpace::Client.new({base_uri: CUSTOM_BASE_URI}) }.to raise_error(RuntimeError)
+      expect { ArchivesSpace::Client.new({base_uri: CUSTOM_BASE_URI}) }.to raise_error(ArchivesSpace::ConfigurationError)
     end
 
     it "will allow a configuration object to be provided" do
@@ -20,15 +20,86 @@ describe ArchivesSpace::Client do
     end
   end
 
+  describe "Login" do
+    it "sends the login request at global scope even when a repo context is set" do
+      client.repository 2
+      expect(ArchivesSpace::Request).to receive(:new)
+        .with(nil, client.config, "POST", "/users/admin/login", anything)
+        .and_wrap_original do |_orig, *_args|
+          double("request", execute: double("response", parsed: {"session" => "token"}, status_code: 200))
+        end
+      client.login
+    end
+
+    it "restores the previous repo context after login" do
+      client.repository 2
+      allow(ArchivesSpace::Request).to receive(:new).and_return(
+        double("request", execute: double("response", parsed: {"session" => "token"}, status_code: 200))
+      )
+      client.login
+      expect(client.context).to eq "repositories/2"
+    end
+
+    it "raises AuthenticationError and restores context when credentials are rejected" do
+      client.repository 2
+      allow(ArchivesSpace::Request).to receive(:new).and_return(
+        double("request", execute: double("response", parsed: {}, status_code: 403))
+      )
+      expect { client.login }.to raise_error(ArchivesSpace::AuthenticationError, /status 403/)
+      expect(client.context).to eq "repositories/2"
+    end
+
+    it "raises AuthenticationError for a real 403 response (VCR)" do
+      bad_client = ArchivesSpace::Client.new(
+        ArchivesSpace::Configuration.new(password: "wrong")
+      )
+      VCR.use_cassette("login_failure") do
+        expect { bad_client.login }.to raise_error(
+          ArchivesSpace::AuthenticationError, /admin.*status 403/
+        )
+      end
+    end
+  end
+
+  describe "Pagination" do
+    it "will have a method for defined paginated record types" do
+      ArchivesSpace::Pagination::ENDPOINTS.each do |e|
+        next if e.match?("/")
+
+        expect(client.respond_to?(e.to_sym)).to be true
+      end
+    end
+
+    it "will have a method for defined paginated record types with multipart path" do
+      expect(client.respond_to?(:people)).to be true
+    end
+
+    it "will pass page_size from configuration to the query" do
+      response = double("response", parsed: {"results" => []})
+      allow(client).to receive(:get).and_return(response)
+      client.all("resources").first
+      expect(client).to have_received(:get).with("resources", hash_including(query: hash_including(page_size: 50)))
+    end
+  end
+
+  describe "Password reset" do
+    it "will raise an error if the user is not found" do
+      allow(client).to receive(:all).with("users").and_return([].lazy)
+      expect { client.password_reset("nonexistent", "newpass") }.to raise_error(
+        ArchivesSpace::RequestError, "User not found: nonexistent"
+      )
+    end
+  end
+
   describe "Repository scoping" do
-    it "will set the repository with an integer id" do
+    it "will set the context with an integer id" do
       client.repository 2
-      expect(client.config.base_repo).to eq "repositories/2"
+      expect(client.context).to eq "repositories/2"
     end
 
-    it "will set the repository with a string id cast to integer" do
+    it "will set the context with a string id cast to integer" do
       client.repository "2"
-      expect(client.config.base_repo).to eq "repositories/2"
+      expect(client.context).to eq "repositories/2"
     end
 
     it "will fail if the id cannot be cast to integer" do
@@ -37,37 +108,81 @@ describe ArchivesSpace::Client do
       )
     end
 
-    it "will use the global repo if repository is passed nil" do
+    it "will fail if the id is not a valid type" do
+      expect { client.repository([]) }.to raise_error(
+        ArchivesSpace::RepositoryIdError
+      )
+    end
+
+    it "will clear the context when passed nil" do
       client.repository 2
       client.repository nil
-      expect(client.config.base_repo).to eq ""
+      expect(client.context).to be_nil
     end
 
-    it "will use the global repo when the method is called" do
+    it "will clear the context when use_global_repository is called" do
       client.repository 2
       client.use_global_repository
-      expect(client.config.base_repo).to eq ""
+      expect(client.context).to be_nil
+    end
+
+    it "scopes the context to a block and restores afterwards" do
+      client.repository(2) do
+        expect(client.context).to eq "repositories/2"
+      end
+      expect(client.context).to be_nil
+    end
+
+    it "restores the previous context when nested" do
+      client.repository 2
+      client.repository(3) do
+        expect(client.context).to eq "repositories/3"
+      end
+      expect(client.context).to eq "repositories/2"
+    end
+
+    it "restores the context even if the block raises" do
+      expect { client.repository(2) { raise "boom" } }.to raise_error("boom")
+      expect(client.context).to be_nil
+    end
+
+    it "does not rebrand ArgumentError raised from within the block" do
+      expect {
+        client.repository(2) { raise ArgumentError, "from caller" }
+      }.to raise_error(ArgumentError, "from caller")
     end
   end
 
   describe "Requests" do
     it "will have an identifiable user agent" do
-      request = ArchivesSpace::Request.new(client.config)
+      request = ArchivesSpace::Request.new(nil, client.config)
       expect(request.options[:headers]["User-Agent"]).to eq "#{ArchivesSpace::Client::NAME}/#{ArchivesSpace::Client::VERSION}"
     end
   end
 
-  describe "Pagination" do
-    it "will have a method for defined paginated record types" do
-      ArchivesSpace::Pagination::ENDPOINTS.each do |e|
-        next if e.match?("/")
+  describe "URL construction" do
+    let(:config) { ArchivesSpace::Configuration.new(base_uri: "http://localhost:8089") }
 
-        expect(client.respond_to?(e.to_sym)).to be true
-      end
+    it "uses the bare base_uri when context is nil" do
+      ArchivesSpace::Request.new(nil, config, "GET", "repositories")
+      expect(ArchivesSpace::Request.base_uri).to eq "http://localhost:8089"
     end
 
-    it "will have a method for defined paginated record types with multipart path" do
-      expect(client.respond_to?(:people)).to be true
+    it "appends a repository context to the base_uri" do
+      ArchivesSpace::Request.new("repositories/2", config, "GET", "resources")
+      expect(ArchivesSpace::Request.base_uri).to eq "http://localhost:8089/repositories/2"
+    end
+
+    it "preserves a path prefix in base_uri when context is nil" do
+      config.base_uri = "https://example.org/staff/api"
+      ArchivesSpace::Request.new(nil, config, "GET", "repositories")
+      expect(ArchivesSpace::Request.base_uri).to eq "https://example.org/staff/api"
+    end
+
+    it "preserves a path prefix in base_uri when scoped to a repository" do
+      config.base_uri = "https://example.org/staff/api"
+      ArchivesSpace::Request.new("repositories/2", config, "GET", "resources")
+      expect(ArchivesSpace::Request.base_uri).to eq "https://example.org/staff/api/repositories/2"
     end
   end
 

data/spec/archivesspace/templates_spec.rb

@@ -21,14 +21,14 @@ describe ArchivesSpace::Template do
 
   it "can process an erb template" do
     data = {repo_code: "ABC", name: "ABC Archive", agent_contact_name: "ABC Admin"}
-    json = JSON.parse(ArchivesSpace::Template.process("repository_with_agent.json.erb", data))
-    expect(json["repository"]["repo_code"]).to eq data[:repo_code]
+    record = ArchivesSpace::Template.process("repository_with_agent.json.erb", data)
+    expect(record["repository"]["repo_code"]).to eq data[:repo_code]
   end
 
   it "can process a jbuilder template" do
     data = {"title" => "Title", "object_number" => "001.001", "description_level" => "collection"}
-    json = JSON.parse(ArchivesSpace::Template.process("resource.json.jbuilder", data))
-    expect(json["id_0"]).to eq data["object_number"]
+    record = ArchivesSpace::Template.process("resource.json.jbuilder", data)
+    expect(record["id_0"]).to eq data["object_number"]
   end
 
   it "rejects a template that does not match by extension" do

data/spec/fixtures/cassettes/login_failure.yml

@@ -0,0 +1,37 @@
+---
+http_interactions:
+- request:
+    method: post
+    uri: http://localhost:8089/users/admin/login?password=wrong
+    body:
+      encoding: UTF-8
+      string: ''
+    headers:
+      Content-Type:
+      - application/json
+      User-Agent:
+      - ArchivesSpaceClient/0.3.0
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+      Accept:
+      - "*/*"
+  response:
+    status:
+      code: 403
+      message: Forbidden
+    headers:
+      Cache-Control:
+      - private, must-revalidate, max-age=0
+      Content-Type:
+      - application/json
+      X-Content-Type-Options:
+      - nosniff
+      Content-Length:
+      - '24'
+      Server:
+      - Jetty(9.4.44.v20210927)
+    body:
+      encoding: UTF-8
+      string: '{"error":"Login failed"}'
+  recorded_at: Tue, 22 Apr 2026 12:00:00 GMT
+recorded_with: VCR 6.3.1

data/spec/spec_helper.rb

@@ -6,8 +6,8 @@ require "vcr"
 require "webmock/rspec"
 
 # GLOBAL VALUES FOR SPECS
-DEFAULT_BASE_URI = "http://localhost:8089"
 CUSTOM_BASE_URI = "https://archives.university.edu/api"
+DEFAULT_BASE_URI = "http://localhost:8089"
 
 VCR.configure do |c|
   c.cassette_library_dir = "spec/fixtures/cassettes"

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: archivesspace-client
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Mark Cooper
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-04-19 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aruba
@@ -76,72 +75,72 @@ dependencies:
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.6.0
+        version: '3.13'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.6.0
+        version: '3.13'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.56'
+        version: '1.72'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.56'
+        version: '1.72'
 - !ruby/object:Gem::Dependency
   name: standard
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.31.0
+        version: '1.44'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.31.0
+        version: '1.44'
 - !ruby/object:Gem::Dependency
   name: vcr
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 6.2.0
+        version: '6.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 6.2.0
+        version: '6.3'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.19.1
+        version: '3.24'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.19.1
+        version: '3.24'
 - !ruby/object:Gem::Dependency
   name: dry-cli
   requirement: !ruby/object:Gem::Requirement
@@ -184,34 +183,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: nokogiri
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.10'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.10'
 - !ruby/object:Gem::Dependency
   name: jbuilder
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.11.5
+        version: '2.12'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.11.5
+        version: '2.12'
 description: Interact with ArchivesSpace via the API.
 email:
 - mark.c.cooper@outlook.com
@@ -237,6 +222,7 @@ files:
 - examples/repo_and_user.rb
 - examples/templates.rb
 - examples/test_connection.rb
+- examples/update_feed.rb
 - examples/user_groups.rb
 - exe/asclient
 - features/exec.feature
@@ -263,12 +249,12 @@ files:
 - spec/archivesspace/configuration_spec.rb
 - spec/archivesspace/templates_spec.rb
 - spec/fixtures/cassettes/backend_version.yml
+- spec/fixtures/cassettes/login_failure.yml
 - spec/spec_helper.rb
 homepage: ''
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -283,8 +269,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
-signing_key: 
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Interact with ArchivesSpace via the API.
 test_files: []