usps-imis-api 0.9.7 → 0.9.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a78cd8daed5969574e8ec5fc3120a8a5a6c362e519918620ce41c2ed0fc0f26c
-  data.tar.gz: 0f20aa470ec2f2b8501f670046ee1071fea8552c22dd9f70165fb2ea986a46aa
+  metadata.gz: cc0ebcfc78fa3368d5901ad0e9bf03b6149ec0b2e84fecbb25e2449ba866fe09
+  data.tar.gz: 04a02698dd0936b051086fc57714a00d6fe90150f82002f3a944a47189ecd120
 SHA512:
-  metadata.gz: 41f2a2c9082ce49399a1a9b3e44ddd2cb86a8624d112ea6c36875e05da74db61cd6272f96819d0d889c5ac83e857f900ecaad357da9dd25a3b3094b7354dbce4
-  data.tar.gz: 131e53225ae3d111b49c64302a99d5b32227e45b2734c42ea2131d5de986c60c2d359c43aef10a5191ce03d6406c5f6bbe0fcfadd11843347533cef0dcd555f3
+  metadata.gz: 60cb55c6754bf92f8ddb804726d6dc0272bfd09c09afb912dc9e5d0fd6e0b7b4984cfe1ea9761b22c38e3a855f0b7675c492c9cb811b9afc2a1e742ebdf2fe49
+  data.tar.gz: f7824ff8fae0a47456811457ead9f91d2bd8c6a481f9b70342bb76cb66b29f93b60ce03980ea339f56baf5099e0b250f10b9f7990be0f0bc30535be3e109d76c

data/.rubocop.yml

@@ -84,3 +84,6 @@ Security/JSONLoad:
   Enabled: true
 Security/YAMLLoad:
   Enabled: true
+
+RSpec/NestedGroups:
+  Max: 4

data/Gemfile

@@ -10,3 +10,7 @@ gem 'rspec',         '>= 3.13.0'
 gem 'rubocop',       '>= 1.66.1'
 gem 'rubocop-rspec', '>= 3.1.0'
 gem 'simplecov',     '>= 0.22.0'
+
+gem 'cgi',           '>= 0.5.0' # Required to resolve a loading issue for VCR
+gem 'vcr',           '>= 6.3.1'
+gem 'webmock',       '>= 3.25.2'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    usps-imis-api (0.9.7)
+    usps-imis-api (0.9.9)
       activesupport (~> 8.0)
 
 GEM
@@ -20,17 +20,24 @@ GEM
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
       uri (>= 0.13.1)
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
     ast (2.4.3)
     base64 (0.3.0)
     bigdecimal (3.3.1)
+    cgi (0.5.0)
     concurrent-ruby (1.3.5)
     connection_pool (2.5.4)
+    crack (1.0.1)
+      bigdecimal
+      rexml
     date (3.4.1)
     diff-lcs (1.6.2)
     docile (1.4.1)
     dotenv (3.1.8)
     drb (2.2.3)
     erb (5.1.1)
+    hashdiff (1.2.1)
     i18n (1.14.7)
       concurrent-ruby (~> 1.0)
     io-console (0.8.1)
@@ -38,7 +45,7 @@ GEM
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.15.1)
+    json (2.15.2)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
@@ -54,6 +61,7 @@ GEM
     psych (5.2.6)
       date
       stringio
+    public_suffix (6.0.2)
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.3.0)
@@ -64,6 +72,7 @@ GEM
     regexp_parser (2.11.3)
     reline (0.6.2)
       io-console (~> 0.5)
+    rexml (3.4.4)
     rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
@@ -110,12 +119,19 @@ GEM
       unicode-emoji (~> 4.1)
     unicode-emoji (4.1.0)
     uri (1.0.4)
+    vcr (6.3.1)
+      base64
+    webmock (3.25.2)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
 
 PLATFORMS
   arm64-darwin-23
   ruby
 
 DEPENDENCIES
+  cgi (>= 0.5.0)
   dotenv (>= 3.1.4)
   irb (>= 1.15.2)
   rake (>= 13.2.1)
