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

data/lib/usps/imis/business_object.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative 'requests'
+require_relative 'data'
+
 module Usps
   module Imis
     # DEV
@@ -18,112 +21,127 @@ module Usps
       #
       attr_reader :business_object_name
 
-      # Override ID param of the URL (e.g. used for Panels)
+      # Ordinal to build override ID param of the URL (e.g. used for Panels)
       #
-      attr_reader :url_id
+      attr_reader :ordinal
 
       # A new instance of +BusinessObject+
       #
-      def initialize(api, business_object_name, url_id: nil)
+      def initialize(api, business_object_name, ordinal: nil)
         @api = api
         @business_object_name = business_object_name
-        @url_id = url_id
+        @ordinal = ordinal
       end
 
       # Get a business object for the current member
       #
-      # @return [Hash] Response data from the API
+      # If +fields+ is provided, will return only those field values
       #
-      def get
-        request = Net::HTTP::Get.new(uri)
-        result = submit(uri, authorize(request))
-        JSON.parse(result.body)
-      end
+      # @param fields [String] Field names to return
+      #
+      # @return [Usps::Imis::Data, Array<Usps::Imis::Data>] Response data from the API
+      #
+      def get(*fields) = fields.any? ? get_fields(*fields) : raw_object
+      alias read get
 
       # Get a single named field from a business object for the current member
       #
-      # @param name [String] Field name to return
+      # @param field [String] Field name to return
       #
-      # @return [Hash] Response data from the API
+      # @return Response data field value from the API
       #
-      def get_field(name)
-        values = get['Properties']['$values']
-        value = values.find { |hash| hash['Name'] == name }['Value']
+      def get_field(field) = raw_object[field]
+      alias fetch get_field
+      alias [] get_field
 
-        value.is_a?(String) ? value : value['$value']
+      # Get named fields from a business object for the current member
+      #
+      # @param names [Array<String>] Field names to return
+      #
+      # @return [Array] Response data from the API
+      #
+      def get_fields(*fields)
+        values = raw_object
+        fields.map { values[it] }
       end
+      alias fetch_all get_fields
 
       # Update only specific fields on a business object for the current member
       #
       # @param fields [Hash] Conforms to pattern +{ field_key => value }+
       #
-      # @return [Hash] Response data from the API
+      # @return [Usps::Imis::Data] Response data from the API
       #
-      def put_fields(fields)
-        updated = filter_fields(fields)
-        put(updated)
-      end
+      def put_fields(fields) = put(filter_fields(fields))
+      alias patch put_fields
 
       # Update a business object for the current member
       #
+      # Any properties not included will be left unmodified
+      #
       # @param body [Hash] Full raw API object data
       #
-      # @return [Hash] Response data from the API
+      # @return [Usps::Imis::Data] Response data from the API
       #
-      def put(body)
-        request = Net::HTTP::Put.new(uri)
-        request.body = JSON.dump(body)
-        result = submit(uri, authorize(request))
-        JSON.parse(result.body)
-      end
+      def put(body) = put_object(Net::HTTP::Put.new(uri), body)
+      alias update put
 
       # Create a business object for the current member
       #
       # @param body [Hash] Full raw API object data
       #
-      # @return [Hash] Response data from the API
+      # @return [Usps::Imis::Data] Response data from the API
       #
-      def post(body)
-        request = Net::HTTP::Post.new(uri)
-        request.body = JSON.dump(body)
-        result = submit(uri, authorize(request))
-        JSON.parse(result.body)
-      end
+      def post(body) = put_object(Net::HTTP::Post.new(uri(id: '')), body)
+      alias create post
 
       # Remove a business object for the current member
       #
-      # @return [String] Error response body from the API, or empty string on success
+      # @return [true] Only on success response (i.e. blank string from the API)
       #
-      def delete
-        request = Net::HTTP::Delete.new(uri)
-        result = submit(uri, authorize(request))
-        result.body
-      end
+      def delete = submit(uri, authorize(Net::HTTP::Delete.new(uri))).body == '' # rubocop:disable Naming/PredicateMethod
+      alias destroy delete
+
+      # 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 logger = Imis.logger('BusinessObject')
+
       # Construct a business object API endpoint address
       #
