xero-kiwi 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 122c7e012d619aabdf473185bf0e39e1e04204940d2c6d6b96888d1b6f73b76c
-  data.tar.gz: 2bbb94621f3e417275b1ea326a2e54e50f03083c01991863e2f91a16af5945ea
+  metadata.gz: e52bfcc3939a00a86a7bc26b931aa6e7553b2479fb3b2b36c3215daccad754de
+  data.tar.gz: 0c13e42901c11b857c0476dea1c898a46a12404de66231df0b82cb9c899d9a71
 SHA512:
-  metadata.gz: 0266fde7e2c101e0533f9e3202ba2871f0a17c170e27ff82dd380448028f608da61f697c3ca08d2a965245125c0987f0a9ddb54ccc01e0a89f47d437fd5aa62d
-  data.tar.gz: 93e24cd65f1ebf4f7dec4a97fe17d352fb7f6d2ed95f22e6466f403f9997859d16d51569614736c9a1ae77351f94b306dd8304b8f368f465d7c040f2eebb4514
+  metadata.gz: 1d9b16a8564e87c0935dfd301ec480fa856c7374f70ca939eef877d4e108f8e54a9ef38a1454451d848de1d6c697addb561f3bf81e3405414dbb0567c9ff77d2
+  data.tar.gz: 169f97330de612d1c940bbd0ee0d671c5d5ae7cc4284f5cc42af9b5d59cd37c2e5a68a81113d7e56a66c6e03a5a649bac779783d9b055db143f04684cd6d954c

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [0.11.0] - 2026-10-08
+
+### Added
+
+- **`include_archived:`** on `tracking_categories` / `each_tracking_category` / `each_tracking_category_page`, matching the contacts methods. Maps to Xero's `includeArchived`. Without it, Xero leaves out archived categories *and* the archived options under active ones, so a sync that mirrors the list — deleting whatever Xero didn't return — deletes every archived option, and historical invoices tagged with one stop resolving. A consumer's legacy XML client sent the flag; on 0.10.0 passing it raised `ArgumentError: unknown keyword: :include_archived`.
+
+### Documentation
+
+- The tracking categories "lookup from option ID" example now passes `include_archived: true`. Without it, `options.fetch` raises `KeyError` on any line item tagged with an archived option.
+- The "Ignoring archived categories" example filtered a list that could never contain one, since Xero leaves archived categories out by default. It now says so, and shows the filter on a list fetched with `include_archived: true`.
+
 ## [0.10.0] - 2026-09-29
 
 ### Breaking

data/docs/accounting/tracking-category.md

@@ -52,8 +52,11 @@ categories.first.options.map(&:name)  # => ["Eastside", "Westside"]
 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
+Archived categories, and archived options under active ones, are left out
+unless you pass `include_archived: true`. See [Querying](../querying.md).
+
+This endpoint isn't paged — Xero returns every category in one response, and
+an organisation has at most two active ones. `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
@@ -139,10 +142,12 @@ so it falls back to structural equality — every attribute must match.
 ### 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.
+option list, fetch the definitions once per sync and index them. Include
+archived ones, or a line item tagged with an archived option raises
+`KeyError`.
 
 ```ruby
-options = client.tracking_categories(tenant_id).flat_map do |category|
+options = client.tracking_categories(tenant_id, include_archived: true).flat_map do |category|
   category.options.map { |option| [option.tracking_option_id, [category.name, option.name]] }
 end.to_h
 
@@ -156,6 +161,11 @@ end
 
 ### Ignoring archived categories
 
+Xero leaves archived categories out unless you ask for them, so a plain
+`client.tracking_categories(tenant_id)` already returns only active ones.
+Filter when you fetched archived ones too, for a lookup like the one above:
+
 ```ruby
-active = client.tracking_categories(tenant_id).select(&:active?)
+categories = client.tracking_categories(tenant_id, include_archived: true)
+active     = categories.select(&:active?)
 ```

data/docs/querying.md

@@ -233,14 +233,18 @@ 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
+## `include_archived:` — archived contacts and tracking categories
 
-Contacts only. Maps to Xero's `includeArchived` query param, which returns
-archived contacts **alongside** active ones in the same pass.
+Contacts and tracking categories only. Maps to Xero's `includeArchived`
+query param, which returns archived records **alongside** active ones in
+the same pass.
 
 ```ruby
 client.contacts(tenant, include_archived: true)
 client.each_contact(tenant, include_archived: true) { |contact| … }
+
+client.tracking_categories(tenant, include_archived: true)
+client.each_tracking_category(tenant, include_archived: true) { |category| … }
 ```
 
 This is not the same as filtering on `contact_status`. A
@@ -252,6 +256,11 @@ 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.
 
+For tracking categories it reaches the options too. Without it, Xero leaves
+out archived categories *and* the archived options under active ones. Line
+items keep pointing at an archived option, so a sync that mirrors the list
+without this flag deletes options its invoices still refer to.
+
 ## Combining everything
 
 Mix and match freely:

data/lib/xero_kiwi/client.rb

@@ -617,7 +617,11 @@ module XeroKiwi
     # Fetches the Tracking Categories for the given tenant. Accepts a tenant-id
     # string or a XeroKiwi::Connection (we use its tenant_id).
     # See: https://developer.xero.com/documentation/api/accounting/trackingcategories
