usps-imis-api 0.6.15 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ece5a19e925e1ef85b9e54b1d8fe7139c4015b0a1fe7ddcb602e172fbb50cab
-  data.tar.gz: 723eb4ccbf3b0c86c3f309c83d32d2b892420c688fd1f8aa2bfedcc47d61d2a9
+  metadata.gz: bc6237ee6d52c0fdfc8cd33809a90600b68a19926490facab194e751b8c983d3
+  data.tar.gz: f66d10f8a53e2df13e42a96fec6a4fc2cb61d798f80dbe7ddc88cf2f84418277
 SHA512:
-  metadata.gz: fbca9aeda6a7a4e7fc6701c2767da349ab49e6b9126b36ea0a6225b4c18b2c7970dc22390ddabfbf571411d76b86ab2b37bbde79f471f4b5a3ceba9d271fdd5c
-  data.tar.gz: 3b09c75a050ad32e8077d9bc07772d91bb37a7e4628734c0159cb05a206f7f9128059532e22e90f014f07041f2ac87d0d37c2d7878845069c1220ec221cb4e69
+  metadata.gz: 16b7a7e05c2fa1cb5d3e2de1604a4a06e5d551a650f7ee451662afa7f43b2b1917f0be04a2c3d4af063a18c0b22515d304bcc25afca79e9214e76542d3b39438
+  data.tar.gz: bfe78effec93b84b65963c54decb29ae114e10231e537ad216d1c3d2b250348474efeb0bd20b5f5759a7b6440eca6b28660a10c94d617c90fa70708c1c85727e

data/.rubocop.yml

@@ -1,4 +1,4 @@
-require:
+plugins:
   - rubocop-rspec
 
 AllCops:
@@ -37,8 +37,6 @@ Lint/UnusedMethodArgument:
   Enabled: true
 Lint/UselessAssignment:
   Enabled: true
-Lint/ItWithoutArgumentsInBlock:
-  Enabled: false
 
 Metrics/MethodLength:
   Enabled: true

data/Gemfile.lock

@@ -1,37 +1,36 @@
 PATH
   remote: .
   specs:
-    usps-imis-api (0.6.15)
+    usps-imis-api (0.7.0)
       activesupport (~> 8.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (8.0.3)
+    activesupport (8.1.0)
       base64
-      benchmark (>= 0.3)
       bigdecimal
       concurrent-ruby (~> 1.0, >= 1.3.1)
       connection_pool (>= 2.2.5)
       drb
       i18n (>= 1.6, < 2)
+      json
       logger (>= 1.4.2)
       minitest (>= 5.1)
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
       uri (>= 0.13.1)
-    ast (2.4.2)
+    ast (2.4.3)
     base64 (0.3.0)
-    benchmark (0.4.1)
     bigdecimal (3.3.1)
     concurrent-ruby (1.3.5)
     connection_pool (2.5.4)
     date (3.4.1)
-    diff-lcs (1.5.1)
+    diff-lcs (1.6.2)
     docile (1.4.1)
-    dotenv (3.1.4)
+    dotenv (3.1.8)
     drb (2.2.3)
-    erb (5.0.3)
+    erb (5.1.1)
     i18n (1.14.7)
       concurrent-ruby (~> 1.0)
     io-console (0.8.1)
@@ -39,70 +38,77 @@ GEM
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.7.2)
-    language_server-protocol (3.17.0.3)
+    json (2.15.1)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
     logger (1.7.0)
     minitest (5.26.0)
-    parallel (1.26.3)
-    parser (3.3.5.0)
+    parallel (1.27.0)
+    parser (3.3.9.0)
       ast (~> 2.4.1)
       racc
     pp (0.6.3)
       prettyprint
     prettyprint (0.2.0)
+    prism (1.6.0)
     psych (5.2.6)
       date
       stringio
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.2.1)
+    rake (13.3.0)
     rdoc (6.15.0)
       erb
       psych (>= 4.0.0)
       tsort
-    regexp_parser (2.9.2)
+    regexp_parser (2.11.3)
     reline (0.6.2)
       io-console (~> 0.5)
-    rspec (3.13.0)
+    rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.1)
+    rspec-core (3.13.6)
       rspec-support (~> 3.13.0)