-      def uri
-        id_for_url = url_id ? CGI.escape(url_id) : api.imis_id
-        full_path = "#{API_PATH}/#{business_object_name}/#{id_for_url}"
+      def uri(id: nil)
+        full_path = "#{API_PATH}/#{business_object_name}/#{id_for_uri(id)}"
         URI(File.join(Imis.configuration.hostname, full_path))
       end
 
+      # Select the correct ID to use in the URI
+      #
+      def id_for_uri(id = nil)
+        return CGI.escape(id) unless id.nil?
+        return CGI.escape("~#{api.imis_id}|#{ordinal}") if ordinal
+
+        api.imis_id.to_s
+      end
+
       # Manually assemble the matching data structure, with fields in the correct order
       #
       def filter_fields(fields)
         existing = get
 
         JSON.parse(JSON.dump(existing)).tap do |updated|
-          # The first property is always the iMIS ID again
-          updated['Properties']['$values'] = [existing['Properties']['$values'][0]]
+          # Preserve the iMIS ID, as well as the Ordinal (if present)
+          updated['Properties']['$values'], properties =
+            existing.raw['Properties']['$values'].partition { %w[ID Ordinal].include?(it['Name']) }
 
           # Iterate through all existing fields
-          existing['Properties']['$values'].each do |value|
+          properties.each do |value|
+            # Skip unmodified fields
             next unless fields.keys.include?(value['Name'])
 
             # Strings are not wrapped in the type definition structure
@@ -139,6 +157,28 @@ module Usps
           end
         end
       end
+
+      # Get a raw object response from the API
+      #
+      # Useful for stubbing data in tests
+      #
+      def raw_object
+        request = Net::HTTP::Get.new(uri)
+        result = submit(uri, authorize(request))
+        result = Data.from_json(result.body)
+        JSON.pretty_generate(result).split("\n").each { logger.debug "    -> #{it}" }
+        result
+      end
+
+      # Upload an object to the API
+      #
+      def put_object(request, body)
+        request.body = JSON.dump(body)
+        result = submit(uri, authorize(request))
+        result = Data.from_json(result.body)
+        JSON.pretty_generate(result).split("\n").each { logger.debug "    -> #{it}" }
+        result
+      end
     end
   end
 end

data/lib/usps/imis/config.rb

@@ -9,21 +9,28 @@ module Usps
       IMIS_ROOT_URL_DEV = 'https://abcdev.imiscloud.com'
 
       attr_accessor :imis_id_query_name, :username, :password
-      attr_reader :environment
+      attr_reader :environment, :logger, :logger_level
 
       def initialize
         @environment = defined?(Rails) ? Rails.env : ActiveSupport::StringInquirer.new('development')
         @imis_id_query_name = ENV.fetch('IMIS_ID_QUERY_NAME', nil)
         @username = ENV.fetch('IMIS_USERNAME', nil)
         @password = ENV.fetch('IMIS_PASSWORD', nil)
+        @logger = ActiveSupport::TaggedLogging.new(Logger.new($stdout, level: :info))
 
         yield self if block_given?
+
+        @logger_level = logger.class::SEV_LABEL[logger.level].downcase.to_sym
       end
 
       def environment=(env)
         @environment = ActiveSupport::StringInquirer.new(env.to_s)
       end
 
+      def logger=(logger)
+        @logger = ActiveSupport::TaggedLogging.new(logger)
+      end
+
       # Environment-specific API endpoint hostname
       #
       # @return The API hostname for the current environment
@@ -32,12 +39,16 @@ module Usps
         return IMIS_ROOT_URL_PROD if environment.production?
         return IMIS_ROOT_URL_DEV if environment.development?
 
-        raise Error::ApiError, "Unexpected API environment: #{environment}"
+        raise Errors::ConfigError, "Unexpected API environment: #{environment}"
       end
 
       # Ruby 3.5 instance variable filter
       #
-      def instance_variables_to_inspect = %i[@environment @imis_id_query_name @username]
+      def instance_variables_to_inspect = %i[@environment @imis_id_query_name @username @logger_level]
+
+      # Parameters to filter out of logging
+      #
+      def filtered_parameters = %i[password]
     end
   end
 end

