usps-imis-api 0.11.26 → 0.11.28

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3e12835817725b251105021e66e0119f4a934bcce5e13d648b611875aff33dd
-  data.tar.gz: b01c567700f486cebd6cfabab0b7017fbcd351cd83bb47bfa38528ad3ed2a9f8
+  metadata.gz: 386dc2ca30c8b2c640872931b83d9105e7e189d56c85edb2b8d75e02e6b830e8
+  data.tar.gz: 1353457f06768558a7cf4491ba0dbe221e072679e4c7f0164616743464700259
 SHA512:
-  metadata.gz: 763bd5cb2d6227333d54e135a66bfbe3a51abe236809c1cbd4a7252f3d4cfce3198e6a3d7235e88ee456bff1a7203ec161c62478abacdedac065643718a5ea66
-  data.tar.gz: 66784814074fb357d0b9afc665ba47c9f19091f0e537b85b351ad215e69960568d8ae73e19606b8e813dd1af04d261513b3f3573d4cead995202d97e64c54e57
+  metadata.gz: 9ef7330684ebcb7c169f285a2c4e44e85307df27b8426e9e25889dbd58c3338732cab7199461e3e6c3797d62a6afe915213261fdac08319dbf957cc652a073a3
+  data.tar.gz: 75e262ce1acec88980b072588747032be8be2faf9aa3bc6bf017e8911d0d728b8a6398e029729c715e63cd00e5844bfddbb7e27804607e23c4160dad2cb5f555

data/lib/usps/imis/api.rb

@@ -53,8 +53,9 @@ module Usps
       #
       # @param imis_id [Integer, String] iMIS ID to select immediately on initialization
       #
-      def initialize(imis_id: nil)
+      def initialize(imis_id: nil, record_id: nil)
         self.imis_id = imis_id if imis_id
+        self.record_id = record_id if record_id
         @logger ||= Imis.logger('Api')
         Imis.config.validate!
       end
@@ -71,6 +72,26 @@ module Usps
         @imis_id = id&.to_i
       end
 
+      # Manually set the current record ID
+      #
+      # @param id [Integer, String] Record ID to select for future requests
+      #
+      # @return [Integer] Record ID
+      #
+      def record_id=(id)
+        return if id.nil?
+
+        raise Errors::LockedIdError if lock_imis_id
+
+        @record_id = id.to_i
+      end
+
+      # Currently selected Record ID for API requests
+      #
+      # Defaults to the iMIS ID
+      #
+      def record_id = @record_id || imis_id
+
       # Convert a member's certificate number into an iMIS ID number
       #
       # @param certificate [String] Certificate number to lookup the corresponding iMIS ID for
@@ -101,6 +122,7 @@ module Usps
       #
       # @param id [Integer, String] iMIS ID to select for requests within the block
       # @param certificate [String] Certificate number to convert to iMIS ID and select for requests within the block
+      # @param record_id [Integer] Record ID to select for requests within the block
       #
       # @example
       #   with(12345) do
@@ -109,12 +131,14 @@ module Usps
       #
       # @return [Usps::Imis::Api]
       #
-      def with(id = nil, certificate: nil, &)
+      def with(id = nil, certificate: nil, record_id: nil, &)
         raise ArgumentError, 'Must provide id or certificate' unless id || certificate
 
         old_id = imis_id
+        old_record_id = @record_id
 
         id.nil? ? imis_id_for(certificate) : self.imis_id = id
+        self.record_id = record_id
         return self unless block_given?
 
         @lock_imis_id = true
@@ -123,6 +147,7 @@ module Usps
         if block_given?
           @lock_imis_id = false
           self.imis_id = old_id
+          self.record_id = old_record_id
         end
       end
 

data/lib/usps/imis/base_data.rb

@@ -23,6 +23,12 @@ module Usps
       end
       alias id imis_id
 
+      # Access the Record ID property
+      #
+      def record_id
+        raise Errors::ApiError, "#{self.class} must implement #record_id"
+      end
+
       # Access an individual property value by name
       #
       def [](_property_name)

