usps-imis-api 0.6.16 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d68eb23f00014bc9cb6173f716084f8eff9cedfc48e70507c07a35fe8e7b207
-  data.tar.gz: fda5c7882bc758d9cfdd2889e734ff8c0d319f456e39bf1965f030765ec82a0e
+  metadata.gz: ca358fc80eed74b0335f6137f71e503fffbc84d6c396c8e1c23c90501eab5b36
+  data.tar.gz: 239111a5dfd7cb186fe358fc0227e3063744225cf619e12a91e994f639142e56
 SHA512:
-  metadata.gz: bb42f257b1e4e6c6383dd9b1f37d68e9c89f358f98bfccb09c53190573da28b0259fabe27e12f50c5420daa8f009661e928463c19a48e854abd86b8dd34021f1
-  data.tar.gz: a4fb539ef056e6936e1546b303ef8b20bf52a822185063d8b6eabc042eb5b3f2b2fceb5d0cff5959c40ce524175a137dd1821783af7eea495803342c1d065cff
+  metadata.gz: 2f31860395762aeead9f002f96867111758a8474ada928ba1369e3122b767f0b27052ed41157d8eac008fade27bdb779389cd65c74ad7cadbb87129ee9c238ff
+  data.tar.gz: 7c0f5eaae8592a93192e08ca4cf88e604629de246b8e2f9272880d19e39a218d01a027387720a6c289b7f4490bc6617b57c637ab00201868ecd36fd178748031

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.16)
+    usps-imis-api (0.7.1)
       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,6 +77,10 @@ You can also manually set the current ID, if you already have it for a given mem
 api.imis_id = imis_id
 ```
 
+#### Without an iMIS ID
+
+Running requests without an iMIS ID set will result in query results returned from the API.
+
 ### Business Object and Panel Actions
 
 Business Objects and Panels support the following actions.
@@ -88,11 +92,15 @@ Panels require passing in the ordinal identifier as an argument, except for `POS
 To fetch member data, run e.g.:
 
 ```ruby
-api.imis_id = 31092
-
 data = api.on('ABC_ASC_Individual_Demog').get
 ```
 
+You can also pass in specific field names to filter the returned member data, e.g.:
+
+```ruby
+data = api.on('ABC_ASC_Individual_Demog').get('TotMMS', 'MMS_Updated')
+```
+
 Alias: `read`
 
 #### GET Field
@@ -100,20 +108,26 @@ Alias: `read`
 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')
 ```
 
 Alias: `fetch`
 
+#### GET Fields
+
+To fetch multiple specific fields from member data, run e.g.:
+
+```ruby
+data = api.on('ABC_ASC_Individual_Demog').get_fields('TotMMS', 'MMS_Updated')
+```
+
+Alias: `fetch_all`
+
 #### 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)
 ```
@@ -128,8 +142,6 @@ Alias: `patch`
 To update member data, run e.g.:
 
 ```ruby
-api.imis_id = 31092
-
 update = api.on('ABC_ASC_Individual_Demog').put(complete_imis_object)
 ```
 
@@ -156,8 +168,6 @@ Alias: `create`
 To remove member data, run e.g.:
 
 ```ruby
-api.imis_id = 31092
-
 api.on('ABC_ASC_Individual_Demog').delete
 ```
 
@@ -200,25 +210,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'].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:
@@ -270,9 +282,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
 
@@ -162,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
@@ -32,28 +34,35 @@ module Usps
 
       # Get a business object for the current member
       #
-      # @return [Hash] Response data from the API
+      # If +fields+ is provided, will return only those field values
       #
-      def get
-        request = Net::HTTP::Get.new(uri)
-        result = submit(uri, authorize(request))
-        JSON.parse(result.body)
-      end
+      # @param fields [String] Field names to return
+      #
+      # @return [Hash, Array<Hash>] Response data from the API
+      #
+      def get(*fields) = fields.any? ? get_fields(*fields) : raw_object
       alias read get
 
       # Get a single named field from a business object for the current member
       #
-      # @param name [String] Field name to return
+      # @param field [String] Field name to return
       #
       # @return [Hash] Response data from the API
       #
-      def get_field(name)
-        values = get['Properties']['$values']
-        value = values.find { it['Name'] == name }['Value']
+      def get_field(field) = extract_field_value(raw_object_values, field)
+      alias fetch get_field
 
-        value.is_a?(String) ? value : value['$value']
+      # Get named fields from a business object for the current member
+      #
+      # @param names [Array<String>] Field names to return
+      #
+      # @return [Array<Hash>] Response data from the API
+      #
+      def get_fields(*fields)
+        values = raw_object_values
+        fields.map { extract_field_value(values, it) }
       end
-      alias fetch get_field
+      alias fetch_all get_fields
 
       # Update only specific fields on a business object for the current member
       #
@@ -61,10 +70,7 @@ module Usps
       #
       # @return [Hash] Response data from the API
       #
-      def put_fields(fields)
-        updated = filter_fields(fields)
-        put(updated)
-      end
+      def put_fields(fields) = put(filter_fields(fields))
       alias patch put_fields
 
       # Update a business object for the current member
@@ -75,12 +81,7 @@ module Usps
       #
       # @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
+      def put(body) = put_object(Net::HTTP::Put.new(uri), body)
       alias update put
 
       # Create a business object for the current member
@@ -89,23 +90,14 @@ module Usps
       #
       # @return [Hash] Response data from the API
       #
-      def post(body)
-        request = Net::HTTP::Post.new(uri(id: ''))
-        request.body = JSON.dump(body)
-        result = submit(uri, authorize(request))
-        JSON.parse(result.body)
-      end
+      def post(body) = put_object(Net::HTTP::Post.new(uri(id: '')), body)
       alias create post
 
       # Remove a business object for the current member
       #
-      # @return [String] Error response body from the API, or empty string on success
+      # @return [true] Only on success response (i.e. blank string from the API)
       #
-      def delete
-        request = Net::HTTP::Delete.new(uri)
-        result = submit(uri, authorize(request))
-        result.body
-      end
+      def delete = submit(uri, authorize(Net::HTTP::Delete.new(uri))).body == '' # rubocop:disable Naming/PredicateMethod
       alias destroy delete
 
     private
@@ -157,6 +149,35 @@ module Usps
           end
         end
       end
+
+      # Get a raw object response from the API
+      #
+      # Useful for stubbing data in tests
+      #
+      def raw_object
+        request = Net::HTTP::Get.new(uri)
+        result = submit(uri, authorize(request))
+        JSON.parse(result.body)
+      end
+
+      # Get just the property values from an object response from the API
+      #
+      def raw_object_values
+        raw_object['Properties']['$values']
+      end
+
+      def extract_field_value(values, field)
+        value = values.find { it['Name'] == field }['Value']
+        value.is_a?(String) ? value : value['$value']
+      end
+
+      # Upload an object to the API
+      #
+      def put_object(request, body)
+        request.body = JSON.dump(body)
+        result = submit(uri, authorize(request))
+        JSON.parse(result.body)
+      end
     end
   end
 end

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