usps-imis-api 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e1d3316b4676bae03e67aa927632ec91801a6d703c55049c1b11013a20c3e08
-  data.tar.gz: 8199c664875cc57e995d73b3a96ce03cd9de2e5460e7a451553df3bb5ca3ff84
+  metadata.gz: e94dcde6abaf560148b72523c9defe96cd30f6980631f11b79cf8b35f52a1dcc
+  data.tar.gz: a94d8ce631656ff48bf6c3b905e3e06bf130a5a658dfad737afec2be21ac1957
 SHA512:
-  metadata.gz: 7015ffe22161d1645959004798ed1fde3e65a66db6695dac75ae84db13177a376a37b083f74abdd9092108ba33d9d0f09fcbaaaa845d861d50af237c77c819b2
-  data.tar.gz: 940e05eeeeea390c67e207f4ace40c6befed6dbe355efdc38e3fa6d270c35f6bf5c48c3093808c505c2b26e9f452000ecd384e250451bc8263cce84d43a78238
+  metadata.gz: 1c155ff3c3e0801c4cb1d738c736e7da9833b651ba56cafb5983439d8e7708f15a266f688d40672917270745b198cac6a38e86b735932c447a631b1c5922b17d
+  data.tar.gz: e99827b9bb433d673c6d76558c209f23a12aba1dbe22a674d4972f8ff97b0122374cb4ef2955c0b903ebcf5f7d20721c15b800b79cba17c304113436ea8c66a9

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    usps-imis-api (0.8.0)
+    usps-imis-api (0.9.0)
       activesupport (~> 8.0)
 
 GEM

data/Readme.md

@@ -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 = Logger.new($stdout)
+  config.logger.level = :info
 end
 ```
 
@@ -120,7 +124,7 @@ To fetch a specific field from member data, run e.g.:
 tot_mms = api.on('ABC_ASC_Individual_Demog').get_field('TotMMS')
 ```
 
-You can also access fields directly on the Business Object like a Hash:
+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']
@@ -195,7 +199,15 @@ 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
@@ -229,9 +241,9 @@ vsc.get(1417)
 
 # All of these options are identical
 #
-vsc.get(1417, 'Quantity')
+vsc.get(1417, 'Quantity').first
 vsc.get(1417)['Quantity']
-vsc.get[1417, 'Quantity']
+vsc[1417, 'Quantity']
 vsc.get(1417).raw['Properties']['$values'].find { it['Name'] == 'Quantity' }['Value']['$value']
 vsc.get_field(1417, 'Quantity')
 
@@ -244,7 +256,7 @@ created = vsc.create(certificate: 'E136924', year: 2024, count: 42)
 ordinal = created.ordinal
 ordinal = created['Ordinal']
 ordinal = created.raw['Properties']['$values'].find { it['Name'] == 'Ordinal' }['Value']['$value']
-ordinal = created.raw['Identity']['IdentityElements']['$values'][1] # Value is duplicated here
+ordinal = created.raw['Identity']['IdentityElements']['$values'][1].to_i # Value is duplicated here
 
 vsc.update(certificate: 'E136924', year: 2024, count: 43, ordinal: ordinal)
 
@@ -314,6 +326,14 @@ end
 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:

data/lib/usps/imis/api.rb

@@ -3,6 +3,7 @@
 require_relative 'requests'
 require_relative 'business_object'
 require_relative 'mapper'
+require_relative 'query'
 
 module Usps
   module Imis
@@ -15,10 +16,6 @@ module Usps
       #
       AUTHENTICATION_PATH = 'Token'
 
-      # Endpoint for IQA query requests
-      #
-      QUERY_PATH = 'api/Query'
-
       # API bearer token
       #
       attr_reader :token
