usps-imis-api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: af49f754c17bf49128b5e71d515f75066ab62cd56573a846b3fb50fa951324ef
+  data.tar.gz: b0df9cc67032d9d40a474fe119deb0c70d0374358425ef6817d91398698cfd92
+SHA512:
+  metadata.gz: 8a26ceb0adc52557754fce7207a32f5e26eeb445c98f328d04d99dfb8c478daa47a124f5cae59d22661c302d33242ad67883d7fc0e4ae77ee77ee55dc5473177
+  data.tar.gz: da23f2bd903cf74d4b74e4d2b4324557662366e37cdb5acc299dc208231e64ed4c8f477649b2e2a53db2db03b9d51b4fa692507b49abfce5ea18f1156c7ca436

data/.gitignore

@@ -0,0 +1,3 @@
+coverage/
+tmp/
+.env

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--order rand

data/.rubocop.yml

@@ -0,0 +1,85 @@
+require:
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.0
+  Exclude:
+    - bin/**/*
+    - config/**/*
+    - db/**/*
+    - vendor/**/*
+    - tmp/**/*
+  NewCops: enable
+
+Layout/FirstHashElementIndentation:
+  EnforcedStyle: consistent
+Layout/AccessModifierIndentation:
+  EnforcedStyle: outdent
+Layout/EmptyLinesAroundAccessModifier:
+  Enabled: true
+Layout/ArrayAlignment:
+  Enabled: true
+Layout/HashAlignment:
+  Enabled: true
+Layout/EmptyLineAfterGuardClause:
+  Enabled: true
+Layout/SpaceInsideBlockBraces:
+  EnforcedStyle: space
+  EnforcedStyleForEmptyBraces: no_space
+Layout/SpaceInsideHashLiteralBraces:
+  EnforcedStyle: space
+  EnforcedStyleForEmptyBraces: no_space
+Layout/SpaceInsideArrayLiteralBrackets:
+  EnforcedStyle: no_space
+
+Lint/UnusedMethodArgument:
+  Enabled: true
+Lint/UselessAssignment:
+  Enabled: true
+
+Metrics/LineLength:
+  Max: 100
+Metrics/MethodLength:
+  Enabled: true
+  Max: 15
+Metrics/ClassLength:
+  Enabled: true
+  Max: 125
+Metrics/ModuleLength:
+  Max: 125
+Metrics/ParameterLists:
+  Enabled: true
+Metrics/CyclomaticComplexity:
+  Enabled: true
+Metrics/AbcSize:
+  Enabled: true
+  Max: 30
+
+Naming/MemoizedInstanceVariableName:
+  Enabled: false
+Naming/MethodParameterName:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+Style/FrozenStringLiteralComment:
+  Enabled: true
+Style/NumericLiterals:
+  Enabled: true
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+Style/AndOr:
+  Enabled: true
+Style/ClassCheck:
+  Enabled: true
+Style/GuardClause:
+  Enabled: true
+Style/OptionalBooleanParameter:
+  Enabled: false
+
+Security/Eval:
+  Enabled: true
+Security/JSONLoad:
+  Enabled: true
+Security/YAMLLoad:
+  Enabled: true

data/.ruby-version

@@ -0,0 +1 @@
+3.2.3

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec
+
+gem 'dotenv',        '>= 3.1.4'
+gem 'rspec',         '>= 3.13.0'
+gem 'rubocop',       '>= 1.66.1'
+gem 'rubocop-rspec', '>= 3.1.0'
+gem 'simplecov',     '>= 0.22.0'

data/Gemfile.lock

@@ -0,0 +1,71 @@
+PATH
+  remote: .
+  specs:
+    usps-imis-api (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    diff-lcs (1.5.1)
+    docile (1.4.1)
+    dotenv (3.1.4)
+    json (2.7.2)
+    language_server-protocol (3.17.0.3)
+    parallel (1.26.3)
+    parser (3.3.5.0)
+      ast (~> 2.4.1)
+      racc
+    racc (1.8.1)
+    rainbow (3.1.1)
+    regexp_parser (2.9.2)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.1)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.1)
+    rubocop (1.66.1)
+      json (~> 2.3)
+      language_server-protocol (>= 3.17.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.4, < 3.0)
+      rubocop-ast (>= 1.32.2, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.32.3)
+      parser (>= 3.3.1.0)
+    rubocop-rspec (3.1.0)
+      rubocop (~> 1.61)
+    ruby-progressbar (1.13.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.1)
+    simplecov_json_formatter (0.1.4)
+    unicode-display_width (2.6.0)
+
+PLATFORMS
+  arm64-darwin-23
+  ruby
+
+DEPENDENCIES
+  dotenv (>= 3.1.4)
+  rspec (>= 3.13.0)
+  rubocop (>= 1.66.1)
+  rubocop-rspec (>= 3.1.0)
+  simplecov (>= 0.22.0)
+  usps-imis-api!
+
+BUNDLED WITH
+   2.5.6

