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

data/lib/usps/imis/api.rb

@@ -1,313 +1,207 @@
 # frozen_string_literal: true
 
-require_relative 'business_object'
-require_relative 'mapper'
-require_relative 'query'
-
 module Usps
   module Imis
-    # The core API wrapper
-    #
     class Api
-      include Requests
-      include Imis::Helpers
-
-      NAME = 'USPS iMIS API - Ruby'
-
-      # 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
-
-      # Name and version of the API
-      #
-      def self.version = "#{NAME} (v#{Imis::VERSION})"
-
-      # 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
-      # @param record_id [Integer, String] iMIS ID to select immediately on initialization
-      # @param certificate [String] Certificate to convert to iMIS ID immediately on initialization
-      #
-      def initialize(imis_id: nil, record_id: nil, certificate: nil)
-        raise ArgumentError, 'Cannot provide both imis_id and certificate' if imis_id && certificate
-
-        @logger = Imis.logger('Api')
-        Imis.config.validate!
+      attr_reader :token, :token_expiration, :imis_id
 
+      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
-        imis_id_for(certificate) if certificate
       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, String] iMIS ID
-      #
       def imis_id=(id)
-        raise Errors::LockedIdError if lock_imis_id
-
-        @imis_id = format_id(id)
+        @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 = format_id(id)
-      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}"
-
-        net_contact_data = query('NetContactData', MajorKey: certificate).one
-        raise Errors::NotFoundError, 'Member not found' if net_contact_data.nil?
-
-        party = query('Party', UniformId: net_contact_data.id).one
-        raise Errors::NotFoundError, 'Member not found' if party.nil?
-
-        self.imis_id = party.imis_id
-      rescue Errors::ResponseError
-        raise Errors::NotFoundError, 'Member not found'
+        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
+      # This should be used with methods that do not change the value of `imis_id`
       #
-      # 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
-      # @yield Block context to run requests with a specific iMIS ID
-      # @yieldparam [Api]
-      #
-      # @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
-      #
-      # 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 }+
+      # Get a business object for the current member
       #
-      # @return [Usps::Imis::Query] Query wrapper
-      #
-      def query(query_name, query_params = {}) = 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+.
+      # Update only specific fields on a business object for the current member
       #
-      # @param business_object_name [String, Symbol] Name of the business object
-      # @param ordinal [Integer] Ordinal to build override ID param of the URL (e.g. used for Panels)
-      # @yield Block context to run requests on a specific +BusinessObject+
-      # @yieldparam [Api]
+      #   fields - hash of shape: { field_name => new_value }
       #
-      # @return [Usps::Imis::BusinessObject]
-      #
-      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
-      #
-      delegate :fetch, to: :mapper
-      alias [] fetch
-
-      # Convenience alias for reading multiple mapped fields
-      #
-      # @return [Array] Values of the specified fields
-      #
-      delegate :fetch_all, to: :mapper
-
-      # Convenience alias for updating mapped fields
+      # Create a business object for the current member
       #
-      # @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
       #
-      delegate :update, to: :mapper
+      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
 
-      # Names of every Business Object that has a registered +Models::Base+
-      # wrapper, partitioned by whether the name carries an +ABC+ prefix.
-      # Sourced from the in-process registry — no HTTP — so this answers
-      # "what does the gem know how to wrap?", not "what does the server
-      # expose?". Anything not listed still round-trips as raw +Data+.
+      # Run an IQA Query
       #
-      # @return [Hash<Symbol, Array<String>>] Grouped registered 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 = Models.entity_names.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
 
-      # Persistent HTTP connection for reuse across requests
-      #
-      def http_connection
-        return @http_connection if @http_connection&.started?
+      def instance_variables_to_inspect = %i[@token_expiration @imis_id]
+
+    private
 
-        config = Imis.configuration
-        hostname = URI(config.hostname)
-        @http_connection = Net::HTTP.new(hostname.host, hostname.port).tap do |http|
+      def client(uri)
+        Net::HTTP.new(uri.host, uri.port).tap do |http|
           http.use_ssl = true
           http.verify_mode = OpenSSL::SSL::VERIFY_PEER
-          http.open_timeout = config.open_timeout
-          http.read_timeout = config.read_timeout
-          http.write_timeout = config.write_timeout
-          http.keep_alive_timeout = 30
-          http.start
         end
       end
 
-      # Ruby 3.5 instance variable filter
-      #
-      def instance_variables_to_inspect = %i[@token_expiration @imis_id]
+      def imis_hostname
+        Imis.configuration.hostname
+      end
 
-      # Authenticate to the iMIS API, and store the access token and expiration time
+      # 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(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
 
-    private
-
-      # 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,175 +1,29 @@
 # frozen_string_literal: true
 
-require_relative 'logger'
-
 module Usps
   module Imis
-    # API Configuration
-    #
     class Config
       IMIS_ROOT_URL_PROD = 'https://portal.americasboatingclub.org'
       IMIS_ROOT_URL_DEV = 'https://abcdev.imiscloud.com'
