usps-imis-api 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3bb98ea050e0d9e6b21b9c67b3e1cc7f74020781556015cc4c03e6b748a8cf3d
-  data.tar.gz: 8e309c38ebb754244a278de5b4968a6bd917c78d43271a042b0ab5e81846ea10
+  metadata.gz: 2fd4e1ff81a49f7bf1c0e18fd6f95563d0e59514a68c17ae69f6e18e3e40106d
+  data.tar.gz: 037cfc9634a8db74cd0fb8fbeca66d1d9c98e9eb8e73b677a6933b6caf8ed0dc
 SHA512:
-  metadata.gz: b8ac2e1b390b4f1c6922eb2bd48202aff6015af2ebd9a577572e61d4c24d4219c89ee85bc0c76438fd0c97a020c10b60c021fe95a7819bc260a282d7c56a83b8
-  data.tar.gz: 35aa8c10cc792f75ef6df018264e1171077598a74076193ea083dfd7edb754ed76173531acff8904df00d70adad9506dc844bce4b94d68537e1eca821d7c784d
+  metadata.gz: 1cfa43aa4502d9020faebaa25c06d92214ed5484f1ed0f871026be970a3ed37920b50cb00798120e7345f574c628b9426d47e8de39a64a16d33282e5919e3e49
+  data.tar.gz: 741f1a0444f81f4fb8d8803858d427a9c21508e779431ed48e849412b5ae8c43d871becb8ce83923c5a3545421124258bc5630aa613d603f2ca0cef9ff87c147

data/.rubocop.yml

@@ -10,6 +10,7 @@ AllCops:
     - vendor/**/*
     - tmp/**/*
   NewCops: enable
+  SuggestExtensions: false
 
 Layout/FirstHashElementIndentation:
   EnforcedStyle: consistent

data/Gemfile

@@ -4,6 +4,7 @@ source 'https://rubygems.org'
 gemspec
 
 gem 'dotenv',        '>= 3.1.4'
+gem 'rake',          '>= 13.2.1'
 gem 'rspec',         '>= 3.13.0'
 gem 'rubocop',       '>= 1.66.1'
 gem 'rubocop-rspec', '>= 3.1.0'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    usps-imis-api (0.2.1)
+    usps-imis-api (0.3.0)
 
 GEM
   remote: https://rubygems.org/
@@ -18,6 +18,7 @@ GEM
       racc
     racc (1.8.1)
     rainbow (3.1.1)
+    rake (13.2.1)
     regexp_parser (2.9.2)
     rspec (3.13.0)
       rspec-core (~> 3.13.0)
@@ -61,6 +62,7 @@ PLATFORMS
 
 DEPENDENCIES
   dotenv (>= 3.1.4)
+  rake (>= 13.2.1)
   rspec (>= 3.13.0)
   rubocop (>= 1.66.1)
   rubocop-rspec (>= 3.1.0)

data/Rakefile

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

data/Readme.md

@@ -13,7 +13,7 @@ gem install usps-imis-api
 or add this line to your Gemfile:
 
 ```ruby
-gem 'usps-imis-api', '>= 0.2.0'
+gem 'usps-imis-api', '>= 0.3.0'
 ```
 
 ## Setup
@@ -22,9 +22,9 @@ Include the library, and set the configuration:
 
 ```ruby
 require 'dotenv/load' # Optionally load environment variables from `.env` file
-require 'usps-imis-api'
+require 'usps/imis'
 
-Imis.configure do |config|
+Usps::Imis.configure do |config|
   config.environment = :development # Rails.env
   config.imis_id_query_name = ENV['IMIS_ID_QUERY_NAME']
 
@@ -33,10 +33,12 @@ Imis.configure do |config|
 end
 ```
 
+When using `bin/console`, this configuration will be run by default.
+
 Instantiate the API object:
 
 ```ruby
-api = Imis::Api.new
+api = Usps::Imis::Api.new
 ```
 
 ### Authentication
@@ -148,7 +150,7 @@ For supported panels (usually, business objects with composite identity keys), y
 with them in the same general way:
 
 ```ruby
-vsc = Imis::Panel::Vsc.new
+vsc = Usps::Imis::Panel::Vsc.new
 
 vsc.api.imis_id = 6374
 
@@ -162,6 +164,12 @@ vsc.update(certificate: 'E136924', year: 2024, count: 43, ordinal: ordinal)
 vsc.destroy(ordinal)
 ```
 
+Panels are also accessible directly from the API object:
+
+```ruby
+api.panels.vsc.get(1417)
+```
+
 ### DSL Mode
 
 Instead of manually setting the current iMIS ID, then running individual queries, you can instead
@@ -204,6 +212,12 @@ bundle exec rubocop
 
 Testing and linting are automatically run on every push.
 
+## 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).
+
 ## PHP
 
 This same API is

