usps-imis-api 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad19ed5d60abf0531fdc10f01113fada6a5bc9413574bda31783d41507000c87
-  data.tar.gz: 8d0fcf7a1881cfb262a248683346489be5e28f2d57ce8a18923210780fc9e847
+  metadata.gz: 596057339ef96ddfa1bc884107307bae2bedfa3ef28610f1293218362daa53ad
+  data.tar.gz: 304f7b47a0923b08646266b71365049074235d24983abaa78fac615f0b02e5cc
 SHA512:
-  metadata.gz: 8abd5d2a143699aa7f184def0c97358bbc475c2248a1f56c5f5104ff9b9e08f917dd1f285637109ed3e0026c91e049661bf77a73f40bc56082a1d286d180951b
-  data.tar.gz: 823f16f923c71f7f0822a0d48fbe84152ea0221a96ded092570ee5554242acf9b619688625708bd9af89117f3d081c26125c02b5b879378e971072c4770cac08
+  metadata.gz: ec4ec8cedb9966992b4e6d86b34e2a219c3f6cc28d4c01622d460e1f1f7c44fdfa8c6aa76f3aad1fb97b2e44f75366eb7060f9685b83c1bca21937c8b778414f
+  data.tar.gz: 412e3f664b0384330956c11eee3ce11f0c6bb77a3154d24fb4c671e34d919628fb58f7780a92b5a164cb987de8f43893308a7de9f892580a3f6478515d861b3b

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    usps-imis-api (0.1.2)
+    usps-imis-api (0.2.0)
 
 GEM
   remote: https://rubygems.org/

data/Readme.md

@@ -1,6 +1,6 @@
 # USPS iMIS API for Ruby
 
