usps-imis-api 0.2.1 → 0.3.1.pre.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3bb98ea050e0d9e6b21b9c67b3e1cc7f74020781556015cc4c03e6b748a8cf3d
-  data.tar.gz: 8e309c38ebb754244a278de5b4968a6bd917c78d43271a042b0ab5e81846ea10
+  metadata.gz: 13821ed6722f9e24d653b29cb2af661a6bfa47b6b38434fd862d9c01f6434056
+  data.tar.gz: d5265804414bde5404c920575baadd957323bb6d700a335a9c637a6cdb9855d2
 SHA512:
-  metadata.gz: b8ac2e1b390b4f1c6922eb2bd48202aff6015af2ebd9a577572e61d4c24d4219c89ee85bc0c76438fd0c97a020c10b60c021fe95a7819bc260a282d7c56a83b8
-  data.tar.gz: 35aa8c10cc792f75ef6df018264e1171077598a74076193ea083dfd7edb754ed76173531acff8904df00d70adad9506dc844bce4b94d68537e1eca821d7c784d
+  metadata.gz: ff6ad6b82f7bf14f6784f31c3d459080d246750a72363a78f4c6cb8aff392ef15123fe0df1cea7623d1c09c574f4e9ee39f75e34813d59c4a20852692214fd56
+  data.tar.gz: f73aeb715681573896f992390f8fcc5dcdeb7eaf9db21d69fc8a324b0d4fc0dcbe76a9b683c2e6b08ad76f20b3ce45b2a46793eb2311d56acc8837fe30c5a0a7

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.1.pre.1)
 
 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
@@ -61,9 +63,13 @@ api.get_imis_id(certificate)
 This will both return the ID, and store it for use with other requests. If you need to change which
 member you are working with, just run this method again with the new certificate number.
 
-### General API Requests
+You can also manually set the current ID, if you already have it for a given member
 
-#### GET
+```ruby
+api.imis_id = imis_id
+```
+
+### GET
 
 To fetch member data, run e.g.:
 
@@ -73,7 +79,7 @@ api.imis_id = 31092
 data = api.get('ABC_ASC_Individual_Demog')
 ```
 
-#### PUT
+### PUT Fields
 
 To update member data, run e.g.:
 
@@ -81,40 +87,48 @@ To update member data, run e.g.:
 api.imis_id = 31092
 
 data = { 'MMS_Updated' => Time.now.strftime('%Y-%m-%dT%H:%M:%S'), 'TotMMS' => new_total }
-update = api.put_object_fields('ABC_ASC_Individual_Demog', data)
+update = api.put_fields('ABC_ASC_Individual_Demog', data)
 ```
 
 This method fetches the current data structure, and filters it down to just what you want to
 update, to reduce the likelihood of update collisions or type validation failures.
 
-### Public Methods
+### PUT
 
-Convert a member's certificate number into an iMIS ID number
+To update member data, run e.g.:
 
 ```ruby
-api.get_imis_id(certificate)
+api.imis_id = 31092
+
+update = api.put('ABC_ASC_Individual_Demog', complete_imis_object)
 ```
 
-Manually set the current ID, if you already have it for a given member
+This method requires a complete iMIS data structure.
 
-```ruby
-api.imis_id = imis_id
-```
+### POST
 
-GET a business object for the current member
+To create new member data, run e.g.:
 
 ```ruby
-api.get(business_object_name)
+created = api.post('ABC_ASC_Individual_Demog', complete_imis_object)
 ```
 
-Update only specific fields on a business object for the current member
+This method requires a complete iMIS data structure.
+
+### DELETE
 
-`fields` is a hash of shape: `{ field_name => new_value }`
+To remove member data, run e.g.:
 
 ```ruby
-api.put_fields(business_object_name, fields)
+api.imis_id = 31092
+
+api.delete('ABC_ASC_Individual_Demog')
 ```
 
+This returns a blank string on success.
+
+### QUERY
+
 Run an IQA Query
 
 `query_params` is a hash of shape: `{ param_name => param_value }`
@@ -148,7 +162,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 +176,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
@@ -177,7 +197,11 @@ api.with(31092) do
   mapper.update(mm: 15)
 
   update(mm: 15)
+end
+```
 
+```ruby
+api.with(6374) do
   panels.vsc.get(1417)
 end
 ```
@@ -204,6 +228,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,69 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    class Mapper
+      FIELD_MAPPING = {
+        grade: %w[ABC_ASC_Individual_Demog Grade],
+        edpro: %w[ABC_ASC_Individual_Demog Educ_Proficiency],
+        edach: %w[ABC_ASC_Individual_Demog Educ_Achievement],
+        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