xero-kiwi 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4deb1de10e85de555f19546d2d2243135b2f95fff462e45a2cac72e8622a9e31
-  data.tar.gz: 46dfc6f3e6eeeda92546e95b3161aea9802fb401e823d0f2ca67d91bab3555d7
+  metadata.gz: ec24e1de644ead6640027a7d62ac1df0eda8677866e2f76f9c4e65c6a36d3750
+  data.tar.gz: a35d014164892fe7aefda15f4c9549d8da82fc292c85f7fcd2e6edb8bdc27458
 SHA512:
-  metadata.gz: 781f5c1cfde039f7746984185d218d2fa9e07ceb66cb660d7227291f7e45210f97f590a97cb0d24dfa7c265843c98a37b3d4fd857b41d6cd6ab7e53d1db8d646
-  data.tar.gz: 727152993b2424d6513c44947db8b75cd4b1a8734b000e390644c59154ba72804cd48cf16b36e0df299df250b1b6a5eebeace82aba0319adc924a30125f5bdc6
+  metadata.gz: ab8caf90f556f23e2cd8d324f2995d7c6a32f18f90728463d3b561199ac5d00181b75de84594e96f9526fa1d32c97d6f97038d48f84a2f49dc41c82d87d68338
+  data.tar.gz: '048baedacba51f2cb1aed61e2fb5539cfcb90af075d64f149a305015cf4feb78fc7dd1adee2aec0af178aaf146d732ec28e341228f4dc89f40e38ff8c3be1c22'

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-04-20
+
+### Added
+
+- Every accounting list endpoint (`contacts`, `invoices`, `credit_notes`, `overpayments`, `prepayments`, `payments`, `users`, `branding_themes`, `contact_groups`) now accepts `where:`, `order:`, `page:`, and `modified_since:` kwargs. `where:` and `order:` take a typed Hash (field-name-aware, safe literal formatting) or a raw String (escape hatch). `page:` maps to Xero's `page` query param. `modified_since: Time` sends `If-Modified-Since`; a `304 Not Modified` response returns an empty `Page`. See `docs/querying.md`.
+- New `XeroKiwi::Page` return type for every list method — `Enumerable` with `size` / `empty?` / `to_a` / `page` / `page_size` / `item_count` / `total_count`.
+- Lazy `each_<resource>` helpers (`each_invoice`, `each_contact`, `each_payment`, `each_credit_note`, `each_prepayment`, `each_overpayment`, `each_branding_theme`, `each_contact_group`, `each_user`) that walk every page for whole-tenant scans or incremental syncs. Returns an `Enumerator` when no block is given.
+- `attribute` DSL gains a `query: true` kwarg; `identity` attributes are auto-included in the resource's `query_fields` schema so you rarely need `query: true` on IDs.
+
+### Breaking
+
+- List methods now return `XeroKiwi::Page`, not `Array`. `Page` is `Enumerable` + `size` / `empty?` / `to_a`, so `.each`, `.map`, `.first`, `.count`, `.select`, `.find` keep working. Callers relying on raw `Array` behaviour (`<<`, `[0..2]`, `push`, mutation, `JSON.dump(page)`, `page.is_a?(Array)`) should call `.to_a`.
+
+### Fixed
+
+- `ResponseHandler` now lets `304 Not Modified` through instead of raising.
+
 ## [0.2.1] - 2026-04-17
 
 ### Changed

data/README.md

@@ -22,6 +22,10 @@ problem.
 - **Accounting resources**: fetch contacts, organisations, users, branding
   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.
 
 ## Installation
 
