usps-imis-api 0.11.42 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db2bc7a4cecec659c0b9d6c86ec8a5819f066537f35b0db089ca5f7df243c597
-  data.tar.gz: 7945390fbd0d073799a01e25cbfd9ffcd6a590da818055a39a7c6368a881e787
+  metadata.gz: 6d4935929ad9c147f74130bc48c0980ad3ffa801bb7fb19680f07fca5492d58d
+  data.tar.gz: dc9dee4a54c2b39fa7b30ec518fb797855f40022d8990b9d6bb348a22bf23006
 SHA512:
-  metadata.gz: 20eca697722eb6ef3d502afa3b87f46655feee6739eabec86580a032d28f590f29b619abdca8d25f56edcc77a7584305fe9911c73c596b5b70dd847d00fb1b96
-  data.tar.gz: 92676045e015b98881b8d40e5d99b9720ddae3618d3686837e6ac9ac0a5414308ba146f4a9339e64038f85c696abbc2d07f148c3a62bed14d93c9f9e7096f0b7
+  metadata.gz: d867fd2358a479359eeb68b00e97c4da63e74909c51ba4eb335af3e4353ec3eb297f79a0d538e565adfc8bf080127d261f8a59f430127266ed9efbb0cebf0039
+  data.tar.gz: 8fc15085b191a48c63d7de467e6479846cde28158e4dbd02d847082243450135e68120b6e9f88d6c497d4c841a3aedd763c7f9c182023588fe89f4642b2c9c55

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
         #
@@ -21,11 +23,6 @@ module Usps
           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.yml.erb

@@ -0,0 +1,134 @@
+# IDs
+certificate:
+  - Member certificate number
+  - type: string
+    short: c
+id:
+  - Member iMIS ID
+  - type: integer
+    short: i
+record_id:
+  - Specific Record ID
+  - type: integer
+    short: I
+uuid:
+  - Record UUID
+  - type: string
+    short: u
+
+# Primary interactions
+'on':
+  - Business Object name
+  - type: string
+    short: O
+panel:
+  - Panel name
+  - type: string
+    short: P
+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
+    short: m
+business_objects:
+  - List available Business Objects
+  - short: B
+
+# Alternate verbs
+create:
+  - "Send a <%= 'POST'.cyan %> request"
+  - short: C
+delete:
+  - "Send a <%= 'DELETE'.cyan %> request"
+  - short: D
+
+# Data
+ordinal:
+  - Ordinal ID within a Panel
+  - type: integer
+    short: r
+field:
+  - Specific field to return or update
+  - type: string
+    short: f
+fields:
+  - Specific field(s) to return
+  - type: strings
+    short: F
+data:
+  - "JSON string input -- <%= 'STDIN'.red %> takes priority"
+  - type: string
+    short: d
+
+# Query params
+page:
+  - Specific page number from a query to return
+  - type: integer
+    default: 1
+    short: p
+page_size:
+  - Maximum number of records to include on a single page (max 500)
+  - type: integer
+    default: 100
+    short: -s
+offset:
+  - Number of records to skip from the beginning of a query
+  - type: integer
+    short: -o
+
+# Output formats
+raw:
+  - Return raw JSON output, rather than simplified data
+  - short: R
+jsonl:
+  - Format array output as JSONL
+  - short: j
+csv:
+  - Format output as CSV (if possible)
+  - short: S
+
+# General config
+config:
+  - "Path to the JSON/YAML config file to use, or one of the following preset options: \
+    `<%= 'local'.yellow %>`, \
+    `<%= 'local_dot_config'.yellow %>`, \
+    `<%= 'local_config'.yellow %>`, \
+    `<%= 'user'.yellow %>`, \
+    `<%= 'system'.yellow %>`. \
+    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"
+  - short: N
+
+# 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
+    short: t
+
+# Logging
+quiet:
+  - "Suppress logging to <%= 'STDERR'.red %>"
+  - short: q
+log:
+  - "Redirect logging to <%= 'STDOUT'.red %>"
+  - short: l
+log_level:
+  - Set the logging level
+  - type: string
+    default: info
+    short: L

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/version.rb

@@ -2,6 +2,6 @@
 
 module Usps
   module Imis
-    VERSION = '0.11.42'
+    VERSION = '0.12.1'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: usps-imis-api
 version: !ruby/object:Gem::Version
-  version: 0.11.42
+  version: 0.12.1
 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,7 +94,9 @@ 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.yml.erb
 - lib/usps/imis/command_line/options_parser.rb
 - lib/usps/imis/command_line/performers.rb
 - lib/usps/imis/config.rb