xero-kiwi 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e67980bd7d7be1131ee07b55847cd4633a527eec4159103ba43551903f0870c
-  data.tar.gz: f06a30a5311f02be7d8695344a7f8eb65e76f4b0abab1743f23b9701f7655600
+  metadata.gz: c3c9271654c527275c19a5738effb1f5d334844a14898eaf467fc6671fbc308a
+  data.tar.gz: 0645a88a9ccd58130524e24d9981f3999b74ddf8ee98af9600a73f45cda4d29e
 SHA512:
-  metadata.gz: bf15925c5971526baeb6c3773de4f454ab917509200794b05957b27eabdfb4691e757a01f9defca50357cf0ce8ba7aa504b8e29973685c1428b365b28d80c5bf
-  data.tar.gz: 854a1cc894da5a8706e084f1b2e328a3529470f785e4cc22c27d80080ec7c2780cf3db40eb3f919fd9afd359539a879af82d241b6a2061f3673fa80ead876357
+  metadata.gz: 74bbf0e97f3207d0aaaa16c85a82fe5c1f8572ef10c3c5d802ed2b051538ad002c9aae5df62da3f9ffd7aa76e64d4446a33cfcb98ac5d9eec3edc2f6a143d1bb
+  data.tar.gz: 32141ab2ffa3f40865a432711e1e6147c99006325e30f633f035790ab1ffefd085021eda40d5f2e22621eda084fb34174691fe6c65c405497ab7452106c9aa69

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 ## [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
+
+- Documented that `Resource#raw` returns nil on nested objects (line items, addresses, contact persons, payment terms) even with `retain_raw: true`, and that the enclosing resource's hash is the access path — `org.raw["Addresses"]` rather than `org.addresses.map(&:raw)`. The behaviour was deliberate and explained in a comment on `from_response`, but the `#raw` docstring never mentioned it and the failure is a silent nil, so a consumer mapped over a nested collection and was one step from storing `[null]`.
+- Added a written contract for `raw` in `docs/client.md`: it is the parsed JSON with only top-level keys stringified, kiwi never normalises it (absent keys stay absent rather than becoming `[]`), unmodelled keys are preserved, and the freeze is shallow — the hash is frozen, the structures inside it are not. Specs pin all four, plus the nested-nil behaviour. The previous "is frozen" example overstated the guarantee and has been replaced.
+- `llms.txt` is now generated alongside `llms-full.txt` from a single manifest in `tasks/llms.rb`, rather than hand-maintained. It had not been touched since the initial commit and was missing four releases of material — no `querying.md`, no `throttling.md`, no `tracking-category.md`, and no mention of `Page`, `RateLimit`, the throttle limiters or the tracking classes. `rake llms:check` now also fails when a doc exists under `docs/` that the manifest does not list, which is the half that was missing: the freshness check could not notice a doc that was never indexed in the first place.
+
 ## [0.5.1] - 2026-09-26
 
 ### 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/Rakefile

