usps-imis-api 0.6.16 → 0.7.1

data/lib/usps/imis/{error → errors}/response_error.rb

@@ -2,10 +2,10 @@
 
 module Usps
   module Imis
-    module Error
+    module Errors
       # Exception raised due to receiving an error response from the API
       #
-      class ResponseError < ApiError
+      class ResponseError < Error
         # [Net::HTTPResponse] The response received from the API
         #
         attr_reader :response
@@ -18,17 +18,14 @@ module Usps
         #
         # @param response [Net::HTTPResponse] The response received from the API
         #
-        def self.from(response)
-          new(nil, response)
-        end
+        def self.from(response) = new(response)
 
         # Create a new instance of +ResponseError+
         #
-        # @param _message Ignored
         # @param response [Net::HTTPResponse] The response received from the API
         # @param metadata [Hash] Additional call-specific metadata to pass through to Bugsnag
         #
-        def initialize(_message, response, metadata = {})
+        def initialize(response, metadata = {})
           @response = response
           super(message, metadata)
         end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    module Errors
+      # Exception raised when attempting to wrap an unexpected property type
+      #
+      class UnexpectedPropertyTypeError < Error
+        # Create a new instance of +UnexpectedPropertyTypeError+ from an unexpected value
+        #
+        # @param value Unexpected value
+        #
+        def self.from(value) = new(value)
+
+        # Create a new instance of +UnexpectedPropertyTypeError+
+        #
+        # @param value Unexpected value
+        # @param metadata [Hash] Additional call-specific metadata to pass through to Bugsnag
+        #
+        def initialize(value, metadata = {})
+          @value = value
+          super(message, metadata)
+        end
+
+        # Exception message including the undefined method
+        #
+        def message = "Unexpected property type: #{@value.inspect}"
+      end
+    end
+  end
+end

data/lib/usps/imis/mapper.rb

@@ -73,11 +73,7 @@ module Usps
           # :nocov:
         end
 
-        raise(
-          Error::MapperError,
-          "Unrecognized field: \"#{field_name}\". " \
-          'Please report what data you are attempting to work with to ITCom leadership.'
-        )
+        raise Errors::MapperError.new({ field_name: })
       end
     end
   end

data/lib/usps/imis/mocks/business_object.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Usps
+  module Imis
+    module Mocks
+      # Mock data response for testing
+      #
+      class BusinessObject
+        attr_reader :fields
+
+        def initialize(**fields)
+          @fields = fields.transform_keys(&:to_s)
+        end
+
+        def get_field(name) = fields[name]
+
+        def get
+          Usps::Imis::Properties.build do |props|
+            fields.each { |name, value| props.add(name, value) }
+          end
+        end
+
+        def put_fields(data)
+          Usps::Imis::Properties.build do |props|
+            fields.merge(data.transform_keys(&:to_s)).each { |name, value| props.add(name, value) }
+          end
+        end
+
+        def put(data) = data
+
+        def post(data) = data
+
+        def delete = ''
+      end
+    end
+  end
+end

data/lib/usps/imis/mocks.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'mocks/business_object'
+
+module Usps
+  module Imis
+    # Namespace for all Mocks
+    #
+    module Mocks; end
+  end
+end

data/lib/usps/imis/{panel → panels}/base_panel.rb

@@ -2,7 +2,7 @@
 
 module Usps
   module Imis
-    module Panel
+    module Panels
       # Base class for configuring Panels
       #
       class BasePanel
@@ -17,25 +17,37 @@ module Usps
 
         # Get a specific object from the Panel
         #
+        # If +fields+ is provided, will return only those field values
+        #
+        # @param fields [String] Field names to return
+        #
         # @param ordinal [Integer] The ordinal identifier for the desired object
         #
-        def get(ordinal)
-          api.on(business_object, ordinal:).get
-        end
+        # @return [Hash, Array<Hash>] Response data from the API
+        #
+        def get(ordinal, *fields) = api.on(business_object, ordinal:).get(*fields)
         alias read get
 
         # Get a single named field from a Panel for the current member
         #
         # @param ordinal [Integer] The ordinal identifier for the desired object
-        # @param name [String] Field name to return
+        # @param field [String] Field name to return
         #
         # @return [Hash] Response data from the API
         #
-        def get_field(ordinal, name)
-          api.on(business_object, ordinal:).get_field(name)
-        end
+        def get_field(ordinal, field) = api.on(business_object, ordinal:).get_field(field)
         alias fetch get_field
 
