usps-imis-api 1.0.0.pre.rc.1 → 1.0.0.pre.rc.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 591c0f59f5d39e06c011116940615588936cef78dfb8e497670909d5654c61b8
-  data.tar.gz: 2f667e0e06d05a519bff31e6387452dc896aa4204443ceb3ae43d1dab8f2eaf0
+  metadata.gz: bd103cb82cf705d717bd293bef46390aee8a82dca66ec103fa28510bb67b921c
+  data.tar.gz: 4d1dee0de5129874d612b8b888d57b24918582925b61ffac91ef7722a5cbc9cd
 SHA512:
-  metadata.gz: 622f9629c46f876901542639099e7544d28d932121e7a9bd09513fcdb0c756e2727f6b69aad8ead5606dd36803a80d9f66f2e2c5e4e6cc08fe7133fc799023de
-  data.tar.gz: 07ffc1e12820b524083e68d054e23eb976fcd7a16cf48fdbf7d64fe25a5d75b4083e2e6aafd7e6a19671ecaa9a7e2b33240a7bd4aa6d487f4f83fb14316c5aae
+  metadata.gz: 30acc54f0082681a9c38ba36bdfe6252331a0199416e131557352a880df66b465cd30de07fb3c3ab0d66366df97b096210e58be649387a3929609c09b9293010
+  data.tar.gz: 729b191b9d78e62f0acc659730d3761e4dc8a60f72304dd5b584a6ac9a63853c659c0fc335ceb7cbd35d903bc2c85656c0642259b2ee8c2f318669741d0d31fe

data/.gitignore

@@ -2,3 +2,4 @@ coverage/
 tmp/
 .env
 *.gem
+.yardoc

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    usps-imis-api (1.0.0.pre.rc.1)
+    usps-imis-api (1.0.0.pre.rc.2)
 
 GEM
   remote: https://rubygems.org/

data/lib/usps/imis/api.rb

@@ -2,14 +2,40 @@
 
 module Usps
   module Imis
+    # The core API wrapper
+    #
     class Api
+      # Endpoint for (re-)authentication requests
+      #
       AUTHENTICATION_PATH = 'Token'
+
+      # Endpoint for general API requests
+      #
       API_PATH = 'api'
+
+      # Endpoint for IQA query requests
+      #
       QUERY_PATH = 'api/Query'
-      PANELS = Struct.new(:vsc, :education)
 
-      attr_reader :token, :token_expiration, :imis_id
+      # API bearer token
+      #
+      attr_reader :token
+
+      # Expiration time for the API bearer token
+      #
+      # Used to automatically re-authenticate as needed
+      #
+      attr_reader :token_expiration
+
+      # Currently selected iMIS ID for API requests
+      #
+      attr_reader :imis_id
 
+      # 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
         self.imis_id = imis_id if imis_id
@@ -17,12 +43,18 @@ module Usps
 
       # Manually set the current ID, if you already have it for a given member
       #
+      # @param id [Integer, String] iMIS ID to select for future requests
+      #
       def imis_id=(id)
         @imis_id = id.to_i.to_s
       end
 
       # Convert a member's certificate number into an iMIS ID number
       #
+      # @param certificate [String] Certificate number to lookup the corresponding iMIS ID for
+      #
+      # @return [String] Corresponding iMIS ID
+      #
       def imis_id_for(certificate)
         result = query(Imis.configuration.imis_id_query_name, { certificate: })
         @imis_id = result['Items']['$values'][0]['ID']
@@ -34,6 +66,13 @@ module Usps
       #
       # This should be used with methods that do not change the value of `imis_id`
       #
+      # @param id [Integer, String] iMIS ID to select for requests within the block
+      #
+      # @example
+      #   with(12345) do
+      #     update(mm: 15)
+      #   end
+      #
       def with(id, &)
         old_id = imis_id
         self.imis_id = id
@@ -44,6 +83,11 @@ module Usps
 
       # Get a business object for the current member
       #
+      # @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)
+      #
+      # @return [Hash] Response data from the API
+      #
       def get(business_object_name, url_id: nil)
         uri = uri_for(business_object_name, url_id:)
         request = Net::HTTP::Get.new(uri)
@@ -53,7 +97,11 @@ module Usps
 
       # Update only specific fields on a business object for the current member
       #
-      #   fields - hash of shape: { field_name => new_value }
+      # @param business_object_name [String] Name of the business object
+      # @param fields [Hash] Conforms to pattern +{ field_key => value }+
+      # @param url_id [String] Override the ID param of the URL (e.g. used for Panels)
+      #
+      # @return [Hash] Response data from the API
       #
       def put_fields(business_object_name, fields, url_id: nil)
         updated = filter_fields(business_object_name, fields)
@@ -62,6 +110,12 @@ module Usps
 
       # Update a business object for the current member
       #