@@ -54,7 +51,7 @@ module Usps
       def imis_id=(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
@@ -67,8 +64,7 @@ module Usps
         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 Errors::NotFoundError, 'Member not found'
         end
@@ -101,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 }+
@@ -109,31 +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
-
-      # Run an IQA Query, paging through all responses
-      #
-      # @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 [Array<Hash>] Collected response item values from the API
-      #
-      def query_all(query_name, query_params = {})
-        response = query(query_name, **query_params)
-        results = response['Items']['$values']
-
-        while response['HasNext']
-          response = query(query_name, **query_params, Offset: response['NextOffset'])
-          results += response['Items']['$values']
-        end
-
-        results
+        Query.new(self, query_name, query_params)
       end
 
       # Run requests as DSL, with specific +BusinessObject+ only maintained for this scope
@@ -178,6 +150,8 @@ module Usps
       # Authenticate to the iMIS API, and store the access token and expiration time
       #
       def authenticate
+        Imis.logger.debug 'Authenticating with iMIS'
+
         uri = URI(File.join(Imis.configuration.hostname, AUTHENTICATION_PATH))
         req = Net::HTTP::Post.new(uri)
         authentication_data = {

data/lib/usps/imis/business_object.rb

@@ -120,7 +120,7 @@ module Usps
         return CGI.escape(id) unless id.nil?
         return CGI.escape("~#{api.imis_id}|#{ordinal}") if ordinal
 
-        api.imis_id
+        api.imis_id.to_s
       end
 
       # Manually assemble the matching data structure, with fields in the correct order

data/lib/usps/imis/config.rb

@@ -8,16 +8,19 @@ module Usps
       IMIS_ROOT_URL_PROD = 'https://portal.americasboatingclub.org'
       IMIS_ROOT_URL_DEV = 'https://abcdev.imiscloud.com'
 
-      attr_accessor :imis_id_query_name, :username, :password
-      attr_reader :environment
+      attr_accessor :imis_id_query_name, :username, :password, :logger
+      attr_reader :environment, :logger_level
 
       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)
+        @logger = Logger.new($stdout, level: :info)
 
         yield self if block_given?
+
+        @logger_level = logger.class::SEV_LABEL[logger.level].downcase.to_sym
       end
 
       def environment=(env)
@@ -37,7 +40,7 @@ module Usps
 
       # Ruby 3.5 instance variable filter
       #
-      def instance_variables_to_inspect = %i[@environment @imis_id_query_name @username]
+      def instance_variables_to_inspect = %i[@environment @imis_id_query_name @username @logger_level]
     end
   end
 end

data/lib/usps/imis/data.rb

@@ -16,14 +16,18 @@ module Usps
 
       alias raw to_h
 
+      # The Business Object or Panel name
+      #
+      def entity = raw['EntityTypeName']
+
       # Access the iMIS ID property
       #
-      def imis_id = self['ID']
+      def imis_id = self['ID'].to_i
       alias id imis_id
 
       # Access the Ordinal identifier property (if present)
       #
-      def ordinal = self['Ordinal']
+      def ordinal = self['Ordinal']&.to_i
 
       # Access an individual property value by name
       #
@@ -35,6 +39,17 @@ module Usps
         value.is_a?(String) ? value : value['$value']
       end
 
+      # Hash of all property names to values
+      #
+      # @param include_ids [Boolean] Whether to include the iMIS ID and Ordinal
+      #
+      def properties(include_ids: false)
+        raw['Properties']['$values']
+          .map { it['Name'] }
+          .select { include_ids || !%w[ID Ordinal].include?(it) }
+          .index_with { self[it] }
+      end
+
       def inspect
         stringio = StringIO.new
         PP.pp(self, stringio)
@@ -42,11 +57,7 @@ module Usps
       end
 
       def pretty_print(pp)
-        data = {
-          entity_type_name: raw['EntityTypeName'],
-          imis_id:,
-          ordinal:
-        }.compact
+        data = { entity:, imis_id:, ordinal: }.compact
 
         pp.group(1, "#<#{self.class}", '>') do
           data.each do |key, value|

data/lib/usps/imis/mapper.rb

