usps-imis-api 0.14.1 → 1.0.0.pre.rc.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92f296666b675bed596644db341453658848f8ff2fff5484a44092627f32e0bf
-  data.tar.gz: 369f09117790760fed0f5c9166753626a0ef3e02a75525cdd6346df5779e782c
+  metadata.gz: 591c0f59f5d39e06c011116940615588936cef78dfb8e497670909d5654c61b8
+  data.tar.gz: 2f667e0e06d05a519bff31e6387452dc896aa4204443ceb3ae43d1dab8f2eaf0
 SHA512:
-  metadata.gz: 89af34efab0e554f3a4c0091ffca5bdf6b972fdd13b8e1b62e73e894a0fe83adba858a4a4bf2b25756f4d4c5e7fa909ef8601b53f0976163c1179a1873ed22b6
-  data.tar.gz: 56c89598f8a3b53fbbc697b96855c45af807318a80f180727e7354e3c4de246903ebd03a87da9c6ca2624fdbcd7d244901c03a739000cd37f7d062b41d6cfc0a
+  metadata.gz: 622f9629c46f876901542639099e7544d28d932121e7a9bd09513fcdb0c756e2727f6b69aad8ead5606dd36803a80d9f66f2e2c5e4e6cc08fe7133fc799023de
+  data.tar.gz: 07ffc1e12820b524083e68d054e23eb976fcd7a16cf48fdbf7d64fe25a5d75b4083e2e6aafd7e6a19671ecaa9a7e2b33240a7bd4aa6d487f4f83fb14316c5aae

data/.github/workflows/main.yml

@@ -0,0 +1,57 @@
+name: 'USPS iMIS API - Ruby'
+on:
+  push:
+    paths:
+      - '**.rb'
+      - '**.yml'
+      - '**.json'
+      - 'Gemfile'
+      - '.simplecov'
+    branches:
+      - 'main'
+      - '**'
+  workflow_dispatch:
+
+jobs:
+  rubocop:
+    runs-on: ubuntu-24.04
+    environment: "USPS iMIS API - Ruby"
+    strategy:
+      matrix:
+        ruby: ['3.4', head]
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: Run Rubocop
+        run: bundle exec rubocop
+  rspec:
+    runs-on: ubuntu-24.04
+    environment: "USPS iMIS API - Ruby"
+    strategy:
+      matrix:
+        ruby: ['3.4', head]
+    env:
+      IMIS_USERNAME: ${{ secrets.IMIS_USERNAME }}
+      IMIS_PASSWORD: ${{ secrets.IMIS_PASSWORD }}
+      IMIS_ID_QUERY_NAME: ${{ secrets.IMIS_ID_QUERY_NAME }}
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: Run Rspec
+        run: bundle exec rspec --format documentation --order rand --color --tty
+      - name: Store Coverage
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-rspec-${{ matrix.ruby }}
+          include-hidden-files: true
+          path: coverage/

data/.gitignore

@@ -0,0 +1,4 @@
+coverage/
+tmp/
+.env
+*.gem

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--order rand

data/.rubocop.yml

@@ -0,0 +1,88 @@
+require:
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.4
+  Exclude:
+    - bin/**/*
+    - config/**/*
+    - db/**/*
+    - vendor/**/*
+    - tmp/**/*
+  NewCops: enable
+  SuggestExtensions: false
+
+Layout/FirstHashElementIndentation:
+  EnforcedStyle: consistent
+Layout/AccessModifierIndentation:
+  EnforcedStyle: outdent
+Layout/EmptyLinesAroundAccessModifier:
+  Enabled: true
+Layout/ArrayAlignment:
+  Enabled: true
+Layout/HashAlignment:
+  Enabled: true
+Layout/EmptyLineAfterGuardClause:
+  Enabled: true
+Layout/SpaceInsideBlockBraces:
+  EnforcedStyle: space
+  EnforcedStyleForEmptyBraces: no_space
+Layout/SpaceInsideHashLiteralBraces:
+  EnforcedStyle: space
+  EnforcedStyleForEmptyBraces: no_space
+Layout/SpaceInsideArrayLiteralBrackets:
+  EnforcedStyle: no_space
+Layout/LineLength:
+  Max: 100
+
+Lint/UnusedMethodArgument:
+  Enabled: true
+Lint/UselessAssignment:
+  Enabled: true
+
+Metrics/MethodLength:
+  Enabled: true
+  Max: 15
+Metrics/ClassLength:
+  Enabled: true
+  Max: 150
+Metrics/ModuleLength:
+  Max: 150
+Metrics/ParameterLists:
+  Enabled: true
+Metrics/CyclomaticComplexity:
+  Enabled: true
+Metrics/AbcSize:
+  Enabled: true
+  Max: 30
+
+Naming/MemoizedInstanceVariableName:
+  Enabled: false
+Naming/MethodParameterName:
+  Enabled: false
+Naming/FileName:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+Style/FrozenStringLiteralComment:
+  Enabled: true
+Style/NumericLiterals:
+  Enabled: false
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+Style/AndOr:
+  Enabled: true
+Style/ClassCheck:
+  Enabled: true
+Style/GuardClause:
+  Enabled: true
+Style/OptionalBooleanParameter:
+  Enabled: false
+
+Security/Eval:
+  Enabled: true
+Security/JSONLoad:
+  Enabled: true
+Security/YAMLLoad:
+  Enabled: true