@@ -72,6 +76,7 @@ below.
 | [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 |
 
 ## Status
 

data/Rakefile

@@ -34,6 +34,7 @@ LLMS_SOURCE_FILES = %w[
   docs/accounting/payment-terms.md
   docs/errors.md
   docs/retries-and-rate-limits.md
+  docs/querying.md
 ].freeze
 
 LLMS_FULL_PATH = "llms-full.txt"
@@ -43,7 +44,7 @@ LLMS_FULL_PATH = "llms-full.txt"
 # `llms:check` use this so the two tasks can never disagree about the
 # expected output.
 def build_llms_full
-  out = +""
+  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"
@@ -70,7 +71,7 @@ namespace :llms do
   desc "Verify llms-full.txt is up to date with README and docs/"
   task :check do
     expected = build_llms_full
-    actual   = File.exist?(LLMS_FULL_PATH) ? File.read(LLMS_FULL_PATH) : ""
+    actual   = File.exist?(LLMS_FULL_PATH) ? File.read(LLMS_FULL_PATH, encoding: "UTF-8") : ""
 
     if expected == actual
       puts "✓ #{LLMS_FULL_PATH} is up to date"

data/docs/plans/0.3.0-querying.md

@@ -0,0 +1,309 @@
+# 0.3.0 — Querying (filter, order, page, modified-since)
+
+## Context
+
+0.2.1 shipped the attribute DSL + `identity` + `Hydrator` — the ground is
+prepared. This release teaches the nine accounting list endpoints how to speak
+Xero's query surface: the `where` / `order` / `page` query params and the
+`If-Modified-Since` header. Today every list call hits the bare endpoint with
+only `Xero-Tenant-Id`, forcing callers who want filtering or incremental sync
+to drop out of kiwi and issue raw HTTP.
+
+Shipping as **0.3.0**. Breaking, because list methods will return a new `Page`
+object instead of a raw `Array`. `Page` is `Enumerable` + `size` + `to_a`, so
+`.each`, `.map`, `.first`, `.select`, `.count` all keep working. Callers
+relying on Array-specific behaviour (`<<`, `[0..2]`, `push`, mutation,
+`JSON.dump`, `is_a?(Array)`) need `.to_a`.
+
+## Decisions locked in
+
+- **Return type:** `XeroKiwi::Page` (Enumerable) — items + pagination
+  metadata.
+- **Filter compiler:** field-type-aware, driven off the DSL. Unknown keys
+  raise `ArgumentError`. Raw-string escape hatch for anything the hash can't
+  express (OR across fields, `LIKE`, `StartsWith`, …).
+- **Order:** accept `Hash` (typed) or `String` (raw passthrough). Same field
+  map as the filter.
+- **Pagination:** explicit `page:` kwarg plus `each_<resource>` lazy
+  Enumerator helper.
+- **Modified-since:** `modified_since: Time` → `If-Modified-Since` header.
+  `304 Not Modified` returns an empty `Page` (no flag) — callers treat it
+  identically to an empty filter result.
+- **Query schema inheritance:** `identity :xxx_id` auto-registers that
+  attribute in the query schema. Other queryable fields still need
+  `query: true`. Saves repeating `query: true` on every ID across 11
+  identity classes.
+- **Writers: out of scope.** Reader-only, as before. DSL stays named neutral.
+
+## Design
+
+### 1. Extend the `attribute` DSL
+
+Two small additions in `lib/xero_kiwi/accounting/resource.rb`:
+
+```ruby
+def attribute(name, xero:, type: :string, of: nil, reference: false,
+              hydrate: nil, query: false)
+  attributes[name] = {
+    xero: xero, type: type, of: of,
+    reference: reference, hydrate: hydrate, query: query
+  }
+  attr_reader name
+end
+
+def query_fields
+  @_query_fields ||= attributes.each_with_object({}) do |(name, spec), acc|
+    next unless spec[:query] || identity_attributes&.include?(name)
+
+    acc[name] = build_query_field(spec)
+  end
+end
+```
+
+String `of:` refs resolve lazily, same as hydration — extract a shared
+`resolve_class` helper the DSL and Hydrator both use.
+
+### 2. Mark queryable fields on listable resources
+
+Only the 9 listable resources need `query: true` additions beyond `identity`.
+Example shape:
+
+```ruby
+class Invoice
+  include Accounting::Resource
+
+  payload_key "Invoices"
+  identity    :invoice_id                            # auto-queryable
+
+  attribute :invoice_id,       xero: "InvoiceID",     type: :guid
+  attribute :invoice_number,   xero: "InvoiceNumber", type: :string, query: true
+  attribute :type,             xero: "Type",          type: :enum,   query: true
+  attribute :status,           xero: "Status",        type: :enum,   query: true
+  attribute :date,             xero: "Date",          type: :date,   query: true
+  attribute :updated_date_utc, xero: "UpdatedDateUTC", type: :date,  query: true
+  attribute :contact,          xero: "Contact",        type: :object,
+                               of: Contact, reference: true, query: true
+  # embedded collections (line_items, payments, credit_notes, …) stay
+  # query: false — Xero's where grammar doesn't filter on them.
+end
+```
+
+Nested queries (`Contact.ContactID`) fall out automatically: when a `:object`
+attribute with `query: true` resolves, `build_query_field` walks into the
+child's `query_fields` (which already exposes the identity ID on Contact).
+
+### 3. Filter compiler — `XeroKiwi::Query::Filter`
+
+```ruby
+XeroKiwi::Query::Filter.compile(where, fields: Invoice.query_fields)
+```
+
+Rules:
+
+- `nil` → `nil`.
+- `String` → passthrough (escape hatch).
+- `Hash` → walk; each pair → `Path==Literal`, joined by `&&`.
+- `Array` value → `(Path==x || Path==y)` (IN semantics).
+- `Range` value → `Path>=lo && Path<=hi` (date ranges).
+- `Hash` value on a `:nested` field → recurse with dotted prefix.
+- Unknown key → `ArgumentError` naming the key.
+
+Literal formatting per type:
+
+- `:guid`           → `Guid("…")`
+- `:date`           → `DateTime(y,m,d)` in UTC
+- `:string`/`:enum` → `"…"` with `"` / `\` escaping
+- `:bool`           → `true` / `false`
+- `:decimal`        → `to_s`
+
+### 4. Order compiler — `XeroKiwi::Query::Order`
+
+Shares the `query_fields` map.
+
+```ruby
+Order.compile({ date: :desc, invoice_number: :asc }, fields: …)
+# => "Date DESC,InvoiceNumber ASC"
+Order.compile("Date DESC", fields: …)    # passthrough
+```
+
+### 5. `XeroKiwi::Page`
+
+```ruby
+class Page
+  include Enumerable
+  attr_reader :items, :page, :page_size, :item_count, :total_count
+
+  def each(&b) = @items.each(&b)
+  def size     = @items.size
+  def empty?   = @items.empty?
+  def to_a     = @items.dup
+end
+```
+
+Built in the client from Xero's `response.body["pagination"]` envelope
+(`page`, `pageSize`, `itemCount`, `pageCount`). When absent (non-paged
+endpoints like `BrandingThemes`, or a 304), fall back to `page: 1,
+page_size: items.size, item_count: items.size, total_count: nil`.
+
+### 6. Client surface
+
+```ruby
+def invoices(tenant_id, where: nil, order: nil, page: nil, modified_since: nil)
+  list_request(
+    path:           "/api.xro/2.0/Invoices",
+    tenant_id:      tenant_id,
+    resource_class: Accounting::Invoice,
+    where: where, order: order, page: page, modified_since: modified_since
+  )
+end
+
+def each_invoice(tenant_id, where: nil, order: nil, modified_since: nil, &block)
+  return to_enum(__method__, tenant_id, where: where, order: order,
+                                        modified_since: modified_since) unless block
+
+  (1..Float::INFINITY).lazy.each do |p|
+    pg = invoices(tenant_id, where: where, order: order, page: p,
+                             modified_since: modified_since)
+    break if pg.empty?
+    pg.each(&block)
+    break if pg.page_size && pg.size < pg.page_size
+  end
+end
+```
+
+### 7. Shared `list_request` helper
+
+```ruby
+private
+
+def list_request(path:, tenant_id:, resource_class:,
+                 where:, order:, page:, modified_since:)
+  tid = extract_tenant_id(tenant_id)
+  raise ArgumentError, "tenant_id is required" if tid.nil? || tid.empty?
+
+  fields = resource_class.query_fields
+  params = {}
+  params["where"] = Query::Filter.compile(where, fields: fields) if where
+  params["order"] = Query::Order.compile(order,  fields: fields) if order
+  params["page"]  = page                                         if page
+
+  with_authenticated_request do
+    response = http.get(path, params) do |req|
+      req.headers["Xero-Tenant-Id"]    = tid
+      req.headers["If-Modified-Since"] = modified_since.utc.httpdate if modified_since
+    end
+    build_page(response, resource_class)
+  end
+end
+```
+
+### 8. 304 handling
+
+`ResponseHandler` currently raises on anything outside 200–299. Extend the
+passthrough so 304 reaches `build_page`, which returns an empty `Page`:
+
+```ruby
+return if (200..299).cover?(env.status) || env.status == 304
+```
+
+No exception, no flag — an empty page after `modified_since:` is
+intentionally indistinguishable from an empty filter result.
+
+### 9. Breaking-change surface
+
+- Every list method returns `Page`, not `Array`.
+- `Page` includes `Enumerable` + `size`, `empty?`, `to_a` — `.each`, `.map`,
+  `.first`, `.count`, `.select`, `.find` keep working.
+- Breaks: `<<`, `[0..2]`, `push`, in-place mutation, `JSON.dump(page)`,
+  `is_a?(Array)` checks. Fix: `.to_a`.
+- `Resource.from_response` unchanged; Page construction lives in the client.
+
+## Files
+
+### Create
+
+- `lib/xero_kiwi/page.rb`
+- `lib/xero_kiwi/query.rb` (autoloads the compilers)
+- `lib/xero_kiwi/query/filter.rb`
+- `lib/xero_kiwi/query/order.rb`
+- `spec/xero_kiwi/page_spec.rb`
+- `spec/xero_kiwi/query/filter_spec.rb`
+- `spec/xero_kiwi/query/order_spec.rb`
+- `docs/querying.md`
+
+### Modify
+
+- `lib/xero_kiwi.rb` — require new files.
+- `lib/xero_kiwi/accounting/resource.rb` — `query:` kwarg + `query_fields`
+  class method honouring `identity_attributes`; share `resolve_class`.
+- `lib/xero_kiwi/accounting/hydrator.rb` — use the shared `resolve_class`.
+- `lib/xero_kiwi/accounting/{contact,invoice,credit_note,payment,prepayment,overpayment,user,branding_theme,contact_group}.rb`
+  — annotate queryable attributes.
+- `lib/xero_kiwi/client.rb` — add `list_request` + `build_page`, rewrite the
+  9 list methods, add `each_*` helpers, let 304 through `ResponseHandler`.
+- `lib/xero_kiwi/version.rb` — bump to `0.3.0`.
+- `CHANGELOG.md` — **Breaking** (Page return type), **Added** (query params,
+  `each_*`, `modified_since`).
+- `README.md` — teaser + link to `docs/querying.md`.
+- `docs/accounting/*.md` — short "Query options" section per resource.
+- `spec/xero_kiwi/accounting/*_spec.rb` — `query_fields` assertions per
+  listable resource.
+- `spec/xero_kiwi/client_spec.rb` — new contexts per list method; VCR
+  cassettes for filtered/paged calls; WebMock stubs for 304 paths.
+- `llms-full.txt` — regenerate.
+
+## Testing strategy
+
+- **Filter / Order compilers:** pure unit tests, no HTTP. Table-driven
+  `{input, fields, expected}` covering scalar eq, Array (IN), Range, nested
+  Hash, raw String passthrough, unknown-key raises, per-type literal
+  formatting.
+- **`query_fields` mixin logic:** declare a throwaway resource with and
+  without `identity`; confirm the merged map contains identity + explicit
+  `query: true` attributes and nothing else.
+- **Page:** Enumerable delegation, pagination envelope parsing, fallback
+  when envelope absent, 304-empty behaviour.
+- **Client integration:** WebMock stubs asserting exact URL and headers;
+  one VCR cassette per listable resource for filtered + paged calls; one
+  WebMock stub per resource for 304; `each_invoice` lazy test with stubbed
+  pages 1..3 where page 3 short-circuits empty.
+
+## Verification
+
+```sh
+bundle exec rspec                               # full suite green
+bundle exec rspec spec/xero_kiwi/query          # new compiler specs
+bundle exec rspec spec/xero_kiwi/client_spec.rb # integration
+bundle exec rubocop                             # style clean
+bundle exec rake llms:check                     # docs in sync
+```
+
+Smoke test:
+
+```ruby
+client = XeroKiwi::Client.new(access_token: ENV.fetch("XERO_TOKEN"))
+
+page = client.invoices(
+  tenant,
+  where: { status: "AUTHORISED", contact: { contact_id: "abc-123" } },
+  order: { date: :desc },
+  page:  1
+)
+
+client.each_invoice(tenant, where: { status: "AUTHORISED" }).first(250).count
+client.invoices(tenant, modified_since: 1.day.ago).empty?
+```
+
+## Execution order
+
+1. Extend the DSL: `query:` + `query_fields` + shared `resolve_class`.
+2. Annotate the 9 listable resources.
+3. Add `Query::Filter` / `Query::Order` compilers + specs.
+4. Add `Page` + specs.
+5. Let 304 through `ResponseHandler`.
+6. Add `list_request` + `build_page` on the client; rewrite the 9 list
+   methods.
+7. Add the 9 `each_*` helpers.
+8. Write `docs/querying.md`, update per-resource docs + README.
+9. Bump version, update changelog, regenerate `llms-full.txt`.
+10. Run full suite + rubocop between stages.

data/docs/querying.md

@@ -0,0 +1,199 @@
+# Querying
+
+Every accounting list endpoint supports four optional query-time features:
+
+- **`where:`** — filter expressions
+- **`order:`** — sorting
+- **`page:`** — pagination
+- **`modified_since:`** — conditional GET via `If-Modified-Side` header
+
+```ruby
+page = client.invoices(
+  tenant,
+  where: { status: "AUTHORISED", date: Date.new(2026, 1, 1)..Date.new(2026, 4, 1) },
+  order: { date: :desc },
+  page:  1
+)
+
+page.size          # => 100
+page.page          # => 1
+page.page_size     # => 100
+page.each { |invoice| … }
+```
+
+## Return type: `XeroKiwi::Page`
+
+List methods return a `XeroKiwi::Page` — an `Enumerable`-backed wrapper
+exposing items plus pagination metadata:
+
+```ruby
+page = client.invoices(tenant)
+
+page.each   { |inv| … }   # Enumerable
+page.map    { |inv| … }   # Enumerable
+page.first                # first item
+page.size                 # 100
+page.empty?               # false
+page.to_a                 # raw Array
+
+page.page         # which page number was returned
+page.page_size    # how many items per page (Xero's default is 100)
+page.item_count   # how many items are on this page
+page.total_count  # total item count across all pages (when Xero reports it)
+```
+
+Because `Page` includes `Enumerable` plus `size` / `empty?` / `to_a`, the
+common idioms (`.map`, `.select`, `.first`, `.count`) keep working. Callers
+that need raw `Array` behaviour (`<<`, slicing, `JSON.dump`,
+`is_a?(Array)`) call `.to_a`.
+
+## `where:` — filtering
+
+Two shapes are supported.
+
+### Hash (recommended)
+
+Kiwi owns the quoting and literal syntax. Field names are the snake-case
+Ruby attribute names.
+
+```ruby
+client.invoices(tenant, where: { status: "AUTHORISED" })
+# emits: Status=="AUTHORISED"
+
+client.invoices(tenant, where: { status: "AUTHORISED", type: "ACCREC" })
+# joined with &&
+
+client.invoices(tenant, where: { status: %w[AUTHORISED DRAFT] })
+# Array value → IN-semantics: (Status=="AUTHORISED" || Status=="DRAFT")
+
+client.invoices(tenant, where: { date: Date.new(2026, 1, 1)..Date.new(2026, 4, 1) })
+# Range value → Date>=DateTime(2026,1,1) && Date<=DateTime(2026,4,1)
+
+client.invoices(tenant, where: { contact: { contact_id: "abc-123" } })
+# Hash value on a nested object → Contact.ContactID==Guid("abc-123")
+```
+
+Literal formatting per field type (declared in the resource class):
+
+| Type       | Rendered as               |
+|------------|---------------------------|
+| `:guid`    | `Guid("…")`               |
+| `:date`    | `DateTime(y,m,d)` in UTC  |
+| `:string`  | `"…"` (escaped)           |
+| `:enum`    | `"…"` (escaped)           |
+| `:bool`    | `true` / `false`          |
+| `:decimal` | `99.5`                    |
+
+Unknown field names raise `ArgumentError` so typos surface at the call
+site rather than producing broken Xero queries.
+
+### Raw String (escape hatch)
+
+When the hash form can't express something (OR across different fields,
+`LIKE`, `StartsWith`, etc.), pass a raw string — kiwi passes it straight
+through.
+
+```ruby
+client.invoices(
+  tenant,
+  where: 'Status=="AUTHORISED" || Status=="DRAFT"'
+)
+```
+
+Consult Xero's [filter docs][xero-filters] for the full grammar.
+
+[xero-filters]: https://developer.xero.com/documentation/api/accounting/requests-and-responses#retrieving-a-filtered-resource
+
+## `order:` — sorting
+
+Hash (typed) or string (raw passthrough).
+
+```ruby
+client.invoices(tenant, order: { date: :desc })
+# => order=Date DESC
+
+client.invoices(tenant, order: { date: :desc, invoice_number: :asc })
+# => order=Date DESC,InvoiceNumber ASC
+
+client.invoices(tenant, order: "Date DESC")
+# passthrough
+```
+
+## `page:` — pagination
+
+Maps directly to Xero's `page` query param (1-indexed). Xero's page size
+is 100 items for paginated endpoints.
+
+```ruby
+client.invoices(tenant, page: 2).size          # => up to 100
+client.invoices(tenant, page: 2).page_size     # => 100
+client.invoices(tenant, page: 2).item_count    # total-on-this-page
+```
+
+### Walking every page — `each_<resource>`
+
+For incremental syncs or whole-tenant scans, use the `each_*` helpers.
+They take the same kwargs as the list method (minus `page:`), return a
+lazy Enumerator when no block is given, and short-circuit when a short
+page indicates no more data.
+
+```ruby
+client.each_invoice(tenant, where: { status: "AUTHORISED" }) do |invoice|
+  Sync.upsert(invoice)
+end
+
+# Or use the Enumerator:
+client.each_invoice(tenant, order: { date: :desc })
+      .first(250)
+      .map(&:invoice_id)
+```
+
+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`.
+
+## `modified_since:` — incremental sync
+
+Pass a `Time`; kiwi sends it as Xero's `If-Modified-Since` header in RFC
+1123 format.
+
+```ruby
+page = client.invoices(tenant, modified_since: 1.day.ago)
+
+page.each { |invoice| … }
+```
+
+If Xero returns `304 Not Modified`, kiwi returns an empty `Page` — no
+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).
+
+## Combining everything
+
+Mix and match freely:
+
+```ruby
+client.invoices(
+  tenant,
+  where:          { status: "AUTHORISED", contact: { contact_id: "abc-123" } },
+  order:          { date: :desc },
+  page:           1,
+  modified_since: last_sync_at
+)
+```
+
+## What's queryable per resource?
+
+Queryable fields are declared via `query: true` on each resource class's
+`attribute` declarations. Identity fields (`invoice_id`, `contact_id`,
+etc.) are queryable automatically.
+
+You can inspect a resource's queryable fields at runtime:
+
+```ruby
+XeroKiwi::Accounting::Invoice.query_fields.keys
+# => [:invoice_id, :invoice_number, :type, :contact, :date, :due_date,
+#     :status, :updated_date_utc, :reference]
+```
+
+See the per-resource docs under `docs/accounting/` for the canonical list.

data/lib/xero_kiwi/accounting/branding_theme.rb

@@ -12,7 +12,7 @@ module XeroKiwi
       identity    :branding_theme_id
 
       attribute :branding_theme_id, xero: "BrandingThemeID", type: :guid
-      attribute :name,              xero: "Name"
+      attribute :name,              xero: "Name", query: true
       attribute :logo_url,          xero: "LogoUrl"
       attribute :type,              xero: "Type"
       attribute :sort_order,        xero: "SortOrder"

data/lib/xero_kiwi/accounting/contact.rb

@@ -17,12 +17,12 @@ module XeroKiwi
 
       attribute :contact_id,                         xero: "ContactID", type: :guid
       attribute :contact_number,                     xero: "ContactNumber"
-      attribute :account_number,                     xero: "AccountNumber"
-      attribute :contact_status,                     xero: "ContactStatus", type: :enum
-      attribute :name,                               xero: "Name"
-      attribute :first_name,                         xero: "FirstName"
-      attribute :last_name,                          xero: "LastName"
-      attribute :email_address,                      xero: "EmailAddress"
+      attribute :account_number,                     xero: "AccountNumber", query: true
+      attribute :contact_status,                     xero: "ContactStatus", type: :enum, query: true
+      attribute :name,                               xero: "Name", query: true
+      attribute :first_name,                         xero: "FirstName", query: true
+      attribute :last_name,                          xero: "LastName", query: true
+      attribute :email_address,                      xero: "EmailAddress", query: true
       attribute :bank_account_details,               xero: "BankAccountDetails"
       attribute :company_number,                     xero: "CompanyNumber"
       attribute :tax_number,                         xero: "TaxNumber"
@@ -31,10 +31,10 @@ module XeroKiwi
       attribute :accounts_payable_tax_type,          xero: "AccountsPayableTaxType"
       attribute :addresses,                          xero: "Addresses",                      type: :collection, of: Address
       attribute :phones,                             xero: "Phones",                         type: :collection, of: Phone
-      attribute :is_supplier,                        xero: "IsSupplier",                     type: :bool
-      attribute :is_customer,                        xero: "IsCustomer",                     type: :bool
+      attribute :is_supplier,                        xero: "IsSupplier",                     type: :bool, query: true
+      attribute :is_customer,                        xero: "IsCustomer",                     type: :bool, query: true
       attribute :default_currency,                   xero: "DefaultCurrency"
-      attribute :updated_date_utc,                   xero: "UpdatedDateUTC",                 type: :date
+      attribute :updated_date_utc,                   xero: "UpdatedDateUTC",                 type: :date, query: true
       attribute :contact_persons,                    xero: "ContactPersons",                 type: :collection, of: ContactPerson
       attribute :xero_network_key,                   xero: "XeroNetworkKey"
       attribute :merged_to_contact_id,               xero: "MergedToContactID", type: :guid

data/lib/xero_kiwi/accounting/contact_group.rb

@@ -12,8 +12,8 @@ module XeroKiwi
       identity    :contact_group_id
 
       attribute :contact_group_id, xero: "ContactGroupID", type: :guid
-      attribute :name,             xero: "Name"
-      attribute :status,           xero: "Status"
+      attribute :name,             xero: "Name",   query: true
+      attribute :status,           xero: "Status", query: true
       attribute :contacts,         xero: "Contacts", type: :collection, of: Contact, reference: true
 
       def active? = status == "ACTIVE"

data/lib/xero_kiwi/accounting/credit_note.rb

@@ -13,17 +13,17 @@ module XeroKiwi
 
       attribute :credit_note_id,     xero: "CreditNoteID", type: :guid
       attribute :credit_note_number, xero: "CreditNoteNumber"
-      attribute :type,               xero: "Type",             type: :enum
-      attribute :contact,            xero: "Contact",          type: :object, of: Contact, reference: true
-      attribute :date,               xero: "Date",             type: :date
-      attribute :status,             xero: "Status",           type: :enum
+      attribute :type,               xero: "Type",             type: :enum, query: true
+      attribute :contact,            xero: "Contact",          type: :object, of: Contact, reference: true, query: true
+      attribute :date,               xero: "Date",             type: :date, query: true
+      attribute :status,             xero: "Status",           type: :enum, query: true
       attribute :line_amount_types,  xero: "LineAmountTypes"
       attribute :line_items,         xero: "LineItems",        type: :collection, of: LineItem
       attribute :sub_total,          xero: "SubTotal",         type: :decimal
       attribute :total_tax,          xero: "TotalTax",         type: :decimal
       attribute :total,              xero: "Total",            type: :decimal
       attribute :cis_deduction,      xero: "CISDeduction",     type: :decimal
-      attribute :updated_date_utc,   xero: "UpdatedDateUTC",   type: :date
+      attribute :updated_date_utc,   xero: "UpdatedDateUTC",   type: :date, query: true
       attribute :currency_code,      xero: "CurrencyCode"
       attribute :currency_rate,      xero: "CurrencyRate",     type: :decimal
       attribute :fully_paid_on_date, xero: "FullyPaidOnDate",  type: :date