data/lib/ext/hash.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Import a simplified version of to_query from Rails if not already defined
+class Hash
+  def to_query
+    map do |key, value|
+      "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"
+    end.sort * '&'
+  end
+end

data/lib/imis/api.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Imis
+  class Api
+    AUTHENTICATION_PATH = 'Token'
+    API_PATH = 'api'
+    QUERY_PATH = 'api/Query'
+
+    attr_reader :token, :token_expiration, :imis_id
+
+    def initialize(skip_authentication: false)
+      authenticate unless skip_authentication
+    end
+
+    # Manually set the current ID, if you already have it for a given member
+    #
+    def imis_id=(id)
+      @imis_id = id.to_s
+    end
+
+    # Convert a member's certificate number into an iMIS ID number
+    #
+    def imis_id_for(certificate)
+      result = query(Imis.configuration.imis_id_query_name, { certificate: certificate })
+      @imis_id = result['Items']['$values'][0]['ID']
+    end
+
+    # Get a business object for the current member
+    #
+    def get(business_object_name)
+      uri = uri_for(business_object_name)
+      request = Net::HTTP::Get.new(uri)
+      result = submit(uri, authorize(request))
+      JSON.parse(result.body)
+    end
+
+    # Update only specific fields on a business object for the current member
+    #
+    #   fields - hash of shape: { field_name => new_value }
+    #
+    def put(business_object_name, fields)
+      uri = uri_for(business_object_name)
+      request = Net::HTTP::Put.new(uri)
+      updated = filter_fields(business_object_name, fields)
+      request.body = JSON.dump(updated)
+      result = submit(uri, authorize(request))
+      JSON.parse(result.body)
+    end
+
+    # Run an IQA Query
+    #
+    #   query_name   - the full path of the query in IQA, e.g. `$/_ABC/Fiander/iMIS_ID`
+    #   query_params - hash of shape: { param_name => param_value }
+    #
+    def query(query_name, query_params = {})
+      query_params[:QueryName] = query_name
+      path = "#{QUERY_PATH}?#{query_params.to_query}"
+      uri = URI(File.join(imis_hostname, path))
+      request = Net::HTTP::Get.new(uri)
+      result = submit(uri, authorize(request))
+      JSON.parse(result.body)
+    end
+
+    def mapper
+      @mapper ||= Mapper.new(self)
+    end
+
+  private
+
+    def client(uri)
+      Net::HTTP.new(uri.host, uri.port).tap do |http|
+        http.use_ssl = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+      end
+    end
+
+    def imis_hostname
+      Imis.configuration.hostname
+    end
+
+    # Authorize a request prior to submitting
+    #
+    # If the current token is missing/expired, request a new one
+    #
+    def authorize(request)
+      authenticate if token_expiration < Time.now
+      request.tap { |r| r.add_field('Authorization', "Bearer #{token}") }
+    end
+
+    # Construct a business object API endpoint address
+    #
+    def uri_for(business_object_name)
+      URI(File.join(imis_hostname, "#{API_PATH}/#{business_object_name}/#{imis_id}"))
+    end
+
+    def submit(uri, request)
+      client(uri).request(request).tap do |result|
+        raise Error::Api.from(result) unless result.is_a?(Net::HTTPSuccess)
+      end
+    end
+
+    # Authenticate to the iMIS API, and store the access token and expiration time
+    #
+    def authenticate
+      uri = URI(File.join(imis_hostname, AUTHENTICATION_PATH))
+      req = Net::HTTP::Post.new(uri)
+      authentication_data = {
+        grant_type: 'password',
+        username: Imis.configuration.username,
+        password: Imis.configuration.password
+      }
+      req.body = URI.encode_www_form(authentication_data)
+      result = submit(uri, req)
+      json = JSON.parse(result.body)
+
+      @token = json['access_token']
+      @token_expiration = Time.parse(json['.expires'])
+    end
+
+    # Manually assemble the matching data structure, with fields in the correct order
+    #
+    def filter_fields(business_object_name, fields)
+      existing = get(business_object_name)
+
+      JSON.parse(JSON.dump(existing)).tap do |updated|
+        # The first property is always the iMIS ID again
+        updated['Properties']['$values'] = [existing['Properties']['$values'][0]]
+
+        # Iterate through all existing fields
+        existing['Properties']['$values'].each do |value|
+          next unless fields.keys.include?(value['Name'])
+
+          # Strings are not wrapped in the type definition structure
+          new_value = fields[value['Name']]
+          if new_value.is_a?(String)
+            value['Value'] = new_value
+          else
+            value['Value']['$value'] = new_value
+          end
+
+          # Add the completed field with the updated value
+          updated['Properties']['$values'] << value
+        end
+      end
+    end
+  end
+end