+      # @param business_object_name [String] Name of the business object
+      # @param body [Hash] Full raw API object data
+      # @param url_id [String] Override the ID param of the URL (e.g. used for Panels)
+      #
+      # @return [Hash] Response data from the API
+      #
       def put(business_object_name, body, url_id: nil)
         uri = uri_for(business_object_name, url_id:)
         request = Net::HTTP::Put.new(uri)
@@ -72,6 +126,12 @@ module Usps
 
       # Create a business object for the current member
       #
+      # @param business_object_name [String] Name of the business object
+      # @param body [Hash] Full raw API object data
+      # @param url_id [String] Override the ID param of the URL (e.g. used for Panels)
+      #
+      # @return [Hash] Response data from the API
+      #
       def post(business_object_name, body, url_id: nil)
         uri = uri_for(business_object_name, url_id:)
         request = Net::HTTP::Post.new(uri)
@@ -82,7 +142,10 @@ module Usps
 
       # Remove a business object for the current member
       #
-      # Returns empty string on success
+      # @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)
+      #
+      # @return [String] Error response body from the API, or empty string on success
       #
       def delete(business_object_name, url_id: nil)
         uri = uri_for(business_object_name, url_id:)
@@ -93,8 +156,10 @@ module Usps
 
       # Run an IQA Query
       #
-      #   query_name   - the full path of the query in IQA, e.g. `$/_ABC/Fiander/iMIS_ID`
-      #   query_params - hash of shape: { param_name => param_value }
+      # @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 [Hash] Response data from the API
       #
       def query(query_name, query_params = {})
         query_params[:QueryName] = query_name
@@ -105,21 +170,30 @@ module Usps
         JSON.parse(result.body)
       end
 
+      # An instance of Mapper, using this instance as its parent +Api+
+      #
       def mapper
         @mapper ||= Mapper.new(self)
       end
 
+      # Convenience accessor for available Panel objects, each using this instance as its parent
+      # +Api+
+      #
       def panels
