xero-kiwi 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b000115e3c885aaad2274ddd3b75f507af96e5e779b016d290559dedfcb96ab8
-  data.tar.gz: c86cc3db68b995cf2620f45165157759e4ec9e4bac78ca12a2e9493562ea5856
+  metadata.gz: 122c7e012d619aabdf473185bf0e39e1e04204940d2c6d6b96888d1b6f73b76c
+  data.tar.gz: 2bbb94621f3e417275b1ea326a2e54e50f03083c01991863e2f91a16af5945ea
 SHA512:
-  metadata.gz: 267a35b68a93afcccef4ce0c161f739c627b048461dbc52972b5405df85b4d2b9b3ca3dfb12d135e20ba57c363bb20605a65d25a51fb108708c0b14a2b8d8341
-  data.tar.gz: f8b9e15d6b786fa9090f61bcc093c50a2bf9654f6ad4cf35bb8b6139dc3224e375907075e82bea1c1997be0c88df406c4559018c5cc89c62d398e4130dc26b71
+  metadata.gz: 0266fde7e2c101e0533f9e3202ba2871f0a17c170e27ff82dd380448028f608da61f697c3ca08d2a965245125c0987f0a9ddb54ccc01e0a89f47d437fd5aa62d
+  data.tar.gz: 93e24cd65f1ebf4f7dec4a97fe17d352fb7f6d2ed95f22e6466f403f9997859d16d51569614736c9a1ae77351f94b306dd8304b8f368f465d7c040f2eebb4514

data/CHANGELOG.md

@@ -1,5 +1,91 @@
 ## [Unreleased]
 
