usps-imis-api 0.11.41 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac3e7c47ae3555e7cb4d83bf24585b5b4ffac669c0f60dab014996566a4ad366
-  data.tar.gz: 547b0943b75e78b4ba4b968e3a780194cfe783eaef2301a4f5cacdee6e298c0e
+  metadata.gz: 5f986785bbba830f42a6aaa6a64f339cebeee7d860468817a7c7c49cf012eed9
+  data.tar.gz: 32a73e123d38e7785f0f26b8515f5f370af3b6c0788d3665f1d69c54244dfac3
 SHA512:
-  metadata.gz: 5f7009001491dd4177d883335bdd63a2049bf157bbac66295d22c789dd1755b9672d096a760a000883f6397e4ee9c74d48cebae0c1868895e46c7b63577aaae6
-  data.tar.gz: 8509266846dab5d93389ee7486afb8f987202d1cfbda01b2e59894e2e5fe6caddf7e820b2c822335c7123535fac1b0d3ada220d9deaf20bb3ab56a3284fccd37
+  metadata.gz: a559de92104378e97072b90d01c68c9723c5635b95a409dca45b4f144c46b337d8a084a46495c616494d568ae1b7719225b4e93a79dbd385657f6255154b300a
+  data.tar.gz: 3fc29fa1f0a916103647eb2d1220bcf07ac03b5476b1aa6423593c7eca13ffee880bc9eda123eb5677ce15785d9e838428dabd1d0da69963bf98586e004a1cf4

data/Readme.md

