collectionspace-client 0.1.5 → 0.14.1

data/examples/search.rb

@@ -1,67 +1,34 @@
-$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
 require 'awesome_print'
 require 'collectionspace/client'
 
-# CREATE CLIENT WITH DEFAULT (DEMO) CONFIGURATION -- BE NICE!!!
-client = CollectionSpace::Client.new
-
-# EXAMPLE NESTED ATTRIBUTE SEARCH
-search_args = {
-  path: "collectionobjects",
-  type: "collectionobjects_common",
-  field: 'titleGroupList/*1/title',
-  expression: "ILIKE '%blue%'",
-}
-
-query = CollectionSpace::Search.new.from_hash search_args
-ap client.search(query).parsed
+config = CollectionSpace::Configuration.new(
+  base_uri: 'https://core.dev.collectionspace.org/cspace-services',
+  username: 'admin@core.collectionspace.org',
+  password: 'Administrator'
+)
 
-# SEARCH AND REFORMAT RESULTS
-
-# assume retrieved for collectionobject i.e.: AttributeMap.where(type: 'collectionobject')
-attribute_map = [
-  { field: 'title', key: 'collectionobjects_common', nested_key: 'title', with: nil },
-  { field: 'title_type', key: 'collectionobjects_common', nested_key: 'titleType', with: nil },
-  { field: 'display_date', key: 'collectionobjects_common', nested_key: 'dateDisplayDate', with: nil },
-  { field: 'object_production_person_group', key: 'collectionobjects_common', nested_key: 'objectProductionPersonGroup', with: 'objectProductionPerson' },
-  { field: 'content_persons', key: 'collectionobjects_common', nested_key: 'contentPersons', with: 'contentPerson' },
-  { field: 'responsible_department', key: 'collectionobjects_common', nested_key: 'responsibleDepartment', with: nil },
-  { field: 'created_by', key: 'collectionspace_core', nested_key: 'createdBy', with: nil },
-  { field: 'created_at', key: 'collectionspace_core', nested_key: 'createdAt', with: nil },
-  { field: 'updated_at', key: 'collectionspace_core', nested_key: 'updatedAt', with: nil },
-]
+client = CollectionSpace::Client.new(config)
 
 search_args = {
-  path: "collectionobjects",
-  type: "collectionspace_core",
-  field: 'updatedAt',
-  expression: ">= TIMESTAMP '2015-12-17T00:00:00'",
+  path: 'groups',
+  namespace: 'groups_common',
+  field: 'title',
+  expression: "ILIKE '%D%'"
 }
 
-query = CollectionSpace::Search.new.from_hash search_args
-
-result = client.search(query)
-if result.status_code == 200
-  data = result.parsed["abstract_common_list"]["list_item"]
-  data.each do |item|
-    record = client.get(item["uri"]).parsed
-
-    attributes = {}
-    attribute_map.each do |map|
-      if map[:with]
-        as = client.deep_find(record, map[:key], map[:nested_key])
-        values = []
-        if as.is_a? Array
-          values = as.map { |a| client.strip_refname( client.deep_find(a, map[:with]) ) }
-        elsif as.is_a? Hash and as[ map[:with] ]
-          values = as[ map[:with] ].is_a?(Array) ? as[ map[:with] ].map { |a| client.strip_refname(a) } : [ client.strip_refname(as[ map[:with] ]) ]
-        end
-        attributes[map[:field]] = values
-      else
-        attributes[map[:field]] = client.deep_find(record, map[:key], map[:nested_key])
-      end
-    end
-    # PRINT REFORMATTED RESULTS
-    ap attributes
+puts 'Search: %D'
+response = client.search(
+  CollectionSpace::Search.new.from_hash(search_args),
+  { sortBy: CollectionSpace::Search::DEFAULT_SORT }
+)
+if response.result.success?
+  response.parsed['abstract_common_list']['list_item'].map do |i|
+    puts i['uri']
   end
-end
+end
+
+puts 'Object and authority term searches have been moved to spec.'
+puts 'See helpers_spec.rb examples describing find'

data/examples/update_password.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+puts 'Update password has been moved to Rake task: `cli:update_password[args...]`'

data/lib/collectionspace/client/client.rb

@@ -1,12 +1,16 @@
-module CollectionSpace
+# frozen_string_literal: true
 
+module CollectionSpace
+  # CollectionSpace client
   class Client
-    include DeepFind
     include Helpers
     attr_reader :config
 
     def initialize(config = Configuration.new)
-      raise "Invalid configuration object" unless config.kind_of? CollectionSpace::Configuration
+      unless config.is_a? CollectionSpace::Configuration
+        raise CollectionSpace::ArgumentError, 'Invalid configuration object'
+      end
+
       @config = config
     end
 