@@ -124,6 +140,8 @@ DEPENDENCIES
   rubocop-rspec (>= 3.1.0)
   simplecov (>= 0.22.0)
   usps-imis-api!
+  vcr (>= 6.3.1)
+  webmock (>= 3.25.2)
 
 BUNDLED WITH
    2.5.6

data/Readme.md

@@ -213,7 +213,7 @@ 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 fetch / update interfaces:
+Mapper class to further simplify the `fetch` / `update` interfaces:
 
 ```ruby
 mm = api.mapper.fetch(:mm)
@@ -234,6 +234,7 @@ 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
@@ -272,6 +273,7 @@ ordinal = created.raw['Identity']['IdentityElements']['$values'][1].to_i # Value
 vsc.update(certificate: 'E136924', year: 2024, count: 43, ordinal: ordinal)
 
 vsc.put_fields(ordinal, 'Quantity' => 44)
+vsc['Quantity'] = 44
 
 vsc.destroy(ordinal)
 ```
@@ -305,7 +307,12 @@ api.with(31092) do
   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
@@ -333,8 +340,9 @@ api.with(31092) do
   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
@@ -369,6 +377,8 @@ Testing is available by running:
 bundle exec rspec
 ```
 
+API web requests are sanitized and recorded using VCR.
+
 Linting is available by running:
 
 ```ruby

data/lib/usps/imis/api.rb

@@ -36,11 +36,10 @@ module Usps
 
       # A new instance of +Api+
       #
-      # @param skip_authentication [bool] Skip authentication on initialization (used for tests)
       # @param imis_id [Integer, String] iMIS ID to select immediately on initialization
       #
-      def initialize(skip_authentication: false, imis_id: nil)
-        authenticate unless skip_authentication
+      def initialize(imis_id: nil)
+        authenticate
         self.imis_id = imis_id if imis_id
       end
 
@@ -104,9 +103,7 @@ module Usps
       #
       # @return [Hash] Response data from the API
       #
-      def query(query_name, query_params = {})
-        Query.new(self, query_name, query_params)
-      end
+      def query(query_name, query_params = {}) = Query.new(self, query_name, **query_params)
 
       # Run requests as DSL, with specific +BusinessObject+ only maintained for this scope
       #
@@ -133,6 +130,11 @@ module Usps
       def fetch(field_key) = mapper.fetch(field_key)
       alias [] fetch
 
+      # Convenience alias for updating mapped fields
+      #
+      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)
@@ -157,20 +159,22 @@ module Usps
       def authenticate
         logger.debug 'Authenticating with iMIS'
 
-        uri = URI(File.join(Imis.configuration.hostname, AUTHENTICATION_PATH))
-        req = Net::HTTP::Post.new(uri)
-        authentication_data = {
+        request = http_post
+        request.body = URI.encode_www_form(
           grant_type: 'password',
           username: Imis.configuration.username,
           password: Imis.configuration.password
-        }
-        req.body = URI.encode_www_form(authentication_data)
-        result = submit(uri, req)
+        )
+        result = submit(uri, request)
         json = JSON.parse(result.body)
 
         @token = json['access_token']
         @token_expiration = Time.parse(json['.expires'])
       end
+
+      # URI for the authentication endpoint
+      #
+      def uri(...) = URI(File.join(Imis.configuration.hostname, AUTHENTICATION_PATH))
     end
   end
 end

data/lib/usps/imis/business_object.rb

@@ -66,6 +66,16 @@ module Usps
       end
       alias fetch_all get_fields
 
+      # Update a single named field on a business object for the current member
+      #
+      # @param field [String] Name of the field
+      # @param value Value of the field
+      #
+      # @return [Usps::Imis::Data] Response data from the API
+      #
+      def put_field(field, value) = put(filter_fields(field => value))
+      alias []= put_field
+
       # Update only specific fields on a business object for the current member
       #
       # @param fields [Hash] Conforms to pattern +{ field_key => value }+
