xero-kiwi 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 353faef8c28dbf7801d5c9e8ebd152e0db172ede1aa69378144ac47cfa603436
-  data.tar.gz: b7decf2d114e9cbfba300c0274d6d9a3604c8d464ce080ac46b4a6df1e23d548
+  metadata.gz: b980ba3e8f03590d2ca887887d8509268bf87df52b882eef4730a9ce1512250c
+  data.tar.gz: bdd4952e2b7d1fd3af201f2446d17d5cd7f2bfe86e58ee9002f4115cc5624240
 SHA512:
-  metadata.gz: ff17d3c14fb35e1d6b3334935cda29c4fba9441ab012692dabc5518bb116a6615007e62a2e3c5c06a9c490f0b56d1fc16f8f42f9ff4b59d389088d68f7b2e3b9
-  data.tar.gz: ed0c6a55bcf9ed6d013f02ad76a3486a8d66f59961b959d85d7ed3e2a9f53c85cf43edb5e6f454f8c5fa556ad73983086105860983ca16c3db23633d39b3e31e
+  metadata.gz: e7086fef7948e63b5d9437a164a241f819e5a96beead2eb2701989613e8b95f643d805be209a63b98ab3dcd278c7e81f46165de054f1fd865318abb82a13e0e9
+  data.tar.gz: 94c08345afefa1b130634ab9d643052d14a24ba5200ae60a7b324344706d71465e9cecb6ce30e183876dafdf7bde0fcdbbaea487869ea99073bb388f2a7f8ab2

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-26
+
+The sync-support release: everything needed to drive a full-tenant sync through kiwi rather than around it.
+
+### Added
+
+- **`page_size:`** on every list method, plus a client-level default (`Client.new(page_size: 1_000)`) that per-call overrides beat. Maps to Xero's `pageSize`. Unset means the parameter is omitted and Xero applies its own default of 100, so existing callers are unaffected. Worth setting for any full sync — at 100 per page a 50,000-invoice tenant costs ~500 API calls against a 5,000/day limit; at 1,000 it costs ~50.
+- **`each_<resource>_page`** for all ten list resources, yielding a whole `XeroKiwi::Page` rather than its items — so the page number reaches the caller, which is what a resumable sync needs to record.
+- **`start_page:`** on both `each_<resource>` and `each_<resource>_page` (default 1), so a resumed run picks up where the last one stopped.
+- **`include_archived:`** on `contacts` / `each_contact` / `each_contact_page`. A distinct query parameter, not a `where` filter: filtering on `contact_status` returns *only* archived contacts, where this returns both kinds in one pass.
+- **`Resource#raw`** — Xero's untouched response hash, behind `Client.new(retain_raw: true)`. Off by default because retaining it roughly doubles the memory of a large page. Populated on resources built directly from a response, not on nested objects; the top-level hash already holds every nested payload, so `contact.raw["ContactPersons"]` gets there. Note `#raw` is not `#to_h` — `to_h` is a snake_case projection with different keys and different nesting.
+- **`client.rate_limit(tenant_id)`** returning a `XeroKiwi::RateLimit`. Blends what Xero's headers last reported for that tenant with what the configured throttle bucket holds, and reports **the stricter of the two** — a configured limit is a ceiling you chose, a reported limit is reality. Exposes `day_remaining`, `minute_remaining`, `day_below?`, `minute_below?`, `day_source`, `minute_source`, `reported`, `configured` and `known?`. Headers are captured on every response including errors, since a 429 is when they matter most. With nothing known, `day_below?` returns false — not knowing isn't a reason to halt a sync.
+- **`RedisTokenBucket#remaining(key)`** — current token counts without spending one, via a separate read-only Lua script. `#remaining` is an optional part of the limiter contract; `Client` checks `respond_to?` first, so a custom limiter written against 0.2.0 keeps working.
+- **Tracking categories**: `client.tracking_categories`, `client.tracking_category`, `each_tracking_category` and `each_tracking_category_page`, with a new `Accounting::TrackingOption` for the nested `Options` array. See `docs/accounting/tracking-category.md`.
+- `XeroKiwi::Page#reported_page_size` — the page size Xero actually stated, or nil when the response carried no `pagination` envelope. `page_size` keeps its existing fallback to the item count.
+
+### Breaking
+
+- **`Accounting::TrackingCategory` is now the `/TrackingCategories` endpoint resource** (`tracking_category_id`, `name`, `status`, `options`). The flattened category-and-chosen-option pair nested on line items and contacts — which this class used to model — is now **`Accounting::Tracking`**, matching Xero's own field name for it. Update any reference to `XeroKiwi::Accounting::TrackingCategory` that came from `line_item.tracking` or a contact's tracking collections. The two shapes share a name and one ID field and nothing else, which is why they're now separate classes.
+
+### Fixed
+
+- Page walks no longer fetch a redundant empty page. `build_page` falls back to the item count when Xero returns no `pagination` envelope, which made the walker's short-page check compare a number to itself (`items.size < items.size`) and never fire, leaving `empty?` as the only way to stop. The walk now measures against Xero's stated page size when there is one and the largest page seen so far otherwise — deliberately **not** against the requested `page_size`, since Xero clamps a request above an endpoint's maximum and a walk that asked for 2,000 where the cap is 1,000 would have seen page 1 as short and truncated the sync.
+
+### Changed
+
+- Widened the `jwt` runtime constraint to `>= 2.7, < 4.0` and `redis` to `>= 5.0, < 7.0`. Both majors (`jwt` 3.x, `redis` 6.x) pass the full suite, including the Lua-backed throttle specs against a real Redis. Widening rather than bumping means a host app on `redis` 5 (Sidekiq, Rails cache) isn't forced to move in lockstep with this gem.
+- Dropped the unused `mock_redis` development dependency. The throttle's bucket maths runs as a server-side Lua script, so the specs have always used a real Redis — `mock_redis` was only ever named in the comments explaining why it couldn't be used, and its `redis (~> 5)` runtime pin blocked resolving `redis` 6.
+
 ## [0.4.0] - 2026-04-20
 
 ### Added

