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

data/lib/usps/imis/api.rb

@@ -1,280 +1,207 @@
 # frozen_string_literal: true
 
-require_relative 'requests'
-require_relative 'business_object'
-require_relative 'mapper'
-require_relative 'query'
-
 module Usps
   module Imis
-    # The core API wrapper
-    #
     class Api
-      include Requests
-
-      # Endpoint for (re-)authentication requests
-      #
       AUTHENTICATION_PATH = 'Token'
+      API_PATH = 'api'
+      QUERY_PATH = 'api/Query'
+      PANELS = Struct.new(:vsc, :education)
 
-      # 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
-
-      # Whether to lock changes to the selected iMIS ID
-      #
-      attr_reader :lock_imis_id
-
-      # Tagged logger
-      #
-      attr_reader :logger
+      attr_reader :token, :token_expiration, :imis_id
 
-      # Create a new instance of +Api+ and provide an existing auth token
-      #
-      # @param token [String] Auth token
-      #
-      def self.with_token(token)
-        new.tap do |api|
-          api.instance_variable_set(:@token, token)
-          api.instance_variable_set(:@token_expiration, Time.now + 3600) # Greater than the actual lifetime of the token
-        end
-      end
-
-      # A new instance of +Api+
-      #
-      # @param imis_id [Integer, String] iMIS ID to select immediately on initialization
-      #
-      def initialize(imis_id: nil, record_id: nil)
+      def initialize(skip_authentication: false, imis_id: nil)
+        authenticate unless skip_authentication
         self.imis_id = imis_id if imis_id
-        self.record_id = record_id if record_id
-        @logger ||= Imis.logger('Api')
-        Imis.config.validate!
       end
 
       # Manually set the current ID, if you already have it for a given member
       #
-      # Supports integer ID and UUID string
-      #
-      # @param id [Integer, String] iMIS ID to select for future requests
-      #
-      # @return [Integer] iMIS ID
-      #
       def imis_id=(id)
-        raise Errors::LockedIdError if lock_imis_id
-
-        hex = '[0-9a-fA-F]'
-        uuid_pattern = /^#{hex}{8}-#{hex}{4}-#{hex}{4}-#{hex}{4}-#{hex}{12}$/
-        @imis_id =
-          if id.to_s.match?(uuid_pattern)
-            id
-          elsif id.to_i.to_s == id.to_s
-            id.to_i
-          end
+        @imis_id = id.to_i.to_s
       end
 
-      # Manually set the current record ID
-      #
-      # @param id [Integer, String] Record ID to select for future requests
-      #
-      # @return [Integer] Record ID
-      #
-      def record_id=(id)
-        return if id.nil?
-
-        raise Errors::LockedIdError if lock_imis_id
-
-        @record_id = id.to_i
-      end
-
-      # Currently selected Record ID for API requests
-      #
-      # Defaults to the iMIS ID
-      #
-      def record_id = @record_id || imis_id
-
       # Convert a member's certificate number into an iMIS ID number
       #
-      # @param certificate [String] Certificate number to lookup the corresponding iMIS ID for
-      #
-      # @return [Integer] Corresponding iMIS ID
-      #
       def imis_id_for(certificate)
-        raise Errors::LockedIdError if lock_imis_id
-
-        logger.debug "Fetching iMIS ID for #{certificate}"
-
-        begin
-          result = query(Imis.configuration.imis_id_query_name, { certificate: })
-          page = result.page.tap { logger.tagged('Response').debug it }
-          self.imis_id = page.first['ID'].to_i
-        rescue StandardError
-          raise Errors::NotFoundError, 'Member not found'
-        end
+        result = query(Imis.configuration.imis_id_query_name, { certificate: })
+        @imis_id = result['Items']['$values'][0]['ID']
+      rescue StandardError
+        raise Error::Api, 'Member not found'
       end
 
       # Run requests as DSL, with specific iMIS ID only maintained for this scope
       #
-      # Either +id+ or +certificate+ is required.
-      #
-      # While in this block, changes to the value of +imis_id+ are not allowed
-      #
-      # If no block is given, this sets the iMIS ID and returns self.
-      #
-      # @param id [Integer, String] iMIS ID to select for requests within the block
-      # @param certificate [String] Certificate number to convert to iMIS ID and select for requests within the block
-      # @param record_id [Integer] Record ID to select for requests within the block
+      # This should be used with methods that do not change the value of `imis_id`
       #