+        # Get named fields from a Panel for the current member
+        #
+        # @param ordinal [Integer] The ordinal identifier for the desired object
+        # @param fields [Array<String>] Field names to return
+        #
+        # @return [Hash] Response data from the API
+        #
+        def get_fields(ordinal, *fields) = api.on(business_object, ordinal:).get_fields(*fields)
+        alias fetch_all get_fields
+
         # Update only specific fields on a Panel for the current member
         #
         # @param ordinal [Integer] The ordinal identifier for the desired object
@@ -43,9 +55,7 @@ module Usps
         #
         # @return [Hash] Response data from the API
         #
-        def put_fields(ordinal, fields)
-          api.on(business_object, ordinal:).put_fields(fields)
-        end
+        def put_fields(ordinal, fields) = api.on(business_object, ordinal:).put_fields(fields)
         alias patch put_fields
 
         # Update an existing object in the Panel
@@ -53,37 +63,31 @@ module Usps
         # @param data [Hash] The record data for the desired object -- including the required
         #                    +ordinal+ identifier
         #
-        def put(data)
-          api.on(business_object, ordinal: data[:ordinal]).put(payload(data))
-        end
+        def put(data) = api.on(business_object, ordinal: data[:ordinal]).put(payload(data))
         alias update put
 
         # Create a new object in the Panel
         #
         # @param data [Hash] The record data for the desired object
         #
-        def post(data)
-          api.on(business_object).post(payload(data))
-        end
+        def post(data) = api.on(business_object).post(payload(data))
         alias create post
 
         # Remove a specific object from the Panel
         #
         # @param ordinal [Integer] The ordinal identifier for the desired object
         #
-        def delete(ordinal)
-          api.on(business_object, ordinal:).delete
-        end
+        def delete(ordinal) = api.on(business_object, ordinal:).delete
         alias destroy delete
 
       private
 
         def business_object
-          raise Error::ApiError, "#{self.class.name} must implement #business_object"
+          raise Errors::PanelUnimplementedError.from(self.class.name, 'business_object')
         end
 
         def payload(_data)
-          raise Error::ApiError, "#{self.class.name} must implement #payload(data)"
+          raise Errors::PanelUnimplementedError.from(self.class.name, 'payload(data)')
         end
 
         def payload_header(data)

data/lib/usps/imis/{panel → panels}/education.rb

@@ -2,7 +2,7 @@
 
 module Usps
   module Imis
-    module Panel
+    module Panels
       # Panel for accessing the Educational completions business object
       #
       class Education < BasePanel

data/lib/usps/imis/{panel → panels}/vsc.rb

@@ -2,7 +2,7 @@
 
 module Usps
   module Imis
-    module Panel
+    module Panels
       # Panel for accessing the annual VSC completed counts business object
       #
       class Vsc < BasePanel

data/lib/usps/imis/panels.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'panels/base_panel'
+require_relative 'panels/vsc'
+require_relative 'panels/education'
+
+module Usps
+  module Imis
+    # Namespace for all Panels
+    #
+    module Panels
+      # Convenience accessor for available Panel objects
+      #
+      # @param api [Api] Parent to use for making requests
+      #
+      def self.all(api = Api.new)
+        panels = constants.reject { it == :BasePanel }
+
+        Struct
+          .new(*panels.map { it.to_s.underscore.to_sym })
+          .new(*panels.map { const_get(it).new(api) })
+      end
+    end
+  end
+end

data/lib/usps/imis/properties.rb

@@ -42,7 +42,7 @@ module Usps
         when Integer then { '$type' => 'System.Int32', '$value' => value }
         when true, false then { '$type' => 'System.Boolean', '$value' => value }
         else
-          raise Error::ApiError, "Unexpected property type: #{value.inspect}"
+          raise Errors::UnexpectedPropertyTypeError.from(value)
         end
       end
     end

data/lib/usps/imis/requests.rb

@@ -25,7 +25,7 @@ module Usps
 
       def submit(uri, request)
         client(uri).request(request).tap do |result|
-          raise Error::ResponseError.from(result) unless result.is_a?(Net::HTTPSuccess)
+          raise Errors::ResponseError.from(result) unless result.is_a?(Net::HTTPSuccess)
         end
       end
     end

data/lib/usps/imis/version.rb

@@ -2,6 +2,6 @@
 
 module Usps
   module Imis
-    VERSION = '0.6.16'
+    VERSION = '0.7.1'
   end
 end

data/lib/usps/imis.rb

@@ -6,27 +6,17 @@ require 'json'
 require 'time'
 require 'cgi'
 
