usps-imis-api 1.0.0.pre.rc.4 → 1.0.0.pre.rc.7

data/lib/usps/imis/mocks/business_object.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    module Mocks
+      # Mock data response for testing
+      #
+      class BusinessObject
+        attr_reader :fields
+
+        def initialize(**fields)
+          @fields = fields.transform_keys(&:to_s)
+        end
+
+        def get
+          Usps::Imis::Properties.build do |props|
+            fields.each { |name, value| props.add(name, value) }
+          end
+        end
+        alias read get
+
+        def get_field(name) = fields[name]
+        alias fetch get_field
+        alias [] get_field
+
+        def get_fields(*field_names) = field_names.map { fields[it] }
+        alias fetch_all get_fields
+
+        def put_fields(data)
+          Usps::Imis::Properties.build do |props|
+            fields.merge(data.transform_keys(&:to_s)).each { |name, value| props.add(name, value) }
+          end
+        end
+        alias patch put_fields
+
+        def put(data) = data
+        alias update put
+
+        def post(data) = data
+        alias create post
+
+        def delete = ''
+        alias destroy delete
+      end
+    end
+  end
+end

data/lib/usps/imis/mocks.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'mocks/business_object'
+
+module Usps
+  module Imis
+    # Namespace for all Mocks
+    #
+    module Mocks; end
+  end
+end

data/lib/usps/imis/panels/base_panel.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    module Panels
+      # Base class for configuring Panels
+      #
+      class BasePanel
+        # The parent +Api+ object
+        #
+        attr_reader :api
+
+        def initialize(api = nil, imis_id: nil)
+          @api = api || Api.new
+          @api.imis_id = imis_id if imis_id
+        end
+
+        # Get a specific object from the Panel
+        #
+        # If +fields+ is provided, will return only those field values
+        #
+        # @param fields [String] Field names to return
+        #
+        # @param ordinal [Integer] The ordinal identifier for the desired object
+        #
+        # @return [Usps::Imis::Data, Array<Usps::Imis::Data>] Response data from the API
+        #
+        def get(ordinal, *fields) = api.on(business_object, ordinal:).get(*fields)
+        alias read get
+
+        # Get a single named field from a Panel for the current member
+        #
+        # @param ordinal [Integer] The ordinal identifier for the desired object
+        # @param field [String] Field name to return
+        #
+        # @return Response data field value from the API
+        #
+        def get_field(ordinal, field) = api.on(business_object, ordinal:).get_field(field)
+        alias fetch get_field
+        alias [] get_field
+
+        # Get named fields from a Panel for the current member
+        #
+        # @param ordinal [Integer] The ordinal identifier for the desired object
+        # @param fields [Array<String>] Field names to return
+        #
+        # @return [Array] Response data from the API
+        #
+        def get_fields(ordinal, *fields) = api.on(business_object, ordinal:).get_fields(*fields)
+        alias fetch_all get_fields
+
+        # Update only specific fields on a Panel for the current member
+        #
+        # @param ordinal [Integer] The ordinal identifier for the desired object
+        # @param fields [Hash] Conforms to pattern +{ field_key => value }+
+        #
+        # @return [Usps::Imis::Data] Response data from the API
+        #
+        def put_fields(ordinal, fields) = api.on(business_object, ordinal:).put_fields(fields)
+        alias patch put_fields
+
+        # Update an existing object in the Panel
+        #
+        # @param data [Hash] The record data for the desired object -- including the required
+        #                    +ordinal+ identifier
+        #
+        # @return [Usps::Imis::Data] Response data from the API
+        #
+        def put(data) = api.on(business_object, ordinal: data[:ordinal]).put(payload(data))
+        alias update put
+
+        # Create a new object in the Panel
+        #
+        # @param data [Hash] The record data for the desired object
+        #
+        # @return [Usps::Imis::Data] Response data from the API
+        #
+        def post(data) = api.on(business_object).post(payload(data))
+        alias create post
+
+        # Remove a specific object from the Panel
+        #
+        # @param ordinal [Integer] The ordinal identifier for the desired object
+        #
+        # @return [true] Only on success response (i.e. blank string from the API)
+        #
+        def delete(ordinal) = api.on(business_object, ordinal:).delete
+        alias destroy delete
+
+        # Ruby 3.5 instance variable filter
+        #
+        def instance_variables_to_inspect = instance_variables - %i[@api]
+
+      private
+
+        def logger = Imis.logger('Panel')
+
+        def business_object
+          raise Errors::PanelUnimplementedError.from(self.class.name, 'business_object')
+        end
+
+        def payload(_data)
+          raise Errors::PanelUnimplementedError.from(self.class.name, 'payload(data)')
+        end
+
+        def payload_header(data)
+          {
+            '$type' => 'Asi.Soa.Core.DataContracts.GenericEntityData, Asi.Contracts',
+            'EntityTypeName' => business_object,
+            'PrimaryParentEntityTypeName' => 'Party',
+            'Identity' => identity(data[:ordinal]),
+            'PrimaryParentIdentity' => primary_parent_identity
+          }
+        end
+
+        def identity(ordinal = nil)
+          {
+            '$type' => 'Asi.Soa.Core.DataContracts.IdentityData, Asi.Contracts',
+            'EntityTypeName' => business_object,
+            'IdentityElements' => {
+              '$type' => identity_type,
+              '$values' => [api.imis_id.to_s, ordinal&.to_s].compact
+            }
+          }
+        end
+
+        def primary_parent_identity
+          {
+            '$type' => 'Asi.Soa.Core.DataContracts.IdentityData, Asi.Contracts',
+            'EntityTypeName' => 'Party',
+            'IdentityElements' => {
+              '$type' => identity_type,
+              '$values' => [api.imis_id.to_s]
+            }
+          }
+        end
+
+        def identity_type = 'System.Collections.ObjectModel.Collection`1[[System.String, mscorlib]], mscorlib'
+
+        def build_payload(data, &) = payload_header(data).merge(Properties.build(&))
+      end
+    end
+  end
+end