@@ -9,76 +9,35 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
-# Files included in llms-full.txt, in reading order. Keep README first, then
-# the docs in the same order the README's table of contents lists them.
-LLMS_SOURCE_FILES = %w[
-  README.md
-  docs/getting-started.md
-  docs/client.md
-  docs/oauth.md
-  docs/tokens.md
-  docs/connections.md
-  docs/accounting/contact.md
-  docs/accounting/contact-group.md
-  docs/accounting/organisation.md
-  docs/accounting/user.md
-  docs/accounting/credit-note.md
-  docs/accounting/invoice.md
-  docs/accounting/payment.md
-  docs/accounting/overpayment.md
-  docs/accounting/prepayment.md
-  docs/accounting/branding-theme.md
-  docs/accounting/tracking-category.md
-  docs/accounting/address.md
-  docs/accounting/phone.md
-  docs/accounting/external-link.md
-  docs/accounting/payment-terms.md
-  docs/errors.md
-  docs/retries-and-rate-limits.md
-  docs/throttling.md
-  docs/querying.md
-].freeze
-
-LLMS_FULL_PATH = "llms-full.txt"
-
-# Builds the llms-full.txt content from LLMS_SOURCE_FILES. Pure function:
-# returns a String, doesn't touch the filesystem. Both `llms:build` and
-# `llms:check` use this so the two tasks can never disagree about the
-# expected output.
-def build_llms_full
-  out = String.new(encoding: "UTF-8")
-  out << "# Xero Kiwi — full documentation\n\n"
-  out << "This file is the complete documentation for the Xero Kiwi gem (a Ruby wrapper for the Xero Accounting API), assembled into a single document for LLM consumption. It contains the README and every doc in the docs/ folder, in reading order.\n\n"
-  out << "For the curated index version, see llms.txt in the same directory.\n\n"
-  out << "Source: https://github.com/douglasgreyling/xero-kiwi\n\n"
-  LLMS_SOURCE_FILES.each { |path| append_file_block(out, path) }
-  out
-end
-
-def append_file_block(out, path)
-  separator = "=" * 80
-  out << "\n" << separator << "\n"
-  out << "FILE: #{path}\n"
-  out << separator << "\n\n"
-  out << File.read(path, encoding: "UTF-8") << "\n"
-end
+require_relative "tasks/llms"
 
 namespace :llms do
-  desc "Regenerate llms-full.txt from README and docs/"
+  desc "Regenerate llms.txt and llms-full.txt from README and docs/"
   task :build do
-    File.write(LLMS_FULL_PATH, build_llms_full)
-    puts "Wrote #{LLMS_FULL_PATH} (#{File.size(LLMS_FULL_PATH)} bytes, #{LLMS_SOURCE_FILES.size} source files)"
+    Llms.outputs.each do |path, content|
+      File.write(path, content)
+      puts "Wrote #{path} (#{File.size(path)} bytes)"
+    end
   end
 
-  desc "Verify llms-full.txt is up to date with README and docs/"
+  desc "Verify llms.txt and llms-full.txt are up to date, and that every doc is indexed"
   task :check do
-    expected = build_llms_full
-    actual   = File.exist?(LLMS_FULL_PATH) ? File.read(LLMS_FULL_PATH, encoding: "UTF-8") : ""
+    missing = Llms.unindexed_docs
+    unless missing.empty?
+      warn "✗ These docs are not listed in Llms::DOCS, so they are missing from llms.txt and llms-full.txt:"
+      missing.each { |path| warn "    #{path}" }
+      warn "  Add them to tasks/llms.rb and run `bundle exec rake llms:build`."
+      exit 1
+    end
+
+    stale = Llms.outputs.reject do |path, expected|
+      File.exist?(path) && File.read(path, encoding: "UTF-8") == expected
+    end
 
-    if expected == actual
-      puts "✓ #{LLMS_FULL_PATH} is up to date"
+    if stale.empty?
+      puts "✓ llms.txt and llms-full.txt are up to date"
     else
-      warn "✗ #{LLMS_FULL_PATH} is out of date with README/docs."
+      warn "✗ Out of date with README/docs: #{stale.keys.join(", ")}"
       warn "  Run `bundle exec rake llms:build` and commit the result."
       exit 1
     end
@@ -86,7 +45,7 @@ namespace :llms do
 end
 
 # Top-level convenience alias.
-desc "Regenerate llms-full.txt (alias for llms:build)"
+desc "Regenerate the LLM docs bundles (alias for llms:build)"
 task llms: "llms:build"
 
 task default: %i[spec rubocop llms:check]

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/docs/client.md

@@ -68,6 +68,18 @@ Five things to know:
   the envelope before building a resource, so there's nothing left of it by
   the time `raw` is populated. If you need the envelope back, you're
   rebuilding it yourself.
