usps-imis-api 0.5.1 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93af4ce91eacb92695d10144b3885da6bd1e8ff31e26f8b22c8ae9404595f951
-  data.tar.gz: 6c2df89c1531953ef37d8fd867699fc8917d2aca3db3e204cf3937bf679cf7ed
+  metadata.gz: 9cbe7660dffdee043ffdbe92a012879ceb439946b737f34fe9ca16d6f34e68b1
+  data.tar.gz: 065c486f386c7b73501dda6bf92a0214680e3ab13104388de29613d4bb4d7315
 SHA512:
-  metadata.gz: 299a9220c4232cd0a1d45681a4f5c32800c0188e3e86f2740b7106f5ccc256f22dfe15bbafe6bd8c06152b4af9f3434c2cba5e49c632eed5a3a1540a4305ca59
-  data.tar.gz: 2d0310cea22d9160330cb4d1438679dc17565ab9e43d32dc0db7fd2dea7315a070cbd949bc30e0cde9ecbca09302a5c1e4033c034667fffb52d44462177766a9
+  metadata.gz: 67e8a5cf1cb919bccaada7960f1680426491880340f68eb8ed3ed57e5922bfdd6ab98208534367679aaec6b0026c1afb8161e5df73c7fd1dff383293882239b7
+  data.tar.gz: 830f0e96d1528bd434a4122511ab15165d27ef42f0383713e10640906395d19742e49b5da8858021fa3a2dbd64be699c5adf2c08f4897a5c3d6b94f8bb3d270f

data/.rubocop.yml

@@ -32,8 +32,6 @@ Layout/SpaceInsideHashLiteralBraces:
   EnforcedStyleForEmptyBraces: no_space
 Layout/SpaceInsideArrayLiteralBrackets:
   EnforcedStyle: no_space
-Layout/LineLength:
-  Max: 100
 
 Lint/UnusedMethodArgument:
   Enabled: true

data/Gemfile.lock

@@ -1,17 +1,39 @@
 PATH
   remote: .
   specs:
-    usps-imis-api (0.5.1)
+    usps-imis-api (0.6.1)
+      activesupport (~> 8.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    activesupport (8.0.3)
+      base64
+      benchmark (>= 0.3)
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
     ast (2.4.2)
+    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)
     docile (1.4.1)
     dotenv (3.1.4)
+    drb (2.2.3)
     erb (5.0.3)
+    i18n (1.14.7)
+      concurrent-ruby (~> 1.0)
     io-console (0.8.1)
     irb (1.15.2)
       pp (>= 0.6.0)
@@ -19,6 +41,8 @@ GEM
       reline (>= 0.4.2)
     json (2.7.2)
     language_server-protocol (3.17.0.3)
+    logger (1.7.0)
+    minitest (5.26.0)
     parallel (1.26.3)
     parser (3.3.5.0)
       ast (~> 2.4.1)
@@ -67,6 +91,7 @@ GEM
     rubocop-rspec (3.1.0)
       rubocop (~> 1.61)
     ruby-progressbar (1.13.0)
+    securerandom (0.4.1)
     simplecov (0.22.0)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
@@ -75,7 +100,10 @@ GEM
     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)
+    uri (1.0.4)
 
 PLATFORMS
   arm64-darwin-23

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.1'
 ```
 
 ## Setup
@@ -25,9 +25,11 @@ require 'dotenv/load' # Optionally load environment variables from `.env` file
 require 'usps/imis'
 
 Usps::Imis.configure do |config|
-  config.environment = :development # Rails.env
-  config.imis_id_query_name = ENV['IMIS_ID_QUERY_NAME']
+  # This will default to `Rails.env` if available.
+  config.environment = :development
 
+  # These options will default to the listed `ENV` variable if available.
+  config.imis_id_query_name = ENV['IMIS_ID_QUERY_NAME']
   config.username = ENV['IMIS_USERNAME']
   config.password = ENV['IMIS_PASSWORD']
 end
@@ -82,7 +84,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 +95,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 +108,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 +118,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 +130,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 +204,11 @@ previous value.
 
 ```ruby
 api.with(31092) do
-  # These three requests are identical:
+  # These four requests are identical:
+
+  on('ABC_ASC_Individual_Demog') { put('TotMMS' => 15) }
 
-  put('ABC_ASC_Individual_Demog', { 'TotMMS' => 15 })
+  on('ABC_ASC_Individual_Demog').put('TotMMS' => 15)
 
   mapper.update(mm: 15)
 
@@ -220,10 +224,7 @@ end
 
 ## Exception Handling
 
-Exception and error response handling will be added later.
-
-To print exception information to STDERR when raising, set the environment
-variable `IMIS_ERROR_LOG_TO_STDERR=true`.
+All internal exceptions inherit from `Usps::Imis::ApiError`.
 
 ## Automated Testing and Linting
 
