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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb187f7e4a8497da991378eec6a9893c5c2a5e637b808a9225ab72ebd5ee385d
-  data.tar.gz: 0d09118f25fce28b94ddbc1257e9670fe3454e34df094885bc9cf35cbb1a86a0
+  metadata.gz: 8f1db4f3db3cd61b247cdef10a3f017ea8efbe7fbf3f98ed17d80fbaa56947b7
+  data.tar.gz: 837b83d46d08d02bd6a27442adde8f5fbf7857050df06efd602583205745dad6
 SHA512:
-  metadata.gz: f50698bc529a6d66d3c69e201d696cdfde1f24c7bf414ab1f655ebdf3b21e1bd512b8e00476ffa62e3ded1a50d72e82586b8f11c002291c5a8038ad5f4cdd2d6
-  data.tar.gz: '09e2849e666c312d0a974efc14b5133ac6e2f0ef181a6715f83ae420b6ba48f6a1566cc749a1dcbce614989c9e5b9fa343ba4dd6a56f1ecd47a9a14b7572617a'
+  metadata.gz: 0e49fd7400ee2fb1932a4321944122f9e6864a89901e56b2c2a5f4b342f4426a039bd789e89159bdec3579725af733213ff5b4b9694d6a59d04901506a71f8b6
+  data.tar.gz: d9dff6ac6e989b163d009a6fe247fed18645a078f5cc00468f5b4011e47050336d561d4bef30f552c51fe531fec3c567086da4d2d5cd6a54bfe0d4a39246d2ff

data/.rubocop.yml

@@ -1,4 +1,4 @@
-require:
+plugins:
   - rubocop-rspec
 
 AllCops:
@@ -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,81 +1,115 @@
 PATH
   remote: .
   specs:
-    usps-imis-api (1.0.0.pre.rc.4)
+    usps-imis-api (1.0.0.pre.rc.7)
+      activesupport (~> 8.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    ast (2.4.2)
+    activesupport (8.1.0)
+      base64
+      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.3)
+    base64 (0.3.0)
+    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)
-    erb (5.0.3)
+    dotenv (3.1.8)
+    drb (2.2.3)
+    erb (5.1.1)
+    i18n (1.14.7)
+      concurrent-ruby (~> 1.0)
     io-console (0.8.1)
     irb (1.15.2)
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.7.2)
-    language_server-protocol (3.17.0.3)
-    parallel (1.26.3)
-    parser (3.3.5.0)
+    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.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)
-    unicode-display_width (2.6.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.1.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.6.0'
+gem 'usps-imis-api'
 ```
 
 ## Setup
@@ -25,11 +25,17 @@ 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']
+
+  # These options will use these defaults
+  config.logger = ActiveSupport::TaggedLogging.new(Logger.new($stdout))
+  config.logger.level = :info
 end
 ```
 
@@ -75,23 +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']
 ```
 
-### PUT Fields
+Alias: `read`
 
-To update member data, run e.g.:
+#### GET Field
+
+To fetch a specific field from member data, run e.g.:
+
+```ruby
+tot_mms = api.on('ABC_ASC_Individual_Demog').get_field('TotMMS')
+```
+
+You can also access fields directly on the Business Object or Panel like a Hash:
+
+```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)
 ```
@@ -99,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).
+
+Alias: `update`
 
-### POST
+#### POST
 
 To create new member data, run e.g.:
 
@@ -121,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
 
@@ -140,19 +199,38 @@ 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)
@@ -168,24 +246,40 @@ 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.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:
@@ -202,11 +296,11 @@ previous value.
 
 ```ruby
 api.with(31092) do
-  # These four requests are identical:
+  # 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)
 
@@ -220,12 +314,52 @@ api.with(6374) do
 end
 ```
 
-## Exception Handling
+```ruby
+api.with(31092) do
+  # These requests are identical:
 
-Exception and error response handling will be added later.
+  on('ABC_ASC_Individual_Demog') do
+    get.raw['Properties']['$values'].find { it['Name'] == 'TotMMS' }['Value']['$value']
 
-To print exception information to STDERR when raising, set the environment
-variable `IMIS_ERROR_LOG_TO_STDERR=true`.
+    get['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
+api.with(31092).on('ABC_ASC_Individual_Demog').get_field('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::Error`.
 
 ## Automated Testing and Linting
 
@@ -241,6 +375,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

@@ -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,20 @@ 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 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 +150,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 = {