@@ -86,4 +86,4 @@ file to [rubygems.org](https://rubygems.org).
 A wrapper for the CLI from this API is
 [available for PHP](https://github.com/unitedstatespowersquadrons/imis-api-php).
 
-You can also view the [original PHP API](https://github.com/unitedstatespowersquadrons/imis-api).
+You can also view the (***deprecated***) [original PHP API](https://github.com/unitedstatespowersquadrons/imis-api).

data/lib/usps/imis/api.rb

@@ -139,6 +139,8 @@ module Usps
       # @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
@@ -184,6 +186,8 @@ module Usps
       #
       # @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]
       #
       # @return [Usps::Imis::BusinessObject]
       #

data/lib/usps/imis/blank_object.rb

@@ -21,6 +21,8 @@ module Usps
       # Build a blank object for the current iMIS ID
       #
       # @param hash [Hash] Hash version of props to set (block takes priority)
+      # @yield Block context to define additional properties with +add+
+      # @yieldparam [Properties]
       #
       def build(hash = {}, &) = header.merge(Properties.build(parent.api.record_id.to_s, @ordinal&.to_s, hash, &))
 

data/lib/usps/imis/business_object.rb

@@ -139,11 +139,17 @@ module Usps
 
       # Build a blank object for the current iMIS ID
       #
+      # @param hash [Hash] Hash version of props to set (block takes priority)
+      # @yield Block context to define additional properties with +add+
+      # @yieldparam [Properties]
+      #
       def blank_object(hash = {}, &) = BlankObject.new(self).build(hash, &)
 
       # Create a business object for the current member, starting with a blank object and building properties
       #
       # @param hash [Hash] Hash version of props to set (block takes priority)
+      # @yield Block context to define additional properties with +add+
+      # @yieldparam [Properties]
       #
       def post_from_blank(hash = {}, &) = post(blank_object(hash, &))
       alias create_from_blank post_from_blank

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    module CommandLine
+      # Command line interface output formatters
+      #
+      # @private
+      #
+      module Formatters
+        # 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
+
+      private
+
+        def simplify(data)
+          return data.to_a if data.is_a?(Query)
+          return data.is_a?(BaseData) ? data.raw : data if force_raw_output?
+
+          if data.is_a?(PartyData)
+            logger.debug 'Returning simplified PartyData#properties'
+            data.properties
+          elsif data.is_a?(Data)
+            logger.debug 'Returning simplified Data#properties'
+            data.properties(include_ids: options[:include_ids])
+          elsif data.is_a?(Array) && data.all?(Data)
+            logger.debug 'Returning simplified Array<Data#properties>'
+            data.map { it.properties(include_ids: options[:include_ids]) }
+          else
+            data
+          end
+        end
+
+        def force_raw_output? = options[:raw] || RAW_HASH_RESPONSE_OPTIONS.any? { options[it] }
+
+        # :nocov:
+        def output(&)
+          if ENV.fetch('SUPPRESS_OUTPUT', false)
+            logger.debug 'Output suppressed'
+            return
+          end
+
+          return unless block_given?
+
+          value = yield
+
+          if value.is_a?(Array) && @options[:jsonl] then jsonl(value)
+          elsif value.is_a?(Array) && @options[:csv] then csv(value)
+          else raw(value)
+          end
+        end
+
+        def raw(value) = puts(JSON.dump(value))
+
+        def jsonl(value) = puts(value.map { JSON.dump(it) })
+
+        def csv(value)
+          puts(CSV.generate(headers: value.first.keys, write_headers: true) do |csv|
+            value.each { csv << it.values }
+          end)
+        end
+        # :nocov:
+      end
+    end
+  end
+end

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'performers'
+require_relative 'formatters'
 
 module Usps
   module Imis
@@ -9,6 +10,7 @@ module Usps
       #
       class Interface
         include Performers
+        include Formatters
 
         # Prioritized list of config file paths to automatically check if not provided
         #
@@ -17,15 +19,10 @@ module Usps
           local: File.join(Dir.pwd, 'imis.yml'),
           local_dot_config: File.join(Dir.pwd, '.config', 'imis.yml'),
           local_config: File.join(Dir.pwd, 'config', 'imis.yml'),
-          user: "#{Dir.home}/.config/imis.yml",
+          user: File.join(Dir.home, '.config', 'imis.yml'),
           system: '/usr/local/imis/config.yml'
         }.freeze
 
-        # 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
@@ -109,45 +106,6 @@ module Usps
           logger.debug "Record ID: #{api.record_id}" if api.record_id
         end
 
-        def simplify(data)
-          return data.to_a if data.is_a?(Query)
-          return data.is_a?(BaseData) ? data.raw : data if force_raw_output?
-
-          if data.is_a?(PartyData)
-            logger.debug 'Returning simplified PartyData#properties'
-            data.properties
-          elsif data.is_a?(Data)
-            logger.debug 'Returning simplified Data#properties'
-            data.properties(include_ids: options[:include_ids])
-          elsif data.is_a?(Array) && data.all?(Data)
-            logger.debug 'Returning simplified Array<Data#properties>'
-            data.map { it.properties(include_ids: options[:include_ids]) }
-          else
-            data
-          end
-        end
-
-        def force_raw_output? = options[:raw] || RAW_HASH_RESPONSE_OPTIONS.any? { options[it] }
-
-        # :nocov:
-        def output(&)
-          if ENV.fetch('SUPPRESS_OUTPUT', false)
-            logger.debug 'Output suppressed'
-            return
-          end
-
-          return unless block_given?
-
-          value = yield
-
-          if value.is_a?(Array) && @options[:jsonl]
-            puts(value.map { JSON.dump(it) })
-          else
-            puts JSON.dump(value)
-          end
-        end
-        # :nocov:
-
         # Supports YAML or JSON config data
         #
         def configure!

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

@@ -7,22 +7,25 @@ module Usps
       #
       class OptionsParser
         SOLO_FLAGS = %i[show_config auth_token business_objects].freeze
+        QUERY_FLAGS = %i[query page page_size offset].freeze
         CONFLICTING_OPTION_GROUPS = [
           %i[certificate id uuid],
           %i[record_id uuid],
           %i[on panel query mapper map] + SOLO_FLAGS,
           %i[field fields map query],
           %i[raw include_ids],
+          %i[raw jsonl csv],
           %i[quiet log_level],
           %i[quiet log],
+          %i[page offset],
 
           %i[create delete],
           %i[create ordinal],
           %i[data fields],
 
-          *(SOLO_FLAGS + %i[mapper query map field fields certificate]).map { [:create, it] },
-          *(SOLO_FLAGS + %i[mapper query map field fields certificate data raw]).map { [:delete, it] },
-          *(SOLO_FLAGS + %i[mapper query map on]).map { [:ordinal, it] },
+          *(SOLO_FLAGS + QUERY_FLAGS + %i[mapper map field fields certificate]).map { [:create, it] },
+          *(SOLO_FLAGS + QUERY_FLAGS + %i[mapper map field fields certificate data raw]).map { [:delete, it] },
+          *(SOLO_FLAGS + QUERY_FLAGS + %i[mapper map on]).map { [:ordinal, it] },
           *(SOLO_FLAGS + %i[certificate]).map { [:data, it] }
         ].freeze
 
@@ -88,17 +91,7 @@ module Usps
           #
           Optimist.educate if ARGV.empty? && defaults?
 
-          # :nocov:
-          @options[:data] = read_stdin if stdin?
-          # :nocov:
-
-          @options[:data] = JSON.parse(@options[:data]) if @options[:data]
-
-          # Support shorthand for setting `certificate` param on queries
-          return unless @options[:query] && @options[:certificate]
-
-          @options[:data] ||= {}
-          @options[:data]['certificate'] = @options.delete(:certificate)
+          pre_process_options!
         end
 
       private
@@ -128,6 +121,24 @@ module Usps
           options_with_defaults.all? { |option, data| data[1].nil? || options[option] == data[1][:default] } &&
             options.except(*options_with_defaults.keys).values.none?
         end
+
+        def pre_process_options!
+          # :nocov:
+          @options[:data] = read_stdin if stdin?
+          # :nocov:
+
+          @options[:data] = JSON.parse(@options[:data]) if @options[:data]
+
+          raise Errors::CommandLineError, 'Maximum page size is 500' if @options[:page_size] > 500
+
+          @options[:offset] = (@options[:page] - 1) * @options[:page_size] if @options[:page]
+
+          # Support shorthand for setting `certificate` param on queries
+          return unless @options[:query] && @options[:certificate]
+
+          @options[:data] ||= {}
+          @options[:data]['certificate'] = @options.delete(:certificate)
+        end
       end
     end
   end

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

@@ -15,11 +15,11 @@ module Usps
           in mapper:, **extra then perform_mapper(mapper, **extra)
           in on:, **extra then perform_on(on, **extra)
           in panel:, **extra then perform_panel(panel, **extra)
-          in query:, **extra then api.query(query, extra[:data])
+          in query:, **extra then perform_query(query, **extra)
           in business_objects: true then api.business_objects
           in auth_token: true then api.auth_token
-          in certificate: then api.imis_id
-          in show_config: then config_path
+          in certificate: _ then api.imis_id
+          in show_config: true then config_path
           in version: true then api.class.version
           end
         rescue NoMatchingPatternError => e
@@ -33,8 +33,7 @@ module Usps
             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
+            else # Nothing to convert
             end
 
             # Remove flags when false
@@ -59,8 +58,7 @@ module Usps
           in data: then on.put_fields(data)
           in fields: then on.get_fields(*fields)
           in field: then on.get_field(field)
-          else
-            on.get
+          else on.get
           end
         end
 
@@ -75,6 +73,19 @@ module Usps
           in ordinal: then panel.get(ordinal)
           end
         end
+
+        def perform_query(query, **options)
+          case options
+          in page: _, page_size:, offset:, data: then api.query(query, page_size:, offset:, **data).page
+          in page: _, page_size:, offset: then api.query(query, page_size:, offset:).page
+          in page: _, page_size:, data: then api.query(query, page_size:, **data).page
+          in page: _, page_size: then api.query(query, page_size:).page
+          in page_size:, offset:, data: then api.query(query, page_size:, offset:, **data)
+          in page_size:, data: then api.query(query, page_size:, **data)
+          in data: then api.query(query, **data)
+          else api.query(query)
+          end
+        end
       end
     end
   end

data/lib/usps/imis/command_line.rb

@@ -3,6 +3,7 @@
 require 'optimist'
 require 'colorize'
 require 'erb'
+require 'csv'
 
 module Usps
   module Imis

data/lib/usps/imis/config.rb

@@ -34,22 +34,36 @@ module Usps
         @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
 
@@ -57,12 +71,18 @@ module Usps
         @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

data/lib/usps/imis/mapper.rb

@@ -39,14 +39,14 @@ module Usps
       #
       # Only available for fields defined in +FIELD_MAPPING+
       #
-      # @param field_key [Symbol] Internal name of the field
+      # @param field_key [String, Symbol] Internal name of the field
       #
       # @return Value of the field
       #
       def get_field(field_key)
         missing_mapping!(field_key) unless FIELD_MAPPING.key?(field_key.to_sym)
 
-        business_object_name, field = FIELD_MAPPING[field_key]
+        business_object_name, field = FIELD_MAPPING[field_key.to_sym]
         api.on(business_object_name)[field]
       end
       alias fetch get_field

data/lib/usps/imis/properties.rb

@@ -10,6 +10,8 @@ module Usps
       # @param id [String] iMIS ID to include in the properties before running the block
       # @param ordinal [String] Ordinal to include in the properties before running the block
       # @param hash [Hash] Hash version of props to set (block takes priority)
+      # @yield Block context to define additional properties with +add+
+      # @yieldparam [Properties]
       #
       def self.build(id = nil, ordinal = nil, hash = {}, &) = new.build(id, ordinal, hash, &)
 
@@ -33,6 +35,7 @@ module Usps
       # @param ordinal [String] Ordinal to include in the properties before running the block
       # @param hash [Hash] Hash version of props to set (block takes priority)
       # @yield Block context to define additional properties with +add+
+      # @yieldparam [Properties]
       #
       def build(id = nil, ordinal = nil, hash = {})
         @properties ||= []

data/lib/usps/imis/version.rb

@@ -2,6 +2,6 @@
 
 module Usps
   module Imis
-    VERSION = '0.11.41'
+    VERSION = '0.12.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: usps-imis-api
 version: !ruby/object:Gem::Version
-  version: 0.11.41
+  version: 0.12.0
 platform: ruby
 authors:
 - Julian Fiander
@@ -51,6 +51,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.1.0
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.3.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.3.5
 - !ruby/object:Gem::Dependency
   name: optimist
   requirement: !ruby/object:Gem::Requirement
@@ -80,6 +94,7 @@ files:
 - lib/usps/imis/blank_object.rb
 - lib/usps/imis/business_object.rb
 - lib/usps/imis/command_line.rb
+- lib/usps/imis/command_line/formatters.rb
 - lib/usps/imis/command_line/interface.rb
 - lib/usps/imis/command_line/options_parser.rb
 - lib/usps/imis/command_line/performers.rb