-    def tracking_categories(tenant_id, where: nil, order: nil, page_size: nil, page: nil, modified_since: nil)
+    def tracking_categories(tenant_id, where: nil, order: nil, page_size: nil, include_archived: nil, page: nil, modified_since: nil)
+      extra_params = {}
+
+      extra_params["includeArchived"] = include_archived unless include_archived.nil?
+
       list_request(
         path:           "/api.xro/2.0/TrackingCategories",
         tenant_id:      tenant_id,
@@ -626,27 +630,28 @@ module XeroKiwi
         order:          order,
         page:           page,
         page_size:      page_size,
-        modified_since: modified_since
+        modified_since: modified_since,
+        extra_params:   extra_params
       )
     end
 
     # Yields every Tracking Category across all pages, driving `#tracking_categories` with
     # `page:` until an empty or short page signals the end. Returns an
     # Enumerator when no block is given.
-    def each_tracking_category(tenant_id, where: nil, order: nil, page_size: nil, start_page: 1, modified_since: nil, &block)
-      return to_enum(:each_tracking_category, tenant_id, where: where, order: order, page_size: page_size, start_page: start_page, modified_since: modified_since) unless block
+    def each_tracking_category(tenant_id, where: nil, order: nil, page_size: nil, include_archived: nil, start_page: 1, modified_since: nil, &block)
+      return to_enum(:each_tracking_category, tenant_id, where: where, order: order, page_size: page_size, include_archived: include_archived, start_page: start_page, modified_since: modified_since) unless block
 
-      each_tracking_category_page(tenant_id, where: where, order: order, page_size: page_size, start_page: start_page, modified_since: modified_since) { |pg| pg.each(&block) }
+      each_tracking_category_page(tenant_id, where: where, order: order, page_size: page_size, include_archived: include_archived, start_page: start_page, modified_since: modified_since) { |pg| pg.each(&block) }
     end
 
     # Same walk as `#each_tracking_category`, but yields each XeroKiwi::Page rather
     # than its items. Pair `page.page` with `start_page:` to make a sync
     # resumable: record the page number in the same transaction that stores
     # the rows, and a crash can't leave a marker ahead of the data.
-    def each_tracking_category_page(tenant_id, where: nil, order: nil, page_size: nil, start_page: 1, modified_since: nil, &block)
-      return to_enum(:each_tracking_category_page, tenant_id, where: where, order: order, page_size: page_size, start_page: start_page, modified_since: modified_since) unless block
+    def each_tracking_category_page(tenant_id, where: nil, order: nil, page_size: nil, include_archived: nil, start_page: 1, modified_since: nil, &block)
+      return to_enum(:each_tracking_category_page, tenant_id, where: where, order: order, page_size: page_size, include_archived: include_archived, start_page: start_page, modified_since: modified_since) unless block
 
-      walk_pages(:tracking_categories, tenant_id, where: where, order: order, page_size: page_size, start_page: start_page, modified_since: modified_since, &block)
+      walk_pages(:tracking_categories, tenant_id, where: where, order: order, page_size: page_size, include_archived: include_archived, start_page: start_page, modified_since: modified_since, &block)
     end
 
     # Fetches a single Tracking Category by ID for the given tenant. Accepts a

data/lib/xero_kiwi/version.rb

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

data/llms-full.txt

@@ -2158,14 +2158,18 @@ 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
+## `include_archived:` — archived contacts and tracking categories
 
-Contacts only. Maps to Xero's `includeArchived` query param, which returns
-archived contacts **alongside** active ones in the same pass.
+Contacts and tracking categories only. Maps to Xero's `includeArchived`
+query param, which returns archived records **alongside** active ones in
+the same pass.
 
 ```ruby
 client.contacts(tenant, include_archived: true)
 client.each_contact(tenant, include_archived: true) { |contact| … }
+
+client.tracking_categories(tenant, include_archived: true)
+client.each_tracking_category(tenant, include_archived: true) { |category| … }
 ```
 
 This is not the same as filtering on `contact_status`. A
@@ -2177,6 +2181,11 @@ 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.
 
+For tracking categories it reaches the options too. Without it, Xero leaves
+out archived categories *and* the archived options under active ones. Line
+items keep pointing at an archived option, so a sync that mirrors the list
+without this flag deletes options its invoices still refer to.
+
 ## Combining everything
 
 Mix and match freely:
@@ -3545,8 +3554,11 @@ categories.first.options.map(&:name)  # => ["Eastside", "Westside"]
 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
+Archived categories, and archived options under active ones, are left out
+unless you pass `include_archived: true`. See [Querying](../querying.md).
+
+This endpoint isn't paged — Xero returns every category in one response, and
+an organisation has at most two active ones. `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
@@ -3632,10 +3644,12 @@ so it falls back to structural equality — every attribute must match.
 ### 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.
+option list, fetch the definitions once per sync and index them. Include
+archived ones, or a line item tagged with an archived option raises
+`KeyError`.
 
 ```ruby
-options = client.tracking_categories(tenant_id).flat_map do |category|
+options = client.tracking_categories(tenant_id, include_archived: true).flat_map do |category|
   category.options.map { |option| [option.tracking_option_id, [category.name, option.name]] }
 end.to_h
 
@@ -3649,8 +3663,13 @@ end
 
 ### Ignoring archived categories
 
+Xero leaves archived categories out unless you ask for them, so a plain
+`client.tracking_categories(tenant_id)` already returns only active ones.
+Filter when you fetched archived ones too, for a lookup like the one above:
+
 ```ruby
-active = client.tracking_categories(tenant_id).select(&:active?)
+categories = client.tracking_categories(tenant_id, include_archived: true)
+active     = categories.select(&:active?)
 ```
 
 

metadata

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