usps-imis-api 0.13.9 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fca31f9bb4d8d748374f47185b5110c95b6f80088dc682cb44613e3629199319
-  data.tar.gz: 742c11021ae6b6446bc29e3b5b29fc99bf151683e5607e2ca2fcb12d5b19f569
+  metadata.gz: b8075b08c9527b8309ac2e784db46c2e9dc6d922b5a4ee7392fbb493ece0bdb8
+  data.tar.gz: 1f37a85470c68ee132e42e10f26cf3d6be97700d160fbd7479d14bdcd3f23474
 SHA512:
-  metadata.gz: 7b5bc685dec91340b99d60d5cf199d41b7dbf5750a5469b25dc46f445c0bb180b1d77bc7cd5e244ee68f88e93f9332083eea11fa19516dbd8d84e572177a35b5
-  data.tar.gz: 3fc9d20a2d78f4cc0ced1c3552db53e08106bb8ab74cd1384897f7faee5b7091a7b411b0ba5b6c91c06a3dcc01d1b94f5f315d746d89b81f9757f98129fda2df
+  metadata.gz: 158b6e90ec01dc5b1d8f3f9ddad0d91434ba86facfe05b1547aaa4ba3a16679092f6e4c4a83d6c96d3ff1e02724bd1c8d8e4aa42eb45782019f18989036842ba
+  data.tar.gz: 298cf14dee964a5c6c1029a68a629b3e0cd921ec7f3ff396947919269686c3233a160fe48d36eb7058431f7e8d5be8b9bd174c911c23f4cdf5bed836ea11b8b2

data/lib/usps/imis/api.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require_relative 'requests'
 require_relative 'business_object'
 require_relative 'mapper'
 require_relative 'query'
@@ -98,7 +97,7 @@ module Usps
 
         raise Errors::LockedIdError if lock_imis_id
 
-        @record_id = id.to_i
+        @record_id = format_id(id)
       end
 
       # Currently selected Record ID for API requests
@@ -124,7 +123,7 @@ module Usps
         party = query('Party', UniformId: net_contact_data.id).one
         raise Errors::NotFoundError, 'Member not found' if party.nil?
 
-        self.imis_id = party.id
+        self.imis_id = party.imis_id
       rescue Errors::ResponseError
         raise Errors::NotFoundError, 'Member not found'
       end
@@ -231,12 +230,16 @@ module Usps
       #
       delegate :update, to: :mapper
 
-      # List of available Business Object names
+      # Names of every Business Object that has a registered +Models::Base+
+      # wrapper, partitioned by whether the name carries an +ABC+ prefix.
+      # Sourced from the in-process registry — no HTTP — so this answers
+      # "what does the gem know how to wrap?", not "what does the server
+      # expose?". Anything not listed still round-trips as raw +Data+.
       #
-      # @return [Hash<Symbol, Array<String>>] Grouped available Business Objects
+      # @return [Hash<Symbol, Array<String>>] Grouped registered Business Objects
       #
       def business_objects
-        abc, other = query('BOEntityDefinition').map(&:entity).partition { it.include?('ABC') }
+        abc, other = Models.entity_names.partition { it.include?('ABC') }
 
         { abc:, other: }
       end

data/lib/usps/imis/base_data.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require 'pp'
-require 'stringio'
-
 module Usps
   module Imis
     # Base class for API data response wrappers

data/lib/usps/imis/blank_object.rb

@@ -1,9 +1,5 @@
 # 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

data/lib/usps/imis/business_object.rb

@@ -1,9 +1,5 @@
 # frozen_string_literal: true
 
-require_relative 'requests'
-require_relative 'data'
-require_relative 'party_data'
-
 module Usps
   module Imis
     # Configured accessor for a specific Business Object
@@ -216,10 +212,9 @@ module Usps
         raise Errors::MissingIdError if api.imis_id.nil?
 
         response = submit(authorize(http_get))
