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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c0abf715f3c6019016bc6b8bdf867ce9d83234ba093c6150a4885997e9156f4
-  data.tar.gz: bcd2727e5f74b7a8681ae8ea1c510539fc24b62085719b439a01a331989a59c9
+  metadata.gz: 07d2a2b0c67186b6c3e2a8c8f3dd1694341b399d2ae95bbffcc8db568a3cdca2
+  data.tar.gz: b6315dd73aff2c70aabf352dfa2b25b905cf11404894a37814a77d7c2c349ef7
 SHA512:
-  metadata.gz: e0f98c36fd93ae643a949980e590fbb327cc40e1947ef5c8b530156e3961073082702dd38916fa27da4db10c642316c3c3db9f97d82d2f7c616032917cea22f1
-  data.tar.gz: 3195ecb427cff0fea1c6d1cef0d877507c2bb7baaa3a3db6d669f281048a03de7fb06c15e3b5f1cfe36625ece30d2e890f05202accfaf56148de40dda0fdce4d
+  metadata.gz: 7e4bd50ec6137ffed9a3035d135fbe62d5ec66846e6b11e4b4c3f2db38cb5f20d09f9ca9b41553291a649859dd8aade13318eed85e0d92645e60734545a3f5c2
+  data.tar.gz: 3bd9f6eb055de1fb5aecbd1c40166f7db9a781cecf5fb93fbe8086636c379c8081d5a97271c5a6f27354439cb7410bf1f13cd7a1c39cb6ccb36ede0ccecf5630

data/.rubocop.yml

@@ -1,4 +1,4 @@
-require:
+plugins:
   - rubocop-rspec
 
 AllCops:
@@ -84,3 +84,6 @@ Security/JSONLoad:
   Enabled: true
 Security/YAMLLoad:
   Enabled: true
+
+RSpec/NestedGroups:
+  Max: 4

data/Gemfile.lock

@@ -1,37 +1,36 @@
 PATH
   remote: .
   specs:
-    usps-imis-api (1.0.0.pre.rc.5)
+    usps-imis-api (1.0.0.pre.rc.8)
       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

@@ -13,7 +13,7 @@ gem install usps-imis-api
 or add this line to your Gemfile:
 
 ```ruby
-gem 'usps-imis-api', '~> 0.6.3'
+gem 'usps-imis-api'
 ```
 
 ## Setup
@@ -32,6 +32,10 @@ Usps::Imis.configure do |config|
   config.imis_id_query_name = ENV['IMIS_ID_QUERY_NAME']
   config.username = ENV['IMIS_USERNAME']
   config.password = ENV['IMIS_PASSWORD']
+
+  # These options will use these defaults
+  config.logger = ActiveSupport::TaggedLogging.new(Logger.new($stdout))
+  config.logger.level = :info
 end
 ```
 
@@ -77,33 +81,72 @@ You can also manually set the current ID, if you already have it for a given mem
 api.imis_id = imis_id
 ```
 
-### GET
+#### 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.
+
+Panels require passing in the ordinal identifier as an argument, except for `POST`.
+
+#### GET
 
 To fetch member data, run e.g.:
 
 ```ruby
-api.imis_id = 31092
+data = api.on('ABC_ASC_Individual_Demog').get
+```
+
+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')
+```
+
+The response from `get` behaves like a Hash, but directly accesses property values by name.
+If you need to access the rest of the underlying data, use the `raw` method:
+
+```ruby
 data = api.on('ABC_ASC_Individual_Demog').get
+data['TotMMS']
+data.raw['EntityTypeName']
 ```
 
-### GET Field
+Alias: `read`
+
+#### GET Field
 
 To fetch a specific field from member data, run e.g.:
 
 ```ruby
-api.imis_id = 31092
-
 tot_mms = api.on('ABC_ASC_Individual_Demog').get_field('TotMMS')
 ```
 
-### PUT Fields
+You can also access fields directly on the Business Object or Panel like a Hash:
 
-To update member data, run e.g.:
+```ruby
+tot_mms = api.on('ABC_ASC_Individual_Demog')['TotMMS']
+```
+
+Alias: `fetch`
+
+#### GET Fields
+
+To fetch multiple specific fields from member data, run e.g.:
 
 ```ruby