-      DEFAULT_GLOBAL_LOG_PATH = '/var/log/imis/imis.log'
-
-      # Net::HTTP timeouts for the API connection (seconds). open_timeout governs connection
-      # establishment (TCP connect + TLS handshake) — the phase that stalls when iMIS is unreachable,
-      # so it defaults low to fail fast rather than pin the caller.
-      DEFAULT_OPEN_TIMEOUT = 3
-      DEFAULT_READ_TIMEOUT = 30
-      DEFAULT_WRITE_TIMEOUT = 30
-
-      REQUIRED = %w[username password].freeze
-      OPTIONAL = %w[
-        environment logger_file global_log_path pretty_print_api
-        open_timeout read_timeout write_timeout
-      ].freeze
-      SETTABLE = (REQUIRED + OPTIONAL).freeze
-
-      class << self
-        # Opt-in +.env+ loader. The gem no longer auto-loads dotenv on require —
-        # call this from your app boot (or before +Imis.configure+) if you want
-        # +ENV+ populated from +.env+. Idempotent.
-        #
-        def load_dotenv!
-          Dotenv.load
-        end
-      end
 
-      attr_accessor :username, :password, :pretty_print_api, :open_timeout, :read_timeout, :write_timeout
-      attr_reader :environment, :logger, :logger_level, :logger_file
+      attr_accessor :environment, :imis_id_query_name, :username, :password
 
       def initialize
-        @environment = default_environment
-        @username = ENV.fetch('IMIS_USERNAME', nil)
-        @password = ENV.fetch('IMIS_PASSWORD', nil)
-        @open_timeout = Integer(ENV.fetch('IMIS_OPEN_TIMEOUT', DEFAULT_OPEN_TIMEOUT).to_s, 10)
-        @read_timeout = Integer(ENV.fetch('IMIS_READ_TIMEOUT', DEFAULT_READ_TIMEOUT).to_s, 10)
-        @write_timeout = Integer(ENV.fetch('IMIS_WRITE_TIMEOUT', DEFAULT_WRITE_TIMEOUT).to_s, 10)
-        @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
-
-      # Define the API environment
-      #
-      # @param env [String] Environment to use
-      #
-      def environment=(env)
-        @environment = ActiveSupport::StringInquirer.new(env.to_s)
-      end
-
-      # Override the main logger
-      #
-      # @param logger [Logger] Configured logging object
-      #
-      def logger=(logger)
-        @base_logger = logger.tap { it.formatter = LoggerFormatter.new }
-        @base_logger.singleton_class.include(LoggerHelpers)
-        @logger = ActiveSupport::TaggedLogging.new(@base_logger)
-      end
-
-      # Define the main logger
-      #
-      # @param path [path, nil] Path to write log to, or +nil+ to log to +STDOUT+
-      #
-      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
-
-      # Current global mirror debug logger
-      #
-      def global_logger
-        return @global_logger if @global_logger
-
-        global_log_path
-        @global_logger
-      end
-
-      # Current path for the global mirror debug logger
-      #
-      def global_log_path
-        return @global_log_path if defined?(@global_log_path)
-
-        self.global_log_path = DEFAULT_GLOBAL_LOG_PATH
       end
 
-      # Define the global mirror debug logger
-      #
-      # @param path [path, nil] Path to write log to, or +nil+ to disable
-      #
-      def global_log_path=(path)
-        @global_log_path = path
-        @global_logger = build_global_logger
-      end
-
-      # Whether the global mirror debug logger writes anywhere. Disabled or unwritable, it is a null
-      # logger, and nothing needs to be mirrored to it.
-      #
-      def global_logging?
-        global_logger
-        @global_logging
-      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 @global_logger]
-
-      # Parameters to filter out of logging
-      #
-      def filtered_parameters = %i[password]
-
-      def validate!
-        missing_config = REQUIRED.filter_map { it if public_send(it).nil? }
-        return if missing_config.empty?
-
-        raise Errors::ConfigError, "Missing required configuration: #{missing_config.join(', ')}"
-      end
-
-    private
-
-      def default_environment
-        return ::Rails.env if defined?(::Rails)
-
-        ActiveSupport::StringInquirer.new(ENV.fetch('IMIS_ENVIRONMENT', 'development'))
+        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
 
-      def build_global_logger
-        writable =
-          begin
-            FileUtils.mkdir_p(File.dirname(global_log_path))
-            File.writable?(global_log_path) || File.writable?(File.dirname(global_log_path))
-          rescue StandardError
-            false
-          end
-        @global_logging = writable
-        return ActiveSupport::TaggedLogging.new(::Logger.new(nil)) unless writable
-
-        ActiveSupport::TaggedLogging.new(
-          ::Logger
-            .new(File.open(global_log_path, 'a'), level: :debug)
-            .tap { it.formatter = LoggerFormatter.new }
-        )
-      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