usps-imis-api 1.0.0.pre.rc.3 → 1.0.0.pre.rc.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 927a6d408196ed631d013daac7854beb5b0c27b7b138a454c0078af710cad204
-  data.tar.gz: 8d747f8023487b5fa1d2e4fc50a3aa5d26676cc99c818849b6fa9af205a8e50b
+  metadata.gz: 1c0abf715f3c6019016bc6b8bdf867ce9d83234ba093c6150a4885997e9156f4
+  data.tar.gz: bcd2727e5f74b7a8681ae8ea1c510539fc24b62085719b439a01a331989a59c9
 SHA512:
-  metadata.gz: b87668b7e37cfa951b729ef0c01b580055b0d48076f6ffab10bff81e0d47ad255df3718e3c63daece6c0a2fc256506eb9ceefec0bed564ce09b1c5bc4e8ba116
-  data.tar.gz: e0c08859e7e890887267d13166023ef903355ed70416bd83e856d143de0eab6753d78c0b976acdcc3356144bd3ae92a95ebef43233c6b40a89b17315bb29de0e
+  metadata.gz: e0f98c36fd93ae643a949980e590fbb327cc40e1947ef5c8b530156e3961073082702dd38916fa27da4db10c642316c3c3db9f97d82d2f7c616032917cea22f1
+  data.tar.gz: 3195ecb427cff0fea1c6d1cef0d877507c2bb7baaa3a3db6d669f281048a03de7fb06c15e3b5f1cfe36625ece30d2e890f05202accfaf56148de40dda0fdce4d

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 (1.0.0.pre.rc.3)
+    usps-imis-api (1.0.0.pre.rc.5)
+      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.3'
 ```
 
 ## 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,17 @@ 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
+```
+
+### 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
@@ -93,7 +105,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 +118,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 +128,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 +140,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 +214,11 @@ previous value.
 
 ```ruby
 api.with(31092) do
-  # These three requests are identical:
+  # These 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)
 
@@ -218,12 +232,26 @@ api.with(6374) do
 end
 ```
 
-## Exception Handling
+```ruby
+api.with(31092) do
+  # These requests are identical:
+
+  on('ABC_ASC_Individual_Demog') do
+    get['Properties']['$values'].find { |hash| hash['Name'] == 'TotMMS' }['Value']['$value']
+  end
+
+  on('ABC_ASC_Individual_Demog') { get_field('TotMMS') }
+
+  on('ABC_ASC_Individual_Demog').get_field('TotMMS')
+end
 
-Exception and error response handling will be added later.
+# This request fetches the same data, but leaves the iMIS ID selected
+api.with(31092).on('ABC_ASC_Individual_Demog').get_field('TotMMS')
+```
 
-To print exception information to STDERR when raising, set the environment
-variable `IMIS_ERROR_LOG_TO_STDERR=true`.
+## Exception Handling
+
+All internal exceptions inherit from `Usps::Imis::ApiError`.
 
 ## Automated Testing and Linting
 
@@ -239,6 +267,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,144 @@
+# 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
+
+      # Get a single named field from a business object for the current member
+      #
+      # @param name [String] Field name to return
+      #
+      # @return [Hash] Response data from the API
+      #
+      def get_field(name)
+        values = get['Properties']['$values']
+        value = values.find { |hash| hash['Name'] == name }['Value']
+
+        value.is_a?(String) ? value : value['$value']
+      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