@@ -36,7 +36,7 @@ module Usps
       #
       # @param data [Hash] Conforms to pattern +{ field_key => value }+
       #
-      # @return [Array<Hash>] Response data from the API for each internal update request
+      # @return [Array<Usps::Imis::Data>] Response data from the API for each internal update request
       #
       def update(data)
         updates = data.each_with_object({}) do |(field_key, value), hash|
@@ -54,15 +54,13 @@ module Usps
     private
 
       def map_update(field_name)
-        if FIELD_MAPPING.key?(field_name.to_sym)
-          business_object_name, field = FIELD_MAPPING[field_name.to_sym]
-          yield(business_object_name, field)
-        else
-          missing_mapping(field_name)
-        end
+        missing_mapping!(field_name) unless FIELD_MAPPING.key?(field_name.to_sym)
+
+        business_object_name, field = FIELD_MAPPING[field_name.to_sym]
+        yield(business_object_name, field)
       end
 
-      def missing_mapping(field_name)
+      def missing_mapping!(field_name)
         unless ENV['TESTING']
           # :nocov:
           warn(

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

@@ -113,7 +113,7 @@ module Usps
             'EntityTypeName' => business_object,
             'IdentityElements' => {
               '$type' => identity_type,
-              '$values' => [api.imis_id, ordinal&.to_s].compact
+              '$values' => [api.imis_id.to_s, ordinal&.to_s].compact
             }
           }
         end
@@ -124,7 +124,7 @@ module Usps
             'EntityTypeName' => 'Party',
             'IdentityElements' => {
               '$type' => identity_type,
-              '$values' => [api.imis_id]
+              '$values' => [api.imis_id.to_s]
             }
           }
         end

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

@@ -14,7 +14,7 @@ module Usps
 
         def payload(data)
           build_payload(data) do |props|
-            props.add 'ID', api.imis_id
+            props.add 'ID', api.imis_id.to_s
             props.add 'Ordinal', data[:ordinal] if data[:ordinal]
             props.add 'ABC_EDUC_THRU_DATE', data[:thru_date] || '0001-01-01T00:00:00'
             props.add 'ABC_ECertificate', data[:certificate]

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

@@ -14,7 +14,7 @@ module Usps
 
         def payload(data)
           build_payload(data) do |props|
-            props.add 'ID', api.imis_id
+            props.add 'ID', api.imis_id.to_s
             props.add 'Ordinal', data[:ordinal] if data[:ordinal]
             props.add 'Source_System', 'Manual ITCom Entry'
             props.add 'ABC_ECertificate', data[:certificate]

data/lib/usps/imis/query.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    # API wrapper for IQA Queries
+    #
+    class Query
+      include Enumerable
+      include Requests
+
+      # Endpoint for IQA query requests
+      #
+      QUERY_PATH = 'api/Query'
+
+      # The parent +Api+ object
+      #
+      attr_reader :api
+
+      # Name of the Query to run
+      #
+      attr_reader :query_name
+
+      # Parameters for the Query
+      #
+      attr_reader :query_params
+
+      # Current offset for paging through the Query
+      #
+      attr_reader :offset
+
+      # 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 }+
+      #
+      def initialize(api, query_name, query_params)
+        @api = api
+        @query_name = query_name
+        @query_params = query_params
+      end
+
+      # Iterate through all results from the query
+      #
+      def each(&)
+        Imis.logger.info 'Running IQA Query on iMIS'
+
+        items = []
+        find_each { items << it }
+        items.each(&)
+      end
+
+      # Iterate through all results from the query, fetching one page at a time
+      #
+      def find_each(&)
+        result = { 'HasNext' => true }
+        count = 0
+
+        while result['HasNext']
+          Imis.logger.info 'Fetching IQA Query page'
+
+          result = fetch
+
+          count += result['Count'] || 0
+          Imis.logger.info "  -> #{count} / #{result['TotalCount']} #{'item'.pluralize(count)}"
+          Imis.logger.debug '  -> Query page data:'
+          JSON.pretty_generate(result).split("\n").each { Imis.logger.debug "    -> #{it}" }
+
+          items = result['Items']['$values'].map { it.except('$type') }
+          @offset = result['NextOffset']
+
+          items.each(&)
+        end
+
+        nil
+      end
+
+    private
+
+      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 uri = URI(File.join(Imis.configuration.hostname, path))
+      def fetch = JSON.parse(submit(uri, authorize(Net::HTTP::Get.new(uri))).body)
+    end
+  end
+end

