archivesspace-client 0.1.6 → 0.1.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c49aac54a1b49b27bbff319aa83e0a6f7dd711a1e644324ae9d96155b06d417
-  data.tar.gz: bf2fa7e423165f8e03282c718fe819fa7c5836e9090ceacbcf58e642e6ea1938
+  metadata.gz: 84c338c470de7977936e22dae4a7e410a289d3c8211a62927a739645410adad6
+  data.tar.gz: 90acc47cfd00eb091504c8219e7e6b4376213dc7fc816c43cdce2aa2df54bf81
 SHA512:
-  metadata.gz: 7ba30d239390c5066bc5a673e532fb75a3d1fc4f994a8d2726494363f919e3656a5f0d1e7cb730797cbfcf24d404c0447ea1a2243aef6fe4bb9ac1af61117dc4
-  data.tar.gz: 385795fdc7c63144d96696be8a39a3e6f6e4f6c95fa5040be5e9be8d7db7c6a03b4db066bc3900299bb4e05e8d3446a8fa69b9628452beb0b65b477302702ee6
+  metadata.gz: 68e243484eb0b0554fd225ab71775745bba1426edddf0916a21079e5bf13cd62e57ce1f36129e5c57a2d2fd8a817bd47b4fb68b6340ea9f430edc3380e2616dc
+  data.tar.gz: e3a05272dbdbcf2cef2b1ab59bdcff5aef5ef527ee62d31d8006d148c7869deba3c09b01120a975b6e3b6eb448086e3790fc84be82976fc8fafb8071cf43d991

data/Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in archivesspace-client.gemspec

data/README.md

@@ -77,14 +77,68 @@ See `helpers.rb` for more convenience methods such as `client.digital_objects` e
 
 **Setting a repository context**
 
-Update the `base_repo` configuration value to add a repository scope to requests (this is optional).
+Use the `repository` method to add a repository scope to requests (this is optional).
 
 ```ruby
-client.config.base_repo = "repositories/2"
-client.get('digital_objects') # instead of "repositories/2/digital_objects" etc.
+client.repository(2)
+client.get('digital_objects', query: {page: 1}) # instead of "repositories/2/digital_objects" etc.
 
 # to reset
-client.config.base_repo = ""
+client.repository(nil)
+# or
+client.use_global_repository
+```
+
+## Templates
+
+Templates are an optional feature that can help simplify the effort of creating
+json payloads for ArchivesSpace. Rather than construct the json programatically
+according to the schemas a `.erb` template can be used to generate payloads
+instead which are transformed to json automatically. There are a small number of
+templates provided with the client, but you can create your own and access them
+by setting the `ARCHIVESSPACE_CLIENT_TEMPLATES_PATH` envvar. A particularly simple
+template might look like:
+
+```erb
+{
+  "digital_object_id": "<%= data[:digital_object_id] %>",
+  "title": "<%= data[:title] %>"
+}
+```
+
+Practically speaking there isn't much benefit to this example, but in the case of
+a more complex record structure where you want to populate deeply nested elements
+using a flat file structure (like csv) this can be a very convenient way of
+assembling the payload. To process a template:
+
+```ruby
+data = { repo_code: 'ABC', name: 'ABC Archive', agent_contact_name: 'ABC Admin' }
+json = ArchivesSpace::Template.process(:repository_with_agent, data)
+response = client.post('/repositories/with_agent', json)
+puts response.result.success? ? '=)' : '=('
+```
+
+## CLI
+
+Create an `~/.asclientrc` file with a json version of the client configuration:
+
+```json
+{
+  "base_uri": "https://archives.university.edu/api",
+  "base_repo": "",
+  "username": "admin",
+  "password": "123456",
+  "page_size": 50,
+  "throttle": 0,
+  "verify_ssl": false
+}
+```
+
+Run commands:
+
+```bash
+# when using locally via the repo prefix commands with ./exe/ i.e. ./exe/asclient -v
+asclient -v
 ```
 
 ## Development