+- **Nested objects return `nil`, even with `retain_raw: true`.** Line
+  items, addresses, contact persons and payment terms do not carry their
+  own payload. Reach them through the enclosing resource's hash:
+
+  ```ruby
+  org.addresses.map(&:raw)   # => [nil]   ← not what you want
+  org.raw["Addresses"]       # => [{"AddressType" => "POBOX", …}]
+  ```
+
+  This is deliberate — see [why nested objects don't carry
+  raw](#why-nested-objects-dont-carry-raw) — but it fails quietly, so it's
+  worth knowing before you map over a collection and store the result.
 - **It's the JSON representation.** Kiwi sends
   `Accept: application/json`. Xero also serves XML, which nests
   differently — XML has no arrays, so a single child parses to a Hash and
@@ -78,14 +90,46 @@ Five things to know:
   the modelled attributes — different keys, different nesting. If you store
   `to_h` where you meant to store the payload, readers fail by returning
   nil rather than raising.
-- **It's per resource, not per nested object.** Line items, addresses and
-  contact persons have no `#raw` of their own. They don't need one: the
-  resource's hash already holds every nested payload, so
-  `contact.raw["ContactPersons"]` gets there.
 - **It costs memory.** Every resource holds its source hash alongside the
   hydrated attributes, which roughly doubles the footprint of a large page.
   That's why it's off by default.
 
+### What `raw` guarantees
+
+Depend on these; they won't change without a major version.
+
+- It is the parsed JSON for that resource, with **only the top-level keys
+  stringified**. Everything nested is exactly what `JSON.parse` produced.
+- **Kiwi does not normalise it.** No key renaming, no defaulting, no
+  filling in of absent keys. If Xero omits `Addresses`, `raw` has no
+  `"Addresses"` key — it does not become `[]`. If Xero sends `[]`, you get
+  `[]`. `raw.fetch("Addresses", [])` and `raw["Addresses"] || []` are both
+  safe and mean the same thing here.
+- Keys the gem doesn't model are preserved. That's the point of it.
+- The top-level hash is **frozen; nested structures are not**. `raw` itself
+  can't be mutated, but `raw["Addresses"]` is an ordinary mutable Array.
+  Dup before mutating if that matters to you.
+
+The one thing deliberately *not* guaranteed is the presence of `raw` on
+nested objects, per the bullet above.
+
+### Why nested objects don't carry raw
+
+Two reasons, both worth knowing if you're tempted to ask for it.
+
+It would cost real memory on the workload `retain_raw` exists for. A page
+of 1,000 invoices with five line items each retains about 3.4 MB with
+top-level raw; giving every nested object its own hash adds about 1.6 MB
+on top, roughly half again, and that's on a flag that has already doubled
+your footprint.
+
+More importantly it couldn't be done consistently. Several attributes —
+`payment_terms` on Contact and Organisation, `invoice_addresses` on
+Invoice — hydrate through custom lambdas that construct their objects
+directly, so they'd stay `nil` while their siblings worked. "Nested
+objects never carry raw" is a rule you can hold in your head. "Nested
+objects carry raw except these four" is not.
+
 ### Migrating from an XML-based client
 
 If you're replacing a Xero client that sent `Accept: text/xml` — HTTParty

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/accounting/resource.rb

@@ -139,11 +139,23 @@ module XeroKiwi
       # arrived, or nil unless the client was built with `retain_raw: true`.
       # Use it to reach fields the gem doesn't model.
       #
+      # Returns nil on NESTED objects even when retain_raw is on — line
+      # items, addresses, contact persons, payment terms. Reach those
+      # through the enclosing resource instead:
+      #
+      #   org.addresses.map(&:raw)  # => [nil]
+      #   org.raw["Addresses"]      # => [{"AddressType" => "POBOX", ...}]
+      #
       # Scope is the item, NOT the enclosing envelope: `contact.raw` has no
       # "Contacts" key, and `organisation.raw` no "Organisations" key. Kiwi
       # unwraps the envelope before a resource is built, so there is nothing
       # left of it by the time this is populated.
       #
+      # Kiwi never normalises what it stores here: absent keys stay absent
+      # rather than becoming [] or nil entries, and keys the gem doesn't
+      # model are preserved. The hash itself is frozen; the structures
+      # nested inside it are not.
+      #
       # It is also the JSON representation specifically. Kiwi sends
       # `Accept: application/json`; Xero's XML representation nests
       # differently — no arrays, so one child is a Hash and several are an

data/lib/xero_kiwi/version.rb

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