xero-kiwi 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8461f3c23bcec591acd4a6bb875ff08f4bacf67573ae6e1957ad78a268d4c7bb
+  data.tar.gz: 8167dae0e2922d57099b177a3ee182f3728c28dfc45f6fd0a50ae61a50ea0feb
+SHA512:
+  metadata.gz: 1a55d9c5c9022a6fbf7fcc777d8084775d54e464d87008dfa876f234f792f5ec45a427ea55dfef0adb01ee8f1101ef49999206d64e6b8cec63f0a97fec3564dd
+  data.tar.gz: 95b28e21648463606521aff37c8413e7f6a73fa9f731d30098ef757cb480beaa2f1c3da3f588b1b00ca8cf00784dcd5ec9ca2c7853d129b35ed82ddf6bececaa

data/.env.example

@@ -0,0 +1,2 @@
+XERO_ACCESS_TOKEN=xxx
+XERO_TENANT_ID=xxx

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-04-15
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Douglas Greyling
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,89 @@
+# Xero Kiwi
+
+A Ruby wrapper for the [Xero](https://www.xero.com) Accounting API. XeroKiwi handles
+the unglamorous parts of integrating with Xero — OAuth2, token refresh, rate
+limiting, retries — so the rest of your code can focus on the actual business
+problem.
+
+## What's in the box
+
+- **Full OAuth2 authorization-code flow** with PKCE support, CSRF state helpers,
+  and OIDC ID token verification against Xero's JWKS.
+- **Automatic token refresh** with proactive (before expiry) and reactive
+  (on-401) handling, a callback hook for persisting rotated tokens, and a
+  mutex to dedupe concurrent refreshes from multiple threads.
+- **Rate-limit-aware retries** that honour Xero's `Retry-After` header on 429s
+  and back off on transient 5xxs, built on `faraday-retry`.
+- **A discoverable client surface** with explicit error classes for every
+  failure mode (authentication, rate limit, code exchange, ID token verification,
+  CSRF mismatch).
+- **Connection management**: list and disconnect tenants, with token revocation
+  for "disconnect Xero from my app" flows.
+- **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.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "xero-kiwi"
+```
+
+Then run `bundle install`.
+
+XeroKiwi requires Ruby 3.4.1 or newer.
+
+## Quick start
+
+```ruby
+require "xero_kiwi"
+
+# Once you've completed the OAuth flow and have an access token:
+client = XeroKiwi::Client.new(access_token: "ya29...")
+client.connections.each do |connection|
+  puts "#{connection.tenant_name} (#{connection.tenant_type})"
+end
+```
+
+For the full OAuth flow, refresh handling, and everything else, see the docs
+below.
+
+## Documentation
+
+| Doc | What it covers |
+|-----|----------------|
+| [Getting started](docs/getting-started.md) | Installation, the mental model, your first end-to-end request |
+| [Client](docs/client.md) | `XeroKiwi::Client` — every constructor option, request lifecycle, configuration |
+| [Connections](docs/connections.md) | Listing tenants, the `XeroKiwi::Connection` resource, disconnecting tenants |
+| [Contacts](docs/accounting/contact.md) | Listing and fetching contacts, the `XeroKiwi::Accounting::Contact` resource, nested ContactPerson |
+| [Contact Groups](docs/accounting/contact-group.md) | Listing and fetching contact groups, the `XeroKiwi::Accounting::ContactGroup` resource |
+| [Organisation](docs/accounting/organisation.md) | Fetching an organisation, the `XeroKiwi::Accounting::Organisation` resource, nested objects |
+| [Users](docs/accounting/user.md) | Listing and fetching users, the `XeroKiwi::Accounting::User` resource, organisation roles |
+| [Credit Notes](docs/accounting/credit-note.md) | Listing and fetching credit notes, the `XeroKiwi::Accounting::CreditNote` resource |
+| [Invoices](docs/accounting/invoice.md) | Listing and fetching invoices/bills, the `XeroKiwi::Accounting::Invoice` resource |
+| [Payments](docs/accounting/payment.md) | Listing and fetching payments, the `XeroKiwi::Accounting::Payment` resource |
+| [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 |
+| [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 XeroKiwi handles 429s and transient failures, customising the retry policy |
+
+## Status
+
+XeroKiwi is in early development. The API surface for the features documented above
+is stable, but expect new resource methods to be added over time. Breaking
+changes will be called out in the [changelog](CHANGELOG.md).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/douglasgreyling/xero-kiwi.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+# Files included in llms-full.txt, in reading order. Keep README first, then
+# the docs in the same order the README's table of contents lists them.
+LLMS_SOURCE_FILES = %w[
+  README.md
+  docs/getting-started.md
+  docs/client.md
+  docs/oauth.md
+  docs/tokens.md
+  docs/connections.md
+  docs/accounting/contact.md
+  docs/accounting/contact-group.md
+  docs/accounting/organisation.md
+  docs/accounting/user.md
+  docs/accounting/credit-note.md
+  docs/accounting/invoice.md
+  docs/accounting/payment.md
+  docs/accounting/overpayment.md
+  docs/accounting/prepayment.md
+  docs/accounting/branding-theme.md
+  docs/accounting/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
+].freeze
+
+LLMS_FULL_PATH = "llms-full.txt"
+
+# Builds the llms-full.txt content from LLMS_SOURCE_FILES. Pure function:
+# returns a String, doesn't touch the filesystem. Both `llms:build` and
+# `llms:check` use this so the two tasks can never disagree about the
+# expected output.
+def build_llms_full
+  out = +""
+  out << "# XeroKiwi — full documentation\n\n"
+  out << "This file is the complete documentation for the XeroKiwi gem (a Ruby wrapper for the Xero Accounting API), assembled into a single document for LLM consumption. It contains the README and every doc in the docs/ folder, in reading order.\n\n"
+  out << "For the curated index version, see llms.txt in the same directory.\n\n"
+  out << "Source: https://github.com/douglasgreyling/xero-kiwi\n\n"
+  LLMS_SOURCE_FILES.each { |path| append_file_block(out, path) }
+  out
+end
+
+def append_file_block(out, path)
+  separator = "=" * 80
+  out << "\n" << separator << "\n"
+  out << "FILE: #{path}\n"
+  out << separator << "\n\n"
+  out << File.read(path) << "\n"
+end
+
+namespace :llms do
+  desc "Regenerate llms-full.txt from README and docs/"
+  task :build do
+    File.write(LLMS_FULL_PATH, build_llms_full)
+    puts "Wrote #{LLMS_FULL_PATH} (#{File.size(LLMS_FULL_PATH)} bytes, #{LLMS_SOURCE_FILES.size} source files)"
+  end
+
+  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) : ""
+
+    if expected == actual
+      puts "✓ #{LLMS_FULL_PATH} is up to date"
+    else
+      warn "✗ #{LLMS_FULL_PATH} is out of date with README/docs."
+      warn "  Run `bundle exec rake llms:build` and commit the result."
+      exit 1
+    end
+  end
+end
+
+# Top-level convenience alias.
+desc "Regenerate llms-full.txt (alias for llms:build)"
+task llms: "llms:build"
+
+task default: %i[spec rubocop llms:check]

data/docs/accounting/address.md

@@ -0,0 +1,54 @@
+# XeroKiwi::Accounting::Address
+
+A Xero address. Used by [Organisation](organisation.md), and in future by
+Contact and other resources.
+
+> See: [Xero docs — Address types](https://developer.xero.com/documentation/api/accounting/types#addresses)
+
+## Usage
+
+```ruby
+org.addresses.each do |address|
+  puts "#{address.address_type}: #{address.address_line_1}, #{address.city}"
+end
+
+street = org.addresses.find(&:street?)
+```
+
+## Attributes
+
+| Attribute | Type | Notes |
+|-----------|------|-------|
+| `address_type` | `String` | `"POBOX"`, `"STREET"`, or `"DELIVERY"` |
+| `address_line_1` | `String` | Max 500 characters |
+| `address_line_2` | `String` | Max 500 characters |
+| `address_line_3` | `String` | Max 500 characters |
+| `address_line_4` | `String` | Max 500 characters |
+| `city` | `String` | Max 255 characters |
+| `region` | `String` | Max 255 characters |
+| `postal_code` | `String` | Max 50 characters |
+| `country` | `String` | Max 50 characters, letters only |
+| `attention_to` | `String` | Max 255 characters |
+
+## Predicates
+
+```ruby
+address.street?   # address_type == "STREET"
+address.pobox?    # address_type == "POBOX"
+address.delivery? # address_type == "DELIVERY"
+```
+
+Note: `DELIVERY` is read-only via Xero's GET endpoint (if set) and is not
+valid for Contacts — only for Organisations.
+
+## Equality
+
+Two addresses are `==` if all their attributes match. `#hash` is consistent
+with `==`.
+
+## Serialisation
+
+```ruby
+address.to_h
+# => { address_type: "STREET", address_line_1: "123 Main St", ... }
+```

data/docs/accounting/branding-theme.md

@@ -0,0 +1,92 @@
+# Branding Themes
+
+A Xero **branding theme** controls the look and feel of invoices, quotes, and
+other documents — logo, colours, layout. Every organisation has at least one
+(the default "Standard" theme). You need a `tenant_id` from a
+[connection](../connections.md) before you can fetch branding themes.
+
+> See: [Xero docs — Branding Themes](https://developer.xero.com/documentation/api/accounting/brandingthemes)
+
+## Listing branding themes
+
+```ruby
+client = XeroKiwi::Client.new(access_token: "ya29...")
+
+# Pass a tenant ID string…
+themes = client.branding_themes("70784a63-d24b-46a9-a4db-0e70a274b056")
+
+# …or a XeroKiwi::Connection (its tenant_id is used automatically).
+connection = client.connections.first
+themes = client.branding_themes(connection)
+```
+
+`client.branding_themes` hits `GET /api.xro/2.0/BrandingThemes` with the
+`Xero-Tenant-Id` header set to the tenant you specify. It returns an
+`Array<XeroKiwi::Accounting::BrandingTheme>`.
+
+## Fetching a single branding theme
+
+```ruby
+theme = client.branding_theme(tenant_id, "dfe23d27-a3a6-4ef3-a5ca-b9e02b142dde")
+theme.name  # => "Special Projects"
+```
+
+`client.branding_theme` hits `GET /api.xro/2.0/BrandingThemes/{BrandingThemeID}`
+and returns a single `XeroKiwi::Accounting::BrandingTheme`, or `nil` if the
+response is empty.
+
+## The BrandingTheme object
+
+Each `XeroKiwi::Accounting::BrandingTheme` is an immutable value object exposing the
+fields Xero returns:
+
+| Attribute | Type | What it is |
+|-----------|------|------------|
+| `branding_theme_id` | `String` | The unique Xero identifier for the branding theme. |
+| `name` | `String` | The display name (e.g. "Standard", "Special Projects"). |
+| `logo_url` | `String` | The URL of the logo image used on the theme. May be `nil` if no custom logo is set. |
+| `type` | `String` | The document type the theme applies to (always `"INVOICE"`). |
+| `sort_order` | `Integer` | Ranked order of the theme. The default theme has a value of `0`. |
+| `created_date_utc` | `Time` | When the theme was created, parsed as UTC. |
+
+## Equality and hashing
+
+Two branding themes are `==` if they share the same `branding_theme_id`.
+`#hash` is consistent with `==`, so branding themes work as hash keys and in
+sets.
+
+## Date parsing
+
+The `created_date_utc` field uses Xero's .NET JSON timestamp format
+(`/Date(946684800000+0000)/`). XeroKiwi parses both .NET JSON and ISO 8601
+formats transparently — the attribute is always a UTC `Time` object.
+
+## Error behaviour
+
+| HTTP status | Exception | What it usually means |
+|-------------|-----------|------------------------|
+| 200 | (none — returns themes) | Success |
+| 401 | `XeroKiwi::AuthenticationError` | Access token is invalid or expired |
+| 403 | `XeroKiwi::ClientError` | The token doesn't have the required scope |
+| 404 | `XeroKiwi::ClientError` | The branding theme ID doesn't exist in this organisation |
+
+## Common patterns
+
+### Listing all themes for a tenant
+
+```ruby
+client = XeroKiwi::Client.new(access_token: "ya29...")
+
+themes = client.branding_themes(tenant_id)
+themes.each do |theme|
+  puts "#{theme.name} (sort: #{theme.sort_order})"
+end
+```
+
+### Finding the default theme
+
+```ruby
+themes  = client.branding_themes(tenant_id)
+default = themes.find { |t| t.sort_order == 0 }
+puts "Default theme: #{default.name}"
+```

data/docs/accounting/contact-group.md

@@ -0,0 +1,91 @@
+# Contact Groups
+
+A Xero **contact group** is a named collection of contacts — useful for
+organising customers or suppliers into categories like "VIP Customers" or
+"Preferred Suppliers". You need a `tenant_id` from a
+[connection](../connections.md) before you can fetch contact groups.
+
+> See: [Xero docs — Contact Groups](https://developer.xero.com/documentation/api/accounting/contactgroups)
+
+## Listing contact groups
+
+```ruby
+client = XeroKiwi::Client.new(access_token: "ya29...")
+
+# Pass a tenant ID string…
+groups = client.contact_groups("70784a63-d24b-46a9-a4db-0e70a274b056")
+
+# …or a XeroKiwi::Connection (its tenant_id is used automatically).
+connection = client.connections.first
+groups = client.contact_groups(connection)
+```
+
+`client.contact_groups` hits `GET /api.xro/2.0/ContactGroups` with the
+`Xero-Tenant-Id` header set to the tenant you specify. It returns an
+`Array<XeroKiwi::Accounting::ContactGroup>`. Only groups with status `ACTIVE` are
+returned by Xero.
+
+## Fetching a single contact group
+
+```ruby
+group = client.contact_group(tenant_id, "97bbd0e6-ab4d-4117-9304-d90dd4779199")
+group.name      # => "VIP Customers"
+group.contacts  # => [{"ContactID" => "...", "Name" => "Boom FM"}, ...]
+```
+
+`client.contact_group` hits `GET /api.xro/2.0/ContactGroups/{ContactGroupID}`
+and returns a single `XeroKiwi::Accounting::ContactGroup`, or `nil` if the
+response is empty.
+
+The single-group response includes a `contacts` array with the `ContactID` and
+`Name` of each contact in the group. The list response does not include this.
+
+## The ContactGroup object
+
+Each `XeroKiwi::Accounting::ContactGroup` is an immutable value object exposing the
+fields Xero returns:
+
+| Attribute | Type | What it is |
+|-----------|------|------------|
+| `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). |
+| `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
+
+```ruby
+group.active?  # status == "ACTIVE"
+```
+
+## Equality and hashing
+
+Two contact groups are `==` if they share the same `contact_group_id`. `#hash`
+is consistent with `==`, so contact groups work as hash keys and in sets.
+
+## Error behaviour
+
+| HTTP status | Exception | What it usually means |
+|-------------|-----------|------------------------|
+| 200 | (none — returns groups) | Success |
+| 401 | `XeroKiwi::AuthenticationError` | Access token is invalid or expired |
+| 403 | `XeroKiwi::ClientError` | The token doesn't have the required scope |
+| 404 | `XeroKiwi::ClientError` | The contact group ID doesn't exist |
+
+## Common patterns
+
+### Listing all contact groups
+
+```ruby
+groups = client.contact_groups(tenant_id)
+groups.each { |g| puts g.name }
+```
+
+### Fetching members of a group
+
+```ruby
+group = client.contact_group(tenant_id, "97bbd0e6-ab4d-4117-9304-d90dd4779199")
+group.contacts.each do |c|
+  puts "#{c.name} (#{c.contact_id})"
+end
+```

data/docs/accounting/contact.md

@@ -0,0 +1,166 @@
+# Contacts
+
+A Xero **contact** is a person or organisation you do business with — customers,
+suppliers, or both. Contacts carry addresses, phone numbers, payment terms, and
+metadata like tax type defaults. You need a `tenant_id` from a
+[connection](../connections.md) before you can fetch contacts.
+
+> See: [Xero docs — Contacts](https://developer.xero.com/documentation/api/accounting/contacts)
+
+## Listing contacts
+
+```ruby
+client = XeroKiwi::Client.new(access_token: "ya29...")
+
+# Pass a tenant ID string…
+contacts = client.contacts("70784a63-d24b-46a9-a4db-0e70a274b056")
+
+# …or a XeroKiwi::Connection (its tenant_id is used automatically).
+connection = client.connections.first
+contacts = client.contacts(connection)
+```
+
+`client.contacts` hits `GET /api.xro/2.0/Contacts` with the `Xero-Tenant-Id`
+header set to the tenant you specify. It returns an
+`Array<XeroKiwi::Accounting::Contact>`.
+
+## Fetching a single contact
+
+```ruby
+contact = client.contact(tenant_id, "bd2270c3-8706-4c11-9cfb-000b551c3f51")
+contact.name  # => "ABC Limited"
+```
+
+`client.contact` hits `GET /api.xro/2.0/Contacts/{ContactID}` and returns a
+single `XeroKiwi::Accounting::Contact`, or `nil` if the response is empty.
+
+Fetching a single contact returns additional fields that are not included in the
+list response (e.g. `contact_persons`, `payment_terms`, `website`).
+
+## The Contact object
+
+Each `XeroKiwi::Accounting::Contact` is an immutable value object. The fields below
+are always returned on list and single-contact responses:
+
+| Attribute | Type | What it is |
+|-----------|------|------------|
+| `contact_id` | `String` | The unique Xero identifier for the contact. |
+| `contact_number` | `String` | External system identifier (read-only in Xero UI). |
+| `account_number` | `String` | A user-defined account number. |
+| `contact_status` | `String` | `"ACTIVE"` or `"ARCHIVED"`. |
+| `name` | `String` | Full name of the contact or organisation. |
+| `first_name` | `String` | First name of the contact person. |
+| `last_name` | `String` | Last name of the contact person. |
+| `email_address` | `String` | Email address of the contact person. |
+| `bank_account_details` | `String` | Bank account number. |
+| `company_number` | `String` | Company registration number (max 50 chars). |
+| `tax_number` | `String` | ABN / GST / VAT / Tax ID Number. |
+| `tax_number_type` | `String` | Regional type of tax number (e.g. `"ABN"`). |
+| `accounts_receivable_tax_type` | `String` | Default AR invoice tax type. |
+| `accounts_payable_tax_type` | `String` | Default AP invoice tax type. |
+| `addresses` | `Array<XeroKiwi::Accounting::Address>` | The contact's addresses. See [Address](address.md). |
+| `phones` | `Array<XeroKiwi::Accounting::Phone>` | The contact's phone numbers. See [Phone](phone.md). |
+| `is_supplier` | `Boolean` | Whether the contact has any AP invoices. |
+| `is_customer` | `Boolean` | Whether the contact has any AR invoices. |
+| `default_currency` | `String` | Default currency code (e.g. `"NZD"`). |
+| `updated_date_utc` | `Time` | When the contact was last modified, parsed as UTC. |
+
+### Additional fields (single contact / paginated responses only)
+
+| Attribute | Type | What it is |
+|-----------|------|------------|
+| `contact_persons` | `Array<XeroKiwi::Accounting::ContactPerson>` | Up to 5 contact people. See [ContactPerson](#the-contactperson-object). |
+| `xero_network_key` | `String` | Xero network key for the contact. |
+| `merged_to_contact_id` | `String` | ID of the destination contact if merged. |
+| `sales_default_account_code` | `String` | Default sales account code. |
+| `purchases_default_account_code` | `String` | Default purchases account code. |
+| `sales_tracking_categories` | `Array<Hash>` | Default sales tracking categories (raw). |
+| `purchases_tracking_categories` | `Array<Hash>` | Default purchases tracking categories (raw). |
+| `sales_default_line_amount_type` | `String` | `"INCLUSIVE"`, `"EXCLUSIVE"`, or `"NONE"`. |
+| `purchases_default_line_amount_type` | `String` | `"INCLUSIVE"`, `"EXCLUSIVE"`, or `"NONE"`. |
+| `tracking_category_name` | `String` | Tracking category name. |
+| `tracking_option_name` | `String` | Tracking option name. |
+| `payment_terms` | `XeroKiwi::Accounting::PaymentTerms` | Default payment terms. See [PaymentTerms](payment-terms.md). |
+| `contact_groups` | `Array<Hash>` | Contact groups the contact belongs to (raw). |
+| `website` | `String` | Website URL. |
+| `branding_theme` | `Hash` | Default branding theme (raw). |
+| `batch_payments` | `Hash` | Batch payment details (raw). |
+| `discount` | `Float` | Default discount rate. |
+| `balances` | `Hash` | Outstanding and overdue AR/AP balances (raw). |
+| `has_attachments` | `Boolean` | Whether the contact has attachments. |
+
+## The ContactPerson object
+
+Each `XeroKiwi::Accounting::ContactPerson` is an immutable value object:
+
+| Attribute | Type | What it is |
+|-----------|------|------------|
+| `first_name` | `String` | First name. |
+| `last_name` | `String` | Last name. |
+| `email_address` | `String` | Email address. |
+| `include_in_emails` | `Boolean` | Whether to include on invoice emails. |
+
+With a predicate: `contact_person.include_in_emails?`
+
+## Predicates
+
+```ruby
+contact.reference?  # true if this is a lightweight reference from another resource
+contact.supplier?   # is_supplier == true
+contact.customer?   # is_customer == true
+contact.active?     # contact_status == "ACTIVE"
+contact.archived?   # contact_status == "ARCHIVED"
+```
+
+### Contact references
+
+When a contact appears nested inside another resource (e.g. an Invoice, Prepayment,
+or CreditNote), it is wrapped as a `XeroKiwi::Accounting::Contact` with `reference?`
+returning `true`. Reference contacts typically carry only a subset of fields (like
+`contact_id` and `name`) — other fields will be `nil`.
+
+```ruby
+invoice = client.invoice(tenant_id, invoice_id)
+invoice.contact.name          # => "City Agency"
+invoice.contact.reference?    # => true
+
+# Fetch the full contact if you need all fields:
+full_contact = client.contact(tenant_id, invoice.contact.contact_id)
+full_contact.reference?       # => false
+full_contact.email_address    # => "a.dutchess@abclimited.com"
+```
+
+## Equality and hashing
+
+Two contacts are `==` if they share the same `contact_id`. `#hash` is consistent
+with `==`, so contacts work as hash keys and in sets.
+
+## Error behaviour
+
+| HTTP status | Exception | What it usually means |
+|-------------|-----------|------------------------|
+| 200 | (none — returns contacts) | Success |
+| 401 | `XeroKiwi::AuthenticationError` | Access token is invalid or expired |
+| 403 | `XeroKiwi::ClientError` | The token doesn't have the required scope |
+| 404 | `XeroKiwi::ClientError` | The contact ID doesn't exist in this organisation |
+
+## Common patterns
+
+### Listing all customers
+
+```ruby
+contacts = client.contacts(tenant_id)
+customers = contacts.select(&:customer?)
+customers.each { |c| puts "#{c.name} (#{c.default_currency})" }
+```
+
+### Fetching a contact with full details
+
+```ruby
+# The list response omits some fields. Fetch individually for full details.
+contact = client.contact(tenant_id, "bd2270c3-8706-4c11-9cfb-000b551c3f51")
+puts contact.website
+contact.contact_persons.each do |person|
+  puts "  #{person.first_name} #{person.last_name} — #{person.email_address}"
+end
+```