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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07d2a2b0c67186b6c3e2a8c8f3dd1694341b399d2ae95bbffcc8db568a3cdca2
-  data.tar.gz: b6315dd73aff2c70aabf352dfa2b25b905cf11404894a37814a77d7c2c349ef7
+  metadata.gz: ebdfba18c4fc6164bd3e5fbf4fe366d2ca81dbe37420bca3035d705b2309319f
+  data.tar.gz: 0244bef394a72715ddf7a6e2219f37bcbc93f025ae87c70fe3928fcd45201b0e
 SHA512:
-  metadata.gz: 7e4bd50ec6137ffed9a3035d135fbe62d5ec66846e6b11e4b4c3f2db38cb5f20d09f9ca9b41553291a649859dd8aade13318eed85e0d92645e60734545a3f5c2
-  data.tar.gz: 3bd9f6eb055de1fb5aecbd1c40166f7db9a781cecf5fb93fbe8086636c379c8081d5a97271c5a6f27354439cb7410bf1f13cd7a1c39cb6ccb36ede0ccecf5630
+  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
 
@@ -377,6 +55,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,9 @@ 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)
         self.imis_id = imis_id if imis_id
       end
 
@@ -63,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
@@ -97,16 +99,16 @@ 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)
-      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
       #
@@ -162,20 +164,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'])
+        @token_expiration = Time.now - json['expires_in'] - 60
       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

@@ -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
@@ -93,7 +99,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
@@ -102,14 +108,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
@@ -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,9 +170,10 @@ 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)
+        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}" }
         result
       end
@@ -183,9 +181,11 @@ 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)
-        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/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/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

@@ -18,7 +18,7 @@ module Usps
         super(message)
         @metadata = metadata
 
-        Imis.logger.debug self
+        Imis.logger(self.class.name).error self
       end
 
       # Additional metadata to include in Bugsnag reports
@@ -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