agris 0.19.0 → 1.1.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,24 @@
+# Specs
+
+Specs in this repo are **build prompts**: short, point-in-time briefs for one PR. The code is
+the source of truth; a prompt records what a slice was asked to deliver and is not updated
+after review. Divergence between prompt and merged code is an expected record of what review
+corrected.
+
+Standing facts (Agris behaviour, business rules, spike results) live in Jira and Confluence and
+are cited, not repeated. A prompt states only what is specific to its slice.
+
+## Writing one
+1. Name the file for the Jira task the PR delivers: `docs/specs/<key>-<slug>.md`
+   (e.g. `ot3-257-freight-ticket-reference.md`).
+2. Keep it to roughly 25–45 lines: **Goal** (2–3 sentences), **Scope** stated positively
+   ("Exactly: …" plus one "Later: …" line), **Rules** (R#, MUST / MUST NOT), **Acceptance
+   criteria** (AC#, the complete test list), and **Slice-specific notes** for gotchas.
+3. Note the diff budget (≤200 lines) and split before dispatch if the estimate is over.
+4. Commit it with the PR as a `docs(specs):` commit and paste it into the PR description
+   in a collapsed `<details>` block titled "Build prompt (frozen — not updated after review)".
+5. Cite R# and AC# in commit bodies and the PR's test checklist. Do not put spec IDs or
+   paths in code or test comments.
+
+`spec-template.md` and `rename-folder.example.md` are the retired long-form house format,
+kept for reference only. The area folders (`grain/`, `inventory/`, …) are unused by prompts.

data/docs/specs/ot3-257-freight-ticket-reference.md

@@ -0,0 +1,48 @@
+# Build Prompt — OT3-257: ACPV3 freight ticket reference detail
+
+Jira: OT3-255 task OT3-257 · 2026-09-16 · Budget ≤200.
+Condensed after the build from the house-format spec this PR first carried; rules and ACs
+match the shipped code. Standing facts live in Jira OT3-256 (staging spike, 2026-09-14) and
+the BRD "Freight Voucher via Agris API" (Confluence, SD space) and are not repeated here.
+
+## Goal
+Let a consumer post an AGRIS accounts-payable freight voucher (type FV) that references the
+grain ticket it pays. AGRIS 22.3.0 SU5 or later (AGS-17887) stamps the voucher number on the
+ticket and drops it from the unpaid Freight Expenses population. The gem gains the ACPV3
+detail record; contracto wires it into vouchers in OT3-259.
+
+## Scope
+Exactly: `Agris::Api::NewVoucher::FreightTicketReferenceDetail` in `lib/agris/api/new_voucher.rb`,
+its RSpec file, a `NewVoucher` RSpec file for mixed details, this prompt, and an `Unreleased`
+changelog line. Later: the 1.1.0 bump and dated changelog heading (release PR); consumer-side
+rules in contracto's `docs/specs/freight-conventions.md` (OT3-258).
+
+## Rules
+- R1 — includes `XmlModel`; `ATTRIBUTE_NAMES` is exactly `in_out_code`, `ticket_location`,
+  `ticket_number`, `freight_amount`, `record_type`; `attr_reader(*ATTRIBUTE_NAMES)` as on
+  `NewVoucher` and `NewDisbursement`.
+- R2 — `record_type` is always `'ACPV3'`; a value passed to the constructor is overwritten.
+- R3 — `to_xml_hash` emits `:@recordtype => 'ACPV3'` plus `:@inoutcode`, `:@ticketlocation`,
+  `:@ticketnumber`, `:@freightamount` for whichever attributes were supplied, values untouched.
+  An omitted attribute emits no key (existing `XmlModel` behaviour; AGRIS decides validity).
+- R4 — `NewVoucher#add_detail` needs no change: a voucher holding a `GeneralLedgerDetail` and
+  this detail serializes both, in insertion order, each under its own record type.
+- R5 — MUST NOT validate AGRIS-side rules (ACPV3 sum equals voucher amount, shipper equals
+  remit-to, an ACPV2 line present). AGRIS reports those in-band via `PostResult#reject_reasons`.
+
+## Acceptance criteria (the complete test list)
+- AC-1 — `record_type` defaults to ACPV3; `record_type: 'OTHER'` still reads and serializes ACPV3.
+- AC-2 — all four attributes supplied (I / 051 / 0028786 / 230.85, the spike's ticket): readers
+  return the inputs; `to_xml_hash` equals exactly the five-key hash.
+- AC-3 — only `ticket_number` supplied: the other readers return nil; hash keys are exactly
+  `:@ticketnumber` and `:@recordtype`.
+- AC-4 — `ATTRIBUTE_NAMES` lists exactly the five names.
+- AC-5 — `NewVoucher` with one GL detail then one ACPV3 detail: `details` in insertion order,
+  record types `%w(ACPV2 ACPV3)`, header `to_xml_hash` excludes the details.
+
+## Slice-specific notes
+- The two older detail classes have no readers and are left alone.
+- No spec IDs or paths in code or test comments (Coding Style Rules §2.4); traceability is this
+  prompt plus the PR checklist.
+- Wire shape confirmed by rendering the real `create_voucher` payload: the ACPV3 element lands
+  flat inside `<details>` beside ACPV0 and ACPV2.

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