+require 'active_support/core_ext/string/inflections'
+require 'active_support/core_ext/object/to_query'
 require 'active_support/string_inquirer'
 
-# Extensions
-# :nocov:
-require 'ext/hash' unless defined?(Rails)
-# :nocov:
-
 # Internal requires
 require_relative 'imis/config'
-require_relative 'imis/error/api_error'
-require_relative 'imis/error/mapper_error'
-require_relative 'imis/error/response_error'
-require_relative 'imis/requests'
-require_relative 'imis/business_object'
+require_relative 'imis/error'
 require_relative 'imis/api'
-require_relative 'imis/mapper'
 require_relative 'imis/properties'
-require_relative 'imis/business_object_mock'
-require_relative 'imis/panel/base_panel'
-require_relative 'imis/panel/vsc'
-require_relative 'imis/panel/education'
+require_relative 'imis/panels'
+require_relative 'imis/mocks'
 
 module Usps
   # API wrapper for interacting with iMIS

data/spec/lib/usps/imis/api_spec.rb

@@ -31,7 +31,7 @@ describe Usps::Imis::Api do
 
       it 'wraps errors' do
         expect { api.imis_id_for('E231625') }.to raise_error(
-          Usps::Imis::Error::ApiError, 'Member not found'
+          Usps::Imis::Errors::NotFoundError, 'Member not found'
         )
       end
     end
@@ -64,7 +64,7 @@ describe Usps::Imis::Api do
     context 'when receiving a response error' do
       let(:warning_text) do
         <<~WARNING.chomp
-          Usps::Imis::Error::ResponseError: [INTERNAL_SERVER_ERROR] The iMIS API returned an error.
+          Usps::Imis::Errors::ResponseError: [INTERNAL_SERVER_ERROR] The iMIS API returned an error.
           Something went wrong
         WARNING
       end
@@ -79,7 +79,7 @@ describe Usps::Imis::Api do
 
       it 'wraps the error' do
         expect { api.on('ABC_ASC_Individual_Demog').put_fields('TotMMS' => 15) }.to(
-          raise_error(Usps::Imis::Error::ApiError, warning_text)
+          raise_error(Usps::Imis::Errors::ResponseError, warning_text)
         )
       end
     end
@@ -103,13 +103,13 @@ describe Usps::Imis::Api do
     it 'blocks calling imis_id=' do
       expect do
         api.with(31092) { self.imis_id = 31092 }
-      end.to raise_error(Usps::Imis::Error::ApiError, 'Cannot change iMIS ID while locked')
+      end.to raise_error(Usps::Imis::Errors::LockedIdError, 'Cannot change iMIS ID while locked')
     end
 
     it 'blocks calling imis_id_for' do
       expect do
         api.with(31092) { imis_id_for('E231625') }
-      end.to raise_error(Usps::Imis::Error::ApiError, 'Cannot change iMIS ID while locked')
+      end.to raise_error(Usps::Imis::Errors::LockedIdError, 'Cannot change iMIS ID while locked')
     end
   end
 

data/spec/lib/usps/imis/business_object_spec.rb

@@ -6,20 +6,8 @@ describe Usps::Imis::BusinessObject do
   let(:business_object) { described_class.new(api, 'Stub') }
   let(:api) { Usps::Imis::Api.new }
 
-  let(:expected) do
-    {
-      'Properties' => {
-        '$values' => [
-          { 'Name' => 'ID', 'Value' => { '$value' => '31092' } },
-          { 'Name' => 'Stub Integer', 'Value' => { '$value' => 43 } },
-          { 'Name' => 'Stub String', 'Value' => 'other' }
-        ]
-      }
-    }
-  end
-
   before do