data/.ruby-version

@@ -0,0 +1 @@
+3.5-dev

data/.simplecov

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+SimpleCov.start do
+  enable_coverage :branch
+  primary_coverage :branch
+
+  add_filter '/spec'
+end

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec
+
+gem 'dotenv',        '>= 3.1.4'
+gem 'irb',           '>= 1.15.2'
+gem 'rake',          '>= 13.2.1'
+gem 'rspec',         '>= 3.13.0'
+gem 'rubocop',       '>= 1.66.1'
+gem 'rubocop-rspec', '>= 3.1.0'
+gem 'simplecov',     '>= 0.22.0'

data/Gemfile.lock

@@ -0,0 +1,95 @@
+PATH
+  remote: .
+  specs:
+    usps-imis-api (1.0.0.pre.rc.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    date (3.4.1)
+    diff-lcs (1.5.1)
+    docile (1.4.1)
+    dotenv (3.1.4)
+    erb (5.0.3)
+    io-console (0.8.1)
+    irb (1.15.2)
+      pp (>= 0.6.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.7.2)
+    language_server-protocol (3.17.0.3)
+    parallel (1.26.3)
+    parser (3.3.5.0)
+      ast (~> 2.4.1)
+      racc
+    pp (0.6.3)
+      prettyprint
+    prettyprint (0.2.0)
+    psych (5.2.6)
+      date
+      stringio
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.2.1)
+    rdoc (6.15.0)
+      erb
+      psych (>= 4.0.0)
+      tsort
+    regexp_parser (2.9.2)
+    reline (0.6.2)
+      io-console (~> 0.5)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.1)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.1)
+    rubocop (1.66.1)
+      json (~> 2.3)
+      language_server-protocol (>= 3.17.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.4, < 3.0)
+      rubocop-ast (>= 1.32.2, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.32.3)
+      parser (>= 3.3.1.0)
+    rubocop-rspec (3.1.0)
+      rubocop (~> 1.61)
+    ruby-progressbar (1.13.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.1)
+    simplecov_json_formatter (0.1.4)
+    stringio (3.1.7)
+    tsort (0.2.0)
+    unicode-display_width (2.6.0)
+
+PLATFORMS
+  arm64-darwin-23
+  ruby
+
+DEPENDENCIES
+  dotenv (>= 3.1.4)
+  irb (>= 1.15.2)
+  rake (>= 13.2.1)
+  rspec (>= 3.13.0)
+  rubocop (>= 1.66.1)
+  rubocop-rspec (>= 3.1.0)
+  simplecov (>= 0.22.0)
+  usps-imis-api!
+
+BUNDLED WITH
+   2.5.6

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/Readme.md

@@ -1,20 +1,19 @@
 # USPS iMIS API for Ruby
 