data/README.md

@@ -23,9 +23,16 @@ problem.
   themes, and nested objects like addresses, phones, external links, and payment
   terms — all wrapped in proper value objects.
 - **Querying**: every list endpoint accepts `where` / `order` / `page` /
-  `modified_since`, with a typed hash DSL (`where: { status: "AUTHORISED" }`)
-  and raw-string escape hatches. Lazy `each_<resource>` helpers walk every
-  page for whole-tenant scans and incremental syncs.
+  `page_size` / `modified_since`, with a typed hash DSL
+  (`where: { status: "AUTHORISED" }`) and raw-string escape hatches. Lazy
+  `each_<resource>` helpers walk every page for whole-tenant scans and
+  incremental syncs.
+- **Resumable syncs**: `each_<resource>_page` yields whole pages so you can
+  record the page number alongside the rows, and `start_page:` picks the walk
+  back up where it stopped.
+- **Quota introspection**: `client.rate_limit(tenant_id)` reports how much of
+  a tenant's daily and per-minute allowance is left, taking the stricter of
+  what Xero reported and what your own throttle bucket holds.
 
 ## Installation
 
@@ -71,12 +78,13 @@ below.
 | [Overpayments](docs/accounting/overpayment.md) | Listing and fetching overpayments, the `XeroKiwi::Accounting::Overpayment` resource |
 | [Prepayments](docs/accounting/prepayment.md) | Listing and fetching prepayments, the `XeroKiwi::Accounting::Prepayment` resource, LineItem |
 | [Branding Themes](docs/accounting/branding-theme.md) | Listing and fetching branding themes, the `XeroKiwi::Accounting::BrandingTheme` resource |