-        @panels ||= PANELS.new(
+        @panels ||= Struct.new(:vsc, :education).new(
           Panel::Vsc.new(self),
           Panel::Education.new(self)
         )
       end
 
+      # Convenience alias for updating mapped fields
+      #
       def update(data)
         mapper.update(data)
       end
 
+      # Ruby 3.5 instance variable filter
+      #
       def instance_variables_to_inspect = %i[@token_expiration @imis_id]
 
     private

data/lib/usps/imis/config.rb

@@ -2,6 +2,8 @@
 
 module Usps
   module Imis
+    # API Configuration
+    #
     class Config
       IMIS_ROOT_URL_PROD = 'https://portal.americasboatingclub.org'
       IMIS_ROOT_URL_DEV = 'https://abcdev.imiscloud.com'
@@ -12,6 +14,10 @@ module Usps
         yield self if block_given?
       end
 
+      # Environment-specific API endpoint hostname
+      #
+      # @return The API hostname for the current environment
+      #
       def hostname
         case environment.to_sym
         when :production
@@ -23,6 +29,8 @@ module Usps
         end
       end
 
+      # Ruby 3.5 instance variable filter
+      #
       def instance_variables_to_inspect = %i[@environment @imis_id_query_name @username]
     end
   end

data/lib/usps/imis/error/api.rb

@@ -3,14 +3,32 @@
 module Usps
   module Imis
     module Error
+      # Base error class for all internal exceptions
+      #
       class Api < StandardError
+        # Additional call-specific metadata to pass through to Bugsnag
+        #
         attr_accessor :metadata
 
+        # A new instance of +Error::Api+
+        #
+        # @param message [String] The base exception message
+        # @param metadata [Hash] Additional call-specific metadata to pass through to Bugsnag
+        #
         def initialize(message, metadata = {})
           super(message)
           @metadata = metadata
         end
 
+        # Additional metadata to include in Bugsnag reports
+        #
+        # Can include fields at the top level, which will be shows on the custom tab
+        #
+        # Can include fields nested under a top-level key, which will be shown on a tab with the
+        # top-level key as its name
+        #
+        # @return [Hash]
+        #
         def bugsnag_meta_data
           metadata == {} ? {} : base_metadata
         end

data/lib/usps/imis/error/mapper.rb

@@ -3,6 +3,8 @@
 module Usps
   module Imis
     module Error
+      # Exception raised by a +Mapper+
+      #
       class Mapper < Api; end
     end
   end

data/lib/usps/imis/error/response.rb

@@ -3,23 +3,53 @@
 module Usps
   module Imis
     module Error
+      # Exception raised due to receiving an error response from the API
+      #
       class Response < Api
+        # [Net::HTTPResponse] The response received from the API
+        #
         attr_reader :response
+
+        # [Hash] Additional call-specific metadata to pass through to Bugsnag
+        #
         attr_accessor :metadata
 
+        # Create a new instance of +Error::Response+ from an API response
+        #
+        # @param response [Net::HTTPResponse] The response received from the API
+        #
         def self.from(response)
           new(nil, response)
         end
 
+        # Create a new instance of +Error::Response+
+        #
+        # @param _message Ignored
+        # @param response [Net::HTTPResponse] The response received from the API
+        # @param metadata [Hash] Additional call-specific metadata to pass through to Bugsnag
+        #
         def initialize(_message, response, metadata = {})
           @response = response
           super(message, metadata)
         end
 
+        # Additional metadata to include in Bugsnag reports
+        #
+        # Can include fields at the top level, which will be shows on the +custom+ tab
+        #
+        # Can include fields nested under a top-level key, which will be shown on a tab with the
+        # top-level key as its name
+        #
+        # @return [Hash]
+        #
         def bugsnag_meta_data
           base_metadata.tap { |m| m[:api].merge!(metadata) }
         end
 
+        # Auto-formatted exception message, based on the provided API response
+        #
+        # @return [String] The exception message
+        #
         def message
           [
             "#{self.class.name}: [#{status.to_s.upcase}] The iMIS API returned an error.",

data/lib/usps/imis/mapper.rb

@@ -2,7 +2,12 @@
 
 module Usps
   module Imis
+    # Specific known fields mapping to facilitate updating across multiple
+    # business objects.
+    #
     class Mapper
+      # List of known mapped fields
+      #
       FIELD_MAPPING = {
         grade: %w[ABC_ASC_Individual_Demog Grade],
         edpro: %w[ABC_ASC_Individual_Demog Educ_Proficiency],
@@ -12,19 +17,26 @@ module Usps
         mm_updated: %w[ABC_ASC_Individual_Demog MMS_Updated]
       }.freeze
 
+      # The parent +Api+ object
+      #
       attr_reader :api
 
+      # A new instance of +Mapper+
+      #
       def initialize(api = nil, imis_id: nil)
         @api = api || Api.new
         @api.imis_id = imis_id if imis_id
       end
 
       # 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
       #
-      # Only available for previously-mapped fields
+      # Only available for fields defined in +FIELD_MAPPING+
+      #
+      # @param data [Hash] Conforms to pattern +{ field_key => value }+
       #
-      #  `data` is a hash of shape { field_key => value }
+      # @return [Array<Hash>] Response data from the API for each internal update request
       #
       def update(data)
         updates = data.each_with_object({}) do |(field_key, value), hash|

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

@@ -3,7 +3,11 @@
 module Usps
   module Imis
     module Panel
+      # Base class for configuring Panels
+      #
       class BasePanel
+        # The parent +Api+ object
+        #
         attr_reader :api
 
         def initialize(api = nil, imis_id: nil)
@@ -11,18 +15,35 @@ module Usps
           @api.imis_id = imis_id if imis_id
         end
 
+        # Get a specific object from the Panel
+        #
+        # @param ordinal [Integer] The ordinal identifier for the desired object
+        #
         def get(ordinal)
           api.get(business_object, url_id: "~#{api.imis_id}|#{ordinal}")
         end
 
+        # Create a new object in the Panel
+        #
+        # @param data [Hash] The record data for the desired object
+        #
         def create(data)
           api.post(business_object, payload(data), url_id: '')
         end
 
+        # Update an existing object in the Panel
+        #
+        # @param data [Hash] The record data for the desired object -- including the required
+        #                    +ordinal+ identifier
+        #
         def update(data)
           api.put(business_object, payload(data), url_id: "~#{api.imis_id}|#{data[:ordinal]}")
         end
 
+        # Remove a specific object from the Panel
+        #
+        # @param ordinal [Integer] The ordinal identifier for the desired object
+        #
         def destroy(ordinal)
           api.delete(business_object, url_id: "~#{api.imis_id}|#{ordinal}")
         end

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

@@ -3,6 +3,8 @@
 module Usps
   module Imis
     module Panel
+      # Panel for accessing the Educational completions business object
+      #
       class Education < BasePanel
       private
 

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

@@ -3,6 +3,8 @@
 module Usps
   module Imis
     module Panel
+      # Panel for accessing the annual VSC completed counts business object
+      #
       class Vsc < BasePanel
       private
 

data/lib/usps/imis/version.rb

@@ -2,6 +2,6 @@
 
 module Usps
   module Imis
-    VERSION = '1.0.0-rc.1'
+    VERSION = '1.0.0-rc.2'
   end
 end

data/lib/usps/imis.rb

@@ -23,24 +23,26 @@ require_relative 'imis/panel/vsc'
 require_relative 'imis/panel/education'
 
 module Usps
+  # API wrapper for interacting with iMIS
+  #
   module Imis
     class << self
+      # Accessor for configuration values
+      #
+      # @return The configuration object
+      #
       def configuration
         @configuration ||= Config.new
       end
 
+      # Used to define a block of configuration settings
+      #
+      # @return The updated configuration object
+      #
       def configure
         yield(configuration) if block_given?
         configuration
       end
-
-      # def mock!(value = true)
-      #   @mock = value
-      # end
-
-      # def mock
-      #   @mock || false
-      # end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: usps-imis-api
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.rc.1
+  version: 1.0.0.pre.rc.2
 platform: ruby
 authors:
 - Julian Fiander