xero-kiwi 0.5.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb7181193042ba51598251bc4bee70c0e84ae0333216d94838e996f813b05770
-  data.tar.gz: 7103cdb42e4cb742cbafa0eae6c807f7958626751dbdd1cd86aa14fbbe4939a8
+  metadata.gz: c3c9271654c527275c19a5738effb1f5d334844a14898eaf467fc6671fbc308a
+  data.tar.gz: 0645a88a9ccd58130524e24d9981f3999b74ddf8ee98af9600a73f45cda4d29e
 SHA512:
-  metadata.gz: f5a369e373c45e9d4343666eb59e2adbf16a1620efe57052b89f655be7d09bc63c30d120c7a47dc873e5ed0ac1f6af5fb2b23c4b71847819ac15c9f3c2e0f5a3
-  data.tar.gz: 51ac21d3ace42a9ebefaa03ee2fdf924a6dd9549eb41d053901f0a2c6d115147e35a9f90e77438241937ca2171fdbf6a295792bfbef4528e209b5211f1d598b4
+  metadata.gz: 74bbf0e97f3207d0aaaa16c85a82fe5c1f8572ef10c3c5d802ed2b051538ad002c9aae5df62da3f9ffd7aa76e64d4446a33cfcb98ac5d9eec3edc2f6a143d1bb
+  data.tar.gz: 32141ab2ffa3f40865a432711e1e6147c99006325e30f633f035790ab1ffefd085021eda40d5f2e22621eda084fb34174691fe6c65c405497ab7452106c9aa69

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [Unreleased]
 
+## [0.6.0] - 2026-09-27
+
+### Fixed
+
+- **`Accounting::Allocation#amount` always returned nil.** It was mapped to Xero's `"Amount"`, which is the key for the allocation *request* body. Every response — and allocations only ever reach this gem embedded in a CreditNote, Prepayment or Overpayment response — carries `"AppliedAmount"`. The allocated value is now modelled as **`applied_amount`**, and `#amount` is an alias of it so callers who reached for the obvious name get the value they meant. Nothing that depended on a real value is affected, because there was never one to depend on.
+
+  This mattered more than a missing field usually would: `allocations.map(&:amount)` returned an array of nils rather than raising, so an importer would have written zeroes into every allocated amount with nothing failing anywhere. Reported by a consumer who checked stored payloads before trusting the typed path.
+
+  Four spec files had fabricated `"Amount"` payloads and so agreed with the bug instead of catching it; all now use the real response shape.
+
+### Breaking
+
+- `Allocation#to_h` now carries `:applied_amount` instead of `:amount`, and `:amount` is no longer a declared attribute (it is a plain reader, so one value maps to one key). Anyone reading `to_h[:amount]` was reading nil.
+
+### Documentation
+
+- The README now documents the release process. It covered running specs but said nothing about cutting a release, so the sequencing lived only in one person's head. It leads with the rule and the reason — `rake release` tags whatever is checked out, so a version bump riding along in a pull request gets orphaned the moment that PR is squash-merged, which is what happened to v0.5.2 — and records the thing that is not guessable from the repo: `docs/` ships inside the gem, so a documentation-only fix still needs a patch release to reach anyone.
+
 ## [0.5.2] - 2026-09-27
 
 ### Documentation

data/README.md

