usps-imis-api 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca358fc80eed74b0335f6137f71e503fffbc84d6c396c8e1c23c90501eab5b36
-  data.tar.gz: 239111a5dfd7cb186fe358fc0227e3063744225cf619e12a91e994f639142e56
+  metadata.gz: 0e1d3316b4676bae03e67aa927632ec91801a6d703c55049c1b11013a20c3e08
+  data.tar.gz: 8199c664875cc57e995d73b3a96ce03cd9de2e5460e7a451553df3bb5ca3ff84
 SHA512:
-  metadata.gz: 2f31860395762aeead9f002f96867111758a8474ada928ba1369e3122b767f0b27052ed41157d8eac008fade27bdb779389cd65c74ad7cadbb87129ee9c238ff
-  data.tar.gz: 7c0f5eaae8592a93192e08ca4cf88e604629de246b8e2f9272880d19e39a218d01a027387720a6c289b7f4490bc6617b57c637ab00201868ecd36fd178748031
+  metadata.gz: 7015ffe22161d1645959004798ed1fde3e65a66db6695dac75ae84db13177a376a37b083f74abdd9092108ba33d9d0f09fcbaaaa845d861d50af237c77c819b2
+  data.tar.gz: 940e05eeeeea390c67e207f4ace40c6befed6dbe355efdc38e3fa6d270c35f6bf5c48c3093808c505c2b26e9f452000ecd384e250451bc8263cce84d43a78238

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    usps-imis-api (0.7.1)
+    usps-imis-api (0.8.0)
       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 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')
+vsc.get(1417)['Quantity']
+vsc.get[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] # 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/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
@@ -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']
+      alias id imis_id
+
+      # Access the Ordinal identifier property (if present)
+      #
+      def ordinal = self['Ordinal']
+
+      # 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
 

data/lib/usps/imis/version.rb

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

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/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

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.0
 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