data/lib/usps/imis/panels/education.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    module Panels
+      # Panel for accessing the Educational completions business object
+      #
+      class Education < BasePanel
+      private
+
+        def business_object
+          'ABC_ASC_Educ'
+        end
+
+        def payload(data)
+          build_payload(data) do |props|
+            props.add 'ID', api.imis_id.to_s
+            props.add 'Ordinal', data[:ordinal] if data[:ordinal]
+            props.add 'ABC_EDUC_THRU_DATE', data[:thru_date] || '0001-01-01T00:00:00'
+            props.add 'ABC_ECertificate', data[:certificate]
+            props.add 'ABC_Educ_Description', data[:description]
+            props.add 'ABC_Educ_Effective_Date', data[:effective_date]
+            props.add 'ABC_Educ_Source_System', data[:source]
+            props.add 'ABC_Educ_Transaction_Date', Time.now
+            props.add 'ABC_Other_Code', data[:code]
+            props.add 'ABC_Product_Code', data[:type_code]
+            props.add 'ABC_TYPE', data[:abc_type_code] || 'EDUC'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/usps/imis/panels/vsc.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    module Panels
+      # Panel for accessing the annual VSC completed counts business object
+      #
+      class Vsc < BasePanel
+      private
+
+        def business_object
+          'ABC_ASC_Vessel_Safety_Checks'
+        end
+
+        def payload(data)
+          build_payload(data) do |props|
+            props.add 'ID', api.imis_id.to_s
+            props.add 'Ordinal', data[:ordinal] if data[:ordinal]
+            props.add 'Source_System', 'Manual ITCom Entry'
+            props.add 'ABC_ECertificate', data[:certificate]
+            props.add 'Activity_Type', 'VSC'
+            props.add 'Description', 'Vessel Safety Checks'
+            props.add 'Effective_Date', "#{data[:year]}-12-01T00:00:00"
+            props.add 'Quantity', data[:count]
+            props.add 'Thru_Date', "#{data[:year]}-12-31T00:00:00"
+            props.add 'Transaction_Date', Time.now
+          end
+        end
+      end
+    end
+  end
+end