-    rspec-expectations (3.13.3)
+    rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.2)
+    rspec-mocks (3.13.6)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.1)
-    rubocop (1.66.1)
+    rspec-support (3.13.6)
+    rubocop (1.81.6)
       json (~> 2.3)
-      language_server-protocol (>= 3.17.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
       parallel (~> 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 2.4, < 3.0)
-      rubocop-ast (>= 1.32.2, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.32.3)
-      parser (>= 3.3.1.0)
-    rubocop-rspec (3.1.0)
-      rubocop (~> 1.61)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.47.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    rubocop-rspec (3.7.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.72, >= 1.72.1)
     ruby-progressbar (1.13.0)
     securerandom (0.4.1)
     simplecov (0.22.0)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
-    simplecov-html (0.13.1)
+    simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
     stringio (3.1.7)
     tsort (0.2.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    unicode-display_width (2.6.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.1.0)
     uri (1.0.4)
 
 PLATFORMS

data/Readme.md

@@ -77,33 +77,37 @@ You can also manually set the current ID, if you already have it for a given mem
 api.imis_id = imis_id
 ```
 
-### GET
+### Business Object and Panel Actions
+
+Business Objects and Panels support the following actions.
+
+Panels require passing in the ordinal identifier as an argument, except for `POST`.
+
+#### GET
 
 To fetch member data, run e.g.:
 
 ```ruby
-api.imis_id = 31092
-
 data = api.on('ABC_ASC_Individual_Demog').get
 ```
 
-### GET Field
+Alias: `read`
+
+#### GET Field
 
 To fetch a specific field from member data, run e.g.:
 
 ```ruby
-api.imis_id = 31092
-
 tot_mms = api.on('ABC_ASC_Individual_Demog').get_field('TotMMS')
 ```
 
-### PUT Fields
+Alias: `fetch`
+
+#### PUT Fields
 
 To update member data, run e.g.:
 
 ```ruby
-api.imis_id = 31092
-
 data = { 'MMS_Updated' => Time.now.strftime('%Y-%m-%dT%H:%M:%S'), 'TotMMS' => new_total }
 update = api.on('ABC_ASC_Individual_Demog').put_fields(data)
 ```
@@ -111,19 +115,23 @@ update = api.on('ABC_ASC_Individual_Demog').put_fields(data)
 This method fetches the current data structure, and filters it down to just what you want to
 update, to reduce the likelihood of update collisions or type validation failures.
 
-### PUT
+Alias: `patch`
+
+#### PUT
 
 To update member data, run e.g.:
 
 ```ruby
-api.imis_id = 31092
-
 update = api.on('ABC_ASC_Individual_Demog').put(complete_imis_object)
 ```
 
-This method requires a complete iMIS data structure.
+This method requires a complete iMIS data structure. However, any properties not included will be
+left unmodified (meaning this also effectively handles `PATCH`, though iMIS does not accept that
+HTTP verb).
+
+Alias: `update`
 
-### POST
+#### POST
 
 To create new member data, run e.g.:
 
@@ -133,18 +141,20 @@ created = api.on('ABC_ASC_Individual_Demog').post(complete_imis_object)
 
 This method requires a complete iMIS data structure.
 
-### DELETE
+Alias: `create`
+
+#### DELETE
 
 To remove member data, run e.g.:
 
 ```ruby
-api.imis_id = 31092
-
 api.on('ABC_ASC_Individual_Demog').delete
 ```
 
 This returns a blank string on success.
 
+Alias: `destroy`
+
 ### QUERY
 
 Run an IQA Query
@@ -180,24 +190,27 @@ For supported panels (usually, business objects with composite identity keys), y
 with them in the same general way:
 
 ```ruby
-vsc = Usps::Imis::Panel::Vsc.new
-
-vsc.api.imis_id = 6374
+vsc = Usps::Imis::Panels::Vsc.new(imis_id: 6374)
 
 vsc.get(1417)
 
+vsc.get_field(1417, 'Quantity')
+
 created = vsc.create(certificate: 'E136924', year: 2024, count: 42)
-ordinal = created['Properties']['$values'][1]['Value']['$value']
+ordinal = created['Properties']['$values'].find { it['Name'] == 'Ordinal' }['Value']['$value']
+# ordinal = created['Identity']['IdentityElements']['$values'][1] # Alternative
 
 vsc.update(certificate: 'E136924', year: 2024, count: 43, ordinal: ordinal)
 
+vsc.put_fields(ordinal, 'Quantity' => 44)
+
 vsc.destroy(ordinal)
 ```
 
 If you already have an iMIS ID to work with, you can pass that in immediately:
 
 ```ruby
-vsc = Usps::Imis::Panel::Vsc.new(imis_id: imis_id)
+vsc = Usps::Imis::Panels::Vsc.new(imis_id: imis_id)
 ```
 
 Panels are also accessible directly from the API object:
@@ -249,9 +262,21 @@ end
 api.with(31092).on('ABC_ASC_Individual_Demog').get_field('TotMMS')
 ```
 
+## Test Data Mocking
+
+You can use the provided Business Object Mock to generate stub data for rspec:
+
+```ruby
+allow(api).to(
+  receive(:on).with('ABC_ASC_Individual_Demog').and_return(
+    Usps::Imis::Mocks::BusinessObject.new(TotMMS: 2)
+  )
+)
+```
+
 ## Exception Handling
 
-All internal exceptions inherit from `Usps::Imis::ApiError`.
+All internal exceptions inherit from `Usps::Imis::Error`.
 
 ## Automated Testing and Linting
 

data/lib/usps/imis/api.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require_relative 'requests'
+require_relative 'business_object'
+require_relative 'mapper'
+
 module Usps
   module Imis
     # The core API wrapper
@@ -48,7 +52,7 @@ module Usps
       # @param id [Integer, String] iMIS ID to select for future requests
       #
       def imis_id=(id)
-        raise Error::ApiError, 'Cannot change iMIS ID while locked' if lock_imis_id
+        raise Errors::LockedIdError if lock_imis_id
 
         @imis_id = id&.to_i&.to_s
       end
@@ -60,13 +64,13 @@ module Usps
       # @return [String] Corresponding iMIS ID
       #
       def imis_id_for(certificate)
-        raise Error::ApiError, 'Cannot change iMIS ID while locked' if lock_imis_id
+        raise Errors::LockedIdError if lock_imis_id
 
         begin
           result = query(Imis.configuration.imis_id_query_name, { certificate: })
           @imis_id = result['Items']['$values'][0]['ID']
         rescue StandardError
-          raise Error::ApiError, 'Member not found'
+          raise Errors::NotFoundError, 'Member not found'
         end
       end
 
@@ -132,15 +136,6 @@ module Usps
         results
       end
 
-      # An instance of +BusinessObject+, using this instance as its parent +Api+
-      #
-      # @param business_object_name [String] Name of the business object
-      # @param ordinal [Integer] Ordinal to build override ID param of the URL (e.g. used for Panels)
-      #
-      def business_object(business_object_name, ordinal: nil)
-        BusinessObject.new(self, business_object_name, ordinal:)
-      end
-
       # Run requests as DSL, with specific +BusinessObject+ only maintained for this scope
       #
       # If no block is given, this returns the specified +BusinessObject+.
@@ -149,7 +144,7 @@ module Usps
       # @param ordinal [Integer] Ordinal to build override ID param of the URL (e.g. used for Panels)
       #
       def on(business_object_name, ordinal: nil, &)
-        object = business_object(business_object_name, ordinal:)
+        object = BusinessObject.new(self, business_object_name, ordinal:)
         return object unless block_given?
 
         object.instance_eval(&)
@@ -171,10 +166,7 @@ module Usps
       # +Api+
       #
       def panels
-        @panels ||= Struct.new(:vsc, :education).new(
-          Panel::Vsc.new(self),
-          Panel::Education.new(self)
-        )
+        @panels ||= Panels.all(self)
       end
 
       # Ruby 3.5 instance variable filter

data/lib/usps/imis/business_object.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'requests'
+
 module Usps
   module Imis
     # DEV

data/lib/usps/imis/config.rb

@@ -32,7 +32,7 @@ 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

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_name]}".
+            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

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