-api.imis_id = 31092
+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
 data = { 'MMS_Updated' => Time.now.strftime('%Y-%m-%dT%H:%M:%S'), 'TotMMS' => new_total }
 update = api.on('ABC_ASC_Individual_Demog').put_fields(data)
 ```
@@ -111,19 +154,23 @@ update = api.on('ABC_ASC_Individual_Demog').put_fields(data)
 This method fetches the current data structure, and filters it down to just what you want to
 update, to reduce the likelihood of update collisions or type validation failures.
 
-### PUT
+Alias: `patch`
+
+#### PUT
 
 To update member data, run e.g.:
 
 ```ruby
-api.imis_id = 31092
-
 update = api.on('ABC_ASC_Individual_Demog').put(complete_imis_object)
 ```
 
-This method requires a complete iMIS data structure.
+This method requires a complete iMIS data structure. However, any properties not included will be
+left unmodified (meaning this also effectively handles `PATCH`, though iMIS does not accept that
+HTTP verb).
 
-### POST
+Alias: `update`
+
+#### POST
 
 To create new member data, run e.g.:
 
@@ -133,17 +180,17 @@ created = api.on('ABC_ASC_Individual_Demog').post(complete_imis_object)
 
 This method requires a complete iMIS data structure.
 
-### DELETE
+Alias: `create`
+
+#### DELETE
 
 To remove member data, run e.g.:
 
 ```ruby
-api.imis_id = 31092
-
 api.on('ABC_ASC_Individual_Demog').delete
 ```
 
-This returns a blank string on success.
+Alias: `destroy`
 
 ### QUERY
 
@@ -152,22 +199,42 @@ Run an IQA Query
 `query_params` is a hash of shape: `{ param_name => param_value }`
 
 ```ruby
-api.query(query_name, query_params)
+query = api.query(query_name, query_params)
+
+query.each do |item|
+  # Download all pages of the query, then iterate on the results
+end
+
+query.find_each do |item|
+  # Iterate one page at a time, fetching new pages automatically
+end
 ```
 
 ### Field Mapper
 
 For fields that have already been mapped between the ITCom database and iMIS, you can use the
-Mapper class to further simplify the update interface:
+Mapper class to further simplify the `fetch` / `update` interfaces:
+
+```ruby
+mm = api.mapper.fetch(:mm)
+mm = api.mapper[:mm]
+```
 
 ```ruby
 api.mapper.update(mm: 15)
 ```
 
-For simplicity, you can also call `update` on the `Api` class directly:
+For simplicity, you can also call `fetch` (or simply use Hash access syntax) and `update` on the
+`Api` class directly:
+
+```ruby
+api.fetch(:mm)
+api[:mm]
+```
 
 ```ruby
 api.update(mm: 15)
+api[:mm] = 15
 ```
 
 If there is no known mapping for the requested field, the Mapper will give up, but will provide
@@ -180,24 +247,41 @@ 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)
 
+# All of these options are identical
+#
+vsc.get(1417, 'Quantity').first
+vsc.get(1417)['Quantity']
+vsc[1417, 'Quantity']
+vsc.get(1417).raw['Properties']['$values'].find { it['Name'] == 'Quantity' }['Value']['$value']
+vsc.get_field(1417, 'Quantity')
+
 created = vsc.create(certificate: 'E136924', year: 2024, count: 42)
-ordinal = created['Properties']['$values'][1]['Value']['$value']
+
+# Get the Ordinal identifier from the response
+#
+# All of these options are identical
+#
+ordinal = created.ordinal
+ordinal = created['Ordinal']
+ordinal = created.raw['Properties']['$values'].find { it['Name'] == 'Ordinal' }['Value']['$value']
+ordinal = created.raw['Identity']['IdentityElements']['$values'][1].to_i # Value is duplicated here
 
 vsc.update(certificate: 'E136924', year: 2024, count: 43, ordinal: ordinal)
 
+vsc.put_fields(ordinal, 'Quantity' => 44)
+vsc['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:
@@ -216,14 +300,19 @@ previous value.
 api.with(31092) do
   # These requests are identical:
 
-  on('ABC_ASC_Individual_Demog') { put('TotMMS' => 15) }
+  on('ABC_ASC_Individual_Demog') { put_fields('TotMMS' => 15) }
 
-  on('ABC_ASC_Individual_Demog').put('TotMMS' => 15)
+  on('ABC_ASC_Individual_Demog').put_fields('TotMMS' => 15)
 
   mapper.update(mm: 15)
 
   update(mm: 15)
+
+  mapper[:mm] = 15
 end
+
+# This request fetches the same data, but leaves the iMIS ID selected
+api.with(31092)[:mm] = 15
 ```
 
 ```ruby
@@ -237,21 +326,48 @@ 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
+    get.raw['Properties']['$values'].find { it['Name'] == 'TotMMS' }['Value']['$value']
+
+    get['TotMMS']
 
-  on('ABC_ASC_Individual_Demog') { get_field('TotMMS') }
+    get_field('TotMMS')
+
+    get_fields('TotMMS').first
+  end
 
   on('ABC_ASC_Individual_Demog').get_field('TotMMS')
+
+  on('ABC_ASC_Individual_Demog')['TotMMS']
 end
 
-# This request fetches the same data, but leaves the iMIS ID selected
+# These requests fetch the same data, but leave the iMIS ID selected
 api.with(31092).on('ABC_ASC_Individual_Demog').get_field('TotMMS')
+api.with(31092).on('ABC_ASC_Individual_Demog')['TotMMS']
+```
+
+### Data Methods
+
+Data responses from the API can be handled as a standard Hash using the `raw` method.
+
+If you need to access all of the property values, you can use the `properties` method.
+By default, this will exclude the `ID` and `Ordinal` properties; they can be included with
+`properties(include_ids: true)`.
+
+## 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,10 @@
 # frozen_string_literal: true
 
