usps-imis-api 0.7.1 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca358fc80eed74b0335f6137f71e503fffbc84d6c396c8e1c23c90501eab5b36
-  data.tar.gz: 239111a5dfd7cb186fe358fc0227e3063744225cf619e12a91e994f639142e56
+  metadata.gz: ea2c1c51fb9d73e9aa4dc60f4be57c72443f9d2f4e16fcd8e572af8e1b7c58e6
+  data.tar.gz: ffd74ed752fe1cfc9f0c0eaeb166e1d13bf75cf40d0b07bafaa9ce1de5b09c49
 SHA512:
-  metadata.gz: 2f31860395762aeead9f002f96867111758a8474ada928ba1369e3122b767f0b27052ed41157d8eac008fade27bdb779389cd65c74ad7cadbb87129ee9c238ff
-  data.tar.gz: 7c0f5eaae8592a93192e08ca4cf88e604629de246b8e2f9272880d19e39a218d01a027387720a6c289b7f4490bc6617b57c637ab00201868ecd36fd178748031
+  metadata.gz: e3fad87c5d7fa1c3bfa8c0140304b39e7df21d5e9abdc5234a183a1175409c5f42fe8e65f8e53975b127f15004a65aa988d533ce68ed56d3867d470f28353b2b
+  data.tar.gz: 872e0e9a73136a6166a5c585c8286d106e3d81758e2eccdbc8f8a1b1fc2d845883680e54323ffbd5902f599cbcc685be611ff1edf62c917d5e42b5ec92ba79ef

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    usps-imis-api (0.7.1)
+    usps-imis-api (0.8.1)
       activesupport (~> 8.0)
 
 GEM

data/Readme.md

@@ -101,6 +101,15 @@ You can also pass in specific field names to filter the returned member data, e.
 data = api.on('ABC_ASC_Individual_Demog').get('TotMMS', 'MMS_Updated')
 ```
 
+The response from `get` behaves like a Hash, but directly accesses property values by name.
+If you need to access the rest of the underlying data, use the `raw` method:
+
+```ruby
+data = api.on('ABC_ASC_Individual_Demog').get
+data['TotMMS']
+data.raw['EntityTypeName']
+```
+
 Alias: `read`
 
 #### GET Field
@@ -111,6 +120,12 @@ To fetch a specific field from member data, run e.g.:
 tot_mms = api.on('ABC_ASC_Individual_Demog').get_field('TotMMS')
 ```
 
+You can also access fields directly on the Business Object or Panel like a Hash:
+
+```ruby
+tot_mms = api.on('ABC_ASC_Individual_Demog')['TotMMS']
+```
+
 Alias: `fetch`
 
 #### GET Fields