@@ -47,7 +47,7 @@ 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
 
@@ -73,11 +73,7 @@ module Usps
           # :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_name: })
       end
     end
   end

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

@@ -0,0 +1,37 @@
+# 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_field(name) = fields[name]
+
+        def get
+          Usps::Imis::Properties.build do |props|
+            fields.each { |name, value| props.add(name, value) }
+          end
+        end
+
+        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
+
+        def put(data) = data
+
+        def post(data) = data
+
+        def 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/{panel → panels}/base_panel.rb

@@ -2,7 +2,7 @@
 
 module Usps
   module Imis
-    module Panel
+    module Panels
       # Base class for configuring Panels
       #
       class BasePanel
@@ -79,11 +79,11 @@ module Usps
       private
 
         def business_object
-          raise Error::ApiError, "#{self.class.name} must implement #business_object"
+          raise Errors::PanelUnimplementedError.from(self.class.name, 'business_object')
         end
 
         def payload(_data)
-          raise Error::ApiError, "#{self.class.name} must implement #payload(data)"
+          raise Errors::PanelUnimplementedError.from(self.class.name, 'payload(data)')
         end
 
         def payload_header(data)

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

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

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

@@ -42,7 +42,7 @@ module Usps
         when Integer then { '$type' => 'System.Int32', '$value' => value }
         when true, false then { '$type' => 'System.Boolean', '$value' => value }
         else