-        klass = business_object_name == 'Party' ? PartyData : Data
-        result = klass.from_json(response.body)
+        result = parse_response(response)
         logger.json result
-        result
+        wrap_data(result)
       end
 
       # Upload an object to the API
@@ -229,10 +224,22 @@ module Usps
 
         request.body = JSON.dump(body)
         response = submit(authorize(request))
-        klass = business_object_name == 'Party' ? PartyData : Data
-        result = klass.from_json(response.body)
+        result = parse_response(response)
         logger.json result
-        result
+        wrap_data(result)
+      end
+
+      def parse_response(response)
+        klass = business_object_name == 'Party' ? PartyData : Data
+        klass.from_json(response.body)
+      end
+
+      # If a +Model+ subclass is registered for this Business Object, wrap the
+      # parsed +Data+ / +PartyData+ in it. Otherwise pass it through unchanged.
+      #
+      def wrap_data(data)
+        model_klass = Models.for_entity(business_object_name)
+        model_klass ? model_klass.from_data(data, api:) : data
       end
 
       def block_not_supported!

data/lib/usps/imis/command_line/formatters.rb

@@ -15,9 +15,11 @@ module Usps
 
       private
 
-        # rubocop:disable Metrics/MethodLength
+        # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
         def simplify(data)
           data = data.to_a if data.is_a?(Query)
+          data = data.map { it.is_a?(Models::Base) ? it.data : it } if data.is_a?(Array)
+          data = data.data if data.is_a?(Models::Base)
 
           return simplify_raw(data) if force_raw_output?
 
@@ -37,7 +39,7 @@ module Usps
             data
           end
         end
-        # rubocop:enable Metrics/MethodLength
+        # rubocop:enable Metrics/MethodLength,Metrics/AbcSize
 
         def simplify_raw(data)
           return data.raw if data.is_a?(BaseData)
@@ -72,7 +74,7 @@ module Usps
             end
           end
 
-          return json(value) if @options[:json]
+          return json(value) if @options[:force_json]
           return value if value.is_a?(String) || value.is_a?(Symbol) || value.nil?
 
           json(value)

data/lib/usps/imis/command_line/interface.rb

@@ -111,6 +111,7 @@ module Usps
         # Supports YAML or JSON config data
         #
         def configure!
+          Usps::Imis::Config.load_dotenv!
           return if config_path.nil?
 
           config_data = YAML.safe_load_file(config_path)
@@ -171,6 +172,7 @@ module Usps
         def handle_exception!(exception)
           raise(exception) if options[:trace] || ENV.fetch('TESTING', false) || ENV.fetch('CI', false)
 
+          exception.log_error if exception.is_a?(Imis::Error)
           exit(2)
         end
       end

data/lib/usps/imis/command_line/options.yml

@@ -112,10 +112,10 @@ Options:
       - short: S
     jsonl:
       - Format array output as JSONL
-      - short: j
-    json:
-      - Format string output also as JSON (i.e. quoted)
       - short: J
+    force_json:
+      - Force JSON-compliant output (i.e. quote raw strings) for piping into %{cyan:jq}
+      - short: j
 
   Configuration:
     config:

data/lib/usps/imis/command_line.rb

@@ -13,7 +13,6 @@ module Usps
   end
 end
 
+# Load OptionsParserConfig before OptionsParser
 require_relative 'command_line/options_parser_config'
-require_relative 'command_line/help'
-require_relative 'command_line/options_parser'
-require_relative 'command_line/interface'
+Dir[File.join(__dir__, 'command_line', '*.rb')].each { require_relative it }

data/lib/usps/imis/config.rb

@@ -1,10 +1,6 @@
 # frozen_string_literal: true
 
-require 'fileutils'
-
 require_relative 'logger'
-require_relative 'logger_formatter'
-require_relative 'logger_helpers'
 
 module Usps
   module Imis
@@ -15,10 +11,20 @@ module Usps
       IMIS_ROOT_URL_DEV = 'https://abcdev.imiscloud.com'
       DEFAULT_GLOBAL_LOG_PATH = '/var/log/imis/imis.log'
       REQUIRED = %w[username password].freeze
