agris 0.18.0 → 1.0.0

data/docs/RELEASING.md

@@ -0,0 +1,147 @@
+# Releasing agris
+
+The gem is published to [rubygems.org](https://rubygems.org/gems/agris) as `agris`.
+
+Releases are cut with `bundle exec rake release`, which tags, pushes and
+publishes in a single irreversible step. Read [What `rake release` actually
+does](#what-rake-release-actually-does) before running it.
+
+## Versioning
+
+**One version line, released from `master`.** The version number follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html) and describes the
+**API** — not which Ruby the gem supports.
+
+Ruby support is expressed in the gemspec instead:
+
+```ruby
+spec.required_ruby_version = '>= 3.1'
+```
+
+Bundler's resolver does the rest. An application on Ruby 3.1 resolves to the
+newest version whose floor it satisfies; one on 3.4 resolves to the newest
+version outright. There is no need for parallel release lines, and consumers do
+not need to pin a version to stay on a supported Ruby.
+
+> This replaced an earlier scheme that encoded the supported Ruby in the version
+> number (`0.19.x` for Ruby 3.1, `0.2x` for Ruby 3.3). It fought semver — the
+> version had to step *backwards* at one point — and RubyGems has no concept of
+> release lines anyway: it always serves the highest version as `latest`.
+
+### How Ruby changes map to versions
+
+| Change | Version impact |
+|--------|----------------|
+| **Adding** support for a newer Ruby (3.5, 4.x) | **None.** Add it to the CI matrix. Patch release only if fixes were needed. |
+| **Dropping** support for an older Ruby (raising `required_ruby_version`) | **Breaking** — major bump. |
+
+Everything else is ordinary semver on the public API.
+
+Raising the floor is breaking because applications that could install the gem
+yesterday cannot today. Do it deliberately, in its own release.
+
+### Keep the floor honest
+
+`.github/workflows/ci.yml` runs the suite across **floor, current and next** —
+currently 3.1, 3.3 and 3.4. If you change `required_ruby_version`, change the
+matrix in the same PR, or the declared floor becomes a claim nothing tests.
+
+Note that the matrix job names are required status checks on `master`
+(`test (3.1)`, `test (3.3)`, `test (3.4)`, `lint`). Changing the matrix changes
+those names, so branch protection must be updated to match — otherwise every
+PR blocks on a check that can never report.
+
+## Pre-release checklist
+
+1. **Be on `master`**, up to date, with everything merged that you intend to
+   ship. `rake release` tags and pushes whatever branch you are standing on —
+   it does not check.
+2. **Working tree is clean.** `rake release` aborts otherwise.
+3. **Full suite is green:**
+   ```sh
+   bundle exec rake        # specs + rubocop
+   ```
+4. **Version is bumped** in `lib/agris/version.rb`, and the bump is committed.
+5. **`required_ruby_version` is correct** for what you are shipping, and the CI
+   matrix covers it.
+6. **The tag does not already exist:**
+   ```sh
+   git tag --list 'v*' | sort -V | tail
+   ```
+7. **RubyGems credentials are present** — see [Credentials](#credentials).
+
+## Cutting the release
+
+```sh
+git checkout master
+git pull
+# bump lib/agris/version.rb, commit, and merge via PR
+bundle exec rake                 # confirm green
+bundle exec rake release
+```
+
+If your account has MFA enabled, `gem push` prompts for an OTP code partway
+through — do not walk away from the terminal.
+
+## What `rake release` actually does
+
+Provided by `bundler/gem_tasks`. In order:
+
+1. **Guards the working tree** — aborts with "There are files that need to be
+   committed first" if anything is modified or staged.
+2. **Checks whether `v<version>` is already tagged** — if so, skips tagging and
+   continues to publish anyway.
+3. **Creates the tag** — `git tag -m "Version <version>" v<version>`.
+4. **Builds the gem** into `pkg/agris-<version>.gem`.
+5. **Pushes to git** — the **current branch** and the new tag, to that branch's
+   configured remote (`origin` by default).
+6. **Publishes to rubygems.org** — `gem push pkg/agris-<version>.gem`.
+
+Steps 5 and 6 reach outside the repository. Step 6 is effectively permanent.
+
+If tagging succeeds but a later step fails, the tag is removed automatically.
+If the *push* succeeds and publishing fails, the tag is already public — delete
+it manually before retrying:
+
+```sh
+git tag -d v<version>
+git push origin :refs/tags/v<version>
+```
+
+## Credentials
+
+`gem push` reads `~/.gem/credentials`. If you have never pushed from this
+machine:
+
+```sh
+gem signin
+```
+
+The gemspec sets no `allowed_push_host`, so pushes go to rubygems.org. You must
+be an owner of the `agris` gem — check with `gem owner agris`.
+
+## After releasing
+
+```sh
+gem list agris --remote --all      # new version is listed
+git ls-remote --tags origin        # tag reached the remote
+```
+
+Confirm the published gem declares the Ruby floor you expect:
+
+```sh
+gem specification agris -r required_ruby_version
+```
+
+## If a release goes wrong
+
+A published version can be yanked, but the version number is **burned
+permanently** — it can never be reused:
+
+```sh
+gem yank agris -v <version>
+```
+
+Yanking removes it from resolution for new installs; it does not recall it from
+anyone who already has it. Prefer releasing a fixed higher version over yanking
+wherever possible.

data/docs/specs/README.md

@@ -0,0 +1,26 @@
+# Specs
+
+Source of truth for behavior in the `agris` gem. Implementation, tests, and PRs trace back to spec IDs (R#, E#, AC-#, AT#).
+
+## How to add a spec
+1. Copy `spec-template.md` into the appropriate area folder (see below).
+2. Name the file by feature, kebab-case (e.g., `import-grain-ticket.md`).
+3. Fill in Goal → Rules → Acceptance Criteria → Acceptance Tests.
+4. Reference spec IDs in commits, tests, and PR descriptions.
+
+## Layout
+
+Specs are grouped by Agris API area, mirroring `lib/agris/api/`:
+
+- `grain/` — tickets, contracts (purchase/sales), commodity codes, grade factors, rates
+- `inventory/` — delivery tickets, orders
+- `accounts-payables/` — voucher posting
+- `accounts-receivables/` — invoice posting
+- `messages/` — document-tracking and "changed since" queries
+- `support/` — support / utility messages
+
+Cross-cutting specs (config, transport, error model) can live at the top level of `docs/specs/`.
+
+## Templates
+- `spec-template.md` — blank template, copy this.
+- `rename-folder.example.md` — completed example showing the expected level of detail.

data/docs/specs/rename-folder.example.md

@@ -0,0 +1,82 @@
+# Spec: Rename Folder (Example)
+
+## Goal
+Allow a user to rename an existing folder.
+
+## Non Goals
+- Moving folders
+- Renaming multiple folders
+
+## Definitions
+- Folder: user-owned container for documents.
+
+## Interfaces
+Endpoint:
+`PATCH /folders/{id}`
+
+Input:
+```json
+{
+  "name": "string"
+}
+```
+
+Output:
+```json
+{
+  "id": "string",
+  "name": "string"
+}
+```
+
+## Rules
+R1: Folder name must be 1-80 characters.
+R2: Leading and trailing whitespace must be trimmed.
+R3: If name is unchanged, return success without modification.
+R4: User must have folder write permission.
+
+## State Model
+- Existing folder name -> renamed folder name (or unchanged for idempotent update).
+
+## Edge Cases
+E1: Folder does not exist -> return 404.
+E2: Invalid name -> return 422.
+E3: Unauthorized -> return 403.
+
+## Acceptance Criteria
+AC-1: User can rename an existing folder with a valid name (1-80 chars).
+AC-2: System trims whitespace and handles idempotent renames.
+AC-3: Unauthorized or invalid requests are rejected with appropriate status codes.
+
+## Acceptance Tests
+AT1
+Given a valid folder id
+When a valid name is submitted
+Then the folder name is updated.
+Covers: R1, R2
+
+AT2
+Given an unchanged folder name
+When request is submitted
+Then return success without modification.
+Covers: R3
+
+AT3
+Given a user without permission
+When request is submitted
+Then return 403.
+Covers: R4
+
+## Observability
+- Log validation failures with request id and rule ID.
+- Emit metric for rename success/failure counts.
+
+## Implementation Decisions
+
+| Date | Decision | Rationale |
+|------|----------|-----------|
+
+## Change Log
+
+| Date | Change | Affected IDs | Rationale |
+|------|--------|-------------|-----------|

data/docs/specs/spec-template.md

@@ -0,0 +1,68 @@
+<!-- See rename-folder.example.md for a completed example of this template -->
+
+# Spec: <Feature Name>
+
+## Goal
+Short description of the feature's purpose and value.
+
+## Non Goals
+Explicitly excluded behavior. List what this spec intentionally does NOT cover.
+
+## Definitions
+Key domain terms used in this spec. Define any term a new team member might misunderstand.
+
+## Interfaces
+Inputs, outputs, APIs, or UI events. Include request/response schemas where applicable.
+
+## Rules
+<!-- Rules describe system behavior at implementation level.
+     Each rule should be specific enough to test.
+     Bad: "User can log in."
+     Good: "POST /api/auth/login with valid credentials returns 200 and a session token (R1)." -->
+
+R1: <rule>
+R2: <rule>
+
+## State Model
+If the system has state transitions, describe them here. Otherwise remove this section.
+
+## Edge Cases
+E1: <edge case and expected behavior>
+E2: <edge case and expected behavior>
+
+## Acceptance Criteria
+<!-- ACs describe observable outcomes a stakeholder can verify.
+     Rules are implementation-facing; ACs are user-facing.
+     Example: "AC-1: User sees a green checkmark when password meets all strength requirements." -->
+
+AC-1: <criterion>
+AC-2: <criterion>
+
+## Acceptance Tests
+<!-- Each AT must have a Covers: field listing the R# or E# it validates.
+     An AT can cover multiple rules. -->
+
+AT1
+Given <context>
+When <action>
+Then <outcome>
+Covers: R1
+
+AT2
+Given <context>
+When <action>
+Then <outcome>
+Covers: R2
+
+## Observability
+Logs, metrics, alerts (optional).
+
+## Implementation Decisions
+
+| Date | Decision | Rationale |
+|------|----------|-----------|
+
+## Change Log
+
+| Date | Change | Affected IDs | Rationale |
+|------|--------|-------------|-----------|

data/lib/agris/api/accounts_payables/disbursements.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Agris
+  module Api
+    module AccountsPayables
+      module Disbursements
+        def create_disbursement(disbursement)
+          response = @request.process_message(
+            Gyoku.xml(xml: context_hash),
+            82_320,
+            create_post_payload_xml([disbursement.to_xml_hash])
+          )
+
+          PostResult.new(response)
+        end
+      end
+    end
+  end
+end

data/lib/agris/api/accounts_payables/new_disbursement.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Agris
+  module Api
+    module AccountsPayables
+      class NewDisbursement
+        include XmlModel
+
+        ATTRIBUTE_NAMES = %w(
+          applied_date
+          apply_payment_on_account
+          bank_code
+          cash_source
+          check_location
+          check_number
+          currency_code
+          discount_amount
+          exchange_rate
+          exchange_rate_date
+          misc_reference
+          name_id
+          payment_amount
+          payment_date
+          prepayment_reference
+          prepayment_type
+          record_type
+          reserved
+          voucher_location
+          voucher_number
+        ).freeze
+
+        attr_reader(*ATTRIBUTE_NAMES)
+
+        def initialize(hash = {})
+          super
+
+          @record_type = 'ACPD0'
+        end
+      end
+    end
+  end
+end

data/lib/agris/api/accounts_payables.rb

@@ -3,6 +3,9 @@
 module Agris
   module Api
     module AccountsPayables
+      autoload :Disbursements, 'agris/api/accounts_payables/disbursements'
+      autoload :NewDisbursement, 'agris/api/accounts_payables/new_disbursement'
+
       module Vouchers
         def create_voucher(voucher)
           response = @request.process_message(

data/lib/agris/api/accounts_receivables/invoices.rb

@@ -17,7 +17,7 @@ module Agris
           )
         end
 
-        def invoices_changed_since(datetime, detail = false)
+        def invoices_changed_since(datetime, detail: false)
           extract_documents(
             Messages::QueryChangedInvoices.new(datetime, detail),
             Agris::Api::AccountsReceivables::Invoice

data/lib/agris/api/accounts_receivables/new_payment.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Agris
+  module Api
+    module AccountsReceivables
+      class NewPayment
+        include XmlModel
+
+        RECEIVE_ON_ACCOUNT = '0'
+        APPLY_TO_INVOICE = 'E'
+
+        ATTRIBUTE_NAMES = %w(
+          applied_date
+          apply_receive_on_acct
+          bank_code
+          cash_source
+          check_number
+          discount_amount
+          invoice_line_pricing_no
+          invoice_location
+          name_id
+          payment_amount
+          payment_date
+          receipt_location
+          receipt_number
+          record_type
+        ).freeze
+
+        attr_reader(*ATTRIBUTE_NAMES)
+
+        # Agris allocates the receipt number, so it is left for the response.
+        # An applied date or invoice on an unapplied receipt is rejected.
+        def self.receive(attributes = {})
+          new(
+            attributes.merge(
+              apply_receive_on_acct: RECEIVE_ON_ACCOUNT,
+              applied_date: '',
+              invoice_line_pricing_no: ''
+            )
+          )
+        end
+
+        # Draws down the unapplied balance of a receipt Agris already
+        # allocated; it cannot create one.
+        def self.apply(attributes = {})
+          new(attributes.merge(apply_receive_on_acct: APPLY_TO_INVOICE))
+        end
+
+        def initialize(attributes = {})
+          super
+
+          @record_type = 'ACRR0'
+          @remarks = []
+        end
+
+        def add_remark(remark)
+          @remarks << remark
+
+          self
+        end
+
+        def remarks
+          @remarks || []
+        end
+
+        def records
+          [self] + remarks
+        end
+
+        def for_allocation(allocation)
+          allocated = self.class.new(hash.merge(allocation_hash(allocation)))
+
+          remarks.each do |remark|
+            allocated.add_remark(remark.for_allocation(allocation))
+          end
+
+          allocated
+        end
+
+        def xml_ignore_attributes
+          [:remarks]
+        end
+
+        protected
+
+        def allocation_hash(allocation)
+          {
+            bank_code: allocation.bank_code,
+            receipt_location: allocation.receipt_location,
+            receipt_number: allocation.receipt_number
+          }
+        end
+      end
+    end
+  end
+end

data/lib/agris/api/accounts_receivables/new_payment_remark.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Agris
+  module Api
+    module AccountsReceivables
+      class NewPaymentRemark
+        include XmlModel
+
+        ATTRIBUTE_NAMES = %w(
+          bank_code
+          receipt_location
+          receipt_number
+          record_type
+          remark_number
+          remark_value
+        ).freeze
+
+        attr_reader(*ATTRIBUTE_NAMES)
+
+        def initialize(attributes = {})
+          super
+
+          @record_type = 'ACRR1'
+        end
+
+        def for_allocation(allocation)
+          self.class.new(
+            hash.merge(
+              bank_code: allocation.bank_code,
+              receipt_location: allocation.receipt_location,
+              receipt_number: allocation.receipt_number
+            )
+          )
+        end
+      end
+    end
+  end
+end

data/lib/agris/api/accounts_receivables/payment_post_result.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Agris
+  module Api
+    module AccountsReceivables
+      # The posted receipt comes back in `document` as a fixed-width triple:
+      # receipt location (3), receipt number (6), bank code (2).
+      class PaymentPostResult < PostResult
+        def receipt_location
+          document_field(0, 3)
+        end
+
+        def receipt_number
+          document_field(3, 6)
+        end
+
+        def bank_code
+          document_field(9, 2)
+        end
+
+        # A rejected post still returns the location and bank code, so only the
+        # receipt number tells you whether Agris allocated a receipt.
+        def allocated?
+          !receipt_number.empty?
+        end
+
+        protected
+
+        def document_field(offset, length)
+          document_number.to_s[offset, length].to_s.strip
+        end
+      end
+    end
+  end
+end

data/lib/agris/api/accounts_receivables/payments.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Agris
+  module Api
+    module AccountsReceivables
+      module Payments
+        def create_payment(payment)
+          post_payment(payment)
+        end
+
+        # Agris will not accept a receipt and its applications in one message,
+        # so each application posts against the receipt Agris allocated.
+        def apply_payment(payment, allocation)
+          post_payment(payment.for_allocation(allocation))
+        end
+
+        protected
+
+        def post_payment(payment)
+          message = Messages::Import.new(payment)
+
+          response = @request.process_message(
+            Gyoku.xml(xml: context_hash),
+            message.message_number,
+            message.to_xml
+          )
+
+          PaymentPostResult.new(response)
+        end
+      end
+    end
+  end
+end

data/lib/agris/api/accounts_receivables.rb

@@ -4,6 +4,12 @@ module Agris
     module AccountsReceivables
       autoload :Invoice, 'agris/api/accounts_receivables/invoice'
       autoload :Invoices, 'agris/api/accounts_receivables/invoices'
+      autoload :NewPayment, 'agris/api/accounts_receivables/new_payment'
+      autoload :NewPaymentRemark,
+               'agris/api/accounts_receivables/new_payment_remark'
+      autoload :PaymentPostResult,
+               'agris/api/accounts_receivables/payment_post_result'
+      autoload :Payments, 'agris/api/accounts_receivables/payments'
       autoload :SpecificInvoiceExtract,
                'agris/api/accounts_receivables/specific_invoice_extract'
     end

data/lib/agris/api/document_query_response.rb

@@ -9,7 +9,8 @@ module Agris
       end
 
       def last_request_date_time
-        Time.parse(@output_hash[pluralized_resource_name]['system']['lastrequestdatetime'])
+        system_hash = @output_hash[pluralized_resource_name]['system']
+        Time.parse(system_hash['lastrequestdatetime'])
       end
 
       def documents
@@ -37,7 +38,10 @@ module Agris
       end
 
       def resource_type
-        @resource_type ||= Object.const_get(self.class.name.split('::').last.chomp('ExtractResponse'))
+        @resource_type ||= begin
+          name = self.class.name.split('::').last.chomp('ExtractResponse')
+          Object.const_get(name)
+        end
       end
 
       def resources

data/lib/agris/api/grain/contract.rb

@@ -104,11 +104,11 @@ module Agris
         def self.add_transcodes_to_schedule(schedule)
           if schedule['trancodes']
             trancodes = schedule['trancodes']['trancode']
-            trancodes = [trancodes] unless trancodes.class == Array
+            trancodes = [trancodes] unless trancodes.instance_of?(Array)
             trancodes.each do |trancode|
-              label_code = trancode['label'].downcase + 'code'
+              label_code = "#{trancode['label'].downcase}code"
               schedule[label_code] = trancode['code']
-              label_description = trancode['label'].downcase + 'description'
+              label_description = "#{trancode['label'].downcase}description"
               schedule[label_description] = trancode['description']
             end
           end

data/lib/agris/api/grain/new_ticket.rb

@@ -31,6 +31,7 @@ module Agris
           tare_weight
           freight_weight
           freight_rate
+          freight_uom
           additional_freight
           cash_price
           cash_basis