xero-kiwi 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 122c7e012d619aabdf473185bf0e39e1e04204940d2c6d6b96888d1b6f73b76c
-  data.tar.gz: 2bbb94621f3e417275b1ea326a2e54e50f03083c01991863e2f91a16af5945ea
+  metadata.gz: 5aeae0acf1024528b094ffc690323179bd336c9817bef6a897258b5304f66844
+  data.tar.gz: 2ab0071a933a39e93a10ef7ed7658b354e2043cc753441c65491443fff5e22a2
 SHA512:
-  metadata.gz: 0266fde7e2c101e0533f9e3202ba2871f0a17c170e27ff82dd380448028f608da61f697c3ca08d2a965245125c0987f0a9ddb54ccc01e0a89f47d437fd5aa62d
-  data.tar.gz: 93e24cd65f1ebf4f7dec4a97fe17d352fb7f6d2ed95f22e6466f403f9997859d16d51569614736c9a1ae77351f94b306dd8304b8f368f465d7c040f2eebb4514
+  metadata.gz: 4b4c8cdd72c20abdd5d377edbb125b53466d6ebb907a8f2949fec962d20d432226c39e21d23c3053f39bdf7f935678ff2a10cc0240db8f32eb07f5d8d7133ff5
+  data.tar.gz: 7b19c8922f563d1a51b599f6379a92d289a19c43b5580282a0cd348561cb1f8f0786e245e0490fbe3ad5cf31c462f49e37cf37cc9996f91c003e0721d80c6e55

data/CHANGELOG.md

@@ -1,5 +1,47 @@
 ## [Unreleased]
 
+## [0.12.0] - 2026-10-19
+
+### Breaking
+
+- **Timeouts and failed connections now raise `XeroKiwi::ConnectionError`.** They used to escape as `Faraday::TimeoutError`, `Faraday::ConnectionFailed` or `Faraday::SSLError`. None of these is a `XeroKiwi::Error`, so `rescue XeroKiwi::Error` missed them. All three are now wrapped in `XeroKiwi::ConnectionError < XeroKiwi::Error`, with the original as `cause`. The client's retry middleware still sees and retries Faraday's own errors; the wrap only happens once it gives up.
+
+  Upgrading: a `rescue` of any of those three Faraday errors around a kiwi call no longer matches. Rescue `XeroKiwi::ConnectionError`, and read `e.cause` if you need to tell them apart.
+
+  `XeroKiwi::OAuth::IDToken.verify` without `jwks:` is unchanged: it still raises `IDTokenError` for any failure to fetch the JWKS.
+
+### Changed
+
+- **Every HTTP call now has a timeout.** There were none, so each call used Net::HTTP's defaults of 60 seconds to connect, 60 to read and 60 to write. A consumer runs the code exchange and the ID token check inside a web request, and retries the exchange 3 times, so a slow identity.xero.com held a server thread for minutes. The defaults are now:
+
+  | Host | Used by | Connect | Read | Write |
+  |------|---------|---------|------|-------|
+  | identity.xero.com | `OAuth`, `TokenRefresher`, `IDToken.verify` | 5s | 10s | 10s |
+  | api.xero.com | `Client` | 5s | 60s | 10s |
+
+  The API read stays at 60 seconds because a page of 1,000 invoices can be slow. The client retries a timeout up to 4 times, so one hung API request can still take more than 5 minutes to fail. Lower `timeout:` and `retry_options: { max: ... }` together where that matters.
+
+  `IDToken.verify` without `jwks:` also stops Net::HTTP retrying a timed-out JWKS fetch, which doubled its wait.
+
+### Added
+
+- **`open_timeout:`, `timeout:` and `write_timeout:`**, in seconds, on `XeroKiwi::OAuth.new`, `XeroKiwi::TokenRefresher.new`, `XeroKiwi::OAuth::IDToken.verify` and `XeroKiwi::Client.new`. `timeout:` is the read timeout, under the name Faraday gives it. The refresh and revoke calls a `Client` makes use the identity defaults, not the client's own values.
+
+### Documentation
+
+- The errors doc said everything kiwi raises is a `XeroKiwi::Error`. One Faraday error still escapes: `Faraday::ParsingError`, when a response says it is JSON but does not parse. The doc now says so.
+
+## [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/client.md