-      # @example
-      #   with(12345) do
-      #     update(mm: 15)
-      #   end
-      #
-      # @return [Usps::Imis::Api]
-      #
-      def with(id = nil, certificate: nil, record_id: nil, &)
-        raise ArgumentError, 'Must provide id or certificate' unless id || certificate
-
+      def with(id, &)
         old_id = imis_id
-        old_record_id = @record_id
-
-        id.nil? ? imis_id_for(certificate) : self.imis_id = id
-        self.record_id = record_id
-        return self unless block_given?
-
-        @lock_imis_id = true
+        self.imis_id = id
         instance_eval(&)
       ensure
-        if block_given?
-          @lock_imis_id = false
-          self.imis_id = old_id
-          self.record_id = old_record_id
-        end
+        self.imis_id = old_id
       end
 
-      # Build a Query interface
+      # Get a business object for the current member
       #
-      # Works with IQA queries and Business Objects
-      #
-      # @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 [Usps::Imis::Query] Query wrapper
-      #
-      def query(query_name, query_params = nil) = Query.new(self, query_name, **query_params)
+      def get(business_object_name, url_id: nil)
+        uri = uri_for(business_object_name, url_id:)
+        request = Net::HTTP::Get.new(uri)
+        result = submit(uri, authorize(request))
+        JSON.parse(result.body)
+      end
 
-      # Run requests as DSL, with specific +BusinessObject+ only maintained for this scope
-      #
-      # If no block is given, this returns the specified +BusinessObject+.
-      #
-      # @param business_object_name [String] Name of the business object
-      # @param ordinal [Integer] Ordinal to build override ID param of the URL (e.g. used for Panels)
+      # Update only specific fields on a business object for the current member
       #
-      # @return [Usps::Imis::BusinessObject]
+      #   fields - hash of shape: { field_name => new_value }
       #
-      def on(business_object_name, ordinal: nil, &)
-        object = BusinessObject.new(self, business_object_name, ordinal:)
-        return object unless block_given?
-
-        object.instance_eval(&)
+      def put_fields(business_object_name, fields, url_id: nil)
+        updated = filter_fields(business_object_name, fields)
+        put(business_object_name, updated, url_id:)
       end
 
-      # An instance of +Mapper+, using this instance as its parent +Api+
+      # Update a business object for the current member
       #
-      def mapper
-        @mapper ||= Mapper.new(self)
+      def put(business_object_name, body, url_id: nil)
+        uri = uri_for(business_object_name, url_id:)
+        request = Net::HTTP::Put.new(uri)
+        request.body = JSON.dump(body)
+        result = submit(uri, authorize(request))
+        JSON.parse(result.body)
       end
 
-      # Convenience alias for reading mapped fields
-      #
-      # @return Value of the specified field
-      #
-      def fetch(field_key) = mapper.fetch(field_key)
-      alias [] fetch
-
-      # Convenience alias for reading multiple mapped fields
+      # Create a business object for the current member
       #
-      # @return [Array] Values of the specified fields
-      #
-      def fetch_all(*fields) = mapper.fetch_all(*fields)
-
-      # Convenience alias for updating mapped fields
-      #
-      # @return [Array] Array containing the updated object
-      #
-      def put_field(field_key, value) = update(field_key => value)
-      alias []= put_field
+      def post(business_object_name, body, url_id: nil)
+        uri = uri_for(business_object_name, url_id:)
+        request = Net::HTTP::Post.new(uri)
+        request.body = JSON.dump(body)
+        result = submit(uri, authorize(request))
+        JSON.parse(result.body)
+      end
 
-      # Convenience alias for updating mapped fields
+      # Remove a business object for the current member
       #
-      # @return [Usps::Imis::Data] Updated object
+      # Returns empty string on success
       #
-      def update(data) = mapper.update(data)
+      def delete(business_object_name, url_id: nil)
+        uri = uri_for(business_object_name, url_id:)
+        request = Net::HTTP::Delete.new(uri)
+        result = submit(uri, authorize(request))
+        result.body
+      end
 
-      # List of available Business Object names
+      # Run an IQA Query
       #
-      # @return [Hash<Symbol, Array<String>>] Grouped available Business Objects
+      #   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 }
       #
-      def business_objects
-        abc, other = query('BOEntityDefinition').map(&:entity).partition { it.include?('ABC') }
+      def query(query_name, query_params = {})
+        query_params[:QueryName] = query_name
+        path = "#{QUERY_PATH}?#{query_params.to_query}"
+        uri = URI(File.join(imis_hostname, path))
+        request = Net::HTTP::Get.new(uri)
+        result = submit(uri, authorize(request))
+        JSON.parse(result.body)
+      end
 