data/lib/usps/imis/data.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'pp'
+require 'stringio'
+
+module Usps
+  module Imis
+    # Convenience wrapper for accessing specific properties within an API data response
+    #
+    class Data < Hash
+      # Load raw API response JSON to access properties
+      #
+      # @param json [String] Raw API response JSON
+      #
+      def self.from_json(json) = self[JSON.parse(json)]
+
+      alias raw to_h
+
+      # The Business Object or Panel name
+      #
+      def entity = raw['EntityTypeName']
+
+      # Access the iMIS ID property
+      #
+      def imis_id = self['ID'].to_i
+      alias id imis_id
+
+      # Access the Ordinal identifier property (if present)
+      #
+      def ordinal = self['Ordinal']&.to_i
+
+      # Access an individual property value by name
+      #
+      def [](property_name)
+        property = raw['Properties']['$values'].find { it['Name'] == property_name }
+        return if property.nil?
+
+        value = property['Value']
+        value.is_a?(String) ? value : value['$value']
+      end
+
+      # Hash of all property names to values
+      #
+      # @param include_ids [Boolean] Whether to include the iMIS ID and Ordinal
+      #
+      def properties(include_ids: false)
+        raw['Properties']['$values']
+          .map { it['Name'] }
+          .select { include_ids || !%w[ID Ordinal].include?(it) }
+          .index_with { self[it] }
+      end
+
+      def inspect
+        stringio = StringIO.new
+        PP.pp(self, stringio)
+        stringio.string.delete("\n")
+      end
+
+      def pretty_print(pp)
+        data = { entity:, imis_id:, ordinal: }.compact
+
+        pp.group(1, "#<#{self.class}", '>') do
+          data.each do |key, value|
+            pp.breakable
+            pp.text "#{key}="
+            pp.pp value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/usps/imis/error.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    # Base error class for all internal exceptions
+    #
+    class Error < StandardError
+      # Additional call-specific metadata to pass through to Bugsnag
+      #
+      attr_accessor :metadata
+
+      # A new instance of +ApiError+
+      #
+      # @param message [String] The base exception message
+      # @param metadata [Hash] Additional call-specific metadata to pass through to Bugsnag
+      #
+      def initialize(message, metadata = {})
+        super(message)
+        @metadata = metadata
+      end
+
+      # Additional metadata to include in Bugsnag reports
+      #
+      # Can include fields at the top level, which will be shows on the custom tab
+      #
+      # Can include fields nested under a top-level key, which will be shown on a tab with the
+      # top-level key as its name
+      #
+      # @return [Hash]
+      #
+      def bugsnag_meta_data
+        metadata == {} ? {} : base_metadata
+      end
+
+    private
+
+      def base_metadata
+        { api: metadata }
+      end
+    end
+  end
+end
+
+require_relative 'errors/api_error'
+require_relative 'errors/config_error'
+require_relative 'errors/locked_id_error'
+require_relative 'errors/mapper_error'
+require_relative 'errors/not_found_error'
+require_relative 'errors/response_error'
+require_relative 'errors/panel_unimplemented_error'
+require_relative 'errors/unexpected_property_type_error'

data/lib/usps/imis/errors/api_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    module Errors
+      # Generic exception raised from within the gem
+      #
+      class ApiError < Error; end
+    end
+  end
+end

data/lib/usps/imis/errors/config_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    module Errors
+      # Exception raised for invalid configuration
+      #
+      class ConfigError < Error; end
+    end
+  end
+end

data/lib/usps/imis/errors/locked_id_error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    module Errors
+      # Exception raised when attempting to change the iMIS ID while it is locked
+      #
+      class LockedIdError < Error
+        def initialize = super(message)
+
+        def message = 'Cannot change iMIS ID while locked'
+      end
+    end
+  end
+end