+## [0.10.0] - 2026-09-29
+
+### Breaking
+
+- **Money attributes now return `BigDecimal` instead of `Float`.** Xero sends money as a JSON number, so Ruby parsed it into a Float and the `:decimal` type declaration passed it straight through, doing nothing. Floats cannot represent most decimal fractions, so arithmetic between two money fields drifts while each one still prints correctly:
+
+  ```ruby
+  17228.67 + 2584.3   # => 19812.969999999998, where Xero's Total is 19812.97
+  ```
+
+  Measured against the recorded `invoices/list` response, `sub_total + total_tax == total` failed on **3 of 55 invoices** as Floats and on **none** as BigDecimals. Every individual value round-trips exactly — all 111 distinct money literals in that recording — so the failure only appears once you do arithmetic, which is what makes it quiet.
+
+  Applies to all 36 `:decimal` attributes across `Invoice`, `CreditNote`, `Prepayment`, `Overpayment`, `Payment`, `Allocation` and `LineItem`. Floats and Integers convert via `#to_d`, which uses the shortest decimal that round-trips, so BigDecimal holds the number Xero wrote rather than the binary approximation of it. Numeric strings are parsed with `BigDecimal()` rather than `String#to_d`, because `to_d` answers `0.0` for unparseable input and a silent zero in a money field is the failure this gem has shipped twice. Unparseable input reads as `nil`, as it does for `:date`.
+
+  Upgrading: comparison is not a concern — `BigDecimal("19812.97")` equals the Float `19812.97`, and a `decimal`/`numeric` column takes it unchanged. A consumer verified that last point on real data, passing five money fields straight into decimal columns with no conversion and getting identical rows.
+
+  Two things do change. `to_s` gives `"0.1981297e5"` rather than `"19812.97"` (use `to_s("F")`), and `to_json` gives that same scientific-notation **string** where a Float gave a JSON number — a visible change in shape if you write a **typed** money attribute into a `jsonb` column. **`raw` is unaffected**: it holds Xero's parsed payload untouched, so money in there is still a Float and still serialises as a JSON number. `#inspect` renders decimals in plain form, so debugging output is unaffected.
+
+  **Check for `.to_f` on money you persist.** It silently undoes this change, and a `decimal(19,4)` column holds more precision than a Float can carry — `BigDecimal("1234567890123.4567").to_f` round-trips to `1234567890123.456`. Out of reach for GBP or ZAR at ordinary invoice sizes, not for IDR or VND. A `.to_f` left over from an XML-era client, where the value arrived as a String, is where to look.
+
+- **`""` now reads as `nil` on `:decimal` attributes too.** 0.8.0 normalised empty strings on `:string`, `:enum` and `:guid` and explicitly left `:decimal` alone as wanting its own decision. This is that decision. The alternative was `BigDecimal("")` raising, or a silent zero — the same shape as both allocation regressions.
+
+- **Removed `Invoice#sales_tax_calculation_type_code`.** It read the payload key `"SalesTaxCalculationTypeCode"`, which appears in none of this gem's recorded responses, nowhere in Xero's 911K OpenAPI spec, and in none of a consumer's 368 recorded interactions across both the XML and JSON eras. Xero has no invoice-level sales-tax-calculation field under any name; its US sales tax fields are on the line item. The reader has returned `nil` since the first commit.
+
+  Removing it cannot break working code, because there has never been a value to depend on. It is listed as Breaking because the method disappears: a caller reading it goes from a silent `nil` to a `NoMethodError`, which is the same trade the empty-string change made in 0.8.0. If Xero ever does send the key, `retain_raw: true` exposes it through `invoice.raw`.
+
+  Recording why it went, so nobody re-adds it from the same plausible-sounding guess: it was never verified against a payload or a schema, and it was documented as "US auto sales tax calculation type", which made a permanent `nil` read as an answer about the organisation rather than a gap in the gem.
+
+### Fixed
+
+- **`invoice.credit_notes`, `invoice.prepayments` and `invoice.overpayments` returned objects with the applied amount missing.** Xero nests **allocation stubs** under an invoice, not whole documents: a stub carries `AppliedAmount`, the amount applied to *that* invoice. Nothing modelled that key, so the nearest-looking reader was `total` — the document's own total, and a different number on **19 of the 24 stubs** in the recorded response. On one, `total` was `10983.65` where `applied_amount` was `857.35`.
+
+  All three resources now model `applied_amount`. It is `nil` on a document fetched in its own right, where Xero sends no such key, and populated on every stub in the recording. The only route to it before was `invoice.raw["CreditNotes"]` with `retain_raw: true`, since nested objects carry no `#raw`.
+
+  Found by the coverage task below rather than by comparison or by reading Xero's docs — the key is in no doc table, because the docs describe the XML representation and this shape only exists in JSON.
+
+- **`LineItem#account_id` was reading a key Xero does not send.** It mapped to `"AccountId"`; Xero sends `"AccountID"`, so the attribute was `nil` on every line item ever returned. The string `AccountId` appears **zero times** in Xero's 911K OpenAPI spec, and a consumer's recorded JSON response carries `AccountID` on all 18 of its populated line items.
+
+  No recording in this repo could have caught it: list endpoints omit line items, so `LineItem` has never had a real payload here. It was found by comparing the classes against Xero's published spec, which is now `rake xero:schema`.
+
+### Added
+
+- **`XeroKiwi::OAuth#client_credentials_token`** — Xero's non-tenanted `client_credentials` grant, authenticating the application rather than a user.
+
+  ```ruby
+  token  = oauth.client_credentials_token(scopes: "app.connections")
+  client = XeroKiwi::Client.new(access_token: token.access_token)
+  client.connections
+  ```
+
+  It is for the calls that belong to the app rather than to a connection — `connections` and `delete_connection`, both already non-tenanted — in the case where **no user token is available**: tearing down an organisation, or reassigning which user owns a sync. Without it, a consumer managing connections has to hand-roll the same POST, which is what prompted this: one had ported everything off its legacy client except this single grant, and was keeping the old client alive to serve it.
+
+  `redirect_uri` is not required. `scopes:` takes a String or an Array, joined the way `authorization_url` joins them, and is omitted from the request entirely when nil so Xero assigns the app's own scopes.
+
+  **The token cannot be refreshed.** Xero issues none for this grant, so `token.refreshable?` is false and a `Client` holding one raises `AuthenticationError` on expiry rather than attempting a renewal that cannot succeed — `Client#can_refresh?` already required a refresh token, so no change was needed there. Renewal is calling this again, which costs one request and needs no stored state.
+
+  Failures raise `XeroKiwi::OAuth::ClientCredentialsError`, which subclasses `AuthenticationError` so existing rescues still catch it.
+
+**`Client#connections` takes an optional `tenant_id:`**, which that grant requires. A user token identifies a user, so Xero can answer "which tenants can you see" unaided; an app token identifies nobody and answers `400 Xero-User-Id and/or Xero-Tenant-Id header must be supplied.` Measured by a consumer against live Xero — same token, same request, one header apart. It takes a String or a `XeroKiwi::Connection`; omitting it sends no header, which is what a user token wants and is unchanged. `delete_connection` needs no tenant header and takes none.
+
+So "app tokens are untenanted" holds at the *token* level and not at the request level. The first version of these docs showed `client.connections` on a client-credentials token, which is the call that 400s.
+
+- `Accounting::Organisation` now models `tax_number_name`, which names what the organisation's locale calls its tax number (`"VAT Number"` on the recorded tenant). Present and populated in the recording, previously reachable only through `raw`.
+
+- Fields Xero's spec documents and the recordings confirm on every record, all previously reachable only through `raw`: `Invoice#is_discounted`, `Invoice#has_errors`, `CreditNote#has_errors`, `CreditNote#invoice_addresses`, `Contact#has_validation_errors`, `Payment#has_validation_errors`, `ContactGroup#has_validation_errors`, and `Prepayment#branding_theme_id`.
+
+- **`attribute` accepts several candidate keys**, as `xero: %w[TrackingCategoryOption TrackingOptionName]`. The first one present in the payload wins. It is for a field with no recorded payload to settle which key Xero sends: a wrong single key reads `nil` forever and is indistinguishable from a field the tenant never fills, which is how two regressions shipped. `Contact#tracking_option_name` uses it — Xero's spec calls that field `TrackingCategoryOption`, kiwi called it `TrackingOptionName`, and neither spelling appears in any recording because no tenant to hand has a contact-level tracking default.
+
+- **`rake xero:schema`** compares the resource classes against Xero's published OpenAPI spec, cached for a day. It is the other half of `xero:coverage`: a recording shows what one tenant populated, the spec shows what an endpoint can return at all. Each has caught what the other missed — the spec found the `AccountID` bug that no payload here could, and the recordings hold `User#GlobalUserID`, which the spec omits entirely and whose absence emptied a consumer's memberships table.
+
+  It reports rather than fails, for the same reason `xero:coverage` does, and because the spec is not authoritative on its own: it documents `CreditNote#DueDate`, which Xero sends on none of the 18 recorded credit notes, and omits the four `TrackingOption` booleans that a live capture proved real. Treat a difference as a question; a payload settles it where one exists.
+
+- **`rake xero:coverage`** compares every recorded response against the resource classes that model it, and reports keys Xero sends that nothing reads, attributes nil in every recording, declared types that disagree with what arrived, and classes no recording exercises. Every silent bug this gem has shipped would have appeared in one of those four lists, with the disproving payload already committed. It reports rather than fails: gating it would need an allowlist of legitimately-absent keys, and an allowlist becomes a list nobody reads.
+
+  It also names the blind spot, and distinguishes *no cassette here* from *unverified*, which are not the same thing. `LineItem`, `Tracking`, `TrackingCategory` and `TrackingOption` have no cassette in this repo but have each been checked against a real response elsewhere — the task now says so, and says which. `Tracking` was the last class resting on Xero's spec alone, and a live `GET /Invoices/{id}` on a line item carrying two tracking categories settled it: four keys sent, four modelled, none nil. Only `ExternalLink` is genuinely unverified — no payload anywhere has carried a populated instance.
+
+  The walk also descends into attributes that hydrate through a custom lambda, which it previously skipped. `PaymentTerms` and `PaymentTerm` had read as exercised by nothing while a recorded contact carried both, and the type check immediately showed `PaymentTerm#day` arriving as an Integer against a `:string` declaration. Those attributes now declare `of:` purely so the audit can find the class; `Hydrator` ignores it when `hydrate:` is set.
+
+### Documentation
+
+- Money attribute types were documented three different ways for the same field — `String` on Overpayment and Prepayment, `Numeric` on CreditNote and Payment, `String/Numeric` on Invoice — and three examples showed `total # => "100.00"`, a quoted string it never was. All 32 rows now say `BigDecimal`, generated from the attribute declarations so they cannot drift apart again.
+
+- Each of Credit Note, Prepayment and Overpayment gained a **Nested under an invoice** section covering the stub shape, with the figures taken from the recorded response rather than invented.
+
+- `docs/client.md` documents money as a fourth thing to check when migrating from an XML client, alongside the existing nesting, key-name and type axes.
+
 ## [0.9.0] - 2026-09-29
 
 ### Added

