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

data/lib/usps/imis/business_object.rb

@@ -1,209 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'requests'
-require_relative 'data'
-
-module Usps
-  module Imis
-    # DEV
-    class BusinessObject
-      include Requests
-
-      # Endpoint for general API requests
-      #
-      API_PATH = 'api'
-
-      # The parent +Api+ object
-      #
-      attr_reader :api
-
-      # Name of the iMIS Business Object
-      #
-      attr_reader :business_object_name
-
-      # Ordinal to build override ID param of the URL (e.g. used for Panels)
-      #
-      attr_reader :ordinal
-
-      # Tagged logger
-      #
-      attr_reader :logger
-
-      # A new instance of +BusinessObject+
-      #
-      def initialize(api, business_object_name, ordinal: nil)
-        @api = api
-        @business_object_name = business_object_name
-        @ordinal = ordinal
-        @logger ||= Imis.logger('BusinessObject')
-      end
-
-      # Run a query on the entire business object
-      #
-      # @return [Usps::Imis::Query] Query wrapper
-      #
-      def query = api.query(business_object_name)
-
-      # Support passthrough for Api#with
-      #
-      def with(imis_id, &)
-        # Bring into local scope
-        wrapper_business_object_name = business_object_name
-        wrapper_ordinal = ordinal
-
-        api.with(imis_id) do
-          on(wrapper_business_object_name, ordinal: wrapper_ordinal, &)
-        end
-      end
-
-      # Get a business object for the current member
-      #
-      # If +fields+ is provided, will return only those field values
-      #
-      # @param fields [String] Field names to return
-      #
-      # @return [Usps::Imis::Data, Array<Usps::Imis::Data>] Response data from the API
-      #
-      def get(*fields) = fields.any? ? get_fields(*fields) : raw_object
-      alias read get
-
-      # Get a single named field from a business object for the current member
-      #
-      # @param field [String] Field name to return
-      #
-      # @return Response data field value from the API
-      #
-      def get_field(field) = raw_object[field]
-      alias fetch get_field
-      alias [] get_field
-
-      # Get named fields from a business object for the current member
-      #
-      # @param names [Array<String>] Field names to return
-      #
-      # @return [Array] Response data from the API
-      #
-      def get_fields(*fields)
-        values = raw_object
-        fields.map { values[it] }
-      end
-      alias fetch_all get_fields
-
-      # Update a single named field on a business object for the current member
-      #
-      # @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) = put(filter_fields(field => value))
-      alias []= put_field
-
-      # Update only specific fields on a business object for the current member
-      #
-      # @param fields [Hash] Conforms to pattern +{ field_key => value }+
-      #
-      # @return [Usps::Imis::Data] Response data from the API
-      #
-      def put_fields(fields) = put(filter_fields(fields))
-      alias patch put_fields
-
-      # Update a business object for the current member
-      #
-      # Any properties not included will be left unmodified
-      #
-      # @param body [Hash] Full raw API object data
-      #
-      # @return [Usps::Imis::Data] Response data from the API
-      #
-      def put(body) = put_object(http_put, body)
-      alias update put
-
-      # Create a business object for the current member
-      #
-      # @param body [Hash] Full raw API object data
-      #
-      # @return [Usps::Imis::Data] Response data from the API
-      #
-      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(http_delete)).body == '' # rubocop:disable Naming/PredicateMethod
-      alias destroy delete
-
-      # Ruby 3.5 instance variable filter
-      #
-      def instance_variables_to_inspect = instance_variables - %i[@api @logger]
-
-    private
-
-      # Construct a business object API endpoint address
-      #
-      def uri(id: nil)
-        full_path = "#{API_PATH}/#{business_object_name}/#{id_for_uri(id)}"
-        URI(File.join(Imis.configuration.hostname, full_path))
-      end
-
-      # Select the correct ID to use in the URI
-      #
-      def id_for_uri(id = nil)
-        return CGI.escape(id) unless id.nil?
-        return CGI.escape("~#{api.imis_id}|#{ordinal}") if ordinal
-
-        api.imis_id.to_s
-      end
-
-      # Manually assemble the matching data structure, with fields in the correct order
-      #
-      def filter_fields(fields)
-        existing = get
-
-        JSON.parse(JSON.dump(existing)).tap do |updated|
-          # Preserve the iMIS ID, as well as the Ordinal (if present)
-          updated['Properties']['$values'], properties =
-            existing.raw['Properties']['$values'].partition { %w[ID Ordinal].include?(it['Name']) }
-
-          # Iterate through all existing fields
-          properties.each do |value|
-            # Skip unmodified fields
-            next unless fields.keys.include?(value['Name'])
-
-            value['Value'] = Properties.wrap(fields[value['Name']])
-
-            # Add the completed field with the updated value
-            updated['Properties']['$values'] << value
-          end
-        end
-      end
-
-      # Get a raw object response from the API
-      #
-      # 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)
-        logger.json result
-        result
-      end
-
-      # 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)
-        logger.json result
-        result
-      end
-    end
-  end
-end