-      OPTIONAL = %w[environment logger_file global_log_path].freeze
+      OPTIONAL = %w[environment logger_file global_log_path pretty_print_api].freeze
       SETTABLE = (REQUIRED + OPTIONAL).freeze
 
-      attr_accessor :username, :password
+      class << self
+        # Opt-in +.env+ loader. The gem no longer auto-loads dotenv on require —
+        # call this from your app boot (or before +Imis.configure+) if you want
+        # +ENV+ populated from +.env+. Idempotent.
+        #
+        def load_dotenv!
+          Dotenv.load
+        end
+      end
+
+      attr_accessor :username, :password, :pretty_print_api
       attr_reader :environment, :logger, :logger_level, :logger_file
 
       def initialize

data/lib/usps/imis/data.rb

@@ -1,10 +1,5 @@
 # frozen_string_literal: true
 
-require 'pp'
-require 'stringio'
-
-require_relative 'base_data'
-
 module Usps
   module Imis
     # Convenience wrapper for accessing specific properties within an API data response

data/lib/usps/imis/dependencies.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Single source of truth for every external (gem + stdlib) dependency the library uses.
+#
+# The Command Line alternate entry declares its own additional dependencies.
+
+# Stdlib
+require 'cgi'
+require 'fileutils'
+require 'json'
+require 'logger'
+require 'net/https'
+require 'pp'
+require 'stringio'
+require 'time'
+require 'yaml'
+
+# ActiveSupport / ActiveModel
+require 'active_model'
+require 'active_model/type'
+require 'active_support/concern'
+require 'active_support/core_ext/class/attribute'
+require 'active_support/core_ext/enumerable'
+require 'active_support/core_ext/module/delegation'
+require 'active_support/core_ext/object/to_query'
+require 'active_support/core_ext/string/inflections'
+require 'active_support/duration'
+require 'active_support/isolated_execution_state' # Fix constant loading issue with TaggedLogging
+require 'active_support/string_inquirer'
+require 'active_support/tagged_logging'
+
+# Others
+require 'dotenv'

data/lib/usps/imis/error.rb

@@ -17,8 +17,6 @@ module Usps
       def initialize(message, metadata = {})
         super(message)
         @metadata = metadata
-
-        log_error
       end
 
       # Additional metadata to include in Bugsnag reports
@@ -34,27 +32,22 @@ module Usps
         metadata == {} ? {} : base_metadata
       end
 
+      # Log the exception message at error level. Callers (e.g. the CLI's
+      # top-level handler) invoke this when an exception escapes user code;
+      # not called from +initialize+ so that internally-rescued exceptions
+      # (e.g. +Models::Base#identity_from_data+) don't pollute the log.
+      #
+      def log_error
+        Imis.logger(self.class.name).multiline(message, level: :error)
+      end
+
     private
 
       def base_metadata
         { api: metadata }
       end
-
-      def log_error
-        Imis.logger(self.class.name).multiline(message, level: :error)
-      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/missing_id_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'
-require_relative 'errors/pattern_matching_error'
-require_relative 'errors/command_line_error'
+Dir[File.join(__dir__, 'errors', '*.rb')].each { require_relative it }

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    module Errors
+      # Exception raised when attempting to +find+ an embedded model
+      #
+      class EmbeddedModelFindError < Error
+        attr_reader :name
+
+        def initialize(name)
+          @name = name
+          super(message)
+        end
+
+        def message = "Cannot `find` an embedded model: #{name}"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    module Errors
+      # Raised when +Models::Base#save+ would build an empty payload — i.e. the
+      # model has no persistable attributes to send. Currently fires when every
+      # changed attribute resolves to a dotted source (which the generic
+      # +payload_for+ cannot serialize) or to +nil+.
+      #
+      class EmptyPayloadError < Error
+        attr_reader :model_class
+
+        def initialize(model_class)
+          @model_class = model_class
+          super(message)
+        end
+
+        def message = "Cannot save #{model_class}: no persistable attributes in payload"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    module Errors
+      # Raised when +Party#updated_party_payload+ tries to write a property
+      # field whose named slot isn't present in the loaded raw payload. The
+      # gem doesn't support creating Party records — every Party model is
+      # expected to start from a fully-loaded payload — so a missing slot
+      # indicates either a malformed payload or a typo in the +source:+.
+      #
+      class MissingPartyFieldError < Error
+        attr_reader :field
+
+        def initialize(field)
+          @field = field
+          super(message)
+        end
+
+        def message = "Party payload has no property entry named #{field.inspect}"
+      end
+    end
+  end
+end

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