data/lib/usps/imis/blank_object.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative 'requests'
+require_relative 'data'
+require_relative 'party_data'
+
+module Usps
+  module Imis
+    # Constructor for blank BusinessObject and BasePanel objects
+    #
+    class BlankObject
+      # The parent object
+      #
+      attr_reader :parent
+
+      def initialize(parent, ordinal = nil)
+        @parent = parent
+        @ordinal = ordinal
+      end
+
+      # Build a blank object for the current iMIS ID
+      #
+      def build(&) = payload_header.merge(Properties.build(parent.api.record_id.to_s, @ordinal&.to_s, &))
+
+    private
+
+      def identity_type = 'System.Collections.ObjectModel.Collection`1[[System.String, mscorlib]], mscorlib'
+
+      def payload_header
+        {
+          '$type' => 'Asi.Soa.Core.DataContracts.GenericEntityData, Asi.Contracts',
+          'EntityTypeName' => parent.business_object_name,
+          'PrimaryParentEntityTypeName' => 'Party',
+          'Identity' => identity,
+          'PrimaryParentIdentity' => primary_parent_identity
+        }
+      end
+
+      def identity
+        {
+          '$type' => 'Asi.Soa.Core.DataContracts.IdentityData, Asi.Contracts',
+          'EntityTypeName' => parent.business_object_name,
+          'IdentityElements' => {
+            '$type' => identity_type,
+            '$values' => [parent.api.record_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' => [parent.api.imis_id.to_s]
+          }
+        }
+      end
+    end
+  end
+end

data/lib/usps/imis/business_object.rb

@@ -6,7 +6,8 @@ require_relative 'party_data'
 
 module Usps
   module Imis
-    # DEV
+    # Configured accessor for a specific Business Object
+    #
     class BusinessObject
       include Requests
 
@@ -47,12 +48,12 @@ module Usps
 
       # Support passthrough for Api#with
       #
-      def with(imis_id, &)
+      def with(*, **, &)
         # Bring into local scope
         wrapper_business_object_name = business_object_name
         wrapper_ordinal = ordinal
 
-        api.with(imis_id) do
+        api.with(*, **) do
           on(wrapper_business_object_name, ordinal: wrapper_ordinal, &)
         end
       end
@@ -136,6 +137,15 @@ module Usps
       def delete = submit(uri, authorize(http_delete)).body == '' # rubocop:disable Naming/PredicateMethod
       alias destroy delete
 
+      # Build a blank object for the current iMIS ID
+      #
+      def blank_object(&) = BlankObject.new(self).build(&)
+
+      # Create a business object for the current member, starting with a blank object and building properties
+      #
+      def post_from_blank(&) = post(blank_object(&))
+      alias create_from_blank post_from_blank
+
       # Ruby 3.5 instance variable filter
       #
       def instance_variables_to_inspect = instance_variables - %i[@api @logger]
@@ -153,9 +163,9 @@ module Usps
       #
       def id_for_uri(id = nil)
         return CGI.escape(id) unless id.nil?
-        return CGI.escape("~#{api.imis_id}|#{ordinal}") if ordinal
+        return CGI.escape("~#{api.record_id}|#{ordinal}") if ordinal
 
-        api.imis_id.to_s
+        api.record_id.to_s
       end
 
       # Manually assemble the matching data structure, with fields in the correct order

data/lib/usps/imis/data.rb

@@ -14,11 +14,15 @@ module Usps
       #
       def entity = raw['EntityTypeName']
 
-      # Access the iMIS ID property
+      # Access the iMIS ID (i.e. Party ID) property
       #
-      def imis_id = self['ID'].to_i
+      def imis_id = raw['PrimaryParentIdentity']['IdentityElements']['$values'].first.to_i
       alias id imis_id
 
+      # Access the Record ID property
+      #
+      def record_id = raw['Identity']['IdentityElements']['$values'].first.to_i
+
       # Access the Ordinal identifier property (if present)
       #
       def ordinal = self['Ordinal']&.to_i
@@ -47,7 +51,7 @@ module Usps
     private
 
       def pretty_print_data
-        { entity:, imis_id:, ordinal: }.compact
+        { entity:, imis_id:, record_id: (record_id unless record_id == imis_id), ordinal: }.compact
       end
 
       def property_values = raw['Properties']['$values']

data/lib/usps/imis/error.rb

@@ -18,7 +18,7 @@ module Usps
         super(message)
         @metadata = metadata
 
-        Imis.logger(self.class.name).error self
+        Imis.logger(self.class.name).multiline(self.message, level: :error)
       end
 
       # Additional metadata to include in Bugsnag reports

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

@@ -3,12 +3,12 @@
 module Usps
   module Imis
     module Errors
-      # Exception raised when attempting to change the iMIS ID while it is locked
+      # Exception raised when attempting to change the iMIS ID or Record ID while it is locked
       #
       class LockedIdError < Error
         def initialize = super(message)
 
-        def message = 'Cannot change iMIS ID while locked'
+        def message = 'Cannot change iMIS or Record ID while locked'
       end
     end
   end

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

@@ -49,8 +49,8 @@ module Usps
         #
         def message
           [
-            "#{self.class.name}: [#{status.to_s.upcase}] The iMIS API returned an error.",
-            (metadata.inspect if metadata != {}),
+            "[#{status.to_s.upcase}] The iMIS API returned an error.",
+            (metadata.inspect if metadata?),
             body
           ].compact.join("\n")
         end
@@ -61,6 +61,8 @@ module Usps
           { api: { status:, body: } }
         end
 
+        def metadata? = metadata != {} && !metadata.nil?
+
         def status
           @status ||=
             case response.code
@@ -93,7 +95,7 @@ module Usps
             response_body['error_description']
           else
             # Unknown error type: just use the raw response
-            response.body
+            JSON.pretty_generate(response.body)
           end
         end
       end

data/lib/usps/imis/logger_helpers.rb

@@ -5,12 +5,15 @@ module Usps
     # Formatted logger helpers
     #
     module LoggerHelpers
-      def multiline(string)
-        string.split("\n").each { |line| debug(line) }
+      def multiline(string, level: :debug)
+        string.split("\n").each { public_send(level, it) }
       end
 
       def json(data)
-        tagged('JSON') { multiline(JSON.pretty_generate(data)) }
+        hash = data.is_a?(String) ? JSON.parse(data) : data
+        tagged('JSON') { multiline(JSON.pretty_generate(hash)) }
+      rescue StandardError
+        multiline(data)
       end
     end
   end

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

@@ -14,9 +14,10 @@ module Usps
         #
         attr_reader :logger
 
-        def initialize(api = nil, imis_id: nil)
+        def initialize(api = nil, imis_id: nil, record_id: nil)
           @api = api || Api.new
           @api.imis_id = imis_id if imis_id
+          @api.record_id = record_id if record_id
           @logger ||= Imis.logger('Panel')
         end
 
@@ -30,7 +31,7 @@ module Usps
         #
         # @return [Usps::Imis::Data, Array<Usps::Imis::Data>] Response data from the API
         #
-        def get(ordinal, *fields) = api.on(business_object, ordinal:).get(*fields)
+        def get(ordinal, *fields) = api.on(business_object_name, ordinal:).get(*fields)
         alias read get
 
         # Get a single named field from a Panel for the current member
@@ -40,7 +41,7 @@ module Usps
         #
         # @return Response data field value from the API
         #
-        def get_field(ordinal, field) = api.on(business_object, ordinal:).get_field(field)
+        def get_field(ordinal, field) = api.on(business_object_name, ordinal:).get_field(field)
         alias fetch get_field
         alias [] get_field
 
@@ -51,7 +52,7 @@ module Usps
         #
         # @return [Array] Response data from the API
         #
-        def get_fields(ordinal, *fields) = api.on(business_object, ordinal:).get_fields(*fields)
+        def get_fields(ordinal, *fields) = api.on(business_object_name, ordinal:).get_fields(*fields)
         alias fetch_all get_fields
 
         # Update a single named field on a business object for the current member
@@ -62,7 +63,7 @@ module Usps
         #
         # @return [Usps::Imis::Data] Response data from the API
         #
-        def put_field(ordinal, field, value) = api.on(business_object, ordinal:).put_field(field, value)
+        def put_field(ordinal, field, value) = api.on(business_object_name, ordinal:).put_field(field, value)
         alias []= put_field
 
         # Update only specific fields on a Panel for the current member
@@ -72,7 +73,7 @@ module Usps
         #
         # @return [Usps::Imis::Data] Response data from the API
         #
-        def put_fields(ordinal, fields) = api.on(business_object, ordinal:).put_fields(fields)
+        def put_fields(ordinal, fields) = api.on(business_object_name, ordinal:).put_fields(fields)
         alias patch put_fields
 
         # Update an existing object in the Panel
@@ -82,7 +83,7 @@ module Usps
         #
         # @return [Usps::Imis::Data] Response data from the API
         #
-        def put(data) = api.on(business_object, ordinal: data[:ordinal]).put(payload(data))
+        def put(data) = api.on(business_object_name, ordinal: data[:ordinal]).put(payload(data))
         alias update put
 
         # Create a new object in the Panel
@@ -91,7 +92,7 @@ module Usps
         #
         # @return [Usps::Imis::Data] Response data from the API
         #
-        def post(data) = api.on(business_object).post(payload(data))
+        def post(data) = api.on(business_object_name).post(payload(data))
         alias create post
 
         # Remove a specific object from the Panel
@@ -100,58 +101,24 @@ module Usps
         #
         # @return [true] Only on success response (i.e. blank string from the API)
         #
-        def delete(ordinal) = api.on(business_object, ordinal:).delete
+        def delete(ordinal) = api.on(business_object_name, ordinal:).delete
         alias destroy delete
 
+        def business_object_name
+          raise Errors::PanelUnimplementedError.from(self.class.name, 'business_object_name')
+        end
+
         # Ruby 3.5 instance variable filter
         #
         def instance_variables_to_inspect = instance_variables - %i[@api @logger]
 
       private
 
-        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(&))
+        def build_payload(data, &) = BlankObject.new(self, data[:ordinal]).build(&)
       end
     end
   end

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