-          raise Error::ApiError, "Unexpected property type: #{value.inspect}"
+          raise Errors::UnexpectedPropertyTypeError.from(value)
         end
       end
     end

data/lib/usps/imis/requests.rb

@@ -25,7 +25,7 @@ module Usps
 
       def submit(uri, request)
         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)
         end
       end
     end

data/lib/usps/imis/version.rb

@@ -2,6 +2,6 @@
 
 module Usps
   module Imis
-    VERSION = '0.6.15'
+    VERSION = '0.7.0'
   end
 end

data/lib/usps/imis.rb

@@ -6,27 +6,17 @@ require 'json'
 require 'time'
 require 'cgi'
 
+require 'active_support/core_ext/string/inflections'
+require 'active_support/core_ext/object/to_query'
 require 'active_support/string_inquirer'
 
-# Extensions
-# :nocov:
-require 'ext/hash' unless defined?(Rails)
-# :nocov:
-
 # 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/properties'
-require_relative 'imis/business_object_mock'
-require_relative 'imis/panel/base_panel'
-require_relative 'imis/panel/vsc'
-require_relative 'imis/panel/education'
+require_relative 'imis/panels'
+require_relative 'imis/mocks'
 
 module Usps
   # API wrapper for interacting with iMIS

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

@@ -31,7 +31,7 @@ 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
@@ -56,7 +56,7 @@ describe Usps::Imis::Api do
     before { api.imis_id = 31092 }
 
     it 'sends an update' do