+require_relative 'requests'
+require_relative 'business_object'
+require_relative 'mapper'
+require_relative 'query'
+
 module Usps
   module Imis
     # The core API wrapper
@@ -11,10 +16,6 @@ module Usps
       #
       AUTHENTICATION_PATH = 'Token'
 
-      # Endpoint for IQA query requests
-      #
-      QUERY_PATH = 'api/Query'
-
       # API bearer token
       #
       attr_reader :token
@@ -48,9 +49,9 @@ 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
+        @imis_id = id&.to_i
       end
 
       # Convert a member's certificate number into an iMIS ID number
@@ -60,13 +61,12 @@ 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']
+          self.imis_id = query(Imis.configuration.imis_id_query_name, { certificate: }).first['ID'].to_i
         rescue StandardError
-          raise Error::ApiError, 'Member not found'
+          raise Errors::NotFoundError, 'Member not found'
         end
       end
 
@@ -97,7 +97,7 @@ module Usps
         end
       end
 
-      # Run an IQA Query
+      # Build an IQA Query interface
       #
       # @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 }+
@@ -105,21 +105,7 @@ module Usps
       # @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.configuration.hostname, path))
-        request = Net::HTTP::Get.new(uri)
-        result = submit(uri, authorize(request))
-        JSON.parse(result.body)
-      end
-
-      # An instance of +BusinessObject+, using this instance as its parent +Api+
-      #
-      # @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)
-      #
-      def business_object(business_object_name, url_id: nil)
-        BusinessObject.new(self, business_object_name, url_id:)
+        Query.new(self, query_name, query_params)
       end
 
       # Run requests as DSL, with specific +BusinessObject+ only maintained for this scope
@@ -127,15 +113,13 @@ module Usps
       # If no block is given, this returns the specified +BusinessObject+.
       #
       # @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 ordinal [Integer] Ordinal to build override ID param of the URL (e.g. used for Panels)
       #
-      def on(business_object_name, url_id: nil, &)
-        object = business_object(business_object_name, url_id:)
+      def on(business_object_name, ordinal: nil, &)
+        object = BusinessObject.new(self, business_object_name, ordinal:)
         return object unless block_given?
 
-        result = nil
-        object.tap { |obj| result = obj.instance_eval(&) }
-        result
+        object.instance_eval(&)
       end
 
       # An instance of +Mapper+, using this instance as its parent +Api+
@@ -144,20 +128,25 @@ module Usps
         @mapper ||= Mapper.new(self)
       end
 
+      # Convenience alias for reading mapped fields
+      #
+      def fetch(field_key) = mapper.fetch(field_key)
+      alias [] fetch
+
       # Convenience alias for updating mapped fields
       #
-      def update(data)
-        mapper.update(data)
-      end
+      def put_field(field_key, value) = update(field_key => value)
+      alias []= put_field
+
+      # Convenience alias for updating mapped fields
+      #
+      def update(data) = mapper.update(data)
 
       # Convenience accessor for available Panel objects, each using this instance as its parent
       # +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
@@ -166,9 +155,13 @@ module Usps
 
     private
 
+      def logger = Imis.logger('Api')
+
       # Authenticate to the iMIS API, and store the access token and expiration time
       #
       def authenticate
+        logger.debug 'Authenticating with iMIS'
+
         uri = URI(File.join(Imis.configuration.hostname, AUTHENTICATION_PATH))
         req = Net::HTTP::Post.new(uri)
         authentication_data = {