@@ -113,6 +113,42 @@ default `redis://127.0.0.1:6379/15`.
 docker compose down          # when you're done
 ```
 
+### Releasing
+
+**Merge first, then bump.** `rake release` tags whatever is checked out, so a
+version bump that rides along inside a pull request gets orphaned the moment
+that PR is squash-merged — the squash creates a new commit and the tag is left
+pointing at the pre-merge branch commit, unreachable from `main`. Bumping after
+the merge makes that impossible regardless of merge strategy.
+
+So: land the work through a PR as normal, then
+
+```sh
+git checkout main && git pull
+```
+
+1. Bump `VERSION` in [lib/xero_kiwi/version.rb](lib/xero_kiwi/version.rb).
+2. Move the `[Unreleased]` entries in [CHANGELOG.md](CHANGELOG.md) under a
+   dated version heading.
+3. `bundle install` to refresh the lockfile's `xero-kiwi (x.y.z)`.
+4. `bundle exec rake` — specs, RuboCop, and the `llms:check` freshness guard.
+5. Commit to `main`. A commit-msg hook requires the `crimesjohnson:` prefix
+   there, so: `crimesjohnson: release x.y.z with <the headline>`.
+
+```sh
+bundle exec rake release     # builds, tags, pushes the tag, publishes
+```
+
+The gemspec sets `rubygems_mfa_required`, so this prompts for an OTP and can't
+run unattended. Finally, cut the GitHub release from the changelog section:
+
+```sh
+gh release create vx.y.z --title "vx.y.z — <headline>" --notes-file <(…) --verify-tag --latest
+```
+
+Note that `docs/` ships inside the gem, so a documentation-only fix still needs
+a patch release to reach anyone — it won't arrive through GitHub alone.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at

data/docs/accounting/credit-note.md

@@ -61,7 +61,7 @@ fields Xero returns:
 | `reference` | `String` | Additional reference number (ACCRECCREDIT only). |
 | `sent_to_contact` | `Boolean` | Whether the credit note has been sent to the contact. |
 | `remaining_credit` | `Numeric` | The remaining credit balance. |
-| `allocations` | `Array<XeroKiwi::Accounting::Allocation>` | Allocations to invoices. Each allocation has an `invoice` reference. |
+| `allocations` | `Array<XeroKiwi::Accounting::Allocation>` | Allocations to invoices. Each has `allocation_id`, `applied_amount`, `date`, `is_deleted`, and an `invoice` reference. |
 | `branding_theme_id` | `String` | The branding theme ID applied to the credit note. |
 | `has_attachments` | `Boolean` | Whether the credit note has attachments. |
 

data/docs/accounting/overpayment.md

@@ -57,7 +57,7 @@ fields Xero returns:
 | `currency_code` | `String` | The currency code (e.g. `"NZD"`). |
 | `currency_rate` | `String` | The currency rate (1.0 for base currency). |
 | `remaining_credit` | `String` | The remaining credit balance. |
-| `allocations` | `Array<XeroKiwi::Accounting::Allocation>` | Allocations to invoices. Each allocation has an `invoice` reference. |
+| `allocations` | `Array<XeroKiwi::Accounting::Allocation>` | Allocations to invoices. Each has `allocation_id`, `applied_amount`, `date`, `is_deleted`, and an `invoice` reference. |
 | `payments` | `Array<XeroKiwi::Accounting::Payment>` | Payment records (references). See [Payments](payment.md). |
 | `has_attachments` | `Boolean` | Whether the overpayment has attachments. |
 | `reference` | `String` | Reference for the overpayment. |

data/docs/accounting/prepayment.md

@@ -58,7 +58,7 @@ fields Xero returns:
 | `currency_rate` | `String` | The currency rate (1.0 for base currency). |
 | `invoice_number` | `String` | The invoice number (for receive prepayments only). |
 | `remaining_credit` | `String` | The remaining credit balance. |
-| `allocations` | `Array<XeroKiwi::Accounting::Allocation>` | Allocations to invoices. Each allocation has an `invoice` reference. |
+| `allocations` | `Array<XeroKiwi::Accounting::Allocation>` | Allocations to invoices. Each has `allocation_id`, `applied_amount`, `date`, `is_deleted`, and an `invoice` reference. |
 | `payments` | `Array<XeroKiwi::Accounting::Payment>` | Payment records (references). See [Payments](payment.md). |
 | `has_attachments` | `Boolean` | Whether the prepayment has attachments. |
 | `fully_paid_on_date` | `Time` | When the prepayment was fully allocated, parsed as UTC. |

data/lib/xero_kiwi/accounting/allocation.rb

@@ -5,17 +5,31 @@ module XeroKiwi
     # Represents an allocation of a credit note, prepayment, or overpayment
     # against an invoice.
     #
+    # Xero names the allocated value differently depending on direction: the
+    # allocation *request* body takes "Amount", while every *response* — and
+    # allocations only ever reach this gem embedded in a CreditNote,
+    # Prepayment or Overpayment response — carries "AppliedAmount". This
+    # class was originally modelled off the request shape, so `amount`
+    # silently returned nil for every allocation the gem could actually
+    # produce. `#amount` is now an alias of `#applied_amount` so callers who
+    # reached for the obvious name get the value they meant.
+    #
     # See: https://developer.xero.com/documentation/api/accounting/overpayments
     class Allocation
       include Resource
 
       identity :allocation_id
 