@@ -13,8 +13,6 @@ module Usps
           super('Unable to match pattern from options', { options: })
         end
 
-      private
-
         def log_error
           Imis.logger(self.class.name).error('Unable to match pattern from options:')
           Imis.logger(self.class.name).json(options, level: :error)

data/lib/usps/imis/logger.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require_relative 'logger_formatter'
-require_relative 'logger_helpers'
-
 module Usps
   module Imis
     # Formatted logger with additional helpers

data/lib/usps/imis/models/associations/individual_demog.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    module Models
+      class IndividualDemog
+        belongs_to :party
+      end
+    end
+  end
+end

data/lib/usps/imis/models/base/finders.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    module Models
+      class Base
+        # ActiveRecord-style finder methods
+        #
+        module Finders
+          # Fetch all records
+          #
+          def all(api: Models.default_api, **)
+            raise Errors::EmbeddedModelFindError, name if business_object_name.nil?
+
+            api.query(business_object_name, **)
+          end
+          alias where all
+
+          # Fetch a record by +imis_id+. For multi-record Business Objects, pass
+          # +record_id:+, and for panels pass +ordinal:+. Always wraps the request in
+          # +Api#with+ so caller api state is preserved.
+          #
+          # @param imis_id [String, Integer] The iMIS ID to use for the request
+          # @param child_id [String, Integer] Input for +record_id+ or +ordinal+, based on Model config
+          #
+          # @raise [Errors::NotFoundError] when the Business Object returns no record
+          # @raise [Errors::EmbeddedModelFindError] when called on an embedded (non-Business Object) Model
+          #
+          def find(imis_id, child_id = nil, api: Models.default_api, record_id: nil, ordinal: nil)
+            raise Errors::EmbeddedModelFindError, name if business_object_name.nil?
+
+            record_id, ordinal = resolve_find_key(child_id, record_id, ordinal)
+
+            bon = business_object_name
+            # Pin record_id explicitly: api.record_id= is a no-op on nil, so a
+            # stale @record_id from a prior call would otherwise leak into the
+            # URL (e.g. wrong parent in `~{record_id}|{ordinal}` for panels).
+            result = api.with(imis_id, record_id: record_id || imis_id) { on(bon, ordinal: ordinal).get }
+            raise Errors::NotFoundError, "#{name} #{imis_id} not found" if result.nil?
+
+            result
+          end
+
+          # Look up a record via an IQA-style query against the Business Object. Returns
+          # +nil+ if no record matches (mirroring +ActiveRecord::Base.find_by+).
+          #
+          def find_by(api: Models.default_api, **conditions)
+            raise Errors::EmbeddedModelFindError, name if business_object_name.nil?
+            raise ArgumentError, "#{name}.find_by requires at least one condition" if conditions.empty?
+
+            return unless (result = api.query(business_object_name, **conditions).one)
+
+            # +Query#wrap+ already wraps registered Business Objects as Models, so the +is_a?+
+            # branch handles the common case. The +from_data+ fallback is defensive: it catches
+            # non-model-defined Business Objects that may exist on the server but lack a registered
+            # wrapper.
+            #
+            result.is_a?(self) ? result : from_data(result, api:)
+          end
+
+          # Raising form of +find_by+.
+          #
+          def find_by!(api: Models.default_api, **conditions)
+            find_by(api:, **conditions) || raise(Errors::NotFoundError, "#{name} not found by #{conditions.inspect}")
+          end
+
+        private
+
+          # Select the correct IDs for the request, based on Model config and what was provided
+          #
+          def resolve_find_key(child_id, record_id, ordinal)
+            return [record_id, ordinal] if child_id.nil?
+
+            find_key == :ordinal ? [record_id, ordinal || child_id] : [record_id || child_id, ordinal]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/usps/imis/models/base/persistence.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    module Models
+      class Base
+        # ActiveRecord-style persistence for +Models::Base+ subclasses:
+        # +save+ / +save!+ on dirty instances, +update+ / +update!+ for
+        # assign-then-save, plus class-level +create+ / +create!+ shortcuts.
+        #
+        module Persistence
+          extend ActiveSupport::Concern
+
+          class_methods do
+            # Build a new instance with attributes and persist it. Returns the
+            # instance whether or not the save succeeded — check +persisted?+.
+            #
+            def create(**) = new(**).tap(&:save)
+
+            # Build a new instance with attributes and persist it, raising if
+            # validation fails.
+            #
+            def create!(**) = new(**).tap(&:save!)
+          end
+
+          # Save dirty changes to the iMIS API. Issues +put+ for persisted
+          # instances (loaded via +from_data+) and +post+ for new instances.
+          # Reloads attributes from the response, clearing dirty state.
+          #
+          # @return [Boolean] +true+ on success, +false+ if validation failed.
+          #
+          def save
+            return false unless valid?
+
+            result = persisted? ? perform_update : perform_create
+            load_from_data(result.is_a?(Models::Base) ? result.data : result)
+            true
+          rescue Errors::EmptyPayloadError => e
+            errors.add(:base, e.message)
+            false
+          end
+
+          # Raising form of +save+.
+          #
+          def save! = save || raise(ActiveModel::ValidationError, self)
+
+          # Assign attributes and +save+. Returns +true+ / +false+ matching +save+.
+          #
+          def update(**)
+            assign_attributes(**)
+            save
+          end
+
+          # Assign attributes and +save!+. Raises on validation failure.
+          #
+          def update!(**)
+            assign_attributes(**)
+            save!
+          end
+
+        private
+
+          # find / belongs_to dispatch through Api#with, which restores prior
+          # api state on block exit — so by the time .save fires, api.imis_id
+          # is back to whatever it was (typically nil). Re-pin the request
+          # scope here from the model's own identity, mirroring Finders#find.
+          #
+          def perform_create
+            bon = self.class.business_object_name
+            payload = ->(accessor) { payload_for(accessor) }
+            api.with(imis_id, record_id: record_id || imis_id) do
+              accessor = on(bon)
+              accessor.post(payload.call(accessor))
+            end
+          end
+
+          def perform_update
+            bon = self.class.business_object_name
+            ord = ordinal
+            payload = ->(accessor) { payload_for(accessor) }
+            api.with(imis_id, record_id: record_id || imis_id) do
+              accessor = on(bon, ordinal: ord)
+              accessor.put(payload.call(accessor))
+            end
+          end
+
+          # Maps snake_case attribute names back to their iMIS source names
+          # and builds the GenericEntityData envelope via +BlankObject+. On
+          # update, only changed attributes are sent; on create, all set
+          # attributes are.
+          #
+          def payload_for(accessor)
+            fields = persisted? ? changes.transform_values(&:last) : attributes
+            named  = fields.filter_map { |attr, value| named_field(attr, value) }.to_h
+            raise Errors::EmptyPayloadError, self.class if named.empty?
+
+            BlankObject.new(accessor, ordinal&.to_s).build(named)
+          end
+
+          def named_field(attr, value)
+            source = self.class.imis_attribute_map[attr.to_sym]
+            return if source.nil? || source.include?('.') || value.nil?
+
+            [source, value]
+          end
+        end
+      end
+    end
+  end
+end