data/lib/usps/imis/panels.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'panels/base_panel'
+require_relative 'panels/vsc'
+require_relative 'panels/education'
+
+module Usps
+  module Imis
+    # Namespace for all Panels
+    #
+    module Panels
+      # Convenience accessor for available Panel objects
+      #
+      # @param api [Api] Parent to use for making requests
+      #
+      def self.all(api = Api.new)
+        panels = constants.reject { it == :BasePanel }
+
+        Struct
+          .new(*panels.map { it.to_s.underscore.to_sym })
+          .new(*panels.map { const_get(it).new(api) })
+      end
+    end
+  end
+end

data/lib/usps/imis/properties.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    # Constructor for the Properties field
+    #
+    class Properties
+      # Build the data for a new Properties field
+      #
+      def self.build(&) = new.build(&)
+
+      # Build the data for the Properties field
+      #
+      def build
+        yield(self)
+
+        {
+          'Properties' => {
+            '$type' => 'Asi.Soa.Core.DataContracts.GenericPropertyDataCollection, Asi.Contracts',
+            '$values' => @properties
+          }
+        }
+      end
+
+      # Add an individual property to the field
+      #
+      def add(name, value)
+        @properties ||= []
+        @properties << {
+          '$type' => 'Asi.Soa.Core.DataContracts.GenericPropertyData, Asi.Contracts',
+          'Name' => name,
+          'Value' => wrap(value)
+        }
+      end
+
+    private
+
+      def wrap(value)
+        case value
+        when String then value
+        when Time, DateTime then value.strftime('%Y-%m-%dT%H:%I:%S')
+        when Integer then { '$type' => 'System.Int32', '$value' => value }
+        when true, false then { '$type' => 'System.Boolean', '$value' => value }
+        else
+          raise Errors::UnexpectedPropertyTypeError.from(value)
+        end
+      end
+    end
+  end
+end

data/lib/usps/imis/query.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    # API wrapper for IQA Queries
+    #
+    class Query
+      include Enumerable
+      include Requests
+
+      # Endpoint for IQA query requests
+      #
+      QUERY_PATH = 'api/Query'
+
+      # The parent +Api+ object
+      #
+      attr_reader :api
+
+      # Name of the Query to run
+      #
+      attr_reader :query_name
+
+      # Parameters for the Query
+      #
+      attr_reader :query_params
+
+      # Current offset for paging through the Query
+      #
+      attr_reader :offset
+
+      # A new instance of +Query+
+      #
+      # @param api [Api] Parent to use for making requests
+      # @param query_name [String] Full path of the query in IQA, e.g. +$/_ABC/Fiander/iMIS_ID+
+      # @query_params [Hash] Conforms to pattern +{ param_name => param_value }+
+      #
+      def initialize(api, query_name, query_params)
+        @api = api
+        @query_name = query_name
+        @query_params = query_params
+      end
+
+      # Iterate through all results from the query
+      #
+      def each(&)
+        logger.info 'Running IQA Query on iMIS'
+
+        items = []
+        find_each { items << it }
+        items.each(&)
+      end
+
+      # Iterate through all results from the query, fetching one page at a time
+      #
+      def find_each(&)
+        result = { 'HasNext' => true }
+        count = 0
+
+        while result['HasNext']
+          logger.info 'Fetching IQA Query page'
+
+          result = fetch
+
+          count += result['Count'] || 0
+          logger.info "  -> #{count} / #{result['TotalCount']} #{'item'.pluralize(count)}"
+          logger.debug '  -> Query page data:'
+          JSON.pretty_generate(result).split("\n").each { logger.debug "    -> #{it}" }
+
+          items = result['Items']['$values'].map { it.except('$type') }
+          @offset = result['NextOffset']
+
+          items.each(&)
+        end
+
+        nil
+      end
+
+      # Ruby 3.5 instance variable filter
+      #
+      def instance_variables_to_inspect = instance_variables - %i[@api]
+
+    private
+
+      def token = api.token
+      def token_expiration = api.token_expiration
+
+      def path = "#{QUERY_PATH}?#{query_params.merge(QueryName: query_name, Offset: offset).to_query}"
+      def uri = URI(File.join(Imis.configuration.hostname, path))
+      def fetch = JSON.parse(submit(uri, authorize(Net::HTTP::Get.new(uri))).body)
+
+      def logger = Imis.logger('Query')
+    end
+  end
+end