data/lib/imis/config.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Imis
+  class Config
+    IMIS_ROOT_URL_PROD = 'https://portal.americasboatingclub.org'
+    IMIS_ROOT_URL_DEV = 'https://abcdev.imiscloud.com'
+
+    attr_accessor :environment, :imis_id_query_name, :username, :password
+
+    def initialize
+      yield self if block_given?
+    end
+
+    def hostname
+      case environment.to_sym
+      when :production
+        IMIS_ROOT_URL_PROD
+      when :development
+        IMIS_ROOT_URL_DEV
+      else
+        raise "Unexpected API environment: #{environment}"
+      end
+    end
+  end
+end

data/lib/imis/error/api.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Imis
+  module Error
+    class Api < StandardError
+      attr_reader :response
+      attr_accessor :metadata
+
+      def self.from(response)
+        new('The iMIS API returned an error.', response)
+      end
+
+      def initialize(message, response, metadata = {})
+        super(message)
+        @metadata = metadata
+        @response = response
+      end
+
+      def bugsnag_meta_data
+        { api: { status: status, body: body }.merge!(metadata) }
+      end
+
+    private
+
+      def status
+        @status ||=
+          case response.code
+          when '400'
+            :bad_request
+          when '401'
+            :unauthorized # RequestVerificationToken invalid
+          when '404'
+            :not_found
+          when '422'
+            :unprocessable_entity # validation error
+          when /^50\d$/
+            :internal_server_error # error within iMIS
+          end
+      end
+
+      def response_body
+        @response_body ||= JSON.parse(response.body)
+      rescue StandardError
+        @response_body ||= response.body
+      end
+
+      def body
+        return response_body unless response_body.is_a?(Hash)
+
+        case response_body['error']
+        when 'invalid_grant'
+          response_body['error_description']
+        else
+          # Unknown error type: just use the raw response
+          response.body
+        end
+      end
+    end
+  end
+end

data/lib/imis/error/mapper.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Imis
+  module Error
+    class Mapper < StandardError; end
+  end
+end

data/lib/imis/mapper.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Imis
+  class Mapper
+    FIELD_MAPPING = {
+      vessel_examiner: ['ABC_ASC_Individual_Demog', 'Vol_Vessel_Examiner'],
+      mm: ['ABC_ASC_Individual_Demog', 'TotMMS'],
+      mm_updated: ['ABC_ASC_Individual_Demog', 'MMS_Updated']
+    }.freeze
+
+    attr_reader :api
+
+    def initialize(api)
+      @api = api
+    end
+
+    # Update a member's data by a single field name
+    # Does not require knowing which business object / iMIS-specific field name to use
+    #
+    # Only available for previously-mapped fields
+    #
+    def update(field_name, value)
+      if FIELD_MAPPING.key?(field_name.to_sym)
+        business_object_name, field = FIELD_MAPPING[field_name.to_sym]
+        api.put(business_object_name, { field => value })
+      else
+        warn(
+          "Mapper does not know how to handle field \"#{field_name}\".\n\n" \
+          'You can use api.put(business_object_name, { field_name => value })  ' \
+          "if you know the business object and iMIS-specific field name.\n\n"
+        ) unless ENV['TESTING']
+
+        raise(
+          Imis::Error::Mapper,
+          "Unrecognized field: \"#{field_name}\". " \
+          'Please report what data you are attempting to work with to ITCom leadership.'
+        )
+      end
+    end
+  end
+end

