usps-imis-api 0.13.4 → 0.13.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f34a885284d3ccfeced54ef7b76cda38b69922d80c61ba22d4950945ee4bc1ea
-  data.tar.gz: fe1a7952665d65adabddf3f13eed3720b267b20ee2d5029715df096bbc82d52f
+  metadata.gz: 9d753667e0811d6bf6018675ed3959338bce46eee41dbcc021f1e2adff0eb30a
+  data.tar.gz: b12e309cbb83288fab1a6a9fb39f3bf03bb56e6972c90a564644e34f3df05b87
 SHA512:
-  metadata.gz: f99eb59125c90b6e1c7dc11b2e32c6b3eea327825785614629919b9548aa429ed30458d68f59943557e07e37c3faef6c22deddc9b5e5da127c05d26f674912d3
-  data.tar.gz: 0dd03c7791e6d1e68a0365aa87c741a44fb5b145aec6002c264e2931c6fa14f35554321ec1cb6d59dfcd36c012ccfcd2f4e0adae514886f48a31ba87a484930a
+  metadata.gz: f84414f2237be27ea64fee65287f68e9275dc294beb1b4dffb62fc8f1281a859f3e98bd257ebb25ba1d08e135ced88d6804e1071fe3b124259e4cfbbbdf2fa4c
+  data.tar.gz: 5c9e1b6fc200af2b1422047424097afef8881d3a78420f91a72f8eb72b86aa2940ab3364c7f670c25b27f9e28d351b52657ac2249e176342efd95af7b963ec3c

data/Readme.md

@@ -1,6 +1,7 @@
 # USPS iMIS API for Ruby
 