@@ -83,7 +93,7 @@ module Usps
       #
       # @return [Usps::Imis::Data] Response data from the API
       #
-      def put(body) = put_object(Net::HTTP::Put.new(uri), body)
+      def put(body) = put_object(http_put, body)
       alias update put
 
       # Create a business object for the current member
@@ -92,14 +102,14 @@ module Usps
       #
       # @return [Usps::Imis::Data] Response data from the API
       #
-      def post(body) = put_object(Net::HTTP::Post.new(uri(id: '')), body)
+      def post(body) = put_object(http_post, body)
       alias create post
 
       # Remove a business object for the current member
       #
       # @return [true] Only on success response (i.e. blank string from the API)
       #
-      def delete = submit(uri, authorize(Net::HTTP::Delete.new(uri))).body == '' # rubocop:disable Naming/PredicateMethod
+      def delete = submit(uri, authorize(http_delete)).body == '' # rubocop:disable Naming/PredicateMethod
       alias destroy delete
 
       # Ruby 3.5 instance variable filter
@@ -163,9 +173,8 @@ module Usps
       # Useful for stubbing data in tests
       #
       def raw_object
-        request = Net::HTTP::Get.new(uri)
-        result = submit(uri, authorize(request))
-        result = Data.from_json(result.body)
+        response = submit(uri, authorize(http_get))
+        result = Data.from_json(response.body)
         JSON.pretty_generate(result).split("\n").each { logger.debug "    -> #{it}" }
         result
       end
@@ -174,8 +183,8 @@ module Usps
       #
       def put_object(request, body)
         request.body = JSON.dump(body)
-        result = submit(uri, authorize(request))
-        result = Data.from_json(result.body)
+        response = submit(uri, authorize(request))
+        result = Data.from_json(response.body)
         JSON.pretty_generate(result).split("\n").each { logger.debug "    -> #{it}" }
         result
       end

data/lib/usps/imis/data.rb

@@ -50,6 +50,10 @@ module Usps
           .index_with { self[it] }
       end
 
+      def []=(...)
+        raise Errors::ApiError, '`Data` does not support setting values. If you need to modify it, call `.raw` on it.'
+      end
+
       def inspect
         stringio = StringIO.new
         PP.pp(self, stringio)

data/lib/usps/imis/error.rb

@@ -17,6 +17,8 @@ module Usps
       def initialize(message, metadata = {})
         super(message)
         @metadata = metadata
+
+        Imis.logger(self.class.name).error self
       end
 
       # Additional metadata to include in Bugsnag reports

data/lib/usps/imis/mapper.rb

@@ -28,6 +28,16 @@ module Usps
         @api.imis_id = imis_id if imis_id
       end
 
+      # Get a member's data for a specific field by arbitrary field name
+      #
+      # Does not require knowing which business object / iMIS-specific field name to use
+      #
+      # Only available for fields defined in +FIELD_MAPPING+
+      #
+      # @param field_key [Symbol] Internal name of the field
+      #
+      # @return Value of the field
+      #
       def fetch(field_key)
         missing_mapping!(field_key) unless FIELD_MAPPING.key?(field_key.to_sym)
 
@@ -36,6 +46,19 @@ module Usps
       end
       alias [] fetch
 
+      # Update a member's data for a specific field by arbitrary field name
+      #
+      # Does not require knowing which business object / iMIS-specific field name to use
+      #
+      # Only available for fields defined in +FIELD_MAPPING+
+      #
+      # @param field_key [Symbol] Internal name of the field
+      #
+      # @return Value of the field
+      #
+      def put_field(field_key, value) = update(field_key => value)
+      alias []= put_field
+
       # Update a member's data on multiple affected business objects by arbitrary field names
       #
       # Does not require knowing which business object / iMIS-specific field name to use

data/lib/usps/imis/panels/base_panel.rb

@@ -49,6 +49,16 @@ module Usps
         def get_fields(ordinal, *fields) = api.on(business_object, ordinal:).get_fields(*fields)
         alias fetch_all get_fields
 