data/bin/console

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'usps/imis'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# Configure from the environment automatically
+require 'dotenv/load'
+Usps::Imis.configure do |config|
+  config.environment = :development
+  config.imis_id_query_name = ENV['IMIS_ID_QUERY_NAME']
+
+  config.username = ENV['IMIS_USERNAME']
+  config.password = ENV['IMIS_PASSWORD']
+end
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/usps/imis/api.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    class Api
+      AUTHENTICATION_PATH = 'Token'
+      API_PATH = 'api'
+      QUERY_PATH = 'api/Query'
+      PANELS = Struct.new(:vsc)
+
+      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
+
+      # Run requests as DSL, with specific iMIS ID only maintained for this scope
+      #
+      # This should be used with methods that do not change the value of `imis_id`
+      #
+      def with(id, &block)
+        old_id = imis_id
+        self.imis_id = id
+        instance_eval(&block)
+      ensure
+        self.imis_id = old_id
+      end
+
+      # Get a business object for the current member
+      #
+      def get(business_object_name, url_id: nil)
+        uri = uri_for(business_object_name, url_id: url_id)
+        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_fields(business_object_name, fields, url_id: nil)
+        updated = filter_fields(business_object_name, fields)
+        put(business_object_name, updated, url_id: url_id)
+      end
+
+      # Update a business object for the current member
+      #
+      def put(business_object_name, body, url_id: nil)
+        uri = uri_for(business_object_name, url_id: url_id)
+        request = Net::HTTP::Put.new(uri)
+        request.body = JSON.dump(body)
+        result = submit(uri, authorize(request))
+        JSON.parse(result.body)
+      end
+
+      # Create a business object for the current member
+      #
+      def post(business_object_name, body, url_id: nil)
+        uri = uri_for(business_object_name, url_id: url_id)
+        request = Net::HTTP::Post.new(uri)
+        request.body = JSON.dump(body)
+        result = submit(uri, authorize(request))
+        JSON.parse(result.body)
+      end
+
+      # Remove a business object for the current member
+      #
+      # Returns empty string on success
+      #
+      def delete(business_object_name, url_id: nil)
+        uri = uri_for(business_object_name, url_id: url_id)
+        request = Net::HTTP::Delete.new(uri)
+        result = submit(uri, authorize(request))
+        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
+
+      def panels
+        @panels ||= PANELS.new(
+          Panel::Vsc.new(self)
+        )
+      end
+
+      def update(data)
+        mapper.update(data)
+      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, url_id: nil)
+        url_id ||= imis_id
+        url_id = CGI.escape(url_id)
+        URI(File.join(imis_hostname, "#{API_PATH}/#{business_object_name}/#{url_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
+end

data/lib/usps/imis/config.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Usps
+  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
+end

data/lib/usps/imis/error/api.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Usps
+  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
+end

data/lib/usps/imis/error/mapper.rb

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

data/lib/usps/imis/mapper.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    class Mapper
+      FIELD_MAPPING = {
+        vessel_examiner: %w[ABC_ASC_Individual_Demog Vol_Vessel_Examiner],
+        mm: %w[ABC_ASC_Individual_Demog TotMMS],
+        mm_updated: %w[ABC_ASC_Individual_Demog MMS_Updated]
+      }.freeze
+
+      attr_reader :api
+
+      def initialize(api = nil)
+        @api = api || Api.new
+      end
+
+      # Update a member's data on multiple affected business objects by arbitrary field names
+      # Does not require knowing which business object / iMIS-specific field name to use
+      #
+      # Only available for previously-mapped fields
+      #
+      #  `data` is a hash of shape { field_key => value }
+      #
+      def update(data)
+        updates = data.each_with_object({}) do |(field_key, value), hash|
+          map_update(field_key) do |business_object_name, field|
+            hash[business_object_name] ||= {}
+            hash[business_object_name][field] = value
+          end
+        end
+
+        updates.map do |business_object_name, field_updates|
+          api.put_fields(business_object_name, field_updates)
+        end
+      end
+
+    private
+
+      def map_update(field_name)
+        if FIELD_MAPPING.key?(field_name.to_sym)
+          business_object_name, field = FIELD_MAPPING[field_name.to_sym]
+          yield(business_object_name, field)
+        else
+          missing_mapping(field_name)
+        end
+      end
+
+      def missing_mapping(field_name)
+        unless ENV['TESTING']
+          warn(
+            "Mapper does not know how to handle field \"#{field_name}\".\n\n" \
+            'You can use api.put_fields(business_object_name, { field_name => value })  ' \
+            "if you know the business object and iMIS-specific field name.\n\n"
+          )
+        end
+
+        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/panel/vsc.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    module Panel
+      class Vsc
+        BUSINESS_OBJECT = 'ABC_ASC_Vessel_Safety_Checks'
+
+        attr_reader :api
+
+        def initialize(api = nil)
+          @api = api || Api.new
+        end
+
+        def get(ordinal)
+          api.get(BUSINESS_OBJECT, url_id: "~#{api.imis_id}|#{ordinal}")
+        end
+
+        def create(data)
+          api.post(BUSINESS_OBJECT, payload(data), url_id: '')
+        end
+
+        def update(data)
+          api.put(BUSINESS_OBJECT, payload(data), url_id: "~#{api.imis_id}|#{data[:ordinal]}")
+        end
+
+        def destroy(ordinal)
+          api.delete(BUSINESS_OBJECT, url_id: "~#{api.imis_id}|#{ordinal}")
+        end
+
+      private
+
+        # rubocop:disable Metrics/MethodLength
+        def payload(data)
+          identity_type =
+            'System.Collections.ObjectModel.Collection`1[[System.String, mscorlib]], mscorlib'
+
+          {
+            '$type' => 'Asi.Soa.Core.DataContracts.GenericEntityData, Asi.Contracts',
+            'EntityTypeName' => 'ABC_ASC_Vessel_Safety_Checks',
+            'PrimaryParentEntityTypeName' => 'Party',
+            'Identity' => {
+              '$type' => 'Asi.Soa.Core.DataContracts.IdentityData, Asi.Contracts',
+              'EntityTypeName' => 'ABC_ASC_Vessel_Safety_Checks',
+              'IdentityElements' => {
+                '$type' => identity_type,
+                '$values' => [api.imis_id]
+              }
+            },
+            'PrimaryParentIdentity' => {
+              '$type' => 'Asi.Soa.Core.DataContracts.IdentityData, Asi.Contracts',
+              'EntityTypeName' => 'Party',
+              'IdentityElements' => {
+                '$type' => identity_type,
+                '$values' => [api.imis_id]
+              }
+            },
+            'Properties' => {
+              '$type' => 'Asi.Soa.Core.DataContracts.GenericPropertyDataCollection, Asi.Contracts',
+              '$values' => [
+                {
+                  '$type' => 'Asi.Soa.Core.DataContracts.GenericPropertyData, Asi.Contracts',
+                  'Name' => 'ID',
+                  'Value' => api.imis_id
+                },
+                (
+                  if data[:ordinal]
+                    {
+                      '$type' => 'Asi.Soa.Core.DataContracts.GenericPropertyData, Asi.Contracts',
+                      'Name' => 'Ordinal',
+                      'Value' => {
+                        '$type' => 'System.Int32',
+                        '$value' => data[:ordinal]
+                      }
+                    }
+                  end
+                ),
+                {
+                  '$type' => 'Asi.Soa.Core.DataContracts.GenericPropertyData, Asi.Contracts',
+                  'Name' => 'Source_System',
+                  'Value' => 'Manual ITCom Entry'
+                },
+                {
+                  '$type' => 'Asi.Soa.Core.DataContracts.GenericPropertyData, Asi.Contracts',
+                  'Name' => 'ABC_ECertificate',
+                  'Value' => data[:certificate]
+                },
+                {
+                  '$type' => 'Asi.Soa.Core.DataContracts.GenericPropertyData, Asi.Contracts',
+                  'Name' => 'Activity_Type',
+                  'Value' => 'VSC'
+                },
+                {
+                  '$type' => 'Asi.Soa.Core.DataContracts.GenericPropertyData, Asi.Contracts',
+                  'Name' => 'Description',
+                  'Value' => 'Vessel Safety Checks'
+                },
+                {
+                  '$type' => 'Asi.Soa.Core.DataContracts.GenericPropertyData, Asi.Contracts',
+                  'Name' => 'Effective_Date',
+                  'Value' => "#{data[:year]}-12-01T00:00:00"
+                },
+                {
+                  '$type' => 'Asi.Soa.Core.DataContracts.GenericPropertyData, Asi.Contracts',
+                  'Name' => 'Quantity',
+                  'Value' => {
+                    '$type' => 'System.Int32',
+                    '$value' => data[:count]
+                  }
+                },
+                {
+                  '$type' => 'Asi.Soa.Core.DataContracts.GenericPropertyData, Asi.Contracts',
+                  'Name' => 'Thru_Date',
+                  'Value' => "#{data[:year]}-12-31T00:00:00"
+                },
+                {
+                  '$type' => 'Asi.Soa.Core.DataContracts.GenericPropertyData, Asi.Contracts',
+                  'Name' => 'Transaction_Date',
+                  'Value' => Time.now.strftime('%Y-%m-%dT%H:%M:%S')
+                }
+              ].compact
+            }
+          }
+        end
+        # rubocop:enable Metrics/MethodLength
+      end
+    end
+  end
+end

data/lib/usps/imis/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    VERSION = '0.3.0'
+  end
+end