-[![Gem Version](https://img.shields.io/gem/v/usps-imis-api)](https://rubygems.org/gems/usps-imis-api)
+[![Gem Version][gem-badge]](https://rubygems.org/gems/usps-imis-api)
+[![iMIS API PHP Wrapper Version][php-badge]](https://github.com/unitedstatespowersquadrons/imis-api-php)
 
 ## Installation
 
@@ -29,7 +30,6 @@ Usps::Imis.configure do |config|
   config.environment = :development
 
   # These options will default to the listed `ENV` variable if available.
-  config.imis_id_query_name = ENV['IMIS_ID_QUERY_NAME']
   config.username = ENV['IMIS_USERNAME']
   config.password = ENV['IMIS_PASSWORD']
 
@@ -83,7 +83,10 @@ file to [rubygems.org](https://rubygems.org).
 
 ## PHP
 
-A wrapper for the CLI from this API is
-[available for PHP](https://github.com/unitedstatespowersquadrons/imis-api-php).
+A wrapper for the CLI from this API is [available for PHP][php-repo].
 
 You can also view the (***deprecated***) [original PHP API](https://github.com/unitedstatespowersquadrons/imis-api).
+
+[gem-badge]: https://img.shields.io/gem/v/usps-imis-api?logo=rubygems&logoColor=white
+[php-badge]: https://img.shields.io/endpoint?url=https%3A%2F%2Fadmin.aws.usps.org%2Flibrary_badge%2Fimis-api-php&label=wrapper&logo=php&logoColor=white
+[php-repo]: https://github.com/unitedstatespowersquadrons/imis-api-php

data/lib/usps/imis/api.rb

@@ -11,6 +11,7 @@ module Usps
     #
     class Api
       include Requests
+      include Imis::Helpers
 
       NAME = 'USPS iMIS API - Ruby'
 
@@ -77,15 +78,7 @@ module Usps
       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) then id
-          elsif id.to_i.to_s == id.to_s.gsub(' ', '') then id.to_i
-          elsif id.nil? then nil
-          else
-            raise ArgumentError, "Invalid id: #{id.inspect}"
-          end
+        @imis_id = format_id(id)
       end
 
       # Manually set the current record ID
@@ -119,11 +112,13 @@ module Usps
 
         logger.debug "Fetching iMIS ID for #{certificate}"
 
-        result = query(Imis.configuration.imis_id_query_name, { certificate: })
-        page = result.page.tap { logger.tagged('Response').debug it }
-        raise Errors::NotFoundError, 'Member not found' if page.empty?
+        net_contact_data = query('NetContactData', MajorKey: certificate).one
+        raise Errors::NotFoundError, 'Member not found' if net_contact_data.nil?
 
-        self.imis_id = page.first['ID'].to_i
+        party = query('Party', UniformId: net_contact_data.id).one
+        raise Errors::NotFoundError, 'Member not found' if party.nil?
+
+        self.imis_id = party.id
       rescue Errors::ResponseError
         raise Errors::NotFoundError, 'Member not found'
       end

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

@@ -8,9 +8,28 @@ module Usps
       # @private
       #
       module Help
-        TERMINAL_WIDTH = 120
+        # Width of the terminal window
+        #
+        # :nocov:
+        TERMINAL_WIDTH = IO.console&.winsize&.at(1) || 80
+        # :nocov:
+
+        # Extra padding between columns
+        #
         GAP = 4
 
+        # Adjust the underlying command padding to account for non-printing characters
+        #
+        # Bold and gray each add 14:
+        #   '-'.bold.length == 15
+        #   '-'.gray.length == 15
+        #
+        ESCAPE_PADDING = 14
+
+        # Pattern for removing escape codes from strings
+        #
+        ESCAPE_PATTERN = /\e\[[0-9;]*m/
+
         def banner_header(version)
           <<~BANNER
             #{version.bold.blue}
@@ -19,6 +38,12 @@ module Usps
         end
 
         def banner_contents
+          wiki = word_wrap(
+            'For an explanation of how to provide API configuration, ' \
+            'more details on the options, and usage examples, please refer to the wiki:',
+            TERMINAL_WIDTH - indent(1).length
+          ).join("\n#{indent(1)}")
+
           <<~BANNER
             #{'Usage'.underline}
 
@@ -27,10 +52,9 @@ module Usps
 
             #{'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:
+              #{wiki}
 
-              https://github.com/unitedstatespowersquadrons/imis-api-ruby/wiki/Command-Line
+              #{'https://github.com/unitedstatespowersquadrons/imis-api-ruby/wiki/Command-Line'.light_blue}
 
           BANNER
         end
@@ -51,12 +75,13 @@ module Usps
           raw_description, details = options[key]
           details ||= {}
 
-          flag = option_flag_string(key, details).ljust(option_column_width)
+          flag_string = option_flag_string(key, details)
+          flag = flag_string.ljust(option_column_width + invisible_length(flag_string))
           left_width = option_column_width + indent(3).length # Indent additional lines one step further
           tags = [
             (" (default: #{details[:default]})" if details[:default]),
             (" (max: #{details[:max]})" if details[:max])
-          ].compact.join
+          ].compact.join.gray
 
           "#{flag}#{wrap_description(raw_description, left_width, suffix: tags)}"
         end
@@ -64,29 +89,21 @@ module Usps
       private
 
         def help_commands(lines)
-          # Adjust the underlying command padding to account for non-printing characters
-          #
-          # Bold and gray each add 14:
-          #   '-'.bold.length == 15
-          #   '-'.gray.length == 15
-          #
-          escape_padding = 14
-
-          command_lengths = subcommands.map { |name, details| name.length + details[:value].to_s.length }
-          command_width = command_lengths.max + GAP + escape_padding
-
           lines << "#{'Commands'.underline}\n"
           subcommands.each do |name, details|
             combined_name = details[:value] ? "#{name.bold} #{"<#{details[:value]}>".gray}" : name.bold
-            lines << [
-              indent(1),
-              combined_name.ljust(command_width + (details[:value] ? escape_padding : 0)),
-              details[:description]
-            ].join
+            command = combined_name.ljust(command_width + (details[:value] ? ESCAPE_PADDING : 0))
+            left_width = indent(1).length + command_width
+            lines << "#{indent(1)}#{command}#{wrap_description(details[:description], left_width)}"
           end
           lines << "\n"
         end
 
+        def command_width
+          command_lengths = subcommands.map { |name, details| name.length + details[:value].to_s.length }
+          command_lengths.max + GAP + ESCAPE_PADDING
+        end
+
         def help_options(lines)
           lines << "#{'Options'.underline}\n"
           option_groups.each do |group_name, option_keys|
@@ -98,9 +115,16 @@ module Usps
 
         def help_legacy_flags(lines)
           lines << "#{indent(1)}#{'Legacy Flags'.underline}\n"
-          lines << "#{indent(2)}The following options are still supported, but have been replaced by subcommands:\n"
+          explanation = word_wrap(
+            'The following options are still supported, but have been replaced by subcommands:',
+            TERMINAL_WIDTH - indent(2).length
+          ).join("\n#{indent(2)}")
+          lines << "#{indent(2)}#{explanation}\n"
+
           legacy_flags.each do |flags, replacement|
-            lines << "#{indent(2)}#{flags.ljust(option_column_width)}use:  #{replacement}"
+            left_width = indent(2).length + option_column_width
+            description = wrap_description("#{'use:'.light_magenta}  #{replacement}", left_width)
+            lines << "#{indent(2)}#{flags.ljust(option_column_width + invisible_length(flags))}#{description}"
           end
           lines << "\n"
         end
@@ -128,7 +152,7 @@ module Usps
           when :io then '=<io>'
           when :ios then '=<io+>'
           else ''
-          end
+          end.gray
         end
 
         def wrap_description(text, left_width, suffix: '')
@@ -162,17 +186,16 @@ module Usps
           lines
         end
 
-        def visible_length(text)
-          text.gsub(/\e\[[0-9;]*m/, '').length
-        end
+        def visible_length(text) = text.gsub(ESCAPE_PATTERN, '').length
+        def invisible_length(text) = text.length - visible_length(text)
 
         def option_column_width
           option_widths = option_groups.values.flatten.map do |key|
             _, details = options[key]
-            option_flag_string(key, details || {}).length
+            visible_length(option_flag_string(key, details || {}))
           end
 
-          all_widths = option_widths + legacy_flags.keys.map(&:length)
+          all_widths = option_widths + legacy_flags.keys.map { visible_length(it) }
           all_widths.max + GAP
         end
       end

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

@@ -168,9 +168,11 @@ module Usps
 
         def default_options? = options[:log_level] == 'info' && options.except(:log_level).values.none?
 
-        # :nocov:
-        def handle_exception!(exception) = options[:trace] ? raise(exception) : exit(2)
-        # :nocov:
+        def handle_exception!(exception)
+          raise(exception) if options[:trace] || ENV.fetch('TESTING', false) || ENV.fetch('CI', false)
+
+          exit(2)
+        end
       end
     end
   end

data/lib/usps/imis/command_line/{options.yml.erb → options.yml}

@@ -2,47 +2,40 @@ Subcommands:
   object:
     description: Interact with a Business Object
     value: name
-    legacy_name: 'on'
+    legacy: 'on'
     option:
-      - Business Object name
-      - type: string
-        short: O
+      type: string
+      short: O
   panel:
     description: Interact with a Panel
     value: name
     option:
-      - Panel name
-      - type: string
-        short: P
+      type: string
+      short: P
   query:
     description: Run an IQA or Business Object Query
     value: name
     option:
-      - IQA Query or Business Object name to query
-      - type: string
-        short: Q
+      type: string
+      short: Q
   mapper:
     description: Interact with mapped fields
     option:
-      - Interact with mapped fields
-      - short: M
+      short: M
   map:
-    description: "Shorthand for `<%= 'mapper -f'.green %>` to access a single mapped field"
+    description: Shorthand for `%{green:mapper -f}` to access a single mapped field
     value: field
     option:
-      - "Shorthand for <%= '-Mf'.green %> to access a single mapped field"
-      - type: string
-        short: m
+      type: string
+      short: m
   business-objects:
     description: List available Business Objects
     option:
-      - List available Business Objects
-      - short: B
+      short: B
   auth-token:
     description: Return an auth token for other language wrappers
     option:
-      - Return an auth token for other language wrappers
-      - short: T
+      short: T
 
 Options:
   Identity:
@@ -65,13 +58,13 @@ Options:
 
   Business Object or Panel:
     create:
-      - "Send a <%= 'POST'.cyan %> request"
+      - Send a %{cyan:POST} request
       - short: C
     delete:
-      - "Send a <%= 'DELETE'.cyan %> request"
+      - Send a %{cyan:DELETE} request
       - short: D
     all:
-      - "Send a <%= 'GET'.cyan %> request for all records for a member"
+      - Send a %{cyan:GET} request for all records for a member
       - short: A
 
   Panel:
@@ -106,7 +99,7 @@ Options:
       - type: strings
         short: F
     data:
-      - "JSON string input -- <%= 'STDIN'.red %> takes priority"
+      - JSON string input -- %{red:STDIN} takes priority
       - type: string
         short: d
 
@@ -126,21 +119,20 @@ Options:
 
   Configuration:
     config:
-      - "Path to the JSON/YAML config file to use, or one of the following preset options:\
-        \n`<%= 'local_dot'.yellow %>`, \
-        `<%= 'local'.yellow %>`, \
-        `<%= 'local_dot_config'.yellow %>`, \
-        `<%= 'local_config'.yellow %>`, \
-        `<%= 'user'.yellow %>`, \
-        `<%= 'system'.yellow %>`\
-        \nIf no option is provided, the first matching preset option will be automatically used."
+      - >-
+        Path to the JSON/YAML config file to use, or one of the following preset options:
+
+        `%{yellow:local_dot}`, `%{yellow:local}`, `%{yellow:local_dot_config}`,
+        `%{yellow:local_config}`, `%{yellow:user}`, `%{yellow:system}`
+
+        If no option is provided, the first matching preset option will be automatically used.
       - type: string
         short: Y
     show_config:
       - Return the active config file path
       - short: X
     include_ids:
-      - "Include any <%= 'iMIS ID'.yellow %> and <%= 'Ordinal'.yellow %> properties in returned data"
+      - Include any %{yellow:iMIS ID} and %{yellow:Ordinal} properties in returned data
       - short: N
     token:
       - Provide an existing auth token
@@ -149,10 +141,10 @@ Options:
 
   Logging:
     quiet:
-      - "Suppress logging to <%= 'STDERR'.red %>"
+      - Suppress logging to %{red:STDERR}
       - short: q
     log:
-      - "Redirect logging to <%= 'STDOUT'.red %>"
+      - Redirect logging to %{red:STDOUT}
       - short: l
     log_level:
       - Set the logging level
@@ -165,10 +157,10 @@ Options:
 
   Misc:
     version:
-      - Print version and exit
+      - Return API version
       - short: v
     environment:
-      - Print configured environment and exit
+      - Return configured environment
       - short: E
     help:
       - Show this message

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

@@ -8,8 +8,15 @@ module Usps
       # @private
       #
       module OptionsParserConfig
+        STYLE_NAMES = (String.colors + String.modes).map(&:to_s).freeze
+        STYLE_PATTERN = /%\{(#{Regexp.union(STYLE_NAMES)}(?:\.#{Regexp.union(STYLE_NAMES)})*):(.*?)\}/
+
         def subcommands
-          @subcommands ||= yaml['Subcommands'].transform_values { it.transform_keys(&:to_sym) }
+          @subcommands ||= yaml['Subcommands'].transform_values do |details|
+            details.transform_keys(&:to_sym).tap do |h|
+              h[:description] = colorize_text(h[:description]) if h[:description]
+            end
+          end
         end
 
         def option_groups
@@ -19,7 +26,7 @@ module Usps
         def options
           @options ||= merged_options.transform_keys(&:to_sym).transform_values do |description, details|
             [
-              description,
+              colorize_text(description),
               details.transform_keys(&:to_sym).each_with_object({}) do |(key, value), hash|
                 hash[key] = %i[type short].include?(key) ? value.to_sym : value
               end
@@ -29,15 +36,15 @@ module Usps
 
         def legacy_aliases
           @legacy_aliases ||= subcommands.each_with_object({}) do |(name, details), aliases|
-            next unless details[:legacy_name]
+            next unless details[:legacy]
 
-            aliases["--#{details[:legacy_name]}"] = "--#{name}"
+            aliases["--#{details[:legacy]}"] = "--#{name}"
           end
         end
 
         def legacy_flags
           @legacy_flags ||= subcommands.to_h do |name, details|
-            flag_name = details[:legacy_name] || name.tr('-', '_')
+            flag_name = details[:legacy] || name.tr('-', '_')
             option_key = name.tr('-', '_').to_sym
             _, option_details = options[option_key]
 
@@ -51,15 +58,22 @@ module Usps
       private
 
         def yaml
-          return @yaml if @yaml
+          @yaml ||= YAML.safe_load_file("#{File.dirname(__FILE__)}/options.yml")
+        end
 
-          raw_yaml_erb = File.read("#{File.dirname(__FILE__)}/options.yml.erb")
-          rendered_yaml = ERB.new(raw_yaml_erb).result.gsub("\x1b", '\u001b')
-          @yaml = YAML.safe_load(rendered_yaml)
+        def colorize_text(text)
+          text.gsub(STYLE_PATTERN) do
+            Regexp.last_match(2).colorize(
+              Regexp.last_match(1).split('.').each_with_object({}) do |name, args|
+                key = String.colors.include?(name.to_sym) ? :color : :mode
+                args[key] = name.to_sym
+              end
+            )
+          end
         end
 
         def merged_options
-          subcommand_options = subcommands.transform_values { it[:option] }.transform_keys { it.gsub('-', '_') }
+          subcommand_options = subcommands.transform_values { ['', it[:option]] }.transform_keys { it.gsub('-', '_') }
           yaml['Options'].values.inject(:merge).merge(subcommand_options)
         end
       end

data/lib/usps/imis/command_line.rb

@@ -2,8 +2,8 @@
 
 require 'optimist'
 require 'colorize'
-require 'erb'
 require 'csv'
+require 'io/console'
 
 module Usps
   module Imis

data/lib/usps/imis/config.rb

@@ -14,16 +14,15 @@ module Usps
       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'
-      REQUIRED = %w[imis_id_query_name username password].freeze
+      REQUIRED = %w[username password].freeze
       OPTIONAL = %w[environment logger_file global_log_path].freeze
       SETTABLE = (REQUIRED + OPTIONAL).freeze
 
-      attr_accessor :imis_id_query_name, :username, :password
+      attr_accessor :username, :password
       attr_reader :environment, :logger, :logger_level, :logger_file
 
       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)

data/lib/usps/imis/data.rb

@@ -10,18 +10,23 @@ module Usps
     # Convenience wrapper for accessing specific properties within an API data response
     #
     class Data < BaseData
+      include Imis::Helpers
+
       # The Business Object or Panel name
       #
       def entity = raw['EntityTypeName']
 
       # Access the iMIS ID (i.e. Party ID) property
       #
-      def imis_id = raw['PrimaryParentIdentity']['IdentityElements']['$values'].first.to_i
+      def imis_id = format_id(raw['PrimaryParentIdentity']['IdentityElements']['$values'].first)
       alias id imis_id
 
       # Access the Record ID property
       #
-      def record_id = raw['Identity']['IdentityElements']['$values'].first.to_i
+      def record_id
+        identity = format_id(raw['Identity']['IdentityElements']['$values'].first)
+        identity unless identity == imis_id
+      end
 
       # Access the Ordinal identifier property (if present)
       #
@@ -51,7 +56,7 @@ module Usps
     private
 
       def pretty_print_data
-        { entity:, imis_id:, record_id: (record_id unless record_id == imis_id), ordinal: }.compact
+        { entity:, imis_id:, record_id:, ordinal: }.compact
       end
 
       def property_values = raw['Properties']['$values']

data/lib/usps/imis/helpers.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    # General helper methods
+    #
+    module Helpers
+      # Helper for consistently formatting valid IDs
+      #
+      def format_id(raw_id)
+        hex = '[0-9a-fA-F]'
+        uuid_pattern = /^#{hex}{8}-#{hex}{4}-#{hex}{4}-#{hex}{4}-#{hex}{12}$/
+
+        if raw_id.to_s.match?(uuid_pattern) then raw_id
+        elsif raw_id.to_i.to_s == raw_id.to_s.gsub(' ', '') then raw_id.to_i
+        elsif raw_id.nil? then nil
+        else
+          raise ArgumentError, "Invalid id: #{raw_id.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/usps/imis/query.rb

@@ -90,6 +90,10 @@ module Usps
       #
       def page = fetch_next['Items']['$values'].map { iqa? ? it.except('$type') : wrap(it) }
 
+      # Fetch the first result from a single query page
+      #
+      def one = page.first
+
       # Fetch the next raw query page, and update the current offset
       #
       def fetch_next

data/lib/usps/imis/version.rb

@@ -2,6 +2,6 @@
 
 module Usps
   module Imis
-    VERSION = '0.13.4'
+    VERSION = '0.13.6'
   end
 end

data/lib/usps/imis.rb

@@ -20,6 +20,7 @@ require 'active_support/tagged_logging'
 require 'dotenv/load'
 
 # Internal requires
+require_relative 'imis/helpers'
 require_relative 'imis/config'
 require_relative 'imis/error'
 require_relative 'imis/api'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: usps-imis-api
 version: !ruby/object:Gem::Version
-  version: 0.13.4
+  version: 0.13.6
 platform: ruby
 authors:
 - Julian Fiander
@@ -97,7 +97,7 @@ files:
 - lib/usps/imis/command_line/formatters.rb
 - lib/usps/imis/command_line/help.rb
 - lib/usps/imis/command_line/interface.rb
-- lib/usps/imis/command_line/options.yml.erb
+- lib/usps/imis/command_line/options.yml
 - lib/usps/imis/command_line/options_parser.rb
 - lib/usps/imis/command_line/options_parser_config.rb
 - lib/usps/imis/command_line/performers.rb
@@ -115,6 +115,7 @@ files:
 - lib/usps/imis/errors/pattern_matching_error.rb
 - lib/usps/imis/errors/response_error.rb
 - lib/usps/imis/errors/unexpected_property_type_error.rb
+- lib/usps/imis/helpers.rb
 - lib/usps/imis/logger.rb
 - lib/usps/imis/logger_formatter.rb
 - lib/usps/imis/logger_helpers.rb