usps-imis-api 1.0.0.pre.rc.9 → 1.0.0.pre.rc.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f59d7505f179cc5306b35b07abb68c618229101a28a637240299dfffce94bec7
-  data.tar.gz: 6b0f55756ea84ee927b6a7115aef6fdd96934dc2b9256c0cc6b2beac9be8c849
+  metadata.gz: ebdfba18c4fc6164bd3e5fbf4fe366d2ca81dbe37420bca3035d705b2309319f
+  data.tar.gz: 0244bef394a72715ddf7a6e2219f37bcbc93f025ae87c70fe3928fcd45201b0e
 SHA512:
-  metadata.gz: b83571a81496bf22fcea8886c82aeba87eb5f9a687f7eb3e033458f89bfd0ac58530e72de9cc1a97f315bf6721e1e58dfa7fd527391188ad3ef8c371fdc5dbbd
-  data.tar.gz: 232d44e8916a5fa4166a5818609595ba217fec1e61438e175161d0d39e52d16a537457b3829ff673dc0b4b7adfa1eec2c46f5056eb6eb50e8c2a6864abfbe53c
+  metadata.gz: cd525cf6c237a7d13addbbd1faeed94b0c8a2cdecc7392d116447e19b91ba69a6d21064c517ce8b1885152eb55d918e129f681238e7b7912d20b0b408a09e441
+  data.tar.gz: 7c56a167b87a406f23e89d1c4bc0fb964e19e05b89c36eb180b2deae3f157c47f25c69a8c95cc7eff0f32fb975872edcf4b8cab28ca11516b7b96be430e63e32

data/Readme.md