-      expect(api.business_object('ABC_ASC_Individual_Demog').put_fields('TotMMS' => 15)).to(
+      expect(api.on('ABC_ASC_Individual_Demog').put_fields('TotMMS' => 15)).to(
         be_a(Hash)
       )
     end
@@ -64,7 +64,7 @@ describe Usps::Imis::Api do
     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
@@ -78,8 +78,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
@@ -88,7 +88,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
 
@@ -103,13 +103,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
 

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

@@ -51,7 +51,7 @@ describe Usps::Imis::Config do
 
       it 'raises an error' do
         expect { config.hostname }.to raise_error(
-          Usps::Imis::Error::ApiError, 'Unexpected API environment: nothing'
+          Usps::Imis::Errors::ConfigError, 'Unexpected API environment: nothing'
         )
       end
     end

data/spec/lib/usps/imis/{error/api_error_spec.rb → error_spec.rb}

@@ -2,7 +2,7 @@
 
 require 'spec_helper'
 
-describe Usps::Imis::Error::ApiError do
+describe Usps::Imis::Error do
   it 'builds Bugsnag metadata' do
     error = described_class.new('Example', something: :else)
 

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

@@ -4,7 +4,7 @@ require 'spec_helper'
 
 ApiResponseStub = Struct.new(:code, :body)
 
-describe Usps::Imis::Error::ResponseError do
+describe Usps::Imis::Errors::ResponseError do
   let(:error) { described_class.from(response) }
 
   describe 'error codes' do
@@ -61,7 +61,7 @@ describe Usps::Imis::Error::ResponseError do
     let(:response) { ApiResponseStub.new('500', 'Body of the API response error') }
     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.
         Body of the API response error
       WARNING
     end
@@ -78,7 +78,7 @@ describe Usps::Imis::Error::ResponseError do
     let(:response) { ApiResponseStub.new('500', response_body) }
     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.
         description
       WARNING
     end
@@ -95,7 +95,7 @@ describe Usps::Imis::Error::ResponseError do
     let(:response) { ApiResponseStub.new('500', response_body) }
     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.
         #{response_body}
       WARNING
     end

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

@@ -22,8 +22,8 @@ describe Usps::Imis::Mapper do
 
     it 'raises for unmapped updates' do
       expect { api.mapper.update(something: 'anything') }.to raise_error(
-        Usps::Imis::Error::MapperError,
-        'Unrecognized field: "something". ' \
+        Usps::Imis::Errors::MapperError,
+        %(Mapper does not recognize field: "something".\n) \
         'Please report what data you are attempting to work with to ITCom leadership.'
       )
     end

data/spec/lib/usps/imis/{business_object_mock_spec.rb → mocks/business_object_spec.rb}

@@ -2,7 +2,7 @@
 
 require 'spec_helper'
 
-describe Usps::Imis::BusinessObjectMock do
+describe Usps::Imis::Mocks::BusinessObject do
   let(:mock) { described_class.new(**fields) }
   let(:fields) { { TotMMS: 2 } }
 

data/spec/lib/usps/imis/panels/base_panel_spec.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+module Usps
+  module Imis
+    module Panels
+      class InvalidPanel < BasePanel; end
+
+      class InvalidPanelWithBusinessObject < BasePanel
+      private
+
+        def business_object = 'Something'
+      end
+    end
+  end
+end
+
+describe Usps::Imis::Panels::BasePanel do
+  it 'requires #business_object to be defined' do
+    expect { Usps::Imis::Panels::InvalidPanel.new.get(1) }.to raise_error(
+      Usps::Imis::Errors::PanelUnimplementedError,
+      'Usps::Imis::Panels::InvalidPanel must implement #business_object'
+    )
+  end
+
+  it 'requires #payload(data) to be defined' do
+    expect { Usps::Imis::Panels::InvalidPanelWithBusinessObject.new.create({}) }.to raise_error(
+      Usps::Imis::Errors::PanelUnimplementedError,
+      'Usps::Imis::Panels::InvalidPanelWithBusinessObject must implement #payload(data)'
+    )
+  end
+end

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

@@ -2,7 +2,7 @@
 
 require 'spec_helper'
 
-describe Usps::Imis::Panel::Education do
+describe Usps::Imis::Panels::Education do
   describe 'api example' do
     let(:education) { described_class.new }
 

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

@@ -2,7 +2,7 @@
 
 require 'spec_helper'
 
-describe Usps::Imis::Panel::Vsc do
+describe Usps::Imis::Panels::Vsc do
   let(:vsc) { described_class.new }
 
   let(:details) do

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

@@ -13,7 +13,7 @@ describe Usps::Imis::Properties do
 
   it 'raises an error for unexpected property types' do
     expect { builder.send(:wrap, {}) }.to raise_error(
-      Usps::Imis::Error::ApiError, 'Unexpected property type: {}'
+      Usps::Imis::Errors::UnexpectedPropertyTypeError, 'Unexpected property type: {}'
     )
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: usps-imis-api
 version: !ruby/object:Gem::Version
-  version: 0.6.15
+  version: 0.7.0
 platform: ruby
 authors:
 - Julian Fiander
@@ -41,32 +41,39 @@ files:
 - Readme.md
 - bin/console
 - bin/setup
-- lib/ext/hash.rb
 - lib/usps/imis.rb
 - lib/usps/imis/api.rb
 - lib/usps/imis/business_object.rb
-- lib/usps/imis/business_object_mock.rb
 - lib/usps/imis/config.rb
-- lib/usps/imis/error/api_error.rb
-- lib/usps/imis/error/mapper_error.rb
-- lib/usps/imis/error/response_error.rb
+- lib/usps/imis/error.rb
+- lib/usps/imis/errors/api_error.rb
+- lib/usps/imis/errors/config_error.rb
+- lib/usps/imis/errors/locked_id_error.rb
+- lib/usps/imis/errors/mapper_error.rb
+- lib/usps/imis/errors/not_found_error.rb
+- lib/usps/imis/errors/panel_unimplemented_error.rb
+- lib/usps/imis/errors/response_error.rb
+- lib/usps/imis/errors/unexpected_property_type_error.rb
 - lib/usps/imis/mapper.rb
-- lib/usps/imis/panel/base_panel.rb
-- lib/usps/imis/panel/education.rb
-- lib/usps/imis/panel/vsc.rb
+- lib/usps/imis/mocks.rb
+- lib/usps/imis/mocks/business_object.rb
+- lib/usps/imis/panels.rb
+- lib/usps/imis/panels/base_panel.rb
+- lib/usps/imis/panels/education.rb
+- lib/usps/imis/panels/vsc.rb
 - lib/usps/imis/properties.rb
 - lib/usps/imis/requests.rb
 - lib/usps/imis/version.rb
 - spec/lib/usps/imis/api_spec.rb
-- spec/lib/usps/imis/business_object_mock_spec.rb
 - spec/lib/usps/imis/business_object_spec.rb
 - spec/lib/usps/imis/config_spec.rb
-- spec/lib/usps/imis/error/api_error_spec.rb
-- spec/lib/usps/imis/error/response_error_spec.rb
+- spec/lib/usps/imis/error_spec.rb
+- spec/lib/usps/imis/errors/response_error_spec.rb
 - spec/lib/usps/imis/mapper_spec.rb
-- spec/lib/usps/imis/panel/base_panel_spec.rb
-- spec/lib/usps/imis/panel/education_spec.rb
-- spec/lib/usps/imis/panel/vsc_spec.rb
+- spec/lib/usps/imis/mocks/business_object_spec.rb
+- spec/lib/usps/imis/panels/base_panel_spec.rb
+- spec/lib/usps/imis/panels/education_spec.rb
+- spec/lib/usps/imis/panels/vsc_spec.rb
 - spec/lib/usps/imis/properties_spec.rb
 - spec/lib/usps/imis_spec.rb
 - spec/spec_helper.rb

data/lib/ext/hash.rb

@@ -1,10 +0,0 @@
-# frozen_string_literal: true
-
-# Import a simplified version of to_query from Rails if not already defined
-class Hash
-  def to_query
-    map do |key, value|
-      "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"
-    end.sort * '&'
-  end
-end

data/lib/usps/imis/business_object_mock.rb

@@ -1,35 +0,0 @@
-# frozen_string_literal: true
-
-module Usps
-  module Imis
-    # Mock data response for testing
-    #
-    class BusinessObjectMock
-      attr_reader :fields
-
-      def initialize(**fields)
-        @fields = fields.transform_keys(&:to_s)
-      end
-
-      def get_field(name) = fields[name]
-
-      def get
-        Usps::Imis::Properties.build do |props|
-          fields.each { |name, value| props.add(name, value) }
-        end
-      end
-
-      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
-
-      def put(data) = data
-
-      def post(data) = data
-
-      def delete = ''
-    end
-  end
-end

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

@@ -1,44 +0,0 @@
-# frozen_string_literal: true
-
-module Usps
-  module Imis
-    module Error
-      # Base error class for all internal exceptions
-      #
-      class ApiError < 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
-end

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

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module Usps
-  module Imis
-    module Error
-      # Exception raised by a +Mapper+
-      #
-      class MapperError < ApiError; end
-    end
-  end
-end

data/spec/lib/usps/imis/panel/base_panel_spec.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-require 'spec_helper'
-
-module Usps
-  module Imis
-    module Panel
-      class InvalidPanel < BasePanel; end
-
-      class InvalidPanelWithBusinessObject < BasePanel
-      private
-
-        def business_object = 'Something'
-      end
-    end
-  end
-end
-
-describe Usps::Imis::Panel::BasePanel do
-  it 'requires #business_object to be defined' do
-    expect { Usps::Imis::Panel::InvalidPanel.new.get(1) }.to raise_error(
-      Usps::Imis::Error::ApiError, 'Usps::Imis::Panel::InvalidPanel must implement #business_object'
-    )
-  end
-
-  it 'requires #payload(data) to be defined' do
-    expect { Usps::Imis::Panel::InvalidPanelWithBusinessObject.new.create({}) }.to raise_error(
-      Usps::Imis::Error::ApiError,
-      'Usps::Imis::Panel::InvalidPanelWithBusinessObject must implement #payload(data)'
-    )
-  end
-end