-![Gem Version](https://img.shields.io/gem/v/usps-imis-api)
+[![Gem Version](https://img.shields.io/gem/v/usps-imis-api)](https://rubygems.org/gems/usps-imis-api)
 
 ## Installation
 
@@ -112,7 +112,7 @@ Update only specific fields on a business object for the current member
 `fields` is a hash of shape: `{ field_name => new_value }`
 
 ```ruby
-api.put(business_object_name, fields)
+api.put_fields(business_object_name, fields)
 ```
 
 Run an IQA Query
@@ -129,13 +129,39 @@ For fields that have already been mapped between the ITCom database and iMIS, yo
 Mapper class to further simplify the update interface:
 
 ```ruby
-api.mapper.update(:mm, 15)
+api.mapper.update(mm: 15)
+```
+
+For simplicity, you can also call `update` on the `Api` class directly:
+
+```ruby
+api.update(mm: 15)
 ```
 
 If there is no known mapping for the requested field, the Mapper will give up, but will provide
 you with the standard API call syntax, and will suggest you inform ITCom leadership of the new
 mapping you need.
 
+### Panels
+
+For supported panels (usually, business objects with composite identity keys), you can interact
+with them in the same general way:
+
+```ruby
+vsc = Imis::Panel::Vsc.new
+
+vsc.api.imis_id = 6374
+
+vsc.get(1417)
+
+created = vsc.create(certificate: 'E136924', year: 2024, count: 42)
+ordinal = created['Properties']['$values'][1]['Value']['$value']
+
+vsc.update(certificate: 'E136924', year: 2024, count: 43, ordinal: ordinal)
+
+vsc.destroy(ordinal)
+```
+
 ### DSL Mode
 
 Instead of manually setting the current iMIS ID, then running individual queries, you can instead
@@ -144,9 +170,13 @@ previous value.
 
 ```ruby
 api.with(31092) do
-  # These two requests are identical:
+  # These three requests are identical:
+
   put('ABC_ASC_Individual_Demog', { 'TotMMS' => 15 })
-  mapper.update(:mm, 15)
+
+  mapper.update(mm: 15)
+
+  update(mm: 15)
 end
 ```
 

data/lib/imis/api.rb

@@ -39,8 +39,8 @@ module Imis
 
     # Get a business object for the current member
     #
-    def get(business_object_name)
-      uri = uri_for(business_object_name)
+    def get(business_object_name, url_id: nil)
+      uri = uri_for(business_object_name, url_id: url_id)
       request = Net::HTTP::Get.new(uri)
       result = submit(uri, authorize(request))
       JSON.parse(result.body)
@@ -50,15 +50,42 @@ module Imis
     #
     #   fields - hash of shape: { field_name => new_value }
     #
-    def put(business_object_name, fields)
-      uri = uri_for(business_object_name)
-      request = Net::HTTP::Put.new(uri)
+    def put_fields(business_object_name, fields, url_id: nil)
       updated = filter_fields(business_object_name, fields)
-      request.body = JSON.dump(updated)
+      put(business_object_name, updated, url_id: url_id)
+    end
+
+    # Update a business object for the current member
+    #
+    def put(business_object_name, body, url_id: nil)
+      uri = uri_for(business_object_name, url_id: url_id)
+      request = Net::HTTP::Put.new(uri)
+      request.body = JSON.dump(body)
       result = submit(uri, authorize(request))
       JSON.parse(result.body)
     end
 
+    # Create a business object for the current member
+    #
+    def post(business_object_name, body, url_id: nil)
+      uri = uri_for(business_object_name, url_id: url_id)
+      request = Net::HTTP::Post.new(uri)
+      request.body = JSON.dump(body)
+      result = submit(uri, authorize(request))
+      JSON.parse(result.body)
+    end
+
+    # Remove a business object for the current member
+    #
+    # Returns empty string on success
+    #
+    def delete(business_object_name, url_id: nil)
+      uri = uri_for(business_object_name, url_id: url_id)
+      request = Net::HTTP::Delete.new(uri)
+      result = submit(uri, authorize(request))
+      result.body
+    end
+
     # Run an IQA Query
     #
     #   query_name   - the full path of the query in IQA, e.g. `$/_ABC/Fiander/iMIS_ID`
@@ -77,6 +104,10 @@ module Imis
       @mapper ||= Mapper.new(self)
     end
 
+    def update(data)
+      mapper.update(data)
+    end
+
   private
 
     def client(uri)
@@ -101,8 +132,10 @@ module Imis
 
     # Construct a business object API endpoint address
     #
-    def uri_for(business_object_name)
-      URI(File.join(imis_hostname, "#{API_PATH}/#{business_object_name}/#{imis_id}"))
+    def uri_for(business_object_name, url_id: nil)
+      url_id ||= imis_id
+      url_id = CGI.escape(url_id)
+      URI(File.join(imis_hostname, "#{API_PATH}/#{business_object_name}/#{url_id}"))
     end
 
     def submit(uri, request)

data/lib/imis/mapper.rb

@@ -10,31 +10,46 @@ module Imis
 
     attr_reader :api
 
-    def initialize(api)
-      @api = api
+    def initialize(api = nil)
+      @api = api || Api.new
     end
 
-    # Update a member's data by a single field name
+    # Update a member's data on multiple affected business objects by arbitrary field names
     # Does not require knowing which business object / iMIS-specific field name to use
     #
     # Only available for previously-mapped fields
     #
-    def update(field_name, value)
+    #  `data` is a hash of shape { field_key => value }
+    #
+    def update(data)
+      updates = data.each_with_object({}) do |(field_key, value), hash|
+        map_update(field_key) do |business_object_name, field|
+          hash[business_object_name] ||= {}
+          hash[business_object_name][field] = value
+        end
+      end
+
+      updates.map do |business_object_name, field_updates|
+        api.put_fields(business_object_name, field_updates)
+      end
+    end
+
+  private
+
+    def map_update(field_name)
       if FIELD_MAPPING.key?(field_name.to_sym)
         business_object_name, field = FIELD_MAPPING[field_name.to_sym]
-        api.put(business_object_name, { field => value })
+        yield(business_object_name, field)
       else
         missing_mapping(field_name)
       end
     end
 
-  private
-
     def missing_mapping(field_name)
       unless ENV['TESTING']
         warn(
           "Mapper does not know how to handle field \"#{field_name}\".\n\n" \
-          'You can use api.put(business_object_name, { field_name => value })  ' \
+          'You can use api.put_fields(business_object_name, { field_name => value })  ' \
           "if you know the business object and iMIS-specific field name.\n\n"
         )
       end

data/lib/imis/panel/vsc.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Imis
+  module Panel
+    class Vsc
+      BUSINESS_OBJECT = 'ABC_ASC_Vessel_Safety_Checks'
+
+      attr_reader :api
+
+      def initialize(api = nil)
+        @api = api || Api.new
+      end
+
+      def get(ordinal)
+        api.get(BUSINESS_OBJECT, url_id: "~#{api.imis_id}|#{ordinal}")
+      end
+
+      def create(data)
+        api.post(BUSINESS_OBJECT, payload(data), url_id: '')
+      end
+
+      def update(data)
+        api.put(BUSINESS_OBJECT, payload(data), url_id: "~#{api.imis_id}|#{data[:ordinal]}")
+      end
+
+      def destroy(ordinal)
+        api.delete(BUSINESS_OBJECT, url_id: "~#{api.imis_id}|#{ordinal}")
+      end
+
+    private
+
+      # rubocop:disable Metrics/MethodLength
+      def payload(data)
+        {
+          '$type' => 'Asi.Soa.Core.DataContracts.GenericEntityData, Asi.Contracts',
+          'EntityTypeName' => 'ABC_ASC_Vessel_Safety_Checks',
+          'PrimaryParentEntityTypeName' => 'Party',
+          'Identity' => {
+            '$type' => 'Asi.Soa.Core.DataContracts.IdentityData, Asi.Contracts',
+            'EntityTypeName' => 'ABC_ASC_Vessel_Safety_Checks',
+            'IdentityElements' => {
+              '$type' =>
+                'System.Collections.ObjectModel.Collection`1[[System.String, mscorlib]], mscorlib',
+              '$values' => [api.imis_id]
+            }
+          },
+          'PrimaryParentIdentity' => {
+            '$type' => 'Asi.Soa.Core.DataContracts.IdentityData, Asi.Contracts',
+            'EntityTypeName' => 'Party',
+            'IdentityElements' => {
+              '$type' =>
+                'System.Collections.ObjectModel.Collection`1[[System.String, mscorlib]], mscorlib',
+              '$values' => [api.imis_id]
+            }
+          },
+          'Properties' => {
+            '$type' => 'Asi.Soa.Core.DataContracts.GenericPropertyDataCollection, Asi.Contracts',
+            '$values' => [
+              {
+                '$type' => 'Asi.Soa.Core.DataContracts.GenericPropertyData, Asi.Contracts',
+                'Name' => 'ID',
+                'Value' => api.imis_id
+              },
+              (
+                if data[:ordinal]
+                  {
+                    '$type' => 'Asi.Soa.Core.DataContracts.GenericPropertyData, Asi.Contracts',
+                    'Name' => 'Ordinal',
+                    'Value' => {
+                      '$type' => 'System.Int32',
+                      '$value' => data[:ordinal]
+                    }
+                  }
+                end
+              ),
+              {
+                '$type' => 'Asi.Soa.Core.DataContracts.GenericPropertyData, Asi.Contracts',
+                'Name' => 'Source_System',
+                'Value' => 'Manual ITCom Entry'
+              },
+              {
+                '$type' => 'Asi.Soa.Core.DataContracts.GenericPropertyData, Asi.Contracts',
+                'Name' => 'ABC_ECertificate',
+                'Value' => data[:certificate]
+              },
+              {
+                '$type' => 'Asi.Soa.Core.DataContracts.GenericPropertyData, Asi.Contracts',
+                'Name' => 'Activity_Type',
+                'Value' => 'VSC'
+              },
+              {
+                '$type' => 'Asi.Soa.Core.DataContracts.GenericPropertyData, Asi.Contracts',
+                'Name' => 'Description',
+                'Value' => 'Vessel Safety Checks'
+              },
+              {
+                '$type' => 'Asi.Soa.Core.DataContracts.GenericPropertyData, Asi.Contracts',
+                'Name' => 'Effective_Date',
+                'Value' => "#{data[:year]}-12-01T00:00:00"
+              },
+              {
+                '$type' => 'Asi.Soa.Core.DataContracts.GenericPropertyData, Asi.Contracts',
+                'Name' => 'Quantity',
+                'Value' => {
+                  '$type' => 'System.Int32',
+                  '$value' => data[:count]
+                }
+              },
+              {
+                '$type' => 'Asi.Soa.Core.DataContracts.GenericPropertyData, Asi.Contracts',
+                'Name' => 'Thru_Date',
+                'Value' => "#{data[:year]}-12-31T00:00:00"
+              },
+              {
+                '$type' => 'Asi.Soa.Core.DataContracts.GenericPropertyData, Asi.Contracts',
+                'Name' => 'Transaction_Date',
+                'Value' => Time.now.strftime('%Y-%m-%dT%H:%M:%S')
+              }
+            ].compact
+          }
+        }
+      end
+      # rubocop:enable Metrics/MethodLength
+    end
+  end
+end

data/lib/usps-imis-api.rb

@@ -15,6 +15,7 @@ require 'imis/error/api'
 require 'imis/error/mapper'
 require 'imis/api'
 require 'imis/mapper'
+require 'imis/panel/vsc'
 
 module Imis
   class << self

data/spec/lib/imis/api_spec.rb

@@ -15,13 +15,19 @@ describe Imis::Api do
     before { api.imis_id = 31092 }
 
     it 'sends an update' do
-      expect(api.put('ABC_ASC_Individual_Demog', { 'TotMMS' => 15 })).to be_a(Hash)
+      expect(api.put_fields('ABC_ASC_Individual_Demog', { 'TotMMS' => 15 })).to be_a(Hash)
     end
   end
 
   describe '#with' do
-    it 'sends an update' do
-      expect(api.with(31092) { put('ABC_ASC_Individual_Demog', { 'TotMMS' => 15 }) }).to be_a(Hash)
+    it 'sends an update from put' do
+      expect(
+        api.with(31092) { put_fields('ABC_ASC_Individual_Demog', { 'TotMMS' => 15 }) }
+      ).to be_a(Hash)
+    end
+
+    it 'sends an update from update' do
+      expect(api.with(31092) { update(mm: 15) }.first).to be_a(Hash)
     end
   end
 end

data/spec/lib/imis/mapper_spec.rb

@@ -9,11 +9,11 @@ describe Imis::Mapper do
     before { api.imis_id = 31092 }
 
     it 'sends a mapped update' do
-      expect(api.mapper.update(:mm, 15)).to be_a(Hash)
+      expect(api.mapper.update(mm: 15).first).to be_a(Hash)
     end
 
     it 'raises for unmapped updates' do
-      expect { api.mapper.update(:something, 'anything') }.to raise_error(
+      expect { api.mapper.update(something: 'anything') }.to raise_error(
         Imis::Error::Mapper,
         'Unrecognized field: "something". ' \
         'Please report what data you are attempting to work with to ITCom leadership.'

data/spec/lib/imis/panel/vsc_spec.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Imis::Panel::Vsc do
+  let(:vsc) { described_class.new }
+
+  let(:details) do
+    {
+      certificate: 'E136924',
+      year: 2024,
+      count: 42
+    }
+  end
+
+  before { vsc.api.imis_id = 6374 }
+
+  describe '#get' do
+    it 'loads a specific object' do
+      expect(vsc.get(1433)).to be_a(Hash)
+    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)
+
+    ordinal = new_record['Properties']['$values'][1]['Value']['$value']
+
+    update_result = vsc.update(details.merge(count: 43, ordinal: ordinal))
+    updated = update_result['Properties']['$values'].find { |v| v['Name'] == 'Quantity' }
+    expect(updated['Value']['$value']).to eq(43)
+
+    expect(vsc.destroy(ordinal)).to eq('')
+  end
+  # rubocop:enable RSpec/ExampleLength
+end

data/usps-imis-api.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |s|
   s.name          = 'usps-imis-api'
-  s.version       = '0.1.2'
+  s.version       = '0.2.0'
   s.summary       = 'iMIS API Wrapper'
   s.description   = 'A wrapper for the iMIS API.'
   s.homepage      = 'http://rubygems.org/gems/usps-imis-api'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: usps-imis-api
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Julian Fiander
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-13 00:00:00.000000000 Z
+date: 2024-10-30 00:00:00.000000000 Z
 dependencies: []
 description: A wrapper for the iMIS API.
 email: jsfiander@gmail.com
@@ -30,9 +30,11 @@ files:
 - lib/imis/error/api.rb
 - lib/imis/error/mapper.rb
 - lib/imis/mapper.rb
+- lib/imis/panel/vsc.rb
 - lib/usps-imis-api.rb
 - spec/lib/imis/api_spec.rb
 - spec/lib/imis/mapper_spec.rb
+- spec/lib/imis/panel/vsc_spec.rb
 - spec/spec_helper.rb
 - usps-imis-api.gemspec
 homepage: http://rubygems.org/gems/usps-imis-api