@@ -39,331 +39,9 @@ Usps::Imis.configure do |config|
 end
 ```
 
-When using `bin/console`, this configuration will be run by default.
-
-Instantiate the API object:
-
-```ruby
-api = Usps::Imis::Api.new
-```
-
-If you already have an iMIS ID to work with, you can pass that in immediately:
-
-```ruby
-api = Usps::Imis::Api.new(imis_id: imis_id)
-```
-
-### Authentication
-
-If a token is not available, this will automatically fetch one when needed. As long as that token
-should still be valid, it will reuse the same token. If the token should expire, this will
-automatically request a new token.
-
 ## Usage
 
-### iMIS ID
-
-To act on member data, you need to have the iMIS ID. If you already have access to that from the
-database, you can skip this step.
-
-To convert a member's certificate number into their iMIS ID, run the following method:
-
-```ruby
-api.imis_id_for(certificate)
-```
-
-This will both return the ID, and store it for use with other requests. If you need to change which
-member you are working with, just run this method again with the new certificate number.
-
-You can also manually set the current ID, if you already have it for a given member
-
-```ruby
-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.
-
-Panels require passing in the ordinal identifier as an argument, except for `POST`.
-
-#### GET
-
-To fetch member data, run e.g.:
-
-```ruby
-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']
-```
-
-Alias: `read`
-
-#### 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
-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)
-```
-
-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.
-
-Alias: `patch`
-
-#### PUT
-
-To update member data, run e.g.:
-
-```ruby
-update = api.on('ABC_ASC_Individual_Demog').put(complete_imis_object)
-```
-
-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
-
-To create new member data, run e.g.:
-
-```ruby
-created = api.on('ABC_ASC_Individual_Demog').post(complete_imis_object)
-```
-
-This method requires a complete iMIS data structure.
-
-Alias: `create`
-
-#### DELETE
-
-To remove member data, run e.g.:
-
-```ruby
-api.on('ABC_ASC_Individual_Demog').delete
-```
-
-Alias: `destroy`
-
-### QUERY
-
-Run an IQA Query
-
-`query_params` is a hash of shape: `{ param_name => param_value }`
-
-```ruby
-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 `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 `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
-you with the standard API call syntax, and will suggest you inform ITCom leadership of the new
-mapping you need.
-
-### Panels
-
-For supported panels (usually, business objects with composite identity keys), you can interact
-with them in the same general way:
-
-```ruby
-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)
-
-# 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::Panels::Vsc.new(imis_id: imis_id)
-```
-
-Panels are also accessible directly from the API object:
-
-```ruby
-api.panels.vsc.get(1417)
-```
-
-### DSL Mode
-
-Instead of manually setting the current iMIS ID, then running individual queries, you can instead
-run queries in DSL mode. This specifies the iMIS ID for the scope of the block, then reverts to the
-previous value.
-
-```ruby
-api.with(31092) do
-  # These requests are identical:
-
-  on('ABC_ASC_Individual_Demog') { put_fields('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
-api.with(6374) do
-  panels.vsc.get(1417)
-end
-```
-
-```ruby
-api.with(31092) do
-  # These requests are identical:
-
-  on('ABC_ASC_Individual_Demog') do
-    get.raw['Properties']['$values'].find { it['Name'] == 'TotMMS' }['Value']['$value']
-
-    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
-
-# 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)
-  )
-)
-```
+For more details and examples, refer to the [Wiki](https://github.com/unitedstatespowersquadrons/imis-api-ruby/wiki).
 
 ## Exception Handling
 

data/lib/usps/imis/api.rb

@@ -39,7 +39,6 @@ module Usps
       # @param imis_id [Integer, String] iMIS ID to select immediately on initialization
       #
       def initialize(imis_id: nil)
-        authenticate
         self.imis_id = imis_id if imis_id
       end
 
@@ -62,8 +61,12 @@ module Usps
       def imis_id_for(certificate)
         raise Errors::LockedIdError if lock_imis_id
 
+        logger.debug "Fetching iMIS ID for #{certificate}"
+
         begin
-          self.imis_id = query(Imis.configuration.imis_id_query_name, { certificate: }).first['ID'].to_i
+          result = query(Imis.configuration.imis_id_query_name, { certificate: }).tap { logger.debug it }
+          page = result.page.tap { logger.debug it }
+          self.imis_id = page.first['ID'].to_i
         rescue StandardError
           raise Errors::NotFoundError, 'Member not found'
         end
@@ -96,12 +99,14 @@ module Usps
         end
       end
 
-      # Build an IQA Query interface
+      # Build a Query interface
+      #
+      # Works with IQA queries and Business Objects
       #
-      # @param query_name [String] Full path of the query in IQA, e.g. +$/_ABC/Fiander/iMIS_ID+
+      # @param query_name [String] Full path of the query, e.g. +$/_ABC/Fiander/iMIS_ID+
       # @query_params [Hash] Conforms to pattern +{ param_name => param_value }+
       #
-      # @return [Hash] Response data from the API
+      # @return [Usps::Imis::Query] Query wrapper
       #
       def query(query_name, query_params = {}) = Query.new(self, query_name, **query_params)
 
@@ -169,7 +174,7 @@ module Usps
         json = JSON.parse(result.body)
 
         @token = json['access_token']
-        @token_expiration = Time.parse(json['.expires'])
+        @token_expiration = Time.now - json['expires_in'] - 60
       end
 
       # URI for the authentication endpoint

data/lib/usps/imis/business_object.rb

@@ -33,6 +33,12 @@ module Usps
         @ordinal = ordinal
       end
 
+      # Run a query on the entire business object
+      #
+      # @return [Usps::Imis::Query] Query wrapper
+      #
+      def query = api.query(business_object_name)
+
       # Get a business object for the current member
       #
       # If +fields+ is provided, will return only those field values
@@ -118,9 +124,6 @@ module Usps
 
     private
 
-      def token = api.token
-      def token_expiration = api.token_expiration
-
       def logger = Imis.logger('BusinessObject')
 
       # Construct a business object API endpoint address
@@ -154,13 +157,7 @@ module Usps
             # Skip unmodified fields
             next unless fields.keys.include?(value['Name'])
 
-            # Strings are not wrapped in the type definition structure
-            new_value = fields[value['Name']]
-            if new_value.is_a?(String)
-              value['Value'] = new_value
-            else
-              value['Value']['$value'] = new_value
-            end
+            value['Value'] = Properties.wrap(fields[value['Name']])
 
             # Add the completed field with the updated value
             updated['Properties']['$values'] << value
@@ -173,6 +170,8 @@ module Usps
       # Useful for stubbing data in tests
       #
       def raw_object
+        raise Errors::MissingIdError if api.imis_id.nil?
+
         response = submit(uri, authorize(http_get))
         result = Data.from_json(response.body)
         JSON.pretty_generate(result).split("\n").each { logger.debug "    -> #{it}" }
@@ -182,6 +181,8 @@ module Usps
       # Upload an object to the API
       #
       def put_object(request, body)
+        raise Errors::MissingIdError if api.imis_id.nil?
+
         request.body = JSON.dump(body)
         response = submit(uri, authorize(request))
         result = Data.from_json(response.body)

data/lib/usps/imis/config.rb

@@ -12,7 +12,7 @@ module Usps
       attr_reader :environment, :logger, :logger_level
 
       def initialize
-        @environment = defined?(Rails) ? Rails.env : ActiveSupport::StringInquirer.new('development')
+        @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)
@@ -31,6 +31,10 @@ module Usps
         @logger = ActiveSupport::TaggedLogging.new(logger)
       end
 