+| [Tracking Categories](docs/accounting/tracking-category.md) | Listing and fetching tracking categories, the `TrackingCategory` / `TrackingOption` / `Tracking` resources |
 | [Tokens](docs/tokens.md) | The `XeroKiwi::Token` value object, automatic refresh, revocation, persistence callbacks |
 | [OAuth](docs/oauth.md) | Authorization URL building, code exchange, PKCE, ID token verification, full Rails-style example |
 | [Errors](docs/errors.md) | The error hierarchy, what to catch and when |
 | [Retries and rate limits](docs/retries-and-rate-limits.md) | How Xero Kiwi handles 429s and transient failures, customising the retry policy |
 | [Throttling](docs/throttling.md) | Redis-backed token bucket for proactive rate-limit coordination across multiple workers |
-| [Querying](docs/querying.md) | `where` / `order` / `page` / `modified_since` on list endpoints, the `Page` return type, and `each_*` lazy pagination helpers |
+| [Querying](docs/querying.md) | `where` / `order` / `page` / `page_size` / `include_archived` / `modified_since` on list endpoints, the `Page` return type, `each_*` and `each_*_page` helpers, and `start_page:` resumability |
 
 ## Status
 

data/Rakefile

@@ -28,12 +28,14 @@ LLMS_SOURCE_FILES = %w[
   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
 

data/docs/accounting/tracking-category.md

@@ -0,0 +1,150 @@
+# Tracking Categories
+
+Xero **tracking categories** let an organisation tag transactions along its
+own dimensions — Region, Department, Cost Centre. Each category holds a set
+of options (Eastside, Westside), and a line item picks at most one option
+per category. An organisation can have at most two active categories.
+
+You need a `tenant_id` from a [connection](../connections.md) before you can
+fetch tracking categories.
+
+> See: [Xero docs — Tracking Categories](https://developer.xero.com/documentation/api/accounting/trackingcategories)
+
+## Two shapes, two classes
+
+Xero uses the phrase "tracking category" for two different things, and kiwi
+models them as two separate classes. Getting these mixed up is the most
+common confusion here, so it's worth being explicit.
+
+**`XeroKiwi::Accounting::TrackingCategory`** — the *definition*, returned by
+`GET /TrackingCategories`. The category plus every option available under it.
+
+```json
+{ "TrackingCategoryID": "abc", "Name": "Region", "Status": "ACTIVE",
+  "Options": [ { "TrackingOptionID": "def", "Name": "Eastside", "Status": "ACTIVE" } ] }
+```
+
+**`XeroKiwi::Accounting::Tracking`** — the *assignment*, nested on a line
+item (Xero's own field name for it is `Tracking`) or a contact. One category
+and the single option chosen for it, flattened.
+
+```json
+{ "TrackingCategoryID": "abc", "TrackingOptionID": "def",
+  "Name": "Region", "Option": "Eastside" }
+```
+
+They share a name and one ID field and nothing else. If you're reading
+`invoice.line_items.first.tracking`, you have `Tracking` objects. If you
+called `client.tracking_categories`, you have `TrackingCategory` objects.
+
+## Listing tracking categories
+
+```ruby
+client = XeroKiwi::Client.new(access_token: "ya29...")
+
+categories = client.tracking_categories(tenant_id)
+
+categories.first.name             # => "Region"
+categories.first.options.map(&:name)  # => ["Eastside", "Westside"]
+```
+
+`client.tracking_categories` hits `GET /api.xro/2.0/TrackingCategories` with
+the `Xero-Tenant-Id` header set, and returns a `XeroKiwi::Page` of
+`TrackingCategory` objects.
+
+This endpoint isn't paged — an organisation has at most two active
+categories. `each_tracking_category` exists so all ten list resources behave
+consistently, but there's no reason to reach for it over the plain call.
+
+## Fetching a single category
+
+```ruby
+category = client.tracking_category(tenant_id, "e2f2f732-e92a-4f3a-9c4d-ee4da0182a13")
+category.name  # => "Region"
+```
+
+Hits `GET /api.xro/2.0/TrackingCategories/{TrackingCategoryID}` and returns a
+single `TrackingCategory`, or `nil` if the response is empty.
+
+## The TrackingCategory object
+
+| Attribute | Type | What it is |
+|-----------|------|------------|
+| `tracking_category_id` | `String` | The unique Xero identifier for the category. |
+| `name` | `String` | The category's display name (e.g. "Region"). |
+| `status` | `String` | `"ACTIVE"` or `"ARCHIVED"`. |
+| `options` | `Array<TrackingOption>` | The options available under this category. Empty array when absent. |
+
+`#active?` is a shorthand for `status == "ACTIVE"`.
+
+## The TrackingOption object
+
+| Attribute | Type | What it is |
+|-----------|------|------------|
+| `tracking_option_id` | `String` | The unique Xero identifier for the option. |
+| `name` | `String` | The option's display name (e.g. "Eastside"). |
+| `status` | `String` | `"ACTIVE"` or `"DELETED"`. |
+
+`#active?` is a shorthand for `status == "ACTIVE"`.
+
+## The Tracking object
+
+The assignment shape, nested on line items and contacts.
+
+| Attribute | Type | What it is |
+|-----------|------|------------|
+| `tracking_category_id` | `String` | Which category this assignment is for. |
+| `tracking_option_id` | `String` | Which option was chosen. |
+| `name` | `String` | The category's name, denormalised by Xero. |
+| `option` | `String` | The chosen option's name, denormalised by Xero. |
+
+## Querying
+
+`name` and `status` are queryable on both `TrackingCategory` and
+`TrackingOption`, as is the identity field.
+
+```ruby
+client.tracking_categories(tenant_id, where: { status: "ACTIVE" })
+```
+
+## Equality and hashing
+
+Two `TrackingCategory` objects are `==` if they share the same
+`tracking_category_id`; two `TrackingOption` objects if they share the same
+`tracking_option_id`. `Tracking` has no server-side primary key of its own,
+so it falls back to structural equality — every attribute must match.
+
+## Error behaviour
+
+| HTTP status | Exception | What it usually means |
+|-------------|-----------|------------------------|
+| 200 | (none — returns categories) | Success |
+| 401 | `XeroKiwi::AuthenticationError` | Access token is invalid or expired |
+| 403 | `XeroKiwi::ClientError` | The token doesn't have the `accounting.settings` scope |
+| 404 | `XeroKiwi::ClientError` | The tracking category ID doesn't exist in this organisation |
+
+## Common patterns
+
+### Building a lookup from option ID to names
+
+Line items carry only IDs and denormalised names; if you need the canonical
+option list, fetch the definitions once per sync and index them.
+
+```ruby
+options = client.tracking_categories(tenant_id).flat_map do |category|
+  category.options.map { |option| [option.tracking_option_id, [category.name, option.name]] }
+end.to_h
+
+invoice.line_items.each do |line|
+  line.tracking.each do |assignment|
+    category_name, option_name = options.fetch(assignment.tracking_option_id)
+    puts "#{category_name}: #{option_name}"
+  end
+end
+```
+
+### Ignoring archived categories
+
+```ruby
+active = client.tracking_categories(tenant_id).select(&:active?)
+```

data/docs/client.md

@@ -41,6 +41,40 @@ you. See [Tokens](tokens.md) for the full refresh story.
 | `adapter:` | `Symbol` / Faraday adapter | No | `Faraday.default_adapter` | The Faraday adapter to use. Override to swap in `:net_http_persistent`, `:typhoeus`, or a test adapter. |
 | `user_agent:` | `String` | No | `"XeroKiwi/<version>"` | Sent as the `User-Agent` header on every request. |
 | `retry_options:` | `Hash` | No | See [retries and rate limits](retries-and-rate-limits.md) | Overrides for the `faraday-retry` configuration. Merged into the defaults. |
+| `throttle:` | Limiter | No | `XeroKiwi.default_throttle`, else none | Proactive per-tenant rate limiting. See [Throttling](throttling.md). |
+| `page_size:` | `Integer` | No | `nil` (Xero's own default of 100) | Default `pageSize` for every list call. Per-call `page_size:` overrides it. See [Querying](querying.md). |
+| `retain_raw:` | `Boolean` | No | `false` | Keep Xero's untouched response hash on each resource, readable via `#raw`. See below. |
+
+### `retain_raw:` and `#raw`
+
+By default a resource hydrates the fields kiwi models and discards the
+original payload. Turn `retain_raw` on and each resource built directly
+from a response keeps that payload:
+
+```ruby
+client  = XeroKiwi::Client.new(access_token: token, retain_raw: true)
+contact = client.contact(tenant, contact_id)
+
+contact.raw
+# => {"ContactID" => "…", "ContactPersons" => [...], "SomeNewField" => "…"}
+```
+
+Use it to reach fields kiwi doesn't model yet, or to store what Xero sent
+verbatim.
+
+Three things to know:
+
+- **`#raw` is not `#to_h`.** `to_h` is a snake_case projection rebuilt from
+  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 top-level only.** Nested objects (line items, addresses, contact
+  persons) have no `#raw` of their own. They don't need one: the top-level
+  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 the client gives you
 

data/docs/querying.md

@@ -130,6 +130,28 @@ client.invoices(tenant, page: 2).page_size     # => 100
 client.invoices(tenant, page: 2).item_count    # total-on-this-page
 ```
 
+## `page_size:` — how many per page
+
+Maps to Xero's `pageSize` query param. Xero's own default is 100 and its
+maximum is 1,000 on most paged endpoints.
+
+Set it once on the client and every call inherits it; override per call
+where you need something different.
+
+```ruby
+client = XeroKiwi::Client.new(access_token: token, page_size: 1_000)
+
+client.invoices(tenant)                  # pageSize=1000
+client.invoices(tenant, page_size: 100)  # this call only
+```
+
+Leave it unset and kiwi omits the parameter entirely, so Xero applies its
+own default.
+
+This is worth setting for any full-tenant sync. At 100 per page a
+50,000-invoice tenant costs ~500 API calls; at 1,000 it costs ~50, against
+a daily limit of 5,000.
+
 ### Walking every page — `each_<resource>`
 
 For incremental syncs or whole-tenant scans, use the `each_*` helpers.
@@ -150,7 +172,50 @@ client.each_invoice(tenant, order: { date: :desc })
 
 Available for every listable resource: `each_user`, `each_contact`,
 `each_contact_group`, `each_invoice`, `each_credit_note`, `each_payment`,
-`each_prepayment`, `each_overpayment`, `each_branding_theme`.
+`each_prepayment`, `each_overpayment`, `each_branding_theme`,
+`each_tracking_category`.
+
+### Walking pages instead of items — `each_<resource>_page`
+
+Same walk, but each yield is a whole `Page` rather than one item. Use it
+when you need the page number — which is what makes a sync resumable.
+
+```ruby
+client.each_invoice_page(tenant, page_size: 1_000) do |page|
+  Invoice.upsert_all(page.map(&:to_h))
+  cursor.update!(invoices: page.page)   # same transaction as the upsert
+end
+```
+
+Recording the page number in the same transaction that stores the rows
+matters: a marker written when the response lands, before the rows are
+saved, can survive a crash that the rows don't — and the next run then
+skips a page it never actually imported.
+
+### Resuming — `start_page:`
+
+Both `each_*` and `each_*_page` accept `start_page:` (default 1), so a
+resumed run picks up where the last one stopped.
+
+```ruby
+client.each_invoice_page(tenant, start_page: cursor.invoices + 1) do |page|
+  …
+end
+```
+
+### How the walk knows when to stop
+
+It stops on an empty page, or on a page shorter than a full one. "Full" is
+measured against Xero's stated page size when the response carries a
+`pagination` envelope, and otherwise against the largest page seen so far
+in that walk.
+
+It is deliberately **not** measured against the `page_size:` you asked
+for. Xero clamps a request above an endpoint's maximum, so a walk that
+asked for 2,000 where the cap is 1,000 would see its very first page as
+short and stop after one page — silently truncating the sync. The cost of
+measuring instead of assuming is one extra request when the whole result
+fits in a single page and no envelope came back.
 
 ## `modified_since:` — incremental sync
 
@@ -168,6 +233,25 @@ exception, no special flag. An empty page after `modified_since:` is
 indistinguishable from a filter that matched nothing (intentional — the
 caller can treat them identically).
 
+## `include_archived:` — archived contacts
+
+Contacts only. Maps to Xero's `includeArchived` query param, which returns
+archived contacts **alongside** active ones in the same pass.
+
+```ruby
+client.contacts(tenant, include_archived: true)
+client.each_contact(tenant, include_archived: true) { |contact| … }
+```
+
+This is not the same as filtering on `contact_status`. A
+`where: { contact_status: "ARCHIVED" }` returns *only* archived contacts;
+`include_archived: true` returns both kinds together, which is what you
+want when mirroring a tenant's full contact list.
+
+It matters beyond contacts themselves: Xero keeps serving archived
+contacts as members of contact groups, so without this you can't tell
+which group members are archived locally.
+
 ## Combining everything
 
 Mix and match freely:
@@ -178,6 +262,7 @@ client.invoices(
   where:          { status: "AUTHORISED", contact: { contact_id: "abc-123" } },
   order:          { date: :desc },
   page:           1,
+  page_size:      1_000,
   modified_since: last_sync_at
 )
 ```

data/docs/retries-and-rate-limits.md

@@ -20,6 +20,54 @@ Xero enforces three separate rate limits, all returned with HTTP 429:
 Plus a `Retry-After` header on every 429 telling you how many seconds to
 wait before trying again.
 
+## Checking how much quota is left
+
+`client.rate_limit(tenant_id)` answers "how many calls can I still make
+for this tenant today?" — useful when a long job should stop early and
+leave headroom for everything else on the same tenant.
+
+```ruby
+invoice_ids.each do |id|
+  break if client.rate_limit(tenant).day_below?(1_000)
+
+  urls << client.online_invoice_url(tenant, id)
+end
+```
+
+It blends the only two sources that know anything, and always reports
+**the stricter of the two**:
+
+| Source | Where it comes from | What it sees |
+|--------|--------------------|--------------|
+| `reported` | Xero's `X-DayLimit-Remaining` / `X-MinLimit-Remaining` headers on the last call to that tenant | Every consumer of the tenant's quota, including other applications. Nil until a request has been made. |
+| `configured` | The throttle limiter's own bucket | Only calls made through this limiter — but it encodes the headroom you deliberately configured. Nil when throttling is off. |
+
+So if Xero reports 3,000 calls left but a bucket configured at 4,900/day
+holds 500 tokens, the answer is 500 — the configured limit is a ceiling
+you chose and the sync should not spend past it. If another app has burned
+the tenant's quota so Xero reports 50 while the bucket still shows 2,000,
+the answer is 50 — that one is reality.
+
+```ruby
+rl = client.rate_limit(tenant)
+
+rl.day_remaining      # => 500     the binding number
+rl.minute_remaining   # => 55
+rl.day_below?(1_000)  # => true
+rl.day_source         # => :configured   which one is binding
+rl.reported           # => #<struct day=3000, minute=58, app_minute=9800>
+rl.configured         # => #<struct day=500, minute=55>
+rl.known?             # => true
+```
+
+The headers are captured on every response, including error responses — a
+429 is exactly when they matter most.
+
+When neither source has a reading, `day_remaining` is nil and
+`day_below?` returns **false**. Not knowing how much quota is left isn't a
+reason to halt a sync, and halting would break the common case where the
+first call is what populates the figures.
+
 ## What Xero Kiwi does automatically
 
 Xero Kiwi sets up a `faraday-retry` middleware that handles transient failures

data/docs/throttling.md

@@ -192,9 +192,28 @@ Fail-open is deliberate: a misbehaving Redis shouldn't stop your app talking
 to Xero. The reactive retry layer still protects you from actually hitting
 the limits.
 
+## Asking how much is left
+
+`RedisTokenBucket#remaining(tenant_id)` reports the current token counts
+without spending one:
+
+```ruby
+bucket.remaining("tenant-abc")
+# => { minute: 55, day: 4_312 }
+```
+
+It runs the same refill arithmetic as `acquire` in a separate read-only
+Lua script, so polling it can't starve the bucket you're polling. Like
+`acquire`, it fails open and returns `nil` if Redis is unreachable, and
+`day` is `nil` when no `per_day` limit is configured.
+
+Most callers won't use this directly — `client.rate_limit(tenant_id)`
+combines it with what Xero itself reported and hands back whichever is
+stricter. See [retries and rate limits](retries-and-rate-limits.md).
+
 ## Writing a custom limiter
 
-The limiter contract is one method:
+The limiter contract is one required method:
 
 ```ruby
 class MyLimiter
@@ -203,6 +222,13 @@ class MyLimiter
     # XeroKiwi::Throttle::Timeout / DailyLimitExhausted if you want the
     # same exception shapes.
   end
+
+  # Optional. Implement it and client.rate_limit(tenant_id) will factor
+  # your bucket into its answer; leave it out and kiwi falls back to
+  # Xero's reported headers alone.
+  def remaining(tenant_id)
+    { minute: …, day: … }
+  end
 end
 ```
 

data/lib/xero_kiwi/accounting/contact.rb

@@ -11,7 +11,7 @@ module XeroKiwi
       payload_key "Contacts"
       identity    :contact_id
 
-      # Some classes referenced below (TrackingCategory, ContactGroup,
+      # Some classes referenced below (Tracking, ContactGroup,
       # BrandingTheme) haven't been loaded at the time Contact's class body
       # runs, so the lookup is deferred with a String reference.
 
@@ -40,8 +40,8 @@ module XeroKiwi
       attribute :merged_to_contact_id,               xero: "MergedToContactID", type: :guid
       attribute :sales_default_account_code,         xero: "SalesDefaultAccountCode"
       attribute :purchases_default_account_code,     xero: "PurchasesDefaultAccountCode"
-      attribute :sales_tracking_categories,          xero: "SalesTrackingCategories",        type: :collection, of: "TrackingCategory"
-      attribute :purchases_tracking_categories,      xero: "PurchasesTrackingCategories",    type: :collection, of: "TrackingCategory"
+      attribute :sales_tracking_categories,          xero: "SalesTrackingCategories",        type: :collection, of: "Tracking"
+      attribute :purchases_tracking_categories,      xero: "PurchasesTrackingCategories",    type: :collection, of: "Tracking"
       attribute :sales_default_line_amount_type,     xero: "SalesDefaultLineAmountType"
       attribute :purchases_default_line_amount_type, xero: "PurchasesDefaultLineAmountType"
       attribute :tracking_category_name,             xero: "TrackingCategoryName"

data/lib/xero_kiwi/accounting/line_item.rb

@@ -21,7 +21,7 @@ module XeroKiwi
       attribute :line_amount,     xero: "LineAmount",     type: :decimal
       attribute :discount_rate,   xero: "DiscountRate",   type: :decimal
       attribute :discount_amount, xero: "DiscountAmount", type: :decimal
-      attribute :tracking,        xero: "Tracking",       type: :collection, of: TrackingCategory
+      attribute :tracking,        xero: "Tracking",       type: :collection, of: Tracking
       attribute :item,            xero: "Item"
     end
   end

data/lib/xero_kiwi/accounting/organisation.rb

@@ -45,14 +45,15 @@ module XeroKiwi
       attribute :payment_terms,                  xero: "PaymentTerms",                 hydrate: ->(raw) { PaymentTerms.from_hash(raw) }
 
       # Xero's /Organisation endpoint returns a one-element "Organisations"
-      # array — we unwrap it to a single object.
-      def self.from_response(payload)
+      # array — we unwrap it to a single object. `opts` stays positional to
+      # match Resource.from_response; see the note there.
+      def self.from_response(payload, opts = {})
         return nil if payload.nil?
 
         items = payload["Organisations"]
         return nil if items.nil? || items.empty?
 
-        new(items.first)
+        new(items.first, retain_raw: opts[:retain_raw])
       end
 
       def demo_company? = is_demo_company == true

data/lib/xero_kiwi/accounting/resource.rb

@@ -99,13 +99,24 @@ module XeroKiwi
 
         public
 
-        def from_response(payload)
+        # `opts[:retain_raw]` is threaded down from Client#initialize. It
+        # applies to the resources built here and not to their nested
+        # objects — the top-level `raw` hash already holds every nested
+        # payload verbatim, so `contact.raw["ContactPersons"]` gets there
+        # without pushing the flag through Hydrator and every build_object
+        # call.
+        #
+        # `opts` is positional for the same reason it is on #initialize: a
+        # bare string-keyed payload (`from_response("Users" => [])`) would
+        # otherwise be swallowed as keyword arguments in Ruby 3, leaving
+        # `payload` unset.
+        def from_response(payload, opts = {})
           return [] if payload.nil?
 
           items = payload[payload_key]
           return [] if items.nil?
 
-          items.map { |attrs| new(attrs) }
+          items.map { |attrs| new(attrs, retain_raw: opts[:retain_raw]) }
         end
       end
 
@@ -116,6 +127,7 @@ module XeroKiwi
       def initialize(attrs, opts = {})
         attrs         = attrs.transform_keys(&:to_s)
         @is_reference = opts[:reference] == true
+        @raw          = opts[:retain_raw] ? attrs.freeze : nil
 
         self.class.attributes.each do |name, spec|
           value = Hydrator.call(attrs[spec[:xero]], spec)
@@ -123,6 +135,14 @@ module XeroKiwi
         end
       end
 
+      # Xero's response hash for this resource, exactly as it arrived, or nil
+      # unless the client was built with `retain_raw: true`. Use it to reach
+      # fields the gem doesn't model, or to store the payload verbatim.
+      #
+      # Note `to_h` is NOT this — it's a snake_case projection rebuilt from
+      # the modelled attributes, with different keys and different nesting.
+      attr_reader :raw
+
       def reference?
         @is_reference
       end

data/lib/xero_kiwi/accounting/tracking.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module XeroKiwi
+  module Accounting
+    # A tracking assignment — one category and the single option chosen for
+    # it — as nested on a line item (`Tracking`) or a contact. This is not
+    # the same shape as the /TrackingCategories endpoint returns; see
+    # Accounting::TrackingCategory for that.
+    #
+    # See: https://developer.xero.com/documentation/api/accounting/invoices
+    class Tracking
+      include Resource
+
+      attribute :tracking_category_id, xero: "TrackingCategoryID", type: :guid
+      attribute :tracking_option_id,   xero: "TrackingOptionID",   type: :guid
+      attribute :name,                 xero: "Name"
+      attribute :option,               xero: "Option"
+    end
+  end
+end

data/lib/xero_kiwi/accounting/tracking_category.rb

@@ -2,16 +2,25 @@
 
 module XeroKiwi
   module Accounting
-    # Represents a tracking category assignment on a line item or contact.
+    # A tracking category *definition* as returned by /TrackingCategories —
+    # the category itself plus the options available under it.
     #
-    # See: https://developer.xero.com/documentation/api/accounting/invoices
+    # Not to be confused with Accounting::Tracking, which is the flattened
+    # category-and-chosen-option pair nested on line items and contacts.
+    #
+    # See: https://developer.xero.com/documentation/api/accounting/trackingcategories
     class TrackingCategory
       include Resource
 
+      payload_key "TrackingCategories"
+      identity    :tracking_category_id
+
       attribute :tracking_category_id, xero: "TrackingCategoryID", type: :guid
-      attribute :tracking_option_id,   xero: "TrackingOptionID",   type: :guid
-      attribute :name,                 xero: "Name"
-      attribute :option,               xero: "Option"
+      attribute :name,                 xero: "Name",               query: true
+      attribute :status,               xero: "Status",             type: :enum, query: true
+      attribute :options,              xero: "Options",            type: :collection, of: TrackingOption
+
+      def active? = status == "ACTIVE"
     end
   end
 end