@@ -6,16 +6,12 @@ module Usps
       # Panel for accessing the Educational completions business object
       #
       class Education < BasePanel
-      private
+        def business_object_name = 'ABC_ASC_Educ'
 
-        def business_object
-          'ABC_ASC_Educ'
-        end
+      private
 
         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]

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

@@ -6,16 +6,12 @@ module Usps
       # Panel for accessing the annual VSC completed counts business object
       #
       class Vsc < BasePanel
-      private
+        def business_object_name = 'ABC_ASC_Vessel_Safety_Checks'
 
-        def business_object
-          'ABC_ASC_Vessel_Safety_Checks'
-        end
+      private
 
         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'

data/lib/usps/imis/properties.rb

@@ -7,7 +7,10 @@ module Usps
     class Properties
       # Build the data for a new Properties field
       #
-      def self.build(&) = new.build(&)
+      # @param id [String] iMIS ID to include in the properties before running the block
+      # @param ordinal [String] Ordinal to include in the properties before running the block
+      #
+      def self.build(id = nil, ordinal = nil, &) = new.build(id, ordinal, &)
 
       # Wrap value in the API-internal type structure
       #
@@ -24,7 +27,15 @@ module Usps
 
       # Build the data for the Properties field
       #
-      def build
+      # @param id [String] iMIS ID to include in the properties before running the block
+      # @param ordinal [String] Ordinal to include in the properties before running the block
+      #
+      def build(id = nil, ordinal = nil)
+        @properties ||= []
+
+        add('ID', id) if id
+        add('Ordinal', ordinal) if ordinal
+
         yield(self)
 
         {
@@ -38,7 +49,6 @@ module Usps
       # Add an individual property to the field
       #
       def add(name, value)
-        @properties ||= []
         @properties << {
           '$type' => 'Asi.Soa.Core.DataContracts.GenericPropertyData, Asi.Contracts',
           'Name' => name,

data/lib/usps/imis/requests.rb

@@ -41,7 +41,7 @@ module Usps
         logger.info 'Submitting request to iMIS'
         logger.tagged('Request') do
           logger.debug "#{request.class.name.demodulize.upcase} #{uri}"
-          logger.multiline sanitized_request_body(request)
+          logger.json sanitized_request_body(request)
 
           client(uri).request(request).tap do |result|
             raise Errors::ResponseError.from(result) unless result.is_a?(Net::HTTPSuccess)

data/lib/usps/imis/version.rb

@@ -2,6 +2,6 @@
 
 module Usps
   module Imis
-    VERSION = '0.11.26'
+    VERSION = '0.11.28'
   end
 end

data/lib/usps/imis.rb

@@ -22,6 +22,7 @@ require_relative 'imis/config'
 require_relative 'imis/error'
 require_relative 'imis/api'
 require_relative 'imis/properties'
+require_relative 'imis/blank_object'
 require_relative 'imis/panels'
 require_relative 'imis/mocks'
 require_relative 'imis/version'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: usps-imis-api
 version: !ruby/object:Gem::Version
-  version: 0.11.26
+  version: 0.11.28
 platform: ruby
 authors:
 - Julian Fiander
@@ -77,6 +77,7 @@ files:
 - lib/usps/imis.rb
 - lib/usps/imis/api.rb
 - lib/usps/imis/base_data.rb
+- lib/usps/imis/blank_object.rb
 - lib/usps/imis/business_object.rb
 - lib/usps/imis/command_line.rb
 - lib/usps/imis/command_line/interface.rb