+      def silence!
+        self.logger = Logger.new(nil)
+      end
+
       # Environment-specific API endpoint hostname
       #
       # @return The API hostname for the current environment
@@ -44,7 +48,7 @@ module Usps
 
       # Ruby 3.5 instance variable filter
       #
-      def instance_variables_to_inspect = %i[@environment @imis_id_query_name @username @logger_level]
+      def instance_variables_to_inspect = instance_variables - %i[@password @logger]
 
       # Parameters to filter out of logging
       #

data/lib/usps/imis/error.rb

@@ -47,6 +47,7 @@ require_relative 'errors/api_error'
 require_relative 'errors/config_error'
 require_relative 'errors/locked_id_error'
 require_relative 'errors/mapper_error'
+require_relative 'errors/missing_id_error'
 require_relative 'errors/not_found_error'
 require_relative 'errors/response_error'
 require_relative 'errors/panel_unimplemented_error'

data/lib/usps/imis/errors/missing_id_error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    module Errors
+      # Exception raised when attempting to access a +BusinessObject+ without an iMIS ID
+      #
+      class MissingIdError < Error
+        def initialize = super(message)
+
+        def message = 'Cannot access an individual Business Object without an iMIS ID'
+      end
+    end
+  end
+end

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

@@ -51,12 +51,13 @@ module Usps
 
         # Update a single named field on a business object for the current member
         #
+        # @param ordinal [Integer] The ordinal identifier for the desired object
         # @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)