@@ -110,7 +164,7 @@ bundle exec rake
 Bump version in `lib/archivesspace/client/version.rb` then:
 
 ```bash
-VERSION=0.1.6
+VERSION=$NEW_VERSION
 gem build archivesspace-client
 git add . && git commit -m "Bump to $VERSION"
 git tag v$VERSION

data/Rakefile

@@ -1,6 +1,14 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+# frozen_string_literal: true
 
+require 'bundler/gem_tasks'
+
+require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+# require 'rubocop/rake_task'
+# RuboCop::RakeTask.new
+
+require 'cucumber/rake/task'
+Cucumber::Rake::Task.new
+
+task default: %i[spec cucumber]

data/archivesspace-client.gemspec

@@ -1,31 +1,37 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'archivesspace/client/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "archivesspace-client"
+  spec.name          = 'archivesspace-client'
   spec.version       = ArchivesSpace::Client::VERSION
-  spec.authors       = ["Mark Cooper"]
-  spec.email         = ["mark.c.cooper@outlook.com"]
-  spec.summary       = %q{Interact with ArchivesSpace via its RESTful API.}
-  spec.description   = %q{Interact with ArchivesSpace via its RESTful API.}
-  spec.homepage      = ""
-  spec.license       = "MIT"
+  spec.authors       = ['Mark Cooper']
+  spec.email         = ['mark.c.cooper@outlook.com']
+  spec.summary       = 'Interact with ArchivesSpace via the API.'
+  spec.description   = 'Interact with ArchivesSpace via the API.'
+  spec.homepage      = ''
+  spec.license       = 'MIT'
 
   spec.files         = `git ls-files -z`.split("\x0")
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
-  spec.add_development_dependency "bundler"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "rspec", "3.6.0"
-  spec.add_development_dependency "vcr", "3.0.3"
-  spec.add_development_dependency "webmock", "3.0.1"
-  spec.add_development_dependency "awesome_print", "~> 1.8.0"
+  spec.add_development_dependency 'aruba'
+  spec.add_development_dependency 'awesome_print', '~> 1.8.0'
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'capybara_discoball'
+  spec.add_development_dependency 'cucumber'
+  spec.add_development_dependency 'json_spec'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '3.6.0'
+  spec.add_development_dependency 'vcr', '3.0.3'
+  spec.add_development_dependency 'webmock', '3.0.1'
 
-  spec.add_dependency "httparty", "0.14.0"
-  spec.add_dependency "json", "2.0.3"
-  spec.add_dependency "nokogiri", "1.10.10"
+  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'
 end

data/examples/export.rb

@@ -1,33 +1,36 @@
-$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+# 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: "http://sandbox.archivesspace.org/api",
-  base_repo: "",
-  username: "admin",
-  password: "admin",
-  page_size: 50,
-  throttle: 0,
-  verify_ssl: false,
-})
+config = ArchivesSpace::Configuration.new(
+  {
+    base_uri: 'http://test.archivesspace.org/staff/api',
+    base_repo: '',
+    username: 'admin',
+    password: 'admin',
+    page_size: 50,
+    throttle: 0,
+    verify_ssl: false
+  }
+)
 
 client = ArchivesSpace::Client.new(config).login
 client.config.throttle = 0.5
-client.config.base_repo = "repositories/2"
+client.config.base_repo = 'repositories/2'
 
 begin
-  # date -d '2015-07-01 00:00:00' +'%s' # 1435734000
-  client.resources.each(query: { modified_since: "1435734000"}) do |resource|
+  # 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
-    break
   end
-rescue ArchivesSpace::RequestError => ex
-  puts ex.message
-end
+rescue ArchivesSpace::RequestError => e
+  puts e.message
+end

data/examples/password_reset.rb

@@ -1,15 +1,16 @@
-$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
 require 'awesome_print'
 require 'archivesspace/client'
 
-username = "mrx"
-password = "123456"
+username = 'admin'
+password = 'admin'
 
 # default client connection: localhost:8089, admin, admin
 client = ArchivesSpace::Client.new.login
 begin
-  client.password_reset username, password
-  puts "Successfully updated password for #{username}."
-rescue Exception => ex
-  puts "Failed to update password for #{username},\n#{ex.message}"
+  puts client.password_reset(username, password).parsed
+rescue StandardError => e
+  puts "Failed to update password for #{username},\n#{e.message}"
 end

data/examples/repo_and_user.rb

@@ -1,57 +1,60 @@
-$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+# 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: "http://sandbox.archivesspace.org/api",
-  base_repo: "",
-  username: "admin",
-  password: "admin",
-  page_size: 50,
-  throttle: 0,
-  verify_ssl: false,
-})
-
-# default client connection: localhost:8089, admin, admin
+config = ArchivesSpace::Configuration.new(
+  {
+    base_uri: 'http://sandbox.archivesspace.org/api',
+    base_repo: '',
+    username: 'admin',
+    password: 'admin',
+    page_size: 50,
+    throttle: 0,
+    verify_ssl: false
+  }
+)
+
 client = ArchivesSpace::Client.new(config).login
 
 ap ArchivesSpace::Template.list # view available templates
 
 repo_data = {
-  repo_code: "XYZ",
-  name: "XYZ Archive",
-  agent_contact_name: "John Doe",
+  repo_code: 'XYZ',
+  name: 'XYZ Archive',
+  agent_contact_name: 'XYZ Admin'
 }
 
 user_data = {
-  username: "lmessi",
-  name: "Lionel Messi",
-  is_admin: true,
+  username: 'lmessi',
+  name: 'Lionel Messi',
+  is_admin: true
 }
-user_password = "123456"
+user_password = '123456'
 
-repository = ArchivesSpace::Template.process_template(:repository_with_agent, repo_data)
+repository = ArchivesSpace::Template.process(:repository_with_agent, repo_data)
 
 begin
   response = client.post('/repositories/with_agent', repository)
-  if response.status_code.to_s =~ /^2/
-    repository = client.repositories.find { |r| r["repo_code"] == "XYZ" }
+  if response.result.success?
+    repository = client.repositories.find { |r| r['repo_code'] == 'XYZ' }
     ap repository
-    ap client.delete(repository["uri"])
+    ap client.delete(repository['uri'])
   else
     ap response.parsed
   end
 
-  user = ArchivesSpace::Template.process_template(:user, user_data)
+  user = ArchivesSpace::Template.process(:user, user_data)
   response = client.post('users', user, { password: user_password })
-  if response.status_code.to_s =~ /^2/
-    user = client.users.find { |r| r["username"] == "lmessi" }
+  if response.result.success?
+    user = client.users.find { |r| r['username'] == 'lmessi' }
     ap user
-    ap client.delete user["uri"]
+    ap client.delete user['uri']
   else
     ap response.parsed
   end
-rescue ArchivesSpace::RequestError => ex
-  puts ex.message
+rescue ArchivesSpace::RequestError => e
+  puts e.message
 end

data/examples/test_connection.rb

@@ -1,17 +1,21 @@
-$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+# 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: "http://sandbox.archivesspace.org/api",
-  base_repo: "",
-  username: "admin",
-  password: "admin",
-  page_size: 50,
-  throttle: 0,
-  verify_ssl: false,
-})
+config = ArchivesSpace::Configuration.new(
+  {
+    base_uri: 'http://sandbox.archivesspace.org/api',
+    base_repo: '',
+    username: 'admin',
+    password: 'admin',
+    page_size: 50,
+    throttle: 0,
+    verify_ssl: false
+  }
+)
 
 client = ArchivesSpace::Client.new(config).login
-puts client.get("version").body
+puts client.get('version').body

data/examples/user_groups.rb

@@ -0,0 +1,44 @@
+# 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: 'http://sandbox.archivesspace.org/api',
+    base_repo: '',
+    username: 'admin',
+    password: 'admin',
+    page_size: 50,
+    throttle: 0,
+    verify_ssl: false
+  }
+)
+
+client = ArchivesSpace::Client.new(config).login
+
+user_data = {
+  username: 'bde',
+  name: 'BDE',
+  is_admin: false
+}
+
+client.post(
+  'users',
+  ArchivesSpace::Template.process(:user, 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)
+rescue ArchivesSpace::RequestError => e
+  puts e.message
+end

data/exe/asclient

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'archivesspace/client'
+
+Dry::CLI.new(ArchivesSpace::Client::CLI).call

data/features/exec.feature

@@ -0,0 +1,4 @@
+Feature: Exec
+  Scenario: With an invalid request type
+    When I run `asclient exec all`
+    Then the output should match /asclient exec TYPE PATH/

data/features/support/setup.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'aruba/cucumber'
+require 'json_spec/cucumber'
+require 'capybara_discoball'
+
+def last_json
+  last_command_started.output
+end

data/features/version.feature

@@ -0,0 +1,12 @@
+Feature: Version
+  Scenario: Output with 'v'
+    When I run `asclient v`
+    Then the output should match /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/
+
+  Scenario: Output with -v
+    When I run `asclient -v`
+    Then the output should match /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/
+
+  Scenario: Output with --version
+    When I run `asclient --version`
+    Then the output should match /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/

data/lib/archivesspace/client/cli/exec.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module ArchivesSpace
+  class Client
+    module CLI
+      # ArchivesSpace::Client::CLI::Exec executes an API request
+      class Exec < Dry::CLI::Command
+        desc 'Execute an API request'
+
+        argument :type, required: true, values: %i[get post put delete], desc: 'API request type'
+        argument :path, required: true, desc: 'API request path'
+
+        option   :rid, type: :integer, default: nil, desc: 'Repository id'
+        option   :payload, type: :string, default: '{}', desc: 'Data payload (json)'
+        option   :params, type: :string, default: '{}', desc: 'Params (json)'
+
+        example [
+          'exec get --rid 2 "resources/1"',
+          'exec get users --params \'{"query": {"page": 1}}\''
+        ]
+
+        def call(type:, path:, rid: nil, payload: '{}', params: '{}', **)
+          client = ArchivesSpace::Client::CLI.client
+          client.repository(rid) if rid
+          type    = type.to_sym
+          payload = JSON.parse(payload, symbolize_names: true)
+          params  = JSON.parse(params, symbolize_names: true)
+
+          response = case type
+                     when :get
+                       client.get(path, params)
+                     when :post
+                       client.post(path, payload, params)
+                     when :put
+                       client.put(path, payload, params)
+                     when :delete
+                       client.delete(path)
+                     end
+          puts JSON.generate(response.parsed)
+        end
+      end
+    end
+  end
+end

data/lib/archivesspace/client/cli/version.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ArchivesSpace
+  class Client
+    module CLI
+      # ArchivesSpace::Client::CLI::Version prints version
+      class Version < Dry::CLI::Command
+        desc 'Print ArchivesSpace Client version'
+
+        def call(*)
+          puts ArchivesSpace::Client::VERSION
+        end
+      end
+    end
+  end
+end

data/lib/archivesspace/client/cli.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ArchivesSpace
+  class Client
+    module CLI
+      extend Dry::CLI::Registry
+
+      def self.client
+        cfg = ArchivesSpace::Configuration.new(ArchivesSpace::Client::CLI.find_config)
+        ArchivesSpace::Client.new(cfg).login
+      end
+
+      def self.find_config
+        config = ENV.fetch('ASCLIENT_CFG', File.join(ENV['HOME'], '.asclientrc'))
+        raise "Unable to find asclient configuration file at: #{config}" unless File.file?(config)
+
+        JSON.parse(File.read(config), symbolize_names: true)
+      end
+
+      register 'exec', Exec, aliases: ['e', '-e']
+      register 'version', Version, aliases: ['v', '-v', '--version']
+    end
+  end
+end

data/lib/archivesspace/client/client.rb

@@ -1,43 +1,66 @@
-module ArchivesSpace
+# frozen_string_literal: true
 
+module ArchivesSpace
   class Client
-    include Helpers
+    include Pagination
+    include Task
     attr_accessor :token
     attr_reader   :config
 
     def initialize(config = Configuration.new)
-      unless config.kind_of? ArchivesSpace::Configuration
-        raise "Invalid configuration object"
-      end
+      raise 'Invalid configuration object' unless config.is_a? ArchivesSpace::Configuration
+
       @config = config
       @token  = nil
     end
 
+    def backend_version
+      get 'version'
+    end
+
     def get(path, options = {})
       request 'GET', path, options
     end
 
     def post(path, payload, params = {})
-      request 'POST', path, { body: payload.to_json, query: params }
+      request 'POST', path, { body: payload, query: params }
     end
 
     def put(path, payload, params = {})
-      request 'PUT', path, { body: payload.to_json, query: params }
+      request 'PUT', path, { body: payload, query: params }
     end
 
     def delete(path)
       request 'DELETE', path
     end
 
+    # Scoping requests
+    def repository(id)
+      if id.nil?
+        use_global_repository
+        return
+      end
+
+      begin
+        Integer(id)
+      rescue StandardError
+        raise RepositoryIdError, "Invalid Repository id: #{id}"
+      end
+
+      @config.base_repo = "repositories/#{id}"
+    end
+
+    def use_global_repository
+      @config.base_repo = ''
+    end
+
     private
 
     def request(method, path, options = {})
       sleep config.throttle
-      options[:headers] = { "X-ArchivesSpace-Session" => token } if token
+      options[:headers] = { 'X-ArchivesSpace-Session' => token } if token
       result = Request.new(config, method, path, options).execute
       Response.new result
     end
-
   end
-
 end