@@ -14,15 +18,14 @@ module CollectionSpace
       request 'GET', path, options
     end
 
-    # additional_options: { query: { foo: 'bar' } }
-    def post(path, payload, additional_options = {})
-      raise PayloadError.new, Nokogiri::XML(payload).errors if Nokogiri::XML(payload).errors.any?
-      request 'POST', path, { body: payload }.merge(additional_options)
+    def post(path, payload, options = {})
+      check_payload(payload)
+      request 'POST', path, { body: payload }.merge(options)
     end
 
-    def put(path, payload)
-      raise PayloadError.new, Nokogiri::XML(payload).errors if Nokogiri::XML(payload).errors.any?
-      request 'PUT', path, { body: payload }
+    def put(path, payload, options = {})
+      check_payload(payload)
+      request 'PUT', path, { body: payload }.merge(options)
     end
 
     def delete(path)
@@ -31,12 +34,14 @@ module CollectionSpace
 
     private
 
+    def check_payload(payload)
+      errors = Nokogiri::XML(payload).errors
+      raise CollectionSpace::PayloadError, errors if errors.any?
+    end
+
     def request(method, path, options = {})
       sleep config.throttle
-      result = Request.new(config, method, path, options).execute
-      Response.new result
+      Response.new(Request.new(config, method, path, options).execute)
     end
-
   end
-
 end

data/lib/collectionspace/client/configuration.rb

@@ -1,28 +1,27 @@
-module CollectionSpace
+# frozen_string_literal: true
 
+module CollectionSpace
+  # CollectionSpace configuration
   class Configuration
+    DEFAULTS = {
+      base_uri: nil,
+      username: nil,
+      password: nil,
+      page_size: 25,
+      include_deleted: false,
+      throttle: 0,
+      verify_ssl: true
+    }.freeze
 
-    def defaults
-      {
-        base_uri: "https://core.collectionspace.org/cspace-services",
-        username: "admin@core.collectionspace.org",
-        password: "Administrator",
-        page_size: 50,
-        include_deleted: false,
-        throttle: 0,
-        verify_ssl: true,
-      }
-    end
+    attr_accessor :base_uri, :username, :password, :page_size, :include_deleted, :throttle, :verify_ssl
 
     def initialize(settings = {})
-      settings = defaults.merge(settings)
+      settings = DEFAULTS.merge(settings)
       settings.each do |property, value|
-        next unless defaults.keys.include? property
+        next unless DEFAULTS.key?(property)
+
         instance_variable_set("@#{property}", value)
-        self.class.send(:attr_accessor, property)
       end
     end
-
   end
-
 end

data/lib/collectionspace/client/helpers.rb

@@ -1,122 +1,168 @@
-module CollectionSpace
+# frozen_string_literal: true
 
-  # http://www.garrettqmartin.com/2015/02/03/finding-deeply-nested-hash-keys/
-  module DeepFind
-    def deep_find(obj, key, nested_key = nil)
-      return obj[key] if obj.respond_to?(:key?) && obj.key?(key)
-      if obj.is_a? Enumerable
-        found = nil
-        obj.find { |*a| found = deep_find(a.last, key) }
-        if nested_key
-          deep_find(found, nested_key)
-        else
-          found
-        end
-      end
+module CollectionSpace
+  # Helper methods for client requests
+  module Helpers
+    # add / update batch job
+    def add_batch_job(name, template, data = {}, params = { pgSz: 100 })
+      payload  = Template.process(template, data)
+      response = get('batch', { query: params })
+      create_or_update(response, 'batch', 'name', name, payload)
     end
-  end
 
-  module Helpers
+    # add / update reports
+    def add_report(data = {}, params = { pgSz: 100 })
+      payload  = Template.process('report', data)
+      response = get('reports', { query: params })
+      create_or_update(response, 'reports', 'name', data[:name], payload)
+    end
 
     # get ALL records at path by paging through record set
     def all(path, options = {})
       list_type, list_item = get_list_types(path)
-      Enumerator.new do |yielder|
-        page = 0
-        loop do
-          result = request('GET', path, options.merge(query: { pgNum: page }))
-          raise StopIteration unless result.parsed[list_type].key?('itemsInPage')
+      iterations = (count(path).to_f / config.page_size).ceil
+      return [] unless iterations.positive?
+
+      Enumerator::Lazy.new(0...iterations) do |yielder, i|
+        response = request('GET', path, options.merge(query: { pgNum: i }))
+        raise CollectionSpace::RequestError, response.result.body unless response.result.success?
 