data/README.md

@@ -117,6 +117,48 @@ default `redis://127.0.0.1:6379/15`.
 docker compose down          # when you're done
 ```
 
+### Checking a resource against real payloads
+
+```sh
+bundle exec rake xero:coverage
+```
+
+Compares every recorded response in `spec/fixtures/vcr_cassettes` against
+the resource classes that model it, and reports four things: keys Xero sends
+that nothing reads, attributes that were nil in every recording, declared
+types that disagree with what arrived, and classes no recording exercises at
+all.
+
+**Run it whenever you add or change a resource.** Every silent bug this gem
+has shipped would have appeared in one of those four lists, and in each case
+the disproving payload was already committed — the recordings were never the
+gap, reading them was.
+
+It reports rather than fails, and deliberately. Gating it would need an
+allowlist of the legitimately-absent keys, and an allowlist becomes a list
+nobody reads — which is the failure this is meant to prevent. Read the
+output instead.
+
+```sh
+bundle exec rake xero:schema
+```
+
+The other half: compares the resource classes against **Xero's published
+OpenAPI spec**, downloaded and cached for a day. A recording shows only what
+one tenant happened to populate; the spec lists what an endpoint can return
+at all.
+
+Run both. Neither is sufficient, and each has caught what the other missed:
+
+| | Found by |
+|---|---|
+| `LineItem` read `AccountId`, Xero sends `AccountID` | **spec** — no recording here carries a line item |
+| `User#global_user_id` | **recordings** — absent from the spec entirely |
+| `CreditNote#due_date` would be a gap | **neither** — the spec documents it, Xero sends it on none |
+
+Treat a difference as a question rather than a defect. A payload settles it
+where one exists.
+
 ### Releasing
 
 **Merge first, then bump.** `rake release` tags whatever is checked out, so a

data/Rakefile

@@ -10,6 +10,88 @@ require "rubocop/rake_task"
 RuboCop::RakeTask.new
 
 require_relative "tasks/llms"
