usps-imis-api 0.10.3 → 0.10.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a699891bdb0679741aafb3754e7939bfcd7f854b51e6cab76c25f6d9fc69995
-  data.tar.gz: 97ff09a0b7d9c1981b9170c96e3885e57f82465e08fa8a8be4c1b20cf7c8f822
+  metadata.gz: b058c2109e980f6706a58b10847ec6d68c943b44c6de7d5c6dbf44d00b5095e9
+  data.tar.gz: 4b49c8c39e215e09add71b36d68e86a3a3b6b6f10f999010c9d858787feaa1cc
 SHA512:
-  metadata.gz: 49f73bb0e65581cb15cb8004170ed22963e025693e8fb62f33a09b6c2afa5ca548a9a37354867679a9562205ff752a18b812bcca085b1b575c3c5bc48ec45564
-  data.tar.gz: 5f455a1a8a0231e08d6b83297ebcfcfea0c423dc6396ae4e1ec312d6da52e111b6a25babc978f232631242ac86da14499cfc2d6ac246c90779e41be6049b3fb7
+  metadata.gz: e646b741b55e2f25395004da9ca74c3bed8a44d7a645e8a0434ec74d38315f0d9e91bbfd17c53111069627ef0ff946eb5f0075df35d375e69cc9ebdc3edfcc7e
+  data.tar.gz: 42650930b35cdef5a05bc361796d2665ff16ca50a005a268551220d2ba6dd2983d451dfa3dd3ebb00886229224078a6ba44eeabf27aad03e5a32d52e4e8ea417

data/Readme.md