-          items = result.parsed[list_type]['itemsInPage'].to_i
-          raise StopIteration if items == 0
+        items_in_page = response.parsed[list_type].fetch('itemsInPage', 0).to_i
+        list_items = items_in_page.positive? ? response.parsed[list_type][list_item] : []
+        list_items = [list_items] if items_in_page == 1
 
-          list_items = result.parsed[list_type][list_item]
-          list_items = [list_items] if items == 1
-          list_items.each { |item| yielder << item }
-          page += 1
-        end
-      end.lazy
+        yielder << list_items.shift until list_items.empty?
+      end
     end
 
     def count(path)
-      # make sure path is only 1 level deep?
-      count  = nil
-      result = request('GET', path, { query: { pgSz: 1 } })
-      count  = result.parsed['abstract_common_list']['totalItems'].to_i if result.status_code == 200
-      count
-    end
-
-    # create blob record by external url
-    def post_blob_url(url)
-      raise ArgumentError.new("Invalid blob URL #{url}") unless URI.parse(url).scheme =~ /^https?/
-      request 'POST', "blobs", {
-        query: { "blobUri" => url },
-      }
-    end
-
-    def post_relationship(type_a, csid_a, type_b, csid_b)
-      # requires an erb template
-      # request 'POST', "relations", { body: payload }
-      # flip for reciprocal relationship
-      # request 'POST', "relations", { body: payload }
-    end
-
-    def search(query, options = {})
-      options = prepare_query(query, options)
-      request "GET", query.path, options
-    end
-
-    def search_all(query, options = {}, &block)
-      options = prepare_query(query, options)
-      all query.path, options, &block
-    end
-
-    def strip_refname(refname)
-      stripped = refname.match(/('.*')/)[0].delete("'") rescue ''
-      stripped
-    end
-
-    # parsed record and map to get restructured object
-    def to_object(record, attribute_map, stringify_keys = false)
-      attributes = {}
-      attribute_map.each do |map|
-        map = map.inject({}) { |memo,(k,v)| memo[k.to_s] = v; memo} if stringify_keys
-        if map["with"]
-          as = deep_find(record, map["key"], map["nested_key"])
-          values = []
-          if as.is_a? Array
-            values = as.map { |a| strip_refname( deep_find(a, map["with"]) ) }
-          elsif as.is_a? Hash and as[ map["with"] ]
-            values = as[ map["with"] ].is_a?(Array) ? as[ map["with"] ].map { |a| strip_refname(a) } : [ strip_refname(as[ map["with"] ]) ]
-          end
-          attributes[map["field"]] = values
-        else
-          attributes[map["field"]] = deep_find(record, map["key"], map["nested_key"])
-        end
-      end
-      attributes
+      list_type, = get_list_types(path)
+      response   = request('GET', path, query: { pgNum: 0, pgSz: 1 })
+      raise CollectionSpace::RequestError, response.result.body unless response.result.success?
+
+      response.parsed[list_type]['totalItems'].to_i
     end
 
-    private
+    # get the tenant domain from a system required top level authority (person)
+    def domain
+      path = 'personauthorities'
+      response = request('GET', path, query: { pgNum: 0, pgSz: 1 })
+      raise CollectionSpace::RequestError, response.result.body unless response.result.success?
+
+      refname = response.parsed.dig(*get_list_types(path), 'refName')
+      CollectionSpace::RefName.parse(refname)[:domain]
+    end
+
+    # find procedure or object by type and id
+    # find authority/vocab term by type, subtype, and refname
+    # rubocop:disable Metrics/ParameterLists
+    def find(type:, value:, subtype: nil, field: nil, schema: 'common', sort: nil, operator: '=')
+      service = CollectionSpace::Service.get(type: type, subtype: subtype)
+      field ||= service[:term] # this will be set if it is an authority or vocabulary, otherwise nil
+      field ||= service[:identifier]
+      search_args = CollectionSpace::Search.new.from_hash(
+        path: service[:path],
+        namespace: "#{service[:ns_prefix]}_#{schema}",
+        field: field,
+        expression: "#{operator} '#{value.gsub(/'/, '\\\\\'')}'"
+      )
+      search(search_args, sortBy: CollectionSpace::Search::DEFAULT_SORT)
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # @param subject_csid [String] to be searched as `sbj` value
+    # @param object_csid [String] to be searched as `obj` value
+    # @param rel_type [String<'affects', 'hasBroader'>, nil] to be searched as `prd` value
+    def find_relation(subject_csid:, object_csid:, rel_type: nil)
+      if rel_type
+        get('relations', query: { 'sbj' => subject_csid, 'obj' => object_csid, 'prd' => rel_type })
+      else
+        warn(
+          "No rel_type specified, so multiple types of relations between #{subject_csid} and #{object_csid} may be returned",
+          uplevel: 1
+        )
+        get('relations', query: { 'sbj' => subject_csid, 'obj' => object_csid })
+      end
+    end
 
     def get_list_types(path)
