mais_person_client 0.0.1

data/README.md

@@ -0,0 +1,82 @@
+[![Gem Version](https://badge.fury.io/rb/mais_person_client.svg)](https://badge.fury.io/rb/mais_person_client)
+[![CircleCI](https://circleci.com/gh/sul-dlss/mais_person_client.svg?style=svg)](https://circleci.com/gh/sul-dlss/mais_person_client)
+[![codecov](https://codecov.io/github/sul-dlss/mais_person_client/graph/badge.svg?token=A6B03FJ981)](https://codecov.io/github/sul-dlss/mais_person_client)
+
+# mais_person_client
+API client for accessing MAIS's Person endpoints.
+
+MAIS's Person API provides access to information for Stanford users.
+
+## API Documentation
+
+API docs: https://uit.stanford.edu/developers/apis/person
+API Schema: https://uit.stanford.edu/service/registry/person-data
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add mais_peron_client
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install mais_person_client
+
+## Usage
+
+For one-off requests:
+
+```ruby
+require "mais_person_client"
+
+# NOTE: The settings below live in the consumer, not in the gem.
+# The user_agent string can be changed by consumers as requested by MaIS for tracking
+client = MaisPersonClient.configure(
+  api_key: Settings.mais_person.api_key,
+  api_cert: Settings.mais_person.api_cert,
+  base_url: Settings.mais_person.base_url,
+  user_agent: 'some-user-agent-string-to-send-in-requests' # defaults to 'stanford-library'
+)
+client.fetch_user('nataliex') # get a single user by sunet
+client.fetch_users # return all users
+```
+
+You can also invoke methods directly on the client class, which is useful in a Rails application environment where you might initialize the client in an
+initializer and then invoke client methods in many other contexts where you want to be sure configuration has already occurred, e.g.:
+
+```ruby
+# config/initializers/mais_person_client.rb
+MaisPersonClient.configure(
+  api_key: Settings.mais_person.api_key,
+  api_cert: Settings.mais_person.api_cert,
+  base_url: Settings.mais_person.base_url,
+)
+
+# app/services/my_mais_person_service.rb
+# ...
+def get_user(sunet)
+  MaisPersonClient.fetch_user(sunet)
+end
+# ...
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## VCR Cassettes
+
+VCR gem is used to record the results of the API calls for the tests.  If you need to record or re-create existing cassettes, you may need to adjust expectations in the tests as the results coming back from the API may be different than when the cassettes were recorded.
+
+To record new cassettes:
+1. Join VPN.
+2. Temporarily adjust the configuration (api_key, api_cert for the MaIS UAT URL) at the top of `spec/mais_person_client_spec.rb` so it matches the real MaIS UAT environment.
+3. Add your new spec with a new cassette name (or delete a previous cassette to re-create it).
+4. Run just that new spec (important: else previous specs may use cassettes that have redacted credentials, causing your new spec to fail).
+5. You should get a new cassette with the name you specified in the spec.
+6. Look at the cassette.  If it has real person data, you will want to redact most of it since there will be private information in there.  Make the expectation match the redaction.
+7. Set your configuration at the top of the spec back to the fake api_key and api_cert values.
+8. The spec that checks for a raised exception when fetching all users may need to be handcrafted in the cassette to look it raised a 500.  It's hard to get the actual URL to produce a 500 on this call.
+9. Re-run all the specs - they should pass now without making real calls.

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[rubocop spec]

data/lib/mais_person_client/person.rb

@@ -0,0 +1,376 @@
+# frozen_string_literal: true
+
+class MaisPersonClient
+  # Model for a Person from the MAIS Person API
+  class Person
+    HOME_ADDRESS_TYPES = %w[home permanent].freeze
+
+    # Struct definitions for complex nodes
+    PersonName = Struct.new(:type, :visibility, :full_name, :first_name, :first_nval, :middle, :middle_nval,
+                            :last, :last_nval)
+    Address = Struct.new(:type, :visibility, :full_address, :line, :city, :state, :state_code, :postal_code, :country,
+                         :country_alpha2, :country_alpha3, :country_numeric, :affnum)
+    Telephone = Struct.new(:type, :visibility, :full_number, :icc, :area, :number, :affnum)
+    Email = Struct.new(:type, :visibility, :full_email, :user, :host)
+    Url = Struct.new(:type, :visibility, :url)
+    Location = Struct.new(:code, :type, :visibility, :location)
+    Identifier = Struct.new(:type, :visibility, :nval, :value)
+    Department = Struct.new(:affnum, :name, :organization, :adminid, :level2orgid, :level2orgname, :regid)
+    Affiliation = Struct.new(:affnum, :effective, :organization, :type, :visibility, :name, :department, :description,
+                             :affdata, :place)
+    AffData = Struct.new(:affnum, :type, :code, :value)
+    Place = Struct.new(:type, :affnum, :address, :qbfr, :telephone)
+    EmergencyContact = Struct.new(:number, :primary, :sync_permanent, :visibility, :contact_name,
+                                  :contact_relationship, :contact_relationship_code, :contact_telephones,
+                                  :contact_address)
+
+    attr_reader :xml
+
+    def initialize(xml)
+      @xml = Nokogiri::XML(xml)
+      @xml.remove_namespaces!
+    end
+
+    # Root attributes
+    def card
+      xml.root['card']
+    end
+
+    def listing
+      xml.root['listing']
+    end
+
+    def name_attr
+      xml.root['name']
+    end
+
+    def regid
+      xml.root['regid']
+    end
+
+    def relationship
+      xml.root['relationship']
+    end
+
+    def source
+      xml.root['source']
+    end
+
+    def sunetid
+      xml.root['sunetid']
+    end
+
+    def univid
+      xml.root['univid']
+    end
+
+    # Names (multiple possible)
+    def names
+      xml.xpath('//name').map { |name_node| build_person_name(name_node) }
+    end
+
+    def registered_name
+      names.find { |name| name.type == 'registered' }
+    end
+
+    def display_name
+      names.find { |name| name.type == 'display' }
+    end
+
+    # Titles (multiple possible)
+    def titles
+      xml.xpath('//title').map do |title_node|
+        {
+          type: title_node['type'],
+          visibility: title_node['visibility'],
+          title: title_node.text
+        }
+      end
+    end
+
+    def job_title
+      titles.find { |title| title[:type] == 'job' }&.[](:title)
+    end
+
+    # Biodemo
+    def gender
+      xml.at_xpath('//biodemo/gender')&.text
+    end
+
+    def biodemo_visibility
+      xml.at_xpath('//biodemo')&.[]('visibility')
+    end
+
+    # Addresses (multiple possible)
+    def addresses
+      xml.xpath('//address').map { |addr_node| build_address(addr_node) }
+    end
+
+    # Telephones (multiple possible)
+    def telephones
+      xml.xpath('//telephone').map { |tel_node| build_telephone(tel_node) }
+    end
+
+    # Emails (multiple possible)
+    def emails
+      xml.xpath('//email').map do |email_node|
+        Email.new(
+          email_node['type'],
+          email_node['visibility'],
+          email_node.children.first&.text&.strip,
+          email_node.at_xpath('user')&.text,
+          email_node.at_xpath('host')&.text
+        )
+      end
+    end
+
+    def primary_email
+      emails.find { |email| email.type == 'primary' }&.full_email
+    end
+
+    # URLs (multiple possible)
+    def urls
+      xml.xpath('//url').map do |url_node|
+        Url.new(
+          url_node['type'],
+          url_node['visibility'],
+          url_node.text
+        )
+      end
+    end
+
+    def homepage
+      urls.find { |url| url.type == 'homepage' }&.url
+    end
+
+    # Locations (multiple possible)
+    def locations
+      xml.xpath('//location').map do |loc_node|
+        Location.new(
+          loc_node['code'],
+          loc_node['type'],
+          loc_node['visibility'],
+          loc_node.text
+        )
+      end
+    end
+
+    # Places (multiple possible - home, work, etc.)
+    def places
+      xml.xpath('//place').map { |place_node| build_place(place_node) }
+    end
+
+    # Affiliations (multiple possible)
+    def affiliations
+      xml.xpath('//affiliation').map { |aff_node| build_affiliation(aff_node) }
+    end
+
+    # Identifiers (multiple)
+    def identifiers
+      xml.xpath('//identifier').map do |id_node|
+        Identifier.new(
+          id_node['type'],
+          id_node['visibility'],
+          id_node['nval'],
+          id_node.text
+        )
+      end
+    end
+
+    def identifier_by_type(type)
+      identifiers.find { |id| id.type == type }&.value
+    end
+
+    # Privacy groups
+    def privgroups
+      xml.xpath('//privgroup').map(&:text)
+    end
+
+    # eduPerson attributes
+    def eduperson_primary_affiliation
+      xml.at_xpath('//edupersonprimaryaffiliation')&.text
+    end
+
+    def eduperson_affiliations
+      xml.xpath('//edupersonaffiliation').map(&:text)
+    end
+
+    # Emergency contacts
+    def emergency_contacts
+      xml.xpath('//emergency_contact').map { |contact_node| build_emergency_contact(contact_node) }
+    end
+
+    # Convenience methods for common lookups
+    def work_address
+      addresses.find { |addr| addr.type == 'work' }
+    end
+
+    def home_address
+      addresses.find { |addr| HOME_ADDRESS_TYPES.include?(addr.type) }
+    end
+
+    def work_phone
+      telephones.find { |tel| tel.type == 'work' }
+    end
+
+    def mobile_phone
+      telephones.find { |tel| tel.type == 'mobile' }
+    end
+
+    def orcid
+      identifier_by_type('orcid')
+    end
+
+    def directory_id
+      identifier_by_type('directory')
+    end
+
+    private
+
+    def build_person_name(name_node)
+      PersonName.new(
+        name_node['type'],
+        name_node['visibility'],
+        name_node.children.first&.text&.strip,
+        name_node.at_xpath('first')&.text,
+        name_node.at_xpath('first')&.[]('nval'),
+        name_node.at_xpath('middle')&.text,
+        name_node.at_xpath('middle')&.[]('nval'),
+        name_node.at_xpath('last')&.text,
+        name_node.at_xpath('last')&.[]('nval')
+      )
+    end
+
+    def build_address(addr_node)
+      lines = addr_node.xpath('line').map(&:text)
+      Address.new(
+        addr_node['type'],
+        addr_node['visibility'],
+        addr_node.children.first&.text&.strip,
+        lines.length == 1 ? lines.first : lines,
+        addr_node.at_xpath('city')&.text,
+        addr_node.at_xpath('state')&.text,
+        addr_node.at_xpath('state')&.[]('code'),
+        addr_node.at_xpath('postalcode')&.text,
+        addr_node.at_xpath('country')&.text,
+        addr_node.at_xpath('country')&.[]('alpha2'),
+        addr_node.at_xpath('country')&.[]('alpha3'),
+        addr_node.at_xpath('country')&.[]('numeric'),
+        addr_node['affnum']
+      )
+    end
+
+    def build_telephone(tel_node)
+      Telephone.new(
+        tel_node['type'],
+        tel_node['visibility'],
+        tel_node.children.first&.text&.strip,
+        tel_node.at_xpath('icc')&.text,
+        tel_node.at_xpath('area')&.text,
+        tel_node.at_xpath('number')&.text,
+        tel_node['affnum']
+      )
+    end
+
+    def build_department(dept_node)
+      return nil unless dept_node
+
+      org_node = dept_node.at_xpath('organization')
+      Department.new(
+        dept_node['affnum'],
+        dept_node.children.first&.text&.strip,
+        org_node&.text,
+        org_node&.[]('adminid'),
+        org_node&.[]('level2orgid'),
+        org_node&.[]('level2orgname'),
+        org_node&.[]('regid')
+      )
+    end
+
+    def build_affdata_array(aff_node)
+      aff_node.xpath('affdata').map do |data_node|
+        AffData.new(
+          data_node['affnum'],
+          data_node['type'],
+          data_node['code'],
+          data_node.text
+        )
+      end
+    end
+
+    def build_places_for_affiliation(aff_node)
+      aff_node.xpath('place').map { |place_node| build_place(place_node) }
+    end
+
+    def build_place(place_node)
+      place_addresses = place_node.xpath('address').map { |addr_node| build_address(addr_node) }
+      place_telephones = place_node.xpath('telephone').map { |tel_node| build_telephone(tel_node) }
+
+      Place.new(
+        place_node['type'],
+        place_node['affnum'],
+        place_addresses,
+        place_node.at_xpath('qbfr')&.text,
+        place_telephones
+      )
+    end
+
+    def build_emergency_contact_telephones(contact_node)
+      contact_node.xpath('contact_telephone').map do |tel_node|
+        Telephone.new(
+          tel_node['type'],
+          tel_node['visibility'],
+          tel_node.children.first&.text&.strip,
+          tel_node.at_xpath('icc')&.text,
+          tel_node.at_xpath('area')&.text,
+          tel_node.at_xpath('number')&.text,
+          nil
+        )
+      end
+    end
+
+    def build_emergency_contact_address(contact_node)
+      addr_node = contact_node.at_xpath('contact_address')
+      return nil unless addr_node
+
+      build_address(addr_node)
+    end
+
+    def build_affiliation(aff_node)
+      department = build_department(aff_node.at_xpath('department'))
+      affdata = build_affdata_array(aff_node)
+      aff_places = build_places_for_affiliation(aff_node)
+
+      Affiliation.new(
+        aff_node['affnum'],
+        aff_node['effective'],
+        aff_node['organization'],
+        aff_node['type'],
+        aff_node['visibility'],
+        aff_node.children.first&.text&.strip,
+        department,
+        aff_node.at_xpath('description')&.text,
+        affdata,
+        aff_places
+      )
+    end
+
+    def build_emergency_contact(contact_node)
+      contact_telephones = build_emergency_contact_telephones(contact_node)
+      contact_address = build_emergency_contact_address(contact_node)
+      rel_node = contact_node.at_xpath('contact_relationship')
+
+      EmergencyContact.new(
+        contact_node['number'],
+        contact_node['primary'] == 'true',
+        contact_node['sync_permanent'] == 'true',
+        contact_node['visibility'],
+        contact_node.at_xpath('contact_name')&.text,
+        rel_node&.text,
+        rel_node&.[]('code'),
+        contact_telephones,
+        contact_address
+      )
+    end
+  end
+end

data/lib/mais_person_client/unexpected_response.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class MaisPersonClient
+  # Handles unexpected responses when communicating with Mais
+  class UnexpectedResponse
+    # Error raised when the Mais API returns a 401 Unauthorized
+    class UnauthorizedError < StandardError; end
+
+    # Error raised when the Mais API returns a 500 error
+    class ServerError < StandardError; end
+
+    # Error raised when the Mais API returns a response with an error message in it
+    class ResponseError < StandardError; end
+
+    def self.call(response)
+      case response.status
+      when 401
+        raise UnauthorizedError, "There was a problem with authentication: #{response.body}"
+      when 500
+        raise ServerError, "Mais server error: #{response.body}"
+      else
+        raise StandardError, "Unexpected response: #{response.status} #{response.body}"
+      end
+    end
+  end
+end

data/lib/mais_person_client/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class MaisPersonClient
+  VERSION = '0.0.1'
+end

data/lib/mais_person_client.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/module/delegation'
+
+require 'faraday'
+require 'faraday/retry'
+require 'openssl'
+require 'ostruct'
+require 'nokogiri'
+require 'singleton'
+require 'zeitwerk'
+
+# Load the gem's internal dependencies: use Zeitwerk instead of needing to manually require classes
+Zeitwerk::Loader.for_gem.setup
+
+# Client for interacting with MAIS's Person API
+class MaisPersonClient
+  include Singleton
+
+  class << self
+    # @param api_key [String] the api_key provided by MAIS
+    # @param api_cert [String] the api_cert provided by MAIS
+    # @param base_url [String] the base URL for the API
+    # @param user_agent [String] the user agent to use for requests (default: 'stanford-library')
+    def configure(api_key:, api_cert:, base_url:, user_agent: 'stanford-library')
+      # rubocop:disable Style/OpenStructUse
+      instance.config = OpenStruct.new(
+        api_key:,
+        api_cert:,
+        base_url:,
+        user_agent:
+      )
+      # rubocop:enable Style/OpenStructUse
+
+      self
+    end
+
+    delegate :config, :fetch_user, to: :instance
+  end
+
+  attr_accessor :config
+
+  # Fetch a user details
+  # @param [string] sunet to fetch
+  # @return [<Person>, nil] user or nil if not found
+  def fetch_user(sunetid)
+    get_response("/doc/person/#{sunetid}", allow404: true)
+  end
+
+  private
+
+  def get_response(path, allow404: false)
+    response = conn.get(path)
+
+    return if allow404 && response.status == 404
+
+    return UnexpectedResponse.call(response) unless response.success?
+
+    response.body
+  end
+
+  def conn
+    conn = Faraday.new(url: config.base_url) do |faraday|
+      configure_faraday(faraday)
+    end
+    conn.options.timeout = 500
+    conn.options.open_timeout = 10
+    conn.headers[:user_agent] = config.user_agent
+    conn
+  end
+
+  def configure_faraday(faraday)
+    faraday.request :retry, max: 3,
+                            interval: 0.5,
+                            interval_randomness: 0.5,
+                            backoff_factor: 2
+
+    # Configure SSL for client certificate authentication (unless we are using bogus fake values in spec)
+    return if config.api_key.include?('fakekey')
+
+    cert = OpenSSL::X509::Certificate.new(config.api_cert)
+    key = OpenSSL::PKey::RSA.new(config.api_key)
+    faraday.ssl.client_cert = cert
+    faraday.ssl.client_key = key
+  end
+end

data/mais_person_client.gemspec

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'mais_person_client/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'mais_person_client'
+  spec.version = MaisPersonClient::VERSION
+  spec.authors = ['Peter Mangiafico']
+  spec.email = ['pmangiafico@stanford.edu']
+
+  spec.summary = "Interface for interacting with the MAIS's Person API."
+  spec.description = "This provides API interaction with the MAIS's Person API"
+  spec.homepage = 'https://github.com/sul-dlss/mais_person_client'
+  spec.required_ruby_version = '>= 3.2.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/sul-dlss/mais_person_client'
+  spec.metadata['changelog_uri'] = 'https://github.com/sul-dlss/mais_person_client/releases'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'activesupport', '>= 4.2'
+  spec.add_dependency 'faraday'
+  spec.add_dependency 'faraday-retry'
+  spec.add_dependency 'nokogiri'
+  spec.add_dependency 'ostruct'
+  spec.add_dependency 'zeitwerk'
+
+  spec.add_development_dependency 'byebug'
+  spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'reline'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'rubocop-capybara'
+  spec.add_development_dependency 'rubocop-factory_bot'
+  spec.add_development_dependency 'rubocop-performance'
+  spec.add_development_dependency 'rubocop-rspec'
+  spec.add_development_dependency 'rubocop-rspec_rails'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'vcr'
+  spec.add_development_dependency 'webmock'
+end