usps-imis-api 1.0.0.pre.rc.2 → 1.0.0.pre.rc.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd103cb82cf705d717bd293bef46390aee8a82dca66ec103fa28510bb67b921c
-  data.tar.gz: 4d1dee0de5129874d612b8b888d57b24918582925b61ffac91ef7722a5cbc9cd
+  metadata.gz: bb187f7e4a8497da991378eec6a9893c5c2a5e637b808a9225ab72ebd5ee385d
+  data.tar.gz: 0d09118f25fce28b94ddbc1257e9670fe3454e34df094885bc9cf35cbb1a86a0
 SHA512:
-  metadata.gz: 30acc54f0082681a9c38ba36bdfe6252331a0199416e131557352a880df66b465cd30de07fb3c3ab0d66366df97b096210e58be649387a3929609c09b9293010
-  data.tar.gz: 729b191b9d78e62f0acc659730d3761e4dc8a60f72304dd5b584a6ac9a63853c659c0fc335ceb7cbd35d903bc2c85656c0642259b2ee8c2f318669741d0d31fe
+  metadata.gz: f50698bc529a6d66d3c69e201d696cdfde1f24c7bf414ab1f655ebdf3b21e1bd512b8e00476ffa62e3ded1a50d72e82586b8f11c002291c5a8038ad5f4cdd2d6
+  data.tar.gz: '09e2849e666c312d0a974efc14b5133ac6e2f0ef181a6715f83ae420b6ba48f6a1566cc749a1dcbce614989c9e5b9fa343ba4dd6a56f1ecd47a9a14b7572617a'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    usps-imis-api (1.0.0.pre.rc.2)
+    usps-imis-api (1.0.0.pre.rc.4)
 
 GEM
   remote: https://rubygems.org/

data/Readme.md

@@ -13,7 +13,7 @@ gem install usps-imis-api
 or add this line to your Gemfile:
 
 ```ruby
-gem 'usps-imis-api', '>= 0.4.0'
+gem 'usps-imis-api', '>= 0.6.0'
 ```
 
 ## Setup
@@ -82,7 +82,7 @@ To fetch member data, run e.g.:
 ```ruby
 api.imis_id = 31092
 
-data = api.get('ABC_ASC_Individual_Demog')
+data = api.on('ABC_ASC_Individual_Demog').get
 ```
 
 ### PUT Fields
@@ -93,7 +93,7 @@ To update member data, run e.g.:
 api.imis_id = 31092
 
 data = { 'MMS_Updated' => Time.now.strftime('%Y-%m-%dT%H:%M:%S'), 'TotMMS' => new_total }
-update = api.put_fields('ABC_ASC_Individual_Demog', data)
+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
@@ -106,7 +106,7 @@ To update member data, run e.g.:
 ```ruby
 api.imis_id = 31092
 
-update = api.put('ABC_ASC_Individual_Demog', complete_imis_object)
+update = api.on('ABC_ASC_Individual_Demog').put(complete_imis_object)
 ```
 
 This method requires a complete iMIS data structure.
@@ -116,7 +116,7 @@ This method requires a complete iMIS data structure.
 To create new member data, run e.g.:
 
 ```ruby
-created = api.post('ABC_ASC_Individual_Demog', complete_imis_object)
+created = api.on('ABC_ASC_Individual_Demog').post(complete_imis_object)
 ```
 
 This method requires a complete iMIS data structure.
@@ -128,7 +128,7 @@ To remove member data, run e.g.:
 ```ruby
 api.imis_id = 31092
 
-api.delete('ABC_ASC_Individual_Demog')
+api.on('ABC_ASC_Individual_Demog').delete
 ```
 
 This returns a blank string on success.