-    allow(business_object).to receive(:get).and_return({
+    allow(business_object).to receive(:raw_object).and_return({
       'Properties' => {
         '$values' => [
           { 'Name' => 'ID', 'Value' => { '$value' => '31092' } },
@@ -30,6 +18,22 @@ describe Usps::Imis::BusinessObject do
     })
   end
 
+  describe '#get' do
+    it 'returns multiple values' do
+      expect(business_object.get('Stub String', 'Stub Integer')).to eq(['something', 42])
+    end
+
+    describe 'delegation to get_fields' do
+      before { allow(business_object).to receive(:get_fields).with('Stub String', 'Stub Integer') }
+
+      it 'delegates to get_fields' do
+        business_object.get('Stub String', 'Stub Integer')
+
+        expect(business_object).to have_received(:get_fields).with('Stub String', 'Stub Integer')
+      end
+    end
+  end
+
   describe '#get_field' do
     it 'returns a string value' do
       expect(business_object.get_field('Stub String')).to eq('something')
@@ -40,7 +44,25 @@ describe Usps::Imis::BusinessObject do
     end
   end
 
+  describe '#get_fields' do
+    it 'returns multiple values' do
+      expect(business_object.get_fields('Stub String', 'Stub Integer')).to eq(['something', 42])
+    end
+  end
+
   describe '#filter_fields' do
+    let(:expected) do
+      {
+        'Properties' => {
+          '$values' => [
+            { 'Name' => 'ID', 'Value' => { '$value' => '31092' } },
+            { 'Name' => 'Stub Integer', 'Value' => { '$value' => 43 } },
+            { 'Name' => 'Stub String', 'Value' => 'other' }
+          ]
+        }
+      }
+    end
+
     it 'formats fields correctly' do
       updated = business_object.send(:filter_fields, 'Stub Integer' => 43, 'Stub String' => 'other')
 

data/spec/lib/usps/imis/config_spec.rb

@@ -51,7 +51,7 @@ describe Usps::Imis::Config do
 
       it 'raises an error' do
         expect { config.hostname }.to raise_error(
-          Usps::Imis::Error::ApiError, 'Unexpected API environment: nothing'
+          Usps::Imis::Errors::ConfigError, 'Unexpected API environment: nothing'
         )
       end
     end

data/spec/lib/usps/imis/{error/api_error_spec.rb → error_spec.rb}

@@ -2,7 +2,7 @@
 
 require 'spec_helper'
 
-describe Usps::Imis::Error::ApiError do
+describe Usps::Imis::Error do
   it 'builds Bugsnag metadata' do
     error = described_class.new('Example', something: :else)
 

data/spec/lib/usps/imis/{error → errors}/response_error_spec.rb

@@ -4,7 +4,7 @@ require 'spec_helper'
 
 ApiResponseStub = Struct.new(:code, :body)
 
-describe Usps::Imis::Error::ResponseError do
+describe Usps::Imis::Errors::ResponseError do
   let(:error) { described_class.from(response) }
 
   describe 'error codes' do
@@ -61,7 +61,7 @@ describe Usps::Imis::Error::ResponseError do
     let(:response) { ApiResponseStub.new('500', 'Body of the API response error') }
     let(:warning_text) do
       <<~WARNING.chomp
-        Usps::Imis::Error::ResponseError: [INTERNAL_SERVER_ERROR] The iMIS API returned an error.
+        Usps::Imis::Errors::ResponseError: [INTERNAL_SERVER_ERROR] The iMIS API returned an error.
         Body of the API response error
       WARNING
     end
@@ -78,7 +78,7 @@ describe Usps::Imis::Error::ResponseError do
     let(:response) { ApiResponseStub.new('500', response_body) }
     let(:warning_text) do
       <<~WARNING.chomp
-        Usps::Imis::Error::ResponseError: [INTERNAL_SERVER_ERROR] The iMIS API returned an error.
+        Usps::Imis::Errors::ResponseError: [INTERNAL_SERVER_ERROR] The iMIS API returned an error.
         description
       WARNING
     end
@@ -95,7 +95,7 @@ describe Usps::Imis::Error::ResponseError do
     let(:response) { ApiResponseStub.new('500', response_body) }
     let(:warning_text) do
       <<~WARNING.chomp
-        Usps::Imis::Error::ResponseError: [INTERNAL_SERVER_ERROR] The iMIS API returned an error.
+        Usps::Imis::Errors::ResponseError: [INTERNAL_SERVER_ERROR] The iMIS API returned an error.
         #{response_body}
       WARNING
     end

data/spec/lib/usps/imis/mapper_spec.rb

@@ -22,8 +22,8 @@ describe Usps::Imis::Mapper do
 
     it 'raises for unmapped updates' do
       expect { api.mapper.update(something: 'anything') }.to raise_error(
-        Usps::Imis::Error::MapperError,
-        'Unrecognized field: "something". ' \
+        Usps::Imis::Errors::MapperError,
+        %(Mapper does not recognize field: "something".\n) \
         'Please report what data you are attempting to work with to ITCom leadership.'
       )
     end

data/spec/lib/usps/imis/{business_object_mock_spec.rb → mocks/business_object_spec.rb}

@@ -2,7 +2,7 @@
 
 require 'spec_helper'
 
-describe Usps::Imis::BusinessObjectMock do
+describe Usps::Imis::Mocks::BusinessObject do
   let(:mock) { described_class.new(**fields) }
   let(:fields) { { TotMMS: 2 } }
 

data/spec/lib/usps/imis/panels/base_panel_spec.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+module Usps
+  module Imis
+    module Panels
+      class InvalidPanel < BasePanel; end
+
+      class InvalidPanelWithBusinessObject < BasePanel
+      private
+
+        def business_object = 'Something'
+      end
+    end
+  end
+end
+
+describe Usps::Imis::Panels::BasePanel do
+  it 'requires #business_object to be defined' do
+    expect { Usps::Imis::Panels::InvalidPanel.new.get(1) }.to raise_error(
+      Usps::Imis::Errors::PanelUnimplementedError,
+      'Usps::Imis::Panels::InvalidPanel must implement #business_object'
+    )
+  end
+
+  it 'requires #payload(data) to be defined' do
+    expect { Usps::Imis::Panels::InvalidPanelWithBusinessObject.new.create({}) }.to raise_error(
+      Usps::Imis::Errors::PanelUnimplementedError,
+      'Usps::Imis::Panels::InvalidPanelWithBusinessObject must implement #payload(data)'
+    )
+  end
+end

data/spec/lib/usps/imis/{panel → panels}/education_spec.rb

@@ -2,7 +2,7 @@
 
 require 'spec_helper'
 
-describe Usps::Imis::Panel::Education do
+describe Usps::Imis::Panels::Education do
   describe 'api example' do
     let(:education) { described_class.new }
 
@@ -23,6 +23,10 @@ describe Usps::Imis::Panel::Education do
       it 'loads a specific object' do
         expect(education.get(90737)).to be_a(Hash)
       end
+
+      it 'returns specific fields' do
+        expect(education.get(90737, 'ABC_Product_Code', 'ABC_Other_Code')).to eq(%w[CRS AP])
+      end
     end
 
     describe '#get_field' do
@@ -31,6 +35,12 @@ describe Usps::Imis::Panel::Education do
       end
     end
 
+    describe '#get_fields' do
+      it 'returns specific fields' do
+        expect(education.get_fields(90737, 'ABC_Product_Code', 'ABC_Other_Code')).to eq(%w[CRS AP])
+      end
+    end
+
     # rubocop:disable RSpec/ExampleLength
     it 'interacts with records correctly', :aggregate_failures do
       new_record = education.create(details)
@@ -51,7 +61,7 @@ describe Usps::Imis::Panel::Education do
       end
       expect(patched['Value']).to eq('Online Exams System - Mod2')
 
-      expect(education.destroy(ordinal)).to eq('')
+      expect(education.destroy(ordinal)).to be(true)
     end
     # rubocop:enable RSpec/ExampleLength
   end

data/spec/lib/usps/imis/{panel → panels}/vsc_spec.rb

@@ -2,7 +2,7 @@
 
 require 'spec_helper'
 
-describe Usps::Imis::Panel::Vsc do
+describe Usps::Imis::Panels::Vsc do
   let(:vsc) { described_class.new }
 
   let(:details) do
@@ -32,7 +32,7 @@ describe Usps::Imis::Panel::Vsc do
     updated = update_result['Properties']['$values'].find { it['Name'] == 'Quantity' }
     expect(updated['Value']['$value']).to eq(43)
 
-    expect(vsc.destroy(ordinal)).to eq('')
+    expect(vsc.destroy(ordinal)).to be(true)
   end
   # rubocop:enable RSpec/ExampleLength
 end

data/spec/lib/usps/imis/properties_spec.rb

@@ -13,7 +13,7 @@ describe Usps::Imis::Properties do
 
   it 'raises an error for unexpected property types' do
     expect { builder.send(:wrap, {}) }.to raise_error(
-      Usps::Imis::Error::ApiError, 'Unexpected property type: {}'
+      Usps::Imis::Errors::UnexpectedPropertyTypeError, 'Unexpected property type: {}'
     )
   end
 end

data/usps-imis-api.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |s|
   s.version       = Usps::Imis::VERSION
   s.summary       = 'iMIS API Wrapper'
   s.description   = 'A wrapper for the iMIS API.'
-  s.homepage      = 'http://rubygems.org/gems/usps-imis-api'
+  s.homepage      = 'https://github.com/unitedstatespowersquadrons/imis-api-ruby'
   s.authors       = ['Julian Fiander']
   s.email         = 'jsfiander@gmail.com'
   s.require_paths = %w[lib]