-[![Gem Version][gem-badge]](https://rubygems.org/gems/usps-imis-api)
-[![iMIS API PHP Wrapper Version][php-badge]](https://github.com/unitedstatespowersquadrons/imis-api-php)
+[![Gem Version](https://img.shields.io/gem/v/usps-imis-api)](https://rubygems.org/gems/usps-imis-api)
 
 ## Installation
 
 Run this command:
 
-```sh
+```ruby
 gem install usps-imis-api
 ```
 
 or add this line to your Gemfile:
 
 ```ruby
-gem 'usps-imis-api'
+gem 'usps-imis-api', '>= 0.4.0'
 ```
 
 ## Setup
@@ -26,27 +25,205 @@ require 'dotenv/load' # Optionally load environment variables from `.env` file
 require 'usps/imis'
 
 Usps::Imis.configure do |config|
-  # This will default to `Rails.env` if available.
-  config.environment = :development
+  config.environment = :development # Rails.env
+  config.imis_id_query_name = ENV['IMIS_ID_QUERY_NAME']
 
-  # These options will default to the listed `ENV` variable if available.
   config.username = ENV['IMIS_USERNAME']
   config.password = ENV['IMIS_PASSWORD']
-
-  # These options will use these defaults
-  config.logger = ActiveSupport::TaggedLogging.new(Logger.new($stdout))
-  config.logger.level = :info
-  config.global_log_path = '/var/log/imis/imis.log'
 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
 
-For more details and examples, refer to the [Wiki](https://github.com/unitedstatespowersquadrons/imis-api-ruby/wiki).
+### 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
+```
+
+### GET
+
+To fetch member data, run e.g.:
+
+```ruby
+api.imis_id = 31092
+
+data = api.get('ABC_ASC_Individual_Demog')
+```
+
+### PUT Fields
+
+To update member data, run e.g.:
+
+```ruby
+api.imis_id = 31092
+
+data = { 'MMS_Updated' => Time.now.strftime('%Y-%m-%dT%H:%M:%S'), 'TotMMS' => new_total }
+update = api.put_fields('ABC_ASC_Individual_Demog', 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.
+
+### PUT
+
+To update member data, run e.g.:
+
+```ruby
+api.imis_id = 31092
+
+update = api.put('ABC_ASC_Individual_Demog', complete_imis_object)
+```
+
+This method requires a complete iMIS data structure.
+
+### POST
+
+To create new member data, run e.g.:
+
+```ruby
+created = api.post('ABC_ASC_Individual_Demog', complete_imis_object)
+```
+
+This method requires a complete iMIS data structure.
+
+### DELETE
+
+To remove member data, run e.g.:
+
+```ruby
+api.imis_id = 31092
+
+api.delete('ABC_ASC_Individual_Demog')
+```
+
+This returns a blank string on success.
+
+### QUERY
+
+Run an IQA Query
+
+`query_params` is a hash of shape: `{ param_name => param_value }`
+
+```ruby
+api.query(query_name, query_params)
+```
+
+### 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 update interface:
+
+```ruby
+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 = Usps::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)
+```
+
+If you already have an iMIS ID to work with, you can pass that in immediately:
+
+```ruby
+vsc = Usps::Imis::Panel::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 three requests are identical:
+
+  put('ABC_ASC_Individual_Demog', { 'TotMMS' => 15 })
+
+  mapper.update(mm: 15)
+
+  update(mm: 15)
+end
+```
+
+```ruby
+api.with(6374) do
+  panels.vsc.get(1417)
+end
+```
 
 ## Exception Handling
 
-All internal exceptions inherit from `Usps::Imis::Error`.
+Exception and error response handling will be added later.
+
+To print exception information to STDERR when raising, set the environment
+variable `IMIS_ERROR_LOG_TO_STDERR=true`.
 
 ## Automated Testing and Linting
 
@@ -56,16 +233,12 @@ Testing is available by running:
 bundle exec rspec
 ```
 
-API web requests are sanitized and recorded using VCR.
-
 Linting is available by running:
 
 ```ruby
 bundle exec rubocop
 ```
 
-100% branch coverage is enforced on the test suite.
-
 ### GitHub Actions
 
 Testing and linting are automatically run on every push.
@@ -83,10 +256,5 @@ file to [rubygems.org](https://rubygems.org).
 
 ## PHP
 
-A wrapper for the CLI from this API is [available for PHP][php-repo].
-
-You can also view the (***deprecated***) [original PHP API](https://github.com/unitedstatespowersquadrons/imis-api).
-
-[gem-badge]: https://img.shields.io/gem/v/usps-imis-api?logo=rubygems&logoColor=white
-[php-badge]: https://img.shields.io/endpoint?url=https%3A%2F%2Fadmin.aws.usps.org%2Flibrary_badge%2Fimis-api-php&label=wrapper&logo=php&logoColor=white
-[php-repo]: https://github.com/unitedstatespowersquadrons/imis-api-php
+This same API is
+[available for PHP](https://github.com/unitedstatespowersquadrons/imis-api).

data/bin/console

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'usps/imis'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# Configure from the environment automatically
+require 'dotenv/load'
+Usps::Imis.configure do |config|
+  config.environment = :development
+  config.imis_id_query_name = ENV['IMIS_ID_QUERY_NAME']
+
+  config.username = ENV['IMIS_USERNAME']
+  config.password = ENV['IMIS_PASSWORD']
+end
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/ext/hash.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Import a simplified version of to_query from Rails if not already defined
+class Hash
+  def to_query
+    map do |key, value|
+      "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"
+    end.sort * '&'
+  end
+end