usps-imis-api 0.1.3 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a27bda1b2938e0cfedde1da424a7694a001c539deb705032c4e7aefe126361a
-  data.tar.gz: f2fccb24b0f76b452a6b7b3719e225f6659f53d8e6251be130d920bff1f299dd
+  metadata.gz: 3bb98ea050e0d9e6b21b9c67b3e1cc7f74020781556015cc4c03e6b748a8cf3d
+  data.tar.gz: 8e309c38ebb754244a278de5b4968a6bd917c78d43271a042b0ab5e81846ea10
 SHA512:
-  metadata.gz: 6a86560e9f859589317faf46dc524105d2b77b2e25d869c6eec604fa1f98592ed4bdf59a6675078e89345782ab45017fdf34f5895d99cf3944473fccf05e9faf
-  data.tar.gz: aea9d7c488dec4f017a3252d5294cc9f9fa03eed3e374bbd4d9cc0926c9e76b6c725df5a65ea6eca3314e483153e80be05002917fa49aab8993884fe4cfbd3fd
+  metadata.gz: b8ac2e1b390b4f1c6922eb2bd48202aff6015af2ebd9a577572e61d4c24d4219c89ee85bc0c76438fd0c97a020c10b60c021fe95a7819bc260a282d7c56a83b8
+  data.tar.gz: 35aa8c10cc792f75ef6df018264e1171077598a74076193ea083dfd7edb754ed76173531acff8904df00d70adad9506dc844bce4b94d68537e1eca821d7c784d

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    usps-imis-api (0.1.3)
+    usps-imis-api (0.2.1)
 
 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
 
@@ -13,7 +13,7 @@ gem install usps-imis-api
 or add this line to your Gemfile:
 
 ```ruby
-gem 'usps-imis-api', '>= 0.1.1'
+gem 'usps-imis-api', '>= 0.2.0'
 ```
 
 ## Setup
@@ -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
@@ -132,10 +132,36 @@ Mapper class to further simplify the update interface:
 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,15 @@ 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)
+
+  update(mm: 15)
+
+  panels.vsc.get(1417)
 end
 ```
 

data/lib/imis/api.rb

@@ -5,6 +5,7 @@ module Imis
     AUTHENTICATION_PATH = 'Token'
     API_PATH = 'api'
     QUERY_PATH = 'api/Query'
+    PANELS = Struct.new(:vsc)
 
     attr_reader :token, :token_expiration, :imis_id
 
@@ -39,8 +40,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 +51,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 +105,12 @@ module Imis
       @mapper ||= Mapper.new(self)
     end
 
+    def panels
+      @panels ||= PANELS.new(
+        Panel::Vsc.new(self)
+      )
+    end
+
     def update(data)
       mapper.update(data)
     end
@@ -105,8 +139,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,8 +10,8 @@ module Imis
 
     attr_reader :api
 
-    def initialize(api)
-      @api = api
+    def initialize(api = nil)
+      @api = api || Api.new
     end
 
     # Update a member's data on multiple affected business objects by arbitrary field names
@@ -30,7 +30,7 @@ module Imis
       end
 
       updates.map do |business_object_name, field_updates|
-        api.put(business_object_name, field_updates)
+        api.put_fields(business_object_name, field_updates)
       end
     end
 
@@ -49,7 +49,7 @@ module Imis
       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,17 +15,23 @@ 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 from put' do
-      expect(api.with(31092) { put('ABC_ASC_Individual_Demog', { 'TotMMS' => 15 }) }).to be_a(Hash)
+      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
+
+    it 'uses a panel correctly' do
+      expect(api.with(6374) { panels.vsc.get(1433) }).to be_a(Hash)
+    end
   end
 end

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.3'
+  s.version       = '0.2.1'
   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.3
+  version: 0.2.1
 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