data/lib/usps/imis/errors/mapper_error.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    module Errors
+      # Exception raised by a +Mapper+
+      #
+      class MapperError < Error
+        # Create a new instance of +MapperError+
+        #
+        # @param metadata [Hash] Additional call-specific metadata to pass through to Bugsnag
+        #
+        def initialize(metadata = {})
+          @metadata = metadata
+          super(message, metadata)
+        end
+
+        # Exception message including the unrecognized field
+        #
+        def message
+          <<~MESSAGE.chomp
+            Mapper does not recognize field: "#{metadata[:field_key]}".
+            Please report what data you are attempting to work with to ITCom leadership.
+          MESSAGE
+        end
+      end
+    end
+  end
+end

data/lib/usps/imis/errors/not_found_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    module Errors
+      # Exception raised when the requested object cannot be found
+      #
+      class NotFoundError < Error; end
+    end
+  end
+end

data/lib/usps/imis/errors/panel_unimplemented_error.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    module Errors
+      # Exception raised when a panel is missing required method definitions
+      #
+      class PanelUnimplementedError < Error
+        # Create a new instance of +PanelUnimplementedError+ from the class name and missing method
+        #
+        # @param class_name [String] Name of the Panel class that is missing a method definition
+        # @param method [String] Method definition that is not defined on the Panel
+        #
+        def self.from(class_name, method) = new(class_name, method)
+
+        # Create a new instance of +PanelUnimplementedError+
+        #
+        # @param class_name [String] Name of the Panel class that is missing a method definition
+        # @param method [String] Method definition that is not defined on the Panel
+        # @param metadata [Hash] Additional call-specific metadata to pass through to Bugsnag
+        #
+        def initialize(class_name, method, metadata = {})
+          @class_name = class_name
+          @method = method
+          super(message, metadata)
+        end
+
+        # Exception message including the undefined method
+        #
+        def message = "#{@class_name} must implement ##{@method}"
+      end
+    end
+  end
+end

data/lib/usps/imis/{error → errors}/response_error.rb

@@ -2,10 +2,10 @@
 
 module Usps
   module Imis
-    module Error
+    module Errors
       # Exception raised due to receiving an error response from the API
       #
-      class ResponseError < ApiError
+      class ResponseError < Error
         # [Net::HTTPResponse] The response received from the API
         #
         attr_reader :response
@@ -18,17 +18,14 @@ module Usps
         #
         # @param response [Net::HTTPResponse] The response received from the API
         #
-        def self.from(response)
-          new(nil, response)
-        end
+        def self.from(response) = new(response)
 
         # Create a new instance of +ResponseError+
         #
-        # @param _message Ignored
         # @param response [Net::HTTPResponse] The response received from the API
         # @param metadata [Hash] Additional call-specific metadata to pass through to Bugsnag
         #
-        def initialize(_message, response, metadata = {})
+        def initialize(response, metadata = {})
           @response = response
           super(message, metadata)
         end
@@ -43,7 +40,7 @@ module Usps
         # @return [Hash]
         #
         def bugsnag_meta_data
-          base_metadata.tap { |m| m[:api].merge!(metadata) }
+          base_metadata.tap { it[:api].merge!(metadata) }
         end
 
         # Auto-formatted exception message, based on the provided API response

data/lib/usps/imis/errors/unexpected_property_type_error.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    module Errors
+      # Exception raised when attempting to wrap an unexpected property type
+      #
+      class UnexpectedPropertyTypeError < Error
+        # Create a new instance of +UnexpectedPropertyTypeError+ from an unexpected value
+        #
+        # @param value Unexpected value
+        #
+        def self.from(value) = new(value)
+
+        # Create a new instance of +UnexpectedPropertyTypeError+
+        #
+        # @param value Unexpected value
+        # @param metadata [Hash] Additional call-specific metadata to pass through to Bugsnag
+        #
+        def initialize(value, metadata = {})
+          @value = value
+          super(message, metadata)
+        end
+
+        # Exception message including the undefined method
+        #
+        def message = "Unexpected property type: #{@value.inspect}"
+      end
+    end
+  end
+end

data/lib/usps/imis/mapper.rb

@@ -28,6 +28,14 @@ module Usps
         @api.imis_id = imis_id if imis_id
       end
 
+      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 on multiple affected business objects by arbitrary field names
       #
       # Does not require knowing which business object / iMIS-specific field name to use
@@ -36,7 +44,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 +55,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