-        { abc:, other: }
+      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.all(self)
+        @panels ||= PANELS.new(
+          Panel::Vsc.new(self),
+          Panel::Education.new(self)
+        )
       end
 
-      # Used by the CLI wrappers to reduce authentication requests
-      #
-      def auth_token
-        authenticate
-
-        { token: @token, token_expiration: @token_expiration }
+      def update(data)
+        mapper.update(data)
       end
 
-      # Ruby 3.5 instance variable filter
-      #
       def instance_variables_to_inspect = %i[@token_expiration @imis_id]
 
     private
 
-      # Authenticate to the iMIS API, and store the access token and expiration time
+      def client(uri)
+        Net::HTTP.new(uri.host, uri.port).tap do |http|
+          http.use_ssl = true
+          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        end
+      end
+
+      def imis_hostname
+        Imis.configuration.hostname
+      end
+
+      # Authorize a request prior to submitting
       #
-      def authenticate
-        json = nil # Scope
+      # If the current token is missing/expired, request a new one
+      #
+      def authorize(request)
+        authenticate if token_expiration < Time.now
+        request.tap { |r| r.add_field('Authorization', "Bearer #{token}") }
+      end
 
-        logger.tagged('Auth') do
-          logger.info 'Authenticating with iMIS'
+      # Construct a business object API endpoint address
+      #
+      def uri_for(business_object_name, url_id: nil)
+        url_id ||= imis_id
+        url_id = CGI.escape(url_id)
+        URI(File.join(imis_hostname, "#{API_PATH}/#{business_object_name}/#{url_id}"))
+      end
 
-          request = http_post
-          request.body = URI.encode_www_form(
-            grant_type: 'password',
-            username: Imis.configuration.username,
-            password: Imis.configuration.password
-          )
-          result = submit(uri, request)
-          json = JSON.parse(result.body)
+      def submit(uri, request)
+        client(uri).request(request).tap do |result|
+          raise Error::Response.from(result) unless result.is_a?(Net::HTTPSuccess)
         end
+      end
+
+      # Authenticate to the iMIS API, and store the access token and expiration time
+      #
+      def authenticate
+        uri = URI(File.join(imis_hostname, AUTHENTICATION_PATH))
+        req = Net::HTTP::Post.new(uri)
+        authentication_data = {
+          grant_type: 'password',
+          username: Imis.configuration.username,
+          password: Imis.configuration.password
+        }
+        req.body = URI.encode_www_form(authentication_data)
+        result = submit(uri, req)
+        json = JSON.parse(result.body)
 
         @token = json['access_token']
-        @token_expiration = Time.now + json['expires_in'] - 60
+        @token_expiration = Time.parse(json['.expires'])
       end
 
-      # URI for the authentication endpoint
+      # Manually assemble the matching data structure, with fields in the correct order
       #
-      def uri(...) = URI(File.join(Imis.configuration.hostname, AUTHENTICATION_PATH))
+      def filter_fields(business_object_name, fields)
+        existing = get(business_object_name)
+
+        JSON.parse(JSON.dump(existing)).tap do |updated|
+          # The first property is always the iMIS ID again
+          updated['Properties']['$values'] = [existing['Properties']['$values'][0]]
+
+          # Iterate through all existing fields
+          existing['Properties']['$values'].each do |value|
+            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
+
+            # Add the completed field with the updated value
+            updated['Properties']['$values'] << value
+          end
+        end
+      end
     end
   end
 end

data/lib/usps/imis/config.rb

@@ -1,87 +1,29 @@
 # frozen_string_literal: true
 
-require_relative 'logger'
-require_relative 'logger_formatter'
-require_relative 'logger_helpers'
-
 module Usps
   module Imis
-    # API Configuration
-    #
     class Config
       IMIS_ROOT_URL_PROD = 'https://portal.americasboatingclub.org'
       IMIS_ROOT_URL_DEV = 'https://abcdev.imiscloud.com'
-      REQUIRED_CONFIGS = %w[imis_id_query_name username password].freeze
 
-      attr_accessor :imis_id_query_name, :username, :password
-      attr_reader :environment, :logger, :logger_level, :logger_file
+      attr_accessor :environment, :imis_id_query_name, :username, :password
 
       def initialize