-      attribute :allocation_id, xero: "AllocationID", type: :guid
-      attribute :amount,        xero: "Amount",       type: :decimal
-      attribute :date,          xero: "Date",         type: :date
-      attribute :invoice,       xero: "Invoice",      type: :object, of: Invoice, reference: true
-      attribute :is_deleted,    xero: "IsDeleted",    type: :bool
+      attribute :allocation_id,  xero: "AllocationID",  type: :guid
+      attribute :applied_amount, xero: "AppliedAmount", type: :decimal
+      attribute :date,           xero: "Date",          type: :date
+      attribute :invoice,        xero: "Invoice",       type: :object, of: Invoice, reference: true
+      attribute :is_deleted,     xero: "IsDeleted",     type: :bool
+
+      # Kept for callers written against the pre-0.6.0 attribute name. It
+      # could only ever have returned nil, so nothing that relied on a real
+      # value is affected.
+      def amount = applied_amount
     end
   end
 end

data/lib/xero_kiwi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module XeroKiwi
-  VERSION = "0.5.2"
+  VERSION = "0.6.0"
 end

data/llms-full.txt

@@ -126,6 +126,42 @@ default `redis://127.0.0.1:6379/15`.
 docker compose down          # when you're done
 ```
 
+### Releasing
+
+**Merge first, then bump.** `rake release` tags whatever is checked out, so a
+version bump that rides along inside a pull request gets orphaned the moment
+that PR is squash-merged — the squash creates a new commit and the tag is left
+pointing at the pre-merge branch commit, unreachable from `main`. Bumping after
+the merge makes that impossible regardless of merge strategy.
+
+So: land the work through a PR as normal, then
+
+```sh
+git checkout main && git pull
+```
+
+1. Bump `VERSION` in [lib/xero_kiwi/version.rb](lib/xero_kiwi/version.rb).
+2. Move the `[Unreleased]` entries in [CHANGELOG.md](CHANGELOG.md) under a
+   dated version heading.
+3. `bundle install` to refresh the lockfile's `xero-kiwi (x.y.z)`.
+4. `bundle exec rake` — specs, RuboCop, and the `llms:check` freshness guard.
+5. Commit to `main`. A commit-msg hook requires the `crimesjohnson:` prefix
+   there, so: `crimesjohnson: release x.y.z with <the headline>`.
+
+```sh
+bundle exec rake release     # builds, tags, pushes the tag, publishes
+```
+
+The gemspec sets `rubygems_mfa_required`, so this prompts for an OTP and can't
+run unattended. Finally, cut the GitHub release from the changelog section:
+
+```sh
+gh release create vx.y.z --title "vx.y.z — <headline>" --notes-file <(…) --verify-tag --latest
+```
+
+Note that `docs/` ships inside the gem, so a documentation-only fix still needs
+a patch release to reach anyone — it won't arrive through GitHub alone.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at
@@ -2494,7 +2530,7 @@ fields Xero returns:
 | `reference` | `String` | Additional reference number (ACCRECCREDIT only). |
 | `sent_to_contact` | `Boolean` | Whether the credit note has been sent to the contact. |
 | `remaining_credit` | `Numeric` | The remaining credit balance. |
-| `allocations` | `Array<XeroKiwi::Accounting::Allocation>` | Allocations to invoices. Each allocation has an `invoice` reference. |
+| `allocations` | `Array<XeroKiwi::Accounting::Allocation>` | Allocations to invoices. Each has `allocation_id`, `applied_amount`, `date`, `is_deleted`, and an `invoice` reference. |
 | `branding_theme_id` | `String` | The branding theme ID applied to the credit note. |
 | `has_attachments` | `Boolean` | Whether the credit note has attachments. |
 
@@ -2838,7 +2874,7 @@ fields Xero returns:
 | `currency_code` | `String` | The currency code (e.g. `"NZD"`). |
 | `currency_rate` | `String` | The currency rate (1.0 for base currency). |
 | `remaining_credit` | `String` | The remaining credit balance. |
-| `allocations` | `Array<XeroKiwi::Accounting::Allocation>` | Allocations to invoices. Each allocation has an `invoice` reference. |
+| `allocations` | `Array<XeroKiwi::Accounting::Allocation>` | Allocations to invoices. Each has `allocation_id`, `applied_amount`, `date`, `is_deleted`, and an `invoice` reference. |
 | `payments` | `Array<XeroKiwi::Accounting::Payment>` | Payment records (references). See [Payments](payment.md). |
 | `has_attachments` | `Boolean` | Whether the overpayment has attachments. |
 | `reference` | `String` | Reference for the overpayment. |
@@ -2939,7 +2975,7 @@ fields Xero returns:
 | `currency_rate` | `String` | The currency rate (1.0 for base currency). |
 | `invoice_number` | `String` | The invoice number (for receive prepayments only). |
 | `remaining_credit` | `String` | The remaining credit balance. |
-| `allocations` | `Array<XeroKiwi::Accounting::Allocation>` | Allocations to invoices. Each allocation has an `invoice` reference. |
+| `allocations` | `Array<XeroKiwi::Accounting::Allocation>` | Allocations to invoices. Each has `allocation_id`, `applied_amount`, `date`, `is_deleted`, and an `invoice` reference. |
 | `payments` | `Array<XeroKiwi::Accounting::Payment>` | Payment records (references). See [Payments](payment.md). |
 | `has_attachments` | `Boolean` | Whether the prepayment has attachments. |
 | `fully_paid_on_date` | `Time` | When the prepayment was fully allocated, parsed as UTC. |

data/llms.txt

@@ -64,7 +64,7 @@ XeroKiwi requires Ruby 3.4.1 or newer. Install with `gem "xero-kiwi"`.
 
 ## Optional
 
-- [README](https://raw.githubusercontent.com/douglasgreyling/xero-kiwi/main/README.md): high-level overview, installation, and the documentation table of contents
+- [README](https://raw.githubusercontent.com/douglasgreyling/xero-kiwi/main/README.md): high-level overview, installation, the documentation table of contents, and the development and release process
 - [Retries and rate limits](https://raw.githubusercontent.com/douglasgreyling/xero-kiwi/main/docs/retries-and-rate-limits.md): how XeroKiwi handles 429s and transient 5xxs, `client.rate_limit(tenant_id)` for remaining quota, tuning the retry policy, the Faraday middleware ordering, why 500 is deliberately not retried
 - [Throttling](https://raw.githubusercontent.com/douglasgreyling/xero-kiwi/main/docs/throttling.md): the Redis-backed per-tenant token bucket for coordinating rate limits across processes, `default_throttle`, `#remaining`, fail-open behaviour, writing a custom limiter
 - [CHANGELOG](https://raw.githubusercontent.com/douglasgreyling/xero-kiwi/main/CHANGELOG.md): version history

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: xero-kiwi
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.6.0
 platform: ruby
 authors:
 - Douglas Greyling