data/lib/usps/imis/command_line/interface.rb

@@ -1,204 +0,0 @@
-# frozen_string_literal: true
-
-module Usps
-  module Imis
-    module CommandLine
-      # Command line interface for the Api
-      #
-      class Interface
-        NAME = 'USPS iMIS API - Ruby'
-
-        # CLI options that indicate the response is a raw Hash rather than a Data object,
-        # and should not be simplified
-        #
-        RAW_HASH_RESPONSE_OPTIONS = %i[business_objects auth_token].freeze
-
-        # Options passed in from the command line
-        #
-        attr_reader :options
-
-        # Tagged logger
-        #
-        attr_reader :logger
-
-        def self.run(...) = new(...).run
-
-        def initialize(**)
-          @options = input_options.merge(**)
-          options[:version] = true if default_options?
-
-          configure! if options[:config]
-          logging!
-          @logger ||= Imis.logger('CommandLine')
-        end
-
-        def run
-          logger.info 'Running'
-          logger.debug 'CLI Options:'
-          logger.json(options.dup.tap { it[:token] = '[FILTERED]' if it[:token] })
-
-          set_member
-
-          result = simplify(perform!)
-
-          output { result }
-
-          result
-        end
-
-      private
-
-        # :nocov:
-        def input_options
-          if ENV.fetch('CI', false) || ENV.fetch('TESTING', false)
-            defaults = {
-              raw: false,
-              quiet: false,
-              log: false,
-              log_level: 'info',
-              version: false,
-              help: false
-            }
-            return defaults
-          end
-
-          OptionsParser.new.options
-        end
-        # :nocov:
-
-        def api
-          @api ||=
-            if options[:token]
-              Usps::Imis::Api.with_token(options[:token])
-            else
-              Usps::Imis::Api.new
-            end
-        end
-
-        def set_member
-          case options
-          in certificate: then api.imis_id_for(certificate)
-          in id: then api.imis_id = id
-          else
-            # Query
-          end
-
-          logger.debug "iMIS ID: #{api.imis_id}" if api.imis_id
-        end
-
-        # rubocop:disable Metrics
-        def perform!
-          case convert(options)
-          in mapper:, field:, data: then mapper.put_field(field.to_sym, data)
-          in mapper:, fields: then mapper.get_fields(*fields)
-          in mapper:, field: then mapper.get_field(field.to_sym)
-          in mapper:, data: then mapper.update(data)
-
-          in on:, delete: true then on.delete
-          in on:, create: true, data: then on.post(data)
-          in on:, data:, field: then on.put_field(field, data)
-          in on:, data: then on.put_fields(data)
-          in on:, fields: then on.get_fields(*fields)
-          in on:, field: then on.get_field(field)
-          in on: then on.get
-
-          in panel:, delete: true, ordinal: then panel.delete(ordinal)
-          in panel:, create: true, data: then panel.post(data)
-          in panel:, ordinal:, data:, field: then panel.put_field(ordinal, field, data)
-          in panel:, ordinal:, data: then panel.put_fields(ordinal, data)
-          in panel:, ordinal:, fields: then panel.get_fields(ordinal, *fields)
-          in panel:, ordinal:, field: then panel.get_field(ordinal, field)
-          in panel:, ordinal: then panel.get(ordinal)
-
-          in query:, data: then api.query(query, data)
-          in query: then api.query(query)
-
-          in business_objects: true then api.business_objects
-
-          in auth_token: true then api.auth_token
-
-          in certificate: then api.imis_id
-
-          in version: true then "#{Interface::NAME} (v#{Imis::VERSION})"
-          end
-        rescue NoMatchingPatternError => e
-          raise Errors::CommandLineError, "Unable to match pattern from options: #{e.message}"
-        end
-        # rubocop:enable Metrics
-
-        def convert(options)
-          options.dup.tap do |converted|
-            case converted
-            in map: then converted.merge!(mapper: api.mapper, field: map)
-            in mapper: true then converted[:mapper] = api.mapper
-            in on: then converted[:on] = api.on(on)
-            in panel: then converted[:panel] = api.panels.public_send(panel)
-            else
-              # Nothing to convert
-            end
-
-            # Remove mapper flag when false
-            converted.delete(:mapper) unless converted[:mapper]
-          end
-        end
-
-        def simplify(data)
-          return data.to_a if data.is_a?(Query)
-          return data if options[:raw] || RAW_HASH_RESPONSE_OPTIONS.any? { options[it] }
-
-          # Hash includes Usps::Imis::Data
-          if data.is_a?(Hash)
-            logger.debug 'Returning simplified Data#properties'
-            data.properties(include_ids: options[:include_ids])
-          elsif data.is_a?(Array) && data.all? { it.is_a?(Hash) }
-            logger.debug 'Returning simplified Array<Data#properties>'
-            data.map { it.properties(include_ids: options[:include_ids]) }
-          else
-            data
-          end
-        end
-
-        # :nocov:
-        def output(&block)
-          if ENV.fetch('SUPPRESS_OUTPUT', false)
-            logger.debug 'Output suppressed'
-            return
-          end
-
-          puts JSON.dump(block.call) if block_given?
-        end
-        # :nocov:
-
-        # Supports YAML or JSON config data
-        #
-        def configure!
-          config_data = YAML.safe_load_file(options[:config])
-
-          Usps::Imis.configure do |config|
-            config_data.each do |key, value|
-              config.public_send("#{key}=", value)
-            end
-          end
-        end
-
-        def logging!
-          Usps::Imis.configure do |config|
-            # :nocov:
-            if options[:quiet] || ENV.fetch('SUPPRESS_OUTPUT', false)
-              config.logger = ActiveSupport::TaggedLogging.new(Logger.new(nil))
-            elsif options[:log] || config.logger_file
-              # Use default, or configured file
-            else
-              config.logger = ActiveSupport::TaggedLogging.new(Logger.new($stderr))
-            end
-            # :nocov:
-
-            config.logger.level = options[:log_level]
-          end
-        end
-
-        def default_options? = options[:log_level] == 'info' && options.except(:log_level).values.none?
-      end
-    end
-  end
-end

