usps-imis-api 1.0.0.pre.rc.5 → 1.0.0.pre.rc.8

data/lib/usps/imis/mapper.rb

@@ -28,6 +28,37 @@ module Usps
         @api.imis_id = imis_id if imis_id
       end
 
+      # Get a member's data for a specific field by arbitrary field name
+      #
+      # Does not require knowing which business object / iMIS-specific field name to use
+      #
+      # Only available for fields defined in +FIELD_MAPPING+
+      #
+      # @param field_key [Symbol] Internal name of the field
+      #
+      # @return Value of the field
+      #
+      def fetch(field_key)
+        missing_mapping!(field_key) unless FIELD_MAPPING.key?(field_key.to_sym)
+
+        business_object_name, field = FIELD_MAPPING[field_key]
+        api.on(business_object_name)[field]
+      end
+      alias [] fetch
+
+      # Update a member's data for a specific field by arbitrary field name
+      #
+      # Does not require knowing which business object / iMIS-specific field name to use
+      #
+      # Only available for fields defined in +FIELD_MAPPING+
+      #
+      # @param field_key [Symbol] Internal name of the field
+      #
+      # @return Value of the field
+      #
+      def put_field(field_key, value) = update(field_key => value)
+      alias []= put_field
+
       # 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
@@ -36,7 +67,7 @@ module Usps
       #
       # @param data [Hash] Conforms to pattern +{ field_key => value }+
       #
-      # @return [Array<Hash>] Response data from the API for each internal update request
+      # @return [Array<Usps::Imis::Data>] Response data from the API for each internal update request
       #
       def update(data)
         updates = data.each_with_object({}) do |(field_key, value), hash|
@@ -47,37 +78,37 @@ module Usps
         end
 
         updates.map do |business_object_name, field_updates|
-          api.business_object(business_object_name).put_fields(field_updates)
+          api.on(business_object_name).put_fields(field_updates)
         end
       end
 
+      # Ruby 3.5 instance variable filter
+      #
+      def instance_variables_to_inspect = instance_variables - %i[@api]
+
     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
+      def logger = Imis.logger('Mapper')
+
+      def map_update(field_key)
+        missing_mapping!(field_key) unless FIELD_MAPPING.key?(field_key.to_sym)
+
+        business_object_name, field = FIELD_MAPPING[field_key.to_sym]
+        yield(business_object_name, field)
       end
 
-      def missing_mapping(field_name)
+      def missing_mapping!(field_key)
         unless ENV['TESTING']
           # :nocov:
-          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"
-          )
+          "Mapper does not know how to handle field \"#{field_key}\".\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"
+            .split("\n")
+            .each { logger.warn(it) }
           # :nocov:
         end
 
-        raise(
-          Error::MapperError,
-          "Unrecognized field: \"#{field_name}\". " \
-          'Please report what data you are attempting to work with to ITCom leadership.'
-        )
+        raise Errors::MapperError.new({ field_key: })
       end
     end
   end

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,154 @@
+# 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 a single named field on a business object for the current member
+        #
+        # @param field [String] Name of the field
+        # @param value Value of the field
+        #
+        # @return [Usps::Imis::Data] Response data from the API
+        #
+        def put_field(field, value) = api.on(business_object, ordinal:).put_field(field, value)
+        alias []= put_field
+
+        # 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/{panel → panels}/education.rb

@@ -2,7 +2,7 @@
 
 module Usps
   module Imis
-    module Panel
+    module Panels
       # Panel for accessing the Educational completions business object
       #
       class Education < BasePanel
@@ -14,7 +14,7 @@ module Usps
 
         def payload(data)
           build_payload(data) do |props|
-            props.add 'ID', api.imis_id
+            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]

data/lib/usps/imis/{panel → panels}/vsc.rb

@@ -2,7 +2,7 @@
 
 module Usps
   module Imis
-    module Panel
+    module Panels
       # Panel for accessing the annual VSC completed counts business object
       #
       class Vsc < BasePanel
@@ -14,7 +14,7 @@ module Usps
 
         def payload(data)
           build_payload(data) do |props|
-            props.add 'ID', api.imis_id
+            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]

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

@@ -7,6 +7,8 @@ module Usps
     module Requests
     private
 
+      def logger = Imis.logger
+
       def client(uri)
         Net::HTTP.new(uri.host, uri.port).tap do |http|
           http.use_ssl = true
@@ -19,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.5'
+    VERSION = '1.0.0-rc.8'
   end
 end

data/lib/usps/imis.rb

@@ -6,26 +6,22 @@ require 'json'
 require 'time'
 require 'cgi'
 
+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'
-
-# Extensions
-# :nocov:
-require 'ext/hash' unless defined?(Rails)
-# :nocov:
+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/panel_properties'
-require_relative 'imis/panel/vsc'
-require_relative 'imis/panel/education'
+require_relative 'imis/properties'
+require_relative 'imis/panels'
+require_relative 'imis/mocks'
+require_relative 'imis/version'
 
 module Usps
   # API wrapper for interacting with iMIS
@@ -39,6 +35,7 @@ module Usps
       def configuration
         @configuration ||= Config.new
       end
+      alias config configuration
 
       # Used to define a block of configuration settings
       #
@@ -48,6 +45,14 @@ 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)
+
+      # Gem version
+      #
+      def version = Gem::Version.new(VERSION)
     end
   end
 end