@@ -239,6 +240,8 @@ Linting is available by running:
 bundle exec rubocop
 ```
 
+100% branch coverage is enforced on the test suite.
+
 ### GitHub Actions
 
 Testing and linting are automatically run on every push.

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'
@@ -52,7 +50,7 @@ module Usps
       def imis_id=(id)
         raise Error::ApiError, 'Cannot change iMIS ID while locked' if lock_imis_id
 
-        @imis_id = id.to_i.to_s
+        @imis_id = id&.to_i&.to_s
       end
 
       # Convert a member's certificate number into an iMIS ID number
@@ -76,6 +74,8 @@ module Usps
       #
       # 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
       #
       # @example
@@ -86,107 +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
-        @lock_imis_id = false
-        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
-      #
-      # @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)
+      # Run requests as DSL, with specific +BusinessObject+ only maintained for this scope
       #
-      # @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
@@ -199,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::ResponseError.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',
@@ -262,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

@@ -8,25 +8,31 @@ module Usps
       IMIS_ROOT_URL_PROD = 'https://portal.americasboatingclub.org'
       IMIS_ROOT_URL_DEV = 'https://abcdev.imiscloud.com'
 
-      attr_accessor :environment, :imis_id_query_name, :username, :password
+      attr_accessor :imis_id_query_name, :username, :password
+      attr_reader :environment
 
       def initialize
+        @environment = defined?(Rails) ? Rails.env : ActiveSupport::StringInquirer.new('development')
+        @imis_id_query_name = ENV.fetch('IMIS_ID_QUERY_NAME', nil)
+        @username = ENV.fetch('IMIS_USERNAME', nil)
+        @password = ENV.fetch('IMIS_PASSWORD', nil)
+
         yield self if block_given?
       end
 
+      def environment=(env)
+        @environment = ActiveSupport::StringInquirer.new(env.to_s)
+      end
+
       # Environment-specific API endpoint hostname
       #
       # @return The API hostname for the current environment
       #
       def hostname
-        case environment.to_sym
-        when :production
-          IMIS_ROOT_URL_PROD
-        when :development
-          IMIS_ROOT_URL_DEV
-        else
-          raise Error::ApiError, "Unexpected API environment: #{environment}"
-        end
+        return IMIS_ROOT_URL_PROD if environment.production?
+        return IMIS_ROOT_URL_DEV if environment.development?
+
+        raise Error::ApiError, "Unexpected API environment: #{environment}"
       end
 
       # Ruby 3.5 instance variable filter

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
 

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

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 = '0.5.1'
+    VERSION = '0.6.1'
   end
 end

data/lib/usps/imis.rb

@@ -16,6 +16,8 @@ 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/api'
 require_relative 'imis/mapper'
 require_relative 'imis/panel/base_panel'

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

@@ -41,7 +41,9 @@ 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
@@ -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::ApiError, 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
 
@@ -96,6 +98,39 @@ describe Usps::Imis::Api do
     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
     it 'is configured to exclude the token instance variable' do
       expect(api.instance_variables_to_inspect).not_to include(:@token)
@@ -120,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

@@ -5,10 +5,36 @@ require 'spec_helper'
 describe Usps::Imis::Config do
   let(:config) { described_class.new }
 
-  it 'sets values on initialize' do
-    config = described_class.new { |c| c.environment = 'test' }
+  describe 'environment' do
+    subject { config.environment }
 
-    expect(config.environment).to eq('test')
+    let(:config) { described_class.new }
+
+    context 'when not specified' do
+      it { is_expected.to be_development }
+    end
+
+    context 'when specified' do
+      before { config.environment = 'something' }
+
+      it { is_expected.to be_something }
+    end
+
+    context 'when specified on initialize' do
+      subject { config.environment }
+
+      let(:config) do
+        described_class.new { |c| c.environment = 'test' }
+      end
+
+      it { is_expected.to be_test }
+    end
+
+    context 'when in Rails' do
+      before { stub_const('Rails', Struct.new(:env).new(ActiveSupport::StringInquirer.new('qa'))) }
+
+      it { is_expected.to be_qa }
+    end
   end
 
   describe '#hostname' do

data/spec/spec_helper.rb

@@ -7,6 +7,7 @@ SimpleCov.minimum_coverage(line: 100, branch: 100)
 
 require 'dotenv/load'
 require 'usps/imis'
+require 'active_support/string_inquirer'
 
 ENV['TESTING'] = 'true'
 

data/usps-imis-api.gemspec

@@ -15,4 +15,6 @@ Gem::Specification.new do |s|
   s.metadata['rubygems_mfa_required'] = 'true'
 
   s.required_ruby_version = '>= 3.4'
+
+  s.add_dependency 'activesupport', '~> 8.0'
 end

metadata

@@ -1,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: usps-imis-api
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.1
 platform: ruby
 authors:
 - Julian Fiander
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
 description: A wrapper for the iMIS API.
 email: jsfiander@gmail.com
 executables: []
@@ -30,6 +44,7 @@ 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_error.rb
 - lib/usps/imis/error/mapper_error.rb
@@ -38,8 +53,10 @@ files:
 - 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_error_spec.rb
 - spec/lib/usps/imis/error/response_error_spec.rb