data/lib/usps/imis/command_line/options_parser.rb

@@ -1,136 +0,0 @@
-# frozen_string_literal: true
-
-module Usps
-  module Imis
-    module CommandLine
-      # Command line options parser
-      #
-      class OptionsParser
-        OPTIONS = {
-          # IDs
-          certificate: ['Member certificate number', { type: :string }],
-          id: ['Member iMIS ID', { type: :integer }],
-
-          # Primary interactions
-          on: ['Business Object name', { type: :string }],
-          panel: ['Panel name', { type: :string }],
-          query: ['IQA Query or Business Object name to query', { type: :string, short: :Q }],
-          mapper: ['Interact with mapped fields', { short: :M }],
-          map: ["Shorthand for #{'-Mf'.green} to access a single mapped field", { type: :string }],
-          business_objects: ['List available Business Objects'],
-
-          # Alternate verbs
-          create: ["Send a #{'POST'.cyan} request", { short: :P }],
-          delete: ["Send a #{'DELETE'.cyan} request", { short: :D }],
-
-          # Data
-          ordinal: ['Ordinal ID within a Panel', { type: :integer }],
-          field: ['Specific field to return or update', { type: :string }],
-          fields: ['Specific field(s) to return', { type: :strings, short: :F }],
-          data: ['JSON string input', { type: :string }],
-
-          # Iteractions for supporting other language wrappers
-          auth_token: ['Return an auth token for other language wrappers', { short: :T }],
-          token: ['Provide an existing auth token', { type: :string }],
-
-          # General config
-          config: ['Path to the JSON/YAML config file to use', { type: :string, short: :C }],
-          raw: ['Return raw JSON output, rather than simplified data', { short: :R }],
-          include_ids: ["Include any #{'iMIS ID'.yellow} and #{'Ordinal'.yellow} properties in returned data"],
-          quiet: ["Suppress logging to #{'STDERR'.red}"],
-          log: ["Redirect logging to #{'STDOUT'.red}"],
-          log_level: ['Set the logging level', { type: :string, default: 'info', short: :L }]
-        }.freeze
-
-        CONFLICTING_OPTION_GROUPS = [
-          %i[certificate id],
-          %i[on panel query mapper map business_objects auth_token],
-          %i[field fields map query],
-          %i[raw include_ids],
-          %i[quiet log_level],
-          %i[quiet log],
-
-          %i[create delete],
-
-          %i[create mapper],
-          %i[create query],
-          %i[create map],
-          %i[create field],
-          %i[create fields],
-
-          %i[delete mapper],
-          %i[delete query],
-          %i[delete map],
-          %i[delete field],
-          %i[delete fields],
-          %i[delete data],
-          %i[delete raw]
-        ].freeze
-
-        attr_reader :arguments, :options
-
-        def self.banner_header(version)
-          <<~BANNER
-            #{version.bold.blue}
-            #{'P/R/C Julian Fiander, SN'.gray}\n \n
-          BANNER
-        end
-
-        def self.banner_contents
-          <<~BANNER
-            #{'Usage'.underline}
-
-              #{'imis'.bold} #{'[options]'.gray}
-
-
-            #{'Further Help'.underline}
-
-              For an explanation of how to provide API configuration, more details on the options,
-              and usage examples, please refer to the wiki:
-
-              https://github.com/unitedstatespowersquadrons/imis-api-ruby/wiki/Command-Line
-
-
-            #{'Options'.underline}
-          BANNER
-        end
-
-        def initialize
-          @options = parse_options.compact
-          @arguments = ARGV # Not currently used
-
-          Optimist.educate if ARGV.empty? && defaults? # DEV: This shadows setting the --version flag by default
-
-          # :nocov:
-          @options[:data] = read_stdin if stdin?
-          # :nocov:
-
-          @options[:data] = JSON.parse(@options[:data]) if @options[:data]
-        end
-
-      private
-
-        def parse_options
-          Optimist.options do
-            version "#{Interface::NAME} (v#{Usps::Imis::VERSION})"
-
-            banner OptionsParser.banner_header(version)
-            banner OptionsParser.banner_contents
-
-            OPTIONS.each { |option, data| opt(option, *data) }
-            CONFLICTING_OPTION_GROUPS.each { |group| conflicts(*group) }
-
-            educate_on_error
-          end
-        end
-
-        # :nocov:
-        def stdin? = $stdin.wait_readable(0)
-        def read_stdin = $stdin.read.chomp
-        # :nocov:
-
-        def defaults? = options[:log_level] == 'info' && options.except(:log_level).values.none?
-      end
-    end
-  end
-end