data/lib/usps/imis/requests.rb

@@ -2,9 +2,13 @@
 
 module Usps
   module Imis
+    # @private
+    #
     module Requests
     private
 
+      def logger = Imis.logger
+
       def client(uri)
         Net::HTTP.new(uri.host, uri.port).tap do |http|
           http.use_ssl = true
@@ -17,15 +21,37 @@ module Usps
       # 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}") }
+        if token_expiration < Time.now
+          logger.debug 'Token expired: re-authenticating with iMIS'
+          authenticate
+        end
+        request.tap { it.add_field('Authorization', "Bearer #{token}") }
       end
 
       def submit(uri, request)
+        logger.info 'Submitting request to iMIS'
+        logger.debug "  -> #{request.class.name.demodulize.upcase} #{uri}"
+        sanitized_request_body(request).split("\n").each { logger.debug "  -> #{it}" }
         client(uri).request(request).tap do |result|
-          raise Error::ResponseError.from(result) unless result.is_a?(Net::HTTPSuccess)
+          raise Errors::ResponseError.from(result) unless result.is_a?(Net::HTTPSuccess)
+
+          logger.info 'Request succeeded'
         end
       end
+
+      def sanitized_request_body(request)
+        return '*** empty request body ***' if request.body.nil?
+
+        body = request.body.dup
+
+        Imis.config.filtered_parameters.each do |parameter|
+          body =
+            body.gsub(Imis.config.public_send(parameter), '[FILTERED]')
+                .gsub(CGI.escape(Imis.config.public_send(parameter)), '[FILTERED]')
+        end
+
+        body
+      end
     end
   end
 end

data/lib/usps/imis/version.rb

@@ -2,6 +2,6 @@
 
 module Usps
   module Imis
-    VERSION = '1.0.0-rc.4'
+    VERSION = '1.0.0-rc.7'
   end
 end

data/lib/usps/imis.rb

@@ -6,23 +6,21 @@ require 'json'
 require 'time'
 require 'cgi'
 
-# Extensions
-# :nocov:
-require 'ext/hash' unless defined?(Rails)
-# :nocov:
+require 'active_support/core_ext/string/inflections'
+require 'active_support/core_ext/object/to_query'
+require 'active_support/core_ext/enumerable'
+require 'active_support/string_inquirer'
+require 'logger'
+require 'active_support/isolated_execution_state' # Fix costant loading issue with TaggedLogging
+require 'active_support/tagged_logging'
 
 # Internal requires
 require_relative 'imis/config'
-require_relative 'imis/error/api_error'
-require_relative 'imis/error/mapper_error'
-require_relative 'imis/error/response_error'
-require_relative 'imis/requests'
-require_relative 'imis/business_object'
+require_relative 'imis/error'
 require_relative 'imis/api'
-require_relative 'imis/mapper'
-require_relative 'imis/panel/base_panel'
-require_relative 'imis/panel/vsc'
-require_relative 'imis/panel/education'
+require_relative 'imis/properties'
+require_relative 'imis/panels'
+require_relative 'imis/mocks'
 
 module Usps
   # API wrapper for interacting with iMIS
@@ -36,6 +34,7 @@ module Usps
       def configuration
         @configuration ||= Config.new
       end
+      alias config configuration
 
       # Used to define a block of configuration settings
       #
@@ -45,6 +44,10 @@ module Usps
         yield(configuration) if block_given?
         configuration
       end
+
+      # Logger (with optional nested tags) to write to
+      #
+      def logger(*tags) = configuration.logger.tagged('iMIS', *tags)
     end
   end
 end

data/spec/lib/usps/imis/api_spec.rb

@@ -17,13 +17,13 @@ describe Usps::Imis::Api do
     it 'stores the initial imis_id' do
       api = described_class.new(imis_id: 42)
 