+        # Update a single named field on a business object for the current member
+        #
+        # @param field [String] Name of the field
+        # @param value Value of the field
+        #
+        # @return [Usps::Imis::Data] Response data from the API
+        #
+        def put_field(field, value) = api.on(business_object, ordinal:).put_field(field, value)
+        alias []= put_field
+
         # Update only specific fields on a Panel for the current member
         #
         # @param ordinal [Integer] The ordinal identifier for the desired object

data/lib/usps/imis/query.rb

@@ -24,20 +24,32 @@ module Usps
       #
       attr_reader :query_params
 
+      # Current page size for paging through the Query
+      #
+      attr_accessor :page_size
+
       # Current offset for paging through the Query
       #
-      attr_reader :offset
+      attr_accessor :offset
+
+      # Count of records processed
+      #
+      attr_reader :count
 
       # A new instance of +Query+
       #
       # @param api [Api] Parent to use for making requests
       # @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 }+
+      # @param page_size [Integer] Number of records to return on each request page
+      # @param offset [Integer] Offset index of records to return on next request page
+      # @param query_params [Hash] Conforms to pattern +{ param_name => param_value }+
       #
-      def initialize(api, query_name, query_params)
+      def initialize(api, query_name, page_size: 100, offset: nil, **query_params)
         @api = api
         @query_name = query_name
         @query_params = query_params
+        @page_size = page_size
+        @offset = offset
       end
 
       # Iterate through all results from the query
@@ -53,26 +65,37 @@ module Usps
       # Iterate through all results from the query, fetching one page at a time
       #
       def find_each(&)
-        result = { 'HasNext' => true }
-        count = 0
+        result = reset!
 
         while result['HasNext']
-          logger.info 'Fetching IQA Query page'
+          result = fetch_next.tap do |result_page|
+            result_page['Items']['$values'].map { it.except('$type') }.each(&)
+          end
+        end
 
-          result = fetch
+        nil
+      end
 
-          count += result['Count'] || 0
-          logger.info "  -> #{count} / #{result['TotalCount']} #{'item'.pluralize(count)}"
-          logger.debug '  -> Query page data:'
-          JSON.pretty_generate(result).split("\n").each { logger.debug "    -> #{it}" }
+      # Fetch a raw query page
+      #
+      def fetch = JSON.parse(submit(uri, authorize(http_get)).body)
 
-          items = result['Items']['$values'].map { it.except('$type') }
-          @offset = result['NextOffset']
+      # Fetch the next raw query page, and update the current offset
+      #
+      def fetch_next
+        logger.info 'Fetching IQA Query page'
 
-          items.each(&)
-        end
+        result = fetch
 
-        nil
+        @count += result['Count'] || 0
+        total = result['TotalCount']
+        logger.info "  -> #{@count} / #{total} #{'item'.pluralize(total)}"
+        logger.debug '  -> Query page data:'
+        JSON.pretty_generate(result).split("\n").each { logger.debug "    -> #{it}" }
+
+        @offset = result['NextOffset']
+
+        result
       end
 
       # Ruby 3.5 instance variable filter
@@ -84,11 +107,20 @@ module Usps
       def token = api.token
       def token_expiration = api.token_expiration
 
-      def path = "#{QUERY_PATH}?#{query_params.merge(QueryName: query_name, Offset: offset).to_query}"
+      def path_params = query_params.merge(QueryName: query_name).merge({ Offset: offset, Limit: page_size }.compact)
+      def path = "#{QUERY_PATH}?#{path_params.to_query}"
       def uri = URI(File.join(Imis.configuration.hostname, path))
-      def fetch = JSON.parse(submit(uri, authorize(Net::HTTP::Get.new(uri))).body)
 
       def logger = Imis.logger('Query')
+
+      def reset!
+        logger.debug 'Resetting Query progress'
+
+        @count = 0
+        @offset = 0
+
+        { 'HasNext' => true }
+      end
     end
   end
 end