+require_relative "tasks/coverage"
+require_relative "tasks/schema"
+
+namespace :xero do
+  desc "Compare every recorded Xero response against the resources that model it"
+  task :coverage do
+    $LOAD_PATH.unshift File.expand_path("lib", __dir__)
+    require "xero_kiwi"
+
+    report = Coverage.survey
+
+    puts "Keys Xero sends that nothing models"
+    puts "-" * 70
+    Coverage.unmodelled(report).sort_by { |klass, _| klass.name }.each do |klass, rows|
+      puts "\n  #{Coverage.short(klass)} (#{report[:seen][klass]} recorded)"
+      rows.each do |key, populated, total|
+        state = populated.positive? ? "populated #{populated}/#{total}" : "always empty"
+        puts format("    %-30<key>s %<state>s", key: key, state: state)
+      end
+    end
+
+    puts "\n\nAttributes nil in every recording"
+    puts "-" * 70
+    puts "  A wrong `xero:` key is indistinguishable from a field this tenant never fills."
+    Coverage.unpopulated(report).sort_by { |klass, _| klass.name }.each do |klass, names|
+      puts "\n  #{Coverage.short(klass)} (#{report[:seen][klass]} recorded)"
+      names.each do |name|
+        puts format("    %-30<name>s -> %<key>s", name: name, key: klass.attributes[name][:xero].inspect)
+      end
+    end
+
+    puts "\n\nDeclared type against what Xero sends"
+    puts "-" * 70
+    Coverage.mistyped(report).sort_by { |klass, _| klass.name }.each do |klass, rows|
+      puts "\n  #{Coverage.short(klass)}"
+      rows.each do |name, type, counts|
+        actual = counts.map { |cls, n| "#{cls} x#{n}" }.join(", ")
+        puts format("    %-26<name>s declared %-9<type>s got %<actual>s",
+                    name: name, type: type.inspect, actual: actual)
+      end
+    end
+
+    puts "\n\nClasses no cassette here exercises"
+    puts "-" * 70
+    Coverage.unexercised(report).sort_by(&:name).each do |klass|
+      short = Coverage.short(klass)
+      note  = Coverage::CONFIRMED_ELSEWHERE[short]
+      puts note ? "    #{short} — confirmed elsewhere: #{note}" : "    #{short} — unverified"
+    end
+    puts
+  end
+
+  desc "Compare the resource classes against Xero's published OpenAPI spec"
+  task :schema do
+    $LOAD_PATH.unshift File.expand_path("lib", __dir__)
+    require "xero_kiwi"
+
+    puts "Fields Xero documents that we do not read"
+    puts "-" * 70
+    Schema.unmodelled.each do |klass, keys|
+      puts "\n  #{Coverage.short(klass)}"
+      keys.each { |key| puts "    #{key}" }
+    end
+
+    puts "\n\nKeys we read that Xero does not document"
+    puts "-" * 70
+    puts "  Either the spec omits the field or we invented the key. Only a"
+    puts "  payload can say which — check `rake xero:coverage` for one."
+    Schema.undocumented.each do |klass, keys|
+      puts "\n  #{Coverage.short(klass)}"
+      keys.each { |key| puts "    #{key}" }
+    end
+
+    unmatched = Schema.unmatched
+    unless unmatched.empty?
+      puts "\n\nClasses with no matching schema in the spec"
+      puts "-" * 70
+      unmatched.each { |klass| puts "    #{Coverage.short(klass)}" }
+    end
+    puts
+  end
+end
 
 namespace :llms do
   desc "Regenerate llms.txt and llms-full.txt from README and docs/"

data/docs/accounting/contact-group.md

@@ -50,6 +50,7 @@ fields Xero returns:
 | `contact_group_id` | `String` | The unique Xero identifier for the group. |
 | `name` | `String` | The display name (e.g. "VIP Customers"). |
 | `status` | `String` | `"ACTIVE"` (only active groups are returned by Xero). |
+| `has_validation_errors` | `Boolean` | Whether Xero flagged validation errors on the group. |
 | `contacts` | `Array<XeroKiwi::Accounting::Contact>` | The contacts in the group (references — each has `reference?` returning `true`). Only present when fetching a single group. See [Contacts](contact.md). |
 
 ## Predicates

data/docs/accounting/contact.md

@@ -87,6 +87,7 @@ are always returned on list and single-contact responses:
 | `batch_payments` | `Hash` | Batch payment details (raw). |
 | `discount` | `Float` | Default discount rate. |
 | `balances` | `Hash` | Outstanding and overdue AR/AP balances (raw). |
+| `has_validation_errors` | `Boolean` | Whether Xero flagged validation errors on the contact. |
 | `has_attachments` | `Boolean` | Whether the contact has attachments. |
 
 ## The ContactPerson object

data/docs/accounting/credit-note.md