-      list_type, list_item = nil
-      if path == 'relations'
-        list_type = 'relations_common_list'
-        list_item = 'relation_list_item'
+      {
+        'accounts' => %w[accounts_common_list account_list_item],
+        'relations' => %w[relations_common_list relation_list_item]
+      }.fetch(path, %w[abstract_common_list list_item])
+    end
+
+    def reindex_full_text(doctype, csids = [])
+      if csids.any?
+        run_job(
+          'Reindex Full Text', :reindex_full_text, :reindex_by_csids, { doctype: doctype, csids: csids }
+        )
       else
-        list_type = 'abstract_common_list'
-        list_item = 'list_item'
+        run_job(
+          'Reindex Full Text', :reindex_full_text, :reindex_by_doctype, { doctype: doctype }
+        )
       end
-      return list_type, list_item
     end
 
-    def prepare_query(query, options = {})
-      query_string = "#{query.type}:#{query.field} #{query.expression}"
-      options      = options.merge({ query: { as: query_string } })
-      options
+    def reset_media_blob(id, url)
+      raise CollectionSpace::ArgumentError, "Not a valid url #{url}" unless URI.parse(url).instance_of? URI::HTTPS
+
+      response = find(type: 'media', value: id, field: 'identificationNumber')
+      raise CollectionSpace::RequestError, response.result.body unless response.result.success?
+
+      found = response.parsed
+      total = found['abstract_common_list']['totalItems'].to_i
+      raise CollectionSpace::NotFoundError, "Media #{id} not found" if total.zero?
+      raise CollectionSpace::DuplicateIdFound, "Found multiple media records for #{id}" unless total == 1
+
+      media_uri = found['abstract_common_list']['list_item']['uri']
+      blob_csid = found['abstract_common_list']['list_item']['blobCsid']
+
+      delete("/blobs/#{blob_csid}") if blob_csid
+
+      payload = Template.process(:reset_media_blob, { id: id })
+      put(media_uri, payload, query: { 'blobUri' => url })
     end
 
-  end
+    def run_job(name, template, invoke_template, data = {})
+      payload = Template.process(invoke_template, data)
+      job     = add_batch_job(name, template)
+      path    = job.parsed['document']['collectionspace_core']['uri']
+      post(path, payload)
+    end
+
+    def search(query, params = {})
+      options = prepare_query(query, params)
+      request 'GET', query.path, options
+    end
+
+    def keyword_search(type:, value:, subtype: nil, sort: nil)
+      service = CollectionSpace::Service.get(type: type, subtype: subtype)
+      options = prepare_keyword_query(value, { sortBy: CollectionSpace::Search::DEFAULT_SORT })
+      request 'GET', service[:path], options
+    end
 
-end
+    def service(type:, subtype: '')
+      CollectionSpace::Service.get(type: type, subtype: subtype)
+    end
+
+    private
+
+    def create_or_update(response, path, property, value, payload)
+      list_type, item_type = get_list_types(path)
+      item = response.find(list_type, item_type, property, value)
+      path = item ? "#{path}/#{item['csid']}" : path
+      item ? put(path, payload) : post(path, payload)
+    end
+
+    def prepare_query(query, params = {})
+      query_string = "#{query.namespace}:#{query.field} #{query.expression}"
+      { query: { as: query_string }.merge(params) }
+    end
+
+    def prepare_keyword_query(query, sort = {})
+      query_string = query.downcase.gsub(' ', '+')
+      { query: { kw: query_string }.merge(sort) }
+    end
+  end
+end