-      expect(api.imis_id).to eq('42')
+      expect(api.imis_id).to eq(42)
     end
   end
 
   describe '#imis_id_for' do
     it 'gets the iMIS ID' do
-      expect(api.imis_id_for('E231625')).to eq('31092')
+      expect(api.imis_id_for('E231625')).to eq(31092)
     end
 
     context 'with a query error' do
@@ -31,25 +31,38 @@ describe Usps::Imis::Api do
 
       it 'wraps errors' do
         expect { api.imis_id_for('E231625') }.to raise_error(
-          Usps::Imis::Error::ApiError, 'Member not found'
+          Usps::Imis::Errors::NotFoundError, 'Member not found'
         )
       end
     end
   end
 
+  describe '#query' do
+    let(:query) { api.query('$/ABC/ExampleQueryAll', {}) }
+
+    before do
+      allow(query).to receive(:fetch).and_return(
+        { 'Items' => { '$values' => [{ 'key1' => 'value1' }] }, 'HasNext' => true, 'NextOffset' => 1 },
+        { 'Items' => { '$values' => [{ 'key1' => 'value2' }] }, 'HasNext' => false, 'NextOffset' => 0 }
+      )
+    end
+
+    it 'collects all query results' do
+      expect(query.to_a).to eq([{ 'key1' => 'value1' }, { 'key1' => 'value2' }])
+    end
+  end
+
   describe '#put' do
     before { api.imis_id = 31092 }
 
     it 'sends an update' do
-      expect(api.business_object('ABC_ASC_Individual_Demog').put_fields('TotMMS' => 15)).to(
-        be_a(Hash)
-      )
+      expect(api.on('ABC_ASC_Individual_Demog').put_fields('TotMMS' => 15)).to be_a(Hash)
     end
 
     context 'when receiving a response error' do
       let(:warning_text) do
         <<~WARNING.chomp
-          Usps::Imis::Error::ResponseError: [INTERNAL_SERVER_ERROR] The iMIS API returned an error.
+          Usps::Imis::Errors::ResponseError: [INTERNAL_SERVER_ERROR] The iMIS API returned an error.
           Something went wrong
         WARNING
       end
@@ -63,8 +76,8 @@ describe Usps::Imis::Api do
       end
 
       it 'wraps the error' do
-        expect { api.business_object('ABC_ASC_Individual_Demog').put_fields('TotMMS' => 15) }.to(
-          raise_error(Usps::Imis::Error::ApiError, warning_text)
+        expect { api.on('ABC_ASC_Individual_Demog').put_fields('TotMMS' => 15) }.to(
+          raise_error(Usps::Imis::Errors::ResponseError, warning_text)
         )
       end
     end
@@ -73,7 +86,7 @@ describe Usps::Imis::Api do
   describe '#with' do
     it 'sends an update from put' do
       expect(
-        api.with(31092) { business_object('ABC_ASC_Individual_Demog').put_fields('TotMMS' => 15) }
+        api.with(31092) { on('ABC_ASC_Individual_Demog').put_fields('TotMMS' => 15) }
       ).to be_a(Hash)
     end
 
@@ -88,13 +101,13 @@ describe Usps::Imis::Api do
     it 'blocks calling imis_id=' do
       expect do
         api.with(31092) { self.imis_id = 31092 }
-      end.to raise_error(Usps::Imis::Error::ApiError, 'Cannot change iMIS ID while locked')
+      end.to raise_error(Usps::Imis::Errors::LockedIdError, 'Cannot change iMIS ID while locked')
     end
 
     it 'blocks calling imis_id_for' do
       expect do
         api.with(31092) { imis_id_for('E231625') }
-      end.to raise_error(Usps::Imis::Error::ApiError, 'Cannot change iMIS ID while locked')
+      end.to raise_error(Usps::Imis::Errors::LockedIdError, 'Cannot change iMIS ID while locked')
     end
   end
 
@@ -118,7 +131,7 @@ describe Usps::Imis::Api do
       end
 
       expect(result).to be_a(Hash)
-      expect(api.imis_id).to eq('31092')
+      expect(api.imis_id).to eq(31092)
     end
 
     it 'nests on and with', :aggregate_failures do