data/lib/usps/imis/command_line.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-require 'optimist'
-require 'colorize'
-
-module Usps
-  module Imis
-    # Wrapper for the command line interface
-    #
-    module CommandLine; end
-  end
-end
-
-require_relative 'command_line/options_parser'
-require_relative 'command_line/interface'

data/lib/usps/imis/data.rb

@@ -1,76 +0,0 @@
-# frozen_string_literal: true
-
-require 'pp'
-require 'stringio'
-
-module Usps
-  module Imis
-    # Convenience wrapper for accessing specific properties within an API data response
-    #
-    class Data < Hash
-      # Load raw API response JSON to access properties
-      #
-      # @param json [String] Raw API response JSON
-      #
-      def self.from_json(json) = self[JSON.parse(json)]
-
-      alias raw to_h
-
-      # The Business Object or Panel name
-      #
-      def entity = raw['EntityTypeName']
-
-      # Access the iMIS ID property
-      #
-      def imis_id = self['ID'].to_i
-      alias id imis_id
-
-      # Access the Ordinal identifier property (if present)
-      #
-      def ordinal = self['Ordinal']&.to_i
-
-      # Access an individual property value by name
-      #
-      def [](property_name)
-        property = raw['Properties']['$values'].find { it['Name'] == property_name }
-        return if property.nil?
-
-        value = property['Value']
-        value.nil? || value.is_a?(String) ? value : value['$value']
-      end
-
-      # Hash of all property names to values
-      #
-      # @param include_ids [Boolean] Whether to include the iMIS ID and Ordinal
-      #
-      def properties(include_ids: false)
-        raw['Properties']['$values']
-          .map { it['Name'] }
-          .select { include_ids || !%w[ID Ordinal].include?(it) }
-          .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)
-        stringio.string.delete("\n")
-      end
-
-      def pretty_print(pp)
-        data = { entity:, imis_id:, ordinal: }.compact
-
-        pp.group(1, "#<#{self.class}", '>') do
-          data.each do |key, value|
-            pp.breakable
-            pp.text "#{key}="
-            pp.pp value
-          end
-        end
-      end
-    end
-  end
-end

data/lib/usps/imis/error.rb

@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-module Usps
-  module Imis
-    # Base error class for all internal exceptions
-    #
-    class Error < StandardError
-      # Additional call-specific metadata to pass through to Bugsnag
-      #
-      attr_accessor :metadata
-
-      # A new instance of +ApiError+
-      #
-      # @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
-
-        Imis.logger(self.class.name).error self
-      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
-
-    private
-
-      def base_metadata
-        { api: metadata }
-      end
-    end
-  end
-end
-
-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'
-require_relative 'errors/unexpected_property_type_error'
-require_relative 'errors/command_line_error'

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

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module Usps
-  module Imis
-    module Errors
-      # Generic exception raised from within the gem
-      #
-      class ApiError < Error; end
-    end
-  end
-end