data/lib/collectionspace/client/refname.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require 'strscan'
+
+module CollectionSpace
+  # CollectionSpace RefName
+  #
+  # There are four patterns we need to handle:
+  # 
+  # - urn:cspace:domain:type:name(subtype)'label'                       : Top level authority/vocabulary
+  # - urn:cspace:domain:type:name(subtype):item:name(identifier)'label' : Authority/vocabulary term
+  # - urn:cspace:domain:type:id(identifier)'label'                      : Collectionobject
+  # - urn:cspace:domain:type:id(identifier)                             : Procedures, relations, blobs
+  class RefName
+    attr_reader :domain, :type, :subtype, :identifier, :label
+
+    def initialize(refname)
+      @refname    = refname
+      @domain     = nil
+      @type       = nil
+      @subtype    = nil
+      @identifier = nil
+      @label      = nil
+      parse
+    end
+
+    def parse
+      scanner = StringScanner.new(@refname)
+      scanner.skip('urn:cspace:')
+      @domain = to_next_colon(scanner) 
+      @type = to_next_colon(scanner)
+
+      case next_segment(scanner)
+      when 'name'
+        set_subtype(scanner)
+      when 'id'
+        set_identifier(scanner)
+      end
+
+      self
+    end
+   
+    # Convenience class method, so new instance of RefName does not have to be instantiated in order to parse
+    #
+    # As of v0.13.1, return_class is added and defaults to nil for backward compatibility
+    # Eventually this default will be deprecated, and a parsed RefName object will be returned as the default.
+    #   Any new code written using this method should set the return_class parameter to :refname_obj
+    def self.parse(refname, return_class = nil)
+      return_class == :refname_obj ? new(refname) : new(refname).to_h
+    end
+
+    # Returns a parsed RefName object as a hash.
+    # As of v0.13.1, this is equivalent to calling RefName.parse('refnamevalue', :hash)
+    # This was added to simplify the process of updating existing code that expects a hash when calling RefName.parse
+    def to_h
+      {
+        domain: domain,
+        type: type,
+        subtype: subtype,
+        identifier: identifier,
+        label: label
+      }
+    end
+
+    private
+
+    def next_segment(scanner)
+      segment = scanner.check_until(/\(/)
+      return nil unless segment
+      
+      segment.delete_suffix('(')
+    end
+
+    def set_identifier(scanner)
+      scanner.skip('id(')
+      @identifier = to_end_paren(scanner)
+      return if scanner.eos?
+
+      set_label(scanner)
+    end
+
+    def set_label(scanner)
+      scanner.skip("'")
+      @label = scanner.rest.delete_suffix("'")
+    end
+
+    def set_subtype(scanner)
+      scanner.skip('name(')
+      @subtype = to_end_paren(scanner)
+
+      case next_segment(scanner)
+      when nil
+        set_label(scanner)
+      when ':item:name'
+        set_term_identifier(scanner)
+      end
+    end
+
+    def set_term_identifier(scanner)
+      scanner.skip(':item:name(')
+      @identifier = to_end_paren(scanner)
+      scanner.skip("'")
+      set_label(scanner)
+    end
+    
+    def to_end_paren(scanner)
+      scanner.scan_until(/\)/).delete_suffix(')')
+    end
+
+    def to_next_colon(scanner)
+      scanner.scan_until(/:/).delete_suffix(':')
+    end
+  end
+end

data/lib/collectionspace/client/request.rb

@@ -1,5 +1,7 @@
-module CollectionSpace
+# frozen_string_literal: true
 
+module CollectionSpace
+  # CollectionSpace request
   class Request
     include HTTParty
     attr_reader :config, :headers, :method, :path, :options
@@ -9,41 +11,43 @@ module CollectionSpace
         delete: {},
         get: {},
         post: {
-          "Content-Type" => "application/xml",
-          "Content-Length" => "nnnn",
+          'Content-Type' => 'application/xml',
+          'Content-Length' => 'nnnn'
         },
         put: {
-          "Content-Type" => "application/xml",
-          "Content-Length" => "nnnn",
+          'Content-Type' => 'application/xml',
+          'Content-Length' => 'nnnn'
         }
       }
       headers[method]
     end
 
-    def initialize(config, method = "GET", path = "", options = {})
+    def initialize(config, method = 'GET', path = '', options = {})
       @config = config
       @method = method.downcase.to_sym
-      @path   = path.gsub(/^\//, '')
+      @path   = path.gsub(%r{^/}, '')
 
       @auth = {
         username: config.username,
-        password: config.password,
+        password: config.password
       }
 
+      headers = default_headers(@method).merge(options.fetch(:headers, {}))
       @options = options
       @options[:basic_auth] = @auth
-      @options[:headers]    = options[:headers] ? default_headers(@method).merge(options[:headers]) : default_headers(@method)
+      @options[:headers]    = headers
       @options[:verify]     = config.verify_ssl
-      @options[:query]      = {} unless options.has_key? :query
+      @options[:query]      = options.fetch(:query, {})
 
       self.class.base_uri config.base_uri
-      self.class.default_params wf_deleted: config.include_deleted, pgSz: config.page_size
+      self.class.default_params(
+        wf_deleted: config.include_deleted,
+        pgSz: config.page_size
+      )
     end
 
     def execute
       self.class.send method, "/#{path}", options
     end
-
   end
-
 end