@@ -39,380 +39,9 @@ Usps::Imis.configure do |config|
 end
 ```
 
-When using `bin/console`, this configuration will be run by default.
-
-Instantiate the API object:
-
-```ruby
-api = Usps::Imis::Api.new
-```
-
-If you already have an iMIS ID to work with, you can pass that in immediately:
-
-```ruby
-api = Usps::Imis::Api.new(imis_id: imis_id)
-```
-
-### Authentication
-
-If a token is not available, this will automatically fetch one when needed. As long as that token
-should still be valid, it will reuse the same token. If the token should expire, this will
-automatically request a new token.
-
 ## Usage
 
-### iMIS ID
-
-To act on member data, you need to have the iMIS ID. If you already have access to that from the
-database, you can skip this step.
-
-To convert a member's certificate number into their iMIS ID, run the following method:
-
-```ruby
-api.imis_id_for(certificate)
-```
-
-This will both return the ID, and store it for use with other requests. If you need to change which
-member you are working with, just run this method again with the new certificate number.
-
-You can also manually set the current ID, if you already have it for a given member
-
-```ruby
-api.imis_id = imis_id
-```
-
-#### Without an iMIS ID
-
-Running requests without an iMIS ID set will raise an exception.
-
-If you want to query the entire Business Object, use the query interface instead:
-
-```ruby
-api = Usps::Imis::Api.new # No iMIS ID set
-
-# These requests are identical:
-
-Usps::Imis::Query.new(api, 'ABC_ASC_Individual_Demog')
-
-api.on('ABC_ASC_Individual_Demog').query
-
-api.query('ABC_ASC_Individual_Demog')
-```
-
-### Business Object and Panel Actions
-
-Business Objects and Panels support the following actions.
-
-Panels require passing in the ordinal identifier as an argument, except for `POST`.
-
-#### GET
-
-To fetch member data, run e.g.:
-
-```ruby
-data = api.on('ABC_ASC_Individual_Demog').get
-```
-
-You can also pass in specific field names to filter the returned member data, e.g.:
-
-```ruby
-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
-
-To fetch a specific field from member data, run e.g.:
-
-```ruby
-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
-
-To fetch multiple specific fields from member data, run e.g.:
-
-```ruby
-data = api.on('ABC_ASC_Individual_Demog').get_fields('TotMMS', 'MMS_Updated')
-```
-
-Alias: `fetch_all`
-
-#### PUT Fields
-
-To update member data, run e.g.:
-
-```ruby
-data = { 'MMS_Updated' => Time.now.strftime('%Y-%m-%dT%H:%M:%S'), 'TotMMS' => new_total }
-update = api.on('ABC_ASC_Individual_Demog').put_fields(data)
-```
-
-This method fetches the current data structure, and filters it down to just what you want to
-update, to reduce the likelihood of update collisions or type validation failures.
-
-Alias: `patch`
-
-#### PUT
-
-To update member data, run e.g.:
-
-```ruby
-update = api.on('ABC_ASC_Individual_Demog').put(complete_imis_object)
-```
-
-This method requires a complete iMIS data structure. However, any properties not included will be
-left unmodified (meaning this also effectively handles `PATCH`, though iMIS does not accept that
-HTTP verb).
-
-Alias: `update`
-
-#### POST
-
-To create new member data, run e.g.:
-
-```ruby
-created = api.on('ABC_ASC_Individual_Demog').post(complete_imis_object)
-```
-
-This method requires a complete iMIS data structure.
-
-Alias: `create`
-
-#### DELETE
-
-To remove member data, run e.g.:
-
-```ruby
-api.on('ABC_ASC_Individual_Demog').delete
-```
-
-Alias: `destroy`
-
-### QUERY
-
-Run an IQA Query
-
-`query_params` is a hash of shape: `{ param_name => param_value }`
-
-```ruby
-query = api.query(query_name, query_params)
-
-query.each do |item|
-  # Download all pages of the query, then iterate on the results
-end
-
-query.find_each do |item|
-  # Iterate one page at a time, fetching new pages automatically
-end
-```
-
-### Field Mapper
-
-For fields that have already been mapped between the ITCom database and iMIS, you can use the
-Mapper class to further simplify the `fetch` / `update` interfaces:
-
-```ruby
-mm = api.mapper.fetch(:mm)
-mm = api.mapper[:mm]
-```
-
-```ruby
-api.mapper.update(mm: 15)
-```
-
-For simplicity, you can also call `fetch` (or simply use Hash access syntax) and `update` on the
-`Api` class directly:
-
-```ruby
-api.fetch(:mm)
-api[:mm]
-```
-
-```ruby
-api.update(mm: 15)
-api[: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 = 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)
-
-# 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)
-
-vsc.put_fields(ordinal, 'Quantity' => 44)
-vsc[ordinal, 'Quantity'] = 44
-
-vsc.destroy(ordinal)
-```
-
-If you already have an iMIS ID to work with, you can pass that in immediately:
-
-```ruby
-vsc = Usps::Imis::Panels::Vsc.new(imis_id: imis_id)
-```
-
-Panels are also accessible directly from the API object:
-
-```ruby
-api.panels.vsc.get(1417)
-```
-
-### DSL Mode
-
-Instead of manually setting the current iMIS ID, then running individual queries, you can instead
-run queries in DSL mode. This specifies the iMIS ID for the scope of the block, then reverts to the
-previous value.
-
-```ruby
-api.with(31092) do
-  # These requests are identical:
-
-  on('ABC_ASC_Individual_Demog') { put_fields('TotMMS' => 15) }
-
-  on('ABC_ASC_Individual_Demog').put_fields('TotMMS' => 15)
-
-  mapper.update(mm: 15)
-
-  update(mm: 15)
-
-  mapper[:mm] = 15
-end
-
-# This request fetches the same data, but leaves the iMIS ID selected
-api.with(31092)[:mm] = 15
-```
-
-```ruby
-api.with(6374) do
-  panels.vsc.get(1417)
-end
-```
-
-```ruby
-api.with(31092) do
-  # These requests are identical:
-
-  on('ABC_ASC_Individual_Demog') do
-    get.raw['Properties']['$values'].find { it['Name'] == 'TotMMS' }['Value']['$value']
-
-    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
-
-# These requests fetch the same data, but leave the iMIS ID selected
-api.with(31092).on('ABC_ASC_Individual_Demog').get_field('TotMMS')
-api.with(31092).on('ABC_ASC_Individual_Demog')['TotMMS']
-```
-
-### Data Methods
-
-Data responses from the API can be handled as a standard Hash using the `raw` method.
-
-If you need to access all of the property values, you can use the `properties` method.
-By default, this will exclude the `ID` and `Ordinal` properties; they can be included with
-`properties(include_ids: true)`.
-
-## Test Data Mocking
-
-You can use the provided Business Object Mock to generate stub data for rspec:
-
-```ruby
-allow(api).to(
-  receive(:on).with('ABC_ASC_Individual_Demog').and_return(
-    Usps::Imis::Mocks::BusinessObject.new(TotMMS: 2)
-  )
-)
-```
-
-### VCR
-
-If you would like to use the included VCR config, make sure your Gemfile includes the required gems:
-
-```ruby
-gem 'cgi' # 2025-10-27 - Currently required for Ruby 3.5
-gem 'vcr'
-gem 'webmock'
-```
-
-In `spec_helper.rb`, add the following:
-
-```ruby
-require 'usps/vcr'
-Usps::Vcr::Config.configure!
-```
-
-You can also pass additional VCR config options through:
-
-```ruby
-Usps::Vcr::Config.configure! do |config|
-  config.ignore_localhost = true
-end
-```
-
-If you have any tests that are dependent on ordering to (re-)generate cassettes, a helper is also
-available to support adding example metadata, which will use a fixed order when the environment
-varialbe `VCR=all` is set:
-
-```ruby
-describe 'examples that care about order', order: Usps::Vcr::Config.vcr_record_ordered do
-  # ...
-end
-```
+For more details and examples, refer to the [Wiki](https://github.com/unitedstatespowersquadrons/imis-api-ruby/wiki).
 
 ## Exception Handling
 

data/lib/usps/imis/business_object.rb

@@ -39,6 +39,18 @@ module Usps
       #
       def query = api.query(business_object_name)
 
+      # Support passthrough for Api#with
+      #
+      def with(imis_id, &)
+        # Bring into local scope
+        wrapper_business_object_name = business_object_name
+        wrapper_ordinal = ordinal
+
+        api.with(imis_id) do
+          on(wrapper_business_object_name, ordinal: wrapper_ordinal, &)
+        end
+      end
+
       # Get a business object for the current member
       #
       # If +fields+ is provided, will return only those field values

data/lib/usps/imis/version.rb

@@ -2,6 +2,6 @@
 
 module Usps
   module Imis
-    VERSION = '0.10.3'
+    VERSION = '0.10.4'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: usps-imis-api
 version: !ruby/object:Gem::Version
-  version: 0.10.3
+  version: 0.10.4
 platform: ruby
 authors:
 - Julian Fiander