data/lib/usps_imis_api.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Core dependencies
+require 'net/https'
+require 'json'
+require 'time'
+require 'cgi'
+
+# Extensions
+require 'ext/hash' unless defined?(Rails)
+
+# Internal requires
+require 'imis/config'
+require 'imis/error/api'
+require 'imis/error/mapper'
+require 'imis/api'
+require 'imis/mapper'
+
+module Imis
+  class << self
+    def configuration
+      @configuration ||= Imis::Config.new
+    end
+
+    def configure
+      yield(configuration) if block_given?
+      configuration
+    end
+
+    # def mock!(value = true)
+    #   @mock = value
+    # end
+
+    # def mock
+    #   @mock || false
+    # end
+  end
+end

data/spec/api_spec.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Imis::Api do
+  let(:api) { described_class.new }
+
+  describe '#imis_id_for' do
+    it 'gets the iMIS ID' do
+      expect(api.imis_id_for('E231625')).to eq('31092')
+    end
+  end
+
+  describe '#put' do
+    before { api.imis_id = 31092 }
+
+    it 'sends an update' do
+      expect(api.put('ABC_ASC_Individual_Demog', { 'TotMMS' => 15 })).to be_a(Hash)
+    end
+  end
+end

data/spec/mapper_spec.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Imis::Mapper do
+  let(:api) { Imis::Api.new }
+
+  describe '#update' do
+    before { api.imis_id = 31092 }
+
+    it 'sends a mapped update' do
+      expect(api.mapper.update(:mm, 15)).to be_a(Hash)
+    end
+
+    it 'raises for unmapped updates' do
+      expect { api.mapper.update(:something, 'anything') }.to raise_error(
+        Imis::Error::Mapper,
+        'Unrecognized field: "something". ' \
+        'Please report what data you are attempting to work with to ITCom leadership.'
+      )
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+Bundler.setup
+require 'simplecov'
+SimpleCov.start do
+  add_filter '/spec'
+end
+# SimpleCov.minimum_coverage(100)
+
+require 'dotenv/load'
+require 'usps_imis_api'
+
+ENV['TESTING'] = 'true'
+
+RSpec.configure do |config|
+  config.before(:suite) do
+    Imis.configure do |imis_config|
+      imis_config.environment = :development
+      imis_config.imis_id_query_name = ENV.fetch('IMIS_ID_QUERY_NAME', '')
+
+      imis_config.username = ENV.fetch('IMIS_USERNAME', '')
+      imis_config.password = ENV.fetch('IMIS_PASSWORD', '')
+    end
+  end
+end

data/usps-imis-api.gemspec

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |s|
+  s.name          = 'usps-imis-api'
+  s.version       = '0.1.0'
+  s.summary       = 'iMIS API Wrapper'
+  s.description   = 'A wrapper for the iMIS API.'
+  s.homepage      = 'http://rubygems.org/gems/usps-imis-api'
+  s.authors       = ['Julian Fiander']
+  s.email         = 'jsfiander@gmail.com'
+  s.require_paths = %w[lib]
+  s.files         = `git ls-files`.split("\n")
+  s.metadata['rubygems_mfa_required'] = 'true'
+
+  s.required_ruby_version = '>= 3.0'
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: usps-imis-api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Julian Fiander
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-10-13 00:00:00.000000000 Z
+dependencies: []
+description: A wrapper for the iMIS API.
+email: jsfiander@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- Gemfile
+- Gemfile.lock
+- lib/ext/hash.rb
+- lib/imis/api.rb
+- lib/imis/config.rb
+- lib/imis/error/api.rb
+- lib/imis/error/mapper.rb
+- lib/imis/mapper.rb
+- lib/usps_imis_api.rb
+- spec/api_spec.rb
+- spec/mapper_spec.rb
+- spec/spec_helper.rb
+- usps-imis-api.gemspec
+homepage: http://rubygems.org/gems/usps-imis-api
+licenses: []
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.6
+signing_key:
+specification_version: 4
+summary: iMIS API Wrapper
+test_files: []