-        @environment = default_environment
-        @imis_id_query_name = ENV.fetch('IMIS_ID_QUERY_NAME', nil)
-        @username = ENV.fetch('IMIS_USERNAME', nil)
-        @password = ENV.fetch('IMIS_PASSWORD', nil)
-        @base_logger = Logger.new($stdout, level: :info)
-        @logger = ActiveSupport::TaggedLogging.new(@base_logger)
-
         yield self if block_given?
-
-        @logger_level = logger.class::SEV_LABEL[logger.level].downcase.to_sym
-      end
-
-      def environment=(env)
-        @environment = ActiveSupport::StringInquirer.new(env.to_s)
-      end
-
-      def logger=(logger)
-        @base_logger = logger.tap { it.formatter = LoggerFormatter.new }
-        @base_logger.singleton_class.include(LoggerHelpers)
-        @logger = ActiveSupport::TaggedLogging.new(@base_logger)
-      end
-
-      def logger_file=(path)
-        @logger_file = path
-        @base_logger = Logger.new(@logger_file.nil? ? $stdout : @logger_file, level: logger.level)
-        @logger = ActiveSupport::TaggedLogging.new(@base_logger)
-      end
-
-      def silence!
-        self.logger = Logger.new(nil)
       end
 
-      # Environment-specific API endpoint hostname
-      #
-      # @return The API hostname for the current environment
-      #
       def hostname
-        return IMIS_ROOT_URL_PROD if environment.production?
-        return IMIS_ROOT_URL_DEV if environment.development?
-
-        raise Errors::ConfigError, "Unexpected API environment: #{environment}"
-      end
-
-      # Ruby 3.5 instance variable filter
-      #
-      def instance_variables_to_inspect = instance_variables - %i[@password @base_logger @logger]
-
-      # Parameters to filter out of logging
-      #
-      def filtered_parameters = %i[password]
-
-      def validate!
-        missing_config = REQUIRED_CONFIGS.filter_map { it if public_send(it).nil? }
-        return if missing_config.empty?
-
-        raise Errors::ConfigError, "Missing required configuration: #{missing_config.join(', ')}"
+        case environment.to_sym
+        when :production
+          IMIS_ROOT_URL_PROD
+        when :development
+          IMIS_ROOT_URL_DEV
+        else
+          raise Error::Api, "Unexpected API environment: #{environment}"
+        end
       end
 
-    private
-
-      def default_environment
-        return ::Rails.env if defined?(::Rails)
-
-        ActiveSupport::StringInquirer.new(ENV.fetch('IMIS_ENVIRONMENT', 'development'))
-      end
+      def instance_variables_to_inspect = %i[@environment @imis_id_query_name @username]
     end
   end
 end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    module Error
+      class Api < StandardError
+        attr_accessor :metadata
+
+        def initialize(message, metadata = {})
+          super(message)
+          @metadata = metadata
+        end
+
+        def bugsnag_meta_data
+          metadata == {} ? {} : base_metadata
+        end
+
+      private
+
+        def base_metadata
+          { api: metadata }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    module Error
+      class Mapper < Api; end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    module Error
+      class Response < Api
+        attr_reader :response
+        attr_accessor :metadata
+
+        def self.from(response)
+          new(nil, response)
+        end
+
+        def initialize(_message, response, metadata = {})
+          @response = response
+          super(message, metadata)
+        end
+
+        def bugsnag_meta_data
+          base_metadata.tap { |m| m[:api].merge!(metadata) }
+        end
+
+        def message
+          [
+            "#{self.class.name}: [#{status.to_s.upcase}] The iMIS API returned an error.",
+            (metadata.inspect if metadata != {}),
+            body
+          ].compact.join("\n")
+        end
+
+      private
+
+        def base_metadata
+          { api: { status:, body: } }
+        end
+
+        def status
+          @status ||=
+            case response.code
+            when '400'
+              :bad_request
+            when '401'
+              :unauthorized # RequestVerificationToken invalid
+            when '404'
+              :not_found
+            when '422'
+              :unprocessable_entity # validation error
+            when /^50\d$/
+              :internal_server_error # error within iMIS
+            else
+              response.code
+            end
+        end
+
+        def response_body
+          @response_body ||= JSON.parse(response.body)
+        rescue StandardError
+          @response_body ||= response.body
+        end
+
+        def body
+          return response_body unless response_body.is_a?(Hash)
+
+          case response_body['error']
+          when 'invalid_grant'
+            response_body['error_description']
+          else
+            # Unknown error type: just use the raw response
+            response.body
+          end
+        end
+      end
+    end
+  end
+end