@@ -44,6 +44,9 @@ you. See [Tokens](tokens.md) for the full refresh story.
 | `throttle:` | Limiter | No | `XeroKiwi.default_throttle`, else none | Proactive per-tenant rate limiting. See [Throttling](throttling.md). |
 | `page_size:` | `Integer` | No | `nil` (Xero's own default of 100) | Default `pageSize` for every list call. Per-call `page_size:` overrides it. See [Querying](querying.md). |
 | `retain_raw:` | `Boolean` | No | `false` | Keep Xero's untouched response hash on each resource, readable via `#raw`. See below. |
+| `open_timeout:` | `Numeric` | No | `5` | Seconds to wait for a connection to api.xero.com. See [Timeouts](#timeouts). |
+| `timeout:` | `Numeric` | No | `60` | Seconds to wait for each read of the response. Longer than the identity default, because a page of 1,000 invoices can be slow. |
+| `write_timeout:` | `Numeric` | No | `10` | Seconds to wait for each write of the request. |
 
 ### `retain_raw:` and `#raw`
 
@@ -371,6 +374,35 @@ client = XeroKiwi::Client.new(
 See [retries and rate limits](retries-and-rate-limits.md) for the full
 configuration reference and which keys you can override.
 
+## Timeouts
+
+A request that hits `open_timeout:`, `timeout:` or `write_timeout:` is
+retried like any other transport failure. Once the retries are exhausted, the
+client raises `XeroKiwi::ConnectionError`, with the last
+`Faraday::TimeoutError` or `Faraday::ConnectionFailed` as its `cause`. A
+failed TLS handshake is not retried: it raises `XeroKiwi::ConnectionError` at
+once, with `Faraday::SSLError` as its `cause`.
+
+```ruby
+client = XeroKiwi::Client.new(
+  access_token: "...",
+  open_timeout: 2,
+  timeout:      30
+)
+```
+
+**Retries multiply the wait.** With the default `max: 4`, one hung request
+can wait for 5 reads of 60 seconds, plus the backoff between them: more than
+5 minutes. Where that matters, such as inside a web request, lower `timeout:`
+and `retry_options: { max: ... }` together.
+
+`timeout:` applies to each read from the socket, not to the whole request, so
+a response that keeps arriving slowly can take longer in total.
+
+**Refresh and revoke use the identity timeouts.** Those calls go to
+identity.xero.com, so the client's own values do not apply to them. See
+[Tokens](tokens.md#timeouts).
+
 ## Thread safety
 
 A single client can safely be shared across threads. The internals are

data/docs/errors.md

@@ -16,6 +16,7 @@ StandardError
    │  ├─ XeroKiwi::ClientError           (other 4xx)
    │  ├─ XeroKiwi::ServerError           (5xx)
    │  └─ XeroKiwi::RateLimitError        (429, with retry_after + problem)
+   ├─ XeroKiwi::ConnectionError          (timeout or failed connection)
    ├─ XeroKiwi::OAuth::StateMismatchError  (CSRF check failed)
    └─ XeroKiwi::OAuth::IDTokenError        (ID token JWT verification failed)
 ```
@@ -23,12 +24,16 @@ StandardError
 A few things worth noticing about the shape:
 
 - **Everything Xero Kiwi raises** descends from `XeroKiwi::Error`. If you only want
-  one rescue clause for "the Xero integration broke," catch this.
+  one rescue clause for "the Xero integration broke," catch this. The one
+  exception is a response that says it is JSON but does not parse, which
+  raises Faraday's own `Faraday::ParsingError`.
 - **HTTP responses** descend from `XeroKiwi::APIError`, which carries `status`
   and `body` attributes you can inspect.
 - **OAuth-specific errors** for state mismatch and ID token verification
   descend from `XeroKiwi::Error` directly (not `APIError`) because they don't
   come from an HTTP response — they're local validation failures.
+- **`XeroKiwi::ConnectionError`** descends from `XeroKiwi::Error` directly
+  too. No response arrived, so there is no status or body to carry.
 - **`XeroKiwi::TokenRefreshError`** and **`XeroKiwi::OAuth::CodeExchangeError`** are
   both `AuthenticationError` subclasses, because the practical recovery is
   the same as for any 401: the user needs to re-authorise.
@@ -136,6 +141,30 @@ Extra attributes beyond `APIError`:
 Sidekiq job can re-enqueue itself with that delay rather than hammering
 Xero.
 
+### `XeroKiwi::ConnectionError`
+
+Raised when a request hits its `open_timeout:`, `timeout:` or
+`write_timeout:`, or when the connection fails (refused, reset, the host
+does not resolve, or the TLS handshake fails). `XeroKiwi::Client` raises it
+only after its retries are exhausted, except for a TLS failure, which it
+does not retry. Identity calls (code exchange, client credentials, refresh,
+revoke and the JWKS fetch) are not retried.
+
+The original `Faraday::TimeoutError`, `Faraday::ConnectionFailed` or
+`Faraday::SSLError` is the error's `cause`:
+
+```ruby
+rescue XeroKiwi::ConnectionError => e
+  e.cause # => #<Faraday::TimeoutError: Net::ReadTimeout ...>
+```
+
+`XeroKiwi::OAuth::IDToken.verify` without `jwks:` is the one exception: it
+raises `XeroKiwi::OAuth::IDTokenError` for any failure to fetch the JWKS,
+timeouts included.
+
+See [Client — Timeouts](client.md#timeouts) and [OAuth — Timeouts](oauth.md#timeouts)
+for the limits and their defaults.
+
 ### `XeroKiwi::OAuth::StateMismatchError`
 
 Raised by `XeroKiwi::OAuth.verify_state!` when the `state` parameter Xero
@@ -156,7 +185,9 @@ the ID token JWT can't be verified. Causes:
 - Wrong audience.
 - Token expired.
 - Nonce mismatch (when nonce verification was requested).
-- Network failure fetching JWKS.
+- Network failure fetching JWKS, through `IDToken.verify` without `jwks:`.
+  Through `oauth.verify_id_token`, a network failure raises
+  `XeroKiwi::ConnectionError` instead.
 
 The error message has a brief description of which check failed (e.g.
 `"ID token verification failed: Signature verification failed"`,
@@ -223,10 +254,12 @@ rescue XeroKiwi::OAuth::CodeExchangeError
   redirect_to root_path, alert: "Could not complete Xero authorisation"
 rescue XeroKiwi::OAuth::IDTokenError
   redirect_to root_path, alert: "Could not verify Xero identity"
+rescue XeroKiwi::ConnectionError
+  redirect_to root_path, alert: "Xero did not respond. Please try again."
 end
 ```
 
-Three separate rescue clauses give you three different user-facing
+Four separate rescue clauses give you four different user-facing
 messages, which is usually what you want for an OAuth callback — different
 failures imply different user actions.
 

data/docs/oauth.md

@@ -40,6 +40,9 @@ oauth = XeroKiwi::OAuth.new(
 | `client_secret:` | `String` | Yes | — | Your Xero app's client secret |
 | `redirect_uri:` | `String` | Conditional | `nil` | Required for `authorization_url` and `exchange_code`. **Optional** if you only use this instance for `revoke_token` or `verify_id_token`. |
 | `adapter:` | Faraday adapter | No | `Faraday.default_adapter` | The HTTP adapter for token-endpoint and JWKS calls |
+| `open_timeout:` | `Numeric` | No | `5` | Seconds to wait for a connection to identity.xero.com. See [Timeouts](#timeouts). |
+| `timeout:` | `Numeric` | No | `10` | Seconds to wait for each read of the response. |
+| `write_timeout:` | `Numeric` | No | `10` | Seconds to wait for each write of the request. |
 
 ### Why `redirect_uri:` is optional
 
@@ -58,6 +61,32 @@ fake redirect URL. Pass `redirect_uri: nil` (or just omit it). If you then
 *do* call `authorization_url` or `exchange_code`, you'll get a clear
 `ArgumentError` at call time rather than a confusing 400 from Xero.
 
+### Timeouts
+
+Every call the instance makes — `exchange_code`, `client_credentials_token`,
+`revoke_token` and the JWKS fetch behind `verify_id_token` — gives up after
+these limits and raises `XeroKiwi::ConnectionError`. Faraday's
+`Faraday::TimeoutError` or `Faraday::ConnectionFailed` is its `cause`.
+
+Without them, each call would use Net::HTTP's defaults of 60 seconds to
+connect, 60 to read and 60 to write. The code exchange and the ID token check
+usually run inside a web request, so a slow identity.xero.com would hold that
+request, and its server thread, for a minute or more.
+
+```ruby
+oauth = XeroKiwi::OAuth.new(
+  client_id:     ENV.fetch("XERO_CLIENT_ID"),
+  client_secret: ENV.fetch("XERO_CLIENT_SECRET"),
+  redirect_uri:  "https://app.example.com/xero/callback",
+  open_timeout:  2,
+  timeout:       5
+)
+```
+
+Identity calls are not retried, so the limits are close to the whole wait.
+`timeout:` applies to each read from the socket, so a response that keeps
+arriving slowly can take longer in total.
+
 ## Step 1: building the authorisation URL
 
 ```ruby
@@ -263,7 +292,7 @@ id_token, and scope. See [Tokens](tokens.md) for the full reference.
 | Wrong `redirect_uri` (must match the one used at authorise time) | `XeroKiwi::OAuth::CodeExchangeError` |
 | PKCE verifier mismatch | `XeroKiwi::OAuth::CodeExchangeError` |
 | Wrong client credentials | `XeroKiwi::OAuth::CodeExchangeError` |
-| Network error | bubbles up as a `Faraday::ConnectionFailed` |
+| Timeout, or no connection to Xero | `XeroKiwi::ConnectionError`, with Faraday's error as its `cause` |
 
 `XeroKiwi::OAuth::CodeExchangeError` inherits from `XeroKiwi::AuthenticationError`,
 so you can catch the broader class if you don't care about the distinction.
@@ -312,6 +341,15 @@ The standalone class method **fetches JWKS fresh on every call** via
 `Net::HTTP`. Fine for one-off use, wasteful in a hot loop. If you find
 yourself calling it repeatedly, switch to the OAuth instance method.
 
+It takes the same `open_timeout:`, `timeout:` and `write_timeout:` options
+as `OAuth.new`, with the same defaults. Unlike the instance method, it raises
+`XeroKiwi::OAuth::IDTokenError` when the fetch times out, as it does for any
+other failure to fetch the JWKS.
+
+```ruby
+XeroKiwi::OAuth::IDToken.verify(id_token, client_id: "...", timeout: 5)
+```
+
 You can also inject your own JWKS provider:
 
 ```ruby
@@ -443,6 +481,7 @@ auto-refresh paths stay out of the way.
 |-------|-----------|
 | Wrong `client_id` / `client_secret` | `XeroKiwi::OAuth::ClientCredentialsError` |
 | Scope the app isn't authorised for | `XeroKiwi::OAuth::ClientCredentialsError` |
+| Timeout, or no connection to Xero | `XeroKiwi::ConnectionError`, with Faraday's error as its `cause` |
 
 `ClientCredentialsError` subclasses `XeroKiwi::AuthenticationError`, so an
 existing `rescue XeroKiwi::AuthenticationError` still catches it. There is

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/docs/retries-and-rate-limits.md

@@ -175,10 +175,12 @@ code, catch `XeroKiwi::ServerError` and handle it explicitly.
 |----------|-----------------|
 | All retries returned 429 | `XeroKiwi::RateLimitError` (with `retry_after` and `problem` attributes) |
 | All retries returned 502/503/504 | `XeroKiwi::ServerError` |
-| All retries failed at the transport level | The underlying `Faraday::ConnectionFailed` / `Faraday::TimeoutError` |
+| All retries failed at the transport level | `XeroKiwi::ConnectionError`, with the last `Faraday::ConnectionFailed` / `Faraday::TimeoutError` as its `cause` |
 
 The retried request count includes the original attempt, so `max: 4` means
-**up to 5 total HTTP requests** before giving up.
+**up to 5 total HTTP requests** before giving up. Each of them can wait the
+full read timeout, so a hung endpoint takes up to 5 times as long to fail.
+See [Client — Timeouts](client.md#timeouts).
 
 ## Customising the retry policy
 

data/docs/tokens.md

@@ -145,6 +145,34 @@ else
 end
 ```
 
+### Timeouts
+
+A refresh goes to identity.xero.com, not api.xero.com, so it uses the
+identity timeouts: 5 seconds to connect, 10 to read and 10 to write. The
+client's own `timeout:` does not apply to it. When identity.xero.com does not
+answer in time, the refresh raises `XeroKiwi::ConnectionError` rather than
+holding the thread for Net::HTTP's default of 60 seconds.
+
+`XeroKiwi::TokenRefresher` takes the same options as `XeroKiwi::OAuth.new`
+if you use it directly:
+
+```ruby
+refresher = XeroKiwi::TokenRefresher.new(
+  client_id:     ENV.fetch("XERO_CLIENT_ID"),
+  client_secret: ENV.fetch("XERO_CLIENT_SECRET"),
+  open_timeout:  2,
+  timeout:       5
+)
+
+refresher.refresh(refresh_token: stored_refresh_token)
+```
+
+| Option | Default | Purpose |
+|--------|---------|---------|
+| `open_timeout:` | `5` | Seconds to wait for a connection. |
+| `timeout:` | `10` | Seconds to wait for each read of the response. |
+| `write_timeout:` | `10` | Seconds to wait for each write of the request. |
+
 ## The `on_token_refresh` callback
 
 This is the most important integration point in the gem. Every time the
@@ -275,7 +303,9 @@ This:
    current refresh token.
 2. Returns `true` on success.
 3. Raises `XeroKiwi::TokenRefreshError` if the client has no refresh capability,
-   or `XeroKiwi::AuthenticationError` if Xero rejects the revoke.
+   `XeroKiwi::AuthenticationError` if Xero rejects the revoke, or
+   `XeroKiwi::ConnectionError` if identity.xero.com does not answer within the
+   [identity timeouts](#timeouts).
 
 After revocation, **treat the client as dead.** Subsequent API calls will
 401, and reactive refresh will fail because the refresh token is gone too.

data/lib/xero_kiwi/client.rb

@@ -52,6 +52,10 @@ module XeroKiwi
       ]
     }.freeze
 
+    DEFAULT_OPEN_TIMEOUT  = 5
+    DEFAULT_READ_TIMEOUT  = 60
+    DEFAULT_WRITE_TIMEOUT = 10
+
     attr_reader :token
 
     def initialize(
@@ -66,7 +70,10 @@ module XeroKiwi
       retry_options: {},
       throttle: nil,
       page_size: nil,
-      retain_raw: false
+      retain_raw: false,
+      open_timeout: DEFAULT_OPEN_TIMEOUT,
+      timeout: DEFAULT_READ_TIMEOUT,
+      write_timeout: DEFAULT_WRITE_TIMEOUT
     )
       @token            = Token.new(access_token: access_token, refresh_token: refresh_token, expires_at: expires_at)
       @client_id        = client_id
@@ -75,6 +82,7 @@ module XeroKiwi
       @adapter          = adapter
       @user_agent       = user_agent
       @retry_options    = DEFAULT_RETRY_OPTIONS.merge(retry_options)
+      @timeouts         = { open_timeout: open_timeout, timeout: timeout, write_timeout: write_timeout }
       @throttle         = throttle || XeroKiwi.default_throttle || Throttle::NullLimiter.new
       @page_size        = page_size
       @retain_raw       = retain_raw
@@ -617,7 +625,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 +638,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
@@ -877,8 +890,9 @@ module XeroKiwi
     # Middleware order matters. Outbound runs top-to-bottom; inbound runs in
     # reverse. We want:
     #
-    #   1. ResponseHandler (outermost) — converts the FINAL response status into
-    #      a XeroKiwi exception, *after* retries have been exhausted.
+    #   1. ResponseHandler (outermost) — converts the FINAL response status, or
+    #      the final transport failure, into a XeroKiwi exception, *after*
+    #      retries have been exhausted.
     #   2. Retry — retries on 429/503 (respecting Retry-After) and on transport
     #      exceptions.
     #   3. RateLimitCapture — records Xero's quota headers. Below Retry so
@@ -894,7 +908,7 @@ module XeroKiwi
     # gets retried by Faraday before we ever raise RateLimitError, and the
     # exception only fires once we've truly given up.
     def build_http
-      Faraday.new(url: BASE_URL) do |f|
+      Faraday.new(url: BASE_URL, request: @timeouts) do |f|
         f.use ResponseHandler
         f.request :retry, @retry_options
         f.use RateLimitCapture, @rate_limits
@@ -980,10 +994,17 @@ module XeroKiwi
       end
     end
 
-    # Faraday middleware that maps non-2xx responses onto our exception
-    # hierarchy. Lives outside the retry middleware so it only fires on the
-    # final response.
+    # Faraday middleware that maps non-2xx responses and transport failures
+    # onto our exception hierarchy. Lives outside the retry middleware so it
+    # only fires on the final response, and so the retry middleware still
+    # sees Faraday's own errors.
     class ResponseHandler < Faraday::Middleware
+      def call(env)
+        super
+      rescue Faraday::TimeoutError, Faraday::ConnectionFailed, Faraday::SSLError => e
+        raise ConnectionError, "Request to #{env.url.host} failed: #{e.message}"
+      end
+
       def on_complete(env)
         # 304 Not Modified is a valid response to a conditional GET
         # (If-Modified-Since). Let it through so the list helper can

data/lib/xero_kiwi/errors.rb

@@ -16,6 +16,7 @@ module XeroKiwi
   class AuthenticationError < APIError; end
   class ClientError < APIError; end
   class ServerError < APIError; end
+  class ConnectionError < Error; end
 
   # Raised when refreshing the OAuth2 token fails — typically because the
   # refresh token has expired (60 days) or has already been rotated. Callers

data/lib/xero_kiwi/identity.rb

@@ -17,15 +17,26 @@ module XeroKiwi
     JWKS_PATH        = "/.well-known/openid-configuration/jwks"
     JWKS_URL         = "#{URL}#{JWKS_PATH}".freeze
 
+    DEFAULT_OPEN_TIMEOUT  = 5
+    DEFAULT_READ_TIMEOUT  = 10
+    DEFAULT_WRITE_TIMEOUT = 10
+
     module_function
 
     # Builds a Faraday connection configured for the Xero identity host:
-    # JSON response parsing and our exception mapping. No retry middleware
-    # — token endpoints aren't subject to the same rate limits as the API,
-    # and retrying a failed token call usually masks a real configuration
-    # problem instead of fixing a transient one.
-    def build_http(adapter: nil)
-      Faraday.new(url: URL) do |f|
+    # timeouts, JSON response parsing and our exception mapping. No retry
+    # middleware — token endpoints aren't subject to the same rate limits as
+    # the API, and retrying a failed token call usually masks a real
+    # configuration problem instead of fixing a transient one.
+    def build_http(
+      adapter: nil,
+      open_timeout: DEFAULT_OPEN_TIMEOUT,
+      timeout: DEFAULT_READ_TIMEOUT,
+      write_timeout: DEFAULT_WRITE_TIMEOUT
+    )
+      request = { open_timeout: open_timeout, timeout: timeout, write_timeout: write_timeout }
+
+      Faraday.new(url: URL, request: request) do |f|
         f.use Client::ResponseHandler
         f.response :json, content_type: /\bjson/
         f.adapter(adapter || Faraday.default_adapter)

data/lib/xero_kiwi/oauth/id_token.rb

@@ -34,20 +34,29 @@ module XeroKiwi
 
       attr_reader :claims
 
-      def self.verify(id_token, client_id:, nonce: nil, jwks: nil)
+      def self.verify(
+        id_token,
+        client_id:,
+        nonce: nil,
+        jwks: nil,
+        open_timeout: Identity::DEFAULT_OPEN_TIMEOUT,
+        timeout: Identity::DEFAULT_READ_TIMEOUT,
+        write_timeout: Identity::DEFAULT_WRITE_TIMEOUT
+      )
         raise ArgumentError, "id_token is required"  if id_token.nil?  || id_token.empty?
         raise ArgumentError, "client_id is required" if client_id.nil? || client_id.empty?
 
-        decoded = decode(id_token, client_id, jwks)
-        claims  = decoded.first
+        timeouts = { open_timeout: open_timeout, timeout: timeout, write_timeout: write_timeout }
+        decoded  = decode(id_token, client_id: client_id, jwks: jwks, timeouts: timeouts)
+        claims   = decoded.first
         verify_nonce!(claims, nonce) if nonce
         new(claims)
       rescue JWT::DecodeError => e
         raise IDTokenError, "ID token verification failed: #{e.message}"
       end
 
-      def self.decode(id_token, client_id, jwks)
-        jwks_proc = jwks || method(:fetch_jwks_directly)
+      def self.decode(id_token, client_id:, jwks:, timeouts:)
+        jwks_proc = jwks || -> { fetch_jwks_directly(**timeouts) }
         JWT.decode(
           id_token,
           nil,
@@ -66,8 +75,18 @@ module XeroKiwi
       # injected. Net::HTTP keeps this dependency-free at the call site;
       # OAuth#verify_id_token uses an instance-cached Faraday fetcher
       # instead.
-      def self.fetch_jwks_directly
-        body = Net::HTTP.get(URI(Identity::JWKS_URL))
+      def self.fetch_jwks_directly(open_timeout:, timeout:, write_timeout:)
+        uri     = URI(Identity::JWKS_URL)
+        options = {
+          use_ssl:       uri.scheme == "https",
+          open_timeout:  open_timeout,
+          read_timeout:  timeout,
+          write_timeout: write_timeout,
+          # Net::HTTP retries a timed-out GET once, which doubles the wait.
+          max_retries:   0
+        }
+
+        body = Net::HTTP.start(uri.host, uri.port, **options) { |http| http.get(uri.request_uri).body }
         JSON.parse(body).fetch("keys")
       rescue StandardError => e
         raise IDTokenError, "failed to fetch JWKS: #{e.message}"

data/lib/xero_kiwi/oauth.rb

@@ -101,11 +101,20 @@ module XeroKiwi
     # (`authorization_url` and `exchange_code`) but not for `revoke_token`
     # or `verify_id_token`. It's optional at construction time so callers
     # who only need the latter operations don't have to invent a fake URL.
-    def initialize(client_id:, client_secret:, redirect_uri: nil, adapter: nil)
+    def initialize(
+      client_id:,
+      client_secret:,
+      redirect_uri: nil,
+      adapter: nil,
+      open_timeout: Identity::DEFAULT_OPEN_TIMEOUT,
+      timeout: Identity::DEFAULT_READ_TIMEOUT,
+      write_timeout: Identity::DEFAULT_WRITE_TIMEOUT
+    )
       @client_id       = client_id
       @client_secret   = client_secret
       @redirect_uri    = redirect_uri
       @adapter         = adapter
+      @timeouts        = { open_timeout: open_timeout, timeout: timeout, write_timeout: write_timeout }
       @jwks_mutex      = Mutex.new
       @jwks_cache      = nil
       @jwks_fetched_at = nil
@@ -281,7 +290,7 @@ module XeroKiwi
     end
 
     def http
-      @_http ||= Identity.build_http(adapter: @adapter)
+      @_http ||= Identity.build_http(adapter: @adapter, **@timeouts)
     end
   end
 end

data/lib/xero_kiwi/token_refresher.rb

@@ -13,10 +13,18 @@ module XeroKiwi
   #
   # See: https://developer.xero.com/documentation/guides/oauth2/auth-flow#refreshing-access-and-refresh-tokens
   class TokenRefresher
-    def initialize(client_id:, client_secret:, adapter: nil)
+    def initialize(
+      client_id:,
+      client_secret:,
+      adapter: nil,
+      open_timeout: Identity::DEFAULT_OPEN_TIMEOUT,
+      timeout: Identity::DEFAULT_READ_TIMEOUT,
+      write_timeout: Identity::DEFAULT_WRITE_TIMEOUT
+    )
       @client_id     = client_id
       @client_secret = client_secret
       @adapter       = adapter
+      @timeouts      = { open_timeout: open_timeout, timeout: timeout, write_timeout: write_timeout }
     end
 
     # Performs the refresh round-trip and returns a fresh XeroKiwi::Token. Raises
@@ -47,7 +55,7 @@ module XeroKiwi
     end
 
     def http
-      @_http ||= Identity.build_http(adapter: @adapter)
+      @_http ||= Identity.build_http(adapter: @adapter, **@timeouts)
     end
   end
 end

data/lib/xero_kiwi/version.rb

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

data/llms-full.txt

@@ -413,6 +413,9 @@ you. See [Tokens](tokens.md) for the full refresh story.
 | `throttle:` | Limiter | No | `XeroKiwi.default_throttle`, else none | Proactive per-tenant rate limiting. See [Throttling](throttling.md). |
 | `page_size:` | `Integer` | No | `nil` (Xero's own default of 100) | Default `pageSize` for every list call. Per-call `page_size:` overrides it. See [Querying](querying.md). |
 | `retain_raw:` | `Boolean` | No | `false` | Keep Xero's untouched response hash on each resource, readable via `#raw`. See below. |
+| `open_timeout:` | `Numeric` | No | `5` | Seconds to wait for a connection to api.xero.com. See [Timeouts](#timeouts). |
+| `timeout:` | `Numeric` | No | `60` | Seconds to wait for each read of the response. Longer than the identity default, because a page of 1,000 invoices can be slow. |
+| `write_timeout:` | `Numeric` | No | `10` | Seconds to wait for each write of the request. |
 
 ### `retain_raw:` and `#raw`
 
@@ -740,6 +743,35 @@ client = XeroKiwi::Client.new(
 See [retries and rate limits](retries-and-rate-limits.md) for the full
 configuration reference and which keys you can override.
 
+## Timeouts
+
+A request that hits `open_timeout:`, `timeout:` or `write_timeout:` is
+retried like any other transport failure. Once the retries are exhausted, the
+client raises `XeroKiwi::ConnectionError`, with the last
+`Faraday::TimeoutError` or `Faraday::ConnectionFailed` as its `cause`. A
+failed TLS handshake is not retried: it raises `XeroKiwi::ConnectionError` at
+once, with `Faraday::SSLError` as its `cause`.
+
+```ruby
+client = XeroKiwi::Client.new(
+  access_token: "...",
+  open_timeout: 2,
+  timeout:      30
+)
+```
+
+**Retries multiply the wait.** With the default `max: 4`, one hung request
+can wait for 5 reads of 60 seconds, plus the backoff between them: more than
+5 minutes. Where that matters, such as inside a web request, lower `timeout:`
+and `retry_options: { max: ... }` together.
+
+`timeout:` applies to each read from the socket, not to the whole request, so
+a response that keeps arriving slowly can take longer in total.
+
+**Refresh and revoke use the identity timeouts.** Those calls go to
+identity.xero.com, so the client's own values do not apply to them. See
+[Tokens](tokens.md#timeouts).
+
 ## Thread safety
 
 A single client can safely be shared across threads. The internals are
@@ -821,6 +853,9 @@ oauth = XeroKiwi::OAuth.new(
 | `client_secret:` | `String` | Yes | — | Your Xero app's client secret |
 | `redirect_uri:` | `String` | Conditional | `nil` | Required for `authorization_url` and `exchange_code`. **Optional** if you only use this instance for `revoke_token` or `verify_id_token`. |
 | `adapter:` | Faraday adapter | No | `Faraday.default_adapter` | The HTTP adapter for token-endpoint and JWKS calls |
+| `open_timeout:` | `Numeric` | No | `5` | Seconds to wait for a connection to identity.xero.com. See [Timeouts](#timeouts). |
+| `timeout:` | `Numeric` | No | `10` | Seconds to wait for each read of the response. |
+| `write_timeout:` | `Numeric` | No | `10` | Seconds to wait for each write of the request. |
 
 ### Why `redirect_uri:` is optional
 
@@ -839,6 +874,32 @@ fake redirect URL. Pass `redirect_uri: nil` (or just omit it). If you then
 *do* call `authorization_url` or `exchange_code`, you'll get a clear
 `ArgumentError` at call time rather than a confusing 400 from Xero.
 
+### Timeouts
+
+Every call the instance makes — `exchange_code`, `client_credentials_token`,
+`revoke_token` and the JWKS fetch behind `verify_id_token` — gives up after
+these limits and raises `XeroKiwi::ConnectionError`. Faraday's
+`Faraday::TimeoutError` or `Faraday::ConnectionFailed` is its `cause`.
+
+Without them, each call would use Net::HTTP's defaults of 60 seconds to
+connect, 60 to read and 60 to write. The code exchange and the ID token check
+usually run inside a web request, so a slow identity.xero.com would hold that
+request, and its server thread, for a minute or more.
+
+```ruby
+oauth = XeroKiwi::OAuth.new(
+  client_id:     ENV.fetch("XERO_CLIENT_ID"),
+  client_secret: ENV.fetch("XERO_CLIENT_SECRET"),
+  redirect_uri:  "https://app.example.com/xero/callback",
+  open_timeout:  2,
+  timeout:       5
+)
+```
+
+Identity calls are not retried, so the limits are close to the whole wait.
+`timeout:` applies to each read from the socket, so a response that keeps
+arriving slowly can take longer in total.
+
 ## Step 1: building the authorisation URL
 
 ```ruby
@@ -1044,7 +1105,7 @@ id_token, and scope. See [Tokens](tokens.md) for the full reference.
 | Wrong `redirect_uri` (must match the one used at authorise time) | `XeroKiwi::OAuth::CodeExchangeError` |
 | PKCE verifier mismatch | `XeroKiwi::OAuth::CodeExchangeError` |
 | Wrong client credentials | `XeroKiwi::OAuth::CodeExchangeError` |
-| Network error | bubbles up as a `Faraday::ConnectionFailed` |
+| Timeout, or no connection to Xero | `XeroKiwi::ConnectionError`, with Faraday's error as its `cause` |
 
 `XeroKiwi::OAuth::CodeExchangeError` inherits from `XeroKiwi::AuthenticationError`,
 so you can catch the broader class if you don't care about the distinction.
@@ -1093,6 +1154,15 @@ The standalone class method **fetches JWKS fresh on every call** via
 `Net::HTTP`. Fine for one-off use, wasteful in a hot loop. If you find
 yourself calling it repeatedly, switch to the OAuth instance method.
 
+It takes the same `open_timeout:`, `timeout:` and `write_timeout:` options
+as `OAuth.new`, with the same defaults. Unlike the instance method, it raises
+`XeroKiwi::OAuth::IDTokenError` when the fetch times out, as it does for any
+other failure to fetch the JWKS.
+
+```ruby
+XeroKiwi::OAuth::IDToken.verify(id_token, client_id: "...", timeout: 5)
+```
+
 You can also inject your own JWKS provider:
 
 ```ruby
@@ -1224,6 +1294,7 @@ auto-refresh paths stay out of the way.
 |-------|-----------|
 | Wrong `client_id` / `client_secret` | `XeroKiwi::OAuth::ClientCredentialsError` |
 | Scope the app isn't authorised for | `XeroKiwi::OAuth::ClientCredentialsError` |
+| Timeout, or no connection to Xero | `XeroKiwi::ConnectionError`, with Faraday's error as its `cause` |
 
 `ClientCredentialsError` subclasses `XeroKiwi::AuthenticationError`, so an
 existing `rescue XeroKiwi::AuthenticationError` still catches it. There is
@@ -1538,6 +1609,34 @@ else
 end
 ```
 
+### Timeouts
+
+A refresh goes to identity.xero.com, not api.xero.com, so it uses the
+identity timeouts: 5 seconds to connect, 10 to read and 10 to write. The
+client's own `timeout:` does not apply to it. When identity.xero.com does not
+answer in time, the refresh raises `XeroKiwi::ConnectionError` rather than
+holding the thread for Net::HTTP's default of 60 seconds.
+
+`XeroKiwi::TokenRefresher` takes the same options as `XeroKiwi::OAuth.new`
+if you use it directly:
+
+```ruby
+refresher = XeroKiwi::TokenRefresher.new(
+  client_id:     ENV.fetch("XERO_CLIENT_ID"),
+  client_secret: ENV.fetch("XERO_CLIENT_SECRET"),
+  open_timeout:  2,
+  timeout:       5
+)
+
+refresher.refresh(refresh_token: stored_refresh_token)
+```
+
+| Option | Default | Purpose |
+|--------|---------|---------|
+| `open_timeout:` | `5` | Seconds to wait for a connection. |
+| `timeout:` | `10` | Seconds to wait for each read of the response. |
+| `write_timeout:` | `10` | Seconds to wait for each write of the request. |
+
 ## The `on_token_refresh` callback
 
 This is the most important integration point in the gem. Every time the
@@ -1668,7 +1767,9 @@ This:
    current refresh token.
 2. Returns `true` on success.
 3. Raises `XeroKiwi::TokenRefreshError` if the client has no refresh capability,
-   or `XeroKiwi::AuthenticationError` if Xero rejects the revoke.
+   `XeroKiwi::AuthenticationError` if Xero rejects the revoke, or
+   `XeroKiwi::ConnectionError` if identity.xero.com does not answer within the
+   [identity timeouts](#timeouts).
 
 After revocation, **treat the client as dead.** Subsequent API calls will
 401, and reactive refresh will fail because the refresh token is gone too.
@@ -2158,14 +2259,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 +2282,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 +3655,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 +3745,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 +3764,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?)
 ```
 
 
@@ -3890,6 +4010,7 @@ StandardError
    │  ├─ XeroKiwi::ClientError           (other 4xx)
    │  ├─ XeroKiwi::ServerError           (5xx)
    │  └─ XeroKiwi::RateLimitError        (429, with retry_after + problem)
+   ├─ XeroKiwi::ConnectionError          (timeout or failed connection)
    ├─ XeroKiwi::OAuth::StateMismatchError  (CSRF check failed)
    └─ XeroKiwi::OAuth::IDTokenError        (ID token JWT verification failed)
 ```
@@ -3897,12 +4018,16 @@ StandardError
 A few things worth noticing about the shape:
 
 - **Everything Xero Kiwi raises** descends from `XeroKiwi::Error`. If you only want
-  one rescue clause for "the Xero integration broke," catch this.
+  one rescue clause for "the Xero integration broke," catch this. The one
+  exception is a response that says it is JSON but does not parse, which
+  raises Faraday's own `Faraday::ParsingError`.
 - **HTTP responses** descend from `XeroKiwi::APIError`, which carries `status`
   and `body` attributes you can inspect.
 - **OAuth-specific errors** for state mismatch and ID token verification
   descend from `XeroKiwi::Error` directly (not `APIError`) because they don't
   come from an HTTP response — they're local validation failures.
+- **`XeroKiwi::ConnectionError`** descends from `XeroKiwi::Error` directly
+  too. No response arrived, so there is no status or body to carry.
 - **`XeroKiwi::TokenRefreshError`** and **`XeroKiwi::OAuth::CodeExchangeError`** are
   both `AuthenticationError` subclasses, because the practical recovery is
   the same as for any 401: the user needs to re-authorise.
@@ -4010,6 +4135,30 @@ Extra attributes beyond `APIError`:
 Sidekiq job can re-enqueue itself with that delay rather than hammering
 Xero.
 
+### `XeroKiwi::ConnectionError`
+
+Raised when a request hits its `open_timeout:`, `timeout:` or
+`write_timeout:`, or when the connection fails (refused, reset, the host
+does not resolve, or the TLS handshake fails). `XeroKiwi::Client` raises it
+only after its retries are exhausted, except for a TLS failure, which it
+does not retry. Identity calls (code exchange, client credentials, refresh,
+revoke and the JWKS fetch) are not retried.
+
+The original `Faraday::TimeoutError`, `Faraday::ConnectionFailed` or
+`Faraday::SSLError` is the error's `cause`:
+
+```ruby
+rescue XeroKiwi::ConnectionError => e
+  e.cause # => #<Faraday::TimeoutError: Net::ReadTimeout ...>
+```
+
+`XeroKiwi::OAuth::IDToken.verify` without `jwks:` is the one exception: it
+raises `XeroKiwi::OAuth::IDTokenError` for any failure to fetch the JWKS,
+timeouts included.
+
+See [Client — Timeouts](client.md#timeouts) and [OAuth — Timeouts](oauth.md#timeouts)
+for the limits and their defaults.
+
 ### `XeroKiwi::OAuth::StateMismatchError`
 
 Raised by `XeroKiwi::OAuth.verify_state!` when the `state` parameter Xero
@@ -4030,7 +4179,9 @@ the ID token JWT can't be verified. Causes:
 - Wrong audience.
 - Token expired.
 - Nonce mismatch (when nonce verification was requested).
-- Network failure fetching JWKS.
+- Network failure fetching JWKS, through `IDToken.verify` without `jwks:`.
+  Through `oauth.verify_id_token`, a network failure raises
+  `XeroKiwi::ConnectionError` instead.
 
 The error message has a brief description of which check failed (e.g.
 `"ID token verification failed: Signature verification failed"`,
@@ -4097,10 +4248,12 @@ rescue XeroKiwi::OAuth::CodeExchangeError
   redirect_to root_path, alert: "Could not complete Xero authorisation"
 rescue XeroKiwi::OAuth::IDTokenError
   redirect_to root_path, alert: "Could not verify Xero identity"
+rescue XeroKiwi::ConnectionError
+  redirect_to root_path, alert: "Xero did not respond. Please try again."
 end
 ```
 
-Three separate rescue clauses give you three different user-facing
+Four separate rescue clauses give you four different user-facing
 messages, which is usually what you want for an OAuth callback — different
 failures imply different user actions.
 
@@ -4326,10 +4479,12 @@ code, catch `XeroKiwi::ServerError` and handle it explicitly.
 |----------|-----------------|
 | All retries returned 429 | `XeroKiwi::RateLimitError` (with `retry_after` and `problem` attributes) |
 | All retries returned 502/503/504 | `XeroKiwi::ServerError` |
-| All retries failed at the transport level | The underlying `Faraday::ConnectionFailed` / `Faraday::TimeoutError` |
+| All retries failed at the transport level | `XeroKiwi::ConnectionError`, with the last `Faraday::ConnectionFailed` / `Faraday::TimeoutError` as its `cause` |
 
 The retried request count includes the original attempt, so `max: 4` means
-**up to 5 total HTTP requests** before giving up.
+**up to 5 total HTTP requests** before giving up. Each of them can wait the
+full read timeout, so a hung endpoint takes up to 5 times as long to fail.
+See [Client — Timeouts](client.md#timeouts).
 
 ## Customising the retry policy
 

metadata

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