+        def put_field(ordinal, 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

data/lib/usps/imis/properties.rb

@@ -9,6 +9,19 @@ module Usps
       #
       def self.build(&) = new.build(&)
 
+      # Wrap value in the API-internal type structure
+      #
+      def self.wrap(value)
+        case value
+        when String then value
+        when Time, DateTime then value.strftime('%Y-%m-%dT%H:%I:%S')
+        when Integer then { '$type' => 'System.Int32', '$value' => value }
+        when true, false then { '$type' => 'System.Boolean', '$value' => value }
+        else
+          raise Errors::UnexpectedPropertyTypeError.from(value)
+        end
+      end
+
       # Build the data for the Properties field
       #
       def build
@@ -29,22 +42,9 @@ module Usps
         @properties << {
           '$type' => 'Asi.Soa.Core.DataContracts.GenericPropertyData, Asi.Contracts',
           'Name' => name,
-          'Value' => wrap(value)
+          'Value' => self.class.wrap(value)
         }
       end
-
-    private
-
-      def wrap(value)
-        case value
-        when String then value
-        when Time, DateTime then value.strftime('%Y-%m-%dT%H:%I:%S')
-        when Integer then { '$type' => 'System.Int32', '$value' => value }
-        when true, false then { '$type' => 'System.Boolean', '$value' => value }
-        else
-          raise Errors::UnexpectedPropertyTypeError.from(value)
-        end
-      end
     end
   end
 end

data/lib/usps/imis/query.rb

@@ -2,7 +2,7 @@
 
 module Usps
   module Imis
-    # API wrapper for IQA Queries
+    # API wrapper for IQA and Business Object Queries
     #
     class Query
       include Enumerable
@@ -10,7 +10,7 @@ module Usps
 
       # Endpoint for IQA query requests
       #
-      QUERY_PATH = 'api/Query'
+      IQA_PATH = 'api/Query'
 
       # The parent +Api+ object
       #
@@ -36,6 +36,10 @@ module Usps
       #
       attr_reader :count
 
+      # Whether the current query has a next page
+      #
+      attr_reader :next_page
+
       # A new instance of +Query+
       #
       # @param api [Api] Parent to use for making requests
@@ -48,14 +52,18 @@ module Usps
         @api = api
         @query_name = query_name
         @query_params = query_params
+        @query_params.merge!(QueryName: query_name) if iqa?
         @page_size = page_size
         @offset = offset
+        @count = 0
+
+        logger.debug "URI: #{uri}"
       end
 
       # Iterate through all results from the query
       #
       def each(&)
-        logger.info 'Running IQA Query on iMIS'
+        logger.info 'Running'
 
         items = []
         find_each { items << it }
@@ -65,10 +73,10 @@ module Usps
       # Iterate through all results from the query, fetching one page at a time
       #
       def find_each(&)
-        result = reset!
+        reset!
 
-        while result['HasNext']
-          result = fetch_next.tap do |result_page|
+        while page?
+          fetch_next.tap do |result_page|
             result_page['Items']['$values'].map { it.except('$type') }.each(&)
           end
         end
@@ -76,14 +84,16 @@ module Usps
         nil
       end
 
-      # Fetch a raw query page
+      # Fetch a filtered query page, and update the current offset
       #
-      def fetch = JSON.parse(submit(uri, authorize(http_get)).body)
+      def page = fetch_next['Items']['$values'].map { iqa? ? it.except('$type') : Imis::Data[it] }
 
       # Fetch the next raw query page, and update the current offset
       #
       def fetch_next
-        logger.info 'Fetching IQA Query page'
+        return unless page?
+
+        logger.info "Fetching #{query_type} Query page"
 
         result = fetch
 
@@ -94,33 +104,44 @@ module Usps
         JSON.pretty_generate(result).split("\n").each { logger.debug "    -> #{it}" }
 
         @offset = result['NextOffset']
+        @next_page = result['HasNext']
 
         result
       end
 
+      # Fetch a raw query page
+      #
+      def fetch = JSON.parse(submit(uri, authorize(http_get)).body)
+
+      # Reset query paging progress
+      #
+      def reset!
+        return if next_page.nil?
+
+        logger.debug 'Resetting progress'
+
+        @count = 0
+        @offset = 0
+        @next_page = nil
+      end
+
       # Ruby 3.5 instance variable filter
       #
       def instance_variables_to_inspect = instance_variables - %i[@api]
 
     private
 
-      def token = api.token
-      def token_expiration = api.token_expiration
+      # Only skip if explicitly set
+      def page? = next_page.nil? || next_page
 
-      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 iqa? = query_name.match?(/^\$/)
+      def query_type = iqa? ? :IQA : :'Business Object'
+      def path_params = query_params.merge({ Offset: offset, Limit: page_size }.compact)
+      def endpoint = iqa? ? IQA_PATH : "#{Imis::BusinessObject::API_PATH}/#{query_name}"
+      def path = "#{endpoint}?#{path_params.to_query}"
       def uri = URI(File.join(Imis.configuration.hostname, path))
 
-      def logger = Imis.logger('Query')
-
-      def reset!
-        logger.debug 'Resetting Query progress'
-
-        @count = 0
-        @offset = 0
-
-        { 'HasNext' => true }
-      end
+      def logger = Imis.logger("#{query_type} Query")
     end
   end
 end