@@ -50,22 +50,48 @@ fields Xero returns:
 | `status` | `String` | e.g. `"DRAFT"`, `"SUBMITTED"`, `"AUTHORISED"`, `"PAID"`, `"VOIDED"`. |
 | `line_amount_types` | `String` | `"Inclusive"`, `"Exclusive"`, or `"NoTax"`. |
 | `line_items` | `Array<XeroKiwi::Accounting::LineItem>` | The line items. See [Prepayments — LineItem](prepayment.md#the-lineitem-object). |
-| `sub_total` | `Numeric` | The subtotal excluding taxes. |
-| `total_tax` | `Numeric` | The total tax amount. |
-| `total` | `Numeric` | The total (subtotal + total tax). |
-| `cis_deduction` | `Numeric` | CIS deduction (UK Construction Industry Scheme only). |
+| `sub_total` | `BigDecimal` | The subtotal excluding taxes. |
+| `total_tax` | `BigDecimal` | The total tax amount. |
+| `total` | `BigDecimal` | The total (subtotal + total tax). |
+| `applied_amount` | `BigDecimal` | Only set when this credit note is nested under an invoice, where it is the amount applied to *that* invoice — not the credit note total. `nil` on a credit note fetched in its own right. See [Nested under an invoice](#nested-under-an-invoice). |
+| `cis_deduction` | `BigDecimal` | CIS deduction (UK Construction Industry Scheme only). |
 | `updated_date_utc` | `Time` | When the credit note was last modified, parsed as UTC. |
 | `currency_code` | `String` | The currency code (e.g. `"NZD"`). |
-| `currency_rate` | `Numeric` | The currency rate (1.0 for base currency). |
+| `currency_rate` | `BigDecimal` | The currency rate (1.0 for base currency). |
 | `fully_paid_on_date` | `Time` | When the credit note was fully allocated, parsed as UTC. |
 | `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. |
+| `remaining_credit` | `BigDecimal` | The remaining credit balance. |
 | `allocations` | `Array<XeroKiwi::Accounting::Allocation>` | Allocations to invoices. Each has `allocation_id`, the allocated value (as both `amount` and `applied_amount` — see below), `date`, `is_deleted`, and an `invoice` reference. |
 | `payments` | `Array<XeroKiwi::Accounting::Payment>` | Payment records (references), as on prepayments and overpayments. See [Payments](payment.md). |
 | `branding_theme_id` | `String` | The branding theme ID applied to the credit note. |
+| `has_errors` | `Boolean` | Whether Xero flagged validation errors on the credit note. |
+| `invoice_addresses` | `Array<Hash>` | Invoice addresses (US auto sales tax only). Empty array when absent. |
 | `has_attachments` | `Boolean` | Whether the credit note has attachments. |
 
+## Nested under an invoice
+
+`invoice.credit_notes` does not return whole credit notes. Xero nests an
+**allocation stub** there — a partial credit note describing how much of it
+was applied to *that* invoice:
+
+```ruby
+invoice = client.invoices(tenant_id).first
+stub    = invoice.credit_notes.find { |s| s.applied_amount != s.total }
+
+stub.applied_amount  # => BigDecimal("857.35")    applied to this invoice
+stub.total           # => BigDecimal("10983.65")  the credit note's own total
+stub.credit_note_id  # => "4bbdbaaf-…"            fetch it in full with this
+```
+
+`applied_amount` and `total` answer different questions, and they differ on
+8 of the 11 stubs in this gem's recorded response. Reaching for `total`
+to ask "how much was applied to this invoice" overstates it.
+
+A stub carries only `credit_note_id`, `applied_amount`, `total` and `date`.
+Everything else is `nil` or empty, including `line_items` — fetch the
+credit note by its ID when you need the rest of it.
+
 ## Predicates
 
 ```ruby

data/docs/accounting/invoice.md

@@ -31,7 +31,7 @@ items. Fetch an individual invoice for full details including line items.
 
 ```ruby
 inv = client.invoice(tenant_id, "243216c5-369e-4056-ac67-05388f86dc81")
-inv.total           # => "2025.00"
+inv.total           # => BigDecimal("2025.00")
 inv.invoice_number  # => "OIT00546"
 ```
 
@@ -54,31 +54,32 @@ cover both the list and single-invoice responses:
 | `status` | `String` | e.g. `"DRAFT"`, `"SUBMITTED"`, `"AUTHORISED"`, `"PAID"`, `"VOIDED"`, `"DELETED"`. |
 | `line_amount_types` | `String` | `"Inclusive"`, `"Exclusive"`, or `"NoTax"`. |
 | `line_items` | `Array<XeroKiwi::Accounting::LineItem>` | The line items (empty on list, populated on single). See [Prepayments — LineItem](prepayment.md#the-lineitem-object). |
-| `sub_total` | `String/Numeric` | The subtotal excluding taxes. |
-| `total_tax` | `String/Numeric` | The total tax amount. |
-| `total` | `String/Numeric` | The total (subtotal + total tax). |
-| `total_discount` | `String/Numeric` | Total discounts on line items. |
+| `sub_total` | `BigDecimal` | The subtotal excluding taxes. |
+| `total_tax` | `BigDecimal` | The total tax amount. |
+| `total` | `BigDecimal` | The total (subtotal + total tax). |
+| `total_discount` | `BigDecimal` | Total discounts on line items. |
 | `updated_date_utc` | `Time` | When the invoice was last modified, parsed as UTC. |
 | `currency_code` | `String` | The currency code (e.g. `"NZD"`). |
-| `currency_rate` | `Numeric` | The currency rate (1.0 for base currency). |
+| `currency_rate` | `BigDecimal` | The currency rate (1.0 for base currency). |
 | `reference` | `String` | Additional reference number (ACCREC only). |
 | `branding_theme_id` | `String` | The branding theme ID. |
 | `url` | `String` | URL link to a source document. |
 | `sent_to_contact` | `Boolean` | Whether the invoice displays as "sent" in Xero. |
 | `expected_payment_date` | `Time` | Expected payment date (ACCREC only). |
 | `planned_payment_date` | `Time` | Planned payment date (ACCPAY only). |
+| `is_discounted` | `Boolean` | Whether any line item carries a discount. |
+| `has_errors` | `Boolean` | Whether Xero flagged validation errors on the invoice. |
 | `has_attachments` | `Boolean` | Whether the invoice has attachments. |
 | `repeating_invoice_id` | `String` | The repeating invoice template ID, if applicable. |
 | `payments` | `Array<XeroKiwi::Accounting::Payment>` | Payment records (references). See [Payments](payment.md). |
 | `credit_notes` | `Array<Hash>` | Credit notes applied (raw hashes). |
 | `prepayments` | `Array<Hash>` | Prepayments applied (raw hashes). |
 | `overpayments` | `Array<Hash>` | Overpayments applied (raw hashes). |
-| `amount_due` | `String/Numeric` | Amount remaining to be paid. |
-| `amount_paid` | `String/Numeric` | Sum of payments received. |
-| `amount_credited` | `String/Numeric` | Sum of credit notes, overpayments, and prepayments applied. |
-| `cis_deduction` | `Numeric` | CIS deduction (UK Construction Industry Scheme only). |
+| `amount_due` | `BigDecimal` | Amount remaining to be paid. |
+| `amount_paid` | `BigDecimal` | Sum of payments received. |
+| `amount_credited` | `BigDecimal` | Sum of credit notes, overpayments, and prepayments applied. |
+| `cis_deduction` | `BigDecimal` | CIS deduction (UK Construction Industry Scheme only). |
 | `fully_paid_on_date` | `Time` | When the invoice was fully paid, parsed as UTC. |
-| `sales_tax_calculation_type_code` | `String` | US auto sales tax calculation type. |
 | `invoice_addresses` | `Array<Hash>` | Invoice addresses (US auto sales tax only). |
 
 ## Predicates

data/docs/accounting/organisation.md

@@ -44,6 +44,7 @@ Xero returns:
 | `registration_number` | `String` | The company registration number. |
 | `employer_identification_number` | `String` | The EIN (US organisations). |
 | `tax_number` | `String` | The tax/VAT number. |
+| `tax_number_name` | `String` | What the organisation's locale calls that number, e.g. `"VAT Number"`. |
 | `financial_year_end_day` | `Integer` | Day of month the financial year ends (1–31). |
 | `financial_year_end_month` | `Integer` | Month the financial year ends (1–12). |
 | `sales_tax_basis` | `String` | e.g. `"Payments"`, `"CASH"`, `"ACCRUALS"`. |

data/docs/accounting/overpayment.md

@@ -29,7 +29,7 @@ overpayments = client.overpayments(connection)
 
 ```ruby
 op = client.overpayment(tenant_id, "aea95d78-ea48-456b-9b08-6bc012600072")
-op.total  # => "100.00"
+op.total  # => BigDecimal("100.00")
 ```
 
 `client.overpayment` hits `GET /api.xro/2.0/Overpayments/{OverpaymentID}` and
@@ -50,18 +50,42 @@ fields Xero returns:
 | `status` | `String` | e.g. `"AUTHORISED"`, `"PAID"`, `"VOIDED"`. |
 | `line_amount_types` | `String` | `"Inclusive"`, `"Exclusive"`, or `"NoTax"`. |
 | `line_items` | `Array<XeroKiwi::Accounting::LineItem>` | The line items. See [Prepayments — LineItem](prepayment.md#the-lineitem-object). |
-| `sub_total` | `String` | The subtotal excluding taxes. |
-| `total_tax` | `String` | The total tax amount. |
-| `total` | `String` | The total (subtotal + total tax). |
+| `sub_total` | `BigDecimal` | The subtotal excluding taxes. |
+| `total_tax` | `BigDecimal` | The total tax amount. |
+| `total` | `BigDecimal` | The total (subtotal + total tax). |
+| `applied_amount` | `BigDecimal` | Only set when this overpayment is nested under an invoice, where it is the amount applied to *that* invoice — not the overpayment total. `nil` on an overpayment fetched in its own right. See [Nested under an invoice](#nested-under-an-invoice). |
 | `updated_date_utc` | `Time` | When the overpayment was last modified, parsed as UTC. |
 | `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. |
+| `currency_rate` | `BigDecimal` | The currency rate (1.0 for base currency). |
+| `remaining_credit` | `BigDecimal` | The remaining credit balance. |
 | `allocations` | `Array<XeroKiwi::Accounting::Allocation>` | Allocations to invoices. Each has `allocation_id`, the allocated value (as both `amount` and `applied_amount` — see below), `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. |
 
+## Nested under an invoice
+
+`invoice.overpayments` does not return whole overpayments. Xero nests an
+**allocation stub** there — a partial overpayment describing how much of it
+was applied to *that* invoice:
+
+```ruby
+invoice = client.invoices(tenant_id).first
+stub    = invoice.overpayments.find { |s| s.applied_amount != s.total }
+
+stub.applied_amount  # => BigDecimal("1366.2")  applied to this invoice
+stub.total           # => BigDecimal("1367.0")  the overpayment's own total
+stub.overpayment_id  # => "c678f3f6-…"          fetch it in full with this
+```
+
+`applied_amount` and `total` answer different questions, and they differ on
+4 of the 4 stubs in this gem's recorded response. Reaching for `total`
+to ask "how much was applied to this invoice" overstates it.
+
+A stub carries only `overpayment_id`, `applied_amount`, `total` and `date`.
+Everything else is `nil` or empty, including `line_items` — fetch the
+overpayment by its ID when you need the rest of it.
+
 ## Predicates
 
 ```ruby

data/docs/accounting/payment.md

@@ -44,10 +44,11 @@ fields Xero returns:
 |-----------|------|------------|
 | `payment_id` | `String` | The unique Xero identifier. |
 | `date` | `Time` | The date the payment was made, parsed as UTC. |
-| `currency_rate` | `Numeric` | Exchange rate (1.0 for base currency). |
-| `amount` | `Numeric` | The payment amount in the invoice's currency. |
-| `bank_amount` | `Numeric` | The payment amount in the account's currency. |
+| `currency_rate` | `BigDecimal` | Exchange rate (1.0 for base currency). |
+| `amount` | `BigDecimal` | The payment amount in the invoice's currency. |
+| `bank_amount` | `BigDecimal` | The payment amount in the account's currency. |
 | `reference` | `String` | An optional description for the payment. |
+| `has_validation_errors` | `Boolean` | Whether Xero flagged validation errors on the payment. |
 | `is_reconciled` | `Boolean` | Whether the payment has been reconciled. |
 | `status` | `String` | e.g. `"AUTHORISED"`, `"DELETED"`. |
 | `payment_type` | `String` | e.g. `"ACCRECPAYMENT"`, `"ACCPAYPAYMENT"`. See Xero docs for all types. |

data/docs/accounting/prepayment.md

@@ -29,7 +29,7 @@ prepayments = client.prepayments(connection)
 
 ```ruby
 prepayment = client.prepayment(tenant_id, "aea95d78-ea48-456b-9b08-6bc012600072")
-prepayment.total  # => "100.00"
+prepayment.total  # => BigDecimal("100.00")
 ```
 
 `client.prepayment` hits `GET /api.xro/2.0/Prepayments/{PrepaymentID}` and
@@ -50,17 +50,19 @@ fields Xero returns:
 | `status` | `String` | e.g. `"AUTHORISED"`, `"PAID"`, `"VOIDED"`. |
 | `line_amount_types` | `String` | `"Inclusive"`, `"Exclusive"`, or `"NoTax"`. |
 | `line_items` | `Array<XeroKiwi::Accounting::LineItem>` | The line items. See [LineItem](#the-lineitem-object). |
-| `sub_total` | `String` | The subtotal excluding taxes. |
-| `total_tax` | `String` | The total tax amount. |
-| `total` | `String` | The total (subtotal + total tax). |
+| `sub_total` | `BigDecimal` | The subtotal excluding taxes. |
+| `total_tax` | `BigDecimal` | The total tax amount. |
+| `total` | `BigDecimal` | The total (subtotal + total tax). |
+| `applied_amount` | `BigDecimal` | Only set when this prepayment is nested under an invoice, where it is the amount applied to *that* invoice — not the prepayment total. `nil` on a prepayment fetched in its own right. See [Nested under an invoice](#nested-under-an-invoice). |
 | `updated_date_utc` | `Time` | When the prepayment was last modified, parsed as UTC. |
 | `currency_code` | `String` | The currency code (e.g. `"NZD"`). |
-| `currency_rate` | `String` | The currency rate (1.0 for base currency). |
+| `currency_rate` | `BigDecimal` | The currency rate (1.0 for base currency). |
 | `invoice_number` | `String` | The invoice number (for receive prepayments only). |
 | `reference` | `String` | The prepayment reference, as on credit notes and overpayments. Nil when Xero sends it empty. |
-| `remaining_credit` | `String` | The remaining credit balance. |
+| `remaining_credit` | `BigDecimal` | The remaining credit balance. |
 | `allocations` | `Array<XeroKiwi::Accounting::Allocation>` | Allocations to invoices. Each has `allocation_id`, the allocated value (as both `amount` and `applied_amount` — see below), `date`, `is_deleted`, and an `invoice` reference. |
 | `payments` | `Array<XeroKiwi::Accounting::Payment>` | Payment records (references). See [Payments](payment.md). |
+| `branding_theme_id` | `String` | The branding theme applied, as on credit notes and invoices. |
 | `has_attachments` | `Boolean` | Whether the prepayment has attachments. |
 | `fully_paid_on_date` | `Time` | When the prepayment was fully allocated, parsed as UTC. |
 
@@ -72,14 +74,38 @@ documents (prepayments, invoices, etc.):
 | Attribute | Type | What it is |
 |-----------|------|------------|
 | `description` | `String` | Line item description. |
-| `quantity` | `Float` | Quantity. |
-| `unit_amount` | `Float` | Unit amount. |
+| `quantity` | `BigDecimal` | Quantity. |
+| `unit_amount` | `BigDecimal` | Unit amount. |
 | `account_code` | `String` | The account code. |
+| `account_id` | `String` | The account ID. Xero sends this as `AccountID`; kiwi read `AccountId` until 0.10.0 and so returned `nil`. |
 | `tax_type` | `String` | The tax type override. |
-| `tax_amount` | `Float` | The calculated tax amount. |
-| `line_amount` | `Float` | The line total. |
+| `tax_amount` | `BigDecimal` | The calculated tax amount. |
+| `line_amount` | `BigDecimal` | The line total. |
 | `tracking` | `Array<Hash>` | Tracking categories (raw, max 2 per line). |
 
+## Nested under an invoice
+
+`invoice.prepayments` does not return whole prepayments. Xero nests an
+**allocation stub** there — a partial prepayment describing how much of it
+was applied to *that* invoice:
+
+```ruby
+invoice = client.invoices(tenant_id).first
+stub    = invoice.prepayments.find { |s| s.applied_amount != s.total }
+
+stub.applied_amount  # => BigDecimal("999.99")   applied to this invoice
+stub.total           # => BigDecimal("1784.87")  the prepayment's own total
+stub.prepayment_id   # => "4a27d582-…"           fetch it in full with this
+```
+
+`applied_amount` and `total` answer different questions, and they differ on
+7 of the 9 stubs in this gem's recorded response. Reaching for `total`
+to ask "how much was applied to this invoice" overstates it.
+
+A stub carries only `prepayment_id`, `applied_amount`, `total` and `date`.
+Everything else is `nil` or empty, including `line_items` — fetch the
+prepayment by its ID when you need the rest of it.
+
 ## Predicates
 
 ```ruby

data/docs/client.md

@@ -215,6 +215,58 @@ This is the third axis on which the two representations differ, after
 nesting and key names. Treat "it's the same field, so it's the same value"
 as the assumption to check rather than the one to rely on.
 
+**Money is a `BigDecimal`, not a String and not a Float.** An XML client
+hands you `"19812.97"`; Xero's JSON sends the number `19812.97`, which Ruby
+parses as a Float. Kiwi converts every money field to `BigDecimal` on the
+way in, because Floats cannot represent most decimal fractions and so
+arithmetic between two of them drifts:
+
+```ruby
+17228.67 + 2584.3            # => 19812.969999999998   ← Float
+invoice.sub_total + invoice.total_tax == invoice.total # => true
+```
+
+That identity failed on 3 of the 55 invoices in this gem's recorded
+response as Floats, and on none of them as BigDecimals. Each individual
+value was correct in both — it is only arithmetic between fields that goes
+wrong, which is what makes it quiet.
+
+For migration this mostly helps. Comparison is not a concern —
+`BigDecimal("19812.97")` equals the Float `19812.97`, equals
+`BigDecimal("19812.97")`, and `BigDecimal("100")` equals `100` — and a
+`decimal`/`numeric` column takes it unchanged. Two things do change:
+
+- **`to_s` gives `"0.1981297e5"`**, not `"19812.97"`. Use `to_s("F")` for a
+  plain decimal string.
+- **`to_json` gives the string `"0.1981297e5"`**, where a Float gave the
+  number `19812.97`. Writing a **typed** money attribute into a `jsonb`
+  column or an API response changes the stored shape — from a JSON number
+  to a JSON string in scientific notation. Call `to_s("F")` or `to_f` on
+  the way in, depending on which you want.
+
+  **`raw` is not affected.** It holds Xero's parsed payload untouched, so a
+  money value in there is still a Float and still serialises as a JSON
+  number. A consumer whose `jsonb` columns are fed from `raw` sees no
+  change at all — that separation is the whole point of `raw`.
+
+`is_a?(Float)` is also now false, though `is_a?(Numeric)` still holds.
+
+**Check for `.to_f` on money you persist.** Converting back to Float
+immediately undoes this change, and does so silently: a `decimal(19,4)`
+column holds more precision than a Float can carry, so the round trip loses
+digits rather than raising.
+
+```ruby
+BigDecimal("1234567890123.4567").round(4)             # => 1234567890123.4567
+BigDecimal("1234567890123.4567").to_f.to_d.round(4)   # => 1234567890123.456
+BigDecimal("999999999999999.9999").to_f.to_d.round(4) # => 1000000000000000.0
+```
+
+Out of reach for currencies like GBP or ZAR at ordinary invoice sizes, not
+for IDR or VND. A `.to_f` left over from an XML-era client — where the value
+arrived as a String and had to be converted — is the likely place to find
+one.
+
 One piece of luck worth knowing about: the two piles tend to fail
 differently. A `dig` that misses returns nil and writes a blank record
 quietly. Code that assumed a Hash, such as `Array#to_h` on what is now a
@@ -226,7 +278,7 @@ review time for the silent ones.
 
 | Method | Returns | Purpose |
 |--------|---------|---------|
-| `client.connections` | `Array<XeroKiwi::Connection>` | Fetch the tenants this token is authorised against. See [Connections](connections.md). |
+| `client.connections(tenant_id: nil)` | `Array<XeroKiwi::Connection>` | Fetch the tenants this token is authorised against. `tenant_id:` is required on a client-credentials token and unused on a user token. See [Connections](connections.md). |
 | `client.contacts(tenant_id_or_connection)` | `Array<XeroKiwi::Accounting::Contact>` | Fetch the contacts for a tenant. See [Contacts](accounting/contact.md). |
 | `client.contact(tenant_id_or_connection, contact_id)` | `XeroKiwi::Accounting::Contact` | Fetch a single contact by ID. See [Contacts](accounting/contact.md). |
 | `client.contact_groups(tenant_id_or_connection)` | `Array<XeroKiwi::Accounting::ContactGroup>` | Fetch the contact groups for a tenant. See [Contact Groups](accounting/contact-group.md). |

data/docs/connections.md

@@ -26,6 +26,21 @@ if the user authorised your app but didn't pick any tenants (rare, but
 possible). The endpoint doesn't take any filtering parameters — Xero returns
 everything the token has access to.
 
+### On a client-credentials token, pass `tenant_id:`
+
+```ruby
+client.connections(tenant_id: org_tenant_id)
+```
+
+Everything above assumes a **user** token, where no argument is needed. An
+app token from the [`client_credentials` grant](oauth.md#the-client-credentials-grant-no-user)
+identifies no user, so Xero can't work out whose connections to list and
+answers `400 Xero-User-Id and/or Xero-Tenant-Id header must be supplied.`
+
+`tenant_id:` takes a String or a `XeroKiwi::Connection`, and sets the
+`Xero-Tenant-Id` header. Omitting it sends no header, which is what a user
+token wants. `delete_connection` needs no tenant header on either.
+
 ## The Connection object
 
 Each `XeroKiwi::Connection` is an immutable value object exposing the fields Xero