data/lib/usps/imis/requests.rb

@@ -9,6 +9,11 @@ module Usps
 
       def logger = Imis.logger
 
+      def http_get = Net::HTTP::Get.new(uri)
+      def http_put = Net::HTTP::Put.new(uri)
+      def http_post = Net::HTTP::Post.new(uri(id: ''))
+      def http_delete = Net::HTTP::Delete.new(uri)
+
       def client(uri)
         Net::HTTP.new(uri.host, uri.port).tap do |http|
           http.use_ssl = true
@@ -45,9 +50,8 @@ module Usps
         body = request.body.dup
 
         Imis.config.filtered_parameters.each do |parameter|
-          body =
-            body.gsub(Imis.config.public_send(parameter), '[FILTERED]')
-                .gsub(CGI.escape(Imis.config.public_send(parameter)), '[FILTERED]')
+          body.gsub!(Imis.config.public_send(parameter), '[FILTERED]')
+          body.gsub!(CGI.escape(Imis.config.public_send(parameter)), '[FILTERED]')
         end
 
         body

data/lib/usps/imis/version.rb

@@ -2,6 +2,6 @@
 
 module Usps
   module Imis
-    VERSION = '0.9.7'
+    VERSION = '0.9.9'
   end
 end

data/spec/fixtures/vcr_cassettes/Usps_Imis_Api/_authorize/automatically_refreshes_an_expired_token.yml

@@ -0,0 +1,67 @@
+---
+http_interactions:
+- request:
+    method: post
+    uri: https://abcdev.imiscloud.com/Token
+    body:
+      encoding: US-ASCII
+      string: grant_type=password&username=<USERNAME>&password=<PASSWORD>
+    headers:
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+      Accept:
+      - "*/*"
+      User-Agent:
+      - Ruby
+      Host:
+      - abcdev.imiscloud.com
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Date:
+      - Sun, 26 Oct 2025 01:24:38 GMT
+      Content-Type:
+      - application/json; charset=UTF-8
+      Transfer-Encoding:
+      - chunked
+      Connection:
+      - keep-alive
+      Server:
+      - cloudflare
+      Cf-Ray:
+      - 994627bdc9e8e822-ORD
+      Cf-Cache-Status:
+      - DYNAMIC
+      Access-Control-Allow-Origin:
+      - "*"
+      Cache-Control:
+      - no-cache
+      Expires:
+      - "-1"
+      Strict-Transport-Security:
+      - max-age=31536000
+      Vary:
+      - Accept-Encoding,Accept-Encoding
+      Pragma:
+      - no-cache
+      Access-Control-Expose-Headers:
+      - Request-Context
+      Request-Context:
+      - appId=cid-v1:9c05b5dd-9acf-4a59-aabb-1775785c005f
+      X-Aspnet-Version:
+      - 4.0.30319
+      X-Content-Type-Options:
+      - nosniff
+      - nosniff
+      Set-Cookie:
+      - __cf_bm=WthwCIYBGJjeQcPIuJteHBCsffR9_YnIswA1GxBsAY0-1761441878-1.0.1.1-PDKN99A_uKww6R0a3o7xNsGHGxn2nOOhCXcaMzV_6LgrHJ1GEYNmKklmEtAghMWUP4IGpM9INbgu7tFJP1_AlEsAbYw0VOZD80N9_B0VvwU;
+        path=/; expires=Sun, 26-Oct-25 01:54:38 GMT; domain=.abcdev.imiscloud.com;
+        HttpOnly; Secure; SameSite=None
+    body:
+      encoding: ASCII-8BIT
+      string: '{"access_token":"<ACCESS_TOKEN>","token_type":"bearer","expires_in":3599,"userName":"J.S.FIANDER@GMAIL.COM",".issued":"Sun,
+        26 Oct 2025 01:24:38 GMT",".expires":"Sun, 26 Oct 2025 02:24:38 GMT"}'
+  recorded_at: Sun, 26 Oct 2025 01:24:38 GMT
+recorded_with: VCR 6.3.1