data/lib/usps/imis/requests.rb

@@ -19,15 +19,29 @@ module Usps
       # If the current token is missing/expired, request a new one
       #
       def authorize(request)
-        authenticate if token_expiration < Time.now
+        if token_expiration < Time.now
+          Imis.logger.debug 'Token expired: re-authenticating with iMIS'
+          authenticate
+        end
         request.tap { it.add_field('Authorization', "Bearer #{token}") }
       end
 
       def submit(uri, request)
+        Imis.logger.info 'Submitting request to iMIS'
+        Imis.logger.debug "  -> #{uri}"
+        sanitized_request_body(request).split("\n").each { Imis.logger.debug "  -> #{it}" }
         client(uri).request(request).tap do |result|
           raise Errors::ResponseError.from(result) unless result.is_a?(Net::HTTPSuccess)
+
+          Imis.logger.info 'Request succeeded'
         end
       end
+
+      def sanitized_request_body(request)
+        return 'grant_type=password&username=[filtered]&password=[filtered]' if request.body&.include?('password=')
+
+        request.body.nil? ? '*** empty request body ***' : JSON.pretty_generate(JSON.parse(request.body))
+      end
     end
   end
 end

data/lib/usps/imis/version.rb

@@ -2,6 +2,6 @@
 
 module Usps
   module Imis
-    VERSION = '0.8.0'
+    VERSION = '0.9.0'
   end
 end

data/lib/usps/imis.rb

@@ -8,7 +8,9 @@ require 'cgi'
 
 require 'active_support/core_ext/string/inflections'
 require 'active_support/core_ext/object/to_query'
+require 'active_support/core_ext/enumerable'
 require 'active_support/string_inquirer'
+require 'logger'
 
 # Internal requires
 require_relative 'imis/config'
@@ -39,6 +41,10 @@ module Usps
         yield(configuration) if block_given?
         configuration
       end
+
+      # Logger instance to write to
+      #
+      def logger = configuration.logger
     end
   end
 end

data/spec/lib/usps/imis/api_spec.rb

@@ -17,13 +17,13 @@ describe Usps::Imis::Api do
     it 'stores the initial imis_id' do
       api = described_class.new(imis_id: 42)
 
-      expect(api.imis_id).to eq('42')
+      expect(api.imis_id).to eq(42)
     end
   end
 
   describe '#imis_id_for' do
     it 'gets the iMIS ID' do
-      expect(api.imis_id_for('E231625')).to eq('31092')
+      expect(api.imis_id_for('E231625')).to eq(31092)
     end
 
     context 'with a query error' do
@@ -37,18 +37,18 @@ describe Usps::Imis::Api do
     end
   end
 
-  describe '#query_all' do
+  describe '#query' do
+    let(:query) { api.query('$/ABC/ExampleQueryAll', {}) }
+
     before do
