xero-kiwi 0.1.0

data/docs/accounting/prepayment.md

@@ -0,0 +1,111 @@
+# Prepayments
+
+A Xero **prepayment** is a payment received or made in advance of an invoice.
+Prepayments are created via the BankTransactions endpoint and refunded via the
+Payments endpoint. This resource lets you retrieve prepayments and their
+allocations. You need a `tenant_id` from a [connection](../connections.md)
+before you can fetch prepayments.
+
+> See: [Xero docs — Prepayments](https://developer.xero.com/documentation/api/accounting/prepayments)
+
+## Listing prepayments
+
+```ruby
+client = XeroKiwi::Client.new(access_token: "ya29...")
+
+# Pass a tenant ID string…
+prepayments = client.prepayments("70784a63-d24b-46a9-a4db-0e70a274b056")
+
+# …or a XeroKiwi::Connection (its tenant_id is used automatically).
+connection = client.connections.first
+prepayments = client.prepayments(connection)
+```
+
+`client.prepayments` hits `GET /api.xro/2.0/Prepayments` with the
+`Xero-Tenant-Id` header set to the tenant you specify. It returns an
+`Array<XeroKiwi::Accounting::Prepayment>`.
+
+## Fetching a single prepayment
+
+```ruby
+prepayment = client.prepayment(tenant_id, "aea95d78-ea48-456b-9b08-6bc012600072")
+prepayment.total  # => "100.00"
+```
+
+`client.prepayment` hits `GET /api.xro/2.0/Prepayments/{PrepaymentID}` and
+returns a single `XeroKiwi::Accounting::Prepayment`, or `nil` if the response is
+empty.
+
+## The Prepayment object
+
+Each `XeroKiwi::Accounting::Prepayment` is an immutable value object exposing the
+fields Xero returns:
+
+| Attribute | Type | What it is |
+|-----------|------|------------|
+| `prepayment_id` | `String` | The unique Xero identifier. |
+| `type` | `String` | `"RECEIVE-PREPAYMENT"` or `"SPEND-PREPAYMENT"`. |
+| `contact` | `XeroKiwi::Accounting::Contact` | The contact (reference — use `contact.reference?` to check). See [Contacts](contact.md). |
+| `date` | `Time` | The date the prepayment was created, parsed as UTC. |
+| `status` | `String` | e.g. `"AUTHORISED"`, `"PAID"`, `"VOIDED"`. |
+| `line_amount_types` | `String` | `"Inclusive"`, `"Exclusive"`, or `"NoTax"`. |
+| `line_items` | `Array<XeroKiwi::Accounting::LineItem>` | The line items. See [LineItem](#the-lineitem-object). |
+| `sub_total` | `String` | The subtotal excluding taxes. |
+| `total_tax` | `String` | The total tax amount. |
+| `total` | `String` | The total (subtotal + total tax). |
+| `updated_date_utc` | `Time` | When the prepayment was last modified, parsed as UTC. |
+| `currency_code` | `String` | The currency code (e.g. `"NZD"`). |
+| `currency_rate` | `String` | The currency rate (1.0 for base currency). |
+| `invoice_number` | `String` | The invoice number (for receive prepayments only). |
+| `remaining_credit` | `String` | The remaining credit balance. |
+| `allocations` | `Array<XeroKiwi::Accounting::Allocation>` | Allocations to invoices. Each allocation has an `invoice` reference. |
+| `payments` | `Array<XeroKiwi::Accounting::Payment>` | Payment records (references). See [Payments](payment.md). |
+| `has_attachments` | `Boolean` | Whether the prepayment has attachments. |
+| `fully_paid_on_date` | `Time` | When the prepayment was fully allocated, parsed as UTC. |
+
+## The LineItem object
+
+Each `XeroKiwi::Accounting::LineItem` is an immutable value object shared across
+documents (prepayments, invoices, etc.):
+
+| Attribute | Type | What it is |
+|-----------|------|------------|
+| `description` | `String` | Line item description. |
+| `quantity` | `Float` | Quantity. |
+| `unit_amount` | `Float` | Unit amount. |
+| `account_code` | `String` | The account code. |
+| `tax_type` | `String` | The tax type override. |
+| `tax_amount` | `Float` | The calculated tax amount. |
+| `line_amount` | `Float` | The line total. |
+| `tracking` | `Array<Hash>` | Tracking categories (raw, max 2 per line). |
+
+## Predicates
+
+```ruby
+prepayment.receive?  # type == "RECEIVE-PREPAYMENT"
+prepayment.spend?    # type == "SPEND-PREPAYMENT"
+```
+
+## Equality and hashing
+
+Two prepayments are `==` if they share the same `prepayment_id`. `#hash` is
+consistent with `==`, so prepayments work as hash keys and in sets.
+
+## Error behaviour
+
+| HTTP status | Exception | What it usually means |
+|-------------|-----------|------------------------|
+| 200 | (none — returns prepayments) | 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 prepayment ID doesn't exist |
+
+## Common patterns
+
+### Listing prepayments with remaining credit
+
+```ruby
+prepayments = client.prepayments(tenant_id)
+with_credit = prepayments.select { |p| p.remaining_credit.to_f > 0 }
+with_credit.each { |p| puts "#{p.prepayment_id}: #{p.remaining_credit} remaining" }
+```

data/docs/accounting/user.md

@@ -0,0 +1,109 @@
+# Users
+
+Xero **users** are the people who have access to a Xero organisation. The Users
+endpoint is read-only — you can list and fetch users, but not create or modify
+them through the API. You need a `tenant_id` from a
+[connection](../connections.md) before you can fetch users.
+
+> See: [Xero docs — Users](https://developer.xero.com/documentation/api/accounting/users)
+
+## Listing users
+
+```ruby
+client = XeroKiwi::Client.new(access_token: "ya29...")
+
+# Pass a tenant ID string…
+users = client.users("70784a63-d24b-46a9-a4db-0e70a274b056")
+
+# …or a XeroKiwi::Connection (its tenant_id is used automatically).
+connection = client.connections.first
+users = client.users(connection)
+```
+
+`client.users` hits `GET /api.xro/2.0/Users` with the `Xero-Tenant-Id` header
+set to the tenant you specify. It returns an `Array<XeroKiwi::Accounting::User>`.
+
+## Fetching a single user
+
+```ruby
+user = client.user(tenant_id, "7cf47fe2-c3dd-4c6b-9895-7ba767ba529c")
+user.email_address  # => "john.smith@mail.com"
+```
+
+`client.user` hits `GET /api.xro/2.0/Users/{UserID}` and returns a single
+`XeroKiwi::Accounting::User`, or `nil` if the response is empty.
+
+## The User object
+
+Each `XeroKiwi::Accounting::User` is an immutable value object exposing the fields
+Xero returns:
+
+| Attribute | Type | What it is |
+|-----------|------|------------|
+| `user_id` | `String` | The unique Xero identifier for the user. |
+| `email_address` | `String` | The user's email address. |
+| `first_name` | `String` | The user's first name. |
+| `last_name` | `String` | The user's last name. |
+| `updated_date_utc` | `Time` | When the user was last modified, parsed as UTC. |
+| `is_subscriber` | `Boolean` | Whether the user is the subscriber (billing owner). |
+| `organisation_role` | `String` | The user's role — see [Organisation roles](#organisation-roles) below. |
+
+## Predicates
+
+```ruby
+user.subscriber?  # is_subscriber == true
+```
+
+## Organisation roles
+
+| Role | Description |
+|------|-------------|
+| `READONLY` | Read-only access |
+| `INVOICEONLY` | Invoice-only access |
+| `STANDARD` | Standard user |
+| `FINANCIALADVISER` | Financial adviser role |
+| `MANAGEDCLIENT` | Managed client (Partner Edition only) |
+| `CASHBOOKCLIENT` | Cashbook client (Partner Edition only) |
+| `ADMIN` | Full admin access |
+
+## Equality and hashing
+
+Two users are `==` if they share the same `user_id`. `#hash` is consistent with
+`==`, so users work as hash keys and in sets.
+
+## Date parsing
+
+The `updated_date_utc` field uses Xero's .NET JSON timestamp format
+(`/Date(1516230549137+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 users) | 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 user ID doesn't exist in this organisation |
+
+## Common patterns
+
+### Listing all users for each tenant
+
+```ruby
+client = XeroKiwi::Client.new(access_token: "ya29...")
+
+client.connections.each do |conn|
+  users = client.users(conn)
+  puts "#{conn.tenant_name}: #{users.size} users"
+  users.each { |u| puts "  #{u.first_name} #{u.last_name} (#{u.organisation_role})" }
+end
+```
+
+### Finding the subscriber
+
+```ruby
+users = client.users(tenant_id)
+subscriber = users.find(&:subscriber?)
+puts "Billing owner: #{subscriber.email_address}" if subscriber
+```

data/docs/client.md

@@ -0,0 +1,174 @@
+# XeroKiwi::Client
+
+`XeroKiwi::Client` is the entry point for talking to Xero's accounting API. You
+construct one with credentials and call resource methods on it. The client
+holds the OAuth token state, knows how to refresh it, and translates HTTP
+errors into XeroKiwi exceptions.
+
+## Constructing a client
+
+Two common shapes:
+
+```ruby
+# Simple — access token only, no refresh capability.
+client = XeroKiwi::Client.new(access_token: "ya29...")
+
+# Full — refresh-capable, with persistence callback.
+client = XeroKiwi::Client.new(
+  access_token:     credential.access_token,
+  refresh_token:    credential.refresh_token,
+  expires_at:       credential.expires_at,
+  client_id:        ENV.fetch("XERO_CLIENT_ID"),
+  client_secret:    ENV.fetch("XERO_CLIENT_SECRET"),
+  on_token_refresh: ->(token) { credential.update!(token.to_h) }
+)
+```
+
+The simple form is fine for one-off scripts and quick experiments. For
+anything long-running, use the full form so the client can refresh tokens for
+you. See [Tokens](tokens.md) for the full refresh story.
+
+## Constructor options
+
+| Option | Type | Required | Default | Purpose |
+|--------|------|----------|---------|---------|
+| `access_token:` | `String` | Yes | — | The OAuth2 bearer token used on every API call. |
+| `refresh_token:` | `String` | No | `nil` | The refresh token. Required if you want the client to refresh expired access tokens. |
+| `expires_at:` | `Time` | No | `nil` | When the access token expires. Used by the proactive refresh check. If `nil`, the client falls back to reactive refresh on 401. |
+| `client_id:` | `String` | No | `nil` | Your Xero app's client ID. Required for refresh. |
+| `client_secret:` | `String` | No | `nil` | Your Xero app's client secret. Required for refresh. |
+| `on_token_refresh:` | `Proc` / lambda | No | `nil` | Called with the new `XeroKiwi::Token` whenever a refresh happens. Use this to persist the rotated token back to storage. |
+| `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. |
+
+## What the client gives you
+
+| Method | Returns | Purpose |
+|--------|---------|---------|
+| `client.connections` | `Array<XeroKiwi::Connection>` | Fetch the tenants this token is authorised against. See [Connections](connections.md). |
+| `client.contacts(tenant_id_or_connection)` | `Array<XeroKiwi::Accounting::Contact>` | Fetch the contacts for a tenant. See [Contacts](accounting/contact.md). |
+| `client.contact(tenant_id_or_connection, contact_id)` | `XeroKiwi::Accounting::Contact` | Fetch a single contact by ID. See [Contacts](accounting/contact.md). |
+| `client.contact_groups(tenant_id_or_connection)` | `Array<XeroKiwi::Accounting::ContactGroup>` | Fetch the contact groups for a tenant. See [Contact Groups](accounting/contact-group.md). |
+| `client.contact_group(tenant_id_or_connection, contact_group_id)` | `XeroKiwi::Accounting::ContactGroup` | Fetch a single contact group by ID. See [Contact Groups](accounting/contact-group.md). |
+| `client.organisation(tenant_id_or_connection)` | `XeroKiwi::Accounting::Organisation` | Fetch the organisation for a tenant. See [Organisation](accounting/organisation.md). |
+| `client.users(tenant_id_or_connection)` | `Array<XeroKiwi::Accounting::User>` | Fetch the users for a tenant. See [Users](accounting/user.md). |
+| `client.user(tenant_id_or_connection, user_id)` | `XeroKiwi::Accounting::User` | Fetch a single user by ID. See [Users](accounting/user.md). |
+| `client.credit_notes(tenant_id_or_connection)` | `Array<XeroKiwi::Accounting::CreditNote>` | Fetch the credit notes for a tenant. See [Credit Notes](accounting/credit-note.md). |
+| `client.credit_note(tenant_id_or_connection, credit_note_id)` | `XeroKiwi::Accounting::CreditNote` | Fetch a single credit note by ID. See [Credit Notes](accounting/credit-note.md). |
+| `client.invoices(tenant_id_or_connection)` | `Array<XeroKiwi::Accounting::Invoice>` | Fetch the invoices for a tenant. See [Invoices](accounting/invoice.md). |
+| `client.invoice(tenant_id_or_connection, invoice_id)` | `XeroKiwi::Accounting::Invoice` | Fetch a single invoice by ID. See [Invoices](accounting/invoice.md). |
+| `client.online_invoice_url(tenant_id_or_connection, invoice_id)` | `String` | Fetch the online invoice URL for a sales invoice. See [Invoices](accounting/invoice.md). |
+| `client.payments(tenant_id_or_connection)` | `Array<XeroKiwi::Accounting::Payment>` | Fetch the payments for a tenant. See [Payments](accounting/payment.md). |
+| `client.payment(tenant_id_or_connection, payment_id)` | `XeroKiwi::Accounting::Payment` | Fetch a single payment by ID. See [Payments](accounting/payment.md). |
+| `client.overpayments(tenant_id_or_connection)` | `Array<XeroKiwi::Accounting::Overpayment>` | Fetch the overpayments for a tenant. See [Overpayments](accounting/overpayment.md). |
+| `client.overpayment(tenant_id_or_connection, overpayment_id)` | `XeroKiwi::Accounting::Overpayment` | Fetch a single overpayment by ID. See [Overpayments](accounting/overpayment.md). |
+| `client.prepayments(tenant_id_or_connection)` | `Array<XeroKiwi::Accounting::Prepayment>` | Fetch the prepayments for a tenant. See [Prepayments](accounting/prepayment.md). |
+| `client.prepayment(tenant_id_or_connection, prepayment_id)` | `XeroKiwi::Accounting::Prepayment` | Fetch a single prepayment by ID. See [Prepayments](accounting/prepayment.md). |
+| `client.branding_themes(tenant_id_or_connection)` | `Array<XeroKiwi::Accounting::BrandingTheme>` | Fetch the branding themes for a tenant. See [Branding Themes](accounting/branding-theme.md). |
+| `client.branding_theme(tenant_id_or_connection, branding_theme_id)` | `XeroKiwi::Accounting::BrandingTheme` | Fetch a single branding theme by ID. See [Branding Themes](accounting/branding-theme.md). |
+| `client.delete_connection(id_or_connection)` | `true` | Disconnect a tenant. See [Connections](connections.md). |
+| `client.token` | `XeroKiwi::Token` | The current in-memory token. Inspect expiry, refreshability, etc. |
+| `client.token.expired?` | `Boolean` | True if `expires_at` is in the past. |
+| `client.token.expiring_soon?(within: 60)` | `Boolean` | True if `expires_at` falls inside the window. |
+| `client.token.refreshable?` | `Boolean` | True if the token has a refresh token attached. |
+| `client.can_refresh?` | `Boolean` | True if the client was constructed with both refresh credentials AND the current token has a `refresh_token`. |
+| `client.refresh_token!` | `XeroKiwi::Token` | Force a refresh now. Returns the new token. Raises `XeroKiwi::TokenRefreshError` if there's no refresh capability. |
+| `client.revoke_token!` | `true` | Revoke the current refresh token at Xero. Use for logout / "disconnect Xero" flows. See [Tokens](tokens.md). |
+
+## The request lifecycle
+
+Every API call goes through `with_authenticated_request`, which wraps the
+actual HTTP call with two layers of token-freshness handling:
+
+1. **Proactive refresh.** Before the request fires, if the token is expiring
+   within the default window (60 seconds) AND the client has refresh
+   capability, the client refreshes the token first. This covers the common
+   case of "the token I loaded from the database is about to expire."
+2. **The actual HTTP call** — including all the retry behaviour described
+   in [retries and rate limits](retries-and-rate-limits.md).
+3. **Reactive refresh on 401.** If the request returns a 401 anyway (token
+   was revoked early, our clock is wrong, etc.), the client refreshes once
+   and retries the request. A `retried` flag prevents an infinite loop —
+   the second 401 raises `XeroKiwi::AuthenticationError`.
+
+If you constructed the client without refresh credentials, both layers are
+skipped: a 401 raises immediately and you handle it in your own code.
+
+## Custom adapters
+
+XeroKiwi uses Faraday under the hood, so you can swap the HTTP adapter for
+testing or for connection pooling:
+
+```ruby
+client = XeroKiwi::Client.new(
+  access_token: "...",
+  adapter:      :net_http_persistent
+)
+```
+
+For tests:
+
+```ruby
+require "faraday"
+
+client = XeroKiwi::Client.new(
+  access_token: "...",
+  adapter:      [:test, Faraday::Adapter::Test::Stubs.new] # or use webmock
+)
+```
+
+The adapter is also passed through to the internal `TokenRefresher`, so a
+test adapter swallows refresh requests too.
+
+## Customising the retry policy
+
+`retry_options:` is merged into XeroKiwi's defaults, so you only need to specify
+overrides:
+
+```ruby
+client = XeroKiwi::Client.new(
+  access_token: "...",
+  retry_options: {
+    max:      8,        # try up to 8 retries (default: 4)
+    interval: 1.0       # initial wait of 1 second (default: 0.5)
+  }
+)
+```
+
+See [retries and rate limits](retries-and-rate-limits.md) for the full
+configuration reference and which keys you can override.
+
+## Thread safety
+
+A single client can safely be shared across threads. The internals are
+thread-safe in two specific ways:
+
+- **Token refresh** is protected by a `Mutex` with a double-check pattern. If
+  two threads both notice the token is expiring at the same time, only one
+  will actually call Xero's refresh endpoint; the other waits, then sees the
+  fresh token and proceeds.
+- **Faraday connections** are reused across threads (Faraday's adapters are
+  designed for this).
+
+There's one caveat: **manual `refresh_token!` calls don't double-check.** If
+you call `client.refresh_token!` from two threads simultaneously, both will
+hit Xero, and the second will fail because the refresh token rotated. The
+automatic path (`ensure_fresh_token!` inside `with_authenticated_request`)
+deduplicates correctly.
+
+If you're sharing a client across multiple processes (e.g. a Sidekiq pool
+spread across machines), the in-process mutex doesn't help you. See
+[Tokens](tokens.md#multi-process-refresh) for the multi-process gotcha and
+how to handle it.
+
+## What the client deliberately does NOT do
+
+- **Persist anything.** The client never writes to your database, session,
+  or filesystem. The `on_token_refresh` callback is your hook for that.
+- **Manage OAuth state.** The client doesn't know about CSRF state or PKCE
+  verifiers. Use [`XeroKiwi::OAuth`](oauth.md) for the auth-code flow.
+- **Validate scopes.** If your token doesn't have the right scope for an
+  endpoint, you'll get a 403 from Xero. The client surfaces it as a
+  `XeroKiwi::ClientError`; it's the caller's job to know what scopes they
+  asked for.

data/docs/connections.md

@@ -0,0 +1,166 @@
+# Connections
+
+In Xero's terminology, a **connection** is one tenant (organisation or
+practice) that an access token has been authorised against. A single user can
+authorise your app against multiple tenants in one OAuth flow, and each one
+becomes a separate connection.
+
+This is the first thing you'll typically call after exchanging an OAuth code
+for tokens — you need the `tenant_id` from a connection before you can hit
+any of the actual accounting endpoints.
+
+> See: [Xero docs — managing connections](https://developer.xero.com/documentation/best-practices/managing-connections/connections)
+
+## Listing connections
+
+```ruby
+client = XeroKiwi::Client.new(access_token: "ya29...")
+
+client.connections.each do |connection|
+  puts "#{connection.tenant_name} — #{connection.tenant_id}"
+end
+```
+
+`client.connections` returns an `Array<XeroKiwi::Connection>`. The array is empty
+if the user authorised your app but didn't pick any tenants (rare, but
+possible). The endpoint doesn't take any filtering parameters — Xero returns
+everything the token has access to.
+
+## The Connection object
+
+Each `XeroKiwi::Connection` is an immutable value object exposing the fields Xero
+returns:
+
+| Attribute | Type | What it is |
+|-----------|------|------------|
+| `id` | `String` | The **connection** UUID. This is what you pass to `delete_connection` to disconnect. |
+| `tenant_id` | `String` | The **tenant** UUID. This is what you put in the `Xero-Tenant-Id` header on every accounting API call. |
+| `tenant_type` | `String` | Either `"ORGANISATION"` or `"PRACTICE"`. |
+| `tenant_name` | `String` | The display name (e.g. "Maple Florists Ltd"). |
+| `auth_event_id` | `String` | The OAuth event UUID. Useful for correlating with Xero's audit logs. |
+| `created_date_utc` | `Time` | When the connection was first established, parsed as UTC. |
+| `updated_date_utc` | `Time` | When the connection was last updated, parsed as UTC. |
+
+### `id` vs `tenant_id` — important
+
+These are **different UUIDs**. Get them mixed up and your API calls will
+mysteriously 401.
+
+- `connection.id` is the unique identifier of the *connection record itself*,
+  used for deletion.
+- `connection.tenant_id` is the unique identifier of the *tenant* (the Xero
+  organisation), used in the `Xero-Tenant-Id` header on every accounting
+  request.
+
+## Predicates
+
+```ruby
+connection.organisation? # tenant_type == "ORGANISATION"
+connection.practice?     # tenant_type == "PRACTICE"
+```
+
+## Equality and hashing
+
+Two connections are `==` if they have the same `id`, even if other attributes
+differ. This is convenient for set operations:
+
+```ruby
+old_connections - new_connections # diff by id
+```
+
+`#hash` is consistent with `==`, so connections work as hash keys.
+
+## Date parsing
+
+Xero serialises dates in C# DateTime format and frequently omits the timezone
+marker on values that are documented as UTC (e.g. `"2019-07-09T23:40:30.1833130"`).
+XeroKiwi force-appends a `Z` before parsing so you always get a UTC `Time` back —
+without this, `Time.parse` would silently fall back to local time and you'd
+get the wrong instant.
+
+If you want the raw string Xero sent, the connection's `to_h` only exposes
+the parsed `Time` objects. Reach into the response yourself if you need the
+original strings.
+
+## Disconnecting a tenant
+
+```ruby
+# By id
+client.delete_connection("e1eede29-f875-4a5d-8470-17f6a29a88b1")
+
+# Or by passing the Connection object — its `id` is used
+connection = client.connections.first
+client.delete_connection(connection)
+```
+
+`delete_connection` returns `true` on success and raises on failure. Both
+forms hit `DELETE /connections/:id`.
+
+After a successful delete:
+
+- The named tenant is detached from the access token.
+- **Other tenants** authorised by the same token are *not* affected — only
+  this one connection is gone.
+- Calls that include the deleted `tenant_id` in their `Xero-Tenant-Id` header
+  will start failing with 401.
+
+### Error behaviour
+
+| HTTP status | Exception | What it usually means |
+|-------------|-----------|------------------------|
+| 204 No Content | (none — returns `true`) | Success |
+| 401 | `XeroKiwi::AuthenticationError` | Access token is invalid or expired |
+| 403 | `XeroKiwi::ClientError` | The token doesn't have permission to disconnect this tenant |
+| 404 | `XeroKiwi::ClientError` | The connection ID doesn't exist (or was already deleted) |
+
+A 404 is usually idempotent-friendly — if you're trying to make sure a tenant
+is disconnected, catching `XeroKiwi::ClientError` and ignoring 404s is reasonable:
+
+```ruby
+begin
+  client.delete_connection(id)
+rescue XeroKiwi::ClientError => e
+  raise unless e.status == 404
+end
+```
+
+## Common patterns
+
+### Find a tenant by name
+
+```ruby
+target = client.connections.find { |c| c.tenant_name == "Maple Florists Ltd" }
+target&.tenant_id # use this in subsequent API calls
+```
+
+### Disconnect everything
+
+For "remove Xero from my app" flows where the user wants a full disconnect,
+combine deletion with token revocation:
+
+```ruby
+client.connections.each { |c| client.delete_connection(c) }
+client.revoke_token!
+credential.destroy!
+```
+
+The order matters — once you `revoke_token!`, the access token is dead and
+subsequent `delete_connection` calls will 401. So delete first, then revoke.
+
+(In practice you can skip the per-connection deletes entirely if you're going
+to revoke the token anyway — revoking the refresh token invalidates the
+access token, which detaches all connections at once. The per-connection
+delete is for when you want to disconnect *some* tenants and keep others.)
+
+### Iterating without holding the array
+
+Connections are usually a small list (1-10 entries) so loading them all is
+cheap. But if you only need one:
+
+```ruby
+client.connections.lazy.find { |c| c.tenant_id == target_tenant_id }
+```
+
+The lazy enumerator doesn't help here — `client.connections` already does
+the full HTTP fetch — but it's idiomatic and avoids materialising more than
+you need into local variables.