# USPS iMIS API for Ruby

[![Gem Version](https://img.shields.io/gem/v/usps-imis-api)](https://rubygems.org/gems/usps-imis-api)

## Installation

Run this command:

```ruby
gem install usps-imis-api
```

or add this line to your Gemfile:

```ruby
gem 'usps-imis-api', '>= 0.3.0'
```

## Setup

Include the library, and set the configuration:

```ruby
require 'dotenv/load' # Optionally load environment variables from `.env` file
require 'usps/imis'

Usps::Imis.configure do |config|
  config.environment = :development # Rails.env
  config.imis_id_query_name = ENV['IMIS_ID_QUERY_NAME']

  config.username = ENV['IMIS_USERNAME']
  config.password = ENV['IMIS_PASSWORD']
end
```

When using `bin/console`, this configuration will be run by default.

Instantiate the API object:

```ruby
api = Usps::Imis::Api.new
```

### 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.get_imis_id(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.

### General API Requests

#### GET

To fetch member data, run e.g.:

```ruby
api.imis_id = 31092

data = api.get('ABC_ASC_Individual_Demog')
```

#### PUT

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

### Public Methods

Convert a member's certificate number into an iMIS ID number

```ruby
api.get_imis_id(certificate)
```

Manually set the current ID, if you already have it for a given member

```ruby
api.imis_id = imis_id
```

GET a business object for the current member

```ruby
api.get(business_object_name)
```

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_fields(business_object_name, fields)
```

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)
```

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)

  panels.vsc.get(1417)
end
```

## Exception Handling

Exception and error response handling will be added later.

## Automated Testing and Linting

Testing is available by running:

```ruby
bundle exec rspec
```

Linting is available by running:

```ruby
bundle exec rubocop
```

### GitHub Actions

Testing and linting are automatically run on every push.

## Development

After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).

## PHP

This same API is
[available for PHP](https://github.com/unitedstatespowersquadrons/imis-api).