@@ -171,8 +186,6 @@ To remove member data, run e.g.:
 api.on('ABC_ASC_Individual_Demog').delete
 ```
 
-This returns a blank string on success.
-
 Alias: `destroy`
 
 ### QUERY
@@ -214,11 +227,24 @@ vsc = Usps::Imis::Panels::Vsc.new(imis_id: 6374)
 
 vsc.get(1417)
 
+# All of these options are identical
+#
+vsc.get(1417, 'Quantity').first
+vsc.get(1417)['Quantity']
+vsc[1417, 'Quantity']
+vsc.get(1417).raw['Properties']['$values'].find { it['Name'] == 'Quantity' }['Value']['$value']
 vsc.get_field(1417, 'Quantity')
 
 created = vsc.create(certificate: 'E136924', year: 2024, count: 42)
-ordinal = created['Properties']['$values'].find { it['Name'] == 'Ordinal' }['Value']['$value']
-# ordinal = created['Identity']['IdentityElements']['$values'][1] # Alternative
+
+# Get the Ordinal identifier from the response
+#
+# All of these options are identical
+#
+ordinal = created.ordinal
+ordinal = created['Ordinal']
+ordinal = created.raw['Properties']['$values'].find { it['Name'] == 'Ordinal' }['Value']['$value']
+ordinal = created.raw['Identity']['IdentityElements']['$values'][1].to_i # Value is duplicated here
 
 vsc.update(certificate: 'E136924', year: 2024, count: 43, ordinal: ordinal)
 
@@ -270,12 +296,18 @@ api.with(31092) do
   # These requests are identical:
 
   on('ABC_ASC_Individual_Demog') do
-    get['Properties']['$values'].find { it['Name'] == 'TotMMS' }['Value']['$value']
-  end
+    get.raw['Properties']['$values'].find { it['Name'] == 'TotMMS' }['Value']['$value']
 
-  on('ABC_ASC_Individual_Demog') { get_field('TotMMS') }
+    get['TotMMS']
+
+    get_field('TotMMS')
+
+    get_fields('TotMMS').first
+  end
 
   on('ABC_ASC_Individual_Demog').get_field('TotMMS')
+
+  on('ABC_ASC_Individual_Demog')['TotMMS']
 end
 
 # This request fetches the same data, but leaves the iMIS ID selected

data/lib/usps/imis/api.rb

@@ -54,7 +54,7 @@ module Usps
       def imis_id=(id)
         raise Errors::LockedIdError if lock_imis_id
 
-        @imis_id = id&.to_i&.to_s
+        @imis_id = id&.to_i
       end
 
       # Convert a member's certificate number into an iMIS ID number
@@ -68,7 +68,7 @@ module Usps
 
         begin
           result = query(Imis.configuration.imis_id_query_name, { certificate: })
-          @imis_id = result['Items']['$values'][0]['ID']
+          @imis_id = result['Items']['$values'][0]['ID'].to_i
         rescue StandardError
           raise Errors::NotFoundError, 'Member not found'
         end

data/lib/usps/imis/business_object.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'requests'
+require_relative 'data'
 
 module Usps
   module Imis
@@ -38,7 +39,7 @@ module Usps
       #
       # @param fields [String] Field names to return
       #
-      # @return [Hash, Array<Hash>] Response data from the API
+      # @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
@@ -47,20 +48,21 @@ module Usps
       #
       # @param field [String] Field name to return
       #
-      # @return [Hash] Response data from the API
+      # @return Response data field value from the API
       #
-      def get_field(field) = extract_field_value(raw_object_values, field)
+      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<Hash>] Response data from the API
+      # @return [Array] Response data from the API
       #
       def get_fields(*fields)
-        values = raw_object_values
-        fields.map { extract_field_value(values, it) }
+        values = raw_object
+        fields.map { values[it] }
       end
       alias fetch_all get_fields
 
@@ -68,7 +70,7 @@ module Usps
       #
       # @param fields [Hash] Conforms to pattern +{ field_key => value }+
       #
-      # @return [Hash] Response data from the API
+      # @return [Usps::Imis::Data] Response data from the API
       #
       def put_fields(fields) = put(filter_fields(fields))
       alias patch put_fields
@@ -79,7 +81,7 @@ module Usps
       #
       # @param body [Hash] Full raw API object data
       #
-      # @return [Hash] Response data from the API
+      # @return [Usps::Imis::Data] Response data from the API
       #
       def put(body) = put_object(Net::HTTP::Put.new(uri), body)
       alias update put
@@ -88,7 +90,7 @@ module Usps
       #
       # @param body [Hash] Full raw API object data
       #
-      # @return [Hash] Response data from the API
+      # @return [Usps::Imis::Data] Response data from the API
       #
       def post(body) = put_object(Net::HTTP::Post.new(uri(id: '')), body)
       alias create post
@@ -118,7 +120,7 @@ module Usps
         return CGI.escape(id) unless id.nil?
         return CGI.escape("~#{api.imis_id}|#{ordinal}") if ordinal
 
-        api.imis_id
+        api.imis_id.to_s
       end
 
       # Manually assemble the matching data structure, with fields in the correct order
@@ -129,7 +131,7 @@ module Usps
         JSON.parse(JSON.dump(existing)).tap do |updated|
           # Preserve the iMIS ID, as well as the Ordinal (if present)
           updated['Properties']['$values'], properties =
-            existing['Properties']['$values'].partition { %w[ID Ordinal].include?(it['Name']) }
+            existing.raw['Properties']['$values'].partition { %w[ID Ordinal].include?(it['Name']) }
 
           # Iterate through all existing fields
           properties.each do |value|
@@ -157,18 +159,7 @@ module Usps
       def raw_object
         request = Net::HTTP::Get.new(uri)
         result = submit(uri, authorize(request))
-        JSON.parse(result.body)
-      end
-
-      # Get just the property values from an object response from the API
-      #
-      def raw_object_values
-        raw_object['Properties']['$values']
-      end
-
-      def extract_field_value(values, field)
-        value = values.find { it['Name'] == field }['Value']
-        value.is_a?(String) ? value : value['$value']
+        Data.from_json(result.body)
       end
 
       # Upload an object to the API
@@ -176,7 +167,7 @@ module Usps
       def put_object(request, body)
         request.body = JSON.dump(body)
         result = submit(uri, authorize(request))
-        JSON.parse(result.body)
+        Data.from_json(result.body)
       end
     end
   end

data/lib/usps/imis/data.rb

@@ -0,0 +1,61 @@
+# 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
+
+      # 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.is_a?(String) ? value : value['$value']
+      end
+
+      def inspect
+        stringio = StringIO.new
+        PP.pp(self, stringio)
+        stringio.string.delete("\n")
+      end
+
+      def pretty_print(pp)
+        data = {
+          entity_type_name: raw['EntityTypeName'],
+          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/panels/base_panel.rb

@@ -23,7 +23,7 @@ module Usps
         #
         # @param ordinal [Integer] The ordinal identifier for the desired object
         #
-        # @return [Hash, Array<Hash>] Response data from the API
+        # @return [Usps::Imis::Data, Array<Usps::Imis::Data>] Response data from the API
         #
         def get(ordinal, *fields) = api.on(business_object, ordinal:).get(*fields)
         alias read get
@@ -33,17 +33,18 @@ module Usps
         # @param ordinal [Integer] The ordinal identifier for the desired object
         # @param field [String] Field name to return
         #
-        # @return [Hash] Response data from the API
+        # @return Response data field value from the API
         #
         def get_field(ordinal, field) = api.on(business_object, ordinal:).get_field(field)
         alias fetch get_field
+        alias [] 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
+        # @return [Array] Response data from the API
         #
         def get_fields(ordinal, *fields) = api.on(business_object, ordinal:).get_fields(*fields)
         alias fetch_all get_fields
@@ -53,7 +54,7 @@ module Usps
         # @param ordinal [Integer] The ordinal identifier for the desired object
         # @param fields [Hash] Conforms to pattern +{ field_key => value }+
         #
-        # @return [Hash] Response data from the API
+        # @return [Usps::Imis::Data] Response data from the API
         #
         def put_fields(ordinal, fields) = api.on(business_object, ordinal:).put_fields(fields)
         alias patch put_fields
@@ -63,6 +64,8 @@ module Usps
         # @param data [Hash] The record data for the desired object -- including the required
         #                    +ordinal+ identifier
         #
+        # @return [Usps::Imis::Data] Response data from the API
+        #
         def put(data) = api.on(business_object, ordinal: data[:ordinal]).put(payload(data))
         alias update put
 
@@ -70,6 +73,8 @@ module Usps
         #
         # @param data [Hash] The record data for the desired object
         #
+        # @return [Usps::Imis::Data] Response data from the API
+        #
         def post(data) = api.on(business_object).post(payload(data))
         alias create post
 
@@ -77,6 +82,8 @@ module Usps
         #
         # @param ordinal [Integer] The ordinal identifier for the desired object
         #
+        # @return [true] Only on success response (i.e. blank string from the API)
+        #
         def delete(ordinal) = api.on(business_object, ordinal:).delete
         alias destroy delete
 
@@ -106,7 +113,7 @@ module Usps
             'EntityTypeName' => business_object,
             'IdentityElements' => {
               '$type' => identity_type,
-              '$values' => [api.imis_id, ordinal&.to_s].compact
+              '$values' => [api.imis_id.to_s, ordinal&.to_s].compact
             }
           }
         end
@@ -117,7 +124,7 @@ module Usps
             'EntityTypeName' => 'Party',
             'IdentityElements' => {
               '$type' => identity_type,
-              '$values' => [api.imis_id]
+              '$values' => [api.imis_id.to_s]
             }
           }
         end

data/lib/usps/imis/panels/education.rb

@@ -14,7 +14,7 @@ module Usps
 
         def payload(data)
           build_payload(data) do |props|
-            props.add 'ID', api.imis_id
+            props.add 'ID', api.imis_id.to_s
             props.add 'Ordinal', data[:ordinal] if data[:ordinal]
             props.add 'ABC_EDUC_THRU_DATE', data[:thru_date] || '0001-01-01T00:00:00'
             props.add 'ABC_ECertificate', data[:certificate]

data/lib/usps/imis/panels/vsc.rb

@@ -14,7 +14,7 @@ module Usps
 
         def payload(data)
           build_payload(data) do |props|
-            props.add 'ID', api.imis_id
+            props.add 'ID', api.imis_id.to_s
             props.add 'Ordinal', data[:ordinal] if data[:ordinal]
             props.add 'Source_System', 'Manual ITCom Entry'
             props.add 'ABC_ECertificate', data[:certificate]

data/lib/usps/imis/version.rb

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

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

@@ -17,13 +17,13 @@ describe Usps::Imis::Api do
     it 'stores the initial imis_id' do
       api = described_class.new(imis_id: 42)
 
-      expect(api.imis_id).to eq('42')
+      expect(api.imis_id).to eq(42)
     end
   end
 
   describe '#imis_id_for' do
     it 'gets the iMIS ID' do
-      expect(api.imis_id_for('E231625')).to eq('31092')
+      expect(api.imis_id_for('E231625')).to eq(31092)
     end
 
     context 'with a query error' do
@@ -133,7 +133,7 @@ describe Usps::Imis::Api do
       end
 
       expect(result).to be_a(Hash)
-      expect(api.imis_id).to eq('31092')
+      expect(api.imis_id).to eq(31092)
     end
 
     it 'nests on and with', :aggregate_failures do

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

@@ -7,15 +7,17 @@ describe Usps::Imis::BusinessObject do
   let(:api) { Usps::Imis::Api.new }
 
   before do
-    allow(business_object).to receive(:raw_object).and_return({
-      'Properties' => {
-        '$values' => [
-          { 'Name' => 'ID', 'Value' => { '$value' => '31092' } },
-          { 'Name' => 'Stub Integer', 'Value' => { '$value' => 42 } },
-          { 'Name' => 'Stub String', 'Value' => 'something' }
-        ]
-      }
-    })
+    allow(business_object).to receive(:raw_object).and_return(
+      Usps::Imis::Data[
+        'Properties' => {
+          '$values' => [
+            { 'Name' => 'ID', 'Value' => { '$value' => '31092' } },
+            { 'Name' => 'Stub Integer', 'Value' => { '$value' => 42 } },
+            { 'Name' => 'Stub String', 'Value' => 'something' }
+          ]
+        }
+      ]
+    )
   end
 
   describe '#get' do

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Usps::Imis::Data do
+  let(:data) do
+    described_class[
+      'EntityTypeName' => 'ABC_ASC_Individual_Demog',
+      'Properties' => {
+        '$values' => [
+          { 'Name' => 'ID', 'Value' => { '$value' => '31092' } },
+          { 'Name' => 'Stub Integer', 'Value' => { '$value' => 42 } },
+          { 'Name' => 'Stub String', 'Value' => 'something' }
+        ]
+      }
+    ]
+  end
+
+  describe 'missing property' do
+    it 'returns nil for missing properties' do
+      expect(data['Not Found']).to be_nil
+    end
+  end
+
+  describe '#inspect' do
+    it 'generates the correct inspect string' do
+      expect(data.inspect).to eq('#<Usps::Imis::Data entity_type_name="ABC_ASC_Individual_Demog" imis_id=31092>')
+    end
+
+    context 'with data from a Panel' do
+      let(:data) do
+        described_class[
+          'EntityTypeName' => 'ABC_ASC_Individual_Demog',
+          'Properties' => {
+            '$values' => [
+              { 'Name' => 'ID', 'Value' => { '$value' => '31092' } },
+              { 'Name' => 'Ordinal', 'Value' => { '$value' => '99' } },
+              { 'Name' => 'Stub Integer', 'Value' => { '$value' => 42 } },
+              { 'Name' => 'Stub String', 'Value' => 'something' }
+            ]
+          }
+        ]
+      end
+
+      it 'generates the correct inspect string with an ordinal' do
+        expect(data.inspect).to eq(
+          '#<Usps::Imis::Data entity_type_name="ABC_ASC_Individual_Demog" imis_id=31092 ordinal=99>'
+        )
+      end
+    end
+  end
+end

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

@@ -9,7 +9,7 @@ describe Usps::Imis::Mapper do
     it 'stores the initial imis_id' do
       mapper = described_class.new(imis_id: 42)
 
-      expect(mapper.api.imis_id).to eq('42')
+      expect(mapper.api.imis_id).to eq(42)
     end
   end
 

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

@@ -21,7 +21,7 @@ describe Usps::Imis::Panels::Education do
 
     describe '#get' do
       it 'loads a specific object' do
-        expect(education.get(90737)).to be_a(Hash)
+        expect(education.get(90737)).to be_a(Usps::Imis::Data)
       end
 
       it 'returns specific fields' do
@@ -44,22 +44,16 @@ describe Usps::Imis::Panels::Education do
     # rubocop:disable RSpec/ExampleLength
     it 'interacts with records correctly', :aggregate_failures do
       new_record = education.create(details)
-      expect(new_record).to be_a(Hash)
+      expect(new_record).to be_a(Usps::Imis::Data)
 
-      ordinal = new_record['Identity']['IdentityElements']['$values'][1]
+      ordinal = new_record.ordinal
 
       update_result =
         education.update(details.merge(source: 'Online Exams System - Modified', ordinal:))
-      updated = update_result['Properties']['$values'].find do |v|
-        v['Name'] == 'ABC_Educ_Source_System'
-      end
-      expect(updated['Value']).to eq('Online Exams System - Modified')
+      expect(update_result['ABC_Educ_Source_System']).to eq('Online Exams System - Modified')
 
       put_fields_result = education.put_fields(ordinal, 'ABC_Educ_Source_System' => 'Online Exams System - Mod2')
-      patched = put_fields_result['Properties']['$values'].find do |v|
-        v['Name'] == 'ABC_Educ_Source_System'
-      end
-      expect(patched['Value']).to eq('Online Exams System - Mod2')
+      expect(put_fields_result['ABC_Educ_Source_System']).to eq('Online Exams System - Mod2')
 
       expect(education.destroy(ordinal)).to be(true)
     end
@@ -70,7 +64,7 @@ describe Usps::Imis::Panels::Education do
     it 'can initialize with an iMIS ID' do
       panel = described_class.new(imis_id: 6374)
 
-      expect(panel.api.imis_id).to eq('6374')
+      expect(panel.api.imis_id).to eq(6374)
     end
   end
 end

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

@@ -17,20 +17,19 @@ describe Usps::Imis::Panels::Vsc do
 
   describe '#get' do
     it 'loads a specific object' do
-      expect(vsc.get(1433)).to be_a(Hash)
+      expect(vsc.get(1433)).to be_a(Usps::Imis::Data)
     end
   end
 
   # rubocop:disable RSpec/ExampleLength
   it 'handles new records correctly', :aggregate_failures do
     new_record = vsc.create(details)
-    expect(new_record).to be_a(Hash)
+    expect(new_record).to be_a(Usps::Imis::Data)
 
-    ordinal = new_record['Identity']['IdentityElements']['$values'][1]
+    ordinal = new_record.ordinal
 
     update_result = vsc.update(details.merge(count: 43, ordinal:))
-    updated = update_result['Properties']['$values'].find { it['Name'] == 'Quantity' }
-    expect(updated['Value']['$value']).to eq(43)
+    expect(update_result['Quantity']).to eq(43)
 
     expect(vsc.destroy(ordinal)).to be(true)
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: usps-imis-api
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.8.1
 platform: ruby
 authors:
 - Julian Fiander
@@ -45,6 +45,7 @@ files:
 - lib/usps/imis/api.rb
 - lib/usps/imis/business_object.rb
 - lib/usps/imis/config.rb
+- lib/usps/imis/data.rb
 - lib/usps/imis/error.rb
 - lib/usps/imis/errors/api_error.rb
 - lib/usps/imis/errors/config_error.rb
@@ -67,6 +68,7 @@ files:
 - spec/lib/usps/imis/api_spec.rb
 - spec/lib/usps/imis/business_object_spec.rb
 - spec/lib/usps/imis/config_spec.rb
+- spec/lib/usps/imis/data_spec.rb
 - spec/lib/usps/imis/error_spec.rb
 - spec/lib/usps/imis/errors/response_error_spec.rb
 - spec/lib/usps/imis/mapper_spec.rb