@@ -202,9 +202,11 @@ previous value.
 
 ```ruby
 api.with(31092) do
-  # These three requests are identical:
+  # These four requests are identical:
 
-  put('ABC_ASC_Individual_Demog', { 'TotMMS' => 15 })
+  on('ABC_ASC_Individual_Demog') { put('TotMMS' => 15) }
+
+  on('ABC_ASC_Individual_Demog').put('TotMMS' => 15)
 
   mapper.update(mm: 15)
 

data/lib/usps/imis/api.rb

@@ -5,14 +5,12 @@ module Usps
     # The core API wrapper
     #
     class Api
+      include Requests
+
       # Endpoint for (re-)authentication requests
       #
       AUTHENTICATION_PATH = 'Token'
 
-      # Endpoint for general API requests
-      #
-      API_PATH = 'api'
-
       # Endpoint for IQA query requests
       #
       QUERY_PATH = 'api/Query'
@@ -31,6 +29,10 @@ module Usps
       #
       attr_reader :imis_id
 
+      # Whether to lock changes to the selected iMIS ID
+      #
+      attr_reader :lock_imis_id
+
       # A new instance of +Api+
       #
       # @param skip_authentication [bool] Skip authentication on initialization (used for tests)
@@ -46,7 +48,9 @@ module Usps
       # @param id [Integer, String] iMIS ID to select for future requests
       #
       def imis_id=(id)
-        @imis_id = id.to_i.to_s
+        raise Error::ApiError, 'Cannot change iMIS ID while locked' if lock_imis_id
+
+        @imis_id = id&.to_i&.to_s
       end
 
       # Convert a member's certificate number into an iMIS ID number
@@ -56,15 +60,21 @@ module Usps
       # @return [String] Corresponding iMIS ID
       #
       def imis_id_for(certificate)
-        result = query(Imis.configuration.imis_id_query_name, { certificate: })
-        @imis_id = result['Items']['$values'][0]['ID']
-      rescue StandardError
-        raise Error::Api, 'Member not found'
+        raise Error::ApiError, 'Cannot change iMIS ID while locked' 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'
+        end
       end
 
       # Run requests as DSL, with specific iMIS ID only maintained for this scope
       #
-      # This should be used with methods that do not change the value of `imis_id`
+      # While in this block, changes to the value of +imis_id+ are not allowed
+      #
+      # If no block is given, this sets the iMIS ID and returns self.
       #
       # @param id [Integer, String] iMIS ID to select for requests within the block
       #
@@ -76,104 +86,68 @@ module Usps
       def with(id, &)
         old_id = imis_id
         self.imis_id = id
+        return self unless block_given?
+
+        @lock_imis_id = true
         instance_eval(&)
       ensure
-        self.imis_id = old_id
+        if block_given?
+          @lock_imis_id = false
+          self.imis_id = old_id
+        end
       end
 
-      # Get a business object for the current member
+      # Run an IQA Query
       #
-      # @param business_object_name [String] Name of the business object
-      # @param url_id [String] Override the ID param of the URL (e.g. used for Panels)
+      # @param query_name [String] Full path of the query in IQA, e.g. +$/_ABC/Fiander/iMIS_ID+
+      # @query_params [Hash] Conforms to pattern +{ param_name => param_value }+
       #
       # @return [Hash] Response data from the API
       #
-      def get(business_object_name, url_id: nil)
-        uri = uri_for(business_object_name, url_id:)
+      def query(query_name, query_params = {})
+        query_params[:QueryName] = query_name
+        path = "#{QUERY_PATH}?#{query_params.to_query}"
+        uri = URI(File.join(Imis.configuration.hostname, path))
         request = Net::HTTP::Get.new(uri)
         result = submit(uri, authorize(request))
         JSON.parse(result.body)
       end
 
-      # Update only specific fields on a business object for the current member
+      # An instance of +BusinessObject+, using this instance as its parent +Api+
       #
       # @param business_object_name [String] Name of the business object
-      # @param fields [Hash] Conforms to pattern +{ field_key => value }+
       # @param url_id [String] Override the ID param of the URL (e.g. used for Panels)
       #
-      # @return [Hash] Response data from the API
-      #
-      def put_fields(business_object_name, fields, url_id: nil)
-        updated = filter_fields(business_object_name, fields)
-        put(business_object_name, updated, url_id:)
+      def business_object(business_object_name, url_id: nil)
+        BusinessObject.new(self, business_object_name, url_id:)
       end
 
-      # Update a business object for the current member
+      # Run requests as DSL, with specific +BusinessObject+ only maintained for this scope
       #
-      # @param business_object_name [String] Name of the business object
-      # @param body [Hash] Full raw API object data
-      # @param url_id [String] Override the ID param of the URL (e.g. used for Panels)
-      #
-      # @return [Hash] Response data from the API
-      #
-      def put(business_object_name, body, url_id: nil)
-        uri = uri_for(business_object_name, url_id:)
-        request = Net::HTTP::Put.new(uri)
-        request.body = JSON.dump(body)
-        result = submit(uri, authorize(request))
-        JSON.parse(result.body)
-      end
-
-      # Create a business object for the current member
+      # If no block is given, this returns the specified +BusinessObject+.
       #
       # @param business_object_name [String] Name of the business object
-      # @param body [Hash] Full raw API object data
       # @param url_id [String] Override the ID param of the URL (e.g. used for Panels)
       #
-      # @return [Hash] Response data from the API
-      #
-      def post(business_object_name, body, url_id: nil)
-        uri = uri_for(business_object_name, url_id:)
-        request = Net::HTTP::Post.new(uri)
-        request.body = JSON.dump(body)
-        result = submit(uri, authorize(request))
-        JSON.parse(result.body)
-      end
+      def on(business_object_name, url_id: nil, &)
+        object = business_object(business_object_name, url_id:)
+        return object unless block_given?
 
-      # Remove a business object for the current member
-      #
-      # @param business_object_name [String] Name of the business object
-      # @param url_id [String] Override the ID param of the URL (e.g. used for Panels)
-      #
-      # @return [String] Error response body from the API, or empty string on success
-      #
-      def delete(business_object_name, url_id: nil)
-        uri = uri_for(business_object_name, url_id:)
-        request = Net::HTTP::Delete.new(uri)
-        result = submit(uri, authorize(request))
-        result.body
+        result = nil
+        object.tap { |obj| result = obj.instance_eval(&) }
+        result
       end
 
-      # Run an IQA Query
-      #
-      # @param query_name [String] Full path of the query in IQA, e.g. +$/_ABC/Fiander/iMIS_ID+
-      # @query_params [Hash] Conforms to pattern +{ param_name => param_value }+
+      # An instance of +Mapper+, using this instance as its parent +Api+
       #
-      # @return [Hash] Response data from the API
-      #
-      def query(query_name, query_params = {})
-        query_params[:QueryName] = query_name
-        path = "#{QUERY_PATH}?#{query_params.to_query}"
-        uri = URI(File.join(imis_hostname, path))
-        request = Net::HTTP::Get.new(uri)
-        result = submit(uri, authorize(request))
-        JSON.parse(result.body)
+      def mapper
+        @mapper ||= Mapper.new(self)
       end
 
-      # An instance of Mapper, using this instance as its parent +Api+
+      # Convenience alias for updating mapped fields
       #
-      def mapper
-        @mapper ||= Mapper.new(self)
+      def update(data)
+        mapper.update(data)
       end
 
       # Convenience accessor for available Panel objects, each using this instance as its parent
@@ -186,56 +160,16 @@ module Usps
         )
       end
 
-      # Convenience alias for updating mapped fields
-      #
-      def update(data)
-        mapper.update(data)
-      end
-
       # Ruby 3.5 instance variable filter
       #
       def instance_variables_to_inspect = %i[@token_expiration @imis_id]
 
     private
 
-      def client(uri)
-        Net::HTTP.new(uri.host, uri.port).tap do |http|
-          http.use_ssl = true
-          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
-        end
-      end
-
-      def imis_hostname
-        Imis.configuration.hostname
-      end
-
-      # Authorize a request prior to submitting
-      #
-      # If the current token is missing/expired, request a new one
-      #
-      def authorize(request)
-        authenticate if token_expiration < Time.now
-        request.tap { |r| r.add_field('Authorization', "Bearer #{token}") }
-      end
-
-      # Construct a business object API endpoint address
-      #
-      def uri_for(business_object_name, url_id: nil)
-        url_id ||= imis_id
-        url_id = CGI.escape(url_id)
-        URI(File.join(imis_hostname, "#{API_PATH}/#{business_object_name}/#{url_id}"))
-      end
-
-      def submit(uri, request)
-        client(uri).request(request).tap do |result|
-          raise Error::Response.from(result) unless result.is_a?(Net::HTTPSuccess)
-        end
-      end
-
       # Authenticate to the iMIS API, and store the access token and expiration time
       #
       def authenticate
-        uri = URI(File.join(imis_hostname, AUTHENTICATION_PATH))
+        uri = URI(File.join(Imis.configuration.hostname, AUTHENTICATION_PATH))
         req = Net::HTTP::Post.new(uri)
         authentication_data = {
           grant_type: 'password',
@@ -249,33 +183,6 @@ module Usps
         @token = json['access_token']
         @token_expiration = Time.parse(json['.expires'])
       end
-
-      # Manually assemble the matching data structure, with fields in the correct order
-      #
-      def filter_fields(business_object_name, fields)
-        existing = get(business_object_name)
-
-        JSON.parse(JSON.dump(existing)).tap do |updated|
-          # The first property is always the iMIS ID again
-          updated['Properties']['$values'] = [existing['Properties']['$values'][0]]
-
-          # Iterate through all existing fields
-          existing['Properties']['$values'].each do |value|
-            next unless fields.keys.include?(value['Name'])
-
-            # Strings are not wrapped in the type definition structure
-            new_value = fields[value['Name']]
-            if new_value.is_a?(String)
-              value['Value'] = new_value
-            else
-              value['Value']['$value'] = new_value
-            end
-
-            # Add the completed field with the updated value
-            updated['Properties']['$values'] << value
-          end
-        end
-      end
     end
   end
 end

data/lib/usps/imis/business_object.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    # DEV
+    class BusinessObject
+      include Requests
+
+      # Endpoint for general API requests
+      #
+      API_PATH = 'api'
+
+      # The parent +Api+ object
+      #
+      attr_reader :api
+
+      # Name of the iMIS Business Object
+      #
+      attr_reader :business_object_name
+
+      # Override ID param of the URL (e.g. used for Panels)
+      #
+      attr_reader :url_id
+
+      # A new instance of +BusinessObject+
+      #
+      def initialize(api, business_object_name, url_id: nil)
+        @api = api
+        @business_object_name = business_object_name
+        @url_id = url_id
+      end
+
+      # Get a business object for the current member
+      #
+      # @return [Hash] Response data from the API
+      #
+      def get
+        request = Net::HTTP::Get.new(uri)
+        result = submit(uri, authorize(request))
+        JSON.parse(result.body)
+      end
+
+      # 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
+      #
+      def put_fields(fields)
+        updated = filter_fields(fields)
+        put(updated)
+      end
+
+      # Update a business object for the current member
+      #
+      # @param body [Hash] Full raw API object data
+      #
+      # @return [Hash] 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
+
+      # Create a business object for the current member
+      #
+      # @param body [Hash] Full raw API object data
+      #
+      # @return [Hash] 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
+
+      # Remove a business object for the current member
+      #
+      # @return [String] Error response body from the API, or empty string on success
+      #
+      def delete
+        request = Net::HTTP::Delete.new(uri)
+        result = submit(uri, authorize(request))
+        result.body
+      end
+
+    private
+
+      def token = api.token
+      def token_expiration = api.token_expiration
+
+      # 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}"
+        URI(File.join(Imis.configuration.hostname, full_path))
+      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]]
+
+          # Iterate through all existing fields
+          existing['Properties']['$values'].each do |value|
+            next unless fields.keys.include?(value['Name'])
+
+            # Strings are not wrapped in the type definition structure
+            new_value = fields[value['Name']]
+            if new_value.is_a?(String)
+              value['Value'] = new_value
+            else
+              value['Value']['$value'] = new_value
+            end
+
+            # Add the completed field with the updated value
+            updated['Properties']['$values'] << value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/usps/imis/config.rb

@@ -25,7 +25,7 @@ module Usps
         when :development
           IMIS_ROOT_URL_DEV
         else
-          raise Error::Api, "Unexpected API environment: #{environment}"
+          raise Error::ApiError, "Unexpected API environment: #{environment}"
         end
       end
 

data/lib/usps/imis/error/{api.rb → api_error.rb}

@@ -5,12 +5,12 @@ module Usps
     module Error
       # Base error class for all internal exceptions
       #
-      class Api < StandardError
+      class ApiError < StandardError
         # Additional call-specific metadata to pass through to Bugsnag
         #
         attr_accessor :metadata
 
-        # A new instance of +Error::Api+
+        # A new instance of +ApiError+
         #
         # @param message [String] The base exception message
         # @param metadata [Hash] Additional call-specific metadata to pass through to Bugsnag

data/lib/usps/imis/error/{mapper.rb → mapper_error.rb}

@@ -5,7 +5,7 @@ module Usps
     module Error
       # Exception raised by a +Mapper+
       #
-      class Mapper < Api; end
+      class MapperError < ApiError; end
     end
   end
 end

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

@@ -5,7 +5,7 @@ module Usps
     module Error
       # Exception raised due to receiving an error response from the API
       #
-      class Response < Api
+      class ResponseError < ApiError
         # [Net::HTTPResponse] The response received from the API
         #
         attr_reader :response
@@ -14,7 +14,7 @@ module Usps
         #
         attr_accessor :metadata
 
-        # Create a new instance of +Error::Response+ from an API response
+        # Create a new instance of +ResponseError+ from an API response
         #
         # @param response [Net::HTTPResponse] The response received from the API
         #
@@ -22,7 +22,7 @@ module Usps
           new(nil, response)
         end
 
-        # Create a new instance of +Error::Response+
+        # Create a new instance of +ResponseError+
         #
         # @param _message Ignored
         # @param response [Net::HTTPResponse] The response received from the API

data/lib/usps/imis/mapper.rb

@@ -47,7 +47,7 @@ module Usps
         end
 
         updates.map do |business_object_name, field_updates|
-          api.put_fields(business_object_name, field_updates)
+          api.business_object(business_object_name).put_fields(field_updates)
         end
       end
 
@@ -74,7 +74,7 @@ module Usps
         end
 
         raise(
-          Error::Mapper,
+          Error::MapperError,
           "Unrecognized field: \"#{field_name}\". " \
           'Please report what data you are attempting to work with to ITCom leadership.'
         )

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

@@ -20,7 +20,7 @@ module Usps
         # @param ordinal [Integer] The ordinal identifier for the desired object
         #
         def get(ordinal)
-          api.get(business_object, url_id: "~#{api.imis_id}|#{ordinal}")
+          api.business_object(business_object, url_id: "~#{api.imis_id}|#{ordinal}").get
         end
 
         # Create a new object in the Panel
@@ -28,7 +28,7 @@ module Usps
         # @param data [Hash] The record data for the desired object
         #
         def create(data)
-          api.post(business_object, payload(data), url_id: '')
+          api.business_object(business_object, url_id: '').post(payload(data))
         end
 
         # Update an existing object in the Panel
@@ -37,7 +37,9 @@ module Usps
         #                    +ordinal+ identifier
         #
         def update(data)
-          api.put(business_object, payload(data), url_id: "~#{api.imis_id}|#{data[:ordinal]}")
+          api
+            .business_object(business_object, url_id: "~#{api.imis_id}|#{data[:ordinal]}")
+            .put(payload(data))
         end
 
         # Remove a specific object from the Panel
@@ -45,17 +47,17 @@ module Usps
         # @param ordinal [Integer] The ordinal identifier for the desired object
         #
         def destroy(ordinal)
-          api.delete(business_object, url_id: "~#{api.imis_id}|#{ordinal}")
+          api.business_object(business_object, url_id: "~#{api.imis_id}|#{ordinal}").delete
         end
 
       private
 
         def business_object
-          raise Error::Api, "#{self.class.name} must implement #business_object"
+          raise Error::ApiError, "#{self.class.name} must implement #business_object"
         end
 
         def payload(_data)
-          raise Error::Api, "#{self.class.name} must implement #payload(data)"
+          raise Error::ApiError, "#{self.class.name} must implement #payload(data)"
         end
       end
     end

data/lib/usps/imis/requests.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    module Requests
+    private
+
+      def client(uri)
+        Net::HTTP.new(uri.host, uri.port).tap do |http|
+          http.use_ssl = true
+          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        end
+      end
+
+      # Authorize a request prior to submitting
+      #
+      # If the current token is missing/expired, request a new one
+      #
+      def authorize(request)
+        authenticate if token_expiration < Time.now
+        request.tap { |r| r.add_field('Authorization', "Bearer #{token}") }
+      end
+
+      def submit(uri, request)
+        client(uri).request(request).tap do |result|
+          raise Error::ResponseError.from(result) unless result.is_a?(Net::HTTPSuccess)
+        end
+      end
+    end
+  end
+end

data/lib/usps/imis/version.rb

@@ -2,6 +2,6 @@
 
 module Usps
   module Imis
-    VERSION = '1.0.0-rc.2'
+    VERSION = '1.0.0-rc.4'
   end
 end

data/lib/usps/imis.rb

@@ -13,9 +13,11 @@ require 'ext/hash' unless defined?(Rails)
 
 # Internal requires
 require_relative 'imis/config'
-require_relative 'imis/error/api'
-require_relative 'imis/error/mapper'
-require_relative 'imis/error/response'
+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/api'
 require_relative 'imis/mapper'
 require_relative 'imis/panel/base_panel'

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::Api, 'Member not found'
+          Usps::Imis::Error::ApiError, 'Member not found'
         )
       end
     end
@@ -41,13 +41,15 @@ describe Usps::Imis::Api do
     before { api.imis_id = 31092 }
 
     it 'sends an update' do
-      expect(api.put_fields('ABC_ASC_Individual_Demog', { 'TotMMS' => 15 })).to be_a(Hash)
+      expect(api.business_object('ABC_ASC_Individual_Demog').put_fields('TotMMS' => 15)).to(
+        be_a(Hash)
+      )
     end
 
     context 'when receiving a response error' do
       let(:warning_text) do
         <<~WARNING.chomp
-          Usps::Imis::Error::Response: [INTERNAL_SERVER_ERROR] The iMIS API returned an error.
+          Usps::Imis::Error::ResponseError: [INTERNAL_SERVER_ERROR] The iMIS API returned an error.
           Something went wrong
         WARNING
       end
@@ -61,8 +63,8 @@ describe Usps::Imis::Api do
       end
 
       it 'wraps the error' do
-        expect { api.put_fields('ABC_ASC_Individual_Demog', { 'TotMMS' => 15 }) }.to raise_error(
-          Usps::Imis::Error::Api, warning_text
+        expect { api.business_object('ABC_ASC_Individual_Demog').put_fields('TotMMS' => 15) }.to(
+          raise_error(Usps::Imis::Error::ApiError, warning_text)
         )
       end
     end
@@ -71,7 +73,7 @@ describe Usps::Imis::Api do
   describe '#with' do
     it 'sends an update from put' do
       expect(
-        api.with(31092) { put_fields('ABC_ASC_Individual_Demog', { 'TotMMS' => 15 }) }
+        api.with(31092) { business_object('ABC_ASC_Individual_Demog').put_fields('TotMMS' => 15) }
       ).to be_a(Hash)
     end
 
@@ -82,6 +84,51 @@ describe Usps::Imis::Api do
     it 'uses a panel correctly' do
       expect(api.with(6374) { panels.vsc.get(1433) }).to be_a(Hash)
     end
+
+    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
+
+    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
+  end
+
+  describe '#on' do
+    it 'returns a BusinessObject without a block' do
+      expect(api.on('ABC_ASC_Individual_Demog')).to be_a(Usps::Imis::BusinessObject)
+    end
+
+    it 'sends an update from put', :aggregate_failures do
+      result = api.with(31092) do
+        on('ABC_ASC_Individual_Demog') { put_fields({ 'TotMMS' => 15 }) }
+      end
+
+      expect(result).to be_a(Hash)
+      expect(api.imis_id).to be_nil
+    end
+
+    it 'chains .with().on() to a single block', :aggregate_failures do
+      result = api.with(31092).on('ABC_ASC_Individual_Demog') do
+        put_fields({ 'TotMMS' => 15 })
+      end
+
+      expect(result).to be_a(Hash)
+      expect(api.imis_id).to eq('31092')
+    end
+
+    it 'nests on and with', :aggregate_failures do
+      result = api.on('ABC_ASC_Individual_Demog') do |object|
+        api.with(31092) { object.put_fields({ 'TotMMS' => 15 }) }
+      end
+
+      expect(result).to be_a(Hash)
+      expect(api.imis_id).to be_nil
+    end
   end
 
   describe '#inspect' do
@@ -108,36 +155,4 @@ describe Usps::Imis::Api do
       expect(api).to have_received(:authenticate)
     end
   end
-
-  describe '#filter_fields' do
-    let(:expected) do
-      {
-        'Properties' => {
-          '$values' => [
-            { 'Name' => 'Stub iMIS ID', 'Value' => { '$value' => '31092' } },
-            { 'Name' => 'Stub Integer', 'Value' => { '$value' => 43 } },
-            { 'Name' => 'Stub String', 'Value' => 'other' }
-          ]
-        }
-      }
-    end
-
-    before do
-      allow(api).to receive(:get).and_return({
-        'Properties' => {
-          '$values' => [
-            { 'Name' => 'Stub iMIS ID', 'Value' => { '$value' => '31092' } },
-            { 'Name' => 'Stub Integer', 'Value' => { '$value' => 42 } },
-            { 'Name' => 'Stub String', 'Value' => 'something' }
-          ]
-        }
-      })
-    end
-
-    it 'formats fields correctly' do
-      updated = api.send(:filter_fields, 'Stub', { 'Stub Integer' => 43, 'Stub String' => 'other' })
-
-      expect(updated).to eq(expected)
-    end
-  end
 end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Usps::Imis::BusinessObject do
+  let(:business_object) { described_class.new(api, 'Stub') }
+  let(:api) { Usps::Imis::Api.new }
+
+  describe '#filter_fields' do
+    let(:expected) do
+      {
+        'Properties' => {
+          '$values' => [
+            { 'Name' => 'Stub iMIS ID', 'Value' => { '$value' => '31092' } },
+            { 'Name' => 'Stub Integer', 'Value' => { '$value' => 43 } },
+            { 'Name' => 'Stub String', 'Value' => 'other' }
+          ]
+        }
+      }
+    end
+
+    before do
+      allow(business_object).to receive(:get).and_return({
+        'Properties' => {
+          '$values' => [
+            { 'Name' => 'Stub iMIS ID', 'Value' => { '$value' => '31092' } },
+            { 'Name' => 'Stub Integer', 'Value' => { '$value' => 42 } },
+            { 'Name' => 'Stub String', 'Value' => 'something' }
+          ]
+        }
+      })
+    end
+
+    it 'formats fields correctly' do
+      updated = business_object.send(:filter_fields, 'Stub Integer' => 43, 'Stub String' => 'other')
+
+      expect(updated).to eq(expected)
+    end
+  end
+end

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

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

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

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

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

@@ -4,7 +4,7 @@ require 'spec_helper'
 
 ApiResponseStub = Struct.new(:code, :body)
 
-describe Usps::Imis::Error::Response do
+describe Usps::Imis::Error::ResponseError do
   let(:error) { described_class.from(response) }
 
   describe 'error codes' do
@@ -61,7 +61,7 @@ describe Usps::Imis::Error::Response do
     let(:response) { ApiResponseStub.new('500', 'Body of the API response error') }
     let(:warning_text) do
       <<~WARNING.chomp
-        Usps::Imis::Error::Response: [INTERNAL_SERVER_ERROR] The iMIS API returned an error.
+        Usps::Imis::Error::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::Response do
     let(:response) { ApiResponseStub.new('500', response_body) }
     let(:warning_text) do
       <<~WARNING.chomp
-        Usps::Imis::Error::Response: [INTERNAL_SERVER_ERROR] The iMIS API returned an error.
+        Usps::Imis::Error::ResponseError: [INTERNAL_SERVER_ERROR] The iMIS API returned an error.
         description
       WARNING
     end
@@ -95,7 +95,7 @@ describe Usps::Imis::Error::Response do
     let(:response) { ApiResponseStub.new('500', response_body) }
     let(:warning_text) do
       <<~WARNING.chomp
-        Usps::Imis::Error::Response: [INTERNAL_SERVER_ERROR] The iMIS API returned an error.
+        Usps::Imis::Error::ResponseError: [INTERNAL_SERVER_ERROR] The iMIS API returned an error.
         #{response_body}
       WARNING
     end

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

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

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

@@ -19,13 +19,13 @@ 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::Api, 'Usps::Imis::Panel::InvalidPanel must implement #business_object'
+      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::Api,
+      Usps::Imis::Error::ApiError,
       'Usps::Imis::Panel::InvalidPanelWithBusinessObject must implement #payload(data)'
     )
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: usps-imis-api
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.rc.2
+  version: 1.0.0.pre.rc.4
 platform: ruby
 authors:
 - Julian Fiander
@@ -30,19 +30,22 @@ files:
 - lib/ext/hash.rb
 - lib/usps/imis.rb
 - lib/usps/imis/api.rb
+- lib/usps/imis/business_object.rb
 - lib/usps/imis/config.rb
-- lib/usps/imis/error/api.rb
-- lib/usps/imis/error/mapper.rb
-- lib/usps/imis/error/response.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/mapper.rb
 - lib/usps/imis/panel/base_panel.rb
 - lib/usps/imis/panel/education.rb
 - lib/usps/imis/panel/vsc.rb
+- lib/usps/imis/requests.rb
 - lib/usps/imis/version.rb
 - spec/lib/usps/imis/api_spec.rb
+- spec/lib/usps/imis/business_object_spec.rb
 - spec/lib/usps/imis/config_spec.rb
-- spec/lib/usps/imis/error/api_spec.rb
-- spec/lib/usps/imis/error/response_spec.rb
+- spec/lib/usps/imis/error/api_error_spec.rb
+- spec/lib/usps/imis/error/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