-      allow(api).to receive(:query).and_return(
+      allow(query).to receive(:fetch).and_return(
         { 'Items' => { '$values' => [{ 'key1' => 'value1' }] }, 'HasNext' => true, 'NextOffset' => 1 },
         { 'Items' => { '$values' => [{ 'key1' => 'value2' }] }, 'HasNext' => false, 'NextOffset' => 0 }
       )
     end
 
     it 'collects all query results' do
-      expect(api.query_all('$/ABC/ExampleQueryAll')).to eq(
-        [{ 'key1' => 'value1' }, { 'key1' => 'value2' }]
-      )
+      expect(query.to_a).to eq([{ 'key1' => 'value1' }, { 'key1' => 'value2' }])
     end
   end
 
@@ -56,9 +56,7 @@ describe Usps::Imis::Api do
     before { api.imis_id = 31092 }
 
     it 'sends an update' do
-      expect(api.on('ABC_ASC_Individual_Demog').put_fields('TotMMS' => 15)).to(
-        be_a(Hash)
-      )
+      expect(api.on('ABC_ASC_Individual_Demog').put_fields('TotMMS' => 15)).to be_a(Hash)
     end
 
     context 'when receiving a response error' do
@@ -133,7 +131,7 @@ describe Usps::Imis::Api do
       end
 
       expect(result).to be_a(Hash)
-      expect(api.imis_id).to eq('31092')
+      expect(api.imis_id).to eq(31092)
     end
 
     it 'nests on and with', :aggregate_failures do

data/spec/lib/usps/imis/data_spec.rb

@@ -22,9 +22,23 @@ describe Usps::Imis::Data do
     end
   end
 
+  describe '#properties' do
+    it 'iterates over the properties, excluding IDs' do
+      expect(data.properties.map { |field, value| "#{field}: #{value}" }).to eq(
+        ['Stub Integer: 42', 'Stub String: something']
+      )
+    end
+
+    it 'iterates over the properties, including IDs' do
+      expect(data.properties(include_ids: true).map { |field, value| "#{field}: #{value}" }).to eq(
+        ['ID: 31092', 'Stub Integer: 42', 'Stub String: something']
+      )
+    end
+  end
+
   describe '#inspect' do
     it 'generates the correct inspect string' do
-      expect(data.inspect).to eq('#<Usps::Imis::Data entity_type_name="ABC_ASC_Individual_Demog" imis_id="31092">')
+      expect(data.inspect).to eq('#<Usps::Imis::Data entity="ABC_ASC_Individual_Demog" imis_id=31092>')
     end
 
     context 'with data from a Panel' do
@@ -44,7 +58,7 @@ describe Usps::Imis::Data do
 
       it 'generates the correct inspect string with an ordinal' do
         expect(data.inspect).to eq(
-          '#<Usps::Imis::Data entity_type_name="ABC_ASC_Individual_Demog" imis_id="31092" ordinal="99">'
+          '#<Usps::Imis::Data entity="ABC_ASC_Individual_Demog" imis_id=31092 ordinal=99>'
         )
       end
     end

data/spec/lib/usps/imis/mapper_spec.rb

@@ -9,7 +9,7 @@ describe Usps::Imis::Mapper do
     it 'stores the initial imis_id' do
       mapper = described_class.new(imis_id: 42)
 
-      expect(mapper.api.imis_id).to eq('42')
+      expect(mapper.api.imis_id).to eq(42)
     end
   end
 

data/spec/lib/usps/imis/panels/education_spec.rb

@@ -64,7 +64,7 @@ describe Usps::Imis::Panels::Education do
     it 'can initialize with an iMIS ID' do
       panel = described_class.new(imis_id: 6374)
 
-      expect(panel.api.imis_id).to eq('6374')
+      expect(panel.api.imis_id).to eq(6374)
     end
   end
 end

data/spec/spec_helper.rb

@@ -31,6 +31,8 @@ RSpec.configure do |config|
 
       imis_config.username = ENV.fetch('IMIS_USERNAME', '')
       imis_config.password = ENV.fetch('IMIS_PASSWORD', '')
+
+      imis_config.logger = Logger.new(nil)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: usps-imis-api
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Julian Fiander
@@ -63,6 +63,7 @@ files:
 - lib/usps/imis/panels/education.rb
 - lib/usps/imis/panels/vsc.rb
 - lib/usps/imis/properties.rb
+- lib/usps/imis/query.rb
 - lib/usps/imis/requests.rb
 - lib/usps/imis/version.rb
 - spec/lib/usps/imis/api_spec.rb